@kirrosh/zond 0.22.0 → 0.26.0

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

@@ -0,0 +1,119 @@
+/**
+ * Live probe-runtime primitives shared by mass-assignment and security
+ * probes. TASK-185 (m-11) extracted the static spec/scaffold half into
+ * `runner.ts`; this module covers the per-endpoint primitives that
+ * were still duplicated between the two probe entry points.
+ *
+ * Scope: small, pure helpers — URL building, baseline body generation,
+ * JSON+auth header construction. Cleanup logic is intentionally NOT
+ * unified: mass-assignment uses fire-and-forget DELETE before attacks,
+ * security-probe uses snapshot/restore + retry-aware DELETE after
+ * attacks. Different invariants, different shapes — see TASK-189 notes.
+ */
+
+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
+ *  application/x-www-form-urlencoded — the probes previously skipped
+ *  every such endpoint, masking real mass-assignment vectors. */
+export function isFormBody(ep: EndpointInfo): boolean {
+  return (
+    ep.requestBodyContentType === "application/x-www-form-urlencoded"
+    && ep.requestBodySchema !== undefined
+  );
+}
+
+/** Probes can drive either application/json or application/x-www-form-urlencoded
+ *  endpoints. Anything else (multipart, octet-stream, …) still gets skipped —
+ *  no general way to construct attack payloads without a body schema. */
+export function hasProbeBody(ep: EndpointInfo): boolean {
+  if (ep.method === "GET" || ep.method === "DELETE") return false;
+  if (!ep.requestBodySchema) return false;
+  return (
+    ep.requestBodyContentType === "application/json"
+    || ep.requestBodyContentType === "application/x-www-form-urlencoded"
+  );
+}
+
+/** Serialise an attack body using whichever content type the endpoint
+ *  declares. Returns the wire-format string + the Content-Type to set. */
+export function serializeProbeBody(
+  ep: EndpointInfo,
+  body: Record<string, unknown>,
+): { content: string; contentType: string } {
+  if (isFormBody(ep)) {
+    return { content: encodeFormBody(body), contentType: "application/x-www-form-urlencoded" };
+  }
+  return { content: JSON.stringify(body), contentType: "application/json" };
+}
+
+/**
+ * Resolve an endpoint's URL against the live `base_url` + path-param
+ * substitutions. Returns the resolved URL and any leftover `{{var}}`
+ * markers the caller couldn't fill — use those to skip the endpoint
+ * with a meaningful reason.
+ */
+export function buildProbeUrl(
+  ep: EndpointInfo,
+  vars: Record<string, string>,
+): { url: string; unresolved: string[] } {
+  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: 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 buildBodyAuthHeaders(
+  ep: EndpointInfo,
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+): Record<string, string> {
+  const ct = isFormBody(ep) ? "application/x-www-form-urlencoded" : "application/json";
+  return {
+    "content-type": ct,
+    accept: "application/json",
+    ...liveAuthHeaders(ep, schemes, vars),
+  };
+}
+
+/**
+ * Synthesize a baseline body from the endpoint's request schema and
+ * 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 = 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/registry.ts

@@ -0,0 +1,89 @@
+/**
+ * Probe registry + boot-time validator (m-17 / ARV-49).
+ *
+ * The CLI bootstrap calls `bootstrapProbes()` exactly once — that
+ * function imports each registered probe class and pushes it through
+ * `registerProbe`, which throws if the contract from `types.ts` is
+ * not fully implemented. Boot fails loud with a list of missing slots,
+ * so adding a new probe class without --dry-run / --report support is
+ * impossible (replaces the conventions-then-drift status quo that
+ * produced F1-15 / F2-15 / F3-15 in feedback round 15).
+ */
+import type { Probe, ProbeFlags } from "./types.ts";
+
+const REQUIRED_METHODS: Array<keyof Probe> = ["dryRun", "run", "report"];
+const REQUIRED_FLAGS: Array<keyof ProbeFlags> = [
+  "api",
+  "tag",
+  "include",
+  "exclude",
+  "dryRun",
+  "listTags",
+  "json",
+  "output",
+  "report",
+];
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+/** Pure validator — used by both `registerProbe` and the contract test
+ *  in `tests/contracts/probe-interface.test.ts`. */
+export function validateProbe(p: unknown): ValidationResult {
+  const errors: string[] = [];
+  if (p === null || typeof p !== "object") {
+    return { ok: false, errors: ["Probe is not an object"] };
+  }
+  const probe = p as Partial<Probe>;
+  const label = probe.name ?? "<anonymous>";
+  if (typeof probe.name !== "string" || probe.name.length === 0) {
+    errors.push("Probe is missing required field name");
+  }
+  if (typeof probe.description !== "string" || probe.description.length === 0) {
+    errors.push(`Probe "${label}" is missing required field description`);
+  }
+  for (const m of REQUIRED_METHODS) {
+    if (typeof (probe as Record<string, unknown>)[m] !== "function") {
+      errors.push(`Probe "${label}" is missing required method ${m}`);
+    }
+  }
+  if (probe.commonFlags === undefined || probe.commonFlags === null || typeof probe.commonFlags !== "object") {
+    errors.push(`Probe "${label}" is missing required field commonFlags`);
+  } else {
+    const flags = probe.commonFlags as unknown as Record<string, unknown>;
+    for (const f of REQUIRED_FLAGS) {
+      const v = flags[f as string];
+      if (typeof v !== "boolean") {
+        errors.push(`Probe "${label}" commonFlags is missing slot ${f} (must be boolean)`);
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+const PROBES = new Map<string, Probe>();
+
+export function registerProbe(probe: Probe): void {
+  const r = validateProbe(probe);
+  if (!r.ok) {
+    throw new Error(
+      `Invalid probe registration:\n  - ${r.errors.join("\n  - ")}`,
+    );
+  }
+  if (PROBES.has(probe.name)) {
+    throw new Error(`Probe "${probe.name}" is already registered`);
+  }
+  PROBES.set(probe.name, probe);
+}
+
+export function listProbes(): readonly Probe[] {
+  return Array.from(PROBES.values());
+}
+
+/** Test helper — wipes the registry between unit tests. NOT exported
+ *  through `index.ts`; tests import this module directly. */
+export function clearProbes(): void {
+  PROBES.clear();
+}

package/src/core/probe/runner.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared scaffolding for the four probe commands (`probe validation`,
+ * `probe methods`, `probe mass-assignment`, `probe security`).
+ *
+ * Each command historically duplicated the same boilerplate: read the
+ * spec, optionally filter by tag, mkdir the output dir, write the
+ * generated suites with an autogen header, and record them in the
+ * workspace manifest. This module collapses that scaffolding into two
+ * helpers (`loadSpecForProbe` / `writeProbeSuites`) so the cli layer
+ * stays thin.
+ *
+ * Live-runner commands (`mass-assignment`, `security`) reuse the
+ * write-suites half for their `--emit-tests` flag; the actual HTTP
+ * orchestration lives in `mass-assignment-probe.ts` /
+ * `security-probe.ts`.
+ *
+ * Goals are documented in TASK-185 (m-11).
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  serializeSuite,
+} from "../generator/index.ts";
+import type { EndpointInfo, SecuritySchemeInfo, RawSuite } from "../generator/index.ts";
+import { collectTags, filterByTag } from "../generator/chunker.ts";
+import {
+  recordGeneratedFiles,
+  inferApiName,
+  autoGenHeader,
+  type RecordInput,
+} from "../workspace/manifest.ts";
+import { findWorkspaceRoot } from "../workspace/root.ts";
+
+export interface LoadSpecForProbeOptions {
+  specPath: string;
+  tag?: string;
+  /** When true, the caller wants the available-tags list, not endpoints. */
+  listTags?: boolean;
+}
+
+export type LoadSpecResult =
+  | { kind: "endpoints"; endpoints: EndpointInfo[]; securitySchemes: SecuritySchemeInfo[] }
+  | { kind: "tags"; tags: string[] }
+  | { kind: "tag-not-found"; tag: string; available: string[] };
+
+/**
+ * Read the spec, optionally filter by tag, and surface either the
+ * filtered endpoints or the list of available tags. Centralises the
+ * tag-not-found error path so probe commands all produce identical
+ * messaging.
+ */
+export async function loadSpecForProbe(opts: LoadSpecForProbeOptions): Promise<LoadSpecResult> {
+  const doc = await readOpenApiSpec(opts.specPath);
+  const allEndpoints = extractEndpoints(doc);
+  const securitySchemes = extractSecuritySchemes(doc);
+
+  if (opts.listTags) {
+    return { kind: "tags", tags: collectTags(allEndpoints) };
+  }
+
+  if (opts.tag) {
+    const filtered = filterByTag(allEndpoints, opts.tag);
+    if (filtered.length === 0) {
+      return { kind: "tag-not-found", tag: opts.tag, available: collectTags(allEndpoints) };
+    }
+    return { kind: "endpoints", endpoints: filtered, securitySchemes };
+  }
+
+  return { kind: "endpoints", endpoints: allEndpoints, securitySchemes };
+}
+
+export interface WriteProbeSuitesOptions {
+  /** Directory to write suites into. Created recursively if missing. */
+  output: string;
+  /** Suites produced by the underlying probe generator. */
+  suites: RawSuite[];
+  /** Manifest `by` field — e.g. `"zond probe-methods --emit"`. */
+  command: string;
+  /** First arg of `autoGenHeader` (label). Defaults to `command`. */
+  headerLabel?: string;
+  /** Concrete repro command shown in the autogen header. */
+  headerExample?: string;
+  /** Manifest category (defaults to `"probes"`). */
+  category?: RecordInput["category"];
+}
+
+export interface WroteProbeSuites {
+  files: Array<{ file: string; suite: string; tests: number }>;
+}
+
+/**
+ * Materialise generator output to disk and register the files in the
+ * workspace manifest. Safe on empty input — returns an empty result and
+ * avoids creating an empty directory (m-9 P5).
+ */
+export async function writeProbeSuites(
+  opts: WriteProbeSuitesOptions,
+): Promise<WroteProbeSuites> {
+  if (opts.suites.length === 0) return { files: [] };
+
+  await mkdir(opts.output, { recursive: true });
+
+  const files: WroteProbeSuites["files"] = [];
+  const manifestEntries: RecordInput[] = [];
+  const inferredApi = inferApiName(opts.output);
+  const headerLabel = opts.headerLabel ?? opts.command;
+  const headerExample = opts.headerExample ?? opts.command;
+
+  for (const suite of opts.suites) {
+    const fileName = `${suite.fileStem ?? suite.name}.yaml`;
+    const filePath = join(opts.output, fileName);
+    await Bun.write(filePath, autoGenHeader(headerLabel, headerExample) + serializeSuite(suite));
+    files.push({ file: filePath, suite: suite.name, tests: suite.tests.length });
+    manifestEntries.push({
+      path: filePath,
+      by: opts.command,
+      api: inferredApi,
+      category: opts.category ?? "probes",
+    });
+  }
+
+  try {
+    const ws = findWorkspaceRoot();
+    if (!ws.fromFallback && manifestEntries.length > 0) {
+      recordGeneratedFiles(ws.root, manifestEntries);
+    }
+  } catch {
+    /* best-effort: manifest is observability, never fail probe emit on it */
+  }
+
+  return { files };
+}

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(" | ") } : {}),
+  };
+}