@fuzdev/fuz_app 0.1.0

package/dist/testing/schema_generators.d.ts

@@ -0,0 +1,33 @@
+import './assert_dev_env.js';
+/**
+ * Schema-driven value generation helpers for testing.
+ *
+ * Walks Zod schemas to generate valid values for route params, request bodies,
+ * and URL paths. Used by adversarial input, adversarial 404, and round-trip
+ * validation test suites.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { type ZodFieldInfo } from '@fuzdev/fuz_util/zod.js';
+/**
+ * Detect format constraints on a field by converting to JSON Schema.
+ * Returns format string (e.g. 'uuid', 'email') or null.
+ */
+export declare const detect_format: (field_schema: z.ZodType) => string | null;
+/** Generate a valid-ish value for a field based on its base type. */
+export declare const generate_valid_value: (field: ZodFieldInfo, field_schema: z.ZodType) => unknown;
+/**
+ * Resolve a route path with valid-ish param values so params validation passes.
+ * Used when testing input on routes that also have params.
+ */
+export declare const resolve_valid_path: (path: string, params_schema?: z.ZodObject) => string;
+/**
+ * Generate a valid request body for a route's input schema.
+ *
+ * Returns `undefined` for null schemas or schemas that can't be unwrapped to objects.
+ * Throws if the generated body fails validation — catches broken generation logic
+ * early with a descriptive error instead of a confusing 400 in downstream tests.
+ */
+export declare const generate_valid_body: (input_schema: z.ZodType) => Record<string, unknown> | undefined;
+//# sourceMappingURL=schema_generators.d.ts.map

package/dist/testing/schema_generators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_generators.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/schema_generators.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAKN,KAAK,YAAY,EACjB,MAAM,yBAAyB,CAAC;AAIjC;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,cAAc,CAAC,CAAC,OAAO,KAAG,MAAM,GAAG,IAShE,CAAC;AAiBF,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,GAAI,OAAO,YAAY,EAAE,cAAc,CAAC,CAAC,OAAO,KAAG,OAqCnF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,gBAAgB,CAAC,CAAC,SAAS,KAAG,MAa9E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC/B,cAAc,CAAC,CAAC,OAAO,KACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAkB5B,CAAC"}

package/dist/testing/schema_generators.js

@@ -0,0 +1,137 @@
+import './assert_dev_env.js';
+/**
+ * Schema-driven value generation helpers for testing.
+ *
+ * Walks Zod schemas to generate valid values for route params, request bodies,
+ * and URL paths. Used by adversarial input, adversarial 404, and round-trip
+ * validation test suites.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { zod_unwrap_def, zod_get_base_type, zod_unwrap_to_object, zod_extract_fields, } from '@fuzdev/fuz_util/zod.js';
+import { is_null_schema } from '../http/schema_helpers.js';
+/**
+ * Detect format constraints on a field by converting to JSON Schema.
+ * Returns format string (e.g. 'uuid', 'email') or null.
+ */
+export const detect_format = (field_schema) => {
+    try {
+        const json = z.toJSONSchema(field_schema);
+        if (typeof json.format === 'string')
+            return json.format;
+        if (typeof json.pattern === 'string')
+            return 'pattern';
+    }
+    catch {
+        // schema can't be converted, no format
+    }
+    return null;
+};
+/** Generate a string that satisfies minLength/maxLength constraints via JSON Schema. */
+const generate_valid_string = (field_schema) => {
+    let min_length = 0;
+    let max_length = Infinity;
+    try {
+        const json = z.toJSONSchema(field_schema);
+        if (typeof json.minLength === 'number')
+            min_length = json.minLength;
+        if (typeof json.maxLength === 'number')
+            max_length = json.maxLength;
+    }
+    catch {
+        // no constraints
+    }
+    const target = Math.max(min_length, Math.min(10, max_length));
+    return 'x'.repeat(target) || 'test_value';
+};
+/** Generate a valid-ish value for a field based on its base type. */
+export const generate_valid_value = (field, field_schema) => {
+    const format = detect_format(field_schema);
+    switch (field.base_type) {
+        case 'uuid':
+            return '00000000-0000-0000-0000-000000000000';
+        case 'email':
+            return 'test@example.com';
+        case 'string':
+            if (format === 'uuid')
+                return '00000000-0000-0000-0000-000000000000';
+            if (format === 'email')
+                return 'test@example.com';
+            return generate_valid_string(field_schema);
+        case 'number':
+        case 'int':
+            return 1;
+        case 'boolean':
+            return true;
+        case 'array':
+            return [];
+        case 'object':
+            return {};
+        case 'null':
+            return null;
+        case 'enum': {
+            const enum_def = zod_unwrap_def(field_schema);
+            if ('entries' in enum_def) {
+                const entries = enum_def.entries;
+                // Zod 4 enum entries is an object {key: value}, not an array
+                if (entries && typeof entries === 'object') {
+                    const values = Object.values(entries);
+                    if (values.length > 0)
+                        return values[0];
+                }
+            }
+            return 'test';
+        }
+        default:
+            return 'test_value';
+    }
+};
+/**
+ * Resolve a route path with valid-ish param values so params validation passes.
+ * Used when testing input on routes that also have params.
+ */
+export const resolve_valid_path = (path, params_schema) => {
+    if (!params_schema) {
+        return path.replace(/:(\w+)/g, 'test_$1');
+    }
+    return path.replace(/:(\w+)/g, (_match, name) => {
+        const field_schema = params_schema.shape[name];
+        if (!field_schema)
+            return `test_${name}`;
+        const base_type = zod_get_base_type(field_schema);
+        if (base_type === 'uuid')
+            return '00000000-0000-0000-0000-000000000000';
+        const format = detect_format(field_schema);
+        if (format === 'uuid')
+            return '00000000-0000-0000-0000-000000000000';
+        return `test_${name}`;
+    });
+};
+/**
+ * Generate a valid request body for a route's input schema.
+ *
+ * Returns `undefined` for null schemas or schemas that can't be unwrapped to objects.
+ * Throws if the generated body fails validation — catches broken generation logic
+ * early with a descriptive error instead of a confusing 400 in downstream tests.
+ */
+export const generate_valid_body = (input_schema) => {
+    if (is_null_schema(input_schema))
+        return undefined;
+    const object_schema = zod_unwrap_to_object(input_schema);
+    if (!object_schema)
+        return undefined;
+    const fields = zod_extract_fields(object_schema);
+    const body = {};
+    for (const field of fields) {
+        if (!field.required && !field.has_default)
+            continue;
+        body[field.name] = generate_valid_value(field, object_schema.shape[field.name]);
+    }
+    const result = input_schema.safeParse(body);
+    if (!result.success) {
+        throw new Error(`generate_valid_body: generated body fails validation — ` +
+            `fix generate_valid_value for: ${result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', ')}`);
+    }
+    return body;
+};

package/dist/testing/standard.d.ts

@@ -0,0 +1,49 @@
+import './assert_dev_env.js';
+/**
+ * Combined standard test suite helper.
+ *
+ * Convenience wrapper that runs both `describe_standard_integration_tests`
+ * and `describe_standard_admin_integration_tests` in a single call.
+ * Existing per-suite calls keep working — this is purely additive.
+ *
+ * @module
+ */
+import type { SessionOptions } from '../auth/session_cookie.js';
+import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import type { RoleSchemaResult } from '../auth/role_schema.js';
+import type { DbFactory } from './db.js';
+/**
+ * Configuration for `describe_standard_tests`.
+ */
+export interface StandardTestOptions {
+    /** Session config for cookie-based auth. */
+    session_options: SessionOptions<string>;
+    /** Route spec factory — same one used in production. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** Optional overrides for `AppServerOptions`. */
+    app_options?: Partial<Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>>;
+    /**
+     * Database factories to run tests against. Default: pglite only.
+     */
+    db_factories?: Array<DbFactory>;
+    /**
+     * Role schema result from `create_role_schema()`.
+     * When provided, admin integration tests are included.
+     */
+    roles?: RoleSchemaResult;
+    /**
+     * Path prefix where admin routes are mounted.
+     * Default `'/api/admin'`.
+     */
+    admin_prefix?: string;
+}
+/**
+ * Run both standard integration and admin integration test suites.
+ *
+ * Admin tests are only included when `roles` is provided.
+ *
+ * @param options - session config, route factory, and optional role schema
+ */
+export declare const describe_standard_tests: (options: StandardTestOptions) => void;
+//# sourceMappingURL=standard.d.ts.map

package/dist/testing/standard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/standard.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF;;OAEG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,mBAAmB,KAAG,IAKtE,CAAC"}

package/dist/testing/standard.js

@@ -0,0 +1,16 @@
+import './assert_dev_env.js';
+import { describe_standard_integration_tests } from './integration.js';
+import { describe_standard_admin_integration_tests } from './admin_integration.js';
+/**
+ * Run both standard integration and admin integration test suites.
+ *
+ * Admin tests are only included when `roles` is provided.
+ *
+ * @param options - session config, route factory, and optional role schema
+ */
+export const describe_standard_tests = (options) => {
+    describe_standard_integration_tests(options);
+    if (options.roles) {
+        describe_standard_admin_integration_tests({ ...options, roles: options.roles });
+    }
+};

package/dist/testing/stubs.d.ts

@@ -0,0 +1,96 @@
+import './assert_dev_env.js';
+import type { z } from 'zod';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import type { MiddlewareSpec } from '../http/middleware_spec.js';
+import type { AppDeps } from '../auth/deps.js';
+import type { AppServerContext } from '../server/app_server.js';
+import { Db } from '../db/db.js';
+import { type RouteSpec } from '../http/route_spec.js';
+import { type AppSurfaceSpec } from '../http/surface.js';
+import type { SseEventSpec } from '../realtime/sse.js';
+/**
+ * Create a Proxy that throws descriptive errors on any property access or method call.
+ *
+ * Use for deps that should never be reached during a test. If a test accidentally
+ * calls through to a throwing stub, the error message identifies exactly which stub
+ * was hit, catching test bugs that would silently pass with `{} as any`.
+ *
+ * @param label - descriptive name for error messages (e.g. `'keyring'`, `'db'`)
+ */
+export declare const create_throwing_stub: <T = any>(label: string) => T;
+/**
+ * Create a Proxy where every method access returns a no-op async function.
+ *
+ * Use for deps that may be reached during "correct auth passes guard" tests
+ * but whose return values don't matter. Unlike the explicit method listing,
+ * this auto-updates when interfaces change.
+ *
+ * @param label - descriptive name for debug purposes
+ * @param overrides - explicit properties to set (e.g. `{db: stub_db}`)
+ */
+export declare const create_noop_stub: <T = any>(_label: string, overrides?: Record<string, unknown>) => T;
+/** Throwing stub — use for deps that should never be reached. */
+export declare const stub: any;
+/**
+ * Create a stub `Db` for handler tests that use `apply_route_specs` with declarative transactions.
+ *
+ * Returns a real `Db` instance with:
+ * - `query` returns empty rows (safety net for unmocked query functions)
+ * - `query_one` returns undefined
+ * - `transaction(fn)` calls `fn(db)` synchronously (no real transaction)
+ */
+export declare const create_stub_db: () => Db;
+/** Stub handler that returns a 200 response. */
+export declare const stub_handler: () => Response;
+/** Stub middleware that passes through. */
+export declare const stub_mw: (_c: any, next: any) => Promise<void>;
+/** Stub `AppDeps` for auth surface tests — throws on any method access. */
+export declare const stub_app_deps: AppDeps;
+/**
+ * Create no-op app deps for auth surface testing.
+ *
+ * @returns an `AppDeps`-shaped object with no-op deps
+ */
+export declare const create_stub_app_deps: () => AppDeps;
+/** Create the API middleware stub array matching `create_auth_middleware_specs` output. */
+export declare const create_stub_api_middleware: (options?: {
+    /** Include the daemon_token middleware layer. */
+    include_daemon_token?: boolean;
+}) => Array<MiddlewareSpec>;
+/**
+ * Create a stub `AppServerContext` for attack surface testing.
+ *
+ * Provides sensible defaults for all fields. Pass `session_options` since
+ * it varies per consumer; other fields use stubs/nulls.
+ *
+ * @param session_options - consumer's session config (required — varies per app)
+ */
+export declare const create_stub_app_server_context: (session_options: SessionOptions<string>) => AppServerContext;
+/** Options for `create_test_app_surface_spec`. */
+export interface CreateTestAppSurfaceSpecOptions {
+    /** Consumer's session config (required — varies per app). */
+    session_options: SessionOptions<string>;
+    /** Consumer's route factory — receives the same `AppServerContext` as production. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** Env schema for surface generation (default: `BaseServerEnv`). */
+    env_schema?: z.ZodObject;
+    /** SSE event specs for surface generation. */
+    event_specs?: Array<SseEventSpec>;
+    /** Transform middleware array (e.g., tx's `extend_middleware_for_tx_binary`). */
+    transform_middleware?: (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>;
+    /** Bootstrap route prefix (default: `'/api/account'`). */
+    bootstrap_route_prefix?: string;
+}
+/**
+ * Create an `AppSurfaceSpec` for attack surface testing.
+ *
+ * Mirrors `create_app_server`'s route assembly: consumer routes +
+ * factory-managed bootstrap routes + surface generation. If
+ * `create_app_server` changes how it wires routes, update this helper
+ * to stay in sync (single source of truth for all consumers).
+ *
+ * @param options - surface spec options
+ * @returns the surface spec for snapshot and adversarial testing
+ */
+export declare const create_test_app_surface_spec: (options: CreateTestAppSurfaceSpecOptions) => AppSurfaceSpec;
+//# sourceMappingURL=stubs.d.ts.map

package/dist/testing/stubs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/stubs.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAa7B,OAAO,KAAK,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAE3B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAE/D,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAC/B,OAAO,EAAqB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EAA0B,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAChF,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAKrD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,GAAG,GAAG,EAAE,OAAO,MAAM,KAAG,CAqBtD,CAAC;AAET;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,GAAG,GAAG,EAAE,QAAQ,MAAM,EAAE,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,CAOxF,CAAC;AAET,iEAAiE;AACjE,eAAO,MAAM,IAAI,EAAE,GAAkC,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAAO,EAI/B,CAAC;AAEJ,gDAAgD;AAChD,eAAO,MAAM,YAAY,QAAO,QAAgC,CAAC;AAEjE,2CAA2C;AAC3C,eAAO,MAAM,OAAO,GAAU,IAAI,GAAG,EAAE,MAAM,GAAG,KAAG,OAAO,CAAC,IAAI,CAAW,CAAC;AAI3E,2EAA2E;AAC3E,eAAO,MAAM,aAAa,EAAE,OAS3B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAO,OAStC,CAAC;AAEH,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,GAAI,UAAU;IACpD,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B,KAAG,KAAK,CAAC,cAAc,CAqBvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAC1C,iBAAiB,cAAc,CAAC,MAAM,CAAC,KACrC,gBAmBF,CAAC;AAEF,kDAAkD;AAClD,MAAM,WAAW,+BAA+B;IAC/C,6DAA6D;IAC7D,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,qFAAqF;IACrF,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,oEAAoE;IACpE,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;IACzB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAClC,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,KAAK,CAAC,cAAc,CAAC,CAAC;IAC/E,0DAA0D;IAC1D,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,cAwBF,CAAC"}

package/dist/testing/stubs.js

@@ -0,0 +1,192 @@
+import './assert_dev_env.js';
+/**
+ * Stub factories for auth surface testing.
+ *
+ * Provides throwing stubs (catch unexpected access), no-op stubs (allow access
+ * without side effects), and pre-built bundles for `AppDeps`.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { ApiError, RateLimitError } from '../http/error_schemas.js';
+import { Db } from '../db/db.js';
+import { prefix_route_specs } from '../http/route_spec.js';
+import { create_bootstrap_route_specs } from '../auth/bootstrap_routes.js';
+import { create_app_surface_spec } from '../http/surface.js';
+import { BaseServerEnv } from '../server/env.js';
+/* eslint-disable @typescript-eslint/require-await */
+/**
+ * Create a Proxy that throws descriptive errors on any property access or method call.
+ *
+ * Use for deps that should never be reached during a test. If a test accidentally
+ * calls through to a throwing stub, the error message identifies exactly which stub
+ * was hit, catching test bugs that would silently pass with `{} as any`.
+ *
+ * @param label - descriptive name for error messages (e.g. `'keyring'`, `'db'`)
+ */
+export const create_throwing_stub = (label) => new Proxy({}, {
+    get: (_target, prop) => {
+        // allow JS internals that runtime/test frameworks probe
+        if (typeof prop === 'symbol' ||
+            prop === 'then' ||
+            prop === 'constructor' ||
+            prop === '$$typeof')
+            return undefined;
+        // Return a sentinel for JSON serialization so accidental serialization
+        // is visible in output (e.g. "[throwing_stub:keyring]") rather than
+        // silently producing "{}". Does not throw — avoids crashing vitest
+        // assertion diffs and console.log output that contain stubs.
+        if (prop === 'toJSON')
+            return () => `[throwing_stub:${label}]`;
+        throw new Error(`Throwing stub '${label}' — unexpected access to '${prop}'. ` +
+            `This dep should not be reached in this test.`);
+    },
+});
+/**
+ * Create a Proxy where every method access returns a no-op async function.
+ *
+ * Use for deps that may be reached during "correct auth passes guard" tests
+ * but whose return values don't matter. Unlike the explicit method listing,
+ * this auto-updates when interfaces change.
+ *
+ * @param label - descriptive name for debug purposes
+ * @param overrides - explicit properties to set (e.g. `{db: stub_db}`)
+ */
+export const create_noop_stub = (_label, overrides) => new Proxy({ ...(overrides ?? {}) }, {
+    get: (target, prop) => {
+        if (prop in target)
+            return target[prop];
+        if (typeof prop === 'symbol' || prop === 'then' || prop === 'toJSON')
+            return undefined;
+        return async () => undefined;
+    },
+});
+/** Throwing stub — use for deps that should never be reached. */
+export const stub = create_throwing_stub('stub');
+/**
+ * Create a stub `Db` for handler tests that use `apply_route_specs` with declarative transactions.
+ *
+ * Returns a real `Db` instance with:
+ * - `query` returns empty rows (safety net for unmocked query functions)
+ * - `query_one` returns undefined
+ * - `transaction(fn)` calls `fn(db)` synchronously (no real transaction)
+ */
+export const create_stub_db = () => new Db({
+    client: { query: async () => ({ rows: [] }) },
+    transaction: async (fn) => fn(create_stub_db()),
+});
+/** Stub handler that returns a 200 response. */
+export const stub_handler = () => new Response('stub');
+/** Stub middleware that passes through. */
+export const stub_mw = async (_c, next) => next();
+const stub_db = create_noop_stub('stub_db');
+/** Stub `AppDeps` for auth surface tests — throws on any method access. */
+export const stub_app_deps = {
+    stat: create_throwing_stub('stat'),
+    read_file: create_throwing_stub('read_file'),
+    delete_file: create_throwing_stub('delete_file'),
+    keyring: create_throwing_stub('keyring'),
+    password: create_throwing_stub('password'),
+    db: create_throwing_stub('db'),
+    log: create_throwing_stub('log'),
+    on_audit_event: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+};
+/**
+ * Create no-op app deps for auth surface testing.
+ *
+ * @returns an `AppDeps`-shaped object with no-op deps
+ */
+export const create_stub_app_deps = () => ({
+    stat: async () => null,
+    read_file: async () => '',
+    delete_file: async (_path) => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    keyring: create_noop_stub('keyring'),
+    password: create_noop_stub('password'),
+    db: stub_db,
+    log: new Logger('test', { level: 'off' }),
+    on_audit_event: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+});
+/** Create the API middleware stub array matching `create_auth_middleware_specs` output. */
+export const create_stub_api_middleware = (options) => {
+    const specs = [
+        { name: 'origin', path: '/api/*', handler: stub_mw, errors: { 403: ApiError } },
+        { name: 'session', path: '/api/*', handler: stub_mw },
+        { name: 'request_context', path: '/api/*', handler: stub_mw },
+        {
+            name: 'bearer_auth',
+            path: '/api/*',
+            handler: stub_mw,
+            errors: { 401: ApiError, 403: ApiError, 429: RateLimitError },
+        },
+    ];
+    if (options?.include_daemon_token) {
+        specs.push({
+            name: 'daemon_token',
+            path: '/api/*',
+            handler: stub_mw,
+            errors: { 401: ApiError, 500: ApiError, 503: ApiError },
+        });
+    }
+    return specs;
+};
+/**
+ * Create a stub `AppServerContext` for attack surface testing.
+ *
+ * Provides sensible defaults for all fields. Pass `session_options` since
+ * it varies per consumer; other fields use stubs/nulls.
+ *
+ * @param session_options - consumer's session config (required — varies per app)
+ */
+export const create_stub_app_server_context = (session_options) => {
+    const deps = create_stub_app_deps();
+    return {
+        deps,
+        backend: {
+            deps,
+            db_type: 'pglite-memory',
+            db_name: 'test',
+            migration_results: [],
+            close: async () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+        },
+        bootstrap_status: { available: false, token_path: null },
+        session_options,
+        ip_rate_limiter: null,
+        login_account_rate_limiter: null,
+        signup_account_rate_limiter: null,
+        app_settings: { open_signup: false, updated_at: null, updated_by: null },
+        audit_sse: null,
+    };
+};
+/**
+ * Create an `AppSurfaceSpec` for attack surface testing.
+ *
+ * Mirrors `create_app_server`'s route assembly: consumer routes +
+ * factory-managed bootstrap routes + surface generation. If
+ * `create_app_server` changes how it wires routes, update this helper
+ * to stay in sync (single source of truth for all consumers).
+ *
+ * @param options - surface spec options
+ * @returns the surface spec for snapshot and adversarial testing
+ */
+export const create_test_app_surface_spec = (options) => {
+    const ctx = create_stub_app_server_context(options.session_options);
+    const consumer_routes = options.create_route_specs(ctx);
+    // Mirror create_app_server's factory-managed route assembly
+    const bootstrap_routes = create_bootstrap_route_specs(ctx.deps, {
+        session_options: options.session_options,
+        bootstrap_status: { available: false, token_path: null },
+        ip_rate_limiter: null,
+    });
+    const prefix = options.bootstrap_route_prefix ?? '/api/account';
+    const route_specs = [...consumer_routes, ...prefix_route_specs(prefix, bootstrap_routes)];
+    let middleware_specs = create_stub_api_middleware();
+    if (options.transform_middleware) {
+        middleware_specs = options.transform_middleware(middleware_specs);
+    }
+    return create_app_surface_spec({
+        middleware_specs,
+        route_specs,
+        env_schema: options.env_schema ?? BaseServerEnv,
+        event_specs: options.event_specs,
+    });
+};