api #

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

Auth table DDL — CREATE TABLE, index, and seed statements.

Consumed by migrations.ts. Separated from account_schema.ts to isolate DDL concerns from runtime types.

Per-factory configuration for account route specs.

Options for the account status route spec.

Options for deriving an SseEventSpec from an ActionSpec.

Utility class to manage and query action specifications. Provides helper methods to get actions by various criteria.

Options for deriving a RouteSpec from an ActionSpec.

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

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

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

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

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

Options for admin route specs.

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

A header-level attack case for middleware stack testing.

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

Alignment options for positioned elements.

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

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

API token for CLI/programmatic access.

Extended deps for query_validate_api_token which needs a logger.

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.

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).

Apply named middleware specs to a Hono app.

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, 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

Result of create_app_server().

Context passed to create_route_specs.

Configuration for create_app_server().

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

App settings row from the database.

Zod schema for client-safe app settings data.

Per-factory configuration for app settings route specs.

Zod schema for admin app settings with resolved updater username.

Generated attack surface — JSON-serializable.

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

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

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

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

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

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).

Argon2id implementation of PasswordHashDeps.

Pass as password in AppDeps / CreateAppBackendOptions for production use.

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.

Every route has a non-empty description.

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.

Assert error coverage meets a minimum threshold.

Computes the ratio of exercised error statuses to total declared error statuses. When min_coverage is 0 (default), logs coverage info without failing. When > 0, fails if coverage is below the threshold.

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.

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.

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.

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

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/...).

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

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.

No duplicate method+path pairs.

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.

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

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.

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

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

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

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

Every protected route has 401 in error_schemas.

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

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

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. Throws with details on mismatch.

Every role/keeper route has 403 in error_schemas.

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.

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.

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

Run all structural invariants. Options-free — applies universally.

Compare live surface against a committed snapshot JSON file.

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

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.

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.

All tracked auth event types.

Default limit for audit log listings.

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.

Log an audit event without blocking the caller.

Errors are logged to console — audit logging never breaks auth flows. Uses background_db so audit entries persist even if the request transaction rolls back. Write failures and on_event callback failures are logged separately so the error message indicates which phase failed.

Per-event-type metadata Zod schemas.

Uses z.looseObject so consumers can add extra fields (e.g. visiones self_service) while known fields are validated. Events with outcome-dependent metadata use a union with z.null().

Configuration for describe_audit_completeness_tests.

Zod schema for audit event types.

Audit log row from the database.

Zod schema for client-safe audit log event.

Zod schema for audit log events with resolved usernames.

Options for fetching audit log events.

Input for creating an audit log entry.

Options for listing audit log entries.

Options for audit log route specs.

Convenience factory result for audit log SSE.

Satisfies AuditLogRouteOptions['stream'] and provides the combined on_audit_event callback (broadcast + guard).

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

Zod schema for audit event outcomes.

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 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.

Namespace identifier for fuz_app auth migrations.

Pre-composed migration namespace for auth tables.

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.

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

Session lifetime in milliseconds (30 days).

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

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.

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.

Per-factory configuration for the standard auth middleware stack.

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

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

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.

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