@astram/guard 0.5.0 → 0.6.0

package/dist/authz/mariadb-list-scope-adapter.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * `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}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbListScopeAdapter = exports.SHIELD_LIST_SCOPE_PORT = void 0;
+const core_1 = require("@astram/core");
+/** The DI token the adapter is bound under (parity with the rule-port token). */
+exports.SHIELD_LIST_SCOPE_PORT = Symbol('SHIELD_LIST_SCOPE_PORT');
+/** Schema the `record_permission_rule` table lives in (framework migration ...009). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/**
+ * Whether a rule group's SUBJECT matches the requesting principal — the EXACT mirror of the
+ * per-record rule adapter's `subjectMatches` ({@link MariaDbRecordPermissionRuleAdapter}):
+ *   • `everyone`               → always matches.
+ *   • `role`                   → matches IFF the principal HOLDS the named role
+ *                                (`subject.roleIds.includes(rpr_subject_value)`, value non-null).
+ *   • any other / unknown kind → does NOT match (fail-closed).
+ * A group's subject is consistent across its rows (the store writes one subject per policy),
+ * so it is read from the group's HEAD row (like the effect). A group that FAILS the subject
+ * match contributes to NEITHER allow NOR deny — it is simply not this principal's rule (a
+ * role-subjected DENY not aimed at the principal must NOT over-restrict them, the symmetric
+ * divergence — so BOTH sides are filtered identically).
+ */
+function subjectMatches(head, subject) {
+    const kind = head.rpr_subject_kind;
+    if (kind === 'everyone')
+        return true;
+    if (kind === 'role') {
+        return head.rpr_subject_value !== null && subject.roleIds.includes(head.rpr_subject_value);
+    }
+    // Unknown subject kind → does NOT match (fail-closed).
+    return false;
+}
+/**
+ * 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.
+ */
+class MariaDbListScopeAdapter {
+    db;
+    schema;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.schema = opts.schema ?? DEFAULT_SCHEMA;
+    }
+    async listPolicyConditions(typeKey, tenantNodeIds, action, subject) {
+        // The caller's reachable subtree (active node + descendants, ADR-0027). A rule scoped to
+        // ANY node in the subtree applies — critically a DENY at a descendant node excludes that
+        // node's records for a parent admin (deny-wins inherits down). Plus global (NULL-tenant)
+        // rules. Empty set (shouldn't happen — always ≥ the active node) → only global rules.
+        const nodes = tenantNodeIds.length > 0 ? tenantNodeIds : [];
+        const tenantClause = nodes.length > 0
+            ? `(rpr_tenant_uuid IN (${nodes.map(() => '?').join(', ')}) OR rpr_tenant_uuid IS NULL)`
+            : `rpr_tenant_uuid IS NULL`;
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT rpr_policy_uuid, rpr_effect, rpr_subject_kind, rpr_subject_value, rpr_field, rpr_operator, rpr_value
+           FROM \`${this.schema}\`.\`record_permission_rule\`
+          WHERE rpr_type_key = ?
+            AND ${tenantClause}
+            AND (rpr_action = ? OR rpr_action = '*')`, [typeKey, ...nodes, action]));
+        }
+        catch (err) {
+            // Genuine store outage — fail closed as retryable (never mask as an empty scope,
+            // which would silently unbound the list — a leak). ADR-0016 / Invariant #8.
+            throw new core_1.AuthorizationUnavailableError(`record_permission_rule store unavailable for ` +
+                `${typeKey}:${action} (list scope): ${err.message}`);
+        }
+        // ── AND-GROUPING BY rpr_policy_uuid (mirrors evaluate / listPolicies) ─────────
+        // Rows sharing a non-null policy uuid form ONE group (its conditions AND-composed);
+        // every NULL-policy row is a distinct singleton group (keyed by a unique sentinel).
+        // Preserve first-seen order for stable, testable output.
+        const groups = new Map();
+        let nullGroupSeq = 0;
+        for (const row of rows) {
+            const key = row.rpr_policy_uuid != null // null OR undefined ⇒ legacy single-row rule
+                ? `p:${row.rpr_policy_uuid}`
+                : `n:${nullGroupSeq++}`; // each legacy row → its own singleton group
+            const bucket = groups.get(key);
+            if (bucket)
+                bucket.push(row);
+            else
+                groups.set(key, [row]);
+        }
+        const allow = [];
+        const deny = [];
+        for (const groupRows of groups.values()) {
+            const head = groupRows[0];
+            if (head === undefined)
+                continue; // a group always has ≥1 row; guard for the type
+            // SUBJECT FILTER (HIGH-1) — the whole group is gated by its subject BEFORE its effect,
+            // EXACTLY as decide()'s per-record `subjectMatches` gates the group before its effect.
+            // A group whose subject does NOT match this principal contributes to NEITHER allow NOR
+            // deny (it is not this principal's rule). Applied identically to allow AND deny so a
+            // role-subjected deny not aimed at the principal cannot over-restrict them.
+            if (!subjectMatches(head, subject))
+                continue;
+            // A NULL-field row contributes NO condition (unconditional). A group of only such
+            // rows → an EMPTY condition list, which the translator renders as `(TRUE)` — a
+            // valid "allow/deny all of this type" rule.
+            const conditions = groupRows
+                .filter((r) => r.rpr_field !== null)
+                .map((r) => ({
+                field: r.rpr_field,
+                operator: r.rpr_operator,
+                value: r.rpr_value, // the stored VARCHAR string (canonical form; comma-string for `in`)
+            }));
+            // The group's effect is consistent across its rows (the store writes one effect per
+            // policy); take it from the first row. A non-'allow'/'deny' effect contributes to
+            // NEITHER side (fail-closed — no scope inferred from a malformed effect).
+            if (head.rpr_effect === 'deny')
+                deny.push(conditions);
+            else if (head.rpr_effect === 'allow')
+                allow.push(conditions);
+        }
+        return { allow, deny };
+    }
+}
+exports.MariaDbListScopeAdapter = MariaDbListScopeAdapter;

package/dist/authz/mariadb-policy-store.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `MariaDbPolicyStore` — the concrete {@link PolicyStore} (core admin port) for
+ * `@astram/guard`, backed by the SAME `record_permission_rule` table the read
+ * adapter ({@link MariaDbRecordPermissionRuleAdapter}) enforces. This is the
+ * AUTHOR half of **author-what-enforces**: a guided policy the admin builder
+ * produces is persisted here as EXACTLY the rows the enforcement adapter reads —
+ * no lossy round-trip, no divergent representation (List-Scoping Engine plan Task 0.3).
+ *
+ * ── THE SEMANTIC GAP THIS CLOSES (architect-identified):
+ *    A {@link GuidedPolicy} has N conditions that are **AND-composed** (ALL must
+ *    hold for the policy to apply). But `record_permission_rule` is
+ *    ONE-CONDITION-PER-ROW. If a 2-condition policy were written as 2 INDEPENDENT
+ *    rows, the read adapter's per-row fold would allow when EITHER holds — an OR,
+ *    over-widening the policy (a security bug). The fix is a GROUP id:
+ *    `rpr_policy_uuid`. All N condition-rows of one policy SHARE one generated
+ *    `rpr_policy_uuid`, and the read adapter's fold (extended in the same task)
+ *    AND-groups by it — a policy applies IFF ALL its rows hold. This store writes
+ *    that group id; the adapter honors it. The two halves agree by construction.
+ *
+ * ── THE ROW MAPPING (one GuidedPolicy → N record_permission_rule rows):
+ *    • `rpr_uuid`         — a fresh per-row UUID (crypto.randomUUID; NEVER a SQL
+ *                           `UUID()` per row — that would give each row a different
+ *                           id and, for the GROUP id, break the sharing).
+ *    • `rpr_policy_uuid`  — ONE generated UUID shared by ALL of this policy's rows
+ *                           (the group id — the `Policy.policyId` returned).
+ *    • `rpr_tenant_uuid`  — the owning tenant (storage scope; server-stamped by the
+ *                           command engine before calling — never client input).
+ *    • `rpr_type_key`     — the policy's `typeKey` (same on every row).
+ *    • `rpr_action`       — the policy's `action` (same on every row).
+ *    • `rpr_effect`       — the policy's `effect` ('allow' | 'deny'; same every row).
+ *    • `rpr_subject_kind` — always `'everyone'` (v1 mapping — a GuidedPolicy carries
+ *                           NO role subject; role-subjected policies are a future
+ *                           extension. See recon C gap #5 / Task 0.3).
+ *    • `rpr_subject_value`— always NULL (no role subject in v1).
+ *    • `rpr_field`        — the condition's `field` (NULL for a 0-condition policy).
+ *    • `rpr_operator`     — the condition's operator, persisted with core's CANONICAL
+ *                           name (`eq`, `ne`, `is_owner`, …). The read adapter
+ *                           dual-accepts legacy names, but the store writes canonical.
+ *    • `rpr_value`        — the condition's operand serialized to its string form,
+ *                           OR NULL for an operand-less operator (`is_null`,
+ *                           `is_owner`, … — the adapter ignores the operand for those,
+ *                           so NULL round-trips faithfully as `value: null`).
+ *
+ *    A ZERO-condition policy → exactly ONE row with `rpr_field`/`rpr_operator`/
+ *    `rpr_value` all NULL. The read adapter treats a NULL-field row as
+ *    UNCONDITIONAL (always-holds) — verified against `conditionHolds` (`row.rpr_field
+ *    === null ⇒ return true`). So an unconditional policy enforces as "applies
+ *    whenever subject+action match", exactly its authored intent.
+ *
+ * ── VALUE FIDELITY (documented): `rpr_value` is a VARCHAR column, so a condition's
+ *    `value` is stored as its STRING form and read back as a string. This is the
+ *    SAME form the enforcement adapter sees (`conditionHolds` always coerces via
+ *    `String(...)` / `Number(...)`), so author == enforce holds. A condition
+ *    authored with `value: 50` round-trips as `value: '50'`; both evaluate
+ *    identically at enforcement (the adapter numeric-parses ordered compares). An
+ *    operand-less operator's `value` round-trips as `null` (its operand is ignored
+ *    everywhere). Round-trip fidelity is thus preserved AT THE ENFORCEMENT LAYER —
+ *    the only fidelity that matters for author-what-enforces.
+ *
+ * ── SAFETY: every value (tenant, type_key, action, effect, field, operator, value,
+ *    both uuids) is BOUND as a `?` param — NEVER interpolated. A SQL payload in any
+ *    field is data, not SQL. No hard-coded UUIDs — ids are minted at runtime via
+ *    `crypto.randomUUID()`. Mirrors {@link MariaDbRecordPermissionRuleAdapter}.
+ *
+ * ── ADR-0003: the `mariadb` driver is a real runtime dependency; core defines only
+ *    the {@link PolicyStore} PORT. This adapter uses `@astram/core` TYPES only (erased).
+ */
+import type { GuidedPolicy, Policy, PolicyStore } from '@astram/core';
+/** The DI token the policy store is bound under (parity with the rule-port token). */
+export declare const SHIELD_POLICY_STORE: unique symbol;
+/** The minimal query surface this store needs — a `mariadb` Pool satisfies it. */
+export interface RuleQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/**
+ * The concrete guided-policy store. Persists a {@link GuidedPolicy} as N
+ * `record_permission_rule` rows sharing one `rpr_policy_uuid`, reads them back
+ * grouped by that id, and deletes a policy by it.
+ */
+export declare class MariaDbPolicyStore implements PolicyStore {
+    private readonly db;
+    private readonly schema;
+    constructor(db: RuleQueryable, opts?: {
+        schema?: string;
+    });
+    /**
+     * Persist a guided policy as N `record_permission_rule` rows (ONE row for a
+     * 0-condition policy), all sharing a freshly-minted `rpr_policy_uuid` group id.
+     * Returns the {@link Policy} with `policyId = rpr_policy_uuid`. The engine has
+     * already VALIDATED the structure (AC 5) before this is called.
+     */
+    savePolicy(tenantId: string, policy: GuidedPolicy): Promise<Policy>;
+    /**
+     * List the policies governing `typeKey` in `tenantId`, GROUPED by
+     * `rpr_policy_uuid` — each group's rows reconstruct one {@link GuidedPolicy}
+     * (its conditions = its rows, in row order). Returns `[]` when none exist (NORMAL).
+     */
+    listPolicies(typeKey: string, tenantId: string): Promise<readonly Policy[]>;
+    /**
+     * Delete the policy identified by `policyId` — ALL its condition-rows sharing
+     * that `rpr_policy_uuid`. Idempotent: a second delete of an absent policy affects
+     * zero rows (a no-op, NOT an error).
+     */
+    deletePolicy(policyId: string): Promise<void>;
+    /**
+     * TENANT-SCOPED delete (the authoring-surface delete path). Removes the policy's rows ONLY
+     * when they belong to `tenantId` — so a tenant admin can NEVER delete another tenant's policy
+     * by guessing/replaying its id (the un-scoped {@link deletePolicy} would). Returns the number
+     * of rows removed (0 ⇒ absent OR not this tenant's — idempotent, and the caller can surface a
+     * 404 rather than silently "succeeding" on someone else's policy). Idempotent: a second call
+     * removes zero rows.
+     *
+     * ── SAFETY: both `rpr_policy_uuid` + `rpr_tenant_uuid` are `?`-bound. The tenant is the
+     *    SERVER-resolved actor tenant (never client input) — see the PolicyService.
+     */
+    deletePolicyForTenant(policyId: string, tenantId: string): Promise<number>;
+}
+//# sourceMappingURL=mariadb-policy-store.d.ts.map

package/dist/authz/mariadb-policy-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-policy-store.d.ts","sourceRoot":"","sources":["../../src/authz/mariadb-policy-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAmB,MAAM,cAAc,CAAC;AAEvF,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,eAAgC,CAAC;AAKjE,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAgCD;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACpD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EAAE,EAAE,aAAa,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAK7D;;;;;OAKG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA4CzE;;;;OAIG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;IAiDjF;;;;OAIG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD;;;;;;;;;;OAUG;IACG,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CASjF"}

package/dist/authz/mariadb-policy-store.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * `MariaDbPolicyStore` — the concrete {@link PolicyStore} (core admin port) for
+ * `@astram/guard`, backed by the SAME `record_permission_rule` table the read
+ * adapter ({@link MariaDbRecordPermissionRuleAdapter}) enforces. This is the
+ * AUTHOR half of **author-what-enforces**: a guided policy the admin builder
+ * produces is persisted here as EXACTLY the rows the enforcement adapter reads —
+ * no lossy round-trip, no divergent representation (List-Scoping Engine plan Task 0.3).
+ *
+ * ── THE SEMANTIC GAP THIS CLOSES (architect-identified):
+ *    A {@link GuidedPolicy} has N conditions that are **AND-composed** (ALL must
+ *    hold for the policy to apply). But `record_permission_rule` is
+ *    ONE-CONDITION-PER-ROW. If a 2-condition policy were written as 2 INDEPENDENT
+ *    rows, the read adapter's per-row fold would allow when EITHER holds — an OR,
+ *    over-widening the policy (a security bug). The fix is a GROUP id:
+ *    `rpr_policy_uuid`. All N condition-rows of one policy SHARE one generated
+ *    `rpr_policy_uuid`, and the read adapter's fold (extended in the same task)
+ *    AND-groups by it — a policy applies IFF ALL its rows hold. This store writes
+ *    that group id; the adapter honors it. The two halves agree by construction.
+ *
+ * ── THE ROW MAPPING (one GuidedPolicy → N record_permission_rule rows):
+ *    • `rpr_uuid`         — a fresh per-row UUID (crypto.randomUUID; NEVER a SQL
+ *                           `UUID()` per row — that would give each row a different
+ *                           id and, for the GROUP id, break the sharing).
+ *    • `rpr_policy_uuid`  — ONE generated UUID shared by ALL of this policy's rows
+ *                           (the group id — the `Policy.policyId` returned).
+ *    • `rpr_tenant_uuid`  — the owning tenant (storage scope; server-stamped by the
+ *                           command engine before calling — never client input).
+ *    • `rpr_type_key`     — the policy's `typeKey` (same on every row).
+ *    • `rpr_action`       — the policy's `action` (same on every row).
+ *    • `rpr_effect`       — the policy's `effect` ('allow' | 'deny'; same every row).
+ *    • `rpr_subject_kind` — always `'everyone'` (v1 mapping — a GuidedPolicy carries
+ *                           NO role subject; role-subjected policies are a future
+ *                           extension. See recon C gap #5 / Task 0.3).
+ *    • `rpr_subject_value`— always NULL (no role subject in v1).
+ *    • `rpr_field`        — the condition's `field` (NULL for a 0-condition policy).
+ *    • `rpr_operator`     — the condition's operator, persisted with core's CANONICAL
+ *                           name (`eq`, `ne`, `is_owner`, …). The read adapter
+ *                           dual-accepts legacy names, but the store writes canonical.
+ *    • `rpr_value`        — the condition's operand serialized to its string form,
+ *                           OR NULL for an operand-less operator (`is_null`,
+ *                           `is_owner`, … — the adapter ignores the operand for those,
+ *                           so NULL round-trips faithfully as `value: null`).
+ *
+ *    A ZERO-condition policy → exactly ONE row with `rpr_field`/`rpr_operator`/
+ *    `rpr_value` all NULL. The read adapter treats a NULL-field row as
+ *    UNCONDITIONAL (always-holds) — verified against `conditionHolds` (`row.rpr_field
+ *    === null ⇒ return true`). So an unconditional policy enforces as "applies
+ *    whenever subject+action match", exactly its authored intent.
+ *
+ * ── VALUE FIDELITY (documented): `rpr_value` is a VARCHAR column, so a condition's
+ *    `value` is stored as its STRING form and read back as a string. This is the
+ *    SAME form the enforcement adapter sees (`conditionHolds` always coerces via
+ *    `String(...)` / `Number(...)`), so author == enforce holds. A condition
+ *    authored with `value: 50` round-trips as `value: '50'`; both evaluate
+ *    identically at enforcement (the adapter numeric-parses ordered compares). An
+ *    operand-less operator's `value` round-trips as `null` (its operand is ignored
+ *    everywhere). Round-trip fidelity is thus preserved AT THE ENFORCEMENT LAYER —
+ *    the only fidelity that matters for author-what-enforces.
+ *
+ * ── SAFETY: every value (tenant, type_key, action, effect, field, operator, value,
+ *    both uuids) is BOUND as a `?` param — NEVER interpolated. A SQL payload in any
+ *    field is data, not SQL. No hard-coded UUIDs — ids are minted at runtime via
+ *    `crypto.randomUUID()`. Mirrors {@link MariaDbRecordPermissionRuleAdapter}.
+ *
+ * ── ADR-0003: the `mariadb` driver is a real runtime dependency; core defines only
+ *    the {@link PolicyStore} PORT. This adapter uses `@astram/core` TYPES only (erased).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbPolicyStore = exports.SHIELD_POLICY_STORE = void 0;
+const node_crypto_1 = require("node:crypto");
+/** The DI token the policy store is bound under (parity with the rule-port token). */
+exports.SHIELD_POLICY_STORE = Symbol('SHIELD_POLICY_STORE');
+/** Schema the `record_permission_rule` table lives in (framework migration ...009). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/**
+ * The operators that take NO operand (the read adapter ignores `rpr_value` for
+ * these). Their conditions persist `rpr_value = NULL` so a round-trip yields the
+ * authored `value` back as `null` (never a spurious serialized operand).
+ */
+const OPERAND_LESS_OPERATORS = new Set([
+    'is_null',
+    'is_not_null',
+    'is_owner',
+    'is_not_owner',
+]);
+/** Serialize a condition operand to the VARCHAR form the enforcement adapter reads. */
+function serializeValue(condition) {
+    if (OPERAND_LESS_OPERATORS.has(condition.operator))
+        return null;
+    const { value } = condition;
+    if (value === null || value === undefined)
+        return null;
+    return String(value);
+}
+/**
+ * The concrete guided-policy store. Persists a {@link GuidedPolicy} as N
+ * `record_permission_rule` rows sharing one `rpr_policy_uuid`, reads them back
+ * grouped by that id, and deletes a policy by it.
+ */
+class MariaDbPolicyStore {
+    db;
+    schema;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.schema = opts.schema ?? DEFAULT_SCHEMA;
+    }
+    /**
+     * Persist a guided policy as N `record_permission_rule` rows (ONE row for a
+     * 0-condition policy), all sharing a freshly-minted `rpr_policy_uuid` group id.
+     * Returns the {@link Policy} with `policyId = rpr_policy_uuid`. The engine has
+     * already VALIDATED the structure (AC 5) before this is called.
+     */
+    async savePolicy(tenantId, policy) {
+        // ONE generated group id shared by every row of this policy (the AND-group key).
+        const policyUuid = (0, node_crypto_1.randomUUID)();
+        // A 0-condition policy → ONE unconditional row (field/operator/value NULL).
+        // Otherwise one row per AND-composed condition.
+        const rows = policy.conditions.length === 0
+            ? [{ field: null, operator: null, value: null }]
+            : policy.conditions.map((c) => ({
+                field: c.field,
+                operator: c.operator, // canonical core name (eq/ne/is_owner/…)
+                value: serializeValue(c),
+            }));
+        for (const row of rows) {
+            await this.db.query(`INSERT INTO \`${this.schema}\`.\`record_permission_rule\`
+           (rpr_uuid, rpr_policy_uuid, rpr_tenant_uuid, rpr_type_key, rpr_action,
+            rpr_effect, rpr_subject_kind, rpr_subject_value, rpr_field, rpr_operator, rpr_value)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                (0, node_crypto_1.randomUUID)(), // rpr_uuid — a fresh per-row id
+                policyUuid, // rpr_policy_uuid — the SHARED group id
+                tenantId, // rpr_tenant_uuid
+                policy.typeKey, // rpr_type_key
+                policy.action, // rpr_action
+                policy.effect, // rpr_effect
+                'everyone', // rpr_subject_kind — v1 mapping (no role subject)
+                null, // rpr_subject_value
+                row.field, // rpr_field
+                row.operator, // rpr_operator
+                row.value, // rpr_value
+            ]);
+        }
+        return { policyId: policyUuid, tenantId, policy };
+    }
+    /**
+     * List the policies governing `typeKey` in `tenantId`, GROUPED by
+     * `rpr_policy_uuid` — each group's rows reconstruct one {@link GuidedPolicy}
+     * (its conditions = its rows, in row order). Returns `[]` when none exist (NORMAL).
+     */
+    async listPolicies(typeKey, tenantId) {
+        const rows = (await this.db.query(`SELECT rpr_policy_uuid, rpr_action, rpr_effect, rpr_field, rpr_operator, rpr_value
+         FROM \`${this.schema}\`.\`record_permission_rule\`
+        WHERE rpr_type_key = ?
+          AND rpr_tenant_uuid = ?
+        ORDER BY rpr_policy_uuid, rpr_created_at, rpr_uuid`, [typeKey, tenantId]));
+        // Group by rpr_policy_uuid, preserving first-seen order.
+        const groups = new Map();
+        for (const row of rows) {
+            // A policy authored via this store always has a group id; a legacy
+            // single-row rule (rpr_policy_uuid NULL) is not a store-authored policy, so
+            // it is not surfaced as a GuidedPolicy here (the read adapter still enforces
+            // it independently).
+            if (row.rpr_policy_uuid === null)
+                continue;
+            const bucket = groups.get(row.rpr_policy_uuid);
+            if (bucket)
+                bucket.push(row);
+            else
+                groups.set(row.rpr_policy_uuid, [row]);
+        }
+        const policies = [];
+        for (const [policyId, groupRows] of groups) {
+            const first = groupRows[0];
+            if (first === undefined)
+                continue; // a group always has ≥1 row; guard for the type
+            const conditions = groupRows
+                // an unconditional (NULL-field) row contributes NO condition
+                .filter((r) => r.rpr_field !== null)
+                .map((r) => ({
+                field: r.rpr_field,
+                operator: r.rpr_operator,
+                value: r.rpr_value,
+            }));
+            policies.push({
+                policyId,
+                tenantId,
+                policy: {
+                    typeKey,
+                    action: first.rpr_action ?? '',
+                    effect: (first.rpr_effect === 'deny' ? 'deny' : 'allow'),
+                    conditions,
+                },
+            });
+        }
+        return policies;
+    }
+    /**
+     * Delete the policy identified by `policyId` — ALL its condition-rows sharing
+     * that `rpr_policy_uuid`. Idempotent: a second delete of an absent policy affects
+     * zero rows (a no-op, NOT an error).
+     */
+    async deletePolicy(policyId) {
+        await this.db.query(`DELETE FROM \`${this.schema}\`.\`record_permission_rule\`
+        WHERE rpr_policy_uuid = ?`, [policyId]);
+    }
+    /**
+     * TENANT-SCOPED delete (the authoring-surface delete path). Removes the policy's rows ONLY
+     * when they belong to `tenantId` — so a tenant admin can NEVER delete another tenant's policy
+     * by guessing/replaying its id (the un-scoped {@link deletePolicy} would). Returns the number
+     * of rows removed (0 ⇒ absent OR not this tenant's — idempotent, and the caller can surface a
+     * 404 rather than silently "succeeding" on someone else's policy). Idempotent: a second call
+     * removes zero rows.
+     *
+     * ── SAFETY: both `rpr_policy_uuid` + `rpr_tenant_uuid` are `?`-bound. The tenant is the
+     *    SERVER-resolved actor tenant (never client input) — see the PolicyService.
+     */
+    async deletePolicyForTenant(policyId, tenantId) {
+        const result = (await this.db.query(`DELETE FROM \`${this.schema}\`.\`record_permission_rule\`
+        WHERE rpr_policy_uuid = ? AND rpr_tenant_uuid = ?`, [policyId, tenantId]));
+        const affected = result?.affectedRows;
+        return typeof affected === 'number' ? affected : 0;
+    }
+}
+exports.MariaDbPolicyStore = MariaDbPolicyStore;

package/dist/authz/mariadb-record-rule-adapter.d.ts

@@ -34,9 +34,13 @@
  * ── SAFETY: every rule row is matched on `(tenant, type_key, action)` with all values
  *    BOUND as `?` params (no interpolation). The action match is exact OR the rule's
  *    wildcard `*`. Field conditions are evaluated in JS against the record attributes
- *    core supplies (design §11.1 builder shape) — the operator set is a fixed
- *    allow-list; an unknown operator makes the rule NOT match (fail-closed, never a
- *    spurious allow).
+ *    core supplies (design §11.1 builder shape) — the operator set is the FULL
+ *    14-operator {@link import('@astram/core').PolicyOperator} model (unified with
+ *    the guided policy builder, Task 0.2): `eq/ne` (dual-accept legacy
+ *    `equals`/`not_equals`), `in/not_in`, `gt/lt/gte/lte`, `contains/not_contains`,
+ *    `is_null/is_not_null`, `is_owner/is_not_owner`. An unknown operator makes the
+ *    rule NOT match (fail-closed, never a spurious allow) — see `conditionHolds`
+ *    below for the exact per-operator semantics and the documented edge-case choices.
  */
 import type { RecordPermissionRulePort, RulePermit, RulePermitInput } from '@astram/core';
 /** The DI token the adapter is bound under (parity with the session store token). */

package/dist/authz/mariadb-record-rule-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-record-rule-adapter.d.ts","sourceRoot":"","sources":["../../src/authz/mariadb-record-rule-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,UAAU,EACV,eAAe,EAChB,MAAM,cAAc,CAAC;AAGtB,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAKzE,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAsED;;;GAGG;AACH,qBAAa,kCAAmC,YAAW,wBAAwB;IACjF,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EAAE,EAAE,aAAa,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAKvD,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;CAwC5D"}
+{"version":3,"file":"mariadb-record-rule-adapter.d.ts","sourceRoot":"","sources":["../../src/authz/mariadb-record-rule-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,UAAU,EACV,eAAe,EAChB,MAAM,cAAc,CAAC;AAGtB,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,eAAoC,CAAC;AAKzE,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAsLD;;;GAGG;AACH,qBAAa,kCAAmC,YAAW,wBAAwB;IACjF,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EAAE,EAAE,aAAa,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAKvD,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;CAuE5D"}