# 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: 1. Admin lädt User per Email ein → `Invitation`-Row in DB mit ID 2. User bekommt Email mit Link `https:///invitation/` 3. 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 `` 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/`-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.ts` wird in #19 polyvalent gemacht (`purpose`-Param). Wir nutzen `purpose: '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: 1. Beim Erstellen einer Invitation wird zusätzlich zum existing `Invitation.id` ein **Magic-Link-Token** generiert (via `generateMagicLinkToken({ purpose: 'invitation', metadata: { invitationId } })`) 2. Email enthält Link `https:///invitation/?magic=` 3. Loader auf `/invitation/`: - 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) - Wenn `?magic=...` nicht vorhanden → existing Legacy-Pfad (Form für Konto-Erstellung) 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 1. **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'` und `metadata`-Param unterstützt werden. Wenn nicht: erweitern. - Commit (falls Erweiterung nötig): `01/magic-link-invite: support invitation purpose in magic-link service` 2. **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) - Commit: `01/magic-link-invite: include magic-link token in invitation emails` 3. **Email-Template anpassen** - Files: bestehendes Invitation-Email-Template (DE + EN) - Aktion: - CTA-Button-URL ändert sich von `/invitation/` auf `/invitation/?magic=` - 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) - Commit: `01/magic-link-invite: update invitation email template` 4. **Loader auf `/invitation/$id` erweitern** - Files: `apps/web/app/routes/invitation.$id.tsx` - Aktion: - URL-Param `magic` aus 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 auf `accepted: true` setzen, 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 - Wenn nicht vorhanden: existing Legacy-Form (kein Bruch) - Commit: `01/magic-link-invite: accept magic-link in invitation route` 5. **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` 6. **User-DB-Schema-Check** - Files: `prisma/schema.prisma` (recherchieren), evtl. Migration - Aktion: - Sicherstellen dass `User.passwordHash` nullable ist (User ohne Passwort möglich) - Wenn nicht nullable: DB-Migration `passwordHash` nullable 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` - Commit (falls Migration nötig): `01/magic-link-invite: allow nullable password hash` 7. **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` 8. **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` ## Test Requirements - **Unit-Tests:** - `generateMagicLinkToken({purpose: 'invitation', metadata})` und `verifyMagicLinkToken` mit Metadata-Roundtrip - Invitation-Create generiert Token mit korrekter TTL und Metadata - **Integration-Tests:** - GET `/invitation/:id?magic=` → User wird erstellt, Membership erzeugt, Session aktiv - GET `/invitation/:id?magic=` mit `metadata.invitationId != id` → 400 (Forge-Versuch) - GET `/invitation/:id?magic=` → Fallback auf Legacy-Form - GET `/invitation/:id?magic=` → Fallback auf Legacy-Form - GET `/invitation/:id` ohne magic → Legacy-Form - User ohne Passwort kann sich später per Magic-Link erneut einloggen - User ohne Passwort versucht Form-Login → freundlicher Hinweis - **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/`-Form funktioniert weiter als Fallback - [ ] `User.passwordHash` ist nullable in DB - [ ] Login-Form-Versuch für Password-less User → freundlicher Redirect zu Magic-Link - [ ] AuditEvents differenzieren `magic` vs `form`-Pfad - [ ] `docs/auth/invitation-flow.md` erstellt - [ ] Unit + Integration + E2E grün - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grü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-purpose` für: "Finde wo Invitations im Codebase erstellt und gesendet werden (Service+Email-Trigger). Finde Schema von `Invitation` und `User`. Prüfe ob `passwordHash` nullable ist." - **Implementation:** - `general-purpose` für Steps 1+2 (Service-Check + Invitation-Create-Erweiterung) - `general-purpose` für Steps 3+4 (Email + Loader-Erweiterung) - `general-purpose` für Steps 5+6 (Password-Setup-Page + DB-Migration) - `general-purpose` für Steps 7+8 (Audit + Doku) - **Tests:** `general-purpose` für Test-Suite + E2E-Mailpit-Setup - **Verification:** `general-purpose` für Acceptance-Criteria + Staging-E2E - **Code-Review:** `gsd-code-reviewer` nach Phase-Abschluss, speziell Security-Pfade + UX-Konsistenz ## Staging-Deployment-Steps 1. Branch `agent/01-magic-link-invitation` pushen. 2. Coolify-Auto-Deploy. 3. 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 4. Audit-Log prüfen: `invitation.accepted.magic`-Event vorhanden 5. Forge-Test: gültigen Magic-Link für Invitation-A nehmen, `params.id` in URL manuell durch Invitation-B-ID ersetzen → 400-Error sichtbar 6. 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 ein `purpose: '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.passwordHash` ist 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 aktuellen `37f23fa6...`-Bundle vorhanden. Live-Invitation-E2E (Admin → invite → click magic → dashboard) bleibt für Operator (Email + browser-driven). - 2026-05-25 — `User.passwordHash` nullable + Auth-Safeguard gelandet (HANDOFF-2026-05-25 Task A). Migration `prisma/migrations/20260525000000_01_user_password_hash_nullable/migration.sql` dropt `NOT NULL` ohne bestehende Hashes anzufassen. `LegacyLoginUser.passwordHash` ist jetzt `string | null`; `verifyPassword(plain, hash)` akzeptiert `string | null | undefined` und gibt für leere/null-Hashes deterministisch `{ valid: false }` zurück. `AuthService.loginFromRequest` (web) prüft vor dem `verifyPassword`-Call ob `user.passwordHash === null` und antwortet dann mit `{ error: "auth:errors.passwordlessAccountUseMagicLink", requiresMagicLink: true, magicLinkHref: "/forgot-password" }` (Status 400) statt durch den `DUMMY_PASSWORD_HASH`-Fallthrough zu laufen. `apps/api/src/routes/auth-routes.ts` /v1/auth/login bekommt denselben Guard, antwortet aber generisch mit `invalid_credentials` damit der API-Client keine Account-Existenz leakt. i18n-Keys in en+de ergänzt. Neuer Regressionstest `apps/web/app/modules/users/services/AuthService.passwordless.test.ts` asserts (a) keine Session-Erstellung, (b) keine `verifyPassword`-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.