@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/secrets/registry.ts

@@ -0,0 +1,164 @@
+/**
+ * SecretRegistry — runtime registry of secret values + sanitizer
+ * (TASK-166, m-10).
+ *
+ * The registry is the single point that knows "this string is a secret;
+ * if you see it anywhere in a request URL, body, response, log line, or
+ * exporter, replace it with `<redacted:<var-name>>`". Every persisted
+ * artifact path (DB-write — TASK-167, exporters — TASK-168) calls
+ * `redact()` / `redactObject()` before writing, so the user can ship a
+ * digest / HTML report without scrubbing tokens by hand.
+ *
+ * Design rules:
+ *   - Exact-match only — no heuristics ("looks like a JWT", "starts with
+ *     `sk_`"). False positives are worse than false negatives here.
+ *   - Minimum length 8 — protects against `auth_token: ""` or `id: 1`
+ *     turning every "1" in the report into `<redacted>`.
+ *   - One marker format documented in one place: `<redacted:<name>>`.
+ *   - `setEnabled(false)` returns a no-op redactor for `--no-redact` (local
+ *     debug). Default is enabled.
+ *
+ * Marker format: `<redacted:auth_token>` — the name comes from the
+ * variable that registered the value (e.g. `.env.yaml` key, `--env` flag,
+ * `.secrets.yaml` future entry). Anything that opens a redacted artifact
+ * sees the variable name and knows where to look it up locally.
+ */
+
+/** Minimum length below which a registered value is silently ignored. */
+export const MIN_SECRET_LENGTH = 8;
+
+const REDACTED_MARKER_RE = /<redacted:[a-zA-Z0-9_.-]+>/;
+
+export interface SecretEntry {
+  name: string;
+  value: string;
+}
+
+export class SecretRegistry {
+  /** value → name. We keep map keyed by *value* so a single redact pass
+   *  iterates the unique values rather than all registrations. Two names
+   *  registering the same value collapse to one entry — the most recent
+   *  wins. */
+  private byValue = new Map<string, string>();
+  private enabled = true;
+
+  register(name: string, value: unknown): void {
+    if (typeof value !== "string") return;
+    if (value.length < MIN_SECRET_LENGTH) return;
+    this.byValue.set(value, name);
+  }
+
+  /**
+   * Bulk-register every string value in a flat object. Used by
+   * `.env.yaml` / `.secrets.yaml` loaders so we don't have to know in
+   * advance which keys are sensitive. The variable name carried into the
+   * marker is the object key.
+   */
+  registerAll(entries: Record<string, unknown> | undefined | null): void {
+    if (!entries) return;
+    for (const [k, v] of Object.entries(entries)) this.register(k, v);
+  }
+
+  /** Disable redaction (for `--no-redact` local debug). */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /** Names of every var that had a value registered. Stable diagnostic. */
+  redactedNames(): string[] {
+    return [...new Set(this.byValue.values())].sort();
+  }
+
+  hasSecrets(): boolean {
+    return this.byValue.size > 0;
+  }
+
+  /** Drop all registered secrets — used between test cases. */
+  clear(): void {
+    this.byValue.clear();
+  }
+
+  /**
+   * Replace every occurrence of a registered value in `text` with the
+   * marker `<redacted:<name>>`. Longest values first, so a token that
+   * happens to contain a shorter registered substring still ends up
+   * redacted as the more-specific match.
+   */
+  redact(text: string): string {
+    if (!this.enabled || this.byValue.size === 0) return text;
+    if (typeof text !== "string" || text.length === 0) return text;
+
+    let out = text;
+    for (const [value, name] of this.sortedEntries()) {
+      if (out.indexOf(value) === -1) continue;
+      out = out.split(value).join(`<redacted:${name}>`);
+    }
+    return out;
+  }
+
+  /**
+   * Deep-clone variant for arbitrary structured data (request/response
+   * bodies, header maps, JSON envelopes). Strings get redacted; numbers,
+   * booleans, null, Buffers stay as-is. Cycles are not expected on the
+   * artifact paths but we guard with `seen` to be safe.
+   */
+  redactObject<T>(obj: T): T {
+    if (!this.enabled || this.byValue.size === 0) return obj;
+    return this.deepRedact(obj, new WeakSet()) as T;
+  }
+
+  private sortedEntries(): Array<[string, string]> {
+    return [...this.byValue.entries()].sort((a, b) => b[0].length - a[0].length);
+  }
+
+  private deepRedact(node: unknown, seen: WeakSet<object>): unknown {
+    if (node == null) return node;
+    if (typeof node === "string") return this.redact(node);
+    if (typeof node !== "object") return node;
+    if (seen.has(node as object)) return node;
+    seen.add(node as object);
+
+    if (Array.isArray(node)) {
+      return node.map((v) => this.deepRedact(v, seen));
+    }
+    // Buffers / Uint8Array / Date — leave intact.
+    if (node instanceof Uint8Array || node instanceof Date) return node;
+
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(node)) {
+      out[k] = this.deepRedact(v, seen);
+    }
+    return out;
+  }
+}
+
+/**
+ * Process-wide registry. CLI commands populate it once after loading
+ * `.env.yaml` / `.secrets.yaml`; library callers can pass their own
+ * instance instead of touching this singleton in tests.
+ */
+let globalRegistry: SecretRegistry | undefined;
+
+export function getSecretRegistry(): SecretRegistry {
+  if (!globalRegistry) globalRegistry = new SecretRegistry();
+  return globalRegistry;
+}
+
+/** Replace the global registry. Tests use this to reset state. */
+export function setSecretRegistry(reg: SecretRegistry): void {
+  globalRegistry = reg;
+}
+
+/** Convenience: redact a string via the global registry. */
+export function redact(text: string): string {
+  return getSecretRegistry().redact(text);
+}
+
+/** Convenience: redact a nested object via the global registry. */
+export function redactObject<T>(value: T): T {
+  return getSecretRegistry().redactObject(value);
+}

package/src/core/secrets/secrets-file.ts

@@ -0,0 +1,115 @@
+/**
+ * `.secrets.yaml` — gitignored flat YAML file holding raw secret values
+ * for an API (TASK-170, m-10). Companion to `.env.yaml` which references
+ * keys here via `@secret:<name>`.
+ *
+ *     # apis/<name>/.secrets.yaml (NEVER committed)
+ *     auth_token: "tok_..."
+ *     dsn: "https://...@example.com/..."
+ *
+ *     # apis/<name>/.env.yaml (committable)
+ *     auth_token: "@secret:auth_token"
+ *     base_url: "https://api.example.com"
+ *
+ * Mental model: anything in `.secrets.yaml` is registered with the
+ * `SecretRegistry` at load-time, so it gets redacted in any persisted
+ * artifact (DB, exporters, digests). Anything in `.env.yaml` is plain.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getSecretRegistry } from "./registry.ts";
+
+const SECRETS_FILENAME = ".secrets.yaml";
+const SECRET_REF_RE = /^@secret:([A-Za-z_][A-Za-z0-9_.-]*)$/;
+
+/** Resolved contents of a `.secrets.yaml`. */
+export interface SecretsFile {
+  filePath: string;
+  values: Record<string, string>;
+}
+
+/**
+ * Read `.secrets.yaml` from a directory, register every value with the
+ * global SecretRegistry, and return the parsed map. Returns `null` when
+ * the file is absent — callers should treat that as "no secrets to
+ * register" rather than a failure.
+ */
+export function loadSecretsFile(dir: string): SecretsFile | null {
+  const filePath = join(dir, SECRETS_FILENAME);
+  if (!existsSync(filePath)) return null;
+  const text = readFileSync(filePath, "utf-8");
+  let parsed: unknown;
+  try {
+    parsed = (Bun as any).YAML.parse(text);
+  } catch (err) {
+    throw new Error(`Failed to parse ${filePath}: ${(err as Error).message}`);
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${filePath} must contain a flat YAML object of key: "value" entries`);
+  }
+
+  const values: Record<string, string> = {};
+  for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+    if (v == null) continue;                 // empty placeholder — skip
+    if (typeof v === "object") {
+      throw new Error(
+        `${filePath}: nested values are not supported (key "${k}"). ` +
+        `.secrets.yaml is intentionally flat — keep one level of key/value pairs.`,
+      );
+    }
+    values[k] = String(v);
+  }
+
+  const reg = getSecretRegistry();
+  reg.registerAll(values);
+
+  return { filePath, values };
+}
+
+/**
+ * Walk up a directory chain to find the first `.secrets.yaml` and load
+ * it. Used by the env loader so a single secrets file at the API root
+ * (`apis/<name>/.secrets.yaml`) is picked up regardless of which
+ * subdirectory `zond run` was invoked from.
+ */
+export function loadSecretsFromAncestor(start: string, stopAt?: string): SecretsFile | null {
+  let dir = start;
+  for (let i = 0; i < 8; i++) {
+    const file = loadSecretsFile(dir);
+    if (file) return file;
+    if (stopAt && dir === stopAt) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Resolve any `@secret:<name>` reference inside an env object against
+ * the values from `secrets`. Throws when a referenced name is missing
+ * (fail-loud).
+ */
+export function resolveSecretRefs(
+  envValues: Record<string, string>,
+  secrets: SecretsFile | null,
+  filePath: string,
+): Record<string, string> {
+  const out: Record<string, string> = { ...envValues };
+  for (const [k, v] of Object.entries(out)) {
+    const m = typeof v === "string" ? v.match(SECRET_REF_RE) : null;
+    if (!m) continue;
+    const refName = m[1]!;
+    const value = secrets?.values[refName];
+    if (value == null) {
+      const where = secrets ? secrets.filePath : `${dirname(filePath)}/${SECRETS_FILENAME}`;
+      throw new Error(
+        `${filePath}: key "${k}" references @secret:${refName} but no such entry exists in ${where}. ` +
+        `Add \`${refName}: "<value>"\` to ${where} (or remove the @secret: prefix to use a literal value).`,
+      );
+    }
+    out[k] = value;
+  }
+  return out;
+}

package/src/core/selectors/operation-filter.ts

@@ -0,0 +1,144 @@
+/**
+ * Unified operation filter (m-15 ARV-9).
+ *
+ * Parses `--include`/`--exclude` filter specs in a single grammar so
+ * `zond run`, `zond checks`, `zond probe`, and `zond generate` all
+ * accept the same `<selector>:<value>` strings without each command
+ * inventing its own flag set.
+ *
+ * Grammar:
+ *
+ *   <spec> := <selector> ":" <value>
+ *   <selector> := "path" | "method" | "tag" | "operation-id" | "operationId"
+ *   <value>:
+ *     path        — POSIX-style regex matched against `op.path`
+ *     method      — comma-separated HTTP methods, case-insensitive
+ *     tag         — comma-separated tag names, exact match (case-sensitive)
+ *     operation-id — POSIX-style regex matched against `op.operationId`
+ *
+ * Semantics:
+ *   - Multiple `--include` flags combine with OR (op passes if it
+ *     matches *any* include); when no include is given, every op is
+ *     considered included.
+ *   - `--exclude` always removes a match — combines with OR too.
+ *   - Excludes are evaluated *after* includes.
+ *
+ * Errors are returned in a `errors[]` array on the compile result so
+ * the CLI can surface a friendly multi-line message instead of a
+ * stack trace (AC #4).
+ */
+import type { EndpointInfo } from "../generator/types.ts";
+
+export type SelectorKind = "path" | "method" | "tag" | "operation-id";
+
+const SELECTOR_ALIASES: Record<string, SelectorKind> = {
+  path: "path",
+  method: "method",
+  tag: "tag",
+  "operation-id": "operation-id",
+  operationid: "operation-id",
+  operation_id: "operation-id",
+};
+
+export interface ParsedSelector {
+  kind: SelectorKind;
+  raw: string;
+  /** Regex form for `path` and `operation-id` selectors. */
+  pattern?: RegExp;
+  /** Lowercase token list for `method`/`tag` selectors. */
+  values?: string[];
+}
+
+export type ParseResult =
+  | { ok: true; selector: ParsedSelector }
+  | { ok: false; error: string };
+
+export function parseFilterSpec(spec: string): ParseResult {
+  const idx = spec.indexOf(":");
+  if (idx <= 0) {
+    return { ok: false, error: `Filter "${spec}": expected "<selector>:<value>" (e.g. path:/users/.*)` };
+  }
+  const head = spec.slice(0, idx).trim().toLowerCase();
+  const tail = spec.slice(idx + 1).trim();
+  if (tail.length === 0) {
+    return { ok: false, error: `Filter "${spec}": value is empty after "${head}:"` };
+  }
+  const kind = SELECTOR_ALIASES[head];
+  if (!kind) {
+    const known = Object.keys(SELECTOR_ALIASES).filter((k) => k === SELECTOR_ALIASES[k]).join(", ");
+    return { ok: false, error: `Filter "${spec}": unknown selector "${head}". Known: ${known}` };
+  }
+
+  if (kind === "path" || kind === "operation-id") {
+    let pattern: RegExp;
+    try {
+      pattern = new RegExp(tail);
+    } catch (err) {
+      return { ok: false, error: `Filter "${spec}": invalid regex — ${(err as Error).message}` };
+    }
+    return { ok: true, selector: { kind, raw: spec, pattern } };
+  }
+
+  // method / tag — comma-separated.
+  const values = tail.split(",").map((v) => v.trim()).filter(Boolean);
+  if (values.length === 0) {
+    return { ok: false, error: `Filter "${spec}": no values after "${head}:"` };
+  }
+  if (kind === "method") {
+    return { ok: true, selector: { kind, raw: spec, values: values.map((v) => v.toUpperCase()) } };
+  }
+  return { ok: true, selector: { kind, raw: spec, values } };
+}
+
+function selectorMatches(sel: ParsedSelector, op: EndpointInfo): boolean {
+  switch (sel.kind) {
+    case "path":
+      return sel.pattern!.test(op.path);
+    case "method":
+      return sel.values!.includes(op.method.toUpperCase());
+    case "tag":
+      return op.tags.some((t) => sel.values!.includes(t));
+    case "operation-id":
+      return op.operationId !== undefined && sel.pattern!.test(op.operationId);
+  }
+}
+
+export interface CompileFilterOptions {
+  includes?: string[];
+  excludes?: string[];
+}
+
+export interface CompiledFilter {
+  filter: (op: EndpointInfo) => boolean;
+  errors: string[];
+  /** Parsed selectors — handy for debug `--explain` output. */
+  parsed: { includes: ParsedSelector[]; excludes: ParsedSelector[] };
+}
+
+export function compileOperationFilter(opts: CompileFilterOptions = {}): CompiledFilter {
+  const errors: string[] = [];
+  const includes: ParsedSelector[] = [];
+  const excludes: ParsedSelector[] = [];
+  for (const raw of opts.includes ?? []) {
+    const r = parseFilterSpec(raw);
+    if (r.ok) includes.push(r.selector);
+    else errors.push(r.error);
+  }
+  for (const raw of opts.excludes ?? []) {
+    const r = parseFilterSpec(raw);
+    if (r.ok) excludes.push(r.selector);
+    else errors.push(r.error);
+  }
+  const filter = (op: EndpointInfo): boolean => {
+    if (includes.length > 0) {
+      const passInclude = includes.some((s) => selectorMatches(s, op));
+      if (!passInclude) return false;
+    }
+    for (const s of excludes) {
+      if (selectorMatches(s, op)) return false;
+    }
+    return true;
+  };
+  return { filter, errors, parsed: { includes, excludes } };
+}
+