@astram/guard 0.2.0 → 0.4.0

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

@@ -0,0 +1,90 @@
+/**
+ * `MariaDbCrossTenantGrantAdapter` — the concrete {@link CrossTenantGrantPort} for
+ * `@astram/guard`, backed by the `cross_tenant_grant` table (ADR-0009). It answers
+ * `findActiveGrant`: is there an ACTIVE (accepted, unexpired, unrevoked), consented grant
+ * that lets THIS grantee reach THIS owning tenant's object type (+ record) for an action?
+ *
+ * ── WHAT A CROSS-TENANT GRANT IS (ADR-0009): the ONLY sanctioned way (short of root)
+ *    a principal reaches a resource owned by a DIFFERENT tenant. It is an explicit,
+ *    CONSENTED handshake — the OWNING tenant (whose data is reached into) offers it, the
+ *    GRANTEE tenant accepts it, either side may revoke it, and it always expires. It is NEVER
+ *    a root bypass: it carries a HARD, non-wildcard action ceiling and a scope
+ *    (whole object type, or a single record). This adapter only REPORTS an active grant; core's
+ *    `isCrossTenantGrantApplicable` re-checks the ceiling + scope + expiry (defense-in-depth).
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): the `mariadb` driver is a real runtime dependency; core
+ *    defines only the PORT. This adapter is INJECTED into core's wired decision authority. It
+ *    uses `@astram/core` TYPES only (erased at build).
+ *
+ * ── THE MATCH (ADR-0009 — an ACTIVE grant): a row matches when ALL hold —
+ *    • `ctg_owning_tenant_uuid` = the resource's owning tenant AND `ctg_type_key` = the object
+ *      type;
+ *    • the grant is ACTIVE: `ctg_status = 'accepted'` (consent completed) AND
+ *      `ctg_revoked_at IS NULL` (not revoked by either side) AND `ctg_expires_at_ms > ?` (not
+ *      expired — bound epoch-ms, timezone-immune) — a revoked/offered/expired grant is NEVER
+ *      returned, so it can never open access even for a heartbeat;
+ *    • the grantee is EITHER this user (`ctg_grantee_kind='user'` AND
+ *      `ctg_grantee_uuid = grantee`) OR one of the grantee's roles (`ctg_grantee_kind='role'`
+ *      AND `ctg_grantee_uuid IN (roleIds)`);
+ *    • the action is in the ceiling — the action-ceiling membership check is left to core's
+ *      grant-evaluator (which re-checks `allowedActions`), but we DO gate scope: an
+ *      `object_type` grant matches any record of the type; a `record` grant matches ONLY when
+ *      the query names the exact `ctg_record_uuid` (a record-scoped row is EXCLUDED for an
+ *      object-type / record-less query so a NULL-compare never spuriously matches).
+ *    ≥1 matching row ⇒ mapped to a {@link CrossTenantGrant} (first match). No matching row ⇒
+ *    `null` (a NORMAL data-absence — no active consent — NOT an error, NOT a lockout).
+ *
+ * ── SCOPE + RECORD-ID HANDLING: `object_type` rows are always eligible; a `record` row is
+ *    eligible ONLY when `query.recordId` is present AND equals `ctg_record_uuid`. When the
+ *    query has NO recordId (an object-type-level question), the SQL restricts to
+ *    `ctg_scope = 'object_type'` so a record row's `ctg_record_uuid` is never compared to a
+ *    bound NULL (which would never match — but we make the intent explicit and avoid the
+ *    accidental all-records reach a `record_uuid = NULL` OR-branch could imply).
+ *
+ * ── ACTION CEILING PARSING: `ctg_allowed_actions` is a JSON column (a JSON array of action-key
+ *    strings). ⚠️ The mariadb driver AUTO-PARSES a JSON column into a JS ARRAY on read, so the
+ *    cell arrives already-parsed — `parseAllowedActions` accepts BOTH an already-parsed array
+ *    (production) and a JSON string (test mocks). A malformed/empty value ⇒ `[]` (an empty
+ *    ceiling permits nothing — fail-closed; core's ceiling check then denies).
+ *
+ * ── EXPIRY (MUST-FIX #1 — timezone immunity): `ctg_expires_at_ms` is a BIGINT epoch-ms column
+ *    (NOT a TIMESTAMP). The active-grant filter compares it `> ?` against a BOUND integer (the
+ *    adapter's `now()` epoch-ms), so it is immune to host-timezone / `NOW()` wall-clock skew (a
+ *    TIMESTAMP + `NOW()` comparison silently kept expired grants alive on a non-UTC host). Mirrors
+ *    the reset-token store's `prt_expires_at_ms` BIGINT precedent.
+ *
+ * ── EMPTY roleIds: guarded — an empty role list must NOT emit `IN ()` (a MariaDB syntax
+ *    error). We omit the role branch entirely when there are no roles, so a role-less grantee
+ *    is matched by its user-grant rows alone.
+ *
+ * ── ADR-0016 (transient-vs-deny): a genuine store outage THROWS
+ *    {@link AuthorizationUnavailableError} (→ 503 retryable) — NEVER a silent `null` that
+ *    would mask an outage as "no grant".
+ *
+ * ── SAFETY: every value (owningTenantId, typeKey, grantee, each roleId, recordId) is BOUND
+ *    as a `?` param — NEVER interpolated. A SQL payload in typeKey/recordId is data, not SQL.
+ *    Mirrors {@link MariaDbRecordShareAdapter}.
+ */
+import type { CrossTenantGrant, CrossTenantGrantPort, CrossTenantGrantQuery } from '@astram/core';
+/** The DI token the adapter is bound under (parity with the share/rule-port tokens). */
+export declare const SHIELD_CROSS_TENANT_GRANT_PORT: unique symbol;
+/** The minimal query surface this adapter needs — a `mariadb` Pool satisfies it. */
+export interface GrantQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/**
+ * The concrete cross-tenant grant adapter. Answers `findActiveGrant` from `cross_tenant_grant`,
+ * matching user- and role-granted, ACCEPTED, unexpired, unrevoked grants for the owning tenant
+ * + object type (+ record for record-scoped).
+ */
+export declare class MariaDbCrossTenantGrantAdapter implements CrossTenantGrantPort {
+    private readonly db;
+    private readonly schema;
+    private readonly now;
+    constructor(db: GrantQueryable, opts?: {
+        schema?: string;
+        nowMs?: () => number;
+    });
+    findActiveGrant(query: CrossTenantGrantQuery): Promise<CrossTenantGrant | null>;
+}
+//# sourceMappingURL=mariadb-cross-tenant-grant-adapter.d.ts.map

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

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

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

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * `MariaDbCrossTenantGrantAdapter` — the concrete {@link CrossTenantGrantPort} for
+ * `@astram/guard`, backed by the `cross_tenant_grant` table (ADR-0009). It answers
+ * `findActiveGrant`: is there an ACTIVE (accepted, unexpired, unrevoked), consented grant
+ * that lets THIS grantee reach THIS owning tenant's object type (+ record) for an action?
+ *
+ * ── WHAT A CROSS-TENANT GRANT IS (ADR-0009): the ONLY sanctioned way (short of root)
+ *    a principal reaches a resource owned by a DIFFERENT tenant. It is an explicit,
+ *    CONSENTED handshake — the OWNING tenant (whose data is reached into) offers it, the
+ *    GRANTEE tenant accepts it, either side may revoke it, and it always expires. It is NEVER
+ *    a root bypass: it carries a HARD, non-wildcard action ceiling and a scope
+ *    (whole object type, or a single record). This adapter only REPORTS an active grant; core's
+ *    `isCrossTenantGrantApplicable` re-checks the ceiling + scope + expiry (defense-in-depth).
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): the `mariadb` driver is a real runtime dependency; core
+ *    defines only the PORT. This adapter is INJECTED into core's wired decision authority. It
+ *    uses `@astram/core` TYPES only (erased at build).
+ *
+ * ── THE MATCH (ADR-0009 — an ACTIVE grant): a row matches when ALL hold —
+ *    • `ctg_owning_tenant_uuid` = the resource's owning tenant AND `ctg_type_key` = the object
+ *      type;
+ *    • the grant is ACTIVE: `ctg_status = 'accepted'` (consent completed) AND
+ *      `ctg_revoked_at IS NULL` (not revoked by either side) AND `ctg_expires_at_ms > ?` (not
+ *      expired — bound epoch-ms, timezone-immune) — a revoked/offered/expired grant is NEVER
+ *      returned, so it can never open access even for a heartbeat;
+ *    • the grantee is EITHER this user (`ctg_grantee_kind='user'` AND
+ *      `ctg_grantee_uuid = grantee`) OR one of the grantee's roles (`ctg_grantee_kind='role'`
+ *      AND `ctg_grantee_uuid IN (roleIds)`);
+ *    • the action is in the ceiling — the action-ceiling membership check is left to core's
+ *      grant-evaluator (which re-checks `allowedActions`), but we DO gate scope: an
+ *      `object_type` grant matches any record of the type; a `record` grant matches ONLY when
+ *      the query names the exact `ctg_record_uuid` (a record-scoped row is EXCLUDED for an
+ *      object-type / record-less query so a NULL-compare never spuriously matches).
+ *    ≥1 matching row ⇒ mapped to a {@link CrossTenantGrant} (first match). No matching row ⇒
+ *    `null` (a NORMAL data-absence — no active consent — NOT an error, NOT a lockout).
+ *
+ * ── SCOPE + RECORD-ID HANDLING: `object_type` rows are always eligible; a `record` row is
+ *    eligible ONLY when `query.recordId` is present AND equals `ctg_record_uuid`. When the
+ *    query has NO recordId (an object-type-level question), the SQL restricts to
+ *    `ctg_scope = 'object_type'` so a record row's `ctg_record_uuid` is never compared to a
+ *    bound NULL (which would never match — but we make the intent explicit and avoid the
+ *    accidental all-records reach a `record_uuid = NULL` OR-branch could imply).
+ *
+ * ── ACTION CEILING PARSING: `ctg_allowed_actions` is a JSON column (a JSON array of action-key
+ *    strings). ⚠️ The mariadb driver AUTO-PARSES a JSON column into a JS ARRAY on read, so the
+ *    cell arrives already-parsed — `parseAllowedActions` accepts BOTH an already-parsed array
+ *    (production) and a JSON string (test mocks). A malformed/empty value ⇒ `[]` (an empty
+ *    ceiling permits nothing — fail-closed; core's ceiling check then denies).
+ *
+ * ── EXPIRY (MUST-FIX #1 — timezone immunity): `ctg_expires_at_ms` is a BIGINT epoch-ms column
+ *    (NOT a TIMESTAMP). The active-grant filter compares it `> ?` against a BOUND integer (the
+ *    adapter's `now()` epoch-ms), so it is immune to host-timezone / `NOW()` wall-clock skew (a
+ *    TIMESTAMP + `NOW()` comparison silently kept expired grants alive on a non-UTC host). Mirrors
+ *    the reset-token store's `prt_expires_at_ms` BIGINT precedent.
+ *
+ * ── EMPTY roleIds: guarded — an empty role list must NOT emit `IN ()` (a MariaDB syntax
+ *    error). We omit the role branch entirely when there are no roles, so a role-less grantee
+ *    is matched by its user-grant rows alone.
+ *
+ * ── ADR-0016 (transient-vs-deny): a genuine store outage THROWS
+ *    {@link AuthorizationUnavailableError} (→ 503 retryable) — NEVER a silent `null` that
+ *    would mask an outage as "no grant".
+ *
+ * ── SAFETY: every value (owningTenantId, typeKey, grantee, each roleId, recordId) is BOUND
+ *    as a `?` param — NEVER interpolated. A SQL payload in typeKey/recordId is data, not SQL.
+ *    Mirrors {@link MariaDbRecordShareAdapter}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbCrossTenantGrantAdapter = exports.SHIELD_CROSS_TENANT_GRANT_PORT = void 0;
+const core_1 = require("@astram/core");
+/** The DI token the adapter is bound under (parity with the share/rule-port tokens). */
+exports.SHIELD_CROSS_TENANT_GRANT_PORT = Symbol('SHIELD_CROSS_TENANT_GRANT_PORT');
+/** Schema the `cross_tenant_grant` table lives in (astram3 ships the migration). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/**
+ * Parse `ctg_allowed_actions` to a `string[]`. ⚠️ The `ctg_allowed_actions` column is a JSON
+ * column, and the mariadb driver AUTO-PARSES it into a JS ARRAY on read — so `raw` is ALREADY an
+ * array in production. A test mock, however, may hand back a JSON STRING. This helper accepts
+ * BOTH:
+ *   • already-parsed array ⇒ filter to strings, return directly (NO `JSON.parse` — parsing an
+ *     array throws, which is exactly the bug that collapsed every ceiling to `[]`);
+ *   • non-empty string ⇒ `JSON.parse`, then filter to strings;
+ *   • anything else (null / empty / non-array-non-string / malformed) ⇒ `[]`.
+ * Non-string members are dropped (fail-closed — a hostile array can never widen the ceiling); an
+ * empty ceiling permits nothing.
+ */
+function parseAllowedActions(raw) {
+    // Production path: the driver already parsed the JSON column into an array.
+    if (Array.isArray(raw)) {
+        return raw.filter((a) => typeof a === 'string');
+    }
+    // Mock / legacy path: a JSON string. Empty/null ⇒ empty ceiling.
+    if (typeof raw === 'string' && raw.length > 0) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((a) => typeof a === 'string');
+    }
+    return [];
+}
+/** Coerce a BIGINT epoch-ms cell (number | bigint | numeric string | null) to a JS number. */
+function toMs(value) {
+    if (value === null)
+        return 0;
+    const ms = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(ms) ? ms : 0;
+}
+/**
+ * The concrete cross-tenant grant adapter. Answers `findActiveGrant` from `cross_tenant_grant`,
+ * matching user- and role-granted, ACCEPTED, unexpired, unrevoked grants for the owning tenant
+ * + object type (+ record for record-scoped).
+ */
+class MariaDbCrossTenantGrantAdapter {
+    db;
+    schema;
+    now;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.schema = opts.schema ?? DEFAULT_SCHEMA;
+        // The expiry filter binds THIS clock's epoch-ms against the BIGINT `ctg_expires_at_ms`
+        // column — timezone-immune (no Date/`NOW()` skew). Injectable for deterministic tests.
+        this.now = opts.nowMs ?? (() => Date.now());
+    }
+    async findActiveGrant(query) {
+        // Grantee predicate: the user grant OR (only when roles exist) a role grant. The role
+        // branch is OMITTED for an empty role list so we NEVER emit `IN ()` (a syntax error).
+        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);
+        }
+        // Scope predicate. An `object_type` grant always matches this type; a `record` grant
+        // matches ONLY when the query names the exact record. When the query has NO recordId, we
+        // restrict to object_type grants (a record row's record_uuid must never be compared to a
+        // bound NULL — it would not match, but we make the intent explicit + never risk a NULL OR).
+        let scopeSql;
+        const scopeParams = [];
+        if (typeof query.recordId === 'string' && query.recordId.length > 0) {
+            scopeSql = `(ctg_scope = 'object_type' OR (ctg_scope = 'record' AND ctg_record_uuid = ?))`;
+            scopeParams.push(query.recordId);
+        }
+        else {
+            scopeSql = `ctg_scope = 'object_type'`;
+        }
+        // The expiry bound is a BIGINT epoch-ms comparison against a BOUND integer (this clock's
+        // now) — timezone-immune (no `NOW()`/Date wall-clock skew, MUST-FIX #1). Param order matches
+        // the SQL below exactly: owning_tenant, type_key, expiry_now, <grantee params>, <scope params>.
+        const nowMs = this.now();
+        const params = [
+            query.owningTenantId,
+            query.typeKey,
+            nowMs,
+            ...granteeParams,
+            ...scopeParams,
+        ];
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT ctg_scope, ctg_type_key, ctg_record_uuid, ctg_allowed_actions, ctg_expires_at_ms` +
+                ` FROM \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` WHERE ctg_owning_tenant_uuid = ?` +
+                `   AND ctg_type_key = ?` +
+                `   AND ctg_status = 'accepted'` +
+                `   AND ctg_revoked_at IS NULL` +
+                `   AND ctg_expires_at_ms > ?` +
+                `   AND (${granteeSql})` +
+                `   AND (${scopeSql})` +
+                // Prefer a record-scoped row over an object_type row when both match, and the
+                // latest-expiring first — deterministic single-match selection.
+                `   ORDER BY (ctg_scope = 'record') DESC, ctg_expires_at_ms DESC` +
+                `   LIMIT 1`, params));
+        }
+        catch (err) {
+            // Genuine store outage — fail closed as retryable (never mask as "no grant").
+            throw new core_1.AuthorizationUnavailableError(`cross_tenant_grant store unavailable for ` +
+                `${query.owningTenantId}:${query.typeKey}:${query.action}: ${err.message}`);
+        }
+        const row = rows[0];
+        if (!row) {
+            // No active consented grant — a NORMAL data-absence (NOT an error). Core reads this as
+            // "no cross-tenant permit" — deny-by-default for the reach.
+            return null;
+        }
+        // Map the row → CrossTenantGrant. Core's grant-evaluator re-checks allowedActions + scope
+        // + expiry; we still filtered status/expiry/revoke/scope in SQL so a revoked/expired/
+        // offered grant is never even returned.
+        const scope = row.ctg_scope === 'record' ? 'record' : 'object_type';
+        const grant = {
+            scope,
+            typeKey: row.ctg_type_key,
+            allowedActions: parseAllowedActions(row.ctg_allowed_actions),
+            // Already epoch-ms (BIGINT column) — just coerce the driver's number/string to a JS number.
+            expiresAtMs: toMs(row.ctg_expires_at_ms),
+            // `recordId` is only present for a record-scoped grant (exactOptionalPropertyTypes:
+            // never write an explicit `undefined` onto the optional field).
+            ...(scope === 'record' && row.ctg_record_uuid !== null
+                ? { recordId: row.ctg_record_uuid }
+                : {}),
+        };
+        return grant;
+    }
+}
+exports.MariaDbCrossTenantGrantAdapter = MariaDbCrossTenantGrantAdapter;

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

@@ -0,0 +1,60 @@
+/**
+ * `MariaDbRecordPermissionRuleAdapter` — the concrete {@link RecordPermissionRulePort}
+ * for `@astram/guard`, backed by the `record_permission_rule` table (design §5.1). It
+ * reads ADMIN rules ONLY and evaluates them for a single record+action, returning the
+ * `{ allow, explicitDeny }` verdict core's record-permit tier composes with the
+ * framework-owned owner BASELINE (design §5.2).
+ *
+ * ── ADMIN-ONLY BY CONSTRUCTION (not by a WHERE filter): the owner/system baselines are
+ *    COMPUTED IN CORE (no rows), so this table is only ever WRITTEN admin-authored rules —
+ *    there is no `provenance` column and every row here is an admin rule. ⚠️ If a future
+ *    change EVER stores non-admin (e.g. `system`) rows in this table, this SELECT MUST add
+ *    a `WHERE rpr_provenance = 'admin'` filter — otherwise a system row would be read as an
+ *    admin rule and could conflict with core's immutable baseline.
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): the `mariadb` driver is a real runtime dependency;
+ *    core defines only the PORT + the immutable owner baseline. This adapter is INJECTED
+ *    into core's wired decision authority. It uses `@astram/core` TYPES only (erased).
+ *
+ * ── THE MODEL (design §5):
+ *    • The OWNER baseline is CORE's job — it is NOT a row here. This table holds ONLY
+ *      admin-authored rules that WIDEN the baseline (e.g. "Company Admins read all
+ *      inspection_reports") or add explicit DENIES (deny-wins). There is no
+ *      `owner`/`system` subject_kind row.
+ *    • NO applicable admin rule ⇒ `{ allow: false, explicitDeny: false }` — a NORMAL
+ *      data-absence (not a lockout): core's owner baseline still permits the owner. An
+ *      empty table ⇒ owner-only access, exactly the safe default.
+ *    • A matching `allow` rule ⇒ `allow: true`. A matching `deny` rule ⇒
+ *      `explicitDeny: true` (deny-wins; core short-circuits the share on it).
+ *
+ * ── ADR-0016 (transient-vs-deny): a genuine store outage THROWS
+ *    {@link AuthorizationUnavailableError} (→ 503 retryable) — NEVER a silent
+ *    `{allow:false,explicitDeny:false}` that would mask an outage as a deny.
+ *
+ * ── 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).
+ */
+import type { RecordPermissionRulePort, RulePermit, RulePermitInput } from '@astram/core';
+/** The DI token the adapter is bound under (parity with the session store token). */
+export declare const SHIELD_RECORD_RULE_PORT: unique symbol;
+/** The minimal query surface this adapter needs — a `mariadb` Pool satisfies it. */
+export interface RuleQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/**
+ * The concrete admin-rule adapter. Reads ADMIN rules for `(tenant, type_key, action|*)`
+ * and folds them into a `{ allow, explicitDeny }` verdict with deny-wins.
+ */
+export declare class MariaDbRecordPermissionRuleAdapter implements RecordPermissionRulePort {
+    private readonly db;
+    private readonly schema;
+    constructor(db: RuleQueryable, opts?: {
+        schema?: string;
+    });
+    evaluate(input: RulePermitInput): Promise<RulePermit>;
+}
+//# sourceMappingURL=mariadb-record-rule-adapter.d.ts.map

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

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

package/dist/authz/mariadb-record-rule-adapter.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * `MariaDbRecordPermissionRuleAdapter` — the concrete {@link RecordPermissionRulePort}
+ * for `@astram/guard`, backed by the `record_permission_rule` table (design §5.1). It
+ * reads ADMIN rules ONLY and evaluates them for a single record+action, returning the
+ * `{ allow, explicitDeny }` verdict core's record-permit tier composes with the
+ * framework-owned owner BASELINE (design §5.2).
+ *
+ * ── ADMIN-ONLY BY CONSTRUCTION (not by a WHERE filter): the owner/system baselines are
+ *    COMPUTED IN CORE (no rows), so this table is only ever WRITTEN admin-authored rules —
+ *    there is no `provenance` column and every row here is an admin rule. ⚠️ If a future
+ *    change EVER stores non-admin (e.g. `system`) rows in this table, this SELECT MUST add
+ *    a `WHERE rpr_provenance = 'admin'` filter — otherwise a system row would be read as an
+ *    admin rule and could conflict with core's immutable baseline.
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): the `mariadb` driver is a real runtime dependency;
+ *    core defines only the PORT + the immutable owner baseline. This adapter is INJECTED
+ *    into core's wired decision authority. It uses `@astram/core` TYPES only (erased).
+ *
+ * ── THE MODEL (design §5):
+ *    • The OWNER baseline is CORE's job — it is NOT a row here. This table holds ONLY
+ *      admin-authored rules that WIDEN the baseline (e.g. "Company Admins read all
+ *      inspection_reports") or add explicit DENIES (deny-wins). There is no
+ *      `owner`/`system` subject_kind row.
+ *    • NO applicable admin rule ⇒ `{ allow: false, explicitDeny: false }` — a NORMAL
+ *      data-absence (not a lockout): core's owner baseline still permits the owner. An
+ *      empty table ⇒ owner-only access, exactly the safe default.
+ *    • A matching `allow` rule ⇒ `allow: true`. A matching `deny` rule ⇒
+ *      `explicitDeny: true` (deny-wins; core short-circuits the share on it).
+ *
+ * ── ADR-0016 (transient-vs-deny): a genuine store outage THROWS
+ *    {@link AuthorizationUnavailableError} (→ 503 retryable) — NEVER a silent
+ *    `{allow:false,explicitDeny:false}` that would mask an outage as a deny.
+ *
+ * ── 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbRecordPermissionRuleAdapter = exports.SHIELD_RECORD_RULE_PORT = void 0;
+const core_1 = require("@astram/core");
+/** The DI token the adapter is bound under (parity with the session store token). */
+exports.SHIELD_RECORD_RULE_PORT = Symbol('SHIELD_RECORD_RULE_PORT');
+/** Schema the `record_permission_rule` table lives in (astram3 ships the migration). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/** Whether the rule's subject matches this principal (role membership / everyone). */
+function subjectMatches(row, input) {
+    const kind = row.rpr_subject_kind;
+    if (kind === 'everyone')
+        return true;
+    if (kind === 'role') {
+        return (row.rpr_subject_value !== null && input.principal.roleIds.includes(row.rpr_subject_value));
+    }
+    // Unknown subject kind → does NOT match (fail-closed).
+    return false;
+}
+/** Resolve a rule value token against the request (e.g. `$actor.id`) or use the literal. */
+function resolveValue(raw, input) {
+    if (raw === '$actor.id')
+        return input.principal.id;
+    if (raw === '$actor.tenant')
+        return input.principal.tenantId;
+    return raw;
+}
+/** The value the rule's field condition tests, read from the record attributes core supplies. */
+function fieldValue(field, input) {
+    return input.attributes?.[field];
+}
+/**
+ * Evaluate a rule's field condition. A rule with NO field (`rpr_field` null) is
+ * UNCONDITIONAL (applies whenever subject+action match). The operator set is a fixed
+ * allow-list; an unknown operator → the condition does NOT hold (fail-closed).
+ */
+function conditionHolds(row, input) {
+    if (row.rpr_field === null)
+        return true; // unconditional
+    const actual = fieldValue(row.rpr_field, input);
+    const expectedRaw = row.rpr_value ?? '';
+    const expected = resolveValue(expectedRaw, input);
+    switch (row.rpr_operator) {
+        case 'equals':
+            return actual === expected;
+        case 'not_equals':
+            return actual !== expected;
+        case 'in': {
+            // comma-separated token list; membership by string comparison.
+            const set = String(expectedRaw)
+                .split(',')
+                .map((s) => s.trim());
+            return set.includes(String(actual));
+        }
+        case 'not_in': {
+            const set = String(expectedRaw)
+                .split(',')
+                .map((s) => s.trim());
+            return !set.includes(String(actual));
+        }
+        default:
+            return false; // unknown operator → fail-closed (rule does not apply)
+    }
+}
+/**
+ * The concrete admin-rule adapter. Reads ADMIN rules for `(tenant, type_key, action|*)`
+ * and folds them into a `{ allow, explicitDeny }` verdict with deny-wins.
+ */
+class MariaDbRecordPermissionRuleAdapter {
+    db;
+    schema;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.schema = opts.schema ?? DEFAULT_SCHEMA;
+    }
+    async evaluate(input) {
+        // tenant scoping: match rows for the resource's tenant OR the global/system baseline
+        // (rpr_tenant_uuid IS NULL). Action match: the exact action OR the rule's `*` wildcard.
+        const tenantId = input.resource.tenantId ?? input.principal.tenantId;
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT 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 (rpr_tenant_uuid = ? OR rpr_tenant_uuid IS NULL)
+            AND (rpr_action = ? OR rpr_action = '*')`, [input.resource.typeKey, tenantId, input.action.key]));
+        }
+        catch (err) {
+            // Genuine store outage — fail closed as retryable (never mask as a deny).
+            throw new core_1.AuthorizationUnavailableError(`record_permission_rule store unavailable for ` +
+                `${input.resource.typeKey}:${input.action.key}: ${err.message}`);
+        }
+        let allow = false;
+        let explicitDeny = false;
+        for (const row of rows) {
+            if (!subjectMatches(row, input))
+                continue;
+            if (!conditionHolds(row, input))
+                continue;
+            if (row.rpr_effect === 'deny') {
+                // Deny-wins — one matching deny is final for this tier.
+                explicitDeny = true;
+            }
+            else if (row.rpr_effect === 'allow') {
+                allow = true;
+            }
+            // any other effect string is ignored (fail-closed — no permit inferred).
+        }
+        // NO applicable admin rule ⇒ {false,false}: a normal data-absence. The CORE owner
+        // baseline still provides the owner permit — this is NOT a lockout.
+        return { allow, explicitDeny };
+    }
+}
+exports.MariaDbRecordPermissionRuleAdapter = MariaDbRecordPermissionRuleAdapter;

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

@@ -0,0 +1,75 @@
+/**
+ * `MariaDbRecordShareAdapter` — the concrete {@link RecordSharePort} for `@astram/guard`,
+ * backed by the `record_share` table (design §6.1). It answers `hasShare`: does the
+ * principal (by id or any of its roles) hold an active per-record share on this
+ * record+action?
+ *
+ * ── WHAT A SHARE IS: an INSTANCE-level grant (one row per record×grantee×action) that
+ *    WIDENS gate 6 (design §6.3). It is a permit SOURCE unioned with the owner baseline +
+ *    admin rules under deny-wins — a share can grant access an absent rule wouldn't, but it
+ *    can NEVER override an explicit deny (core enforces that; this adapter only reports the
+ *    share's presence via a strict boolean).
+ *
+ * ── WHY HERE, NOT CORE (ADR-0003): the `mariadb` driver is a real runtime dependency;
+ *    core defines only the PORT. This adapter is INJECTED into core's wired decision
+ *    authority. It uses `@astram/core` TYPES only (erased).
+ *
+ * ── THE MATCH (design §6.1): a row matches when ALL hold —
+ *    • `rs_type_key` = the object type AND `rs_record_uuid` = the record;
+ *    • the grantee is EITHER this user (`rs_grantee_kind='user'` AND
+ *      `rs_grantee_uuid = principalId`) OR one of the principal's roles
+ *      (`rs_grantee_kind='role'` AND `rs_grantee_uuid IN (roleIds)`);
+ *    • the action matches exactly (`rs_action = action`) OR the row is all-actions
+ *      (`rs_action = '*'`).
+ *    ≥1 matching row ⇒ `true`. No matching row ⇒ `false` (a NORMAL data-absence — no
+ *    share — NOT an error, NOT a lockout: the owner baseline / admin rules still govern).
+ *
+ * ── TENANT ISOLATION (design §6 "cross-tenant share impossible"): the {@link RecordSharePort}
+ *    contract does NOT carry a tenant id (core evaluates same-tenant shares only — a
+ *    cross-tenant reach is governed by the SEPARATE crossTenantGrant port, not a share).
+ *    Isolation is therefore enforced at BOTH ends structurally:
+ *      1. WRITE-TIME (the authoritative bound, {@link RecordShareWriter}): a share row can
+ *         ONLY be created for a record the sharer OWNS in the sharer's OWN tenant, and the
+ *         row is stamped with that tenant (`rs_tenant_uuid`). A share for a foreign tenant's
+ *         record is impossible to create.
+ *      2. READ-TIME (here): `rs_record_uuid` is a GLOBALLY-UNIQUE char36 record uuid — it
+ *         identifies exactly one record in exactly one tenant. Matching on
+ *         `(rs_type_key, rs_record_uuid)` therefore selects that one tenant's row by
+ *         construction; a tenant-A share row can never match a tenant-B record because the
+ *         two records have DIFFERENT uuids. The record uuid IS the tenant discriminator.
+ *    (A future core-contract change that threads the resource tenant into `hasShare` would
+ *    let this add an explicit `rs_tenant_uuid = ?` bound too — flagged for the architect;
+ *    it is a defense-in-depth ADD, not a correctness fix, given uuid uniqueness.)
+ *
+ * ── EMPTY roleIds: guarded — an empty role list must NOT emit `IN ()` (a MariaDB syntax
+ *    error). We omit the role branch entirely when there are no roles, so a role-less
+ *    principal is matched by its user-share rows alone.
+ *
+ * ── ADR-0016 (transient-vs-deny): a genuine store outage THROWS
+ *    {@link AuthorizationUnavailableError} (→ 503 retryable) — NEVER a silent `false` that
+ *    would mask an outage as "no share".
+ *
+ * ── SAFETY: every value (typeKey, recordId, principalId, each roleId, action) is BOUND as
+ *    a `?` param — NEVER interpolated. A SQL payload in typeKey/recordId is data, not SQL.
+ *    Mirrors {@link MariaDbRecordPermissionRuleAdapter}.
+ */
+import type { RecordSharePort } from '@astram/core';
+/** The DI token the adapter is bound under (parity with the rule-port token). */
+export declare const SHIELD_RECORD_SHARE_PORT: unique symbol;
+/** The minimal query surface this adapter needs — a `mariadb` Pool satisfies it. */
+export interface ShareQueryable {
+    query(sql: string, params?: readonly unknown[]): Promise<unknown>;
+}
+/**
+ * The concrete per-record share adapter. Answers `hasShare` from `record_share`, matching
+ * user- and role-granted shares with exact-or-wildcard action.
+ */
+export declare class MariaDbRecordShareAdapter implements RecordSharePort {
+    private readonly db;
+    private readonly schema;
+    constructor(db: ShareQueryable, opts?: {
+        schema?: string;
+    });
+    hasShare(principalId: string, roleIds: readonly string[], typeKey: string, recordId: string, action: string): Promise<boolean>;
+}
+//# sourceMappingURL=mariadb-record-share-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-record-share-adapter.d.ts","sourceRoot":"","sources":["../../src/authz/mariadb-record-share-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAK3E,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;AAOD;;;GAGG;AACH,qBAAa,yBAA0B,YAAW,eAAe;IAC/D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EAAE,EAAE,cAAc,EAAE,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAKxD,QAAQ,CACZ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;CAqCpB"}