@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/probe/negative-probe.ts

@@ -0,0 +1,691 @@
+/**
+ * Negative-input probe generator (T49).
+ *
+ * Goal: catch the class of bugs where an API returns 5xx (unhandled exception)
+ * instead of 4xx (validation error) when given malformed input. The contract
+ * is simple: any client-supplied invalid input MUST produce a 4xx, never a 5xx.
+ *
+ * For each endpoint we generate a suite of probe steps. Each step expects a
+ * "no 5xx" response (status in [400, 401, 403, 404, 405, 409, 415, 422, 429]).
+ * If the API returns 500/502/503 — the test fails and the runner logs it as
+ * a bug candidate via the regular reporter / `zond db diagnose` flow.
+ *
+ * ARV-34: 429 is in the allow-set because rate-limiting is itself a valid
+ * server-side rejection of the request — the API refused to process invalid
+ * input, the contract is satisfied. Throttled probe runs were producing
+ * hundreds of false failures with the warning "N requests hit rate limit"
+ * already saying the same thing.
+ *
+ * The probes are deterministic — same spec → same suites — so the generated
+ * YAML can be committed as a regression test.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
+import type { RawSuite, RawStep } from "../generator/serializer.ts";
+import { generateFromSchema } from "../generator/data-factory.ts";
+import {
+  convertPath,
+  endpointStem,
+  getAuthHeaders,
+  renderPath,
+  isMutating,
+  findDeleteCounterpart,
+  captureFieldFor,
+  headersEqual,
+  hasJsonBody,
+} from "./shared.ts";
+
+// ──────────────────────────────────────────────
+// Constants
+// ──────────────────────────────────────────────
+
+/** Statuses we consider an *acceptable* response to invalid input. Anything
+ *  outside this set (notably 5xx, but also 200/201 which would mean the API
+ *  silently accepted the bad input) is a probe failure. ARV-34: 429 stays in
+ *  the allow-set — server-side throttling is a valid rejection. */
+const ACCEPTABLE_4XX = [400, 401, 403, 404, 405, 409, 415, 422, 429];
+
+/** Long string for boundary probes — 10_000 chars. */
+const LONG_STRING = "a".repeat(10_000);
+
+/** Mixed unicode + emoji + RTL for charset probes. */
+const UNICODE_MIX = "Mix🌐مرحبا\u200B";
+
+/** Sentinel non-UUID inputs for path/UUID probes. */
+export const INVALID_UUID_SENTINELS = [
+  "not-a-uuid",
+  "12345",
+  "00000000",
+  "../../etc/passwd",
+] as const;
+const INVALID_UUID_VALUES = INVALID_UUID_SENTINELS;
+
+/** Sentinel invalid emails. */
+const INVALID_EMAIL_VALUES = [
+  "not-an-email",
+  "@no-local.example.com",
+  "spaces in@email.com",
+];
+
+/** Sentinel invalid URIs. */
+const INVALID_URI_VALUES = [
+  "not a url",
+  "javascript:alert(1)",
+  "ftp:/missing-slash",
+];
+
+/** Sentinel invalid date-time strings. */
+const INVALID_DATETIME_VALUES = [
+  "yesterday",
+  "2023-13-45T99:99:99Z",
+  "2023-10-06:23:47:56.678Z", // colon-instead-of-T (real bug we caught)
+];
+
+// ──────────────────────────────────────────────
+// Types
+// ──────────────────────────────────────────────
+
+export interface ProbeOptions {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+  /** Cap probes per endpoint (default 50). Hard cutoff for huge schemas. */
+  maxProbesPerEndpoint?: number;
+  /**
+   * Skip emission of follow-up DELETE cleanup steps for mutating probes
+   * (POST/PUT/PATCH). Useful for namespace-isolated test environments
+   * (staging dump-and-reset) where cleanup is handled out of band.
+   */
+  noCleanup?: boolean;
+  /**
+   * TASK-135: when true (default), non-attacked path-params are emitted as
+   * runtime placeholders `{{name}}` so `zond run` substitutes them from
+   * `.env.yaml`. This avoids the short-circuit where every probe targeting a
+   * nested path resolved `{org}=nonexistent-zzzzz` and got 404 before the
+   * leaf validator ever fired. Set to false to keep the legacy behaviour
+   * (synthetic-by-type for every param).
+   */
+  useRealParents?: boolean;
+}
+
+export interface ProbeResult {
+  suites: RawSuite[];
+  /** Number of endpoints that received probes. */
+  probedEndpoints: number;
+  /** Endpoints we skipped (no body & no UUID path params). */
+  skippedEndpoints: number;
+  /** Total generated probe steps. */
+  totalProbes: number;
+  /**
+   * Generation-time warnings — typically about mutating endpoints whose
+   * probes might leak resources because the spec defines no DELETE
+   * counterpart. CLI surfaces these to the user.
+   */
+  warnings: string[];
+}
+
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+
+function findUuidPathParams(ep: EndpointInfo): OpenAPIV3.ParameterObject[] {
+  return ep.parameters.filter((p) => {
+    if (p.in !== "path") return false;
+    const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+    if (!schema) return false;
+    if (schema.format === "uuid") return true;
+    // also probe path params named like *_id / *_uuid
+    const lower = p.name.toLowerCase();
+    return lower === "id" || lower.endsWith("_id") || lower === "uuid";
+  });
+}
+
+/** Walk schema and collect required-field paths up to depth 1 with their schema. */
+function collectRequiredFields(
+  schema: OpenAPIV3.SchemaObject | undefined,
+): Array<{ name: string; schema: OpenAPIV3.SchemaObject }> {
+  if (!schema || !schema.properties) return [];
+  const required = new Set(schema.required ?? []);
+  const out: Array<{ name: string; schema: OpenAPIV3.SchemaObject }> = [];
+  for (const [name, propSchema] of Object.entries(schema.properties)) {
+    if (required.has(name)) {
+      out.push({ name, schema: propSchema as OpenAPIV3.SchemaObject });
+    }
+  }
+  return out;
+}
+
+/** Walk schema (depth 1) and collect all properties with their schema. */
+function collectAllProps(
+  schema: OpenAPIV3.SchemaObject | undefined,
+): Array<{ name: string; schema: OpenAPIV3.SchemaObject; required: boolean }> {
+  if (!schema || !schema.properties) return [];
+  const required = new Set(schema.required ?? []);
+  return Object.entries(schema.properties).map(([name, s]) => ({
+    name,
+    schema: s as OpenAPIV3.SchemaObject,
+    required: required.has(name),
+  }));
+}
+
+// ──────────────────────────────────────────────
+// Probe generators
+// ──────────────────────────────────────────────
+
+/**
+ * Build a step that targets `endpoint`, but with an arbitrary body override.
+ * Authentication and required path params are populated with valid placeholders
+ * so the request reaches the body-validation layer.
+ *
+ * `pathOverride` (if provided) is treated as already-final — no further
+ * placeholder conversion is applied. Otherwise the path is rendered via
+ * `renderPath` with no attack target (so all path-params become runtime
+ * placeholders / synthetic sentinels depending on `useRealParents`).
+ */
+function buildStep(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  opts: {
+    name: string;
+    json?: unknown;
+    pathOverride?: string;
+    expectStatusOk?: number[];
+    useRealParents: boolean;
+  },
+): RawStep {
+  const method = ep.method.toUpperCase();
+  const path = opts.pathOverride ?? renderPath(ep, null, { useRealParents: opts.useRealParents });
+  const headers = getAuthHeaders(ep, schemes);
+
+  const expectedStatus = opts.expectStatusOk ?? ACCEPTABLE_4XX;
+  const responseBranch = Array.isArray(expectedStatus) ? expectedStatus.map(String).join("|") : String(expectedStatus);
+  const step: RawStep = {
+    name: opts.name,
+    source: {
+      generator: "negative-probe",
+      endpoint: `${method} ${ep.path}`,
+      response_branch: responseBranch,
+    },
+    [method]: path,
+    expect: {
+      status: expectedStatus,
+    },
+  };
+  if (headers) step.headers = headers;
+  if (opts.json !== undefined) (step as any).json = opts.json;
+  return step;
+}
+
+function probeEmptyBody(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  useRealParents: boolean,
+): RawStep | null {
+  if (!hasJsonBody(ep)) return null;
+  const required = collectRequiredFields(ep.requestBodySchema);
+  // Only meaningful when there *is* required data — otherwise {} is valid.
+  if (required.length === 0) return null;
+  return buildStep(ep, schemes, {
+    name: "empty body — must reject (no 5xx)",
+    json: {},
+    useRealParents,
+  });
+}
+
+function probeMissingRequired(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  if (!hasJsonBody(ep) || !ep.requestBodySchema) return [];
+  const required = collectRequiredFields(ep.requestBodySchema);
+  if (required.length === 0) return [];
+
+  // Build a baseline valid object, then drop one required field at a time.
+  const baseline = generateFromSchema(ep.requestBodySchema) as Record<string, unknown>;
+  if (typeof baseline !== "object" || baseline === null) return [];
+
+  const out: RawStep[] = [];
+  for (const field of required) {
+    if (out.length >= budget) break;
+    const variant = { ...baseline };
+    delete variant[field.name];
+    out.push(
+      buildStep(ep, schemes, {
+        name: `missing required field "${field.name}" — must reject (no 5xx)`,
+        json: variant,
+        useRealParents,
+      }),
+    );
+  }
+  return out;
+}
+
+function probeBoundaryString(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  if (!hasJsonBody(ep) || !ep.requestBodySchema) return [];
+  const props = collectAllProps(ep.requestBodySchema).filter(
+    (p) => p.schema.type === "string",
+  );
+  if (props.length === 0) return [];
+
+  const baseline = generateFromSchema(ep.requestBodySchema) as Record<string, unknown>;
+  if (typeof baseline !== "object" || baseline === null) return [];
+
+  const out: RawStep[] = [];
+  // Only probe the first N string fields to stay within budget
+  for (const field of props.slice(0, Math.max(1, Math.floor(budget / 3)))) {
+    if (out.length + 3 > budget) break;
+    out.push(
+      buildStep(ep, schemes, {
+        name: `${field.name}: empty string — must reject (no 5xx)`,
+        json: { ...baseline, [field.name]: "" },
+        useRealParents,
+      }),
+      buildStep(ep, schemes, {
+        name: `${field.name}: 10000-char string — must reject or accept (no 5xx)`,
+        json: { ...baseline, [field.name]: LONG_STRING },
+        useRealParents,
+      }),
+      buildStep(ep, schemes, {
+        name: `${field.name}: unicode/emoji/RTL — must not 5xx`,
+        json: { ...baseline, [field.name]: UNICODE_MIX },
+        useRealParents,
+      }),
+    );
+  }
+  return out;
+}
+
+function probeTypeConfusion(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  if (!hasJsonBody(ep) || !ep.requestBodySchema) return [];
+  const props = collectAllProps(ep.requestBodySchema);
+  if (props.length === 0) return [];
+
+  const baseline = generateFromSchema(ep.requestBodySchema) as Record<string, unknown>;
+  if (typeof baseline !== "object" || baseline === null) return [];
+
+  const out: RawStep[] = [];
+  for (const field of props) {
+    if (out.length >= budget) break;
+    const wrongValue = pickWrongType(field.schema);
+    if (wrongValue === undefined) continue;
+    out.push(
+      buildStep(ep, schemes, {
+        name: `${field.name}: wrong type (${describeType(field.schema)} → ${typeof wrongValue}) — must reject (no 5xx)`,
+        json: { ...baseline, [field.name]: wrongValue },
+        useRealParents,
+      }),
+    );
+  }
+  return out;
+}
+
+function probeInvalidFormat(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  if (!hasJsonBody(ep) || !ep.requestBodySchema) return [];
+  const props = collectAllProps(ep.requestBodySchema);
+  const baseline = generateFromSchema(ep.requestBodySchema) as Record<string, unknown>;
+  if (typeof baseline !== "object" || baseline === null) return [];
+
+  const out: RawStep[] = [];
+  for (const field of props) {
+    if (out.length >= budget) break;
+    const fmt = field.schema.format;
+    let badValue: string | undefined;
+    if (fmt === "email") badValue = INVALID_EMAIL_VALUES[0];
+    else if (fmt === "uri" || fmt === "url") badValue = INVALID_URI_VALUES[0];
+    else if (fmt === "date-time") badValue = INVALID_DATETIME_VALUES[0];
+    else if (fmt === "uuid") badValue = INVALID_UUID_VALUES[0];
+    if (badValue === undefined) continue;
+    out.push(
+      buildStep(ep, schemes, {
+        name: `${field.name}: invalid ${fmt} (${JSON.stringify(badValue)}) — must reject (no 5xx)`,
+        json: { ...baseline, [field.name]: badValue },
+        useRealParents,
+      }),
+    );
+  }
+  return out;
+}
+
+function probeInvalidEnum(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  if (!hasJsonBody(ep) || !ep.requestBodySchema) return [];
+  const baseline = generateFromSchema(ep.requestBodySchema) as Record<string, unknown>;
+  if (typeof baseline !== "object" || baseline === null) return [];
+
+  const out: RawStep[] = [];
+  // Walk depth 1 for plain enum strings
+  for (const field of collectAllProps(ep.requestBodySchema)) {
+    if (out.length >= budget) break;
+    if (Array.isArray(field.schema.enum) && field.schema.enum.length > 0) {
+      out.push(
+        buildStep(ep, schemes, {
+          name: `${field.name}: unknown enum value "zond_invalid_value" — must reject (no 5xx)`,
+          json: { ...baseline, [field.name]: "zond_invalid_value" },
+          useRealParents,
+        }),
+      );
+    }
+    // enum-of-strings inside an array (e.g. webhooks.events: [enum])
+    if (field.schema.type === "array" && field.schema.items) {
+      const items = field.schema.items as OpenAPIV3.SchemaObject;
+      const enumLike = Array.isArray(items.enum) && items.enum.length > 0;
+      const isStringArray = items.type === "string";
+      if (enumLike || isStringArray) {
+        // even when no enum is declared, names like "events"/"types"/"channels"
+        // strongly imply a backing whitelist — bug #05B
+        out.push(
+          buildStep(ep, schemes, {
+            name: `${field.name}: array with unknown value ["zond.nonexistent.event"] — must reject (no 5xx)`,
+            json: { ...baseline, [field.name]: ["zond.nonexistent.event"] },
+            useRealParents,
+          }),
+        );
+      }
+    }
+  }
+  return out;
+}
+
+function probeInvalidPathId(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  const params = findUuidPathParams(ep);
+  if (params.length === 0) return [];
+  // Skip POST /resource (no path id) — covered by body probes
+  const out: RawStep[] = [];
+  for (const param of params) {
+    for (const bad of INVALID_UUID_VALUES) {
+      if (out.length >= budget) break;
+      const path = renderPath(ep, { name: param.name, value: bad }, { useRealParents });
+      out.push(
+        buildStep(ep, schemes, {
+          name: `path param ${param.name}=${JSON.stringify(bad)} — must reject (no 5xx)`,
+          pathOverride: path,
+          useRealParents,
+        }),
+      );
+    }
+  }
+  return out;
+}
+
+/** TASK-67: numeric coercion probes for integer/number params (query + path).
+ *  Round-2 found `GET /emails?limit=1.5` → 500 — the bug class probe-validation
+ *  exists for. T49 covered numeric type-confusion in body, this extends to
+ *  query/path. */
+const NUMERIC_BAD_VALUES: Array<{ value: string; label: string }> = [
+  { value: "1.5", label: "float on integer" },
+  { value: "-1", label: "negative" },
+  { value: "0", label: "zero" },
+  { value: "abc", label: "non-numeric" },
+  { value: "", label: "empty string" },
+  // null on a query param means literal "null" string — most parsers treat it as bad input
+  { value: "null", label: "literal null" },
+  // Number.MAX_SAFE_INTEGER + 1 = 9007199254740992
+  { value: "9007199254740992", label: "MAX_SAFE_INTEGER+1" },
+];
+
+function isNumericSchema(schema: OpenAPIV3.SchemaObject | undefined): boolean {
+  return schema?.type === "integer" || schema?.type === "number";
+}
+
+function probeNumericQueryParams(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  const numericQuery = ep.parameters.filter(
+    (p) => p.in === "query" && isNumericSchema(p.schema as OpenAPIV3.SchemaObject | undefined),
+  );
+  if (numericQuery.length === 0) return [];
+
+  const out: RawStep[] = [];
+  for (const param of numericQuery) {
+    for (const { value, label } of NUMERIC_BAD_VALUES) {
+      if (out.length >= budget) break;
+      const basePath = renderPath(ep, null, { useRealParents });
+      const sep = basePath.includes("?") ? "&" : "?";
+      const pathWithQuery = `${basePath}${sep}${param.name}=${encodeURIComponent(value)}`;
+      out.push(
+        buildStep(ep, schemes, {
+          name: `query ${param.name}=${JSON.stringify(value)} (${label}) — must reject (no 5xx)`,
+          pathOverride: pathWithQuery,
+          useRealParents,
+        }),
+      );
+    }
+  }
+  return out;
+}
+
+function probeNumericPathParams(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  budget: number,
+  useRealParents: boolean,
+): RawStep[] {
+  const numericPath = ep.parameters.filter(
+    (p) => p.in === "path" && isNumericSchema(p.schema as OpenAPIV3.SchemaObject | undefined),
+  );
+  if (numericPath.length === 0) return [];
+
+  const out: RawStep[] = [];
+  for (const param of numericPath) {
+    for (const { value, label } of NUMERIC_BAD_VALUES) {
+      if (value === "") continue; // empty path segment yields a different endpoint
+      if (out.length >= budget) break;
+      const overriddenPath = renderPath(ep, { name: param.name, value }, { useRealParents });
+      out.push(
+        buildStep(ep, schemes, {
+          name: `path param ${param.name}=${JSON.stringify(value)} (${label}) — must reject (no 5xx)`,
+          pathOverride: overriddenPath,
+          useRealParents,
+        }),
+      );
+    }
+  }
+  return out;
+}
+
+// ──────────────────────────────────────────────
+// Type-confusion helpers
+// ──────────────────────────────────────────────
+
+function pickWrongType(schema: OpenAPIV3.SchemaObject): unknown | undefined {
+  switch (schema.type) {
+    case "string":
+      return 12345; // number where string expected
+    case "integer":
+    case "number":
+      return "five"; // string where number expected
+    case "boolean":
+      return "true"; // string where boolean expected
+    case "array":
+      return { not: "an-array" }; // object where array expected
+    case "object":
+      return ["not", "an", "object"]; // array where object expected
+    default:
+      return undefined;
+  }
+}
+
+function describeType(schema: OpenAPIV3.SchemaObject): string {
+  if (schema.format) return `${schema.type ?? "any"}/${schema.format}`;
+  return schema.type ?? "any";
+}
+
+/** Build a cleanup-DELETE step for a single mutating probe. The capture var
+ *  must come from the paired probe step. If the probe didn't capture (e.g.
+ *  the API correctly returned 4xx and no resource was created), the runner
+ *  skips this step via the standard "missing capture" path — exactly the
+ *  semantics we want. */
+function buildCleanupStep(
+  deleteEp: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  captureVar: string,
+  probeStepName: string,
+): RawStep {
+  // Replace the DELETE's path-id placeholder with our captured var.
+  const path = convertPath(deleteEp.path).replace(/\{\{[^}]+\}\}/, `{{${captureVar}}}`);
+  const headers = getAuthHeaders(deleteEp, schemes);
+  const step: RawStep = {
+    name: `cleanup leaked resource from "${probeStepName}"`,
+    source: {
+      generator: "negative-probe-cleanup",
+      endpoint: `DELETE ${deleteEp.path}`,
+    },
+    always: true,
+    DELETE: path,
+    expect: {
+      status: [200, 202, 204, 404],
+    },
+  };
+  if (headers) step.headers = headers;
+  return step;
+}
+
+// ──────────────────────────────────────────────
+// Public API
+// ──────────────────────────────────────────────
+
+export function generateNegativeProbes(opts: ProbeOptions): ProbeResult {
+  const { endpoints, securitySchemes } = opts;
+  const cap = opts.maxProbesPerEndpoint ?? 50;
+  const noCleanup = opts.noCleanup === true;
+  // TASK-135: default ON. Non-attacked path-params are emitted as runtime
+  // placeholders `{{name}}` and resolved from `.env.yaml` by `zond run`.
+  const useRealParents = opts.useRealParents !== false;
+
+  const suites: RawSuite[] = [];
+  const warnings: string[] = [];
+  let probedEndpoints = 0;
+  let skippedEndpoints = 0;
+  let totalProbes = 0;
+
+  for (const ep of endpoints) {
+    if (ep.deprecated) continue;
+
+    const steps: RawStep[] = [];
+    const remaining = () => Math.max(0, cap - steps.length);
+
+    // 1. Path-id probes (cheap, deterministic)
+    steps.push(...probeInvalidPathId(ep, securitySchemes, remaining(), useRealParents));
+
+    // 1b. Numeric query / path coercion probes (T67) — float-on-integer,
+    //     negative, non-numeric, etc. Catches `GET /x?limit=1.5` → 500.
+    const numericQueryProbes = probeNumericQueryParams(ep, securitySchemes, remaining(), useRealParents);
+    steps.push(...numericQueryProbes);
+    const numericPathProbes = probeNumericPathParams(ep, securitySchemes, remaining(), useRealParents);
+    steps.push(...numericPathProbes);
+    const hasNumericCoercion = numericQueryProbes.length + numericPathProbes.length > 0;
+
+    // 2. Body probes (only for body-bearing methods)
+    const empty = probeEmptyBody(ep, securitySchemes, useRealParents);
+    if (empty && steps.length < cap) steps.push(empty);
+
+    steps.push(...probeMissingRequired(ep, securitySchemes, remaining(), useRealParents));
+    steps.push(...probeTypeConfusion(ep, securitySchemes, remaining(), useRealParents));
+    steps.push(...probeInvalidFormat(ep, securitySchemes, remaining(), useRealParents));
+    steps.push(...probeBoundaryString(ep, securitySchemes, remaining(), useRealParents));
+    steps.push(...probeInvalidEnum(ep, securitySchemes, remaining(), useRealParents));
+
+    if (steps.length === 0) {
+      skippedEndpoints++;
+      continue;
+    }
+
+    // T79: Cleanup for mutating probes. If a probe accidentally returns 2xx
+    // (the bug class probe-validation hunts for), the resource sticks around
+    // unless we follow up with a DELETE. We pair each probe step with a
+    // cleanup-DELETE marked `always: true`; the runner skips the DELETE
+    // automatically when no id was captured (i.e. the probe correctly got 4xx).
+    const cleanupSteps: RawStep[] = [];
+    if (isMutating(ep.method) && !noCleanup) {
+      const deleteEp = findDeleteCounterpart(ep, endpoints);
+      if (deleteEp) {
+        const idField = captureFieldFor(ep);
+        for (let i = 0; i < steps.length; i++) {
+          const probeStep = steps[i]!;
+          const captureVar = `leaked_id_${i}`;
+          const probeExpect = probeStep.expect as { body?: Record<string, unknown> };
+          if (!probeExpect.body) probeExpect.body = {};
+          // capture-only rule: doesn't add an assertion, just extracts the id
+          // when the response body has one. extractCaptures is a no-op when
+          // the field is absent (the typical 4xx case).
+          probeExpect.body[idField] = { capture: captureVar };
+          cleanupSteps.push(buildCleanupStep(deleteEp, securitySchemes, captureVar, probeStep.name));
+        }
+      } else {
+        warnings.push(
+          `${ep.method.toUpperCase()} ${ep.path}: probe-validation may create resources but spec defines no DELETE counterpart — manual cleanup required if any probe unexpectedly returns 2xx`,
+        );
+      }
+    }
+    if (cleanupSteps.length > 0) {
+      steps.push(...cleanupSteps);
+    }
+
+    probedEndpoints++;
+    totalProbes += steps.length;
+
+    // Hoist auth headers to suite level — every probe in this suite hits the
+    // same endpoint, so per-step headers are pure duplication. Dropping them
+    // here keeps generated YAML small and makes suite-level overrides
+    // (e.g. switching auth tokens) work as expected.
+    const suiteHeaders = getAuthHeaders(ep, securitySchemes);
+    if (suiteHeaders) {
+      for (const step of steps) {
+        if (step.headers && headersEqual(step.headers as Record<string, string>, suiteHeaders)) {
+          delete (step as { headers?: unknown }).headers;
+        }
+      }
+    }
+
+    const stem = endpointStem(ep);
+    const suite: RawSuite = {
+      name: `probe ${ep.method} ${ep.path}`,
+      tags: [
+        "probe-validation",
+        "negative-input",
+        "no-5xx",
+        ...(hasNumericCoercion ? ["query-coercion"] : []),
+      ],
+      source: {
+        type: "probe-suite",
+        generator: "negative-probe",
+        endpoint: `${ep.method.toUpperCase()} ${ep.path}`,
+      },
+      fileStem: `probe-${stem}`,
+      base_url: "{{base_url}}",
+      ...(suiteHeaders ? { headers: suiteHeaders } : {}),
+      tests: steps,
+    };
+    suites.push(suite);
+  }
+
+  return { suites, probedEndpoints, skippedEndpoints, totalProbes, warnings };
+}