@fuzdev/fuz_app 0.54.0 → 0.56.0

package/dist/auth/permit_offer_action_specs.js

@@ -1,227 +0,0 @@
-/**
- * Permit offer RPC action specs — declarative contract for the
- * consentful-permits surface (offer lifecycle + admin revoke).
- *
- * Import this module for the specs, Input/Output schemas, `ERROR_OFFER_*`
- * reason constants, and the `all_permit_offer_action_specs` registry.
- * Handlers live in `auth/permit_offer_actions.ts`.
- *
- * Authorization enforcement: offer-lifecycle specs declare
- * `auth: 'authenticated'` and rely on `query_*` IDOR guards or in-handler
- * policy checks (e.g. `permit_offer_list`/`_history` elevate to admin only
- * when inspecting another account — an input-dependent check that can't be
- * expressed at the spec level). `permit_revoke` declares
- * `auth: {role: 'admin'}` — the RPC dispatcher's per-spec `check_action_auth`
- * gates it before the handler runs even though the endpoint hosts non-admin
- * methods alongside.
- *
- * @module
- */
-import { z } from 'zod';
-import { Uuid } from '@fuzdev/fuz_util/id.js';
-import { ERROR_ACCOUNT_NOT_FOUND, ERROR_PERMIT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE, } from '../http/error_schemas.js';
-import { RoleName } from './role_schema.js';
-import { PERMIT_OFFER_MESSAGE_LENGTH_MAX, PermitOfferJson } from './permit_offer_schema.js';
-import { PERMIT_REVOKED_REASON_LENGTH_MAX } from './account_schema.js';
-/** Error reason — caller tried to offer themselves a permit. */
-export const ERROR_OFFER_SELF_TARGET = 'offer_self_target';
-/** Error reason — offer is declined, retracted, or superseded. */
-export const ERROR_OFFER_TERMINAL = 'offer_terminal';
-/** Error reason — offer's `expires_at` has passed. */
-export const ERROR_OFFER_EXPIRED = 'offer_expired';
-/** Error reason — offer does not exist or belongs to a different recipient (404-over-403 IDOR mask). */
-export const ERROR_OFFER_NOT_FOUND = 'offer_not_found';
-/** Error reason — the offered role is not `web_grantable` (nobody may offer it via this surface). */
-export const ERROR_OFFER_ROLE_NOT_GRANTABLE = 'offer_role_not_grantable';
-/** Error reason — caller is not authorized to offer this role (default policy: caller lacks the role; consumer `authorize` callback may add further policy). */
-export const ERROR_OFFER_NOT_AUTHORIZED = 'offer_not_authorized';
-// -- Input/output schemas ---------------------------------------------------
-/** Input for `permit_offer_create`. */
-export const PermitOfferCreateInput = z.strictObject({
-    to_account_id: Uuid.meta({ description: 'Account id of the recipient.' }),
-    role: RoleName.meta({ description: 'Role being offered.' }),
-    scope_id: Uuid.nullish().meta({
-        description: 'Scope id for resource-scoped grants (e.g. classroom id). `null` for global.',
-    }),
-    message: z
-        .string()
-        .max(PERMIT_OFFER_MESSAGE_LENGTH_MAX)
-        .nullish()
-        .meta({ description: 'Optional free-form note from the grantor.' }),
-});
-/** Input for `permit_offer_accept`. */
-export const PermitOfferAcceptInput = z.strictObject({
-    offer_id: Uuid.meta({ description: 'The offer to accept.' }),
-});
-/** Input for `permit_offer_decline`. */
-export const PermitOfferDeclineInput = z.strictObject({
-    offer_id: Uuid.meta({ description: 'The offer to decline.' }),
-    reason: z
-        .string()
-        .max(PERMIT_OFFER_MESSAGE_LENGTH_MAX)
-        .nullish()
-        .meta({ description: 'Optional free-form reason given on decline.' }),
-});
-/** Input for `permit_offer_retract`. */
-export const PermitOfferRetractInput = z.strictObject({
-    offer_id: Uuid.meta({ description: 'The offer to retract.' }),
-});
-/** Input for `permit_offer_list`. `account_id` is admin-only (inspect another account's inbox). */
-export const PermitOfferListInput = z.strictObject({
-    account_id: Uuid.nullish().meta({
-        description: 'Admin-only — list offers for another account. Defaults to the caller.',
-    }),
-});
-/**
- * Input for `permit_revoke`. Admin-only mutation that revokes an active
- * permit on a target actor. `actor_id` is the natural key — permits are
- * actor-scoped, and the admin UI reads `row.actor.id` straight from the
- * listing. Deriving `actor_id` from `account_id` would collapse under
- * multi-actor accounts.
- */
-export const PermitRevokeInput = z.strictObject({
-    actor_id: Uuid.meta({ description: 'Actor whose permit to revoke.' }),
-    permit_id: Uuid.meta({ description: 'The permit to revoke.' }),
-    reason: z.string().max(PERMIT_REVOKED_REASON_LENGTH_MAX).nullish().meta({
-        description: 'Optional free-form reason; stamped on `permit.revoked_reason` and surfaced on the revokee WS notification.',
-    }),
-});
-/**
- * Input for `permit_offer_history`. Returns every offer involving the account
- * in either direction (recipient or grantor), including terminal rows, newest
- * first. `account_id` is admin-only.
- */
-export const PermitOfferHistoryInput = z.strictObject({
-    account_id: Uuid.nullish().meta({
-        description: 'Admin-only — history for another account. Defaults to the caller.',
-    }),
-    limit: z.number().int().min(1).max(500).nullish().meta({
-        description: 'Max rows to return (default 100).',
-    }),
-    offset: z.number().int().min(0).nullish().meta({
-        description: 'Pagination offset (default 0).',
-    }),
-});
-/** Output for `permit_offer_create`. */
-export const PermitOfferCreateOutput = z.strictObject({
-    offer: PermitOfferJson,
-});
-/** Output for `permit_offer_accept`. */
-export const PermitOfferAcceptOutput = z.strictObject({
-    permit_id: Uuid,
-    offer: PermitOfferJson,
-    superseded_offer_ids: z.array(Uuid),
-});
-/** Output for `permit_offer_decline` / `permit_offer_retract`. */
-export const PermitOfferOkOutput = z.strictObject({ ok: z.literal(true) });
-/** Output for `permit_offer_list`. */
-export const PermitOfferListOutput = z.strictObject({ offers: z.array(PermitOfferJson) });
-/** Output for `permit_offer_history`. */
-export const PermitOfferHistoryOutput = z.strictObject({ offers: z.array(PermitOfferJson) });
-/** Output for `permit_revoke`. */
-export const PermitRevokeOutput = z.strictObject({
-    ok: z.literal(true),
-    revoked: z.literal(true),
-});
-// -- Action specs -----------------------------------------------------------
-export const permit_offer_create_action_spec = {
-    method: 'permit_offer_create',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: 'authenticated',
-    side_effects: true,
-    input: PermitOfferCreateInput,
-    output: PermitOfferCreateOutput,
-    async: true,
-    description: 'Offer a permit to another account. Grantor must hold the offered role (or pass a consumer authorize callback); role must be web_grantable.',
-    error_reasons: [
-        ERROR_OFFER_SELF_TARGET,
-        ERROR_OFFER_ROLE_NOT_GRANTABLE,
-        ERROR_OFFER_NOT_AUTHORIZED,
-    ],
-};
-export const permit_offer_accept_action_spec = {
-    method: 'permit_offer_accept',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: 'authenticated',
-    side_effects: true,
-    input: PermitOfferAcceptInput,
-    output: PermitOfferAcceptOutput,
-    async: true,
-    description: 'Accept an offer. Atomically marks the offer accepted, inserts the permit, and supersedes sibling pending offers for the same (account, role, scope).',
-    error_reasons: [ERROR_OFFER_NOT_FOUND, ERROR_OFFER_TERMINAL, ERROR_OFFER_EXPIRED],
-};
-export const permit_offer_decline_action_spec = {
-    method: 'permit_offer_decline',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: 'authenticated',
-    side_effects: true,
-    input: PermitOfferDeclineInput,
-    output: PermitOfferOkOutput,
-    async: true,
-    description: 'Decline an offer. Recipient-only.',
-    error_reasons: [ERROR_OFFER_NOT_FOUND, ERROR_OFFER_TERMINAL],
-};
-export const permit_offer_retract_action_spec = {
-    method: 'permit_offer_retract',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: 'authenticated',
-    side_effects: true,
-    input: PermitOfferRetractInput,
-    output: PermitOfferOkOutput,
-    async: true,
-    description: 'Retract an offer. Grantor-only, pre-decision.',
-    error_reasons: [ERROR_OFFER_NOT_FOUND, ERROR_OFFER_TERMINAL],
-};
-export const permit_offer_list_action_spec = {
-    method: 'permit_offer_list',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: 'authenticated',
-    side_effects: false,
-    input: PermitOfferListInput,
-    output: PermitOfferListOutput,
-    async: true,
-    description: 'List pending, non-expired offers for the caller. Admins may pass `account_id` to inspect another account.',
-};
-export const permit_offer_history_action_spec = {
-    method: 'permit_offer_history',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: 'authenticated',
-    side_effects: false,
-    input: PermitOfferHistoryInput,
-    output: PermitOfferHistoryOutput,
-    async: true,
-    description: 'List every offer involving the caller (either direction), including terminal rows, newest first. Admins may pass `account_id` to inspect another account.',
-};
-export const permit_revoke_action_spec = {
-    method: 'permit_revoke',
-    kind: 'request_response',
-    initiator: 'frontend',
-    auth: { role: 'admin' },
-    side_effects: true,
-    input: PermitRevokeInput,
-    output: PermitRevokeOutput,
-    async: true,
-    description: 'Revoke an active permit on a target actor. Admin-only. Supersedes any pending offers for the same (account, role, scope). Fires permit_revoke + permit_offer_supersede notifications.',
-    error_reasons: [ERROR_PERMIT_NOT_FOUND, ERROR_ACCOUNT_NOT_FOUND, ERROR_ROLE_NOT_WEB_GRANTABLE],
-    rate_limit: 'account',
-};
-/**
- * All permit-offer action specs — a codegen-ready registry. Consumers spread
- * this into their own action-spec array to include offer lifecycle + revoke
- * methods in a typed client surface.
- */
-export const all_permit_offer_action_specs = [
-    permit_offer_create_action_spec,
-    permit_offer_accept_action_spec,
-    permit_offer_decline_action_spec,
-    permit_offer_retract_action_spec,
-    permit_offer_list_action_spec,
-    permit_offer_history_action_spec,
-    permit_revoke_action_spec,
-];

package/dist/auth/permit_offer_actions.d.ts

@@ -1,110 +0,0 @@
-/**
- * Permit offer RPC action handlers — the consentful-permits action surface.
- *
- * Seven actions: six offer-lifecycle methods (create / accept / decline /
- * retract / list / history) plus `permit_revoke` (admin-only). All mount
- * on a consumer's JSON-RPC endpoint via `create_rpc_endpoint`. The action
- * specs themselves live in `auth/permit_offer_action_specs.ts`. Mutations
- * declare `side_effects: true` so the RPC dispatcher wraps the handler in
- * a DB transaction; `permit_offer_list` and `permit_offer_history` declare
- * `side_effects: false` so they are addressable via GET.
- *
- * Authorization:
- * - `permit_offer_create` — the grantor must hold an active permit for the
- *   role being offered, and that role must be `web_grantable`. Consumers
- *   needing a richer policy (e.g., "teacher may offer student in *their*
- *   classroom") pass an `authorize` callback that overrides the default.
- * - `permit_offer_accept` / `permit_offer_decline` — keyed to the caller's
- *   account; `query_*` helpers enforce the IDOR guard.
- * - `permit_offer_retract` — keyed to the caller's actor.
- * - `permit_offer_list` / `permit_offer_history` — self by default;
- *   `{account_id}` is admin-only.
- * - `permit_revoke` — spec-level `auth: {role: 'admin'}`; the RPC
- *   dispatcher rejects non-admin callers before the handler runs.
- *   `web_grantable` gate prevents revoking keeper/daemon-scoped roles
- *   via this surface. Keys on `actor_id` to survive multi-actor accounts.
- *
- * Audit events are emitted in-transaction by the query layer (atomic with
- * the permit write on accept/revoke) or by the handler via
- * `audit_log_fire_and_forget` for single-event lifecycle transitions.
- * `on_audit_event` (SSE broadcast) fires post-commit in both paths.
- *
- * WS notifications fan out post-commit via `emit_after_commit` when a
- * `notification_sender` is wired: offer lifecycle transitions notify the
- * counterparty, `permit_revoke` notifies the revokee plus each superseded
- * pending offer's grantor.
- *
- * @module
- */
-import { type ActionContext, type RpcAction } from '../actions/action_rpc.js';
-import { type RoleSchemaResult } from './role_schema.js';
-import { type RequestContext } from './request_context.js';
-import type { RouteFactoryDeps } from './deps.js';
-import { type NotificationSender } from './permit_offer_notifications.js';
-/**
- * Authorization callback for `permit_offer_create`. Returns `true` to allow,
- * `false` to reject (handler converts to `forbidden`).
- *
- * Provided with the fully-resolved request context and the parsed input
- * (pre-TTL, pre-normalization). Consumers override the default to implement
- * policies like "teacher may offer classroom_student only in classrooms they
- * teach".
- */
-export type PermitOfferCreateAuthorize = (auth: RequestContext, input: {
-    to_account_id: string;
-    role: string;
-    scope_id: string | null;
-}, deps: Pick<RouteFactoryDeps, 'log'>, ctx: ActionContext) => boolean | Promise<boolean>;
-/** Options for `create_permit_offer_actions`. */
-export interface PermitOfferActionOptions {
-    /**
-     * Role schema result from `create_role_schema()`. Defaults to builtin roles only.
-     * The `role_options` map is read for `web_grantable` lookups.
-     */
-    roles?: RoleSchemaResult;
-    /** TTL applied to newly-created offers. Defaults to `PERMIT_OFFER_DEFAULT_TTL_MS`. */
-    default_ttl_ms?: number;
-    /**
-     * Custom authorization for `permit_offer_create`. The default requires the
-     * caller to hold an active permit for the offered role *and* the role to
-     * be `web_grantable`. Consumers with richer policies (scope-aware, chained
-     * roles) override this.
-     */
-    authorize?: PermitOfferCreateAuthorize;
-}
-/**
- * Authorization callback that admits any admin and otherwise falls back to
- * the symmetric default (caller must hold the offered role globally).
- *
- * The `web_grantable` filter in `create_handler` runs **before** the
- * `authorize` callback, so this never sees non-web-grantable roles. Drop
- * into `create_permit_offer_actions({authorize: authorize_admin_or_holder})`
- * (or any factory that forwards `authorize`, e.g. `create_standard_rpc_actions`)
- * for the common "admins offer anything; users offer what they hold"
- * pattern. Scope-aware policies (e.g. classroom_teacher offering
- * classroom_student in their own scope) wrap this and short-circuit `true`
- * before delegating.
- */
-export declare const authorize_admin_or_holder: PermitOfferCreateAuthorize;
-/**
- * Dependencies for `create_permit_offer_actions`.
- *
- * `notification_sender` is optional — when absent, WS fan-out is silently
- * skipped. Consumers wiring `BackendWebsocketTransport` assign its instance
- * directly (the transport's `send_to_account` signature accepts the broader
- * `JsonrpcMessageFromServerToClient`, which is contravariantly compatible).
- */
-export interface PermitOfferActionDeps extends Pick<RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config'> {
-    /** Optional WS fan-out primitive. `null` or absent → notifications skipped. */
-    notification_sender?: NotificationSender | null;
-}
-/**
- * Create the seven permit-offer RPC actions (six offer-lifecycle methods
- * plus `permit_revoke`).
- *
- * @param deps - `PermitOfferActionDeps` — `log`, `on_audit_event`, optional `audit_log_config` (slice of `AppDeps`); optional `notification_sender` for WS fan-out
- * @param options - role schema, default TTL, authorization override
- * @returns the `RpcAction` array to spread into a `create_rpc_endpoint` call
- */
-export declare const create_permit_offer_actions: (deps: PermitOfferActionDeps, options?: PermitOfferActionOptions) => Array<RpcAction>;
-//# sourceMappingURL=permit_offer_actions.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"permit_offer_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/permit_offer_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAa,KAAK,aAAa,EAAE,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAC;AAGxF,OAAO,EAAmC,KAAK,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAkBzF,OAAO,EAA4B,KAAK,cAAc,EAAC,MAAM,sBAAsB,CAAC;AACpF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAChD,OAAO,EAON,KAAK,kBAAkB,EACvB,MAAM,iCAAiC,CAAC;AAmCzC;;;;;;;;GAQG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACxC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAC,EACrE,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,EACnC,GAAG,EAAE,aAAa,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,iDAAiD;AACjD,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,0BAA0B,CAAC;CACvC;AA4BD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,0BASvC,CAAC;AAcF;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAClD,gBAAgB,EAChB,KAAK,GAAG,gBAAgB,GAAG,kBAAkB,CAC7C;IACA,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GACvC,MAAM,qBAAqB,EAC3B,UAAS,wBAA6B,KACpC,KAAK,CAAC,SAAS,CAudjB,CAAC"}