realtimeclipboard 0.3.0

package/src/core/paths.js

@@ -0,0 +1,68 @@
+/**
+ * Where the app is served from, resolved once for the whole codebase.
+ *
+ * Six modules used to compute this themselves with `new URL("../…",
+ * import.meta.url)` — each one hard-coding how deep its own file sits in the
+ * tree. That works exactly as long as every module keeps its own file, and
+ * stops the moment the deploy bundles `src/ui/*.js` into `src/main.js`: every
+ * one of those paths shifts by a directory level, all at once, and nothing
+ * throws. `install.js` in particular resolved the app root to the GitHub Pages
+ * ROOT rather than to `/RealtimeClipboard/`, which silently breaks the service-worker
+ * scope and the PWA install criteria — PRD OI-9, the failure its own comment
+ * warned about.
+ *
+ * A module's depth in the tree is not information any module should depend on.
+ * `document.baseURI` is: it is what the browser already resolved every relative
+ * href on the page against, so it is right whether the code arrives as forty
+ * modules or as one bundle.
+ *
+ * !! The app root is the ORIGIN root — `new URL("/", …)`, not `new URL(".", …)`.
+ * That is a deliberate narrowing: this used to resolve the directory the current
+ * page sits in, so the app could be served from a subpath like
+ * `user.github.io/RealtimeClipboard/`. Subpath hosting is no longer supported, because
+ * src/pages/ publishes its pages one level up from where they sit on disk and
+ * therefore links to them root-absolutely — and a root-absolute link is wrong
+ * under a subpath by construction. Supporting both would mean two link styles
+ * in one site, which is how the depth bugs above happened in the first place.
+ *
+ * What that buys: the app's HTML no longer has to live at the app root for this
+ * to be correct, so a page's depth stops being load-bearing anywhere. What it
+ * costs: hosting under a path prefix. docs/SELF-HOSTING.md says so. !!
+ */
+
+/**
+ * Guarded the same way `config.js` guards `location`: `core/` is imported by
+ * the node-based tests, where there is no document, and a bare reference would
+ * throw at import time and take the whole module graph down with it.
+ */
+const BASE = typeof document !== "undefined" && document.baseURI
+  ? document.baseURI
+  : "http://localhost/";
+
+/** The origin root, with trailing slash — `https://realtimeclipboard.com/`. */
+export const APP_ROOT = new URL("/", BASE);
+
+/** A file sitting beside `app.html`: `sw.js`, `manifest.webmanifest`, `changelog.json`. */
+export const atRoot = name => new URL(name, APP_ROOT).href;
+
+/**
+ * A stylesheet under `src/styles/lazy/`, fetched on first open.
+ *
+ * Lazy sheets stay OUT of the bundle on purpose — a QR modal's stylesheet has
+ * no business in the critical path of an app most people never open it in.
+ *
+ * !! The directory is the whole contract. `styles/` is bundled into main.css
+ * and `styles/lazy/` is copied verbatim, so which loader a sheet belongs to is
+ * a fact about where it sits rather than about who happens to reference it.
+ * tools/build/build.mjs used to recover that by grepping every module for calls to
+ * this function; it copies the directory now. Pointing this at `styles/` would
+ * make an eager sheet loadable twice, once bundled and once over the wire. !!
+ *
+ * A sheet cannot be moved into `lazy/` on payload grounds alone. An injected
+ * <link> lands AFTER main.css, and main.css ends with mobile.css, which
+ * overrides earlier sheets at equal specificity and relies on source order to
+ * win. So anything mobile.css restyles has to stay eager whatever it costs —
+ * qr.css and history.css share ten classes with it and are the standing
+ * example.
+ */
+export const lazyStyleHref = name => new URL(`src/styles/lazy/${name}`, APP_ROOT).href;

package/src/core/state.js

@@ -0,0 +1,193 @@
+/**
+ * Single source of truth for session state.
+ *
+ * Deliberately not reactive. Modules mutate through the setters here and the
+ * bus announces the change; nothing observes this object directly. That keeps
+ * the data flow one-directional and greppable.
+ */
+
+import { emit, EV } from "./bus.js";
+import { DEFAULT_SYNC_MODE } from "./config.js";
+
+const state = {
+  key: null,
+  roomHash: null,
+  aesKey: null,
+  /**
+   * Locked session — a PIN outside the link (core/crypto.js).
+   *
+   * `verified` is a separate fact from `locked` and the difference is the whole
+   * honesty of the feature. A wrong PIN does not fail loudly: it derives a
+   * different, empty room, which looks exactly like being the first one to
+   * arrive. `verified` means something in this room actually decrypted, so we
+   * KNOW the PIN is right rather than assuming it.
+   */
+  locked: false,
+  verified: false,
+  /**
+   * Were we the first device into this room?
+   *
+   * `null` until the relay's `welcome` answers it — "not yet known" is a third
+   * state and must not be spelled `false`, or the lock button would be refused
+   * for the fraction of a second before the room reports itself and refused
+   * again for the whole of an offline session.
+   *
+   * Only locking reads it (see canLock). The relay's `existing` count is the
+   * source: it is the peers already present at the moment we joined.
+   */
+  founder: null,
+  authToken: null,           // proves PIN knowledge to the relay; not a secret
+  originId: crypto.randomUUID().slice(0, 8),   // this tab, for loop suppression
+  peerId: null,              // assigned by the relay in `welcome.you`
+  connection: "idle",        // idle | connecting | connected | reconnecting | offline
+  instance: null,            // relay instance id — a change means split-brain (OI-3)
+  peers: 1,
+  tier: "T1",                // clipboard capture tier, see clipboard/capture.js
+  lastSent: "",              // dedupe guard (FR-2.7)
+  suppressUntil: 0,          // loop-suppression deadline (FR-2.6)
+  settings: {
+    syncMode: DEFAULT_SYNC_MODE,   // live | manual — see config.js
+    autowrite: true,
+    autoread: true,
+    autoaccept: false,
+    thumbs: true,
+    images: true,
+    cursors: true,
+    poll: "1s",
+  },
+};
+
+export const get = () => state;
+
+export function setKey({ key, roomHash, aesKey, locked = false, authToken = null }) {
+  state.key = key;
+  state.roomHash = roomHash ?? state.roomHash;
+  state.aesKey = aesKey ?? state.aesKey;
+  state.locked = locked;
+  state.authToken = authToken;
+  // A new key is a new room: whatever we had proved about the old one does not
+  // carry over, and claiming otherwise would leave a stale padlock on screen.
+  state.verified = false;
+  // Likewise "we were first" — asked and answered per room. Left standing, the
+  // founder of one session would carry the right to lock into the next one it
+  // walked into, which is precisely the device that must not have it.
+  state.founder = null;
+  emit(EV.KEY_CHANGED, { key, locked });
+  emit(EV.LOCK_STATE, { locked, verified: false });
+  emit(EV.FOUNDER, { founder: null });
+}
+
+/**
+ * Record whether this device was the first one into the room.
+ *
+ * Fed from `welcome.existing` in main.js. Re-answered on every welcome, so a
+ * relay restart — which empties every room (OI-13) — hands the title to
+ * whoever reconnects into the empty room first, rather than to whoever held it
+ * before the room stopped existing.
+ */
+export function setFounder(first) {
+  const next = first === null ? null : !!first;
+  if (state.founder === next) return;
+  state.founder = next;
+  emit(EV.FOUNDER, { founder: next });
+}
+
+/**
+ * May THIS device lock the session?
+ *
+ * Alone, anyone may: there is nobody to be thrown out. With company, only the
+ * device that opened the room, because locking is not a setting — it moves the
+ * session to a different room and removes everybody else from it (see
+ * LOCK.EVICT). A control that lets any arrival do that to the rest is a control
+ * for taking a session over, and the person who started it is the one who
+ * chose to share the key in the first place.
+ *
+ * A rule the UI keeps, not one the relay enforces: every device in the room
+ * already holds the key, so a modified client could send the goodbye itself.
+ * That is not a new power — it could equally read every clip — and the honest
+ * description of this is "the app will not help you do it", not "you cannot".
+ */
+export function canLock() {
+  if (state.locked) return false;
+  if (state.peers <= 1) return true;
+  return state.founder === true;
+}
+
+/**
+ * Record that this device can actually read this room.
+ *
+ * Set from the first thing that decrypts — the beacon replayed in `welcome`, or
+ * any real frame. Only ever moves false -> true within a session; setKey resets
+ * it, because a different room is a different question.
+ */
+export function setVerified() {
+  if (!state.locked || state.verified) return;
+  state.verified = true;
+  emit(EV.LOCK_STATE, { locked: true, verified: true });
+}
+
+export function setConnection(connection, detail = "") {
+  state.connection = connection;
+  emit(EV.CONN_STATE, { state: connection, detail });
+}
+
+/**
+ * Peer roster.
+ *
+ * Diffed rather than just counted, so arrivals can be announced. The key is a
+ * bearer credential — a device appearing is the one observable moment that
+ * tells you someone else has it, and a count quietly going 2 → 3 is not
+ * something anyone notices.
+ *
+ * The first roster after connecting is not announced: those devices were
+ * already there, and greeting them as arrivals would cry wolf on every reload.
+ */
+let roster = null;
+
+export function setPeers(count, list = []) {
+  state.peers = count;
+
+  if (roster === null) {
+    roster = new Map(list.map(p => [p.peerId, p.name]));
+  } else {
+    const now = new Map(list.map(p => [p.peerId, p.name]));
+    for (const [id, name] of now) {
+      if (!roster.has(id) && id !== state.peerId) emit(EV.PEER_JOINED, { name, id });
+    }
+    for (const [id, name] of roster) {
+      if (!now.has(id)) emit(EV.PEER_LEFT, { name, id });
+    }
+    roster = now;
+  }
+
+  emit(EV.PEERS_CHANGED, { count, list });
+}
+
+/** Forget the roster so a reconnect does not report everyone as newly arrived. */
+export function resetRoster() { roster = null; }
+
+/**
+ * The relay keeps rooms in process memory, so a changed instance id means we
+ * may have landed on a different replica where our peers do not exist. Loud,
+ * not silent — a quiet failure here looks exactly like "the network is slow".
+ */
+export function setInstance(instance) {
+  const previous = state.instance;
+  state.instance = instance;
+  if (previous && previous !== instance) {
+    emit(EV.INSTANCE_CHANGED, { from: previous, to: instance });
+  }
+}
+
+export function setTier(tier, note = "") {
+  state.tier = tier;
+  emit(EV.TIER_CHANGED, { tier, note });
+}
+
+export function setSetting(name, value) {
+  state.settings[name] = value;
+}
+
+/** Mute local capture briefly after applying a remote clip (FR-2.6). */
+export function suppress(ms) { state.suppressUntil = Date.now() + ms; }
+export function isSuppressed() { return Date.now() < state.suppressUntil; }

package/src/core/storage.js

@@ -0,0 +1,182 @@
+/**
+ * localStorage, wrapped so a disabled-storage browser degrades instead of
+ * throwing. Clipboard *content* never comes near this — only preferences.
+ */
+
+import { NET, STORAGE_PREFIX, normaliseRelay } from "./config.js";
+
+const PREFIX = STORAGE_PREFIX;
+
+export function read(name, fallback = null) {
+  try {
+    const raw = localStorage.getItem(PREFIX + name);
+    return raw === null ? fallback : JSON.parse(raw);
+  } catch { return fallback; }
+}
+
+export function write(name, value) {
+  try { localStorage.setItem(PREFIX + name, JSON.stringify(value)); return true; }
+  catch { return false; }        // private mode, quota, or storage disabled
+}
+
+export function remove(name) {
+  try { localStorage.removeItem(PREFIX + name); } catch { /* nothing to do */ }
+}
+
+export const loadSettings = () => read("settings", null);
+export const saveSettings = s => write("settings", s);
+
+/**
+ * The relay this device talks to, when it is not the one the build ships with.
+ *
+ * A preference, not session content, so it belongs here — nothing about a clip
+ * or a key is being written. core/config.js READS this key directly at module
+ * evaluation, because the URL has to be resolved before anything imports it;
+ * this pair is for changing it afterwards.
+ *
+ * Normalised on the way in as well as on the way out. A value that got into
+ * storage malformed would otherwise be re-read as malformed on every launch,
+ * and the symptom — every connection refused — looks nothing like its cause.
+ */
+export const loadRelayUrl = () => normaliseRelay(read("relayUrl", null));
+
+export function saveRelayUrl(url) {
+  const clean = normaliseRelay(url);
+  if (!clean) { remove("relayUrl"); return null; }
+  write("relayUrl", clean);
+  return clean;
+}
+
+/**
+ * The last room, so a relaunch can offer it back (FR-1.7, OI-10).
+ *
+ * Stores `{key, locked}` since locked sessions exist; it used to be a bare
+ * string and still reads one, because an upgrade must not strand somebody in
+ * "no room at all" on their first load of the new build.
+ *
+ * The lock FLAG is remembered here, in localStorage. The PIN is not, and never
+ * will be — see saveLock below.
+ */
+export function loadLastKey() {
+  const saved = read("lastKey", null);
+  if (!saved) return null;
+  return typeof saved === "string"
+    ? { key: saved, locked: false }
+    : { key: saved.key ?? null, locked: !!saved.locked };
+}
+
+export const saveLastKey = (key, locked = false) => write("lastKey", { key, locked });
+
+/**
+ * Which transport last worked (see transport/relay.js).
+ *
+ * Remembered because probing costs the user real seconds of "Connecting…" on
+ * every load behind a proxy that blocks WebSockets, and the answer there is the
+ * same every time. Expired rather than permanent because it is a fact about the
+ * *network*, not the device: a laptop that leaves the office should go back to
+ * the faster transport on its own, without anyone knowing there was a setting.
+ */
+export function loadTransport() {
+  const saved = read("transport", null);
+  if (!saved?.mode || !saved.at) return null;
+  return Date.now() - saved.at < NET.TRANSPORT_MEMORY_MS ? saved.mode : null;
+}
+
+export function saveTransport(mode) {
+  if (!mode) return remove("transport");
+  write("transport", { mode, at: Date.now() });
+}
+
+/**
+ * A transport the user picked by hand, which outranks anything measured.
+ *
+ * Kept apart from the remembered-working one above because they answer
+ * different questions — "what worked last time" is an observation and expires;
+ * "use HTTP" is an instruction and does not. Merging them would let a
+ * successful automatic connection quietly overwrite a deliberate choice.
+ */
+export const loadTransportChoice = () => read("transportChoice", null);
+
+export function saveTransportChoice(mode) {
+  if (!mode) return remove("transportChoice");
+  write("transportChoice", mode);
+}
+
+/* ------------------------------------------------------------------
+   Session-scoped file allowances
+
+   sessionStorage, not localStorage, and this is the whole point of them: "allow
+   everything from this device" is a decision about the session you are in, and
+   it has to die with the tab. A permanent version of this setting is a standing
+   grant to whoever holds the share key, made once and then forgotten about.
+
+   Scoped to a room as well as a tab. The key is a bearer credential and rooms
+   are named after it, so an allowance granted in one session must not survive
+   into another — rotating the key is how someone throws a device out, and it
+   would be worth nothing if the allowance came along.
+------------------------------------------------------------------- */
+
+export function loadAllowances(room) {
+  if (!room) return [];
+  try {
+    const saved = JSON.parse(sessionStorage.getItem(PREFIX + "allow") || "null");
+    return saved && saved.room === room && Array.isArray(saved.peers) ? saved.peers : [];
+  } catch { return []; }
+}
+
+export function saveAllowances(room, peers) {
+  try {
+    if (!room || !peers?.length) sessionStorage.removeItem(PREFIX + "allow");
+    else sessionStorage.setItem(PREFIX + "allow", JSON.stringify({ room, peers }));
+    return true;
+  } catch { return false; }
+}
+
+/* ------------------------------------------------------------------
+   The locked-session unlock, scoped to this tab
+
+   Two decisions here, both deliberate.
+
+   WHAT is stored is the PBKDF2 output, never the PIN. It unlocks exactly the
+   same room, so this is not a security improvement in itself — the point is
+   that a PIN is a human-chosen secret and humans reuse them. The string the
+   user typed should not be sitting in a browser store waiting to be read by
+   the next thing that gets to run in this origin. The derived value is useless
+   anywhere else, and reading it back skips 600k PBKDF2 iterations, so a refresh
+   is instant instead of a second of "Unlocking…".
+
+   WHERE is sessionStorage, for the same reason the file allowances above use
+   it: a refresh is the same session and must not re-prompt, but the tab closing
+   is the end of it. localStorage would put the unlock on disk next to the
+   plaintext key — at which point the link and the PIN are stored together and
+   the second secret has bought nothing.
+
+   Scoped to the share key, so rotating the key invalidates it automatically.
+------------------------------------------------------------------- */
+
+/**
+ * The remembered unlock for a share key, or null.
+ *
+ * Matched on the KEY rather than on the room, and that is not interchangeable.
+ * The room hash of a locked session is derived from the stretched PIN alone, so
+ * a record left behind by a previous key would still look perfectly
+ * self-consistent and would silently reconnect this tab to a room the current
+ * link does not name. The key is the thing that has to agree.
+ */
+export function loadLock(key) {
+  if (!key) return null;
+  try {
+    const saved = JSON.parse(sessionStorage.getItem(PREFIX + "lock") || "null");
+    return saved && saved.key === key && saved.prk ? saved.prk : null;
+  } catch { return null; }
+}
+
+export function saveLock(key, prk) {
+  try {
+    if (!key || !prk) sessionStorage.removeItem(PREFIX + "lock");
+    else sessionStorage.setItem(PREFIX + "lock", JSON.stringify({ key, prk }));
+    return true;
+  } catch { return false; }
+}
+
+export const clearLock = () => saveLock(null, null);

package/src/transport/CLAUDE.md

@@ -0,0 +1,30 @@
+# src/transport/ — rank 10
+
+May import `core/`. May not import `clipboard/`, `files/`, `landing/` or anything in `ui/`.
+
+**Nothing above this directory may import `relay.js`, `ws.js` or `sse.js`** — the static check
+fails the commit. `protocol.js` is the one exception, because frame *shapes* are transport-agnostic
+and `files/transfer.js` reads its type constants rather than hand-copying eleven string literals.
+
+That boundary is not decoration. It is what let the entire SSE fallback land without a single UI
+file changing, and it is the reason the transport could stay unsettled while everything above it
+was built.
+
+## The shape
+
+`relay.js` is the facade. `ws.js` and `sse.js` are channels behind one contract —
+`create → {send, close, isOpen}` — and know nothing but how to move frames.
+
+Everything easy to get subtly different between two transports lives in `relay.js` **once**: the
+hello, the 30 s heartbeat, jittered reconnect backoff, the last-clip replay, and which channel is
+live. Adding a third channel should mean adding one file and one line.
+
+## Rules
+
+- A new frame type is declared in `protocol.js` and handled in `relay.js`. Nowhere else.
+- The relay learns nothing. It sees a room hash and ciphertext, and is never told anything about
+  the visitor. Widening that needs an argument in `docs/PRD.md` first.
+- A blocked WebSocket usually **hangs rather than fails**, so there is no error to react to — only
+  `NET.PROBE_MS` notices. Do not replace the probe with an error handler.
+- Nothing here may decide which channel to use on a UI module's behalf. The status-bar picker emits
+  `EV.TRANSPORT_SELECT`; `main.js` calls `setTransport()`.

package/src/transport/README.md

@@ -0,0 +1,16 @@
+# src/transport/
+
+Getting frames to the relay and back, over whichever channel the network allows.
+
+| File | What it does |
+|---|---|
+| `relay.js` | The facade: protocol, hello, heartbeat, reconnect backoff, and which channel is live |
+| `ws.js` | WebSocket channel — the default |
+| `sse.js` | SSE downstream + POST upstream — the fallback for networks that swallow WebSockets |
+| `protocol.js` | Wire frame shapes, transport-agnostic. See `docs/PRD.md` §6 |
+
+The client tries WebSocket, gives it `NET.PROBE_MS` to become usable, and after
+`NET.SWITCH_AFTER` attempts that never do, moves to SSE and says so in the status bar. Nothing
+above this directory can tell which channel is carrying the session.
+
+Rules that govern edits here: [CLAUDE.md](CLAUDE.md).

package/src/transport/protocol.js

@@ -0,0 +1,68 @@
+/**
+ * Wire protocol — PRD §6. Frame shapes live here and nowhere else.
+ *
+ * Deliberately transport-agnostic: if the SSE+POST fallback is ever needed
+ * (PRD §4.3 R3), these same envelopes travel unchanged.
+ */
+
+export const T = {
+  HELLO:   "hello",
+  CLIP:    "clip",
+  PING:    "ping",
+  PONG:    "pong",
+  WELCOME: "welcome",
+  PEERS:   "peers",
+  ERROR:   "error",
+  // M7 — WebRTC signalling, forwarded blindly by the relay
+  RTC_OFFER:  "rtc-offer",
+  RTC_ANSWER: "rtc-answer",
+  RTC_ICE:    "rtc-ice",
+  FILE_META:  "file-meta",
+  FILE_REQ:   "file-req",
+};
+
+/**
+ * `intent` is the collision guard (OI-2). A key we generated connects as
+ * "create"; if the welcome reports peers already present, that key is taken and
+ * we must regenerate rather than silently join a stranger's clipboard.
+ * A key the user typed or followed a link to is always "join".
+ */
+export const hello = (intent, originId, name) => ({ t: T.HELLO, intent, originId, name });
+
+export const clip = ({ payload, iv, originId }) => ({
+  t: T.CLIP, payload, iv, originId, ts: Date.now(),
+});
+
+export const ping = () => ({ t: T.PING });
+
+export const fileMeta = ({ id, name, size, type, thumb, originId }) => ({
+  t: T.FILE_META, id, name, size, type, thumb, originId,
+});
+
+export const fileReq = ({ id, to, originId }) => ({
+  t: T.FILE_REQ, id, to, originId,
+});
+
+export function parse(raw) {
+  try { return JSON.parse(raw); }
+  catch { return { t: T.ERROR, code: "BAD_JSON" }; }
+}
+
+export const ERRORS = {
+  TOO_LARGE:    "That clip is over the 32 KB limit",
+  RATE_LIMITED: "Slow down — too many messages",
+  ROOM_FULL:    "This session already has the maximum number of devices",
+  BAD_JSON:     "The relay sent something unreadable",
+  NO_STREAM:    "The connection expired — reconnecting",
+  // Only ever shown after the transport has given up retrying: the usual cause
+  // is our own just-closed connection still holding the name, which clears on
+  // its own. See relay.js reclaimIdentity().
+  PEER_ID_TAKEN: "Another device in this session is using the same id — files may not reach this one",
+  // Locked sessions. In practice unreachable from a correct client: a locked
+  // room's name is derived from the PIN, so a device that got the PIN wrong is
+  // addressing a different room entirely rather than being turned away from
+  // this one. It fires if a client's room derivation and key derivation ever
+  // disagree — which is a bug, and this is how it surfaces instead of a
+  // session that connects and then reads nothing.
+  AUTH_FAILED:  "This session's PIN does not match the one already in use here",
+};