Discord

src/servers/api/browser/cdp.ts

@@ -0,0 +1,99 @@
+type CdpCommandOptions = {
+  relayPort: number;
+  userToken: string;
+  targetId?: string;
+};
+
+async function sendCdpCommand(opts: CdpCommandOptions, method: string, params?: unknown): Promise<unknown> {
+  const { relayPort, userToken, targetId } = opts;
+  const url = `ws://127.0.0.1:${relayPort}/cdp?token=${encodeURIComponent(userToken)}`;
+
+  return await new Promise<unknown>((resolve, reject) => {
+    const ws = new WebSocket(url);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      ws.close();
+      reject(new Error(`CDP command timeout: ${method}`));
+    }, 30_000);
+
+    ws.addEventListener('open', () => {
+      const cmd: Record<string, unknown> = { id: 1, method };
+      if (params) cmd.params = params;
+      if (targetId) cmd.sessionId = targetId;
+      ws.send(JSON.stringify(cmd));
+    });
+
+    ws.addEventListener('message', (event) => {
+      if (settled) return;
+      try {
+        const msg = JSON.parse(String(event.data)) as { id?: number; result?: unknown; error?: { message: string } };
+        if (msg.id === 1) {
+          settled = true;
+          clearTimeout(timeout);
+          ws.close();
+          if (msg.error) reject(new Error(msg.error.message));
+          else resolve(msg.result);
+        }
+      } catch {
+        // ignore parse errors, wait for correct message
+      }
+    });
+
+    ws.addEventListener('error', () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(new Error('CDP WebSocket connection failed'));
+    });
+
+    ws.addEventListener('close', () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(new Error('CDP WebSocket closed before response'));
+    });
+  });
+}
+
+export async function captureScreenshot(
+  opts: CdpCommandOptions,
+  format: 'png' | 'jpeg' = 'png',
+  quality?: number,
+): Promise<string> {
+  const params: Record<string, unknown> = { format };
+  if (quality !== undefined) params.quality = quality;
+  const result = (await sendCdpCommand(opts, 'Page.captureScreenshot', params)) as { data: string };
+  return result.data;
+}
+
+export async function evaluateJS(opts: CdpCommandOptions, expression: string): Promise<unknown> {
+  const result = (await sendCdpCommand(opts, 'Runtime.evaluate', {
+    expression,
+    returnByValue: true,
+    awaitPromise: true,
+  })) as { result?: { value?: unknown; description?: string }; exceptionDetails?: { text?: string } };
+
+  if (result.exceptionDetails) {
+    throw new Error(result.exceptionDetails.text ?? 'Evaluation failed');
+  }
+  return result.result?.value;
+}
+
+export async function navigateTo(opts: CdpCommandOptions, url: string): Promise<void> {
+  await sendCdpCommand(opts, 'Page.navigate', { url });
+}
+
+export async function getPageInfo(opts: CdpCommandOptions): Promise<{ title: string; url: string }> {
+  const result = (await sendCdpCommand(opts, 'Runtime.evaluate', {
+    expression: 'JSON.stringify({ title: document.title, url: location.href })',
+    returnByValue: true,
+  })) as { result?: { value?: string } };
+
+  try {
+    return JSON.parse(result.result?.value ?? '{}');
+  } catch {
+    return { title: '', url: '' };
+  }
+}

src/servers/api/browser/relay-auth.ts

@@ -0,0 +1,31 @@
+import { createHmac } from 'node:crypto';
+
+const RELAY_TOKEN_CONTEXT = 'officer-browser-relay-v1';
+
+const { JWT_SECRET } = process.env;
+
+if (!JWT_SECRET) {
+  throw new Error('JWT_SECRET is required for browser relay auth');
+}
+
+export function deriveRelayToken(userId: number, port: number): string {
+  return createHmac('sha256', JWT_SECRET!)
+    .update(`${RELAY_TOKEN_CONTEXT}:${port}:${userId}`)
+    .digest('hex');
+}
+
+const tokenToUser = new Map<string, number>();
+
+export function registerUserToken(userId: number, port: number): string {
+  const token = deriveRelayToken(userId, port);
+  tokenToUser.set(token, userId);
+  return token;
+}
+
+export function resolveUserFromToken(token: string): number | null {
+  return tokenToUser.get(token) ?? null;
+}
+
+export function getRelayAuthHeader(): string {
+  return 'x-officer-relay-token';
+}

src/servers/api/browser/relay-types.ts

@@ -0,0 +1,89 @@
+export type TargetInfo = {
+  targetId: string;
+  type?: string;
+  title?: string;
+  url?: string;
+  attached?: boolean;
+};
+
+export type ConnectedTarget = {
+  sessionId: string;
+  targetId: string;
+  targetInfo: TargetInfo;
+};
+
+export type RelayStatus = {
+  extensionConnected: boolean;
+  targetCount: number;
+};
+
+export type CdpCommand = {
+  id: number;
+  method: string;
+  params?: unknown;
+  sessionId?: string;
+};
+
+export type CdpResponse = {
+  id: number;
+  result?: unknown;
+  error?: { message: string };
+  sessionId?: string;
+};
+
+export type CdpEvent = {
+  method: string;
+  params?: unknown;
+  sessionId?: string;
+};
+
+export type ExtensionForwardCommandMessage = {
+  id: number;
+  method: 'forwardCDPCommand';
+  params: { method: string; params?: unknown; sessionId?: string };
+};
+
+export type ExtensionResponseMessage = {
+  id: number;
+  result?: unknown;
+  error?: string;
+};
+
+export type ExtensionForwardEventMessage = {
+  method: 'forwardCDPEvent';
+  params: { method: string; params?: unknown; sessionId?: string };
+};
+
+export type ExtensionPingMessage = { method: 'ping' };
+export type ExtensionPongMessage = { method: 'pong' };
+
+export type ExtensionMessage = ExtensionResponseMessage | ExtensionForwardEventMessage | ExtensionPongMessage;
+
+export type AttachedToTargetEvent = {
+  sessionId: string;
+  targetInfo: TargetInfo;
+  waitingForDebugger?: boolean;
+};
+
+export type DetachedFromTargetEvent = {
+  sessionId: string;
+  targetId?: string;
+};
+
+export type UserRelay = {
+  extensionWs: unknown | null;
+  cdpClients: Set<unknown>;
+  connectedTargets: Map<string, ConnectedTarget>;
+  pingInterval: Timer | null;
+  gracePeriodTimer: Timer | null;
+  pendingExtension: Map<
+    number,
+    {
+      resolve: (v: unknown) => void;
+      reject: (e: Error) => void;
+      timer: Timer;
+    }
+  >;
+  nextExtensionId: number;
+  extensionReconnectWaiters: Set<(connected: boolean) => void>;
+};

src/servers/api/browser/relay.ts

@@ -0,0 +1,670 @@
+// Based on OpenClaw Browser Extension Relay (MIT License)
+// https://github.com/nicepkg/openclaw
+//
+// Rewritten for Bun.serve() with multi-user support.
+
+import type { ServerWebSocket } from 'bun';
+import type {
+  AttachedToTargetEvent,
+  CdpCommand,
+  CdpEvent,
+  CdpResponse,
+  ConnectedTarget,
+  DetachedFromTargetEvent,
+  ExtensionForwardCommandMessage,
+  ExtensionForwardEventMessage,
+  ExtensionMessage,
+  ExtensionPongMessage,
+} from './relay-types';
+import { getRelayAuthHeader, resolveUserFromToken } from './relay-auth';
+
+const RELAY_AUTH_HEADER = getRelayAuthHeader();
+const DEFAULT_EXTENSION_RECONNECT_GRACE_MS = 5_000;
+const DEFAULT_EXTENSION_COMMAND_RECONNECT_WAIT_MS = 3_000;
+
+type WSData = {
+  kind: 'extension' | 'cdp';
+  userId: number;
+  token: string;
+};
+
+type UserRelay = {
+  extensionWs: ServerWebSocket<WSData> | null;
+  cdpClients: Set<ServerWebSocket<WSData>>;
+  connectedTargets: Map<string, ConnectedTarget>;
+  pingInterval: Timer | null;
+  gracePeriodTimer: Timer | null;
+  pendingExtension: Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: Timer }>;
+  nextExtensionId: number;
+  extensionReconnectWaiters: Set<(connected: boolean) => void>;
+};
+
+const userRelays = new Map<number, UserRelay>();
+
+function getUserRelay(userId: number): UserRelay {
+  let relay = userRelays.get(userId);
+  if (!relay) {
+    relay = {
+      extensionWs: null,
+      cdpClients: new Set(),
+      connectedTargets: new Map(),
+      pingInterval: null,
+      gracePeriodTimer: null,
+      pendingExtension: new Map(),
+      nextExtensionId: 1,
+      extensionReconnectWaiters: new Set(),
+    };
+    userRelays.set(userId, relay);
+  }
+  return relay;
+}
+
+function extensionConnected(relay: UserRelay): boolean {
+  return relay.extensionWs !== null && relay.extensionWs.readyState === WebSocket.OPEN;
+}
+
+function flushExtensionReconnectWaiters(relay: UserRelay, connected: boolean) {
+  if (relay.extensionReconnectWaiters.size === 0) return;
+  const waiters = Array.from(relay.extensionReconnectWaiters);
+  relay.extensionReconnectWaiters.clear();
+  for (const waiter of waiters) waiter(connected);
+}
+
+function clearGracePeriodTimer(relay: UserRelay) {
+  if (!relay.gracePeriodTimer) return;
+  clearTimeout(relay.gracePeriodTimer);
+  relay.gracePeriodTimer = null;
+}
+
+function closeCdpClientsAfterExtensionDisconnect(relay: UserRelay) {
+  relay.connectedTargets.clear();
+  for (const client of relay.cdpClients) {
+    try {
+      client.close(1011, 'extension disconnected');
+    } catch {
+      // ignore
+    }
+  }
+  relay.cdpClients.clear();
+  flushExtensionReconnectWaiters(relay, false);
+}
+
+function scheduleExtensionDisconnectCleanup(relay: UserRelay) {
+  clearGracePeriodTimer(relay);
+  relay.gracePeriodTimer = setTimeout(() => {
+    relay.gracePeriodTimer = null;
+    if (extensionConnected(relay)) return;
+    closeCdpClientsAfterExtensionDisconnect(relay);
+  }, DEFAULT_EXTENSION_RECONNECT_GRACE_MS);
+}
+
+async function waitForExtensionReconnect(relay: UserRelay, timeoutMs: number): Promise<boolean> {
+  if (extensionConnected(relay)) return true;
+  return await new Promise<boolean>((resolve) => {
+    let settled = false;
+    const waiter = (connected: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      relay.extensionReconnectWaiters.delete(waiter);
+      resolve(connected);
+    };
+    const timer = setTimeout(() => waiter(false), timeoutMs);
+    relay.extensionReconnectWaiters.add(waiter);
+  });
+}
+
+function sendToExtension(relay: UserRelay, payload: ExtensionForwardCommandMessage): Promise<unknown> {
+  const ws = relay.extensionWs;
+  if (!ws || ws.readyState !== WebSocket.OPEN) {
+    throw new Error('Chrome extension not connected');
+  }
+  ws.send(JSON.stringify(payload));
+  return new Promise<unknown>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      relay.pendingExtension.delete(payload.id);
+      reject(new Error(`extension request timeout: ${payload.params.method}`));
+    }, 30_000);
+    relay.pendingExtension.set(payload.id, { resolve, reject, timer });
+  });
+}
+
+function broadcastToCdpClients(relay: UserRelay, evt: CdpEvent) {
+  const msg = JSON.stringify(evt);
+  for (const ws of relay.cdpClients) {
+    if (ws.readyState !== WebSocket.OPEN) continue;
+    ws.send(msg);
+  }
+}
+
+function sendResponseToCdp(ws: ServerWebSocket<WSData>, res: CdpResponse) {
+  if (ws.readyState !== WebSocket.OPEN) return;
+  ws.send(JSON.stringify(res));
+}
+
+function ensureTargetEventsForClient(relay: UserRelay, ws: ServerWebSocket<WSData>, mode: 'autoAttach' | 'discover') {
+  for (const target of relay.connectedTargets.values()) {
+    if (mode === 'autoAttach') {
+      ws.send(
+        JSON.stringify({
+          method: 'Target.attachedToTarget',
+          params: {
+            sessionId: target.sessionId,
+            targetInfo: { ...target.targetInfo, attached: true },
+            waitingForDebugger: false,
+          },
+        } satisfies CdpEvent),
+      );
+    } else {
+      ws.send(
+        JSON.stringify({
+          method: 'Target.targetCreated',
+          params: { targetInfo: { ...target.targetInfo, attached: true } },
+        } satisfies CdpEvent),
+      );
+    }
+  }
+}
+
+async function routeCdpCommand(relay: UserRelay, cmd: CdpCommand): Promise<unknown> {
+  switch (cmd.method) {
+    case 'Browser.getVersion':
+      return {
+        protocolVersion: '1.3',
+        product: 'Chrome/Officer-Browser-Relay',
+        revision: '0',
+        userAgent: 'Officer-Browser-Relay',
+        jsVersion: 'V8',
+      };
+    case 'Browser.setDownloadBehavior':
+      return {};
+    case 'Target.setAutoAttach':
+    case 'Target.setDiscoverTargets':
+      return {};
+    case 'Target.getTargets':
+      return {
+        targetInfos: Array.from(relay.connectedTargets.values()).map((t) => ({
+          ...t.targetInfo,
+          attached: true,
+        })),
+      };
+    case 'Target.getTargetInfo': {
+      const params = (cmd.params ?? {}) as { targetId?: string };
+      const targetId = typeof params.targetId === 'string' ? params.targetId : undefined;
+      if (targetId) {
+        for (const t of relay.connectedTargets.values()) {
+          if (t.targetId === targetId) return { targetInfo: t.targetInfo };
+        }
+      }
+      if (cmd.sessionId && relay.connectedTargets.has(cmd.sessionId)) {
+        const t = relay.connectedTargets.get(cmd.sessionId);
+        if (t) return { targetInfo: t.targetInfo };
+      }
+      const first = Array.from(relay.connectedTargets.values())[0];
+      return { targetInfo: first?.targetInfo };
+    }
+    case 'Target.attachToTarget': {
+      const params = (cmd.params ?? {}) as { targetId?: string };
+      const targetId = typeof params.targetId === 'string' ? params.targetId : undefined;
+      if (!targetId) throw new Error('targetId required');
+      for (const t of relay.connectedTargets.values()) {
+        if (t.targetId === targetId) return { sessionId: t.sessionId };
+      }
+      throw new Error('target not found');
+    }
+    default: {
+      const id = relay.nextExtensionId++;
+      return await sendToExtension(relay, {
+        id,
+        method: 'forwardCDPCommand',
+        params: {
+          method: cmd.method,
+          sessionId: cmd.sessionId,
+          params: cmd.params,
+        },
+      });
+    }
+  }
+}
+
+function handleExtensionMessage(relay: UserRelay, data: string) {
+  let parsed: ExtensionMessage | null = null;
+  try {
+    parsed = JSON.parse(data) as ExtensionMessage;
+  } catch {
+    return;
+  }
+
+  if (parsed && typeof parsed === 'object' && 'id' in parsed && typeof parsed.id === 'number') {
+    const pending = relay.pendingExtension.get(parsed.id);
+    if (!pending) return;
+    relay.pendingExtension.delete(parsed.id);
+    clearTimeout(pending.timer);
+    if ('error' in parsed && typeof parsed.error === 'string' && parsed.error.trim()) {
+      pending.reject(new Error(parsed.error));
+    } else {
+      pending.resolve(parsed.result);
+    }
+    return;
+  }
+
+  if (parsed && typeof parsed === 'object' && 'method' in parsed) {
+    if ((parsed as ExtensionPongMessage).method === 'pong') return;
+    if ((parsed as ExtensionForwardEventMessage).method !== 'forwardCDPEvent') return;
+
+    const evt = parsed as ExtensionForwardEventMessage;
+    const method = evt.params?.method;
+    const params = evt.params?.params;
+    const sessionId = evt.params?.sessionId;
+    if (!method || typeof method !== 'string') return;
+
+    if (method === 'Target.attachedToTarget') {
+      const attached = (params ?? {}) as AttachedToTargetEvent;
+      const targetType = attached?.targetInfo?.type ?? 'page';
+      if (targetType !== 'page') return;
+      if (attached?.sessionId && attached?.targetInfo?.targetId) {
+        const prev = relay.connectedTargets.get(attached.sessionId);
+        const nextTargetId = attached.targetInfo.targetId;
+        const prevTargetId = prev?.targetId;
+        const changedTarget = Boolean(prev && prevTargetId && prevTargetId !== nextTargetId);
+        relay.connectedTargets.set(attached.sessionId, {
+          sessionId: attached.sessionId,
+          targetId: nextTargetId,
+          targetInfo: attached.targetInfo,
+        });
+        if (changedTarget && prevTargetId) {
+          broadcastToCdpClients(relay, {
+            method: 'Target.detachedFromTarget',
+            params: { sessionId: attached.sessionId, targetId: prevTargetId },
+            sessionId: attached.sessionId,
+          });
+        }
+        if (!prev || changedTarget) {
+          broadcastToCdpClients(relay, { method, params, sessionId });
+        }
+        return;
+      }
+    }
+
+    if (method === 'Target.detachedFromTarget') {
+      const detached = (params ?? {}) as DetachedFromTargetEvent;
+      if (detached?.sessionId) {
+        relay.connectedTargets.delete(detached.sessionId);
+      }
+      broadcastToCdpClients(relay, { method, params, sessionId });
+      return;
+    }
+
+    if (method === 'Target.targetInfoChanged') {
+      const changed = (params ?? {}) as { targetInfo?: { targetId?: string; type?: string } };
+      const targetInfo = changed?.targetInfo;
+      const targetId = targetInfo?.targetId;
+      if (targetId && (targetInfo?.type ?? 'page') === 'page') {
+        for (const [sid, target] of relay.connectedTargets) {
+          if (target.targetId !== targetId) continue;
+          relay.connectedTargets.set(sid, {
+            ...target,
+            targetInfo: { ...target.targetInfo, ...(targetInfo as object) },
+          });
+        }
+      }
+    }
+
+    broadcastToCdpClients(relay, { method, params, sessionId });
+  }
+}
+
+function handleExtensionClose(relay: UserRelay, ws: ServerWebSocket<WSData>) {
+  if (relay.pingInterval) {
+    clearInterval(relay.pingInterval);
+    relay.pingInterval = null;
+  }
+  if (relay.extensionWs !== ws) return;
+  relay.extensionWs = null;
+  for (const [, pending] of relay.pendingExtension) {
+    clearTimeout(pending.timer);
+    pending.reject(new Error('extension disconnected'));
+  }
+  relay.pendingExtension.clear();
+  scheduleExtensionDisconnectCleanup(relay);
+}
+
+function handleExtensionOpen(relay: UserRelay, ws: ServerWebSocket<WSData>) {
+  relay.extensionWs = ws;
+  clearGracePeriodTimer(relay);
+  flushExtensionReconnectWaiters(relay, true);
+
+  relay.pingInterval = setInterval(() => {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify({ method: 'ping' }));
+  }, 5000);
+}
+
+async function handleCdpMessage(relay: UserRelay, ws: ServerWebSocket<WSData>, data: string) {
+  let cmd: CdpCommand | null = null;
+  try {
+    cmd = JSON.parse(data) as CdpCommand;
+  } catch {
+    return;
+  }
+  if (!cmd || typeof cmd !== 'object') return;
+  if (typeof cmd.id !== 'number' || typeof cmd.method !== 'string') return;
+
+  if (!extensionConnected(relay)) {
+    const reconnected = await waitForExtensionReconnect(relay, DEFAULT_EXTENSION_COMMAND_RECONNECT_WAIT_MS);
+    if (!reconnected || !extensionConnected(relay)) {
+      sendResponseToCdp(ws, {
+        id: cmd.id,
+        sessionId: cmd.sessionId,
+        error: { message: 'Extension not connected' },
+      });
+      return;
+    }
+  }
+
+  try {
+    const result = await routeCdpCommand(relay, cmd);
+
+    if (cmd.method === 'Target.setAutoAttach' && !cmd.sessionId) {
+      ensureTargetEventsForClient(relay, ws, 'autoAttach');
+    }
+    if (cmd.method === 'Target.setDiscoverTargets') {
+      const discover = (cmd.params ?? {}) as { discover?: boolean };
+      if (discover.discover === true) {
+        ensureTargetEventsForClient(relay, ws, 'discover');
+      }
+    }
+    if (cmd.method === 'Target.attachToTarget') {
+      const params = (cmd.params ?? {}) as { targetId?: string };
+      const targetId = typeof params.targetId === 'string' ? params.targetId : undefined;
+      if (targetId) {
+        const target = Array.from(relay.connectedTargets.values()).find((t) => t.targetId === targetId);
+        if (target) {
+          ws.send(
+            JSON.stringify({
+              method: 'Target.attachedToTarget',
+              params: {
+                sessionId: target.sessionId,
+                targetInfo: { ...target.targetInfo, attached: true },
+                waitingForDebugger: false,
+              },
+            } satisfies CdpEvent),
+          );
+        }
+      }
+    }
+
+    sendResponseToCdp(ws, { id: cmd.id, sessionId: cmd.sessionId, result });
+  } catch (err) {
+    sendResponseToCdp(ws, {
+      id: cmd.id,
+      sessionId: cmd.sessionId,
+      error: { message: err instanceof Error ? err.message : String(err) },
+    });
+  }
+}
+
+function getTokenFromUrl(url: string): string | null {
+  try {
+    const parsed = new URL(url, 'http://localhost');
+    return parsed.searchParams.get('token')?.trim() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function getTokenFromHeaders(headers: Headers): string | null {
+  return headers.get(RELAY_AUTH_HEADER)?.trim() ?? null;
+}
+
+function getTokenFromRequest(req: Request): string | null {
+  return getTokenFromHeaders(req.headers) ?? getTokenFromUrl(req.url);
+}
+
+function authenticateRequest(req: Request): number | null {
+  const token = getTokenFromRequest(req);
+  if (!token) return null;
+  return resolveUserFromToken(token);
+}
+
+let relayServer: ReturnType<typeof Bun.serve> | null = null;
+let relayPort = 0;
+
+export function getRelayPort(): number {
+  return relayPort;
+}
+
+export function getUserRelayStatus(userId: number): { extensionConnected: boolean; targetCount: number } {
+  const relay = userRelays.get(userId);
+  if (!relay) return { extensionConnected: false, targetCount: 0 };
+  return {
+    extensionConnected: extensionConnected(relay),
+    targetCount: relay.connectedTargets.size,
+  };
+}
+
+export function getUserTargets(userId: number): ConnectedTarget[] {
+  const relay = userRelays.get(userId);
+  if (!relay) return [];
+  return Array.from(relay.connectedTargets.values());
+}
+
+export function startBrowserRelay(port: number) {
+  relayPort = port;
+
+  const server = Bun.serve<WSData>({
+    port,
+    hostname: '0.0.0.0',
+    idleTimeout: 60,
+
+    routes: {
+      '/': (req: Request) => {
+        if (req.method === 'HEAD') return new Response(null, { status: 200 });
+        return new Response('OK', { status: 200, headers: { 'Content-Type': 'text/plain' } });
+      },
+    },
+
+    fetch(req, server) {
+      const url = new URL(req.url);
+      const path = url.pathname;
+
+      // CORS for chrome-extension origins
+      const origin = req.headers.get('origin');
+      const corsHeaders: Record<string, string> = {};
+      if (origin) {
+        corsHeaders['Access-Control-Allow-Origin'] = origin;
+        corsHeaders['Vary'] = 'Origin';
+      }
+
+      if (req.method === 'OPTIONS') {
+        return new Response(null, {
+          status: 204,
+          headers: {
+            ...corsHeaders,
+            'Access-Control-Allow-Methods': 'GET, PUT, POST, OPTIONS',
+            'Access-Control-Allow-Headers': `Content-Type, ${RELAY_AUTH_HEADER}`,
+            'Access-Control-Max-Age': '86400',
+          },
+        });
+      }
+
+      if (path === '/extension/status') {
+        const connectedCount = Array.from(userRelays.values()).filter((r) => extensionConnected(r)).length;
+        return Response.json({ connected: connectedCount > 0, users: connectedCount }, { headers: corsHeaders });
+      }
+
+      // Auth-protected endpoints
+      const token = getTokenFromRequest(req);
+      const userId = token ? resolveUserFromToken(token) : null;
+
+      if (path === '/json/version' || path === '/json/version/') {
+        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
+        const relay = userRelays.get(userId);
+        const payload: Record<string, unknown> = {
+          Browser: 'Officer/browser-relay',
+          'Protocol-Version': '1.3',
+        };
+        if (relay && extensionConnected(relay)) {
+          const hostHeader = req.headers.get('host')?.trim() || `0.0.0.0:${port}`;
+          payload.webSocketDebuggerUrl = `ws://${hostHeader}/cdp?token=${token}`;
+        }
+        return Response.json(payload, { headers: corsHeaders });
+      }
+
+      const listPaths = new Set(['/json', '/json/', '/json/list', '/json/list/']);
+      if (listPaths.has(path)) {
+        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
+        const relay = userRelays.get(userId);
+        const hostHeader = req.headers.get('host')?.trim() || `0.0.0.0:${port}`;
+        const cdpWsUrl = `ws://${hostHeader}/cdp?token=${token}`;
+        const list = relay
+          ? Array.from(relay.connectedTargets.values()).map((t) => ({
+              id: t.targetId,
+              type: t.targetInfo.type ?? 'page',
+              title: t.targetInfo.title ?? '',
+              description: t.targetInfo.title ?? '',
+              url: t.targetInfo.url ?? '',
+              webSocketDebuggerUrl: cdpWsUrl,
+            }))
+          : [];
+        return Response.json(list, { headers: corsHeaders });
+      }
+
+      const activateMatch = path.match(/^\/json\/activate\/(.+)$/);
+      if (activateMatch) {
+        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
+        const targetId = decodeURIComponent(activateMatch[1]!).trim();
+        if (!targetId) return new Response('targetId required', { status: 400, headers: corsHeaders });
+        const relay = userRelays.get(userId);
+        if (relay && extensionConnected(relay)) {
+          void sendToExtension(relay, {
+            id: relay.nextExtensionId++,
+            method: 'forwardCDPCommand',
+            params: { method: 'Target.activateTarget', params: { targetId } },
+          }).catch(() => {});
+        }
+        return new Response('OK', { status: 200, headers: corsHeaders });
+      }
+
+      const closeMatch = path.match(/^\/json\/close\/(.+)$/);
+      if (closeMatch) {
+        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
+        const targetId = decodeURIComponent(closeMatch[1]!).trim();
+        if (!targetId) return new Response('targetId required', { status: 400, headers: corsHeaders });
+        const relay = userRelays.get(userId);
+        if (relay && extensionConnected(relay)) {
+          void sendToExtension(relay, {
+            id: relay.nextExtensionId++,
+            method: 'forwardCDPCommand',
+            params: { method: 'Target.closeTarget', params: { targetId } },
+          }).catch(() => {});
+        }
+        return new Response('OK', { status: 200, headers: corsHeaders });
+      }
+
+      // WebSocket upgrades
+      if (path === '/extension') {
+        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
+        const relay = getUserRelay(userId);
+        // Close stale extension WS
+        if (relay.extensionWs && relay.extensionWs.readyState !== WebSocket.OPEN) {
+          try {
+            (relay.extensionWs as ServerWebSocket<WSData>).close();
+          } catch {
+            // ignore
+          }
+          relay.extensionWs = null;
+        }
+        if (extensionConnected(relay)) {
+          return new Response('Extension already connected', { status: 409, headers: corsHeaders });
+        }
+        const ok = server.upgrade(req, { data: { kind: 'extension', userId, token: token! } });
+        if (!ok) return new Response('Upgrade failed', { status: 500, headers: corsHeaders });
+        return undefined as unknown as Response;
+      }
+
+      if (path === '/cdp') {
+        if (userId === null) return new Response('Unauthorized', { status: 401, headers: corsHeaders });
+        const relay = userRelays.get(userId);
+        if (!relay || !extensionConnected(relay)) {
+          return new Response('Extension not connected', { status: 503, headers: corsHeaders });
+        }
+        const ok = server.upgrade(req, { data: { kind: 'cdp', userId, token: token! } });
+        if (!ok) return new Response('Upgrade failed', { status: 500, headers: corsHeaders });
+        return undefined as unknown as Response;
+      }
+
+      return new Response('Not found', { status: 404, headers: corsHeaders });
+    },
+
+    websocket: {
+      open(ws) {
+        const { kind, userId } = ws.data;
+        const relay = getUserRelay(userId);
+
+        if (kind === 'extension') {
+          handleExtensionOpen(relay, ws);
+        } else {
+          relay.cdpClients.add(ws);
+        }
+      },
+
+      message(ws, raw) {
+        const { kind, userId } = ws.data;
+        const relay = userRelays.get(userId);
+        if (!relay) return;
+        const data = typeof raw === 'string' ? raw : new TextDecoder().decode(raw as unknown as ArrayBuffer);
+
+        if (kind === 'extension') {
+          handleExtensionMessage(relay, data);
+        } else {
+          void handleCdpMessage(relay, ws, data);
+        }
+      },
+
+      close(ws) {
+        const { kind, userId } = ws.data;
+        const relay = userRelays.get(userId);
+        if (!relay) return;
+
+        if (kind === 'extension') {
+          handleExtensionClose(relay, ws);
+        } else {
+          relay.cdpClients.delete(ws);
+        }
+      },
+    },
+  });
+
+  relayServer = server;
+  return server;
+}
+
+export function stopBrowserRelay() {
+  if (!relayServer) return;
+  for (const [, relay] of userRelays) {
+    clearGracePeriodTimer(relay);
+    if (relay.pingInterval) clearInterval(relay.pingInterval);
+    flushExtensionReconnectWaiters(relay, false);
+    for (const [, pending] of relay.pendingExtension) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('server stopping'));
+    }
+    relay.pendingExtension.clear();
+    try {
+      relay.extensionWs?.close(1001, 'server stopping');
+    } catch {
+      // ignore
+    }
+    for (const ws of relay.cdpClients) {
+      try {
+        ws.close(1001, 'server stopping');
+      } catch {
+        // ignore
+      }
+    }
+  }
+  userRelays.clear();
+  relayServer.stop();
+  relayServer = null;
+}

src/servers/api/browser/router.ts

@@ -0,0 +1,135 @@
+import { createRouter } from '@@/create-router';
+import * as errors from '@@/custom-errors';
+import { registerUserToken } from './relay-auth';
+import { getRelayPort, getUserRelayStatus, getUserTargets } from './relay';
+import { captureScreenshot, evaluateJS, navigateTo } from './cdp';
+
+export const browserRouter = createRouter();
+
+function getOpts(userId: number) {
+  const port = getRelayPort();
+  const token = registerUserToken(userId, port);
+  return { relayPort: port, userToken: token };
+}
+
+browserRouter.get('/status', async (ctx) => {
+  const user = ctx.get('user');
+  const status = getUserRelayStatus(user.id);
+  return ctx.json(status);
+});
+
+browserRouter.get('/relay-token', async (ctx) => {
+  const user = ctx.get('user');
+  const port = getRelayPort();
+  const token = registerUserToken(user.id, port);
+  return ctx.json({ token, port });
+});
+
+browserRouter.get('/targets', async (ctx) => {
+  const user = ctx.get('user');
+  const targets = getUserTargets(user.id);
+  return ctx.json(
+    targets.map((t) => ({
+      id: t.targetId,
+      sessionId: t.sessionId,
+      type: t.targetInfo.type ?? 'page',
+      title: t.targetInfo.title ?? '',
+      url: t.targetInfo.url ?? '',
+    })),
+  );
+});
+
+browserRouter.get('/targets/:id/screenshot', async (ctx) => {
+  const user = ctx.get('user');
+  const targetId = ctx.req.param('id');
+  const format = (ctx.req.query('format') as 'png' | 'jpeg') || 'png';
+
+  const opts = getOpts(user.id);
+  // Find session ID for the target
+  const targets = getUserTargets(user.id);
+  const target = targets.find((t) => t.targetId === targetId);
+  if (!target) throw errors.NOT_FOUND('Target not found');
+
+  try {
+    const data = await captureScreenshot({ ...opts, targetId: target.sessionId }, format);
+    return ctx.json({ data, format });
+  } catch (err) {
+    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Screenshot failed');
+  }
+});
+
+browserRouter.post('/targets/:id/evaluate', async (ctx) => {
+  const user = ctx.get('user');
+  const targetId = ctx.req.param('id');
+  const body = ctx.get('body') as { expression?: string };
+
+  if (!body.expression) throw errors.BAD_REQUEST('expression is required');
+
+  const opts = getOpts(user.id);
+  const targets = getUserTargets(user.id);
+  const target = targets.find((t) => t.targetId === targetId);
+  if (!target) throw errors.NOT_FOUND('Target not found');
+
+  try {
+    const result = await evaluateJS({ ...opts, targetId: target.sessionId }, body.expression);
+    return ctx.json({ result });
+  } catch (err) {
+    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Evaluation failed');
+  }
+});
+
+browserRouter.post('/targets/:id/navigate', async (ctx) => {
+  const user = ctx.get('user');
+  const targetId = ctx.req.param('id');
+  const body = ctx.get('body') as { url?: string };
+
+  if (!body.url) throw errors.BAD_REQUEST('url is required');
+
+  const opts = getOpts(user.id);
+  const targets = getUserTargets(user.id);
+  const target = targets.find((t) => t.targetId === targetId);
+  if (!target) throw errors.NOT_FOUND('Target not found');
+
+  try {
+    await navigateTo({ ...opts, targetId: target.sessionId }, body.url);
+    return ctx.json({ ok: true });
+  } catch (err) {
+    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Navigation failed');
+  }
+});
+
+browserRouter.post('/targets/:id/activate', async (ctx) => {
+  const user = ctx.get('user');
+  const targetId = ctx.req.param('id');
+
+  const port = getRelayPort();
+  const token = registerUserToken(user.id, port);
+
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/activate/${encodeURIComponent(targetId)}`, {
+      headers: { 'x-officer-relay-token': token },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return ctx.json({ ok: true });
+  } catch (err) {
+    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Activate failed');
+  }
+});
+
+browserRouter.post('/targets/:id/close', async (ctx) => {
+  const user = ctx.get('user');
+  const targetId = ctx.req.param('id');
+
+  const port = getRelayPort();
+  const token = registerUserToken(user.id, port);
+
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/close/${encodeURIComponent(targetId)}`, {
+      headers: { 'x-officer-relay-token': token },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return ctx.json({ ok: true });
+  } catch (err) {
+    throw errors.INTERNAL_SERVER_ERROR(err instanceof Error ? err.message : 'Close failed');
+  }
+});