@fuzdev/fuz_app 0.55.0 → 0.56.0

package/dist/auth/permit_queries.d.ts

@@ -1,222 +0,0 @@
-/**
- * Permit database queries.
- *
- * Permits are time-bounded, revocable grants of a role to an actor.
- * The system is safe by default — no permit, no capability.
- *
- * @module
- */
-import type { Uuid } from '@fuzdev/fuz_util/id.js';
-import type { QueryDeps } from '../db/query_deps.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, 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
- * @mutates `permit` table - inserts a row when no active permit matches `(actor_id, role, scope_id)`
- */
-export declare const query_grant_permit: (deps: QueryDeps, input: GrantPermitInput) => Promise<Permit>;
-/**
- * Look up the role of an active permit (constrained to a specific
- * actor) plus the actor's `account_id`.
- *
- * Used by admin routes to inspect the permit's role before acting
- * (e.g., enforcing `web_grantable` on revoke). The actor constraint
- * mirrors `query_revoke_permit` so IDOR protection is consistent:
- * a caller can only see permits 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 permit is not found, already revoked, or
- * belongs to a different actor.
- *
- * @param deps - query dependencies
- * @param permit_id - the permit id to look up
- * @param actor_id - the actor that must own the permit
- * @returns `{role, account_id}` on a match, or `null`
- */
-export declare const query_permit_find_active_role_for_actor: (deps: QueryDeps, permit_id: string, actor_id: string) => Promise<{
-    role: string;
-    account_id: Uuid;
-} | 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.
- *
- * 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.
- * @mutates `permit` row - sets `revoked_at`, `revoked_by`, and `revoked_reason`
- * @mutates `permit_offer` rows - stamps `superseded_at` on every pending sibling for the same `(account, role, scope)`
- */
-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, scope_id?: string | null) => Promise<boolean>;
-/**
- * List all permits for an actor (including revoked/expired).
- */
-export declare const query_permit_list_for_actor: (deps: QueryDeps, actor_id: string) => Promise<Array<Permit>>;
-/**
- * Find the account ID of an account that holds an active permit for a given role.
- *
- * Joins permit → 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_permit_find_account_id_for_role: (deps: QueryDeps, role: string) => Promise<string | null>;
-/** Result of `query_permit_revoke_for_scope` — every permit revoked plus every pending offer superseded by the scope-wide cascade. */
-export interface RevokeForScopeResult {
-    /**
-     * One entry per permit revoked by this call. Carries both the revokee's
-     * `actor_id` (the permit'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 permit was bound to the scope.
-     */
-    revoked: Array<{
-        permit_id: Uuid;
-        role: string;
-        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 `permit_offer_supersede` notification fan-out.
-     *
-     * The caller is responsible for emitting `permit_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 permit revoke (the revokes are themselves
-     * consequences of the scope going away).
-     */
-    superseded_offers: Array<SupersededOffer>;
-}
-/**
- * Revoke every active permit 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) — `permit.scope_id` and `permit_offer.scope_id` are polymorphic
- * with no FK constraint by design, so a parent row deletion would otherwise
- * orphan permits 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_permit_revoke_role`'s shape). The two halves are
- * independent — orphan pending offers can exist at a scope with no active
- * permits, so the supersede half always runs even when no permit was
- * revoked.
- *
- * @param deps - query dependencies
- * @param scope_id - the scope whose permits and offers to terminate
- * @param revoked_by - the actor performing the cascade (audit trail)
- * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
- * @returns the revoked permits (with `account_id` for fan-out) and superseded offers (with `from_account_id` for fan-out)
- * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row at `scope_id`
- * @mutates `permit_offer` table - stamps `superseded_at` on every pending row at `scope_id`
- */
-export declare const query_permit_revoke_for_scope: (deps: QueryDeps, scope_id: Uuid, revoked_by: Uuid | null, reason?: string | null) => Promise<RevokeForScopeResult>;
-/** 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 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.
- *
- * 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 permits 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 `permit.revoked_reason`.
- * @returns the list of revoked permits (empty if none were active) and superseded pending offers
- * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row for `(actor, role)`
- * @mutates `permit_offer` table - stamps `superseded_at` on every matching pending offer
- */
-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 +0,0 @@
-{"version":3,"file":"permit_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_queries.ts"],"names":[],"mappings":"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"}

package/dist/auth/permit_queries.js

@@ -1,305 +0,0 @@
-/**
- * Permit database queries.
- *
- * Permits are time-bounded, revocable grants of a role to an actor.
- * The system is safe by default — no permit, no capability.
- *
- * @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, 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
- * @mutates `permit` table - inserts a row when no active permit matches `(actor_id, role, scope_id)`
- */
-export const query_grant_permit = async (deps, input) => {
-    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.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 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');
-};
-/**
- * Look up the role of an active permit (constrained to a specific
- * actor) plus the actor's `account_id`.
- *
- * Used by admin routes to inspect the permit's role before acting
- * (e.g., enforcing `web_grantable` on revoke). The actor constraint
- * mirrors `query_revoke_permit` so IDOR protection is consistent:
- * a caller can only see permits 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 permit is not found, already revoked, or
- * belongs to a different actor.
- *
- * @param deps - query dependencies
- * @param permit_id - the permit id to look up
- * @param actor_id - the actor that must own the permit
- * @returns `{role, account_id}` on a match, or `null`
- */
-export const query_permit_find_active_role_for_actor = async (deps, permit_id, actor_id) => {
-    const row = await deps.db.query_one(`SELECT permit.role, actor.account_id
-		   FROM permit
-		   JOIN actor ON actor.id = permit.actor_id
-		  WHERE permit.id = $1 AND permit.actor_id = $2 AND permit.revoked_at IS NULL`, [permit_id, actor_id]);
-    return row ?? null;
-};
-/**
- * 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.
- *
- * 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.
- * @mutates `permit` row - sets `revoked_at`, `revoked_by`, and `revoked_reason`
- * @mutates `permit_offer` rows - stamps `superseded_at` on every pending sibling for the same `(account, role, scope)`
- */
-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, 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.
- */
-export const query_permit_find_active_for_actor = async (deps, actor_id) => {
-    return deps.db.query(`SELECT * FROM permit
-		 WHERE actor_id = $1
-		   AND revoked_at IS NULL
-		   AND (expires_at IS NULL OR expires_at > NOW())
-		 ORDER BY created_at`, [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, 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, scope_id ?? null]);
-    return row?.exists ?? false;
-};
-/**
- * List all permits for an actor (including revoked/expired).
- */
-export const query_permit_list_for_actor = async (deps, actor_id) => {
-    return deps.db.query(`SELECT * FROM permit WHERE actor_id = $1 ORDER BY created_at DESC`, [actor_id]);
-};
-/**
- * Find the account ID of an account that holds an active permit for a given role.
- *
- * Joins permit → 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 const query_permit_find_account_id_for_role = async (deps, role) => {
-    const row = await deps.db.query_one(`SELECT a.id AS account_id
-		 FROM permit p
-		 JOIN actor act ON act.id = p.actor_id
-		 JOIN account a ON a.id = act.account_id
-		 WHERE p.role = $1
-		   AND p.revoked_at IS NULL
-		   AND (p.expires_at IS NULL OR p.expires_at > NOW())
-		 LIMIT 1`, [role]);
-    return row?.account_id ?? null;
-};
-/**
- * Revoke every active permit 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) — `permit.scope_id` and `permit_offer.scope_id` are polymorphic
- * with no FK constraint by design, so a parent row deletion would otherwise
- * orphan permits 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_permit_revoke_role`'s shape). The two halves are
- * independent — orphan pending offers can exist at a scope with no active
- * permits, so the supersede half always runs even when no permit was
- * revoked.
- *
- * @param deps - query dependencies
- * @param scope_id - the scope whose permits and offers to terminate
- * @param revoked_by - the actor performing the cascade (audit trail)
- * @param reason - optional free-form reason, stamped on `permit.revoked_reason`.
- * @returns the revoked permits (with `account_id` for fan-out) and superseded offers (with `from_account_id` for fan-out)
- * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row at `scope_id`
- * @mutates `permit_offer` table - stamps `superseded_at` on every pending row at `scope_id`
- */
-export const query_permit_revoke_for_scope = async (deps, scope_id, revoked_by, reason) => {
-    // Revoke every active permit at the scope. CTE returns `actor_id` directly
-    // from the permit row (drives `target_actor_id` audit envelopes); a join
-    // against `actor` resolves `account_id` for `target_account_id`
-    // + WS/SSE socket-close fan-out, all in one round-trip.
-    const revoked = await deps.db.query(`WITH updated AS (
-			UPDATE permit
-			SET revoked_at = NOW(), revoked_by = $2, revoked_reason = $3
-			WHERE scope_id = $1 AND revoked_at IS NULL
-			RETURNING id, role, scope_id, actor_id
-		)
-		SELECT u.id AS permit_id, u.role, u.scope_id, u.actor_id, a.account_id
-		FROM updated u
-		JOIN actor a ON a.id = u.actor_id`, [scope_id, revoked_by ?? null, reason ?? null]);
-    // Supersede every pending offer at the scope — tuple-matched or orphan,
-    // no distinction. The cause of every supersede in this cascade is the
-    // scope deletion; offers tuple-matched to a revoked permit are not
-    // tagged separately because the revoke is itself a consequence of the
-    // scope going away.
-    const superseded_offers = await deps.db.query(`WITH updated AS (
-			UPDATE permit_offer o
-			SET superseded_at = NOW()
-			WHERE o.scope_id = $1
-			  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`, [scope_id]);
-    return { revoked, superseded_offers };
-};
-/**
- * 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.
- *
- * 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 permits 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 `permit.revoked_reason`.
- * @returns the list of revoked permits (empty if none were active) and superseded pending offers
- * @mutates `permit` table - sets `revoked_at`/`revoked_by`/`revoked_reason` on every active row for `(actor, role)`
- * @mutates `permit_offer` table - stamps `superseded_at` on every matching pending offer
- */
-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/require_keeper.d.ts

@@ -1,20 +0,0 @@
-/**
- * Keeper credential type guard.
- *
- * Two-part check:
- * 1. Credential type must be `daemon_token` (not session cookie, not API token).
- * 2. Account must hold active keeper permit.
- *
- * Both must pass. A session cookie from the bootstrap account still fails check #1.
- *
- * @module
- */
-import type { MiddlewareHandler } from 'hono';
-/**
- * Middleware that requires keeper credentials.
- *
- * Returns 401 if unauthenticated, 403 if credential type is not
- * `daemon_token` or if the keeper role is missing.
- */
-export declare const require_keeper: MiddlewareHandler;
-//# sourceMappingURL=require_keeper.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"require_keeper.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/require_keeper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,MAAM,CAAC;AAW5C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,iBAmB5B,CAAC"}

package/dist/auth/require_keeper.js

@@ -1,35 +0,0 @@
-/**
- * Keeper credential type guard.
- *
- * Two-part check:
- * 1. Credential type must be `daemon_token` (not session cookie, not API token).
- * 2. Account must hold active keeper permit.
- *
- * Both must pass. A session cookie from the bootstrap account still fails check #1.
- *
- * @module
- */
-import { get_request_context, has_role } from './request_context.js';
-import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
-import { ROLE_KEEPER } from './role_schema.js';
-import { ERROR_AUTHENTICATION_REQUIRED, ERROR_INSUFFICIENT_PERMISSIONS, ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, } from '../http/error_schemas.js';
-/**
- * Middleware that requires keeper credentials.
- *
- * Returns 401 if unauthenticated, 403 if credential type is not
- * `daemon_token` or if the keeper role is missing.
- */
-export const require_keeper = async (c, next) => {
-    const ctx = get_request_context(c);
-    if (!ctx) {
-        return c.json({ error: ERROR_AUTHENTICATION_REQUIRED }, 401);
-    }
-    const credential_type = c.get(CREDENTIAL_TYPE_KEY);
-    if (credential_type !== 'daemon_token') {
-        return c.json({ error: ERROR_KEEPER_REQUIRES_DAEMON_TOKEN, credential_type: credential_type ?? 'none' }, 403);
-    }
-    if (!has_role(ctx, ROLE_KEEPER)) {
-        return c.json({ error: ERROR_INSUFFICIENT_PERMISSIONS, required_role: ROLE_KEEPER }, 403);
-    }
-    await next();
-};

package/dist/auth/route_guards.d.ts

@@ -1,27 +0,0 @@
-/**
- * Auth guard resolver for the route spec system.
- *
- * Maps `RouteAuth` discriminants to two-phase auth middleware sets.
- * `pre_validation` carries the 401 check (`require_auth`) so
- * unauthenticated callers never see route-shape information from input
- * parse failures. `post_authorization` carries the 403 role / keeper
- * checks because they read the `RequestContext` populated by the
- * dispatcher's authorization phase.
- *
- * Injected into `apply_route_specs` to decouple the generic HTTP
- * framework (`http/route_spec.ts`) from auth-specific middleware.
- *
- * @module
- */
-import type { AuthGuardResolver } from '../http/route_spec.js';
-/**
- * Standard auth guard resolver for fuz_app.
- *
- * Maps `RouteAuth` to middleware:
- * - `none` → no guards
- * - `authenticated` → pre-validation `require_auth`
- * - `role` → pre-validation `require_auth` + post-authorization `require_role(role)`
- * - `keeper` → pre-validation `require_auth` + post-authorization `require_keeper`
- */
-export declare const fuz_auth_guard_resolver: AuthGuardResolver;
-//# sourceMappingURL=route_guards.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"route_guards.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/route_guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAWrC,CAAC"}

package/dist/auth/route_guards.js

@@ -1,38 +0,0 @@
-/**
- * Auth guard resolver for the route spec system.
- *
- * Maps `RouteAuth` discriminants to two-phase auth middleware sets.
- * `pre_validation` carries the 401 check (`require_auth`) so
- * unauthenticated callers never see route-shape information from input
- * parse failures. `post_authorization` carries the 403 role / keeper
- * checks because they read the `RequestContext` populated by the
- * dispatcher's authorization phase.
- *
- * Injected into `apply_route_specs` to decouple the generic HTTP
- * framework (`http/route_spec.ts`) from auth-specific middleware.
- *
- * @module
- */
-import { require_auth, require_role } from './request_context.js';
-import { require_keeper } from './require_keeper.js';
-/**
- * Standard auth guard resolver for fuz_app.
- *
- * Maps `RouteAuth` to middleware:
- * - `none` → no guards
- * - `authenticated` → pre-validation `require_auth`
- * - `role` → pre-validation `require_auth` + post-authorization `require_role(role)`
- * - `keeper` → pre-validation `require_auth` + post-authorization `require_keeper`
- */
-export const fuz_auth_guard_resolver = (auth) => {
-    switch (auth.type) {
-        case 'none':
-            return { pre_validation: [], post_authorization: [] };
-        case 'authenticated':
-            return { pre_validation: [require_auth], post_authorization: [] };
-        case 'role':
-            return { pre_validation: [require_auth], post_authorization: [require_role(auth.role)] };
-        case 'keeper':
-            return { pre_validation: [require_auth], post_authorization: [require_keeper] };
-    }
-};