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/auth/auth.controller.spec.ts

@@ -55,6 +55,7 @@ interface SessionStub {
   user?: AuthenticatedUser;
   createdAt?: number;
   absoluteExpiresAt?: number;
+  csrfToken?: string;
   save: jest.Mock;
   destroy: jest.Mock;
 }
@@ -261,6 +262,34 @@ describe('AuthController.callback', () => {
     }
   });
 
+  it('mints a CSRF token, writes it to the session, and mirrors it to the JS-readable cookie', async () => {
+    const { controller } = makeController();
+    const res = makeResStub();
+    const session = makeSessionStub();
+    const req = makeReqStub({
+      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+      session,
+    });
+
+    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+
+    // Server-side source of truth lives on the session.
+    expect(typeof session.csrfToken).toBe('string');
+    expect((session.csrfToken as string).length).toBeGreaterThan(20);
+
+    // Cookie mirror — name picked from sessionCookieName's twin
+    // (NODE_ENV-conditional). In the test default (development),
+    // it's the unprefixed variant.
+    const csrfCookieCall = res.cookie.mock.calls.find(
+      (c) => c[0] === 'portal_csrf' || c[0] === '__Host-portal_csrf',
+    );
+    expect(csrfCookieCall).toBeDefined();
+    expect(csrfCookieCall?.[1]).toBe(session.csrfToken);
+    // Must NOT be HttpOnly — the SPA reads it to echo back via the
+    // X-CSRF-Token header.
+    expect(csrfCookieCall?.[2]).toMatchObject({ httpOnly: false });
+  });
+
   it('registers the new session in the user_sessions index after save', async () => {
     const { controller, userSessionIndex } = makeController();
     const res = makeResStub();
@@ -501,6 +530,7 @@ describe('AuthController.logout', () => {
     });
     expect(session.destroy).toHaveBeenCalledTimes(1);
     expect(res.clearCookie).toHaveBeenCalledWith('portal_session', { path: '/' });
+    expect(res.clearCookie).toHaveBeenCalledWith('portal_csrf', { path: '/' });
     expect(logger.log).toHaveBeenCalledWith(
       { event: 'auth.signed_out', wasAuthenticated: true },
       'AuthLogout',

apps/portal-bff/src/auth/auth.controller.ts

@@ -1,7 +1,9 @@
+import { randomBytes } from 'node:crypto';
 import { Controller, Get, Inject, Query, Req, Res } from '@nestjs/common';
 import type { Request, Response } from 'express';
 import { Logger } from 'nestjs-pino';
 import { AuditWriter } from '../audit/audit.service';
+import { csrfCookieName, csrfCookieOptions } from '../security/csrf-cookie';
 import { readSessionTimeouts, sessionCookieName } from '../session/session-cookie';
 import { UserSessionIndexService } from '../session/user-session-index.service';
 import {
@@ -117,19 +119,30 @@ export class AuthController {
     try {
       const user = await this.authService.completeAuthCodeFlow(code, state, preAuth);
       const now = Date.now();
-      const { absoluteSeconds } = readSessionTimeouts();
+      const { idleSeconds, absoluteSeconds } = readSessionTimeouts();
+      const csrfToken = randomBytes(32).toString('base64url');
       req.session.user = user;
       req.session.createdAt = now;
       // Hard ceiling per ADR-0010 §"TTL policy" — checked on every
       // request by the absolute-timeout middleware, independent of
       // idle TTL.
       req.session.absoluteExpiresAt = now + absoluteSeconds * 1000;
+      // CSRF token per ADR-0009 §"Double-submit CSRF". Server-side
+      // source of truth lives on the session; the cookie below is
+      // the SPA's read-only mirror used to echo the value in the
+      // X-CSRF-Token header.
+      req.session.csrfToken = csrfToken;
       // Force the save before the redirect: express-session writes
       // on response end, but the 302 we're about to emit closes the
       // response before the async store-write would otherwise
       // complete. Without this, the browser hits the SPA before
       // Redis carries the new payload.
       await saveSession(req);
+      // Mirror the CSRF token to a JS-readable cookie. maxAge
+      // matches the session's idle TTL so the cookie expires at
+      // the same time as the session (rolling, refreshed on each
+      // request alongside express-session's own cookie).
+      res.cookie(csrfCookieName(), csrfToken, csrfCookieOptions(idleSeconds * 1000));
       // Register the freshly-minted session id in the per-user
       // index so a future admin "logout everywhere" can enumerate
       // and revoke. Best-effort: a Redis hiccup here doesn't fail
@@ -232,6 +245,7 @@ export class AuthController {
     }
 
     res.clearCookie(sessionCookieName(), { path: '/' });
+    res.clearCookie(csrfCookieName(), { path: '/' });
     this.logger.log({ event: 'auth.signed_out', wasAuthenticated }, 'AuthLogout');
     res.redirect(302, logoutUrl);
   }