candor-ts 0.5.5 → 0.5.7

package/mcp.mjs

@@ -45,6 +45,20 @@ function resolvePrefix(args) {
   if (!hasReport(p)) throw new Error(`no report at \`${p}\` (.json or .<crate>.scan.json) — run a candor scan first`);
   return p;
 }
+// Truncate a caller-supplied value echoed back in an error (a multi-MB `fn` would otherwise be reflected
+// verbatim — token/memory amplification over the agent transport, the opposite of the list-cap thrift).
+const clip = (s, n = 120) => { s = String(s); return s.length > n ? s.slice(0, n) + "…" : s; };
+// Read a caller-supplied policy file CONFINED to the report's directory tree. The MCP surface is
+// report-query-only (spec §7.12); an arbitrary `policy` path (/etc/passwd, ~/.aws/credentials) whose
+// parsed deny-rule scopes are reflected back in violations[].rule is an arbitrary-file-read exfiltration
+// channel — tie the policy to the project it gates.
+function confinedPolicyRead(policyPath, prefix) {
+  const root = nodePath.resolve(nodePath.dirname(prefix));
+  const abs = nodePath.resolve(policyPath);
+  if (abs !== root && !abs.startsWith(root + nodePath.sep))
+    throw new Error(`policy must be within the report's directory (${root}) — refusing to read \`${clip(policyPath)}\``);
+  return fs.readFileSync(abs, "utf8");
+}
 
 // ---- the tools: name -> {description, schema, run} ------------------------------------------------
 const reportArg = { report: { type: "string", description: "report prefix (optional; defaults to $CANDOR_REPORT)" } };
@@ -110,9 +124,9 @@ const TOOLS = {
     description: "Hypothetically add `effect` to `fn` and report the blast radius; with `policy`, also the deny-rule violations it would cause. Pre-edit gate check.",
     schema: { type: "object", properties: { fn: { type: "string" }, effect: { type: "string" }, policy: { type: "string", description: "path to a CANDOR_POLICY file (optional)" }, ...reportArg }, required: ["fn", "effect"] },
     run: (a, p) => {
-      const pol = a.policy && fs.existsSync(a.policy) ? parsePolicy(fs.readFileSync(a.policy, "utf8")) : null;
+      const pol = a.policy && fs.existsSync(a.policy) ? parsePolicy(confinedPolicyRead(a.policy, p)) : null;
       const r = Q.whatif(Q.loadCallgraph(p), a.fn, a.effect, pol, scopeMatches);
-      if (r === null) throw new Error(`no function matching \`${a.fn}\` in the call graph`);
+      if (r === null) throw new Error(`no function matching \`${clip(a.fn)}\` in the call graph`);
       return r;
     },
   },
@@ -156,7 +170,7 @@ function handle(msg) {
       if (args.fn !== undefined) {
         const names = [...new Set([...Object.keys(Q.loadCallgraph(prefix)), ...Q.loadReport(prefix).map((e) => e.fn)])];
         if (Q.matches(names, args.fn).length === 0)
-          return result(id, { content: [{ type: "text", text: `candor: no function matching \`${args.fn}\` in this report` }], isError: true });
+          return result(id, { content: [{ type: "text", text: `candor: no function matching \`${clip(args.fn)}\` in this report` }], isError: true });
       }
       const out = t.run(args, prefix);
       // Minified, not pretty-printed: the consumer is an AGENT (it parses the JSON), so the indentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "candor-ts",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "candor for TypeScript — per-function side effects, transitively, with a policy gate (candor-spec 0.5)",
   "type": "module",
   "dependencies": {

package/scan-core.mjs

@@ -40,6 +40,14 @@ export const KAPPA_RULES = [
   // these three named validators are freed; every genuine verb (connect/createConnection/createServer…)
   // stays Net (the matcher excludes ONLY new + the three validators, nothing else).
   [/^(node:)?(net|dgram|tls|http2?|https)$/, /^(?!(new|isIP|isIPv4|isIPv6)$)/, "Net"],
+  // node:dns — name resolution is NETWORK I/O (lookup/lookupService hit the OS resolver; resolve*/
+  // reverse query DNS servers directly). Was unclassified, so a `dns.resolve(...)` read silently pure.
+  // Same construction-and-pure-accessor carve-out as the net cluster: `new dns.Resolver()` ("new") is
+  // inert, and the SERVER-CONFIG accessors getServers/setServers/get|setDefaultResultOrder touch no
+  // network (in-process config) — classifying them Net would FABRICATE the cardinal sin. Every genuine
+  // resolver verb (lookup/resolve4/resolveMx/reverse/…) stays Net. Covers node:dns/promises too.
+  [/^(node:)?dns(\/promises)?$/,
+   /^(?!(new|getServers|setServers|getDefaultResultOrder|setDefaultResultOrder)$)/, "Net"],
   [/^(node:)?child_process$/, null, "Exec"],
   [/^(node:)?sqlite$/, null, "Db"],
   // the curated npm tier
@@ -52,7 +60,11 @@ export const KAPPA_RULES = [
   // entropy: node:crypto's random surface + the password-hashing libs (salted -> Rand). Found by
   // the CTA dogfood on a Nest app: argon2.hash came out SILENTLY PURE (the curated-kappa caveat
   // landing on exactly the call a security review cares about).
-  [/^(node:)?crypto$/, /^random/, "Rand"],
+  [/^(node:)?crypto$/, /^(random|getRandomValues)/, "Rand"],
+  // node:os identity reads — userInfo (the OS user record) and hostname (the machine name) are
+  // environment/host reads (Env), like System.getenv's host-identity cousins. The rest of node:os
+  // (platform/arch/cpus/totalmem/…) is inert host introspection, left pure.
+  [/^(node:)?os$/, /^(userInfo|hostname)$/, "Env"],
   [/^(argon2|bcrypt|bcryptjs)$/, null, "Rand"],
   // The ORM tier — VERB-PRECISE (the CLASSIFIER discipline: tag the execution boundary, not
   // builders; `createQueryBuilder` is pure, its `getMany`/`execute` is the I/O). Found on the

package/scan.mjs

@@ -242,7 +242,12 @@ const sources = program.getSourceFiles().filter((f) => projectFiles.has(path.res
 function declModule(decl) {
   const f = path.resolve(decl.getSourceFile().fileName);
   if (projectFiles.has(f)) return "<local>";
-  let m = f.match(/@types\/node\/(\w+?)\.d\.ts$/);
+  // `(.+?)` not `(\w+?)`: a SUBPATH typing (`@types/node/fs/promises.d.ts`, `dns/promises.d.ts`) carries
+  // a `/` that `\w` can't cross, so the module collapsed to `@types/node` (via the node_modules branch
+  // below) and the `fs(\/promises)?` / `dns(\/promises)?` κ rules — written to cover exactly these — could
+  // never fire (`fs/promises` is the dominant modern Node FS API: a silent-pure under-report). Keep the
+  // slash so the module reads `fs/promises`, which the rules match.
+  let m = f.match(/@types\/node\/(.+?)\.d\.ts$/);
   if (m) return m[1];
   if (/typescript\/lib\/lib\..*\.d\.ts$/.test(f)) return "<es-lib>";
   m = f.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)\//);
@@ -577,8 +582,10 @@ function realDecl(sym) {
 // when the accessor's declaration lives in a project file (a UNIT we minted; edge to it). A resolved
 // accessor we CAN'T see (external/typed-only declaration) returns local:false so the caller follows
 // the existing Unknown/curated-κ posture — never silent-pure for a resolved-but-unseen accessor.
-function accessorAt(propNode, kind /* "get" | "set" */) {
-  const sym = checker.getSymbolAtLocation(propNode.name ?? propNode);
+// A property SYMBOL → its accessor declaration of the wanted kind (or null). `local` is true when that
+// declaration lives in a project file (a unit we minted; edge to it). Shared by every property-read
+// shape: dot access, element access, and object destructuring.
+function accessorFromSym(sym, kind /* "get" | "set" */) {
   if (!sym) return null;
   const want = kind === "get" ? ts.isGetAccessorDeclaration : ts.isSetAccessorDeclaration;
   // A symbol is an accessor only if its declarations include an accessor of the wanted kind.
@@ -586,10 +593,59 @@ function accessorAt(propNode, kind /* "get" | "set" */) {
   if (!decl) return null;
   return { decl, local: projectFiles.has(path.resolve(decl.getSourceFile().fileName)) };
 }
+function accessorAt(propNode, kind /* "get" | "set" */) {
+  let sym;
+  if (ts.isElementAccessExpression(propNode)) {
+    // `c["prop"]` carries no `.name`; resolve the LITERAL key as a property on the receiver's type.
+    // A dynamic key (`c[k]`) can't be pinned to one property — leave it unresolved (the existing
+    // dynamic-access posture stands; resolving it would guess, never fabricate here).
+    const arg = propNode.argumentExpression;
+    sym = arg && ts.isStringLiteralLike(arg)
+      ? checker.getTypeAtLocation(propNode.expression)?.getProperty?.(arg.text)
+      : null;
+  } else {
+    sym = checker.getSymbolAtLocation(propNode.name ?? propNode);
+  }
+  return accessorFromSym(sym, kind);
+}
+// Record a resolved accessor HIT (read or write) as an edge from `owner`: into the accessor UNIT when
+// it's a local declaration we minted; otherwise Unknown (a resolved-but-unseen accessor body — never
+// silent-pure, SPEC §4). `label` tags the §-why disclosure.
+function recordAccessorHit(owner, hit, label) {
+  const rec = fns.get(owner);
+  const t = nodeName.get(hit.decl);
+  if (hit.local && t) {
+    rec.edges.add(t); // (EDGE) into the accessor unit — effects propagate
+  } else {
+    rec.direct.add("Unknown");
+    rec.why.add(`accessor:${label}`);
+  }
+}
+
+// Object PROPERTY-ENUMERATION (`{...obj}`, `const {...rest} = obj`, `Object.assign(t, obj)`): copying an
+// object's own enumerable props INVOKES each source getter — the whole-object analog of `obj.prop`,
+// invisible to the property-access arm (no PropertyAccess node per key). Edge `owner` to every LOCAL
+// getter on the source type. A rest/spread can't name one key, so ALL getters are enumerated (sound
+// over-approximation); a plain prop resolves to no accessor and adds nothing (no fabrication).
+function enumerateGetters(owner, type) {
+  if (!owner || !type || !type.getProperties) return;
+  for (const p of type.getProperties()) {
+    const hit = accessorFromSym(p, "get");
+    if (hit) recordAccessorHit(owner, hit, p.getName());
+  }
+}
 
 // nearest enclosing analyzed function (closures attribute to it — SEMANTICS §2)
 function enclosing(node) {
   for (let p = node; p; p = p.parent) {
+    // A call/effect lexically inside a DECORATOR (`@factory(arg)`) runs at class-DEFINITION time, NOT in
+    // the decorated declaration's body. The parent chain of a decorator's expression is
+    // CallExpression → Decorator → MethodDeclaration/ClassDeclaration/Parameter, so `enclosing` otherwise
+    // lands on the decorated unit and FABRICATES the factory's effects onto that method/class/param and
+    // every transitive caller (a cardinal sin — @Entity/@Injectable factories that touch I/O would
+    // poison every decorated handler). Stop at the Decorator: the factory's own effects live in its own
+    // function unit; the application site attributes to nothing (load-time, like a no-arg decorator).
+    if (ts.isDecorator(p)) return null;
     const n = nodeName.get(p);
     if (n) return n;
   }
@@ -697,6 +753,22 @@ function visitCalls(node) {
         }
       } else {
         const mod = declModule(decl);
+        // A LOCAL function/method passed BY REFERENCE to a NON-LOCAL (opaque) callee — `xs.map(loadFree)`,
+        // `arr.forEach(this.m)`, `setTimeout(handler)`, `external(cb)` — may be INVOKED by that callee, so
+        // its effects are reachable here. The precise callback-flow below only resolves a LOCAL callee's
+        // params; a non-local HOF dropped the reference entirely (a silent-pure hole — confirmed for
+        // `map`/`forEach`/`reduce`). Edge to the referenced unit: the sound over-approximation, matching
+        // the Rust engine's fn-as-value edge. An inline closure is already charged lexically; a non-fn
+        // argument resolves to no minted unit (`nodeName` miss) and adds nothing — no fabrication. Gated
+        // on a non-local callee so a local callee that merely STORES (never invokes) keeps its precision.
+        if (mod !== "<local>") {
+          for (const a of node.arguments ?? []) {
+            if (!ts.isIdentifier(a) && !ts.isPropertyAccessExpression(a)) continue;
+            const d2 = realDecl(checker.getSymbolAtLocation(a));
+            const t = d2 && nodeName.get(d2);
+            if (t) rec.edges.add(t);
+          }
+        }
         if (mod === "<local>") {
           const targetName = nodeName.get(decl);
           if (targetName) {
@@ -971,6 +1043,34 @@ function visitCalls(node) {
     const owner = enclosing(node);
     if (owner) fns.get(owner).direct.add("Env");
   }
+  // Runtime GLOBALS reached as CALLS with no import for the κ resolver to classify: `process.hrtime()`/
+  // `.hrtime.bigint()` is a monotonic clock read (Clock); `process.send(...)` is the child↔parent IPC
+  // channel (Ipc); the global `fetch(...)` is the standard modern HTTP client (Net). Matched on the
+  // callee — `process.*` by exact text (mirroring the process.env match), `fetch` by identifier whose
+  // symbol is NOT a local declaration (so a project's own `fetch` shadow never fabricates Net).
+  if (ts.isCallExpression(node)) {
+    const callee = node.expression;
+    const ctext = callee.getText().replace(/\s+/g, "");
+    let geff = null;
+    if (ctext === "process.hrtime" || ctext === "process.hrtime.bigint") geff = "Clock";
+    else if (ctext === "process.send") geff = "Ipc";
+    else if (ts.isIdentifier(callee) && callee.text === "fetch"
+             && !(checker.getSymbolAtLocation(callee)?.declarations ?? [])
+                  .some((d) => projectFiles.has(path.resolve(d.getSourceFile().fileName))))
+      geff = "Net";
+    if (geff) {
+      const owner = enclosing(node);
+      if (owner) fns.get(owner).direct.add(geff);
+    }
+    // Object.assign(target, ...sources) copies each SOURCE's own enumerable props → invokes their
+    // getters (the object-spread twin). Enumerate the sources' local getters.
+    if (callee.getText().replace(/\s+/g, "") === "Object.assign") {
+      const owner = enclosing(node);
+      for (const src of (node.arguments ?? []).slice(1)) {
+        enumerateGetters(owner, checker.getTypeAtLocation(src));
+      }
+    }
+  }
   // GET/SET ACCESSOR access (the silent-pure-accessor fix): a property read that resolves to a
   // getter, or a property assignment whose target resolves to a setter, is effectively a call into
   // the accessor body — model it as a call EDGE so the accessor's effects propagate (like a method
@@ -987,16 +1087,31 @@ function visitCalls(node) {
     if (hit) {
       const owner = enclosing(node);
       if (owner) {
-        const rec = fns.get(owner);
-        const t = nodeName.get(hit.decl);
-        if (hit.local && t) {
-          rec.edges.add(t); // (EDGE) into the accessor unit — effects propagate
-        } else {
-          // resolved to an accessor whose body we can't see → Unknown, never silent-pure (SPEC §4)
-          rec.direct.add("Unknown");
-          const an = hit.decl.parent?.name?.getText?.() ?? "?";
-          rec.why.add(`accessor:${an}.${node.name?.getText?.() ?? node.argumentExpression?.getText?.() ?? "?"}`);
-        }
+        const an = hit.decl.parent?.name?.getText?.() ?? "?";
+        const pn = node.name?.getText?.() ?? node.argumentExpression?.getText?.() ?? "?";
+        recordAccessorHit(owner, hit, `${an}.${pn}`);
+      }
+    }
+  }
+  // OBJECT-DESTRUCTURING getter read (`const { prop } = obj`): each bound property is a READ that may
+  // resolve to a getter whose body does I/O — the binding-pattern analog of `obj.prop`, invisible to
+  // the property-access arm above because there is no PropertyAccess/ElementAccess node. (ARRAY
+  // destructuring is ITERATION, handled below; object destructuring copies named own/inherited props,
+  // invoking each getter.) Resolve every bound key as a property on the initializer's type; a rest
+  // element / computed key can't be pinned to one accessor, so it's skipped (no fabrication).
+  if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
+    const owner = enclosing(node);
+    if (owner) {
+      const recvType = checker.getTypeAtLocation(node.initializer);
+      for (const el of node.name.elements) {
+        if (el.dotDotDotToken) { enumerateGetters(owner, recvType); continue; } // `...rest` copies every
+        // remaining prop → invokes every (remaining) getter; enumerate all (the bound ones double-handle).
+        const key = el.propertyName ?? el.name; // `{prop}` shorthand, or `{prop: alias}`
+        const keyName = ts.isIdentifier(key) ? key.text
+          : ts.isStringLiteralLike(key) ? key.text : null;
+        if (keyName === null) continue; // computed key (`{[k]: v}`) — unresolvable to one property
+        const hit = accessorFromSym(recvType?.getProperty?.(keyName), "get");
+        if (hit) recordAccessorHit(owner, hit, keyName);
       }
     }
   }
@@ -1008,9 +1123,12 @@ function visitCalls(node) {
     let iterExpr = null, iterAsync = false;
     if (ts.isForOfStatement(node)) { iterExpr = node.expression; iterAsync = !!node.awaitModifier; }
     else if (ts.isSpreadElement(node)) iterExpr = node.expression; // [...bag] / f(...bag)
-    else if (ts.isSpreadAssignment(node)) iterExpr = node.expression; // {...bag} — object spread is NOT
-    // iteration (it copies own enumerable props, no [Symbol.iterator]); wellKnownSymbolMember simply
-    // finds none and edges nothing. Listed for clarity; the resolution self-guards.
+    else if (ts.isSpreadAssignment(node)) {
+      iterExpr = node.expression; // {...bag} — object spread is NOT iteration (copies own enumerable
+      // props, no [Symbol.iterator]); wellKnownSymbolMember finds none and edges nothing for iteration.
+      // But the copy DOES invoke each source getter — enumerate them (the silent-pure object-spread hole).
+      enumerateGetters(enclosing(node), checker.getTypeAtLocation(node.expression));
+    }
     else if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name) && node.initializer)
       iterExpr = node.initializer; // const [a] = bag
     else if (ts.isCallExpression(node) && node.arguments?.[0]