docs(website): add API v2 plan (auth merge, CSP hardening, domain split) #45

wtclaude · 2026-07-22T21:51:02Z

wtclaude commented

2026-07-22 21:51:02 +00:00

Adds website/API_V2_PLAN.md — the design plan for website API v2. Docs-only; no code changes.

What v2 is

Two sequenced pieces of work landed behind a parallel /api/v2 (v1 frozen, migrate the client route-by-route, retire v1 last):

Phase 1 — the auth merge. Retire httpOnly session cookies; unify web + mobile on the bearer access + rotating/revocable refresh model that mobile already has (mintMobileTokens / refreshMobileSession). The merge is mostly deletion — web joins the mobile session model and the /auth/mobile/* namespace collapses into plain /auth/*. Two constraints called out explicitly:

SSO / email-connect transaction cookies stay — the browser redirects to the IdP with no JS context to carry a bearer; only the final session handoff changes (callback → one-time code the SPA exchanges, so no token in the URL).
SSE moves to fetch-based streaming with Authorization: Bearer (EventSource can't send headers), preserving the public/admin allowlist boundary.

Phase 1b — CSP hardening. Once the token lives in JS, CSP's job is "injected script can't run and can't phone home." Tightens the already-shipped policy: add form-action 'self', frame-ancestors 'self' → 'none'; keep script-src/connect-src at 'self'. Self-host fonts + Trusted Types (report-only rollout) tracked as follow-ups.

Phase 2 — the domain split. Break the monolithic route wiring (admin.routes.js, ~100 routes / 14 controllers) into one router per business capability so the URL predicts the file. Controllers are already domain-split; this is re-wiring, not re-logic.

Notes

Locked decisions (versioning / web session model / SSE auth) are recorded in the doc.
Risks flagged: XSS → token theft (mitigated by short TTL + rotation + CSP), unavoidable tx cookies, SSE reconnect regressions, v1/v2 double-maintenance window.

AI-assisted: authored with Claude (Claude Code). See the commit's Co-Authored-By trailer.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr

Adds `website/API_V2_PLAN.md` — the design plan for website API v2. Docs-only; no code changes. ## What v2 is Two sequenced pieces of work landed behind a **parallel `/api/v2`** (v1 frozen, migrate the client route-by-route, retire v1 last): **Phase 1 — the auth merge.** Retire httpOnly session cookies; unify web + mobile on the bearer **access + rotating/revocable refresh** model that mobile already has (`mintMobileTokens` / `refreshMobileSession`). The merge is mostly deletion — web joins the mobile session model and the `/auth/mobile/*` namespace collapses into plain `/auth/*`. Two constraints called out explicitly: - **SSO / email-connect transaction cookies stay** — the browser redirects to the IdP with no JS context to carry a bearer; only the final session handoff changes (callback → one-time code the SPA exchanges, so no token in the URL). - **SSE moves to fetch-based streaming** with `Authorization: Bearer` (EventSource can't send headers), preserving the public/admin allowlist boundary. **Phase 1b — CSP hardening.** Once the token lives in JS, CSP's job is "injected script can't run and can't phone home." Tightens the already-shipped policy: add `form-action 'self'`, `frame-ancestors 'self'` → `'none'`; keep `script-src`/`connect-src` at `'self'`. Self-host fonts + Trusted Types (report-only rollout) tracked as follow-ups. **Phase 2 — the domain split.** Break the monolithic route wiring (`admin.routes.js`, ~100 routes / 14 controllers) into one router per business capability so the URL predicts the file. Controllers are already domain-split; this is re-wiring, not re-logic. ## Notes - Locked decisions (versioning / web session model / SSE auth) are recorded in the doc. - Risks flagged: XSS → token theft (mitigated by short TTL + rotation + CSP), unavoidable tx cookies, SSE reconnect regressions, v1/v2 double-maintenance window. --- AI-assisted: authored with Claude (Claude Code). See the commit's `Co-Authored-By` trailer. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr

wtclaude added 1 commit 2026-07-22 21:51:03 +00:00

docs(website): add API v2 plan (auth merge, CSP hardening, domain split) eb19556802

Plan for website API v2, sequenced in two phases behind a parallel /api/v2:

- Phase 1: retire httpOnly session cookies; unify web + mobile on the existing
  bearer access + rotating/revocable refresh model. Separates removable session
  cookies from the SSO/email transaction cookies that must stay. SSE moves to
  fetch-based streaming with Authorization: Bearer.
- Phase 1b: tighten the shipped CSP for the now-JS-held token (add form-action
  'self', frame-ancestors 'none'); self-host fonts + Trusted Types as follow-ups.
- Phase 2: break the monolithic route wiring (admin.routes.js, ~100 routes) into
  one router per business capability so the URL predicts the file.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-07-22 21:51:59 +00:00

whitlocktech merged commit cfd202b23e into main

2026-07-22 21:52:05 +00:00

whitlocktech deleted branch docs/api-v2-plan

2026-07-22 21:52:06 +00:00

whitlocktech referenced this issue from a commit

2026-07-22 21:52:07 +00:00

Merge pull request 'docs(website): add API v2 plan (auth merge, CSP hardening, domain split)' (#45) from docs/api-v2-plan into main

wtclaude referenced this pull request

2026-07-22 21:55:52 +00:00

docs(website): add /api/v2 skeleton (PR 1 scaffold) #46

Sign in to join this conversation.