realtimeclipboard 0.5.0 → 0.7.0

package/README.md

@@ -19,8 +19,8 @@ touch the server.
 **Status: beta, and it works end to end.** The relay is deployed and live,
 the frontend is wired to it over a WebSocket with an SSE fallback, and the
 32-check end-to-end suite runs two real peers with real crypto against the
-production relay. See [docs/M0-RESULTS.md](docs/M0-RESULTS.md) for exactly what
-is proven, and [Known limitations](#known-limitations) for what is not.
+production relay. See [Known limitations](#known-limitations) for what is not
+proven.
 
 ---
 
@@ -223,8 +223,8 @@ npm run release -- minor             # verify, changelog, release PR, tag, deplo
 | [CHANGELOG.md](CHANGELOG.md) | What shipped in each release — generated from the commits |
 | [CLIPBOARD-FLOW.md](docs/CLIPBOARD-FLOW.md) | How the browser reaches the OS clipboard, and why background capture is impossible |
 | [P2P-FILES.md](docs/P2P-FILES.md) | Thumbnails over the relay, bytes over WebRTC, and the corporate-network problem |
-| [M0-RESULTS.md](docs/M0-RESULTS.md) | Transport gate results |
-| [SEO.md](docs/SEO.md) | Search, answer-engine and distribution strategy |
+| [ACCESSIBILITY.md](docs/ACCESSIBILITY.md) | Keyboard paths, focus handling, and what the screen reader announces |
+| [SELF-HOSTING.md](docs/SELF-HOSTING.md) | Running your own relay and pointing a build at it |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Setup, the commit convention, and the boundaries the checks enforce |
 | [SECURITY.md](SECURITY.md) | Reporting a vulnerability privately, and what is in scope |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1 |

package/cli/realtimeclipboard.mjs

@@ -28,11 +28,9 @@ import { hostname } from "node:os";
 import { readFileSync } from "node:fs";
 
 import * as keys from "../src/core/keys.js";
-import * as cryptoBox from "../src/core/crypto.js";
 import * as relay from "../src/transport/relay.js";
-import * as proto from "../src/transport/protocol.js";
-import { on, EV } from "../src/core/bus.js";
-import { DEFAULT_RELAY_URL, normaliseRelay, TEXT, LOCK } from "../src/core/config.js";
+import * as room from "./session.mjs";
+import { DEFAULT_RELAY_URL, normaliseRelay, TEXT } from "../src/core/config.js";
 import { INVISIBLE_SOURCE } from "../src/core/text.js";
 
 /**
@@ -168,87 +166,43 @@ function die(msg, code = 1) {
 /* --------------------------------------------------------------- session -- */
 
 /**
- * Everything needed to talk in a room, derived exactly as the browser derives
- * it — same salt, same iteration count, same HKDF info strings, because it is
- * the same function.
+ * Derived exactly as the browser derives it, because it is the same function —
+ * see cli/session.mjs. This wrapper exists only to turn a throw into an exit
+ * code, which is the part a pipe cares about.
  */
 async function derive(rawKey, pin) {
-  const key = keys.normalise(rawKey);
-  if (!keys.isValid(key)) die(`"${rawKey}" is not a valid key`, 2);
-
-  if (pin) {
-    const clean = cryptoBox.normalisePin(pin);
-    if (!clean) die("that PIN is too short", 2);
-    const d = await cryptoBox.deriveLocked(key, clean);
-    return { key, roomHash: d.roomHash, aesKey: d.aesKey, auth: d.authToken, locked: true };
-  }
-  const open = await cryptoBox.deriveOpen(key);
-  return { key, roomHash: open.roomHash, aesKey: open.aesKey, auth: null, locked: false };
+  try { return await room.derive(rawKey, pin); }
+  catch (err) { die(err.message, 2); }
 }
 
 /**
- * Connect and resolve once the relay has welcomed us.
- *
- * relay.js announces state on the bus rather than returning a promise, because
- * in the browser the connection outlives any one call. Here there is a script
- * waiting, so the bus event is adapted back into a promise — and a timeout,
- * since a pipe that hangs forever is worse than one that fails.
+ * Connect and resolve once the relay has welcomed us. The adapter is shared; what
+ * stays here is the CLI's own reporting — a `--quiet`-aware note on a transport
+ * error, and a line on stderr for a clip this key cannot read.
  */
-function connect(session, opts, onClip) {
+function connect(sess, opts, onClip) {
   const url = opts.relay ?? env.REALTIMECLIPBOARD_RELAY ?? undefined;
   if (opts.relay && !normaliseRelay(opts.relay)) die(`"${opts.relay}" is not a usable relay address`, 2);
 
-  return new Promise((resolve, reject) => {
-    // Connecting has its own bound, separate from --timeout below: "the relay
-    // never answered" and "nothing was ever sent to this room" are different
-    // failures, and a script that gets one when it expected the other has been
-    // told a lie about its own network.
-    const timer = setTimeout(
-      () => reject(new Error("the relay did not answer")),
-      Math.max(opts.timeout || 0, 20_000),
-    );
-
-    on(EV.CONN_STATE, ({ state, detail }) => {
-      if (state === "connected") { clearTimeout(timer); resolve(); }
-      if (state === "error" && detail) note(`  ${detail}`, opts);
-    });
-
-    relay.setFrameHandler(async msg => {
-      if (msg.t !== proto.T.CLIP || !msg.payload) return;
-      try {
-        const text = await cryptoBox.decrypt(session.aesKey, msg.payload, msg.iv);
-        // The lock beacon is a control frame wearing a clip's clothes: it is
-        // what lets a joiner tell "wrong PIN" from "first one here". Receivers
-        // drop it rather than render it, and a pipe must not see it either.
-        // Compared against the constant, not a guess at its shape: it starts
-        // with NUL, and "looks like a control character" would also
-        // swallow a legitimate clip that happened to.
-        if (text === LOCK.BEACON) return;
-        onClip(text, msg);
-      } catch {
-        // Undecryptable means a different secret, not a corrupt relay: someone
-        // in the room with another PIN, or a stale frame from a rotated key.
-        note("  (a clip arrived that this key cannot read)", opts);
-      }
-    });
-
-    relay.connect({
-      roomHash: session.roomHash,
-      intent: "join",
-      name: `cli@${hostname()}`,
-      auth: session.auth,
-      ...(url ? { url: normaliseRelay(url) } : {}),
-    });
+  return room.open({
+    session: sess,
+    name: `cli@${hostname()}`,
+    url: url ? normaliseRelay(url) : undefined,
+    timeoutMs: opts.timeout || 0,
+    onClip,
+    onState: (state, detail) => { if (state === "error" && detail) note(`  ${detail}`, opts); },
+    onUndecryptable: () => note("  (a clip arrived that this key cannot read)", opts),
   });
 }
 
-async function sendText(session, text, opts) {
+async function sendText(sess, text, opts) {
   if (!text) die("nothing on stdin to send", 2);
   if (text.length > TEXT.MAX_CHARS) {
     die(`that is ${text.length} characters; the limit is ${TEXT.MAX_CHARS}`, 2);
   }
-  const { payload, iv } = await cryptoBox.encrypt(session.aesKey, text);
-  relay.send(proto.clip({ payload, iv, originId: `cli-${Date.now().toString(36)}` }));
+  try {
+    await room.send(sess, text, `cli-${Date.now().toString(36)}`);
+  } catch (err) { die(err.message, 2); }
   // The frame is handed to a socket, not delivered. Give it a moment to flush
   // before the process exits out from under it.
   await new Promise(r => setTimeout(r, 250));
@@ -338,7 +292,15 @@ if (cmd === "both") {
   // Not readStdin(): that waits for EOF, and this mode has to send each line as
   // it is typed while still printing what arrives in between.
   const rl = createInterface({ input: stdin, terminal: false });
-  rl.on("line", line => { if (line.length) sendText(session, line, opts).catch(() => {}); });
+  // Chained, not launched: each line is encrypted before it is sent, and two
+  // encryptions in flight complete in whichever order WebCrypto finishes them.
+  // A pasted block of lines could reach the relay out of order and be stamped
+  // with inverted `seq`, which is what receivers order and dedupe by.
+  let sending = Promise.resolve();
+  rl.on("line", line => {
+    if (!line.length) return;
+    sending = sending.then(() => sendText(session, line, opts)).catch(() => {});
+  });
   rl.on("close", () => { relay.close(); exit(0); });
 }
 

package/cli/session.mjs

@@ -0,0 +1,134 @@
+/**
+ * A room, as a promise-shaped API — for the surfaces that have a caller waiting.
+ *
+ * relay.js announces state on the bus because in a browser the connection
+ * outlives any one call. `cli/`, `mcp/` and `vscode/` all have something waiting
+ * instead, and all three had adapted the bus back into a promise separately.
+ * This is that adapter, once, because three copies of "derive, connect, decrypt,
+ * drop the beacon" is three chances for two ends to disagree silently.
+ *
+ * Deliberately below the app: it touches no state, emits no bus events and knows
+ * nothing about history, editors or clipboards. It hands decrypted text to a
+ * callback and stops. What each surface does next is that surface's business.
+ *
+ * WHY IT LIVES IN cli/ AND NOT src/transport/, which is where it looks like it
+ * belongs: `src/` is the web app, and every .js under it is app shell — the
+ * precache check in tests/unit/static-check.mjs treats the directory itself as
+ * the list. A module no page ever loads would have to be precached anyway, or
+ * carved out with an exception. `cli/` is already the npm publish boundary and
+ * already the headless half of this codebase, so it is the honest home; `mcp/`
+ * and `vscode/` import it from here.
+ */
+
+import * as keys from "../src/core/keys.js";
+import * as cryptoBox from "../src/core/crypto.js";
+import { LOCK, TEXT, textBytes, NET } from "../src/core/config.js";
+import { on, EV } from "../src/core/bus.js";
+import * as relay from "../src/transport/relay.js";
+import * as proto from "../src/transport/protocol.js";
+
+/**
+ * Everything needed to talk in a room, derived exactly as the browser derives
+ * it — same salt, same iteration count, same HKDF info strings, because it is
+ * the same function.
+ *
+ * Throws rather than exiting: a library that calls process.exit() cannot be
+ * used by anything that wants to handle the failure.
+ */
+export async function derive(rawKey, pin) {
+  const key = keys.normalise(rawKey);
+  const refused = keys.rejectMessage(key);
+  if (refused) throw new Error(`"${rawKey}" cannot be used — ${refused}`);
+
+  if (pin) {
+    const clean = cryptoBox.normalisePin(pin);
+    if (!clean) throw new Error(`a PIN needs at least ${LOCK.MIN_PIN} characters`);
+    const d = await cryptoBox.deriveLocked(key, clean);
+    return { key, roomHash: d.roomHash, aesKey: d.aesKey, auth: d.authToken, locked: true };
+  }
+  const d = await cryptoBox.deriveOpen(key);
+  return { key, roomHash: d.roomHash, aesKey: d.aesKey, auth: null, locked: false };
+}
+
+/**
+ * Connect, and resolve once the relay has welcomed us.
+ *
+ * The connect bound is separate from any read timeout a caller keeps: "the relay
+ * never answered" and "nothing was ever sent to this room" are different
+ * failures, and a script handed one when it expected the other has been told a
+ * lie about its own network.
+ *
+ *   onClip(text, frame)   decrypted, beacon already dropped
+ *   onUndecryptable()     someone in the room on another secret — not an error
+ */
+export function open({ session, name, url, onClip, onUndecryptable, onState, timeoutMs = 0 }) {
+  return new Promise((resolve, reject) => {
+    let off = null;
+    const timer = setTimeout(() => {
+      off?.();                       // or the subscription outlives every failed open
+      reject(new Error("the relay did not answer"));
+    }, Math.max(timeoutMs || 0, NET.PROBE_MS * 2.5));
+
+    off = on(EV.CONN_STATE, ({ state, detail }) => {
+      onState?.(state, detail);
+      if (state !== "connected") return;
+      clearTimeout(timer);
+      off();
+      resolve(session);
+    });
+
+    relay.setFrameHandler(async (msg) => {
+      if (msg.t !== proto.T.CLIP || !msg.payload) return;
+      let text;
+      try {
+        text = await cryptoBox.decrypt(session.aesKey, msg.payload, msg.iv);
+      } catch {
+        // Undecryptable means a different secret, not a corrupt relay: someone
+        // in the room on another PIN, or a stale frame from a rotated key.
+        onUndecryptable?.();
+        return;
+      }
+      // A control frame wearing a clip's clothes — it is what lets a joiner tell
+      // "wrong PIN" from "first one here". Compared against the constant, never
+      // "looks like a control character", which would also swallow a legitimate
+      // clip that happened to start with NUL.
+      if (text === LOCK.BEACON) return;
+      onClip?.(text, msg);
+    });
+
+    relay.connect({
+      roomHash: session.roomHash,
+      intent: "join",
+      name,
+      auth: session.auth,
+      ...(url ? { url } : {}),
+    });
+  });
+}
+
+/** Bytes, not characters: the frame cap is what the relay actually enforces. */
+export async function send(session, text, originId) {
+  if (!text) throw new Error("there is nothing to send");
+  if (textBytes(text) > TEXT.MAX_BYTES) {
+    throw new Error(`that is ${textBytes(text)} bytes; the limit is ${TEXT.MAX_BYTES}`);
+  }
+  const { payload, iv } = await cryptoBox.encrypt(session.aesKey, text);
+  return relay.send(proto.clip({ payload, iv, originId }));
+}
+
+/** Announce a room being abandoned, so nobody is left connected to nothing. */
+export async function evict(session, originId) {
+  try {
+    const { payload, iv } = await cryptoBox.encrypt(session.aesKey, LOCK.EVICT);
+    relay.send(proto.clip({ payload, iv, originId }));
+  } catch { /* leaving anyway */ }
+}
+
+/** Is the room actually usable right now? Callers that reconnect on demand ask
+ *  this before tearing a live connection down and building it again. */
+export const isOpen = () => relay.isOpen();
+
+export function close() {
+  relay.setFrameHandler(() => {});
+  relay.close();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtimeclipboard",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Live clipboard sharing. Static frontend of native ES modules — development needs no build, and `npm run build` exists only to assemble the deploy. Nothing here is needed to READ the app.",
   "license": "MIT",
   "repository": {
@@ -34,19 +34,28 @@
     "node": ">=22"
   },
   "scripts": {
-    "verify": "node tests/unit/static-check.mjs && node tests/unit/relay-url.mjs && node tests/unit/lock.mjs && node tests/unit/files.mjs && node tests/unit/transfer.mjs && node tests/unit/clipsize.mjs && node tests/unit/syncmode.mjs && node tests/unit/pasteguard.mjs && node tests/dom/dialog.mjs && node tests/dom/whatsnew.mjs && node tests/dom/tiles.mjs && node tests/dom/guide.mjs && node tests/dom/editor.mjs && node tests/dom/offer.mjs",
-    "test": "npm run verify && node tests/dom/bundle.mjs && node tests/live/e2e.mjs && node tests/live/boot.mjs && node tests/live/boot.mjs --locked && node tests/live/fallback.mjs",
+    "verify": "node tests/unit/static-check.mjs && node tests/unit/relay-url.mjs && node tests/unit/lock.mjs && node tests/unit/files.mjs && node tests/unit/transfer.mjs && node tests/unit/clipsize.mjs && node tests/unit/syncmode.mjs && node tests/unit/pasteguard.mjs && node tests/unit/sharelink.mjs && node tests/unit/keyfloor.mjs && node tests/unit/adpolicy.mjs && node tests/unit/vscode-host.mjs && node tests/unit/browser-worker.mjs && node tests/dom/dialog.mjs && node tests/dom/theme.mjs && node tests/dom/whatsnew.mjs && node tests/dom/tiles.mjs && node tests/dom/guide.mjs && node tests/dom/links.mjs && node tests/dom/editor.mjs && node tests/dom/capture.mjs && node tests/dom/offer.mjs",
+    "test": "npm run verify && npm run build:vscode && npm run build:mcp && npm run build:browser && node tests/dom/bundle.mjs && node tests/dom/extension.mjs && node tests/live/vscode.mjs && node tests/live/mcp.mjs && node tests/live/cli.mjs && node tests/live/e2e.mjs && node tests/live/boot.mjs && node tests/live/boot.mjs --locked && node tests/live/boot.mjs --qr && node tests/live/boot.mjs --locked --qr && node tests/live/fallback.mjs",
     "test:static": "node tests/unit/static-check.mjs",
     "test:lock": "node tests/unit/lock.mjs && node tests/dom/dialog.mjs",
     "test:e2e": "node tests/live/e2e.mjs",
-    "test:boot": "node tests/live/boot.mjs && node tests/live/boot.mjs --locked",
+    "test:boot": "node tests/live/boot.mjs && node tests/live/boot.mjs --locked && node tests/live/boot.mjs --qr && node tests/live/boot.mjs --locked --qr",
     "test:bundle": "node tests/dom/bundle.mjs",
+    "test:vscode": "node tools/build/build-vscode.mjs && node tests/dom/extension.mjs && node tests/live/vscode.mjs",
     "test:tiles": "node tests/dom/tiles.mjs",
     "test:fallback": "node tests/live/fallback.mjs",
     "test:cli": "node tests/live/cli.mjs",
+    "test:mcp": "node tests/live/mcp.mjs",
+    "test:editor": "node tests/editor/host.mjs",
     "build": "node tools/build/build.mjs",
     "build:site": "node tools/build/build.mjs _site && node tools/check/site-check.mjs _site",
-    "build:desktop": "node tools/build/build.mjs _desktop --desktop",
+    "size:record": "node tools/build/build.mjs _site --record-size",
+    "build:desktop": "node tools/build/build.mjs _desktop --desktop && node tools/check/desktop-check.mjs _desktop",
+    "build:vscode": "node tools/build/build-vscode.mjs",
+    "build:browser": "node tools/build/build-browser.mjs",
+    "build:mcp": "node tools/build/build-mcp.mjs",
+    "package:browser": "node tools/build/build-browser.mjs --zip",
+    "package:vscode": "node tools/build/build-vscode.mjs --package",
     "build:og": "python tools/build/build-og-card.py",
     "check:og": "python tools/build/build-og-card.py --check",
     "build:icons": "python tools/build/build-icons.py",

package/src/core/README.md

@@ -9,7 +9,7 @@ and the node test suites run these files unchanged.
 | `config.js` | Every tunable constant, the relay address, and the crypto parameters |
 | `state.js` | Session state and the setters that announce changes |
 | `crypto.js` | Room hashing, PBKDF2/HKDF derivation, AES-GCM. No libraries |
-| `keys.js` | Share-key generation, normalisation, and the URL fragment |
+| `keys.js` | Share-key generation, normalisation, the URL fragment, and the link a peer opens |
 | `storage.js` | localStorage, wrapped so a disabled-storage browser degrades instead of throwing |
 | `paths.js` | Where the app is served from, resolved once for the whole codebase |
 | `device.js` | A human-readable name for this device, shown in the peer list |

package/src/core/bus.js

@@ -38,7 +38,7 @@ export const EV = {
   TEXT_STREAMED:   "text:streamed",    // {text, caret, name, from} in
   TIER_CHANGED:    "clipboard:tier",   // {tier, note}
   PENDING_CLIP:    "clipboard:pending",// {pending, text} — arrived while unfocused
-  CLIP_OFFERED:    "clipboard:offered",// {text} — arrived, but the editor has unsent work
+  CLIP_OFFERED:    "clipboard:offered",// {text, onClipboard} — arrived over unsent work; text:null retracts the offer
   PEER_JOINED:     "peers:joined",     // {name} — a device entered the session
   PEER_LEFT:       "peers:left",       // {name}
   PERMISSION:      "clipboard:permission", // {state} granted|prompt|denied
@@ -64,6 +64,10 @@ export const EV = {
   // from LOCK_STATE because `state.locked` is still false: no session was ever
   // opened to be locked.
   LOCK_REQUIRED:   "session:lockrequired",
+  // {key, reason} — a key was named and refused before any connection opened.
+  // Like LOCK_REQUIRED there is no session behind it, and for the same reason:
+  // the app must not look usable when nothing it does would go anywhere.
+  KEY_REJECTED:    "session:keyrejected",
   FOUNDER:         "session:founder",  // {founder} — first into this room? null = not yet known
 
   // files