@astram/identity 0.3.1 → 0.5.0

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

@@ -1,6 +1,9 @@
 import type { Pool } from 'mariadb';
+import type { Principal } from '@astram/core';
+import type { AuditPort } from '@astram/engine';
 import { PermissionVersionBumper } from './permission-version.bumper.js';
 import { AccessBundleStore } from './access-bundle-store.js';
+import { GrantCeiling } from './grant-ceiling.js';
 /**
  * The caller's reachable subtree, threaded from `req.principal` (Task 4.2). It scopes the
  * grant-admin reads so a caller sees ONLY roles bound within their subtree — the SAME cached
@@ -49,8 +52,19 @@ export interface RoleGrantSummary {
 export declare class GrantAdminService {
     private readonly pool;
     private readonly bumper;
+    private readonly ceiling?;
+    private readonly audit?;
     private readonly bundles;
-    constructor(pool: Pool, bumper: PermissionVersionBumper, bundleStore?: AccessBundleStore);
+    /**
+     * @param ceiling  The ADR-0029 self-escalation ceiling ("only grant what you hold") plus the
+     *   security-hardening role-binding rule. Enforced on grant/revoke/grantBundle/revokeBundle for a
+     *   non-root actor. OPTIONAL for back-compat: when absent (legacy wiring / tests that don't
+     *   exercise it), neither check runs — the identity module ALWAYS wires it, so production always
+     *   enforces. Root bypasses regardless.
+     * @param audit  The grant-administration audit sink (D6): written on the grant's own transaction
+     *   connection, fail-closed. The identity module ALWAYS wires the engine `MariaDbAuditSink`.
+     */
+    constructor(pool: Pool, bumper: PermissionVersionBumper, bundleStore?: AccessBundleStore, ceiling?: GrantCeiling | undefined, audit?: AuditPort | undefined);
     /** All grantable exact keys (from the catalog) + the computed wildcard set. */
     listCatalog(): Promise<{
         catalog: CatalogRow[];
@@ -67,13 +81,42 @@ export declare class GrantAdminService {
     /** Validate the key against the catalog + wildcard set. Throws BadKeyError if unknown. */
     private assertValidKey;
     /**
-     * Grant a key to a role (idempotent) + bump the version, atomically. `actorUuid`, when
-     * given, stamps `rp_granted_at`/`rp_granted_by` on a NEWLY-inserted row (a duplicate is a
-     * no-op and its existing stamp is left as-is).
+     * Security hardening #1 (D1 interim rule) + ADR-0029, in this order, BEFORE any write: the role
+     * must be administrable by the actor (bound inside its subtree and nowhere outside — a shared
+     * role is root-only), then every key must be covered by the actor's own effective keys ("only
+     * grant — or revoke — what you hold"). Root bypasses both. No ceiling wired (legacy/tests) ⇒
+     * neither check runs; the identity module always wires it.
+     */
+    private assertMayChangeGrants;
+    /**
+     * Run one grant-administration write in ONE transaction: the `role_permission` statements, the
+     * permission-version bump of every tenant using the role, and the audit row(s) (D6 — audited in
+     * the SAME transaction, fail-closed: an audit failure rolls the grant back). Store failures map
+     * to AuthorizationUnavailableError (503).
+     */
+    private writeGrants;
+    /**
+     * Write the grant-administration audit row(s) on the transaction connection (D6). One row per
+     * distinct tenant among the actor's tenant and every tenant the change bumped, so each affected
+     * tenant's auditor sees it. Names, never ids, in the detail (ADR-0012): the role name and the
+     * bumped tenants' names; the viewer resolves the actor and row tenant itself. No sink wired
+     * (legacy/tests) ⇒ nothing is written.
+     */
+    private auditGrantChange;
+    /**
+     * Grant a key to a role (idempotent) + bump the version + audit, atomically. The `grantor`
+     * Principal stamps `rp_granted_at`/`rp_granted_by` on a NEWLY-inserted row (a duplicate is a
+     * no-op and its existing stamp is left as-is). Order: catalog validation (400) → role binding
+     * (404/403) → ceiling (403) → write. Root bypasses the binding rule and the ceiling.
+     */
+    grant(roleUuid: string, key: string, grantor: Principal): Promise<void>;
+    /**
+     * 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.
      */
-    grant(roleUuid: string, key: string, actorUuid?: string): Promise<void>;
-    /** Revoke a key from a role (no-op if absent) + bump the version, atomically. */
-    revoke(roleUuid: string, key: string): Promise<void>;
+    revoke(roleUuid: string, key: string, actor: Principal): Promise<void>;
     /** All active bundles + their resolved atomic keys, for the Access UI. */
     listBundles(): Promise<{
         bundles: BundleView[];
@@ -82,15 +125,18 @@ export declare class GrantAdminService {
      * Grant a bundle to a role: resolve the bundle → its atomic keys, then INSERT each
      * into `role_permission` idempotently in ONE transaction with ONE version bump.
      * An unknown / orphaned bundle → `BadKeyError` (mapped to 400 by the controller).
+     * ADR-0029: a non-root `grantor` must effectively hold EVERY atomic key the bundle expands
+     * to; otherwise `GrantCeilingError` (403), checked before any write. Root bypasses.
      */
-    grantBundle(roleUuid: string, bundleKey: string, actorUuid?: string): Promise<void>;
+    grantBundle(roleUuid: string, bundleKey: string, grantor: Principal): Promise<void>;
     /**
      * Revoke a bundle from a role: resolve → DELETE each of the bundle's atomic keys, in
-     * ONE transaction with ONE version bump. Caveat (design §5.1): this removes exactly the
+     * ONE transaction with ONE version bump + audit. Caveat (design §5.1): this removes exactly the
      * bundle's keys even if a manual grant or another bundle shares one — the model is
-     * key-based, not bundle-membership-based. Unknown bundle → `BadKeyError`.
+     * key-based, not bundle-membership-based. Unknown bundle → `BadKeyError`. Security hardening
+     * #1: the binding rule + "only revoke what you hold" apply (root bypasses).
      */
-    revokeBundle(roleUuid: string, bundleKey: string): Promise<void>;
+    revokeBundle(roleUuid: string, bundleKey: string, actor: Principal): Promise<void>;
     /** Resolve a bundle key → its atomic keys; throw BadKeyError when unknown/orphaned. */
     private resolveBundleKeysOrThrow;
     /**

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

@@ -4,23 +4,11 @@ exports.GrantAdminService = exports.BadKeyError = void 0;
 const core_1 = require("@astram/core");
 const access_bundle_store_js_1 = require("./access-bundle-store.js");
 const db_permission_facts_adapter_js_1 = require("./db-permission-facts.adapter.js");
+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 AUTHZ = 'shield_authz';
 const APP = 'shield_app';
-/**
- * Build the shared EXISTS-subtree fragment for a non-root caller. A role qualifies only if it
- * is bound (`membership_posting → company_membership`) to a node in the caller's subtree. All
- * node ids are `?`-bound (never interpolated → injection-free); the caller splices the returned
- * `params` at the position where `sql` sits in the surrounding query. Root / empty scope callers
- * are handled by the caller (root ⇒ no fragment; the engine guarantees non-empty subtrees).
- */
-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] };
-}
 /** 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 {
@@ -33,10 +21,23 @@ exports.BadKeyError = BadKeyError;
 class GrantAdminService {
     pool;
     bumper;
+    ceiling;
+    audit;
     bundles;
-    constructor(pool, bumper, bundleStore) {
+    /**
+     * @param ceiling  The ADR-0029 self-escalation ceiling ("only grant what you hold") plus the
+     *   security-hardening role-binding rule. Enforced on grant/revoke/grantBundle/revokeBundle for a
+     *   non-root actor. OPTIONAL for back-compat: when absent (legacy wiring / tests that don't
+     *   exercise it), neither check runs — the identity module ALWAYS wires it, so production always
+     *   enforces. Root bypasses regardless.
+     * @param audit  The grant-administration audit sink (D6): written on the grant's own transaction
+     *   connection, fail-closed. The identity module ALWAYS wires the engine `MariaDbAuditSink`.
+     */
+    constructor(pool, bumper, bundleStore, ceiling, audit) {
         this.pool = pool;
         this.bumper = bumper;
+        this.ceiling = ceiling;
+        this.audit = audit;
         this.bundles = bundleStore ?? new access_bundle_store_js_1.AccessBundleStore(pool);
     }
     /** All grantable exact keys (from the catalog) + the computed wildcard set. */
@@ -52,8 +53,11 @@ class GrantAdminService {
             throw new core_1.AuthorizationUnavailableError('permission catalog unavailable', cause);
         }
         const catalog = rows.map((r) => ({
-            key: r.perm_key, label: r.perm_label, module: r.perm_module,
-            typeKey: r.perm_type_key, action: r.perm_action,
+            key: r.perm_key,
+            label: r.perm_label,
+            module: r.perm_module,
+            typeKey: r.perm_type_key,
+            action: r.perm_action,
         }));
         // Wildcards: module-wide + one per distinct type key.
         const modules = [...new Set(catalog.map((c) => c.module))];
@@ -98,52 +102,142 @@ class GrantAdminService {
             throw new BadKeyError(key);
     }
     /**
-     * Grant a key to a role (idempotent) + bump the version, atomically. `actorUuid`, when
-     * given, stamps `rp_granted_at`/`rp_granted_by` on a NEWLY-inserted row (a duplicate is a
-     * no-op and its existing stamp is left as-is).
+     * Security hardening #1 (D1 interim rule) + ADR-0029, in this order, BEFORE any write: the role
+     * must be administrable by the actor (bound inside its subtree and nowhere outside — a shared
+     * role is root-only), then every key must be covered by the actor's own effective keys ("only
+     * grant — or revoke — what you hold"). Root bypasses both. No ceiling wired (legacy/tests) ⇒
+     * neither check runs; the identity module always wires it.
      */
-    async grant(roleUuid, key, actorUuid) {
-        await this.assertValidKey(key); // throws BadKeyError (400) before touching the store
+    async assertMayChangeGrants(roleUuid, keys, actor) {
+        if (!this.ceiling)
+            return;
+        await this.ceiling.assertRoleAdministrable(actor, roleUuid);
+        await this.ceiling.assertCanGrant(actor, keys);
+    }
+    /**
+     * Run one grant-administration write in ONE transaction: the `role_permission` statements, the
+     * permission-version bump of every tenant using the role, and the audit row(s) (D6 — audited in
+     * the SAME transaction, fail-closed: an audit failure rolls the grant back). Store failures map
+     * to AuthorizationUnavailableError (503).
+     */
+    async writeGrants(action, roleUuid, keys, actor, statement, extra = {}) {
         const conn = await this.pool.getConnection();
         try {
             await conn.beginTransaction();
-            // Idempotent insert — UNIQUE (rp_role_uuid, rp_perm_key); a duplicate is a no-op.
-            await conn.query(`INSERT INTO \`${AUTHZ}\`.\`role_permission\`
-           (rp_uuid, rp_role_uuid, rp_perm_key, rp_granted_at, rp_granted_by)
-           SELECT UUID(), ?, ?, UTC_TIMESTAMP(), ?
-            WHERE NOT EXISTS (
-              SELECT 1 FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?
-            )`, [roleUuid, key, actorUuid ?? null, roleUuid, key]);
-            await this.bumper.bumpForRole(roleUuid, conn);
+            // Security review F2: serialise against a concurrent posting of this role (in any tenant).
+            // Lock the role row FIRST — the posting path locks the same row before it inserts — then
+            // re-run the binding rule on THIS connection, so a binding committed by a writer we waited
+            // for is seen, and a role that became shared in the meantime is refused (rolled back).
+            await conn.query(`SELECT r_uuid FROM \`${APP}\`.\`roles\` WHERE r_uuid = ? FOR UPDATE`, [
+                roleUuid,
+            ]);
+            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)));
+            }
+            for (const key of keys)
+                await statement(conn, key);
+            const bumped = await this.bumper.bumpForRole(roleUuid, conn);
+            await this.auditGrantChange(conn, action, roleUuid, keys, actor, bumped, extra);
             await conn.commit();
+            // ADR-0035: the committed versions reach Redis now (gate 5 reads them there).
+            await this.bumper.publishCommitted(conn);
         }
         catch (cause) {
             await conn.rollback();
-            if (cause instanceof BadKeyError)
+            this.bumper.discardPending(conn);
+            if (cause instanceof BadKeyError ||
+                cause instanceof identity_errors_js_1.IdentityForbiddenError ||
+                cause instanceof identity_errors_js_1.IdentityNotFoundError) {
                 throw cause;
-            throw new core_1.AuthorizationUnavailableError('grant failed', cause);
+            }
+            throw new core_1.AuthorizationUnavailableError(`${action} failed`, cause);
         }
         finally {
             await conn.release();
         }
     }
-    /** Revoke a key from a role (no-op if absent) + bump the version, atomically. */
-    async revoke(roleUuid, key) {
-        const conn = await this.pool.getConnection();
-        try {
-            await conn.beginTransaction();
-            await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?`, [roleUuid, key]);
-            await this.bumper.bumpForRole(roleUuid, conn);
-            await conn.commit();
-        }
-        catch (cause) {
-            await conn.rollback();
-            throw new core_1.AuthorizationUnavailableError('revoke failed', cause);
+    /**
+     * Write the grant-administration audit row(s) on the transaction connection (D6). One row per
+     * distinct tenant among the actor's tenant and every tenant the change bumped, so each affected
+     * tenant's auditor sees it. Names, never ids, in the detail (ADR-0012): the role name and the
+     * bumped tenants' names; the viewer resolves the actor and row tenant itself. No sink wired
+     * (legacy/tests) ⇒ nothing is written.
+     */
+    async auditGrantChange(conn, action, roleUuid, keys, actor, bumpedTenants, extra) {
+        if (!this.audit)
+            return;
+        const query = (sql, params) => conn.query(sql, params);
+        const roleRows = (await query(`SELECT r_name FROM \`${APP}\`.\`roles\` WHERE r_uuid = ? LIMIT 1`, [roleUuid]));
+        const tenants = [...new Set(bumpedTenants)];
+        const nameOf = new Map();
+        if (tenants.length > 0) {
+            const ph = tenants.map(() => '?').join(', ');
+            const rows = (await query(`SELECT c_uuid, c_name FROM \`${APP}\`.\`companies\` WHERE c_uuid IN (${ph})`, tenants));
+            for (const r of rows)
+                nameOf.set(r.c_uuid, r.c_name);
         }
-        finally {
-            await conn.release();
+        const labelOf = (t) => nameOf.get(t) ?? '(deleted organisation)';
+        const bumpedSet = new Set(tenants);
+        // Security review F1: each row is filed under ONE tenant and names ONLY that tenant — a
+        // tenant's auditor must never learn which OTHER tenants use the same (shared) role. The one
+        // exception is root's own row, filed under a tenant the change did NOT bump, which may carry
+        // the full list (root administers across tenants).
+        const tenantsFor = (rowTenant) => {
+            if (bumpedSet.has(rowTenant))
+                return [labelOf(rowTenant)];
+            return actor.isRoot === true ? tenants.map(labelOf) : [];
+        };
+        const occurredAtMs = Date.now();
+        for (const tenantId of new Set([actor.tenantId, ...tenants])) {
+            const tenantNames = tenantsFor(tenantId);
+            await this.audit.record({
+                type: 'admin_action',
+                occurredAtMs,
+                actorId: actor.id,
+                tenantId,
+                action: { key: action },
+                attributes: {
+                    eventType: 'role_grant',
+                    role: roleRows[0]?.r_name ?? '(deleted role)',
+                    keys: [...keys],
+                    tenants: tenantNames,
+                    ...extra,
+                },
+            }, query);
         }
     }
+    /**
+     * Grant a key to a role (idempotent) + bump the version + audit, atomically. The `grantor`
+     * Principal stamps `rp_granted_at`/`rp_granted_by` on a NEWLY-inserted row (a duplicate is a
+     * no-op and its existing stamp is left as-is). Order: catalog validation (400) → role binding
+     * (404/403) → ceiling (403) → write. Root bypasses the binding rule and the ceiling.
+     */
+    async grant(roleUuid, key, grantor) {
+        await this.assertValidKey(key); // throws BadKeyError (400) before touching the store
+        await this.assertMayChangeGrants(roleUuid, [key], grantor);
+        const actorUuid = grantor.id;
+        await this.writeGrants('role.permission_granted', roleUuid, [key], grantor, async (conn, k) => {
+            // Idempotent insert — UNIQUE (rp_role_uuid, rp_perm_key); a duplicate is a no-op.
+            await conn.query(`INSERT INTO \`${AUTHZ}\`.\`role_permission\`
+           (rp_uuid, rp_role_uuid, rp_perm_key, rp_granted_at, rp_granted_by)
+           SELECT UUID(), ?, ?, UTC_TIMESTAMP(), ?
+            WHERE NOT EXISTS (
+              SELECT 1 FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?
+            )`, [roleUuid, k, actorUuid ?? null, roleUuid, k]);
+        });
+    }
+    /**
+     * 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.
+     */
+    async revoke(roleUuid, key, actor) {
+        await this.assertMayChangeGrants(roleUuid, [key], actor);
+        await this.writeGrants('role.permission_revoked', roleUuid, [key], actor, async (conn, k) => {
+            await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?`, [roleUuid, k]);
+        });
+    }
     // ── Access bundles ────────────────────────────────────────────────────────
     /** All active bundles + their resolved atomic keys, for the Access UI. */
     async listBundles() {
@@ -159,56 +253,38 @@ class GrantAdminService {
      * Grant a bundle to a role: resolve the bundle → its atomic keys, then INSERT each
      * into `role_permission` idempotently in ONE transaction with ONE version bump.
      * An unknown / orphaned bundle → `BadKeyError` (mapped to 400 by the controller).
+     * ADR-0029: a non-root `grantor` must effectively hold EVERY atomic key the bundle expands
+     * to; otherwise `GrantCeilingError` (403), checked before any write. Root bypasses.
      */
-    async grantBundle(roleUuid, bundleKey, actorUuid) {
+    async grantBundle(roleUuid, bundleKey, grantor) {
         const keys = await this.resolveBundleKeysOrThrow(bundleKey);
-        const conn = await this.pool.getConnection();
-        try {
-            await conn.beginTransaction();
-            for (const key of keys) {
-                // Idempotent — UNIQUE (rp_role_uuid, rp_perm_key); a duplicate is a no-op.
-                await conn.query(`INSERT INTO \`${AUTHZ}\`.\`role_permission\`
+        // Binding rule + ADR-0029 ceiling: a non-root grantor must hold EVERY atomic key the bundle
+        // expands to — checked before any write (no partial bundle escalation).
+        await this.assertMayChangeGrants(roleUuid, [...keys], grantor);
+        const actorUuid = grantor.id;
+        await this.writeGrants('role.bundle_granted', roleUuid, keys, grantor, async (conn, key) => {
+            // Idempotent — UNIQUE (rp_role_uuid, rp_perm_key); a duplicate is a no-op.
+            await conn.query(`INSERT INTO \`${AUTHZ}\`.\`role_permission\`
              (rp_uuid, rp_role_uuid, rp_perm_key, rp_granted_at, rp_granted_by)
              SELECT UUID(), ?, ?, UTC_TIMESTAMP(), ?
               WHERE NOT EXISTS (
                 SELECT 1 FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?
               )`, [roleUuid, key, actorUuid ?? null, roleUuid, key]);
-            }
-            await this.bumper.bumpForRole(roleUuid, conn);
-            await conn.commit();
-        }
-        catch (cause) {
-            await conn.rollback();
-            throw new core_1.AuthorizationUnavailableError('grant bundle failed', cause);
-        }
-        finally {
-            await conn.release();
-        }
+        }, { bundle: bundleKey });
     }
     /**
      * Revoke a bundle from a role: resolve → DELETE each of the bundle's atomic keys, in
-     * ONE transaction with ONE version bump. Caveat (design §5.1): this removes exactly the
+     * ONE transaction with ONE version bump + audit. Caveat (design §5.1): this removes exactly the
      * bundle's keys even if a manual grant or another bundle shares one — the model is
-     * key-based, not bundle-membership-based. Unknown bundle → `BadKeyError`.
+     * key-based, not bundle-membership-based. Unknown bundle → `BadKeyError`. Security hardening
+     * #1: the binding rule + "only revoke what you hold" apply (root bypasses).
      */
-    async revokeBundle(roleUuid, bundleKey) {
+    async revokeBundle(roleUuid, bundleKey, actor) {
         const keys = await this.resolveBundleKeysOrThrow(bundleKey);
-        const conn = await this.pool.getConnection();
-        try {
-            await conn.beginTransaction();
-            for (const key of keys) {
-                await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?`, [roleUuid, key]);
-            }
-            await this.bumper.bumpForRole(roleUuid, conn);
-            await conn.commit();
-        }
-        catch (cause) {
-            await conn.rollback();
-            throw new core_1.AuthorizationUnavailableError('revoke bundle failed', cause);
-        }
-        finally {
-            await conn.release();
-        }
+        await this.assertMayChangeGrants(roleUuid, [...keys], actor);
+        await this.writeGrants('role.bundle_revoked', roleUuid, keys, actor, async (conn, key) => {
+            await conn.query(`DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_role_uuid = ? AND rp_perm_key = ?`, [roleUuid, key]);
+        }, { bundle: bundleKey });
     }
     /** Resolve a bundle key → its atomic keys; throw BadKeyError when unknown/orphaned. */
     async resolveBundleKeysOrThrow(bundleKey) {
@@ -251,7 +327,9 @@ class GrantAdminService {
             // subtree (the EXISTS predicate); root spans all tenants (no predicate). The scope clause
             // sits FIRST in the WHERE (before the LIKE), so its ?-bound node params lead the arg list —
             // identical on BOTH the count and page queries so they can never disagree.
-            const scope = subtreeScope.isRoot ? { sql: '', params: [] } : subtreeExists(subtreeScope.nodeIds);
+            const scope = subtreeScope.isRoot
+                ? { sql: '', params: [] }
+                : (0, role_binding_js_1.subtreeExists)(subtreeScope.nodeIds);
             // Distinct granted roles (a role appears iff it has ≥1 role_permission row), filtered
             // by name search. Bind the LIKE term as a param (wildcards escaped).
             const likeClause = search ? `AND r.r_name LIKE ?` : '';

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

@@ -0,0 +1,111 @@
+/**
+ * Grant-admin self-escalation ceiling (ADR-0029) — "only grant what you hold".
+ *
+ * A non-root grantor may only grant a role a permission key the grantor THEMSELVES effectively
+ * holds. This module provides:
+ *   • `coversKey` — a PURE predicate: does an effective key set cover a granted key (exact or
+ *     wildcard)? A wildcard is covered only if EVERY registered exact key it expands to is held.
+ *   • `GrantCeiling` — resolves a grantor's effective keys (their roles' `role_permission` rows in
+ *     their tenant, wildcards expanded) and asserts coverage; throws `GrantCeilingError` (→ 403) on
+ *     violation, `AuthorizationUnavailableError` (→ 503) on a store outage (fail-closed).
+ *
+ * Reuses the SAME `expandGrantKeys` + `readRoleIdsForTenant` the object-type gate uses — one
+ * definition of "what a principal holds". Root (strict `isRoot === true`) bypasses.
+ */
+import type { Pool } from 'mariadb';
+import type { ModuleRegistry, Principal } from '@astram/core';
+import { type RoleBinding } from './role-binding.js';
+/** The grantor exceeds their own authority — cannot grant a key they do not hold (→ 403). */
+export declare class GrantCeilingError extends Error {
+    constructor(key: string, message?: string);
+}
+/** The actor's reachable subtree: the session's cached closure, else the self node (non-widening). */
+export declare function subtreeOf(actor: Principal): readonly string[];
+/**
+ * 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.
+ */
+export declare function coversKey(effective: ReadonlySet<string>, registeredKeys: readonly string[], granted: string): boolean;
+/**
+ * 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.
+ */
+export declare class GrantCeiling {
+    private readonly pool;
+    private readonly registry;
+    /** Injectable clock (epoch-ms) for the posting effective-window read; defaults to Date.now. */
+    private readonly now;
+    private readonly rootIds;
+    constructor(pool: Pool, registry: ModuleRegistry, 
+    /**
+     * 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: readonly string[] | null, 
+    /** Injectable clock (epoch-ms) for the posting effective-window read; defaults to Date.now. */
+    now?: () => number);
+    /** The D1 administer rule over a binding read: used inside and nowhere outside (404 / 403). */
+    static checkAdministrable(b: RoleBinding): void;
+    /** The #11 assign rule over a binding read: never a role also used outside (403). */
+    static checkAssignable(b: RoleBinding): void;
+    /** The registry's exact-key universe (wildcard expansion bound). */
+    private registeredKeys;
+    /** The raw `role_permission` keys of `roleIds` (exact or wildcard). Store errors propagate. */
+    private rawKeysOfRoles;
+    /** Run a store read, mapping any non-domain failure to AuthorizationUnavailableError (503). */
+    private facts;
+    /**
+     * 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).
+     */
+    effectiveKeys(grantor: Principal): Promise<Set<string>>;
+    /**
+     * 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.
+     */
+    assertCanGrant(grantor: Principal, keys: readonly string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    assertCanAssignRoles(actor: Principal, roleIds: readonly string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    assertDominates(actor: Principal, targetUserId: string): Promise<void>;
+    /** Where `roleUuid` is bound relative to the actor's subtree (postings + service accounts). */
+    roleBinding(actor: Principal, roleUuid: string): Promise<RoleBinding>;
+    /**
+     * 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.
+     */
+    assertRoleAdministrable(actor: Principal, roleUuid: string): Promise<void>;
+    /**
+     * 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.
+     */
+    assertRoleAssignable(actor: Principal, roleUuid: string): Promise<void>;
+}
+//# sourceMappingURL=grant-ceiling.d.ts.map

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

@@ -0,0 +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"}