@astram/identity 0.2.0 → 0.3.0

package/dist/features/policy/policy.service.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyService = exports.PolicyNotFoundError = exports.PolicyAuthorDeniedError = exports.InvalidPolicyError = void 0;
+exports.validOperatorsForFieldType = validOperatorsForFieldType;
+const core_1 = require("@astram/core");
+/** A guided policy could not be authored because it is structurally invalid (→ 400). */
+class InvalidPolicyError extends Error {
+    constructor(message = 'The policy is invalid.') {
+        super(message);
+        this.name = 'InvalidPolicyError';
+    }
+}
+exports.InvalidPolicyError = InvalidPolicyError;
+/** The acting admin exceeds their authority (delegated-admin ceiling) — author denied (→ 403). */
+class PolicyAuthorDeniedError extends Error {
+    constructor(message = 'You may not author this policy.') {
+        super(message);
+        this.name = 'PolicyAuthorDeniedError';
+    }
+}
+exports.PolicyAuthorDeniedError = PolicyAuthorDeniedError;
+/** A policy id was not found in the acting admin's tenant (absent OR another tenant's) (→ 404). */
+class PolicyNotFoundError extends Error {
+    constructor(message = 'Policy not found.') {
+        super(message);
+        this.name = 'PolicyNotFoundError';
+    }
+}
+exports.PolicyNotFoundError = PolicyNotFoundError;
+// Operator families, mirroring core's validator (policies.ts) narrowed for GUIDED-BUILDER UX.
+// The server's `validateGuidedPolicy` remains the authority; this is what the builder OFFERS.
+const NULLARY = ['is_null', 'is_not_null'];
+const ARRAY_OPS = ['in', 'not_in'];
+const RELATIONAL = ['gt', 'lt', 'gte', 'lte'];
+const TEXT = ['contains', 'not_contains'];
+const EQUALITY = ['eq', 'ne', 'in', 'not_in'];
+/**
+ * The operators the guided builder offers for a FIELD TYPE. Equality + null apply to every type;
+ * relational (gt/lt/…) only to numeric + timestamp (the recorded v1 limit — lexical vs numeric
+ * ordering on a VARCHAR diverges, so relational is NOT offered on string/uuid); text
+ * (contains/…) only to string. boolean/json get equality + null only. This is INTENTIONALLY a
+ * subset the builder shows; the server accepts anything `operatorValidForField` allows.
+ */
+function validOperatorsForFieldType(type) {
+    const base = [...EQUALITY, ...NULLARY];
+    switch (type) {
+        case 'number':
+        case 'timestamp':
+            return [...base, ...RELATIONAL];
+        case 'string':
+            return [...base, ...TEXT];
+        case 'boolean':
+            // No membership on a boolean (in/not_in over true/false is pointless) → eq/ne + null.
+            return ['eq', 'ne', ...NULLARY];
+        case 'json':
+        case 'uuid':
+        default:
+            return base;
+    }
+}
+class PolicyService {
+    store;
+    authorPolicy;
+    schemaByType;
+    constructor(deps) {
+        this.store = deps.policyStore;
+        this.schemaByType = new Map((deps.schemaSource ?? []).map((s) => [s.typeKey, s]));
+        this.authorPolicy = (0, core_1.makeAuthorPolicy)({
+            registry: deps.registry,
+            // makeAuthorPolicy's PolicyStore only needs savePolicy; the concrete store satisfies it.
+            policyStore: deps.policyStore,
+            decide: deps.decide,
+            audit: deps.audit,
+            ...(deps.now !== undefined ? { now: deps.now } : {}),
+        });
+    }
+    /**
+     * The guided-builder SCHEMA for a type: its authorable fields (each with its type + the
+     * operators the builder offers, split into array/nullary families the UI renders differently)
+     * + the type's actions. Server-derived from the registered object type so the builder's
+     * dropdowns are ONE source of truth with enforcement (no client-side operator table to drift).
+     * A type not in the schema source → PolicyNotFoundError (not authorable via the builder).
+     */
+    schema(typeKey) {
+        const src = this.schemaByType.get(typeKey);
+        if (src === undefined) {
+            throw new PolicyNotFoundError(`No authorable schema for type '${typeKey}'.`);
+        }
+        const fields = src.fields.map((f) => {
+            const valid = validOperatorsForFieldType(f.type);
+            return {
+                key: f.key,
+                label: f.key,
+                type: f.type,
+                validOperators: valid,
+                arrayOperators: valid.filter((o) => ARRAY_OPS.includes(o)),
+                nullaryOperators: valid.filter((o) => NULLARY.includes(o)),
+            };
+        });
+        return { typeKey: src.typeKey, label: src.label, actions: src.actions, fields };
+    }
+    /**
+     * Author a guided policy in the acting admin's OWN tenant. The target tenant is
+     * `actor.tenantId` — a `tenantId` in the body is IGNORED (cross-tenant author impossible).
+     * Runs the core pipeline (delegated-admin ceiling → validate → write → audit). Maps deny
+     * reasons to typed errors; a transient throw PROPAGATES (→ 503).
+     */
+    async author(actor, policy) {
+        const mutation = {
+            kind: 'author_policy',
+            admin: actor,
+            targetTenantId: actor.tenantId, // SERVER-resolved — never the body
+        };
+        const result = await this.authorPolicy(mutation, policy);
+        if (result.ok === true) {
+            return result.value;
+        }
+        // Map the core deny reason → a typed error. `invalid_policy` is a 400; every authority /
+        // delegation deny is a 403 (a non-root admin exceeding what they hold, or a plain deny).
+        if (result.reason === 'invalid_policy') {
+            throw new InvalidPolicyError();
+        }
+        throw new PolicyAuthorDeniedError(`Policy author denied: ${result.reason}.`);
+    }
+    /** List the policies governing `typeKey` in the acting admin's tenant (tenant-scoped read). */
+    async list(actor, typeKey) {
+        return this.store.listPolicies(typeKey, actor.tenantId);
+    }
+    /**
+     * Delete a policy the acting admin owns. TENANT-SCOPED: `deletePolicyForTenant` removes rows
+     * only when they belong to `actor.tenantId`, so a foreign tenant's policy id can never be
+     * deleted. Zero rows removed ⇒ the policy is absent OR another tenant's ⇒ NotFound (never a
+     * false "deleted someone else's").
+     */
+    async delete(actor, policyId) {
+        const removed = await this.store.deletePolicyForTenant(policyId, actor.tenantId);
+        if (removed === 0) {
+            throw new PolicyNotFoundError();
+        }
+    }
+}
+exports.PolicyService = PolicyService;

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

@@ -0,0 +1,82 @@
+/**
+ * The minimal query surface a transaction connection must expose. A `mariadb`
+ * `PoolConnection` satisfies it structurally; kept framework-agnostic (mirrors `Queryable`
+ * in `permission-version.bumper.ts`) so this signature doesn't force `mariadb` on callers.
+ */
+export interface ScopeConn {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/** The pool surface this service needs: `query` for reads + `getConnection` for transactions. */
+export interface ScopePool {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+    getConnection(): Promise<ScopeConn & {
+        beginTransaction(): Promise<void>;
+        commit(): Promise<void>;
+        rollback(): Promise<void>;
+        release(): Promise<void>;
+    }>;
+}
+/** The version-bump surface moveNode needs — satisfied by `PermissionVersionBumper`. */
+export interface ScopeVersionBumper {
+    bumpForTenant(tenantUuid: string, conn: ScopeConn): Promise<void>;
+}
+export declare class ScopeClosureService {
+    private readonly pool;
+    private readonly bumper;
+    constructor(pool: ScopePool, bumper: ScopeVersionBumper);
+    /**
+     * 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.
+     */
+    reconcileClosure(): Promise<{
+        nodes: number;
+        rows: number;
+    }>;
+    /**
+     * 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`
+     * and touch NOTHING. Otherwise, atomically: UPDATE the edge, rebuild the closure, and bump the
+     * permission version of the MOVED SUBTREE's tenants.
+     *
+     * WHICH NODES ARE BUMPED — BOTH sides of the cut, read from the closure BEFORE the update:
+     *   (a) the moved node + every descendant (its subtree) — their ancestry changed; AND
+     *   (b) the FORMER-PARENT ANCESTRY (`node`'s old ancestors, excluding self) — they LOST the
+     *       moved subtree from their reach.
+     * Rationale: a re-parent changes the reachable set of BOTH the moved subtree (new ancestry)
+     * and the losing parents (they can no longer reach the moved-away tenant). BOTH sides' admins
+     * have stale cached session subtrees; bumping each forces those tenants to re-derive their
+     * subtree at their NEXT REFRESH (ADR-0011 bound — no forced re-login). Missing (b) was the
+     * 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>;
+    /**
+     * 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
+     * explicit check gives a clear early error). A leaf is deleted with its closure rows in one tx.
+     * BUMPS the FORMER-PARENT ANCESTRY: deleting a leaf removes it from its parents' reachable
+     * subtree, so those admins' cached session subtrees are stale (they'd keep the deleted node in
+     * their set) — bump them so they re-derive at the next refresh (same discipline as moveNode's
+     * former-parent bump; without it, a parent admin's list/decide would reference a gone node).
+     *
+     * v1 SCOPE NOTE: this refuses a node with CHILDREN. Broader resource-orphan cleanup (rows in
+     * 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>;
+    /** Read the node forest's parent edges (`c_uuid` → `c_parent_uuid`) as `ScopeEdge[]`. */
+    private readEdges;
+    /**
+     * Replace the entire `scope_closure` with `rows` over a tx connection: DELETE-all then a
+     * single multi-row INSERT (all values `?`-bound). Delete-then-insert makes reconcile trivially
+     * idempotent (a re-run writes the identical target set) and correct for a full rebuild.
+     */
+    private rewriteClosure;
+}
+/** deleteNode fail-closed guard: the node still has child companies (re-parent/cascade first). */
+export declare class NodeHasChildrenError extends Error {
+    constructor(nodeUuid: string);
+}
+//# sourceMappingURL=scope-closure.service.d.ts.map

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

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

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

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeHasChildrenError = exports.ScopeClosureService = void 0;
+// 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
+ * tenancy program, ADR-0027). Task 1.1 shipped the `shield_authz.scope_closure` table and the
+ * PURE `buildClosureRows` (guard); THIS service makes the closure live against the real node
+ * tree (`shield_app.companies`, parent edge `c_parent_uuid`):
+ *
+ *   • `reconcileClosure()` — (re)build the whole closure from the current parent edges. Runs at
+ *     boot (mirroring the catalog reconcile) and on demand, so the closure is always consistent
+ *     with the tree. Idempotent (delete-then-insert in ONE tx → a second run yields the identical
+ *     row set) and FAIL-LOUD: an orphaned parent ref makes the pure builder throw, and that
+ *     throw PROPAGATES (never a silent skip — a mis-scoped closure is a tenant-isolation bug).
+ *
+ *   • `moveNode(node, newParent)` — re-parent a node (E-1). Validates NO cycle FIRST (the new
+ *     parent must not sit inside the moved node's own subtree), then, in ONE transaction:
+ *     UPDATE the edge, rebuild the closure, and BUMP the permission version of every tenant in
+ *     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.
+ *
+ *   • `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
+ *     RESTRICT so the DB refuses too; this service checks explicitly for a clear, early error.
+ *     A leaf (no children) is deleted with its closure rows in one tx.
+ *
+ * Reuse (Task 1.1 / Phase 3): the pure `buildClosureRows` + the `Scope*Error` classes from
+ * `@astram/guard`, and `PermissionVersionBumper.bumpForTenant` for moveNode's session
+ * 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 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';
+class ScopeClosureService {
+    pool;
+    bumper;
+    constructor(pool, bumper) {
+        this.pool = pool;
+        this.bumper = bumper;
+    }
+    /**
+     * 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.
+     */
+    async reconcileClosure() {
+        const edges = await this.readEdges(this.pool);
+        const rows = (0, guard_1.buildClosureRows)(edges); // throws on cycle/depth/orphan — propagate (fail-loud).
+        const conn = await this.pool.getConnection();
+        try {
+            await conn.beginTransaction();
+            await this.rewriteClosure(conn, rows);
+            await conn.commit();
+        }
+        catch (cause) {
+            await conn.rollback();
+            throw cause;
+        }
+        finally {
+            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
+     * closure: if `newParentUuid` is already a descendant of `nodeUuid`, throw `ScopeCycleError`
+     * and touch NOTHING. Otherwise, atomically: UPDATE the edge, rebuild the closure, and bump the
+     * permission version of the MOVED SUBTREE's tenants.
+     *
+     * WHICH NODES ARE BUMPED — BOTH sides of the cut, read from the closure BEFORE the update:
+     *   (a) the moved node + every descendant (its subtree) — their ancestry changed; AND
+     *   (b) the FORMER-PARENT ANCESTRY (`node`'s old ancestors, excluding self) — they LOST the
+     *       moved subtree from their reach.
+     * Rationale: a re-parent changes the reachable set of BOTH the moved subtree (new ancestry)
+     * and the losing parents (they can no longer reach the moved-away tenant). BOTH sides' admins
+     * have stale cached session subtrees; bumping each forces those tenants to re-derive their
+     * subtree at their NEXT REFRESH (ADR-0011 bound — no forced re-login). Missing (b) was the
+     * 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) {
+        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\`
+          WHERE ancestor_uuid = ? AND descendant_uuid = ? LIMIT 1`, [nodeUuid, newParentUuid]));
+            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\`
+        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);
+            }
+            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
+     * silently orphans/promotes a sub-org (the `...016` FK RESTRICT enforces this at the DB too; the
+     * explicit check gives a clear early error). A leaf is deleted with its closure rows in one tx.
+     * BUMPS the FORMER-PARENT ANCESTRY: deleting a leaf removes it from its parents' reachable
+     * subtree, so those admins' cached session subtrees are stale (they'd keep the deleted node in
+     * their set) — bump them so they re-derive at the next refresh (same discipline as moveNode's
+     * former-parent bump; without it, a parent admin's list/decide would reference a gone node).
+     *
+     * v1 SCOPE NOTE: this refuses a node with CHILDREN. Broader resource-orphan cleanup (rows in
+     * 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();
+            // 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]);
+            // Remove the company row itself.
+            await conn.query(`DELETE FROM \`${APP}\`.\`companies\` WHERE c_uuid = ?`, [nodeUuid]);
+            // Bump the former-parent ancestry so their cached subtrees re-derive at next refresh.
+            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();
+        }
+    }
+    /** Read the node forest's parent edges (`c_uuid` → `c_parent_uuid`) as `ScopeEdge[]`. */
+    async readEdges(q) {
+        const rows = (await q.query(`SELECT c_uuid, c_parent_uuid FROM \`${APP}\`.\`companies\``));
+        return rows.map((r) => ({ node: r.c_uuid, parent: r.c_parent_uuid ?? null }));
+    }
+    /**
+     * Replace the entire `scope_closure` with `rows` over a tx connection: DELETE-all then a
+     * single multi-row INSERT (all values `?`-bound). Delete-then-insert makes reconcile trivially
+     * idempotent (a re-run writes the identical target set) and correct for a full rebuild.
+     */
+    async rewriteClosure(conn, rows) {
+        await conn.query(`DELETE FROM \`${AUTHZ}\`.\`scope_closure\``);
+        if (rows.length === 0)
+            return;
+        const placeholders = rows.map(() => '(?, ?, ?)').join(', ');
+        const params = [];
+        for (const r of rows) {
+            params.push(r.ancestor, r.descendant, r.depth);
+        }
+        await conn.query(`INSERT INTO \`${AUTHZ}\`.\`scope_closure\` (ancestor_uuid, descendant_uuid, depth)
+         VALUES ${placeholders}`, params);
+    }
+}
+exports.ScopeClosureService = ScopeClosureService;
+/** deleteNode fail-closed guard: the node still has child companies (re-parent/cascade first). */
+class NodeHasChildrenError extends Error {
+    constructor(nodeUuid) {
+        super(`scope: refusing to delete node '${nodeUuid}' — it still has child nodes. Re-parent or ` +
+            `delete its children first (fail-closed: a silent promote/orphan would break the ` +
+            `hierarchy boundary).`);
+        this.name = 'NodeHasChildrenError';
+    }
+}
+exports.NodeHasChildrenError = NodeHasChildrenError;

package/dist/features/scope/scope-subtree.resolver.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `DbScopeSubtreeResolver` — the identity-side implementation of the guard-defined
+ * `ScopeSubtreeResolver` port (Task 2.2 of the scoped-hierarchy tenancy program,
+ * ADR-0027 / ADR-0024). It answers ONE question at LOGIN time: given a principal's
+ * active scope node, what is the reachable subtree (that node + all its descendants)?
+ *
+ * The answer is a SINGLE closure read over `shield_authz.scope_closure` (built + kept
+ * live by {@link import('./scope-closure.service.js').ScopeClosureService}):
+ *
+ *     SELECT descendant_uuid FROM shield_authz.scope_closure WHERE ancestor_uuid = ?
+ *
+ * (the closure stores a self-row `(node, node, 0)`, so the node itself is included).
+ * The guard caches the returned set on the Redis session binding, so the per-request
+ * tenant gate reads it from the binding with ZERO extra DB — the closure query happens
+ * ONLY here, at login (the ADR-0024 parity guarantee).
+ *
+ * ── LAYERING ──────────────────────────────────────────────────────────────────────
+ * The PORT (`ScopeSubtreeResolver`) is defined in `@astram/guard`; this IMPLEMENTATION
+ * lives in `@astram/identity` (which owns the app/authz schemas + the closure). The
+ * consumer injects an instance through `ShieldModule.forRoot({ scopeSubtreeResolver })`
+ * — the same sanctioned direction as the record-tier adapters + the facts projector.
+ * Guard never imports identity.
+ *
+ * ── FAIL-SAFE (non-widening) ───────────────────────────────────────────────────────
+ * If the closure has NO rows for the node yet (a pre-first-reconcile boot), this returns
+ * `[nodeId]` — the self-node, exactly today's flat isolation. It NEVER widens the subtree
+ * on missing data. A store OUTAGE THROWS (the guard's login path swallows it best-effort
+ * → the binding omits the subtree → the per-request path still falls back to the
+ * self-node): a resolution failure degrades to today's correct, non-widening behavior and
+ * NEVER fails login.
+ *
+ * All SQL values are `?`-bound (never interpolated). `scope_closure` lives in
+ * `shield_authz`; the shared authz pool reaches it.
+ */
+import type { Pool } from 'mariadb';
+export declare class DbScopeSubtreeResolver {
+    private readonly pool;
+    constructor(pool: Pool);
+    /**
+     * Resolve the active-scope subtree for `nodeId` — the node itself plus every
+     * descendant — from `scope_closure`. Returns `[nodeId]` (self-node, non-widening)
+     * when the closure has no rows for the node yet (pre-first-reconcile). Throws on a
+     * store outage (the login path swallows it → self-node fallback per request).
+     */
+    resolveSubtree(nodeId: string): Promise<readonly string[]>;
+}
+//# sourceMappingURL=scope-subtree.resolver.d.ts.map

package/dist/features/scope/scope-subtree.resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-subtree.resolver.d.ts","sourceRoot":"","sources":["../../../src/features/scope/scope-subtree.resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAKpC,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;CAQjE"}

package/dist/features/scope/scope-subtree.resolver.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbScopeSubtreeResolver = void 0;
+/** Schema the closure table lives in (Task 1.1 / ADR-0011). */
+const AUTHZ = 'shield_authz';
+class DbScopeSubtreeResolver {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Resolve the active-scope subtree for `nodeId` — the node itself plus every
+     * descendant — from `scope_closure`. Returns `[nodeId]` (self-node, non-widening)
+     * when the closure has no rows for the node yet (pre-first-reconcile). Throws on a
+     * store outage (the login path swallows it → self-node fallback per request).
+     */
+    async resolveSubtree(nodeId) {
+        const rows = (await this.pool.query(`SELECT descendant_uuid FROM \`${AUTHZ}\`.\`scope_closure\` WHERE ancestor_uuid = ?`, [nodeId]));
+        if (rows.length === 0)
+            return [nodeId]; // pre-first-reconcile → self-node (non-widening).
+        return rows.map((r) => r.descendant_uuid);
+    }
+}
+exports.DbScopeSubtreeResolver = DbScopeSubtreeResolver;

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

@@ -0,0 +1,35 @@
+import type { Principal } from '@astram/core';
+import { ShareService } from './share.service.js';
+/** The request shape after the enforcement guard attaches the resolved principal. */
+interface AuthedRequest {
+    principal: Principal;
+}
+export declare class ShareController {
+    private readonly shares;
+    constructor(shares: ShareService);
+    /**
+     * List the shares on a record the caller owns — grantee NAMES resolved (no raw uuid).
+     * `GET /identity/record-shares?typeKey=&recordId=`. Gated `record_share:read`. Only the owner
+     * sees a record's shares (the writer's owner-bound); a non-owner → 403.
+     */
+    list(req: AuthedRequest, typeKey?: string, recordId?: string): Promise<{
+        shares: readonly import("./share.service.js").ShareView[];
+    }>;
+    /**
+     * Share a record the caller owns. `POST /identity/record-shares` with
+     * `{ typeKey, recordId, granteeKind, granteeUuid, action }`. Gated `record_share:share`. The
+     * writer proves the caller owns the record before writing (non-owner → 403).
+     */
+    share(req: AuthedRequest, body: unknown): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Revoke a share the caller owns. `DELETE /identity/record-shares` with the same body shape
+     * (the exact tuple to remove). Gated `record_share:share`. Owner-only (the writer enforces it).
+     */
+    unshare(req: AuthedRequest, body: unknown): Promise<{
+        success: boolean;
+    }>;
+}
+export {};
+//# sourceMappingURL=share.controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"share.controller.d.ts","sourceRoot":"","sources":["../../../src/features/share/share.controller.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAErE,qFAAqF;AACrF,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,CAAC;CACtB;AAqBD,qBACa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,YAAY;IAEjD;;;;OAIG;IAGG,IAAI,CACD,GAAG,EAAE,aAAa,EACP,OAAO,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM;;;IAYtC;;;;OAIG;IAGG,KAAK,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE,OAAO;;;IAW5D;;;OAGG;IAGG,OAAO,CAAQ,GAAG,EAAE,aAAa,EAAU,IAAI,EAAE,OAAO;;;CAU/D"}