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

@@ -7,6 +7,7 @@ import { PRE_AUTH_COOKIE_NAME, PRE_AUTH_COOKIE_TTL_MS } from './auth.cookie';
 import { AuthCodeFlowException } from './auth.errors';
 import type { AuthService, AuthenticatedUser, PreAuthPayload } from './auth.service';
 import type { EntraConfig } from './entra-config.token';
+import { SessionEstablisher } from './session-establisher.service';
 
 const ENTRA: EntraConfig = {
   instanceUrl: 'https://login.microsoftonline.com/',
@@ -15,6 +16,8 @@ const ENTRA: EntraConfig = {
   clientSecret: 's3cret',
   redirectUri: 'http://localhost:3000/api/auth/callback',
   postLogoutRedirectUri: 'http://localhost:4200/',
+  adminRedirectUri: 'http://localhost:3000/api/admin/auth/callback',
+  adminPostLogoutRedirectUri: 'http://localhost:4201/',
   authority: 'https://login.microsoftonline.com/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
 };
 
@@ -140,13 +143,21 @@ function makeController(opts?: { completeAuthCodeFlow?: jest.Mock }): Controller
     sessionExpired: jest.fn().mockResolvedValue(undefined),
   };
   const logger = makeLoggerStub();
+  // Real SessionEstablisher with the same mocks the legacy tests
+  // already wire — keeps the behavioural assertions on session
+  // fields / audit calls untouched after the controller refactor.
+  const sessionEstablisher = new SessionEstablisher(
+    logger as unknown as Logger,
+    userSessionIndex as unknown as UserSessionIndexService,
+    audit as unknown as AuditWriter,
+  );
   return {
     controller: new AuthController(
       service,
       logger as unknown as Logger,
       ENTRA,
-      userSessionIndex as unknown as UserSessionIndexService,
       audit as unknown as AuditWriter,
+      sessionEstablisher,
     ),
     beginAuthCodeFlow,
     completeAuthCodeFlow,
@@ -214,7 +225,12 @@ describe('AuthController.callback', () => {
     await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
 
     expect(res.clearCookie).toHaveBeenCalledWith(PRE_AUTH_COOKIE_NAME, expect.any(Object));
-    expect(completeAuthCodeFlow).toHaveBeenCalledWith('auth-code', PRE_AUTH.state, PRE_AUTH);
+    expect(completeAuthCodeFlow).toHaveBeenCalledWith(
+      'auth-code',
+      PRE_AUTH.state,
+      PRE_AUTH,
+      ENTRA.redirectUri,
+    );
     // The resolved user must be on the session before the redirect
     // so the subsequent /me call sees a populated payload.
     expect(session.user).toEqual(USER);
@@ -222,6 +238,7 @@ describe('AuthController.callback', () => {
     expect(logger.log).toHaveBeenCalledWith(
       expect.objectContaining({
         event: 'auth.signed_in',
+        surface: 'user',
         oid: USER.oid,
         username: USER.username,
         amr: USER.amr,
@@ -565,7 +582,7 @@ describe('AuthController.logout', () => {
     expect(res.clearCookie).toHaveBeenCalledWith('portal_session', { path: '/' });
     expect(res.clearCookie).toHaveBeenCalledWith('portal_csrf', { path: '/' });
     expect(logger.log).toHaveBeenCalledWith(
-      { event: 'auth.signed_out', wasAuthenticated: true },
+      { event: 'auth.signed_out', surface: 'user', wasAuthenticated: true },
       'AuthLogout',
     );
     // Authority + /oauth2/v2.0/logout?post_logout_redirect_uri=…
@@ -617,7 +634,7 @@ describe('AuthController.logout', () => {
     expect(audit.signOut).not.toHaveBeenCalled();
     expect(session.destroy).toHaveBeenCalledTimes(1);
     expect(logger.log).toHaveBeenCalledWith(
-      { event: 'auth.signed_out', wasAuthenticated: false },
+      { event: 'auth.signed_out', surface: 'user', wasAuthenticated: false },
       'AuthLogout',
     );
     expect(res.redirect).toHaveBeenCalled();