viveworker 0.7.0 → 0.8.0

package/web/remote-pairing/keys.js

@@ -0,0 +1,237 @@
+/**
+ * web/remote-pairing/keys.js — IndexedDB-backed identity key store (browser).
+ *
+ * Mirrors the Node-side `scripts/lib/remote-pairing/keys.mjs` API
+ * (load / save / ensure / clear) so the rest of the remote-pairing
+ * client can consume the same shape regardless of platform. Pure crypto
+ * helpers (`generateIdentityKeypair`, `publicFromPrivate`,
+ * `fingerprintIdentity`, hex helpers) are re-exported from the shared
+ * bundle.
+ *
+ * Storage model:
+ *   DB:    viveworker-remote-pairing
+ *   Store: keys
+ *   Key:   "identity"
+ *   Value: { priv: Uint8Array(32), pub: Uint8Array(32), createdAtMs: number }
+ *
+ * Threat model (Phase 2 MVP):
+ *   - IndexedDB is origin-scoped and survives PWA restarts. A user
+ *     "clear site data" wipes it; we treat that as the device losing
+ *     its pairing identity (re-pair from LAN required).
+ *   - Private bytes are stored extractable. Migrating to Web Crypto
+ *     non-extractable CryptoKey requires switching the handshake's DH
+ *     calls to Web Crypto's X25519 (Chrome 100+, Safari 17+, Firefox 100+).
+ *     That's tracked as a future hardening pass — for now filesystem-style
+ *     origin scoping is what we lean on.
+ *
+ * The async API tolerates "no IndexedDB" (e.g., Safari private mode in
+ * some configs): callers get a thrown error with a clear message and can
+ * decide whether to surface it to the user or fall back to in-memory only.
+ */
+
+// Relative path so the same source resolves correctly under both the bridge
+// (which serves /remote-pairing/keys.js → /remote-pairing.bundle.js) and
+// Node-driven unit tests (which load it from the filesystem).
+import {
+  generateIdentityKeypair as bundleGenerateIdentityKeypair,
+  publicFromPrivate,
+  fingerprintIdentity,
+  bytesToHex,
+  hexToBytes,
+  IDENTITY_KEY_BYTES,
+} from "../remote-pairing.bundle.js";
+
+// Re-export the pure helpers so callers don't have to import the bundle
+// directly for everyday operations.
+export {
+  publicFromPrivate,
+  fingerprintIdentity,
+  bytesToHex,
+  hexToBytes,
+  IDENTITY_KEY_BYTES,
+};
+
+const DB_NAME = "viveworker-remote-pairing";
+const DB_VERSION = 1;
+const STORE_NAME = "keys";
+const RECORD_KEY = "identity";
+
+// ---------------------------------------------------------------------------
+// IndexedDB plumbing
+// ---------------------------------------------------------------------------
+
+/**
+ * Open (or upgrade) the database. Cached after first open; safe to call
+ * concurrently — only one upgrade transaction will run.
+ *
+ * @param {{ indexedDB?: IDBFactory }} [options]
+ * @returns {Promise<IDBDatabase>}
+ */
+function openDB({ indexedDB = globalThis.indexedDB } = {}) {
+  if (!indexedDB) {
+    return Promise.reject(new Error("IndexedDB not available in this environment"));
+  }
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME);
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error("indexedDB.open failed"));
+    req.onblocked = () => reject(new Error("indexedDB.open blocked by another tab"));
+  });
+}
+
+/**
+ * Run a single object-store transaction. The callback receives the store
+ * and returns the IDBRequest whose `result` we should resolve with.
+ */
+function runTx(db, mode, fn) {
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, mode);
+    const store = tx.objectStore(STORE_NAME);
+    let req;
+    try {
+      req = fn(store);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    tx.oncomplete = () => resolve(req?.result);
+    tx.onerror = () => reject(tx.error ?? new Error("transaction failed"));
+    tx.onabort = () => reject(tx.error ?? new Error("transaction aborted"));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a fresh keypair (does NOT persist; pair with `saveIdentityKeypair`
+ * or use `ensureIdentityKeypair` for the load-or-create path).
+ *
+ * @returns {{ priv: Uint8Array, pub: Uint8Array }}
+ */
+export function generateIdentityKeypair() {
+  return bundleGenerateIdentityKeypair();
+}
+
+/**
+ * Load the persisted keypair, or null if none has been saved yet.
+ *
+ * @param {{ indexedDB?: IDBFactory }} [options]
+ * @returns {Promise<{ priv: Uint8Array, pub: Uint8Array, createdAtMs: number } | null>}
+ */
+export async function loadIdentityKeypair(options) {
+  const db = await openDB(options);
+  try {
+    const record = await runTx(db, "readonly", (store) => store.get(RECORD_KEY));
+    if (!record) return null;
+    const priv = coerceBytes(record.priv);
+    const pub = coerceBytes(record.pub);
+    if (priv.length !== IDENTITY_KEY_BYTES || pub.length !== IDENTITY_KEY_BYTES) {
+      return null; // corrupt; let caller decide whether to reset
+    }
+    // Sanity check: derived pub should match stored pub. If it diverges
+    // (shouldn't happen barring storage corruption), trust the priv.
+    const derivedPub = publicFromPrivate(priv);
+    if (!equalBytes(derivedPub, pub)) {
+      // Best we can do client-side; surface via a console warning so devs
+      // notice during testing. Production callers will eventually want to
+      // wipe + regenerate.
+      console.warn("[remote-pairing/keys] stored pub disagrees with derived pub; trusting private key");
+      return { priv, pub: derivedPub, createdAtMs: numberOr(record.createdAtMs, Date.now()) };
+    }
+    return { priv, pub, createdAtMs: numberOr(record.createdAtMs, Date.now()) };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Persist a keypair. Overwrites any existing record.
+ *
+ * @param {{ priv: Uint8Array, pub: Uint8Array }} keypair
+ * @param {{ indexedDB?: IDBFactory }} [options]
+ */
+export async function saveIdentityKeypair(keypair, options) {
+  if (!keypair?.priv || !keypair?.pub) throw new TypeError("keypair { priv, pub } required");
+  if (keypair.priv.length !== IDENTITY_KEY_BYTES) throw new RangeError("priv must be 32 bytes");
+  if (keypair.pub.length !== IDENTITY_KEY_BYTES) throw new RangeError("pub must be 32 bytes");
+
+  const db = await openDB(options);
+  try {
+    const record = {
+      priv: copyBytes(keypair.priv),
+      pub: copyBytes(keypair.pub),
+      createdAtMs: Date.now(),
+    };
+    await runTx(db, "readwrite", (store) => store.put(record, RECORD_KEY));
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Load the persisted keypair, generating + saving a fresh one if none exists.
+ *
+ * @param {{ indexedDB?: IDBFactory }} [options]
+ * @returns {Promise<{ priv: Uint8Array, pub: Uint8Array, createdAtMs: number }>}
+ */
+export async function ensureIdentityKeypair(options) {
+  const existing = await loadIdentityKeypair(options);
+  if (existing) return existing;
+  const fresh = generateIdentityKeypair();
+  await saveIdentityKeypair(fresh, options);
+  return { ...fresh, createdAtMs: Date.now() };
+}
+
+/**
+ * Wipe the persisted keypair. Used by the "unpair this device" flow.
+ *
+ * @param {{ indexedDB?: IDBFactory }} [options]
+ */
+export async function clearIdentityKeypair(options) {
+  const db = await openDB(options);
+  try {
+    await runTx(db, "readwrite", (store) => store.delete(RECORD_KEY));
+  } finally {
+    db.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function coerceBytes(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (Array.isArray(value)) return new Uint8Array(value);
+  throw new TypeError(`unsupported byte container: ${typeof value}`);
+}
+
+function copyBytes(bytes) {
+  // Defensive copy so a caller mutating its array after save doesn't
+  // poison the persisted record. (IndexedDB structured-clones, so this
+  // is partially redundant — but it costs ~64B and removes a footgun.)
+  const u8 = coerceBytes(bytes);
+  const out = new Uint8Array(u8.length);
+  out.set(u8);
+  return out;
+}
+
+function equalBytes(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+function numberOr(value, fallback) {
+  return Number.isFinite(value) ? value : fallback;
+}

package/web/remote-pairing/pairing-state.js

@@ -0,0 +1,313 @@
+/**
+ * web/remote-pairing/pairing-state.js — localStorage-backed pairing record.
+ *
+ * After a successful LAN pairing the phone calls
+ * `POST /api/remote-pairing/lan-enroll` and gets back enough information
+ * to reach the same bridge over the relay when off-LAN:
+ *
+ *   - pairingId         (relay slot identifier; opaque to the phone)
+ *   - relayToken        (capability required by the public relay)
+ *   - bridgePubHex      (bridge's X25519 static pubkey — the phone uses
+ *                        it as the responder static for Noise IK)
+ *   - bridgeFingerprint (canonical "AB:CD:EF…" form for display)
+ *   - relayUrl          (wss://… — destination of the WebSocket dial)
+ *   - phonePub          (echoed; useful for "is this still my keypair?"
+ *                        sanity checks against IndexedDB on bootstrap)
+ *   - label             (whatever the phone sent at enroll time)
+ *   - addedAtMs         (server-side timestamp; phones with skewed clocks
+ *                        still see a coherent "added on" date)
+ *   - relayTokenUpdatedAtMs (server-side timestamp of the latest relayToken)
+ *
+ * Why localStorage and not IndexedDB:
+ *   - The X25519 *private* key lives in IndexedDB (keys.js) because
+ *     it's the secret half of the identity. This file stores routing
+ *     capability metadata — including `relayToken`, which can reach the
+ *     correct relay room but still cannot decrypt or authenticate the Noise
+ *     channel without the IndexedDB private key. Treat XSS on this origin as
+ *     device compromise, just like an attacker reading same-origin session
+ *     state.
+ *   - localStorage is synchronous, which is convenient on the bootstrap
+ *     hot path where we want to know "is this phone enrolled?" before
+ *     we even have a chance to await anything.
+ *
+ * Single-record assumption:
+ *   The phone is paired with at most ONE bridge at a time (current PWA
+ *   design — `bridge URL = origin`). If we later support multi-bridge
+ *   bookmarking, this becomes an array keyed by origin and the helpers
+ *   grow a `bridgeOrigin` parameter. Keep callers using the helpers
+ *   here so that future migration is local.
+ *
+ * Schema versioning:
+ *   The `version` field lets us reject + clear unknown shapes on bootstrap.
+ *   When the format evolves, bump the constant and write a migrator.
+ */
+
+const STORAGE_KEY = "viveworker.remote-pairing.state";
+const SCHEMA_VERSION = 2;
+const LEGACY_SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {Object} RemotePairingState
+ * @property {number} version            schema version (== SCHEMA_VERSION)
+ * @property {string} pairingId          relay slot identifier
+ * @property {string} relayToken         relay capability token
+ * @property {string} phonePub           lowercase 64-hex of the phone's X25519 pub
+ * @property {string} phoneFingerprint   canonical "AB:CD:EF…" of phonePub
+ * @property {string} bridgePubHex       lowercase 64-hex of the bridge's X25519 pub
+ * @property {string} bridgeFingerprint  canonical fingerprint of bridgePubHex
+ * @property {string} relayUrl           ws:// or wss:// URL the bridge is on
+ * @property {string} label              user-visible device label
+ * @property {number} addedAtMs          server-side enroll time
+ * @property {number} relayTokenUpdatedAtMs server-side token update time, 0 for legacy records
+ */
+
+/**
+ * Resolve the localStorage instance. Wrapped so tests can pass a stub
+ * (e.g. a fake { getItem, setItem, removeItem } object) without monkey-
+ * patching globalThis.
+ *
+ * @returns {Storage | null}
+ */
+function getStorage(opts) {
+  if (opts?.storage) return opts.storage;
+  if (typeof globalThis === "undefined") return null;
+  // localStorage may be missing entirely (older Node-based test contexts)
+  // or throw on access (some private-mode browsers). Treat both as "no
+  // persistent storage" — the caller can decide whether to surface the
+  // failure or fall back to in-memory only.
+  try {
+    return globalThis.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the persisted pairing state, or null if there isn't one (or it's
+ * malformed / wrong version — both treated identically: caller should
+ * re-enroll).
+ *
+ * @param {{ storage?: Storage }} [opts]
+ * @returns {RemotePairingState | null}
+ */
+export function loadPairingState(opts) {
+  const store = getStorage(opts);
+  if (!store) return null;
+  let raw;
+  try {
+    raw = store.getItem(STORAGE_KEY);
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  if (parsed.version !== SCHEMA_VERSION) return null;
+  // Light shape validation — every required string field must be present
+  // and non-empty. We don't re-validate hex format here; the bridge owns
+  // that and any garbage we'd find here came from a corrupted localStorage.
+  const required = [
+    "pairingId",
+    "relayToken",
+    "phonePub",
+    "phoneFingerprint",
+    "bridgePubHex",
+    "bridgeFingerprint",
+    "relayUrl",
+  ];
+  for (const key of required) {
+    if (typeof parsed[key] !== "string" || parsed[key].length === 0) {
+      return null;
+    }
+  }
+  return {
+    version: SCHEMA_VERSION,
+    pairingId: parsed.pairingId,
+    relayToken: parsed.relayToken,
+    phonePub: parsed.phonePub.toLowerCase(),
+    phoneFingerprint: parsed.phoneFingerprint,
+    bridgePubHex: parsed.bridgePubHex.toLowerCase(),
+    bridgeFingerprint: parsed.bridgeFingerprint,
+    relayUrl: parsed.relayUrl,
+    label: typeof parsed.label === "string" ? parsed.label : "",
+    addedAtMs: Number.isFinite(parsed.addedAtMs) ? parsed.addedAtMs : 0,
+    relayTokenUpdatedAtMs: Number.isFinite(parsed.relayTokenUpdatedAtMs)
+      ? parsed.relayTokenUpdatedAtMs
+      : 0,
+  };
+}
+
+/**
+ * Inspect the raw stored pairing state without silently collapsing every
+ * non-v2 shape to null. This lets the app distinguish "not enrolled yet"
+ * from "legacy v1 record needs a LAN refresh after relayToken hardening".
+ *
+ * @param {{ storage?: Storage }} [opts]
+ * @returns {{
+ *   status: "ready" | "missing" | "legacy-v1" | "missing-token" | "malformed" | "unsupported-version" | "storage-unavailable",
+ *   needsEnrollment: boolean,
+ *   record: RemotePairingState | null,
+ *   legacyRecord?: object | null,
+ * }}
+ */
+export function inspectPairingState(opts) {
+  const store = getStorage(opts);
+  if (!store) {
+    return stateStatus("storage-unavailable", false);
+  }
+
+  let raw;
+  try {
+    raw = store.getItem(STORAGE_KEY);
+  } catch {
+    return stateStatus("storage-unavailable", false);
+  }
+  if (!raw) {
+    return stateStatus("missing", true);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return stateStatus("malformed", true);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return stateStatus("malformed", true);
+  }
+
+  if (parsed.version === LEGACY_SCHEMA_VERSION) {
+    return {
+      ...stateStatus("legacy-v1", true),
+      legacyRecord: normalizeLegacyRecordForInspection(parsed),
+    };
+  }
+
+  if (parsed.version !== SCHEMA_VERSION) {
+    return stateStatus("unsupported-version", true);
+  }
+
+  if (typeof parsed.relayToken !== "string" || parsed.relayToken.length === 0) {
+    return stateStatus("missing-token", true);
+  }
+
+  const record = loadPairingState(opts);
+  if (!record) {
+    return stateStatus("malformed", true);
+  }
+  return {
+    ...stateStatus("ready", false),
+    record,
+  };
+}
+
+/**
+ * Persist a pairing state record. Overwrites any existing record (the
+ * single-record assumption above — re-enrolling under the same origin
+ * replaces the previous bridge).
+ *
+ * @param {Omit<RemotePairingState, "version"> & { version?: number }} record
+ * @param {{ storage?: Storage }} [opts]
+ * @returns {boolean} true if written, false if storage is unavailable.
+ */
+export function savePairingState(record, opts) {
+  const store = getStorage(opts);
+  if (!store) return false;
+  if (!record || typeof record !== "object") {
+    throw new TypeError("savePairingState: record must be an object");
+  }
+  // Validate inputs synchronously so a buggy caller fails loudly rather
+  // than persisting "undefined" strings.
+  for (const key of [
+    "pairingId",
+    "relayToken",
+    "phonePub",
+    "phoneFingerprint",
+    "bridgePubHex",
+    "bridgeFingerprint",
+    "relayUrl",
+  ]) {
+    if (typeof record[key] !== "string" || record[key].length === 0) {
+      throw new TypeError(`savePairingState: ${key} must be a non-empty string`);
+    }
+  }
+  const out = {
+    version: SCHEMA_VERSION,
+    pairingId: record.pairingId,
+    relayToken: record.relayToken,
+    phonePub: record.phonePub.toLowerCase(),
+    phoneFingerprint: record.phoneFingerprint,
+    bridgePubHex: record.bridgePubHex.toLowerCase(),
+    bridgeFingerprint: record.bridgeFingerprint,
+    relayUrl: record.relayUrl,
+    label: typeof record.label === "string" ? record.label : "",
+    addedAtMs: Number.isFinite(record.addedAtMs) ? record.addedAtMs : Date.now(),
+    relayTokenUpdatedAtMs: Number.isFinite(record.relayTokenUpdatedAtMs)
+      ? record.relayTokenUpdatedAtMs
+      : 0,
+  };
+  try {
+    store.setItem(STORAGE_KEY, JSON.stringify(out));
+    return true;
+  } catch {
+    // Storage quota / disabled-by-user / private-mode-throws → swallow.
+    // The user can re-trigger enrollment from the settings page later.
+    return false;
+  }
+}
+
+/**
+ * Clear the pairing state. Use cases:
+ *   - User logged out / unpaired the phone
+ *   - Bridge identity changed (we detect it via bridgePubHex mismatch
+ *     and need to force a re-enroll)
+ *   - localStorage held a malformed record (shouldn't happen but
+ *     `loadPairingState` returning null while `getItem` returns
+ *     non-empty is a signal we want gone)
+ *
+ * @param {{ storage?: Storage }} [opts]
+ */
+export function clearPairingState(opts) {
+  const store = getStorage(opts);
+  if (!store) return;
+  try {
+    store.removeItem(STORAGE_KEY);
+  } catch {
+    // ignore
+  }
+}
+
+function stateStatus(status, needsEnrollment) {
+  return {
+    status,
+    needsEnrollment,
+    record: null,
+    legacyRecord: null,
+  };
+}
+
+function normalizeLegacyRecordForInspection(parsed) {
+  return {
+    version: LEGACY_SCHEMA_VERSION,
+    pairingId: typeof parsed.pairingId === "string" ? parsed.pairingId : "",
+    phonePub: typeof parsed.phonePub === "string" ? parsed.phonePub.toLowerCase() : "",
+    phoneFingerprint: typeof parsed.phoneFingerprint === "string" ? parsed.phoneFingerprint : "",
+    bridgePubHex: typeof parsed.bridgePubHex === "string" ? parsed.bridgePubHex.toLowerCase() : "",
+    bridgeFingerprint: typeof parsed.bridgeFingerprint === "string" ? parsed.bridgeFingerprint : "",
+    relayUrl: typeof parsed.relayUrl === "string" ? parsed.relayUrl : "",
+    label: typeof parsed.label === "string" ? parsed.label : "",
+    addedAtMs: Number.isFinite(parsed.addedAtMs) ? parsed.addedAtMs : 0,
+    relayTokenUpdatedAtMs: Number.isFinite(parsed.relayTokenUpdatedAtMs)
+      ? parsed.relayTokenUpdatedAtMs
+      : 0,
+  };
+}
+
+// Test-visible constants for tests that want to assert raw key shape.
+export const __STORAGE_KEY = STORAGE_KEY;
+export const __SCHEMA_VERSION = SCHEMA_VERSION;