@fuzdev/fuz_app 0.128.0 → 0.130.0

package/dist/server/app_server.d.ts

@@ -10,18 +10,18 @@
 import { Hono, type Context } from 'hono';
 import type { UpgradeWebSocket } from 'hono/ws';
 import { z } from 'zod';
-import { type SessionOptions } from '../auth/session_cookie.js';
+import { type SessionOptions, type SessionCookieOptions } 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 { RateLimiter, type RateLimiterMode } from '../rate_limiter.js';
+import { RateLimiter, type RateLimiterMode, type RateLimiterOptions } 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';
 import type { AppServerContext } from './app_server_context.js';
 import '../hono_context.js';
 import { type ServeStaticFactory } from './static.js';
-import { type AppSurfaceSpec, type RpcEndpointSpec } from '../http/surface.js';
+import { type AppSurfaceSpec, type AppSurfaceDiagnostic, 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';
@@ -186,10 +186,19 @@ export interface AppServerOptions {
     /** Bootstrap options. Omit to skip bootstrap status check and routes. */
     bootstrap?: BootstrapServerOptions;
     /**
-     * Set to `false` to disable the auto-created surface route (`GET /api/surface`).
-     * Default: auto-created (authenticated).
+     * 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`.
+     *
+     * @default false
      */
-    surface_route?: false;
+    surface_route?: boolean;
     /**
      * Build route specs from the initialized backend.
      * Called after all middleware is ready.
@@ -424,7 +433,10 @@ export interface AppServer {
      *    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
+     *    throws is logged and the shutdown goes on. Each transport and registry
+     *    is left closing, so an upgrade or stream that registers afterward is
+     *    born closed — refused at once rather than outliving the server — and
+     *    a closed transport hosts no other server
      * 3. release what assembly acquired, last acquired first: remove the
      *    audit listeners `create_app_server` registered on `deps.audit` (the
      *    audit-log SSE listener, the WS auth guards, each
@@ -469,6 +481,106 @@ export declare const require_audit_sse: (source: {
 }) => AuditLogSse;
 /** Default maximum request body size: 1 MiB. */
 export declare const DEFAULT_MAX_BODY_SIZE: number;
+/**
+ * Each `AppServerOptions` rate-limiter field, with the defaults an omitted one
+ * is built from under `rate_limiters: 'enforced'` and the name its
+ * explicitly-null diagnostic uses. Insertion order is the order limiters are
+ * built and their diagnostics are listed.
+ */
+declare const rate_limiter_slots: {
+    readonly login_ip_rate_limiter: {
+        readonly label: "login IP";
+        readonly defaults: RateLimiterOptions;
+    };
+    readonly signup_ip_rate_limiter: {
+        readonly label: "signup IP";
+        readonly defaults: RateLimiterOptions;
+    };
+    readonly bootstrap_ip_rate_limiter: {
+        readonly label: "bootstrap IP";
+        readonly defaults: RateLimiterOptions;
+    };
+    readonly login_account_rate_limiter: {
+        readonly label: "login account";
+        readonly defaults: RateLimiterOptions;
+    };
+    readonly signup_account_rate_limiter: {
+        readonly label: "signup account";
+        readonly defaults: RateLimiterOptions;
+    };
+    readonly action_ip_rate_limiter: {
+        readonly label: "action IP";
+        readonly defaults: RateLimiterOptions;
+    };
+    readonly action_account_rate_limiter: {
+        readonly label: "action account";
+        readonly defaults: RateLimiterOptions;
+    };
+};
+/**
+ * Name of an `AppServerOptions` rate-limiter field — also the
+ * `AppServerContext` field its resolved limiter lands on.
+ *
+ * @internal
+ */
+export type AppServerRateLimiterKey = keyof typeof rate_limiter_slots;
+/**
+ * Every `AppServerOptions` rate-limiter field, in build order.
+ *
+ * @internal
+ */
+export declare const APP_SERVER_RATE_LIMITER_KEYS: ReadonlyArray<AppServerRateLimiterKey>;
+/**
+ * The rate limiters `create_app_server` resolved from its options.
+ *
+ * @internal
+ */
+export interface ResolvedRateLimiters {
+    /** The `rate_limiters` mode, defaulted to `'enforced'`. */
+    mode: RateLimiterMode;
+    /** Each limiter by option name — `null` when off. */
+    limiters: Record<AppServerRateLimiterKey, RateLimiter | null>;
+    /**
+     * The limiters built here for omitted options, in build order — the
+     * server's to dispose. Never one passed in, which its caller owns.
+     */
+    built: Array<RateLimiter>;
+}
+/**
+ * Resolve each rate-limiter option: an explicit option (instance or `null`)
+ * wins; an omitted one is a default instance under `'enforced'` and `null`
+ * under `'disabled_for_testing'`, which also announces the mode on stderr
+ * (`announce_rate_limiters_disabled`). One instance per surface — see
+ * `AppServerOptions.login_ip_rate_limiter` for why these are not a single
+ * shared bucket.
+ *
+ * @param options - the rate-limiter fields and `rate_limiters` mode of `AppServerOptions`
+ * @internal
+ */
+export declare const resolve_rate_limiters: (options: Pick<AppServerOptions, AppServerRateLimiterKey | "rate_limiters">) => ResolvedRateLimiters;
+/**
+ * Inputs to `collect_config_diagnostics`.
+ *
+ * @internal
+ */
+export interface ConfigDiagnosticsInput {
+    /** The session cookie overrides, from `AppServerOptions.session_options`. */
+    cookie_options: Partial<SessionCookieOptions> | undefined;
+    /** The `rate_limiters` mode, defaulted. */
+    rate_limiter_mode: RateLimiterMode;
+    /** The resolved limiters, from `resolve_rate_limiters`. */
+    rate_limiters: Record<AppServerRateLimiterKey, RateLimiter | null>;
+}
+/**
+ * The config-level diagnostics `create_app_server` appends to the surface's
+ * spec-level ones: a weakened session cookie, and an open rate-limited
+ * surface — one warning for `'disabled_for_testing'`, otherwise one per
+ * explicitly-null limiter, so a deployment that disables login's limiter but
+ * keeps signup's reads differently from one that disables both.
+ *
+ * @internal
+ */
+export declare const collect_config_diagnostics: (input: ConfigDiagnosticsInput) => Array<AppSurfaceDiagnostic>;
 /**
  * Create a fully assembled Hono app with auth, middleware, and routes.
  *
@@ -503,8 +615,10 @@ export declare const DEFAULT_MAX_BODY_SIZE: number;
  * live connection on the backend's closer, runs the same releases, and
  * closes the database (`AppServer.close`).
  *
- * @returns assembled Hono app, backend, surface build, and bootstrap status
+ * @returns the assembled Hono app with its surface, bootstrap status, migration results,
+ *   audit SSE, mounted WS transports, and `close`
  * @throws Error from any assembly step, after releasing what assembly acquired
  */
 export declare const create_app_server: (options: AppServerOptions) => Promise<AppServer>;
+export {};
 //# sourceMappingURL=app_server.d.ts.map

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":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAEN,KAAK,cAAc,EAEnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAIN,KAAK,WAAW,EAChB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACN,WAAW,EAMX,KAAK,eAAe,EAEpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAEN,KAAK,cAAc,EAEnB,KAAK,eAAe,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAGN,KAAK,eAAe,EACpB,MAAM,6BAA6B,CAAC;AAarC,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAsB,KAAK,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEzF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,sBAAsB,GACjC,wBAAwB,GAAG,2BAA2B,GAAG,oBAAoB,CAAC;AAE/E,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC3C,IAAI,EAAE,cAAc,CAAC;IACrB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,2DAA2D;IAC3D,OAAO,EAAE,UAAU,CAAC;IACpB,6CAA6C;IAC7C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,sCAAsC;IACtC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE/B,6BAA6B;IAC7B,KAAK,EAAE;QACN,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;KACtD,CAAC;IAEF;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC;;;;;;;;;;;;;OAaG;IACH,qBAAqB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3C;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,yBAAyB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IAEtC,yEAAyE;IACzE,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAEnC;;;OAGG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC;IAEtB;;;OAGG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAEpE;;;;;;;;;;;;;;;OAeG;IACH,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,KAAK,CAAC,cAAc,CAAC,CAAC;IAE/E;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,EAAE,IAAI,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,0BAA0B,CAAC;IAEpD,gFAAgF;IAChF,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;IAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,wBAAwB,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,gBAAgB,CAAC;IAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,YAAY,CAAC,EACZ,aAAa,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;IAEhG;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IAEzB,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAE9C,6DAA6D;IAC7D,cAAc,CAAC,EAAE;QAChB,YAAY,EAAE,kBAAkB,CAAC;QACjC,4DAA4D;QAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,gEAAgE;QAChE,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB;;;;WAIG;QACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IAEF;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAExE,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACzB,GAAG,EAAE,IAAI,CAAC;IACV,wEAAwE;IACxE,YAAY,EAAE,cAAc,CAAC;IAC7B,gBAAgB,EAAE,eAAe,CAAC;IAClC,oGAAoG;IACpG,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAClD;;;;OAIG;IACH,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAClE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ;IAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,KAAG,WAO7E,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,SAAS,CAQpF,CAAC"}
+{"version":3,"file":"app_server.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/app_server.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAIN,KAAK,WAAW,EAChB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACN,WAAW,EAMX,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAEN,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAGN,KAAK,eAAe,EACpB,MAAM,6BAA6B,CAAC;AAarC,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAsB,KAAK,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAEzF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,sBAAsB,GACjC,wBAAwB,GAAG,2BAA2B,GAAG,oBAAoB,CAAC;AAE/E,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC3C,IAAI,EAAE,cAAc,CAAC;IACrB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,EAAE,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,2DAA2D;IAC3D,OAAO,EAAE,UAAU,CAAC;IACpB,6CAA6C;IAC7C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,sCAAsC;IACtC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE/B,6BAA6B;IAC7B,KAAK,EAAE;QACN,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,iBAAiB,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;KACtD,CAAC;IAEF;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC;;;;;;;;;;;;;OAaG;IACH,qBAAqB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3C;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;;;OAOG;IACH,yBAAyB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,2BAA2B,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IAEtC,yEAAyE;IACzE,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAEnC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,kBAAkB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAEpE;;;;;;;;;;;;;;;OAeG;IACH,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,KAAK,CAAC,cAAc,CAAC,CAAC;IAE/E;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,EAAE,IAAI,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,0BAA0B,CAAC;IAEpD,gFAAgF;IAChF,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC;IAEjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,wBAAwB,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,gBAAgB,CAAC;IAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,YAAY,CAAC,EACZ,aAAa,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;IAEhG;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IAEzB,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAE9C,6DAA6D;IAC7D,cAAc,CAAC,EAAE;QAChB,YAAY,EAAE,kBAAkB,CAAC;QACjC,4DAA4D;QAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,gEAAgE;QAChE,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB;;;;WAIG;QACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;KACzC,CAAC;IAEF;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAExE,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,uCAAuC;AACvC,MAAM,WAAW,SAAS;IACzB,GAAG,EAAE,IAAI,CAAC;IACV,wEAAwE;IACxE,YAAY,EAAE,cAAc,CAAC;IAC7B,gBAAgB,EAAE,eAAe,CAAC;IAClC,oGAAoG;IACpG,iBAAiB,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAClD;;;;OAIG;IACH,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAClE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ;IAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,KAAG,WAO7E,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAEjD;;;;;GAKG;AACH,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiB4D,CAAC;AAErF;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,EAEpC,aAAa,CAAC,uBAAuB,CAAC,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACpC,2DAA2D;IAC3D,IAAI,EAAE,eAAe,CAAC;IACtB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC,uBAAuB,EAAE,WAAW,GAAG,IAAI,CAAC,CAAC;IAC9D;;;OAGG;IACH,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,IAAI,CAAC,gBAAgB,EAAE,uBAAuB,GAAG,eAAe,CAAC,KACxE,oBAkBF,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,6EAA6E;IAC7E,cAAc,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,SAAS,CAAC;IAC1D,2CAA2C;IAC3C,iBAAiB,EAAE,eAAe,CAAC;IACnC,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC,uBAAuB,EAAE,WAAW,GAAG,IAAI,CAAC,CAAC;CACnE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GACtC,OAAO,sBAAsB,KAC3B,KAAK,CAAC,oBAAoB,CAiD5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,iBAAiB,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,SAAS,CAQpF,CAAC"}

package/dist/server/app_server.js

@@ -24,7 +24,7 @@ import { log_startup_summary } from './startup.js';
 import { create_app_surface_spec } from '../http/surface.js';
 import { apply_middleware_specs, apply_route_specs, prefix_route_specs } from '../http/route_spec.js';
 import { check_bootstrap_status, create_bootstrap_route_specs } from '../auth/bootstrap_routes.js';
-import { create_surface_route_spec } from '../http/common_routes.js';
+import { create_surface_route_spec } from './surface_route.js';
 import { flush_pending_effects, flush_post_commit_effects } from '../http/pending_effects.js';
 import { assert_endpoint_in_auth_scope, assert_middleware_stack_mounted, create_auth_middleware_specs } from '../auth/middleware.js';
 import { fuz_auth_guard_resolver } from '../auth/auth_guard_resolver.js';
@@ -60,6 +60,125 @@ export const require_audit_sse = (source) => {
 };
 /** Default maximum request body size: 1 MiB. */
 export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
+/**
+ * Each `AppServerOptions` rate-limiter field, with the defaults an omitted one
+ * is built from under `rate_limiters: 'enforced'` and the name its
+ * explicitly-null diagnostic uses. Insertion order is the order limiters are
+ * built and their diagnostics are listed.
+ */
+const rate_limiter_slots = {
+    login_ip_rate_limiter: { label: 'login IP', defaults: default_login_ip_rate_limit },
+    signup_ip_rate_limiter: { label: 'signup IP', defaults: default_login_ip_rate_limit },
+    bootstrap_ip_rate_limiter: { label: 'bootstrap IP', defaults: default_login_ip_rate_limit },
+    login_account_rate_limiter: {
+        label: 'login account',
+        defaults: default_login_account_rate_limit
+    },
+    signup_account_rate_limiter: {
+        label: 'signup account',
+        defaults: default_login_account_rate_limit
+    },
+    action_ip_rate_limiter: { label: 'action IP', defaults: default_action_ip_rate_limit },
+    action_account_rate_limiter: {
+        label: 'action account',
+        defaults: default_action_account_rate_limit
+    }
+};
+/**
+ * Every `AppServerOptions` rate-limiter field, in build order.
+ *
+ * @internal
+ */
+export const APP_SERVER_RATE_LIMITER_KEYS = Object.keys(rate_limiter_slots);
+/**
+ * Resolve each rate-limiter option: an explicit option (instance or `null`)
+ * wins; an omitted one is a default instance under `'enforced'` and `null`
+ * under `'disabled_for_testing'`, which also announces the mode on stderr
+ * (`announce_rate_limiters_disabled`). One instance per surface — see
+ * `AppServerOptions.login_ip_rate_limiter` for why these are not a single
+ * shared bucket.
+ *
+ * @param options - the rate-limiter fields and `rate_limiters` mode of `AppServerOptions`
+ * @internal
+ */
+export const resolve_rate_limiters = (options) => {
+    const mode = options.rate_limiters ?? 'enforced';
+    const limiters = {};
+    const built = [];
+    for (const key of APP_SERVER_RATE_LIMITER_KEYS) {
+        const option = options[key];
+        if (option !== undefined) {
+            limiters[key] = option;
+        }
+        else if (mode === 'disabled_for_testing') {
+            announce_rate_limiters_disabled();
+            limiters[key] = null;
+        }
+        else {
+            const limiter = new RateLimiter({ ...rate_limiter_slots[key].defaults });
+            built.push(limiter);
+            limiters[key] = limiter;
+        }
+    }
+    return { mode, limiters, built };
+};
+/**
+ * The config-level diagnostics `create_app_server` appends to the surface's
+ * spec-level ones: a weakened session cookie, and an open rate-limited
+ * surface — one warning for `'disabled_for_testing'`, otherwise one per
+ * explicitly-null limiter, so a deployment that disables login's limiter but
+ * keeps signup's reads differently from one that disables both.
+ *
+ * @internal
+ */
+export const collect_config_diagnostics = (input) => {
+    const diagnostics = [];
+    const { cookie_options } = input;
+    if (cookie_options) {
+        if (cookie_options.secure === false) {
+            diagnostics.push({
+                level: 'warning',
+                category: 'security',
+                message: 'Session cookie secure=false — cookies sent over HTTP'
+            });
+        }
+        if (cookie_options.sameSite && cookie_options.sameSite !== session_cookie_options.sameSite) {
+            diagnostics.push({
+                level: 'warning',
+                category: 'security',
+                message: `Session cookie sameSite='${cookie_options.sameSite}' — weakened from default '${session_cookie_options.sameSite}'`
+            });
+        }
+        if (cookie_options.httpOnly === false) {
+            diagnostics.push({
+                level: 'warning',
+                category: 'security',
+                message: 'Session cookie httpOnly=false — cookie accessible to JS'
+            });
+        }
+    }
+    if (input.rate_limiter_mode === 'disabled_for_testing') {
+        // one warning for the mode rather than one per limiter it nulled
+        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 {
+        for (const key of APP_SERVER_RATE_LIMITER_KEYS) {
+            if (input.rate_limiters[key] === null) {
+                diagnostics.push({
+                    level: 'warning',
+                    category: 'security',
+                    message: `${rate_limiter_slots[key].label} rate limiter explicitly disabled (null)`
+                });
+            }
+        }
+    }
+    return diagnostics;
+};
 /**
  * Create a fully assembled Hono app with auth, middleware, and routes.
  *
@@ -94,7 +213,8 @@ export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
  * live connection on the backend's closer, runs the same releases, and
  * closes the database (`AppServer.close`).
  *
- * @returns assembled Hono app, backend, surface build, and bootstrap status
+ * @returns the assembled Hono app with its surface, bootstrap status, migration results,
+ *   audit SSE, mounted WS transports, and `close`
  * @throws Error from any assembly step, after releasing what assembly acquired
  */
 export const create_app_server = async (options) => {
@@ -130,31 +250,13 @@ const assemble_app_server = async (options, releases) => {
     const { backend } = options;
     const { deps } = backend;
     const { log } = deps;
-    // 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, or when assembly fails.
-    const rate_limiter_mode = options.rate_limiters ?? 'enforced';
-    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 });
+    // Rate limiters — the ones built here are the server's to dispose, on
+    // close or when assembly fails.
+    const { mode: rate_limiter_mode, limiters: rate_limiters, built: built_rate_limiters } = resolve_rate_limiters(options);
+    for (const limiter of built_rate_limiters) {
         releases.push(() => limiter.dispose());
-        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);
+    }
+    const { bootstrap_ip_rate_limiter, action_ip_rate_limiter, action_account_rate_limiter } = rate_limiters;
     // 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
@@ -213,13 +315,7 @@ const assemble_app_server = async (options, releases) => {
         backend,
         bootstrap_status,
         session_options: options.session_options,
-        login_ip_rate_limiter,
-        signup_ip_rate_limiter,
-        bootstrap_ip_rate_limiter,
-        login_account_rate_limiter,
-        signup_account_rate_limiter,
-        action_ip_rate_limiter,
-        action_account_rate_limiter,
+        ...rate_limiters,
         audit_sse
     };
     const consumer_routes = options.create_route_specs(context);
@@ -280,8 +376,8 @@ const assemble_app_server = async (options, releases) => {
         }
         ws_mount = { endpoints: resolved_ws_endpoints, create_upgrade_websocket };
     }
-    // Surface route (default: enabled)
-    if (options.surface_route !== false) {
+    // Surface route (opt-in)
+    if (options.surface_route) {
         factory_routes.push(create_surface_route_spec(surface_ref));
     }
     const route_specs = [...consumer_routes, ...factory_routes];
@@ -323,62 +419,11 @@ const assemble_app_server = async (options, releases) => {
         ws_endpoints: resolved_ws_endpoints
     });
     // Config-level diagnostics (concatenated after spec-level from generate_app_surface)
-    const config_diagnostics = [];
-    const cookie_opts = options.session_options.cookie_options;
-    if (cookie_opts) {
-        if (cookie_opts.secure === false) {
-            config_diagnostics.push({
-                level: 'warning',
-                category: 'security',
-                message: 'Session cookie secure=false — cookies sent over HTTP'
-            });
-        }
-        if (cookie_opts.sameSite && cookie_opts.sameSite !== session_cookie_options.sameSite) {
-            config_diagnostics.push({
-                level: 'warning',
-                category: 'security',
-                message: `Session cookie sameSite='${cookie_opts.sameSite}' — weakened from default '${session_cookie_options.sameSite}'`
-            });
-        }
-        if (cookie_opts.httpOnly === false) {
-            config_diagnostics.push({
-                level: 'warning',
-                category: 'security',
-                message: 'Session cookie httpOnly=false — cookie accessible to JS'
-            });
-        }
-    }
-    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)`
-                });
-            }
-        }
-    }
+    const config_diagnostics = collect_config_diagnostics({
+        cookie_options: options.session_options.cookie_options,
+        rate_limiter_mode,
+        rate_limiters
+    });
     if (config_diagnostics.length) {
         surface_spec.surface.diagnostics = [...surface_spec.surface.diagnostics, ...config_diagnostics];
     }

package/dist/server/surface_route.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The surface explorer route — `GET /api/surface`, serving the generated
+ * `AppSurface` as JSON.
+ *
+ * Opt-in on `create_app_server` (`surface_route: true`), and admin-only when
+ * mounted: the surface is a map of every route, its auth, and its schemas.
+ *
+ * @module
+ */
+import type { RouteSpec } from '../http/route_spec.js';
+import type { AppSurface } from '../http/surface.js';
+/** Options for the surface explorer route. */
+export interface SurfaceRouteOptions {
+    /** The generated app surface to serve — read per request, so a backfilled ref serves the final surface. */
+    surface: AppSurface;
+}
+/**
+ * Create the admin-only route spec that serves the `AppSurface` as JSON.
+ *
+ * Surface data reveals API structure (routes, auth, schemas), so the route
+ * requires the global admin role. It is also a non-RPC surface: it declares
+ * `required_scope: 'surface:app_surface'`, so a narrowed API token is refused
+ * it whatever its method list says (403 `token_scope_required`, ahead of the
+ * role gate), while a full-scope admin bearer passes. The admin role implies
+ * `actor: 'required'`, so the route takes the `?acting=` selector a
+ * multi-actor admin disambiguates with.
+ *
+ * @param options - the surface to serve
+ * @returns the `GET /api/surface` route spec
+ */
+export declare const create_surface_route_spec: (options: SurfaceRouteOptions) => RouteSpec;
+//# sourceMappingURL=surface_route.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"surface_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/surface_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIrD,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,2GAA2G;IAC3G,OAAO,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,mBAAmB,KAAG,SAmBvE,CAAC"}

package/dist/server/surface_route.js

@@ -0,0 +1,46 @@
+/**
+ * The surface explorer route — `GET /api/surface`, serving the generated
+ * `AppSurface` as JSON.
+ *
+ * Opt-in on `create_app_server` (`surface_route: true`), and admin-only when
+ * mounted: the surface is a map of every route, its auth, and its schemas.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { ActingActor } from '../http/auth_shape.js';
+import { ROLE_ADMIN } from '../auth/role_schema.js';
+/**
+ * Create the admin-only route spec that serves the `AppSurface` as JSON.
+ *
+ * Surface data reveals API structure (routes, auth, schemas), so the route
+ * requires the global admin role. It is also a non-RPC surface: it declares
+ * `required_scope: 'surface:app_surface'`, so a narrowed API token is refused
+ * it whatever its method list says (403 `token_scope_required`, ahead of the
+ * role gate), while a full-scope admin bearer passes. The admin role implies
+ * `actor: 'required'`, so the route takes the `?acting=` selector a
+ * multi-actor admin disambiguates with.
+ *
+ * @param options - the surface to serve
+ * @returns the `GET /api/surface` route spec
+ */
+export const create_surface_route_spec = (options) => ({
+    method: 'GET',
+    path: '/api/surface',
+    auth: {
+        account: 'required',
+        actor: 'required',
+        roles: [ROLE_ADMIN],
+        // rule 3 — the surface map is not an RPC method, so a narrowed token
+        // gets none of it
+        required_scope: 'surface:app_surface'
+    },
+    handler: (c) => c.json(options.surface),
+    description: 'Application surface (routes, middleware, schemas) — admin only',
+    query: z.strictObject({ acting: ActingActor }),
+    input: z.null(),
+    output: z.looseObject({
+        routes: z.array(z.looseObject({})),
+        middleware: z.array(z.looseObject({}))
+    })
+});