@fuzdev/fuz_app 0.55.0 → 0.56.0

package/dist/auth/{permit_offer_queries.d.ts → role_grant_offer_queries.d.ts}

@@ -1,9 +1,9 @@
 /**
- * Permit offer database queries.
+ * Role grant offer database queries.
  *
- * Covers the offer side of the consentful-permits flow: create (with
+ * 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 → permit.
+ * 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
@@ -13,16 +13,16 @@
  */
 import type { Uuid } from '@fuzdev/fuz_util/id.js';
 import type { QueryDeps } from '../db/query_deps.js';
-import type { Permit } from './account_schema.js';
-import { type CreatePermitOfferInput, type PermitOffer, type SupersededOffer } from './permit_offer_schema.js';
+import type { RoleGrant } from './account_schema.js';
+import { type CreateRoleGrantOfferInput, type RoleGrantOffer, type SupersededOffer } from './role_grant_offer_schema.js';
 import type { AuditLogEvent } from './audit_log_schema.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 `PermitOfferExpiredError` — expiry has its own
+ * actionable. Distinct from `RoleGrantOfferExpiredError` — expiry has its own
  * user-facing story ("ask the grantor to re-send") so it travels separately.
  */
-export declare class PermitOfferAlreadyTerminalError extends Error {
+export declare class RoleGrantOfferAlreadyTerminalError extends Error {
     constructor(offer_id: string);
 }
 /**
@@ -31,7 +31,7 @@ export declare class PermitOfferAlreadyTerminalError extends Error {
  * must not be accepted, even in the race window between expiry and the
  * sweep stamping the audit event.
  */
-export declare class PermitOfferExpiredError extends Error {
+export declare class RoleGrantOfferExpiredError extends Error {
     constructor(offer_id: string);
 }
 /**
@@ -40,11 +40,11 @@ export declare class PermitOfferExpiredError extends Error {
  * (IDOR guard) — the standard 404-over-403 pattern that avoids disclosing
  * whether an offer id exists.
  */
-export declare class PermitOfferNotFoundError extends Error {
+export declare class RoleGrantOfferNotFoundError extends Error {
     constructor(offer_id: string);
 }
 /**
- * Error thrown when a grantor attempts to offer a permit to their own account.
+ * 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
@@ -52,31 +52,31 @@ export declare class PermitOfferNotFoundError extends Error {
  * recipient account may host many actors, but the grantor → account binding
  * remains 1:1 by definition of `actor`.
  */
-export declare class PermitOfferSelfTargetError extends Error {
+export declare class RoleGrantOfferSelfTargetError extends Error {
     constructor();
 }
 /**
  * Error thrown when an actor-targeted offer is being accepted by an actor
- * other than `offer.to_actor_id`. Distinct from `PermitOfferNotFoundError`
+ * 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 declare class PermitOfferActorMismatchError extends Error {
+export declare class RoleGrantOfferActorMismatchError extends Error {
     constructor(offer_id: string);
 }
 /**
- * Error thrown when `query_permit_offer_create` is called with a
+ * 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 declare class PermitOfferActorAccountMismatchError extends Error {
+export declare class RoleGrantOfferActorAccountMismatchError extends Error {
     constructor();
 }
 /**
- * Create a new permit offer, or refresh an existing pending offer for the
+ * 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
@@ -88,7 +88,7 @@ export declare class PermitOfferActorAccountMismatchError extends Error {
  * 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
+ * Self-offer rejection: throws `RoleGrantOfferSelfTargetError` if the offering
  * actor belongs to the recipient account.
  *
  * Actor-targeted offers: when `to_actor_id` is supplied,
@@ -97,13 +97,13 @@ export declare class PermitOfferActorAccountMismatchError extends Error {
  * `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 `permit_offer` table - inserts a new offer or upserts the matching pending row
- * @throws PermitOfferSelfTargetError if the offering actor belongs to `to_account_id`
- * @throws PermitOfferActorAccountMismatchError if `to_actor_id` is set but does not belong to `to_account_id`
+ * @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 declare const query_permit_offer_create: (deps: QueryDeps, input: CreatePermitOfferInput) => Promise<PermitOffer>;
-/** Result of `query_permit_offer_decline` — the declined offer plus the grantor's `account_id`. */
-export interface DeclinedOffer extends PermitOffer {
+export declare const query_role_grant_offer_create: (deps: QueryDeps, input: CreateRoleGrantOfferInput) => Promise<RoleGrantOffer>;
+/** Result of `query_role_grant_offer_decline` — the declined offer plus the grantor's `account_id`. */
+export interface DeclinedOffer extends RoleGrantOffer {
     /**
      * Grantor's `account_id`, resolved via a join on `actor` so the audit
      * envelope's `target_account_id` (decline is *to* the grantor) and the
@@ -117,7 +117,7 @@ export interface DeclinedOffer extends PermitOffer {
  *
  * 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
+ * `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
@@ -126,117 +126,117 @@ export interface DeclinedOffer extends PermitOffer {
  * grantor account), satisfying the "both populated → same account"
  * invariant the audit-log column comments describe.
  *
- * @mutates `permit_offer` row - sets `declined_at` and `decline_reason`
- * @throws PermitOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
+ * @mutates `role_grant_offer` row - sets `declined_at` and `decline_reason`
+ * @throws RoleGrantOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
  */
-export declare const query_permit_offer_decline: (deps: QueryDeps, offer_id: string, to_account_id: string, reason: string | null) => Promise<DeclinedOffer | null>;
+export declare const query_role_grant_offer_decline: (deps: QueryDeps, offer_id: string, to_account_id: string, reason: string | null) => Promise<DeclinedOffer | null>;
 /**
  * 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
+ * `RoleGrantOfferAlreadyTerminalError` if the offer exists for this grantor
  * but is already in a terminal state.
  *
- * @mutates `permit_offer` row - sets `retracted_at`
- * @throws PermitOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
+ * @mutates `role_grant_offer` row - sets `retracted_at`
+ * @throws RoleGrantOfferAlreadyTerminalError if the offer is already accepted, declined, retracted, or superseded
  */
-export declare const query_permit_offer_retract: (deps: QueryDeps, offer_id: string, from_actor_id: string) => Promise<PermitOffer | null>;
+export declare const query_role_grant_offer_retract: (deps: QueryDeps, offer_id: string, from_actor_id: string) => Promise<RoleGrantOffer | 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_permit_offer_sweep_expired`) handles audit tombstoning.
+ * sweep (`query_role_grant_offer_sweep_expired`) handles audit tombstoning.
  */
-export declare const query_permit_offer_list: (deps: QueryDeps, to_account_id: string) => Promise<Array<PermitOffer>>;
+export declare const query_role_grant_offer_list: (deps: QueryDeps, to_account_id: string) => Promise<Array<RoleGrantOffer>>;
 /**
  * List every offer involving an account (either direction), newest first.
  *
  * Includes terminal offers — used by the grantor-side admin / history view.
  */
-export declare const query_permit_offer_history_for_account: (deps: QueryDeps, account_id: string, limit?: number, offset?: number) => Promise<Array<PermitOffer>>;
+export declare const query_role_grant_offer_history_for_account: (deps: QueryDeps, account_id: string, limit?: number, offset?: number) => Promise<Array<RoleGrantOffer>>;
 /**
  * Look up a pending offer by id. Returns `null` if the offer is terminal,
  * expired (server-side filter), or missing.
  */
-export declare const query_permit_offer_find_pending: (deps: QueryDeps, offer_id: string) => Promise<PermitOffer | null>;
+export declare const query_role_grant_offer_find_pending: (deps: QueryDeps, offer_id: string) => Promise<RoleGrantOffer | null>;
 /**
  * Return pending offers whose `expires_at` has passed.
  *
- * Callers fire `permit_offer_expire` audit events for each row. The schema
+ * 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 `permit_offer_expire` audit event
+ * idempotency (e.g. check whether a `role_grant_offer_expire` audit event
  * already exists for the offer id).
  */
-export declare const query_permit_offer_sweep_expired: (deps: QueryDeps) => Promise<Array<PermitOffer>>;
+export declare const query_role_grant_offer_sweep_expired: (deps: QueryDeps) => Promise<Array<RoleGrantOffer>>;
 /** Input for `query_accept_offer`. */
 export interface AcceptOfferInput {
     offer_id: Uuid;
     /** Account of the accepting recipient — IDOR guard against another account accepting the offer. */
     to_account_id: Uuid;
     /**
-     * Accepting actor — the actor that will hold the resulting permit.
+     * Accepting actor — the actor that will hold the resulting role_grant.
      * Must belong to `to_account_id`; the query verifies and throws if not
      * (defense-in-depth — the action handler passes `auth.actor.id` which
      * is session-bound, but the query enforces the invariant for all
      * callers including tests and future direct consumers).
      *
      * Required because under multi-actor an account may host many actors;
-     * the resulting permit must bind to the actor that actually accepted,
+     * the resulting role_grant must bind to the actor that actually accepted,
      * not "an" actor on the account picked by query order.
      */
     actor_id: Uuid;
     /** Optional IP to stamp on the audit events. */
     ip?: string | null;
 }
-/** Result of `query_accept_offer` — the permit produced (new or pre-existing on race), plus the (now-accepted) offer. */
+/** Result of `query_accept_offer` — the role_grant produced (new or pre-existing on race), plus the (now-accepted) offer. */
 export interface AcceptOfferResult {
-    permit: Permit;
-    offer: PermitOffer;
-    /** `true` if this call is the one that accepted the offer (new permit inserted); `false` on a race returning the already-created permit. */
+    role_grant: RoleGrant;
+    offer: RoleGrantOffer;
+    /** `true` if this call is the one that accepted the offer (new role_grant inserted); `false` on a race returning the already-created role_grant. */
     created: boolean;
     /**
      * Sibling offers superseded by this accept — empty on the race-loser path.
      * Each entry carries its grantor's `from_account_id` so the caller can
-     * fan out `permit_offer_supersede` notifications without a second
+     * fan out `role_grant_offer_supersede` notifications without a second
      * round-trip.
      */
     superseded_offers: Array<SupersededOffer>;
-    /** Audit events emitted in-transaction — fed back through the normal `on_audit_event` broadcast chain by the caller. Includes one `permit_offer_supersede` per superseded sibling. */
+    /** Audit events emitted in-transaction — fed back through `audit.notify` by the caller, which fans out to `audit.on_event_chain`. Includes one `role_grant_offer_supersede` per superseded sibling. */
     audit_events: Array<AuditLogEvent>;
 }
 /**
- * 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
+ * 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 permit rather than creating a
+ * already accepted, returns the existing role_grant rather than creating a
  * duplicate or throwing.
  *
  * Error map:
- * - `PermitOfferNotFoundError` — offer does not exist, or belongs to a
+ * - `RoleGrantOfferNotFoundError` — offer does not exist, or belongs to a
  *   different recipient (IDOR guard). The offer row is untouched.
- * - `PermitOfferAlreadyTerminalError` — offer is declined, retracted, or
+ * - `RoleGrantOfferAlreadyTerminalError` — offer is declined, retracted, or
  *   superseded.
- * - `PermitOfferExpiredError` — offer is pending but past `expires_at`.
+ * - `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 permit is later revoked.
- *
- * @mutates `permit_offer` row - stamps `accepted_at` and `resulting_permit_id`
- * @mutates `permit` table - inserts the resulting permit (idempotent on race)
- * @mutates `permit_offer` siblings - stamps `superseded_at` on every other pending offer for the tuple
- * @mutates `audit_log` table - emits `permit_offer_accept` + `permit_grant` + one `permit_offer_supersede` per sibling
- * @throws PermitOfferNotFoundError if the offer is missing or belongs to another recipient
- * @throws PermitOfferAlreadyTerminalError if the offer is declined, retracted, or superseded
- * @throws PermitOfferExpiredError if the offer is pending but past `expires_at`
+ * 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 declare const query_accept_offer: (deps: QueryDeps, input: AcceptOfferInput) => Promise<AcceptOfferResult>;
-//# sourceMappingURL=permit_offer_queries.d.ts.map
+//# sourceMappingURL=role_grant_offer_queries.d.ts.map

package/dist/auth/role_grant_offer_queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role_grant_offer_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_queries.ts"],"names":[],"mappings":"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"}