@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/lib/core/security/agentshield-run.cjs

@@ -0,0 +1,343 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 199-04 (AS-03 / AS-04) -- the AgentShield surface adapters + run orchestrator.
+ * ==========================================================================
+ * This is the I/O layer that sits ABOVE the pure 199-03 engine
+ * (lib/core/security/agentshield-scanner.cjs). It separates "what to scan"
+ * (these 5 gatherers) from "how to classify" (scanSurface). The engine stays
+ * surface-agnostic and pure; the gatherers own all filesystem reads.
+ *
+ * Five gatherers, each reading a REAL plugin-local surface and returning an
+ * array of { surface, id, target } entries -- no gatherer makes a scanning
+ * decision, it only produces targets for scanSurface():
+ *   1. gatherMcpToolDescriptions -> .mcp.json mcpServers + each server's
+ *      entry-point source (STATIC description-string extraction, never a live
+ *      MCP handshake; this file NEVER starts a server).
+ *   2. gatherHookCommands        -> hooks/hooks.json (command STRING only, never
+ *      executed -- T-199-04-02 mitigate).
+ *   3. gatherSkillFiles          -> .claude/skills SKILL.md + skills SKILL.md.
+ *   4. gatherClaudeMdPermissions -> CLAUDE.md + .claude/rules .md files.
+ *   5. gatherSupplyChainTargets  -> package.json dependencies.
+ *
+ * runAgentShieldScan(opts) calls scanSurface() once per gathered target across
+ * all 5 NON-Brain surfaces and aggregates into one report shaped for a Shape E
+ * Action Report render. brain_egress is NOT gathered/scanned here -- that surface
+ * is already exercised at the classify()/PreToolUse-hook layer shipped by Phase
+ * 196; AgentShield's orchestrator covers the 5 NEW surfaces only (this phase's
+ * own scope).
+ *
+ * Part 7 (reuse before build): the classification logic is NOT reimplemented --
+ * every target flows through scanSurface() from 199-03. Part 8 (LOCAL): every
+ * read is a plugin-local, repo-tracked file; NO network wire opens here. Every
+ * gatherer opens files READ-ONLY (T-199-04-01 mitigate-by-construction).
+ *
+ * NO em-dashes / en-dashes anywhere (CLAUDE.md HARD RULE). Hyphens only.
+ * Pure CJS, zero npm deps.
+ *
+ * License: BSL 1.1.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { scanSurface } = require('./agentshield-scanner.cjs');
+
+// Repo root = three levels up from lib/core/security/.
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function _root(opts) {
+  return (opts && opts.root) ? opts.root : REPO_ROOT;
+}
+
+function _readTextOrNull(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+}
+
+function _readJsonOrNull(p) {
+  const txt = _readTextOrNull(p);
+  if (txt === null) return null;
+  try {
+    return JSON.parse(txt);
+  } catch (_e) {
+    return null;
+  }
+}
+
+// Strip a ${CLAUDE_PLUGIN_ROOT}/ (or any ${VAR}/) prefix from a configured path
+// so it resolves against the local repo root for a STATIC read.
+function _stripPluginRootPrefix(s) {
+  return String(s || '').replace(/\$\{[^}]+\}\/?/g, '');
+}
+
+function _lineOf(text, index) {
+  return text.slice(0, index).split('\n').length;
+}
+
+// ---------------------------------------------------------------------------
+// 1. gatherMcpToolDescriptions -- reads .mcp.json's mcpServers map and, for each
+// server's entry-point file, STATICALLY extracts tool description string literals
+// via a bounded regex over the source TEXT. This is a static read, never a live
+// MCP handshake (this plan never starts a server). MindrianOS declares its MCP
+// tool descriptions through the SDK's zod `.describe('...')` helper as well as
+// plain `description:` object literals, so both forms are captured -- each is the
+// same prompt-injection attack surface (a poisoned tool-description string).
+// ---------------------------------------------------------------------------
+function gatherMcpToolDescriptions(opts) {
+  const root = _root(opts);
+  const out = [];
+  const mcp = _readJsonOrNull(path.join(root, '.mcp.json'));
+  if (!mcp || !mcp.mcpServers || typeof mcp.mcpServers !== 'object') return out;
+
+  const serverNames = Object.keys(mcp.mcpServers);
+  for (let s = 0; s < serverNames.length; s++) {
+    const name = serverNames[s];
+    const cfg = mcp.mcpServers[name] || {};
+    const args = Array.isArray(cfg.args) ? cfg.args : [];
+    // The entry-point is the last .cjs/.js argument.
+    let entry = null;
+    for (let a = args.length - 1; a >= 0; a--) {
+      const cleaned = _stripPluginRootPrefix(args[a]);
+      if (/\.(c?js)$/.test(cleaned)) { entry = cleaned; break; }
+    }
+    if (!entry) continue;
+    const src = _readTextOrNull(path.join(root, entry));
+    if (src === null) continue;
+
+    // Match `.describe('...')` / `.describe("...")` and `description: '...'` /
+    // `description: "..."`. Captures the quote in group 1, the body in group 2.
+    const re = /(?:\.describe\s*\(|\bdescription\s*:)\s*(['"])((?:\\.|(?!\1)[\s\S])*?)\1/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+      out.push({
+        surface: 'mcp_tool_description',
+        id: name + '.' + _lineOf(src, m.index),
+        target: m[2],
+      });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 2. gatherHookCommands -- reads hooks/hooks.json, walks every hook-type array,
+// and extracts each hook's `command` STRING. The command is never executed
+// (T-199-04-02): only the literal string is handed to scanSurface().
+// ---------------------------------------------------------------------------
+function gatherHookCommands(opts) {
+  const root = _root(opts);
+  const out = [];
+  const doc = _readJsonOrNull(path.join(root, 'hooks', 'hooks.json'));
+  const hooks = doc && doc.hooks && typeof doc.hooks === 'object' ? doc.hooks : null;
+  if (!hooks) return out;
+
+  const hookTypes = Object.keys(hooks);
+  for (let t = 0; t < hookTypes.length; t++) {
+    const hookType = hookTypes[t];
+    const groups = Array.isArray(hooks[hookType]) ? hooks[hookType] : [];
+    let idx = 0;
+    for (let g = 0; g < groups.length; g++) {
+      const inner = groups[g] && Array.isArray(groups[g].hooks) ? groups[g].hooks : [];
+      for (let h = 0; h < inner.length; h++) {
+        const cmd = inner[h] && inner[h].command;
+        if (typeof cmd !== 'string' || cmd.length === 0) continue;
+        out.push({
+          surface: 'hook_scope',
+          id: hookType + '.' + idx,
+          target: cmd,
+        });
+        idx++;
+      }
+    }
+  }
+  return out;
+}
+
+// One-level glob helper: for each parent in `parents`, list its immediate
+// subdirectories and, if `child` exists inside, yield the path. Bounded to one
+// directory level (T-199-04-03 accept: repo-local, plugin-sized).
+function _globChildInSubdirs(root, parents, child) {
+  const results = [];
+  for (let p = 0; p < parents.length; p++) {
+    const parentAbs = path.join(root, parents[p]);
+    let names;
+    try {
+      names = fs.readdirSync(parentAbs, { withFileTypes: true });
+    } catch (_e) {
+      continue;
+    }
+    for (let i = 0; i < names.length; i++) {
+      if (!names[i].isDirectory()) continue;
+      const rel = path.join(parents[p], names[i].name, child);
+      const abs = path.join(root, rel);
+      try {
+        if (fs.statSync(abs).isFile()) results.push(rel);
+      } catch (_e) { /* not a file */ }
+    }
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// 3. gatherSkillFiles -- globs the SKILL.md under each .claude/skills and skills
+// subdirectory, returning one entry per file with FULL file contents as target (skill
+// injection can hide anywhere in the body) and the relative path as id.
+// ---------------------------------------------------------------------------
+function gatherSkillFiles(opts) {
+  const root = _root(opts);
+  const out = [];
+  const rels = _globChildInSubdirs(root, ['.claude/skills', 'skills'], 'SKILL.md');
+  for (let i = 0; i < rels.length; i++) {
+    const body = _readTextOrNull(path.join(root, rels[i]));
+    if (body === null) continue;
+    out.push({
+      surface: 'skill_injection',
+      id: rels[i],
+      target: body,
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 4. gatherClaudeMdPermissions -- reads CLAUDE.md (project root) plus any
+// .claude/rules/*.md, one entry per file with the FULL file contents as target.
+// The claudemd_permission rules fire on the whole file: the attack class is "a
+// permission-granting line ANYWHERE in the file", not a per-line concern.
+// ---------------------------------------------------------------------------
+function gatherClaudeMdPermissions(opts) {
+  const root = _root(opts);
+  const out = [];
+
+  const claudeMd = _readTextOrNull(path.join(root, 'CLAUDE.md'));
+  if (claudeMd !== null) {
+    out.push({ surface: 'claudemd_permission', id: 'CLAUDE.md', target: claudeMd });
+  }
+
+  const rulesDir = path.join(root, '.claude', 'rules');
+  let entries = [];
+  try {
+    entries = fs.readdirSync(rulesDir, { withFileTypes: true });
+  } catch (_e) {
+    entries = [];
+  }
+  for (let i = 0; i < entries.length; i++) {
+    if (!entries[i].isFile() || !/\.md$/.test(entries[i].name)) continue;
+    const rel = path.join('.claude', 'rules', entries[i].name);
+    const body = _readTextOrNull(path.join(root, rel));
+    if (body === null) continue;
+    out.push({ surface: 'claudemd_permission', id: rel, target: body });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 5. gatherSupplyChainTargets -- reads package.json's `dependencies` and returns
+// one { surface:'supply_chain', id:name, target:{name, version} } per dependency.
+// ---------------------------------------------------------------------------
+function gatherSupplyChainTargets(opts) {
+  const root = _root(opts);
+  const out = [];
+  const pkg = _readJsonOrNull(path.join(root, 'package.json'));
+  const deps = pkg && pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : null;
+  if (!deps) return out;
+  const names = Object.keys(deps);
+  for (let i = 0; i < names.length; i++) {
+    out.push({
+      surface: 'supply_chain',
+      id: names[i],
+      target: { name: names[i], version: deps[names[i]] },
+    });
+  }
+  return out;
+}
+
+// The 5 non-Brain gatherers, in a stable order.
+const GATHERERS = [
+  gatherMcpToolDescriptions,
+  gatherHookCommands,
+  gatherSkillFiles,
+  gatherClaudeMdPermissions,
+  gatherSupplyChainTargets,
+];
+
+// Verdict severity ordering for the per-surface worst-of rollup.
+const _VERDICT_RANK = { clean: 0, ambiguous: 1, flagged: 2 };
+function _worse(a, b) {
+  return (_VERDICT_RANK[b] > _VERDICT_RANK[a]) ? b : a;
+}
+
+// ---------------------------------------------------------------------------
+// runAgentShieldScan(opts) -- gathers every target across the 5 non-Brain
+// surfaces, runs scanSurface() on each, and aggregates into one report:
+//   {
+//     scannedAt,
+//     surfaces: { <surface>: { verdict (worst-of), findingCount } },
+//     totalFlagged, totalAmbiguous,
+//     findings: [ { surface, id, ruleId, reason } ]  (non-clean entries only)
+//   }
+// ---------------------------------------------------------------------------
+function runAgentShieldScan(opts) {
+  opts = opts || {};
+  const surfaces = {};
+  const findings = [];
+  let totalFlagged = 0;
+  let totalAmbiguous = 0;
+
+  for (let gi = 0; gi < GATHERERS.length; gi++) {
+    const entries = GATHERERS[gi](opts) || [];
+    for (let e = 0; e < entries.length; e++) {
+      const entry = entries[e];
+      const res = scanSurface(entry.surface, entry.target, opts) || {};
+      const verdict = res.verdict || 'clean';
+
+      if (!surfaces[entry.surface]) {
+        surfaces[entry.surface] = { verdict: 'clean', findingCount: 0 };
+      }
+      const bucket = surfaces[entry.surface];
+      bucket.verdict = _worse(bucket.verdict, verdict);
+
+      if (verdict !== 'clean') {
+        bucket.findingCount++;
+        if (verdict === 'flagged') totalFlagged++;
+        else if (verdict === 'ambiguous') totalAmbiguous++;
+
+        const resFindings = Array.isArray(res.findings) ? res.findings : [];
+        if (resFindings.length === 0) {
+          findings.push({ surface: entry.surface, id: entry.id, ruleId: null, reason: verdict });
+        } else {
+          for (let f = 0; f < resFindings.length; f++) {
+            findings.push({
+              surface: entry.surface,
+              id: entry.id,
+              ruleId: resFindings[f].ruleId,
+              reason: resFindings[f].reason,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    scannedAt: new Date().toISOString(),
+    surfaces: surfaces,
+    totalFlagged: totalFlagged,
+    totalAmbiguous: totalAmbiguous,
+    findings: findings,
+  };
+}
+
+// ---------- Exports ----------
+module.exports = {
+  gatherMcpToolDescriptions: gatherMcpToolDescriptions,
+  gatherHookCommands: gatherHookCommands,
+  gatherSkillFiles: gatherSkillFiles,
+  gatherClaudeMdPermissions: gatherClaudeMdPermissions,
+  gatherSupplyChainTargets: gatherSupplyChainTargets,
+  runAgentShieldScan: runAgentShieldScan,
+};

package/lib/core/security/agentshield-scanner.cjs

@@ -0,0 +1,314 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 199-03 (AS-01) -- the ONE generalized LOCAL AgentShield scanner engine.
+ * ==========================================================================
+ * scanSurface(surfaceType, target, opts) is the plugin-wide generalization of
+ * the Phase-196 brain-boundary-scan gate. brain_egress is NOT a second scanner;
+ * it is one of six registered surfaces that DELEGATES, byte-identical, to the
+ * already-shipped part8-egress-guard.classify() (Part 7: reuse before build, no
+ * second scanner engine).
+ *
+ * The six surfaces:
+ *   1. brain_egress          -> delegates to part8-egress-guard.classify()
+ *   2. mcp_tool_description   \
+ *   3. hook_scope              } ONE shared _regexSweep() primitive, parameterized
+ *   4. skill_injection         } by references/security/cve-db.json (no private copy)
+ *   5. claudemd_permission    /
+ *   6. supply_chain          -> a small structured heuristic over the CVE-DB's
+ *                               known_bad_packages / typosquat_watchlist / allowlist.
+ *
+ * Every pattern is READ from references/security/cve-db.json at require time. This
+ * file declares NO private per-surface pattern array; a new rule lands in the
+ * versioned, PR-reviewed CVE-DB, not here (AS-02, mirrors how rs-egress-prompts.cjs
+ * re-exports FORBIDDEN_PATTERNS from the Canon-authoritative source).
+ *
+ * It is a PURE LOCAL function. It opens ZERO network wire (Part 8): brain_egress
+ * inherits classify()'s local-only judge, the regex surfaces match strings, and
+ * supply_chain compares names against static lists. The engine treats every target
+ * as inert DATA: it never require()s, eval()s, or spawns the scanned content
+ * (T-199-03-03 mitigate-by-construction).
+ *
+ * verdict vocabulary: 'clean' | 'flagged' | 'ambiguous'. Return shape:
+ *   { verdict, surface, findings: [{ ruleId, reason }] }  (findings [] when clean).
+ *
+ * NO em-dashes / en-dashes anywhere (CLAUDE.md HARD RULE). Hyphens only.
+ * Pure CJS, zero npm deps at scan time.
+ *
+ * License: BSL 1.1.
+ */
+
+const egressGuard = require('../part8-egress-guard.cjs');
+const cveDb = require('../../../references/security/cve-db.json');
+
+// ---------------------------------------------------------------------------
+// Require-time defensive guard. Mirrors the rs-egress-prompts.cjs require-time
+// guard on FORBIDDEN_PATTERNS: a drifted / malformed rules source is a LOUD
+// failure at load, never a silent no-op scan.
+// ---------------------------------------------------------------------------
+if (!cveDb || typeof cveDb.version !== 'string' || !cveDb.surfaces || typeof cveDb.surfaces !== 'object') {
+  throw new Error(
+    'agentshield-scanner: cve-db.json is missing version/surfaces; ' +
+    'rules-source drift (expected a versioned surfaces map from 199-02)'
+  );
+}
+
+// The six surfaces the generalized engine covers, frozen for caller introspection.
+const SURFACES = Object.freeze([
+  'brain_egress',
+  'mcp_tool_description',
+  'hook_scope',
+  'skill_injection',
+  'claudemd_permission',
+  'supply_chain',
+]);
+
+// The four surfaces served by the shared regex-sweep primitive.
+const REGEX_SURFACES = new Set([
+  'mcp_tool_description',
+  'hook_scope',
+  'skill_injection',
+  'claudemd_permission',
+]);
+
+// Bounded reason length (T-199-03-02): reason scalars are rule descriptions, not
+// echoed input bytes, but we still clip defensively so no surfaced string is
+// unbounded.
+const REASON_MAX = 200;
+function _clip(s) {
+  s = String(s === null || s === undefined ? '' : s);
+  return s.length > REASON_MAX ? s.slice(0, REASON_MAX) : s;
+}
+
+// ---------------------------------------------------------------------------
+// _findRuleById(id) -> the first rule anywhere in the CVE-DB that declares a
+// pattern under this id. Backs the CVE-DB "see" cross-reference (a surface may
+// reuse a rule defined under another surface without duplicating its regex).
+// ---------------------------------------------------------------------------
+function _findRuleById(id) {
+  const keys = Object.keys(cveDb.surfaces);
+  for (let k = 0; k < keys.length; k++) {
+    const arr = cveDb.surfaces[keys[k]];
+    if (!Array.isArray(arr)) continue;
+    for (let i = 0; i < arr.length; i++) {
+      if (arr[i] && arr[i].id === id && arr[i].pattern) return arr[i];
+    }
+  }
+  return null;
+}
+
+// _resolveRule(rule) -> a rule that carries an actual pattern. A rule with a
+// "see" reference (no inline pattern) resolves to the referenced rule's pattern,
+// keeping the id + description of the referencing entry.
+function _resolveRule(rule) {
+  if (rule && rule.pattern) return rule;
+  if (rule && rule.see) {
+    const ref = _findRuleById(rule.see);
+    if (ref && ref.pattern) {
+      return {
+        id: rule.id,
+        pattern: ref.pattern,
+        flags: ref.flags,
+        description: rule.description || ref.description,
+      };
+    }
+  }
+  return rule;
+}
+
+// ---------------------------------------------------------------------------
+// _regexSweep(str, rules) -- the ONE generalized loop-first-hit primitive.
+//
+// This is the SAME loop-first-hit shape as rs-egress-prompts.auditQueryString,
+// generalized to an arbitrary rule array (read from cve-db.json) instead of the
+// fixed FORBIDDEN_PATTERNS. It walks the rule array in order; the first rule
+// whose regex matches wins and is returned as the hit; no match -> clean. This
+// is what makes the AgentShield engine a REAL Part-7 generalization of the 196
+// gate (one shared primitive) rather than five bolted-on scanners.
+// ---------------------------------------------------------------------------
+function _regexSweep(str, rules) {
+  for (let i = 0; i < rules.length; i++) {
+    const rule = _resolveRule(rules[i]);
+    if (!rule || !rule.pattern) continue;
+    const re = new RegExp(rule.pattern, rule.flags || '');
+    if (re.test(str)) {
+      return { hit: true, ruleId: rule.id, reason: rule.description };
+    }
+  }
+  return { hit: false };
+}
+
+// ---------------------------------------------------------------------------
+// brain_egress -- DELEGATE to the shipped Phase-196 classify(), then normalize
+// its allow/block/ambiguous verdict into the AgentShield clean/flagged/ambiguous
+// vocabulary. A string target is wrapped into the free-form brain_query payload
+// shape ({ brain_query_payload }) with the bare 'brain_query' tool name so the
+// delegate runs its free-form path exactly as the 196 gate did (byte-identical
+// frozen-scalar parity). An object target is passed through untouched.
+//
+// Phase 239 (BRAIN-01) bare-vs-scoped decision rule: this call reaches
+// classify() IN-PROCESS (no hook, no host matcher in between), so it takes
+// the BARE tool name, matching the shipped precedent in
+// lib/core/bono/persona-research.cjs:208-233 (toolName: 'brain_ask') and
+// brain-client.cjs's sendPacket PB8-10 belt (toolName: 'brain_packet'). The
+// prior default was the dead scoped-looking literal 'mcp__brain_query',
+// which never mattered for classify()'s own verdict (_isFreeFormTool does a
+// substring indexOf check that a scoped name also satisfies) but was still
+// a fabricated tool name with no live counterpart. Every current invoker of
+// scanSurface('brain_egress', ...) is a test fixture omitting opts.toolName
+// (lib/core/security/agentshield-scanner.test.cjs,
+// lib/core/security/agentshield-adapters.test.cjs,
+// tests/agentshield-e2e-smoke.test.cjs); no production orchestrator
+// (agentshield-run.cjs, scripts/agentshield-scan-cli.cjs) calls this surface
+// today (agentshield-run.cjs's own header comment states brain_egress is
+// deliberately NOT gathered/scanned there). This default is nonetheless real
+// production code on a real classify() call path, reached whenever any
+// future caller passes a string target without opts.toolName -- so a dead
+// default here was silently classifying against a fabricated name every
+// time it was reached, even though no shipped orchestrator reaches it yet.
+//
+// A caller MAY still pass the live scoped form explicitly via opts.toolName
+// (e.g. mcp__plugin_mos_mindrian-brain__brain_query or
+// mcp__mindrian-brain__brain_query) and classify() resolves it identically,
+// because _isFreeFormTool's substring check matches 'brain_query' inside
+// either form. The bare default here is the correct one for THIS call site
+// specifically because it is unauthenticated by any host matcher or hook --
+// there is no scope to assert.
+// ---------------------------------------------------------------------------
+function _scanBrainEgress(target, opts) {
+  opts = opts || {};
+  let payload;
+  let callOpts;
+  if (typeof target === 'string') {
+    payload = { brain_query_payload: target };
+    callOpts = { toolName: opts.toolName || 'brain_query' };
+  } else {
+    payload = target;
+    callOpts = opts;
+  }
+  const res = egressGuard.classify(payload, callOpts) || {};
+  let verdict;
+  if (res.verdict === 'block') verdict = 'flagged';
+  else if (res.verdict === 'allow') verdict = 'clean';
+  else verdict = 'ambiguous';
+  const findings = verdict === 'clean'
+    ? []
+    : [{ ruleId: egressGuard.EGRESS_SURFACE, reason: _clip(res.reason) }];
+  return { verdict: verdict, surface: 'brain_egress', findings: findings };
+}
+
+// ---------------------------------------------------------------------------
+// supply_chain heuristic. Accepts either { name, version } or a "name@version"
+// string. Order: known-bad exact -> typosquat watch match (flagged) -> a name
+// that IS a watchlist legit or an allowlisted VETTED name (clean) -> otherwise
+// ambiguous (fail-closed: an unrecognized package is neither proven safe nor
+// proven malicious, mirroring the brain_egress ambiguous posture).
+// ---------------------------------------------------------------------------
+function _parsePackageTarget(target) {
+  if (target && typeof target === 'object') {
+    return { name: target.name, version: target.version };
+  }
+  if (typeof target === 'string') {
+    let s = target;
+    let scope = '';
+    if (s.charAt(0) === '@') { scope = '@'; s = s.slice(1); }
+    const at = s.indexOf('@');
+    if (at === -1) return { name: scope + s, version: undefined };
+    return { name: scope + s.slice(0, at), version: s.slice(at + 1) };
+  }
+  return { name: undefined, version: undefined };
+}
+
+function _scanSupplyChain(target) {
+  const sc = cveDb.surfaces.supply_chain || {};
+  const parsed = _parsePackageTarget(target);
+  const name = parsed.name;
+  if (typeof name !== 'string' || name.length === 0) {
+    return { verdict: 'ambiguous', surface: 'supply_chain', findings: [] };
+  }
+  const lname = name.toLowerCase();
+
+  const knownBad = Array.isArray(sc.known_bad_packages) ? sc.known_bad_packages : [];
+  for (let i = 0; i < knownBad.length; i++) {
+    if (knownBad[i] === name) {
+      return {
+        verdict: 'flagged',
+        surface: 'supply_chain',
+        findings: [{ ruleId: 'supply_chain:known_bad', reason: _clip('package ' + name + ' is on the known-bad list') }],
+      };
+    }
+  }
+
+  const watch = Array.isArray(sc.typosquat_watchlist) ? sc.typosquat_watchlist : [];
+  for (let i = 0; i < watch.length; i++) {
+    const entry = watch[i] || {};
+    const names = Array.isArray(entry.watch) ? entry.watch : [];
+    for (let j = 0; j < names.length; j++) {
+      if (String(names[j]).toLowerCase() === lname) {
+        return {
+          verdict: 'flagged',
+          surface: 'supply_chain',
+          findings: [{ ruleId: 'supply_chain:typosquat', reason: _clip('possible typosquat of ' + entry.legit) }],
+        };
+      }
+    }
+  }
+  // A name that IS a watchlist "legit" entry is the legitimate package it protects.
+  for (let i = 0; i < watch.length; i++) {
+    const entry = watch[i] || {};
+    if (entry.legit && String(entry.legit).toLowerCase() === lname) {
+      return { verdict: 'clean', surface: 'supply_chain', findings: [] };
+    }
+  }
+
+  const allow = Array.isArray(sc.allowlist) ? sc.allowlist : [];
+  for (let i = 0; i < allow.length; i++) {
+    if (allow[i] && allow[i].name === name && allow[i].disposition === 'VETTED') {
+      return { verdict: 'clean', surface: 'supply_chain', findings: [] };
+    }
+  }
+
+  return { verdict: 'ambiguous', surface: 'supply_chain', findings: [] };
+}
+
+// ---------------------------------------------------------------------------
+// scanSurface(surfaceType, target, opts) -- the ONE generalized entry point.
+//   - brain_egress: delegates to classify() (block->flagged, allow->clean,
+//     ambiguous->ambiguous).
+//   - the four regex surfaces: run _regexSweep against cveDb.surfaces[surfaceType];
+//     first hit -> flagged, no hit -> clean. Never ambiguous. A non-string target
+//     throws a TypeError (fail loud, mirrors auditQueryString's input guard).
+//   - supply_chain: the structured heuristic above (can return ambiguous).
+// ---------------------------------------------------------------------------
+function scanSurface(surfaceType, target, opts) {
+  if (surfaceType === 'brain_egress') {
+    return _scanBrainEgress(target, opts);
+  }
+  if (surfaceType === 'supply_chain') {
+    return _scanSupplyChain(target);
+  }
+  if (REGEX_SURFACES.has(surfaceType)) {
+    if (typeof target !== 'string') {
+      throw new TypeError('scanSurface: ' + surfaceType + ' target must be a string; got ' + typeof target);
+    }
+    const rules = Array.isArray(cveDb.surfaces[surfaceType]) ? cveDb.surfaces[surfaceType] : [];
+    const sweep = _regexSweep(target, rules);
+    if (sweep.hit) {
+      return {
+        verdict: 'flagged',
+        surface: surfaceType,
+        findings: [{ ruleId: sweep.ruleId, reason: _clip(sweep.reason) }],
+      };
+    }
+    return { verdict: 'clean', surface: surfaceType, findings: [] };
+  }
+  throw new Error('scanSurface: unknown surface type "' + surfaceType + '"');
+}
+
+// ---------- Exports ----------
+// Only the public entry point plus the frozen surface list (AS-01).
+module.exports = {
+  scanSurface: scanSurface,
+  SURFACES: SURFACES,
+};