@astram/identity 0.4.0 → 0.6.0

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

@@ -1,18 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GrantCeiling = exports.GrantCeilingError = void 0;
+exports.subtreeOf = subtreeOf;
 exports.coversKey = coversKey;
 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). */
 class GrantCeilingError extends Error {
-    constructor(key) {
-        super(`You cannot grant '${key}' — it exceeds the permissions you hold.`);
+    constructor(key, message) {
+        super(message ?? `You cannot grant '${key}' — it exceeds the permissions you hold.`);
         this.name = 'GrantCeilingError';
     }
 }
 exports.GrantCeilingError = GrantCeilingError;
+/** The actor's reachable subtree: the session's cached closure, else the self node (non-widening). */
+function subtreeOf(actor) {
+    return actor.scopeSubtreeNodeIds?.length ? actor.scopeSubtreeNodeIds : [actor.tenantId];
+}
 /**
  * Does `effective` (the grantor's held EXACT keys) cover `granted`?
  *
@@ -44,12 +53,61 @@ class GrantCeiling {
     pool;
     registry;
     now;
+    rootIds;
     constructor(pool, registry, 
+    /**
+     * The platform root allowlist (the SAME `rootIds` given to `ShieldModule.forRoot`) — REQUIRED,
+     * no default (security review F5): pass the array, or `null` to state explicitly that it is
+     * not configured. A root user is never dominated by a non-root actor; independently of this
+     * list, a user flagged `u_is_platform_superuser` in the database is never dominated either.
+     */
+    rootIds, 
     /** Injectable clock (epoch-ms) for the posting effective-window read; defaults to Date.now. */
     now = Date.now) {
         this.pool = pool;
         this.registry = registry;
         this.now = now;
+        if (rootIds !== null && !Array.isArray(rootIds)) {
+            throw new TypeError('GrantCeiling: rootIds is required (the root allowlist, or null when none is configured)');
+        }
+        this.rootIds = rootIds ?? [];
+    }
+    /** The D1 administer rule over a binding read: used inside and nowhere outside (404 / 403). */
+    static checkAdministrable(b) {
+        if (!b.inside)
+            throw new identity_errors_js_1.IdentityNotFoundError('Role not found.');
+        if (b.outside) {
+            throw new identity_errors_js_1.IdentityForbiddenError('This role is also used outside the organisations you manage; only a platform administrator can change it.');
+        }
+    }
+    /** The #11 assign rule over a binding read: never a role also used outside (403). */
+    static checkAssignable(b) {
+        if (b.outside) {
+            throw new identity_errors_js_1.IdentityForbiddenError('This role is also used outside the organisations you manage; you cannot assign it.');
+        }
+    }
+    /** The registry's exact-key universe (wildcard expansion bound). */
+    registeredKeys() {
+        return this.registry.listActions().map((a) => a.permissionKey);
+    }
+    /** The raw `role_permission` keys of `roleIds` (exact or wildcard). Store errors propagate. */
+    async rawKeysOfRoles(roleIds) {
+        if (roleIds.length === 0)
+            return [];
+        const ph = roleIds.map(() => '?').join(', ');
+        const rows = (await this.pool.query(`SELECT rp_perm_key FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid IN (${ph})`, [...roleIds]));
+        return rows.map((r) => r.rp_perm_key);
+    }
+    /** Run a store read, mapping any non-domain failure to AuthorizationUnavailableError (503). */
+    async facts(what, read) {
+        try {
+            return await read();
+        }
+        catch (cause) {
+            if (cause instanceof core_1.AuthorizationUnavailableError)
+                throw cause;
+            throw new core_1.AuthorizationUnavailableError(`${what} unavailable`, cause);
+        }
     }
     /**
      * The grantor's EFFECTIVE exact keys: the keys granted to the grantor's roles (active
@@ -90,5 +148,209 @@ class GrantCeiling {
             }
         }
     }
+    // ── Block A (security hardening Phase 1) ──────────────────────────────────────────────────
+    /**
+     * 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; 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)
+            return;
+        const ids = [...new Set(roleIds)];
+        if (ids.length === 0)
+            return;
+        const raw = await this.facts('role grants', () => this.rawKeysOfRoles(ids));
+        if (raw.length === 0)
+            return;
+        const effective = await this.effectiveKeys(actor);
+        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
+     * through any of its postings (any membership, any window — potential authority, not just what is
+     * in effect now) is held by the actor. A platform root target is never dominated by a non-root.
+     * Root actors bypass. Store outage → 503.
+     */
+    async assertDominates(actor, targetUserId) {
+        if (actor.isRoot === true)
+            return;
+        if (this.rootIds.includes(targetUserId)) {
+            throw new identity_errors_js_1.IdentityForbiddenError('You cannot change this user: they are a platform administrator.');
+        }
+        const subtree = new Set(subtreeOf(actor));
+        const { companies, roleIds, superuser } = await this.facts('target memberships', async () => {
+            const su = (await this.pool.query(`SELECT u_is_platform_superuser AS su FROM \`${APP}\`.\`users\` WHERE u_uuid = ? LIMIT 1`, [targetUserId]));
+            const memberships = (await this.pool.query(`SELECT DISTINCT cm_company_uuid AS company
+           FROM \`${APP}\`.\`company_membership\`
+          WHERE cm_user_uuid = ?`, [targetUserId]));
+            const postings = (await this.pool.query(`SELECT DISTINCT mp.mp_role_uuid AS role_uuid
+           FROM \`${APP}\`.\`membership_posting\` mp
+           JOIN \`${APP}\`.\`company_membership\` cm ON cm.cm_uuid = mp.mp_membership_uuid
+          WHERE cm.cm_user_uuid = ?`, [targetUserId]));
+            return {
+                companies: memberships.map((m) => m.company),
+                roleIds: postings.map((p) => p.role_uuid),
+                superuser: Number(su[0]?.su ?? 0) === 1,
+            };
+        });
+        if (superuser) {
+            throw new identity_errors_js_1.IdentityForbiddenError('You cannot change this user: they are a platform administrator.');
+        }
+        // Security review F5: a user with NO membership is in nobody's subtree — refuse like the
+        // walled read does (404), never "vacuously dominated".
+        if (companies.length === 0)
+            throw new identity_errors_js_1.IdentityNotFoundError('User not found.');
+        if (companies.some((c) => !subtree.has(c))) {
+            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));
+        if (raw.length === 0)
+            return;
+        const effective = await this.effectiveKeys(actor);
+        // 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)));
+    }
+    /**
+     * Assert the actor may ADMINISTER the role — edit its grants, rename or delete it (#1, D1
+     * interim rule): the role is bound inside the actor's subtree AND bound nowhere outside it. A
+     * role not bound in the subtree is "not found" for the actor (no existence leak); a role also
+     * used outside (a shared role) is root-only. Root bypasses.
+     */
+    async assertRoleAdministrable(actor, roleUuid) {
+        if (actor.isRoot === true)
+            return;
+        GrantCeiling.checkAdministrable(await this.roleBinding(actor, roleUuid));
+    }
+    /**
+     * Assert the actor may POST someone to the role (#11): the role is bound within the actor's
+     * subtree or not bound at all — never a role also used outside it (a shared role's assignment
+     * would widen another tenant's role). Pair with {@link assertCanAssignRoles}. Root bypasses.
+     */
+    async assertRoleAssignable(actor, roleUuid) {
+        if (actor.isRoot === true)
+            return;
+        GrantCeiling.checkAssignable(await this.roleBinding(actor, roleUuid));
+    }
 }
 exports.GrantCeiling = GrantCeiling;

package/dist/features/authz/mariadb-catalog-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-catalog-store.d.ts","sourceRoot":"","sources":["../../../src/features/authz/mariadb-catalog-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAIxE;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEjC,eAAe,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAelD,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAW7E,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQzD"}
+{"version":3,"file":"mariadb-catalog-store.d.ts","sourceRoot":"","sources":["../../../src/features/authz/mariadb-catalog-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAIxE;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEjC,eAAe,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAwBlD,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB7E,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQzD"}

package/dist/features/authz/mariadb-catalog-store.js

@@ -16,8 +16,12 @@ class MariaDbCatalogStore {
         const rows = (await this.pool.query(`SELECT perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status
          FROM \`${AUTHZ}\`.\`permission\``));
         return rows.map((r) => ({
-            permissionKey: r.perm_key, moduleKey: r.perm_module, typeKey: r.perm_type_key,
-            action: r.perm_action, label: r.perm_label, tier: r.perm_tier,
+            permissionKey: r.perm_key,
+            moduleKey: r.perm_module,
+            typeKey: r.perm_type_key,
+            action: r.perm_action,
+            label: r.perm_label,
+            tier: r.perm_tier,
             status: r.perm_status === 'orphaned' ? 'orphaned' : 'active',
         }));
     }
@@ -25,7 +29,15 @@ class MariaDbCatalogStore {
         const res = (await this.pool.query(`INSERT INTO \`${AUTHZ}\`.\`permission\`
          (perm_uuid, perm_key, perm_module, perm_type_key, perm_action, perm_label, perm_tier, perm_status)
          SELECT UUID(), ?, ?, ?, ?, ?, ?, 'active'
-          WHERE NOT EXISTS (SELECT 1 FROM \`${AUTHZ}\`.\`permission\` WHERE perm_key = ?)`, [row.permissionKey, row.moduleKey, row.typeKey, row.action, row.label, row.tier, row.permissionKey]));
+          WHERE NOT EXISTS (SELECT 1 FROM \`${AUTHZ}\`.\`permission\` WHERE perm_key = ?)`, [
+            row.permissionKey,
+            row.moduleKey,
+            row.typeKey,
+            row.action,
+            row.label,
+            row.tier,
+            row.permissionKey,
+        ]));
         return Number(res?.affectedRows ?? 0) > 0;
     }
     async markOrphaned(keys) {

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

@@ -20,7 +20,37 @@ export interface Queryable {
  *  - `bumpForRole` wraps a failure in `AuthorizationUnavailableError` and THROWS (see its own
  *    doc comment below) — do not assume it is also fail-safe.
  */
+/**
+ * Where a committed version is published (ADR-0035, GAPS #6) — `@astram/guard`'s
+ * `RedisPermissionVersionCache` satisfies it structurally (monotonic, TTL'd, never throws).
+ */
+export interface VersionPublisher {
+    publish(tenantUuid: string, version: number): Promise<void>;
+}
 export declare class PermissionVersionBumper {
+    private publisher?;
+    /**
+     * Bumped versions waiting for their transaction to commit, per connection (ADR-0035). A
+     * transaction connection is a pooled object reused across requests, so callers either publish
+     * (`publishCommitted`, after `commit()`) or drop (`discardPending`, after `rollback()`) them.
+     */
+    private readonly pending;
+    private readonly logger;
+    /**
+     * @param publisher OPTIONAL Redis publisher (ADR-0035). Absent → DB-only bumps, exactly as
+     *   before (no read-back). `IdentityFeatureModule` attaches the guard's cache through DI.
+     */
+    constructor(publisher?: VersionPublisher | undefined);
+    /** Attach the Redis publisher once it is resolved through DI (first attach wins). */
+    attachVersionPublisher(publisher: VersionPublisher): void;
+    /**
+     * Publish the versions this transaction connection bumped — call right AFTER `commit()`.
+     * Best-effort: a failure is logged (no tenant id) and swallowed; the key TTL bounds the delay.
+     */
+    publishCommitted(conn: Queryable): Promise<void>;
+    /** Drop the versions a ROLLED-BACK transaction bumped (nothing was committed). */
+    discardPending(conn: Queryable): void;
+    private safePublish;
     /**
      * Increment the permission version for a SINGLE tenant — for events that change a
      * principal's EFFECTIVE grants without touching `role_permission` directly (a
@@ -41,7 +71,28 @@ export declare class PermissionVersionBumper {
      * so both roll back together).
      */
     bumpForRole(roleUuid: string, conn: Queryable): Promise<string[]>;
-    /** The raw per-tenant increment (INSERT-or-increment). */
+    /**
+     * 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
+     * hardening Phase 3: disabling or re-enabling an account). Returns the bumped tenants. Like
+     * `bumpForRole`, a failure is wrapped in `AuthorizationUnavailableError` and THROWS: a silently
+     * missed bump would leave a disabled user's cached grants honoured.
+     */
+    bumpForUser(userUuid: string, conn: Queryable): Promise<string[]>;
+    /**
+     * The raw per-tenant increment (INSERT-or-increment). With a publisher attached (ADR-0035) the
+     * new version is read back on the SAME connection (inside a transaction that is the
+     * transaction's own value) and published to Redis AFTER the commit: at once over the autocommit
+     * pool, at `publishCommitted(conn)` for a transaction. A read-back failure skips the publish
+     * (the TTL bounds it) and never fails the bump.
+     */
     private bumpTenant;
 }
 //# sourceMappingURL=permission-version.bumper.d.ts.map

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":"AAQA;;;;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,qBAAa,uBAAuB;IAClC;;;;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;IAmBvE,0DAA0D;YAC5C,UAAU;CAQzB"}
+{"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

@@ -1,26 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PermissionVersionBumper = void 0;
+const common_1 = require("@nestjs/common");
 const core_1 = require("@astram/core");
 /** Schema the `authz_permission_version` table lives in (ADR-0011). */
 const AUTHZ = 'shield_authz';
 /** Schema the membership/posting tables live in — the join `bumpForRole` walks. */
 const APP = 'shield_app';
-/**
- * PermissionVersionBumper — the WRITER side of ADR-0011: increments a tenant's
- * `shield_authz.authz_permission_version` so `loadCoarseGrants` marks cached facts stale →
- * gate 5 reloads → a role gain/loss (from a posting change) lands WITHOUT re-login. Runs the
- * INSERT-or-increment over a supplied connection (the sealed authz pool, or a transaction
- * connection so the bump joins the caller's write). Fail-safe: the caller wraps a bump failure
- * so it never fails the membership/posting write. Never logs the tenant or the query.
- *
- * NOTE — the two bump methods do NOT share an error contract:
- *  - `bumpForTenant` propagates the raw underlying error unwrapped; it is up to ITS caller
- *    (the Phase 3 membership/posting write) to swallow it fail-safe, per the paragraph above.
- *  - `bumpForRole` wraps a failure in `AuthorizationUnavailableError` and THROWS (see its own
- *    doc comment below) — do not assume it is also fail-safe.
- */
+/** An autocommit pool (it hands out connections) rather than one transaction's connection. */
+function isAutocommitPool(conn) {
+    return typeof conn.getConnection === 'function';
+}
 class PermissionVersionBumper {
+    publisher;
+    /**
+     * Bumped versions waiting for their transaction to commit, per connection (ADR-0035). A
+     * transaction connection is a pooled object reused across requests, so callers either publish
+     * (`publishCommitted`, after `commit()`) or drop (`discardPending`, after `rollback()`) them.
+     */
+    pending = new WeakMap();
+    logger = new common_1.Logger('PermissionVersionBumper');
+    /**
+     * @param publisher OPTIONAL Redis publisher (ADR-0035). Absent → DB-only bumps, exactly as
+     *   before (no read-back). `IdentityFeatureModule` attaches the guard's cache through DI.
+     */
+    constructor(publisher) {
+        this.publisher = publisher;
+    }
+    /** Attach the Redis publisher once it is resolved through DI (first attach wins). */
+    attachVersionPublisher(publisher) {
+        if (this.publisher === undefined)
+            this.publisher = publisher;
+    }
+    /**
+     * Publish the versions this transaction connection bumped — call right AFTER `commit()`.
+     * Best-effort: a failure is logged (no tenant id) and swallowed; the key TTL bounds the delay.
+     */
+    async publishCommitted(conn) {
+        const versions = this.pending.get(conn);
+        if (versions === undefined)
+            return;
+        this.pending.delete(conn);
+        for (const [tenantUuid, version] of versions)
+            await this.safePublish(tenantUuid, version);
+    }
+    /** Drop the versions a ROLLED-BACK transaction bumped (nothing was committed). */
+    discardPending(conn) {
+        this.pending.delete(conn);
+    }
+    async safePublish(tenantUuid, version) {
+        const publisher = this.publisher;
+        if (publisher === undefined)
+            return;
+        try {
+            await publisher.publish(tenantUuid, version);
+        }
+        catch {
+            this.logger.warn('permission version publish failed; cached sessions refresh within the TTL');
+        }
+    }
     /**
      * Increment the permission version for a SINGLE tenant — for events that change a
      * principal's EFFECTIVE grants without touching `role_permission` directly (a
@@ -44,11 +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]));
-            const tenants = rows.map((r) => r.tenant);
+            const tenants = await this.tenantsForRole(roleUuid, conn);
             for (const tenant of tenants) {
                 await this.bumpTenant(tenant, conn);
             }
@@ -58,11 +92,76 @@ class PermissionVersionBumper {
             throw new core_1.AuthorizationUnavailableError('permission version bump failed', cause);
         }
     }
-    /** The raw per-tenant increment (INSERT-or-increment). */
+    /**
+     * 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
+     * hardening Phase 3: disabling or re-enabling an account). Returns the bumped tenants. Like
+     * `bumpForRole`, a failure is wrapped in `AuthorizationUnavailableError` and THROWS: a silently
+     * missed bump would leave a disabled user's cached grants honoured.
+     */
+    async bumpForUser(userUuid, conn) {
+        try {
+            const rows = (await conn.query(`SELECT DISTINCT cm.cm_company_uuid AS tenant
+           FROM \`${APP}\`.\`company_membership\` cm
+          WHERE cm.cm_user_uuid = ?`, [userUuid]));
+            const tenants = [...new Set(rows.map((r) => r.tenant))];
+            for (const tenant of tenants)
+                await this.bumpTenant(tenant, conn);
+            return tenants;
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('permission version bump failed', cause);
+        }
+    }
+    /**
+     * The raw per-tenant increment (INSERT-or-increment). With a publisher attached (ADR-0035) the
+     * new version is read back on the SAME connection (inside a transaction that is the
+     * transaction's own value) and published to Redis AFTER the commit: at once over the autocommit
+     * pool, at `publishCommitted(conn)` for a transaction. A read-back failure skips the publish
+     * (the TTL bounds it) and never fails the bump.
+     */
     async bumpTenant(tenantUuid, conn) {
         await conn.query(`INSERT INTO \`${AUTHZ}\`.\`authz_permission_version\` (apv_tenant_uuid, apv_version)
          VALUES (?, 1)
        ON DUPLICATE KEY UPDATE apv_version = apv_version + 1`, [tenantUuid]);
+        if (this.publisher === undefined)
+            return;
+        let version;
+        try {
+            const rows = (await conn.query(`SELECT apv_version FROM \`${AUTHZ}\`.\`authz_permission_version\`
+          WHERE apv_tenant_uuid = ? LIMIT 1`, [tenantUuid]));
+            version = Number(rows[0]?.apv_version);
+        }
+        catch {
+            return;
+        }
+        if (!Number.isSafeInteger(version) || version < 0)
+            return;
+        if (isAutocommitPool(conn)) {
+            await this.safePublish(tenantUuid, version);
+            return;
+        }
+        const versions = this.pending.get(conn) ?? new Map();
+        versions.set(tenantUuid, Math.max(version, versions.get(tenantUuid) ?? 0));
+        this.pending.set(conn, versions);
     }
 }
 exports.PermissionVersionBumper = PermissionVersionBumper;

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,EAA6C,KAAK,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1G,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"}