@astram/identity 0.5.0 → 0.6.0

package/dist/features/authz/grant-admin.service.d.ts

@@ -114,9 +114,32 @@ export declare class GrantAdminService {
      * Revoke a key from a role (no-op if absent) + bump + audit, atomically. Security hardening #1:
      * the actor must be able to administer the role (binding rule) and must hold the key itself —
      * "only revoke what you hold" — so a delegated admin can no longer strip a role of authority it
-     * never had. Root bypasses.
+     * never had. Phase 8 #2: it must also dominate every user holding the role (checked under the
+     * role lock in `writeGrants`). Root bypasses.
      */
     revoke(roleUuid: string, key: string, actor: Principal): Promise<void>;
+    /**
+     * Remove a role that is being DELETED from authorization (Phase 8 #2 follow-up): every
+     * `role_permission` row of the role, and the role from every service account's `sa_role_ids`
+     * (guard's API-key store reads that column live, so a stale entry would keep the deleted role's
+     * keys on the agent). ONE transaction on the shared authz pool — the same pool, bump, audit and
+     * error mapping as {@link revoke}:
+     *   1. lock the holding accounts (`FOR UPDATE`), then check the actor may strip the role from
+     *      each (`GrantCeiling.assertMayStripRoleFromServiceAccounts`, root bypasses);
+     *   2. bump every tenant using the role — postings AND the accounts' tenants — before the strip,
+     *      so the account tenants are still found;
+     *   3. delete the role's grants; rewrite each account's role list without it (edit stamp moved
+     *      forward, so a concurrent preserve-merge edit conflicts instead of re-adding it);
+     *   4. audit as `role.permission_revoked` (`roleDeleted: true`), commit, publish the versions.
+     * Returns the bumped tenants.
+     *
+     * The CALLER (`RoleService.deleteRole`) holds the role row lock on its own engine connection and
+     * has already run the binding rule and user-holder dominance; this method therefore does NOT
+     * lock the role row (that would wait on the caller). It commits BEFORE the caller deletes the
+     * role, so a failure in between leaves a role with no grants and no agents: fewer permissions,
+     * never live grants for a deleted role (fail closed).
+     */
+    purgeRole(roleUuid: string, actor: Principal): Promise<string[]>;
     /** All active bundles + their resolved atomic keys, for the Access UI. */
     listBundles(): Promise<{
         bundles: BundleView[];

package/dist/features/authz/grant-admin.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant-admin.service.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAa,MAAM,oBAAoB,CAAC;AAmB7D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;6EAC6E;AAC7E,qBAAa,WAAY,SAAQ,KAAK;gBACxB,GAAG,EAAE,MAAM;CAIxB;AAED,KAAK,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,qBAAa,iBAAiB;IAa1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IAhBzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C;;;;;;;;OAQG;gBAEgB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,uBAAuB,EAChD,WAAW,CAAC,EAAE,iBAAiB,EACd,OAAO,CAAC,EAAE,YAAY,YAAA,EACtB,KAAK,CAAC,EAAE,SAAS,YAAA;IAKpC,+EAA+E;IACzE,WAAW,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAmC5E;;;;OAIG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA0BhC,0FAA0F;YAC5E,cAAc;IAM5B;;;;;;OAMG;YACW,qBAAqB;IAUnC;;;;;OAKG;YACW,WAAW;IA2CzB;;;;;;OAMG;YACW,gBAAgB;IA0D9B;;;;;OAKG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7E;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5E,0EAA0E;IACpE,WAAW,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IASvD;;;;;;OAMG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BzF;;;;;;OAMG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBxF,uFAAuF;YACzE,wBAAwB;IAWtC;;;;;;;;;;;;OAYG;IACG,iBAAiB,CACrB,MAAM,EACF;QACE,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;KAC5B,GACD,SAAS,EACb,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC;QAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAgIrF"}
+{"version":3,"file":"grant-admin.service.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-admin.service.ts"],"names":[],"mappings":"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"}

package/dist/features/authz/grant-admin.service.js

@@ -9,6 +9,24 @@ const role_binding_js_1 = require("./role-binding.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
 const AUTHZ = 'shield_authz';
 const APP = 'shield_app';
+/** The grant-admin actions that REMOVE authority from a role's holders (Phase 8 #2). */
+const REVOKE_ACTIONS = new Set([
+    'role.permission_revoked',
+    'role.bundle_revoked',
+]);
+/** A JSON-array column (the driver returns an array OR a string) → its string items; else []. */
+function jsonIdArray(v) {
+    let arr = v;
+    if (typeof v === 'string') {
+        try {
+            arr = JSON.parse(v);
+        }
+        catch {
+            arr = [];
+        }
+    }
+    return Array.isArray(arr) ? arr.filter((x) => typeof x === 'string') : [];
+}
 /** A granted key was not in the catalog and is not a recognized wildcard. The
  *  controller maps this to HTTP 400 (distinct from a store outage → 503). */
 class BadKeyError extends Error {
@@ -133,6 +151,11 @@ class GrantAdminService {
             ]);
             if (this.ceiling && actor.isRoot !== true) {
                 grant_ceiling_js_1.GrantCeiling.checkAdministrable(await (0, role_binding_js_1.readRoleBinding)(conn, roleUuid, (0, grant_ceiling_js_1.subtreeOf)(actor)));
+                // Phase 8 #2: a revocation strips authority from every holder of the role, so the actor
+                // must dominate each of them — checked under the role lock (no holder can appear unseen).
+                if (REVOKE_ACTIONS.has(action)) {
+                    await this.ceiling.assertDominatesRoleHolders(actor, roleUuid);
+                }
             }
             for (const key of keys)
                 await statement(conn, key);
@@ -230,7 +253,8 @@ class GrantAdminService {
      * Revoke a key from a role (no-op if absent) + bump + audit, atomically. Security hardening #1:
      * the actor must be able to administer the role (binding rule) and must hold the key itself —
      * "only revoke what you hold" — so a delegated admin can no longer strip a role of authority it
-     * never had. Root bypasses.
+     * never had. Phase 8 #2: it must also dominate every user holding the role (checked under the
+     * role lock in `writeGrants`). Root bypasses.
      */
     async revoke(roleUuid, key, actor) {
         await this.assertMayChangeGrants(roleUuid, [key], actor);
@@ -238,6 +262,69 @@ class GrantAdminService {
             await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?`, [roleUuid, k]);
         });
     }
+    /**
+     * Remove a role that is being DELETED from authorization (Phase 8 #2 follow-up): every
+     * `role_permission` row of the role, and the role from every service account's `sa_role_ids`
+     * (guard's API-key store reads that column live, so a stale entry would keep the deleted role's
+     * keys on the agent). ONE transaction on the shared authz pool — the same pool, bump, audit and
+     * error mapping as {@link revoke}:
+     *   1. lock the holding accounts (`FOR UPDATE`), then check the actor may strip the role from
+     *      each (`GrantCeiling.assertMayStripRoleFromServiceAccounts`, root bypasses);
+     *   2. bump every tenant using the role — postings AND the accounts' tenants — before the strip,
+     *      so the account tenants are still found;
+     *   3. delete the role's grants; rewrite each account's role list without it (edit stamp moved
+     *      forward, so a concurrent preserve-merge edit conflicts instead of re-adding it);
+     *   4. audit as `role.permission_revoked` (`roleDeleted: true`), commit, publish the versions.
+     * Returns the bumped tenants.
+     *
+     * The CALLER (`RoleService.deleteRole`) holds the role row lock on its own engine connection and
+     * has already run the binding rule and user-holder dominance; this method therefore does NOT
+     * lock the role row (that would wait on the caller). It commits BEFORE the caller deletes the
+     * role, so a failure in between leaves a role with no grants and no agents: fewer permissions,
+     * never live grants for a deleted role (fail closed).
+     */
+    async purgeRole(roleUuid, actor) {
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            const accounts = (await conn.query(`SELECT sa_id, sa_tenant_id, sa_role_ids, sa_updated_at_ms
+           FROM \`${APP}\`.\`service_account\`
+          WHERE JSON_CONTAINS(sa_role_ids, JSON_QUOTE(?))
+          FOR UPDATE`, [roleUuid]));
+            if (this.ceiling && actor.isRoot !== true) {
+                await this.ceiling.assertMayStripRoleFromServiceAccounts(actor, roleUuid, accounts.map((a) => a.sa_tenant_id));
+            }
+            const keys = (await conn.query(`SELECT rp_perm_key FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? ORDER BY rp_perm_key`, [roleUuid])).map((r) => r.rp_perm_key);
+            const bumped = await this.bumper.bumpForRole(roleUuid, conn);
+            await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ?`, [
+                roleUuid,
+            ]);
+            const nowMs = Date.now();
+            for (const a of accounts) {
+                const remaining = jsonIdArray(a.sa_role_ids).filter((id) => id !== roleUuid);
+                const previous = a.sa_updated_at_ms === null ? 0 : Number(a.sa_updated_at_ms);
+                await conn.query(`UPDATE \`${APP}\`.\`service_account\` SET sa_role_ids = ?, sa_updated_at_ms = ? WHERE sa_id = ?`, [JSON.stringify(remaining), Math.max(nowMs, previous + 1), a.sa_id]);
+            }
+            await this.auditGrantChange(conn, 'role.permission_revoked', roleUuid, keys, actor, bumped, {
+                roleDeleted: true,
+                serviceAccountsUpdated: accounts.length,
+            });
+            await conn.commit();
+            await this.bumper.publishCommitted(conn);
+            return bumped;
+        }
+        catch (cause) {
+            await conn.rollback();
+            this.bumper.discardPending(conn);
+            if (cause instanceof identity_errors_js_1.IdentityForbiddenError || cause instanceof identity_errors_js_1.IdentityNotFoundError) {
+                throw cause;
+            }
+            throw new core_1.AuthorizationUnavailableError('role grant purge failed', cause);
+        }
+        finally {
+            await conn.release();
+        }
+    }
     // ── Access bundles ────────────────────────────────────────────────────────
     /** All active bundles + their resolved atomic keys, for the Access UI. */
     async listBundles() {

package/dist/features/authz/grant-ceiling.d.ts

@@ -81,9 +81,18 @@ export declare class GrantCeiling {
      * Assert the actor may ASSIGN every role in `roleIds` (post someone to it): the roles' effective
      * keys (their `role_permission` rows, wildcards expanded against the registry) must all be held
      * by the actor — the same "only grant what you hold" ceiling, applied to role assignment (#11).
-     * A role holding nothing assigns nothing and passes. Root bypasses. Store outage → 503.
+     * A role holding nothing assigns nothing and passes; a role key the registry does not know
+     * counts as not held (Phase 8 #4). Root bypasses. Store outage → 503.
      */
     assertCanAssignRoles(actor: Principal, roleIds: readonly string[]): Promise<void>;
+    /**
+     * The first of a TARGET's raw keys (a role's `role_permission` rows) the actor does not cover,
+     * or `undefined` when all are covered. Phase 8 #4: judged per RAW key with `coversKey`, so a key
+     * the registry does not know — an exact key that is not registered, or a wildcard expanding to
+     * nothing — counts as NOT held and denies. Expanding first would silently drop it and could
+     * pass vacuously (fail open) when this registry is narrower than the decision path's.
+     */
+    private firstUncovered;
     /**
      * Assert the actor DOMINATES the target user (#3, D2): every membership the target holds (in any
      * tenant, active or not) is inside the actor's subtree, AND every key the target could hold
@@ -92,6 +101,45 @@ export declare class GrantCeiling {
      * Root actors bypass. Store outage → 503.
      */
     assertDominates(actor: Principal, targetUserId: string): Promise<void>;
+    /**
+     * Assert the actor DOMINATES every user who holds the role (Phase 8 #2): deleting a role, or
+     * revoking a key from it, strips authority from each holder, so it needs the same
+     * {@link assertDominates} the actor would need to change any one of them directly. Holders are
+     * the users with a posting of the role in any membership and any window (potential authority).
+     * The actor itself is skipped: giving up your own authority stays allowed (self-demotion).
+     * Service-account holders: a revoke is covered by the binding rule (`assertRoleAdministrable`:
+     * no binding outside the actor's subtree) plus "only revoke what you hold"; a role DELETE also
+     * strips the role from each account and checks {@link assertMayStripRoleFromServiceAccounts}.
+     * Root bypasses. Store outage → 503.
+     *
+     * Callers serialise against a concurrent posting by locking the role row first (the posting
+     * path locks the same row before it inserts), then call this — so no holder appears unseen.
+     */
+    assertDominatesRoleHolders(actor: Principal, roleUuid: string): Promise<void>;
+    /**
+     * Assert the actor may REMOVE `roleUuid` from every service account holding it (Phase 8 #2
+     * follow-up: a role delete strips the role from each holding account). Judged by the SAME rules
+     * as editing the account directly (`ServiceAccountService.update`, ADR-0029 ceiling via
+     * {@link ceilingOf}): each account's tenant is inside the actor's subtree, and the role is one
+     * the actor holds itself — a non-root admin's edit preserves (cannot strip) a role it does not
+     * hold. `accountTenantIds` are the holding accounts' tenants, read by the caller under a row lock.
+     * Root bypasses. Refusals name no account. Store outage → 503.
+     */
+    assertMayStripRoleFromServiceAccounts(actor: Principal, roleUuid: string, accountTenantIds: readonly string[]): Promise<void>;
+    /**
+     * Assert the actor may RETIRE (disable + revoke the keys of) each of these service accounts
+     * (Phase 8 #3: a company delete retires the deleted company's own agents). Judged by the SAME
+     * ADR-0029 ceiling an admin needs to have made the agent ({@link ceilingOf}): the account's
+     * tenant and every node of its scope are inside the actor's subtree, and every role it holds is
+     * one the actor holds itself — so a sub-admin can never switch off an agent more powerful than
+     * itself by deleting its company. `accounts` are read by the caller under a row lock. Root
+     * bypasses. Refusals name no account. Store outage → 503.
+     */
+    assertMayRetireServiceAccounts(actor: Principal, accounts: ReadonlyArray<{
+        readonly tenantId: string;
+        readonly scopeSubtreeNodeIds: readonly string[];
+        readonly roleIds: readonly string[];
+    }>): Promise<void>;
     /** Where `roleUuid` is bound relative to the actor's subtree (postings + service accounts). */
     roleBinding(actor: Principal, roleUuid: string): Promise<RoleBinding>;
     /**

package/dist/features/authz/grant-ceiling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant-ceiling.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-ceiling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9D,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMtE,6FAA6F;AAC7F,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAI1C;AAED,sGAAsG;AACtG,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,MAAM,EAAE,CAE7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,EAC9B,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,OAAO,EAAE,MAAM,GACd,OAAO,CAST;AAED;;;GAGG;AACH,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAQzB,+FAA+F;IAC/F,OAAO,CAAC,QAAQ,CAAC,GAAG;IAbtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAGzB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,cAAc;IACzC;;;;;OAKG;IACH,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IACjC,+FAA+F;IAC9E,GAAG,GAAE,MAAM,MAAiB;IAU/C,+FAA+F;IAC/F,MAAM,CAAC,kBAAkB,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI;IAS/C,qFAAqF;IACrF,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI;IAQ5C,oEAAoE;IACpE,OAAO,CAAC,cAAc;IAItB,+FAA+F;YACjF,cAAc;IAU5B,+FAA+F;YACjF,KAAK;IASnB;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAkB7D;;;;OAIG;IACG,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAahF;;;;;OAKG;IACG,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBvF;;;;;;OAMG;IACG,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwD5E,+FAA+F;IACzF,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI3E;;;;;OAKG;IACG,uBAAuB,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhF;;;;OAIG;IACG,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAI9E"}
+{"version":3,"file":"grant-ceiling.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-ceiling.ts"],"names":[],"mappings":"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"}

package/dist/features/authz/grant-ceiling.js

@@ -7,6 +7,7 @@ const core_1 = require("@astram/core");
 const db_permission_facts_adapter_js_1 = require("./db-permission-facts.adapter.js");
 const role_binding_js_1 = require("./role-binding.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
+const service_account_service_js_1 = require("../service-account/service-account.service.js");
 const AUTHZ = 'shield_authz';
 const APP = 'shield_app';
 /** The grantor exceeds their own authority — cannot grant a key they do not hold (→ 403). */
@@ -152,7 +153,8 @@ class GrantCeiling {
      * Assert the actor may ASSIGN every role in `roleIds` (post someone to it): the roles' effective
      * keys (their `role_permission` rows, wildcards expanded against the registry) must all be held
      * by the actor — the same "only grant what you hold" ceiling, applied to role assignment (#11).
-     * A role holding nothing assigns nothing and passes. Root bypasses. Store outage → 503.
+     * A role holding nothing assigns nothing and passes; a role key the registry does not know
+     * counts as not held (Phase 8 #4). Root bypasses. Store outage → 503.
      */
     async assertCanAssignRoles(actor, roleIds) {
         if (actor.isRoot === true)
@@ -161,16 +163,25 @@ class GrantCeiling {
         if (ids.length === 0)
             return;
         const raw = await this.facts('role grants', () => this.rawKeysOfRoles(ids));
-        const roleKeys = (0, db_permission_facts_adapter_js_1.expandGrantKeys)(raw, this.registeredKeys());
-        if (roleKeys.length === 0)
+        if (raw.length === 0)
             return;
         const effective = await this.effectiveKeys(actor);
-        for (const key of roleKeys) {
-            if (!effective.has(key)) {
-                throw new GrantCeilingError(key, `You cannot assign this role — it grants '${key}', which exceeds the permissions you hold.`);
-            }
+        const key = this.firstUncovered(effective, raw);
+        if (key !== undefined) {
+            throw new GrantCeilingError(key, `You cannot assign this role — it grants '${key}', which exceeds the permissions you hold.`);
         }
     }
+    /**
+     * The first of a TARGET's raw keys (a role's `role_permission` rows) the actor does not cover,
+     * or `undefined` when all are covered. Phase 8 #4: judged per RAW key with `coversKey`, so a key
+     * the registry does not know — an exact key that is not registered, or a wildcard expanding to
+     * nothing — counts as NOT held and denies. Expanding first would silently drop it and could
+     * pass vacuously (fail open) when this registry is narrower than the decision path's.
+     */
+    firstUncovered(effective, raw) {
+        const registered = this.registeredKeys();
+        return [...new Set(raw)].sort().find((k) => !coversKey(effective, registered, k));
+    }
     /**
      * Assert the actor DOMINATES the target user (#3, D2): every membership the target holds (in any
      * tenant, active or not) is inside the actor's subtree, AND every key the target could hold
@@ -211,14 +222,111 @@ class GrantCeiling {
             throw new identity_errors_js_1.IdentityForbiddenError('You cannot change this user: they also belong to an organisation outside the ones you manage.');
         }
         const raw = await this.facts('target grants', () => this.rawKeysOfRoles(roleIds));
-        const targetKeys = (0, db_permission_facts_adapter_js_1.expandGrantKeys)(raw, this.registeredKeys());
-        if (targetKeys.length === 0)
+        if (raw.length === 0)
             return;
         const effective = await this.effectiveKeys(actor);
-        if (targetKeys.some((k) => !effective.has(k))) {
+        // Phase 8 #4: an unknown target key counts as not held (see `firstUncovered`).
+        if (this.firstUncovered(effective, raw) !== undefined) {
             throw new identity_errors_js_1.IdentityForbiddenError('You cannot change this user: they hold permissions you do not hold.');
         }
     }
+    /**
+     * Assert the actor DOMINATES every user who holds the role (Phase 8 #2): deleting a role, or
+     * revoking a key from it, strips authority from each holder, so it needs the same
+     * {@link assertDominates} the actor would need to change any one of them directly. Holders are
+     * the users with a posting of the role in any membership and any window (potential authority).
+     * The actor itself is skipped: giving up your own authority stays allowed (self-demotion).
+     * Service-account holders: a revoke is covered by the binding rule (`assertRoleAdministrable`:
+     * no binding outside the actor's subtree) plus "only revoke what you hold"; a role DELETE also
+     * strips the role from each account and checks {@link assertMayStripRoleFromServiceAccounts}.
+     * Root bypasses. Store outage → 503.
+     *
+     * Callers serialise against a concurrent posting by locking the role row first (the posting
+     * path locks the same row before it inserts), then call this — so no holder appears unseen.
+     */
+    async assertDominatesRoleHolders(actor, roleUuid) {
+        if (actor.isRoot === true)
+            return;
+        const holders = await this.facts('role holders', async () => {
+            const rows = (await this.pool.query(`SELECT DISTINCT cm.cm_user_uuid AS holder
+           FROM \`${APP}\`.\`membership_posting\` mp
+           JOIN \`${APP}\`.\`company_membership\` cm ON cm.cm_uuid = mp.mp_membership_uuid
+          WHERE mp.mp_role_uuid = ?`, [roleUuid]));
+            return rows.map((r) => r.holder);
+        });
+        for (const holder of [...new Set(holders)].sort()) {
+            if (holder === actor.id)
+                continue;
+            try {
+                await this.assertDominates(actor, holder);
+            }
+            catch (cause) {
+                if (cause instanceof identity_errors_js_1.IdentityForbiddenError || cause instanceof identity_errors_js_1.IdentityNotFoundError) {
+                    // Names no holder (who holds a role is not the caller's to learn from a refusal).
+                    throw new identity_errors_js_1.IdentityForbiddenError('You cannot change this role: it is held by someone outside your authority.');
+                }
+                throw cause;
+            }
+        }
+    }
+    /**
+     * Assert the actor may REMOVE `roleUuid` from every service account holding it (Phase 8 #2
+     * follow-up: a role delete strips the role from each holding account). Judged by the SAME rules
+     * as editing the account directly (`ServiceAccountService.update`, ADR-0029 ceiling via
+     * {@link ceilingOf}): each account's tenant is inside the actor's subtree, and the role is one
+     * the actor holds itself — a non-root admin's edit preserves (cannot strip) a role it does not
+     * hold. `accountTenantIds` are the holding accounts' tenants, read by the caller under a row lock.
+     * Root bypasses. Refusals name no account. Store outage → 503.
+     */
+    async assertMayStripRoleFromServiceAccounts(actor, roleUuid, accountTenantIds) {
+        if (actor.isRoot === true || accountTenantIds.length === 0)
+            return;
+        const admin = {
+            id: actor.id,
+            tenantId: actor.tenantId,
+            scopeSubtreeNodeIds: subtreeOf(actor),
+            isRoot: false,
+        };
+        const refuse = () => new identity_errors_js_1.IdentityForbiddenError('You cannot delete this role: it is assigned to an agent you cannot change.');
+        const nodes = (0, service_account_service_js_1.ceilingOf)(admin, []);
+        if (accountTenantIds.some((t) => !(0, service_account_service_js_1.ceilingAllowsNode)(nodes, t)))
+            throw refuse();
+        const held = await this.facts('held roles', () => (0, db_permission_facts_adapter_js_1.readRoleIdsForTenant)(this.pool, actor.id, actor.tenantId, this.now));
+        if (!(0, service_account_service_js_1.ceilingAllowsRole)((0, service_account_service_js_1.ceilingOf)(admin, held), roleUuid))
+            throw refuse();
+    }
+    /**
+     * Assert the actor may RETIRE (disable + revoke the keys of) each of these service accounts
+     * (Phase 8 #3: a company delete retires the deleted company's own agents). Judged by the SAME
+     * ADR-0029 ceiling an admin needs to have made the agent ({@link ceilingOf}): the account's
+     * tenant and every node of its scope are inside the actor's subtree, and every role it holds is
+     * one the actor holds itself — so a sub-admin can never switch off an agent more powerful than
+     * itself by deleting its company. `accounts` are read by the caller under a row lock. Root
+     * bypasses. Refusals name no account. Store outage → 503.
+     */
+    async assertMayRetireServiceAccounts(actor, accounts) {
+        if (actor.isRoot === true || accounts.length === 0)
+            return;
+        const admin = {
+            id: actor.id,
+            tenantId: actor.tenantId,
+            scopeSubtreeNodeIds: subtreeOf(actor),
+            isRoot: false,
+        };
+        const refuse = () => new identity_errors_js_1.IdentityForbiddenError('You cannot delete this company: one of its agents is outside your authority.');
+        const nodes = (0, service_account_service_js_1.ceilingOf)(admin, []);
+        const outsideNodes = accounts.some((a) => !(0, service_account_service_js_1.ceilingAllowsNode)(nodes, a.tenantId) ||
+            a.scopeSubtreeNodeIds.some((n) => !(0, service_account_service_js_1.ceilingAllowsNode)(nodes, n)));
+        if (outsideNodes)
+            throw refuse();
+        if (accounts.every((a) => a.roleIds.length === 0))
+            return;
+        const held = await this.facts('held roles', () => (0, db_permission_facts_adapter_js_1.readRoleIdsForTenant)(this.pool, actor.id, actor.tenantId, this.now));
+        const ceiling = (0, service_account_service_js_1.ceilingOf)(admin, held);
+        if (accounts.some((a) => a.roleIds.some((r) => !(0, service_account_service_js_1.ceilingAllowsRole)(ceiling, r)))) {
+            throw refuse();
+        }
+    }
     /** Where `roleUuid` is bound relative to the actor's subtree (postings + service accounts). */
     async roleBinding(actor, roleUuid) {
         return this.facts('role binding', () => (0, role_binding_js_1.readRoleBinding)(this.pool, roleUuid, subtreeOf(actor)));

package/dist/features/authz/permission-version.bumper.d.ts

@@ -71,6 +71,13 @@ export declare class PermissionVersionBumper {
      * so both roll back together).
      */
     bumpForRole(roleUuid: string, conn: Queryable): Promise<string[]>;
+    /**
+     * The tenants whose cached grants depend on the role: every tenant where it is ACTIVELY posted
+     * (active membership + posting) plus every service account's tenant holding it. Read-only; the
+     * tenant set `bumpForRole` bumps. A role delete reads it BEFORE the delete (Phase 8 #2), because
+     * the delete cascades the postings away. Errors propagate raw.
+     */
+    tenantsForRole(roleUuid: string, conn: Queryable): Promise<string[]>;
     /**
      * Increment the permission version for EVERY tenant where the user has a membership (any status)
      * — for a change to the USER itself that alters its effective grants everywhere (security

package/dist/features/authz/permission-version.bumper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission-version.bumper.d.ts","sourceRoot":"","sources":["../../../src/features/authz/permission-version.bumper.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;GAaG;AACH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAOD,qBAAa,uBAAuB;IAatB,OAAO,CAAC,SAAS,CAAC;IAZ9B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IACtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAEhE;;;OAGG;gBACiB,SAAS,CAAC,EAAE,gBAAgB,YAAA;IAEhD,qFAAqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAIzD;;;OAGG;IACG,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD,kFAAkF;IAClF,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;YAIvB,WAAW;IAUzB;;;;OAIG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvE;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA2BvE;;;;;;OAMG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBvE;;;;;;OAMG;YACW,UAAU;CA4BzB"}
+{"version":3,"file":"permission-version.bumper.d.ts","sourceRoot":"","sources":["../../../src/features/authz/permission-version.bumper.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;GAaG;AACH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAOD,qBAAa,uBAAuB;IAatB,OAAO,CAAC,SAAS,CAAC;IAZ9B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IACtE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAEhE;;;OAGG;gBACiB,SAAS,CAAC,EAAE,gBAAgB,YAAA;IAEhD,qFAAqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAIzD;;;OAGG;IACG,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD,kFAAkF;IAClF,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;YAIvB,WAAW;IAUzB;;;;OAIG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvE;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAYvE;;;;;OAKG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAmB1E;;;;;;OAMG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBvE;;;;;;OAMG;YACW,UAAU;CA4BzB"}

package/dist/features/authz/permission-version.bumper.js

@@ -82,16 +82,7 @@ class PermissionVersionBumper {
      */
     async bumpForRole(roleUuid, conn) {
         try {
-            const rows = (await conn.query(`SELECT DISTINCT cm.cm_company_uuid AS tenant
-           FROM \`${APP}\`.\`company_membership\` cm
-           JOIN \`${APP}\`.\`membership_posting\` mp ON mp.mp_membership_uuid = cm.cm_uuid
-          WHERE mp.mp_role_uuid = ? AND cm.cm_is_active = 1`, [roleUuid]));
-            // Service accounts (ADR-0033) hold roles on `sa_role_ids`, not postings: a role held only by
-            // machine principals must still invalidate their tenants' cached grants (security hardening).
-            const saRows = (await conn.query(`SELECT DISTINCT sa.sa_tenant_id AS tenant
-           FROM \`${APP}\`.\`service_account\` sa
-          WHERE JSON_CONTAINS(sa.sa_role_ids, JSON_QUOTE(?))`, [roleUuid]));
-            const tenants = [...new Set([...rows, ...saRows].map((r) => r.tenant))];
+            const tenants = await this.tenantsForRole(roleUuid, conn);
             for (const tenant of tenants) {
                 await this.bumpTenant(tenant, conn);
             }
@@ -101,6 +92,24 @@ class PermissionVersionBumper {
             throw new core_1.AuthorizationUnavailableError('permission version bump failed', cause);
         }
     }
+    /**
+     * The tenants whose cached grants depend on the role: every tenant where it is ACTIVELY posted
+     * (active membership + posting) plus every service account's tenant holding it. Read-only; the
+     * tenant set `bumpForRole` bumps. A role delete reads it BEFORE the delete (Phase 8 #2), because
+     * the delete cascades the postings away. Errors propagate raw.
+     */
+    async tenantsForRole(roleUuid, conn) {
+        const rows = (await conn.query(`SELECT DISTINCT cm.cm_company_uuid AS tenant
+         FROM \`${APP}\`.\`company_membership\` cm
+         JOIN \`${APP}\`.\`membership_posting\` mp ON mp.mp_membership_uuid = cm.cm_uuid
+        WHERE mp.mp_role_uuid = ? AND cm.cm_is_active = 1`, [roleUuid]));
+        // Service accounts (ADR-0033) hold roles on `sa_role_ids`, not postings: a role held only by
+        // machine principals must still invalidate their tenants' cached grants (security hardening).
+        const saRows = (await conn.query(`SELECT DISTINCT sa.sa_tenant_id AS tenant
+         FROM \`${APP}\`.\`service_account\` sa
+        WHERE JSON_CONTAINS(sa.sa_role_ids, JSON_QUOTE(?))`, [roleUuid]));
+        return [...new Set([...rows, ...saRows].map((r) => r.tenant))];
+    }
     /**
      * Increment the permission version for EVERY tenant where the user has a membership (any status)
      * — for a change to the USER itself that alters its effective grants everywhere (security

package/dist/features/authz/record-authorization.d.ts

@@ -12,6 +12,7 @@
 import { type Pool } from 'mariadb';
 import { type RecordAuthorizationInputs } from '@astram/guard';
 import type { ObjectTypeInput } from '@astram/engine';
+import type { ModuleRegistry } from '@astram/core';
 /**
  * A lean `mariadb` pool for the authz grant-reads (built from `APP_DB_*` env via guard's
  * `loadDbConfig`). Kept small — these are pre-gate coarse-grant reads, not the main CRUD pool.
@@ -37,4 +38,15 @@ export declare function createIdentityAuthzPool(): Pool;
  * those keys now project, and the framework still owns the four record-tier adapters + scope fn.
  */
 export declare function buildIdentityRecordAuthorization(pool: Pool, extraObjects?: readonly ObjectTypeInput[]): RecordAuthorizationInputs;
+/**
+ * The inputs builder WITHOUT the boot parity record — for the identity module's own internal
+ * authorities (they are not the decision path the consumer hands `ShieldModule`).
+ */
+export declare function buildRecordAuthorizationInputs(pool: Pool, extraObjects?: readonly ObjectTypeInput[]): RecordAuthorizationInputs;
+/** The boot error: the two registries' action-key sets differ (names the first differing keys). */
+export declare class IdentityRegistryMismatchError extends Error {
+    constructor(onlyDecision: readonly string[], onlyCeiling: readonly string[]);
+}
+/** Called by `IdentityFeatureModule.forRoot` with the grant ceiling's registry (Phase 8 #4). */
+export declare function noteIdentityCeilingRegistry(registry: ModuleRegistry): void;
 //# sourceMappingURL=record-authorization.d.ts.map

package/dist/features/authz/record-authorization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-authorization.d.ts","sourceRoot":"","sources":["../../../src/features/authz/record-authorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAKtD;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAU9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,IAAI,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,yBAAyB,CAS3B"}
+{"version":3,"file":"record-authorization.d.ts","sourceRoot":"","sources":["../../../src/features/authz/record-authorization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAgB,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAU9C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,IAAI,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,yBAAyB,CAI3B;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,IAAI,EACV,YAAY,GAAE,SAAS,eAAe,EAAO,GAC5C,yBAAyB,CAS3B;AAmBD,mGAAmG;AACnG,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,YAAY,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE;CAW5E;AAoBD,gGAAgG;AAChG,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAE1E"}

package/dist/features/authz/record-authorization.js

@@ -3,8 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityRegistryMismatchError = void 0;
 exports.createIdentityAuthzPool = createIdentityAuthzPool;
 exports.buildIdentityRecordAuthorization = buildIdentityRecordAuthorization;
+exports.buildRecordAuthorizationInputs = buildRecordAuthorizationInputs;
+exports.noteIdentityCeilingRegistry = noteIdentityCeilingRegistry;
 /**
  * Assemble the record-tier authorization wiring for `@astram/identity`: the lean grant-read
  * pool factory + the `recordAuthorization` inputs the consumer passes to
@@ -56,6 +59,15 @@ function createIdentityAuthzPool() {
  * those keys now project, and the framework still owns the four record-tier adapters + scope fn.
  */
 function buildIdentityRecordAuthorization(pool, extraObjects = []) {
+    const inputs = buildRecordAuthorizationInputs(pool, extraObjects);
+    noteRegistry('decision', inputs.registry);
+    return inputs;
+}
+/**
+ * The inputs builder WITHOUT the boot parity record — for the identity module's own internal
+ * authorities (they are not the decision path the consumer hands `ShieldModule`).
+ */
+function buildRecordAuthorizationInputs(pool, extraObjects = []) {
     const registry = (0, guard_1.buildIdentityModuleRegistry)([...objects_js_1.identityObjects, ...extraObjects]);
     return {
         pool,
@@ -65,3 +77,40 @@ function buildIdentityRecordAuthorization(pool, extraObjects = []) {
         operationManifest: [],
     };
 }
+const recordedKeySets = {
+    decision: new Map(),
+    ceiling: new Map(),
+};
+/** The boot error: the two registries' action-key sets differ (names the first differing keys). */
+class IdentityRegistryMismatchError extends Error {
+    constructor(onlyDecision, onlyCeiling) {
+        const sample = (keys) => keys.length === 0 ? 'none' : keys.slice(0, 10).join(', ') + (keys.length > 10 ? ', …' : '');
+        super('IdentityFeatureModule.forRoot({ extraObjects }) and buildIdentityRecordAuthorization(pool, ' +
+            'extraObjects) were given different object types. Pass the SAME array to both. ' +
+            `Only in the decision path: ${sample(onlyDecision)}. ` +
+            `Only in IdentityFeatureModule: ${sample(onlyCeiling)}.`);
+        this.name = 'IdentityRegistryMismatchError';
+    }
+}
+exports.IdentityRegistryMismatchError = IdentityRegistryMismatchError;
+/** Record one side's registry and throw if it disagrees with any recorded registry of the other. */
+function noteRegistry(role, registry) {
+    const keys = [...new Set(registry.listActions().map((a) => a.permissionKey))].sort();
+    const other = recordedKeySets[role === 'decision' ? 'ceiling' : 'decision'];
+    for (const otherKeys of other.values()) {
+        const mine = new Set(keys);
+        const theirs = new Set(otherKeys);
+        const onlyMine = keys.filter((k) => !theirs.has(k));
+        const onlyTheirs = otherKeys.filter((k) => !mine.has(k));
+        if (onlyMine.length > 0 || onlyTheirs.length > 0) {
+            throw role === 'decision'
+                ? new IdentityRegistryMismatchError(onlyMine, onlyTheirs)
+                : new IdentityRegistryMismatchError(onlyTheirs, onlyMine);
+        }
+    }
+    recordedKeySets[role].set(keys.join('\n'), keys);
+}
+/** Called by `IdentityFeatureModule.forRoot` with the grant ceiling's registry (Phase 8 #4). */
+function noteIdentityCeilingRegistry(registry) {
+    noteRegistry('ceiling', registry);
+}