@fuzdev/fuz_app 0.1.0

package/dist/testing/middleware.js

@@ -0,0 +1,210 @@
+import './assert_dev_env.js';
+/**
+ * Table-driven middleware test helpers.
+ *
+ * Provides mock builders for bearer auth middleware dependencies,
+ * a generic test runner that iterates case tables, and a reusable
+ * middleware stack factory for integration testing.
+ *
+ * @module
+ */
+import { vi, test, assert, describe } from 'vitest';
+import { Hono } from 'hono';
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { create_bearer_auth_middleware } from '../auth/bearer_auth.js';
+import { query_validate_api_token } from '../auth/api_token_queries.js';
+import { query_account_by_id, query_actor_by_account } from '../auth/account_queries.js';
+import { query_permit_find_active_for_actor } from '../auth/permit_queries.js';
+import { create_proxy_middleware, get_client_ip } from '../http/proxy.js';
+import { verify_request_source, parse_allowed_origins } from '../http/origin.js';
+import { REQUEST_CONTEXT_KEY } from '../auth/request_context.js';
+import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { ApiError } from '../http/error_schemas.js';
+// Mock the query modules so test cases can control return values.
+// vi.mock() is hoisted by vitest, so these run before any imports resolve.
+vi.mock('../auth/api_token_queries.js', () => ({
+    query_validate_api_token: vi.fn(),
+}));
+vi.mock('../auth/account_queries.js', () => ({
+    query_account_by_id: vi.fn(),
+    query_actor_by_account: vi.fn(),
+}));
+vi.mock('../auth/permit_queries.js', () => ({
+    query_permit_find_active_for_actor: vi.fn(),
+}));
+/** Stub `QueryDeps` for bearer auth tests (no real DB needed). */
+const STUB_DEPS = { db: {} };
+/**
+ * Create mock dependencies for `create_bearer_auth_middleware`, configured per test case.
+ *
+ * Configures the module-level mocks for `query_validate_api_token`,
+ * `query_account_by_id`, `query_actor_by_account`, and `query_permit_find_active_for_actor`
+ * so each test case controls return values independently.
+ *
+ * @param tc - the test config providing mock return values
+ * @returns mocks bundle with spy references
+ */
+export const create_bearer_auth_mocks = (tc) => {
+    const mock_validate = vi.mocked(query_validate_api_token);
+    const mock_find_by_id = vi.mocked(query_account_by_id);
+    const mock_find_by_account = vi.mocked(query_actor_by_account);
+    const mock_find_active_for_actor = vi.mocked(query_permit_find_active_for_actor);
+    mock_validate
+        .mockReset()
+        .mockImplementation(() => Promise.resolve(tc.mock_validate_result));
+    mock_find_by_id
+        .mockReset()
+        .mockImplementation(() => Promise.resolve(tc.mock_find_by_id_result));
+    mock_find_by_account
+        .mockReset()
+        .mockImplementation(() => Promise.resolve(tc.mock_find_by_account_result));
+    mock_find_active_for_actor
+        .mockReset()
+        .mockImplementation(() => Promise.resolve(tc.mock_permits_result ?? []));
+    return { mock_validate, mock_find_by_id, mock_find_by_account, mock_find_active_for_actor };
+};
+/** Default client IP set by the proxy stub in test apps. */
+export const TEST_CLIENT_IP = '127.0.0.1';
+/**
+ * Create a Hono app wired with `create_bearer_auth_middleware` using mocked deps.
+ *
+ * The route handler at `/api/test` returns the resolved context in the response body,
+ * enabling assertions on `REQUEST_CONTEXT_KEY` and `CREDENTIAL_TYPE_KEY`.
+ *
+ * @param tc - the test config providing mock behavior
+ * @param ip_rate_limiter - optional rate limiter (null to disable)
+ * @returns the app and mocks bundle
+ */
+export const create_bearer_auth_test_app = (tc, ip_rate_limiter = null) => {
+    const mocks = create_bearer_auth_mocks(tc);
+    const bearer_middleware = create_bearer_auth_middleware(STUB_DEPS, ip_rate_limiter, new Logger('test', { level: 'off' }));
+    const app = new Hono();
+    // inject pre-existing request context if the test case specifies one
+    if (tc.pre_context) {
+        app.use('*', async (c, next) => {
+            c.set(REQUEST_CONTEXT_KEY, tc.pre_context);
+            c.set(CREDENTIAL_TYPE_KEY, 'session');
+            await next();
+        });
+    }
+    // proxy middleware stub — sets a known client_ip
+    app.use('*', async (c, next) => {
+        c.set('client_ip', TEST_CLIENT_IP);
+        await next();
+    });
+    app.use('/api/*', bearer_middleware);
+    // route handler echoes full context state for assertions
+    app.get('/api/test', (c) => {
+        const ctx = c.get(REQUEST_CONTEXT_KEY);
+        const cred = c.get(CREDENTIAL_TYPE_KEY);
+        return c.json({
+            ok: true,
+            has_context: ctx != null,
+            credential_type: cred ?? null,
+            account_id: ctx?.account.id ?? null,
+            actor_id: ctx?.actor.id ?? null,
+            permit_count: ctx?.permits.length ?? 0,
+        });
+    });
+    return { app, mocks };
+};
+// --- Table-driven test runner ---
+/**
+ * Run a table of bearer auth middleware test cases.
+ *
+ * Generates one `test()` per case inside a `describe()` block.
+ *
+ * @param suite_name - the describe block name
+ * @param cases - the test case table
+ * @param ip_rate_limiter - optional rate limiter shared across cases
+ */
+export const describe_bearer_auth_cases = (suite_name, cases, ip_rate_limiter = null) => {
+    describe(suite_name, () => {
+        for (const tc of cases) {
+            test(tc.name, async () => {
+                const { app, mocks } = create_bearer_auth_test_app(tc, ip_rate_limiter);
+                const res = await app.request('/api/test', {
+                    method: 'GET',
+                    headers: tc.headers,
+                });
+                const body = await res.json();
+                if (tc.expected_status === 'next') {
+                    assert.strictEqual(res.status, 200, `expected next() but got ${res.status}`);
+                }
+                else {
+                    assert.strictEqual(res.status, tc.expected_status);
+                    if (tc.expected_error) {
+                        assert.strictEqual(body.error, tc.expected_error);
+                        const error_schema = tc.expected_error_schema ?? ApiError;
+                        error_schema.parse(body);
+                    }
+                }
+                if (tc.validate_expectation === 'not_called') {
+                    assert.strictEqual(mocks.mock_validate.mock.calls.length, 0, 'validate should not have been called');
+                }
+                else {
+                    assert.ok(mocks.mock_validate.mock.calls.length > 0, 'validate should have been called');
+                }
+                if (tc.assert_context_set) {
+                    assert.strictEqual(body.has_context, true, 'REQUEST_CONTEXT_KEY should be set');
+                    assert.strictEqual(body.credential_type, 'api_token', 'CREDENTIAL_TYPE_KEY should be api_token');
+                }
+                if (tc.assert_context_preserved) {
+                    assert.strictEqual(body.has_context, true, 'original context should be preserved');
+                    assert.strictEqual(body.credential_type, 'session', 'credential type should remain session');
+                }
+                if (tc.assert_mocks) {
+                    tc.assert_mocks(mocks);
+                }
+            });
+        }
+    });
+};
+// --- Middleware stack test factory ---
+/** Path used by the echo route in `create_test_middleware_stack_app`. */
+export const TEST_MIDDLEWARE_PATH = '/api/test';
+/**
+ * Create a Hono app with real proxy + origin + bearer middleware for integration testing.
+ *
+ * All DB queries return undefined (no real database needed).
+ * The echo route at `TEST_MIDDLEWARE_PATH` returns `{ok, client_ip, has_context}`.
+ *
+ * @param options - middleware stack configuration
+ * @returns the app and mock spies (reconfigure via `mockImplementation` for valid-token paths)
+ */
+export const create_test_middleware_stack_app = (options) => {
+    const trusted_proxies = options?.trusted_proxies ?? ['10.0.0.1'];
+    const allowed_origins_str = options?.allowed_origins ?? 'https://app.example.com';
+    const mock_validate = vi.mocked(query_validate_api_token);
+    const mock_find_by_id = vi.mocked(query_account_by_id);
+    const mock_find_by_account = vi.mocked(query_actor_by_account);
+    const mock_find_active_for_actor = vi.mocked(query_permit_find_active_for_actor);
+    mock_validate.mockReset().mockImplementation(() => Promise.resolve(undefined));
+    mock_find_by_id.mockReset().mockImplementation(() => Promise.resolve(undefined));
+    mock_find_by_account.mockReset().mockImplementation(() => Promise.resolve(undefined));
+    mock_find_active_for_actor.mockReset().mockImplementation(() => Promise.resolve([]));
+    const get_connection_ip = typeof options?.connection_ip === 'function'
+        ? options.connection_ip
+        : () => options?.connection_ip ?? trusted_proxies[0];
+    const proxy_mw = create_proxy_middleware({
+        trusted_proxies,
+        get_connection_ip: get_connection_ip,
+    });
+    const allowed_patterns = parse_allowed_origins(allowed_origins_str);
+    const origin_mw = verify_request_source(allowed_patterns);
+    const bearer_mw = create_bearer_auth_middleware(STUB_DEPS, options?.ip_rate_limiter ?? null, new Logger('test', { level: 'off' }));
+    const app = new Hono();
+    app.use('*', proxy_mw);
+    app.use('/api/*', origin_mw);
+    app.use('/api/*', bearer_mw);
+    // echo route for assertions
+    app.get(TEST_MIDDLEWARE_PATH, (c) => {
+        const ctx = c.get(REQUEST_CONTEXT_KEY);
+        return c.json({
+            ok: true,
+            client_ip: get_client_ip(c),
+            has_context: ctx != null,
+        });
+    });
+    return { app, mock_validate, mock_find_by_id, mock_find_by_account, mock_find_active_for_actor };
+};

package/dist/testing/rate_limiting.d.ts

@@ -0,0 +1,43 @@
+import './assert_dev_env.js';
+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 DbFactory } from './db.js';
+/**
+ * Configuration for `describe_rate_limiting_tests`.
+ */
+export interface RateLimitingTestOptions {
+    /** 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>;
+    /**
+     * Maximum attempts before rate limiting kicks in.
+     * Default: `2` (tight limit for fast tests).
+     */
+    max_attempts?: number;
+}
+/**
+ * Standard rate limiting integration test suite.
+ *
+ * Creates 3 test groups:
+ * 1. IP rate limiting on login — fires `max_attempts + 1` login requests,
+ *    verifies the last returns 429 with a valid `RateLimitError` body.
+ * 2. Per-account rate limiting on login — fires `max_attempts + 1` login
+ *    requests with the same username, verifies the last returns 429.
+ * 3. Bearer auth IP rate limiting — fires `max_attempts + 1` bearer requests
+ *    with an invalid token, verifies the last returns 429.
+ *
+ * Each test group asserts that required routes exist, failing with a descriptive
+ * message if the consumer's route specs are misconfigured.
+ *
+ * @param options - session config and route factory
+ */
+export declare const describe_rate_limiting_tests: (options: RateLimitingTestOptions) => void;
+//# sourceMappingURL=rate_limiting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rate_limiting.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/rate_limiting.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAiB7B,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;AAKrD,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAKjB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,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,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,uBAAuB,KAAG,IA+N/E,CAAC"}

package/dist/testing/rate_limiting.js

@@ -0,0 +1,216 @@
+import './assert_dev_env.js';
+/**
+ * Rate limiting integration test suite.
+ *
+ * Verifies that sensitive routes (login, bootstrap, token creation) enforce
+ * rate limits when rate limiters are enabled. Tests create a tight rate limiter
+ * (2 attempts / 1 minute) and fire requests until 429 is returned.
+ *
+ * Consumers call `describe_rate_limiting_tests` with their route factory and
+ * session config — rate limit enforcement tests come for free.
+ *
+ * @module
+ */
+import { describe, test, assert } from 'vitest';
+import { RateLimiter } from '../rate_limiter.js';
+import { RateLimitError } from '../http/error_schemas.js';
+import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
+import { create_test_app } from './app_server.js';
+import { create_pglite_factory, create_describe_db, AUTH_INTEGRATION_TRUNCATE_TABLES, } from './db.js';
+import { find_auth_route, assert_rate_limit_retry_after_header } from './integration_helpers.js';
+import { run_migrations } from '../db/migrate.js';
+/**
+ * Standard rate limiting integration test suite.
+ *
+ * Creates 3 test groups:
+ * 1. IP rate limiting on login — fires `max_attempts + 1` login requests,
+ *    verifies the last returns 429 with a valid `RateLimitError` body.
+ * 2. Per-account rate limiting on login — fires `max_attempts + 1` login
+ *    requests with the same username, verifies the last returns 429.
+ * 3. Bearer auth IP rate limiting — fires `max_attempts + 1` bearer requests
+ *    with an invalid token, verifies the last returns 429.
+ *
+ * Each test group asserts that required routes exist, failing with a descriptive
+ * message if the consumer's route specs are misconfigured.
+ *
+ * @param options - session config and route factory
+ */
+export const describe_rate_limiting_tests = (options) => {
+    const max_attempts = options.max_attempts ?? 2;
+    const init_schema = async (db) => {
+        await run_migrations(db, [AUTH_MIGRATION_NS]);
+    };
+    const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
+    const describe_db = create_describe_db(factories, AUTH_INTEGRATION_TRUNCATE_TABLES);
+    /** Create a tight rate limiter for testing — low attempt count, long window. */
+    const create_test_rate_limiter = () => new RateLimiter({ max_attempts, window_ms: 60_000, cleanup_interval_ms: 0 });
+    describe_db('rate_limiting', (get_db) => {
+        // --- 1. IP rate limiting on login ---
+        describe('IP rate limiting on login', () => {
+            test(`login is blocked after ${max_attempts} failed attempts`, async () => {
+                const ip_rate_limiter = create_test_rate_limiter();
+                try {
+                    const test_app = await create_test_app({
+                        session_options: options.session_options,
+                        create_route_specs: options.create_route_specs,
+                        db: get_db(),
+                        app_options: {
+                            ...options.app_options,
+                            ip_rate_limiter,
+                            login_account_rate_limiter: null,
+                            bearer_ip_rate_limiter: null,
+                        },
+                    });
+                    const login_route = find_auth_route(test_app.route_specs, '/login', 'POST');
+                    assert.ok(login_route, 'Expected POST /login route — ensure create_route_specs includes account routes');
+                    // Fire max_attempts failed login requests (sequential — must exhaust the window)
+                    /* eslint-disable no-await-in-loop */
+                    for (let i = 0; i < max_attempts; i++) {
+                        const res = await test_app.app.request(login_route.path, {
+                            method: 'POST',
+                            headers: {
+                                host: 'localhost',
+                                origin: 'http://localhost:5173',
+                                'content-type': 'application/json',
+                            },
+                            body: JSON.stringify({ username: 'nonexistent', password: 'wrong' }),
+                        });
+                        assert.notStrictEqual(res.status, 429, `Request ${i + 1}/${max_attempts} should not be rate limited`);
+                    }
+                    /* eslint-enable no-await-in-loop */
+                    // The next request should be rate limited
+                    const blocked_res = await test_app.app.request(login_route.path, {
+                        method: 'POST',
+                        headers: {
+                            host: 'localhost',
+                            origin: 'http://localhost:5173',
+                            'content-type': 'application/json',
+                        },
+                        body: JSON.stringify({ username: 'nonexistent', password: 'wrong' }),
+                    });
+                    assert.strictEqual(blocked_res.status, 429);
+                    const body = await blocked_res.json();
+                    RateLimitError.parse(body);
+                    assert.ok(typeof body.retry_after === 'number' && body.retry_after > 0, 'Expected positive retry_after');
+                    assert_rate_limit_retry_after_header(blocked_res, body);
+                }
+                finally {
+                    ip_rate_limiter.dispose();
+                }
+            });
+        });
+        // --- 2. Per-account rate limiting on login ---
+        describe('per-account rate limiting on login', () => {
+            test(`login is blocked after ${max_attempts} failed attempts for the same username`, async () => {
+                const login_account_rate_limiter = create_test_rate_limiter();
+                try {
+                    const test_app = await create_test_app({
+                        session_options: options.session_options,
+                        create_route_specs: options.create_route_specs,
+                        db: get_db(),
+                        app_options: {
+                            ...options.app_options,
+                            ip_rate_limiter: null,
+                            login_account_rate_limiter,
+                            bearer_ip_rate_limiter: null,
+                        },
+                    });
+                    const login_route = find_auth_route(test_app.route_specs, '/login', 'POST');
+                    assert.ok(login_route, 'Expected POST /login route — ensure create_route_specs includes account routes');
+                    const target_username = 'rate_limit_target';
+                    // Fire max_attempts failed login requests for the same username
+                    /* eslint-disable no-await-in-loop */
+                    for (let i = 0; i < max_attempts; i++) {
+                        const res = await test_app.app.request(login_route.path, {
+                            method: 'POST',
+                            headers: {
+                                host: 'localhost',
+                                origin: 'http://localhost:5173',
+                                'content-type': 'application/json',
+                            },
+                            body: JSON.stringify({ username: target_username, password: 'wrong' }),
+                        });
+                        assert.notStrictEqual(res.status, 429, `Request ${i + 1}/${max_attempts} should not be rate limited`);
+                    }
+                    /* eslint-enable no-await-in-loop */
+                    // The next request for the same username should be rate limited
+                    const blocked_res = await test_app.app.request(login_route.path, {
+                        method: 'POST',
+                        headers: {
+                            host: 'localhost',
+                            origin: 'http://localhost:5173',
+                            'content-type': 'application/json',
+                        },
+                        body: JSON.stringify({ username: target_username, password: 'wrong' }),
+                    });
+                    assert.strictEqual(blocked_res.status, 429);
+                    const body = await blocked_res.json();
+                    RateLimitError.parse(body);
+                    assert.ok(typeof body.retry_after === 'number' && body.retry_after > 0, 'Expected positive retry_after');
+                    assert_rate_limit_retry_after_header(blocked_res, body);
+                    // A different username should NOT be rate limited
+                    const other_res = await test_app.app.request(login_route.path, {
+                        method: 'POST',
+                        headers: {
+                            host: 'localhost',
+                            origin: 'http://localhost:5173',
+                            'content-type': 'application/json',
+                        },
+                        body: JSON.stringify({ username: 'different_user', password: 'wrong' }),
+                    });
+                    assert.notStrictEqual(other_res.status, 429, 'Different username should not be rate limited');
+                }
+                finally {
+                    login_account_rate_limiter.dispose();
+                }
+            });
+        });
+        // --- 3. Bearer auth IP rate limiting ---
+        describe('bearer auth IP rate limiting', () => {
+            test(`bearer auth is blocked after ${max_attempts} invalid token attempts`, async () => {
+                const bearer_ip_rate_limiter = create_test_rate_limiter();
+                try {
+                    const test_app = await create_test_app({
+                        session_options: options.session_options,
+                        create_route_specs: options.create_route_specs,
+                        db: get_db(),
+                        app_options: {
+                            ...options.app_options,
+                            ip_rate_limiter: null,
+                            login_account_rate_limiter: null,
+                            bearer_ip_rate_limiter,
+                        },
+                    });
+                    const verify_route = find_auth_route(test_app.route_specs, '/verify', 'GET');
+                    assert.ok(verify_route, 'Expected GET /verify route — ensure create_route_specs includes account routes');
+                    // Fire max_attempts invalid bearer requests (sequential — must exhaust the window)
+                    /* eslint-disable no-await-in-loop */
+                    for (let i = 0; i < max_attempts; i++) {
+                        const res = await test_app.app.request(verify_route.path, {
+                            headers: {
+                                host: 'localhost',
+                                authorization: 'Bearer secret_fuz_token_invalid',
+                            },
+                        });
+                        assert.notStrictEqual(res.status, 429, `Request ${i + 1}/${max_attempts} should not be rate limited`);
+                    }
+                    /* eslint-enable no-await-in-loop */
+                    // The next request should be rate limited
+                    const blocked_res = await test_app.app.request(verify_route.path, {
+                        headers: {
+                            host: 'localhost',
+                            authorization: 'Bearer secret_fuz_token_invalid',
+                        },
+                    });
+                    assert.strictEqual(blocked_res.status, 429);
+                    const body = await blocked_res.json();
+                    RateLimitError.parse(body);
+                    assert_rate_limit_retry_after_header(blocked_res, body);
+                }
+                finally {
+                    bearer_ip_rate_limiter.dispose();
+                }
+            });
+        });
+    });
+};

package/dist/testing/round_trip.d.ts

@@ -0,0 +1,37 @@
+import './assert_dev_env.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import { type DbFactory } from './db.js';
+/** Options for `describe_round_trip_validation`. */
+export interface RoundTripTestOptions {
+    /** 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>;
+    /** Routes to skip, in `'METHOD /path'` format. */
+    skip_routes?: Array<string>;
+    /** Override generated bodies for specific routes (`'METHOD /path'` → body). */
+    input_overrides?: Map<string, Record<string, unknown>>;
+}
+/**
+ * Run schema-driven round-trip validation tests.
+ *
+ * For each route:
+ * 1. Resolve URL with valid params
+ * 2. Generate a valid request body (or use override)
+ * 3. Pick auth headers matching the route's auth requirement
+ * 4. Fire the request and validate the response against declared schemas
+ *
+ * SSE routes are skipped (Content-Type `text/event-stream`).
+ * Routes returning non-2xx with valid input are still validated against
+ * their declared error schemas.
+ *
+ * @param options - round-trip test configuration
+ */
+export declare const describe_round_trip_validation: (options: RoundTripTestOptions) => void;
+//# sourceMappingURL=round_trip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAc7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAwB,KAAK,SAAS,EAAC,MAAM,SAAS,CAAC;AAO9D,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACpC,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,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,kDAAkD;IAClD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,oBAAoB,KAAG,IAsF9E,CAAC"}

package/dist/testing/round_trip.js

@@ -0,0 +1,128 @@
+import './assert_dev_env.js';
+/**
+ * Schema-driven round-trip validation test suite.
+ *
+ * For every route spec, generates a valid request (auth, params, body)
+ * and validates the response against declared output or error schemas.
+ * DB-backed via `create_test_app` — exercises the full middleware stack.
+ *
+ * @module
+ */
+import { describe, test, beforeAll, afterAll } from 'vitest';
+import { ROLE_ADMIN } from '../auth/role_schema.js';
+import { create_test_app } from './app_server.js';
+import { create_pglite_factory } from './db.js';
+import { assert_response_matches_spec } from './integration_helpers.js';
+import { resolve_valid_path, generate_valid_body } from './schema_generators.js';
+import { run_migrations } from '../db/migrate.js';
+import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
+/**
+ * Run schema-driven round-trip validation tests.
+ *
+ * For each route:
+ * 1. Resolve URL with valid params
+ * 2. Generate a valid request body (or use override)
+ * 3. Pick auth headers matching the route's auth requirement
+ * 4. Fire the request and validate the response against declared schemas
+ *
+ * SSE routes are skipped (Content-Type `text/event-stream`).
+ * Routes returning non-2xx with valid input are still validated against
+ * their declared error schemas.
+ *
+ * @param options - round-trip test configuration
+ */
+export const describe_round_trip_validation = (options) => {
+    const skip_set = new Set(options.skip_routes);
+    const init_schema = async (db) => {
+        await run_migrations(db, [AUTH_MIGRATION_NS]);
+    };
+    const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
+    for (const factory of factories) {
+        describe(`round-trip validation (${factory.name})`, () => {
+            if (factory.skip)
+                return;
+            let test_app;
+            let authed_account;
+            let admin_account;
+            let db;
+            beforeAll(async () => {
+                db = await factory.create();
+                test_app = await create_test_app({
+                    session_options: options.session_options,
+                    create_route_specs: options.create_route_specs,
+                    db,
+                    app_options: options.app_options,
+                });
+                // Create accounts at each auth level
+                authed_account = await test_app.create_account({
+                    username: 'round_trip_authed',
+                    roles: [],
+                });
+                admin_account = await test_app.create_account({
+                    username: 'round_trip_admin',
+                    roles: [ROLE_ADMIN],
+                });
+            });
+            afterAll(async () => {
+                await test_app.cleanup();
+                await factory.close(db);
+            });
+            test('all routes produce schema-valid responses', async () => {
+                for (const spec of test_app.route_specs) {
+                    const route_key = `${spec.method} ${spec.path}`;
+                    if (skip_set.has(route_key))
+                        continue;
+                    // Resolve URL with valid param values
+                    const url = resolve_valid_path(spec.path, spec.params);
+                    // Generate or override request body
+                    const override = options.input_overrides?.get(route_key);
+                    const body = override ?? generate_valid_body(spec.input);
+                    // Pick auth headers based on route auth requirement
+                    const headers = pick_auth_headers(spec, test_app, authed_account, admin_account);
+                    // Fire request
+                    const request_init = {
+                        method: spec.method,
+                        headers: {
+                            ...headers,
+                            ...(body ? { 'content-type': 'application/json' } : {}),
+                        },
+                        ...(body ? { body: JSON.stringify(body) } : {}),
+                    };
+                    const res = await test_app.app.request(url, request_init); // eslint-disable-line no-await-in-loop
+                    // Skip SSE responses — streaming bodies can't be parsed as JSON
+                    if (res.headers.get('Content-Type')?.includes('text/event-stream')) {
+                        await res.body?.cancel(); // eslint-disable-line no-await-in-loop
+                        continue;
+                    }
+                    // Validate response against declared schemas
+                    try {
+                        await assert_response_matches_spec(test_app.route_specs, spec.method, url, res); // eslint-disable-line no-await-in-loop
+                    }
+                    catch (e) {
+                        // Re-throw with route context for easier debugging
+                        throw new Error(`Round-trip validation failed for ${route_key} (status ${res.status}): ${e.message}`);
+                    }
+                }
+            });
+        });
+    }
+};
+/**
+ * Pick auth headers matching a route spec's auth requirement.
+ */
+const pick_auth_headers = (spec, test_app, authed_account, admin_account) => {
+    switch (spec.auth.type) {
+        case 'none':
+            return { host: 'localhost', origin: 'http://localhost:5173' };
+        case 'authenticated':
+            return authed_account.create_session_headers();
+        case 'role':
+            if (spec.auth.role === ROLE_ADMIN) {
+                return admin_account.create_session_headers();
+            }
+            // Keeper role uses the bootstrapped account (which has keeper role)
+            return test_app.create_session_headers();
+        case 'keeper':
+            return test_app.create_bearer_headers();
+    }
+};