docs(website): correct the CSP delta to one directive and document the report sink
Companion to website "feat(security): soak the tightened CSP on report-only".
The plan's Phase 1 claimed a two-directive delta, one of which was adding
`form-action 'self'` as "currently absent". It was not absent. The directives
object in app.js does not list it, but the middleware runs `useDefaults: true`
and helmet's default set already supplies it, so production has been serving it
all along. The plan was written from the config rather than from the live
header; the correction, and how it was caught, are now recorded in place rather
than quietly fixed.
That leaves `frame-ancestors 'self'` -> `'none'` as the entire behavioural delta
of the phase. Worth noting that this is also the directive that most justifies a
soak: a frame-ancestors violation is reported by the browser of whoever framed
the site, so it is the only available way to discover a legitimate embed before
an enforcing policy breaks it.
Also documented:
* POST /api/csp-report -- the same-origin sink report-to/report-uri point at,
why it is same-origin, why it lives outside /api/v1, both wire formats, the
Reporting-Endpoints header requirement, and the properties that make an
unauthenticated public POST safe (always-204, caps, truncation, rate limit).
* That the sink is scoped to the soak, so the enforce PR must decide
explicitly whether to retire it or keep a report-to group on the enforced
policy -- rather than leaving an orphan route behind.
* The `[csp]` log tag in section 7.5 as the thing to watch during the soak,
and what silence across one release means.
* client/vite.config.js already sets `modulePreload: { polyfill: false }`, so
the plan's inline-polyfill prerequisite was already satisfied.
api-route-inventory.json moves 199 -> 200 for the new route. That is the PR 0
freeze working as intended: the first manifest diff since the baseline is a
deliberate, reviewed one.
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -270,7 +270,7 @@ are authoritative, and they answer different questions:
|
||||
|
||||
| Artifact | Source of truth for | Generated by |
|
||||
|---|---|---|
|
||||
| `server/routes.manifest.json` — mirrored as [api-route-inventory.json](./api-route-inventory.json) | **What URLs exist.** 199 public routes + 2 on the internal listener, sorted, method + path only. | `npm run routes:manifest`, by walking the live Express stack |
|
||||
| `server/routes.manifest.json` — mirrored as [api-route-inventory.json](./api-route-inventory.json) | **What URLs exist.** 200 public routes + 2 on the internal listener, sorted, method + path only. | `npm run routes:manifest`, by walking the live Express stack |
|
||||
| `server/swagger/swagger-output.json` — served at `/api/docs` | **What each route means.** Parameters, bodies, response codes, security. | `npm run swagger`, from `#swagger.*` annotations |
|
||||
|
||||
The split is deliberate: Swagger is annotation-derived, so an unannotated route is invisible in it and
|
||||
@@ -490,7 +490,8 @@ who"; `activity_log` provides the history feed.
|
||||
- **bcrypt** hashing (cost 10+); plaintext passwords never stored, logged, or returned.
|
||||
- **Rate limiting** (`express-rate-limit`) on `/auth/login` and `/public/contact`.
|
||||
- **Validation** (`express-validator`) on all writes; centralized error handler.
|
||||
- **helmet** with a Content-Security-Policy tuned for the built React SPA (see `server/src/app.js`):
|
||||
- **helmet** with a Content-Security-Policy tuned for the built React SPA. The policies now live in
|
||||
**`server/src/config/csp.js`** (`app.js` only wires them up):
|
||||
`default-src 'self'`; `script-src 'self'` (the Vite build emits only external module chunks — the
|
||||
inline module-preload polyfill is disabled in `client/vite.config.js` to keep this valid);
|
||||
`style-src 'self' 'unsafe-inline' https://fonts.googleapis.com` (React's pervasive inline
|
||||
@@ -498,11 +499,33 @@ who"; `activity_log` provides the history feed.
|
||||
https://fonts.gstatic.com` (Cinzel); `img-src 'self' data: https:` (same-origin uploads, plus
|
||||
external https images embedded in wiki/news bodies or `BRAND_*` logo/hero/favicon); `connect-src
|
||||
'self'` (REST + SSE are same-origin); `frame-ancestors 'self'`; `object-src 'none'`; `base-uri
|
||||
'self'`. `upgrade-insecure-requests` is intentionally **not** set (TLS terminates at the proxy, there
|
||||
'self'`; `form-action 'self'` (blocks an injected `<form action="https://evil">` from POSTing
|
||||
credentials off-origin — an exfil path `connect-src` does not cover; it was always emitted via
|
||||
helmet's `useDefaults` and is now pinned explicitly so it cannot vanish under a helmet upgrade).
|
||||
`upgrade-insecure-requests` is intentionally **not** set (TLS terminates at the proxy, there
|
||||
are no mixed-content subresources, and it would break a local `npm start` over plain http). The
|
||||
`/api/docs` Swagger UI route gets a **looser** policy that additionally allows inline script/style,
|
||||
since swagger-ui-express injects an inline bootstrap. helmet also strips `X-Powered-By`; the two
|
||||
internal-only listeners (`internalApp.js`, `bot/src/app.js`) disable it explicitly too.
|
||||
- **A second, tightened policy ships alongside on `Content-Security-Policy-Report-Only`** for one
|
||||
release before it replaces the enforced one (`docs/website/API_V2_PLAN.md` § Phase 1). It is derived
|
||||
from the enforced policy so the two cannot drift, and differs by exactly one directive:
|
||||
`frame-ancestors 'self'` → **`'none'`**. Serving both headers at once means the live policy keeps
|
||||
protecting users while anything the tightened version would break arrives as a report rather than as
|
||||
a broken page — and for `frame-ancestors` specifically, a report from the browser of whoever framed
|
||||
the site is the only way to learn that something does.
|
||||
- **`POST /api/csp-report`** is the same-origin violation sink that `report-to` / `report-uri` point at
|
||||
(`report-to` additionally requires the `Reporting-Endpoints` response header, which is set alongside).
|
||||
Same-origin on purpose: reports describe attacks against this site and are not handed to a
|
||||
third-party collector. It parses **both** wire formats (`application/csp-report` from Firefox/Safari,
|
||||
`application/reports+json` from Chrome's Reporting API — handling one drops half the browsers),
|
||||
writes to the `csp` log tag and **stores nothing**. Necessarily unauthenticated (browsers send
|
||||
reports with no session), so it is bounded on every axis: 16 KB body cap, per-IP rate limit, fixed
|
||||
field allowlist, every logged field truncated, and **always 204 — even for malformed input**, since a
|
||||
4xx would make the global error handler log the attacker-supplied body and turn an open endpoint into
|
||||
a log-flood primitive. Mounted outside `/api/v1` next to `/api/health`: the browser learns the path
|
||||
from the policy header, never from a client build, so it is not part of the versioned client
|
||||
contract.
|
||||
- **Admin not indexed**: `X-Robots-Tag: noindex, nofollow` on `/api/v1/admin` and the admin SPA routes; `robots.txt` disallows `/admin`.
|
||||
- **No directory browsing** (express.static doesn't list; no `serve-index`).
|
||||
- **No hardcoded credentials**: first admin via `seed.js` reading `ADMIN_USERNAME`/`ADMIN_PASSWORD` from env (created only if no users exist); `.env` git-ignored, `.env.example` committed.
|
||||
@@ -527,7 +550,11 @@ instead. Errors never leak credentials.
|
||||
|
||||
`utils/logger.js` — a small dependency-free logger with **two transports, console + file**,
|
||||
and four levels (`error`/`warn`/`info`/`debug`). Each line is timestamped and tagged by
|
||||
subsystem (`[server]`, `[http]`, `[db]`, `[auth]`, `[admin]`, `[ratelimit]`, …).
|
||||
subsystem (`[server]`, `[http]`, `[db]`, `[auth]`, `[admin]`, `[ratelimit]`, `[csp]`, …).
|
||||
|
||||
> During the CSP report-only soak, `[csp]` is the tag to watch: a `csp violation` warn line with
|
||||
> `directive: frame-ancestors` means something really does frame the site and the enforce PR would
|
||||
> break it. Silence across one release is the green light to flip.
|
||||
|
||||
- **Console**: color on a TTY, plain in Docker; verbosity = `LOG_LEVEL` (default `info`).
|
||||
- **File**: plain text appended to `LOG_DIR/LOG_FILE` (default `<server>/logs/app.log`,
|
||||
|
||||
Reference in New Issue
Block a user