auth/role_grant_offer_queries.ts

Input for query_accept_offer.

Result of query_accept_offer — the role_grant produced (new or pre-existing on race), plus the (now-accepted) offer.

Why query_accept_offer refused to mint a builtin-role grant.

Each is a row no current grant path creates but a database can still hold (a direct query_role_grant_offer_create call, or an offer made under a since-closed path), so accept — the chokepoint where an offer becomes a role_grant — checks them itself.

• bootstrap_only — the offer is of keeper, which is bootstrap-only: never conferred through an offer, whoever made it.
• scoped — the offer binds a builtin role to a scope; builtin roles are global-only.
• grantor_not_authorized — the grantor no longer holds an active global admin on an active actor of an active account. Conferring a builtin role is global-admin authority, so it is re-checked when the grant is minted, not only when the offer was made.

Result of query_role_grant_offer_decline — the declined offer plus the grantor's account_id.

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.
• RoleGrantOfferActorMismatchError — actor-targeted offer, different actor.
• RoleGrantOfferBuiltinRefusedError — a builtin-role offer that must not mint: keeper at all, a builtin bound to a scope, or one whose grantor no longer holds an active global admin (read under FOR SHARE). The offer stays pending.

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.

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) and clearing expire_audited_at, so a re-offer of an expired, already-audited row gets its own role_grant_offer_expire when the refreshed expiry passes. 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.

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.

Look up a pending offer by id. Returns null if the offer is terminal, expired (server-side filter), or missing.

List every offer involving an account (either direction), newest first.

Includes terminal offers — used by the grantor-side admin / history view.

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) audits each expiry once.

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.

Claim the pending offers whose expires_at has passed and whose expiry has not been audited yet, stamping expire_audited_at on each, and return them soonest-expiry first.

The stamp is the sweep's idempotency: a claimed row never matches again, so each expiry is audited exactly once. It must share a transaction with the caller's role_grant_offer_expire audit inserts — committed together, or rolled back together so the next sweep retries. Concurrent sweeps claim disjoint rows: a row another sweep has stamped but not committed blocks on its row lock, then fails the re-checked expire_audited_at IS NULL. cleanup_expired_role_grant_offers is the caller.

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.

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

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.

Error thrown by query_accept_offer when the offer confers a builtin role (admin / keeper) that this accept must not mint — refusal names the rule. Carries the locked (still pending, untouched) offer so the caller can audit the refusal with the offer's role and scope.

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.

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.

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.