16 KiB
Magic-Link Invitation-Onboarding
Status: in_progress (skip-password feature shipped; MagicLinkToken-based pre-user-token redesign deferred — see deviations) Task-ID: #20 Phase: 01 Estimated Effort: 2 Tage Owner: claude (opus-4-7)
Problem
Der aktuelle Invitation-Flow funktioniert so:
- Admin lädt User per Email ein →
Invitation-Row in DB mit ID - User bekommt Email mit Link
https://<host>/invitation/<id> - User klickt → muss ein Konto erstellen (Email + Passwort) → wird dem Tenant zugewiesen
Probleme:
- Friction: User muss aktiv ein Passwort setzen, obwohl die Email-Adresse durch den Invitation-Link bereits "verified" ist
- Conversion-Loss: viele Invitations verlaufen im Sand weil User vergessen das Passwort zu setzen
- Sicherheits-Annahme: aktuell ist
<id>der einzige Token — wer den Link abfängt, kann das Konto übernehmen → schwache Sicherheit
Neuer Flow: Invitation-Mail enthält signierten Magic-Link-Token. Click → Konto wird automatisch aktiviert (oder Passwort-Setup als Bonus-Schritt) → User wird direkt in Tenant eingeloggt.
Bestehender /invitation/<id>-Route bleibt als Fallback funktionsfähig (für Fälle wo Magic-Link-Token nicht parst, z.B. URL-Manipulation in Email-Client).
Depends on
01-tech-debt-foundation/magic-link-reset.md(#19) —magic-link.server.tswird in #19 polyvalent gemacht (purpose-Param). Wir nutzenpurpose: 'invitation'. Wenn #19 nicht zuerst fertig ist → wir müssten den Refactor doppelt machen.01-tech-debt-foundation/password-policy.md(#27) — wenn User im Onboarding-Schritt optional ein Passwort setzt, muss die neue Policy greifen.
Blocks
- Keine internen Blocks innerhalb Phase 01.
- Phase 05 Marketing-Funnel und Phase 10 React-Email — bessere UX-Pfade können später aufbauen.
Approach
Erweiterter Invitation-Flow mit Magic-Link, ohne den alten Pfad zu brechen.
Schritte:
- Beim Erstellen einer Invitation wird zusätzlich zum existing
Invitation.idein Magic-Link-Token generiert (viagenerateMagicLinkToken({ purpose: 'invitation', metadata: { invitationId } })) - Email enthält Link
https://<host>/invitation/<id>?magic=<token> - Loader auf
/invitation/<id>:- Wenn
?magic=...Param vorhanden →verifyMagicLinkToken(token, 'invitation')aufrufen- Bei Valid: prüfe ob
metadata.invitationId === id. Wenn Match: Konto auto-aktivieren (oder Optional-Password-Setup-Step zeigen), Session erzeugen, User in Tenant einloggen, Redirect zu Tenant-Dashboard. - Bei Invalid (forged/expired/used): Fallback auf legacy-Pfad (Form für Passwort-Setup)
- Bei Valid: prüfe ob
- Wenn
?magic=...nicht vorhanden → existing Legacy-Pfad (Form für Konto-Erstellung)
- Wenn
UX-Entscheidung "auto-aktivieren ohne Passwort" vs "auto-Login + Passwort-Setup-Modal":
- Empfehlung: Auto-Login + Modal/Banner "Du kannst optional ein Passwort setzen für zukünftige Logins. Wenn du das nicht möchtest, nutze einfach Magic-Link beim nächsten Login."
- Passwort ist optional. User der nie Passwort setzt wird beim nächsten Login auf
/forgot-password→ Magic-Link-Pfad (#19) verwiesen.
Alternativen verworfen:
- Magic-Link ersetzt Invitation-Flow komplett (kein /invitation/ mehr) — Backwards-Compat-Risiko für ältere Emails die noch nicht abgerufen wurden.
- Token statt ID in URL — würde URL-Shape ändern, breaks Bookmarks.
Implementation Steps
-
Magic-Link-Service prüfen ist polyvalent
- Files:
apps/web/app/services/auth/magic-link.server.ts - Aktion: Verifizieren dass nach Task #19 der
purpose: 'invitation'undmetadata-Param unterstützt werden. Wenn nicht: erweitern. - Commit (falls Erweiterung nötig):
01/magic-link-invite: support invitation purpose in magic-link service
- Files:
-
Invitation-Creation um Magic-Link-Token erweitern
- Files: Pfad wo Invitations erstellt werden (z.B.
apps/web/app/modules/invitations/services/inviteUser.server.ts— Pfad recherchieren), Email-Trigger - Aktion:
- Bei Invitation-Create: zusätzlich
token = generateMagicLinkToken({ purpose: 'invitation', ttl: 7*24*60*60*1000, metadata: { invitationId } })(7 Tage TTL — Invitations sollten länger leben als Magic-Links für Password-Reset) - Token in Email-Template einbinden (Link:
${baseUrl}/invitation/${invitation.id}?magic=${token}) - Existing
Invitation-Row erhält keine neue Spalte (Token ist self-contained signiert)
- Bei Invitation-Create: zusätzlich
- Commit:
01/magic-link-invite: include magic-link token in invitation emails
- Files: Pfad wo Invitations erstellt werden (z.B.
-
Email-Template anpassen
- Files: bestehendes Invitation-Email-Template (DE + EN)
- Aktion:
- CTA-Button-URL ändert sich von
/invitation/<id>auf/invitation/<id>?magic=<token> - Body-Text: "Klicke auf den Button um deinem Konto beizutreten. Der Link funktioniert 7 Tage."
- Keine visible Token-Anzeige im Email-Body (nur im Link)
- CTA-Button-URL ändert sich von
- Commit:
01/magic-link-invite: update invitation email template
-
Loader auf
/invitation/$iderweitern- Files:
apps/web/app/routes/invitation.$id.tsx - Aktion:
- URL-Param
magicaus search-params lesen - Wenn vorhanden:
verifyMagicLinkToken(magic, 'invitation')- Bei valid +
metadata.invitationId === params.id:- Lade Invitation-Row aus DB
- Wenn
accepted: false: User erstellen (via existierender User-Create-Logik, ohne Passwort), Membership in Tenant erstellen, Invitation aufaccepted: truesetzen, Token als used markieren - Session erzeugen
- Optional-Password-Setup-Page anzeigen (Step 5) ODER direkt Redirect zu Tenant-Dashboard
- Bei invalid: Fallback auf Legacy-Form
- Bei valid +
- Wenn nicht vorhanden: existing Legacy-Form (kein Bruch)
- URL-Param
- Commit:
01/magic-link-invite: accept magic-link in invitation route
- Files:
-
Optional Password-Setup-Page
- Files:
apps/web/app/routes/auth/setup-password.tsx(neu, oder als Modal in Dashboard) - Aktion:
- Page mit Form: "Setze ein Passwort (optional, du kannst dich auch immer per Magic-Link einloggen)"
- Submit ruft
validatePassword(aus Task #27) und setzt Hash via argon2 (aus Task #28) - "Überspringen"-Button → Redirect zu Dashboard
- Banner im Dashboard wenn User kein Passwort hat: "Setze ein Passwort für schnellere Logins" mit Link zur Setup-Page
- Commit:
01/magic-link-invite: add optional password-setup page
- Files:
-
User-DB-Schema-Check
- Files:
prisma/schema.prisma(recherchieren), evtl. Migration - Aktion:
- Sicherstellen dass
User.passwordHashnullable ist (User ohne Passwort möglich) - Wenn nicht nullable: DB-Migration
passwordHashnullable machen - Bei Login-Pfad: wenn User kein Passwort hat und versucht via Form einzuloggen → freundlicher Hinweis "Bitte nutze Magic-Link" mit Redirect zu
/forgot-password
- Sicherstellen dass
- Commit (falls Migration nötig):
01/magic-link-invite: allow nullable password hash
- Files:
-
Audit-Log
- Files: existierender AuditEvent-Pfad
- Aktion: bei Invitation-Acceptance via Magic-Link →
invitation.accepted.magic-Event mit invitation-id, user-id, tenant-id. Bei Legacy-Pfad →invitation.accepted.form. Damit Operator den Anteil der Magic-Link-Conversions messen kann. - Commit:
01/magic-link-invite: audit-log invitation acceptance mode
-
Doku
- Files:
docs/auth/invitation-flow.md(neu) - Aktion: beide Pfade dokumentieren, Operator-Anleitung für Token-TTL-Anpassung, Anti-Abuse-Mechanismen.
- Commit:
01/magic-link-invite: document invitation flow
- Files:
Test Requirements
- Unit-Tests:
generateMagicLinkToken({purpose: 'invitation', metadata})undverifyMagicLinkTokenmit Metadata-Roundtrip- Invitation-Create generiert Token mit korrekter TTL und Metadata
- Integration-Tests:
- GET
/invitation/:id?magic=<valid>→ User wird erstellt, Membership erzeugt, Session aktiv - GET
/invitation/:id?magic=<valid>mitmetadata.invitationId != id→ 400 (Forge-Versuch) - GET
/invitation/:id?magic=<expired>→ Fallback auf Legacy-Form - GET
/invitation/:id?magic=<used>→ Fallback auf Legacy-Form - GET
/invitation/:idohne magic → Legacy-Form - User ohne Passwort kann sich später per Magic-Link erneut einloggen
- User ohne Passwort versucht Form-Login → freundlicher Hinweis
- GET
- E2E-Tests (Playwright):
- Admin invitet neuen User → Email in Mailpit → Click → User landet auf Dashboard (eingeloggt) → optional Password-Setup-Banner sichtbar
- User skipped Password-Setup → kann sich beim nächsten Login per Magic-Link erneut einloggen
- User setzt Passwort → kann sich danach auch per Email+Password einloggen
- Coverage-Target:
/invitation/$id.tsx: ≥ 90%setup-password.tsx: ≥ 85%
- Test-Files:
apps/web/app/routes/invitation.$id.test.ts(erweitert)apps/web/app/routes/auth/setup-password.test.ts(neu)
NICHT als completed markieren bevor E2E-Flow auf Staging grün ist (Invitation senden → Magic-Click → Dashboard).
Acceptance Criteria
- Invitation-Email enthält Magic-Link-Token (TTL 7 Tage)
- Click auf Magic-Link erstellt User + Membership + Session ohne Passwort-Eingabe
- Optional Password-Setup-Page existiert + nutzt Task #27 + #28 Policy/Hasher
- Legacy
/invitation/<id>-Form funktioniert weiter als Fallback User.passwordHashist nullable in DB- Login-Form-Versuch für Password-less User → freundlicher Redirect zu Magic-Link
- AuditEvents differenzieren
magicvsform-Pfad docs/auth/invitation-flow.mderstellt- Unit + Integration + E2E grün
pnpm lint,pnpm typecheck,pnpm testgrün- Detail-MD Progress-Log aktualisiert
- PROGRESS.md Status auf
completed
Rollback Strategy
8 atomic commits → einzeln revert-bar.
- Schritt 2-4 revert → Invitations werden wieder ohne Token verschickt; Loader ignoriert
?magic=...; Legacy-Pfad bleibt funktional. Kein Daten-Loss. - DB-Migration Rollback (Schritt 6): nur problematisch wenn User ohne Passwort bereits existieren — diese müssten dann Bulk-Password-Reset bekommen. Mitigation: Migration NICHT down-migrieren in Production wenn User-ohne-Passwort existieren.
- Notfall-Bypass: Env
AUTH_INVITATION_MAGIC_ENABLED=false(in Step 2 implementieren) → Invitations werden wieder mit Legacy-Link versendet; bestehende Magic-Links sind weiterhin verifizierbar (kein Bruch für in-flight Tokens).
Security Notes
- Token-Forge-Schutz:
metadata.invitationId === params.id-Check verhindert dass jemand mit einem gültigen Token für Invitation-A versucht auf Invitation-B zuzugreifen. KRITISCH. - TTL 7 Tage länger als Login-Magic-Link (15 Min) weil User-Onboarding-Decisions länger dauern. Trade-off: längere Token-Leak-Exposure. Mitigiert durch Single-Use.
- Single-Use: nach erfolgreicher Acceptance muss Token als used markiert sein. Re-Use → Token verworfen → Fallback.
- Email-Forwarding: User könnten die Invitation-Email forwarden. Der Forward-Empfänger könnte dann als der invited User landen. Mitigation: Email-Body sollte explizit "Wenn du diese Einladung nicht erwartet hast, ignoriere sie" enthalten. Kein Email-Address-Verify beim Magic-Click (wäre UX-Bruch).
- DB-Race: zwei parallele Klicks → erster commitet User-Create, zweiter rennt in Unique-Constraint-Error. Behandeln: Try-Catch + auf Duplicate-Email → einfach Session für existing User erzeugen wenn Magic-Token zur gleichen Invitation gehört.
- Password-less Accounts: User die nie ein Passwort setzen sind 100% Magic-Link-abhängig. Falls Magic-Link-Service ausfällt → User können sich nicht einloggen. Operator-Notiz: Magic-Link-Service ist hochkritisch, muss in Phase 02 Sentry-Wiring überwacht werden.
- Logging-Hygiene: Token-Wert niemals in Logs. AuditEvent enthält invitation-id, NICHT token.
Subagent Recommendations
- Planning: ein
Plan-Subagent für die UX-Entscheidung Password-Setup-Modal vs eigene Page (Empfehlung in Approach, aber Subagent kann mit existing Component-Library validieren). - Research:
general-purposefür: "Finde wo Invitations im Codebase erstellt und gesendet werden (Service+Email-Trigger). Finde Schema vonInvitationundUser. Prüfe obpasswordHashnullable ist." - Implementation:
general-purposefür Steps 1+2 (Service-Check + Invitation-Create-Erweiterung)general-purposefür Steps 3+4 (Email + Loader-Erweiterung)general-purposefür Steps 5+6 (Password-Setup-Page + DB-Migration)general-purposefür Steps 7+8 (Audit + Doku)
- Tests:
general-purposefür Test-Suite + E2E-Mailpit-Setup - Verification:
general-purposefür Acceptance-Criteria + Staging-E2E - Code-Review:
gsd-code-reviewernach Phase-Abschluss, speziell Security-Pfade + UX-Konsistenz
Staging-Deployment-Steps
- Branch
agent/01-magic-link-invitationpushen. - Coolify-Auto-Deploy.
- Smoke-Tests:
- Admin invitet
test-magic@example.com→ Mailpit checken → Email mit Magic-Link - Click → User landet eingeloggt auf Tenant-Dashboard → Password-Setup-Banner sichtbar
- Banner-Click → Setup-Page → Passwort setzen → erfolgreich
- Logout → Login per Email+Passwort → erfolgreich
- Zweiter Test-User: Invitation, Click, "Überspringen" beim Password-Setup, Logout, Login-Form-Versuch → Hinweis "Bitte Magic-Link nutzen"
/forgot-password→ Magic-Link → eingeloggt
- Admin invitet
- Audit-Log prüfen:
invitation.accepted.magic-Event vorhanden - Forge-Test: gültigen Magic-Link für Invitation-A nehmen,
params.idin URL manuell durch Invitation-B-ID ersetzen → 400-Error sichtbar - 48h Burn-In bevor Production-Cutover.
Deviations from Plan
- MagicLinkToken-Tabelle hat KEIN
purpose-Column auf staging (verified via\d "MagicLinkToken"). Plan ging davon aus dass nach #19 einpurpose: 'login' | 'invitation' | 'reset-alt'-Param in der Service-API und potenziell in der DB landet. Stattdessen blieb das Schema single-purpose (id, userId, tokenHash, expiresAt, consumedAt) und das "pre-user-token redesign" für Invitation-Onboarding wurde deferred (Status: "skip-password shipped"). Code-Pfad funktioniert weiter — nur die geplante Token-Differenzierung per DB-Field ist nicht implementiert.
Progress Log
- 2026-05-17 04:47 — staging-verify —
MagicLinkToken-Tabelle teilt dasselbe Schema wie für #19 dokumentiert.User.passwordHashist NOT NULL auf staging (Step 6 "passwordHash nullable" wurde nicht migriert, passt zur "skip-password shipped (pre-user-redesign deferred)"-Status). Code (skip-password-Form) im aktuellen37f23fa6...-Bundle vorhanden. Live-Invitation-E2E (Admin → invite → click magic → dashboard) bleibt für Operator (Email + browser-driven). - 2026-05-25 —
User.passwordHashnullable + Auth-Safeguard gelandet (HANDOFF-2026-05-25 Task A). Migrationprisma/migrations/20260525000000_01_user_password_hash_nullable/migration.sqldroptNOT NULLohne bestehende Hashes anzufassen.LegacyLoginUser.passwordHashist jetztstring | null;verifyPassword(plain, hash)akzeptiertstring | null | undefinedund gibt für leere/null-Hashes deterministisch{ valid: false }zurück.AuthService.loginFromRequest(web) prüft vor demverifyPassword-Call obuser.passwordHash === nullund antwortet dann mit{ error: "auth:errors.passwordlessAccountUseMagicLink", requiresMagicLink: true, magicLinkHref: "/forgot-password" }(Status 400) statt durch denDUMMY_PASSWORD_HASH-Fallthrough zu laufen.apps/api/src/routes/auth-routes.ts/v1/auth/login bekommt denselben Guard, antwortet aber generisch mitinvalid_credentialsdamit der API-Client keine Account-Existenz leakt. i18n-Keys in en+de ergänzt. Neuer Regressionstestapps/web/app/modules/users/services/AuthService.passwordless.test.tsasserts (a) keine Session-Erstellung, (b) keineverifyPassword-Aufrufe, (c)requiresMagicLink: true-Hint im Body. Lokaler typecheck + relevante Test-Suites grün. DB-Cutover auf staging (prisma migrate deploy) bleibt Operator-Action — Code ist abwärtskompatibel weil keine bestehende Row null-Hash hat.