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

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) — 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

  • /forgot-password zeigt 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-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
      1. 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.