Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
+214
@@ -0,0 +1,214 @@
|
||||
# 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/<id> 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.
|
||||
Reference in new issue
Block a user