Decouple bundled UI from runtime API and add remote instance tooling (#1228)

Add a packaged-client runtime boundary so the shared UI can talk to local,
desktop, remote, and VS Code runtimes through the right transport instead of
assuming one same-origin web server.

Centralize OpenChamber-owned API access behind RuntimeAPIs, runtimeFetch, and
runtime URL helpers, while keeping official OpenCode traffic on the SDK path.
Support runtime switching, remote host selection, desktop client credentials,
and headless connection links for pairing packaged clients with remote
OpenChamber servers.

Harden the new auth model by moving long-lived client tokens out of browser
URLs, introducing short-lived scoped URL tokens for browser-owned transports,
restricting URL-token access to explicit readable/realtime routes, and making
client-token management session-scoped or self-scoped as appropriate.

Update browser-owned assets and preview proxy flows to work with the split
runtime model, including authenticated project icons, preview token propagation,
CSP-safe preview bridge injection, and preview proxy auth that survives
short-lived URL-token expiry.

Tighten Electron security boundaries for packaged clients by gating privileged
preload state to trusted origins and requiring explicit confirmation before
connect deep-links import or switch remote runtimes.

Also refresh agent guidance and project skills so future runtime/API, auth,
preview, UI, CLI, settings, locale, and drag-to-reorder work follows the new
architecture.

packages/web/server/lib/opencode/core-routes.js

@@ -22,6 +22,42 @@ const parseLoopbackUrl = (rawUrl) => {
   return url;
 };
 
+const getRequestPathname = (req) => {
+  const rawUrl = req?.originalUrl || req?.url || '';
+  if (typeof rawUrl !== 'string' || rawUrl.length === 0) return '';
+  try {
+    return new URL(rawUrl, 'http://localhost').pathname;
+  } catch {
+    return '';
+  }
+};
+
+const getQueryParam = (req, name) => {
+  const rawUrl = req?.originalUrl || req?.url || '';
+  if (typeof rawUrl !== 'string' || rawUrl.length === 0) return '';
+  try {
+    return new URL(rawUrl, 'http://localhost').searchParams.get(name)?.trim() || '';
+  } catch {
+    return '';
+  }
+};
+
+const getCookieValue = (req, name) => {
+  const cookieHeader = req?.headers?.cookie;
+  if (typeof cookieHeader !== 'string' || cookieHeader.length === 0) return '';
+  for (const segment of cookieHeader.split(';')) {
+    const [rawName, ...rawValueParts] = segment.split('=');
+    if (rawName?.trim() !== name) continue;
+    return rawValueParts.join('=').trim();
+  }
+  return '';
+};
+
+const hasPreviewProxyCredential = (req) => {
+  if (!getRequestPathname(req).startsWith('/api/preview/proxy/')) return false;
+  return Boolean(getQueryParam(req, 'oc_preview_token') || getCookieValue(req, 'oc_preview_token'));
+};
+
 export const registerServerStatusRoutes = (app, dependencies) => {
   const {
     express,
@@ -56,6 +92,19 @@ export const registerServerStatusRoutes = (app, dependencies) => {
     });
   };
 
+  const compatibility = {
+    apiVersion: 1,
+    minClientApiVersion: 1,
+    capabilities: [
+      'api.health.v1',
+      'api.runtime-url.v1',
+      'api.raw-file.v1',
+      'realtime.sse.v1',
+      'realtime.websocket.global-events.v1',
+      'terminal.websocket.v1',
+    ],
+  };
+
   const isDevShutdownAllowed = () => {
     // Dev-only escape hatch: allow terminating the whole dev process group.
     // This should never be enabled in production runtimes.
@@ -166,10 +215,23 @@ export const registerServerStatusRoutes = (app, dependencies) => {
     res.json({
       status: 'ok',
       timestamp: new Date().toISOString(),
+      openchamberVersion,
+      runtime: runtimeName,
+      compatibility,
       ...getHealthSnapshot(),
     });
   });
 
+  app.get('/api/version', (_req, res) => {
+    res.json({
+      status: 'ok',
+      openchamberVersion,
+      runtime: runtimeName,
+      startedAt: serverStartedAt,
+      compatibility,
+    });
+  });
+
   app.post('/api/system/shutdown', (_req, res) => {
     res.json({ ok: true });
     gracefulShutdown({ exitProcess: true }).catch((error) => {
@@ -271,11 +333,69 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     express,
     tunnelAuthController,
     uiAuthController,
+    remoteClientAuthRuntime,
     readSettingsFromDiskMigrated,
     normalizeTunnelSessionTtlMs,
   } = dependencies;
 
+  const runWithUiAuth = async (req, res, next, handler, options = {}) => {
+    try {
+      const requireAuth = options.sessionOnly === true && typeof uiAuthController.requireSessionAuth === 'function'
+        ? uiAuthController.requireSessionAuth
+        : uiAuthController.requireAuth;
+      await requireAuth(req, res, async () => {
+        await handler();
+      });
+    } catch (error) {
+      next(error);
+    }
+  };
+
+  const runWithClientManagementAuth = async (req, res, next, handler) => {
+    try {
+      if (typeof uiAuthController.resolveAuthContext === 'function') {
+        const context = await uiAuthController.resolveAuthContext(req, res, {
+          allowClientAuth: true,
+          allowUrlToken: false,
+        });
+        if (context?.type === 'session' || context?.type === 'client') {
+          await handler(context);
+          return;
+        }
+      }
+
+      await runWithUiAuth(req, res, next, async () => {
+        await handler({ type: 'session' });
+      }, { sessionOnly: true });
+    } catch (error) {
+      next(error);
+    }
+  };
+
+  const clientIdFromAuthContext = (context) => {
+    const raw = context?.client?.id || context?.clientId;
+    return typeof raw === 'string' && raw.length > 0 ? raw : null;
+  };
+
+  const clientRecordFromAuthContext = async (context) => {
+    if (context?.client && typeof context.client === 'object') {
+      return context.client;
+    }
+    const clientId = clientIdFromAuthContext(context);
+    if (!clientId) return null;
+    const clients = await remoteClientAuthRuntime.listClients();
+    return clients.find((client) => client.id === clientId) || null;
+  };
+
   const requireApiAuth = async (req, res, next) => {
+    // Preview proxy requests carry a target-scoped capability token that the
+    // preview proxy validates against the registered target id/TTL. Let those
+    // requests reach that stricter check instead of failing the global UI auth
+    // gate when the short-lived browser URL auth token expires.
+    if (hasPreviewProxyCredential(req)) {
+      return next();
+    }
+
     const requestScope = tunnelAuthController.classifyRequestScope(req);
     if (requestScope === 'tunnel' || requestScope === 'unknown-public') {
       return tunnelAuthController.requireTunnelSession(req, res, next);
@@ -309,6 +429,14 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     return uiAuthController.handleSessionCreate(req, res);
   });
 
+  app.post('/auth/url-token', async (req, res, next) => {
+    try {
+      await uiAuthController.handleUrlAuthToken(req, res);
+    } catch (error) {
+      next(error);
+    }
+  });
+
   app.get('/auth/passkey/status', (req, res) => {
     const requestScope = tunnelAuthController.classifyRequestScope(req);
     if (requestScope === 'tunnel' || requestScope === 'unknown-public') {
@@ -339,7 +467,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
       return res.status(403).json({ error: 'Passkey setup is disabled for tunnel scope', tunnelLocked: true });
     }
     try {
-      await uiAuthController.requireAuth(req, res, async () => {
+      await uiAuthController.requireSessionAuth(req, res, async () => {
         await uiAuthController.handlePasskeyRegistrationOptions(req, res);
       });
     } catch (error) {
@@ -353,7 +481,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
       return res.status(403).json({ error: 'Passkey setup is disabled for tunnel scope', tunnelLocked: true });
     }
     try {
-      await uiAuthController.requireAuth(req, res, async () => {
+      await uiAuthController.requireSessionAuth(req, res, async () => {
         await uiAuthController.handlePasskeyRegistrationVerify(req, res);
       });
     } catch (error) {
@@ -367,7 +495,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
       return res.status(403).json({ error: 'Passkey management is disabled for tunnel scope', tunnelLocked: true });
     }
     try {
-      await uiAuthController.requireAuth(req, res, async () => {
+      await uiAuthController.requireSessionAuth(req, res, async () => {
         await uiAuthController.handlePasskeyList(req, res);
       });
     } catch (error) {
@@ -381,7 +509,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
       return res.status(403).json({ error: 'Passkey management is disabled for tunnel scope', tunnelLocked: true });
     }
     try {
-      await uiAuthController.requireAuth(req, res, async () => {
+      await uiAuthController.requireSessionAuth(req, res, async () => {
         await uiAuthController.handlePasskeyRevoke(req, res);
       });
     } catch (error) {
@@ -395,7 +523,7 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
       return res.status(403).json({ error: 'Global sign-out is disabled for tunnel scope', tunnelLocked: true });
     }
     try {
-      await uiAuthController.requireAuth(req, res, async () => {
+      await uiAuthController.requireSessionAuth(req, res, async () => {
         await uiAuthController.handleResetAuth(req, res);
       });
     } catch (error) {
@@ -403,6 +531,52 @@ export const registerAuthAndAccessRoutes = (app, dependencies) => {
     }
   });
 
+  app.get('/api/client-auth/clients', async (req, res, next) => {
+    await runWithClientManagementAuth(req, res, next, async (authContext) => {
+      if (authContext.type === 'client') {
+        const client = await clientRecordFromAuthContext(authContext);
+        return res.json({ clients: client ? [client] : [] });
+      }
+      const clients = await remoteClientAuthRuntime.listClients();
+      res.json({ clients });
+    });
+  });
+
+  app.post('/api/client-auth/clients', express.json({ limit: '64kb' }), async (req, res, next) => {
+    await runWithUiAuth(req, res, next, async () => {
+      const result = await remoteClientAuthRuntime.createClient({
+        label: req.body?.label,
+        clientKind: req.body?.clientKind,
+        dedupeKey: req.body?.dedupeKey,
+      });
+      res.setHeader('Cache-Control', 'no-store');
+      res.status(201).json(result);
+    }, { sessionOnly: true });
+  });
+
+  app.delete('/api/client-auth/clients/:id', async (req, res, next) => {
+    await runWithClientManagementAuth(req, res, next, async (authContext) => {
+      if (authContext.type === 'client') {
+        const clientId = clientIdFromAuthContext(authContext);
+        if (!clientId || clientId !== req.params?.id) {
+          return res.status(403).json({ revoked: false, error: 'Client tokens can only revoke themselves' });
+        }
+      }
+      const result = await remoteClientAuthRuntime.revokeClient(req.params?.id);
+      if (!result.revoked) {
+        return res.status(404).json({ revoked: false, error: 'Client not found' });
+      }
+      res.json(result);
+    });
+  });
+
+  app.delete('/api/client-auth/clients', async (req, res, next) => {
+    await runWithUiAuth(req, res, next, async () => {
+      const result = await remoteClientAuthRuntime.purgeRevokedClients();
+      res.json(result);
+    }, { sessionOnly: true });
+  });
+
   app.get('/connect', async (req, res) => {
     try {
       const token = typeof req.query?.t === 'string' ? req.query.t : '';