candor-ts 0.4.0

package/policy.mjs

@@ -0,0 +1,140 @@
+/**
+ * The §6.2 policy grammar + gate semantics, shared by query.mjs (whatif/parsepolicy) and scan.mjs
+ * (the standing --policy gate). One parser, one matcher set — the same single-source rule the Rust
+ * engines follow (candor-classify::policy), so the TS gate can never disagree with its own whatif.
+ */
+
+export const EFFECTS = ["Net", "Fs", "Db", "Exec", "Env", "Clock", "Ipc", "Log", "Rand", "Clipboard"];
+const ALLOW_EFFECTS = new Set(["Net", "Exec", "Fs", "Db"]); // the four literal surfaces
+
+export function parsePolicy(text) {
+  const deny = [], allow = [], forbid = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.split("#")[0].trim();
+    if (!line) continue;
+    const t = line.split(/\s+/);
+    const warn = (why) => console.error(`candor: ignoring policy rule (${why}): ${line}`);
+    if (t[0] === "deny") {
+      const effects = [];
+      let scope = "";
+      for (const tok of t.slice(1)) {
+        if (EFFECTS.includes(tok) || tok === "Unknown") effects.push(tok);
+        else { scope = tok; break; }
+      }
+      if (effects.length === 0) { warn("deny names no known effect"); continue; }
+      deny.push({ effects: effects.sort(), scope, raw: line });
+    } else if (t[0] === "pure") {
+      deny.push({ effects: [], scope: t[1] ?? "", raw: line });
+    } else if (t[0] === "allow") {
+      if (t.length < 3) { warn("allow names no values"); continue; }
+      if (!ALLOW_EFFECTS.has(t[1])) { warn("allow supports only Net hosts / Exec commands / Fs paths / Db tables"); continue; }
+      let scope = "", vi = 2;
+      if (t[2] === "in") { scope = t[3] ?? ""; vi = 4; }
+      const values = t.slice(vi);
+      if (values.length === 0) { warn("allow names no values"); continue; }
+      allow.push({ effect: t[1], scope, values: values.sort(), raw: line });
+    } else if (t[0] === "forbid") {
+      // Token-wise like the Rust/JVM parsers: the arrow must be its own whitespace-separated token
+      // (`a->b` glued is malformed), and tokens past `b` are ignored. A regex here once accepted and
+      // rejected DIFFERENT lines than the other engines — the one thing a shared gate must not do.
+      const [a, arrow, b] = [t[1] ?? "", t[2] ?? "", t[3] ?? ""];
+      if (!a || arrow !== "->" || !b) { warn("malformed forbid (want `forbid <scope> -> <scope>`)"); continue; }
+      forbid.push({ from: a, to: b, raw: line });
+    } else {
+      warn("unknown rule kind");
+    }
+  }
+  return { deny, allow, forbid };
+}
+
+/** §6.2 scope match: by NAME SEGMENT over ".", last segment a prefix. */
+export function scopeMatches(name, scope) {
+  const segs = name.split(".");
+  const parts = scope.split(".");
+  if (parts.length === 0 || parts.length > segs.length) return false;
+  const last = parts[parts.length - 1], init = parts.slice(0, -1);
+  outer: for (let i = 0; i + parts.length <= segs.length; i++) {
+    for (let k = 0; k < init.length; k++) if (segs[i + k] !== init[k]) continue outer;
+    if (segs[i + parts.length - 1].startsWith(last)) return true;
+  }
+  return false;
+}
+
+// ---- the effect-specific literal matchers (§6.2), mirroring the Rust/JVM semantics ---------------
+export function hostPart(h) {
+  if (h.startsWith("[")) return h.slice(1).split("]")[0];           // [ipv6][:port]
+  if ((h.match(/:/g) ?? []).length > 1) return h;                   // bare ipv6 — no port to strip
+  return h.split(":")[0];
+}
+export function cmdBase(c) {
+  const first = c.trim().split(/\s+/)[0];
+  return first.split(/[/\\]/).pop();
+}
+export function pathCovered(a, r) {
+  const norm = (s) => s.split(/[/\\]/).filter((c) => c && c !== ".");
+  if (norm(r).includes("..")) return false;
+  const abs = (s) => s.startsWith("/") || s.startsWith("\\");
+  if (abs(a) !== abs(r)) return false;
+  const ac = norm(a), rc = norm(r);
+  return ac.length <= rc.length && ac.every((x, i) => x === rc[i]);
+}
+export function tableCovered(a, r) {
+  a = a.toLowerCase(); r = r.toLowerCase();
+  if (a.endsWith(".*")) return r.startsWith(a.slice(0, -1));        // "schema." prefix
+  return a === r;
+}
+export function literalAllowed(effect, reached, values) {
+  switch (effect) {
+    case "Net":  return values.some((a) => hostPart(a) === hostPart(reached));
+    case "Exec": return values.some((a) => cmdBase(a) === cmdBase(reached));
+    case "Fs":   return values.some((a) => pathCovered(a, reached));
+    case "Db":   return values.some((a) => tableCovered(a, reached));
+    default:     return values.includes(reached);
+  }
+}
+
+/**
+ * The standing gate: evaluate a parsed policy over a report + callgraph (AS-EFF-006 deny/pure over
+ * transitive inferred; AS-EFF-008 allowlists over the transitive literal surfaces, the no-visible-
+ * literal case flagged as uncertifiable; AS-EFF-009 forbid by reachability). One line per violation.
+ */
+export function evaluatePolicy(pol, functions, callgraph) {
+  const out = [];
+  const surfaces = { Net: "hosts", Exec: "cmds", Fs: "paths", Db: "tables" };
+  for (const f of functions) {
+    for (const r of pol.deny) {
+      if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
+      const hits = r.effects.length === 0 ? f.inferred : f.inferred.filter((e) => r.effects.includes(e));
+      if (hits.length) out.push(`[AS-EFF-006] \`${f.fn}\` performs { ${hits.join(", ")} }, forbidden by policy: \`${r.raw}\``);
+    }
+    for (const r of pol.allow) {
+      if (r.scope && !scopeMatches(f.fn, r.scope)) continue;
+      if (!f.inferred.includes(r.effect)) continue;
+      const reached = f[surfaces[r.effect]] ?? [];
+      if (reached.length === 0) {
+        out.push(`[AS-EFF-008] \`${f.fn}\` performs ${r.effect} with no visible literal — the surface cannot be certified: \`${r.raw}\``);
+      } else {
+        const bad = reached.filter((v) => !literalAllowed(r.effect, v, r.values));
+        if (bad.length) out.push(`[AS-EFF-008] \`${f.fn}\` reaches { ${bad.join(", ")} } outside the allowlist: \`${r.raw}\``);
+      }
+    }
+  }
+  // AS-EFF-009: forbid A -> B by reachability over the callgraph.
+  for (const r of pol.forbid) {
+    for (const fn of Object.keys(callgraph)) {
+      if (!scopeMatches(fn, r.from)) continue;
+      const seen = new Set([fn]), queue = [fn];
+      let hit = null;
+      while (queue.length && !hit) {
+        for (const c of callgraph[queue.pop()] ?? []) {
+          if (seen.has(c)) continue;
+          seen.add(c);
+          if (scopeMatches(c, r.to)) { hit = c; break; }
+          queue.push(c);
+        }
+      }
+      if (hit) out.push(`[AS-EFF-009] \`${fn}\` reaches into a forbidden layer (via \`${hit}\`), violating policy: \`${r.raw}\``);
+    }
+  }
+  return out;
+}

package/query.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * candor-ts queries — the SPEC §3.1 read-only query surface + the §6.2 policy grammar, over the
+ * report + callgraph sidecar that scan.mjs writes. Same command names, same JSON shapes, same match
+ * ladder as the Rust and JVM engines (the cross-impl conformance suite diffs all three).
+ *
+ * Provenance note (honesty): the ORIGINAL scan.mjs was written from the spec documents alone — the
+ * clean-room derivability proof. This file was added later, implemented from the same spec text,
+ * but its author had by then read the reference engines; the ongoing guarantee for it is the
+ * conformance differential, not clean-room provenance.
+ *
+ *   node query.mjs parsepolicy <file>
+ *   node query.mjs show     <prefix> <query>  <0|1>
+ *   node query.mjs where    <prefix> <Effect> <0|1>
+ *   node query.mjs callers  <prefix> <query>  <0|1>
+ *   node query.mjs map      <prefix>          <0|1>
+ *   node query.mjs whatif   <prefix> <fn> <Effect> [policy-file] [0|1]
+ */
+import fs from "node:fs";
+
+import { parsePolicy, scopeMatches } from "./policy.mjs";
+
+// ---- the §3.1 match ladder: exact > segment-suffix > substring ------------------------------------
+function matchTier(name, q) {
+  if (name === q) return 3;
+  if (name.endsWith(q) && /[.$]$/.test(name.slice(0, name.length - q.length))) return 2;
+  if (name.includes(q)) return 1;
+  return 0;
+}
+function matches(names, q) {
+  const best = Math.max(0, ...names.map((n) => matchTier(n, q)));
+  return best === 0 ? [] : names.filter((n) => matchTier(n, q) >= best);
+}
+
+function loadReport(prefix) {
+  const d = JSON.parse(fs.readFileSync(`${prefix}.json`, "utf8"));
+  return d.functions ?? d;
+}
+function loadCallgraph(prefix) {
+  return JSON.parse(fs.readFileSync(`${prefix}.callgraph.json`, "utf8"));
+}
+const emit = (v) => console.log(JSON.stringify(v, null, 1));
+
+const [, , cmd, ...args] = process.argv;
+switch (cmd) {
+  case "parsepolicy": {
+    emit(parsePolicy(fs.readFileSync(args[0], "utf8")));
+    break;
+  }
+  case "show": {
+    const [prefix, q] = args;
+    const fns = loadReport(prefix);
+    const hit = new Set(matches(fns.map((e) => e.fn), q));
+    const out = fns.filter((e) => hit.has(e.fn)).map((e) => {
+      const o = { fn: e.fn, inferred: e.inferred, direct: e.direct };
+      if (e.fs?.length) o.fs = e.fs;
+      if (e.hosts?.length) o.hosts = e.hosts;
+      if (e.tables?.length) o.tables = e.tables;
+      o.unresolved = e.unresolved;
+      return o;
+    });
+    emit(out);
+    break;
+  }
+  case "where": {
+    const [prefix, eff] = args;
+    const fns = loadReport(prefix);
+    emit({
+      effect: eff,
+      directly: fns.filter((e) => e.direct.includes(eff)).map((e) => e.fn).sort(),
+      inherited: fns.filter((e) => e.inferred.includes(eff) && !e.direct.includes(eff)).map((e) => e.fn).sort(),
+    });
+    break;
+  }
+  case "callers": {
+    const [prefix, q] = args;
+    const cg = loadCallgraph(prefix);
+    const names = Object.keys(cg);
+    const targets = matches(names, q);
+    const rev = new Map();
+    for (const [caller, callees] of Object.entries(cg))
+      for (const c of callees) (rev.get(c) ?? rev.set(c, []).get(c)).push(caller);
+    const direct = new Set(), transitive = new Set();
+    const queue = [...targets];
+    for (const t of targets) for (const c of rev.get(t) ?? []) direct.add(c);
+    while (queue.length) {
+      const n = queue.pop();
+      for (const c of rev.get(n) ?? []) if (!transitive.has(c) && !targets.includes(c)) { transitive.add(c); queue.push(c); }
+    }
+    emit({ of: targets, direct: [...direct].sort(), transitive: [...transitive].sort() });
+    break;
+  }
+  case "map": {
+    const [prefix] = args;
+    const fns = loadReport(prefix);
+    const mods = {};
+    for (const e of fns) {
+      const mod = e.fn.includes(".") ? e.fn.split(".").slice(0, -1).join(".") : "(root)";
+      const m = (mods[mod] ??= { effects: new Set(), functions: 0 });
+      for (const x of e.inferred) m.effects.add(x);
+      m.functions += 1;
+    }
+    emit(Object.fromEntries(Object.entries(mods).sort()
+      .map(([k, v]) => [k, { effects: [...v.effects].sort(), functions: v.functions }])));
+    break;
+  }
+  case "diff": {
+    // per-function effect delta vs a baseline: {changes: [{fn, gained, lost}]} — the envelope shape
+    // the conformance suite pins (diff-vs-self must be {changes: []}).
+    const [curPrefix, basePrefix] = args;
+    const cur = new Map(loadReport(curPrefix).map((e) => [e.fn, new Set(e.inferred)]));
+    const base = new Map(loadReport(basePrefix).map((e) => [e.fn, new Set(e.inferred)]));
+    const changes = [];
+    for (const fn of new Set([...cur.keys(), ...base.keys()])) {
+      const c = cur.get(fn) ?? new Set(), b = base.get(fn) ?? new Set();
+      const gained = [...c].filter((e) => !b.has(e)).sort();
+      const lost = [...b].filter((e) => !c.has(e)).sort();
+      if (gained.length || lost.length) changes.push({ fn, gained, lost });
+    }
+    changes.sort((a, b) => a.fn.localeCompare(b.fn));
+    emit({ changes });
+    process.exit(changes.some((c) => c.gained.length) ? 1 : 0);
+  }
+  case "reachable": {
+    // what the app DOES at runtime: effects unioned over the entry points (SPEC §3.1; same JSON
+    // shape as the Rust engine: {entryPoints, effects: {Eff: {count, via}}}).
+    const [prefix] = args;
+    const fns = loadReport(prefix);
+    const roots = fns.filter((e) => e.entryPoint);
+    const byEff = {};
+    for (const e of roots) for (const x of e.inferred) (byEff[x] ??= []).push(e.fn);
+    emit({ entryPoints: roots.length,
+           effects: Object.fromEntries(Object.entries(byEff).sort()
+             .map(([k, v]) => [k, { count: v.length, via: v.sort() }])) });
+    break;
+  }
+  case "whatif": {
+    const [prefix, target, eff, maybePolicy] = args;
+    const cg = loadCallgraph(prefix);
+    const names = Object.keys(cg);
+    const targets = matches(names, target);
+    if (targets.length === 0) {
+      console.error(`candor: no function matching \`${target}\` in the call graph`);
+      process.exit(2);
+    }
+    const rev = new Map();
+    for (const [caller, callees] of Object.entries(cg))
+      for (const c of callees) (rev.get(c) ?? rev.set(c, []).get(c)).push(caller);
+    const affected = new Set(targets);
+    const queue = [...targets];
+    while (queue.length) {
+      const n = queue.pop();
+      for (const c of rev.get(n) ?? []) if (!affected.has(c)) { affected.add(c); queue.push(c); }
+    }
+    const violations = [];
+    if (maybePolicy && maybePolicy !== "0" && maybePolicy !== "1" && fs.existsSync(maybePolicy)) {
+      const pol = parsePolicy(fs.readFileSync(maybePolicy, "utf8"));
+      for (const r of pol.deny) {
+        if (r.effects.length && !r.effects.includes(eff)) continue; // pure ([]) forbids ANY effect
+        for (const fn of affected)
+          if (!r.scope || scopeMatches(fn, r.scope))
+            violations.push({ fn, rule: `deny ${r.effects.join(" ") || "(pure)"} ${r.scope}`.trim() });
+      }
+    }
+    emit({ of: targets, effect: eff, affected: [...affected].sort(), violations, ok: violations.length === 0 });
+    process.exit(violations.length ? 1 : 0);
+  }
+  default:
+    console.error("usage: node query.mjs <parsepolicy|show|where|callers|map|whatif> …");
+    process.exit(2);
+}