@fuzdev/fuz_app 0.30.0 → 0.31.0

package/dist/auth/permit_offer_schema.js

@@ -0,0 +1,142 @@
+/**
+ * Permit 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`):
+ * 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
+ * produced by `query_accept_offer`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { Uuid } from '../uuid.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';
+/** Maximum length of the optional message attached to an offer. */
+export const PERMIT_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 (
+  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,
+  role TEXT NOT NULL,
+  scope_id UUID NULL,
+  message TEXT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  expires_at TIMESTAMPTZ NOT NULL,
+  accepted_at TIMESTAMPTZ NULL,
+  declined_at TIMESTAMPTZ NULL,
+  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 (
+    (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 permit_offer_reason_iff_declined CHECK (
+    decline_reason IS NULL OR declined_at IS NOT NULL
+  )
+)`;
+/**
+ * At most one pending offer per (to_account, role, 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.
+ */
+export const PERMIT_OFFER_PENDING_UNIQUE_INDEX = `
+CREATE UNIQUE INDEX IF NOT EXISTS permit_offer_pending_unique
+  ON permit_offer (
+    to_account_id,
+    role,
+    COALESCE(scope_id, '${PERMIT_OFFER_SCOPE_SENTINEL_UUID}'::uuid),
+    from_actor_id
+  )
+  WHERE accepted_at IS NULL
+    AND declined_at IS NULL
+    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)
+  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
+    .strictObject({
+    id: Uuid.meta({ description: 'Offer id.' }),
+    from_actor_id: Uuid.meta({ description: 'Actor that issued the offer.' }),
+    to_account_id: Uuid.meta({ description: 'Account the offer is directed to.' }),
+    role: RoleName.meta({ description: 'Role being offered.' }),
+    scope_id: Uuid.nullable().meta({
+        description: 'Scope the offered permit applies to (e.g. a classroom id). `null` for global permits.',
+    }),
+    message: z
+        .string()
+        .max(PERMIT_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.' }),
+    expires_at: z
+        .string()
+        .meta({ description: 'ISO timestamp after which the offer is no longer valid.' }),
+    accepted_at: z
+        .string()
+        .nullable()
+        .meta({ description: 'ISO timestamp when the offer was accepted.' }),
+    declined_at: z
+        .string()
+        .nullable()
+        .meta({ description: 'ISO timestamp when the offer was declined.' }),
+    decline_reason: z
+        .string()
+        .max(PERMIT_OFFER_MESSAGE_LENGTH_MAX)
+        .nullable()
+        .meta({ description: 'Optional reason given on decline.' }),
+    retracted_at: z
+        .string()
+        .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.',
+    }),
+    resulting_permit_id: Uuid.nullable().meta({
+        description: 'Permit 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) => ({
+    id: offer.id,
+    from_actor_id: offer.from_actor_id,
+    to_account_id: offer.to_account_id,
+    role: offer.role,
+    scope_id: offer.scope_id,
+    message: offer.message,
+    created_at: offer.created_at,
+    expires_at: offer.expires_at,
+    accepted_at: offer.accepted_at,
+    declined_at: offer.declined_at,
+    decline_reason: offer.decline_reason,
+    retracted_at: offer.retracted_at,
+    superseded_at: offer.superseded_at,
+    resulting_permit_id: offer.resulting_permit_id,
+});

package/dist/auth/permit_queries.d.ts

@@ -7,11 +7,19 @@
  * @module
  */
 import type { QueryDeps } from '../db/query_deps.js';
+import type { Uuid } from '../uuid.js';
 import type { Permit, GrantPermitInput } from './account_schema.js';
+import { type SupersededOffer } from './permit_offer_schema.js';
 /**
  * Grant a permit to an actor.
- * Idempotent — if an active permit already exists for this actor and role,
- * returns the existing permit instead of creating a duplicate.
+ * Idempotent — if an active permit already exists for this actor, role, and
+ * scope, returns the existing permit instead of creating a duplicate.
+ *
+ * The `ON CONFLICT` target and the fallback `SELECT` both collapse `NULL`
+ * scopes via the same sentinel used by the partial unique index
+ * (`permit_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.
  *
  * @param deps - query dependencies
  * @param input - the permit fields
@@ -37,30 +45,57 @@ export declare const query_grant_permit: (deps: QueryDeps, input: GrantPermitInp
 export declare const query_permit_find_active_role_for_actor: (deps: QueryDeps, permit_id: string, actor_id: string) => Promise<{
     role: string;
 } | null>;
+/** Result of `query_revoke_permit` — the revoked permit plus any pending offers superseded by the revoke. */
+export interface RevokePermitResult {
+    id: Uuid;
+    role: string;
+    scope_id: Uuid | null;
+    /**
+     * Pending offers for the revoked permit'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
+     * `permit_offer_supersede` notifications without a second round-trip.
+     * The caller is responsible for emitting a `permit_offer_supersede`
+     * audit event per entry (with `reason: 'permit_revoked'` and
+     * `cause_id: <revoked permit id>`).
+     */
+    superseded_offers: Array<SupersededOffer>;
+}
 /**
  * Revoke a permit by id, constrained to a specific actor.
  *
  * Requires `actor_id` to prevent cross-account revocation (IDOR guard).
  * Returns `null` if the permit is not found, already revoked, or belongs
- * to a different actor. Returns `{id, role}` on success for audit logging.
+ * to a different actor.
+ *
+ * Supersedes any pending offers for the revoked permit'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_permit_offer_create` again.
  *
  * @param deps - query dependencies
  * @param permit_id - the permit to revoke
  * @param actor_id - the actor that must own the permit
  * @param revoked_by - the actor who revoked it (for audit trail)
+ * @param reason - optional free-form reason, stamped on `permit.revoked_reason` and surfaced to the revokee notification.
  */
-export declare const query_revoke_permit: (deps: QueryDeps, permit_id: string, actor_id: string, revoked_by: string | null) => Promise<{
-    id: string;
-    role: string;
-} | null>;
+export declare const query_revoke_permit: (deps: QueryDeps, permit_id: Uuid, actor_id: Uuid, revoked_by: Uuid | null, reason?: string | null) => Promise<RevokePermitResult | null>;
 /**
  * Find all active (non-revoked, non-expired) permits for an actor.
  */
 export declare const query_permit_find_active_for_actor: (deps: QueryDeps, actor_id: string) => Promise<Array<Permit>>;
 /**
  * Check if an actor has an active permit for a given role.
+ *
+ * The `scope_id` parameter selects between global and scoped checks:
+ * - Omitted or `null` — matches a global permit (`scope_id IS NULL`).
+ *   Pre-scope callers keep their existing semantics.
+ * - A scope uuid — matches a permit bound to that exact scope.
+ *
+ * The `IS NOT DISTINCT FROM` comparison handles the NULL case uniformly.
  */
-export declare const query_permit_has_role: (deps: QueryDeps, actor_id: string, role: string) => Promise<boolean>;
+export declare const query_permit_has_role: (deps: QueryDeps, actor_id: string, role: string, scope_id?: string | null) => Promise<boolean>;
 /**
  * List all permits for an actor (including revoked/expired).
  */
@@ -75,17 +110,45 @@ export declare const query_permit_list_for_actor: (deps: QueryDeps, actor_id: st
  * @returns the account ID, or `null`
  */
 export declare const query_permit_find_account_id_for_role: (deps: QueryDeps, role: string) => Promise<string | null>;
+/** Result of `query_permit_revoke_role` — every permit revoked plus the pending offers superseded by the bulk revoke. */
+export interface RevokeRoleResult {
+    /**
+     * One entry per permit revoked by this call. Carries the revokee's
+     * `account_id` so callers can fan out a `permit_revoke` notification per
+     * scope-instance. Empty array means nothing was active for `(actor, role)`.
+     */
+    revoked: Array<{
+        permit_id: string;
+        role: string;
+        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 `permit_offer_supersede` notifications without a
+     * second round-trip.
+     */
+    superseded_offers: Array<SupersededOffer>;
+}
 /**
- * Revoke the active permit for an actor with a given role.
+ * Revoke every active permit an actor holds for a given role.
+ *
+ * With scoped permits a single actor+role tuple can hold several active
+ * permits (one per scope), so this revokes all of them. Pass
+ * `query_revoke_permit(permit_id, ...)` when a single scoped permit
+ * is the target.
  *
- * Due to the unique partial index on `(actor_id, role) WHERE revoked_at IS NULL`,
- * at most one active permit exists per actor+role combination.
+ * 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 permit to revoke
+ * @param actor_id - the actor whose permits to revoke
  * @param role - the role to revoke
  * @param revoked_by - the actor who revoked it (for audit trail)
- * @returns `true` if a permit was revoked, `false` if none was active
+ * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
+ * @returns the list of revoked permits (empty if none were active) and superseded pending offers
  */
-export declare const query_permit_revoke_role: (deps: QueryDeps, actor_id: string, role: string, revoked_by: string | null) => Promise<boolean>;
+export declare const query_permit_revoke_role: (deps: QueryDeps, actor_id: string, role: string, revoked_by: string | null, reason?: string | null) => Promise<RevokeRoleResult>;
 //# sourceMappingURL=permit_queries.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"permit_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAGlE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,gBAAgB,KACrB,OAAO,CAAC,MAAM,CAiBhB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,UAAU,MAAM,KACd,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAO/B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,UAAU,MAAM,EAChB,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAQ3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CASvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,KACV,OAAO,CAAC,OAAO,CAYjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAKvB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAavB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC"}
+{"version":3,"file":"permit_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AACrC,OAAO,KAAK,EAAC,MAAM,EAAE,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAmC,KAAK,eAAe,EAAC,MAAM,0BAA0B,CAAC;AAEhG;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,gBAAgB,KACrB,OAAO,CAAC,MAAM,CA4BhB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uCAAuC,GACnD,MAAM,SAAS,EACf,WAAW,MAAM,EACjB,UAAU,MAAM,KACd,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAO/B,CAAC;AAEF,6GAA6G;AAC7G,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB;;;;;;;;OAQG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,WAAW,IAAI,EACf,UAAU,IAAI,EACd,YAAY,IAAI,GAAG,IAAI,EACvB,SAAS,MAAM,GAAG,IAAI,KACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAsCnC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CASvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,WAAW,MAAM,GAAG,IAAI,KACtB,OAAO,CAAC,OAAO,CAajB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAKvB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAavB,CAAC;AAEF,yHAAyH;AACzH,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,OAAO,EAAE,KAAK,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAC/F;;;;;OAKG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,YAAY,MAAM,GAAG,IAAI,EACzB,SAAS,MAAM,GAAG,IAAI,KACpB,OAAO,CAAC,gBAAgB,CA2C1B,CAAC"}

package/dist/auth/permit_queries.js

@@ -7,26 +7,44 @@
  * @module
  */
 import { assert_row } from '../db/assert_row.js';
+import { PERMIT_OFFER_SCOPE_SENTINEL_UUID } from './permit_offer_schema.js';
 /**
  * Grant a permit to an actor.
- * Idempotent — if an active permit already exists for this actor and role,
- * returns the existing permit instead of creating a duplicate.
+ * Idempotent — if an active permit already exists for this actor, role, and
+ * scope, returns the existing permit instead of creating a duplicate.
+ *
+ * The `ON CONFLICT` target and the fallback `SELECT` both collapse `NULL`
+ * scopes via the same sentinel used by the partial unique index
+ * (`permit_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.
  *
  * @param deps - query dependencies
  * @param input - the permit fields
  * @returns the created or existing active permit
  */
 export const query_grant_permit = async (deps, input) => {
-    const inserted = await deps.db.query_one(`INSERT INTO permit (actor_id, role, expires_at, granted_by)
-		 VALUES ($1, $2, $3, $4)
-		 ON CONFLICT (actor_id, role) WHERE revoked_at IS NULL
+    const inserted = await deps.db.query_one(`INSERT INTO permit (actor_id, role, scope_id, expires_at, granted_by, source_offer_id)
+		 VALUES ($1, $2, $3, $4, $5, $6)
+		 ON CONFLICT (actor_id, role, COALESCE(scope_id, '${PERMIT_OFFER_SCOPE_SENTINEL_UUID}'::uuid))
+		   WHERE revoked_at IS NULL
 		 DO NOTHING
-		 RETURNING *`, [input.actor_id, input.role, input.expires_at?.toISOString() ?? null, input.granted_by ?? null]);
+		 RETURNING *`, [
+        input.actor_id,
+        input.role,
+        input.scope_id ?? null,
+        input.expires_at?.toISOString() ?? null,
+        input.granted_by ?? null,
+        input.source_offer_id ?? null,
+    ]);
     if (inserted)
         return inserted;
     // Active permit already exists — return it (idempotent grant).
     const existing = await deps.db.query_one(`SELECT * FROM permit
-		 WHERE actor_id = $1 AND role = $2 AND revoked_at IS NULL`, [input.actor_id, input.role]);
+		 WHERE actor_id = $1
+		   AND role = $2
+		   AND scope_id IS NOT DISTINCT FROM $3
+		   AND revoked_at IS NULL`, [input.actor_id, input.role, input.scope_id ?? null]);
     return assert_row(existing, 'idempotent permit grant');
 };
 /**
@@ -55,18 +73,53 @@ export const query_permit_find_active_role_for_actor = async (deps, permit_id, a
  *
  * Requires `actor_id` to prevent cross-account revocation (IDOR guard).
  * Returns `null` if the permit is not found, already revoked, or belongs
- * to a different actor. Returns `{id, role}` on success for audit logging.
+ * to a different actor.
+ *
+ * Supersedes any pending offers for the revoked permit'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_permit_offer_create` again.
  *
  * @param deps - query dependencies
  * @param permit_id - the permit to revoke
  * @param actor_id - the actor that must own the permit
  * @param revoked_by - the actor who revoked it (for audit trail)
+ * @param reason - optional free-form reason, stamped on `permit.revoked_reason` and surfaced to the revokee notification.
  */
-export const query_revoke_permit = async (deps, permit_id, actor_id, revoked_by) => {
-    const rows = await deps.db.query(`UPDATE permit SET revoked_at = NOW(), revoked_by = $3
+export const query_revoke_permit = async (deps, permit_id, actor_id, revoked_by, reason) => {
+    const rows = await deps.db.query(`UPDATE permit SET revoked_at = NOW(), revoked_by = $3, revoked_reason = $4
 		 WHERE id = $1 AND actor_id = $2 AND revoked_at IS NULL
-		 RETURNING id, role`, [permit_id, actor_id, revoked_by ?? null]);
-    return rows[0] ?? null;
+		 RETURNING id, role, scope_id`, [permit_id, actor_id, revoked_by ?? null, reason ?? null]);
+    const revoked = rows[0];
+    if (!revoked)
+        return null;
+    // CTE joins `actor` after the UPDATE so each superseded row carries the
+    // grantor's `account_id` — callers fan out `permit_offer_supersede`
+    // notifications to that account without a second round-trip.
+    const superseded_offers = await deps.db.query(`WITH updated AS (
+			UPDATE permit_offer o
+			SET superseded_at = NOW()
+			FROM actor a
+			WHERE a.id = $1
+			  AND o.to_account_id = a.account_id
+			  AND o.role = $2
+			  AND o.scope_id IS NOT DISTINCT FROM $3
+			  AND o.accepted_at IS NULL
+			  AND o.declined_at IS NULL
+			  AND o.retracted_at IS NULL
+			  AND o.superseded_at IS NULL
+			RETURNING o.*
+		)
+		SELECT u.*, grantor.account_id AS from_account_id
+		FROM updated u
+		JOIN actor grantor ON grantor.id = u.from_actor_id`, [actor_id, revoked.role, revoked.scope_id]);
+    return {
+        id: revoked.id,
+        role: revoked.role,
+        scope_id: revoked.scope_id,
+        superseded_offers,
+    };
 };
 /**
  * Find all active (non-revoked, non-expired) permits for an actor.
@@ -80,15 +133,23 @@ export const query_permit_find_active_for_actor = async (deps, actor_id) => {
 };
 /**
  * Check if an actor has an active permit for a given role.
+ *
+ * The `scope_id` parameter selects between global and scoped checks:
+ * - Omitted or `null` — matches a global permit (`scope_id IS NULL`).
+ *   Pre-scope callers keep their existing semantics.
+ * - A scope uuid — matches a permit bound to that exact scope.
+ *
+ * The `IS NOT DISTINCT FROM` comparison handles the NULL case uniformly.
  */
-export const query_permit_has_role = async (deps, actor_id, role) => {
+export const query_permit_has_role = async (deps, actor_id, role, scope_id) => {
     const row = await deps.db.query_one(`SELECT EXISTS(
 			SELECT 1 FROM permit
 			WHERE actor_id = $1
 			  AND role = $2
+			  AND scope_id IS NOT DISTINCT FROM $3
 			  AND revoked_at IS NULL
 			  AND (expires_at IS NULL OR expires_at > NOW())
-		 ) AS exists`, [actor_id, role]);
+		 ) AS exists`, [actor_id, role, scope_id ?? null]);
     return row?.exists ?? false;
 };
 /**
@@ -118,20 +179,54 @@ export const query_permit_find_account_id_for_role = async (deps, role) => {
     return row?.account_id ?? null;
 };
 /**
- * Revoke the active permit for an actor with a given role.
+ * Revoke every active permit an actor holds for a given role.
+ *
+ * With scoped permits a single actor+role tuple can hold several active
+ * permits (one per scope), so this revokes all of them. Pass
+ * `query_revoke_permit(permit_id, ...)` when a single scoped permit
+ * is the target.
  *
- * Due to the unique partial index on `(actor_id, role) WHERE revoked_at IS NULL`,
- * at most one active permit exists per actor+role combination.
+ * 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 permit to revoke
+ * @param actor_id - the actor whose permits to revoke
  * @param role - the role to revoke
  * @param revoked_by - the actor who revoked it (for audit trail)
- * @returns `true` if a permit was revoked, `false` if none was active
+ * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
+ * @returns the list of revoked permits (empty if none were active) and superseded pending offers
  */
-export const query_permit_revoke_role = async (deps, actor_id, role, revoked_by) => {
-    const rows = await deps.db.query(`UPDATE permit SET revoked_at = NOW(), revoked_by = $3
-		 WHERE actor_id = $1 AND role = $2 AND revoked_at IS NULL
-		 RETURNING id`, [actor_id, role, revoked_by ?? null]);
-    return rows.length > 0;
+export const query_permit_revoke_role = async (deps, actor_id, role, revoked_by, reason) => {
+    // CTE pulls the revokee's `account_id` via a join on `actor` so callers
+    // can address the revokee without an extra round-trip.
+    const revoked = await deps.db.query(`WITH updated AS (
+			UPDATE permit
+			SET revoked_at = NOW(), revoked_by = $3, revoked_reason = $4
+			WHERE actor_id = $1 AND role = $2 AND revoked_at IS NULL
+			RETURNING id, role, scope_id, actor_id
+		)
+		SELECT u.id AS permit_id, u.role, u.scope_id, a.account_id
+		FROM updated u
+		JOIN actor a ON a.id = u.actor_id`, [actor_id, role, revoked_by ?? null, reason ?? null]);
+    if (revoked.length === 0) {
+        return { revoked: [], superseded_offers: [] };
+    }
+    const superseded_offers = await deps.db.query(`WITH updated AS (
+			UPDATE permit_offer o
+			SET superseded_at = NOW()
+			FROM actor a
+			WHERE a.id = $1
+			  AND o.to_account_id = a.account_id
+			  AND o.role = $2
+			  AND o.accepted_at IS NULL
+			  AND o.declined_at IS NULL
+			  AND o.retracted_at IS NULL
+			  AND o.superseded_at IS NULL
+			RETURNING o.*
+		)
+		SELECT u.*, grantor.account_id AS from_account_id
+		FROM updated u
+		JOIN actor grantor ON grantor.id = u.from_actor_id`, [actor_id, role]);
+    return { revoked, superseded_offers };
 };

package/dist/auth/session_queries.d.ts

@@ -88,8 +88,10 @@ export declare const query_session_list_for_account: (deps: QueryDeps, account_i
  *
  * Race safety: this function must run inside a transaction alongside the
  * INSERT that created the new session. All callers satisfy this requirement:
- * - `POST /login` and `POST /tokens/create` use the default `transaction: true`
- *   (framework-managed transaction wrapping in `apply_route_specs`)
+ * - `POST /login` uses the default `transaction: true` (framework-managed
+ *   transaction wrapping in `apply_route_specs`)
+ * - The `account_token_create` RPC handler runs under the dispatcher's
+ *   transaction path because its spec declares `side_effects: true`
  * - `POST /bootstrap` and `POST /signup` manage their own transactions
  *   and pass the transaction-scoped `deps` to `create_session_and_set_cookie`
  *

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

@@ -1 +1 @@
-{"version":3,"file":"session_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAElD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,YAAY,IAAI,KACd,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAKjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAY3F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAK5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAYhB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,cAAW,KACT,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CASjD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,CAKnF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACjD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAMd,CAAC"}
+{"version":3,"file":"session_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/session_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAErD,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,QAA2B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAElD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAEzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,EAClB,YAAY,IAAI,KACd,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,WAAW,GAAG,SAAS,CAKjC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,EAAE,YAAY,MAAM,KAAG,OAAO,CAAC,IAAI,CAY3F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,IAAI,CAEd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,YAAY,MAAM,KAChB,OAAO,CAAC,OAAO,CAMjB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,GAChD,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,MAAM,CAMhB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAK5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAc,MAAM,KAClB,OAAO,CAAC,MAAM,CAYhB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,cAAW,KACT,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CASjD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,MAAM,CAKnF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,iBAAiB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACjD,KAAK,MAAM,KACT,OAAO,CAAC,IAAI,CAMd,CAAC"}

package/dist/auth/session_queries.js

@@ -118,8 +118,10 @@ export const query_session_list_for_account = async (deps, account_id, limit = 5
  *
  * Race safety: this function must run inside a transaction alongside the
  * INSERT that created the new session. All callers satisfy this requirement:
- * - `POST /login` and `POST /tokens/create` use the default `transaction: true`
- *   (framework-managed transaction wrapping in `apply_route_specs`)
+ * - `POST /login` uses the default `transaction: true` (framework-managed
+ *   transaction wrapping in `apply_route_specs`)
+ * - The `account_token_create` RPC handler runs under the dispatcher's
+ *   transaction path because its spec declares `side_effects: true`
  * - `POST /bootstrap` and `POST /signup` manage their own transactions
  *   and pass the transaction-scoped `deps` to `create_session_and_set_cookie`
  *

package/dist/auth/signup_routes.d.ts

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { z } from 'zod';
 import { type RouteSpec } from '../http/route_spec.js';
 import { type RateLimiter } from '../rate_limiter.js';
 import type { RouteFactoryDeps } from './deps.js';
@@ -21,6 +22,18 @@ export interface SignupRouteOptions extends AuthSessionRouteOptions {
     /** Mutable ref to app settings — when `open_signup` is true, invite check is skipped. */
     app_settings: AppSettings;
 }
+/** Input for `POST /signup`. `email` is optional and must match any referenced invite. */
+export declare const SignupInput: z.ZodObject<{
+    username: z.ZodString;
+    password: z.ZodString;
+    email: z.ZodOptional<z.ZodEmail>;
+}, z.core.$strict>;
+export type SignupInput = z.infer<typeof SignupInput>;
+/** Output for `POST /signup`. Session cookie is the operative side effect. */
+export declare const SignupOutput: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export type SignupOutput = z.infer<typeof SignupOutput>;
 /**
  * Create signup route specs for account creation.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CAqIjB,CAAC"}
+{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAID,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,YAAY;;kBAEvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CAyHjB,CAAC"}

package/dist/auth/signup_routes.js

@@ -19,6 +19,17 @@ import { rate_limit_exceeded_response } from '../rate_limiter.js';
 import { ERROR_NO_MATCHING_INVITE, ERROR_SIGNUP_CONFLICT } from '../http/error_schemas.js';
 import { audit_log_fire_and_forget } from './audit_log_queries.js';
 import { is_pg_unique_violation } from '../db/pg_error.js';
+// -- Input/output schemas ---------------------------------------------------
+/** Input for `POST /signup`. `email` is optional and must match any referenced invite. */
+export const SignupInput = z.strictObject({
+    username: Username,
+    password: Password,
+    email: Email.optional(),
+});
+/** Output for `POST /signup`. Session cookie is the operative side effect. */
+export const SignupOutput = z.strictObject({
+    ok: z.literal(true),
+});
 /**
  * Create signup route specs for account creation.
  *
@@ -36,12 +47,8 @@ export const create_signup_route_specs = (deps, options) => {
             auth: { type: 'none' },
             description: 'Create account (invite-gated or open signup)',
             transaction: false, // manages its own transaction for TOCTOU safety
-            input: z.strictObject({
-                username: Username,
-                password: Password,
-                email: Email.optional(),
-            }),
-            output: z.strictObject({ ok: z.literal(true) }),
+            input: SignupInput,
+            output: SignupOutput,
             rate_limit: signup_account_rate_limiter ? 'both' : 'ip',
             errors: {
                 403: z.looseObject({ error: z.literal(ERROR_NO_MATCHING_INVITE) }),
@@ -56,7 +63,7 @@ export const create_signup_route_specs = (deps, options) => {
                         return rate_limit_exceeded_response(c, check.retry_after);
                     }
                 }
-                const { username, password: pw, email, } = get_route_input(c);
+                const { username, password: pw, email } = get_route_input(c);
                 // Per-account rate limit check (after input parsing, before DB work)
                 const account_key = username.toLowerCase();
                 if (signup_account_rate_limiter) {