@astram/identity 0.5.0 → 0.7.0

package/README.md

@@ -14,3 +14,18 @@ destination for the identity model currently declared in consuming applications
 once relocated, apps declare only role-maps, extra columns, and session
 extensions, while the canonical identity objects, migrations, and resolver live
 here in the framework.
+
+## `astram-sa-keys-report`
+
+Service-account keys issued before an expiry became mandatory never expire. This read-only command
+lists each agent's current, unrevoked key with no expiry (agent label, company name, status, key
+version, issue date; never a secret, hash or id), so you can rotate it with an expiry:
+
+```sh
+APP_DB_HOST=… APP_DB_PORT=… APP_DB_USER=… APP_DB_PASSWORD=… APP_DB_NAME=shield_app \
+  npx astram-sa-keys-report            # exit 0
+npx astram-sa-keys-report --fail-on-found   # exit 1 if any key is listed (CI)
+```
+
+It uses the same `APP_DB_*` variables as the identity module's authz pool. Exit code 2 means it
+could not run (bad option, no database).

package/dist/bin/sa-keys-report.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=sa-keys-report.d.ts.map

package/dist/bin/sa-keys-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sa-keys-report.d.ts","sourceRoot":"","sources":["../../src/bin/sa-keys-report.ts"],"names":[],"mappings":""}

package/dist/bin/sa-keys-report.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `astram-sa-keys-report` — list service-account keys that never expire (security hardening
+ * Phase 8 #13 / Phase 9 #8). Read-only; connects with the identity authz pool's `APP_DB_*` env.
+ * `--fail-on-found` exits 1 when any key is listed. Logic: `no-expiry-key-report.ts`.
+ */
+const record_authorization_js_1 = require("../features/authz/record-authorization.js");
+const no_expiry_key_report_js_1 = require("../features/service-account/no-expiry-key-report.js");
+void (0, no_expiry_key_report_js_1.runNonExpiringKeyReport)({
+    argv: process.argv.slice(2),
+    openDb: record_authorization_js_1.createIdentityAuthzPool,
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+}).then((code) => {
+    process.exitCode = code;
+});

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

@@ -114,9 +114,41 @@ 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,
+     * has already run the binding rule and user-holder dominance, and has already run the engine's
+     * delete (gate included, Phase 9 #5) on that still-open transaction; this method therefore does
+     * NOT lock the role row (that would wait on the caller) and reads only committed state. It
+     * commits BEFORE the caller does, 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[]>;
+    /**
+     * The service accounts holding `roleUuid`, read with a row lock on the transaction `conn` (a
+     * concurrent edit of one of them waits until this transaction ends). Phase 9 #11: only those
+     * rows are locked, never the whole table (`lockServiceAccountsWhere`). An agent that gains the
+     * role after the candidate read is not seen; the outcome equals "this change, then that edit"
+     * (a role delete leaves that agent an inert uuid: the role and its grants are gone).
+     */
+    private lockAccountsHoldingRole;
     /** 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":"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"}
+{"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

@@ -7,8 +7,27 @@ const db_permission_facts_adapter_js_1 = require("./db-permission-facts.adapter.
 const grant_ceiling_js_1 = require("./grant-ceiling.js");
 const role_binding_js_1 = require("./role-binding.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
+const lock_service_accounts_js_1 = require("../service-account/lock-service-accounts.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 +152,16 @@ 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).
+                // Phase 9 #9: that includes the service accounts holding the role, judged as a role
+                // delete judges them (each account's tenant in the actor's subtree, the role held by the
+                // actor), over the accounts read under a row lock.
+                if (REVOKE_ACTIONS.has(action)) {
+                    await this.ceiling.assertDominatesRoleHolders(actor, roleUuid);
+                    const accounts = await this.lockAccountsHoldingRole(conn, roleUuid);
+                    await this.ceiling.assertMayStripRoleFromServiceAccounts(actor, roleUuid, accounts.map((a) => a.sa_tenant_id), 'revoke');
+                }
             }
             for (const key of keys)
                 await statement(conn, key);
@@ -230,7 +259,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 +268,80 @@ 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,
+     * has already run the binding rule and user-holder dominance, and has already run the engine's
+     * delete (gate included, Phase 9 #5) on that still-open transaction; this method therefore does
+     * NOT lock the role row (that would wait on the caller) and reads only committed state. It
+     * commits BEFORE the caller does, 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 this.lockAccountsHoldingRole(conn, roleUuid);
+            if (this.ceiling && actor.isRoot !== true) {
+                await this.ceiling.assertMayStripRoleFromServiceAccounts(actor, roleUuid, accounts.map((a) => a.sa_tenant_id), 'delete');
+            }
+            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();
+        }
+    }
+    /**
+     * The service accounts holding `roleUuid`, read with a row lock on the transaction `conn` (a
+     * concurrent edit of one of them waits until this transaction ends). Phase 9 #11: only those
+     * rows are locked, never the whole table (`lockServiceAccountsWhere`). An agent that gains the
+     * role after the candidate read is not seen; the outcome equals "this change, then that edit"
+     * (a role delete leaves that agent an inert uuid: the role and its grants are gone).
+     */
+    lockAccountsHoldingRole(conn, roleUuid) {
+        return (0, lock_service_accounts_js_1.lockServiceAccountsWhere)(conn, 'sa_id, sa_tenant_id, sa_role_ids, sa_updated_at_ms', {
+            sql: 'JSON_CONTAINS(sa_role_ids, JSON_QUOTE(?))',
+            params: [roleUuid],
+        });
+    }
     // ── 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,58 @@ 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 are checked separately by {@link assertMayStripRoleFromServiceAccounts}
+     * (a role delete strips the role from each account; a revoke narrows what each account holds —
+     * Phase 9 #9). 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.
+     * Phase 9 #9: a grant revoke (`operation: 'revoke'`) narrows every holding account the same way
+     * and is judged by the same rule. Root bypasses. Refusals name no account. Store outage → 503.
+     */
+    assertMayStripRoleFromServiceAccounts(actor: Principal, roleUuid: string, accountTenantIds: readonly string[], operation?: 'delete' | 'revoke'): 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>;
+    /**
+     * Assert every department and branch a posting names belongs to the membership's company
+     * (Phase 9 #13b, review F4): a `company_departments` / `company_branches` junction row links it
+     * to `companyUuid`. Otherwise a posting could carry another tenant's department or branch.
+     * Applies to every actor, root included (it is the data's shape, not a privilege). A missing
+     * company (`null`) admits none. A foreign and a nonexistent unit give the same 400. Read through
+     * the shared authz pool, not the engine: the posting admin need not hold `company_department` /
+     * `company_branch` read. Store outage → 503.
+     */
+    assertOrgUnitsInCompany(companyUuid: string | null, units: {
+        readonly departmentUuids: readonly string[];
+        readonly branchUuids: 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,138 @@ 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 are checked separately by {@link assertMayStripRoleFromServiceAccounts}
+     * (a role delete strips the role from each account; a revoke narrows what each account holds —
+     * Phase 9 #9). 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.
+     * Phase 9 #9: a grant revoke (`operation: 'revoke'`) narrows every holding account the same way
+     * and is judged by the same rule. Root bypasses. Refusals name no account. Store outage → 503.
+     */
+    async assertMayStripRoleFromServiceAccounts(actor, roleUuid, accountTenantIds, operation = 'delete') {
+        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(operation === 'revoke'
+            ? 'You cannot change this role: it is assigned to an agent you cannot change.'
+            : '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();
+        }
+    }
+    /**
+     * Assert every department and branch a posting names belongs to the membership's company
+     * (Phase 9 #13b, review F4): a `company_departments` / `company_branches` junction row links it
+     * to `companyUuid`. Otherwise a posting could carry another tenant's department or branch.
+     * Applies to every actor, root included (it is the data's shape, not a privilege). A missing
+     * company (`null`) admits none. A foreign and a nonexistent unit give the same 400. Read through
+     * the shared authz pool, not the engine: the posting admin need not hold `company_department` /
+     * `company_branch` read. Store outage → 503.
+     */
+    async assertOrgUnitsInCompany(companyUuid, units) {
+        const check = async (ids, table, companyCol, unitCol, message) => {
+            const wanted = [...new Set(ids)];
+            if (wanted.length === 0)
+                return;
+            if (companyUuid === null)
+                throw new identity_errors_js_1.IdentityBadRequestError(message);
+            const rows = await this.facts('company org units', async () => (await this.pool.query(`SELECT ${unitCol} AS unit FROM \`${APP}\`.\`${table}\`
+            WHERE ${companyCol} = ? AND ${unitCol} IN (${wanted.map(() => '?').join(', ')})`, [companyUuid, ...wanted])));
+            const linked = new Set(rows.map((r) => r.unit));
+            if (wanted.some((u) => !linked.has(u)))
+                throw new identity_errors_js_1.IdentityBadRequestError(message);
+        };
+        await check(units.departmentUuids, 'company_departments', 'cd_company_uuid', 'cd_department_uuid', 'The department is not one of this company’s departments.');
+        await check(units.branchUuids, 'company_branches', 'cb_company_uuid', 'cb_branch_uuid', 'The branch is not one of this company’s branches.');
+    }
     /** 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