feat(portal-bff): /auth/callback route — token exchange + amr check (#107)

## Summary

Fourth step of ADR-0009 wiring. Closes the OIDC round-trip on the BFF side (modulo session persistence — that's the next PR per ADR-0010). Entra now redirects the user back to `GET /api/auth/callback`; the BFF verifies the state, exchanges the code for tokens via MSAL's `acquireTokenByCode`, runs the ADR-0011 `amr` sanity-check, logs the resolved identity to Pino, clears the single-use pre-auth cookie, and 302s the user back to the SPA.

## What lands

- **[`auth.errors.ts`](apps/portal-bff/src/auth/auth.errors.ts)** — discriminated-union `AuthCodeFlowError` (`state-mismatch` / `flow-expired` / `amr-missing` / `token-exchange-failed`) + `AuthCodeFlowException` wrapper. The `kind` field doubles as the `?auth_error=<code>` query param on the SPA-bound redirect so the front-end can render an exact message without duplicating the string set.
- **[`AuthService.completeAuthCodeFlow(code, state, preAuth, now?)`](apps/portal-bff/src/auth/auth.service.ts)** — verifies state binding, refuses cookies older than the 5-minute flow TTL, calls MSAL Node's `acquireTokenByCode` with the stored verifier, validates `amr` is non-empty (the BFF sanity-check per ADR-0011 — Entra Conditional Access on the org side does the real enforcement), extracts `oid` / `tid` / `preferred_username` / `name` / `amr` into an `AuthenticatedUser` shape.
- **[`auth.cookie.ts`](apps/portal-bff/src/auth/auth.cookie.ts)** gains `clearPreAuthCookieOptions()` mirroring the set-options minus `maxAge` so the browser actually drops the cookie. (Cookies match by name + path + secure; getting any of those wrong leaves the old cookie in place.)
- **[`AuthController.callback()`](apps/portal-bff/src/auth/auth.controller.ts)** — `@Get('callback')`. Always clears the cookie first (single-use). Bails on Entra-side errors (`?error=`), missing query params, missing or malformed cookie — each branch logs a structured Pino warning and redirects with the right `auth_error` code. On `AuthCodeFlowException`, logs + redirects with the typed `kind`. On success, logs an `auth.signed_in` event with `oid`, `tid`, `username`, `amr` (PII-sensitive bits only; no tokens), then 302s to `entra.postLogoutRedirectUri`.

## Decisions worth flagging

- **`postLogoutRedirectUri` reused as the SPA root URL.** Semantically a tiny stretch (its OIDC role is the post-logout destination) but the value is the same. Avoids one more env var until / unless the two URLs need to diverge.
- **Cookie cleared FIRST**, before any branching. Single-use is a property we want guaranteed regardless of which path exits the handler — overlap with a parallel /login from the same browser session would otherwise leak a usable cookie.
- **`auth.signed_in` logged via Pino, not via the audit module.** ADR-0013 wants this in the audit table; pairing audit with the session that ships in the next PR keeps the audit row carrying a `session_id` (otherwise it'd reference a "phantom" auth event with no follow-up).
- **`amr` non-empty is the BFF's check; the Conditional Access policy is what enforces "MFA happened".** ADR-0011 explicitly factors it this way — empty `amr` would indicate a policy misconfiguration where MFA never fired.

## Verification

- `nx run-many -t lint test build --projects=portal-bff` — green.
- **52 / 52 specs** (was 39; +13 across the new completeFlow branches and callback branches).
- Service spec covers happy path + 6 failure modes (state mismatch, flow expired, amr missing, MSAL throws, MSAL returns null, oid claim missing).
- Controller spec covers happy redirect, Entra error, missing cookie, AuthCodeFlowException branch, missing query, malformed cookie.

## Manual smoke test (end-to-end)

1. `apps/portal-bff/.env` carries real `ENTRA_*` + `SESSION_SECRET`.
2. `nx serve portal-bff` and `nx serve portal-shell`.
3. Open `http://localhost:3000/api/auth/login` → redirects to Entra.
4. Authenticate. Entra redirects to `http://localhost:3000/api/auth/callback?code=…&state=…`.
5. BFF processes; redirects to `http://localhost:4200/`. Pino log shows `auth.signed_in` with the user's `oid`, `tid`, `username`, `amr`.
6. Tamper test: open the link again, hand-edit the `state=` in the callback URL → BFF redirects with `?auth_error=state-mismatch`.

## What this PR explicitly does NOT do

- **Persist a session.** The user is "authenticated" from the BFF's point of view (identity resolved + logged) but the next request lands anonymous. Closes in the Redis sessions PR per ADR-0010.
- **Audit log entry.** Pairs with sessions so the row carries a `session_id`.
- **Logout / `/me`.** Land after sessions.

---------

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

apps/portal-bff/src/auth/auth.service.spec.ts

@@ -1,5 +1,7 @@
-import type { ConfidentialClientApplication } from '@azure/msal-node';
-import { AuthService } from './auth.service';
+import type { AuthenticationResult, ConfidentialClientApplication } from '@azure/msal-node';
+import { PRE_AUTH_COOKIE_TTL_MS } from './auth.cookie';
+import { AuthCodeFlowException } from './auth.errors';
+import { AuthService, type PreAuthPayload } from './auth.service';
 import type { EntraConfig } from './entra-config.token';
 
 const ENTRA: EntraConfig = {
@@ -12,17 +14,54 @@ const ENTRA: EntraConfig = {
   authority: 'https://login.microsoftonline.com/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
 };
 
-describe('AuthService', () => {
-  let getAuthCodeUrl: jest.Mock<Promise<string>, [unknown]>;
-  let service: AuthService;
+interface ServiceFixture {
+  service: AuthService;
+  getAuthCodeUrl: jest.Mock;
+  acquireTokenByCode: jest.Mock;
+}
 
-  beforeEach(() => {
-    getAuthCodeUrl = jest.fn().mockResolvedValue('https://entra.example/authorize?…');
-    const msalStub = { getAuthCodeUrl } as unknown as ConfidentialClientApplication;
-    service = new AuthService(msalStub, ENTRA);
-  });
+function makeService(overrides?: { acquireTokenByCode?: jest.Mock }): ServiceFixture {
+  const getAuthCodeUrl = jest.fn().mockResolvedValue('https://entra.example/authorize?…');
+  const acquireTokenByCode =
+    overrides?.acquireTokenByCode ??
+    jest.fn().mockResolvedValue(makeAuthResult({ amr: ['pwd', 'mfa'] }));
+  const msalStub = {
+    getAuthCodeUrl,
+    acquireTokenByCode,
+  } as unknown as ConfidentialClientApplication;
+  return { service: new AuthService(msalStub, ENTRA), getAuthCodeUrl, acquireTokenByCode };
+}
 
+function makeAuthResult(
+  claims: Partial<{
+    amr: string[];
+    oid: string;
+    tid: string;
+    name: string;
+    preferred_username: string;
+  }>,
+): AuthenticationResult {
+  return {
+    idTokenClaims: {
+      oid: claims.oid ?? 'user-oid',
+      tid: claims.tid ?? ENTRA.tenantId,
+      name: claims.name ?? 'Jane Doe',
+      preferred_username: claims.preferred_username ?? 'jane.doe@apf.example',
+      amr: claims.amr ?? ['pwd', 'mfa'],
+    },
+    account: { username: 'jane.doe@apf.example', name: 'Jane Doe' },
+  } as unknown as AuthenticationResult;
+}
+
+const PRE_AUTH_OK: PreAuthPayload = {
+  state: 'state-nonce',
+  codeVerifier: 'verifier-secret',
+  createdAt: 1_000_000,
+};
+
+describe('AuthService.beginAuthCodeFlow', () => {
   it('builds the auth URL with the configured redirect, OIDC scopes, S256 challenge', async () => {
+    const { service, getAuthCodeUrl } = makeService();
     await service.beginAuthCodeFlow();
     expect(getAuthCodeUrl).toHaveBeenCalledTimes(1);
     const arg = getAuthCodeUrl.mock.calls[0]?.[0] as Record<string, unknown>;
@@ -30,30 +69,102 @@ describe('AuthService', () => {
     expect(arg['scopes']).toEqual(['openid', 'profile', 'email']);
     expect(arg['codeChallengeMethod']).toBe('S256');
     expect(typeof arg['codeChallenge']).toBe('string');
-    expect((arg['codeChallenge'] as string).length).toBeGreaterThan(20);
     expect(typeof arg['state']).toBe('string');
-    expect((arg['state'] as string).length).toBeGreaterThan(8);
   });
 
   it('returns the pre-auth payload with state + codeVerifier matching what MSAL was called with', async () => {
-    const { authUrl, preAuthPayload } = await service.beginAuthCodeFlow();
-    expect(authUrl).toBe('https://entra.example/authorize?…');
-
+    const { service, getAuthCodeUrl } = makeService();
+    const { preAuthPayload } = await service.beginAuthCodeFlow();
     const arg = getAuthCodeUrl.mock.calls[0]?.[0] as Record<string, unknown>;
     expect(preAuthPayload.state).toBe(arg['state']);
-    // The verifier returned to the caller is the secret the callback
-    // will send back to Entra; the challenge sent to Entra is its
-    // SHA-256-of-verifier transform, so the two must differ.
     expect(preAuthPayload.codeVerifier).not.toBe(arg['codeChallenge']);
-    expect(typeof preAuthPayload.codeVerifier).toBe('string');
-    expect(preAuthPayload.codeVerifier.length).toBeGreaterThan(40);
     expect(preAuthPayload.createdAt).toBeLessThanOrEqual(Date.now());
   });
 
-  it('generates a fresh state + verifier on every call (replay protection)', async () => {
+  it('generates a fresh state + verifier on every call', async () => {
+    const { service } = makeService();
     const a = await service.beginAuthCodeFlow();
     const b = await service.beginAuthCodeFlow();
     expect(a.preAuthPayload.state).not.toBe(b.preAuthPayload.state);
     expect(a.preAuthPayload.codeVerifier).not.toBe(b.preAuthPayload.codeVerifier);
   });
 });
+
+describe('AuthService.completeAuthCodeFlow', () => {
+  it('returns the authenticated user on the happy path', async () => {
+    const { service, acquireTokenByCode } = makeService();
+    const user = await service.completeAuthCodeFlow(
+      'auth-code',
+      PRE_AUTH_OK.state,
+      PRE_AUTH_OK,
+      PRE_AUTH_OK.createdAt + 1_000,
+    );
+    expect(acquireTokenByCode).toHaveBeenCalledWith({
+      code: 'auth-code',
+      codeVerifier: PRE_AUTH_OK.codeVerifier,
+      redirectUri: ENTRA.redirectUri,
+      scopes: ['openid', 'profile', 'email'],
+    });
+    expect(user).toEqual({
+      oid: 'user-oid',
+      tid: ENTRA.tenantId,
+      username: 'jane.doe@apf.example',
+      displayName: 'Jane Doe',
+      amr: ['pwd', 'mfa'],
+    });
+  });
+
+  it('throws state-mismatch when the query state differs from the cookie state', async () => {
+    const { service } = makeService();
+    await expect(
+      service.completeAuthCodeFlow('code', 'other-state', PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+    ).rejects.toMatchObject({ failure: { kind: 'state-mismatch' } });
+  });
+
+  it('throws flow-expired when the cookie is older than the TTL', async () => {
+    const { service } = makeService();
+    const now = PRE_AUTH_OK.createdAt + PRE_AUTH_COOKIE_TTL_MS + 1;
+    await expect(
+      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, now),
+    ).rejects.toMatchObject({ failure: { kind: 'flow-expired' } });
+  });
+
+  it('throws amr-missing when the ID token has no amr claim', async () => {
+    const acquireTokenByCode = jest.fn().mockResolvedValue(makeAuthResult({ amr: [] }));
+    const { service } = makeService({ acquireTokenByCode });
+    await expect(
+      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+    ).rejects.toMatchObject({ failure: { kind: 'amr-missing' } });
+  });
+
+  it('throws token-exchange-failed when MSAL throws', async () => {
+    const acquireTokenByCode = jest.fn().mockRejectedValue(new Error('AADSTS70008'));
+    const { service } = makeService({ acquireTokenByCode });
+    await expect(
+      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+    ).rejects.toMatchObject({
+      failure: { kind: 'token-exchange-failed', cause: 'AADSTS70008' },
+    });
+  });
+
+  it('throws token-exchange-failed when MSAL returns null', async () => {
+    const acquireTokenByCode = jest.fn().mockResolvedValue(null);
+    const { service } = makeService({ acquireTokenByCode });
+    await expect(
+      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+    ).rejects.toBeInstanceOf(AuthCodeFlowException);
+  });
+
+  it('throws token-exchange-failed when oid claim is missing', async () => {
+    const acquireTokenByCode = jest.fn().mockResolvedValue({
+      idTokenClaims: { tid: ENTRA.tenantId, amr: ['mfa'] },
+      account: { username: '', name: '' },
+    } as unknown as AuthenticationResult);
+    const { service } = makeService({ acquireTokenByCode });
+    await expect(
+      service.completeAuthCodeFlow('code', PRE_AUTH_OK.state, PRE_AUTH_OK, PRE_AUTH_OK.createdAt),
+    ).rejects.toMatchObject({
+      failure: { kind: 'token-exchange-failed', cause: /oid/ },
+    });
+  });
+});