@nifrajs/testing 4.0.2 → 5.0.0

package/dist/adversarial.js

@@ -7,14 +7,34 @@
  * responses are validated off the hot path as part of the same laboratory run.
  */
 import { compileRoutePattern, } from "@nifrajs/core/pattern";
-import { reflectRoutes, } from "@nifrajs/core/reflection";
-import { autoReflectJsonSchema, generateMockValue } from "@nifrajs/mock";
+import { reflectMounts, reflectRoutes, } from "@nifrajs/core/reflection";
+import { autoReflectJsonSchema, explainAutoReflectJsonSchema, generateMockValue, } from "@nifrajs/mock";
 const DEFAULT_ORIGIN = "http://nifra.contract";
 const DEFAULT_SEED = 0x4e_49_46_52;
 const DEFAULT_MAX_MUTATIONS = 32;
 const DEFAULT_MAX_SHRINK_ATTEMPTS = 12;
 const DEFAULT_MAX_WITNESS_BYTES = 256 * 1024;
 const NO_BODY_METHODS = new Set(["GET", "HEAD"]);
+/** In the order a route validates them, so the first input that cannot resolve is the one named. */
+const INPUT_TARGETS = ["headers", "params", "body", "query"];
+/**
+ * Header names the harness never invents or mutates: a credential belongs to the witness or
+ * `prepareRequest`, and the rest are owned by the fetch runtime.
+ */
+const CREDENTIAL_HEADER = /^(?:authorization|proxy-authorization|cookie|x-api-key)$|-key$|token|secret|signature/;
+const RUNTIME_HEADERS = new Set([
+    "connection",
+    "content-length",
+    "expect",
+    "host",
+    "keep-alive",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 export class AdversarialContractError extends Error {
     report;
     constructor(report) {
@@ -228,15 +248,29 @@ async function rejectedByValidator(reflection, value) {
     const result = await validator["~standard"].validate(value);
     return result.issues !== undefined;
 }
-async function provenMutations(input, target, maxMutations) {
+/**
+ * Validator-proven hostile values for one input. A header mutation touches only a field the harness
+ * owns, and an extra header proves nothing (servers tolerate them). `constrained` reports whether any
+ * transportable candidate came from a schema constraint rather than a bare type swap: a params or
+ * headers validator that accepts every type swap may simply accept any text.
+ */
+async function provenMutations(input, target, maxMutations, paramNames) {
     const candidates = candidateMutations(input.value, input.reflection.jsonSchema, maxMutations);
     const mutations = [];
     const seen = new Set();
+    let constrained = false;
     for (const candidate of candidates) {
+        if (target === "headers") {
+            const name = candidate.path[0];
+            if (typeof name !== "string" || !harnessOwnsHeader(name))
+                continue;
+            if (candidate.reason === "additional-property")
+                continue;
+        }
         let serialized;
         let value;
         try {
-            value = target === "query" ? queryInput(candidate.value) : jsonClone(candidate.value);
+            value = transported(target, candidate.value, paramNames);
             if (value === undefined)
                 continue;
             serialized = JSON.stringify(value);
@@ -247,6 +281,8 @@ async function provenMutations(input, target, maxMutations) {
         if (seen.has(serialized))
             continue;
         seen.add(serialized);
+        if (!candidate.reason.startsWith("wrong-type-"))
+            constrained = true;
         try {
             if (await rejectedByValidator(input.reflection, value))
                 mutations.push({ ...candidate, value });
@@ -258,7 +294,102 @@ async function provenMutations(input, target, maxMutations) {
         if (mutations.length >= maxMutations)
             break;
     }
-    return mutations;
+    return { mutations, constrained };
+}
+/** The header names the harness may set or mutate. */
+const harnessOwnsHeader = (name) => {
+    const lower = name.toLowerCase();
+    return !CREDENTIAL_HEADER.test(lower) && !RUNTIME_HEADERS.has(lower);
+};
+const scalarText = (value) => typeof value === "string"
+    ? value
+    : (typeof value === "number" && Number.isFinite(value)) || typeof value === "boolean"
+        ? String(value)
+        : undefined;
+/** Path params as the router hands them over: exactly the route's names, each a non-empty segment
+ * text that survives URL normalization (no `.` or `..` part). Anything else cannot be sent. */
+const paramsInput = (value, names) => {
+    const record = recordOf(value);
+    if (record === undefined || Object.keys(record).length !== names.length)
+        return undefined;
+    const entries = [];
+    for (const name of names) {
+        const text = own(record, name) ? scalarText(record[name]) : undefined;
+        if (text === undefined ||
+            text.split("/").some((part) => part === "" || part === "." || part === ".."))
+            return undefined;
+        entries.push([name, text]);
+    }
+    return Object.fromEntries(entries);
+};
+/** Headers as a server reads them: lower-case names to values `Headers` carries unchanged. */
+const headersInput = (value) => {
+    const record = recordOf(value);
+    if (record === undefined)
+        return undefined;
+    const entries = [];
+    for (const [name, item] of Object.entries(record)) {
+        if (item === undefined)
+            continue;
+        const text = scalarText(item);
+        if (text === undefined ||
+            !HEADER_NAME.test(name) ||
+            text !== text.trim() ||
+            // biome-ignore lint/suspicious/noControlCharactersInRegex: a header value may carry none of these
+            /[\r\n\u0000]|[^\u0000-\u00ff]/.test(text))
+            return undefined;
+        entries.push([name.toLowerCase(), text]);
+    }
+    return Object.fromEntries(entries);
+};
+/** The names a route pattern binds, each with a value its own matcher accepts. */
+function placeholderParams(path) {
+    let segments;
+    try {
+        segments = compileRoutePattern(path).segments;
+    }
+    catch {
+        return {};
+    }
+    const entries = [];
+    for (const segment of segments) {
+        if (segment.kind === "param")
+            entries.push([segment.name, `${segment.name}-contract`]);
+        else if (segment.kind === "wildcard") {
+            entries.push([segment.name, `${segment.name === "*" ? "path" : segment.name}/contract`]);
+        }
+        else if (segment.kind === "mixed") {
+            for (const part of segment.parts) {
+                if (part.t !== "lit") {
+                    entries.push([
+                        part.name,
+                        part.c === undefined ? `${part.name}-contract` : satisfying(part.c),
+                    ]);
+                }
+            }
+        }
+    }
+    return Object.fromEntries(entries);
+}
+/** `value` when it is a record of strings, as a resolved params input always is. */
+const stringRecordOf = (value) => {
+    const record = recordOf(value);
+    if (record === undefined)
+        return undefined;
+    const entries = Object.entries(record);
+    return entries.every((entry) => typeof entry[1] === "string")
+        ? Object.fromEntries(entries)
+        : undefined;
+};
+/** `value` in the form `target` travels in, or `undefined` when no request could carry it. */
+function transported(target, value, paramNames) {
+    if (target === "query")
+        return queryInput(value);
+    if (target === "headers")
+        return headersInput(value);
+    if (target === "params")
+        return paramsInput(value, paramNames);
+    return jsonClone(value);
 }
 const queryPairs = (value) => {
     const record = recordOf(value);
@@ -310,7 +441,7 @@ const withReflectedJsonSchema = (reflection, reflect) => {
         return reflection;
     }
 };
-async function resolveInput(routeKey, target, reflection, witness, seed, maxWitnessBytes) {
+async function resolveInput(routeKey, target, reflection, source, seed, maxWitnessBytes) {
     if (reflection.standard === undefined) {
         return {
             ok: false,
@@ -323,12 +454,13 @@ async function resolveInput(routeKey, target, reflection, witness, seed, maxWitn
         };
     }
     let value;
-    if (own(witness, target)) {
-        value = witness[target];
+    if (source.given !== undefined && source.merge === undefined) {
+        value = source.given;
     }
     else if (reflection.jsonSchema !== undefined) {
         try {
-            value = generateMockValue(reflection.jsonSchema, target, seededRandom(seed ^ hash(`${routeKey}:${target}`)));
+            const synthesized = generateMockValue(reflection.jsonSchema, target, seededRandom(seed ^ hash(`${routeKey}:${target}`)));
+            value = source.merge === undefined ? synthesized : source.merge(synthesized);
         }
         catch (error) {
             return {
@@ -342,6 +474,9 @@ async function resolveInput(routeKey, target, reflection, witness, seed, maxWitn
             };
         }
     }
+    else if (source.merge !== undefined && source.given !== undefined) {
+        value = source.merge(undefined);
+    }
     else {
         return {
             ok: false,
@@ -349,12 +484,12 @@ async function resolveInput(routeKey, target, reflection, witness, seed, maxWitn
                 route: routeKey,
                 target,
                 code: "NO_WITNESS",
-                message: `opaque ${target} schema needs witnesses[${JSON.stringify(routeKey)}].${target}`,
+                message: `opaque ${target} schema${source.opaqueReason === undefined ? "" : ` (${source.opaqueReason})`} needs witnesses[${JSON.stringify(routeKey)}].${target}`,
             },
         };
     }
     try {
-        value = target === "query" ? queryInput(value) : jsonClone(value);
+        value = transported(target, value, source.paramNames);
         if (value === undefined)
             throw new TypeError(`${target} witness is not transport-serializable`);
         if (valueSize(value) > maxWitnessBytes) {
@@ -436,18 +571,39 @@ function materializePath(path, params) {
     });
     return `/${filled.join("/")}`;
 }
-function requestFor(laboratory, origin, body, query) {
-    const path = materializePath(laboratory.route.path, laboratory.witness.params);
+const paramNamesOf = (laboratory) => Object.keys(recordOf(laboratory.inputs.params?.value) ?? {});
+/** The laboratory's resolved inputs, with `target` replaced by `value` when one is given. */
+function inputValues(laboratory, target, value) {
+    const values = {};
+    for (const name of INPUT_TARGETS) {
+        const current = name === target ? value : laboratory.inputs[name]?.value;
+        if (current !== undefined)
+            values[name] = current;
+    }
+    return values;
+}
+function requestFor(laboratory, origin, values) {
+    const params = stringRecordOf(values.params);
+    const path = materializePath(laboratory.route.path, params ?? laboratory.witness.params);
     const url = new URL(path, origin);
-    for (const [key, value] of queryPairs(query) ?? [])
+    for (const [key, value] of queryPairs(values.query) ?? [])
         url.searchParams.append(key, value);
     const headers = new Headers(laboratory.witness.headers);
+    const headerValues = recordOf(values.headers);
+    if (headerValues !== undefined) {
+        // The resolved record holds the witness's headers too, so a mutation that drops one drops it here.
+        for (const name of Object.keys(recordOf(laboratory.inputs.headers?.value) ?? {})) {
+            headers.delete(name);
+        }
+        for (const [name, value] of Object.entries(headerValues))
+            headers.set(name, String(value));
+    }
     const init = { method: laboratory.route.method, headers };
     if (laboratory.route.schema?.body !== undefined &&
         !NO_BODY_METHODS.has(laboratory.route.method)) {
         if (!headers.has("content-type"))
             headers.set("content-type", "application/json");
-        init.body = JSON.stringify(body);
+        init.body = JSON.stringify(values.body);
     }
     return new Request(url.toString(), init);
 }
@@ -502,9 +658,7 @@ async function executeRejection(runtime, laboratory, target, mutation, id, optio
         mutation: `${displayPath(target, mutation.path)} ${mutation.reason}`,
     };
     try {
-        const body = target === "body" ? mutation.value : laboratory.body?.value;
-        const query = target === "query" ? mutation.value : laboratory.query?.value;
-        const request = await preparedRequest(requestFor(laboratory, origin, body, query), context, options.prepareRequest);
+        const request = await preparedRequest(requestFor(laboratory, origin, inputValues(laboratory, target, mutation.value)), context, options.prepareRequest);
         const response = await runtime.fetch(request);
         const rejected = options.isRejected === undefined
             ? statuses.has(response.status)
@@ -527,20 +681,20 @@ async function shrinkFailure(runtime, laboratory, target, mutation, id, options,
             attempts += 1;
             if (attempts > maxAttempts)
                 break;
-            const reflection = target === "body" ? laboratory.body?.reflection : laboratory.query?.reflection;
-            const transported = target === "query" ? queryInput(value) : jsonClone(value);
-            if (transported === undefined)
+            const reflection = laboratory.inputs[target]?.reflection;
+            const carried = transported(target, value, paramNamesOf(laboratory));
+            if (carried === undefined)
                 continue;
             if (reflection === undefined)
                 continue;
             try {
-                if (!(await rejectedByValidator(reflection, transported)))
+                if (!(await rejectedByValidator(reflection, carried)))
                     continue;
             }
             catch {
                 continue;
             }
-            const candidate = { ...current, value: transported };
+            const candidate = { ...current, value: carried };
             const result = await executeRejection(runtime, laboratory, target, candidate, id, options, seed, origin, statuses);
             status = result.status;
             if (!result.rejected && result.error === undefined) {
@@ -561,6 +715,21 @@ const resultForFailure = (base, seed, message) => ({
     message,
     replay: { seed, caseId: base.id, runtime: base.runtime },
 });
+/** A witness's headers as the lower-case record a server validates. */
+function headerRecordOf(init) {
+    const entries = [];
+    new Headers(init).forEach((value, name) => {
+        entries.push([name, value]);
+    });
+    return Object.fromEntries(entries);
+}
+/** The `required` property names a JSON Schema object states. */
+const requiredNames = (schema) => {
+    const required = schemaRecord(schema)?.required;
+    return Array.isArray(required)
+        ? required.filter((name) => typeof name === "string")
+        : [];
+};
 async function buildLaboratories(routes, options, seed, gaps) {
     const laboratories = [];
     const maxMutations = positiveInteger(options.maxMutationsPerInput, DEFAULT_MAX_MUTATIONS);
@@ -569,73 +738,122 @@ async function buildLaboratories(routes, options, seed, gaps) {
     for (const route of routes) {
         const routeKey = routeKeyOf(route);
         const witness = options.witnesses?.[routeKey] ?? {};
-        let body;
-        let query;
-        if (route.schema?.body !== undefined) {
+        const schema = route.schema;
+        const witnessKey = `witnesses[${JSON.stringify(routeKey)}]`;
+        const witnessHeaders = headerRecordOf(witness.headers);
+        const placeholders = placeholderParams(route.path);
+        const paramNames = Object.keys(placeholders);
+        const sendsBody = !NO_BODY_METHODS.has(route.method);
+        const inputs = {};
+        let resolved = true;
+        if (schema?.cookies !== undefined && witnessHeaders.cookie === undefined) {
+            resolved = false;
+            gaps.push({
+                route: routeKey,
+                target: "cookies",
+                code: "NO_WITNESS",
+                message: `cookies are credentials and are never synthesized: set ${witnessKey}.headers.cookie`,
+            });
+        }
+        for (const target of INPUT_TARGETS) {
+            const declared = schema?.[target];
+            if (declared === undefined)
+                continue;
             targetCount += 1;
-            if (NO_BODY_METHODS.has(route.method)) {
+            if (target === "body" && !sendsBody) {
+                resolved = false;
                 gaps.push({
                     route: routeKey,
                     target: "body",
                     code: "UNSUPPORTED_BODY_METHOD",
                     message: `${route.method} cannot carry a request body`,
                 });
+                continue;
             }
-            else {
-                const resolved = await resolveInput(routeKey, "body", withReflectedJsonSchema(route.schema.body, options.reflectJsonSchema ?? autoReflectJsonSchema), witness, seed, maxWitnessBytes);
-                if (resolved.ok)
-                    body = resolved.input;
-                else
-                    gaps.push(resolved.gap);
+            const reflection = withReflectedJsonSchema(declared, options.reflectJsonSchema ?? autoReflectJsonSchema);
+            const opaqueReason = reflection.jsonSchema === undefined && options.reflectJsonSchema === undefined
+                ? explainAutoReflectJsonSchema(reflection.standard)
+                : undefined;
+            const source = target === "params"
+                ? {
+                    given: witness.params,
+                    merge: (synthesized) => ({
+                        ...placeholders,
+                        ...Object.fromEntries(Object.entries(recordOf(synthesized) ?? {}).filter(([name]) => own(placeholders, name))),
+                        ...witness.params,
+                    }),
+                    paramNames,
+                    opaqueReason,
+                }
+                : target === "headers"
+                    ? {
+                        given: witness.headers === undefined ? undefined : witnessHeaders,
+                        merge: (synthesized) => {
+                            const merged = {
+                                ...Object.fromEntries(Object.entries(recordOf(synthesized) ?? {}).filter(([name]) => harnessOwnsHeader(name) && !own(witnessHeaders, name.toLowerCase()))),
+                                ...witnessHeaders,
+                            };
+                            // The request carries this for a body, so the validator must see it too.
+                            if (schema?.body !== undefined && sendsBody && !own(merged, "content-type"))
+                                merged["content-type"] = "application/json";
+                            return merged;
+                        },
+                        paramNames,
+                        opaqueReason,
+                    }
+                    : {
+                        given: own(witness, target) ? witness[target] : undefined,
+                        paramNames,
+                        opaqueReason,
+                    };
+            const result = await resolveInput(routeKey, target, reflection, source, seed, maxWitnessBytes);
+            if (result.ok) {
+                inputs[target] = result.input;
+                continue;
             }
-        }
-        if (route.schema?.query !== undefined) {
-            targetCount += 1;
-            const resolved = await resolveInput(routeKey, "query", withReflectedJsonSchema(route.schema.query, options.reflectJsonSchema ?? autoReflectJsonSchema), witness, seed, maxWitnessBytes);
-            if (resolved.ok)
-                query = resolved.input;
-            else
-                gaps.push(resolved.gap);
+            resolved = false;
+            const credentials = target === "headers" && result.gap.code === "INVALID_WITNESS"
+                ? requiredNames(reflection.jsonSchema).filter((name) => !harnessOwnsHeader(name) && !own(witnessHeaders, name.toLowerCase()))
+                : [];
+            gaps.push(credentials.length === 0
+                ? result.gap
+                : {
+                    ...result.gap,
+                    code: "NO_WITNESS",
+                    message: `the harness never invents credentials: set ${credentials.join(", ")} in ${witnessKey}.headers (prepareRequest may replace them per runtime)`,
+                });
         }
         const expectedStatus = witness.expected?.status;
         const expectedResponseSchema = expectedStatus !== undefined && (expectedStatus < 200 || expectedStatus >= 300)
-            ? route.schema?.errors?.[expectedStatus]
-            : route.schema?.response;
+            ? schema?.errors?.[expectedStatus]
+            : schema?.response;
         if (options.validateResponses !== false && expectedResponseSchema !== undefined)
             targetCount += 1;
-        const allInputsResolved = (route.schema?.body === undefined || body !== undefined) &&
-            (route.schema?.query === undefined || query !== undefined);
-        const bodyMutations = body !== undefined && allInputsResolved
-            ? await provenMutations(body, "body", maxMutations)
-            : [];
-        const queryMutations = query !== undefined && allInputsResolved
-            ? await provenMutations(query, "query", maxMutations)
-            : [];
-        if (body !== undefined && allInputsResolved && bodyMutations.length === 0) {
-            gaps.push({
-                route: routeKey,
-                target: "body",
-                code: "NO_REJECTED_MUTATION",
-                message: "the body validator accepted every generated hostile mutation",
-            });
-        }
-        if (query !== undefined && allInputsResolved && queryMutations.length === 0) {
-            gaps.push({
-                route: routeKey,
-                target: "query",
-                code: "NO_REJECTED_MUTATION",
-                message: "the query validator accepted every generated hostile mutation",
-            });
+        const mutations = {
+            headers: [],
+            params: [],
+            body: [],
+            query: [],
+        };
+        for (const target of INPUT_TARGETS) {
+            const input = inputs[target];
+            if (input === undefined || !resolved)
+                continue;
+            const proven = await provenMutations(input, target, maxMutations, paramNames);
+            mutations[target] = proven.mutations;
+            // A params or headers field typed as bare text accepts every type swap, so only a constraint
+            // the schema states is a rejection to expect there.
+            const expectRejection = target === "body" || target === "query" || proven.constrained;
+            if (proven.mutations.length === 0 && expectRejection) {
+                gaps.push({
+                    route: routeKey,
+                    target,
+                    code: "NO_REJECTED_MUTATION",
+                    message: `the ${target} validator accepted every generated hostile mutation`,
+                });
+            }
         }
-        laboratories.push({
-            route,
-            routeKey,
-            witness,
-            ...(body === undefined ? {} : { body }),
-            ...(query === undefined ? {} : { query }),
-            bodyMutations,
-            queryMutations,
-        });
+        laboratories.push({ route, routeKey, witness, inputs, mutations, resolved });
     }
     return { laboratories, targetCount };
 }
@@ -675,13 +893,12 @@ export async function runAdversarialContract(app, options = {}) {
     if (targetCount === 0) {
         gaps.push({
             code: "NO_CONTRACT_TARGETS",
-            message: "selected routes declare no body, query, or response contracts",
+            message: "selected routes declare no headers, params, body, query, or response contracts",
         });
     }
     for (const laboratory of laboratories) {
-        for (const target of ["body", "query"]) {
-            const mutations = target === "body" ? laboratory.bodyMutations : laboratory.queryMutations;
-            for (const mutation of mutations) {
+        for (const target of INPUT_TARGETS) {
+            for (const mutation of laboratory.mutations[target]) {
                 const id = mutationId(laboratory.routeKey, target, mutation);
                 if (only !== undefined && !only.has(id))
                     continue;
@@ -751,9 +968,7 @@ export async function runAdversarialContract(app, options = {}) {
             });
             continue;
         }
-        const allInputsResolved = (laboratory.route.schema?.body === undefined || laboratory.body !== undefined) &&
-            (laboratory.route.schema?.query === undefined || laboratory.query !== undefined);
-        if (!allInputsResolved)
+        if (!laboratory.resolved)
             continue;
         for (const runtime of runtimes) {
             const context = {
@@ -773,7 +988,7 @@ export async function runAdversarialContract(app, options = {}) {
                 target: "response",
             };
             try {
-                const request = await preparedRequest(requestFor(laboratory, origin, laboratory.body?.value, laboratory.query?.value), context, options.prepareRequest);
+                const request = await preparedRequest(requestFor(laboratory, origin, inputValues(laboratory)), context, options.prepareRequest);
                 const response = await runtime.fetch(request);
                 const status = response.status;
                 if (expected === undefined ? !response.ok : response.status !== expected.status) {
@@ -854,6 +1069,12 @@ export async function runAdversarialContract(app, options = {}) {
             "conformance checked 0 targets. Response types inferred from a handler's return are a client-side " +
             "contract only - declare `response:` or `errors:` on the routes you want the laboratory to verify.");
     }
+    // Declared on an opaque mount's word: listed so the run states what it could not test.
+    for (const mount of reflectMounts(app)) {
+        for (const route of mount.routes ?? []) {
+            advisories.push(`${route.method} ${route.path} is declared by the opaque mount ${mount.path} (${mount.opaque}) and has no contract to test`);
+        }
+    }
     return {
         ok: failures.length === 0 && !fatalGap && (!coverageRequired || gaps.length === 0),
         seed,