@astram/guard 0.5.0 → 0.6.0

package/dist/authz/list-scope-sql.js

@@ -0,0 +1,477 @@
+"use strict";
+/**
+ * `translateListScope` — the PURE, SECURITY-CRITICAL translator that turns core's
+ * abstract {@link ListScopeSpec} (Phase 1, `list-scope.ts`) into a SAFE, parameterized
+ * SQL WHERE fragment. Phase 3 injects the returned fragment into the engine's `list()`
+ * so a collection endpoint returns ONLY the rows `decide()` would allow — filtered IN
+ * the query (Invariant #8), never fetch-then-discard.
+ *
+ * ── THE SHAPE IT EMITS (mirrors the record-permit tier composition, `permit-tier.ts`):
+ *
+ *      <tenant-bound>  AND  ( <positive union> )  [ AND NOT ( <deny union> ) ]
+ *
+ *    • positive union = ownerBaseline OR policyAllow OR share OR crossTenant — a row is
+ *      INCLUDED if ANY term is true. NO positive term present ⇒ the union is `(FALSE)`
+ *      (fail-closed — never an empty `()` and never a `TRUE`).
+ *    • deny union     = policyDeny AND-groups OR'd, wrapped in `AND NOT (...)` so a row
+ *      matching ANY deny group is EXCLUDED even if a share/owner/allow would include it
+ *      (deny-wins is load-bearing).
+ *    • policyAllow / policyDeny are AND-GROUPS OR'd: each group is `( c1 AND c2 ... )`,
+ *      groups joined by ` OR `. Preserving the AND-within / OR-across grouping EXACTLY is
+ *      security-critical — flattening `(a AND b) OR (c)` into `a OR b OR c` over-widens.
+ *
+ * ── NO SQL INJECTION (the whole point): the ONLY tokens interpolated into the `sql`
+ *    string are PHYSICAL COLUMN identifiers resolved from the {@link ObjectType} registry
+ *    (via `columnOf`/`ownerColumn`/`uuidPkColumn`/`tenantColumnOf` from `@astram/engine` —
+ *    the guard→engine→core DAG makes that import legal), backtick-quoted. Every SPEC VALUE
+ *    is a `?` placeholder with the value pushed to `params` in emission order — NEVER
+ *    interpolated. An UNKNOWN field key (not registered on the type) is REJECTED (throws) —
+ *    a rule referencing an unregistered field is a misconfiguration, and emitting the raw
+ *    key as a column IS the injection hole (fail the read closed instead).
+ *
+ * ── FAIL-CLOSED OPERATORS (mirrors `mariadb-record-rule-adapter.ts`'s `conditionHolds`
+ *    so the SQL row set equals the per-record verdict, row-for-row):
+ *    • the NEGATIVE operators (`ne`/`not_in`/`not_contains`/`is_not_owner`) emit an
+ *      `IS NOT NULL` guard so a NULL column never wrongly matches (the Phase-0/0.4
+ *      widening bug in SQL form — `NULL <> ?` must not include the row).
+ *    • `is_owner`/`is_not_owner` additionally guard `<> ''` (an empty owner column must
+ *      never "match" an empty principal id) and compare to `principal.id`, NOT the
+ *      condition operand (the operand is ignored, exactly as `conditionHolds` does).
+ *    • `contains`/`not_contains` escape the LIKE metacharacters (`\ % _`) and use
+ *      `ESCAPE '\\'` (mirrors record-engine's search LIKE).
+ *    • an UNKNOWN operator falls to a defensive `FALSE` (fail-closed — never omit-and-widen,
+ *      never throw-open). The switch is over the closed {@link PolicyOperator} type, so this
+ *      is belt-and-braces.
+ *
+ * ── `$actor` TOKENS (mirrors `resolveValue`): a scalar-op value of `'$actor.id'` /
+ *    `'$actor.tenant'` resolves to the principal's id / tenant AS A BOUND PARAM (still `?`).
+ *    Inside an `in`/`not_in` SET the adapter does NOT resolve `$actor` — neither do we.
+ *
+ * ── `in`/`not_in` SERIALIZATION (the Phase-1 review's Low-1/Low-2 obligation): the value
+ *    may arrive as an ARRAY (`['us','eu']`) or a COMMA-STRING (`'us,eu'`); BOTH expand to
+ *    the SAME token list (split on `,`, trim) so the emitted `IN (?, ?)` matches the
+ *    adapter's `String(rpr_value).split(',')` membership test exactly.
+ *
+ * ── ROOT-UNBOUNDED: `tenantBound === 'root-unbounded'` emits NO tenant clause (root spans
+ *    tenants) AND OMITS the share + crossTenant terms — root's ownerBaseline is `{kind:'all'}`
+ *    ⇒ the union is `(TRUE)` (all rows), so share/crossTenant would be redundant (and share
+ *    needs a tenant value root does not carry). crossTenant is ALWAYS omitted in Task 2.1
+ *    (Phase 4 completes the real cross-tenant record set).
+ *
+ * ── `tenantSubtree` — the scoped-hierarchy tenant bound (ADR-0027). Core
+ *    (`ScopeTenantBound`) emits `{role:'tenantSubtree', nodeIds}` for every non-root list
+ *    (the generalization of the flat `tenantId` bound), where `nodeIds` is the PRE-EXPANDED
+ *    reachable subtree (`principal.scopeSubtreeNodeIds` — the active node + descendants,
+ *    resolved once at login and cached, Task 2.2). This translator emits a DIRECT membership:
+ *    `tenant_col IN (?, ...)` over those node ids — a row is visible when its tenant node is
+ *    IN the subtree. Every id is `?`-bound. It uses the SAME cached set the tenant GATE tests
+ *    membership against, so list ≡ decide holds BY CONSTRUCTION (no closure query at list time
+ *    → no divergence from a stale/absent `scope_closure` row, and no closure read on the list
+ *    hot path — the ADR-0024 parity guarantee). The subtree clause is ANDed with the positive
+ *    union + deny sections exactly like the flat `tenantId` case — NOT an early return. Fails
+ *    CLOSED (`{sql:'FALSE', params:[]}`) when the type has no tenant column (misconfiguration)
+ *    or when `nodeIds` is empty (no reachable scope) — never silently widen. Note:
+ *    `tenantSubtree` carries no single flat tenant value, so the share term (which needs one)
+ *    is naturally omitted here.
+ *
+ * PURE — no DB, no I/O. `translateListScope(spec, reg, principal) → { sql, params }`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownScopeFieldError = void 0;
+exports.translateListScope = translateListScope;
+const engine_1 = require("@astram/engine");
+/** Schema the `record_share` table lives in (parity with the share adapter). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/** Error thrown when a scope condition references a field the type does not register. */
+class UnknownScopeFieldError extends Error {
+    constructor(typeKey, field) {
+        super(`list-scope: unknown field '${field}' on type '${typeKey}' — a rule references an ` +
+            `unregistered field (misconfiguration); the read fails closed rather than emit it as a column.`);
+        this.name = 'UnknownScopeFieldError';
+    }
+}
+exports.UnknownScopeFieldError = UnknownScopeFieldError;
+/** Emission accumulator — a fragment builder collects params in `?`-order. */
+class Params {
+    values = [];
+    bind(value) {
+        this.values.push(value);
+        return '?';
+    }
+}
+/** Resolve a stable field KEY to its backtick-quoted physical column, or REJECT. */
+function columnFor(reg, field) {
+    const spec = reg.fields.find((f) => f.key === field);
+    if (!spec)
+        throw new UnknownScopeFieldError(reg.typeKey, field);
+    return `\`${(0, engine_1.columnOf)(spec)}\``;
+}
+/** Escape the LIKE metacharacters (`\ % _`) so a literal value matches literally. */
+function escapeLike(value) {
+    return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/** Resolve a `$actor.*` token to the principal value, else the literal (scalar ops only). */
+function resolveScalarValue(raw, principal) {
+    if (raw === '$actor.id')
+        return principal.principalId;
+    if (raw === '$actor.tenant')
+        return principal.principalTenantId;
+    return raw;
+}
+/**
+ * Split an `in`/`not_in` value into its canonical token list. An ARRAY is used as-is
+ * (stringified per element); a COMMA-STRING is split on `,` + trimmed — BOTH yield the
+ * SAME set the adapter's `String(rpr_value).split(',').map(trim)` produces. `$actor`
+ * tokens inside the set are NOT resolved (matches the adapter).
+ */
+function inTokens(value) {
+    if (Array.isArray(value))
+        return value.map((v) => String(v).trim());
+    return String(value)
+        .split(',')
+        .map((s) => s.trim());
+}
+/**
+ * Translate ONE {@link ScopeCondition} to a SQL fragment + push its params. Mirrors
+ * `conditionHolds` per-operator, with the negative-operator `IS NOT NULL` guards and the
+ * ownership `<> ''` guards that keep a NULL/empty column from wrongly matching.
+ */
+function translateCondition(cond, reg, principal, p) {
+    const col = columnFor(reg, cond.field);
+    const op = cond.operator;
+    switch (op) {
+        case 'eq':
+            return `${col} = ${p.bind(resolveScalarValue(cond.value, principal))}`;
+        case 'ne':
+            // IS NOT NULL guard = fail-closed on absent (mirrors isPresent(actual) && actual !== expected).
+            return `(${col} IS NOT NULL AND ${col} <> ${p.bind(resolveScalarValue(cond.value, principal))})`;
+        case 'in': {
+            const tokens = inTokens(cond.value);
+            const placeholders = tokens.map((t) => p.bind(t)).join(', ');
+            return `${col} IN (${placeholders})`;
+        }
+        case 'not_in': {
+            // IS NOT NULL guard (fail-closed on absent — the exact Task-0.4 fix in SQL form).
+            const tokens = inTokens(cond.value);
+            const placeholders = tokens.map((t) => p.bind(t)).join(', ');
+            return `(${col} IS NOT NULL AND ${col} NOT IN (${placeholders}))`;
+        }
+        case 'gt':
+            return `${col} > ${p.bind(resolveScalarValue(cond.value, principal))}`;
+        case 'gte':
+            return `${col} >= ${p.bind(resolveScalarValue(cond.value, principal))}`;
+        case 'lt':
+            return `${col} < ${p.bind(resolveScalarValue(cond.value, principal))}`;
+        case 'lte':
+            return `${col} <= ${p.bind(resolveScalarValue(cond.value, principal))}`;
+        case 'contains': {
+            // IS NOT NULL guard = fail-closed on absent; LIKE with escaped metacharacters.
+            const pattern = `%${escapeLike(String(resolveScalarValue(cond.value, principal)))}%`;
+            return `(${col} IS NOT NULL AND ${col} LIKE ${p.bind(pattern)} ESCAPE '\\\\')`;
+        }
+        case 'not_contains': {
+            // IS NOT NULL guard (fail-closed on absent — the safer non-widening choice).
+            const pattern = `%${escapeLike(String(resolveScalarValue(cond.value, principal)))}%`;
+            return `(${col} IS NOT NULL AND ${col} NOT LIKE ${p.bind(pattern)} ESCAPE '\\\\')`;
+        }
+        case 'is_null':
+            return `${col} IS NULL`;
+        case 'is_not_null':
+            return `${col} IS NOT NULL`;
+        case 'is_owner':
+            // Compare the field to principal.id (operand IGNORED); <> '' guard = fail-closed on empty.
+            return `(${col} IS NOT NULL AND ${col} <> '' AND ${col} = ${p.bind(principal.principalId)})`;
+        case 'is_not_owner':
+            // Same guards, mirrored for the negative ownership operator.
+            return `(${col} IS NOT NULL AND ${col} <> '' AND ${col} <> ${p.bind(principal.principalId)})`;
+        default:
+            // Unknown operator → a condition that never matches (fail-closed; never widen).
+            return 'FALSE';
+    }
+}
+/** Translate ONE AND-group: `( c1 AND c2 ... )`. An empty group ⇒ `(TRUE)` (unconditional). */
+function translateGroup(group, reg, principal, p) {
+    if (group.length === 0)
+        return '(TRUE)';
+    const parts = group.map((c) => translateCondition(c, reg, principal, p));
+    return `( ${parts.join(' AND ')} )`;
+}
+/** Translate AND-groups OR'd: `( grp1 ) OR ( grp2 ) ...`, or null when there are none. */
+function translateGroups(groups, reg, principal, p) {
+    if (groups.length === 0)
+        return null;
+    return groups.map((g) => translateGroup(g, reg, principal, p)).join(' OR ');
+}
+/**
+ * Translate the full {@link ListScopeSpec} into a SAFE parameterized WHERE fragment.
+ *
+ * @param spec      the abstract visible-set description (from `computeListScope`).
+ * @param reg       the target object type registration (the ONLY source of columns).
+ * @param principal the actor's id + tenant, for `is_owner`/`$actor.*` resolution.
+ * @returns `{ sql, params }` — `sql` carries ONLY `?` + backtick columns; `params` the
+ *          bound values in `?`-order.
+ * @throws {@link UnknownScopeFieldError} if any condition names an unregistered field.
+ */
+function translateListScope(spec, reg, principal, opts = {}) {
+    const schema = opts.schema ?? DEFAULT_SCHEMA;
+    // The cross-tenant expiry filter binds THIS clock's epoch-ms against the BIGINT
+    // `ctg_expires_at_ms` column — timezone-immune (mirrors MariaDbCrossTenantGrantAdapter's
+    // injectable clock). Injectable for deterministic tests.
+    const nowMs = opts.nowMs ?? (() => Date.now());
+    const p = new Params();
+    const clauses = [];
+    // ── 1. Tenant bound ────────────────────────────────────────────────────────
+    const rootUnbounded = spec.tenantBound === 'root-unbounded';
+    let tenantValue = null;
+    // The node set the SHARE term scopes to (a shared record must belong to a node the
+    // principal can reach): flat → [the one tenant]; subtree → the whole reachable node set.
+    // Null while root-unbounded (share omitted — root's baseline already includes all).
+    let tenantNodeIds = null;
+    // The tenant clause is captured here (not pushed directly) so the cross-tenant term can OR
+    // into it: a cross-tenant grant reaches rows in the OWNING tenant, which are OUTSIDE the
+    // actor's own tenant/subtree — so it WIDENS the tenant gate (the list-form of decide()'s
+    // tenant gate PROCEEDING on a grant), it does NOT join the positive union (which filters
+    // WITHIN the visible tenants). `null` while root-unbounded (no tenant clause at all).
+    let tenantClause = null;
+    if (!rootUnbounded) {
+        if (spec.tenantBound.role === 'tenantSubtree') {
+            // Scoped-hierarchy bound (ADR-0027): the row's tenant node must be IN the principal's
+            // reachable subtree. `nodeIds` is the PRE-EXPANDED cached set (self + descendants,
+            // resolved once at login — Task 2.2), the SAME set the tenant GATE tests membership
+            // against — so `tenant_col IN (?, ...)` over these ids makes list ≡ decide equivalence
+            // hold BY CONSTRUCTION (no closure query here → no divergence from a stale/absent
+            // closure row, and no closure read on the list hot path — the parity guarantee). All
+            // ids are `?`-bound. Falls THROUGH to the union/deny sections (ANDed — NOT early return).
+            const tenantCol = (0, engine_1.tenantColumnOf)(reg);
+            if (tenantCol === null) {
+                // No `trusted:'tenantId'` column. If the type declares a `readScope` (the
+                // decoupled read-wall, Task 4.1 — the identity system types company/user/role/…),
+                // that clause IS the tenant wall (applied by the engine over the SAME subtree), so
+                // the list-scope tenant bound defers to it: emit NO tenant clause here (the positive
+                // union still governs, and the engine's readScope ANDs the subtree wall). Without a
+                // readScope, a subtree bound on a tenant-column-less type is a misconfiguration →
+                // fail closed. tenantNodeIds stays null → the share term (which needs a tenant value)
+                // is naturally omitted (a readScope type is not record-shared in v1).
+                if (reg.readScope) {
+                    // defer to readScope — no tenant clause added; fall through to the union/deny.
+                }
+                else {
+                    return { sql: 'FALSE', params: [] };
+                }
+            }
+            else {
+                const nodeIds = spec.tenantBound.nodeIds;
+                if (nodeIds.length === 0) {
+                    // No reachable scope → no rows (fail-closed; shouldn't happen — Task 3.2 always
+                    // emits at least the active node).
+                    return { sql: 'FALSE', params: [] };
+                }
+                const nodePlaceholders = nodeIds.map((n) => p.bind(n)).join(', ');
+                tenantClause = `\`${tenantCol}\` IN (${nodePlaceholders})`;
+                // The SHARE term scopes to the WHOLE reachable subtree (a record shared to the
+                // principal may live at any node it can reach), so `rs_tenant_uuid IN (subtree)`.
+                tenantNodeIds = nodeIds;
+            }
+        }
+        else {
+            tenantValue = spec.tenantBound.value;
+            const tenantCol = (0, engine_1.tenantColumnOf)(reg);
+            if (tenantCol === null) {
+                // A tenant-scoped bound on a type with no tenant column is a misconfiguration →
+                // fail closed (the whole fragment is FALSE — no rows). Documented (Decision).
+                return { sql: 'FALSE', params: [] };
+            }
+            tenantClause = `\`${tenantCol}\` = ${p.bind(tenantValue)}`;
+            tenantNodeIds = [tenantValue]; // the flat case: the share is scoped to the one tenant
+        }
+        if (tenantClause !== null)
+            clauses.push(tenantClause);
+    }
+    // ── 2. Positive union ( ownerBaseline OR policyAllow OR share OR crossTenant ) ──
+    const positive = [];
+    // ownerBaseline
+    const ob = spec.ownerBaseline;
+    if (ob.kind === 'all') {
+        positive.push('TRUE');
+    }
+    else if (ob.kind === 'owned') {
+        const ownerCol = (0, engine_1.ownerColumn)(reg);
+        if (ownerCol === null) {
+            // owned type with no owner column (misconfig) → contributes FALSE (fail-closed).
+            positive.push('FALSE');
+        }
+        else {
+            positive.push(`\`${ownerCol}\` = ${p.bind(ob.principalId)}`);
+        }
+    }
+    // kind:'none' → contributes nothing.
+    // policyAllow (AND-groups OR'd)
+    const allow = translateGroups(spec.policyAllow, reg, principal, p);
+    if (allow !== null)
+        positive.push(allow);
+    // share — OMITTED for root-unbounded (baseline TRUE already includes everything). For a
+    // non-root list (flat OR subtree), the share is scoped to the reachable node set:
+    // `rs_tenant_uuid IN (nodes)` (flat = the one tenant; subtree = self + descendants). A
+    // record shared to the principal at any reachable node is unioned in. Decision C.
+    if (!rootUnbounded && tenantNodeIds !== null && tenantNodeIds.length > 0) {
+        const share = translateShareOrdered(spec.share, tenantNodeIds, spec.typeKey, reg, p, schema);
+        if (share !== null)
+            positive.push(share);
+    }
+    const union = positive.length === 0 ? 'FALSE' : positive.join(' OR ');
+    clauses.push(`( ${union} )`);
+    // At this point `clauses` = [ <tenant clause?>, ( <positive union> ) ] — the SAME-TENANT
+    // visible positive set: a row must be IN the tenant gate AND satisfy a positive permit.
+    const sameTenantPositive = clauses.join(' AND ');
+    // ── 3. PER-BRANCH deny scoping (Task 4.2 — the fail-open leak fix) ───────────────────────
+    // decide() judges each record AT ITS OWN TENANT, so a Tenant-B deny touches only Tenant-B
+    // records. The list must mirror that: the actor-subtree deny (`spec.policyDeny`) scopes the
+    // SAME-TENANT branch; the owning-tenant deny (`opts.owningTenantDeny`, fetched over the
+    // grant's owning tenants) scopes the CROSS-TENANT branch. A SINGLE global `AND NOT (deny)`
+    // over both would (a) leak — miss the owning tenant's deny on a cross-tenant row (the caught
+    // bug), and (b) over-restrict — wrongly exclude a same-tenant row matching the owning tenant's
+    // deny. Bind order follows emission: actorDeny (inside the same-tenant branch) → crossTenant
+    // reach → owningDeny (inside the cross-tenant branch) — the `Params` positional-bind contract.
+    const actorDeny = translateGroups(spec.policyDeny, reg, principal, p);
+    const sameTenantBranch = actorDeny !== null ? `( ${sameTenantPositive} ) AND NOT ( ${actorDeny} )` : sameTenantPositive;
+    // ── Cross-tenant grant reach (§10bis.5) — a FULL permit source, its OWN deny-scoped branch ──
+    // In decide(), an active, consented cross-tenant grant BOTH lets the tenant gate proceed
+    // (gate 3/5) AND contributes the record-permit (gate 6 via evaluateRecordShare) — so a
+    // cross-tenant-reachable row is visible on the grant ALONE (it need NOT be in the actor's own
+    // tenant NOR satisfy the actor's own owner/policy/share union). It remains subject to the
+    // OWNING tenant's deny-wins (`decide()` evaluates the record's rules at the record's tenant).
+    // OMITTED for root-unbounded (baseline TRUE covers all; root carries no grantee identity).
+    let result;
+    if (!rootUnbounded) {
+        const crossTenant = translateCrossTenant(spec, reg, schema, nowMs, p);
+        if (crossTenant !== null) {
+            const owningDeny = translateGroups(opts.owningTenantDeny ?? [], reg, principal, p);
+            const crossBranch = owningDeny !== null ? `( ${crossTenant} ) AND NOT ( ${owningDeny} )` : crossTenant;
+            result = `( ${sameTenantBranch} OR ${crossBranch} )`;
+        }
+        else {
+            result = sameTenantBranch;
+        }
+    }
+    else {
+        result = sameTenantBranch;
+    }
+    return { sql: result, params: p.values };
+}
+/**
+ * The share subquery with CORRECT param ordering: tenant + typeKey bind BEFORE the grantee
+ * params, matching the emitted SQL left-to-right. Returns null when the share is absent or
+ * the type has no uuid PK (composite-PK types key the share off the uuid record id, which
+ * they lack in v1 — omit + documented).
+ */
+function translateShareOrdered(share, tenantNodeIds, typeKey, reg, p, schema) {
+    if (share.kind !== 'shared-records')
+        return null;
+    if (reg.primaryKey.kind !== 'uuid')
+        return null;
+    if (tenantNodeIds.length === 0)
+        return null;
+    const pkCol = `\`${(0, engine_1.uuidPkColumn)(reg.primaryKey)}\``;
+    // Bind in emission order: tenant node(s), typeKey, principalId, roleIds..., action.
+    // The share is scoped to the principal's reachable node set (`rs_tenant_uuid IN (...)`):
+    // flat = the one tenant; subtree = self + descendants. Every node id is `?`-bound.
+    const tenantPlaceholders = tenantNodeIds.map((n) => p.bind(n)).join(', ');
+    const typeKeyP = p.bind(typeKey);
+    let granteeSql = `(rs_grantee_kind = 'user' AND rs_grantee_uuid = ${p.bind(share.principalId)})`;
+    if (share.roleIds.length > 0) {
+        const placeholders = share.roleIds.map((r) => p.bind(r)).join(', ');
+        granteeSql += ` OR (rs_grantee_kind = 'role' AND rs_grantee_uuid IN (${placeholders}))`;
+    }
+    const actionP = p.bind(share.action);
+    return (`${pkCol} IN (` +
+        `SELECT rs_record_uuid FROM \`${schema}\`.\`record_share\`` +
+        ` WHERE rs_tenant_uuid IN (${tenantPlaceholders})` +
+        ` AND rs_type_key = ${typeKeyP}` +
+        ` AND (${granteeSql})` +
+        ` AND (rs_action = ${actionP} OR rs_action = '*')` +
+        `)`);
+}
+/**
+ * The cross-tenant grant reach (§10bis.5) — the list-form of decide()'s tenant gate PROCEEDING
+ * on an active, consented cross-tenant grant (ADR-0009). A non-root grantee that holds such a
+ * grant reaches the OWNING tenant's granted rows, which live OUTSIDE its own subtree, so this
+ * fragment WIDENS the tenant gate (it is OR'd into the tenant clause — never the positive
+ * union, which filters WITHIN the visible tenants). Returns `null` when there is no grant
+ * descriptor (`kind:'none'`) or the widening is impossible (no tenant column AND no uuid PK).
+ *
+ * ── MIRRORS MariaDbCrossTenantGrantAdapter's active-grant filter EXACTLY:
+ *    `ctg_status='accepted' AND ctg_revoked_at IS NULL AND ctg_expires_at_ms > ?` (bound
+ *    epoch-ms, timezone-immune) AND `ctg_type_key = ?` AND the grantee predicate
+ *    (`user` OR — only when roles exist — `role IN (...)`; an empty role list emits NO
+ *    `IN ()`). The DIFFERENCE from the adapter (which answers ONE record and left the ceiling
+ *    to core): the list CANNOT post-filter, so the ACTION CEILING is filtered IN-QUERY via
+ *    `JSON_CONTAINS(ctg_allowed_actions, JSON_QUOTE(?))` (the JSON array membership test) — a
+ *    row whose grant does not permit the listed action never surfaces.
+ *
+ * ── TWO REACH SHAPES, OR'd (a grant may be either):
+ *    • `object_type` grant → ALL of the owning tenant's rows of this type: widen by the tenant
+ *      column — `tenant_col IN (SELECT ctg_owning_tenant_uuid FROM … WHERE ctg_scope='object_type' …)`.
+ *      Omitted when the type has no tenant column (nothing to widen).
+ *    • `record` grant → the SPECIFIC record: widen by the uuid PK —
+ *      `pk IN (SELECT ctg_record_uuid FROM … WHERE ctg_scope='record' AND ctg_record_uuid IS NOT NULL …)`.
+ *      Omitted when the type has no uuid PK.
+ *
+ * ── SAFETY: every value (nowMs, typeKey, grantee, each roleId, action) is `?`-bound in
+ *    emission order — never interpolated. Mirrors {@link translateShareOrdered}.
+ */
+function translateCrossTenant(spec, reg, schema, nowMs, p) {
+    const xt = spec.crossTenant;
+    if (xt.kind !== 'granted')
+        return null;
+    const tenantCol = (0, engine_1.tenantColumnOf)(reg);
+    const hasUuidPk = reg.primaryKey.kind === 'uuid';
+    if (tenantCol === null && !hasUuidPk)
+        return null; // nothing to widen — fail-closed (omit)
+    const table = `\`${schema}\`.\`cross_tenant_grant\``;
+    // The shared active-grant WHERE tail — binds in EMISSION ORDER (typeKey, now, grantee(+roles),
+    // action) so the `?` placeholders line up with `Params` positional binds. Emitted (and bound)
+    // fresh per subquery so `Params` stays in `?`-order. ⚠️ typeKey binds BEFORE now because
+    // `ctg_type_key = ?` is emitted BEFORE `ctg_expires_at_ms > ?` — binding now first swapped the
+    // two, feeding the timestamp to ctg_type_key and the typeKey to the expiry compare (a silent
+    // no-match the live equivalence gate caught).
+    const activeTail = (scopeClause) => {
+        const typeKeyP = p.bind(spec.typeKey);
+        const nowP = p.bind(nowMs());
+        let granteeSql = `(ctg_grantee_kind = 'user' AND ctg_grantee_uuid = ${p.bind(xt.principalId)})`;
+        if (xt.roleIds.length > 0) {
+            const placeholders = xt.roleIds.map((r) => p.bind(r)).join(', ');
+            granteeSql += ` OR (ctg_grantee_kind = 'role' AND ctg_grantee_uuid IN (${placeholders}))`;
+        }
+        // The action ceiling: a JSON array membership test (the list cannot post-filter). A grant
+        // whose ceiling does not contain the listed action contributes NO owning tenant / record.
+        const actionP = p.bind(xt.action);
+        return (` WHERE ctg_type_key = ${typeKeyP}` +
+            `   AND ctg_status = 'accepted'` +
+            `   AND ctg_revoked_at IS NULL` +
+            `   AND ctg_expires_at_ms > ${nowP}` +
+            `   AND (${granteeSql})` +
+            `   AND JSON_CONTAINS(ctg_allowed_actions, JSON_QUOTE(${actionP}))` +
+            `   AND ${scopeClause}`);
+    };
+    const reaches = [];
+    // object_type reach — widen the tenant column to the owning tenants that granted the whole
+    // type. Emitted FIRST (so its params bind first). Omitted when there is no tenant column.
+    if (tenantCol !== null) {
+        reaches.push(`\`${tenantCol}\` IN (` +
+            `SELECT ctg_owning_tenant_uuid FROM ${table}` +
+            activeTail(`ctg_scope = 'object_type'`) +
+            `)`);
+    }
+    // record reach — widen the uuid PK to the specific granted records. Omitted when there is no
+    // uuid PK. `ctg_record_uuid IS NOT NULL` guards a record row against a spurious NULL match.
+    if (hasUuidPk) {
+        const pkCol = `\`${(0, engine_1.uuidPkColumn)(reg.primaryKey)}\``;
+        reaches.push(`${pkCol} IN (` +
+            `SELECT ctg_record_uuid FROM ${table}` +
+            activeTail(`ctg_scope = 'record' AND ctg_record_uuid IS NOT NULL`) +
+            `)`);
+    }
+    if (reaches.length === 0)
+        return null;
+    return reaches.length === 1 ? reaches[0] : `( ${reaches.join(' OR ')} )`;
+}

package/dist/authz/mariadb-cross-tenant-grant-adapter.d.ts

@@ -86,5 +86,33 @@ export declare class MariaDbCrossTenantGrantAdapter implements CrossTenantGrantP
         nowMs?: () => number;
     });
     findActiveGrant(query: CrossTenantGrantQuery): Promise<CrossTenantGrant | null>;
+    /**
+     * The DISTINCT owning tenants a grantee reaches for `(typeKey, action)` via an ACTIVE,
+     * consented cross-tenant grant — the LIST-form companion to {@link findActiveGrant}. Used by
+     * the list-scope wiring to fetch the OWNING tenant's deny rules so a cross-tenant-reached
+     * record the owning tenant DENIES is excluded from the grantee's list (deny-wins per the
+     * resource's tenant, exactly as `decide()` applies it — closing the fail-open leak the Phase-4
+     * adversarial review found).
+     *
+     * ── SAME active-grant filter as findActiveGrant: `ctg_status='accepted' AND
+     *    ctg_revoked_at IS NULL AND ctg_expires_at_ms > ?` (bound epoch-ms, timezone-immune) AND
+     *    the grantee predicate (user OR — only when roles exist — role IN (...)) AND the action
+     *    ceiling (`JSON_CONTAINS(ctg_allowed_actions, JSON_QUOTE(?))`). Covers BOTH `object_type`
+     *    and `record` grants (any active grant into a tenant means that tenant's deny rules must
+     *    scope the grantee's view of it). Returns `[]` when there is no active grant (a normal
+     *    absence — the caller then adds NO owning-tenant deny).
+     *
+     * ── FAIL-CLOSED (ADR-0016): a genuine store outage THROWS
+     *    {@link AuthorizationUnavailableError} — never a silent `[]` that would drop the owning
+     *    tenant's deny and REOPEN the leak.
+     *
+     * ── SAFETY: every value (`?`-bound); empty roleIds omits the role branch (never `IN ()`).
+     */
+    listActiveOwningTenants(query: {
+        grantee: string;
+        roleIds: readonly string[];
+        typeKey: string;
+        action: string;
+    }): Promise<string[]>;
 }
 //# sourceMappingURL=mariadb-cross-tenant-grant-adapter.d.ts.map

package/dist/authz/mariadb-cross-tenant-grant-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-cross-tenant-grant-adapter.d.ts","sourceRoot":"","sources":["../../src/authz/mariadb-cross-tenant-grant-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,cAAc,CAAC;AAGtB,wFAAwF;AACxF,eAAO,MAAM,8BAA8B,eAA2C,CAAC;AAKvF,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAsDD;;;;GAIG;AACH,qBAAa,8BAA+B,YAAW,oBAAoB;IACzE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,EAAE,EAAE,cAAc,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAQ9E,eAAe,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAuFtF"}
+{"version":3,"file":"mariadb-cross-tenant-grant-adapter.d.ts","sourceRoot":"","sources":["../../src/authz/mariadb-cross-tenant-grant-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,cAAc,CAAC;AAGtB,wFAAwF;AACxF,eAAO,MAAM,8BAA8B,eAA2C,CAAC;AAKvF,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAsDD;;;;GAIG;AACH,qBAAa,8BAA+B,YAAW,oBAAoB;IACzE,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,EAAE,EAAE,cAAc,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;KAAO;IAQ9E,eAAe,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAwFrF;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,uBAAuB,CAAC,KAAK,EAAE;QACnC,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAgCtB"}

package/dist/authz/mariadb-cross-tenant-grant-adapter.js

@@ -207,5 +207,54 @@ class MariaDbCrossTenantGrantAdapter {
         };
         return grant;
     }
+    /**
+     * The DISTINCT owning tenants a grantee reaches for `(typeKey, action)` via an ACTIVE,
+     * consented cross-tenant grant — the LIST-form companion to {@link findActiveGrant}. Used by
+     * the list-scope wiring to fetch the OWNING tenant's deny rules so a cross-tenant-reached
+     * record the owning tenant DENIES is excluded from the grantee's list (deny-wins per the
+     * resource's tenant, exactly as `decide()` applies it — closing the fail-open leak the Phase-4
+     * adversarial review found).
+     *
+     * ── SAME active-grant filter as findActiveGrant: `ctg_status='accepted' AND
+     *    ctg_revoked_at IS NULL AND ctg_expires_at_ms > ?` (bound epoch-ms, timezone-immune) AND
+     *    the grantee predicate (user OR — only when roles exist — role IN (...)) AND the action
+     *    ceiling (`JSON_CONTAINS(ctg_allowed_actions, JSON_QUOTE(?))`). Covers BOTH `object_type`
+     *    and `record` grants (any active grant into a tenant means that tenant's deny rules must
+     *    scope the grantee's view of it). Returns `[]` when there is no active grant (a normal
+     *    absence — the caller then adds NO owning-tenant deny).
+     *
+     * ── FAIL-CLOSED (ADR-0016): a genuine store outage THROWS
+     *    {@link AuthorizationUnavailableError} — never a silent `[]` that would drop the owning
+     *    tenant's deny and REOPEN the leak.
+     *
+     * ── SAFETY: every value (`?`-bound); empty roleIds omits the role branch (never `IN ()`).
+     */
+    async listActiveOwningTenants(query) {
+        let granteeSql = `(ctg_grantee_kind = 'user' AND ctg_grantee_uuid = ?)`;
+        const granteeParams = [query.grantee];
+        if (query.roleIds.length > 0) {
+            const placeholders = query.roleIds.map(() => '?').join(', ');
+            granteeSql += ` OR (ctg_grantee_kind = 'role' AND ctg_grantee_uuid IN (${placeholders}))`;
+            granteeParams.push(...query.roleIds);
+        }
+        const nowMs = this.now();
+        const params = [query.typeKey, nowMs, ...granteeParams, query.action];
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT DISTINCT ctg_owning_tenant_uuid` +
+                ` FROM \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` WHERE ctg_type_key = ?` +
+                `   AND ctg_status = 'accepted'` +
+                `   AND ctg_revoked_at IS NULL` +
+                `   AND ctg_expires_at_ms > ?` +
+                `   AND (${granteeSql})` +
+                `   AND JSON_CONTAINS(ctg_allowed_actions, JSON_QUOTE(?))`, params));
+        }
+        catch (err) {
+            throw new core_1.AuthorizationUnavailableError(`cross_tenant_grant store unavailable resolving owning tenants for ` +
+                `${query.typeKey}:${query.action}: ${err.message}`);
+        }
+        return rows.map((r) => r.ctg_owning_tenant_uuid).filter((t) => typeof t === 'string');
+    }
 }
 exports.MariaDbCrossTenantGrantAdapter = MariaDbCrossTenantGrantAdapter;

package/dist/authz/mariadb-list-scope-adapter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `MariaDbListScopeAdapter` — the concrete {@link ListScopePort} for `@astram/guard`,
+ * backed by the SAME `record_permission_rule` table the record-permit rule adapter
+ * ({@link MariaDbRecordPermissionRuleAdapter}) enforces. This is the LIST-form sibling
+ * to that adapter's `evaluate`: where `evaluate` folds the rules into an allow/deny
+ * verdict for ONE record, this projects them into the abstract allow/deny
+ * {@link ScopeCondition} GROUPS that core's `computeListScope` hands the guard translator
+ * ({@link translateListScope}) to push into a collection's WHERE (Invariant #8).
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): the `mariadb` driver is a real runtime dependency;
+ *    core defines only the {@link ListScopePort}. This adapter is INJECTED into the wired
+ *    list-scope computation. It uses `@astram/core` TYPES only (erased).
+ *
+ * ── THE SELECTION (identical to the rule adapter's `evaluate`): rows for
+ *    `(rpr_type_key = ? AND (rpr_tenant_uuid = ? OR rpr_tenant_uuid IS NULL)
+ *      AND (rpr_action = ? OR rpr_action = '*'))` — the exact-tenant OR global-NULL rule
+ *    and the exact-action OR `*` wildcard, all values BOUND as `?` (never interpolated).
+ *    NO OR-IS-NULL escalation of a tenant-scoped rule beyond that global-baseline match.
+ *
+ * ── THE GROUPING (Phase-0 / Task-0.3, mirrors both the rule adapter's `evaluate` and the
+ *    policy store's `listPolicies`): rows sharing a non-null `rpr_policy_uuid` form ONE
+ *    AND-group (a guided policy's N AND-composed conditions); a NULL-uuid row is its OWN
+ *    singleton group (legacy single-row rule — an OR term, never merged). Allow-effect
+ *    groups → `allow: ScopeCondition[][]`; deny-effect groups → `deny: ScopeCondition[][]`.
+ *    A NULL-field row contributes NO condition — an all-`TRUE` (unconditional) group,
+ *    which the translator renders as `(TRUE)` (a valid "allow/deny all of this type" rule).
+ *
+ * ── VALUE FIDELITY: `rpr_value` is read back as its stored VARCHAR string — the SAME form
+ *    the enforcement adapter's `conditionHolds` sees (it always coerces via `String(...)`).
+ *    For `in`/`not_in` this string is the canonical comma form the translator splits on `,`,
+ *    so the emitted `IN (...)` list equals the adapter's `String(rpr_value).split(',')` set
+ *    (the Phase-1 review's serialization obligation — Decision B in the task report).
+ *
+ * ── FAIL-CLOSED (ADR-0016 / Invariant #8): a genuine store outage THROWS
+ *    {@link AuthorizationUnavailableError} — NEVER an empty `{allow:[],deny:[]}` that would
+ *    silently unbound/mis-scope the list (an unbounded list is a leak). An empty result is
+ *    returned ONLY for a genuine data-absence (no applicable rule), NEVER to mask an outage.
+ *
+ * ── SAFETY: parameterized SQL only; schema `shield_authz`. Mirrors
+ *    {@link MariaDbRecordPermissionRuleAdapter}.
+ */
+import type { ListScopePort, ListPolicyConditions, ListScopeSubject } from '@astram/core';
+/** The DI token the adapter is bound under (parity with the rule-port token). */
+export declare const SHIELD_LIST_SCOPE_PORT: unique symbol;
+/** The minimal query surface this adapter needs — a `mariadb` Pool satisfies it. */
+export interface ListScopeQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/**
+ * The concrete list-scope adapter. Reads the ADMIN rules for `(tenant, type_key, action|*)`
+ * and projects them into allow/deny {@link ScopeCondition} AND-groups for the translator.
+ */
+export declare class MariaDbListScopeAdapter implements ListScopePort {
+    private readonly db;
+    private readonly schema;
+    constructor(db: ListScopeQueryable, opts?: {
+        schema?: string;
+    });
+    listPolicyConditions(typeKey: string, tenantNodeIds: readonly string[], action: string, subject: ListScopeSubject): Promise<ListPolicyConditions>;
+}
+//# sourceMappingURL=mariadb-list-scope-adapter.d.ts.map

package/dist/authz/mariadb-list-scope-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-list-scope-adapter.d.ts","sourceRoot":"","sources":["../../src/authz/mariadb-list-scope-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAGjB,MAAM,cAAc,CAAC;AAGtB,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,eAAmC,CAAC;AAKvE,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAoCD;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,aAAa;IAC3D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EAAE,EAAE,kBAAkB,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAK5D,oBAAoB,CACxB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,oBAAoB,CAAC;CA8EjC"}