@astram/identity 0.4.0 → 0.5.0

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 {
@@ -34,17 +22,22 @@ class GrantAdminService {
     pool;
     bumper;
     ceiling;
+    audit;
     bundles;
     /**
-     * @param ceiling  The ADR-0029 self-escalation ceiling ("only grant what you hold"). Enforced
-     *   on `grant()`/`grantBundle()` for a non-root grantor. OPTIONAL for back-compat: when absent
-     *   (legacy wiring / tests that don't exercise the ceiling), the ceiling is not applied — the
-     *   identity module ALWAYS wires it, so production always enforces. Root bypasses regardless.
+     * @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) {
+    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. */
@@ -60,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))];
@@ -106,57 +102,142 @@ class GrantAdminService {
             throw new BadKeyError(key);
     }
     /**
-     * Grant a key to a role (idempotent) + bump the version, 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) AND is subjected to the ADR-0029 self-escalation ceiling:
-     * a non-root grantor may only grant a key they themselves effectively hold. Order: catalog
-     * validation (400) → ceiling (403) → write. Root bypasses the ceiling.
+     * 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, grantor) {
-        await this.assertValidKey(key); // throws BadKeyError (400) before touching the store
-        // ADR-0029 ceiling: throws GrantCeilingError (403) if the grantor exceeds their authority.
-        await this.ceiling?.assertCanGrant(grantor, [key]);
-        const actorUuid = grantor.id;
+    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();
+    /**
+     * 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);
         }
-        catch (cause) {
-            await conn.rollback();
-            throw new core_1.AuthorizationUnavailableError('revoke failed', cause);
-        }
-        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() {
@@ -177,57 +258,33 @@ class GrantAdminService {
      */
     async grantBundle(roleUuid, bundleKey, grantor) {
         const keys = await this.resolveBundleKeysOrThrow(bundleKey);
-        // ADR-0029 ceiling: a non-root grantor must hold EVERY atomic key the bundle expands to,
-        // else GrantCeilingError (403) — checked before any write (no partial bundle escalation).
-        await this.ceiling?.assertCanGrant(grantor, [...keys]);
+        // 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;
-        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\`
+        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) {
@@ -270,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

@@ -14,10 +14,13 @@
  */
 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);
+    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`?
  *
@@ -40,9 +43,27 @@ export declare class GrantCeiling {
     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
@@ -56,5 +77,35 @@ export declare class GrantCeiling {
      * `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

@@ -1 +1 @@
-{"version":3,"file":"grant-ceiling.d.ts","sourceRoot":"","sources":["../../../src/features/authz/grant-ceiling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9D,6FAA6F;AAC7F,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,GAAG,EAAE,MAAM;CAIxB;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;IAErB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,+FAA+F;IAC/F,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAHH,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,cAAc;IACzC,+FAA+F;IAC9E,GAAG,GAAE,MAAM,MAAiB;IAG/C;;;;;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;CAUjF"}
+{"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"}

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

@@ -1,18 +1,26 @@
 "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) {
-        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 +52,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 +147,102 @@ 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. 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"}