@kirrosh/zond 0.26.0 → 0.27.0

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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,89 +0,0 @@
-/**
- * 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

@@ -1,136 +0,0 @@
-/**
- * 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

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