@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/auth/permit_offer_notifications.js

@@ -1,182 +0,0 @@
-/**
- * Permit offer WebSocket notification specs, builders, and the narrow
- * `NotificationSender` interface that decouples offer/revoke send sites
- * from `BackendWebsocketTransport`.
- *
- * Six `RemoteNotificationActionSpec`s cover the consentful-permits
- * lifecycle events the server pushes to affected accounts:
- *
- * - `permit_offer_received` → recipient's sockets when an offer is created
- * - `permit_offer_retracted` → recipient's sockets when a grantor retracts
- * - `permit_offer_accepted` → grantor's sockets when the recipient accepts
- * - `permit_offer_declined` → grantor's sockets when the recipient declines
- * - `permit_offer_supersede` → grantor's sockets when a sibling accept,
- *   a revoke of the resulting permit, or destruction of the parent scope
- *   row obsoletes their pending offer
- * - `permit_revoke` → revokee's sockets when one of their active permits
- *   is revoked (companion to the `permit_revoke` audit event)
- *
- * Payloads are flat and normalized — `PermitOfferJson` for the offer-lifecycle
- * notifications (decline reason rides on `offer.decline_reason`, not a
- * sibling field), and `{permit_id, role, scope_id, reason?}` for `permit_revoke`. The
- * revokee/grantor/recipient account id travels via the send target (the
- * `NotificationSender.send_to_account` argument), not in the payload.
- *
- * The specs surface as `EventSpec`s via `create_action_event_spec` — callers
- * append `PERMIT_OFFER_NOTIFICATION_SPECS` to their `event_specs` on
- * `create_app_server` so the surface reflects them and DEV-mode broadcast
- * validation catches payload drift.
- *
- * @module
- */
-import { z } from 'zod';
-import { Uuid as UuidSchema } from '@fuzdev/fuz_util/id.js';
-import { create_action_event_spec } from '../actions/action_bridge.js';
-import { create_jsonrpc_notification } from '../http/jsonrpc_helpers.js';
-import { RoleName } from './role_schema.js';
-import { PermitOfferJson } from './permit_offer_schema.js';
-import { PERMIT_REVOKED_REASON_LENGTH_MAX } from './account_schema.js';
-// -- Method constants -------------------------------------------------------
-export const PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD = 'permit_offer_received';
-export const PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD = 'permit_offer_retracted';
-export const PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD = 'permit_offer_accepted';
-export const PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD = 'permit_offer_declined';
-export const PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD = 'permit_offer_supersede';
-export const PERMIT_REVOKE_NOTIFICATION_METHOD = 'permit_revoke';
-// -- Params schemas ---------------------------------------------------------
-/** Params for `permit_offer_received` — offer delivered to its recipient. */
-export const PermitOfferReceivedParams = z.strictObject({
-    offer: PermitOfferJson,
-});
-/** Params for `permit_offer_retracted` — grantor-side retraction. */
-export const PermitOfferRetractedParams = z.strictObject({
-    offer: PermitOfferJson,
-});
-/** Params for `permit_offer_accepted` — recipient accepted the offer. */
-export const PermitOfferAcceptedParams = z.strictObject({
-    offer: PermitOfferJson,
-});
-/**
- * Params for `permit_offer_declined`. The decline reason (if any) rides along
- * inside `offer.decline_reason` — the DB stamps it on the offer row during
- * decline, so a sibling `reason` field would just duplicate it.
- */
-export const PermitOfferDeclinedParams = z.strictObject({
-    offer: PermitOfferJson,
-});
-/**
- * Params for `permit_offer_supersede`. Fires to the grantor's sockets when
- * their pending offer is obsoleted — either by a sibling accept
- * (`reason: 'sibling_accepted'`), by revoke of the resulting permit
- * (`reason: 'permit_revoked'`), or by deletion of the parent scope row
- * the offer was bound to (`reason: 'scope_destroyed'`). `cause_id` points
- * at the accepted offer id, the revoked permit id, or the destroyed scope
- * row id respectively.
- */
-export const PermitOfferSupersedeParams = z.strictObject({
-    offer: PermitOfferJson,
-    reason: z.enum(['sibling_accepted', 'permit_revoked', 'scope_destroyed']),
-    cause_id: UuidSchema,
-});
-/**
- * Params for `permit_revoke`. Delivered to the revokee's sockets when one
- * of their active permits is revoked. Flat wire shape — `revoked_by` is
- * admin-UI-visible but deliberately omitted here (the revokee doesn't need
- * to learn the admin's identity). Target account is implicit in the send
- * target.
- */
-export const PermitRevokeParams = z.strictObject({
-    permit_id: UuidSchema,
-    role: RoleName,
-    scope_id: UuidSchema.nullable(),
-    reason: z.string().max(PERMIT_REVOKED_REASON_LENGTH_MAX).nullable(),
-});
-// -- Action specs -----------------------------------------------------------
-export const permit_offer_received_notification_spec = {
-    method: PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD,
-    kind: 'remote_notification',
-    initiator: 'backend',
-    auth: null,
-    side_effects: true,
-    input: PermitOfferReceivedParams,
-    output: z.void(),
-    async: true,
-    description: 'A new permit offer arrived in the recipient’s inbox.',
-};
-export const permit_offer_retracted_notification_spec = {
-    method: PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD,
-    kind: 'remote_notification',
-    initiator: 'backend',
-    auth: null,
-    side_effects: true,
-    input: PermitOfferRetractedParams,
-    output: z.void(),
-    async: true,
-    description: 'A pending permit offer was retracted by its grantor.',
-};
-export const permit_offer_accepted_notification_spec = {
-    method: PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD,
-    kind: 'remote_notification',
-    initiator: 'backend',
-    auth: null,
-    side_effects: true,
-    input: PermitOfferAcceptedParams,
-    output: z.void(),
-    async: true,
-    description: 'A pending permit offer was accepted by its recipient.',
-};
-export const permit_offer_declined_notification_spec = {
-    method: PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD,
-    kind: 'remote_notification',
-    initiator: 'backend',
-    auth: null,
-    side_effects: true,
-    input: PermitOfferDeclinedParams,
-    output: z.void(),
-    async: true,
-    description: 'A pending permit offer was declined by its recipient.',
-};
-export const permit_offer_supersede_notification_spec = {
-    method: PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD,
-    kind: 'remote_notification',
-    initiator: 'backend',
-    auth: null,
-    side_effects: true,
-    input: PermitOfferSupersedeParams,
-    output: z.void(),
-    async: true,
-    description: 'A grantor’s pending permit offer was obsoleted by a sibling accept, by revoke of the resulting permit, or by destruction of the parent scope row.',
-};
-export const permit_revoke_notification_spec = {
-    method: PERMIT_REVOKE_NOTIFICATION_METHOD,
-    kind: 'remote_notification',
-    initiator: 'backend',
-    auth: null,
-    side_effects: true,
-    input: PermitRevokeParams,
-    output: z.void(),
-    async: true,
-    description: 'An active permit on the revokee’s account was revoked.',
-};
-// -- EventSpec surface ------------------------------------------------------
-/**
- * SSE/WS event specs for the consentful-permits notification surface.
- *
- * Pass to `create_app_server`'s `event_specs` so the attack surface reflects
- * them and DEV-mode `create_validated_broadcaster` catches payload drift.
- */
-export const PERMIT_OFFER_NOTIFICATION_SPECS = [
-    create_action_event_spec(permit_offer_received_notification_spec),
-    create_action_event_spec(permit_offer_retracted_notification_spec),
-    create_action_event_spec(permit_offer_accepted_notification_spec),
-    create_action_event_spec(permit_offer_declined_notification_spec),
-    create_action_event_spec(permit_offer_supersede_notification_spec),
-    create_action_event_spec(permit_revoke_notification_spec),
-];
-// -- Notification builders --------------------------------------------------
-export const build_permit_offer_received_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD, params);
-export const build_permit_offer_retracted_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD, params);
-export const build_permit_offer_accepted_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD, params);
-export const build_permit_offer_declined_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD, params);
-export const build_permit_offer_supersede_notification = (params) => create_jsonrpc_notification(PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD, params);
-export const build_permit_revoke_notification = (params) => create_jsonrpc_notification(PERMIT_REVOKE_NOTIFICATION_METHOD, params);

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

@@ -1 +0,0 @@
-{"version":3,"file":"permit_offer_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_offer_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAEN,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AAEzD;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;gBAC7C,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACrC,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACtC,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;;CAKpD;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;gBAC3C,QAAQ,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,oCAAqC,SAAQ,KAAK;;CAK9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,OAAO,sBAAsB,KAC3B,OAAO,CAAC,WAAW,CAgDrB,CAAC;AAEF,mGAAmG;AACnG,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD;;;;;OAKG;IACH,eAAe,EAAE,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,eAAe,MAAM,EACrB,QAAQ,MAAM,GAAG,IAAI,KACnB,OAAO,CAAC,aAAa,GAAG,IAAI,CAoB9B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,SAAS,EACf,UAAU,MAAM,EAChB,eAAe,MAAM,KACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAe5B,CAAC;AA8BF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,eAAe,MAAM,KACnB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAY5B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,cAAW,EACX,eAAU,KACR,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAS5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,WAAW,GAAG,IAAI,CAY5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,KACb,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAU5B,CAAC;AAEF,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,IAAI,CAAC;IACf,mGAAmG;IACnG,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,IAAI,CAAC;IACf,gDAAgD;IAChD,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB;AAED,yHAAyH;AACzH,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,4IAA4I;IAC5I,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAC1C,sLAAsL;IACtL,YAAY,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,OAAO,gBAAgB,KACrB,OAAO,CAAC,iBAAiB,CA8N3B,CAAC"}

package/dist/auth/permit_offer_schema.d.ts

@@ -1,125 +0,0 @@
-/**
- * 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 '@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 PERMIT_OFFER_SCOPE_SENTINEL_UUID = "00000000-0000-0000-0000-000000000000";
-/** Maximum length of the optional message attached to an offer. */
-export declare const PERMIT_OFFER_MESSAGE_LENGTH_MAX = 500;
-/** Default TTL for a newly created offer — 30 days. Matches GitHub org-invite expiry. */
-export declare const PERMIT_OFFER_DEFAULT_TTL_MS: number;
-export declare const PERMIT_OFFER_SCHEMA = "\nCREATE TABLE IF NOT EXISTS permit_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_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_permit_id UUID NULL REFERENCES permit(id) ON DELETE SET NULL,\n  CONSTRAINT permit_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 permit_offer_permit_iff_accepted CHECK (\n    (accepted_at IS NOT NULL) = (resulting_permit_id IS NOT NULL)\n  ),\n  CONSTRAINT permit_offer_reason_iff_declined CHECK (\n    decline_reason IS NULL OR declined_at IS NOT NULL\n  )\n)";
-/**
- * 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 declare const PERMIT_OFFER_PENDING_UNIQUE_INDEX = "\nCREATE UNIQUE INDEX IF NOT EXISTS permit_offer_pending_unique\n  ON permit_offer (\n    to_account_id,\n    role,\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 PERMIT_OFFER_INBOX_INDEX = "\nCREATE INDEX IF NOT EXISTS permit_offer_inbox\n  ON permit_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";
-/** Permit offer row as returned by the database. */
-export interface PermitOffer {
-    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 `permit_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
-     * (`permit_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;
-    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 permit this offer's role+scope maps to)
-     * or the resulting permit 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_permit_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 `permit_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 PermitOffer {
-    from_account_id: Uuid;
-}
-/**
- * Input for `query_permit_offer_create`.
- *
- * `expires_at` must be supplied — the query layer does not apply a default,
- * so callers can thread their own TTL (typically `PERMIT_OFFER_DEFAULT_TTL_MS`).
- */
-export interface CreatePermitOfferInput {
-    from_actor_id: Uuid;
-    to_account_id: Uuid;
-    /**
-     * Optional actor-grain target on the recipient account. When set,
-     * `query_permit_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;
-    scope_id?: Uuid | null;
-    message?: string | null;
-    expires_at: Date;
-}
-/** Zod schema for client-safe permit offer data. */
-export declare const PermitOfferJson: 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_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_permit_id: z.ZodNullable<z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">>;
-}, z.core.$strict>;
-export type PermitOfferJson = z.infer<typeof PermitOfferJson>;
-/** Convert a `PermitOffer` row to its JSON payload shape. */
-export declare const to_permit_offer_json: (offer: PermitOffer) => PermitOfferJson;
-//# sourceMappingURL=permit_offer_schema.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"permit_offer_schema.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_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,gCAAgC,yCAAyC,CAAC;AAEvF,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,yFAAyF;AACzF,eAAO,MAAM,2BAA2B,QAA2B,CAAC;AAEpE,eAAO,MAAM,mBAAmB,8oCA8B9B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iCAAiC,8UAWhB,CAAC;AAE/B,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,0NAMP,CAAC;AAQ/B,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC3B,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,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,mBAAmB,EAAE,IAAI,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IACnD,eAAe,EAAE,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACtC,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,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,CAAC;CACjB;AAED,oDAAoD;AACpD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;kBAgDyD,CAAC;AACtF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,GAAI,OAAO,WAAW,KAAG,eAgBxD,CAAC"}

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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"}