feat(portal-bff): entra config foundation — boot validator + auth module (#102)

## Summary

First step of ADR-0009 wiring on the BFF: capture the Entra app-registration env vars in the boot pipeline so subsequent PRs can plug `@azure/msal-node` onto a typed, already-validated config without re-reading `process.env`. **No MSAL client, no OIDC routes, no session integration yet** — those land in follow-up PRs.

## What lands

- **[`.env.example`](apps/portal-bff/.env.example)** promotes the Entra block from its previous "future-vars" comment stub to an active section. Six keys:
  - `ENTRA_INSTANCE_URL` — the Microsoft login endpoint (e.g. `https://login.microsoftonline.com/`).
  - `ENTRA_TENANT_ID`, `ENTRA_CLIENT_ID`, `ENTRA_CLIENT_SECRET` — the values from the Entra app-registration UI.
  - `ENTRA_REDIRECT_URI`, `ENTRA_POST_LOGOUT_REDIRECT_URI` — consumed by the OIDC routes in a follow-up PR.

  Multi-tenant `ENTRA_ACCEPTED_TENANT_IDS` stays in the future-vars comment until External ID activation (ADR-0008 phase 2).

- **[`apps/portal-bff/src/config/check-entra-config.ts`](apps/portal-bff/src/config/check-entra-config.ts)** — boot-time validator mirroring `check-database-url.ts`. Verifies every required key is present, the instance URL is `https://` and ends with `/`, tenant + client IDs are UUIDs, none of them are the literal placeholder values from `.env.example`, and the two redirect URIs parse as URLs. Returns a typed `EntraConfig` object with a pre-computed `authority` field (`${instanceUrl}${tenantId}`) so the future MSAL factory does not re-derive it.

- **[`auth.module.ts`](apps/portal-bff/src/auth/auth.module.ts)** — `AuthModule` whose v1 surface is one provider: the parsed `EntraConfig` keyed by the `ENTRA_CONFIG` injection token. Factory delegates to `assertEntraConfig()`. Non-global on purpose — consumers state intent by importing the module.

- **Bootstrap wiring** — `main.ts` calls `assertEntraConfig()` alongside `assertDatabaseUrl()` so misconfiguration fails fast at boot rather than mid-request (per ADR-0018 §"BFF env-var loading"). `AppModule` imports `AuthModule`.

## Naming choice

Chose `ENTRA_*` rather than `AZURE_AD_*` to align with the ADR text (Microsoft Entra ID, post-2023 rebrand). The values you copy from the Entra app-registration UI go into `apps/portal-bff/.env` (git-ignored).

## Decisions worth flagging

- **Validator called twice** — once in `main.ts` (boot-time fail-fast) and once in the `AuthModule` factory (to obtain the value for DI). Both reads are idempotent and trivially cheap. The duplication is intentional: boot-time gives a clear, pre-NestFactory error; the factory call surfaces the typed value to consumers.
- **No `@azure/msal-node` dependency added yet** — introducing the dep without a consumer would be a smell. Lands in the next PR alongside the MSAL client factory.
- **Pre-computed `authority`** in the parsed config rather than letting each MSAL consumer concatenate `instanceUrl + tenantId`. One place to change if the multi-tenant authority (`/organizations`, `/common`) replaces the tenant-scoped one when External ID activates.

## Verification

- `nx run-many -t lint test build --projects=portal-bff` — green.
- **29 / 29 specs** (was 20; +9 from the new entra-config spec + auth.module spec).
- Boot smoke test (manual): with the placeholder values in `.env.example`, `nx serve portal-bff` aborts immediately with `ENTRA_CLIENT_ID is still the .env.example placeholder (…)`. With real values in a local `.env`, the BFF starts normally.

## Test plan

- [x] Lint + test + build green.
- [x] Validator unit-test covers happy path + every documented failure mode.
- [ ] Manual: drop the real Entra values you obtained into `apps/portal-bff/.env`, `nx serve portal-bff` boots clean.
- [ ] Manual: temporarily blank out one of the four `ENTRA_*` keys → BFF aborts at boot with a clear message naming the missing key.

## Next PRs on the auth track

1. Install `@azure/msal-node`, add the `MsalConfidentialClient` factory provider in `AuthModule`, expose it via DI.
2. First OIDC routes: `/api/auth/login` (PKCE-initiated redirect to Entra) + `/api/auth/callback` (token exchange + ID-token validation, audit-logged, no session persistence yet).
3. Session persistence per ADR-0010 (Redis + AES-GCM, `__Host-portal_session` cookie). Closes the auth loop.
4. RP-initiated logout, CSRF protection, route guards.

---------

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

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

@@ -0,0 +1,48 @@
+import { Test } from '@nestjs/testing';
+import { AuthModule } from './auth.module';
+import { ENTRA_CONFIG, type EntraConfig } from './entra-config.token';
+
+const VALID = {
+  ENTRA_INSTANCE_URL: 'https://login.microsoftonline.com/',
+  ENTRA_TENANT_ID: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+  ENTRA_CLIENT_ID: '11111111-2222-3333-4444-555555555555',
+  ENTRA_CLIENT_SECRET: 's3cret-value-from-entra',
+  ENTRA_REDIRECT_URI: 'http://localhost:3000/api/auth/callback',
+  ENTRA_POST_LOGOUT_REDIRECT_URI: 'http://localhost:4200/',
+};
+
+describe('AuthModule', () => {
+  const originalEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const key of Object.keys(VALID) as Array<keyof typeof VALID>) {
+      originalEnv[key] = process.env[key];
+      process.env[key] = VALID[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const key of Object.keys(VALID) as Array<keyof typeof VALID>) {
+      const saved = originalEnv[key];
+      if (saved === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = saved;
+      }
+    }
+  });
+
+  it('provides EntraConfig via the ENTRA_CONFIG token', async () => {
+    const ref = await Test.createTestingModule({ imports: [AuthModule] }).compile();
+    const config = ref.get<EntraConfig>(ENTRA_CONFIG);
+    expect(config.clientId).toBe(VALID.ENTRA_CLIENT_ID);
+    expect(config.authority).toBe(`${VALID.ENTRA_INSTANCE_URL}${VALID.ENTRA_TENANT_ID}`);
+  });
+
+  it('fails to compile when an env var is missing', async () => {
+    delete process.env['ENTRA_CLIENT_SECRET'];
+    await expect(Test.createTestingModule({ imports: [AuthModule] }).compile()).rejects.toThrow(
+      /ENTRA_CLIENT_SECRET/,
+    );
+  });
+});

apps/portal-bff/src/auth/auth.module.ts

@@ -0,0 +1,28 @@
+import { Module } from '@nestjs/common';
+import { assertEntraConfig } from '../config/check-entra-config';
+import { ENTRA_CONFIG } from './entra-config.token';
+
+/**
+ * Auth module — owns the Entra ID configuration and (in subsequent
+ * PRs) the MSAL Node confidential client, the OIDC routes, the
+ * session integration, and the route guards. Per ADR-0009.
+ *
+ * v1 of this module exposes a single provider: the parsed Entra
+ * config, available via the `ENTRA_CONFIG` injection token. The
+ * factory delegates to `assertEntraConfig()` — the same validator
+ * `main.ts` calls at boot — so the typed config object that
+ * consumers receive is guaranteed to be complete and well-formed.
+ * The duplicate call is intentional: boot-time fails fast, the
+ * factory parses again for the DI result. Both reads are
+ * idempotent and trivially cheap.
+ */
+@Module({
+  providers: [
+    {
+      provide: ENTRA_CONFIG,
+      useFactory: () => assertEntraConfig(),
+    },
+  ],
+  exports: [ENTRA_CONFIG],
+})
+export class AuthModule {}

apps/portal-bff/src/auth/entra-config.token.ts

@@ -0,0 +1,15 @@
+import type { EntraConfig } from '../config/check-entra-config';
+
+/**
+ * DI token used to inject the parsed Entra configuration.
+ *
+ * Usage:
+ *   @Inject(ENTRA_CONFIG) private readonly entra: EntraConfig
+ *
+ * The provider lives in `AuthModule` — modules that need the config
+ * import `AuthModule` (not a global module on purpose; "I depend on
+ * auth" is worth stating in code).
+ */
+export const ENTRA_CONFIG = 'ENTRA_CONFIG';
+
+export type { EntraConfig };