@astram/engine 0.3.0 → 0.5.0

package/dist/pipe/stages/fetch-record.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Stage: fetch-record (update/delete on EVERY type — runs BEFORE the permission gate).
+ * Security hardening block D (#10); replaces the owner-only `fetch-owner` stage. Since Phase 8
+ * #7 it runs AFTER `type-pre-gate` (permission-gate.ts), so an actor with no permission on the
+ * type is denied before this stage can take a row lock.
+ *
+ * Core's decision authority is zero-dep (no DB), so it cannot read the record it judges. This
+ * stage reads the EXISTING row, inside the pipe's unit of work, with
+ *
+ *     SELECT * FROM <table> WHERE <whereById> LIMIT 1 FOR UPDATE
+ *
+ * through the SAME `whereById` the write stage uses (pk + actor-tenant clause + ADR-0030 write
+ * scope), and stashes:
+ *   - `ctx.existing`       — the row projected to registered field keys (the PRE-image, D9),
+ *   - `ctx.ownerId`        — the `trusted:'actorId'` column, when it is a string,
+ *   - `ctx.recordTenantId` — the `trusted:'tenantId'` column, when it is a string.
+ * The gate passes `attributes = { ...existing, ownerId }` and `resource.tenantId =
+ * recordTenantId ?? actor.tenantId` to `decide()`, so field-conditioned rules (e.g. deny
+ * `status eq locked`) fire on update/delete exactly as they do in `list()`.
+ *
+ * ── SECURITY (fail-closed, no existence oracle):
+ *   - No row ⇒ `AuthorizationDeniedError('no_record_permit')`, thrown inside the transaction
+ *     (rollback: no write, no junction sync, no audit). A missing id and a foreign-tenant or
+ *     foreign-subtree id both match zero rows here, so they are the same error. It is also the
+ *     reason core returns for an owned record the actor does not own, which is what the
+ *     previous owner pre-fetch produced for a missing owned row.
+ *   - `FOR UPDATE` row-locks the pre-image until commit, so the row the gate judged is the row
+ *     the write changes (no TOCTOU between gate and write).
+ *   - The row is never returned to the caller; only the gate sees it.
+ *   - `create` no-ops: there is no existing row (the create wall is ADR-0034, in `write.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordFacts = recordFacts;
+exports.decisionAttributes = decisionAttributes;
+exports.recordNotReachable = recordNotReachable;
+exports.fetchRecordStage = fetchRecordStage;
+const errors_js_1 = require("../../errors.js");
+const registry_js_1 = require("../../registry.js");
+const where_by_id_js_1 = require("../where-by-id.js");
+/** Project a raw row to its decision facts (shared by the write pre-fetch and `get()`). */
+function recordFacts(reg, row) {
+    const fields = {};
+    for (const f of reg.fields) {
+        const col = (0, registry_js_1.columnOf)(f);
+        if (Object.prototype.hasOwnProperty.call(row, col))
+            fields[f.key] = row[col];
+    }
+    const ownerCol = (0, registry_js_1.ownerColumn)(reg);
+    const owner = ownerCol ? row[ownerCol] : undefined;
+    const tenantCol = (0, registry_js_1.tenantColumnOf)(reg);
+    const tenant = tenantCol ? row[tenantCol] : undefined;
+    return {
+        fields,
+        ...(typeof owner === 'string' ? { ownerId: owner } : {}),
+        ...(typeof tenant === 'string' ? { tenantId: tenant } : {}),
+    };
+}
+/**
+ * The `context.attributes` bag for `decide()`: every registered field by key, plus `ownerId`
+ * (the owner baseline's input). When the type has an owner column, `ownerId` is that column's
+ * string value or absent: a null/non-string owner is never passed, so core's strict `===` owner
+ * match can never spuriously succeed.
+ */
+function decisionAttributes(reg, facts) {
+    const attrs = { ...facts.fields };
+    if ((0, registry_js_1.ownerColumn)(reg) !== null) {
+        if (facts.ownerId !== undefined)
+            attrs.ownerId = facts.ownerId;
+        else
+            delete attrs.ownerId;
+    }
+    return attrs;
+}
+/** The ONE refusal for a record the actor cannot reach (missing ≡ foreign; no ids). */
+function recordNotReachable(reg) {
+    return new errors_js_1.AuthorizationDeniedError('no_record_permit', `no reachable '${reg.typeKey}' record for this operation`);
+}
+function fetchRecordStage() {
+    return {
+        name: 'fetch-record',
+        async run(ctx) {
+            if (ctx.op === 'create')
+                return;
+            if (ctx.id === undefined)
+                throw new errors_js_1.RegistrationError(`${ctx.op} requires an id`);
+            const reg = ctx.registration;
+            const where = (0, where_by_id_js_1.whereById)(reg, ctx.actor, ctx.id);
+            const rows = (await ctx.query(`SELECT * FROM ${(0, where_by_id_js_1.qualifiedTable)(reg)} WHERE ${where.sql} LIMIT 1 FOR UPDATE`, where.params));
+            const first = Array.isArray(rows)
+                ? rows[0]
+                : undefined;
+            if (first === undefined || first === null)
+                throw recordNotReachable(reg);
+            const facts = recordFacts(reg, first);
+            ctx.existing = facts.fields;
+            if (facts.ownerId !== undefined)
+                ctx.ownerId = facts.ownerId;
+            if (facts.tenantId !== undefined)
+                ctx.recordTenantId = facts.tenantId;
+        },
+    };
+}

package/dist/pipe/stages/permission-gate.d.ts

@@ -8,4 +8,33 @@
 import type { DecisionPort } from '../../ports.js';
 import type { Stage } from '../context.js';
 export declare function permissionGateStage(decision: DecisionPort): Stage;
+/**
+ * Stage: type pre-gate (update/delete only; runs FIRST, before fetch-record's row lock).
+ * Security-hardening Phase 8 #7.
+ *
+ * fetch-record takes `SELECT * … FOR UPDATE` so the gate judges the row the write changes; but
+ * run before any check, that let an actor with NO permission on the type take row locks. This
+ * stage asks the same `decide()` the coarse question first — `{ level: 'object_type', typeKey,
+ * tenantId: actor.tenantId }` for the op's action, no attributes — and stops the pipe on deny
+ * BEFORE any SQL. On allow, fetch-record locks and the record-level permission gate runs
+ * unchanged.
+ *
+ * ── It never denies what the record-level gate would allow. In core's one decision path the
+ *    record-level and object-type-level calls differ only after gate 5 (record ⇒ gate 6 runs;
+ *    object type ⇒ allow terminates), and every input gates 0–5 and 7 read is identical here:
+ *      - typeKey and action: identical;
+ *      - resource.tenantId: the record gate uses the row's tenant column, and `whereById`
+ *        pins that column to `actor.tenantId` (a type without one falls back to it) — so it is
+ *        always `actor.tenantId`, exactly what this stage sends (gates 3 and 5 agree);
+ *      - gate 5's coarse key and root-plane rule depend only on (typeKey, action, principal);
+ *      - gate 7 (delegation) reads only the `shield.delegation` attribute, which the engine
+ *        never supplies (the record gate's attributes are registered field values).
+ *    So a deny here is a deny at gate ≤ 5 (or 7) that the record-level call reaches too.
+ *
+ * ── Existence: it runs before any read, so its answer cannot depend on whether the id exists
+ *    (a missing and an existing id give the same error). It throws the decision's own reason,
+ *    as the record gate would for the same actor. `create` no-ops: the permission gate already
+ *    judges a create at object-type level, and a create takes no lock.
+ */
+export declare function typePreGateStage(decision: DecisionPort): Stage;
 //# sourceMappingURL=permission-gate.d.ts.map

package/dist/pipe/stages/permission-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,eAAe,CAAC;AAOlE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAwCjE"}
+{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAyB,MAAM,eAAe,CAAC;AAQlE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAiCjE;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,KAAK,CAe9D"}

package/dist/pipe/stages/permission-gate.js

@@ -8,7 +8,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.permissionGateStage = permissionGateStage;
+exports.typePreGateStage = typePreGateStage;
 const errors_js_1 = require("../../errors.js");
+const fetch_record_js_1 = require("./fetch-record.js");
 /** Map the pipe op to the stable authorization action key. */
 function actionKey(op) {
     return op; // 'create' | 'update' | 'delete' — stable action keys (core §5.2)
@@ -21,33 +23,89 @@ function permissionGateStage(decision) {
             const resource = {
                 level: ctx.id !== undefined ? 'record' : 'object_type',
                 typeKey: ctx.registration.typeKey,
-                // The resource's owning tenant is the ACTOR's tenant for a write — a write
-                // into another tenant is denied by the tenant gate downstream in decide().
-                tenantId: ctx.actor.tenantId,
+                // Block D (#10): an existing record is judged at ITS tenant (read from the row by
+                // fetch-record). A create, or a type with no tenant column, uses the actor's tenant — a
+                // write into another tenant is denied by the tenant gate downstream in decide().
+                tenantId: ctx.recordTenantId ?? ctx.actor.tenantId,
                 ...(typeof ctx.id === 'string' ? { recordId: ctx.id } : {}),
             };
-            // For an OWNED update/delete, the fetch-owner stage (which ran BEFORE this one)
-            // read the existing row's owner tenant-scoped and stashed it on ctx.ownerId. Pass
-            // it to decide() so core's owner baseline can compare it to the actor. Absent (not
-            // owned, or the row is missing/other-tenant) ⇒ no attribute ⇒ the baseline finds
-            // no owner match ⇒ deny (the missing row never leaks).
+            // Block D (#10): for update/delete, fetch-record (which ran BEFORE this one) read the
+            // existing row. Every registered field (the PRE-image, D9) plus `ownerId` reaches
+            // decide(), so field-conditioned rules (e.g. deny `status eq locked`) fire here exactly
+            // as they do in list(). A missing row never reaches this stage: fetch-record threw.
             const context = {
                 isAuthenticated: true,
-                ...(ctx.ownerId !== undefined ? { attributes: { ownerId: ctx.ownerId } } : {}),
+                ...(ctx.existing !== undefined
+                    ? {
+                        attributes: (0, fetch_record_js_1.decisionAttributes)(ctx.registration, {
+                            fields: ctx.existing,
+                            ...(ctx.ownerId !== undefined ? { ownerId: ctx.ownerId } : {}),
+                        }),
+                    }
+                    : {}),
+            };
+            await decideOrThrow(decision, ctx, action, resource, context);
+        },
+    };
+}
+/** Ask `decide()` once; throw on deny (AuthorizationDeniedError) or a throw (unavailable). */
+async function decideOrThrow(decision, ctx, action, resource, context) {
+    let outcome;
+    try {
+        outcome = await decision.decide(ctx.actor, action, resource, context);
+    }
+    catch (err) {
+        // A thrown decision = transient/unavailable (ADR-0016). Fail-closed: do NOT
+        // proceed; signal retryable.
+        throw new errors_js_1.EngineUnavailableError(`decision authority unavailable for ${ctx.op} ${ctx.registration.typeKey}: ` +
+            `${err.message}`);
+    }
+    if (outcome.effect !== 'allow') {
+        throw new errors_js_1.AuthorizationDeniedError(outcome.reason, outcome.detail);
+    }
+}
+/**
+ * Stage: type pre-gate (update/delete only; runs FIRST, before fetch-record's row lock).
+ * Security-hardening Phase 8 #7.
+ *
+ * fetch-record takes `SELECT * … FOR UPDATE` so the gate judges the row the write changes; but
+ * run before any check, that let an actor with NO permission on the type take row locks. This
+ * stage asks the same `decide()` the coarse question first — `{ level: 'object_type', typeKey,
+ * tenantId: actor.tenantId }` for the op's action, no attributes — and stops the pipe on deny
+ * BEFORE any SQL. On allow, fetch-record locks and the record-level permission gate runs
+ * unchanged.
+ *
+ * ── It never denies what the record-level gate would allow. In core's one decision path the
+ *    record-level and object-type-level calls differ only after gate 5 (record ⇒ gate 6 runs;
+ *    object type ⇒ allow terminates), and every input gates 0–5 and 7 read is identical here:
+ *      - typeKey and action: identical;
+ *      - resource.tenantId: the record gate uses the row's tenant column, and `whereById`
+ *        pins that column to `actor.tenantId` (a type without one falls back to it) — so it is
+ *        always `actor.tenantId`, exactly what this stage sends (gates 3 and 5 agree);
+ *      - gate 5's coarse key and root-plane rule depend only on (typeKey, action, principal);
+ *      - gate 7 (delegation) reads only the `shield.delegation` attribute, which the engine
+ *        never supplies (the record gate's attributes are registered field values).
+ *    So a deny here is a deny at gate ≤ 5 (or 7) that the record-level call reaches too.
+ *
+ * ── Existence: it runs before any read, so its answer cannot depend on whether the id exists
+ *    (a missing and an existing id give the same error). It throws the decision's own reason,
+ *    as the record gate would for the same actor. `create` no-ops: the permission gate already
+ *    judges a create at object-type level, and a create takes no lock.
+ */
+function typePreGateStage(decision) {
+    return {
+        name: 'type-pre-gate',
+        async run(ctx) {
+            if (ctx.op === 'create')
+                return;
+            const resource = {
+                level: 'object_type',
+                typeKey: ctx.registration.typeKey,
+                tenantId: ctx.actor.tenantId,
             };
-            let outcome;
-            try {
-                outcome = await decision.decide(ctx.actor, action, resource, context);
-            }
-            catch (err) {
-                // A thrown decision = transient/unavailable (ADR-0016). Fail-closed: do NOT
-                // proceed; signal retryable.
-                throw new errors_js_1.EngineUnavailableError(`decision authority unavailable for ${ctx.op} ${ctx.registration.typeKey}: ` +
-                    `${err.message}`);
-            }
-            if (outcome.effect !== 'allow') {
-                throw new errors_js_1.AuthorizationDeniedError(outcome.reason, outcome.detail);
-            }
+            await decideOrThrow(decision, ctx, { key: actionKey(ctx.op) }, resource, {
+                isAuthenticated: true,
+            });
         },
     };
 }

package/dist/pipe/stages/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAkEzD,wBAAgB,UAAU,IAAI,KAAK,CAkDlC"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAsEzD,wBAAgB,UAAU,IAAI,KAAK,CAsElC"}

package/dist/pipe/stages/write.js

@@ -13,62 +13,65 @@ exports.writeStage = writeStage;
 const node_crypto_1 = require("node:crypto");
 const errors_js_1 = require("../../errors.js");
 const registry_js_1 = require("../../registry.js");
+const where_by_id_js_1 = require("../where-by-id.js");
+const fetch_record_js_1 = require("./fetch-record.js");
 function qualified(ctx) {
-    const schema = ctx.registration.schema;
-    const t = ctx.registration.table;
-    return schema ? `\`${schema}\`.\`${t}\`` : `\`${t}\``;
-}
-/** The physical column of a `tenantId`-trusted field, if the table has one. */
-function tenantColumn(ctx) {
-    const f = ctx.registration.fields.find((x) => x.trusted === 'tenantId');
-    return f ? (0, registry_js_1.columnOf)(f) : null;
+    return (0, where_by_id_js_1.qualifiedTable)(ctx.registration);
 }
 /**
- * Build a WHERE clause + params for a record id (uuid or composite). CRITICAL
- * cross-tenant safety: when the table is tenant-owned (has a `tenantId`-trusted
- * column), the WHERE is ALSO constrained to the ACTOR's tenant — so an update/
- * delete can NEVER touch another tenant's row even if the id is known and the gate
- * (which sees the actor's own tenant on a record-scoped resource) would allow it.
- * This is the write-path twin of the read-path scoping (defense-in-depth).
- *
- * ADR-0030 — write-scope wall: additionally, for a type declaring `readScope` (the identity
- * `system` types company_membership / membership_posting, which have NO tenant column so the
- * clause above never fires for them), a NON-ROOT actor's WHERE is constrained to rows within the
- * actor's reachable subtree (`writeScopeClause`). A targeted update/delete of a foreign-subtree
- * row then matches ZERO rows (fail-closed no-op), closing the read-wall-only asymmetry. Root
- * spans all. This is a FILTER, never a stamp (create is unaffected — the ADR-0027 decoupling
- * that lets an admin add a user to a SUB-company is preserved).
+ * WHERE for a record id: the ONE shared helper (`where-by-id.ts`) — pk + the ACTOR's tenant
+ * (when the type has a tenant column) + the ADR-0030 write-scope wall (readScope types,
+ * non-root). The fetch-record pre-fetch, UPDATE, DELETE and the ADR-0034 create wall all use it,
+ * so the row the gate judged is the row the write touches.
  */
 function whereById(ctx, id) {
-    const pk = ctx.registration.primaryKey;
-    let sql;
-    let params;
-    if (pk.kind === 'uuid') {
-        if (typeof id !== 'string') {
-            throw new errors_js_1.RegistrationError(`uuid PK table '${ctx.registration.typeKey}' needs a string id`);
-        }
-        sql = `\`${pk.column}\` = ?`;
-        params = [id];
-    }
-    else {
-        if (typeof id === 'string') {
-            throw new errors_js_1.RegistrationError(`composite PK table '${ctx.registration.typeKey}' needs a key map, not a string id`);
-        }
-        sql = pk.columns.map((c) => `\`${c}\` = ?`).join(' AND ');
-        params = pk.columns.map((c) => id[c]);
-    }
-    const tenantCol = tenantColumn(ctx);
-    if (tenantCol) {
-        sql += ` AND \`${tenantCol}\` = ?`;
-        params = [...params, ctx.actor.tenantId];
-    }
-    // ADR-0030 write-scope wall (readScope types, non-root only; null otherwise).
-    const scope = (0, registry_js_1.writeScopeClause)(ctx.registration, ctx.actor);
-    if (scope) {
-        sql += ` AND ${scope.sql}`;
-        params = [...params, ...scope.params];
+    return (0, where_by_id_js_1.whereById)(ctx.registration, ctx.actor, id);
+}
+/** `affectedRows` of a driver OK packet, or `undefined` when the result carries none. */
+function affectedRowsOf(result) {
+    if (typeof result !== 'object' || result === null)
+        return undefined;
+    const n = result.affectedRows;
+    if (typeof n === 'number')
+        return n;
+    if (typeof n === 'bigint')
+        return Number(n);
+    return undefined;
+}
+/**
+ * ADR-0034 — the CREATE-time write-scope wall (amends ADR-0030, which walled update/delete only).
+ * For a `readScope` type that has not opted out (`create: 'unscoped'`), a NON-ROOT create is
+ * re-read inside the SAME unit of work right after the INSERT, through the SAME `whereById`
+ * (pk + tenant clause + `writeScopeClause`) that update/delete use. Zero rows ⇒ the new row lies
+ * outside the actor's reachable subtree ⇒ `AuthorizationDeniedError`, and the pipe's transaction
+ * rolls the INSERT back (no row, no audit). A post-insert check — rather than inspecting input
+ * values — covers both `nodeColumn` and `subtreeSubquery` scopes with one predicate and sees the
+ * row exactly as stored. Root (`writeScopeClause` ⇒ null) is not checked. The error carries no
+ * ids (no existence leak, Invariant #10).
+ */
+async function assertCreateInsideWriteScope(ctx, table) {
+    if (!(0, registry_js_1.isCreateWalled)(ctx.registration))
+        return;
+    if ((0, registry_js_1.writeScopeClause)(ctx.registration, ctx.actor) === null)
+        return; // root spans all
+    if (ctx.resultId === undefined) {
+        throw new errors_js_1.RegistrationError(`create '${ctx.registration.typeKey}': no id to wall-check`);
     }
-    return { sql, params };
+    const where = whereById(ctx, ctx.resultId);
+    const rows = (await ctx.query(`SELECT 1 AS in_scope FROM ${table} WHERE ${where.sql} LIMIT 1`, where.params));
+    if (!Array.isArray(rows) || rows.length === 0)
+        throw outsideWriteScope(ctx);
+}
+/** The ONE create-wall refusal (same reason, same message for every cause — no oracle). */
+function outsideWriteScope(ctx) {
+    return new errors_js_1.AuthorizationDeniedError('create_outside_write_scope', `a new '${ctx.registration.typeKey}' must lie inside the actor's reachable subtree`);
+}
+/** A MariaDB/MySQL "referenced row does not exist" foreign-key violation (errno 1452). */
+function isMissingReferenceError(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const e = err;
+    return (e.errno === 1452 || e.code === 'ER_NO_REFERENCED_ROW_2' || e.code === 'ER_NO_REFERENCED_ROW');
 }
 function writeStage() {
     return {
@@ -96,7 +99,22 @@ function writeStage() {
                 }
                 const placeholders = cols.map(() => '?').join(', ');
                 const sql = `INSERT INTO ${table} (${cols.map((c) => `\`${c}\``).join(', ')}) VALUES (${placeholders})`;
-                await ctx.query(sql, cols.map((c) => ctx.columns[c]));
+                try {
+                    await ctx.query(sql, cols.map((c) => ctx.columns[c]));
+                }
+                catch (err) {
+                    // Existence oracle (security review): on a WALLED non-root create, a reference to a
+                    // node that does not exist fails the foreign key BEFORE the wall check runs. Answer it
+                    // exactly like a node outside the subtree, so "missing" and "foreign" look the same.
+                    // Root and unwalled types keep the driver error.
+                    if (isMissingReferenceError(err) &&
+                        (0, registry_js_1.isCreateWalled)(ctx.registration) &&
+                        (0, registry_js_1.writeScopeClause)(ctx.registration, ctx.actor) !== null) {
+                        throw outsideWriteScope(ctx);
+                    }
+                    throw err;
+                }
+                await assertCreateInsideWriteScope(ctx, table);
                 return;
             }
             if (ctx.op === 'update') {
@@ -116,7 +134,12 @@ function writeStage() {
             if (ctx.id === undefined)
                 throw new errors_js_1.RegistrationError('delete requires an id');
             const where = whereById(ctx, ctx.id);
-            await ctx.query(`DELETE FROM ${table} WHERE ${where.sql}`, where.params);
+            const result = await ctx.query(`DELETE FROM ${table} WHERE ${where.sql}`, where.params);
+            // Review H2: a delete that removed nothing must not go on to junction sync or audit. The
+            // fetch-record stage already row-locked the target, so this is defence in depth; it throws
+            // the same no-id refusal as a missing row (rollback).
+            if (affectedRowsOf(result) === 0)
+                throw (0, fetch_record_js_1.recordNotReachable)(ctx.registration);
             ctx.resultId = ctx.id;
         },
     };

package/dist/pipe/where-by-id.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The ONE definition of "this record, as the actor may write it" (security hardening block D).
+ *
+ * Before this file the fetch-owner stage and the write stage each carried a private copy of
+ * `whereById`. The record pre-fetch (`fetch-record.ts`), the UPDATE/DELETE and the ADR-0034
+ * post-insert create wall now all build their WHERE here, so the row the gate judges is exactly
+ * the row the write touches.
+ *
+ * WHERE = primary key
+ *       + `tenant_col = actor.tenantId` when the type has a `trusted:'tenantId'` column
+ *       + `writeScopeClause` (ADR-0030) for a `readScope` type and a non-root actor.
+ *
+ * Every identifier is the type's own registered column; every value is `?`-bound.
+ */
+import type { ObjectType, Principal, RecordId } from '../types.js';
+/** A parameterized SQL fragment. */
+export interface SqlFragment {
+    readonly sql: string;
+    readonly params: unknown[];
+}
+/** The `schema`.`table` (or `table`) identifier of a registered type. */
+export declare function qualifiedTable(reg: ObjectType): string;
+/** The primary-key predicate for a record id (uuid or composite). Throws on a shape mismatch. */
+export declare function pkClause(reg: ObjectType, id: RecordId): SqlFragment;
+/** The primary-key column(s) of a type, in declaration order (the list tiebreaker). */
+export declare function pkColumns(reg: ObjectType): readonly string[];
+/**
+ * WHERE (pk + actor-tenant clause + ADR-0030 write-scope wall) for a WRITE-path record id. A
+ * foreign-tenant or foreign-subtree id matches zero rows, exactly like a missing one, so the two
+ * are indistinguishable to the caller.
+ */
+export declare function whereById(reg: ObjectType, actor: Principal, id: RecordId): SqlFragment;
+//# sourceMappingURL=where-by-id.d.ts.map

package/dist/pipe/where-by-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"where-by-id.d.ts","sourceRoot":"","sources":["../../src/pipe/where-by-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnE,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;CAC5B;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED,iGAAiG;AACjG,wBAAgB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,GAAG,WAAW,CAiBnE;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,GAAG,WAAW,CAetF"}

package/dist/pipe/where-by-id.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * The ONE definition of "this record, as the actor may write it" (security hardening block D).
+ *
+ * Before this file the fetch-owner stage and the write stage each carried a private copy of
+ * `whereById`. The record pre-fetch (`fetch-record.ts`), the UPDATE/DELETE and the ADR-0034
+ * post-insert create wall now all build their WHERE here, so the row the gate judges is exactly
+ * the row the write touches.
+ *
+ * WHERE = primary key
+ *       + `tenant_col = actor.tenantId` when the type has a `trusted:'tenantId'` column
+ *       + `writeScopeClause` (ADR-0030) for a `readScope` type and a non-root actor.
+ *
+ * Every identifier is the type's own registered column; every value is `?`-bound.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qualifiedTable = qualifiedTable;
+exports.pkClause = pkClause;
+exports.pkColumns = pkColumns;
+exports.whereById = whereById;
+const errors_js_1 = require("../errors.js");
+const registry_js_1 = require("../registry.js");
+/** The `schema`.`table` (or `table`) identifier of a registered type. */
+function qualifiedTable(reg) {
+    return reg.schema ? `\`${reg.schema}\`.\`${reg.table}\`` : `\`${reg.table}\``;
+}
+/** The primary-key predicate for a record id (uuid or composite). Throws on a shape mismatch. */
+function pkClause(reg, id) {
+    const pk = reg.primaryKey;
+    if (pk.kind === 'uuid') {
+        if (typeof id !== 'string') {
+            throw new errors_js_1.RegistrationError(`uuid PK table '${reg.typeKey}' needs a string id`);
+        }
+        return { sql: `\`${pk.column}\` = ?`, params: [id] };
+    }
+    if (typeof id === 'string') {
+        throw new errors_js_1.RegistrationError(`composite PK table '${reg.typeKey}' needs a key map, not a string id`);
+    }
+    return {
+        sql: pk.columns.map((c) => `\`${c}\` = ?`).join(' AND '),
+        params: pk.columns.map((c) => id[c]),
+    };
+}
+/** The primary-key column(s) of a type, in declaration order (the list tiebreaker). */
+function pkColumns(reg) {
+    const pk = reg.primaryKey;
+    return pk.kind === 'uuid' ? [pk.column] : pk.columns;
+}
+/**
+ * WHERE (pk + actor-tenant clause + ADR-0030 write-scope wall) for a WRITE-path record id. A
+ * foreign-tenant or foreign-subtree id matches zero rows, exactly like a missing one, so the two
+ * are indistinguishable to the caller.
+ */
+function whereById(reg, actor, id) {
+    const pk = pkClause(reg, id);
+    let sql = pk.sql;
+    let params = pk.params;
+    const tenantCol = (0, registry_js_1.tenantColumnOf)(reg);
+    if (tenantCol) {
+        sql += ` AND \`${tenantCol}\` = ?`;
+        params = [...params, actor.tenantId];
+    }
+    const scope = (0, registry_js_1.writeScopeClause)(reg, actor);
+    if (scope) {
+        sql += ` AND ${scope.sql}`;
+        params = [...params, ...scope.params];
+    }
+    return { sql, params };
+}

package/dist/registry.d.ts

@@ -43,7 +43,8 @@ export declare function columnForRole(reg: ObjectType, role: FieldSpec['role']):
  * update/delete to rows within the actor's reachable subtree, so a targeted write to a
  * foreign-subtree row matches ZERO rows (fail-closed no-op) instead of touching it. It is a
  * FILTER, never a stamp — no column value is set, so the ADR-0027 create-stamping decoupling
- * (add-to-sub-company) is preserved.
+ * (add-to-sub-company) is preserved. ADR-0034 reuses the SAME clause for the post-insert create
+ * wall (`write.ts`), so update, delete and create share one definition of "inside my subtree".
  *
  * Returns `null` (nothing to AND) when:
  *  - the type declares no `readScope`, OR
@@ -61,6 +62,12 @@ export declare function writeScopeClause(reg: ObjectType, actor: Principal): {
     sql: string;
     params: readonly unknown[];
 } | null;
+/**
+ * Whether a NON-ROOT create of this type must pass the post-insert create wall (ADR-0034): the
+ * type declares `readScope` and has not explicitly opted out with `create: 'unscoped'`. Default
+ * walled (fail closed). Root is handled by {@link writeScopeClause} returning `null`.
+ */
+export declare function isCreateWalled(reg: ObjectType): boolean;
 /** Boot-enforce that exactly-one field claims `role`; throw if none. */
 export declare function requireRole(reg: ObjectType, role: NonNullable<FieldSpec['role']>): void;
 //# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/E,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IAExD,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAQ/B,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAWpC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,GAAG,IAAI,SAAS,UAAU,EAAE;CAG7B;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAGrF;AAaD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,GACf;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GAAG,IAAI,CAYpD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAMvF"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE/E,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IAExD,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAQ/B,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAWpC,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B,GAAG,IAAI,SAAS,UAAU,EAAE;CAG7B;AAED,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEjD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAGrF;AAaD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,GACf;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GAAG,IAAI,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAEvD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAMvF"}

package/dist/registry.js

@@ -18,6 +18,7 @@ exports.ownerColumn = ownerColumn;
 exports.tenantColumnOf = tenantColumnOf;
 exports.columnForRole = columnForRole;
 exports.writeScopeClause = writeScopeClause;
+exports.isCreateWalled = isCreateWalled;
 exports.requireRole = requireRole;
 const errors_js_1 = require("./errors.js");
 const types_js_1 = require("./types.js");
@@ -101,7 +102,8 @@ function subtreeNodesOf(actor) {
  * update/delete to rows within the actor's reachable subtree, so a targeted write to a
  * foreign-subtree row matches ZERO rows (fail-closed no-op) instead of touching it. It is a
  * FILTER, never a stamp — no column value is set, so the ADR-0027 create-stamping decoupling
- * (add-to-sub-company) is preserved.
+ * (add-to-sub-company) is preserved. ADR-0034 reuses the SAME clause for the post-insert create
+ * wall (`write.ts`), so update, delete and create share one definition of "inside my subtree".
  *
  * Returns `null` (nothing to AND) when:
  *  - the type declares no `readScope`, OR
@@ -129,6 +131,14 @@ function writeScopeClause(reg, actor) {
     const expanded = rs.subquerySql.replace(types_js_1.READ_SCOPE_NODES_TOKEN, placeholders);
     return { sql: `\`${rs.pkColumn}\` IN (${expanded})`, params: [...nodes] };
 }
+/**
+ * Whether a NON-ROOT create of this type must pass the post-insert create wall (ADR-0034): the
+ * type declares `readScope` and has not explicitly opted out with `create: 'unscoped'`. Default
+ * walled (fail closed). Root is handled by {@link writeScopeClause} returning `null`.
+ */
+function isCreateWalled(reg) {
+    return reg.readScope !== undefined && reg.readScope.create !== 'unscoped';
+}
 /** Boot-enforce that exactly-one field claims `role`; throw if none. */
 function requireRole(reg, role) {
     if (!reg.fields.some((f) => f.role === role)) {
@@ -149,6 +159,20 @@ function validate(reg) {
             throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': duplicate field key '${f.key}'`);
         }
         keys.add(f.key);
+        // ADR-0034: `immutable` is a security posture (create-only) — a truthy non-boolean is a
+        // malformed declaration, never silently read as "mutable".
+        const immutable = f.immutable;
+        if (immutable !== undefined && typeof immutable !== 'boolean') {
+            throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': field '${f.key}' immutable must be a boolean, got ` +
+                `${typeof immutable} (${String(immutable)}).`);
+        }
+    }
+    // ADR-0034: the create-wall mode is either absent (walled), 'walled' or 'unscoped'. Anything
+    // else fails boot — an opt-out is an explicit decision, never a typo.
+    const createMode = reg.readScope?.create;
+    if (createMode !== undefined && createMode !== 'walled' && createMode !== 'unscoped') {
+        throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': readScope.create must be 'walled' or 'unscoped', got ` +
+            `'${String(createMode)}'.`);
     }
     if (reg.primaryKey.kind === 'composite' && reg.primaryKey.columns.length < 2) {
         throw new errors_js_1.RegistrationError(`registration '${reg.typeKey}': composite primary key needs >= 2 columns`);