agent-dag 3.13.0 → 3.15.0

package/src/server/index.mjs

@@ -16,7 +16,9 @@ import { claudeConfigDir } from "./claude-dir.mjs";
 import { CODEX_HOME, CODEX_SESSIONS_DIR, STOP, walkRolloutDays } from "./codex-dir.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { createBlockNotifier } from "./block-notify.mjs";
-import { DEFAULTS as PREF_DEFAULTS, notificationsOn, notificationsVetoed, readPrefs, writePrefs } from "./deck-prefs.mjs";
+import { DEFAULTS as PREF_DEFAULTS, notificationsOn, notificationsVetoed, publicPrefs, readPrefs, writePrefs } from "./deck-prefs.mjs";
+import { createEngine, defaultName } from "./lan-engine.mjs";
+import { suggestPassphrase } from "./lan-sync.mjs";
 import { notify as osNotify } from "./browser-react.mjs";
 import { invokedName, renameNotice } from "./invoked-as.mjs";
 import { appendLogLine, codexCwdInWorkspace, electWriters, foldsCase, writesCodexLog } from "./log-writer.mjs";
@@ -3169,7 +3171,10 @@ function redactDeckToken(raw) {
  * same freshness every other cross-deck setting has.
  */
 let _prefs = { ...PREF_DEFAULTS };
-readPrefs().then(p => { _prefs = p; }).catch(() => {});
+// And LAN sync starts from the same read, so a deck that had it on comes back
+// with it on. `applyLanPrefs` is defined below — this runs after module
+// evaluation, which is what makes the forward reference fine.
+readPrefs().then(async p => { _prefs = p; await applyLanPrefs(); }).catch(() => {});
 
 const blockNotifier = createBlockNotifier({
   notify: osNotify,
@@ -3197,7 +3202,11 @@ const blockNotifier = createBlockNotifier({
 function prefsPayload() {
   return {
     ok: true,
-    prefs: _prefs,
+    // `publicPrefs`, never `_prefs`. This route answers anything that can reach
+    // the loopback port, and the LAN group passphrase is in the stored object —
+    // one field, and sending it here would put it in front of every page on the
+    // machine. What goes out is whether one is set.
+    prefs: publicPrefs(_prefs),
     notificationsAllowed: notificationsOn(_prefs),
     notificationsVetoed: notificationsVetoed(),
   };
@@ -3214,9 +3223,113 @@ async function handlePrefsWrite(req, res) {
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
   _prefs = await writePrefs(body);
+  // The engine reads its settings from here rather than holding its own copy,
+  // so turning the switch off in the panel really does stop the sockets rather
+  // than only changing what the panel says.
+  await applyLanPrefs();
   return send(res, 200, prefsPayload());
 }
 
+// ── LAN sync ────────────────────────────────────────────────────────────────
+//
+// The engine is built once and told the settings; it opens and closes its own
+// sockets as those change. Nothing here touches a credential — see
+// lan-engine.mjs, which passes an opaque blob between two claude-swap commands.
+const lanEngine = createEngine({
+  readAccounts: async () => {
+    const { fetchClaudeAccounts } = await import("./claude-accounts.mjs");
+    return fetchClaudeAccounts();
+  },
+  exportAccount: async num => {
+    const { shareAccounts } = await import("./cswap-admin.mjs");
+    const out = await shareAccounts([String(num)]);
+    return out?.ok ? out.blob : null;
+  },
+  importAccount: async blob => {
+    const { importAccount } = await import("./cswap-admin.mjs");
+    // NO `force`, ever, and this is the line where that promise is kept. A
+    // plain import adds an account that is missing and replaces exactly one
+    // claude-swap has quarantined; it SKIPS one that is present and healthy.
+    // So a peer cannot overwrite a working credential of this deck's even by
+    // lying about its own, because the flag that would allow it is not passed.
+    const out = await importAccount(blob);
+    return !!out?.ok;
+  },
+  // The deck's own public id, kept so a restart is the same deck rather than a
+  // new row in every peer's list. Written once, on the first start that has
+  // none — not a secret, and in every beacon this deck sends.
+  onIdentity: async id => {
+    try {
+      _prefs = await writePrefs({ lan: { deckId: id } });
+      // AND PUT IT TO WORK. Writing it alone was not enough: a clash was
+      // detected, a new id was stored, and both decks kept broadcasting the old
+      // one — so they stayed invisible to each other with a correct file on
+      // disk. `apply` restarts only when the id it is holding differs from the
+      // one it is given, so this settles after one pass rather than looping.
+      await applyLanPrefs();
+    } catch { /* the next start picks it up; a shared id is the cost until then */ }
+  },
+  onError: (what, err) => {
+    // Reported, never thrown. A machine with no route, a firewall that refuses
+    // the bind, an interface that comes and goes with a VPN — none of them is a
+    // reason for the deck to fall over.
+    if (what !== "other-group") console.error(`${PRODUCT}: lan sync (${what}):`, err?.message ?? err);
+  },
+});
+
+/** Push whatever is in prefs at the engine. Called at boot and after every
+ *  write, so there is one source of truth and it is the file. */
+async function applyLanPrefs() {
+  const lan = _prefs?.lan ?? {};
+  try {
+    await lanEngine.apply({
+      enabled: !!lan.enabled,
+      name: lan.name || defaultName(),
+      passphrase: lan.passphrase || "",
+      shared: Array.isArray(lan.shared) ? lan.shared : [],
+      deckId: lan.deckId || "",
+    });
+    // Wholesale, so removing an address in the panel really stops it being
+    // dialled rather than only taking the row away.
+    lanEngine.setPeers(lan.manual);
+  } catch (err) {
+    console.error(`${PRODUCT}: lan sync could not start:`, err?.message ?? err);
+  }
+}
+
+/** What the panel draws: the switch, this deck's own name and address, and who
+ *  else is in the group. No passphrase, for the reason prefsPayload gives. */
+function handleLanStatus(req, res) {
+  return send(res, 200, { ok: true, ...lanEngine.status() });
+}
+
+/**
+ * A strong group passphrase, for the field to open with.
+ *
+ * THE WHOLE FEATURE'S SECURITY IS THIS STRING — groupKey scrypts it and
+ * everything else hangs off that — and until this route existed the field
+ * opened empty under a placeholder reading "the same words on every deck",
+ * which is an invitation to type something two people can both remember.
+ * suggestPassphrase has been written, documented and tested since the first
+ * commit of the feature and was reachable from nothing.
+ *
+ * Generated per request rather than folded into the status route, because the
+ * status route is polled every five seconds and a suggestion that changed
+ * under somebody's fingers while they read it out loud would be worse than no
+ * suggestion at all.
+ */
+function handleLanSuggest(req, res) {
+  return send(res, 200, { ok: true, passphrase: suggestPassphrase() });
+}
+
+/** Ask every peer now rather than at the next tick — the button beside the
+ *  list, for somebody who has just fixed a login on the other machine and does
+ *  not want to wait a minute to see it arrive. */
+async function handleLanSync(req, res) {
+  const done = await lanEngine.round();
+  return send(res, 200, { ok: true, done, ...lanEngine.status() });
+}
+
 function pushEvent(raw, source, opts = {}) {
   // First, before anything below can see it: the deck's own credential does not
   // belong in a store that is served without one. Every entry point to the
@@ -5444,6 +5557,9 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     // Machine state, not session state: sampled on the server's own timer and
     // deliberately kept out of the event stream. See src/server/system-metrics.mjs.
     if (req.method === "GET"  && url.pathname === "/api/prefs")        return handlePrefsRead(req, res);
+    if (req.method === "GET"  && url.pathname === "/api/lan")          return handleLanStatus(req, res);
+    if (req.method === "GET"  && url.pathname === "/api/lan/passphrase") return handleLanSuggest(req, res);
+    if (req.method === "POST" && url.pathname === "/api/lan/sync")     return guard(handleLanSync(req, res), res);
     if (req.method === "POST" && url.pathname === "/api/prefs")        return guard(handlePrefsWrite(req, res), res);
     if (req.method === "GET"  && url.pathname === "/api/system")       return send(res, 200, systemSnapshot());
     // On demand only — the process list costs a subprocess on every platform,

package/src/server/lan-engine.mjs

@@ -0,0 +1,359 @@
+// The thing that actually heals an account: the beacon, the listener and
+// claude-swap, wired together.
+//
+// The two files under this one hold everything that can be reasoned about
+// without a network — lan-sync.mjs decides, lan-socket.mjs carries — and what
+// is left here is the part that has to touch the store. It is deliberately the
+// smallest of the three.
+//
+// WHAT ONE ROUND LOOKS LIKE, from a deck whose copy of an account has died:
+//
+//   1. it hears a beacon from a deck with the same group tag
+//   2. it dials that deck's sync port and both sides prove the passphrase
+//   3. it asks for a manifest: which accounts, and does each one work THERE
+//   4. `plan()` says "heal a@@1" — mine is quarantined, theirs is alive
+//   5. it asks for that one account, with a fresh proof naming it
+//   6. the peer runs `cswap export - --account N`, seals it, sends it
+//   7. it opens the envelope and runs `cswap import -`
+//
+// Steps 6 and 7 are the only ones that touch a credential, and neither of them
+// reads one: claude-swap does the reading and the writing, this passes an
+// opaque blob between two of its commands. That is the same division the manual
+// share already uses, which is why this needed no new credential handling at
+// all.
+//
+// NOTHING HAPPENS ON A SCHEDULE THAT MOVES A CREDENTIAL. The manifest round is
+// periodic and carries no credential; the transfer happens when a plan has
+// something in it, which is when an account is actually broken. A deck whose
+// accounts all work talks to its peers every minute and never asks for
+// anything.
+import { accountKey, manifestFor, open, plan, seal, stillListed, transferChallenge } from "./lan-sync.mjs";
+import { connectToPeer, createBeacon, createSyncServer, sendFrame } from "./lan-socket.mjs";
+import { fingerprint, groupKey } from "./lan-sync.mjs";
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+import { hostname, networkInterfaces } from "node:os";
+
+/** How often a deck asks its peers what they have. A minute is far more often
+ *  than a login dies, and it is what makes the panel's list feel live rather
+ *  than something that updates when you press a button. */
+export const SYNC_MS = 60_000;
+
+/** How long one peer round may take before it is abandoned. A manifest is one
+ *  round trip on a local network; anything past this is a peer that is not
+ *  going to answer, and holding the attempt open would stall the next round. */
+export const ROUND_MS = 10_000;
+
+
+/**
+ * The name everybody knows this deck by.
+ *
+ * PERSISTED, and the first version was not. It regenerated on every start, on
+ * the argument that a stored key is one more secret to protect — and that
+ * argument was about the wrong thing, because this is not a key. Nothing is
+ * signed with it and nothing is decrypted with it; the group passphrase is what
+ * authenticates, and this is only an identifier, broadcast in the clear in
+ * every beacon. There is nothing here to steal.
+ *
+ * What regenerating it cost was measured rather than guessed: on a machine
+ * where decks had been restarted a few times, every peer's list held a row per
+ * restart — dozens of them, each reporting ECONNREFUSED every minute against a
+ * port nothing has listened on for an hour. Remembered forever and never
+ * recognised again is the worst of both, and a stable id is the whole fix.
+ */
+export function newIdentity(stored) {
+  if (typeof stored === "string" && /^[0-9a-f]{12}$/.test(stored)) {
+    return { fp: stored.replace(/(.{3})(?=.)/g, "$1-"), id: stored };
+  }
+  const { publicKey } = generateKeyPairSync("x25519");
+  const raw = publicKey.export({ type: "spki", format: "der" });
+  const fp = fingerprint(raw);
+  return { fp, id: fp.replace(/-/g, "") };
+}
+
+/** What this machine calls itself when the user has not said. The hostname,
+ *  because that is the word they already use for this machine everywhere else. */
+export function defaultName() {
+  return hostname().replace(/\.local$/i, "") || "this machine";
+}
+
+/**
+ * EVERY address another deck might dial, for the panel to print.
+ *
+ * It returned the first one, and that was wrong the first time somebody
+ * checked: on this machine the first is 192.168.1.82 and the deck it needs to
+ * reach is on Tailscale at 100.67.32.58, so the panel would have offered an
+ * address that peer cannot route to and left them to work out why.
+ *
+ * WHICH ONE IS RIGHT DEPENDS ON WHERE THE PEER IS, which this side cannot
+ * answer — a VPN, a second NIC, a container bridge, all real and all at once.
+ * So it offers them all and the person picks: they are the only one who knows
+ * how the other machine sees this one, and a list of two is a smaller ask than
+ * a wrong answer.
+ *
+ * `internal` is node's word for loopback, and a link-local 169.254 address is a
+ * machine whose DHCP failed — reachable by nobody worth telling about.
+ */
+export function localAddresses(faces = networkInterfaces()) {
+  const out = [];
+  for (const list of Object.values(faces ?? {})) {
+    for (const n of list ?? []) {
+      if (n.internal) continue;
+      if (n.family !== "IPv4" && n.family !== 4) continue;
+      if (typeof n.address !== "string" || n.address.startsWith("169.254.")) continue;
+      if (!out.includes(n.address)) out.push(n.address);
+    }
+  }
+  return out;
+}
+
+/**
+ * One deck's LAN sync, from settings to a healed account.
+ *
+ * `deps` is every side effect: reading accounts, exporting one, importing one.
+ * Injected rather than imported so a test can run a whole round — two engines,
+ * two fake stores, one real socket pair — without claude-swap on the machine.
+ */
+export function createEngine({
+  readAccounts, exportAccount, importAccount,
+  onChange, onError, onIdentity, now = Date.now,
+} = {}) {
+  let cfg = { enabled: false, name: defaultName(), passphrase: "", shared: [], deckId: "" };
+  let identity = null;
+  let beacon = null;
+  let server = null;
+  let timer = null;
+  let key = null;
+  /** What the last round did, for the panel. Not a log: one line per peer, most
+   *  recent only, because "what happened" is a question about now. */
+  const lastRound = new Map();
+
+  /** This deck's accounts in the shape the rules want. Read through the same
+   *  function the panel uses, so a row can never be alive here and dead there. */
+  const localAccounts = async () => {
+    const got = await readAccounts();
+    return (got?.accounts ?? []).map(a => ({
+      key: accountKey(a.email, a.orgUuid),
+      email: a.email,
+      alive: a.alive === true,
+      num: a.num,
+    }));
+  };
+
+  /** Frames from a peer that has proved the passphrase. Nothing reaches this
+   *  before that, which is the whole point of where the check sits. */
+  const serve = async (msg, ctx) => {
+    try {
+      if (msg.t === "manifest") {
+        const accounts = await localAccounts();
+        return ctx.send({ t: "manifest", accounts: manifestFor(accounts, cfg.shared) });
+      }
+      if (msg.t === "want") {
+        // A SECOND PROOF, for the one operation that moves a credential. The
+        // session says who connected; this says they are asking for this
+        // account, now. A long-lived connection authenticated an hour ago is
+        // not a statement about now.
+        const want = transferChallenge(key, {
+          nonce: msg.nonce, accountKey: msg.key, fromFp: ctx.peerFp, toFp: identity.fp,
+        });
+        if (typeof msg.proof !== "string" || msg.proof !== want) {
+          return ctx.send({ t: "no", why: "proof" });
+        }
+        // Only what the user ticked, checked again here rather than trusted
+        // from the manifest we sent: the list can change between the two, and
+        // the answer that matters is the one at the moment of sending.
+        if (!cfg.shared.includes(msg.key)) return ctx.send({ t: "no", why: "not shared" });
+        const accounts = await localAccounts();
+        const mine = accounts.find(a => a.key === msg.key);
+        if (!mine || !mine.alive) return ctx.send({ t: "no", why: "not mine to give" });
+        const blob = await exportAccount(mine.num);
+        if (!blob) return ctx.send({ t: "no", why: "export failed" });
+        const aad = `${identity.fp}->${ctx.peerFp}|${msg.key}`;
+        return ctx.send({ t: "have", key: msg.key, sealed: seal(key, blob, aad) });
+      }
+    } catch (err) {
+      onError?.("serve", err);
+      ctx.send({ t: "no", why: "error" });
+    }
+  };
+
+  /** Ask one peer what it has, and heal whatever it can heal. */
+  const roundWith = async peer => {
+    let conn = null;
+    try {
+      conn = await connectToPeer({ host: peer.addr, port: peer.port, fp: identity.fp, key, timeoutMs: ROUND_MS });
+      const ask = frame => new Promise((resolve, reject) => {
+        const bell = setTimeout(() => reject(new Error("peer went quiet")), ROUND_MS);
+        bell.unref?.();
+        let buf = "";
+        const onData = chunk => {
+          buf += chunk;
+          const i = buf.indexOf("\n");
+          if (i === -1) return;
+          clearTimeout(bell);
+          conn.sock.off("data", onData);
+          try { resolve(JSON.parse(buf.slice(0, i))); } catch { reject(new Error("bad reply")); }
+        };
+        conn.sock.on("data", onData);
+        sendFrame(conn.sock, frame);
+      });
+
+      const theirs = await ask({ t: "manifest" });
+      if (theirs?.t !== "manifest" || !Array.isArray(theirs.accounts)) throw new Error("no manifest");
+      const mine = await localAccounts();
+      // Only accounts I have also ticked. Sharing is mutual by construction:
+      // a peer cannot push an account at me that I never agreed to hold.
+      // A HEAL NEEDS MY TICK; AN ADD DOES NOT, and the asymmetry is deliberate.
+      // Healing replaces a slot I already have, so it is only reasonable for an
+      // account I said I share. Adding is the case the owner asked for by name:
+      // an account that appears in the group appears everywhere in it, which is
+      // the whole of "I do not want to paste blobs any more". The group is
+      // passphrase-gated, so what can reach this is what somebody I trusted
+      // with that passphrase chose to offer.
+      const wanted = plan(mine, theirs.accounts)
+        .filter(step => step.action === "add" || cfg.shared.includes(step.key));
+      const done = [];
+      for (const step of wanted) {
+        const nonce = randomBytes(12).toString("hex");
+        const reply = await ask({
+          t: "want", key: step.key, nonce,
+          proof: transferChallenge(key, {
+            nonce, accountKey: step.key, fromFp: identity.fp, toFp: conn.peerFp,
+          }),
+        });
+        if (reply?.t !== "have" || !reply.sealed) { done.push({ ...step, ok: false, why: reply?.why ?? "refused" }); continue; }
+        const blob = open(key, reply.sealed, `${conn.peerFp}->${identity.fp}|${step.key}`);
+        if (!blob) { done.push({ ...step, ok: false, why: "could not open" }); continue; }
+        const ok = await importAccount(blob);
+        done.push({ ...step, ok: !!ok, why: ok ? null : "import failed" });
+      }
+      lastRound.set(peer.fp, { at: now(), name: peer.name, offered: theirs.accounts.length, done });
+      if (done.length) onChange?.();
+      return done;
+    } catch (err) {
+      lastRound.set(peer.fp, { at: now(), name: peer.name, error: err.message });
+      return [];
+    } finally {
+      conn?.sock?.destroy();
+    }
+  };
+
+  /** Peers the user typed in, which the beacon will never find.
+   *
+   *  Broadcast dies at the first router and is dropped by a switch that
+   *  filters it, so a deck across a VPN or on another subnet is unreachable by
+   *  discovery and perfectly reachable by address. The passphrase remains the
+   *  only gate, so an address is not a way in — it is a way to be dialled.
+   *
+   *  Keyed by `host:port` rather than by fingerprint, because a fingerprint is
+   *  what a deck says about itself after the handshake and this list has to
+   *  exist before there has been one. */
+  const manual = new Map();
+
+  const round = async () => {
+    if (!beacon) return [];
+    const all = [];
+    // Heard first, typed second, and a typed one is skipped when the beacon
+    // already found that address: otherwise a deck that is both would be dialled
+    // twice a round and its work counted twice.
+    // The same rule the list uses. A deck that has been silent for a day is not
+    // dialled once a minute forever on the chance it comes back.
+    const heard = [...beacon.peers.values()].filter(p => stillListed(p, now()));
+    const seen = new Set(heard.map(p => `${p.addr}:${p.port}`));
+    for (const peer of [...heard, ...[...manual.values()].filter(p => !seen.has(`${p.addr}:${p.port}`))]) {
+      // Sequential rather than parallel. The store takes one mutation at a
+      // time anyway (cswap-admin's lock), and two peers healing the same
+      // account at once would race for a slot number claude-swap assigns as
+      // max+1 without a lock of its own.
+      all.push(...await roundWith(peer));
+    }
+    return all;
+  };
+
+  return {
+    async apply(next) {
+      const was = cfg;
+      cfg = { ...cfg, ...next };
+      const restart = !was.enabled !== !cfg.enabled
+        || was.passphrase !== cfg.passphrase
+        || was.name !== cfg.name
+        || was.deckId !== cfg.deckId;
+      if (!restart) return;
+      this.stop();
+      if (!cfg.enabled || !cfg.passphrase) return;
+      key = groupKey(cfg.passphrase);
+      identity = newIdentity(cfg.deckId);
+      // Hand the caller an id to keep when there was none, so the next start is
+      // the same deck rather than a new row in everybody's list.
+      if (identity.id !== cfg.deckId) onIdentity?.(identity.id);
+      server = createSyncServer({ fp: identity.fp, name: cfg.name, key, handlers: serve, onError });
+      const port = await server.start();
+      beacon = createBeacon({
+        port, name: cfg.name, fp: identity.fp, key,
+        onPeer: () => onChange?.(),
+        // Take a new name and keep it. Two decks with one id are invisible to
+        // each other forever otherwise, and the second one to notice moving is
+        // enough — whichever notices first, moves.
+        onIdClash: () => {
+          const fresh = newIdentity();
+          onIdentity?.(fresh.id);
+          onError?.("id-clash", new Error("another deck was using this one's id; taking a new one"));
+        },
+        onError, now,
+      });
+      await beacon.start();
+      timer = setInterval(() => { void round(); }, SYNC_MS);
+      timer.unref?.();
+    },
+    round,
+    /** Dial this address on every round from now on. Returns false for an
+     *  address that is not one, rather than storing a row that can never
+     *  connect and reports an error every minute forever. */
+    addPeer(addr, port) {
+      const p = Number(port);
+      if (typeof addr !== "string" || !addr.trim() || !Number.isInteger(p) || p < 1 || p > 65_535) return false;
+      const host = addr.trim();
+      manual.set(`${host}:${p}`, { fp: `manual:${host}:${p}`, name: host, addr: host, port: p, manual: true });
+      return true;
+    },
+    removePeer(addr, port) { return manual.delete(`${String(addr).trim()}:${Number(port)}`); },
+    /** Replace the typed list wholesale, which is what a settings write means.
+     *  Adding one at a time would leave a removed address still being dialled
+     *  every minute until the next restart — the row would vanish from the
+     *  panel while the socket kept opening, which is the worst of both. */
+    setPeers(entries) {
+      manual.clear();
+      for (const entry of Array.isArray(entries) ? entries : []) {
+        const at = String(entry).lastIndexOf(":");
+        if (at > 0) this.addPeer(String(entry).slice(0, at), Number(String(entry).slice(at + 1)));
+      }
+      return manual.size;
+    },
+    status() {
+      return {
+        enabled: !!cfg.enabled,
+        running: !!beacon,
+        name: cfg.name,
+        fp: identity?.fp ?? null,
+        // The address and port a person on another subnet types into the other
+        // deck's field. Null when this machine has no ordinary one, which the
+        // panel says rather than printing a placeholder.
+        port: server?.port() ?? null,
+        addrs: beacon ? localAddresses() : [],
+        shared: [...cfg.shared],
+        // The rule is stillListed's, in lan-sync.mjs, where it can be tested.
+        peers: beacon ? [...beacon.peers.values(), ...manual.values()]
+          .filter(p => stillListed(p, now()))
+          .map(p => ({ ...p, last: lastRound.get(p.fp) ?? null })) : [],
+      };
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = null;
+      beacon?.stop();
+      server?.stop();
+      beacon = null;
+      server = null;
+      key = null;
+    },
+  };
+}