auth/role_grant_offer_action_specs.ts

All role-grant-offer action specs — a codegen-ready registry. Consumers spread this into their own action-spec array to include offer lifecycle + revoke + assign methods in a typed client surface.

Error reason — a grant path was asked to bind a builtin role to a scope (builtin roles are global-only, see is_builtin_role). Refused by role_grant_assign, role_grant_offer_create, and role_grant_offer_accept.

Error reason — role_grant_offer_create was called with a to_actor_id that does not belong to to_account_id.

Error reason — actor-targeted offer was accepted by an actor other than to_actor_id.

Error reason — offer's expires_at has passed.

Error reason — caller is not authorized to offer this role (default policy: caller lacks the role; consumer authorize callback may add further policy).

Error reason — offer does not exist or belongs to a different recipient (404-over-403 IDOR mask).

Error reason — the offered role does not include 'admin' in its RoleSpec.grant_paths (nobody may offer it via this surface).

Error reason — caller tried to offer themselves a role_grant.

Error reason — offer is declined, retracted, or superseded.

The message a half-scoped grant input fails with — the grant inputs' refine, and the UI's pre-RPC guard.

Whether a grant input's scope_kind + scope_id are paired — both absent (a global grant) or both present (a scoped one), the role_grant_scope_kind_paired / role_grant_offer_scope_kind_paired CHECKs. The grant inputs refine on it so a half-scoped call is a -32602 rather than a constraint-violation 500.

rate_limit: 'account' bounds admin-side burn of role_grant_assign — the action is admin-gated and audit-trailed, but the per-account cap matches role_grant_revoke so a single admin script can't churn grants in a loop.

credential_types: ['session'] — see docs/security.md §Credential-channel gating. The only offer verb that moves the *caller's own* authority: accepting a pending admin offer over a leaked API token is a privilege pivot in the same family the credential-lifecycle mutations are gated to prevent (the token is account-wide and non-expiring, and the resulting role_grant outlives revoking it). Consent inherently belongs to a human at a browser, and no automation accepts an offer on its own behalf. The sibling verbs stay ungated deliberately — _create is the offering side, and _decline / _retract destroy a pending offer and confer nothing.

rate_limit: 'account' throttles offer-spam at the authenticated grantor and bounds the account-existence oracle on to_account_id — the same shape as invite_create_action_spec upstream addresses, where a hostile authed caller iterates recipients to probe ERROR_ACCOUNT_NOT_FOUND (and the actor-binding via ERROR_ROLE_GRANT_OFFER_ACTOR_ACCOUNT_MISMATCH) as an enumeration vector. Failure-outcome audit rows preserve the forensic trail; the rate cap closes the budget.

rate_limit: 'account' bounds admin-side burn of role_grant_revoke — the action is admin-gated and audit-trailed, but the per-account cap keeps a single admin script from churning role_grants in a loop and obscuring audit context for unrelated activity.

Input for role_grant_assign — the immediate admin-only conferral path, the consent-free sibling of role_grant_offer_create. An admin assigns a role_grant straight onto the target actor; there is no offer for a grantee to accept. No message (no offer to carry it on). scope_kind pairs with scope_id exactly as on role_grant_offer_create — both or neither — and the grant row carries the pair.

Output for role_grant_assign.

Input for role_grant_offer_accept.

Output for role_grant_offer_accept.

Input for role_grant_offer_create.

to_actor_id (optional) narrows the offer to a specific actor on the recipient account. When supplied, role_grant_offer_accept will only admit the named actor — wrong-actor accepts reject with role_grant_offer_actor_mismatch. The audit envelope's target_actor_id is stamped from this column on the create / supersede / expire / retract events. Omit (or pass null) for the account-grain default — any actor on to_account_id may accept.

Output for role_grant_offer_create.

Input for role_grant_offer_decline.

Input for role_grant_offer_history. Returns every offer involving the account in either direction (recipient or grantor), including terminal rows, newest first. account_id is admin-only.

Output for role_grant_offer_history.

Input for role_grant_offer_list. account_id is admin-only (inspect another account's inbox).

Output for role_grant_offer_list.

Output for role_grant_offer_decline / role_grant_offer_retract.

Input for role_grant_offer_retract.

Input for role_grant_revoke. Admin-only mutation that revokes an active role_grant on a target actor. actor_id is the natural key — role_grants are actor-scoped, and the admin UI reads row.actor.id straight from the listing. Deriving actor_id from account_id would collapse under multi-actor accounts.

Output for role_grant_revoke.