@astram/identity 0.4.0 → 0.6.0

package/dist/features/authz/record-authorization.js

@@ -3,8 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityRegistryMismatchError = void 0;
 exports.createIdentityAuthzPool = createIdentityAuthzPool;
 exports.buildIdentityRecordAuthorization = buildIdentityRecordAuthorization;
+exports.buildRecordAuthorizationInputs = buildRecordAuthorizationInputs;
+exports.noteIdentityCeilingRegistry = noteIdentityCeilingRegistry;
 /**
  * Assemble the record-tier authorization wiring for `@astram/identity`: the lean grant-read
  * pool factory + the `recordAuthorization` inputs the consumer passes to
@@ -56,6 +59,15 @@ function createIdentityAuthzPool() {
  * those keys now project, and the framework still owns the four record-tier adapters + scope fn.
  */
 function buildIdentityRecordAuthorization(pool, extraObjects = []) {
+    const inputs = buildRecordAuthorizationInputs(pool, extraObjects);
+    noteRegistry('decision', inputs.registry);
+    return inputs;
+}
+/**
+ * The inputs builder WITHOUT the boot parity record — for the identity module's own internal
+ * authorities (they are not the decision path the consumer hands `ShieldModule`).
+ */
+function buildRecordAuthorizationInputs(pool, extraObjects = []) {
     const registry = (0, guard_1.buildIdentityModuleRegistry)([...objects_js_1.identityObjects, ...extraObjects]);
     return {
         pool,
@@ -65,3 +77,40 @@ function buildIdentityRecordAuthorization(pool, extraObjects = []) {
         operationManifest: [],
     };
 }
+const recordedKeySets = {
+    decision: new Map(),
+    ceiling: new Map(),
+};
+/** The boot error: the two registries' action-key sets differ (names the first differing keys). */
+class IdentityRegistryMismatchError extends Error {
+    constructor(onlyDecision, onlyCeiling) {
+        const sample = (keys) => keys.length === 0 ? 'none' : keys.slice(0, 10).join(', ') + (keys.length > 10 ? ', …' : '');
+        super('IdentityFeatureModule.forRoot({ extraObjects }) and buildIdentityRecordAuthorization(pool, ' +
+            'extraObjects) were given different object types. Pass the SAME array to both. ' +
+            `Only in the decision path: ${sample(onlyDecision)}. ` +
+            `Only in IdentityFeatureModule: ${sample(onlyCeiling)}.`);
+        this.name = 'IdentityRegistryMismatchError';
+    }
+}
+exports.IdentityRegistryMismatchError = IdentityRegistryMismatchError;
+/** Record one side's registry and throw if it disagrees with any recorded registry of the other. */
+function noteRegistry(role, registry) {
+    const keys = [...new Set(registry.listActions().map((a) => a.permissionKey))].sort();
+    const other = recordedKeySets[role === 'decision' ? 'ceiling' : 'decision'];
+    for (const otherKeys of other.values()) {
+        const mine = new Set(keys);
+        const theirs = new Set(otherKeys);
+        const onlyMine = keys.filter((k) => !theirs.has(k));
+        const onlyTheirs = otherKeys.filter((k) => !mine.has(k));
+        if (onlyMine.length > 0 || onlyTheirs.length > 0) {
+            throw role === 'decision'
+                ? new IdentityRegistryMismatchError(onlyMine, onlyTheirs)
+                : new IdentityRegistryMismatchError(onlyTheirs, onlyMine);
+        }
+    }
+    recordedKeySets[role].set(keys.join('\n'), keys);
+}
+/** Called by `IdentityFeatureModule.forRoot` with the grant ceiling's registry (Phase 8 #4). */
+function noteIdentityCeilingRegistry(registry) {
+    noteRegistry('ceiling', registry);
+}

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,108 @@
+/**
+ * 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; the
+ *     node is not the actor's own root; the actor dominates every member and may administer every
+ *     service account of the company (Phase 8 #3). The delete disables those agents, revokes their
+ *     keys, drops the node from other agents' scopes and revokes cross-tenant grants naming it.
+ *
+ * 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>;
+}
+/**
+ * The authority checks a company delete needs — over each member and each of the company's own
+ * service accounts. `GrantCeiling` satisfies it.
+ */
+export interface MemberDominance {
+    assertDominates(actor: Principal, targetUserId: string): Promise<void>;
+    assertMayRetireServiceAccounts(actor: Principal, accounts: ReadonlyArray<{
+        readonly tenantId: string;
+        readonly scopeSubtreeNodeIds: readonly string[];
+        readonly roleIds: readonly string[];
+    }>): Promise<void>;
+}
+export declare class CompanyHierarchyService {
+    private readonly pool;
+    private readonly closure;
+    /** Phase 8 #3: required — a company delete must dominate every member (no silent skip). */
+    private readonly ceiling;
+    private readonly audit?;
+    private readonly now;
+    constructor(pool: HierarchyQueryable, closure: ScopeClosureService, 
+    /** Phase 8 #3: required — a company delete must dominate every member (no silent skip). */
+    ceiling: MemberDominance, 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
+     * and own-node bump in one transaction). The caller has already checked reach (walled read).
+     *
+     * Phase 8 #3: the delete cascades every membership and posting of the company, stripping its
+     * members' authority there, so a non-root actor must DOMINATE every member (the actor itself is
+     * skipped). Inside the delete's transaction and tree lock, before anything is deleted: lock the
+     * company row (a new membership's FK check waits on it), read the members with a locking read
+     * (latest committed rows, no insert into the range until commit), then `assertDominates` each.
+     * Any refusal rolls the whole delete back (403). Root bypasses the dominance check.
+     *
+     * Phase 8 #3 (continued): nothing in the database ties a service account or a cross-tenant grant
+     * to its company (no FK), so, still before the company row goes and on the same transaction,
+     * {@link retireDependents} disables the company's agents and revokes their keys, removes the
+     * company from other agents' scopes, and revokes every cross-tenant grant naming it — audited on
+     * that transaction. One transaction: a failure anywhere leaves the company and everything
+     * depending on it as they were; a commit leaves a deleted company with no live agent or grant.
+     */
+    remove(actor: Principal, nodeUuid: string): Promise<void>;
+    /**
+     * Retire what depends on a company being deleted (Phase 8 #3), on the delete's transaction after
+     * the company row lock and the member check, BEFORE the company row is deleted. Returns the
+     * tenants whose agents changed (the delete bumps them with the node and its ancestors).
+     *
+     *  1. Agents (`shield_app.service_account`) bound to the company, or whose scope names it, are
+     *     read with a locking read.
+     *  2. The company's OWN agents: a non-root actor must be able to administer every one of them
+     *     (`assertMayRetireServiceAccounts`, the ADR-0029 ceiling: scope and roles within its own) or
+     *     the whole delete is refused (403). Then each is disabled and its keys revoked (the same
+     *     `sak_revoked_at_ms` stamp `MariaDbApiKeyStore.revoke` writes, here on this transaction).
+     *  3. Other tenants' agents lose the company from their scope (reach over a deleted node only;
+     *     the actor dominates that node). An agent whose ENTIRE scope was the company is disabled and
+     *     its keys revoked instead — an empty scope would make the API-key path fall back to the
+     *     agent's own tenant, a widening — and its scope is left as it was (a dead reference, never
+     *     wider). These need no further authority check: they lose only reach over the deleted node.
+     *  4. Cross-tenant grants (`shield_authz.cross_tenant_grant`) where the company is the owning or
+     *     the grantee tenant and that are not yet revoked are revoked exactly as
+     *     `CrossTenantGrantWriter.revoke` does (status + `ctg_revoked_at`), and audited under both
+     *     tenants. The writer itself cannot join this transaction (it writes on its own pool, and
+     *     audits best-effort after the write); either side may revoke (ADR-0009), and the actor's
+     *     authority over the deleted side is the delete itself.
+     * Every change is audited on this transaction (names; ids only in structured attributes).
+     */
+    private retireDependents;
+    /** Step 4 of {@link retireDependents}: revoke and audit the grants naming the company. */
+    private revokeGrantsNaming;
+    /** Lock the company, then require dominance over each of its members (see `remove`). */
+    private assertMayDeleteMembers;
+    /** 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;;;;;;;;;;;;;;;;;;;GAmBG;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;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,8BAA8B,CAC5B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,aAAa,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;QAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KACrC,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAuCD,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBALH,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,mBAAmB;IAC7C,2FAA2F;IAC1E,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,SAAS,YAAA,EACjB,GAAG,GAAE,MAAM,MAAiB;IAG/C,0EAA0E;IAC1E,OAAO,CAAC,OAAO;IAIf,uDAAuD;YACzC,KAAK;YAUL,WAAW;IAqBzB,iGAAiG;IAC3F,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkD3F;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB/D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;YACW,gBAAgB;IA6E9B,0FAA0F;YAC5E,kBAAkB;IAmDhC,wFAAwF;YAC1E,sBAAsB;IA+BpC,wFAAwF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD"}

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

@@ -0,0 +1,277 @@
+"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';
+const AUTHZ = 'shield_authz';
+/** A JSON-array column (the driver returns an array OR a string) → its string items; else []. */
+function jsonIdArray(v) {
+    let arr = v;
+    if (typeof v === 'string') {
+        try {
+            arr = JSON.parse(v);
+        }
+        catch {
+            arr = [];
+        }
+    }
+    return Array.isArray(arr) ? arr.filter((x) => typeof x === 'string') : [];
+}
+class CompanyHierarchyService {
+    pool;
+    closure;
+    ceiling;
+    audit;
+    now;
+    constructor(pool, closure, 
+    /** Phase 8 #3: required — a company delete must dominate every member (no silent skip). */
+    ceiling, audit, now = Date.now) {
+        this.pool = pool;
+        this.closure = closure;
+        this.ceiling = ceiling;
+        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, tenantId = actor.tenantId) {
+        if (!this.audit)
+            return;
+        await this.audit.record({
+            type: 'admin_action',
+            occurredAtMs: this.now(),
+            actorId: actor.id,
+            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
+     * and own-node bump in one transaction). The caller has already checked reach (walled read).
+     *
+     * Phase 8 #3: the delete cascades every membership and posting of the company, stripping its
+     * members' authority there, so a non-root actor must DOMINATE every member (the actor itself is
+     * skipped). Inside the delete's transaction and tree lock, before anything is deleted: lock the
+     * company row (a new membership's FK check waits on it), read the members with a locking read
+     * (latest committed rows, no insert into the range until commit), then `assertDominates` each.
+     * Any refusal rolls the whole delete back (403). Root bypasses the dominance check.
+     *
+     * Phase 8 #3 (continued): nothing in the database ties a service account or a cross-tenant grant
+     * to its company (no FK), so, still before the company row goes and on the same transaction,
+     * {@link retireDependents} disables the company's agents and revokes their keys, removes the
+     * company from other agents' scopes, and revokes every cross-tenant grant naming it — audited on
+     * that transaction. One transaction: a failure anywhere leaves the company and everything
+     * depending on it as they were; a commit leaves a deleted company with no live agent or grant.
+     */
+    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) ?? '(unknown)';
+        await this.closure.deleteNode(nodeUuid, (conn) => this.recordAudit(conn, actor, 'company.deleted', { company: name }), async (conn) => {
+            await this.assertMayDeleteMembers(conn, actor, nodeUuid);
+            return this.retireDependents(conn, actor, nodeUuid, name);
+        });
+    }
+    /**
+     * Retire what depends on a company being deleted (Phase 8 #3), on the delete's transaction after
+     * the company row lock and the member check, BEFORE the company row is deleted. Returns the
+     * tenants whose agents changed (the delete bumps them with the node and its ancestors).
+     *
+     *  1. Agents (`shield_app.service_account`) bound to the company, or whose scope names it, are
+     *     read with a locking read.
+     *  2. The company's OWN agents: a non-root actor must be able to administer every one of them
+     *     (`assertMayRetireServiceAccounts`, the ADR-0029 ceiling: scope and roles within its own) or
+     *     the whole delete is refused (403). Then each is disabled and its keys revoked (the same
+     *     `sak_revoked_at_ms` stamp `MariaDbApiKeyStore.revoke` writes, here on this transaction).
+     *  3. Other tenants' agents lose the company from their scope (reach over a deleted node only;
+     *     the actor dominates that node). An agent whose ENTIRE scope was the company is disabled and
+     *     its keys revoked instead — an empty scope would make the API-key path fall back to the
+     *     agent's own tenant, a widening — and its scope is left as it was (a dead reference, never
+     *     wider). These need no further authority check: they lose only reach over the deleted node.
+     *  4. Cross-tenant grants (`shield_authz.cross_tenant_grant`) where the company is the owning or
+     *     the grantee tenant and that are not yet revoked are revoked exactly as
+     *     `CrossTenantGrantWriter.revoke` does (status + `ctg_revoked_at`), and audited under both
+     *     tenants. The writer itself cannot join this transaction (it writes on its own pool, and
+     *     audits best-effort after the write); either side may revoke (ADR-0009), and the actor's
+     *     authority over the deleted side is the delete itself.
+     * Every change is audited on this transaction (names; ids only in structured attributes).
+     */
+    async retireDependents(conn, actor, nodeUuid, companyName) {
+        const agents = (await conn.query(`SELECT sa_id, sa_tenant_id, sa_label, sa_scope_subtree, sa_role_ids, sa_updated_at_ms
+         FROM \`${APP}\`.\`service_account\`
+        WHERE sa_tenant_id = ? OR JSON_CONTAINS(sa_scope_subtree, JSON_QUOTE(?))
+        ORDER BY sa_id
+        FOR UPDATE`, [nodeUuid, nodeUuid]));
+        const own = agents.filter((a) => a.sa_tenant_id === nodeUuid);
+        const others = agents.filter((a) => a.sa_tenant_id !== nodeUuid);
+        // Root bypasses inside; a refusal (403, names no agent) rolls the whole delete back.
+        await this.ceiling.assertMayRetireServiceAccounts(actor, own.map((a) => ({
+            tenantId: a.sa_tenant_id,
+            scopeSubtreeNodeIds: jsonIdArray(a.sa_scope_subtree),
+            roleIds: jsonIdArray(a.sa_role_ids),
+        })));
+        const nowMs = this.now();
+        const touched = new Set();
+        const editStamp = (a) => Math.max(nowMs, (a.sa_updated_at_ms == null ? 0 : Number(a.sa_updated_at_ms)) + 1);
+        const retire = async (a, reason) => {
+            await conn.query(`UPDATE \`${APP}\`.\`service_account\` SET sa_status = 'disabled', sa_updated_at_ms = ? WHERE sa_id = ?`, [editStamp(a), a.sa_id]);
+            const res = (await conn.query(`UPDATE \`${AUTHZ}\`.\`service_account_key\`
+            SET sak_revoked_at_ms = ?
+          WHERE sak_account_id = ? AND sak_revoked_at_ms IS NULL`, [nowMs, a.sa_id]));
+            touched.add(a.sa_tenant_id);
+            await this.recordAudit(conn, actor, 'service_account.disabled', {
+                eventType: 'service_account',
+                accountId: a.sa_id,
+                account: a.sa_label,
+                company: companyName,
+                reason,
+                keysRevoked: Number(res?.affectedRows ?? 0),
+            });
+        };
+        for (const a of own)
+            await retire(a, 'company_deleted');
+        for (const a of others) {
+            const remaining = jsonIdArray(a.sa_scope_subtree).filter((n) => n !== nodeUuid);
+            if (remaining.length === 0) {
+                await retire(a, 'scope_company_deleted');
+                continue;
+            }
+            await conn.query(`UPDATE \`${APP}\`.\`service_account\` SET sa_scope_subtree = ?, sa_updated_at_ms = ? WHERE sa_id = ?`, [JSON.stringify(remaining), editStamp(a), a.sa_id]);
+            touched.add(a.sa_tenant_id);
+            await this.recordAudit(conn, actor, 'service_account.updated', {
+                eventType: 'service_account',
+                accountId: a.sa_id,
+                account: a.sa_label,
+                fields: ['scopeSubtreeNodeIds'],
+                scopeRemoved: [companyName],
+                reason: 'company_deleted',
+            });
+        }
+        await this.revokeGrantsNaming(conn, actor, nodeUuid, companyName);
+        return [...touched];
+    }
+    /** Step 4 of {@link retireDependents}: revoke and audit the grants naming the company. */
+    async revokeGrantsNaming(conn, actor, nodeUuid, companyName) {
+        const grants = (await conn.query(`SELECT ctg_uuid, ctg_owning_tenant_uuid, ctg_grantee_tenant_uuid, ctg_grantee_kind,
+              ctg_grantee_uuid, ctg_type_key, ctg_scope, ctg_allowed_actions
+         FROM \`${AUTHZ}\`.\`cross_tenant_grant\`
+        WHERE (ctg_owning_tenant_uuid = ? OR ctg_grantee_tenant_uuid = ?)
+          AND ctg_status <> 'revoked'
+        ORDER BY ctg_uuid
+        FOR UPDATE`, [nodeUuid, nodeUuid]));
+        if (grants.length === 0)
+            return;
+        const revokedAt = new Date(this.now());
+        const otherSides = grants.map((g) => g.ctg_owning_tenant_uuid === nodeUuid ? g.ctg_grantee_tenant_uuid : g.ctg_owning_tenant_uuid);
+        const names = await this.names(conn, otherSides);
+        for (const [i, g] of grants.entries()) {
+            await conn.query(`UPDATE \`${AUTHZ}\`.\`cross_tenant_grant\`
+            SET ctg_status = 'revoked', ctg_revoked_at = ?
+          WHERE ctg_uuid = ? AND ctg_status <> 'revoked'`, [revokedAt, g.ctg_uuid]);
+            const other = otherSides[i];
+            const attributes = {
+                eventType: 'cross_tenant_grant',
+                grantUuid: g.ctg_uuid,
+                typeKey: g.ctg_type_key,
+                scope: g.ctg_scope === 'record' ? 'record' : 'object_type',
+                granteeKind: g.ctg_grantee_kind === 'role' ? 'role' : 'user',
+                granteeUuid: g.ctg_grantee_uuid,
+                allowedActions: jsonIdArray(g.ctg_allowed_actions),
+                owningTenantId: g.ctg_owning_tenant_uuid,
+                granteeTenantId: g.ctg_grantee_tenant_uuid,
+                reason: 'company_deleted',
+                company: companyName,
+                otherCompany: names.get(other) ?? '(deleted organisation)',
+            };
+            // Audit on BOTH tenants (ADR-0009), one row each, as the writer's audit bridge files it.
+            for (const tenantId of new Set([g.ctg_owning_tenant_uuid, g.ctg_grantee_tenant_uuid])) {
+                await this.recordAudit(conn, actor, 'grant.revoked', attributes, tenantId);
+            }
+        }
+    }
+    /** Lock the company, then require dominance over each of its members (see `remove`). */
+    async assertMayDeleteMembers(conn, actor, nodeUuid) {
+        await conn.query(`SELECT c_uuid FROM \`${APP}\`.\`companies\` WHERE c_uuid = ? FOR UPDATE`, [
+            nodeUuid,
+        ]);
+        if (actor.isRoot === true)
+            return;
+        const rows = (await conn.query(`SELECT cm_user_uuid AS member FROM \`${APP}\`.\`company_membership\`
+        WHERE cm_company_uuid = ? FOR UPDATE`, [nodeUuid]));
+        const members = [...new Set(rows.map((r) => r.member))].sort();
+        for (const member of members) {
+            if (member === actor.id)
+                continue; // leaving your own membership behind stays allowed
+            try {
+                await this.ceiling.assertDominates(actor, member);
+            }
+            catch (cause) {
+                if (cause instanceof identity_errors_js_1.IdentityForbiddenError || cause instanceof identity_errors_js_1.IdentityNotFoundError) {
+                    // Names no member (who belongs to the company is not the caller's to learn from a refusal).
+                    throw new identity_errors_js_1.IdentityForbiddenError('You cannot delete this company: one of its members is outside your authority.');
+                }
+                throw cause;
+            }
+        }
+    }
+    /** 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"}