Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/01-tech-debt-foundation/magic-link-invitation.md
T

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:

  1. Admin lädt User per Email ein → Invitation-Row in DB mit ID
  2. User bekommt Email mit Link https://<host>/invitation/<id>
  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 <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.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://<host>/invitation/<id>?magic=<token>
  3. 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)
    • 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/<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)
    • 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=<valid> → User wird erstellt, Membership erzeugt, Session aktiv
    • GET /invitation/:id?magic=<valid> mit metadata.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/: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/<id>-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.