realtimeclipboard 0.3.0 → 0.5.0

package/src/core/crypto.js

@@ -1,31 +1,20 @@
 /**
  * End-to-end encryption. All of it. No libraries.
  *
- * OPEN SESSION — the key the user types serves two purposes without the server
- * learning it:
+ *   OPEN    prk      = PBKDF2(KEY, salt, 250k)
+ *           aesKey   = HKDF(prk, "…/aes")
+ *           roomHash = HKDF(prk, "…/room")   -> sent
  *
- *   roomHash = SHA-256("realtimeclipboard:" + KEY)[0..16]   -> sent, routes the room
- *   aesKey   = PBKDF2(KEY, salt, 250k)             -> never leaves this browser
+ *   LOCKED  prk       = PBKDF2(PIN, "realtimeclipboard-lock-v1:" + KEY, 600k)
+ *           aesKey    = HKDF(prk, "…/aes")
+ *           roomHash  = HKDF(prk, "…/room")   -> sent
+ *           authToken = HKDF(prk, "…/auth")   -> sent, proves PIN knowledge
  *
- * LOCKED SESSION — a PIN that is never in the link, never on disk and never
- * sent anywhere. It is folded into ONE PBKDF2 run whose output is expanded by
- * HKDF into three independent values:
- *
- *   prk       = PBKDF2(PIN, salt = "realtimeclipboard-lock-v1:" + KEY, 600k)
- *   aesKey    = HKDF(prk, "…/aes")    -> AES-GCM-256
- *   roomHash  = HKDF(prk, "…/room")   -> sent, routes the room
- *   authToken = HKDF(prk, "…/auth")   -> sent, proves PIN knowledge to the relay
- *
- * The room hash requiring the PIN is the load-bearing part: it is what turns
- * "you cannot read it" into "you cannot find it". Someone holding the link but
- * not the PIN computes a different room hash, lands in a different room, and
- * never appears in the real one at all — no peer slot, no roster entry, no
- * traffic metadata. Locked and unlocked rooms with the same key are likewise
- * disjoint, so the two kinds of client can never meet and fail to decrypt each
- * other.
- *
- * The relay cannot derive the key from the hash, so it cannot decrypt. It sees
- * a room name and ciphertext, and nothing else. See PRD §7.3.
+ * The room hash requiring the PIN is the load-bearing part: it turns "you cannot
+ * read it" into "you cannot find it". Someone holding the link but not the PIN
+ * computes a different room hash and never appears in the real room at all — no
+ * peer slot, no roster entry, no traffic metadata. Locked and unlocked rooms of
+ * the same key are disjoint for the same reason. See PRD §7.3.
  */
 
 import { CRYPTO } from "./config.js";
@@ -34,89 +23,76 @@ const enc = new TextEncoder();
 const dec = new TextDecoder();
 
 /** Derivation is expensive (OI-8), so cache per key for the session. */
-let cached = { id: null, aesKey: null };
-
-export async function roomHash(key) {
-  const digest = await crypto.subtle.digest("SHA-256", enc.encode("realtimeclipboard:" + key));
-  return hex(new Uint8Array(digest).slice(0, CRYPTO.ROOM_HASH_BYTES));
-}
+let cached = { id: null, open: null };
 
 /**
- * Derive the AES key. Several hundred ms on a low-end Android, so call once
- * per session and show an "unlocking" state — never per message.
+ * Both outputs of an open session, from one PBKDF2.
+ *
+ * Several hundred ms on a low-end Android, so call once per session and show an
+ * "unlocking" state — never per message. It is not a new cost: the room hash was
+ * always awaited alongside this derivation before the connection opened, so the
+ * slower of the two already set the pace.
+ *
+ * Returning them together is deliberate. Two exported functions is what let the
+ * room hash be computed by a route that never ran the PBKDF2, which is exactly
+ * how it ended up being a bare SHA-256 of the key.
  */
-export async function deriveKey(key) {
-  if (cached.id === `open:${key}` && cached.aesKey) return cached.aesKey;
+export async function deriveOpen(key) {
+  if (cached.id === `open:${key}` && cached.open) return cached.open;
 
   const material = await crypto.subtle.importKey(
-    "raw", enc.encode(key), "PBKDF2", false, ["deriveKey"]
+    "raw", enc.encode(key), "PBKDF2", false, ["deriveBits"]
   );
-  const aesKey = await crypto.subtle.deriveKey(
+  const prk = await crypto.subtle.deriveBits(
     { name: "PBKDF2", salt: enc.encode(CRYPTO.SALT),
       iterations: CRYPTO.ITERATIONS, hash: "SHA-256" },
     material,
-    { name: "AES-GCM", length: 256 },
-    false,
-    ["encrypt", "decrypt"]
+    256
   );
-  cached = { id: `open:${key}`, aesKey };
-  return aesKey;
+
+  const open = await expand(prk, CRYPTO.OPEN_INFO);
+  cached = { id: `open:${key}`, open };
+  return open;
 }
 
-/* ------------------------------------------------------------------
-   Locked sessions
-------------------------------------------------------------------- */
+/* ---- locked sessions ---- */
 
 /**
- * Normalise a PIN — the exact OPPOSITE of what normalise() does to a key, and
- * the reasoning is worth keeping because getting it backwards is silent.
- *
- * A key is uppercased and stripped to [A-Z0-9] so that two people typing "the
- * same key" land in the same room. A PIN is user-chosen prose, so:
+ * The exact opposite of what normalise() does to a key, and getting it backwards
+ * is silent.
  *
- *   - NFC, mandatory. "é" can be typed as one code point or as "e" plus a
- *     combining accent. They are different byte strings, they derive different
- *     rooms, and NOTHING would report it — the second device would simply be
- *     alone in a room of its own, looking like a wrong PIN.
- *   - Trim the ends. A trailing space from a paste is invisible on screen and
- *     the user has no way to see why their correct PIN is rejected.
- *   - Keep case and everything in the middle. Uppercasing would throw away
- *     about a bit per letter to buy nothing: unlike a key, a PIN is never read
- *     aloud off a screen and retyped from memory.
+ *   - NFC is mandatory. "é" as one code point and as "e" + combining accent are
+ *     different byte strings deriving different rooms, and nothing reports it —
+ *     the second device is simply alone, looking like a wrong PIN.
+ *   - Trim the ends: a pasted trailing space is invisible on screen.
+ *   - Keep case and the middle. A PIN is never read aloud and retyped, so
+ *     uppercasing would throw away a bit per letter to buy nothing.
  */
 export function normalisePin(raw) {
   return String(raw ?? "").normalize("NFC").trim();
 }
 
 /**
- * The whole locked-session derivation: one PBKDF2, three outputs.
+ * One PBKDF2, three outputs. PBKDF2 reruns its full iteration count per 32-byte
+ * block, so asking it for 64 bytes would cost double; stretch once and expand
+ * with HKDF, which is a couple of HMACs.
  *
- * PBKDF2 reruns its full iteration count for every 32-byte block of output, so
- * asking it for the 64 bytes we need would cost twice what it should — and OI-8
- * already flags this as hundreds of milliseconds on a low-end Android. Instead
- * we stretch once and expand with HKDF, which is a couple of HMACs.
+ * The share key as salt stops ONE table covering every session — the open path,
+ * with its single global salt, has exactly that weakness. It buys nothing
+ * against the attacker this feature is for: someone holding the link can compute
+ * the salt. Only PIN length and iteration count defend there, which is why the
+ * dialog reports entropy in bits rather than calling a short PIN "secure".
  *
- * The share key is the salt, and it is worth being precise about what that does
- * and does not buy. It stops ONE table from covering every session — the
- * open-session path, with its single global CRYPTO.SALT, has exactly that
- * weakness today. It buys nothing at all against the attacker this feature is
- * actually for: someone holding the link holds the key, so they can compute the
- * salt themselves. Against them the only defence is the length of the PIN and
- * the iteration count, which is why the dialog reports entropy in bits instead
- * of calling a short PIN "secure".
- *
- * Returns `prk` as hex alongside the derived values so a page refresh can skip
- * the 600k iterations. See storage.saveLock for why the PIN itself is never
- * what gets stored.
+ * Returns `prk` as hex so a refresh can skip the 600k iterations.
  */
 export async function deriveLocked(key, pin) {
   const prk = await stretch(key, normalisePin(pin));
-  return { ...(await expand(prk)), prk: hex(new Uint8Array(prk)) };
+  return { ...(await expand(prk, CRYPTO.LOCK_INFO)), prk: hex(new Uint8Array(prk)) };
 }
 
 /** Same outputs, from a remembered prk. No PBKDF2, so this is instant. */
 export async function deriveLockedFromPrk(prkHex) {
-  return { ...(await expand(unhex(prkHex))), prk: prkHex };
+  return { ...(await expand(unhex(prkHex), CRYPTO.LOCK_INFO)), prk: prkHex };
 }
 
 async function stretch(key, pin) {
@@ -131,37 +107,37 @@ async function stretch(key, pin) {
   );
 }
 
-async function expand(prk) {
+/**
+ * Shared by both paths, which is the point: the open and locked sessions differ
+ * only in what they stretch and under which domain-separation strings, never in
+ * how the outputs are pulled off the PRK. `AUTH` is absent from OPEN_INFO — an
+ * unlocked room has no PIN to prove knowledge of — and its absence is what makes
+ * the token optional rather than a flag.
+ */
+async function expand(prk, labels) {
   const ikm = await crypto.subtle.importKey("raw", prk, "HKDF", false, ["deriveBits", "deriveKey"]);
   const info = i => ({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: enc.encode(i) });
+  const bits = i => crypto.subtle.deriveBits(info(i), ikm, CRYPTO.ROOM_HASH_BYTES * 8);
 
   const [aesKey, room, auth] = await Promise.all([
     crypto.subtle.deriveKey(
-      info(CRYPTO.LOCK_INFO.AES), ikm,
+      info(labels.AES), ikm,
       { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]
     ),
-    crypto.subtle.deriveBits(info(CRYPTO.LOCK_INFO.ROOM), ikm, CRYPTO.ROOM_HASH_BYTES * 8),
-    crypto.subtle.deriveBits(info(CRYPTO.LOCK_INFO.AUTH), ikm, CRYPTO.ROOM_HASH_BYTES * 8),
+    bits(labels.ROOM),
+    labels.AUTH ? bits(labels.AUTH) : null,
   ]);
 
   return {
     aesKey,
-    roomHash:  hex(new Uint8Array(room)),
-    authToken: hex(new Uint8Array(auth)),
+    roomHash: hex(new Uint8Array(room)),
+    ...(auth ? { authToken: hex(new Uint8Array(auth)) } : {}),
   };
 }
 
-/**
- * No cache entry for locked sessions, deliberately.
- *
- * The open-session cache exists because deriveKey() is called with the same key
- * repeatedly. The locked path is not: it runs once per session, a reconnect
- * reuses the room hash without re-deriving, and the only things that DO call it
- * again — a corrected PIN, a rotated key — are the cases where the previous
- * answer is exactly the one you must not reuse. The refresh path is covered by
- * the stored prk instead, which is cheaper than a cache and survives the tab
- * being reloaded.
- */
+// No locked-session cache on purpose: the path runs once per session, and the
+// things that DO call it again — a corrected PIN, a rotated key — are exactly
+// where the previous answer must not be reused. The stored prk covers refresh.
 
 /** -> {payload, iv} both base64. A fresh IV per message is mandatory for GCM. */
 export async function encrypt(aesKey, plaintext) {
@@ -179,14 +155,10 @@ export async function decrypt(aesKey, payloadB64, ivB64) {
   return dec.decode(buf);
 }
 
-/**
- * Forget the derived key.
- *
- * Called on leaving a session and on rotating the key. For years this had no
- * callers at all, which meant the AES key of a room you had deliberately walked
- * out of stayed live in this module until you happened to open another one.
- */
-export function clearCache() { cached = { id: null, aesKey: null }; }
+// Called on leaving a session and on rotating the key. This had no callers for
+// years, so the AES key of a room you walked out of stayed live until you opened
+// another one.
+export function clearCache() { cached = { id: null, open: null }; }
 
 /* ---- hex helpers ---- */
 function hex(bytes) {

package/src/core/device.js

@@ -1,33 +1,34 @@
 /**
- * A human-readable name for this device, shown in the peer list.
+ * A human-readable name for this device, shown in the peer list. Derived from
+ * the user agent, which is unreliable by design — a label to help someone
+ * recognise their own laptop in a list of three, not an identity.
  *
- * Derived from the user agent, which is unreliable by design — this is a label
- * to help someone recognise their own laptop in a list of three, not an
- * identity.
- *
- * IT IS SENT IN THE CLEAR. This comment used to claim the opposite — "inside
- * the encrypted envelope, never to the relay in the clear" — and the wire has
- * never agreed with it: `protocol.hello()` puts `name` in a plaintext field,
- * and the relay stores it and rebroadcasts it in every roster
- * (backend/main.py `_adopt_identity`, `_roster`).
- *
- * So keep it a label. "Chrome · Windows" is fine; a name is not the place for
- * anything you would mind the relay operator reading. This is one of the things
- * a locked session does NOT hide — see PRD §7.5 and OI-20.
+ * IT IS SENT IN THE CLEAR: `protocol.hello()` puts `name` in a plaintext field,
+ * and the relay stores and rebroadcasts it in every roster. So keep it a label —
+ * "Chrome · Windows" is fine, and a name is not the place for anything you would
+ * mind the relay operator reading. One of the things a locked session does NOT
+ * hide, see PRD §7.5 and OI-20.
  */
 
 import { read, write } from "./storage.js";
 
+/**
+ * Windows | Android | iOS | macOS | Linux | Unknown. Exported because the
+ * desktop guide describes the tray, which behaves differently enough per
+ * platform that one paragraph covering all three would be wrong on two.
+ */
+export function os() {
+  const ua = globalThis.navigator?.userAgent ?? "";
+  return /Windows/i.test(ua)            ? "Windows" :
+         /Android/i.test(ua)            ? "Android" :
+         /iPhone|iPad|iPod/i.test(ua)   ? "iOS"     :
+         /Mac OS X|Macintosh/i.test(ua) ? "macOS"   :
+         /Linux/i.test(ua)              ? "Linux"   : "Unknown";
+}
+
 function detect() {
   const ua = navigator.userAgent;
 
-  const os =
-    /Windows/i.test(ua)                    ? "Windows" :
-    /Android/i.test(ua)                    ? "Android" :
-    /iPhone|iPad|iPod/i.test(ua)           ? "iOS"     :
-    /Mac OS X|Macintosh/i.test(ua)         ? "macOS"   :
-    /Linux/i.test(ua)                      ? "Linux"   : "Unknown";
-
   // Order matters: Edge and Opera both contain "Chrome", Chrome contains "Safari".
   const browser =
     /Edg\//i.test(ua)                      ? "Edge"    :
@@ -36,7 +37,7 @@ function detect() {
     /Chrome\//i.test(ua)                   ? "Chrome"  :
     /Safari\//i.test(ua)                   ? "Safari"  : "Browser";
 
-  return `${browser} · ${os}`;
+  return `${browser} · ${os()}`;
 }
 
 /** Persisted so a device keeps its name across reloads, and stays renameable. */

package/src/core/history.js

@@ -1,35 +1,22 @@
 /**
  * In-session clip history — PRD FR-2.9 (last 20 clips, one-click copy).
  *
- * ── PRIVACY INVARIANT ──────────────────────────────────────────────────────
- * This module persists to **sessionStorage only. Never localStorage.**
+ * PRIVACY INVARIANT: persists to **sessionStorage only, never localStorage**.
+ * Clipboard content is passwords, tokens, 2FA codes and private URLs; it must
+ * not survive the browser session, be readable by the next person to open the
+ * laptop, or leak between rooms. The sessionStorage twin lives here rather than
+ * in core/storage.js precisely so a future edit cannot quietly move clips onto
+ * disk — that module is the localStorage one, for preferences.
  *
- * Clipboard content is not ordinary application data: in practice it is
- * passwords, API tokens, 2FA codes and private URLs. Those must not survive the
- * browser session, must not be readable by the next person to open the laptop,
- * and must not leak between rooms. sessionStorage is scoped to the tab and dies
- * with it, which is exactly the lifetime we want.
- *
- * core/storage.js is the localStorage wrapper and is explicitly documented as
- * "clipboard *content* never comes near this — only preferences". So the
- * sessionStorage twin lives here rather than being bolted onto that module: the
- * two stores have different lifetimes for a reason, and keeping them in separate
- * files is what stops a future edit from quietly moving clips onto disk.
- *
- * The same reasoning drives the key-change behaviour: a different share key is a
- * different room and a different set of people. History never crosses that line.
- *
- * Node-testable on purpose — this file imports only core/bus.js, and every
- * sessionStorage call is wrapped, so it degrades to memory-only where the API is
- * missing (node, private mode, storage disabled).
+ * Node-testable on purpose: imports only core/bus.js, and every sessionStorage
+ * call is wrapped, so it degrades to memory-only where the API is missing.
  */
 
 import { on, emit, EV } from "./bus.js";
 
 /**
- * PRD FR-2.9 caps history at 20. This belongs in core/config.js with the other
- * limits; it lives here only because config.js is owned elsewhere. Move it when
- * the two land together.
+ * PRD FR-2.9 caps history at 20. Belongs in core/config.js with the other
+ * limits; it is here because importing config.js would cost node testability.
  */
 export const MAX_CLIPS = 20;
 
@@ -48,14 +35,8 @@ let roomKey = null;      // share key the current list belongs to; null until fi
 let started = false;
 let seq = 0;
 
-/* ------------------------------------------------------------------ storage */
-/*
- * Mirrors the shape of core/storage.js (read / write / remove, wrapped so a
- * disabled-storage browser degrades instead of throwing) but targets
- * sessionStorage. try/catch also swallows the ReferenceError under node, which
- * is what makes this module testable outside a browser.
- */
-
+// Mirrors core/storage.js against sessionStorage. try/catch also swallows the
+// ReferenceError under node, which is what makes this module testable.
 function readStore() {
   try {
     const raw = sessionStorage.getItem(STORE_KEY);
@@ -73,22 +54,19 @@ function removeStore() {
 }
 
 /**
- * A clip can be 50k characters and we keep 20 of them, so a full list can push
- * a megabyte. If the write is refused we keep going in memory rather than
- * dropping the clip — losing persistence across a reload is a smaller failure
- * than losing the user's clipboard.
+ * A refused write keeps going in memory rather than dropping the clip: 20 clips
+ * of 50k characters can push a megabyte, and losing persistence across a reload
+ * is a smaller failure than losing the user's clipboard.
  */
 function persist() {
   if (!clips.length && roomKey === null) return removeStore();
   writeStore({ key: roomKey, clips });
 }
 
-/* ------------------------------------------------------------------- model */
-
 const nextId = () => `h${Date.now().toString(36)}${(++seq).toString(36)}`;
 
-/** Local normalisation — deliberately not importing core/keys.js, which pulls in
- *  config.js and its top-level `location` read (breaks node testability). */
+// Local, deliberately not core/keys.js — that pulls in config.js and its
+// top-level `location` read, which breaks node testability.
 const normKey = k => String(k ?? "").trim().toUpperCase();
 
 function announce(reason) {
@@ -107,13 +85,10 @@ export function get(id) {
 export const size = () => clips.length;
 
 /**
- * Record a clip. Returns the new entry, or null if it was ignored.
- *
- * Ignored when: the text is empty/whitespace, or it is identical to the most
- * recent entry. That last one matters more than it looks — capture tiers can
- * fire twice for one copy (paste event + poll), and a peer echoing our own clip
- * back arrives with the same text under a different direction. Consecutive
- * duplicates are noise in every one of those cases.
+ * Record a clip. Returns the new entry, or null if it was ignored — empty text,
+ * or identical to the most recent entry. Consecutive dedupe matters more than it
+ * looks: capture tiers can fire twice for one copy (paste event + poll), and a
+ * peer echoing our own clip back arrives with the same text.
  */
 export function add({ text, direction }) {
   const value = String(text ?? "");
@@ -141,13 +116,8 @@ export function clear(reason = "clear") {
   return had;
 }
 
-/* -------------------------------------------------------------------- boot */
-
-/**
- * Rehydrate whatever this tab had before a reload. The stored key is not known
- * to be the current room yet — the first KEY_CHANGED decides whether to keep or
- * discard this (see onKeyChanged).
- */
+// The stored key is not known to be the current room yet — the first
+// KEY_CHANGED decides whether to keep or discard this.
 function hydrate() {
   const saved = readStore();
   if (!saved || !Array.isArray(saved.clips)) return;
@@ -166,13 +136,10 @@ function hydrate() {
 }
 
 /**
- * A new share key is a new room, new peers, and a new privacy context. Clips
- * from the old room must not be sitting in the panel when someone else joins.
- *
- * The first KEY_CHANGED after boot is not a rotation, though — main.js emits one
- * during startup for the key we already had. Comparing against the key stored
- * alongside the clips is what tells the two apart, and is why the key is
- * persisted with the list rather than held only in memory.
+ * A new share key is a new room, new peers, and a new privacy context. The first
+ * KEY_CHANGED after boot is not a rotation, though — main.js emits one for the
+ * key we already had, and comparing against the key stored alongside the clips
+ * is what tells the two apart.
  */
 function onKeyChanged({ key }) {
   const next = normKey(key);
@@ -189,11 +156,7 @@ function onKeyChanged({ key }) {
   persist();
 }
 
-/**
- * Subscribe to the bus. Idempotent — ui/historyPanel.js calls this so the
- * feature is one init() line in main.js, but calling it from main.js directly is
- * equally fine.
- */
+/** Subscribe to the bus. Idempotent. */
 export function init() {
   if (started) return;
   started = true;