api #

AcceptOfferInput

Input for query_accept_offer.

`offer_id`

type Uuid

`to_account_id`

Account of the accepting recipient — IDOR guard against another account accepting the offer.

type Uuid

`ip`

Optional IP to stamp on the audit events.

type string | null

AcceptOfferResult
#

AcceptOfferResult

Result of query_accept_offer — the permit produced (new or pre-existing on race), plus the (now-accepted) offer.

`permit`

type Permit

`offer`

type PermitOffer

`created`

true if this call is the one that accepted the offer (new permit inserted); false on a race returning the already-created permit.

type boolean

`superseded_offers`

Sibling offers superseded by this accept — empty on the race-loser path.
Each entry carries its grantor's from_account_id so the caller can
fan out permit_offer_supersede notifications without a second
round-trip.

type Array<SupersededOffer>

`audit_events`

Audit events emitted in-transaction — fed back through the normal on_audit_event broadcast chain by the caller. Includes one permit_offer_supersede per superseded sibling.

type Array<AuditLogEvent>

Account
#

Account

Account — authentication identity. You log in as an account.

`id`

type Uuid

`username`

type Username

`email`

type Email | null

`email_verified`

type boolean

`password_hash`

type string

`created_at`

type string

`created_by`

type Uuid | null

`updated_at`

type string

`updated_by`

type Uuid | null

ACCOUNT_EMAIL_INDEX
#

"\nCREATE UNIQUE INDEX IF NOT EXISTS idx_account_email ON account (LOWER(email)) WHERE email IS NOT NULL"

ACCOUNT_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS account (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  username TEXT UNIQUE NOT NULL,\n  email TEXT,\n  email_verified BOOLEAN NOT NULL DEFAULT false,\n  password_hash TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  created_by UUID,\n  updated_at TIMESTAMPTZ ...

Auth table DDL — CREATE TABLE, index, and seed statements.
Consumed by auth/migrations.ts. Separated from auth/account_schema.ts
to isolate DDL concerns from runtime types.

account_session_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: false; input: ZodVoid; output: ZodObject<{ sessions: ZodArray<ZodObject<{ id: ZodString; account_id: $ZodBranded<...>; created_at: ZodString; expires_at: ZodString; last_seen_at: ZodString; }, $strict>>; }, $stric...

account_session_revoke_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ session_id: ZodString; }, $strict>; output: ZodObject<...>; async: true; description: string; }

account_session_revoke_all_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodVoid; output: ZodObject<{ ok: ZodLiteral<true>; count: ZodNumber; }, $strict>; async: true; description: string; }

account_sessions_rpc_context
#

{ get: () => () => AccountSessionsRpc | null; set: (value?: (() => AccountSessionsRpc | null) | undefined) => () => AccountSessionsRpc | null; }

Svelte context carrying the reactive AccountSessionsRpc accessor. Mirrors
the admin-side RPC contexts. Unset context falls back to () => null so
components render the usual "rpc adapter not wired" state.

account_token_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ name: ZodDefault<ZodString>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

account_token_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: false; input: ZodVoid; output: ZodObject<{ tokens: ZodArray<ZodObject<{ id: ZodString; account_id: $ZodBranded<...>; ... 4 more ...; created_at: ZodString; }, $strict>>; }, $strict>; async: true; description: stri...

account_token_revoke_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ token_id: ZodString; }, $strict>; output: ZodObject<...>; async: true; description: string; }

ACCOUNT_USERNAME_CI_INDEX
#

"\nCREATE UNIQUE INDEX IF NOT EXISTS idx_account_username_ci ON account (LOWER(username))"

account_verify_action_spec
#

auth/account_actions.ts view source

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: false; input: ZodVoid; output: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<...>; email_verified: ZodBoolean; created_at: ZodString; }, $strict>; async: true; descri...

AccountActionDeps
#

AccountActionDeps

Dependencies for create_account_actions.
Shares shape with AdminActionDeps / PermitOfferActionDeps so consumers
can pass the same deps to every action factory. audit_log_config is
carried through AppDeps and consumed by audit_log_fire_and_forget;
absent → defaults to BUILTIN_AUDIT_LOG_CONFIG.

AccountActionOptions
#

auth/account_actions.ts view source

AccountActionOptions

Options for create_account_actions.

`max_tokens`

Max API tokens per account. When set, account_token_create enforces the
cap via query_api_token_enforce_limit inside the same transaction —
oldest tokens are evicted once the cap is exceeded. Default
DEFAULT_MAX_TOKENS; pass null to disable the cap.

type number | null

AccountRouteOptions
#

ui/AccountSessions.svelte view source

AccountRouteOptions

Per-factory configuration for account route specs.

inheritance

extends:

AuthSessionRouteOptions

`login_account_rate_limiter`

Rate limiter for login attempts, keyed by submitted username. Pass null to disable.

type RateLimiter | null

`max_sessions`

Max active sessions per account. Evicts oldest on login. Default 5, null disables.

type number | null

`login_fail_floor_ms`

Minimum wall-clock time (ms) for login 401 responses. Set to 0 or a
negative number to disable (e.g., in tests). Default
DEFAULT_LOGIN_FAIL_FLOOR_MS.

type number

`login_fail_jitter_ms`

Uniform jitter window (±ms) layered on the floor. Set to 0 to disable
jitter while keeping the floor. Default DEFAULT_LOGIN_FAIL_JITTER_MS.

type number

AccountSessions
#

AccountSessionsRpc
#

AccountSessionsRpc

Narrow RPC surface consumed by AccountSessionsState. Consumers adapt their
typed RPC client to this shape. Mirrors the other per-domain *Rpc
interfaces (AdminAccountsRpc, AuditLogRpc, AdminInvitesRpc).
The three methods wrap the corresponding action specs on
auth/account_actions.ts:
- list → account_session_list
- revoke → account_session_revoke (IDOR-guarded by account_id server-side)
- revoke_all → account_session_revoke_all

`list`

type () => Promise<{sessions: Array<AuthSessionJson>}>

`revoke`

type (params: {session_id: string}) => Promise<{ok: true; revoked: boolean}>

`revoke_all`

type () => Promise<{ok: true; count: number}>

AccountSessionsState
#

inheritance

extends:

Loadable

`sessions`

type Array<AuthSessionJson>

`active_count`

readonly

`constructor`

type new (options?: AccountSessionsStateOptions | undefined): AccountSessionsState

`options?`

type AccountSessionsStateOptions | undefined

optional

`fetch`

type (): Promise<void>

returns Promise<void>

`revoke`

type (id: string): Promise<void>

`id`

type string

returns Promise<void>

`revoke_all`

type (): Promise<void>

returns Promise<void>

AccountSessionsStateOptions
#

AccountSessionsStateOptions

`get_rpc`

Reactive accessor for the RPC adapter; returns null when unwired.
Matches the get_rpc pattern on the admin state classes.

type () => AccountSessionsRpc | null

AccountStatusInput
#

ZodNull

Input for GET /api/account/status. No parameters — caller is the subject.

AccountStatusOptions
#

AccountStatusOptions

Options for the account status route spec.

`path`

Override the default path (/api/account/status).

type string

`bootstrap_status`

Runtime bootstrap status — when available, 401 responses include bootstrap_available.

type {available: boolean}

AccountStatusOutput
#

ZodObject<{ account: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; }, $strict>; actor: ZodObject<...>; permits: ZodArray<...>; }, $strict>

Output for GET /api/account/status on the authenticated path.
account and actor are the caller's own identity entities (v1 is 1:1
account/actor, but actor is first-class so consumers don't have to
derive actor_id from the permit list). Permits are already
active-filtered by build_request_context via
query_permit_find_active_for_actor — revoked_at / revoked_by /
revoked_reason are never populated here, so PermitSummaryJson
carries the fields a client actually needs (including scope_id for
per-scope auth decisions).

AccountStatusUnauthenticatedError
#

actions/action_types.ts view source

ZodObject<{ error: ZodLiteral<"authentication_required">; bootstrap_available: ZodOptional<ZodBoolean>; }, $loose>

Error body for GET /api/account/status on the unauthenticated path.

Action
#

Action<TCtx>

A spec paired with its optional handler — the composable unit passed to
register_action_ws and create_rpc_client. The server uses
both fields; the client reads only spec (the handler is
ignored, harmless). Shared fuz_app primitives (e.g. heartbeat_action)
export a complete tuple so consumers spread them into both sides'
actions array without inventing per-repo ping plumbing.
Left open for future fields (rate_limit, ACL, middleware hooks) so
additions attach to the action itself instead of scattering across
parallel arrays.

generics

`TCtx`

constraint BaseHandlerContext

default BaseHandlerContext

`spec`

type ActionSpecUnion

`handler`

Server-side handler. Ignored by the client. Omit for client-only specs.

type WsActionHandler<TCtx>

ACTION_EVENT_PHASE_BY_KIND
#

Record<"request_response" | "remote_notification" | "local_call", readonly ("send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute")[]>

ACTION_EVENT_PHASE_TRANSITIONS
#

Record<"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "send_request" | "receive_request" | ... 7 more ... | null>

ACTION_EVENT_STEP_TRANSITIONS
#

Record<"initial" | "parsed" | "handling" | "handled" | "failed", readonly ("initial" | "parsed" | "handling" | "handled" | "failed")[]>

ACTION_METHOD_ENUM_KINDS_ALL
#

ReadonlySet<ActionMethodEnumKind>

Default emit set — every enum kind.

ActionAuth
#

ZodUnion<readonly [ZodLiteral<"public">, ZodLiteral<"authenticated">, ZodLiteral<"keeper">, ZodObject<{ role: ZodString; }, $strict>]>

ActionContext
#

ActionContext

Per-request context provided to RPC action handlers.
Extends RouteContext with auth identity and logger.
auth is RequestContext | null — handlers for authenticated
actions can narrow via the auth middleware guarantee.

`auth`

The authenticated identity, or null for public routes.

type RequestContext | null

`request_id`

The JSON-RPC request ID from the envelope.

type JsonrpcRequestId

`db`

Transaction-scoped for mutations, pool-level for reads.

type Db

`background_db`

Always pool-level — for fire-and-forget effects that outlive the transaction.

type Db

`pending_effects`

Fire-and-forget side effects — push here for post-response flushing.

type Array<Promise<void>>

`client_ip`

Resolved client IP from the trusted-proxy middleware — 'unknown' if the
middleware wasn't in the stack (e.g. WS dispatch) or couldn't resolve.
Thread into audit_log_fire_and_forget as ip: ctx.client_ip for every
user-initiated action so RPC audit rows match the REST convention. Pass
null only for rows written outside a request (e.g. the
permit_offer_expire cleanup sweep in auth/cleanup.ts).

type string

`log`

Logger instance.

type Logger

`notify`

Send a request-scoped JSON-RPC notification to the originator.
On streaming transports (WebSocket) this routes to the originating
connection only. On the HTTP RPC transport this is a no-op with a
DEV-mode warn — non-streaming transports have no channel for mid-
request notifications. The streams field on an ActionSpec names
the notification method this handler is expected to emit.

type (method: string, params: unknown) => void

`signal`

AbortSignal that fires when the originating request is cancelled
(client disconnect on HTTP, socket close on WebSocket). Streaming
handlers should check this for early termination.

type AbortSignal

ActionEvent
#

Action event that manages the lifecycle of an action through its state machine.

generics

`TMethod`

constraint string

default string

readonly

`spec`

method narrows to TMethod so consumers passing a typed TApi to
create_rpc_client get event.spec.method typed as the union of
their API's method names rather than plain string. The runtime
value comes from lookup_action_spec(method) keyed off the Proxy
get trap, so the narrowing matches the dispatched method.

type ActionSpecUnion & {method: TMethod}

readonly

`constructor`

type new <TMethod extends string = string, TPhase extends ActionEventPhase = "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", TStep extends ActionEventStep = "initial" | ... 3 more ... | "failed">(environment: ActionEventEnvironment, spec: { ...; } | ... 1 more ... | { ...; }, data: ActionEventDataUnion<...>): ActionEvent<...>

`environment`

`spec`

type

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

`data`

type ActionEventDataUnion<TMethod>

`toJSON`

type (): ActionEventDataUnion<TMethod>

returns ActionEventDataUnion<TMethod>

`observe`

Subscribe a listener fired on every data transition.

type (listener: ActionEventChangeObserver<TMethod>): () => void

`listener`

called with (new_data, old_data, event) after each mutation

type ActionEventChangeObserver<TMethod>

returns () => void

unsubscribe function

`set_data`

Replace the event's data and notify observers.

type (new_data: ActionEventDataUnion<TMethod>): void

`new_data`

type ActionEventDataUnion<TMethod>

returns void

`parse`

Parse input data according to the action's schema.

type (): this

returns this

this for chaining with handle_async / handle_sync

throws

Error - if called from a step other than `initial`

`handle_async`

Execute the handler for the current phase.

type (): Promise<void>

returns Promise<void>

throws

Error - if called from a step other than `parsed` (or `failed`,

`handle_sync`

Execute handler synchronously (only for sync local_call actions).

type (): void

returns void

throws

Error - if the spec is not a sync `local_call`, or if called

`transition`

Transition to a new phase.

`phase`

the next phase to transition into

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"

returns void

throws

Error - if called from a step other than `handled` (or

`is_complete`

type (): boolean

returns boolean

`update_progress`

type (progress: unknown): void

`progress`

type unknown

returns void

`set_request`

type (request: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }): void

`request`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

returns void

`set_response`

type (response: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }): void

`response`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }

returns void

`set_notification`

type (notification: { [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }): void

`notification`

type { [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

returns void

ActionEventChangeObserver
#

ActionEventChangeObserver<TMethod>

generics

`TMethod`

constraint string

default string

ActionEventData
#

ZodObject<{ kind: ZodEnum<{ request_response: "request_response"; remote_notification: "remote_notification"; local_call: "local_call"; }>; phase: ZodEnum<{ send_request: "send_request"; ... 7 more ...; execute: "execute"; }>; ... 9 more ...; notification: ZodNullable<...>; }, $strict>

ActionEventDataUnion
#

ActionEventDataUnion<TMethod, TInput, TOutput>

generics

`TMethod`

constraint string

default string

`TInput`

default unknown

`TOutput`

default unknown

ActionEventEnvironment
#

ActionEventEnvironment

`executor`

type ActionExecutor

readonly

`lookup_action_handler`

type

(
		method: string,
		phase: ActionEventPhase,
	) => ((event: any) => any) | undefined

`lookup_action_spec`

type (method: string) => ActionSpecUnion | undefined

`log`

type Logger | null

readonly

ActionEventLocalCallData
#

ActionEventLocalCallData<TMethod, TInput, TOutput>

generics

`TMethod`

constraint string

default string

`TInput`

default unknown

`TOutput`

default unknown

ActionEventOptions
#

ActionEventOptions

Options for deriving an EventSpec from an ActionSpec.

`channel`

type string

ActionEventPhase
#

ZodEnum<{ send_request: "send_request"; receive_request: "receive_request"; send_response: "send_response"; receive_response: "receive_response"; send_error: "send_error"; receive_error: "receive_error"; send: "send"; receive: "receive"; execute: "execute"; }>

ActionEventRemoteNotificationData
#

ActionEventRemoteNotificationData<TMethod, TInput>

generics

`TMethod`

constraint string

default string

`TInput`

default unknown

ActionEventRequestResponseData
#

ActionEventRequestResponseData<TMethod, TInput, TOutput>

generics

`TMethod`

constraint string

default string

`TInput`

default unknown

`TOutput`

default unknown

ActionEventStep
#

ZodEnum<{ initial: "initial"; parsed: "parsed"; handling: "handling"; handled: "handled"; failed: "failed"; }>

ActionExecutor
#

ZodEnum<{ frontend: "frontend"; backend: "backend"; }>

ActionHandler
#

ActionHandler<TInput, TOutput>

Handler function for an RPC action.
Receives validated input and an ActionContext with per-request deps.
Returns the output value (serialized to JSON by the wrapper).

generics

`TInput`

default any

`TOutput`

default any

ActionInitiator
#

ZodEnum<{ frontend: "frontend"; backend: "backend"; both: "both"; }>

ActionKind
#

ZodEnum<{ request_response: "request_response"; remote_notification: "remote_notification"; local_call: "local_call"; }>

ActionMethodEnumKind
#

actions/action_peer.ts view source

ActionMethodEnumKind

Discriminator for generate_action_method_enums — which method-set enums to emit.

ActionPeer
#

`environment`

actions/action_peer.ts view source

readonly

`transports`

type Transports

readonly

`default_send_options`

type Omit<ActionPeerSendOptions, 'signal'>

`constructor`

type new (options: ActionPeerOptions): ActionPeer

`options`

type ActionPeerOptions

`send`

Resolve a transport (per-call name → default name → registry default)
and forward the message. Catches unexpected throws and converts them
to JSON-RPC error responses — this method never throws.

type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }, options?: ActionPeerSendOptions | undefined): Promise<...>

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type ActionPeerSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

the response envelope for requests, or null for successful
notifications (JsonrpcErrorResponse if the notification's transport
send failed)

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type ActionPeerSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type ActionPeerSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`receive`

Dispatch an inbound JSON-RPC message — request, notification, or
malformed envelope. Never throws; unexpected failures become
JSON-RPC error responses.

type (message: unknown): Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | ... 4 more ... | (number & $brand<...>); message: string; data?: unknown; }; } | { ...; } | null>

`message`

type unknown

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

response message for requests, null for notifications, or
an invalid_request error for malformed input

ActionPeerOptions
#

ActionPeerOptions

`environment`

actions/action_peer.ts view source

`transports`

type Transports

`default_send_options`

type Omit<ActionPeerSendOptions, 'signal'>

ActionPeerSendOptions
#

ActionPeerSendOptions

Per-call options for ActionPeer.send. Extends TransportSendOptions
with transport_name for per-call transport selection. The peer-wide
default for any field lives on ActionPeerOptions.default_send_options —
set queue: true there once for client-authoritative peers and override
per-call for exceptions (e.g. high-frequency position sync where stale
replays are wrong).

inheritance

extends:

TransportSendOptions

`transport_name`

type TransportName

ActionRegistry
#

actions/action_registry.ts view source

`specs`

type Array<ActionSpecUnion>

readonly

`constructor`

type new (specs: ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[]): ActionRegistry

`specs`

type

({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; ...

ActionRouteOptions
#

ActionRouteOptions

Options for deriving a RouteSpec from an ActionSpec.

`path`

type string

`handler`

type RouteHandler

`params`

URL path parameter schema. Use z.strictObject() with string fields matching :param segments.

type z.ZodObject

`query`

URL query parameter schema. Use z.strictObject() with string fields.

type z.ZodObject

`http_method`

Override the default HTTP method (default: side_effects → POST, else GET).

type RouteMethod

`auth`

Override the default auth mapping (default: 'public' → none, 'authenticated' → authenticated, 'keeper' → keeper, {role} → role).

type RouteAuth

`errors`

Handler-specific error schemas (HTTP status code → Zod schema). Transport-specific — not on ActionSpec.

type RouteErrorSchemas

ActionSideEffects
#

ZodBoolean

ActionSpec
#

ZodObject<{ method: ZodString; kind: ZodEnum<{ request_response: "request_response"; remote_notification: "remote_notification"; local_call: "local_call"; }>; initiator: ZodEnum<...>; ... 8 more ...; rate_limit: ZodOptional<...>; }, $strict>

ActionSpecUnion
#

ZodUnion<readonly [ZodObject<{ method: ZodString; initiator: ZodEnum<{ frontend: "frontend"; backend: "backend"; both: "both"; }>; side_effects: ZodBoolean; input: ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodType<...>>; ... 7 more ...; async: ZodDefault<...>; }, $strict>, ZodObject<....

Actor
#

Actor

Actor — the entity that acts. Owns cells, holds permits, appears in audit trails.

`id`

type Uuid

`account_id`

type Uuid

`name`

type string

`created_at`

type string

`updated_at`

type string | null

`updated_by`

type Uuid | null

ACTOR_INDEX
#

"\nCREATE INDEX IF NOT EXISTS idx_actor_account ON actor(account_id)"

ACTOR_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS actor (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  name TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at TIMESTAMPTZ,\n  updated_by UUID REFERENCES actor(id) ON DELETE SET NULL\...

ActorSummaryJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; name: ZodString; }, $strict>

Zod schema for the actor summary returned in admin account listings.

admin_account_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: false; input: ZodVoid; output: ZodObject<{ accounts: ZodArray<ZodObject<{ account: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 5 more ...; updated_by: ZodNullable<...>; }, $strict>; actor: ZodNullab...

admin_accounts_rpc_context
#

{ get: () => () => AdminAccountsRpc | null; set: (value?: (() => AdminAccountsRpc | null) | undefined) => () => AdminAccountsRpc | null; }

Svelte context carrying the reactive AdminAccountsRpc accessor. The
provisioner (typically the admin route shell) calls set(() => rpc);
consumers read with const get_rpc = admin_accounts_rpc_context.get();
and either pass the accessor straight to AdminAccountsState/
AdminSessionsState or wrap it with const rpc = $derived(get_rpc());
for direct RPC calls. Unset context falls back to () => null so
components mounted without a provisioner surface the usual "rpc adapter
not wired" path.

admin_invites_rpc_context
#

{ get: () => () => AdminInvitesRpc | null; set: (value?: (() => AdminInvitesRpc | null) | undefined) => () => AdminInvitesRpc | null; }

Svelte context carrying the reactive AdminInvitesRpc accessor. Mirrors
admin_accounts_rpc_context. Unset context falls back to () => null.

ADMIN_ONLY_FIELD_BLOCKLIST
#

readonly string[]

Field names that must not appear in non-admin HTTP response bodies.

admin_session_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: false; input: ZodVoid; output: ZodObject<{ sessions: ZodArray<ZodObject<{ id: ZodString; account_id: $ZodBranded<...>; created_at: ZodString; expires_at: ZodString; last_seen_at: ZodString; username: ZodString; ...

admin_session_revoke_all_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: true; input: ZodObject<{ account_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>; output: ZodObject<...>; async: true; description: string; rate_limit: "account"; }

admin_token_revoke_all_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: true; input: ZodObject<{ account_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>; output: ZodObject<...>; async: true; description: string; rate_limit: "account"; }

AdminAccountEntryJson
#

ZodObject<{ account: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; updated_at: ZodString; updated_by: ZodNullable<...>; }, $strict>; actor: ZodNullable<...>; permits: ZodArray<...>; pending_offers: ZodArray<....

Zod schema for an admin account listing entry (account + actor + permits + pending offers).

AdminAccountJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; updated_at: ZodString; updated_by: ZodNullable<...>; }, $strict>

Zod schema for admin-facing account data — extends SessionAccountJson with audit fields.

AdminAccountListInput
#

ZodVoid

Input for admin_account_list. No parameters — the caller is the subject.

AdminAccountListOutput
#

ui/AdminAccounts.svelte view source

ZodObject<{ accounts: ZodArray<ZodObject<{ account: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; updated_at: ZodString; updated_by: ZodNullable<...>; }, $strict>; actor: ZodNullable<...>; permits: ZodArray<....

Output for admin_account_list.

AdminAccounts
#

AdminAccountsRpc
#

AdminAccountsRpc

Narrow RPC surface consumed by AdminAccountsState. Consumers adapt their
typed RPC client (e.g. a create_rpc_client Proxy) to this shape — the
state class stays decoupled from the client's Result return type so
tests can inject plain-function stubs. Mirrors the PermitOffersRpc
pattern.
Every operation flows through RPC: the listing reuses admin_account_list,
grant reuses permit_offer_create, revoke and retract have dedicated
actions, and the session / token revoke-all mutations reuse
admin_session_revoke_all and admin_token_revoke_all. Without the
adapter the state class cannot fetch, grant, revoke, retract, or
revoke-all sessions/tokens.
Method signatures track the underlying action specs — Uuid-branded ids
propagate from the wire through the state class to the components. The
adapter built by create_admin_rpc_adapters therefore needs zero casts
to bridge to the typed throwing Proxy.

`list_accounts`

type () => Promise<AdminAccountListOutput>

`list_sessions`

type () => Promise<AdminSessionListOutput>

`grant_permit`

type (params: PermitOfferCreateInput) => Promise<PermitOfferCreateOutput>

`revoke_permit`

type (params: PermitRevokeInput) => Promise<PermitRevokeOutput>

`retract_offer`

type (offer_id: Uuid) => Promise<PermitOfferOkOutput>

`session_revoke_all`

type (params: AdminSessionRevokeAllInput) => Promise<AdminSessionRevokeAllOutput>

`token_revoke_all`

type (params: AdminTokenRevokeAllInput) => Promise<AdminTokenRevokeAllOutput>

AdminAccountsState
#

inheritance

extends:

Loadable

`accounts`

type Array<AdminAccountEntryJson>

`grantable_roles`

type Array<RoleName>

`granting_keys`

type SvelteSet<string>

readonly

`revoking_ids`

type SvelteSet<string>

readonly

`retracting_ids`

type SvelteSet<string>

readonly

`account_count`

readonly

`constructor`

type new (options?: AdminAccountsStateOptions | undefined): AdminAccountsState

`options?`

type AdminAccountsStateOptions | undefined

optional

`fetch`

type (): Promise<void>

returns Promise<void>

`grant_permit`

Offer the role to the recipient via the permit_offer_create RPC.
Server returns the pending offer; the recipient must accept before
the permit materializes. Returns the offer payload on success so
callers can drive follow-up UX (e.g. seed PermitOffersState.outgoing).
A re-offer from the same admin to the same (account, role)
refreshes the existing pending row — the returned offer id is stable
across those calls.
No-op when the rpc adapter is absent; error is set to a descriptive
message so the UI surfaces the misconfiguration.

type (account_id: string & $brand<"Uuid">, role: string): Promise<{ id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<...>; ... 10 more ...; resulting_permit_id: (string & $brand<...>) | null; } | undefined>

`account_id`

type string & $brand<"Uuid">

`role`

type string

returns

Promise<{ id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; } | undefined>

`revoke_permit`

Revoke an active permit via the permit_revoke RPC.
actor_id is the natural key — permits are actor-scoped, and the
admin UI reads row.actor.id straight from the listing, so the state
class takes it directly rather than deriving it from account_id.
The optional reason is stamped on permit.revoked_reason and
surfaced on the revokee's WS notification.

type (actor_id: string & $brand<"Uuid">, permit_id: string & $brand<"Uuid">, reason?: string | null | undefined): Promise<void>

`actor_id`

type string & $brand<"Uuid">

`permit_id`

type string & $brand<"Uuid">

`reason?`

type string | null | undefined

optional

returns Promise<void>

`retract_offer`

Retract a pending offer the admin issued via the permit_offer_retract
RPC. The action handles auth, audit, and the
permit_offer_retracted WS notification.
After success, refetches the listing so pending_offers drops the
row and the "+ {role}" button un-hides.

type (offer_id: string & $brand<"Uuid">): Promise<void>

`offer_id`

type string & $brand<"Uuid">

returns Promise<void>

AdminAccountsStateOptions
#

auth/admin_actions.ts view source

AdminAccountsStateOptions

`get_rpc`

Reactive accessor for the RPC adapter; returns null when unwired.
Matches PermitOffersStateOptions.account_id / actor_id pattern —
lets the component pass a $props()-sourced rpc without tripping
Svelte's state_referenced_locally warning.

type () => AdminAccountsRpc | null

AdminActionDeps
#

AdminActionDeps

Dependencies for create_admin_actions.
Shares shape with PermitOfferActionDeps so consumers can pass the same
deps to both factories. log drives RPC-internal error logging;
on_audit_event is wired by the two revoke-all mutations so SSE fan-out
mirrors the former REST-route behavior. audit_log_config flows from
AppDeps and is consumed by audit_log_fire_and_forget.

AdminActionOptions
#

auth/admin_actions.ts view source

AdminActionOptions

Options for create_admin_actions.

`roles`

Role schema result from create_role_schema(). Defaults to builtin
roles only. Used to derive grantable_roles (the web_grantable
subset) returned by admin_account_list.

type RoleSchemaResult

`app_settings`

Mutable in-memory app settings ref — typically ctx.app_settings from
AppServerContext. When provided, the factory wires the
app_settings_get and app_settings_update handlers; the update
handler mutates this ref so signup middleware reads the new value
without a DB round trip. When omitted, those two methods have no
handler and RPC dispatch returns method_not_found.

type AppSettings

AdminAuditLog
#

ui/AdminAuditLog.svelte view source

AdminInvites
#

ui/AdminInvites.svelte view source

AdminInvitesRpc
#

AdminInvitesRpc

Narrow RPC surface consumed by AdminInvitesState. Consumers adapt their
typed RPC client to this shape. error.data.reason on thrown errors
carries the ERROR_INVITE_* constant — handled by the caller when
user-friendly messages are needed. Method signatures track the wire
spec types directly so the adapter needs no casts.

`list`

type () => Promise<InviteListOutput>

`create`

type (params: InviteCreateInput) => Promise<InviteCreateOutput>

`delete`

type (params: InviteDeleteInput) => Promise<InviteDeleteOutput>

AdminInvitesState
#

inheritance

extends:

Loadable

`invites`

type Array<InviteWithUsernamesJson>

`creating`

`deleting_ids`

type SvelteSet<string>

readonly

`invite_count`

readonly

`unclaimed_count`

readonly

`constructor`

type new (options?: AdminInvitesStateOptions | undefined): AdminInvitesState

`options?`

type AdminInvitesStateOptions | undefined

optional

`fetch`

type (): Promise<void>

returns Promise<void>

`create_invite`

type (email?: string | undefined, username?: string | undefined): Promise<boolean>

`email?`

type string | undefined

optional

`username?`

type string | undefined

optional

returns Promise<boolean>

`delete_invite`

type (id: string & $brand<"Uuid">): Promise<void>

`id`

type string & $brand<"Uuid">

returns Promise<void>

AdminInvitesStateOptions
#

ui/AdminOverview.svelte view source

AdminInvitesStateOptions

`get_rpc`

Reactive accessor for the RPC adapter. null disables all operations
(the state reports a descriptive error when mutations/fetches fire).

type () => AdminInvitesRpc | null

AdminOverview
#

AdminPermitHistory
#

ui/AdminPermitHistory.svelte view source

AdminRpcAdapters
#

AdminRpcAdapters

The four admin RPC adapters assembled from a shared api.

`admin_accounts`

type AdminAccountsRpc

`admin_invites`

type AdminInvitesRpc

`audit_log`

type AuditLogRpc

`app_settings`

type AppSettingsRpc

AdminRpcApi
#

AdminRpcApi

The wire-method surface this module needs from the typed throwing RPC
client. Every method returns the unwrapped value or throws an Error
carrying the JSON-RPC {code, message, data?} shape — i.e. the
ThrowingApi<...> view of the corresponding action specs.
Consumers pass the typed throwing Proxy returned by
create_frontend_rpc_client directly. Structural typing means any
superset (e.g. the consumer's full ThrowingApi<ActionsApi>) is
assignable as long as these methods are present at these signatures.

`admin_account_list`

type () => Promise<AdminAccountListOutput>

`admin_session_list`

type () => Promise<AdminSessionListOutput>

`admin_session_revoke_all`

type

(
		input: AdminSessionRevokeAllInput,
	) => Promise<AdminSessionRevokeAllOutput>

`admin_token_revoke_all`

type (input: AdminTokenRevokeAllInput) => Promise<AdminTokenRevokeAllOutput>

`audit_log_list`

type (input: AuditLogListInput) => Promise<AuditLogListOutput>

`audit_log_permit_history`

type

(
		input: AuditLogPermitHistoryInput,
	) => Promise<AuditLogPermitHistoryOutput>

`invite_list`

type () => Promise<InviteListOutput>

`invite_create`

type (input: InviteCreateInput) => Promise<InviteCreateOutput>

`invite_delete`

type (input: InviteDeleteInput) => Promise<InviteDeleteOutput>

`app_settings_get`

type () => Promise<AppSettingsGetOutput>

`app_settings_update`

type (input: AppSettingsUpdateInput) => Promise<AppSettingsUpdateOutput>

`permit_offer_create`

type (input: PermitOfferCreateInput) => Promise<PermitOfferCreateOutput>

`permit_offer_retract`

type (input: PermitOfferRetractInput) => Promise<PermitOfferOkOutput>

`permit_revoke`

type (input: PermitRevokeInput) => Promise<PermitRevokeOutput>

AdminSessionJson
#

ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; created_at: ZodString; expires_at: ZodString; last_seen_at: ZodString; username: ZodString; }, $strict>

Zod schema for admin session listing (session + username).

AdminSessionListInput
#

ZodVoid

Input for admin_session_list. No parameters — reads every active session.

AdminSessionListOutput
#

ZodObject<{ sessions: ZodArray<ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; created_at: ZodString; expires_at: ZodString; last_seen_at: ZodString; username: ZodString; }, $strict>>; }, $strict>

Output for admin_session_list. Cross-account listing; fan-out already scoped by role auth.

AdminSessionRevokeAllInput
#

ZodObject<{ account_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>

Input for admin_session_revoke_all.

AdminSessionRevokeAllOutput
#

ui/AdminSessions.svelte view source

ZodObject<{ ok: ZodLiteral<true>; count: ZodNumber; }, $strict>

Output for admin_session_revoke_all.

AdminSessions
#

AdminSessionsState
#

ui/admin_sessions_state.svelte.ts view source

inheritance

extends:

Loadable

`sessions`

type Array<AdminSessionJson>

`revoking_account_ids`

type SvelteSet<string>

readonly

`revoking_token_account_ids`

type SvelteSet<string>

readonly

`active_count`

readonly

`constructor`

type new (options?: AdminSessionsStateOptions | undefined): AdminSessionsState

`options?`

type AdminSessionsStateOptions | undefined

optional

`fetch`

type (): Promise<void>

returns Promise<void>

`revoke_all_for_account`

type (account_id: string & $brand<"Uuid">): Promise<void>

`account_id`

type string & $brand<"Uuid">

returns Promise<void>

`revoke_all_tokens_for_account`

type (account_id: string & $brand<"Uuid">): Promise<void>

`account_id`

type string & $brand<"Uuid">

returns Promise<void>

AdminSessionsStateOptions
#

ui/admin_sessions_state.svelte.ts view source

AdminSessionsStateOptions

Options for AdminSessionsState.
The RPC adapter drives every operation (listing + the two revoke-all
mutations). Without it, fetch and the revoke controls no-op with
'rpc adapter not wired' on error.

`get_rpc`

Reactive accessor for the RPC adapter; returns null when unwired.
Mirrors AdminAccountsStateOptions.get_rpc so a single adapter
instance backs both states without tripping Svelte's
state_referenced_locally warning.

type () => AdminAccountsRpc | null

AdminSettings
#

ui/AdminSettings.svelte view source

AdminSurface
#

ui/AdminSurface.svelte view source

AdminTokenRevokeAllInput
#

ZodObject<{ account_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>

Input for admin_token_revoke_all.

AdminTokenRevokeAllOutput
#

testing/adversarial_headers.ts view source

ZodObject<{ ok: ZodLiteral<true>; count: ZodNumber; }, $strict>

Output for admin_token_revoke_all.

AdversarialHeaderCase
#

AdversarialHeaderCase

A header-level attack case for middleware stack testing.

`name`

type string

`headers`

type Record<string, string>

`expected_status`

type number

`expected_error`

type string

`expected_error_schema`

Zod schema to validate error response body against. Defaults to ApiError when expected_error is set.

type z.ZodType

`validate_expectation`

Whether the request should reach token validation or be short-circuited by earlier middleware.

type 'called' | 'not_called'

AdversarialTestOptions
#

AdversarialTestOptions

Options for adversarial test runners (auth enforcement and input validation).

`build`

Build the app surface bundle (surface + route specs + middleware specs).

type () => AppSurfaceSpec

`roles`

All roles in the app (e.g. ['admin', 'keeper']).

type Array<string>

Alignment
#

Alignment

Alignment options for positioned elements.

all_account_action_specs
#

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }[]

All self-service account action specs — a codegen-ready registry.
Consumers spread this into their own action-spec array to include
account methods in a typed client surface.

all_admin_action_specs
#

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }[]

All admin action specs — a codegen-ready registry. Consumers spread this
into their own action-spec array to include admin methods in a typed
client surface. Always includes the two app-settings specs; the runtime
factory only wires their handlers when AdminActionOptions.app_settings
is provided.

all_permit_offer_action_specs
#

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }[]

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.

all_self_service_role_action_specs
#

auth/standard_action_specs.ts view source

readonly { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }[]

All self-service role action specs — a codegen-ready registry. Single-element
post-unification, kept for symmetry with the other all_*_action_specs
exports so codegen and frontend bundles import the same shape.

all_standard_action_specs
#

readonly { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }[]

Combined spec registry for the standard RPC surface (admin +
permit_offer + account). Symmetric with create_standard_rpc_actions.
Spec count is the sum of the three sub-registries. Adding a method to
any sub-registry surfaces here automatically.

API_TOKEN_ID_REGEX
#

RegExp

Regex for the public API token id (e.g. tok_abC0_d-3xyzA). Twelve
base64url characters after the tok_ prefix. Matches the format produced
by generate_api_token.

API_TOKEN_INDEX
#

"\nCREATE INDEX IF NOT EXISTS idx_api_token_account ON api_token(account_id)"

API_TOKEN_PREFIX
#

"secret_fuz_token_"

Prefix for all fuz API tokens (enables secret scanning).

API_TOKEN_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS api_token (\n  id TEXT PRIMARY KEY,\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  name TEXT NOT NULL,\n  token_hash TEXT NOT NULL,\n  expires_at TIMESTAMPTZ,\n  last_used_at TIMESTAMPTZ,\n  last_used_ip TEXT,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n)"

ApiError
#

ZodObject<{ error: ZodString; }, $loose>

Base API error — all JSON error responses have at least {error: string}.

ApiToken
#

ApiToken

API token for CLI/programmatic access.

`id`

type string

`account_id`

type Uuid

`name`

type string

`token_hash`

type string

`expires_at`

type string | null

`last_used_at`

type string | null

`last_used_ip`

type string | null

`created_at`

type string

ApiTokenId
#

ZodString

Zod schema for the public API token id.

ApiTokenQueryDeps
#

ApiTokenQueryDeps

Extended deps for query_validate_api_token which needs a logger.

inheritance

extends:

QueryDeps

`log`

type Logger

app_settings_get_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: false; input: ZodVoid; output: ZodObject<{ settings: ZodObject<{ open_signup: ZodBoolean; updated_at: ZodNullable<...>; updated_by: ZodNullable<...>; updated_by_username: ZodNullable<...>; }, $strict>; }, $stric...

app_settings_rpc_context
#

{ get: () => () => AppSettingsRpc | null; set: (value?: (() => AppSettingsRpc | null) | undefined) => () => AppSettingsRpc | null; }

Svelte context carrying the reactive AppSettingsRpc accessor. Mirrors
admin_accounts_rpc_context. Unset context falls back to () => null so
OpenSignupToggle mounted outside a provisioner hides gracefully.

APP_SETTINGS_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS app_settings (\n  id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1),\n  open_signup BOOLEAN NOT NULL DEFAULT false,\n  updated_at TIMESTAMPTZ,\n  updated_by UUID\n)"

APP_SETTINGS_SEED
#

"\nINSERT INTO app_settings (id) VALUES (1) ON CONFLICT DO NOTHING"

app_settings_update_action_spec
#

server/app_backend.ts view source

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: true; input: ZodObject<{ open_signup: ZodBoolean; }, $strict>; output: ZodObject<...>; async: true; description: string; rate_limit: "account"; }

AppBackend
#

AppBackend

Result of create_app_backend() — database metadata + deps bundle.
This is the initialized backend, not the HTTP server.
Pass it to create_app_server() to assemble the Hono app.

`deps`

type AppDeps

`db_type`

type DbType

`db_name`

type string

`migration_results`

Migration results from create_app_backend — auth migrations plus any consumer namespaces passed via migration_namespaces.

type ReadonlyArray<MigrationResult>

readonly

`close`

Close the database connection. Bound to the actual driver.

type () => Promise<void>

AppDeps
#

auth/deps.ts view source

AppDeps

Stateless capabilities bundle for fuz_app backends.
Injectable and swappable per environment (production vs test).
Does not contain config (static values) or runtime state (mutable refs).

`stat`

Get file/directory stats, or null if path doesn't exist.

type (path: string) => Promise<StatResult | null>

`read_text_file`

Read a file as text.

type (path: string) => Promise<string>

`delete_file`

Delete a file.

type (path: string) => Promise<void>

`keyring`

HMAC-SHA256 cookie signing keyring.

type Keyring

`password`

Password hashing operations. Use argon2_password_deps in production.

type PasswordHashDeps

`db`

Database instance.

type Db

`log`

Structured logger instance.

type Logger

`on_audit_event`

Called after each audit log INSERT succeeds.
Use to broadcast audit events via SSE. Flows automatically to all
route factories that receive deps or RouteFactoryDeps.
Defaults to a noop when not wired to SSE.

type (event: AuditLogEvent) => void

`audit_log_config`

Audit-log config for audit_log_fire_and_forget and query_audit_log.
Built once at startup via create_audit_log_config({extra_events}) to
register consumer event types. Optional — defaults to
BUILTIN_AUDIT_LOG_CONFIG when absent.
Threaded through AppDeps (instead of a per-call positional arg) so
consumer handlers cannot silently fall back to the builtin config by
forgetting to pass theirs — the deps bundle carries it everywhere
fuz_app emits an audit event.

type AuditLogConfig

apply_middleware_specs
#

(app: Hono<BlankEnv, BlankSchema, "/">, specs: MiddlewareSpec[]): void

Apply named middleware specs to a Hono app.

`app`

type Hono<BlankEnv, BlankSchema, "/">

`specs`

type MiddlewareSpec[]

returns

void

apply_route_specs
#

(app: Hono<BlankEnv, BlankSchema, "/">, specs: RouteSpec[], resolve_auth_guards: AuthGuardResolver, log: Logger, db: Db): void

Apply route specs to a Hono app.
For each spec: resolves auth to guards via the provided resolver,
adds input validation middleware (for routes with non-null input schemas),
wraps handler with DEV-only output and error validation, wraps with error
catch layer (catches ThrownJsonrpcError and generic errors), and registers the route.
Each handler receives a RouteContext with:
- db: transaction-scoped (for non-GET) or pool-level (for GET)
- background_db: always pool-level
- pending_effects: fire-and-forget effect queue

`app`

type Hono<BlankEnv, BlankSchema, "/">

`specs`

type RouteSpec[]

`resolve_auth_guards`

maps RouteAuth to middleware — use fuz_auth_guard_resolver from auth/route_guards.ts

type AuthGuardResolver

`log`

type Logger

`db`

used for transaction wrapping and RouteContext

type Db

returns

void

throws

Error - if two specs share the same `method` + `path` (each combination must be unique)

AppServer
#

AppServer

Result of create_app_server().

`app`

type Hono

`surface_spec`

Surface spec — serializable surface + raw specs that produced it.

type AppSurfaceSpec

`bootstrap_status`

type BootstrapStatus

`app_settings`

Global app settings (mutable ref — mutated by settings admin route).

type AppSettings

`migration_results`

Migration results from create_app_backend (auth + any migration_namespaces passed there).

type ReadonlyArray<MigrationResult>

`audit_sse`

Factory-managed audit log SSE. null when audit_log_sse option is not set.

type AuditLogSse | null

`close`

Close the database connection. Propagated from AppBackend.

type () => Promise<void>

AppServerContext
#

AppServerContext

Context passed to create_route_specs.

`deps`

type AppDeps

`backend`

type AppBackend

`bootstrap_status`

type BootstrapStatus

`session_options`

type SessionOptions<string>

`ip_rate_limiter`

Shared IP rate limiter (from options). null when not configured.

type RateLimiter | null

`login_account_rate_limiter`

Per-account login rate limiter (from options). null when not configured.

type RateLimiter | null

`signup_account_rate_limiter`

Per-account signup rate limiter (from options). null when not configured.

type RateLimiter | null

`action_ip_rate_limiter`

Per-IP action-dispatcher rate limiter — shared across HTTP RPC + WS. null when not configured.

type RateLimiter | null

`action_account_rate_limiter`

Per-actor action-dispatcher rate limiter — shared across HTTP RPC + WS. null when not configured.

type RateLimiter | null

`app_settings`

Global app settings (mutable ref — mutated by settings admin route).

type AppSettings

`audit_sse`

Factory-managed audit log SSE. null when audit_log_sse option is not set.

type AuditLogSse | null

AppServerOptions
#

AppServerOptions

Configuration for create_app_server().
Requires a pre-initialized AppBackend from create_app_backend().
Two explicit steps: init backend then assemble server.

`backend`

Pre-initialized backend from create_app_backend().

type AppBackend

`session_options`

Session options for cookie-based auth.

type SessionOptions<string>

`allowed_origins`

Parsed allowed origin patterns.

type Array<RegExp>

`proxy`

Trusted proxy options.

type

{
		trusted_proxies: Array<string>;
		get_connection_ip: (c: Context) => string | undefined;
	}

`ip_rate_limiter`

Shared IP rate limiter for login, bootstrap, and bearer auth.
Omit or undefined to use a default limiter (5 attempts per 15 minutes).
Pass null to explicitly disable rate limiting.
Also available on AppServerContext for route factory callbacks.

type RateLimiter | null

`login_account_rate_limiter`

Per-account rate limiter for login attempts.
Omit or undefined to use a default limiter (10 attempts per 30 minutes).
Pass null to explicitly disable rate limiting.
Also available on AppServerContext for route factory callbacks.

type RateLimiter | null

`signup_account_rate_limiter`

Per-account rate limiter for signup attempts, keyed by submitted username.
Omit or undefined to use a default limiter (10 attempts per 30 minutes).
Pass null to explicitly disable rate limiting.
Also available on AppServerContext for route factory callbacks.

type RateLimiter | null

`bearer_ip_rate_limiter`

Rate limiter for bearer token auth attempts (per-IP).
Omit or undefined to use a default limiter (5 attempts per 15 minutes).
Pass null to explicitly disable rate limiting.

type RateLimiter | null

`action_ip_rate_limiter`

Per-IP rate limiter for the action dispatchers (HTTP RPC + WebSocket).
Consulted for actions whose spec declares rate_limit: 'ip' or 'both'.
Same limiter applies across transports — one budget per action.
Omit or undefined to use a default limiter (600 attempts per
15 minutes — permissive). Pass null to explicitly disable.
Also available on AppServerContext for consumers wiring
register_action_ws.

type RateLimiter | null

`action_account_rate_limiter`

Per-actor rate limiter for the action dispatchers (HTTP RPC + WebSocket).
Consulted for actions whose spec declares rate_limit: 'account' or
'both'. Keyed on request_context.actor.id (post-auth).
Omit or undefined to use a default limiter (1200 attempts per
15 minutes — permissive). Pass null to explicitly disable.
Also available on AppServerContext for consumers wiring
register_action_ws.

type RateLimiter | null

`max_body_size`

Maximum allowed request body size in bytes.
Omit or undefined to use the default (1 MiB).
Pass null to explicitly disable body size limiting.

type number | null

`daemon_token_state`

Daemon token state for keeper auth. Omit to disable.

type DaemonTokenState

`bootstrap`

Bootstrap options. Omit to skip bootstrap status check and routes.

type

{
		token_path: string | null;
		/** Route prefix for bootstrap routes. Default `'/api/account'`. */
		route_prefix?: string;
		/**
		 * Called after successful bootstrap (account + session created).
		 * Use for app-specific post-bootstrap work like generating API tokens.
		 */
		on_bootstrap?: (result: BootstrapAccountSuccess, c: Context) => Promise<void>;
	}

`surface_route`

Set to false to disable the auto-created surface route (GET /api/surface).
Default: auto-created (authenticated).

type false

`create_route_specs`

Build route specs from the initialized backend.
Called after all middleware is ready.

type (context: AppServerContext) => Array<RouteSpec>

`transform_middleware`

Optional: transform middleware specs before applying.

type (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>

`audit_log_sse`

Enable factory-managed audit log SSE.
When truthy, creates an AuditLogSse instance internally, wires on_audit_event
on the backend deps (composing with any existing callback), and auto-includes
AUDIT_LOG_EVENT_SPECS in the surface. The result is exposed on AppServerContext
(for route factories) and AppServer (for the caller).
Pass true for defaults (admin role), or {role: 'custom'} for a custom role.
Omit to wire audit SSE manually.

type true | {role?: string}

`event_specs`

SSE event specs for surface generation. Defaults to [] (no SSE events).

type Array<EventSpec>

`rpc_endpoints`

RPC endpoint specs — single source of truth for both surface generation
*and* live dispatch. Each entry is mounted via create_rpc_endpoint
against the assembled Hono app, so consumers no longer call
create_rpc_endpoint themselves inside create_route_specs.
Accepts either an array (evaluated eagerly) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> (evaluated after the
server context is assembled). Use the factory form when action lists
depend on ctx.deps / ctx.app_settings — e.g.
create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings}).

type Array<RpcEndpointSpec> | ((context: AppServerContext) => Array<RpcEndpointSpec>)

`env_schema`

Env schema for surface generation. Pass z.object({}) when there are no env vars beyond BaseServerEnv.

type z.ZodObject

`post_route_middleware`

Middleware applied after routes, before static serving. Included in surface.

type Array<MiddlewareSpec>

`static_serving`

Static file serving. Omit if not serving static files.

type

{
		serve_static: ServeStaticFactory;
		spa_fallback?: string;
	}

`await_pending_effects`

Await all pending fire-and-forget effects before returning the response.
Use in tests so audit log assertions don't need polling.
Default false (production: true fire-and-forget).

type boolean

`on_effect_error`

Called when a pending effect rejects.
Use for monitoring, metrics, or alerting in production.
Only called when await_pending_effects is false (production mode).

type (error: unknown, context: EffectErrorContext) => void

`env_values`

Env values for startup summary logging.

type Record<string, unknown>

AppSettings
#

AppSettings

App settings row from the database.

`open_signup`

type boolean

`updated_at`

type string | null

`updated_by`

type Uuid | null

AppSettingsGetInput
#

ZodVoid

Input for app_settings_get. No parameters.

AppSettingsGetOutput
#

ZodObject<{ settings: ZodObject<{ open_signup: ZodBoolean; updated_at: ZodNullable<ZodString>; updated_by: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; updated_by_username: ZodNullable<...>; }, $strict>; }, $strict>

Output for app_settings_get.

AppSettingsJson
#

ZodObject<{ open_signup: ZodBoolean; updated_at: ZodNullable<ZodString>; updated_by: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; }, $strict>

Zod schema for client-safe app settings data.

AppSettingsRpc
#

AppSettingsRpc

Narrow RPC surface consumed by AppSettingsState. Consumers adapt their
typed RPC client to this shape. Method signatures track the wire spec
inputs/outputs directly so the adapter needs no casts.

`get`

type () => Promise<AppSettingsGetOutput>

`update`

type (params: AppSettingsUpdateInput) => Promise<AppSettingsUpdateOutput>

AppSettingsState
#

inheritance

extends:

Loadable

`settings`

type AppSettingsWithUsernameJson | null

`updating`

`constructor`

type new (options?: AppSettingsStateOptions | undefined): AppSettingsState

`options?`

type AppSettingsStateOptions | undefined

optional

`fetch`

type (): Promise<void>

returns Promise<void>

`update_open_signup`

type (value: boolean): Promise<void>

`value`

type boolean

returns Promise<void>

AppSettingsStateOptions
#

AppSettingsStateOptions

`get_rpc`

Reactive accessor for the RPC adapter. null disables all operations
(the state reports a descriptive error when fetch/update fires).

type () => AppSettingsRpc | null

AppSettingsUpdateInput
#

ZodObject<{ open_signup: ZodBoolean; }, $strict>

Input for app_settings_update.

AppSettingsUpdateOutput
#

ZodObject<{ ok: ZodLiteral<true>; settings: ZodObject<{ open_signup: ZodBoolean; updated_at: ZodNullable<ZodString>; updated_by: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; updated_by_username: ZodNullable<...>; }, $strict>; }, $strict>

Output for app_settings_update.

AppSettingsWithUsernameJson
#

ui/AppShell.svelte view source

ZodObject<{ open_signup: ZodBoolean; updated_at: ZodNullable<ZodString>; updated_by: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; updated_by_username: ZodNullable<...>; }, $strict>

Zod schema for admin app settings with resolved updater username.

AppShell
#

`children`

type Snippet

`sidebar`

type Snippet

`sidebar_width?`

Sidebar width in pixels when shown.

type number

optional

`sidebar_state?`

Optional pre-built SidebarState for sharing visibility across shells.

type SidebarState

optional

`keyboard_shortcut?`

Single-key shortcut that toggles the sidebar (e.g. 'b'). false disables.

type string | false

optional

`show_toggle?`

Whether to render the built-in (or custom) toggle button.

type boolean

optional

`toggle_button?`

Custom toggle-button renderer; receives the title, visibility, and toggle callback.

type Snippet<[{title: string; show_sidebar: boolean; toggle: () => void}]>

optional

AppSurface
#

AppSurface

Generated attack surface — JSON-serializable.

`middleware`

type Array<AppSurfaceMiddleware>

`routes`

type Array<AppSurfaceRoute>

`rpc_endpoints`

type Array<AppSurfaceRpcEndpoint>

`env`

type Array<AppSurfaceEnv>

`events`

type Array<AppSurfaceEvent>

`diagnostics`

type Array<AppSurfaceDiagnostic>

AppSurfaceDiagnostic
#

AppSurfaceDiagnostic

Assembly-time diagnostic collected during surface generation or server assembly.

`level`

type 'warning' | 'info'

`category`

type string

`message`

type string

`source`

type string

AppSurfaceEnv
#

AppSurfaceEnv

An env var in the generated attack surface (JSON-serializable).

`name`

type string

`description`

type string

`sensitivity`

Sensitivity level from .meta({sensitivity}). null when not sensitive.

type Sensitivity | null

`has_default`

type boolean

`optional`

type boolean

AppSurfaceEvent
#

AppSurfaceEvent

An SSE event in the generated attack surface (JSON-serializable).

`method`

type string

`description`

type string

`channel`

type string | null

`params_schema`

type unknown

AppSurfaceMiddleware
#

AppSurfaceMiddleware

A middleware in the generated attack surface (JSON-serializable).

`name`

type string

`path`

type string

`error_schemas`

JSON Schema representations of error responses, keyed by HTTP status code. null when none.

type Record<string, unknown> | null

AppSurfaceRoute
#

AppSurfaceRoute

A route in the generated attack surface (JSON-serializable).

`method`

type string

`path`

type string

`auth`

type RouteAuth

`applicable_middleware`

type Array<string>

`description`

type string

`is_mutation`

Whether this route mutates state (POST, PUT, DELETE, PATCH).

type boolean

`transaction`

Whether this route's handler runs inside a database transaction.

type boolean

`rate_limit_key`

Rate limit key type declared on the route spec. null when not rate-limited.

type RateLimitKey | null

`params_schema`

JSON Schema representation of the URL path params schema. null when no params.

type unknown

`query_schema`

JSON Schema representation of the URL query params schema. null when no query schema.

type unknown

`input_schema`

JSON Schema representation of the request body schema. null for no-body routes.

type unknown

`output_schema`

JSON Schema representation of the success response schema.

type unknown

`error_schemas`

JSON Schema representations of error responses, keyed by HTTP status code. null when none.

type Record<string, unknown> | null

AppSurfaceRpcEndpoint
#

AppSurfaceRpcEndpoint

An RPC endpoint in the generated attack surface (JSON-serializable).

`path`

type string

`methods`

type Array<AppSurfaceRpcMethod>

AppSurfaceRpcMethod
#

AppSurfaceRpcMethod

A method within an RPC endpoint in the generated attack surface (JSON-serializable).

`name`

type string

`auth`

type RouteAuth

`input_schema`

JSON Schema representation of the input schema. null for null-input methods.

type unknown

`output_schema`

JSON Schema representation of the output schema.

type unknown

`side_effects`

type boolean

`description`

type string

`rate_limit_key`

Rate limit key declared on the action spec. null when not rate-limited.

type RateLimitKey | null

AppSurfaceSpec
#

AppSurfaceSpec

The surface bundled with the source specs that produced it.
AppSurface is JSON-serializable (snapshots, UI, startup logging).
AppSurfaceSpec is runtime-only (tests, introspection, attack surface assertions).

`surface`

type AppSurface

`route_specs`

type Array<RouteSpec>

`middleware_specs`

type Array<MiddlewareSpec>

`rpc_endpoints`

type Array<RpcEndpointSpec>

argon2_password_deps
#

PasswordHashDeps

Argon2id implementation of PasswordHashDeps.
Pass as password in AppDeps / CreateAppBackendOptions for production use.

assert_404_schemas_use_specific_errors
#

(surface: AppSurface): void

Routes declaring 404 error schemas should use specific z.literal() or z.enum()
error codes, not generic z.string().
A generic 404 schema (ApiError with z.string()) means the error code is
unconstrained — the handler could return any string, making client error handling
fragile. Routes with params (:id) are the primary 404 producers; their error
schemas should use specific constants like ERROR_ACCOUNT_NOT_FOUND.
Only flags routes that have params_schema (param-driven resource lookup) — routes
declaring 404 for other reasons (e.g., bootstrap not configured) may legitimately
use generic schemas.

`surface`

type AppSurface

returns

void

assert_descriptions_present
#

(surface: AppSurface): void

Every route has a non-empty description.

`surface`

type AppSurface

returns

void

assert_error_code_status_consistency
#

(surface: AppSurface): void

The same z.literal() error code should not appear at different HTTP status codes
across routes.
Extracts const values from error schema error properties (which correspond to
z.literal() in the Zod source). Flags when the same literal appears at different
status codes — e.g., ERROR_INVALID_CREDENTIALS at both 401 and 403 would be a bug.
Only checks schemas with const values (literal schemas). Generic z.string()
schemas (which produce {type: 'string'} in JSON Schema) are ignored.

`surface`

type AppSurface

returns

void

assert_error_coverage
#

(collector: ErrorCoverageCollector, route_specs: RouteSpec[], options?: ErrorCoverageOptions | undefined): void

Assert error coverage meets a minimum threshold.
Computes the ratio of exercised error paths to total declared error paths.
For routes whose status error schema names specific codes (z.literal or
z.enum), each declared code counts as one coverage path; for schemas
without declared codes (ApiError/z.string()), the status counts as one
path. A status-only observation covers all declared codes for that status
(the "any-code" rule).
When min_coverage is 0 (default), logs coverage info without failing.
When > 0, fails if coverage is below the threshold.

`collector`

type ErrorCoverageCollector

`route_specs`

type RouteSpec[]

`options?`

type ErrorCoverageOptions | undefined

optional

returns

void

throws

AssertionError - if `min_coverage > 0` and the covered/total ratio

assert_error_schema_tightness
#

(surface: AppSurface, options?: ErrorSchemaTightnessOptions | undefined): void

Assert that all error schemas meet a minimum specificity threshold.
Calls audit_error_schema_tightness and fails on any entry below
the configured threshold. Use allowlist and ignore_statuses to exclude
known exceptions during progressive tightening.

`surface`

type AppSurface

`options?`

type ErrorSchemaTightnessOptions | undefined

optional

returns

void

throws

AssertionError - listing every route × status combination whose error

assert_error_schema_valid
#

(lookup: Map<string, Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>, route: AppSurfaceRoute, status: number, body: unknown): void

Assert that an error schema exists for a route+status and validate the body against it.
Protected routes should always have auto-derived error schemas (401 for authenticated,
403 for role-restricted). A missing schema indicates a gap in error schema derivation.

`lookup`

map from "METHOD /path" to merged error schemas

type Map<string, Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>

`route`

the surface route to validate against

type AppSurfaceRoute

`status`

expected HTTP status code

type number

`body`

the parsed response body to validate

type unknown

returns

void

throws

AssertionError - if no schema is declared for the route+status pair.
ZodError - if the body does not satisfy the declared schema.

assert_error_schemas_structurally_valid
#

(surface: AppSurface): void

Every route's declared error schemas must have an error field at the top level
(conforming to the ApiError base shape {error: string}).
Catches typos in error schema definitions and ensures consumers can always
read .error from error responses.

`surface`

type AppSurface

returns

void

assert_full_middleware_stack
#

(surface: AppSurface, path_prefix: string, expected_middleware: string[]): void

Verify every route under a path prefix has the exact expected middleware stack.

`surface`

the app surface to check

type AppSurface

`path_prefix`

prefix to filter routes (e.g. '/api/')

type string

`expected_middleware`

the exact middleware names in order

type string[]

returns

void

throws

AssertionError - if no routes match `path_prefix`, or if any matching

assert_input_routes_declare_400
#

(surface: AppSurface): void

Every route with non-null input_schema has 400 in error_schemas.

`surface`

type AppSurface

returns

void

assert_jsonrpc_error_response
#

(body: unknown, expected_code?: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">) | undefined): void

Assert that a response body is a valid JSON-RPC error response.
Validates the structure matches JsonrpcErrorResponse and optionally
checks the error code.

`body`

type unknown

`expected_code?`

optional error code to assert

type -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">) | undefined

optional

returns

void

assert_jsonrpc_success_response
#

(body: unknown, output_schema?: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined): void

Assert that a response body is a valid JSON-RPC success response.
Validates the structure matches JsonrpcResponse. When output_schema
is provided, also validates the result field against the declared
output schema — matching the REST round-trip's assert_response_matches_spec.

`body`

type unknown

`output_schema?`

optional Zod schema to validate the result field against

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined

optional

returns

void

assert_keeper_routes_under_prefix
#

(surface: AppSurface, prefixes?: string[]): void

Keeper-protected routes must be under expected path prefixes.
Catches keeper routes accidentally placed outside the API namespace
(e.g., a keeper route at /health or /admin/ instead of /api/...).

`surface`

type AppSurface

`prefixes`

type string[]

default DEFAULT_KEEPER_ROUTE_PREFIXES

returns

void

assert_middleware_errors_propagated
#

(surface: AppSurface): void

Every applicable middleware that declares errors must have those status codes
present in the route's error_schemas.

`surface`

type AppSurface

returns

void

assert_mutation_routes_use_post
#

(surface: AppSurface): void

Routes with non-null input schemas should use POST (or other mutation methods),
not GET.
GET routes with request bodies are technically allowed by HTTP but semantically
suspicious — they bypass browser security assumptions about GET being idempotent.
Query-string-driven filtering (audit log, list endpoints) should use params schemas
or query string parsing, not input schemas.
Note: RPC endpoints (create_rpc_endpoint) use input: z.null() on their
route specs — the dispatcher handles body/query parsing internally. Real input
schemas live in rpc_endpoints surface, not on routes.

`surface`

type AppSurface

returns

void

assert_no_duplicate_routes
#

(surface: AppSurface): void

No duplicate method+path pairs.

`surface`

type AppSurface

returns

void

assert_no_error_info_leakage
#

(body: Record<string, unknown>, context: string): void

Assert that an error response contains no leaky field values.
Checks both field names and string values for patterns indicating
stack traces, SQL, or internal paths.

`body`

type Record<string, unknown>

`context`

description for error messages

type string

returns

void

assert_no_sensitive_fields_in_json
#

(body: unknown, blocklist: readonly string[], context: string): void

Assert that a parsed JSON body contains no fields from the given blocklist.

`body`

type unknown

`blocklist`

type readonly string[]

`context`

description for error messages

type string

returns

void

assert_no_unexpected_public_mutations
#

(surface: AppSurface, allowlist?: string[]): void

Public mutation routes (auth: none + is_mutation) must be in the allowlist.
Catches accidentally unprotected POST/PUT/DELETE routes. Routes like login
and bootstrap are public mutations by design — they go in the allowlist.

`surface`

type AppSurface

`allowlist`

type string[]

default []

returns

void

assert_non_admin_schemas_no_admin_fields
#

(surface: AppSurface, admin_only_fields?: readonly string[]): void

Assert that non-admin route output schemas don't contain admin-only fields.

`surface`

type AppSurface

`admin_only_fields`

type readonly string[]

default ADMIN_ONLY_FIELD_BLOCKLIST

returns

void

assert_only_expected_public_routes
#

(surface: AppSurface, expected_public: string[]): void

Bidirectional check: no unexpected public routes, no missing expected ones.

`surface`

the app surface to check

type AppSurface

`expected_public`

format: ['GET /health', 'POST /api/account/login']

type string[]

returns

void

throws

AssertionError - if the live surface has public routes not in

assert_output_schemas_no_sensitive_fields
#

(surface: AppSurface, sensitive_fields?: readonly string[]): void

Assert that no output schema in the surface contains sensitive field names.

`surface`

type AppSurface

`sensitive_fields`

type readonly string[]

default SENSITIVE_FIELD_BLOCKLIST

returns

void

assert_params_routes_declare_400
#

(surface: AppSurface): void

Every route with non-null params_schema has 400 in error_schemas.

`surface`

type AppSurface

returns

void

assert_protected_routes_declare_401
#

(surface: AppSurface): void

Every protected route has 401 in error_schemas.

`surface`

type AppSurface

returns

void

assert_query_routes_declare_400
#

(surface: AppSurface): void

Every route with non-null query_schema has 400 in error_schemas.

`surface`

type AppSurface

returns

void

assert_rate_limit_retry_after_header
#

(response: Response, body: { retry_after: number; }): void

Assert that a 429 response includes a valid Retry-After header
matching the JSON body's retry_after field.

`response`

type Response

`body`

type { retry_after: number; }

returns

void

assert_response_matches_spec
#

(route_specs: RouteSpec[], method: string, path: string, response: Response): Promise<void>

Validate a response body against the route spec's declared schemas.
For 2xx responses, validates against spec.output.
For error responses, validates against the merged error schema for that status code.

`route_specs`

type RouteSpec[]

`method`

type string

`path`

type string

`response`

type Response

returns

Promise<void>

throws

Error - if no route spec matches `method` + `path`, if the response

assert_role_routes_declare_403
#

db/assert_row.ts view source

(surface: AppSurface): void

Every role/keeper route has 403 in error_schemas.

`surface`

type AppSurface

returns

void

assert_row
#

<T>(row: T | undefined, context?: string | undefined): T

Assert that a row is present, throwing a descriptive error if missing.
Use after INSERT ... RETURNING queries where the database guarantees
a row is returned on success. Replaces bare row! non-null assertions
with an explicit runtime check.

`row`

the row from query_one (T | undefined) or rows[0] (T | undefined)

type T | undefined

`context?`

optional context for the error message (e.g. table or operation name)

type string | undefined

optional

returns

T

the row, guaranteed non-undefined

throws

Error - if `row` is `undefined`

assert_sensitive_routes_rate_limited
#

(surface: AppSurface, sensitive_patterns?: (string | RegExp)[]): void

Sensitive routes must declare rate limiting (rate_limit_key is non-null)
or have 429 in their error schemas.
Matches routes against sensitive patterns and flags any that lack rate limit
declarations. Catches forgotten rate limiting on credential-handling routes.

`surface`

type AppSurface

`sensitive_patterns`

type (string | RegExp)[]

default DEFAULT_SENSITIVE_PATTERNS

returns

void

assert_surface_deterministic
#

(build_surface: () => AppSurface): void

Verify surface generation is deterministic (build twice, compare).

`build_surface`

type () => AppSurface

returns

void

assert_surface_invariants
#

(surface: AppSurface): void

Run all structural invariants. Options-free — applies universally.
Catches schema/surface generation bugs: missing 401/403/400 declarations,
empty descriptions, duplicate routes, middleware-injected error codes
unpropagated to routes, structurally invalid error schemas, error codes
appearing at multiple statuses, and generic 404 schemas on param routes.

`surface`

type AppSurface

returns

void

throws

AssertionError - on the first invariant violation; the message names

assert_surface_matches_snapshot
#

(surface: AppSurface, snapshot_path: string): void

Compare live surface against a committed snapshot JSON file.
Failure message instructs the developer to run gro gen to update the
snapshot — every fuz_app consumer wires the snapshot through a *.gen.ts
file so regeneration goes through the same pipeline as the rest of the
generated artifacts.

`surface`

the live surface to check

type AppSurface

`snapshot_path`

absolute path to the committed JSON snapshot

type string

returns

void

throws

AssertionError - if the live surface does not deep-equal the snapshot,

assert_surface_security_policy
#

db/sql_identifier.ts view source

(surface: AppSurface, options?: SurfaceSecurityPolicyOptions): void

Run security policy invariants. Configurable with sensible defaults.
Checks:
- Sensitive routes are rate-limited
- No unexpected public mutation routes
- Input schemas use mutation methods (not GET)
- Keeper routes under expected prefixes

`surface`

type AppSurface

`options`

type SurfaceSecurityPolicyOptions

default {}

returns

void

throws

AssertionError - on the first policy violation; the message names

assert_valid_sql_identifier
#

(name: string): string

Assert that a string is a valid SQL identifier.
Use this before interpolating table or column names into DDL queries
where parameterized placeholders ($1) are not supported.

`name`

the identifier to validate

type string

returns

string

the validated identifier

throws

Error - if the identifier contains characters outside `[a-zA-Z0-9_]`

audit_error_schema_tightness
#

(surface: AppSurface): ErrorSchemaAuditEntry[]

Audit error schema tightness across all routes in a surface.
Reports which route x status code combinations use generic ApiError
(z.string()) vs specific z.literal() or z.enum() error codes.
Use the output to prioritize progressive tightening of error schemas.

`surface`

type AppSurface

returns

ErrorSchemaAuditEntry[]

audit entries for every route x status combination

AUDIT_EVENT_TYPE_NAME_REGEX
#

RegExp

Letter start, then letters, digits, _, ., /, -. Accepts snake_case,
dotted, and namespaced consumer conventions; rejects empty strings, leading
separators, whitespace, and control characters.

AUDIT_EVENT_TYPES
#

readonly ["login", "logout", "bootstrap", "signup", "password_change", "session_revoke", "session_revoke_all", "token_create", "token_revoke", "token_revoke_all", "permit_grant", ... 9 more ..., "app_settings_update"]

All tracked auth event types. Frozen to convert accidental in-process
mutation (test cross-contamination, cast escapes) into loud TypeErrors.
Not a security boundary — in-process code has many other paths to subvert
audit logging.

AUDIT_LOG_CHANNEL
#

"audit_log"

SSE channel the audit-log stream route publishes on.

AUDIT_LOG_DEFAULT_LIMIT
#

50

Default page size for audit log listings.

AUDIT_LOG_EVENT_SPECS
#

EventSpec[]

SSE event specs for audit log events.
One spec per AUDIT_EVENT_TYPES entry, all sharing the AuditLogEventJson params schema.
Pass to create_app_server's event_specs for surface generation and DEV validation.

audit_log_fire_and_forget
#

<T extends string>(route: Pick<RouteContext, "background_db" | "pending_effects">, input: AuditLogInput<T>, deps: AuditLogFireAndForgetDeps): Promise<...>

Log an audit event without blocking the caller.
Errors are logged — audit logging never breaks auth flows. Uses
background_db so entries persist even when the request transaction
rolls back. Write and on_audit_event callback failures are logged separately.

`route`

background_db and pending_effects from the route context

type Pick<RouteContext, "background_db" | "pending_effects">

`input`

the audit event to record

type AuditLogInput<T>

`deps`

logger, on_audit_event callback, and optional audit_log_config

type AuditLogFireAndForgetDeps

returns

Promise<void>

the settled promise (callers may ignore it)

AUDIT_LOG_INDEXES
#

string[]

audit_log_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: false; input: ZodObject<{ event_type: ZodOptional<ZodNullable<ZodString>>; ... 4 more ...; since_seq: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

AUDIT_LOG_LIST_LIMIT_MAX
#

200

Max audit-log page size. Mirrors the former REST route's clamp.

audit_log_permit_history_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: false; input: ZodObject<{ limit: ZodOptional<ZodNullable<ZodNumber>>; offset: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

audit_log_rpc_context
#

{ get: () => () => AuditLogRpc | null; set: (value?: (() => AuditLogRpc | null) | undefined) => () => AuditLogRpc | null; }

Svelte context carrying the reactive AuditLogRpc accessor. Mirrors
admin_accounts_rpc_context. Unset context falls back to () => null.

AUDIT_LOG_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS audit_log (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  seq SERIAL NOT NULL,\n  event_type TEXT NOT NULL,\n  outcome TEXT NOT NULL DEFAULT 'success',\n  actor_id UUID REFERENCES actor(id) ON DELETE SET NULL,\n  account_id UUID REFERENCES account(id) ON DELETE SET NULL,\n  targe...

AUDIT_LOG_SSE_MAX_PER_SCOPE
#

10

Default max concurrent SSE subscribers per session scope for the audit log.
The audit log SSE subscribes with scope = session_hash and
groups = [account_id]. Only scope is capped — so this limits tabs
per session. An account's total streams across all sessions is bounded
transitively by max_sessions × AUDIT_LOG_SSE_MAX_PER_SCOPE. 10 tabs
per session is a comfortable ceiling for normal use; consumers raising
it above ~50 should consider server-side connection limits.

AUDIT_METADATA_SCHEMAS
#

testing/audit_completeness.ts view source

Readonly<{ login: ZodNullable<ZodObject<{ username: ZodString; }, $loose>>; logout: ZodNull; bootstrap: ZodNullable<ZodObject<{ error: ZodString; }, $loose>>; ... 17 more ...; app_settings_update: ZodObject<...>; }>

Per-event-type metadata Zod schemas. z.looseObject so consumers can
add fields while known ones are validated. The record is frozen to
catch mutation bugs at the key level (e.g. tests that try to swap in a
stub schema); the Zod schemas themselves are reachable and mutable —
freeze isn't a security boundary.

AuditCompletenessTestOptions
#

AuditCompletenessTestOptions

Configuration for describe_audit_completeness_tests.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same one used in production.

type (ctx: AppServerContext) => Array<RouteSpec>

`rpc_endpoints`

RPC endpoint specs — the source RpcAction arrays. Required; the
admin permit flow is RPC-only and the suite hard-fails without it.
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> — the factory form
is required when action handlers must close over the per-test
ctx.app_settings / ctx.deps (e.g. exercising app_settings_update).
The factory must return the same endpoint path regardless of ctx —
it is invoked once at setup with a stub ctx for path lookup and again
per-test by create_app_server for live dispatch.

`app_options`

Optional overrides for AppServerOptions.

type SuiteAppOptions

`db_factories`

Database factories to run tests against. Default: pglite only.

type Array<DbFactory>

AuditEventHandler
#

AuditEventHandler

Audit-event callback shape — the function CreateAppBackendOptions.on_audit_event
accepts and that the helpers in this module return.
Exported so consumers composing multiple handlers (typically
create_ws_auth_guard + create_ws_logout_closer + their own
pre-existing on_audit_event) can annotate their composed callback
without reaching for Parameters<typeof create_ws_auth_guard>[0].

AuditEventType
#

ZodEnum<{ invite_create: "invite_create"; invite_delete: "invite_delete"; app_settings_update: "app_settings_update"; login: "login"; logout: "logout"; bootstrap: "bootstrap"; signup: "signup"; ... 13 more ...; permit_offer_supersede: "permit_offer_supersede"; }>

Zod schema for audit event types.

AuditEventTypeName
#

ZodString

Zod schema for valid audit event-type name strings.

AuditLogConfig
#

AuditLogConfig

Configuration bundle for audit-log event types and metadata schemas.
Lets consumers extend the closed AUDIT_EVENT_TYPES enum with their own
event strings (and metadata Zod schemas) without forking. Pass to
audit_log_fire_and_forget / query_audit_log as the optional config
argument; both default to BUILTIN_AUDIT_LOG_CONFIG.
The DB column is TEXT NOT NULL and never enforced an enum, so consumer
event types round-trip through query_audit_log_list and SSE identically
to builtins.
Constructed configs are deep-frozen (wrapper, event_types,
metadata_schemas) to catch accidental mutation bugs early. Not a
security boundary against in-process code, which can subvert audit
logging through other paths.

`event_types`

All recognized event-type strings — fuz_app builtins plus consumer extras.

type ReadonlyArray<string>

readonly

`metadata_schemas`

Per-event-type metadata schemas. Missing entries skip metadata
validation for that type (row still written; metadata stored as raw JSONB).

type Readonly<Record<string, z.ZodType>>

readonly

AuditLogEvent
#

AuditLogEvent

Audit log row from the database. See AuditLogEventJson for event_type widening rationale.

`id`

type Uuid

`seq`

type number

`event_type`

type AuditEventTypeName

`outcome`

type AuditOutcome

`actor_id`

type Uuid | null

`account_id`

type Uuid | null

`target_account_id`

type Uuid | null

`ip`

type string | null

`created_at`

type string

`metadata`

type Record<string, unknown> | null

AuditLogEventJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; seq: ZodNumber; event_type: ZodString; outcome: ZodEnum<{ success: "success"; failure: "failure"; }>; ... 5 more ...; metadata: ZodNullable<...>; }, $strict>

Zod schema for client-safe audit log event.
event_type is AuditEventTypeName (regex-validated string) — matches
the AuditLogEvent row and the DB's TEXT NOT NULL column. Consumer
types registered via create_audit_log_config({extra_events}) round-trip
through queries, on_audit_event callbacks, and JSON-RPC responses
identically to builtins. AuditLogInput<T> stays parameterized on the
write side so AuditMetadataMap narrowing via get_audit_metadata works.

AuditLogEventWithUsernamesJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; seq: ZodNumber; event_type: ZodString; outcome: ZodEnum<{ success: "success"; failure: "failure"; }>; ... 7 more ...; target_username: ZodNullable<...>; }, $strict>

Zod schema for audit log events with resolved usernames.

AuditLogFireAndForgetDeps
#

AuditLogFireAndForgetDeps

Capabilities required by audit_log_fire_and_forget.
Defined as a slice of AppDeps so call sites can pass the surrounding deps
bundle directly without a structural-compatibility coincidence. The bundled
shape replaces the prior (log, on_audit_event, config?) positional args
— consumers that forgot the trailing config would silently fall back to
BUILTIN_AUDIT_LOG_CONFIG and skip metadata validation for their own
event types. audit_log_config is optional on AppDeps and defaults to
BUILTIN_AUDIT_LOG_CONFIG inside audit_log_fire_and_forget when absent.

AuditLogInput
#

AuditLogInput<T>

Input for creating an audit log entry.

generics

`T`

constraint string

default AuditEventType

`event_type`

type T

`outcome`

type AuditOutcome

`actor_id`

type Uuid | null

`account_id`

type Uuid | null

`target_account_id`

type Uuid | null

`ip`

type string | null

`metadata`

Per-event-type metadata. Builtin T narrows to AuditMetadataMap[T];
consumer strings widen to a generic record (validation runs against
AuditLogConfig.metadata_schemas at insert time).

type

T extends AuditEventType
		? (AuditMetadataMap[T] & Record<string, unknown>) | null
		: Record<string, unknown> | null

AuditLogListInput
#

ZodObject<{ event_type: ZodOptional<ZodNullable<ZodString>>; outcome: ZodOptional<ZodNullable<ZodEnum<{ success: "success"; failure: "failure"; }>>>; account_id: ZodOptional<...>; limit: ZodOptional<...>; offset: ZodOptional<...>; since_seq: ZodOptional<...>; }, $strict>

Input for audit_log_list. All filter fields are optional — omit for the
default newest-first page. since_seq exists for SSE reconnection gap
fill (caller supplies the highest seq seen; server returns everything
after).

AuditLogListOptions
#

AuditLogListOptions

Options for listing audit log entries.

`limit`

type number

`offset`

type number

`event_type`

Event-type filter. Accepts any string — builtins or consumer-registered
via create_audit_log_config({extra_events}). The DB column is
TEXT NOT NULL with no CHECK, so unknown strings simply match nothing.

type string

`event_type_in`

type Array<string>

`account_id`

type Uuid

`outcome`

type AuditOutcome

`since_seq`

When set, only return events with seq greater than this value. Enables SSE reconnection gap fill.

type number

AuditLogListOutput
#

ZodObject<{ events: ZodArray<ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; seq: ZodNumber; event_type: ZodString; outcome: ZodEnum<{ success: "success"; failure: "failure"; }>; ... 7 more ...; target_username: ZodNullable<...>; }, $strict>>; }, $strict>

Output for audit_log_list.

AuditLogPermitHistoryInput
#

ZodObject<{ limit: ZodOptional<ZodNullable<ZodNumber>>; offset: ZodOptional<ZodNullable<ZodNumber>>; }, $strict>

Input for audit_log_permit_history.

AuditLogPermitHistoryOutput
#

auth/audit_log_routes.ts view source

ZodObject<{ events: ZodArray<ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; seq: ZodNumber; event_type: ZodString; outcome: ZodEnum<{ success: "success"; failure: "failure"; }>; ... 7 more ...; target_username: ZodNullable<...>; }, $strict>>; }, $strict>

Output for audit_log_permit_history.

AuditLogRouteOptions
#

AuditLogRouteOptions

Options for audit log route specs.

`required_role`

Role required to access audit routes. Default 'admin'.

type string

`stream`

When provided, includes an SSE route at /audit/stream for realtime audit events.
The subscribe function receives the stream, channels, and the subscriber's account_id
as an identity key — enabling close_by_identity() for auth revocation.

type

{
		subscribe: (stream: SseStream<SseNotification>, options?: SubscribeOptions) => () => void;
		log: Logger;
	}

AuditLogRpc
#

AuditLogRpc

Narrow RPC surface consumed by AuditLogState. Consumers adapt their typed
RPC client to this shape. Mirrors AdminAccountsRpc / AdminInvitesRpc.
Method signatures track the wire spec inputs/outputs directly so the
adapter needs no casts.

`list`

type (input?: AuditLogListInput) => Promise<AuditLogListOutput>

`permit_history`

type (input?: AuditLogPermitHistoryInput) => Promise<AuditLogPermitHistoryOutput>

AuditLogSse
#

AuditLogSse

Convenience factory result for audit log SSE.
Satisfies AuditLogRouteOptions['stream'] and provides the combined
on_audit_event callback (broadcast + guard).

`subscribe`

Subscribe function — pass as part of stream option to create_audit_log_route_specs.

type (stream: SseStream<SseNotification>, options?: SubscribeOptions) => () => void

`log`

Logger — pass as part of stream option to create_audit_log_route_specs.

type Logger

`on_audit_event`

Combined broadcast + guard callback. Pass as on_audit_event on CreateAppBackendOptions.

type (event: AuditLogEvent) => void

`registry`

The underlying registry — exposed for subscriber count monitoring.

type SubscriberRegistry<SseNotification>

AuditLogState
#

inheritance

extends:

Loadable

`events`

type Array<AuditLogEventWithUsernamesJson>

`permit_history_events`

type Array<PermitHistoryEventJson>

`count`

readonly

`connected`

Whether the SSE stream is currently connected.

`constructor`

type new (options?: AuditLogStateOptions | undefined): AuditLogState

`options?`

type AuditLogStateOptions | undefined

optional

`fetch`

type (options?: { event_type?: string | null | undefined; outcome?: "success" | "failure" | null | undefined; account_id?: (string & $brand<"Uuid">) | null | undefined; limit?: number | null | undefined; offset?: number | ... 1 more ... | undefined; since_seq?: number | ... 1 more ... | undefined; } | undefined): Promise<...>

`options?`

type

{ event_type?: string | null | undefined; outcome?: "success" | "failure" | null | undefined; account_id?: (string & $brand<"Uuid">) | null | undefined; limit?: number | null | undefined; offset?: number | ... 1 more ... | undefined; since_seq?: number | ... 1 more ... | undefined; } | undefined

optional

returns Promise<void>

`fetch_permit_history`

type (limit?: number | undefined, offset?: number | undefined): Promise<void>

`limit?`

type number | undefined

optional

`offset?`

type number | undefined

optional

returns Promise<void>

`subscribe`

Connect to the SSE stream for realtime audit events.
New events are prepended to events. EventSource auto-reconnects on
transient errors; since_seq fills gaps on reconnection.

type (): () => void

returns () => void

cleanup function that closes the connection

`disconnect`

Close the SSE connection.

type (): void

returns void

AuditLogStateOptions
#

AuditLogStateOptions

`get_rpc`

Reactive accessor for the RPC adapter. Matches the get_rpc pattern on
AdminAccountsState — null disables fetch operations (SSE still works).

type () => AuditLogRpc | null

`stream_url`

SSE stream URL. Defaults to the shipped admin audit-log stream route.

type string

AuditMetadataMap
#

AuditMetadataMap

Mapped type of metadata shapes per event type, derived from Zod schemas.

AuditOutcome
#

ZodEnum<{ success: "success"; failure: "failure"; }>

Zod schema for audit event outcomes.

AUTH_API_TOKEN_ID_KEY
#

"auth_api_token_id"

Hono context variable name for the authenticated API token id.

AUTH_DROP_TABLES
#

readonly ["app_settings", "invite", "audit_log", "api_token", "auth_session", "permit", "permit_offer", "actor", "account", "bootstrap_lock"]

All auth tables in drop order (children first for FK safety).
The full set created by AUTH_MIGRATIONS — use for clean-slate
test DB initialization. AUTH_TRUNCATE_TABLES is the subset for
between-test data cleanup (excludes audit_log).
When adding tables to AUTH_MIGRATIONS, add them here too.

AUTH_INTEGRATION_TRUNCATE_TABLES
#

auth/migrations.ts view source

string[]

Auth tables including audit_log — for integration tests that exercise
the full middleware stack (login, admin, rate limiting).
Separate from AUTH_TRUNCATE_TABLES because unit-level DB tests that don't
touch audit logging don't need to truncate it.

AUTH_MIGRATION_NAMESPACE
#

"fuz_auth"

Namespace identifier for fuz_app auth migrations.

AUTH_MIGRATION_NS
#

auth/migrations.ts view source

MigrationNamespace

Pre-composed migration namespace for auth tables.

AUTH_MIGRATIONS
#

auth/migrations.ts view source

Migration[]

Auth schema migrations in order.
- v0: Full auth schema — account (with email_verified), actor, permit,
  auth_session, api_token, audit_log (with seq), bootstrap_lock, invite,
  app_settings, plus all indexes and seeds.
- v1: permit_offer table for consentful grants; adds scope_id /
  source_offer_id / revoked_reason to permit and swaps the
  (actor_id, role) partial unique index for a scope-aware variant using
  the all-zeros sentinel UUID. The permit_offer table carries a
  superseded_at terminal state; its partial unique index is scoped by
  (to_account, role, scope, from_actor) so multiple grantors may coexist.

AUTH_SESSION_EXTEND_THRESHOLD_MS
#

number

Extend session when it has less than this remaining (1 day in ms).

AUTH_SESSION_INDEXES
#

string[]

AUTH_SESSION_LIFETIME_MS
#

number

Session lifetime in milliseconds (30 days).

AUTH_SESSION_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS auth_session (\n  id TEXT PRIMARY KEY,\n  account_id UUID NOT NULL REFERENCES account(id) ON DELETE CASCADE,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  expires_at TIMESTAMPTZ NOT NULL,\n  last_seen_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n)"

AUTH_SESSION_TOKEN_HASH_KEY
#

ui/auth_state.svelte.ts view source

"auth_session_token_hash"

Hono context variable name for the authenticated session token hash.
Set by create_request_context_middleware after a successful session lookup.
null when the request is unauthenticated or authenticated via a non-session
credential (bearer token, daemon token). Exposed so handlers can scope
per-session resources (e.g., SSE stream identity for targeted disconnection
on session_revoke) without re-hashing the token.

auth_state_context
#

{ get: (error_message?: string | undefined) => AuthState; get_maybe: () => AuthState | undefined; set: (value: AuthState) => AuthState; }

Svelte context for AuthState.
Use auth_state_context.set(state) in the provider and auth_state_context.get() to access.

AUTH_TRUNCATE_TABLES
#

string[]

Auth table names in truncation order (children first for FK safety).
Consumer projects can spread this into their own list and append app-specific tables.

AuthCleanupDeps
#

AuthCleanupDeps

Dependencies for the cleanup helpers.

inheritance

extends:

QueryDeps

`log`

type Logger

`on_audit_event`

Called after each audit event INSERT succeeds. Typically the same
callback wired into AppDeps.on_audit_event (SSE broadcast). Omit
to skip broadcast — the audit rows still land in the DB.

type ((event: AuditLogEvent) => void) | null

`audit_log_config`

Audit-log config. Only the builtin permit_offer_expire event type is
emitted here, so omitting this is safe — the field exists so consumers
threading the same AppDeps bundle to scheduled cleanup keep using
their registered config (and consumer extensions to the
permit_offer_expire metadata schema get validated).

type AuditLogConfig

AuthCleanupResult
#

AuthCleanupResult

Result of run_auth_cleanup.

`expired_sessions`

Number of expired session rows deleted.

type number

`expired_offers`

Number of expired permit offer rows audit-stamped.

type number

AuthGuardResolver
#

auth/middleware.ts view source

AuthGuardResolver

Resolves a RouteAuth to middleware guard handlers.
Injected into apply_route_specs to decouple route registration
from auth-specific middleware. See fuz_auth_guard_resolver in
auth/route_guards.ts for the standard implementation.

AuthMiddlewareOptions
#

AuthMiddlewareOptions

Per-factory configuration for the standard auth middleware stack.

`allowed_origins`

type Array<RegExp>

`session_options`

type SessionOptions<string>

`path`

Path pattern for middleware (default: '/api/*').

type string

`daemon_token_state`

Daemon token state for keeper auth. Omit to disable daemon token middleware.

type DaemonTokenState

`bearer_ip_rate_limiter`

Rate limiter for bearer token auth attempts (per-IP). Pass null to disable.

type RateLimiter | null

authorize_admin_or_holder
#

(auth: RequestContext, input: { to_account_id: string; role: string; scope_id: string | null; }, deps: Pick<RouteFactoryDeps, "log">, ctx: ActionContext): boolean | Promise<...>

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.

`auth`

type RequestContext

`input`

type { to_account_id: string; role: string; scope_id: string | null; }

`deps`

type Pick<RouteFactoryDeps, "log">

`ctx`

type ActionContext

returns

boolean | Promise<boolean>

AuthSession
#

AuthSession

Server-side auth session, keyed by blake3 hash of session token.

`id`

type string

`account_id`

type Uuid

`created_at`

type string

`expires_at`

type string

`last_seen_at`

type string

AuthSessionJson
#

ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; created_at: ZodString; expires_at: ZodString; last_seen_at: ZodString; }, $strict>

Zod schema for AuthSession — id is the blake3 hash, safe for client.

AuthSessionRouteOptions
#

ui/auth_state.svelte.ts view source

AuthSessionRouteOptions

Shared options for route factories that create sessions and rate-limit by IP.
Extended by AccountRouteOptions and SignupRouteOptions.
Consumers can destructure these from AppServerContext once and spread into multiple factories.

`session_options`

type SessionOptions<string>

`ip_rate_limiter`

Rate limiter for auth attempts, keyed by client IP. Pass null to disable.

type RateLimiter | null

AuthState
#

`verifying`

`verified`

`verify_error`

type string | null

`account`

type SessionAccount | null

`actor`

type ActorSummaryJson | null

`permits`

type Array<PermitSummaryJson>

`active_permits`

type Array<PermitSummaryJson>

readonly

`roles`

type Array<string>

readonly

`needs_bootstrap`

True when bootstrap is available (no accounts exist yet).

`check_session`

Check auth state and bootstrap availability.
Fetches GET /api/account/status — returns account info (200) or
401 with optional bootstrap_available flag.
Called on init, and after login/bootstrap to refresh state.

type (): Promise<void>

returns Promise<void>

`login`

Log in with username and password. Translates 401 / 429 to friendly
messages on verify_error; refreshes the session via check_session
on success.

type (username: string, password: string): Promise<boolean>

`username`

type string

`password`

type string

returns Promise<boolean>

true if login succeeded, false otherwise

`bootstrap`

Bootstrap the first keeper account using a single-use token.

type (token: string, username: string, password: string): Promise<boolean>

`token`

type string

`username`

type string

`password`

type string

returns Promise<boolean>

true if bootstrap succeeded, false otherwise

`signup`

Sign up via invite (or open signup, when app_settings.open_signup
is true server-side). Translates 403 / 409 / 429 to friendly messages
on verify_error.

type (username: string, password: string, email?: string | undefined): Promise<boolean>

`username`

type string

`password`

type string

`email?`

type string | undefined

optional

returns Promise<boolean>

true if signup succeeded, false otherwise

`logout`

Log out — best-effort POST /api/account/logout to clear the session
cookie, then clears local state regardless of the network outcome.

type (): Promise<void>

returns Promise<void>

AuthTestApps
#

AuthTestApps

Pre-built Hono apps for each auth level, shared across adversarial test suites.

`public`

type Hono

`authed`

type Hono

`keeper`

type Hono

`by_role`

type Map<string, Hono>

BackendWebsocketTransport
#

actions/action_types.ts view source

inheritance

implements:

FilterableBroadcastTransport

`transport_name`

readonly

`add_connection`

Add a new WebSocket connection with auth info.
Session connections pass a token hash for targeted revocation.
Bearer token connections (api_token) pass the api_token.id so the
socket can be closed when that specific token is revoked without
tearing down the account's other sockets. Daemon-token connections
pass null for both — they're only reachable via
close_sockets_for_account.

type (ws: WSContext<unknown>, token_hash: string | null, account_id: string & $brand<"Uuid">, api_token_id?: string | null): string & $brand<"Uuid">

`ws`

type WSContext<unknown>

`token_hash`

type string | null

`account_id`

type string & $brand<"Uuid">

`api_token_id`

type string | null

default null

returns string & $brand<"Uuid">

the freshly assigned connection_id (branded Uuid)

`remove_connection`

Remove a WebSocket connection and its auth tracking data.
Idempotent — safe to call after revocation has already cleaned up.

type (ws: WSContext<unknown>): void

`ws`

type WSContext<unknown>

returns void

`close_sockets_for_session`

Close all sockets associated with a specific session token hash.

type (token_hash: string): number

`token_hash`

type string

returns number

the number of sockets closed

`close_sockets_for_account`

Close all sockets associated with a specific account.

type (account_id: string & $brand<"Uuid">): number

`account_id`

type string & $brand<"Uuid">

returns number

the number of sockets closed

`close_sockets_for_token`

Close all sockets associated with a specific API token.
Used on token_revoke audit events so revoking one token doesn't
tear down the account's session-authenticated sockets or other
tokens' sockets.

type (api_token_id: string): number

`api_token_id`

type string

returns number

the number of sockets closed

`send`

type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }, options?: TransportSendOptions | undefined): Promise<...>

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`broadcast_filtered`

Broadcast to connections whose identity satisfies a predicate.
Used by the broadcast API when a consumer supplies a subscription ACL hook
(e.g. tx's tx_run_created only reaches the account that owns the run).
When no ACL is needed, callers should prefer send(message) / #broadcast
to skip the per-connection predicate overhead.

type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; } | { ...; }, predicate: (identity: ConnectionIdentity) => boolean): number

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; } | { ....

`predicate`

type (identity: ConnectionIdentity) => boolean

returns number

the number of sockets the message was sent to

`send_to_account`

Send a message to every socket bound to a specific account.
Targeted per-account fan-out for any flow where the delivery target
is a single known account. Prefer this over broadcast_filtered when
the filter is exactly "this account_id"; reach for broadcast_filtered
when the ACL is an arbitrary predicate over ConnectionIdentity.
Mirrors close_sockets_for_account on the send side: every connection
for the account (session, bearer, and daemon-token) receives the
message.

type (account_id: string & $brand<"Uuid">, message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { ...; }; } | { ...; }): number

`account_id`

type string & $brand<"Uuid">

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; } | { ....

returns number

the number of sockets the message was sent to

`is_ready`

type (): boolean

returns boolean

`get_connection_count`

Number of currently tracked WebSocket connections.
Read-only counter intended for telemetry, logging, and tests.
Counts every entry in the connection map — including connections
that have been closed by the peer but not yet removed by the WS
adapter's onClose callback.

type (): number

returns number

BaseHandlerContext
#

BaseHandlerContext

Minimum per-request context every server-side WS handler receives.
Consumers extend this with domain-specific fields via the dispatcher's
extend_context option. Mirrors the HTTP-side ActionContext and Rust's
Ctx<'a> shape (request_id + NotifyFn + CancellationToken).

`request_id`

JSON-RPC envelope request id — echoed back on the response.

type JsonrpcRequestId

`connection_id`

Stable per-socket connection id assigned by
BackendWebsocketTransport.add_connection — same reference across every
message on this socket, also passed to on_socket_open /
on_socket_close. Consumers key per-connection domain state on this
directly instead of trying to derive it from signals (which are
per-message composites of AbortSignal.any([socket, request])).

type Uuid

`notify`

Send a request-scoped JSON-RPC notification to the originating socket.
Not a broadcast — the message only reaches the client whose request
triggered this handler.

type (method: string, params: unknown) => void

`signal`

Fires on socket close OR on a client-initiated cancel notification
matching this request's id. Streaming handlers poll for early
termination; per-message composite (AbortSignal.any([socket, request]))
— not stable across messages.

type AbortSignal

baseline
#

(db: Db, ns: MigrationNamespace, names: readonly string[]): Promise<void>

Insert tracker rows for the named migrations of a namespace without
executing them.
Used to promote an existing schema (e.g. produced by a pre-0.42 build,
preserved through a tracker-shape upgrade) into the new identity tracker.
baseline() trusts the operator-supplied list — it does not verify that
the schema actually matches what the named migrations would have produced.
Pair with a schema-assertion script post-baseline before re-enabling traffic.
Contract:
- Probes for the pre-0.42 tracker shape; throws old-tracker-shape if
  found (DDL with IF NOT EXISTS would otherwise no-op against the old
  table and the INSERT would fail with a confusing column-not-found).
- Creates the new-shape schema_version table if missing — cutover
  scripts that just dropped the old-shape table can call baseline()
  directly with no separate DDL step.
- Acquires the same per-namespace advisory lock as run_migrations (with
  the same try/catch fallback for environments lacking pg_advisory_lock).
- Refuses if any tracker rows already exist *for this namespace* — lets
  multi-call baseline scripts resume after partial failure (completed
  namespaces guard themselves while remaining ones still run).
- Verifies the supplied names are a strict prefix of the namespace's
  current migrations array — a name not in the array, or out of order,
  errors before any INSERT.
- Writes sequences 0..N-1 in one transaction.

`db`

the database instance

type Db

`ns`

the namespace whose migrations are being baselined

type MigrationNamespace

`names`

prefix of ns.migrations[].name to record as already-applied

type readonly string[]

returns

Promise<void>

throws

MigrationError - with `kind` of `old-tracker-shape`,

BaseServerEnv
#

ZodObject<{ NODE_ENV: ZodEnum<{ development: "development"; production: "production"; }>; PORT: ZodDefault<ZodCoercedNumber<unknown>>; HOST: ZodDefault<ZodString>; ... 9 more ...; SMTP_PASSWORD: ZodOptional<...>; }, $strict>

Base Zod schema for server environment variables.
Provides the common fields used by fuz apps:
server config, database, auth, security, public URLs, and SMTP.
Apps can use directly or extend with app-specific fields via .extend().

BearerAuthMocks
#

BearerAuthMocks

Mocks bundle returned by create_bearer_auth_mocks.

`mock_validate`

type ReturnType<typeof vi.fn>

`mock_find_by_id`

type ReturnType<typeof vi.fn>

`mock_find_by_account`

type ReturnType<typeof vi.fn>

`mock_find_active_for_actor`

type ReturnType<typeof vi.fn>

BearerAuthTestCase
#

BearerAuthTestCase

A full test case for the table-driven bearer auth runner.

inheritance

extends:

BearerAuthTestOptions

`validate_expectation`

Whether the request should reach token validation or be short-circuited.

type 'called' | 'not_called'

`assert_context_set`

If true, assert REQUEST_CONTEXT_KEY and CREDENTIAL_TYPE_KEY were set to api_token values.

type boolean

`expected_api_token_id`

If set, assert AUTH_API_TOKEN_ID_KEY was set to this value after a successful bearer auth.

type string

`assert_context_preserved`

If true, assert the pre-existing session context and credential type are preserved.

type boolean

`assert_mocks`

Optional callback for custom spy assertions on the mocks bundle.

type (mocks: BearerAuthMocks) => void

BearerAuthTestOptions
#

BearerAuthTestOptions

Mock configuration for bearer auth middleware test setup.

`name`

Test description.

type string

`headers`

Request headers.

type Record<string, string>

`pre_context`

Pre-set request context (simulates session already resolved).

type RequestContext

`mock_validate_result`

What query_validate_api_token() returns.

type unknown

`mock_find_by_id_result`

What query_account_by_id() returns.

type unknown

`mock_find_by_account_result`

What query_actor_by_account() returns.

type unknown

`mock_permits_result`

What query_permit_find_active_for_actor() returns.

type unknown

`expected_status`

Expected HTTP status, or 'next' if the middleware should call next().

type number | 'next'

`expected_error`

Expected error field in JSON response body.

type string

`expected_error_schema`

Zod schema to validate error response body against. Defaults to ApiError when expected_error is set.

type z.ZodType

bootstrap_account
#

(deps: BootstrapAccountDeps, provided_token: string, input: BootstrapAccountInput): Promise<BootstrapAccountResult>

Bootstrap the first account with keeper and admin privileges.
Uses an atomic bootstrap_lock UPDATE to prevent concurrent bootstrap
attempts (TOCTOU). The full flow runs in a single transaction:
1. Read and verify the bootstrap token (before transaction)
2. Hash the password (CPU-intensive, before transaction)
3. Acquire the bootstrap lock atomically (inside transaction)
4. Create account + actor
5. Grant keeper and admin permits (no expiry, granted_by = null)
6. Delete the token file (after commit, reported via token_file_deleted)

`deps`

database, token path, filesystem callbacks, and password hashing

type BootstrapAccountDeps

`provided_token`

the bootstrap token from the user

type string

`input`

username and password

type BootstrapAccountInput

returns

Promise<BootstrapAccountResult>

the created account, actor, and permits — or a bootstrap failure

BOOTSTRAP_LOCK_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS bootstrap_lock (\n  id INTEGER PRIMARY KEY DEFAULT 1 CHECK (id = 1),\n  bootstrapped BOOLEAN NOT NULL DEFAULT false\n)"

BOOTSTRAP_LOCK_SEED
#

"\nINSERT INTO bootstrap_lock (id, bootstrapped)\n SELECT 1, EXISTS(SELECT 1 FROM account)\n ON CONFLICT DO NOTHING"

Seed the bootstrap_lock table, setting bootstrapped based on whether accounts exist.

bootstrap_test_account
#

(options: BootstrapTestAccountOptions): Promise<{ account: { id: string & $brand<"Uuid">; username: string; }; actor: { id: string & $brand<"Uuid">; }; api_token: string; session_cookie: string; }>

Bootstrap a test account with credentials.
Creates an account with actor, grants roles, creates an API token,
creates a session, and signs a session cookie. Shared by
create_test_app_server and TestApp.create_account.

`options`

type BootstrapTestAccountOptions

returns

Promise<{ account: { id: string & $brand<"Uuid">; username: string; }; actor: { id: string & $brand<"Uuid">; }; api_token: string; session_cookie: string; }>

BootstrapAccountDeps
#

BootstrapAccountDeps

Dependencies for bootstrap_account.

`db`

type Db

`token_path`

Path to the bootstrap token file on disk.

type string

`read_text_file`

Read a file's contents as a string.

type (path: string) => Promise<string>

`delete_file`

Delete a file.

type (path: string) => Promise<void>

`password`

Only hashing is needed — verification happens separately during login.

type Pick<PasswordHashDeps, 'hash_password'>

`log`

Structured logger instance.

type Logger

BootstrapAccountFailure
#

BootstrapAccountFailure

Bootstrap failure result.

BootstrapAccountInput
#

BootstrapAccountInput

Input for the bootstrap account creation.

`username`

type string

`password`

type string

BootstrapAccountResult
#

BootstrapAccountResult

Bootstrap account result — either success or a bootstrap verification failure.

BootstrapAccountSuccess
#

ui/BootstrapForm.svelte view source

BootstrapAccountSuccess

Successful bootstrap result with the created entities.

`ok`

type true

`account`

type Account

`actor`

type Actor

`permits`

type {keeper: Permit; admin: Permit}

`token_file_deleted`

Whether the bootstrap token file was successfully deleted after account creation.

type boolean

BootstrapForm
#

`redirect_on_bootstrap?`

Path to navigate to after the first-keeper account is created.

type string

optional

BootstrapInput
#

ZodObject<{ token: ZodString; username: ZodString; password: ZodString; }, $strict>

Input for POST /bootstrap. token is the one-shot token file contents.

BootstrapOutput
#

ZodObject<{ ok: ZodLiteral<true>; username: ZodString; }, $strict>

Output for POST /bootstrap. Session cookie is the operative side effect.

BootstrapRouteOptions
#

BootstrapRouteOptions

Per-factory configuration for bootstrap route specs.
bootstrap_status is runtime state (a mutable ref), not a dep or options value —
it is passed through so the route handler can flip it on success.

`session_options`

type SessionOptions<string>

`bootstrap_status`

Shared mutable reference — flipped to false after successful bootstrap.

type BootstrapStatus

`on_bootstrap`

Called after successful bootstrap (account + session created).
Use for app-specific post-bootstrap work like generating API tokens.

type (result: BootstrapAccountSuccess, c: Context) => Promise<void>

`ip_rate_limiter`

Rate limiter for bootstrap attempts (per-IP). Pass null to disable.

type RateLimiter | null

BootstrapStatus
#

BootstrapStatus

Bootstrap status — runtime state computed once at startup.

`available`

type boolean

`token_path`

type string | null

BootstrapTestAccountOptions
#

BootstrapTestAccountOptions

Options for bootstrap_test_account.

`db`

type Db

`keyring`

type Keyring

`session_options`

type SessionOptions<string>

`password`

type PasswordHashDeps

`username`

type string

`password_value`

type string

`roles`

type Array<string>

BroadcastApi
#

BroadcastApi

Loose base shape for a broadcast API. Consumers typically declare a
stricter per-method interface (e.g. BackendActionsApi) and pin it via
the type parameter on create_broadcast_api.

build_broadcast_api
#

<TApi extends object>(options: { harness: WsTestHarness; specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[]; }): TApi

Wire a typed broadcast API against the harness's transport, matching
how a consumer's real backend composes the stack. Returns the typed
API so tests can call .tx_run_created(...) / .workspace_changed(...)
etc. directly.
const harness = create_ws_test_harness<BaseHandlerContext>({specs, handlers});
const broadcast = build_broadcast_api<MyBackendActionsApi>({
  harness,
  specs: my_broadcast_action_specs,
});
const client = await harness.connect(keeper_identity());
await broadcast.tx_run_created({run_id: '...', ...});
await client.wait_for(is_notification('tx_run_created'));

`options`

type

{ harness: WsTestHarness; specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[]; }

returns

TApi

build_permit_offer_accepted_notification
#

(params: { offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }): { ...; }

`params`

type

{ offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }

returns

{ [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

build_permit_offer_declined_notification
#

(params: { offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }): { ...; }

`params`

type

{ offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }

returns

{ [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

build_permit_offer_received_notification
#

(params: { offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }): { ...; }

`params`

type

{ offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }

returns

{ [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

build_permit_offer_retracted_notification
#

(params: { offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }): { ...; }

`params`

type

{ offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; }

returns

{ [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

build_permit_offer_supersede_notification
#

(params: { offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; reason: "sibling_accepted" | ... 1 more ... | "scope_destroyed"; cause_id: string & $brand<...>; }): { ...; }

`params`

type

{ offer: { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }; reason: "sibling_accepted" | ... 1 more ... | "scope_destroyed"; cause_...

returns

{ [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

build_permit_revoke_notification
#

(params: { permit_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<"Uuid">) | null; reason: string | null; }): { [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { ...; } | undefined; }

`params`

type { permit_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<"Uuid">) | null; reason: string | null; }

returns

{ [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

build_request_context
#

(deps: QueryDeps, account_id: string): Promise<RequestContext | null>

Build a full RequestContext from an account id.
Shared helper used by session, bearer, and daemon token middleware,
as well as WebSocket upgrade handlers. Does the account → actor → permits
lookup pipeline and returns the composed context, or null if
the account or actor is not found.

`deps`

query dependencies

type QueryDeps

`account_id`

the account to build context for

type string

returns

Promise<RequestContext | null>

a request context, or null if account/actor not found

BUILTIN_AUDIT_LOG_CONFIG
#

AuditLogConfig

Builtin fuz_app audit-log config — every existing event type and its metadata schema.

BUILTIN_ROLE_OPTIONS
#

ReadonlyMap<string, Required<RoleOptions>>

Builtin role configs. Not overridable by consumers.
Typed ReadonlyMap for the contract — but JS Maps don't honor
Object.freeze for .set / .delete / .clear (they mutate internal
slots, not own properties), so freeze adds no runtime guard here. Read
once at startup by create_role_schema and the admin / permit-offer
action factories; runtime mutation has no effect on already-built role
schemas.

BUILTIN_ROLES
#

readonly ["keeper", "admin"]

The builtin role names as a const tuple.

BuiltinRole
#

ZodEnum<{ keeper: "keeper"; admin: "admin"; }>

Zod schema for builtin roles only.

cancel_action
#

Action<BaseHandlerContext>

Protocol-action tuple — spread into the server's actions array (or via
protocol_actions from actions/protocol.ts) so the dispatcher registers the
spec for input validation and so create_rpc_client codegen sees the
method. The client doesn't need to call it directly;
FrontendWebsocketClient.request({signal}) sends the cancel notification
automatically when the signal fires.

cancel_action_spec
#

{ method: string; kind: "remote_notification"; initiator: "frontend"; auth: null; side_effects: true; input: ZodObject<{ request_id: ZodUnion<readonly [ZodString, ZodNumber]>; }, $strict>; output: ZodVoid; async: true; description: string; }

ActionSpec for the shared cancel. auth: null matches every other
remote-notification spec — upgrade-time auth has already admitted the
socket, so per-action auth on a fire-and-forget notification is moot. The
per-connection {request_id → AbortController} map enforces socket-scoped
ownership naturally: a different socket's cancel for the same id misses
in its own map.

cancel_handler
#

(): void

Placeholder handler — cancel semantics are owned by register_action_ws,
not invoked per-handler. Exported for symmetry with the Action
tuple shape; the dispatcher short-circuits cancel notifications before any
handler lookup happens.

returns

void

CancelNotificationParams
#

ZodObject<{ request_id: ZodUnion<readonly [ZodString, ZodNumber]>; }, $strict>

Params for the cancel notification. request_id is the id of the
pending request to abort. Must match the id of a request sent on the
same socket; cancels from other sockets (or for unknown ids) are ignored.

CardinalPosition
#

CardinalPosition

Basic position options for UI elements (cardinal directions).

check_bootstrap_status
#

(deps: CheckBootstrapStatusDeps, options: { token_path: string | null; }): Promise<BootstrapStatus>

Check bootstrap availability at startup.
Bootstrap is available when:
1. A token path is configured
2. The token file exists on disk
3. The bootstrap_lock table shows bootstrapped = false

`deps`

filesystem and database access for the check

type CheckBootstrapStatusDeps

`options`

static configuration including token_path

type { token_path: string | null; }

returns

Promise<BootstrapStatus>

an object with available (boolean) and token_path (string | null)

check_daemon_health
#

(deps: FetchDeps, port: number, host?: string, timeout_ms?: number): Promise<boolean>

Check if a daemon is healthy by probing its /health endpoint.
Complements is_daemon_running (PID check) with an HTTP liveness probe.
Requires the daemon to register a /health route (e.g. via create_health_route_spec).

`deps`

runtime with fetch capability

type FetchDeps

`port`

port the daemon should be listening on

type number

`host`

hostname (default localhost)

type string

default 'localhost'

`timeout_ms`

request timeout in milliseconds (default 2000)

type number

default 2000

returns

Promise<boolean>

true if the health endpoint responds with 2xx

check_error_response_fields
#

(body: Record<string, unknown>): string[]

List the fields in an error response body that are not in the known-safe set.
Error schemas use z.looseObject (intentional — multiple producers), but
test responses should be checked for fields that could leak information.

`body`

type Record<string, unknown>

returns

string[]

array of unexpected field names (empty = clean)

CheckBootstrapStatusDeps
#

CheckBootstrapStatusDeps

Dependencies for checking bootstrap status at startup.

`stat`

type (path: string) => Promise<StatResult | null>

`db`

type Db

`log`

type Logger

cleanup_expired_permit_offers
#

(deps: AuthCleanupDeps): Promise<number>

Sweep expired permit offers and emit one permit_offer_expire audit
event per row.
Returns the count of offers audit-stamped. The offer rows themselves are
preserved — offers carry audit value for the history view even after
expiry, and accepted rows are the provenance for the resulting permit
(deleting expired rows would not threaten that, but keeping them uniform
with the retention policy for terminal rows is simpler).

`deps`

type AuthCleanupDeps

returns

Promise<number>

clear_session_cookie
#

<T>(c: Context<any, any, {}>, options: SessionOptions<T>): void

Clear the session cookie on a response.

`c`

type Context<any, any, {}>

`options`

type SessionOptions<T>

returns

void

ClientApiTokenJson
#

cli/logger.ts view source

ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; name: ZodString; expires_at: ZodNullable<ZodString>; last_used_at: ZodNullable<...>; last_used_ip: ZodNullable<...>; created_at: ZodString; }, $strict>

Zod schema for client-safe API token listing (excludes token_hash).

CliLogger
#

CliLogger

`error`

Logs an error via Logger (gets Logger's error prefix).

type (...args: Array<unknown>) => void

`warn`

Logs a warning via Logger (gets Logger's warn prefix).

type (...args: Array<unknown>) => void

`info`

Logs info via Logger (gets Logger's label prefix).

type (...args: Array<unknown>) => void

`debug`

Logs debug via Logger (gets Logger's debug prefix).

type (...args: Array<unknown>) => void

`raw`

Logs raw output via Logger (no prefix, no level filtering).

type (...args: Array<unknown>) => void

`success`

Logs a success message with [done] prefix at info level.

type (msg: string) => void

`skip`

Logs a skip message with [skip] prefix at info level.

type (msg: string) => void

`step`

Logs a step message with ==> prefix at info level.

type (msg: string) => void

`header`

Logs a header with === title === decoration at info level.

type (title: string) => void

`dim`

Logs a dimmed message at info level.

type (msg: string) => void

`logger`

The underlying Logger instance.

type Logger

collect_json_keys_recursive
#

(value: unknown): Set<string>

Recursively collect all key names from a parsed JSON value.
Walks objects and arrays to find every property name at any nesting depth.

`value`

type unknown

returns

Set<string>

collect_json_schema_property_names
#

(schema: unknown): Set<string>

Recursively collect all property names from a JSON Schema.
Walks properties, items, allOf/anyOf/oneOf, and
additionalProperties to find every declared field name at any depth.

`schema`

type unknown

returns

Set<string>

collect_middleware_errors
#

(middleware: MiddlewareSpec[], route_path: string): Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>> | null

Collect error schemas from all middleware that applies to a route path.

`middleware`

type MiddlewareSpec[]

`route_path`

type string

returns

Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>> | null

merged middleware error schemas, or null if none

colors
#

cli/util.ts view source

{ readonly green: "" | "\u001B[32m"; readonly yellow: "" | "\u001B[33m"; readonly blue: "" | "\u001B[34m"; readonly red: "" | "\u001B[31m"; readonly cyan: "" | "\u001B[36m"; readonly dim: "" | "\u001B[2m"; readonly bold: "" | "\u001B[1m"; readonly reset: "" | "\u001B[0m"; }

ColumnInfo
#

ui/ColumnLayout.svelte view source

ColumnInfo

Column metadata from information_schema.

`column_name`

type string

`data_type`

type string

`is_nullable`

type string

ColumnLayout
#

`aside`

type Snippet

`children`

type Snippet

`column_width?`

CSS width of the fixed aside column.

type string

optional

CommandDeps
#

CommandDeps

Command execution.

`run_command`

Run a command and return the result. Never throws — failures surface as
success: false.
options.cwd sets the child's working directory. options.signal aborts
the child when the signal fires. options.timeout_ms kills the child
after the given duration and returns timed_out: true on the result.

type

(
		cmd: string,
		args: Array<string>,
		options?: RunCommandOptions,
	) => Promise<CommandResult>

CommandMeta
#

CommandMeta<TCategory>

Command metadata for help generation.

generics

`TCategory`

constraint string

default string

`schema`

type z.ZodType

`summary`

type string

`usage`

type string

`category`

type TCategory

CommandResult
#

CommandResult

Result of executing a command.
timed_out is present only when timeout_ms was passed in RunCommandOptions
and the process was killed after exceeding the timeout. Callers that pass
timeout_ms should check this flag to distinguish timeout from exit-code failure.

`success`

type boolean

`code`

type number

`stdout`

type string

`stderr`

type string

`timed_out`

type boolean

compose_gen_file
#

ui/ConfirmButton.svelte view source

(input: { origin_path: string; imports: ImportBuilder; blocks: readonly string[]; }): string

Wrap the per-*.gen.ts boilerplate (banner + imports.build() +
blocks join + template literal) into one call. Returns the full file body
as a string ready to return from a Gen function.
Each consumer producer collapses to one compose_gen_file call wrapping
the helper invocations.

`input`

type { origin_path: string; imports: ImportBuilder; blocks: readonly string[]; }

returns

string

examples

export const gen: Gen = ({origin_path}) => {
  const imports = new ImportBuilder();
  return compose_gen_file({
    origin_path,
    imports,
    blocks: [
      generate_action_specs_record(all_action_specs, imports),
      generate_action_inputs_outputs(all_action_specs, imports),
      generate_action_event_datas(all_action_specs, imports),
    ],
  });
};Empty blocks ('') are filtered out so helpers that short-circuit on
empty spec sets don't introduce stray double blank lines.

confirm
#

cli/util.ts view source

(runtime: TerminalDeps, message: string): Promise<boolean>

Prompt for yes/no confirmation.

`runtime`

runtime with stdout_write and stdin_read capabilities

type TerminalDeps

`message`

message to display

type string

returns

Promise<boolean>

true if user confirms, false otherwise

ConfirmButton
#

`onconfirm`

type (popover: Popover) => void

`popover_button_attrs?`

type SvelteHTMLElements['button'] | undefined

optional

`hide_on_confirm?`

type boolean | undefined

optional

`popover_content?`

Unlike on PopoverButton this is optional and has a confirm arg

type Snippet<[popover: Popover, confirm: () => void]> | undefined

optional

`popover_button_content?`

Content for the popover button

type Snippet<[popover: Popover, confirm: () => void]> | undefined

optional

`children?`

Unlike on PopoverButton this has a confirm arg

type Snippet<[popover: Popover, confirm: () => void]> | undefined

optional

ConnectionIdentity
#

ConnectionIdentity

Auth identity attached to a single WebSocket connection.
One record per connection. token_hash is set for cookie-session
connections, api_token_id for bearer (api_token) connections, and
both are null for daemon-token connections (reachable only via
BackendWebsocketTransport.close_sockets_for_account).

`token_hash`

Blake3 session token hash, or null for non-session credentials.

type string | null

`account_id`

Authenticated account id. Always set.

type Uuid

`api_token_id`

api_token.id for bearer-authenticated connections, else null.

type string | null

CoverageFilterOptions
#

auth/account_actions.ts view source

CoverageFilterOptions

Options controlling which routes/statuses are considered for coverage.

`ignore_routes`

Routes to skip, in 'METHOD /path' format.

type Array<string>

`ignore_statuses`

HTTP status codes to skip.

type Array<number>

create_account_actions
#

(deps: AccountActionDeps, options?: AccountActionOptions): RpcAction[]

Create the self-service account RPC actions.

`deps`

AccountActionDeps slice of AppDeps (log, on_audit_event, optional audit_log_config)

type AccountActionDeps

`options`

per-factory configuration

type AccountActionOptions

default {}

returns

RpcAction[]

the RpcAction array to spread into a create_rpc_endpoint call

create_account_route_specs
#

(deps: RouteFactoryDeps, options: AccountRouteOptions): RouteSpec[]

Create account route specs for session-based auth.
The returned specs cover the three flows that stay REST after the RPC
migration (login, logout, password change). Self-service session/token
management and verify are on auth/account_actions.ts.

`deps`

stateless capabilities (keyring, password, log)

type RouteFactoryDeps

`options`

per-factory configuration (session_options, ip_rate_limiter, login_account_rate_limiter)

type AccountRouteOptions

returns

RouteSpec[]

route specs (not yet applied to Hono)

create_account_status_route_spec
#

(options?: AccountStatusOptions | undefined): RouteSpec

Create the account status route spec.
Handles both authenticated and unauthenticated requests:
- Authenticated: returns {account} with 200
- Unauthenticated: returns 401 with optional bootstrap_available flag
This eliminates the need for a separate /health fetch on page load —
the frontend gets both session state and bootstrap availability in one request.

`options?`

optional configuration (bootstrap_status for bootstrap detection)

type AccountStatusOptions | undefined

optional

returns

RouteSpec

a single account status route spec

create_action_event
#

<TMethod extends string = string>(environment: ActionEventEnvironment, spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<...>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }, input: unknown, initial_phase?: "send_request" | ... 8 more ... | undefined): ActionEvent<...>

Create an action event from a spec and initial input.

`environment`

`spec`

type

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

`input`

type unknown

`initial_phase?`

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute" | undefined

optional

returns

ActionEvent<TMethod, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

throws

Error - if `initial_phase` is omitted and the executor cannot

create_action_event_from_json
#

<TMethod extends string = string>(json: ActionEventDataUnion<TMethod>, environment: ActionEventEnvironment): ActionEvent<TMethod, "send_request" | ... 7 more ... | "execute", "initial" | ... 3 more ... | "failed">

Reconstruct an action event from serialized JSON data.

`json`

type ActionEventDataUnion<TMethod>

`environment`

returns

ActionEvent<TMethod, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

throws

Error - if the JSON's `method` field has no spec registered in `environment`

create_action_event_spec
#

(spec: { method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { ...; } | null; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }, options?: ActionEventOptions | undefined): EventSpec

Derive an EventSpec from an ActionSpec.
Only remote_notification actions can become push events.

`spec`

the action spec (must have kind: 'remote_notification')

type

{ method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { role: string; } | null; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }

`options?`

optional event-specific options (channel)

type ActionEventOptions | undefined

optional

returns

EventSpec

an EventSpec ready for create_validated_broadcaster

throws

Error - if `spec.kind` is not `'remote_notification'`

create_action_route_spec
#

auth/admin_actions.ts view source

(spec: { method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { ...; } | null; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }, options: ActionRouteOptions): RouteSpec

Derive a RouteSpec from an ActionSpec and options.
Only request_response actions (which require non-null auth) can become routes.
remote_notification actions (auth null) should use create_action_event_spec.
local_call actions are not for HTTP transport.
Error schemas are transport-specific (keyed by HTTP status codes) and belong
on the options, not the action spec. Action specs define the contract;
transport concerns like HTTP error codes are added at the bridge layer.

`spec`

the action spec (must have non-null auth)

type

{ method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { role: string; } | null; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; }

`options`

HTTP-specific options (path, handler, optional overrides)

type ActionRouteOptions

returns

RouteSpec

a RouteSpec ready for apply_route_specs

throws

Error - if `spec.auth` is null (only `request_response` actions can

create_admin_actions
#

(deps: AdminActionDeps, options?: AdminActionOptions): RpcAction[]

Create the admin-only RPC actions.

`deps`

AdminActionDeps slice of AppDeps (log, on_audit_event, optional audit_log_config)

type AdminActionDeps

`options`

role schema for grantable_roles derivation

type AdminActionOptions

default {}

returns

RpcAction[]

the RpcAction array to spread into a create_rpc_endpoint call

create_admin_rpc_adapters
#

server/app_backend.ts view source

(api: AdminRpcApi): AdminRpcAdapters

Build the four admin RPC adapters from a typed throwing RPC client.
Method-name mapping:
| Narrow RPC method                   | Action spec method           |
| ----------------------------------- | ---------------------------- |
| admin_accounts.list_accounts      | admin_account_list         |
| admin_accounts.list_sessions      | admin_session_list         |
| admin_accounts.grant_permit       | permit_offer_create        |
| admin_accounts.revoke_permit      | permit_revoke              |
| admin_accounts.retract_offer      | permit_offer_retract       |
| admin_accounts.session_revoke_all | admin_session_revoke_all   |
| admin_accounts.token_revoke_all   | admin_token_revoke_all     |
| admin_invites.list                | invite_list                |
| admin_invites.create              | invite_create              |
| admin_invites.delete              | invite_delete              |
| audit_log.list                    | audit_log_list             |
| audit_log.permit_history          | audit_log_permit_history   |
| app_settings.get                  | app_settings_get           |
| app_settings.update               | app_settings_update        |
All four adapter factories call through the same api — consumers
pass the typed throwing Proxy from create_frontend_rpc_client once,
regardless of how many admin surfaces they mount.

`api`

type AdminRpcApi

returns

AdminRpcAdapters

create_app_backend
#

(options: CreateAppBackendOptions): Promise<AppBackend>

Initialize the backend: database + auth migrations + deps.
Calls create_db → run_migrations (auth namespace, then any
migration_namespaces from options in order) and bundles the result
with the provided keyring and password deps.

`options`

keyring, password deps, optional database URL, and optional migration_namespaces

type CreateAppBackendOptions

returns

Promise<AppBackend>

app backend with deps, database metadata, and combined migration results

throws

Error - if `migration_namespaces` contains the reserved `'fuz_auth'` namespace

create_app_server
#

(options: AppServerOptions): Promise<AppServer>

Create a fully assembled Hono app with auth, middleware, and routes.
Handles the assembly lifecycle: proxy middleware → auth middleware →
bootstrap status → route specs → surface generation → Hono app assembly →
static serving. Database migrations belong to the backend lifecycle —
pass migration_namespaces to create_app_backend.
When audit_log_sse is set, shallow-copies backend.deps with a composed
on_audit_event that fans out to the SSE registry and the original
callback — backend.deps itself is not mutated.

`options`

type AppServerOptions

returns

Promise<AppServer>

assembled Hono app, backend, surface build, and bootstrap status

create_app_surface_spec
#

(options: GenerateAppSurfaceOptions): AppSurfaceSpec

Create an AppSurfaceSpec — the surface bundled with its source specs.

`options`

type GenerateAppSurfaceOptions

returns

AppSurfaceSpec

create_audit_log_config
#

auth/audit_log_routes.ts view source

(options?: CreateAuditLogConfigOptions | undefined): AuditLogConfig

Build an AuditLogConfig by merging fuz_app builtins with consumer extras.
Throws when an extra_events key collides with a builtin event type, or
fails AuditEventTypeName format validation.
Call once at startup; pass the result to consumer-emitted
audit_log_fire_and_forget calls. Builtin handlers omit the argument and
pick up BUILTIN_AUDIT_LOG_CONFIG.

`options?`

type CreateAuditLogConfigOptions | undefined

optional

returns

AuditLogConfig

throws

Error - when an `extra_events` key collides with a builtin event type or fails `AuditEventTypeName` format validation

create_audit_log_route_specs
#

(options?: AuditLogRouteOptions | undefined): RouteSpec[]

Create the optional audit-log SSE route spec.
Returns an empty array when options.stream is not set — no REST routes
live here apart from the stream.

`options?`

optional stream wiring + role override

type AuditLogRouteOptions | undefined

optional

returns

RouteSpec[]

the SSE route spec (when options.stream is provided) or an empty array

create_audit_log_sse
#

auth/middleware.ts view source

(options: { role?: string | undefined; log: Logger; max_per_scope?: number | null | undefined; }): AuditLogSse

Create a complete audit log SSE setup with broadcasting and auth guard.
Combines SubscriberRegistry, create_sse_auth_guard, and the broadcast
call into a single object. The result satisfies AuditLogRouteOptions['stream']
and provides the on_audit_event callback for CreateAppBackendOptions.

`options`

factory options

type { role?: string | undefined; log: Logger; max_per_scope?: number | null | undefined; }

returns

AuditLogSse

audit log SSE setup (stream options + on_audit_event + registry)

examples

const audit_sse = create_audit_log_sse({log});

// In create_app_backend options:
on_audit_event: audit_sse.on_audit_event,

// In create_route_specs:
create_audit_log_route_specs({stream: audit_sse});

// In create_app_server options:
event_specs: AUDIT_LOG_EVENT_SPECS,

create_auth_middleware_specs
#

(deps: AppDeps, options: AuthMiddlewareOptions): Promise<MiddlewareSpec[]>

Create the auth middleware stack.
Returns [origin, session, request_context, bearer_auth] middleware specs
for the given path pattern. When daemon_token_state is provided, appends
a 5th daemon_token layer. Apps can append extra entries for non-standard
paths (e.g., tx's /tx binary endpoint).

`deps`

stateless capabilities (keyring, db)

type AppDeps

`options`

middleware configuration (allowed_origins, session_options, path, daemon_token_state)

type AuthMiddlewareOptions

returns

Promise<MiddlewareSpec[]>

the middleware spec array

create_auth_test_apps
#

(route_specs: RouteSpec[], roles: string[]): AuthTestApps

Create one Hono test app per auth level.

`route_specs`

the route specs to register

type RouteSpec[]

`roles`

all roles in the app

type string[]

returns

AuthTestApps

create_banner
#

auth/bearer_auth.ts view source

(origin_path: string): string

"DO NOT EDIT" banner naming the gen producer.

`origin_path`

type string

returns

string

create_bearer_auth_middleware
#

(deps: QueryDeps, ip_rate_limiter: RateLimiter | null, log: Logger): MiddlewareHandler

Create middleware that authenticates via bearer token.
Soft-fails for invalid, expired, or empty tokens — calls next() without
setting a request context, letting downstream auth enforcement (per-action
check_action_auth or require_auth) return a consistent JSON-RPC or
route-level error. This avoids leaking token-specific diagnostics
(invalid_token, account_not_found) that could aid enumeration attacks,
and ensures public actions are not blocked by bad credentials.
Rejects bearer tokens when an Origin or Referer header is present —
browsers must use cookie auth to reduce attack surface.
Auth scheme matching is case-insensitive per RFC 7235.
On success, builds the request context ({ account, actor, permits })
and sets it on the Hono context. Skips if a request context is already set
(e.g. by session middleware).
Rate limiting (429) is the only hard-fail — it's a throttling concern
independent of auth identity.

`deps`

query dependencies (pool-level db for middleware)

type QueryDeps

`ip_rate_limiter`

per-IP rate limiter for bearer token attempts (null to disable)

type RateLimiter | null

`log`

the logger instance

type Logger

returns

MiddlewareHandler

create_bearer_auth_mocks
#

(tc: BearerAuthTestOptions): BearerAuthMocks

Create mock dependencies for create_bearer_auth_middleware, configured per test case.
Configures the module-level mocks for query_validate_api_token,
query_account_by_id, query_actor_by_account, and query_permit_find_active_for_actor
so each test case controls return values independently.

`tc`

type BearerAuthTestOptions

returns

BearerAuthMocks

mocks bundle with spy references

create_bearer_auth_test_app
#

(tc: BearerAuthTestOptions, ip_rate_limiter?: RateLimiter | null): { app: Hono<BlankEnv, BlankSchema, "/">; mocks: BearerAuthMocks; }

Create a Hono app wired with create_bearer_auth_middleware using mocked deps.
The route handler at /api/test returns the resolved context in the response body,
enabling assertions on REQUEST_CONTEXT_KEY and CREDENTIAL_TYPE_KEY.

`tc`

type BearerAuthTestOptions

`ip_rate_limiter`

type RateLimiter | null

default null

returns

{ app: Hono<BlankEnv, BlankSchema, "/">; mocks: BearerAuthMocks; }

create_bootstrap_route_specs
#

(deps: RouteFactoryDeps, options: BootstrapRouteOptions): RouteSpec[]

Create bootstrap route specs for first-time account creation.

`deps`

stateless capabilities including filesystem access

type RouteFactoryDeps

`options`

per-factory configuration (session, token path, bootstrap status)

type BootstrapRouteOptions

returns

RouteSpec[]

route specs (not yet applied to Hono)

create_broadcast_api
#

cli/logger.ts view source

<TApi extends object>(options: CreateBroadcastApiOptions): TApi

Builds a typed broadcast API from a set of action specs.
For each spec, adds a method keyed by spec.method that:
- Validates input against the spec's Zod schema (logs and returns on failure)
- Creates a JSON-RPC notification from the validated input
- Broadcasts via the peer (filtered by should_deliver when supplied)
Silently returns when no transport is ready (e.g. before any clients
connect). Errors during send are logged but never thrown — broadcasts are
fire-and-forget from the handler's perspective.
Typed consumer surfaceConsumers declare an explicit interface and pin it via the type parameter:
export interface BackendActionsApi {
  filer_change: (input: ActionInputs['filer_change']) => Promise<void>;
  workspace_changed: (input: ActionInputs['workspace_changed']) => Promise<void>;
}

const api = create_broadcast_api<BackendActionsApi>({
  peer: backend.peer,
  specs: [filer_change_action_spec, workspace_changed_action_spec],
});The cast is unchecked — callers must keep the interface and the specs
array in sync. Codegen (action_collections.gen.ts) is a natural fit
if the consumer already generates per-method type maps.

`options`

type CreateBroadcastApiOptions

returns

TApi

create_cli_logger
#

(logger: Logger): CliLogger

Creates a CLI logger wrapping a Logger with semantic output methods.

`logger`

the Logger instance to wrap

type Logger

returns

CliLogger

a CliLogger with CLI semantic methods mapped to Logger levels

create_daemon_token_middleware
#

(state: DaemonTokenState, deps: QueryDeps): MiddlewareHandler

Create middleware that authenticates via daemon token.
Checks the X-Daemon-Token header. Behavior:
- No header: pass through (don't touch existing context)
- Header present + valid: build RequestContext from keeper account,
  set credential_type: 'daemon_token' (overrides any existing session/bearer context)
- Header present + invalid: return 401 (fail-closed, no downgrade)
- Header present + valid but keeper_account_id is null: return 503

`state`

the daemon token runtime state

type DaemonTokenState

`deps`

query dependencies (pool-level db for middleware)

type QueryDeps

returns

MiddlewareHandler

create_database
#

db/create_db.ts view source

(deps: CommandDeps, db_name: string, options?: CreateDatabaseOptions | undefined): Promise<CommandResult>

Create a PostgreSQL database if createdb is available.
Does not throw — returns the underlying command result so callers can
decide how to react to a missing createdb or an "already exists" failure.

`deps`

command execution capability

type CommandDeps

`db_name`

database name to create

type string

`options?`

logger

type CreateDatabaseOptions | undefined

optional

returns

Promise<CommandResult>

the command result

create_db
#

(database_url: string): Promise<CreateDbResult>

Create a database connection based on a URL.
The close callback is bound to the actual driver — callers never need to
know which driver is in use.
For direct driver construction without URL routing, import
create_pg_db from db/db_pg.ts or create_pglite_db from db/db_pglite.ts.

`database_url`

connection URL (postgres://, postgresql://, file://, or memory://)

type string

returns

Promise<CreateDbResult>

database instance, close callback, type, and display name

throws

Error - if `database_url` uses an unsupported scheme. Driver

create_db_route_specs
#

runtime/deno.ts view source

(options: DbRouteOptions): RouteSpec[]

Create the db API route specs.

`options`

type DbRouteOptions

returns

RouteSpec[]

create_deno_runtime
#

(args: readonly string[]): RuntimeDeps

Create a runtime backed by Deno APIs.
Returns an object satisfying all *Deps interfaces from runtime/deps.ts.
Pass to shared functions that accept EnvDeps, FsReadDeps, etc.

`args`

CLI arguments (typically Deno.args)

type readonly string[]

returns

RuntimeDeps

runtime implementation using Deno APIs

create_describe_db
#

(factories: DbFactory | DbFactory[], truncate_tables: string[]): (name: string, fn: (get_db: () => Db) => void) => void

Create a describe_db function bound to specific factories and truncate tables.
Returns a 2-arg (name, fn) function that runs the test suite against each
factory. Each factory gets its own describe block with a shared database
instance, automatic beforeEach truncation, and afterAll cleanup.
Skipped factories use describe.skip.

`factories`

one or more database factories to run suites against

type DbFactory | DbFactory[]

`truncate_tables`

tables to truncate between tests (children first for FK safety)

type string[]

returns

(name: string, fn: (get_db: () => Db) => void) => void

create_expired_test_cookie
#

(keyring: Keyring, session_options: SessionOptions<string>): Promise<string>

Create an expired test cookie — validly signed but with an expiry timestamp in 1970.

`keyring`

type Keyring

`session_options`

type SessionOptions<string>

returns

Promise<string>

create_extract_global_flags
#

cli/args.ts view source

<T extends Record<string, unknown>>(schema: ZodType<T, unknown, $ZodTypeInternals<T, unknown>>, fallback: T): (unparsed: ParsedArgs) => { flags: T; remaining: ParsedArgs; }

Create a project-specific global flag extractor.
Returns a function that separates global flags from command-specific args.
The schema defines which flags are global (with aliases via .meta({aliases})),
and the fallback provides defaults when parsing fails.

`schema`

Zod schema for global flags

type ZodType<T, unknown, $ZodTypeInternals<T, unknown>>

`fallback`

default values when parsing fails

type T

returns

(unparsed: ParsedArgs) => { flags: T; remaining: ParsedArgs; }

extractor function (unparsed) => {flags, remaining}

create_fake_hono_context
#

(opts: FakeHonoContextOptions): Context<any, any, {}>

Build a fake Hono Context exposing the auth keys the dispatcher
reads via c.get(...). Only .get() is populated — no other Hono
context surface is simulated.

`opts`

type FakeHonoContextOptions

returns

Context<any, any, {}>

create_fake_ws
#

actions/frontend_rpc_client.ts view source

(): FakeWs

Build a real WSContext backed by in-memory send/close capture.
Parsing of outgoing frames is left to the caller — sends holds the
raw strings as the dispatcher wrote them.

returns

FakeWs

create_frontend_rpc_client
#

<TApi extends object>(options: CreateFrontendRpcClientOptions<TApi>): FrontendRpcClient<TApi>

Build a frontend-only typed RPC client. See module doc for the bundle's design.

`options`

type CreateFrontendRpcClientOptions<TApi>

returns

FrontendRpcClient<TApi>

create_health_route_spec
#

(): RouteSpec

Create a public health check route spec.
Infrastructure endpoint for uptime monitors and load balancers.
Bootstrap availability is exposed via /api/account/status instead.

returns

RouteSpec

create_help
#

<TCategory extends string>(options: HelpOptions<TCategory>): HelpGenerator

Create a help generator configured for an application.

`options`

help configuration

type HelpOptions<TCategory>

returns

HelpGenerator

help generator with generate_main_help, generate_command_help, and get_help_text

create_initial_data
#

(kind: "request_response" | "remote_notification" | "local_call", phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", method: string, executor: "frontend" | "backend", input: unknown): { ...; }

`kind`

type "request_response" | "remote_notification" | "local_call"

`phase`

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"

`method`

type string

`executor`

type "frontend" | "backend"

`input`

type unknown

returns

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

create_jsonrpc_error_response
#

(id: string | number | null, error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }): { ...; }

Creates a JSON-RPC error response message.

`id`

type string | number | null

`error`

type

{ [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }

returns

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }

create_jsonrpc_error_response_from_thrown
#

(id: string | number | null, error: unknown): { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }

Creates a JSON-RPC error response from any error.
Handles ThrownJsonrpcError (preserves code/message/data) and
regular Error objects (maps to internal_error, includes stack in DEV).

`id`

type string | number | null

`error`

type unknown

returns

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }

create_jsonrpc_notification
#

(method: string, params: { [x: string]: unknown; } | undefined): { [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

Creates a JSON-RPC notification message (no id, no response expected).

`method`

type string

`params`

type { [x: string]: unknown; } | undefined

returns

{ [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

create_jsonrpc_request
#

(method: string, params: { [x: string]: unknown; } | undefined, id: string | number): { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

Creates a JSON-RPC request message.

`method`

type string

`params`

type { [x: string]: unknown; } | undefined

`id`

type string | number

returns

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

create_jsonrpc_response
#

(id: string | number, result: { [x: string]: unknown; }): { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; }

Creates a JSON-RPC success response message.

`id`

type string | number

`result`

type { [x: string]: unknown; }

returns

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; }

create_keyring
#

testing/mock_fs.ts view source

(env_value: string | undefined): Keyring | null

Create a keyring from environment variable.
Keys are separated by __ for rotation support. First key is used
for signing, all keys are tried for verification.
CryptoKeys are cached on first use for performance.
Security: key rotation is an operational concern. Old keys remain valid
for verification indefinitely — a leaked old key can forge session cookies
until it is removed from SECRET_COOKIE_KEYS. After rotating to a new
signing key, remove the old key within a grace period (e.g. 24–48 hours,
long enough for active sessions to re-sign with the new key via cookie
refresh). Treat SECRET_COOKIE_KEYS changes as security-critical deploys.

`env_value`

the SECRET_COOKIE_KEYS environment variable

type string | undefined

returns

Keyring | null

keyring or null if no keys configured

create_mock_fs
#

(initial_files?: Record<string, string>): MockFs

Creates an in-memory file system for tests.
read_file throws an ENOENT-tagged error for missing paths so callers
can exercise the same "file doesn't exist" code path as node:fs.

`initial_files`

type Record<string, string>

default {}

returns

MockFs

create_mock_runtime
#

(args?: string[]): MockRuntime

Create a mock RuntimeDeps for testing.
The mock exit records the code on exit_calls and throws MockExitError
(so the never-returning contract holds in tests). fetch throws TypeError
when no mock_fetch_responses pattern matches the request URL.

`args`

type string[]

default []

returns

MockRuntime

MockRuntime with controllable state

examples

const runtime = create_mock_runtime(['apply', 'tx.ts']);
runtime.mock_env.set('HOME', '/home/test');
runtime.mock_fs.set('/home/test/.app/config.json', '{}');

await some_function(runtime);

assert.strictEqual(runtime.command_calls.length, 1);
assert.deepStrictEqual(runtime.exit_calls, [0]);

create_namespace_qualifier
#

runtime/node.ts view source

(sources: readonly SpecSource[], imports: ImportBuilder): { qualify_spec: (spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; ... 8 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }) => string; all_specs: readonly ({ ...; } | ... 1 more ... | { ...; })[]; }

Multi-source consumer helper. Takes a list of {ns, module, specs} rows,
registers import * as ns from module for each on imports, builds the
method_to_ns lookup with duplicate-method detection, and returns
{qualify_spec, all_specs} ready to thread through the high-level
helpers.
Closes the per-file boilerplate gap that kept tx + visiones on hand-rolled
template strings even after qualify_spec? landed in API review II — the
per-call callback wasn't enough; the import dance + dup-check was the
real boilerplate.

`sources`

type readonly SpecSource[]

`imports`

type ImportBuilder

returns

{ qualify_spec: (spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<...>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }) => string; all_specs: rea...

throws

Error - if two sources contain the same method name (same-method

examples

const sources = [
  {ns: 'tx_specs', module: './action_specs.js', specs: all_tx_action_specs},
  {ns: 'admin_specs', module: '@fuzdev/fuz_app/auth/admin_action_specs.js', specs: all_admin_action_specs},
];

export const gen: Gen = ({origin_path}) => {
  const imports = new ImportBuilder();
  const {qualify_spec, all_specs} = create_namespace_qualifier(sources, imports);
  return compose_gen_file({
    origin_path,
    imports,
    blocks: [
      generate_action_specs_record(all_specs, imports, {qualify_spec}),
      generate_action_inputs_outputs(all_specs, imports, {qualify_spec}),
    ],
  });
};

create_node_runtime
#

(args?: readonly string[]): RuntimeDeps

Create a RuntimeDeps backed by Node.js APIs.

`args`

CLI arguments (typically process.argv.slice(2))

type readonly string[]

default process.argv.slice(2)

returns

RuntimeDeps

RuntimeDeps implementation using Node.js runtime

create_noop_stub
#

<T = any>(_label: string, overrides?: Record<string, unknown> | undefined): T

Create a Proxy where every method access returns a no-op async function.
Use for deps that may be reached during "correct auth passes guard" tests
but whose return values don't matter. Unlike the explicit method listing,
this auto-updates when interfaces change.

`_label`

type string

`overrides?`

explicit properties to set (e.g. {db: stub_db})

type Record<string, unknown> | undefined

optional

returns

T

create_permit_offer_actions
#

(deps: PermitOfferActionDeps, options?: PermitOfferActionOptions): RpcAction[]

Create the seven permit-offer RPC actions (six offer-lifecycle methods
plus permit_revoke).

`deps`

PermitOfferActionDeps — log, on_audit_event, optional audit_log_config (slice of AppDeps); optional notification_sender for WS fan-out

type PermitOfferActionDeps

`options`

role schema, default TTL, authorization override

type PermitOfferActionOptions

default {}

returns

RpcAction[]

the RpcAction array to spread into a create_rpc_endpoint call

create_pg_db
#

db/db_pg.ts view source

(pool: Pool): DbDriverResult

Create a Db backed by a pg.Pool.
Owns the transaction implementation, acquiring a dedicated pool client
per transaction.

`pool`

an already-constructed pg.Pool

type Pool

returns

DbDriverResult

the Db instance and a close callback bound to pool.end()

create_pg_factory
#

db/db_pglite.ts view source

(init_schema: (db: Db) => Promise<void>, test_url?: string | undefined): DbFactory

Create a pg (PostgreSQL) database factory for tests.
Skipped when test_url is not provided.
Drops schema_version before running init_schema, forcing migrations
to re-evaluate against the actual tables. Prevents stale tracker rows
from skipping migrations when DDL changes between test sessions.
For full clean-slate behavior (recommended), call drop_auth_schema(db)
at the start of init_schema before running migrations. This handles
upstream schema changes that go beyond adding new tables/columns.

`init_schema`

callback to initialize the database schema

type (db: Db) => Promise<void>

`test_url?`

PostgreSQL connection URL (e.g. from TEST_DATABASE_URL)

type string | undefined

optional

returns

DbFactory

a factory that creates pg databases. The returned create()
throws when test_url is unset (despite the skip: true flag — defense
against direct invocation), and rewrites Postgres "database does not
exist" errors into a createdb hint message.

create_pglite_db
#

(pglite: PGlite): DbDriverResult

Create a Db backed by a PGlite instance.
Delegates transactions to PGlite's native transaction() method.

`pglite`

an already-constructed PGlite instance

type PGlite

returns

DbDriverResult

the Db instance and a close callback bound to pglite.close()

create_pglite_factory
#

(init_schema: (db: Db) => Promise<void>): DbFactory

Create a pglite (in-memory) database factory for tests.
Always enabled — no external dependencies required.
Shares a single PGlite WASM instance across all factories in the same
vitest worker thread (one test file). Subsequent create() calls reset
the schema via DROP SCHEMA public CASCADE instead of paying the WASM
cold-start cost again.

`init_schema`

callback to initialize the database schema

type (db: Db) => Promise<void>

returns

DbFactory

create_proxy_middleware
#

(options: ProxyOptions): MiddlewareHandler

Create a Hono middleware that resolves the client IP from trusted proxies.
Sets client_ip on the Hono context for downstream use by get_client_ip.
All client IPs are normalized (lowercase, IPv4-mapped IPv6 stripped).
Resolution logic:
1. No X-Forwarded-For → use connection IP directly.
2. X-Forwarded-For present but connection is untrusted → ignore header
   (spoofed by a direct attacker), use connection IP.
3. X-Forwarded-For present and connection is trusted → walk header
   right-to-left, strip trusted entries, use first untrusted entry.

`options`

trusted proxy configuration

type ProxyOptions

returns

MiddlewareHandler

throws

Error - if any entry in `options.trusted_proxies` is invalid (parsed eagerly via `parse_proxy_entry`)

create_proxy_middleware_spec
#

(options: ProxyOptions): MiddlewareSpec

Create a middleware spec for trusted proxy resolution.
Apply before auth middleware so client_ip is available for rate limiting.

`options`

trusted proxy configuration

type ProxyOptions

returns

MiddlewareSpec

create_rate_limiter
#

(options?: Partial<RateLimiterOptions> | undefined): RateLimiter

Create a RateLimiter with sensible defaults for per-IP login protection.

`options?`

override individual options; unset fields use DEFAULT_LOGIN_IP_RATE_LIMIT

type Partial<RateLimiterOptions> | undefined

optional

returns

RateLimiter

create_request_context_middleware
#

(deps: QueryDeps, log: Logger, session_context_key?: string): MiddlewareHandler

Create middleware that builds the request context from a session cookie.
Reads the session identity (set by session middleware), looks up
the auth_session, loads account + actor + active permits, and
sets the RequestContext on the Hono context.
If the session is invalid or the account is not found, the context
is set to null (unauthenticated). No 401 is returned — use
require_role or require_auth for enforcement.

`deps`

query dependencies (pool-level db for middleware)

type QueryDeps

`log`

the logger instance

type Logger

`session_context_key`

the Hono context key where session middleware stored the session token

type string

default 'auth_session_id'

returns

MiddlewareHandler

create_role_schema
#

<T extends string>(app_roles: Record<T, RoleOptions>): RoleSchemaResult

Create a role schema and config map that extends the builtins with app-defined roles.
Call once at server init. The returned Role schema validates role strings
at I/O boundaries (grant endpoint, permit queries). The role_options map
is used by middleware to check requires_daemon_token and by admin UI to
filter web_grantable roles.

`app_roles`

app-defined roles with optional config overrides

type Record<T, RoleOptions>

returns

RoleSchemaResult

{Role, role_options} — Zod schema and full config map

throws

Error - if any `app_roles` key fails the `RoleName` regex or collides with a builtin role

examples

// visiones
const {Role, role_options} = create_role_schema({
  teacher: {},
});
// Role validates 'keeper' | 'admin' | 'teacher'
// role_options has all 3 entries with defaults applied

create_rpc_client
#

<TApi extends object>(options: CreateRpcClientOptions<TApi>): TApi

Creates a Proxy-based API from action specs.
Method calls are dynamically dispatched based on the action spec's kind:
- request_response → send request, await response, return Result
- remote_notification → send notification, return Result
- local_call → execute locally (sync or async), return Result or throw
Generic TApi is the consumer's typed Proxy interface (typically a
codegen-derived ActionsApi). Required — no default, so forgetting it
is a type error rather than a silent slide into any. The `as unknown
as TApi` coercion lives inside this function so call sites get a typed
return without a cast at the seam. TApi is a type-layer promise about
what the Proxy responds to; the runtime walks specs (kept in sync by
the consumer, codegen recommended).
const api_result = create_rpc_client<MyActionsApi>({peer, environment});

`options`

type CreateRpcClientOptions<TApi>

returns

TApi

a Proxy typed as TApi that responds to any method name found in the environment's specs

create_rpc_endpoint
#

(options: CreateRpcEndpointOptions): RouteSpec[]

Single JSON-RPC 2.0 endpoint — the canonical RPC transport binding.
Returns two RouteSpec entries (GET + POST on the same path) for
apply_route_specs. The internal dispatcher handles:
1. Parse envelope — POST: JSON body as JsonrpcRequest. GET: method
   and params from query string.
2. Lookup method — find the RpcAction by method name.
3. Auth check — verify identity against the action's auth requirement.
4. Validate params — parse input against the action's input schema.
5. Dispatch — acquire DB handle (transaction for mutations, pool for reads),
   construct ActionContext, call handler, return JSON-RPC response.
GET is restricted to side_effects: false actions (cacheable reads).
All errors use JSON-RPC format: {jsonrpc, id, error: {code, message, data?}}.
The RouteSpecs use auth: {type: 'none'} because auth is checked per-action
inside the dispatcher, and transaction: false because transaction scope
is per-action (mutations get a transaction, reads get pool).

`options`

endpoint path, actions, and logger

type CreateRpcEndpointOptions

returns

RouteSpec[]

route specs (GET + POST) ready for apply_route_specs

throws

Error - if two actions share the same `spec.method` (registration-time

create_rpc_get_url
#

(endpoint_path: string, method: string, params?: unknown, id?: string | number): string

Build a GET URL with JSON-RPC query parameters.

`endpoint_path`

the RPC endpoint path (e.g., /api/rpc)

type string

`method`

type string

`params?`

params (omit for parameterless methods)

type unknown

optional

`id`

request id (default 'test')

type string | number

default 'test'

returns

string

create_rpc_post_init
#

auth/self_service_role_actions.ts view source

(method: string, params?: unknown, id?: string | number): RequestInit

Create a RequestInit for a JSON-RPC POST request.

`method`

type string

`params?`

params (omit for parameterless methods; null is also
 stripped for ergonomic call sites — JSON-RPC 2.0 §4.2
 forbids "params": null on the wire, and create_rpc_endpoint
 rejects z.null() action input schemas at registration).
 Tests that need to construct a literal "params": null
 envelope (e.g. asserting envelope-level rejection) should
 build the body inline rather than route through this helper.

type unknown

optional

`id`

request id (default 'test')

type string | number

default 'test'

returns

RequestInit

create_self_service_role_actions
#

(deps: SelfServiceRoleActionDeps, options: SelfServiceRoleActionsOptions): RpcAction[]

Build the unified self-service role toggle RPC action.

`deps`

SelfServiceRoleActionDeps slice of AppDeps (log, on_audit_event, optional audit_log_config)

type SelfServiceRoleActionDeps

`options`

eligible-role allowlist plus optional role schema for typo-checking

type SelfServiceRoleActionsOptions

returns

RpcAction[]

the RpcAction array to spread into a create_rpc_endpoint call

throws

Error - at factory time if any `eligible_roles` entry is missing from `options.roles.role_options`

create_server_status_route_spec
#

auth/session_lifecycle.ts view source

(options: ServerStatusOptions): RouteSpec

Create an authenticated server status route spec.
Returns version and uptime. Unlike the public health check,
this requires authentication.

`options`

type ServerStatusOptions

returns

RouteSpec

create_session_and_set_cookie
#

(options: CreateSessionAndSetCookieOptions): Promise<void>

Create an auth session and set the session cookie on the response.
Shared by login and bootstrap — generates a token, hashes it, persists
the session row, optionally enforces a per-account session limit, and
sets the signed cookie.

`options`

type CreateSessionAndSetCookieOptions

returns

Promise<void>

create_session_config
#

(cookie_name: string): SessionOptions<string>

Create a session config for raw session token identity.
The standard pattern: cookie stores the raw session token,
server hashes it (blake3) to look up the auth_session row.
Only the cookie_name varies per app.

`cookie_name`

cookie name (e.g. 'tx_session', 'visiones_session')

type string

returns

SessionOptions<string>

a SessionOptions<string> ready for use with session middleware

create_session_cookie_value
#

<TIdentity>(keyring: Keyring, identity: TIdentity, options: SessionOptions<TIdentity>, now_seconds?: number | undefined): Promise<string>

Create a signed session cookie value.
Format: ${encode(identity)}:${expires_at} signed with HMAC-SHA256.
Embeds expiration in the signed value itself for defense-in-depth.

`keyring`

key ring for signing

type Keyring

`identity`

the identity to encode

type TIdentity

`options`

session configuration with encode logic

type SessionOptions<TIdentity>

`now_seconds?`

current time in seconds (for testing)

type number | undefined

optional

returns

Promise<string>

signed cookie value string

create_session_middleware
#

<TIdentity>(keyring: Keyring, options: SessionOptions<TIdentity>): MiddlewareHandler

Create session middleware that parses cookies and sets identity on context.
Always sets the identity on context (null when invalid/missing) for type-safe reads.
Uses options.context_key as the Hono context variable name.

`keyring`

key ring for cookie verification

type Keyring

`options`

session configuration

type SessionOptions<TIdentity>

returns

MiddlewareHandler

create_signup_route_specs
#

(deps: RouteFactoryDeps, options: SignupRouteOptions): RouteSpec[]

Create signup route specs for account creation.

`deps`

stateless capabilities

type RouteFactoryDeps

`options`

per-factory configuration

type SignupRouteOptions

returns

RouteSpec[]

route specs (not yet applied to Hono)

create_sse_auth_guard
#

<T>(registry: SubscriberRegistry<T>, required_role: string | null, log: Logger): (event: AuditLogEvent) => void

Create an audit event handler that closes SSE streams on auth changes.
Closes streams when:
- permit_revoke fires for the required_role targeting a connected subscriber
- session_revoke_all targets a connected subscriber (consistent invalidation)
- password_change targets a connected subscriber (sessions revoked implicitly)
The registry must use account_id as the identity key when subscribing
(passed as the third argument to registry.subscribe()).

`registry`

the subscriber registry to guard

type SubscriberRegistry<T>

`required_role`

the role that grants access to the SSE endpoint,
or null to skip permit_revoke handling entirely (for streams not gated
by a specific permit)

type string | null

`log`

logger for disconnect events

type Logger

returns

(event: AuditLogEvent) => void

an on_audit_event callback

create_sse_response
#

testing/adversarial_headers.ts view source

<T = unknown>(c: Context<any, any, {}>, log: Logger): { response: Response; stream: SseStream<T>; }

Create an SSE response for a Hono context.
Wraps Hono's streamSSE to provide a {response, stream} API
compatible with SubscriberRegistry push-based broadcasting.
The callback suspends via a promise that resolves on client disconnect
or explicit close(), keeping the stream alive for external sends.
Uses hono_stream.write() directly (not writeSSE) to avoid
Hono's HTML callback resolution — keeps the same data: JSON\n\n format.

`c`

type Context<any, any, {}>

`log`

logger for serialization and on_close listener errors

type Logger

returns

{ response: Response; stream: SseStream<T>; }

object with the streaming Response and an SseStream controller

create_standard_adversarial_cases
#

(allowed_origin: string): AdversarialHeaderCase[]

7 standard adversarial header cases applicable to any middleware stack.

`allowed_origin`

an origin that passes the origin check

type string

returns

AdversarialHeaderCase[]

create_standard_rpc_actions
#

auth/standard_rpc_actions.ts view source

(deps: PermitOfferActionDeps, options?: StandardRpcActionsOptions): RpcAction[]

Build the combined admin + permit-offer + account RPC action set.
Spreads create_admin_actions(deps, {roles, app_settings}),
create_permit_offer_actions(deps, {roles, default_ttl_ms, authorize}),
and create_account_actions(deps, {max_tokens}). The shared roles
option flows to admin + permit-offer.

`deps`

StandardRpcActionsDeps (log, on_audit_event, optional audit_log_config from AppDeps; optional notification_sender for WS fan-out)

type PermitOfferActionDeps

`options`

role schema, optional app-settings ref, permit-offer config, account config

type StandardRpcActionsOptions

default {}

returns

RpcAction[]

RPC actions to pass as rpc_endpoints or spread into create_rpc_endpoint

create_static_middleware
#

server/static.ts view source

(serve_static: ServeStaticFactory, options?: { root?: string | undefined; spa_fallback?: string | undefined; is_spa_route?: ((path: string) => boolean) | undefined; } | undefined): MiddlewareHandler[]

Create static file serving middleware for SvelteKit static builds.
Returns an array of middleware handlers to register on '/*'.

`serve_static`

runtime-specific serveStatic factory

type ServeStaticFactory

`options?`

optional root directory and SPA fallback path

type

{ root?: string | undefined; spa_fallback?: string | undefined; is_spa_route?: ((path: string) => boolean) | undefined; } | undefined

optional

returns

MiddlewareHandler[]

create_stub_api_middleware
#

(options?: { include_daemon_token?: boolean | undefined; } | undefined): MiddlewareSpec[]

Create the API middleware stub array matching create_auth_middleware_specs output.

`options?`

type { include_daemon_token?: boolean | undefined; } | undefined

optional

returns

MiddlewareSpec[]

create_stub_app_deps
#

(): AppDeps

Create no-op AppDeps for auth surface testing.

returns

AppDeps

create_stub_app_server_context
#

(session_options: SessionOptions<string>): AppServerContext

Create a stub AppServerContext for attack surface testing.
Provides sensible defaults for all fields. Pass session_options since
it varies per consumer; other fields use stubs/nulls.

`session_options`

consumer's session config (required — varies per app)

type SessionOptions<string>

returns

AppServerContext

create_stub_db
#

(): Db

Create a stub Db for handler tests that use apply_route_specs with declarative transactions.
Returns a real Db instance with:
- query returns empty rows (safety net for unmocked query functions)
- query_one returns undefined
- transaction(fn) calls fn(db) synchronously (no real transaction)

returns

Db

create_stub_upgrade
#

(): StubUpgrade

Build a fake upgradeWebSocket that captures the createEvents
callback. The returned middleware is inert — tests drive
createEvents directly.

returns

StubUpgrade

create_surface_route_spec
#

(options: SurfaceRouteOptions): RouteSpec

Create an authenticated route spec that serves the AppSurface as JSON.
Surface data reveals API structure (routes, auth, schemas), so this
requires authentication like the server status route.

`options`

type SurfaceRouteOptions

returns

RouteSpec

create_test_account
#

(overrides?: TestAccountOverrides | undefined): Account

Create a test Account with sensible defaults.

`overrides?`

type TestAccountOverrides | undefined

optional

returns

Account

create_test_actor
#

(overrides?: TestActorOverrides | undefined): Actor

Create a test Actor with sensible defaults.

`overrides?`

type TestActorOverrides | undefined

optional

returns

Actor

create_test_app
#

(options: CreateTestAppOptions): Promise<TestApp>

Create a fully assembled test app with a Hono server, middleware, and routes.
Combines create_test_app_server + create_app_server into a single call.
Disables rate limiters and logging by default (test-friendly).
A fresh Hono app is created each call — middleware closures bind to the
server's deps (db, keyring), so reuse across servers is unsafe.
The expensive resource (PGlite WASM) is cached separately in test_db.ts.

`options`

test app configuration

type CreateTestAppOptions

returns

Promise<TestApp>

a TestApp ready for HTTP testing

create_test_app_from_specs
#

(route_specs: RouteSpec[], auth_ctx?: RequestContext | undefined, credential_type?: "session" | "api_token" | "daemon_token" | undefined): Hono<BlankEnv, BlankSchema, "/">

Create a Hono test app from route specs with optional auth context.

`route_specs`

the route specs to register

type RouteSpec[]

`auth_ctx?`

optional request context to inject via middleware

type RequestContext | undefined

optional

`credential_type?`

optional credential type (default: 'session' when auth_ctx provided)

type "session" | "api_token" | "daemon_token" | undefined

optional

returns

Hono<BlankEnv, BlankSchema, "/">

create_test_app_server
#

(options: TestAppServerOptions): Promise<TestAppServer>

Create an app server with a bootstrapped account for testing.
Sets up:
- Auth tables (via cached PGlite factory, or reuses existing db)
- A keeper account with hashed password
- Role permits for each role in options.roles
- An API token for Bearer auth
- A session with a signed cookie value
Uses stub_password_deps by default — deterministic hashing that works
correctly for login/logout tests without Argon2 overhead.

`options`

session options and optional overrides

type TestAppServerOptions

returns

Promise<TestAppServer>

a TestAppServer ready for HTTP testing

create_test_app_surface_spec
#

(options: CreateTestAppSurfaceSpecOptions): AppSurfaceSpec

Create an AppSurfaceSpec for attack surface testing.
Mirrors create_app_server's route assembly: consumer routes +
factory-managed bootstrap routes + surface generation. If
create_app_server changes how it wires routes, update this helper
to stay in sync (single source of truth for all consumers).

`options`

surface spec options

type CreateTestAppSurfaceSpecOptions

returns

AppSurfaceSpec

the surface spec for snapshot and adversarial testing

create_test_audit_event
#

(overrides?: TestAuditEventOverrides | undefined): AuditLogEvent

Create a test AuditLogEvent with sensible defaults.

`overrides?`

type TestAuditEventOverrides | undefined

optional

returns

AuditLogEvent

create_test_context
#

(permits?: TestPermitOverrides[]): RequestContext

Create a test RequestContext with permits from partial overrides.

`permits`

type TestPermitOverrides[]

default [{}]

returns

RequestContext

create_test_middleware_stack_app
#

(options?: TestMiddlewareStackOptions | undefined): TestMiddlewareStackApp

Create a Hono app with real proxy + origin + bearer middleware for integration testing.
All DB queries return undefined (no real database needed).
The echo route at TEST_MIDDLEWARE_PATH returns {ok, client_ip, has_context}.

`options?`

type TestMiddlewareStackOptions | undefined

optional

returns

TestMiddlewareStackApp

the app and mock spies (reconfigure via mockImplementation for valid-token paths)

create_test_permit
#

(overrides?: TestPermitOverrides | undefined): Permit

Create a test Permit with sensible defaults.

`overrides?`

type TestPermitOverrides | undefined

optional

returns

Permit

create_test_request_context
#

(role?: string | undefined): RequestContext

Create a mock RequestContext with optional role permit.

`role?`

type string | undefined

optional

returns

RequestContext

create_throwing_api
#

<TApi extends object>(api_result: TApi): ThrowingApi<TApi>

Wrap a typed RPC client so every call resolves to its unwrapped value or
throws an Error carrying the JSON-RPC {code, message, data?} shape.
Implementation is a Proxy because the underlying create_rpc_client
return is itself a Proxy with no concrete keys — a key-by-key wrap would
need to enumerate the typed surface, which only the consumer's generated
ActionsApi interface knows.
Pass-through on non-Result returns is deliberate: sync local_call
Proxy methods return values directly (see create_sync_local_call_method
above). The Proxy can't distinguish those at get-time, so the wrapper
inspects result shape at call-time and only unwraps when it sees a
Result. Non-object returns pass through unchanged.
Only {code, data} cross onto the thrown Error — name / stack are
left as the Error's own properties so attacker-shaped result.error
payloads cannot overwrite them.
Recommended consumer convention: create_frontend_rpc_client ships
both shapes by default — api (throwing) for hot-path call sites and
api_result (Result) for sites that inspect error.data.reason
without try/catch. Result is the protocol primitive; this wrapper is
the ergonomic layer over it. Picking is per call site — both Proxies
share the same underlying transport.
Catch blocks read err.data?.reason — optional chaining required
because JSON-RPC data is spec-level optional.
On unknown string-keyed methods, the get trap returns a function that
throws "rpc method not found: <prop>" on invocation — clearer than
the JS default "api.foo is not a function". Symbol props and then
stay undefined so the Proxy isn't accidentally treated as a thenable
(await api would otherwise probe then and trip the thrower).

`api_result`

typed Result-returning RPC client from
create_rpc_client<ActionsApi>(...). The "_result" suffix names
what the underlying calls return (Result<{value}, {error}>).

type TApi

returns

ThrowingApi<TApi>

create_throwing_stub
#

<T = any>(label: string): T

Create a Proxy that throws descriptive errors on any property access or method call.
Use for deps that should never be reached during a test. If a test accidentally
calls through to a throwing stub, the error message identifies exactly which stub
was hit, catching test bugs that would silently pass with {} as any.
JS-internal probes (Symbol, then, constructor, $$typeof) return
undefined so the proxy doesn't crash framework-level identity checks;
toJSON returns "[throwing_stub:label]" so accidental serialization
surfaces the stub's identity in console output rather than silent "{}".

`label`

descriptive name for error messages (e.g. 'keyring', 'db')

type string

returns

T

throws

Error - on any non-internal property access, labeled with the stub

create_validated_broadcaster
#

<T extends SseNotification>(broadcaster: { broadcast: (channel: string, data: T) => void; }, event_specs: EventSpec[], log: Logger): { broadcast: (channel: string, data: T) => void; }

Create a broadcaster that validates events in DEV mode.
In DEV: warns on unknown methods and invalid params.
In production: passes through with zero overhead.

`broadcaster`

duck-typed broadcaster (e.g. SubscriberRegistry)

type { broadcast: (channel: string, data: T) => void; }

`event_specs`

event specs to validate against

type EventSpec[]

`log`

logger used to emit DEV warnings on unknown methods or param mismatches

type Logger

returns

{ broadcast: (channel: string, data: T) => void; }

validated broadcaster wrapper (passthrough in production)

create_validated_keyring
#

(env_value: string | undefined): ValidatedKeyringResult

Validate and create a keyring in one step.
Returns a discriminated union so callers handle exit/logging their own way
(e.g. Deno.exit(1) vs runtime.exit(1)).

`env_value`

the SECRET_COOKIE_KEYS environment variable

type string | undefined

returns

ValidatedKeyringResult

{ok: true, keyring} or {ok: false, errors}

create_ws_auth_guard
#

(transport: BackendWebsocketTransport, log: Logger): AuditEventHandler

Create an audit event handler that closes WebSocket connections on auth changes.
Ignores outcome === 'failure' events — they carry attacker-controlled
identifiers (e.g. a session_revoke that the DB rejected still records
the submitted session_id), so reacting to them would let any authenticated
user close another user's socket by guessing a session hash or token id.

`transport`

`log`

logger for disconnect events (info level on non-zero closures)

type Logger

returns

AuditEventHandler

an on_audit_event callback suitable for CreateAppBackendOptions.
The returned callback mutates transport (closing matching sockets via
close_sockets_for_session / _token / _account) on every relevant event.

create_ws_logout_closer
#

(transport: BackendWebsocketTransport, log: Logger): AuditEventHandler

Create an audit event handler that closes WebSocket connections on
user-initiated logout.
Sibling helper to create_ws_auth_guard — kept separate because
WS_DISCONNECT_EVENT_TYPES deliberately omits logout (admin-initiated
revocations use session_revoke, while logout is the user-initiated
case). Three consumers (tx, undying, zzz) hand-rolled this same branch
before extraction.
Compose with create_ws_auth_guard to handle both kinds of disconnect:
const ws_guard = create_ws_auth_guard(transport, log);
const ws_logout_closer = create_ws_logout_closer(transport, log);
const on_audit_event = (event: AuditLogEvent): void => {
  ws_guard(event);
  ws_logout_closer(event);
};Ignores outcome === 'failure' events — failed logouts carry
unauthenticated identifiers (no session to close anyway), and reacting
to them would let an unauthenticated probe close the targeted account's
sockets by submitting a logout for an arbitrary account_id.

`transport`

`log`

logger for disconnect events (info level on non-zero closures)

type Logger

returns

AuditEventHandler

an on_audit_event callback wireable alongside create_ws_auth_guard.
The returned callback mutates transport via close_sockets_for_account
on every successful logout event with a non-empty account_id.

create_ws_test_harness
#

<TCtx extends BaseHandlerContext>(options: CreateWsTestHarnessOptions<TCtx>): WsTestHarness

Create a WebSocket test harness for the given specs + handlers.
Registers against a throwaway Hono app with a fake
upgradeWebSocket; the captured events factory is invoked per
connect() with a synthesized Hono context carrying the requested
auth identity. Returned clients drive the real
onOpen/onMessage/onClose path against a real WSContext.

`options`

type CreateWsTestHarnessOptions<TCtx>

returns

WsTestHarness

CreateAccountInput
#

server/app_backend.ts view source

CreateAccountInput

`username`

type Username

`password_hash`

type string

`email`

type Email | null

CreateAppBackendOptions
#

CreateAppBackendOptions

Input for create_app_backend().
keyring is passed pre-validated — callers handle their own error reporting
(e.g., tx uses runtime.exit(1) on invalid keys).

`stat`

Get file/directory stats, or null if path doesn't exist.

type (path: string) => Promise<StatResult | null>

`read_text_file`

Read a file as text.

type (path: string) => Promise<string>

`delete_file`

Delete a file.

type (path: string) => Promise<void>

`database_url`

Database connection URL (postgres://, file://, or memory://).

type string

`keyring`

Validated cookie signing keyring.

type Keyring

`password`

Password hashing implementation. Use argon2_password_deps in production.

type PasswordHashDeps

`log`

Structured logger instance. Omit for default (new Logger('server')).

type Logger

`on_audit_event`

Called after each audit log INSERT succeeds.
Use to broadcast audit events via SSE. Flows through AppDeps
to all route factories automatically. Defaults to a noop.

type (event: AuditLogEvent) => void

`audit_log_config`

Audit-log config for consumer event-type extensions. Built once at
startup via create_audit_log_config({extra_events}) and threaded
through AppDeps.audit_log_config to every fuz_app emit site so
consumer handlers cannot silently fall back to the builtin config.
Omit to use BUILTIN_AUDIT_LOG_CONFIG (no extra events).

type AuditLogConfig

`migration_namespaces`

Additional migration namespaces to run after the builtin auth namespace.
The shared schema_version table records one row per applied migration
(namespace, name, sequence); order is append-only so forward-only
guarantees hold per-namespace.
The reserved 'fuz_auth' namespace is rejected at startup. Omit for no
extra namespaces. This is the only place to splice consumer migrations
— DB init belongs to the backend lifecycle, not server assembly.

type ReadonlyArray<MigrationNamespace>

CreateAuditLogConfigOptions
#

CreateAuditLogConfigOptions

Options for create_audit_log_config.

`extra_events`

Extra event types keyed by event-type string. Value is a Zod metadata
schema, or null to register the type without validation (row still
written, metadata stored as raw JSONB).
Collisions with builtin event-type strings throw at construction.
Schemas are run via safeParse at insert time; mismatches log + count
but never throw (fail-open — see the drift counters in auth/audit_log_queries.ts).

type Readonly<Record<string, z.ZodType | null>>

CreateBroadcastApiOptions
#

CreateBroadcastApiOptions

Options for create_broadcast_api.

`peer`

The peer holding the transport registry used for sends.

type ActionPeer

`specs`

Notification specs to expose as broadcast methods. Typically the
remote_notification specs whose initiator is backend (or both).
Other kinds are accepted — the helper only uses spec.method and
spec.input — but the typical use is notifications.

type ReadonlyArray<ActionSpecUnion>

`log`

Logger for validation/send errors. Defaults to a [broadcast] namespace.

type LoggerType | null

`should_deliver`

Optional per-connection ACL predicate. When set, the broadcast fans out
via the transport's broadcast_filtered (feature-detected) — each
connection's identity is checked before the message is sent. When
unset, the transport broadcasts unfiltered via transport.send.
Requires a transport that implements FilterableBroadcastTransport
(today: only BackendWebsocketTransport). If set and the active
transport is not filterable, the send is skipped and an error logged.

type ShouldDeliverFn

CreateDatabaseOptions
#

db/create_db.ts view source

CreateDatabaseOptions

Options for create_database.

`log`

type SetupLogger

CreateDbResult
#

CreateDbResult

Result of database initialization.

`db`

type Db

`close`

Close the database connection. Bound to the actual driver at construction.

type () => Promise<void>

`db_type`

type DbType

`db_name`

type string

CreateFrontendRpcClientOptions
#

actions/frontend_rpc_client.ts view source

CreateFrontendRpcClientOptions<TApi>

Options for create_frontend_rpc_client.

generics

`TApi`

constraint object

default object

`specs`

Action specs the typed Proxy can dispatch. Methods absent from this
list silently return undefined from the Proxy — the generic TApi
cannot constrain runtime membership, so consumers must keep this list
in sync with the typed surface (codegen recommended).
Protocol actions (heartbeat, cancel) are not auto-spread —
they're filtered out of generated action_specs by codegen's
include_protocol_actions: false default and consumers spread them
in explicitly so the contract stays visible at every registration
site. For WS-using consumers, spread protocol_action_specs from
actions/protocol.ts here:
specs: [...protocol_action_specs, ...action_specs]. HTTP-only
consumers can omit them.

type ReadonlyArray<ActionSpecUnion>

`path`

HTTP RPC endpoint path for the default FrontendHttpTransport.
Defaults to /api/rpc. Ignored when transports is provided.

type string

`transports`

Optional explicit transport list. When provided, the default
FrontendHttpTransport(path) is not registered — the caller is
responsible for at least one ready transport. Use for WS-first or
WS+HTTP mixed setups.

type ReadonlyArray<Transport>

`transport_for_method`

Optional per-method transport selector — pure pass-through to
create_rpc_client. Return the transport name to use for a given
method, or undefined to fall back to the peer's default selection.
Useful when methods are registered on different backend dispatchers
(e.g. streaming actions on WS, REST RPC on HTTP) — a tx-style mixed
setup. Per-call RpcClientCallOptions.transport_name overrides this
for individual dispatches.

type TransportForMethod

`on_action_event`

Optional callback fired once per dispatched action — pure pass-through
to create_rpc_client. Used by zzz-style consumers that thread the
ActionEvent into a reactive cell (add_from_json + listen_to_action_event)
for pending / failed / value derivations.
event.spec.method and event.data.method narrow to
keyof TApi & string — drop the as ActionMethod cast at the call
site when TApi is a generated ActionsApi interface.

type (event: ActionEvent<keyof TApi & string>) => void

`lookup_action_handler`

Optional handler resolver. Wired onto environment.lookup_action_handler
— the registry the dispatcher uses to find handlers for inbound
messages and lifecycle phases. Defaults to () => undefined, which
is fine for HTTP-only frontends that never receive a server-pushed
notification or register a receive_error recovery hook.
Common reasons to provide this:
- Server-pushed notifications over WS — return a handler for
  (method, 'receive') so a remote_notification arriving on the
  socket dispatches to your subscriber bus (tx-style).
- Per-method retry / telemetry on errors — return a handler for
  (method, 'receive_error'). Note that as of the
  extract_action_result fix, a missing handler already produces
  {ok: false, error} — the stub is no longer required just to
  surface server errors.

type ActionEventEnvironment['lookup_action_handler']

CreateInviteInput
#

CreateInviteInput

Input for creating an invite.

`email`

type Email | null

`username`

type Username | null

`created_by`

type Uuid | null

CreatePermitOfferInput
#

CreatePermitOfferInput

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).

`from_actor_id`

type Uuid

`to_account_id`

type Uuid

`role`

type string

`scope_id`

type Uuid | null

`message`

type string | null

`expires_at`

type Date

CreateRpcClientOptions
#

CreateRpcClientOptions<TApi>

Options for create_rpc_client.

generics

`TApi`

constraint object

default object

`peer`

type ActionPeer

`environment`

`on_action_event`

Optional callback fired once per dispatched action with the live
ActionEvent. Consumers wire reactive state here — e.g. zzz's Actions
cell calls add_from_json + listen_to_action_event inside the
callback so its history stays decoupled from the rpc_client surface.
event.spec.method and event.data.method narrow to
keyof TApi & string — drop the as ActionMethod cast at the call
site when TApi is a generated ActionsApi interface.

type (event: ActionEvent<keyof TApi & string>) => void

`transport_for_method`

Optional per-method transport selector. When provided, the client calls
peer.send(msg, {transport_name}) with the returned transport for each
request_response / remote_notification dispatch. Returning undefined
falls back to the peer's default selection.

type TransportForMethod

CreateRpcEndpointOptions
#

auth/session_lifecycle.ts view source

CreateRpcEndpointOptions

Options for create_rpc_endpoint.

`path`

Mount path for the endpoint (e.g., /api/rpc).

type string

`actions`

RPC actions to serve.

type Array<RpcAction>

`log`

Logger instance for handler context.

type Logger

`action_ip_rate_limiter`

Per-IP rate limiter consulted for actions whose spec declares
rate_limit: 'ip' or 'both'. null disables the IP check.
Per-action gate via action.spec.rate_limit. Same limiter is
shared with the WebSocket action dispatcher — one budget per
action, not per transport.

type RateLimiter | null

`action_account_rate_limiter`

Per-actor rate limiter consulted for actions whose spec declares
rate_limit: 'account' or 'both'. Keyed on
request_context.actor.id. null disables the account check.
Same limiter is shared with the WebSocket action dispatcher.

type RateLimiter | null

CreateSessionAndSetCookieOptions
#

CreateSessionAndSetCookieOptions

Options for create_session_and_set_cookie.

`keyring`

Keyring for cookie signing.

type Keyring

`deps`

Query deps (needs db for session creation).

type QueryDeps

`c`

Hono context for setting the cookie.

type Context

`account_id`

The account to create a session for.

type string

`session_options`

Session cookie configuration.

type SessionOptions<string>

`max_sessions`

Per-account session cap (null to skip enforcement).

type number | null

CreateTestAppOptions
#

CreateTestAppOptions

Configuration for create_test_app.

inheritance

extends:

TestAppServerOptions

`create_route_specs`

Route spec factory — called with the assembled AppServerContext.

type (context: AppServerContext) => Array<RouteSpec>

`rpc_endpoints`

RPC endpoints mounted by create_app_server — eager array or
(ctx: AppServerContext) => Array<RpcEndpointSpec> factory. Symmetric
with the suite-level rpc_endpoints option on
describe_standard_admin_integration_tests etc., so callers wiring a
full RPC stack don't have to switch shapes between low-level and
suite-level helpers. Equivalent to app_options.rpc_endpoints; when
both are set app_options wins and console.warn fires.

`app_options`

Optional overrides for AppServerOptions (backend, session_options, and create_route_specs are managed).

type

Partial<
		Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>
	>

CreateTestAppSurfaceSpecOptions
#

CreateTestAppSurfaceSpecOptions

Options for create_test_app_surface_spec.

`session_options`

Consumer's session config (required — varies per app).

type SessionOptions<string>

`create_route_specs`

Consumer's route factory — receives the same AppServerContext as production.

type (ctx: AppServerContext) => Array<RouteSpec>

`env_schema`

Env schema for surface generation (default: BaseServerEnv).

type z.ZodObject

`event_specs`

SSE event specs for surface generation.

type Array<EventSpec>

`rpc_endpoints`

RPC endpoint specs for surface generation.
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> — symmetric with
create_app_server's rpc_endpoints option, so consumers can pass
the same factory to both entry points. The factory runs once against
the stub AppServerContext this helper already builds.

type Array<RpcEndpointSpec> | ((ctx: AppServerContext) => Array<RpcEndpointSpec>)

`transform_middleware`

Transform middleware array (e.g., tx's extend_middleware_for_tx_binary).

type (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>

`bootstrap_route_prefix`

Bootstrap route prefix (default: '/api/account').

type string

CreateWsTestHarnessOptions
#

CreateWsTestHarnessOptions<TCtx>

Options for create_ws_test_harness.

generics

`TCtx`

constraint BaseHandlerContext

`actions`

The actions registered on this endpoint — matches the shape
register_action_ws accepts. Each entry is a {spec, handler?} tuple;
shared fuz_app primitives (like heartbeat_action) can be spread in
alongside consumer-specific actions.

type ReadonlyArray<Action<TCtx>>

`extend_context`

type RegisterActionWsOptions<TCtx>['extend_context']

`transport`

Pass a pre-created transport to share with a broadcast API.

`heartbeat`

Threaded through to register_action_ws. Defaults to false in tests —
fake timers + receive-silence detection need explicit opt-in and per-
test tuning to avoid spurious closes.

type RegisterActionWsOptions<TCtx>['heartbeat']

`log`

Optional logger. Defaults to a silent [ws-test] logger.

type Logger

`on_socket_open`

Threaded straight through to register_action_ws.

type RegisterActionWsOptions<TCtx>['on_socket_open']

`on_socket_close`

Threaded straight through to register_action_ws.

type RegisterActionWsOptions<TCtx>['on_socket_close']

CREDENTIAL_TYPE_KEY
#

"credential_type"

Hono context variable name for the credential type.

CREDENTIAL_TYPES
#

readonly ["session", "api_token", "daemon_token"]

The credential types that can authenticate a request.

CredentialType
#

ZodEnum<{ session: "session"; api_token: "api_token"; daemon_token: "daemon_token"; }>

Credential type — how a request was authenticated.

DAEMON_TOKEN_HEADER
#

"X-Daemon-Token"

The X-Daemon-Token header name.

DaemonInfo
#

ZodObject<{ version: ZodNumber; pid: ZodNumber; port: ZodNumber; started: ZodString; app_version: ZodString; }, $strict>

Daemon info schema for ~/.{name}/run/daemon.json.

DaemonToken
#

ZodString

Daemon token format: 43 base64url characters (256 bits).

DaemonTokenRotation
#

DaemonTokenRotation

Result of starting daemon token rotation.

`state`

The mutable runtime state. Pass to create_daemon_token_middleware.

type DaemonTokenState

`stop`

Stop rotation, clean up the interval, and delete the token file. Call on graceful shutdown.

type () => Promise<void>

DaemonTokenRotationOptions
#

DaemonTokenRotationOptions

Options for daemon token rotation.

`app_name`

Application name (for ~/.{name}/run/daemon_token).

type string

`rotation_interval_ms`

Rotation interval in ms. Default: 30000 (30s).

type number

DaemonTokenState
#

DaemonTokenState

Mutable runtime state for daemon token rotation.
This is runtime state (not AppDeps or *Options) — it changes during
operation. Created at server startup, passed to the middleware factory.

`current_token`

Current valid token.

type string

`previous_token`

Previous token, still valid during the race window. null before first rotation.

type string | null

`rotated_at`

When the last rotation occurred.

type Date

`keeper_account_id`

The account ID of the keeper (resolved at startup, set by on_bootstrap).

type string | null

DaemonTokenWriteDeps
#

DaemonTokenWriteDeps

Deps for writing the daemon token to disk.

DataExposureTestOptions
#

ui/Datatable.svelte view source

DataExposureTestOptions

Options for describe_data_exposure_tests.

`build`

Build the app surface spec (for schema-level checks).

type () => AppSurfaceSpec

`session_options`

Session config for runtime tests.

type SessionOptions<string>

`create_route_specs`

Route spec factory for runtime tests.

type (ctx: AppServerContext) => Array<RouteSpec>

`sensitive_fields`

Fields that must never appear in any response. Default: SENSITIVE_FIELD_BLOCKLIST.

type ReadonlyArray<string>

`admin_only_fields`

Fields that must not appear in non-admin responses. Default: ADMIN_ONLY_FIELD_BLOCKLIST.

type ReadonlyArray<string>

`app_options`

Optional overrides for AppServerOptions.

type

Partial<
		Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>
	>

`db_factories`

Database factories to run tests against. Default: pglite only.

type Array<DbFactory>

`skip_routes`

Routes to skip, in 'METHOD /path' format.

type Array<string>

Datatable
#

DATATABLE_COLUMN_WIDTH_DEFAULT
#

ui/datatable.ts view source

120

Default initial column width in pixels.

DATATABLE_MIN_COLUMN_WIDTH
#

ui/datatable.ts view source

50

Default minimum column width in pixels.

DatatableColumn
#

ui/datatable.ts view source

DatatableColumn<T>

Column definition for a Datatable.

generics

`T`

default unknown

`key`

Row data accessor key.

type string & keyof T

`label`

Header label text.

type string

`width`

Initial column width in pixels.

type number

`min_width`

Minimum column width in pixels.

type number

`format`

Format a cell value for display. Falls back to format_value when absent.

type (value: T[keyof T], row: T) => string

Db
#

Database wrapper providing a consistent query and transaction interface.
Construct via create_pg_db() from db/db_pg.ts or create_pglite_db() from
db/db_pglite.ts for proper transaction support, or via create_db() for
URL-based auto-detection.

examples

const {db, close} = await create_db('postgres://...');
const users = await db.query<User>('SELECT * FROM users WHERE active = $1', [true]);
await db.transaction(async (tx) => {
  await tx.query('INSERT INTO users ...');
  await tx.query('INSERT INTO audit_log ...');
});
await close();

`client`

type DbClient

readonly

`constructor`

type new (options: DbDeps): Db

`options`

type DbDeps

`query`

Execute a query and return all rows.

type <T>(text: string, values?: unknown[] | undefined): Promise<T[]>

`text`

SQL text with $1, $2, ... parameter placeholders

type string

`values?`

parameter values bound to the placeholders in text

type unknown[] | undefined

optional

returns Promise<T[]>

the result rows, typed as T

`query_one`

Execute a query and return the first row, or undefined if no rows.

type <T>(text: string, values?: unknown[] | undefined): Promise<T | undefined>

`text`

SQL text with $1, $2, ... parameter placeholders

type string

`values?`

parameter values bound to the placeholders in text

type unknown[] | undefined

optional

returns Promise<T | undefined>

the first row, or undefined when the result set is empty

`transaction`

Run a function inside a database transaction.
The callback receives a transaction-scoped Db. Queries inside the callback
go through the transaction connection; queries outside use the pool normally.
Commits on success, rolls back on error.

type <T>(fn: (tx_db: Db) => Promise<T>): Promise<T>

`fn`

async function receiving a transaction-scoped Db

type (tx_db: Db) => Promise<T>

returns Promise<T>

the value returned by fn

throws

Error - propagated from `fn` after `ROLLBACK`, or from the driver

DbClient
#

DbClient

Minimal interface that both pg and pglite satisfy.

`query`

type <T = unknown>(text: string, values?: Array<unknown>) => Promise<{rows: Array<T>}>

DbDeps
#

DbDeps

Configuration for constructing a Db with transaction support.
transaction is injected by create_db which knows the driver.
For pg: acquires a dedicated pool client per transaction.
For PGlite: delegates to pglite.transaction().

`client`

type DbClient

`transaction`

type <T>(fn: (tx_db: Db) => Promise<T>) => Promise<T>

DbDriverResult
#

DbDriverResult

Result of constructing a driver-specific Db.
Returned by create_pg_db() and create_pglite_db().
The close callback is bound to the actual driver — callers
never need to know which driver is in use.

`db`

type Db

`close`

Close the database connection. Bound to the actual driver at construction.

type () => Promise<void>

DbFactory
#

DbFactory

Factory interface for creating test database instances.

`name`

type string

`create`

type () => Promise<Db>

`close`

type (db: Db) => Promise<void>

`skip`

type boolean

`skip_reason`

type string

DbRouteOptions
#

DbRouteOptions

Per-factory configuration for db routes.

`db_type`

type DbType

`db_name`

type string

`extra_stats`

Optional callback to provide app-specific stats in the health response.

type (db: Db) => Promise<Record<string, unknown>>

`log`

Optional logger for server-side diagnostics (e.g. FK violation details).

type Logger

DbStatus
#

DbStatus

Full database status snapshot.

`connected`

Whether the database is reachable.

type boolean

`error`

Error message if connection failed.

type string

`table_count`

Number of public tables.

type number

`tables`

Per-table row counts.

type Array<TableStatus>

`migrations`

Per-namespace migration status.

type Array<MigrationStatus>

`old_tracker_shape`

True if the pre-0.42 schema_version shape (with a version column)
was detected. The runner refuses to start in this state — operators
see this flag as their cue to drop the table or call baseline().

type boolean

DbType
#

DbType

Database driver type.

DEFAULT_ACTION_ACCOUNT_RATE_LIMIT
#

RateLimiterOptions

Default options for per-actor action-dispatcher rate limiting: 1200
attempts per 15 minutes. Shared by the HTTP RPC and WebSocket action
dispatchers. Permissive — sustained ~80/min is well above any human
admin workflow; an oracle probing 10k addresses still finishes in
~2 hours, slow enough to surface in audit. Tighten downstream.

DEFAULT_ACTION_IP_RATE_LIMIT
#

RateLimiterOptions

Default options for per-IP action-dispatcher rate limiting: 600 attempts
per 15 minutes. Shared by the HTTP RPC and WebSocket action dispatchers
(one budget per action, not per transport). Permissive — catches runaway
scripts and egregious oracle probes, but well above human or normal
automation pace. Tighten downstream for stricter deployments.

DEFAULT_BACKOFF_FACTOR
#

1.5

Exponential backoff factor: delay = base * factor^(attempt-1).

DEFAULT_CLOSE_CODE
#

1000

Default WebSocket close code (normal closure).

DEFAULT_COLLECTIONS_PATH
#

"./action_collections.js"

Default collections_path — every consumer's gen producers point at the sibling action_collections.js.

DEFAULT_ERROR_SCHEMA_TIGHTNESS
#

ErrorSchemaTightnessOptions

Baseline error schema tightness applied by
describe_standard_attack_surface_tests when no config is passed.
Uses min_specificity: 'enum' (the assertion default) with ignore_statuses
for middleware-derived status codes that are commonly generic (auth middleware
produces multiple error codes at 401/403, and 429 comes from rate limiters),
and allowlist seeded with FUZ_APP_STOCK_ROUTE_TIGHTNESS_ALLOWLIST so
fuz_app-shipped routes with heterogeneous generic schemas don't force every
consumer to hand-maintain an identical allowlist. Consumers can pass a
narrower config with project-specific allowlist entries, or pass null
to skip the assertion entirely.

default_format_scope
#

(args: { scope_id: string | null; role: string; }): string | null

Default FormatScope — always returns null so callers fall back to the raw uuid.

`args`

type { scope_id: string | null; role: string; }

returns

string | null

DEFAULT_HEARTBEAT_INTERVAL
#

30000

Idle interval before sending a heartbeat (ms).

DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT
#

60000

Max receive silence before closing with WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT (ms).

DEFAULT_INTEGRATION_ERROR_COVERAGE
#

0.2

Default minimum error coverage threshold for the standard integration
and admin test suites. Conservative — not all error paths are exercisable
in the composable suites. Consumers should increase as their test suites mature.

DEFAULT_LOGIN_ACCOUNT_RATE_LIMIT
#

RateLimiterOptions

Default options for per-account login rate limiting: 10 attempts per 30 minutes.

DEFAULT_LOGIN_FAIL_FLOOR_MS
#

250

Default minimum wall-clock time (ms) for a login failure (401) response.
Picked to exceed the p99 of every 401 code path (Argon2id dominates at
~100ms, plus DB + overhead). The handler races failure work against
sleep(floor + jitter) via await, so observed response time = max(work,
delay). Found-vs-not-found and rate-limit-skipped-vs-not paths converge.
Only 401 is padded — 429 stays fast by design to keep rate-limit DoS
handling cheap.

DEFAULT_LOGIN_FAIL_JITTER_MS
#

25

Default uniform jitter window (±ms) layered on the floor.
Random jitter prevents a stable clamp point from leaking whenever a path
occasionally exceeds the floor. Math.random is sufficient — we only need
unpredictability of the exact delay, not cryptographic guarantees.

DEFAULT_LOGIN_IP_RATE_LIMIT
#

RateLimiterOptions

Default options for per-IP login rate limiting: 5 attempts per 15 minutes.

DEFAULT_MAX_BODY_SIZE
#

number

Default maximum request body size: 1 MiB.

DEFAULT_MAX_SESSIONS
#

5

Default maximum sessions per account.

DEFAULT_MAX_TOKENS
#

10

Default maximum API tokens per account.

DEFAULT_METATYPES_PATH
#

"./action_metatypes.js"

Default metatypes_path — sibling action_metatypes.js carrying the generated ActionMethod.

DEFAULT_QUEUE_MAX_SIZE
#

100

Default bound on buffered requests while disconnected. Overflow rejects.

DEFAULT_RATE_LIMITER_MAX_KEYS
#

100000

Default tracked-key cap: bounds worst-case memory under key-enumeration
attacks (an attacker rotating source IPs cannot grow the backing map
indefinitely between cleanup ticks). Tuned to comfortably fit real
traffic for a single-instance deployment while capping memory at a few
MB in the worst case.

DEFAULT_RECONNECT_DELAY
#

1000

Base reconnect delay in ms.

DEFAULT_RECONNECT_DELAY_MAX
#

10000

Max reconnect delay in ms (cap on exponential backoff).

DEFAULT_ROTATION_INTERVAL_MS
#

30000

Default rotation interval in milliseconds (30 seconds).

DEFAULT_SERVER_HEARTBEAT_TIMEOUT
#

60000

Default inactivity window before the server closes a silent socket.

default_setup_logger
#

SetupLogger

Default logger using bracket format.

DEFAULT_SPECS_MODULE
#

"./action_specs.js"

Default specs_module — sibling action_specs.js namespace bundled by the consumer.

derive_error_schemas
#

(auth: RouteAuth, has_input: boolean, has_params?: boolean, has_query?: boolean, rate_limit?: "both" | "ip" | "account" | undefined): Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

Derive error schemas from a route's auth requirement, input schema, and rate limit config.
Returns the error schemas that middleware will auto-produce for this route.
Route handlers can declare additional error schemas via RouteSpec.errors;
explicit entries override auto-derived ones for the same status code.
Derivation rules:
- Has input schema (non-null) or has params schema or has query schema: 400 (validation error with issues)
- auth: authenticated: 401
- auth: role: 401 + 403 (with required_role)
- auth: keeper: 401 + 403 (keeper-specific)
- rate_limit: 429 (rate limit exceeded with retry_after)

`auth`

type RouteAuth

`has_input`

type boolean

`has_params`

type boolean

default false

`has_query`

type boolean

default false

`rate_limit?`

type "both" | "ip" | "account" | undefined

optional

returns

Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

derive_http_method
#

testing/adversarial_404.ts view source

(side_effects: boolean): RouteMethod

Derive the default HTTP method from side effects.

`side_effects`

type boolean

returns

RouteMethod

describe_adversarial_404
#

(options: AdversarialTestOptions): void

Generate adversarial 404 response validation tests.
For each route with params + 404 in error_schemas:
1. Creates a stub handler returning 404 with the declared error code
2. Fires a request with valid-format params (nil UUIDs for UUID params)
3. Validates response status is 404
4. Validates response body matches the declared 404 Zod schema

`options`

type AdversarialTestOptions

returns

void

describe_adversarial_auth
#

(options: AdversarialTestOptions): void

Generate adversarial HTTP auth enforcement test suites.
Describe blocks:
- unauthenticated → 401 — every protected route
- wrong role → 403 — every role route, tested with all non-matching roles
- authenticated without role → 403 — every role route, no-role context
- correct auth passes guard — every protected route, assert not 401/403

`options`

type AdversarialTestOptions

returns

void

describe_adversarial_input
#

testing/audit_completeness.ts view source

(options: AdversarialTestOptions): void

Generate adversarial input validation test suites.
Tests input body validation and params validation for all routes.
Uses correct auth credentials so auth guards pass and validation
middleware is actually exercised.

`options`

type AdversarialTestOptions

returns

void

describe_audit_completeness_tests
#

(options: AuditCompletenessTestOptions): void

Composable audit log completeness test suite.
Verifies that every auth mutation route produces the correct audit log
event type. Exercises routes via HTTP requests against a real PGlite
database, then queries the audit_log table to verify events.

`options`

type AuditCompletenessTestOptions

returns

void

throws

Error - at setup time when `options.rpc_endpoints` is empty — the

describe_bearer_auth_cases
#

(suite_name: string, cases: BearerAuthTestCase[], ip_rate_limiter?: RateLimiter | null): void

Run a table of bearer auth middleware test cases.
Generates one test() per case inside a describe() block.

`suite_name`

type string

`cases`

type BearerAuthTestCase[]

`ip_rate_limiter`

type RateLimiter | null

default null

returns

void

describe_data_exposure_tests
#

testing/rate_limiting.ts view source

(options: DataExposureTestOptions): void

Composable data exposure test suite.
Three test groups:
1. Schema-level — walk JSON Schema output/error schemas for sensitive field names
2. Runtime — fire real requests and check response bodies against blocklists
3. Cross-privilege — admin routes return 403 for non-admin, error responses
   contain no sensitive fields

`options`

type DataExposureTestOptions

returns

void

describe_rate_limiting_tests
#

(options: RateLimitingTestOptions): void

Standard rate limiting integration test suite.
Creates 3 test groups:
1. IP rate limiting on login — fires max_attempts + 1 login requests,
   verifies the last returns 429 with a valid RateLimitError body.
2. Per-account rate limiting on login — fires max_attempts + 1 login
   requests with the same username, verifies the last returns 429.
3. Bearer auth IP rate limiting — fires max_attempts + 1 bearer requests
   with an invalid token, verifies the last returns 429.
Each test group asserts that required routes exist, failing with a descriptive
message if the consumer's route specs are misconfigured.

`options`

type RateLimitingTestOptions

returns

void

throws

Error - at setup time when `options.rpc_endpoints` is empty — the

describe_round_trip_validation
#

testing/round_trip.ts view source

(options: RoundTripTestOptions): void

Run schema-driven round-trip validation tests.
For each route:
1. Resolve URL with valid params
2. Generate a valid request body (or use override)
3. Pick auth headers matching the route's auth requirement
4. Fire the request and validate the response against declared schemas
SSE routes are skipped (Content-Type text/event-stream).
Routes returning non-2xx with valid input are still validated against
their declared error schemas.

`options`

type RoundTripTestOptions

returns

void

describe_rpc_attack_surface_tests
#

testing/rpc_attack_surface.ts view source

(options: RpcAttackSurfaceOptions): void

Run the standard RPC attack surface test suite.
Generates 3 test groups:
1. Auth enforcement — per-method auth checks via JSON-RPC envelopes
2. Adversarial envelopes — malformed JSON-RPC requests
3. Adversarial params — schema-invalid params per method
Skips silently when surface.rpc_endpoints is empty.

`options`

type RpcAttackSurfaceOptions

returns

void

describe_rpc_round_trip_tests
#

testing/rpc_round_trip.ts view source

(options: RpcRoundTripTestOptions): void

Run schema-driven round-trip validation for RPC endpoints.
For each method:
1. Generate valid params from the action's input schema
2. Fire a POST request with JSON-RPC envelope
3. For side_effects: false methods, also fire a GET request
4. Validate response is well-formed JSON-RPC; successful responses are
   also validated against the method's declared output schema
Error responses (from missing DB state, etc.) are expected and validated
as well-formed JSON-RPC errors. Successful responses are validated against
action.spec.output.

`options`

type RpcRoundTripTestOptions

returns

void

describe_sse_route_tests
#

testing/sse_round_trip.ts view source

(options: SseRouteTestOptions): void

Run SSE route validation tests.
For each route: opens an authenticated SSE connection, asserts the
connected comment, fires the trigger, validates the resulting payload,
then asserts close-on-revoke (unless opted out).

`options`

type SseRouteTestOptions

returns

void

throws

Error - at setup time when `options.rpc_endpoints` is empty — the

describe_standard_admin_integration_tests
#

testing/admin_integration.ts view source

(options: StandardAdminIntegrationTestOptions): void

Standard admin integration test suite for fuz_app admin routes.
Exercises account listing, permit grant/revoke (via RPC), session
management, token management, audit log reads, admin-to-admin
isolation, and 401/403 error-coverage on the admin REST surface.
Output-schema conformance is not in scope — see the module docstring
for the suites that cover it.

`options`

type StandardAdminIntegrationTestOptions

returns

void

throws

Error - at setup time when `options.rpc_endpoints` is empty — admin

describe_standard_adversarial_headers
#

testing/adversarial_headers.ts view source

(suite_name: string, options: TestMiddlewareStackOptions, allowed_origin: string, extra_cases?: AdversarialHeaderCase[] | undefined): void

Create a middleware stack app with standard adversarial header tests.
Convenience wrapper combining create_test_middleware_stack_app
and create_standard_adversarial_cases. Generates one test() per case
inside a describe() block — asserts body content for both error and
success cases, and verifies that mock_validate was (or was not) reached
per the case's validate_expectation flag, ensuring earlier middleware
actually short-circuits before token validation in the rejection cases.

`suite_name`

the describe block name

type string

`options`

middleware stack configuration

type TestMiddlewareStackOptions

`allowed_origin`

an origin that passes the origin check (used for standard cases)

type string

`extra_cases?`

additional cases appended after the 7 standard ones

type AdversarialHeaderCase[] | undefined

optional

returns

void

describe_standard_attack_surface_tests
#

testing/integration.ts view source

(options: StandardAttackSurfaceOptions): void

Run the standard attack surface test suite.
Generates 10 test groups:
Snapshot — live surface matches committed JSON
Determinism — building twice yields identical results
Public routes — bidirectional check (no unexpected, no missing)
Middleware stack — every API route has the full middleware chain
Surface invariants — structural assertions (error schemas, descriptions, duplicates, consistency)
Security policy — rate limiting on sensitive routes, no unexpected public mutations, method conventions
Error schema tightness — informational log of generic vs specific error schemas, plus assertion against DEFAULT_ERROR_SCHEMA_TIGHTNESS by default (opt out with error_schema_tightness: null)
Adversarial auth — unauthenticated/wrong-role/correct-auth enforcement
Adversarial input — input body and params validation
Adversarial 404 — stub 404 handlers, validate response bodies against declared schemas
Consumer test files call this with project-specific options, then add
any project-specific assertions in additional describe blocks.

`options`

type StandardAttackSurfaceOptions

returns

void

describe_standard_integration_tests
#

(options: StandardIntegrationTestOptions): void

Standard integration test suite for fuz_app auth routes.
Exercises login/logout, cookie attributes, session security, session
revocation, password change (incl. API token revocation), origin
verification, bearer auth (incl. browser context discard on mutations),
token revocation, cross-account isolation, expired credential rejection,
signup invite edge cases, and response body validation.
Each test group asserts that required routes exist, failing with a descriptive
message if the consumer's route specs are misconfigured.

`options`

type StandardIntegrationTestOptions

returns

void

throws

Error - at setup time when `options.rpc_endpoints` is empty — the

describe_standard_tests
#

testing/standard.ts view source

(options: StandardTestOptions): void

Run both standard integration and admin integration test suites.
Admin tests are only included when roles is provided.

`options`

type StandardTestOptions

returns

void

detect_format
#

(field_schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): string | null

Detect format constraints on a field by converting to JSON Schema.
Returns format string (e.g. 'uuid', 'email') or null.

`field_schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

string | null

DISCONNECT_EVENT_TYPES
#

ReadonlySet<string>

Audit event types that trigger SSE stream disconnection.
permit_revoke requires the revoked role to match the guard's required_role
(or is skipped entirely when required_role is null — useful for streams
not gated by any specific permit).
session_revoke_all and password_change close every stream for the target account.
session_revoke closes only the stream tied to the specific revoked session
(matched by the blake3 session hash in event.metadata.session_id) — closing
all of a user's streams for a single-session revoke would be over-aggressive.

dispatch_ws_message
#

(on_message: (evt: MessageEvent<WSMessageReceive>, ws: WSContext<unknown>) => void, event: MessageEvent<any>, ws: WSContext<unknown>): Promise<...>

Hono types WSEvents.onMessage as () => void | Promise<void>.
Awaits only the Promise branch so tests observe full dispatch
(auth, validation, handler, send).

`on_message`

type (evt: MessageEvent<WSMessageReceive>, ws: WSContext<unknown>) => void

`event`

type MessageEvent<any>

`ws`

type WSContext<unknown>

returns

Promise<void>

drop_auth_schema
#

(db: Db): Promise<void>

Drop all auth tables and schema version tracking for a clean slate.
Recommended at the start of init_schema callbacks for create_pg_factory.
Persistent test databases can accumulate stale schema from previous fuz_app
versions — this ensures migrations run against a truly empty database.
Safe on fresh databases (IF EXISTS on all statements). No-op effect for
PGlite (already fresh), but harmless to call unconditionally.

`db`

type Db

returns

Promise<void>

EffectErrorContext
#

EffectErrorContext

Context passed to on_effect_error when a pending effect rejects.

`method`

HTTP method of the request that spawned the effect.

type string

`path`

URL path of the request that spawned the effect.

type string

Email
#

http/pending_effects.ts view source

ZodEmail

Email validation.

emit_after_commit
#

(ctx: PendingEffectsContext, fn: () => void): void

Defer a side effect until after the handler's transaction commits.
Exceptions thrown by fn are caught and logged via ctx.log.error, so one
failed send cannot corrupt the already-committed response or starve other
queued effects in the same tick.

`ctx`

context carrying log and the pending_effects queue

type PendingEffectsContext

`fn`

synchronous side effect to run after commit

type () => void

returns

void

env_schema_to_surface
#

(schema: ZodObject<$ZodLooseShape, $strip>): AppSurfaceEnv[]

Convert env schema to surface entries using .meta() metadata.

`schema`

Zod object schema with .meta() on fields

type ZodObject<$ZodLooseShape, $strip>

returns

AppSurfaceEnv[]

EnvDeps
#

EnvDeps

Environment variable access.

`env_get`

Get an environment variable value.

type (name: string) => string | undefined

`env_set`

Set an environment variable.

type (name: string, value: string) => void

EnvValidationError
#

env/load.ts view source

Error thrown when environment validation fails.
Contains structured information for apps to format their own error messages.

inheritance

extends:

Error

`raw`

The raw env values that were read.

type Record<string, string | undefined>

readonly

`zod_error`

The Zod validation error.

type z.core.$ZodError

readonly

`all_undefined`

True if every env var was undefined (nothing loaded).

type boolean

readonly

`constructor`

type new (raw: Record<string, string | undefined>, zod_error: $ZodError<unknown>): EnvValidationError

`raw`

type Record<string, string | undefined>

`zod_error`

type $ZodError<unknown>

`format_issues`

Format Zod validation issues as human-readable strings.

type (): string[]

returns string[]

array of formatted issue strings like "PORT: Expected number"

EnvValidationResult
#

EnvValidationResult

Result of env var validation.
Uses discriminated union for better type narrowing:
- ok: true, missing: null — all vars present
- ok: false, missing: EnvVarRef[] — some vars missing

EnvVarRef
#

EnvVarRef

An env var reference found in a config.

`name`

Variable name (without $$ delimiters).

type string

`path`

Path where the reference was found (e.g., "target.host", "resources[3].path").

type string

ERROR_ACCOUNT_NOT_FOUND
#

"account_not_found"

Token references a deleted account.

ERROR_ALREADY_BOOTSTRAPPED
#

"already_bootstrapped"

Bootstrap lock already acquired — system already bootstrapped.

ERROR_AUTHENTICATION_REQUIRED
#

"authentication_required"

No valid session or bearer token.

ERROR_BEARER_REJECTED_BROWSER
#

"bearer_token_rejected_in_browser_context"

Bearer token sent with Origin/Referer header (browser context).

ERROR_BOOTSTRAP_NOT_CONFIGURED
#

"bootstrap_not_configured"

Bootstrap endpoint called but no token path configured.

ERROR_DATABASE_CONNECTION_FAILED
#

"database_connection_failed"

Database health-check query failed (connectivity or query error).

ERROR_FORBIDDEN_ORIGIN
#

"forbidden_origin"

Request origin not in allowlist.

ERROR_FORBIDDEN_REFERER
#

"forbidden_referer"

Request referer not in allowlist.

ERROR_FOREIGN_KEY_VIOLATION
#

"foreign_key_violation"

DELETE blocked by a foreign key constraint.

ERROR_INSUFFICIENT_PERMISSIONS
#

"insufficient_permissions"

Authenticated but missing required role.

ERROR_INVALID_CREDENTIALS
#

"invalid_credentials"

Username or password is wrong (intentionally vague for enumeration prevention).

ERROR_INVALID_DAEMON_TOKEN
#

"invalid_daemon_token"

Daemon token header present but malformed or not matching current/previous token.

ERROR_INVALID_EVENT_TYPE
#

"invalid_event_type"

Query parameter event_type is not a valid audit event type.

ERROR_INVALID_JSON_BODY
#

"invalid_json_body"

Request body is not valid JSON or not an object.

ERROR_INVALID_QUERY_PARAMS
#

"invalid_query_params"

URL query params failed Zod validation.

ERROR_INVALID_REQUEST_BODY
#

"invalid_request_body"

Request body failed Zod validation.

ERROR_INVALID_ROUTE_PARAMS
#

"invalid_route_params"

URL path params failed Zod validation.

ERROR_INVALID_TOKEN
#

"invalid_token"

Bearer token failed validation (missing, malformed, or revoked).

ERROR_INVITE_ACCOUNT_EXISTS_EMAIL
#

"invite_account_exists_email"

An account already exists with this invite's email.

ERROR_INVITE_ACCOUNT_EXISTS_USERNAME
#

"invite_account_exists_username"

An account already exists with this invite's username.

ERROR_INVITE_DUPLICATE
#

"invite_duplicate"

An unclaimed invite already exists for this email or username.

ERROR_INVITE_MISSING_IDENTIFIER
#

"invite_missing_identifier"

Invite must have at least an email or username.

ERROR_INVITE_NOT_FOUND
#

"invite_not_found"

Invite not found (for delete operations).

ERROR_KEEPER_ACCOUNT_NOT_CONFIGURED
#

"keeper_account_not_configured"

Daemon token valid but keeper account not yet resolved (pre-bootstrap).

ERROR_KEEPER_ACCOUNT_NOT_FOUND
#

"keeper_account_not_found"

Keeper account ID set but account row not found.

ERROR_KEEPER_REQUIRES_DAEMON_TOKEN
#

"keeper_requires_daemon_token"

Keeper routes require daemon_token credential type.

ERROR_NO_MATCHING_INVITE
#

"no_matching_invite"

No unclaimed invite matches the signup credentials.

ERROR_OFFER_EXPIRED
#

"offer_expired"

Error reason — offer's expires_at has passed.

ERROR_OFFER_NOT_AUTHORIZED
#

"offer_not_authorized"

Error reason — caller is not authorized to offer this role (default policy: caller lacks the role; consumer authorize callback may add further policy).

ERROR_OFFER_NOT_FOUND
#

"offer_not_found"

Error reason — offer does not exist or belongs to a different recipient (404-over-403 IDOR mask).

ERROR_OFFER_ROLE_NOT_GRANTABLE
#

"offer_role_not_grantable"

Error reason — the offered role is not web_grantable (nobody may offer it via this surface).

ERROR_OFFER_SELF_TARGET
#

"offer_self_target"

Error reason — caller tried to offer themselves a permit.

ERROR_OFFER_TERMINAL
#

"offer_terminal"

Error reason — offer is declined, retracted, or superseded.

ERROR_PAYLOAD_TOO_LARGE
#

"payload_too_large"

Request body exceeds the maximum allowed size.

ERROR_PERMIT_NOT_FOUND
#

"permit_not_found"

Permit ID not found or not owned by the target actor.

ERROR_RATE_LIMIT_EXCEEDED
#

"rate_limit_exceeded"

Rate limiter rejected the request.

ERROR_ROLE_NOT_SELF_SERVICE_ELIGIBLE
#

"role_not_self_service_eligible"

Error reason — caller asked to self-toggle a role outside the configured allowlist.

ERROR_ROLE_NOT_WEB_GRANTABLE
#

"role_not_web_grantable"

Admin tried to grant a role that is not web-grantable.

ERROR_ROW_NOT_FOUND
#

"row_not_found"

Row with the given PK value not found.

ERROR_SIGNUP_CONFLICT
#

"signup_conflict"

Signup conflict — username or email already taken (intentionally vague for enumeration prevention).

ERROR_TABLE_NO_PRIMARY_KEY
#

"table_no_primary_key"

Table has no primary key constraint (cannot delete by PK).

ERROR_TABLE_NOT_FOUND
#

"table_not_found"

Table name not found in information_schema.

ERROR_TOKEN_FILE_MISSING
#

"token_file_missing"

Bootstrap token file not found on disk.

ErrorCoverageCollector
#

Tracks which route × status (and route × status × code) combinations have
been exercised in tests.
Use record() to log an observed status (optionally with the body's error
code), or assert_and_record() to combine response validation with tracking
(auto-extracts body.error from the response when present).
After all tests, call uncovered() to find declared error paths never
exercised.
An observation recorded without a code still satisfies "any-code" coverage
requirements for the same status — i.e., if a caller records just the status,
all declared codes for that status are considered covered. Per-code tracking
is additive: callers who know the body's error value should pass it to get
precise per-code gap reporting on routes with literal/enum error schemas.

`observed`

Observed keys: "METHOD /spec-path:STATUS" or "METHOD /spec-path:STATUS:CODE".
Both shapes coexist — the code-less key marks the status as covered at any
code; a code-bearing key adds per-code precision.

type Set<string>

readonly

`record`

Record an observed error status (optionally with the body's error code) for a route.
Resolves the concrete request path back to the spec template path
(e.g., /api/accounts/abc → /api/accounts/:id). When code is provided,
it is stored alongside the status for per-code coverage tracking.

type (route_specs: RouteSpec[], method: string, path: string, status: number, code?: string | undefined): void

`route_specs`

type RouteSpec[]

`method`

type string

`path`

request path (may be concrete)

type string

`status`

type number

`code?`

observed body error code (pass when the route's error
schema declares specific codes via z.literal or z.enum)

type string | undefined

optional

returns void

`assert_and_record`

Validate a response against its route spec and record the status.
Wraps assert_response_matches_spec and records the status code. For
error responses, auto-extracts body.error from the JSON body (via a
cloned response, so the original stream stays usable) and records it
for per-code coverage. Pass an explicit code to override the
auto-extracted value or when the body was already consumed.

type (route_specs: RouteSpec[], method: string, path: string, response: Response, code?: string | undefined): Promise<void>

`route_specs`

type RouteSpec[]

`method`

type string

`path`

type string

`response`

type Response

`code?`

observed body error code (override; if omitted and the
response body is a JSON object with a string error field, that value
is auto-extracted)

type string | undefined

optional

returns Promise<void>

throws

Error - if the response body fails the route spec's declared

`uncovered`

Find declared error paths that were never observed.
Computes the declared set from merge_error_schemas for each route spec.
For statuses whose error schema names specific codes (via z.literal or
z.enum), reports per-code rows; otherwise reports one row per status.
A status-only observation (no code) satisfies all declared codes for that
status — the "any-code" rule.

type (route_specs: RouteSpec[], options?: CoverageFilterOptions | undefined): UncoveredEntry[]

`route_specs`

type RouteSpec[]

`options?`

type CoverageFilterOptions | undefined

optional

returns UncoveredEntry[]

ErrorCoverageOptions
#

ErrorCoverageOptions

Options for assert_error_coverage.

inheritance

extends:

CoverageFilterOptions

`min_coverage`

Minimum coverage ratio (0–1). Default 0 (informational only).

type number

ErrorSchemaAuditEntry
#

ErrorSchemaAuditEntry

A single entry in the error schema tightness audit report.

`method`

type string

`route_path`

type string

`status`

type string

`specificity`

type ErrorSchemaSpecificity

`error_codes`

The literal value or enum values, if specific.

type Array<string> | null

ErrorSchemaSpecificity
#

ErrorSchemaSpecificity

Specificity level of an error schema's error field.

ErrorSchemaTightnessOptions
#

ErrorSchemaTightnessOptions

Options for assert_error_schema_tightness.

`min_specificity`

Minimum specificity level. Error schemas below this threshold fail. Default: 'enum'.

type ErrorSchemaSpecificity

`ignore_statuses`

HTTP status codes to skip (e.g., middleware-injected codes).

type Array<number>

`allowlist`

Routes to skip, in 'METHOD /path' format.

type Array<string>

events_to_surface
#

(event_specs: EventSpec[]): AppSurfaceEvent[]

Convert SSE event specs to surface entries.

`event_specs`

type EventSpec[]

returns

AppSurfaceEvent[]

EventSpec
#

EventSpec

Spec for a push event — declares params schema, description, and channel.

`method`

Event method name, used as the JSON-RPC notification method.

type string

`params`

Zod schema for the notification params payload.

type z.ZodType

`description`

Human-readable description for surface output and docs.

type string

`channel`

Channel this event broadcasts on. Omit for cross-channel events.

type string

extract_action_result
#

(event: ActionEvent<string, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">): Result<...>

Pull the terminal Result from an action event.
data.error populated → error path (covers both explicit failed and
the unhandled receive_error / send_error case where no handler was
registered for the error phase). step === 'handled' → success path.

`event`

type

ActionEvent<string, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

returns

Result<{ value: unknown; }, { error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }>

throws

Error - if the event is in a non-terminal state (programming error —

extract_declared_error_codes
#

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): string[] | null

Extract declared error code values from an error response schema.
Recognizes schemas shaped like z.object({error: z.literal(...)}) or
z.object({error: z.enum([...])}) (incl. looseObject/strictObject).
Returns the set of declared code values, or null if the schema doesn't
expose a literal/enum error field (e.g., bare ApiError with z.string()).
Used by coverage reporting to split a single declared status into per-code
rows when the route's error schema names specific codes.

`schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

string[] | null

FakeHonoContextOptions
#

FakeHonoContextOptions

Options for create_fake_hono_context.

`credential_type`

type CredentialType

`role`

A single role to grant via create_test_request_context.

type string

`auth_session_id`

type string | null

`api_token_id`

type string | null

`request_context`

Override the RequestContext outright (for multi-role or custom
account/actor fixtures). Takes precedence over role.

type RequestContext

FakeWs
#

FakeWs

A WSContext paired with capture arrays. Use sends to assert on
outgoing frames; use closes to assert on revocation / close.

`ws`

type WSContext

`sends`

type Array<string>

`closes`

type Array<{code?: number; reason?: string}>

FetchDeps
#

FetchDeps

HTTP fetch capability.

`fetch`

Fetch a URL. Same signature as the global fetch.

type typeof globalThis.fetch

filter_authenticated_routes
#

(surface: AppSurface): (AppSurfaceRoute & { auth: { type: "authenticated"; }; })[]

Filter routes that require basic authentication (no specific role).

`surface`

type AppSurface

returns

(AppSurfaceRoute & { auth: { type: "authenticated"; }; })[]

filter_keeper_routes
#

(surface: AppSurface): (AppSurfaceRoute & { auth: { type: "keeper"; }; })[]

Filter routes that require keeper credentials.

`surface`

type AppSurface

returns

(AppSurfaceRoute & { auth: { type: "keeper"; }; })[]

filter_mutation_routes
#

(surface: AppSurface): AppSurfaceRoute[]

Filter routes that are mutations (POST, PUT, DELETE, PATCH).

`surface`

type AppSurface

returns

AppSurfaceRoute[]

filter_protected_routes
#

(surface: AppSurface): AppSurfaceRoute[]

Filter routes that require any form of authentication.

`surface`

type AppSurface

returns

AppSurfaceRoute[]

filter_public_routes
#

(surface: AppSurface): AppSurfaceRoute[]

Filter routes that are publicly accessible (no auth).

`surface`

type AppSurface

returns

AppSurfaceRoute[]

filter_rate_limited_routes
#

(surface: AppSurface): AppSurfaceRoute[]

Filter routes that declare rate limiting.

`surface`

type AppSurface

returns

AppSurfaceRoute[]

filter_role_routes
#

(surface: AppSurface): (AppSurfaceRoute & { auth: { type: "role"; role: string; }; })[]

Filter all role-guarded routes (any role).

`surface`

type AppSurface

returns

(AppSurfaceRoute & { auth: { type: "role"; role: string; }; })[]

filter_routes_by_prefix
#

(surface: AppSurface, prefix: string): AppSurfaceRoute[]

Filter routes whose path starts with prefix.

`surface`

type AppSurface

`prefix`

type string

returns

AppSurfaceRoute[]

filter_routes_for_role
#

(surface: AppSurface, role: string): (AppSurfaceRoute & { auth: { type: "role"; role: string; }; })[]

Filter routes that require a specific named role.

`surface`

type AppSurface

`role`

type string

returns

(AppSurfaceRoute & { auth: { type: "role"; role: string; }; })[]

filter_routes_with_input
#

(surface: AppSurface): AppSurfaceRoute[]

Filter routes that have a non-null input schema.

`surface`

type AppSurface

returns

AppSurfaceRoute[]

filter_routes_with_params
#

(surface: AppSurface): AppSurfaceRoute[]

Filter routes that have a non-null params schema.

`surface`

type AppSurface

returns

AppSurfaceRoute[]

filter_routes_with_query
#

(surface: AppSurface): AppSurfaceRoute[]

Filter routes that have a non-null query schema.

`surface`

type AppSurface

returns

AppSurfaceRoute[]

FilterableBroadcastTransport
#

FilterableBroadcastTransport

Structural capability for transports that can broadcast with a
per-connection ACL predicate. Named separately from Transport so the
broadcast API can feature-detect without importing a concrete class.
ConnectionIdentity is the auth-gated identity shape used today. When a
second implementation (e.g. SSE backend transport) lands with a
different identity, consider parameterizing on TIdentity.

inheritance

extends:

Transport

`broadcast_filtered`

type

(
		message: JsonrpcMessageFromServerToClient,
		predicate: (identity: ConnectionIdentity) => boolean,
	) => number

find_auth_route
#

(specs: RouteSpec[], suffix: "/login" | "/logout" | "/password" | "/verify" | "/signup" | "/bootstrap", method: RouteMethod): RouteSpec | undefined

Find a REST auth route by suffix and method.
Decouples tests from consumer route prefix (/api/account/login,
/api/auth/login, etc.). suffix must be one of
REST_AUTH_ROUTE_SUFFIXES — throws otherwise so a post-migration RPC
method name (e.g. /sessions/revoke-all) fails loudly at the call site
instead of silently returning undefined.

`specs`

type RouteSpec[]

`suffix`

`method`

type RouteMethod

returns

RouteSpec | undefined

throws

Error - if `suffix` is not in `REST_AUTH_ROUTE_SUFFIXES`.

find_route_spec
#

(specs: RouteSpec[], method: string, path: string): RouteSpec | undefined

Find a route spec matching the given method and path.
Supports both exact matches and parameterized paths (:param segments).

`specs`

type RouteSpec[]

`method`

type string

`path`

request path (exact or with concrete param values)

type string

returns

RouteSpec | undefined

find_rpc_action
#

(rpc_endpoints: readonly RpcEndpointSpec[], method: string): { path: string; action: RpcAction; } | undefined

Find the RpcAction for a method within a set of RPC endpoint specs.
Returns both the endpoint path and the matched action. undefined when
the method is not registered.

`rpc_endpoints`

type readonly RpcEndpointSpec[]

`method`

type string

returns

{ path: string; action: RpcAction; } | undefined

find_rpc_method
#

(rpc_endpoints: readonly AppSurfaceRpcEndpoint[], method: string): { path: string; method_spec: AppSurfaceRpcMethod; } | undefined

Find the generated surface entry for a method — the shape returned by
generate_app_surface (JSON-serializable, useful for schema assertions
at the boundary of a consumer test).

`rpc_endpoints`

type readonly AppSurfaceRpcEndpoint[]

`method`

type string

returns

{ path: string; method_spec: AppSurfaceRpcMethod; } | undefined

ForeignKeyError
#

ZodObject<{ error: ZodLiteral<"foreign_key_violation">; }, $loose>

Foreign key violation error — returned when a delete is blocked by references.

format_arg_name
#

(prop: ZodSchemaProperty): string

Format argument name with short aliases for display.
Only single-char aliases are shown (e.g., -h, --help).
Flags use snake_case (e.g., --env_file, --detect_only).

`prop`

schema property

type ZodSchemaProperty

returns

string

formatted name string

format_audit_metadata
#

(event_type: string, metadata: Record<string, unknown> | null): string

Format audit event metadata for display based on event type.

`event_type`

builtin or consumer-registered audit event type

type string

`metadata`

type Record<string, unknown> | null

returns

string

format_datetime_local
#

(timestamp: string | number | Date): string

Format a timestamp as an absolute datetime string for title attributes.

`timestamp`

type string | number | Date

returns

string

readable absolute datetime like "2026-03-21 14:30:00 UTC"

format_db_status
#

(status: DbStatus): string

Format a DbStatus as a human-readable string for CLI output.

`status`

the status to format

type DbStatus

returns

string

multi-line string suitable for console output

format_env_display_value
#

env/mask.ts view source

(value: unknown, secret: boolean): string

Format an env value for display, masking secrets.

`value`

the env value to format

type unknown

`secret`

whether the value is secret and should be masked

type boolean

returns

string

display string — masked placeholder for secrets, string values as-is, non-strings JSON-stringified

format_missing_env_vars
#

(missing: EnvVarRef[], options?: FormatMissingEnvVarsOptions | undefined): string

Format missing env vars error message.
Groups refs by variable name so each missing var is shown once
with all paths where it's referenced.

`missing`

missing env var references (may contain duplicate names)

type EnvVarRef[]

`options?`

formatting options

type FormatMissingEnvVarsOptions | undefined

optional

returns

string

formatted error message for display

format_relative_time
#

(timestamp: string | number | Date, now?: number): string

Format a timestamp as a relative time string.

`timestamp`

type string | number | Date

`now`

type number

default Date.now()

returns

string

human-friendly relative time (e.g. "2m ago", "3h ago", "5d ago", "2mo ago", "1y ago")

format_route_key
#

(route: AppSurfaceRoute): string

Format a route as 'METHOD /path' (e.g. 'GET /health').

`route`

type AppSurfaceRoute

returns

string

format_scope_context
#

{ get: () => () => FormatScope; set: (value?: (() => FormatScope) | undefined) => () => FormatScope; }

Svelte context carrying a getter for the consumer's FormatScope.
Provisioned by provide_admin_rpc_contexts from its format_scope option.
Default getter returns default_format_scope so unprovisioned trees render
the raw uuid.

format_uptime
#

(ms: number): string

Format milliseconds as a human-friendly uptime string.

`ms`

type number

returns

string

human-friendly duration (e.g. "45s", "12m", "3h 15m", "2d 5h")

format_value
#

(value: unknown): string

Format an arbitrary value for table cell display.

`value`

type unknown

returns

string

FormatMissingEnvVarsOptions
#

FormatMissingEnvVarsOptions

Options for format_missing_env_vars.

`env_file`

Path to env file if one was loaded.

type string

`setup_hint`

Hint text for how to set up the environment.

type string

FormatScope
#

ui/form_state.svelte.ts view source

FormatScope

Render a {scope_id, role} pair as a human label. Return null to fall
back to the raw scope uuid (or a caller-chosen global_label when
scope_id is null).
Returning null for unknown scope ids (stale cache, revoked resource) is
the recommended pattern — components show the raw uuid rather than a
misleading blank.

FormState
#

`form`

Creates a form attachment that handles Enter key advancing between
focusable elements and tracks field touched state via delegated focusout.
Fields are identified by their name attribute.

type (): Attachment<HTMLFormElement>

returns Attachment<HTMLFormElement>

throws

Error - in DEV when called while already attached, or when an

`is_touched`

Whether a field has been blurred at least once.

type (field: string): boolean

`field`

type string

returns boolean

`show`

Whether to show validation errors for a field.
Returns true if the field has been blurred or a submit attempt was made.

type (field: string): boolean

`field`

type string

returns boolean

`touch`

Programmatically marks a field as touched without requiring a blur event.

type (field: string): void

`field`

type string

returns void

`focus`

Focuses the named input within the form.

type (field: string): void

`field`

type string

returns void

`attempt`

Marks the form as having been submitted, causing all field errors to show.

type (): void

returns void

`reset`

Resets all touched and attempted state.

type (): void

returns void

FrontendHttpTransport
#

actions/transports_http.ts view source

Thin fetch adapter for the JSON-RPC endpoint. POST by default; GET when
the optional has_side_effects(method) callback returns false for the
method (matches create_rpc_endpoint's GET convention). On non-OK HTTP
responses, synthesizes a JSON-RPC error envelope via
http_status_to_jsonrpc_error_code. Always reports ready.

inheritance

implements:

Transport

`transport_name`

readonly

`constructor`

type new (url: string, headers?: Record<string, string> | undefined, has_side_effects?: ((method: string) => boolean) | undefined): FrontendHttpTransport

`url`

type string

`headers?`

type Record<string, string> | undefined

optional

`has_side_effects?`

type ((method: string) => boolean) | undefined

optional

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`is_ready`

type (): boolean

returns boolean

FrontendRpcClient
#

actions/frontend_rpc_client.ts view source

FrontendRpcClient<TApi>

Bundle returned by create_frontend_rpc_client.

generics

`TApi`

`api`

Typed throwing Proxy. await api.method(input) returns the unwrapped
value or throws an Error with {code, data} from the JSON-RPC
error. Default for call sites that don't inspect errors.

type ThrowingApi<TApi>

`api_result`

Typed Result-shaped Proxy. await api_result.method(input) returns
Result<{value}, {error: JsonrpcErrorObject}>. Use when call sites
inspect error.data.reason without try/catch, or when Error
allocation per {ok: false} would be wasteful.

type TApi

`peer`

Underlying peer — exposed for consumers that need to register more transports or send raw messages.

type ActionPeer

`environment`

Action environment — exposed for consumers that need to share it (e.g. attach a notification handler registry).

FrontendWebsocketClient
#

Reactive WebSocket client implementing WebsocketConnection.
Construct with a URL and optional config; call connect() to open the
socket and begin auto-reconnect. Register message/error handlers via
add_message_handler / add_error_handler — both return unsubscribe
functions. FrontendWebsocketTransport consumes this as its connection.
Session-revocation close codes (WS_CLOSE_SESSION_REVOKED) put the client
in a permanently-closed state; reconnecting would just loop on 401.

inheritance

implements:

WebsocketConnection
Disposable

`ws`

type WebSocket | null

`status`

type SocketStatus

`reconnect_count`

type number

`current_reconnect_delay`

type number

`last_connect_time`

Epoch ms of the most recent successful open. Never cleared on close.

type number | null

`last_close_time`

Epoch ms of the most recent close event or client-initiated close.

type number | null

`last_close_code`

Close code from the most recent close. Initial null means "never closed."

type number | null

`last_close_reason`

Reason string from the most recent close event (may be empty).

type string | null

`last_send_error`

The error thrown by the most recent attempted send(), or null if the
most recent attempt succeeded or none has been attempted yet. Populated
when the underlying ws.send throws (e.g., buffer full, serialization
error); reset to null on the next successful send. Not touched when
send() short-circuits because the socket is not connected — consult
connected for that case. Wrappers surfacing per-message failure
reasons can read this after a false return from send().

type Error | null

`connected`

type boolean

readonly

`constructor`

type new (url: string, options?: FrontendWebsocketClientOptions): FrontendWebsocketClient

`url`

type string

`options`

type FrontendWebsocketClientOptions

default {}

`set_reconnect`

Swap the auto-reconnect policy in place. Accepts the same shape as the
constructor's reconnect option: false disables reconnect, true or
null/omitted restores the defaults, or a config object customizes
specific fields (missing fields fall back to defaults, not "keep
current" — each call defines the whole policy atomically, same as the
constructor).
In-flight reconnect schedules are monotonically shortened: the
effective total wait from arm-time never exceeds what the new policy
prescribes. If the new target is already past the time already
elapsed, the reconnect fires immediately (on the next tick). The wait
is never extended.
Turning reconnect off while a reconnect timer is pending cancels that
timer and transitions status to closed (since the lie of
'reconnecting' would be visible to UI indicators). Turning it back on
does not synthesize a reconnect — wait for the next close.

type (reconnect?: boolean | FrontendWebsocketReconnectOptions | null): void

`reconnect`

type boolean | FrontendWebsocketReconnectOptions | null

default null

returns void

`set_heartbeat`

Swap the heartbeat policy in place. Accepts the same shape as the
constructor's heartbeat option: false disables the timer, true or
null/omitted restores the defaults, or a config object customizes
specific fields (missing fields fall back to defaults, not "keep
current" — each call defines the whole policy atomically, same as the
constructor and set_reconnect).
When connected, the live timer is restarted immediately so the new
interval / receive_timeout take effect without a reconnect; when
disconnected, just stashes the policy for the next open.

type (heartbeat?: boolean | FrontendWebsocketHeartbeatOptions | null): void

`heartbeat`

type boolean | FrontendWebsocketHeartbeatOptions | null

default null

returns void

`cancel_reconnect`

Cancel a scheduled reconnect without closing the client or disabling
auto-reconnect. Transitions status from reconnecting → closed and
resets the backoff counters — the next close still triggers a fresh
reconnect cycle under the current policy. No-op when no reconnect is
pending.
Use this when UI state asks "stop trying for now" without the finality
of disconnect (which also rejects pending/queued requests and
clears heartbeat) or the policy change of set_reconnect(false)
(which disables future reconnects). The queue stays intact so that
calling connect later flushes buffered work.

type (): void

returns void

`connect`

Open the WebSocket. No-op on SSR, or if the session has been revoked.
Cancels any pending reconnect and tears down any existing connection first;
an open prior socket is closed with a normal-closure code.

type (): void

returns void

`disconnect`

Close the WebSocket, cancel any pending reconnect, and reset the reconnect
backoff counters. Puts the client in closed status; call connect() to
reopen. Safe to call more than once.

type (code?: number): void

`code`

type number

default DEFAULT_CLOSE_CODE

returns void

`[Symbol.dispose]`

Explicit-resource-management hook — supports using client = new FrontendWebsocketClient(url).

type (): void

returns void

`send`

type (data: object): boolean

`data`

type object

returns boolean

`request`

Promise-based JSON-RPC over the socket. Auto-assigns a monotonic request
id (or uses an explicit one supplied via options.id — used by
FrontendWebsocketTransport which delegates to this method and has its
own peer-minted UUID), tracks the pending promise, and resolves when the
server sends a matching response.
Callers supplying an explicit options.id are responsible for
uniqueness — the pending map is keyed by id, and a duplicate silently
overwrites the prior entry. Auto-minted ids are monotonic and never
collide with themselves or with peer-minted UUIDs (the types differ:
integer vs string).
While the socket is disconnected, the request is buffered in a bounded
queue (default-on, DEFAULT_QUEUE_MAX_SIZE) and flushed on reopen. Pass
{queue: false} to reject immediately when disconnected — used
internally by the heartbeat, which must not fight the queue for the
disconnect-detection slot.
On AbortSignal fire: rejects the local promise *and* sends the shared
cancel notification (cancel_action_spec.method) so the server-side
dispatcher can abort the matching handler's ctx.signal. Suppressed
for queued-but-never-sent (server doesn't know about it) and
response-beat-cancel races.

type <R = unknown>(method: string, params?: unknown, options?: { signal?: AbortSignal | undefined; queue?: boolean | undefined; id?: string | number | undefined; }): Promise<R>

`method`

type string

`params`

type unknown

default {}

`options`

type { signal?: AbortSignal | undefined; queue?: boolean | undefined; id?: string | number | undefined; }

default {}

returns Promise<R>

throws

ThrownJsonrpcError - on the returned promise — never thrown

`add_message_handler`

type (handler: SocketMessageHandler): () => void

`handler`

type SocketMessageHandler

returns () => void

`add_error_handler`

type (handler: SocketErrorHandler): () => void

`handler`

type SocketErrorHandler

returns () => void

FrontendWebsocketClientOptions
#

FrontendWebsocketClientOptions

`reconnect`

Auto-reconnect policy. false disables reconnect entirely; true or
omit for default timing; pass an object to customize.

type boolean | FrontendWebsocketReconnectOptions | null

`heartbeat`

Activity-aware heartbeat. true/null/omit for defaults; false disables
the timer entirely (only do this if the server side is also running
without heartbeat); pass an object to tune interval / receive_timeout.

type boolean | FrontendWebsocketHeartbeatOptions | null

`queue`

Durable queue for FrontendWebsocketClient.request. true or omit
for defaults; false disables buffering (requests while disconnected
reject immediately). Raw FrontendWebsocketClient.send is never
queued — use request() for RPC semantics.

type boolean | FrontendWebsocketQueueOptions

`log`

Optional logger for diagnostic messages.

type Logger | null

FrontendWebsocketHeartbeatOptions
#

FrontendWebsocketHeartbeatOptions

`interval`

Idle duration (ms) after which a heartbeat is sent. Reset by any send or
receive — chatty clients never emit extras. Defaults to
DEFAULT_HEARTBEAT_INTERVAL.

type number

`receive_timeout`

Receive-silence (ms) after which the client closes the socket with
WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, letting auto-reconnect kick
in. Should be a comfortable multiple of interval. Defaults to
DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT.

type number

FrontendWebsocketQueueOptions
#

FrontendWebsocketQueueOptions

`max_size`

Maximum number of requests held while the socket is disconnected.
Enqueue past this rejects the new call with a queue_overflow error.
Defaults to DEFAULT_QUEUE_MAX_SIZE.

type number

FrontendWebsocketReconnectOptions
#

actions/transports_ws.ts view source

FrontendWebsocketReconnectOptions

`delay`

Base reconnect delay in ms. Defaults to 1000.

type number

`delay_max`

Max reconnect delay in ms (cap on exponential backoff). Defaults to 10000.

type number

`factor`

Exponential backoff factor. Defaults to 1.5.

type number

FrontendWebsocketTransport
#

Thin adapter over WebsocketRpcConnection (canonical implementation:
FrontendWebsocketClient). Routes inbound server-pushed requests and
notifications into the supplied receive callback; responses are owned
by the connection's own request() pending map and are ignored here.

inheritance

implements:

Transport

`transport_name`

readonly

`constructor`

type new (connection: WebsocketRpcConnection, receive: (data: unknown) => Promise<unknown>): FrontendWebsocketTransport

`connection`

type WebsocketRpcConnection

`receive`

type (data: unknown) => Promise<unknown>

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`send`

`message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

`options?`

type TransportSendOptions | undefined

optional

returns

Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; };...

`is_ready`

type (): boolean

returns boolean

`dispose`

Detach the inbound message and error handlers registered on the
connection. Idempotent — subsequent calls no-op. Does not close the
underlying connection (that lifecycle is owned by the caller).

type (): void

returns void

FsReadDeps
#

FsReadDeps

File system read operations.

`stat`

Get file/directory stats, or null if path doesn't exist.

type (path: string) => Promise<StatResult | null>

`read_text_file`

Read a file as text. Throws if the file does not exist.

type (path: string) => Promise<string>

`read_file`

Read a file as bytes. Throws if the file does not exist.

type (path: string) => Promise<Uint8Array>

`read_text_from_offset`

Read text starting from a byte offset. Throws if the file does not exist.
Returns content, bytes_read, and file_size so callers can detect
truncation (when file_size < offset) and tail incrementally without
re-reading the whole file.

type (path: string, offset: number) => Promise<ReadTextFromOffsetResult>

`readdir`

List directory entries (names, not full paths). Throws if the directory does not exist.

type (path: string) => Promise<Array<string>>

FsRemoveDeps
#

FsRemoveDeps

File system remove operations.

`remove`

Remove a file or directory.

type (path: string, options?: {recursive?: boolean}) => Promise<void>

FsWriteDeps
#

FsWriteDeps

File system write operations.

`mkdir`

Create a directory.

type (path: string, options?: {recursive?: boolean}) => Promise<void>

`write_text_file`

Write text to a file.

type (path: string, content: string) => Promise<void>

`write_file`

Write bytes to a file.

type (path: string, data: Uint8Array) => Promise<void>

`rename`

Rename (move) a file.

type (old_path: string, new_path: string) => Promise<void>

FUZ_APP_STOCK_ROUTE_TIGHTNESS_ALLOWLIST
#

auth/route_guards.ts view source

readonly string[]

Routes shipped by fuz_app whose error schemas require a tightness exemption.
Currently empty — every fuz_app-shipped route (account login/password/
bootstrap/signup, db health/tables/:name/tables/:name/rows/:id) was tightened
in place to z.enum([...]) / z.literal(...) against every emit-site error
code.
Kept as a forward-compatibility hook: when new stock routes ship with
heterogeneous error surfaces that need an interim generic schema, add
them here instead of forcing every consumer to hand-maintain the entry.
Paths assume the standard /api/account + /api/db prefixes used by every
fuz_app consumer. Merged into DEFAULT_ERROR_SCHEMA_TIGHTNESS.allowlist so
consumers calling assert_error_schema_tightness directly inherit the
exemptions; the standard attack-surface suite also prepends these entries
underneath any consumer-supplied allowlist so project-specific entries are
additive.

fuz_auth_guard_resolver
#

(auth: RouteAuth): MiddlewareHandler[]

Standard auth guard resolver for fuz_app.
Maps RouteAuth to middleware:
- none → no guards
- authenticated → require_auth
- role → require_role(role)
- keeper → require_keeper

`auth`

type RouteAuth

returns

MiddlewareHandler[]

fuz_session_config
#

SessionOptions<string>

Canonical session config for fuz_app auth.

generate_action_event_datas
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options?: { ...; } | undefined): string

Emit the ActionEventDatas interface — one ActionEvent*Data variant per
method, parameterized by the spec's kind:
- request_response → ActionEventRequestResponseData<method, input, output>
- remote_notification → ActionEventRemoteNotificationData<method, input>
- local_call → ActionEventLocalCallData<method, input, output>
Adds the per-kind data type imports (only the kinds that appear in specs).

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options?`

type

{ same_file?: boolean | undefined; collections_path?: string | undefined; include_protocol_actions?: boolean | undefined; } | undefined

optional

returns

string

generate_action_inputs_outputs
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options?: { ...; } | undefined): string

Emit ActionInputs + ActionOutputs runtime consts and matching interfaces.
The runtime consts reference specs.{method}_action_spec.input /
.output; the interfaces use z.infer.
Adds import {z} from 'zod'; and the * as specs namespace import.

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options?`

type

{ specs_module?: string | undefined; qualify_spec?: ((spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }) => string)...

optional

returns

string

generate_action_method_enum_block
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options: { ...; }): string

Emit a single named z.enum([...]) + z.infer block for an arbitrary
spec subset. Lower-level escape hatch from generate_action_method_enums —
for cross-product or domain-specific enums the built-in discriminator
doesn't cover.
Mirrors the built-in helper's contract: protocol actions filtered by
default, empty subsets return '' (skip rather than emit z.enum([])),
zod import registered idempotently only when at least one method
qualifies.
The cross-product space is open-ended; rather than grow the
ActionMethodEnumKind discriminator one cross-product at a time, callers
own the subset shape — name, jsdoc, predicate.

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options`

type

{ name: string; jsdoc: string; predicate: (spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }) => boolean; include_p...

returns

string

generate_action_method_enums
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options?: { ...; } | undefined): string

Emit one or more z.enum([...]) declarations for action method names —
ActionMethod, RequestResponseActionMethod, RemoteNotificationActionMethod,
LocalCallActionMethod, FrontendActionMethod, BackendActionMethod,
FrontendRequestResponseMethod, BackendRequestResponseMethod,
BroadcastActionMethod. Pairs each runtime const with a z.infer type
alias under the same identifier.
Protocol-action methods (heartbeat, cancel) are filtered out by
default — pass include_protocol_actions: true if a consumer genuinely
wants them on their typed surface. Empty kinds are skipped so the helper
never emits z.enum([]) (zod runtime-throws on that).
Adds import {z} from 'zod'; to imports only when at least one block
is emitted (idempotent).
For genuinely cross-product enums the discriminator doesn't cover, use
generate_action_method_enum_block — caller owns the predicate, name,
and jsdoc.

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options?`

type { emit?: ReadonlySet<ActionMethodEnumKind> | undefined; include_protocol_actions?: boolean | undefined; } | undefined

optional

returns

string

generate_action_specs_record
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options?: { ...; } | undefined): string

Emit the ActionSpecs runtime const + interface + the `action_specs:
Array<ActionSpecUnion> value bundling every spec. Adds the * as specs`
namespace import + the ActionSpecUnion type import.

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options?`

type

{ specs_module?: string | undefined; qualify_spec?: ((spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }) => string)...

optional

returns

string

generate_actions_api_method_signature
#

(spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }, imports: ImportBuilder, options?: { ...; } | undefined): string

Generates one method line of the typed FrontendActionsApi interface for a
single spec. Encapsulates the input/options/return-type signature shape so
the surface evolves in one place when fields like signal or
transport_name are added to per-call options.
Async methods (request_response, remote_notification, async
local_call) get an optional second options?: RpcClientCallOptions arg
({signal?, transport_name?, queue?}) and a Promise<Result<...>> return
type. Sync local_call methods omit the options arg — signal can't
cooperatively interrupt a synchronous handler and there's no transport to
select. remote_notification is async because
create_remote_notification_method returns a Promise that resolves to a
Result<{value: void}> (success) or Result<{error}> (transport send
failure). Earlier emit shapes declared notifications as => void —
regenerate consumer typed clients to pick up the corrected return.
Registers exactly the imports the emitted line references on imports:
ActionInputs (when the spec has input), ActionOutputs (always),
RpcClientCallOptions (async only), and Result + JsonrpcErrorObject
(any return shape that wraps the value in Result<{value}, {error}> —
every async method, plus sync local_call when `sync_returns_value:
false). Mirrors the leaf-level pattern get_handler_return_type` already
follows so wrappers no longer pre-register imports a per-spec emit might
not actually use.

`spec`

type

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

`imports`

type ImportBuilder

`options?`

type { sync_returns_value?: boolean | undefined; collections_path?: string | undefined; } | undefined

optional

returns

string

one line like foo: (input: ActionInputs['foo'], options?: RpcClientCallOptions) => Promise<Result<...>>;

generate_api_token
#

(): { token: string; id: string; token_hash: string; }

Generate a new API token with its hash and public id.
The raw token is returned exactly once — callers must present it
to the user immediately.

returns

{ token: string; id: string; token_hash: string; }

the raw token, a public id, and the blake3 hash for storage

generate_app_surface
#

(options: GenerateAppSurfaceOptions): AppSurface

Generate a JSON-serializable attack surface from middleware, route specs,
and optional env/event metadata.

`options`

type GenerateAppSurfaceOptions

returns

AppSurface

generate_backend_action_handlers_map
#

(imports: ImportBuilder, options?: { type_name?: string | undefined; method_enum_name?: string | undefined; context_type?: string | undefined; collections_path?: string | undefined; metatypes_path?: string | undefined; } | undefined): string

Emit the BackendActionHandlers mapped type — one entry per
BackendRequestResponseMethod, each (input, ctx) => output | Promise<output>.
Replaces the hand-maintained Exclude<> + parallel mapped-type pattern
(zzz had this at zzz/src/lib/server/zzz_action_handlers.ts:42-66).
The context type is consumer-defined (e.g. zzz's ZzzHandlerContext). Pass
context_type to name it; the helper assumes it's importable or defined
in the emitted module's scope (consumer's responsibility).
Adds ActionInputs / ActionOutputs type imports from collections_path
and the BackendRequestResponseMethod import from metatypes_path.

`imports`

type ImportBuilder

`options?`

type

{ type_name?: string | undefined; method_enum_name?: string | undefined; context_type?: string | undefined; collections_path?: string | undefined; metatypes_path?: string | undefined; } | undefined

optional

returns

string

generate_backend_actions_api
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options?: { ...; } | undefined): string

Emit BOTH the typed BackendActionsApi interface AND the
broadcast_action_specs runtime array. The interface is shaped for
create_broadcast_api: backend-initiated remote_notification methods,
each (input) => Promise<void>. The array bundles the matching specs as a
ReadonlyArray<ActionSpecUnion>.
Filter: kind === 'remote_notification' && initiator !== 'frontend',
additionally excluding methods that are the target of another spec's
streams field. Streams targets (e.g. completion_progress,
ollama_progress) are request-scoped notifications invoked via
ctx.notify inside their parent handler — they're never callable through
the broadcast API. The discriminator is ActionSpec.streams, not a manual
exclusion list.
Adds the * as specs namespace import (from specs_module), the
ActionInputs type import (from collections_path), and the
ActionSpecUnion type import.
Method signature shape today is (input) => Promise<void> — matches the
fire-and-forget runtime of create_broadcast_api. Generalizing per-kind
via generate_actions_api_method_signature is deferred until a second
backend runtime constructor lands.

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options?`

type

{ specs_module?: string | undefined; collections_path?: string | undefined; qualify_spec?: ((spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; ... 8 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }) => string) | undefined; include_protocol_a...

optional

returns

string

generate_daemon_token
#

(): string

Generate a new daemon token (256-bit random, base64url).

returns

string

a 43-character base64url string

generate_frontend_action_handlers
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options?: { ...; } | undefined): string

Emit the FrontendActionHandlers interface — wraps generate_phase_handlers
with the TypedActionEvent action-event type and standard 1-tab per-method
indentation. Pairs with generate_typed_action_event_alias (emits the
matching TypedActionEvent alias) — call both in the same gen producer.

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options?`

type { collections_path?: string | undefined; include_protocol_actions?: boolean | undefined; } | undefined

optional

returns

string

generate_frontend_actions_api
#

(specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[], imports: ImportBuilder, options?: { ...; } | undefined): string

Emit the FrontendActionsApi interface — one method signature per spec via
generate_actions_api_method_signature. Optionally filter the spec set
(e.g. omit additional methods alongside the default protocol-action
filter) via method_filter.
Imports are registered by the leaf generate_actions_api_method_signature
per emitted line — only what the spec set actually references shows up on
imports. A spec set with no async methods skips RpcClientCallOptions;
one with no inputs skips ActionInputs; sync local_call methods with
sync_returns_value: true (the default) skip Result / JsonrpcErrorObject.
The interface name is fixed at FrontendActionsApi — the symmetric counterpart
of BackendActionsApi. Earlier consumer-named variants (MyActionsApi,
VisionesActionsApi) were retired in API review III to make the side-of-the-wire
intent visible at every call site. If a consumer needs a different name they
hand-roll the interface (the helper's job is the standard symmetric shape).

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`imports`

type ImportBuilder

`options?`

type

{ method_filter?: ((spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }) => boolean) | undefined; collections_path?: ...

optional

returns

string

generate_input_test_cases
#

(input_schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): InputTestCase[]

Generate adversarial test cases for a route's input schema.
Produces focused, non-redundant cases:
- Whole-body: send array instead of object, extra unknown key
- Missing required fields (without defaults)
- One wrong-type value per field
- Null for required non-nullable fields
- One format violation per constrained field

`input_schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

InputTestCase[]

throws

Error - if the seed body built by `generate_valid_value` fails

generate_params_test_cases
#

(params_schema: ZodObject<$ZodLooseShape, $strip>): ParamsTestCase[]

Generate adversarial test cases for a route's params schema.
Params are always strings from URL segments. Only generates cases for
format-constrained fields (uuid, pattern) since unconstrained string
params accept any string value.

`params_schema`

type ZodObject<$ZodLooseShape, $strip>

returns

ParamsTestCase[]

generate_phase_handlers
#

(spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }, executor: "frontend" | "backend", imports: ImportBuilder, options?: { ...; } | undefined): string

Generates the phase handlers for an action spec using the unified ActionEvent type
with the new phase/step type parameters.
Returns '' when the spec contributes no phases on the given executor side
(e.g. a backend-only local_call asked for 'frontend'). Upstream wrappers
compose blocks with .filter(Boolean) so empty entries are dropped from the
generated handler map. The earlier shape was ${method}?: never, which read
as "calling this here is a type error" but in practice produced useless rows
on FrontendActionHandlers for methods that don't belong on this side at
all — drop the row instead so the typed surface only carries methods the
executor actually handles.

`spec`

type

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

`executor`

type "frontend" | "backend"

`imports`

type ImportBuilder

`options?`

type { action_event_type?: string | undefined; collections_path?: string | undefined; } | undefined

optional

returns

string

generate_position_styles
#

(position?: Position, align?: Alignment, offset?: string): Record<string, string>

Generates CSS positioning styles for UI elements.

`position`

type Position

default 'center'

`align`

type Alignment

default 'center'

`offset`

distance from the position (CSS value)

type string

default '0'

returns

Record<string, string>

throws

UnreachableError - if `position` is not a known `Position` value

generate_query_test_cases
#

(query_schema: ZodObject<$ZodLooseShape, $strip>): QueryTestCase[]

Generate adversarial test cases for a route's query schema.
Query params are always strings from the URL. Generates cases for:
- Missing required fields
- Format violations on constrained fields (uuid, pattern)

`query_schema`

type ZodObject<$ZodLooseShape, $strip>

returns

QueryTestCase[]

generate_random_base64url
#

crypto.ts view source

(byte_length?: number): string

Generate a cryptographically random base64url string.

`byte_length`

number of random bytes (default 32 = 256 bits)

type number

default 32

returns

string

base64url-encoded string without padding

generate_random_key
#

(deps: CommandDeps): Promise<string>

Generate a random base64 key using openssl.

`deps`

command execution capability

type CommandDeps

returns

Promise<string>

a random 32-byte base64-encoded key

throws

Error - if `openssl rand` fails or is unavailable

generate_session_token
#

(): string

Generate a cryptographically random session token.

returns

string

a 32-byte base64url-encoded token

generate_typed_action_event_alias
#

(imports: ImportBuilder, options?: { collections_path?: string | undefined; metatypes_path?: string | undefined; } | undefined): string

Emit the fixed-shape TypedActionEvent alias used by FrontendActionHandlers
to narrow ActionEvent.data against the consumer's generated ActionEventDatas
map. Registers the four fuz_app type imports it needs (ActionEvent,
ActionEventPhase, ActionEventStep, ActionEventDatas) plus the
ActionMethod type import — sourced from collections_path and
metatypes_path respectively.
Pair with generate_action_method_enums (emits ActionMethod into
metatypes_path) and generate_action_event_datas (emits
ActionEventDatas into collections_path).

`imports`

type ImportBuilder

`options?`

type { collections_path?: string | undefined; metatypes_path?: string | undefined; } | undefined

optional

returns

string

generate_valid_body
#

(input_schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): Record<string, unknown> | undefined

Generate a valid request body for a route's input schema.

`input_schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

Record<string, unknown> | undefined

a generated body that passes safeParse, or undefined for null /
non-object schemas

throws

Error - if the generated body fails `input_schema.safeParse` — catches

generate_valid_value
#

(field: ZodFieldInfo, field_schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): unknown

Generate a valid-ish value for a field based on its base type.

`field`

type ZodFieldInfo

`field_schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

unknown

GenerateAppSurfaceOptions
#

GenerateAppSurfaceOptions

Options for generate_app_surface.

`route_specs`

type Array<RouteSpec>

`middleware_specs`

type Array<MiddlewareSpec>

`env_schema`

type z.ZodObject

`event_specs`

type Array<EventSpec>

`rpc_endpoints`

type Array<RpcEndpointSpec>

get_app_dir
#

(runtime: Pick<EnvDeps, "env_get">, name: string): string | null

Get the CLI config directory path (~/.{name}).

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`name`

application name (e.g., "tx", "zzz")

type string

returns

string | null

path to config directory, or null if $HOME is not set

get_audit_metadata
#

<T extends AuditEventType>(event: AuditLogEvent & { event_type: T; }): AuditMetadataMap[T] | null

Narrow metadata type for a known event type.
Use after checking event_type to get typed metadata access.

`event`

type AuditLogEvent & { event_type: T; }

returns

AuditMetadataMap[T] | null

get_audit_metadata_validation_failures
#

(): number

Number of audit metadata validation failures observed since process start.

returns

number

get_audit_unknown_event_type_failures
#

(): number

Number of audit unknown-event-type failures observed since process start.

returns

number

get_client_ip
#

(c: Context<any, any, {}>): string

Read the resolved client IP from the Hono context.
Returns 'unknown' if the proxy middleware has not run or no IP is available.
Set by create_proxy_middleware.

`c`

type Context<any, any, {}>

returns

string

get_config_path
#

(runtime: Pick<EnvDeps, "env_get">, name: string): string | null

Get the CLI config file path (~/.{name}/config.json).

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`name`

application name

type string

returns

string | null

path to config.json, or null if $HOME is not set

get_daemon_info_path
#

(runtime: Pick<EnvDeps, "env_get">, name: string): string | null

Get the daemon info file path (~/.{name}/run/daemon.json).

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`name`

application name

type string

returns

string | null

path to daemon.json, or null if $HOME is not set

get_daemon_token_path
#

(runtime: Pick<EnvDeps, "env_get">, name: string): string | null

Get the daemon token file path (~/.{name}/run/daemon_token).

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`name`

application name

type string

returns

string | null

path to daemon_token, or null if $HOME is not set

get_env_var_names
#

(value: string): string[]

Get list of env var names referenced in a string.

`value`

string to scan

type string

returns

string[]

array of variable names (without $$ delimiters)

get_executor_phases
#

(spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }, executor: "frontend" | "backend"): ("send_request" | ... 7 more ... | "execute")[]

Phases an executor can handle for the given spec — kind + initiator → set of phases.

`spec`

type

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

`executor`

type "frontend" | "backend"

returns

("send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute")[]

get_handler_return_type
#

(spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }, phase: "send_request" | ... 7 more ... | "execute", imports: ImportBuilder, collections_path?: string): string

Gets the handler return type for a specific phase and spec. Adds an
ActionOutputs import (from collections_path) when the phase carries an
output (request_response receive_request, local_call execute).

`spec`

type

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

`phase`

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"

`imports`

type ImportBuilder

`collections_path`

type string

default DEFAULT_COLLECTIONS_PATH

returns

string

get_initial_phase
#

(kind: "request_response" | "remote_notification" | "local_call", initiator: "frontend" | "backend" | "both", executor: "frontend" | "backend"): "send_request" | "receive_request" | ... 7 more ... | null

`kind`

type "request_response" | "remote_notification" | "local_call"

`initiator`

type "frontend" | "backend" | "both"

`executor`

type "frontend" | "backend"

returns

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute" | null

get_request_context
#

(c: Context<any, any, {}>): RequestContext | null

Get the request context from a Hono context, or null if unauthenticated.

`c`

the Hono context

type Context<any, any, {}>

returns

RequestContext | null

the request context, or null

get_route_error_schema
#

(lookup: Map<string, Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>, route: AppSurfaceRoute, status: number): ZodType<...> | undefined

Look up the merged error schema for a route+status from a pre-built schema lookup.

`lookup`

map from "METHOD /path" to merged error schemas

type Map<string, Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>>

`route`

the surface route to look up

type AppSurfaceRoute

`status`

HTTP status code

type number

returns

ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined

the Zod schema for that route+status, or undefined when no error
schema is declared for the status code

get_route_input
#

<T>(c: Context<any, any, {}>): T

Get validated input from the Hono context.
Call after the input validation middleware has run. The type parameter
should match the route's input schema.

`c`

type Context<any, any, {}>

returns

T

get_route_params
#

<T>(c: Context<any, any, {}>): T

Get validated URL path params from the Hono context.
Call after the params validation middleware has run. The type parameter
should match the route's params schema.
TODO derive T from the route spec so the type parameter isn't manually
specified — same applies to get_route_input / get_route_query.

`c`

type Context<any, any, {}>

returns

T

get_route_query
#

<T>(c: Context<any, any, {}>): T

Get validated URL query params from the Hono context.
Call after the query validation middleware has run. The type parameter
should match the route's query schema.

`c`

type Context<any, any, {}>

returns

T

get_session_cookie
#

<T>(c: Context<any, any, {}>, options: SessionOptions<T>): string | undefined

Read the session cookie value from a request.

`c`

type Context<any, any, {}>

`options`

type SessionOptions<T>

returns

string | undefined

GrantPermitInput
#

GrantPermitInput

`actor_id`

type Uuid

`role`

type string

`scope_id`

Scope the grant applies to. null / omitted grants a global permit.

type Uuid | null

`expires_at`

type Date | null

`granted_by`

type Uuid | null

`source_offer_id`

Offer id that produced this permit. Set by query_accept_offer; leave unset for direct grants.

type Uuid | null

has_any_scoped_role
#

(ctx: RequestContext | null, roles: readonly string[], scope_id: string | null, now?: Date): boolean

Whether the request context holds an active permit for any role in roles
at scope_id. Empty roles short-circuits to false — documents intent
at the call site ("zero roles trivially admit no-one"). Same scope and
null-tolerance semantics as has_scoped_role.

`ctx`

the request context, or null for unauthenticated callers

type RequestContext | null

`roles`

the roles that would admit the caller (any-of)

type readonly string[]

`scope_id`

the scope to check (null for global)

type string | null

`now`

current time (defaults to new Date(), pass for testability)

type Date

default new Date()

returns

boolean

true iff the actor holds an active permit for any role in roles at the requested scope

has_env_vars
#

(value: string): boolean

Check if a string contains unresolved env var references.

`value`

string to check

type string

returns

boolean

true if string contains $$VAR$$ patterns

has_role
#

(ctx: RequestContext | null, role: string, now?: Date): boolean

Check if a request context has an active permit for a given role.
Checks the permits already loaded in the context (no DB query).
Null-tolerant — null ctx (unauthenticated) returns false. Symmetric
with has_scoped_role / has_any_scoped_role so the three helpers
compose freely in the same predicate (e.g.
has_role(auth, ADMIN) || has_scoped_role(auth, role, scope)).

`ctx`

the request context, or null for unauthenticated callers

type RequestContext | null

`role`

the role to check

type string

`now`

current time (defaults to new Date(), pass for testability and hot-path efficiency)

type Date

default new Date()

returns

boolean

true if the actor has an active permit for the role

has_scoped_role
#

(ctx: RequestContext | null, role: string, scope_id: string | null, now?: Date): boolean

Whether the request context holds an active permit for role at scope_id.
Walks the in-memory ctx.permits snapshot loaded once per request by
create_request_context_middleware; zero DB roundtrip per check. The
"freshness" framing of a SQL re-query is illusory because the race window
is between predicate and the actual mutation, not predicate and middleware
load. Closing that race needs a transactional re-check inside the
UPDATE/INSERT, which neither style provides.
Null-tolerant — null ctx (unauthenticated) returns false. Same
convention as has_role; lets the helper drop into auth: 'public'
handlers without a manual narrow. See cell_authorize for the
resource-side analog.
scope_id semantics: in-memory permit.scope_id is string | null, so
JS === matches the SQL IS NOT DISTINCT FROM semantics exactly:
- scope_id === null matches global permits (scope_id IS NULL).
- scope_id === '<uuid>' matches permits bound to that exact scope.

`ctx`

the request context, or null for unauthenticated callers

type RequestContext | null

`role`

the role to check

type string

`scope_id`

the scope to check (null for global)

type string | null

`now`

current time (defaults to new Date(), pass for testability and hot-path efficiency)

type Date

default new Date()

returns

boolean

true iff the actor holds an active permit for the role at the requested scope

hash_api_token
#

(token: string): string

Hash an API token for storage using blake3.

`token`

the raw API token

type string

returns

string

hex-encoded blake3 hash

hash_password
#

(password: string): Promise<string>

Hash a password using Argon2id.

`password`

the plaintext password to hash

type string

returns

Promise<string>

the Argon2id hash string

hash_session_token
#

actions/heartbeat.ts view source

(token: string): string

Hash a session token to its storage key using blake3.

`token`

the raw session token

type string

returns

string

hex-encoded blake3 hash

heartbeat_action
#

Action<BaseHandlerContext>

Protocol-action tuple — spread into the server's actions array for
dispatch (or via protocol_actions from actions/protocol.ts) so the
dispatcher resolves the heartbeat handler. The frontend-side spread
happens via protocol_action_specs — the client doesn't run the echo
handler, but the spec must be in ActionRegistry so create_rpc_client
types app.api.heartbeat() against the shared spec.

heartbeat_action_spec
#

actions/heartbeat.ts view source

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: false; input: ZodObject<{}, $strict>; output: ZodObject<{}, $strict>; async: true; description: string; }

ActionSpec for the shared heartbeat. authenticated auth — upgrade-time
auth has already admitted the socket; heartbeats don't need role gating.
side_effects: false keeps it orthogonal to state changes.

heartbeat_handler
#

actions/heartbeat.ts view source

(): Record<string, never>

Handler — nullary echo. Stateless, suitable for high-frequency pings.

returns

Record<string, never>

HelpCategory
#

HelpCategory<TCategory>

Category configuration for help display.

generics

`TCategory`

constraint string

default string

`key`

type TCategory

`title`

type string

HelpGenerator
#

HelpGenerator

Help generator returned by create_help.

`generate_main_help`

Generate main help text with all commands grouped by category.

type () => string

`generate_command_help`

Generate help text for a specific command.

type (command: string, meta: CommandMeta) => string

`get_help_text`

Get help text for a command or main help.

type (command?: string, subcommand?: string) => string

HelpOptions
#

HelpOptions<TCategory>

Configuration for create_help.

generics

`TCategory`

constraint string

default string

`name`

Application name (e.g., "tx", "zzz").

type string

`version`

Application version string.

type string

`description`

Short description for the main help header.

type string

`commands`

Command registry keyed by command path (e.g., "apply", "daemon start").

type Record<string, CommandMeta<TCategory>>

`categories`

Category display order for main help.

type Array<HelpCategory<TCategory>>

`examples`

Example commands for main help.

type Array<string>

`global_args_schema`

Zod schema for global arguments (shown in all help output).

type z.ZodType

`use_colors`

Whether to use ANSI colors in output. Defaults to true.

type boolean

http_status_to_jsonrpc_error_code
#

(status: number): -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)

Map an HTTP status code to a JSON-RPC error code.
Returns internal_error (-32603) for unrecognized status codes.

`status`

type number

returns

-32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)

HTTP_STATUS_TO_JSONRPC_ERROR_CODE
#

Record<number, -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)>

Maps HTTP status codes to JSON-RPC error codes (reverse mapping).
When multiple error codes map to the same HTTP status (e.g. parse_error
and invalid_request both map to 400), the last one wins. Use for
best-effort HTTP → JSON-RPC translation.

http_transport
#

(app: { request: (input: string, init: RequestInit) => Response | Promise<Response>; }): RpcTestTransport

Adapt a Hono-style app into an RpcTestTransport.

`app`

type { request: (input: string, init: RequestInit) => Response | Promise<Response>; }

returns

RpcTestTransport

ImportBuilder
#

Manages imports for generated code, building them on demand.
Automatically optimizes type-only imports to use import type syntax.
Why this matters:
- import type statements are completely removed during compilation
- Mixed imports like import { type A, B } cannot be safely removed
- This ensures optimal tree-shaking and smaller bundle sizes

examples

const imports = new ImportBuilder();
imports.add_types('./types.js', 'Foo', 'Bar');
imports.add('./utils.js', 'helper');
imports.add_type('./utils.js', 'HelperOptions');
imports.add('./action_specs.js', '* as specs');

// Generates:
// import type {Foo, Bar} from './types.js';
// import {helper, type HelperOptions} from './utils.js';
// import * as specs from './action_specs.js';

`imports`

type Map<string, Map<string, ImportItem>>

`add`

Add a value import. Accepts * as ns strings as namespace imports.

type (from: string, what: string): this

`from`

type string

`what`

type string

returns this

this for chaining

`add_type`

Add a type-only import.

type (from: string, what: string): this

`from`

type string

`what`

type string

returns this

this for chaining

`add_many`

type (from: string, ...items: string[]): this

`from`

type string

`items`

type string[]

returns this

`add_types`

type (from: string, ...items: string[]): this

`from`

type string

`items`

type string[]

returns this

`build`

Generate the import statements. When every import from a module is a
type, emits import type {…} so the whole statement disappears at
compile time.

type (): string

returns string

`has_imports`

type (): boolean

returns boolean

`preview`

Build the same statement list as build without joining — for inspection in tests.

type (): string[]

returns string[]

`clear`

Clear all imports.

type (): this

returns this

this for chaining

Invite
#

Invite

Invite row from the database.

`id`

type Uuid

`email`

type Email | null

`username`

type Username | null

`claimed_by`

type Uuid | null

`claimed_at`

type string | null

`created_at`

type string

`created_by`

type Uuid | null

invite_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: true; input: ZodObject<{ email: ZodOptional<ZodNullable<ZodEmail>>; username: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; rate_limit: "account"; }

invite_delete_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: true; input: ZodObject<{ invite_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>; output: ZodObject<...>; async: true; description: string; rate_limit: "account"; }

INVITE_INDEXES
#

string[]

invite_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: false; input: ZodVoid; output: ZodObject<{ invites: ZodArray<ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 7 more ...; claimed_by_username: ZodNullable<...>; }, $strict>>; }, $strict>; async: true; de...

INVITE_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS invite (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  email TEXT,\n  username TEXT,\n  claimed_by UUID REFERENCES account(id) ON DELETE SET NULL,\n  claimed_at TIMESTAMPTZ,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  created_by UUID REFERENCES actor(id) ON DELETE SET NU...

InviteCreateInput
#

ZodObject<{ email: ZodOptional<ZodNullable<ZodEmail>>; username: ZodOptional<ZodNullable<ZodString>>; }, $strict>

Input for invite_create. At least one of email / username must be provided.

InviteCreateOutput
#

ZodObject<{ ok: ZodLiteral<true>; invite: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; email: ZodNullable<ZodEmail>; username: ZodNullable<...>; claimed_by: ZodNullable<...>; claimed_at: ZodNullable<...>; created_at: ZodString; created_by: ZodNullable<...>; }, $strict>; }, $strict>

Output for invite_create.

InviteDeleteInput
#

ZodObject<{ invite_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>

Input for invite_delete.

InviteDeleteOutput
#

ZodObject<{ ok: ZodLiteral<true>; }, $strict>

Output for invite_delete.

InviteJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; email: ZodNullable<ZodEmail>; username: ZodNullable<ZodString>; claimed_by: ZodNullable<...>; claimed_at: ZodNullable<...>; created_at: ZodString; created_by: ZodNullable<...>; }, $strict>

Zod schema for client-safe invite data.

InviteListInput
#

ZodVoid

Input for invite_list.

InviteListOutput
#

ZodObject<{ invites: ZodArray<ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; email: ZodNullable<ZodEmail>; username: ZodNullable<ZodString>; ... 5 more ...; claimed_by_username: ZodNullable<...>; }, $strict>>; }, $strict>

Output for invite_list. Uses the enriched row including creator/claimer usernames.

InviteWithUsernamesJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; email: ZodNullable<ZodEmail>; username: ZodNullable<ZodString>; ... 5 more ...; claimed_by_username: ZodNullable<...>; }, $strict>

Zod schema for invite data with resolved creator/claimer usernames.

is_action_complete
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): boolean

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_action_spec
#

(value: unknown): value is { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<...>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

Structural type guard for any ActionSpecUnion variant — checks kind is one of the three known values.

`value`

type unknown

returns

boolean

IS_CI
#

boolean

CI detection — CI=true is set automatically by GitHub Actions, GitLab CI, etc.

is_daemon_running
#

(runtime: CommandDeps, pid: number): Promise<boolean>

Check if a process is running by PID.

`runtime`

runtime with command execution capability

type CommandDeps

`pid`

process ID to check

type number

returns

Promise<boolean>

true if the process is running

is_execute
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ActionEventLocalCallData & { ...; }

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_failed
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is { ...; } & { ...; }

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_filterable_broadcast_transport
#

(transport: Transport): transport is FilterableBroadcastTransport

Type guard for FilterableBroadcastTransport.

`transport`

type Transport

returns

boolean

is_handled
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is { ...; } & { ...; }

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_handling
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is { ...; } & { ...; }

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_initial
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is { ...; } & { ...; }

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_jsonrpc_error_response
#

(message: unknown): message is { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }

Checks if a value is a JSON-RPC error response (has error + id).

`message`

type unknown

returns

boolean

is_jsonrpc_message
#

(message: unknown): message is { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { ...; } | { ...; } | ({ ...; } | ... 2 more ... | { ...; })[]

Checks if a value is any valid JSON-RPC message or batch array.

`message`

type unknown

returns

boolean

is_jsonrpc_notification
#

(message: unknown): message is { [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }

Checks if a value is a JSON-RPC notification (has method, no id).

`message`

type unknown

returns

boolean

is_jsonrpc_object
#

(message: unknown): message is { jsonrpc: "2.0"; }

Checks if a value is a JSON-RPC object (has jsonrpc: '2.0').

`message`

type unknown

returns

boolean

is_jsonrpc_request
#

(message: unknown): message is { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }

Checks if a value is a JSON-RPC request (has method + id).

`message`

type unknown

returns

boolean

is_jsonrpc_request_id
#

(id: unknown): id is string | number

Checks if a value is a valid JSON-RPC request id (string or finite number).

`id`

type unknown

returns

boolean

is_jsonrpc_response
#

(message: unknown): message is { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; }

Checks if a value is a JSON-RPC success response (has result + id).

`message`

type unknown

returns

boolean

is_local_call
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ActionEventLocalCallData

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_notification
#

(method: string): (msg: unknown) => boolean

Predicate matching a JSON-RPC notification with the given method name.

`method`

type string

returns

(msg: unknown) => boolean

is_notification_receive
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ... 3 more ... | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_notification_send
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ... 3 more ... | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_notification_send_with_parsed_input
#

<TMethod extends string = string>(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_notification_with
#

<P>(method: string, match: (params: P) => boolean): (msg: unknown) => msg is JsonrpcNotificationFrame<P>

Type-guard combinator: match a notification whose typed params satisfies
match. Collapses the common test pattern of casting msg to
JsonrpcNotificationFrame<P> in every predicate body.
const match_roster_for = (id: Uuid) =>
  is_notification_with<RosterChangedParams>(
    WORLD_METHODS.roster_changed,
    (params) => params.character_id === id && !params.removed,
  );
const roster = await client.wait_for(match_roster_for(char_id));

`method`

type string

`match`

type (params: P) => boolean

returns

(msg: unknown) => msg is JsonrpcNotificationFrame<P>

is_null_schema
#

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): boolean

Check if a schema is exactly z.null().
Uses instanceof rather than runtime parsing to avoid false positives
from z.nullable(z.string()) or similar schemas that accept null
but also accept other values.

`schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

boolean

is_parsed
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is { ...; } & { ...; }

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_permit_active
#

db/pg_error.ts view source

(p: { revoked_at?: string | null | undefined; expires_at: string | null; }, now?: Date): boolean

`p`

type { revoked_at?: string | null | undefined; expires_at: string | null; }

`now`

type Date

default new Date()

returns

boolean

is_pg_unique_violation
#

(error: unknown): boolean

Check if an error is a PostgreSQL unique constraint violation (error code 23505).

`error`

the caught error

type unknown

returns

boolean

true if the error is a unique constraint violation

is_protocol_action_method
#

(method: string): method is "heartbeat" | "cancel"

Type predicate for filtering protocol-action methods out of a typed
FrontendActionsApi method_filter. Avoids the (... as never) cast
required to call Array.prototype.includes on the readonly tuple at narrow
string types.

`method`

type string

returns

boolean

examples

generate_frontend_actions_api(specs, imports, {
  method_filter: (s) => !is_protocol_action_method(s.method),
});

is_receive_request
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ... 3 more ... | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_receive_response
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ... 3 more ... | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_remote_notification
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ActionEventRemoteNotificationData

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_request_response
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ActionEventRequestResponseData

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_response_for
#

(id: string | number): (msg: unknown) => boolean

Predicate matching a JSON-RPC response frame (success or error) for the given request id.

`id`

type string | number

returns

(msg: unknown) => boolean

is_send_request
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ... 3 more ... | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_send_request_with_parsed_input
#

<TMethod extends string = string>(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_send_response
#

(data: { kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }): data is ({ ...; } & { ...; }) | ... 3 more ... | ({ ...; } & { ...; })

`data`

type

{ kind: "request_response" | "remote_notification" | "local_call"; phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"; ... 9 more ...; notification: { ...; } | null; }

returns

boolean

is_strict_object_schema
#

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): boolean

Check if a schema is a strict object (z.strictObject()).
Strict objects set catchall to ZodNever to reject unknown keys.
Regular z.object() has catchall: undefined (strips unknown keys in Zod 4).

`schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

boolean

is_trusted_ip
#

(ip: string, proxies: ParsedProxy[]): boolean

Check whether ip matches any entry in the trusted proxy list.
Normalizes ip before matching (lowercase, IPv4-mapped IPv6 stripped).

`ip`

type string

`proxies`

type ParsedProxy[]

returns

boolean

is_void_schema
#

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): boolean

Check if a schema is exactly z.void().
RPC action specs use z.void() to declare a parameterless method —
JSON-RPC 2.0 forbids params: null (params must be omitted or be a
Structured value), so z.void() is the correct schema for "no params"
and the dispatcher maps absent params to undefined for these specs.

`schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

boolean

jsonrpc_error_code_to_http_status
#

(code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)): number

Map a JSON-RPC error code to an HTTP status code.
Returns 500 for unrecognized codes (consumer-defined codes
without a mapping default to internal server error).

`code`

type -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)

returns

number

JSONRPC_ERROR_CODE_TO_HTTP_STATUS
#

Record<number, number>

Maps JSON-RPC error codes to HTTP status codes.
Extensible — consumers with domain-specific error codes assign directly
(JSONRPC_ERROR_CODE_TO_HTTP_STATUS[-32020] = 502) at module load. The
lookup function reads at call time, so mutation is the supported
extension mechanism.

JSONRPC_ERROR_CODES
#

Readonly<Record<JsonrpcErrorName, -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)>>

Standard JSON-RPC error codes (5) plus general application codes (10).
Extensible — consumers add domain-specific codes to their own objects
by casting as JsonrpcErrorCode. Application codes use the -32000 to
-32099 range reserved by the JSON-RPC spec.
Frozen with Object.freeze to convert accidental mutation (test
cross-contamination, cast escapes) into loud TypeErrors. Spread into
a fresh object to extend.

jsonrpc_error_messages
#

Readonly<Record<JsonrpcErrorName, (...args: any[]) => { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }>>

Named constructors for JsonrpcErrorObject values.
Each function creates a JSON-RPC error object with the correct
code and a sensible default message. Used by the catch layer in
apply_route_specs to build response bodies.
Frozen so tests must compose new objects rather than monkey-patch.

jsonrpc_errors
#

{ readonly parse_error: (...args: any[]) => ThrownJsonrpcError; readonly invalid_request: (...args: any[]) => ThrownJsonrpcError; readonly method_not_found: (...args: any[]) => ThrownJsonrpcError; ... 11 more ...; readonly request_cancelled: (...args: any[]) => ThrownJsonrpcError; }

Named constructors for ThrownJsonrpcError.
Usage: throw jsonrpc_errors.not_found('user') or throw jsonrpc_errors.forbidden().

JSONRPC_INTERNAL_ERROR
#

-32603

JSONRPC_INVALID_PARAMS
#

-32602

JSONRPC_INVALID_REQUEST
#

-32600

JSONRPC_METHOD_NOT_FOUND
#

-32601

JSONRPC_PARSE_ERROR
#

-32700

JSONRPC_SERVER_ERROR_END
#

-32099

End of the server-defined error code range (-32099).

JSONRPC_SERVER_ERROR_START
#

-32000

Start of the server-defined error code range (-32000).

JSONRPC_VERSION
#

"2.0"

JsonrpcErrorCode
#

ZodUnion<readonly [ZodLiteral<-32700>, ZodLiteral<-32600>, ZodLiteral<-32601>, ZodLiteral<-32602>, ZodLiteral<-32603>, $ZodBranded<...>]>

A valid JSON-RPC error code — one of the 5 standard codes or
a server-defined code in the -32000 to -32099 range.

JsonrpcErrorName
#

JsonrpcErrorName

Names of standard and general application JSON-RPC error codes.

JsonrpcErrorObject
#

ZodObject<{ code: ZodUnion<readonly [ZodLiteral<-32700>, ZodLiteral<-32600>, ZodLiteral<-32601>, ZodLiteral<-32602>, ZodLiteral<-32603>, $ZodBranded<...>]>; message: ZodString; data: ZodOptional<...>; }, $loose>

Error object within a JSON-RPC error response.

JsonrpcErrorResponse
#

ZodObject<{ jsonrpc: ZodLiteral<"2.0">; id: ZodNullable<ZodUnion<readonly [ZodString, ZodNumber]>>; error: ZodObject<{ code: ZodUnion<readonly [ZodLiteral<-32700>, ... 4 more ..., $ZodBranded<...>]>; message: ZodString; data: ZodOptional<...>; }, $loose>; }, $loose>

A response that indicates an error occurred.

JsonrpcErrorResponseFrame
#

JsonrpcErrorResponseFrame<D>

generics

`D`

default unknown

`jsonrpc`

type typeof JSONRPC_VERSION

`id`

type number | string

`error`

type {code: number; message: string; data?: D}

JsonrpcMcpMeta
#

ZodObject<{}, $loose>

MCP metadata object — loose to allow additional properties and .extend.

JsonrpcMessage
#

ZodUnion<readonly [ZodObject<{ jsonrpc: ZodLiteral<"2.0">; id: ZodUnion<readonly [ZodString, ZodNumber]>; method: ZodString; params: ZodOptional<ZodObject<{}, $loose>>; }, $loose>, ZodObject<...>, ZodObject<...>, ZodObject<...>]>

Any valid JSON-RPC message (request, notification, response, or error response).

JsonrpcMessageFromClientToServer
#

ZodUnion<readonly [ZodObject<{ jsonrpc: ZodLiteral<"2.0">; id: ZodUnion<readonly [ZodString, ZodNumber]>; method: ZodString; params: ZodOptional<ZodObject<{}, $loose>>; }, $loose>, ZodObject<...>]>

Messages a client can send to a server (request or notification).

JsonrpcMessageFromServerToClient
#

ZodUnion<readonly [ZodObject<{ jsonrpc: ZodLiteral<"2.0">; method: ZodString; params: ZodOptional<ZodObject<{}, $loose>>; }, $loose>, ZodObject<...>, ZodObject<...>]>

Messages a server can send to a client (notification, response, or error response).

JsonrpcMethod
#

ZodString

A JSON-RPC method name.

JsonrpcNotification
#

ZodObject<{ jsonrpc: ZodLiteral<"2.0">; method: ZodString; params: ZodOptional<ZodObject<{}, $loose>>; }, $loose>

A notification which does not expect a response.

JsonrpcNotificationFrame
#

JsonrpcNotificationFrame<P>

generics

`P`

default unknown

`jsonrpc`

type typeof JSONRPC_VERSION

`method`

type string

`params`

type P

JsonrpcNotificationParams
#

ZodObject<{}, $loose>

Notification params — loose object. Per-action schemas validate _meta content.

JsonrpcProgressToken
#

ZodUnion<readonly [ZodString, ZodNumber]>

A progress token, used to associate progress notifications with the original request.

JsonrpcRequest
#

ZodObject<{ jsonrpc: ZodLiteral<"2.0">; id: ZodUnion<readonly [ZodString, ZodNumber]>; method: ZodString; params: ZodOptional<ZodObject<{}, $loose>>; }, $loose>

A request that expects a response.

JsonrpcRequestId
#

ZodUnion<readonly [ZodString, ZodNumber]>

A uniquely identifying id for a request in JSON-RPC. Like MCP, excludes null.

JsonrpcRequestParams
#

ZodObject<{}, $loose>

Request params — loose object. Per-action schemas validate _meta content.

JsonrpcRequestParamsMeta
#

ZodObject<{ progressToken: ZodOptional<ZodUnion<readonly [ZodString, ZodNumber]>>; }, $loose>

Request params metadata — extends MCP meta with optional progress token.

JsonrpcResponse
#

ZodObject<{ jsonrpc: ZodLiteral<"2.0">; id: ZodUnion<readonly [ZodString, ZodNumber]>; result: ZodObject<{}, $loose>; }, $loose>

A successful (non-error) response to a request.

JsonrpcResponseOrError
#

ZodUnion<readonly [ZodObject<{ jsonrpc: ZodLiteral<"2.0">; id: ZodUnion<readonly [ZodString, ZodNumber]>; result: ZodObject<{}, $loose>; }, $loose>, ZodObject<...>]>

A successful response or an error response.

JsonrpcResult
#

ZodObject<{}, $loose>

Result — loose object. Per-action schemas validate _meta content.

JsonrpcServerErrorCode
#

$ZodBranded<ZodNumber, "JsonrpcServerErrorCode", "out">

A server-defined error code in the -32000 to -32099 range.

JsonrpcSuccessResponseFrame
#

JsonrpcSuccessResponseFrame<R>

generics

`R`

default unknown

`jsonrpc`

type typeof JSONRPC_VERSION

`id`

type number | string

`result`

type R

keeper_identity
#

(): WsConnectIdentity

Convenience: default identity for keeper-authenticated connections.

returns

WsConnectIdentity

KeeperError
#

ZodObject<{ error: ZodLiteral<"keeper_requires_daemon_token">; credential_type: ZodString; }, $loose>

Keeper credential error — returned by require_keeper when credential type is wrong.

Keyring
#

Keyring

Opaque keyring that encapsulates secret keys.
Only exposes sign/verify operations, never the raw keys.

`sign`

Sign a value with HMAC SHA-256.

type (value: string) => Promise<string>

`verify`

Verify a signed value and extract the original.
Tries all keys in order to support key rotation.

type (signed_value: string) => Promise<{value: string; key_index: number} | null>

load_config
#

env/dotenv.ts view source

<T>(runtime: Pick<FsReadDeps, "stat" | "read_text_file"> & LogDeps, path: string, schema: ZodType<T, unknown, $ZodTypeInternals<T, unknown>>): Promise<...>

Load CLI configuration from a JSON file with Zod schema validation.

`runtime`

runtime with file read capability

type Pick<FsReadDeps, "stat" | "read_text_file"> & LogDeps

`path`

path to the config JSON file

type string

`schema`

Zod schema to validate against

type ZodType<T, unknown, $ZodTypeInternals<T, unknown>>

returns

Promise<T | null>

parsed config, or null if file doesn't exist or is invalid

load_env
#

env/load.ts view source

<T extends z.ZodObject>(schema: T, get_env: (key: string) => string | undefined): output<T>

Load and validate env vars against a Zod schema.

`schema`

Zod object schema defining expected env vars

type T

`get_env`

function to read an env var by key

type (key: string) => string | undefined

returns

output<T>

validated env object

throws

EnvValidationError - if Zod validation fails

load_env_file
#

(runtime: Pick<FsReadDeps, "read_text_file">, path: string): Promise<Record<string, string> | null>

Load and parse an env file.
Returns null only when the file does not exist. Other read errors
(permission denied, I/O failure, etc.) are re-thrown so callers can
distinguish "no file" from "couldn't read".

`runtime`

runtime with read_text_file capability

type Pick<FsReadDeps, "read_text_file">

`path`

path to env file

type string

returns

Promise<Record<string, string> | null>

parsed env record, or null if file doesn't exist

throws

Error - if reading fails for any reason other than `ENOENT` / `NotFound`

Loadable
#

ui/loadable.svelte.ts view source

Base reactive state class with loading/error management.
Provides the common loading/error pattern shared by all state classes.
Subclasses add domain-specific $state fields and methods that call
the protected run helper for async operations.

generics

`TError`

default string

examples

class ItemsState extends Loadable {
	items: Array<Item> = $state.raw([]);

	async fetch(): Promise<void> {
		await this.run(async () => {
			const response = await fetch('/api/items');
			if (!response.ok) throw new Error('failed to fetch');
			this.items = await response.json();
		});
	}
}

// structured errors via map_error
class FormState extends Loadable<{field: string; message: string}> {
	async submit(data: FormData): Promise<void> {
		await this.run(
			() => post_form(data),
			(e) => ({field: 'form', message: e instanceof Error ? e.message : 'unknown'}),
		);
	}
}

`loading`

`error`

type TError | null

`error_data`

The raw caught value from the last failed run(), for programmatic inspection.

type unknown

`run`

Run an async operation with loading/error handling.
Sets loading to true, clears error and error_data, runs fn, catches errors.
Pass map_error to produce structured errors instead of strings.

type <T>(fn: () => Promise<T>, map_error?: ((e: unknown) => TError) | undefined): Promise<T | undefined>

protected

`fn`

type () => Promise<T>

`map_error?`

type ((e: unknown) => TError) | undefined

optional

returns Promise<T | undefined>

the result or undefined if the operation failed

`reset`

Reset loading and error state. Subclasses override to clear data.

type (): void

returns void

LocalCallActionSpec
#

ZodObject<{ method: ZodString; initiator: ZodEnum<{ frontend: "frontend"; backend: "backend"; both: "both"; }>; side_effects: ZodBoolean; input: ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodType<...>>; ... 7 more ...; auth: ZodDefault<...>; }, $strict>

Local calls can wrap synchronous or asynchronous actions, and are the
escape hatch for remote APIs that do not support SAES.

log_db_factory_status
#

server/startup.ts view source

(factories: DbFactory[]): void

Log factory status to console.

`factories`

type DbFactory[]

returns

void

log_env_validation_error
#

env/load.ts view source

(error: EnvValidationError, label?: string | undefined): void

Log formatted env validation issues to stderr.
Handles the common case: labels each Zod issue with an optional prefix.
Callers who want app-specific "getting started" instructions should check
error.all_undefined before calling this.

`error`

the env validation error

type EnvValidationError

`label?`

optional prefix for log lines (e.g., 'tx daemon', 'env')

type string | undefined

optional

returns

void

log_startup_summary
#

(surface: AppSurface, log: Logger, env_values?: Record<string, unknown> | undefined): void

Log a startup summary from an AppSurface.
Logs route count, middleware count, env breakdown (when non-empty),
and event/channel counts (when non-empty). When env_values is provided,
non-secret values are logged and secrets are masked with ***.

`surface`

type AppSurface

`log`

type Logger

`env_values?`

optional env values to log (secrets are masked)

type Record<string, unknown> | undefined

optional

returns

void

LogDeps
#

ui/LoginForm.svelte view source

LogDeps

Warning/diagnostic output.

`warn`

Log a warning message.

type (...args: Array<unknown>) => void

LoginForm
#

`username_label?`

Label and placeholder for the username field — set when the surface
accepts only one of username/email so the UX matches.

type string

optional

`redirect_on_login?`

Path to navigate to on successful login.

type string

optional

LoginInput
#

ZodObject<{ username: ZodString; password: ZodString; }, $strict>

Input for POST /login. Accepts a username or email in the username field.

LoginOutput
#

ui/LogoutButton.svelte view source

ZodObject<{ ok: ZodLiteral<true>; }, $strict>

Output for POST /login. The signed session cookie is the operative side effect.

LogoutButton
#

`onclick?`

type ComponentProps<typeof PendingButton>['onclick']

optional

`children?`

type Snippet

optional

LogoutInput
#

ZodNull

Input for POST /logout. Session identity flows through the cookie.

LogoutOutput
#

ZodObject<{ ok: ZodLiteral<true>; username: ZodString; }, $strict>

Output for POST /logout. Includes the revoked account's username for UI redraw.

map_action_auth
#

ui/MenuLink.svelte view source

(auth: "public" | "authenticated" | "keeper" | { role: string; }): RouteAuth

Map an ActionAuth value to a RouteAuth.

`auth`

type "public" | "authenticated" | "keeper" | { role: string; }

returns

RouteAuth

MASKED_VALUE
#

env/mask.ts view source

"***"

Placeholder displayed in place of secret values.

MenuLink
#

`path`

Route path passed to resolve from $app/paths to compute href.

type string

`highlighted?`

Override the auto-derived highlighted flag (defaults to "current path is below href").

type boolean

optional

`children?`

type Snippet

optional

merge_error_schemas
#

(spec: { auth: RouteAuth; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; params?: ZodObject<$ZodLooseShape, $strip> | undefined; query?: ZodObject<...> | undefined; rate_limit?: "both" | ... 2 more ... | undefined; errors?: Partial<...> | undefined; }, middleware_errors?: Partial<...> | ... 1 more ... | undefined): Partial<...> | null

Merge auto-derived, middleware, and explicit error schemas for a route spec.
Merge order: derived -> middleware -> explicit route errors.
Later layers override earlier ones for the same status code.

`spec`

the route spec (needs auth, input, params, rate_limit, errors)

type

{ auth: RouteAuth; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; params?: ZodObject<$ZodLooseShape, $strip> | undefined; query?: ZodObject<...> | undefined; rate_limit?: "both" | ... 2 more ... | undefined; errors?: Partial<...> | undefined; }

`middleware_errors?`

type Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>> | null | undefined

optional

returns

Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>> | null

merged error schemas, or null if empty

middleware_applies
#

http/middleware_spec.ts view source

(mw_path: string, route_path: string): boolean

Check if a middleware path pattern applies to a route path.
Supports Hono-style patterns:
- /api/* matches /api/anything
- /api/tx/* matches /api/tx/runs but not /api/account/login
- Exact match: /health matches /health

`mw_path`

type string

`route_path`

type string

returns

boolean

MiddlewareSpec
#

MiddlewareSpec

A named middleware layer.

`name`

type string

`path`

type string

`handler`

type MiddlewareHandler

`errors`

Error response schemas this middleware can produce, keyed by HTTP status code.

type RouteErrorSchemas

Migration
#

Migration

A single migration: a name + an up function applied inside a transaction.
Throw from up to roll back the entire chain.

`name`

type string

`up`

type (db: Db) => Promise<void>

MigrationError
#

Tagged error thrown by run_migrations and baseline.
Branch on .kind; the message carries an operator-facing remediation hint.

inheritance

extends:

Error

`kind`

type MigrationErrorKind

readonly

`namespace`

type string

readonly

`at_index`

type number

readonly

`unknown_names`

type ReadonlyArray<string>

readonly

`constructor`

type new (kind: MigrationErrorKind, message: string, context?: MigrationErrorContext | undefined): MigrationError

`kind`

type MigrationErrorKind

`message`

type string

`context?`

type MigrationErrorContext | undefined

optional

MigrationErrorContext
#

MigrationErrorContext

Structured context passed alongside a MigrationError.

`namespace`

type string

`at_index`

type number

`unknown_names`

type ReadonlyArray<string>

`cause`

type unknown

MigrationErrorKind
#

MigrationErrorKind

Tagged error vocabulary for run_migrations and baseline.
Callers branch on .kind rather than matching error messages — message
text is for operators, not control flow.

MigrationNamespace
#

MigrationNamespace

A named group of ordered migrations.
Array index = position in the chain. Append-only after publish.

`namespace`

type string

`migrations`

type Array<Migration>

MigrationResult
#

MigrationResult

Result of running migrations for a single namespace.

`namespace`

type string

`applied_names`

Migrations applied in this run, in sequence-ascending (execution) order.

type Array<string>

MigrationStatus
#

MigrationStatus

Migration status for a single namespace.

`namespace`

type string

`applied_names`

Names of migrations recorded in the tracker, sequence-ascending.

type Array<string>

`pending_names`

Names of code migrations not yet applied (suffix of the code array).

type Array<string>

`up_to_date`

Whether applied_names is the full code array (no pending work).

type boolean

MinimalActionEnvironment
#

Minimal ActionEventEnvironment for tests that instantiate an
ActionPeer without pulling in the full runtime. Pre-loads a
spec map from the supplied list.

inheritance

implements:

ActionEventEnvironment

`executor`

type 'frontend' | 'backend'

`constructor`

type new (specs: readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; })[]): MinimalActionEnvironment

`specs`

type

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

`lookup_action_handler`

type (): undefined

returns undefined

`lookup_action_spec`

type (method: string): { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; } | undefined

`method`

type string

returns

{ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }...

MockExitError
#

testing/mock_fs.ts view source

Error thrown when mock runtime.exit() is called.
Tests can catch this to verify exit behavior.

inheritance

extends:

Error

`code`

type number

readonly

`constructor`

type new (code: number): MockExitError

`code`

type number

MockFs
#

MockFs

In-memory file system mock for tests that use dependency-injected
read_file and write_file callbacks. Avoids module-level mocking.

`read_file`

type (path: string, encoding: string) => Promise<string>

`write_file`

type (path: string, content: string, encoding: string) => Promise<void>

`get_file`

type (path: string) => string | undefined

MockRuntime
#

MockRuntime

Mock RuntimeDeps with observable state for assertions.

inheritance

extends:

RuntimeDeps

`mock_env`

Mock environment variables.

type Map<string, string>

`mock_fs`

Mock file system (path -> content).

type Map<string, string>

`mock_fs_bytes`

Mock binary file system (path -> bytes).

type Map<string, Uint8Array>

`mock_dirs`

Mock directories that exist.

type Set<string>

`exit_calls`

Exit calls recorded (exit codes).

type Array<number>

`command_calls`

Commands executed. Captures options when passed so tests can assert cwd/timeout/signal.

type Array<{cmd: string; args: Array<string>; options?: RunCommandOptions}>

`command_inherit_calls`

Commands executed with inherit.

type Array<{cmd: string; args: Array<string>}>

`stdout_writes`

Stdout writes recorded.

type Array<string>

`mock_command_results`

Mock command results (cmd -> result).

type Map<string, CommandResult>

`stdin_buffer`

Stdin buffer for input simulation.

type Uint8Array | null

`fetch_calls`

Fetch calls recorded.

type Array<{input: string | URL | Request; init?: RequestInit}>

`mock_fetch_responses`

Mock fetch responses (URL substring -> Response).

type Map<string, Response>

MockWsClient
#

server/validate_nginx.ts view source

MockWsClient

A mock WS client: send requests, inspect/await incoming messages.

`send`

Send a JSON-RPC message (request or notification) to the server.

type (message: unknown) => Promise<void>

`request`

Send a JSON-RPC request and await its response. Resolves with the
result; throws with a useful message (code, text, and any data
payload) on an error frame — without this, asserting on
result.foo for a failed request throws
Cannot read property 'foo' of undefined, which hides the real
cause. Use send + wait_for(is_response_for(id)) directly when
you need to assert on the error frame itself.

type

<R = unknown>(
		id: number | string,
		method: string,
		params: unknown,
		timeout_ms?: number,
	) => Promise<R>

`close`

Close the connection, firing onClose. Returns a promise that
resolves once on_socket_close (and the transport's own cleanup)
have completed — tests that assert on post-close state should await.

type (code?: number, reason?: string) => Promise<void>

`messages`

Every message the server has sent, in arrival order.

type ReadonlyArray<unknown>

readonly

`wait_for`

Wait until a message satisfies predicate. Matches are checked
against already-received messages first, then new arrivals until
the timeout (defaults to 1000ms).
When predicate is a type guard (e.g. is_notification_with<P>),
the result is narrowed automatically and callers don't need to
spell <JsonrpcNotificationFrame<P>> on the call site.

type

{
		<T>(predicate: (msg: unknown) => msg is T, timeout_ms?: number): Promise<T>;
		// eslint-disable-next-line @typescript-eslint/unified-signatures
		<T = unknown>(predicate: (msg: unknown) => boolean, timeout_ms?: number): Promise<T>;
	}

NginxValidationResult
#

NginxValidationResult

Result of validating an nginx config template string.

`ok`

True when no errors were detected. Warnings do not affect this flag.

type boolean

`warnings`

Non-fatal issues — missing optional headers, weakened defaults, etc.

type Array<string>

`errors`

Fatal issues — missing /api block, missing required security headers, etc.

type Array<string>

no_nested_transaction
#

<T>(fn: (tx_db: Db) => Promise<T>): Promise<T>

Sentinel transaction function for transaction-scoped Db instances.
Used by driver adapters when constructing the inner Db passed
to transaction callbacks.

`fn`

type (tx_db: Db) => Promise<T>

returns

Promise<T>

throws

Error - always — nested transactions are not supported

normalize_ip
#

(ip: string): string

Normalize an IP address for consistent matching and storage.
- Strips ::ffff: prefix from IPv4-mapped IPv6 addresses
  (e.g. ::ffff:127.0.0.1 → 127.0.0.1)
- Lowercases for case-insensitive IPv6 comparison
- Idempotent: calling twice produces the same result
- Safe on non-IP strings: normalize_ip('unknown') returns 'unknown'

`ip`

type string

returns

string

NotificationSender
#

ui/OpenSignupToggle.svelte view source

NotificationSender

Narrow structural capability for sending a JSON-RPC notification to every
socket bound to an account.
BackendWebsocketTransport satisfies this interface — its
send_to_account(account_id, message) signature accepts the broader
JsonrpcMessageFromServerToClient type, which is contravariantly
compatible with JsonrpcNotification here. The interface stays local so
handlers don't couple to the concrete transport, and tests can inject a
capturing stub with no WS machinery.
Returns the number of sockets the notification was sent to — callers
typically ignore it (used by telemetry / tests).

`send_to_account`

type (account_id: Uuid, message: JsonrpcNotification) => number

OpenSignupToggle
#

parse_action_event
#

(raw_json: unknown, environment: ActionEventEnvironment): ActionEvent<string, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | ... 3 more ... | "failed">

`raw_json`

type unknown

`environment`

http/origin.ts view source

returns

ActionEvent<string, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

parse_allowed_origins
#

(env_value: string | undefined): RegExp[]

Parses ALLOWED_ORIGINS env var into regex matchers for request source verification.
Origin allowlisting for locally-running services — not the CSRF layer
(that's SameSite: strict on session cookies).
Accepts comma-separated patterns with limited wildcards:
- Exact origins: https://api.fuz.dev
- Wildcard subdomains: https://*.fuz.dev (matches exactly one subdomain level)
- Multiple wildcards: https://*.staging.*.fuz.dev (for deep subdomains)
- Wildcard ports: http://localhost:* (matches any port or no port)
- IPv6 addresses: http://[::1]:3000, https://[2001:db8::1]
- Combined: https://*.fuz.dev:*
Examples:
- http://localhost:3000,https://prod.fuz.dev
- https://*.api.fuz.dev,http://127.0.0.1:*
- http://[::1]:*,https://*.*.corp.fuz.dev:*

`env_value`

type string | undefined

returns

RegExp[]

throws

Error - if any individual pattern is invalid (missing protocol, partial wildcards, etc.)

parse_command_args
#

cli/args.ts view source

<T extends Record<string, unknown>>(remaining: ParsedArgs, schema: ZodType<T, unknown, $ZodTypeInternals<T, unknown>>): ParseResult<T>

Parse command-specific args against a Zod schema.
Validates remaining args (after global flag extraction) with alias expansion
and returns a typed result or a prettified error string.

`remaining`

remaining args after global flag extraction

type ParsedArgs

`schema`

Zod schema for the command

type ZodType<T, unknown, $ZodTypeInternals<T, unknown>>

returns

ParseResult<T>

parse result with typed data or error message

parse_db_name
#

env/dotenv.ts view source

(url: string): string | null

Extract the database name from a PostgreSQL URL.

`url`

type string

returns

string | null

the database name, or null if the URL is invalid or has no path

parse_dotenv
#

(content: string): Record<string, string>

Parse a dotenv-format string into a record.
Values wrapped in "..." have \\ → \, \" → ", \n → newline,
and \r → carriage-return decoded (symmetric with the writer in
update_env_variable). Values wrapped in '...' are taken literally —
no escape processing. Unquoted values are unchanged.
Inline comments are stripped after a closing quote (e.g. KEY="v" # c → v)
and after whitespace on unquoted values (e.g. KEY=v # c → v). Unquoted
values keep # literal when no whitespace precedes it so URL fragments
like KEY=https://x.com#frag round-trip unchanged.
Trailing whitespace on unquoted values is lost (the raw value is trimmed);
wrap the value in "..." or '...' to preserve surrounding spacing.

`content`

dotenv file content

type string

returns

Record<string, string>

parsed key-value pairs

parse_proxy_entry
#

ui/ui_fetch.ts view source

(entry: string): ParsedProxy

Parse a trusted proxy entry string into a structured form.
Accepts plain IPs ('127.0.0.1', '::1') and CIDR notation ('10.0.0.0/8', 'fe80::/10').
Plain IPs are normalized (lowercase, IPv4-mapped IPv6 stripped) and validated.
CIDR prefixes are validated against address family bounds.

`entry`

IP address or CIDR notation

type string

returns

ParsedProxy

throws

Error - on invalid IP, invalid CIDR network, or NaN/negative/over-range prefix

parse_response_error
#

(response: Response, fallback?: string | undefined): Promise<string>

Safely extract an error message from a non-ok response.
Handles responses with non-JSON bodies (e.g. HTML 404 pages)
that would throw on response.json().

`response`

type Response

`fallback?`

message when no .error field is found

type string | undefined

optional

returns

Promise<string>

parse_session
#

<TIdentity>(signed_value: string | undefined, keyring: Keyring, options: SessionOptions<TIdentity>, now_seconds?: number | undefined): Promise<ParsedSession<...> | null | undefined>

Parse a signed session cookie value.
The signed value format is ${encode(identity)}:${expires_at}.
Tries all keys in order to support key rotation.

`signed_value`

the raw cookie value (signed)

type string | undefined

`keyring`

key ring for verification

type Keyring

`options`

session configuration with decode logic

type SessionOptions<TIdentity>

`now_seconds?`

current time in seconds (for testing)

type number | undefined

optional

returns

Promise<ParsedSession<TIdentity> | null | undefined>

ParsedSession if valid, null if invalid/expired, undefined if empty/missing

ParsedProxy
#

ParsedProxy

A parsed proxy entry — either an exact IP or a CIDR range.

ParsedSession
#

ParsedSession<TIdentity>

Result of parsing a signed session cookie.

generics

`TIdentity`

`identity`

The decoded identity.

type TIdentity

`should_refresh_signature`

True if verified with a non-primary key (needs re-signing).

type boolean

`key_index`

Index of the key that verified the signature.

type number

ParseResult
#

cli/args.ts view source

ParseResult<T>

Discriminated union result for CLI argument parsing.

generics

`T`

Password
#

ZodString

Password for account creation or password change — enforces current length policy. Also usable for client-side UX validation.

PASSWORD_LENGTH_MAX
#

300

Maximum password length. Caps hashing cost to prevent DoS via oversized passwords.

PASSWORD_LENGTH_MIN
#

12

Minimum password length (OWASP recommendation).

PasswordChangeInput
#

ZodObject<{ current_password: ZodString; new_password: ZodString; }, $strict>

Input for POST /password. current_password is minimally validated; new_password enforces the full policy.

PasswordChangeOutput
#

ZodObject<{ ok: ZodLiteral<true>; sessions_revoked: ZodNumber; tokens_revoked: ZodNumber; }, $strict>

Output for POST /password. Counts are returned so the UI can summarize the revoke-all cascade.

PasswordHashDeps
#

PasswordHashDeps

Injectable password hashing dependencies.
Groups all three password operations for injection in route factories
and other callers. Use Pick<PasswordHashDeps, ...> when only a subset is needed:

examples

// Login handler only needs verification
password: Pick<PasswordHashDeps, 'verify_password' | 'verify_dummy'>;
// Bootstrap only needs hashing
password: Pick<PasswordHashDeps, 'hash_password'>;

`hash_password`

type (password: string) => Promise<string>

`verify_password`

type (password: string, password_hash: string) => Promise<boolean>

`verify_dummy`

type (password: string) => Promise<boolean>

PasswordProvided
#

ZodString

Password submitted for login or verification — minimal validation for forward-compatibility if length requirements change.

PayloadTooLargeError
#

http/pending_effects.ts view source

ZodObject<{ error: ZodLiteral<"payload_too_large">; }, $loose>

Payload too large error — returned when the request body exceeds the size limit.

PendingEffectsContext
#

PendingEffectsContext

Minimal structural context required by emit_after_commit.

`log`

type Logger

`pending_effects`

type Array<Promise<void>>

PendingOfferSummaryJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_id: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; from_actor_id: $ZodBranded<...>; from_username: ZodString; created_at: ZodString; expires_at: ZodString; }, $strict>

Zod schema for a pending permit offer surfaced in admin account listings.
Deliberately narrower than PermitOfferJson: omits message and
decline_reason so cross-admin visibility of the listing does not expose
grantor-authored text that the audit log also withholds. Full offer
payloads remain available through the offer-specific RPC surface and the
audit log when admins need them.
from_username is resolved server-side so multi-admin deployments can see
at a glance whose pending offer is blocking a "+ {role}" button; the
resolution runs inside the listing query's parallel batch.

PermissionError
#

ZodObject<{ error: ZodLiteral<"insufficient_permissions">; required_role: ZodString; }, $loose>

Permission error — returned by require_role() when the required role is missing.

Permit
#

Permit

Permit — time-bounded, revocable grant of a role to an actor.

`id`

type Uuid

`actor_id`

type Uuid

`role`

type string

`scope_id`

Resource scope this grant applies to (e.g. a classroom id). null for global permits.

type Uuid | null

`created_at`

type string

`expires_at`

type string | null

`revoked_at`

type string | null

`revoked_by`

type Uuid | null

`revoked_reason`

Optional free-form reason attached on revoke (surfaced in the revokee WS notification once it lands).

type string | null

`granted_by`

type Uuid | null

`source_offer_id`

Offer that produced this permit (set by query_accept_offer). null for direct grants.

type Uuid | null

PERMIT_INDEXES
#

string[]

permit_offer_accept_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ offer_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>; output: ZodObject<...>; async: true; description: string; error_reasons: ("offer_terminal" | ... 1 more ... | "offer_not_found")...

PERMIT_OFFER_ACCEPTED_NOTIFICATION_METHOD
#

"permit_offer_accepted"

permit_offer_accepted_notification_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<...>; ... 11 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>; output: ZodVoid; async...

permit_offer_create_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_id: ZodOptional<...>; message: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: s...

permit_offer_decline_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ offer_id: $ZodBranded<ZodUUID, "Uuid", "out">; reason: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description: string; error_reasons: ("offer_terminal" | "offer_no...

PERMIT_OFFER_DECLINED_NOTIFICATION_METHOD
#

"permit_offer_declined"

permit_offer_declined_notification_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<...>; ... 11 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>; output: ZodVoid; async...

PERMIT_OFFER_DEFAULT_TTL_MS
#

number

Default TTL for a newly created offer — 30 days. Matches GitHub org-invite expiry.

permit_offer_history_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: false; input: ZodObject<{ account_id: ZodOptional<ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>>; limit: ZodOptional<...>; offset: ZodOptional<...>; }, $strict>; output: ZodObject<...>; async: true; description...

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"

Inbox lookup — pending offers for an account, ordered by soonest expiry.

permit_offer_list_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: false; input: ZodObject<{ account_id: ZodOptional<ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>>; }, $strict>; output: ZodObject<...>; async: true; description: string; }

PERMIT_OFFER_MESSAGE_LENGTH_MAX
#

500

Maximum length of the optional message attached to an offer.

PERMIT_OFFER_NOTIFICATION_SPECS
#

EventSpec[]

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.

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 supersed...

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.

PERMIT_OFFER_RECEIVED_NOTIFICATION_METHOD
#

"permit_offer_received"

permit_offer_received_notification_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<...>; ... 11 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>; output: ZodVoid; async...

permit_offer_retract_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ offer_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>; output: ZodObject<...>; async: true; description: string; error_reasons: ("offer_terminal" | "offer_not_found")[]; }

PERMIT_OFFER_RETRACTED_NOTIFICATION_METHOD
#

"permit_offer_retracted"

permit_offer_retracted_notification_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<...>; ... 11 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>; output: ZodVoid; async...

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  role TEXT NOT NULL,\n  scope_id UUID NULL,\n  message TEXT NULL,\n  created...

PERMIT_OFFER_SCOPE_SENTINEL_UUID
#

"00000000-0000-0000-0000-000000000000"

Sentinel UUID used inside the partial unique indexes to collapse scope_id IS NULL into a comparable value.

PERMIT_OFFER_SUPERSEDE_NOTIFICATION_METHOD
#

"permit_offer_supersede"

permit_offer_supersede_notification_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<...>; ... 11 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; reason: ZodEnum<...>; cause_id: $Zo...

permit_offers_state_context
#

{ get: (error_message?: string | undefined) => PermitOffersState; get_maybe: () => PermitOffersState | undefined; set: (value: PermitOffersState) => PermitOffersState; }

Svelte context for PermitOffersState.
Use permit_offers_state_context.set(state) in the provider and
permit_offers_state_context.get() to access.

permit_revoke_action_spec
#

{ method: string; kind: "request_response"; initiator: "frontend"; auth: { role: string; }; side_effects: true; input: ZodObject<{ actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; permit_id: $ZodBranded<...>; reason: ZodOptional<...>; }, $strict>; ... 4 more ...; rate_limit: "account"; }

PERMIT_REVOKE_NOTIFICATION_METHOD
#

"permit_revoke"

permit_revoke_notification_spec
#

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ZodObject<{ permit_id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_id: ZodNullable<...>; reason: ZodNullable<...>; }, $strict>; output: ZodVoid; async: true; description: string; }

PERMIT_REVOKED_REASON_LENGTH_MAX
#

500

Maximum length of the optional free-form revoked_reason attached to a
revoked permit. Bounds the value at the schema layer so both the admin
input (when the route surfaces a reason field) and the revokee-facing
permit_revoke WS notification validate against the same ceiling.

PERMIT_SCHEMA
#

"\nCREATE TABLE IF NOT EXISTS permit (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,\n  role TEXT NOT NULL,\n  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  expires_at TIMESTAMPTZ,\n  revoked_at TIMESTAMPTZ,\n  revoked_by UUID REFERENCES actor...

PermitHistoryEventJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; seq: ZodNumber; event_type: ZodString; outcome: ZodEnum<{ success: "success"; failure: "failure"; }>; ... 7 more ...; target_username: ZodNullable<...>; }, $strict>

Zod schema for permit history events with resolved usernames.

PermitOffer
#

PermitOffer

Permit offer row as returned by the database.

`id`

type Uuid

`from_actor_id`

type Uuid

`to_account_id`

type Uuid

`role`

type string

`scope_id`

type Uuid | null

`message`

type string | null

`created_at`

type string

`expires_at`

type string

`accepted_at`

type string | null

`declined_at`

type string | null

`decline_reason`

type string | null

`retracted_at`

type string | null

`superseded_at`

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.

type string | null

`resulting_permit_id`

type Uuid | null

PermitOfferAcceptedParams
#

ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>

Params for permit_offer_accepted — recipient accepted the offer.

PermitOfferAcceptInput
#

ZodObject<{ offer_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>

Input for permit_offer_accept.

PermitOfferAcceptOutput
#

ZodObject<{ permit_id: $ZodBranded<ZodUUID, "Uuid", "out">; offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 11 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; superseded_offer_ids: ZodArray<...>; }, $strict>

Output for permit_offer_accept.

PermitOfferActionDeps
#

PermitOfferActionDeps

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).

inheritance

extends:

Pick< RouteFactoryDeps, 'log' | 'on_audit_event' | 'audit_log_config' >

`notification_sender`

Optional WS fan-out primitive. null or absent → notifications skipped.

type NotificationSender | null

PermitOfferActionOptions
#

PermitOfferActionOptions

Options for create_permit_offer_actions.

`roles`

Role schema result from create_role_schema(). Defaults to builtin roles only.
The role_options map is read for web_grantable lookups.

type RoleSchemaResult

`default_ttl_ms`

TTL applied to newly-created offers. Defaults to PERMIT_OFFER_DEFAULT_TTL_MS.

type number

`authorize`

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.

type PermitOfferCreateAuthorize

PermitOfferAlreadyTerminalError
#

Error thrown by offer-lifecycle queries when the offer is in a non-pending
state (accepted / declined / retracted / superseded) and therefore not
actionable. Distinct from PermitOfferExpiredError — expiry has its own
user-facing story ("ask the grantor to re-send") so it travels separately.

inheritance

extends:

Error

`constructor`

type new (offer_id: string): PermitOfferAlreadyTerminalError

`offer_id`

type string

PermitOfferCreateAuthorize
#

PermitOfferCreateAuthorize

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

PermitOfferCreateInput
#

ZodObject<{ to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_id: ZodOptional<ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>>; message: ZodOptional<...>; }, $strict>

Input for permit_offer_create.

PermitOfferCreateOutput
#

ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>

Output for permit_offer_create.

PermitOfferDeclinedParams
#

ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>

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.

PermitOfferDeclineInput
#

ZodObject<{ offer_id: $ZodBranded<ZodUUID, "Uuid", "out">; reason: ZodOptional<ZodNullable<ZodString>>; }, $strict>

Input for permit_offer_decline.

PermitOfferExpiredError
#

ui/PermitOfferForm.svelte view source

Error thrown when an offer's expires_at has passed. The accept path
enforces this independently of the sweep — a stale offer past its expiry
must not be accepted, even in the race window between expiry and the
sweep stamping the audit event.

inheritance

extends:

Error

`constructor`

type new (offer_id: string): PermitOfferExpiredError

`offer_id`

type string

PermitOfferForm
#

`to_account_id`

type string

`roles`

Roles the caller may offer — caller filters by web_grantable upstream.

type Array<string>

`scope_id?`

Resource scope for the offer; null (default) yields a global offer.

type string | null

optional

`on_created?`

type (offer: PermitOfferJson) => void

optional

`format_role?`

type (role: string) => string

optional

PermitOfferHistory
#

ui/PermitOfferHistory.svelte view source

`current_actor_id`

Used to label a row as sent vs received. When null, direction shows as -.

type string | null

`format_actor?`

type (from_actor_id: string) => string

optional

`format_scope?`

Display label for an offer's scope. Bypasses format_scope_context
when supplied — return null to fall back to a truncated uuid (or
'global' for null scope_id). Omit to use the context value directly.

type FormatScope

optional

`format_role?`

type (role: string) => string

optional

PermitOfferHistoryInput
#

ZodObject<{ account_id: ZodOptional<ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>>; limit: ZodOptional<ZodNullable<ZodNumber>>; offset: ZodOptional<...>; }, $strict>

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.

PermitOfferHistoryOutput
#

ui/PermitOfferInbox.svelte view source

ZodObject<{ offers: ZodArray<ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>>; }, $strict>

Output for permit_offer_history.

PermitOfferInbox
#

`format_actor?`

Display label for from_actor_id. Defaults to a truncated uuid.

type (from_actor_id: string) => string

optional

`format_scope?`

Display label for an offer's scope. Bypasses format_scope_context
when supplied — return null to fall back to a truncated uuid (or
'global' for null scope_id). Omit to use the context value directly.

type FormatScope

optional

`format_role?`

Display label for a role constant. Defaults to identity.

type (role: string) => string

optional

PermitOfferJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>

Zod schema for client-safe permit offer data.

PermitOfferListInput
#

ZodObject<{ account_id: ZodOptional<ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>>; }, $strict>

Input for permit_offer_list. account_id is admin-only (inspect another account's inbox).

PermitOfferListOutput
#

ZodObject<{ offers: ZodArray<ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>>; }, $strict>

Output for permit_offer_list.

PermitOfferNotFoundError
#

Error thrown when an offer cannot be located for the caller. Covers both
"offer does not exist" and "offer belongs to a different recipient"
(IDOR guard) — the standard 404-over-403 pattern that avoids disclosing
whether an offer id exists.

inheritance

extends:

Error

`constructor`

type new (offer_id: string): PermitOfferNotFoundError

`offer_id`

type string

PermitOfferNotification
#

PermitOfferNotification

Narrow WS notification envelope — method + params, matching JsonrpcNotification.

`method`

type string

`params`

type unknown

PermitOfferOkOutput
#

ZodObject<{ ok: ZodLiteral<true>; }, $strict>

Output for permit_offer_decline / permit_offer_retract.

PermitOfferReceivedParams
#

ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>

Params for permit_offer_received — offer delivered to its recipient.

PermitOfferRetractedParams
#

ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; }, $strict>

Params for permit_offer_retracted — grantor-side retraction.

PermitOfferRetractInput
#

ZodObject<{ offer_id: $ZodBranded<ZodUUID, "Uuid", "out">; }, $strict>

Input for permit_offer_retract.

PermitOfferSelfTargetError
#

Error thrown when a grantor attempts to offer a permit to their own account.
Enforced here (rather than via a CHECK constraint) so the constraint can
be expressed as a cross-row JOIN on actor.account_id without requiring
denormalized columns.

inheritance

extends:

Error

`constructor`

type new (): PermitOfferSelfTargetError

PermitOffersRpc
#

PermitOffersRpc

Narrow RPC surface consumed by PermitOffersState. Consumers adapt their
typed client (e.g. a create_rpc_client Proxy) to this shape — the state
class stays decoupled from the client's Result return type so tests can
inject plain-function stubs.

`list`

type () => Promise<{offers: Array<PermitOfferJson>}>

`history`

type

(options?: {
		limit?: number;
		offset?: number;
	}) => Promise<{offers: Array<PermitOfferJson>}>

`create`

type

(params: {
		to_account_id: string;
		role: string;
		scope_id?: string | null;
		message?: string | null;
	}) => Promise<{offer: PermitOfferJson}>

`accept`

type

(offer_id: string) => Promise<{
		permit_id: string;
		offer: PermitOfferJson;
		superseded_offer_ids: Array<string>;
	}>

`decline`

type (offer_id: string, reason?: string | null) => Promise<{ok: true}>

`retract`

type (offer_id: string) => Promise<{ok: true}>

PermitOffersState
#

inheritance

extends:

Loadable

`incoming`

Pending offers for the current account, soonest-expiring first.

type Array<PermitOfferJson>

readonly

`outgoing`

Pending offers from the current actor, newest-created first.

type Array<PermitOfferJson>

readonly

`history`

Every offer known to this state, newest-created first. Feeds the history view.

type Array<PermitOfferJson>

readonly

`incoming_count`

type number

readonly

`constructor`

type new (options: PermitOffersStateOptions): PermitOffersState

`options`

type PermitOffersStateOptions

`fetch`

Seed the cache with the recipient-side pending inbox.

type (): Promise<void>

returns Promise<void>

`fetch_history`

Seed both-directions history (includes terminal rows).

type (options?: { limit?: number | undefined; offset?: number | undefined; } | undefined): Promise<void>

`options?`

type { limit?: number | undefined; offset?: number | undefined; } | undefined

optional

returns Promise<void>

`create`

Issue a new offer; merges the returned offer into the cache on success.

type (params: { to_account_id: string; role: string; scope_id?: string | null | undefined; message?: string | null | undefined; }): Promise<{ id: string & $brand<"Uuid">; from_actor_id: string & $brand<...>; ... 11 more ...; resulting_permit_id: (string & $brand<...>) | null; } | undefined>

`params`

type { to_account_id: string; role: string; scope_id?: string | null | undefined; message?: string | null | undefined; }

returns

Promise<{ id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<...>) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; } | undefined>

`accept`

Accept an offer; stamps it terminal in the cache and drops any siblings the server superseded.

type (offer_id: string): Promise<void>

`offer_id`

type string

returns Promise<void>

`decline`

type (offer_id: string, reason?: string | null | undefined): Promise<void>

`offer_id`

type string

`reason?`

type string | null | undefined

optional

returns Promise<void>

`retract`

type (offer_id: string): Promise<void>

`offer_id`

type string

returns Promise<void>

`subscribe`

Wire a notification subscription. The handler dispatches each matching
notification into apply_notification; the returned disposer unwires.

type (subscribe_fn: PermitOfferSubscribe): () => void

`subscribe_fn`

type PermitOfferSubscribe

returns () => void

`apply_notification`

Reduce a single WS notification into the cache. Exposed so consumers
wiring their WS receiver directly (without subscribe) and tests can
drive the reducer without allocating a subscription.

type (notification: PermitOfferNotification): void

`notification`

type PermitOfferNotification

returns void

`reset`

Clear the cache and reset loading/error state.

type (): void

returns void

PermitOffersStateOptions
#

PermitOffersStateOptions

`rpc`

type PermitOffersRpc

`account_id`

Reactive accessor for the current account id; returns null when logged out.

type () => string | null

`actor_id`

Reactive accessor for the current actor id — required to classify
offers as outgoing. Returns null when unknown.

type () => string | null

PermitOfferSubscribe
#

PermitOfferSubscribe

Subscription primitive — consumer wires their WS receiver; returns a disposer.

PermitOfferSupersedeParams
#

ZodObject<{ offer: ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; from_actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; to_account_id: $ZodBranded<ZodUUID, "Uuid", "out">; ... 10 more ...; resulting_permit_id: ZodNullable<...>; }, $strict>; reason: ZodEnum<...>; cause_id: $ZodBranded<...>; }, $strict>

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.

PermitRevokeInput
#

ZodObject<{ actor_id: $ZodBranded<ZodUUID, "Uuid", "out">; permit_id: $ZodBranded<ZodUUID, "Uuid", "out">; reason: ZodOptional<ZodNullable<ZodString>>; }, $strict>

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.

PermitRevokeOutput
#

ZodObject<{ ok: ZodLiteral<true>; revoked: ZodLiteral<true>; }, $strict>

Output for permit_revoke.

PermitRevokeParams
#

ZodObject<{ permit_id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_id: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; reason: ZodNullable<...>; }, $strict>

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.

PermitSummaryJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; role: ZodString; scope_id: ZodNullable<$ZodBranded<ZodUUID, "Uuid", "out">>; created_at: ZodString; expires_at: ZodNullable<...>; granted_by: ZodNullable<...>; }, $strict>

Zod schema for the permit summary returned in admin account listings.

pick_auth_headers
#

ui/PopoverButton.svelte view source

(spec: RouteSpec, test_app: TestApp, authed_account: TestAccount, admin_account: TestAccount): Record<string, string>

Pick request headers matching a route spec's auth requirement.
Maps RouteAuth onto a test account's credentials:
- none — origin headers only
- authenticated — the authed account's session cookie
- role: admin — the admin account's session cookie
- role: <other> — the test app's bootstrapped keeper session
- keeper — the test app's daemon token

`spec`

type RouteSpec

`test_app`

type TestApp

`authed_account`

type TestAccount

`admin_account`

type TestAccount

returns

Record<string, string>

Popover
#

PopoverButton
#

`position?`

type Position | undefined

optional

`align?`

type Alignment | undefined

optional

`disable_outside_click?`

type boolean | undefined

optional

`popover_class?`

type string | undefined

optional

`popover_attrs?`

type SvelteHTMLElements['div'] | undefined

optional

`popover_content`

type Snippet<[popover: Popover]>

`popover_container_attrs?`

type SvelteHTMLElements['div'] | undefined

optional

`button?`

type Snippet<[popover: Popover]> | undefined

optional

`children?`

type Snippet<[popover: Popover]> | undefined

optional

PopoverContentParameters
#

PopoverContentParameters

Parameters for the popover content action.

inheritance

extends:

PopoverParameters

PopoverParameters
#

PopoverParameters

Parameters for configuring the popover.

`position`

Position of the popover relative to its trigger.

type Position

`align`

Alignment along the position edge.

type Alignment

`offset`

Distance from the position.

type string

`disable_outside_click`

Whether to disable closing when clicking outside.

type boolean

`popover_class`

Custom class for the popover content.

type string

`onshow`

Optional callback when popover is shown.

type () => void

`onhide`

Optional callback when popover is hidden.

type () => void

PopoverTriggerParameters
#

PopoverTriggerParameters

Parameters for the popover trigger action.

inheritance

extends:

PopoverParameters

`content`

Content to render in the popover (as a snippet).

type Snippet

Position
#

Position

Extended position options including overlay and center.

prefix_route_specs
#

(prefix: string, specs: RouteSpec[]): RouteSpec[]

Prepend a prefix to all route spec paths.

`prefix`

the path prefix (e.g. /api/account)

type string

`specs`

type RouteSpec[]

returns

RouteSpec[]

a new array — the input specs are not mutated

PrimaryKeyInfo
#

PrimaryKeyInfo

Primary key constraint info.

`column_name`

type string

process_session_cookie
#

<TIdentity>(signed_value: string | undefined, keyring: Keyring, options: SessionOptions<TIdentity>, now_seconds?: number | undefined): Promise<ProcessSessionResult<TIdentity>>

Process a session cookie and determine what action to take.

`signed_value`

the raw cookie value (may be undefined)

type string | undefined

`keyring`

key ring for verification and signing

type Keyring

`options`

session configuration

type SessionOptions<TIdentity>

`now_seconds?`

current time in seconds (for testing)

type number | undefined

optional

returns

Promise<ProcessSessionResult<TIdentity>>

result with validity and action to take

ProcessDeps
#

ProcessDeps

Process lifecycle.

`exit`

Exit the process with a code.

type (code: number) => never

ProcessSessionResult
#

ProcessSessionResult<TIdentity>

Result of processing a session cookie.

generics

`TIdentity`

`valid`

Whether the session is valid.

type boolean

`action`

Action the adapter should take.

type 'none' | 'clear' | 'refresh'

`new_signed_value`

New signed value when action is 'refresh'.

type string

`identity`

The decoded identity if the cookie was valid.

type TIdentity

PROTOCOL_ACTION_METHODS
#

actions/protocol.ts view source

readonly ["heartbeat", "cancel"]

Method names of fuz_app's protocol actions — heartbeat (auth-aware client
liveness probe) and cancel (request-scoped abort signal). Consumers spread
this list when filtering backend request_response methods so the
dispatcher-owned protocol actions don't show up in
BackendRequestResponseMethod / handler maps. Pairs with protocol_actions
/ protocol_action_specs from actions/protocol.ts (the runtime bundles).

protocol_action_specs
#

readonly ({ method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } ...

Canonical protocol specs for ActionRegistry construction on the
frontend. Spread before consumer-owned specs so dispatcher-owned methods
are present in the lookup map even though codegen excludes them from the
generated action_specs array:
new ActionRegistry([...protocol_action_specs, ...action_specs])Derived from protocol_actions so a future protocol action lands in one
place — the two arrays cannot drift.

protocol_actions
#

actions/protocol.ts view source

readonly Action<BaseHandlerContext>[]

Canonical protocol {spec, handler} tuples for the server's
register_action_ws actions array. Spread before consumer-owned actions
so disconnect detection and per-request cancel work uniformly:
register_action_ws({actions: [...protocol_actions, ...consumer_actions], ...})

ProtocolActionMethod
#

"heartbeat" | "cancel"

Methods that ship from fuz_app, kept out of consumer-owned method enums + handler maps.

provide_admin_rpc_contexts
#

(adapters: AdminRpcAdapters, options?: ProvideAdminRpcContextsOptions | undefined): void

Wire all four admin RPC contexts in a single call.
Call once at the admin shell layout (e.g. src/routes/admin/+layout.svelte)
with adapters built from create_admin_rpc_adapters. Every Admin*.svelte
component that reads a context below this point sees the adapters.
Each context accessor reads adapters.{domain} on every invocation, so
mutating an adapter field on the same object propagates. Replacing the
whole adapter set requires calling provide_admin_rpc_contexts again
during init — in practice this is one-shot at layout mount.
Pass options.format_scope to render permit/offer scope_id values as
human labels across AdminAccounts, AdminPermitHistory,
PermitOfferInbox, PermitOfferForm, and PermitOfferHistory.
Components that accept a format_scope prop honor the prop first; the
context is the fallback.

`adapters`

type AdminRpcAdapters

`options?`

type ProvideAdminRpcContextsOptions | undefined

optional

returns

void

ProvideAdminRpcContextsOptions
#

ProvideAdminRpcContextsOptions

Optional knobs alongside the adapters when wiring admin contexts.

`format_scope`

Render {scope_id, role} as a human label across permit-display
components. Omit (or return null) to fall back to the raw uuid.

type FormatScope

ProxyOptions
#

ProxyOptions

Configuration for trusted proxy resolution.

`trusted_proxies`

Trusted proxy IPs or CIDR ranges (e.g. '127.0.0.1', '10.0.0.0/8', '::1').

type Array<string>

`get_connection_ip`

Extract the raw TCP connection IP from the Hono context.

type (c: Context) => string | undefined

`log`

Optional logger for proxy resolution diagnostics.

type Logger

query_accept_offer
#

(deps: QueryDeps, input: AcceptOfferInput): Promise<AcceptOfferResult>

Accept an offer atomically: mark accepted, insert the permit, stamp
resulting_permit_id, supersede sibling pending offers for the same
(to_account, role, scope), and emit permit_offer_accept +
permit_grant + one permit_offer_supersede per sibling. Must run
inside a transaction — the caller's route spec should declare
transaction: true (or wrap explicitly).
Idempotent on race: if a second concurrent call observes the offer
already accepted, returns the existing permit rather than creating a
duplicate or throwing.
Error map:
- PermitOfferNotFoundError — offer does not exist, or belongs to a
  different recipient (IDOR guard). The offer row is untouched.
- PermitOfferAlreadyTerminalError — offer is declined, retracted, or
  superseded.
- PermitOfferExpiredError — offer is pending but past expires_at.
Sibling supersede is what closes the "accept a pre-revoke sibling offer
to bypass a revoke" path: once A is accepted, B/C/... can no longer be
accepted even if the resulting permit is later revoked.

`deps`

type QueryDeps

`input`

type AcceptOfferInput

returns

Promise<AcceptOfferResult>

throws

PermitOfferNotFoundError - if the offer is missing or belongs to another recipient
PermitOfferAlreadyTerminalError - if the offer is declined, retracted, or superseded
PermitOfferExpiredError - if the offer is pending but past `expires_at`
Error - if the accepting account has no actor (1:1 invariant) or invariant assertions fail

query_account_by_email
#

(deps: QueryDeps, email: string): Promise<Account | undefined>

Find an account by email (case-insensitive).

`deps`

type QueryDeps

`email`

type string

returns

Promise<Account | undefined>

query_account_by_id
#

(deps: QueryDeps, id: string): Promise<Account | undefined>

Find an account by id.

`deps`

type QueryDeps

`id`

type string

returns

Promise<Account | undefined>

query_account_by_username
#

(deps: QueryDeps, username: string): Promise<Account | undefined>

Find an account by username (case-insensitive).

`deps`

type QueryDeps

`username`

type string

returns

Promise<Account | undefined>

query_account_by_username_or_email
#

(deps: QueryDeps, input: string): Promise<Account | undefined>

Find an account by username or email.
If the input contains @, tries email lookup first then username.
Otherwise tries username first then email. This supports a single
login field that accepts either format.

`deps`

query dependencies

type QueryDeps

`input`

username or email address

type string

returns

Promise<Account | undefined>

the matching account, or undefined

query_account_has_any
#

(deps: QueryDeps): Promise<boolean>

Check if any account exists.

`deps`

type QueryDeps

returns

Promise<boolean>

query_actor_by_account
#

(deps: QueryDeps, account_id: string): Promise<Actor | undefined>

Find the actor for an account.
For v1, each account has exactly one actor.

`deps`

type QueryDeps

`account_id`

type string

returns

Promise<Actor | undefined>

query_actor_by_id
#

(deps: QueryDeps, id: string): Promise<Actor | undefined>

Find an actor by id.

`deps`

type QueryDeps

`id`

type string

returns

Promise<Actor | undefined>

query_admin_account_list
#

(deps: QueryDeps): Promise<{ account: { id: string & $brand<"Uuid">; username: string; email: string | null; email_verified: boolean; created_at: string; updated_at: string; updated_by: (string & $brand<...>) | null; }; actor: { ...; } | null; permits: { ...; }[]; pending_offers: { ...; }[]; }[]>

List all accounts with their actors, active permits, and pending inbound
permit offers for admin display.
Uses 4 flat queries instead of N+1 per-account loops. Pending offers surface
the "offer pending — awaiting acceptance" UX without a second round-trip;
message is intentionally excluded (cross-admin visibility of grantor notes
would expand beyond what the audit log discloses).

`deps`

query dependencies

type QueryDeps

returns

Promise<{ account: { id: string & $brand<"Uuid">; username: string; email: string | null; email_verified: boolean; created_at: string; updated_at: string; updated_by: (string & $brand<"Uuid">) | null; }; actor: { ...; } | null; permits: { ...; }[]; pending_offers: { ...; }[]; }[]>

admin account entries sorted by creation date

query_api_token_enforce_limit
#

(deps: QueryDeps, account_id: string, max_tokens: number): Promise<number>

Enforce a per-account token limit by evicting the oldest tokens.
Race safety: this function must run inside a transaction alongside the
INSERT that created the new token. The caller (the account_token_create
RPC handler) runs under the dispatcher's transaction path because the
spec declares side_effects: true, ensuring the INSERT + enforce_limit
pair is atomic — concurrent token creation cannot interleave.

`deps`

query dependencies (must be transaction-scoped)

type QueryDeps

`account_id`

the account to enforce the limit for

type string

`max_tokens`

maximum number of tokens to keep

type number

returns

Promise<number>

the number of tokens evicted

query_api_token_list_for_account
#

auth/app_settings_queries.ts view source

(deps: QueryDeps, account_id: string): Promise<Omit<ApiToken, "token_hash">[]>

List all tokens for an account (does not include hashes).
Columns are enumerated explicitly to exclude token_hash.
Must be updated if the api_token table gains new columns.

`deps`

type QueryDeps

`account_id`

type string

returns

Promise<Omit<ApiToken, "token_hash">[]>

query_app_settings_load
#

(deps: QueryDeps): Promise<AppSettings>

Load the current app settings.

`deps`

query dependencies

type QueryDeps

returns

Promise<AppSettings>

the app settings row

throws

Error - if the singleton `app_settings` row is missing (migration drift — should not occur in practice)

query_app_settings_load_with_username
#

auth/app_settings_queries.ts view source

(deps: QueryDeps): Promise<{ open_signup: boolean; updated_at: string | null; updated_by: (string & $brand<"Uuid">) | null; updated_by_username: string | null; }>

Load the current app settings with resolved updater username.

`deps`

query dependencies

type QueryDeps

returns

Promise<{ open_signup: boolean; updated_at: string | null; updated_by: (string & $brand<"Uuid">) | null; updated_by_username: string | null; }>

the app settings with updated_by_username

throws

Error - if the singleton `app_settings` row is missing

query_app_settings_update
#

auth/app_settings_queries.ts view source

(deps: QueryDeps, open_signup: boolean, actor_id: string): Promise<AppSettings>

Update app settings and return the updated row.

`deps`

query dependencies

type QueryDeps

`open_signup`

new value for the open_signup toggle

type boolean

`actor_id`

the actor making the change

type string

returns

Promise<AppSettings>

the updated app settings row

throws

Error - if the singleton `app_settings` row is missing

query_audit_log
#

<T extends string>(deps: QueryDeps, input: AuditLogInput<T>, config?: AuditLogConfig): Promise<AuditLogEvent>

Insert an audit log entry.
RETURNING * so callers receive DB-assigned fields (id, seq,
created_at). Validates metadata against config.metadata_schemas;
unknown event_type and metadata mismatches log + bump their counters
but write the row anyway. Consumers extend the recognized set via
create_audit_log_config({extra_events}).

`deps`

query dependencies

type QueryDeps

`input`

the audit event to record

type AuditLogInput<T>

`config`

audit-log config. Defaults to BUILTIN_AUDIT_LOG_CONFIG.

type AuditLogConfig

default BUILTIN_AUDIT_LOG_CONFIG

returns

Promise<AuditLogEvent>

the inserted audit log row

query_audit_log_cleanup_before
#

(deps: QueryDeps, before: Date): Promise<number>

Delete audit log entries older than the given date.

`deps`

query dependencies

type QueryDeps

`before`

delete entries created before this date

type Date

returns

Promise<number>

the number of entries deleted

query_audit_log_list
#

(deps: QueryDeps, options?: AuditLogListOptions | undefined): Promise<AuditLogEvent[]>

List audit log entries, newest first.

`deps`

query dependencies

type QueryDeps

`options?`

filters and pagination

type AuditLogListOptions | undefined

optional

returns

Promise<AuditLogEvent[]>

matching audit log entries

query_audit_log_list_for_account
#

(deps: QueryDeps, account_id: string, limit?: number): Promise<AuditLogEvent[]>

List audit log entries related to an account (as actor or target).

`deps`

query dependencies

type QueryDeps

`account_id`

the account to query for

type string

`limit`

maximum entries to return

type number

default AUDIT_LOG_DEFAULT_LIMIT

returns

Promise<AuditLogEvent[]>

query_audit_log_list_permit_history
#

(deps: QueryDeps, limit?: number, offset?: number): Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; actor_id: (string & $brand<...>) | null; ... 6 more ...; target_username: string | null; }[]>

List permit grant/revoke events with resolved usernames.

`deps`

query dependencies

type QueryDeps

`limit`

maximum entries to return

type number

default AUDIT_LOG_DEFAULT_LIMIT

`offset`

number of entries to skip

type number

default 0

returns

Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; actor_id: (string & $brand<"Uuid">) | null; account_id: (string & $brand<...>) | null; ... 5 more ...; target_username: string | null; }[]>

permit history events with username and target_username

query_audit_log_list_with_usernames
#

(deps: QueryDeps, options?: AuditLogListOptions | undefined): Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; ... 7 more ...; target_username: string | null; }[]>

List audit log entries with resolved usernames, newest first.

`deps`

query dependencies

type QueryDeps

`options?`

filters and pagination

type AuditLogListOptions | undefined

optional

returns

Promise<{ id: string & $brand<"Uuid">; seq: number; event_type: string; outcome: "success" | "failure"; actor_id: (string & $brand<"Uuid">) | null; account_id: (string & $brand<...>) | null; ... 5 more ...; target_username: string | null; }[]>

matching audit log entries with username and target_username

query_create_account
#

(deps: QueryDeps, input: CreateAccountInput): Promise<Account>

Create a new account.

`deps`

query dependencies

type QueryDeps

`input`

the account fields

type CreateAccountInput

returns

Promise<Account>

the created account

query_create_account_with_actor
#

(deps: QueryDeps, input: CreateAccountInput): Promise<{ account: Account; actor: Actor; }>

Create an account and its actor in a single operation.
For v1, every account gets exactly one actor with the same name as the username.

`deps`

query dependencies

type QueryDeps

`input`

the account fields

type CreateAccountInput

returns

Promise<{ account: Account; actor: Actor; }>

the created account and actor

query_create_actor
#

(deps: QueryDeps, account_id: string, name: string): Promise<Actor>

Create a new actor for an account.

`deps`

query dependencies

type QueryDeps

`account_id`

the owning account

type string

`name`

display name (defaults to account username)

type string

returns

Promise<Actor>

the created actor

query_create_api_token
#

(deps: QueryDeps, id: string, account_id: string, name: string, token_hash: string, expires_at?: Date | null | undefined): Promise<ApiToken>

Store a new API token (the hash, not the raw token).

`deps`

query dependencies

type QueryDeps

`id`

the public token id (e.g. tok_abc123)

type string

`account_id`

the owning account

type string

`name`

human-readable name

type string

`token_hash`

blake3 hash of the raw token

type string

`expires_at?`

optional expiration

type Date | null | undefined

optional

returns

Promise<ApiToken>

the stored token record

query_create_invite
#

(deps: QueryDeps, input: CreateInviteInput): Promise<Invite>

Create a new invite.

`deps`

query dependencies

type QueryDeps

`input`

the invite fields

type CreateInviteInput

returns

Promise<Invite>

the created invite

query_create_session
#

(deps: QueryDeps, token_hash: string, account_id: string, expires_at: Date): Promise<void>

Create a new auth session.

`deps`

query dependencies

type QueryDeps

`token_hash`

blake3 hash of the session token (use hash_session_token)

type string

`account_id`

the account this session belongs to

type string

`expires_at`

when the session expires

type Date

returns

Promise<void>

query_db_status
#

(db: Db, namespaces?: MigrationNamespace[] | undefined): Promise<DbStatus>

Query database status including connectivity, tables, and migration state.
Designed for CLI db:status commands. Does not modify the database.

`db`

the database instance

type Db

`namespaces?`

migration namespaces to check status for

type MigrationNamespace[] | undefined

optional

returns

Promise<DbStatus>

a snapshot of database status; connected: false with error
set when the initial connectivity probe fails

throws

Error - propagated from the driver if a query fails after the

query_delete_account
#

(deps: QueryDeps, id: string): Promise<boolean>

Delete an account. Cascades to actors, permits, sessions, and tokens.

`deps`

type QueryDeps

`id`

type string

returns

Promise<boolean>

query_grant_permit
#

(deps: QueryDeps, input: GrantPermitInput): Promise<Permit>

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.

`deps`

query dependencies

type QueryDeps

`input`

the permit fields

type GrantPermitInput

returns

Promise<Permit>

the created or existing active permit

query_invite_claim
#

(deps: QueryDeps, invite_id: string, account_id: string): Promise<boolean>

Claim an invite by setting the claimed_by and claimed_at fields.

`deps`

query dependencies

type QueryDeps

`invite_id`

the invite to claim

type string

`account_id`

the account claiming the invite

type string

returns

Promise<boolean>

true if the invite was claimed, false if already claimed or not found

query_invite_delete_unclaimed
#

(deps: QueryDeps, id: string): Promise<boolean>

Delete an unclaimed invite.

`deps`

query dependencies

type QueryDeps

`id`

the invite id

type string

returns

Promise<boolean>

true if deleted, false if not found or already claimed

query_invite_find_unclaimed_by_email
#

(deps: QueryDeps, email: string): Promise<Invite | undefined>

Find an unclaimed invite by email (case-insensitive).

`deps`

type QueryDeps

`email`

type string

returns

Promise<Invite | undefined>

query_invite_find_unclaimed_by_username
#

(deps: QueryDeps, username: string): Promise<Invite | undefined>

Find an unclaimed invite by username (case-insensitive).

`deps`

type QueryDeps

`username`

type string

returns

Promise<Invite | undefined>

query_invite_find_unclaimed_match
#

(deps: QueryDeps, email: string | null, username: string): Promise<Invite | undefined>

Find an unclaimed invite matching email and/or username using three scoping modes:
- Email-only invite (email set, username NULL) → matches only if signup provides matching email.
- Username-only invite (username set, email NULL) → matches only if signup provides matching username.
- Both-field invite (both set) → requires BOTH email and username to match.

`deps`

query dependencies

type QueryDeps

`email`

email to match (or null if signup provides none)

type string | null

`username`

username to match

type string

returns

Promise<Invite | undefined>

the matching invite, or undefined

query_invite_list_all
#

(deps: QueryDeps): Promise<Invite[]>

List all invites, newest first.

`deps`

type QueryDeps

returns

Promise<Invite[]>

query_invite_list_all_with_usernames
#

(deps: QueryDeps): Promise<{ id: string & $brand<"Uuid">; email: string | null; username: string | null; claimed_by: (string & $brand<"Uuid">) | null; ... 4 more ...; claimed_by_username: string | null; }[]>

List all invites with resolved creator/claimer usernames, newest first.

`deps`

query dependencies

type QueryDeps

returns

Promise<{ id: string & $brand<"Uuid">; email: string | null; username: string | null; claimed_by: (string & $brand<"Uuid">) | null; claimed_at: string | null; created_at: string; created_by: (string & $brand<...>) | null; created_by_username: string | null; claimed_by_username: string | null; }[]>

invites with created_by_username and claimed_by_username

query_permit_find_account_id_for_role
#

(deps: QueryDeps, role: string): Promise<string | null>

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.

`deps`

query dependencies

type QueryDeps

`role`

the role to search for

type string

returns

Promise<string | null>

the account ID, or null

query_permit_find_active_for_actor
#

(deps: QueryDeps, actor_id: string): Promise<Permit[]>

Find all active (non-revoked, non-expired) permits for an actor.

`deps`

type QueryDeps

`actor_id`

type string

returns

Promise<Permit[]>

query_permit_find_active_role_for_actor
#

(deps: QueryDeps, permit_id: string, actor_id: string): Promise<{ role: string; } | null>

Look up the role of an active permit, constrained to a specific actor.
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.
Returns null if the permit is not found, already revoked, or
belongs to a different actor.

`deps`

query dependencies

type QueryDeps

`permit_id`

the permit id to look up

type string

`actor_id`

the actor that must own the permit

type string

returns

Promise<{ role: string; } | null>

{role} on a match, or null

query_permit_has_role
#

(deps: QueryDeps, actor_id: string, role: string, scope_id?: string | null | undefined): Promise<boolean>

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.

`deps`

type QueryDeps

`actor_id`

type string

`role`

type string

`scope_id?`

type string | null | undefined

optional

returns

Promise<boolean>

query_permit_list_for_actor
#

(deps: QueryDeps, actor_id: string): Promise<Permit[]>

List all permits for an actor (including revoked/expired).

`deps`

type QueryDeps

`actor_id`

type string

returns

Promise<Permit[]>

query_permit_offer_create
#

(deps: QueryDeps, input: CreatePermitOfferInput): Promise<PermitOffer>

Create a new permit offer, or refresh an existing pending offer for the
same (to_account_id, role, scope_id, from_actor_id) tuple.
Re-offer semantics: a second call by the same grantor with the same
(to_account, role, scope) while pending upserts the existing row,
refreshing message and expires_at. A different grantor offering the
same (to_account, role, scope) creates a distinct row — multiple
pending grantors coexist. After a terminal state, a re-offer is a fresh
INSERT.
Self-offer rejection: throws PermitOfferSelfTargetError if the offering
actor belongs to the recipient account.

`deps`

type QueryDeps

`input`

type CreatePermitOfferInput

returns

Promise<PermitOffer>

throws

PermitOfferSelfTargetError - if the offering actor belongs to `to_account_id`

query_permit_offer_decline
#

(deps: QueryDeps, offer_id: string, to_account_id: string, reason: string | null): Promise<PermitOffer | null>

Mark an offer declined.
Guarded by to_account_id (IDOR). Returns null if the offer does not
exist or belongs to a different account. Throws
PermitOfferAlreadyTerminalError if the offer exists for the caller but
is already in a terminal state.

`deps`

type QueryDeps

`offer_id`

type string

`to_account_id`

type string

`reason`

type string | null

returns

Promise<PermitOffer | null>

throws

PermitOfferAlreadyTerminalError - if the offer is already accepted, declined, retracted, or superseded

query_permit_offer_find_pending
#

(deps: QueryDeps, offer_id: string): Promise<PermitOffer | null>

Look up a pending offer by id. Returns null if the offer is terminal,
expired (server-side filter), or missing.

`deps`

type QueryDeps

`offer_id`

type string

returns

Promise<PermitOffer | null>

query_permit_offer_history_for_account
#

(deps: QueryDeps, account_id: string, limit?: number, offset?: number): Promise<PermitOffer[]>

List every offer involving an account (either direction), newest first.
Includes terminal offers — used by the grantor-side admin / history view.

`deps`

type QueryDeps

`account_id`

type string

`limit`

type number

default 100

`offset`

type number

default 0

returns

Promise<PermitOffer[]>

query_permit_offer_list
#

(deps: QueryDeps, to_account_id: string): Promise<PermitOffer[]>

List pending, non-expired offers for an account, soonest expiry first.
Expired offers are filtered server-side (expires_at > NOW()) so the
inbox never surfaces a row that can no longer be accepted. The periodic
sweep (query_permit_offer_sweep_expired) handles audit tombstoning.

`deps`

type QueryDeps

`to_account_id`

type string

returns

Promise<PermitOffer[]>

query_permit_offer_retract
#

(deps: QueryDeps, offer_id: string, from_actor_id: string): Promise<PermitOffer | null>

Mark an offer retracted by the grantor.
Guarded by from_actor_id (IDOR). Returns null if the offer does not
exist or was issued by a different actor. Throws
PermitOfferAlreadyTerminalError if the offer exists for this grantor
but is already in a terminal state.

`deps`

type QueryDeps

`offer_id`

type string

`from_actor_id`

type string

returns

Promise<PermitOffer | null>

throws

PermitOfferAlreadyTerminalError - if the offer is already accepted, declined, retracted, or superseded

query_permit_offer_sweep_expired
#

(deps: QueryDeps): Promise<PermitOffer[]>

Return pending offers whose expires_at has passed.
Callers fire permit_offer_expire audit events for each row. The schema
does not tombstone the row, so callers are responsible for their own
idempotency (e.g. check whether a permit_offer_expire audit event
already exists for the offer id).

`deps`

type QueryDeps

returns

Promise<PermitOffer[]>

query_permit_revoke_for_scope
#

(deps: QueryDeps, scope_id: string & $brand<"Uuid">, revoked_by: (string & $brand<"Uuid">) | null, reason?: string | null | undefined): Promise<RevokeForScopeResult>

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.

`deps`

query dependencies

type QueryDeps

`scope_id`

the scope whose permits and offers to terminate

type string & $brand<"Uuid">

`revoked_by`

the actor performing the cascade (audit trail)

type (string & $brand<"Uuid">) | null

`reason?`

optional free-form reason, stamped on permit.revoked_reason.

type string | null | undefined

optional

returns

Promise<RevokeForScopeResult>

the revoked permits (with account_id for fan-out) and superseded offers (with from_account_id for fan-out)

query_permit_revoke_role
#

(deps: QueryDeps, actor_id: string, role: string, revoked_by: string | null, reason?: string | null | undefined): Promise<RevokeRoleResult>

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).

`deps`

query dependencies

type QueryDeps

`actor_id`

the actor whose permits to revoke

type string

`role`

the role to revoke

type string

`revoked_by`

the actor who revoked it (for audit trail)

type string | null

`reason?`

optional free-form reason, stamped on permit.revoked_reason.

type string | null | undefined

optional

returns

Promise<RevokeRoleResult>

the list of revoked permits (empty if none were active) and superseded pending offers

query_revoke_all_api_tokens_for_account
#

(deps: QueryDeps, account_id: string): Promise<number>

Revoke all tokens for an account.

`deps`

query dependencies

type QueryDeps

`account_id`

the account whose tokens to revoke

type string

returns

Promise<number>

the number of tokens revoked

query_revoke_api_token_for_account
#

(deps: QueryDeps, id: string, account_id: string): Promise<boolean>

Revoke a token only if it belongs to the specified account.
Prevents cross-account token revocation.

`deps`

query dependencies

type QueryDeps

`id`

the public token id

type string

`account_id`

the account that must own the token

type string

returns

Promise<boolean>

true if a token was revoked, false if not found or wrong account

query_revoke_permit
#

(deps: QueryDeps, permit_id: string & $brand<"Uuid">, actor_id: string & $brand<"Uuid">, revoked_by: (string & $brand<"Uuid">) | null, reason?: string | ... 1 more ... | undefined): Promise<...>

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.

`deps`

query dependencies

type QueryDeps

`permit_id`

the permit to revoke

type string & $brand<"Uuid">

`actor_id`

the actor that must own the permit

type string & $brand<"Uuid">

`revoked_by`

the actor who revoked it (for audit trail)

type (string & $brand<"Uuid">) | null

`reason?`

optional free-form reason, stamped on permit.revoked_reason and surfaced to the revokee notification.

type string | null | undefined

optional

returns

Promise<RevokePermitResult | null>

query_session_cleanup_expired
#

(deps: QueryDeps): Promise<number>

Delete expired sessions.

`deps`

type QueryDeps

returns

Promise<number>

the number of sessions cleaned up

query_session_enforce_limit
#

(deps: QueryDeps, account_id: string, max_sessions: number): Promise<number>

Enforce a per-account session limit by evicting the oldest sessions.
Keeps the newest max_sessions sessions and deletes the rest.
Race safety: this function must run inside a transaction alongside the
INSERT that created the new session. All callers satisfy this requirement:
- 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
The transaction ensures the INSERT + enforce_limit pair is atomic —
concurrent session creation cannot interleave between the two statements.

`deps`

query dependencies (must be transaction-scoped)

type QueryDeps

`account_id`

the account to enforce the limit for

type string

`max_sessions`

maximum number of sessions to keep

type number

returns

Promise<number>

the number of sessions evicted

query_session_get_valid
#

(deps: QueryDeps, token_hash: string): Promise<AuthSession | undefined>

Get a session if it exists, is not expired, and has not been revoked.

`deps`

query dependencies

type QueryDeps

`token_hash`

blake3 hash of the session token

type string

returns

Promise<AuthSession | undefined>

query_session_list_all_active
#

(deps: QueryDeps, limit?: number): Promise<(AuthSession & { username: string; })[]>

List all active sessions across all accounts with usernames.

`deps`

query dependencies

type QueryDeps

`limit`

maximum entries to return

type number

default 200

returns

Promise<(AuthSession & { username: string; })[]>

active sessions joined with account usernames, newest activity first

query_session_list_for_account
#

(deps: QueryDeps, account_id: string, limit?: number): Promise<AuthSession[]>

List sessions for an account, newest first.

`deps`

type QueryDeps

`account_id`

type string

`limit`

type number

default 50

returns

Promise<AuthSession[]>

query_session_revoke_all_for_account
#

(deps: QueryDeps, account_id: string): Promise<number>

Revoke all sessions for an account.

`deps`

type QueryDeps

`account_id`

type string

returns

Promise<number>

the number of sessions revoked

query_session_revoke_by_hash_unscoped
#

(deps: QueryDeps, token_hash: string): Promise<void>

Revoke (delete) a session by its token hash, with no account scoping.
The _unscoped suffix is the safety signal — there is no account_id
constraint, so callers must guarantee the hash came from a trusted
source (the authenticated session cookie path is the only safe production
caller — see auth/account_routes.ts /logout). For user-facing revocation
of a specific session by ID, use query_session_revoke_for_account
(IDOR-guarded).

`deps`

type QueryDeps

`token_hash`

type string

returns

Promise<void>

query_session_revoke_for_account
#

(deps: QueryDeps, token_hash: string, account_id: string): Promise<boolean>

Revoke a session only if it belongs to the specified account.
Prevents cross-account session revocation.

`deps`

query dependencies

type QueryDeps

`token_hash`

blake3 hash of the session token

type string

`account_id`

the account that must own the session

type string

returns

Promise<boolean>

true if a session was revoked, false if not found or wrong account

query_session_touch
#

(deps: QueryDeps, token_hash: string): Promise<void>

Update last_seen_at and optionally extend expiry for a session.
Extends if less than AUTH_SESSION_EXTEND_THRESHOLD_MS remaining.

`deps`

query dependencies

type QueryDeps

`token_hash`

blake3 hash of the session token

type string

returns

Promise<void>

query_update_account_password
#

(deps: QueryDeps, id: string, password_hash: string, updated_by: string | null): Promise<void>

Update the password hash for an account.

`deps`

type QueryDeps

`id`

type string

`password_hash`

type string

`updated_by`

type string | null

returns

Promise<void>

query_validate_api_token
#

db/query_deps.ts view source

(deps: ApiTokenQueryDeps, raw_token: string, ip: string | undefined, pending_effects: Promise<void>[] | undefined): Promise<ApiToken | undefined>

Validate a raw API token and return the token record.
Hashes the token with blake3, looks up the hash, and checks
expiration. Updates last_used_at and last_used_ip on success
(fire-and-forget — errors logged, never thrown).

`deps`

query dependencies with logger

type ApiTokenQueryDeps

`raw_token`

the raw API token from the Authorization header

type string

`ip`

the client IP address (for audit)

type string | undefined

`pending_effects`

optional array to register the usage-tracking effect for later awaiting

type Promise<void>[] | undefined

returns

Promise<ApiToken | undefined>

the token record if valid, or undefined

QueryDeps
#

QueryDeps

Base dependency for all query functions.

`db`

type Db

rate_limit_exceeded_response
#

(c: Context<any, any, {}>, retry_after: number): Response

Build a 429 rate-limit-exceeded JSON response with Retry-After header.

`c`

Hono context

type Context<any, any, {}>

`retry_after`

seconds until the client should retry

type number

returns

Response

a 429 Response

RateLimiter
#

In-memory sliding window rate limiter.
Stores an array of timestamps per key. On check/record, timestamps
outside the window are pruned. retry_after reports seconds until the
oldest active timestamp expires.
The backing store is an LruMap when options.max_keys is a positive
number (default DEFAULT_RATE_LIMITER_MAX_KEYS) and a plain Map when
max_keys is null. The LruMap path bounds memory under
key-enumeration attack at the cost of a slight per-op overhead and the
LRU trade-off described on RateLimiterOptions.max_keys.
Parameters that accept RateLimiter | null (e.g. ip_rate_limiter,
login_account_rate_limiter) silently disable rate limiting when null
is passed — no checks are performed and all requests are allowed through.

`options`

type RateLimiterOptions

readonly

`constructor`

type new (options: RateLimiterOptions): RateLimiter

`options`

type RateLimiterOptions

`check`

Check whether key is allowed without recording an attempt.
Prunes timestamps that fell outside the window as a side effect (and
removes the key entirely when none remain), so the backing map stays
bounded even under read-only traffic.

type (key: string, now?: number): RateLimitResult

`key`

rate limit key (e.g. IP address)

type string

`now`

current timestamp in ms (defaults to Date.now())

type number

default Date.now()

returns RateLimitResult

`record`

Record a failed attempt for key and return the updated result.

type (key: string, now?: number): RateLimitResult

`key`

rate limit key (e.g. IP address)

type string

`now`

current timestamp in ms (defaults to Date.now())

type number

default Date.now()

returns RateLimitResult

`reset`

Clear all attempts for key (e.g. after successful login).

type (key: string): void

`key`

type string

returns void

`cleanup`

Remove entries whose timestamps are all outside the window.

type (now?: number): void

`now`

current timestamp in ms (defaults to Date.now())

type number

default Date.now()

returns void

`dispose`

Stop the cleanup timer. Safe to call multiple times.

type (): void

returns void

RateLimiterOptions
#

RateLimiterOptions

Configuration for a rate limiter instance.

`max_attempts`

Maximum allowed attempts within the window.

type number

`window_ms`

Sliding window duration in milliseconds.

type number

`cleanup_interval_ms`

Interval for pruning stale entries (0 disables the timer).

type number

`max_keys`

Maximum tracked keys. When exceeded, the least-recently-used key is
evicted — bounds memory under key-enumeration attacks. Default:
DEFAULT_RATE_LIMITER_MAX_KEYS (100_000). Pass null to disable the
cap (falls back to an unbounded Map — only recommended when the key
set is known to be closed, e.g. a per-account limiter keyed to a
bounded-size account table).
LRU trade-off: every check / record call marks the key as
most-recently-used, so keys under active attack stay fresh and won't
be evicted. A slow-burn attacker spread across many low-volume keys
can, however, drop out of the table and reset their budget — set
max_keys high enough to fit the expected legitimate key set and
this stays theoretical.

type number | null

RateLimitError
#

testing/rate_limiting.ts view source

ZodObject<{ error: ZodLiteral<"rate_limit_exceeded">; retry_after: ZodNumber; }, $loose>

Rate limit error — returned when a rate limiter rejects the request.

RateLimitingTestOptions
#

RateLimitingTestOptions

Configuration for describe_rate_limiting_tests.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same one used in production.

type (ctx: AppServerContext) => Array<RouteSpec>

`app_options`

Optional overrides for AppServerOptions.

type SuiteAppOptions

`db_factories`

Database factories to run tests against. Default: pglite only.

type Array<DbFactory>

`max_attempts`

Maximum attempts before rate limiting kicks in.
Default: 2 (tight limit for fast tests).

type number

`rpc_endpoints`

RPC endpoint specs — required so the bearer-auth rate limiting test
can probe an authenticated method via the account_verify RPC
action. Hard-fails via require_rpc_endpoint_path on setup.
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> — the factory form
is required when action handlers must close over the per-test
ctx.app_settings / ctx.deps. The factory must return the same
endpoint path regardless of ctx — it is invoked once at setup with
a stub ctx for path lookup and again per-test by create_app_server
for live dispatch.

RateLimitKey
#

ZodEnum<{ both: "both"; ip: "ip"; account: "account"; }>

Rate limit key type — declares what a route or RPC action's rate limiter
is keyed on.
- 'ip' — per-IP rate limiting (bootstrap, password change, bearer auth)
- 'account' — per-account rate limiting. On REST auth routes the key is
  the submitted identifier (login). On RPC actions (post-auth) the key is
  the resolved actor id (request_context.actor.id) — separate namespace.
- 'both' — both keys.

RateLimitResult
#

RateLimitResult

Result of a rate limit check or record operation.

`allowed`

Whether the request is allowed.

type boolean

`remaining`

Remaining attempts before blocking.

type number

`retry_after`

Seconds until the oldest active attempt expires (0 if allowed).

type number

read_daemon_info
#

(runtime: Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & LogDeps, name: string): Promise<{ version: number; pid: number; port: number; started: string; app_version: string; } | null>

Read and validate daemon info from the PID file.

`runtime`

runtime with file read and env capabilities

type Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & LogDeps

`name`

application name

type string

returns

Promise<{ version: number; pid: number; port: number; started: string; app_version: string; } | null>

parsed daemon info, or null if missing or invalid

read_env_var
#

(deps: Pick<FsReadDeps, "stat" | "read_text_file">, env_path: string, name: string): Promise<string | undefined>

Read a single env var from a dotenv-style file.

`deps`

file read capability

type Pick<FsReadDeps, "stat" | "read_text_file">

`env_path`

path to the .env file

type string

`name`

the variable name to read

type string

returns

Promise<string | undefined>

the value, or undefined if the file or variable doesn't exist

ReadTextFromOffsetResult
#

ReadTextFromOffsetResult

Result of reading text from a byte offset.

`content`

Decoded text content read from the offset.

type string

`bytes_read`

Number of bytes actually read.

type number

`file_size`

Total file size at the time of the read (for truncation detection).

type number

refresh_permits
#

(ctx: RequestContext, deps: QueryDeps): Promise<RequestContext>

Reload active permits from the database, returning a new request context.
Useful for long-lived WebSocket connections where permits may change
(grant or revoke) during the connection lifetime. Call periodically
or after receiving a revocation signal.
Returns a new RequestContext with updated permits — the original
context is not mutated, making concurrent calls safe.

`ctx`

the request context to refresh

type RequestContext

`deps`

query dependencies

type QueryDeps

returns

Promise<RequestContext>

a new RequestContext with fresh permits

register_action_ws
#

actions/register_ws_endpoint.ts view source

<TCtx extends BaseHandlerContext>(options: RegisterActionWsOptions<TCtx>): RegisterActionWsResult

Mount a JSON-RPC WebSocket endpoint that dispatches to the supplied handler
map. Per-request context is built from the base + consumer-provided
RegisterActionWsOptions.extend_context.
Wire behavior:
- Batch JSON-RPC is rejected (single-message only).
- Notifications (method + no id) are silently dropped per JSON-RPC spec.
- Per-action auth: public / authenticated pass through (upgrade auth
  already verified identity); keeper requires daemon_token credential
  type *and* the keeper role; role-based {role} requires the named role
  via has_role, matching the HTTP path in actions/action_rpc.ts.
- DEV mode validates handler output against the spec's output schema and
  warns on mismatches.

`options`

type RegisterActionWsOptions<TCtx>

returns

RegisterActionWsResult

the transport (supplied or freshly created) — retain it to wire
create_ws_auth_guard or broadcast on audit events.

register_ws_endpoint
#

<TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>): RegisterActionWsResult

Mount a WebSocket endpoint with the standard upgrade stack (origin check
+ auth + optional role) and JSON-RPC dispatch.
Returns the BackendWebsocketTransport (supplied or freshly
created), same as register_action_ws — retain it to wire
create_ws_auth_guard on on_audit_event or to broadcast.

`options`

type RegisterWsEndpointOptions<TCtx>

returns

RegisterActionWsResult

RegisterActionWsOptions
#

RegisterActionWsOptions<TCtx>

Options for register_action_ws.

generics

`TCtx`

constraint BaseHandlerContext

`path`

Mount path (e.g., /api/ws).

type string

`app`

The Hono app to mount on.

type Hono

`upgradeWebSocket`

Hono's upgradeWebSocket helper from the runtime adapter.

type UpgradeWebSocket

`actions`

The actions registered on this endpoint — each carries a spec (drives
method lookup, per-action auth, input/output validation) and an
optional handler (omit for client-only specs like inbound
notifications). Spread protocol_actions from actions/protocol.ts
here to complete the disconnect-detection + per-request cancel
pairing with the frontend client.

type ReadonlyArray<Action<TCtx>>

`extend_context`

Build the per-request context from the base and the upgrade-time Hono
context. Called once per incoming message. Consumers use this to attach
domain singletons (backend) or per-socket auth (auth,
credential_type) without re-reading them from c inside every handler.

type (base: BaseHandlerContext, c: Context) => TCtx

`transport`

Existing transport to register connections with. When omitted, a fresh
one is created and returned in the result. Pass your own to keep a
handle for create_ws_auth_guard and send_to/broadcast.

`heartbeat`

Server-side heartbeat policy. Default-on (receive-silence detection,
60s timeout). false disables the timer entirely — only do this if
the upstream stack (TCP keepalive, Cloudflare idle timeout, etc.)
already owns disconnect detection. Pass an object to tune the timeout.

type boolean | ServerHeartbeatOptions

`artificial_delay`

Optional per-message delay for testing loading states. Ignored when 0.

type number

`log`

Optional logger; defaults to [ws] namespace.

type LoggerType

`on_socket_open`

Called once per socket, after the transport registers the connection.
Awaited before any message is dispatched. Throwing logs an error and
closes the socket with an internal_error frame — a failing bootstrap
should not leave a partially-initialized socket alive.

type (ctx: SocketOpenContext) => void | Promise<void>

`on_socket_close`

Called once per socket on close, *before* the transport removes the
connection. Receives connection_id and identity captured at open
time, so it is safe to read even when the audit guard has already torn
down the transport's internal state. Errors are logged and swallowed.

type (ctx: SocketCloseContext) => void | Promise<void>

`action_ip_rate_limiter`

Per-IP rate limiter consulted for actions whose spec declares
rate_limit: 'ip' or 'both'. null (or omitted) disables the
IP check. Same limiter is shared with the HTTP RPC dispatcher so
one budget covers both transports per action. Resolved at upgrade
time and reused for every message on the socket.

type RateLimiter | null

`action_account_rate_limiter`

Per-actor rate limiter consulted for actions whose spec declares
rate_limit: 'account' or 'both'. Keyed on
request_context.actor.id. null (or omitted) disables the
account check. Same limiter is shared with the HTTP RPC dispatcher.

type RateLimiter | null

RegisterActionWsResult
#

RegisterActionWsResult

Result of register_action_ws.

`transport`

The transport bound to the endpoint — supplied or freshly created.

actions/register_ws_endpoint.ts view source

RegisterWsEndpointOptions
#

RegisterWsEndpointOptions<TCtx>

Options for register_ws_endpoint.

generics

`TCtx`

constraint BaseHandlerContext

inheritance

extends:

RegisterActionWsOptions<TCtx>

`allowed_origins`

Origin allowlist regexes — typically parsed from the ALLOWED_ORIGINS
env var via parse_allowed_origins. Passed straight to
verify_request_source.

type Array<RegExp>

`required_role`

Role required to upgrade. Omit for any authenticated account (require_auth
alone); set to e.g. ROLE_ADMIN to gate the endpoint behind a role. The
per-action auth in each spec still applies at dispatch time — this is
a coarse upgrade-time gate.

type RoleName

RemoteNotificationActionSpec
#

ZodObject<{ method: ZodString; initiator: ZodEnum<{ frontend: "frontend"; backend: "backend"; both: "both"; }>; input: ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodType<...>>; ... 8 more ...; async: ZodDefault<...>; }, $strict>

REQUEST_CONTEXT_KEY
#

"request_context"

Hono context variable name for the request context.

RequestContext
#

RequestContext

The resolved identity context for an authenticated request.

`account`

type Account

`actor`

type Actor

`permits`

type Array<Permit>

RequestResponseActionSpec
#

actions/request_tracker.svelte.ts view source

ZodObject<{ method: ZodString; initiator: ZodEnum<{ frontend: "frontend"; backend: "backend"; both: "both"; }>; side_effects: ZodBoolean; input: ZodCustom<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>, ZodType<...>>; ... 7 more ...; async: ZodDefault<...>; }, $strict>

RequestTracker
#

Reactive pending-request store with per-request timeouts. Used by transports
that don't delegate request/response correlation to a WebsocketRpcConnection.

`pending_requests`

type SvelteMap<JsonrpcRequestId, RequestTrackerItem>

readonly

`request_timeout_ms`

type number

readonly

`constructor`

type new (request_timeout_ms?: number): RequestTracker

`request_timeout_ms`

type number

default 120_000

`track_request`

Track a new request keyed by id.

type (id: string | number): Deferred<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | ... 4 more ... | (number & $brand<...>); message: string; data?: unknown; }; }>

`id`

type string | number

returns

Deferred<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }...

deferred resolved on response, or rejected via the timeout

`resolve_request`

Resolve a pending request with its response.

type (id: string | number, response: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | ... 4 more ... | (number & $brand<...>); message: string; data?: unknown; }; }): void

`id`

type string | number

`response`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }

returns void

`reject_request`

Reject a pending request with error_message.

type (id: string | number, error_message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }): void

`id`

type string | number

`error_message`

type

{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">); message: string; data?: unknown; }; }

returns void

`handle_message`

Handles an incoming JSON-RPC message. Resolves or rejects the associated request.
Ignores notifications and unknown/invalid messages.

type (message: any): void

`message`

type any

returns void

`cancel_request`

Cancel a pending request without rejecting its deferred — just
cleanup. The caller's promise stays unsettled; pair with an external
resolution if needed.

type (id: string | number): void

`id`

type string | number

returns void

`cancel_all_requests`

Cancel all pending requests.

type (reason?: string | undefined): void

`reason?`

optional reason to include in rejection

type string | undefined

optional

returns void

RequestTrackerItem
#

actions/request_tracker.svelte.ts view source

`id`

type JsonrpcRequestId

readonly

`deferred`

type Deferred<JsonrpcResponseOrError>

readonly

`created`

type Datetime

readonly

`status`

type AsyncStatus

`timeout`

type NodeJS.Timeout | undefined

`constructor`

type new (id: string | number, deferred: Deferred<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | ... 4 more ... | (number & $brand<...>); message: string; data?: unknown; }; }>, created: Datetime, status: AsyncStatus, timeout: Timeout | undefined): RequestTrackerItem

`id`

type string | number

`deferred`

type

Deferred<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }...

`created`

type Datetime

`status`

type AsyncStatus

`timeout`

type Timeout | undefined

require_auth
#

auth/require_keeper.ts view source

(c: Context<any, string, {}>, next: Next): Promise<void | Response>

Middleware that requires authentication.
Returns 401 if no request context is set.

`c`

type Context<any, string, {}>

`next`

type Next

returns

Promise<void | Response>

require_keeper
#

(c: Context<any, string, {}>, next: Next): Promise<void | Response>

Middleware that requires keeper credentials.
Returns 401 if unauthenticated, 403 if credential type is not
daemon_token or if the keeper role is missing.

`c`

type Context<any, string, {}>

`next`

type Next

returns

Promise<void | Response>

require_request_context
#

(c: Context<any, any, {}>): RequestContext

Get the request context, throwing if unauthenticated.
Use in route handlers where auth middleware guarantees a context exists
(i.e., routes with auth: {type: 'authenticated'} or stricter).
Prefer this over get_request_context(c)! for explicit error handling.

`c`

the Hono context

type Context<any, any, {}>

returns

RequestContext

the request context (never null)

throws

Error - if no request context is set (middleware misconfiguration)

require_role
#

(role: string): MiddlewareHandler

Create middleware that requires a specific role.
Returns 401 if unauthenticated, 403 if the role is missing.

`role`

the required role

type string

returns

MiddlewareHandler

require_rpc_endpoint_path
#

(rpc_endpoints: readonly RpcEndpointSpec[]): string

Resolve a single RPC endpoint path — the common case where a consumer
mounts exactly one create_rpc_endpoint.
Used at suite setup time to hard-fail integration suites (admin / audit /
SSE / rate-limiting) when the consumer omitted rpc_endpoints rather
than letting tests fail mid-run with confusing errors.
Callers that need multi-endpoint support should iterate rpc_endpoints
directly.

`rpc_endpoints`

type readonly RpcEndpointSpec[]

returns

string

throws

Error - if `rpc_endpoints` is empty (hard-fail; see the suite options

reset_audit_metadata_validation_failures
#

(): void

Reset the counter — for tests only.

returns

void

reset_audit_unknown_event_type_failures
#

(): void

Reset the counter — for tests only.

returns

void

reset_bootstrap_token
#

(deps: FsReadDeps & FsWriteDeps & FsRemoveDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions | undefined): Promise<...>

Remove an existing bootstrap token and create a new one.

`deps`

file, command, env, and remove capabilities

type FsReadDeps & FsWriteDeps & FsRemoveDeps & CommandDeps & EnvDeps

`app_name`

application name

type string

`options?`

state_dir override, permissions, logger

type SetupBootstrapTokenOptions | undefined

optional

returns

Promise<SetupTokenResult>

result from creating the new token

reset_database
#

(deps: CommandDeps & FsReadDeps & FsRemoveDeps, database_url: string, options?: ResetDatabaseOptions | undefined): Promise<...>

Reset a database to a clean slate.
For PostgreSQL: drops and recreates the database.
For pglite: removes the data directory if pglite_data_dir is provided.
For empty/missing URLs: skips.

`deps`

command and file capabilities

type CommandDeps & FsReadDeps & FsRemoveDeps

`database_url`

the DATABASE_URL value

type string

`options?`

pglite_data_dir, logger

type ResetDatabaseOptions | undefined

optional

returns

Promise<ResetDbResult>

result describing what happened

reset_mock_runtime
#

(runtime: MockRuntime): void

Reset a mock runtime to initial state.

`runtime`

type MockRuntime

returns

void

reset_pglite
#

(db: Db): Promise<void>

Reset a PGlite database to a clean state by dropping and recreating the public schema.
Removes all tables, sequences, indexes, types, and functions.
The database instance remains usable after reset.

`db`

type Db

returns

Promise<void>

ResetDatabaseOptions
#

ResetDatabaseOptions

Options for reset_database.

`pglite_data_dir`

Directory to remove for file-based pglite.

type string

`log`

type SetupLogger

ResetDbResult
#

ResetDbResult

Result of reset_database.

`reset`

Whether the database was actually reset.

type boolean

`skipped`

Whether the operation was skipped (e.g. pglite with no data dir).

type boolean

`db_type`

What type of database was detected.

type 'postgres' | 'pglite' | 'none'

resolve_client_ip
#

(forwarded_for: string, proxies: ParsedProxy[]): string | undefined

Resolve the real client IP from an X-Forwarded-For header value.
Walks right-to-left, skipping trusted proxy entries. The first
non-trusted entry is the client IP. If all entries are trusted,
returns the leftmost entry. All entries are normalized before
matching and in the returned value.

`forwarded_for`

the X-Forwarded-For header value

type string

`proxies`

parsed trusted proxy entries

type ParsedProxy[]

returns

string | undefined

the normalized client IP, or undefined if the header is empty

resolve_env_vars
#

(runtime: Pick<EnvDeps, "env_get">, value: string): string

Resolve environment variable references in a string.
Uses $$VAR$$ syntax (bookended double-dollar signs).
Only resolves variables that are actually set in the environment.
Unset variables are left as-is for clear error messages.

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`value`

string that may contain $$VAR$$ references

type string

returns

string

string with env vars resolved

resolve_env_vars_in_object
#

<T extends Record<string, unknown>>(runtime: Pick<EnvDeps, "env_get">, obj: T): T

Resolve env vars in an object's string values (shallow).

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`obj`

object with string values

type T

returns

T

new object with env vars resolved

resolve_env_vars_required
#

(runtime: Pick<EnvDeps, "env_get">, value: string, context: string): string

Resolve env vars and throw if any are missing/empty.
Use this for values that must be present.

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`value`

string with $$VAR$$ references

type string

`context`

description for error message (e.g., "target.host")

type string

returns

string

resolved string

throws

Error - if any referenced env var is missing or empty

resolve_fixture_path
#

(filename: string, import_meta_url: string): string

Resolve an absolute path relative to the caller's module.

`filename`

type string

`import_meta_url`

the caller's import.meta.url

type string

returns

string

resolve_keeper_account_id
#

(deps: QueryDeps): Promise<string | null>

Resolve the keeper account ID by querying for the account with an active keeper permit.
There is exactly one keeper account (the bootstrap account). Runs once at
server startup — the result is cached in DaemonTokenState.keeper_account_id.

`deps`

query dependencies

type QueryDeps

returns

Promise<string | null>

the keeper account ID, or null if no keeper exists yet (pre-bootstrap)

resolve_rpc_endpoints_for_setup
#

(rpc_endpoints: RpcEndpointsSuiteOption, session_options: SessionOptions<string>): RpcEndpointSpec[]

Resolve a suite's rpc_endpoints option to an array for setup-time
inspection (path lookup, action presence checks).
For the factory form this invokes the factory twice with stub
AppServerContexts and asserts that both invocations produce the same
(path, method-list) shape — catching factories that close over mutable
state or otherwise diverge across calls. The first array is returned;
the second is discarded after the comparison. create_app_server
invokes the factory again per-test with its real ctx, and those are
the handlers that actually serve requests.
Safe as long as the factory is pure with respect to the endpoint path
and the action spec.method list — the canonical helpers
(create_standard_rpc_actions, create_admin_actions, create_account_actions,
etc.) are. Factories that return a different path based on ctx will
produce a setup/runtime mismatch; the path-purity assert below surfaces
that as a clear gro check error rather than a silent test/runtime drift.

`rpc_endpoints`

`session_options`

type SessionOptions<string>

returns

RpcEndpointSpec[]

throws

Error - if the factory's two stub-ctx invocations produce different

resolve_scope_label
#

<G extends string | null>(scope_id: string | null, role: string, format_scope: FormatScope, global_label: G): string | G

Resolve a scope label across the context → raw-uuid fallback chain.
global_label is returned for scope_id === null. Callers pass null
to render no chip (admin tables — global is the implicit default) or
'global' for explicit labels (offer surfaces). The return type
propagates null only when global_label is null.

`scope_id`

type string | null

`role`

type string

`format_scope`

type FormatScope

`global_label`

type G

returns

string | G

resolve_standard_error_schema_tightness
#

(consumer: ErrorSchemaTightnessOptions | null | undefined): ErrorSchemaTightnessOptions | null

Merge a consumer's error_schema_tightness option with
DEFAULT_ERROR_SCHEMA_TIGHTNESS so allowlist and ignore_statuses are
additive rather than replacing.
- undefined → return the default as-is.
- null → return null (opt out of the assertion).
- object → spread the default, then consumer overrides for scalar fields
  (min_specificity), then concat stock-then-consumer for the list fields
  (allowlist, ignore_statuses) so consumer entries extend rather than
  replace.
Exported for direct use when a consumer calls assert_error_schema_tightness
outside the standard suite but still wants the additive merge.

`consumer`

type ErrorSchemaTightnessOptions | null | undefined

returns

ErrorSchemaTightnessOptions | null

resolve_test_path
#

(path: string): string

Replace Hono route params (:foo) with dummy values for HTTP testing.

`path`

type string

returns

string

resolve_valid_path
#

(path: string, params_schema?: ZodObject<$ZodLooseShape, $strip> | undefined): string

Resolve a route path with valid-ish param values so params validation passes.
Used when testing input on routes that also have params.

`path`

type string

`params_schema?`

type ZodObject<$ZodLooseShape, $strip> | undefined

optional

returns

string

REST_AUTH_ROUTE_SUFFIXES
#

readonly ["/login", "/logout", "/password", "/verify", "/signup", "/bootstrap"]

REST auth route suffixes still on the account/bootstrap surface after the
2026-04-22 RPC migration. find_auth_route rejects any other suffix at
runtime — session/token CRUD, admin operations, and permit flows live on
the RPC surface and should be reached via rpc_call.

RestAuthRouteSuffix
#

RevokeForScopeResult
#

RevokeForScopeResult

Result of query_permit_revoke_for_scope — every permit revoked plus every pending offer superseded by the scope-wide cascade.

`revoked`

One entry per permit revoked by this call. Carries the revokee's
account_id so callers can fan out a permit_revoke notification per
permit. Empty array means no active permit was bound to the scope.

type Array<{permit_id: Uuid; role: string; scope_id: Uuid; account_id: Uuid}>

`superseded_offers`

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).

type Array<SupersededOffer>

RevokePermitResult
#

RevokePermitResult

Result of query_revoke_permit — the revoked permit plus any pending offers superseded by the revoke.

`id`

type Uuid

`role`

type string

`scope_id`

type Uuid | null

`superseded_offers`

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>).

type Array<SupersededOffer>

RevokeRoleResult
#

RevokeRoleResult

Result of query_permit_revoke_role — every permit revoked plus the pending offers superseded by the bulk revoke.

`revoked`

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).

type Array<{permit_id: string; role: string; scope_id: string | null; account_id: string}>

`superseded_offers`

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.

type Array<SupersededOffer>

ROLE_ADMIN
#

"admin"

App-level administrative role. Web-grantable, manages users and content.

ROLE_KEEPER
#

"keeper"

System-level role. Requires daemon token (filesystem proof). Controls the keep.

RoleName
#

ZodString

Valid role name: lowercase letters and underscores, no leading/trailing underscore.

RoleOptions
#

RoleOptions

Configuration for a role.
Builtin roles have fixed configs. App-defined roles get sensible defaults
(requires_daemon_token: false, web_grantable: true).

`requires_daemon_token`

If true, exercising this role requires daemon token authentication. Only keeper for now.

type boolean

`web_grantable`

If true, admins can grant this role via the web UI. Default true.

type boolean

RoleSchemaResult
#

testing/round_trip.ts view source

RoleSchemaResult

The result of create_role_schema — a Zod schema and config map for all roles.

`Role`

Zod schema that validates role strings. Use at I/O boundaries (grant endpoint, permit queries).

type z.ZodType<string>

`role_options`

Options for every role (builtins + app-defined). Keyed by role name.

type ReadonlyMap<string, Required<RoleOptions>>

RoundTripTestOptions
#

RoundTripTestOptions

Options for describe_round_trip_validation.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same one used in production.

type (ctx: AppServerContext) => Array<RouteSpec>

`app_options`

Optional overrides for AppServerOptions.

type

Partial<
		Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>
	>

`db_factories`

Database factories to run tests against. Default: pglite only.

type Array<DbFactory>

`skip_routes`

Routes to skip, in 'METHOD /path' format.

type Array<string>

`input_overrides`

Override generated bodies for specific routes ('METHOD /path' → body).

type Map<string, Record<string, unknown>>

RouteAuth
#

RouteAuth

Auth requirement for a route — none, authenticated, a specific role, or keeper.
{type: 'none'} means the route is open to all clients — including non-browser
callers (CLI, API tokens, scripts). No session or auth middleware guards are applied.

RouteContext
#

RouteContext

Per-request deps provided by the framework to route handlers.

`db`

Transaction-scoped for mutations, pool-level for reads.

type Db

`background_db`

Always pool-level — for fire-and-forget effects that must outlive the transaction.

type Db

`pending_effects`

Fire-and-forget side effects — push here for post-response flushing.

type Array<Promise<void>>

RouteErrorSchemas
#

Partial<Record<number, ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>>

Error schema map — maps HTTP status codes to Zod schemas.
Used on RouteSpec.errors and internally by derive_error_schemas.

RouteFactoryDeps
#

auth/deps.ts view source

RouteFactoryDeps

Capabilities for route spec factories.
AppDeps without db — route handlers receive database connections
via RouteContext, so factories don't capture a pool-level Db.

RouteHandler
#

RouteHandler

Route handler function — receives the Hono context and a RouteContext
with per-request deps (db, background_db, pending_effects).
TypeScript allows fewer params, so handlers that don't need route
can use (c) => ... without changes.

RouteMethod
#

RouteMethod

HTTP methods supported by route specs.

routes_by_auth_type
#

(surface: AppSurface): Map<string, AppSurfaceRoute[]>

Group routes by auth type.

`surface`

type AppSurface

returns

Map<string, AppSurfaceRoute[]>

a map from auth type string to route arrays, with role routes keyed as 'role:name'

RouteSpec
#

RouteSpec

A single route definition — the unit of the surface map.
input and output schemas align with SAES ActionSpec naming.
Use z.null() for routes with no request body (GET, DELETE without body).

`method`

type RouteMethod

`path`

type string

`auth`

type RouteAuth

`handler`

type RouteHandler

`description`

type string

`params`

URL path parameter schema. Use z.strictObject() with string fields matching :param segments.
REST-only — actions dispatch through a single JSON-RPC endpoint and encode
everything in input, so params doesn't appear on ActionSpec.

type z.ZodObject

`query`

URL query parameter schema. Use z.strictObject() with string fields.

type z.ZodObject

`input`

Request body schema. Use z.null() for routes with no body.

type z.ZodType

`output`

Success response body schema.

type z.ZodType

`rate_limit`

Rate limit key type — declares what this route's rate limiter is keyed on.
When set, 429 (RateLimitError) is auto-derived in derive_error_schemas.
The actual RateLimiter instance is still wired imperatively in the handler —
this field is metadata for surface introspection and policy invariants.

type RateLimitKey

`errors`

Handler-specific error response schemas keyed by HTTP status code.
Middleware errors (auth 401/403, validation 400, rate limit 429) are
auto-derived from auth, input, and rate_limit. Declare handler-specific
errors here (e.g., 404 for not-found, 409 for conflicts).
Explicit entries override auto-derived ones for the same status code.

type RouteErrorSchemas

`transaction`

Whether to wrap the handler in a database transaction.
When omitted, defaults are derived from the HTTP method:
- GET → false (read-only, no transaction)
- All others (POST, PUT, DELETE, PATCH) → true
Set explicitly to override the default (e.g., false for a POST
that manages its own transaction like signup).

type boolean

rpc_action
#

<TSpec extends RequestResponseActionSpec>(spec: TSpec, handler: ActionHandler<output<TSpec["input"]>, output<TSpec["output"]>>): RpcAction

Pair a spec with a handler while preserving per-method input/output types.
Constructing {spec, handler} literals widens handler to
ActionHandler<any, any>, so spec/handler drift (renamed Zod schema,
output field removal, input shape change) slips past the typechecker.
rpc_action(spec, handler) binds the handler signature to
(input: z.infer<spec.input>, ctx) => z.infer<spec.output> via the
generic spec parameter — drift surfaces at the call site.
Fits fuz_app's factory-closure pattern (handlers close over
grantable_roles, app_settings ref, notification_sender, etc.).
zzz uses a different shape — a codegen-keyed Record<Method, Handler>
map typed via generated ActionInputs/ActionOutputs — which works when
handlers are pure (no closure state) and specs are codegen-enumerated.
fuz_app's admin + permit-offer actions have neither, so per-pair typing
at the registration site is the right fit.

`spec`

type TSpec

`handler`

type ActionHandler<output<TSpec["input"]>, output<TSpec["output"]>>

returns

RpcAction

rpc_call
#

(args: RpcCallArgs): Promise<RpcCallResult>

One-shot JSON-RPC call over a Hono app.
Merges sensible defaults (host, origin, Content-Type) under
caller-provided headers, fires POST (default) or GET, parses the envelope,
and returns a discriminated result.

`args`

type RpcCallArgs

returns

Promise<RpcCallResult>

throws

Error - if the response body is neither a valid `JsonrpcResponse`

rpc_call_for_spec
#

<TSpec extends RequestResponseActionSpec>(args: RpcCallForSpecArgs<TSpec>): Promise<RpcCallResultForSpec<TSpec>>

Typed wrapper over rpc_call — binds params to z.infer<spec.input>
and the success result to z.infer<spec.output> via the generic.
Success results are validated at runtime against spec.output (same
contract as rpc_call_typed); a mismatch throws. Error responses come
back on the discriminated {ok: false, error} branch — use this for
happy-path + denial-path assertions where the error data.reason shape
is still asserted manually. For adversarial input tests that send
malformed params, use the untyped rpc_call.

`args`

type RpcCallForSpecArgs<TSpec>

returns

Promise<RpcCallResultForSpec<TSpec>>

throws

Error - if the success `result` does not parse against `spec.output`,

rpc_call_non_browser
#

(args: Omit<RpcCallArgs, "suppress_default_origin">): Promise<RpcCallResult>

Same as rpc_call but without the default origin header. Use for
bearer-auth probes: bearer_auth discards the token when Origin or
Referer is present (browser context), so a bearer probe via rpc_call
would short-circuit to 401 before the token is ever validated.
Equivalent to rpc_call({...args, suppress_default_origin: true}).

`args`

type Omit<RpcCallArgs, "suppress_default_origin">

returns

Promise<RpcCallResult>

rpc_call_typed
#

<T>(args: RpcCallArgs, output_schema: ZodType<T, unknown, $ZodTypeInternals<T, unknown>>): Promise<T>

Same as rpc_call but parses the success result through the given
output schema and returns typed data. Envelope-level failures or error
responses throw — use the untyped rpc_call for tests that need to
assert on specific error shapes.

`args`

type RpcCallArgs

`output_schema`

type ZodType<T, unknown, $ZodTypeInternals<T, unknown>>

returns

Promise<T>

throws

Error - if the response is a JSON-RPC error, if `rpc_call` throws

RpcAction
#

testing/rpc_attack_surface.ts view source

RpcAction

An RPC action — combines an action spec with its handler.
The spec defines the contract (method, auth, schemas, side effects).
The handler implements the behavior.

`spec`

type RequestResponseActionSpec

`handler`

type ActionHandler

RpcAttackSurfaceOptions
#

RpcAttackSurfaceOptions

Options for describe_rpc_attack_surface_tests.

`build`

Build the app surface bundle (surface + route specs + middleware specs + rpc_endpoints).

type () => AppSurfaceSpec

`roles`

All roles in the app (e.g. ['admin', 'keeper']).

type Array<string>

RpcCallArgs
#

RpcCallArgs

Arguments for rpc_call.

`app`

Hono-like app (anything with a request(url, init) method).

type {request: (input: string, init: RequestInit) => Promise<Response> | Response}

`path`

RPC endpoint path, e.g. '/api/rpc'.

type string

`method`

JSON-RPC method name.

type string

`params`

Params for the call. Omit (or pass undefined) for parameterless
(z.void()) methods — the helper drops params from the envelope
either way. See create_rpc_post_init for the null-stripping
affordance and JSON-RPC 2.0 §4.2's prohibition on params: null.

type unknown

`headers`

Extra request headers (session cookie, bearer, etc.). Overrides defaults.

type Record<string, string>

`id`

Request id. Defaults to 'test'.

type string | number

`verb`

HTTP verb — 'POST' (default) or 'GET' for side_effects: false methods.

type 'POST' | 'GET'

`suppress_default_origin`

Suppress the default origin header. Required for bearer-auth paths:
bearer_auth discards the token when Origin or Referer is present
(browser context), so probing it via rpc_call needs this flag — or
use rpc_call_non_browser, which sets it for you.

type boolean

RpcCallForSpecArgs
#

RpcCallForSpecArgs<TSpec>

Arguments for rpc_call_for_spec. spec replaces the loose method field.

generics

`TSpec`

constraint RequestResponseActionSpec

RpcCallResult
#

RpcCallResult

Discriminated return from rpc_call. status is the HTTP status.

RpcCallResultForSpec
#

RpcCallResultForSpec<TSpec>

Typed discriminated result returned by rpc_call_for_spec. The success
branch's result is inferred from TSpec['output']. The error branch
stays untyped because JSON-RPC error.data shapes vary per error and
are asserted per call site.

generics

`TSpec`

constraint RequestResponseActionSpec

RpcClientCallOptions
#

RpcClientCallOptions

Per-call options accepted by every typed Proxy method. Same shape as
ActionPeerSendOptions — the client threads these through unchanged
to the underlying peer. transport_name overrides the per-method
transport_for_method selector for this call.

inheritance

extends:

ActionPeerSendOptions

RpcEndpointSpec
#

RpcEndpointSpec

An RPC endpoint definition for surface generation.

`path`

type string

`actions`

type Array<RpcAction>

RpcEndpointsSuiteOption
#

testing/rpc_round_trip.ts view source

RpcEndpointsSuiteOption

Union accepted by the suite-level rpc_endpoints option — eager array or
a factory that takes an AppServerContext and returns endpoint specs. The
factory form is required when action handlers must close over the
per-test ctx.app_settings / ctx.deps (e.g. the canonical
create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings})
pattern). create_app_server resolves either shape natively; test helpers
forward the raw value to app_options.rpc_endpoints for live dispatch.

RpcRoundTripTestOptions
#

RpcRoundTripTestOptions

Options for describe_rpc_round_trip_tests.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same one used in production.

type (ctx: AppServerContext) => Array<RouteSpec>

`rpc_endpoints`

RPC endpoint specs — the source RpcAction arrays for params generation.
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> — the factory form
is required when action handlers must close over the per-test
ctx.app_settings / ctx.deps. The factory must return the same
endpoint path and spec.method list regardless of ctx — it is
invoked once at setup (via a stub ctx) to enumerate methods and
again per-test by create_app_server for live dispatch.

`app_options`

Optional overrides for AppServerOptions.

type SuiteAppOptions

`db_factories`

Database factories to run tests against. Default: pglite only.

type Array<DbFactory>

`skip_methods`

Methods to skip, by name (e.g., 'tx_plan').

type Array<string>

`input_overrides`

Override generated params for specific methods (method name → params).

type Map<string, Record<string, unknown>>

RpcTestTransport
#

RpcTestTransport

Minimal transport surface — the duck type Hono.request already satisfies.
Extracted so test setups that want an in-process / WS / mock path can plug
a different dispatcher without changing call sites.

run_auth_cleanup
#

(deps: AuthCleanupDeps): Promise<AuthCleanupResult>

Run every auth cleanup sweep — expired sessions and expired permit
offers — and return the counts.
Consumers call this from a scheduled task (setInterval, cron, etc.)
alongside their own domain cleanup. Errors from individual sweeps are
re-thrown so the caller's scheduler can log/alert; use the per-task
helpers (query_session_cleanup_expired, cleanup_expired_permit_offers)
directly if you need finer error isolation.

`deps`

type AuthCleanupDeps

returns

Promise<AuthCleanupResult>

throws

Error - re-thrown from any sweep that fails (no per-sweep isolation here)

run_local
#

cli/util.ts view source

(runtime: CommandDeps, command: string, args: string[]): Promise<CommandResult>

Run a local command and return the result.

`runtime`

runtime with run_command capability

type CommandDeps

`command`

command to run

type string

`args`

command arguments

type string[]

returns

Promise<CommandResult>

command result

run_migrations
#

(db: Db, namespaces: MigrationNamespace[]): Promise<MigrationResult[]>

Run pending migrations for each namespace.
For each namespace: acquires an advisory lock, reads applied rows ordered
by sequence, length-checks (binary-older-than-db short-circuits), name-
prefix-verifies, then runs the pending tail in a single chain transaction.
Each migration's row is INSERTed with sequence = max(sequence) + 1 for
the namespace.
Length check before name verify is load-bearing: a binary-older case
with a rename in the overlap would otherwise fire name-divergence-at-N
first and the operator would chase a phantom source-revert before
discovering the binary is the real problem.
Atomicity: any failure rolls back every migration that ran in that
invocation. Namespaces are independent: a later namespace's failure does
not roll back an earlier namespace that already committed.
Concurrency: per-namespace advisory locks reduce contention in
multi-instance deployments but are best-effort on pool drivers (see
the module docstring's "Advisory locking" notes). Correctness on concurrent boots
falls out of chain-tx atomicity + the (namespace, name) PK — the
loser's INSERT triggers PK violation and rollback; subsequent boots
see the committed state.

`db`

the database instance

type Db

`namespaces`

migration namespaces, processed in the order passed

type MigrationNamespace[]

returns

Promise<MigrationResult[]>

one result per namespace where work happened (already-up-to-date
namespaces are omitted)

throws

MigrationError - with `kind` of `binary-older-than-db`,

RunCommandOptions
#

RunCommandOptions

Options for run_command.

`cwd`

Working directory for the child process.

type string

`signal`

AbortSignal to terminate the child process.

type AbortSignal

`timeout_ms`

Kill the process and return timed_out: true after this many milliseconds.

type number

RuntimeDeps
#

RuntimeDeps

Full runtime capabilities returned by create_deno_runtime or create_node_runtime.
Extends all *Deps interfaces with additional app-level capabilities.
Functions should accept narrow *Deps interfaces, not this full type —
this type is for the wiring layer that creates and passes the runtime.

inheritance

extends:

`env_all`

Get all environment variables.

type () => Record<string, string>

`args`

CLI arguments passed to the program.

type ReadonlyArray<string>

readonly

`cwd`

Get current working directory.

type () => string

`run_command_inherit`

Run a command with inherited stdout/stderr (output goes directly to terminal).

type (cmd: string, args: Array<string>) => Promise<number>

save_config
#

<T>(runtime: Pick<FsWriteDeps, "mkdir" | "write_text_file">, path: string, dir: string, config: T): Promise<void>

Save CLI configuration to a JSON file.

`runtime`

runtime with file write capability

type Pick<FsWriteDeps, "mkdir" | "write_text_file">

`path`

path to the config JSON file

type string

`dir`

directory containing the config file (created if missing)

type string

`config`

configuration to save

type T

returns

Promise<void>

scan_env_vars
#

(obj: unknown): EnvVarRef[]

Recursively scan an object for $$VAR$$ env var references.
Walks all string values in the object tree and extracts env var names
with their path context for error reporting.

`obj`

object to scan (typically a config)

type unknown

returns

EnvVarRef[]

array of env var references with paths

schema_to_surface
#

schema_meta.ts view source

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): unknown

Convert a Zod schema to a JSON-serializable representation for the surface.
Returns null for null schemas, JSON Schema for object schemas.

`schema`

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

unknown

SchemaFieldMeta
#

SchemaFieldMeta

Zod .meta() shape for fuz_app schema metadata conventions.

`description`

type string

`sensitivity`

Sensitivity level for masking/redaction. 'secret' masks the value.

type Sensitivity

seed_dev_account
#

(deps: SeedDevAccountDeps, input: SeedDevAccountInput, options?: { log?: SetupLogger | undefined; } | undefined): Promise<...>

Seed a development test account, bypassing username/password policy.
Idempotent by username — if an account with the given username already
exists, reuses it and only reconciles the requested role grants. Never
updates an existing password (rerun would silently rotate it).
Intended for scripts/dev_setup.ts — do not call in production.

`deps`

type SeedDevAccountDeps

`input`

type SeedDevAccountInput

`options?`

type { log?: SetupLogger | undefined; } | undefined

optional

returns

Promise<SeedDevAccountResult>

throws

Error - if an existing account is found without an associated actor row

SeedDevAccountDeps
#

SeedDevAccountDeps

Dependencies for seed_dev_account.

inheritance

extends:

QueryDeps

`hash_password`

Password hasher (e.g., argon2_password_deps.hash_password).

type (password: string) => Promise<string>

SeedDevAccountInput
#

SeedDevAccountInput

Input to seed_dev_account.

`username`

Account username. Policy is bypassed — any non-empty string is accepted.

type string

`password`

Account password. Policy is bypassed — any non-empty string is accepted.

type string

`roles`

Roles to grant via permit (idempotent).

type ReadonlyArray<string>

SeedDevAccountResult
#

SeedDevAccountResult

Result of seed_dev_account.

`account_id`

type string

`actor_id`

type string

`created`

True if a new account was created; false if one already existed.

type boolean

select_auth_app
#

(apps: AuthTestApps, auth: RouteAuth): Hono<BlankEnv, BlankSchema, "/">

Select the Hono test app with correct auth for a route.

`apps`

type AuthTestApps

`auth`

type RouteAuth

returns

Hono<BlankEnv, BlankSchema, "/">

throws

Error - if `auth.type === 'role'` and `auth.role` is not present in

self_service_role_set_action_spec
#

auth/self_service_role_actions.ts view source

{ method: string; kind: "request_response"; initiator: "frontend"; auth: "authenticated"; side_effects: true; input: ZodObject<{ role: ZodString; enabled: ZodBoolean; }, $strict>; output: ZodObject<...>; async: true; description: string; }

SelfServiceRoleActionDeps
#

SelfServiceRoleActionDeps

Dependencies for create_self_service_role_actions. Same shape as the
peer factories so consumers thread one deps object through all three.
audit_log_config flows from AppDeps and is consumed by
audit_log_fire_and_forget.

SelfServiceRoleActionsOptions
#

auth/self_service_role_actions.ts view source

SelfServiceRoleActionsOptions

Options for create_self_service_role_actions.

`eligible_roles`

Allowlist of role strings eligible for self-service. Empty array
effectively disables the surface — every call comes back as
forbidden with reason role_not_self_service_eligible.

type ReadonlyArray<string>

`roles`

Optional role schema. When supplied, eligible_roles entries are
checked against roles.role_options at factory time so typos throw
at startup instead of at first call.

type RoleSchemaResult

SelfServiceRoleSetInput
#

ZodObject<{ role: ZodString; enabled: ZodBoolean; }, $strict>

Input for self_service_role_set.

SelfServiceRoleSetOutput
#

ZodObject<{ ok: ZodLiteral<true>; enabled: ZodBoolean; changed: ZodBoolean; }, $strict>

Output for self_service_role_set. enabled echoes the post-call state
(always equals the input enabled on success). changed is true only
when the call mutated — re-grants / re-revokes return false.

SENSITIVE_FIELD_BLOCKLIST
#

sensitivity.ts view source

readonly string[]

Field names that must never appear in any HTTP response body.

Sensitivity
#

"secret"

Sensitivity level for a schema field.
- 'secret' — value is masked in logs and UI (e.g. passwords, API keys, signing keys)

ServerEnvOptions
#

ServerEnvOptions

Validated server env config — the artifacts create_app_server() needs.

`ok`

type true

`keyring`

type Keyring

`allowed_origins`

type Array<RegExp>

`bootstrap_token_path`

type string | null

ServerEnvOptionsError
#

ServerEnvOptionsError

Error from validate_server_env — keyring or origin validation failed.

`ok`

type false

`field`

type 'SECRET_COOKIE_KEYS' | 'ALLOWED_ORIGINS'

`errors`

type Array<string>

ServerEnvOptionsResult
#

ServerEnvOptionsResult

ServerHeartbeatOptions
#

ServerHeartbeatOptions

`timeout`

Receive-silence (ms) past which the server closes the socket with
WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT. Any incoming message resets
the counter — chatty clients never trip it. First timeout
window after socket open is exempt (cold-start grace).

type number

ServerStatusOptions
#

server/static.ts view source

ServerStatusOptions

Options for the authenticated server status route.

`version`

Application version string.

type string

`get_uptime_ms`

Returns milliseconds since server start.

type () => number

ServeStaticFactory
#

ServeStaticFactory

Factory function that creates a static file serving middleware.
Matches the signature of serveStatic from hono/deno and @hono/node-server/serve-static.

ServeStaticOptions
#

server/static.ts view source

ServeStaticOptions

Options for serve_static factory functions (matches Hono's serveStatic signature).

`root`

type string

`rewriteRequestPath`

type (path: string) => string

`mimes`

type Record<string, string>

SESSION_AGE_MAX
#

number

Cookie max age in seconds (30 days — aligned with AUTH_SESSION_LIFETIME_MS).

SESSION_COOKIE_OPTIONS
#

SessionCookieOptions

Default cookie options for session cookies.
Uses strict security settings:
- secure: true - Works on localhost in Chrome/Firefox (treated as secure context)
- sameSite: 'strict' - Prevents CSRF
- httpOnly: true - Prevents XSS access to cookie

session_touch_fire_and_forget
#

(deps: QueryDeps, token_hash: string, pending_effects: Promise<void>[] | undefined, log: Logger): Promise<void>

Touch a session without blocking the caller.
Errors are logged to console — session touching never breaks request flows.
Pass pending_effects (from c.var.pending_effects) to register
the promise for test flushing.

`deps`

query dependencies

type QueryDeps

`token_hash`

blake3 hash of the session token

type string

`pending_effects`

optional array to register the effect for later awaiting

type Promise<void>[] | undefined

`log`

the logger instance

type Logger

returns

Promise<void>

the settled promise (callers may ignore it — fire-and-forget semantics preserved)

SessionAccount
#

SessionAccount

Account without sensitive fields, scoped to the authenticated user's own session.

`id`

type Uuid

`username`

type Username

`email`

type Email | null

`email_verified`

type boolean

`created_at`

type string

SessionAccountJson
#

ZodObject<{ id: $ZodBranded<ZodUUID, "Uuid", "out">; username: ZodString; email: ZodNullable<ZodEmail>; email_verified: ZodBoolean; created_at: ZodString; }, $strict>

Zod schema for SessionAccount — account without sensitive fields.

SessionCookieOptions
#

SessionCookieOptions

Cookie options for session cookies.

`path`

type string

`httpOnly`

type boolean

`secure`

type boolean

`sameSite`

type 'strict' | 'lax' | 'none'

`maxAge`

type number

SessionListInput
#

ZodVoid

Input for account_session_list. No parameters.

SessionListOutput
#

ZodObject<{ sessions: ZodArray<ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; created_at: ZodString; expires_at: ZodString; last_seen_at: ZodString; }, $strict>>; }, $strict>

Output for account_session_list.

SessionOptions
#

SessionOptions<TIdentity>

Configuration for a session cookie format.
Apps provide encode/decode to control the identity portion
of the cookie payload.
The TIdentity type parameter determines the trust model:
- string (e.g. a session_id) — the cookie references a server-side session record,
  enabling per-session revocation and metadata. Use when you need admin controls
  like "revoke all sessions" or per-session audit trails.
- number (e.g. an account_id) — the cookie directly encodes the user identity,
  requiring no server-side session state. Simpler, but individual sessions
  can only be invalidated by rotating the signing key (which invalidates all sessions).

generics

`TIdentity`

examples

// tx: 3-part format (admin:session_id)
const tx_config: SessionOptions<string> = {
  cookie_name: 'tx_session',
  context_key: 'auth_session_id',
  encode_identity: (session_id) => `admin:${session_id}`,
  decode_identity: (payload) => {
    const parts = payload.split(':');
    if (parts.length !== 2 || parts[0] !== 'admin') return null;
    return parts[1] || null;
  },
};

// visiones: 1-part format (account_id)
const visiones_config: SessionOptions<number> = {
  cookie_name: 'session_id',
  context_key: 'auth_session_id',
  encode_identity: (id) => String(id),
  decode_identity: (payload) => {
    const n = parseInt(payload, 10);
    return Number.isFinite(n) && n > 0 ? n : null;
  },
};

`cookie_name`

type string

`context_key`

Hono context variable name for the identity.

type string

`max_age`

type number

`cookie_options`

type Partial<SessionCookieOptions>

`encode_identity`

Encode identity into the cookie payload (before the :expires_at suffix).

type (identity: TIdentity) => string

`decode_identity`

Decode identity from cookie payload. Return null if invalid.

type (payload: string) => TIdentity | null

SessionRevokeAllInput
#

ZodVoid

Input for account_session_revoke_all. No parameters.

SessionRevokeAllOutput
#

ZodObject<{ ok: ZodLiteral<true>; count: ZodNumber; }, $strict>

Output for account_session_revoke_all.

SessionRevokeInput
#

ZodObject<{ session_id: ZodString; }, $strict>

Input for account_session_revoke. session_id is the blake3 hash.

SessionRevokeOutput
#

ZodObject<{ ok: ZodLiteral<true>; revoked: ZodBoolean; }, $strict>

Output for account_session_revoke. revoked is false for IDOR misses.

set_mock_stdin
#

(runtime: MockRuntime, input: string): void

Set stdin buffer for simulating user input.

`runtime`

type MockRuntime

`input`

string to provide as stdin input

type string

returns

void

set_session_cookie
#

<T>(c: Context<any, any, {}>, value: string, options: SessionOptions<T>): void

Set the session cookie on a response.

`c`

type Context<any, any, {}>

`value`

type string

`options`

type SessionOptions<T>

returns

void

setup_bootstrap_token
#

(deps: FsReadDeps & FsWriteDeps & CommandDeps & EnvDeps, app_name: string, options?: SetupBootstrapTokenOptions | undefined): Promise<...>

Create a bootstrap token file if it doesn't exist.
The token is a one-shot secret used to create the first admin account.
Stored at ~/.{app_name}/secret_bootstrap_token by default.

`deps`

file, command, and env capabilities

type FsReadDeps & FsWriteDeps & CommandDeps & EnvDeps

`app_name`

application name (used for default state directory)

type string

`options?`

state_dir override, permissions, logger

type SetupBootstrapTokenOptions | undefined

optional

returns

Promise<SetupTokenResult>

result indicating whether a token was created

setup_env_file
#

(deps: FsReadDeps & FsWriteDeps & CommandDeps, env_path: string, example_path: string, options?: SetupEnvOptions | undefined): Promise<...>

Create an env file from its example template, auto-generating SECRET_COOKIE_KEYS.
If the file already exists, backfills any empty values that have generators.
Idempotent — safe to re-run.

`deps`

file read, write, and command capabilities

type FsReadDeps & FsWriteDeps & CommandDeps

`env_path`

path for the env file (e.g. .env.development)

type string

`example_path`

path to the example template

type string

`options?`

extra replacements, permissions, logger

type SetupEnvOptions | undefined

optional

returns

Promise<SetupEnvResult>

result indicating whether the file was created or updated

SetupBootstrapTokenOptions
#

SetupBootstrapTokenOptions

Options for setup_bootstrap_token.

`state_dir`

State directory override. Defaults to ~/.{app_name}.

type string

`set_permissions`

Optional callback to set file/directory permissions.

type (path: string, mode: number) => Promise<void>

`log`

type SetupLogger

SetupEnvOptions
#

SetupEnvOptions

Options for setup_env_file.

`replacements`

Extra env var replacements beyond the default SECRET_COOKIE_KEYS.
Keys are env var names, values are async generators.
Replaces ^KEY=$ (empty value) patterns in the env file.

type Record<string, () => Promise<string>>

`set_permissions`

Optional callback to set file permissions (e.g. Deno.chmod).

type (path: string, mode: number) => Promise<void>

`log`

type SetupLogger

SetupEnvResult
#

SetupEnvResult

Result of setup_env_file.

`created`

Whether a new file was created (vs updating existing).

type boolean

`updated`

Whether any values were generated/replaced.

type boolean

`path`

The env file path.

type string

SetupLogger
#

SetupLogger

Optional logger for setup helpers.
Functions that accept a logger use it for status messages.
When omitted, a default bracket-format logger writes to console.

`ok`

type (msg: string) => void

`skip`

type (msg: string) => void

`error`

type (msg: string) => void

SetupTokenResult
#

http/origin.ts view source

SetupTokenResult

Result of setup_bootstrap_token.

`created`

Whether a new token was created (false if already existed).

type boolean

`token_path`

The token file path.

type string

should_allow_origin
#

(origin: string, allowed_patterns: RegExp[]): boolean

Tests if a request source (origin or referer) matches any of the allowed patterns.
Pattern matching is case-insensitive for domains (as per web standards).

`origin`

type string

`allowed_patterns`

type RegExp[]

returns

boolean

should_validate_output
#

(kind: "request_response" | "remote_notification" | "local_call", phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"): boolean

`kind`

type "request_response" | "remote_notification" | "local_call"

`phase`

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"

returns

boolean

ShouldDeliverFn
#

ui/sidebar_state.svelte.ts view source

ShouldDeliverFn

Per-connection delivery predicate for subscription ACLs.
Called once per connection for every broadcast send. Returning false
skips that connection. Keep it fast — this runs in the broadcast hot path.
input is the already-validated payload (matches the spec's input schema);
method is the action method name.

sidebar_state_context
#

{ get: (error_message?: string | undefined) => () => SidebarState; get_maybe: () => (() => SidebarState) | undefined; set: (value: () => SidebarState) => () => SidebarState; }

Svelte context carrying a reactive SidebarState accessor. Set by
AppShell.svelte (creates a fresh SidebarState if not supplied);
consumers call sidebar_state_context.get() to read or toggle visibility.

SidebarState
#

ui/sidebar_state.svelte.ts view source

`constructor`

type new (options?: SidebarStateOptions | undefined): SidebarState

`options?`

type SidebarStateOptions | undefined

optional

`toggle_sidebar`

type (value?: boolean): void

`value`

type boolean

default !this.show_sidebar

returns void

`activate`

Show the sidebar and enable the toggle. The returned disposer hides
and disables on cleanup — pair with $effect for scoped activation.

type (): () => void

returns () => void

SidebarStateOptions
#

ui/sidebar_state.svelte.ts view source

SidebarStateOptions

`enabled`

Reactive getter that controls whether the sidebar is enabled. When
supplied, overrides the internal enabled state — show_sidebar
auto-returns false while the getter returns false.

type () => boolean

SignupForm
#

ui/SignupForm.svelte view source

`redirect_on_signup?`

Path to navigate to after a successful signup.

type string

optional

SignupInput
#

ZodObject<{ username: ZodString; password: ZodString; email: ZodOptional<ZodEmail>; }, $strict>

Input for POST /signup. email is optional and must match any referenced invite.

SignupOutput
#

ZodObject<{ ok: ZodLiteral<true>; }, $strict>

Output for POST /signup. Session cookie is the operative side effect.

SignupRouteOptions
#

SignupRouteOptions

Per-factory configuration for signup route specs.

inheritance

extends:

AuthSessionRouteOptions

`signup_account_rate_limiter`

Rate limiter for signup attempts, keyed by submitted username. Pass null to disable.

type RateLimiter | null

`app_settings`

Mutable ref to app settings — when open_signup is true, invite check is skipped.

type AppSettings

socket_status_to_async_status
#

(status: SocketStatus, revoked: boolean): AsyncStatus

Project SocketStatus onto fuz_util's AsyncStatus — the
5-way → 4-way mapping every consumer re-derives to surface connection state
to UI (loading indicators, retry banners). Collapses reconnecting into
failure (UI shows "lost, retrying") and splits closed by revoked so
a terminal session-revocation read as failure while a clean client-
initiated close reads as initial (the "not connected, not trying" state).

`status`

type SocketStatus

`revoked`

whether the session has been permanently revoked
(typically FrontendWebsocketClient.revoked)

type boolean

returns

AsyncStatus

SocketCloseContext
#

SocketCloseContext

Context passed to the on_socket_close hook.
Fires before transport.remove_connection runs, so consumer cleanup can
still read identity before it's torn down. Fires for both client-initiated
closes (Hono onClose) and server-initiated closes via audit revocation
(the audit guard calls ws.close(), which triggers Hono's onClose).

`ws`

The raw WebSocket context at close time.

type WSContext

`connection_id`

Connection id captured at open time.

type Uuid

`identity`

Auth identity captured at open time — still valid even if the transport already cleaned up.

type ConnectionIdentity

SocketErrorHandler
#

SocketErrorHandler

SocketMessageHandler
#

SocketMessageHandler

SocketOpenContext
#

SocketOpenContext

Context passed to the on_socket_open hook.
Fires after the transport has registered the new connection (so
connection_id is valid) but before any client message can dispatch.
Consumers use this to bootstrap per-socket domain state — e.g. undying
spawns the per-account spirit unit and pushes an initial state snapshot.

`ws`

The raw WebSocket context — exposed for edge cases; prefer notify for sends.

type WSContext

`connection_id`

Connection id assigned by BackendWebsocketTransport.add_connection.

type Uuid

`identity`

Auth identity registered for this connection.

type ConnectionIdentity

`notify`

Send a JSON-RPC notification to just this socket. Mirrors ctx.notify
on per-message handler contexts — same socket-scoped semantics.

type (method: string, params: unknown) => void

`signal`

Fires when this socket closes — threaded through to every handler's ctx.signal.

type AbortSignal

SocketStatus
#

SocketStatus

Client-side WebSocket status.
- initial — never connected; connect() has not been called.
- connecting — WebSocket readyState === CONNECTING.
- connected — WebSocket readyState === OPEN.
- reconnecting — close fired; waiting out backoff before next attempt.
- closed — socket is not open. Terminal only when revoked is true
  or auto-reconnect is disabled; otherwise connect() reopens.

SpecSource
#

SpecSource

One source in a multi-source consumer's namespace map. ns is the local
alias used inside the generated file; module is the import path; specs
is the runtime spec array. create_namespace_qualifier consumes a list of
these.

`ns`

type string

`module`

type string

`specs`

type ReadonlyArray<ActionSpecUnion>

SSE_CONNECTED_COMMENT
#

": connected\n\n"

SSE comment sent on connect to flush headers through proxies. Exported for test assertions.

SseNotification
#

testing/sse_round_trip.ts view source

SseNotification

Notification shape aligned with JSON-RPC 2.0.
Uses {method, params} to match the JSON-RPC notification format.

`method`

Notification method name (e.g. 'run_created', 'host_updated').

type string

`params`

Method-specific payload.

type unknown

SseRouteTestOptions
#

SseRouteTestOptions

Options for describe_sse_route_tests.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same shape as production.

type (ctx: AppServerContext) => Array<RouteSpec>

`app_options`

Optional overrides for AppServerOptions.

type SuiteAppOptions

`db_factories`

Database factories to run tests against. Default: pglite only.

type Array<DbFactory>

`on_audit_event`

Backend audit event callback — threaded to create_test_app_server.
Use to wire a close-on-revoke guard for consumer SSE registries
(e.g., via create_sse_auth_guard) so session_revoke_all actually
closes the tested streams.

type (event: AuditLogEvent) => void

`rpc_endpoints`

RPC endpoint specs — required so the close-on-revoke assertion can
dispatch account_session_revoke_all via RPC (the former REST route
POST /api/account/sessions/revoke-all was removed in the 2026-04-23
migration). Hard-fails via require_rpc_endpoint_path on setup.
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> — the factory form
is required when action handlers must close over the per-test
ctx.app_settings / ctx.deps. The factory must return the same
endpoint path regardless of ctx — it is invoked once at setup with
a stub ctx for path lookup and again per-test by create_app_server
for live dispatch.

testing/sse_round_trip.ts view source

`routes`

SSE routes to exercise.

type Array<SseRouteTestSpec>

SseRouteTestSpec
#

SseRouteTestSpec

Config for a single SSE route under test.

`path`

Full HTTP path of the SSE endpoint (e.g., '/api/tx/subscribe').

type string

`trigger`

Fire an event matching one of the declared event_specs that should
reach the open stream. Called after the : connected comment is observed.
The triggered frame must be a JSON-serializable {method, params} payload.

type (ctx: {test_app: TestApp; account: TestAccount}) => Promise<void>

`event_specs`

Event specs to validate the triggered payload against. When omitted,
the payload is only asserted to be well-formed {method, params}.

type Array<EventSpec>

`assert_closes_on_revoke`

Whether to assert the stream closes after session_revoke_all.
Default true. Set false for endpoints that don't wire a close-on-revoke
guard (leaves a TODO to fix, rather than silently passing).

type boolean

SseStream
#

testing/admin_integration.ts view source

SseStream<T>

Generic SSE stream controller interface.
Transport-agnostic — works with any serializable type.

generics

`T`

default unknown

`send`

Send data to the client as a JSON SSE event.

type (data: T) => void

`comment`

Send a comment (for keep-alive pings).

type (text: string) => void

`close`

Close the stream.

type () => void

`on_close`

Register a listener called when the stream closes (client disconnect or explicit close).

type (fn: () => void) => void

StandardAdminIntegrationTestOptions
#

StandardAdminIntegrationTestOptions

Configuration for describe_standard_admin_integration_tests.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same one used in production.

type (ctx: AppServerContext) => Array<RouteSpec>

`roles`

Role schema result from create_role_schema() — used to determine valid/invalid/web-grantable roles.

type RoleSchemaResult

`rpc_endpoints`

RPC endpoint specs — the source RpcAction arrays. Required; permit
grant/revoke are RPC-only and the suite hard-fails without them.
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> — the factory form
is required when action handlers must close over the per-test
ctx.app_settings / ctx.deps (e.g. the canonical
create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings})
pattern). The factory must return the same endpoint path regardless
of ctx — it is invoked once at setup with a stub ctx for path lookup
and again per-test by create_app_server for live dispatch.

`admin_prefix`

Path prefix where admin routes are mounted (e.g., '/api/admin').
Used by the 401/403 error-coverage probe to scope to fuz_app admin
routes only, avoiding app-specific admin-gated routes that may use
stub deps. Default '/api/admin'.

type string

`app_options`

Optional overrides for AppServerOptions.

type SuiteAppOptions

`db_factories`

Database factories to run tests against. Default: pglite only.
Pass consumer factories (e.g. [pglite_factory, pg_factory]) to also test against PostgreSQL.

type Array<DbFactory>

StandardAttackSurfaceOptions
#

testing/integration.ts view source

StandardAttackSurfaceOptions

Options for the standard attack surface test suite.

`build`

Build the app surface bundle (surface + route specs + middleware specs).

type () => AppSurfaceSpec

`snapshot_path`

Absolute path to the committed snapshot JSON file.

type string

`expected_public_routes`

Expected public routes, e.g. ['GET /health', 'POST /api/account/login'].

type Array<string>

`expected_api_middleware`

Expected middleware names for API routes, e.g. ['origin', 'session', 'request_context', 'bearer_auth'].

type Array<string>

`roles`

All roles in the app (e.g. ['admin', 'keeper']).

type Array<string>

`api_path_prefix`

Path prefix for middleware stack assertion. Default '/api/'.

type string

`security_policy`

Security policy configuration. Omit for sensible defaults.

type SurfaceSecurityPolicyOptions

`error_schema_tightness`

Error schema tightness assertion config. Defaults to
DEFAULT_ERROR_SCHEMA_TIGHTNESS (ignores 401/403/429,
min_specificity: 'enum', allowlist seeded with
FUZ_APP_STOCK_ROUTE_TIGHTNESS_ALLOWLIST).
Consumer-supplied allowlist and ignore_statuses are additive —
the suite merges them underneath the stock defaults, so project-specific
entries don't need to re-list fuz_app's own stock routes. Pass a narrower
config to extend either list or tighten min_specificity; pass null
to skip the assertion and keep the audit log informational-only.

type ErrorSchemaTightnessOptions | null

StandardIntegrationTestOptions
#

StandardIntegrationTestOptions

Configuration for describe_standard_integration_tests.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same one used in production.

type (ctx: AppServerContext) => Array<RouteSpec>

`app_options`

Optional overrides for AppServerOptions.

type SuiteAppOptions

`db_factories`

Database factories to run tests against. Default: pglite only.
Pass consumer factories (e.g. [pglite_factory, pg_factory]) to also test against PostgreSQL.

type Array<DbFactory>

`rpc_endpoints`

RPC endpoint specs — required. This suite dispatches
account_verify, account_session_*, and account_token_* via
rpc_call_for_spec (the /api/account/verify REST route is a
status-only nginx shim with no payload). Hard-fails via
require_rpc_endpoint_path on setup so consumer projects see a
clear setup error instead of confusing test failures.
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec> — the factory form
is required when action handlers must close over the per-test
ctx.app_settings / ctx.deps (e.g. the canonical
create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings})
pattern). The factory must return the same endpoint path regardless
of ctx — it is invoked once at setup with a stub ctx for path lookup
and again per-test by create_app_server for live dispatch.

auth/standard_rpc_actions.ts view source

StandardRpcActionsDeps
#

PermitOfferActionDeps

Dependencies for create_standard_rpc_actions.
Same shape as PermitOfferActionDeps — log, on_audit_event, and an
optional notification_sender for permit-offer WS fan-out. Admin and
account factories only read log + on_audit_event; the extra field
is harmless.

StandardRpcActionsOptions
#

auth/standard_rpc_actions.ts view source

StandardRpcActionsOptions

Options for create_standard_rpc_actions.
Composes AdminActionOptions (roles, app_settings),
PermitOfferActionOptions (roles, default_ttl_ms, authorize), and
AccountActionOptions (max_tokens). roles is shared between admin
and permit-offer — the caller supplies it once and the helper threads
the same reference to both.

inheritance

extends:

StandardTestOptions
#

testing/standard.ts view source

StandardTestOptions

Configuration for describe_standard_tests.

`session_options`

Session config for cookie-based auth.

type SessionOptions<string>

`create_route_specs`

Route spec factory — same one used in production.

type (ctx: AppServerContext) => Array<RouteSpec>

`app_options`

Optional overrides for AppServerOptions.

type

Partial<
		Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>
	>

`db_factories`

Database factories to run tests against. Default: pglite only.

type Array<DbFactory>

`roles`

Role schema result from create_role_schema().
When provided, admin integration tests are included.

type RoleSchemaResult

`rpc_endpoints`

RPC endpoint specs — required. The standard integration tests drive
account_verify, account_session_*, account_token_* through the
RPC surface (and admin tests, when wired, drive permit grant/revoke
through it too).
Accepts either an array (eager) or a factory
(ctx: AppServerContext) => Array<RpcEndpointSpec>. Round-tripped
to both sub-suites unchanged — see their docstrings for the full
factory-form contract.

`admin_prefix`

Path prefix where admin routes are mounted.
Default '/api/admin'.

type string

start_daemon_token_rotation
#

(runtime: Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename"> & { chmod?: ((path: string, mode: number) => Promise<...>) | undefined; } & FsRemoveDeps, deps: QueryDeps, options: DaemonTokenRotationOptions, log: Logger): Promise<...>

Start daemon token rotation.
Generates an initial token, writes it to disk, resolves the keeper account,
and sets up periodic rotation. Returns the mutable state object and a stop function.

`runtime`

runtime with file, env, and remove capabilities

type

Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename"> & { chmod?: ((path: string, mode: number) => Promise<void>) | undefined; } & FsRemoveDeps

`deps`

query dependencies for resolving keeper account

type QueryDeps

`options`

rotation configuration

type DaemonTokenRotationOptions

`log`

the logger instance

type Logger

returns

Promise<DaemonTokenRotation>

rotation state and stop function

throws

Error - if `$HOME` is not set so the daemon token path cannot be resolved

StatResult
#

StatResult

Result of a stat operation.

`is_file`

type boolean

`is_directory`

type boolean

stop_daemon
#

(runtime: Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & FsRemoveDeps & CommandDeps & LogDeps, name: string): Promise<...>

Stop a running daemon by sending SIGTERM and cleaning up the PID file.
Returns a result object instead of logging directly, separating
lifecycle from presentation. Errors removing the PID file are swallowed
(the daemon's own shutdown handler may have removed it concurrently).

`runtime`

runtime with command, file, and env capabilities

type Pick<EnvDeps, "env_get"> & Pick<FsReadDeps, "stat" | "read_text_file"> & FsRemoveDeps & CommandDeps & LogDeps

`name`

application name

type string

returns

Promise<StopDaemonResult>

result describing the outcome

StopDaemonResult
#

StopDaemonResult

Result of a stop_daemon operation.

`stopped`

Whether a daemon was stopped.

type boolean

`pid`

PID of the stopped daemon, if any.

type number

`message`

Human-readable message describing the outcome.

type string

stub
#

any

Throwing stub — use for deps that should never be reached.

stub_app_deps
#

AppDeps

Stub AppDeps for auth surface tests — throws on any method access.

stub_handler
#

(): Response

Stub handler that returns a 200 response.

returns

Response

stub_mw
#

(_c: any, next: any): Promise<void>

Stub middleware that passes through.

`_c`

type any

`next`

type any

returns

Promise<void>

stub_password_deps
#

PasswordHashDeps

Fast password stub for tests that don't exercise login/password flows.
Hashes are deterministic (stub_hash_<password>) and verify correctly,
so auth bootstrap and session creation work without Argon2 overhead.

StubUpgrade
#

StubUpgrade

The return of create_stub_upgrade — fake upgradeWebSocket + factory capture.

`upgradeWebSocket`

type UpgradeWebSocket

`get_create_events`

type () => (c: Context) => WSEvents | Promise<WSEvents>

SubscribeOptions
#

SubscribeOptions

Options for SubscriberRegistry.subscribe.

`channels`

Channels to subscribe to. Empty/absent = all channels.

type ReadonlyArray<string>

`scope`

Primary (capped) identity — e.g., session hash. Subject to
max_per_scope and matched by close_by_identity.

type string

`groups`

Grouping identities — e.g., account id. Matched by close_by_identity
but NOT subject to the cap. Use for coarse-targeted close.

type ReadonlyArray<string>

Subscriber
#

Subscriber<T>

generics

`T`

`stream`

type SseStream<T>

`channels`

Channels this subscriber listens to. null means all channels.

type Set<string> | null

`scope`

Primary (capped) identity. null when none.

type string | null

`groups`

Grouping identities for close_by_identity. null when none.

type Set<string> | null

SubscriberRegistry
#

Generic subscriber registry with channel-based filtering and identity-keyed disconnection.
Subscribers connect with optional channel filters, a capped scope, and
uncapped groups. Broadcasts go to a specific channel and reach only
matching subscribers. close_by_identity force-closes all subscribers
whose scope or groups contain the given key — use for auth revocation.

generics

`T`

examples

const registry = new SubscriberRegistry<SseNotification>();

// subscriber connects (from SSE endpoint)
const unsubscribe = registry.subscribe(stream, {channels: ['runs']});

// when a run changes
registry.broadcast('runs', {method: 'run_created', params: {run}});

// subscriber disconnects
unsubscribe();

// scope = session hash (capped), groups = [account id] (close-only)
const unsubscribe = registry.subscribe(stream, {
  channels: ['audit_log'],
  scope: session_hash,
  groups: [account_id],
});

// coarse — close all of a user's streams on role revocation
registry.close_by_identity(account_id);

// fine — close just the stream(s) tied to a specific session
registry.close_by_identity(session_hash);

`constructor`

type new <T>(options?: SubscriberRegistryOptions | undefined): SubscriberRegistry<T>

`options?`

type SubscriberRegistryOptions | undefined

optional

`subscribe`

Add a subscriber.

type (stream: SseStream<T>, options?: SubscribeOptions | undefined): () => void

`stream`

SSE stream to send data to

type SseStream<T>

`options?`

channel filter and identity slots (scope + groups)

type SubscribeOptions | undefined

optional

returns () => void

unsubscribe function

`broadcast`

Broadcast data to all subscribers on a channel.
Subscribers with no channel filter receive all broadcasts.
Subscribers with a channel filter only receive matching broadcasts.

type (channel: string, data: T): void

`channel`

type string

`data`

type T

returns void

`close_by_identity`

Force-close all subscribers whose scope or groups match the given key.
Closes each matching stream and removes the subscriber from the registry.
Use for auth revocation — when a user's permissions change, close their
SSE connections so they must reconnect and re-authenticate.

type (identity: string): number

`identity`

the identity key to match (checked against scope and groups)

type string

returns number

the number of subscribers closed

SubscriberRegistryOptions
#

SubscriberRegistryOptions

Options for SubscriberRegistry.

`max_per_scope`

Max subscribers sharing a single scope. On subscribe, when the count
of subscribers with the same scope reaches this limit, the oldest
matching subscriber(s) are closed before the new one is added.
null (default) disables the cap. groups identities are never capped.

type number | null

SuiteAppOptions
#

Partial<Omit<AppServerOptions, "backend" | "session_options" | "create_route_specs" | "rpc_endpoints">>

app_options shape accepted by DB-backed suite helpers
(describe_standard_integration_tests, describe_audit_completeness_tests,
etc.). Excludes rpc_endpoints on top of the fields CreateTestAppOptions
excludes — suites require rpc_endpoints at the suite level (hard-failed
by require_rpc_endpoint_path) so setup-time path lookup and runtime
dispatch read from one source of truth. Low-level create_test_app
callers still pass rpc_endpoints via app_options.

SupersededOffer
#

SupersededOffer

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.

inheritance

extends:

PermitOffer

`from_account_id`

type Uuid

surface_auth_summary
#

ui/SurfaceExplorer.svelte view source

(surface: AppSurface): { none: number; authenticated: number; role: Map<string, number>; keeper: number; }

Summarize route auth distribution across the surface.

`surface`

type AppSurface

returns

{ none: number; authenticated: number; role: Map<string, number>; keeper: number; }

counts by auth type, with role counts broken out by role name

SurfaceExplorer
#

`surface`

type AppSurface

SurfaceRouteOptions
#

SurfaceRouteOptions

Options for the surface explorer route.

`surface`

The generated app surface to serve.

type AppSurface

SurfaceSecurityPolicyOptions
#

ui/table_state.svelte.ts view source

SurfaceSecurityPolicyOptions

Configuration for security policy invariants.
All fields have sensible defaults. Pass overrides for project-specific needs.

`sensitive_route_patterns`

Path patterns for routes that should be rate-limited.
Default: common sensitive REST patterns (login, password, bootstrap).
account_token_create became RPC-only in the 2026-04-23 migration;
per-method RPC rate limiting is a separate invariant if consumers want it.

type Array<string | RegExp>

`public_mutation_allowlist`

Routes explicitly allowed to be public mutations (e.g., webhooks, bootstrap).
Format: 'METHOD /path' (e.g., 'POST /api/account/login').

type Array<string>

`keeper_route_prefixes`

Allowed path prefixes for keeper-protected routes.
Default: ['/api/']. Catches keeper routes outside expected namespaces.

type Array<string>

TABLE_LIMIT_MAX
#

1000

Maximum number of rows that can be fetched in a single page.

TableInfo
#

ui/table_state.svelte.ts view source

TableInfo

Table metadata from information_schema.

`table_name`

type string

TableState
#

inheritance

extends:

Loadable

`table_name`

type string

`columns`

type Array<ColumnInfo>

`rows`

type Array<Record<string, unknown>>

`total`

`offset`

`limit`

`primary_key`

type string | null

`deleting`

type string | null

`delete_error`

type string | null

`showing_start`

readonly

`showing_end`

readonly

`has_prev`

readonly

`has_next`

readonly

`fetch`

Fetch a page of rows for table_name from GET /api/db/tables/{table_name}.
limit is clamped to [1, TABLE_LIMIT_MAX].

type (table_name: string, offset?: number, limit?: number): Promise<void>

`table_name`

type string

`offset`

type number

default 0

`limit`

type number

default 100

returns Promise<void>

`go_prev`

type (): void

returns void

`go_next`

type (): void

returns void

`delete_row`

Delete a row by its primary key via DELETE /api/db/tables/{table_name}/rows/{pk}.
Optimistically drops it from rows and decrements total on success;
surfaces server errors on delete_error.

type (row: Record<string, unknown>): Promise<boolean>

`row`

type Record<string, unknown>

returns Promise<boolean>

true when the row was removed; false on missing primary key or server error

TableStatus
#

TableStatus

Table info with row count.

`name`

type string

`row_count`

type number

TableWithCount
#

TableWithCount

Table info with row count.

`name`

type string

`row_count`

type number

TerminalDeps
#

TerminalDeps

Terminal I/O operations.

`stdout_write`

Write bytes to stdout.

type (data: Uint8Array) => Promise<number>

`stdin_read`

Read bytes from stdin, or null on EOF.

type (buffer: Uint8Array) => Promise<number | null>

TEST_CLIENT_IP
#

"127.0.0.1"

Default client IP set by the proxy stub in test apps.

TEST_COOKIE_SECRET
#

string

64-hex-char test cookie secret — deterministic, never used in production.

TEST_MIDDLEWARE_PATH
#

"/api/test"

Path used by the echo route in create_test_middleware_stack_app.

TestAccount
#

TestAccount

A bootstrapped test account with credentials.

`account`

type {id: Uuid; username: string}

`actor`

type {id: Uuid}

`session_cookie`

Signed session cookie value.

type string

`api_token`

Raw API token for Bearer auth.

type string

`create_session_headers`

Build request headers with this account's session cookie.

type (extra?: Record<string, string>) => Record<string, string>

`create_bearer_headers`

Build request headers with this account's Bearer token.

type (extra?: Record<string, string>) => Record<string, string>

TestAccountOverrides
#

TestAccountOverrides

Override type for create_test_account — id-like fields accept plain string.

TestActorOverrides
#

TestActorOverrides

Override type for create_test_actor — id-like fields accept plain string.

TestApp
#

TestApp

A fully assembled test app — Hono app + backend + helpers.

`app`

type Hono

`backend`

type TestAppServer

`surface_spec`

type AppSurfaceSpec

`surface`

type AppSurface

`route_specs`

type Array<RouteSpec>

`create_session_headers`

Build request headers with the bootstrapped session cookie.

type (extra?: Record<string, string>) => Record<string, string>

`create_bearer_headers`

Build request headers with the bootstrapped Bearer token.

type (extra?: Record<string, string>) => Record<string, string>

`create_daemon_token_headers`

Build request headers with the daemon token (keeper auth).

type (extra?: Record<string, string>) => Record<string, string>

`create_account`

Create an additional account with credentials.

type

(options?: {
		username?: string;
		password_value?: string;
		roles?: Array<string>;
	}) => Promise<TestAccount>

`cleanup`

Cleanup resources (delegates to TestAppServer.cleanup).

type () => Promise<void>

TestAppServer
#

TestAppServer

An AppBackend with a bootstrapped account, API token, and session cookie.

inheritance

extends:

AppBackend

`account`

The bootstrapped account.

type {id: Uuid; username: string}

`actor`

The actor linked to the account.

type {id: Uuid}

`api_token`

Raw API token for Bearer auth.

type string

`session_cookie`

Signed session cookie value for cookie auth.

type string

`keyring`

Keyring used for cookie signing — exposed for forging expired/tampered cookies in tests.

type Keyring

`cleanup`

Release test resources (no-op when DB is injected or factory-cached).

type () => Promise<void>

TestAppServerOptions
#

TestAppServerOptions

Configuration for create_test_app_server.

`session_options`

Session options — needed for cookie signing.

type SessionOptions<string>

`db`

Existing database — skips internal DB creation when provided. Caller owns the DB lifecycle.

type Db

`db_type`

Database driver type — only used when db is provided. Default: 'pglite-memory'.

type DbType

`password`

Password implementation. Default: stub_password_deps. Pass argon2_password_deps for tests that exercise login.

type PasswordHashDeps

`username`

Username for the bootstrapped account. Default: 'keeper'.

type string

`password_value`

Password for the bootstrapped account. Default: 'test-password-123'.

type string

`roles`

Roles to grant. Default: [ROLE_KEEPER].

type Array<string>

`on_audit_event`

Backend audit event callback — wired into backend.deps.on_audit_event.
When audit_log_sse: true is passed to create_app_server, this runs
after the audit SSE broadcast (composed downstream by app_server).
Use to wire consumer SSE auth guards in tests.
Default: no-op.

type (event: AuditLogEvent) => void

`audit_log_config`

Optional audit log config — written onto backend.deps.audit_log_config
before return so it lands in time for create_app_server's shallow
spread of backend.deps (SSE branch) and the no-SSE alias branch alike.
Use when the consumer registers extra event types via
create_audit_log_config({extra_events}) — without this, emits for
those events fall back to BUILTIN_AUDIT_LOG_CONFIG and log
"unknown event_type" warnings.

type AuditLogConfig

TestAuditEventOverrides
#

TestAuditEventOverrides

Override type for create_test_audit_event — id-like fields accept plain string.

TestMiddlewareStackApp
#

TestMiddlewareStackApp

Return type of create_test_middleware_stack_app.

`app`

type Hono

`mock_validate`

type ReturnType<typeof vi.fn>

`mock_find_by_id`

type ReturnType<typeof vi.fn>

`mock_find_by_account`

type ReturnType<typeof vi.fn>

`mock_find_active_for_actor`

type ReturnType<typeof vi.fn>

TestMiddlewareStackOptions
#

TestMiddlewareStackOptions

Options for create_test_middleware_stack_app.

`trusted_proxies`

Trusted proxy IPs.

type Array<string>

`allowed_origins`

Comma-separated allowed origin patterns.

type string

`connection_ip`

Connection IP or factory.

type string | (() => string | undefined)

`ip_rate_limiter`

Rate limiter for bearer auth.

type RateLimiter | null

TestPermitOverrides
#

TestPermitOverrides

Override type for create_test_permit — id-like fields accept plain string.

ThrowingApi
#

ThrowingApi<TApi>

Maps a typed ActionsApi to a throwing variant.
For each method whose return type matches the create_rpc_client shape
(Promise<Result<{value: T}, {error: JsonrpcErrorObject}>>), the wrapped
method returns Promise<T> directly. Other shapes (notifications typed
as => void, sync local_call methods) pass through unchanged — there
is nothing to unwrap.
Input + options parameters are preserved verbatim via ...args: infer TArgs
so the conditional matches both required-input (input: T) and
optional-input (input?: T / nullary) signatures uniformly. Required-input
shapes (e.g. admin_session_revoke_all(input: AdminSessionRevokeAllInput))
are not assignable to a (input?: TInput) => … pattern under
--strictFunctionTypes, so an earlier (input?, options?) => form
silently fell through to TApi[K] and left those methods Result-shaped —
create_admin_rpc_adapters(api) would then reject the typed throwing
Proxy because half its surface still returned Result<...>. The rest-args
form preserves both required and optional parameters and resolves the gap.

generics

`TApi`

ThrownJsonrpcError
#

Error class carrying a JSON-RPC error code — thrown by handlers,
caught by apply_route_specs and mapped to HTTP status + JSON-RPC error response.
Named for what it is: an error with a JSON-RPC error code that gets thrown.

inheritance

extends:

Error

`code`

type JsonrpcErrorCode

`data`

type unknown

`constructor`

type new (code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">), message: string, data?: unknown, options?: ErrorOptions | undefined): ThrownJsonrpcError

`code`

type -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<"JsonrpcServerErrorCode">)

`message`

type string

`data?`

type unknown

optional

`options?`

type ErrorOptions | undefined

optional

to_action_spec_identifier
#

(method: string): string

`method`

type string

returns

string

to_action_spec_input_identifier
#

(method: string): string

`method`

type string

returns

string

to_action_spec_output_identifier
#

(method: string): string

`method`

type string

returns

string

to_admin_account
#

(account: Account): { id: string & $brand<"Uuid">; username: string; email: string | null; email_verified: boolean; created_at: string; updated_at: string; updated_by: (string & $brand<...>) | null; }

Convert an Account to an AdminAccountJson for admin listings.

`account`

the full account record

type Account

returns

{ id: string & $brand<"Uuid">; username: string; email: string | null; email_verified: boolean; created_at: string; updated_at: string; updated_by: (string & $brand<"Uuid">) | null; }

the admin-safe account with audit fields

to_jsonrpc_message_id
#

(message_or_id: unknown): string | number | null

Extracts a JSON-RPC request id from a message or raw value.
Returns null if no valid id can be extracted.

`message_or_id`

type unknown

returns

string | number | null

to_jsonrpc_params
#

(input: unknown): Record<string, any> | undefined

Normalizes input to JSON-RPC params format.
Returns undefined for null/undefined, wraps primitives in {value}.

`input`

type unknown

returns

Record<string, any> | undefined

to_jsonrpc_result
#

(output: unknown): Record<string, any>

Normalizes output to JSON-RPC result format.
Returns empty object for null/undefined, wraps primitives in {value}.

`output`

type unknown

returns

Record<string, any>

to_max_length
#

<T>(items: T[], to_string: (item: T) => string): number

Get maximum length from array.

`items`

array of items

type T[]

`to_string`

function to convert item to string for length measurement

type (item: T) => string

returns

number

maximum string length

to_permit_offer_json
#

(offer: PermitOffer): { id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; ... 10 more ...; resulting_permit_id: (string & $brand<...>) | null; }

Convert a PermitOffer row to its JSON payload shape.

`offer`

type PermitOffer

returns

{ id: string & $brand<"Uuid">; from_actor_id: string & $brand<"Uuid">; to_account_id: string & $brand<"Uuid">; role: string; scope_id: (string & $brand<"Uuid">) | null; ... 8 more ...; resulting_permit_id: (string & $brand<...>) | null; }

to_session_account
#

(account: Account): SessionAccount

Convert an Account to a SessionAccount by stripping sensitive fields.

`account`

the full account record

type Account

returns

SessionAccount

the client-safe account

TokenCreateInput
#

ZodObject<{ name: ZodDefault<ZodString>; }, $strict>

Input for account_token_create.

TokenCreateOutput
#

ZodObject<{ ok: ZodLiteral<true>; token: ZodString; id: ZodString; name: ZodString; }, $strict>

Output for account_token_create. token is returned exactly once.

TokenListInput
#

ZodVoid

Input for account_token_list. No parameters.

TokenListOutput
#

ZodObject<{ tokens: ZodArray<ZodObject<{ id: ZodString; account_id: $ZodBranded<ZodUUID, "Uuid", "out">; name: ZodString; expires_at: ZodNullable<ZodString>; last_used_at: ZodNullable<...>; last_used_ip: ZodNullable<...>; created_at: ZodString; }, $strict>>; }, $strict>

Output for account_token_list. Hashes are excluded.

TokenRevokeInput
#

ZodObject<{ token_id: ZodString; }, $strict>

Input for account_token_revoke.

TokenRevokeOutput
#

ZodObject<{ ok: ZodLiteral<true>; revoked: ZodBoolean; }, $strict>

Output for account_token_revoke. revoked is false for IDOR misses.

TransitionFunction
#

TransitionFunction

Support both Svelte transitions and custom transitions.

Transport
#

Transport

`transport_name`

type TransportName

`is_ready`

type () => boolean

`dispose`

type () => void

TransportForMethod
#

TransportForMethod

Optional per-method transport selector. Return the transport to use for a
given method, or undefined to let the peer pick via its fallback rules.
Useful when methods are registered on different backend dispatchers — e.g.
a streaming action mounted on the WebSocket endpoint while the rest of the
RPC surface lives on HTTP.

TransportName
#

ZodString

Transports
#

`allow_fallback`

Whether to allow fallback to other transports if the current one is not available.

type boolean

`register_transport`

Registers a transport. The first transport registered also becomes the current.

type (transport: Transport): void

`transport`

type Transport

returns void

`set_current_transport`

Switch the current transport selection by name.

type (transport_name: string): void

`transport_name`

type string

returns void

throws

Error - if no transport with `transport_name` has been registered

`get_transport`

Resolve a transport. With allow_fallback, walks specified → current →
any-ready; without, returns the named transport (or current) only when
it's ready.

type (transport_name?: string | undefined): Transport | null

`transport_name?`

type string | undefined

optional

returns Transport | null

the resolved transport, or null when none is ready

`is_ready`

type (): boolean | null

returns boolean | null

`get_current_transport`

type (): Transport | null

returns Transport | null

`get_current_transport_name`

type (): string | null

returns string | null

`get_transport_by_name`

type (transport_name: string): Transport | null

`transport_name`

type string

returns Transport | null

TransportSendOptions
#

TransportSendOptions

Per-call options accepted by every transport's send. Optional and
extensible — adding a field is non-breaking. Source of truth for the
shared option shape; ActionPeerSendOptions and RpcClientCallOptions
extend it.

`signal`

Per-call cancellation. Bottoms out at
FrontendWebsocketClient.request({signal}) on the WS path (sends the
shared cancel notification on abort) and at fetch({signal}) on
HTTP. Backend transport has no per-call abort surface to honor.

type AbortSignal

`queue`

Per-call durable-queue opt-in. Names the client-authoritative vs
server-authoritative distinction — server-authoritative consumers
(e.g. zzz completion calls) fail fast with service_unavailable when
the transport is down; client-authoritative consumers (games,
real-time apps) buffer and replay on reconnect because the user
already committed to the action at click time. Honored only by
FrontendWebsocketTransport on the request_response path (default
false). HTTP and backend transports ignore it; WS notifications
also ignore it and always fail-fast when disconnected (fire-and-forget
connection.send has no queue semantic).

type boolean

truncate_middle
#

(str: string, max_length: number, separator?: string): string

Truncate a string by keeping the start and end, with a separator in the middle.

`str`

type string

`max_length`

total length including separator

type number

`separator`

type string

default '…'

returns

string

the truncated string, or the original if it fits

truncate_uuid
#

ui/ui_fetch.ts view source

(uuid: string): string

Truncate a UUID for display, keeping start and end visible.

`uuid`

type string

returns

string

a 12-character truncated UUID like a1b2c…7890

ui_fetch
#

(input: RequestInfo | URL, init?: RequestInit | undefined): Promise<Response>

Fetch with credentials included (sends cookies).

`input`

type RequestInfo | URL

`init?`

type RequestInit | undefined

optional

returns

Promise<Response>

UncoveredEntry
#

UncoveredEntry

Uncovered entry — either a status-level row (no code) or a specific-code row.

`method`

type string

`path`

type string

`status`

type number

`code`

Declared code value missing, when the status's error schema names specific codes.

type string

UNKNOWN_ERROR_MESSAGE
#

env/update_env_variable.ts view source

"unknown error"

Default message for unknown errors.

update_env_variable
#

(key: string, value: string, options: UpdateEnvVariableOptions): Promise<void>

Updates or adds an environment variable in the .env file.
Preserves existing formatting, comments, and other variables.
Behavior:
- Duplicate keys: updates the LAST occurrence (matches dotenv behavior)
- Inline comments: preserved after the value (e.g., KEY=value # comment)
- Quote style: preserved from original (quoted/unquoted)

`key`

the environment variable name (e.g., 'SOME_CONFIGURATION_KEY')

type string

`value`

the new value for the environment variable

type string

`options`

file path and optional read/write overrides

type UpdateEnvVariableOptions

returns

Promise<void>

throws

Error - if the file read fails for any reason other than `ENOENT`, or if the write fails

UpdateAppSettingsInput
#

env/update_env_variable.ts view source

ZodObject<{ open_signup: ZodBoolean; }, $strict>

Zod schema for updating app settings.

UpdateEnvVariableOptions
#

UpdateEnvVariableOptions

Options for updating environment variables in a .env file.

`env_file_path`

Path to the .env file.

type string

`read_file`

Function to read file contents (defaults to node:fs/promises readFile).

type (path: string, encoding: string) => Promise<string>

`write_file`

Function to write file contents (defaults to node:fs/promises writeFile).

type (path: string, content: string, encoding: string) => Promise<void>

Username
#

ZodString

Username for account creation — starts with letter, alphanumeric/dash/underscore middle, ends with alphanumeric. No @ or . allowed.

USERNAME_LENGTH_MAX
#

39

Maximum username length (matches GitHub's limit).

USERNAME_LENGTH_MIN
#

3

Minimum username length (must have start + middle + end characters).

USERNAME_PROVIDED_LENGTH_MAX
#

255

Maximum length for username input on login/lookup — more permissive than USERNAME_LENGTH_MAX for forward-compatibility if the creation limit is raised.

UsernameProvided
#

db/sql_identifier.ts view source

ZodString

Username submitted for login or lookup — minimal validation for forward-compatibility if format rules change.

VALID_SQL_IDENTIFIER
#

RegExp

Pattern matching valid SQL identifiers: starts with a letter or underscore,
followed by letters, digits, or underscores.

validate_daemon_token
#

(provided: string, state: DaemonTokenState): boolean

Validate a daemon token against the current state.
Accepts both the current and previous token (2-token race window).
Uses timing-safe comparison.

`provided`

the token from the X-Daemon-Token header

type string

`state`

the daemon token state

type DaemonTokenState

returns

boolean

true if the token is valid

validate_env_vars
#

(runtime: Pick<EnvDeps, "env_get">, refs: EnvVarRef[]): EnvValidationResult

Validate that all referenced env vars exist in the environment.
Returns all missing refs (including duplicates by name). Grouping
and deduplication is handled by format_missing_env_vars at display time.

`runtime`

runtime with env_get capability

type Pick<EnvDeps, "env_get">

`refs`

env var references from scan_env_vars

type EnvVarRef[]

returns

EnvValidationResult

validation result with any missing vars

validate_keyring
#

server/validate_nginx.ts view source

(env_value: string | undefined): string[]

Validate key ring configuration.
Returns an error when no keys are configured (undefined, empty string,
or all-separator input like '____'), and for each key shorter than
MIN_KEY_LENGTH characters.

`env_value`

the SECRET_COOKIE_KEYS environment variable

type string | undefined

returns

string[]

array of validation errors (empty if valid)

validate_nginx_config
#

(config: string): NginxValidationResult

Validate an nginx config template string for security properties.
Checks for required security headers, Authorization stripping in /api
blocks, and the nginx add_header inheritance gotcha. Designed for
fuz_app consumer deploy configs (tx.ts NGINX_CONFIG constants).
Limitations: string pattern matching, not a real nginx parser. Catches
common omissions in fuz_app deploy configs but won't catch all possible
misconfigurations.

`config`

type string

returns

NginxValidationResult

validate_phase_for_kind
#

(kind: "request_response" | "remote_notification" | "local_call", phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"): void

Validate that phase is one of the phases allowed for kind per
ACTION_EVENT_PHASE_BY_KIND.

`kind`

type "request_response" | "remote_notification" | "local_call"

`phase`

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"

returns

void

throws

Error - if `phase` is not valid for `kind`

validate_phase_transition
#

(from: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", to: "send_request" | "receive_request" | ... 6 more ... | "execute"): void

Validate that a phase chain is legal per ACTION_EVENT_PHASE_TRANSITIONS.

`from`

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"

`to`

type

"send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"

returns

void

throws

Error - if `from → to` is not the permitted next phase (or `from` is terminal)

validate_server_env
#

(env: { NODE_ENV: "development" | "production"; PORT: number; HOST: string; DATABASE_URL: string; SECRET_COOKIE_KEYS: string; ALLOWED_ORIGINS: string; PUBLIC_API_URL: string; PUBLIC_WEBSOCKET_URL?: string | undefined; ... 4 more ...; SMTP_PASSWORD?: string | undefined; }): ServerEnvOptionsResult

Validate a loaded BaseServerEnv and produce the artifacts needed for server init.
Handles keyring validation, origin parsing, and bootstrap token path extraction.
Returns a Result so callers handle errors their own way (exit, logging, etc).

`env`

a loaded and Zod-validated BaseServerEnv

type

{ NODE_ENV: "development" | "production"; PORT: number; HOST: string; DATABASE_URL: string; SECRET_COOKIE_KEYS: string; ALLOWED_ORIGINS: string; PUBLIC_API_URL: string; PUBLIC_WEBSOCKET_URL?: string | undefined; ... 4 more ...; SMTP_PASSWORD?: string | undefined; }

returns

ServerEnvOptionsResult

{ok: true, keyring, allowed_origins, bootstrap_token_path} or {ok: false, field, errors}

validate_step_transition
#

(from: "initial" | "parsed" | "handling" | "handled" | "failed", to: "initial" | "parsed" | "handling" | "handled" | "failed"): void

Validate that a step transition is legal per ACTION_EVENT_STEP_TRANSITIONS.

`from`

type "initial" | "parsed" | "handling" | "handled" | "failed"

`to`

type "initial" | "parsed" | "handling" | "handled" | "failed"

returns

void

throws

Error - if `from → to` is not a permitted transition

ValidatedKeyringResult
#

ValidatedKeyringResult

Result of create_validated_keyring.
Discriminated union — callers handle the error case their own way.

ValidationError
#

ZodObject<{ error: ZodString; issues: ZodArray<ZodObject<{ code: ZodString; message: ZodString; path: ZodArray<ZodUnion<readonly [ZodString, ZodNumber]>>; }, $loose>>; }, $loose>

Input validation error — returned when the request body fails Zod parsing.
issues contains the Zod validation issues for diagnostic display.

verify_dummy
#

(password: string): Promise<boolean>

Verify a password against a dummy hash for timing attack resistance.
Always returns false, but takes the same time as a real verification.
Call when account lookup fails to prevent timing-based user enumeration.

`password`

the plaintext password to "verify"

type string

returns

Promise<boolean>

always false

verify_password
#

http/origin.ts view source

(password: string, password_hash: string): Promise<boolean>

Verify a password against an Argon2id hash.

`password`

the plaintext password to verify

type string

`password_hash`

the Argon2id hash to verify against

type string

returns

Promise<boolean>

true if the password matches

verify_request_source
#

(allowed_patterns: RegExp[]): Handler

Middleware that verifies the request source against an allowlist.
Origin allowlisting (not the CSRF layer — that's SameSite: strict cookies):
- Checks the Origin header first (if present)
- Falls back to Referer header (if no Origin)
- Allows requests without Origin/Referer headers (direct access, curl, etc.)

`allowed_patterns`

compiled regex patterns from parse_allowed_origins

type RegExp[]

returns

Handler

VerifyInput
#

actions/transports_ws.ts view source

ZodVoid

Input for account_verify. No parameters — the caller is the subject.

WebsocketConnection
#

WebsocketConnection

Minimal interface for a WebSocket connection, decoupled from the concrete Socket Cell.

`send`

type (data: object) => boolean

`connected`

type boolean

readonly

`add_message_handler`

type (handler: (event: MessageEvent) => void) => () => void

`add_error_handler`

type (handler: (event: Event) => void) => () => void

WebsocketRpcConnection
#

actions/transports_ws.ts view source

WebsocketRpcConnection

RPC-capable WebSocket connection — a WebsocketConnection that also
handles request/response correlation with timeout, queue,
AbortSignal cancel, and explicit-id support. Required by
FrontendWebsocketTransport so it can delegate the pending-map
bookkeeping to one canonical implementation
(FrontendWebsocketClient) instead of running a parallel one.
Consumer wrappers around FrontendWebsocketClient (e.g. zzz's
Socket) implement this by adding a one-line delegate to the
underlying client's request.

inheritance

extends:

WebsocketConnection

`request`

type

(
		method: string,
		params: unknown,
		options?: {signal?: AbortSignal; queue?: boolean; id?: JsonrpcRequestId},
	) => Promise<unknown>

write_daemon_info
#

(runtime: Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename">, name: string, info: { version: number; pid: number; port: number; started: string; app_version: string; }): Promise<...>

Write daemon info to the PID file, creating directories as needed.

`runtime`

runtime with file write and env capabilities

type Pick<EnvDeps, "env_get"> & Pick<FsWriteDeps, "mkdir" | "write_text_file" | "rename">

`name`

application name

type string

`info`

daemon info to write

type { version: number; pid: number; port: number; started: string; app_version: string; }

returns

Promise<void>

throws

Error - if `$HOME` is not set

write_daemon_token
#

runtime/fs.ts view source

(runtime: DaemonTokenWriteDeps, token_path: string, token: string): Promise<void>

Write the current token to disk atomically.
Uses write_file_atomic (temp file + rename) and optionally sets mode 0600.

`runtime`

runtime with file write capabilities

type DaemonTokenWriteDeps

`token_path`

path to write the token

type string

`token`

the raw token string

type string

returns

Promise<void>

write_file_atomic
#

(deps: Pick<FsWriteDeps, "write_text_file" | "rename">, path: string, content: string): Promise<void>

Write a file atomically via temp file + rename.
Writes to <path>.tmp then renames over path so readers either see the
old contents or the full new contents — never a partial write.

`deps`

type Pick<FsWriteDeps, "write_text_file" | "rename">

`path`

type string

`content`

type string

returns

Promise<void>

throws

Error - if `write_text_file` or `rename` rejects (permissions, disk full, cross-device rename, etc.)

WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT
#

4002

WebSocket close code — client timed out waiting for a response.

WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT
#

4003

WebSocket close code — server timed out with no incoming activity.

WS_CLOSE_SESSION_REVOKED
#

4001

WebSocket close code for session revocation.

WS_DISCONNECT_EVENT_TYPES
#

actions/action_types.ts view source

ReadonlySet<string>

Audit event types that trigger WebSocket socket closure.
- session_revoke — close only the socket tied to the revoked session hash.
- token_revoke — close only the socket(s) authenticated with the revoked api_token.id.
- session_revoke_all / token_revoke_all / password_change — close every socket
  for the affected account (all credentials invalidated).
permit_revoke is intentionally omitted: the WS transport does not track
per-connection role requirements, so role-scoped disconnection would
require either closing all sockets (too aggressive) or new tracking
(out of scope). Consumers that need it compose their own callback.

WsActionHandler
#

WsActionHandler<TCtx>

Handler signature — receives validated input and per-request context.
Named to disambiguate from actions/action_rpc.ts's ActionHandler
(HTTP-side, ActionContext + two generic slots). The WS variant is
single-slotted on the context and returns unknown.

generics

`TCtx`

constraint BaseHandlerContext

default BaseHandlerContext

WsConnectIdentity
#

WsConnectIdentity

Auth identity for a mock connection.

`account_id`

Account id for the connection. Defaults to a fresh uuid per call.

type Uuid

`credential_type`

Credential type. Defaults to 'session'. Keeper actions require 'daemon_token'.

type CredentialType

`session_id`

Session id (any string). Defaults to a fresh uuid. Hashed by the dispatcher.

type string

`api_token_id`

Api token id; set for bearer connections, null otherwise.

type string | null

`roles`

Roles to grant via active permits. Pass [ROLE_KEEPER] for keeper actions.

type Array<string>

WsTestHarness
#

WsTestHarness

A harness instance — transport handle + connection factory.

`transport`