@fuzdev/fuz_app 0.125.0 → 0.127.0

package/dist/server/app_server.d.ts

@@ -14,7 +14,7 @@ import { type SessionOptions } from '../auth/session_cookie.js';
 import type { BootstrapAccountSuccess } from '../auth/bootstrap_account.js';
 import type { EventSpec } from '../realtime/sse.js';
 import { type AuditLogSse } from '../realtime/sse_auth_guard.js';
-import { type RateLimiter } from '../rate_limiter.js';
+import { RateLimiter, type RateLimiterMode } from '../rate_limiter.js';
 import type { DaemonTokenState } from '../auth/daemon_token.js';
 import type { MigrationResult } from '../db/migrate.js';
 import type { AppBackend } from './app_backend.js';
@@ -25,7 +25,7 @@ import { type AppSurfaceSpec, type RpcEndpointSpec } from '../http/surface.js';
 import { type RouteSpec } from '../http/route_spec.js';
 import type { MiddlewareSpec } from '../http/middleware_spec.js';
 import { type BootstrapStatus } from '../auth/bootstrap_routes.js';
-import type { WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
+import { type WsEndpointSpec } from '../actions/ws_endpoint_spec.js';
 import type { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 import { type AuthCleanupScheduleOptions } from '../auth/cleanup.js';
 /**
@@ -95,10 +95,21 @@ export interface AppServerOptions {
         trusted_proxies: Array<string>;
         get_connection_ip: (c: Context) => string | undefined;
     };
+    /**
+     * 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`.
+     */
+    rate_limiters?: RateLimiterMode;
     /**
      * 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). Pass `null` to explicitly disable rate limiting.
+     * 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
@@ -110,32 +121,34 @@ export interface AppServerOptions {
      */
     login_ip_rate_limiter?: RateLimiter | null;
     /**
-     * Per-IP rate limiter for signup. Omit or `undefined` to use a default
-     * limiter (5 attempts per 15 minutes). Pass `null` to explicitly disable.
+     * 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.
      */
     signup_ip_rate_limiter?: RateLimiter | null;
     /**
-     * Per-IP rate limiter for bootstrap. Omit or `undefined` to use a default
-     * limiter (5 attempts per 15 minutes). Pass `null` to explicitly disable.
+     * 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.
      */
     bootstrap_ip_rate_limiter?: RateLimiter | null;
     /**
-     * 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.
+     * 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.
      */
     login_account_rate_limiter?: RateLimiter | null;
     /**
      * 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.
+     * 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.
      */
     signup_account_rate_limiter?: RateLimiter | null;
@@ -143,20 +156,23 @@ export interface AppServerOptions {
      * 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`.
+     * 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`.
      */
     action_ip_rate_limiter?: RateLimiter | null;
     /**
-     * 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`.
+     * 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`.
      */
     action_account_rate_limiter?: RateLimiter | null;
     /**
@@ -179,7 +195,13 @@ export interface AppServerOptions {
      * Called after all middleware is ready.
      */
     create_route_specs: (context: AppServerContext) => Array<RouteSpec>;
-    /** Optional: transform middleware specs before applying. */
+    /**
+     * Optional: transform middleware specs before applying.
+     *
+     * The endpoint auth-scope check (`assert_endpoint_in_auth_scope`) reads
+     * `AUTH_MIDDLEWARE_PATH`, not the transformed specs — a transform that
+     * moves or drops the auth middleware is not followed by it.
+     */
     transform_middleware?: (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>;
     /**
      * Enable factory-managed audit log SSE.
@@ -226,50 +248,79 @@ export interface AppServerOptions {
     event_specs?: Array<EventSpec>;
     /**
      * 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
+     * *and* live dispatch. Each entry becomes route specs via
+     * `create_rpc_endpoint`, applied with the other routes, so consumers don't 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` — e.g. `create_standard_rpc_actions(ctx.deps)`.
+     *
+     * Each path must sit inside the auth middleware's scope
+     * (`AUTH_MIDDLEWARE_PATH`, `'/api/*'`) — assembly throws otherwise, since
+     * an endpoint outside it would see every caller as unauthenticated.
      */
     rpc_endpoints?: Array<RpcEndpointSpec> | ((context: AppServerContext) => Array<RpcEndpointSpec>);
     /**
-     * Hono adapter's `upgradeWebSocket` helper. Required whenever
-     * `ws_endpoints` resolves to a non-empty array — `create_app_server`
-     * throws at assembly otherwise. Omit (along with `ws_endpoints`)
-     * when the consumer doesn't mount any WS endpoints. The same
-     * adapter helper services every `WsEndpointSpec` mounted from
-     * `ws_endpoints` — one adapter per app.
+     * 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:
+     *
+     * ```ts
+     * import {upgradeWebSocket} from '@hono/deno'; // or '@hono/bun'
+     * create_upgrade_websocket: () => upgradeWebSocket,
+     * ```
      *
-     * For Deno or Bun, `import {upgradeWebSocket} from '@hono/deno'` (or
-     * `'@hono/bun'`). Node's `@hono/node-ws` has no module-level helper -
-     * `createNodeWebSocket({app})` needs the app this function builds - so
-     * on Node omit this and `ws_endpoints`, then mount on the returned
-     * `app` with `register_ws_endpoint` and call `injectWebSocket(server)`
-     * after `serve()`. Test harnesses use `create_stub_upgrade` from
-     * `$lib/testing/ws_round_trip.ts`.
+     * Node keeps the adapter so it can attach to the server after `serve()`:
+     *
+     * ```ts
+     * let node_ws: NodeWebSocket | undefined;
+     * const server = await create_app_server({
+     *   ...,
+     *   create_upgrade_websocket: (app) => (node_ws = createNodeWebSocket({app})).upgradeWebSocket,
+     * });
+     * node_ws?.injectWebSocket(serve({fetch: server.app.fetch, port}));
+     * ```
+     *
+     * Test harnesses pass `() => stub.upgradeWebSocket` with
+     * `create_stub_upgrade` from `testing/ws_round_trip.ts`.
      */
-    upgradeWebSocket?: UpgradeWebSocket;
+    create_upgrade_websocket?: (app: Hono) => UpgradeWebSocket;
     /**
      * 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, so
-     * consumers no longer call `register_ws_endpoint` themselves.
+     * `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` /
-     * `ctx.action_*_rate_limiter` — e.g. when spreading
-     * `create_standard_rpc_actions(ctx.deps, ...)` over WS.
+     * 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, `upgradeWebSocket` must be supplied (throws
+     * 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 `WsEndpointSpec`s throw at
      * mount time (Hono would silently shadow them otherwise).
      *
@@ -353,10 +404,27 @@ export interface AppServer {
      */
     ws_endpoints: Readonly<Record<string, BackendWebsocketTransport>>;
     /**
-     * Shut the server's resources down: stop the auth cleanup schedule when
-     * the `auth_cleanup` option started one — waiting for a pass in progress —
-     * then close the database connection (`AppBackend.close`). That wait has
-     * no bound of its own; a shutdown with a deadline races it.
+     * Shut the server's resources down, in order:
+     *
+     * 1. stop the auth cleanup schedule when the `auth_cleanup` option started
+     *    one, waiting for a pass in progress — that wait has no bound of its
+     *    own, so a shutdown with a deadline races it
+     * 2. close every live connection on `deps.connection_closer`
+     *    (`close_all_sockets`) — each WebSocket with `WS_CLOSE_GOING_AWAY`, each
+     *    audit stream — including transports supplied through
+     *    `WsEndpointSpec.transport` or added by hand, since they are registered
+     *    on the backend's closer and the backend is going away; a close that
+     *    throws is logged and the shutdown goes on
+     * 3. `dispose` the rate limiters `create_app_server` built for omitted
+     *    options — never one passed in, which its caller owns
+     * 4. close the database connection (`AppBackend.close`)
+     *
+     * Idempotent: a second call settles with the first one's outcome (a failed
+     * close is not retried), and concurrent calls share one shutdown.
+     *
+     * Stop accepting new HTTP connections first — without awaiting the
+     * listener's full drain, since live WebSockets hold it open until `close`
+     * ends them — so no new request reaches a closed database.
      */
     close: () => Promise<void>;
 }
@@ -385,9 +453,11 @@ export declare const DEFAULT_MAX_BODY_SIZE: number;
 /**
  * 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 —
+ * Handles the assembly lifecycle: rate limiters → audit SSE → proxy
+ * middleware → auth middleware → bootstrap status → route specs (consumer,
+ * bootstrap, RPC endpoints, surface) → surface generation → Hono app assembly
+ * (routes, then WS endpoints) → post-route middleware → static serving → the
+ * auth cleanup schedule. Database migrations belong to the backend lifecycle —
  * pass `migration_namespaces` to `create_app_backend`.
  *
  * When `audit_log_sse` is set, the SSE registry's listener is registered via
@@ -401,8 +471,11 @@ export declare const DEFAULT_MAX_BODY_SIZE: number;
  * to assert the invariant.
  *
  * When `auth_cleanup` is set, the auth cleanup schedule starts as the last
- * step of assembly — so an assembly that throws leaves no schedule running —
- * and the returned `close` stops it before closing the database.
+ * step of assembly — so an assembly that throws leaves no schedule running.
+ *
+ * The returned `close` owns shutdown: it stops that schedule, closes every
+ * live connection on the backend's closer, disposes the rate limiters built
+ * here, and closes the database (`AppServer.close`).
  *
  * @returns assembled Hono app, backend, surface build, and bootstrap status
  */

package/dist/server/app_server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"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"}

package/dist/server/app_server.js

@@ -14,7 +14,7 @@ import { z } from 'zod';
 import { session_cookie_options } from '../auth/session_cookie.js';
 import { create_audit_log_sse, audit_log_event_specs } from '../realtime/sse_auth_guard.js';
 import { BaseServerEnv } from './env.js';
-import { create_rate_limiter, default_login_account_rate_limit, default_action_account_rate_limit, default_action_ip_rate_limit } from '../rate_limiter.js';
+import { RateLimiter, announce_rate_limiters_disabled, default_login_ip_rate_limit, default_login_account_rate_limit, default_action_account_rate_limit, default_action_ip_rate_limit } from '../rate_limiter.js';
 // Side-effect import: augments Hono's ContextVariableMap so consumers
 // that import app_server get type-safe c.get('auth_session_id') etc.
 import '../hono_context.js';
@@ -26,12 +26,13 @@ import { apply_middleware_specs, apply_route_specs, prefix_route_specs } from '.
 import { check_bootstrap_status, create_bootstrap_route_specs } from '../auth/bootstrap_routes.js';
 import { create_surface_route_spec } from '../http/common_routes.js';
 import { flush_pending_effects, flush_post_commit_effects } from '../http/pending_effects.js';
-import { create_auth_middleware_specs } from '../auth/middleware.js';
+import { assert_endpoint_in_auth_scope, create_auth_middleware_specs } from '../auth/middleware.js';
 import { fuz_auth_guard_resolver } from '../auth/auth_guard_resolver.js';
 import { create_fuz_authorization_handler } from '../auth/request_context.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
 import { register_ws_endpoint } from '../actions/register_ws_endpoint.js';
+import { resolve_ws_endpoints } from '../actions/ws_endpoint_spec.js';
 import { create_ws_auth_guard } from '../actions/transports_ws_auth_guard.js';
 import { start_auth_cleanup } from '../auth/cleanup.js';
 /**
@@ -62,9 +63,11 @@ export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
 /**
  * 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 —
+ * Handles the assembly lifecycle: rate limiters → audit SSE → proxy
+ * middleware → auth middleware → bootstrap status → route specs (consumer,
+ * bootstrap, RPC endpoints, surface) → surface generation → Hono app assembly
+ * (routes, then WS endpoints) → post-route middleware → static serving → the
+ * auth cleanup schedule. Database migrations belong to the backend lifecycle —
  * pass `migration_namespaces` to `create_app_backend`.
  *
  * When `audit_log_sse` is set, the SSE registry's listener is registered via
@@ -78,8 +81,11 @@ export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
  * to assert the invariant.
  *
  * When `auth_cleanup` is set, the auth cleanup schedule starts as the last
- * step of assembly — so an assembly that throws leaves no schedule running —
- * and the returned `close` stops it before closing the database.
+ * step of assembly — so an assembly that throws leaves no schedule running.
+ *
+ * The returned `close` owns shutdown: it stops that schedule, closes every
+ * live connection on the backend's closer, disposes the rate limiters built
+ * here, and closes the database (`AppServer.close`).
  *
  * @returns assembled Hono app, backend, surface build, and bootstrap status
  */
@@ -87,30 +93,31 @@ export const create_app_server = async (options) => {
     const { backend } = options;
     const { deps } = backend;
     const { log } = deps;
-    // Rate limiter defaults (undefined = default, null = disable)
-    // One instance per surface — see `AppServerOptions.login_ip_rate_limiter`
-    // for why these are not a single shared bucket.
-    const login_ip_rate_limiter = options.login_ip_rate_limiter === undefined
-        ? create_rate_limiter()
-        : options.login_ip_rate_limiter;
-    const signup_ip_rate_limiter = options.signup_ip_rate_limiter === undefined
-        ? create_rate_limiter()
-        : options.signup_ip_rate_limiter;
-    const bootstrap_ip_rate_limiter = options.bootstrap_ip_rate_limiter === undefined
-        ? create_rate_limiter()
-        : options.bootstrap_ip_rate_limiter;
-    const login_account_rate_limiter = options.login_account_rate_limiter === undefined
-        ? create_rate_limiter(default_login_account_rate_limit)
-        : options.login_account_rate_limiter;
-    const signup_account_rate_limiter = options.signup_account_rate_limiter === undefined
-        ? create_rate_limiter(default_login_account_rate_limit)
-        : options.signup_account_rate_limiter;
-    const action_ip_rate_limiter = options.action_ip_rate_limiter === undefined
-        ? create_rate_limiter(default_action_ip_rate_limit)
-        : options.action_ip_rate_limiter;
-    const action_account_rate_limiter = options.action_account_rate_limiter === undefined
-        ? create_rate_limiter(default_action_account_rate_limit)
-        : options.action_account_rate_limiter;
+    // Rate limiters: an explicit option (instance or `null`) wins; an omitted
+    // one is a default instance under 'enforced', `null` under
+    // 'disabled_for_testing'. One instance per surface — see
+    // `AppServerOptions.login_ip_rate_limiter` for why these are not a single
+    // shared bucket. The ones built here are the server's to dispose on close.
+    const rate_limiter_mode = options.rate_limiters ?? 'enforced';
+    const built_rate_limiters = [];
+    const resolve_rate_limiter = (option, defaults) => {
+        if (option !== undefined)
+            return option;
+        if (rate_limiter_mode === 'disabled_for_testing') {
+            announce_rate_limiters_disabled();
+            return null;
+        }
+        const limiter = new RateLimiter({ ...defaults });
+        built_rate_limiters.push(limiter);
+        return limiter;
+    };
+    const login_ip_rate_limiter = resolve_rate_limiter(options.login_ip_rate_limiter, default_login_ip_rate_limit);
+    const signup_ip_rate_limiter = resolve_rate_limiter(options.signup_ip_rate_limiter, default_login_ip_rate_limit);
+    const bootstrap_ip_rate_limiter = resolve_rate_limiter(options.bootstrap_ip_rate_limiter, default_login_ip_rate_limit);
+    const login_account_rate_limiter = resolve_rate_limiter(options.login_account_rate_limiter, default_login_account_rate_limit);
+    const signup_account_rate_limiter = resolve_rate_limiter(options.signup_account_rate_limiter, default_login_account_rate_limit);
+    const action_ip_rate_limiter = resolve_rate_limiter(options.action_ip_rate_limiter, default_action_ip_rate_limit);
+    const action_account_rate_limiter = resolve_rate_limiter(options.action_account_rate_limiter, default_action_account_rate_limit);
     // Factory-managed audit SSE — registers a listener on the bound emitter
     // so SSE fan-out runs alongside the consumer's `on_audit_event`
     // without rebuilding `AppDeps`, and adds the registry to the backend's
@@ -195,6 +202,7 @@ export const create_app_server = async (options) => {
         : options.rpc_endpoints;
     if (resolved_rpc_endpoints) {
         for (const endpoint of resolved_rpc_endpoints) {
+            assert_endpoint_in_auth_scope('rpc_endpoints', endpoint.path);
             factory_routes.push(...create_rpc_endpoint({
                 path: endpoint.path,
                 actions: endpoint.actions,
@@ -210,9 +218,24 @@ export const create_app_server = async (options) => {
     // live Hono `app` (origin / auth / role / authorization middleware +
     // the `app.get(path, ...)` upgrade route), and `app` does not exist
     // until the assembly phase below.
-    const resolved_ws_endpoints = typeof options.ws_endpoints === 'function'
+    // A spec without `allowed_origins` takes the server's list — resolved here,
+    // once, so the mount and the surface read the same patterns.
+    const resolved_ws_endpoints = resolve_ws_endpoints(typeof options.ws_endpoints === 'function'
         ? options.ws_endpoints(context)
-        : options.ws_endpoints;
+        : options.ws_endpoints, options.allowed_origins);
+    // the endpoints to mount and the adapter factory they need — null when none resolve
+    let ws_mount = null;
+    if (resolved_ws_endpoints?.length) {
+        const create_upgrade_websocket = options.create_upgrade_websocket;
+        if (create_upgrade_websocket === undefined) {
+            throw new Error('create_app_server: ws_endpoints resolved non-empty but create_upgrade_websocket is missing. ' +
+                "Pass a factory returning the Hono adapter's upgradeWebSocket helper.");
+        }
+        for (const endpoint of resolved_ws_endpoints) {
+            assert_endpoint_in_auth_scope('ws_endpoints', endpoint.path);
+        }
+        ws_mount = { endpoints: resolved_ws_endpoints, create_upgrade_websocket };
+    }
     // Surface route (default: enabled)
     if (options.surface_route !== false) {
         factory_routes.push(create_surface_route_spec(surface_ref));
@@ -260,20 +283,35 @@ export const create_app_server = async (options) => {
             });
         }
     }
-    // One diagnostic per surface — a deployment that disables login's limiter
-    // but keeps signup's is a different posture than one that disables both,
-    // and a single collapsed warning hid which surface was open.
-    for (const [name, limiter] of [
-        ['login', login_ip_rate_limiter],
-        ['signup', signup_ip_rate_limiter],
-        ['bootstrap', bootstrap_ip_rate_limiter]
-    ]) {
-        if (limiter === null) {
-            config_diagnostics.push({
-                level: 'warning',
-                category: 'config',
-                message: `${name} IP rate limiter explicitly disabled (null)`
-            });
+    if (rate_limiter_mode === 'disabled_for_testing') {
+        // one warning for the mode rather than one per limiter it nulled
+        config_diagnostics.push({
+            level: 'warning',
+            category: 'security',
+            message: "rate limiters disabled for testing (rate_limiters: 'disabled_for_testing') — " +
+                'every limiter not passed explicitly is off; never use in production'
+        });
+    }
+    else {
+        // One diagnostic per explicitly-null limiter — a deployment that disables
+        // login's limiter but keeps signup's is a different posture than one that
+        // disables both, and a single collapsed warning hid which surface was open.
+        for (const [name, limiter] of [
+            ['login IP', login_ip_rate_limiter],
+            ['signup IP', signup_ip_rate_limiter],
+            ['bootstrap IP', bootstrap_ip_rate_limiter],
+            ['login account', login_account_rate_limiter],
+            ['signup account', signup_account_rate_limiter],
+            ['action IP', action_ip_rate_limiter],
+            ['action account', action_account_rate_limiter]
+        ]) {
+            if (limiter === null) {
+                config_diagnostics.push({
+                    level: 'warning',
+                    category: 'security',
+                    message: `${name} rate limiter explicitly disabled (null)`
+                });
+            }
         }
     }
     if (config_diagnostics.length) {
@@ -347,11 +385,10 @@ export const create_app_server = async (options) => {
     // adjacent to the consumer routes and ahead of the static fallback —
     // matches the "WS mount is route registration" mental model.
     const mounted_ws_endpoints = {};
-    if (resolved_ws_endpoints?.length) {
-        if (options.upgradeWebSocket === undefined) {
-            throw new Error('create_app_server: ws_endpoints resolved non-empty but upgradeWebSocket is missing. ' +
-                "Pass the Hono adapter's upgradeWebSocket helper as a top-level option.");
-        }
+    if (ws_mount) {
+        // the adapter helper — built from this app, which Node's
+        // `createNodeWebSocket({app})` needs, and only when there is something to mount
+        const upgrade_websocket = ws_mount.create_upgrade_websocket(app);
         // Cross-surface collision: `register_ws_endpoint` mounts a `GET path`
         // upgrade route. If a `RouteSpec` already registered `GET path`,
         // Hono's last-wins semantics would silently shadow the consumer's
@@ -371,7 +408,7 @@ export const create_app_server = async (options) => {
         // (even with explicit `auth_guard: false`) cannot opt out. To
         // disable, every spec sharing the transport must pass `auth_guard: false`.
         const guarded_transports = new WeakSet();
-        for (const endpoint of resolved_ws_endpoints) {
+        for (const endpoint of ws_mount.endpoints) {
             if (seen_paths.has(endpoint.path)) {
                 throw new Error(`create_app_server: duplicate ws_endpoints path: ${endpoint.path}`);
             }
@@ -382,7 +419,7 @@ export const create_app_server = async (options) => {
             const { transport: endpoint_transport } = register_ws_endpoint({
                 app,
                 path: endpoint.path,
-                upgradeWebSocket: options.upgradeWebSocket,
+                upgradeWebSocket: upgrade_websocket,
                 allowed_origins: endpoint.allowed_origins,
                 db: deps.db,
                 actions: endpoint.actions,
@@ -429,6 +466,24 @@ export const create_app_server = async (options) => {
     const auth_cleanup = options.auth_cleanup
         ? start_auth_cleanup(deps, options.auth_cleanup === true ? undefined : options.auth_cleanup)
         : null;
+    // One shutdown, shared by every call — see `AppServer.close` for the order.
+    let closing = null;
+    const shutdown = async () => {
+        // the schedule first, so a pass in progress finishes on a live pool
+        if (auth_cleanup)
+            await auth_cleanup.stop();
+        // then the connections, so none outlives the server — a failure here
+        // must not keep the database open
+        try {
+            deps.connection_closer.close_all_sockets();
+        }
+        catch (error) {
+            log.error('create_app_server: closing live connections on shutdown failed:', error);
+        }
+        for (const limiter of built_rate_limiters)
+            limiter.dispose();
+        await backend.close();
+    };
     return {
         app,
         surface_spec,
@@ -436,12 +491,6 @@ export const create_app_server = async (options) => {
         migration_results: backend.migration_results,
         audit_sse,
         ws_endpoints: mounted_ws_endpoints,
-        close: auth_cleanup
-            ? async () => {
-                // the schedule first, so a pass in progress finishes on a live pool
-                await auth_cleanup.stop();
-                await backend.close();
-            }
-            : backend.close
+        close: () => (closing ??= shutdown())
     };
 };

package/dist/server/app_server_context.d.ts

@@ -26,22 +26,30 @@ export interface AppServerContext {
     bootstrap_status: BootstrapStatus;
     session_options: SessionOptions<string>;
     /**
-     * Per-IP login + password-change rate limiter (from options). `null` when
-     * not configured. One instance per auth surface — see
-     * `AppServerOptions.login_ip_rate_limiter` for why these aren't shared.
+     * Per-IP login + password-change rate limiter. One instance per auth
+     * surface — see `AppServerOptions.login_ip_rate_limiter` for why these
+     * aren't shared.
+     *
+     * Each limiter here is what `create_app_server` resolved: the instance
+     * its option passed, else a default instance under
+     * `rate_limiters: 'enforced'` (the default). `null` when disabled — the
+     * option was an explicit `null`, or the mode is `'disabled_for_testing'`.
      */
     login_ip_rate_limiter: RateLimiter | null;
-    /** Per-IP signup rate limiter (from options). `null` when not configured. */
+    /** Per-IP signup rate limiter. `null` when disabled. */
     signup_ip_rate_limiter: RateLimiter | null;
-    /** Per-IP bootstrap rate limiter (from options). `null` when not configured. */
+    /** Per-IP bootstrap rate limiter. `null` when disabled. */
     bootstrap_ip_rate_limiter: RateLimiter | null;
-    /** Per-account login rate limiter (from options). `null` when not configured. */
+    /** Per-account login rate limiter. `null` when disabled. */
     login_account_rate_limiter: RateLimiter | null;
-    /** Per-account signup rate limiter (from options). `null` when not configured. */
+    /** Per-account signup rate limiter. `null` when disabled. */
     signup_account_rate_limiter: RateLimiter | null;
-    /** Per-IP action-dispatcher rate limiter — shared across HTTP RPC + WS. `null` when not configured. */
+    /** Per-IP action-dispatcher rate limiter — shared across HTTP RPC + WS. `null` when disabled. */
     action_ip_rate_limiter: RateLimiter | null;
-    /** Per-actor action-dispatcher rate limiter — shared across HTTP RPC + WS. `null` when not configured. */
+    /**
+     * Per-account action-dispatcher rate limiter, keyed on the authenticated
+     * account's id — shared across HTTP RPC + WS. `null` when disabled.
+     */
     action_account_rate_limiter: RateLimiter | null;
     /**
      * Factory-managed audit log SSE. Non-null when the `audit_log_sse`