karajan-code 4.38.0 → 4.40.0

package/src/harden/human-act.js

@@ -0,0 +1,70 @@
+/**
+ * The layers that make a command a HUMAN act (ADR 0009), out of the supervisor's
+ * seal so that other human-only commands use the very same ones (KJC-TSK-0951).
+ *
+ *  1-2. the environment and the terminal: an agent session declares itself;
+ *  3.   the process ancestry: a kj launched by an agent DESCENDS from it, and
+ *       that is in /proc whoever fakes the pty or cleans the environment;
+ *  4.   a random nonce typed back, read from the real controlling terminal.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, openSync, readFileSync, readSync } from "node:fs";
+
+const AGENT_PROC = /claude|codex|copilot|gemini|opencode|\bagy\b/i;
+
+export function agentAncestry({ pid = process.pid, readProc = null, maxDepth = 40 } = {}) {
+  const read = readProc || ((p) => {
+    const stat = readFileSync(`/proc/${p}/stat`, "utf8");
+    const ppid = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+    let cmd = "";
+    try { cmd = readFileSync(`/proc/${p}/cmdline`).toString("utf8").replaceAll("\0", " "); } catch { /* gone */ }
+    return { ppid, cmd };
+  });
+  let cur = pid;
+  for (let i = 0; i < maxDepth && cur > 1; i += 1) {
+    let info;
+    try { info = read(cur); } catch { return { agent: false, unknown: true }; }
+    if (info?.cmd && AGENT_PROC.test(info.cmd)) return { agent: true, match: info.cmd.slice(0, 80) };
+    if (!Number.isFinite(info?.ppid) || info.ppid === cur) break;
+    cur = info.ppid;
+  }
+  return { agent: false };
+}
+
+/** Layers 1 to 3: throws when `what` runs inside an agent session. */
+export function refuseAgentSession(what, { env = process.env, tty = process.stdout.isTTY, ancestry = {} } = {}) {
+  if (env.CLAUDECODE || env.KJ_NON_INTERACTIVE === "1" || !tty) {
+    throw new Error(`${what} es un acto humano: córrelo desde TU terminal, fuera de una sesión de agente (ADR 0009)`);
+  }
+  const anc = agentAncestry(ancestry);
+  if (anc.agent) {
+    throw new Error(`${what} es un acto humano y este proceso desciende de un agente (${anc.match}) — ni con pty falso ni con el entorno limpio (ADR 0009)`);
+  }
+}
+
+// The answer comes from the process's REAL tty (not stdin, which an attacker
+// feeds through a pipe): /dev/tty only exists with a controlling terminal.
+function readTty(what, nonce) {
+  process.stdout.write(`${what}: teclea "${nonce}" para confirmar que eres humano: `);
+  try {
+    const buf = Buffer.alloc(64);
+    const fd = openSync("/dev/tty", "r");
+    const n = readSync(fd, buf, 0, 64);
+    closeSync(fd);
+    return buf.toString("utf8", 0, n).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Layer 4: a random nonce typed back. A blind feeder does not know the code;
+ * automating its reading takes an expect driver, which is premeditation.
+ * @param {string} what
+ * @param {(nonce: string) => string|null} [confirm] test seam
+ */
+export function confirmHuman(what, confirm = null) {
+  const nonce = randomBytes(3).toString("hex");
+  const answer = confirm ? confirm(nonce) : readTty(what, nonce);
+  if (answer !== nonce) throw new Error(`${what}: confirmación humana fallida (esperaba "${nonce}") — ADR 0009`);
+}

package/src/harden/phone-sign.js

@@ -132,6 +132,32 @@ export function verifyPhoneSignature({ payload, signature, publicKey }) {
   return verify(null, Buffer.from(payload, "utf8"), key, Buffer.from(signature, "base64"));
 }
 
+/**
+ * KJC-TSK-0964 (HUM-A, ADR 0018): the seal's signature, checked where the
+ * machine that made it has no say. With signers in the versioned roster, a
+ * provenance must be signed by one of them over the very files it declares.
+ * With no roster nothing is required: the guarantee is local only.
+ * @returns {{required: boolean, ok: boolean, reason?: string}}
+ */
+export function provenanceSignature({ projectDir, provenance }) {
+  const roster = readSigners({ projectDir });
+  if (roster.length === 0) return { required: false, ok: true };
+  const fail = (reason) => ({ required: true, ok: false, reason });
+  const sig = provenance?.signature;
+  if (typeof sig?.signature !== "string" || typeof sig?.signer !== "string") return fail("el padrón tiene firmantes y la procedencia no lleva firma");
+  if (!roster.includes(sig.signer)) return fail("la clave que firma la procedencia no está en el padrón");
+  // The files as the phone signed them: {file, sha256}, a deletion with no hash.
+  // A provenance is read from the project: a malformed one is rejected, it does not crash.
+  const entries = Array.isArray(provenance.files) ? provenance.files : [];
+  if (entries.some((entry) => typeof entry?.file !== "string")) return fail("la procedencia declara ficheros mal formados");
+  const files = entries.map(({ file, sha256 }) => ({ file, sha256: sha256 ?? "" }));
+  let good = false;
+  try {
+    good = verifyPhoneSignature({ payload: canonicalPayload({ ...sig, files }), signature: sig.signature, publicKey: sig.signer });
+  } catch { /* a malformed key or signature is a signature that does not verify */ }
+  return good ? { required: true, ok: true } : fail("la firma no corresponde a los ficheros que la procedencia declara");
+}
+
 /**
  * Publica la petición en Firestore, enseña QR + URL, pollea el doc y verifica
  * la firma. Sin fallbacks silenciosos: red caída o HTTP no-ok ⇒ throw. Firma

package/src/harden/sentinel/pretooluse-rules.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// kj sentinel rules hook (KJC-TSK-0946, MDR-C2, ADR 0016), managed by `kj harden`.
+// PreToolUse with NO matcher: every tool call, MCP ones included, passes the rules
+// of the MD files (compiled into .karajan/rules.yml) before it runs. Exit 2 blocks
+// the call and stderr says which rule. The decision is the gate's (sentinel-rules.mjs).
+// Copied byte for byte into .karajan/harness.
+import console from "node:console";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { ROOT, doc } from "./sentinel-lib.mjs";
+import { rulesGate } from "./sentinel-rules.mjs";
+
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  let call;
+  try { call = JSON.parse(raw); } catch { process.exit(0); } // not a tool call: nothing to judge
+  // The user's switch for the whole Sentinel, set in the host's environment.
+  if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
+  const verdict = rulesGate({ root: ROOT, tool: call?.tool_name, input: call?.tool_input, run: spawnSync });
+  if (!verdict.deny) process.exit(0);
+  console.error("karajan sentinel: " + verdict.message + doc("rules"));
+  console.error("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la regla para pasarlo; si te parece injusta, díselo a tu usuario o usa kj report-issue.");
+  process.exit(2);
+});

package/src/harden/sentinel/sentinel-bash-write.mjs

@@ -5,7 +5,7 @@
 import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
-import { headIndex, shellSegments } from "./sentinel-shell.mjs";
+import { headIndex, shellSegments, withoutRedirections } from "./sentinel-shell.mjs";
 
 const WRITES = ["tee", "touch", "truncate", "cp", "mv", "install", "ln", "sed", "perl", "dd", "sh", "bash", "zsh", "dash", "eval"];
 const RUNNERS = ["xargs", "find", "node", "python3", "python", "ruby", "php", "deno", "bun"];
@@ -56,11 +56,7 @@ export const shellWrites = (words) => {
   // xargs / find -exec run a writer on targets that arrive at run time.
   if (["xargs", "find"].includes(head) && words.slice(i + 1).some((w) => WRITES.includes(w.split("/").at(-1)))) out.push(`$(${head})`);
   // Arguments without redirections (< << <<< > >> and a detached operand).
-  const rest = [];
-  for (let k = i + 1; k < words.length; k++) {
-    if (!/^\d*[<>]/.test(words[k])) rest.push(words[k]);
-    else if (/^\d*(<{1,3}|>>?|>[|&])$/.test(words[k])) k++;
-  }
+  const rest = withoutRedirections(words.slice(i + 1));
   // Operands: words that are not options, and EVERY word after "--" (touch -- -file).
   const cut = rest.includes("--") ? rest.indexOf("--") : rest.length;
   const plain = [...rest.slice(0, cut).filter((w) => !w.startsWith("-")), ...rest.slice(cut + 1)];

package/src/harden/sentinel/sentinel-discard.mjs

@@ -2,9 +2,9 @@
 // ADR 0014). An agent does not discard changes it did not make. Copied byte for
 // byte into .karajan/harness; `root` is the project root, injected.
 import { spawnSync } from "node:child_process";
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import process from "node:process";
-import { headIndex, shortOpts } from "./sentinel-shell.mjs";
+import { headIndex, shortOpts, withoutRedirections } from "./sentinel-shell.mjs";
 
 export const DISCARD_VERBS = ["checkout", "restore", "reset", "stash", "switch", "clean"];
 
@@ -16,7 +16,9 @@ export const DISCARD_VERBS = ["checkout", "restore", "reset", "stash", "switch",
  * @param {string[]} words
  * @param {string} root
  */
-export const discardOf = (words, root) => {
+export const discardOf = (command, root) => {
+  // KJC-BUG-0268: `git checkout main 2>&1` names a branch, not a branch and a path.
+  const words = withoutRedirections(command);
   let i = headIndex(words, ["git"]); // /usr/bin/git is git
   // A $variable in command position beside a discard verb ($g checkout) cannot be read.
   if (words[i]?.startsWith("$") && words.some((w) => DISCARD_VERBS.includes(w))) return { unknown: true };
@@ -58,6 +60,30 @@ export const discardOf = (words, root) => {
   return pos.length > 1 ? { cwd, paths: pos.slice(1) } : null;
 };
 
+/**
+ * KJC-BUG-0261: the tracked files an `rm` or `git rm` removes, relative to root.
+ * Removing a file is the session touching it, so its state is noted before it
+ * goes and restoring it later is not taken for someone else's change.
+ * @param {string[]} words
+ * @param {string} root
+ * @param {string} cwd where relative paths resolve (the session's cwd)
+ * @returns {string[]}
+ */
+export const removedFiles = (words, root, cwd = process.cwd()) => {
+  const i = headIndex(words, ["rm", "git"]);
+  const head = words[i]?.split("/").at(-1);
+  const isGitRm = head === "git" && words[i + 1] === "rm";
+  if (head !== "rm" && !isGitRm) return [];
+  const args = words.slice(i + (isGitRm ? 2 : 1));
+  const dd = args.indexOf("--");
+  const named = dd < 0 ? args.filter((a) => !a.startsWith("-")) : [...args.slice(0, dd).filter((a) => !a.startsWith("-")), ...args.slice(dd + 1)];
+  const rels = named.map((p) => relative(root, resolve(cwd, p))).filter((r) => r && !r.startsWith("..") && !isAbsolute(r));
+  if (rels.length === 0) return [];
+  // ls-files expands a directory (rm -r dir) into the tracked files it holds.
+  const r = spawnSync("git", ["-C", root, "ls-files", "-z", "--", ...rels], { encoding: "utf8" });
+  return r.status === 0 ? String(r.stdout).split("\0").filter(Boolean) : [];
+};
+
 /**
  * Files the discard would lose that the session did not own: dirty now and not
  * clean at first touch. Anything unreadable, or another repo, is foreign.
@@ -84,7 +110,10 @@ export const foreignLost = (d, touch, root) => {
   }
   // Fail-closed: a path git does not know (misparsed, $VAR, substitution) cannot
   // be proven safe; git would refuse to check it out anyway.
-  if (spawnSync("git", ["-C", d.cwd, "ls-files", "--error-unmatch", "--", ...d.paths]).status !== 0) return [`(ruta no resoluble: ${d.paths.join(" ")})`];
+  if (spawnSync("git", ["-C", d.cwd, "ls-files", "--error-unmatch", "--", ...d.paths]).status !== 0) {
+    // KJC-BUG-0261: what the session removed with git rm left the index, and it is still its own.
+    return d.paths.map((p) => relative(root, resolve(d.cwd, p))).every(own) ? [] : [`(ruta no resoluble: ${d.paths.join(" ")})`];
+  }
   const r = spawnSync("git", ["-C", d.cwd, "status", "--porcelain", "-z", "--untracked-files=no", "--", ...d.paths], { encoding: "utf8" });
   if (r.status !== 0) return ["(git status fallo)"];
   const files = [];

package/src/harden/sentinel/sentinel-rules.mjs

@@ -0,0 +1,86 @@
+// The Sentinel's rules gate (KJC-TSK-0939, MDR-C, ADR 0016). A real module with
+// no dependencies: kj harden copies it byte for byte into .karajan/harness as
+// sentinel-rules.mjs, and this code is unit-tested.
+//
+// The rules written in the MD files, compiled into .karajan/rules.yml, are asked
+// to kj before EVERY tool call. kj decides (exit 0 allow, 2 deny); whatever
+// cannot be evaluated is denied, because rules silently off would be every call
+// allowed. With no rules.yml the gate does not exist and costs nothing.
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RULES_FILE = join(".karajan", "rules.yml");
+// KJC-TSK-0954 (ADR 0017): the rules from the user's private sources, out of git.
+// Either file is rules: a project with only local ones is gated just the same.
+const LOCAL_RULES_FILE = join(".karajan", "rules.local.yml");
+const hasRules = (root, exists) => exists(join(root, RULES_FILE)) || exists(join(root, LOCAL_RULES_FILE));
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+const KJ_DOES_NOT_START = /SyntaxError|ReferenceError|Cannot find module|ERR_MODULE_NOT_FOUND|ERR_REQUIRE_ESM/;
+
+/**
+ * KJC-BUG-0207: a kj that does not start (a linked tree with a syntax error) is
+ * not a verdict. Returns the file its stack names, "" when it names none, or
+ * null when kj did start.
+ * @param {string} stderr
+ */
+export const brokenKjFile = (stderr) => {
+  const text = String(stderr || "");
+  if (!KJ_DOES_NOT_START.test(text)) return null;
+  // The location line node prints: a path or file: URL (blanks allowed), then :line.
+  const at = text.split("\n").map((line) => line.trim()).find((line) => /^(file:|\/|[A-Za-z]:\\).*\.(m?js|cjs|ts):\d+$/.test(line)) || "";
+  const file = at.slice(0, at.lastIndexOf(":"));
+  return file.startsWith("file:") ? fileURLToPath(file) : file;
+};
+
+const lastJson = (stdout) => {
+  try { return JSON.parse(String(stdout || "").trim().split("\n").pop()); } catch { return null; }
+};
+const deny = (message) => ({ deny: true, message });
+
+/**
+ * KJC-TSK-0949 (MDR-E2): an MD changed and what was compiled no longer covers
+ * it. One line for the session's start, or "" when every rule is decided, there
+ * is no rules.yml, or kj cannot tell (a notice never fails a session).
+ * @param {{root: string, run: Function, exists?: Function}} opts
+ * @returns {string}
+ */
+export function rulesDriftNotice({ root, run, exists = existsSync }) {
+  if (!hasRules(root, exists)) return "";
+  const res = run("kj", ["rules", "coverage", "--json"], { cwd: root, encoding: "utf8" });
+  const counts = res.error || res.status !== 0 ? null : lastJson(res.stdout)?.counts;
+  const none = Number(counts?.none) || 0;
+  const stale = Number(counts?.stale) || 0;
+  if (none + stale === 0) return "";
+  return none + " sin gate y " + stale + " desfasada(s) entre las reglas de tus MD (" + RULES_FILE + "). Ejecuta kj rules compile, "
+    + "escribe la propuesta y pide a tu usuario que la apruebe (kj rules approve); kj rules coverage las nombra.";
+}
+
+/**
+ * @param {{root: string, tool: string, input?: object, run: Function, exists?: Function}} call
+ *   `run` is spawnSync (injected so the gate is testable without a process).
+ * @returns {{deny: boolean, message?: string}}
+ */
+export function rulesGate({ root, tool, input, run, exists = existsSync }) {
+  if (!hasRules(root, exists)) return { deny: false };
+  // The input goes on stdin: a large Write does not fit in an argument.
+  const res = run("kj", ["rules", "eval", "--tool", String(tool), "--input", "-"], { cwd: root, encoding: "utf8", input: JSON.stringify(input ?? {}) });
+  if (res.error || res.status === null) {
+    return deny(RULES_FILE + " declara reglas pero kj no es ejecutable, así que no se pueden evaluar: restaura kj en el PATH.");
+  }
+  if (res.status === 0) return { deny: false };
+  const out = lastJson(res.stdout);
+  if (res.status === 2) {
+    const source = out?.source ? " (" + out.source + ")" : "";
+    const what = String(out?.message ?? "la acción rompe una regla de los MD").replace(/[.\s]+$/, "");
+    return deny("regla " + (out?.rule_id ?? "sin identificar") + source + ": " + what + ". Sin escape (ADR 0016): si la regla está mal compilada, la corrige tu usuario.");
+  }
+  const broken = brokenKjFile(res.stderr);
+  if (broken !== null) {
+    const target = input?.file_path || input?.notebook_path || "";
+    if (EDIT_TOOLS.has(tool) && broken && target && resolve(String(target)) === resolve(broken)) return { deny: false };
+    return deny("kj no arranca" + (broken ? " (" + broken + ")" : "") + ", así que las reglas no se pueden evaluar y nada más pasa: arregla ese fichero.");
+  }
+  const why = Array.isArray(out?.errors) ? out.errors.join("; ") : "exit " + res.status;
+  return deny(RULES_FILE + " no se puede evaluar (" + why + "): lo corrige tu usuario, fuera de la sesión.");
+}

package/src/harden/sentinel/sentinel-shell.mjs

@@ -86,10 +86,42 @@ export const stripInertQuotes = (cmd) => {
 };
 
 // Options whose value is prose, never a path (gh, git, kj).
-const TEXT_OPTION = /(^|\s)(--title|--body|--message|-m|--notes|--description|--ac|--criteria|--reason|--decision|--context|--consequences)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
+const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position"]);
+const QUOTED_OPTION_VALUE = /(^|\s)(--?[a-z]+)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
 
 /** KJC-BUG-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
-export const stripTextOptionValues = (cmd) => cmd.replace(TEXT_OPTION, (_m, pre, opt, sep, val) => `${pre}${opt}${sep}${val[0]}${val[0]}`);
+export const stripTextOptionValues = (cmd) => cmd.replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
+
+/**
+ * KJC-BUG-0245: the values of the named options, read by the shell reader, so a
+ * `;`, `&&` or `|` right after a path ends the word instead of joining it.
+ * Covers `--opt value` and `--opt=value`.
+ * @param {string} cmd
+ * @param {string[]} names
+ * @returns {string[]}
+ */
+export const optionValues = (cmd, names) => shellSegments(cmd).flatMap((words) => words.flatMap((w, i) => {
+  if (names.includes(w) && i + 1 < words.length) return [words[i + 1]];
+  const eq = w.indexOf("=");
+  return eq > 0 && names.includes(w.slice(0, eq)) ? [w.slice(eq + 1)] : [];
+}));
+
+/**
+ * KJC-BUG-0268: the words of a simple command without its redirections (2>&1,
+ * >file, < file, >> log...) and the operand a detached operator takes. A
+ * redirection is where output goes, never an argument of the command.
+ * @param {string[]} words
+ */
+export const withoutRedirections = (words) => {
+  const rest = [];
+  let operand = false; // the previous word was a bare operator: this one is its target
+  for (const word of words) {
+    if (operand) operand = false;
+    else if (!/^\d*[<>]/.test(word)) rest.push(word);
+    else operand = /^\d*(<{1,3}|>>?|>[|&])$/.test(word);
+  }
+  return rest;
+};
 
 /** Short flags of a cluster stop at "e": the rest is -e's value (-fen = -f -e n). */
 export const shortOpts = (a) => (/^-[a-zA-Z]/.test(a) ? a.slice(1).split("e")[0] : "");

package/src/harden/sentinel/sessionstart.mjs

@@ -2,10 +2,12 @@
 // kj sentinel SessionStart hook (KJC-TSK-0918, ADR 0014), managed by `kj harden`.
 // A compaction takes exactly what the agent needs most: the rules it read at the
 // start. After a compaction or a resume, this gives them back, short, with the
-// state of the session. A new session gets nothing: CLAUDE.md already brings them.
+// state of the session. A new session gets no rules: CLAUDE.md already brings them.
 // Copied byte for byte into .karajan/harness; never fails a session (exit 0).
 import process from "node:process";
-import { CARD, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+import { spawnSync } from "node:child_process";
+import { CARD, ROOT, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+import { rulesDriftNotice } from "./sentinel-rules.mjs";
 
 const RULES = [
   "1. Karajan gobierna y se le obedece: no cambies políticas, configuración de gates ni exclusiones para pasar un gate. Si uno parece injusto, díselo a tu usuario o usa kj report-issue.",
@@ -24,13 +26,20 @@ process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
     const { session_id: sid = "default", source } = JSON.parse(raw || "{}");
-    if (source !== "compact" && source !== "resume") process.exit(0);
-    const branch = branchOf() || "?";
-    const card = CARD.exec(branch)?.[0]?.toUpperCase() ?? "ninguna en la rama";
-    const pending = pendingMoves(load().sessions?.[sid]).map((p) => `${p.card ?? "?"} (PR #${p.pr})`);
-    const state = `Estado: rama ${branch}, card ${card}${pending.length ? `; cards mergeadas sin mover: ${pending.join(", ")}` : ""}.`;
-    const context = ["Karajan (reglas que la compactación se lleva):", ...RULES, state].join("\n");
-    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }));
+    // KJC-TSK-0949: an MD changed and its compiled rules fell behind. Said at
+    // every start, a new session included: that one gets this line and nothing else.
+    const drift = rulesDriftNotice({ root: ROOT, run: spawnSync });
+    const lines = [];
+    if (source === "compact" || source === "resume") {
+      const branch = branchOf() || "?";
+      const card = CARD.exec(branch)?.[0]?.toUpperCase() ?? "ninguna en la rama";
+      const pending = pendingMoves(load().sessions?.[sid]).map((p) => `${p.card ?? "?"} (PR #${p.pr})`);
+      const unmoved = pending.length ? "; cards mergeadas sin mover: " + pending.join(", ") : "";
+      lines.push("Karajan (reglas que la compactación se lleva):", ...RULES, `Estado: rama ${branch}, card ${card}${unmoved}.`);
+    }
+    if (drift) lines.push(`Karajan: ${drift}`);
+    if (lines.length === 0) process.exit(0);
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } }));
   } catch { /* never fails a session */ }
   process.exit(0);
 });