15 KiB
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) — gleichesmagic-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-passwordbekommt zwei Buttons statt einem:- Primary: "Passwort zurücksetzen" (existierend)
- Secondary: "Einmal-Login per Magic-Link senden" (neu)
- Beide POSTen an unterschiedliche Action-IDs (
resetvsmagic).
Backend-Änderungen:
forgot-password.tsxAction discriminiert per Form-Fieldmode: 'reset' | 'magic'.- Bei
mode: 'magic': signierter Token viamagic-link.server.ts.generateMagicLinkToken({ userId, purpose: 'login', ttl: 15min })erstellt, Email mit Linkhttps://<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
-
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 umpurpose: 'login' | 'invitation' | 'reset-alt'-Param zu unterstützen. - Output: Notiz im PR-Body
-
Magic-Link-Service polyvalent machen (falls nötig)
- Files:
apps/web/app/services/auth/magic-link.server.ts - Aktion:
generateMagicLinkToken({ userId, purpose, ttl, metadata? })exportierenverifyMagicLinkToken(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
- Files:
-
Action-Logic in
/forgot-password- Files:
apps/web/app/routes/forgot-password.tsx(oder wherever die Action lebt) - Aktion:
- Form-Field
modelesen - Bei
reset: existierender Pfad - Bei
magic:- User per Email lookup
- Wenn User existiert:
generateMagicLinkToken({ userId, purpose: 'login', ttl: 15*60*1000 }) - Email versenden via existierendem EmailService (Template:
magicLinkLogin) - 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)
- Form-Field
- Commit:
01/magic-link-reset: add magic-link mode to forgot-password action
- Files:
-
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
- Form mit zwei
- Commit:
01/magic-link-reset: add dual-button UI to forgot-password
- Files:
-
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/dashboardje 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)
- Loader:
- Commit:
01/magic-link-reset: add /auth/magic-link route
- Files:
-
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
- Files: bestehender Email-Templates-Pfad (z.B.
-
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
-
Audit-Log
- Files: existierender AuditEvent-Pfad
- Aktion: bei Magic-Link-Request einen
auth.magic-link.requested-Event, bei Magic-Link-Login einenauth.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-passwordmitmode: 'magic'und valider Email → 200 + Email versendet - POST
/forgot-passwordmitmode: '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
- POST
- 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
/forgot-passwordzeigt zwei Buttons (Reset + Magic-Link)- Magic-Link-Email enthält gültigen Token (15 Min TTL)
/auth/magic-link?token=...loggt User ein bei valid Token- Single-Use: zweiter Klick auf denselben Link → Error
- Rate-Limit aktiv (3 / 15 Min per IP UND per email)
- Anti-Enumeration: gleiche Response für existing/nicht-existing Email
- AuditEvents geschrieben
- Email-Template DE + EN
- Unit + Integration + staging smoke grün
pnpm lint,pnpm typecheck, focused tests grün- Detail-MD Progress-Log aktualisiert
- 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-purposefürmagic-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-purposefür Acceptance-Criteria + Staging-E2E. - Code-Review:
gsd-code-reviewernach Phase-Abschluss, speziell Security-Pfade.
Staging-Deployment-Steps
- Branch
agent/01-magic-link-resetpushen. - Coolify-Auto-Deploy.
- 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
-
- Magic-Link in 15 Min anfordern → 429
- Audit-Log auf Staging prüfen.
- 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=mailcontainer processed the Magic-Link job successfully. On 2026-05-25, B-014 was resolved by persistent Coolify worker applications forgeneral,mail,import,webhook, andplugin; themailgroup now drainstoolctrl.emailcontinuously.
Progress Log
Entries before 2026-05-25 are historical incident evidence. The temporary
WORKER_QUEUE_GROUP=mailnotes and the "persistent mail-worker" gap below were superseded by the 2026-05-25 staging closeout. Current worker topology truth lives indocs/ops/worker-queues.md,docs/worker.md, anddocs/deployment.md.
- 2026-05-17 04:47 — staging-verify —
MagicLinkToken-Tabelle auf staging vorhanden mit Schema (id, createdAt, userId, tokenHash, expiresAt, consumedAt) + 3 Indexes (tokenHashunique,userId,expiresAt,expiresAt,consumedAt) + FK ON DELETE CASCADE. Keinpurpose-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-container37f23fa6...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 —
f86dc77fdeployed healthy across web/api/worker./forgot-passwordGET returned 200; POST withmode=magicfor the staging admin returned 200 HTML and created aMagicLinkTokenrow plus a criticaltoolctrl.emailjob containing themagic-linktemplate data. The prior 500s were fixed by150a593b(preserve real server-side@toolctrl/queue/runtimedynamic imports despite the Vite browser alias) andf86dc77f(preserve BullMQqueue.addreceiver binding inenqueueJob). - 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=mailcontainer from the deployed worker image. The job moved fromprioritizedto terminalfailedafter 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 threeMAILERSEND_*keys present. A fresh/forgot-passwordmode=magicrequest createdtoolctrl.emailjob3; a temporaryWORKER_QUEUE_GROUP=mailcontainer 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, andpluginfrom 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.