npm - @openchambery/web - Versions diffs - 1.19.5-beta.4 → 1.19.5-beta.5 - Mend

@openchambery/web 1.19.5-beta.4 → 1.19.5-beta.5

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.

Files changed (60) hide show

package/dist/mini-chat.html CHANGED Viewed

@@ -74,7 +74,7 @@
       }
     </style>
-    <script type="module" crossorigin src="/assets/miniChat-BLk2pfbb.js"></script>
+    <script type="module" crossorigin src="/assets/miniChat-CUFkoTCJ.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-base-ui-CnHfUmDN.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-zustand-B4dlGEM2.js">
@@ -91,7 +91,7 @@
     <link rel="modulepreload" crossorigin href="/assets/terminalApi-Bnx0KvaV.js">
     <link rel="modulepreload" crossorigin href="/assets/types-BuiqMmh_.js">
     <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-DCowZ2ab.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-lhaApt62.js">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-_JcGrrxY.js">
     <link rel="stylesheet" crossorigin href="/assets/src-CD7-ovJ5.css">
   </head>
   <body class="h-full bg-background text-foreground">

package/dist/mobile.html CHANGED Viewed

@@ -63,7 +63,7 @@
       })();
     </script>
-    <script type="module" crossorigin src="/assets/mobile-4xN65TJf.js"></script>
+    <script type="module" crossorigin src="/assets/mobile-B_x6fY62.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-base-ui-CnHfUmDN.js">
     <link rel="modulepreload" crossorigin href="/assets/vendor-zustand-B4dlGEM2.js">
@@ -80,7 +80,7 @@
     <link rel="modulepreload" crossorigin href="/assets/terminalApi-Bnx0KvaV.js">
     <link rel="modulepreload" crossorigin href="/assets/types-BuiqMmh_.js">
     <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-DCowZ2ab.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-lhaApt62.js">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-_JcGrrxY.js">
     <link rel="stylesheet" crossorigin href="/assets/src-CD7-ovJ5.css">
   </head>
   <body class="h-full bg-background text-foreground">

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@openchambery/web",
-  "version": "1.19.5-beta.4",
+  "version": "1.19.5-beta.5",
   "private": false,
   "type": "module",
   "main": "./server/index.js",

package/server/index.js CHANGED Viewed

@@ -1419,6 +1419,29 @@ async function main(options = {}) {
     // Re-evaluate the relay lifecycle after pairing/device changes (a revoked or
     // redeemed device can flip relay demand on or off).
     reconcileRelay: () => (relayServiceInstance ? relayServiceInstance.reconcile() : Promise.resolve()),
+    // Canonical endpoints the host relay currently uses (primary first).
+    // Pairing-session requests from paired desktop clients may carry a relayUrl
+    // only when it matches one of these (an echo of an advertised endpoint,
+    // never a re-point or an extension).
+    getEffectiveRelayUrls: async () => {
+      if (!relayServiceInstance) return [];
+      try {
+        const status = await relayServiceInstance.getStatus();
+        return Array.isArray(status?.relayUrls) ? status.relayUrls : [];
+      } catch {
+        return [];
+      }
+    },
+    // Every configured relay endpoint as a pairing candidate (multi-relay),
+    // for the connection-candidates refresh.
+    getRelayPairingCandidates: async () => {
+      if (!relayServiceInstance) return [];
+      try {
+        return await relayServiceInstance.getPairingCandidates();
+      } catch {
+        return [];
+      }
+    },
     getPairingTransports: async (req) => {
       const transports = resolvePairingTransports(req);
       if (!relayServiceInstance || !transports.relayAvailable) return transports;
@@ -1426,6 +1449,7 @@ async function main(options = {}) {
       return {
         ...transports,
         relayUrl: relay.relayUrl,
+        relayUrls: relay.relayUrls,
         relayUrlLocked: relay.relayUrlLocked,
       };
     },
@@ -1516,6 +1540,22 @@ async function main(options = {}) {
     onRelayUrlChanged: async () => {
       await apnsRuntime.reRegisterAllTokens();
     },
+    // Owner gate for relay-endpoint management: UI session or the local desktop
+    // shell. Paired remote clients (desktops included) are NOT endpoint owners
+    // — adding/removing endpoints is the same trust boundary as re-pointing
+    // the primary endpoint.
+    isOwnerRequest: async (req, res) => {
+      if (typeof uiAuthController?.resolveAuthContext !== 'function') return false;
+      try {
+        const context = await uiAuthController.resolveAuthContext(req, res, { allowClientAuth: true, allowUrlToken: false });
+        if (context?.type === 'session') return true;
+        if (context?.type === 'client') {
+          return context.client?.clientKind === 'desktop-local';
+        }
+      } catch {
+      }
+      return false;
+    },
   });
   relayServiceInstance = relayService;
   relayService.registerRoutes(app);

package/server/lib/opencode/core-routes.js CHANGED Viewed

@@ -390,6 +390,16 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     // hostEncPubJwk, priority }) when the host relay is enabled, else null.
     // Injected lazily because the relay service is constructed after these routes.
     getRelayPairingCandidate = async () => null,
+    // All configured relay endpoints (canonical ws(s)://…), primary first, or
+    // [] when relay status is unavailable. Gates remote-bearer pairing requests
+    // that carry a relayUrl: paired desktops may only use an endpoint the host
+    // already has (echo of any configured endpoint, never a re-point).
+    getEffectiveRelayUrls = async () => [],
+    // Candidates for EVERY configured relay endpoint (multi-relay), or null /
+    // a non-array when only the single-endpoint accessor is available. Feeds
+    // the connection-candidates refresh so paired devices learn the full
+    // reachable endpoint set.
+    getRelayPairingCandidates = async () => null,
     // Re-evaluate the relay lifecycle after pairing/device changes.
     reconcileRelay = async () => {},
     // Returns { local, lan, relayAvailable } — the direct transport URLs the
@@ -424,6 +434,15 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     }
   };
+  // Which paired clients may act as operators of this server's device fleet:
+  // create pairing links, list every device, and revoke other devices. The
+  // desktop shell's local client is the in-process operator; a paired `desktop`
+  // client is granted the same trust at pairing time (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.
+  const canManageRemoteClients = (client) =>
+    client?.clientKind === 'desktop-local' || client?.clientKind === 'desktop';
   const runWithClientManagementAuth = async (req, res, next, handler) => {
     try {
       if (typeof uiAuthController.resolveAuthContext === 'function') {
@@ -458,7 +477,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
         }
         if (context?.type === 'client') {
           const client = await clientRecordFromAuthContext(context);
-          if (client?.clientKind === 'desktop-local') {
+          if (canManageRemoteClients(client)) {
             await handler({ ...context, client });
             return;
           }
@@ -779,10 +798,10 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     await runWithClientManagementAuth(req, res, next, async (authContext) => {
       if (authContext.type === 'client') {
         const client = await clientRecordFromAuthContext(authContext);
-        // The desktop shell's local client is the trusted operator of this
-        // server; it manages devices just like a browser UI session. Every
-        // other client token is scoped to its own record.
-        if (client?.clientKind !== 'desktop-local') {
+        // Operator clients (local desktop shell, paired desktops) manage the
+        // whole device fleet; every other client token is scoped to its own
+        // record.
+        if (!canManageRemoteClients(client)) {
           return res.json({ clients: client ? [client] : [] });
         }
       }
@@ -807,9 +826,9 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     await runWithClientManagementAuth(req, res, next, async (authContext) => {
       if (authContext.type === 'client') {
         const actingClient = await clientRecordFromAuthContext(authContext);
-        // The desktop shell's local client manages every device; other client
-        // tokens may only revoke themselves.
-        if (actingClient?.clientKind !== 'desktop-local') {
+        // Operator clients (local desktop shell, paired desktops) may revoke
+        // any device; other client tokens may only revoke themselves.
+        if (!canManageRemoteClients(actingClient)) {
           const clientId = clientIdFromAuthContext(authContext);
           if (!clientId || clientId !== req.params?.id) {
             return res.status(403).json({ revoked: false, error: 'Client tokens can only revoke themselves' });
@@ -829,9 +848,10 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     await runWithClientManagementAuth(req, res, next, async (authContext) => {
       if (authContext.type === 'client') {
         const actingClient = await clientRecordFromAuthContext(authContext);
-        // Purging revoked devices is a whole-server management action; only the
-        // trusted desktop shell client (or a UI session) may do it.
-        if (actingClient?.clientKind !== 'desktop-local') {
+        // Purging revoked devices is a whole-server management action; only
+        // operator clients (local desktop shell, paired desktops) or a UI
+        // session may do it.
+        if (!canManageRemoteClients(actingClient)) {
           return res.status(403).json({ purged: 0, error: 'Client tokens cannot purge revoked devices' });
         }
       }
@@ -843,22 +863,25 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
   app.post('/api/client-auth/pairing/sessions', express.json({ limit: '64kb' }), async (req, res, next) => {
     await runWithClientCreateAuth(req, res, next, async (authContext) => {
-      // Changing the Host Relay endpoint is an owner-UI or local desktop-shell
-      // action. Paired remote clients never reach this handler (create-auth only
-      // admits session + desktop-local); keep the kind check so a future auth
-      // widening cannot re-point the Host relay from a remote bearer.
-      if (req.body?.relayUrl !== undefined && authContext?.type === 'client') {
-        const actingClient = authContext.client || await clientRecordFromAuthContext(authContext);
-        if (actingClient?.clientKind !== 'desktop-local') {
-          return res.status(403).json({ error: 'Only the owner UI session can set a custom Relay endpoint' });
-        }
-      }
       const requestedRelayUrl = req.body?.relayUrl === undefined
         ? undefined
         : normalizeRequestedRelayUrl(req.body.relayUrl);
       if (req.body?.relayUrl !== undefined && !requestedRelayUrl) {
         return res.status(400).json({ error: 'Relay URL must use ws:// or wss://' });
       }
+      // Changing the Host Relay endpoint set is an owner-UI or local
+      // desktop-shell action. Paired desktop operators reach this handler too,
+      // but may only name an endpoint the host already uses — anything else
+      // would re-point (or extend) the Host relay from a remote bearer.
+      if (requestedRelayUrl !== undefined && authContext?.type === 'client') {
+        const actingClient = authContext.client || await clientRecordFromAuthContext(authContext);
+        if (actingClient?.clientKind !== 'desktop-local') {
+          const effectiveRelayUrls = await getEffectiveRelayUrls();
+          if (!Array.isArray(effectiveRelayUrls) || !effectiveRelayUrls.includes(requestedRelayUrl)) {
+            return res.status(403).json({ error: 'Only the owner UI session can set a custom Relay endpoint' });
+          }
+        }
+      }
       const candidates = await pairingServerCandidates(req, {
         preferredServerUrl: req.body?.serverUrl,
         includeRelay: typeof req.body?.includeRelay === 'boolean' ? req.body.includeRelay : undefined,
@@ -906,8 +929,18 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
         if (normalized) candidates.push({ type: 'lan', url: normalized, priority: 10 });
       }
       try {
-        const relayCandidate = await getRelayPairingCandidate({ ensureEnabled: false });
-        if (relayCandidate) candidates.push(relayCandidate);
+        // Multi-relay: a paired device learns EVERY configured endpoint so a
+        // lost/expensive domain can fall back to the other (the client still
+        // keeps its per-connection instance identity — serverId + relayUrl).
+        const relayCandidates = await getRelayPairingCandidates();
+        if (Array.isArray(relayCandidates)) {
+          for (const relayCandidate of relayCandidates) {
+            if (relayCandidate) candidates.push(relayCandidate);
+          }
+        } else {
+          const relayCandidate = await getRelayPairingCandidate({ ensureEnabled: false });
+          if (relayCandidate) candidates.push(relayCandidate);
+        }
       } catch {
         // Relay status failure must not break the direct-candidate refresh.
       }

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

@@ -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 CHANGED Viewed

@@ -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.