@astram/guard 0.2.0 → 0.4.0

package/dist/auth/totp-enrollment.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Phase 4 MFA-enrollment — the **pure TOTP-enrollment helpers**: generate a fresh
+ * base32 TOTP secret, compose the `otpauth://` provisioning URI an authenticator app
+ * scans, and mint one-time recovery codes.
+ *
+ * ── WHY THIS LIVES IN GUARD (not core) ──────────────────────────────────────
+ * Core owns the TOTP *verifier* (`createTotpFactorVerifier`, RFC 6238) but is
+ * ZERO-dep + node-type-free (ADR-0003), so it cannot mint secrets (needs
+ * `node:crypto.randomBytes`) nor build a URI. Enrollment is the *provisioning* side
+ * — it produces the secret the verifier later checks against. Guard owns node
+ * builtins, so the generation lives here. NO core change: the secret this emits is a
+ * plain base32 string, exactly what `createTotpFactorVerifier` decodes.
+ *
+ * ── SECURITY ─────────────────────────────────────────────────────────────────
+ * The secret + recovery codes are credential material: never logged, returned to the
+ * user exactly ONCE at enrollment, and (recovery codes) stored only Argon2-hashed.
+ * These functions are PURE (no I/O, no storage) — the caller decides what to persist.
+ *
+ * ADR-0003: guard owns `node:crypto`; this file has NO framework/HTTP/DB coupling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTotpSecret = generateTotpSecret;
+exports.buildOtpauthUri = buildOtpauthUri;
+exports.generateRecoveryCodes = generateRecoveryCodes;
+const node_crypto_1 = require("node:crypto");
+/** RFC 4648 base32 alphabet — the standard TOTP secret encoding (no padding here). */
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+/**
+ * Bytes of entropy behind a generated TOTP secret. 20 bytes = 160 bits → exactly
+ * 32 base32 characters (20 × 8 / 5 = 32, no remainder → no padding), the RFC 4226
+ * recommended HMAC-SHA1 key length.
+ */
+const SECRET_BYTES = 20;
+/** How many recovery codes to mint by default (industry-standard batch of 10). */
+const DEFAULT_RECOVERY_CODE_COUNT = 10;
+/** Bytes per recovery code → 5 bytes = 10 lowercase hex chars, split into two groups. */
+const RECOVERY_CODE_BYTES = 5;
+/**
+ * Encode raw bytes into an RFC 4648 base32 string (no padding). Used to turn the
+ * random secret into the base32 string an authenticator app + the core verifier both
+ * expect. Pure bit-packing: 5 bits per output char, MSB-first.
+ */
+function base32Encode(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += BASE32_ALPHABET[(value >>> bits) & 0x1f];
+        }
+    }
+    if (bits > 0) {
+        // Flush the remaining <5 bits, left-padded with zeros to a full 5-bit group.
+        out += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+    }
+    return out;
+}
+/**
+ * Generate a fresh, cryptographically-random base32 TOTP secret (160 bits → 32
+ * chars). This is what the user's authenticator app is provisioned with and what the
+ * core verifier later checks presented codes against.
+ */
+function generateTotpSecret() {
+    return base32Encode((0, node_crypto_1.randomBytes)(SECRET_BYTES));
+}
+/**
+ * Build the `otpauth://totp/...` provisioning URI an authenticator app scans (or the
+ * user enters manually). `label` identifies the account (shown in the app), `issuer`
+ * names the service. All three URI components are percent-encoded so a label/issuer
+ * with spaces or `:`/`?`/`&` cannot break the URI. Fixed to the defaults the core
+ * verifier uses (SHA-1, 6 digits, 30s period).
+ */
+function buildOtpauthUri(secret, label, issuer) {
+    const encIssuer = encodeURIComponent(issuer);
+    const encLabel = encodeURIComponent(label);
+    return (`otpauth://totp/${encIssuer}:${encLabel}` +
+        `?secret=${secret}&issuer=${encIssuer}&digits=6&period=30`);
+}
+/**
+ * Mint `count` unique one-time recovery codes (each `xxxxx-xxxxx`, 10 lowercase hex
+ * chars grouped for readability). Returned RAW to the caller ONCE at enrollment; the
+ * store persists them Argon2-hashed. Uniqueness is enforced (a hex collision at this
+ * entropy is astronomically unlikely, but the loop guarantees `count` distinct codes).
+ */
+function generateRecoveryCodes(count = DEFAULT_RECOVERY_CODE_COUNT) {
+    const codes = new Set();
+    while (codes.size < count) {
+        const hex = (0, node_crypto_1.randomBytes)(RECOVERY_CODE_BYTES).toString('hex'); // 10 hex chars
+        codes.add(`${hex.slice(0, 5)}-${hex.slice(5)}`);
+    }
+    return [...codes];
+}

package/dist/authentication/mariadb-credential-resolver.d.ts

@@ -1,20 +1,30 @@
 /**
- * `MariaDbCredentialResolver` — the concrete {@link CredentialResolver} (core
- * port) backed by the `shield_identity.identity_credential` table. Resolves an
- * `identityHint` (username / email) → a {@link ResolvedCredential} the
- * Authentication engine verifies, or `null` for an unknown hint.
+ * `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.
  *
- * ⛔⛔ PHASE 0b PRELUDE SKELETON — the CONTRACT is frozen here; **Team A fills the
- * body**. `resolve()` currently THROWS "not implemented" so a missing Team-A impl
- * fails CLOSED (a broken resolver can NEVER silently authenticate). Do not change
- * the constructor shape (it takes the `SHIELD_DB_POOL`) or the return type — the
- * composition (Team B) and the engine depend on them.
+ * ⛔ 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 Team A must create (infra migration/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):
+ * 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
  *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
@@ -25,16 +35,16 @@
  *   │ 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_totp_secret         │ VARCHAR(255) │ NULLABLE — base32 TOTP secret;     │
- *   │                        │              │ present ⇒ requiredFactors:[totp]   │
  *   │ 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,
- *       ic_totp_secret FROM shield_identity.identity_credential
+ *   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
@@ -43,16 +53,16 @@
  *        passwordHash    = ic_password_hash
  *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
  *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
- *        requiredFactors = ic_totp_secret ? [{ factor:'totp', secret: ic_totp_secret }] : []
- *   4. NEVER log the hash, the TOTP secret, or the raw row.
+ *        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).
- *      Team A does NOT need to swallow it, but MUST NOT convert it into a `null`
- *      (that would make an outage look like "unknown user").
+ *      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 superuser flag in the row — superuser is the broker's server-side
+ *  put any root flag in the row — root is the broker's server-side
  *  allowlist, never a claim, per core/identity.)
  * ─────────────────────────────────────────────────────────────────────────────
  *
@@ -88,8 +98,12 @@ export declare class MariaDbCredentialResolver implements CredentialResolver {
      *   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 and TOTP secret are NEVER logged; the raw row is never
-     *   logged. On success they are returned to the engine as verify inputs only.
+     * - 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`.
      */
     resolve(identityHint: string): Promise<ResolvedCredential | null>;
 }

package/dist/authentication/mariadb-credential-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb-credential-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAwD/D;;;;;;;GAOG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAgCxE"}
+{"version":3,"file":"mariadb-credential-resolver.d.ts","sourceRoot":"","sources":["../../src/authentication/mariadb-credential-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAEtB,kFAAkF;AAClF,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAqD/D;;;;;;;GAOG;AACH,qBAAa,yBAA0B,YAAW,kBAAkB;IACtD,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAEvC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAgCxE"}

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

@@ -1,21 +1,31 @@
 "use strict";
 /**
- * `MariaDbCredentialResolver` — the concrete {@link CredentialResolver} (core
- * port) backed by the `shield_identity.identity_credential` table. Resolves an
- * `identityHint` (username / email) → a {@link ResolvedCredential} the
- * Authentication engine verifies, or `null` for an unknown hint.
+ * `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.
  *
- * ⛔⛔ PHASE 0b PRELUDE SKELETON — the CONTRACT is frozen here; **Team A fills the
- * body**. `resolve()` currently THROWS "not implemented" so a missing Team-A impl
- * fails CLOSED (a broken resolver can NEVER silently authenticate). Do not change
- * the constructor shape (it takes the `SHIELD_DB_POOL`) or the return type — the
- * composition (Team B) and the engine depend on them.
+ * ⛔ 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 Team A must create (infra migration/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):
+ * 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
  *   ┌────────────────────────┬──────────────┬────────────────────────────────────┐
@@ -26,16 +36,16 @@
  *   │ 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_totp_secret         │ VARCHAR(255) │ NULLABLE — base32 TOTP secret;     │
- *   │                        │              │ present ⇒ requiredFactors:[totp]   │
  *   │ 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,
- *       ic_totp_secret FROM shield_identity.identity_credential
+ *   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
@@ -44,16 +54,16 @@
  *        passwordHash    = ic_password_hash
  *        claims          = { id: ic_principal_id, tenantId: ic_tenant_id,
  *                            roleIds: <parsed ic_roles> }   // canonical Internal claims
- *        requiredFactors = ic_totp_secret ? [{ factor:'totp', secret: ic_totp_secret }] : []
- *   4. NEVER log the hash, the TOTP secret, or the raw row.
+ *        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).
- *      Team A does NOT need to swallow it, but MUST NOT convert it into a `null`
- *      (that would make an outage look like "unknown user").
+ *      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 superuser flag in the row — superuser is the broker's server-side
+ *  put any root flag in the row — root is the broker's server-side
  *  allowlist, never a claim, per core/identity.)
  * ─────────────────────────────────────────────────────────────────────────────
  *
@@ -123,14 +133,18 @@ class MariaDbCredentialResolver {
      *   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 and TOTP secret are NEVER logged; the raw row is never
-     *   logged. On success they are returned to the engine as verify inputs only.
+     * - 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, ic_totp_secret
+        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]));
@@ -139,9 +153,9 @@ class MariaDbCredentialResolver {
         if (!row) {
             return null;
         }
-        const requiredFactors = row.ic_totp_secret
-            ? [{ factor: 'totp', secret: row.ic_totp_secret }]
-            : [];
+        // 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: {

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