@fuzdev/fuz_app 0.127.0 → 0.129.0

package/dist/server/app_server.js

@@ -12,7 +12,7 @@ import { logger } from 'hono/logger';
 import { bodyLimit } from 'hono/body-limit';
 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 { create_audit_log_sse, create_sse_connection_closer, audit_log_event_specs } from '../realtime/sse_auth_guard.js';
 import { BaseServerEnv } from './env.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
@@ -24,9 +24,9 @@ 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, create_auth_middleware_specs } from '../auth/middleware.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';
 import { create_fuz_authorization_handler } from '../auth/request_context.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../http/error_schemas.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.
  *
@@ -80,57 +199,80 @@ export const DEFAULT_MAX_BODY_SIZE = 1024 * 1024;
  * case; consumers can call `require_audit_sse(ctx)` / `require_audit_sse(server)`
  * 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.
+ * Assembly acquires a few things that outlive it — the rate limiters it
+ * builds, the listeners it registers on `deps.audit`, the members it adds to
+ * `deps.connection_closer` — and records a release for each as it goes. When
+ * assembly throws, every release recorded so far runs, last acquired first
+ * (one that throws is logged and the rest still run), and the original error
+ * is rethrown: a failed assembly leaves the backend's emitter and closer as
+ * it found them and no limiter timer running. When `auth_cleanup` is set, the
+ * auth cleanup schedule starts as the last step of assembly — nothing after
+ * it can throw, 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`).
+ * 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) => {
+    const releases = [];
+    try {
+        return await assemble_app_server(options, releases);
+    }
+    catch (error) {
+        run_releases(releases, options.backend.deps.log, 'a failed assembly');
+        throw error;
+    }
+};
+/**
+ * Run `releases` last-first and empty it. Each runs in its own `try`, so one
+ * that throws is logged and the rest still run.
+ */
+const run_releases = (releases, log, during) => {
+    for (const release of releases.splice(0).reverse()) {
+        try {
+            release();
+        }
+        catch (error) {
+            log.error(`create_app_server: a release during ${during} failed:`, error);
+        }
+    }
+};
+/**
+ * The body of `create_app_server`. Every acquisition that outlives assembly
+ * pushes its release onto `releases` as it happens, so a throw at any later
+ * step unwinds exactly what was acquired.
+ */
+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.
-    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);
+    // 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());
+    }
+    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
-    // closer so revocations close its streams.
+    // closer so revocations close its streams. The closer membership is added
+    // here rather than through `create_audit_log_sse`'s option, so its remover
+    // is the server's.
     const audit_sse = options.audit_log_sse
         ? create_audit_log_sse({
             log,
             role: typeof options.audit_log_sse === 'object' ? options.audit_log_sse.role : undefined,
-            connection_closer: deps.connection_closer
+            connection_closer: null
         })
         : null;
     if (audit_sse) {
-        deps.audit.add_listener(audit_sse.on_audit_event);
+        releases.push(deps.connection_closer.add(create_sse_connection_closer(audit_sse.registry)));
+        releases.push(deps.audit.add_listener(audit_sse.on_audit_event));
     }
     // Proxy middleware
     const proxy_spec = create_proxy_middleware_spec({ ...options.proxy, log });
@@ -140,9 +282,13 @@ export const create_app_server = async (options) => {
         session_options: options.session_options,
         daemon_token_state: options.daemon_token_state
     });
-    let middleware_specs = [proxy_spec, ...auth_middleware];
+    const stack_specs = [proxy_spec, ...auth_middleware];
+    let middleware_specs = stack_specs;
     if (options.transform_middleware) {
-        middleware_specs = options.transform_middleware(middleware_specs);
+        // the transform gets copies in a fresh array, so mutating what it was
+        // handed can't rewrite the originals the check matches against
+        middleware_specs = options.transform_middleware(stack_specs.map((spec) => ({ ...spec })));
+        assert_middleware_stack_mounted(stack_specs, middleware_specs);
     }
     // Bootstrap status
     // - undefined / 'disabled': no route mounted; placeholder status.
@@ -169,13 +315,7 @@ export const create_app_server = async (options) => {
         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);
@@ -236,11 +376,32 @@ export const create_app_server = async (options) => {
         }
         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];
+    // WS path checks — pure data, so they run before anything mounts.
+    // `register_ws_endpoint` mounts a `GET path` upgrade route: a duplicate
+    // path, or one a `RouteSpec` already registered as `GET path`, would be
+    // silently shadowed by Hono's last-wins semantics — fail fast instead.
+    if (ws_mount) {
+        const route_spec_get_paths = new Set();
+        for (const r of route_specs) {
+            if (r.method === 'GET')
+                route_spec_get_paths.add(r.path);
+        }
+        const seen_paths = new Set();
+        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}`);
+            }
+            if (route_spec_get_paths.has(endpoint.path)) {
+                throw new Error(`create_app_server: ws_endpoints path collides with a GET RouteSpec: ${endpoint.path}`);
+            }
+            seen_paths.add(endpoint.path);
+        }
+    }
     // Surface + logging
     const surface_middleware = options.post_route_middleware
         ? [...middleware_specs, ...options.post_route_middleware]
@@ -258,62 +419,11 @@ export const create_app_server = async (options) => {
         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];
     }
@@ -389,16 +499,6 @@ export const create_app_server = async (options) => {
         // 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
-        // GET route — fail fast instead.
-        const route_spec_get_paths = new Set();
-        for (const r of route_specs) {
-            if (r.method === 'GET')
-                route_spec_get_paths.add(r.path);
-        }
-        const seen_paths = new Set();
         // Dedupe `auth_guard` wiring by transport reference — two specs
         // sharing one transport instance get a single listener,
         // otherwise revocation events would fire `close_sockets_for_*`
@@ -409,13 +509,6 @@ export const create_app_server = async (options) => {
         // disable, every spec sharing the transport must pass `auth_guard: false`.
         const guarded_transports = new WeakSet();
         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}`);
-            }
-            if (route_spec_get_paths.has(endpoint.path)) {
-                throw new Error(`create_app_server: ws_endpoints path collides with a GET RouteSpec: ${endpoint.path}`);
-            }
-            seen_paths.add(endpoint.path);
             const { transport: endpoint_transport } = register_ws_endpoint({
                 app,
                 path: endpoint.path,
@@ -424,8 +517,8 @@ export const create_app_server = async (options) => {
                 db: deps.db,
                 actions: endpoint.actions,
                 transport: endpoint.transport,
-                // every revocation handler's close reaches this transport
-                connection_closer: deps.connection_closer,
+                // added below instead, so the remover is the server's
+                connection_closer: null,
                 max_connections_per_account: endpoint.max_connections_per_account,
                 heartbeat: endpoint.heartbeat,
                 artificial_delay: endpoint.artificial_delay,
@@ -438,13 +531,15 @@ export const create_app_server = async (options) => {
                 action_account_rate_limiter
             });
             mounted_ws_endpoints[endpoint.path] = endpoint_transport;
+            // every revocation handler's close reaches this transport
+            releases.push(deps.connection_closer.add(endpoint_transport));
             if (endpoint.auth_guard !== false && !guarded_transports.has(endpoint_transport)) {
                 guarded_transports.add(endpoint_transport);
-                deps.audit.add_listener(create_ws_auth_guard(endpoint_transport, log));
+                releases.push(deps.audit.add_listener(create_ws_auth_guard(endpoint_transport, log)));
             }
             if (endpoint.extra_audit_handlers?.length) {
                 for (const handler of endpoint.extra_audit_handlers) {
-                    deps.audit.add_listener(handler);
+                    releases.push(deps.audit.add_listener(handler));
                 }
             }
         }
@@ -461,8 +556,10 @@ export const create_app_server = async (options) => {
         }
     }
     // Auth cleanup — opt-in, and last: nothing after it can throw, so a failed
-    // assembly never leaves a schedule running. Its closes go through
-    // `deps.connection_closer`, which the mounts above have filled.
+    // assembly never leaves a schedule running. Its own throw (an invalid
+    // `interval_ms`) comes before any pass starts, and unwinds `releases` like
+    // any other. Its closes go through `deps.connection_closer`, which the
+    // mounts above have filled.
     const auth_cleanup = options.auth_cleanup
         ? start_auth_cleanup(deps, options.auth_cleanup === true ? undefined : options.auth_cleanup)
         : null;
@@ -480,8 +577,9 @@ export const create_app_server = async (options) => {
         catch (error) {
             log.error('create_app_server: closing live connections on shutdown failed:', error);
         }
-        for (const limiter of built_rate_limiters)
-            limiter.dispose();
+        // then what assembly acquired — the audit listeners and closer members
+        // this server added, and the limiters it built
+        run_releases(releases, log, 'shutdown');
         await backend.close();
     };
     return {

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({}))
+    })
+});