testing/app_server.ts

Optional email stored on the account row — exercises the username-or-email login lookup.

test app configuration

bootstrap config + factory inputs

session options and optional overrides

Optional email stored on the account row — exercises the username-or-email login lookup.

Optional email stored on the account row — exercises the username-or-email login lookup.

Live bootstrap config — the test drives POST /bootstrap against this.

Token contents the stub fs returns when reading bootstrap.token_path. The test posts a body containing this same value as token to satisfy the timing-safe equality check inside bootstrap_account.

Route spec factory — called with the assembled AppServerContext.

RPC endpoints mounted by create_app_server — eager array or (ctx: AppServerContext) => Array<RpcEndpointSpec> factory. Single source of truth; the equivalent slot under app_options is Omit'd so setup-time path lookup and runtime dispatch read from one place. Symmetric with the suite-level rpc_endpoints option on describe_standard_admin_integration_tests etc.

Bootstrap config — symmetric with AppServerOptions.bootstrap. Same single-source-of-truth precedent as rpc_endpoints: setup-time surface generation and runtime dispatch both read this slot, so the equivalent field under app_options is Omit'd. Discriminated union over {mode: 'disabled' | 'surface_only' | 'live'}. Omit (or pass {mode: 'disabled'}) for the default — no bootstrap route mounted.

For tests that exercise the bootstrap success path against a real token + empty DB, use create_test_app_for_bootstrap instead — it skips the keeper pre-creation that blocks the success branch.

Optional overrides for AppServerOptions. Excludes fields create_test_app manages directly: backend, session_options, create_route_specs, rpc_endpoints, bootstrap (top-level slots above).

Account the minted session belongs to.

Session lifetime offset in seconds applied to NOW() for the auth_session.expires_at row. A negative value backdates the row so the authoritative DB-row expiry gate (query_session_get_valid — WHERE expires_at > NOW()) rejects it, while the returned cookie's own signed payload stays valid (future). Resolution therefore passes the cookie-payload check in parse_session and is refused at the DB-row gate — the gate the in-process payload-expiry tests never reach and the one that structurally needs a server-side mint.

Per-IP rate limiter for login + password change — the distributed-spray backstop. Omit or undefined to use a default limiter (5 attempts per 15 minutes) under rate_limiters: 'enforced', none under 'disabled_for_testing'. Pass null to explicitly disable rate limiting. Also available on AppServerContext for route factory callbacks.

One instance per auth surface, not one shared across all four. These buckets are monotone within their window — a success never refunds them (see RateLimiter.reset) — so a shared instance let a failure on any surface spend the budget that bounds guessing on every other one, and let one caller's exhaustion deny four routes at once. Pass the same limiter to two of these fields to opt back into a shared budget.

Per-IP rate limiter for signup. Omit or undefined for the mode's default (5 attempts per 15 minutes under rate_limiters: 'enforced'). Pass null to explicitly disable. Separate from login_ip_rate_limiter because an open-signup deployment lets any unauthenticated caller spend it. Also available on AppServerContext for route factory callbacks.

Per-IP rate limiter for bootstrap. Omit or undefined for the mode's default (5 attempts per 15 minutes under rate_limiters: 'enforced'). Pass null to explicitly disable. Separate from login_ip_rate_limiter so a fumbled bootstrap token can't spend the operator's login budget. Wired directly into the factory-managed bootstrap route; also on AppServerContext for symmetry.

Per-account rate limiter for login attempts. Omit or undefined for the mode's default (10 attempts per 30 minutes under rate_limiters: 'enforced'). Pass null to explicitly disable. Also available on AppServerContext for route factory callbacks.

Per-account rate limiter for signup attempts, keyed by submitted username. Omit or undefined for the mode's default (10 attempts per 30 minutes under rate_limiters: 'enforced'). Pass null to explicitly disable. Also available on AppServerContext for route factory callbacks.

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 for the mode's default (600 attempts per 15 minutes — permissive — under rate_limiters: 'enforced'). Pass null to explicitly disable. Threaded into every endpoint mounted from rpc_endpoints and ws_endpoints; also available on AppServerContext.

Per-account rate limiter for the action dispatchers (HTTP RPC + WebSocket). Consulted for actions whose spec declares rate_limit: 'account' or 'both'. Keyed on the authenticated account's id, so every actor and credential of one account shares a budget. Omit or undefined for the mode's default (1200 attempts per 15 minutes — permissive — under rate_limiters: 'enforced'). Pass null to explicitly disable. Threaded into every endpoint mounted from rpc_endpoints and ws_endpoints; also available on AppServerContext.

Parsed allowed origin patterns.

Trusted proxy options.

What an omitted rate limiter becomes — 'enforced' (the default) builds a default instance for each *_rate_limiter option left out, 'disabled_for_testing' leaves each of them null. An explicit option (an instance or null) always wins over the mode. The disabled mode adds one surface warning, and prints a stderr banner once per module instance (announce_rate_limiters_disabled). Never 'disabled_for_testing' in production — see RateLimiterMode.

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

Daemon token state for keeper auth. Omit to disable.

Mount GET /api/surface, which serves this server's generated AppSurface (every route, its auth, and its schemas) to an admin UI such as AdminSurface.svelte. Off by default — the Rust spine serves no such route, and a map of the API is nothing to publish unasked.

When mounted the route is admin-only (roles: ['admin'], so it takes the ?acting= selector) and a rule-3 token surface (required_scope: 'surface:app_surface'): a narrowed API token is refused it whatever its method list says. See server/surface_route.ts.

Optional: transform middleware specs before applying.

Receives shallow copies of the trusted-proxy spec followed by the auth stack, in a fresh array — mutating them leaves the originals untouched. Add layers anywhere (before the proxy spec, between it and the auth stack, between the auth layers, or after), but keep each of those specs — its handler, not just its name — mounted once at its original path ('*' for the proxy, AUTH_MIDDLEWARE_PATH for auth) in its original order: the endpoint auth-scope check (assert_endpoint_in_auth_scope) and client-IP rate limiting (get_client_ip) assume it, so assembly throws (assert_middleware_stack_mounted) if the transform moves, drops, duplicates, reorders, wraps, or replaces one. The check pins where those layers sit, not what added layers do — a layer you add runs with full context access.

Enable factory-managed audit log SSE.

When truthy, creates an AuditLogSse instance internally, registers the SSE listener via backend.deps.audit.add_listener (composing with the consumer's on_audit_event callback rather than rebuilding AppDeps), adds its registry to backend.deps.connection_closer so revocations close its streams, and auto-includes audit_log_event_specs in the surface. The result is exposed on AppServerContext (for route factories) and AppServer (for the caller), always typed as AuditLogSse | null — when this option is set, the field is non-null. Use require_audit_sse(ctx) to assert the invariant in route factories that depend on it.

Pass true for defaults (admin role), or {role: 'custom'} for a custom role. Omit to wire audit SSE manually.

Schedule the auth cleanup beside the server: start_auth_cleanup over backend.deps — a pass as assembly finishes, then one per interval — stopped by AppServer.close. Each pass deletes expired sessions and closes the connections they opened through deps.connection_closer (every WebSocket transport and audit stream this server mounts), and audits each newly expired role_grant offer once.

Off by default; a production server should turn it on. Without it nothing sweeps: expired session rows accumulate, a WebSocket or audit stream outlives the expiry of the session it opened on until it disconnects, and an offer's expiry is never audited. With it, a connection outlives its session's expiry by at most one interval. The Rust spine's servers all schedule the twin (spawn_auth_cleanup).

Pass true for the default interval (DEFAULT_AUTH_CLEANUP_INTERVAL_MS), or {interval_ms} for another. Leave it off in an in-process test harness — a background pass deletes rows and writes audit rows mid-test — and in a process that runs run_auth_cleanup on a schedule of its own.

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

Returns the Hono runtime adapter's upgradeWebSocket helper for the assembled app. create_app_server calls it once, with the app it builds (the same instance as AppServer.app), after creating the app and before mounting ws_endpoints — and only when ws_endpoints resolves non-empty, so it is never called for a server with no WebSocket endpoints. Required in that case: assembly throws without it. One helper services every mounted endpoint.

A factory rather than the helper itself because Node's adapter needs the app: @hono/node-ws has no module-level helper, only createNodeWebSocket({app}), and create_app_server is what builds the app. Deno and Bun ignore the argument:

Node keeps the adapter so it can attach to the server after serve():

Test harnesses pass () => stub.upgradeWebSocket with create_stub_upgrade from testing/ws_round_trip.ts.

WebSocket endpoint specs — single source of truth for both surface generation *and* live dispatch. Each entry is auto-mounted via register_ws_endpoint against the assembled Hono app on every runtime, so consumers don't call register_ws_endpoint themselves.

Accepts either an array (evaluated eagerly) or a factory (ctx: AppServerContext) => ReadonlyArray<WsEndpointSpec> (evaluated after the server context is assembled). Use the factory form when action lists depend on ctx.deps — e.g. when spreading create_standard_rpc_actions({...ctx.deps, notification_sender}) over WS.

When non-empty, create_upgrade_websocket must be supplied (throws otherwise). A factory returning [] does NOT trip the check — feature-flag gated WS surfaces stay safe.

Every mount gets what the HTTP surface gets: the auth middleware (a path outside AUTH_MIDDLEWARE_PATH throws at assembly, like rpc_endpoints), the server's allowed_origins unless the spec narrows them, and the same action_ip_rate_limiter / action_account_rate_limiter instances the RPC endpoints charge — one budget per action across both transports. The upgrade routes register after the route specs and before post_route_middleware and static_serving, so neither runs ahead of an upgrade.

Duplicate path values across two WsEndpointSpecs, and a path a GET RouteSpec already claims, throw at assembly before any endpoint mounts (Hono would silently shadow them otherwise).

Every mounted transport is added to deps.connection_closer, so the revocation handlers' post-commit closes reach its sockets — unconditionally, since those closes are what ends a revoked credential's connections. AppServer.close removes it again.

Each spec's auth_guard? defaults to true — the factory registers create_ws_auth_guard against the mounted transport via deps.audit.add_listener, repeating the close on the audit row. Wiring is deduped by transport reference identity so two specs sharing one BackendWebsocketTransport instance get a single listener; wrapped / proxied transports dedupe as separate entries (set auth_guard: false on duplicates and compose against the underlying transport once).

Env schema for surface generation. Defaults to BaseServerEnv — pass an extended schema (typically BaseServerEnv.extend({...})) when the consumer adds app-specific env vars.

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

Static file serving. Omit if not serving static files.

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

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

Env values for startup summary logging.

Signed session cookie value.

Raw API token for Bearer auth.

Build request headers with this account's session cookie.

Build request headers with this account's Bearer token.

The assembled AppServer — reach for what create_app_server built beyond the fields lifted onto TestApp: audit_sse (with audit_log_sse in app_options), the ws_endpoints transports, bootstrap_status, migration_results.

Build request headers with the bootstrapped session cookie.

Build request headers with the bootstrapped Bearer token.

Build request headers with the daemon token (keeper auth).

Create an additional account with credentials.

Cleanup resources — AppServer.close: stops an opted-in auth cleanup schedule, closes live connections, disposes the limiters the server built and removes the audit listeners and closer members it added, then the backend's close. Idempotent.

The assembled AppServer, as on TestApp — bootstrap_status, audit_sse, the ws_endpoints transports.

Build host/origin request headers for the anonymous bootstrap POST.

Cleanup resources — AppServer.close, as on TestApp; the backend's own close leaves the injected or factory-cached database open. Idempotent.

The bootstrapped account.

The actor linked to the account.

Raw API token for Bearer auth.

Signed session cookie value for cookie auth.

Keyring used for cookie signing — exposed for forging expired/tampered cookies in tests.

Release test resources (no-op when DB is injected or factory-cached).

Session options — needed for cookie signing.

Existing database — skips internal DB creation when provided. Caller owns the DB lifecycle.

Database driver type — only used when db is provided. Default: 'pglet-memory'.

Extra migration namespaces run after the builtin auth namespace in the auto-created in-memory database, mirroring create_app_backend's migration_namespaces. For suites whose backend needs tables beyond auth — the cell parity suite passes [CELL_MIGRATION_NS]. The harness builds + caches a fresh-per-test factory migrating [auth_migration_ns, ...migration_namespaces]; the reset-on-create gives the same fresh-db isolation as the auth-only default. Mutually exclusive with db (which assumes the caller already migrated).

Password implementation. Default: stub_password_deps. Pass argon2_password_deps for tests that exercise login.

Username for the bootstrapped account. Default: 'keeper'.

Password for the bootstrapped account. Default: DEFAULT_TEST_PASSWORD.

Roles to grant. Default: [ROLE_KEEPER].

Build the bound AuditEmitter used by the test backend. Defaults to default_audit_factory (a no-listener create_audit_emitter over the test backend's {db, log}). Pass a custom factory when a test needs:

• to capture audit events (compose on_audit_event inside the body)
• to register consumer event-type schemas (pass audit_log_config)
• to instrument emit (emit_decorator)
• to wrap or replace the emitter for some other reason

Matches the production shape — create_app_backend requires an audit_factory and create_test_app_server mirrors that contract end-to-end.