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
2026-05-13 20:50:44 +02:00
parent a97be121e6
commit 5bbe2304ff
24 changed files with 902 additions and 23 deletions
@@ -1,6 +1,7 @@
-export { AUTH_BFF_BASE_URL, AUTH_NAVIGATOR } from './lib/auth.config';
+export { AUTH_BFF_BASE_URL, AUTH_CSRF_COOKIE_NAME, AUTH_NAVIGATOR } from './lib/auth.config';
 export { authGuard } from './lib/auth.guard';
 export { AuthService } from './lib/auth.service';
 export type { AuthState, CurrentUser } from './lib/auth.types';
 export { bffCredentialsInterceptor } from './lib/bff-credentials.interceptor';
 export { bffUnauthorizedInterceptor } from './lib/bff-unauthorized.interceptor';
+export { csrfInterceptor } from './lib/csrf.interceptor';
@@ -26,3 +26,12 @@ export const AUTH_NAVIGATOR = new InjectionToken<(url: string) => void>('AUTH_NA
  providedIn: 'root',
  factory: () => (url: string) => window.location.assign(url),
 });
+
+/**
+ * Name of the BFF's CSRF cookie that the `csrfInterceptor` reads
+ * to echo back in the `X-CSRF-Token` header. Provided by the host
+ * from its per-environment config (`environment.bffCsrfCookieName`)
+ * so the lib doesn't have to know the env-conditional naming
+ * (`portal_csrf` dev / `__Host-portal_csrf` prod) the BFF picks.
+ */
+export const AUTH_CSRF_COOKIE_NAME = new InjectionToken<string>('AUTH_CSRF_COOKIE_NAME');
@@ -0,0 +1,115 @@
+import { HttpClient, provideHttpClient, withInterceptors } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+import { TestBed } from '@angular/core/testing';
+import { AUTH_BFF_BASE_URL, AUTH_CSRF_COOKIE_NAME } from './auth.config';
+import { csrfInterceptor } from './csrf.interceptor';
+
+const BFF_BASE = 'http://bff.test/api';
+const CSRF_COOKIE = 'portal_csrf';
+
+function setup() {
+  TestBed.configureTestingModule({
+    providers: [
+      provideHttpClient(withInterceptors([csrfInterceptor])),
+      provideHttpClientTesting(),
+      { provide: AUTH_BFF_BASE_URL, useValue: BFF_BASE },
+      { provide: AUTH_CSRF_COOKIE_NAME, useValue: CSRF_COOKIE },
+    ],
+  });
+  return {
+    http: TestBed.inject(HttpClient),
+    httpCtrl: TestBed.inject(HttpTestingController),
+  };
+}
+
+/**
+ * jsdom keeps `document.cookie` as a single mutable string. Wipe it
+ * around each test so prior writes don't leak.
+ */
+function setCookie(name: string, value: string): void {
+  document.cookie = `${name}=${value}; path=/`;
+}
+function clearAllCookies(): void {
+  const all = document.cookie.split(';');
+  for (const c of all) {
+    const eq = c.indexOf('=');
+    const name = (eq > -1 ? c.slice(0, eq) : c).trim();
+    if (name) document.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/`;
+  }
+}
+
+describe('csrfInterceptor', () => {
+  beforeEach(() => clearAllCookies());
+  afterEach(() => {
+    clearAllCookies();
+    TestBed.resetTestingModule();
+  });
+
+  it('echoes the cookie value into the X-CSRF-Token header on POST', () => {
+    setCookie(CSRF_COOKIE, 'tok-abc');
+    const { http, httpCtrl } = setup();
+    http.post(`${BFF_BASE}/profile`, { name: 'Jane' }).subscribe();
+    const req = httpCtrl.expectOne(`${BFF_BASE}/profile`);
+    expect(req.request.headers.get('X-CSRF-Token')).toBe('tok-abc');
+    req.flush({});
+  });
+
+  it.each(['PUT', 'PATCH', 'DELETE'])('sets the header on %s too', (method) => {
+    setCookie(CSRF_COOKIE, 'tok-abc');
+    const { http, httpCtrl } = setup();
+    http.request(method, `${BFF_BASE}/profile`, { body: {} }).subscribe();
+    const req = httpCtrl.expectOne(`${BFF_BASE}/profile`);
+    expect(req.request.headers.get('X-CSRF-Token')).toBe('tok-abc');
+    req.flush({});
+  });
+
+  it('does NOT set the header on GET (BFF skips CSRF on safe methods)', () => {
+    setCookie(CSRF_COOKIE, 'tok-abc');
+    const { http, httpCtrl } = setup();
+    http.get(`${BFF_BASE}/me`).subscribe();
+    const req = httpCtrl.expectOne(`${BFF_BASE}/me`);
+    expect(req.request.headers.has('X-CSRF-Token')).toBe(false);
+    req.flush({});
+  });
+
+  it('does NOT touch requests to other origins', () => {
+    setCookie(CSRF_COOKIE, 'tok-abc');
+    const { http, httpCtrl } = setup();
+    http.post('http://otel.example/v1/traces', {}).subscribe();
+    const req = httpCtrl.expectOne('http://otel.example/v1/traces');
+    expect(req.request.headers.has('X-CSRF-Token')).toBe(false);
+    req.flush({});
+  });
+
+  it('omits the header when the cookie is missing (lets the BFF respond with its 403)', () => {
+    // No setCookie call — cookie isn't set.
+    const { http, httpCtrl } = setup();
+    http.post(`${BFF_BASE}/profile`, {}).subscribe();
+    const req = httpCtrl.expectOne(`${BFF_BASE}/profile`);
+    expect(req.request.headers.has('X-CSRF-Token')).toBe(false);
+    req.flush({});
+  });
+
+  it('URL-decodes the cookie value (cookies are URI-encoded in transit)', () => {
+    // Cookies preserve their stored form; if anything URL-encodes
+    // the token (current BFF doesn't, base64url is safe), we still
+    // round-trip cleanly.
+    setCookie(CSRF_COOKIE, encodeURIComponent('A B+/='));
+    const { http, httpCtrl } = setup();
+    http.post(`${BFF_BASE}/profile`, {}).subscribe();
+    const req = httpCtrl.expectOne(`${BFF_BASE}/profile`);
+    expect(req.request.headers.get('X-CSRF-Token')).toBe('A B+/=');
+    req.flush({});
+  });
+
+  it('finds the right cookie when others are also set', () => {
+    setCookie('other_cookie', 'noise');
+    setCookie(CSRF_COOKIE, 'tok-abc');
+    setCookie('yet_another', 'noise');
+    const { http, httpCtrl } = setup();
+    http.post(`${BFF_BASE}/profile`, {}).subscribe();
+    const req = httpCtrl.expectOne(`${BFF_BASE}/profile`);
+    expect(req.request.headers.get('X-CSRF-Token')).toBe('tok-abc');
+    req.flush({});
+  });
+});
@@ -0,0 +1,56 @@
+import type { HttpHandlerFn, HttpInterceptorFn, HttpRequest } from '@angular/common/http';
+import { inject } from '@angular/core';
+import { AUTH_BFF_BASE_URL, AUTH_CSRF_COOKIE_NAME } from './auth.config';
+
+/**
+ * Double-submit CSRF helper interceptor (per ADR-0009). Reads the
+ * BFF-issued `__Host-portal_csrf` cookie (or its dev twin
+ * `portal_csrf`) and copies the value into an `X-CSRF-Token` header
+ * on every BFF request whose method mutates state.
+ *
+ * GET / HEAD / OPTIONS pass through without a header — the BFF
+ * skips CSRF on safe methods anyway, and adding the header would
+ * just be noise.
+ *
+ * Non-BFF origins pass through untouched. Same posture as the other
+ * BFF-only interceptors in this lib.
+ *
+ * If the cookie is missing (anonymous, freshly-cleared session,
+ * etc.), the request goes through without the header — the BFF
+ * skips CSRF on anonymous requests, and on the authenticated path
+ * the BFF will answer 403 which the SPA can surface as "please
+ * sign in again".
+ */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+export const csrfInterceptor: HttpInterceptorFn = (
+  req: HttpRequest<unknown>,
+  next: HttpHandlerFn,
+) => {
+  const bffBaseUrl = inject(AUTH_BFF_BASE_URL);
+  const cookieName = inject(AUTH_CSRF_COOKIE_NAME);
+
+  if (!req.url.startsWith(bffBaseUrl)) return next(req);
+  if (SAFE_METHODS.has(req.method.toUpperCase())) return next(req);
+
+  const token = readCookie(cookieName);
+  if (!token) return next(req);
+
+  return next(req.clone({ setHeaders: { 'X-CSRF-Token': token } }));
+};
+
+function readCookie(name: string): string | null {
+  // `document.cookie` is the only browser API to read non-HttpOnly
+  // cookies. The CSRF cookie is deliberately *not* HttpOnly so we
+  // can do exactly this; the session cookie remains HttpOnly.
+  const cookies = typeof document !== 'undefined' ? document.cookie : '';
+  for (const raw of cookies.split(';')) {
+    const eq = raw.indexOf('=');
+    if (eq < 0) continue;
+    const key = raw.slice(0, eq).trim();
+    if (key === name) {
+      return decodeURIComponent(raw.slice(eq + 1));
+    }
+  }
+  return null;
+}