calllint 0.7.0 → 0.9.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 import { execFileSync } from "node:child_process";
 
 // src/args.ts
@@ -67,6 +67,7 @@ COMMANDS
   diagnostics [target]  Emit editor/agent-host diagnostics JSON (calllint.diagnostics.v0)
   baseline [target]  Record the approved risk surface as a baseline
   approve            Record the repo-wide capability surface as approved state (L4)
+  receipt verify <f>    Structurally validate a local calllint.receipt.v0 file
   gen-rule --host <h>   Emit the CallLint agent-safety rule for a host (CLAUDE.md, etc.)
   policy init        Write a default calllint.policy.json
   policy explain     Show the effective policy
@@ -92,6 +93,8 @@ SCAN OPTIONS
   --markdown         Emit Markdown for PR comments / GitHub Step Summary
   --html             Emit a self-contained HTML report
   --badge            Emit a shields.io endpoint badge JSON (SAFE/REVIEW/UNKNOWN/BLOCK)
+  --receipt          Also write a local calllint.receipt.v0 (offline reporting layer)
+  --receipt-out <f>  Receipt output path (default: calllint-receipt.json)
   --policy <file>    Use a policy file (default: built-in defaults)
   --stdin            Read config JSON from stdin
   --ci               Exit non-zero per policy (BLOCK=30, UNKNOWN=20, REVIEW=10 if enabled)
@@ -112,6 +115,7 @@ EXAMPLES
   calllint check ./mcp.json --json
   calllint scan .cursor/mcp.json --markdown
   calllint scan .cursor/mcp.json --badge > calllint-badge.json
+  calllint scan .cursor/mcp.json --receipt && calllint receipt verify calllint-receipt.json
   calllint verify ./mcp.json --ci
   calllint approve && calllint verify --approved --ci
   calllint explain filesystem
@@ -2978,6 +2982,147 @@ ${rule()}
   }
 }
 
+// ../../packages/core/src/receipt/createReceipt.ts
+import { randomBytes } from "node:crypto";
+function newReceiptId() {
+  const b64 = randomBytes(16).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  return `clrec_${b64}`;
+}
+function riskCounts(counts) {
+  return {
+    safe: counts.SAFE ?? 0,
+    review: counts.REVIEW ?? 0,
+    block: counts.BLOCK ?? 0,
+    unknown: counts.UNKNOWN ?? 0
+  };
+}
+function findingRefs(reports) {
+  const refs = [];
+  for (const report of reports) {
+    for (const f of report.findings ?? []) {
+      const path = f.evidence?.find((e) => typeof e.path === "string")?.path;
+      refs.push({
+        rule_id: f.id,
+        severity: f.severity,
+        ...path ? { evidence_path: path } : {}
+      });
+    }
+  }
+  return refs;
+}
+function createReceipt(input, now) {
+  const summary = input.scanReport;
+  const receipt = {
+    schema_version: "calllint.receipt.v0",
+    receipt_id: newReceiptId(),
+    created_at: now,
+    tool: { name: "calllint", version: input.toolVersion },
+    subject: input.subject,
+    verdict: summary.verdict,
+    hashes: {
+      input_hash: hashInput(input.inputForHash),
+      policy_hash: hashJson(input.effectivePolicyForHash),
+      report_hash: hashJson(input.scanReport),
+      ruleset_hash: hashJson(input.rulesetForHash)
+    },
+    risk_counts: riskCounts(summary.counts),
+    finding_refs: findingRefs(summary.reports ?? []),
+    trust_boundaries: {
+      executed_target: false,
+      network_used: input.networkUsed === true,
+      llm_in_verdict_path: false,
+      secret_values_read: false
+    },
+    ...input.corpus ? { corpus: input.corpus } : {}
+  };
+  return receipt;
+}
+function hashInput(value) {
+  return typeof value === "string" ? sha256(value) : hashJson(value);
+}
+
+// ../../packages/core/src/receipt/verifyReceipt.ts
+var SHA256_RE = /^sha256:[0-9a-f]{64}$/;
+var RECEIPT_ID_RE = /^clrec_[A-Za-z0-9_-]+$/;
+var VERDICTS = /* @__PURE__ */ new Set(["SAFE", "REVIEW", "BLOCK", "UNKNOWN"]);
+var HASH_KEYS = ["input_hash", "policy_hash", "report_hash", "ruleset_hash"];
+var COUNT_KEYS = ["safe", "review", "block", "unknown"];
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function verifyReceipt(input) {
+  const errors = [];
+  const push = (msg) => errors.push(msg);
+  if (!isObject(input)) {
+    return { valid: false, errors: ["receipt is not a JSON object"], signed: false };
+  }
+  const r = input;
+  if (r.schema_version !== "calllint.receipt.v0") {
+    push(`schema_version must be "calllint.receipt.v0" (got ${JSON.stringify(r.schema_version)})`);
+  }
+  if (typeof r.receipt_id !== "string" || !RECEIPT_ID_RE.test(r.receipt_id)) {
+    push("receipt_id must match /^clrec_[A-Za-z0-9_-]+$/");
+  }
+  if (typeof r.created_at !== "string" || Number.isNaN(Date.parse(r.created_at))) {
+    push("created_at must be an ISO-8601 timestamp");
+  }
+  if (!isObject(r.tool) || r.tool.name !== "calllint" || typeof r.tool.version !== "string") {
+    push('tool must be { name: "calllint", version: <string> }');
+  }
+  if (!isObject(r.subject) || r.subject.type !== "scan") {
+    push('subject.type must be "scan"');
+  }
+  if (typeof r.verdict !== "string" || !VERDICTS.has(r.verdict)) {
+    push("verdict must be one of SAFE | REVIEW | BLOCK | UNKNOWN");
+  }
+  if (!isObject(r.hashes)) {
+    push("hashes must be an object");
+  } else {
+    for (const key of HASH_KEYS) {
+      const val = r.hashes[key];
+      if (typeof val !== "string" || !SHA256_RE.test(val)) {
+        push(`hashes.${key} must match sha256:<64 lowercase hex>`);
+      }
+    }
+  }
+  if (!isObject(r.risk_counts)) {
+    push("risk_counts must be an object");
+  } else {
+    for (const key of COUNT_KEYS) {
+      const val = r.risk_counts[key];
+      if (typeof val !== "number" || !Number.isInteger(val) || val < 0) {
+        push(`risk_counts.${key} must be an integer >= 0`);
+      }
+    }
+  }
+  if (!Array.isArray(r.finding_refs)) {
+    push("finding_refs must be an array");
+  } else {
+    r.finding_refs.forEach((ref, i) => {
+      if (!isObject(ref) || typeof ref.rule_id !== "string" || typeof ref.severity !== "string") {
+        push(`finding_refs[${i}] must have string rule_id and severity`);
+      }
+    });
+  }
+  if (!isObject(r.trust_boundaries)) {
+    push("trust_boundaries must be an object");
+  } else {
+    const tb = r.trust_boundaries;
+    if (tb.executed_target !== false) push("trust_boundaries.executed_target must be false");
+    if (tb.llm_in_verdict_path !== false) push("trust_boundaries.llm_in_verdict_path must be false");
+    if (tb.secret_values_read !== false) push("trust_boundaries.secret_values_read must be false");
+    if (typeof tb.network_used !== "boolean") push("trust_boundaries.network_used must be a boolean");
+  }
+  const signed = isObject(r.signature);
+  if (signed) {
+    const sig = r.signature;
+    if (typeof sig.algorithm !== "string" || typeof sig.key_id !== "string" || typeof sig.value !== "string") {
+      push("signature, when present, must have string algorithm, key_id, and value");
+    }
+  }
+  return { valid: errors.length === 0, errors, signed };
+}
+
 // ../../packages/report-renderer/src/style.ts
 var DEFAULT_STYLE = { emoji: true };
 var NO_EMOJI_STYLE = { emoji: false };
@@ -3738,7 +3883,7 @@ function readDocumentSurfaces(dir) {
 }
 
 // src/commands/scan.ts
-import { readFileSync as readFileSync7 } from "node:fs";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync3 } from "node:fs";
 function scanCommand(args, deps) {
   if (flagBool(args.flags, "changed")) {
     return scanChangedCommand(args, deps);
@@ -3761,7 +3906,7 @@ function scanCommand(args, deps) {
   const { text, configPath } = input;
   return scanOneConfig(text, configPath, policy, args, deps);
 }
-function scanOneConfig(text, configPath, policy, args, deps) {
+function scanOneConfig(text, configPath, policy, args, deps, allowReceipt = true) {
   const surfaceDir = flagStr(args.flags, "surface-dir");
   const surfaces = surfaceDir ? readDocumentSurfaces(resolve2(deps.cwd, surfaceDir)) : void 0;
   let summary;
@@ -3790,9 +3935,38 @@ function scanOneConfig(text, configPath, policy, args, deps) {
     }
   }
   const stdout = renderSummary(summary, args);
+  if (allowReceipt && flagBool(args.flags, "receipt")) {
+    const err = writeReceiptFile(summary, text, configPath, policy, args, deps);
+    if (err) return { stdout: "", stderr: err, exitCode: EXIT.ERROR };
+  }
   const exitCode = flagBool(args.flags, "ci") ? exitCodeFor(summary, policy) : EXIT.OK;
   return { stdout, exitCode };
 }
+function writeReceiptFile(summary, text, configPath, policy, args, deps) {
+  const toolVersion = deps.toolVersion ?? "0.0.0-dev";
+  const receipt = createReceipt(
+    {
+      toolVersion,
+      subject: { type: "scan", target: configPath },
+      inputForHash: text,
+      effectivePolicyForHash: policy ?? { policy: "default" },
+      scanReport: summary,
+      rulesetForHash: { tool: "calllint", version: toolVersion },
+      networkUsed: flagBool(args.flags, "online")
+    },
+    deps.generatedAt
+  );
+  const outPath = resolve2(
+    deps.cwd,
+    flagStr(args.flags, "receipt-out") ?? "calllint-receipt.json"
+  );
+  try {
+    writeFileSync3(outPath, JSON.stringify(receipt, null, 2) + "\n", "utf8");
+  } catch (e) {
+    return `Could not write receipt to ${outPath}: ${e instanceof Error ? e.message : String(e)}`;
+  }
+  return void 0;
+}
 function renderSummary(summary, args) {
   const style = flagBool(args.flags, "no-emoji") ? NO_EMOJI_STYLE : DEFAULT_STYLE;
   if (flagBool(args.flags, "json")) return renderJson(summary);
@@ -3931,7 +4105,7 @@ function worstExit2(decisions) {
 }
 
 // src/commands/genRule.ts
-import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "node:fs";
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "node:fs";
 import { dirname as dirname3, join as join7, resolve as resolve3 } from "node:path";
 function isRuleHost(v) {
   return v !== void 0 && RULE_HOSTS.includes(v);
@@ -3978,7 +4152,7 @@ Run \`calllint gen-rule\` to list hosts.`,
 }
 function defaultWrite(path, content) {
   mkdirSync3(dirname3(path), { recursive: true });
-  writeFileSync3(path, content, "utf8");
+  writeFileSync4(path, content, "utf8");
 }
 
 // src/commands/diagnostics.ts
@@ -4061,7 +4235,7 @@ function explainCommand(args, deps) {
 }
 
 // src/commands/policy.ts
-import { existsSync as existsSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync6, writeFileSync as writeFileSync5 } from "node:fs";
 import { join as join9 } from "node:path";
 function policyCommand(args, deps) {
   const sub = args.positionals[0];
@@ -4074,7 +4248,7 @@ function policyCommand(args, deps) {
         exitCode: EXIT.USAGE
       };
     }
-    writeFileSync4(path, defaultPolicyJson(), "utf8");
+    writeFileSync5(path, defaultPolicyJson(), "utf8");
     return { stdout: `Wrote default policy to ${path}`, exitCode: EXIT.OK };
   }
   if (sub === "explain") {
@@ -4231,6 +4405,73 @@ function approveCommand(args, deps) {
   };
 }
 
+// src/commands/receipt.ts
+import { readFileSync as readFileSync8 } from "node:fs";
+import { resolve as resolve4 } from "node:path";
+function receiptCommand(args, deps) {
+  const sub = args.positionals[0];
+  if (sub !== "verify") {
+    return {
+      stdout: "",
+      stderr: "Usage: calllint receipt verify <receipt.json>",
+      exitCode: EXIT.USAGE
+    };
+  }
+  const file = args.positionals[1];
+  if (!file) {
+    return {
+      stdout: "",
+      stderr: "Usage: calllint receipt verify <receipt.json>",
+      exitCode: EXIT.USAGE
+    };
+  }
+  let raw;
+  try {
+    raw = readFileSync8(resolve4(deps.cwd, file), "utf8");
+  } catch (e) {
+    return {
+      stdout: "",
+      stderr: `Could not read receipt ${file}: ${e instanceof Error ? e.message : String(e)}`,
+      exitCode: EXIT.ERROR
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    const msg = `receipt is not valid JSON: ${e instanceof Error ? e.message : String(e)}`;
+    if (flagBool(args.flags, "json")) {
+      return {
+        stdout: JSON.stringify({ valid: false, errors: [msg], signed: false }, null, 2),
+        exitCode: 1
+      };
+    }
+    return { stdout: "", stderr: `CallLint receipt: invalid
+  - ${msg}`, exitCode: 1 };
+  }
+  const result = verifyReceipt(parsed);
+  if (flagBool(args.flags, "json")) {
+    return {
+      stdout: JSON.stringify(result, null, 2),
+      exitCode: result.valid ? EXIT.OK : 1
+    };
+  }
+  if (!result.valid) {
+    const lines = ["CallLint receipt: invalid", ...result.errors.map((e) => `  - ${e}`)];
+    return { stdout: "", stderr: lines.join("\n"), exitCode: 1 };
+  }
+  const r = parsed;
+  const signature = r.signature ? "present (shape-only, not cryptographically verified)" : "unsigned local receipt";
+  const stdout = [
+    "CallLint receipt: valid",
+    `receipt_id: ${r.receipt_id}`,
+    `schema: ${r.schema_version}`,
+    `verdict: ${r.verdict}`,
+    `signature: ${signature}`
+  ].join("\n");
+  return { stdout, exitCode: EXIT.OK };
+}
+
 // src/run.ts
 function run(argv, deps) {
   const args = parseArgs(argv);
@@ -4260,7 +4501,8 @@ function run(argv, deps) {
         generatedAt: deps.generatedAt,
         writeCacheFile: deps.writeCacheFile,
         online: deps.online,
-        getChangedFilesDiff: deps.getChangedFilesDiff
+        getChangedFilesDiff: deps.getChangedFilesDiff,
+        toolVersion: deps.toolVersion
       });
     case "diagnostics":
       return diagnosticsCommand(args, {
@@ -4296,6 +4538,8 @@ function run(argv, deps) {
       });
     case "explain":
       return explainCommand(args, { cwd: deps.cwd });
+    case "receipt":
+      return receiptCommand(args, { cwd: deps.cwd });
     case "gen-rule":
       return genRuleCommand(args, { cwd: deps.cwd });
     case "policy":
@@ -4350,15 +4594,39 @@ async function fetchNpmFacts(packageSpec, fetchJson) {
     (k) => typeof scripts[k] === "string" && scripts[k].length > 0
   );
   const deprecated = typeof versionDoc.deprecated === "string" ? versionDoc.deprecated : void 0;
+  const description = typeof versionDoc.description === "string" ? versionDoc.description : void 0;
+  const readme = typeof doc.readme === "string" ? doc.readme : void 0;
   return {
     name,
     versionExists: true,
     installScripts,
     deprecated,
     latestVersion,
-    resolvedVersion
+    resolvedVersion,
+    description,
+    readme
   };
 }
+function surfacesFromNpmFacts(facts) {
+  const surfaces = [];
+  if (typeof facts.description === "string" && facts.description.length > 0) {
+    surfaces.push({
+      path: `registry:${facts.name}#description`,
+      kind: "registry-description",
+      text: facts.description,
+      truncated: false
+    });
+  }
+  if (typeof facts.readme === "string" && facts.readme.length > 0) {
+    surfaces.push({
+      path: `registry:${facts.name}#readme`,
+      kind: "registry-readme",
+      text: facts.readme,
+      truncated: false
+    });
+  }
+  return surfaces;
+}
 function findingsFromNpmFacts(facts, fetchedAt) {
   const findings = [];
   const stamp = (f) => ({ ...f, source: "online", fetchedAt });
@@ -4416,6 +4684,9 @@ function findingsFromNpmFacts(facts, fetchedAt) {
       fix: "Migrate to the maintained successor or a supported version."
     }));
   }
+  for (const f of analyzeDocumentSurfaces(surfacesFromNpmFacts(facts))) {
+    findings.push(stamp(f));
+  }
   return findings;
 }
 async function enrichNpmPackage(packageSpec, fetchJson, fetchedAt) {
@@ -4541,10 +4812,24 @@ async function breathe(argv, deps = {}) {
   }
 }
 
+// src/version.ts
+import { readFileSync as readFileSync9 } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname as dirname4, join as join11 } from "node:path";
+function resolveToolVersion() {
+  try {
+    const pkgPath = join11(dirname4(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(readFileSync9(pkgPath, "utf8"));
+    return typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // src/index.ts
 function readStdin() {
   try {
-    return readFileSync8(0, "utf8");
+    return readFileSync10(0, "utf8");
   } catch {
     return "";
   }
@@ -4593,6 +4878,7 @@ async function main() {
     now,
     generatedAt,
     online,
+    toolVersion: resolveToolVersion(),
     getChangedFilesDiff: () => gitChangedFiles(process.cwd())
   });
   if (result.stdout) process.stdout.write(result.stdout + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calllint",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Evidence-backed security verdicts for MCP servers and agent tools. Lint agent tool-call risk before tools run — SAFE / REVIEW / BLOCK / UNKNOWN, with evidence. Never executes the server it judges.",
   "keywords": [
     "mcp",