docs(website): finalize the API plan — in-place router split, no /api/v2
The API v2 plan is revised down to the work that is actually justified: a CSP hardening pass and an in-place domain split of the monolithic route wiring. - Auth merge (httpOnly cookies -> bearer + rotating refresh for every client) is removed and re-filed as deferred behind trigger conditions. httpOnly+SameSite is the stronger model, session.service.js already unifies cookie and bearer, the SSO/PKCE transaction cookies survive any merge, and it dragged the admin SSE fetch/ReadableStream rewrite along as a dependency for no user-visible payoff. A revival must first spec refresh-token reuse detection and a rollback procedure. - No parallel /api/v2. The URL surface is already grouped by capability, so each new router file mounts at the prefix it already owns and every URL stays byte-identical. No dual mount, no per-route migration, no v1 retirement; the SPA, Discord bot, and Android app are all untouched. API_V2_SKELETON.md is marked superseded (kept as the recipe if a versioned API is ever forced). - The /api/mobile facade and app-version floor are deferred with the revival note that it starts as a one-line alias mount, not ~70 hand-written delegates. The M11 milestone is dropped from android/PLAN.md. - Adds PR 0: a generated route manifest, so "every URL is unchanged" is proved by a zero-line diff rather than asserted in review. The baseline api-route-inventory.json (199 API routes + 2 internal) is committed here and is what PR 0's generator must reproduce byte-for-byte. - Split sequenced as five grouped PRs; CSP fixed to report-only first, then enforce (the old plan contradicted itself), with the verified delta being just form-action 'self' and frame-ancestors 'none'. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -1,159 +1,170 @@
|
||||
# Website API v2 — Plan
|
||||
# Website API — router domain split + CSP hardening
|
||||
|
||||
Status: **planning** · Target repo: `website/` · Docs owner: this file + `BACKEND_DESIGN.md`
|
||||
|
||||
v2 is three sequenced pieces of work, landed in order:
|
||||
> **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](./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.
|
||||
|
||||
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
|
||||
## Why the auth merge is out
|
||||
|
||||
| Decision | Choice | Consequence |
|
||||
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`](./api-route-inventory.json).
|
||||
|
||||
| Group | Routes | Second segment → capability |
|
||||
|---|---|---|
|
||||
| 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. |
|
||||
| `/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 |
|
||||
|
||||
## What already exists (so we don't rebuild it)
|
||||
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.
|
||||
|
||||
- `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.)
|
||||
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](./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.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — The mobile facade (`/api/mobile`, lands before v2)
|
||||
## Deferred: the `/api/mobile` facade and the app-version floor
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
**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.
|
||||
**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.
|
||||
|
||||
### Server
|
||||
**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.
|
||||
|
||||
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.
|
||||
**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):
|
||||
|
||||
### 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.
|
||||
- **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 — The auth merge (cookie removal)
|
||||
## Phase 1 — CSP hardening (independent)
|
||||
|
||||
### Server
|
||||
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.
|
||||
|
||||
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.
|
||||
**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.
|
||||
|
||||
### Client
|
||||
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:
|
||||
|
||||
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.
|
||||
- `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. It is not a meaningful hole.
|
||||
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:
|
||||
|
||||
@@ -170,209 +181,189 @@ form-action 'self';
|
||||
frame-ancestors 'none';
|
||||
```
|
||||
|
||||
Changes vs. the current policy:
|
||||
Delta vs. the policy in `server/src/app.js` today — the whole change is two directives:
|
||||
|
||||
- **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:`).
|
||||
- **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:`).
|
||||
|
||||
Tracked follow-ups (own PRs, not blocking the merge):
|
||||
**Rollout:** ship via `Content-Security-Policy-Report-Only` with `report-to` for one release, watch for
|
||||
violations, then flip to enforce.
|
||||
|
||||
- **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.
|
||||
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.)
|
||||
|
||||
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.)
|
||||
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
|
||||
|
||||
**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.
|
||||
**This is the reason the plan exists.** Everything else is supporting work.
|
||||
|
||||
Target tree (`router/v2/`):
|
||||
**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/v2/
|
||||
router/v1/
|
||||
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
|
||||
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 sso.router.js totp.router.js session.router.js
|
||||
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 wiki.router.js page.router.js shard.router.js
|
||||
news.router.js (posts) pages.router.js wiki.router.js shard.router.js
|
||||
site.router.js # status, settings, version, contact
|
||||
player/
|
||||
profile.router.js appeals.router.js shard.router.js
|
||||
account.router.js shard.router.js appeals.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.
|
||||
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)
|
||||
|
||||
"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`](./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
|
||||
|
||||
**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.
|
||||
CSP and the split are independent; the only hard ordering is PR 0 before the first split PR.
|
||||
|
||||
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.
|
||||
1. **PR — CSP report-only.** Tightened policy behind `Content-Security-Policy-Report-Only` + `report-to`.
|
||||
2. **PR — CSP enforce.** One release later, assuming a clean violation report.
|
||||
3. **PR 0 — route manifest.** Generator + CI check + committed baseline of today's surface. No routers moved.
|
||||
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: server tests green (`cd website/server && npm test`), Swagger regenerated, matching `docs/`
|
||||
edit, Conventional Commit, AI-disclosure trailer, branch from a freshly-pulled `main`.
|
||||
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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### Who calls the site API
|
||||
|
||||
| Consumer | Repo (release cadence) | How it's pinned to v1 | Migration cost |
|
||||
| Consumer | Repo (cadence) | Pinning | Impact under this plan |
|
||||
|---|---|---|---|
|
||||
| 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) |
|
||||
| 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. |
|
||||
|
||||
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.**
|
||||
Standing constraints, unchanged:
|
||||
|
||||
### Mobile (site ↔ Android) — decoupled by the Phase 0 facade
|
||||
- **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.
|
||||
|
||||
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.
|
||||
## Appendix: mapping from the previous plan
|
||||
|
||||
### 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.
|
||||
| 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](./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 |
|
||||
|
||||
Reference in New Issue
Block a user