realtimeclipboard 0.4.0 → 0.5.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Akshay Nikhare
+Copyright (c) 2026 CadNative
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -16,9 +16,9 @@ touch the server.
                      (never touch the server)
 ```
 
-**Status: pre-alpha, and it works end to end.** The relay is deployed and live,
+**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
-17-check end-to-end suite runs two real peers with real crypto against 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.
 
@@ -29,8 +29,8 @@ is proven, and [Known limitations](#known-limitations) for what is not.
 - **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
-  (six characters on the web, ten in the installed apps, and either works on both)
-- **End-to-end encrypted** in the browser with AES-GCM; `PBKDF2` derives the key, `SHA-256` routes the room
+  (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
@@ -71,7 +71,7 @@ welcome — open an issue.
 | Text | WebSocket through the relay, AES-GCM encrypted in the browser |
 | Blocked networks | If a proxy eats the WebSocket, the client moves itself to SSE + POST on the same host and says so |
 | Files | WebRTC data channel, direct between peers, 5 MB cap |
-| Key | `SHA-256(key)` routes the room; `PBKDF2(key)` encrypts. The key itself is never transmitted |
+| Key | `PBKDF2(key)` is expanded with HKDF into the AES key and the room address. Neither the key nor anything reversible to it is transmitted |
 
 The relay only ever sees a room hash and ciphertext. It cannot decrypt anything,
 and it stores nothing beyond the last message in RAM.
@@ -208,13 +208,14 @@ message format the changelog is generated from are in
 ```bash
 npm run verify                       # what the pre-commit hook runs
 npm test                             # everything, needs a relay
-npm run release -- minor             # verify, changelog, tag, push, deploy
+npm run release -- minor             # verify, changelog, release PR, tag, deploy
 ```
 
 ## Docs
 
 | Doc | What it covers |
 |---|---|
+| [THREAT-MODEL.md](docs/THREAT-MODEL.md) | **What is protected and what is not, with the arithmetic.** Read this before trusting the encryption claim |
 | [PRD.md](docs/PRD.md) | Requirements, architecture, security model, open issues |
 | [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Running it locally, the test suite, the landing-page grid and globe, and the traps |
 | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Module layout, boundaries, and how to add a feature |
@@ -236,6 +237,11 @@ npm run release -- minor             # verify, changelog, tag, push, deploy
 - **P2P file transfer may fail on corporate networks**, which block the UDP that
   WebRTC needs. Falls back to relay-chunked transfer, labelled visibly.
 - **The share key is a bearer credential.** Anyone holding it can read the session.
+- **Share links created before v0.5.0 no longer work.** The room hash is now
+  derived through the same 250k PBKDF2 as the encryption key, and generated keys
+  went from 6 characters to 10. Both were needed to stop the relay operator being
+  able to reverse a room hash back to a share key — the reasoning and the
+  arithmetic are in [THREAT-MODEL.md §4](docs/THREAT-MODEL.md).
 - Chromium-first. Firefox and Safari can receive and can send via paste, but
   cannot silently read the clipboard.
 

package/cli/realtimeclipboard.mjs

@@ -33,6 +33,7 @@ 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 { INVISIBLE_SOURCE } from "../src/core/text.js";
 
 /**
  * Read from package.json rather than written here.
@@ -114,6 +115,49 @@ ever sees a room hash and ciphertext.`;
 
 /* ---------------------------------------------------------------- output -- */
 
+/**
+ * Escape sequences, stripped from clip text before it reaches a terminal.
+ *
+ * A clip is written by whoever else is in the room, and printing it raw hands
+ * them the terminal's own control channel. That is not theoretical: OSC 52 sets
+ * the TERMINAL's clipboard, so `realtimeclipboard watch` printing an untrusted
+ * clip is a pastejacking primitive against the machine running it — the exact
+ * attack src/clipboard/guard.js exists to stop in the browser. Others retitle
+ * the window, or use a bare CR to redraw the tail of a line over its head so
+ * that what is displayed is not what was sent.
+ *
+ * Built from strings so this file contains no literal control characters — a
+ * literal one is invisible in a diff, which is the property being defended
+ * against.
+ *
+ *   CSI   ESC [ … final byte   colours, cursor movement
+ *   OSC   ESC ] … BEL or ST    window title, and clipboard writes
+ *   two-character escapes, then any ESC left over
+ *   INVISIBLE_SOURCE          the single characters, shared with the browser
+ *                             halves via core/text.js. A terminal needs the
+ *                             sequences above ON TOP of that class, not instead
+ *                             of it, which is why this composes rather than
+ *                             redefining the ranges.
+ */
+const TERMINAL_UNSAFE = new RegExp([
+  "\\u001B\\[[0-9;?]*[ -/]*[@-~]",
+  "\\u001B\\][^\\u0007\\u001B]*(?:\\u0007|\\u001B\\\\)",
+  "\\u001B[@-Z\\\\-_]",
+  "\\u001B",
+  INVISIBLE_SOURCE,
+].join("|"), "g");
+
+/**
+ * Only when stdout is a terminal.
+ *
+ * A pipe is not a terminal and has no control channel to hijack, and the
+ * documented uses of this tool are pipes — `watch KEY > clip.txt`,
+ * `--json | jq`. Rewriting bytes there would corrupt the payload to defend
+ * against a threat that is not present. `--json` is additionally safe by
+ * construction: JSON.stringify escapes every one of these.
+ */
+const forTerminal = text => (stdout.isTTY ? text.replace(TERMINAL_UNSAFE, "") : text);
+
 const note = (msg, opts) => { if (!opts.quiet) stderr.write(`${msg}\n`); };
 
 function die(msg, code = 1) {
@@ -138,13 +182,8 @@ async function derive(rawKey, pin) {
     const d = await cryptoBox.deriveLocked(key, clean);
     return { key, roomHash: d.roomHash, aesKey: d.aesKey, auth: d.authToken, locked: true };
   }
-  return {
-    key,
-    roomHash: await cryptoBox.roomHash(key),
-    aesKey: await cryptoBox.deriveKey(key),
-    auth: null,
-    locked: false,
-  };
+  const open = await cryptoBox.deriveOpen(key);
+  return { key, roomHash: open.roomHash, aesKey: open.aesKey, auth: null, locked: false };
 }
 
 /**
@@ -232,7 +271,7 @@ const readStdin = () => new Promise(resolve => {
 const emitClip = (text, msg, opts) => stdout.write(
   opts.json
     ? `${JSON.stringify({ text, seq: msg.seq ?? null, origin: msg.originId ?? null, receivedAt: new Date().toISOString() })}\n`
-    : (text.endsWith("\n") ? text : `${text}\n`),
+    : (t => t.endsWith("\n") ? t : `${t}\n`)(forTerminal(text)),
 );
 
 /* ------------------------------------------------------------------ main -- */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtimeclipboard",
-  "version": "0.4.0",
+  "version": "0.5.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,7 +34,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/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",
+    "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",
     "test:static": "node tests/unit/static-check.mjs",
     "test:lock": "node tests/unit/lock.mjs && node tests/dom/dialog.mjs",
@@ -49,7 +49,10 @@
     "build:desktop": "node tools/build/build.mjs _desktop --desktop",
     "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",
+    "check:icons": "python tools/build/build-icons.py --check",
     "check:csp": "node tools/build/build.mjs _site && node tools/check/csp-check.mjs",
+    "seo:indexnow": "node tools/seo/indexnow.mjs",
     "relay": "python -m uvicorn main:app --app-dir backend --port 8000",
     "relay:up": "node tools/release/relay-up.mjs",
     "changelog": "node tools/release/changelog.mjs",

package/src/core/CLAUDE.md

@@ -27,5 +27,12 @@ runs these exact modules. Two consequences:
 - Event names are `EV.*` constants in `bus.js`. Adding an event means adding a constant.
 - A bus event that **reports** is never named the same as one that **commands** — `EV.LOCK_STATE`
   and `"session:lock"` once shared a name and every `setKey()` opened the PIN dialog by itself.
-- The share key and the session PIN are never logged, never stored, never transmitted. Only
-  `SHA-256(key)` and PBKDF2/HKDF output leave this directory.
+- The share key and the session PIN are never logged and never transmitted. Only `SHA-256(key)` and
+  PBKDF2/HKDF output leave this directory.
+- **The PIN is never stored. The share key is, and that is a decision with a switch on it.** This
+  file used to say neither was, and it was wrong about the key for as long as `saveLastKey()` has
+  existed — it writes the key to `localStorage` in plain text so a relaunch can offer the room back
+  (FR-1.7). `rememberKey` in `state.js` governs it, and turning it off removes what is already
+  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.

package/src/core/bus.js

@@ -1,9 +1,7 @@
 /**
- * Tiny pub/sub. The only way modules talk to each other.
- *
- * The rule that keeps this codebase modular: UI modules never import transport
- * or clipboard modules, and vice versa. They publish and subscribe to events
- * here. main.js is the only file that knows the full graph.
+ * Tiny pub/sub. The only way modules talk to each other — UI never imports
+ * transport or clipboard, and vice versa. main.js is the only file that knows
+ * the full graph.
  */
 
 const listeners = new Map();
@@ -33,16 +31,11 @@ export const EV = {
   // clipboard
   TEXT_CAPTURED:   "text:captured",    // {text, how} — a clip settled here, needs sending
   TEXT_RECEIVED:   "text:received",    // {text, from} — a clip arrived from a peer
-  /**
-   * Typing, not clips. {text, caret} out, {text, caret, name, from} in.
-   *
-   * The pair above is the COMMIT channel: a clip that settled, bound for
-   * history, the OS clipboard and the size cap. This pair is the VIEW channel —
-   * what the text looks like mid-keystroke. Keeping them apart is what stops a
-   * streamed sentence becoming six history entries and six clipboard writes.
-   */
-  TEXT_TYPED:      "text:typed",
-  TEXT_STREAMED:   "text:streamed",
+  // The VIEW channel — what the text looks like mid-keystroke. The pair above is
+  // the COMMIT channel. Keeping them apart is what stops a streamed sentence
+  // becoming six history entries and six clipboard writes.
+  TEXT_TYPED:      "text:typed",       // {text, caret} out
+  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
@@ -63,29 +56,13 @@ export const EV = {
 
   // session
   KEY_CHANGED:     "session:key",      // {key, locked}
-  /**
-   * {locked, verified} — see core/crypto.js.
-   *
-   * "lockstate", not "lock", and the extra syllable is load-bearing. The name
-   * used to be "session:lock", which is ALSO the imperative the UI emits to
-   * mean "lock this session" (main.js). One name, two opposite meanings: a
-   * report and an order. So every state.setKey() — one per session, on every
-   * single boot — delivered a report to the handler that acts on the order,
-   * and the app opened the "Lock this session" PIN dialog by itself the moment
-   * it started. Nothing failed, nothing was logged, and the dialog looked
-   * exactly like a feature.
-   *
-   * Announcements are past tense here (`session:key`, `peers:changed`) and
-   * commands are bare verbs (`session:lock`, `session:leave`). Keep it that
-   * way; the bus does no namespacing of its own and a collision is silent.
-   */
-  LOCK_STATE:      "session:lockstate",
-  /**
-   * {required} — a locked link is open and its PIN has not been given, so there
-   * is no session and nothing behind the UI is connected to anything. Reported
-   * separately from LOCK_STATE because `state.locked` is still false at that
-   * point: no session was ever opened to be locked.
-   */
+  // 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.
+  LOCK_STATE:      "session:lockstate",// {locked, verified} — see core/crypto.js
+  // {required} — a locked link is open and its PIN has not been given. Separate
+  // from LOCK_STATE because `state.locked` is still false: no session was ever
+  // opened to be locked.
   LOCK_REQUIRED:   "session:lockrequired",
   FOUNDER:         "session:founder",  // {founder} — first into this room? null = not yet known