feat(portal-bff): helmet + env-driven CORS allowlist + double-submit CSRF (#122)

## Summary

Phase-2 security baseline that the `main.ts` placeholder note has been advertising since the auth/session work began. Three independent middlewares + their SPA counterparts, all mounted in a single PR because they only become meaningful together.

### Helmet on the BFF

`helmet()` with three overrides matching our specific shape:

- **HSTS only in production** — dev runs on plain HTTP, HSTS is just noise.
- **`crossOriginResourcePolicy: 'cross-origin'`** — the SPA on its own origin reads JSON from the BFF; the default `same-origin` would block it.
- **CSP disabled in non-production** — the BFF doesn't render HTML, so CSP on JSON responses is mostly inert, but Helmet's default CSP triggers noisy `connect-src` violations in browser devtools that we don't need.

Everything else is Helmet defaults: `X-Frame-Options=SAMEORIGIN`, `X-Content-Type-Options=nosniff`, `Referrer-Policy=no-referrer`, `X-Powered-By` removed, etc.

### CORS allowlist, env-driven

`CORS_ALLOWED_ORIGINS` env (comma-separated) is now **mandatory** at boot. The BFF refuses to start without it via `readCorsAllowlist()` — same boot-time validator family as `assertSessionSecret` etc. The previous hardcoded `http://localhost:4200` fallback is gone; getting CORS wrong silently is the kind of "works in dev, breaks in prod" trap the validator is specifically designed to catch. `X-CSRF-Token` is now in the allowed headers.

### Double-submit CSRF

- BFF mints a 256-bit `csrfToken` at session creation (`/auth/callback`), stored on `req.session.csrfToken` and mirrored to a JS-readable cookie (`__Host-portal_csrf` prod / `portal_csrf` dev). The cookie is the SPA's read-only view; the server-side session is the source of truth.
- `createCsrfMiddleware` (mounted after the session middleware in `main.ts`) compares the `X-CSRF-Token` header with `req.session.csrfToken` using `crypto.timingSafeEqual`. Skips:
  - safe methods (`GET / HEAD / OPTIONS`),
  - anonymous requests (no `req.session.user`),
  - `/api/auth/login` and `/api/auth/callback` (those mint the token themselves).
- Mismatch → `403 {"error":"csrf"}` with a structured Pino warn.
- SPA's `csrfInterceptor` reads the cookie via `document.cookie` and copies its value into `X-CSRF-Token` on every mutating BFF request. The header is omitted on `GET / HEAD / OPTIONS` (BFF skips them anyway) and on non-BFF origins.
- Logout and the absolute-timeout middleware both clear the CSRF cookie alongside the session cookie.

## Notable choices

**Session-bound double-submit, not pure cookie-vs-header.** A naive "compare cookie with header" check is defeated when an attacker can plant a cookie (subdomain takeover, etc.). Comparing the header to the server-side session-stored token instead means the attacker would also need to be the authenticated user — which is what CSRF defense is supposed to prevent in the first place.

**No CSRF for anonymous mutating routes (v1).** None exist today; we don't have an unauthenticated POST endpoint anywhere. Generating a CSRF token for anonymous sessions would conflict with `saveUninitialized: false` on express-session and add complexity we don't need yet. Anonymous public-form CSRF defenses (site-key, captcha) land if and when those routes ship.

**`SameSite=Lax`, not `Strict`, on the CSRF cookie.** Matches the session cookie's policy so the two travel together on the SPA→BFF cross-origin same-site fetch (different ports = different origin, same registrable domain). The double-submit pattern is what gives the protection; `SameSite=Lax` is a belt-and-braces layer.

**`csrfInterceptor` runs after `bffCredentialsInterceptor` and before `bffUnauthorizedInterceptor` in the chain.** Order: credentials first (set `withCredentials`), then CSRF (set the header), then unauthorized handling (catch 401s). Forward order, no surprises.

**`CORS_ALLOWED_ORIGINS` has no localhost fallback.** I considered keeping the fallback for ergonomics but it makes the BFF silently misconfigured if someone forgets the env. The error message points straight at the file to edit.

## Out of scope (next PRs)

- Rate limiting + structured error filter (still in the phase-2 to-do).
- CSP fine-tuning when we have actual HTML pages (portal-shell + portal-admin static serving).
- CSRF token rotation on idle-extension (today the token lives the session's lifetime; refreshing on each request would invalidate in-flight mutations).

## Test plan

- [x] `pnpm nx run-many -t test --projects=portal-bff,feature-auth,portal-shell` clean env → **177 + 28 + 34 = 239/239 pass** (was 144 + 19 + 34 = 197 before; +42 specs across CSRF middleware, CSRF cookie helpers, CORS allowlist parser, csrfInterceptor, and extended auth.controller / absolute-timeout coverage).
- [x] `pnpm nx run-many -t lint build --projects=portal-bff,feature-auth,portal-shell` → clean.
- [x] **CI clean-env repro** (lesson from prior PRs): every env var unset (including new `CORS_ALLOWED_ORIGINS`) → tests still pass. The BFF refuses to boot without `CORS_ALLOWED_ORIGINS`, which is the intended behaviour.
- [x] Prettier-clean.
- [ ] Manual smoke against running BFF:
  - [ ] Sign in → `__Host-portal_csrf` (prod) / `portal_csrf` (dev) cookie set, value matches `audit.events.payload->>actorIdHash`-style traceability via `req.session.csrfToken` in Redis.
  - [ ] Hit a future POST route from the SPA → request carries `X-CSRF-Token`, BFF accepts.
  - [ ] Forge a POST without the header (curl) → 403 `{"error":"csrf"}`.
  - [ ] Sign out → both cookies cleared.

---------

Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #122

apps/portal-bff/src/main.ts

@@ -6,14 +6,17 @@ import './observability/tracing';
 import { ValidationPipe } from '@nestjs/common';
 import { NestFactory } from '@nestjs/core';
 import cookieParser from 'cookie-parser';
+import helmet from 'helmet';
 import { Logger } from 'nestjs-pino';
 import { AppModule } from './app/app.module';
+import { readCorsAllowlist } from './config/check-cors-allowlist';
 import { assertDatabaseUrl } from './config/check-database-url';
 import { assertEntraConfig } from './config/check-entra-config';
 import { assertRedisConfig } from './config/check-redis-config';
 import { assertLogUserIdSalt } from './config/check-log-user-id-salt';
 import { assertSessionEncryptionKey } from './config/check-session-encryption-key';
 import { assertSessionSecret } from './config/check-session-secret';
+import { CSRF_MIDDLEWARE } from './security/security.token';
 import {
   SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE,
   SESSION_MIDDLEWARE,
@@ -57,21 +60,43 @@ async function bootstrap() {
   const app = await NestFactory.create(AppModule, { bufferLogs: true });
   app.useLogger(app.get(Logger));
 
-  // CORS — minimal dev-time allowlist. The SPA running on
-  // http://localhost:4200 issues fetches to the BFF and must be
-  // able to send the W3C `traceparent` (and `tracestate`) headers
-  // that `@opentelemetry/instrumentation-fetch` injects, so the BFF
-  // can pick up the parent span id and emit child spans on the same
-  // trace. The full security-grade allowlist (per-environment
-  // origins, credentials policy, helmet stack, etc.) lands with the
-  // phase-2 security ADR — for now this is the minimum needed for
-  // end-to-end tracing.
+  // Security headers (phase-2). Defaults from `helmet()` are good
+  // for an API server returning JSON: X-Frame-Options=SAMEORIGIN,
+  // X-Content-Type-Options=nosniff, Referrer-Policy=no-referrer,
+  // X-Powered-By removed, etc. CSP defaults apply too but the BFF
+  // doesn't render HTML, so they're inert here.
+  //
+  // Three overrides for our specific shape:
+  //   - HSTS only in production (dev runs on plain HTTP).
+  //   - crossOriginResourcePolicy: 'cross-origin' so the SPA on its
+  //     own origin can read JSON from the BFF without being blocked
+  //     by Spectre-class CORP protections.
+  //   - contentSecurityPolicy: false in dev — Helmet's default CSP
+  //     blocks `connect-src` from anything but 'self', which is
+  //     fine for HTML pages but irrelevant for JSON responses and
+  //     noisy in browser devtools.
+  app.use(
+    helmet({
+      hsts: process.env['NODE_ENV'] === 'production',
+      crossOriginResourcePolicy: { policy: 'cross-origin' },
+      contentSecurityPolicy: process.env['NODE_ENV'] === 'production',
+    }),
+  );
+
+  // CORS allowlist — env-driven via `CORS_ALLOWED_ORIGINS`, parsed
+  // and validated at boot. No hardcoded localhost fallback: getting
+  // CORS wrong silently is exactly the kind of "works in dev, breaks
+  // in prod" issue this validator is meant to catch.
   app.enableCors({
-    origin: (process.env['CORS_ALLOWED_ORIGINS'] ?? 'http://localhost:4200')
-      .split(',')
-      .map((o) => o.trim())
-      .filter(Boolean),
-    allowedHeaders: ['Content-Type', 'Accept', 'Authorization', 'traceparent', 'tracestate'],
+    origin: [...readCorsAllowlist()],
+    allowedHeaders: [
+      'Content-Type',
+      'Accept',
+      'Authorization',
+      'X-CSRF-Token',
+      'traceparent',
+      'tracestate',
+    ],
     credentials: true,
   });
 
@@ -104,9 +129,17 @@ async function bootstrap() {
   // needed).
   app.use(app.get<RequestHandler>(SESSION_ABSOLUTE_TIMEOUT_MIDDLEWARE));
 
-  // Phase-2 security ADRs will harden the above: helmet, real CORS
-  // allowlist, CSRF protection, rate limiting, auth guards,
-  // structured error filter.
+  // Double-submit CSRF (ADR-0009 §"CSRF defense"). Mounted after
+  // the session middleware so `req.session.csrfToken` is available
+  // for comparison with the `X-CSRF-Token` request header. Skips
+  // safe methods (GET / HEAD / OPTIONS), anonymous requests, and
+  // the auth entry routes that *mint* the token (`/auth/login`,
+  // `/auth/callback`).
+  app.use(app.get<RequestHandler>(CSRF_MIDDLEWARE));
+
+  // Phase-2 hardening still pending: rate limiting + structured
+  // error filter (helmet, CORS allowlist, CSRF protection landed
+  // with this PR).
 
   const globalPrefix = 'api';
   app.setGlobalPrefix(globalPrefix);