@fuzdev/fuz_app 0.55.0 → 0.57.0

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"role_grant_offer_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/role_grant_offer_schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAI5C,mHAAmH;AACnH,eAAO,MAAM,oCAAoC,yCAAyC,CAAC;AAE3F,mEAAmE;AACnE,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAEvD,yFAAyF;AACzF,eAAO,MAAM,+BAA+B,QAA2B,CAAC;AAExE,eAAO,MAAM,uBAAuB,qzCAkClC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,WAAW,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qCAAqC,2XAYpB,CAAC;AAE/B,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,kOAMX,CAAC;AAQ/B,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,IAAI,CAAC;IACT,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;OAWG;IACH,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,IAAI,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACtD,eAAe,EAAE,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACzC,aAAa,EAAE,IAAI,CAAC;IACpB,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,CAAC;CACjB;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;kBAoD0D,CAAC;AAC1F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,GAAI,OAAO,cAAc,KAAG,kBAiB/D,CAAC"}

package/dist/auth/{permit_offer_schema.js → role_grant_offer_schema.js}

@@ -1,10 +1,10 @@
 /**
- * Permit offer DDL, types, and client-safe schemas.
+ * 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 (`permit_offer_single_terminal`):
+ * 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_permit_id` links to the permit row
+ * On accept, the offer's `resulting_role_grant_id` links to the role_grant row
  * produced by `query_accept_offer`.
  *
  * @module
@@ -13,18 +13,19 @@ import { z } from 'zod';
 import { Uuid } from '@fuzdev/fuz_util/id.js';
 import { RoleName } from './role_schema.js';
 /** Sentinel UUID used inside the partial unique indexes to collapse `scope_id IS NULL` into a comparable value. */
-export const PERMIT_OFFER_SCOPE_SENTINEL_UUID = '00000000-0000-0000-0000-000000000000';
+export const ROLE_GRANT_OFFER_SCOPE_SENTINEL_UUID = '00000000-0000-0000-0000-000000000000';
 /** Maximum length of the optional message attached to an offer. */
-export const PERMIT_OFFER_MESSAGE_LENGTH_MAX = 500;
+export const ROLE_GRANT_OFFER_MESSAGE_LENGTH_MAX = 500;
 /** Default TTL for a newly created offer — 30 days. Matches GitHub org-invite expiry. */
-export const PERMIT_OFFER_DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-export const PERMIT_OFFER_SCHEMA = `
-CREATE TABLE IF NOT EXISTS permit_offer (
+export const ROLE_GRANT_OFFER_DEFAULT_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const ROLE_GRANT_OFFER_SCHEMA = `
+CREATE TABLE IF NOT EXISTS role_grant_offer (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
   from_actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,
   to_account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,
   to_actor_id UUID NULL REFERENCES actor(id) ON DELETE CASCADE,
   role TEXT NOT NULL,
+  scope_kind TEXT NULL,
   scope_id UUID NULL,
   message TEXT NULL,
   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
@@ -34,38 +35,52 @@ CREATE TABLE IF NOT EXISTS permit_offer (
   decline_reason TEXT NULL,
   retracted_at TIMESTAMPTZ NULL,
   superseded_at TIMESTAMPTZ NULL,
-  resulting_permit_id UUID NULL REFERENCES permit(id) ON DELETE SET NULL,
-  CONSTRAINT permit_offer_single_terminal CHECK (
+  resulting_role_grant_id UUID NULL REFERENCES role_grant(id) ON DELETE SET NULL,
+  CONSTRAINT role_grant_offer_single_terminal CHECK (
     (accepted_at IS NOT NULL)::int
     + (declined_at IS NOT NULL)::int
     + (retracted_at IS NOT NULL)::int
     + (superseded_at IS NOT NULL)::int
     <= 1
   ),
-  CONSTRAINT permit_offer_permit_iff_accepted CHECK (
-    (accepted_at IS NOT NULL) = (resulting_permit_id IS NOT NULL)
+  CONSTRAINT role_grant_offer_role_grant_iff_accepted CHECK (
+    (accepted_at IS NOT NULL) = (resulting_role_grant_id IS NOT NULL)
   ),
-  CONSTRAINT permit_offer_reason_iff_declined CHECK (
+  CONSTRAINT role_grant_offer_reason_iff_declined CHECK (
     decline_reason IS NULL OR declined_at IS NOT NULL
+  ),
+  CONSTRAINT role_grant_offer_scope_kind_paired CHECK (
+    (scope_kind IS NULL) = (scope_id IS NULL)
   )
 )`;
 /**
- * At most one pending offer per (to_account, role, scope, from_actor).
+ * 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 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 UUID so Postgres's NULL-in-unique-index quirk does not allow
- * duplicate global pending offers. The ON CONFLICT target in
- * `query_permit_offer_create` must match this expression literally.
+ * 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 const PERMIT_OFFER_PENDING_UNIQUE_INDEX = `
-CREATE UNIQUE INDEX IF NOT EXISTS permit_offer_pending_unique
-  ON permit_offer (
+export const ROLE_GRANT_OFFER_PENDING_UNIQUE_INDEX = `
+CREATE UNIQUE INDEX IF NOT EXISTS role_grant_offer_pending_unique
+  ON role_grant_offer (
     to_account_id,
     role,
-    COALESCE(scope_id, '${PERMIT_OFFER_SCOPE_SENTINEL_UUID}'::uuid),
+    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
@@ -73,15 +88,15 @@ CREATE UNIQUE INDEX IF NOT EXISTS permit_offer_pending_unique
     AND retracted_at IS NULL
     AND superseded_at IS NULL`;
 /** Inbox lookup — pending offers for an account, ordered by soonest expiry. */
-export const PERMIT_OFFER_INBOX_INDEX = `
-CREATE INDEX IF NOT EXISTS permit_offer_inbox
-  ON permit_offer (to_account_id, expires_at)
+export const ROLE_GRANT_OFFER_INBOX_INDEX = `
+CREATE INDEX IF NOT EXISTS role_grant_offer_inbox
+  ON role_grant_offer (to_account_id, expires_at)
   WHERE accepted_at IS NULL
     AND declined_at IS NULL
     AND retracted_at IS NULL
     AND superseded_at IS NULL`;
-/** Zod schema for client-safe permit offer data. */
-export const PermitOfferJson = z
+/** Zod schema for client-safe role_grant offer data. */
+export const RoleGrantOfferJson = z
     .strictObject({
     id: Uuid.meta({ description: 'Offer id.' }),
     from_actor_id: Uuid.meta({ description: 'Actor that issued the offer.' }),
@@ -90,12 +105,15 @@ export const PermitOfferJson = z
         description: 'Optional actor-grain target on the recipient account. When set, only this actor may accept; when null any actor on `to_account_id` may accept.',
     }),
     role: RoleName.meta({ description: 'Role being offered.' }),
+    scope_kind: z.string().nullable().meta({
+        description: 'Machine-readable kind tag for `scope_id` — paired-null with `scope_id` (both null for global, both non-null for scoped).',
+    }),
     scope_id: Uuid.nullable().meta({
-        description: 'Scope the offered permit applies to (e.g. a classroom id). `null` for global permits.',
+        description: 'Scope the offered role_grant applies to (e.g. a classroom id). `null` for global role_grants.',
     }),
     message: z
         .string()
-        .max(PERMIT_OFFER_MESSAGE_LENGTH_MAX)
+        .max(ROLE_GRANT_OFFER_MESSAGE_LENGTH_MAX)
         .nullable()
         .meta({ description: 'Optional free-form note from the grantor.' }),
     created_at: z.string().meta({ description: 'ISO timestamp when the offer was created.' }),
@@ -112,7 +130,7 @@ export const PermitOfferJson = z
         .meta({ description: 'ISO timestamp when the offer was declined.' }),
     decline_reason: z
         .string()
-        .max(PERMIT_OFFER_MESSAGE_LENGTH_MAX)
+        .max(ROLE_GRANT_OFFER_MESSAGE_LENGTH_MAX)
         .nullable()
         .meta({ description: 'Optional reason given on decline.' }),
     retracted_at: z
@@ -120,20 +138,21 @@ export const PermitOfferJson = z
         .nullable()
         .meta({ description: 'ISO timestamp when the grantor retracted the offer.' }),
     superseded_at: z.string().nullable().meta({
-        description: 'ISO timestamp when this offer was obsoleted by a sibling accept or by revoke of the resulting permit.',
+        description: 'ISO timestamp when this offer was obsoleted by a sibling accept or by revoke of the resulting role_grant.',
     }),
-    resulting_permit_id: Uuid.nullable().meta({
-        description: 'Permit produced by accepting this offer. `null` until/unless accepted.',
+    resulting_role_grant_id: Uuid.nullable().meta({
+        description: 'Role grant produced by accepting this offer. `null` until/unless accepted.',
     }),
 })
-    .meta({ description: 'A permit offer — a pending grant awaiting recipient consent.' });
-/** Convert a `PermitOffer` row to its JSON payload shape. */
-export const to_permit_offer_json = (offer) => ({
+    .meta({ description: 'A role_grant offer — a pending grant awaiting recipient consent.' });
+/** Convert a `RoleGrantOffer` row to its JSON payload shape. */
+export const to_role_grant_offer_json = (offer) => ({
     id: offer.id,
     from_actor_id: offer.from_actor_id,
     to_account_id: offer.to_account_id,
     to_actor_id: offer.to_actor_id,
     role: offer.role,
+    scope_kind: offer.scope_kind,
     scope_id: offer.scope_id,
     message: offer.message,
     created_at: offer.created_at,
@@ -143,5 +162,5 @@ export const to_permit_offer_json = (offer) => ({
     decline_reason: offer.decline_reason,
     retracted_at: offer.retracted_at,
     superseded_at: offer.superseded_at,
-    resulting_permit_id: offer.resulting_permit_id,
+    resulting_role_grant_id: offer.resulting_role_grant_id,
 });

package/dist/auth/role_grant_queries.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Role grant database queries.
+ *
+ * Role grants are time-bounded, revocable grants of a role to an actor.
+ * The system is safe by default — no role_grant, no capability.
+ *
+ * @module
+ */
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { QueryDeps } from '../db/query_deps.js';
+import type { RoleGrant, CreateRoleGrantInput } from './account_schema.js';
+import { type SupersededOffer } from './role_grant_offer_schema.js';
+/**
+ * Grant a role_grant to an actor.
+ * Idempotent — if an active role_grant already exists for this actor, role, and
+ * scope, returns the existing role_grant instead of creating a duplicate.
+ *
+ * The `ON CONFLICT` target and the fallback `SELECT` both collapse `NULL`
+ * scopes via the same sentinel + index-side `'GLOBAL'` token used by the
+ * partial unique index (`role_grant_actor_role_scope_active_unique`). The
+ * `IS NOT DISTINCT FROM` form on the fallback is deliberate — plain `=`
+ * would miss the NULL-scope case where the conflict fired.
+ *
+ * `scope_kind` is paired-null with `scope_id` per the
+ * `role_grant_scope_kind_paired` CHECK; mismatched pairs raise at the DB
+ * layer rather than producing silent rows.
+ *
+ * @param deps - query dependencies
+ * @param input - the role_grant fields
+ * @returns the created or existing active role_grant
+ * @mutates `role_grant` table - inserts a row when no active role_grant matches `(actor_id, role, scope_kind, scope_id)`
+ */
+export declare const query_create_role_grant: (deps: QueryDeps, input: CreateRoleGrantInput) => Promise<RoleGrant>;
+/**
+ * Look up the role of an active role_grant (constrained to a specific
+ * actor) plus the actor's `account_id`.
+ *
+ * Used by admin routes to inspect the role_grant's role before acting
+ * (e.g., enforcing the admin-grant-path gate on revoke). The actor constraint
+ * mirrors `query_revoke_role_grant` so IDOR protection is consistent:
+ * a caller can only see role_grants belonging to the target actor.
+ *
+ * The JOIN to `actor` collapses what used to be a second
+ * `query_actor_by_id` round-trip in the revoke handler into one read,
+ * which closes the small TOCTOU window where the actor row could be
+ * deleted between the IDOR check and the actor lookup. The `account_id`
+ * is needed by the audit envelope's `target_account_id` field and the
+ * SSE/WS socket-close fan-out targeting.
+ *
+ * Returns `null` if the role_grant is not found, already revoked, or
+ * belongs to a different actor.
+ *
+ * @param deps - query dependencies
+ * @param role_grant_id - the role_grant id to look up
+ * @param actor_id - the actor that must own the role_grant
+ * @returns `{role, account_id}` on a match, or `null`
+ */
+export declare const query_role_grant_find_active_role_for_actor: (deps: QueryDeps, role_grant_id: string, actor_id: string) => Promise<{
+    role: string;
+    account_id: Uuid;
+} | null>;
+/** Result of `query_revoke_role_grant` — the revoked role_grant plus any pending offers superseded by the revoke. */
+export interface RevokeRoleGrantResult {
+    id: Uuid;
+    role: string;
+    scope_kind: string | null;
+    scope_id: Uuid | null;
+    /**
+     * Pending offers for the revoked role_grant's `(account, role, scope)` that
+     * were marked superseded as a side effect. Each entry carries its
+     * grantor's `from_account_id` so callers can fan out
+     * `role_grant_offer_supersede` notifications without a second round-trip.
+     * The caller is responsible for emitting a `role_grant_offer_supersede`
+     * audit event per entry (with `reason: 'role_grant_revoked'` and
+     * `cause_id: <revoked role_grant id>`).
+     */
+    superseded_offers: Array<SupersededOffer>;
+}
+/**
+ * Revoke a role_grant by id, constrained to a specific actor.
+ *
+ * Requires `actor_id` to prevent cross-account revocation (IDOR guard).
+ * Returns `null` if the role_grant is not found, already revoked, or belongs
+ * to a different actor.
+ *
+ * Supersedes any pending offers for the revoked role_grant's
+ * `(to_account, role, scope)` in the same transaction. Prevents the
+ * "accept a pre-revoke offer to bypass the revoke" path — any stale
+ * offer becomes terminal at revoke time. A fresh post-revoke grant
+ * requires the grantor to call `query_role_grant_offer_create` again.
+ *
+ * @param deps - query dependencies
+ * @param role_grant_id - the role_grant to revoke
+ * @param actor_id - the actor that must own the role_grant
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ * @param reason - optional free-form reason, stamped on `role_grant.revoked_reason` and surfaced to the revokee notification.
+ * @mutates `role_grant` row - sets `revoked_at`, `revoked_by`, and `revoked_reason`
+ * @mutates `role_grant_offer` rows - stamps `superseded_at` on every pending sibling for the same `(account, role, scope)`
+ */
+export declare const query_revoke_role_grant: (deps: QueryDeps, role_grant_id: Uuid, actor_id: Uuid, revoked_by: Uuid | null, reason?: string | null) => Promise<RevokeRoleGrantResult | null>;
+/**
+ * Find all active (non-revoked, non-expired) role_grants for an actor.
+ */
+export declare const query_role_grant_find_active_for_actor: (deps: QueryDeps, actor_id: string) => Promise<Array<RoleGrant>>;
+/**
+ * Check if an actor has an active role_grant for a given role.
+ *
+ * The `scope_id` parameter selects between global and scoped checks:
+ * - Omitted or `null` — matches a global role_grant (`scope_id IS NULL`).
+ *   Pre-scope callers keep their existing semantics.
+ * - A scope uuid — matches a role_grant bound to that exact scope.
+ *
+ * The `IS NOT DISTINCT FROM` comparison handles the NULL case uniformly.
+ */
+export declare const query_role_grant_has_role: (deps: QueryDeps, actor_id: string, role: string, scope_id?: string | null) => Promise<boolean>;
+/**
+ * List all role_grants for an actor (including revoked/expired).
+ */
+export declare const query_role_grant_list_for_actor: (deps: QueryDeps, actor_id: string) => Promise<Array<RoleGrant>>;
+/**
+ * Find the account ID of an account that holds an active role_grant for a given role.
+ *
+ * Joins role_grant → actor → account. Returns the first match, or `null` if none.
+ *
+ * @param deps - query dependencies
+ * @param role - the role to search for
+ * @returns the account ID, or `null`
+ */
+export declare const query_role_grant_find_account_id_for_role: (deps: QueryDeps, role: string) => Promise<string | null>;
+/** Result of `query_role_grant_revoke_for_scope` — every role_grant revoked plus every pending offer superseded by the scope-wide cascade. */
+export interface RevokeForScopeResult {
+    /**
+     * One entry per role_grant revoked by this call. Carries both the revokee's
+     * `actor_id` (the role_grant's grantee — drives `target_actor_id` audit
+     * envelopes) and `account_id` (the actor's account — drives
+     * `target_account_id` for SSE/WS socket-close fan-out). Empty array
+     * means no active role_grant was bound to the scope. `scope_kind` is
+     * surfaced for forensic completeness; the cascade itself keys on
+     * `scope_id` regardless of kind.
+     */
+    revoked: Array<{
+        role_grant_id: Uuid;
+        role: string;
+        scope_kind: string | null;
+        scope_id: Uuid;
+        actor_id: Uuid;
+        account_id: Uuid;
+    }>;
+    /**
+     * Every pending offer at the scope — tuple-matched and orphan, undifferentiated
+     * — superseded in the same cascade. Each entry carries its grantor's
+     * `from_account_id` for `role_grant_offer_supersede` notification fan-out.
+     *
+     * The caller is responsible for emitting `role_grant_offer_supersede` audit
+     * events with `reason: 'scope_destroyed'` and `cause_id: <destroyed scope row id>`
+     * per entry — the cause of every supersede here is the scope deletion,
+     * not any individual role_grant revoke (the revokes are themselves
+     * consequences of the scope going away).
+     */
+    superseded_offers: Array<SupersededOffer>;
+}
+/**
+ * Revoke every active role_grant bound to a scope and supersede every pending
+ * offer at the scope, in one cascade.
+ *
+ * Use this from a consumer's parent-scope delete handler (e.g., classroom
+ * deletion) — `role_grant.scope_id` and `role_grant_offer.scope_id` are polymorphic
+ * with no FK constraint by design, so a parent row deletion would otherwise
+ * orphan role_grants and offers. The cascade is **role-agnostic**: anything
+ * attached to the destroyed scope is cleaned up.
+ *
+ * Both updates run as separate statements inside the caller's transaction
+ * (mirrors `query_role_grant_revoke_role`'s shape). The two halves are
+ * independent — orphan pending offers can exist at a scope with no active
+ * role_grants, so the supersede half always runs even when no role_grant was
+ * revoked.
+ *
+ * @param deps - query dependencies
+ * @param scope_id - the scope whose role_grants and offers to terminate
+ * @param revoked_by - the actor performing the cascade (audit trail)
+ * @param reason - optional free-form reason, stamped on `role_grant.revoked_reason`.
+ * @returns the revoked role_grants (with `account_id` for fan-out) and superseded offers (with `from_account_id` for fan-out)
+ * @mutates `role_grant` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row at `scope_id`
+ * @mutates `role_grant_offer` table - stamps `superseded_at` on every pending row at `scope_id`
+ */
+export declare const query_role_grant_revoke_for_scope: (deps: QueryDeps, scope_id: Uuid, revoked_by: Uuid | null, reason?: string | null) => Promise<RevokeForScopeResult>;
+/** Result of `query_role_grant_revoke_role` — every role_grant revoked plus the pending offers superseded by the bulk revoke. */
+export interface RevokeRoleResult {
+    /**
+     * One entry per role_grant revoked by this call. Carries the revokee's
+     * `account_id` so callers can fan out a `role_grant_revoke` notification per
+     * scope-instance. Empty array means nothing was active for `(actor, role)`.
+     */
+    revoked: Array<{
+        role_grant_id: string;
+        role: string;
+        scope_kind: string | null;
+        scope_id: string | null;
+        account_id: string;
+    }>;
+    /**
+     * Pending offers for the actor's account+role (all scopes) superseded by
+     * the bulk revoke. Each entry carries its grantor's `from_account_id` so
+     * callers can fan out `role_grant_offer_supersede` notifications without a
+     * second round-trip.
+     */
+    superseded_offers: Array<SupersededOffer>;
+}
+/**
+ * Revoke every active role_grant an actor holds for a given role.
+ *
+ * With scoped role_grants a single actor+role tuple can hold several active
+ * role_grants (one per scope), so this revokes all of them. Pass
+ * `query_revoke_role_grant(role_grant_id, ...)` when a single scoped role_grant
+ * is the target.
+ *
+ * Also supersedes pending offers for the actor's account across every
+ * scope of this role (the actor can no longer hold the role, so any
+ * pending offer of the same role is a bypass vector).
+ *
+ * @param deps - query dependencies
+ * @param actor_id - the actor whose role_grants to revoke
+ * @param role - the role to revoke
+ * @param revoked_by - the actor who revoked it (for audit trail)
+ * @param reason - optional free-form reason, stamped on `role_grant.revoked_reason`.
+ * @returns the list of revoked role_grants (empty if none were active) and superseded pending offers
+ * @mutates `role_grant` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row for `(actor, role)`
+ * @mutates `role_grant_offer` table - stamps `superseded_at` on every matching pending offer
+ */
+export declare const query_role_grant_revoke_role: (deps: QueryDeps, actor_id: string, role: string, revoked_by: string | null, reason?: string | null) => Promise<RevokeRoleResult>;
+//# sourceMappingURL=role_grant_queries.d.ts.map

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

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