docs/website/API_V2_PLAN.md

# Website API v2 — Plan

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

v2 is three sequenced pieces of work, landed in order:

0. **The mobile facade** (lands *first*, before any v2 work) — a **version-agnostic `/api/mobile`
   namespace** is stood up over the current controllers, and the Android app is migrated to it. From
   then on the app is pinned to `/api/mobile`, insulated from all internal version churn — so the
   auth merge and domain split below never touch it. See Phase 0.
1. **The auth merge** — httpOnly session cookies go away; a bearer JWT (access) + rotating
   refresh token becomes the single session model for *every* client (web and mobile).
2. **The domain split** — the monolithic route wiring (esp. `admin.routes.js`, 1552 lines) is
   broken into one router file per business capability, so a developer can predict where an
   endpoint lives from its URL.

## Locked decisions

| Decision | Choice | Consequence |
|---|---|---|
| Mobile decoupling | **A version-agnostic `/api/mobile` facade, landed before v2** | The Android app pins one stable namespace; internal v1→v2→vN churn never reaches it. The app leaves the v2 blast radius entirely. |
| Versioning | **New `/api/v2` mounted in parallel** with a frozen `/api/v1` | Migrate the *web* client route-by-route; delete v1 once no caller remains. No big-bang break. |
| Web session model | **Web adopts mobile's access + refresh** | One session model everywhere. Reuses `session.service` machinery that already exists — nothing new invented. |
| Live-feed (SSE) auth | **admin stream → fetch + `Authorization: Bearer`; public stream stays anonymous** | Admin token stays out of URLs/logs. Public/mobile stream keeps `EventSource`, no auth header. |

## What already exists (so we don't rebuild it)

- `auth/token.js` already extracts a token from cookie **or** `Authorization: Bearer`, and
  `auth/session.service.js` already unifies both into one session.
- Mobile already has the full target model: `mintMobileTokens` / `createMobileSession` /
  `refreshMobileSession`, with **hashed, rotated, revocable** refresh tokens stored server-side.
  Endpoints live at `/api/v1/auth/mobile/{login,refresh,logout}`.
- **The merge is therefore mostly deletion + rename:** web joins the mobile session model, the
  internal `/mobile` auth namespace collapses into unified `/auth/*`, and the cookie code path is
  removed. (The *app-facing* `/api/mobile` facade is unaffected — it re-points its internals to the
  unified flow; the app sees no change. See Phase 0.)

---

## Phase 0 — The mobile facade (`/api/mobile`, lands before v2)

**Goal:** make the Android app's contract *version-agnostic* so the v2 work below can proceed without
ever breaking an installed app. The app currently hardcodes ~70 `api/v1/…` endpoints (plus the SSE
path and SSO URLs) and has **no version negotiation and no force-update** — which is exactly why v1
can't otherwise be retired on the web client's schedule. Phase 0 pays that migration **once**, up
front, against a pure rename with no behavior change, and never again.

**What it is:** a thin routing facade mounted at `/api/mobile`, next to `/api/v1`, that delegates to
the **same controllers with the same middleware** as the routes it mirrors. It is *routing + optional
response-shaping*, never business logic — a Backend-for-Frontend, not a fork.

### Server

1. **Mount `/api/mobile` in `api.router.js`** next to `/v1` (today it mounts only `/v1`).
2. **Re-home the app's *entire* surface under it — not just the mobile-auth routes.** The app calls
   mostly *shared* routes (`auth/me/*`, `public/*`, `player/*`, `admin/*`) plus the mobile-only auth
   routes and the anonymous `public/shard/stream`. All of them move under `/api/mobile/**`. If any
   endpoint the app needs is left only under `/api/v1`, the app is not decoupled and the whole point
   is lost. Cross-check against the app's endpoint inventory (§ Cross-component blast radius).
3. **Delegate; never bypass auth.** Each facade route requires the *same* middleware chain as its
   underlying route (`requireAuth`, `staffOnly`/`adminOnly`, validators, the public/admin SSE
   allowlist split). A re-exposed admin route missing `adminOnly` is a privilege-escalation hole —
   treat the facade as a security surface, not a convenience alias.
4. **Keep the mobile SSE stream anonymous.** `/api/mobile/…/shard/stream` carries no auth (the app
   sends no `Authorization` header); only the public/safe kinds, same allowlist as today.
5. **Pin the wire shapes with contract tests.** `/api/mobile` is now a **committed stable contract**:
   a v2 internal refactor that changes a response shape must fail a test here *before* it can ship to
   installed apps. This is the facade's ongoing cost and its entire value — enforce it in CI.

### Android app (`Android-app` repo — separate PR, separate release)

6. **Re-point everything to `/api/mobile`:** the ~70 Retrofit endpoints (`data/api/*.kt`), the SSE
   path in `ShardStreamClient.kt`, and the SSO start/exchange URLs in `SsoAuthManager.kt`. Drop the
   `api/v1/` and `auth/mobile/` prefixes; the app now knows only `/api/mobile`.
7. **Add the app-version header + a server-side min-version floor** (the mechanism the blast-radius
   section calls for). Its first job is to sunset the *pre-facade* app so `/api/v1` can eventually be
   deleted; thereafter it is insurance for any genuinely breaking `/api/mobile` change (negotiated
   in-band, since URL-path versioning is deliberately gone here).
8. **Ship and let the fleet adopt** before starting v2. The old app keeps working on frozen `/api/v1`
   until the version floor ages it out.

### Docs / spec

9. Document `/api/mobile` as its own tagged surface in Swagger; record the facade + the version-floor
   mechanism in `docs/android/PLAN.md`, and note the app-contract change in the Android repo's docs.

**Not in scope for Phase 0:** any behavior change, any auth-model change, any v2 route. The facade
maps 1:1 onto today's controllers; the auth merge happens later and reaches the app only as an
internal re-point behind the unchanged `/api/mobile` shapes.

---

## Phase 1 — The auth merge (cookie removal)

### Server

1. **Promote the mobile flow to the mainline v2 auth routes.** Under `/api/v2/auth`:
   - `POST /login` → password (+ TOTP) → returns `{ accessToken, refreshToken, user }` (no `Set-Cookie`).
   - `POST /refresh` → rotate: validate + revoke presented refresh, mint a new pair.
   - `POST /logout` → revoke the current refresh/session server-side.
   - `POST /login/totp` → second-factor step, same token shape.
   The `/auth/mobile/*` namespace is **not** carried into v2 — it collapses into these.
2. **Delete the session-cookie code path in v2 controllers.** Stop calling `setAuthCookie` /
   `clearAuthCookie`. `extractToken` keeps its Bearer branch; the cookie branch is dead for v2
   routes (v1 keeps it until v1 is removed).
3. **Separate *session* cookies from *transaction* cookies — the latter stay.** The SSO / email-
   connect redirect flow (`sso.controller.js`, `emailConfig.controller.js`) *must* keep its
   short-lived httpOnly tx / PKCE-verifier / pending-TOTP cookies: the browser leaves for the IdP
   and returns with no JS context to carry a bearer across the hop. Only the **final session**
   handoff changes — the callback ends by issuing bearer tokens (redirect with a one-time code the
   SPA exchanges, so tokens never land in the URL) instead of setting `rg_token`.
4. **Trusted-device token** already supports the `X-Trust-Token` header for native clients
   (`extractTrustToken`). Web switches to the same header + client storage; `rg_trust` cookie is
   dropped for v2.
5. **SSE auth is per-channel — the public stream stays anonymous.** The **admin** shard stream
   (today gated by the session cookie via `isLoggedIn`) moves to `requireAuth` on the Bearer header,
   since its browser client becomes fetch-based (below). The **public** shard stream
   (`/public/shard/stream`) has **no auth middleware today and must keep none** — it is consumed by
   logged-out browser visitors *and* by the Android `ShardStreamClient`, neither of which sends an
   `Authorization` header. Adding `requireAuth` to it would black out the public live boards on web
   and mobile. Keep the public/admin allowlist split — that security boundary is unchanged.

### Client

6. **`api/client.js`:** drop `credentials: 'include'`; attach `Authorization: Bearer <access>`;
   on `401`, silent-refresh once via `/auth/refresh`, retry, else bounce to login.
7. **Token storage:** access token in memory (JS var/context); refresh token in `localStorage`.
   Short access TTL keeps the XSS window small — the accepted tradeoff for losing httpOnly.
8. **`lib/useShardFeed.js`:** only the **admin** stream needs the rewrite — replace
   `EventSource(adminShardStreamUrl, { withCredentials: true })` with a `fetch()` + `ReadableStream`
   reader that sends the Bearer header, parses SSE frames, and adds reconnect/backoff +
   access-token refresh-on-401. The **public** stream stays on `EventSource` (no credentials, so
   nothing to change) and keeps its free auto-reconnect. Do not convert both blindly.

### Docs / spec (required, same PR)

9. Update `BACKEND_DESIGN.md` auth section (cookie → bearer-everywhere; tx-cookie exception).
10. Regenerate Swagger (`npm run swagger`) — v2 auth routes, `Authorization` security scheme,
    remove `Set-Cookie` from documented responses.

---

## Phase 1b — CSP hardening (ships with the auth merge)

Once httpOnly is gone the access token lives in JS, so CSP's job becomes: **injected script can't
run, and if it somehow runs it can't phone home.** The app already ships a tuned policy
(`server/src/app.js`); v2 tightens it rather than rewriting it.

Two directives are load-bearing for the token-theft threat and must stay tight:

- `script-src 'self'` — no `'unsafe-inline'` / `'unsafe-eval'`. Primary defense; guard it.
- `connect-src 'self'` — the exfiltration channel. Do **not** widen it (e.g. to a separate API host)
  unless the API genuinely becomes cross-origin; the SPA + REST + fetch-SSE are all same-origin here.

`style-src 'unsafe-inline'` stays — it permits inline styling, not script execution, and React's
pervasive `style={{…}}` attributes can't be nonce'd. It is not a meaningful hole.

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';
```

Changes vs. the current policy:

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

Tracked follow-ups (own PRs, not blocking the merge):

- **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** — roll out `require-trusted-types-for 'script'` + a `trusted-types` policy in
  **report-only** first; neutralizes most DOM-based XSS at the sink (the exact bug class that would
  steal a JS-held token). Audit `dangerouslySetInnerHTML` + the `sanitizeHtml` render path first.
- **Report-only rollout** — ship the tightened policy via `Content-Security-Policy-Report-Only` with
  `report-to` for one release, watch for violations, then flip to enforce.

Verify 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.)

---

## Phase 2 — The domain split

**Rule:** one router file = one business capability; the URL names the domain; related endpoints
live together regardless of HTTP method; no generic `admin.router.js` / `api.router.js` catch-alls.
Controllers are **already** domain-split — Phase 2 is mostly re-wiring the routes, not the logic.

Target tree (`router/v2/`):

```
router/v2/
  admin/
    dashboard.router.js     users.router.js       moderation.router.js
    content.router.js       wiki.router.js        shard.router.js
    settings.router.js      invites.router.js     bot-activity.router.js
  auth/
    login.router.js   sso.router.js   totp.router.js   session.router.js
  public/
    news.router.js    wiki.router.js  page.router.js   shard.router.js
  player/
    profile.router.js  appeals.router.js  shard.router.js
  internal/            (unchanged — stays on the unpublished port, never mounted publicly)
```

Steps:

11. Carve `admin.routes.js` (~100 routes) into the per-capability files above, each requiring its
    already-existing controller. A thin `admin/index.js` mounts them under `/admin`.
12. Split `public.routes.js` and `player.routes.js` the same way.
13. `v2.router.js` mounts the domain sub-routers; `api.router.js` mounts `/v1` (frozen) **and** `/v2`.
14. Keep `/internal` off the public listener exactly as v1 does (separate `internalApp.js` port).
15. Update `#swagger.*` annotations for every moved route, regenerate the spec, and update
    `PROJECT_TREE.md` + `BACKEND_DESIGN.md` route map.

---

## Sequencing & PR breakdown

**Phase 0 lands entirely before the v2 scaffold** — the app must be off `/api/v1`-direct and onto
`/api/mobile` (and the fleet adopting) before v2 behavior work begins.

1. **PR 0a — mobile facade (server):** mount `/api/mobile` in `api.router.js`; re-home the app's full
   endpoint surface as thin delegates to existing controllers (same middleware); add contract tests
   pinning the wire shapes; add v1-usage telemetry. No behavior change. See Phase 0.
2. **PR 0b — mobile migration (separate `Android-app` repo):** re-point the ~70 Retrofit endpoints,
   the `ShardStreamClient` SSE path, and the SSO start/exchange URLs to `/api/mobile`; add the
   app-version header + server-side min-version floor. Released and adopted on the app-store cadence
   before v2 starts. See `docs/android/PLAN.md`.
3. **PR 1 — v2 scaffold:** `router/v2/` skeleton, `v2.router.js`, mount `/v2` next to `/v1`. Empty
   but wired; no behavior change. Detailed in [API_V2_SKELETON.md](./API_V2_SKELETON.md).
4. **PR 2 — auth merge (server):** v2 bearer auth routes + SSO callback code-exchange + admin-SSE-on-
   Bearer + docs/swagger. **Re-point `/api/mobile`'s internals to the unified flow behind unchanged
   wire shapes** (contract tests must stay green) — the app sees nothing.
5. **PR 3 — auth merge (web client):** `client.js` bearer + silent-refresh; `useShardFeed.js` fetch
   stream for the **admin** stream only.
6. **PR 4…N — domain split:** one PR per admin capability (dashboard, users, moderation, content,
   wiki, shard, settings, …) to keep diffs reviewable; then public + player. Keep `/api/mobile`
   delegating correctly as controllers move; contract tests catch any shape drift.
7. **PR final — retire v1:** only once (a) the web client is fully on v2, **and** (b) telemetry shows
   no `/api/v1` traffic from the pre-facade app, i.e. the old fleet has aged past the version floor.
   Then delete `router/v1` and the dead cookie code in `token.js`. See § Cross-component blast radius.

Each PR: 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

The plan above is written as if the website is the whole world. It isn't. **Three independent
clients consume the site's HTTP/SSE API, and two of them live in separate repos on separate release
cadences.** Any change to a URL shape, an auth mechanism, or a namespace is a *contract* change, not
a local refactor — the same discipline the docs demand for the shard↔sidecar wire protocol applies
here. This section is the coordination map the per-repo work must respect.

### Who calls the site API

| Consumer | Repo (release cadence) | How it's pinned to v1 | Migration cost |
|---|---|---|---|
| Browser SPA | `website/client` (same repo, lockstep) | `BASE = /api/v1` in `client/src/api/client.js` | In-plan (Phase 1 client + Phase 2) |
| **Android app** | `Android-app` (separate repo, app-store cadence, un-updatable installs in the wild) | **~70 Retrofit endpoints hardcode `api/v1/…`** across `data/api/*.kt`; SSE path hardcoded in `ShardStreamClient.kt`; SSO in `SsoAuthManager.kt` | **Migrated once to the version-agnostic `/api/mobile` facade in Phase 0; thereafter decoupled from v2.** |
| Discord bot | `website/bot` (separate deploy, but env-configured) | `SITE_PUBLIC_URL` env → `/api/v1/public` (`announce`/`wiki` commands) | Trivial — repoint the env var once `/v2/public` exists; unaffected by the auth merge (anonymous public reads) |

Only the browser migrates in true lockstep. The bot is a one-line env change. **The Android app was
the load-bearing coupling — the `/api/mobile` facade (Phase 0) is what removes it from the critical
path so v2 can proceed freely.**

### Mobile (site ↔ Android) — decoupled by the Phase 0 facade

The facade turns the mobile problem from "the app must chase every version rename forever" into "the
app pins one stable namespace, migrated once." What remains to keep in view:

1. **The facade must be *complete* or the decoupling leaks.** The app uses mostly *shared* routes
   (`auth/me/*`, `public/*`, `player/*`, `admin/*`), not just the mobile-auth ones. Every endpoint in
   the app's inventory (below) must exist under `/api/mobile`, or the app still calls `/api/v1`
   directly and is not actually insulated. This is the single most important Phase 0 check.
2. **The one-time cutover is still fleet-gated — the facade doesn't erase that, it *contains* it.**
   The *pre-facade* installed app still calls `/api/v1/*`, and with no force-update it does so until
   its users update. So `/api/v1` stays alive until that old fleet ages out. The difference: this is
   now a **pure-rename** migration decoupled from v2 behavior, paid once, and closed out by the
   version floor (next point) rather than blocking the auth merge.
3. **The version floor is still needed — its role just changed.** Add an app-version header + a
   server-side min-version gate (Phase 0 step 7). Its *first* job is to sunset the pre-facade app so
   `/api/v1` can finally be deleted; *afterward* it is the in-band mechanism for any breaking
   `/api/mobile` change, since URL-path versioning is deliberately absent there. Without it there is
   still no safe way to force the last stragglers off v1.
4. **v1-usage telemetry** — per-route counts, tagged to distinguish the migrated browser from
   lingering pre-facade app installs, so "nothing calls v1" is measured, not assumed.
5. **`/api/mobile` is now a frozen wire contract** — contract tests (Phase 0 step 5) must guard its
   response shapes so a v2 internal refactor can't silently break installed apps. This replaces
   "don't break the app during the auth merge" with "the auth merge can't reach the app at all."
6. **The public/mobile SSE stream must stay anonymous** (Phase 0 step 4 / Phase 1 step 5) — the app's
   `ShardStreamClient` sends no auth header.
7. **Record the mobile side in `docs/android/PLAN.md`.** This plan owns the `/api/mobile` server
   contract + the facade; that plan owns the app migration + version-floor rollout.

### Shard (site ↔ link) — mostly *out* of the blast radius, with one seam to guard

The auth merge is a **website↔client** change; the **website↔sidecar** contract is orthogonal and
should not move:

- The sidecar's own bearer token lives in the DB (`uoLinkConfig`, write-only in the API), the
  server-side REST client (`utils/uoLinkClient.js`) and live ingest (`utils/shardIngest.js`) talk to
  the sidecar independent of any browser/mobile session, and `PROTOCOL_VERSION` / `X-UOLink-Version`
  are their own versioning axis. **None of that changes for v2** — `link/` needs no edit and
  `PROTOCOL_VERSION` does **not** bump for this work.
- **The one seam:** the *admin* SSE stream re-fans the sidecar's full feed (including sensitive kinds).
  When that endpoint moves to Bearer auth under v2, the public/admin allowlist split in the fan-out
  (`utils/shardBroadcast.js` / `shardIngest.js`) is the same security boundary it is today and must be
  preserved verbatim. This is a website-internal concern; it does not reach into `link/`.

### SSO transaction cookies are load-bearing for *both* web and native

Phase 1 step 3's carve-out (keep the short-lived httpOnly tx / PKCE-verifier / pending-TOTP cookies)
isn't only a web concern. The Android SSO flow opens a Custom Tab to the website's
`/auth/…/sso/start`, so it rides the **same** server-side redirect transaction and the **same** tx
cookies. The mobile side already ends in a code-exchange (`/auth/mobile/sso/exchange`) — which is the
exact pattern v2's web callback is adopting. So: don't let "cookies go away" delete the tx cookies, or
you break native SSO as well as web SSO.

### Contract-sync checklist (this is a multi-repo change)

A v2 endpoint or auth change is not "done" until every consumer's contract is reconciled:

- `docs/website/BACKEND_DESIGN.md` — route map + auth/security contract, incl. the `/api/mobile`
  facade as its own documented, version-agnostic surface with pinned response shapes.
- `server/swagger/swagger-output.json` — regenerated (tag `/api/mobile` separately from v1/v2).
- Facade contract tests — the frozen `/api/mobile` wire shapes; kept green across every v2 change.
- `docs/android/PLAN.md` — the `/api/mobile` migration milestone + the app-version-floor mechanism.
- The Android app's own endpoint constants + contract comments (`data/api/*.kt`,
  `ShardStreamClient.kt`, `SsoAuthManager.kt`) — re-pointed to `/api/mobile` in a separate
  `Android-app` PR.
- Bot: note the `SITE_PUBLIC_URL` repoint in `website/` deploy docs when `/v2/public` lands.

## Risks / watch-items

- **XSS is now token-theft.** Losing httpOnly means any XSS can read the access token. Mitigation:
  short access TTL + refresh rotation + revocation, paired with the Phase 1b CSP hardening.
- **SSO/email tx cookies cannot be removed** — don't let "cookies go away" over-reach into the
  redirect transaction. Only the session handoff changes.
- **SSE reconnect regressions** — `EventSource` gave auto-reconnect + `Last-Event-ID` for free; the
  fetch reader must reproduce backoff and (if used) event-id resume, plus refresh a stale token
  mid-stream.
- **Incomplete facade defeats the purpose** — if any endpoint the app needs is left only under
  `/api/v1`, the app still calls v1 directly and Phase 0's decoupling silently leaks. Reconcile the
  facade against the app's full endpoint inventory before shipping PR 0a.
- **The facade is a security surface, not an alias** — each `/api/mobile` route must carry the *same*
  auth middleware as the route it mirrors. A re-exposed admin route missing `adminOnly`, or the
  mobile SSE leaking sensitive kinds, is a privilege/data-exposure hole introduced by the facade.
- **Silent shape drift through the facade** — once `/api/mobile` internals re-point to v2, a v2
  response-shape change can break installed apps with no compile error. Contract tests on the facade
  are the guardrail; treat a failing one as a release blocker, not a test to update.
- **Double maintenance while v1 and v2 coexist** — bug fixes may need both. Keep the window short;
  drive the *web* client to v2 completion. The facade means the window is no longer bounded by app
  behavior — only by the pre-facade fleet aging out (see § Cross-component blast radius).
- **Public SSE must not become auth-gated** — the single most likely regression in Phase 1 is
  reflexively wrapping *both* shard streams in `requireAuth`. The public stream is anonymous by
  contract; doing so blacks out the public live boards for every logged-out browser and every phone.
- **v1 deletion is still fleet-gated (once)** — even with the facade, the *pre-facade* installed app
  calls `/api/v1` until the version floor ages it out. The facade contains this to a one-time,
  behavior-free cutover done *before* v2; it does not make v1 deletable on the web client's schedule.
- **`link/` is not in scope but is adjacent** — resist bumping `PROTOCOL_VERSION` or touching the
  sidecar client for v2 work; the only shared seam is preserving the admin-stream allowlist split.