feat: add private relay for end-to-end-encrypted remote access (#2087)

Adds OpenChamber Relay — an opt-in way to reach an instance from a phone,
browser, or another desktop from anywhere, with no open inbound ports, no
tunnel, and no shared LAN. The instance dials outbound to a relay; all app
traffic (HTTP, the event stream, terminal, dictation) is multiplexed and
encrypted through a single connection per client, so the relay only ever
forwards opaque ciphertext.

Transport
- End-to-end-encrypted channel over WebCrypto (ECDH P-256 -> HKDF ->
  AES-256-GCM) with a capability-negotiated handshake and a small
  HTTP/SSE/WebSocket multiplexing protocol. A byte-compatible JS host mirror
  is cross-checked by tests.
- Host: outbound connection manager, per-client tunnel dispatcher to the local
  server over loopback, reuse of the existing instance identity key, and
  management routes. Disabled by default; explicit opt-in.
- Client: plugs into the existing runtime layer (runtime-fetch/-url/-switch/
  -auth, event pipeline, terminal, dictation) so features work over the relay
  unchanged; direct-URL and Electron realtime-proxy paths are untouched.

Pairing & UX
- Relay section in Settings -> Remote Instances (live status, QR/link pairing,
  revocation via the existing client-token list) and the mobile connect flow.
- Frame batching and idle-gated keepalive keep tunnel message volume low
  without affecting streaming smoothness.

Security
- The tunnel is transport only; the server authenticates every tunneled
  request exactly as for a direct remote client.
  fragments only. The relay stores no keys, tokens, or payloads.

Operability
- The endpoint can be pinned to a self-hosted rel
  paired clients inherit it from the offer automatically.
- Relay module DOCUMENTATION.md and a relay-trans
  invariants that future WebSocket/streaming changes must follow.

The relay transport is complete and tested; the UI for enabling and pairing
is gated behind openchamber_relay_gate and stays

packages/ui/src/apps/mobileConnections.test.ts

@@ -1,10 +1,19 @@
 import { describe, expect, mock, test } from 'bun:test';
 
-import { validateMobileConnectionSession } from './mobileConnections';
+import { loadMobileConnections, upsertMobileConnection, validateMobileConnectionSession, type MobileRelayConfig } from './mobileConnections';
 
 const originalFetch = globalThis.fetch;
 const originalWindow = globalThis.window;
 
+const createLocalStorageStub = () => {
+  const store = new Map<string, string>();
+  return {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => { store.set(key, value); },
+    removeItem: (key: string) => { store.delete(key); },
+  };
+};
+
 const installTestWindow = () => {
   Object.defineProperty(globalThis, 'window', {
     configurable: true,
@@ -12,6 +21,7 @@ const installTestWindow = () => {
       setTimeout: globalThis.setTimeout.bind(globalThis),
       clearTimeout: globalThis.clearTimeout.bind(globalThis),
       location: { protocol: 'https:' },
+      localStorage: createLocalStorageStub(),
     },
   });
 };
@@ -21,6 +31,95 @@ const restoreGlobals = () => {
   Object.defineProperty(globalThis, 'window', { configurable: true, value: originalWindow });
 };
 
+const STORAGE_KEY = 'openchamber.mobile.connections.v1';
+
+const testRelay: MobileRelayConfig = {
+  relayUrl: 'wss://relay.example/tunnel',
+  serverId: 'srv_test123',
+  hostEncPubJwk: { kty: 'EC', crv: 'P-256', x: 'eHhY', y: 'eVlZ' },
+};
+
+describe('mobile connection storage', () => {
+  test('entries persisted before relay support normalize to direct mode on read', async () => {
+    try {
+      installTestWindow();
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify([
+        { id: 'a', label: 'Home', url: 'http://192.168.1.10:2606', lastUsedAt: 10, clientToken: 'tok-a' },
+        { id: 'b', label: 'Work', url: 'http://work.example', lastUsedAt: 5 },
+      ]));
+
+      const connections = await loadMobileConnections();
+      expect(connections).toHaveLength(2);
+      expect(connections.every((connection) => connection.mode === 'direct')).toBe(true);
+      expect(connections[0]?.relay).toBe(undefined);
+      expect(connections[0]?.clientToken).toBe('tok-a');
+    } finally {
+      restoreGlobals();
+    }
+  });
+
+  test('relay connections round-trip mode and transport config', async () => {
+    try {
+      installTestWindow();
+
+      await upsertMobileConnection({
+        label: 'My Desktop',
+        url: 'openchamber://connect?v=1&mode=relay',
+        clientToken: 'oc_client_secret',
+        relay: testRelay,
+      });
+
+      const connections = await loadMobileConnections();
+      expect(connections).toHaveLength(1);
+      const saved = connections[0]!;
+      expect(saved.mode).toBe('relay');
+      expect(saved.relay).toEqual(testRelay);
+      // Web surface: token stays inline like direct connections.
+      expect(saved.clientToken).toBe('oc_client_secret');
+
+      // Persisted metadata carries only the three transport fields — no grant.
+      const raw = JSON.parse(window.localStorage.getItem(STORAGE_KEY) || '[]') as Array<Record<string, unknown>>;
+      expect(raw[0]?.mode).toBe('relay');
+      expect(Object.keys(raw[0]?.relay as object).sort()).toEqual(['hostEncPubJwk', 'relayUrl', 'serverId']);
+    } finally {
+      restoreGlobals();
+    }
+  });
+
+  test('relay entries with malformed transport config are dropped, direct entries survive', async () => {
+    try {
+      installTestWindow();
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify([
+        { id: 'bad', label: 'Broken', url: 'openchamber://connect', lastUsedAt: 20, mode: 'relay', relay: { relayUrl: 'wss://relay.example' } },
+        { id: 'ok', label: 'Home', url: 'http://192.168.1.10:2606', lastUsedAt: 10 },
+      ]));
+
+      const connections = await loadMobileConnections();
+      expect(connections).toHaveLength(1);
+      expect(connections[0]?.id).toBe('ok');
+      expect(connections[0]?.mode).toBe('direct');
+    } finally {
+      restoreGlobals();
+    }
+  });
+
+  test('relay and direct connections dedupe independently', async () => {
+    try {
+      installTestWindow();
+      await upsertMobileConnection({ label: 'Direct', url: 'http://host.example' });
+      await upsertMobileConnection({ label: 'Relay', url: 'openchamber://connect?v=1&mode=relay', relay: testRelay });
+      await upsertMobileConnection({ label: 'Relay renamed', url: 'openchamber://connect?v=1&mode=relay', relay: testRelay });
+
+      const connections = await loadMobileConnections();
+      expect(connections).toHaveLength(2);
+      expect(connections.filter((connection) => connection.mode === 'relay')).toHaveLength(1);
+      expect(connections.find((connection) => connection.mode === 'relay')?.label).toBe('Relay renamed');
+    } finally {
+      restoreGlobals();
+    }
+  });
+});
+
 describe('validateMobileConnectionSession', () => {
   test('accepts a reachable authenticated runtime', async () => {
     const fetchMock = mock(async (input: RequestInfo | URL) => {