@fuzdev/fuz_app 0.1.0

package/dist/testing/data_exposure.js

@@ -0,0 +1,297 @@
+import './assert_dev_env.js';
+/**
+ * Composable data exposure test suite.
+ *
+ * Verifies that sensitive database fields never leak through HTTP responses:
+ * - Schema-level: walks JSON Schema output/error schemas for blocklisted property names
+ * - Runtime: fires real requests and checks response bodies against field blocklists
+ * - Cross-privilege: verifies admin routes return 403 for non-admin users,
+ *   and non-admin responses exclude admin-only fields
+ *
+ * @module
+ */
+import { describe, test, beforeAll, afterAll, assert } 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 { 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';
+import { is_null_schema, is_strict_object_schema } from '../http/schema_helpers.js';
+import { SENSITIVE_FIELD_BLOCKLIST, ADMIN_ONLY_FIELD_BLOCKLIST, assert_no_sensitive_fields_in_json, } from './integration_helpers.js';
+// --- Schema introspection ---
+/**
+ * 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 const collect_json_schema_property_names = (schema) => {
+    const names = new Set();
+    const walk = (s) => {
+        if (s === null || s === undefined || typeof s !== 'object')
+            return;
+        const obj = s;
+        if (obj.properties && typeof obj.properties === 'object') {
+            for (const [name, prop_schema] of Object.entries(obj.properties)) {
+                names.add(name);
+                walk(prop_schema);
+            }
+        }
+        if (obj.items)
+            walk(obj.items);
+        for (const key of ['allOf', 'anyOf', 'oneOf']) {
+            if (Array.isArray(obj[key])) {
+                for (const sub of obj[key])
+                    walk(sub);
+            }
+        }
+        if (obj.additionalProperties && typeof obj.additionalProperties === 'object') {
+            walk(obj.additionalProperties);
+        }
+    };
+    walk(schema);
+    return names;
+};
+// --- Schema-level assertions ---
+/**
+ * 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 const assert_output_schemas_no_sensitive_fields = (surface, sensitive_fields = SENSITIVE_FIELD_BLOCKLIST) => {
+    for (const route of surface.routes) {
+        if (route.output_schema === null)
+            continue;
+        const prop_names = collect_json_schema_property_names(route.output_schema);
+        for (const field of sensitive_fields) {
+            assert.ok(!prop_names.has(field), `${route.method} ${route.path}: output schema contains sensitive field '${field}'`);
+        }
+    }
+};
+/**
+ * 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 const assert_non_admin_schemas_no_admin_fields = (surface, admin_only_fields = ADMIN_ONLY_FIELD_BLOCKLIST) => {
+    const non_admin = surface.routes.filter((r) => r.auth.type !== 'keeper' && !(r.auth.type === 'role' && r.auth.role === 'admin'));
+    for (const route of non_admin) {
+        if (route.output_schema === null)
+            continue;
+        const prop_names = collect_json_schema_property_names(route.output_schema);
+        for (const field of admin_only_fields) {
+            assert.ok(!prop_names.has(field), `${route.method} ${route.path}: non-admin output schema contains admin-only field '${field}'`);
+        }
+    }
+};
+/**
+ * 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 const describe_data_exposure_tests = (options) => {
+    const { build, sensitive_fields = SENSITIVE_FIELD_BLOCKLIST, admin_only_fields = ADMIN_ONLY_FIELD_BLOCKLIST, } = options;
+    describe('data exposure — schema-level', () => {
+        const { surface } = build();
+        test('no sensitive fields in any output schema', () => {
+            assert_output_schemas_no_sensitive_fields(surface, sensitive_fields);
+        });
+        test('no admin-only fields in non-admin output schemas', () => {
+            assert_non_admin_schemas_no_admin_fields(surface, admin_only_fields);
+        });
+        test('no sensitive fields in any error schema', () => {
+            for (const route of surface.routes) {
+                if (!route.error_schemas)
+                    continue;
+                for (const [status, schema] of Object.entries(route.error_schemas)) {
+                    const prop_names = collect_json_schema_property_names(schema);
+                    for (const field of sensitive_fields) {
+                        assert.ok(!prop_names.has(field), `${route.method} ${route.path} error ${status}: contains sensitive field '${field}'`);
+                    }
+                }
+            }
+        });
+    });
+    describe_data_exposure_runtime_tests(options);
+};
+// --- Runtime tests ---
+const describe_data_exposure_runtime_tests = (options) => {
+    const { sensitive_fields = SENSITIVE_FIELD_BLOCKLIST, admin_only_fields = ADMIN_ONLY_FIELD_BLOCKLIST, } = 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(`data exposure — runtime (${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,
+                });
+                authed_account = await test_app.create_account({
+                    username: 'exposure_authed',
+                    roles: [],
+                });
+                admin_account = await test_app.create_account({
+                    username: 'exposure_admin',
+                    roles: [ROLE_ADMIN],
+                });
+            });
+            afterAll(async () => {
+                await test_app.cleanup();
+                await factory.close(db);
+            });
+            // Tests that don't fire authenticated requests run first — they don't
+            // invalidate sessions and are independent of test order.
+            test('unauthenticated error responses contain no sensitive fields', async () => {
+                const protected_specs = test_app.route_specs.filter((s) => s.auth.type !== 'none');
+                for (const spec of protected_specs) {
+                    const route_key = `${spec.method} ${spec.path}`;
+                    if (skip_set.has(route_key))
+                        continue;
+                    const url = resolve_valid_path(spec.path, spec.params);
+                    // eslint-disable-next-line no-await-in-loop
+                    const res = await test_app.app.request(url, {
+                        method: spec.method,
+                        headers: { host: 'localhost', origin: 'http://localhost:5173' },
+                    });
+                    if (res.headers.get('Content-Type')?.includes('text/event-stream')) {
+                        await res.body?.cancel(); // eslint-disable-line no-await-in-loop
+                        continue;
+                    }
+                    let error_body;
+                    try {
+                        error_body = await res.clone().json(); // eslint-disable-line no-await-in-loop
+                    }
+                    catch {
+                        continue;
+                    }
+                    assert_no_sensitive_fields_in_json(error_body, sensitive_fields, `unauthenticated ${route_key} (${res.status})`);
+                }
+            });
+            // Cross-privilege test runs before 2xx tests — admin routes reject
+            // without calling handlers, so sessions stay intact.
+            test('admin routes return 403 for non-admin user', async () => {
+                const admin_specs = test_app.route_specs.filter((s) => s.auth.type === 'role' && s.auth.role === 'admin');
+                for (const spec of admin_specs) {
+                    const route_key = `${spec.method} ${spec.path}`;
+                    if (skip_set.has(route_key))
+                        continue;
+                    const url = resolve_valid_path(spec.path, spec.params);
+                    const headers = authed_account.create_session_headers();
+                    // eslint-disable-next-line no-await-in-loop
+                    const res = await test_app.app.request(url, {
+                        method: spec.method,
+                        headers,
+                    });
+                    assert.strictEqual(res.status, 403, `${route_key} should return 403 for non-admin user`);
+                    let error_body;
+                    try {
+                        error_body = await res.clone().json(); // eslint-disable-line no-await-in-loop
+                    }
+                    catch {
+                        continue;
+                    }
+                    assert_no_sensitive_fields_in_json(error_body, sensitive_fields, `${route_key} 403`);
+                }
+            });
+            // 2xx tests run last — handlers like logout and session-revoke-all
+            // invalidate sessions as a side effect. Sort GET before POST so
+            // data-returning routes are checked before destructive routes fire.
+            test('all 2xx responses pass field blocklists', async () => {
+                // sort GET before mutations to check data-returning routes
+                // before destructive routes (logout, revoke-all) invalidate sessions
+                const sorted_specs = [...test_app.route_specs].sort((a, b) => {
+                    if (a.method === 'GET' && b.method !== 'GET')
+                        return -1;
+                    if (a.method !== 'GET' && b.method === 'GET')
+                        return 1;
+                    return 0;
+                });
+                for (const spec of sorted_specs) {
+                    const route_key = `${spec.method} ${spec.path}`;
+                    if (skip_set.has(route_key))
+                        continue;
+                    // keeper auth (daemon token) is strictly more privileged than admin
+                    const is_elevated = spec.auth.type === 'keeper' ||
+                        (spec.auth.type === 'role' && spec.auth.role === 'admin');
+                    const url = resolve_valid_path(spec.path, spec.params);
+                    const body = generate_valid_body(spec.input);
+                    const headers = pick_auth_headers(spec, test_app, authed_account, admin_account);
+                    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
+                    if (res.headers.get('Content-Type')?.includes('text/event-stream')) {
+                        await res.body?.cancel(); // eslint-disable-line no-await-in-loop
+                        continue;
+                    }
+                    if (!res.ok)
+                        continue;
+                    let response_body;
+                    try {
+                        response_body = await res.clone().json(); // eslint-disable-line no-await-in-loop
+                    }
+                    catch {
+                        continue;
+                    }
+                    assert_no_sensitive_fields_in_json(response_body, sensitive_fields, `${route_key} (${res.status})`);
+                    // Admin-only field check applies to non-elevated routes with strict
+                    // output schemas. Loose schemas (e.g. surface route returning JSON
+                    // Schema representations) may contain admin field names as metadata.
+                    if (!is_elevated &&
+                        !is_null_schema(spec.output) &&
+                        is_strict_object_schema(spec.output)) {
+                        assert_no_sensitive_fields_in_json(response_body, admin_only_fields, `non-admin ${route_key} (${res.status})`);
+                    }
+                }
+            });
+        });
+    }
+};
+/**
+ * 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
+            return test_app.create_session_headers();
+        case 'keeper':
+            return test_app.create_bearer_headers();
+    }
+};

package/dist/testing/db.d.ts

@@ -0,0 +1,111 @@
+import './assert_dev_env.js';
+import type { Db } from '../db/db.js';
+/**
+ * CI detection — `CI=true` is set automatically by GitHub Actions, GitLab CI, etc.
+ */
+export declare const IS_CI: boolean;
+/**
+ * Factory interface for creating test database instances.
+ */
+export interface DbFactory {
+    name: string;
+    create: () => Promise<Db>;
+    close: (db: Db) => Promise<void>;
+    skip: boolean;
+    skip_reason?: string;
+}
+/**
+ * Reset a PGlite database to a clean state by dropping and recreating the public schema.
+ *
+ * Removes all tables, sequences, indexes, types, and functions.
+ * The database instance remains usable after reset.
+ *
+ * @param db - the database to reset
+ */
+export declare const reset_pglite: (db: Db) => Promise<void>;
+/**
+ * Create a pglite (in-memory) database factory for tests.
+ *
+ * Always enabled — no external dependencies required.
+ * Shares a single PGlite WASM instance across all factories in the same
+ * vitest worker thread (one test file). Subsequent `create()` calls reset
+ * the schema via `DROP SCHEMA public CASCADE` instead of paying the WASM
+ * cold-start cost again.
+ *
+ * @param init_schema - callback to initialize the database schema
+ * @returns a factory that creates in-memory pglite databases
+ */
+export declare const create_pglite_factory: (init_schema: (db: Db) => Promise<void>) => DbFactory;
+/**
+ * Create a pg (PostgreSQL) database factory for tests.
+ *
+ * Skipped when `test_url` is not provided.
+ * Drops `schema_version` before running `init_schema`, forcing migrations
+ * to re-evaluate against the actual tables. Prevents stale version entries
+ * from skipping migrations when DDL changes between test sessions.
+ *
+ * For full clean-slate behavior (recommended), call `drop_auth_schema(db)`
+ * at the start of `init_schema` before running migrations. This handles
+ * upstream schema changes that go beyond adding new tables/columns.
+ *
+ * @param init_schema - callback to initialize the database schema
+ * @param test_url - PostgreSQL connection URL (e.g. from `TEST_DATABASE_URL`)
+ * @returns a factory that creates pg databases
+ */
+export declare const create_pg_factory: (init_schema: (db: Db) => Promise<void>, test_url?: string) => DbFactory;
+/**
+ * Auth table names in truncation order (children first for FK safety).
+ *
+ * Consumer projects can spread this into their own list and append app-specific tables.
+ */
+export declare const AUTH_TRUNCATE_TABLES: string[];
+/**
+ * Auth tables including `audit_log` — for integration tests that exercise
+ * the full middleware stack (login, admin, rate limiting).
+ *
+ * Separate from `AUTH_TRUNCATE_TABLES` because unit-level DB tests that don't
+ * touch audit logging don't need to truncate it.
+ */
+export declare const AUTH_INTEGRATION_TRUNCATE_TABLES: string[];
+/**
+ * All auth tables in drop order (children first for FK safety).
+ *
+ * The full set created by `AUTH_MIGRATIONS` — use for clean-slate
+ * test DB initialization. `AUTH_TRUNCATE_TABLES` is the subset for
+ * between-test data cleanup (excludes `audit_log`).
+ *
+ * When adding tables to `AUTH_MIGRATIONS`, add them here too.
+ */
+export declare const AUTH_DROP_TABLES: readonly ["app_settings", "invite", "audit_log", "api_token", "auth_session", "permit", "actor", "account", "bootstrap_lock"];
+/**
+ * Drop all auth tables and schema version tracking for a clean slate.
+ *
+ * Recommended at the start of `init_schema` callbacks for `create_pg_factory`.
+ * Persistent test databases can accumulate stale schema from previous fuz_app
+ * versions — this ensures migrations run against a truly empty database.
+ * Safe on fresh databases (`IF EXISTS` on all statements). No-op effect for
+ * PGlite (already fresh), but harmless to call unconditionally.
+ *
+ * @param db - the database to clean
+ */
+export declare const drop_auth_schema: (db: Db) => Promise<void>;
+/**
+ * Create a `describe_db` function bound to specific factories and truncate tables.
+ *
+ * Returns a 2-arg `(name, fn)` function that runs the test suite against each
+ * factory. Each factory gets its own `describe` block with a shared database
+ * instance, automatic `beforeEach` truncation, and `afterAll` cleanup.
+ * Skipped factories use `describe.skip`.
+ *
+ * @param factories - one or more database factories to run suites against
+ * @param truncate_tables - tables to truncate between tests (children first for FK safety)
+ * @returns a `describe_db` function for use in test files
+ */
+export declare const create_describe_db: (factories: DbFactory | Array<DbFactory>, truncate_tables: Array<string>) => ((name: string, fn: (get_db: () => Db) => void) => void);
+/**
+ * Log factory status to console.
+ *
+ * @param factories - the database factories to report on
+ */
+export declare const log_db_factory_status: (factories: Array<DbFactory>) => void;
+//# sourceMappingURL=db.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/db.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA6B7B,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAKpC;;GAEG;AACH,eAAO,MAAM,KAAK,SAA4B,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,OAAO,CAAC,EAAE,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,IAAI,CAGvD,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAAI,aAAa,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,KAAG,SAkB7E,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,GAC7B,aAAa,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,EACtC,WAAW,MAAM,KACf,SA2DF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAOhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,UAAyC,CAAC;AAEvF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,+HAUnB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,IAAI,CAK3D,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC9B,WAAW,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,EACvC,iBAAiB,KAAK,CAAC,MAAM,CAAC,KAC5B,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,KAAK,IAAI,CAwBzD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,KAAK,CAAC,SAAS,CAAC,KAAG,IAMnE,CAAC"}

package/dist/testing/db.js

@@ -0,0 +1,258 @@
+import './assert_dev_env.js';
+/**
+ * Test database fixtures for parameterized testing.
+ *
+ * Provides factory builders for creating test databases with pglite (in-memory)
+ * and pg (PostgreSQL) drivers. Consumer projects provide their own schema
+ * initialization via `run_migrations` and compose factories into test suites.
+ *
+ * @example
+ * ```ts
+ * import {create_pglite_factory, create_pg_factory} from '@fuzdev/fuz_app/testing/db.js';
+ * import {run_migrations} from '@fuzdev/fuz_app/db/migrate.js';
+ * import {AUTH_MIGRATION_NS} from '@fuzdev/fuz_app/auth/migrations.js';
+ *
+ * const init_schema = async (db) => {
+ *   await run_migrations(db, [AUTH_MIGRATION_NS]);
+ * };
+ * const pglite_factory = create_pglite_factory(init_schema);
+ * const pg_factory = create_pg_factory(init_schema, process.env.TEST_DATABASE_URL);
+ * export const db_factories = [pglite_factory, pg_factory];
+ * ```
+ *
+ * @module
+ */
+import { describe, beforeAll, beforeEach, afterAll } from 'vitest';
+import { create_pglite_db } from '../db/db_pglite.js';
+import { assert_valid_sql_identifier } from '../db/sql_identifier.js';
+import { create_pg_db } from '../db/db_pg.js';
+/**
+ * CI detection — `CI=true` is set automatically by GitHub Actions, GitLab CI, etc.
+ */
+export const IS_CI = process.env.CI === 'true';
+/**
+ * Reset a PGlite database to a clean state by dropping and recreating the public schema.
+ *
+ * Removes all tables, sequences, indexes, types, and functions.
+ * The database instance remains usable after reset.
+ *
+ * @param db - the database to reset
+ */
+export const reset_pglite = async (db) => {
+    await db.query('DROP SCHEMA public CASCADE');
+    await db.query('CREATE SCHEMA public');
+};
+// Module-level PGlite cache — shared across all factories in the same vitest worker (one test file).
+// Each vitest file runs in its own worker thread, so no cross-file contamination.
+let module_db = null;
+/**
+ * Create a pglite (in-memory) database factory for tests.
+ *
+ * Always enabled — no external dependencies required.
+ * Shares a single PGlite WASM instance across all factories in the same
+ * vitest worker thread (one test file). Subsequent `create()` calls reset
+ * the schema via `DROP SCHEMA public CASCADE` instead of paying the WASM
+ * cold-start cost again.
+ *
+ * @param init_schema - callback to initialize the database schema
+ * @returns a factory that creates in-memory pglite databases
+ */
+export const create_pglite_factory = (init_schema) => ({
+    name: 'pglite',
+    skip: false,
+    async create() {
+        if (module_db) {
+            await reset_pglite(module_db);
+        }
+        else {
+            const { PGlite } = await import('@electric-sql/pglite');
+            const pglite = new PGlite();
+            module_db = create_pglite_db(pglite).db;
+        }
+        await init_schema(module_db);
+        return module_db;
+    },
+    async close() {
+        // No-op: shared instance lives for the worker thread's lifetime.
+        // PGlite is cleaned up when the vitest worker exits.
+    },
+});
+/**
+ * Create a pg (PostgreSQL) database factory for tests.
+ *
+ * Skipped when `test_url` is not provided.
+ * Drops `schema_version` before running `init_schema`, forcing migrations
+ * to re-evaluate against the actual tables. Prevents stale version entries
+ * from skipping migrations when DDL changes between test sessions.
+ *
+ * For full clean-slate behavior (recommended), call `drop_auth_schema(db)`
+ * at the start of `init_schema` before running migrations. This handles
+ * upstream schema changes that go beyond adding new tables/columns.
+ *
+ * @param init_schema - callback to initialize the database schema
+ * @param test_url - PostgreSQL connection URL (e.g. from `TEST_DATABASE_URL`)
+ * @returns a factory that creates pg databases
+ */
+export const create_pg_factory = (init_schema, test_url) => {
+    const should_skip = !test_url;
+    const skip_reason = !test_url ? 'TEST_DATABASE_URL not set' : undefined;
+    let pool_ref = null;
+    return {
+        name: 'pg',
+        skip: should_skip,
+        skip_reason,
+        async create() {
+            if (!test_url) {
+                throw new Error('TEST_DATABASE_URL required for pg tests.');
+            }
+            // Close any previous pool to prevent leaks on repeated create() calls.
+            // With isolate: false, the pool may have been ended by a previous file's close().
+            if (pool_ref) {
+                try {
+                    await pool_ref.end();
+                }
+                catch {
+                    // pool already ended — safe to ignore
+                }
+                pool_ref = null;
+            }
+            const { Pool } = await import('pg');
+            const pool = new Pool({ connectionString: test_url });
+            pool_ref = pool;
+            const { db } = create_pg_db(pool);
+            try {
+                // Drop schema_version so migrations re-evaluate against the actual
+                // tables. Prevents stale version entries from skipping migrations
+                // when DDL changes between test sessions. Migrations use
+                // IF NOT EXISTS guards, so re-running is safe.
+                await db.query('DROP TABLE IF EXISTS schema_version');
+                await init_schema(db);
+            }
+            catch (error) {
+                await pool.end();
+                const msg = error instanceof Error ? error.message : String(error);
+                if (msg.includes('does not exist')) {
+                    const db_name = test_url.split('/').pop()?.split('?')[0] ?? 'test_db';
+                    throw new Error(`Database "${db_name}" does not exist. Create it with: createdb ${db_name}`);
+                }
+                throw error;
+            }
+            return db;
+        },
+        async close() {
+            if (pool_ref) {
+                try {
+                    await pool_ref.end();
+                }
+                catch {
+                    // pool already ended — safe to ignore
+                }
+                pool_ref = null;
+            }
+        },
+    };
+};
+/**
+ * Auth table names in truncation order (children first for FK safety).
+ *
+ * Consumer projects can spread this into their own list and append app-specific tables.
+ */
+export const AUTH_TRUNCATE_TABLES = [
+    'invite',
+    'api_token',
+    'auth_session',
+    'permit',
+    'actor',
+    'account',
+];
+/**
+ * Auth tables including `audit_log` — for integration tests that exercise
+ * the full middleware stack (login, admin, rate limiting).
+ *
+ * Separate from `AUTH_TRUNCATE_TABLES` because unit-level DB tests that don't
+ * touch audit logging don't need to truncate it.
+ */
+export const AUTH_INTEGRATION_TRUNCATE_TABLES = [...AUTH_TRUNCATE_TABLES, 'audit_log'];
+/**
+ * All auth tables in drop order (children first for FK safety).
+ *
+ * The full set created by `AUTH_MIGRATIONS` — use for clean-slate
+ * test DB initialization. `AUTH_TRUNCATE_TABLES` is the subset for
+ * between-test data cleanup (excludes `audit_log`).
+ *
+ * When adding tables to `AUTH_MIGRATIONS`, add them here too.
+ */
+export const AUTH_DROP_TABLES = [
+    'app_settings',
+    'invite',
+    'audit_log',
+    'api_token',
+    'auth_session',
+    'permit',
+    'actor',
+    'account',
+    'bootstrap_lock',
+];
+/**
+ * Drop all auth tables and schema version tracking for a clean slate.
+ *
+ * Recommended at the start of `init_schema` callbacks for `create_pg_factory`.
+ * Persistent test databases can accumulate stale schema from previous fuz_app
+ * versions — this ensures migrations run against a truly empty database.
+ * Safe on fresh databases (`IF EXISTS` on all statements). No-op effect for
+ * PGlite (already fresh), but harmless to call unconditionally.
+ *
+ * @param db - the database to clean
+ */
+export const drop_auth_schema = async (db) => {
+    for (const table of AUTH_DROP_TABLES) {
+        await db.query(`DROP TABLE IF EXISTS ${assert_valid_sql_identifier(table)} CASCADE`); // eslint-disable-line no-await-in-loop
+    }
+    await db.query('DROP TABLE IF EXISTS schema_version CASCADE');
+};
+/**
+ * Create a `describe_db` function bound to specific factories and truncate tables.
+ *
+ * Returns a 2-arg `(name, fn)` function that runs the test suite against each
+ * factory. Each factory gets its own `describe` block with a shared database
+ * instance, automatic `beforeEach` truncation, and `afterAll` cleanup.
+ * Skipped factories use `describe.skip`.
+ *
+ * @param factories - one or more database factories to run suites against
+ * @param truncate_tables - tables to truncate between tests (children first for FK safety)
+ * @returns a `describe_db` function for use in test files
+ */
+export const create_describe_db = (factories, truncate_tables) => {
+    const factory_list = Array.isArray(factories) ? factories : [factories];
+    return (name, fn) => {
+        for (const factory of factory_list) {
+            const describe_fn = factory.skip ? describe.skip : describe;
+            describe_fn(`${name} (${factory.name})`, () => {
+                let db;
+                beforeAll(async () => {
+                    db = await factory.create();
+                });
+                beforeEach(async () => {
+                    if (db && truncate_tables.length > 0) {
+                        await db.query(`TRUNCATE ${truncate_tables.map(assert_valid_sql_identifier).join(', ')} CASCADE`);
+                    }
+                });
+                afterAll(async () => {
+                    if (db)
+                        await factory.close(db);
+                });
+                fn(() => db);
+            });
+        }
+    };
+};
+/**
+ * Log factory status to console.
+ *
+ * @param factories - the database factories to report on
+ */
+export const log_db_factory_status = (factories) => {
+    const enabled = factories.filter((f) => !f.skip).map((f) => f.name);
+    const skipped = factories.filter((f) => f.skip).map((f) => `${f.name} (${f.skip_reason})`);
+    console.log(`[db tests] drivers: ${enabled.join(', ')}${skipped.length ? ` | skipped: ${skipped.join(', ')}` : ''}`);
+};