@astram/identity 0.4.0 → 0.5.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"company-hierarchy.service.d.ts","sourceRoot":"","sources":["../../../src/features/company/company-hierarchy.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAkB,MAAM,mCAAmC,CAAC;AAUxF,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAHH,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,mBAAmB,EAC5B,KAAK,CAAC,EAAE,SAAS,YAAA,EACjB,GAAG,GAAE,MAAM,MAAiB;IAG/C,0EAA0E;IAC1E,OAAO,CAAC,OAAO;IAIf,uDAAuD;YACzC,KAAK;YAUL,WAAW;IAoBzB,iGAAiG;IAC3F,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkD3F;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/D,wFAAwF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD"}

package/dist/features/company/company-hierarchy.service.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanyHierarchyService = void 0;
+const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const identity_errors_js_1 = require("../shared/identity-errors.js");
+const APP = 'shield_app';
+class CompanyHierarchyService {
+    pool;
+    closure;
+    audit;
+    now;
+    constructor(pool, closure, audit, now = Date.now) {
+        this.pool = pool;
+        this.closure = closure;
+        this.audit = audit;
+        this.now = now;
+    }
+    /** The actor's own root node (the active node its subtree hangs from). */
+    ownRoot(actor) {
+        return actor.activeScopeNodeId ?? actor.tenantId;
+    }
+    /** Names of the given companies (unknown → absent). */
+    async names(q, ids) {
+        const unique = [...new Set(ids)];
+        if (unique.length === 0)
+            return new Map();
+        const rows = (await q.query(`SELECT c_uuid, c_name FROM \`${APP}\`.\`companies\` WHERE c_uuid IN (${unique.map(() => '?').join(', ')})`, unique));
+        return new Map(rows.map((r) => [r.c_uuid, r.c_name]));
+    }
+    async recordAudit(conn, actor, action, attributes) {
+        if (!this.audit)
+            return;
+        await this.audit.record({
+            type: 'admin_action',
+            occurredAtMs: this.now(),
+            actorId: actor.id,
+            tenantId: actor.tenantId,
+            action: { key: action },
+            attributes: { eventType: 'company_hierarchy', ...attributes },
+        }, (sql, params) => conn.query(sql, params));
+    }
+    /** Re-parent `nodeUuid` under `newParentUuid` (null = make it a top-level tenant; root only). */
+    async move(actor, nodeUuid, newParentUuid) {
+        if (typeof nodeUuid !== 'string' || nodeUuid.length === 0) {
+            throw new identity_errors_js_1.IdentityBadRequestError('A company is required.');
+        }
+        if (newParentUuid !== null &&
+            (typeof newParentUuid !== 'string' || newParentUuid.length === 0)) {
+            throw new identity_errors_js_1.IdentityBadRequestError('parentUuid must be a company or null.');
+        }
+        if (actor.isRoot !== true) {
+            const subtree = new Set((0, grant_ceiling_js_1.subtreeOf)(actor));
+            if (!subtree.has(nodeUuid))
+                throw new identity_errors_js_1.IdentityNotFoundError('Company not found.');
+            if (nodeUuid === this.ownRoot(actor)) {
+                throw new identity_errors_js_1.IdentityForbiddenError('You cannot move the organisation your access is rooted at.');
+            }
+            if (newParentUuid === null || !subtree.has(newParentUuid)) {
+                throw new identity_errors_js_1.IdentityForbiddenError('You can only move a company under another company you manage.');
+            }
+        }
+        const names = await this.names(this.pool, [
+            nodeUuid,
+            ...(newParentUuid ? [newParentUuid] : []),
+        ]);
+        if (!names.has(nodeUuid))
+            throw new identity_errors_js_1.IdentityNotFoundError('Company not found.');
+        if (newParentUuid !== null && !names.has(newParentUuid)) {
+            throw new identity_errors_js_1.IdentityNotFoundError('Parent company not found.');
+        }
+        const oldParentRows = (await this.pool.query(`SELECT c_parent_uuid FROM \`${APP}\`.\`companies\` WHERE c_uuid = ? LIMIT 1`, [nodeUuid]));
+        const oldParent = oldParentRows[0]?.c_parent_uuid ?? null;
+        const oldParentName = oldParent
+            ? (await this.names(this.pool, [oldParent])).get(oldParent)
+            : undefined;
+        await this.closure.moveNode(nodeUuid, newParentUuid, (conn) => this.recordAudit(conn, actor, 'company.moved', {
+            company: names.get(nodeUuid),
+            from: oldParent ? (oldParentName ?? '(deleted organisation)') : '(top level)',
+            to: newParentUuid ? names.get(newParentUuid) : '(top level)',
+        }));
+    }
+    /**
+     * 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).
+     */
+    async remove(actor, nodeUuid) {
+        // Security review F6: the same own-root guard as `move` — a sub-admin never deletes the
+        // organisation its access is rooted at.
+        if (actor.isRoot !== true && nodeUuid === this.ownRoot(actor)) {
+            throw new identity_errors_js_1.IdentityForbiddenError('You cannot delete the organisation your access is rooted at.');
+        }
+        const name = (await this.names(this.pool, [nodeUuid])).get(nodeUuid);
+        await this.closure.deleteNode(nodeUuid, (conn) => this.recordAudit(conn, actor, 'company.deleted', { company: name ?? '(unknown)' }));
+    }
+    /** A company was just created: give it closure rows now and bump its ancestors (D5). */
+    async attached(nodeUuid) {
+        await this.closure.attachNode(nodeUuid);
+    }
+}
+exports.CompanyHierarchyService = CompanyHierarchyService;

package/dist/features/company/company.controller.d.ts

@@ -1,5 +1,6 @@
 import { CompanyService } from './company.service.js';
 import { type ListQueryDto } from '../shared/list-query.js';
+import type { AuthedRequest } from '../shared/http.js';
 export declare class CompanyController {
     private readonly companies;
     constructor(companies: CompanyService);
@@ -14,23 +15,40 @@ export declare class CompanyController {
         page: number;
         limit: number;
     }>;
-    /** Create a company (a new tenant) — gated on `identity:company:create`. */
-    createCompany(body: {
+    /**
+     * Create a company — gated on `identity:company:create`. A non-root caller's company is created
+     * UNDER the caller's own organisation (D5); only root creates a top-level tenant.
+     */
+    createCompany(req: AuthedRequest, body: {
         name?: string;
     }): Promise<{
         id: import("packages/engine/dist/types.js").RecordId;
     }>;
     /** Read one company — gated on `identity:company:read`. */
     getCompany(uuid: string): Promise<import("packages/engine/dist/types.js").RecordView | null>;
-    /** Update a company — gated on `identity:company:update`. */
+    /**
+     * Move a company under a new parent — gated on `identity:company:update`. Body
+     * `{ parentUuid: string | null }`. Non-root: the company and the new parent must both be in the
+     * caller's subtree, the company is not the caller's own root, and the parent is not null. A move
+     * that would form a cycle → 409. Declared BEFORE `companies/:uuid` (static sub-path first).
+     */
+    moveCompany(req: AuthedRequest, uuid: string, body: {
+        parentUuid?: string | null;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Update a company's name/status — gated on `identity:company:update`. Any other key
+     * (parentUuid, type, …) is ignored: use `PUT companies/:uuid/parent` to move a company.
+     */
     updateCompany(uuid: string, body: {
         name?: string;
         status?: string;
     }): Promise<{
         success: boolean;
     }>;
-    /** Delete a company — gated on `identity:company:delete`. */
-    deleteCompany(uuid: string): Promise<{
+    /** Delete a company — gated on `identity:company:delete`. A company with sub-companies → 409. */
+    deleteCompany(req: AuthedRequest, uuid: string): Promise<{
         success: boolean;
     }>;
 }

package/dist/features/company/company.controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"company.controller.d.ts","sourceRoot":"","sources":["../../../src/features/company/company.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5E,qBACa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,cAAc;IAEtD;;;;OAIG;IAGG,aAAa,CAAU,KAAK,EAAE,YAAY;;;;;;IAMhD,4EAA4E;IAGtE,aAAa,CAAS,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKnD,2DAA2D;IAG3D,UAAU,CAAgB,IAAI,EAAE,MAAM;IAItC,6DAA6D;IAGvD,aAAa,CAAgB,IAAI,EAAE,MAAM,EAAU,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKjG,6DAA6D;IAGvD,aAAa,CAAgB,IAAI,EAAE,MAAM;;;CAIhD"}
+{"version":3,"file":"company.controller.d.ts","sourceRoot":"","sources":["../../../src/features/company/company.controller.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,qBAEa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,cAAc;IAEtD;;;;OAIG;IAGG,aAAa,CAAU,KAAK,EAAE,YAAY;;;;;;IAMhD;;;OAGG;IAGG,aAAa,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAK9E,2DAA2D;IAG3D,UAAU,CAAgB,IAAI,EAAE,MAAM;IAItC;;;;;OAKG;IAGG,WAAW,CACR,GAAG,EAAE,aAAa,EACV,IAAI,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;;;IAa9C;;;OAGG;IAGG,aAAa,CACF,IAAI,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAMlD,iGAAiG;IAG3F,aAAa,CAAQ,GAAG,EAAE,aAAa,EAAiB,IAAI,EAAE,MAAM;;;CAI3E"}