@astram/guard 0.5.0 → 0.6.0

package/dist/scope/closure-builder.js

@@ -0,0 +1,134 @@
+"use strict";
+// astram-framework/packages/guard/src/scope/closure-builder.ts
+/**
+ * `buildClosureRows` — the PURE, data-foundation half of Task 1.1 (Phase 1 of the
+ * scoped-hierarchy tenancy program). Turns a node forest's parent edges into the flat
+ * ancestor/descendant/depth rows the `shield_authz.scope_closure` table stores, so any
+ * subtree query (`WHERE ancestor_uuid = N`) or ancestry query (`WHERE descendant_uuid = N`)
+ * is a flat, indexed lookup — NEVER a recursive walk on any request-serving query path.
+ *
+ * This module does NO I/O. The Task 1.2 reconciler is the one that calls this against real
+ * node edges (read from the DB) and writes the resulting rows back to `scope_closure`; this
+ * file only computes the correct row set from an in-memory edge list.
+ *
+ * ── SEMANTICS ───────────────────────────────────────────────────────────────────────────
+ *   • EVERY node gets a self-row `{ancestor: n, descendant: n, depth: 0}` — including a
+ *     root (parent === null) and including a node with NO children.
+ *   • For each node, walking UP its parent chain, every ancestor `a` at chain-distance `d`
+ *     (1-based: the immediate parent is depth 1, the grandparent depth 2, ...) emits
+ *     `{ancestor: a, descendant: n, depth: d}`.
+ *   • A FLAT set (every node's parent is `null`) therefore degenerates to SELF-ROWS ONLY —
+ *     this is the non-breaking case: a flat deployment (no hierarchy configured yet) is
+ *     just a depth-1 forest of roots, and every existing single-tenant scope check
+ *     (`ancestor_uuid = descendant_uuid = tenant`) continues to hold.
+ *   • A FOREST (multiple independent root trees) computes each branch independently — no
+ *     cross-tree rows are ever emitted.
+ *
+ * ── FAILURE MODES (all fail LOUD — a closure computed over bad data must never silently
+ *    produce a wrong, over- or under-scoped row set; that would be a tenant-isolation bug) ─
+ *   • CYCLE (a node reachable from itself via parent edges, direct `A→A` or indirect
+ *     `A→B→A`): throws {@link ScopeCycleError}. Detected by tracking the in-progress walk
+ *     set per node — if the walk revisits a node already on the CURRENT path, it's a cycle.
+ *   • DEPTH EXCEEDED (a parent chain longer than `opts.maxDepth`, default 32 — a sane bound
+ *     for any real org hierarchy): throws {@link ScopeDepthError}. Guards against a
+ *     pathological or malformed edge set turning this into an unbounded walk.
+ *   • UNKNOWN PARENT (a node's `parent` id doesn't reference any node in the SAME edge set):
+ *     throws a plain `Error` — an orphaned edge is a data error (e.g. the parent was deleted
+ *     without re-parenting children), never a silent skip that would misplace a subtree.
+ *   • Empty input → empty output (no throw) — the vacuous case.
+ *
+ * ── DETERMINISM: output order is not semantically meaningful (the caller writes rows to a
+ *    PK-indexed table), but rows are sorted (ancestor, then descendant, then depth) so tests
+ *    and diffs are stable.
+ *
+ * ── COMPLEXITY: O(nodes × depth) — for each node, one iterative (non-recursive) walk up its
+ *    parent chain, bounded by `maxDepth`. No recursion, so no call-stack depth risk either.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeUnknownParentError = exports.ScopeDepthError = exports.ScopeCycleError = void 0;
+exports.buildClosureRows = buildClosureRows;
+/** A node's parent chain revisits a node already on the walk — the edge set has a cycle. */
+class ScopeCycleError extends Error {
+    constructor(node) {
+        super(`scope-closure: cycle detected while walking ancestors of node '${node}' — a node's ` +
+            `parent chain reaches back to itself. The edge set is corrupt; refusing to compute ` +
+            `a closure over it (a cycle would make ancestor/descendant scoping meaningless).`);
+        this.name = 'ScopeCycleError';
+    }
+}
+exports.ScopeCycleError = ScopeCycleError;
+/** A node's parent chain exceeds the configured (or default) maximum depth. */
+class ScopeDepthError extends Error {
+    constructor(node, maxDepth) {
+        super(`scope-closure: node '${node}' has an ancestor chain deeper than the maximum allowed ` +
+            `depth (${maxDepth}). Refusing to compute a closure — either the hierarchy is ` +
+            `pathologically deep or the edge set is malformed (e.g. hides a cycle just past the ` +
+            `bound).`);
+        this.name = 'ScopeDepthError';
+    }
+}
+exports.ScopeDepthError = ScopeDepthError;
+/** A node's `parent` id does not reference any node present in the same edge set. */
+class ScopeUnknownParentError extends Error {
+    constructor(node, parent) {
+        super(`scope-closure: node '${node}' declares parent '${parent}', which is not present in ` +
+            `the supplied edge set. An orphaned edge is a data error (e.g. the parent was ` +
+            `removed without re-parenting its children) — refusing to silently drop it from ` +
+            `the hierarchy.`);
+        this.name = 'ScopeUnknownParentError';
+    }
+}
+exports.ScopeUnknownParentError = ScopeUnknownParentError;
+/** A sane default bound on ancestor-chain depth — comfortably beyond any real org hierarchy. */
+const DEFAULT_MAX_DEPTH = 32;
+/**
+ * Compute the transitive closure of a node forest from its parent edges.
+ * Pure — no I/O. See the file header for full semantics and failure modes.
+ */
+function buildClosureRows(edges, opts) {
+    const maxDepth = opts?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    // node -> parent id (or null for a root); also doubles as the "known nodes" set.
+    const parentOf = new Map();
+    for (const edge of edges) {
+        parentOf.set(edge.node, edge.parent);
+    }
+    const rows = [];
+    for (const edge of edges) {
+        const node = edge.node;
+        // Self-row — every node is its own ancestor at depth 0.
+        rows.push({ ancestor: node, descendant: node, depth: 0 });
+        // Walk UP the parent chain, guarding against cycles (revisiting a node already on
+        // THIS walk) and excessive depth. Iterative — no recursion, no call-stack risk.
+        const onThisWalk = new Set([node]);
+        let current = node;
+        let depth = 0;
+        for (;;) {
+            const parent = parentOf.get(current);
+            if (parent === undefined) {
+                // `current` isn't a known node itself only if it was referenced as a parent but
+                // never declared as a node — guard defensively even though `current` starts as
+                // `node` (always known) and only becomes a parent id below.
+                throw new ScopeUnknownParentError(node, current);
+            }
+            if (parent === null) {
+                break; // reached a root — done walking this node's ancestors.
+            }
+            if (!parentOf.has(parent)) {
+                throw new ScopeUnknownParentError(current, parent);
+            }
+            if (onThisWalk.has(parent)) {
+                throw new ScopeCycleError(node);
+            }
+            depth += 1;
+            if (depth > maxDepth) {
+                throw new ScopeDepthError(node, maxDepth);
+            }
+            rows.push({ ancestor: parent, descendant: node, depth });
+            onThisWalk.add(parent);
+            current = parent;
+        }
+    }
+    return rows.sort((a, b) => a.ancestor.localeCompare(b.ancestor) ||
+        a.descendant.localeCompare(b.descendant) ||
+        a.depth - b.depth);
+}

package/migrations/1710000000009-CreateRecordPermissionRule.cjs

@@ -0,0 +1,56 @@
+/**
+ * Framework authz migration — `shield_authz.record_permission_rule`: the framework-defined
+ * ADMIN record-rule table (List-Scoping Engine spec §5.1 / plan Task 0.1). One row = one
+ * admin-authored (or guided-builder-authored) rule that WIDENS — or explicitly DENIES,
+ * deny-wins — the framework-owned OWNER baseline for a record type.
+ *
+ *   • The OWNER baseline itself is NOT a row here — it is computed in @astram/core from
+ *     each object type's access declaration (owned/system/tenantScoped). This table holds
+ *     ONLY rules layered on top (e.g. "Company Admins read all inspection_reports"). There
+ *     is no owner/system subject_kind row.
+ *   • `rpr_policy_uuid` is a framework ADDITION beyond the ported astram3 table: it groups
+ *     the N AND-composed condition-rows of one guided policy under a single policy id (a
+ *     guided policy = an AND of its condition-rows, sharing this uuid). NULL for a legacy /
+ *     unconditional single-row rule. Consumed by the Task 0.3 policy store + the list-scope
+ *     translator (Phase 2/3) — the existing record-rule read adapter does not read this
+ *     column yet, which is expected at this stage.
+ *   • EMPTY today: no admin rules are seeded, so the read adapter finds nothing → the CORE
+ *     owner baseline governs (owner passes; system-provenance types are grant-governed). An
+ *     empty table is the correct safe default, NOT a lockout.
+ *
+ * Ported from astram3 `server/migrations/1720000000020-CreateRecordPermissionRule.js`
+ * (read-only reference — columns/indexes match exactly, plus the `rpr_policy_uuid` addition).
+ * Schema `shield_authz` is created by `1710000000006-CreateAuthzSchema.cjs` — NOT recreated
+ * here. Idempotent (CREATE TABLE IF NOT EXISTS). No hard-coded UUIDs (empty seed). `down`
+ * drops the table. Run by the DDL account.
+ */
+
+const SCHEMA = 'shield_authz';
+const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
+
+async function up({ query }) {
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`record_permission_rule\` (
+    rpr_uuid          VARCHAR(36)  NOT NULL,
+    rpr_policy_uuid   VARCHAR(36)  NULL,             -- groups a guided policy's AND-composed condition-rows; NULL = legacy/unconditional single-row rule
+    rpr_tenant_uuid   VARCHAR(36)  NULL,             -- NULL = global/system baseline scope
+    rpr_type_key      VARCHAR(64)  NOT NULL,         -- object type the rule governs
+    rpr_action        VARCHAR(64)  NOT NULL,         -- read/create/update/delete or '*'
+    rpr_effect        VARCHAR(16)  NOT NULL,         -- 'allow' | 'deny' (deny-wins)
+    rpr_subject_kind  VARCHAR(16)  NOT NULL,         -- 'role' | 'everyone'
+    rpr_subject_value VARCHAR(36)  NULL,             -- role uuid when kind='role'; else NULL
+    rpr_field         VARCHAR(64)  NULL,             -- record field the condition tests (NULL = unconditional)
+    rpr_operator      VARCHAR(32)  NULL,             -- one of the 14 PolicyOperator names (is_not_owner longest at 12 chars)
+    rpr_value         VARCHAR(255) NULL,             -- literal or token (e.g. '$actor.id')
+    rpr_created_at    ${TS},
+    PRIMARY KEY (rpr_uuid),
+    INDEX idx_rpr_lookup (rpr_type_key, rpr_action),
+    INDEX idx_rpr_tenant (rpr_tenant_uuid),
+    INDEX idx_rpr_policy (rpr_policy_uuid)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`record_permission_rule\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000014-CreateRecordShare.cjs

@@ -0,0 +1,49 @@
+/**
+ * Framework authz migration — `shield_authz.record_share`: the framework-defined
+ * per-record SHARE table (List-Scoping Engine spec §6.1 / plan Task 0.1). One row = one
+ * instance-level grant of an object type's record to a user/role for a single action (or
+ * `*`). A share WIDENS the record-permit tier, unioned with the owner baseline + admin
+ * rules under deny-wins.
+ *
+ *   • WHO MAY CREATE a row is bounded in code (guard's RecordShareWriter, Phase 6): only
+ *     the record's OWNER (fetched tenant-scoped, never trusted from input) may share an
+ *     `owned`-type record. This table is the STORAGE; the write bound is code.
+ *   • `rs_granted_by` records the sharer (the who-may-share audit trail).
+ *   • EMPTY today: no shares are seeded — the table starts empty and the guard adapter
+ *     finds no shares (the correct safe default, NOT a lockout).
+ *
+ * Ported from astram3 `server/migrations/1720000000030-CreateRecordShare.js` (read-only
+ * reference — columns/indexes match exactly). Schema `shield_authz` is created by
+ * `1710000000006-CreateAuthzSchema.cjs` — NOT recreated here. Idempotent (CREATE TABLE IF
+ * NOT EXISTS). No hard-coded UUIDs (empty seed). `down` drops the table. Run by the DDL
+ * account. No FK to `record_permission_rule` — the two tables are independent.
+ */
+
+const SCHEMA = 'shield_authz';
+const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
+
+async function up({ query }) {
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`record_share\` (
+    rs_uuid          VARCHAR(36)  NOT NULL,
+    rs_tenant_uuid   VARCHAR(36)  NOT NULL,        -- the tenant the shared record belongs to
+    rs_type_key      VARCHAR(64)  NOT NULL,        -- object type of the shared record
+    rs_record_uuid   VARCHAR(36)  NOT NULL,        -- the shared record's uuid
+    rs_grantee_kind  VARCHAR(16)  NOT NULL,        -- 'user' | 'role'
+    rs_grantee_uuid  VARCHAR(36)  NOT NULL,        -- the grantee user/role uuid
+    rs_action        VARCHAR(64)  NOT NULL,        -- one action per row; '*' = all actions
+    rs_granted_by    VARCHAR(36)  NOT NULL,        -- the sharer (owner) — who-may-share audit
+    rs_created_at    ${TS},
+    PRIMARY KEY (rs_uuid),
+    -- The hasShare lookup path: (tenant, type, record) narrows to a record's shares fast.
+    INDEX idx_rs_lookup (rs_tenant_uuid, rs_type_key, rs_record_uuid),
+    -- Idempotent re-share: the same (tenant, type, record, grantee, action) tuple is ONE
+    -- row — a writer's INSERT ... ON DUPLICATE KEY UPDATE keys off this unique index.
+    UNIQUE INDEX uq_rs_grant (rs_tenant_uuid, rs_type_key, rs_record_uuid, rs_grantee_kind, rs_grantee_uuid, rs_action)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`record_share\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000015-CreateScopeClosure.cjs

@@ -0,0 +1,46 @@
+/**
+ * Framework authz migration — `shield_authz.scope_closure`: the transitive-closure table for
+ * the N-level scoped-node hierarchy (ADR-0027 / Phase 1 of the scoped-hierarchy tenancy
+ * program, Task 1.1). One row = "descendant is reachable from ancestor at this depth" —
+ * `depth = 0` is the self-row (ancestor === descendant).
+ *
+ *   • `ancestor_uuid`   — a node (company) in the hierarchy.
+ *   • `descendant_uuid` — a node AT OR BELOW the ancestor (self, when depth = 0).
+ *   • `depth`           — 0 = self, 1 = direct child, 2 = grandchild, ...
+ *
+ * WHY A CLOSURE TABLE (not a recursive walk): every scope query becomes a flat, indexed
+ * lookup instead of a recursive CTE / application-side tree walk on the request-serving
+ * path:
+ *   • SUBTREE query  (everything at/under node N): `WHERE ancestor_uuid = N`
+ *   • ANCESTRY query (everything N is inside):      `WHERE descendant_uuid = N`
+ *
+ * This table is BUILT by the Task 1.2 reconciler from the node hierarchy's parent edges
+ * (using the pure `buildClosureRows` in `src/scope/closure-builder.ts` — no raw SQL walk);
+ * it is EMPTY at creation here — no seed, no hard-coded ids. `depth` is a plain INT (not
+ * unsigned) purely to mirror the sibling migrations' column style; it is never negative in
+ * practice (enforced by the pure builder, not by a DB constraint, since MariaDB has no CHECK
+ * enforcement guarantee across all supported versions used here).
+ *
+ * Schema `shield_authz` is created by `1710000000006-CreateAuthzSchema.cjs` — NOT recreated
+ * here. Idempotent (CREATE TABLE IF NOT EXISTS); `down` drops the table. Run by the DDL
+ * account (ADR-0014 schema-change containment — this file only touches `shield_authz`, never
+ * the Application schema).
+ */
+
+const SCHEMA = 'shield_authz';
+
+async function up({ query }) {
+  await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`scope_closure\` (
+    ancestor_uuid    VARCHAR(36) NOT NULL,   -- a node (company) in the hierarchy
+    descendant_uuid  VARCHAR(36) NOT NULL,   -- a node at or below the ancestor (self = depth 0)
+    depth            INT         NOT NULL,   -- 0 = self, 1 = direct child, ...
+    PRIMARY KEY (ancestor_uuid, descendant_uuid),
+    INDEX idx_scope_closure_desc (descendant_uuid)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
+}
+
+async function down({ query }) {
+  await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`scope_closure\``);
+}
+
+module.exports = { up, down };

package/migrations/1710000000016-AlterCompanyParentFkRestrict.cjs

@@ -0,0 +1,71 @@
+/**
+ * Framework migration — flip `shield_app.companies.FK_companies_parent` from
+ * `ON DELETE SET NULL` to `ON DELETE RESTRICT` (Task 1.2 / E-2 of the scoped-hierarchy tenancy
+ * program, ADR-0027).
+ *
+ * WHY: the original FK (created by identity migration `...001-CreateIdentityOrgModel`) used
+ * `ON DELETE SET NULL`. Deleting a parent company would then SILENTLY null its children's
+ * `c_parent_uuid` — promoting a whole sub-org to a root of the hierarchy. That is a
+ * tenant-boundary violation (a sub-org is not a tenant root) and it desynchronizes the
+ * `scope_closure` from the tree behind the app's back. `RESTRICT` forces the DB to REFUSE a
+ * parent delete while children exist, so a deletion must go through the explicit, fail-closed
+ * `ScopeClosureService.deleteNode` path (re-parent/cascade first). Defence-in-depth: the service
+ * checks children explicitly for a clear early error; this FK makes the DB refuse regardless.
+ *
+ * The physical `companies` table lives in `shield_app` (created by identity `...001`). This
+ * migration only ALTERs a constraint — it does NOT recreate the table. Idempotent: it DROPs the
+ * constraint if present, then ADDs the RESTRICT variant (checking information_schema so a re-run
+ * is a no-op net change). `down()` restores the original SET NULL variant.
+ *
+ * Runs merged into the ONE ordered migration timeline (loader merges guard + identity dirs by
+ * timestamp); `...016` sorts strictly after `...001`, so `companies` + its FK already exist.
+ */
+
+const SCHEMA = 'shield_app';
+const TABLE = 'companies';
+const FK = 'FK_companies_parent';
+const COL = 'c_parent_uuid';
+const PK = 'c_uuid';
+
+/** True if a FK constraint of this name exists on the table (idempotency guard). */
+async function fkExists(query) {
+  const rows = await query(
+    `SELECT 1
+       FROM information_schema.TABLE_CONSTRAINTS
+      WHERE CONSTRAINT_SCHEMA = ?
+        AND TABLE_NAME = ?
+        AND CONSTRAINT_NAME = ?
+        AND CONSTRAINT_TYPE = 'FOREIGN KEY'
+      LIMIT 1`,
+    [SCHEMA, TABLE, FK],
+  );
+  return Array.isArray(rows) && rows.length > 0;
+}
+
+async function dropFkIfPresent(query) {
+  if (await fkExists(query)) {
+    await query(`ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\` DROP FOREIGN KEY \`${FK}\``);
+  }
+}
+
+async function up({ query }) {
+  // Drop the existing SET NULL FK (if present), re-add it as RESTRICT.
+  await dropFkIfPresent(query);
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\`
+       ADD CONSTRAINT \`${FK}\` FOREIGN KEY (\`${COL}\`)
+       REFERENCES \`${SCHEMA}\`.\`${TABLE}\` (\`${PK}\`) ON DELETE RESTRICT`,
+  );
+}
+
+async function down({ query }) {
+  // Restore the original SET NULL behavior.
+  await dropFkIfPresent(query);
+  await query(
+    `ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\`
+       ADD CONSTRAINT \`${FK}\` FOREIGN KEY (\`${COL}\`)
+       REFERENCES \`${SCHEMA}\`.\`${TABLE}\` (\`${PK}\`) ON DELETE SET NULL`,
+  );
+}
+
+module.exports = { up, down };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "description": "Astram framework — the enforcement guard + real-world adapters (the 'hands'). One global deny-by-default gate every request passes through (ADR-0002), classification decorators, boot-pool assertion (ADR-0018), the forRoot() registration seam, and the DB/Redis/crypto adapters that connect the sealed core to a real backend. Depends on @astram/core (ADR-0003, ADR-0023).",
   "type": "commonjs",
@@ -24,8 +24,8 @@
     "argon2": "^0.41.1",
     "ioredis": "^5.4.1",
     "mariadb": "^3.4.0",
-    "@astram/core": "1.0.0",
-    "@astram/engine": "0.1.3"
+    "@astram/engine": "0.2.0",
+    "@astram/core": "1.2.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",