@openchamber/web 1.14.0 → 1.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/cli.test.js +8 -0
- package/bin/lib/DOCUMENTATION.md +3 -0
- package/bin/lib/cli-args.js +10 -0
- package/bin/lib/commands-connect-url.js +169 -22
- package/dist/assets/{DiagramView-CIaZCGUT.js → DiagramView-HR2xZxJ8.js} +1 -1
- package/dist/assets/MarkdownRendererImpl-sm01Q7R7.js +11 -0
- package/dist/assets/{MultiRunWindow-Bsbr3i8y.js → MultiRunWindow-DlFUaNQK.js} +1 -1
- package/dist/assets/OnboardingScreen-DVRz82mJ.js +1 -0
- package/dist/assets/{SessionSwitcherDropdown-CLm6tF5n.js → SessionSwitcherDropdown-DvoOalMY.js} +1 -1
- package/dist/assets/SettingsWindow-CkInZcj7.js +1 -0
- package/dist/assets/{TerminalView-DF7-jlam.js → TerminalView-D_9BAjtv.js} +3 -3
- package/dist/assets/es-cjUissX4.js +15 -0
- package/dist/assets/fr-DqbXnTdK.js +13 -0
- package/dist/assets/index-Dg0nmvQU.css +1 -0
- package/dist/assets/index-ltrmNGAf.js +2 -0
- package/dist/assets/ja-Cetyq6Eg.js +15 -0
- package/dist/assets/ko-DtunWisP.js +15 -0
- package/dist/assets/main-BC0m8s1v.js +236 -0
- package/dist/assets/main-DzNa8r0N.js +2 -0
- package/dist/assets/miniChat-BRYDE-Se.js +2 -0
- package/dist/assets/mobile-C3QJVA97.js +2 -0
- package/dist/assets/pl-DctGLgve.js +15 -0
- package/dist/assets/pt-BR-CXPhf78S.js +15 -0
- package/dist/assets/renderElectronMiniChatApp-CVFbDC5A.js +2 -0
- package/dist/assets/renderMobileApp-wkBjh5WR.js +16 -0
- package/dist/assets/runtimeEndpointReset-C42u8PvG.js +167 -0
- package/dist/assets/uk-Bdrc-kqF.js +15 -0
- package/dist/assets/{useAppFontEffects-DTO332li.js → useAppFontEffects-DzBg8hrC.js} +132 -116
- package/dist/assets/{vendor-.bun-C6iL44L9.js → vendor-.bun-BE757pvp.js} +1 -1
- package/dist/assets/zh-CN-CeCVKrHP.js +15 -0
- package/dist/assets/zh-TW-CoqiQING.js +15 -0
- package/dist/index.html +4 -4
- package/dist/mini-chat.html +4 -4
- package/dist/mobile.html +4 -4
- package/package.json +2 -2
- package/server/index.js +157 -6
- package/server/lib/client-auth/pairing.js +308 -0
- package/server/lib/client-auth/pairing.test.js +142 -0
- package/server/lib/client-auth/remote-clients.js +65 -3
- package/server/lib/notifications/apns-runtime.js +9 -16
- package/server/lib/opencode/bootstrap-runtime.js +10 -0
- package/server/lib/opencode/core-routes.js +247 -6
- package/server/lib/opencode/core-routes.test.js +248 -9
- package/server/lib/opencode/feature-routes-runtime.js +10 -0
- package/server/lib/opencode/models-metadata.js +61 -0
- package/server/lib/opencode/network-runtime.js +14 -1
- package/server/lib/opencode/network-runtime.test.js +29 -9
- package/server/lib/opencode/openchamber-routes.js +7 -40
- package/server/lib/opencode/proxy.js +47 -6
- package/server/lib/opencode/settings-helpers.js +16 -0
- package/server/lib/opencode/settings-helpers.test.js +11 -0
- package/server/lib/opencode/settings-normalization-runtime.js +2 -0
- package/server/lib/opencode/shutdown-runtime.js +2 -0
- package/server/lib/package-manager.js +18 -5
- package/server/lib/relay/DOCUMENTATION.md +78 -0
- package/server/lib/relay/cross-compat.test.js +135 -0
- package/server/lib/relay/e2ee.js +341 -0
- package/server/lib/relay/e2ee.test.js +124 -0
- package/server/lib/relay/host-client.js +389 -0
- package/server/lib/relay/host-client.test.js +280 -0
- package/server/lib/relay/identity.js +73 -0
- package/server/lib/relay/identity.test.js +78 -0
- package/server/lib/relay/service.js +247 -0
- package/server/lib/relay/signing-key.js +50 -0
- package/server/lib/relay/tunnel-codec.js +373 -0
- package/server/lib/relay/tunnel-codec.test.js +58 -0
- package/server/lib/relay/tunnel-host.js +462 -0
- package/server/lib/session-assist/DOCUMENTATION.md +66 -0
- package/server/lib/session-assist/runtime.js +394 -0
- package/server/lib/small-model/DOCUMENTATION.md +78 -0
- package/server/lib/small-model/call.js +380 -0
- package/server/lib/small-model/catalog.js +13 -0
- package/server/lib/small-model/index.js +167 -0
- package/server/lib/small-model/resolve.js +131 -0
- package/server/lib/small-model/resolve.test.js +197 -0
- package/server/lib/small-model/routes.js +44 -0
- package/server/lib/ui-auth/DOCUMENTATION.md +6 -0
- package/server/lib/ui-auth/ui-auth.js +10 -0
- package/server/opencode-proxy.test.js +38 -0
- package/dist/assets/MarkdownRendererImpl-DWgOeIpO.js +0 -7
- package/dist/assets/OnboardingScreen-3IAKkM5k.js +0 -1
- package/dist/assets/SettingsWindow-K-ErjehP.js +0 -1
- package/dist/assets/es-DQIFCjC2.js +0 -15
- package/dist/assets/fr-CJRav0LS.js +0 -13
- package/dist/assets/index-5eUDDB6w.js +0 -2
- package/dist/assets/index-CgpE7F8T.css +0 -1
- package/dist/assets/ja-CjAaqvHO.js +0 -15
- package/dist/assets/ko-BEbFxvrd.js +0 -15
- package/dist/assets/main-C2put7uQ.js +0 -2
- package/dist/assets/main-DuQEoz31.js +0 -214
- package/dist/assets/miniChat-o3AAQ-8r.js +0 -2
- package/dist/assets/mobile-X0421aWz.js +0 -2
- package/dist/assets/pl-D4kzai5T.js +0 -15
- package/dist/assets/pt-BR-9Sk3esQZ.js +0 -15
- package/dist/assets/renderElectronMiniChatApp-CdDj0ms1.js +0 -2
- package/dist/assets/renderMobileApp-cZ_HZKSe.js +0 -16
- package/dist/assets/runtimeEndpointReset-BYLVW9e7.js +0 -167
- package/dist/assets/uk-DW_dTfoO.js +0 -15
- package/dist/assets/zh-CN-r2_euV7U.js +0 -15
- package/dist/assets/zh-TW-BdPx3NWh.js +0 -15
|
@@ -100,6 +100,17 @@ describe('settings helpers', () => {
|
|
|
100
100
|
});
|
|
101
101
|
});
|
|
102
102
|
|
|
103
|
+
it('accepts desktopMinimizeToTrayEnabled as a persisted shared setting', () => {
|
|
104
|
+
const helpers = createTestHelpers();
|
|
105
|
+
|
|
106
|
+
expect(helpers.sanitizeSettingsUpdate({ desktopMinimizeToTrayEnabled: true })).toEqual({
|
|
107
|
+
desktopMinimizeToTrayEnabled: true,
|
|
108
|
+
});
|
|
109
|
+
expect(helpers.sanitizeSettingsUpdate({ desktopMinimizeToTrayEnabled: false })).toEqual({
|
|
110
|
+
desktopMinimizeToTrayEnabled: false,
|
|
111
|
+
});
|
|
112
|
+
});
|
|
113
|
+
|
|
103
114
|
it('accepts desktopUiPassword as a persisted shared setting', () => {
|
|
104
115
|
const helpers = createTestHelpers();
|
|
105
116
|
|
|
@@ -139,6 +139,7 @@ export const createSettingsNormalizationRuntime = (dependencies) => {
|
|
|
139
139
|
: null;
|
|
140
140
|
const iconBackground = normalizeIconBackground(candidate.iconBackground);
|
|
141
141
|
const color = typeof candidate.color === 'string' ? candidate.color.trim() : '';
|
|
142
|
+
const defaultModel = typeof candidate.defaultModel === 'string' ? candidate.defaultModel.trim() : '';
|
|
142
143
|
const addedAt = Number.isFinite(candidate.addedAt) ? Number(candidate.addedAt) : null;
|
|
143
144
|
const lastOpenedAt = Number.isFinite(candidate.lastOpenedAt)
|
|
144
145
|
? Number(candidate.lastOpenedAt)
|
|
@@ -158,6 +159,7 @@ export const createSettingsNormalizationRuntime = (dependencies) => {
|
|
|
158
159
|
...(icon ? { icon } : {}),
|
|
159
160
|
...(iconBackground ? { iconBackground } : {}),
|
|
160
161
|
...(color ? { color } : {}),
|
|
162
|
+
...(defaultModel && defaultModel.includes('/') ? { defaultModel } : {}),
|
|
161
163
|
...(Number.isFinite(addedAt) && addedAt >= 0 ? { addedAt } : {}),
|
|
162
164
|
...(Number.isFinite(lastOpenedAt) && lastOpenedAt >= 0 ? { lastOpenedAt } : {}),
|
|
163
165
|
};
|
|
@@ -8,6 +8,7 @@ export const createGracefulShutdownRuntime = (dependencies) => {
|
|
|
8
8
|
syncToHmrState,
|
|
9
9
|
openCodeWatcherRuntime,
|
|
10
10
|
sessionRuntime,
|
|
11
|
+
sessionAssistRuntime,
|
|
11
12
|
scheduledTasksRuntime,
|
|
12
13
|
getHealthCheckInterval,
|
|
13
14
|
clearHealthCheckInterval,
|
|
@@ -41,6 +42,7 @@ export const createGracefulShutdownRuntime = (dependencies) => {
|
|
|
41
42
|
|
|
42
43
|
openCodeWatcherRuntime.stop();
|
|
43
44
|
sessionRuntime.dispose();
|
|
45
|
+
sessionAssistRuntime?.stop?.();
|
|
44
46
|
scheduledTasksRuntime?.stop?.();
|
|
45
47
|
|
|
46
48
|
const healthCheckInterval = getHealthCheckInterval();
|
|
@@ -12,6 +12,7 @@ const PACKAGE_NAME = '@openchamber/web';
|
|
|
12
12
|
const PACKAGE_PATH_SEGMENTS = PACKAGE_NAME.split('/');
|
|
13
13
|
const NPM_REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}`;
|
|
14
14
|
const CHANGELOG_URL = 'https://raw.githubusercontent.com/btriapitsyn/openchamber/main/CHANGELOG.md';
|
|
15
|
+
const GITHUB_RELEASES_URL = 'https://github.com/openchamber/openchamber/releases';
|
|
15
16
|
let cachedDetectedPm = null;
|
|
16
17
|
|
|
17
18
|
function getSpawnSyncBaseOptions() {
|
|
@@ -29,7 +30,7 @@ function getOpenChamberConfigDir() {
|
|
|
29
30
|
}
|
|
30
31
|
|
|
31
32
|
function sanitizeInstallScope(scope) {
|
|
32
|
-
if (scope === 'desktop-electron' || scope === 'vscode' || scope === 'web') return scope;
|
|
33
|
+
if (scope === 'desktop-electron' || scope === 'vscode' || scope === 'web' || scope === 'mobile-capacitor') return scope;
|
|
33
34
|
return 'web';
|
|
34
35
|
}
|
|
35
36
|
|
|
@@ -65,7 +66,7 @@ function mapArch(value) {
|
|
|
65
66
|
}
|
|
66
67
|
|
|
67
68
|
function normalizeAppType(value) {
|
|
68
|
-
if (value === 'web' || value === 'desktop-electron' || value === 'vscode') return value;
|
|
69
|
+
if (value === 'web' || value === 'desktop-electron' || value === 'vscode' || value === 'mobile-capacitor') return value;
|
|
69
70
|
return 'web';
|
|
70
71
|
}
|
|
71
72
|
|
|
@@ -75,7 +76,7 @@ function normalizeDeviceClass(value) {
|
|
|
75
76
|
}
|
|
76
77
|
|
|
77
78
|
function normalizePlatform(value) {
|
|
78
|
-
if (value === 'macos' || value === 'windows' || value === 'linux' || value === 'web') return value;
|
|
79
|
+
if (value === 'macos' || value === 'windows' || value === 'linux' || value === 'web' || value === 'android' || value === 'ios') return value;
|
|
79
80
|
return mapPlatform(process.platform);
|
|
80
81
|
}
|
|
81
82
|
|
|
@@ -89,8 +90,9 @@ async function checkForUpdatesFromApi(currentVersion, options = {}) {
|
|
|
89
90
|
const appType = normalizeAppType(options.appType);
|
|
90
91
|
const hostPlatform = mapPlatform(process.platform);
|
|
91
92
|
const hostArch = mapArch(process.arch);
|
|
92
|
-
const
|
|
93
|
-
const
|
|
93
|
+
const shouldTrustClientPlatform = appType === 'vscode' || appType === 'mobile-capacitor';
|
|
94
|
+
const platform = shouldTrustClientPlatform ? normalizePlatform(options.platform) : hostPlatform;
|
|
95
|
+
const arch = shouldTrustClientPlatform ? normalizeArch(options.arch) : hostArch;
|
|
94
96
|
const payload = {
|
|
95
97
|
appType,
|
|
96
98
|
deviceClass: normalizeDeviceClass(options.deviceClass),
|
|
@@ -120,11 +122,19 @@ async function checkForUpdatesFromApi(currentVersion, options = {}) {
|
|
|
120
122
|
const versionComparison = compareVersions(data.latestVersion, currentVersion);
|
|
121
123
|
if (versionComparison < 0) return null;
|
|
122
124
|
|
|
125
|
+
const releaseUrl = `${GITHUB_RELEASES_URL}/tag/v${data.latestVersion}`;
|
|
126
|
+
const downloadUrl = typeof data.downloadUrl === 'string'
|
|
127
|
+
? data.downloadUrl
|
|
128
|
+
: typeof data.download?.url === 'string'
|
|
129
|
+
? data.download.url
|
|
130
|
+
: undefined;
|
|
123
131
|
return {
|
|
124
132
|
available: Boolean(data.updateAvailable) && versionComparison > 0,
|
|
125
133
|
version: data.latestVersion,
|
|
126
134
|
currentVersion,
|
|
127
135
|
body: typeof data.releaseNotes === 'string' ? data.releaseNotes : undefined,
|
|
136
|
+
releaseUrl: typeof data.releaseNotesUrl === 'string' ? data.releaseNotesUrl : releaseUrl,
|
|
137
|
+
downloadUrl: appType === 'mobile-capacitor' ? (downloadUrl || releaseUrl) : undefined,
|
|
128
138
|
nextSuggestedCheckInSec:
|
|
129
139
|
typeof data.nextSuggestedCheckInSec === 'number' && Number.isFinite(data.nextSuggestedCheckInSec)
|
|
130
140
|
? data.nextSuggestedCheckInSec
|
|
@@ -721,6 +731,7 @@ export async function checkForUpdates(options = {}) {
|
|
|
721
731
|
const currentVersion = options.currentVersion || getCurrentVersion();
|
|
722
732
|
const pm = detectPackageManager();
|
|
723
733
|
const appType = normalizeAppType(options.appType);
|
|
734
|
+
const platform = normalizePlatform(options.platform);
|
|
724
735
|
|
|
725
736
|
if (currentVersion !== 'unknown') {
|
|
726
737
|
const remote = await checkForUpdatesFromApi(currentVersion, options);
|
|
@@ -760,6 +771,8 @@ export async function checkForUpdates(options = {}) {
|
|
|
760
771
|
version: latestVersion,
|
|
761
772
|
currentVersion,
|
|
762
773
|
body: changelog,
|
|
774
|
+
releaseUrl: `${GITHUB_RELEASES_URL}/tag/v${latestVersion}`,
|
|
775
|
+
downloadUrl: appType === 'mobile-capacitor' && platform === 'android' ? `${GITHUB_RELEASES_URL}/tag/v${latestVersion}` : undefined,
|
|
763
776
|
packageManager: pm,
|
|
764
777
|
// Show our CLI command, not raw package manager command
|
|
765
778
|
updateCommand: 'openchamber update',
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Relay Module Documentation
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
The private relay lets an OpenChamber client (mobile app, browser, or another desktop) reach a user's OpenChamber instance through OpenChamber-hosted infrastructure when the instance is not directly reachable (behind NAT, no public URL, no tunnel). The instance dials **outbound** to the relay; nothing needs to be exposed inbound.
|
|
6
|
+
|
|
7
|
+
Traffic is **end-to-end encrypted between the two endpoints** (client and host instance). The relay infrastructure forwards opaque ciphertext and cannot read application traffic — it is an untrusted transport, not a trusted middlebox.
|
|
8
|
+
|
|
9
|
+
This module (`packages/web/server/lib/relay/`) is the **host side**: it runs inside the OpenChamber web server (so it works for Electron desktop, headless server, and CLI installs alike). The **client side** lives in `packages/ui/src/lib/relay/`. The **relay service itself** is a separate Cloudflare Worker in the `openchamber-website` repo and only brokers connections.
|
|
10
|
+
|
|
11
|
+
## The three layers
|
|
12
|
+
|
|
13
|
+
Traffic is modeled as three stacked layers. The relay understands only Layer 1; Layers 2–3 exist solely between the client and the host.
|
|
14
|
+
|
|
15
|
+
1. **Relay routing (Layer 1)** — outbound WebSocket connections to the relay, connection brokering, and host authentication to the relay. The relay routes each client to the correct host and forwards frames verbatim.
|
|
16
|
+
2. **End-to-end encryption (Layer 2)** — an authenticated encrypted channel established directly between client and host, keyed so the relay cannot participate. Built on standard WebCrypto primitives (ECDH key agreement + AEAD framing). The host's encryption public key is distributed to the client out-of-band via the pairing payload and is the client's trust anchor.
|
|
17
|
+
3. **Tunnel multiplexing (Layer 3)** — because an OpenChamber client speaks many concurrent HTTP requests, an event stream (SSE), and WebSockets to one origin, the encrypted channel carries a small multiplexing protocol. It frames HTTP request/response (including streamed bodies) and WebSocket sub-streams so the whole app works over one encrypted connection.
|
|
18
|
+
|
|
19
|
+
## Entrypoints and structure
|
|
20
|
+
|
|
21
|
+
Host side (`packages/web/server/lib/relay/`):
|
|
22
|
+
- `service.js` — thin entrypoint: relay config (enabled flag + relay URL), the management routes (`GET/POST /api/openchamber/relay/{status,enable,disable}`), a `getPairingCandidate()` accessor (the relay transport candidate folded into pairing-v2 links when enabled, consumed by the pairing-session route in `core-routes.js`), and lifecycle wiring. Started from `packages/web/server/index.js` only when the user has explicitly enabled the relay. The relay endpoint defaults to the OpenChamber-hosted relay but can be pinned to a self-hosted relay via the `OPENCHAMBER_RELAY_URL` env var (must be `ws://`/`wss://`); when set it overrides the stored setting for the host connection, the pairing candidate, and status, so paired clients inherit the endpoint automatically.
|
|
23
|
+
- `identity.js` — the host's stable identity: the long-lived signing keypair (shared with the push relay, defines the routing id) plus a long-lived encryption keypair (the E2EE trust anchor). Reused across restarts; never rotated implicitly.
|
|
24
|
+
- `signing-key.js` — storage/derivation of the signing keypair and the routing id, shared with the notifications runtime.
|
|
25
|
+
- `host-client.js` — the long-lived connection manager: one outbound control connection to the relay, a per-client data connection for each connected device, reconnect/backoff, and the E2EE responder handshake per connection.
|
|
26
|
+
- `tunnel-host.js` — the per-connection dispatcher: decrypts tunnel frames and forwards HTTP/SSE/WS to the local server over loopback, then streams responses back. Enforces a path allowlist and never injects credentials.
|
|
27
|
+
- `e2ee.js`, `tunnel-codec.js` — host-side (JS) mirrors of the shared crypto and framing (see "Two implementations" below).
|
|
28
|
+
|
|
29
|
+
Client side (`packages/ui/src/lib/relay/`):
|
|
30
|
+
- `protocol.ts` — the shared contract: constants, frame types, message shapes. The normative source both implementations follow.
|
|
31
|
+
- `crypto.ts`, `handshake.ts` — the E2EE primitives and handshake state machines (initiator + responder).
|
|
32
|
+
- `tunnel-codec.ts` — Layer 3 frame codec, fragmentation, and outbound frame batching.
|
|
33
|
+
- `tunnel-client.ts` — the client tunnel: exposes a `fetch()`-compatible and a WebSocket-compatible surface backed by the encrypted tunnel.
|
|
34
|
+
- `tunnel-payloads.ts`, `runtime-tunnel.ts`, `runtime-socket.ts` — payload helpers, the active-tunnel singleton, and the shared "open a runtime WebSocket the right way" helper.
|
|
35
|
+
|
|
36
|
+
Relay is not a separate link format: it is one transport candidate inside the unified **pairing v2** payload (`packages/ui/src/lib/connectionPayload.ts`). A relay candidate is `{ type: 'relay', relayUrl, serverId, hostEncPubJwk }` — no embedded token; the client redeems the one-time pairing secret over the tunnel like any other candidate.
|
|
37
|
+
|
|
38
|
+
## What travels the tunnel
|
|
39
|
+
|
|
40
|
+
Everything a client normally sends to the single OpenChamber origin:
|
|
41
|
+
- **HTTP** — REST endpoints and proxied OpenCode SDK calls under `/api/*`, plus `/auth/*` and `/health`.
|
|
42
|
+
- **SSE** — long-lived streamed responses (the event stream, notifications, terminal output fallback). These are just HTTP responses whose body streams; the tunnel needs no special SSE handling.
|
|
43
|
+
- **WebSocket** — the endpoints that use a real socket (the global event stream on platforms that support WS, terminal I/O, dictation).
|
|
44
|
+
|
|
45
|
+
The host dispatcher restricts tunneled traffic to explicit path allowlists (one for HTTP, one for WS).
|
|
46
|
+
|
|
47
|
+
## Authentication model
|
|
48
|
+
|
|
49
|
+
- The tunnel is **transport only**. The OpenChamber server still authenticates every tunneled request exactly as it authenticates a direct remote client. The relay path grants reachability, not authorization.
|
|
50
|
+
- Clients carry their normal credential. HTTP and SSE requests authenticate with the client's bearer token (a header). **WebSocket upgrades cannot send headers**, so they authenticate with a short-lived URL-scoped token minted beforehand and passed as a query parameter. This asymmetry is important when adding new WebSocket features (see the skill).
|
|
51
|
+
- The host authenticates itself to the relay with a signed handshake using its long-lived signing key.
|
|
52
|
+
- Enabling the relay is explicit opt-in and disabled by default; disabling it severs all relay reachability immediately.
|
|
53
|
+
|
|
54
|
+
## End-to-end flow (overview)
|
|
55
|
+
|
|
56
|
+
1. **Pairing.** The host issues a pairing-v2 link (QR / deep link) carrying a one-time secret and a list of transport candidates. When the relay is enabled, one candidate is the relay transport (its endpoint, routing id, and encryption public key — the E2EE trust anchor). The client redeems the secret over the first reachable candidate; over the relay candidate it opens the E2EE tunnel first, then redeems through it, and stores the connection.
|
|
57
|
+
2. **Presence.** When the relay is enabled, the host opens one outbound control connection and waits.
|
|
58
|
+
3. **Connect.** The client connects for a given routing id; the relay notifies the host over the control connection; the host opens a matching per-client data connection.
|
|
59
|
+
4. **Handshake.** Over that connection pair, client and host run the E2EE handshake and derive a shared encrypted channel the relay cannot read.
|
|
60
|
+
5. **Traffic.** All normal app traffic is multiplexed and encrypted through that channel. On the host, decrypted requests are dispatched to the local server over loopback; responses stream back encrypted. Reconnects re-establish a fresh channel and the app's existing retry machinery recovers.
|
|
61
|
+
|
|
62
|
+
## Two implementations, kept in sync
|
|
63
|
+
|
|
64
|
+
The E2EE and framing logic exists twice: TypeScript in `packages/ui/src/lib/relay/` (shared by the client and the normative reference) and a JavaScript mirror in this module (the host, which is plain JS ESM). They **must stay byte-compatible** — a client encrypted by one must decrypt on the other. A cross-compatibility test (`cross-compat.test.js`) imports the TS modules directly and exercises a full TS-client ↔ JS-host exchange. Any change to the wire format, frame codec, handshake, or batching must update both sides and keep that test green.
|
|
65
|
+
|
|
66
|
+
## Runtime integration (client)
|
|
67
|
+
|
|
68
|
+
Relay mode plugs into the existing client transport layer rather than a parallel path: `runtime-switch` activates the tunnel singleton, `runtime-fetch` routes runtime requests through it, `runtime-url`/`runtime-socket` yield tunnel-backed URLs and sockets, and `runtime-auth` mints the URL-scoped token through the tunnel. Direct-URL connections and the Electron realtime-proxy path are unaffected.
|
|
69
|
+
|
|
70
|
+
## Design invariants (do not regress)
|
|
71
|
+
|
|
72
|
+
- The relay never sees plaintext application traffic; it sees only routing metadata (routing id, connection identifiers, timestamps, coarse counts).
|
|
73
|
+
- Pairing secrets travel in URL fragments only, never in query strings, never logged.
|
|
74
|
+
- The host dispatcher never injects credentials; the server authenticates each tunneled request.
|
|
75
|
+
- The tunnel is transparent to the app: adding relay support to a feature should not require the feature to know the relay exists — it goes through the shared runtime transport helpers.
|
|
76
|
+
- The two implementations stay byte-compatible and the wire format is versioned/negotiated so mixed client/host app versions degrade gracefully rather than break.
|
|
77
|
+
|
|
78
|
+
For the operational rules that keep future changes (new WebSocket endpoints, transport refactors, terminal/voice porting) from breaking this, load the `relay-transport` skill.
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
// Cross-compatibility: the JS host e2ee must interoperate with the normative TS
|
|
2
|
+
// modules in packages/ui/src/lib/relay. bun runs TS directly, so import the TS
|
|
3
|
+
// client handshake and drive a full TS-client <-> JS-host exchange both ways.
|
|
4
|
+
|
|
5
|
+
import { describe, expect, it } from 'bun:test';
|
|
6
|
+
|
|
7
|
+
import { createHostHandshake, exportPublicKeyJwk, generateEcdhKeyPair } from './e2ee.js';
|
|
8
|
+
import { createClientHandshake } from '../../../../ui/src/lib/relay/handshake.ts';
|
|
9
|
+
import {
|
|
10
|
+
TunnelFrameType as JsFrameType,
|
|
11
|
+
decodeFrameBatch as jsDecodeBatch,
|
|
12
|
+
decodeTunnelFrame as jsDecode,
|
|
13
|
+
encodeFrameBatch as jsEncodeBatch,
|
|
14
|
+
encodeTunnelFrame as jsEncode,
|
|
15
|
+
} from './tunnel-codec.js';
|
|
16
|
+
import {
|
|
17
|
+
decodeFrameBatch as tsDecodeBatch,
|
|
18
|
+
decodeTunnelFrame as tsDecode,
|
|
19
|
+
encodeFrameBatch as tsEncodeBatch,
|
|
20
|
+
encodeTunnelFrame as tsEncode,
|
|
21
|
+
} from '../../../../ui/src/lib/relay/tunnel-codec.ts';
|
|
22
|
+
import { TunnelFrameType as TsFrameType } from '../../../../ui/src/lib/relay/protocol.ts';
|
|
23
|
+
|
|
24
|
+
describe('relay JS-host <-> TS-client cross compatibility', () => {
|
|
25
|
+
it('completes a handshake and exchanges frames both ways', async () => {
|
|
26
|
+
const hostKeys = await generateEcdhKeyPair();
|
|
27
|
+
const hostPubJwk = await exportPublicKeyJwk(hostKeys.publicKey);
|
|
28
|
+
|
|
29
|
+
const jsHost = createHostHandshake(hostKeys.privateKey);
|
|
30
|
+
const tsClient = await createClientHandshake(hostPubJwk);
|
|
31
|
+
|
|
32
|
+
// TS client hello -> JS host establishes and replies ready.
|
|
33
|
+
const hostAction = await jsHost.handleText(tsClient.helloText);
|
|
34
|
+
expect(hostAction.type).toBe('established');
|
|
35
|
+
const hostChannel = hostAction.channel;
|
|
36
|
+
|
|
37
|
+
// JS host ready -> TS client establishes.
|
|
38
|
+
const clientAction = await tsClient.handleText(hostAction.replyText);
|
|
39
|
+
expect(clientAction.type).toBe('established');
|
|
40
|
+
const clientChannel = clientAction.channel;
|
|
41
|
+
|
|
42
|
+
// TS client -> JS host.
|
|
43
|
+
const up = new TextEncoder().encode('ts client speaking');
|
|
44
|
+
const upPlain = await hostChannel.decryptor.decrypt(await clientChannel.encryptor.encrypt(up));
|
|
45
|
+
expect(new TextDecoder().decode(upPlain)).toBe('ts client speaking');
|
|
46
|
+
|
|
47
|
+
// JS host -> TS client.
|
|
48
|
+
const down = new TextEncoder().encode('js host replying');
|
|
49
|
+
const downPlain = await clientChannel.decryptor.decrypt(await hostChannel.encryptor.encrypt(down));
|
|
50
|
+
expect(new TextDecoder().decode(downPlain)).toBe('js host replying');
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
it('tunnel frames are byte-compatible across TS and JS codecs', () => {
|
|
54
|
+
const payload = new TextEncoder().encode('{"method":"GET"}');
|
|
55
|
+
const tsFrame = tsEncode(TsFrameType.HttpRequest, 5, payload);
|
|
56
|
+
const jsFrame = jsEncode(JsFrameType.HttpRequest, 5, payload);
|
|
57
|
+
expect(Array.from(jsFrame)).toEqual(Array.from(tsFrame));
|
|
58
|
+
|
|
59
|
+
const decodedByJs = jsDecode(tsFrame);
|
|
60
|
+
const decodedByTs = tsDecode(jsFrame);
|
|
61
|
+
expect(decodedByJs.streamId).toBe(5);
|
|
62
|
+
expect(decodedByTs.streamId).toBe(5);
|
|
63
|
+
expect(decodedByJs.frameType).toBe(TsFrameType.HttpRequest);
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
it('negotiates batching between a TS client and a JS host, then exchanges a batch', async () => {
|
|
67
|
+
const hostKeys = await generateEcdhKeyPair();
|
|
68
|
+
const hostPubJwk = await exportPublicKeyJwk(hostKeys.publicKey);
|
|
69
|
+
|
|
70
|
+
const jsHost = createHostHandshake(hostKeys.privateKey);
|
|
71
|
+
const tsClient = await createClientHandshake(hostPubJwk);
|
|
72
|
+
|
|
73
|
+
const hostAction = await jsHost.handleText(tsClient.helloText);
|
|
74
|
+
expect(hostAction.type).toBe('established');
|
|
75
|
+
expect(hostAction.batch).toBe(true);
|
|
76
|
+
const clientAction = await tsClient.handleText(hostAction.replyText);
|
|
77
|
+
expect(clientAction.type).toBe('established');
|
|
78
|
+
expect(clientAction.batch).toBe(true);
|
|
79
|
+
|
|
80
|
+
// TS client encodes a multi-frame batch -> JS host decodes it byte-identically.
|
|
81
|
+
const frames = [
|
|
82
|
+
tsEncode(TsFrameType.HttpBody, 1, new TextEncoder().encode('alpha')),
|
|
83
|
+
tsEncode(TsFrameType.HttpBody, 1, new TextEncoder().encode('beta')),
|
|
84
|
+
tsEncode(TsFrameType.HttpBody, 1, new TextEncoder().encode('gamma')),
|
|
85
|
+
];
|
|
86
|
+
const overWire = await hostAction.channel.decryptor.decrypt(
|
|
87
|
+
await clientAction.channel.encryptor.encrypt(tsEncodeBatch(frames)),
|
|
88
|
+
);
|
|
89
|
+
const jsFrames = jsDecodeBatch(overWire);
|
|
90
|
+
expect(jsFrames.length).toBe(3);
|
|
91
|
+
jsFrames.forEach((frame, index) => expect(Array.from(frame)).toEqual(Array.from(frames[index])));
|
|
92
|
+
|
|
93
|
+
// JS host encodes a batch -> TS client decodes it.
|
|
94
|
+
const downFrames = [
|
|
95
|
+
jsEncode(JsFrameType.HttpBody, 1, new TextEncoder().encode('down-1')),
|
|
96
|
+
jsEncode(JsFrameType.HttpBody, 1, new TextEncoder().encode('down-2')),
|
|
97
|
+
];
|
|
98
|
+
const downWire = await clientAction.channel.decryptor.decrypt(
|
|
99
|
+
await hostAction.channel.encryptor.encrypt(jsEncodeBatch(downFrames)),
|
|
100
|
+
);
|
|
101
|
+
const tsFrames = tsDecodeBatch(downWire);
|
|
102
|
+
expect(tsFrames.length).toBe(2);
|
|
103
|
+
tsFrames.forEach((frame, index) => expect(Array.from(frame)).toEqual(Array.from(downFrames[index])));
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
it('falls back to legacy (no batch) when either peer does not advertise batching', async () => {
|
|
107
|
+
const hostKeys = await generateEcdhKeyPair();
|
|
108
|
+
const hostPubJwk = await exportPublicKeyJwk(hostKeys.publicKey);
|
|
109
|
+
|
|
110
|
+
// Legacy JS host (batch:false) vs batch-capable TS client -> batching off.
|
|
111
|
+
const legacyHost = createHostHandshake(hostKeys.privateKey, { batch: false });
|
|
112
|
+
const tsClient = await createClientHandshake(hostPubJwk);
|
|
113
|
+
const hostAction = await legacyHost.handleText(tsClient.helloText);
|
|
114
|
+
expect(hostAction.type).toBe('established');
|
|
115
|
+
expect(hostAction.batch).toBe(false);
|
|
116
|
+
const clientAction = await tsClient.handleText(hostAction.replyText);
|
|
117
|
+
expect(clientAction.type).toBe('established');
|
|
118
|
+
expect(clientAction.batch).toBe(false);
|
|
119
|
+
|
|
120
|
+
// Legacy wire: plaintext is a single raw tunnel frame (no container tag).
|
|
121
|
+
const frame = tsEncode(TsFrameType.HttpBody, 1, new TextEncoder().encode('legacy'));
|
|
122
|
+
const overWire = await hostAction.channel.decryptor.decrypt(
|
|
123
|
+
await clientAction.channel.encryptor.encrypt(frame),
|
|
124
|
+
);
|
|
125
|
+
expect(jsDecode(overWire).frameType).toBe(JsFrameType.HttpBody);
|
|
126
|
+
|
|
127
|
+
// Batch-capable JS host vs legacy TS client (batch:false) -> also off.
|
|
128
|
+
const host2 = createHostHandshake(hostKeys.privateKey);
|
|
129
|
+
const legacyClient = await createClientHandshake(hostPubJwk, { batch: false });
|
|
130
|
+
const host2Action = await host2.handleText(legacyClient.helloText);
|
|
131
|
+
expect(host2Action.batch).toBe(false);
|
|
132
|
+
const client2Action = await legacyClient.handleText(host2Action.replyText);
|
|
133
|
+
expect(client2Action.batch).toBe(false);
|
|
134
|
+
});
|
|
135
|
+
});
|