@astram/guard 0.2.0 → 0.4.0

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

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * `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}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbRecordShareAdapter = exports.SHIELD_RECORD_SHARE_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_RECORD_SHARE_PORT = Symbol('SHIELD_RECORD_SHARE_PORT');
+/** Schema the `record_share` table lives in (astram3 ships the migration). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/**
+ * The concrete per-record share adapter. Answers `hasShare` from `record_share`, matching
+ * user- and role-granted shares with exact-or-wildcard action.
+ */
+class MariaDbRecordShareAdapter {
+    db;
+    schema;
+    constructor(db, opts = {}) {
+        this.db = db;
+        this.schema = opts.schema ?? DEFAULT_SCHEMA;
+    }
+    async hasShare(principalId, roleIds, typeKey, recordId, action) {
+        // Grantee predicate: the user share OR (only when roles exist) a role share. The role
+        // branch is OMITTED for an empty role list so we NEVER emit `IN ()` (a syntax error).
+        // The IN placeholder list is built from the COUNT of roleIds — never their values.
+        let granteeSql = `(rs_grantee_kind = 'user' AND rs_grantee_uuid = ?)`;
+        const granteeParams = [principalId];
+        if (roleIds.length > 0) {
+            const placeholders = roleIds.map(() => '?').join(', ');
+            granteeSql += ` OR (rs_grantee_kind = 'role' AND rs_grantee_uuid IN (${placeholders}))`;
+            granteeParams.push(...roleIds);
+        }
+        // Param order matches the SQL below exactly: type_key, record_uuid, <grantee params>, action.
+        const params = [typeKey, recordId, ...granteeParams, action];
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT COUNT(*) AS n FROM \`${this.schema}\`.\`record_share\`` +
+                ` WHERE rs_type_key = ?` +
+                `   AND rs_record_uuid = ?` +
+                `   AND (${granteeSql})` +
+                `   AND (rs_action = ? OR rs_action = '*')`, params));
+        }
+        catch (err) {
+            // Genuine store outage — fail closed as retryable (never mask as "no share").
+            throw new core_1.AuthorizationUnavailableError(`record_share store unavailable for ${typeKey}:${recordId}:${action}: ` +
+                `${err.message}`);
+        }
+        // ≥1 matching row ⇒ a share exists ⇒ true. The engine additionally gates the returned
+        // boolean on strict `=== true` (defense-in-depth); we return a genuine boolean.
+        return Number(rows[0]?.n ?? 0) > 0;
+    }
+}
+exports.MariaDbRecordShareAdapter = MariaDbRecordShareAdapter;

package/dist/authz/record-share-cascade.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `makeShareDeleteCascade` — the share-side of record delete (design §6.2: "on record
+ * delete, its `record_share` rows are removed — no orphan grants").
+ *
+ * ⛔ LAYERING (ADR-0003): the ENGINE owns record delete, but it must NOT depend on guard.
+ *    So the engine exposes an OPTIONAL `onRecordDeleted(query, typeKey, recordId, tenantId)`
+ *    hook ({@link RecordEngineDeps}) that it calls AFTER a successful delete of an
+ *    `owned`-type record. This factory builds a guard-owned function of that exact shape
+ *    which the CONSUMER wires into the engine as that hook. The dependency direction is
+ *    consumer → (engine hook) + consumer → (this guard function); the engine never imports
+ *    guard.
+ *
+ * ⛔ SAME-TRANSACTION (mirrors the engine's `AuditPort.record(event, query)` precedent): the
+ *    hook is handed the engine's TX-BOUND query fn per-call and runs the DELETE through THAT
+ *    — NOT a pool/connection it closed over. So the cascade commits/rolls back ATOMICALLY
+ *    with the record delete: a rolled-back delete never leaves the shares destroyed for a
+ *    still-existing record, and there is no separate-connection self-deadlock on the delete's
+ *    row lock. Because the query fn comes from the engine per-call, this factory needs NO
+ *    pool/db of its own.
+ *
+ * ── WHAT IT DOES: DELETE every `record_share` row for `(tenant, type, record)`, tenant-
+ *    scoped, all values BOUND `?` (no interpolation). The engine calls it only for `owned`
+ *    types (the only shareable ones), inside the delete's transaction. Idempotent — a second
+ *    run deletes zero rows.
+ *
+ * ── FAIL-CLOSED: a cascade failure PROPAGATES (throws) — because the engine runs it inside
+ *    the delete's transaction, the throw aborts + rolls back the whole delete. An orphaned
+ *    share pointing at a deleted record is a security-relevant leftover, not something to
+ *    swallow; propagating keeps the record + its shares consistent (both present, or both
+ *    gone).
+ */
+/**
+ * The transaction-bound query fn the engine hands the cascade per-call — the SAME connection
+ * the delete stages used. Structurally matches the engine's `QueryFn` (guard does not import
+ * `@astram/engine`, so it declares the compatible shape here). Params are bound `?` values.
+ */
+export type ShareQueryFn = (sql: string, params?: readonly unknown[]) => Promise<unknown>;
+/**
+ * The hook shape the engine's `onRecordDeleted` expects: it receives the TX-bound query fn
+ * FIRST, then the deleted record's coordinates.
+ */
+export type RecordDeletedHook = (query: ShareQueryFn, typeKey: string, recordId: string, tenantId: string) => Promise<void>;
+/**
+ * Build the delete-cascade function (a {@link RecordDeletedHook}) the consumer wires into
+ * the engine as `onRecordDeleted`. Removes a deleted record's `record_share` rows,
+ * tenant-scoped, THROUGH the engine-supplied transaction query fn (same-tx, atomic). Takes
+ * no pool — the query fn is supplied by the engine on every call.
+ */
+export declare function makeShareDeleteCascade(opts?: {
+    schema?: string;
+}): RecordDeletedHook;
+//# sourceMappingURL=record-share-cascade.d.ts.map

package/dist/authz/record-share-cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-share-cascade.d.ts","sourceRoot":"","sources":["../../src/authz/record-share-cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE1F;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,iBAAiB,CAcxF"}

package/dist/authz/record-share-cascade.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * `makeShareDeleteCascade` — the share-side of record delete (design §6.2: "on record
+ * delete, its `record_share` rows are removed — no orphan grants").
+ *
+ * ⛔ LAYERING (ADR-0003): the ENGINE owns record delete, but it must NOT depend on guard.
+ *    So the engine exposes an OPTIONAL `onRecordDeleted(query, typeKey, recordId, tenantId)`
+ *    hook ({@link RecordEngineDeps}) that it calls AFTER a successful delete of an
+ *    `owned`-type record. This factory builds a guard-owned function of that exact shape
+ *    which the CONSUMER wires into the engine as that hook. The dependency direction is
+ *    consumer → (engine hook) + consumer → (this guard function); the engine never imports
+ *    guard.
+ *
+ * ⛔ SAME-TRANSACTION (mirrors the engine's `AuditPort.record(event, query)` precedent): the
+ *    hook is handed the engine's TX-BOUND query fn per-call and runs the DELETE through THAT
+ *    — NOT a pool/connection it closed over. So the cascade commits/rolls back ATOMICALLY
+ *    with the record delete: a rolled-back delete never leaves the shares destroyed for a
+ *    still-existing record, and there is no separate-connection self-deadlock on the delete's
+ *    row lock. Because the query fn comes from the engine per-call, this factory needs NO
+ *    pool/db of its own.
+ *
+ * ── WHAT IT DOES: DELETE every `record_share` row for `(tenant, type, record)`, tenant-
+ *    scoped, all values BOUND `?` (no interpolation). The engine calls it only for `owned`
+ *    types (the only shareable ones), inside the delete's transaction. Idempotent — a second
+ *    run deletes zero rows.
+ *
+ * ── FAIL-CLOSED: a cascade failure PROPAGATES (throws) — because the engine runs it inside
+ *    the delete's transaction, the throw aborts + rolls back the whole delete. An orphaned
+ *    share pointing at a deleted record is a security-relevant leftover, not something to
+ *    swallow; propagating keeps the record + its shares consistent (both present, or both
+ *    gone).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeShareDeleteCascade = makeShareDeleteCascade;
+/** Schema the `record_share` table lives in. */
+const DEFAULT_SCHEMA = 'shield_authz';
+/**
+ * Build the delete-cascade function (a {@link RecordDeletedHook}) the consumer wires into
+ * the engine as `onRecordDeleted`. Removes a deleted record's `record_share` rows,
+ * tenant-scoped, THROUGH the engine-supplied transaction query fn (same-tx, atomic). Takes
+ * no pool — the query fn is supplied by the engine on every call.
+ */
+function makeShareDeleteCascade(opts = {}) {
+    const schema = opts.schema ?? DEFAULT_SCHEMA;
+    return async (query, typeKey, recordId, tenantId) => {
+        await query(`DELETE FROM \`${schema}\`.\`record_share\`` +
+            ` WHERE rs_tenant_uuid = ? AND rs_type_key = ? AND rs_record_uuid = ?`, [tenantId, typeKey, recordId]);
+    };
+}

package/dist/authz/record-share-writer.d.ts

@@ -0,0 +1,175 @@
+/**
+ * `RecordShareWriter` — the framework-owned WHO-MAY-SHARE write path (design §6.2, the
+ * KEY NEW INVARIANT of Phase 3). Share CREATION — not just evaluation — is framework-
+ * governed here so a share can NEVER expose data the sharer does not own.
+ *
+ * ⛔ THIS IS NOT A CORE PORT. Share evaluation is a core port ({@link RecordSharePort});
+ *    share CREATION is a guard WRITE path (it needs the `mariadb` driver + the type's
+ *    physical schema, neither of which core may touch — ADR-0003). It lives in guard and
+ *    is exposed as a provider the consumer app calls from its share/unshare surface.
+ *
+ * ── THE BOUND (enforced fail-closed, IN ORDER, BEFORE any INSERT):
+ *    1. The type MUST be `owned`. A non-owned type (system / tenant-scoped-only) has no
+ *       single owner, so there is no "sharer owns it" notion — sharing it is meaningless
+ *       and REJECTED. The writer resolves the type's access posture via the injected
+ *       {@link ShareTypeResolver}; an unknown type / non-owned type ⇒ reject.
+ *    2. The record's OWNER is FETCHED from the DB, TENANT-SCOPED
+ *       (`SELECT owner_col FROM table WHERE pk = ? AND tenant_col = ?`). A row that does
+ *       not exist in the SHARER'S tenant ⇒ reject (no cross-tenant reach, and no existence
+ *       oracle beyond "you can't share it"). ⛔ THE OWNER IS ALWAYS FETCHED — never taken
+ *       from caller input (fetch-then-gate discipline, mirrors the engine's fetch-owner
+ *       stage).
+ *    3. The sharer MUST BE THE OWNER: `fetchedOwner === sharerId` (STRICT, non-empty). A
+ *       non-owner — INCLUDING a grantee who merely received a share — can NEVER share.
+ *       Because only the LITERAL owner passes, re-share by grantees is forbidden BY
+ *       CONSTRUCTION (a grantee's id is not the owner id).
+ *    ⛔ The `sharerId` is the AUTHENTICATED PRINCIPAL'S id — the caller MUST supply it from
+ *       the request principal, NOT from a user-controlled body field. The writer never
+ *       trusts an owner id in `input`; it fetches the owner and compares against `sharerId`.
+ *
+ * ── ON PASS: an IDEMPOTENT INSERT into `record_share` (the UNIQUE index on
+ *    (tenant, type, record, grantee_kind, grantee_uuid, action) makes a repeat share of the
+ *    same tuple a no-op via `INSERT ... ON DUPLICATE KEY UPDATE`). `unshare` DELETEs the
+ *    matching row(s). Every share/unshare emits an audit event via the injected
+ *    {@link ShareAuditSink} (best-effort; a sink error never fails the operation). NO raw
+ *    uuid appears in a human-readable audit MESSAGE — ids ride in structured fields only.
+ *
+ * ── TENANT: every write is stamped with, and scoped to, the SHARER'S tenant. A share for
+ *    a foreign tenant's record is impossible — the owner fetch is tenant-scoped, so a
+ *    record outside the sharer's tenant is "not found" ⇒ rejected at step 2.
+ */
+import type { ShareQueryable } from './mariadb-record-share-adapter.js';
+/** The DI token the writer is bound under. */
+export declare const SHIELD_RECORD_SHARE_WRITER: unique symbol;
+/** Who a share is granted to. Mirrors `rs_grantee_kind`. */
+export type ShareGranteeKind = 'user' | 'role';
+/**
+ * The physical shape of an `owned` object type the writer needs to fetch the record's
+ * owner tenant-scoped. The consumer resolves this from the engine's TableRegistry (so guard
+ * never imports `@astram/engine` — ADR-0003 layering). `owned` is the access posture flag
+ * the bound's step 1 checks.
+ */
+export interface ShareTypeInfo {
+    /** Physical table name. */
+    readonly table: string;
+    /** Schema the table lives in (undefined → the engine's default app schema). */
+    readonly schema?: string;
+    /** The single uuid primary-key column (owned types use a uuid PK). */
+    readonly pkColumn: string;
+    /** The `trusted:'actorId'` owner column. */
+    readonly ownerColumn: string;
+    /** The `trusted:'tenantId'` tenant column, if the type has one (owned types normally do). */
+    readonly tenantColumn?: string;
+    /** Whether the type declares `access.owned === true` (only owned types are shareable). */
+    readonly owned: boolean;
+}
+/**
+ * Resolves a type key → its physical share info, or `undefined` if the type is unknown.
+ * The consumer implements this over the engine registry (`isOwned`/`ownerColumn`/
+ * `tenantColumnOf`/`uuidPkColumn`) — keeping guard decoupled from the engine.
+ */
+export interface ShareTypeResolver {
+    resolve(typeKey: string): ShareTypeInfo | undefined;
+}
+/** A share/unshare audit event (structured — ids in fields, NEVER in a rendered message). */
+export interface ShareAuditEvent {
+    /** Always `'record_share'`. */
+    readonly type: 'record_share';
+    /** The specific event key. */
+    readonly action: 'share.created' | 'share.removed';
+    /** Epoch ms the event occurred. */
+    readonly occurredAtMs: number;
+    /** The sharer (owner) principal id — the actor. */
+    readonly actorId: string;
+    /** The tenant the shared record belongs to. */
+    readonly tenantId: string;
+    /** Structured, UUID-free-message detail (the ids live HERE, not in a message string). */
+    readonly attributes: {
+        readonly typeKey: string;
+        readonly recordId: string;
+        readonly granteeKind: ShareGranteeKind;
+        readonly granteeUuid: string;
+        readonly shareAction: string;
+    };
+}
+/** The audit seam the writer emits through. Best-effort — a throw never fails the write. */
+export interface ShareAuditSink {
+    record(event: ShareAuditEvent): Promise<void>;
+}
+/** Input to {@link RecordShareWriter.share} / `.unshare`. */
+export interface ShareInput {
+    /** The SHARER'S tenant — the record must belong to it (owner fetch is scoped to it). */
+    readonly tenantId: string;
+    /** The object type being shared (MUST be `owned`). */
+    readonly typeKey: string;
+    /** The record uuid being shared. */
+    readonly recordId: string;
+    /** Who the share is granted to. */
+    readonly granteeKind: ShareGranteeKind;
+    /** The grantee's user/role uuid. */
+    readonly granteeUuid: string;
+    /** The action granted (a single action, or `'*'` for all actions). */
+    readonly action: string;
+    /**
+     * ⛔ The AUTHENTICATED principal id — supplied by the caller FROM THE REQUEST PRINCIPAL,
+     * never a user-controlled body field. The writer proves this id owns the record before
+     * writing; it never trusts an owner id in the input.
+     */
+    readonly sharerId: string;
+}
+/** Thrown when the who-may-share bound rejects a share/unshare (fail-closed). */
+export declare class ShareNotPermittedError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the share store genuinely cannot answer/write (transient). */
+export declare class ShareStoreUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare class RecordShareWriter {
+    private readonly db;
+    private readonly types;
+    private readonly audit;
+    private readonly schema;
+    private readonly now;
+    constructor(deps: {
+        db: ShareQueryable;
+        types: ShareTypeResolver;
+        /** Optional — absent ⇒ shares are written un-audited (never blocks the write). */
+        audit?: ShareAuditSink;
+        schema?: string;
+        /** Test seam: a deterministic clock (defaults to Date.now). */
+        nowMs?: () => number;
+    });
+    /**
+     * Create a share, enforcing the §6.2 who-may-share bound. Idempotent: re-sharing the
+     * same (tenant, type, record, grantee, action) tuple is a no-op (UNIQUE index +
+     * ON DUPLICATE KEY UPDATE). Emits a `share.created` audit event on success.
+     *
+     * @throws {@link ShareNotPermittedError} if the bound rejects (non-owned type, record
+     *   not in the sharer's tenant, or the sharer is not the owner).
+     * @throws {@link ShareStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    share(input: ShareInput): Promise<void>;
+    /**
+     * Remove a share. The SAME owner bound applies — only the owner of the record may revoke
+     * a share on it (a grantee cannot unshare a record they don't own). DELETEs the matching
+     * row(s); a no-match delete is a benign no-op. Emits `share.removed` on success.
+     */
+    unshare(input: ShareInput): Promise<void>;
+    /**
+     * Enforce the §6.2 who-may-share bound (steps 1–3) and return the resolved type info.
+     * Fetches the record owner tenant-scoped and proves `sharerId` owns it. Throws
+     * {@link ShareNotPermittedError} on any failure (fail-closed).
+     */
+    private assertMayShare;
+    /**
+     * SELECT the owner column for `recordId`, tenant-scoped by `tenantId`. Returns the owner
+     * id string, or `undefined` when the row does not exist in that tenant / the owner is not
+     * a non-empty string (fail-closed — a null/non-string owner never matches a sharerId).
+     */
+    private fetchOwnerTenantScoped;
+    private qualifiedTable;
+    /** Best-effort audit emission — a sink error is swallowed (never fails the write). */
+    private emit;
+}
+//# sourceMappingURL=record-share-writer.d.ts.map

package/dist/authz/record-share-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-share-writer.d.ts","sourceRoot":"","sources":["../../src/authz/record-share-writer.ts"],"names":[],"mappings":"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"}

package/dist/authz/record-share-writer.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * `RecordShareWriter` — the framework-owned WHO-MAY-SHARE write path (design §6.2, the
+ * KEY NEW INVARIANT of Phase 3). Share CREATION — not just evaluation — is framework-
+ * governed here so a share can NEVER expose data the sharer does not own.
+ *
+ * ⛔ THIS IS NOT A CORE PORT. Share evaluation is a core port ({@link RecordSharePort});
+ *    share CREATION is a guard WRITE path (it needs the `mariadb` driver + the type's
+ *    physical schema, neither of which core may touch — ADR-0003). It lives in guard and
+ *    is exposed as a provider the consumer app calls from its share/unshare surface.
+ *
+ * ── THE BOUND (enforced fail-closed, IN ORDER, BEFORE any INSERT):
+ *    1. The type MUST be `owned`. A non-owned type (system / tenant-scoped-only) has no
+ *       single owner, so there is no "sharer owns it" notion — sharing it is meaningless
+ *       and REJECTED. The writer resolves the type's access posture via the injected
+ *       {@link ShareTypeResolver}; an unknown type / non-owned type ⇒ reject.
+ *    2. The record's OWNER is FETCHED from the DB, TENANT-SCOPED
+ *       (`SELECT owner_col FROM table WHERE pk = ? AND tenant_col = ?`). A row that does
+ *       not exist in the SHARER'S tenant ⇒ reject (no cross-tenant reach, and no existence
+ *       oracle beyond "you can't share it"). ⛔ THE OWNER IS ALWAYS FETCHED — never taken
+ *       from caller input (fetch-then-gate discipline, mirrors the engine's fetch-owner
+ *       stage).
+ *    3. The sharer MUST BE THE OWNER: `fetchedOwner === sharerId` (STRICT, non-empty). A
+ *       non-owner — INCLUDING a grantee who merely received a share — can NEVER share.
+ *       Because only the LITERAL owner passes, re-share by grantees is forbidden BY
+ *       CONSTRUCTION (a grantee's id is not the owner id).
+ *    ⛔ The `sharerId` is the AUTHENTICATED PRINCIPAL'S id — the caller MUST supply it from
+ *       the request principal, NOT from a user-controlled body field. The writer never
+ *       trusts an owner id in `input`; it fetches the owner and compares against `sharerId`.
+ *
+ * ── ON PASS: an IDEMPOTENT INSERT into `record_share` (the UNIQUE index on
+ *    (tenant, type, record, grantee_kind, grantee_uuid, action) makes a repeat share of the
+ *    same tuple a no-op via `INSERT ... ON DUPLICATE KEY UPDATE`). `unshare` DELETEs the
+ *    matching row(s). Every share/unshare emits an audit event via the injected
+ *    {@link ShareAuditSink} (best-effort; a sink error never fails the operation). NO raw
+ *    uuid appears in a human-readable audit MESSAGE — ids ride in structured fields only.
+ *
+ * ── TENANT: every write is stamped with, and scoped to, the SHARER'S tenant. A share for
+ *    a foreign tenant's record is impossible — the owner fetch is tenant-scoped, so a
+ *    record outside the sharer's tenant is "not found" ⇒ rejected at step 2.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordShareWriter = exports.ShareStoreUnavailableError = exports.ShareNotPermittedError = exports.SHIELD_RECORD_SHARE_WRITER = void 0;
+const node_crypto_1 = require("node:crypto");
+/** Schema the `record_share` table lives in (astram3 ships the migration). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/** The DI token the writer is bound under. */
+exports.SHIELD_RECORD_SHARE_WRITER = Symbol('SHIELD_RECORD_SHARE_WRITER');
+/** Thrown when the who-may-share bound rejects a share/unshare (fail-closed). */
+class ShareNotPermittedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ShareNotPermittedError';
+    }
+}
+exports.ShareNotPermittedError = ShareNotPermittedError;
+/** Thrown when the share store genuinely cannot answer/write (transient). */
+class ShareStoreUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ShareStoreUnavailableError';
+    }
+}
+exports.ShareStoreUnavailableError = ShareStoreUnavailableError;
+class RecordShareWriter {
+    db;
+    types;
+    audit;
+    schema;
+    now;
+    constructor(deps) {
+        this.db = deps.db;
+        this.types = deps.types;
+        this.audit = deps.audit;
+        this.schema = deps.schema ?? DEFAULT_SCHEMA;
+        this.now = deps.nowMs ?? (() => Date.now());
+    }
+    /**
+     * Create a share, enforcing the §6.2 who-may-share bound. Idempotent: re-sharing the
+     * same (tenant, type, record, grantee, action) tuple is a no-op (UNIQUE index +
+     * ON DUPLICATE KEY UPDATE). Emits a `share.created` audit event on success.
+     *
+     * @throws {@link ShareNotPermittedError} if the bound rejects (non-owned type, record
+     *   not in the sharer's tenant, or the sharer is not the owner).
+     * @throws {@link ShareStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    async share(input) {
+        await this.assertMayShare(input);
+        try {
+            // Idempotent insert — the UNIQUE index makes a repeat tuple a no-op. rs_granted_by
+            // records the sharer (for the who-may-share audit trail).
+            await this.db.query(`INSERT INTO \`${this.schema}\`.\`record_share\`` +
+                ` (rs_uuid, rs_tenant_uuid, rs_type_key, rs_record_uuid,` +
+                `  rs_grantee_kind, rs_grantee_uuid, rs_action, rs_granted_by)` +
+                ` VALUES (?, ?, ?, ?, ?, ?, ?, ?)` +
+                ` ON DUPLICATE KEY UPDATE rs_granted_by = VALUES(rs_granted_by)`, [
+                (0, node_crypto_1.randomUUID)(),
+                input.tenantId,
+                input.typeKey,
+                input.recordId,
+                input.granteeKind,
+                input.granteeUuid,
+                input.action,
+                input.sharerId,
+            ]);
+        }
+        catch (err) {
+            throw new ShareStoreUnavailableError(`record_share write failed for ${input.typeKey}: ${err.message}`);
+        }
+        await this.emit('share.created', input);
+    }
+    /**
+     * Remove a share. The SAME owner bound applies — only the owner of the record may revoke
+     * a share on it (a grantee cannot unshare a record they don't own). DELETEs the matching
+     * row(s); a no-match delete is a benign no-op. Emits `share.removed` on success.
+     */
+    async unshare(input) {
+        await this.assertMayShare(input);
+        try {
+            await this.db.query(`DELETE FROM \`${this.schema}\`.\`record_share\`` +
+                ` WHERE rs_tenant_uuid = ?` +
+                `   AND rs_type_key = ?` +
+                `   AND rs_record_uuid = ?` +
+                `   AND rs_grantee_kind = ?` +
+                `   AND rs_grantee_uuid = ?` +
+                `   AND rs_action = ?`, [
+                input.tenantId,
+                input.typeKey,
+                input.recordId,
+                input.granteeKind,
+                input.granteeUuid,
+                input.action,
+            ]);
+        }
+        catch (err) {
+            throw new ShareStoreUnavailableError(`record_share delete failed for ${input.typeKey}: ${err.message}`);
+        }
+        await this.emit('share.removed', input);
+    }
+    // --- the bound -------------------------------------------------------------
+    /**
+     * Enforce the §6.2 who-may-share bound (steps 1–3) and return the resolved type info.
+     * Fetches the record owner tenant-scoped and proves `sharerId` owns it. Throws
+     * {@link ShareNotPermittedError} on any failure (fail-closed).
+     */
+    async assertMayShare(input) {
+        // Step 1 — the type must be `owned` (and known).
+        const info = this.types.resolve(input.typeKey);
+        if (!info) {
+            throw new ShareNotPermittedError(`type '${input.typeKey}' is not registered — cannot share.`);
+        }
+        if (info.owned !== true) {
+            throw new ShareNotPermittedError(`type '${input.typeKey}' is not an owned type — only owned records are shareable.`);
+        }
+        // A sharerId is mandatory + non-empty (the authenticated principal).
+        if (typeof input.sharerId !== 'string' || input.sharerId.length === 0) {
+            throw new ShareNotPermittedError(`a non-empty sharerId (the authenticated principal) is required.`);
+        }
+        // Step 2 — FETCH the owner tenant-scoped (never trust caller input). A record absent
+        // from the sharer's tenant ⇒ reject (no cross-tenant, no existence oracle).
+        const owner = await this.fetchOwnerTenantScoped(info, input.recordId, input.tenantId);
+        if (owner === undefined) {
+            throw new ShareNotPermittedError(`record not found in tenant — cannot share.`);
+        }
+        // Step 3 — the sharer MUST BE the owner (strict, non-empty). Grantees never pass.
+        if (owner !== input.sharerId) {
+            throw new ShareNotPermittedError(`only the record owner may share it.`);
+        }
+        return info;
+    }
+    /**
+     * SELECT the owner column for `recordId`, tenant-scoped by `tenantId`. Returns the owner
+     * id string, or `undefined` when the row does not exist in that tenant / the owner is not
+     * a non-empty string (fail-closed — a null/non-string owner never matches a sharerId).
+     */
+    async fetchOwnerTenantScoped(info, recordId, tenantId) {
+        const qualified = this.qualifiedTable(info);
+        let where = `\`${info.pkColumn}\` = ?`;
+        const params = [recordId];
+        if (info.tenantColumn) {
+            where += ` AND \`${info.tenantColumn}\` = ?`;
+            params.push(tenantId);
+        }
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT \`${info.ownerColumn}\` AS owner_id FROM ${qualified} WHERE ${where} LIMIT 1`, params));
+        }
+        catch (err) {
+            throw new ShareStoreUnavailableError(`owner fetch failed for ${info.table}: ${err.message}`);
+        }
+        const first = rows[0];
+        return first && typeof first.owner_id === 'string' && first.owner_id.length > 0
+            ? first.owner_id
+            : undefined;
+    }
+    qualifiedTable(info) {
+        return info.schema ? `\`${info.schema}\`.\`${info.table}\`` : `\`${info.table}\``;
+    }
+    /** Best-effort audit emission — a sink error is swallowed (never fails the write). */
+    async emit(action, input) {
+        if (!this.audit)
+            return;
+        const event = {
+            type: 'record_share',
+            action,
+            occurredAtMs: this.now(),
+            actorId: input.sharerId,
+            tenantId: input.tenantId,
+            attributes: {
+                typeKey: input.typeKey,
+                recordId: input.recordId,
+                granteeKind: input.granteeKind,
+                granteeUuid: input.granteeUuid,
+                shareAction: input.action,
+            },
+        };
+        try {
+            await this.audit.record(event);
+        }
+        catch {
+            // Best-effort: an audit failure must not fail a legitimate share/unshare.
+        }
+    }
+}
+exports.RecordShareWriter = RecordShareWriter;