ccdeck 3.29.11 → 3.31.0

package/src/server/lan-call.mjs

@@ -0,0 +1,239 @@
+// The calling half: dial a deck, prove this one, check that deck's proof back,
+// and hand over the connection — with the sentence each refusal from the far
+// end is read as. Lifted out of lan-socket.mjs, which re-exports it; the
+// answering half stays there, and the line both halves speak is lan-lines.mjs's.
+import net from "node:net";
+import { cleanName } from "./lan-sync.mjs";
+import {
+  challengeFor, ephemeralPair, frameChannel, handshakeTranscript, mixesEphemeral, proof, proofOk, readChallenge,
+  readEphemeral, readPub, sealsFrames, sessionKey,
+} from "./lan-wire.mjs";
+import { inviteProof, inviteProofBack } from "./lan-invite.mjs";
+import { frameReader, sendFrame, HANDSHAKE_MS } from "./lan-lines.mjs";
+
+/**
+ * What each refusal reason means, in a sentence the LAN panel can print.
+ *
+ * At module scope so it is one object rather than one per frame, and named so
+ * the `Object.hasOwn` guard below reads as the rule it is rather than as
+ * punctuation. The keys are the protocol's, not a user's.
+ */
+const REFUSALS = Object.freeze({
+  pending: "waiting for the other deck to accept this one",
+  declined: "that deck said no",
+  "invite only": "that deck pairs only by invite",
+  // Sent back to a caller that said it was not asking, so the far end's answer
+  // is about the caller's own setting — the same words its own round uses.
+  "not asking": "this deck pairs only by invite",
+  impostor: "that deck has this one pinned under a different key",
+  "wrong invite": "that deck did not take this invite — ask them for a new one",
+  "bad proof": "the other deck refused this one's proof",
+});
+
+/**
+ * The calling half: connect, prove, be proved to, then talk.
+ *
+ * BOTH SIDES PROVE, and the second half is the one that is easy to skip. A
+ * handshake where only the caller proves itself stops a stranger reading a
+ * manifest and stops nothing else — a stranger can still stand up a listener on
+ * the announced port, wait for a real deck to dial it, and be handed whatever
+ * that deck was going to say. So this checks the reply with the same care the
+ * server checks the hello, and gives up if it does not hold.
+ */
+export function connectToPeer({
+  host, port, fp, pub, secret, name, myPort = null, code = null, timeoutMs = HANDSHAKE_MS,
+  /** False when this deck is reaching an address it already had WITHOUT asking
+   *  to pair — an invite-only deck's round. Sent only when false, so every other
+   *  hello is byte-for-byte what it was, and a deck that predates the field
+   *  reads past it the way it reads past `epk`. */
+  ask = true,
+  /** The public key we pinned for this deck the first time, or null for a deck
+   *  we are meeting — an address somebody typed. */
+  expectPub = null,
+  /** Whether the deck that minted `code` said it will prove it holds one too.
+   *  From the token's own `pb`, which is the only way to tell a deck that will
+   *  not from a deck that cannot — see mintInvite. False leaves this path
+   *  exactly as it shipped, for a token minted by an older deck. */
+  inviteProvesBack = false,
+  /** Whether this deck seals every frame after the handshake with a deck that
+   *  says it does too — see frameChannel. False announces nothing and seals
+   *  nothing, exactly as every deck before #810 dials; only the suite asks. */
+  sealFrames = true,
+  /** Whether this deck mixes a key pair made for the connection into its key,
+   *  with a deck that says it does too — see sessionKey. False dials exactly
+   *  as a deck of #810's version does; only the suite asks. */
+  ephemeral = true,
+}) {
+  return new Promise((resolve, reject) => {
+    const myChallenge = challengeFor({ seals: sealFrames, ephemeral });
+    // Made before the other deck is heard from, because the public half goes
+    // in the hello. Let go of once the key is derived — unused, when the deck
+    // that answers turns out not to mix — and on every way out below.
+    let mine = mixesEphemeral(myChallenge) ? ephemeralPair() : null;
+    const myEpk = mine?.pub;
+    const sock = net.createConnection({ host, port });
+    sock.setEncoding("utf8");
+    let settled = false;
+    const fail = err => {
+      if (settled) return;
+      settled = true;
+      mine = null;
+      sock.destroy();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    };
+    const timer = setTimeout(() => fail(new Error("handshake timed out")), timeoutMs);
+    timer.unref?.();
+
+    sock.on("error", fail);
+    sock.on("close", () => fail(new Error("peer closed the connection")));
+    sock.on("connect", () => {
+      // No proof in the hello: the caller cannot cover a challenge it has not
+      // been given, and a proof over an empty one would be a proof that means
+      // nothing. It goes in message three.
+      // `port` is where WE listen, which is not the port this socket came from
+      // — that one is ephemeral and useless to dial. Without it a deck can
+      // accept an incoming request and still have no way to reach back, so the
+      // pairing is mutual on paper and one-way in fact.
+      // `epk` is this connection's key pair, offered: a deck from before #1120
+      // reads past a field it does not know, and one of this version answers.
+      sendFrame(sock, {
+        t: "hello", fp, pub, name, port: myPort, challenge: myChallenge, ...(myEpk ? { epk: myEpk } : {}),
+        ...(ask === false ? { ask: false } : {}),
+      });
+    });
+
+    let theirChallenge = null;
+    let theirFp = null;
+    let theirPub = null;
+    let key = null;
+    /** What the key was derived over; the invite proofs are made over it too. */
+    let transcript = null;
+
+    /** Step 2, answered: the listener's challenge, checked against the pin,
+     *  and this deck's proof back — with the connection's key derived first. */
+    const challenge = msg => {
+      if (theirFp || !readChallenge(msg.challenge)) return fail(new Error("bad challenge"));
+      const them = readPub(msg.pub);
+      if (!them || them.fp !== msg.fp) return fail(new Error("bad challenge"));
+      // THE PIN, CHECKED BEFORE ANYTHING ELSE. A deck we have paired with is
+      // this key and no other; a key that does not match is not a peer whose
+      // details changed, it is a different machine at the same address.
+      if (expectPub && expectPub !== them.pub) {
+        return fail(new Error("a different deck is answering at that address"));
+      }
+      theirChallenge = msg.challenge;
+      theirFp = them.fp;
+      theirPub = them.pub;
+      // Mixed when both challenges say so, as at the listener, and then the
+      // listener's key is required: a deck of this version that says it
+      // mixes and sends no key is not an older deck, it is a deck whose key
+      // was taken out on the way. Refused, and never read the old way.
+      const mixing = mixesEphemeral(myChallenge) && mixesEphemeral(theirChallenge);
+      const theirEphemeral = mixing ? readEphemeral(msg.epk) : null;
+      if (mixing && !theirEphemeral) return fail(new Error("bad challenge"));
+      transcript = mixing
+        ? handshakeTranscript(fp, theirFp, myChallenge, theirChallenge, myEpk, theirEphemeral)
+        : handshakeTranscript(fp, theirFp, myChallenge, theirChallenge);
+      try {
+        key = sessionKey(secret, theirPub, transcript,
+          mixing ? { role: "caller", priv: mine.priv, peer: theirEphemeral } : null);
+      } catch {
+        return fail(new Error("bad challenge"));
+      } finally {
+        // Used or not, the private half goes now.
+        mine = null;
+      }
+      sendFrame(sock, {
+        t: "auth",
+        proof: proof(key, {
+          challenge: myChallenge, peerChallenge: theirChallenge,
+          fromFp: fp, toFp: theirFp, direction: "hello",
+        }),
+        // Only when joining on an invite. Sent in the same frame as the
+        // session proof so a deck that holds a token is paired in one round
+        // trip rather than being queued behind somebody else's press.
+        ...(code ? { invite: inviteProof(code, transcript) } : {}),
+      });
+    };
+
+    /** Step 4: the listener's own proof — and the invite's, when this deck is
+     *  joining on one — and then the connection, handed to whoever dialled. */
+    const ok = msg => {
+      // The same deck that gave us the challenge, or nothing: a reply naming a
+      // different fingerprint is a second party in the middle of this.
+      //
+      // AND A CHALLENGE FIRST. `theirFp` is null until one is accepted, so an
+      // `ok` sent as the very first frame with `fp: null` matched it — null is
+      // null — and walked into `proof` with no key, which throws. Before #1146
+      // that throw ended the deck, and this end dials whatever address a beacon
+      // announces; since #1146 the reader catches it as "bad frame". Neither is
+      // the answer: an `ok` before a challenge is out of order, and says so.
+      if (msg.t !== "ok" || !theirFp || !key || msg.fp !== theirFp) return fail(new Error("expected ok"));
+      const want = proof(key, {
+        challenge: theirChallenge, peerChallenge: myChallenge,
+        fromFp: theirFp, toFp: fp, direction: "reply",
+      });
+      if (!proofOk(want, msg.proof)) return fail(new Error("that deck could not prove its own key"));
+      // AND THAT IT IS THE DECK THE INVITE NAMED. The proof above is about a
+      // key the responder chose a moment ago; this one is about a code it had
+      // to have been given. `join` has no pin to pass, so `expectPub` above is
+      // null on this path and this is the only check that distinguishes the
+      // deck whose owner minted the token from whatever else is reachable at
+      // one of the ten addresses the token happens to carry.
+      //
+      // The caller giving up here is not the end of the attempt: `join` walks
+      // the rest of the list, so a deck answering at a stale or borrowed
+      // address costs one failed address instead of winning the whole token.
+      if (code && inviteProvesBack) {
+        const back = inviteProofBack(code, transcript);
+        if (!proofOk(back, msg.inviteProof)) {
+          return fail(new Error("that deck does not hold the invite"));
+        }
+      }
+      // Sealed from here when both challenges said so. The listener decided
+      // the same at the same moment from the same two strings, and the proof
+      // just checked is what says it saw the same two. See frameChannel.
+      const chan = sealsFrames(myChallenge) && sealsFrames(theirChallenge) ? frameChannel(key, "caller") : null;
+      settled = true;
+      clearTimeout(timer);
+      sock.removeAllListeners("close");
+      resolve({
+        sock, key, sealed: !!chan,
+        peerFp: theirFp, peerPub: theirPub, peerName: cleanName(msg.name, ""),
+        send: obj => sendFrame(sock, chan ? chan.wrap(obj) : obj),
+        /** What a frame from the other end says — or null on a sealed
+         *  connection when it does not open, which ends the connection: every
+         *  frame after it would fail too. On a connection to a deck from before
+         *  #810, a plain frame passes through as it arrived. */
+        read: frame => (chan ? chan.unwrap(frame) : frame),
+      });
+    };
+
+    sock.on("data", frameReader(msg => {
+      if (settled) return;
+      // A deck that heard us and said no. Each reason is a different problem
+      // with a different fix, and until this frame existed they were all one
+      // silent close that read as a firewall. See REFUSALS.
+      if (msg.t === "no") {
+        // `Object.hasOwn`, and here more than anywhere: `msg.why` is a field in
+        // a frame written by the OTHER MACHINE, which is the case admin-failure
+        // states the rule for (#474). Every member of Object.prototype answers
+        // a plain bracket read with an inherited value that is neither nullish
+        // nor falsy, so `?? "the other deck refused this handshake"` never
+        // fired for one — `{...}["constructor"]` is the Object function itself,
+        // and `new Error(Object).message` is the string "function Object() {
+        // [native code] }". lan-engine files that as `lastRound.error` and the
+        // LAN panel prints it verbatim, so a peer chose what appeared in the
+        // user's interface. Asking whether the map has a ROW is the question
+        // this read was always trying to ask; no real reason moves.
+        return fail(new Error(Object.hasOwn(REFUSALS, msg.why) ? REFUSALS[msg.why]
+          : "the other deck refused this handshake"));
+      }
+      if (msg.t === "challenge") return challenge(msg);
+      return ok(msg);
+    // A refusal from the reader, with the thrown error as its cause when there
+    // was one: the message is the one it always was, and whatever logs the
+    // rejection can reach what actually threw.
+    }, (why, cause) => fail(cause ? new Error(why, { cause }) : new Error(why))));
+  });
+}

package/src/server/lan-copies.mjs

@@ -0,0 +1,270 @@
+// Which copy of a login wins when two decks both hold one, what a deck tells
+// the decks it is paired with about the logins it holds — the lists a manifest
+// carries, as they go out and as they are read coming in — and the words for
+// why a login did not move. Moved out of lan-sync.mjs, which re-exports all of
+// it: none of it reads the beacon, the handshake or the seals, and the identity
+// of an account is the one rule modules far from this feature ask for. Like
+// everything there it is pure — no sockets, no timers, no filesystem.
+import { storedCopyAlive } from "./account-health.mjs";
+
+// ── which copy wins ─────────────────────────────────────────────────────────
+
+/**
+ * The identity of one account, which is NOT its slot number.
+ *
+ * claude-swap keys on `(email, organizationUuid)` — same email under two orgs
+ * is two accounts on purpose — and assigns slots as max+1 per store, so the
+ * account that is 4 here is 2 there. Anything keyed on the number would swap
+ * the wrong pair the first time two stores had grown in a different order.
+ */
+export function accountKey(email, orgUuid) {
+  return `${String(email ?? "").trim().toLowerCase()}@@${String(orgUuid ?? "")}`;
+}
+
+/**
+ * What to do about one account, given what I have and what a peer has.
+ *
+ * TWO OUTCOMES, AND NEITHER OVERWRITES SOMETHING THAT WORKS.
+ *
+ *   "add"   I do not have this account at all.
+ *   "heal"  I have it and claude-swap has quarantined it — refresh token dead,
+ *           verified by an invalid_grant from Anthropic rather than guessed
+ *           from an expiry field — and the peer's copy is alive.
+ *   null    Anything else, which is most of the time.
+ *
+ * A third outcome was designed and dropped, and the reason is worth keeping
+ * because it looks like a feature being given up. It was "replace": take a
+ * peer's copy when it is strictly newer than mine, so the freshest copy wins
+ * everywhere. Measuring "newer" needs the OAuth payload's `expiresAt`, which
+ * means the deck opening a credential — something it does not do, claude-swap
+ * owns that — and on macOS that credential is in the Keychain, which a
+ * background process cannot reliably read at all.
+ *
+ * What settled it is not the obstacle. It is that a working credential replaced
+ * by a newer working credential changes nothing today. It would only matter if
+ * mine were about to die — and a login dies from not being used, so if I am not
+ * using it I do not care, and if I am using it the refresh keeps it alive. The
+ * whole value is in the account that is already dead.
+ *
+ * So this never returns an outcome that needs `cswap import --force`, which
+ * makes claude-swap's own rule the entire safety property: a plain import skips
+ * an account that is present and healthy, and replaces exactly one that is
+ * quarantined. A peer cannot overwrite a credential of mine that works, because
+ * nothing here ever asks for that.
+ */
+export function syncAction(mine, theirs) {
+  if (!theirs || !theirs.alive || theirs.shareable === false) return null;
+  if (!mine) return "add";
+  return mine.alive ? null : "heal";
+}
+
+/**
+ * Everything to do this round, over one peer's manifest.
+ *
+ * Sorted by account key rather than left in manifest order, so two decks
+ * reconciling the same pair of stores do the same work in the same sequence —
+ * which is what makes a failure halfway through repeatable rather than a
+ * different half each time.
+ */
+export function plan(local, remote) {
+  // Through onePerKey, not array order: a Map built straight from the rows
+  // keeps the LAST one for a key, so an expired second slot hid a live first
+  // one and every round "healed" a login that works here.
+  const mine = new Map(onePerKey(local).map(a => [a.key, a]));
+  const out = [];
+  for (const theirs of remote) {
+    const action = syncAction(mine.get(theirs.key), theirs);
+    if (action) out.push({ key: theirs.key, email: theirs.email, action });
+  }
+  return out.sort((a, b) => a.key.localeCompare(b.key));
+}
+
+/**
+ * One row per identity, and THE rule for which one when claude-swap holds two
+ * slots for the same login: a live copy beats an expired one, then one this
+ * process can read beats one it cannot, then the earlier slot.
+ *
+ * ONE RULE, FOUR PLACES. The manifest this deck sends, the peer manifest it
+ * reads, the export it answers a `want` with, and plan's view of this deck's
+ * own copy all pick through this, so the slot a peer was told about is the
+ * slot it is then handed, and the copy this deck advertises as working is the
+ * one it plans from. Each used to take array order on its own and agreed only
+ * by coincidence — and two slots for one identity became two imports of it in
+ * a single round.
+ */
+export function onePerKey(rows) {
+  const rank = a => (a.alive ? 2 : 0) + (a.readable === false ? 0 : 1);
+  const best = new Map();
+  for (const a of rows) {
+    const had = best.get(a.key);
+    if (!had || rank(a) > rank(had)) best.set(a.key, a);
+  }
+  return [...best.values()];
+}
+
+/** This deck's own slot for one identity, by onePerKey's rule, or null. */
+export function slotFor(accounts, key) {
+  return onePerKey(accounts.filter(a => a.key === key))[0] ?? null;
+}
+
+/**
+ * What this deck publishes about its own accounts — to the group, and only to
+ * the group.
+ *
+ * `alive` says whether the stored copy is still valid. `shareable: false` is
+ * the separate, temporary condition where this process cannot read that valid
+ * copy (for example a locked macOS Keychain). Keeping those facts separate is
+ * what stops another deck treating a healthy-but-inaccessible copy as expired
+ * and repeatedly trying to heal it.
+ *
+ * Emails are in it, and the manifest is sealed on its way. This said "in the
+ * clear inside the encrypted channel" until #810, and there was no such
+ * channel: the handshake derived a key and sealed a credential and a version
+ * card with it, and nothing else — so every email in this list crossed the
+ * network readable by anybody on it. Between two decks that both seal, every
+ * frame after the handshake now is (see frameChannel). Toward a deck from
+ * before that it still travels plain, because that deck cannot open anything
+ * else, until it updates.
+ *
+ * Plain emails INSIDE the seal are a deliberate line: a manifest only ever
+ * reaches a deck that proved the key somebody here accepted, and the panel has
+ * to name the account it is offering to heal. Hashing the email would buy
+ * nothing against that reader and would cost the one thing the row needs to say.
+ *
+ * `shared` is the user's list. An account absent from it is absent from the
+ * manifest entirely — not listed as withheld, which would tell the group that
+ * an account exists and is being kept back, and that is itself the fact being
+ * kept back.
+ */
+export function manifestFor(accounts, shared) {
+  const want = new Set(shared);
+  return onePerKey(accounts.filter(a => want.has(a.key)))
+    .map(a => ({
+      key: a.key,
+      email: a.email,
+      alive: !!a.alive,
+      ...(a.readable === false ? { shareable: false } : {}),
+    }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+}
+
+/**
+ * Which account this deck is on, as a frame field for the decks it is paired
+ * with — or nothing.
+ *
+ * ONLY ONE IT SHARES IS EVER NAMED. The account a deck works on is named only
+ * when it is also in the list the owner ticked, so the promise the share list
+ * makes — an unticked account is never told to anybody — holds for this too.
+ * On one it does not share, it says `other` and nothing more: a paired deck
+ * reads "on another account", which says this machine is working without
+ * saying on what.
+ *
+ * `hidden` is the owner's switch turned off, and that IS said, on purpose: a
+ * paired deck then reads "current account hidden" rather than nothing, so the
+ * person over there knows this machine is working and chose not to say where.
+ * A deck with no account at all says nothing.
+ */
+export function currentFor(accounts, shared, shareActive) {
+  if (shareActive === false) return { current: { hidden: true } };
+  const on = accounts.find(a => a.active);
+  if (!on) return {};
+  return new Set(shared).has(on.key) ? { current: { key: on.key } } : { current: { other: true } };
+}
+
+/** One peer-supplied string as the panel may draw it: no control or format
+ *  characters, whitespace collapsed, bounded. The rule cleanName applies to a
+ *  deck's name and lan-about's `field` to a card, applied to the two strings
+ *  that sit next to the fingerprint in the import dialog. */
+function flatten(v, max) {
+  if (typeof v !== "string") return "";
+  const flat = v.replace(/\p{Cc}/gu, " ").replace(/\p{Cf}/gu, "").replace(/\s+/g, " ").trim();
+  return [...flat].slice(0, max).join("");
+}
+
+/**
+ * The accounts a peer's manifest listed, as the panel may keep them.
+ *
+ * It arrived from another machine, so it is read rather than trusted: strings
+ * where strings belong, a boolean for the verdict, and no more rows than a
+ * manifest may carry. What is kept is only what the deck's dialog draws.
+ */
+export function offered(list) {
+  return onePerKey((Array.isArray(list) ? list : [])
+    .filter(a => a && typeof a.key === "string" && typeof a.email === "string")
+    // Character-filtered, not merely cut. These two are drawn beside the
+    // fingerprint at the moment the operator picks which of a peer's logins to
+    // import (LanPeerModal.tsx:497), and a bare slice let a format character
+    // through — the same class cleanName strips from the name one frame over.
+    .map(a => ({
+      key: flatten(a.key, 320),
+      email: flatten(a.email, 254),
+      alive: storedCopyAlive(a.alive, a.collector),
+      // Additive wire field: an older peer omitted it, which means shareable.
+      ...(a.shareable === false ? { shareable: false } : {}),
+    }))
+    .filter(a => a.key && a.email))
+    // Fifty IDENTITIES, so the cap is spent after onePerKey rather than before
+    // it: a peer with duplicate slots could otherwise push a live copy past
+    // row fifty and out of the list while offering far fewer than fifty
+    // logins. The raw array is already bounded by MAX_FRAME_BYTES.
+    .slice(0, 50);
+}
+
+/**
+ * Which account a peer said it is on, as the panel may keep it: the key of one
+ * of the accounts it listed in the same frame, that its owner is hiding it, or
+ * that it is on one it does not share — and nothing for anything else. A key
+ * that is not in its own list is dropped rather than drawn: a deck only ever
+ * names an account it shares, and one that names another is saying something
+ * this deck will not show.
+ */
+export function heardCurrent(raw, list) {
+  if (!raw || typeof raw !== "object") return null;
+  if (raw.hidden === true) return { hidden: true };
+  if (raw.other === true) return { other: true };
+  if (typeof raw.key !== "string") return null;
+  return list.some(a => a.key === raw.key) ? { key: raw.key } : null;
+}
+
+// ── why a login did not move ────────────────────────────────────────────────
+
+/**
+ * The reason a sending deck gives for a login it holds and cannot read: on a
+ * Mac, claude-swap could not open the Keychain from the session this deck runs
+ * in. A fixed code, never the CLI's words — export's stdout IS the credential,
+ * and nothing it printed is any business of the deck asking.
+ */
+export const SENDER_UNREADABLE = "keychain_unavailable";
+
+/** The reasons `serve` gives for a login it will not send. Its other answer to
+ *  a `want`, "not paired", is not in the set, so a deck that gets it records
+ *  "refused". */
+const WIRE_REFUSALS = new Set(["proof", "not shared", "not mine to give", "export failed", SENDER_UNREADABLE, "error"]);
+
+/**
+ * A peer's refusal, as this deck records it. The panel prints these, so a peer
+ * must not be able to put words in its mouth — least of all one of the HERE
+ * codes, which are sentences about this machine. Anything outside the closed
+ * set is "refused", which is all it ever proved.
+ */
+export function peerWhy(why) {
+  return typeof why === "string" && WIRE_REFUSALS.has(why) ? why : "refused";
+}
+
+/**
+ * What this deck found wrong with a login it received. Produced by the local
+ * adapters only and never read off a frame — see peerWhy — so a code here is
+ * always about THIS machine, and on an arrived row it is a warning rather than
+ * a failure: the credential landed and something about this machine stops it
+ * being used.
+ */
+export const HERE = Object.freeze({
+  // claude-swap cannot open this Mac's Keychain from the deck's session.
+  unreadable: "unreadable_here",
+  // It landed, and claude-swap still holds no login for it.
+  noLogin: "no_credentials_here",
+  // It landed, and the login it carried was rejected.
+  expired: "relogin_required_here",
+  // It landed, and claude-swap could not be asked whether it is readable.
+  unverified: "unverified_here",
+});