@opencode-cockpit/trust 0.0.0 → 0.8.0

package/dist/core/keys.js

@@ -0,0 +1,149 @@
+/**
+ * What a permission request is a request *for*, as the things an approval can be counted against.
+ *
+ * Each permission type has its own notion of "the same thing again":
+ *
+ * | permission | one subject per | e.g. |
+ * | --- | --- | --- |
+ * | `bash` (v2 `shell`) | command, by its exact signature | `git status`, `(in web) bun test` |
+ * | `edit` | file path | `src/app.ts` |
+ * | `webfetch` | host | `docs.example.com` |
+ * | `task` (v2 `subagent`) | agent type | `explore` |
+ * | `external_directory`, `doom_loop` | — never answered | |
+ * | anything else | the request's patterns, together | `opencode_read_mcp_resource` `*` |
+ *
+ * The key a count is kept under is the subject *and* the permission *and* the agent: trust earned
+ * by `build` running `git push` is not trust for `general` to run it.
+ */
+
+import { dangerOf } from "./danger.js";
+import { canonical } from "./rules.js";
+import { parse } from "./shell.js";
+import { signature } from "./signature.js";
+
+/** A permission request, whichever OpenCode asked it (see `adapt/`). */
+
+/** Everything about the call that the request itself does not carry. */
+
+/** Permissions Trust never answers: they exist to make a person look. */
+const NEVER = {
+  external_directory: "outside the project — always yours to answer",
+  doom_loop: "the agent is repeating itself — always yours to answer"
+};
+
+/** A command's words as OpenCode's patterns spell them: for matching config, not for counting. */
+const written = command => [...command.env, ...command.argv].join(" ");
+function bash(request, context) {
+  if (context.line === undefined) return {
+    kind: "opaque",
+    why: "the command line was not available"
+  };
+  const parsed = parse(context.line);
+  if (parsed.kind === "opaque") return {
+    kind: "opaque",
+    why: parsed.reason
+  };
+  const subjects = parsed.commands.map(command => {
+    const placed = withWorkdir(command, context.workdir);
+    const danger = dangerOf(placed);
+    return {
+      subject: signature(placed, context.root),
+      texts: [written(command)],
+      ...(danger ? {
+        danger
+      } : {})
+    };
+  });
+  if (subjects.length === 0) return {
+    kind: "opaque",
+    why: "nothing on the line runs"
+  };
+  return {
+    kind: "subjects",
+    subjects,
+    patterns: request.patterns
+  };
+}
+
+/** The tool's working directory, under any `cd` the line made. */
+function withWorkdir(command, workdir) {
+  if (!workdir) return command;
+  if (!command.cwd) return {
+    ...command,
+    cwd: workdir
+  };
+  if (command.cwd.startsWith("/") || command.cwd.startsWith("~")) return command;
+  return {
+    ...command,
+    cwd: `${workdir.replace(/\/+$/, "")}/${command.cwd}`
+  };
+}
+function host(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.host || undefined;
+  } catch {
+    return undefined;
+  }
+}
+export function subjectsOf(request, context) {
+  const permission = canonical(request.permission);
+  const never = NEVER[permission];
+  if (never) return {
+    kind: "never",
+    why: never
+  };
+  if (permission === "bash") return bash(request, context);
+  if (request.patterns.length === 0) return {
+    kind: "opaque",
+    why: "the request names nothing"
+  };
+  if (permission === "webfetch") {
+    const subjects = [];
+    for (const url of request.patterns) {
+      const name = host(url);
+      if (!name) return {
+        kind: "opaque",
+        why: `not a URL: ${url}`
+      };
+      subjects.push({
+        subject: name,
+        texts: [url]
+      });
+    }
+    return {
+      kind: "subjects",
+      subjects: dedupe(subjects),
+      patterns: request.patterns
+    };
+  }
+  if (permission === "edit" || permission === "task") return {
+    kind: "subjects",
+    subjects: dedupe(request.patterns.map(p => ({
+      subject: p,
+      texts: [p]
+    }))),
+    patterns: request.patterns
+  };
+  return {
+    kind: "subjects",
+    subjects: [{
+      subject: request.patterns.join(" "),
+      texts: [...request.patterns]
+    }],
+    patterns: request.patterns
+  };
+}
+
+/** Two patterns naming one host or one file are one subject; config is checked against both. */
+function dedupe(subjects) {
+  const by = new Map();
+  for (const subject of subjects) {
+    const known = by.get(subject.subject);
+    if (known) known.texts.push(...subject.texts);else by.set(subject.subject, {
+      ...subject,
+      texts: [...subject.texts]
+    });
+  }
+  return [...by.values()];
+}

package/dist/core/ledger.js

@@ -0,0 +1,202 @@
+/**
+ * The ledger: what happened, one event per line, and what it adds up to.
+ *
+ * Append-only on purpose. Several OpenCode windows on one project write to the same file, and a
+ * whole line appended in one write is the only update that needs no lock: nothing is ever rewritten,
+ * so no window can undo another's. The state is never stored — it is a fold over the events, so it
+ * cannot drift from them, and a rule's history ("approved 3×, rejected once, approved again") is
+ * there to read rather than summarised away.
+ *
+ * Reading is forgiving in exactly one way: a line cut short by a crash is skipped, and a line written
+ * after it (which then starts mid-line) is recovered. Anything else that does not parse is ignored —
+ * a ledger you edited by hand should cost you a rule, not the bay.
+ */
+
+import { canonical } from "./rules.js";
+
+/** What every event about one request carries. */
+
+/** One subject's standing, under one permission and one agent. */
+
+/** An "always" a person gave OpenCode itself: broader than it looks, and gone when OpenCode stops. */
+
+/** A family you trusted as a whole, for one agent under one permission. */
+
+export const DAY = 86_400_000;
+export const emptyState = () => ({
+  entries: new Map(),
+  widened: new Map(),
+  always: [],
+  paused: false,
+  settled: new Set()
+});
+export const keyOf = (permission, agent, subject) => JSON.stringify([canonical(permission), agent, subject]);
+function entry(state, permission, agent, item, at) {
+  const key = keyOf(permission, agent, item.subject);
+  let found = state.entries.get(key);
+  if (!found) {
+    found = {
+      key,
+      permission: canonical(permission),
+      agent,
+      subject: item.subject,
+      streak: 0,
+      approvals: 0,
+      autos: 0,
+      firstAt: at,
+      lastAt: at
+    };
+    state.entries.set(key, found);
+  }
+  if (item.danger) found.danger = item.danger;else delete found.danger;
+  return found;
+}
+const expired = (found, at, options) => options.expireMs > 0 && found.lastAt > 0 && at - found.lastAt > options.expireMs;
+export function apply(state, event, options) {
+  switch (event.type) {
+    case "asked":
+      return state;
+    case "approved":
+    case "rejected":
+    case "auto":
+      {
+        if (state.settled.has(event.request)) return state;
+        state.settled.add(event.request);
+        for (const item of event.items) {
+          const found = entry(state, event.permission, event.agent, item, event.at);
+          if (event.type === "rejected") {
+            found.streak = 0;
+            found.rejectedAt = event.at;
+            continue;
+          }
+          if (expired(found, event.at, options)) found.streak = 0;
+          if (event.type === "approved") {
+            found.streak++;
+            found.approvals++;
+          } else found.autos++;
+          found.lastAt = Math.max(found.lastAt, event.at);
+        }
+        if (event.type === "approved" && event.always?.length) state.always.push({
+          at: event.at,
+          session: event.session,
+          permission: canonical(event.permission),
+          agent: event.agent,
+          patterns: event.always
+        });
+        return state;
+      }
+    case "revoked":
+      {
+        const found = state.entries.get(keyOf(event.permission, event.agent, event.subject));
+        if (found) {
+          found.streak = 0;
+          found.revokedAt = event.at;
+        }
+        return state;
+      }
+    case "widened":
+      {
+        const key = keyOf(event.permission, event.agent, event.family);
+        state.widened.set(key, {
+          key,
+          permission: canonical(event.permission),
+          agent: event.agent,
+          family: event.family,
+          at: event.at
+        });
+        return state;
+      }
+    case "unwidened":
+      state.widened.delete(keyOf(event.permission, event.agent, event.family));
+      return state;
+    case "paused":
+      state.paused = true;
+      return state;
+    case "resumed":
+      state.paused = false;
+      return state;
+  }
+}
+export function applyAll(state, events, options) {
+  for (const event of events) apply(state, event, options);
+  return state;
+}
+
+/* ─── standing ───────────────────────────────────────────────────────────────────────────────── */
+
+export function needFor(danger, settings) {
+  return settings.threshold + (danger ? settings.dangerExtra : 0);
+}
+
+/** Where a subject stands now. `danger` is today's reading, which wins over the one stored. */
+export function standing(found, danger, settings, now) {
+  const need = needFor(danger, settings);
+  if (!found) return {
+    have: 0,
+    need,
+    trusted: false,
+    expired: false
+  };
+  const gone = settings.expireDays > 0 && now - found.lastAt > settings.expireDays * DAY;
+  const have = gone ? 0 : found.streak;
+  return {
+    have,
+    need,
+    trusted: have >= need,
+    expired: gone
+  };
+}
+
+/* ─── the file ───────────────────────────────────────────────────────────────────────────────── */
+
+const TYPES = new Set(["asked", "approved", "rejected", "auto", "revoked", "widened", "unwidened", "paused", "resumed"]);
+function asEvent(value) {
+  if (!value || typeof value !== "object") return undefined;
+  const raw = value;
+  if (raw.v !== 1 || typeof raw.at !== "number" || typeof raw.type !== "string" || !TYPES.has(raw.type)) return undefined;
+  if (raw.type === "revoked") return typeof raw.permission === "string" && typeof raw.agent === "string" && typeof raw.subject === "string" ? raw : undefined;
+  if (raw.type === "widened" || raw.type === "unwidened") return typeof raw.permission === "string" && typeof raw.agent === "string" && typeof raw.family === "string" ? raw : undefined;
+  if (raw.type === "paused" || raw.type === "resumed") return raw;
+  if (typeof raw.request !== "string" || typeof raw.permission !== "string" || typeof raw.agent !== "string" || !Array.isArray(raw.items) || !raw.items.every(item => item && typeof item.subject === "string")) return undefined;
+  return raw;
+}
+function parseLine(line) {
+  try {
+    return asEvent(JSON.parse(line));
+  } catch {
+    /**
+     * A writer that died mid-line leaves no newline, so the next event is appended onto the remains:
+     * `{"v":1,"at":17…{"v":1,"at":18…}`. The last event start in the line is the whole one.
+     */
+    const at = line.lastIndexOf('{"v":1');
+    if (at <= 0) return undefined;
+    try {
+      return asEvent(JSON.parse(line.slice(at)));
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+/**
+ * Events in `text`, and what is left after the last newline. The rest is not an error: it is a line
+ * another window is still writing, read again next time.
+ */
+export function parseLines(text) {
+  const end = text.lastIndexOf("\n");
+  const whole = end < 0 ? "" : text.slice(0, end);
+  const rest = end < 0 ? text : text.slice(end + 1);
+  const events = [];
+  for (const line of whole.split("\n")) {
+    if (line.trim() === "") continue;
+    const event = parseLine(line);
+    if (event) events.push(event);
+  }
+  return {
+    events,
+    rest
+  };
+}
+
+/** One line of the file. Never contains a newline, whatever a subject holds. */
+export const serialize = event => `${JSON.stringify(event)}\n`;

package/dist/core/paths.js

@@ -0,0 +1,38 @@
+/**
+ * Where a project's ledger lives on disk.
+ *
+ * Pure: creates nothing, reads nothing, and takes its environment as an argument — as Review's
+ * `core/store/paths.ts` does, which this mirrors.
+ *
+ * **Outside the project.** What you have approved is about you, not the work; a ledger in the repo
+ * would turn up in `git status` and, worse, travel to everyone who clones it — trust you earned would
+ * answer for them.
+ *
+ * **Keyed by the project's full path.** The readable part is the last two segments, which tells two
+ * checkouts apart at a glance but not for certain (`~/a/web` and `~/b/web`); a short hash of the whole
+ * path makes it certain, so one checkout's trust can never answer in another.
+ */
+
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Anything that is not plainly a filename becomes a dash. */
+export function slug(text) {
+  const cleaned = text.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 60);
+  return cleaned.length > 0 ? cleaned : "unnamed";
+}
+export function projectSlug(directory) {
+  const parts = directory.split("/").filter(Boolean);
+  return slug(parts.slice(-2).join("-"));
+}
+export function shortHash(text) {
+  return createHash("sha256").update(text).digest("hex").slice(0, 8);
+}
+export function trustPaths(directory, env = process.env) {
+  const base = env.COCKPIT_HOME ?? join(env.XDG_DATA_HOME ?? join(env.HOME ?? homedir(), ".local", "share"), "opencode-cockpit");
+  const dir = join(base, "trust", `${projectSlug(directory)}-${shortHash(directory)}`);
+  return {
+    dir,
+    events: join(dir, "events.ndjson")
+  };
+}

package/dist/core/policy.js

@@ -0,0 +1,128 @@
+/**
+ * Whether Trust answers a request, and why — a pure function of the request, what config says, and
+ * what the ledger adds up to.
+ *
+ * The order of the questions is the design:
+ *
+ * 1. **Can it be read?** A command line with `$(…)` in it, a permission that exists to make a person
+ *    look (`external_directory`, `doom_loop`): asked, and nothing is counted.
+ * 2. **Did you ask to be asked?** A specific `ask` rule in config matching any part of the request
+ *    holds all of it. So does a `deny`, though OpenCode never lets one reach us.
+ * 3. **Is every part trusted, or allowed by config?** One untrusted command in a line is enough to
+ *    ask: `git status && rm -rf build` is not half-approved. A part is trusted by its own count, or
+ *    by a family you widened for this agent — unless it is one a widening never covers (dangerous,
+ *    writing a file, running another program: `family.outside`). Config's `ask` was settled in 2, so
+ *    it still wins over a widening.
+ *
+ * The answer always carries what an approval of the request would count towards, so a person's
+ * approval of a request Trust declined is counted against exactly what Trust looked at.
+ */
+
+import { familyOf, outside } from "./family.js";
+import { subjectsOf } from "./keys.js";
+import { keyOf, standing } from "./ledger.js";
+import { describeRule, gate } from "./rules.js";
+const left = why => ({
+  answer: false,
+  why,
+  items: [],
+  progress: []
+});
+export function decide(input) {
+  const {
+    request,
+    context,
+    agent,
+    rules,
+    state,
+    settings,
+    now
+  } = input;
+  const keyed = subjectsOf(request, context);
+  if (keyed.kind !== "subjects") return left(keyed.why);
+  for (const text of [...keyed.subjects.flatMap(subject => subject.texts), ...keyed.patterns]) {
+    const said = gate(rules, request.permission, text);
+    if (said.kind === "held") return left(said.rule.action === "deny" ? `config denies it: ${describeRule(said.rule)}` : `you asked to be asked: ${describeRule(said.rule)}`);
+  }
+  const progress = [];
+  for (const subject of keyed.subjects) {
+    /** Allowed by config, all of it: not Trust's to count, and no reason to ask. */
+    if (subject.texts.every(text => gate(rules, request.permission, text).kind === "allowed")) continue;
+    const found = state.entries.get(keyOf(request.permission, agent, subject.subject));
+    const where = standing(found, subject.danger, settings, now);
+    const via = where.trusted ? undefined : widenedFor(state, request.permission, agent, subject.subject);
+    progress.push({
+      subject: subject.subject,
+      ...(subject.danger ? {
+        danger: subject.danger
+      } : {}),
+      have: where.have,
+      need: where.need,
+      trusted: where.trusted || via !== undefined,
+      ...(via !== undefined ? {
+        via
+      } : {})
+    });
+  }
+  const items = progress.map(({
+    subject,
+    danger
+  }) => danger ? {
+    subject,
+    danger
+  } : {
+    subject
+  });
+
+  /**
+   * OpenCode asked, yet by our reading config allows every part: the readings disagree, and when
+   * they do the person decides.
+   */
+  if (progress.length === 0) return left("config allows all of it by our reading — yours to answer");
+  const short = progress.filter(each => !each.trusted);
+  if (short.length > 0) {
+    const worst = short.reduce((a, b) => b.need - b.have > a.need - a.have ? b : a);
+    return {
+      answer: false,
+      why: progress.length === 1 ? `${worst.have}/${worst.need} approvals in a row` : `${short.length} of ${progress.length} not yet trusted (${worst.subject} ${worst.have}/${worst.need})`,
+      items,
+      progress
+    };
+  }
+  if (state.paused) return {
+    answer: false,
+    why: "Trust is paused in this project",
+    items,
+    progress
+  };
+  const only = progress[0];
+  /** An answer records which widening gave it, so the ledger can say "any ls" answered `ls -R`. */
+  const answered = progress.map(({
+    subject,
+    danger,
+    via
+  }) => ({
+    subject,
+    ...(danger ? {
+      danger
+    } : {}),
+    ...(via !== undefined ? {
+      via
+    } : {})
+  }));
+  const widened = progress.filter(each => each.via !== undefined);
+  return {
+    answer: true,
+    why: progress.length === 1 ? only.via !== undefined ? `in a family you widened: ${only.via}` : `approved by you ${only.have}× in a row${only.danger ? ` (dangerous: ${only.danger})` : ""}` : widened.length > 0 ? `all ${progress.length} commands trusted (${widened.length} by a family you widened)` : `all ${progress.length} commands approved enough times in a row`,
+    items: answered,
+    progress
+  };
+}
+
+/** The family this subject is answered through, when you widened it for this agent and it covers it. */
+function widenedFor(state, permission, agent, subject) {
+  if (state.widened.size === 0) return undefined;
+  const family = familyOf(permission, subject);
+  if (!state.widened.has(keyOf(permission, agent, family))) return undefined;
+  return outside(permission, subject) === undefined ? family : undefined;
+}

package/dist/core/rules.js

@@ -0,0 +1,152 @@
+/**
+ * What `opencode.json` says about a permission, read the way OpenCode reads it.
+ *
+ * Trust only ever sees the gap config left open (docs/opencode/permissions.md): `deny` never emits an
+ * event and `allow` never needs one. Inside that gap there are two kinds of "ask", and telling them
+ * apart is this file's job:
+ *
+ * - **a catch-all** — `"bash": "ask"`, `{ "bash": { "*": "ask" } }`, or no rule at all — is a default:
+ *   "I have not decided about these". Trust may fill it.
+ * - **a specific pattern set to ask** — `"git push *": "ask"` — is a decision: "always ask me about
+ *   this one". Trust never answers it.
+ *
+ * Matching is OpenCode's own: its wildcard (`*` any run, `?` one character, and a trailing ` *` that
+ * also matches nothing, so `ls *` covers `ls`), evaluated over the ordered rules, last match wins.
+ * The merge across files is OpenCode's too — v1 hands over the merged config; v2 hands over its
+ * documents in priority order, and concatenating their rules in that order keeps "last match wins"
+ * meaning what it meant.
+ */
+
+/**
+ * One name per permission, whichever OpenCode asked. v2 renamed several (measured in 2.0.18's own
+ * table: `bash → shell`, `task → subagent`, `write`/`patch → edit`); a rule written for one must
+ * still match a request from the other.
+ */
+const CANONICAL = {
+  shell: "bash",
+  subagent: "task",
+  write: "edit",
+  patch: "edit",
+  apply_patch: "edit",
+  multiedit: "edit"
+};
+export const canonical = permission => CANONICAL[permission] ?? permission;
+
+/** OpenCode's `Wildcard.match`, as in `util/wildcard.ts`. */
+export function match(text, pattern) {
+  const subject = text.replaceAll("\\", "/");
+  let escaped = pattern.replaceAll("\\", "/").replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  // "ls *" covers both "ls" and "ls -la".
+  if (escaped.endsWith(" .*")) escaped = `${escaped.slice(0, -3)}( .*)?`;
+  return new RegExp(`^${escaped}$`, "s").test(subject);
+}
+const ACTIONS = new Set(["allow", "deny", "ask"]);
+const isAction = value => typeof value === "string" && ACTIONS.has(value);
+const obj = value => value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+
+/**
+ * OpenCode 1's `permission` block: `"ask"` for everything, `{ bash: "ask" }` for one permission, or
+ * `{ bash: { "git push *": "ask" } }` for patterns. Key order is rule order.
+ */
+function fromV1(permission) {
+  if (isAction(permission)) return [{
+    permission: "*",
+    pattern: "*",
+    action: permission
+  }];
+  const block = obj(permission);
+  if (!block) return [];
+  const rules = [];
+  for (const [name, value] of Object.entries(block)) {
+    if (isAction(value)) rules.push({
+      permission: canonical(name),
+      pattern: "*",
+      action: value
+    });else for (const [pattern, action] of Object.entries(obj(value) ?? {})) if (isAction(action)) rules.push({
+      permission: canonical(name),
+      pattern,
+      action
+    });
+  }
+  return rules;
+}
+
+/** OpenCode 2's `permissions`: an ordered list of `{ action, resource, effect }`. */
+function fromV2(permissions) {
+  if (!Array.isArray(permissions)) return [];
+  return permissions.flatMap(entry => {
+    const rule = obj(entry);
+    if (!rule || typeof rule.action !== "string" || typeof rule.resource !== "string" || !isAction(rule.effect)) return [];
+    return [{
+      permission: canonical(rule.action),
+      pattern: rule.resource,
+      action: rule.effect
+    }];
+  });
+}
+
+/** Every rule one config document holds at its top level, in order. */
+function own(config) {
+  return [...fromV1(config.permission), ...fromV2(config.permissions)];
+}
+
+/** The rules an agent adds on top: v1 `agent.<name>.permission` (and the older `mode`), v2 `agents`. */
+function agentRules(config, agent) {
+  if (!agent) return [];
+  const rules = [];
+  for (const key of ["mode", "agent", "agents"]) {
+    const entry = obj(obj(config[key])?.[agent]);
+    if (entry) rules.push(...own(entry));
+  }
+  return rules;
+}
+
+/**
+ * The rules in force for an agent, from whatever `config.get` returned: v1's merged config, or v2's
+ * list of documents (`{ type: "document", info }`, lowest priority first). The agent's rules come last
+ * because OpenCode lays them over the global ones.
+ */
+export function rulesFrom(config, agent) {
+  const documents = Array.isArray(config) ? config.flatMap(entry => {
+    const info = obj(obj(entry)?.info);
+    return info ? [info] : [];
+  }) : obj(config) ? [obj(config)] : [];
+  return [...documents.flatMap(own), ...documents.flatMap(document => agentRules(document, agent))];
+}
+
+/** The rule that decides `text` for `permission`, as OpenCode picks it: the last that matches. */
+export function evaluate(rules, permission, text) {
+  const name = canonical(permission);
+  return rules.findLast(rule => match(name, rule.permission) && match(text, rule.pattern));
+}
+
+/**
+ * What config means for one pattern of a request.
+ *
+ * `open` — nothing decided it, or a catch-all said ask: Trust's to fill.
+ * `allowed` — config allows it; the request asked because of something else in it.
+ * `held` — you asked to be asked (a specific `ask`), or config denies it: Trust stays out.
+ */
+
+export function gate(rules, permission, text) {
+  const rule = evaluate(rules, permission, text);
+  if (!rule) return {
+    kind: "open"
+  };
+  if (rule.action === "allow") return {
+    kind: "allowed",
+    rule
+  };
+  if (rule.action === "ask" && rule.pattern === "*") return {
+    kind: "open"
+  };
+  return {
+    kind: "held",
+    rule
+  };
+}
+
+/** A rule as you would have written it, for a reason shown to you. */
+export function describeRule(rule) {
+  return rule.pattern === "*" ? `"${rule.permission}": "${rule.action}"` : `"${rule.pattern}": "${rule.action}"`;
+}