feat(auth): authorization catalogues + Principal builder skeleton (ADR-0025) (#206)

## Summary First implementation PR after [ADR-0025](docs/decisions/0025-authorization-model-privileges-roles-scopes.md) was accepted in #205. Lands the closed-set catalogues + the OIDC-callback hook that composes the session-resident `Principal`. No new guards yet — those come in the next PR per the ADR's `§More Information` phasing. ## What lands **New shared library: `libs/shared/auth/`** (`scope:shared`, `type:shared`, framework-agnostic, vitest) | File | Role | | --- | --- | | `src/lib/authorization.types.ts` | Closed catalogues: `PRIVILEGES` (4), `FUNCTIONAL_ROLES` (24), `SCOPE_KINDS` (6). `Principal`, `Scope` types. `isPrivilege` / `isFunctionalRole` / `isScopeKind` type-guards for the drift gate. | | `src/lib/entra-group-to-role.ts` | `parseEntraGroupMap` (validates GUID + slug closedness + dedup) + `EntraGroupToRoleResolver` (translates the Entra `groups` claim into ordered `apf-role-*` slugs, reports unknown GUIDs via callback). | | `src/lib/*.spec.ts` | 17 unit tests against the catalogue counts + resolver contracts. | **BFF wiring** (`apps/portal-bff/src/auth/` + `src/config/`) | File | Role | | --- | --- | | `auth.service.ts` | Extracts the Entra `groups` claim. `AuthenticatedUser` grows `groups: readonly string[]`. | | `principal-builder.ts` | Composes the three axes at sign-in. Filters `roles` claim through `isPrivilege` (drops + WARNs on unknown), resolves `groups` claim through the `EntraGroupToRoleResolver` (drops + WARNs on unknown). | | `scope-resolver.ts` | `ScopeResolver` abstract class + `StubScopeResolver` returning `[{ kind: 'unrestricted' }]` (per ADR-0025 §331 — replaced by a Prisma implementation when ADR-0026's `user_scopes` table lands). | | `session-establisher.service.ts` | Calls `PrincipalBuilder.build()` once, persists the result as `req.session.principal`. The legacy `req.session.user` shape is untouched (audit + AI bridge keep working). | | `session.types.ts` | Adds optional `principal?: Principal` field on the express-session augmentation. | | `entra-group-to-role.token.ts` | DI token for the lazily-loaded resolver. | | `config/load-entra-group-map.ts` | Reads the gitignored `infra/<env>-tenant.entra.json` at boot. Missing path → empty resolver + WARN. Malformed file → hard fail (alternative would be silently dropping a role). | **Tests against the 19 test-tenant personas** (`principal-builder.spec.ts`) Every persona provisioned in `apfrd.onmicrosoft.com` on 2026-05-20 is exercised end-to-end: `admin`, `directeur-bordeaux`, `directeur-complexe`, `rh-aquitaine`, `rh-siege`, `collaborateur-simple`, `tresorier-bordeaux`, `dpo`, `it`, `benevole-aquitaine`, `chef-equipe-bordeaux`, `chef-service-bordeaux`, `directeur-territorial-aquitaine`, `juriste-siege`, `rssi`, `communication-siege`, `elu-ca-national`, `president-cd-aquitaine`, `secretaire-cd-aquitaine`. A coverage assertion confirms the personas cover all 4 privileges + 23 of 24 functional roles (the `partenaire` gap is intentional per ADR-0025). **Infra + docs** | File | Change | | --- | --- | | `infra/test-tenant.entra.example.json` | Template GUID → slug map (24 entries, full v1 catalogue). Real file (`*-tenant.entra.json`) gitignored. | | `infra/README.md` | New row + "Entra group map" section documenting the load semantics + provisioning workflow. | | `apps/portal-bff/.env.example` | New `ENTRA_GROUP_MAP_PATH` block. | | `.gitignore` | `infra/*-tenant.entra.json` (except `.example.json`). | | `tsconfig.base.json` | `shared-auth` path alias. | | `notes/entra-groups-claim-activation.md` | Operator runbook for the Entra admin-centre step (Token configuration → Add groups claim → Security groups → Group ID). | **ADR amendment** | File | Change | | --- | --- | | `docs/decisions/0025-authorization-model-privileges-roles-scopes.md` | Path references updated `libs/feature/auth/...` → `libs/shared/auth/...` (4 occurrences), and the `ENTRA_GROUP_TO_ROLE` static-record example replaced by the actual `EntraGroupToRoleResolver` + JSON shape. | ## Notes for the reviewer - **Why `libs/shared/auth/` and not `libs/feature/auth/` (as the ADR initially said).** The existing `libs/feature/auth/` carries `tags: ['scope:portal-shell', 'type:feature']`, which the Nx `enforce-module-boundaries` rule in `eslint.config.mjs:36-46` blocks the BFF from importing. The catalogue is needed by both sides (BFF builds the `Principal`, SPA will gate UI conditionally later), so a `scope:shared` lib is the correct home. The ADR is patched in the same PR so the document and the code agree. - **Why drop unknown privileges with a WARN instead of preserving them.** `Portal.GhostRole` in the `roles` claim is either a leftover from a different app registration or a v1+1 experiment that hasn't been added to the catalogue yet. Both paths should not silently grant access — drop with a WARN so an operator notices, and the drift CI gate (next PR) catches the source-side equivalent before merge. - **Why the principal builder uses a `ScopeResolver` seam now.** Per ADR-0025 §331 the v1 implementation returns `unrestricted` for everyone; the real version queries the `user_scopes` Prisma table that lands with ADR-0026. The seam is here so the next PR replaces only the implementation, not the call-site in `PrincipalBuilder` or its 24 tests. Per-persona stub scope data was deliberately not embedded in this PR — no guard consumes scopes yet, so it would be write-only documentation that drifts from the eventual Prisma seed. - **Why `user.id` and `user.personId` placeholder to `entraOid`.** Same logic: the real UUIDs land with the `Person` + `User` Prisma schema (proposed ADR-0026). Until then, populating both fields with `entraOid` lets consumers key on `principal.user.id` today and get a real value later without branching on availability. The seam is one place (in the builder), not 24 guards. - **Why session.types.ts carries both `user` and `principal`.** Additive instead of replacement: the audit module + the AI-bridge controller key on `user.oid` / `user.tid` directly, and migrating them in the same PR would balloon the diff for zero behavioural benefit. New consumers (`@RequirePrivilege` / `@RequireRole` / `@RequireScope` decorators, next PR) reach for `principal`. - **Map file fails soft on absence, hard on malformation.** Path unset OR file missing → empty resolver + WARN. Sign-in still succeeds, every user gets `roles: []`. This is deliberately fail-soft so a fresh dev environment isn't blocked by an Entra-side dependency. **Bad JSON / unknown slug / duplicate GUID → throws at boot.** The alternative would silently mis-resolve a role. - **Why `boot-time` validation only (no per-request)** for the map file. Catalogue drift is detected once at boot; per-request validation would re-read the file from disk on every sign-in. The trade-off is that a hot-edit to the file requires a BFF restart — acceptable because the file changes once per tenant lifecycle, not per session. - **Entra `groups` claim must be activated** on the BFF's app registration before this code does anything useful. The runbook in `notes/entra-groups-claim-activation.md` walks through the steps; if the claim isn't activated, every user signs in with `principal.roles = []` and a future warn for every group GUID that would have arrived (none, in that case). - **No drift gate yet.** ADR-0025's §"Confirmation" §346 calls for an ESLint custom rule (or `pnpm run` script) that greps every `@RequireRole('...')` literal and asserts membership in the catalogue. That's the third PR in the phasing — there's no `@RequireRole` consumer in the tree yet, so the gate would have nothing to assert against today. ## Test plan - [x] `pnpm nx affected -t lint test build --base=main` — 13 projects green - 497 BFF tests (was 465 — added 4 new `groups`-claim tests in `auth.service.spec.ts`, 1 new test in `session-establisher.service.spec.ts`, 6 new tests in `load-entra-group-map.spec.ts`, 24 new tests in `principal-builder.spec.ts`) - 17 `shared-auth` tests (catalogue counts + resolver contracts) - 1 `shared-util` test (unchanged) - full lint + full build - [x] `pnpm nx format:check` — clean after `pnpm nx format:write` - [x] Manual: `tsc --build libs/shared/auth/tsconfig.lib.json` emits `.d.ts` files at the path `portal-bff`'s webpack expects. - [ ] **Review focus** — the closed catalogues (`PRIVILEGES`, `FUNCTIONAL_ROLES`, `SCOPE_KINDS`) verbatim match ADR-0025; the 19 personas verbatim match `notes/test-tenant-role-assignments.md`; the `Principal` shape matches the ADR §"Principal shape" (modulo the `user.id` / `personId` placeholder); fail-soft on missing map file, hard on malformed. - [ ] **After merge — operator step** : activate the Entra `groups` claim per `notes/entra-groups-claim-activation.md` and drop the real GUIDs into `infra/test-tenant.entra.json` (gitignored). Then a sign-in with `admin@apfrd.onmicrosoft.com` should land `principal.privileges = ['Portal.Admin']` and `principal.roles = ['collaborateur', 'rh']` in Redis. ## What's next Per ADR-0025 §"More Information" phasing: 1. ✅ **This PR** — types + Principal builder + group-to-role mapping skeleton. 2. **Next PR** — `@RequirePrivilege` + `@RequireRole` + `@RequireScope` decorators + guard integration tests against the 19 personas. 3. **PR after that** — drift CI gate (ESLint custom rule asserting every `@RequireX('...')` literal is in the catalogue). 4. **Depends on ADR-0026** — `user_scopes` Prisma table + seed + `PrismaScopeResolver` replacing `StubScopeResolver`. --------- Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr> Reviewed-on: #206
2026-05-23 21:09:13 +02:00
parent c9a1e195fe
commit 12136f7a8a
35 changed files with 1709 additions and 29 deletions
@@ -0,0 +1,340 @@
+import type { Logger } from 'nestjs-pino';
+import {
+  EntraGroupToRoleResolver,
+  parseEntraGroupMap,
+  type FunctionalRole,
+  type Scope,
+} from 'shared-auth';
+import type { AuthenticatedUser } from './auth.service';
+import { PrincipalBuilder } from './principal-builder';
+import type { ScopeResolver } from './scope-resolver';
+
+/**
+ * Mirrors the 24-entry `apf-role-*` catalogue: one synthetic GUID
+ * per slug, in catalogue order. The exact GUIDs do not matter to
+ * any assertion below — what matters is that the test resolver
+ * maps them deterministically so a persona's `groups` claim can
+ * be assembled by slug.
+ */
+const ROLE_GUID: Record<FunctionalRole, string> = {
+  collaborateur: '00000000-0000-0000-0000-000000000101',
+  'chef-equipe': '00000000-0000-0000-0000-000000000102',
+  'chef-service': '00000000-0000-0000-0000-000000000103',
+  'directeur-etablissement': '00000000-0000-0000-0000-000000000104',
+  'directeur-territorial': '00000000-0000-0000-0000-000000000105',
+  rh: '00000000-0000-0000-0000-000000000106',
+  'responsable-paie': '00000000-0000-0000-0000-000000000107',
+  comptable: '00000000-0000-0000-0000-000000000108',
+  juriste: '00000000-0000-0000-0000-000000000109',
+  dpo: '00000000-0000-0000-0000-00000000010a',
+  rssi: '00000000-0000-0000-0000-00000000010b',
+  it: '00000000-0000-0000-0000-00000000010c',
+  formation: '00000000-0000-0000-0000-00000000010d',
+  qualite: '00000000-0000-0000-0000-00000000010e',
+  communication: '00000000-0000-0000-0000-00000000010f',
+  'elu-ca': '00000000-0000-0000-0000-000000000110',
+  'elu-cd': '00000000-0000-0000-0000-000000000111',
+  'elu-cd-president': '00000000-0000-0000-0000-000000000112',
+  'elu-cd-tresorier': '00000000-0000-0000-0000-000000000113',
+  'elu-cd-secretaire': '00000000-0000-0000-0000-000000000114',
+  delegue: '00000000-0000-0000-0000-000000000115',
+  benevole: '00000000-0000-0000-0000-000000000116',
+  'benevole-responsable': '00000000-0000-0000-0000-000000000117',
+  partenaire: '00000000-0000-0000-0000-000000000118',
+};
+
+/**
+ * The 19 personas provisioned in the `apfrd.onmicrosoft.com` test
+ * tenant on 2026-05-20, transcribed from
+ * `notes/test-tenant-role-assignments.md` (reverse view). The
+ * builder's contract is that these inputs round-trip to the
+ * expected `(privileges, roles, scopes)` triple — when the spec
+ * passes, every persona we documented in the ADR is exercised
+ * end-to-end.
+ *
+ * Scopes are stubbed to `[{ kind: 'unrestricted' }]` for every
+ * persona in v1 per ADR-0025 §"Sources of truth — apf_portal-side
+ * `user_scopes` table". The intended per-persona scopes
+ * (`etablissement:…`, `delegation:33`, …) land with the Prisma
+ * `user_scopes` table — the next PR after this skeleton.
+ */
+interface Persona {
+  readonly label: string;
+  readonly username: string;
+  readonly privileges: readonly string[]; // raw `roles` claim values
+  readonly roles: readonly FunctionalRole[];
+}
+
+const PERSONAS: readonly Persona[] = [
+  {
+    label: 'admin',
+    username: 'admin@apfrd.onmicrosoft.com',
+    privileges: ['Portal.Admin'],
+    roles: ['collaborateur', 'rh'],
+  },
+  {
+    label: 'directeur-bordeaux',
+    username: 'directeur-bordeaux@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'directeur-etablissement'],
+  },
+  {
+    label: 'directeur-complexe',
+    username: 'directeur-complexe@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'directeur-etablissement'],
+  },
+  {
+    label: 'rh-aquitaine',
+    username: 'rh-aquitaine@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'rh', 'formation'],
+  },
+  {
+    label: 'rh-siege',
+    username: 'rh-siege@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'rh', 'responsable-paie', 'comptable'],
+  },
+  {
+    label: 'collaborateur-simple',
+    username: 'collaborateur-simple@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur'],
+  },
+  {
+    label: 'tresorier-bordeaux',
+    username: 'tresorier-bordeaux@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['elu-cd', 'elu-cd-tresorier'],
+  },
+  {
+    label: 'dpo',
+    username: 'dpo@apfrd.onmicrosoft.com',
+    privileges: ['Portal.DPO', 'Portal.Auditor'],
+    roles: ['collaborateur', 'dpo', 'qualite'],
+  },
+  {
+    label: 'it',
+    username: 'it@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'it'],
+  },
+  {
+    label: 'benevole-aquitaine',
+    username: 'benevole-aquitaine@apfrd.onmicrosoft.com',
+    privileges: [],
+    // Catalogue order: delegue (governance) precedes benevole +
+    // benevole-responsable (volunteer). The resolver re-sorts on
+    // catalogue order regardless of the Entra claim's order.
+    roles: ['delegue', 'benevole', 'benevole-responsable'],
+  },
+  {
+    label: 'chef-equipe-bordeaux',
+    username: 'chef-equipe-bordeaux@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'chef-equipe'],
+  },
+  {
+    label: 'chef-service-bordeaux',
+    username: 'chef-service-bordeaux@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'chef-service'],
+  },
+  {
+    label: 'directeur-territorial-aquitaine',
+    username: 'directeur-territorial-aquitaine@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'directeur-territorial'],
+  },
+  {
+    label: 'juriste-siege',
+    username: 'juriste-siege@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'juriste'],
+  },
+  {
+    label: 'rssi',
+    username: 'rssi@apfrd.onmicrosoft.com',
+    privileges: ['Portal.SecurityOfficer'],
+    roles: ['collaborateur', 'rssi'],
+  },
+  {
+    label: 'communication-siege',
+    username: 'communication-siege@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['collaborateur', 'communication'],
+  },
+  {
+    label: 'elu-ca-national',
+    username: 'elu-ca-national@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['elu-ca'],
+  },
+  {
+    label: 'president-cd-aquitaine',
+    username: 'president-cd-aquitaine@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['elu-cd', 'elu-cd-president'],
+  },
+  {
+    label: 'secretaire-cd-aquitaine',
+    username: 'secretaire-cd-aquitaine@apfrd.onmicrosoft.com',
+    privileges: [],
+    roles: ['elu-cd', 'elu-cd-secretaire'],
+  },
+];
+
+function makeUser(p: Persona): AuthenticatedUser {
+  return {
+    oid: `oid-${p.label}`,
+    tid: 'tenant-1',
+    username: p.username,
+    displayName: p.label,
+    amr: ['pwd', 'mfa'],
+    roles: [...p.privileges],
+    groups: p.roles.map((slug) => ROLE_GUID[slug]),
+  };
+}
+
+function makeBuilder(): {
+  builder: PrincipalBuilder;
+  scopeResolver: { resolve: jest.Mock };
+  logger: { log: jest.Mock; warn: jest.Mock; error: jest.Mock };
+} {
+  const rawMap: Record<string, FunctionalRole> = {};
+  for (const [slug, guid] of Object.entries(ROLE_GUID) as Array<[FunctionalRole, string]>) {
+    rawMap[guid] = slug;
+  }
+  const resolver = new EntraGroupToRoleResolver(parseEntraGroupMap(rawMap));
+  const scopeResolver = {
+    resolve: jest.fn().mockResolvedValue([{ kind: 'unrestricted' } as Scope]),
+  };
+  const logger = { log: jest.fn(), warn: jest.fn(), error: jest.fn() };
+  const builder = new PrincipalBuilder(
+    resolver,
+    scopeResolver as unknown as ScopeResolver,
+    logger as unknown as Logger,
+  );
+  return { builder, scopeResolver, logger };
+}
+
+describe('PrincipalBuilder — 19 test-tenant personas', () => {
+  for (const persona of PERSONAS) {
+    it(`builds the principal for ${persona.label}`, async () => {
+      const { builder } = makeBuilder();
+      const principal = await builder.build(makeUser(persona));
+      expect(principal.privileges).toEqual(persona.privileges);
+      expect(principal.roles).toEqual(persona.roles);
+      expect(principal.scopes).toEqual([{ kind: 'unrestricted' }]);
+      expect(principal.user.entraOid).toBe(`oid-${persona.label}`);
+      expect(principal.user.tenantId).toBe('tenant-1');
+      // amr passes through verbatim — MFA freshness checks read it
+      // off the principal per ADR-0011.
+      expect(principal.amr).toEqual(['pwd', 'mfa']);
+    });
+  }
+
+  it('asserts the 19 personas cover all 4 privileges + 23 of 24 functional roles', () => {
+    // Coverage check baked into the spec so a regression that
+    // drops a role from a persona is caught here, not at PR review.
+    // The intentional gap is `partenaire` (placeholder per ADR-0025).
+    const privilegesUsed = new Set(PERSONAS.flatMap((p) => p.privileges));
+    expect(privilegesUsed).toEqual(
+      new Set(['Portal.Admin', 'Portal.Auditor', 'Portal.SecurityOfficer', 'Portal.DPO']),
+    );
+    const rolesUsed = new Set(PERSONAS.flatMap((p) => p.roles));
+    expect(rolesUsed.size).toBe(23);
+    expect(rolesUsed.has('partenaire')).toBe(false);
+  });
+});
+
+describe('PrincipalBuilder — edge cases', () => {
+  it('returns an empty privileges array when the user has no app role assignment', async () => {
+    const { builder } = makeBuilder();
+    const user = makeUser({
+      label: 'anon',
+      username: 'anon@example',
+      privileges: [],
+      roles: ['collaborateur'],
+    });
+    const principal = await builder.build(user);
+    expect(principal.privileges).toEqual([]);
+  });
+
+  it('drops + warns on a claim value that is not a known privilege', async () => {
+    const { builder, logger } = makeBuilder();
+    const user = makeUser({
+      label: 'stale',
+      username: 'stale@example',
+      privileges: [],
+      roles: [],
+    });
+    // Force in a non-catalogue value the way an old assignment would.
+    const userWithDrift: AuthenticatedUser = {
+      ...user,
+      roles: ['Portal.Admin', 'Portal.GhostRole'],
+    };
+    const principal = await builder.build(userWithDrift);
+    expect(principal.privileges).toEqual(['Portal.Admin']);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'auth.unknown_privilege_claim',
+        value: 'Portal.GhostRole',
+      }),
+      'PrincipalBuilder',
+    );
+  });
+
+  it('drops + warns on an unknown group GUID (tenant misconfiguration)', async () => {
+    const { builder, logger } = makeBuilder();
+    const user = makeUser({
+      label: 'ghost-group',
+      username: 'ghost-group@example',
+      privileges: [],
+      roles: ['collaborateur'],
+    });
+    const userWithUnknownGroup: AuthenticatedUser = {
+      ...user,
+      groups: [...user.groups, 'ffffffff-ffff-ffff-ffff-ffffffffffff'],
+    };
+    const principal = await builder.build(userWithUnknownGroup);
+    expect(principal.roles).toEqual(['collaborateur']);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event: 'auth.unknown_group_claim',
+        groupId: 'ffffffff-ffff-ffff-ffff-ffffffffffff',
+      }),
+      'PrincipalBuilder',
+    );
+  });
+
+  it('builds an empty-permissions principal when the user has no groups or roles', async () => {
+    const { builder } = makeBuilder();
+    const user = makeUser({
+      label: 'empty',
+      username: 'empty@example',
+      privileges: [],
+      roles: [],
+    });
+    const principal = await builder.build(user);
+    expect(principal.privileges).toEqual([]);
+    expect(principal.roles).toEqual([]);
+    // Scope resolver stub returns unrestricted — the v1 behaviour
+    // per ADR-0025 §331 until the user_scopes table lands.
+    expect(principal.scopes).toEqual([{ kind: 'unrestricted' }]);
+  });
+
+  it('asks the scope resolver to resolve by entraOid', async () => {
+    const { builder, scopeResolver } = makeBuilder();
+    await builder.build(
+      makeUser({
+        label: 'sr',
+        username: 'sr@example',
+        privileges: [],
+        roles: ['collaborateur'],
+      }),
+    );
+    expect(scopeResolver.resolve).toHaveBeenCalledWith({ entraOid: 'oid-sr' });
+  });
+});