@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/checks/checks/pagination_invariants.ts

@@ -0,0 +1,238 @@
+/**
+ * `pagination_invariants` (m-20 ARV-171) — cursor-style page consistency.
+ *
+ * For each CRUD group whose list endpoint declares a pagination block
+ * (or has a recognisable cursor-style query param in the spec):
+ *
+ *   1. GET ?limit=N → page A.
+ *   2. Pick the last item's cursor field (default `id`).
+ *   3. GET ?<cursor_param>=<last_id>&limit=N → page B.
+ *
+ * Assertions:
+ *   • A∩B disjoint by cursor_field — no item appears on both pages.
+ *   • has_more consistency — if B is empty, has_more must be false.
+ *   • A.length == limit when page A advertises has_more=true — a partial
+ *     first page with has_more=true is a server bug.
+ *
+ * Severity policy: HIGH. The dominant signal class is duplicates (data
+ * loss / off-by-one); has_more inconsistency surfaces in the same
+ * finding via `evidence.kind`.
+ *
+ * Anti-FP guards:
+ *   • Page A empty → skip ("empty collection — no data to paginate").
+ *   • Cursor field missing on last item → skip with reason naming the
+ *     field so the operator can fix the yaml.
+ *   • 4xx/5xx on either page → broken-baseline skip.
+ *   • Concurrent writes can race the probe; this MVP doesn't double-
+ *     sweep yet (ARV-171 acceptance #2 calls for it). A second sweep
+ *     wrapper will land alongside the data-quality work in ARV-187 —
+ *     today the finding is gated on cursor-field disjointness which is
+ *     much harder to false-positive than counter checks.
+ *
+ * Pagination types other than `cursor`: skip with explicit reason so
+ * `page` / `offset` / `token` callers know the yaml block parsed but
+ * the check has no logic for them yet.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { CrudStatefulCheck } from "../stateful.ts";
+import type { PaginationConfig } from "../../generator/resources-builder.ts";
+import { fillPathParams } from "./_crud-helpers.ts";
+
+/** Cursor-style query params we recognise on auto-detect (Stripe,
+ *  GitHub, Resend, Linear). Lower-cased for case-insensitive match. */
+const CURSOR_QUERY_NAMES = new Set([
+  "starting_after",
+  "after",
+  "cursor",
+  "page_token",
+  "next_cursor",
+]);
+
+const DEFAULT_LIMIT_PARAM = "limit";
+const DEFAULT_CURSOR_FIELD = "id";
+const DEFAULT_HAS_MORE_FIELD = "has_more";
+/** Probe page size — small so two requests land fast and (more
+ *  importantly) so the probe doesn't repeatedly hammer a 1000-item
+ *  endpoint just to assert "no duplicates on consecutive pages". */
+const DEFAULT_LIMIT = 2;
+const ITEMS_FIELD_FALLBACKS: ReadonlyArray<string> = ["data", "items", "results", "value"];
+
+function safeParse(v: unknown): unknown {
+  if (typeof v !== "string") return v;
+  try { return JSON.parse(v); } catch { return v; }
+}
+
+function detectCursorParam(list: { parameters: OpenAPIV3.ParameterObject[] }): string | null {
+  for (const p of list.parameters) {
+    if (p.in !== "query") continue;
+    if (CURSOR_QUERY_NAMES.has(p.name.toLowerCase())) return p.name;
+  }
+  return null;
+}
+
+function resolveConfig(
+  cfg: PaginationConfig | undefined,
+  list: { parameters: OpenAPIV3.ParameterObject[] },
+): { type: "cursor"; cursorParam: string; cursorField: string; hasMoreField: string; limitParam: string; limit: number; itemsField: string | null } | { type: PaginationConfig["type"]; reason: string } | null {
+  const type = cfg?.type ?? "cursor";
+  if (type !== "cursor") {
+    return { type, reason: `pagination type "${type}" not implemented yet — cursor-style only in this milestone` };
+  }
+  const cursorParam = cfg?.cursorParam ?? detectCursorParam(list);
+  if (!cursorParam) return null;
+  return {
+    type: "cursor",
+    cursorParam,
+    cursorField: cfg?.cursorField ?? DEFAULT_CURSOR_FIELD,
+    hasMoreField: cfg?.hasMoreField ?? DEFAULT_HAS_MORE_FIELD,
+    limitParam: cfg?.limitParam ?? DEFAULT_LIMIT_PARAM,
+    limit: cfg?.defaultLimit ?? DEFAULT_LIMIT,
+    itemsField: cfg?.itemsField ?? null,
+  };
+}
+
+/** Find the array-of-items in a list response. Tries the explicit
+ *  yaml field first, then a small set of common shapes. Returns null
+ *  when the body shape is not recognisable. */
+function extractItems(body: unknown, itemsField: string | null): unknown[] | null {
+  if (Array.isArray(body)) return body;
+  if (!body || typeof body !== "object") return null;
+  const obj = body as Record<string, unknown>;
+  if (itemsField) {
+    const v = obj[itemsField];
+    return Array.isArray(v) ? v : null;
+  }
+  for (const f of ITEMS_FIELD_FALLBACKS) {
+    const v = obj[f];
+    if (Array.isArray(v)) return v;
+  }
+  return null;
+}
+
+function readHasMore(body: unknown, field: string): boolean | undefined {
+  if (!body || typeof body !== "object") return undefined;
+  const v = (body as Record<string, unknown>)[field];
+  return typeof v === "boolean" ? v : undefined;
+}
+
+function pickCursor(item: unknown, field: string): string | number | null {
+  if (item == null || typeof item !== "object") return null;
+  const v = (item as Record<string, unknown>)[field];
+  if (typeof v === "string" || typeof v === "number") return v;
+  return null;
+}
+
+function buildUrl(base: string, path: string, pathVars: Record<string, string> | undefined, qs: Record<string, string | number>): string {
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(qs)) params.append(k, String(v));
+  return `${base.replace(/\/+$/, "")}${fillPathParams(path, pathVars)}?${params.toString()}`;
+}
+
+export const paginationInvariants: CrudStatefulCheck = {
+  id: "pagination_invariants",
+  severity: "high",
+  defaultExpected: "Consecutive cursor pages must be disjoint and has_more must agree with item presence",
+  references: [{ id: "ARV-171" }],
+  phase: "crud",
+  applies(g) {
+    return Boolean(g.list);
+  },
+  async run(g, h) {
+    if (h.bootstrapCleanupFailed) {
+      return { kind: "skip", reason: "bootstrap-cleanup failed — stateful checks paused" };
+    }
+    const list = g.list!;
+
+    const cfg = h.resourceConfigs?.get(g.resource)?.pagination;
+    const resolved = resolveConfig(cfg, list);
+    if (resolved == null) {
+      return { kind: "skip", reason: "no pagination config and no cursor-style query param in spec" };
+    }
+    if ("reason" in resolved) {
+      return { kind: "skip", reason: resolved.reason };
+    }
+
+    const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+    const urlA = buildUrl(h.baseUrl, list.path, h.pathVars, { [resolved.limitParam]: resolved.limit });
+
+    const rA = await h.send({ method: "GET", url: urlA, headers: baseHeaders });
+    if (rA.status < 200 || rA.status >= 300) {
+      return { kind: "skip", reason: `page A returned ${rA.status} — broken-baseline guard` };
+    }
+    const bodyA = rA.body_parsed ?? safeParse(rA.body);
+    const itemsA = extractItems(bodyA, resolved.itemsField);
+    if (itemsA == null) {
+      return { kind: "skip", reason: `page A: items array not found (tried items_field="${resolved.itemsField ?? "auto"}" + defaults)` };
+    }
+    if (itemsA.length === 0) {
+      return { kind: "skip", reason: "page A empty — no data to paginate" };
+    }
+
+    const hasMoreA = readHasMore(bodyA, resolved.hasMoreField);
+    const partialPageWithMore = hasMoreA === true && itemsA.length < resolved.limit;
+
+    const lastCursor = pickCursor(itemsA[itemsA.length - 1], resolved.cursorField);
+    if (lastCursor == null) {
+      return { kind: "skip", reason: `cursor field "${resolved.cursorField}" missing on last item of page A` };
+    }
+
+    const urlB = buildUrl(h.baseUrl, list.path, h.pathVars, {
+      [resolved.limitParam]: resolved.limit,
+      [resolved.cursorParam]: lastCursor,
+    });
+    const rB = await h.send({ method: "GET", url: urlB, headers: baseHeaders });
+    if (rB.status < 200 || rB.status >= 300) {
+      return { kind: "skip", reason: `page B returned ${rB.status} — broken-baseline guard` };
+    }
+    const bodyB = rB.body_parsed ?? safeParse(rB.body);
+    const itemsB = extractItems(bodyB, resolved.itemsField);
+    if (itemsB == null) {
+      return { kind: "skip", reason: "page B: items array shape changed between pages" };
+    }
+    const hasMoreB = readHasMore(bodyB, resolved.hasMoreField);
+
+    const idsA = new Set<string>();
+    for (const it of itemsA) {
+      const c = pickCursor(it, resolved.cursorField);
+      if (c != null) idsA.add(String(c));
+    }
+    const duplicates: string[] = [];
+    for (const it of itemsB) {
+      const c = pickCursor(it, resolved.cursorField);
+      if (c != null && idsA.has(String(c))) duplicates.push(String(c));
+    }
+
+    // has_more must be false on the page that ran out of items.
+    const inconsistentHasMore = itemsB.length === 0 && hasMoreA === true && hasMoreB !== false;
+
+    if (duplicates.length === 0 && !inconsistentHasMore && !partialPageWithMore) {
+      return { kind: "pass" };
+    }
+
+    const kinds: string[] = [];
+    if (duplicates.length > 0) kinds.push("duplicate_items");
+    if (inconsistentHasMore) kinds.push("has_more_inconsistent");
+    if (partialPageWithMore) kinds.push("partial_page_with_has_more");
+
+    return {
+      kind: "fail",
+      message:
+        duplicates.length > 0
+          ? `Pagination on ${g.resource}: ${duplicates.length} item id(s) appear on both pages (${duplicates.slice(0, 3).join(", ")}${duplicates.length > 3 ? ", …" : ""})`
+          : inconsistentHasMore
+            ? `Pagination on ${g.resource}: page A advertised has_more=true but page B is empty with has_more!=false`
+            : `Pagination on ${g.resource}: page A has ${itemsA.length}/${resolved.limit} items yet has_more=true (partial page with more)`,
+      evidence: {
+        resource: g.resource,
+        kind: kinds.join("+"),
+        cursor_param: resolved.cursorParam,
+        cursor_field: resolved.cursorField,
+        page_a_size: itemsA.length,
+        page_b_size: itemsB.length,
+        has_more_a: hasMoreA,
+        has_more_b: hasMoreB,
+        duplicates,
+      },
+    };
+  },
+};

package/src/core/checks/checks/positive_data_acceptance.ts

@@ -0,0 +1,36 @@
+/**
+ * `positive_data_acceptance` (m-15 ARV-4) — schemathesis-equivalent.
+ * Runs against the standard positive case (kind="positive"). When the
+ * server *rejects* a generated-as-valid body with a schema-validation
+ * status (400 / 422), it's either our generator was wrong or the spec
+ * is over-strict — both worth flagging.
+ *
+ * Auth/lookup statuses (401/403/404/409) are skipped: they aren't
+ * schema-validation rejects. 5xx is skipped here too because
+ * `not_a_server_error` already covers it.
+ */
+import type { Check } from "../types.ts";
+import { applyAntiFp } from "../../anti-fp/index.ts";
+
+export const positiveDataAcceptance: Check = {
+  id: "positive_data_acceptance",
+  severity: "medium",
+  defaultExpected: "Server must accept a generated-as-valid body (2xx)",
+  references: [{ id: "OWASP-API-08" }],
+  applies: (op) => Boolean(op.requestBodySchema),
+  run({ case: c, response }) {
+    const s = response.status;
+    if (s >= 200 && s < 300) return { kind: "pass" };
+    // Auth / not-found / conflict / server-error → not a schema-rejection signal.
+    if (s === 401 || s === 403 || s === 404 || s === 409) return { kind: "pass" };
+    if (s >= 500) return { kind: "skip", reason: "5xx covered by not_a_server_error" };
+    if (s !== 400 && s !== 422) return { kind: "skip", reason: `status ${s} not a schema-validation reject` };
+    const skip = applyAntiFp(c, "check:positive_data_acceptance");
+    if (skip) return { kind: "skip", reason: `${skip.ruleId}: ${skip.reason}` };
+    return {
+      kind: "fail",
+      message: `Server rejected a generated-as-valid body with ${s} — generator or spec disagrees with the implementation`,
+      evidence: { status: s },
+    };
+  },
+};

package/src/core/checks/checks/rate_limit_headers_absent.ts

@@ -0,0 +1,77 @@
+/**
+ * `rate_limit_headers_absent` (ARV-256, m-21 pivot) — flag mutating
+ * endpoints (POST/PATCH/PUT/DELETE) whose 2xx responses ship no
+ * rate-limit-* headers at all.
+ *
+ * The full version of this check would burst N requests to detect a
+ * 429, but bursting POST creates real resources — too destructive for
+ * a default-on check. The lightweight header-inspect version is what
+ * Burp/ZAP also do at first pass: detect the absence of standard
+ * rate-limit metadata in the response. If the server emits any of
+ * `X-RateLimit-*` / `RateLimit-*` / `Retry-After`, this check skips —
+ * the server has *some* rate-limit story.
+ *
+ * Reliability category (ARV-251): missing rate-limit on write
+ * endpoints is a production concern (abuse → bill, abuse → DoS), not
+ * a security exploit. Severity MEDIUM by default.
+ *
+ * Anti-FP: skip non-mutating methods. Skip non-2xx responses (a 4xx
+ * doesn't tell us anything about rate-limit behaviour on the happy
+ * path). Skip endpoints with `security: []` override (public read-only
+ * APIs may intentionally omit rate-limit headers).
+ */
+import type { Check } from "../types.ts";
+
+const RATE_LIMIT_PATTERNS: RegExp[] = [
+  /^x-ratelimit-/i,
+  /^x-rate-limit-/i,
+  /^ratelimit-/i,
+  /^retry-after$/i,
+];
+
+function hasRateLimitHeader(headers: Record<string, string>): boolean {
+  for (const name of Object.keys(headers)) {
+    for (const re of RATE_LIMIT_PATTERNS) {
+      if (re.test(name)) return true;
+    }
+  }
+  return false;
+}
+
+const MUTATING = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+
+export const rateLimitHeadersAbsent: Check = {
+  id: "rate_limit_headers_absent",
+  severity: "medium",
+  defaultExpected:
+    "Mutating endpoints should advertise rate-limit semantics via X-RateLimit-* / RateLimit-* / Retry-After headers",
+  references: [
+    { id: "RFC-9239-rate-limit-headers" },
+    { id: "OWASP-API-04-rate-limit" },
+  ],
+  applies(op) {
+    if (!MUTATING.has(op.method.toUpperCase())) return false;
+    // Skip explicitly-public endpoints (security: [] override) — those
+    // are often abuse-tolerant by design (anonymous feedback forms etc).
+    if (op.security.length === 0) return false;
+    return true;
+  },
+  run({ response }) {
+    if (response.status < 200 || response.status >= 300) {
+      return { kind: "skip", reason: `non-2xx response (${response.status}) — rate-limit semantics only meaningful on success` };
+    }
+    if (hasRateLimitHeader(response.headers)) {
+      return { kind: "pass" };
+    }
+    return {
+      kind: "fail",
+      message:
+        "Mutating endpoint returned 2xx without any rate-limit-* / Retry-After header — no advertised abuse protection on a write path",
+      evidence: {
+        method: "POST/PUT/PATCH/DELETE",
+        response_status: response.status,
+        looked_for: ["X-RateLimit-*", "RateLimit-*", "Retry-After"],
+      },
+    };
+  },
+};

package/src/core/checks/checks/response_headers_conformance.ts

@@ -0,0 +1,74 @@
+/**
+ * `response_headers_conformance` — every response header declared in
+ * the OpenAPI `responses[<status>].headers` map must be present, and
+ * (when a schema is given) its value must validate. Schemathesis-style.
+ *
+ * For the check to mean anything, the spec has to declare some
+ * headers; if it declares none, the check skips. Validation is shallow
+ * here (string presence + simple type/format match) — full ajv
+ * validation lands alongside ARV-5/ARV-6 once we cache validators per
+ * (status, header) pair without paying compile cost per response.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { Check } from "../types.ts";
+
+function getDeclaredHeaders(
+  doc: OpenAPIV3.Document,
+  path: string,
+  method: string,
+  status: number,
+): Record<string, OpenAPIV3.HeaderObject> {
+  const op = (doc.paths?.[path] as OpenAPIV3.PathItemObject | undefined)
+    ?.[method.toLowerCase() as OpenAPIV3.HttpMethods] as OpenAPIV3.OperationObject | undefined;
+  if (!op?.responses) return {};
+  const exact = op.responses[String(status)] as OpenAPIV3.ResponseObject | undefined;
+  const wildcard = op.responses[`${Math.floor(status / 100)}XX`] as OpenAPIV3.ResponseObject | undefined;
+  const fallback = op.responses.default as OpenAPIV3.ResponseObject | undefined;
+  const branch = exact ?? wildcard ?? fallback;
+  return (branch?.headers ?? {}) as Record<string, OpenAPIV3.HeaderObject>;
+}
+
+function valueOk(value: string | undefined, header: OpenAPIV3.HeaderObject): boolean {
+  if (value === undefined) return false;
+  const schema = header.schema as OpenAPIV3.SchemaObject | undefined;
+  if (!schema) return true;
+  if (schema.type === "integer") return /^-?\d+$/.test(value);
+  if (schema.type === "number") return /^-?\d+(\.\d+)?$/.test(value);
+  if (schema.type === "boolean") return value === "true" || value === "false";
+  return true;
+}
+
+export const responseHeadersConformance: Check = {
+  id: "response_headers_conformance",
+  severity: "low",
+  defaultExpected: "All headers declared on the response must be present and shape-valid",
+  references: [{ id: "OAS3-headerObject" }],
+  applies: () => true,
+  run({ case: c, response, doc }) {
+    if (!doc) return { kind: "skip", reason: "spec doc not available" };
+    // ARV-183: use originalPath (pre-ARV-40 rename) for spec lookup.
+    const specPath = c.operation.originalPath ?? c.operation.path;
+    const declared = getDeclaredHeaders(doc, specPath, c.operation.method, response.status);
+    const names = Object.keys(declared);
+    if (names.length === 0) return { kind: "skip", reason: "no declared response headers" };
+    const issues: string[] = [];
+    for (const name of names) {
+      const header = declared[name]!;
+      const required = header.required === true;
+      const got = response.headers[name] ?? response.headers[name.toLowerCase()];
+      if (got === undefined) {
+        if (required) issues.push(`missing required "${name}"`);
+        continue;
+      }
+      if (!valueOk(got, header)) {
+        issues.push(`"${name}" value "${got}" doesn't match declared schema`);
+      }
+    }
+    if (issues.length === 0) return { kind: "pass" };
+    return {
+      kind: "fail",
+      message: `Response headers don't conform: ${issues.join("; ")}`,
+      evidence: { issues, declared: names },
+    };
+  },
+};

package/src/core/checks/checks/response_schema_conformance.ts

@@ -0,0 +1,30 @@
+/**
+ * `response_schema_conformance` — body must validate against the JSON
+ * Schema declared on the matched response branch. Reuses the existing
+ * `runner/schema-validator.ts` so we don't rebuild AJV plumbing
+ * (ARV-2 AC #3).
+ */
+import type { Check } from "../types.ts";
+
+export const responseSchemaConformance: Check = {
+  id: "response_schema_conformance",
+  severity: "high",
+  defaultExpected: "Response body must validate against the OpenAPI response schema",
+  references: [{ id: "OAS3-schemaObject" }],
+  applies: () => true,
+  run({ case: c, response, schemaValidator }) {
+    if (!schemaValidator) return { kind: "skip", reason: "validator unavailable" };
+    const inspect = schemaValidator.inspect(c.operation.method, c.operation.path, response.status);
+    if (!inspect.matchedEndpoint) return { kind: "skip", reason: "no spec endpoint matched" };
+    if (!inspect.hasJsonSchema) return { kind: "skip", reason: "no JSON Schema on this response branch" };
+    const results = schemaValidator.validate(c.operation.method, c.operation.path, response.status, response.body);
+    const failed = results.filter((r) => !r.passed);
+    if (failed.length === 0) return { kind: "pass" };
+    const messages = failed.slice(0, 5).map((r) => `${r.field}: expected ${JSON.stringify(r.expected)}`);
+    return {
+      kind: "fail",
+      message: `Response body fails schema validation (${failed.length} issue${failed.length === 1 ? "" : "s"})`,
+      evidence: { issues: messages },
+    };
+  },
+};

package/src/core/checks/checks/status_code_conformance.ts

@@ -0,0 +1,61 @@
+/**
+ * `status_code_conformance` — schemathesis-equivalent. Fails when the
+ * server returns a status code that's not declared in the OpenAPI
+ * `responses` for this operation (and no `default` is declared either).
+ *
+ * Edge: `default` in OpenAPI means "any status not enumerated above" —
+ * the presence of `default` makes every status code conforming. ARV-2
+ * AC #6 explicitly tests this case.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+
+import type { Check } from "../types.ts";
+
+function declaredStatuses(doc: OpenAPIV3.Document, path: string, method: string):
+  { codes: Set<number>; hasDefault: boolean; hasWildcard: Map<number, boolean> } {
+  const codes = new Set<number>();
+  const hasWildcard = new Map<number, boolean>(); // 2,3,4,5 -> declared as 2XX etc.
+  let hasDefault = false;
+  const op = (doc.paths?.[path] as OpenAPIV3.PathItemObject | undefined)
+    ?.[method.toLowerCase() as OpenAPIV3.HttpMethods] as OpenAPIV3.OperationObject | undefined;
+  if (!op?.responses) return { codes, hasDefault, hasWildcard };
+  for (const key of Object.keys(op.responses)) {
+    if (key === "default") { hasDefault = true; continue; }
+    const n = Number.parseInt(key, 10);
+    if (Number.isFinite(n)) { codes.add(n); continue; }
+    // 2XX / 3XX / 4XX / 5XX wildcard keys are valid OpenAPI 3.0 forms.
+    const m = /^([1-5])XX$/i.exec(key);
+    if (m) hasWildcard.set(Number.parseInt(m[1]!, 10), true);
+  }
+  return { codes, hasDefault, hasWildcard };
+}
+
+export const statusCodeConformance: Check = {
+  id: "status_code_conformance",
+  severity: "medium",
+  defaultExpected: "Response status must be declared in the OpenAPI `responses` (or `default`)",
+  references: [{ id: "OAS3-responsesObject", url: "https://spec.openapis.org/oas/v3.0.3#responses-object" }],
+  // ARV-180: status-code conformance is a property of the response, not
+  // of the input. The check must fire on every case kind — including
+  // negative-data, dropped-header, and unsupported-method probes — so
+  // an undocumented 5xx/404/422 on bad input surfaces as a finding
+  // (matches schemathesis V4 default: the check has no input-kind filter).
+  caseKinds: ["positive", "negative_data", "missing_required_header", "unsupported_method"],
+  applies: () => true,
+  run({ case: c, response, doc }) {
+    if (!doc) return { kind: "skip", reason: "spec doc not available" };
+    // ARV-183: ARV-40 path-disambiguation renames {id} → {<resource>_id}
+    // in EndpointInfo.path. doc.paths keeps the original — use
+    // originalPath for spec lookup when present.
+    const specPath = c.operation.originalPath ?? c.operation.path;
+    const { codes, hasDefault, hasWildcard } = declaredStatuses(doc, specPath, c.operation.method);
+    if (hasDefault) return { kind: "pass" };
+    if (codes.has(response.status)) return { kind: "pass" };
+    if (hasWildcard.get(Math.floor(response.status / 100))) return { kind: "pass" };
+    return {
+      kind: "fail",
+      message: `Status ${response.status} not declared in OpenAPI responses for ${c.operation.method} ${c.operation.path}`,
+      evidence: { actual: response.status, declared: [...codes].sort((a, b) => a - b) },
+    };
+  },
+};

package/src/core/checks/checks/unsupported_method.ts

@@ -0,0 +1,63 @@
+/**
+ * `unsupported_method` — the live-running counterpart of the offline
+ * `method-probe`. Sends a method that isn't declared on the path; the
+ * server must reject with a 405 (or 401/403/404 fallback). Shares the
+ * acceptable-status list with the offline probe via `method-shared`
+ * (ARV-2 AC #4).
+ */
+import type { Check } from "../types.ts";
+import {
+  ACCEPTABLE_UNSUPPORTED_STATUSES,
+  isPermissibleOptionsResponse,
+} from "../../probe/method-shared.ts";
+
+const ACCEPTABLE = new Set<number>(ACCEPTABLE_UNSUPPORTED_STATUSES);
+
+export const unsupportedMethod: Check = {
+  id: "unsupported_method",
+  severity: "medium",
+  defaultExpected: "Server must reject undeclared HTTP methods with 405 (or 401/403/404)",
+  references: [{ id: "RFC-9110-15.5.6", url: "https://www.rfc-editor.org/rfc/rfc9110#name-405-method-not-allowed" }],
+  caseKinds: ["unsupported_method"],
+  applies: () => true,
+  run({ case: c, response, options }) {
+    const status = response.status;
+    const undeclared = String(c.meta?.undeclared_method ?? c.request.method);
+    const strict = options?.strict405 === true;
+
+    // ARV-179: OPTIONS 2xx is legitimate CORS preflight behaviour on
+    // almost every framework. Treat as pass even in strict mode — the
+    // m-18 parity replication explicitly ignores OPTIONS responses too.
+    if (isPermissibleOptionsResponse(undeclared, status)) return { kind: "pass" };
+
+    if (strict) {
+      if (status === 405) return { kind: "pass" };
+      return {
+        kind: "fail",
+        message: `Undeclared method ${undeclared} returned ${status} — strict mode requires 405`,
+        evidence: { undeclared_method: undeclared, status, strict_405: true },
+      };
+    }
+
+    if (ACCEPTABLE.has(status)) return { kind: "pass" };
+    if (status >= 200 && status < 300) {
+      return {
+        kind: "fail",
+        message: `Server accepted undeclared method ${undeclared} on ${c.operation.path} (status ${status})`,
+        evidence: { undeclared_method: undeclared, status },
+      };
+    }
+    if (status >= 500) {
+      return {
+        kind: "fail",
+        message: `Server 5xx'd on undeclared method ${undeclared} for ${c.operation.path} — should be 405`,
+        evidence: { undeclared_method: undeclared, status },
+      };
+    }
+    return {
+      kind: "fail",
+      message: `Undeclared method ${undeclared} returned ${status} — expected 405 (or 401/403/404)`,
+      evidence: { undeclared_method: undeclared, status },
+    };
+  },
+};

package/src/core/checks/checks/use_after_free.ts

@@ -0,0 +1,78 @@
+/**
+ * `use_after_free` (m-15 ARV-3) — given a CRUD group with create+read+
+ * delete, create a resource, delete it, then GET by id. The server
+ * must respond 404/410. Any 2xx means the resource is still readable
+ * after a successful DELETE (a classic data-leak / soft-delete bug).
+ */
+import type { CrudStatefulCheck } from "../stateful.ts";
+import { extractIdFromCreateResponse, fillPathWithId, fillPathParams, serializeCheckBody, resolveCreateBody } from "./_crud-helpers.ts";
+
+export const useAfterFree: CrudStatefulCheck = {
+  id: "use_after_free",
+  severity: "high",
+  defaultExpected: "GET on a deleted resource must return 404 or 410",
+  references: [{ id: "CWE-672" }],
+  phase: "crud",
+  applies(g) {
+    return Boolean(g.create && g.read && g.delete);
+  },
+  async run(g, h) {
+    if (h.bootstrapCleanupFailed) {
+      return { kind: "skip", reason: "bootstrap-cleanup failed — security checks paused (ARV-3 AC #6)" };
+    }
+    const create = g.create!;
+    const read = g.read!;
+    const del = g.delete!;
+    const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+
+    // 1. create — ARV-191: respect form-urlencoded so Stripe-style APIs
+    // don't silently broken-baseline-skip every CRUD chain.
+    // ARV-187: prefer LLM-authored seed_body when available.
+    const seedBody = h.resourceConfigs?.get(g.resource)?.seedBody;
+    const generated = resolveCreateBody(create, seedBody) ?? {};
+    const { body: createBody, contentType } = serializeCheckBody(
+      create,
+      generated,
+      h.pathVars,
+      seedBody?.contentType,
+    );
+    const createUrl = `${h.baseUrl.replace(/\/+$/, "")}${fillPathParams(create.path, h.pathVars)}`;
+    const createResp = await h.send({
+      method: "POST",
+      url: createUrl,
+      headers: { ...baseHeaders, "Content-Type": contentType },
+      body: createBody,
+    });
+    if (createResp.status < 200 || createResp.status >= 300) {
+      return { kind: "skip", reason: `create returned ${createResp.status} — broken-baseline guard` };
+    }
+    const id = extractIdFromCreateResponse(createResp.body_parsed ?? createResp.body, g.idParam);
+    if (id == null) return { kind: "skip", reason: "could not extract id from create response" };
+
+    // 2. delete
+    const delResp = await h.send({
+      method: "DELETE",
+      url: `${h.baseUrl.replace(/\/+$/, "")}${fillPathWithId(fillPathParams(del.path, h.pathVars), g.idParam, id)}`,
+      headers: baseHeaders,
+    });
+    if (delResp.status < 200 || delResp.status >= 300) {
+      return { kind: "skip", reason: `delete returned ${delResp.status} — broken-baseline guard` };
+    }
+
+    // 3. read after delete
+    const readResp = await h.send({
+      method: "GET",
+      url: `${h.baseUrl.replace(/\/+$/, "")}${fillPathWithId(fillPathParams(read.path, h.pathVars), g.idParam, id)}`,
+      headers: baseHeaders,
+    });
+    if (readResp.status === 404 || readResp.status === 410) return { kind: "pass" };
+    if (readResp.status >= 200 && readResp.status < 300) {
+      return {
+        kind: "fail",
+        message: `GET on resource ${id} after DELETE returned ${readResp.status} — resource still readable`,
+        evidence: { resource: g.resource, id, get_status_after_delete: readResp.status },
+      };
+    }
+    return { kind: "skip", reason: `read after delete returned ${readResp.status} — neither 404/410 nor 2xx` };
+  },
+};