Archive unify-auth-completion + sync spec delta (task 5.1)

Applies the ADDED requirement from
openspec/changes/unify-auth-completion/specs/authentication-methods/
into openspec/specs/authentication-methods/spec.md:

- Single web auth completion chokepoint (completeAuth at
  apps/journal/app/lib/auth/completion.server.ts) with five scenarios
  covering passkey register/login finish, magic-link verify-code,
  magic-link click-through, and returnTo sanitization.

Path in the synced requirement is .server.ts (the post-rename name),
not the .ts the delta originally captured.

Change moved to openspec/changes/archive/2026-05-08-unify-auth-completion/.
15/15 tasks complete.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

openspec/changes/archive/2026-05-08-unify-auth-completion/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-08

openspec/changes/archive/2026-05-08-unify-auth-completion/design.md

@@ -0,0 +1,103 @@
+## Context
+
+`apps/journal/app/lib/auth.server.ts` is 489 lines covering passkey ceremonies, magic-link token lifecycle, session cookie storage, terms recording, and email-change tokens. Four route handlers (`api.auth.register.ts`, `api.auth.login.ts` × 2 branches, `auth.verify.tsx`) each repeat the same trailing sequence after their per-method identity verification:
+
+```ts
+if (isNewRegistration) await recordTermsAcceptance(userId, termsVersion);
+const headers = await createSession(userId, request);
+return redirect(safeReturnTo(returnTo) ?? "/", { headers });
+```
+
+The repetition is the *entire* asymmetry between methods at the post-verify layer. WebAuthn vs. magic-link diverge before this point (challenge persistence, token consumption, etc.) but converge here — every flow does the same thing.
+
+ADRs already recorded:
+- ADR-0004: centralize this orchestration in a single `completeAuth` function.
+- ADR-0005: do **not** extract an `AuthMethod` interface; passkey + magic-link is the entire surface and OAuth2 is transport, not a peer.
+
+## Goals / Non-Goals
+
+**Goals:**
+- One function (`completeAuth`) is the only place where a successful web auth records terms + creates session + redirects. Bug fixes apply once.
+- File reorganization: `apps/journal/app/lib/auth/` directory containing `completion.ts` and `session.ts`. The existing `auth.server.ts` shrinks but stays for the per-method functions (passkey ceremony, magic-token lifecycle).
+- `returnTo` sanitization centralized inside `completeAuth` so no caller can ship an open-redirect.
+- Refactor is behaviour-preserving: existing e2e auth tests pass without modification.
+
+**Non-Goals:**
+- No `AuthMethod` interface (per ADR-0005).
+- The OAuth-code issuance flow at `/oauth/authorize` is NOT migrated. It operates on already-authenticated users; only the trailing redirect overlaps, not enough leverage to fold in.
+- The add-passkey post-login ceremony does NOT need `completeAuth` (no session creation — user is already logged in).
+- The magic-link request-token step does NOT need `completeAuth` (only emits a token; verification happens later).
+- Session transport (cookie vs. bearer) — orthogonal; not touched.
+- Connected-devices UX — separate spec.
+- Any change to the Terms gate enforcement points (root loader for web, `requireApiUser` for API).
+
+## Decisions
+
+### Decision 1: Single function, no mode flag
+`completeAuth` covers exactly the four web post-verify call sites listed in the proposal. There is no `redirectMode: 'cookie' | 'oauth-code'` flag because OAuth-code issuance is genuinely a different flow (already-authenticated user, no session creation, only a code + redirect). Folding both into one function would force a discriminated union and obscure that they don't share much. The OAuth-code path stays in `oauth.authorize.tsx` unchanged.
+
+### Decision 2: Function signature
+```ts
+async function completeAuth(input: {
+  userId: string;
+  request: Request;
+  returnTo?: string | null;
+}): Promise<Response>
+```
+
+Returns a `Response` (a `redirect` from React Router with the session `Set-Cookie` attached). Callers do `return await completeAuth(...)` from their action / loader. No headers-vs-redirect split: the chokepoint owns both halves.
+
+**Terms recording is NOT in `completeAuth`.** Both registration paths already write `terms_version` + `terms_accepted_at` at user creation: `finishRegistration` writes them when the user row is inserted (passkey path); `registerWithMagicLink` writes them when the user row is inserted (magic-link path). Magic-link registration *must* write terms at user creation, before verification, because the user row exists between register and verify — if terms weren't already written, the Terms gate would bounce the user on first authenticated visit.
+
+So `completeAuth` is purely **session + redirect**. No `isNewRegistration` flag, no `termsVersion` parameter. The earlier framing of an `isNewRegistration` discriminator was a mis-read — there is no code path that needs to record terms at completion time.
+
+### Decision 3: File layout
+New directory `apps/journal/app/lib/auth/` containing:
+- `completion.ts` — `completeAuth` + `safeReturnTo` helper (open-redirect rejection).
+- `session.ts` — `sessionStorage`, `createSession`, `getSessionUser`, `destroySession`. Moved from `auth.server.ts`.
+
+`auth.server.ts` keeps the per-method functions (passkey ceremony, magic-token lifecycle, terms recording, email-change). It re-exports the moved session helpers from their new home so existing imports keep working without a touch:
+```ts
+// auth.server.ts
+export { sessionStorage, createSession, getSessionUser, destroySession } from "./auth/session.ts";
+```
+
+That keeps the migration small. A future change can rip the re-exports and update callers across the app — out of scope here.
+
+### Decision 4: `returnTo` sanitization centralizes inside `completeAuth`
+Today, several callers do their own `returnTo` checks of varying rigor (some check `startsWith("/") && !startsWith("//")`, others don't). Move the check into `safeReturnTo` inside `completion.ts`; every caller passes `returnTo` raw and gets the safe version applied uniformly. Reject anything that isn't a same-origin path → fall back to `/`.
+
+### Decision 5: Tests
+Unit tests for `completeAuth` in `completion.test.ts`:
+- new-registration writes `users.terms_version` + `users.terms_accepted_at` (mock the DB or use an in-memory test DB — match existing test patterns).
+- non-registration skips the terms write.
+- response includes a `Set-Cookie` header from `sessionStorage.commitSession`.
+- `returnTo` of `/foo` redirects to `/foo`; `returnTo` of `//evil.com/x` redirects to `/`; `returnTo` of `https://evil.com` redirects to `/`; missing `returnTo` redirects to `/`.
+
+Existing `e2e/auth.test.ts` (passkey register + login + logout) MUST pass without modification — that's the behaviour-preservation proof.
+
+## Risks / Trade-offs
+
+- **[Risk]** Re-exporting from `auth.server.ts` to maintain backwards compatibility means there are temporarily two paths to the same symbols. → **Mitigation:** comment marks the re-exports as transitional. A follow-up PR (small) can update import paths app-wide and remove the re-exports.
+
+- **[Risk]** The runtime assertion (`isNewRegistration && !termsVersion → throw`) is a programmer error, not a user-visible failure. If a future caller forgets to pass `termsVersion`, tests should catch it; if they don't, registration breaks loudly. → **Accepted:** the type-level alternative (discriminated union) costs more than it pays back at three internal call sites.
+
+- **[Trade-off]** Centralizing `returnTo` sanitization changes behaviour at any call sites that *don't* currently sanitize. The change is strictly safer (rejecting more inputs as `/`) but worth confirming there are no integration tests that pass a deliberately-unsafe `returnTo` and expect it to work.
+
+## Migration Plan
+
+Single PR ("spec apply") containing:
+
+1. Create `apps/journal/app/lib/auth/session.ts` with the moved helpers.
+2. Add re-exports in `auth.server.ts`.
+3. Create `apps/journal/app/lib/auth/completion.ts` with `completeAuth` + `safeReturnTo`.
+4. Write `completion.test.ts` (unit tests).
+5. Migrate the 4 callers to `completeAuth`.
+6. Verify `pnpm typecheck && pnpm lint && pnpm test && pnpm test:e2e` green.
+
+**Rollback**: revert the PR. No DB or schema changes; the file moves are pure code-organization, the call-site changes are mechanical.
+
+## Open Questions
+
+- **Q1**: Does `sessionStorage` get its `secret` from `process.env.SESSION_SECRET` directly, or from a config helper? Move-as-is and revisit only if it complicates the `session.ts` file. → Decide during implementation.
+- **Q2**: Should the `auth.server.ts` re-exports be marked `@deprecated` JSDoc-style so editors warn on use? Light touch — yes, with a comment pointing at `./auth/session.ts`. Decide during implementation.

openspec/changes/archive/2026-05-08-unify-auth-completion/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+Every successful web authentication today inlines the same three-step orchestration in its route handler: record the accepted Terms version on registration (`recordTermsAcceptance`), mint the session cookie (`createSession`), and `redirect(returnTo ?? "/", { headers })`. Four call sites — passkey register-finish, passkey login-finish, magic-link verify-code, and the magic-link click-through consumer — re-implement the same sequence. A bug in any one of them must be fixed in four places, and a future fifth flow (admin impersonation, recovery, etc.) re-derives the same boilerplate.
+
+This change extracts the orchestration into a single function `completeAuth` and folds in the small file-organization win that comes with it (a new `apps/journal/app/lib/auth/` directory). It does **not** introduce an `AuthMethod` interface — see ADR-0005 for why polymorphism here is theoretical with no future adapter.
+
+## What Changes
+
+- **New module** `apps/journal/app/lib/auth/completion.ts` exporting `completeAuth({ userId, isNewRegistration, termsVersion?, request, returnTo? }) → Promise<Response>`. Records terms on registration (only), creates the session, returns a `redirect(...)` Response with the `Set-Cookie` header attached.
+- **New module** `apps/journal/app/lib/auth/session.ts` carrying the cookie session storage (`sessionStorage`, `createSession`, `getSessionUser`, `destroySession`) extracted from `auth.server.ts`. The existing path keeps re-exports for backwards compatibility — caller migration is a follow-up if anything.
+- **Caller migration**: 4 route handlers (`api.auth.register.ts` passkey-finish branch, `api.auth.login.ts` passkey-finish-passkey branch, `api.auth.login.ts` magic-link verify-code branch, `auth.verify.tsx` magic-link click-through) replace their inlined orchestration with a single `completeAuth(...)` call.
+- **`returnTo` sanitization** centralizes inside `completeAuth` (was already same-origin checked in callers; now there's one place).
+- **Tests**: new `completion.test.ts` covering register-records-terms, non-register-skips-terms, returnTo default, header attachment, returnTo open-redirect rejection. Existing `e2e/auth.test.ts` continues to pass without modification — that's the proof the refactor is behaviour-preserving.
+- **Negative scope (recorded in ADR-0005)**: no `AuthMethod` interface, no adapter pattern. Passkey + magic-link is the entire identity surface; OAuth2/PKCE is session transport, not a third method.
+
+## Capabilities
+
+### New Capabilities
+
+(none — this change reshapes existing capabilities, no new user-visible behaviour.)
+
+### Modified Capabilities
+
+- `authentication-methods`: requirement-level addition codifying that every post-verify web flow goes through the single completion chokepoint that records terms (on register), creates the session, and redirects. User-visible behaviour unchanged.
+
+## Impact
+
+- **Code**: 1 new directory (`apps/journal/app/lib/auth/`), 2 new files (`completion.ts`, `session.ts`), `auth.server.ts` slims down by ~80 lines (the moved session helpers), 4 route handlers shrink. No DB changes. No schema changes.
+- **Tests**: 1 new unit test file (`completion.test.ts`). Existing e2e auth test should pass unmodified.
+- **Specs**: 1 spec gets a small ADDED requirement (`authentication-methods/spec.md`).
+- **Decision references**: `docs/adr/0004-centralize-auth-completion.md`, `docs/adr/0005-no-authmethod-polymorphism.md`, `CONTEXT.md` (Authentication section).
+- **Out of scope** (separate concerns): the OAuth-code issuance flow at `/oauth/authorize` (operates on already-authenticated users; only shares the trailing redirect), the magic-link request-token step (emits a token, no session created), the add-passkey post-login ceremony (no session creation). Connected-devices UX is its own spec/change. Session-transport changes (cookie ↔ bearer) are orthogonal and not touched here.

openspec/changes/archive/2026-05-08-unify-auth-completion/specs/authentication-methods/spec.md

@@ -0,0 +1,33 @@
+## 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

openspec/changes/archive/2026-05-08-unify-auth-completion/tasks.md

@@ -0,0 +1,30 @@
+## 1. New auth module structure
+
+- [x] 1.1 Create `apps/journal/app/lib/auth/` directory.
+- [x] 1.2 Create `apps/journal/app/lib/auth/session.ts` and move `sessionStorage`, `createSession`, `getSessionUser`, `destroySession` from `auth.server.ts` (preserve behaviour, including `process.env.SESSION_SECRET` source).
+- [x] 1.3 In `auth.server.ts`, re-export the moved helpers from `./auth/session.ts` so existing imports keep working unchanged. Add a JSDoc `@deprecated`-style comment pointing at the new path.
+
+## 2. completeAuth chokepoint
+
+- [x] 2.1 Write `apps/journal/app/lib/auth/completion.test.ts` (TDD red): scenarios for returnTo defaults to `/`, returnTo `//evil.com` rejected, returnTo `https://evil.com` rejected, response is a 302/303 redirect, response includes Set-Cookie naming `__session`.
+- [x] 2.2 Create `apps/journal/app/lib/auth/completion.ts` exporting `completeAuth({ userId, request, returnTo? }) → Promise<Response>` and a private `safeReturnTo(value)` helper. Implementation: `createSession(userId, request)`; `redirect(safeReturnTo(returnTo) ?? "/", { headers: { "Set-Cookie": cookie } })`. Terms recording is **not** here — both registration paths already record terms at user creation, so the chokepoint is purely session + redirect.
+- [x] 2.3 Run completion tests green.
+
+## 3. Caller migration
+
+- [x] 3.1 `apps/journal/app/routes/api.auth.register.ts` passkey-finish branch — replace inlined session+redirect with `return completeAuth({ userId, request, returnTo })`. Drop now-unused imports.
+- [x] 3.2 `apps/journal/app/routes/api.auth.login.ts` passkey `step: "finish-passkey"` branch — replace with `return completeAuth({ userId, request, returnTo })`.
+- [x] 3.3 `apps/journal/app/routes/api.auth.login.ts` magic-link `step: "verify-code"` branch — replace with `return completeAuth(...)`.
+- [x] 3.4 `apps/journal/app/routes/auth.verify.tsx` magic-link click-through consumer — replace with `return completeAuth(...)`.
+- [x] 3.5 Confirm no other callers of `createSession` remain inside auth route handlers (they should all flow through `completeAuth`). `getSessionUser` and `destroySession` continue to be called directly from non-completion sites — that's expected.
+
+## 4. Verification
+
+- [x] 4.1 `pnpm typecheck && pnpm lint && pnpm test` green.
+- [x] 4.2 `pnpm test:e2e` (auth flows) green without modification — proves behaviour-preserving refactor.
+- [x] 4.3 Manual sanity: register with passkey locally, login with passkey, log out, re-login via magic-link 6-digit code, click-through magic link from `auth.verify.tsx`. Confirm session cookie set + correct redirect each time. Verified 2026-05-08 over plain HTTP (HTTPS dev hits a pre-existing HTTP/2 + missing-Host issue with React Router 7.14's CSRF check — separate follow-up).
+
+## 5. Documentation + follow-up
+
+- [x] 5.1 At archive time, apply the spec delta in `specs/authentication-methods/` to `openspec/specs/`.
+- [x] 5.2 Update import paths app-wide from `auth.server.ts` to `./auth/session.ts` and drop the re-exports. (Folded into this PR after the smoke test confirmed everything works.)