@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/checks/checks/cross_call_references.ts

@@ -0,0 +1,134 @@
+/**
+ * `cross_call_references` (m-20 ARV-169) — POST→GET shape-diff probe.
+ *
+ * For each CRUD group with create+read, POST a generated body, capture
+ * the new id from the response, then GET the resource and diff the
+ * write-shape against the read-shape. Fields the create accepted (or
+ * echoed) but the read didn't return surface as drift findings — the
+ * server is silently dropping state.
+ *
+ * Severity policy:
+ *   • `state_not_persisted` (POST echoed, GET dropped) is the high-
+ *     signal class, so the check is registered as HIGH.
+ *   • `write_only` (POST accepted, GET never returned) is also surfaced
+ *     in the same finding's evidence. Anti-FP: write-only fields the
+ *     spec explicitly declares are *not* present on GET (e.g. password
+ *     write-only properties) are filtered out via spec.responses.GET
+ *     declared field set.
+ *   • Per-resource quirks (Stripe `metadata` stripping, livemode) are
+ *     declared in `.api-resources[.local].yaml` `readback_diff` blocks
+ *     and the harness threads them through `resourceConfigs`.
+ *
+ * The check fails (one finding) when EITHER list is non-empty. The
+ * evidence carries the per-field breakdown so the reporter can show
+ * exactly which fields drifted and how. We deliberately emit a single
+ * finding per resource — splitting into one-finding-per-field would
+ * inflate counts but tell the user the same story.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { CrudStatefulCheck } from "../stateful.ts";
+import { extractIdFromCreateResponse, fillPathWithId, fillPathParams, serializeCheckBody, resolveCreateBody } from "./_crud-helpers.ts";
+import { computeDrift } from "./_readback-helpers.ts";
+
+function declaredReadFields(read: { responses: Array<{ statusCode: number; schema?: unknown }> }): Set<string> {
+  const success = read.responses.find((r) => r.statusCode >= 200 && r.statusCode < 300);
+  const schema = success?.schema as OpenAPIV3.SchemaObject | undefined;
+  if (!schema?.properties) return new Set();
+  return new Set(Object.keys(schema.properties));
+}
+
+function safeParse(v: unknown): unknown {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+}
+
+export const crossCallReferences: CrudStatefulCheck = {
+  id: "cross_call_references",
+  severity: "high",
+  defaultExpected: "Fields accepted or echoed by POST must be readable via GET on the same resource",
+  references: [{ id: "ARV-169" }, { id: "OWASP-API-3-2023" }],
+  phase: "crud",
+  applies(g) {
+    return Boolean(g.create && g.read);
+  },
+  async run(g, h) {
+    if (h.bootstrapCleanupFailed) {
+      return { kind: "skip", reason: "bootstrap-cleanup failed — stateful checks paused" };
+    }
+    const create = g.create!;
+    const read = g.read!;
+    const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+
+    const seedBody = h.resourceConfigs?.get(g.resource)?.seedBody;
+    if (!create.requestBodySchema && !seedBody) {
+      return { kind: "skip", reason: "create has no requestBody schema and no seed_body — nothing to diff" };
+    }
+    const writeBody = resolveCreateBody(create, seedBody);
+    if (writeBody == null) {
+      return { kind: "skip", reason: "could not produce a create body (no seed_body, generator returned non-object)" };
+    }
+
+    const createUrl = `${h.baseUrl.replace(/\/+$/, "")}${fillPathParams(create.path, h.pathVars)}`;
+    // ARV-191: form-urlencoded dispatch — see _crud-helpers.serializeCheckBody.
+    // ARV-187: seed_body.content_type overrides spec'd contentType when set.
+    const { body: createBodyStr, contentType } = serializeCheckBody(create, writeBody, h.pathVars, seedBody?.contentType);
+    const createResp = await h.send({
+      method: "POST",
+      url: createUrl,
+      headers: { ...baseHeaders, "Content-Type": contentType },
+      body: createBodyStr,
+    });
+    if (createResp.status < 200 || createResp.status >= 300) {
+      return { kind: "skip", reason: `create returned ${createResp.status} — broken-baseline guard` };
+    }
+    const echo = createResp.body_parsed ?? safeParse(createResp.body);
+    const id = extractIdFromCreateResponse(echo, g.idParam);
+    if (id == null) return { kind: "skip", reason: "could not extract id from create response" };
+
+    // Substitute parent-scope vars first (e.g., {organization_id_or_slug}),
+    // then the captured id for {idParam}. Order matters: fillPathWithId's
+    // fallback regex replaces ANY remaining `{...}` with the id, so parent
+    // vars must already be resolved when it runs.
+    const readPath = fillPathWithId(fillPathParams(read.path, h.pathVars), g.idParam, id);
+    const readUrl = `${h.baseUrl.replace(/\/+$/, "")}${readPath}`;
+    const readResp = await h.send({ method: "GET", url: readUrl, headers: baseHeaders });
+    if (readResp.status < 200 || readResp.status >= 300) {
+      return { kind: "skip", reason: `read returned ${readResp.status} — broken-baseline guard` };
+    }
+    const readBody = readResp.body_parsed ?? safeParse(readResp.body);
+
+    const cfg = h.resourceConfigs?.get(g.resource)?.readbackDiff;
+    const specDeclared = declaredReadFields(read);
+    const drift = computeDrift(writeBody, echo, readBody, specDeclared, cfg);
+
+    const stateNotPersisted = drift.stateNotPersisted;
+    const writeOnly = drift.writeOnly;
+    if (stateNotPersisted.length === 0 && writeOnly.length === 0) {
+      return { kind: "pass" };
+    }
+
+    const driftedFields = [
+      ...stateNotPersisted.map((d) => d.field),
+      ...writeOnly.map((d) => d.field),
+    ];
+    return {
+      kind: "fail",
+      message:
+        stateNotPersisted.length > 0
+          ? `POST→GET drift on ${g.resource}: ${stateNotPersisted.length} state-not-persisted field(s)` +
+            (writeOnly.length > 0 ? `, ${writeOnly.length} write-only field(s)` : "")
+          : `POST→GET drift on ${g.resource}: ${writeOnly.length} write-only field(s)`,
+      evidence: {
+        resource: g.resource,
+        id,
+        state_not_persisted: stateNotPersisted.map((d) => ({ field: d.field, written_value: d.writtenValue })),
+        write_only: writeOnly.map((d) => d.field),
+        drifted_fields: driftedFields,
+      },
+    };
+  },
+};

package/src/core/checks/checks/ensure_resource_availability.ts

@@ -0,0 +1,62 @@
+/**
+ * `ensure_resource_availability` (m-15 ARV-3) — create a resource via
+ * POST, then GET by id; the read must succeed (2xx). Catches lost-
+ * write bugs where the create returns 201 but the resource never
+ * actually appears in storage.
+ */
+import type { CrudStatefulCheck } from "../stateful.ts";
+import { extractIdFromCreateResponse, fillPathWithId, fillPathParams, serializeCheckBody, resolveCreateBody } from "./_crud-helpers.ts";
+
+export const ensureResourceAvailability: CrudStatefulCheck = {
+  id: "ensure_resource_availability",
+  severity: "medium",
+  defaultExpected: "GET on a freshly-created resource must succeed (2xx)",
+  references: [{ id: "CWE-924" }],
+  phase: "crud",
+  applies(g) {
+    return Boolean(g.create && g.read);
+  },
+  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 baseHeaders = { Accept: "application/json", ...h.authHeaders };
+    // ARV-191: form-urlencoded vs JSON dispatch — Stripe-style APIs
+    // declare x-www-form-urlencoded; JSON.stringify would yield "400
+    // missing param" the broken-baseline guard then silently swallows.
+    // ARV-187: prefer LLM-authored seed_body over generator.
+    const seedBody = h.resourceConfigs?.get(g.resource)?.seedBody;
+    const generated = resolveCreateBody(create, seedBody) ?? {};
+    const { body, contentType } = serializeCheckBody(
+      create,
+      generated,
+      h.pathVars,
+      seedBody?.contentType,
+    );
+    const createResp = await h.send({
+      method: "POST",
+      url: `${h.baseUrl.replace(/\/+$/, "")}${fillPathParams(create.path, h.pathVars)}`,
+      headers: { ...baseHeaders, "Content-Type": contentType },
+      body,
+    });
+    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" };
+
+    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 >= 200 && readResp.status < 300) return { kind: "pass" };
+    return {
+      kind: "fail",
+      message: `GET on freshly-created resource ${id} returned ${readResp.status}`,
+      evidence: { resource: g.resource, id, create_status: createResp.status, read_status: readResp.status },
+    };
+  },
+};

package/src/core/checks/checks/idempotency_replay.ts

@@ -0,0 +1,246 @@
+/**
+ * `idempotency_replay` (m-20 ARV-170) — Idempotency-Key honor probe.
+ *
+ * For each CRUD group with create+delete where idempotency is opted-in
+ * (either via `.api-resources.yaml` `idempotency:` block or by the
+ * create endpoint declaring an `Idempotency-Key` header parameter),
+ * POST the same body twice with the same key. The server must:
+ *
+ *   1. return the *same* resource id on both calls (id1 == id2 — no
+ *      duplicate created), AND
+ *   2. return bit-identical responses modulo a small allow-list of
+ *      timestamp / request-id fields (R1 == R2).
+ *
+ * Severity policy: HIGH. The two failure classes share one finding —
+ * the runner doesn't support per-finding severity downgrade and
+ * `duplicate_resource` is the dominant signal anyway. `non_bit_identical`
+ * piggybacks via finding.evidence.kind so consumers can split the
+ * digest if they care.
+ *
+ * Anti-FP guards:
+ *   • Skip when the second POST gets a 429 / 409 / 5xx — replay rate
+ *     limiting and locking races confuse the verdict.
+ *   • Skip when either POST fails the broken-baseline check (non-2xx).
+ *   • Cleanup tolerates missing DELETE wiring — emits a warning via
+ *     `cleanup_warning` in evidence.
+ *
+ * Auto-detect fallback: if no yaml block exists but the create endpoint
+ * declares an `Idempotency-Key` header in its `parameters[]`, the check
+ * runs with default settings. Explicit yaml wins — it lets the user
+ * override the header name and customize the ignore list.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { CrudStatefulCheck } from "../stateful.ts";
+import type { IdempotencyConfig } from "../../generator/resources-builder.ts";
+import { extractIdFromCreateResponse, fillPathWithId, fillPathParams, serializeCheckBody, resolveCreateBody } from "./_crud-helpers.ts";
+
+/** Default header name used when yaml omits it and we're running on
+ *  spec-detected idempotency support. Matches the Stripe / Resend
+ *  convention; specs that use a different casing should declare it
+ *  explicitly. */
+const DEFAULT_HEADER = "Idempotency-Key";
+
+/** Baseline response fields stripped before bit-identical compare.
+ *  Mirrors the readback-diff baseline minus a few read-shape-specific
+ *  ones (livemode, _links). Timestamps + request-id + etag cover the
+ *  common "every replay has a new request_id" surface. */
+const DEFAULT_IGNORE_RESPONSE: ReadonlySet<string> = new Set([
+  "created",
+  "created_at",
+  "createdAt",
+  "updated",
+  "updated_at",
+  "updatedAt",
+  "request_id",
+  "requestId",
+  "x_request_id",
+  "etag",
+  "_etag",
+]);
+
+function safeParse(v: unknown): unknown {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+}
+
+function detectSpecHeader(create: { parameters: OpenAPIV3.ParameterObject[] }): string | null {
+  for (const p of create.parameters) {
+    if (p.in !== "header") continue;
+    if (p.name.toLowerCase() === "idempotency-key") return p.name;
+  }
+  return null;
+}
+
+function resolveConfig(
+  cfg: IdempotencyConfig | undefined,
+  create: { parameters: OpenAPIV3.ParameterObject[] },
+): { header: string; ignore: ReadonlySet<string> } | null {
+  if (cfg) {
+    const header = cfg.header ?? DEFAULT_HEADER;
+    const ignore = cfg.ignoreResponseFields
+      ? new Set<string>([...DEFAULT_IGNORE_RESPONSE, ...cfg.ignoreResponseFields])
+      : DEFAULT_IGNORE_RESPONSE;
+    return { header, ignore };
+  }
+  const detected = detectSpecHeader(create);
+  if (detected) return { header: detected, ignore: DEFAULT_IGNORE_RESPONSE };
+  return null;
+}
+
+/** Shallow object diff with field-level ignore. Returns the list of
+ *  keys whose values differ (or whose presence differs) between a and
+ *  b, excluding ignored fields. Both inputs treated as `{}` when not
+ *  object-shaped. */
+function diffFields(a: unknown, b: unknown, ignore: ReadonlySet<string>): string[] {
+  const av = (a && typeof a === "object" && !Array.isArray(a)) ? (a as Record<string, unknown>) : {};
+  const bv = (b && typeof b === "object" && !Array.isArray(b)) ? (b as Record<string, unknown>) : {};
+  const keys = new Set<string>([...Object.keys(av), ...Object.keys(bv)]);
+  const diffs: string[] = [];
+  for (const k of keys) {
+    if (ignore.has(k)) continue;
+    const sa = JSON.stringify(av[k] ?? null);
+    const sb = JSON.stringify(bv[k] ?? null);
+    if (sa !== sb) diffs.push(k);
+  }
+  return diffs;
+}
+
+function generateKey(): string {
+  // Bun + Node 19+ ship crypto.randomUUID; fall back to a timestamp+rand
+  // mash so tests on minimal stubs still produce a stable-ish key.
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `zond-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+export const idempotencyReplay: CrudStatefulCheck = {
+  id: "idempotency_replay",
+  severity: "high",
+  defaultExpected: "Two POSTs with the same Idempotency-Key must return the same resource id and bit-identical responses",
+  references: [{ id: "ARV-170" }, { id: "stripe-idempotent-requests" }],
+  phase: "crud",
+  applies(g) {
+    return Boolean(g.create);
+  },
+  async run(g, h) {
+    if (h.bootstrapCleanupFailed) {
+      return { kind: "skip", reason: "bootstrap-cleanup failed — stateful checks paused" };
+    }
+    const create = g.create!;
+
+    const cfg = h.resourceConfigs?.get(g.resource)?.idempotency;
+    const resolved = resolveConfig(cfg, create);
+    if (!resolved) {
+      return { kind: "skip", reason: "no idempotency config and no Idempotency-Key parameter in spec" };
+    }
+
+    const seedBody = h.resourceConfigs?.get(g.resource)?.seedBody;
+    if (!create.requestBodySchema && !seedBody) {
+      return { kind: "skip", reason: "create has no requestBody schema and no seed_body — nothing to replay" };
+    }
+    const writeBody = resolveCreateBody(create, seedBody);
+    if (writeBody == null) {
+      return { kind: "skip", reason: "could not produce a create body (no seed_body, generator returned non-object)" };
+    }
+
+    const key = generateKey();
+    // ARV-191: form-urlencoded vs JSON dispatch — Stripe-style APIs
+    // honor Idempotency-Key but expect x-www-form-urlencoded payloads;
+    // JSON.stringify would yield broken-baseline 400s on every replay.
+    const { body: bodyStr, contentType } = serializeCheckBody(create, writeBody, h.pathVars, seedBody?.contentType);
+    const baseHeaders = {
+      Accept: "application/json",
+      "Content-Type": contentType,
+      [resolved.header]: key,
+      ...h.authHeaders,
+    };
+    const url = `${h.baseUrl.replace(/\/+$/, "")}${fillPathParams(create.path, h.pathVars)}`;
+
+    // 1st POST
+    const r1 = await h.send({ method: "POST", url, headers: baseHeaders, body: bodyStr });
+    if (r1.status < 200 || r1.status >= 300) {
+      return { kind: "skip", reason: `1st create returned ${r1.status} — broken-baseline guard` };
+    }
+    const body1 = r1.body_parsed ?? safeParse(r1.body);
+    const id1 = extractIdFromCreateResponse(body1, g.idParam);
+    if (id1 == null) return { kind: "skip", reason: "could not extract id from 1st create response" };
+
+    // 2nd POST — same body, same key
+    const r2 = await h.send({ method: "POST", url, headers: baseHeaders, body: bodyStr });
+    if (r2.status === 429 || r2.status === 409) {
+      // Cleanup r1 before bailing — we did create something.
+      await tryCleanup(g, h, id1);
+      return { kind: "skip", reason: `2nd create returned ${r2.status} — rate-limit/conflict, replay verdict ambiguous` };
+    }
+    if (r2.status < 200 || r2.status >= 300) {
+      await tryCleanup(g, h, id1);
+      return { kind: "skip", reason: `2nd create returned ${r2.status} — broken-baseline guard` };
+    }
+    const body2 = r2.body_parsed ?? safeParse(r2.body);
+    const id2 = extractIdFromCreateResponse(body2, g.idParam);
+
+    // Verdict
+    const duplicate = id2 != null && String(id1) !== String(id2);
+    const diffs = duplicate ? [] : diffFields(body1, body2, resolved.ignore);
+    const nonBitIdentical = !duplicate && diffs.length > 0;
+
+    // Cleanup. If duplicate, both ids need to go.
+    const cleanupWarn: string[] = [];
+    const okCleanup1 = await tryCleanup(g, h, id1);
+    if (!okCleanup1) cleanupWarn.push(`failed to DELETE id=${id1}`);
+    if (duplicate && id2 != null) {
+      const okCleanup2 = await tryCleanup(g, h, id2);
+      if (!okCleanup2) cleanupWarn.push(`failed to DELETE id=${id2}`);
+    }
+
+    if (!duplicate && !nonBitIdentical) {
+      return { kind: "pass" };
+    }
+
+    const kind = duplicate && nonBitIdentical
+      ? "both"
+      : duplicate ? "duplicate_resource" : "non_bit_identical";
+    const message = duplicate
+      ? `Idempotency-Key not honored on ${g.resource}: replay produced a new resource (id1=${id1}, id2=${id2})`
+      : `Idempotency-Key replay on ${g.resource} is not bit-identical (${diffs.length} field(s) differ): ${diffs.slice(0, 5).join(", ")}`;
+
+    return {
+      kind: "fail",
+      message,
+      evidence: {
+        resource: g.resource,
+        kind,
+        header: resolved.header,
+        key,
+        id1,
+        id2,
+        diff_fields: diffs,
+        ...(cleanupWarn.length > 0 ? { cleanup_warning: cleanupWarn } : {}),
+      },
+    };
+  },
+};
+
+async function tryCleanup(
+  g: { delete?: { path: string }; idParam: string },
+  h: import("../stateful.ts").StatefulHarness,
+  id: string | number,
+): Promise<boolean> {
+  if (!g.delete) return false;
+  const url = `${h.baseUrl.replace(/\/+$/, "")}${fillPathWithId(fillPathParams(g.delete.path, h.pathVars), g.idParam, id)}`;
+  try {
+    const resp = await h.send({
+      method: "DELETE",
+      url,
+      headers: { Accept: "application/json", ...h.authHeaders },
+    });
+    // 404 = already gone (good); 2xx = deleted; anything else = failure.
+    return resp.status === 404 || (resp.status >= 200 && resp.status < 300);
+  } catch {
+    return false;
+  }
+}

package/src/core/checks/checks/ignored_auth.ts

@@ -0,0 +1,211 @@
+/**
+ * `ignored_auth` (m-15 ARV-3, refined in ARV-181) — for every operation
+ * that declares a security requirement, send 3 requests:
+ *
+ *   1. baseline   — full real-auth headers,
+ *   2. no_auth    — drop every auth-shaped header,
+ *   3. bogus_auth — replace each auth header value with a malformed-
+ *                   shaped, plausibly-typed bogus.
+ *
+ * Verdict logic (ARV-181 differential):
+ *
+ *   - baseline 5xx → skip (server unhealthy; nothing we say is trustworthy).
+ *   - baseline 2xx → strict mode. Any 2xx on no_auth/bogus → HIGH bypass.
+ *   - baseline 4xx → soft mode. The auth token didn't get a 2xx (wrong
+ *     permissions, real path-var not provided, etc.), but we can still
+ *     learn from how the server treats *worse* credentials:
+ *       · no_auth/bogus returns **strictly better** status (lower 4xx
+ *         class, or 2xx/3xx) → HIGH bypass. The classic smoking gun
+ *         is `baseline 403 / no_auth 200`.
+ *       · same or worse status → pass (auth was checked; the resource
+ *         simply isn't accessible to anyone).
+ *
+ * Strictness:
+ *   - default: no_auth/bogus passes if status is in [400..499] (any 4xx).
+ *   - --strict-401 (CheckRuntimeOptions.strict401): only 401 passes; any
+ *     other status — even 403/404 — fails. Mirrors schemathesis V4.
+ *
+ * Anti-FP guards (kept from ARV-3):
+ *   - skip operations with `security: []` override (explicitly public),
+ *   - skip when `bootstrap_cleanup_failed` (data state corrupted),
+ *   - skip when no auth headers provided to the harness at all.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { AuthStatefulCheck } from "../stateful.ts";
+import type { HttpRequest } from "../../runner/types.ts";
+
+function buildBogus(name: string, value: string): string {
+  // Keep the original prefix so the auth scheme detection at the
+  // server still matches (Bearer xxx, Basic xxx). Only the secret
+  // payload is replaced.
+  if (/^Bearer\s+/i.test(value)) return "Bearer aaaaaaaaaaaa.bbbbbbbbbbbb.cccccccccccc";
+  if (/^Basic\s+/i.test(value)) return "Basic " + Buffer.from("zzz:zzz").toString("base64");
+  // apiKey / custom header — preserve length-class, replace content.
+  return name.toLowerCase().includes("token") ? "ZZZZZZZZZZ" : "bogus-" + "z".repeat(8);
+}
+
+/** ARV-181: substitute path placeholders using `h.pathVars` first, then
+ *  fall back to schema-derived placeholders. Mirrors `fillPathParams`
+ *  in `runner.ts` (kept inline to avoid a cross-module dependency that
+ *  would yank generator imports into stateful checks). */
+function fillPath(
+  path: string,
+  op: { parameters: OpenAPIV3.ParameterObject[] },
+  pathVars: Record<string, string> | undefined,
+): string {
+  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const real = pathVars?.[name];
+    if (typeof real === "string" && real.length > 0) return encodeURIComponent(real);
+    const param = op.parameters.find((p) => p.name === name && p.in === "path");
+    const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
+    if (schema?.format === "uuid") return "00000000-0000-0000-0000-000000000000";
+    if (schema?.type === "integer" || schema?.type === "number") return "1";
+    return "x";
+  });
+}
+
+function isAuthHeaderName(name: string): boolean {
+  const n = name.toLowerCase();
+  return n === "authorization" || n.startsWith("x-api") || n.includes("token") || n.includes("key");
+}
+
+/** ARV-181: classify response status into a single ordering bucket so
+ *  the differential broken-baseline logic can answer "did stripping
+ *  auth give a *better* status than baseline?". Lower index = more
+ *  permissive (worse from auth-enforcement POV). 5xx is its own
+ *  bucket — never compare across it. */
+function statusBucket(status: number): number {
+  if (status >= 200 && status < 400) return 0; // accepted-ish
+  if (status === 401) return 3;                // canonical "auth required"
+  if (status === 403) return 2;                // permission denied
+  if (status >= 400 && status < 500) return 1; // other 4xx (404, 422, ...)
+  return -1;                                   // 5xx / 1xx — incomparable
+}
+
+function isAcceptableRejection(status: number, strict401: boolean): boolean {
+  if (strict401) return status === 401;
+  return status >= 400 && status < 500;
+}
+
+export const ignoredAuth: AuthStatefulCheck = {
+  id: "ignored_auth",
+  severity: "high",
+  defaultExpected: "Server must reject requests without (or with bogus) auth credentials with 401/403",
+  references: [{ id: "OWASP-API-01" }],
+  phase: "auth",
+  applies(op) {
+    // Anti-FP: explicit `security: []` override means the op is intentionally public.
+    if (op.security.length === 0) return false;
+    return true;
+  },
+  async run(op, h) {
+    if (h.bootstrapCleanupFailed) {
+      return { kind: "skip", reason: "bootstrap-cleanup failed — security checks paused (ARV-3 AC #6)" };
+    }
+    if (Object.keys(h.authHeaders).length === 0) {
+      return { kind: "skip", reason: "no auth headers provided to harness — pass --auth-header" };
+    }
+    const strict401 = h.options?.strict401 === true;
+    const url = `${h.baseUrl.replace(/\/+$/, "")}${fillPath(op.path, op, h.pathVars)}`;
+    const method = op.method.toUpperCase();
+    const baseHeaders: Record<string, string> = { Accept: "application/json", ...h.authHeaders };
+
+    // 1. baseline
+    const baseReq: HttpRequest = { method, url, headers: baseHeaders };
+    const baseline = await h.send(baseReq);
+    if (baseline.status >= 500) {
+      return { kind: "skip", reason: `baseline returned ${baseline.status} — server-side error, no trustworthy signal` };
+    }
+
+    // 2. no_auth — strip every auth-shaped header
+    const noAuthHeaders: Record<string, string> = { ...baseHeaders };
+    for (const k of Object.keys(noAuthHeaders)) {
+      if (isAuthHeaderName(k)) delete noAuthHeaders[k];
+    }
+    const noAuth = await h.send({ method, url, headers: noAuthHeaders });
+
+    // 3. bogus_auth — keep header names, replace values
+    const bogusHeaders: Record<string, string> = { ...baseHeaders };
+    for (const k of Object.keys(bogusHeaders)) {
+      if (isAuthHeaderName(k)) bogusHeaders[k] = buildBogus(k, bogusHeaders[k]!);
+    }
+    const bogus = await h.send({ method, url, headers: bogusHeaders });
+
+    const baseBucket = statusBucket(baseline.status);
+    const baseIs2xx = baseline.status >= 200 && baseline.status < 300;
+
+    // ── strict-2xx-baseline branch (legacy path, unchanged semantically) ──
+    if (baseIs2xx) {
+      if (noAuth.status >= 200 && noAuth.status < 300) {
+        return {
+          kind: "fail",
+          message: `Server accepted request without auth credentials (status ${noAuth.status}) — auth is being ignored`,
+          evidence: { variant: "no_auth", baseline_status: baseline.status, no_auth_status: noAuth.status },
+        };
+      }
+      if (bogus.status >= 200 && bogus.status < 300) {
+        return {
+          kind: "fail",
+          message: `Server accepted request with bogus auth (status ${bogus.status}) — credentials not validated`,
+          evidence: { variant: "bogus_auth", baseline_status: baseline.status, bogus_auth_status: bogus.status },
+        };
+      }
+      if (strict401) {
+        if (noAuth.status !== 401) {
+          return {
+            kind: "fail",
+            message: `no_auth returned ${noAuth.status}, expected 401 (--strict-401)`,
+            evidence: { variant: "no_auth_strict", baseline_status: baseline.status, no_auth_status: noAuth.status, strict_401: true },
+          };
+        }
+        if (bogus.status !== 401) {
+          return {
+            kind: "fail",
+            message: `bogus_auth returned ${bogus.status}, expected 401 (--strict-401)`,
+            evidence: { variant: "bogus_auth_strict", baseline_status: baseline.status, bogus_auth_status: bogus.status, strict_401: true },
+          };
+        }
+      }
+      return { kind: "pass" };
+    }
+
+    // ── differential 4xx-baseline branch (ARV-181) ─────────────────────
+    if (baseBucket < 0) {
+      return { kind: "skip", reason: `baseline returned ${baseline.status} — incomparable status, no trustworthy signal` };
+    }
+    const noAuthBucket = statusBucket(noAuth.status);
+    const bogusBucket = statusBucket(bogus.status);
+
+    if (noAuthBucket >= 0 && noAuthBucket < baseBucket) {
+      return {
+        kind: "fail",
+        message: `Server gave a more permissive status (${noAuth.status}) without auth than with valid auth (${baseline.status}) — possible bypass`,
+        evidence: { variant: "no_auth_differential", baseline_status: baseline.status, no_auth_status: noAuth.status },
+      };
+    }
+    if (bogusBucket >= 0 && bogusBucket < baseBucket) {
+      return {
+        kind: "fail",
+        message: `Server gave a more permissive status (${bogus.status}) with bogus auth than with valid auth (${baseline.status}) — possible bypass`,
+        evidence: { variant: "bogus_auth_differential", baseline_status: baseline.status, bogus_auth_status: bogus.status },
+      };
+    }
+    if (strict401) {
+      if (!isAcceptableRejection(noAuth.status, true) && noAuthBucket >= 0) {
+        return {
+          kind: "fail",
+          message: `no_auth returned ${noAuth.status}, expected 401 (--strict-401, baseline ${baseline.status})`,
+          evidence: { variant: "no_auth_strict", baseline_status: baseline.status, no_auth_status: noAuth.status, strict_401: true },
+        };
+      }
+      if (!isAcceptableRejection(bogus.status, true) && bogusBucket >= 0) {
+        return {
+          kind: "fail",
+          message: `bogus_auth returned ${bogus.status}, expected 401 (--strict-401, baseline ${baseline.status})`,
+          evidence: { variant: "bogus_auth_strict", baseline_status: baseline.status, bogus_auth_status: bogus.status, strict_401: true },
+        };
+      }
+    }
+    return { kind: "pass" };
+  },
+};