@fuzdev/fuz_app 0.147.0 → 0.149.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"adversarial_input_cases.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_input_cases.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAmE/F,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,0BAA0B,GAAG,OAAO,uBAAuB,CAAC;CACnF;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAID,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,yBAAyB,GACrC,cAAc,CAAC,CAAC,OAAO,EACvB,UAAU,oBAAoB,KAC5B,KAAK,CAAC,aAAa,CAmOrB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,cAAc,CAAC,CAAC,OAAO,EACvB,WAAW,aAAa,KACtB,MAAM,GAAG,SAG+C,CAAC;AAkC5D;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GAAI,eAAe,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,cAAc,CAoB3F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CAkCxF,CAAC"}

package/dist/testing/adversarial_input_cases.js

@@ -0,0 +1,393 @@
+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 { resolve_invalid_reason } from '../schema_meta.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, detect_json_schema_format, format_zod_issues, generate_valid_object, generate_valid_object_with_field, generate_valid_string_param, to_field_json_schema } 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;
+    }
+};
+/**
+ * `value` moved by `step`, up when that stays inside the field's numeric range
+ * and down otherwise — a number off the integer or `multipleOf` grid that
+ * still meets the range, so the grid check is the one a refusal names.
+ */
+const off_grid_in_range = (json, value, step) => {
+    const up = value + step;
+    const over = (typeof json.maximum === 'number' && up > json.maximum) ||
+        (typeof json.exclusiveMaximum === 'number' && up >= json.exclusiveMaximum);
+    return over ? value - step : up;
+};
+/**
+ * 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
+ * - String length (empty, one under `minLength`, one over `maxLength`), numeric
+ *   (out of range, non-integer, off a `multipleOf` grid) and array-length
+ *   (empty, one under `minItems`, one over `maxItems`) boundaries
+ *
+ * Format and boundaries come from the field's input-side JSON Schema
+ * (`to_field_json_schema`), so a field carrying a `.transform()` or pipe and a
+ * `.nullable()` / `.nullish()` field get them too. A bound only a `.refine()`
+ * enforces generates nothing — JSON Schema can't express it.
+ *
+ * Each per-field case is single-fault: valid except for the field it breaks.
+ * It changes one field of a valid base body — `options.base` when given, else
+ * one built by `generate_valid_object` — or, for a field that base omits, of
+ * the valid body `generate_valid_object_with_field` builds around it, so a case
+ * can't also break an object-level rule (adding `scope_kind` without its
+ * paired `scope_id`, or `slug` beside an exactly-one-of `id`). A field no valid
+ * body carries keeps its wrong-type and null cases on the base and gets no
+ * format or boundary cases, which would test no bound. A per-field case is
+ * emitted only when the field refuses its value, so no case is accidentally
+ * valid.
+ *
+ * @param input_schema - the input schema to attack
+ * @param options - a base body to seed the cases, and a label for errors
+ * @throws Error if the base body fails `input_schema.safeParse` — a seeded
+ *   base the schema refuses, or a generated one that surfaces broken
+ *   generation logic — naming the issues rather than producing nonsense
+ *   adversarial cases.
+ */
+export const generate_input_test_cases = (input_schema, options) => {
+    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 = [];
+    const for_label = options?.label === undefined ? '' : ` for '${options.label}'`;
+    // the base object every case breaks one field of — must pass validation itself
+    let base;
+    if (options?.base) {
+        base = { ...options.base };
+        const base_result = input_schema.safeParse(base);
+        if (!base_result.success) {
+            throw new Error(`adversarial_input: the seeded base${for_label} fails validation — ` +
+                `fix the base for: ${format_zod_issues(base_result.error)}`);
+        }
+    }
+    else {
+        const generated = generate_valid_object(object_schema, input_schema);
+        if (!generated.result.success) {
+            throw new Error(`adversarial_input: generated base object fails validation${for_label} — ` +
+                `fix generate_valid_value for: ${format_zod_issues(generated.result.error)}`);
+        }
+        base = generated.value;
+    }
+    // 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];
+        // the valid body every case on this field changes only the field of: the
+        // base, or for a field the base omits, one that carries it — so the case
+        // can't also break an object-level rule (exactly one of, both or neither)
+        const field_base = generate_valid_object_with_field(object_schema, input_schema, base, field);
+        // every per-field case breaks the field, so the field itself must refuse
+        // its value — a candidate it accepts (a `z.coerce` field given a wrong
+        // type, a pattern that admits the violation string) is no invalid case.
+        // A type case (wrong type, null) on a field no valid body carries falls
+        // back to the base; a value case — a format or a bound — is built only on
+        // a body that is valid but for the field, or it tests no bound at all
+        const push_field_case = (label, value, kind) => {
+            if (field_schema.safeParse(value).success)
+                return;
+            const body_base = field_base ?? (kind === 'type' ? base : null);
+            if (!body_base)
+                return;
+            cases.push({
+                label,
+                body: { ...body_base, [field.name]: value },
+                field: field.name,
+                expected_error: ERROR_INVALID_REQUEST_BODY
+            });
+        };
+        // the field's valid value the value cases start from
+        const valid_value = field_base?.[field.name];
+        // missing required field (skip fields with defaults — Zod fills them)
+        if (field.required && !field.has_default && !field_schema.safeParse(undefined).success) {
+            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,
+                field: field.name,
+                expected_error: ERROR_INVALID_REQUEST_BODY
+            });
+        }
+        // one wrong-type value
+        const wrong = wrong_type_for(field.base_type);
+        if (wrong)
+            push_field_case(`wrong type: ${field.name} (${wrong.label})`, wrong.value, 'type');
+        // null for required non-nullable fields
+        if (field.required && !field.nullable && field.base_type !== 'null') {
+            push_field_case(`null: ${field.name}`, null, 'type');
+        }
+        // the field's input-side JSON Schema — format, pattern and bounds, read
+        // through a transform or pipe and under a nullable's `anyOf`
+        const json = to_field_json_schema(field_schema);
+        if (!json || !field_base)
+            continue; // no constraints, or no body to break them on
+        // format violation for constrained string fields
+        const format = detect_json_schema_format(json);
+        if (format) {
+            const violation = format_violation(format);
+            if (violation) {
+                push_field_case(`format: ${field.name} (${violation.label})`, violation.value, 'value');
+            }
+        }
+        // string length boundaries — `x`s are one UTF-16 unit and one code point
+        // each, so the over-`maxLength` string is over in either count
+        if (field.base_type === 'string' || field.base_type === 'uuid' || field.base_type === 'email') {
+            if (typeof json.minLength === 'number' && json.minLength > 0) {
+                push_field_case(`empty string: ${field.name}`, '', 'value');
+            }
+            // one short of the minimum, distinct from the empty string — a prefix of
+            // the valid value where there is one, so a pattern it met still holds
+            if (typeof json.minLength === 'number' && json.minLength > 1) {
+                const under = json.minLength - 1;
+                push_field_case(`under minLength: ${field.name} (${under} chars)`, typeof valid_value === 'string' && valid_value.length >= under
+                    ? valid_value.slice(0, under)
+                    : 'x'.repeat(under), 'value');
+            }
+            if (typeof json.maxLength === 'number') {
+                push_field_case(`over maxLength: ${field.name} (${json.maxLength + 1} chars)`, 'x'.repeat(json.maxLength + 1), 'value');
+            }
+        }
+        // numeric boundaries
+        if (field.base_type === 'number' || field.base_type === 'int') {
+            if (typeof json.minimum === 'number') {
+                push_field_case(`below minimum: ${field.name} (${json.minimum - 1})`, json.minimum - 1, 'value');
+            }
+            if (typeof json.maximum === 'number') {
+                push_field_case(`above maximum: ${field.name} (${json.maximum + 1})`, json.maximum + 1, 'value');
+            }
+            if (typeof json.exclusiveMinimum === 'number') {
+                push_field_case(`at exclusive minimum: ${field.name} (${json.exclusiveMinimum})`, json.exclusiveMinimum, 'value');
+            }
+            if (typeof json.exclusiveMaximum === 'number') {
+                push_field_case(`at exclusive maximum: ${field.name} (${json.exclusiveMaximum})`, json.exclusiveMaximum, 'value');
+            }
+            // 0 and negative for positive-only fields
+            if (typeof json.minimum === 'number' && json.minimum > 0) {
+                push_field_case(`zero for positive-only: ${field.name}`, 0, 'value');
+                push_field_case(`negative for positive-only: ${field.name}`, -1, 'value');
+            }
+            // off the grid by half a step from the valid value, inside the range,
+            // so the integer or `multipleOf` check is the one that refuses
+            const valid_number = typeof valid_value === 'number' ? valid_value : 1;
+            if (json.type === 'integer') {
+                const value = off_grid_in_range(json, valid_number, 0.5);
+                push_field_case(`non-integer: ${field.name} (${value})`, value, 'value');
+            }
+            if (typeof json.multipleOf === 'number' && json.multipleOf > 0) {
+                // a whole step for an integer field, so the integer check still holds
+                const step = json.type === 'integer' && json.multipleOf > 1 ? 1 : json.multipleOf / 2;
+                const value = off_grid_in_range(json, valid_number, step);
+                push_field_case(`not multipleOf: ${field.name} (${value}, multipleOf ${json.multipleOf})`, value, 'value');
+            }
+        }
+        // array length boundaries
+        if (field.base_type === 'array') {
+            if (typeof json.minItems === 'number' && json.minItems > 0) {
+                push_field_case(`empty array for minItems > 0: ${field.name}`, [], 'value');
+            }
+            // one short of the minimum, distinct from the empty array — the valid
+            // value's own items, so only the count is wrong
+            if (typeof json.minItems === 'number' &&
+                json.minItems > 1 &&
+                Array.isArray(valid_value) &&
+                valid_value.length >= json.minItems - 1) {
+                push_field_case(`under minItems: ${field.name} (${json.minItems - 1} items)`, valid_value.slice(0, json.minItems - 1), 'value');
+            }
+            if (typeof json.maxItems === 'number') {
+                // one item over the max (items are null — schema-agnostic)
+                push_field_case(`over maxItems: ${field.name} (${json.maxItems + 1} items)`, Array.from({ length: json.maxItems + 1 }, () => null), 'value');
+            }
+        }
+    }
+    return cases;
+};
+/**
+ * The `error.data.reason` an RPC refusal of `test_case` owes: the declared
+ * `invalid_reason` of the field it breaks, resolved as the dispatcher resolves
+ * a failure on that field (`resolve_invalid_reason`), or `undefined` — no
+ * reason — for an undeclared field or a whole-body case.
+ *
+ * @param input_schema - the input schema the case was generated from
+ * @param test_case - a case `generate_input_test_cases` produced from it
+ * @returns the owed reason, or `undefined` when the refusal carries none
+ */
+export const expected_invalid_reason = (input_schema, test_case) => test_case.field === undefined
+    ? undefined
+    : resolve_invalid_reason(input_schema, [test_case.field]);
+// --- Params and query test case generation ---
+/**
+ * A valid string record for a route's params or query schema — each field the
+ * string `generate_valid_string_param` finds for it — checked against the
+ * whole schema, so a case changing one field breaks that field only.
+ *
+ * @throws Error if a field has no string it accepts, or the record fails the
+ *   schema, naming the issues
+ */
+const generate_string_record_base = (schema, kind) => {
+    const base = {};
+    for (const field of zod_extract_fields(schema)) {
+        const value = generate_valid_string_param(field, schema.shape[field.name]);
+        if (value === null) {
+            throw new Error(`adversarial_input: no generated ${kind} value passes field '${field.name}'`);
+        }
+        base[field.name] = value;
+    }
+    const result = schema.safeParse(base);
+    if (!result.success) {
+        throw new Error(`adversarial_input: generated ${kind} base fails validation — ` +
+            `fix generate_valid_string_param for: ${format_zod_issues(result.error)}`);
+    }
+    return base;
+};
+/**
+ * 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, and only a violation the field refuses.
+ * Each case breaks one field of a valid params record.
+ *
+ * @throws Error if no valid params record can be generated
+ */
+export const generate_params_test_cases = (params_schema) => {
+    const fields = zod_extract_fields(params_schema);
+    const cases = [];
+    const base_params = generate_string_record_base(params_schema, 'params');
+    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 && !field_schema.safeParse(violation.value).success) {
+            cases.push({
+                label: `${violation.label}: param ${field.name}`,
+                params: { ...base_params, [field.name]: violation.value }
+            });
+        }
+    }
+    return cases;
+};
+/**
+ * Generate adversarial test cases for a route's query schema.
+ *
+ * Query params are always strings from the URL. Generates cases for:
+ * - Missing required fields the field refuses to go without (a preprocessed
+ *   field with a default accepts its absence)
+ * - Format violations on constrained fields (uuid, pattern) the field refuses
+ *
+ * Each case breaks one field of a valid query record.
+ *
+ * @throws Error if no valid query record can be generated
+ */
+export const generate_query_test_cases = (query_schema) => {
+    const fields = zod_extract_fields(query_schema);
+    const cases = [];
+    const base_query = generate_string_record_base(query_schema, 'query');
+    for (const field of fields) {
+        const field_schema = query_schema.shape[field.name];
+        // missing required field
+        if (field.required && !field.has_default && !field_schema.safeParse(undefined).success) {
+            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 format = detect_format(field_schema);
+        if (!format)
+            continue;
+        const violation = format_violation(format);
+        if (violation && !field_schema.safeParse(violation.value).success) {
+            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`
@@ -61,8 +61,9 @@ export interface RecordingAuditEmitter {
  * `notify` is a no-op; `add_listener` records into a local array that
  * `listener_count` reports, and returns a remover with the production
  * semantics (per registration, idempotent) — registered listeners never fire,
- * since this emitter captures `emit` shapes, not fan-out. `drain_inflight` resolves at once:
- * a recorded call writes nothing, so nothing is ever in flight.
+ * since this emitter captures `emit` shapes, not fan-out. `drain_inflight` resolves at once
+ * and `is_tracking_inflight` answers `false`: a recorded call writes nothing, so nothing is
+ * ever in flight.
  *
  * `emit` AND `emit_pool` both append to `calls`, so a test reads either
  * entry point's writes off the same array.
@@ -81,4 +82,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,8BAA8B,GAC1C,YAAY,KAAK,CAAC,aAAa,CAAC,KAC9B,qBAsCF,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"}