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
2026-05-14 02:21:47 +02:00
parent d51ccebe6a
commit fed905edc5
19 changed files with 1221 additions and 223 deletions
@@ -0,0 +1,282 @@
+import type { Request, Response } from 'express';
+import type { Logger } from 'nestjs-pino';
+import type { AuditWriter } from '../audit/audit.service';
+import { PRE_AUTH_COOKIE_NAME } from '../auth/auth.cookie';
+import { AuthCodeFlowException } from '../auth/auth.errors';
+import type { AuthService, PreAuthPayload } from '../auth/auth.service';
+import type { EntraConfig } from '../auth/entra-config.token';
+import type { SessionEstablisher } from '../auth/session-establisher.service';
+import { AdminAuthController } from './admin-auth.controller';
+
+const ENTRA: EntraConfig = {
+  instanceUrl: 'https://login.microsoftonline.com/',
+  tenantId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+  clientId: '11111111-2222-3333-4444-555555555555',
+  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',
+};
+
+const USER = {
+  oid: 'admin-oid',
+  tid: ENTRA.tenantId,
+  username: 'admin@apf.example',
+  displayName: 'Admin Smith',
+  amr: ['pwd', 'mfa'],
+  roles: ['admin'],
+};
+
+const PRE_AUTH: PreAuthPayload = {
+  state: 'state-nonce',
+  codeVerifier: 'verifier-secret',
+  createdAt: 1_000,
+};
+
+const ADMIN_LOGOUT_URL = `${ENTRA.authority}/oauth2/v2.0/logout?post_logout_redirect_uri=${encodeURIComponent(ENTRA.adminPostLogoutRedirectUri)}`;
+
+function makeResStub() {
+  const res = {
+    cookie: jest.fn(),
+    clearCookie: jest.fn(),
+    redirect: jest.fn(),
+    status: jest.fn(),
+    json: jest.fn(),
+  };
+  res.cookie.mockReturnValue(res);
+  res.clearCookie.mockReturnValue(res);
+  res.redirect.mockReturnValue(res);
+  res.status.mockReturnValue(res);
+  res.json.mockReturnValue(res);
+  return res as unknown as Response & typeof res;
+}
+
+function makeReqStub(opts?: {
+  signedCookies?: Record<string, unknown>;
+  sessionUser?: typeof USER;
+}): Request {
+  return {
+    signedCookies: opts?.signedCookies ?? {},
+    session: opts?.sessionUser !== undefined ? { user: opts.sessionUser } : {},
+    sessionID: 'sid-admin',
+  } as unknown as Request;
+}
+
+function makeFixture(opts?: { completeAuthCodeFlow?: jest.Mock }) {
+  const beginAuthCodeFlow = jest.fn().mockResolvedValue({
+    authUrl: 'https://entra.example/authorize?state=state-nonce',
+    preAuthPayload: PRE_AUTH,
+  });
+  const completeAuthCodeFlow = opts?.completeAuthCodeFlow ?? jest.fn().mockResolvedValue(USER);
+  const buildLogoutUrl = jest.fn().mockReturnValue(ADMIN_LOGOUT_URL);
+  const authService = {
+    beginAuthCodeFlow,
+    completeAuthCodeFlow,
+    buildLogoutUrl,
+  } as unknown as AuthService;
+  const audit = {
+    signIn: jest.fn().mockResolvedValue(undefined),
+    signInFailed: jest.fn().mockResolvedValue(undefined),
+    signOut: jest.fn().mockResolvedValue(undefined),
+  };
+  const establisher = {
+    establish: jest.fn().mockResolvedValue(undefined),
+    destroy: jest.fn().mockResolvedValue(undefined),
+  };
+  const logger = { log: jest.fn(), warn: jest.fn(), error: jest.fn() };
+  return {
+    controller: new AdminAuthController(
+      authService,
+      logger as unknown as Logger,
+      ENTRA,
+      audit as unknown as AuditWriter,
+      establisher as unknown as SessionEstablisher,
+    ),
+    beginAuthCodeFlow,
+    completeAuthCodeFlow,
+    buildLogoutUrl,
+    audit,
+    establisher,
+    logger,
+  };
+}
+
+describe('AdminAuthController.login', () => {
+  it('passes the admin redirect URI to beginAuthCodeFlow', async () => {
+    const { controller, beginAuthCodeFlow } = makeFixture();
+    await controller.login(makeResStub());
+    expect(beginAuthCodeFlow).toHaveBeenCalledWith(ENTRA.adminRedirectUri);
+  });
+
+  it('writes the pre-auth cookie and 302s to the Entra auth URL', async () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    await controller.login(res);
+    expect(res.cookie).toHaveBeenCalledWith(
+      PRE_AUTH_COOKIE_NAME,
+      expect.any(String),
+      expect.objectContaining({ signed: true, httpOnly: true }),
+    );
+    expect(res.redirect).toHaveBeenCalledWith(302, expect.stringContaining('entra.example'));
+  });
+});
+
+describe('AdminAuthController.callback', () => {
+  it('passes the admin redirect URI to completeAuthCodeFlow and establishes a surface=admin session', async () => {
+    const { controller, completeAuthCodeFlow, establisher } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({
+      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+    });
+
+    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+
+    expect(completeAuthCodeFlow).toHaveBeenCalledWith(
+      'auth-code',
+      PRE_AUTH.state,
+      PRE_AUTH,
+      ENTRA.adminRedirectUri,
+    );
+    expect(establisher.establish).toHaveBeenCalledWith({
+      user: USER,
+      req,
+      res,
+      surface: 'admin',
+    });
+    expect(res.redirect).toHaveBeenCalledWith(302, ENTRA.adminPostLogoutRedirectUri);
+  });
+
+  it('redirects with ?auth_error=token-exchange-failed when Entra returns error', async () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({
+      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+    });
+
+    await controller.callback(req, res, undefined, undefined, 'access_denied', 'consent declined');
+
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining('auth_error=token-exchange-failed'),
+    );
+    // Error redirect lands on the admin post-logout target, not the user-portal one.
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining(ENTRA.adminPostLogoutRedirectUri),
+    );
+  });
+
+  it('redirects with ?auth_error=flow-expired when the pre-auth cookie is missing', async () => {
+    const { controller, audit } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({ signedCookies: {} });
+
+    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining('auth_error=flow-expired'),
+    );
+    expect(audit.signInFailed).toHaveBeenCalledWith(
+      expect.objectContaining({
+        failureKind: 'no-pre-auth-cookie',
+        payload: expect.objectContaining({ surface: 'admin' }),
+      }),
+    );
+  });
+
+  it('redirects with the typed error from AuthCodeFlowException', async () => {
+    const completeAuthCodeFlow = jest
+      .fn()
+      .mockRejectedValue(new AuthCodeFlowException({ kind: 'state-mismatch' }));
+    const { controller, audit } = makeFixture({ completeAuthCodeFlow });
+    const res = makeResStub();
+    const req = makeReqStub({
+      signedCookies: { [PRE_AUTH_COOKIE_NAME]: JSON.stringify(PRE_AUTH) },
+    });
+
+    await controller.callback(req, res, 'auth-code', PRE_AUTH.state);
+
+    expect(res.redirect).toHaveBeenCalledWith(
+      302,
+      expect.stringContaining('auth_error=state-mismatch'),
+    );
+    expect(audit.signInFailed).toHaveBeenCalledWith(
+      expect.objectContaining({
+        failureKind: 'state-mismatch',
+        payload: expect.objectContaining({ surface: 'admin' }),
+      }),
+    );
+  });
+});
+
+describe('AdminAuthController.me', () => {
+  it('returns the public payload with roles when the admin session is populated', () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({ sessionUser: USER });
+    controller.me(req, res);
+    expect(res.json).toHaveBeenCalledWith({
+      oid: USER.oid,
+      tid: USER.tid,
+      username: USER.username,
+      displayName: USER.displayName,
+      roles: USER.roles,
+    });
+  });
+
+  it('throws UnauthorizedException when no user is on the admin session', () => {
+    const { controller } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub();
+    expect(() => controller.me(req, res)).toThrow(/Unauthenticated/);
+  });
+});
+
+describe('AdminAuthController.logout', () => {
+  it('destroys the admin session, clears the admin cookie + CSRF cookie, redirects to Entra logout', async () => {
+    const { controller, establisher, buildLogoutUrl } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub({ sessionUser: USER });
+
+    await controller.logout(req, res);
+
+    expect(establisher.destroy).toHaveBeenCalledWith({ actor: USER, req });
+    expect(buildLogoutUrl).toHaveBeenCalledWith(ENTRA.adminPostLogoutRedirectUri);
+    expect(res.clearCookie).toHaveBeenCalledWith('portal_admin_session', { path: '/' });
+    expect(res.clearCookie).toHaveBeenCalledWith('portal_csrf', { path: '/' });
+    expect(res.redirect).toHaveBeenCalledWith(302, ADMIN_LOGOUT_URL);
+  });
+
+  it('uses the __Host- prefixed admin cookie name in production', async () => {
+    const originalNodeEnv = process.env['NODE_ENV'];
+    try {
+      process.env['NODE_ENV'] = 'production';
+      const { controller } = makeFixture();
+      const res = makeResStub();
+      const req = makeReqStub({ sessionUser: USER });
+      await controller.logout(req, res);
+      expect(res.clearCookie).toHaveBeenCalledWith('__Host-portal_admin_session', {
+        path: '/',
+      });
+    } finally {
+      if (originalNodeEnv === undefined) {
+        delete process.env['NODE_ENV'];
+      } else {
+        process.env['NODE_ENV'] = originalNodeEnv;
+      }
+    }
+  });
+
+  it('still clears cookies and redirects for an anonymous admin sign-out', async () => {
+    const { controller, establisher } = makeFixture();
+    const res = makeResStub();
+    const req = makeReqStub();
+    await controller.logout(req, res);
+    expect(establisher.destroy).toHaveBeenCalledWith({ actor: undefined, req });
+    expect(res.clearCookie).toHaveBeenCalledWith('portal_admin_session', { path: '/' });
+    expect(res.redirect).toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,185 @@
+import { Controller, Get, Inject, Query, Req, Res, UnauthorizedException } from '@nestjs/common';
+import type { Request, Response } from 'express';
+import { Logger } from 'nestjs-pino';
+import { AuditWriter } from '../audit/audit.service';
+import {
+  PRE_AUTH_COOKIE_NAME,
+  clearPreAuthCookieOptions,
+  preAuthCookieOptions,
+} from '../auth/auth.cookie';
+import { AuthCodeFlowException, type AuthCodeFlowError, authErrorCode } from '../auth/auth.errors';
+import { AuthService, type PreAuthPayload } from '../auth/auth.service';
+import { ENTRA_CONFIG, type EntraConfig } from '../auth/entra-config.token';
+import { SessionEstablisher } from '../auth/session-establisher.service';
+import { csrfCookieName } from '../security/csrf-cookie';
+import { adminSessionCookieName } from '../session/admin-session-cookie';
+
+/**
+ * `/api/admin/auth/*` — admin-portal OIDC routes per ADR-0020.
+ *
+ * Structurally identical to the user-portal `AuthController`:
+ * `GET /login` 302s to Entra with PKCE + state in a signed cookie,
+ * `GET /callback` exchanges the code for tokens, establishes the
+ * admin session, and redirects to the admin SPA. `GET /me` reads
+ * the admin session back. `GET /logout` destroys the admin session
+ * and redirects to Entra's RP-initiated logout.
+ *
+ * The key difference is *which* `req.session` we're looking at: the
+ * session middleware mounted on `/api/admin/*` in `main.ts` resolves
+ * to the admin-session Redis namespace (`session:admin:*`) and uses
+ * the `__Host-portal_admin_session` cookie, distinct from
+ * `__Host-portal_session` used by the user portal. Per ADR-0020
+ * §"Sessions — distinct from `portal-shell`": signing in to one
+ * surface does NOT sign in to the other.
+ *
+ * Routes here are **deliberately not** guarded with `@RequireAdmin`
+ * or `@RequireMfa`. The whole point of the login flow is to *create*
+ * the session that those guards check against. Sub-controllers
+ * (admin business routes) layer the guards on top.
+ */
+@Controller('admin/auth')
+export class AdminAuthController {
+  constructor(
+    private readonly authService: AuthService,
+    private readonly logger: Logger,
+    @Inject(ENTRA_CONFIG) private readonly entra: EntraConfig,
+    private readonly audit: AuditWriter,
+    private readonly sessionEstablisher: SessionEstablisher,
+  ) {}
+
+  @Get('login')
+  async login(@Res() res: Response): Promise<void> {
+    const { authUrl, preAuthPayload } = await this.authService.beginAuthCodeFlow(
+      this.entra.adminRedirectUri,
+    );
+    res.cookie(PRE_AUTH_COOKIE_NAME, JSON.stringify(preAuthPayload), preAuthCookieOptions());
+    res.redirect(302, authUrl);
+  }
+
+  @Get('callback')
+  async callback(
+    @Req() req: Request,
+    @Res() res: Response,
+    @Query('code') code?: string,
+    @Query('state') state?: string,
+    @Query('error') entraError?: string,
+    @Query('error_description') entraErrorDescription?: string,
+  ): Promise<void> {
+    res.clearCookie(PRE_AUTH_COOKIE_NAME, clearPreAuthCookieOptions());
+
+    if (entraError) {
+      this.logger.warn(
+        {
+          event: 'auth.entra_error',
+          surface: 'admin',
+          entraError,
+          entraErrorDescription,
+        },
+        'AdminAuthCallback',
+      );
+      await this.audit.signInFailed({
+        failureKind: 'entra-error',
+        payload: { surface: 'admin', entraError, entraErrorDescription },
+      });
+      return this.redirectWithError(res, 'token-exchange-failed');
+    }
+
+    if (typeof code !== 'string' || typeof state !== 'string') {
+      await this.audit.signInFailed({
+        failureKind: 'missing-code-or-state',
+        payload: { surface: 'admin' },
+      });
+      return this.redirectWithError(res, 'token-exchange-failed');
+    }
+
+    const preAuth = readPreAuthCookie(req);
+    if (!preAuth) {
+      this.logger.warn({ event: 'auth.no_pre_auth_cookie', surface: 'admin' }, 'AdminAuthCallback');
+      await this.audit.signInFailed({
+        failureKind: 'no-pre-auth-cookie',
+        payload: { surface: 'admin' },
+      });
+      return this.redirectWithError(res, 'flow-expired');
+    }
+
+    try {
+      const user = await this.authService.completeAuthCodeFlow(
+        code,
+        state,
+        preAuth,
+        this.entra.adminRedirectUri,
+      );
+      await this.sessionEstablisher.establish({ user, req, res, surface: 'admin' });
+      res.redirect(302, this.entra.adminPostLogoutRedirectUri);
+    } catch (err) {
+      if (err instanceof AuthCodeFlowException) {
+        this.logger.warn(
+          { event: 'auth.flow_error', surface: 'admin', failure: err.failure },
+          'AdminAuthCallback',
+        );
+        await this.audit.signInFailed({
+          failureKind: err.failure.kind,
+          payload: { surface: 'admin' },
+        });
+        return this.redirectWithError(res, err.failure.kind);
+      }
+      throw err;
+    }
+  }
+
+  @Get('me')
+  me(@Req() req: Request, @Res() res: Response): void {
+    const user = req.session.user;
+    if (!user) {
+      throw new UnauthorizedException({
+        code: 'unauthenticated',
+        message: 'Unauthenticated',
+      });
+    }
+    res.json({
+      oid: user.oid,
+      tid: user.tid,
+      username: user.username,
+      displayName: user.displayName,
+      // Admins benefit from seeing their role assignment in the
+      // SPA — drives conditional UI for super-admin features later.
+      // Other surfaces (`/api/auth/me`) still omit it.
+      roles: user.roles,
+    });
+  }
+
+  @Get('logout')
+  async logout(@Req() req: Request, @Res() res: Response): Promise<void> {
+    const user = req.session.user;
+    const wasAuthenticated = Boolean(user);
+    const logoutUrl = this.authService.buildLogoutUrl(this.entra.adminPostLogoutRedirectUri);
+
+    await this.sessionEstablisher.destroy({ actor: user, req });
+
+    res.clearCookie(adminSessionCookieName(), { path: '/' });
+    res.clearCookie(csrfCookieName(), { path: '/' });
+    this.logger.log(
+      { event: 'auth.signed_out', surface: 'admin', wasAuthenticated },
+      'AdminAuthLogout',
+    );
+    res.redirect(302, logoutUrl);
+  }
+
+  private redirectWithError(res: Response, kind: AuthCodeFlowError['kind']): void {
+    const url = new URL(this.entra.adminPostLogoutRedirectUri);
+    url.searchParams.set('auth_error', authErrorCode({ kind } as AuthCodeFlowError));
+    res.redirect(302, url.toString());
+  }
+}
+
+function readPreAuthCookie(req: Request): PreAuthPayload | null {
+  const raw = (req.signedCookies as Record<string, unknown>)[PRE_AUTH_COOKIE_NAME];
+  if (typeof raw !== 'string') {
+    return null;
+  }
+  try {
+    return JSON.parse(raw) as PreAuthPayload;
+  } catch {
+    return null;
+  }
+}
@@ -1,21 +1,34 @@
 import { Module } from '@nestjs/common';
+import { AuthModule } from '../auth/auth.module';
+import { AdminAuthController } from './admin-auth.controller';
 import { AdminController } from './admin.controller';
 import { AdminRoleGuard } from './admin-role.guard';

 /**
 * `AdminModule` — root of the `/api/admin/*` surface per ADR-0020.
 *
- * v1 ships the self-test endpoint only (`GET /api/admin/me`). The
- * functional admin modules (audit log viewer, CMS, menu management,
- * user list) land as separate sub-modules consumed from here once
- * the distinct admin session + the audit query endpoint are in
- * place — see the chantier sequence in `notes/handoff.md`.
+ * v1 ships:
+ *   - `GET /api/admin/me` (self-test, guarded by `@RequireAdmin`).
+ *   - `/api/admin/auth/{login,callback,me,logout}` — the distinct
+ *     admin auth flow that establishes the `__Host-portal_admin_session`
+ *     per ADR-0020 §"Sessions — distinct from `portal-shell`".
+ *
+ * Imports `AuthModule` to consume `AuthService`, `SessionEstablisher`,
+ * and `ENTRA_CONFIG` — the auth flow itself is shared with the
+ * user-portal `AuthController`; what differs is the redirect URIs
+ * passed in (admin-specific) and the session that gets populated
+ * (resolved by the path-routed session middleware in `main.ts`).
+ *
+ * The functional admin modules (audit log viewer, CMS, menu
+ * management, user list) land as separate sub-modules consumed from
+ * here in upcoming PRs.
 *
 * `AuditWriter` (required by `AdminRoleGuard`) is provided globally
- * by `AuditModule`, so no extra import is needed here.
+ * by `AuditModule`, so no extra import is needed for it.
 */
@Module({
-  controllers: [AdminController],
+  imports: [AuthModule],
+  controllers: [AdminController, AdminAuthController],
  providers: [AdminRoleGuard],
 })
 export class AdminModule {}