@gorlitzer-labs/comb 0.1.4 → 0.1.6

package/README.md

@@ -60,6 +60,7 @@ matters. Everything else is recoverable; that is not. Back it up somewhere real.
 | `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) |
+| `comb sync <host>` | merge the store with another realm's, both ways, over ssh |
 
 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
@@ -174,9 +175,37 @@ 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.
 
+## Keeping realms in step — `comb sync`
+
+Each realm holds its own copy of the store. `comb sync bankai` merges this
+machine's copy with bankai's, both ways, and writes the one result to both:
+
+- a secret on one side only is copied to the other
+- on both sides, the newer one wins (a rotation propagates)
+- a removal travels: `comb rm` leaves a marker (the name and when, no value),
+  so the next sync deletes it on the other side instead of copying it back
+- a secret changed on **both** sides since the last sync is named in the
+  output; the newer is kept and the other value is gone
+
+Only ciphertext crosses the wire. The other side's store is fetched over ssh,
+decrypted here with this machine's key, merged, re-encrypted to the same
+recipients and written back. The other machine needs only ssh. The sync refuses
+and writes nothing if the two stores are encrypted to different recipients, so
+syncing never adds or revokes a realm. Each sync keeps the timestamps it agreed
+on in `~/.comb/sync/<host>.json`: names and times, never values.
+
+**Upgrade every realm to comb 0.1.6 before relying on it.** An older comb does
+not know the deletion marker: it would list a removed secret as though it were
+still there, with no value.
+
+Why not a private git repo: sops encrypts values, not names, so the repo would
+show which services you use and when you rotated each one, and git keeps every
+old copy of the ciphertext forever. Syncing directly between your own machines
+keeps no history and puts no copy on anyone else's server.
+
 ## Requires
 
-`sops` and `age` on PATH (`brew install sops age`, or your package manager).
+`sops` 3.11+ and `age` on PATH (`brew install sops age`, or your package manager).
 Node 20+.
 
 MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gorlitzer-labs/comb",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Keep your keys out of your conversations. A small vault front-end over SOPS + age.",
   "type": "module",
   "bin": {

package/src/backends/sops.mjs

@@ -62,12 +62,33 @@ export function init(home = combHome()) {
   return { home, recipient: ageRecipient(home) };
 }
 
+// `sops set --value-stdin` arrived in sops 3.11.0. Older sops would need the
+// value as an argument, so refuse rather than fall back to the leak.
+let valueStdinChecked = false;
+export function sopsSupportsValueStdin(versionText) {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(versionText || "");
+  if (!m) return false;
+  const [maj, min] = [Number(m[1]), Number(m[2])];
+  return maj > 3 || (maj === 3 && min >= 11);
+}
+function requireValueStdin() {
+  if (valueStdinChecked) return;
+  const v = spawnSync("sops", ["--version"], { encoding: "utf-8" });
+  if (!sopsSupportsValueStdin(v.stdout)) {
+    throw new Error(`sops 3.11 or newer is needed to store a value without exposing it (found: ${(v.stdout || "none").split("\n")[0].trim()}) — upgrade sops`);
+  }
+  valueStdinChecked = true;
+}
+
 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()) {
+/**
+ * The whole store as it is on disk, decrypted in memory, deletion markers
+ * included. Only `comb sync` needs those; everything else wants readAll.
+ */
+export function readRaw(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",
@@ -77,6 +98,11 @@ export function readAll(home = combHome()) {
   return JSON.parse(r.stdout || "{}");
 }
 
+/** The live secrets, decrypted in memory. Never written anywhere. */
+export function readAll(home = combHome()) {
+  return Object.fromEntries(Object.entries(readRaw(home)).filter(([, e]) => !e?.deleted));
+}
+
 /**
  * Write one entry.
  *
@@ -85,20 +111,38 @@ export function readAll(home = combHome()) {
  */
 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)], {
+  requireValueStdin();
+  // Subcommand form (`sops set <file> <index>`), 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.
+  //
+  // The value goes in on stdin, never as an argument. It used to be the last
+  // argument, which put every secret comb stored into the process table for as
+  // long as sops ran — readable by `ps` from any process on the machine, which
+  // is the exact leak comb exists to stop.
+  const r = spawnSync("sops", ["set", "--value-stdin", storePath(home), `["${name}"]`], {
     encoding: "utf-8",
     env: sopsEnv(home),
+    input: JSON.stringify(entry),
   });
   if (r.status !== 0) throw new Error(`could not write ${name}: ${r.stderr?.trim()}`);
 }
 
+/**
+ * Forget one: the value is erased, and a marker — the name and when — stays.
+ *
+ * Unsetting the key outright used to be enough. With more than one machine it
+ * is not: the next `comb sync` would find the secret on the other side, take it
+ * for one this side had never seen, and copy it straight back. The marker is
+ * what lets a deletion travel. It holds no value, and readAll never shows it.
+ */
 export function deleteSecret(name, home = combHome()) {
-  const r = spawnSync("sops", ["unset", storePath(home), `["${name}"]`], {
+  if (!(name in readAll(home))) throw new Error(`no secret called ${name}`);
+  requireValueStdin();
+  const r = spawnSync("sops", ["set", "--value-stdin", storePath(home), `["${name}"]`], {
     encoding: "utf-8",
     env: sopsEnv(home),
+    input: JSON.stringify({ deleted: true, updated: new Date().toISOString() }),
   });
   if (r.status !== 0) throw new Error(`could not remove ${name}: ${r.stderr?.trim()}`);
 }

package/src/cli.mjs

@@ -22,6 +22,7 @@ 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 { syncWith } from "./sync.mjs";
 import { scan, defaultTargets } from "./audit.mjs";
 import { VERSION, checkAndNotify } from "./update-check.mjs";
 
@@ -72,6 +73,7 @@ function help() {
     `  ${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 sync")} <host>                 merge the store with another realm's, both ways (over ssh)`,
     `  ${B("comb pubkey")}                      print THIS machine's age public key`,
     `  ${B("comb rm")} <NAME>                  forget one`,
     "",
@@ -172,6 +174,23 @@ try {
       break;
     }
 
+    case "sync": {
+      const peer = pos[0];
+      if (!peer) throw new Error("with which machine? `comb sync bankai` (any ssh destination)");
+      const r = syncWith(peer, typeof flags["remote-home"] === "string" ? { remoteHome: flags["remote-home"] } : {});
+      if (!r.changedHere && !r.changedThere) {
+        say(`${green("✓")} already in sync with ${B(peer)} ${dim(`(${r.live} secret(s))`)}`);
+        break;
+      }
+      say(`${green("✓")} synced with ${B(peer)} ${dim(`(${r.live} secret(s), only ciphertext crossed the wire)`)}`);
+      if (r.pulled.length) say(`  ${dim("←")} from ${peer}: ${r.pulled.join(", ")}`);
+      if (r.pushed.length) say(`  ${dim("→")} to ${peer}: ${r.pushed.join(", ")}`);
+      for (const c of r.conflicts) {
+        say(yellow(`  ⚠ ${c.name} changed on both sides since the last sync — kept ${c.kept === "theirs" ? peer + "'s" : "this machine's"} (the newer); the other value is gone`));
+      }
+      break;
+    }
+
     case "pubkey": {
       say(realms.localRecipient());
       break;

package/src/sync.mjs

@@ -0,0 +1,166 @@
+/**
+ * comb sync — one vault on two machines, kept the same both ways.
+ *
+ * A realm can read the store, but each machine still holds its own copy, and a
+ * secret set on one used to stay there until somebody copied the file across —
+ * which also threw away whatever the other side had added. This merges the two.
+ *
+ * What crosses the wire is ciphertext only. The other side's store is fetched
+ * over ssh (`cat`), decrypted HERE with this machine's key (both are recipients
+ * of the same store), merged, re-encrypted to the same recipients, and the one
+ * resulting file is written to both sides. The other machine needs nothing but
+ * ssh: no comb, no sops, no key in use.
+ *
+ * The merge, secret by secret:
+ *   - on one side only          → copied to the other
+ *   - on both, different        → the newer `updated` wins
+ *   - a deletion marker         → wins over an older value, loses to a newer one
+ * Without a record of the last sync, "different" cannot tell an ordinary
+ * rotation from a secret changed on BOTH sides since. So each sync leaves the
+ * timestamps it agreed on (names and times, never values) in sync/<peer>.json;
+ * the next one compares against it and names anything changed on both sides.
+ * The newer still wins — but you are told which one was overwritten.
+ *
+ * It refuses, and writes nothing, when the two stores are not encrypted to the
+ * same recipients: a sync must never be the way a realm is added or revoked.
+ * And it re-reads the other side just before writing, so a change made there
+ * mid-sync is not overwritten.
+ *
+ * Not a ledger, on purpose. A ledger keeps every old value; for secrets the
+ * point of rotating is that the old value is gone.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, readFileSync, rmSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { combHome, storePath, keyPath, readRaw } from "./backends/sops.mjs";
+import { localRecipient } from "./realms.mjs";
+
+const SAFE_PEER = /^[A-Za-z0-9_.@-]+$/;
+const SAFE_PATH = /^[~A-Za-z0-9_./-]+$/;
+
+/** The age recipients a store is encrypted to, read from its sops metadata. */
+export function recipientsOf(ciphertext) {
+  return [...new Set([...(ciphertext || "").matchAll(/recipient:\s*(age1[a-z0-9]+)/g)].map((m) => m[1]))].sort();
+}
+
+// Equal as data, whatever order the keys are in. A byte comparison of the JSON
+// minds order, and the merge sorts by name — so two identical stores used to
+// look changed and both files were rewritten on every sync.
+const canonical = (x) => Array.isArray(x) ? x.map(canonical)
+  : x && typeof x === "object" ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, canonical(x[k])])) : x;
+const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+const stamp = (e) => e?.updated ?? "";
+
+/**
+ * Merge two decrypted stores. Pure: no I/O, so every rule is testable alone.
+ *
+ * `base` is the name → updated map the previous sync agreed on (may be empty).
+ * Returns the merged store and, by name only, what moved and what collided.
+ */
+export function mergeStores(local, remote, base = {}) {
+  const merged = {};
+  const report = { pulled: [], pushed: [], conflicts: [] };
+  const names = [...new Set([...Object.keys(local), ...Object.keys(remote)])].sort();
+  for (const n of names) {
+    const a = local[n], b = remote[n];
+    if (b === undefined) { merged[n] = a; report.pushed.push(n); continue; }
+    if (a === undefined) { merged[n] = b; report.pulled.push(n); continue; }
+    if (same(a, b)) { merged[n] = a; continue; }
+    // Newer wins; on an exact tie keep this side's, so the result is decided.
+    const remoteWins = stamp(b) > stamp(a);
+    merged[n] = remoteWins ? b : a;
+    (remoteWins ? report.pulled : report.pushed).push(n);
+    // Changed on both sides since the last agreed state: say so.
+    if (n in base && stamp(a) !== base[n] && stamp(b) !== base[n]) {
+      report.conflicts.push({ name: n, kept: remoteWins ? "theirs" : "ours" });
+    }
+  }
+  return { merged, report };
+}
+
+function ssh(peer, command, input) {
+  const bin = process.env.COMB_SSH || "ssh";   // overridable for tests
+  return spawnSync(bin, ["-o", "BatchMode=yes", "-o", "ConnectTimeout=10", peer, command],
+    { encoding: "utf-8", input, maxBuffer: 64 * 1024 * 1024 });
+}
+
+function fetch(peer, remoteHome) {
+  const r = ssh(peer, `cat ${remoteHome}/secrets.yaml`);
+  if (r.status !== 0) throw new Error(`could not read ${peer}:${remoteHome}/secrets.yaml — ${r.stderr?.trim() || "ssh failed"}`);
+  return r.stdout;
+}
+
+function decrypt(ciphertext, home) {
+  const dir = mkdtempSync(join(tmpdir(), "comb-sync-"));
+  try {
+    // Ciphertext only: it is safe on disk, and sops wants a file to read.
+    const f = join(dir, "peer.yaml");
+    writeFileSync(f, ciphertext, { mode: 0o600 });
+    const r = spawnSync("sops", ["--decrypt", "--output-type", "json", f],
+      { encoding: "utf-8", env: { ...process.env, SOPS_AGE_KEY_FILE: keyPath(home) } });
+    if (r.status !== 0) throw new Error(`could not decrypt the other side's store with this machine's key: ${r.stderr?.trim()}`);
+    return JSON.parse(r.stdout || "{}");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function encrypt(plain, recipients, home) {
+  // Same as realms.rekeyStore: sops reads a private temp file, never /dev/stdin
+  // (not openable in some non-interactive contexts), and it is wiped at once.
+  const dir = mkdtempSync(join(tmpdir(), "comb-sync-"));
+  try {
+    const f = join(dir, "store.json");
+    writeFileSync(f, JSON.stringify(plain), { mode: 0o600 });
+    const r = spawnSync("sops",
+      ["--encrypt", "--age", recipients.join(","), "--input-type", "json", "--output-type", "yaml", f],
+      { encoding: "utf-8", env: { ...process.env, SOPS_AGE_KEY_FILE: keyPath(home) } });
+    if (r.status !== 0) throw new Error(`could not encrypt the merged store: ${r.stderr?.trim()}`);
+    return r.stdout;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const basePath = (peer, home) => join(home, "sync", `${peer}.json`);
+const readBase = (peer, home) => existsSync(basePath(peer, home)) ? JSON.parse(readFileSync(basePath(peer, home), "utf-8")) : {};
+function writeBase(peer, store, home) {
+  mkdirSync(join(home, "sync"), { recursive: true, mode: 0o700 });
+  // Names and timestamps only — never a value.
+  const stamps = Object.fromEntries(Object.entries(store).map(([n, e]) => [n, stamp(e)]));
+  writeFileSync(basePath(peer, home), JSON.stringify(stamps, null, 1) + "\n", { mode: 0o600 });
+}
+
+/** Sync this machine's store with `peer` (an ssh destination). */
+export function syncWith(peer, { remoteHome = "~/.comb", home = combHome() } = {}) {
+  if (!SAFE_PEER.test(peer)) throw new Error(`not a host comb will pass to ssh: ${JSON.stringify(peer)}`);
+  if (!SAFE_PATH.test(remoteHome)) throw new Error(`not a path comb will pass to ssh: ${JSON.stringify(remoteHome)}`);
+
+  const theirsCipher = fetch(peer, remoteHome);
+  const oursCipher = readFileSync(storePath(home), "utf-8");
+  const ours = recipientsOf(oursCipher), theirs = recipientsOf(theirsCipher);
+  if (!ours.includes(localRecipient(home))) throw new Error("this machine's key is not a recipient of its own store — run `comb init`?");
+  if (!same(ours, theirs)) {
+    throw new Error(`the two stores are encrypted to different recipients (here ${ours.length}, ${peer} ${theirs.length}). ` +
+      "Add or revoke realms on both sides first — sync never changes who can read the store.");
+  }
+
+  const local = readRaw(home), remote = decrypt(theirsCipher, home);
+  const { merged, report } = mergeStores(local, remote, readBase(peer, home));
+  const changedHere = !same(merged, local), changedThere = !same(merged, remote);
+
+  if (changedHere || changedThere) {
+    const out = encrypt(merged, ours, home);
+    if (changedThere) {
+      if (fetch(peer, remoteHome) !== theirsCipher) throw new Error(`${peer} changed its store during the sync — nothing was written; run it again`);
+      const tmp = `${remoteHome}/secrets.yaml.comb-sync`;
+      const w = ssh(peer, `umask 077 && cat > ${tmp} && mv ${tmp} ${remoteHome}/secrets.yaml`, out);
+      if (w.status !== 0) throw new Error(`could not write ${peer}'s store — nothing changed here: ${w.stderr?.trim()}`);
+    }
+    if (changedHere) writeFileSync(storePath(home), out);
+  }
+  writeBase(peer, merged, home);
+  const live = Object.values(merged).filter((e) => !e?.deleted).length;
+  return { ...report, changedHere, changedThere, live };
+}