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

Per ADR-0025's implementation phasing, lands the closed-set
catalogues + the OIDC-callback hook that composes the
session-resident Principal. No new guards yet.

- libs/shared/auth: framework-agnostic lib hosting
  authorization.types.ts (4 privileges + 24 functional roles + 6
  scope kinds + Principal type) and entra-group-to-role.ts
  (validated GUID -> slug resolver). 17 unit tests against the
  catalogues + resolver contracts.
- BFF: PrincipalBuilder composes the three axes once at sign-in;
  ScopeResolver seam (StubScopeResolver returns unrestricted in
  v1, replaced by a Prisma-backed implementation when ADR-0026's
  user_scopes table lands). 19 persona-driven tests covering the
  test tenant's full provisioning + edge cases (unknown
  privilege drift, unknown group GUID, empty permissions).
- AuthService extracts the Entra "groups" claim; AuthenticatedUser
  grows the groups: readonly string[] field.
- SessionEstablisher builds + persists the principal alongside
  the legacy user shape (additive — guards consuming user.oid
  unchanged).
- ENTRA_GROUP_MAP_PATH env var + load-entra-group-map.ts read
  the tenant-private map from infra/<env>-tenant.entra.json
  (gitignored; .example.json committed with the schema).
- ADR-0025 path references updated from libs/feature/auth
  (Angular-scoped, scope:portal-shell) to libs/shared/auth
  (consumable by both BFF and SPA).
- notes/entra-groups-claim-activation.md: operator runbook for
  the "Token configuration -> Add groups claim" step in the
  Entra admin centre.

Test plan:
- pnpm nx affected -t lint test build : 13 projects green
  (497 BFF tests + 17 shared-auth tests + 1 shared-util test +
  full lint + full build).

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

@@ -38,11 +38,23 @@ export interface AuthCodeFlowStart {
  *     the BFF's MFA sanity-check (ADR-0011) and by `@RequireMfa`
  *     freshness checks once the session lands.
  *   - `roles`: Entra app roles assigned to this user on the BFF's
- *     app registration. Surfaced for the future `@RequireAdmin` /
- *     `@RequireRole(...)` guards (ADR-0020 admin module). Always
- *     present in the shape — an empty array means the user has no
- *     app role on this app registration, not that the claim was
- *     unparseable.
+ *     app registration. These are the four `Portal.*` *privileges*
+ *     per ADR-0025 (`Portal.Admin`, `Portal.Auditor`,
+ *     `Portal.SecurityOfficer`, `Portal.DPO`). Surfaced for the
+ *     existing `@RequireAdmin()` guard and the upcoming
+ *     `@RequirePrivilege()` decorator. Always present in the shape
+ *     — an empty array means the user has no app role on this app
+ *     registration, not that the claim was unparseable.
+ *   - `groups`: Entra security-group GUIDs the user belongs to.
+ *     Emitted by the `groups` claim once the app registration sets
+ *     `groupMembershipClaims: 'SecurityGroup'` (per ADR-0025
+ *     §"Sources of truth — Entra-side configuration"). The
+ *     `PrincipalBuilder` resolves these GUIDs to `apf-role-*` slugs
+ *     via the `EntraGroupToRoleResolver`. Always present — empty
+ *     means either the user has no group membership or the claim
+ *     was not configured on the app registration. Unknown GUIDs
+ *     are dropped at resolve time, not at extraction time, so an
+ *     audit reader still sees the raw claim.
  */
 export interface AuthenticatedUser {
   readonly oid: string;
@@ -51,6 +63,7 @@ export interface AuthenticatedUser {
   readonly displayName: string;
   readonly amr: readonly string[];
   readonly roles: readonly string[];
+  readonly groups: readonly string[];
 }
 
 /**
@@ -212,6 +225,18 @@ export class AuthService {
       ? (claims['roles'] as unknown[]).filter((v): v is string => typeof v === 'string')
       : [];
 
+    // `groups` is an optional claim (per ADR-0025 §"Sources of truth
+    // — Entra-side configuration"). Present only when the app
+    // registration sets `groupMembershipClaims: 'SecurityGroup'`.
+    // Empty array if the user is in zero security groups or the
+    // claim is not configured — both are valid "no functional
+    // roles" states the rest of the BFF must tolerate. Same
+    // string-filter as `roles` to defend against a non-string value
+    // smuggled in via a malformed token.
+    const groups = Array.isArray(claims['groups'])
+      ? (claims['groups'] as unknown[]).filter((v): v is string => typeof v === 'string')
+      : [];
+
     return {
       oid: requireString(claims['oid'], 'oid'),
       tid: requireString(claims['tid'], 'tid'),
@@ -225,6 +250,7 @@ export class AuthService {
           : (result.account?.name ?? ''),
       amr,
       roles,
+      groups,
     };
   }
 }