@astram/guard 0.2.0 → 0.3.0

package/dist/authz/cross-tenant-grant-writer.d.ts

@@ -0,0 +1,259 @@
+/**
+ * `CrossTenantGrantWriter` — the framework-owned WHO-MAY-GRANT write path (ADR-0009, the KEY
+ * NEW INVARIANT of Phase 4). Cross-tenant grant LIFECYCLE — offer / accept / revoke — is
+ * framework-governed here so a grant can NEVER be minted by the party that BENEFITS from it.
+ *
+ * ⛔ THIS IS NOT A CORE PORT. Grant EVALUATION is a core port ({@link CrossTenantGrantPort});
+ *    grant LIFECYCLE is a guard WRITE path (it needs the `mariadb` driver + the consumer's
+ *    identity schema to answer "is X an admin of tenant T", neither of which core may touch —
+ *    ADR-0003). It lives in guard and is exposed as a provider the consumer app's grant surface
+ *    calls (the invitation-email / inbox UX is DEFERRED — ADR-0009's Admin-Console follow-up).
+ *
+ * ── THE CONSENT MODEL (ADR-0009). A cross-tenant grant is TENANT B (the OWNING tenant, whose
+ *    data is reached into) consenting to let TENANT A's principal in. The handshake:
+ *      offer  → an owner/ADMIN in the OWNING tenant (or root) declares the grant
+ *               (object type, scope, action ceiling, expiry) → row created in 'offered' status.
+ *      accept → the GRANTEE tenant must ACCEPT → row moves to 'accepted' → the grant ACTIVATES
+ *               (only now does {@link CrossTenantGrantPort.findActiveGrant} return it).
+ *      revoke → EITHER side (owning tenant admin OR grantee tenant member) may revoke → row
+ *               moves to 'revoked' + `ctg_revoked_at` stamped → immediately inactive.
+ *    ⛔ THE #1 SECURITY CRUX: the grantee's OWN tenant can NEVER unilaterally mint a grant. A
+ *    grant is consent FROM the owning tenant; only an owning-tenant admin may OFFER.
+ *
+ * ── THE BOUNDS (enforced fail-closed, IN ORDER, BEFORE any write):
+ *   • offer:
+ *       1. The offerer MUST hold `'share'` authority in the OWNING tenant (`ctg_owning_tenant_uuid`)
+ *          — verified SERVER-SIDE via the injected {@link GrantAuthorizeFn} (the app's `decide()`);
+ *          rejected otherwise. ⛔ `offeredBy` + `owningTenantId` come from the AUTHENTICATED
+ *          principal context — the caller supplies them from the request principal, NEVER from
+ *          a user-controlled body field for the authority decision.
+ *       2. `allowedActions` MUST be non-empty AND MUST NOT contain a wildcard (`'*'`) — the
+ *          ceiling is a hard, explicit, enumerated set (ADR-0009: "non-wildcard, non-empty").
+ *       3. `expiresAtMs` MUST be a finite FUTURE timestamp — no perpetual / absent / past
+ *          expiry (ADR-0009: "expiry mandatory").
+ *       4. scope='record' REQUIRES a non-empty `recordId`; scope='object_type' FORBIDS one.
+ *     On pass ⇒ INSERT a fresh row in 'offered' status.
+ *   • accept:
+ *       Only a principal who holds `'accept'` authority in the GRANTEE tenant (`ctg_grantee_tenant_uuid`)
+ *       may accept — verified via {@link GrantAuthorizeFn} (the app's `decide()`, which implies
+ *       grantee-tenant membership); and only a grant
+ *       currently in 'offered' status (not already accepted/revoked). On pass ⇒ UPDATE to
+ *       'accepted' + stamp `ctg_accepted_at`. Re-accepting an already-'accepted' grant is a
+ *       benign no-op (idempotent). Accepting a 'revoked' grant is REJECTED (a revoked grant is
+ *       dead — it must be re-offered).
+ *   • revoke:
+ *       EITHER an admin of the OWNING tenant OR a member of the GRANTEE tenant may revoke
+ *       (ADR-0009: "either side may revoke immediately"). A stranger (neither) is REJECTED. On
+ *       pass ⇒ UPDATE to 'revoked' + stamp `ctg_revoked_at`. Re-revoking an already-'revoked'
+ *       grant is a benign no-op (idempotent).
+ *
+ * ── AUDIT ON BOTH TENANTS (ADR-0009: "audited on BOTH tenants as cross-tenant"). Every
+ *    offer/accept/revoke emits ONE {@link GrantAuditEvent} through the injected
+ *    {@link GrantAuditSink} carrying BOTH `owningTenantId` and `granteeTenantId` in STRUCTURED
+ *    fields — so the consumer's sink can record it under each tenant's audit trail. NO raw uuid
+ *    appears in any human-readable MESSAGE (ids ride in structured attributes only). Best-effort
+ *    — a sink throw never fails the lifecycle operation.
+ *
+ * ── FETCH-THEN-GATE (mirrors {@link RecordShareWriter}). The authority decisions (is-admin /
+ *    is-member) are resolved SERVER-SIDE via the injected resolver — NEVER trusted from caller
+ *    input. accept/revoke FETCH the grant's owning+grantee tenants from the row (not from the
+ *    caller) before deciding who may act.
+ */
+import type { GrantQueryable } from './mariadb-cross-tenant-grant-adapter.js';
+/** The DI token the writer is bound under. */
+export declare const SHIELD_CROSS_TENANT_GRANT_WRITER: unique symbol;
+/** Who a grant is granted to (the grantee principal kind). Mirrors `ctg_grantee_kind`. */
+export type GrantGranteeKind = 'user' | 'role';
+/** The two scopes a grant may span (mirrors core's `CrossTenantGrantScope`). */
+export type GrantScope = 'object_type' | 'record';
+/**
+ * The ONE authority question the writer asks: "may this principal perform `action` within
+ * `tenantId`?" — answered by the CONSUMER over its OWN identity + authorization model, so guard
+ * never imports `@astram/engine` or the app (ADR-0003 layering).
+ *
+ * This REPLACES the former `GrantAuthorityResolver` port (the bespoke `isTenantAdmin` /
+ * `isTenantMember` pair). Cross-tenant sharing is NOT a special authority question — it is the
+ * SAME "may this person do this?" question every other action asks. So the app resolves it the
+ * SAME way it resolves everything else: through `decide()`. The app's closure builds the
+ * principal (id → roleIds for `tenantId`, via its in-effect membership→posting read) and calls
+ * its own `decide(principal, {key: action}, {level:'object_type', typeKey:'cross_tenant_grant',
+ * tenantId}, ...)`. Because a principal's permissions are resolved THROUGH their membership,
+ * one `decide()` answers BOTH "are you in this tenant" AND "do you hold the permission" — so no
+ * separate membership check is needed.
+ *
+ *   • offer  → `authorize(offeredBy,  owningTenantId,  'share')`   (act in your own tenant A)
+ *   • accept → `authorize(acceptedBy, granteeTenantId, 'accept')`  (act in your own tenant B)
+ *   • revoke → `authorize(revokedBy, owningTenantId, 'revoke')` OR (…granteeTenantId, 'revoke')
+ *
+ * Returns a genuine boolean; the writer gates on strict `=== true`. A store/authority outage
+ * SHOULD throw (the writer surfaces it as {@link GrantStoreUnavailableError}, a retryable 503) —
+ * never a silent `false` that would mask an outage as "not authorized".
+ */
+export type GrantAuthorizeFn = (principalId: string, tenantId: string, action: 'share' | 'accept' | 'revoke') => Promise<boolean>;
+/** A grant lifecycle audit event (structured — ids in fields, NEVER in a rendered message). */
+export interface GrantAuditEvent {
+    /** Always `'cross_tenant_grant'`. */
+    readonly type: 'cross_tenant_grant';
+    /** The specific lifecycle event. */
+    readonly action: 'grant.offered' | 'grant.accepted' | 'grant.revoked';
+    /** Epoch ms the event occurred. */
+    readonly occurredAtMs: number;
+    /** The principal who performed the action (offerer / accepter / revoker). */
+    readonly actorId: string;
+    /**
+     * The grant's OWNING tenant (whose data is reached into / who consents). Present so the
+     * consumer's sink records the event under this tenant's audit trail too (audit-on-both).
+     */
+    readonly owningTenantId: string;
+    /** The grant's GRANTEE tenant (reaching in). Present so the sink records it under BOTH. */
+    readonly granteeTenantId: string;
+    /** Structured, UUID-free-message detail (the ids live HERE, not in a message string). */
+    readonly attributes: {
+        readonly grantUuid: string;
+        readonly typeKey: string;
+        readonly scope: GrantScope;
+        readonly recordId?: string;
+        readonly granteeKind: GrantGranteeKind;
+        readonly granteeUuid: string;
+        readonly allowedActions: readonly string[];
+    };
+}
+/** The audit seam the writer emits through. Best-effort — a throw never fails the write. */
+export interface GrantAuditSink {
+    record(event: GrantAuditEvent): Promise<void>;
+}
+/** Input to {@link CrossTenantGrantWriter.offer}. */
+export interface OfferGrantInput {
+    /**
+     * ⛔ The OWNING tenant — whose data is reached into / who consents. Supplied from the
+     * AUTHENTICATED principal's context, NEVER a user-controlled body field for the authority
+     * decision. The offerer MUST be an admin of THIS tenant.
+     */
+    readonly owningTenantId: string;
+    /** The GRANTEE tenant — the tenant reaching in. */
+    readonly granteeTenantId: string;
+    /** Who in the grantee tenant the grant is for (a specific user or role). */
+    readonly granteeKind: GrantGranteeKind;
+    /** The grantee user/role uuid (in the grantee tenant). */
+    readonly granteeUuid: string;
+    /** The object type the grant covers. */
+    readonly typeKey: string;
+    /** Whole-object-type, or a single record. */
+    readonly scope: GrantScope;
+    /** REQUIRED iff `scope='record'`; FORBIDDEN for `scope='object_type'`. */
+    readonly recordId?: string;
+    /** The hard action ceiling — non-empty, non-wildcard, enumerated action keys. */
+    readonly allowedActions: readonly string[];
+    /** Mandatory FUTURE expiry (UTC epoch ms). No perpetual/absent/past grants. */
+    readonly expiresAtMs: number;
+    /**
+     * ⛔ The AUTHENTICATED principal id who is offering — supplied from the request principal,
+     * never a user-controlled body field. Proven to be an OWNING-tenant admin before the write.
+     */
+    readonly offeredBy: string;
+}
+/** Input to {@link CrossTenantGrantWriter.accept}. */
+export interface AcceptGrantInput {
+    /** The grant to accept (its uuid). */
+    readonly grantUuid: string;
+    /**
+     * ⛔ The AUTHENTICATED principal accepting — supplied from the request principal. Proven to
+     * be a MEMBER of the grant's GRANTEE tenant before the write.
+     */
+    readonly acceptedBy: string;
+}
+/** Input to {@link CrossTenantGrantWriter.revoke}. */
+export interface RevokeGrantInput {
+    /** The grant to revoke (its uuid). */
+    readonly grantUuid: string;
+    /**
+     * ⛔ The AUTHENTICATED principal revoking — supplied from the request principal. Proven to be
+     * EITHER an admin of the OWNING tenant OR a member of the GRANTEE tenant before the write.
+     */
+    readonly revokedBy: string;
+}
+/** Thrown when the who-may-grant bound rejects an offer/accept/revoke (fail-closed). */
+export declare class GrantNotPermittedError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the grant input is malformed (bad ceiling / expiry / scope). */
+export declare class InvalidGrantError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the grant store genuinely cannot answer/write (transient → 503-retryable). */
+export declare class GrantStoreUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare class CrossTenantGrantWriter {
+    private readonly db;
+    private readonly authorize;
+    private readonly audit;
+    private readonly schema;
+    private readonly now;
+    constructor(deps: {
+        db: GrantQueryable;
+        /**
+         * Answers "may `principalId` perform `action` in `tenantId`?" over the consumer's OWN
+         * authorization model (typically a thin closure that builds the principal and calls the
+         * app's `decide()`). Replaces the former `authority: GrantAuthorityResolver`.
+         */
+        authorize: GrantAuthorizeFn;
+        /** Optional — absent ⇒ lifecycle events are un-audited (never blocks the write). */
+        audit?: GrantAuditSink;
+        schema?: string;
+        /** Test seam: a deterministic clock (defaults to Date.now). */
+        nowMs?: () => number;
+    });
+    /**
+     * OFFER a grant — the OWNING tenant consents to let a grantee tenant's principal in. Enforces
+     * the offer bound (owning-tenant admin, non-empty/non-wildcard ceiling, future expiry, scope
+     * ↔ recordId). Creates a fresh row in 'offered' status. Emits `grant.offered`.
+     *
+     * @returns the new grant's uuid.
+     * @throws {@link GrantNotPermittedError} if the offerer is not an owning-tenant admin.
+     * @throws {@link InvalidGrantError} on a bad ceiling / expiry / scope.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    offer(input: OfferGrantInput): Promise<string>;
+    /**
+     * ACCEPT a grant — the GRANTEE tenant activates it. Only a MEMBER of the grant's grantee
+     * tenant may accept, and only a grant currently 'offered'. Moves it to 'accepted' (the point
+     * at which it becomes ACTIVE for `findActiveGrant`). Re-accepting an 'accepted' grant is a
+     * benign no-op; accepting a 'revoked' grant is rejected. Emits `grant.accepted`.
+     *
+     * @throws {@link GrantNotPermittedError} if the accepter is not a grantee-tenant member, the
+     *   grant does not exist, or it is not in 'offered' status.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    accept(input: AcceptGrantInput): Promise<void>;
+    /**
+     * REVOKE a grant — EITHER an admin of the owning tenant OR a member of the grantee tenant may
+     * revoke (either side, ADR-0009). Moves it to 'revoked' + stamps `ctg_revoked_at` (it becomes
+     * immediately inactive — `findActiveGrant` reads live). Re-revoking a 'revoked' grant is a
+     * benign no-op. Emits `grant.revoked`.
+     *
+     * @throws {@link GrantNotPermittedError} if the revoker is neither an owning-tenant admin nor
+     *   a grantee-tenant member, or the grant does not exist.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    revoke(input: RevokeGrantInput): Promise<void>;
+    /**
+     * Enforce the offer INPUT bounds (ceiling non-empty + non-wildcard, future expiry, scope ↔
+     * recordId). Throws {@link InvalidGrantError} on any failure (fail-closed). The is-admin
+     * authority check is done separately (it needs I/O).
+     */
+    private assertValidOffer;
+    /**
+     * Run an authority resolver call, translating a store outage into
+     * {@link GrantStoreUnavailableError} (retryable) — a resolver that THROWS is an outage, not a
+     * "not authorized". A resolver returning `false` is a legitimate deny (handled by the caller).
+     */
+    private resolveAuthority;
+    /** Fetch a grant's lifecycle row (tenants + status) by uuid — never trusts caller-supplied tenants. */
+    private fetchGrant;
+    /** Emit an offer event (fields already assembled). Best-effort. */
+    private emit;
+    /** Emit an accept/revoke event, deriving structured attributes from the fetched row. */
+    private emitFromRow;
+}
+//# sourceMappingURL=cross-tenant-grant-writer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cross-tenant-grant-writer.d.ts","sourceRoot":"","sources":["../../src/authz/cross-tenant-grant-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAK9E,8CAA8C;AAC9C,eAAO,MAAM,gCAAgC,eAA6C,CAAC;AAE3F,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,QAAQ,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,KAClC,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,GAAG,eAAe,CAAC;IACtE,mCAAmC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;QACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;KAC5C,CAAC;CACH;AAED,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wFAAwF;AACxF,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,+EAA+E;AAC/E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,6FAA6F;AAC7F,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAqCD,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,EAAE;QAChB,EAAE,EAAE,cAAc,CAAC;QACnB;;;;WAIG;QACH,SAAS,EAAE,gBAAgB,CAAC;QAC5B,oFAAoF;QACpF,KAAK,CAAC,EAAE,cAAc,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,+DAA+D;QAC/D,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;KACtB;IAQD;;;;;;;;;OASG;IACG,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAuEpD;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDpD;;;;;;;;;OASG;IACG,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqDpD;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IA8CxB;;;;OAIG;YACW,gBAAgB;IAU9B,uGAAuG;YACzF,UAAU;IAqBxB,mEAAmE;YACrD,IAAI;IAalB,wFAAwF;YAC1E,WAAW;CA0B1B"}

package/dist/authz/cross-tenant-grant-writer.js

@@ -0,0 +1,397 @@
+"use strict";
+/**
+ * `CrossTenantGrantWriter` — the framework-owned WHO-MAY-GRANT write path (ADR-0009, the KEY
+ * NEW INVARIANT of Phase 4). Cross-tenant grant LIFECYCLE — offer / accept / revoke — is
+ * framework-governed here so a grant can NEVER be minted by the party that BENEFITS from it.
+ *
+ * ⛔ THIS IS NOT A CORE PORT. Grant EVALUATION is a core port ({@link CrossTenantGrantPort});
+ *    grant LIFECYCLE is a guard WRITE path (it needs the `mariadb` driver + the consumer's
+ *    identity schema to answer "is X an admin of tenant T", neither of which core may touch —
+ *    ADR-0003). It lives in guard and is exposed as a provider the consumer app's grant surface
+ *    calls (the invitation-email / inbox UX is DEFERRED — ADR-0009's Admin-Console follow-up).
+ *
+ * ── THE CONSENT MODEL (ADR-0009). A cross-tenant grant is TENANT B (the OWNING tenant, whose
+ *    data is reached into) consenting to let TENANT A's principal in. The handshake:
+ *      offer  → an owner/ADMIN in the OWNING tenant (or root) declares the grant
+ *               (object type, scope, action ceiling, expiry) → row created in 'offered' status.
+ *      accept → the GRANTEE tenant must ACCEPT → row moves to 'accepted' → the grant ACTIVATES
+ *               (only now does {@link CrossTenantGrantPort.findActiveGrant} return it).
+ *      revoke → EITHER side (owning tenant admin OR grantee tenant member) may revoke → row
+ *               moves to 'revoked' + `ctg_revoked_at` stamped → immediately inactive.
+ *    ⛔ THE #1 SECURITY CRUX: the grantee's OWN tenant can NEVER unilaterally mint a grant. A
+ *    grant is consent FROM the owning tenant; only an owning-tenant admin may OFFER.
+ *
+ * ── THE BOUNDS (enforced fail-closed, IN ORDER, BEFORE any write):
+ *   • offer:
+ *       1. The offerer MUST hold `'share'` authority in the OWNING tenant (`ctg_owning_tenant_uuid`)
+ *          — verified SERVER-SIDE via the injected {@link GrantAuthorizeFn} (the app's `decide()`);
+ *          rejected otherwise. ⛔ `offeredBy` + `owningTenantId` come from the AUTHENTICATED
+ *          principal context — the caller supplies them from the request principal, NEVER from
+ *          a user-controlled body field for the authority decision.
+ *       2. `allowedActions` MUST be non-empty AND MUST NOT contain a wildcard (`'*'`) — the
+ *          ceiling is a hard, explicit, enumerated set (ADR-0009: "non-wildcard, non-empty").
+ *       3. `expiresAtMs` MUST be a finite FUTURE timestamp — no perpetual / absent / past
+ *          expiry (ADR-0009: "expiry mandatory").
+ *       4. scope='record' REQUIRES a non-empty `recordId`; scope='object_type' FORBIDS one.
+ *     On pass ⇒ INSERT a fresh row in 'offered' status.
+ *   • accept:
+ *       Only a principal who holds `'accept'` authority in the GRANTEE tenant (`ctg_grantee_tenant_uuid`)
+ *       may accept — verified via {@link GrantAuthorizeFn} (the app's `decide()`, which implies
+ *       grantee-tenant membership); and only a grant
+ *       currently in 'offered' status (not already accepted/revoked). On pass ⇒ UPDATE to
+ *       'accepted' + stamp `ctg_accepted_at`. Re-accepting an already-'accepted' grant is a
+ *       benign no-op (idempotent). Accepting a 'revoked' grant is REJECTED (a revoked grant is
+ *       dead — it must be re-offered).
+ *   • revoke:
+ *       EITHER an admin of the OWNING tenant OR a member of the GRANTEE tenant may revoke
+ *       (ADR-0009: "either side may revoke immediately"). A stranger (neither) is REJECTED. On
+ *       pass ⇒ UPDATE to 'revoked' + stamp `ctg_revoked_at`. Re-revoking an already-'revoked'
+ *       grant is a benign no-op (idempotent).
+ *
+ * ── AUDIT ON BOTH TENANTS (ADR-0009: "audited on BOTH tenants as cross-tenant"). Every
+ *    offer/accept/revoke emits ONE {@link GrantAuditEvent} through the injected
+ *    {@link GrantAuditSink} carrying BOTH `owningTenantId` and `granteeTenantId` in STRUCTURED
+ *    fields — so the consumer's sink can record it under each tenant's audit trail. NO raw uuid
+ *    appears in any human-readable MESSAGE (ids ride in structured attributes only). Best-effort
+ *    — a sink throw never fails the lifecycle operation.
+ *
+ * ── FETCH-THEN-GATE (mirrors {@link RecordShareWriter}). The authority decisions (is-admin /
+ *    is-member) are resolved SERVER-SIDE via the injected resolver — NEVER trusted from caller
+ *    input. accept/revoke FETCH the grant's owning+grantee tenants from the row (not from the
+ *    caller) before deciding who may act.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossTenantGrantWriter = exports.GrantStoreUnavailableError = exports.InvalidGrantError = exports.GrantNotPermittedError = exports.SHIELD_CROSS_TENANT_GRANT_WRITER = void 0;
+const node_crypto_1 = require("node:crypto");
+/** Schema the `cross_tenant_grant` table lives in (astram3 ships the migration). */
+const DEFAULT_SCHEMA = 'shield_authz';
+/** The DI token the writer is bound under. */
+exports.SHIELD_CROSS_TENANT_GRANT_WRITER = Symbol('SHIELD_CROSS_TENANT_GRANT_WRITER');
+/** Thrown when the who-may-grant bound rejects an offer/accept/revoke (fail-closed). */
+class GrantNotPermittedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GrantNotPermittedError';
+    }
+}
+exports.GrantNotPermittedError = GrantNotPermittedError;
+/** Thrown when the grant input is malformed (bad ceiling / expiry / scope). */
+class InvalidGrantError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidGrantError';
+    }
+}
+exports.InvalidGrantError = InvalidGrantError;
+/** Thrown when the grant store genuinely cannot answer/write (transient → 503-retryable). */
+class GrantStoreUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GrantStoreUnavailableError';
+    }
+}
+exports.GrantStoreUnavailableError = GrantStoreUnavailableError;
+/**
+ * Parse a `ctg_allowed_actions` cell to a `string[]`, accepting BOTH an already-parsed array
+ * (production — the mariadb driver auto-parses the JSON column) and a JSON string (test mocks).
+ * Anything else / malformed ⇒ `[]` (fail-closed). Shared shape with the adapter's parser.
+ */
+function parseCeiling(raw) {
+    if (Array.isArray(raw)) {
+        return raw.filter((a) => typeof a === 'string');
+    }
+    if (typeof raw === 'string' && raw.length > 0) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                return parsed.filter((a) => typeof a === 'string');
+        }
+        catch {
+            return [];
+        }
+    }
+    return [];
+}
+class CrossTenantGrantWriter {
+    db;
+    authorize;
+    audit;
+    schema;
+    now;
+    constructor(deps) {
+        this.db = deps.db;
+        this.authorize = deps.authorize;
+        this.audit = deps.audit;
+        this.schema = deps.schema ?? DEFAULT_SCHEMA;
+        this.now = deps.nowMs ?? (() => Date.now());
+    }
+    /**
+     * OFFER a grant — the OWNING tenant consents to let a grantee tenant's principal in. Enforces
+     * the offer bound (owning-tenant admin, non-empty/non-wildcard ceiling, future expiry, scope
+     * ↔ recordId). Creates a fresh row in 'offered' status. Emits `grant.offered`.
+     *
+     * @returns the new grant's uuid.
+     * @throws {@link GrantNotPermittedError} if the offerer is not an owning-tenant admin.
+     * @throws {@link InvalidGrantError} on a bad ceiling / expiry / scope.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    async offer(input) {
+        // (2)–(4) input validity BEFORE any authority I/O (cheap, deterministic, fail-closed).
+        this.assertValidOffer(input);
+        // (1) THE CRUX: the offerer MUST be an admin of the OWNING tenant — resolved SERVER-SIDE
+        // (never trusted from input). The grantee's own tenant can never mint a grant, because the
+        // offer authority is checked against the OWNING tenant, not the grantee tenant.
+        if (typeof input.offeredBy !== 'string' || input.offeredBy.length === 0) {
+            throw new GrantNotPermittedError(`a non-empty offeredBy (the authenticated principal) is required.`);
+        }
+        const mayShare = await this.resolveAuthority(() => this.authorize(input.offeredBy, input.owningTenantId, 'share'));
+        if (mayShare !== true) {
+            throw new GrantNotPermittedError(`principal lacks 'share' authority in the owning tenant — cannot offer a cross-tenant grant.`);
+        }
+        const grantUuid = (0, node_crypto_1.randomUUID)();
+        // Store the ceiling as a JSON array (text — the JSON column accepts a valid JSON string).
+        const allowedActionsJson = JSON.stringify([...input.allowedActions]);
+        try {
+            await this.db.query(`INSERT INTO \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` (ctg_uuid, ctg_owning_tenant_uuid, ctg_grantee_tenant_uuid,` +
+                `  ctg_grantee_kind, ctg_grantee_uuid, ctg_type_key, ctg_scope, ctg_record_uuid,` +
+                `  ctg_allowed_actions, ctg_status, ctg_offered_by, ctg_expires_at_ms)` +
+                ` VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'offered', ?, ?)`, [
+                grantUuid,
+                input.owningTenantId,
+                input.granteeTenantId,
+                input.granteeKind,
+                input.granteeUuid,
+                input.typeKey,
+                input.scope,
+                input.scope === 'record' ? (input.recordId ?? null) : null,
+                allowedActionsJson,
+                input.offeredBy,
+                // Expiry stored as BIGINT epoch-ms (timezone-immune — MUST-FIX #1). Bind the integer
+                // directly; NEVER `new Date(...)` (which serializes to a TZ-skewed wall-clock TIMESTAMP).
+                input.expiresAtMs,
+            ]);
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant offer write failed for ${input.typeKey}: ${err.message}`);
+        }
+        await this.emit('grant.offered', {
+            occurredAtMs: this.now(),
+            actorId: input.offeredBy,
+            owningTenantId: input.owningTenantId,
+            granteeTenantId: input.granteeTenantId,
+            attributes: {
+                grantUuid,
+                typeKey: input.typeKey,
+                scope: input.scope,
+                ...(input.scope === 'record' && input.recordId ? { recordId: input.recordId } : {}),
+                granteeKind: input.granteeKind,
+                granteeUuid: input.granteeUuid,
+                allowedActions: [...input.allowedActions],
+            },
+        });
+        return grantUuid;
+    }
+    /**
+     * ACCEPT a grant — the GRANTEE tenant activates it. Only a MEMBER of the grant's grantee
+     * tenant may accept, and only a grant currently 'offered'. Moves it to 'accepted' (the point
+     * at which it becomes ACTIVE for `findActiveGrant`). Re-accepting an 'accepted' grant is a
+     * benign no-op; accepting a 'revoked' grant is rejected. Emits `grant.accepted`.
+     *
+     * @throws {@link GrantNotPermittedError} if the accepter is not a grantee-tenant member, the
+     *   grant does not exist, or it is not in 'offered' status.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    async accept(input) {
+        const row = await this.fetchGrant(input.grantUuid);
+        if (!row) {
+            throw new GrantNotPermittedError(`grant not found — cannot accept.`); // no uuid in message
+        }
+        if (typeof input.acceptedBy !== 'string' || input.acceptedBy.length === 0) {
+            throw new GrantNotPermittedError(`a non-empty acceptedBy (the authenticated principal) is required.`);
+        }
+        // Idempotent no-op: already accepted ⇒ nothing to do (but still verify the actor has
+        // 'accept' authority in the grantee tenant, so a stranger cannot probe/replay). A principal
+        // only holds a grantee-tenant permission THROUGH membership there, so this one check covers
+        // both "is a member" and "may accept".
+        const mayAccept = await this.resolveAuthority(() => this.authorize(input.acceptedBy, row.ctg_grantee_tenant_uuid, 'accept'));
+        if (mayAccept !== true) {
+            throw new GrantNotPermittedError(`principal lacks 'accept' authority in the grantee tenant — cannot accept this grant.`);
+        }
+        if (row.ctg_status === 'accepted') {
+            return; // benign idempotent no-op
+        }
+        if (row.ctg_status !== 'offered') {
+            // 'revoked' (dead) — must be re-offered, not re-accepted.
+            throw new GrantNotPermittedError(`grant is not in an offerable state — cannot accept.`);
+        }
+        try {
+            await this.db.query(`UPDATE \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` SET ctg_status = 'accepted', ctg_accepted_at = ?` +
+                ` WHERE ctg_uuid = ? AND ctg_status = 'offered'`, [new Date(this.now()), input.grantUuid]);
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant accept write failed: ${err.message}`);
+        }
+        await this.emitFromRow('grant.accepted', row, input.grantUuid, input.acceptedBy);
+    }
+    /**
+     * REVOKE a grant — EITHER an admin of the owning tenant OR a member of the grantee tenant may
+     * revoke (either side, ADR-0009). Moves it to 'revoked' + stamps `ctg_revoked_at` (it becomes
+     * immediately inactive — `findActiveGrant` reads live). Re-revoking a 'revoked' grant is a
+     * benign no-op. Emits `grant.revoked`.
+     *
+     * @throws {@link GrantNotPermittedError} if the revoker is neither an owning-tenant admin nor
+     *   a grantee-tenant member, or the grant does not exist.
+     * @throws {@link GrantStoreUnavailableError} if the store cannot be reached (transient).
+     */
+    async revoke(input) {
+        const row = await this.fetchGrant(input.grantUuid);
+        if (!row) {
+            throw new GrantNotPermittedError(`grant not found — cannot revoke.`); // no uuid in message
+        }
+        if (typeof input.revokedBy !== 'string' || input.revokedBy.length === 0) {
+            throw new GrantNotPermittedError(`a non-empty revokedBy (the authenticated principal) is required.`);
+        }
+        // Either side may revoke (ADR-0009): 'revoke' authority in the OWNING tenant OR in the
+        // GRANTEE tenant. Check owning-side first, then grantee-side; a principal with neither is a
+        // stranger and is rejected. (Each check is a `decide()` in that tenant, so it implies
+        // membership there too.)
+        const mayRevokeOwning = await this.resolveAuthority(() => this.authorize(input.revokedBy, row.ctg_owning_tenant_uuid, 'revoke'));
+        let permitted = mayRevokeOwning === true;
+        if (!permitted) {
+            const mayRevokeGrantee = await this.resolveAuthority(() => this.authorize(input.revokedBy, row.ctg_grantee_tenant_uuid, 'revoke'));
+            permitted = mayRevokeGrantee === true;
+        }
+        if (!permitted) {
+            throw new GrantNotPermittedError(`principal lacks 'revoke' authority in either the owning or grantee tenant — cannot revoke this grant.`);
+        }
+        if (row.ctg_status === 'revoked') {
+            return; // benign idempotent no-op
+        }
+        try {
+            await this.db.query(`UPDATE \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` SET ctg_status = 'revoked', ctg_revoked_at = ?` +
+                ` WHERE ctg_uuid = ? AND ctg_status <> 'revoked'`, [new Date(this.now()), input.grantUuid]);
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant revoke write failed: ${err.message}`);
+        }
+        await this.emitFromRow('grant.revoked', row, input.grantUuid, input.revokedBy);
+    }
+    // --- validity + authority helpers ------------------------------------------
+    /**
+     * Enforce the offer INPUT bounds (ceiling non-empty + non-wildcard, future expiry, scope ↔
+     * recordId). Throws {@link InvalidGrantError} on any failure (fail-closed). The is-admin
+     * authority check is done separately (it needs I/O).
+     */
+    assertValidOffer(input) {
+        // Ceiling: non-empty AND non-wildcard AND all-strings. A wildcard `'*'` is a hard reject —
+        // the ceiling must be an explicit enumerated set (ADR-0009).
+        const actions = input.allowedActions;
+        if (!Array.isArray(actions) || actions.length === 0) {
+            throw new InvalidGrantError(`allowedActions must be a non-empty set.`);
+        }
+        for (const a of actions) {
+            if (typeof a !== 'string' || a.length === 0) {
+                throw new InvalidGrantError(`allowedActions must contain only non-empty action keys.`);
+            }
+            if (a === '*') {
+                throw new InvalidGrantError(`allowedActions must not contain a wildcard '*' — the ceiling is explicit.`);
+            }
+        }
+        // Expiry: a finite FUTURE timestamp (mandatory, no perpetual/absent/past).
+        if (typeof input.expiresAtMs !== 'number' || !Number.isFinite(input.expiresAtMs)) {
+            throw new InvalidGrantError(`expiresAtMs must be a finite timestamp.`);
+        }
+        if (input.expiresAtMs <= this.now()) {
+            throw new InvalidGrantError(`expiresAtMs must be in the future — no perpetual/expired grants.`);
+        }
+        // Scope ↔ recordId: 'record' requires one; 'object_type' forbids one.
+        if (input.scope === 'record') {
+            if (typeof input.recordId !== 'string' || input.recordId.length === 0) {
+                throw new InvalidGrantError(`a record-scoped grant requires a non-empty recordId.`);
+            }
+        }
+        else if (input.scope === 'object_type') {
+            if (input.recordId !== undefined) {
+                throw new InvalidGrantError(`an object_type-scoped grant must not carry a recordId.`);
+            }
+        }
+        else {
+            throw new InvalidGrantError(`scope must be 'object_type' or 'record'.`);
+        }
+        // Tenant sanity: both tenants non-empty (a grant spans two DISTINCT tenants).
+        if (typeof input.owningTenantId !== 'string' || input.owningTenantId.length === 0) {
+            throw new InvalidGrantError(`a non-empty owningTenantId is required.`);
+        }
+        if (typeof input.granteeTenantId !== 'string' || input.granteeTenantId.length === 0) {
+            throw new InvalidGrantError(`a non-empty granteeTenantId is required.`);
+        }
+    }
+    /**
+     * Run an authority resolver call, translating a store outage into
+     * {@link GrantStoreUnavailableError} (retryable) — a resolver that THROWS is an outage, not a
+     * "not authorized". A resolver returning `false` is a legitimate deny (handled by the caller).
+     */
+    async resolveAuthority(fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`grant authority resolver unavailable: ${err.message}`);
+        }
+    }
+    /** Fetch a grant's lifecycle row (tenants + status) by uuid — never trusts caller-supplied tenants. */
+    async fetchGrant(grantUuid) {
+        let rows;
+        try {
+            rows = (await this.db.query(`SELECT ctg_owning_tenant_uuid, ctg_grantee_tenant_uuid, ctg_grantee_kind,` +
+                `       ctg_grantee_uuid, ctg_type_key, ctg_scope, ctg_record_uuid,` +
+                `       ctg_allowed_actions, ctg_status` +
+                ` FROM \`${this.schema}\`.\`cross_tenant_grant\`` +
+                ` WHERE ctg_uuid = ? LIMIT 1`, [grantUuid]));
+        }
+        catch (err) {
+            throw new GrantStoreUnavailableError(`cross_tenant_grant read failed: ${err.message}`);
+        }
+        return rows[0];
+    }
+    // --- audit -----------------------------------------------------------------
+    /** Emit an offer event (fields already assembled). Best-effort. */
+    async emit(action, detail) {
+        if (!this.audit)
+            return;
+        const event = { type: 'cross_tenant_grant', action, ...detail };
+        try {
+            await this.audit.record(event);
+        }
+        catch {
+            // Best-effort: an audit failure must not fail a legitimate lifecycle operation.
+        }
+    }
+    /** Emit an accept/revoke event, deriving structured attributes from the fetched row. */
+    async emitFromRow(action, row, grantUuid, actorId) {
+        if (!this.audit)
+            return;
+        const scope = row.ctg_scope === 'record' ? 'record' : 'object_type';
+        // Array-aware (driver auto-parses the JSON column) — NEVER a bare JSON.parse on an array.
+        const allowedActions = parseCeiling(row.ctg_allowed_actions);
+        await this.emit(action, {
+            occurredAtMs: this.now(),
+            actorId,
+            owningTenantId: row.ctg_owning_tenant_uuid,
+            granteeTenantId: row.ctg_grantee_tenant_uuid,
+            attributes: {
+                grantUuid,
+                typeKey: row.ctg_type_key,
+                scope,
+                ...(scope === 'record' && row.ctg_record_uuid ? { recordId: row.ctg_record_uuid } : {}),
+                granteeKind: row.ctg_grantee_kind === 'role' ? 'role' : 'user',
+                granteeUuid: row.ctg_grantee_uuid,
+                allowedActions,
+            },
+        });
+    }
+}
+exports.CrossTenantGrantWriter = CrossTenantGrantWriter;