@astram/identity 0.3.1 → 0.5.0

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

@@ -0,0 +1,248 @@
+"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 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, 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`?
+ *
+ * - An EXACT key is covered iff it is in `effective`.
+ * - A WILDCARD key (`module:*`, `module:type:*`, bare `module`) is covered iff EVERY registered
+ *   exact key it expands to is in `effective` — you cannot grant a wildcard you don't fully hold.
+ *   A wildcard that expands to ZERO registered keys is treated as NOT covered (nothing to hold ⇒
+ *   no basis to grant; also prevents a typo'd wildcard from vacuously passing).
+ *
+ * `effective` is assumed already expanded to exact keys (the grantor's wildcards resolved).
+ * PURE — no I/O; `registeredKeys` is the live registry's exact-key universe.
+ */
+function coversKey(effective, registeredKeys, granted) {
+    const isWildcard = granted.endsWith(':*') || !granted.includes(':');
+    if (!isWildcard) {
+        return effective.has(granted);
+    }
+    // Expand the granted wildcard against the SAME registry universe, then require full coverage.
+    const expanded = (0, db_permission_facts_adapter_js_1.expandGrantKeys)([granted], [...registeredKeys]);
+    if (expanded.length === 0)
+        return false;
+    return expanded.every((k) => effective.has(k));
+}
+/**
+ * Resolves a grantor's effective keys and enforces the ADR-0029 ceiling. Constructed in the
+ * identity module over the shared authz pool + the identity registry.
+ */
+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
+     * membership's in-effect postings in the grantor's tenant), wildcards expanded against the
+     * live registry. Fail-closed: a store outage throws AuthorizationUnavailableError (never an
+     * empty set masking an outage).
+     */
+    async effectiveKeys(grantor) {
+        try {
+            const roleIds = await (0, db_permission_facts_adapter_js_1.readRoleIdsForTenant)(this.pool, grantor.id, grantor.tenantId, this.now);
+            if (roleIds.length === 0)
+                return new Set();
+            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));
+            const raw = rows.map((r) => r.rp_perm_key);
+            const registered = this.registry.listActions().map((a) => a.permissionKey);
+            return new Set((0, db_permission_facts_adapter_js_1.expandGrantKeys)(raw, registered));
+        }
+        catch (cause) {
+            if (cause instanceof core_1.AuthorizationUnavailableError)
+                throw cause;
+            throw new core_1.AuthorizationUnavailableError('grant-ceiling facts unavailable', cause);
+        }
+    }
+    /**
+     * Assert the grantor may grant EVERY key in `keys`. Root (strict) bypasses. A non-root grantor
+     * must effectively hold each key (exact) or fully hold each wildcard's expansion. Throws
+     * `GrantCeilingError` on the FIRST key that exceeds the grantor's authority.
+     */
+    async assertCanGrant(grantor, keys) {
+        if (grantor.isRoot === true)
+            return; // strict root bypass
+        const effective = await this.effectiveKeys(grantor);
+        const registered = this.registry.listActions().map((a) => a.permissionKey);
+        for (const key of keys) {
+            if (!coversKey(effective, registered, key)) {
+                throw new GrantCeilingError(key);
+            }
+        }
+    }
+    // ── 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. 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));
+        const roleKeys = (0, db_permission_facts_adapter_js_1.expandGrantKeys)(raw, this.registeredKeys());
+        if (roleKeys.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.`);
+            }
+        }
+    }
+    /**
+     * 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));
+        const targetKeys = (0, db_permission_facts_adapter_js_1.expandGrantKeys)(raw, this.registeredKeys());
+        if (targetKeys.length === 0)
+            return;
+        const effective = await this.effectiveKeys(actor);
+        if (targetKeys.some((k) => !effective.has(k))) {
+            throw new identity_errors_js_1.IdentityForbiddenError('You cannot change this user: they hold permissions you do not hold.');
+        }
+    }
+    /** 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,21 @@ export declare class PermissionVersionBumper {
      * so both roll back together).
      */
     bumpForRole(roleUuid: string, conn: Queryable): Promise<string[]>;
-    /** The raw per-tenant increment (INSERT-or-increment). */
+    /**
+     * 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;IA2BvE;;;;;;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
@@ -48,7 +86,12 @@ class PermissionVersionBumper {
            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);
+            // 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))];
             for (const tenant of tenants) {
                 await this.bumpTenant(tenant, conn);
             }
@@ -58,11 +101,58 @@ class PermissionVersionBumper {
             throw new core_1.AuthorizationUnavailableError('permission version bump failed', cause);
         }
     }
-    /** The raw per-tenant increment (INSERT-or-increment). */
+    /**
+     * 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.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;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"}

package/dist/features/authz/role-binding.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Role binding — where a GLOBAL role (`shield_app.roles`) is in use, relative to a caller's subtree.
+ *
+ * Roles are a global catalog, so one `role_permission` edit changes every tenant that uses the role
+ * (review finding #1). Until roles are tenant-owned (D1 follow-up), "may this caller administer the
+ * role" is decided by WHERE the role is bound:
+ *   - a human binding: a `membership_posting` on a `company_membership` of company X;
+ *   - a machine binding: a `service_account` of tenant X whose `sa_role_ids` holds the role.
+ * `inside` = some binding's node is in the caller's subtree; `outside` = some binding's node is not.
+ *
+ * ONE definition, shared by grant administration (the `subtreeExists` read predicate below and the
+ * write rule), role update/delete, and posting creation, via {@link GrantCeiling}. All node ids and
+ * the role id are `?`-bound (never interpolated).
+ */
+import type { Queryable } from './permission-version.bumper.js';
+/** Where a role is bound relative to a set of subtree nodes. */
+export interface RoleBinding {
+    readonly inside: boolean;
+    readonly outside: boolean;
+}
+/**
+ * The shared EXISTS-subtree fragment for a non-root caller's READS (Task 4.2): a role row `r`
+ * qualifies only if it is bound (`membership_posting → company_membership`) to a node in the
+ * subtree. The caller splices `params` where `sql` sits in the surrounding query.
+ */
+export declare function subtreeExists(nodeIds: readonly string[]): {
+    sql: string;
+    params: string[];
+};
+/**
+ * Read where `roleUuid` is bound relative to `nodeIds` (human postings + service accounts) in ONE
+ * query. An empty `nodeIds` is treated as "nothing is inside" (every binding is outside) — fail
+ * closed, never an `IN ()` syntax error.
+ */
+export declare function readRoleBinding(q: Queryable, roleUuid: string, nodeIds: readonly string[]): Promise<RoleBinding>;
+//# sourceMappingURL=role-binding.d.ts.map

package/dist/features/authz/role-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-binding.d.ts","sourceRoot":"","sources":["../../../src/features/authz/role-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAIhE,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ3F;AASD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,CAAC,EAAE,SAAS,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,OAAO,CAAC,WAAW,CAAC,CAwBtB"}

package/dist/features/authz/role-binding.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subtreeExists = subtreeExists;
+exports.readRoleBinding = readRoleBinding;
+const APP = 'shield_app';
+/**
+ * The shared EXISTS-subtree fragment for a non-root caller's READS (Task 4.2): a role row `r`
+ * qualifies only if it is bound (`membership_posting → company_membership`) to a node in the
+ * subtree. The caller splices `params` where `sql` sits in the surrounding query.
+ */
+function subtreeExists(nodeIds) {
+    const ph = nodeIds.map(() => '?').join(', ');
+    const sql = ` AND EXISTS (` +
+        `SELECT 1 FROM \`${APP}\`.\`membership_posting\` mp` +
+        ` JOIN \`${APP}\`.\`company_membership\` cm ON cm.cm_uuid = mp.mp_membership_uuid` +
+        ` WHERE mp.mp_role_uuid = r.r_uuid AND cm.cm_company_uuid IN (${ph}))`;
+    return { sql, params: [...nodeIds] };
+}
+/** Coerce a driver aggregate (number | bigint | string | null) to a boolean. */
+function truthy(v) {
+    if (v === null || v === undefined)
+        return false;
+    if (typeof v === 'bigint')
+        return v !== 0n;
+    return Number(v) > 0;
+}
+/**
+ * Read where `roleUuid` is bound relative to `nodeIds` (human postings + service accounts) in ONE
+ * query. An empty `nodeIds` is treated as "nothing is inside" (every binding is outside) — fail
+ * closed, never an `IN ()` syntax error.
+ */
+async function readRoleBinding(q, roleUuid, nodeIds) {
+    const ids = nodeIds.length > 0 ? [...nodeIds] : [];
+    const inList = ids.length > 0 ? ids.map(() => '?').join(', ') : 'NULL';
+    // `x IN (NULL)` is NULL (never true) and `x NOT IN (NULL)` is NULL too, so for an empty list the
+    // outside test is written as a plain existence check instead.
+    const insideExpr = ids.length > 0 ? `b.node IN (${inList})` : '0';
+    const outsideExpr = ids.length > 0 ? `b.node NOT IN (${inList})` : '1';
+    const rows = (await q.query(`SELECT COALESCE(MAX(${insideExpr}), 0) AS bound_inside,
+            COALESCE(MAX(${outsideExpr}), 0) AS bound_outside
+       FROM (
+         SELECT cm.cm_company_uuid AS node
+           FROM \`${APP}\`.\`membership_posting\` mp
+           JOIN \`${APP}\`.\`company_membership\` cm ON cm.cm_uuid = mp.mp_membership_uuid
+          WHERE mp.mp_role_uuid = ?
+         UNION ALL
+         SELECT sa.sa_tenant_id AS node
+           FROM \`${APP}\`.\`service_account\` sa
+          WHERE JSON_CONTAINS(sa.sa_role_ids, JSON_QUOTE(?))
+       ) b`, [...ids, ...ids, roleUuid, roleUuid]));
+    const row = rows[0];
+    return { inside: truthy(row?.bound_inside), outside: truthy(row?.bound_outside) };
+}

package/dist/features/company/company-hierarchy.service.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CompanyHierarchyService — the ONLY way a company's place in the tree changes (security hardening
+ * #2, D5). The generic company patch can no longer move a company (`parentUuid`/`type` are
+ * immutable at the engine, ADR-0034, and the patch is whitelisted); every move, delete and new-node
+ * attach goes through `ScopeClosureService`, which owns the cycle check, the closure rebuild and
+ * the permission-version bump (ADR-0027 E-1/E-2).
+ *
+ * Authority (non-root; root bypasses), decided from the session's cached subtree — the SAME
+ * `scopeSubtreeNodeIds` the engine's write wall uses:
+ *   - move: the node is in the actor's subtree, is NOT the actor's own root node (a sub-admin can
+ *     never re-home its whole tenant), and the new parent is in the actor's subtree and non-null
+ *     (only root creates or promotes top-level tenants). A cycle → ScopeCycleError (409).
+ *   - delete: the caller (CompanyService) has already read the node through the subtree wall.
+ *
+ * Move and delete are audited ON their own transaction (a failed audit rolls them back). Names,
+ * never ids, in the audit detail (ADR-0012).
+ */
+import type { Principal } from '@astram/core';
+import type { AuditPort } from '@astram/engine';
+import { ScopeClosureService } from '../scope/scope-closure.service.js';
+/** The read surface used for existence/name lookups (the shared authz pool satisfies it). */
+export interface HierarchyQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+export declare class CompanyHierarchyService {
+    private readonly pool;
+    private readonly closure;
+    private readonly audit?;
+    private readonly now;
+    constructor(pool: HierarchyQueryable, closure: ScopeClosureService, audit?: AuditPort | undefined, now?: () => number);
+    /** The actor's own root node (the active node its subtree hangs from). */
+    private ownRoot;
+    /** Names of the given companies (unknown → absent). */
+    private names;
+    private recordAudit;
+    /** Re-parent `nodeUuid` under `newParentUuid` (null = make it a top-level tenant; root only). */
+    move(actor: Principal, nodeUuid: string, newParentUuid: string | null): Promise<void>;
+    /**
+     * Delete a company through `deleteNode` (refuses a node with children; closure rows + ancestor
+     * bump in one transaction). The caller has already checked reach (walled read).
+     */
+    remove(actor: Principal, nodeUuid: string): Promise<void>;
+    /** A company was just created: give it closure rows now and bump its ancestors (D5). */
+    attached(nodeUuid: string): Promise<void>;
+}
+//# sourceMappingURL=company-hierarchy.service.d.ts.map