simt-dev 0.6.2 → 0.6.3

package/src/secrets.mjs

@@ -0,0 +1,231 @@
+// A zero-dependency scan of the staged diff for secrets (plan 0003 R52).
+//
+// Two finding sources, deliberately both. A pattern library catches the shapes
+// vendors publish — an AWS key id, a private key header, a token prefix — and
+// Shannon entropy catches the high-entropy blobs that carry no prefix at all:
+// a 32-character random base64 string is a secret whether or not a vendor named
+// it. Neither needs a network call or an install step, which is the point. A
+// gate that needs an install step is a gate a fresh clone does not have
+// (ADR-012, zero runtime dependencies).
+//
+// Three boundaries, each load-bearing:
+//
+//   - Added lines only. The scan reads `git diff --cached`, so a secret already
+//     sitting in history is not this gate's finding: the commit about to be made
+//     is. Flagging context lines would block commits for work the author did not
+//     stage, which is the failure `format`'s staged-only rule exists to prevent.
+//   - Findings never print the matched bytes. The hook output lands in a
+//     terminal, a CI log and often a transcript an agent reads back: echoing the
+//     secret into a report about the secret is the leak with extra steps. A
+//     finding carries a four-character prefix (the part a vendor publishes as a
+//     type — `AKIA`, `sk-`, `ghp_`) and nothing else.
+//   - Placeholders are not secrets. `password = "changeme-example"` in a README
+//     is documentation, and a gate that blocks it teaches the exact `--no-verify`
+//     habit the dispatcher's fail-closed rule exists to prevent.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+/** The length at which a token is worth measuring, and the entropy it must reach. */
+const ENTROPY_MIN_LENGTH = 32;
+export const ENTROPY_MIN_BITS = 4.5;
+
+/**
+ * Value markers that mean "this string is here to be replaced". A pattern match
+ * or entropy hit whose value carries one of these is documentation, not a leak.
+ */
+const PLACEHOLDER =
+  /(example|placeholder|changeme|dummy|redacted|notasecret|your[_-]|xxxx+|<[a-z-]*>|\{\{?[a-z_.-]+\}\}?)/i;
+
+/**
+ * The pattern library. Each row names itself so the finding tells the reader
+ * WHICH shape matched — "a secret was found" sends them hunting for it;
+ * "aws-access-key-id on line 12" says what to revoke.
+ *
+ * `group`, when set, is the capture holding the VALUE — what the placeholder
+ * check and the redaction run on. Without it the whole match is the value.
+ */
+const PATTERNS = [
+  { id: 'aws-access-key-id', re: /\b(?:A3T[A-Z0-9]|AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/g },
+  { id: 'private-key-block', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY(?: BLOCK)?-----/g },
+  { id: 'github-token', re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b|\bgithub_pat_[A-Za-z0-9_]{22,}\b/g },
+  { id: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { id: 'stripe-live-key', re: /\b(?:sk|rk)_live_[0-9a-zA-Z]{24,}\b/g },
+  { id: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { id: 'openai-style-key', re: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+  { id: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+  {
+    id: 'assigned-secret',
+    re: /\b(?:password|passwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\b\s*[:=]\s*["']([^"']{8,})["']/gi,
+    group: 1,
+  },
+];
+
+/** Longest base64ish run worth measuring for entropy. */
+const ENTROPY_CANDIDATE = /[A-Za-z0-9+/=_-]{32,}/g;
+
+/**
+ * Shannon entropy of a string, in bits per character.
+ *
+ * The detector's whole discriminator in one function: a uniformly random token
+ * approaches log2(alphabet size) — near 6 bits for base64 — while English,
+ * hex digests and repeated identifiers fall below 4.5. A sha256 hex digest tops
+ * out at 4.0 over sixteen symbols, which is exactly why the threshold sits above
+ * it: a commit hash is not a secret, and a gate that calls it one gets disabled.
+ */
+export function entropy(text) {
+  const freq = new Map();
+  for (const ch of text) freq.set(ch, (freq.get(ch) ?? 0) + 1);
+  let bits = 0;
+  for (const n of freq.values()) {
+    const p = n / text.length;
+    bits -= p * Math.log2(p);
+  }
+  return bits;
+}
+
+/** The four characters a finding may show: the prefix a vendor publishes as a type. */
+function redact(value) {
+  return `${value.slice(0, 4)}…`;
+}
+
+/**
+ * Scan one line's worth of added text.
+ *
+ * @param {string} text the added line, without the leading `+`
+ * @returns {{kind: string, preview: string, entropy?: number}[]} findings in
+ *   pattern order, then entropy over whatever no pattern claimed
+ */
+export function scanText(text) {
+  const found = [];
+  const claimed = [];
+
+  for (const pattern of PATTERNS) {
+    pattern.re.lastIndex = 0;
+    for (const match of text.matchAll(pattern.re)) {
+      const value = pattern.group !== undefined ? match[pattern.group] : match[0];
+      if (PLACEHOLDER.test(value)) continue;
+      const at = match.index + (pattern.group !== undefined ? match[0].indexOf(value) : 0);
+      // Overlap, not equality: a token a pattern named is one finding, and the
+      // entropy reading of the same bytes would double the count a gate reports.
+      if (claimed.some(([a, b]) => at < b && a < at + value.length)) continue;
+      claimed.push([at, at + value.length]);
+      found.push({ kind: pattern.id, preview: redact(value) });
+    }
+  }
+
+  ENTROPY_CANDIDATE.lastIndex = 0;
+  for (const match of text.matchAll(ENTROPY_CANDIDATE)) {
+    const value = match[0];
+    if (value.length < ENTROPY_MIN_LENGTH) continue;
+    if (PLACEHOLDER.test(value)) continue;
+    if (claimed.some(([a, b]) => match.index < b && a < match.index + value.length)) continue;
+    const bits = entropy(value);
+    if (bits < ENTROPY_MIN_BITS) continue;
+    found.push({ kind: 'high-entropy', preview: redact(value), entropy: Number(bits.toFixed(1)) });
+  }
+
+  return found;
+}
+
+/**
+ * Scan the staged diff: the added lines of what the next commit would record.
+ *
+ * File attribution is a hunk state machine rather than a prefix test, because
+ * the two are indistinguishable by prefix alone: an added line whose content
+ * starts with `++ ` renders as `+++ something`, which looks exactly like a
+ * `+++ b/…` file header. Headers appear only outside hunks and content only
+ * inside them, so the `diff --git` boundary and the `@@` header decide which
+ * one a line is.
+ *
+ * @param {string} root repository root
+ * @returns {Promise<{findings: {file: string, line: number, kind: string,
+ *   preview: string, entropy?: number}[], lines: number, error: string|null}>}
+ *   `error` is set only when git itself could not answer; callers fail closed on
+ *   it rather than reading silence as a clean diff.
+ */
+export async function scanStaged(root) {
+  let stdout;
+  try {
+    // Every flag here defeats a way a repository can keep the scan from seeing its
+    // own staged bytes (review 0003 Q02): `diff.external` routes the diff to a
+    // program that prints nothing, `-diff` in `.gitattributes` and genuinely binary
+    // files make git print no text at all, a textconv rewrites the bytes on the way
+    // out, `diff.mnemonicPrefix` renames the header prefixes the attribution below
+    // reads, and C-quoting mangles a non-ASCII name. The scan asks git for the staged
+    // bytes with its own flags and ignores what the repository asked for.
+    ({ stdout } = await exec(
+      'git',
+      [
+        '-c', 'core.quotePath=false',
+        'diff',
+        '--cached',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--text',
+        '--unified=0',
+        '--no-color',
+        '--src-prefix=a/',
+        '--dst-prefix=b/',
+      ],
+      { cwd: root, maxBuffer: 32 * 1024 * 1024 },
+    ));
+  } catch (error) {
+    const stderr = String(error.stderr ?? '').trim();
+    const reason = (stderr || String(error.message ?? error)).split('\n')[0];
+    return { findings: [], lines: 0, error: reason };
+  }
+
+  const findings = [];
+  let lines = 0;
+  let file = null;
+  let lineNo = 0;
+  let inHunk = false;
+
+  for (const raw of stdout.split('\n')) {
+    if (raw.startsWith('diff --git ')) {
+      inHunk = false;
+      continue;
+    }
+    if (raw.startsWith('@@ ')) {
+      const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+      if (hunk) {
+        lineNo = Number(hunk[1]);
+        inHunk = true;
+      }
+      continue;
+    }
+    if (!inHunk) {
+      // Outside a hunk: headers only. `+++ /dev/null` is the removal side of a
+      // deletion; nothing is added under it.
+      if (raw.startsWith('+++ ')) {
+        const path = raw.slice(4).trim();
+        file = path === '/dev/null' ? null : path.replace(/^b\//, '');
+      }
+      continue;
+    }
+    if (!raw.startsWith('+')) continue; // -U0 has no context; this is `\ No newline…`
+    lines += 1;
+    if (file !== null) {
+      for (const hit of scanText(raw.slice(1))) {
+        findings.push({ file, line: lineNo, ...hit });
+      }
+    }
+    lineNo += 1;
+  }
+
+  return { findings, lines, error: null };
+}
+
+/** The report a failing gate prints: one finding per line, redacted. */
+export function renderFindings(findings) {
+  return findings
+    .map(
+      (f) =>
+        `  ${f.file}:${f.line}  ${f.kind}  ${f.preview}` +
+        (f.entropy !== undefined ? `  (entropy ${f.entropy} bits)` : ''),
+    )
+    .join('\n');
+}

package/src/status.mjs

@@ -0,0 +1,152 @@
+// The `--line` status cache (plan 0003 R48).
+//
+// `status --line` is for shell prompts, tmux and agent status lines: it must
+// answer in well under 50 ms, which rules out everything `check` does (rule
+// loading, projection, gate probing). So `check` — the one command that
+// already measures all of it — writes `.simt/check.json` on every run, and
+// `--line` reads only that file plus one `git rev-parse HEAD` to notice new
+// commits. No fingerprint, no rule reads, no capability probe.
+//
+// Three honesties, each a failure this module refuses to be:
+//
+//   - The cache is local state, never content (the same standing as the
+//     journal, the ledger and the index). Writers that change files `check`
+//     reads (`init`, `sync`, `upgrade`, `hooks install`, `undo`) delete it
+//     when they apply, so the line goes back to "no cache" instead of
+//     reporting the tree as it was. Hand edits between checks are the
+//     documented blind spot: the line is the gate state *as of the last
+//     check*, and says `stale` only when HEAD moved.
+//   - A blocking finding that fits no slot still fails the line. The version
+//     pin, an invalid rule, a bad gate cwd — none of these is rules, hooks
+//     or gates-count, and a line that showed all slots green while the gate
+//     fails would be the lie prompts are for. So PASS/FAIL is carried
+//     explicitly rather than inferred from the symbols.
+//   - The write is atomic (tmp + rename) and fixed-size: only counts and
+//     booleans are stored, never findings, so a huge gate still leaves a
+//     ~200-byte file and a killed `check` never leaves half a document.
+
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { readHooksState, wantsShim } from './compare/hooksstate.mjs';
+import { STATE_DIR } from './name.mjs';
+
+const exec = promisify(execFile);
+
+const CACHE_FILE = join(STATE_DIR, 'check.json');
+const CACHE_VERSION = 1;
+
+/**
+ * The commit the cached state was measured at, or null when git cannot say
+ * (not a repository, no commits yet, git missing). Null is trust, not failure:
+ * without a HEAD there is nothing to compare, and refusing the line would
+ * make exported trees — the ones with no `.git` at all — unreportable.
+ */
+export async function currentHead(root) {
+  try {
+    const { stdout } = await exec('git', ['rev-parse', 'HEAD'], { cwd: root });
+    return stdout.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function cachePath(root) {
+  return join(root, CACHE_FILE);
+}
+
+/**
+ * Add the when and the where to a check-measured summary. The summary itself
+ * is built by `check`, which is the only command that measures all of it;
+ * this only stamps it.
+ */
+export async function buildCacheRecord(root, summary) {
+  return {
+    version: CACHE_VERSION,
+    at: Date.now(),
+    head: await currentHead(root),
+    rulesOk: summary.rulesOk,
+    hooksOk: summary.hooksOk,
+    gatesRun: summary.gatesRun,
+    gatesTotal: summary.gatesTotal,
+    blocking: summary.blocking,
+    warnings: summary.warnings,
+  };
+}
+
+/** Atomically replace the cache. A killed `check` leaves the previous record, not half of one. */
+export async function writeCheckCache(root, record) {
+  const path = cachePath(root);
+  await mkdir(join(root, STATE_DIR), { recursive: true });
+  const body = `${JSON.stringify(record)}\n`;
+  const tmp = `${path}.tmp-${process.pid}`;
+  await writeFile(tmp, body, 'utf8');
+  await rename(tmp, path);
+}
+
+/** The last record `check` wrote, or null when it never ran (or a writer invalidated it). */
+export async function readCheckCache(root) {
+  let raw;
+  try {
+    raw = await readFile(cachePath(root), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  try {
+    const record = JSON.parse(raw);
+    if (record.version !== CACHE_VERSION) return null;
+    return record;
+  } catch {
+    // A damaged cache is no cache: the next `check` rewrites it, and a prompt
+    // that refused to render over a corrupt byte would stay broken until then.
+    return null;
+  }
+}
+
+/**
+ * Forget the cached state. Called by writers that change files `check` reads,
+ * after they apply — never on preview or dry-run, where nothing changed and
+ * the record is still true.
+ */
+export async function invalidateCheckCache(root) {
+  try {
+    await unlink(cachePath(root));
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+}
+
+/**
+ * The hooks slot of the line: every declared gate routed through a current
+ * shim. A repository that declares no gate has nothing to enforce, so the
+ * slot is vacuously true rather than forever red (the same answer `init`
+ * prints in prose). Gates run/total is counted by `check` from the runnable
+ * verdicts, not here: routing and runnability are different slots.
+ */
+export async function hooksSummary(root, manifest, exists) {
+  const declared = [...(manifest?.gates?.preCommit ?? []), ...(manifest?.gates?.prePush ?? [])];
+  const evidence = manifest?.gates?.evidence === 'warn' || manifest?.gates?.evidence === 'block';
+  if (declared.length === 0 && !evidence) return { ok: true };
+  const state = await readHooksState(root, { declaresGate: (event) => wantsShim(manifest, exists, event) });
+  return { ok: state.complete };
+}
+
+/**
+ * One line, always: `simt PASS ✓rules ✓hooks 3/3gates`, longest honest case
+ * `simt FAIL ✗rules ✗hooks 0/12gates ⚠9 stale`. Counts stay small because they
+ * count gates and warnings, never findings; the ≤ 60-char budget is asserted
+ * on a synthetic worst case, not on the hope that gates stay few.
+ */
+export function renderStatusLine(record, stale) {
+  const outcome = record.blocking === 0 ? 'PASS' : 'FAIL';
+  const rules = record.rulesOk ? '✓rules' : '✗rules';
+  const hooks = record.hooksOk ? '✓hooks' : '✗hooks';
+  let line = `simt ${outcome} ${rules} ${hooks} ${record.gatesRun}/${record.gatesTotal}gates`;
+  if (record.warnings > 0) line += ` ⚠${record.warnings}`;
+  if (stale) line += ' stale';
+  return line;
+}