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

219 lines
15 KiB
Markdown

# Magic-Link Secondary-Flow (Password-Reset-Alternative)
**Status:** completed
**Task-ID:** #19
**Phase:** 01
**Estimated Effort:** 1 Tag
**Owner:** claude (opus-4-7)
## Problem
Aktuell hat `/forgot-password` nur einen Pfad: Benutzer gibt Email an → bekommt einen Reset-Link → muss ein neues Passwort setzen. Das ist:
- **Friction**: User muss sich ein neues Passwort merken/speichern
- **Konversions-Verlust**: viele User brechen ab beim Schritt "neues Passwort setzen"
- **Inkonsistent zu modernen SaaS**: Notion, Linear, Vercel etc. bieten Magic-Link als Alternative
`apps/web/app/services/auth/magic-link.server.ts` existiert bereits (für Initial-Onboarding). Wir nutzen die existierende Token-Generation-Logik und exposen sie als zweiten Button im `/forgot-password`-Flow.
Resultat: User wählt zwischen
- "Reset-Link senden" (klassisch, neuer Password-Setup)
- "Magic-Link senden" (direkt einloggen ohne Passwort-Change)
Beide Pfade bleiben parallel.
## Depends on
- `01-tech-debt-foundation/password-policy.md` (#27) — Reset-Pfad nutzt die neue Policy beim Passwort-Setup. Wenn Magic-Link gewählt wird, ist keine Passwort-Eingabe nötig → keine Policy-Berührung, aber Code-Konsistenz wichtig.
- `01-tech-debt-foundation/dep-updates.md` (#28) — bcrypt → argon2; bei Magic-Link wird kein Hash neu gesetzt, aber die Session-Erstellung muss konsistent sein.
## Blocks
- `01-tech-debt-foundation/magic-link-invitation.md` (#20) — gleiches `magic-link.server.ts`-File. Wenn parallel gearbeitet wird, kommt es zu Merge-Konflikten. Empfohlen: #19 zuerst, #20 danach.
## Approach
**Minimal-Invasive Erweiterung** des bestehenden Flows. Kein neuer Auth-Service, kein paralleler Token-Store — wir nutzen `magic-link.server.ts` wie es ist.
UI-Änderungen:
- `/forgot-password` bekommt zwei Buttons statt einem:
- **Primary**: "Passwort zurücksetzen" (existierend)
- **Secondary**: "Einmal-Login per Magic-Link senden" (neu)
- Beide POSTen an unterschiedliche Action-IDs (`reset` vs `magic`).
Backend-Änderungen:
- `forgot-password.tsx` Action discriminiert per Form-Field `mode: 'reset' | 'magic'`.
- Bei `mode: 'magic'`: signierter Token via `magic-link.server.ts.generateMagicLinkToken({ userId, purpose: 'login', ttl: 15min })` erstellt, Email mit Link `https://<host>/auth/magic-link?token=<token>` versendet.
- Neue Route `apps/web/app/routes/auth/magic-link.tsx`: Loader verifiziert Token (single-use, expire-check), erzeugt Session, redirected zu Dashboard.
Rate-Limit auf den Trigger-Endpoint: per IP UND per Email-Address (max 3 Requests / 15 Min). Email-basiertes Limit verhindert Email-Bombing.
Alternativen verworfen:
- **Magic-Link ersetzt Reset-Flow komplett** — Risiko für User die Authenticator-Apps mit gespeicherten Passwörtern nutzen, würden Workflow brechen.
- **OAuth-Replacement** — out-of-scope, Phase 09 adressiert das.
## Implementation Steps
1. **Audit `magic-link.server.ts`**
- Files: keine (Recherche)
- Aktion: Prüfen welche API bereits existiert. Wenn `generateMagicLinkToken({purpose, ttl})` schon polyvalent designed ist → direkt nutzen. Wenn nur invitation-spezifisch → minor Refactor um `purpose: 'login' | 'invitation' | 'reset-alt'`-Param zu unterstützen.
- Output: Notiz im PR-Body
2. **Magic-Link-Service polyvalent machen (falls nötig)**
- Files: `apps/web/app/services/auth/magic-link.server.ts`
- Aktion:
- `generateMagicLinkToken({ userId, purpose, ttl, metadata? })` exportieren
- `verifyMagicLinkToken(token, expectedPurpose?)` exportieren — Single-Use durch In-DB-Used-Flag oder In-Memory-Nonce-Store (Empfehlung: DB-Flag wenn schon Token-Tabelle existiert, sonst In-Memory mit Redis als Backing).
- Tests dafür schreiben.
- Commit: `01/magic-link-reset: extend magic-link service with purpose param`
3. **Action-Logic in `/forgot-password`**
- Files: `apps/web/app/routes/forgot-password.tsx` (oder wherever die Action lebt)
- Aktion:
- Form-Field `mode` lesen
- Bei `reset`: existierender Pfad
- Bei `magic`:
1. User per Email lookup
2. Wenn User existiert: `generateMagicLinkToken({ userId, purpose: 'login', ttl: 15*60*1000 })`
3. Email versenden via existierendem EmailService (Template: `magicLinkLogin`)
4. Response: gleicher generischer Success-Message wie Reset-Pfad ("Wenn ein Account existiert, haben wir dir einen Link geschickt") — kein User-Enumeration-Risk
- Bei Nicht-Existenz: identischer Response (anti-enumeration)
- Commit: `01/magic-link-reset: add magic-link mode to forgot-password action`
4. **UI mit zwei Buttons**
- Files: `apps/web/app/routes/forgot-password.tsx` (Component) ggf. + Übersetzungs-Files
- Aktion:
- Form mit zwei `<button type="submit" name="mode" value="...">`-Buttons
- Primary = Reset, Secondary = Magic-Link
- Sub-Text unter dem Magic-Link-Button: "Du erhältst einen Link der dich für 15 Minuten direkt einloggt — ohne Passwort-Change."
- Beide Buttons mit Loading-State während Submission
- Commit: `01/magic-link-reset: add dual-button UI to forgot-password`
5. **Neue Route `/auth/magic-link`**
- Files: `apps/web/app/routes/auth/magic-link.tsx` (neu), `app/routes.ts` (Eintrag)
- Aktion:
- Loader: `?token=...`-Param lesen, `verifyMagicLinkToken(token, 'login')` aufrufen
- Bei valid: Session erzeugen (existierender Auth-Pfad), Token als used markieren, Redirect zu `/app/<tenant>` oder `/dashboard` je nach existing Logik
- Bei invalid (expired/used/forged): Error-Page mit Hinweis "Link ungültig oder abgelaufen. Versuche es erneut."
- **Kein** automatisches Magic-Link-Re-Issue — User muss aktiv neuen anfordern (verhindert Token-Leak-Abuse)
- Commit: `01/magic-link-reset: add /auth/magic-link route`
6. **Email-Template `magicLinkLogin`**
- Files: bestehender Email-Templates-Pfad (z.B. `apps/web/app/modules/emails/templates/...`)
- Aktion:
- Template mit Login-Link, TTL-Hinweis, "wenn du das nicht warst, ignoriere diese Email"-Disclaimer, Support-Link
- DE + EN (entsprechend bestehender i18n-Convention)
- Commit: `01/magic-link-reset: add magicLinkLogin email template`
7. **Rate-Limit auf `/forgot-password`-Action**
- Files: existierender Rate-Limiter-Pfad
- Aktion:
- 3 Requests / 15 Min per IP UND per email-hash (separate Counter)
- Bei Limit-Hit: 429 + generische Error-Message
- Commit: `01/magic-link-reset: rate-limit forgot-password trigger`
8. **Audit-Log**
- Files: existierender AuditEvent-Pfad
- Aktion: bei Magic-Link-Request einen `auth.magic-link.requested`-Event, bei Magic-Link-Login einen `auth.magic-link.login`-Event. User-ID, IP, User-Agent.
- Commit: `01/magic-link-reset: audit-log magic-link events`
## Test Requirements
- **Unit-Tests:**
- `magic-link.server.test.ts`: token-roundtrip, expire-check, single-use-check, purpose-validation, forged-token-rejection
- **Integration-Tests:**
- POST `/forgot-password` mit `mode: 'magic'` und valider Email → 200 + Email versendet
- POST `/forgot-password` mit `mode: 'magic'` und nicht-existenter Email → 200 (identische Response)
- GET `/auth/magic-link?token=<valid>` → Session erzeugt, Redirect
- GET `/auth/magic-link?token=<expired>` → Error-Page
- GET `/auth/magic-link?token=<used>` → Error-Page
- Rate-Limit: 4. Request innerhalb 15 Min → 429
- **E2E-Tests (Playwright):**
- User klickt "Magic-Link senden" → Email in Mailpit/Mailcatcher → klickt Link → wird eingeloggt und sieht Dashboard
- User klickt abgelaufenen Link → sieht Error
- **Coverage-Target:**
- `magic-link.server.ts`: ≥ 95%
- `/auth/magic-link`-Route: ≥ 90%
- **Test-Files:**
- `apps/web/app/services/auth/magic-link.server.test.ts` (neu/erweitert)
- `apps/web/app/routes/auth/magic-link.test.ts` (neu)
- `apps/web/app/routes/forgot-password.test.ts` (erweitert)
**NICHT als completed markieren bevor E2E-Flow auf Staging mit echter Mail-Versendung grün ist.**
## Acceptance Criteria
- [x] `/forgot-password` zeigt zwei Buttons (Reset + Magic-Link)
- [x] Magic-Link-Email enthält gültigen Token (15 Min TTL)
- [x] `/auth/magic-link?token=...` loggt User ein bei valid Token
- [x] Single-Use: zweiter Klick auf denselben Link → Error
- [x] Rate-Limit aktiv (3 / 15 Min per IP UND per email)
- [x] Anti-Enumeration: gleiche Response für existing/nicht-existing Email
- [x] AuditEvents geschrieben
- [x] Email-Template DE + EN
- [x] Unit + Integration + staging smoke grün
- [x] `pnpm lint`, `pnpm typecheck`, focused tests grün
- [x] Detail-MD Progress-Log aktualisiert
- [x] PROGRESS.md Status auf `completed`
## Rollback Strategy
8 atomic commits → einzeln revert-bar.
- **Bei Token-Verify-Bug:** Schritt 5+6 revert → UI-Button bleibt aber führt zu 404. Sauberer: alle 8 Commits in einem `git revert <range>` rollbacken.
- **Bei Email-Spam-Beschwerden:** Schritt 7 (Rate-Limit) verschärfen statt Feature deaktivieren.
- **Notfall-Bypass:** Env `AUTH_MAGIC_LINK_ENABLED=false` (in Step 3 implementieren — defaults true) versteckt den Magic-Link-Button + lehnt Token-Verify ab.
Keine DB-Schema-Changes außer evtl. `magicLinkTokens.used`-Bool wenn neu — Down-Migration im Migrations-File.
## Security Notes
- **Single-Use ist kritisch.** Wenn Token mehrfach nutzbar wäre, könnte ein abgefangener Link mehrfach verwendet werden. Implementation: DB-Flag `used: true` + DB-Update in atomarer Transaktion (SELECT FOR UPDATE).
- **15 Min TTL** ist ein Trade-off. Länger = besser UX (Email-Delay-Toleranz), kürzer = besser Security. 15 Min ist branchenüblich.
- **Anti-Enumeration**: identische Response für existing/nicht-existing Email verhindert dass Angreifer Email-Adressen rausfindet. KRITISCH — niemals "User not found" zurückgeben.
- **Rate-Limit per email-hash** verhindert dass Angreifer einen Opfer-Account mit Magic-Link-Spam überflutet.
- **Token-Signature**: Token MUSS signiert sein (HMAC-SHA256 mit Server-Secret). Niemals nur Random-String + DB-Lookup — bei DB-Compromise wären alle aktiven Token gültig.
- **Token-Logging-Hygiene**: Token-Wert darf NIEMALS in Logs erscheinen. Auch nicht in Sentry/Breadcrumbs.
- **HTTPS-only**: Token im URL-Query muss bei jeder Antwort den `Cache-Control: no-store`-Header haben.
- **Referer-Leakage**: `<meta name="referrer" content="no-referrer">` auf der `/auth/magic-link`-Page damit Token nicht via Referer-Header an Drittseiten geht (z.B. wenn die Page einen externen Link enthält).
## Subagent Recommendations
- **Planning:** unnötig.
- **Research:** `general-purpose` für `magic-link.server.ts`-API-Audit (Step 1).
- **Implementation:** ein `general-purpose`-Subagent für Steps 2+3 (Service + Action), ein zweiter für Steps 4-6 (UI + Route + Template), ein dritter für Steps 7+8 (Rate-Limit + Audit).
- **Tests:** `general-purpose`-Subagent für Test-Suite gemäß Test-Requirements.
- **Verification:** `general-purpose` für Acceptance-Criteria + Staging-E2E.
- **Code-Review:** `gsd-code-reviewer` nach Phase-Abschluss, speziell Security-Pfade.
## Staging-Deployment-Steps
1. Branch `agent/01-magic-link-reset` pushen.
2. Coolify-Auto-Deploy.
3. Smoke-Tests:
- `/forgot-password` öffnen → beide Buttons sichtbar
- "Magic-Link senden" klicken → Mailpit checken → Email mit Link erscheint
- Link klicken → eingeloggt
- Link nochmal klicken → Error
- 4. Magic-Link in 15 Min anfordern → 429
4. Audit-Log auf Staging prüfen.
5. Token-Signatur manuell verifizieren (Token kopieren, mit Server-Secret nachsignieren, vergleichen).
## Deviations from Plan
- **Persistent mail worker closeout landed after the first blocker proof.** On 2026-05-24, Mailjet env was set on the Coolify web/api/worker resources and a temporary `WORKER_QUEUE_GROUP=mail` container processed the Magic-Link job successfully. On 2026-05-25, B-014 was resolved by persistent Coolify worker applications for `general`, `mail`, `import`, `webhook`, and `plugin`; the `mail` group now drains `toolctrl.email` continuously.
## Progress Log
> Entries before 2026-05-25 are historical incident evidence. The temporary
> `WORKER_QUEUE_GROUP=mail` notes and the "persistent mail-worker" gap below
> were superseded by the 2026-05-25 staging closeout. Current worker topology
> truth lives in `docs/ops/worker-queues.md`, `docs/worker.md`, and
> `docs/deployment.md`.
- 2026-05-17 04:47 — staging-verify — `MagicLinkToken`-Tabelle auf staging vorhanden mit Schema (id, createdAt, userId, tokenHash, expiresAt, consumedAt) + 3 Indexes (`tokenHash` unique, `userId,expiresAt`, `expiresAt,consumedAt`) + FK ON DELETE CASCADE. **Kein `purpose`-Column** — single-token-table-Design, Routes diskriminieren über separate Routes/Templates statt DB-Field. Aktueller Bestand: total=0, consumed=0, expired=0 (noch kein Magic-Link auf staging angefordert). Code via web-container `37f23fa6...` deployed. Live-Smoke (forgot-password → email → click → session) bleibt für operator (Email-Versand ohne Mailpit auf staging nicht testable per SSH).
- 2026-05-24 19:44 Europe/Berlin — staging-live — `f86dc77f` deployed healthy across web/api/worker. `/forgot-password` GET returned 200; POST with `mode=magic` for the staging admin returned 200 HTML and created a `MagicLinkToken` row plus a critical `toolctrl.email` job containing the `magic-link` template data. The prior 500s were fixed by `150a593b` (preserve real server-side `@toolctrl/queue/runtime` dynamic imports despite the Vite browser alias) and `f86dc77f` (preserve BullMQ `queue.add` receiver binding in `enqueueJob`).
- 2026-05-24 19:46 Europe/Berlin — staging-live — Extracted the queued action URL without printing the token. First GET `/auth/magic-link?token=...` returned 302 `/` with a session cookie and marked the DB token consumed. Replay of the same URL returned 200 with the "already used / works only once" copy. Latest DB token state: consumed and unexpired.
- 2026-05-24 19:49 Europe/Berlin — staging-live blocker proof — Removed the consumed test job, requested a fresh magic link, and started a temporary `WORKER_QUEUE_GROUP=mail` container from the deployed worker image. The job moved from `prioritized` to terminal `failed` after 3 attempts with missing Mailjet API key; the temporary container was removed and the failed test job was cleaned from Redis. This verifies the core auth flow and identifies the remaining closeout blocker as staging mail configuration, not application code.
- 2026-05-24 20:30 Europe/Berlin — staging-live mail-provider smoke — Operator supplied Mailjet credentials; Coolify envs were added to web/api/worker and all three resources were redeployed on `b6b65247`. Container env checks showed all three `MAILERSEND_*` keys present. A fresh `/forgot-password` `mode=magic` request created `toolctrl.email` job `3`; a temporary `WORKER_QUEUE_GROUP=mail` container processed it successfully (`Worker job completed`, attemptsMade=1). The temporary worker was removed, queue counts returned to zero, the captured Magic-Link URL returned 302 `/` with a session cookie, and replay returned the already-used page. At that time the remaining gap was a persistent Coolify mail-worker service; this was closed by the 2026-05-25 entry below.
- 2026-05-25 — staging-closeout — B-014 resolved. Coolify now runs persistent separate worker applications for `general`, `mail`, `import`, `webhook`, and `plugin` from the shared worker image. The active staging worker containers are healthy, use distinct health/admin ports, and the legacy single-worker container is no longer active. #19 is operationally closed because future Magic-Link mail jobs no longer depend on manual temporary worker starts.