realtimeclipboard 0.5.0 → 0.7.0

package/src/core/crypto.js

@@ -25,6 +25,13 @@ const dec = new TextDecoder();
 /** Derivation is expensive (OI-8), so cache per key for the session. */
 let cached = { id: null, open: null };
 
+/**
+ * Bumped by clearCache(). A derivation that was already in flight when the user
+ * left the room resolves afterwards, and storing its result would put the AES
+ * key of a room they walked out of back into the cache the purge just emptied.
+ */
+let generation = 0;
+
 /**
  * Both outputs of an open session, from one PBKDF2.
  *
@@ -39,6 +46,7 @@ let cached = { id: null, open: null };
  */
 export async function deriveOpen(key) {
   if (cached.id === `open:${key}` && cached.open) return cached.open;
+  const gen = generation;
 
   const material = await crypto.subtle.importKey(
     "raw", enc.encode(key), "PBKDF2", false, ["deriveBits"]
@@ -51,7 +59,7 @@ export async function deriveOpen(key) {
   );
 
   const open = await expand(prk, CRYPTO.OPEN_INFO);
-  cached = { id: `open:${key}`, open };
+  if (gen === generation) cached = { id: `open:${key}`, open };
   return open;
 }
 
@@ -158,7 +166,10 @@ export async function decrypt(aesKey, payloadB64, ivB64) {
 // 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 }; }
+export function clearCache() {
+  generation++;
+  cached = { id: null, open: null };
+}
 
 /* ---- hex helpers ---- */
 function hex(bytes) {

package/src/core/keys.js

@@ -1,6 +1,7 @@
 /** Share-key generation and normalisation. */
 
-import { KEY, LOCK } from "./config.js";
+import { KEY, LOCK, SITE } from "./config.js";
+import { IS_WEB } from "./native.js";
 import * as state from "./state.js";
 
 // Modulo bias: 256 does not divide 30, costing ~0.03 bits over a 6-char key.
@@ -42,11 +43,46 @@ export function normalise(raw) {
  * KEY.ALPHABET constrains what we PRODUCE. Validation must accept anything a
  * peer might legitimately hand us: a key from another build is still a valid
  * hash input, and rejecting an in-use key strands the user with no way to join.
- * "D75LV" contains an L, which the generator never emits, and still has to work.
+ * "D75LVX9QR" contains an L, which the generator never emits, and still works.
+ *
+ * Permissive about the ALPHABET, not about the LENGTH — see KEY.MIN_LENGTH.
  */
 export function isValid(raw) {
+  return rejectReason(raw) === null;
+}
+
+/**
+ * WHY a key was refused, or null if it was not. `isValid()` answers the question
+ * the code asks; this answers the one the user asks.
+ *
+ * The distinction matters at boot. A key that is merely absent means "generate
+ * one" — the ordinary first visit. A key that is present and too short is a
+ * request we are declining, and declining it silently is what let `#F5H4` open
+ * a session with 19 bits behind it. See ui/shell/keyGate.js.
+ */
+export function rejectReason(raw) {
   const k = normalise(raw);
-  return k.length >= 4 && k.length <= 32;
+  if (!k.length) return "empty";
+  if (k.length < KEY.MIN_LENGTH) return "short";
+  if (k.length > KEY.MAX_LENGTH) return "long";
+  return null;
+}
+
+/**
+ * One sentence for a surface with no room for a card — the CLI's exit message
+ * and the extension's error. `null` when the key is fine.
+ *
+ * Here rather than at each call site so the two of them cannot drift from each
+ * other or from the floor: both said "is not a valid key" and left the reader
+ * to guess which of length, characters or typo they had hit.
+ */
+export function rejectMessage(raw) {
+  const reason = rejectReason(raw);
+  if (!reason) return null;
+  const n = normalise(raw).length;
+  if (reason === "empty") return "it has no usable characters in it";
+  if (reason === "long") return `it is ${n} characters; the most a key may be is ${KEY.MAX_LENGTH}`;
+  return `it is ${n} character${n === 1 ? "" : "s"}; a key needs at least ${KEY.MIN_LENGTH}`;
 }
 
 /**
@@ -125,6 +161,38 @@ export function clearUrl() {
   history.replaceState(null, "", location.pathname + location.search);
 }
 
+/**
+ * A link for the OTHER device to open, which is why it is not always this one's
+ * URL. Only a browser can hand out its own address — see SITE in config.js for
+ * the hosts that cannot.
+ */
 export function shareLink(key, locked = false) {
-  return `${location.origin}${location.pathname}#${fragment(key, locked)}`;
+  const here = IS_WEB && typeof location !== "undefined"
+    ? location.origin + location.pathname
+    : SITE.APP_URL;
+  return `${here}#${fragment(key, locked)}`;
+}
+
+/**
+ * The share link, plus the flag that asks the app to open its QR immediately.
+ *
+ * Here rather than in the surface that wanted it, because there is exactly one
+ * rule to get wrong and it is not obvious: the query goes BEFORE the fragment.
+ * Everything after `#` is the key, so `#KEY?qr=1` is not a broken flag — it is a
+ * broken key, and the symptom is a room nobody else can join rather than an
+ * error anybody sees. One implementation, tested in tests/unit/sharelink.mjs.
+ */
+export function qrLink(key, locked = false) {
+  const [base, fragment] = shareLink(key, locked).split("#");
+  const sep = base.includes("?") ? "&" : "?";
+  return `${base}${sep}${SITE.QR_PARAM}=1${fragment ? `#${fragment}` : ""}`;
 }
+
+/**
+ * Did this visit ask for the code? The reader sits beside the writer so the two
+ * cannot drift, and it is strict: `?qr=0` and `?qr=false` are not requests, and
+ * a truthiness test on the string would have treated both as one.
+ */
+export const qrRequested = () =>
+  typeof location !== "undefined"
+  && new URLSearchParams(location.search).get(SITE.QR_PARAM) === "1";

package/src/core/native.js

@@ -1,5 +1,5 @@
 /**
- * The one place that knows there is a native shell underneath.
+ * The one place that knows there is a native host underneath.
  *
  * Rank 0 and DOM-free, because the answer also decides the default key length in
  * config.js — and core/ is imported by the node tests and shipped in the npm
@@ -9,6 +9,11 @@
  * three failed at once: `withGlobalTauri` had never been switched on, so the
  * global did not exist, T0 never started, and the desktop app silently degraded
  * to a browser tab that cannot watch the clipboard.
+ *
+ * There are two hosts now — the Tauri shell, which announces itself through a
+ * global, and the VS Code extension, which registers itself through setHost().
+ * Both answer the same two questions (`invoke`, `listen`), so everything above
+ * this file sees one native boundary rather than a growing list of shells.
  */
 
 const g = globalThis;
@@ -22,34 +27,73 @@ const IN_TAURI = typeof g.__TAURI_INTERNALS__ === "object"
 /** `document` first: jsdom has both, and the DOM suites want to be "web". */
 const IN_NODE = typeof document === "undefined" && !!g.process?.versions?.node;
 
-export const SURFACE    = IN_TAURI ? "desktop" : IN_NODE ? "cli" : "web";
+/**
+ * A host that cannot be detected declares itself, before this module is first
+ * imported. Declared rather than sniffed on purpose: `process.env.VSCODE_PID` is
+ * set inside VS Code's *integrated terminal* as well as inside its extension
+ * host, so `realtimeclipboard watch …` typed at that terminal would claim to be
+ * the extension.
+ */
+const DECLARED = typeof g.__REALTIMECLIPBOARD_SURFACE__ === "string"
+  ? g.__REALTIMECLIPBOARD_SURFACE__
+  : null;
+
+export const SURFACE    = DECLARED ?? (IN_TAURI ? "desktop" : IN_NODE ? "cli" : "web");
 export const IS_DESKTOP = SURFACE === "desktop";
 export const IS_WEB     = SURFACE === "web";
 export const IS_CLI     = SURFACE === "cli";
 
-/** Call a command in desktop/src-tauri/src/main.rs. Null anywhere else. */
+/**
+ * Surfaces the user installed rather than visited. What this actually governs is
+ * key length: an installed surface keeps its session across restarts and is worth
+ * the longer key, a visited one is usually typing it to somebody.
+ */
+export const IS_INSTALLED = IS_DESKTOP || SURFACE === "vscode";
+
+let host = null;
+
+/**
+ * Register the process-side half of a native shell. Called once, before anything
+ * that depends on it — which is why the three consumers below all ask through a
+ * function rather than reading a const captured at import time.
+ */
+export function setHost(h) { host = h; }
+
+/** Is there something underneath that owns the OS clipboard? */
+export const hasNativeClipboard = () => IN_TAURI || host !== null;
+
+/** How this host watches the clipboard, for the tier readout. */
+export const hostNote = () => host?.note ?? "watching the system clipboard";
+
+/**
+ * Call a command on the host — desktop/src-tauri/src/main.rs, or a registered
+ * host's own implementation. Null where there is no host.
+ */
 export async function invoke(command, args) {
   const core = g.__TAURI__?.core;
-  if (!core?.invoke) return null;
-  try {
-    return await core.invoke(command, args);
-  } catch (err) {
-    console.warn(`[realtimeclipboard] native "${command}" failed:`, err);
-    return null;
-  }
+  return run(host?.invoke ?? core?.invoke?.bind(core), "invoke", command, args);
 }
 
 /**
- * Subscribe to an event the shell emits. Resolves to an unsubscribe function, or
- * null off the desktop so callers can treat "no shell" as ordinary.
+ * Subscribe to an event the host emits. Resolves to an unsubscribe function, or
+ * null where there is no host, so callers can treat "no shell" as ordinary.
+ *
+ * The Tauri API hands the listener an envelope; a registered host calls back with
+ * the payload. Unwrapped here so `clipboard://text` looks the same to capture.js
+ * whichever shell is underneath.
  */
 export async function listen(event, fn) {
   const api = g.__TAURI__?.event;
-  if (!api?.listen) return null;
+  return run(host?.listen ?? (api?.listen && ((e, cb) => api.listen(e, m => cb(m.payload)))),
+             "listen", event, fn);
+}
+
+async function run(fn, what, a, b) {
+  if (!fn) return null;
   try {
-    return await api.listen(event, ({ payload }) => fn(payload));
+    return await fn(a, b);
   } catch (err) {
-    console.warn(`[realtimeclipboard] native listen "${event}" failed:`, err);
+    console.warn(`[realtimeclipboard] native ${what} "${a}" failed:`, err);
     return null;
   }
 }

package/src/core/state.js

@@ -6,7 +6,7 @@
  */
 
 import { emit, EV } from "./bus.js";
-import { DEFAULT_SYNC_MODE, SYNC_MODES, KEY, TEXT } from "./config.js";
+import { DEFAULT_SYNC_MODE, DEFAULT_THEME, SYNC_MODES, KEY, TEXT } from "./config.js";
 import * as storage from "./storage.js";
 
 const state = {
@@ -53,6 +53,9 @@ const state = {
     // setting that decides whether a secret touches disk, so it is a switch and
     // it is named plainly in the UI. See storage.js saveLastKey.
     rememberKey: true,
+    // system | light | dark. "system" is not a third colour scheme, it is the
+    // absence of a choice — see config.js THEMES and ui/features/theme.js.
+    theme: DEFAULT_THEME,
   },
 };
 
@@ -70,6 +73,7 @@ export function restore() {
   if (saved) Object.assign(state.settings, saved);
 
   migrateReceiving(saved);
+  watchSettings();
 
   /**
    * Anyone who toggled any switch before this shipped has an explicit
@@ -106,10 +110,37 @@ function migrateReceiving(saved) {
 /** Change a setting and remember it. The only path that persists one. */
 export function saveSetting(name, value) {
   state.settings[name] = value;
-  storage.saveSettings(state.settings);
+  // Merged into what is on disk rather than written wholesale. Two tabs of one
+  // session each hold their own copy of this object from boot, so a whole-object
+  // write reverted every setting the OTHER tab had changed since — including the
+  // sync rung, which silently put a device the user had taken offline back on
+  // the wire at the next launch, and `rememberKey`, which decides whether the
+  // share key touches disk at all.
+  storage.saveSettings({ ...(storage.loadSettings() ?? {}), [name]: value });
   emit(EV.SETTINGS_CHANGED, { name, value });
 }
 
+let watching = false;
+
+/**
+ * Adopt what another tab saved, so two windows of one session do not disagree
+ * about the rung. `external` marks these apart from this tab's own changes:
+ * the control that owns a setting has already applied it locally by the time it
+ * emits, and would double-apply on its own event.
+ */
+function watchSettings() {
+  if (watching) return;
+  watching = true;
+  storage.onSettingsChanged(saved => {
+    if (!saved) return;
+    for (const [name, value] of Object.entries(saved)) {
+      if (state.settings[name] === value) continue;
+      state.settings[name] = value;
+      emit(EV.SETTINGS_CHANGED, { name, value, external: true });
+    }
+  });
+}
+
 export function setKey({ key, roomHash, aesKey, locked = false, authToken = null }) {
   state.key = key;
   state.roomHash = roomHash ?? state.roomHash;

package/src/core/storage.js

@@ -26,6 +26,22 @@ export function remove(name) {
 export const loadSettings = () => read("settings", null);
 export const saveSettings = s => write("settings", s);
 
+/**
+ * Another tab saved the settings. localStorage delivers this event only to the
+ * tabs that did NOT write, which is exactly the set that needs to catch up.
+ *
+ * Guarded rather than assumed: this module is published in the npm package and
+ * `cli/` imports it, where there are no other tabs and no event target.
+ */
+export function onSettingsChanged(cb) {
+  if (typeof addEventListener !== "function") return;
+  addEventListener("storage", e => {
+    if (e.key !== PREFIX + "settings") return;
+    try { cb(e.newValue === null ? null : JSON.parse(e.newValue)); }
+    catch { /* another tab wrote something we cannot read */ }
+  });
+}
+
 /**
  * The relay this device talks to, when it is not the one the build ships with.
  * config.js reads this key directly at module evaluation, because the URL has to

package/src/core/surface.js

@@ -0,0 +1,84 @@
+/**
+ * What this surface is allowed to load, and what to call it in a report.
+ *
+ * Ads differ per surface by POLICY, not by preference. Google's programme
+ * policies forbid ads in software applications — "Google ads may not be
+ * integrated into a software application of any kind" — and enforcement is
+ * account-level, so an AdSense tag in the desktop shell or the extension would
+ * put the website's revenue at risk too. `adNetwork()` is the one place that
+ * decides, so the rule is greppable rather than spread across three tag
+ * modules. docs/decisions/0001 has the reasoning.
+ *
+ * A leaf on purpose: it imports from core/ and nothing in core/ imports it.
+ * `device.js` reaches `storage.js` which reaches `config.js` which reaches
+ * `native.js`, so folding this into any of those would close a cycle and the
+ * symptom would be a TDZ error at import time, not a legible one.
+ */
+
+import { SURFACE } from "./native.js";
+import { os } from "./device.js";
+import { adsEnabled, analyticsEnabled } from "./config.js";
+
+/**
+ * Running as an installed app rather than a browser tab. Guarded the way
+ * core/CLAUDE.md requires — this module is imported by the node tests and by
+ * the published npm package, where `matchMedia` does not exist.
+ *
+ * `fullscreen` is deliberately NOT in this list, though ui/features/install.js
+ * tests for it: F11 in an ordinary tab matches it, which is harmless when the
+ * question is "should I offer to install" and wrong when the question is "which
+ * surface produced this event" — it would file plain web traffic as web-pwa.
+ */
+export function isStandalone() {
+  const mm = globalThis.matchMedia;
+  if (!mm) return false;
+  return ["standalone", "window-controls-overlay", "minimal-ui"]
+    .some(mode => mm.call(globalThis, `(display-mode: ${mode})`).matches)
+    || globalThis.navigator?.standalone === true;   // iOS Safari's non-standard flag
+}
+
+/**
+ * The GA4 `rtc_surface` value. One vocabulary for every tag module.
+ *
+ * `desktop-other` exists so the function is total: Tauri ships exactly three
+ * desktop targets, so that value appearing in a report is a user-agent bug worth
+ * seeing rather than something to quietly fold into desktop-linux.
+ */
+export function platform() {
+  if (SURFACE === "vscode") return "vscode";
+  if (SURFACE === "cli") return "cli";
+  if (SURFACE === "desktop") {
+    const name = os();
+    return name === "Windows" ? "desktop-windows"
+         : name === "macOS"   ? "desktop-mac"
+         : name === "Linux"   ? "desktop-linux"
+         : "desktop-other";
+  }
+  return isStandalone() ? "web-pwa" : "web-browser";
+}
+
+/**
+ * Which ad network this surface may load, if any.
+ *
+ * "none" for vscode and cli is unconditional — it does not depend on an ID being
+ * empty, because a rule that a configuration change can undo is not a rule.
+ * tests/unit/adpolicy.mjs asserts exactly that.
+ */
+export function adNetwork() {
+  if (SURFACE === "web") return adsEnabled() ? "adsense" : "none";
+  if (SURFACE === "desktop") return "house";
+  return "none";
+}
+
+/**
+ * Only a surface with a document can carry a tag at all.
+ *
+ * The CLI and the VS Code extension are both Node hosts — the extension runs in
+ * the extension host and owns no webview, so ui/features/analytics.js is never
+ * even imported there. Saying "vscode reports" would describe something that
+ * cannot happen, and it would also mean answering to `vscode.env.isTelemetryEnabled`
+ * before it ever could. If the extension grows a webview, that opt-out is the
+ * prerequisite, not an afterthought. docs/decisions/0003.
+ */
+export const analyticsOn = () =>
+  (SURFACE === "web" || SURFACE === "desktop") && analyticsEnabled();