coldpin 0.0.0-stage → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/ACCESSIBILITY.md +17 -0
  2. package/CHANGELOG.md +97 -0
  3. package/CONTRIBUTING.md +36 -0
  4. package/LICENSE +98 -0
  5. package/MAINTENANCE.md +33 -0
  6. package/README.md +142 -2
  7. package/SECURITY.md +34 -0
  8. package/TESTING.md +26 -0
  9. package/agents/coldpin-auditor.md +47 -0
  10. package/agents/coldpin-compliance.md +38 -0
  11. package/agents/coldpin-confusion-auditor.md +38 -0
  12. package/agents/coldpin-discoverer.md +37 -0
  13. package/agents/coldpin-forensics.md +38 -0
  14. package/agents/coldpin-inspector.md +37 -0
  15. package/agents/coldpin-manifest-auditor.md +38 -0
  16. package/assets/icon.svg +7 -0
  17. package/catalog/mcp-schema-pin.json +14 -0
  18. package/catalog/plugin.oms.sig +19 -0
  19. package/catalog/sigma/npx-suspicious-child-process-linux.yml +54 -0
  20. package/catalog/sigma/npx-suspicious-child-process.yml +49 -0
  21. package/catalog/triage-rules.json +104 -0
  22. package/docs/assets/readme-header.svg +21 -0
  23. package/docs/designs/SITEMAP.md +14 -0
  24. package/docs/designs/coldpin.md +68 -0
  25. package/docs/fact-ledger.md +36 -0
  26. package/docs/faq.md +31 -0
  27. package/docs/getting_started.md +62 -0
  28. package/docs/harnesses.md +45 -0
  29. package/docs/privacy.md +27 -0
  30. package/docs/verification/skill-inspector-self-audit.md +33 -0
  31. package/examples/.coldpin.policy.example.json +27 -0
  32. package/examples/.npmrc.example +8 -0
  33. package/examples/mcp_config.private-registry.example.json +42 -0
  34. package/hooks.json +47 -0
  35. package/lib/analysis/parity-and-bisect.mjs +1371 -0
  36. package/lib/analysis/static-triage.mjs +4572 -0
  37. package/lib/cache/sqlite-store.mjs +251 -0
  38. package/lib/cli.mjs +427 -0
  39. package/lib/compliance/audit-log.mjs +357 -0
  40. package/lib/config/policy.mjs +780 -0
  41. package/lib/core/path-confinement.mjs +289 -0
  42. package/lib/core/workflows.mjs +1205 -0
  43. package/lib/discovery/slopsquat-guard.mjs +289 -0
  44. package/lib/hook.mjs +1038 -0
  45. package/lib/intel/registry-osv.mjs +1681 -0
  46. package/lib/mcp/report-store.mjs +175 -0
  47. package/lib/mcp/server.mjs +1387 -0
  48. package/lib/mcp/stdio-transport.mjs +289 -0
  49. package/lib/mcp/tool-catalog.mjs +273 -0
  50. package/lib/mcp/types.mjs +95 -0
  51. package/lib/mcp.mjs +19 -0
  52. package/lib/quarantine/safe-unpack.mjs +568 -0
  53. package/lib/types.mjs +383 -0
  54. package/lib/verdict/engine-and-formatters.mjs +895 -0
  55. package/mcp_config.json +21 -0
  56. package/package.json +71 -3
  57. package/plugin.json +54 -0
  58. package/rules/AGENTS.md +18 -0
  59. package/rules/coldpin-incident-checklist.md +18 -0
  60. package/rules/coldpin-manifest-guard.md +14 -0
  61. package/server.json +38 -0
  62. package/skills/coldpin/BENCHMARK.md +166 -0
  63. package/skills/coldpin/SKILL.md +110 -0
  64. package/skills/coldpin/TEST.md +13 -0
  65. package/skills/coldpin/agents/openai.yaml +6 -0
  66. package/skills/coldpin/assets/icon.svg +7 -0
  67. package/skills/coldpin/assets/runtime-contract.yaml +105 -0
  68. package/skills/coldpin/evals/evals.json +60 -0
  69. package/skills/coldpin/references/aspect-compliance-audit.md +27 -0
  70. package/skills/coldpin/references/aspect-discovery.md +26 -0
  71. package/skills/coldpin/references/aspect-forensics-rea.md +26 -0
  72. package/skills/coldpin/references/aspect-inspection.md +26 -0
  73. package/skills/coldpin/references/aspect-manifest-confusion.md +26 -0
  74. package/skills/coldpin/references/enterprise-policy-schema.md +65 -0
  75. package/skills/coldpin/references/evidence-card-spec.md +27 -0
  76. package/skills/coldpin/references/rea-integration-playbook.md +34 -0
  77. package/skills/coldpin/references/threat-taxonomy.md +35 -0
  78. package/skills/coldpin/skill-card.md +62 -0
  79. package/skills/coldpin/skill.oms.sig +19 -0
  80. package/skills/coldpin/test_scenarios.yaml +61 -0
  81. package/skills/coldpin-audit/SKILL.md +39 -0
  82. package/skills/coldpin-incident/SKILL.md +37 -0
  83. package/src/analysis/parity-and-bisect.ts +1368 -0
  84. package/src/analysis/static-triage.ts +4569 -0
  85. package/src/cache/sqlite-store.ts +248 -0
  86. package/src/cli.ts +424 -0
  87. package/src/compliance/audit-log.ts +354 -0
  88. package/src/config/policy.ts +777 -0
  89. package/src/core/path-confinement.ts +286 -0
  90. package/src/core/workflows.ts +1202 -0
  91. package/src/discovery/slopsquat-guard.ts +286 -0
  92. package/src/hook.ts +1035 -0
  93. package/src/intel/registry-osv.ts +1678 -0
  94. package/src/mcp/report-store.ts +172 -0
  95. package/src/mcp/server.ts +1384 -0
  96. package/src/mcp/stdio-transport.ts +286 -0
  97. package/src/mcp/tool-catalog.ts +270 -0
  98. package/src/mcp/types.ts +92 -0
  99. package/src/mcp.ts +16 -0
  100. package/src/quarantine/safe-unpack.ts +565 -0
  101. package/src/types.ts +380 -0
  102. package/src/verdict/engine-and-formatters.ts +892 -0
@@ -0,0 +1,251 @@
1
+ import { createHash } from "node:crypto";
2
+ import { chmodSync, mkdirSync } from "node:fs";
3
+ import { homedir } from "node:os";
4
+ import { dirname, join } from "node:path";
5
+ import { DatabaseSync } from "node:sqlite";
6
+ import { CACHE_SCHEMA_VERSION, ENGINE_VERSION } from "../types.mjs";
7
+
8
+ export function defaultCacheDbPath(customDir ) {
9
+ if (customDir === ":memory:") return ":memory:";
10
+ const baseDir =
11
+ customDir ??
12
+ (process.platform === "win32"
13
+ ? join(process.env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local"), "coldpin")
14
+ : join(process.env["XDG_CACHE_HOME"] ?? join(homedir(), ".cache"), "coldpin"));
15
+ return join(baseDir, "cache.sqlite");
16
+ }
17
+
18
+ function openSqliteWithFallback(preferredPath ) {
19
+ if (preferredPath === ":memory:") {
20
+ return { db: new DatabaseSync(":memory:"), resolvedPath: ":memory:" };
21
+ }
22
+ // Never fall back to world-writable shared tmpdir() (prevents multi-user /tmp cache race [MCP-13]);
23
+ // fall directly to isolated in-memory SQLite when preferred user/plugin cache path is unwritable.
24
+ try {
25
+ const parentDir = dirname(preferredPath);
26
+ mkdirSync(parentDir, { recursive: true, mode: 0o700 });
27
+ if (process.platform !== "win32") {
28
+ try {
29
+ chmodSync(parentDir, 0o700);
30
+ } catch {
31
+ // Best-effort owner-only directory permissions
32
+ }
33
+ }
34
+ const db = new DatabaseSync(preferredPath);
35
+ if (process.platform !== "win32") {
36
+ try {
37
+ chmodSync(preferredPath, 0o600);
38
+ } catch {
39
+ // Best-effort owner-only database file permissions
40
+ }
41
+ }
42
+ db.exec("PRAGMA journal_mode = WAL;");
43
+ return { db, resolvedPath: preferredPath };
44
+ } catch {
45
+ return { db: new DatabaseSync(":memory:"), resolvedPath: ":memory:" };
46
+ }
47
+ }
48
+
49
+ export function buildFactCacheKey(params
50
+
51
+
52
+
53
+ ) {
54
+ const canonicalOptions = JSON.stringify(
55
+ Object.keys(params.options)
56
+ .sort()
57
+ .reduce ((acc, k) => {
58
+ acc[k] = params.options[k];
59
+ return acc;
60
+ }, {}),
61
+ );
62
+ const raw = [
63
+ params.content_sha,
64
+ params.ruleset_sha256,
65
+ ENGINE_VERSION,
66
+ canonicalOptions,
67
+ CACHE_SCHEMA_VERSION,
68
+ ].join("|");
69
+ return createHash("sha256").update(raw).digest("hex");
70
+ }
71
+
72
+ export function raceWithAbort (promise , signal ) {
73
+ if (!signal) return promise;
74
+ if (signal.aborted) {
75
+ return Promise.reject(new Error("Operation aborted"));
76
+ }
77
+ return new Promise ((resolvePromise, rejectPromise) => {
78
+ const onAbort = () => {
79
+ rejectPromise(new Error("Operation aborted"));
80
+ };
81
+ signal.addEventListener("abort", onAbort, { once: true });
82
+ promise.then(
83
+ (val) => {
84
+ signal.removeEventListener("abort", onAbort);
85
+ resolvePromise(val);
86
+ },
87
+ (err) => {
88
+ signal.removeEventListener("abort", onAbort);
89
+ rejectPromise(err);
90
+ },
91
+ );
92
+ });
93
+ }
94
+
95
+ /**
96
+ * Producer-once in-flight deduplicator (REA `rea-analysis-optimization` pattern).
97
+ * Coalesces concurrent identical async lookups so work runs once per key without
98
+ * letting a single caller failure or cancellation corrupt unrelated waiters.
99
+ */
100
+ export class SingleFlight {
101
+ inflight = new Map ();
102
+
103
+ run(key , producer , callerSignal ) {
104
+ let promise = this.inflight.get(key);
105
+ if (!promise) {
106
+ promise = Promise.resolve()
107
+ .then(producer)
108
+ .finally(() => {
109
+ if (this.inflight.get(key) === promise) {
110
+ this.inflight.delete(key);
111
+ }
112
+ });
113
+ // Prevent unhandled rejection if every waiter aborts before the shared producer settles
114
+ promise.catch(() => undefined);
115
+ this.inflight.set(key, promise);
116
+ }
117
+ return raceWithAbort(promise, callerSignal);
118
+ }
119
+
120
+ get activeCount() {
121
+ return this.inflight.size;
122
+ }
123
+ }
124
+
125
+ /**
126
+ * Split-Plane SQLite Cache:
127
+ * 1. `artifact_facts`: immutable structural byte facts keyed by 5-tuple SHA-256.
128
+ * 2. `threat_intel_cache`: TTL-bounded mutable OSV/MAL-star/KEV intelligence.
129
+ * Composite verdicts are NEVER cached directly; always recomputed dynamically.
130
+ */
131
+ export class SplitPlaneCache {
132
+ dbPath ;
133
+ db ;
134
+
135
+ constructor(dbPath ) {
136
+ const opened = openSqliteWithFallback(dbPath ?? defaultCacheDbPath());
137
+ this.dbPath = opened.resolvedPath;
138
+ this.db = opened.db;
139
+ this.db.exec("PRAGMA busy_timeout = 5000;");
140
+ this.db.exec("PRAGMA foreign_keys = ON;");
141
+ this.db.exec(`
142
+ CREATE TABLE IF NOT EXISTS artifact_facts (
143
+ cache_key TEXT PRIMARY KEY,
144
+ content_sha TEXT NOT NULL,
145
+ ruleset_sha256 TEXT NOT NULL,
146
+ engine_version TEXT NOT NULL,
147
+ facts_json TEXT NOT NULL,
148
+ created_at_utc TEXT NOT NULL
149
+ );
150
+
151
+ CREATE TABLE IF NOT EXISTS threat_intel_cache (
152
+ intel_key TEXT PRIMARY KEY,
153
+ source TEXT NOT NULL,
154
+ payload_json TEXT NOT NULL,
155
+ fetched_at_ms INTEGER NOT NULL,
156
+ expires_at_ms INTEGER NOT NULL
157
+ );
158
+ `);
159
+ }
160
+
161
+ getArtifactFacts (cacheKey ) {
162
+ const stmt = this.db.prepare("SELECT facts_json FROM artifact_facts WHERE cache_key = ?");
163
+ const row = stmt.get(cacheKey) ;
164
+ if (!row?.facts_json) return null;
165
+ try {
166
+ return JSON.parse(row.facts_json) ;
167
+ } catch {
168
+ return null;
169
+ }
170
+ }
171
+
172
+ putArtifactFacts(params
173
+
174
+
175
+
176
+
177
+ ) {
178
+ const stmt = this.db.prepare(`
179
+ INSERT INTO artifact_facts (cache_key, content_sha, ruleset_sha256, engine_version, facts_json, created_at_utc)
180
+ VALUES (?, ?, ?, ?, ?, ?)
181
+ ON CONFLICT(cache_key) DO UPDATE SET
182
+ facts_json = excluded.facts_json,
183
+ created_at_utc = excluded.created_at_utc
184
+ `);
185
+ stmt.run(
186
+ params.cache_key,
187
+ params.content_sha,
188
+ params.ruleset_sha256,
189
+ ENGINE_VERSION,
190
+ JSON.stringify(params.facts),
191
+ new Date().toISOString(),
192
+ );
193
+ }
194
+
195
+ getThreatIntel (intelKey , nowMs = Date.now()) {
196
+ const stmt = this.db.prepare(
197
+ "SELECT payload_json, expires_at_ms FROM threat_intel_cache WHERE intel_key = ?",
198
+ );
199
+ const row = stmt.get(intelKey) ;
200
+ if (!row?.payload_json || typeof row.expires_at_ms !== "number") return null;
201
+ try {
202
+ const data = JSON.parse(row.payload_json) ;
203
+ return { data, stale: nowMs > row.expires_at_ms };
204
+ } catch {
205
+ return null;
206
+ }
207
+ }
208
+
209
+ putThreatIntel(params
210
+
211
+
212
+
213
+
214
+
215
+ ) {
216
+ const now = params.now_ms ?? Date.now();
217
+ const expires = now + params.ttl_seconds * 1000;
218
+ const stmt = this.db.prepare(`
219
+ INSERT INTO threat_intel_cache (intel_key, source, payload_json, fetched_at_ms, expires_at_ms)
220
+ VALUES (?, ?, ?, ?, ?)
221
+ ON CONFLICT(intel_key) DO UPDATE SET
222
+ source = excluded.source,
223
+ payload_json = excluded.payload_json,
224
+ fetched_at_ms = excluded.fetched_at_ms,
225
+ expires_at_ms = excluded.expires_at_ms
226
+ `);
227
+ stmt.run(params.intel_key, params.source, JSON.stringify(params.payload), now, expires);
228
+ }
229
+
230
+ pruneExpiredIntel(nowMs = Date.now()) {
231
+ const stmt = this.db.prepare("DELETE FROM threat_intel_cache WHERE expires_at_ms < ?");
232
+ const res = stmt.run(nowMs);
233
+ return Number(res.changes ?? 0);
234
+ }
235
+
236
+ getStats() {
237
+ const a = this.db.prepare("SELECT COUNT(*) AS c FROM artifact_facts").get() ;
238
+ const t = this.db.prepare("SELECT COUNT(*) AS c FROM threat_intel_cache").get() ;
239
+ return {
240
+ artifact_facts_count: Number(a?.c ?? 0),
241
+ threat_intel_count: Number(t?.c ?? 0),
242
+ };
243
+ }
244
+
245
+ close() {
246
+ this.db.close();
247
+ }
248
+ }
249
+
250
+
251
+ //# sourceURL=cache/sqlite-store.ts
package/lib/cli.mjs ADDED
@@ -0,0 +1,427 @@
1
+ #!/usr/bin/env node
2
+ import { randomUUID } from "node:crypto";
3
+ import { resolve } from "node:path";
4
+
5
+ function checkNodeVersionFloor() {
6
+ const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
7
+ if (!Number.isFinite(major) || major < 24) {
8
+ process.stderr.write(
9
+ `Coldpin requires Node.js >= 24.0.0; detected ${process.version}. Upgrade to Node 24+ LTS.\n`,
10
+ );
11
+ process.exit(1);
12
+ }
13
+ }
14
+
15
+ checkNodeVersionFloor();
16
+
17
+ const { defaultCacheDbPath, SplitPlaneCache } = await import("./cache/sqlite-store.mjs");
18
+ const { logOperationalEvent } = await import("./compliance/audit-log.mjs");
19
+ const { loadNpmrc, loadPolicy, probeHostCapabilitiesAsync } = await import("./config/policy.mjs");
20
+ const {
21
+ runAuditManifestBatch,
22
+ runAuditVerify,
23
+ runDiscover,
24
+ runInspect,
25
+ runResolveAnchor,
26
+ runVerifyConfusion,
27
+ } = await import("./core/workflows.mjs");
28
+ const { ENGINE_VERSION } = await import("./types.mjs");
29
+ const {
30
+ formatAnchorMarkdown,
31
+ formatCycloneDxSbom,
32
+ formatDiscoveryMarkdown,
33
+ formatInspectionMarkdownCard,
34
+ formatSarif210,
35
+ } = await import("./verdict/engine-and-formatters.mjs");
36
+
37
+
38
+
39
+
40
+
41
+
42
+
43
+
44
+
45
+
46
+ const BOOLEAN_FLAGS = new Set([
47
+ "json",
48
+ "sarif",
49
+ "sbom",
50
+ "offline",
51
+ "verbose",
52
+ "check-public",
53
+ "include-dev",
54
+ "help",
55
+ "version",
56
+ ]);
57
+
58
+ const VALUE_FLAGS = new Set([
59
+ "tarball",
60
+ "git-dir",
61
+ "repo-url",
62
+ "subdir",
63
+ "org",
64
+ "creator",
65
+ "category",
66
+ "limit",
67
+ "window",
68
+ "policy",
69
+ "cache-dir",
70
+ "audit-log",
71
+ "override-ticket",
72
+ ]);
73
+
74
+ function parseCliArgs(argv ) {
75
+ const positionals = [];
76
+ const flags = {};
77
+ const args = argv.slice(2);
78
+ let i = 0;
79
+ let afterDoubleDash = false;
80
+ while (i < args.length) {
81
+ const a = args[i] ;
82
+ if (afterDoubleDash) {
83
+ positionals.push(a);
84
+ i++;
85
+ continue;
86
+ }
87
+ if (a === "--") {
88
+ afterDoubleDash = true;
89
+ i++;
90
+ continue;
91
+ }
92
+ if (a === "-h") {
93
+ flags["help"] = true;
94
+ i++;
95
+ continue;
96
+ }
97
+ if (a === "-V") {
98
+ flags["version"] = true;
99
+ i++;
100
+ continue;
101
+ }
102
+ if (a.startsWith("--")) {
103
+ const eqIdx = a.indexOf("=");
104
+ if (eqIdx > 2) {
105
+ const key = a.slice(2, eqIdx);
106
+ const val = a.slice(eqIdx + 1);
107
+ if (BOOLEAN_FLAGS.has(key)) {
108
+ flags[key] = val === "true" || val === "1";
109
+ } else if (VALUE_FLAGS.has(key)) {
110
+ flags[key] = val;
111
+ } else {
112
+ return { command: "help", positionals, flags, error: `Unknown flag: --${key}` };
113
+ }
114
+ } else {
115
+ const key = a.slice(2);
116
+ if (BOOLEAN_FLAGS.has(key)) {
117
+ flags[key] = true;
118
+ } else if (VALUE_FLAGS.has(key)) {
119
+ const next = args[i + 1];
120
+ if (next === undefined || next.startsWith("--")) {
121
+ return { command: "help", positionals, flags, error: `Flag --${key} requires a value` };
122
+ }
123
+ flags[key] = next;
124
+ i++;
125
+ } else {
126
+ return { command: "help", positionals, flags, error: `Unknown flag: --${key}` };
127
+ }
128
+ }
129
+ } else {
130
+ positionals.push(a);
131
+ }
132
+ i++;
133
+ }
134
+ const command = positionals.shift() ?? "help";
135
+ return { command, positionals, flags };
136
+ }
137
+
138
+ function strFlag(flags , name ) {
139
+ const v = flags[name];
140
+ return typeof v === "string" ? v : undefined;
141
+ }
142
+
143
+ function boolFlag(flags , name ) {
144
+ return flags[name] === true || flags[name] === "true";
145
+ }
146
+
147
+ function printHelp() {
148
+ const help = `coldpin v${ENGINE_VERSION} — Inspect npx packages cold in memory; pin clean releases with verifiable evidence
149
+
150
+ USAGE:
151
+ node src/cli.ts <command> [target] [flags]
152
+ coldpin <command> [target] [flags]
153
+
154
+ COMMANDS:
155
+ discover [query] Search npm packages by query/category/creator/org with slopsquat & policy guards
156
+ inspect <pkg[@ver]> Zero-exec tarball inspection, AST taint triage, parity & verdict card
157
+ resolve-anchor <pkg> Identify patient-zero commit and safe pre-compromise release/alternative
158
+ verify-confusion [path] Audit package.json & .npmrc for dependency confusion (T1195.001)
159
+ audit-batch [path] Batch-screen up to 50 direct dependencies from package.json (squat/policy/OSV)
160
+ audit-verify <jsonl> Verify local hash-chained audit.jsonl integrity
161
+ mcp Start local zero-dependency JSON-RPC 2.0 MCP server over stdio
162
+
163
+ COMMON FLAGS:
164
+ --json Emit canonical JSON to stdout
165
+ --sarif Emit SARIF 2.1.0 JSON (inspect)
166
+ --sbom Emit CycloneDX 1.5 SBOM + VEX JSON (inspect)
167
+ --tarball <file.tgz> Inspect a local tarball offline (inspect)
168
+ --git-dir <dir> Local Git repository path for parity or commit bisect
169
+ --repo-url <url> Git repository URL for treeless commit bisect (resolve-anchor)
170
+ --subdir <path> Monorepo subdirectory inside Git repo
171
+ --org <scope> Filter by npm org/scope (discover)
172
+ --creator <handle> Filter by maintainer/creator (discover)
173
+ --category <keyword> Filter by capability/category keyword (discover)
174
+ --limit <n> Max discovery results (default 10) or batch deps (audit-batch, 1..50)
175
+ --include-dev Include devDependencies in batch screening (audit-batch)
176
+ --window <n> Max commits to bisect (overrides policy bisect_max_commits)
177
+ --policy <file> Explicit .coldpin.policy.json path
178
+ --cache-dir <dir> Cache directory (or :memory:)
179
+ --audit-log <file> Append local hash-chained audit event to JSONL file
180
+ --override-ticket <id> Record security approval ticket ID in audit.jsonl (does not alter verdict)
181
+ --verbose Emit structured operational JSON telemetry to stderr (zero secrets/PII)
182
+ --offline Disable all outbound network queries (fail closed)
183
+ --check-public Probe public npmjs.org for unscoped claimability (verify-confusion)
184
+ --version, -V Print coldpin CLI version and exit
185
+ --help, -h Print this help message and exit
186
+
187
+ EXIT CODES:
188
+ 0 = VERIFIED_CLEAN_WITHIN_SCOPE / check passed
189
+ 2 = QUARANTINE_SUSPICIOUS or UNVERIFIABLE_UNKNOWN
190
+ 3 = MALICIOUS_INDICATORS_FOUND / confusion or audit integrity failure
191
+ 1 = CLI usage or runtime error`;
192
+ process.stdout.write(`${help}\n`);
193
+ }
194
+
195
+ async function main() {
196
+ const parsed = parseCliArgs(process.argv);
197
+ if (parsed.error) {
198
+ process.stderr.write(`Error: ${parsed.error}\n`);
199
+ return 1;
200
+ }
201
+ if (boolFlag(parsed.flags, "version")) {
202
+ process.stdout.write(`coldpin v${ENGINE_VERSION}\n`);
203
+ return 0;
204
+ }
205
+ if (parsed.command === "help" || boolFlag(parsed.flags, "help")) {
206
+ printHelp();
207
+ return 0;
208
+ }
209
+
210
+ // Early handoff to MCP stdio server before CLI policy/cache/capability initialization
211
+ if (parsed.command === "mcp") {
212
+ const { startMcpServerFromEnv } = await import("./mcp/server.mjs");
213
+ return (await startMcpServerFromEnv()) ;
214
+ }
215
+
216
+ const cwd = process.cwd();
217
+ const { policy, policy_sha256 } = loadPolicy(cwd, strFlag(parsed.flags, "policy"));
218
+ if (boolFlag(parsed.flags, "offline")) policy.offline_mode = true;
219
+ const windowArg = strFlag(parsed.flags, "window");
220
+ let parsedWindow ;
221
+ if (windowArg !== undefined) {
222
+ const n = Number(windowArg);
223
+ if (!Number.isInteger(n) || n < 1) {
224
+ process.stderr.write(`Error: --window must be a positive integer (got '${windowArg}')\n`);
225
+ return 1;
226
+ }
227
+ parsedWindow = n;
228
+ policy.bisect_max_commits = n;
229
+ }
230
+
231
+ const npmrc = loadNpmrc(cwd);
232
+ const hostCaps = await probeHostCapabilitiesAsync();
233
+ const cacheDir = strFlag(parsed.flags, "cache-dir");
234
+ const cache = new SplitPlaneCache(cacheDir ? defaultCacheDbPath(cacheDir) : defaultCacheDbPath());
235
+ const auditLogPath = strFlag(parsed.flags, "audit-log");
236
+ const overrideTicketId = strFlag(parsed.flags, "override-ticket");
237
+ const verbose = boolFlag(parsed.flags, "verbose");
238
+ const requestId = `req_${randomUUID().slice(0, 12)}`;
239
+ const asJson = boolFlag(parsed.flags, "json");
240
+ const stderrWriter = (line ) => {
241
+ process.stderr.write(line);
242
+ };
243
+
244
+ logOperationalEvent(
245
+ verbose,
246
+ {
247
+ request_id: requestId,
248
+ stage: "cli_start",
249
+ command: parsed.command,
250
+ offline: policy.offline_mode,
251
+ },
252
+ stderrWriter,
253
+ );
254
+
255
+ const ctx = {
256
+ cwd,
257
+ workspaceRoots: [cwd],
258
+ enforceRootConfinement: false,
259
+ policy,
260
+ policy_sha256,
261
+ npmrc,
262
+ host_capabilities: hostCaps,
263
+ cache,
264
+ auditLogPath: auditLogPath ? resolve(auditLogPath) : undefined,
265
+ overrideTicketId,
266
+ invokerSurface: "cli" ,
267
+ requestId,
268
+ onTelemetry: verbose
269
+ ? (ev ) => {
270
+ logOperationalEvent(true, ev, stderrWriter);
271
+ }
272
+ : undefined,
273
+ };
274
+
275
+ try {
276
+ if (parsed.command === "discover") {
277
+ const query = parsed.positionals.join(" ");
278
+ const limitStr = strFlag(parsed.flags, "limit");
279
+ let limit = 10;
280
+ if (limitStr !== undefined) {
281
+ const parsedLimit = Number(limitStr);
282
+ if (!Number.isInteger(parsedLimit) || parsedLimit < 1) {
283
+ process.stderr.write(`Error: --limit must be a positive integer (got '${limitStr}')\n`);
284
+ return 1;
285
+ }
286
+ limit = parsedLimit;
287
+ }
288
+ const res = await runDiscover(ctx, {
289
+ query,
290
+ org: strFlag(parsed.flags, "org"),
291
+ creator: strFlag(parsed.flags, "creator"),
292
+ category: strFlag(parsed.flags, "category"),
293
+ limit,
294
+ });
295
+ process.stdout.write(asJson ? `${JSON.stringify(res.report, null, 2)}\n` : `${formatDiscoveryMarkdown(res.report)}\n`);
296
+ return res.exitCode;
297
+ }
298
+
299
+ if (parsed.command === "inspect") {
300
+ const res = await runInspect(ctx, {
301
+ packageSpec: parsed.positionals[0],
302
+ tarballPath: strFlag(parsed.flags, "tarball"),
303
+ localGitDir: strFlag(parsed.flags, "git-dir"),
304
+ subdir: strFlag(parsed.flags, "subdir"),
305
+ offline: boolFlag(parsed.flags, "offline"),
306
+ });
307
+ if (!res.ok) {
308
+ process.stderr.write(`${res.error}\n`);
309
+ return res.exitCode;
310
+ }
311
+ if (boolFlag(parsed.flags, "sarif")) {
312
+ process.stdout.write(`${JSON.stringify(formatSarif210(res.report), null, 2)}\n`);
313
+ } else if (boolFlag(parsed.flags, "sbom")) {
314
+ process.stdout.write(`${JSON.stringify(formatCycloneDxSbom(res.report, res.dependencies), null, 2)}\n`);
315
+ } else if (asJson) {
316
+ process.stdout.write(`${JSON.stringify(res.report, null, 2)}\n`);
317
+ } else {
318
+ process.stdout.write(`${formatInspectionMarkdownCard(res.report)}\n`);
319
+ }
320
+ return res.exitCode;
321
+ }
322
+
323
+ if (parsed.command === "resolve-anchor") {
324
+ const res = await runResolveAnchor(ctx, {
325
+ packageName: parsed.positionals[0],
326
+ localGitDir: strFlag(parsed.flags, "git-dir"),
327
+ repoUrl: strFlag(parsed.flags, "repo-url"),
328
+ subdir: strFlag(parsed.flags, "subdir"),
329
+ window: parsedWindow,
330
+ });
331
+ if (!res.ok) {
332
+ process.stderr.write(`${res.error}\n`);
333
+ return res.exitCode;
334
+ }
335
+ process.stdout.write(asJson ? `${JSON.stringify(res.decision, null, 2)}\n` : `${formatAnchorMarkdown(res.decision)}\n`);
336
+ return res.exitCode;
337
+ }
338
+
339
+ if (parsed.command === "verify-confusion") {
340
+ const res = await runVerifyConfusion(ctx, {
341
+ manifestPath: parsed.positionals[0],
342
+ checkPublic: boolFlag(parsed.flags, "check-public"),
343
+ allowPublicProbe: true,
344
+ });
345
+ if (!res.ok) {
346
+ process.stderr.write(`${res.error}\n`);
347
+ return res.exitCode;
348
+ }
349
+ process.stdout.write(`${JSON.stringify(res.report, null, 2)}\n`);
350
+ return res.exitCode;
351
+ }
352
+
353
+ if (parsed.command === "audit-batch") {
354
+ const limitStr = strFlag(parsed.flags, "limit");
355
+ let maxDeps ;
356
+ if (limitStr !== undefined) {
357
+ const parsedLimit = Number(limitStr);
358
+ if (!Number.isInteger(parsedLimit) || parsedLimit < 1 || parsedLimit > 50) {
359
+ process.stderr.write(`Error: --limit for audit-batch must be an integer between 1 and 50 (got '${limitStr}')\n`);
360
+ return 1;
361
+ }
362
+ maxDeps = parsedLimit;
363
+ }
364
+ const res = await runAuditManifestBatch(ctx, {
365
+ manifestPath: parsed.positionals[0],
366
+ includeDev: boolFlag(parsed.flags, "include-dev"),
367
+ maxDeps,
368
+ offline: boolFlag(parsed.flags, "offline"),
369
+ });
370
+ if (!res.ok) {
371
+ process.stderr.write(`${res.error}\n`);
372
+ return res.exitCode;
373
+ }
374
+ if (asJson) {
375
+ process.stdout.write(`${JSON.stringify(res.report, null, 2)}\n`);
376
+ } else {
377
+ const r = res.report;
378
+ const lines = [
379
+ `# Coldpin Batch Dependency Screening`,
380
+ `- Manifest: \`${r.manifest_path}\``,
381
+ `- Evaluated: ${r.evaluated_count} / ${r.total_declared}${r.truncated_at_cap ? " (capped)" : ""}`,
382
+ `- Clean screened: ${r.summary_counts.clean_screened} | Suspicious: ${r.summary_counts.flagged_suspicious} | Malicious/Blocked: ${r.summary_counts.malicious_or_blocked} | Unverifiable/Offline: ${r.summary_counts.unverifiable_offline}`,
383
+ ];
384
+ if (r.flagged.length > 0) {
385
+ lines.push("", "| Package | Status | Route | Primary Reason |", "| --- | --- | --- | --- |");
386
+ for (const f of r.flagged) {
387
+ const safeReason = (f.reasons[0] ?? "").replace(/\|/g, "\\|").slice(0, 120);
388
+ lines.push(`| \`${f.package_name}\` | ${f.status} | ${f.route} | ${safeReason} |`);
389
+ }
390
+ }
391
+ if (r.unknowns.length > 0) {
392
+ lines.push("", "## Unknowns", ...r.unknowns.map((u) => `- ${u}`));
393
+ }
394
+ process.stdout.write(`${lines.join("\n")}\n`);
395
+ }
396
+ return res.exitCode;
397
+ }
398
+
399
+ if (parsed.command === "audit-verify") {
400
+ const target = parsed.positionals[0];
401
+ if (!target) {
402
+ process.stderr.write("Error: audit-verify requires <path-to-audit.jsonl>\n");
403
+ return 1;
404
+ }
405
+ const res = await runAuditVerify(ctx, { auditLogPath: target });
406
+ if (!res.ok) {
407
+ // Preserve existing CLI JSON output on unreadable/missing audit file
408
+ const payload = { valid: false, total_events: 0, reason: res.error };
409
+ process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
410
+ return 3;
411
+ }
412
+ process.stdout.write(`${JSON.stringify(res.result, null, 2)}\n`);
413
+ return res.exitCode;
414
+ }
415
+
416
+ process.stderr.write(`Unknown command: ${parsed.command}\n`);
417
+ printHelp();
418
+ return 1;
419
+ } finally {
420
+ cache.close();
421
+ }
422
+ }
423
+
424
+ process.exitCode = await main();
425
+
426
+
427
+ //# sourceURL=cli.ts