@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/auth/role_grant_offer_queries.js

@@ -0,0 +1,533 @@
+/**
+ * Role grant offer database queries.
+ *
+ * Covers the offer side of the consentful-role-grants flow: create (with
+ * re-offer upsert), decline, retract, list, find-pending, sweep-expired,
+ * and the atomic `query_accept_offer` that bridges offer → role_grant.
+ *
+ * IDOR guards are expressed in each helper's signature — decline/accept
+ * require the recipient's `to_account_id`, retract requires the grantor's
+ * `from_actor_id`.
+ *
+ * @module
+ */
+import { assert_row } from '../db/assert_row.js';
+import { ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN, ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID, } from './role_grant_offer_schema.js';
+import { query_audit_log } from './audit_log_queries.js';
+/**
+ * Error thrown by offer-lifecycle queries when the offer is in a non-pending
+ * state (accepted / declined / retracted / superseded) and therefore not
+ * actionable. Distinct from `RoleGrantOfferExpiredError` — expiry has its own
+ * user-facing story ("ask the grantor to re-send") so it travels separately.
+ */
+export class RoleGrantOfferAlreadyTerminalError extends Error {
+    constructor(offer_id) {
+        super(`Offer ${offer_id} is already in a terminal state`);
+        this.name = 'RoleGrantOfferAlreadyTerminalError';
+    }
+}
+/**
+ * Error thrown when an offer's `expires_at` has passed. The accept path
+ * enforces this independently of the sweep — a stale offer past its expiry
+ * must not be accepted, even in the race window between expiry and the
+ * sweep stamping the audit event.
+ */
+export class RoleGrantOfferExpiredError extends Error {
+    constructor(offer_id) {
+        super(`Offer ${offer_id} has expired`);
+        this.name = 'RoleGrantOfferExpiredError';
+    }
+}
+/**
+ * Error thrown when an offer cannot be located for the caller. Covers both
+ * "offer does not exist" and "offer belongs to a different recipient"
+ * (IDOR guard) — the standard 404-over-403 pattern that avoids disclosing
+ * whether an offer id exists.
+ */
+export class RoleGrantOfferNotFoundError extends Error {
+    constructor(offer_id) {
+        super(`Offer ${offer_id} not found`);
+        this.name = 'RoleGrantOfferNotFoundError';
+    }
+}
+/**
+ * Error thrown when a grantor attempts to offer a role_grant to their own account.
+ *
+ * Enforced via a single SELECT on the grantor's `actor.account_id` (rather
+ * than via a CHECK constraint or a denormalized column). Resolving from the
+ * grantor side keeps the check multi-actor-correct: under multi-actor the
+ * recipient account may host many actors, but the grantor → account binding
+ * remains 1:1 by definition of `actor`.
+ */
+export class RoleGrantOfferSelfTargetError extends Error {
+    constructor() {
+        super('Cannot offer a role_grant to your own account');
+        this.name = 'RoleGrantOfferSelfTargetError';
+    }
+}
+/**
+ * Error thrown when an actor-targeted offer is being accepted by an actor
+ * other than `offer.to_actor_id`. Distinct from `RoleGrantOfferNotFoundError`
+ * (the IDOR mask): once an offer has been resolved to the recipient account,
+ * a wrong-actor accept on a same-account actor is a contract violation, not
+ * a privacy boundary — surface a specific error so the client UI can
+ * distinguish "this offer isn't for you" from "no such offer".
+ */
+export class RoleGrantOfferActorMismatchError extends Error {
+    constructor(offer_id) {
+        super(`Offer ${offer_id} is targeted to a different actor on this account`);
+        this.name = 'RoleGrantOfferActorMismatchError';
+    }
+}
+/**
+ * Error thrown when `query_role_grant_offer_create` is called with a
+ * `to_actor_id` that does not exist or does not belong to `to_account_id`.
+ * Surfaces the actor↔account binding mismatch at the boundary instead of
+ * letting the FK silently disagree with the recipient field.
+ */
+export class RoleGrantOfferActorAccountMismatchError extends Error {
+    constructor() {
+        super('to_actor_id does not belong to to_account_id');
+        this.name = 'RoleGrantOfferActorAccountMismatchError';
+    }
+}
+/**
+ * Create a new role_grant offer, or refresh an existing pending offer for the
+ * same `(to_account_id, role, scope_id, from_actor_id)` tuple.
+ *
+ * Re-offer semantics: a second call by the same grantor with the same
+ * `(to_account, role, scope)` while pending upserts the existing row,
+ * refreshing `message` and `expires_at` (and `to_actor_id` — supplying
+ * a different `to_actor_id` on re-offer narrows the existing row to the
+ * named actor; supplying null widens it back to account-grain). A
+ * different grantor offering the same `(to_account, role, scope)` creates
+ * a distinct row — multiple pending grantors coexist. After a terminal
+ * state, a re-offer is a fresh INSERT.
+ *
+ * Self-offer rejection: throws `RoleGrantOfferSelfTargetError` if the offering
+ * actor belongs to the recipient account.
+ *
+ * Actor-targeted offers: when `to_actor_id` is supplied,
+ * `query_accept_offer` rejects any actor other than the named one. Closes
+ * the audit hole where offer-shape events would otherwise leave
+ * `target_actor_id` null even when the recipient binding is known at
+ * offer time. The actor↔account binding is verified here in one SELECT.
+ *
+ * @mutates `role_grant_offer` table - inserts a new offer or upserts the matching pending row
+ * @throws RoleGrantOfferSelfTargetError if the offering actor belongs to `to_account_id`
+ * @throws RoleGrantOfferActorAccountMismatchError if `to_actor_id` is set but does not belong to `to_account_id`
+ */
+export const query_role_grant_offer_create = async (deps, input) => {
+    // Self-target check resolves the **grantor** actor's account and
+    // compares against to_account_id. This is multi-actor-correct:
+    // a single account may host many actors, and self-target means
+    // "the offering actor's account == the recipient account",
+    // regardless of how many other actors live on either account.
+    // (The earlier shape — "look up an actor on to_account_id, compare
+    // to from_actor_id" — silently picked one actor on a multi-actor
+    // recipient account, missing the self-target case when the picked
+    // actor wasn't the offering one.)
+    const grantor = await deps.db.query_one(`SELECT account_id FROM actor WHERE id = $1`, [input.from_actor_id]);
+    if (grantor && grantor.account_id === input.to_account_id) {
+        throw new RoleGrantOfferSelfTargetError();
+    }
+    if (input.to_actor_id != null) {
+        const target = await deps.db.query_one(`SELECT account_id FROM actor WHERE id = $1`, [input.to_actor_id]);
+        if (!target || target.account_id !== input.to_account_id) {
+            throw new RoleGrantOfferActorAccountMismatchError();
+        }
+    }
+    const row = await deps.db.query_one(`INSERT INTO role_grant_offer
+			 (from_actor_id, to_account_id, to_actor_id, role, scope_kind, scope_id, message, expires_at)
+		 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+		 ON CONFLICT (
+		   to_account_id,
+		   role,
+		   COALESCE(scope_kind, '${ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN}'),
+		   COALESCE(scope_id, '${ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID}'::uuid),
+		   from_actor_id
+		 )
+		   WHERE accepted_at IS NULL AND declined_at IS NULL AND retracted_at IS NULL AND superseded_at IS NULL
+		 DO UPDATE SET
+			 to_actor_id = EXCLUDED.to_actor_id,
+			 message = EXCLUDED.message,
+			 expires_at = EXCLUDED.expires_at
+		 RETURNING *`, [
+        input.from_actor_id,
+        input.to_account_id,
+        input.to_actor_id ?? null,
+        input.role,
+        input.scope_kind ?? null,
+        input.scope_id ?? null,
+        input.message ?? null,
+        input.expires_at.toISOString(),
+    ]);
+    return assert_row(row, 'INSERT INTO role_grant_offer');
+};
+/**
+ * Mark an offer declined.
+ *
+ * Guarded by `to_account_id` (IDOR). Returns `null` if the offer does not
+ * exist or belongs to a different account. Throws
+ * `RoleGrantOfferAlreadyTerminalError` if the offer exists for the caller but
+ * is already in a terminal state.
+ *
+ * Returns the declined offer with the grantor's `from_account_id` joined
+ * in via CTE — the decline audit envelope populates **both**
+ * `target_actor_id` (the grantor actor) and `target_account_id` (the
+ * grantor account), satisfying the "both populated → same account"
+ * invariant the audit-log column comments describe.
+ *
+ * @mutates `role_grant_offer` row - sets `declined_at` and `decline_reason`
+ * @throws RoleGrantOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
+ */
+export const query_role_grant_offer_decline = async (deps, offer_id, to_account_id, reason) => {
+    const updated = await deps.db.query_one(`WITH updated AS (
+			UPDATE role_grant_offer
+			SET declined_at = NOW(), decline_reason = $3
+			WHERE id = $1
+			  AND to_account_id = $2
+			  AND accepted_at IS NULL
+			  AND declined_at IS NULL
+			  AND retracted_at IS NULL
+			  AND superseded_at IS NULL
+			RETURNING *
+		)
+		SELECT u.*, grantor.account_id AS from_account_id
+		FROM updated u
+		JOIN actor grantor ON grantor.id = u.from_actor_id`, [offer_id, to_account_id, reason ?? null]);
+    if (updated)
+        return updated;
+    return resolve_terminal_or_missing(deps, offer_id, { to_account_id });
+};
+/**
+ * Mark an offer retracted by the grantor.
+ *
+ * Guarded by `from_actor_id` (IDOR). Returns `null` if the offer does not
+ * exist or was issued by a different actor. Throws
+ * `RoleGrantOfferAlreadyTerminalError` if the offer exists for this grantor
+ * but is already in a terminal state.
+ *
+ * @mutates `role_grant_offer` row - sets `retracted_at`
+ * @throws RoleGrantOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
+ */
+export const query_role_grant_offer_retract = async (deps, offer_id, from_actor_id) => {
+    const updated = await deps.db.query_one(`UPDATE role_grant_offer
+		 SET retracted_at = NOW()
+		 WHERE id = $1
+		   AND from_actor_id = $2
+		   AND accepted_at IS NULL
+		   AND declined_at IS NULL
+		   AND retracted_at IS NULL
+		   AND superseded_at IS NULL
+		 RETURNING *`, [offer_id, from_actor_id]);
+    if (updated)
+        return updated;
+    return resolve_terminal_or_missing(deps, offer_id, { from_actor_id });
+};
+/** Helper: distinguish "not found / different owner" from "already terminal". */
+const resolve_terminal_or_missing = async (deps, offer_id, scope) => {
+    const conditions = ['id = $1'];
+    const params = [offer_id];
+    let idx = 2;
+    if (scope.to_account_id) {
+        conditions.push(`to_account_id = $${idx++}`);
+        params.push(scope.to_account_id);
+    }
+    if (scope.from_actor_id) {
+        conditions.push(`from_actor_id = $${idx++}`);
+        params.push(scope.from_actor_id);
+    }
+    const row = await deps.db.query_one(`SELECT * FROM role_grant_offer WHERE ${conditions.join(' AND ')}`, params);
+    if (!row)
+        return null;
+    if (row.accepted_at || row.declined_at || row.retracted_at || row.superseded_at) {
+        throw new RoleGrantOfferAlreadyTerminalError(offer_id);
+    }
+    return null;
+};
+/**
+ * List pending, non-expired offers for an account, soonest expiry first.
+ *
+ * Expired offers are filtered server-side (`expires_at > NOW()`) so the
+ * inbox never surfaces a row that can no longer be accepted. The periodic
+ * sweep (`query_role_grant_offer_sweep_expired`) handles audit tombstoning.
+ */
+export const query_role_grant_offer_list = async (deps, to_account_id) => {
+    return deps.db.query(`SELECT * FROM role_grant_offer
+		 WHERE to_account_id = $1
+		   AND accepted_at IS NULL
+		   AND declined_at IS NULL
+		   AND retracted_at IS NULL
+		   AND superseded_at IS NULL
+		   AND expires_at > NOW()
+		 ORDER BY expires_at ASC`, [to_account_id]);
+};
+/**
+ * List every offer involving an account (either direction), newest first.
+ *
+ * Includes terminal offers — used by the grantor-side admin / history view.
+ */
+export const query_role_grant_offer_history_for_account = async (deps, account_id, limit = 100, offset = 0) => {
+    return deps.db.query(`SELECT o.* FROM role_grant_offer o
+		 LEFT JOIN actor a ON a.id = o.from_actor_id
+		 WHERE o.to_account_id = $1 OR a.account_id = $1
+		 ORDER BY o.created_at DESC
+		 LIMIT $2 OFFSET $3`, [account_id, limit, offset]);
+};
+/**
+ * Look up a pending offer by id. Returns `null` if the offer is terminal,
+ * expired (server-side filter), or missing.
+ */
+export const query_role_grant_offer_find_pending = async (deps, offer_id) => {
+    const row = await deps.db.query_one(`SELECT * FROM role_grant_offer
+		 WHERE id = $1
+		   AND accepted_at IS NULL
+		   AND declined_at IS NULL
+		   AND retracted_at IS NULL
+		   AND superseded_at IS NULL
+		   AND expires_at > NOW()`, [offer_id]);
+    return row ?? null;
+};
+/**
+ * Return pending offers whose `expires_at` has passed.
+ *
+ * Callers fire `role_grant_offer_expire` audit events for each row. The schema
+ * does not tombstone the row, so callers are responsible for their own
+ * idempotency (e.g. check whether a `role_grant_offer_expire` audit event
+ * already exists for the offer id).
+ */
+export const query_role_grant_offer_sweep_expired = async (deps) => {
+    return deps.db.query(`SELECT * FROM role_grant_offer
+		 WHERE accepted_at IS NULL
+		   AND declined_at IS NULL
+		   AND retracted_at IS NULL
+		   AND superseded_at IS NULL
+		   AND expires_at <= NOW()
+		 ORDER BY expires_at ASC`);
+};
+/**
+ * Accept an offer atomically: mark accepted, insert the role_grant, stamp
+ * `resulting_role_grant_id`, supersede sibling pending offers for the same
+ * `(to_account, role, scope)`, and emit `role_grant_offer_accept` +
+ * `role_grant_create` + one `role_grant_offer_supersede` per sibling. Must run
+ * inside a transaction — the caller's route spec should declare
+ * `transaction: true` (or wrap explicitly).
+ *
+ * Idempotent on race: if a second concurrent call observes the offer
+ * already accepted, returns the existing role_grant rather than creating a
+ * duplicate or throwing.
+ *
+ * Error map:
+ * - `RoleGrantOfferNotFoundError` — offer does not exist, or belongs to a
+ *   different recipient (IDOR guard). The offer row is untouched.
+ * - `RoleGrantOfferAlreadyTerminalError` — offer is declined, retracted, or
+ *   superseded.
+ * - `RoleGrantOfferExpiredError` — offer is pending but past `expires_at`.
+ *
+ * Sibling supersede is what closes the "accept a pre-revoke sibling offer
+ * to bypass a revoke" path: once A is accepted, B/C/... can no longer be
+ * accepted even if the resulting role_grant is later revoked.
+ *
+ * @mutates `role_grant_offer` row - stamps `accepted_at` and `resulting_role_grant_id`
+ * @mutates `role_grant` table - inserts the resulting role_grant (idempotent on race)
+ * @mutates `role_grant_offer` siblings - stamps `superseded_at` on every other pending offer for the tuple
+ * @mutates `audit_log` table - emits `role_grant_offer_accept` + `role_grant_create` + one `role_grant_offer_supersede` per sibling
+ * @throws RoleGrantOfferNotFoundError if the offer is missing or belongs to another recipient
+ * @throws RoleGrantOfferAlreadyTerminalError if the offer is declined, retracted, or superseded
+ * @throws RoleGrantOfferExpiredError if the offer is pending but past `expires_at`
+ * @throws Error if the accepting `actor_id` does not belong to `to_account_id`, or invariant assertions fail
+ */
+export const query_accept_offer = async (deps, input) => {
+    const { offer_id, to_account_id, actor_id, ip } = input;
+    // Claim the offer with a row-level lock. Subsequent concurrent callers
+    // block on the lock until this transaction commits/rolls back; after commit
+    // they see the new state (accepted or terminal) and branch idempotently.
+    // We defer writing `accepted_at` until the role_grant row exists — the
+    // `role_grant_offer_role_grant_iff_accepted` CHECK constraint demands both be set
+    // (or neither) at row-visibility time.
+    const locked = await deps.db.query_one(`SELECT * FROM role_grant_offer
+		 WHERE id = $1 AND to_account_id = $2
+		 FOR UPDATE`, [offer_id, to_account_id]);
+    if (!locked) {
+        throw new RoleGrantOfferNotFoundError(offer_id);
+    }
+    if (locked.accepted_at) {
+        // Race winner already committed; return the pre-existing role_grant.
+        // `role_grant_offer_role_grant_iff_accepted` CHECK guarantees resulting_role_grant_id is non-null.
+        const role_grant = assert_row(await deps.db.query_one(`SELECT * FROM role_grant WHERE id = $1`, [
+            locked.resulting_role_grant_id,
+        ]), 'resulting_role_grant lookup');
+        // Multi-actor guard: two actors on the same recipient account may
+        // both race an account-grain offer — the loser must not silently
+        // receive the winner's role_grant (which would tell them "you got it"
+        // while the actor on the role_grant is someone else). Treat the offer
+        // as terminal for the loser.
+        if (role_grant.actor_id !== actor_id) {
+            throw new RoleGrantOfferAlreadyTerminalError(offer_id);
+        }
+        return {
+            role_grant,
+            offer: locked,
+            created: false,
+            superseded_offers: [],
+            audit_events: [],
+        };
+    }
+    if (locked.declined_at || locked.retracted_at || locked.superseded_at) {
+        throw new RoleGrantOfferAlreadyTerminalError(offer_id);
+    }
+    // Expiry check AFTER the accepted-path: a validly-accepted offer past its
+    // expires_at still returns the role_grant idempotently. Only pending offers
+    // past expiry reach this branch.
+    if (new Date(locked.expires_at) <= new Date()) {
+        throw new RoleGrantOfferExpiredError(offer_id);
+    }
+    // Actor-targeted offer gate. When the offer is account-grain
+    // (`to_actor_id IS NULL`) any actor on `to_account_id` may accept and
+    // the existing actor↔account check below applies. When actor-grain
+    // (`to_actor_id IS NOT NULL`) the accepting actor must match —
+    // reject otherwise, even when the actor is on the same account, so
+    // teacher-A's offer cannot be claimed by teacher-B's actor.
+    //
+    // Ordering contract: this check fires *before* the cross-account
+    // `actor_check` SELECT below. A wrong-actor accept on an actor-grain
+    // offer surfaces as `RoleGrantOfferActorMismatchError` regardless of
+    // whether the supplied `actor_id` belongs to `to_account_id` — the
+    // actor-grain binding is the tighter constraint and dominates. The
+    // cross-account `Error` only fires for account-grain offers (or
+    // matching actor-grain offers where `to_actor_id === actor_id` but
+    // the actor turns out not to be on the account, which is unreachable
+    // under the FK invariant but stays as defense-in-depth).
+    if (locked.to_actor_id != null && locked.to_actor_id !== actor_id) {
+        throw new RoleGrantOfferActorMismatchError(offer_id);
+    }
+    // Verify the accepting actor belongs to the recipient account.
+    // Defense-in-depth: the action handler passes `auth.actor.id` which is
+    // already session-bound, but enforcing the invariant here protects
+    // direct callers (tests, future consumers) from cross-account binding
+    // bugs that would silently grant a role_grant to the wrong actor.
+    const actor_check = await deps.db.query_one(`SELECT id FROM actor WHERE id = $1 AND account_id = $2`, [actor_id, to_account_id]);
+    if (!actor_check) {
+        throw new Error(`Accepting actor ${actor_id} does not belong to account ${to_account_id} (offer ${offer_id})`);
+    }
+    // Insert the role_grant. Uses the normal grant idempotency — if another
+    // code path already granted the same (actor, role, scope_kind, scope), reuse it.
+    const granted_role_grant = await deps.db.query_one(`INSERT INTO role_grant (actor_id, role, scope_kind, scope_id, granted_by, source_offer_id)
+		 VALUES ($1, $2, $3, $4, $5, $6)
+		 ON CONFLICT (
+		   actor_id,
+		   role,
+		   COALESCE(scope_kind, '${ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN}'),
+		   COALESCE(scope_id, '${ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID}'::uuid)
+		 )
+		   WHERE revoked_at IS NULL
+		 DO NOTHING
+		 RETURNING *`, [actor_id, locked.role, locked.scope_kind, locked.scope_id, locked.from_actor_id, locked.id]);
+    let role_grant;
+    if (granted_role_grant) {
+        role_grant = granted_role_grant;
+    }
+    else {
+        const existing = await deps.db.query_one(`SELECT * FROM role_grant
+			 WHERE actor_id = $1
+			   AND role = $2
+			   AND scope_kind IS NOT DISTINCT FROM $3
+			   AND scope_id IS NOT DISTINCT FROM $4
+			   AND revoked_at IS NULL`, [actor_id, locked.role, locked.scope_kind, locked.scope_id]);
+        role_grant = assert_row(existing, 'query_accept_offer idempotent role_grant lookup');
+    }
+    // Single UPDATE sets both sides of the CHECK constraint at once.
+    const offer_accepted = await deps.db.query_one(`UPDATE role_grant_offer
+		 SET accepted_at = NOW(), resulting_role_grant_id = $2
+		 WHERE id = $1
+		 RETURNING *`, [locked.id, role_grant.id]);
+    const offer = assert_row(offer_accepted, 'mark offer accepted');
+    // Supersede sibling pending offers for the same (to_account, role, scope).
+    // Forecloses the "accept this other sibling later to get the role back
+    // after a revoke" path — any pending offer for this tuple at accept time
+    // is obsoleted by the accept. CTE joins `actor` to surface each sibling's
+    // grantor `account_id` for the caller's notification fan-out.
+    const superseded = await deps.db.query(`WITH updated AS (
+			UPDATE role_grant_offer
+			SET superseded_at = NOW()
+			WHERE to_account_id = $1
+			  AND role = $2
+			  AND scope_id IS NOT DISTINCT FROM $3
+			  AND id <> $4
+			  AND accepted_at IS NULL
+			  AND declined_at IS NULL
+			  AND retracted_at IS NULL
+			  AND superseded_at IS NULL
+			RETURNING *
+		)
+		SELECT u.*, grantor.account_id AS from_account_id
+		FROM updated u
+		JOIN actor grantor ON grantor.id = u.from_actor_id`, [to_account_id, offer.role, offer.scope_id, offer.id]);
+    // Emit audit events in-transaction (atomic with the role_grant insert).
+    // `RETURNING *` after the SET guarantees `offer.resulting_role_grant_id === role_grant.id`.
+    // Accept binds the actor deterministically — populate both target
+    // columns to mirror `role_grant_create` (the in-tx pair) so forensic
+    // queries don't have to split between the two events.
+    const offer_accept_event = await query_audit_log(deps, {
+        event_type: 'role_grant_offer_accept',
+        actor_id,
+        account_id: to_account_id,
+        target_account_id: to_account_id,
+        target_actor_id: actor_id,
+        ip: ip ?? null,
+        metadata: {
+            offer_id: offer.id,
+            role_grant_id: role_grant.id,
+            role: offer.role,
+            scope_id: offer.scope_id,
+        },
+    });
+    // `role_grant_create` is the canonical actor-bound-subject event — the
+    // role_grant just bound to this actor. On self-accept the actor and the
+    // target are the same identity; on admin direct-grant (separate code
+    // path) they differ. Either way `target_actor_id` carries the
+    // grantee for actor-grain forensics.
+    const role_grant_create_event = await query_audit_log(deps, {
+        event_type: 'role_grant_create',
+        actor_id,
+        account_id: to_account_id,
+        target_account_id: to_account_id,
+        target_actor_id: actor_id,
+        ip: ip ?? null,
+        metadata: {
+            role: offer.role,
+            role_grant_id: role_grant.id,
+            scope_id: offer.scope_id,
+            source_offer_id: offer.id,
+        },
+    });
+    const supersede_events = [];
+    for (const sibling of superseded) {
+        // Supersede inherits the sibling's actor-grain target — actor-grain
+        // when the sibling was actor-targeted, account-grain (null) when it
+        // was account-level.
+        supersede_events.push(await query_audit_log(deps, {
+            event_type: 'role_grant_offer_supersede',
+            actor_id,
+            account_id: to_account_id,
+            target_account_id: to_account_id,
+            target_actor_id: sibling.to_actor_id,
+            ip: ip ?? null,
+            metadata: {
+                offer_id: sibling.id,
+                role: sibling.role,
+                scope_id: sibling.scope_id,
+                reason: 'sibling_accepted',
+                cause_id: offer.id,
+            },
+        }));
+    }
+    return {
+        role_grant,
+        offer,
+        created: true,
+        superseded_offers: superseded,
+        audit_events: [offer_accept_event, role_grant_create_event, ...supersede_events],
+    };
+};

package/dist/auth/role_grant_offer_schema.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Role grant offer DDL, types, and client-safe schemas.
+ *
+ * An offer is a pending grant awaiting recipient consent. Lifecycle states
+ * are mutually exclusive via a CHECK constraint (`role_grant_offer_single_terminal`):
+ * at most one of `accepted_at` / `declined_at` / `retracted_at` may be set.
+ * On accept, the offer's `resulting_role_grant_id` links to the role_grant row
+ * produced by `query_accept_offer`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+/** Sentinel UUID used inside the partial unique indexes to collapse `scope_id IS NULL` into a comparable value. */
+export declare const ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID = "00000000-0000-0000-0000-000000000000";
+/** Maximum length of the optional message attached to an offer. */
+export declare const ROLE_GRANT_OFFER_MESSAGE_LENGTH_MAX = 500;
+/** Default TTL for a newly created offer — 30 days. Matches GitHub org-invite expiry. */
+export declare const ROLE_GRANT_OFFER_DEFAULT_TTL_MS: number;
+export declare const ROLE_GRANT_OFFER_SCHEMA = "\nCREATE TABLE IF NOT EXISTS role_grant_offer (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  from_actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,\n  to_account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  to_actor_id UUID NULL REFERENCES actor(id) ON DELETE CASCADE,\n  role TEXT NOT NULL,\n  scope_kind TEXT NULL,\n  scope_id UUID NULL,\n  message TEXT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  expires_at TIMESTAMPTZ NOT NULL,\n  accepted_at TIMESTAMPTZ NULL,\n  declined_at TIMESTAMPTZ NULL,\n  decline_reason TEXT NULL,\n  retracted_at TIMESTAMPTZ NULL,\n  superseded_at TIMESTAMPTZ NULL,\n  resulting_role_grant_id UUID NULL REFERENCES role_grant(id) ON DELETE SET NULL,\n  CONSTRAINT role_grant_offer_single_terminal CHECK (\n    (accepted_at IS NOT NULL)::int\n    + (declined_at IS NOT NULL)::int\n    + (retracted_at IS NOT NULL)::int\n    + (superseded_at IS NOT NULL)::int\n    <= 1\n  ),\n  CONSTRAINT role_grant_offer_role_grant_iff_accepted CHECK (\n    (accepted_at IS NOT NULL) = (resulting_role_grant_id IS NOT NULL)\n  ),\n  CONSTRAINT role_grant_offer_reason_iff_declined CHECK (\n    decline_reason IS NULL OR declined_at IS NOT NULL\n  ),\n  CONSTRAINT role_grant_offer_scope_kind_paired CHECK (\n    (scope_kind IS NULL) = (scope_id IS NULL)\n  )\n)";
+/**
+ * Index-side token for the global case in the partial unique index. Uppercase
+ * so it cannot collide with consumer-declared `ScopeKindName` values (which
+ * are lowercase by regex). Never appears as a column value — column-level
+ * `scope_kind = NULL` and `scope_id = NULL` together encode the global case.
+ */
+export declare const ROLE_GRANT_OFFER_SCOPE_KIND_GLOBAL_TOKEN = "GLOBAL";
+/**
+ * At most one pending offer per (to_account, role, scope_kind, scope, from_actor).
+ *
+ * Including `from_actor_id` in the tuple lets multiple grantors coexist —
+ * teacher A and teacher B can each have a pending `classroom_student` offer
+ * for the same student and scope. A same-grantor re-offer upserts the
+ * existing pending row. `COALESCE` collapses `NULL` scopes into the
+ * sentinel values so Postgres's NULL-in-unique-index quirk does not allow
+ * duplicate global pending offers; the `scope_kind` / `scope_id` pair is
+ * always either both null (global) or both non-null (scoped) per the
+ * `role_grant_offer_scope_kind_paired` CHECK, so the two COALESCE expressions
+ * always agree. The ON CONFLICT target in `query_role_grant_offer_create` must
+ * match this expression literally.
+ */
+export declare const ROLE_GRANT_OFFER_PENDING_UNIQUE_INDEX = "\nCREATE UNIQUE INDEX IF NOT EXISTS role_grant_offer_pending_unique\n  ON role_grant_offer (\n    to_account_id,\n    role,\n    COALESCE(scope_kind, 'GLOBAL'),\n    COALESCE(scope_id, '00000000-0000-0000-0000-000000000000'::uuid),\n    from_actor_id\n  )\n  WHERE accepted_at IS NULL\n    AND declined_at IS NULL\n    AND retracted_at IS NULL\n    AND superseded_at IS NULL";
+/** Inbox lookup — pending offers for an account, ordered by soonest expiry. */
+export declare const ROLE_GRANT_OFFER_INBOX_INDEX = "\nCREATE INDEX IF NOT EXISTS role_grant_offer_inbox\n  ON role_grant_offer (to_account_id, expires_at)\n  WHERE accepted_at IS NULL\n    AND declined_at IS NULL\n    AND retracted_at IS NULL\n    AND superseded_at IS NULL";
+/** Role grant offer row as returned by the database. */
+export interface RoleGrantOffer {
+    id: Uuid;
+    from_actor_id: Uuid;
+    to_account_id: Uuid;
+    /**
+     * Optional actor-grain target on the recipient account. When set, accept
+     * is gated to this specific actor — `query_accept_offer` rejects any
+     * other actor with `role_grant_offer_actor_mismatch` even when they belong
+     * to `to_account_id`. When null the offer is account-grain and any
+     * actor on `to_account_id` may accept (the v1 default).
+     *
+     * Drives the audit envelope's `target_actor_id` on offer-shape events
+     * (`role_grant_offer_create` / `_expire` / `_retract` / `_supersede`) — when
+     * set, the actor-grain forensic field carries the named actor; when
+     * null the offer-shape events leave it null by design.
+     */
+    to_actor_id: Uuid | null;
+    role: string;
+    /**
+     * Machine-readable kind tag for the polymorphic `scope_id`. Paired-null
+     * with `scope_id` per the `role_grant_offer_scope_kind_paired` CHECK: both
+     * null (global) or both non-null (scoped). Consumer-declared via
+     * `create_scope_kind_schema(...)`; v1 keeps validation registry-membership
+     * only, with no INSERT-time `(role, scope_kind)` enforcement.
+     */
+    scope_kind: string | null;
+    scope_id: Uuid | null;
+    message: string | null;
+    created_at: string;
+    expires_at: string;
+    accepted_at: string | null;
+    declined_at: string | null;
+    decline_reason: string | null;
+    retracted_at: string | null;
+    /**
+     * Set when the offer was obsoleted by an external event — a sibling
+     * offer was accepted (yielding the role_grant this offer's role+scope maps to)
+     * or the resulting role_grant for this (to_account, role, scope) was revoked.
+     * Closes the "accept a pre-revoke offer to bypass the revoke" path.
+     */
+    superseded_at: string | null;
+    resulting_role_grant_id: Uuid | null;
+}
+/**
+ * A superseded offer row annotated with the grantor's `account_id`.
+ *
+ * Carried by `superseded_offers` in accept/revoke query results so callers
+ * can fan out `role_grant_offer_supersede` notifications to the grantor's
+ * sockets without a second round-trip. Populated via a CTE join on `actor`
+ * in the supersede UPDATE.
+ */
+export interface SupersededOffer extends RoleGrantOffer {
+    from_account_id: Uuid;
+}
+/**
+ * Input for `query_role_grant_offer_create`.
+ *
+ * `expires_at` must be supplied — the query layer does not apply a default,
+ * so callers can thread their own TTL (typically `ROLE_GRANT_OFFER_DEFAULT_TTL_MS`).
+ */
+export interface CreateRoleGrantOfferInput {
+    from_actor_id: Uuid;
+    to_account_id: Uuid;
+    /**
+     * Optional actor-grain target on the recipient account. When set,
+     * `query_role_grant_offer_create` validates that the actor belongs to
+     * `to_account_id` and stamps the column; accept then matches against
+     * this specific actor. Omit (or pass null) for the account-grain
+     * default — any actor on `to_account_id` may accept.
+     */
+    to_actor_id?: Uuid | null;
+    role: string;
+    /**
+     * Machine-readable kind for the `scope_id`. Required iff `scope_id` is
+     * set; must be null when `scope_id` is null (DB-level CHECK rejects the
+     * mismatch). Consumer-declared via `create_scope_kind_schema(...)`.
+     */
+    scope_kind?: string | null;
+    scope_id?: Uuid | null;
+    message?: string | null;
+    expires_at: Date;
+}
+/** Zod schema for client-safe role_grant offer data. */
+export declare const RoleGrantOfferJson: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    from_actor_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    to_account_id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    to_actor_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    role: z.ZodString;
+    scope_kind: z.ZodNullable<z.ZodString>;
+    scope_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+    message: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    expires_at: z.ZodString;
+    accepted_at: z.ZodNullable<z.ZodString>;
+    declined_at: z.ZodNullable<z.ZodString>;
+    decline_reason: z.ZodNullable<z.ZodString>;
+    retracted_at: z.ZodNullable<z.ZodString>;
+    superseded_at: z.ZodNullable<z.ZodString>;
+    resulting_role_grant_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
+}, z.core.$strict>;
+export type RoleGrantOfferJson = z.infer<typeof RoleGrantOfferJson>;
+/** Convert a `RoleGrantOffer` row to its JSON payload shape. */
+export declare const to_role_grant_offer_json: (offer: RoleGrantOffer) => RoleGrantOfferJson;
+//# sourceMappingURL=role_grant_offer_schema.d.ts.map