ccdeck 3.29.11 → 3.30.0

package/src/server/lan-hearing.mjs

@@ -0,0 +1,49 @@
+// Whether this deck can hear other decks announce themselves, and what the
+// panel says while it cannot: lifted out of createEngine in lan-engine.mjs
+// with the one variable only it used — who is holding the discovery port.
+// The beacon knows WHETHER it hears (see createBeacon's `hearing`); this keeps
+// the sentence, and asks port-holder.mjs once per spell whose fault it is.
+import { DISCOVERY_PORT } from "./lan-beacon.mjs";
+
+/**
+ * `beaconNow` answers the engine's beacon as it is at the moment of asking,
+ * null while it is down. `portHolder` names the program on the port — see
+ * port-holder.mjs — and without one nothing is asked. `onChange` is the
+ * engine's own, so the panel redraws when the answer arrives.
+ */
+export function createHearing({ beaconNow, portHolder, onChange }) {
+  /** Who held the discovery port the last time it was asked, for as long as
+   *  this deck cannot hear: the answer does not change between two tries half a
+   *  minute apart, and on Windows asking costs a PowerShell start. Undefined
+   *  until asked, null when the machine would not say. */
+  let holder;
+
+  /** What the panel says while this deck cannot hear — see createBeacon's
+   *  `hearing`. Null whenever it can. */
+  const deafLine = () => {
+    const beacon = beaconNow();
+    if (!beacon || beacon.hearing()) return null;
+    const err = beacon.deafError?.();
+    if (err && err.code !== "EADDRINUSE") {
+      return `This deck cannot listen on UDP ${DISCOVERY_PORT} (${err.code ?? err.message}), so it hears no other deck announce itself. Other decks still find it and pair with it.`;
+    }
+    return `${holder ?? "Another program"} is holding UDP ${DISCOVERY_PORT}, so this deck hears no new decks. Others still find it and pair with it, and it takes the port back as soon as it is free.`;
+  };
+
+  /** The beacon took the discovery port, or lost it: say so, and while it
+   *  cannot hear, ask once which program is holding the port. See deafLine. */
+  const hearingChanged = now => {
+    if (now) { holder = undefined; onChange?.(); return; }
+    if (holder === undefined && portHolder && beaconNow()?.deafError?.()?.code === "EADDRINUSE") {
+      holder = null;
+      void Promise.resolve().then(() => portHolder()).then(who => { holder = who ?? null; onChange?.(); }, () => {});
+    }
+    onChange?.();
+  };
+
+  /** Forget who held the port, so the next spell of deafness asks again —
+   *  what a stop does, because the next start may find somebody else there. */
+  const forget = () => { holder = undefined; };
+
+  return { deafLine, hearingChanged, forget };
+}

package/src/server/lan-inbound.mjs

@@ -0,0 +1,100 @@
+// Who has called this deck, and for how long anybody could have: lifted out of
+// createEngine in lan-engine.mjs with the four records only these write — when
+// each paired deck last spoke and from where, when another machine last got a
+// connection through, and when the listener came up. Nothing here listens:
+// serve (lan-serve.mjs) and the listener's onInbound report each call, and
+// status() and the peer list read what they left.
+
+/**
+ * Did this connection come from a DIFFERENT computer?
+ *
+ * The question behind "can other decks reach this one": a socket accepted from
+ * loopback, or from one of this machine's own addresses, is the second deck on
+ * this computer talking to the first — which happens on every developer machine
+ * and proves nothing at all about the network. Both spellings of loopback are
+ * named because both arrive: `127.0.0.1` from a deck that dialled an address
+ * and `::1` from one that dialled a name.
+ *
+ * Pure and separate from the engine so the case that matters — a connection
+ * from somewhere else — can be tested without a second machine.
+ */
+export const anotherMachine = (from, mine = []) => {
+  const at = String(from ?? "").replace(/^::ffff:/, "").trim();
+  return !!at && at !== "127.0.0.1" && at !== "::1" && !mine.includes(at);
+};
+
+/**
+ * `localAddresses` answers this machine's own addresses at the moment of
+ * asking — see localAddresses in lan-engine.mjs — and `now` is the engine's
+ * clock.
+ */
+export function createInbound({ now, localAddresses }) {
+  /**
+   * When each paired deck last SPOKE TO THIS ONE, keyed by fingerprint.
+   *
+   * The panel had no evidence at all about a deck it does not dial. A deck that
+   * calls in has no beacon row here (if it had one it would be dialled), never
+   * appears in `lastRound`, and its `lastSeen` was therefore undefined forever
+   * — so the row was drawn as live on the strength of being paired, and a
+   * Windows deck that had been closed for an hour still read `ready`. Reported
+   * from a screenshot of exactly that.
+   *
+   * Every authenticated frame lands in `serve`, which is the one place that
+   * knows a paired deck is on the other end of an open socket right now. That
+   * is the evidence, and it is the same kind the beacon gives: a timestamp.
+   */
+  const spokeAt = new Map();
+  /** And the address it spoke FROM, so a deck that only ever calls in can
+   *  still be said to come over the tailnet or the local network — it has no
+   *  address of its own here, and without this its row could not say which. */
+  const spokeFrom = new Map();
+  /**
+   * When a connection from ANOTHER MACHINE last arrived on the sync listener.
+   *
+   * The one fact that settles "can other decks reach this one", and the only
+   * one on the whole question that is measured rather than reasoned about: a
+   * firewall's configuration is read through three different tools on three
+   * platforms, one of which (`ufw`) refuses to show its rules to a process
+   * that is not root. An accepted socket needs none of that — the packets got
+   * in, whatever any rule file says.
+   *
+   * ANOTHER MACHINE, checked here and not in the socket: a connection from
+   * loopback or from one of this machine's own addresses is the second deck on
+   * this computer, which proves nothing about the network. The socket does not
+   * hold that list; this does.
+   */
+  let inboundAt = null;
+
+  /** When this deck's listener came up, or null while it is down.
+   *
+   *  THE OTHER HALF OF `inboundAt`. On its own, "nothing has ever connected in"
+   *  says nothing: a deck that started four seconds ago has the same null as one
+   *  that has been listening all afternoon while the network talked around it.
+   *  What makes the silence evidence is how long it has gone on for, and that is
+   *  a number only the engine holds. See silentInbound in lan-reach.mjs, which
+   *  is the one verdict in this feature that works on a platform nothing can be
+   *  asked about. */
+  let listeningSince = null;
+
+  return {
+    /** A paired deck is talking to this one, now, over the socket `ctx` is
+     *  serve's for — see spokeAt. */
+    spoke(ctx) {
+      spokeAt.set(ctx.peerFp, now());
+      const from = ctx.peerAddr || String(ctx.sock?.remoteAddress ?? "").replace(/^::ffff:/, "");
+      if (from) spokeFrom.set(ctx.peerFp, from);
+    },
+    /** When that deck last spoke, and from which address: undefined until it
+     *  has. */
+    spokeAt: fp => spokeAt.get(fp),
+    spokeFrom: fp => spokeFrom.get(fp),
+    /** A connection arrived on the listener from `from`, handshake or not —
+     *  see inboundAt. */
+    arrived(from) { if (anotherMachine(from, localAddresses())) inboundAt = now(); },
+    inboundAt: () => inboundAt,
+    /** The listener came up, or went down — see listeningSince. */
+    listening() { listeningSince = now(); },
+    closed() { listeningSince = null; },
+    listeningSince: () => listeningSince,
+  };
+}

package/src/server/lan-invite-offer.mjs

@@ -0,0 +1,77 @@
+// The invite this deck is offering right now, and what has happened to it:
+// lifted out of createEngine in lan-engine.mjs, where it was one variable that
+// seven places wrote and read. lan-invite.mjs says what an invite IS — minting
+// one, reading one, the proofs that ride the handshake — and stays pure; this
+// is the one this deck is holding out, from the press that makes it to the
+// proof that spends it or the wrong ones that put it away.
+import { MAX_WRONG_PROOFS } from "./lan-invite.mjs";
+
+/**
+ * `now` is the engine's clock; `onChange` and `onError` are the engine's own,
+ * so the panel redraws and the log reads exactly as it did when this lived
+ * inside it.
+ */
+export function createInviteOffer({ now, onChange, onError }) {
+  /** The invite this deck is offering, or null. One at a time: a deck showing
+   *  two tokens is a deck whose owner cannot say which one they sent. */
+  let invite = null;
+
+  return {
+    /** Offer a freshly minted invite in place of whatever was on offer — see
+     *  the engine's invite(), which mints it — with no wrong proofs yet. */
+    put(made) {
+      invite = { ...made, refused: 0 };
+      onChange?.();
+    },
+
+    /** The invite a proof is checked against, or null once it has run out —
+     *  what the listener asks on every handshake. */
+    live: () => (invite && invite.expiresAt > now() ? invite : null),
+
+    /** What this deck is offering right now, for the panel to draw. Null once
+     *  it has run out, so a token nobody can use is not shown as if they could. */
+    offering() {
+      if (!invite || invite.expiresAt <= now()) return null;
+      return { token: invite.token, expiresAt: invite.expiresAt };
+    },
+
+    /** Put it away without using it. */
+    withdraw() {
+      const had = !!invite;
+      invite = null;
+      if (had) onChange?.();
+      return had;
+    },
+
+    /** Somebody used it: it is spent. Nothing is redrawn here, because the
+     *  pairing that spent it redraws once it is done. */
+    retire() {
+      invite = null;
+    },
+
+    /** Somebody presented a proof of the token that did not hold. Counted on
+     *  the invite, written to the log with where it came from, and at
+     *  MAX_WRONG_PROOFS the invite is put away (#1137) — the owner makes a new
+     *  one, which is one press, and the old one stops being something anybody
+     *  can keep working at. */
+    wrongInvite(from) {
+      if (!invite) return;
+      const refused = (invite.refused ?? 0) + 1;
+      invite = { ...invite, refused };
+      const where = from?.addr || "an unknown address";
+      onError?.("invite", new Error(`a proof of this deck's invite from ${where} did not hold (${refused} of ${MAX_WRONG_PROOFS})`));
+      if (refused >= MAX_WRONG_PROOFS) {
+        invite = null;
+        onError?.("invite", new Error(`put the invite away after ${MAX_WRONG_PROOFS} proofs that did not hold; make a new one`));
+      }
+      onChange?.();
+    },
+
+    /** The token on offer for status(), with how many proofs of it have failed
+     *  so far — the record beside the log's. Null when there is none, or it has
+     *  run out. */
+    row: () => (invite && invite.expiresAt > now()
+      ? { token: invite.token, expiresAt: invite.expiresAt, refused: invite.refused ?? 0 }
+      : null),
+  };
+}

package/src/server/lan-invite.mjs

@@ -0,0 +1,207 @@
+// The invite: one piece of text that lets a deck pair with this one without
+// anybody pressing accept, and the two proofs that ride the handshake for it.
+// Moved out of lan-sync.mjs, whose protocol version and name rule it uses;
+// like everything there, it is pure — no sockets, no timers, no filesystem.
+//
+// ONE PIECE OF TEXT THAT CARRIES EVERYTHING, and it exists because of a real
+// afternoon. Two people, two machines, a typed address, and `handshake timed
+// out` — because the address on screen was the LAN one and the only route
+// between them was a VPN. Neither of them could have known which of the two to
+// use; the deck could not know either, and printing both made it their problem.
+//
+// So the invite carries EVERY address this deck has, and the deck that receives
+// it tries them in turn. Nobody has to know which one is routable, because the
+// only machine that can find out is the one doing the reaching.
+//
+// AND IT CARRIES A CODE, which is what turns two presses into one. A deck that
+// proves it holds the invite is not a stranger asking to be let in — it is
+// somebody the owner of this machine handed a token to. So it is paired on
+// arrival and nobody presses accept. That also closes the gap trust-on-first-use
+// left open: the first contact is verified rather than believed — for as long
+// as the code cannot be guessed, which is why it is 128 random bits and not
+// something a person would type (#1137; see inviteCode).
+//
+// THE TOKEN IS THE SECRET, said plainly rather than implied. Whoever holds it
+// can pair with this deck until it expires. It is a door key with a timer, not
+// an identifier — which is why it is short-lived, single-purpose, and replaced
+// the moment it is used.
+import { createHmac, randomBytes } from "node:crypto";
+import { cleanName, PROTOCOL } from "./lan-sync.mjs";
+
+/** How long an invite is good for. Long enough to paste into a chat and have
+ *  somebody read it, short enough that one left in a channel is not a way in
+ *  tomorrow. */
+export const INVITE_MS = 10 * 60 * 1000;
+
+/** The most addresses an invite may carry. A machine with a VPN, a second card
+ *  and a container bridge has three or four; ten is far past honest and keeps a
+ *  hand-built token from being a way to make this deck dial a list. */
+export const MAX_INVITE_ADDRS = 10;
+
+/** How many proofs of one invite may fail before it is put away (#1137).
+ *
+ *  Not a guard on the code — 128 bits is not something a few more tries get
+ *  any nearer — but a bound on how long a live invite can be worked at, and a
+ *  signal: a token presented wrong this often is circulating in some form
+ *  nobody here handed out, and the owner is better off making another. Five
+ *  rather than one, because one honest paste can reach the deck at several of
+ *  its addresses and an old token pasted by mistake should not cost the new
+ *  one. */
+export const MAX_WRONG_PROOFS = 5;
+
+/** What the token starts with, so a reader can tell at a glance what they have
+ *  been sent and a wrong paste is refused before it is parsed. */
+export const INVITE_PREFIX = "ccdeck1.";
+
+const b64url = buf => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+const unb64url = str => Buffer.from(str.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+
+/** How many random bytes an invite's code is: 128 bits, which is past anything
+ *  that can be counted through. See inviteCode. */
+export const INVITE_CODE_BYTES = 16;
+
+/** The code in a token this version mints: INVITE_CODE_BYTES in base64url,
+ *  which is 22 characters and no padding. */
+const CODE = /^[A-Za-z0-9_-]{22}$/;
+
+/** The code in a token an OLDER deck minted: six digits. Read, so a deck of
+ *  this version can still join one — never minted, so this deck never holds
+ *  one. See readInvite. */
+const OLDER_CODE = /^[0-9]{6}$/;
+
+/**
+ * The invite's secret: 128 bits from the system's random source, spelled in
+ * base64url so it rides in the token as 22 characters.
+ *
+ * IT WAS SIX DIGITS, "a code somebody could read out loud if they had to", and
+ * nobody ever had to: the panel shows the whole token to copy, and `join` reads
+ * the code out of the pasted token and nowhere else. Six digits is about twenty
+ * bits, which a laptop counts through in a second, and both handshake proofs
+ * are made over the code and a transcript that crosses the wire — so the
+ * proofs kept the code only as well as it could not be guessed (#1137). A
+ * secret nobody types can be as long as it needs to be.
+ *
+ * The bytes go into the code as they came, with nothing reduced or sampled
+ * away, so every bit of it is the random source's.
+ */
+export function inviteCode(rand = randomBytes) {
+  return b64url(rand(INVITE_CODE_BYTES));
+}
+
+/** Mint one. `addrs` are already `host:port` strings, because which addresses
+ *  this machine has is not a question this file can answer.
+ *
+ *  Never with an older deck's six digits, even when handed one: a code that
+ *  can be counted through, held by this deck, is exactly what #1137 retired.
+ *  A code that is not this version's kind is refused rather than used. */
+export function mintInvite({ addrs, name, now = Date.now(), code = inviteCode() } = {}) {
+  if (typeof code !== "string" || !CODE.test(code)) return null;
+  const list = (Array.isArray(addrs) ? addrs : []).filter(a => typeof a === "string" && a).slice(0, MAX_INVITE_ADDRS);
+  if (!list.length) return null;
+  const expiresAt = now + INVITE_MS;
+  // `pb` IS THE MINTER SAYING IT WILL PROVE THE CODE BACK, and it is here
+  // rather than in PROTOCOL because PROTOCOL is the whole wire. A deck of this
+  // version answers the handshake with `inviteProofBack`; every deck before it
+  // speaks the same PROTOCOL and does not. The joiner has no other way to tell
+  // the two apart, and a joiner that demanded the proof from both would break
+  // invites exactly across a version boundary — which is when people use them.
+  //
+  // It is not a security decision the far end gets to make. The token is text
+  // the minter handed to the joiner out of band, in the same breath as the
+  // code; whoever can rewrite it already holds the code and has no use for
+  // this. What the flag can do is say "the deck that minted me is old", and the
+  // worst that buys is the behaviour shipped today.
+  //
+  // SINCE #1137 THE CODE SAYS IT TOO. A token with this version's code was
+  // minted by a deck that proves back, so readInvite asks for the proof from
+  // one whether or not `pb` survived the trip. The flag stays for what it
+  // always meant; a token without it can only ever lower the bar for a token
+  // an older deck minted.
+  const body = { v: PROTOCOL, a: list, n: cleanName(name), c: code, x: expiresAt, pb: 1 };
+  return { token: INVITE_PREFIX + b64url(Buffer.from(JSON.stringify(body), "utf8")), code, expiresAt };
+}
+
+/**
+ * Read one somebody pasted, or null.
+ *
+ * REFUSES BEFORE IT UNDERSTANDS, in the order that costs least: the prefix,
+ * then the length, then the decode, then the shape, then the clock. A token is
+ * text a person pasted out of a chat window, so it is as untrusted as anything
+ * that arrives on a socket — and every failure here is the same answer to the
+ * reader, which is "that is not an invite".
+ */
+export function readInvite(raw, now = Date.now()) {
+  if (typeof raw !== "string") return null;
+  const text = raw.trim();
+  if (!text.startsWith(INVITE_PREFIX)) return null;
+  if (text.length > 2048) return null;
+  let body = null;
+  try { body = JSON.parse(unb64url(text.slice(INVITE_PREFIX.length)).toString("utf8")); }
+  catch { return null; }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  if (body.v !== PROTOCOL) return null;
+  // THIS VERSION'S CODE, OR AN OLDER DECK'S SIX DIGITS. Every deck before
+  // #1137 mints six digits and refuses any other code, so a token from one of
+  // those still joins here, while a token from this version is refused THERE
+  // as not an invite, before that deck dials anything. This deck never mints
+  // six digits — see mintInvite — so the older kind only ever names a deck
+  // that is older.
+  const ours = typeof body.c === "string" && CODE.test(body.c);
+  if (!ours && !(typeof body.c === "string" && OLDER_CODE.test(body.c))) return null;
+  if (typeof body.x !== "number" || !Number.isFinite(body.x)) return null;
+  // Expired is its own answer and the caller says so — "that invite has run
+  // out, ask for a new one" is a different instruction from "that is not an
+  // invite", and a reader who cannot tell them apart retypes the same thing.
+  const expired = body.x <= now;
+  const addrs = (Array.isArray(body.a) ? body.a : [])
+    .filter(a => typeof a === "string")
+    .slice(0, MAX_INVITE_ADDRS)
+    .map(a => ({ raw: a, at: a.lastIndexOf(":") }))
+    .filter(p => p.at > 0)
+    .map(p => ({ addr: p.raw.slice(0, p.at), port: Number(p.raw.slice(p.at + 1)) }))
+    .filter(p => p.addr && Number.isInteger(p.port) && p.port > 0 && p.port < 65_536);
+  if (!addrs.length) return null;
+  return {
+    addrs, name: cleanName(body.n), code: body.c, expiresAt: body.x, expired,
+    // Whether the deck that minted this will prove it holds the code — see
+    // mintInvite. Absent means a deck older than that, and the caller degrades
+    // to what it did before rather than refusing the token. Always so for this
+    // version's code, which only a deck that proves back mints.
+    provesBack: ours || body.pb === 1,
+  };
+}
+
+/**
+ * The proof that a caller is holding the invite, over the same transcript the
+ * session key is bound to.
+ *
+ * Not the code itself on the wire. A code that travelled in the clear would be
+ * replayable by anybody who watched one exchange, and this is the value that
+ * decides whether a deck is paired without anybody pressing anything.
+ */
+export function inviteProof(code, transcript) {
+  return createHmac("sha256", `ccdeck-invite-v${PROTOCOL}`).update(`${code}|${transcript}`).digest("hex");
+}
+
+/**
+ * The same proof, the other way round: the deck that MINTED the invite showing
+ * the caller it holds the code too.
+ *
+ * WHY THE CALLER'S PROOF WAS NOT ENOUGH, and it is the whole of #971. The code
+ * travelled in one message, caller to listener, and the reply carried a session
+ * proof — an HMAC over an ECDH against whatever public key the responder had
+ * just presented. That proves the responder holds the private half of the key
+ * it just chose. Anything with a socket holds the private half of a key it just
+ * chose. `join` passes no pin, by definition, so the impostor check in
+ * connectToPeer is inert on this path and whatever answered first was written
+ * into the trusted list.
+ *
+ * A SEPARATE KEY STRING RATHER THAN A DIRECTION FIELD, because the two
+ * transcripts are byte-identical — handshakeTranscript takes the caller and the
+ * listener in a fixed order, so both sides compute the same string. Reusing
+ * `inviteProof` here would let the listener's reply be the caller's own `auth`
+ * frame echoed back, which is precisely the party this is meant to exclude.
+ */
+export function inviteProofBack(code, transcript) {
+  return createHmac("sha256", `ccdeck-invite-back-v${PROTOCOL}`).update(`${code}|${transcript}`).digest("hex");
+}

package/src/server/lan-lines.mjs

@@ -0,0 +1,73 @@
+// The line both ends of a connection speak, whichever dialled: newline-
+// delimited JSON, read without being made to allocate and written with the
+// newline the reader waits for — and the two bounds on it, the most one line
+// may be and how long the handshake over it may take. Lifted out of
+// lan-socket.mjs, which re-exports all of it: it is the one part of that file
+// the answering half and the calling half both use.
+import { MAX_MANIFEST_BYTES } from "./lan-sync.mjs";
+
+/** How long a connection has to finish the handshake before it is dropped. A
+ *  handshake is two round trips on a local network — single-digit
+ *  milliseconds — so five seconds is generous for a slow machine and short
+ *  enough that holding sockets open costs an attacker something. */
+export const HANDSHAKE_MS = 5_000;
+
+/** The most one frame may be, and the most a peer may hold open.
+ *
+ *  Frames are JSON lines. The largest legitimate one is a manifest; the cap is
+ *  an order of magnitude over the biggest real store, and the buffer is
+ *  ABANDONED rather than grown past it — a socket that keeps sending without a
+ *  newline is trying to make this allocate, and the answer is to stop reading
+ *  rather than to read faster. */
+export const MAX_FRAME_BYTES = MAX_MANIFEST_BYTES;
+
+/**
+ * Read newline-delimited JSON off a socket, refusing to be made to allocate.
+ *
+ * The cap is on the UNTERMINATED buffer rather than on a frame that arrived,
+ * which is the distinction that matters: a peer that sends a megabyte with no
+ * newline in it is not sending a large frame, it is sending nothing at all,
+ * expensively. Past the cap this stops reading and hands the caller a refusal
+ * — it does not keep buffering in the hope a newline turns up.
+ */
+export function frameReader(onFrame, onRefuse, max = MAX_FRAME_BYTES) {
+  let buf = "";
+  let dead = false;
+  return chunk => {
+    if (dead) return;
+    buf += chunk;
+    if (buf.length > max) { dead = true; buf = ""; onRefuse("frame too large"); return; }
+    let i;
+    while ((i = buf.indexOf("\n")) !== -1) {
+      const line = buf.slice(0, i);
+      buf = buf.slice(i + 1);
+      if (!line.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(line); }
+      catch { dead = true; buf = ""; onRefuse("not json"); return; }
+      // `typeof [] === "object"`, so an array walks straight past the obvious
+      // check and reaches a handler that reads `msg.t` off it — undefined, and
+      // then whatever that handler does with a frame that has no type. A frame
+      // is a record; anything else is refused.
+      if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
+        dead = true; buf = ""; onRefuse("not an object"); return;
+      }
+      // A HANDLER THAT THROWS ENDS ITS CONNECTION, NOT THE PROCESS. This runs
+      // inside the socket's `data` event, where nothing above catches, so a
+      // throw from a frame handler took the whole deck down — and every frame
+      // read here has come off the network before anybody is trusted. The
+      // handlers are meant never to throw; this is what holds when one does.
+      // The error goes on with the refusal, so the next one that hides here is
+      // logged with its stack rather than as two words.
+      try { onFrame(msg); }
+      catch (err) { dead = true; buf = ""; onRefuse("bad frame", err); return; }
+      if (dead) return;
+    }
+  };
+}
+
+/** One line out. Kept in one place so nothing forgets the newline the reader
+ *  above is waiting for. */
+export function sendFrame(sock, obj) {
+  try { sock.write(`${JSON.stringify(obj)}\n`); } catch { /* peer went away */ }
+}

package/src/server/lan-manifest.mjs

@@ -0,0 +1,74 @@
+// This deck's side of the manifest exchange: the frame it sends — the accounts
+// it shares, which of them it is on, and its card — and what it keeps of the
+// frame it hears back. Lifted out of createEngine in lan-engine.mjs with the
+// two maps only these fill, so saying and hearing sit in one file as they sat
+// side by side in the engine. The rules for the lists themselves are
+// lan-copies.mjs's, and the card's are lan-about.mjs's.
+import { currentFor, heardCurrent, manifestFor, offered } from "./lan-sync.mjs";
+import { openAbout, sealAbout } from "./lan-about.mjs";
+
+/**
+ * `about` is this deck's own card, or null for a deck built without one. `now`
+ * is the engine's clock. `myFp` answers this deck's fingerprint as it is at
+ * the moment of asking — a restart for a new key changes it — and `settings`
+ * the settings in force, of which a manifest reads `shared` and `shareActive`.
+ */
+export function createManifests({ about, now, myFp, settings }) {
+  /** What each paired deck said about itself — version, operating system,
+   *  architecture — keyed by fingerprint, most recent only. Filled from both
+   *  directions: the manifest a deck answers with, and the question a deck that
+   *  calls in asks. See lan-about.mjs. */
+  const aboutBy = new Map();
+  /** The accounts each paired deck offered in its last manifest, keyed by
+   *  fingerprint. Kept APART from the engine's lastRound on purpose: a round
+   *  that fails replaces that line, and the list a deck offered a minute ago is
+   *  still the best answer to "what does it share" while it is unreachable. */
+  const offersBy = new Map();
+
+  /** This deck's card for one connection, as a frame field — or nothing, for a
+   *  deck built without one. Spread into the frame, so a deck from before this
+   *  existed receives exactly the frame it always did plus one key it never
+   *  reads. */
+  const cardFor = (key, toFp) => {
+    const sealed = sealAbout(key, about, myFp(), toFp);
+    return sealed ? { about: sealed } : {};
+  };
+
+  /** This deck's manifest for the deck on the other end of `key`: the accounts
+   *  it shares, which of them it is on, and its card. One frame whichever way
+   *  it travels — the question a round asks, and the answer `serve` gives. */
+  const manifestFrame = (accounts, key, toFp) => {
+    const cfg = settings();
+    return {
+      t: "manifest", accounts: manifestFor(accounts, cfg.shared),
+      ...currentFor(accounts, cfg.shared, cfg.shareActive),
+      ...cardFor(key, toFp),
+    };
+  };
+
+  /**
+   * What a paired deck's manifest said about it, kept for the panel — the
+   * question a deck that calls in asks as much as the answer a dialled one
+   * gives. Its card, when the seal opens; and the accounts it offers with the
+   * one it is on, kept only when a list came — an older caller asks with its
+   * card alone, and a missing list is not an empty one. Returns that list, or
+   * null for a frame that carried none.
+   */
+  const keepManifest = (key, frame, fromFp) => {
+    const card = openAbout(key, frame.about, fromFp, myFp());
+    if (card) aboutBy.set(fromFp, { ...card, at: now() });
+    if (!Array.isArray(frame.accounts)) return null;
+    const list = offered(frame.accounts);
+    offersBy.set(fromFp, { at: now(), accounts: list, current: heardCurrent(frame.current, list) });
+    return list;
+  };
+
+  /** What the deck proven as `fp` last said, for its row: its card and the
+   *  logins it offered, each null until it has said one. */
+  const heardOf = fp => ({
+    about: aboutBy.get(fp) ?? null,
+    offers: offersBy.get(fp) ?? null,
+  });
+
+  return { manifestFrame, keepManifest, heardOf };
+}