@astram/identity 0.3.1 → 0.5.0

package/dist/features/scope/scope-closure.service.d.ts

@@ -1,3 +1,4 @@
+import { type ScopeEdge } from '@astram/guard';
 /**
  * The minimal query surface a transaction connection must expose. A `mariadb`
  * `PoolConnection` satisfies it structurally; kept framework-agnostic (mirrors `Queryable`
@@ -14,11 +15,17 @@ export interface ScopePool {
         commit(): Promise<void>;
         rollback(): Promise<void>;
         release(): Promise<void>;
+        /** Drop the session instead of pooling it (used if a named lock could not be released). */
+        destroy?(): void;
     }>;
 }
 /** The version-bump surface moveNode needs — satisfied by `PermissionVersionBumper`. */
 export interface ScopeVersionBumper {
     bumpForTenant(tenantUuid: string, conn: ScopeConn): Promise<void>;
+    /** ADR-0035: publish this transaction's bumped versions to Redis — called after `commit()`. */
+    publishCommitted?(conn: ScopeConn): Promise<void>;
+    /** ADR-0035: drop this transaction's bumped versions — called after `rollback()`. */
+    discardPending?(conn: ScopeConn): void;
 }
 export declare class ScopeClosureService {
     private readonly pool;
@@ -27,13 +34,32 @@ export declare class ScopeClosureService {
     /**
      * Rebuild `scope_closure` from the current `companies.c_parent_uuid` edges. Idempotent
      * (delete-then-insert in a tx → a second run over the same tree writes the identical set).
-     * FAIL-LOUD: an orphaned/cyclic/too-deep edge makes `buildClosureRows` throw and that
-     * propagates (the tx rolls back — never a partial closure). Returns a small summary + logs.
+     * A CYCLIC component is quarantined (no rows for it; logged loudly) so the rest of the forest
+     * still reconciles. FAIL-LOUD for the rest: an orphaned/too-deep edge makes `buildClosureRows`
+     * throw and that propagates (the tx rolls back — never a partial closure). Returns a summary.
      */
     reconcileClosure(): Promise<{
         nodes: number;
         rows: number;
+        quarantined: number;
     }>;
+    /**
+     * A node was just CREATED (security hardening D5): rebuild the closure so it has rows at once
+     * (not at the next hourly reconcile), and bump every ANCESTOR's permission version — their
+     * reachable subtree just grew — so their sessions pick the new node up at the next refresh.
+     * One transaction; fail-loud like `moveNode` (a corrupt tree aborts the rebuild). A node inside
+     * a quarantined cycle gets no rows and bumps nothing.
+     */
+    attachNode(nodeUuid: string): Promise<void>;
+    /**
+     * Run `fn` in ONE transaction while holding the tree's named lock (security review F3). Every
+     * hierarchy writer (move, delete, attach, reconcile) takes the SAME `GET_LOCK` on its own
+     * connection BEFORE `BEGIN`, so they run one at a time and each transaction's first read sees
+     * every move committed before it. Without it, two concurrent moves each pass the cycle check
+     * against the other's pre-move tree and together form a cycle. A lock that cannot be taken in
+     * time fails closed (503, nothing written). The lock is released after commit/rollback.
+     */
+    private inTreeLock;
     /**
      * Re-parent `nodeUuid` under `newParentUuid` (or null for a root). Cycle-checked FIRST via the
      * closure: if `newParentUuid` is already a descendant of `nodeUuid`, throw `ScopeCycleError`
@@ -51,7 +77,9 @@ export declare class ScopeClosureService {
      * HIGH stale-subtree-after-move leak: a parent admin kept reaching a moved-away tenant.
      * Nodes on neither side keep their exact set and are not bumped.
      */
-    moveNode(nodeUuid: string, newParentUuid: string | null): Promise<void>;
+    moveNode(nodeUuid: string, newParentUuid: string | null, 
+    /** Runs on the move's transaction after the bump (e.g. the audit row) — a throw rolls back. */
+    inTransaction?: (conn: ScopeConn) => Promise<void>): Promise<void>;
     /**
      * Delete `nodeUuid`, FAIL-CLOSED. Refuses (throws) if the node has ANY child company — never
      * silently orphans/promotes a sub-org (the `...016` FK RESTRICT enforces this at the DB too; the
@@ -65,7 +93,9 @@ export declare class ScopeClosureService {
      * the many tenant-scoped app tables that reference the deleted node) is out of scope for v1 and
      * is tracked as a follow-up; deleteNode v1 only guarantees the HIERARCHY stays consistent.
      */
-    deleteNode(nodeUuid: string): Promise<void>;
+    deleteNode(nodeUuid: string, 
+    /** Runs on the delete's transaction after the bump (e.g. the audit row) — a throw rolls back. */
+    inTransaction?: (conn: ScopeConn) => Promise<void>): Promise<void>;
     /** Read the node forest's parent edges (`c_uuid` → `c_parent_uuid`) as `ScopeEdge[]`. */
     private readEdges;
     /**
@@ -75,6 +105,16 @@ export declare class ScopeClosureService {
      */
     private rewriteClosure;
 }
+/**
+ * Split the edge set into the CLEAN part and the nodes QUARANTINED because their parent chain
+ * reaches a cycle (the cycle's members and everything below them). PURE. Orphans and depth are
+ * left to `buildClosureRows` (still fail-loud): only a cycle is quarantined, because a cycle is
+ * the corruption a tenant admin could once create through the generic company patch (#2).
+ */
+export declare function quarantineCycles(edges: readonly ScopeEdge[]): {
+    clean: ScopeEdge[];
+    quarantined: string[];
+};
 /** deleteNode fail-closed guard: the node still has child companies (re-parent/cascade first). */
 export declare class NodeHasChildrenError extends Error {
     constructor(nodeUuid: string);

package/dist/features/scope/scope-closure.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-closure.service.d.ts","sourceRoot":"","sources":["../../../src/features/scope/scope-closure.service.ts"],"names":[],"mappings":"AAqCA;;;;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,iGAAiG;AACjG,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,aAAa,IAAI,OAAO,CACtB,SAAS,GAAG;QACV,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KAC1B,CACF,CAAC;CACH;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,kBAAkB;IAG7C;;;;;OAKG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBlE;;;;;;;;;;;;;;;;OAgBG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IA2E7E;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCjD,yFAAyF;YAC3E,SAAS;IAOvB;;;;OAIG;YACW,cAAc;CAiB7B;AAED,kGAAkG;AAClG,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM;CAQ7B"}
+{"version":3,"file":"scope-closure.service.d.ts","sourceRoot":"","sources":["../../../src/features/scope/scope-closure.service.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAOlF;;;;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,iGAAiG;AACjG,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,aAAa,IAAI,OAAO,CACtB,SAAS,GAAG;QACV,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACxB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACzB,2FAA2F;QAC3F,OAAO,CAAC,IAAI,IAAI,CAAC;KAClB,CACF,CAAC;CACH;AAOD,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,+FAA+F;IAC/F,gBAAgB,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,qFAAqF;IACrF,cAAc,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;CACxC;AAED,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,kBAAkB;IAG7C;;;;;;OAMG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAsBvF;;;;;;OAMG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcjD;;;;;;;OAOG;YACW,UAAU;IAwCxB;;;;;;;;;;;;;;;;OAgBG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GAAG,IAAI;IAC5B,+FAA+F;IAC/F,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GACjD,OAAO,CAAC,IAAI,CAAC;IAiFhB;;;;;;;;;;;;OAYG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM;IAChB,iGAAiG;IACjG,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GACjD,OAAO,CAAC,IAAI,CAAC;IAoChB,yFAAyF;YAC3E,SAAS;IAOvB;;;;OAIG;YACW,cAAc;CAiB7B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG;IAC7D,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CA8BA;AAED,kGAAkG;AAClG,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM;CAQ7B"}

package/dist/features/scope/scope-closure.service.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeHasChildrenError = exports.ScopeClosureService = void 0;
+exports.quarantineCycles = quarantineCycles;
 // astram-framework/packages/identity/src/features/scope/scope-closure.service.ts
 /**
  * `ScopeClosureService` — the LIVE, I/O half of Task 1.2 (Phase 1 of the scoped-hierarchy
@@ -20,6 +21,12 @@ exports.NodeHasChildrenError = exports.ScopeClosureService = void 0;
  *     the moved subtree so active sessions re-derive their (now-changed) subtree WITHOUT re-login
  *     (ADR-0011). A failed rebuild rolls the whole move back — atomic.
  *
+ *   • `attachNode(node)` — a node was just created: rebuild + bump its ancestors (security
+ *     hardening D5), so the creator's subtree includes it without waiting for the hourly reconcile.
+ *
+ *   Callers: `CompanyHierarchyService` (move / delete / attach, with an in-transaction audit hook)
+ *   and the boot/hourly reconcile. A generic company patch can no longer move a node (ADR-0034).
+ *
  *   • `deleteNode(node)` — remove a node (E-2), FAIL-CLOSED: it DENIES (throws) if the node has
  *     children, never letting the DB's old `ON DELETE SET NULL` silently promote a sub-org to a
  *     root (a hierarchy-boundary violation). The `...016` migration also flips the FK to
@@ -31,11 +38,16 @@ exports.NodeHasChildrenError = exports.ScopeClosureService = void 0;
  * invalidation. All SQL values are `?`-bound (never interpolated). `companies` lives in
  * `shield_app`; `scope_closure` lives in `shield_authz` — the shared authz pool reaches both.
  */
+const core_1 = require("@astram/core");
 const guard_1 = require("@astram/guard");
 /** Schema the node tree (`companies`) lives in. */
 const APP = 'shield_app';
 /** Schema the closure table lives in (ADR-0011 / Task 1.1). */
 const AUTHZ = 'shield_authz';
+/** The named lock every hierarchy writer holds (security review F3). */
+const TREE_LOCK = 'shield_scope_closure';
+/** Seconds to wait for it before failing closed. */
+const TREE_LOCK_TIMEOUT_S = 10;
 class ScopeClosureService {
     pool;
     bumper;
@@ -46,27 +58,99 @@ class ScopeClosureService {
     /**
      * Rebuild `scope_closure` from the current `companies.c_parent_uuid` edges. Idempotent
      * (delete-then-insert in a tx → a second run over the same tree writes the identical set).
-     * FAIL-LOUD: an orphaned/cyclic/too-deep edge makes `buildClosureRows` throw and that
-     * propagates (the tx rolls back — never a partial closure). Returns a small summary + logs.
+     * A CYCLIC component is quarantined (no rows for it; logged loudly) so the rest of the forest
+     * still reconciles. FAIL-LOUD for the rest: an orphaned/too-deep edge makes `buildClosureRows`
+     * throw and that propagates (the tx rolls back — never a partial closure). Returns a summary.
      */
     async reconcileClosure() {
-        const edges = await this.readEdges(this.pool);
-        const rows = (0, guard_1.buildClosureRows)(edges); // throws on cycle/depth/orphan — propagate (fail-loud).
+        // Security hardening #2: a cyclic component (and everything hanging under it) is QUARANTINED —
+        // left out of the closure, so its nodes get no rows (their admins fall back to the self node,
+        // non-widening) — instead of one corrupt component aborting the rebuild for EVERY tenant.
+        // Other corruption (orphan / too deep) still throws and propagates (fail-loud).
+        const { clean, quarantined, rows } = await this.inTreeLock(async (conn) => {
+            const split = quarantineCycles(await this.readEdges(conn));
+            const built = (0, guard_1.buildClosureRows)(split.clean);
+            await this.rewriteClosure(conn, built);
+            return { ...split, rows: built };
+        });
+        if (quarantined.length > 0) {
+            console.error(`[scope] closure: QUARANTINED ${quarantined.length} node(s) in or under a parent cycle — ` +
+                `they have no closure rows until the cycle is repaired`);
+        }
+        console.log(`[scope] closure: ${clean.length} nodes, ${rows.length} rows`);
+        return { nodes: clean.length, rows: rows.length, quarantined: quarantined.length };
+    }
+    /**
+     * A node was just CREATED (security hardening D5): rebuild the closure so it has rows at once
+     * (not at the next hourly reconcile), and bump every ANCESTOR's permission version — their
+     * reachable subtree just grew — so their sessions pick the new node up at the next refresh.
+     * One transaction; fail-loud like `moveNode` (a corrupt tree aborts the rebuild). A node inside
+     * a quarantined cycle gets no rows and bumps nothing.
+     */
+    async attachNode(nodeUuid) {
+        await this.inTreeLock(async (conn) => {
+            const { clean } = quarantineCycles(await this.readEdges(conn));
+            const rows = (0, guard_1.buildClosureRows)(clean);
+            await this.rewriteClosure(conn, rows);
+            const ancestors = rows
+                .filter((r) => r.descendant === nodeUuid && r.ancestor !== nodeUuid)
+                .map((r) => r.ancestor);
+            for (const tenantUuid of new Set(ancestors)) {
+                await this.bumper.bumpForTenant(tenantUuid, conn);
+            }
+        });
+    }
+    /**
+     * Run `fn` in ONE transaction while holding the tree's named lock (security review F3). Every
+     * hierarchy writer (move, delete, attach, reconcile) takes the SAME `GET_LOCK` on its own
+     * connection BEFORE `BEGIN`, so they run one at a time and each transaction's first read sees
+     * every move committed before it. Without it, two concurrent moves each pass the cycle check
+     * against the other's pre-move tree and together form a cycle. A lock that cannot be taken in
+     * time fails closed (503, nothing written). The lock is released after commit/rollback.
+     */
+    async inTreeLock(fn) {
         const conn = await this.pool.getConnection();
+        let locked = false;
         try {
+            const got = (await conn.query('SELECT GET_LOCK(?, ?) AS got', [
+                TREE_LOCK,
+                TREE_LOCK_TIMEOUT_S,
+            ]));
+            if (!Array.isArray(got) || Number(got[0]?.got) !== 1) {
+                throw new core_1.AuthorizationUnavailableError('scope hierarchy is busy; try again');
+            }
+            locked = true;
             await conn.beginTransaction();
-            await this.rewriteClosure(conn, rows);
-            await conn.commit();
-        }
-        catch (cause) {
-            await conn.rollback();
-            throw cause;
+            let out;
+            try {
+                out = await fn(conn);
+                await conn.commit();
+            }
+            catch (cause) {
+                await conn.rollback();
+                this.bumper.discardPending?.(conn);
+                throw cause;
+            }
+            // ADR-0035: the committed version bumps reach Redis (best-effort; never fails the write).
+            await this.bumper.publishCommitted?.(conn);
+            return out;
         }
         finally {
-            await conn.release();
+            let releasedLock = !locked;
+            if (locked) {
+                try {
+                    await conn.query('SELECT RELEASE_LOCK(?)', [TREE_LOCK]);
+                    releasedLock = true;
+                }
+                catch {
+                    // handled below: a pooled session that may still hold the lock is destroyed, not reused
+                }
+            }
+            if (!releasedLock && typeof conn.destroy === 'function')
+                conn.destroy();
+            else
+                await conn.release();
         }
-        console.log(`[scope] closure: ${edges.length} nodes, ${rows.length} rows`);
-        return { nodes: edges.length, rows: rows.length };
     }
     /**
      * Re-parent `nodeUuid` under `newParentUuid` (or null for a root). Cycle-checked FIRST via the
@@ -85,62 +169,74 @@ class ScopeClosureService {
      * HIGH stale-subtree-after-move leak: a parent admin kept reaching a moved-away tenant.
      * Nodes on neither side keep their exact set and are not bumped.
      */
-    async moveNode(nodeUuid, newParentUuid) {
+    async moveNode(nodeUuid, newParentUuid, 
+    /** Runs on the move's transaction after the bump (e.g. the audit row) — a throw rolls back. */
+    inTransaction) {
         if (newParentUuid === nodeUuid) {
             // A node cannot be its own parent (a trivial 1-cycle).
             throw new guard_1.ScopeCycleError(nodeUuid);
         }
-        if (newParentUuid !== null) {
-            // Cycle guard: the new parent must NOT be at/under the moved node. A closure hit means
-            // newParent is a descendant of node → re-parenting node under it would form a cycle.
-            const cyclic = (await this.pool.query(`SELECT 1 FROM \`${AUTHZ}\`.\`scope_closure\`
+        // Review F3: every read below runs INSIDE the tree lock + transaction, so a concurrent move
+        // that committed first is visible to the cycle check (two moves can no longer each pass the
+        // check against the other's pre-move tree).
+        await this.inTreeLock(async (conn) => {
+            if (newParentUuid !== null) {
+                // Cycle guard: the new parent must NOT be at/under the moved node. A closure hit means
+                // newParent is a descendant of node → re-parenting node under it would form a cycle.
+                const cyclic = (await conn.query(`SELECT 1 FROM \`${AUTHZ}\`.\`scope_closure\`
           WHERE ancestor_uuid = ? AND descendant_uuid = ? LIMIT 1`, [nodeUuid, newParentUuid]));
-            if (cyclic.length > 0) {
-                throw new guard_1.ScopeCycleError(nodeUuid);
+                if (cyclic.length > 0) {
+                    throw new guard_1.ScopeCycleError(nodeUuid);
+                }
             }
-        }
-        // The moved subtree — the nodes whose ancestry changes (node + all descendants). Read
-        // BEFORE the update (the move doesn't change the subtree's internal membership).
-        const subtreeRows = (await this.pool.query(`SELECT descendant_uuid FROM \`${AUTHZ}\`.\`scope_closure\` WHERE ancestor_uuid = ?`, [nodeUuid]));
-        // The FORMER-PARENT ANCESTRY — the nodes ABOVE `node` in the OLD tree (its ancestors,
-        // excluding self). They just LOST `node`'s subtree from their reach, so their admins' cached
-        // session subtrees are now stale (they'd otherwise keep reaching the moved-away tenant — the
-        // HIGH stale-subtree-after-move leak). Read BEFORE the update (the pre-move closure has the
-        // old ancestry). Bump these too so those sessions re-derive their (now-smaller) subtree at
-        // their next refresh (ADR-0011 bound — no forced re-login).
-        const formerAncestryRows = (await this.pool.query(`SELECT ancestor_uuid FROM \`${AUTHZ}\`.\`scope_closure\`
+            // The moved subtree — the nodes whose ancestry changes (node + all descendants). Read
+            // BEFORE the update (the move doesn't change the subtree's internal membership).
+            const subtreeRows = (await conn.query(`SELECT descendant_uuid FROM \`${AUTHZ}\`.\`scope_closure\` WHERE ancestor_uuid = ?`, [nodeUuid]));
+            // The FORMER-PARENT ANCESTRY — the nodes ABOVE `node` in the OLD tree (its ancestors,
+            // excluding self). They just LOST `node`'s subtree from their reach, so their admins' cached
+            // session subtrees are now stale (they'd otherwise keep reaching the moved-away tenant — the
+            // HIGH stale-subtree-after-move leak). Read BEFORE the update (the pre-move closure has the
+            // old ancestry). Bump these too so those sessions re-derive their (now-smaller) subtree at
+            // their next refresh (ADR-0011 bound — no forced re-login).
+            const formerAncestryRows = (await conn.query(`SELECT ancestor_uuid FROM \`${AUTHZ}\`.\`scope_closure\`
         WHERE descendant_uuid = ? AND ancestor_uuid <> ?`, [nodeUuid, nodeUuid]));
-        // Fall back to the node itself if the closure has no self-row yet (pre-first-reconcile).
-        const movedSubtree = subtreeRows.length > 0 ? subtreeRows.map((r) => r.descendant_uuid) : [nodeUuid];
-        // The full bump set: the moved subtree (their ancestry grew/changed) UNION the former-parent
-        // ancestry (they lost the moved subtree). Deduped.
-        const affected = [
-            ...new Set([...movedSubtree, ...formerAncestryRows.map((r) => r.ancestor_uuid)]),
-        ];
-        const conn = await this.pool.getConnection();
-        try {
-            await conn.beginTransaction();
-            // 1) Re-parent the edge.
-            await conn.query(`UPDATE \`${APP}\`.\`companies\` SET c_parent_uuid = ? WHERE c_uuid = ?`, [newParentUuid, nodeUuid]);
-            // 2) Rebuild the whole closure from the now-updated edges (full rebuild — safe + simple;
-            //    a targeted subtree rebuild is a later optimization). Re-reads edges over the SAME tx
-            //    connection so it sees the UPDATE. Fail-loud propagates → the whole move rolls back.
-            const edges = await this.readEdges(conn);
-            const rows = (0, guard_1.buildClosureRows)(edges);
-            await this.rewriteClosure(conn, rows);
-            // 3) Session invalidation: bump each moved-subtree tenant so its cached subtree re-derives.
-            for (const tenantUuid of affected) {
-                await this.bumper.bumpForTenant(tenantUuid, conn);
+            // Fall back to the node itself if the closure has no self-row yet (pre-first-reconcile).
+            const movedSubtree = subtreeRows.length > 0 ? subtreeRows.map((r) => r.descendant_uuid) : [nodeUuid];
+            // The full bump set: the moved subtree (their ancestry grew/changed) UNION the former-parent
+            // ancestry (they lost the moved subtree). Deduped.
+            const affected = [
+                ...new Set([...movedSubtree, ...formerAncestryRows.map((r) => r.ancestor_uuid)]),
+            ];
+            {
+                // 1) Re-parent the edge.
+                await conn.query(`UPDATE \`${APP}\`.\`companies\` SET c_parent_uuid = ? WHERE c_uuid = ?`, [
+                    newParentUuid,
+                    nodeUuid,
+                ]);
+                // 2) Rebuild the whole closure from the now-updated edges (full rebuild — safe + simple;
+                //    a targeted subtree rebuild is a later optimization). Re-reads edges over the SAME tx
+                //    connection so it sees the UPDATE. Fail-loud propagates → the whole move rolls back.
+                //    A pre-existing cycle elsewhere is quarantined (not this move's problem); but if THIS
+                //    node lands in a cycle (the closure pre-check can miss one through quarantined nodes,
+                //    which have no closure rows), refuse and roll back.
+                const { clean, quarantined } = quarantineCycles(await this.readEdges(conn));
+                if (quarantined.includes(nodeUuid))
+                    throw new guard_1.ScopeCycleError(nodeUuid);
+                const rows = (0, guard_1.buildClosureRows)(clean);
+                await this.rewriteClosure(conn, rows);
+                // 3) Session invalidation: bump each moved-subtree tenant so its cached subtree re-derives.
+                //    The NEW ancestry gained the subtree too: bump it so its sessions see the move.
+                const newAncestry = rows
+                    .filter((r) => r.descendant === nodeUuid && r.ancestor !== nodeUuid)
+                    .map((r) => r.ancestor);
+                for (const tenantUuid of new Set([...affected, ...newAncestry])) {
+                    await this.bumper.bumpForTenant(tenantUuid, conn);
+                }
+                // 4) Caller hook on the SAME transaction (audit) — a throw rolls the whole move back.
+                if (inTransaction)
+                    await inTransaction(conn);
             }
-            await conn.commit();
-        }
-        catch (cause) {
-            await conn.rollback();
-            throw cause;
-        }
-        finally {
-            await conn.release();
-        }
+        });
     }
     /**
      * Delete `nodeUuid`, FAIL-CLOSED. Refuses (throws) if the node has ANY child company — never
@@ -155,18 +251,20 @@ class ScopeClosureService {
      * the many tenant-scoped app tables that reference the deleted node) is out of scope for v1 and
      * is tracked as a follow-up; deleteNode v1 only guarantees the HIERARCHY stays consistent.
      */
-    async deleteNode(nodeUuid) {
-        const children = (await this.pool.query(`SELECT 1 FROM \`${APP}\`.\`companies\` WHERE c_parent_uuid = ? LIMIT 1`, [nodeUuid]));
-        if (children.length > 0) {
-            throw new NodeHasChildrenError(nodeUuid);
-        }
-        // The former-parent ancestry — the deleted node's ancestors (excluding self). They lose the
-        // node from their reach → bump so their sessions re-derive. Read BEFORE the delete.
-        const formerAncestryRows = (await this.pool.query(`SELECT ancestor_uuid FROM \`${AUTHZ}\`.\`scope_closure\`
-        WHERE descendant_uuid = ? AND ancestor_uuid <> ?`, [nodeUuid, nodeUuid]));
-        const conn = await this.pool.getConnection();
-        try {
-            await conn.beginTransaction();
+    async deleteNode(nodeUuid, 
+    /** Runs on the delete's transaction after the bump (e.g. the audit row) — a throw rolls back. */
+    inTransaction) {
+        // Under the tree lock (review F3): a concurrent move cannot hang a child under this node
+        // between the children check and the delete.
+        await this.inTreeLock(async (conn) => {
+            const children = (await conn.query(`SELECT 1 FROM \`${APP}\`.\`companies\` WHERE c_parent_uuid = ? LIMIT 1`, [nodeUuid]));
+            if (children.length > 0) {
+                throw new NodeHasChildrenError(nodeUuid);
+            }
+            // The former-parent ancestry — the deleted node's ancestors (excluding self). They lose the
+            // node from their reach → bump so their sessions re-derive. Read BEFORE the delete.
+            const formerAncestryRows = (await conn.query(`SELECT ancestor_uuid FROM \`${AUTHZ}\`.\`scope_closure\`
+          WHERE descendant_uuid = ? AND ancestor_uuid <> ?`, [nodeUuid, nodeUuid]));
             // Remove the node's closure rows (self-row + any it appears in as ancestor/descendant).
             await conn.query(`DELETE FROM \`${AUTHZ}\`.\`scope_closure\`
           WHERE ancestor_uuid = ? OR descendant_uuid = ?`, [nodeUuid, nodeUuid]);
@@ -176,15 +274,9 @@ class ScopeClosureService {
             for (const { ancestor_uuid } of formerAncestryRows) {
                 await this.bumper.bumpForTenant(ancestor_uuid, conn);
             }
-            await conn.commit();
-        }
-        catch (cause) {
-            await conn.rollback();
-            throw cause;
-        }
-        finally {
-            await conn.release();
-        }
+            if (inTransaction)
+                await inTransaction(conn);
+        });
     }
     /** Read the node forest's parent edges (`c_uuid` → `c_parent_uuid`) as `ScopeEdge[]`. */
     async readEdges(q) {
@@ -210,6 +302,47 @@ class ScopeClosureService {
     }
 }
 exports.ScopeClosureService = ScopeClosureService;
+/**
+ * Split the edge set into the CLEAN part and the nodes QUARANTINED because their parent chain
+ * reaches a cycle (the cycle's members and everything below them). PURE. Orphans and depth are
+ * left to `buildClosureRows` (still fail-loud): only a cycle is quarantined, because a cycle is
+ * the corruption a tenant admin could once create through the generic company patch (#2).
+ */
+function quarantineCycles(edges) {
+    const parentOf = new Map();
+    for (const e of edges)
+        parentOf.set(e.node, e.parent);
+    const state = new Map();
+    for (const e of edges) {
+        if (state.has(e.node))
+            continue;
+        const path = [];
+        const onPath = new Set();
+        let current = e.node;
+        let verdict = 'ok';
+        for (;;) {
+            if (current === null || current === undefined || !parentOf.has(current))
+                break; // root / orphan
+            const known = state.get(current);
+            if (known !== undefined) {
+                verdict = known;
+                break;
+            }
+            if (onPath.has(current)) {
+                verdict = 'bad'; // revisited a node on this walk → a cycle
+                break;
+            }
+            onPath.add(current);
+            path.push(current);
+            current = parentOf.get(current);
+        }
+        for (const n of path)
+            state.set(n, verdict);
+    }
+    const quarantined = edges.filter((e) => state.get(e.node) === 'bad').map((e) => e.node);
+    const bad = new Set(quarantined);
+    return { clean: edges.filter((e) => !bad.has(e.node)), quarantined };
+}
 /** deleteNode fail-closed guard: the node still has child companies (re-parent/cascade first). */
 class NodeHasChildrenError extends Error {
     constructor(nodeUuid) {

package/dist/features/service-account/service-account.controller.d.ts

@@ -0,0 +1,63 @@
+import type { Principal } from '@astram/core';
+import { ServiceAccountService } from './service-account.service.js';
+/** The request shape after the enforcement guard attaches the resolved principal. */
+interface AuthedRequest {
+    principal: Principal;
+}
+export declare class ServiceAccountController {
+    private readonly svc;
+    constructor(svc: ServiceAccountService);
+    /** List the caller's own-tenant service accounts (by label). Gated `service_account:read`. */
+    list(req: AuthedRequest): Promise<{
+        accounts: import("./service-account.service.js").ServiceAccountView[];
+    }>;
+    /**
+     * What the caller may grant an agent — the create/edit picker source (Phase 4). Gated
+     * `service_account:create` (only someone who can create agents needs the list). Computed from the
+     * SAME ceiling the create/update write check enforces: `{ roles: [{id,name}], scopeNodes:
+     * [{id,name,parentId|null}] }`. ⚠ Declared BEFORE `service-accounts/:id` so the static path wins.
+     */
+    assignable(req: AuthedRequest): Promise<import("./service-account.service.js").AssignableAccess>;
+    /** Fetch one own-tenant account. Gated `service_account:read`. Cross-tenant/unknown → 404. */
+    get(req: AuthedRequest, id: string): Promise<{
+        account: import("./service-account.service.js").ServiceAccountView;
+    }>;
+    /**
+     * Create an account in the caller's own tenant. Gated `service_account:create`.
+     * Body: `{ label, scopeSubtreeNodeIds?, roleIds? }`. Scope/roles must pass the ADR-0029 ceiling.
+     */
+    create(req: AuthedRequest, body: unknown): Promise<{
+        account: import("./service-account.service.js").ServiceAccountView;
+    }>;
+    /**
+     * Edit an account (label/scope/roles/status). Gated `service_account:update`. Own-tenant only;
+     * scope/roles re-checked against the ceiling (an edit cannot escalate).
+     */
+    update(req: AuthedRequest, id: string, body: unknown): Promise<{
+        account: import("./service-account.service.js").ServiceAccountView;
+    }>;
+    /**
+     * Issue a NEW key for an account. Gated `service_account:manage_keys`. Body: `{ expiresAtMs }`
+     * (a future epoch-ms) or `{ neverExpires: true }` — one of the two is required (400 otherwise).
+     * Returns the raw `ask_…` key EXACTLY ONCE — copy it now, it is never retrievable again.
+     */
+    issueKey(req: AuthedRequest, id: string, body: unknown): Promise<{
+        key: import("./service-account.service.js").IssuedKey;
+    }>;
+    /**
+     * Rotate an account's key. Gated `service_account:manage_keys`. The previous key stops
+     * authenticating; the new raw key is returned EXACTLY ONCE. Same expiry rule as issue.
+     */
+    rotateKey(req: AuthedRequest, id: string, body: unknown): Promise<{
+        key: import("./service-account.service.js").IssuedKey;
+    }>;
+    /**
+     * Revoke ALL of an account's keys. Gated `service_account:manage_keys`. Fail-closed on the next
+     * request; idempotent.
+     */
+    revokeKeys(req: AuthedRequest, id: string): Promise<{
+        success: boolean;
+    }>;
+}
+export {};
+//# sourceMappingURL=service-account.controller.d.ts.map

package/dist/features/service-account/service-account.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-account.controller.d.ts","sourceRoot":"","sources":["../../../src/features/service-account/service-account.controller.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EACL,qBAAqB,EAOtB,MAAM,8BAA8B,CAAC;AAGtC,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAwDD,qBAEa,wBAAwB;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,qBAAqB;IAEvD,8FAA8F;IAGxF,IAAI,CAAQ,GAAG,EAAE,aAAa;;;IAQpC;;;;;OAKG;IAGG,UAAU,CAAQ,GAAG,EAAE,aAAa;IAQ1C,8FAA8F;IAGxF,GAAG,CAAQ,GAAG,EAAE,aAAa,EAAe,EAAE,EAAE,MAAM;;;IAQ5D;;;OAGG;IAGG,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE,OAAO;;;IAiB7D;;;OAGG;IAGG,MAAM,CAAQ,GAAG,EAAE,aAAa,EAAe,EAAE,EAAE,MAAM,EAAU,IAAI,EAAE,OAAO;;;IAuBtF;;;;OAIG;IAGG,QAAQ,CAAQ,GAAG,EAAE,aAAa,EAAe,EAAE,EAAE,MAAM,EAAU,IAAI,EAAE,OAAO;;;IAUxF;;;OAGG;IAGG,SAAS,CAAQ,GAAG,EAAE,aAAa,EAAe,EAAE,EAAE,MAAM,EAAU,IAAI,EAAE,OAAO;;;IAUzF;;;OAGG;IAGG,UAAU,CAAQ,GAAG,EAAE,aAAa,EAAe,EAAE,EAAE,MAAM;;;CAQpE"}