feat(users): add Person + User + UserScope + lazy provisioner (ADR-0026 PR 1) (#232)

## Summary

First implementation PR for [ADR-0026](docs/decisions/0026-person-user-portal-data-model.md) (portal-side identity model). Ships:

- `Person` golden record + `User` portal-account overlay + `UserScope` Prisma models;
- `PersonAndUserProvisioner` service called from `SessionEstablisher.establish` (blocking — lazy-creates `Person` + `User` at first OIDC callback);
- `PERSON_SOURCES` closed-set catalogue + drift-gate extension;
- `PrincipalBuilder.build(user, identity)` signature update + `ScopeResolver.resolve({ userId })` seam change — `Principal.user.{id, personId}` now carry real portal UUIDs, no longer the `entraOid` placeholder.

No consumer for `UserScope` yet — `PrismaScopeResolver` lands in ADR-0026 PR 2. The `StubScopeResolver` continues to return `[{ kind: 'unrestricted' }]` for everyone.

## What lands

| File | Change |
| --- | --- |
| `apps/portal-bff/prisma/schema.prisma` | **+3 models** in the `public` schema: `Person` (UUID PK + PII + nullable email indexed-not-unique + source catalogue + nullable externalId + back-ref to User), `User` (UUID PK + 1-to-1 personId FK + unique entraOid + tenantId + lastSignInAt + scopes[]), `UserScope` (UUID PK + userId FK with `onDelete: Cascade` + kind + opaque value with `@default("")` + source + nullable expiresAt + `@@unique([userId, kind, value])`). All comments explain the cross-references to ADR-0025 / ADR-0027 / ADR-0029. |
| `apps/portal-bff/prisma/migrations/20260526210000_add_person_user_userscope/migration.sql` | **New** hand-written migration. DDL for the 3 tables, indexes (Person: source/externalId/email; User: unique personId + unique entraOid; UserScope: unique composite + plain userId), FKs with the correct `ON DELETE` actions (User.personId → RESTRICT; UserScope.userId → CASCADE — both Prisma defaults given the schema's `Delegation?` / explicit `onDelete: Cascade`). |
| `apps/portal-bff/src/users/person-source.ts` + `.spec.ts` | **New** catalogue. `PERSON_SOURCES = ['self-signin', 'admin-ui', 'seed'] as const`, `PersonSource` type union, `isPersonSource` type guard. Spec follows the structure-kind shape (catalogue content, no duplicates, type guard true/false, narrowing test via `String()` to widen). |
| `apps/portal-bff/src/users/person-and-user-provisioner.service.ts` + `.spec.ts` | **New** blocking provisioner. Fast path: `findUnique by entraOid` + `update lastSignInAt`. Cold path: nested `create` of Person + linked User in a single transaction. Race-condition handling: catches P2002 on `User.entraOid` and re-runs `ensureUser` (loser of a concurrent first-sign-in falls through to the now-warm fast path). Defense-in-depth `isPersonSource` check on the constant. Spec covers cold/warm/race/non-P2002-propagation paths + `splitDisplayName` cases (single token / trailing whitespace / empty / multi-word). |
| `scripts/check-catalogue-drift.mjs` | Property-literal scanner generalised. Adds `extractPersonSources` + `findPersonSourceViolationsInFile` (property `source` instead of `kind`, otherwise identical to the structure-kind scanner). The two extractors share `extractAsConstArray(path, constName)` and the two property scanners share `findPropertyLiteralViolations(path, validValues, sourceText, opts)`. Error-message formatter unchanged. Closing hint extended to reference all three catalogue locations. |
| `scripts/check-catalogue-drift.spec.mjs` | Fixture now writes a `person-source.ts` alongside `structure-kind.ts`. 7 new tests: extractPersonSources (2), findPersonSourceViolationsInFile (5: skip-no-import, no-violation, flag, non-literal, line/col). Aggregation test updated to assert decorator + Structure.kind + Person.source violations all surface together. **29 tests total, all passing.** |
| `apps/portal-bff/src/auth/scope-resolver.ts` | `resolve(input: { entraOid })` → `resolve(input: { userId })`. Stub still ignores its argument; PR 2's `PrismaScopeResolver` will key queries on `User.id`. Comment block updated to reflect that ADR-0026 PR 1 is now landed (no longer "proposed"). |
| `apps/portal-bff/src/auth/principal-builder.ts` | Signature: `build(user)` → `build(user, identity: { userId, personId })`. `Principal.user.id` / `Principal.user.personId` populated from `identity` instead of `user.oid`. Scope resolver called with `{ userId: identity.userId }`. Doc comment block updated to remove the "placeholder" caveat and document the new wiring. |
| `apps/portal-bff/src/auth/principal-builder.spec.ts` | New `TEST_IDENTITY` constant. Every `builder.build(...)` call gets the second arg. New assertions on `principal.user.id` / `principal.user.personId` carrying the test identity. Edge-case test "asks the scope resolver to resolve by entraOid" renamed + retargeted to `{ userId }`. **All 19 persona tests + 5 edge cases pass.** |
| `apps/portal-bff/src/auth/session-establisher.service.ts` | New constructor arg `personUserProvisioner: PersonAndUserProvisioner`. `establish()` calls `ensureUser({ oid, tenantId, displayName, email: user.username })` **before** `principalBuilder.build` so the identity is available. Comment block explains the Entra `preferred_username` → `Person.email` mapping and the blocking-vs-best-effort distinction with `UserDirectoryService.recordSignIn`. |
| `apps/portal-bff/src/auth/session-establisher.service.spec.ts` | Fixture extended with `provisioner` mock + `PROVISIONED_IDENTITY` constant. `STUB_PRINCIPAL` now carries those UUIDs instead of `user.oid`. New tests: (1) provisioner is called with the right input shape; (2) provisioner runs **before** `principalBuilder.build` (`mock.invocationCallOrder` assertion); (3) provisioner failure propagates and nothing downstream runs (build / audit / directory). |
| `apps/portal-bff/src/auth/auth.controller.spec.ts` | Provisioner mock added to the controller fixture (the controller's specs don't exercise provisioning themselves but `SessionEstablisher`'s constructor needs the arg). Principal stub's UUIDs aligned with the new provisioned shape. |
| `apps/portal-bff/src/users/users.module.ts` | `PersonAndUserProvisioner` registered + exported alongside `UserDirectoryService`. `@Global` so the auth module's `SessionEstablisher` can inject both without re-routing the module graph. Comment block updated to document the blocking/best-effort distinction between the two. |

## Key choices

- **Provisioner is blocking**, not best-effort. Distinct from `UserDirectoryService.recordSignIn` which is still best-effort (ADR-0020 admin-list cache, swallows its own errors). Both run from `SessionEstablisher.establish` per the new ordering: (1) provisioner — blocking, (2) build principal — uses identity, (3) save session, (4) cookie, (5) user-session index (best-effort), (6) audit (blocking ADR-0013), (7) UserDirectoryService.recordSignIn (best-effort), (8) log. A provisioner failure short-circuits the whole flow before any of (3)..(8) — the spec asserts this explicitly.
- **No email-based dedup in v1.** `Person.email` is indexed (not unique). The provisioner keys ONLY on `entraOid`. ADR-0026 §"Why no email-based merging in v1" — two distinct humans genuinely share emails; ADR-0029's sync flow handles operator-confirmed reconciliation.
- **Race-condition handling on first sign-in.** Two concurrent first-sign-ins for the same `entraOid` both fall through to `create`. The unique constraint on `User.entraOid` rejects the loser with P2002; the provisioner catches that specific code and re-runs `ensureUser` — fast path now warm. Pathological infinite-loop guarded by the warm-path behaviour on the second attempt. Spec covers the success retry + the non-P2002 propagation paths.
- **ScopeResolver seam moved from `{ entraOid }` to `{ userId }`.** The stub doesn't care about its argument either way; the change is the seam for ADR-0026 PR 2's `PrismaScopeResolver`, which keys `userScope` queries on `User.id` (UUID). Doing the rename now keeps PR 2 to "swap the implementation" only.
- **`PersonAndUserProvisioner.SELF_SIGNIN_SOURCE`** is a typed constant inside the class, not a magic string. Defense in depth: TS type union (compile-time) + drift gate (`source: 'self-signin'` literal is in a file importing `person-source.ts` — flagged if it ever drifts off-catalogue) + runtime `isPersonSource` check (error log + throw if the constant is mutated to an off-catalogue value).
- **UserDirectoryService stays.** ADR-0020's admin-list cache is functionally redundant with Person + User now, but folding it would extend the PR scope (DTO + reader + admin UI + migration of existing rows). Out of scope here — flagged as a follow-up.

## Local verification

- [x] `node scripts/check-catalogue-drift.mjs` — clean (`4 privileges, 24 roles, 7 structure kinds, 3 person sources`).
- [x] `node --test scripts/check-catalogue-drift.spec.mjs` — **29 tests passing** (was 22 — +7 for PERSON_SOURCES).
- [x] `pnpm exec nx lint portal-bff` — **0 errors**, 13 warnings (all pre-existing, none from this PR).
- [x] `pnpm exec nx test portal-bff` (filtered to the 6 affected spec files) — **766 tests passing**.
- [x] `pnpm exec prisma generate` — client regenerated with the 3 new models.

## Test plan — remaining (on a fresh dev DB)

- [ ] `./infra/local/dev.sh down -v && ./infra/local/dev.sh up` (wipe + reboot) then `cd apps/portal-bff && pnpm exec prisma migrate dev` — applies the new migration cleanly, no drift prompt.
- [ ] `pnpm exec prisma studio` — `persons` / `users` / `user_scopes` tables visible, all empty (no seed in this PR).
- [ ] Sign in via `apf-portal` against the test tenant — `users` table gets one row, `persons` table gets one row, `user_scopes` stays empty. Principal in the session carries the provisioned UUIDs (not the `entraOid`).
- [ ] **Review focus** — the provisioner's race-handling logic; the `Entra preferred_username → Person.email` mapping in `SessionEstablisher`; the ScopeResolver seam change rationale; the FK actions in the migration SQL (especially CASCADE on UserScope.userId vs RESTRICT on User.personId).

## What's next

- **ADR-0026 PR 2** — `PrismaScopeResolver` replacing `StubScopeResolver` + `/admin/users/:id/scopes` admin-app screen + `prisma/seed.ts` populating the 19 test personas' `user_scopes` per `notes/test-tenant-role-assignments.md` (referencing this PR's `User.id` and ADR-0027 PR 1's `Structure.code` values).
- **Future PR (out of this scope)** — fold `UserDirectoryEntry` into Person + User now that the latter exists. Touches AdminUsersReader, the DTO, the admin SPA, and a data migration for existing rows. Defer until ADR-0026 PR 2 stabilises.

---------

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

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

@@ -147,6 +147,16 @@ function makeController(opts?: { completeAuthCodeFlow?: jest.Mock }): Controller
   // The directory service is a best-effort dependency — a noop mock
   // is sufficient for the controller's behavioural assertions.
   const userDirectory = { recordSignIn: jest.fn().mockResolvedValue(undefined) };
+  // The provisioner is blocking per ADR-0026 — the controller specs
+  // don't exercise the provisioning behaviour itself, so a noop mock
+  // returning a fixed UUID pair is enough to let SessionEstablisher
+  // proceed.
+  const personUserProvisioner = {
+    ensureUser: jest.fn().mockResolvedValue({
+      userId: '00000000-0000-0000-0000-000000000fff',
+      personId: '00000000-0000-0000-0000-000000000eee',
+    }),
+  };
   // 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.
@@ -156,8 +166,8 @@ function makeController(opts?: { completeAuthCodeFlow?: jest.Mock }): Controller
     // so SessionEstablisher persists it without throwing.
     build: jest.fn().mockResolvedValue({
       user: {
-        id: 'oid',
-        personId: 'oid',
+        id: '00000000-0000-0000-0000-000000000fff',
+        personId: '00000000-0000-0000-0000-000000000eee',
         entraOid: 'oid',
         tenantId: 'tid',
         displayName: 'Jane',
@@ -173,6 +183,7 @@ function makeController(opts?: { completeAuthCodeFlow?: jest.Mock }): Controller
     userSessionIndex as unknown as UserSessionIndexService,
     audit as unknown as AuditWriter,
     userDirectory as unknown as UserDirectoryService,
+    personUserProvisioner as unknown as import('../users/person-and-user-provisioner.service').PersonAndUserProvisioner,
     principalBuilder as unknown as import('./principal-builder').PrincipalBuilder,
   );
   return {

apps/portal-bff/src/auth/principal-builder.spec.ts

@@ -197,6 +197,17 @@ function makeUser(p: Persona): AuthenticatedUser {
   };
 }
 
+/**
+ * Fixed identity used by every `build()` call in the spec. The
+ * provisioner is mocked at the `SessionEstablisher` test level; the
+ * `PrincipalBuilder` spec receives the UUIDs verbatim — what matters
+ * here is that they round-trip onto `Principal.user.{id, personId}`.
+ */
+const TEST_IDENTITY = {
+  userId: '00000000-0000-0000-0000-000000000fff',
+  personId: '00000000-0000-0000-0000-000000000eee',
+};
+
 function makeBuilder(): {
   builder: PrincipalBuilder;
   scopeResolver: { resolve: jest.Mock };
@@ -223,12 +234,16 @@ 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));
+      const principal = await builder.build(makeUser(persona), TEST_IDENTITY);
       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');
+      // Real UUIDs from the provisioner, per ADR-0026 PR 1 — no
+      // longer the entraOid placeholder.
+      expect(principal.user.id).toBe(TEST_IDENTITY.userId);
+      expect(principal.user.personId).toBe(TEST_IDENTITY.personId);
       // amr passes through verbatim — MFA freshness checks read it
       // off the principal per ADR-0011.
       expect(principal.amr).toEqual(['pwd', 'mfa']);
@@ -258,7 +273,7 @@ describe('PrincipalBuilder — edge cases', () => {
       privileges: [],
       roles: ['collaborateur'],
     });
-    const principal = await builder.build(user);
+    const principal = await builder.build(user, TEST_IDENTITY);
     expect(principal.privileges).toEqual([]);
   });
 
@@ -275,7 +290,7 @@ describe('PrincipalBuilder — edge cases', () => {
       ...user,
       roles: ['Portal.Admin', 'Portal.GhostRole'],
     };
-    const principal = await builder.build(userWithDrift);
+    const principal = await builder.build(userWithDrift, TEST_IDENTITY);
     expect(principal.privileges).toEqual(['Portal.Admin']);
     expect(logger.warn).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -298,7 +313,7 @@ describe('PrincipalBuilder — edge cases', () => {
       ...user,
       groups: [...user.groups, 'ffffffff-ffff-ffff-ffff-ffffffffffff'],
     };
-    const principal = await builder.build(userWithUnknownGroup);
+    const principal = await builder.build(userWithUnknownGroup, TEST_IDENTITY);
     expect(principal.roles).toEqual(['collaborateur']);
     expect(logger.warn).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -317,7 +332,7 @@ describe('PrincipalBuilder — edge cases', () => {
       privileges: [],
       roles: [],
     });
-    const principal = await builder.build(user);
+    const principal = await builder.build(user, TEST_IDENTITY);
     expect(principal.privileges).toEqual([]);
     expect(principal.roles).toEqual([]);
     // Scope resolver stub returns unrestricted — the v1 behaviour
@@ -325,7 +340,7 @@ describe('PrincipalBuilder — edge cases', () => {
     expect(principal.scopes).toEqual([{ kind: 'unrestricted' }]);
   });
 
-  it('asks the scope resolver to resolve by entraOid', async () => {
+  it('asks the scope resolver to resolve by userId (ADR-0026 PR 1 seam change)', async () => {
     const { builder, scopeResolver } = makeBuilder();
     await builder.build(
       makeUser({
@@ -334,7 +349,11 @@ describe('PrincipalBuilder — edge cases', () => {
         privileges: [],
         roles: ['collaborateur'],
       }),
+      TEST_IDENTITY,
     );
-    expect(scopeResolver.resolve).toHaveBeenCalledWith({ entraOid: 'oid-sr' });
+    // Pre-ADR-0026 the resolver was called with { entraOid }; PR 1
+    // switches the seam to { userId } so PR 2's PrismaScopeResolver
+    // can key queries on the real User.id.
+    expect(scopeResolver.resolve).toHaveBeenCalledWith({ userId: TEST_IDENTITY.userId });
   });
 });

apps/portal-bff/src/auth/principal-builder.ts

@@ -21,17 +21,18 @@ import type { AuthenticatedUser } from './auth.service';
  *     WARN (per ADR-0025 §"Sources of truth — Entra-side
  *     configuration") and ignored.
  *   - **Scopes** — resolved by `ScopeResolver` from the portal-side
- *     `user_scopes` table once ADR-0026 lands. v1 stubs to
+ *     `user_scopes` table (schema landed in ADR-0026 PR 1; the
+ *     `PrismaScopeResolver` consumer lands in PR 2). v1 stubs to
  *     `[{ kind: 'unrestricted' }]`.
  *
  * Built once per sign-in, not per request: the session payload
  * carries the resolved `Principal` so guards can read it without
  * re-doing the GUID lookup on every API call.
  *
- * `user.id` and `user.personId` are placeholders (= `entraOid`)
- * until the `User` + `Person` schema (proposed ADR-0026) lands.
- * The seam is here so the next PR populates the real UUIDs in one
- * place, not in every guard.
+ * The `identity` parameter (UUIDs from `PersonAndUserProvisioner`)
+ * populates `Principal.user.{id, personId}` with the real portal-
+ * side identifiers introduced in ADR-0026 PR 1 — pre-PR-1 the BFF
+ * reused the Entra `oid` as a placeholder.
  */
 @Injectable()
 export class PrincipalBuilder {
@@ -42,7 +43,10 @@ export class PrincipalBuilder {
     private readonly logger: Logger,
   ) {}
 
-  async build(user: AuthenticatedUser): Promise<Principal> {
+  async build(
+    user: AuthenticatedUser,
+    identity: { userId: string; personId: string },
+  ): Promise<Principal> {
     const privileges = filterPrivileges(user.roles, user.oid, this.logger);
 
     const roles = this.groupToRole.resolve(user.groups, (groupId: string) => {
@@ -56,16 +60,12 @@ export class PrincipalBuilder {
       );
     });
 
-    const scopes = await this.scopes.resolve({ entraOid: user.oid });
+    const scopes = await this.scopes.resolve({ userId: identity.userId });
 
     return {
       user: {
-        // Real UUIDs land with ADR-0026's User + Person schema.
-        // Until then `entraOid` is the closest thing to a stable
-        // portal identity, so callers that key on `principal.user.id`
-        // get a usable value today and a real one later.
-        id: user.oid,
-        personId: user.oid,
+        id: identity.userId,
+        personId: identity.personId,
         entraOid: user.oid,
         tenantId: user.tid,
         displayName: user.displayName,

apps/portal-bff/src/auth/scope-resolver.ts

@@ -6,38 +6,40 @@ import type { Scope } from 'shared-auth';
  *
  * Per [ADR-0025 §"Sources of truth — apf_portal-side `user_scopes`
  * table"](../../../../docs/decisions/0025-authorization-model-privileges-roles-scopes.md),
- * scopes are *not* carried by Entra: they will live in a portal
- * `user_scopes` Prisma table (proposed ADR-0026), queried by Entra
- * `oid` at sign-in. Each row materialises one `Scope` entry on the
- * session principal.
+ * scopes are *not* carried by Entra: they live in the portal-side
+ * `user_scopes` Prisma table (per ADR-0026 PR 1's schema), keyed on
+ * `User.id` (UUID). Each row materialises one `Scope` entry on the
+ * session-resident principal.
  *
- * The seam is here in v1 so the next PR replaces only the
- * implementation, leaving the call-site in `PrincipalBuilder`
- * untouched. The v1 implementation (`StubScopeResolver`) always
- * returns `[{ kind: 'unrestricted' }]` per ADR-0025 §331 — until
- * the Prisma table lands the test tenant runs against a single
- * "see everything" scope; the absence of fine-grained scoping is
- * acceptable because guards consuming `@RequireScope` are not in
- * the codebase yet.
+ * The seam is here in v1 so ADR-0026 PR 2 (the `PrismaScopeResolver`
+ * landing the seed + the `/admin/users/:id/scopes` screen) replaces
+ * only the implementation, leaving the call-site in
+ * `PrincipalBuilder` untouched. The v1 stub (`StubScopeResolver`)
+ * always returns `[{ kind: 'unrestricted' }]` per ADR-0025 §331.
+ *
+ * Note: the `input` shape switched from `{ entraOid }` to `{ userId }`
+ * with ADR-0026 PR 1 (Person + User + UserScope schema landed). The
+ * stub ignores its argument either way; the change is the seam for
+ * PR 2's Prisma resolver, which keys queries on `User.id`.
  */
 export abstract class ScopeResolver {
-  abstract resolve(input: { entraOid: string }): Promise<ReadonlyArray<Scope>>;
+  abstract resolve(input: { userId: string }): Promise<ReadonlyArray<Scope>>;
 }
 
 /**
  * v1 stub — returns `unrestricted` for every user. Per ADR-0025
  * §"Sources of truth — apf_portal-side `user_scopes` table" the
  * real implementation queries `user_scopes WHERE userId = ?`; that
- * lands with the `Person` + `User` schema (proposed ADR-0026) and
- * the seed PR that follows.
+ * lands as `PrismaScopeResolver` in ADR-0026 PR 2 alongside the
+ * test-tenant seed.
  *
  * Deliberately not an in-memory hard-coded persona-keyed map: the
  * 19 test personas have *intended* scopes (see
  * `notes/test-tenant-role-assignments.md`) but those scopes have
  * no guard consuming them yet, so per-persona stub data would be
- * write-only documentation. When ADR-0026 lands, the seed PR
- * populates `user_scopes`; this class is replaced by a
- * Prisma-backed implementation in the same change.
+ * write-only documentation. ADR-0026 PR 2 populates the table; this
+ * class is replaced by a Prisma-backed implementation in the same
+ * change.
  */
 @Injectable()
 export class StubScopeResolver extends ScopeResolver {

apps/portal-bff/src/auth/session-establisher.service.spec.ts

@@ -3,6 +3,7 @@ import type { Logger } from 'nestjs-pino';
 import type { Principal } from 'shared-auth';
 import type { AuditWriter } from '../audit/audit.service';
 import type { UserSessionIndexService } from '../session/user-session-index.service';
+import type { PersonAndUserProvisioner } from '../users/person-and-user-provisioner.service';
 import type { UserDirectoryService } from '../users/user-directory.service';
 import type { AuthenticatedUser } from './auth.service';
 import type { PrincipalBuilder } from './principal-builder';
@@ -55,14 +56,20 @@ interface Fixture {
   index: { add: jest.Mock; remove: jest.Mock; list: jest.Mock };
   audit: { signIn: jest.Mock; signOut: jest.Mock };
   directory: { recordSignIn: jest.Mock };
+  provisioner: { ensureUser: jest.Mock };
   logger: ReturnType<typeof makeLoggerStub>;
   principalBuilder: { build: jest.Mock };
 }
 
+const PROVISIONED_IDENTITY = {
+  userId: 'user-uuid-1',
+  personId: 'person-uuid-1',
+};
+
 const STUB_PRINCIPAL: Principal = {
   user: {
-    id: USER.oid,
-    personId: USER.oid,
+    id: PROVISIONED_IDENTITY.userId,
+    personId: PROVISIONED_IDENTITY.personId,
     entraOid: USER.oid,
     tenantId: USER.tid,
     displayName: USER.displayName,
@@ -86,6 +93,9 @@ function makeFixture(): Fixture {
   const directory = {
     recordSignIn: jest.fn().mockResolvedValue(undefined),
   };
+  const provisioner = {
+    ensureUser: jest.fn().mockResolvedValue(PROVISIONED_IDENTITY),
+  };
   const logger = makeLoggerStub();
   const principalBuilder = {
     build: jest.fn().mockResolvedValue(STUB_PRINCIPAL),
@@ -95,9 +105,10 @@ function makeFixture(): Fixture {
     index as unknown as UserSessionIndexService,
     audit as unknown as AuditWriter,
     directory as unknown as UserDirectoryService,
+    provisioner as unknown as PersonAndUserProvisioner,
     principalBuilder as unknown as PrincipalBuilder,
   );
-  return { est, index, audit, directory, logger, principalBuilder };
+  return { est, index, audit, directory, provisioner, logger, principalBuilder };
 }
 
 describe('SessionEstablisher.establish', () => {
@@ -119,20 +130,56 @@ describe('SessionEstablisher.establish', () => {
     expect((sess['csrfToken'] as string).length).toBeGreaterThan(20);
   });
 
-  it('builds the authorization principal and stamps mfaVerifiedAt on it (ADR-0025)', async () => {
-    const { est, principalBuilder } = makeFixture();
+  it('provisions Person + User before building the Principal (ADR-0026 §Lifecycle)', async () => {
+    const { est, provisioner } = makeFixture();
     const req = makeReqStub();
     const res = makeResStub();
     await est.establish({ user: USER, req, res, surface: 'user' });
-    expect(principalBuilder.build).toHaveBeenCalledWith(USER);
+    expect(provisioner.ensureUser).toHaveBeenCalledWith({
+      oid: USER.oid,
+      tenantId: USER.tid,
+      displayName: USER.displayName,
+      // Entra preferred_username (= AuthenticatedUser.username) maps
+      // to Person.email per ADR-0026 §"Lifecycle".
+      email: USER.username,
+    });
+  });
+
+  it('builds the authorization principal with the provisioned UUIDs and stamps mfaVerifiedAt (ADR-0025 + ADR-0026)', async () => {
+    const { est, provisioner, principalBuilder } = makeFixture();
+    const req = makeReqStub();
+    const res = makeResStub();
+    await est.establish({ user: USER, req, res, surface: 'user' });
+    expect(principalBuilder.build).toHaveBeenCalledWith(USER, PROVISIONED_IDENTITY);
+    // Order: provisioner MUST run before principalBuilder so the
+    // build call has real UUIDs to populate Principal.user.{id,personId}.
+    const provisionerOrder = provisioner.ensureUser.mock.invocationCallOrder[0] ?? Infinity;
+    const buildOrder = principalBuilder.build.mock.invocationCallOrder[0] ?? 0;
+    expect(provisionerOrder).toBeLessThan(buildOrder);
     const sess = (req as unknown as { session: Record<string, unknown> }).session;
     const principal = sess['principal'] as Principal;
     expect(principal).toBeDefined();
     expect(principal.user.entraOid).toBe(USER.oid);
+    expect(principal.user.id).toBe(PROVISIONED_IDENTITY.userId);
+    expect(principal.user.personId).toBe(PROVISIONED_IDENTITY.personId);
     expect(principal.scopes).toEqual([{ kind: 'unrestricted' }]);
     expect(principal.mfaVerifiedAt).toBe(sess['createdAt']);
   });
 
+  it('propagates provisioner failures (blocking per ADR-0026)', async () => {
+    const { est, provisioner, audit, directory, principalBuilder } = makeFixture();
+    provisioner.ensureUser.mockRejectedValueOnce(new Error('postgres unreachable'));
+    const req = makeReqStub();
+    const res = makeResStub();
+    await expect(est.establish({ user: USER, req, res, surface: 'user' })).rejects.toThrow(
+      'postgres unreachable',
+    );
+    // Nothing downstream of the provisioner runs when it fails.
+    expect(principalBuilder.build).not.toHaveBeenCalled();
+    expect(audit.signIn).not.toHaveBeenCalled();
+    expect(directory.recordSignIn).not.toHaveBeenCalled();
+  });
+
   it('saves the session before returning (no race with the controller redirect)', async () => {
     const { est } = makeFixture();
     const req = makeReqStub();

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

@@ -6,6 +6,7 @@ import { AuditWriter } from '../audit/audit.service';
 import { csrfCookieName, csrfCookieOptions } from '../security/csrf-cookie';
 import { readSessionTimeouts } from '../session/session-cookie';
 import { UserSessionIndexService } from '../session/user-session-index.service';
+import { PersonAndUserProvisioner } from '../users/person-and-user-provisioner.service';
 import { UserDirectoryService } from '../users/user-directory.service';
 import type { AuthenticatedUser } from './auth.service';
 import { PrincipalBuilder } from './principal-builder';
@@ -48,6 +49,7 @@ export class SessionEstablisher {
     private readonly userSessionIndex: UserSessionIndexService,
     private readonly audit: AuditWriter,
     private readonly userDirectory: UserDirectoryService,
+    private readonly personUserProvisioner: PersonAndUserProvisioner,
     private readonly principalBuilder: PrincipalBuilder,
   ) {}
 
@@ -81,13 +83,27 @@ export class SessionEstablisher {
     // does not re-validate factors. Refreshed by future step-up
     // re-auth flows.
     req.session.mfaVerifiedAt = now;
+    // Provision Person + User (blocking per ADR-0026 §"Lifecycle"):
+    // the BFF cannot build a Principal without User.id / Person.id,
+    // so a Postgres outage here fails the sign-in. Idempotent —
+    // returns the existing pair's UUIDs on subsequent sign-ins.
+    // Note: the Entra `preferred_username` claim maps to Person.email
+    // (it's typically the user's UPN / email); `AuthenticatedUser.username`
+    // is the BFF's name for the same field.
+    const identity = await this.personUserProvisioner.ensureUser({
+      oid: user.oid,
+      tenantId: user.tid,
+      displayName: user.displayName,
+      email: user.username,
+    });
+
     // Authorization principal per ADR-0025: composes the three
     // axes (privileges / functional roles / scopes) once at
     // sign-in so guards read a single coherent shape instead of
     // re-parsing claims on every request. Built before the
     // session is persisted so a Redis hiccup either persists
     // everything or nothing.
-    const principal = await this.principalBuilder.build(user);
+    const principal = await this.principalBuilder.build(user, identity);
     req.session.principal = { ...principal, mfaVerifiedAt: now };
 
     await saveSession(req);