realtimeclipboard 0.3.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

@@ -1,7 +1,7 @@
 # RealtimeClipboard — an end-to-end encrypted online clipboard that syncs text between devices
 
 RealtimeClipboard is a free, open-source online clipboard: open it on two devices, type the
-same five-character key, and whatever you copy on one is ready to paste on the
+same short key, and whatever you copy on one is ready to paste on the
 other. No account, no install, no database. Files travel peer-to-peer and never
 touch the server.
 
@@ -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.
 
@@ -28,8 +28,9 @@ 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 five-character key is the whole identity of a session
-- **End-to-end encrypted** in the browser with AES-GCM; `PBKDF2` derives the key, `SHA-256` routes the room
+- **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
@@ -40,7 +41,7 @@ is proven, and [Known limitations](#known-limitations) for what is not.
 
 Moving a snippet between a work laptop, a desktop and a phone is
 disproportionately annoying. The alternatives want an account, an install with
-admin rights, or an email to yourself. This wants a five-character key.
+admin rights, or an email to yourself. This wants a short key.
 
 ## How RealtimeClipboard compares to Snapdrop, PairDrop, LocalSend and AirDrop
 
@@ -70,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.
@@ -85,7 +86,7 @@ with a short key, and share a single clipboard between them.
 
 ### How do I sync my clipboard between my phone and my PC?
 
-Open RealtimeClipboard on both, type the same five-character key on each, and copy
+Open RealtimeClipboard on both, type the same short key on each, and copy
 something. It arrives on the other device ready to paste. Nothing to install, so
 it works on a machine where you do not have admin rights.
 
@@ -207,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 |
@@ -235,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.
@@ -55,7 +56,14 @@ const VERSION = JSON.parse(
 /* ------------------------------------------------------------------ args -- */
 
 function parse(args) {
-  const opts = { relay: null, pin: null, once: false, json: false, timeout: 0, quiet: false };
+  const opts = {
+    relay: null, pin: null, once: false, json: false, timeout: 0, quiet: false,
+    // A CLI key gets pasted into shells, scripts and CI configs, where length is
+    // friction with no QR code to fall back on — so unlike the installed desktop
+    // app this stays short unless asked. REALTIMECLIPBOARD_LONG is the way to
+    // ask once, for a machine that generates a lot of them.
+    long: !!process.env.REALTIMECLIPBOARD_LONG,
+  };
   const rest = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -86,6 +94,8 @@ Options
   --relay <url>    relay to use            (default ${DEFAULT_RELAY_URL})
                    or set REALTIMECLIPBOARD_RELAY
   --pin <pin>      join a locked session   (or set REALTIMECLIPBOARD_PIN)
+  --long           new: a 10-character key (~49 bits) instead of 6 (~29 bits)
+                   or set REALTIMECLIPBOARD_LONG
   --once           watch: exit after the first clip
   --json           one JSON object per line instead of raw text
   --timeout <s>    give up after this many seconds
@@ -105,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) {
@@ -129,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 };
 }
 
 /**
@@ -223,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.3.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/dom/dialog.mjs && node tests/dom/whatsnew.mjs && node tests/dom/tiles.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();
@@ -31,8 +29,13 @@ export function emit(event, payload) {
 /** Canonical event names. Typos here are silent bugs, so use the constants. */
 export const EV = {
   // clipboard
-  TEXT_CAPTURED:   "text:captured",    // {text, how} — local capture, needs sending
-  TEXT_RECEIVED:   "text:received",    // {text, from} — arrived from a peer
+  TEXT_CAPTURED:   "text:captured",    // {text, how} — a clip settled here, needs sending
+  TEXT_RECEIVED:   "text:received",    // {text, from} — a clip arrived from a peer
+  // 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
@@ -53,23 +56,14 @@ 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",
+  // 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
 
   // files