@kirrosh/zond 0.23.0 → 0.26.1

package/src/core/probe/mass-assignment-template.ts

@@ -124,6 +124,12 @@ function mergePrivileged(
   return merged;
 }
 
+/** ARV-198: declared content type signals whether the create step needs
+ *  `form:` (Stripe v1, Rails/PHP-style APIs) or the default `json:` body. */
+function isFormEndpoint(ep: EndpointInfo): boolean {
+  return ep.requestBodyContentType === "application/x-www-form-urlencoded";
+}
+
 function buildFullChain(
   create: EndpointInfo,
   read: EndpointInfo,
@@ -134,12 +140,24 @@ function buildFullChain(
   const idVar = captureFieldFor(create) || "created_id";
   const tests: RawStep[] = [];
 
-  tests.push({
+  // ARV-198: when the spec declares only application/x-www-form-urlencoded
+  // for this mutating endpoint, emit a `form:` block + Content-Type header.
+  // The serializer force-quotes form values (ARV-162) so booleans/numbers
+  // round-trip as strings on the wire; the template is paste-ready against
+  // Stripe-style APIs without any post-processing.
+  const createIsForm = isFormEndpoint(create);
+  const createStep: Record<string, unknown> = {
     name: "create with privileged fields",
     [create.method.toUpperCase()]: create.path,
-    json: privilegedBody,
     expect: { status: [200, 201], body: { id: { capture: idVar } } },
-  } as unknown as RawStep);
+  };
+  if (createIsForm) {
+    createStep.headers = { "Content-Type": "application/x-www-form-urlencoded" };
+    createStep.form = privilegedBody;
+  } else {
+    createStep.json = privilegedBody;
+  }
+  tests.push(createStep as unknown as RawStep);
 
   // Canonical assertion vocabulary: only `not_equals` is supported (no `not`,
   // no `not_starts_with`). For protected fields we assert the exact attacker
@@ -187,7 +205,17 @@ function buildSingleStep(
     [method]: ep.path,
     expect: { status: [400, 422] },
   };
-  if (method !== "GET" && method !== "DELETE") step.json = privilegedBody;
+  if (method !== "GET" && method !== "DELETE") {
+    // ARV-198: same form/json branching as the full-chain create — see
+    // buildFullChain for rationale (Stripe-style mutators declare only
+    // application/x-www-form-urlencoded).
+    if (isFormEndpoint(ep)) {
+      step.headers = { "Content-Type": "application/x-www-form-urlencoded" };
+      step.form = privilegedBody;
+    } else {
+      step.json = privilegedBody;
+    }
+  }
   tests.push(step as unknown as RawStep);
   return {
     name: `ma ${slugFromPath(ep.path)}`,

package/src/core/probe/path-discovery.ts

@@ -18,6 +18,7 @@ import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
 import { executeRequest } from "../runner/http-client.ts";
 import { substituteString } from "../parser/variables.ts";
 import { convertPath, captureFieldFor, liveAuthHeaders } from "./shared.ts";
+import { joinBaseAndPath } from "../util/url.ts";
 
 export type DiscoveryHit = { kind: "hit"; values: Record<string, string> };
 export type DiscoveryMiss = { kind: "miss"; reason: string };
@@ -103,8 +104,7 @@ async function discoverFromList(opts: DiscoverFromListOpts): Promise<DiscoveryRe
   opts.cache.inFlight.add(cacheKey);
   try {
     // Resolve listEp's own path placeholders (nested-collection case).
-    const baseUrl = (opts.vars["base_url"] ?? "").replace(/\/+$/, "");
-    const templated = `${baseUrl}${convertPath(listEp.path)}`;
+    const templated = joinBaseAndPath(opts.vars["base_url"], convertPath(listEp.path));
     let urlVars = opts.vars;
     let urlSubstituted = String(substituteString(templated, urlVars));
     let stillUnresolved = collectUnresolved(urlSubstituted);
@@ -326,8 +326,7 @@ export async function discoverBodyFkVars(
       continue;
     }
 
-    const baseUrl = (opts.vars["base_url"] ?? "").replace(/\/+$/, "");
-    const url = `${baseUrl}${listEp.path}`;
+    const url = joinBaseAndPath(opts.vars["base_url"], listEp.path);
     const headers: Record<string, string> = {
       accept: "application/json",
       ...liveAuthHeaders(listEp, opts.schemes, opts.vars),

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

@@ -15,7 +15,9 @@ import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
 import { generateFromSchema } from "../generator/data-factory.ts";
 import { substituteDeep, substituteString } from "../parser/variables.ts";
 import { convertPath, liveAuthHeaders } from "./shared.ts";
+import { joinBaseAndPath } from "../util/url.ts";
 import { encodeFormBody } from "../runner/form-encode.ts";
+import type { SeedBodyConfig } from "../generator/resources-builder.ts";
 
 /** ARV-150: form-encoded mutating endpoint (Stripe v1 pattern).
  *  Stripe and other Rails/PHP APIs declare requestBody.content with ONLY
@@ -62,34 +64,20 @@ export function buildProbeUrl(
   ep: EndpointInfo,
   vars: Record<string, string>,
 ): { url: string; unresolved: string[] } {
-  const baseUrl = (vars["base_url"] ?? "").replace(/\/+$/, "");
-  const templated = `${baseUrl}${convertPath(ep.path)}`;
+  const templated = joinBaseAndPath(vars["base_url"], convertPath(ep.path));
   const url = String(substituteString(templated, vars));
   const unresolved = Array.from(url.matchAll(/\{\{([^}]+)\}\}/g)).map(m => m[1]!);
   return { url, unresolved };
 }
 
 /**
- * Standard probe headers: JSON content-type/accept plus the resolved
- * auth header for the endpoint. Empty `liveAuthHeaders` is fine — the
- * spread is a no-op for unauthenticated endpoints.
+ * Standard probe headers: content-type from the endpoint's spec
+ * (form-urlencoded for Stripe v1, JSON otherwise) plus the resolved
+ * auth header for the endpoint. Accept stays JSON — the server still
+ * answers in JSON even when the body is form-encoded. Empty
+ * `liveAuthHeaders` is fine — the spread is a no-op for unauthenticated
+ * endpoints.
  */
-export function buildJsonAuthHeaders(
-  ep: EndpointInfo,
-  schemes: SecuritySchemeInfo[],
-  vars: Record<string, string>,
-): Record<string, string> {
-  return {
-    "content-type": "application/json",
-    accept: "application/json",
-    ...liveAuthHeaders(ep, schemes, vars),
-  };
-}
-
-/** ARV-150: like buildJsonAuthHeaders but picks the Content-Type from the
- *  endpoint's spec (form-urlencoded for Stripe v1, JSON otherwise). Accept
- *  stays JSON — the server still answers in JSON even when the body is
- *  form-encoded. */
 export function buildBodyAuthHeaders(
   ep: EndpointInfo,
   schemes: SecuritySchemeInfo[],
@@ -108,12 +96,23 @@ export function buildBodyAuthHeaders(
  * substitute live vars. Returns null when the result isn't a JSON
  * object (array / scalar / null) — both probes treat that as a skip
  * reason ("request body not a JSON object").
+ *
+ * ARV-269: when `seedBody` is provided (agent-authored overlay from
+ * `.api-resources.local.yaml`), it wins over `generateFromSchema`.
+ * Strict-validating APIs (Stripe required-field XORs, `expand[]` arrays)
+ * reject random scalars from the generator and the whole verdict becomes
+ * INCONCLUSIVE-baseline; the overlay carries a payload the API actually
+ * accepts. Mirrors the path stateful checks took via `resolveCreateBody`
+ * (`core/checks/checks/_crud-helpers.ts`).
  */
 export function buildBaselineFromSpec(
   ep: EndpointInfo,
   vars: Record<string, string>,
+  seedBody?: SeedBodyConfig,
 ): Record<string, unknown> | null {
-  const raw = ep.requestBodySchema ? generateFromSchema(ep.requestBodySchema) : {};
+  const raw = seedBody && seedBody.body && typeof seedBody.body === "object"
+    ? seedBody.body
+    : (ep.requestBodySchema ? generateFromSchema(ep.requestBodySchema) : {});
   const sub = substituteDeep(raw, vars);
   if (typeof sub !== "object" || sub === null || Array.isArray(sub)) return null;
   return sub as Record<string, unknown>;

package/src/core/probe/security/baseline.ts

@@ -0,0 +1,174 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "../../generator/types.ts";
+import { executeRequest } from "../../runner/http-client.ts";
+import { findGetByIdCounterpart, liveAuthHeaders } from "../shared.ts";
+import { buildProbeUrl, serializeProbeBody } from "../probe-harness.ts";
+import type { ProbeStepOpts, SecurityVerdict } from "./types.ts";
+
+export interface Snapshot {
+  /** Original GET-response body, used to restore state via PUT/PATCH. */
+  body: Record<string, unknown>;
+  /** ETag (if API uses optimistic locking) — sent back as `If-Match` on restore. */
+  etag?: string;
+}
+
+export type BaselineResult =
+  | { kind: "ok"; status: number; body: unknown; headers: Record<string, string> }
+  | { kind: "network"; reason: string };
+
+/**
+ * Baseline send — wraps executeRequest with shape that distinguishes a real
+ * HTTP response from a network error (so the caller can decide whether to
+ * retry partial-body / mark the endpoint unreachable).
+ */
+export async function sendBaseline(
+  ep: EndpointInfo,
+  method: string,
+  url: string,
+  headers: Record<string, string>,
+  body: unknown,
+  opts: ProbeStepOpts,
+): Promise<BaselineResult> {
+  try {
+    // ARV-161: serialize via serializeProbeBody so form-encoded endpoints
+    // get x-www-form-urlencoded payload matching Content-Type.
+    const wire = body && typeof body === "object" && !Array.isArray(body)
+      ? serializeProbeBody(ep, body as Record<string, unknown>).content
+      : JSON.stringify(body);
+    const resp = await executeRequest(
+      { method, url, headers, body: wire },
+      { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+    );
+    return {
+      kind: "ok",
+      status: resp.status,
+      body: resp.body_parsed ?? resp.body,
+      headers: resp.headers ?? {},
+    };
+  } catch (err) {
+    return {
+      kind: "network",
+      reason: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * TASK-151: snapshot original state via GET-by-id counterpart so PUT/PATCH
+ * attacks can be undone. Returns null when there's no usable counterpart
+ * or the response isn't a JSON object.
+ */
+export async function snapshotOriginal(
+  ep: EndpointInfo,
+  allEndpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+  opts: ProbeStepOpts,
+): Promise<Snapshot | null> {
+  const getEp = findGetByIdCounterpart(ep, allEndpoints);
+  if (!getEp) return null;
+  const { url, unresolved } = buildProbeUrl(getEp, vars);
+  if (unresolved.length > 0) return null;
+  const reqHeaders: Record<string, string> = {
+    accept: "application/json",
+    ...liveAuthHeaders(getEp, schemes, vars),
+  };
+  let resp;
+  try {
+    resp = await executeRequest(
+      { method: "GET", url, headers: reqHeaders },
+      { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+    );
+  } catch {
+    return null;
+  }
+  if (resp.status < 200 || resp.status >= 300) return null;
+  const body = resp.body_parsed ?? resp.body;
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+
+  const respHeaders = resp.headers ?? {};
+  const etag =
+    respHeaders["etag"] ??
+    respHeaders["ETag"] ??
+    respHeaders["Etag"];
+
+  return {
+    body: body as Record<string, unknown>,
+    etag: typeof etag === "string" ? etag : undefined,
+  };
+}
+
+/**
+ * Restore the original state captured by `snapshotOriginal`. Sends a
+ * minimal PUT/PATCH containing only the fields the probe mutated —
+ * sending the full snapshot body trips `422 use partial PUT` on
+ * SaaS-shaped APIs (round-4 regression), so we replay each
+ * dirty field as its own single-key request.
+ *
+ * `verdict.cleanup.error` is **accumulated** across calls (not
+ * overwritten) so a single restore failure during the run is still
+ * visible in the digest.
+ */
+export async function restoreOriginal(
+  ep: EndpointInfo,
+  snapshot: Snapshot,
+  baseHeaders: Record<string, string>,
+  _schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+  opts: ProbeStepOpts,
+  verdict: SecurityVerdict,
+  dirtyFields: Iterable<string>,
+): Promise<void> {
+  const m = ep.method.toUpperCase();
+  const { url, unresolved } = buildProbeUrl(ep, vars);
+  if (unresolved.length > 0) return;
+  const headers: Record<string, string> = { ...baseHeaders };
+  if (snapshot.etag && ep.requiresEtag) {
+    headers["If-Match"] = snapshot.etag;
+  }
+  // Filter out fields the API will reject as read-only.
+  const READ_ONLY = new Set([
+    "id", "created_at", "createdAt", "updated_at", "updatedAt",
+  ]);
+  const fields = Array.from(new Set(Array.from(dirtyFields))).filter(
+    f => !READ_ONLY.has(f) && f in snapshot.body,
+  );
+
+  // Per-field PUT — works for both partial-PUT APIs and
+  // full-PUT APIs (the body just carries one of the legal keys).
+  const failures: string[] = [];
+  let lastSuccessStatus = 0;
+  let attempted = false;
+  for (const field of fields) {
+    attempted = true;
+    const body: Record<string, unknown> = { [field]: snapshot.body[field] };
+    let resp;
+    try {
+      resp = await executeRequest(
+        { method: m, url, headers, body: serializeProbeBody(ep, body).content },
+        { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+      );
+    } catch (err) {
+      failures.push(
+        `restore.${field} network error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      continue;
+    }
+    if (resp.status < 200 || resp.status >= 300) {
+      failures.push(`restore.${field} failed: ${resp.status}`);
+      continue;
+    }
+    lastSuccessStatus = resp.status;
+  }
+
+  // Merge with any prior cleanup state on this verdict.
+  const prior = verdict.cleanup ?? { attempted: false };
+  const allErrors = [
+    ...(prior.error ? [prior.error] : []),
+    ...failures,
+  ];
+  verdict.cleanup = {
+    attempted: attempted || prior.attempted,
+    ...(lastSuccessStatus ? { status: lastSuccessStatus } : prior.status ? { status: prior.status } : {}),
+    ...(allErrors.length > 0 ? { error: allErrors.join(" | ") } : {}),
+  };
+}

package/src/core/probe/security/classify.ts

@@ -0,0 +1,341 @@
+import type { EndpointInfo } from "../../generator/types.ts";
+import { classify as classifyRecommendedAction } from "../../classifier/recommended-action.ts";
+import type {
+  SecurityClass,
+  SecurityFieldHit,
+  SecurityFinding,
+} from "./types.ts";
+
+/** ARV-56: route through the single classifier. */
+function stampAction(f: SecurityFinding): SecurityFinding {
+  const action = classifyRecommendedAction({
+    finding_class: "probe:security",
+    severity: f.severity as Parameters<typeof classifyRecommendedAction>[0]["severity"],
+  });
+  if (action) f.recommended_action = action;
+  return f;
+}
+
+export interface ClassifyResp {
+  status: number;
+  body?: unknown;
+  body_parsed?: unknown;
+  headers?: Record<string, string>;
+}
+
+export function classify(
+  hit: SecurityFieldHit,
+  payload: string,
+  resp: ClassifyResp,
+  ctx: { endpoint?: EndpointInfo } = {},
+): SecurityFinding {
+  return stampAction(classifyInner(hit, payload, resp, ctx));
+}
+
+/**
+ * ARV-254: detect whether an endpoint declares delivery semantics for
+ * a URL field — i.e. the server is documented to actually hit the URL
+ * (webhook receiver, push subscription, callback).
+ *
+ * Without OOB infrastructure (interactsh / Burp Collaborator —
+ * deferred to ARV-177 post-pivot), zond can't prove the server fetched
+ * the URL. So SSRF "accept" lands as LOW by default. But if the spec
+ * declares delivery, we know the URL gets fetched on some schedule,
+ * which raises the stakes — surface as MEDIUM with an explicit
+ * disclaimer that OOB verification is still required for HIGH.
+ *
+ * Heuristic: path or tag contains "webhook" / "callback" / "subscription"
+ * (case-insensitive). When ARV-189 lands, this also reads
+ * `x-zond-delivery: true` from the spec.
+ */
+function endpointDeclaresDelivery(ep: EndpointInfo | undefined): boolean {
+  if (!ep) return false;
+  const haystacks: string[] = [ep.path.toLowerCase()];
+  if (Array.isArray(ep.tags)) {
+    for (const t of ep.tags) haystacks.push(String(t).toLowerCase());
+  }
+  return haystacks.some((h) => /webhook|callback|subscription/.test(h));
+}
+
+/**
+ * Check whether the CRLF payload reflects into any response header
+ * value. ARV-253: header reflection is the smoking gun for CRLF —
+ * response splitting / header injection becomes exploitable as soon as
+ * the server emits attacker-controlled bytes in headers.
+ *
+ * We check raw payload AND its URL-decoded form so encodings like
+ * `%0d%0a` survive the comparison.
+ */
+function reflectsInHeaders(payload: string, headers: Record<string, string> | undefined): string | null {
+  if (!headers || !payload) return null;
+  const decoded = safeDecodeURI(payload);
+  const variants = [payload, decoded].filter((v) => v && v.length >= 3);
+  for (const [name, value] of Object.entries(headers)) {
+    for (const v of variants) {
+      if (value.includes(v)) return name;
+    }
+  }
+  return null;
+}
+
+function isHtmlContentType(headers: Record<string, string> | undefined): boolean {
+  const ct = headers?.["content-type"] ?? headers?.["Content-Type"] ?? "";
+  return /text\/html|application\/xhtml/i.test(ct);
+}
+
+function classifyInner(
+  hit: SecurityFieldHit,
+  payload: string,
+  resp: ClassifyResp,
+  ctx: { endpoint?: EndpointInfo } = {},
+): SecurityFinding {
+  const status = resp.status;
+  const echo = classifyEcho(resp.body_parsed ?? resp.body, payload, hit.class);
+  const echoed = echo.matched;
+
+  if (status >= 500) {
+    // ARV-250: 5xx on attack payload is a reliability signal, not a
+    // proven security issue. Single-signal proof (one crashed response)
+    // caps severity at LOW per the m-21 severity matrix. ARV-251
+    // relocates this signal to the reliability category; the existing
+    // `not_a_server_error` check already tracks 5xx on positive input,
+    // so the security probe here is a secondary signal at best.
+    return {
+      field: hit.field,
+      class: hit.class,
+      payload,
+      status,
+      echoed,
+      severity: "low",
+      reason: `5xx unhandled — server crashed on ${hit.class} payload (reliability signal; see also not_a_server_error check)`,
+    };
+  }
+  if (status >= 200 && status < 300) {
+    // ARV-253: CRLF severity now keyed on reflection context, not on
+    // raw echo. The pivot principle: HIGH requires evidence the stored
+    // payload reaches a dangerous rendering context (header value /
+    // unescaped HTML). Echo in a JSON body alone is single_signal —
+    // storage is real, exploit pathway is not. Caps at LOW.
+    if (hit.class === "crlf") {
+      const headerName = reflectsInHeaders(payload, resp.headers);
+      if (headerName) {
+        return {
+          field: hit.field,
+          class: hit.class,
+          payload,
+          status,
+          echoed: true,
+          severity: "high",
+          reason: `payload reflected in response header \`${headerName}\` — response-splitting / header-injection candidate (evidence_chain)`,
+        };
+      }
+      if (echoed && isHtmlContentType(resp.headers)) {
+        return {
+          field: hit.field,
+          class: hit.class,
+          payload,
+          status,
+          echoed,
+          severity: "high",
+          reason: `payload echoed (${echo.kind}) in text/html response — unescaped reflection candidate (evidence_chain)`,
+        };
+      }
+      if (echoed) {
+        return {
+          field: hit.field,
+          class: hit.class,
+          payload,
+          status,
+          echoed,
+          severity: "low",
+          reason: `payload echoed (${echo.kind}) in JSON body — storage observed, no dangerous-context reflection. Manual follow-up: check whether the stored value reaches a downstream renderer (HTML page, RSS, custom header).`,
+        };
+      }
+      return {
+        field: hit.field,
+        class: hit.class,
+        payload,
+        status,
+        echoed: false,
+        severity: "info",
+        reason: `${status} accepted ${hit.class} payload but no reflection observed — sanitization may be missing but no exploit pathway proven`,
+      };
+    }
+    // ARV-254: SSRF / open-redirect severity rebalance.
+    //
+    // Without an out-of-band (OOB) channel zond can't prove the server
+    // actually fetched the injected URL. "API accepted 169.254" is
+    // single_signal proof — caps at LOW per the m-21 matrix.
+    //
+    // Stake-raising signal: when the spec declares delivery semantics
+    // (path/tag mentions webhook / callback / subscription), the server
+    // is documented to fetch the URL — surface MEDIUM. Full HIGH is
+    // gated on OOB confirmation which lands with ARV-177 (deferred-
+    // post-pivot, out of scope for now).
+    const declaresDelivery = endpointDeclaresDelivery(ctx.endpoint);
+    const oobDisclaimer = "no OOB channel — accept ≠ proven fetch. Verify with Burp Collaborator / interactsh manually for HIGH severity.";
+    if (echoed) {
+      const label = echo.kind === "verbatim"
+        ? "payload echoed verbatim"
+        : `payload echoed (${echo.kind})`;
+      if (declaresDelivery) {
+        return {
+          field: hit.field,
+          class: hit.class,
+          payload,
+          status,
+          echoed,
+          severity: "low",
+          reason: `${label}; ${hit.class}: endpoint declares delivery (webhook/callback) but ${oobDisclaimer}`,
+        };
+      }
+      return {
+        field: hit.field,
+        class: hit.class,
+        payload,
+        status,
+        echoed,
+        severity: "low",
+        reason: `${label} — stored ${hit.class} candidate; ${oobDisclaimer}`,
+      };
+    }
+    if (declaresDelivery) {
+      return {
+        field: hit.field,
+        class: hit.class,
+        payload,
+        status,
+        echoed,
+        severity: "medium",
+        reason: `2xx accepted ${hit.class} payload on endpoint declaring delivery semantics (webhook/callback). ${oobDisclaimer}`,
+      };
+    }
+    return {
+      field: hit.field,
+      class: hit.class,
+      payload,
+      status,
+      echoed,
+      severity: "low",
+      reason: `2xx accepted ${hit.class} payload but no echo observed. ${oobDisclaimer}`,
+    };
+  }
+  if (status >= 400) {
+    return {
+      field: hit.field,
+      class: hit.class,
+      payload,
+      status,
+      echoed,
+      severity: "ok",
+      reason: `${status} rejected — ${hit.class} payload refused`,
+    };
+  }
+  return {
+    field: hit.field,
+    class: hit.class,
+    payload,
+    status,
+    echoed,
+    severity: "inconclusive",
+    reason: `unexpected status ${status}`,
+  };
+}
+
+function bodyToString(body: unknown): string {
+  if (!body) return "";
+  if (typeof body === "string") return body;
+  // Walk object/array, concatenating raw string leaves so CR/LF chars aren't
+  // hidden behind JSON escape sequences (\r → "\\r" after JSON.stringify).
+  const parts: string[] = [];
+  const seen = new WeakSet<object>();
+  const visit = (v: unknown): void => {
+    if (typeof v === "string") parts.push(v);
+    else if (v && typeof v === "object") {
+      if (seen.has(v as object)) return;
+      seen.add(v as object);
+      if (Array.isArray(v)) v.forEach(visit);
+      else for (const k of Object.keys(v as object)) visit((v as Record<string, unknown>)[k]);
+    }
+  };
+  try {
+    visit(body);
+  } catch {
+    return "";
+  }
+  return parts.join("\n");
+}
+
+function safeDecodeURI(s: string): string {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+
+type EchoKind =
+  | "verbatim"
+  | "url-decoded"
+  | "CR stripped"
+  | "LF stripped"
+  | "CRLF→LF"
+  | "CRLF→CR"
+  | "tail after CRLF";
+
+export interface EchoResult {
+  matched: boolean;
+  kind: EchoKind | "none";
+}
+
+export function classifyEcho(body: unknown, payload: string, cls: SecurityClass): EchoResult {
+  if (!payload) return { matched: false, kind: "none" };
+  const haystackRaw = bodyToString(body);
+  if (!haystackRaw) return { matched: false, kind: "none" };
+
+  // SSRF / open-redirect: verbatim only — URLs are usually preserved as-is.
+  if (cls !== "crlf") {
+    return haystackRaw.includes(payload)
+      ? { matched: true, kind: "verbatim" }
+      : { matched: false, kind: "none" };
+  }
+
+  // CRLF: try verbatim → URL-decode pairs → CR/LF normalization variants → tail.
+  if (haystackRaw.includes(payload)) return { matched: true, kind: "verbatim" };
+
+  const haystackDecoded = safeDecodeURI(haystackRaw);
+  const payloadDecoded = safeDecodeURI(payload);
+
+  if (
+    (payloadDecoded !== payload && haystackRaw.includes(payloadDecoded)) ||
+    (haystackDecoded !== haystackRaw && haystackDecoded.includes(payload)) ||
+    (payloadDecoded !== payload && haystackDecoded !== haystackRaw && haystackDecoded.includes(payloadDecoded))
+  ) {
+    return { matched: true, kind: "url-decoded" };
+  }
+
+  // Normalize: try variants of payload where backend stripped CR or LF.
+  const variants: Array<[string, EchoKind]> = [];
+  if (payloadDecoded.includes("\r\n")) {
+    variants.push([payloadDecoded.replace(/\r\n/g, "\n"), "CRLF→LF"]);
+    variants.push([payloadDecoded.replace(/\r\n/g, "\r"), "CRLF→CR"]);
+    variants.push([payloadDecoded.replace(/\r\n/g, ""), "CRLF→LF"]);
+  }
+  if (payloadDecoded.includes("\r")) variants.push([payloadDecoded.replace(/\r/g, ""), "CR stripped"]);
+  if (payloadDecoded.includes("\n")) variants.push([payloadDecoded.replace(/\n/g, ""), "LF stripped"]);
+
+  for (const [variant, kind] of variants) {
+    if (variant && variant !== payloadDecoded && (haystackRaw.includes(variant) || haystackDecoded.includes(variant))) {
+      return { matched: true, kind };
+    }
+  }
+
+  // Tail-substring: parser truncated at newline, only suffix landed in storage.
+  const splitMatch = payloadDecoded.match(/(?:\r\n|%0d%0a|%0a|%0d|\r|\n)(.+)$/i);
+  const tail = splitMatch?.[1];
+  if (tail && tail.length >= 3 && (haystackRaw.includes(tail) || haystackDecoded.includes(tail))) {
+    return { matched: true, kind: "tail after CRLF" };
+  }
+
+  return { matched: false, kind: "none" };
+}