seisin 0.4.2 → 0.6.0

package/src/provider-run.js

@@ -0,0 +1,81 @@
+/**
+ * Runs one key provider and reports what it printed, as JSON on stdout.
+ *
+ * A separate process because `spawnSync` cannot do two things a provider
+ * needs, and `resolveRef` is synchronous by contract (keys.js):
+ *
+ *   - **Take the answer when the provider exits.** `spawnSync` returns when
+ *     the child has exited AND every copy of its stdout is closed. A provider
+ *     that printed the value, exited 0 and left a background process holding
+ *     the pipe made seisin wait the whole timeout and then say the provider
+ *     "did not answer". Here the answer is what was read by the time the
+ *     provider exited, plus a short drain for bytes still in the pipe.
+ *   - **Stop it for good.** A timeout is SIGKILL, not SIGTERM: a provider that
+ *     ignored SIGTERM held the run forever. And it goes to every descendant
+ *     too, so a child the provider was waiting on dies with it instead of
+ *     living on. Found by walking `ps`, not by a process group of its own: a
+ *     new session would take the provider's terminal away, and a pinentry
+ *     needs it. A provider that exits on its own keeps whatever it left
+ *     running: an agent it starts (gpg-agent, an op daemon) is its business.
+ *
+ * stderr is read and counted, never kept: a provider may print the value
+ * there, and nothing downstream shows it.
+ *
+ * argv: <timeoutMs> <maxBytes> <drainMs> <command> [args…]
+ */
+import { spawn, execFileSync } from "node:child_process";
+
+const [timeoutMs, maxBytes, drainMs] = process.argv.slice(2, 5).map(Number);
+const argv = process.argv.slice(5);
+
+const chunks = [];
+let size = 0, errBytes = 0, timedOut = false, tooBig = false, done = false;
+
+function finish(result) {
+  if (done) return;
+  done = true;
+  clearTimeout(timer);
+  const out = tooBig ? "" : Buffer.concat(chunks).toString("base64");
+  process.stdout.write(JSON.stringify({ ...result, out, errBytes, timedOut, tooBig }), () => process.exit(0));
+}
+
+/** The provider and every process below it. */
+function tree(root) {
+  const kids = new Map();
+  try {
+    for (const line of execFileSync("ps", ["-A", "-o", "pid=,ppid="], { encoding: "utf8" }).split("\n")) {
+      const [pid, ppid] = line.trim().split(/\s+/).map(Number);
+      if (pid && ppid) kids.set(ppid, [...(kids.get(ppid) ?? []), pid]);
+    }
+  } catch {}
+  const all = [root];
+  for (let i = 0; i < all.length; i++) all.push(...(kids.get(all[i]) ?? []));
+  return all;
+}
+
+const child = spawn(argv[0], argv.slice(1), { stdio: ["ignore", "pipe", "pipe"] });
+const kill = () => {
+  if (!child.pid) return;
+  // Stopped first, so nothing forks between the listing and the kill.
+  const pids = tree(child.pid);
+  for (const pid of pids) try { process.kill(pid, "SIGSTOP"); } catch {}
+  for (const pid of tree(child.pid)) if (!pids.includes(pid)) pids.push(pid);
+  for (const pid of pids) try { process.kill(pid, "SIGKILL"); } catch {}
+};
+const timer = setTimeout(() => { timedOut = true; kill(); }, timeoutMs);
+
+child.stdout.on("data", (c) => {
+  size += c.length;
+  if (size > maxBytes) { tooBig = true; chunks.length = 0; kill(); return; }
+  if (!tooBig) chunks.push(c);
+});
+child.stderr.on("data", (c) => { errBytes += c.length; });
+child.on("error", (e) => finish({ error: e.code ?? e.message }));
+child.on("exit", (status, signal) => {
+  // What the provider wrote before exiting may still be in the pipe. Wait for
+  // the end of it, but not for a descendant that kept the pipe open.
+  const drained = () => finish({ status, signal });
+  if (child.stdout.readableEnded) return drained();
+  child.stdout.once("end", drained);
+  setTimeout(drained, drainMs).unref();
+});

package/src/redact.js

@@ -20,6 +20,7 @@
  * README spends its time avoiding.
  */
 import { Transform } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
 
 /** Reads the values this role may read. Unreadable or huge files are skipped. */
 export function secretsOf(settings, readFile) {
@@ -49,34 +50,66 @@ export function secretsOf(settings, readFile) {
  * It carries the tail of each chunk forward, because a value split across a
  * buffer boundary would otherwise sail through — which is the one case a
  * naive implementation always gets wrong and never notices.
+ *
+ * Bytes are decoded with a StringDecoder that lives as long as the stream. A
+ * chunk boundary falls wherever the pipe put it, including inside a multibyte
+ * character: decoding each chunk on its own turned `año` into `a��o`, and a
+ * secret with an `ñ` in it split that way was never seen whole, so it was
+ * never masked. The same care applies to the cut below, which must not leave
+ * half of a surrogate pair on either side.
  */
 export function redactor(secrets, label = "redacted") {
+  // Embedders use this export directly; neither order nor empty values may
+  // decide how much of a split credential is retained between chunks.
+  secrets = [...new Set(secrets.filter((s) => typeof s === "string" && s.length > 0))]
+    .sort((a, b) => b.length - a.length);
   if (secrets.length === 0) return null;
   const longest = secrets[0].length;
+  const decoder = new StringDecoder("utf8");
   let tail = "";
 
   return new Transform({
     transform(chunk, _enc, done) {
-      // Mask the WHOLE accumulated text first, then cut. Doing it the other way
-      // — masking only the part about to be emitted — lets a secret that
-      // straddles the cut through in two innocent halves. Written that way
-      // first; the split-buffer test caught it on the first run.
-      const masked = mask(tail + chunk.toString("utf8"), secrets, label);
-      const keep = Math.min(longest - 1, masked.length);
-      this.push(masked.slice(0, masked.length - keep));
-      tail = masked.slice(masked.length - keep);
+      // Retain original input, not replacement text. Replacing a shorter
+      // credential before a longer one finishes destroys their shared prefix;
+      // carrying a marker forward also lets another secret replace its label.
+      const text = typeof chunk === "string" ? chunk : decoder.write(chunk);
+      const buffered = tail + text;
+      let cut = Math.max(0, buffered.length - longest + 1);
+      if (cut > 0 && isHighSurrogate(buffered.charCodeAt(cut - 1))) cut--;
+      const result = maskPrefix(buffered, cut, secrets, label);
+      if (result.output) this.push(result.output);
+      tail = result.tail;
       done();
     },
     flush(done) {
-      this.push(mask(tail, secrets, label));
+      const text = tail + decoder.end();
+      const result = maskPrefix(text, text.length, secrets, label);
+      if (result.output) this.push(result.output);
       tail = "";
       done();
     },
   });
 }
 
-function mask(text, secrets, label) {
-  let out = text;
-  for (const s of secrets) out = out.split(s).join(`‹${label}›`);
-  return out;
+const isHighSurrogate = (c) => c >= 0xd800 && c <= 0xdbff;
+
+/** Only match starts with enough input to decide the longest credential. */
+function maskPrefix(text, cut, secrets, label) {
+  const next = secrets.map((s) => text.indexOf(s));
+  let from = 0, output = "";
+  while (from < cut) {
+    let at = Infinity, chosen = -1;
+    for (let i = 0; i < next.length; i++) {
+      if (next[i] >= 0 && next[i] < at) { at = next[i]; chosen = i; }
+    }
+    if (at >= cut) { output += text.slice(from, cut); from = cut; break; }
+    output += text.slice(from, at) + `‹${label}›`;
+    from = at + secrets[chosen].length;
+    // Keep each search moving forward. In particular, a value absent from
+    // this buffer is not searched again for every occurrence of another.
+    for (let i = 0; i < next.length; i++)
+      if (next[i] >= 0 && next[i] < from) next[i] = text.indexOf(secrets[i], from);
+  }
+  return { output, tail: text.slice(from) };
 }

package/src/render.js

@@ -67,8 +67,16 @@ export function collapseSidecars(paths) {
   return out;
 }
 
-/** The `check` report, as text. Takes the object `inspect()` returns. */
-export function renderReport(report) {
+/**
+ * The `check` report, as text. Takes the object `inspect()` returns.
+ *
+ * The map and one line per warning first; the paragraphs behind `verbose`.
+ * On a three-role repo the full report ran to forty lines of explanation under
+ * a six-line map, and the one warning a person could act on sat in the middle.
+ * Nothing is dropped: the protected paths, each warning's reason and the
+ * standing limits are one flag away, and the footer says how many.
+ */
+export function renderReport(report, { verbose = true } = {}) {
   const lines = [`\n${C.b}${report.where}${C.off}\n\n`];
   const width = Math.max(...report.roles.map((r) => r.name.length), 4);
 
@@ -78,6 +86,8 @@ export function renderReport(report) {
     lines.push(`  ${C.b}${r.name.padEnd(width)}${C.off}  ${C.blue}writes${C.off} ${writes}\n`);
     // Only when present: absent is the default, and a "never_writes nothing" line
     // on every role is noise that teaches the reader to skip the one that matters.
+    if (r.private?.length)
+      lines.push(`  ${" ".repeat(width)}  ${C.yellow}private${C.off} ${r.private.join(" ")} ${C.dim}(only this role reads or writes it)${C.off}\n`);
     if (r.neverWrites?.length)
       lines.push(`  ${" ".repeat(width)}  ${C.yellow}never${C.off}  ${collapseSidecars(r.neverWrites).join(" ")}\n`);
     if (r.trustd)
@@ -88,6 +98,12 @@ export function renderReport(report) {
       lines.push(`  ${" ".repeat(width)}  ${C.yellow}mcp${C.off}    ${r.mcp.length ? r.mcp.join(" ") : "none"} ${C.dim}(declared; the launcher enforces it)${C.off}\n`);
     if (r.localPorts?.length)
       lines.push(`  ${" ".repeat(width)}  ${C.yellow}reach${C.off}  localhost ${r.localPorts.join(" ")} ${C.dim}(local_ports, through the proxy)${C.off}\n`);
+    if (r.reads?.length)
+      lines.push(`  ${" ".repeat(width)}  ${C.blue}reads${C.off}  ${r.reads.join(" ")}\n`);
+    if (r.toolchain?.length)
+      lines.push(`  ${" ".repeat(width)}  ${C.blue}tools${C.off}  ${r.toolchain.join(" ")}\n`);
+    if (r.verify)
+      lines.push(`  ${" ".repeat(width)}  ${C.blue}verify${C.off} ${r.verify.join(" ")}\n`);
     lines.push(`  ${" ".repeat(width)}  ${C.green}keys${C.off}   ${keys}\n\n`);
   }
 
@@ -101,10 +117,10 @@ export function renderReport(report) {
   // What the kernel refuses inside a territory, and why. Shown because each one
   // takes something from a territory as written; capped because a monorepo has
   // a hooks directory per package and the reader needs the shape, not all 200.
-  if (report.protected?.length) {
+  if (report.protected?.length && verbose) {
     const root = report.where ? report.where.replace(/\/[^/]*$/, "/") : "";
     const show = (p) => (root && p.startsWith(root) ? p.slice(root.length) : p.replace(/^\/Users\/[^/]+|^\/home\/[^/]+/, "~"));
-    lines.push(`  ${C.b}protected${C.off} ${C.dim}— inside a territory, refused anyway: something outside the box runs or reads it${C.off}\n`);
+    lines.push(`  ${C.b}protected${C.off} ${C.dim}— inside a territory, denied anyway: something outside the sandbox runs or reads it${C.off}\n`);
     const LIMIT = 12;
     for (const e of report.protected.slice(0, LIMIT)) {
       const who = e.roles.length > 3 ? `${e.roles.slice(0, 3).join(", ")} +${e.roles.length - 3}` : e.roles.join(", ");
@@ -115,22 +131,39 @@ export function renderReport(report) {
     lines.push("\n");
   }
 
+  if (!verbose) {
+    for (const w of report.warnings) lines.push(`  ${C.yellow}${w.headline}${C.off}\n`);
+    if (report.warnings.length) lines.push("\n");
+    const more = [
+      report.protected?.length ? `${report.protected.length} protected path(s)` : "",
+      report.warnings.some((w) => w.detail) ? "why each warning matters" : "",
+    ].filter(Boolean);
+    if (more.length) lines.push(`  ${C.dim}seisin check --verbose: ${more.join(", ")}${C.off}\n`);
+    lines.push(limitsLine(report), "\n");
+    return lines.join("");
+  }
+
   for (const w of report.warnings) {
     lines.push(`  ${C.yellow}${w.headline}${C.off}\n`);
     if (w.detail) lines.push(`  ${C.dim}${w.detail}${C.off}\n`);
+    // A list is a list: one entry per line, not a sentence of twenty paths.
+    for (const item of w.items ?? []) lines.push(`    ${C.dim}${item}${C.off}\n`);
     lines.push("\n");
   }
 
-  // Dim, and last: a standing limit is not an alarm, but it is not a footnote
-  // either — it is the part of the map that is blank.
-  for (const l of report.limits ?? []) {
-    lines.push(`  ${C.dim}${l.headline}${C.off}\n`);
-    if (l.detail) lines.push(`  ${C.dim}${l.detail}${C.off}\n`);
-    lines.push("\n");
-  }
+  // The standing limits are the same in every repo, so they are one line here
+  // and the paragraphs are `seisin help limits` — six of them closed every
+  // verbose report, under the part that was about this repo.
+  lines.push(limitsLine(report), "\n");
   return lines.join("");
 }
 
+/** Where the standing limits are, or nothing when the report carries none. */
+function limitsLine(report) {
+  const n = report.limits?.length ?? 0;
+  return n ? `  ${C.dim}${n} standing limit(s) apply to every repo: seisin help limits${C.off}\n` : "";
+}
+
 /* ── one verdict ──────────────────────────────────────────────────────── */
 
 /** The `explain` answer, as text. Takes what `owners.explain()` returns. */
@@ -149,6 +182,19 @@ export function renderVerdict(role, action, target, verdict) {
  * people to stop reading the colour.
  */
 export function renderEntry(e) {
+  if (e.event === "canary") {
+    const mark = e.confined ? `${C.green}canary passed${C.off}` : `${C.red}canary failed${C.off}`;
+    const why = e.reasons?.length ? `  ${C.dim}${e.reasons.join("; ")}${C.off}` : "";
+    return `  ${C.dim}${(e.at ?? "").slice(11, 19)}${C.off}  ${mark}  ${C.b}${e.role}${C.off}${why}\n`;
+  }
+  if (e.event === "log-dropped") {
+    const mark = `${C.yellow}log dropped${C.off}`;
+    return `  ${C.dim}${(e.at ?? "").slice(11, 19)}${C.off}  ${mark}  ${C.b}${e.role}${C.off} ${C.dim}${e.batches} batch(es) of system log messages lost — kernel denials may be missing${C.off}\n`;
+  }
+  if (e.event === "key") {
+    const mark = e.ok ? `${C.green}key resolved${C.off}` : `${C.red}key failed${C.off}`;
+    return `  ${C.dim}${(e.at ?? "").slice(11, 19)}${C.off}  ${mark}  ${C.b}${e.role}${C.off} ${safe(e.key)}  ${C.dim}${e.mode}${C.off}\n`;
+  }
   const mark =
     e.verdict === "denied" ? `${C.yellow}denied ${C.off}`
     : e.verdict === "observed" ? `${C.dim}seen   ${C.off}`
@@ -177,16 +223,40 @@ export function renderScan(result, keyDirs) {
   const { certain, review, skipped, truncated } = result;
   const links = result.links ?? [];
   const where = keyDirs.length ? keyDirs.join(", ") : `${C.yellow}nowhere — [keys] dir is unset${C.off}`;
-  const lines = [`\n  ${C.dim}protected: ${where}${C.off}\n\n`];
+  const lines = [`\n  ${C.dim}protected: ${where}${C.off}\n`];
+  // Scoped to the territories: say where it looked, and how to look everywhere.
+  if (result.scope) {
+    const shown = result.scope.slice(0, 10).map(safe).join(", ");
+    const more = result.scope.length > 10 ? ` and ${result.scope.length - 10} more` : "";
+    lines.push(`  ${C.dim}scanned: where the territories are — ${shown}${more}. ${C.b}seisin scan --all${C.off}${C.dim} walks the whole folder${C.off}\n`);
+  }
+  lines.push("\n");
 
-  if (certain.length === 0 && review.length === 0 && links.length === 0) {
-    lines.push(`  ${C.green}nothing credential-shaped outside the declared directories${C.off}\n\n`);
+  // A pruned checkout is part of what a clean result means, so it is said
+  // even when there is nothing else to say — in yellow, not dim: every role
+  // can still read it, and a dim line under a green verdict read as clean.
+  const paths = result.nestedPaths ?? [];
+  let nested = "";
+  if (skipped.nested) {
+    nested = `  ${C.yellow}not scanned: ${skipped.nested} nested checkout(s)${C.off} — another repository each; every role can still read them. Scan one with ${C.b}cd <dir> && seisin scan${C.off}\n`;
+    for (const p of paths.slice(0, 15)) nested += `    ${safe(p)}\n`;
+    if (paths.length > 15) nested += `    ${C.dim}… and ${paths.length - 15} more${C.off}\n`;
+    nested += "\n";
+  }
+  const named = result.named ?? [];
+  if (certain.length === 0 && review.length === 0 && links.length === 0 && named.length === 0) {
+    lines.push(skipped.nested
+      ? `  nothing credential-shaped in what was scanned ${C.dim}(outside the declared directories)${C.off}\n\n`
+      : `  ${C.green}nothing credential-shaped outside the declared directories${C.off}\n\n`, nested);
     return lines.join("");
   }
 
   if (certain.length) {
-    lines.push(`  ${C.red}${certain.length} credential(s)${C.off} — these shapes are issued, not written by accident\n\n`);
-    for (const h of certain) lines.push(`    ${C.b}${h.file}${C.off}${C.dim}:${h.line}${C.off}  ${h.shape}\n`);
+    lines.push(`  ${C.red}${certain.length} credential(s)${C.off} — issued shapes, or a password in a URL: a credential, not a word that mentions one\n\n`);
+    for (const h of certain) {
+      const whose = h.owners?.length ? `  ${C.dim}in ${h.owners.map(safe).join(", ")}'s territory${C.off}` : "";
+      lines.push(`    ${C.b}${safe(h.file)}${C.off}${C.dim}:${h.line}${C.off}  ${h.shape}${whose}\n`);
+    }
     lines.push("\n");
   }
 
@@ -200,6 +270,18 @@ export function renderScan(result, keyDirs) {
     lines.push("\n");
   }
 
+  // By name, not by content, and said that way: a .env of DEBUG=1 is on this
+  // list too. What it is for is the .env nobody declared.
+  if (named.length) {
+    lines.push(`  ${C.yellow}${named.length} file(s) that usually hold secrets${C.off} — by their name, not certain; every role reads them\n\n`);
+    for (const h of named.slice(0, 15)) {
+      const whose = h.owners?.length ? `  ${C.dim}in ${h.owners.map(safe).join(", ")}'s territory${C.off}` : "";
+      lines.push(`    ${C.b}${safe(h.file)}${C.off}${whose}\n`);
+    }
+    if (named.length > 15) lines.push(`    ${C.dim}… and ${named.length - 15} more${C.off}\n`);
+    lines.push("\n");
+  }
+
   // Links are their own finding, not a line with a secret-shaped name in it.
   // What is reported is that the link leaves the repo — the destination is
   // named and never opened, because the point is that it exists.
@@ -217,7 +299,9 @@ export function renderScan(result, keyDirs) {
   if (skipped.ignored) quiet.push(`${skipped.ignored} ignored path(s)`);
   if (skipped.protectedDirs) quiet.push(`${skipped.protectedDirs} inside declared key dir(s)`);
   if (quiet.length) lines.push(`  ${C.dim}not reported: ${quiet.join(" · ")}${C.off}\n`);
-  if (truncated) lines.push(`  ${C.yellow}stopped at the limit — there are more${C.off}\n`);
+  // Only the ones to review are capped; a certain hit is always listed above.
+  if (truncated) lines.push(`  ${C.yellow}${result.omitted ?? "more"} more to review were not listed — the cap applies to review, never to certain hits${C.off}\n`);
+  if (nested) lines.push(nested);
   lines.push(`  ${C.dim}seisin does not move these. Where a credential lives is your call.${C.off}\n\n`);
   return lines.join("");
 }