@fuzdev/fuz_app 0.147.0 → 0.148.0

package/dist/testing/adversarial_input_cases.js

@@ -0,0 +1,348 @@
+import './assert_dev_env.js';
+/**
+ * Schema-walk generation of adversarial inputs — payloads that must fail
+ * validation.
+ *
+ * Focused cases: one representative wrong-type value per field, one format
+ * violation per constrained field, one null and one missing case per required
+ * field, plus whole-body structural attacks (non-object body, extra unknown
+ * keys). Hono-free, so the cross-process suites reuse the generators the
+ * in-process `describe_adversarial_input` and `describe_rpc_attack_surface_tests`
+ * run.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { zod_unwrap_to_object, zod_extract_fields } from '../zod.js';
+import { is_null_schema } from '../http/schema_helpers.js';
+import { ERROR_INVALID_REQUEST_BODY, ERROR_INVALID_JSON_BODY } from '../http/error_schemas.js';
+import { detect_format, generate_valid_value } from './schema_generators.js';
+// --- Payload generation ---
+/** One wrong-type value per base type — one representative is sufficient. */
+const wrong_type_for = (base_type) => {
+    switch (base_type) {
+        case 'string':
+        case 'uuid':
+        case 'email':
+            return { label: 'number instead of string', value: 42 };
+        case 'number':
+        case 'int':
+            return { label: 'string instead of number', value: 'not_a_number' };
+        case 'boolean':
+            return { label: 'number instead of boolean', value: 42 };
+        case 'array':
+            return { label: 'string instead of array', value: 'not_an_array' };
+        case 'object':
+            return { label: 'string instead of object', value: 'not_an_object' };
+        case 'enum':
+            return { label: 'number instead of enum', value: 42 };
+        default:
+            return null;
+    }
+};
+/** Format violation payloads — one per constraint type. */
+const format_violation = (format) => {
+    switch (format) {
+        case 'uuid':
+            return { label: 'malformed uuid', value: 'not-a-uuid' };
+        case 'email':
+            return { label: 'malformed email', value: 'not-an-email' };
+        case 'date-time':
+            return { label: 'malformed datetime', value: 'not-a-date' };
+        case 'pattern':
+            return { label: 'pattern violation', value: "'; DROP TABLE --" };
+        default:
+            return null;
+    }
+};
+// --- Input test case generation ---
+/**
+ * Generate adversarial test cases for a route's input schema.
+ *
+ * Produces focused, non-redundant cases:
+ * - Whole-body: send array instead of object, extra unknown key
+ * - Missing required fields (without defaults)
+ * - One wrong-type value per field
+ * - Null for required non-nullable fields
+ * - One format violation per constrained field
+ *
+ * @throws Error if the seed body built by `generate_valid_value` fails
+ *   `input_schema.safeParse` — surfaces broken generation logic with the
+ *   Zod issues path rather than producing nonsense adversarial cases.
+ */
+export const generate_input_test_cases = (input_schema) => {
+    if (is_null_schema(input_schema))
+        return [];
+    const object_schema = zod_unwrap_to_object(input_schema);
+    if (!object_schema)
+        return [];
+    const fields = zod_extract_fields(object_schema);
+    const cases = [];
+    // build a base object with valid-ish values — must pass validation itself
+    // skip optional fields without defaults to avoid generating invalid nested values
+    const base = {};
+    for (const field of fields) {
+        if (!field.required && !field.has_default)
+            continue;
+        base[field.name] = generate_valid_value(field, object_schema.shape[field.name]);
+    }
+    let base_result = input_schema.safeParse(base);
+    if (!base_result.success) {
+        // Fallback for schemas with a top-level `.refine()` that requires at
+        // least one of N optional fields. Fill optional fields until the base
+        // satisfies validation; surfaces a clear error if no combination works.
+        for (const field of fields) {
+            if (field.required || field.has_default || field.name in base)
+                continue;
+            base[field.name] = generate_valid_value(field, object_schema.shape[field.name]);
+            base_result = input_schema.safeParse(base);
+            if (base_result.success)
+                break;
+        }
+    }
+    if (!base_result.success) {
+        throw new Error(`adversarial_input: generated base object fails validation for schema — ` +
+            `fix generate_valid_value for: ${base_result.error.issues
+                .map((i) => `${i.path.join('.')}: ${i.message}`)
+                .join(', ')}`);
+    }
+    // whole-body structural: send array instead of object
+    cases.push({
+        label: 'non-object body (array)',
+        body: [1, 2, 3],
+        expected_error: ERROR_INVALID_JSON_BODY
+    });
+    // whole-body structural: extra unknown key (enforces strictObject)
+    // only emit if the schema rejects unknown keys (i.e. uses z.strictObject)
+    const extra_key_result = input_schema.safeParse({ ...base, __adversarial_extra: 'rejected' });
+    if (!extra_key_result.success) {
+        cases.push({
+            label: 'extra unknown key',
+            body: { ...base, __adversarial_extra: 'should_be_rejected' },
+            expected_error: ERROR_INVALID_REQUEST_BODY
+        });
+    }
+    for (const field of fields) {
+        const field_schema = object_schema.shape[field.name];
+        // missing required field (skip fields with defaults — Zod fills them)
+        if (field.required && !field.has_default) {
+            const without = {};
+            for (const [k, v] of Object.entries(base)) {
+                if (k !== field.name)
+                    without[k] = v;
+            }
+            cases.push({
+                label: `missing: ${field.name}`,
+                body: without,
+                expected_error: ERROR_INVALID_REQUEST_BODY
+            });
+        }
+        // one wrong-type value
+        const wrong = wrong_type_for(field.base_type);
+        if (wrong) {
+            cases.push({
+                label: `wrong type: ${field.name} (${wrong.label})`,
+                body: { ...base, [field.name]: wrong.value },
+                expected_error: ERROR_INVALID_REQUEST_BODY
+            });
+        }
+        // null for required non-nullable fields
+        if (field.required && !field.nullable && field.base_type !== 'null') {
+            cases.push({
+                label: `null: ${field.name}`,
+                body: { ...base, [field.name]: null },
+                expected_error: ERROR_INVALID_REQUEST_BODY
+            });
+        }
+        // format violation for constrained string fields
+        const format = detect_format(field_schema);
+        if (format) {
+            const violation = format_violation(format);
+            if (violation) {
+                cases.push({
+                    label: `format: ${field.name} (${violation.label})`,
+                    body: { ...base, [field.name]: violation.value },
+                    expected_error: ERROR_INVALID_REQUEST_BODY
+                });
+            }
+        }
+        // --- Boundary cases via JSON Schema introspection ---
+        try {
+            const json = z.toJSONSchema(field_schema);
+            // string length boundaries
+            if (field.base_type === 'string' ||
+                field.base_type === 'uuid' ||
+                field.base_type === 'email') {
+                if (typeof json.minLength === 'number' && json.minLength > 0) {
+                    cases.push({
+                        label: `empty string: ${field.name}`,
+                        body: { ...base, [field.name]: '' },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+                if (typeof json.maxLength === 'number') {
+                    cases.push({
+                        label: `over maxLength: ${field.name} (${json.maxLength + 1} chars)`,
+                        body: { ...base, [field.name]: 'x'.repeat(json.maxLength + 1) },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+            }
+            // numeric boundaries
+            if (field.base_type === 'number' || field.base_type === 'int') {
+                if (typeof json.minimum === 'number') {
+                    cases.push({
+                        label: `below minimum: ${field.name} (${json.minimum - 1})`,
+                        body: { ...base, [field.name]: json.minimum - 1 },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+                if (typeof json.maximum === 'number') {
+                    cases.push({
+                        label: `above maximum: ${field.name} (${json.maximum + 1})`,
+                        body: { ...base, [field.name]: json.maximum + 1 },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+                if (typeof json.exclusiveMinimum === 'number') {
+                    cases.push({
+                        label: `at exclusive minimum: ${field.name} (${json.exclusiveMinimum})`,
+                        body: { ...base, [field.name]: json.exclusiveMinimum },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+                if (typeof json.exclusiveMaximum === 'number') {
+                    cases.push({
+                        label: `at exclusive maximum: ${field.name} (${json.exclusiveMaximum})`,
+                        body: { ...base, [field.name]: json.exclusiveMaximum },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+                // 0 and negative for positive-only fields
+                if (typeof json.minimum === 'number' && json.minimum > 0) {
+                    cases.push({
+                        label: `zero for positive-only: ${field.name}`,
+                        body: { ...base, [field.name]: 0 },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                    cases.push({
+                        label: `negative for positive-only: ${field.name}`,
+                        body: { ...base, [field.name]: -1 },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+            }
+            // array length boundaries
+            if (field.base_type === 'array') {
+                if (typeof json.minItems === 'number' && json.minItems > 0) {
+                    cases.push({
+                        label: `empty array for minItems > 0: ${field.name}`,
+                        body: { ...base, [field.name]: [] },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+                if (typeof json.maxItems === 'number') {
+                    // generate an array one item over the max (items are null — schema-agnostic)
+                    cases.push({
+                        label: `over maxItems: ${field.name} (${json.maxItems + 1} items)`,
+                        body: { ...base, [field.name]: Array.from({ length: json.maxItems + 1 }, () => null) },
+                        expected_error: ERROR_INVALID_REQUEST_BODY
+                    });
+                }
+            }
+        }
+        catch {
+            // schema can't be converted to JSON Schema, skip boundary cases
+        }
+    }
+    return cases;
+};
+// --- Params test case generation ---
+/**
+ * Generate adversarial test cases for a route's params schema.
+ *
+ * Params are always strings from URL segments. Only generates cases for
+ * format-constrained fields (uuid, pattern) since unconstrained string
+ * params accept any string value.
+ */
+export const generate_params_test_cases = (params_schema) => {
+    const fields = zod_extract_fields(params_schema);
+    const cases = [];
+    // build base params with valid-ish values
+    const base_params = {};
+    for (const field of fields) {
+        const field_schema = params_schema.shape[field.name];
+        const format = detect_format(field_schema);
+        if (format === 'uuid' || field.base_type === 'uuid') {
+            base_params[field.name] = '00000000-0000-0000-0000-000000000000';
+        }
+        else {
+            base_params[field.name] = 'test_value';
+        }
+    }
+    for (const field of fields) {
+        const field_schema = params_schema.shape[field.name];
+        const format = detect_format(field_schema);
+        if (!format)
+            continue; // unconstrained string — any value passes
+        const violation = format_violation(format);
+        if (violation) {
+            cases.push({
+                label: `${violation.label}: param ${field.name}`,
+                params: { ...base_params, [field.name]: violation.value }
+            });
+        }
+    }
+    return cases;
+};
+// --- Query test case generation ---
+/**
+ * Generate adversarial test cases for a route's query schema.
+ *
+ * Query params are always strings from the URL. Generates cases for:
+ * - Missing required fields
+ * - Format violations on constrained fields (uuid, pattern)
+ */
+export const generate_query_test_cases = (query_schema) => {
+    const fields = zod_extract_fields(query_schema);
+    const cases = [];
+    // build base query with valid-ish values
+    const base_query = {};
+    for (const field of fields) {
+        const field_schema = query_schema.shape[field.name];
+        const format = detect_format(field_schema);
+        if (format === 'uuid' || field.base_type === 'uuid') {
+            base_query[field.name] = '00000000-0000-0000-0000-000000000000';
+        }
+        else {
+            base_query[field.name] = 'test_value';
+        }
+    }
+    for (const field of fields) {
+        // missing required field
+        if (field.required && !field.has_default) {
+            const without = {};
+            for (const [k, v] of Object.entries(base_query)) {
+                if (k !== field.name)
+                    without[k] = v;
+            }
+            cases.push({
+                label: `missing query: ${field.name}`,
+                query: without
+            });
+        }
+        // format violation for constrained string fields
+        const field_schema = query_schema.shape[field.name];
+        const format = detect_format(field_schema);
+        if (!format)
+            continue;
+        const violation = format_violation(format);
+        if (violation) {
+            cases.push({
+                label: `${violation.label}: query ${field.name}`,
+                query: { ...base_query, [field.name]: violation.value }
+            });
+        }
+    }
+    return cases;
+};

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

@@ -1 +1 @@
-{"version":3,"file":"audit_completeness.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/audit_completeness.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA4B7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAUhE,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AA2B1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,0BAA0B,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,yEAAyE;IACzE,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC;;;OAGG;IACH,aAAa,EAAE,uBAAuB,CAAC;CACvC;AAgGD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iCAAiC,GAAI,SAAS,4BAA4B,KAAG,IAgnBzF,CAAC"}
+{"version":3,"file":"audit_completeness.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/audit_completeness.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AA4B7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAUhE,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AA2B1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,0BAA0B,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC5C;;;;;OAKG;IACH,UAAU,EAAE,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,yEAAyE;IACzE,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC;;;OAGG;IACH,aAAa,EAAE,uBAAuB,CAAC;CACvC;AAoGD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iCAAiC,GAAI,SAAS,4BAA4B,KAAG,IAgnBzF,CAAC"}

package/dist/testing/audit_completeness.js

@@ -54,8 +54,12 @@ const create_admin_observer = (fixture) => fixture.create_account({ username: 'a
  * `observer` is a dedicated admin account (see `create_admin_observer`)
  * — its credentials are never the subject of the mutation under test, so the
  * read works uniformly across every flow including session-revoking ones.
+ *
+ * In-process only, so no drain precedes the read (`create_test_app` settles a
+ * request's effects before it responds) — the cross-process reader is
+ * `cross_backend/audit_cross_helpers.ts`'s `list_audit_events`.
  */
-const list_audit_events = async (app, rpc_path, observer, params = {}) => {
+const read_audit_log = async (app, rpc_path, observer, params = {}) => {
     const res = await rpc_call_for_spec({
         app,
         path: rpc_path,
@@ -128,7 +132,7 @@ export const describe_audit_completeness_tests = (options) => {
                     })
                 });
                 assert.strictEqual(res.status, 200);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'login', 'POST /login (success)');
             });
             test('login failure produces login event with failure outcome', async () => {
@@ -145,7 +149,7 @@ export const describe_audit_completeness_tests = (options) => {
                     })
                 });
                 assert.strictEqual(res.status, 401);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'login', 'POST /login (failure)');
             });
             test('logout produces logout event', async () => {
@@ -158,7 +162,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers({ 'content-type': 'application/json' })
                 });
                 assert.strictEqual(res.status, 200);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'logout', 'POST /logout');
             });
             test('token create produces token_create event', async () => {
@@ -176,7 +180,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `account_token_create failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'token_create', 'account_token_create RPC');
                 assert_event_credential_type(events, 'token_create', 'session', 'account_token_create RPC');
             });
@@ -202,7 +206,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `account_token_revoke failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'token_revoke', 'account_token_revoke RPC');
                 assert_event_credential_type(events, 'token_revoke', 'session', 'account_token_revoke RPC');
             });
@@ -242,7 +246,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `account_session_revoke failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'session_revoke', 'account_session_revoke RPC');
                 assert_event_credential_type(events, 'session_revoke', 'session', 'account_session_revoke RPC');
             });
@@ -257,7 +261,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `account_session_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'session_revoke_all', 'account_session_revoke_all RPC');
                 assert_event_credential_type(events, 'session_revoke_all', 'session', 'account_session_revoke_all RPC');
             });
@@ -275,7 +279,7 @@ export const describe_audit_completeness_tests = (options) => {
                     })
                 });
                 assert.strictEqual(res.status, 200);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'password_change', 'POST /password');
                 assert_event_credential_type(events, 'password_change', 'session', 'POST /password');
             });
@@ -298,7 +302,7 @@ export const describe_audit_completeness_tests = (options) => {
                 // Admin offer emits `role_grant_offer_create` only — the role_grant doesn't
                 // exist yet. Drive the accept to confirm `role_grant_offer_accept` and
                 // `role_grant_create` both fire on the downstream consent transition.
-                const events_after_offer = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events_after_offer = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events_after_offer, 'role_grant_offer_create', 'role_grant_offer_create RPC');
                 const accept_res = await rpc_call_for_spec({
                     app: { request: fixture.transport },
@@ -308,7 +312,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: target.create_session_headers()
                 });
                 assert.ok(accept_res.ok, `role_grant_offer_accept failed: ${accept_res.ok ? '' : JSON.stringify(accept_res.error)}`);
-                const events_after_accept = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events_after_accept = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events_after_accept, 'role_grant_offer_accept', 'offer accept RPC');
                 assert_has_event(events_after_accept, 'role_grant_create', 'offer accept RPC');
             });
@@ -335,7 +339,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(revoke_res.ok, `role_grant_revoke failed: ${revoke_res.ok ? '' : JSON.stringify(revoke_res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'role_grant_revoke', 'role_grant_revoke RPC');
                 // Audit envelope must populate both target columns —
                 // `role_grant_revoke` is the canonical actor-bound-subject event.
@@ -357,7 +361,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `admin_session_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 // admin session revoke-all also produces session_revoke_all
                 assert_has_event(events, 'session_revoke_all', 'admin_session_revoke_all RPC');
             });
@@ -373,7 +377,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `admin_token_revoke_all failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'token_revoke_all', 'admin_token_revoke_all RPC');
             });
         });
@@ -399,7 +403,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(delete_res.ok, `invite_delete failed: ${delete_res.ok ? '' : JSON.stringify(delete_res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'invite_create', 'invite_create RPC');
                 assert_has_event(events, 'invite_delete', 'invite_delete RPC');
             });
@@ -417,7 +421,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `app_settings_update failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'app_settings_update', 'app_settings_update RPC');
             });
         });
@@ -435,7 +439,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `account_delete failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'account_delete', 'account_delete RPC');
                 assert_has_event(events, 'actor_delete', 'account_delete RPC (per-actor cascade)');
             });
@@ -455,7 +459,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_daemon_token_headers()
                 });
                 assert.ok(res.ok, `account_purge failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'account_purge', 'account_purge RPC');
                 assert_has_event(events, 'actor_purge', 'account_purge RPC (per-actor cascade)');
             });
@@ -479,7 +483,7 @@ export const describe_audit_completeness_tests = (options) => {
                     headers: fixture.create_session_headers()
                 });
                 assert.ok(res.ok, `account_undelete failed: ${res.ok ? '' : JSON.stringify(res.error)}`);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'account_undelete', 'account_undelete RPC');
                 assert_has_event(events, 'actor_undelete', 'account_undelete RPC (per-actor cascade)');
             });
@@ -514,7 +518,7 @@ export const describe_audit_completeness_tests = (options) => {
                     })
                 });
                 assert.strictEqual(res.status, 200);
-                const events = await list_audit_events({ request: fixture.transport }, rpc_path, observer);
+                const events = await read_audit_log({ request: fixture.transport }, rpc_path, observer);
                 assert_has_event(events, 'signup', 'POST /signup');
             });
         });

package/dist/testing/audit_drift_guard.d.ts

@@ -1,6 +1,6 @@
 import './assert_dev_env.js';
 import { type AuditEmitter } from '../auth/audit_emitter.js';
-import type { AuditLogInput } from '../auth/audit_log_schema.js';
+import { type AuditLogEventJson, type AuditLogInput } from '../auth/audit_log_schema.js';
 /**
  * Register per-test `beforeEach` + `afterEach` hooks that catch any audit
  * emission with a metadata shape that fails its `audit_metadata_schemas`
@@ -81,4 +81,30 @@ export interface RecordingAuditEmitter {
  * so the freeze isn't load-bearing here.
  */
 export declare const create_recording_audit_emitter: (calls_ref?: Array<AuditLogInput>) => RecordingAuditEmitter;
+/** Options for `assert_audit_event_metadata`. */
+export interface AssertAuditEventMetadataOptions {
+    /**
+     * Refuse metadata keys the event type doesn't declare. Off by default: the
+     * builtin schemas admit consumer-added fields. For a suite whose backend
+     * adds none — a spine's own — so an undeclared key on any spine fails.
+     */
+    readonly reject_unknown_keys?: boolean;
+}
+/**
+ * Assert an audit row read off the wire carries the metadata its event type
+ * declares — parsed against `audit_metadata_schemas[event_type]` as declared,
+ * so a mistyped, `null`, or missing field fails, and with
+ * `reject_unknown_keys` so does a key the event doesn't declare. The wire
+ * schema (`AuditLogEventJson.metadata`) is a loose record, and only the TS
+ * spine validates metadata, at insert and fail-open, so this is the check that
+ * holds a spine's rows to their event's contract.
+ *
+ * Builtin event types only: a consumer-registered type has no entry here, and
+ * passes unexamined.
+ *
+ * @param event - an audit row from `audit_log_list` or an audit read like it
+ * @param options - `reject_unknown_keys` for the closed-world check
+ * @throws AssertionError naming the event type and the schema issues
+ */
+export declare const assert_audit_event_metadata: (event: Pick<AuditLogEventJson, "event_type" | "outcome" | "metadata">, options?: AssertAuditEventMetadataOptions) => void;
 //# sourceMappingURL=audit_drift_guard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"audit_drift_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/audit_drift_guard.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAU7B,OAAO,EAGN,KAAK,YAAY,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAO5C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAO,IAgBxC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,8BAA8B,GAC1C,YAAY,KAAK,CAAC,aAAa,CAAC,KAC9B,qBAqCF,CAAC"}
+{"version":3,"file":"audit_drift_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/audit_drift_guard.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAW7B,OAAO,EAGN,KAAK,YAAY,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGN,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAO5C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAO,IAgBxC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,8BAA8B,GAC1C,YAAY,KAAK,CAAC,aAAa,CAAC,KAC9B,qBAqCF,CAAC;AA2BF,iDAAiD;AACjD,MAAM,WAAW,+BAA+B;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,GACvC,OAAO,IAAI,CAAC,iBAAiB,EAAE,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC,EACrE,UAAU,+BAA+B,KACvC,IAcF,CAAC"}

package/dist/testing/audit_drift_guard.js

@@ -1,7 +1,9 @@
 import './assert_dev_env.js';
 import { assert, beforeEach, afterEach } from 'vitest';
+import { z } from 'zod';
 import { get_audit_metadata_validation_failures, get_audit_unknown_event_type_failures, reset_audit_metadata_validation_failures, reset_audit_unknown_event_type_failures } from '../auth/audit_log_queries.js';
 import { get_audit_write_failures, reset_audit_write_failures } from '../auth/audit_emitter.js';
+import { audit_metadata_schemas } from '../auth/audit_log_schema.js';
 /**
  * Register per-test `beforeEach` + `afterEach` hooks that catch any audit
  * emission with a metadata shape that fails its `audit_metadata_schemas`
@@ -120,3 +122,51 @@ export const create_recording_audit_emitter = (calls_ref) => {
     };
     return { emitter, calls };
 };
+/**
+ * The closed-world twin of a builtin event's `audit_metadata_schemas` entry:
+ * the same fields, with unknown keys refused. The registry's schemas are
+ * `z.looseObject` so a consumer can add fields to a builtin event (a builtin's
+ * schema can't be overridden), so this is opt-in.
+ */
+const to_closed_metadata_schema = (schema) => {
+    if (schema instanceof z.ZodNullable) {
+        return to_closed_metadata_schema(schema.unwrap()).nullable();
+    }
+    if (schema instanceof z.ZodObject)
+        return z.strictObject(schema.shape);
+    return schema;
+};
+const declared_metadata_schemas = new Map(Object.entries(audit_metadata_schemas));
+const closed_metadata_schemas = new Map(Object.entries(audit_metadata_schemas).map(([event_type, schema]) => [
+    event_type,
+    to_closed_metadata_schema(schema)
+]));
+/**
+ * Assert an audit row read off the wire carries the metadata its event type
+ * declares — parsed against `audit_metadata_schemas[event_type]` as declared,
+ * so a mistyped, `null`, or missing field fails, and with
+ * `reject_unknown_keys` so does a key the event doesn't declare. The wire
+ * schema (`AuditLogEventJson.metadata`) is a loose record, and only the TS
+ * spine validates metadata, at insert and fail-open, so this is the check that
+ * holds a spine's rows to their event's contract.
+ *
+ * Builtin event types only: a consumer-registered type has no entry here, and
+ * passes unexamined.
+ *
+ * @param event - an audit row from `audit_log_list` or an audit read like it
+ * @param options - `reject_unknown_keys` for the closed-world check
+ * @throws AssertionError naming the event type and the schema issues
+ */
+export const assert_audit_event_metadata = (event, options) => {
+    const schema = (options?.reject_unknown_keys ? closed_metadata_schemas : declared_metadata_schemas).get(event.event_type);
+    if (!schema)
+        return;
+    const parsed = schema.safeParse(event.metadata);
+    if (parsed.success)
+        return;
+    assert.fail(`audit row ${event.event_type} (outcome=${event.outcome}) carries metadata outside its ` +
+        `audit_metadata_schemas entry: ${JSON.stringify(event.metadata)} — ` +
+        parsed.error.issues
+            .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('; '));
+};

package/dist/testing/cross_backend/account_lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account_lifecycle.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/account_lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuC9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;GAKG;AACH,MAAM,MAAM,gCAAgC,GAAG,uCAAuC,CAAC;AAEvF,eAAO,MAAM,sCAAsC,GAClD,SAAS,gCAAgC,KACvC,IAqZF,CAAC"}
+{"version":3,"file":"account_lifecycle.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/account_lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuC9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E;;;;;GAKG;AACH,MAAM,MAAM,gCAAgC,GAAG,uCAAuC,CAAC;AAEvF,eAAO,MAAM,sCAAsC,GAClD,SAAS,gCAAgC,KACvC,IAwaF,CAAC"}