@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/checks/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Public entry point for the `core/checks` framework.
+ *
+ * Importing this module also triggers `checks/index.ts` which registers
+ * the built-in checks exactly once.
+ */
+export type {
+  Check,
+  CheckCase,
+  CheckContext,
+  CheckFinding,
+  CheckOutcome,
+  CheckResponse,
+  CheckRunData,
+  CheckRunSummary,
+  Phase,
+  Severity,
+} from "./types.ts";
+export { emptySummary } from "./types.ts";
+export {
+  __resetRegistryForTests,
+  getCheck,
+  listChecks,
+  registerCheck,
+  selectChecks,
+  type SelectOptions,
+  type SelectionResult,
+} from "./registry.ts";
+export { runChecks, type RunChecksOptions, type RunChecksResult } from "./runner.ts";
+export { registerBuiltinChecks } from "./checks/index.ts";

package/src/core/checks/mode.ts

@@ -0,0 +1,79 @@
+/**
+ * `--mode positive|negative|all` filter (m-15 ARV-7).
+ *
+ * Splits the registered check catalog along the positive-vs-negative
+ * axis so an agent can run *just* contract verification (positive) or
+ * *just* malicious-input probes (negative) on the same spec without
+ * juggling a long `--check` list.
+ *
+ * Centralized table — both response-phase `Check`s and stateful
+ * security checks declare their mode here. Tests snapshot the table so
+ * adding a new check forces an explicit decision rather than letting it
+ * silently land in the "all" bucket and surface in both modes.
+ */
+import type { Check } from "./types.ts";
+import type { StatefulCheck } from "./stateful.ts";
+
+export type Mode = "positive" | "negative" | "all";
+
+export const MODE_BY_CHECK: Record<string, Mode> = {
+  // Conformance checks fire on every response — both modes.
+  not_a_server_error: "all",
+  status_code_conformance: "all",
+  content_type_conformance: "all",
+  response_headers_conformance: "all",
+  response_schema_conformance: "all",
+  // Probes that *only* make sense as malicious input.
+  missing_required_header: "negative",
+  unsupported_method: "negative",
+  negative_data_rejection: "negative",
+  // The "happy-path didn't break" sanity probe.
+  positive_data_acceptance: "positive",
+  // Security checks (stateful) — they verify a *bad* outcome (auth
+  // bypass, dangling reads). Not part of the positive contract.
+  ignored_auth: "negative",
+  use_after_free: "negative",
+  // Availability is positive-flavored — it asserts the server *can*
+  // serve the listed resource. Useful in `--mode positive` runs.
+  ensure_resource_availability: "all",
+  // ARV-169 (m-20): cross-call drift is a contract-verification check
+  // (does GET reflect POST?), not a malicious-input probe. Positive.
+  cross_call_references: "positive",
+  // ARV-170 (m-20): idempotency replay verifies a *contract* the server
+  // advertises (Idempotency-Key honored). Positive.
+  idempotency_replay: "positive",
+  // ARV-171 (m-20): pagination invariants verify the cursor contract.
+  pagination_invariants: "positive",
+  // ARV-172 (m-20): lifecycle verifies the declared state machine.
+  lifecycle_transitions: "positive",
+  // ARV-256 (m-21): open-CORS check sends an attacker Origin and
+  // inspects response — categorically negative-mode probe.
+  open_cors_on_sensitive: "negative",
+  // ARV-256 (m-21): rate-limit headers check inspects 2xx responses
+  // for advertised rate-limit metadata — runs on the positive path.
+  rate_limit_headers_absent: "positive",
+};
+
+export function modeFor(checkId: string): Mode {
+  return MODE_BY_CHECK[checkId] ?? "all";
+}
+
+export function filterChecksByMode<T extends Check | StatefulCheck>(
+  checks: T[],
+  mode: Mode,
+): T[] {
+  if (mode === "all") return checks;
+  return checks.filter((c) => {
+    const cm = modeFor(c.id);
+    if (cm === "all") return true;
+    return cm === mode;
+  });
+}
+
+/** True if a built case (with `mode: "positive" | "negative"`) should be
+ *  sent in the requested run-mode. The runner uses this to short-circuit
+ *  request emission for cases the active mode doesn't care about. */
+export function caseMatchesMode(caseMode: "positive" | "negative", runMode: Mode): boolean {
+  if (runMode === "all") return true;
+  return runMode === caseMode;
+}

package/src/core/checks/recommended-action.ts

@@ -0,0 +1,64 @@
+/**
+ * ARV-11 (m-15): per-check `recommended_action` table.
+ *
+ * Each `CheckFinding` carries one closed-enum action so an agent can
+ * route on it without parsing the free-form `message`. The mapping is
+ * deterministic — given the check id and (for a couple of fan-out cases)
+ * the response status, exactly one action comes out.
+ *
+ * Keep this file thin and table-driven. The shared enum lives in
+ * `core/diagnostics/failure-hints.ts` so `db diagnose` (TASK-294) and
+ * `zond checks run` (ARV-11) can never drift.
+ */
+import type { RecommendedAction } from "../diagnostics/failure-hints.ts";
+import { classify, type FindingClass } from "../classifier/recommended-action.ts";
+
+/** Check IDs the classifier explicitly recognises. Keeping this typed
+ *  guarantees that adding a new check forces a branch in the classifier
+ *  switch (tsc errors out at compile time on a stale `STATIC_TABLE` lookup). */
+const CHECK_ID_TO_CLASS: Record<string, FindingClass> = {
+  status_code_conformance: "check:status_code_conformance",
+  content_type_conformance: "check:content_type_conformance",
+  response_headers_conformance: "check:response_headers_conformance",
+  response_schema_conformance: "check:response_schema_conformance",
+  not_a_server_error: "check:not_a_server_error",
+  unsupported_method: "check:unsupported_method",
+  positive_data_acceptance: "check:positive_data_acceptance",
+  use_after_free: "check:use_after_free",
+  ensure_resource_availability: "check:ensure_resource_availability",
+  negative_data_rejection: "check:negative_data_rejection",
+  missing_required_header: "check:missing_required_header",
+  ignored_auth: "check:ignored_auth",
+  cross_call_references: "check:cross_call_references",
+  idempotency_replay: "check:idempotency_replay",
+  pagination_invariants: "check:pagination_invariants",
+  lifecycle_transitions: "check:lifecycle_transitions",
+  open_cors_on_sensitive: "check:open_cors_on_sensitive",
+  rate_limit_headers_absent: "check:rate_limit_headers_absent",
+  network_error: "check:network_error",
+};
+
+/**
+ * ARV-56: thin wrapper that maps a check id + status to the unified
+ * classifier. Returns `undefined` when the check id isn't in the table
+ * — unknown ids are a bug in this map, not a runtime input to coerce.
+ */
+export function recommendForCheck(
+  checkId: string,
+  status?: number,
+): RecommendedAction | undefined {
+  const findingClass = CHECK_ID_TO_CLASS[checkId];
+  if (!findingClass) return undefined;
+  return classify({ finding_class: findingClass, status: status ?? null });
+}
+
+/** Test-only export — keeps the unit table authoritative without
+ *  re-listing entries inside the test file. Derived from classifier
+ *  output so the table never drifts from the classifier's switch. */
+export const RECOMMENDED_ACTION_TABLE: Readonly<Record<string, RecommendedAction>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(CHECK_ID_TO_CLASS)
+      .filter(([id]) => id !== "network_error") // dynamic — depends on status
+      .map(([id, fc]) => [id, classify({ finding_class: fc })!]),
+  ),
+);

package/src/core/checks/registry.ts

@@ -0,0 +1,78 @@
+/**
+ * Global registry of `zond checks`. Built-in checks register themselves
+ * on first import (see `checks/index.ts`); `selectChecks` resolves the
+ * `--check` / `--exclude-check` filters from the CLI into the active
+ * subset for a single run.
+ */
+import type { Check } from "./types.ts";
+
+const REGISTRY = new Map<string, Check>();
+
+export function registerCheck(check: Check): void {
+  if (REGISTRY.has(check.id)) {
+    throw new Error(`Check "${check.id}" is already registered`);
+  }
+  REGISTRY.set(check.id, check);
+}
+
+export function getCheck(id: string): Check | undefined {
+  return REGISTRY.get(id);
+}
+
+export function listChecks(): Check[] {
+  return [...REGISTRY.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export interface SelectOptions {
+  include?: string[];
+  exclude?: string[];
+}
+
+export interface SelectionResult {
+  selected: Check[];
+  unknown: string[];
+}
+
+/**
+ * Resolve include/exclude id lists into the active set of checks.
+ * Unknown ids are returned separately so the caller can surface them as
+ * envelope warnings (and decide whether to fail or continue).
+ */
+export function selectChecks(opts: SelectOptions = {}): SelectionResult {
+  const all = listChecks();
+  const knownIds = new Set(all.map(c => c.id));
+  const unknown: string[] = [];
+
+  for (const id of [...(opts.include ?? []), ...(opts.exclude ?? [])]) {
+    if (!knownIds.has(id)) unknown.push(id);
+  }
+
+  let pool = all;
+  if (opts.include && opts.include.length > 0) {
+    const includeSet = new Set(opts.include);
+    pool = pool.filter(c => includeSet.has(c.id));
+  }
+  if (opts.exclude && opts.exclude.length > 0) {
+    const excludeSet = new Set(opts.exclude);
+    pool = pool.filter(c => !excludeSet.has(c.id));
+  }
+  return { selected: pool, unknown };
+}
+
+/** Test-only escape hatch — wipes the registry between unit tests. */
+export function __resetRegistryForTests(): void {
+  REGISTRY.clear();
+}
+
+/** Test-only snapshot/restore. Use when a test wants a clean slate but the
+ *  rest of the suite still needs the side-effect-registered built-ins
+ *  (otherwise wiping the registry leaks across files because the modules
+ *  that registered them are already cached and won't re-fire on re-import).
+ */
+export function __snapshotRegistryForTests(): () => void {
+  const saved = new Map(REGISTRY);
+  return () => {
+    REGISTRY.clear();
+    for (const [k, v] of saved) REGISTRY.set(k, v);
+  };
+}