@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/probe/mass-assignment-template.ts

@@ -0,0 +1,240 @@
+/**
+ * TASK-146: emit-template generator.
+ *
+ * Builds a ready-to-edit YAML probe template for a single endpoint, so the
+ * user doesn't have to copy-paste the boilerplate from the skill (Phase 5.1).
+ * Used when the auto-prober marked an endpoint INCONCLUSIVE / INCONCLUSIVE-5XX
+ * and the user wants to drop down to manual catch-up.
+ *
+ * Heuristics:
+ *  - Suspected fields: classic mass-assignment vectors (is_admin, role,
+ *    owner_id, account_id, ...).
+ *  - readOnly: true / x-zond-protected fields lifted from the request body
+ *    schema — these MUST NOT round-trip back from the server.
+ *  - For POST endpoints with discoverable item path (GET-by-id / DELETE
+ *    counterpart) we emit a full create → verify → cleanup chain.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo } from "../generator/types.ts";
+import type { RawSuite, RawStep } from "../generator/serializer.ts";
+import { serializeSuite } from "../generator/serializer.ts";
+import { readOpenApiSpec, extractEndpoints } from "../generator/openapi-reader.ts";
+import { findDeleteCounterpart, findGetByIdCounterpart, captureFieldFor } from "./shared.ts";
+import { SUSPECTED_FIELDS } from "./mass-assignment-probe.ts";
+
+export interface EmitTemplateOptions {
+  specPath: string;
+  method: string;
+  path: string;
+}
+
+export type EmitTemplateResult =
+  | { kind: "ok"; yaml: string; chain: "full" | "single"; protectedFields: string[] }
+  | { kind: "endpoint-not-found"; method: string; path: string; nearest: string[] };
+
+export async function buildMassAssignmentTemplate(
+  opts: EmitTemplateOptions,
+): Promise<EmitTemplateResult> {
+  const doc = await readOpenApiSpec(opts.specPath);
+  const all = extractEndpoints(doc);
+
+  const wantMethod = opts.method.toUpperCase();
+  const target = all.find(
+    e => e.method.toUpperCase() === wantMethod && pathsEqual(e.path, opts.path),
+  );
+
+  if (!target) {
+    const nearest = all
+      .filter(e => e.method.toUpperCase() === wantMethod)
+      .map(e => e.path)
+      .filter(p => similar(p, opts.path))
+      .slice(0, 5);
+    return { kind: "endpoint-not-found", method: wantMethod, path: opts.path, nearest };
+  }
+
+  const protectedFields = collectProtectedFields(target.requestBodySchema);
+  const baselineBody = buildBaselineSkeleton(target.requestBodySchema);
+  const privilegedBody = mergePrivileged(baselineBody, protectedFields);
+
+  const isMutatingCreateLike = wantMethod === "POST";
+  const readSibling = isMutatingCreateLike ? findGetByIdCounterpart(target, all) : undefined;
+  const deleteSibling = findDeleteCounterpart(target, all);
+
+  const suite = isMutatingCreateLike && readSibling
+    ? buildFullChain(target, readSibling, deleteSibling, privilegedBody, protectedFields)
+    : buildSingleStep(target, privilegedBody, protectedFields);
+
+  return {
+    kind: "ok",
+    yaml: serializeSuite(suite),
+    chain: isMutatingCreateLike && readSibling ? "full" : "single",
+    protectedFields,
+  };
+}
+
+function collectProtectedFields(schema?: OpenAPIV3.SchemaObject): string[] {
+  if (!schema || !schema.properties) return [];
+  const out: string[] = [];
+  for (const [name, raw] of Object.entries(schema.properties)) {
+    const prop = raw as OpenAPIV3.SchemaObject & { "x-zond-protected"?: boolean };
+    if (prop.readOnly === true || prop["x-zond-protected"] === true) out.push(name);
+  }
+  return out;
+}
+
+function buildBaselineSkeleton(schema?: OpenAPIV3.SchemaObject): Record<string, unknown> {
+  // Skeleton is intentionally minimal — `# …real create body sourced from
+  // fixtures…` placeholder shows up in the YAML so the user fills it in.
+  if (!schema || !schema.properties) return {};
+  const out: Record<string, unknown> = {};
+  for (const [name, raw] of Object.entries(schema.properties)) {
+    const prop = raw as OpenAPIV3.SchemaObject;
+    if (prop.readOnly === true) continue;
+    if (schema.required?.includes(name)) {
+      out[name] = placeholderForType(prop);
+    }
+  }
+  return out;
+}
+
+function placeholderForType(prop: OpenAPIV3.SchemaObject): unknown {
+  if (prop.example !== undefined) return prop.example;
+  switch (prop.type) {
+    case "integer":
+    case "number": return 1;
+    case "boolean": return false;
+    case "array": return [];
+    case "object": return {};
+    default: return `ma-test-{{$randomString}}`;
+  }
+}
+
+function mergePrivileged(
+  baseline: Record<string, unknown>,
+  protectedFields: string[],
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...baseline };
+  // Suspected fields always added.
+  for (const [k, v] of Object.entries(SUSPECTED_FIELDS)) merged[k] = v;
+  // readOnly / x-zond-protected fields: inject distinctive sentinel values
+  // so we can detect server-side echo vs server-side regeneration.
+  for (const f of protectedFields) {
+    if (!(f in merged)) merged[f] = `attacker-${f}-{{$uuid}}`;
+  }
+  return merged;
+}
+
+/** ARV-198: declared content type signals whether the create step needs
+ *  `form:` (Stripe v1, Rails/PHP-style APIs) or the default `json:` body. */
+function isFormEndpoint(ep: EndpointInfo): boolean {
+  return ep.requestBodyContentType === "application/x-www-form-urlencoded";
+}
+
+function buildFullChain(
+  create: EndpointInfo,
+  read: EndpointInfo,
+  del: EndpointInfo | undefined,
+  privilegedBody: Record<string, unknown>,
+  protectedFields: string[],
+): RawSuite {
+  const idVar = captureFieldFor(create) || "created_id";
+  const tests: RawStep[] = [];
+
+  // ARV-198: when the spec declares only application/x-www-form-urlencoded
+  // for this mutating endpoint, emit a `form:` block + Content-Type header.
+  // The serializer force-quotes form values (ARV-162) so booleans/numbers
+  // round-trip as strings on the wire; the template is paste-ready against
+  // Stripe-style APIs without any post-processing.
+  const createIsForm = isFormEndpoint(create);
+  const createStep: Record<string, unknown> = {
+    name: "create with privileged fields",
+    [create.method.toUpperCase()]: create.path,
+    expect: { status: [200, 201], body: { id: { capture: idVar } } },
+  };
+  if (createIsForm) {
+    createStep.headers = { "Content-Type": "application/x-www-form-urlencoded" };
+    createStep.form = privilegedBody;
+  } else {
+    createStep.json = privilegedBody;
+  }
+  tests.push(createStep as unknown as RawStep);
+
+  // Canonical assertion vocabulary: only `not_equals` is supported (no `not`,
+  // no `not_starts_with`). For protected fields we assert the exact attacker
+  // sentinel value did NOT round-trip back from the server.
+  const verifyBody: Record<string, Record<string, unknown>> = {};
+  for (const k of Object.keys(SUSPECTED_FIELDS)) {
+    verifyBody[k] = { not_equals: SUSPECTED_FIELDS[k] };
+  }
+  for (const f of protectedFields) {
+    if (!(f in verifyBody)) verifyBody[f] = { not_contains: "attacker-" };
+  }
+
+  tests.push({
+    name: "verify privileged fields not echoed",
+    [read.method.toUpperCase()]: read.path.replace(/\{[^}]+\}/, `{{${idVar}}}`),
+    expect: { status: 200, body: verifyBody as unknown as Record<string, Record<string, string>> },
+  } as unknown as RawStep);
+
+  if (del) {
+    tests.push({
+      name: "cleanup",
+      [del.method.toUpperCase()]: del.path.replace(/\{[^}]+\}/, `{{${idVar}}}`),
+      always: true,
+      expect: { status: [200, 202, 204] },
+    } as unknown as RawStep);
+  }
+
+  return {
+    name: `ma ${slugFromPath(create.path)}`,
+    base_url: "{{base_url}}",
+    headers: { Authorization: "Bearer {{auth_token}}" },
+    tests,
+  };
+}
+
+function buildSingleStep(
+  ep: EndpointInfo,
+  privilegedBody: Record<string, unknown>,
+  _protectedFields: string[],
+): RawSuite {
+  const method = ep.method.toUpperCase();
+  const tests: RawStep[] = [];
+  const step: Record<string, unknown> = {
+    name: `mass-assignment ${method} ${ep.path}`,
+    [method]: ep.path,
+    expect: { status: [400, 422] },
+  };
+  if (method !== "GET" && method !== "DELETE") {
+    // ARV-198: same form/json branching as the full-chain create — see
+    // buildFullChain for rationale (Stripe-style mutators declare only
+    // application/x-www-form-urlencoded).
+    if (isFormEndpoint(ep)) {
+      step.headers = { "Content-Type": "application/x-www-form-urlencoded" };
+      step.form = privilegedBody;
+    } else {
+      step.json = privilegedBody;
+    }
+  }
+  tests.push(step as unknown as RawStep);
+  return {
+    name: `ma ${slugFromPath(ep.path)}`,
+    base_url: "{{base_url}}",
+    headers: { Authorization: "Bearer {{auth_token}}" },
+    tests,
+  };
+}
+
+function pathsEqual(a: string, b: string): boolean {
+  return a.replace(/\/$/, "") === b.replace(/\/$/, "");
+}
+
+function similar(a: string, b: string): boolean {
+  const aSeg = a.split("/").filter(Boolean);
+  const bSeg = b.split("/").filter(Boolean);
+  return aSeg.some(s => bSeg.includes(s));
+}
+
+function slugFromPath(p: string): string {
+  return p.replace(/^\//, "").replace(/\/?\{[^}]+\}/g, "").replace(/\//g, "-") || "endpoint";
+}

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

@@ -18,19 +18,19 @@
 import type { OpenAPIV3 } from "openapi-types";
 import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
 import type { RawSuite, RawStep } from "../generator/serializer.ts";
-
-// ──────────────────────────────────────────────
-// Constants
-// ──────────────────────────────────────────────
-
-const ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
-type Method = (typeof ALL_METHODS)[number];
-
-/** Statuses we accept on a *missing* method. 405 is canonical, 404 is a
- *  common fallback (path not registered for that method), 401/403 are
- *  acceptable when auth is checked before routing. Anything else — notably
- *  5xx (unhandled), 200/201 (silent acceptance) — is a probe failure. */
-const ACCEPTABLE_STATUSES = [401, 403, 404, 405];
+import { pathWithByAliases, getAuthHeaders } from "./shared.ts";
+import {
+  ALL_METHODS,
+  ACCEPTABLE_UNSUPPORTED_STATUSES,
+  bucketEndpointsByPath,
+  pathWithMethodPlaceholders,
+  type Method,
+} from "./method-shared.ts";
+
+// 405-or-equivalent statuses for an *undeclared* method probe. ARV-2
+// (m-15) extracted this list to method-shared.ts so the live
+// `unsupported_method` check stays in lock-step with the offline probe.
+const ACCEPTABLE_STATUSES = [...ACCEPTABLE_UNSUPPORTED_STATUSES];
 
 // ──────────────────────────────────────────────
 // Types
@@ -67,75 +67,22 @@ function slugify(s: string): string {
 }
 
 function pathStem(path: string): string {
-  const cleaned = path
-    .replace(/\{[^}]+\}/g, "by-id")
+  // TASK-159 (m-9 P3): preserve placeholder name (`by-org`, `by-proj`)
+  // instead of collapsing every `{x}` to a generic `by-id`.
+  const cleaned = pathWithByAliases(path)
     .replace(/^\//, "")
     .replace(/\//g, "-");
   return slugify(cleaned) || "root";
 }
 
-/** Replace path params with valid-shape placeholders so the request can
- *  reach the routing layer without being rejected purely on path syntax. */
-function pathWithPlaceholders(
-  path: string,
-  parameters: OpenAPIV3.ParameterObject[],
-): string {
-  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
-    const param = 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 "999999999";
-    return "nonexistent-zzzzz";
-  });
-}
-
-function getAuthHeaders(
-  ep: EndpointInfo,
-  schemes: SecuritySchemeInfo[],
-): Record<string, string> | undefined {
-  if (ep.security.length === 0) return undefined;
-  for (const secName of ep.security) {
-    const scheme = schemes.find((s) => s.name === secName);
-    if (!scheme) continue;
-    if (scheme.type === "http") {
-      if (scheme.scheme === "bearer" || !scheme.scheme) {
-        return { Authorization: "Bearer {{auth_token}}" };
-      }
-      if (scheme.scheme === "basic") {
-        return { Authorization: "Basic {{auth_token}}" };
-      }
-    }
-    if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
-      if (scheme.apiKeyName === "Authorization") {
-        return { Authorization: "Bearer {{auth_token}}" };
-      }
-      return { [scheme.apiKeyName]: "{{api_key}}" };
-    }
-  }
-  return undefined;
-}
-
-interface PathBucket {
+// pathWithPlaceholders + bucketByPath moved to ./method-shared.ts for
+// reuse by the live `unsupported_method` check (m-15 ARV-2).
+const pathWithPlaceholders = pathWithMethodPlaceholders;
+const bucketByPath = (endpoints: EndpointInfo[]): Array<{
   path: string;
-  /** Methods declared on this path, normalized to upper-case. */
   declared: Set<string>;
-  /** A representative endpoint we can borrow auth/path-param shape from. */
   sample: EndpointInfo;
-}
-
-function bucketByPath(endpoints: EndpointInfo[]): PathBucket[] {
-  const map = new Map<string, PathBucket>();
-  for (const ep of endpoints) {
-    if (ep.deprecated) continue;
-    let bucket = map.get(ep.path);
-    if (!bucket) {
-      bucket = { path: ep.path, declared: new Set(), sample: ep };
-      map.set(ep.path, bucket);
-    }
-    bucket.declared.add(ep.method.toUpperCase());
-  }
-  return Array.from(map.values());
-}
+}> => Array.from(bucketEndpointsByPath(endpoints).values());
 
 // ──────────────────────────────────────────────
 // Public API
@@ -165,10 +112,25 @@ export function generateMethodProbes(opts: MethodProbeOptions): MethodProbeResul
     const headers = getAuthHeaders(bucket.sample, securitySchemes);
 
     const steps: RawStep[] = missing.map((method) => {
+      // ARV-179: OPTIONS on an undeclared path is legitimately handled
+      // by most stacks (CORS preflight, 200/204 with Allow header). Let
+      // the probe accept 2xx for OPTIONS only; everything else keeps
+      // the strict "no 2xx, no 5xx" expectation.
+      const acceptable = method === "OPTIONS"
+        ? [200, 204, ...ACCEPTABLE_STATUSES]
+        : ACCEPTABLE_STATUSES;
+      const expectLabel = method === "OPTIONS"
+        ? `${method} ${bucket.path} — undeclared method must not 5xx (OPTIONS may legitimately succeed)`
+        : `${method} ${bucket.path} — undeclared method must reject (no 5xx, no 2xx)`;
       const step: RawStep = {
-        name: `${method} ${bucket.path} — undeclared method must reject (no 5xx, no 2xx)`,
+        name: expectLabel,
+        source: {
+          generator: "method-probe",
+          endpoint: `${method} ${bucket.path}`,
+          response_branch: acceptable.map(String).join("|"),
+        },
         [method]: convertPath(concretePath),
-        expect: { status: ACCEPTABLE_STATUSES },
+        expect: { status: acceptable },
       };
       // Body-bearing methods on an undeclared route — send a minimal valid
       // JSON object to provoke any body-parsing path while the router is
@@ -186,6 +148,11 @@ export function generateMethodProbes(opts: MethodProbeOptions): MethodProbeResul
     suites.push({
       name: `probe methods ${bucket.path}`,
       tags: ["probe-methods", "negative-method", "no-5xx", "smoke"],
+      source: {
+        type: "probe-suite",
+        generator: "method-probe",
+        endpoint: bucket.path,
+      },
       fileStem: `probe-methods-${stem}`,
       base_url: "{{base_url}}",
       ...(headers ? { headers } : {}),

package/src/core/probe/method-shared.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared bits between the offline `method-probe` (which emits YAML
+ * suites) and the live `unsupported_method` check from `core/checks`
+ * (m-15 ARV-2). Both ask the same question — "which HTTP methods aren't
+ * declared on this path?" — so the constants and helpers live here so
+ * the two stay in lock-step (ARV-2 AC #4).
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { EndpointInfo } from "../generator/types.ts";
+
+/** ARV-179: full HTTP method complement used for `unsupported_method`
+ *  enumeration. Matches schemathesis V4 `DEFAULT_UNEXPECTED_METHODS`
+ *  minus the WebDAV-style `query` (not a REST norm) and `CONNECT`
+ *  (irrelevant to API routing). `HEAD` is intentionally excluded
+ *  because most stacks auto-derive it from `GET`, so a 2xx response is
+ *  expected behaviour rather than a leak. */
+export const ALL_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE"] as const;
+export type Method = (typeof ALL_METHODS)[number];
+
+/** Statuses we accept for an *undeclared* method on a path. 405 is
+ *  canonical, 404 is a common fallback (path not registered for that
+ *  method), 401/403 are acceptable when auth is checked before routing. */
+export const ACCEPTABLE_UNSUPPORTED_STATUSES = [401, 403, 404, 405] as const;
+
+/** ARV-179: OPTIONS is special — it's legitimately implemented by most
+ *  stacks for CORS preflight and may legitimately return 2xx with
+ *  `Allow`/`Access-Control-*` headers. A 2xx OPTIONS on an undeclared
+ *  path is the spec-compliant outcome, not a finding. Use this helper
+ *  in both the offline probe and the live check to keep the policy in
+ *  one place. */
+export function isPermissibleOptionsResponse(method: string, status: number): boolean {
+  return method.toUpperCase() === "OPTIONS" && status >= 200 && status < 300;
+}
+
+/**
+ * Replace `{name}` segments with valid-shape placeholders so the
+ * request can reach the routing layer without being rejected purely on
+ * path syntax. Used by both the offline probe and the live check.
+ */
+export function pathWithMethodPlaceholders(
+  path: string,
+  parameters: OpenAPIV3.ParameterObject[],
+): string {
+  return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    const param = 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 "999999999";
+    return "nonexistent-zzzzz";
+  });
+}
+
+export function bucketEndpointsByPath(endpoints: EndpointInfo[]): Map<string, {
+  path: string;
+  declared: Set<string>;
+  sample: EndpointInfo;
+}> {
+  const map = new Map<string, { path: string; declared: Set<string>; sample: EndpointInfo }>();
+  for (const ep of endpoints) {
+    if (ep.deprecated) continue;
+    let bucket = map.get(ep.path);
+    if (!bucket) {
+      bucket = { path: ep.path, declared: new Set(), sample: ep };
+      map.set(ep.path, bucket);
+    }
+    bucket.declared.add(ep.method.toUpperCase());
+  }
+  return map;
+}