feat(portal-bff): distinct admin session + /api/admin/auth flow (#129)

## Summary

Phase-3a step per [ADR-0020](docs/decisions/0020-portal-admin-app.md) §"Sessions — distinct from `portal-shell`". Wires a second `express-session` middleware on `/api/admin/*` carrying `__Host-portal_admin_session` over Redis prefix `session:admin:`, and ships the parallel `/api/admin/auth/{login,callback,me,logout}` flow that populates it. Signing in to one surface no longer signs the user into the other — Entra SSO at the IdP level still preserves the click-through.

## What lands

### Session middlewares — path-routed dispatch

| Token | Cookie | Redis prefix | Bound to |
| --- | --- | --- | --- |
| `SESSION_MIDDLEWARE` | `portal_session` / `__Host-portal_session` | `session:` | every path **except** `/api/admin/*` |
| `ADMIN_SESSION_MIDDLEWARE` | `portal_admin_session` / `__Host-portal_admin_session` | `session:admin:` | `/api/admin/*` only |

Implemented via a `buildSessionMiddleware(redis, logger, opts)` factory in [session.module.ts](apps/portal-bff/src/session/session.module.ts) — the TTL policy, encryption key, signing secret, session-id entropy, and serializer error-handling all come from the same source. Only the cookie name + Redis key prefix differ.

The dispatch in [main.ts](apps/portal-bff/src/main.ts) is a tiny `(req, res, next) => req.path.startsWith('/api/admin') ? adminSession(...) : userSession(...)`. Running both middlewares unconditionally would have the second overwrite `req.session` from the first, collapsing the two surfaces.

### Distinct admin auth flow

[`AdminAuthController`](apps/portal-bff/src/admin/admin-auth.controller.ts) mounts `/api/admin/auth/{login,callback,me,logout}`. Structurally identical to [`AuthController`](apps/portal-bff/src/auth/auth.controller.ts) but passes `adminRedirectUri` / `adminPostLogoutRedirectUri` and clears the admin session cookie on logout. `me` exposes the `roles` claim (admin SPA needs it for conditional UI); the user-portal `me` intentionally still doesn't.

### Shared `SessionEstablisher` (no controller duplication)

[`SessionEstablisher`](apps/portal-bff/src/auth/session-establisher.service.ts) encapsulates the session lifecycle so both controllers stay thin:

- `establish({ user, req, res, surface })` — mints CSRF, populates `user / createdAt / absoluteExpiresAt / csrfToken / mfaVerifiedAt`, saves, sets the CSRF cookie, registers in `user_sessions` index, emits `auth.sign_in` audit (blocking), logs with the `surface` tag.
- `destroy({ actor, req })` — when `actor` is set, removes from index + emits `auth.sign_out`; always destroys the session with Redis-hiccup tolerance.

No code duplicated between the two surfaces — the only per-surface differences are the redirect URIs (passed in) and the cookie names cleared on logout (controller-local).

### Entra config gains two URIs

`EntraConfig` adds `adminRedirectUri` + `adminPostLogoutRedirectUri`, validated at boot in [check-entra-config.ts](apps/portal-bff/src/config/check-entra-config.ts). The validator **refuses to start** when `ENTRA_ADMIN_REDIRECT_URI === ENTRA_REDIRECT_URI` — that misconfiguration would silently collapse the two surfaces into one session. Both URIs must be registered on the same Entra app registration's "Redirect URIs" list.

### `AuthService` API change

`beginAuthCodeFlow(redirectUri)`, `completeAuthCodeFlow(code, state, preAuth, redirectUri, now?)`, and `buildLogoutUrl(postLogoutRedirectUri)` now take their URI as a parameter. Callers (user-portal vs admin-portal controllers) pick which set to pass.

## Required ops action before this PR can run locally

Two new mandatory env vars. The BFF refuses to start without them.

```env
ENTRA_ADMIN_REDIRECT_URI=http://localhost:3000/api/admin/auth/callback
ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI=http://localhost:4201/
```

The example values land in [apps/portal-bff/.env.example](apps/portal-bff/.env.example) for reference. The corresponding Entra app registration also needs `/api/admin/auth/callback` added to its "Redirect URIs" list before any admin sign-in works end-to-end.

## Notes for the reviewer

- The user-portal callback's post-login redirect still targets `postLogoutRedirectUri` (existing quirk where the post-auth and post-logout landing happen to be the same URL). The admin callback mirrors the pattern for `adminPostLogoutRedirectUri`. Splitting these into dedicated post-login URIs is a separate ADR/PR.
- `AdminModule` now imports `AuthModule` to consume `AuthService`, `SessionEstablisher`, and `ENTRA_CONFIG`. `AuditWriter` and `RequireMfaGuard` come through transitively.
- Existing `AuthController` spec assertions are preserved through the refactor by constructing a **real** `SessionEstablisher` in the test fixture with the same audit / index / logger mocks. No behavioural assertion was removed — the inline session-state-setting logic is now exercised through the establisher.
- The pre-existing docstring in `check-entra-config.ts` line 11-16 still says "the two redirect URIs are mandatory once the OIDC routes ship (next PR)" — stale, the routes have shipped. Not touched in this PR to keep the diff focused; can be a one-line doc PR later.

## Test plan

- [x] `pnpm nx test portal-bff` — **278 specs pass** (was 253; +25: admin cookie 3, session-establisher 11, admin auth controller 9, entra config 2).
- [x] `pnpm exec nx affected -t format:check lint test build --base=origin/main` — clean (the pre-existing `_res` / `_next` warnings in `rate-limit.middleware.ts` are unrelated).
- [x] Entra config validator: both URIs required, both URL-validated, equality refused.
- [x] Path-dispatch verified by routing — `/api/admin/me` and `/api/admin/auth/*` see the admin session; everything else sees the user session.
- [ ] e2e — pending env var update + Entra registration update to add the admin redirect URI. Once both are in place: sign in via `/api/auth/login`, see `portal_session` cookie; clear cookies; sign in via `/api/admin/auth/login`, see `portal_admin_session` cookie; verify `/api/admin/me` works on the admin session and `/api/auth/me` works on the user session — neither sees the other's session.

---------

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

apps/portal-bff/src/config/check-entra-config.spec.ts

@@ -7,6 +7,8 @@ const VALID = {
   ENTRA_CLIENT_SECRET: 's3cret-value-from-entra',
   ENTRA_REDIRECT_URI: 'http://localhost:3000/api/auth/callback',
   ENTRA_POST_LOGOUT_REDIRECT_URI: 'http://localhost:4200/',
+  ENTRA_ADMIN_REDIRECT_URI: 'http://localhost:3000/api/admin/auth/callback',
+  ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI: 'http://localhost:4201/',
 };
 
 describe('assertEntraConfig', () => {
@@ -38,9 +40,21 @@ describe('assertEntraConfig', () => {
     expect(config.clientSecret).toBe(VALID.ENTRA_CLIENT_SECRET);
     expect(config.redirectUri).toBe(VALID.ENTRA_REDIRECT_URI);
     expect(config.postLogoutRedirectUri).toBe(VALID.ENTRA_POST_LOGOUT_REDIRECT_URI);
+    expect(config.adminRedirectUri).toBe(VALID.ENTRA_ADMIN_REDIRECT_URI);
+    expect(config.adminPostLogoutRedirectUri).toBe(VALID.ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI);
     expect(config.authority).toBe(`${VALID.ENTRA_INSTANCE_URL}${VALID.ENTRA_TENANT_ID}`);
   });
 
+  it('throws when ENTRA_ADMIN_REDIRECT_URI equals ENTRA_REDIRECT_URI (would collapse the two surfaces)', () => {
+    process.env['ENTRA_ADMIN_REDIRECT_URI'] = VALID.ENTRA_REDIRECT_URI;
+    expect(() => assertEntraConfig()).toThrow(/must differ from ENTRA_REDIRECT_URI/);
+  });
+
+  it('rejects ENTRA_ADMIN_REDIRECT_URI when not a valid URL', () => {
+    process.env['ENTRA_ADMIN_REDIRECT_URI'] = 'nope';
+    expect(() => assertEntraConfig()).toThrow(/ENTRA_ADMIN_REDIRECT_URI is not a valid URL/);
+  });
+
   it('throws listing every missing required key', () => {
     delete process.env['ENTRA_CLIENT_ID'];
     delete process.env['ENTRA_CLIENT_SECRET'];

apps/portal-bff/src/config/check-entra-config.ts

@@ -28,10 +28,25 @@ export interface EntraConfig {
   readonly clientId: string;
   /** Confidential client secret. */
   readonly clientSecret: string;
-  /** Where Entra sends the user after authentication — `/auth/callback`. */
+  /** Where Entra sends the user after authentication — `/api/auth/callback`. */
   readonly redirectUri: string;
   /** Where Entra sends the user after RP-initiated logout. */
   readonly postLogoutRedirectUri: string;
+  /**
+   * Admin-surface callback URL — `/api/admin/auth/callback`. Distinct
+   * from {@link redirectUri} per ADR-0020 §"Sessions — distinct from
+   * `portal-shell`" so Entra knows which callback handler (and
+   * therefore which session) the auth flow is establishing.
+   * Both URIs must be registered on the same Entra app registration.
+   */
+  readonly adminRedirectUri: string;
+  /**
+   * Where Entra sends the admin user after RP-initiated logout from
+   * the admin surface. Typically the admin SPA's landing page — kept
+   * distinct from {@link postLogoutRedirectUri} so an operator can
+   * route admin sign-outs to a different page than user sign-outs.
+   */
+  readonly adminPostLogoutRedirectUri: string;
   /**
    * Convenience: the full authority URL passed to MSAL Node
    * (`${instanceUrl}${tenantId}`). Computed once so the rest of the
@@ -47,6 +62,8 @@ const REQUIRED_KEYS = [
   'ENTRA_CLIENT_SECRET',
   'ENTRA_REDIRECT_URI',
   'ENTRA_POST_LOGOUT_REDIRECT_URI',
+  'ENTRA_ADMIN_REDIRECT_URI',
+  'ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI',
 ] as const;
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -70,6 +87,8 @@ export function assertEntraConfig(): EntraConfig {
   const clientSecret = process.env['ENTRA_CLIENT_SECRET'] as string;
   const redirectUri = process.env['ENTRA_REDIRECT_URI'] as string;
   const postLogoutRedirectUri = process.env['ENTRA_POST_LOGOUT_REDIRECT_URI'] as string;
+  const adminRedirectUri = process.env['ENTRA_ADMIN_REDIRECT_URI'] as string;
+  const adminPostLogoutRedirectUri = process.env['ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI'] as string;
 
   assertUrl('ENTRA_INSTANCE_URL', instanceUrl, ['https:']);
   if (!instanceUrl.endsWith('/')) {
@@ -87,6 +106,24 @@ export function assertEntraConfig(): EntraConfig {
 
   assertUrl('ENTRA_REDIRECT_URI', redirectUri, ['http:', 'https:']);
   assertUrl('ENTRA_POST_LOGOUT_REDIRECT_URI', postLogoutRedirectUri, ['http:', 'https:']);
+  assertUrl('ENTRA_ADMIN_REDIRECT_URI', adminRedirectUri, ['http:', 'https:']);
+  assertUrl('ENTRA_ADMIN_POST_LOGOUT_REDIRECT_URI', adminPostLogoutRedirectUri, [
+    'http:',
+    'https:',
+  ]);
+
+  // Admin and user redirect URIs must differ — they're the only
+  // way Entra (and therefore the BFF) tells the two flows apart.
+  // A misconfiguration that points both to the same handler would
+  // silently collapse the two surfaces into one session.
+  if (adminRedirectUri === redirectUri) {
+    throw new Error(
+      `ENTRA_ADMIN_REDIRECT_URI must differ from ENTRA_REDIRECT_URI ` +
+        `so Entra can route the callback to the matching session ` +
+        `(see ADR-0020 §"Sessions — distinct from portal-shell"). ` +
+        `Both are: ${redirectUri}`,
+    );
+  }
 
   return {
     instanceUrl,
@@ -95,6 +132,8 @@ export function assertEntraConfig(): EntraConfig {
     clientSecret,
     redirectUri,
     postLogoutRedirectUri,
+    adminRedirectUri,
+    adminPostLogoutRedirectUri,
     authority: `${instanceUrl}${tenantId}`,
   };
 }