@openchambery/web 1.19.4 → 1.19.5-beta.10

package/server/lib/opencode/core-routes.test.js

@@ -915,13 +915,17 @@ describe('core-routes', () => {
     ]);
   });
 
-  it('forbids non-desktop client tokens from setting a custom Relay endpoint', async () => {
-    const getRelayPairingCandidate = vi.fn();
+  it('lets paired desktop clients create pairing sessions like the local owner (relay-attached parity)', async () => {
+    const getRelayPairingCandidate = vi.fn(async () => ({
+      type: 'relay',
+      relayUrl: 'wss://relay.example/ws',
+      serverId: 'srv_desktop',
+      hostEncPubJwk: { kty: 'EC', crv: 'P-256', x: 'aaa', y: 'bbb' },
+      priority: 30,
+    }));
     const { app, dependencies } = createPairingRouteApp({
       getRelayPairingCandidate,
       uiAuthController: {
-        // Force a remote desktop client past create-auth so the relayUrl gate is
-        // exercised independently of the desktop-local create-auth admission rule.
         resolveAuthContext: vi.fn(async () => ({
           type: 'client',
           clientId: 'remote-desktop-1',
@@ -943,15 +947,152 @@ describe('core-routes', () => {
       },
     });
 
+    const response = await request(app)
+      .post('/api/client-auth/pairing/sessions')
+      .set('Host', 'runtime.example')
+      .send({ label: 'Pair phone', includeRelay: true })
+      .expect(201);
+
+    expect(dependencies.clientPairingRuntime.createPairingSession).toHaveBeenCalledWith({
+      label: 'Pair phone',
+      allowedClientKinds: undefined,
+      createdByClientId: 'remote-desktop-1',
+      usesRelay: true,
+    });
+    expect(response.body.server.candidates).toEqual([
+      { type: 'lan', url: 'http://runtime.example', priority: 10 },
+      expect.objectContaining({ type: 'relay', relayUrl: 'wss://relay.example/ws' }),
+    ]);
+  });
+
+  it('rejects pairing-session creation from mobile client tokens', async () => {
+    const { app, dependencies } = createPairingRouteApp({
+      uiAuthController: {
+        resolveAuthContext: vi.fn(async () => ({
+          type: 'client',
+          clientId: 'phone-1',
+          client: { id: 'phone-1', clientKind: 'mobile' },
+        })),
+        requireAuth: vi.fn((_req, _res, next) => next()),
+        requireSessionAuth: vi.fn((_req, _res, next) => next()),
+        handleSessionStatus: vi.fn(),
+        handleSessionCreate: vi.fn(),
+        handleUrlAuthToken: vi.fn(),
+        handlePasskeyStatus: vi.fn(),
+        handlePasskeyAuthenticationOptions: vi.fn(),
+        handlePasskeyAuthenticationVerify: vi.fn(),
+        handlePasskeyRegistrationOptions: vi.fn(),
+        handlePasskeyRegistrationVerify: vi.fn(),
+        handlePasskeyList: vi.fn(),
+        handlePasskeyRevoke: vi.fn(),
+        handleResetAuth: vi.fn(),
+      },
+    });
+
     await request(app)
       .post('/api/client-auth/pairing/sessions')
-      .send({ includeRelay: true, relayUrl: 'wss://relay.example/custom' })
+      .send({ label: 'Pair phone' })
       .expect(403, { error: 'Client tokens cannot create remote clients' });
 
+    expect(dependencies.clientPairingRuntime.createPairingSession).not.toHaveBeenCalled();
+  });
+
+  it('forbids paired desktop clients from re-pointing the Relay endpoint when pairing', async () => {
+    const getRelayPairingCandidate = vi.fn();
+    const getEffectiveRelayUrls = vi.fn(async () => ['wss://relay.example/ws']);
+    const { app, dependencies } = createPairingRouteApp({
+      getRelayPairingCandidate,
+      getEffectiveRelayUrls,
+      uiAuthController: {
+        resolveAuthContext: vi.fn(async () => ({
+          type: 'client',
+          clientId: 'remote-desktop-1',
+          client: { id: 'remote-desktop-1', clientKind: 'desktop' },
+        })),
+        requireAuth: vi.fn((_req, _res, next) => next()),
+        requireSessionAuth: vi.fn((_req, _res, next) => next()),
+        handleSessionStatus: vi.fn(),
+        handleSessionCreate: vi.fn(),
+        handleUrlAuthToken: vi.fn(),
+        handlePasskeyStatus: vi.fn(),
+        handlePasskeyAuthenticationOptions: vi.fn(),
+        handlePasskeyAuthenticationVerify: vi.fn(),
+        handlePasskeyRegistrationOptions: vi.fn(),
+        handlePasskeyRegistrationVerify: vi.fn(),
+        handlePasskeyList: vi.fn(),
+        handlePasskeyRevoke: vi.fn(),
+        handleResetAuth: vi.fn(),
+      },
+    });
+
+    await request(app)
+      .post('/api/client-auth/pairing/sessions')
+      .send({ includeRelay: true, relayUrl: 'wss://attacker.example/ws' })
+      .expect(403, { error: 'Only the owner UI session can set a custom Relay endpoint' });
+
     expect(getRelayPairingCandidate).not.toHaveBeenCalled();
     expect(dependencies.clientPairingRuntime.createPairingSession).not.toHaveBeenCalled();
   });
 
+  it('lets paired desktop clients echo the current Relay endpoint when pairing', async () => {
+    const getRelayPairingCandidate = vi.fn(async ({ relayUrl }) => ({
+      type: 'relay',
+      relayUrl,
+      serverId: 'srv_desktop',
+      hostEncPubJwk: { kty: 'EC', crv: 'P-256', x: 'aaa', y: 'bbb' },
+      priority: 30,
+    }));
+    const getEffectiveRelayUrls = vi.fn(async () => ['wss://relay.example/ws', 'wss://relay2.example/ws']);
+    const { app } = createPairingRouteApp({
+      getRelayPairingCandidate,
+      getEffectiveRelayUrls,
+      uiAuthController: {
+        resolveAuthContext: vi.fn(async () => ({
+          type: 'client',
+          clientId: 'remote-desktop-1',
+          client: { id: 'remote-desktop-1', clientKind: 'desktop' },
+        })),
+        requireAuth: vi.fn((_req, _res, next) => next()),
+        requireSessionAuth: vi.fn((_req, _res, next) => next()),
+        handleSessionStatus: vi.fn(),
+        handleSessionCreate: vi.fn(),
+        handleUrlAuthToken: vi.fn(),
+        handlePasskeyStatus: vi.fn(),
+        handlePasskeyAuthenticationOptions: vi.fn(),
+        handlePasskeyAuthenticationVerify: vi.fn(),
+        handlePasskeyRegistrationOptions: vi.fn(),
+        handlePasskeyRegistrationVerify: vi.fn(),
+        handlePasskeyList: vi.fn(),
+        handlePasskeyRevoke: vi.fn(),
+        handleResetAuth: vi.fn(),
+      },
+    });
+
+    const response = await request(app)
+      .post('/api/client-auth/pairing/sessions')
+      .send({ includeRelay: true, includeDirect: false, relayUrl: 'wss://relay.example/ws' })
+      .expect(201);
+
+    expect(getRelayPairingCandidate).toHaveBeenCalledWith({
+      ensureEnabled: true,
+      relayUrl: 'wss://relay.example/ws',
+    });
+    expect(response.body.server.candidates).toEqual([
+      expect.objectContaining({ type: 'relay', relayUrl: 'wss://relay.example/ws' }),
+    ]);
+
+    // Multi-relay: any CONFIGURED endpoint is fair game for a paired desktop
+    // (choosing between the host's endpoints is not a re-point).
+    await request(app)
+      .post('/api/client-auth/pairing/sessions')
+      .send({ includeRelay: true, includeDirect: false, relayUrl: 'wss://relay2.example/ws' })
+      .expect(201);
+    expect(getRelayPairingCandidate).toHaveBeenLastCalledWith({
+      ensureEnabled: true,
+      relayUrl: 'wss://relay2.example/ws',
+    });
+  });
+
   it('still lets desktop-local create pairing sessions without a custom Relay endpoint', async () => {
     const getRelayPairingCandidate = vi.fn(async () => null);
     const { app, dependencies } = createPairingRouteApp({
@@ -1287,6 +1428,25 @@ describe('client auth routes', () => {
     expect(response.body.candidates).toEqual([]);
   });
 
+  it('returns every configured relay endpoint in the candidates refresh (multi-relay)', async () => {
+    const app = express();
+    const relayCandidates = [
+      { type: 'relay', relayUrl: 'wss://relay.example/ws', serverId: 'server-abc', hostEncPubJwk: { kty: 'EC', crv: 'P-256', x: 'x', y: 'y' }, priority: 30 },
+      { type: 'relay', relayUrl: 'wss://relay2.example/ws', serverId: 'server-abc', hostEncPubJwk: { kty: 'EC', crv: 'P-256', x: 'x', y: 'y' }, priority: 30 },
+    ];
+    const dependencies = {
+      ...createDependencies({ resolveAuthContext: async () => ({ type: 'client', clientId: 'client-1' }) }),
+      getDirectCandidateUrls: () => [],
+      getRelayPairingCandidates: async () => relayCandidates,
+      getServerId: async () => 'server-abc',
+    };
+    registerAuthAndAccessRoutes(app, dependencies);
+
+    const response = await request(app).get('/api/client-auth/connection/candidates');
+    expect(response.status).toBe(200);
+    expect(response.body.candidates).toEqual(relayCandidates);
+  });
+
   it('scopes non-desktop client credentials to list and revoke only themselves', async () => {
     const app = express();
     let authContext = { type: 'session' };
@@ -1355,7 +1515,47 @@ describe('client auth routes', () => {
     expect(purged.body.purged).toBe(1);
   });
 
-  it('allows only the local desktop client token to create remote client tokens', async () => {
+  it('lets paired desktop clients list and revoke every device (relay-attached parity)', async () => {
+    const app = express();
+    let authContext = { type: 'session' };
+    const dependencies = createDependencies({
+      resolveAuthContext: async () => authContext,
+    });
+    registerAuthAndAccessRoutes(app, dependencies);
+
+    const localDesktop = await request(app)
+      .post('/api/client-auth/clients')
+      .send({ label: 'OpenChamber Desktop', clientKind: 'desktop-local' });
+    const pairedDesktop = await request(app)
+      .post('/api/client-auth/clients')
+      .send({ label: 'Study desktop', clientKind: 'desktop' });
+    const phone = await request(app)
+      .post('/api/client-auth/clients')
+      .send({ label: 'Phone', clientKind: 'mobile' });
+
+    // A paired desktop (connected over relay) manages all devices like the
+    // local desktop shell — SSH-attach parity for relay-attached hosts.
+    authContext = { type: 'client', clientId: pairedDesktop.body.client.id, client: pairedDesktop.body.client };
+
+    const listed = await request(app).get('/api/client-auth/clients');
+    expect(listed.status).toBe(200);
+    const listedIds = listed.body.clients.map((client) => client.id).sort();
+    expect(listedIds).toEqual([
+      localDesktop.body.client.id,
+      pairedDesktop.body.client.id,
+      phone.body.client.id,
+    ].sort());
+
+    const revoked = await request(app).delete(`/api/client-auth/clients/${phone.body.client.id}`);
+    expect(revoked.status).toBe(200);
+    expect(revoked.body.revoked).toBe(true);
+
+    const purged = await request(app).delete('/api/client-auth/clients');
+    expect(purged.status).toBe(200);
+    expect(purged.body.purged).toBeGreaterThanOrEqual(1);
+  });
+
+  it('restricts direct client-token creation to operator clients', async () => {
     const app = express();
     let authContext = { type: 'session' };
     const dependencies = createDependencies({

package/server/lib/relay/DOCUMENTATION.md

@@ -19,7 +19,7 @@ Traffic is modeled as three stacked layers. The relay understands only Layer 1;
 ## Entrypoints and structure
 
 Host side (`packages/web/server/lib/relay/`):
-- `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. Host lifecycle is gated by `isRelayHostRuntime()` (`desktop` or `ssh-remote`): other runtimes (`bun run dev`, `dev:web:hmr`, ordinary CLI `serve`, VS Code, plain `node server`) report `state: 'unavailable'`, refuse `/relay/enable`, `/relay/disable`, and relay pairing with 403, never mint a relay identity, never advertise `relayAvailable`, and never call `startRelayHost`. Direct `node server/index.js` forces `OPENCHAMBER_RUNTIME=web` unless it is already `ssh-remote`, so a leftover desktop env cannot open the host-control socket. On host runtimes, started from `packages/web/server/index.js` when demand/opt-in enables the relay. Desktop auto-clears `privateRelay.enabled` when demand drops; `ssh-remote` keeps an explicit opt-in (e.g. `openchamber serve --relay-host`) sticky until disabled. 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; when set it overrides the stored setting for the host connection, the pairing candidate, and status, so paired clients inherit the endpoint automatically. Endpoint identity is scheme/host/path only: accepted schemes are `ws://` and `wss://`; URLs with userinfo are rejected (no silent default fallback); query and fragment are stripped before persistence and pairing candidates. Custom endpoint persistence and Host control-connection switching are explicit authenticated management actions. Pairing creation with `relayUrl` requires an owner UI session or the local `desktop-local` shell client; `/relay/enable` follows its API auth gate. `derivePushSendUrlFromRelayUrl` maps a canonical Relay `wss://`/`ws://` URL to the same host's `https://`/`http://` `/v1/push/send` path (register is `/v1/push/register-token`); `OPENCHAMBER_PUSH_RELAY_URL` on the Host overrides that derivation. The isolated Push process lives in `packages/relay-server/src/push/` and does not share Layer 1 credentials or tunnel state.
+- `service.js` — thin entrypoint: relay config (enabled flag + endpoints), the management routes (`GET/POST /api/openchamber/relay/{status,enable,disable}`, `POST /api/openchamber/relay/endpoints`), 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. **Multi-relay:** `settings.privateRelay = { enabled, relayUrl, extraRelayUrls }` — the host dials EVERY configured endpoint simultaneously with one identity (same serverId); clients treat `serverId + relayUrl` as the instance identity, so the same machine exposed via two domains appears as two separately named instances. The primary (`relayUrl`) owns push registration and stays the default pairing candidate. A pairing link created for an endpoint the host does not have yet APPENDS it as an extra endpoint (owner request only) instead of replacing the primary, so devices paired over the old domain keep working. `POST /relay/endpoints` (owner session / `desktop-local` only) replaces the extra-endpoint list wholesale and starts/stops host connections incrementally. Paired desktops may pair over any CONFIGURED endpoint but can never add one. Host lifecycle is gated by `isRelayHostRuntime()` (`desktop` or `ssh-remote`): other runtimes (`bun run dev`, `dev:web:hmr`, ordinary CLI `serve`, VS Code, plain `node server`) report `state: 'unavailable'`, refuse `/relay/enable`, `/relay/disable`, `/relay/endpoints`, and relay pairing with 403, never mint a relay identity, never advertise `relayAvailable`, and never call `startRelayHost`. Direct `node server/index.js` forces `OPENCHAMBER_RUNTIME=web` unless it is already `ssh-remote`, so a leftover desktop env cannot open the host-control socket. On host runtimes, started from `packages/web/server/index.js` when demand/opt-in enables the relay. Desktop auto-clears `privateRelay.enabled` when demand drops; `ssh-remote` keeps an explicit opt-in (e.g. `openchamber serve --relay-host`) sticky until disabled. 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; when set it overrides the stored setting for the host connection, the pairing candidate, and status, so paired clients inherit the endpoint automatically. Endpoint identity is scheme/host/path only: accepted schemes are `ws://` and `wss://`; URLs with userinfo are rejected (no silent default fallback); query and fragment are stripped before persistence and pairing candidates. Custom endpoint persistence and Host control-connection switching are explicit authenticated management actions. Pairing creation with `relayUrl` requires an owner UI session or the local `desktop-local` shell client; `/relay/enable` follows its API auth gate. `derivePushSendUrlFromRelayUrl` maps a canonical Relay `wss://`/`ws://` URL to the same host's `https://`/`http://` `/v1/push/send` path (register is `/v1/push/register-token`); `OPENCHAMBER_PUSH_RELAY_URL` on the Host overrides that derivation. The isolated Push process lives in `packages/relay-server/src/push/` and does not share Layer 1 credentials or tunnel state.
 - `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.
 - `signing-key.js` — storage/derivation of the signing keypair and the routing id, shared with the notifications runtime. Canonical public JWK hashing matches `packages/relay-server/src/push/crypto.js`.
 - `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.
@@ -59,6 +59,7 @@ See also `packages/web/server/lib/opencode/DOCUMENTATION.md` (“Catalog / OpenC
 ## Authentication model
 
 - 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.
+- A paired **desktop** client is a device-fleet operator: through the tunnel it can create pairing links, list every paired device, and revoke other devices (parity with the SSH attach flow, where the connecting desktop authenticates as the operator). Mobile (and any other) paired clients stay scoped to their own record. Re-pointing the Host relay endpoint set from a remote bearer remains forbidden — a paired desktop may name any endpoint the host already has, but adding/removing endpoints (including `relayUrl` in pairing requests for a new domain) is an owner-UI / local-desktop-shell action.
 - 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).
 - The host authenticates itself to the relay with a signed handshake using its long-lived signing key.
 - Enabling the relay is explicit opt-in and disabled by default; disabling it severs all relay reachability immediately.