@opencode-cockpit/trust 0.0.0-stage → 0.8.0

package/dist/core/sample.js

@@ -0,0 +1,311 @@
+/**
+ * Sample worlds for the preview and the grid test: the states a design gets wrong
+ * (docs/building/testing.md) — nothing at all, a first week, a busy project, a paused one, one
+ * where something broke, and one grouped into families with one of them widened by hand.
+ *
+ * Each is built by running the real engine over real requests, so the preview shows what the
+ * engine actually produces rather than what a hand-written state hoped it would.
+ */
+
+import { createEngine } from "./engine.js";
+import { DAY } from "./ledger.js";
+import { rulesFrom } from "./rules.js";
+export const SAMPLE_ROOT = "/work/app";
+export const SAMPLE_NOW = 1_790_300_000_000;
+export const SAMPLE_SETTINGS = {
+  threshold: 3,
+  dangerExtra: 5,
+  expireDays: 30,
+  keep: 20
+};
+const RULES = rulesFrom({
+  permission: {
+    bash: {
+      "*": "ask",
+      "npm publish *": "ask"
+    },
+    edit: "ask",
+    webfetch: "ask"
+  }
+});
+function build(script) {
+  const engine = createEngine(SAMPLE_SETTINGS);
+  let n = 0;
+  let clock = SAMPLE_NOW - 3 * DAY;
+  const ask = (line, permission = "bash", patterns = [line], agent = "build") => {
+    n++;
+    const request = {
+      id: `per_${n}`,
+      sessionID: "ses_sample",
+      permission,
+      patterns,
+      always: permission === "bash" ? [`${line.split(" ").slice(0, 2).join(" ")} *`] : ["*"],
+      call: `call_${n}`
+    };
+    const {
+      judgement,
+      event
+    } = engine.ask({
+      request,
+      context: {
+        line,
+        root: SAMPLE_ROOT
+      },
+      agent,
+      rules: RULES,
+      at: clock
+    });
+    engine.load([event]);
+    return {
+      id: request.id,
+      judgement
+    };
+  };
+  const steps = {
+    at: ms => {
+      clock = ms;
+    },
+    approve(line, times, how = "once", permission = "bash", agent = "build") {
+      for (let i = 0; i < times; i++) {
+        const {
+          id
+        } = ask(line, permission, [line], agent);
+        clock += 2_000;
+        engine.load(engine.replied({
+          requestID: id,
+          reply: how,
+          at: clock
+        }).events);
+        clock += 60_000;
+      }
+    },
+    auto(line, times, permission = "bash", agent = "build") {
+      for (let i = 0; i < times; i++) {
+        const {
+          id,
+          judgement
+        } = ask(line, permission, [line], agent);
+        if (!judgement.answer) throw new Error(`sample: ${line} is not trusted (${judgement.why})`);
+        clock += 25;
+        const event = engine.answered(id, clock);
+        if (event) engine.load([event]);
+        engine.replied({
+          requestID: id,
+          reply: "once",
+          at: clock + 5
+        });
+        clock += 90_000;
+      }
+    },
+    pending(line) {
+      ask(line);
+    },
+    widen(family, agent, permission = "bash") {
+      engine.load([{
+        v: 1,
+        at: clock,
+        type: "widened",
+        permission,
+        agent,
+        family
+      }]);
+      clock += 1_000;
+    }
+  };
+  script(steps);
+  return engine;
+}
+/** The `crowded` afternoon, as steps: the oldest first, so the newest are what the ledger leads with. */
+function crowd(s) {
+  const general = (line, times, how = "once") => s.approve(line, times, how, "bash", "general");
+  /** An agent reading a project: each of these asked once, and never again. */
+  for (let i = 1; i <= 101; i++) s.approve(i % 3 === 0 ? `wc -l src/part${i}.ts` : `sed -n ${i},${i + 40}p src/part${i}.ts`, 1);
+  s.approve("git push origin feat/trust", 5);
+  s.approve("rm -rf dist", 4);
+  s.approve("docker compose -p prod down -v", 2);
+  for (const line of ["uniq -c", "wc -l", 'sed "s|^\\./||"', "sort", "sort -rn"]) general(line, 3);
+  general('find packages -type f -not -path "*/dist/*"', 3);
+  general('find site -type f -not -path "site/node_modules/*" -not -path "site/dist/*"', 2);
+  general("find . -path ./.git -prune -o -type f -print", 2);
+  general("head -30", 3);
+  for (const line of ["head -40", "head -80", "head -50", "head -20"]) general(line, 2);
+  general("find . -name '*.md'", 1, "always");
+  general("ls src", 1, "always");
+  s.at(SAMPLE_NOW - 3_600_000);
+  general("cat package.json", 2);
+  s.widen("cat", "general");
+  s.auto("cat package.json", 2, "bash", "general");
+  s.auto("cat src/app.ts", 1, "bash", "general");
+  s.approve("bun --version", 2);
+  s.approve("exit 0", 2);
+  general("exit 1", 2);
+  general("sleep 5", 2);
+  general("echo ---", 3);
+  general("echo boom", 2);
+  s.approve("echo trust-test", 3);
+  s.approve("git status --short", 3);
+  general("git status --short", 2);
+  s.approve("ls -la", 3);
+  general("ls -la", 3);
+  s.at(SAMPLE_NOW - 120_000);
+  s.auto("git status --short", 3);
+  s.auto("echo trust-test", 1);
+  s.auto("ls -la", 1);
+  s.at(SAMPLE_NOW - 2_000);
+  s.pending("git push origin feat/trust");
+}
+
+/** A week of a project, as steps: rules earned early on, answered on most days since, the newest today. */
+function week(s) {
+  const general = (line, times, how = "once") => s.approve(line, times, how, "bash", "general");
+  const hour = 3_600_000;
+  s.at(SAMPLE_NOW - 8 * DAY);
+  s.approve("git status --short", 3);
+  s.approve("echo trust-test", 3);
+  s.approve("bun test", 3);
+  s.approve("src/app.ts", 3, "once", "edit");
+  general("ls -la", 3);
+  general("head -30", 3);
+  general("cat package.json", 2);
+  s.widen("cat", "general");
+  s.at(SAMPLE_NOW - 6 * DAY - 5 * hour);
+  s.auto("git status --short", 1);
+  s.at(SAMPLE_NOW - 4 * DAY - 3 * hour);
+  s.auto("git status --short", 2);
+  s.auto("ls -la", 1, "bash", "general");
+  s.at(SAMPLE_NOW - 3 * DAY - 2 * hour);
+  s.auto("bun test", 1);
+  s.at(SAMPLE_NOW - 2 * DAY - 6 * hour);
+  s.auto("git status --short", 3);
+  s.auto("src/app.ts", 2, "edit");
+  s.at(SAMPLE_NOW - DAY - 4 * hour);
+  s.auto("echo trust-test", 2);
+  s.at(SAMPLE_NOW - DAY + 2 * hour);
+  general("head -40", 2);
+  general("head -60", 2);
+  general("head -80 README.md", 1);
+  general("git status --short -uno", 2);
+  s.approve("bun --version", 2);
+  general("sleep 5", 1);
+  s.approve("git push origin feat/trust", 5);
+  general("find . -name '*.md'", 1, "always");
+  general("sort -rn", 1, "always");
+  for (const once of ["wc -l src/app.ts", "sed -n 1,40p src/app.ts", "pwd"]) s.approve(once, 1);
+  s.at(SAMPLE_NOW - 50 * 60_000);
+  s.auto("cat src/app.ts", 1, "bash", "general");
+  s.at(SAMPLE_NOW - 20 * 60_000);
+  s.auto("git status --short && echo trust-test", 1);
+  s.at(SAMPLE_NOW - 12 * 60_000);
+  s.auto("bun test", 1);
+  s.at(SAMPLE_NOW - 3 * 60_000);
+  s.auto("ls -la", 1, "bash", "general");
+  s.auto("git status --short", 1);
+  s.at(SAMPLE_NOW - 2_000);
+  s.pending("git push origin feat/trust");
+}
+export const SAMPLES = {
+  /** A new install: nothing approved, nothing to say. */
+  empty: () => ({
+    engine: build(() => {})
+  }),
+  /** A first session: one command trusted and answered, one being counted, on screen now. */
+  first: () => ({
+    engine: build(s => {
+      s.approve("git status", 3);
+      s.at(SAMPLE_NOW - 600_000);
+      s.auto("git status", 1);
+      s.approve("docker compose -p cockpit up -d", 2);
+      s.at(SAMPLE_NOW - 1_000);
+      s.pending("docker compose -p cockpit up -d");
+    })
+  }),
+  /**
+   * A busy week, as the activity screen was designed from: rules earned over the week and answered
+   * most days, a family widened by hand, commands one approval away, a dangerous one half way, and an
+   * "always" given to OpenCode itself.
+   */
+  busy: () => ({
+    engine: build(week)
+  }),
+  /** Dangerous commands on their way: each needs eight in a row, and none of their families widens. */
+  dangerous: () => ({
+    engine: build(s => {
+      s.at(SAMPLE_NOW - 2 * DAY);
+      s.approve("git status", 3);
+      s.approve("git push origin feat/trust", 5);
+      s.approve("rm -rf dist", 7);
+      s.approve("docker compose -p prod down -v", 2);
+      s.approve("kubectl delete pod web-0", 3, "once", "bash", "general");
+      s.at(SAMPLE_NOW - 3_600_000);
+      s.auto("git status", 2);
+      s.at(SAMPLE_NOW - 2_000);
+      s.pending("rm -rf dist");
+    })
+  }),
+  /**
+   * Families: three `ls` rules and one answered only because you widened `ls` for general; `echo ---`
+   * (the line a font drew as `echo ──`); one `git status --short` earned by two agents; a dangerous
+   * family that can never be widened; and a tail of commands approved once, folded.
+   */
+  families: () => ({
+    engine: build(s => {
+      s.approve("ls -la", 3, "once", "bash", "general");
+      s.approve("ls -la src", 3, "once", "bash", "general");
+      s.approve("ls -R docs", 2, "once", "bash", "general");
+      s.approve("echo ---", 3, "once", "bash", "general");
+      s.approve("git status --short", 3);
+      s.approve("git status --short", 2, "once", "bash", "general");
+      s.approve("git -C packages/web status", 3);
+      s.approve("git push origin feat/trust", 5);
+      s.approve("docker compose -p cockpit up -d", 3);
+      s.approve("docker compose -p prod down -v", 2);
+      s.approve("src/app.ts", 3, "once", "edit");
+      s.approve("src/view.ts", 2, "once", "edit");
+      for (const once of ["head -60 README.md", "wc -l src/app.ts", "cat package.json", "pwd"]) s.approve(once, 1);
+      s.at(SAMPLE_NOW - 900_000);
+      s.widen("ls", "general");
+      s.at(SAMPLE_NOW - 600_000);
+      s.auto("ls -la", 3, "bash", "general");
+      s.auto("echo ---", 1, "bash", "general");
+      s.auto("git status --short", 2);
+      s.auto("ls -x", 1, "bash", "general");
+    })
+  }),
+  /**
+   * A real afternoon, as a user's screenshots of the ledger showed it: two agents, a hundred commands
+   * approved once, families half trusted and half counting, a family widened by hand, dangerous rules
+   * on their way, a long `find`, the `---` a font merges, and OpenCode's own "always" twice.
+   */
+  crowded: () => ({
+    engine: build(crowd)
+  }),
+  /** The same afternoon, paused: the dialog has to say it before anything else. */
+  "crowded-paused": () => {
+    const engine = build(crowd);
+    engine.load([{
+      v: 1,
+      at: SAMPLE_NOW - 60_000,
+      type: "paused"
+    }]);
+    return {
+      engine
+    };
+  },
+  /** The busy week, paused: still learning, answering nothing — and every surface says so. */
+  paused: () => {
+    const engine = build(week);
+    engine.load([{
+      v: 1,
+      at: SAMPLE_NOW - 60_000,
+      type: "paused"
+    }]);
+    return {
+      engine
+    };
+  },
+  /** The ledger could not be written: the block speaks even with nothing else to say. */
+  trouble: () => ({
+    engine: build(() => {}),
+    trouble: "ledger not saved: EACCES"
+  })
+};

package/dist/core/shell.js

@@ -0,0 +1,253 @@
+/**
+ * A command line, read the way Trust needs it: split into the commands it runs, each as words.
+ *
+ * Not a shell. It has one job and one direction to fail in: anything it cannot read *for certain* —
+ * an expansion, a substitution, a subshell, a heredoc, a program that runs a string it was handed —
+ * comes back `opaque`, and an opaque line is always asked. A reader that guesses would let the one
+ * line it misread be approved by the approvals of another.
+ *
+ * Why not OpenCode's tree-sitter: one runtime dependency per package (docs/building/a-new-bay.md),
+ * and a grammar still has to be told what "cannot be known statically" means — which is this file.
+ */
+
+import { posix } from "node:path";
+class Opaque extends Error {}
+
+/** Programs that run a string, a file or stdin as code: what they do is not on the line. */
+const RUNS_CODE = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish", "eval", "source", ".", "exec"]);
+/** Directory moves that cannot be followed from the text alone. */
+const MOVES = new Set(["pushd", "popd"]);
+/**
+ * Shell grammar, not programs: `while true; do echo tick; sleep 2; done` is one loop, and read word by
+ * word it became four "commands" — `while true`, `do echo tick`, `done` — each counting on its own.
+ * What a loop or a condition runs depends on what it tests, which the text does not settle.
+ */
+const GRAMMAR = new Set(["if", "then", "else", "elif", "fi", "for", "while", "until", "do", "done", "case", "esac", "select", "function", "coproc", "{", "}", "[[", "!"]);
+function tokenize(line) {
+  const tokens = [];
+  let word = "";
+  /** A word can be empty and still exist: `echo ""` has an argument. */
+  let started = false;
+  const flush = () => {
+    if (started) tokens.push({
+      type: "word",
+      text: word
+    });
+    word = "";
+    started = false;
+  };
+  const op = text => {
+    flush();
+    tokens.push({
+      type: "op",
+      text
+    });
+  };
+  const expansion = next => next !== undefined && /[({A-Za-z_0-9!?#@*$-]/.test(next);
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    const next = line[i + 1];
+    if (c === " " || c === "\t") {
+      flush();
+      continue;
+    }
+    if (c === "\n") {
+      op(";");
+      continue;
+    }
+    if (c === "#" && !started) {
+      while (i < line.length && line[i] !== "\n") i++;
+      i--;
+      continue;
+    }
+    if (c === "\\") {
+      if (next === "\n") {
+        i++;
+        continue;
+      }
+      if (next === undefined) throw new Opaque("a trailing backslash");
+      word += next;
+      started = true;
+      i++;
+      continue;
+    }
+    if (c === "'") {
+      const end = line.indexOf("'", i + 1);
+      if (end < 0) throw new Opaque("an unclosed quote");
+      word += line.slice(i + 1, end);
+      started = true;
+      i = end;
+      continue;
+    }
+    if (c === '"') {
+      started = true;
+      let j = i + 1;
+      for (; j < line.length && line[j] !== '"'; j++) {
+        const d = line[j];
+        if (d === "`") throw new Opaque("a command substitution");
+        if (d === "$" && expansion(line[j + 1])) throw new Opaque("an expansion");
+        if (d === "\\" && /[$`"\\\n]/.test(line[j + 1] ?? "")) {
+          word += line[j + 1];
+          j++;
+          continue;
+        }
+        word += d;
+      }
+      if (j >= line.length) throw new Opaque("an unclosed quote");
+      i = j;
+      continue;
+    }
+    if (c === "`") throw new Opaque("a command substitution");
+    if (c === "$" && expansion(next)) throw new Opaque("an expansion");
+    if (c === "(" || c === ")") throw new Opaque("a subshell");
+    if (c === "<" || c === ">") {
+      if (next === "(") throw new Opaque("a process substitution");
+      if (c === "<" && next === "<") throw new Opaque("a heredoc");
+      /** `2>` and `2>&1`: a file descriptor is part of the redirection, not a word of its own. */
+      const fd = /^\d+$/.test(word) ? word : "";
+      if (!fd) flush();
+      word = "";
+      started = false;
+      let redirect = fd + c;
+      if (next === ">" || next === "&") {
+        redirect += next;
+        i++;
+        if (next === "&" && /\d|-/.test(line[i + 1] ?? "")) {
+          redirect += line[i + 1];
+          i++;
+        }
+      }
+      tokens.push({
+        type: "word",
+        text: redirect,
+        redirect: true
+      });
+      continue;
+    }
+    if (c === "&") {
+      if (next === "&") {
+        op("&&");
+        i++;
+      } else if (next === ">") {
+        flush();
+        const redirect = line[i + 2] === ">" ? "&>>" : "&>";
+        tokens.push({
+          type: "word",
+          text: redirect,
+          redirect: true
+        });
+        i += redirect.length - 1;
+      } else op("&");
+      continue;
+    }
+    if (c === "|") {
+      if (next === "|" || next === "&") {
+        op(`|${next}`);
+        i++;
+      } else op("|");
+      continue;
+    }
+    if (c === ";") {
+      op(";");
+      if (next === ";") i++;
+      continue;
+    }
+    word += c;
+    started = true;
+  }
+  flush();
+  return tokens;
+}
+
+/**
+ * Reads a command line into the commands it runs.
+ *
+ * `cd` is not returned as a command — it asks nothing by itself, as in OpenCode — but it moves every
+ * command after it, and that is kept: `cd build && rm -rf *` and `cd /tmp && rm -rf *` are different
+ * lines and must never share an approval.
+ */
+export function parse(line) {
+  let tokens;
+  try {
+    tokens = tokenize(line);
+  } catch (error) {
+    if (error instanceof Opaque) return {
+      kind: "opaque",
+      reason: error.message
+    };
+    throw error;
+  }
+  const commands = [];
+  let cwd;
+  let words = [];
+  let piped = false;
+  const end = after => {
+    const current = words;
+    words = [];
+    if (current.length === 0) return undefined;
+    const split = current.findIndex(w => w.redirect || !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w.text));
+    const env = (split < 0 ? current : current.slice(0, split)).map(w => w.text);
+    const rest = split < 0 ? [] : current.slice(split);
+    const argv = rest.map(w => w.text);
+    const redirects = rest.flatMap((w, i) => w.redirect ? [i] : []);
+    const program = argv[0];
+    if (program !== undefined && RUNS_CODE.has(posix.basename(program))) {
+      return {
+        kind: "opaque",
+        reason: `\`${program}\` runs code that is not on the line`
+      };
+    }
+    if (program !== undefined && GRAMMAR.has(program)) {
+      return {
+        kind: "opaque",
+        reason: `\`${program}\` is a loop or a condition, not a command`
+      };
+    }
+    if (program !== undefined && MOVES.has(program)) {
+      return {
+        kind: "opaque",
+        reason: `\`${program}\` moves where later commands run`
+      };
+    }
+    if (program === "cd" && env.length === 0) {
+      const target = argv[1];
+      if (argv.length > 2 || target === "-" || piped || after === "|" || after === "|&") {
+        return {
+          kind: "opaque",
+          reason: "a `cd` that cannot be followed"
+        };
+      }
+      cwd = target === undefined ? "~" : cwd && !posix.isAbsolute(target) && !target.startsWith("~") ? posix.join(cwd, target) : target;
+      return undefined;
+    }
+    commands.push({
+      env,
+      argv,
+      ...(cwd !== undefined ? {
+        cwd
+      } : {}),
+      ...(redirects.length > 0 ? {
+        redirects
+      } : {})
+    });
+    return undefined;
+  };
+  for (const token of tokens) {
+    if (token.type === "word") {
+      words.push({
+        text: token.text,
+        redirect: token.redirect === true
+      });
+      continue;
+    }
+    const stop = end(token.text);
+    if (stop) return stop;
+    piped = token.text === "|" || token.text === "|&";
+  }
+  const stop = end(undefined);
+  if (stop) return stop;
+  return {
+    kind: "commands",
+    commands
+  };
+}

package/dist/core/signature.js

@@ -0,0 +1,38 @@
+/**
+ * What an approval is an approval *of*.
+ *
+ * A signature is the command exactly as it will run — environment, program, every argument in order,
+ * and where it runs — with quoting normalised so that `echo 'a b'` and `echo "a b"` are one thing.
+ * Nothing is generalised away. OpenCode's own "always" generalises, and measured on its own arity
+ * table, `docker compose -p cockpit up -d` and `docker compose -p prod down -v` both became
+ * `docker compose -p *` (docs/opencode/permissions.md). A signature can only ever match the command
+ * that earned it; making one cover more is something a person does, in the ledger, on purpose.
+ */
+
+import { posix } from "node:path";
+/** Words that need no quotes to read back as themselves. */
+const PLAIN = /^[A-Za-z0-9_@%+=:,./~^-]+$/;
+export function quote(word) {
+  if (PLAIN.test(word)) return word;
+  return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Where a command runs, said relative to the project: `cd /path/to/project && git status` is
+ * `git status`. A directory outside the project stays absolute, so it cannot pass for one inside.
+ */
+export function place(cwd, root) {
+  if (cwd === undefined) return undefined;
+  if (root === undefined || !posix.isAbsolute(cwd)) return posix.normalize(cwd);
+  const relative = posix.relative(root, posix.normalize(cwd));
+  if (relative === "") return undefined;
+  if (relative.startsWith("..") || posix.isAbsolute(relative)) return posix.normalize(cwd);
+  return relative;
+}
+export function signature(command, root) {
+  const where = place(command.cwd, root);
+  /** A redirection is written bare and an argument quoted, so `echo > x` and `echo '>' x` differ. */
+  const ops = new Set(command.redirects ?? []);
+  const words = [...command.env.map(quote), ...command.argv.map((word, i) => ops.has(i) ? word : quote(word))].join(" ");
+  return where === undefined ? words : `(in ${quote(where)}) ${words}`;
+}