@astram/guard 0.1.1 → 0.3.0

package/dist/authentication/mariadb-credential-resolver.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * `MariaDbCredentialResolver` — the framework-DEFAULT concrete
+ * {@link CredentialResolver} (core port) backed by the single
+ * `shield_identity.identity_credential` table. Resolves an `identityHint`
+ * (username / email) → a {@link ResolvedCredential} the Authentication engine
+ * verifies, or `null` for an unknown hint.
+ *
+ * ⛔ PASSWORD-ONLY BY DESIGN. This default resolver reads ONLY the columns the
+ * framework's shipped seed (`infra/mariadb/init/30-identity-credential.sql`)
+ * actually creates: `ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles`.
+ * It therefore ALWAYS returns `requiredFactors: []` — it does NOT provide an
+ * MFA/second-factor challenge. There is no TOTP column here: the multi-device MFA
+ * model moved authenticator secrets out of `identity_credential` into a separate
+ * `mfa_device` table, which the framework ships only as an UNIMPLEMENTED port.
+ *
+ * MFA / required-factors are a CONSUMER concern, delivered by plugging a custom
+ * `credentialResolver` (+ a concrete `MfaDeviceStore`) via `ShieldModule.forRoot`
+ * — NOT by this default. See astram3's `IdentityCredentialResolver`, which reads
+ * this same table AND folds in the consumer's confirmed authenticators via
+ * `listConfirmedSecrets(mfa_device)` to populate `requiredFactors`. That seam is
+ * the supported way to add MFA-at-login on top of this password-only default.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE TABLE CONTRACT (infra seed `infra/mariadb/init/30-identity-credential.sql`,
+ * in `shield_identity`; the runtime `shield_core` account already has DML there —
+ * no new grant). Columns per spec §3 (prefix `ic_` to match the repo's
+ * session-table convention):
+ *
+ *   identity_credential
+ *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
+ *   │ column                 │ type         │ notes                              │
+ *   ├────────────────────────┼──────────────┼────────────────────────────────────┤
+ *   │ ic_identity_hint       │ VARCHAR(255) │ UNIQUE — the login key (user/email)│
+ *   │ ic_password_hash       │ VARCHAR(255) │ Argon2id encoded hash (verify in)  │
+ *   │ ic_principal_id        │ VARCHAR(255) │ → ResolvedCredential.claims.id     │
+ *   │ ic_tenant_id           │ VARCHAR(255) │ → claims.tenantId                  │
+ *   │ ic_roles               │ JSON / TEXT  │ role-id array → claims.roleIds     │
+ *   │ ic_created_at_ms       │ BIGINT       │ UTC epoch ms (platform sets UTC)   │
+ *   │ ic_updated_at_ms       │ BIGINT       │ UTC epoch ms                       │
+ *   └────────────────────────┴──────────────┴────────────────────────────────────┘
+ *   PRIMARY KEY / UNIQUE on ic_identity_hint (single-row resolve by hint).
+ *   (No `ic_totp_secret` column — MFA secrets live in the consumer's `mfa_device`
+ *    table, resolved by a consumer-plugged resolver, not by this default.)
+ *
+ * The resolver's SELECT must:
+ *   1. `SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles
+ *       FROM shield_identity.identity_credential
+ *       WHERE ic_identity_hint = ? LIMIT 1` (parameterized — NEVER string-built).
+ *   2. Return `null` when NO row matches — the ONLY "not found" signal
+ *      (anti-enumeration; MUST NOT throw for an unknown hint; the engine burns a
+ *      decoy verify on `null` so timing is uniform).
+ *   3. Map a found row → `ResolvedCredential`:
+ *        passwordHash    = ic_password_hash
+ *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
+ *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
+ *        requiredFactors = []   // ALWAYS empty — password-only default (see above)
+ *   4. NEVER log the hash or the raw row.
+ *   5. A store outage (connection/query error) MAY throw — the engine treats a
+ *      resolver throw as fail-closed `authentication_unavailable` (never a leak).
+ *      It MUST NOT convert a throw into a `null` (that would make an outage look
+ *      like "unknown user").
+ *
+ * (`claims.kind` is optional — the Internal adapter defaults an absent kind; add
+ *  an `ic_kind` column later if a deployment needs non-`user` principals. Do NOT
+ *  put any root flag in the row — root is the broker's server-side
+ *  allowlist, never a claim, per core/identity.)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * ADR-0003: the concrete DB lives in guard (Core stays zero-dep). ADR-0013/0014:
+ * reads `shield_identity` via the hot-path `shield_core` account.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MariaDbCredentialResolver = exports.SHIELD_CREDENTIAL_RESOLVER = void 0;
+/** DI token for the resolver — re-exported from the shared auth tokens module. */
+var tokens_js_1 = require("../auth/tokens.js");
+Object.defineProperty(exports, "SHIELD_CREDENTIAL_RESOLVER", { enumerable: true, get: function () { return tokens_js_1.SHIELD_CREDENTIAL_RESOLVER; } });
+/**
+ * Normalize the stored `ic_roles` into a role-id string array. Accepts BOTH:
+ *   - a native `string[]` (the mariadb `JSON`-column driver already parsed it);
+ *   - a JSON string (defensive — a `TEXT` column / `autoJsonMap` disabled), which
+ *     is `JSON.parse`d here.
+ *
+ * A malformed roles value is a DATA-INTEGRITY error, not an unknown user — so this
+ * THROWS (the engine treats a resolver throw as fail-closed
+ * `authentication_unavailable`) rather than silently granting an empty role set (a
+ * silent privilege change) OR crashing later. Anything that is not, after
+ * normalization, an array of strings is rejected the same way.
+ */
+function parseRoleIds(raw, hint) {
+    let value = raw;
+    if (typeof value === 'string') {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            // Never include the raw blob in the message (defensive; it isn't a secret,
+            // but keep the no-detail-leak discipline uniform).
+            throw new Error(`MariaDbCredentialResolver: malformed ic_roles JSON for identity "${hint}" ` +
+                `(data-integrity error — failing closed rather than granting empty roles).`);
+        }
+    }
+    if (!Array.isArray(value) || !value.every((r) => typeof r === 'string')) {
+        throw new Error(`MariaDbCredentialResolver: ic_roles for identity "${hint}" is not an array ` +
+            `of strings (data-integrity error — failing closed).`);
+    }
+    return value;
+}
+/**
+ * The concrete MariaDB-backed {@link CredentialResolver}. Constructed with the
+ * live `shield_core` {@link Pool} (via {@link SHIELD_CREDENTIAL_RESOLVER}'s
+ * factory, which injects {@link SHIELD_DB_POOL}). Stateless per call apart from
+ * the injected pool.
+ *
+ * ⛔ SKELETON: `resolve()` throws until Team A implements the SELECT above.
+ */
+class MariaDbCredentialResolver {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Resolve `identityHint` → {@link ResolvedCredential}, or `null` when no such
+     * principal exists.
+     *
+     * - Parameterized SELECT (`WHERE ic_identity_hint = ? LIMIT 1`) — never
+     *   string-built, so the hint can never inject SQL.
+     * - **No row ⇒ `null`** — the ONLY "not found" signal (anti-enumeration; the
+     *   engine burns a decoy password verify on `null` so an unknown user is
+     *   indistinguishable from a wrong password by content or timing). We do NOT
+     *   throw for an unknown hint.
+     * - A **query/connection ERROR propagates** (rejects) — an outage is NOT an
+     *   unknown user; the engine treats a resolver throw as fail-closed
+     *   `authentication_unavailable`. We never convert an error into `null` (that
+     *   would mask an outage AND make it look like "no such user").
+     * - The password hash is NEVER logged; the raw row is never logged. On success
+     *   it is returned to the engine as a verify input only.
+     * - **Password-only:** `requiredFactors` is ALWAYS `[]`. This default provides
+     *   no second-factor challenge; MFA-at-login is delivered by a consumer-plugged
+     *   `credentialResolver` (+ `MfaDeviceStore`) — see the class doc header and
+     *   astram3's `IdentityCredentialResolver`.
+     */
+    async resolve(identityHint) {
+        // A failed query rejects out of here unchanged (fail-closed): we deliberately
+        // do NOT wrap this in a try/catch that returns null — only a genuine "no row"
+        // maps to null (below), never a store outage.
+        const rows = (await this.pool.query(`SELECT ic_password_hash, ic_principal_id, ic_tenant_id, ic_roles
+         FROM shield_identity.identity_credential
+        WHERE ic_identity_hint = ?
+        LIMIT 1`, [identityHint]));
+        const row = rows[0];
+        // Unknown hint → null (anti-enumeration). MUST NOT throw here.
+        if (!row) {
+            return null;
+        }
+        // Password-only default: no second factor is derived here. MFA is a consumer
+        // concern (custom resolver + MfaDeviceStore), so requiredFactors is always [].
+        const requiredFactors = [];
+        return {
+            passwordHash: row.ic_password_hash,
+            claims: {
+                id: row.ic_principal_id,
+                tenantId: row.ic_tenant_id,
+                roleIds: parseRoleIds(row.ic_roles, identityHint),
+            },
+            requiredFactors,
+        };
+    }
+}
+exports.MariaDbCredentialResolver = MariaDbCredentialResolver;

package/dist/authentication/mariadb-credential-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mariadb-credential-resolver.js","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;;;AASH,kFAAkF;AAClF,+CAA+D;AAAtD,uHAAA,0BAA0B,OAAA;AAkBnC;;;;;;;;;;;GAWG;AACH,SAAS,YAAY,CAAC,GAAY,EAAE,IAAY;IAC9C,IAAI,KAAK,GAAY,GAAG,CAAC;IACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,2EAA2E;YAC3E,mDAAmD;YACnD,MAAM,IAAI,KAAK,CACb,oEAAoE,IAAI,IAAI;gBAC1E,2EAA2E,CAC9E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CACb,qDAAqD,IAAI,oBAAoB;YAC3E,qDAAqD,CACxD,CAAC;IACJ,CAAC;IACD,OAAO,KAA0B,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAa,yBAAyB;IACP;IAA7B,YAA6B,IAAU;QAAV,SAAI,GAAJ,IAAI,CAAM;IAAG,CAAC;IAE3C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,OAAO,CAAC,YAAoB;QAChC,8EAA8E;QAC9E,8EAA8E;QAC9E,8CAA8C;QAC9C,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CACjC;;;gBAGU,EACV,CAAC,YAAY,CAAC,CACf,CAAoB,CAAC;QAEtB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,+DAA+D;QAC/D,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QACd,CAAC;QAED,6EAA6E;QAC7E,+EAA+E;QAC/E,MAAM,eAAe,GAAqB,EAAE,CAAC;QAE7C,OAAO;YACL,YAAY,EAAE,GAAG,CAAC,gBAAgB;YAClC,MAAM,EAAE;gBACN,EAAE,EAAE,GAAG,CAAC,eAAe;gBACvB,QAAQ,EAAE,GAAG,CAAC,YAAY;gBAC1B,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC;aAClD;YACD,eAAe;SAChB,CAAC;IACJ,CAAC;CACF;AAxDD,8DAwDC"}

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":"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"}