@openchambery/web 1.17.1 → 1.18.0

package/server/lib/relay/host-client.js

@@ -54,12 +54,14 @@ const resolveBatchWindowMs = (option) => {
  *   identity: { serverId: string, hostEncPrivateKey: CryptoKey, signRelayAuth: (role: string, connectionId?: string | null) => { ts: number, sig: string, pk: string } },
  *   localPort?: number,
  *   getLocalPort?: () => number,
+ *   getSshRoutingTable?: () => { id: string, localPort: number }[],
  *   onStatus?: (status: { state: string, lastError: string | null, connectedClients: number }) => void,
  *   logger?: Pick<Console, 'warn'>,
  * }} options
  */
-export const startRelayHost = ({ relayUrl, identity, localPort, getLocalPort, onStatus, logger = console, batchWindowMs, batch }) => {
+export const startRelayHost = ({ relayUrl, identity, localPort, getLocalPort, getSshRoutingTable = () => [], onStatus, logger = console, batchWindowMs, batch }) => {
   const resolveLocalPort = typeof getLocalPort === 'function' ? getLocalPort : () => localPort;
+  const resolveSshRoutingTable = typeof getSshRoutingTable === 'function' ? getSshRoutingTable : () => [];
   const localBatch = batch !== false;
   const resolvedBatchWindowMs = resolveBatchWindowMs(batchWindowMs);
 
@@ -188,6 +190,7 @@ export const startRelayHost = ({ relayUrl, identity, localPort, getLocalPort, on
           entry.tunnel = createTunnelHost({
             connectionId,
             getLocalPort: resolveLocalPort,
+            getSshRoutingTable: resolveSshRoutingTable,
             getBufferedAmount: () => socket.bufferedAmount,
             sendFrame: (plaintextFrame) => {
               if (dataSockets.get(connectionId) !== entry || socket.readyState !== WebSocket.OPEN) return;

package/server/lib/relay/service.js

@@ -9,8 +9,9 @@
 // Host gate: only the Electron desktop runtime may run a relay host
 // (OPENCHAMBER_RUNTIME=desktop, set before the in-process web server starts).
 // Plain `node server`, `dev:web:hmr`, VS Code, CLI, and browser clients must
-// never open the host-control socket or advertise a host pairing candidate.
-// They may still be relay *clients* when connecting to another host.
+// never open the host-control socket, mint a relay identity, advertise a host
+// pairing candidate, or probe the relay. They may still be relay *clients*
+// when connecting to another host.
 
 import express from 'express';
 
@@ -68,6 +69,7 @@ const envRelayUrlOverride = () => {
  *   readSettingsFromDiskMigrated: () => Promise<object>,
  *   writeSettingsToDisk: (settings: object) => Promise<void>,
  *   getLocalPort: () => number,
+ *   getSshRoutingTable?: () => { id: string, localPort: number }[],
  *   logger?: Pick<Console, 'warn'>,
  *   canHostRelay?: () => boolean,
  * }} deps
@@ -80,6 +82,8 @@ export const createRelayService = ({
   // regeneration — see identity.js/signing-key.js.
   readSettingsStrict,
   getLocalPort,
+  // Live SSH local-forward ports (Electron). Empty outside desktop.
+  getSshRoutingTable = () => [],
   // Returns true when any paired device or pending pairing session uses the
   // relay transport. The relay lifecycle is driven purely by this demand.
   hasRelayDemand = async () => false,
@@ -207,6 +211,7 @@ export const createRelayService = ({
       relayUrl,
       identity,
       getLocalPort,
+      getSshRoutingTable,
       logger,
       onStatus: (next) => {
         status = next;
@@ -265,27 +270,27 @@ export const createRelayService = ({
   // Stable server identity (base64url SHA-256 of the canonical public signing
   // JWK). Derived from a public key, so it is not a secret; clients use it to
   // verify that a learned/probed address belongs to this server before trusting
-  // it. Independent of whether the relay host is currently enabled.
+  // it. Independent of whether the relay host is currently enabled. Off
+  // desktop this is null — minting identity is a desktop-host concern.
   const getServerId = async () => {
+    if (!hostAllowed()) return null;
     const identity = await identityRuntime.getRelayIdentity();
     return identity.serverId;
   };
 
   const getStatus = async () => {
-    const config = await readConfig();
-    const identity = await identityRuntime.getRelayIdentity();
     if (!hostAllowed()) {
       return {
         enabled: false,
         hostAllowed: false,
         state: 'unavailable',
-        serverId: identity.serverId,
+        serverId: null,
         connectedClients: 0,
-        relayUrl: config.relayUrl,
-        relayUrlLocked: config.relayUrlLocked,
         lastError: RELAY_HOST_DESKTOP_ONLY_MESSAGE,
       };
     }
+    const config = await readConfig();
+    const identity = await identityRuntime.getRelayIdentity();
     const live = hostClient ? hostClient.getStatus() : status;
     return {
       enabled: config.enabled,
@@ -404,6 +409,9 @@ export const createRelayService = ({
 
     app.post('/api/openchamber/relay/disable', async (_req, res) => {
       try {
+        if (!hostAllowed()) {
+          return res.status(403).json({ error: RELAY_HOST_DESKTOP_ONLY_MESSAGE });
+        }
         const current = await readConfig();
         await writeConfig({ enabled: false, relayUrl: current.relayUrl });
         stop();

package/server/lib/relay/service.test.js

@@ -5,14 +5,18 @@ import request from 'supertest';
 const relayMocks = vi.hoisted(() => ({
   starts: [],
   stops: [],
+  identityReads: 0,
 }));
 
 vi.mock('./identity.js', () => ({
   createRelayIdentityRuntime: () => ({
-    getRelayIdentity: async () => ({
-      serverId: 'server-test',
-      hostEncPubJwk: { kty: 'EC', crv: 'P-256', x: 'x', y: 'y' },
-    }),
+    getRelayIdentity: async () => {
+      relayMocks.identityReads += 1;
+      return {
+        serverId: 'server-test',
+        hostEncPubJwk: { kty: 'EC', crv: 'P-256', x: 'x', y: 'y' },
+      };
+    },
   }),
 }));
 
@@ -59,6 +63,7 @@ describe('relay service pairing endpoint', () => {
   afterEach(() => {
     relayMocks.starts.length = 0;
     relayMocks.stops.length = 0;
+    relayMocks.identityReads = 0;
     delete process.env.OPENCHAMBER_RELAY_URL;
   });
 
@@ -142,9 +147,10 @@ describe('relay host desktop-only gate', () => {
   afterEach(() => {
     relayMocks.starts.length = 0;
     relayMocks.stops.length = 0;
+    relayMocks.identityReads = 0;
   });
 
-  it('does not start a host, claim, or rewrite settings when reconcile runs off desktop', async () => {
+  it('does not start a host, claim, mint identity, or rewrite settings when reconcile runs off desktop', async () => {
     const write = vi.fn(async (next) => next);
     const { service, settings } = createTestRelayService({
       canHostRelay: false,
@@ -157,12 +163,16 @@ describe('relay host desktop-only gate', () => {
     expect(relayMocks.starts).toEqual([]);
     expect(write).not.toHaveBeenCalled();
     expect(settings.current()).toEqual({});
-    await expect(service.getStatus()).resolves.toMatchObject({
+    await expect(service.getStatus()).resolves.toEqual({
       enabled: false,
       hostAllowed: false,
       state: 'unavailable',
+      serverId: null,
+      connectedClients: 0,
       lastError: RELAY_HOST_DESKTOP_ONLY_MESSAGE,
     });
+    await expect(service.getServerId()).resolves.toBeNull();
+    expect(relayMocks.identityReads).toBe(0);
   });
 
   it('refuses relay pairing and enable off desktop', async () => {
@@ -181,6 +191,11 @@ describe('relay host desktop-only gate', () => {
       .send({})
       .expect(403, { error: RELAY_HOST_DESKTOP_ONLY_MESSAGE });
 
+    await request(app)
+      .post('/api/openchamber/relay/disable')
+      .send({})
+      .expect(403, { error: RELAY_HOST_DESKTOP_ONLY_MESSAGE });
+
     expect(relayMocks.starts).toEqual([]);
     expect(settings.current()).toEqual({});
   });

package/server/lib/relay/tunnel-host.js

@@ -35,9 +35,14 @@ const ALLOWED_WS_PATHS = new Set([
   '/api/dictation/ws',
 ]);
 
+// Client-selected SSH local-forward target (decimal port string). Valid only
+// when present in the injected routing table; never falls back to default port.
+const TARGET_PORT_HEADER = 'x-openchamber-target-port';
+
 // Hop-by-hop headers stripped from tunneled requests; `host` is set by fetch
 // to the loopback origin. content-length is dropped too because the body is
 // re-chunked through the tunnel and undici computes framing itself.
+// Target-port is host-routing metadata and must not reach the loopback origin.
 const STRIPPED_REQUEST_HEADERS = new Set([
   'connection',
   'keep-alive',
@@ -45,6 +50,7 @@ const STRIPPED_REQUEST_HEADERS = new Set([
   'upgrade',
   'host',
   'content-length',
+  TARGET_PORT_HEADER,
 ]);
 
 // Response framing headers that no longer apply once the body crosses the
@@ -75,14 +81,45 @@ const isWsOpenPayload = (parsed) =>
   Boolean(parsed && typeof parsed === 'object'
     && typeof parsed.path === 'string'
     && typeof parsed.query === 'string'
-    && (parsed.protocols === undefined || Array.isArray(parsed.protocols)));
+    && (parsed.protocols === undefined || Array.isArray(parsed.protocols))
+    && (parsed.headers === undefined || (parsed.headers && typeof parsed.headers === 'object')));
 
 const isWsClosePayload = (parsed) => Boolean(parsed && typeof parsed === 'object');
 
+const readHeaderValue = (headers, name) => {
+  if (!headers || typeof headers !== 'object') return undefined;
+  const want = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (typeof key === 'string' && key.toLowerCase() === want) return value;
+  }
+  return undefined;
+};
+
+/**
+ * Resolve loopback dial port from optional x-openchamber-target-port.
+ * No header → defaultPort. Header present → only a routingTable hit is accepted;
+ * miss/invalid returns null (caller must not fall back to defaultPort).
+ * @param {Record<string, string> | undefined} requestHeaders
+ * @param {number} defaultPort
+ * @param {() => { id?: string, localPort?: number }[]} getSshRoutingTable
+ * @returns {number | null}
+ */
+export const resolveTargetPort = (requestHeaders, defaultPort, getSshRoutingTable) => {
+  const raw = readHeaderValue(requestHeaders, TARGET_PORT_HEADER);
+  if (raw === undefined || raw === null || raw === '') return defaultPort;
+  const parsed = typeof raw === 'number' ? raw : Number.parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 65535) return null;
+  const table = typeof getSshRoutingTable === 'function' ? getSshRoutingTable() : [];
+  if (!Array.isArray(table)) return null;
+  const hit = table.some((entry) => Number(entry?.localPort) === parsed);
+  return hit ? parsed : null;
+};
+
 /**
  * @param {{
  *   connectionId: string,
  *   getLocalPort: () => number,
+ *   getSshRoutingTable?: () => { id: string, localPort: number }[],
  *   sendFrame: (plaintextFrame: Uint8Array) => void | Promise<void>,
  *   getBufferedAmount: () => number,
  *   createWebSocket?: (url: string, protocols: string[] | undefined, options: { headers: Record<string, string> }) => import('ws').WebSocket,
@@ -91,6 +128,7 @@ const isWsClosePayload = (parsed) => Boolean(parsed && typeof parsed === 'object
 export const createTunnelHost = ({
   connectionId,
   getLocalPort,
+  getSshRoutingTable = () => [],
   sendFrame,
   getBufferedAmount,
   createWebSocket = (url, protocols, options) => new WebSocket(url, protocols, options),
@@ -197,6 +235,13 @@ export const createTunnelHost = ({
     const stream = streams.get(streamId);
     if (!stream || stream.kind !== 'http') return;
 
+    const targetPort = resolveTargetPort(request.headers, getLocalPort(), getSshRoutingTable);
+    if (targetPort === null) {
+      dropStream(streamId);
+      await syntheticResponse(streamId, 503, 'ssh-host-unreachable');
+      return;
+    }
+
     const hasBody = method !== 'GET' && method !== 'HEAD';
     let requestBody;
     if (hasBody) {
@@ -210,7 +255,7 @@ export const createTunnelHost = ({
       stream.noBody = true;
     }
 
-    const url = `http://127.0.0.1:${getLocalPort()}${request.path}${request.query ? `?${request.query}` : ''}`;
+    const url = `http://127.0.0.1:${targetPort}${request.path}${request.query ? `?${request.query}` : ''}`;
     let response;
     try {
       response = await fetch(url, {
@@ -323,7 +368,15 @@ export const createTunnelHost = ({
       return;
     }
 
-    const url = `ws://127.0.0.1:${getLocalPort()}${open.path}${open.query ? `?${open.query}` : ''}`;
+    // Optional headers on WsOpen carry routing metadata (e.g. target-port).
+    // Same resolve rules as HTTP; miss refuses without falling back to default.
+    const targetPort = resolveTargetPort(open.headers, getLocalPort(), getSshRoutingTable);
+    if (targetPort === null) {
+      void sendAbort(streamId, 'ssh-host-unreachable');
+      return;
+    }
+
+    const url = `ws://127.0.0.1:${targetPort}${open.path}${open.query ? `?${open.query}` : ''}`;
     // Present the loopback origin we're actually dialing. The server derives this
     // as a trusted same-origin candidate from the Host header (127.0.0.1:<port>),
     // so the WS origin check passes reliably for every client platform. We do NOT
@@ -333,7 +386,7 @@ export const createTunnelHost = ({
     // authenticated by the tunneled oc_url_token, not by this origin.
     const dialHeaders = {
       'x-openchamber-relay-connection': connectionId,
-      origin: `http://127.0.0.1:${getLocalPort()}`,
+      origin: `http://127.0.0.1:${targetPort}`,
     };
     let socket;
     try {

package/server/lib/relay/tunnel-host.test.js

@@ -7,17 +7,18 @@
 // corrupted payload. This test must stay red until send serialization is fixed.
 // Production send path is intentionally not changed here.
 
-import { describe, expect, it } from 'bun:test';
+import { afterEach, describe, expect, it } from 'bun:test';
 
 import {
   MAX_TUNNEL_PAYLOAD_BYTES,
   TunnelFrameType,
   createFragmentAssembler,
+  decodeJsonPayload,
   decodeTunnelFrame,
   encodeJsonPayload,
   encodeTunnelFrame,
 } from './tunnel-codec.js';
-import { createTunnelHost } from './tunnel-host.js';
+import { createTunnelHost, resolveTargetPort } from './tunnel-host.js';
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -223,3 +224,250 @@ describe('createTunnelHost WS fragment ordering', () => {
     }
   });
 });
+
+const collectHttpExchange = async (outbound, streamId) => {
+  await waitFor(() => outbound.some((frame) => {
+    const decoded = decodeTunnelFrame(frame);
+    return decoded.streamId === streamId
+      && (decoded.frameType === TunnelFrameType.StreamEnd
+        || decoded.frameType === TunnelFrameType.StreamAbort);
+  }));
+  let status = null;
+  /** @type {Uint8Array[]} */
+  const bodyChunks = [];
+  for (const raw of outbound) {
+    const frame = decodeTunnelFrame(raw);
+    if (frame.streamId !== streamId) continue;
+    if (frame.frameType === TunnelFrameType.HttpResponse) {
+      status = decodeJsonPayload(frame.payload, (v) => v && typeof v.status === 'number').status;
+    } else if (frame.frameType === TunnelFrameType.HttpBody) {
+      bodyChunks.push(frame.payload);
+    }
+  }
+  let body = null;
+  if (bodyChunks.length > 0) {
+    const total = bodyChunks.reduce((n, c) => n + c.length, 0);
+    const merged = new Uint8Array(total);
+    let off = 0;
+    for (const c of bodyChunks) {
+      merged.set(c, off);
+      off += c.length;
+    }
+    body = JSON.parse(textDecoder.decode(merged));
+  }
+  return { status, body };
+};
+
+describe('createTunnelHost SSH target-port routing', () => {
+  /** @type {typeof globalThis.fetch | undefined} */
+  let originalFetch;
+
+  afterEach(() => {
+    if (originalFetch) {
+      globalThis.fetch = originalFetch;
+      originalFetch = undefined;
+    }
+  });
+
+  const installFetchProbe = () => {
+    /** @type {{ url: string, headers: Record<string, string> }[]} */
+    const calls = [];
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = async (url, init) => {
+      calls.push({
+        url: String(url),
+        headers: { ...(init?.headers || {}) },
+      });
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    };
+    return calls;
+  };
+
+  it('dials the routing-table port when x-openchamber-target-port is allowed', async () => {
+    const fetchCalls = installFetchProbe();
+    /** @type {Uint8Array[]} */
+    const outbound = [];
+    const host = createTunnelHost({
+      connectionId: 'test-conn',
+      getLocalPort: () => 3000,
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+      sendFrame: (frame) => { outbound.push(frame); },
+      getBufferedAmount: () => 0,
+    });
+
+    const streamId = 11;
+    await host.handleFrame(encodeTunnelFrame(
+      TunnelFrameType.HttpRequest,
+      streamId,
+      encodeJsonPayload({
+        method: 'GET',
+        path: '/health',
+        query: '',
+        headers: { 'x-openchamber-target-port': '41234', accept: 'application/json' },
+      }),
+    ));
+
+    const exchange = await collectHttpExchange(outbound, streamId);
+    expect(exchange.status).toBe(200);
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0].url).toBe('http://127.0.0.1:41234/health');
+    host.close();
+  });
+
+  it('returns 503 and does not fall back when target-port is unknown', async () => {
+    const fetchCalls = installFetchProbe();
+    /** @type {Uint8Array[]} */
+    const outbound = [];
+    const host = createTunnelHost({
+      connectionId: 'test-conn',
+      getLocalPort: () => 3000,
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+      sendFrame: (frame) => { outbound.push(frame); },
+      getBufferedAmount: () => 0,
+    });
+
+    const streamId = 12;
+    await host.handleFrame(encodeTunnelFrame(
+      TunnelFrameType.HttpRequest,
+      streamId,
+      encodeJsonPayload({
+        method: 'GET',
+        path: '/health',
+        query: '',
+        headers: { 'x-openchamber-target-port': '9999' },
+      }),
+    ));
+
+    const exchange = await collectHttpExchange(outbound, streamId);
+    expect(exchange.status).toBe(503);
+    expect(exchange.body?.error).toBe('ssh-host-unreachable');
+    expect(fetchCalls).toHaveLength(0);
+    host.close();
+  });
+
+  it('strips x-openchamber-target-port before forwarding to loopback', async () => {
+    const fetchCalls = installFetchProbe();
+    /** @type {Uint8Array[]} */
+    const outbound = [];
+    const host = createTunnelHost({
+      connectionId: 'test-conn',
+      getLocalPort: () => 3000,
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+      sendFrame: (frame) => { outbound.push(frame); },
+      getBufferedAmount: () => 0,
+    });
+
+    const streamId = 13;
+    await host.handleFrame(encodeTunnelFrame(
+      TunnelFrameType.HttpRequest,
+      streamId,
+      encodeJsonPayload({
+        method: 'GET',
+        path: '/api/version',
+        query: '',
+        headers: {
+          'x-openchamber-target-port': '41234',
+          authorization: 'Bearer client-token',
+        },
+      }),
+    ));
+
+    await collectHttpExchange(outbound, streamId);
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0].headers['x-openchamber-target-port']).toBeUndefined();
+    expect(fetchCalls[0].headers.authorization).toBe('Bearer client-token');
+    expect(fetchCalls[0].headers['x-openchamber-relay-connection']).toBe('test-conn');
+    host.close();
+  });
+
+  it('dials the default local port when target-port header is absent', async () => {
+    const fetchCalls = installFetchProbe();
+    /** @type {Uint8Array[]} */
+    const outbound = [];
+    const host = createTunnelHost({
+      connectionId: 'test-conn',
+      getLocalPort: () => 3000,
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+      sendFrame: (frame) => { outbound.push(frame); },
+      getBufferedAmount: () => 0,
+    });
+
+    const streamId = 14;
+    await host.handleFrame(encodeTunnelFrame(
+      TunnelFrameType.HttpRequest,
+      streamId,
+      encodeJsonPayload({
+        method: 'GET',
+        path: '/health',
+        query: '',
+        headers: { accept: 'application/json' },
+      }),
+    ));
+
+    await collectHttpExchange(outbound, streamId);
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0].url).toBe('http://127.0.0.1:3000/health');
+    host.close();
+  });
+
+  it('WS open dials routing-table port and aborts on miss without fallback', async () => {
+    FakeWebSocket.reset();
+    /** @type {Uint8Array[]} */
+    const outbound = [];
+    const host = createTunnelHost({
+      connectionId: 'test-conn',
+      getLocalPort: () => 3000,
+      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
+      sendFrame: (frame) => { outbound.push(frame); },
+      getBufferedAmount: () => 0,
+      createWebSocket: (url, protocols) => new FakeWebSocket(url, protocols),
+    });
+
+    await host.handleFrame(encodeTunnelFrame(
+      TunnelFrameType.WsOpen,
+      21,
+      encodeJsonPayload({
+        path: '/api/event/ws',
+        query: '',
+        headers: { 'x-openchamber-target-port': '41234' },
+      }),
+    ));
+    expect(FakeWebSocket.instances).toHaveLength(1);
+    expect(FakeWebSocket.instances[0].url).toBe('ws://127.0.0.1:41234/api/event/ws');
+
+    await host.handleFrame(encodeTunnelFrame(
+      TunnelFrameType.WsOpen,
+      22,
+      encodeJsonPayload({
+        path: '/api/event/ws',
+        query: '',
+        headers: { 'x-openchamber-target-port': '9999' },
+      }),
+    ));
+    // Miss must not open another socket (no fallback to 3000).
+    expect(FakeWebSocket.instances).toHaveLength(1);
+    await waitFor(() => outbound.some((frame) => {
+      const decoded = decodeTunnelFrame(frame);
+      return decoded.streamId === 22 && decoded.frameType === TunnelFrameType.StreamAbort;
+    }));
+    const abort = outbound
+      .map((frame) => decodeTunnelFrame(frame))
+      .find((frame) => frame.streamId === 22 && frame.frameType === TunnelFrameType.StreamAbort);
+    expect(decodeJsonPayload(abort.payload, () => true).reason).toBe('ssh-host-unreachable');
+    host.close();
+  });
+});
+
+describe('resolveTargetPort', () => {
+  it('returns default when header is absent and null on table miss', () => {
+    const table = () => [{ id: 'ssh-1', localPort: 41234 }];
+    expect(resolveTargetPort({}, 3000, table)).toBe(3000);
+    expect(resolveTargetPort({ 'x-openchamber-target-port': '41234' }, 3000, table)).toBe(41234);
+    expect(resolveTargetPort({ 'X-OpenChamber-Target-Port': '41234' }, 3000, table)).toBe(41234);
+    expect(resolveTargetPort({ 'x-openchamber-target-port': '9999' }, 3000, table)).toBeNull();
+    expect(resolveTargetPort({ 'x-openchamber-target-port': 'not-a-port' }, 3000, table)).toBeNull();
+  });
+});