d64c47614d
Implements all of unify-auth-completion (12/14 tasks done; manual
smoke + archive-time spec sync remain).
Design refinement during implementation: completeAuth supports two
response shapes via a `mode` parameter:
- mode: 'redirect' (loaders / direct browser navigation; auth.verify.tsx)
- mode: 'json' (action handlers called by imperative fetch from
client forms; api.auth.login, api.auth.register)
Both modes share createSession + safeReturnTo + Set-Cookie. JSON mode
carries `{ ok: true, step: "done", redirectTo }` (the `step` field
preserves the existing client-form check).
Why two modes: passkey ceremonies are inherently imperative
(start → browser WebAuthn API → finish), so action handlers can't
move to <Form>/useFetcher. Picking option (B) from the design grill —
the chokepoint owns destination selection while clients navigate —
required this dual shape. The 3 hardcoded client-side targets
(returnTo ?? "/", "/", "/?add-passkey=1") collapse into 1 server-side
sanitization pass (safeReturnTo) inside completeAuth.
New module:
- apps/journal/app/lib/auth/session.ts: cookie session storage
(sessionStorage, createSession, getSessionUser, destroySession)
moved from auth.server.ts. Legacy import path kept via re-exports
with @deprecated JSDoc.
- apps/journal/app/lib/auth/completion.ts: completeAuth + safeReturnTo.
- apps/journal/app/lib/auth/completion.test.ts: 10 contract tests
covering both modes, returnTo sanitization (path-relative, protocol-
relative, absolute-URL, malformed), Set-Cookie attachment, redirect
status, JSON shape.
Caller migration:
- api.auth.register.ts passkey-finish → completeAuth(json)
- api.auth.login.ts finish-passkey → completeAuth(json)
- api.auth.login.ts verify-code → completeAuth(json)
- auth.verify.tsx magic-link consumer → completeAuth(redirect)
Client form updates:
- auth.login.tsx: pass returnTo in fetch body, read result.redirectTo
on done.
- auth.register.tsx: pass returnTo: "/?add-passkey=1" for the magic-
link verify-code path (preserves the post-register passkey prompt
via the chokepoint's safeReturnTo, instead of hardcoding it
client-side).
Verified:
- pnpm typecheck && pnpm lint: green across all 15 workspaces.
- pnpm --filter @trails-cool/journal test: 126 passed.
- pnpm test:e2e auth: 4/4 passed without modification — confirms the
refactor is behaviour-preserving for the user-facing flows that
matter most (passkey register + login).
Spec delta in openspec/changes/unify-auth-completion/specs/ applies at
/opsx:archive time.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
33 lines
3.1 KiB
Markdown
33 lines
3.1 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Single web auth completion chokepoint
|
|
Every successful web authentication flow — passkey register-finish, passkey login-finish, magic-link 6-digit-code verify, magic-link click-through verify — SHALL complete by calling a single `completeAuth` function at `apps/journal/app/lib/auth/completion.ts`. The function SHALL be the sole place where a successful web authentication mints the cookie session and constructs the redirect to `returnTo` (or `/` when absent or rejected).
|
|
|
|
Per-method identity verification (WebAuthn ceremony, magic-token consumption, 6-digit-code consumption) SHALL run in its own function and produce a `userId` *before* `completeAuth` is invoked. `completeAuth` SHALL NOT know how identity was proved.
|
|
|
|
Terms recording happens at user creation time inside the per-method registration functions (`finishRegistration` for passkey, `registerWithMagicLink` for magic-link), not inside `completeAuth`. The Terms gate (root-loader redirect for cookie sessions; `requireApiUser` 403 for bearer-token API requests) SHALL remain the enforcement point for stale `terms_version`.
|
|
|
|
OAuth-code issuance at `/oauth/authorize` SHALL NOT be routed through `completeAuth` — that flow operates on an already-authenticated user and shares only the trailing redirect, not the full sequence.
|
|
|
|
#### Scenario: Passkey register-finish completes through the chokepoint
|
|
- **WHEN** a visitor submits a successful WebAuthn `step: "finish"` registration response
|
|
- **THEN** the route handler verifies the credential and creates the user row (with terms recorded) inside `finishRegistration`, then calls `completeAuth({ userId, request, returnTo })`
|
|
- **AND** `completeAuth` mints the session cookie and returns a `Response` redirecting to `returnTo` (or `/`)
|
|
|
|
#### Scenario: Passkey login-finish completes through the chokepoint
|
|
- **WHEN** a visitor submits a successful WebAuthn `step: "finish-passkey"` login response
|
|
- **THEN** the route handler verifies the credential and calls `completeAuth({ userId, request, returnTo })`
|
|
- **AND** `completeAuth` mints the session cookie and returns a `Response` redirecting to `returnTo` (or `/`)
|
|
|
|
#### Scenario: Magic-link 6-digit-code verify completes through the chokepoint
|
|
- **WHEN** a visitor submits a valid 6-digit code via `step: "verify-code"`
|
|
- **THEN** the route handler consumes the magic token (marks `used_at`) and calls `completeAuth({ userId, request, returnTo })`
|
|
|
|
#### Scenario: Magic-link click-through verify completes through the chokepoint
|
|
- **WHEN** a visitor opens `/auth/verify?token=<token>` with a valid, unused, unexpired token
|
|
- **THEN** the route handler consumes the magic token and calls `completeAuth({ userId, request, returnTo })`
|
|
|
|
#### Scenario: returnTo is sanitized inside completeAuth
|
|
- **WHEN** `completeAuth` is called with a `returnTo` value that is not a same-origin absolute path (e.g. starts with `//`, an absolute URL, or is malformed)
|
|
- **THEN** the redirect target falls back to `/` rather than honoring the unsafe value
|
|
- **AND** every caller benefits from the same check rather than reimplementing it
|