@fuzdev/fuz_app 0.1.0

package/dist/testing/audit_completeness.js

@@ -0,0 +1,410 @@
+import './assert_dev_env.js';
+/**
+ * Composable audit log completeness test suite.
+ *
+ * Verifies that every auth mutation route produces the expected audit log
+ * event. Uses the real middleware stack and database — audit events are
+ * verified by querying the `audit_log` table after each request.
+ *
+ * Bootstrap is excluded because it requires filesystem token state that
+ * `create_test_app` does not provide. Bootstrap audit logging is tested
+ * separately in `bootstrap_account.db.test.ts`.
+ *
+ * @module
+ */
+import { describe, test, assert } from 'vitest';
+import { ROLE_KEEPER, ROLE_ADMIN } from '../auth/role_schema.js';
+import { AUDIT_EVENT_TYPES } from '../auth/audit_log_schema.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 } from './integration_helpers.js';
+import { run_migrations } from '../db/migrate.js';
+/** Find an admin route by suffix and method. */
+const find_admin_route = (specs, suffix, method) => specs.find((s) => s.method === method &&
+    s.path.endsWith(suffix) &&
+    s.auth.type === 'role' &&
+    s.auth.role === 'admin');
+/** Query audit log events from the database. */
+const query_audit_events = async (db) => {
+    return db.query('SELECT event_type, seq FROM audit_log ORDER BY seq');
+};
+/** Assert that audit events contain the expected event type. */
+const assert_has_event = (events, expected, context) => {
+    assert.ok(events.some((e) => e.event_type === expected), `Expected '${expected}' audit event after ${context}`);
+};
+/** Build CreateTestAppOptions with admin+keeper roles. */
+const build_options = (options, db) => ({
+    session_options: options.session_options,
+    create_route_specs: options.create_route_specs,
+    db,
+    roles: [ROLE_KEEPER, ROLE_ADMIN],
+    app_options: options.app_options,
+});
+/** Headers for unauthenticated JSON requests (login, signup). */
+const UNAUTHENTICATED_JSON_HEADERS = {
+    host: 'localhost',
+    origin: 'http://localhost:5173',
+    'content-type': 'application/json',
+};
+/** Standard request headers for session-authenticated JSON requests. */
+const json_session_headers = (test_app, extra) => test_app.create_session_headers({
+    'content-type': 'application/json',
+    ...extra,
+});
+/**
+ * Find an account-scoped parameterized route (e.g. `/tokens/:id/revoke`).
+ *
+ * Matches routes with a `:id` or `:param` segment that are NOT admin role-gated.
+ */
+const find_account_parameterized_route = (specs, segment, suffix, method) => specs.find((s) => s.method === method &&
+    s.path.includes(`/${segment}/`) &&
+    s.path.endsWith(suffix) &&
+    s.auth.type !== 'role');
+/**
+ * Composable audit log completeness test suite.
+ *
+ * Verifies that every auth mutation route produces the correct audit log
+ * event type. Exercises routes via HTTP requests against a real PGlite
+ * database, then queries the `audit_log` table to verify events.
+ *
+ * @param options - session config, route factory, and optional overrides
+ */
+export const describe_audit_completeness_tests = (options) => {
+    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);
+    describe_db('audit_log_completeness', (get_db) => {
+        // --- Account routes ---
+        describe('account mutation audit events', () => {
+            test('login success produces login event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const login_route = find_auth_route(test_app.route_specs, '/login', 'POST');
+                assert.ok(login_route, 'Expected POST /login route');
+                const res = await test_app.app.request(login_route.path, {
+                    method: 'POST',
+                    headers: UNAUTHENTICATED_JSON_HEADERS,
+                    body: JSON.stringify({
+                        username: test_app.backend.account.username,
+                        password: 'test-password-123',
+                    }),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'login', 'POST /login (success)');
+            });
+            test('login failure produces login event with failure outcome', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const login_route = find_auth_route(test_app.route_specs, '/login', 'POST');
+                assert.ok(login_route, 'Expected POST /login route');
+                const res = await test_app.app.request(login_route.path, {
+                    method: 'POST',
+                    headers: UNAUTHENTICATED_JSON_HEADERS,
+                    body: JSON.stringify({
+                        username: test_app.backend.account.username,
+                        password: 'wrong-password',
+                    }),
+                });
+                assert.strictEqual(res.status, 401);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'login', 'POST /login (failure)');
+            });
+            test('logout produces logout event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const logout_route = find_auth_route(test_app.route_specs, '/logout', 'POST');
+                assert.ok(logout_route, 'Expected POST /logout route');
+                const res = await test_app.app.request(logout_route.path, {
+                    method: 'POST',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'logout', 'POST /logout');
+            });
+            test('token create produces token_create event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const route = find_auth_route(test_app.route_specs, '/tokens/create', 'POST');
+                assert.ok(route, 'Expected POST /tokens/create route');
+                const res = await test_app.app.request(route.path, {
+                    method: 'POST',
+                    headers: json_session_headers(test_app),
+                    body: JSON.stringify({ name: 'audit-test' }),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'token_create', 'POST /tokens/create');
+            });
+            test('token revoke produces token_revoke event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                // get a token ID to revoke
+                const tokens_route = find_auth_route(test_app.route_specs, '/tokens', 'GET');
+                assert.ok(tokens_route, 'Expected GET /tokens route');
+                const list_res = await test_app.app.request(tokens_route.path, {
+                    headers: test_app.create_session_headers(),
+                });
+                const { tokens } = (await list_res.json());
+                assert.ok(tokens.length > 0, 'Expected at least one token');
+                const route = find_account_parameterized_route(test_app.route_specs, 'tokens', '/revoke', 'POST');
+                assert.ok(route, 'Expected POST /tokens/:id/revoke route');
+                const path = route.path.replace(':id', tokens[0].id);
+                const res = await test_app.app.request(path, {
+                    method: 'POST',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'token_revoke', 'POST /tokens/:id/revoke');
+            });
+            test('session revoke produces session_revoke event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                // login to create a second session we can revoke
+                const login_route = find_auth_route(test_app.route_specs, '/login', 'POST');
+                assert.ok(login_route, 'Expected POST /login route');
+                await test_app.app.request(login_route.path, {
+                    method: 'POST',
+                    headers: UNAUTHENTICATED_JSON_HEADERS,
+                    body: JSON.stringify({
+                        username: test_app.backend.account.username,
+                        password: 'test-password-123',
+                    }),
+                });
+                // get session IDs (newest first)
+                const sessions_route = find_auth_route(test_app.route_specs, '/sessions', 'GET');
+                assert.ok(sessions_route, 'Expected GET /sessions route');
+                const list_res = await test_app.app.request(sessions_route.path, {
+                    headers: test_app.create_session_headers(),
+                });
+                const { sessions } = (await list_res.json());
+                assert.ok(sessions.length >= 2, 'Expected at least 2 sessions');
+                const route = find_account_parameterized_route(test_app.route_specs, 'sessions', '/revoke', 'POST');
+                assert.ok(route, 'Expected POST /sessions/:id/revoke route');
+                // revoke the second session (not the one used for auth)
+                const path = route.path.replace(':id', sessions[1].id);
+                const res = await test_app.app.request(path, {
+                    method: 'POST',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'session_revoke', 'POST /sessions/:id/revoke');
+            });
+            test('session revoke-all produces session_revoke_all event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const route = find_auth_route(test_app.route_specs, '/sessions/revoke-all', 'POST');
+                assert.ok(route, 'Expected POST /sessions/revoke-all route');
+                const res = await test_app.app.request(route.path, {
+                    method: 'POST',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'session_revoke_all', 'POST /sessions/revoke-all');
+            });
+            test('password change produces password_change event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const route = find_auth_route(test_app.route_specs, '/password', 'POST');
+                assert.ok(route, 'Expected POST /password route');
+                const res = await test_app.app.request(route.path, {
+                    method: 'POST',
+                    headers: json_session_headers(test_app),
+                    body: JSON.stringify({
+                        current_password: 'test-password-123',
+                        new_password: 'new-password-456',
+                    }),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'password_change', 'POST /password');
+            });
+        });
+        // --- Admin routes ---
+        describe('admin mutation audit events', () => {
+            test('permit grant produces permit_grant event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const route = find_admin_route(test_app.route_specs, '/permits/grant', 'POST');
+                assert.ok(route, 'Expected admin POST /permits/grant route');
+                const target = await test_app.create_account({ username: 'audit_target' });
+                const path = route.path.replace(':account_id', target.account.id);
+                const res = await test_app.app.request(path, {
+                    method: 'POST',
+                    headers: json_session_headers(test_app),
+                    body: JSON.stringify({ role: ROLE_ADMIN }),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'permit_grant', 'POST /permits/grant');
+            });
+            test('permit revoke produces permit_revoke event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const grant_route = find_admin_route(test_app.route_specs, '/permits/grant', 'POST');
+                const revoke_route = test_app.route_specs.find((s) => s.method === 'POST' &&
+                    s.path.includes('/permits/') &&
+                    s.path.endsWith('/revoke') &&
+                    s.auth.type === 'role');
+                assert.ok(grant_route, 'Expected admin POST /permits/grant route');
+                assert.ok(revoke_route, 'Expected admin POST /permits/:permit_id/revoke route');
+                const target = await test_app.create_account({ username: 'audit_revoke_target' });
+                // grant a permit first
+                const grant_path = grant_route.path.replace(':account_id', target.account.id);
+                const grant_res = await test_app.app.request(grant_path, {
+                    method: 'POST',
+                    headers: json_session_headers(test_app),
+                    body: JSON.stringify({ role: ROLE_ADMIN }),
+                });
+                const grant_body = (await grant_res.json());
+                // revoke it
+                const revoke_path = revoke_route.path
+                    .replace(':account_id', target.account.id)
+                    .replace(':permit_id', grant_body.permit.id);
+                const res = await test_app.app.request(revoke_path, {
+                    method: 'POST',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'permit_revoke', 'POST /permits/:permit_id/revoke');
+            });
+            test('admin session revoke-all produces session_revoke_all event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const route = find_admin_route(test_app.route_specs, '/sessions/revoke-all', 'POST');
+                assert.ok(route, 'Expected admin POST /sessions/revoke-all route');
+                const target = await test_app.create_account({ username: 'audit_sessions_target' });
+                const path = route.path.replace(':account_id', target.account.id);
+                const res = await test_app.app.request(path, {
+                    method: 'POST',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                // admin session revoke-all also produces session_revoke_all
+                assert_has_event(events, 'session_revoke_all', 'admin POST /sessions/revoke-all');
+            });
+            test('admin token revoke-all produces token_revoke_all event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const route = find_admin_route(test_app.route_specs, '/tokens/revoke-all', 'POST');
+                assert.ok(route, 'Expected admin POST /tokens/revoke-all route');
+                const target = await test_app.create_account({ username: 'audit_tokens_target' });
+                const path = route.path.replace(':account_id', target.account.id);
+                const res = await test_app.app.request(path, {
+                    method: 'POST',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'token_revoke_all', 'admin POST /tokens/revoke-all');
+            });
+        });
+        // --- Invite routes ---
+        describe('invite mutation audit events', () => {
+            test('invite create and delete produce audit events', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const create_route = find_admin_route(test_app.route_specs, '/invites', 'POST');
+                const delete_route = test_app.route_specs.find((s) => s.method === 'DELETE' && s.path.includes('/invites/') && s.auth.type === 'role');
+                assert.ok(create_route, 'Expected admin POST /invites route');
+                assert.ok(delete_route, 'Expected admin DELETE /invites/:id route');
+                // create invite
+                const create_res = await test_app.app.request(create_route.path, {
+                    method: 'POST',
+                    headers: json_session_headers(test_app),
+                    body: JSON.stringify({ username: 'invited_user' }),
+                });
+                assert.strictEqual(create_res.status, 200);
+                const { invite } = (await create_res.json());
+                // delete invite
+                const delete_path = delete_route.path.replace(':id', invite.id);
+                const delete_res = await test_app.app.request(delete_path, {
+                    method: 'DELETE',
+                    headers: test_app.create_session_headers(),
+                });
+                assert.strictEqual(delete_res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'invite_create', 'POST /invites');
+                assert_has_event(events, 'invite_delete', 'DELETE /invites/:id');
+            });
+        });
+        // --- App settings routes ---
+        describe('app settings mutation audit events', () => {
+            test('settings update produces app_settings_update event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                const route = find_admin_route(test_app.route_specs, '/settings', 'PATCH');
+                assert.ok(route, 'Expected admin PATCH /settings route');
+                const res = await test_app.app.request(route.path, {
+                    method: 'PATCH',
+                    headers: json_session_headers(test_app),
+                    body: JSON.stringify({ open_signup: true }),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'app_settings_update', 'PATCH /settings');
+            });
+        });
+        // --- Signup route ---
+        describe('signup audit events', () => {
+            test('signup produces signup event', async () => {
+                const test_app = await create_test_app(build_options(options, get_db()));
+                // enable open signup
+                const settings_route = find_admin_route(test_app.route_specs, '/settings', 'PATCH');
+                assert.ok(settings_route, 'Expected admin PATCH /settings route');
+                await test_app.app.request(settings_route.path, {
+                    method: 'PATCH',
+                    headers: json_session_headers(test_app),
+                    body: JSON.stringify({ open_signup: true }),
+                });
+                // signup
+                const signup_route = find_auth_route(test_app.route_specs, '/signup', 'POST');
+                assert.ok(signup_route, 'Expected POST /signup route');
+                const res = await test_app.app.request(signup_route.path, {
+                    method: 'POST',
+                    headers: UNAUTHENTICATED_JSON_HEADERS,
+                    body: JSON.stringify({
+                        username: 'signup_user',
+                        password: 'signup-password-123',
+                    }),
+                });
+                assert.strictEqual(res.status, 200);
+                const events = await query_audit_events(test_app.backend.deps.db);
+                assert_has_event(events, 'signup', 'POST /signup');
+            });
+        });
+        // --- Completeness check ---
+        describe('completeness', () => {
+            /**
+             * Event types covered by this suite. Bootstrap is excluded because
+             * it requires filesystem token state not provided by create_test_app.
+             */
+            const COVERED_EVENT_TYPES = new Set([
+                'login',
+                'logout',
+                'signup',
+                'password_change',
+                'session_revoke',
+                'session_revoke_all',
+                'token_create',
+                'token_revoke',
+                'token_revoke_all',
+                'permit_grant',
+                'permit_revoke',
+                'invite_create',
+                'invite_delete',
+                'app_settings_update',
+            ]);
+            /** Event types excluded with justification. */
+            const EXCLUDED_EVENT_TYPES = new Set([
+                'bootstrap', // requires filesystem token — tested in bootstrap_account.db.test.ts
+            ]);
+            test('all audit event types are covered or explicitly excluded', () => {
+                const all_covered = new Set([...COVERED_EVENT_TYPES, ...EXCLUDED_EVENT_TYPES]);
+                for (const event_type of AUDIT_EVENT_TYPES) {
+                    assert.ok(all_covered.has(event_type), `Audit event type '${event_type}' is not covered by the completeness suite and not explicitly excluded — add a test or exclude with justification`);
+                }
+            });
+            test('no excluded event types are also covered', () => {
+                for (const event_type of EXCLUDED_EVENT_TYPES) {
+                    assert.ok(!COVERED_EVENT_TYPES.has(event_type), `Event type '${event_type}' is in both COVERED and EXCLUDED — remove from one`);
+                }
+            });
+        });
+    });
+};

package/dist/testing/auth_apps.d.ts

@@ -0,0 +1,55 @@
+import './assert_dev_env.js';
+/**
+ * Auth test app factories for adversarial testing.
+ *
+ * Creates Hono test apps at each auth level (public, authenticated, keeper,
+ * per-role) for use in adversarial auth enforcement and input validation tests.
+ *
+ * @module
+ */
+import { Hono } from 'hono';
+import { type RouteSpec, type RouteAuth } from '../http/route_spec.js';
+import { type RequestContext } from '../auth/request_context.js';
+import { type CredentialType } from '../hono_context.js';
+/**
+ * Create a mock request context with optional role permit.
+ *
+ * @param role - optional role to grant
+ * @returns a valid `RequestContext`
+ */
+export declare const create_test_request_context: (role?: string) => RequestContext;
+/**
+ * Create a Hono test app from route specs with optional auth context.
+ *
+ * @param route_specs - the route specs to register
+ * @param auth_ctx - optional request context to inject via middleware
+ * @param credential_type - optional credential type (default: `'session'` when auth_ctx provided)
+ * @returns a configured Hono app
+ */
+export declare const create_test_app_from_specs: (route_specs: Array<RouteSpec>, auth_ctx?: RequestContext, credential_type?: CredentialType) => Hono;
+/** Pre-built Hono apps for each auth level, shared across adversarial test suites. */
+export interface AuthTestApps {
+    public: Hono;
+    authed: Hono;
+    keeper: Hono;
+    by_role: Map<string, Hono>;
+}
+/**
+ * Create one Hono test app per auth level.
+ *
+ * @param route_specs - the route specs to register
+ * @param roles - all roles in the app
+ * @returns apps keyed by auth level
+ */
+export declare const create_auth_test_apps: (route_specs: Array<RouteSpec>, roles: Array<string>) => AuthTestApps;
+/**
+ * Select the Hono test app with correct auth for a route.
+ *
+ * @param apps - the pre-built auth test apps
+ * @param auth - the route's auth options
+ * @returns the correctly-authenticated Hono app
+ */
+export declare const select_auth_app: (apps: AuthTestApps, auth: RouteAuth) => Hono;
+/** Replace Hono route params (`:foo`) with dummy values for HTTP testing. */
+export declare const resolve_test_path: (path: string) => string;
+//# sourceMappingURL=auth_apps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth_apps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/auth_apps.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;GAOG;AAEH,OAAO,EAAC,IAAI,EAAC,MAAM,MAAM,CAAC;AAG1B,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAExF,OAAO,EAAsB,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAsB,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAG5E;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,MAAM,KAAG,cAkC1D,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,WAAW,cAAc,EACzB,kBAAkB,cAAc,KAC9B,IAkBF,CAAC;AAEF,sFAAsF;AACtF,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,IAAI,CAAC;IACb,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GACjC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,OAAO,KAAK,CAAC,MAAM,CAAC,KAClB,YAeF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,YAAY,EAAE,MAAM,SAAS,KAAG,IAcrE,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC"}

package/dist/testing/auth_apps.js

@@ -0,0 +1,122 @@
+import './assert_dev_env.js';
+/**
+ * Auth test app factories for adversarial testing.
+ *
+ * Creates Hono test apps at each auth level (public, authenticated, keeper,
+ * per-role) for use in adversarial auth enforcement and input validation tests.
+ *
+ * @module
+ */
+import { Hono } from 'hono';
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { apply_route_specs } from '../http/route_spec.js';
+import { fuz_auth_guard_resolver } from '../auth/route_guards.js';
+import { REQUEST_CONTEXT_KEY } from '../auth/request_context.js';
+import { CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { create_stub_db } from './stubs.js';
+/**
+ * Create a mock request context with optional role permit.
+ *
+ * @param role - optional role to grant
+ * @returns a valid `RequestContext`
+ */
+export const create_test_request_context = (role) => ({
+    account: {
+        id: 'acc_1',
+        username: 'testuser',
+        password_hash: 'hash',
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        created_by: null,
+        updated_by: null,
+        email: null,
+        email_verified: false,
+    },
+    actor: {
+        id: 'act_1',
+        account_id: 'acc_1',
+        name: 'testuser',
+        created_at: new Date().toISOString(),
+        updated_at: null,
+        updated_by: null,
+    },
+    permits: role
+        ? [
+            {
+                id: 'perm_1',
+                actor_id: 'act_1',
+                role,
+                created_at: new Date().toISOString(),
+                expires_at: null,
+                revoked_at: null,
+                revoked_by: null,
+                granted_by: null,
+            },
+        ]
+        : [],
+});
+/**
+ * Create a Hono test app from route specs with optional auth context.
+ *
+ * @param route_specs - the route specs to register
+ * @param auth_ctx - optional request context to inject via middleware
+ * @param credential_type - optional credential type (default: `'session'` when auth_ctx provided)
+ * @returns a configured Hono app
+ */
+export const create_test_app_from_specs = (route_specs, auth_ctx, credential_type) => {
+    const app = new Hono();
+    app.use('/*', async (c, next) => {
+        c.set('pending_effects', []);
+        if (auth_ctx) {
+            c.set(REQUEST_CONTEXT_KEY, auth_ctx);
+            c.set(CREDENTIAL_TYPE_KEY, credential_type ?? 'session');
+        }
+        await next();
+    });
+    apply_route_specs(app, route_specs, fuz_auth_guard_resolver, new Logger('test', { level: 'off' }), create_stub_db());
+    return app;
+};
+/**
+ * Create one Hono test app per auth level.
+ *
+ * @param route_specs - the route specs to register
+ * @param roles - all roles in the app
+ * @returns apps keyed by auth level
+ */
+export const create_auth_test_apps = (route_specs, roles) => {
+    const by_role = new Map();
+    for (const role of roles) {
+        by_role.set(role, create_test_app_from_specs(route_specs, create_test_request_context(role)));
+    }
+    return {
+        public: create_test_app_from_specs(route_specs),
+        authed: create_test_app_from_specs(route_specs, create_test_request_context()),
+        keeper: create_test_app_from_specs(route_specs, create_test_request_context('keeper'), 'daemon_token'),
+        by_role,
+    };
+};
+/**
+ * Select the Hono test app with correct auth for a route.
+ *
+ * @param apps - the pre-built auth test apps
+ * @param auth - the route's auth options
+ * @returns the correctly-authenticated Hono app
+ */
+export const select_auth_app = (apps, auth) => {
+    switch (auth.type) {
+        case 'none':
+            return apps.public;
+        case 'authenticated':
+            return apps.authed;
+        case 'keeper':
+            return apps.keeper;
+        case 'role': {
+            const app = apps.by_role.get(auth.role);
+            if (!app)
+                throw new Error(`No test app for role '${auth.role}' — is it in the roles array?`);
+            return app;
+        }
+    }
+};
+/** Replace Hono route params (`:foo`) with dummy values for HTTP testing. */
+export const resolve_test_path = (path) => path.replace(/:(\w+)/g, 'test_$1');

package/dist/testing/data_exposure.d.ts

@@ -0,0 +1,62 @@
+import './assert_dev_env.js';
+import type { AppSurface, AppSurfaceSpec } from '../http/surface.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';
+/**
+ * Recursively collect all property names from a JSON Schema.
+ *
+ * Walks `properties`, `items`, `allOf`/`anyOf`/`oneOf`, and
+ * `additionalProperties` to find every declared field name at any depth.
+ *
+ * @param schema - JSON Schema object
+ * @returns set of all property names found
+ */
+export declare const collect_json_schema_property_names: (schema: unknown) => Set<string>;
+/**
+ * Assert that no output schema in the surface contains sensitive field names.
+ *
+ * @param surface - the app surface to check
+ * @param sensitive_fields - field names to flag
+ */
+export declare const assert_output_schemas_no_sensitive_fields: (surface: AppSurface, sensitive_fields?: ReadonlyArray<string>) => void;
+/**
+ * Assert that non-admin route output schemas don't contain admin-only fields.
+ *
+ * @param surface - the app surface to check
+ * @param admin_only_fields - field names that are admin-only
+ */
+export declare const assert_non_admin_schemas_no_admin_fields: (surface: AppSurface, admin_only_fields?: ReadonlyArray<string>) => void;
+/** Options for `describe_data_exposure_tests`. */
+export interface DataExposureTestOptions {
+    /** Build the app surface spec (for schema-level checks). */
+    build: () => AppSurfaceSpec;
+    /** Session config for runtime tests. */
+    session_options: SessionOptions<string>;
+    /** Route spec factory for runtime tests. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** Fields that must never appear in any response. Default: `SENSITIVE_FIELD_BLOCKLIST`. */
+    sensitive_fields?: ReadonlyArray<string>;
+    /** Fields that must not appear in non-admin responses. Default: `ADMIN_ONLY_FIELD_BLOCKLIST`. */
+    admin_only_fields?: ReadonlyArray<string>;
+    /** 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>;
+}
+/**
+ * Composable data exposure test suite.
+ *
+ * Three test groups:
+ * 1. Schema-level — walk JSON Schema output/error schemas for sensitive field names
+ * 2. Runtime — fire real requests and check response bodies against blocklists
+ * 3. Cross-privilege — admin routes return 403 for non-admin, error responses
+ *    contain no sensitive fields
+ *
+ * @param options - test configuration
+ */
+export declare const describe_data_exposure_tests: (options: DataExposureTestOptions) => void;
+//# sourceMappingURL=data_exposure.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"data_exposure.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/data_exposure.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAgB7B,OAAO,KAAK,EAAC,UAAU,EAAE,cAAc,EAAC,MAAM,oBAAoB,CAAC;AACnE,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;AAc9D;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC,GAAI,QAAQ,OAAO,KAAG,GAAG,CAAC,MAAM,CAuB9E,CAAC;AAIF;;;;;GAKG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,UAAU,EACnB,mBAAkB,aAAa,CAAC,MAAM,CAA6B,KACjE,IAWF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wCAAwC,GACpD,SAAS,UAAU,EACnB,oBAAmB,aAAa,CAAC,MAAM,CAA8B,KACnE,IAcF,CAAC;AAIF,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACvC,4DAA4D;IAC5D,KAAK,EAAE,MAAM,cAAc,CAAC;IAC5B,wCAAwC;IACxC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,4CAA4C;IAC5C,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,iGAAiG;IACjG,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,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;CAC5B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,uBAAuB,KAAG,IAmC/E,CAAC"}