session-orchestrator 3.16.0

package/scripts/lib/validate/confidential-names.mjs

@@ -0,0 +1,169 @@
+/**
+ * confidential-names.mjs — Host-local confidential customer/repo name list (Issue #728a).
+ *
+ * The owner-leakage scanner (check-owner-leakage.mjs) guards owner PATHS and a
+ * CLOSED, audit-reviewed list of private slugs (CP6). It cannot enumerate the
+ * OPEN-ended set of confidential customer / source-repo names the Operator's
+ * confidentiality rule (2026-07-02) forbids in GitHub-visible artefacts — those
+ * names must never live in a committed file (that would be the very leak they
+ * guard against).
+ *
+ * This module loads a HOST-LOCAL name list, referenced by owner.yaml
+ * (`paths.confidential-names-file`, env `SO_CONFIDENTIAL_NAMES_FILE`) OUTSIDE any
+ * repo, so the confidential names are never committed; only the PATH mechanism is
+ * committed. The scanner's CP11 rule builds word-boundary regexes from the loaded
+ * names and REDACTS any match from its output (a CP11 hit printed verbatim to the
+ * public CI log would be a WORSE leak than the one being guarded).
+ *
+ * Contract:
+ *   loadConfidentialNames({ namesPath, deps? }) → string[] | null
+ *
+ *   - `namesPath` empty/whitespace/non-string → null (no list configured; SILENT —
+ *     this is the default for the ~99% of hosts without a list).
+ *   - file missing / unreadable / malformed-JSON / non-array → null + one stderr WARN.
+ *   - Each entry is validated: it must be a non-empty string within a length cap
+ *     (MAX_NAME_LENGTH — a ReDoS/DoS guard against a manipulated host-local file;
+ *     a real customer/repo name never exceeds it). Entries failing either check
+ *     are dropped with an aggregate COUNT-ONLY WARN (the offending names are NOT
+ *     logged — logging them would defeat the confidentiality guarantee).
+ *   - Result is CACHED per process, keyed by namesPath (the scanner reads it once).
+ *
+ * Privacy: this module never writes the list anywhere; it only reads the operator's
+ * host-local file. WARN messages carry the file PATH (the operator's own config
+ * path, shown transiently on their terminal) but NEVER the confidential names.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+
+/**
+ * Max characters for a single confidential name. A real customer / repo name is
+ * always far shorter; a longer entry in the host-local file is a corruption or a
+ * DoS payload (an oversized string fed into a regex constructor is a ReDoS/DoS
+ * vector). Over-long entries are dropped with a count-only WARN.
+ */
+const MAX_NAME_LENGTH = 256;
+
+/** Per-process cache: namesPath → (string[] | null). */
+const _cache = new Map();
+
+/**
+ * Clear the per-process confidential-names cache. Test-only seam — production
+ * code never needs to reset (the list file does not change mid-process).
+ */
+export function _resetConfidentialNamesCache() {
+  _cache.clear();
+}
+
+/** Default (production) dependency bindings — overridable per call for tests. */
+const DEFAULT_DEPS = {
+  readFileSync,
+  existsSync,
+  warn: (msg) => process.stderr.write(msg),
+};
+
+/**
+ * Parse + validate the raw JSON body into a list of confidential names.
+ * Returns null when the body is malformed or yields zero usable entries.
+ *
+ * @param {string} raw
+ * @param {string} namesPath
+ * @param {{ warn: (msg: string) => void }} d
+ * @returns {string[]|null}
+ */
+function parseNames(raw, namesPath, d) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    // Fix 3 (security-reviewer): NEVER embed err.message — V8's JSON.parse error
+    // text echoes the first ~10 chars of the file body, which for a confidential-
+    // names file is a would-be confidential-name prefix. Log only the error CLASS
+    // (err.name, e.g. SyntaxError) + the path. Keeps the module-docstring invariant
+    // ("WARN messages … NEVER the confidential names") true.
+    d.warn(
+      `WARN validate/confidential-names: malformed JSON in ${namesPath} (${err.name}); CP11 inactive\n`,
+    );
+    return null;
+  }
+
+  if (!Array.isArray(parsed)) {
+    d.warn(
+      `WARN validate/confidential-names: ${namesPath} must be a JSON array of strings; ignoring the list (CP11 inactive)\n`,
+    );
+    return null;
+  }
+
+  const names = [];
+  let ignoredInvalid = 0;
+  let ignoredOversized = 0;
+
+  for (const entry of parsed) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+      ignoredInvalid += 1;
+      continue;
+    }
+    // Length cap on the RAW entry (before trim) — a padded oversized payload is
+    // still a payload. A real confidential name never approaches this bound.
+    if (entry.length > MAX_NAME_LENGTH) {
+      ignoredOversized += 1;
+      continue;
+    }
+    names.push(entry.trim());
+  }
+
+  if (ignoredInvalid > 0 || ignoredOversized > 0) {
+    // Deliberately omit the offending entries — logging them would leak the very
+    // confidential names the list exists to keep host-local. COUNTS only.
+    d.warn(
+      `WARN validate/confidential-names: ignored ${ignoredInvalid} invalid and ${ignoredOversized} oversized (>${MAX_NAME_LENGTH} chars) name entr(ies) in ${namesPath}\n`,
+    );
+  }
+
+  return names.length > 0 ? names : null;
+}
+
+/**
+ * Load and validate the host-local confidential-names list. Defensive — never throws.
+ *
+ * @param {object} opts
+ * @param {string|null|undefined} opts.namesPath - absolute path to the names JSON, or
+ *   empty/absent when no list is configured.
+ * @param {Partial<typeof DEFAULT_DEPS>} [opts.deps] - injected fs / warn (tests).
+ * @returns {string[]|null} the validated names, or null when unconfigured/unusable.
+ */
+export function loadConfidentialNames({ namesPath, deps = {} } = {}) {
+  const d = { ...DEFAULT_DEPS, ...deps };
+
+  // Unconfigured → no list, no noise. This is the normal case for public repos
+  // and for any host that has not opted into confidential-name scanning.
+  if (typeof namesPath !== 'string' || namesPath.trim() === '') {
+    return null;
+  }
+
+  if (_cache.has(namesPath)) {
+    return _cache.get(namesPath);
+  }
+
+  let result = null; // default when the file is missing/unreadable/unusable
+  try {
+    if (!d.existsSync(namesPath)) {
+      d.warn(
+        `WARN validate/confidential-names: confidential-names-file is set but the file does not exist: ${namesPath}; CP11 inactive\n`,
+      );
+    } else {
+      const raw = d.readFileSync(namesPath, 'utf8');
+      result = parseNames(raw, namesPath, d);
+    }
+  } catch (err) {
+    // Fix 3 (security-reviewer): log the error CLASS, not err.message. A filesystem
+    // error rarely embeds file content, but keeping the invariant uniform ("the WARN
+    // carries only counts / err-class + the path, never file body") removes the last
+    // err.message sink in this module.
+    d.warn(
+      `WARN validate/confidential-names: failed to read confidential-names file at ${namesPath} (${err.name}); CP11 inactive\n`,
+    );
+  }
+
+  _cache.set(namesPath, result);
+  return result;
+}

package/scripts/lib/validate/dead-bridge-corpus.mjs

@@ -0,0 +1,141 @@
+// dead-bridge-corpus.mjs — Regression corpus + declared real bridges for the
+// dead-bridge validator. Issue #671.
+//
+// PROVENANCE: This module is the equivalence anchor that proves the unified
+// dead-bridge validator subsumes three previously-separate guards:
+//   - #614 dangling-subagent-type   (subagent_type references a non-existent agent)
+//   - #445 dangling-rule-reference  (a "See Also" footer cites a missing sibling rule)
+//   - #618 dangling-bootstrap-bridge(a bootstrap shell guard checks a renamed/absent file)
+// plus a NEW class introduced by the unified validator:
+//   - bridge-balance               (a declared producer/consumer pair where one side
+//                                     has zero live matches — set-but-never-read or
+//                                     read-but-never-set)
+//
+// PURE DATA MODULE — no IO, no console, no process.exit. Import-safe.
+// The detectors (dead-bridge-detectors.mjs) and the CLI (check-dead-bridge.mjs)
+// consume these exports; this module never reaches the filesystem itself.
+
+/**
+ * @typedef {Object} CorpusCase
+ * @property {string} id          Stable identifier for the regression case.
+ * @property {'dangling-subagent-type'|'dangling-rule-reference'|'dangling-bootstrap-bridge'|'bridge-balance'} rule
+ * @property {string} description Human-readable summary of what the case proves.
+ * @property {string} positive    Minimal source text that MUST produce a Finding for `rule`.
+ * @property {string} negative    Minimal source text that MUST NOT produce any Finding.
+ */
+
+/**
+ * Regression corpus. Each row is an equivalence anchor: the detector for `rule`
+ * MUST flag `positive` and MUST clear `negative`. The Quality wave's corpus test
+ * consumes these strings directly — keep them minimal and self-contained.
+ * @type {CorpusCase[]}
+ */
+export const CORPUS = [
+  {
+    id: '614-dead-subagent-type',
+    rule: 'dangling-subagent-type',
+    description:
+      '#614 — a subagent_type reference must resolve to an agent that exists under agents/. ' +
+      'The positive names a ghost agent; the negative names code-implementer (which exists).',
+    positive: 'subagent_type: "session-orchestrator:ghost-agent-xyz"',
+    negative: 'subagent_type: "session-orchestrator:code-implementer"',
+  },
+  {
+    id: '445-dangling-rule-ref',
+    rule: 'dangling-rule-reference',
+    description:
+      '#445 — a "## See Also" footer entry ending in .md must resolve to a sibling rule file ' +
+      'under .claude/rules/. The positive cites a non-existent sibling; the negative cites ' +
+      'security.md (which exists in .claude/rules/).',
+    positive: '## See Also\nfoo · ghost-rule-xyz.md · bar',
+    negative: '## See Also\nfoo · security.md · bar',
+  },
+  {
+    id: '618-renamed-dep-guard',
+    rule: 'dangling-bootstrap-bridge',
+    description:
+      '#618 — a bootstrap shell guard that tests for a plugin-relative file must point at a ' +
+      'file that actually exists. The positive checks fetch-baseline.sh (only the .mjs exists ' +
+      'after the rename); the negative checks fetch-baseline.mjs (present).',
+    positive: '[ -f "$PLUGIN_ROOT/scripts/lib/fetch-baseline.sh" ]',
+    negative: '[ -f "$PLUGIN_ROOT/scripts/lib/fetch-baseline.mjs" ]',
+  },
+  {
+    id: 'bridge-balance-set-never-read',
+    rule: 'bridge-balance',
+    description:
+      'NEW class — a declared producer/consumer bridge where the consumer side has zero live ' +
+      'matches (set-but-never-read). The positive declares an event that is emitted but never ' +
+      'consumed; the negative declares an event that is both emitted and consumed.',
+    positive:
+      'producer emits "orphan_event_set_never_read"; consumer reads <nothing> → 0 consumer matches',
+    negative:
+      'producer emits "paired_event"; consumer reads "paired_event" → both sides >= 1 match',
+  },
+  {
+    id: 'bridge-balance-read-never-set',
+    rule: 'bridge-balance',
+    description:
+      'NEW class — a declared producer/consumer bridge where the producer side has zero live ' +
+      'matches (read-but-never-set). The positive declares a config key that is read but never ' +
+      'documented/written; the negative declares a key that is both written and read.',
+    positive:
+      'consumer reads "phantom_key_read_never_set"; producer writes <nothing> → 0 producer matches',
+    negative:
+      'consumer reads "paired_key"; producer writes "paired_key" → both sides >= 1 match',
+  },
+];
+
+/**
+ * @typedef {Object} BridgeEndpoint
+ * @property {string} pattern   Literal/regex token grepped for at this endpoint.
+ * @property {string[]} scope   Repo-relative paths (files or dirs) the grep is scoped to.
+ * @property {string[]} [exts]  Optional file-extension allow-list within `scope`.
+ */
+
+/**
+ * @typedef {Object} Bridge
+ * @property {string} id           Stable identifier for the declared bridge.
+ * @property {string} description  What the producer/consumer pair represents.
+ * @property {BridgeEndpoint} producer  The "set"/"emit"/"document" side.
+ * @property {BridgeEndpoint} consumer  The "read"/"parse"/"consume" side.
+ */
+
+/**
+ * Declared REAL bridges, checked against the LIVE repo by detectBridgeBalance.
+ * EVERY entry here MUST currently be BALANCED (both endpoints have >= 1 match) so
+ * `node scripts/lib/validate/check-dead-bridge.mjs` stays GREEN. Only declare
+ * pairs that have been grep-proven balanced.
+ *
+ * Grep-proven 2026-06-24 (#671 Wave 2; re-verified Wave 3 against the fixed,
+ * file-or-dir-aware detector):
+ *   producer: rg -c "test-command" docs/session-config-template.md  => 5
+ *   consumer: rg -c "test-command" scripts/lib/config.mjs           => 2
+ *
+ * NOTE: `scope` entries below are concrete FILE paths (not directories) and
+ * `exts` are declared without a leading dot (`'md'`/`'mjs'`). The detector's
+ * countMatches() handles both file/dir scope entries and normalizes exts, so
+ * this declaration is LIVE — detectBridgeBalance counts 5/2, not 0/0.
+ *
+ * @type {Bridge[]}
+ */
+export const BRIDGES = [
+  {
+    id: 'session-config-test-command',
+    description:
+      'The `test-command` Session Config key is DOCUMENTED in the config template (producer) ' +
+      'and PARSED by the config reader (consumer, via _coerceString(kv, "test-command", ...)). ' +
+      'Both endpoints must keep at least one live match — a rename on either side leaves the ' +
+      'other dangling.',
+    producer: {
+      pattern: 'test-command',
+      scope: ['docs/session-config-template.md'],
+      exts: ['md'],
+    },
+    consumer: {
+      pattern: 'test-command',
+      scope: ['scripts/lib/config.mjs'],
+      exts: ['mjs'],
+    },
+  },
+];