agent-dag 3.20.0 → 3.21.0

package/src/server/lan-about.mjs

@@ -0,0 +1,119 @@
+// What a paired deck says about itself: the version it runs and the machine it
+// runs on.
+//
+// ONLY TO A DECK THAT IS PAIRED, AND SEALED. The beacon is shouted at the whole
+// network and the hello is sent before anybody has proved anything, so neither
+// carries this: which build of which operating system a machine runs is the
+// first thing somebody hunting for a known-broken version would want, and
+// nobody on the network is owed it. It rides the manifest exchange, which only
+// happens between two decks that have each accepted the other — and it is
+// sealed with that connection's key, because the frames around it are JSON in
+// the clear on the wire.
+//
+// BOTH WAYS. The deck that dials sends its own card with the question, and the
+// deck that answers sends its own with the answer. A deck that only calls in —
+// paired, with no address this one can reach — is never asked anything, so the
+// card it sends when it calls is the only way this deck ever learns what it is.
+//
+// OLDER DECKS SAY NOTHING, AND NOTHING BREAKS. The field is extra on a frame
+// both versions already send: a deck from before this reads the accounts and
+// never looks at the rest, and a card that is absent is drawn as absent.
+import { readFileSync } from "node:fs";
+import { release as osRelease } from "node:os";
+import { open, seal } from "./lan-sync.mjs";
+
+/**
+ * The operating system, in the words its owner would use.
+ *
+ * Node reports the KERNEL — `darwin 25.5.0`, `win32 10.0.26100` — and nobody
+ * calls their laptop Darwin 25. So the numbers are translated on the machine
+ * they describe, where the translation is certain, rather than on the one
+ * reading them. Every input is a parameter, so all three platforms are tested
+ * on any one of them.
+ */
+export function osLabel({ platform, release = "", prettyName = "" } = {}) {
+  const [major, minor, build] = String(release).split(".").map(n => Number.parseInt(n, 10));
+  const dot = Number.isInteger(minor) ? `.${minor}` : "";
+  if (platform === "darwin") {
+    if (!Number.isInteger(major)) return "macOS";
+    // Darwin 20 was macOS 11 and every major after it was one more — until 25,
+    // which Apple shipped as macOS 26 to match the year.
+    if (major >= 25) return `macOS ${major + 1}${dot}`;
+    if (major >= 20) return `macOS ${major - 9}${dot}`;
+    // The 10.x years, where the kernel's major minus four is the second number.
+    return major >= 5 ? `macOS 10.${major - 4}` : "macOS";
+  }
+  if (platform === "win32") {
+    // Windows 11 kept the version 10.0 and moved only the build, and 22000 is
+    // the first one. From here it is the only way to tell the two apart.
+    if (major === 10 && Number.isInteger(build)) return build >= 22_000 ? "Windows 11" : "Windows 10";
+    return "Windows";
+  }
+  if (platform === "linux") return prettyName || "Linux";
+  return typeof platform === "string" && platform ? platform : "unknown";
+}
+
+/** The distribution's own name for itself, from the file every systemd-era
+ *  distribution ships, with the fallback path the same spec names. Only ever
+ *  read on Linux: the paths are Linux's and mean nothing anywhere else. */
+export function linuxPrettyName(read = readFileSync) {
+  for (const file of ["/etc/os-release", "/usr/lib/os-release"]) {
+    try {
+      const line = /^PRETTY_NAME=(.*)$/m.exec(String(read(file, "utf8")))?.[1];
+      const name = line?.trim().replace(/^(["'])(.*)\1$/, "$2").trim();
+      if (name) return name;
+    } catch { /* not this one */ }
+  }
+  return "";
+}
+
+/** This deck's own card. Built once, at start: nothing in it changes while the
+ *  process lives, and an upgrade is a restart. */
+export function aboutThisDeck({
+  version = null, platform = process.platform, release = osRelease(), arch = process.arch, read = readFileSync,
+} = {}) {
+  return readAbout({
+    version,
+    os: osLabel({ platform, release, prettyName: platform === "linux" ? linuxPrettyName(read) : "" }),
+    arch,
+  });
+}
+
+/** One field of a card, or null. It came off the network, so it is a string of
+ *  bounded length with no control characters — the rule cleanName applies to a
+ *  deck's name, for the same reason: it reaches a terminal as well as a page.
+ *  `\p{Cc}` is the Unicode class for exactly those, C0 and C1 both. */
+function field(v, max, shape = null) {
+  if (typeof v !== "string") return null;
+  const flat = v.replace(/\p{Cc}/gu, " ").replace(/\s+/g, " ").trim();
+  const s = [...flat].slice(0, max).join("").trim();
+  return s && (!shape || shape.test(s)) ? s : null;
+}
+
+/** A card, or null when there is nothing in it worth drawing. */
+export function readAbout(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const version = field(raw.version, 32, /^[0-9A-Za-z][0-9A-Za-z.+-]*$/);
+  const os = field(raw.os, 48);
+  const arch = field(raw.arch, 16, /^[0-9A-Za-z_]+$/);
+  return version || os || arch ? { version, os, arch } : null;
+}
+
+/** Bound to one connection AND one direction, so a card cannot be replayed
+ *  back at the deck that sent it as if it were the other deck's. */
+const aboutAad = (fromFp, toFp) => `${fromFp}->${toFp}|about`;
+
+/** This deck's card, sealed for the deck on the other end of `key`. */
+export function sealAbout(key, about, fromFp, toFp) {
+  if (!key || !about) return null;
+  return seal(key, JSON.stringify(about), aboutAad(fromFp, toFp));
+}
+
+/** The other deck's card, or null — for a deck that sent none, and for one
+ *  whose seal does not open, which mean the same thing to the panel. */
+export function openAbout(key, sealed, fromFp, toFp) {
+  if (!key || !sealed || typeof sealed !== "object") return null;
+  const text = open(key, sealed, aboutAad(fromFp, toFp));
+  if (text == null) return null;
+  try { return readAbout(JSON.parse(text)); } catch { return null; }
+}

package/src/server/lan-engine.mjs

@@ -30,6 +30,7 @@
 import { accountKey, manifestFor, open, plan, seal, stillListed, transferChallenge } from "./lan-sync.mjs";
 import { connectToPeer, createBeacon, createSyncServer, sendFrame } from "./lan-socket.mjs";
 import { addTrusted, dropTrusted, identityFrom, mintInvite, pairable, readInvite, trustedPeer } from "./lan-sync.mjs";
+import { openAbout, sealAbout } from "./lan-about.mjs";
 import { randomBytes } from "node:crypto";
 import { hostname, networkInterfaces } from "node:os";
 
@@ -95,6 +96,20 @@ export function localAddresses(faces = networkInterfaces()) {
   return out;
 }
 
+/**
+ * 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 (Array.isArray(list) ? list : [])
+    .filter(a => a && typeof a.key === "string" && typeof a.email === "string")
+    .slice(0, 50)
+    .map(a => ({ key: a.key.slice(0, 320), email: a.email.slice(0, 254), alive: a.alive === true }));
+}
+
 /**
  * One deck's LAN sync, from settings to a healed account.
  *
@@ -118,10 +133,13 @@ export function createEngine({
    * with. Nothing secret leaves, and it is still a test shouting at an office.
    */
   createSocket,
+  /** This deck's own card — its version and its machine — handed to every
+   *  paired deck and to nobody else. See lan-about.mjs. */
+  about = null,
 } = {}) {
   let cfg = {
     enabled: false, name: defaultName(), secret: "", shared: [], trusted: [], port: 0,
-    autoAsk: true, autoAccept: true,
+    autoAsk: true, autoAccept: true, aliases: {},
   };
   let identity = null;
   let beacon = null;
@@ -166,6 +184,16 @@ export function createEngine({
   /** 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();
+  /** 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 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();
   /** When the last round FINISHED, whatever it did or failed to do. The panel's
    *  `↻` fires one on demand and the loop fires one on its own; a reader who
    *  pressed it wants to know it happened, and a reader who did not wants to
@@ -212,6 +240,15 @@ export function createEngine({
     }));
   };
 
+  /** 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, identity.fp, toFp);
+    return sealed ? { about: sealed } : {};
+  };
+
   /** Frames from a deck that finished the handshake AND that somebody here has
    *  accepted. Nothing reaches this before both, which is the whole point of
    *  where the two checks sit. `ctx.key` is this connection's key and no other
@@ -222,8 +259,16 @@ export function createEngine({
     if (ctx?.peerFp) spokeAt.set(ctx.peerFp, now());
     try {
       if (msg.t === "manifest") {
+        // THE CALLER'S CARD RIDES THE QUESTION, which is the only way a deck
+        // that calls in ever says what it is: nothing here dials it, so nothing
+        // here ever asks. A seal that does not open is a deck that said nothing.
+        const card = openAbout(ctx.key, msg.about, ctx.peerFp, identity.fp);
+        if (card) aboutBy.set(ctx.peerFp, { ...card, at: now() });
         const accounts = await localAccounts();
-        return ctx.send({ t: "manifest", accounts: manifestFor(accounts, cfg.shared) });
+        return ctx.send({
+          t: "manifest", accounts: manifestFor(accounts, cfg.shared),
+          ...cardFor(ctx.key, ctx.peerFp),
+        });
       }
       if (msg.t === "want") {
         // A SECOND PROOF, for the one operation that moves a credential. The
@@ -313,13 +358,18 @@ export function createEngine({
 
       if (!trustedPeer(cfg.trusted, conn.peerFp)) {
         const { list, added } = addTrusted(cfg.trusted, {
-          fp: conn.peerFp, pub: conn.peerPub, name: conn.peerName,
+          fp: conn.peerFp, pub: conn.peerPub, name: conn.peerName, at: now(),
         });
         if (added) { cfg = { ...cfg, trusted: list }; onTrust?.(list); }
       }
 
-      const theirs = await ask({ t: "manifest" });
+      // Our card goes with the question and theirs comes back with the answer
+      // — see lan-about.mjs for why it is here and nowhere earlier.
+      const theirs = await ask({ t: "manifest", ...cardFor(conn.key, conn.peerFp) });
       if (theirs?.t !== "manifest" || !Array.isArray(theirs.accounts)) throw new Error("no manifest");
+      const card = openAbout(conn.key, theirs.about, conn.peerFp, identity.fp);
+      if (card) aboutBy.set(conn.peerFp, { ...card, at: now() });
+      offersBy.set(conn.peerFp, { at: now(), accounts: offered(theirs.accounts) });
       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.
@@ -449,7 +499,7 @@ export function createEngine({
         // Somebody used the token. They are pinned, and the token is retired —
         // one that pairs twice is one worth stealing twice.
         onInviteUsed: entry => {
-          const { list } = addTrusted(cfg.trusted, { fp: entry.fp, pub: entry.pub, name: entry.name });
+          const { list } = addTrusted(cfg.trusted, { fp: entry.fp, pub: entry.pub, name: entry.name, at: now() });
           cfg = { ...cfg, trusted: list };
           invite = null;
           // AND DIAL IT BACK, KEPT. Accepting made it welcome and left this
@@ -612,7 +662,7 @@ export function createEngine({
             name: cfg.name, myPort: server.port(), code: inv.code,
           });
           const { list } = addTrusted(cfg.trusted, {
-            fp: conn.peerFp, pub: conn.peerPub, name: conn.peerName || inv.name,
+            fp: conn.peerFp, pub: conn.peerPub, name: conn.peerName || inv.name, at: now(),
           });
           cfg = { ...cfg, trusted: list };
           this.addPeer(at.addr, at.port);
@@ -667,7 +717,7 @@ export function createEngine({
         onChange?.();
         return { fp, name: seen.name, addr: seen.addr, port: seen.port, dialled: true };
       }
-      const { list, added } = addTrusted(cfg.trusted, { fp, pub: seen.pub, name: seen.name });
+      const { list, added } = addTrusted(cfg.trusted, { fp, pub: seen.pub, name: seen.name, at: now() });
       cfg = { ...cfg, trusted: list };
       pending.delete(fp);
       strangers.delete(fp);
@@ -724,6 +774,24 @@ export function createEngine({
       return true;
     },
     round,
+    /**
+     * One deck, now — the `check now` in that deck's own dialog.
+     *
+     * Found the way the list found it: heard on the network under its own
+     * fingerprint, or dialled at an address whose answer was that fingerprint.
+     * Null when it is neither, which is a deck that only calls in — nothing
+     * here holds an address for it, so there is nobody to dial.
+     *
+     * `roundAt` is left alone: it says when EVERY paired deck was last asked,
+     * and asking one of them does not make that true.
+     */
+    async roundOne(fp) {
+      if (!beacon || typeof fp !== "string" || !fp) return null;
+      const heard = [...beacon.peers.values()].find(p => p.fp === fp && stillListed(p, now()));
+      const typed = [...manual.values()].find(p => learned.get(`${p.addr}:${p.port}`)?.fp === fp);
+      const peer = heard ?? typed;
+      return peer ? roundWith(peer) : null;
+    },
     /** 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. */
@@ -758,6 +826,11 @@ export function createEngine({
         // which on a deck that has just started is the honest answer.
         checkedAt: roundAt,
         name: cfg.name,
+        // This deck's own card, so the panel can read a peer's version against
+        // it; and the names somebody here gave other decks, which the panel
+        // and the request dialog draw in place of the ones those decks chose.
+        about: about ?? null,
+        aliases: { ...(cfg.aliases ?? {}) },
         // Whether this deck asks on its own, and whether a request that
         // arrives is answered here or answered for you.
         autoAsk: !!cfg.autoAsk,
@@ -820,6 +893,15 @@ export function createEngine({
             had.met = had.met || row.met;
             if (row.name && !had.name) had.name = row.name;
           };
+          // WHAT THE DECK'S OWN DIALOG DRAWS, by identity: the card it sent,
+          // the logins it offered last, and when somebody here said yes. All
+          // three are keyed by the fingerprint that proved itself, so both
+          // halves of a merged row read the same answer.
+          const card = id => ({
+            about: aboutBy.get(id) ?? null,
+            offers: offersBy.get(id) ?? null,
+            pairedAt: trustedPeer(cfg.trusted, id)?.at ?? null,
+          });
           for (const p of [...beacon.peers.values(), ...manual.values()]) {
             if (!stillListed(p, now())) continue;
             const met = p.manual ? learned.get(`${p.addr}:${p.port}`) : null;
@@ -834,6 +916,7 @@ export function createEngine({
               met: !!met,
               paired: !!trustedPeer(cfg.trusted, id),
               last: lastRound.get(p.fp) ?? null,
+              ...card(id),
             });
           }
           // A DECK WE ARE PAIRED WITH AND DO NOT DIAL. It called us, we accepted

package/src/server/lan-sync.mjs

@@ -592,7 +592,11 @@ export function addTrusted(trusted, entry) {
       added: false,
     };
   }
-  return { list: [...list, { fp: entry.fp, pub: entry.pub, name: entry.name ?? "" }], added: true };
+  // WHEN, for the panel's "paired since". Only a new pin gets one: a deck that
+  // was already trusted keeps whatever date it had, and one pinned before this
+  // field existed keeps having none rather than being given today's.
+  const at = Number.isFinite(entry.at) && entry.at > 0 ? { at: entry.at } : {};
+  return { list: [...list, { fp: entry.fp, pub: entry.pub, name: entry.name ?? "", ...at }], added: true };
 }
 
 /** Take one back out. Unpairing stops what has not happened yet and takes back

package/src/server/presence.mjs

@@ -0,0 +1,40 @@
+// Whether somebody is looking at the deck right now, as its tabs say.
+//
+// The server can tell whether a page is CONNECTED — `sseClients.size` — but not
+// whether anybody is looking at one: a tab behind other windows keeps its
+// stream open all day. The away-update (auto-update.mjs) needs the second fact,
+// so each tab reports it (src/web/presence.ts), and a claim expires here unless
+// it is renewed, because a tab that crashed or lost its network never gets to
+// take it back.
+export const PRESENCE_TTL_MS = 45_000;
+/** More tabs than anybody opens on one deck. A bound because the ids arrive
+ *  from pages; past it the oldest claim goes. */
+const MAX_TABS = 32;
+const TAB_ID = /^[\w-]{1,64}$/;
+
+export function createPresence({ ttlMs = PRESENCE_TTL_MS } = {}) {
+  /** tab id → when it last said it was looking */
+  const seen = new Map();
+  return {
+    /** A tab saying whether it is being looked at. False for an id no page
+     *  could have made, which the route answers with a 400. */
+    report(tab, looking, now) {
+      if (typeof tab !== "string" || !TAB_ID.test(tab)) return false;
+      seen.delete(tab);
+      if (looking) {
+        seen.set(tab, now);
+        while (seen.size > MAX_TABS) seen.delete(seen.keys().next().value);
+      }
+      return true;
+    },
+    /** Whether any tab's claim is still live. A claim stamped by a clock that
+     *  has since moved either way is as expired as an old one. */
+    looking(now) {
+      for (const [tab, at] of seen) {
+        if (Math.abs(now - at) > ttlMs) seen.delete(tab);
+        else return true;
+      }
+      return false;
+    },
+  };
+}