realtimeclipboard 0.7.0 → 1.0.0

package/README.md

@@ -26,16 +26,16 @@ proven.
 
 ## What it does
 
-- **Sync clipboard text between devices** — Windows, macOS, Android, ChromeOS and Linux
-- **Works across different networks**, not just the same Wi-Fi, and not just the same LAN
-- **No account, no sign-up, no email** — a short key is the whole identity of a session
+- Syncs clipboard text between Windows, macOS, Android, ChromeOS and Linux
+- Works across different networks, not just the same Wi-Fi and not just the same LAN
+- No account, no sign-up, no email. A short key is the whole identity of a session
   (ten characters on the web, sixteen in the installed apps, and either works on both)
-- **End-to-end encrypted** in the browser with AES-GCM; one `PBKDF2` derivation produces both the key and the room address
-- **Peer-to-peer file transfer** over a WebRTC data channel, 5 MB per file
-- **Copy and paste images** — a screenshot copied on one machine previews on the other
-- **Installable progressive web app** — own window, own icon, works offline
-- **Nothing written to disk**, on your machine or the server
-- **Self-hostable relay** — it is one small FastAPI service
+- End-to-end encrypted in the browser with AES-GCM; one `PBKDF2` derivation produces both the key and the room address
+- Peer-to-peer file transfer over a WebRTC data channel, 5 MB per file
+- Copy and paste images: a screenshot copied on one machine previews on the other
+- Installable progressive web app, with its own window and icon, and it works offline
+- Nothing written to disk, on your machine or the server
+- Self-hostable relay, one small FastAPI service
 
 ## Why
 
@@ -138,7 +138,7 @@ desktop/                Tauri shell around this very src/ — no second implemen
 assets/                 icons/ (precached whole) + social/ (the OG card, never)
 tests/                  unit/ needs nothing · dom/ needs jsdom · live/ needs a relay
 tools/                  build/ · check/ · release/ · seo/
-docs/                   PRD, architecture, clipboard design, P2P design, SEO
+docs/                   PRD, architecture, clipboard design, P2P design, threat model
 ```
 
 A directory **at the root** is served at its own path — `assets/icons/icon.svg` is

package/cli/CLAUDE.md

@@ -25,4 +25,11 @@ end up subtly and silently disagreeing.
   already wrong — the package said 0.2.1 while `--version` said 0.1.0.
 - `package.json` `files:` ships `cli/`, `src/core/` and `src/transport/`. Importing anything outside
   those three from here breaks the published package, and only after publish.
+- **`session.mjs` acts on its own initiative in exactly one place**, and that place needs the
+  caller's permission. Everything else in it runs because a surface asked — it sends when told,
+  closes when told. The lock-verification responder answers a frame off the wire with nobody in the
+  loop, so it takes a `sharing` predicate (VS Code has an Off rung; the other three do not) and
+  carries a session generation, because producing an answer spans two awaits and the surface can
+  leave, be evicted, or rejoin on another key inside either. Anything else added here that
+  transmits unprompted needs both. `tests/unit/shared-session.mjs`.
 - `tests/live/cli.mjs` runs this against a real relay, and `prepublishOnly` runs that suite.

package/cli/realtimeclipboard.mjs

@@ -47,6 +47,13 @@ import { INVISIBLE_SOURCE } from "../src/core/text.js";
  * itself and never goes through the bundler, so its depth in the tree is fixed.
  * npm always includes package.json in a tarball, so this resolves after install.
  */
+/**
+ * This process's id in the room. One per run, not one per clip: it is how peers
+ * recognise our own frames coming back, and how a locked room's verification
+ * answer is attributed.
+ */
+const ORIGIN = `cli-${Date.now().toString(36)}`;
+
 const VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 ).version;
@@ -158,6 +165,9 @@ const forTerminal = text => (stdout.isTTY ? text.replace(TERMINAL_UNSAFE, "") :
 
 const note = (msg, opts) => { if (!opts.quiet) stderr.write(`${msg}\n`); };
 
+/** How long EOF waits for queued lines to finish leaving. */
+const DRAIN_MS = 5_000;
+
 function die(msg, code = 1) {
   stderr.write(`realtimeclipboard: ${msg}\n`);
   exit(code);
@@ -187,6 +197,7 @@ function connect(sess, opts, onClip) {
   return room.open({
     session: sess,
     name: `cli@${hostname()}`,
+    originId: ORIGIN,
     url: url ? normaliseRelay(url) : undefined,
     timeoutMs: opts.timeout || 0,
     onClip,
@@ -195,14 +206,17 @@ function connect(sess, opts, onClip) {
   });
 }
 
-async function sendText(sess, text, opts) {
-  if (!text) die("nothing on stdin to send", 2);
+/**
+ * Throws rather than exiting. `send` is one shot and dies on a failure, but
+ * two-way mode has a session to keep: killing the process on one refused line
+ * would drop the reader half too.
+ */
+async function sendText(sess, text) {
+  if (!text) throw new Error("nothing on stdin to send");
   if (text.length > TEXT.MAX_CHARS) {
-    die(`that is ${text.length} characters; the limit is ${TEXT.MAX_CHARS}`, 2);
+    throw new Error(`that is ${text.length} characters; the limit is ${TEXT.MAX_CHARS}`);
   }
-  try {
-    await room.send(sess, text, `cli-${Date.now().toString(36)}`);
-  } catch (err) { die(err.message, 2); }
+  await room.send(sess, text, ORIGIN);
   // 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));
@@ -283,7 +297,9 @@ try {
 note("  connected", opts);
 
 if (cmd === "send") {
-  await sendText(session, await readStdin(), opts);
+  try {
+    await sendText(session, await readStdin());
+  } catch (err) { die(err.message, 2); }
   relay.close();
   exit(0);
 }
@@ -297,11 +313,30 @@ if (cmd === "both") {
   // 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();
+  let failed = false;
   rl.on("line", line => {
     if (!line.length) return;
-    sending = sending.then(() => sendText(session, line, opts)).catch(() => {});
+    sending = sending
+      .then(() => sendText(session, line))
+      .catch(err => { failed = true; note(`  ${err.message}`, opts); });
+  });
+
+  // Drained, not abandoned. `close` fires the moment stdin ends, and calling
+  // exit() there killed the chain mid-flight: piping three lines in sent none of
+  // them, because the first was still being encrypted — and the exit status said
+  // it had worked. Bounded, so a wedged relay cannot hold the process open.
+  rl.on("close", async () => {
+    // Which of the two won matters: the timeout winning means lines are still
+    // unsent, and exiting 0 there reports a success that did not happen — the
+    // same overstatement as the send path that ignored its own return value.
+    const drained = await Promise.race([
+      sending.then(() => true, () => true),
+      new Promise(done => setTimeout(() => done(false), DRAIN_MS)),
+    ]);
+    relay.close();
+    if (!drained) note("  timed out with lines still unsent", opts);
+    exit(failed || !drained ? 4 : 0);
   });
-  rl.on("close", () => { relay.close(); exit(0); });
 }
 
 for (const sig of ["SIGINT", "SIGTERM"]) {

package/cli/session.mjs

@@ -26,6 +26,19 @@ 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";
+import { sealWith, openWith } from "../src/core/frames.js";
+
+/**
+ * Which room this module is currently in. Bumped by open() and close(), and
+ * therefore by eviction, which goes through close().
+ *
+ * It exists for the one thing here that outlives the frame it started from: a
+ * verification answer takes two awaits to produce, and both of them are long
+ * enough for the surface to have left the room, rejoined on another key, or
+ * been evicted from it. Sealed with the old key and sent into the new room,
+ * that answer is undecryptable noise attributed to this device.
+ */
+let epoch = 0;
 
 /**
  * Everything needed to talk in a room, derived exactly as the browser derives
@@ -41,8 +54,14 @@ export async function derive(rawKey, pin) {
   if (refused) throw new Error(`"${rawKey}" cannot be used — ${refused}`);
 
   if (pin) {
+    // Length, not truthiness. A one-character PIN passed this and derived a real
+    // locked room that the web PIN dialog then refused to join, because it
+    // enforces the floor on every mode — so these clients could create sessions
+    // no browser could open, with a secret worth a couple of bits.
     const clean = cryptoBox.normalisePin(pin);
-    if (!clean) throw new Error(`a PIN needs at least ${LOCK.MIN_PIN} characters`);
+    if (clean.length < LOCK.MIN_PIN) {
+      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 };
   }
@@ -58,10 +77,29 @@ export async function derive(rawKey, pin) {
  * 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
+ *   onClip(text, frame)   decrypted, control frames already dropped
+ *   onEvicted()           the room was abandoned; the connection is ALREADY shut
  *   onUndecryptable()     someone in the room on another secret — not an error
+ *
+ * `originId` is this surface's own id — the same one it passes to send(). It is
+ * wanted here because a locked room's verification is answered from inside this
+ * handler, with no caller to ask.
+ *
+ * `sharing` is that answer's rung gate. Defaulted to "yes" rather than made
+ * required, and the default is correct rather than convenient: the CLI, the MCP
+ * server and the browser extension have no Off rung to consult — every one of
+ * their sessions exists because somebody asked for it. VS Code does have one,
+ * and passes it. See vscode/src/room.mjs.
  */
-export function open({ session, name, url, onClip, onUndecryptable, onState, timeoutMs = 0 }) {
+export function open({
+  session, name, url, originId, sharing = () => true,
+  onClip, onEvicted, onUndecryptable, onState, timeoutMs = 0,
+}) {
+  // A rejoin is a different room, even on the same key — re-PINning keeps the
+  // key and moves the room. Anything still in flight for the last one is now
+  // answering a question nobody asked.
+  const mine = ++epoch;
+
   return new Promise((resolve, reject) => {
     let off = null;
     const timer = setTimeout(() => {
@@ -78,6 +116,9 @@ export function open({ session, name, url, onClip, onUndecryptable, onState, tim
     });
 
     relay.setFrameHandler(async (msg) => {
+      if (msg.t === proto.T.VERIFY) {
+        return answerVerify({ session, msg, originId, sharing, mine });
+      }
       if (msg.t !== proto.T.CLIP || !msg.payload) return;
       let text;
       try {
@@ -93,6 +134,21 @@ export function open({ session, name, url, onClip, onUndecryptable, onState, tim
       // "looks like a control character", which would also swallow a legitimate
       // clip that happened to start with NUL.
       if (text === LOCK.BEACON) return;
+
+      // The other control frame, and it was not filtered — it reached callers as
+      // clip text, so the sentinel was printed to stdout by the CLI, recorded as
+      // a clip for the model by the MCP server, and put on the extension's badge.
+      // Every one of them then stayed connected to a room the owner had left.
+      //
+      // Closed here rather than left to each surface: "stop talking to a room
+      // nobody is in" is not a per-client decision, and three of the four
+      // clients did not know they had to make it.
+      if (text === LOCK.EVICT) {
+        close();
+        onEvicted?.();
+        return;
+      }
+
       onClip?.(text, msg);
     });
 
@@ -106,6 +162,42 @@ export function open({ session, name, url, onClip, onUndecryptable, onState, tim
   });
 }
 
+/**
+ * Prove a locked room to whoever asked.
+ *
+ * These four surfaces are frequently the ONLY other device in a room — a phone
+ * on the web app plus a terminal, plus nothing else — and a locked session
+ * cannot confirm its PIN without a peer that answers. Silent here, and the
+ * browser at the other end sits on "the PIN may not match theirs" for the whole
+ * session while the CLI it is talking to reads every clip perfectly.
+ *
+ * `probe !== true` is the loop guard, and it is the same one the app uses: an
+ * answer is never answered.
+ *
+ * Both gates are re-read at every step rather than once at the top, because
+ * there are two awaits here and each is a window: the rung can come down and
+ * the room can change inside either.
+ *
+ * The rung is checked BEFORE the decryption, which is where this deliberately
+ * differs from the app (src/main.js, case proto.T.VERIFY). There, opening the
+ * frame is what sets `verified`, so an Off device is entitled to do it — the
+ * rung governs what reaches the user, not what the session knows. Here nothing
+ * is learned from opening it: the only thing this function produces is a frame
+ * on the wire, so a surface that has said nothing leaves has no reason to start
+ * decrypting.
+ */
+async function answerVerify({ session, msg, originId, sharing, mine }) {
+  if (!session.locked || !sharing() || mine !== epoch) return;
+
+  const frame = await openWith(session.aesKey, msg);
+  if (!sharing() || mine !== epoch) return;
+  if (!frame || frame.probe !== true) return;
+
+  const answer = await sealWith(session.aesKey, proto.verify({ probe: false, originId }));
+  if (!sharing() || mine !== epoch) return;
+  relay.send(answer);
+}
+
 /** 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");
@@ -113,7 +205,15 @@ export async function send(session, text, originId) {
     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 }));
+  // The relay's boolean means "handed to an open socket", and every caller
+  // ignored it: the CLI exited 0 having sent nothing, the MCP server told the
+  // model the clip was delivered, and the extension said "Sent N characters."
+  // — all while disconnected. A throw is the one result none of them can drop
+  // by accident, and each already reports a thrown error.
+  if (!relay.send(proto.clip({ payload, iv, originId }))) {
+    throw new Error("not connected to the relay — nothing was sent");
+  }
+  return true;
 }
 
 /** Announce a room being abandoned, so nobody is left connected to nothing. */
@@ -129,6 +229,10 @@ export async function evict(session, originId) {
 export const isOpen = () => relay.isOpen();
 
 export function close() {
+  // Before the socket, not after: a response mid-seal must be abandoned even
+  // though relay.send() would refuse it anyway, because the next open() may
+  // have handed the transport a new room by the time that seal resolves.
+  epoch++;
   relay.setFrameHandler(() => {});
   relay.close();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtimeclipboard",
-  "version": "0.7.0",
+  "version": "1.0.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": {
@@ -26,6 +26,7 @@
   "files": [
     "cli/",
     "src/core/",
+    "!src/core/lang/",
     "src/transport/",
     "LICENSE",
     "README.md"
@@ -34,7 +35,7 @@
     "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/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",
+    "verify": "node tests/unit/static-check.mjs && node tools/i18n/build-pages.mjs --check && node tools/i18n/app-strings.mjs --check && node tests/unit/i18n.mjs && node tests/unit/relay-url.mjs && node tests/unit/lock.mjs && node tests/unit/session-boundaries.mjs && node tests/unit/verify.mjs && node tests/unit/shared-session.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/unit/browser-popup.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",
@@ -49,6 +50,8 @@
     "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",
+    "i18n:pages": "node tools/i18n/build-pages.mjs",
+    "i18n:app": "node tools/i18n/app-strings.mjs",
     "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",

package/src/core/CLAUDE.md

@@ -36,3 +36,7 @@ runs these exact modules. Two consequences:
   there. The active session lives in `sessionStorage` and dies with the tab.
 - `text.js` is a security character class with three consumers that may not import each other. It
   belongs here for that reason, and the ranges in it are not a style preference — see the comment.
+- **`verify.js` and `frames.js` take their seams injected, not imported.** A frame shape and the
+  transport are both rank 10, so neither is reachable from here — but the reason to keep it that
+  way is that every rule in them is then exercisable from a plain node test. Both were four lines
+  in the composition root first, and four lines in `main.js` can only be checked by reading them.

package/src/core/bus.js

@@ -52,10 +52,10 @@ export const EV = {
   PEERS_CHANGED:   "peers:changed",    // {count, list}
   INSTANCE_CHANGED:"conn:instance",    // {from, to} — split-brain warning (OI-3)
   KEY_COLLISION:   "session:collision",// generated key was taken (OI-2)
-  ROOM_STATE:      "conn:room",        // {existing, hasLast} — what `welcome` said
+  ROOM_STATE:      "conn:room",        // {existing} — what `welcome` said
 
   // session
-  KEY_CHANGED:     "session:key",      // {key, locked}
+  KEY_CHANGED:     "session:key",      // {key, locked, roomHash}
   // Announcements are past tense, commands are bare verbs, and the extra
   // syllable here is load-bearing — see core/CLAUDE.md. The bus does no
   // namespacing of its own, so a collision between the two is silent.

package/src/core/config.js

@@ -63,6 +63,40 @@ export const RELAY_URL =
 /** True when the app is not talking to the relay it was built against. */
 export const RELAY_IS_CUSTOM = RELAY_URL !== DEFAULT_RELAY_URL && RELAY_URL !== LOCAL_RELAY_URL;
 
+/**
+ * The organisation token for a relay that runs with REALTIMECLIPBOARD_JOIN_TOKEN set.
+ *
+ * Such a relay refuses every join that does not present `?org=`, and no client
+ * had any way to send one — so turning the setting on, which SELF-HOSTING.md
+ * tells operators to do to stop their relay being open to anyone who learns the
+ * hostname, bricked every shipped client instead of restricting it.
+ *
+ * Deliberately NOT in the share link: a link is pasted into chats and read off
+ * screens, and this is the credential that admits a device to the deployment.
+ * It is configured once per device — `?org=` on first load, which is persisted,
+ * or REALTIMECLIPBOARD_ORG for the CLI and MCP server.
+ */
+const ORG_KEY = "orgToken";
+
+/** The query parameter that carries it. Named once — safeSearch() strips it. */
+export const ORG_PARAM = "org";
+const storedOrg = () => {
+  try { return JSON.parse(localStorage.getItem(STORAGE_PREFIX + ORG_KEY)); }
+  catch { return null; }
+};
+const orgFromQuery = () => {
+  try { return new URLSearchParams(location.search).get(ORG_PARAM); }
+  catch { return null; }
+};
+const orgFromEnv = () => {
+  try { return globalThis.process?.env?.REALTIMECLIPBOARD_ORG || null; }
+  catch { return null; }
+};
+const cleanOrg = v => (typeof v === "string" && v.trim() ? v.trim() : null);
+
+export const ORG_TOKEN = cleanOrg(orgFromQuery()) ?? cleanOrg(orgFromEnv()) ?? cleanOrg(storedOrg());
+export const ORG_STORAGE_KEY = ORG_KEY;
+
 /**
  * The same relay over plain HTTP, for the SSE+POST fallback and /stats. One
  * hostname so IT allowlists one domain (PRD §5.4); derived so the two cannot drift.
@@ -146,8 +180,13 @@ export const PASTE_GUARD = {
   ENABLED: true,
 
   /**
-   * Past this, do not scan. The patterns are anchored per line, so a pasted
-   * logfile is a lot of backtracking for a case this does not defend against.
+   * The longest LINE the scanner will look at. Every pattern is anchored to the
+   * start of a line and none spans one, so the scan runs per line and this
+   * bounds the work any single regex does.
+   *
+   * A line past it is treated as risky rather than safe. This was once a cap on
+   * the whole clip, above which nothing was scanned at all — and it sat below
+   * the clip size limit, so padding a command past it turned the guard off.
    */
   MAX_SCAN_CHARS: 8_192,
 };
@@ -188,6 +227,17 @@ export const FILES = {
    * wedged association must not hold a transfer open.
    */
   CHANNEL_CLOSE_MS: 1_000,
+
+  /**
+   * How long a sender waits for the receiver to confirm it has the file, whole
+   * and verified, before reporting what it actually knows.
+   *
+   * "Sent" used to mean "the last frame was handed to a socket". A digest
+   * failure at the far end was reported to nobody, so the holder's tile said
+   * the transfer had worked while the other device showed an error. Bounded,
+   * because a receiver that vanishes must not leave a progress bar up forever.
+   */
+  RECEIPT_MS: 10_000,
 };
 
 export const KEY = {
@@ -291,8 +341,21 @@ export const LOCK = {
   SIGIL: "!",
 
   /**
-   * Sent on creating a locked room and replayed to joiners, so a joiner can tell
-   * "wrong PIN" from "first one here" by whether it decrypts. Receivers drop it.
+   * READ, never written. Locked sessions used to prove themselves by planting
+   * this as a clip: the relay retains one clip per room and replays it, so a
+   * joiner that decrypted it had proved its PIN before any peer was awake.
+   *
+   * It worked and it cost too much. The proof took the room's single retained
+   * slot, so it either destroyed the last thing the user copied or, once the
+   * plant started honouring the sync rung, silently never happened — and the
+   * two guards that stopped those cases could not both hold. Verification is
+   * now its own frame (`proto.verify`), forwarded and not retained.
+   *
+   * Still recognised on arrival, because a client older than that change is
+   * still planting one, and a sentinel that reached the editor would be
+   * printed, put on the OS clipboard and written to history as a clip.
+   * Compared against the constant, never "starts with NUL", which would also
+   * swallow a legitimate clip.
    */
   BEACON: String.fromCharCode(0) + "realtimeclipboard-lock-v1",
 
@@ -314,10 +377,30 @@ export const LOCK = {
    * that needs the fallback.
    */
   EVICT_FLUSH_MS: 250,
+
+  /**
+   * Floor between two verification probes. Not a retry timer — every trigger
+   * is an event worth asking on (a peer arrived, the rung came off Off) and
+   * roster churn can fire several in a second. One question per interval is
+   * plenty: a peer that can answer answers immediately, and a peer that cannot
+   * will not answer the second one either.
+   */
+  VERIFY_MIN_INTERVAL_MS: 3_000,
 };
 
 export const NET = {
   HEARTBEAT_MS: 30_000,       // must beat proxy idle reaping (PRD 5.4, FR-3.6)
+
+  /**
+   * How long a ping may go unanswered before the connection is treated as dead.
+   *
+   * A socket can sit at readyState OPEN with nothing at the other end: no
+   * error, no close, and the session reads "connected" for as long as the tab
+   * is left open. The ping had no deadline at all, so nothing ever noticed.
+   * Generous against a slow phone network, short enough that a dead session
+   * reconnects rather than sits.
+   */
+  PONG_DEADLINE_MS: 10_000,
   BACKOFF_MIN_MS: 1_000,
   BACKOFF_MAX_MS: 30_000,
   ICE_TIMEOUT_MS: 5_000,      // then fall back to relay chunks (FR-7.6)
@@ -482,7 +565,8 @@ export const LAYOUT = {
  * removed 2026-08-09). The ad tag reports the page URL itself with no override,
  * so what survives is TIMING: ui/features/ads.js must never load it while the
  * share key is still in `location.hash`, and waits for keys.clearUrl(). gtag
- * takes `page_location` from `pageLocation()` below, which strips it too. !!
+ * takes `page_location` from `pageLocation()` below, which strips it too — and
+ * strips `?org=` with it, a credential rather than a room name. !!
  *
  * Adding an origin means adding it to the CSP in _headers AND every page's meta
  * tag — app.html's included — which tools/check/site-check.mjs asserts agree.
@@ -570,6 +654,32 @@ export const CONSENT_REGIONS = [
  * `page_location` is `location.href` — the unmodified tag would send the key to
  * Google on the first page_view. Every gtag config passes this instead. !!
  */
+/**
+ * `location.search` with the deployment credential taken out.
+ *
+ * `?org=` admits a device to a self-hosted relay, and it rides in the query
+ * because a browser cannot set a header on a WebSocket or an EventSource. That
+ * put it in `location.search` — which is exactly what gtag's `page_location`
+ * sends, and what AdSense reads off the page for itself. A deployment that
+ * turned the token on was handing it to Google on the first page_view.
+ *
+ * Fails CLOSED: anything unparseable yields no query at all rather than the
+ * original string, because the string is the thing under suspicion.
+ */
+export function safeSearch(search) {
+  const raw = search ?? (typeof location === "undefined" ? "" : location.search);
+  if (!raw) return "";
+  try {
+    const q = new URLSearchParams(raw);
+    if (!q.has(ORG_PARAM)) return raw;
+    q.delete(ORG_PARAM);
+    const rest = q.toString();
+    return rest ? `?${rest}` : "";
+  } catch {
+    return "";
+  }
+}
+
 export const pageLocation = () => {
   if (typeof location === "undefined") return "";
   /* The desktop webview answers at `tauri.localhost` on Windows and
@@ -580,7 +690,7 @@ export const pageLocation = () => {
      on-disk name is not the name a report should show. Which surface a hit came
      from is `rtc_surface`, not the hostname. */
   if (IS_DESKTOP) return `${SITE.ORIGIN}/app`;
-  return location.origin + location.pathname + location.search;
+  return location.origin + location.pathname + safeSearch();
 };
 
 export const GOOGLE_SRC = {