auth/permit_offer_queries.ts

Input for query_accept_offer.

Result of query_accept_offer — the permit produced (new or pre-existing on race), plus the (now-accepted) 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 PermitOfferExpiredError — expiry has its own user-facing story ("ask the grantor to re-send") so it travels separately.

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 permit to their own account.

Enforced here (rather than via a CHECK constraint) so the constraint can be expressed as a cross-row JOIN on actor.account_id without requiring denormalized columns.

Accept an offer atomically: mark accepted, insert the permit, stamp resulting_permit_id, supersede sibling pending offers for the same (to_account, role, scope), and emit permit_offer_accept + permit_grant + one permit_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 permit rather than creating a duplicate or throwing.

Error map: - PermitOfferNotFoundError — offer does not exist, or belongs to a different recipient (IDOR guard). The offer row is untouched. - PermitOfferAlreadyTerminalError — offer is declined, retracted, or superseded. - PermitOfferExpiredError — 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 permit is later revoked.

Create a new permit 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. 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 PermitOfferSelfTargetError if the offering actor belongs to the recipient account.

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 PermitOfferAlreadyTerminalError if the offer exists for the caller but is already in a terminal state.

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_permit_offer_sweep_expired) handles audit tombstoning.

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 PermitOfferAlreadyTerminalError if the offer exists for this grantor but is already in a terminal state.

Return pending offers whose expires_at has passed.

Callers fire permit_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 permit_offer_expire audit event already exists for the offer id).