@gorlitzer-labs/comb 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# comb
+
+Keep your keys out of your conversations.
+
+You paste a Cloudflare token to an agent so it can do a job. That token is now in
+a transcript file on your disk, in plaintext, forever. Do it enough times and you
+no longer know which credentials are exposed, or which ones to rotate — so you
+rotate none of them.
+
+`comb` is a small front-end over [SOPS](https://github.com/getsops/sops) and
+[age](https://github.com/FiloSottile/age). Secrets are referred to by **name**.
+Values go into a child process's environment and nowhere else: not into a shell,
+not into history, not into the conversation.
+
+```bash
+comb init
+comb set CF_API_TOKEN --url https://dash.cloudflare.com/profile/api-tokens
+comb run --with CF_API_TOKEN -- curl -H "Authorization: Bearer $CF_API_TOKEN" ...
+comb audit
+```
+
+## Why not a secrets server
+
+Infisical and OpenBao are good. They are also a database, a cache, a patch
+cadence, and something that can be down at 3am when an agent needs a key. For one
+person that is overhead you will resent.
+
+SOPS and age are two static binaries and an encrypted file. Identical on macOS
+and Linux, identical in a container. "Self-hosted" is literally true: nothing
+leaves the machine, and there is no host to compromise.
+
+The encrypted store is safe to commit. Put it in a private repo and you get
+versioning and offsite backup for free, plus a history of when each key changed —
+which is the only rotation record anyone actually keeps.
+
+**The cost, stated plainly:** the age private key is the one credential that
+matters. Everything else is recoverable; that is not. Back it up somewhere real.
+
+## Commands
+
+| command | |
+|---|---|
+| `comb init` | create the age key and the encrypted store |
+| `comb set <NAME> [--url <where>]` | take a value without echoing it, and store it |
+| `comb ls` | names, dates and notes — never values |
+| `comb run --with A,B -- <cmd>` | run a command with those secrets in its environment |
+| `comb rotate <NAME>` | tell you where to go, then take the new value |
+| `comb audit` | which secrets leaked into transcripts and shell history |
+| `comb rm <NAME>` | forget one (does **not** revoke it at the provider) |
+
+Values are never printed, never passed as command-line arguments, never logged.
+`comb get NAME --reveal` exists for when you genuinely need to read one, and
+refuses without the flag.
+
+## `comb audit`
+
+This is the half no vault does, and the half that makes manual rotation
+survivable. "Rotate everything just in case" is advice nobody follows twice.
+Knowing that three specific keys are sitting in a transcript turns a day of work
+into ten minutes.
+
+```
+comb audit  scanning 5 place(s) credentials go to be forgotten
+  · Claude transcripts   · Codex sessions   · Codex history
+  · zsh history          · bash history
+
+  LEAKED  CF_API_TOKEN — 2 occurrence(s) across 1 file(s): Claude transcripts
+
+  credential-shaped strings (not necessarily yours):
+  GitHub token — 3 distinct, 3 occurrence(s), 2 file(s)
+  private key block — 1 distinct, 3 occurrence(s), 2 file(s)
+```
+
+Two kinds of finding, and the difference matters:
+
+- **LEAKED** — a value from your own store, found verbatim. Certain.
+- **shaped** — something that looks like a credential by its prefix. Probable,
+  and biased: a GitHub token announces itself with `ghp_`, while a Cloudflare
+  token is forty characters of nothing in particular and cannot be recognised at
+  all. **Finding none proves nothing.**
+
+## Rotation is manual, on purpose
+
+To rotate a credential automatically you need a credential that can rotate
+credentials — a Cloudflare token with Edit-API-Tokens, a GitHub PAT with admin
+scope. That meta-credential is strictly more dangerous than the ones it replaces,
+it lives in the same store, and nothing can rotate *it*. Automating this would
+trade a small risk for a bigger one.
+
+So `comb rotate` does the part a tool should: reminds you where to go, takes the
+new value without echoing it, records when it changed, and leaves revoking the
+old one to you — after you have confirmed the new one works.
+
+## What this does not do
+
+A process that *uses* a secret can *read* it. `comb` cannot stop an agent seeing
+a token you have handed it to work with. What it stops is the token entering a
+conversation, a file, or your shell history in the first place — and it makes
+rotating one cheap enough that you actually do it.
+
+## Across machines — `comb realm`
+
+An agent running on another machine needs credentials too, but the store and its
+key live here. age solves this: a secret can be encrypted to **several
+recipients** at once, each with its own keypair, any one of which decrypts. So
+each realm gets its own age key, the store is encrypted to all of them, and the
+**same encrypted file** can be copied to every realm — over bifrost's sync, or a
+private repo — leaking nothing, because it is ciphertext.
+
+```bash
+# on the realm, once:
+comb init && comb pubkey            # → age1realm…
+
+# here, register it:
+comb realm add zanpakuto age1realm…  # re-encrypts the store to include it
+comb realm ls                        # who can read the store
+comb realm rm zanpakuto              # revoke — re-encrypts WITHOUT it
+```
+
+Revoking a realm re-encrypts the store without its key, so it can no longer
+decrypt the **current** store — no secret has to be rotated.
+
+**The honest limit:** revocation seals the current and future store, not the
+past. A copy of the ciphertext a realm decrypted *while it was a recipient* stays
+readable by that realm — you cannot un-share what was already shared. If a realm
+is actually compromised, revoke it here **and** rotate the secrets it held
+(`comb rotate`), exactly as you would for any exposed credential. Revocation
+stops future leaks; rotation closes the ones already out.
+
+## Requires
+
+`sops` and `age` on PATH (`brew install sops age`, or your package manager).
+Node 20+.
+
+MIT.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@gorlitzer-labs/comb",
+  "version": "0.1.0",
+  "description": "Keep your keys out of your conversations. A small vault front-end over SOPS + age.",
+  "type": "module",
+  "bin": {
+    "comb": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "secrets",
+    "sops",
+    "age",
+    "vault",
+    "ai",
+    "agents",
+    "cli"
+  ],
+  "author": "Franco Berardi"
+}

package/src/audit.mjs

@@ -0,0 +1,104 @@
+/**
+ * Find the secrets you have already leaked.
+ *
+ * This is the half no vault does, and it is the half that makes manual rotation
+ * survivable. Rotating credentials is slow and irreversible-ish, so "rotate
+ * everything, just in case" is advice nobody follows twice. Knowing that three
+ * specific keys appeared in a transcript turns a day of work into ten minutes.
+ *
+ * Agent sessions are the leak nobody watches. A token pasted into a chat is
+ * written to a transcript file and stays there, in plaintext, indefinitely —
+ * long after the conversation is forgotten. Shell history is the same story with
+ * a longer tradition.
+ *
+ * Two kinds of finding, and the difference matters:
+ *
+ *   - EXACT   a value from your own store appears verbatim in a file. Certain.
+ *   - SHAPED  something that looks like a credential by its prefix. Probable,
+ *             and biased: a GitHub token announces itself with `ghp_`, while a
+ *             Cloudflare token is forty characters of nothing in particular and
+ *             cannot be recognised at all. Finding none proves nothing.
+ */
+import { readdirSync, statSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/** Credentials that announce themselves. Deliberately not exhaustive. */
+export const SHAPES = [
+  { name: "GitHub token", rx: /gh[pousr]_[A-Za-z0-9]{20,}/g },
+  { name: "GitHub fine-grained PAT", rx: /github_pat_[A-Za-z0-9_]{20,}/g },
+  { name: "AWS access key id", rx: /AKIA[0-9A-Z]{16}/g },
+  { name: "Slack token", rx: /xox[baprs]-[A-Za-z0-9-]{10,}/g },
+  { name: "Google API key", rx: /AIza[0-9A-Za-z_\-]{30,}/g },
+  { name: "OpenAI key", rx: /sk-[A-Za-z0-9_\-]{20,}/g },
+  { name: "Anthropic key", rx: /sk-ant-[A-Za-z0-9_\-]{20,}/g },
+  { name: "private key block", rx: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+];
+
+/** Where credentials go to be forgotten about. */
+export function defaultTargets(home = homedir()) {
+  return [
+    { label: "Claude transcripts", path: join(home, ".claude", "projects") },
+    { label: "Codex sessions", path: join(home, ".codex", "sessions") },
+    { label: "Codex history", path: join(home, ".codex", "history.jsonl") },
+    { label: "zsh history", path: join(home, ".zsh_history") },
+    { label: "bash history", path: join(home, ".bash_history") },
+  ].filter((t) => existsSync(t.path));
+}
+
+/** Every readable file under a path, capped so a huge tree cannot hang the scan. */
+function* walk(path, budget = { files: 20000 }) {
+  let st;
+  try { st = statSync(path); } catch { return; }
+  if (st.isFile()) { yield path; return; }
+  if (!st.isDirectory()) return;
+  let entries;
+  try { entries = readdirSync(path); } catch { return; }
+  for (const e of entries) {
+    if (budget.files-- <= 0) return;
+    yield* walk(join(path, e), budget);
+  }
+}
+
+/**
+ * Scan for leaks.
+ *
+ * `known` maps name → current value. Those are matched verbatim, which is the
+ * only certain signal available; everything else is a shape and says so.
+ * Values are compared, never returned — a leak report that quotes the secret
+ * has simply moved the leak.
+ */
+export function scan({ targets = defaultTargets(), known = {}, minLength = 16 } = {}) {
+  const exact = new Map();   // name -> { files:Set, hits:number }
+  const shaped = new Map();  // shapeName -> { distinct:Set, hits:number, files:Set }
+
+  const watch = Object.entries(known).filter(([, v]) => typeof v === "string" && v.length >= minLength);
+
+  for (const target of targets) {
+    for (const file of walk(target.path)) {
+      let text;
+      try { text = readFileSync(file, "utf-8"); } catch { continue; }
+
+      for (const [name, value] of watch) {
+        if (!text.includes(value)) continue;
+        const rec = exact.get(name) ?? { files: new Set(), hits: 0, labels: new Set() };
+        rec.hits += text.split(value).length - 1;
+        rec.files.add(file);
+        rec.labels.add(target.label);
+        exact.set(name, rec);
+      }
+
+      for (const shape of SHAPES) {
+        const found = text.match(shape.rx);
+        if (!found) continue;
+        const rec = shaped.get(shape.name) ?? { distinct: new Set(), hits: 0, files: new Set(), labels: new Set() };
+        rec.hits += found.length;
+        for (const f of found) rec.distinct.add(f);
+        rec.files.add(file);
+        rec.labels.add(target.label);
+        shaped.set(shape.name, rec);
+      }
+    }
+  }
+  return { exact, shaped, targets };
+}

package/src/backends/sops.mjs

@@ -0,0 +1,104 @@
+/**
+ * Storage: SOPS + age.
+ *
+ * Chosen for what it is NOT. A secrets server — Infisical, OpenBao — is a
+ * database, a cache, a patch cadence and a thing that can be down at 3am when an
+ * agent needs a key. This is two static binaries and an encrypted file. It runs
+ * the same on a laptop and in a container, which matters because the container
+ * is where the agents live now, and it means "self-hosted" is literally true:
+ * nothing leaves the machine and there is no host to compromise.
+ *
+ * The file is safe to commit. That is the point — an encrypted store in a
+ * private repo gets versioning and offsite backup for free, and the history
+ * shows when each key last changed, which is the only rotation record anyone
+ * actually keeps.
+ *
+ * The cost, stated plainly: the age private key is the one credential that
+ * matters. Everything else is recoverable; that is not. It never goes in the
+ * store, it never goes in the repo.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/** Where the encrypted store and the key live. Override for tests. */
+export function combHome() {
+  return process.env.COMB_HOME ?? join(homedir(), ".comb");
+}
+export const storePath = (home = combHome()) => join(home, "secrets.yaml");
+export const keyPath = (home = combHome()) => join(home, "age.key");
+
+function ageRecipient(home = combHome()) {
+  const key = readFileSync(keyPath(home), "utf-8");
+  const m = key.match(/public key: (age1[a-z0-9]+)/);
+  if (!m) throw new Error("could not read the age public key — is ~/.comb/age.key intact?");
+  return m[1];
+}
+
+/** True once there is a key and a store to talk to. */
+export function initialised(home = combHome()) {
+  return existsSync(keyPath(home)) && existsSync(storePath(home));
+}
+
+export function init(home = combHome()) {
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  if (!existsSync(keyPath(home))) {
+    const gen = spawnSync("age-keygen", { encoding: "utf-8" });
+    if (gen.status !== 0) throw new Error("age-keygen failed — is `age` installed?");
+    writeFileSync(keyPath(home), gen.stdout, { mode: 0o600 });
+    chmodSync(keyPath(home), 0o600);
+  }
+  if (!existsSync(storePath(home))) {
+    // An empty store still has to be encrypted, or the first `set` has nothing
+    // to merge into and sops has no recipient to learn from.
+    writeFileSync(storePath(home), "{}\n");
+    const r = spawnSync("sops", ["--encrypt", "--age", ageRecipient(home), "--in-place", storePath(home)], {
+      encoding: "utf-8",
+      env: { ...process.env },
+    });
+    if (r.status !== 0) throw new Error(`sops could not create the store: ${r.stderr?.trim()}`);
+  }
+  return { home, recipient: ageRecipient(home) };
+}
+
+function sopsEnv(home) {
+  return { ...process.env, SOPS_AGE_KEY_FILE: keyPath(home) };
+}
+
+/** The whole store, decrypted in memory. Never written anywhere. */
+export function readAll(home = combHome()) {
+  if (!initialised(home)) throw new Error("no store yet — run `comb init`");
+  const r = spawnSync("sops", ["--decrypt", "--output-type", "json", storePath(home)], {
+    encoding: "utf-8",
+    env: sopsEnv(home),
+  });
+  if (r.status !== 0) throw new Error(`could not decrypt the store: ${r.stderr?.trim()}`);
+  return JSON.parse(r.stdout || "{}");
+}
+
+/**
+ * Write one entry.
+ *
+ * `sops --set` rather than decrypt-edit-reencrypt: the plaintext store never
+ * exists as a whole, not even for an instant, and not in a temp file.
+ */
+export function writeSecret(name, value, meta = {}, home = combHome()) {
+  const entry = { value, updated: new Date().toISOString(), ...meta };
+  // Subcommand form (`sops set <file> <index> <value>`), not the legacy --set
+  // flag: `unset` only exists as a subcommand, and having the pair disagree is
+  // how you end up with a delete that silently is not one.
+  const r = spawnSync("sops", ["set", storePath(home), `["${name}"]`, JSON.stringify(entry)], {
+    encoding: "utf-8",
+    env: sopsEnv(home),
+  });
+  if (r.status !== 0) throw new Error(`could not write ${name}: ${r.stderr?.trim()}`);
+}
+
+export function deleteSecret(name, home = combHome()) {
+  const r = spawnSync("sops", ["unset", storePath(home), `["${name}"]`], {
+    encoding: "utf-8",
+    env: sopsEnv(home),
+  });
+  if (r.status !== 0) throw new Error(`could not remove ${name}: ${r.stderr?.trim()}`);
+}

package/src/cli.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * comb — keep your keys out of your conversations.
+ *
+ * The problem this exists for: you paste a Cloudflare token to an agent so it
+ * can do a job, and that token is now in a transcript file forever. Do it enough
+ * times and you have no idea which credentials are exposed or which to rotate.
+ *
+ * So: secrets are referred to by NAME, never by value. `comb run` hands the
+ * value to a child process's environment and nowhere else — not to a shell, not
+ * to history, not into the conversation. `comb audit` tells you which ones
+ * escaped anyway, because some already have.
+ *
+ * Rotation stays manual on purpose. Rotating a credential automatically needs a
+ * credential that can rotate credentials — a CF token with Edit-API-Tokens, a
+ * GitHub PAT with admin scope. That meta-credential is strictly more dangerous
+ * than the ones it replaces, lives in the same store, and nothing can rotate it.
+ * `comb rotate` therefore does the part a tool should: tells you where to go,
+ * takes the new value without echoing it, and records when it changed.
+ */
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import * as store from "./backends/sops.mjs";
+import * as realms from "./realms.mjs";
+import { scan, defaultTargets } from "./audit.mjs";
+
+const B = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const say = (s) => process.stdout.write(s + "\n");
+
+/**
+ * Read a secret from the terminal without echoing it.
+ *
+ * Not an argument, deliberately. A value on the command line is in your shell
+ * history, in `ps` output while it runs, and in this conversation if an agent
+ * typed the command — which is the exact leak comb exists to stop.
+ */
+async function promptSecret(label) {
+  if (!process.stdin.isTTY) {
+    // Piped input is fine and is how scripts and agents should feed a value.
+    return (await new Promise((r) => {
+      let d = ""; process.stdin.on("data", (c) => (d += c)); process.stdin.on("end", () => r(d));
+    })).trim();
+  }
+  process.stdout.write(`${label}: `);
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  // Silence the echo: the value should not be on screen, over a shoulder or in
+  // a screen recording.
+  const onData = () => process.stdout.write("\x1b[2K\r" + label + ": ");
+  process.stdin.on("data", onData);
+  const value = await new Promise((r) => rl.question("", r));
+  process.stdin.off("data", onData);
+  rl.close();
+  process.stdout.write("\n");
+  return value.trim();
+}
+
+function help() {
+  say([
+    `${B("comb")} — keep your keys out of your conversations`,
+    "",
+    `  ${B("comb init")}                       create the age key and the encrypted store`,
+    `  ${B("comb set")} <NAME> [--url <where>] take a value without echoing it, and store it`,
+    `  ${B("comb ls")}                         names, age and notes — never values`,
+    `  ${B("comb run")} --with A,B -- <cmd>    run a command with those secrets in its env`,
+    `  ${B("comb rotate")} <NAME>              where to go, then take the new value`,
+    `  ${B("comb audit")}                      which secrets leaked into transcripts and history`,
+    `  ${B("comb realm add")} <name> <age1…>   let a realm's key read the store (re-encrypts)`,
+    `  ${B("comb realm rm")} <name>             revoke a realm (re-encrypts without it)`,
+    `  ${B("comb realm ls")}                    realms that can read the store`,
+    `  ${B("comb pubkey")}                      print THIS machine's age public key`,
+    `  ${B("comb rm")} <NAME>                  forget one`,
+    "",
+    dim("  Values are never printed, never passed as arguments, never logged."),
+    dim("  `comb get NAME --reveal` exists for when you genuinely need to read one."),
+  ].join("\n"));
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+const flags = {}; const pos = [];
+for (let i = 0; i < rest.length; i++) {
+  const a = rest[i];
+  if (a === "--") { flags["--"] = rest.slice(i + 1); break; }
+  if (a.startsWith("--")) {
+    const k = a.slice(2), n = rest[i + 1];
+    if (n === undefined || n.startsWith("--")) flags[k] = true; else { flags[k] = n; i++; }
+  } else pos.push(a);
+}
+
+try {
+  switch (cmd) {
+    case "init": {
+      const { home, recipient } = store.init();
+      say(`${green("✓")} store ready at ${B(home)}`);
+      say(dim(`  public key  ${recipient}`));
+      say(dim(`  private key ${home}/age.key — back this up somewhere safe; nothing else can recover the store`));
+      break;
+    }
+
+    case "set": case "add": {
+      const name = pos[0];
+      if (!name) throw new Error("which one? `comb set CF_API_TOKEN`");
+      const value = await promptSecret(`value for ${name}`);
+      if (!value) throw new Error("nothing entered — not stored");
+      store.writeSecret(name, value, typeof flags.url === "string" ? { url: flags.url } : {});
+      say(`${green("✓")} ${name} stored ${dim(`(${value.length} characters — not shown, not logged)`)}`);
+      break;
+    }
+
+    case "rotate": {
+      const name = pos[0];
+      if (!name) throw new Error("which one? `comb rotate CF_API_TOKEN`");
+      const all = store.readAll();
+      const cur = all[name];
+      if (!cur) throw new Error(`no secret called ${name} — see \`comb ls\``);
+      say(`${B(name)} last changed ${cur.updated ? cur.updated.slice(0, 10) : "unknown"}`);
+      if (cur.url) say(`rotate it here: ${B(cur.url)}`);
+      say(dim("revoke the old one at the provider AFTER the new one is verified working"));
+      const value = await promptSecret(`new value for ${name}`);
+      if (!value) throw new Error("nothing entered — the old value is untouched");
+      store.writeSecret(name, value, cur.url ? { url: cur.url } : {});
+      say(`${green("✓")} ${name} updated. Old value is gone from the store.`);
+      break;
+    }
+
+    case "ls": {
+      const all = store.readAll();
+      const names = Object.keys(all).sort();
+      if (names.length === 0) { say(dim("  nothing stored yet — `comb set NAME`")); break; }
+      say(B("  name                          updated      note"));
+      for (const n of names) {
+        const e = all[n] ?? {};
+        say(`  ${n.padEnd(29)} ${(e.updated ?? "").slice(0, 10).padEnd(12)} ${e.url ?? ""}`);
+      }
+      break;
+    }
+
+    case "get": {
+      const name = pos[0];
+      if (!name) throw new Error("which one?");
+      if (flags.reveal !== true) throw new Error("that prints a secret to your terminal — pass --reveal if you mean it");
+      const all = store.readAll();
+      if (!(name in all)) throw new Error(`no secret called ${name}`);
+      process.stdout.write(all[name].value + "\n");
+      break;
+    }
+
+    case "run": {
+      const want = typeof flags.with === "string" ? flags.with.split(",").map((s) => s.trim()).filter(Boolean) : [];
+      const command = flags["--"] ?? [];
+      if (command.length === 0) throw new Error("what should I run? `comb run --with CF_API_TOKEN -- curl ...`");
+      const all = store.readAll();
+      const env = { ...process.env };
+      for (const n of want) {
+        if (!(n in all)) throw new Error(`no secret called ${n} — see \`comb ls\``);
+        env[n] = all[n].value;
+      }
+      const r = spawnSync(command[0], command.slice(1), { stdio: "inherit", env });
+      process.exit(r.status ?? 1);
+    }
+
+    case "rm": {
+      const name = pos[0];
+      if (!name) throw new Error("which one?");
+      store.deleteSecret(name);
+      say(`${green("✓")} ${name} removed from the store ${dim("(this does NOT revoke it at the provider)")}`);
+      break;
+    }
+
+    case "pubkey": {
+      say(realms.localRecipient());
+      break;
+    }
+
+    case "realm": {
+      const sub = pos[0];
+      if (sub === "add") {
+        const name = pos[1];
+        // key may be an arg, or piped (so it need not sit in shell history)
+        let key = pos[2];
+        if (!key && !process.stdin.isTTY) {
+          key = await new Promise((r) => { let d=""; process.stdin.on("data",c=>d+=c); process.stdin.on("end",()=>r(d.trim())); });
+        }
+        if (!name || !key) throw new Error("usage: comb realm add <name> <age1…>  (key may be piped)");
+        const n = realms.addRealm(name, key);
+        say(`${green("✓")} realm ${B(name)} can now read the store ${dim(`(re-encrypted to ${n} recipients)`)}`);
+      } else if (sub === "rm" || sub === "remove") {
+        const name = pos[1];
+        if (!name) throw new Error("usage: comb realm rm <name>");
+        const n = realms.removeRealm(name);
+        say(`${green("✓")} realm ${B(name)} revoked ${dim(`(store re-encrypted to ${n} recipients; it can no longer decrypt, old copies included)`)}`);
+      } else if (sub === "ls" || sub === undefined) {
+        const list = realms.listRealmRecipients();
+        say(`${B("comb realms")} ${dim("(can read the store, besides this machine)")}`);
+        if (!list.length) say(dim("  none — `comb realm add <name> <age1…>`"));
+        for (const r of list) say(`  ${B(r.name)}  ${dim(r.key.slice(0, 24) + "…")}`);
+      } else {
+        throw new Error(`unknown: comb realm ${sub}`);
+      }
+      break;
+    }
+
+    case "audit": {
+      const known = store.initialised()
+        ? Object.fromEntries(Object.entries(store.readAll()).map(([k, v]) => [k, v?.value]))
+        : {};
+      const targets = defaultTargets();
+      say(`${B("comb audit")} ${dim(`scanning ${targets.length} place(s) credentials go to be forgotten`)}`);
+      for (const t of targets) say(dim(`  · ${t.label}`));
+      say("");
+
+      const { exact, shaped } = scan({ targets, known });
+
+      if (exact.size === 0) say(green("  no stored secret was found verbatim in any of them"));
+      for (const [name, rec] of exact) {
+        say(red(`  LEAKED  ${name}`) + dim(` — ${rec.hits} occurrence(s) across ${rec.files.size} file(s): ${[...rec.labels].join(", ")}`));
+      }
+      say("");
+      if (shaped.size === 0) {
+        say(dim("  nothing credential-shaped found either"));
+      } else {
+        say(B("  credential-shaped strings (not necessarily yours):"));
+        for (const [name, rec] of shaped) {
+          say(yellow(`  ${name}`) + dim(` — ${rec.distinct.size} distinct, ${rec.hits} occurrence(s), ${rec.files.size} file(s): ${[...rec.labels].join(", ")}`));
+        }
+      }
+      say("");
+      say(dim("  A Cloudflare token is 40 characters of nothing in particular and cannot be"));
+      say(dim("  matched by shape. Finding none above does not mean none are there."));
+      break;
+    }
+
+    case undefined: case "help": case "--help": case "-h": help(); break;
+    case "version": case "--version": case "-v": say("comb 0.1.0"); break;
+    default: say(red(`unknown command: ${cmd}`)); help(); process.exit(2);
+  }
+} catch (e) {
+  say(red(`✗ ${e.message}`));
+  process.exit(1);
+}

package/src/realms.mjs

@@ -0,0 +1,81 @@
+// comb across machines: give a realm agent the credentials it needs, without
+// the secrets ever leaving your control.
+//
+// A secret encrypted with age can be encrypted to SEVERAL recipients at once —
+// each with its own keypair, any one of which can decrypt. So each realm gets
+// its own age key, the store is encrypted to all of them, and the SAME encrypted
+// file can be copied to every realm (over bifrost's sync, or a private repo)
+// leaking nothing: it is ciphertext, useless without a key.
+//
+// Revoking a realm is re-encrypting the store WITHOUT its key — no secret has to
+// be rotated, because that realm can no longer decrypt anything, old copies
+// included (its key never changes what the current ciphertext is encrypted to).
+import { execFileSync, spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { combHome, storePath, keyPath } from "./backends/sops.mjs";
+
+export const recipientsDir = (home = combHome()) => join(home, "recipients");
+
+/** A realm's recipient file: just its age public key. */
+const recipientFile = (name, home = combHome()) => join(recipientsDir(home), name);
+
+/** The local store's own public key — always a recipient. */
+export function localRecipient(home = combHome()) {
+  const m = readFileSync(keyPath(home), "utf-8").match(/public key: (age1[a-z0-9]+)/);
+  if (!m) throw new Error("no local age key — run `comb init`");
+  return m[1];
+}
+
+/** Names of every realm registered as a recipient. */
+export function listRealmRecipients(home = combHome()) {
+  const d = recipientsDir(home);
+  if (!existsSync(d)) return [];
+  return readdirSync(d)
+    .filter((n) => /^[A-Za-z0-9_-]+$/.test(n))
+    .map((name) => ({ name, key: readFileSync(join(d, name), "utf-8").trim() }));
+}
+
+/** A public key is well-formed if it's a single age1… recipient. */
+export function isValidAgePubkey(key) {
+  return /^age1[a-z0-9]{20,}$/.test((key || "").trim());
+}
+
+/**
+ * Re-key the store to exactly the current recipient set (local + all realms).
+ *
+ * Runs after any add or remove. `sops updatekeys`-style via rotate add/rm would
+ * need diffing; instead we decrypt with our key and re-encrypt to the full set,
+ * which is simplest and leaves the store readable by precisely those who should.
+ */
+export function rekeyStore(home = combHome()) {
+  const recipients = [localRecipient(home), ...listRealmRecipients(home).map((r) => r.key)];
+  const env = { ...process.env, SOPS_AGE_KEY_FILE: keyPath(home) };
+  // Decrypt to JSON in memory, then re-encrypt to the new recipient set.
+  const dec = spawnSync("sops", ["--decrypt", "--output-type", "json", storePath(home)], { encoding: "utf-8", env });
+  if (dec.status !== 0) throw new Error(`could not decrypt to re-key: ${dec.stderr?.trim()}`);
+  const enc = spawnSync("sops",
+    ["--encrypt", "--age", recipients.join(","), "--input-type", "json", "--output-type", "yaml", "/dev/stdin"],
+    { input: dec.stdout, encoding: "utf-8", env });
+  if (enc.status !== 0) throw new Error(`could not re-encrypt: ${enc.stderr?.trim()}`);
+  writeFileSync(storePath(home), enc.stdout);
+  return recipients.length;
+}
+
+/** Register a realm's public key and re-key the store so it can read secrets. */
+export function addRealm(name, pubkey, home = combHome()) {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error(`invalid realm name: ${JSON.stringify(name)}`);
+  const key = (pubkey || "").trim();
+  if (!isValidAgePubkey(key)) throw new Error("that is not an age public key (expected age1…)");
+  mkdirSync(recipientsDir(home), { recursive: true });
+  writeFileSync(recipientFile(name, home), key + "\n", { mode: 0o644 });
+  return rekeyStore(home);
+}
+
+/** Remove a realm and re-key WITHOUT it — revocation. */
+export function removeRealm(name, home = combHome()) {
+  const f = recipientFile(name, home);
+  if (!existsSync(f)) throw new Error(`no realm recipient called ${name}`);
+  rmSync(f);
+  return rekeyStore(home);
+}