@linxin666/dsh-remote-web-ui 0.2.4 → 0.2.5

package/src/remote-api.ts

@@ -0,0 +1,217 @@
+/**
+ * The remote desktop data channel: `/remote` is this plugin's own prefix, so
+ * the paired-device cookie is the access control (exactly like `/m/api`).
+ * After that gate, every fenced same-origin path the browser rewrote here is
+ * re-issued to 127.0.0.1 as a loopback-shaped request so sibling plugin
+ * fences (and the connection plugin's `/api`) accept it — no `--trusted-host`
+ * and no per-plugin pairing consult.
+ *
+ * Security model:
+ * - Every request must carry a live paired-device cookie, enforced before
+ *   any bytes are forwarded and before any host call.
+ * - The SDK's loopback-only privileged methods (native dialogs, the settings
+ *   plane, credentials — the `PRIVILEGED_METHODS` set of client-connection)
+ *   are denied here. The set is pinned by tests/remote-contract.spec.ts.
+ * - `/api/pair/*`, `/api/update/*`, `/api/plugin-manager/*`,
+ *   `/api/dsh-desktop-launcher/*` and `/api/dsh-web-ui-settings/*` stay physically local.
+ * - Everything else is HTTP- or WebSocket-proxied to the local port with
+ *   Host rewritten, Origin and cookies dropped, and a synthetic same-origin
+ *   browser marker added after authentication. Plugin loopback fences then
+ *   pass. The pairing cookie never leaves this process.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
+import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
+import type { PairingService } from './pairing.ts'
+import { readCookie } from './gate.ts'
+import { writeJson } from './http.ts'
+import { proxyLoopbackHttp, proxyLoopbackUpgrade } from './loopback-proxy.ts'
+import {
+  DESKTOP_LAUNCHER_PATH,
+  LOOPBACK_ONLY_METHODS,
+  PLUGIN_MANAGER_PATH,
+  REMOTE_API_PATHS,
+  REMOTE_PREFIX,
+  REMOTE_UPGRADE_PATHS,
+  WEB_UI_SETTINGS_BRIDGE_PATH,
+} from './remote-methods.ts'
+
+export {
+  DESKTOP_LAUNCHER_PATH,
+  LOOPBACK_ONLY_METHODS,
+  PLUGIN_MANAGER_PATH,
+  REMOTE_API_PATHS,
+  REMOTE_PREFIX,
+  REMOTE_UPGRADE_PATHS,
+  WEB_UI_SETTINGS_BRIDGE_PATH,
+} from './remote-methods.ts'
+export { REMOTE_API_PREFIX } from './remote-methods.ts'
+
+const ALLOWED_METHODS = new Set(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'])
+
+/** Reject traversal and empty segments; allow plugin file-path characters. */
+function isSafeSegment(segment: string): boolean {
+  if (segment === '') return false
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(segment)
+  } catch {
+    return false
+  }
+  return decoded !== '.' && decoded !== '..' && !decoded.includes('/') && !decoded.includes('\\') && !decoded.includes('\0')
+}
+
+/** Route-family dependencies. */
+export interface RemoteApiDeps {
+  /** The pairing service (device gate + cookie name). */
+  service: PairingService
+  /** The local webServer port the loopback proxy connects to. */
+  port: number
+}
+
+/** One SDK-shaped error envelope (keeps the desktop client's parse path intact). */
+function envelopeError(res: ServerResponse, status: number, rpcId: string, code: string, message: string): void {
+  writeJson(res, status, {
+    type: 'server-response',
+    rpcId,
+    result: { ok: false, error: { code, message, details: { issues: [] } } },
+  })
+}
+
+/**
+ * Map `/remote/...` to the inner path, or undefined when the outer path is
+ * not a safe rewrite target.
+ */
+export function innerPathOf(pathname: string): string | undefined {
+  if (pathname === REMOTE_PREFIX || pathname === `${REMOTE_PREFIX}/`) return undefined
+  if (!pathname.startsWith(`${REMOTE_PREFIX}/`)) return undefined
+  const rest = pathname.slice(REMOTE_PREFIX.length)
+  if (!rest.startsWith('/')) return undefined
+  const segments = rest.slice(1).split('/')
+  if (segments.length === 0 || segments.some(segment => !isSafeSegment(segment))) {
+    return undefined
+  }
+  return rest
+}
+
+/**
+ * Whether a paired inner path must stay physically local.
+ * @returns a denial message, or undefined when the path may be proxied.
+ */
+export function loopbackOnlyDenial(innerPath: string): string | undefined {
+  if (innerPath === '/api/pair' || innerPath.startsWith('/api/pair/')) {
+    return 'pairing endpoints stay loopback-only and stay unreachable from a paired remote desktop'
+  }
+  if (innerPath === '/api/update' || innerPath.startsWith('/api/update/')) {
+    return 'update endpoints stay loopback-only and stay unreachable from a paired remote desktop'
+  }
+  if (innerPath === PLUGIN_MANAGER_PATH || innerPath.startsWith(`${PLUGIN_MANAGER_PATH}/`)) {
+    return 'plugin-manager stays loopback-only and stays unreachable from a paired remote desktop'
+  }
+  if (innerPath === DESKTOP_LAUNCHER_PATH || innerPath.startsWith(`${DESKTOP_LAUNCHER_PATH}/`)) {
+    return 'desktop-launcher endpoints stay loopback-only and stay unreachable from a paired remote desktop'
+  }
+  if (innerPath === WEB_UI_SETTINGS_BRIDGE_PATH || innerPath.startsWith(`${WEB_UI_SETTINGS_BRIDGE_PATH}/`)) {
+    return 'settings-bridge endpoints stay loopback-only and stay unreachable from a paired remote desktop'
+  }
+  if (!innerPath.startsWith('/api/')) return undefined
+  const method = innerPath.slice('/api/'.length)
+  if (method !== '' && !method.includes('/') && LOOPBACK_ONLY_METHODS.has(method)) {
+    return `${method} is loopback-only and stays unreachable from a paired remote desktop`
+  }
+  return undefined
+}
+
+/**
+ * Build the remote desktop channel HTTP routes.
+ * @param deps - pairing service + local port.
+ * @returns the routes to register on webServer.
+ */
+export function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[] {
+  const { service, port } = deps
+
+  const handler = (req: IncomingMessage, res: ServerResponse): void => {
+    // Cookie gate first — same order as /m/api. Do not buffer an unpaired body.
+    const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
+    const paired = deviceId !== undefined && service.touchDevice(deviceId)
+    if (!paired) {
+      req.resume()
+      envelopeError(res, 403, 'invalid-request', 'unpaired', 'this device is not paired with the desktop')
+      return
+    }
+
+    const method = req.method ?? 'GET'
+    if (!ALLOWED_METHODS.has(method)) {
+      req.resume()
+      res.writeHead(405).end()
+      return
+    }
+
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+    const inner = innerPathOf(url.pathname)
+    if (inner === undefined) {
+      req.resume()
+      res.writeHead(404).end()
+      return
+    }
+    const denied = loopbackOnlyDenial(inner)
+    if (denied !== undefined) {
+      req.resume()
+      envelopeError(res, 403, 'invalid-request', 'forbidden', denied)
+      return
+    }
+
+    proxyLoopbackHttp(req, res, port, `${inner}${url.search}`)
+  }
+
+  return [{ kind: 'prefix', path: REMOTE_PREFIX, handler }]
+}
+
+/**
+ * Map one outer upgrade URL onto the loopback path (query string included).
+ */
+export function upgradeInnerPath(reqUrl: string | undefined, fallbackPath: string): string {
+  if (reqUrl === undefined || reqUrl === '') return fallbackPath
+  let url: URL
+  try {
+    url = new URL(reqUrl, 'http://127.0.0.1')
+  } catch {
+    return fallbackPath
+  }
+  const inner = innerPathOf(url.pathname)
+  if (inner === undefined) return fallbackPath
+  return `${inner}${url.search}`
+}
+
+/**
+ * Build the WebSocket upgrade routes for the event streams and known plugin
+ * sockets. webServer matches upgrades by exact path.
+ * @param deps - pairing service + local port.
+ * @returns the upgrade routes to register on webServer.
+ */
+export function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute[] {
+  const { service, port } = deps
+
+  const handlerFor = (fallbackPath: string) => (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
+    const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
+    if (deviceId === undefined || !service.touchDevice(deviceId)) {
+      socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
+      socket.destroy()
+      return
+    }
+    const inner = upgradeInnerPath(req.url, fallbackPath)
+    const denied = loopbackOnlyDenial(inner.split('?')[0] ?? inner)
+    if (denied !== undefined) {
+      socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
+      socket.destroy()
+      return
+    }
+    proxyLoopbackUpgrade(req, socket, head, port, inner)
+  }
+
+  return REMOTE_UPGRADE_PATHS.map((path) => ({
+    path,
+    handler: handlerFor(path.slice(REMOTE_PREFIX.length)),
+  }))
+}

package/src/remote-methods.ts

@@ -0,0 +1,62 @@
+/**
+ * Remote desktop channel constants — SDK-independent so tests and the
+ * client half can pin them without importing the host SDK graph.
+ */
+
+/** Gated mirror of same-origin fenced paths (`/remote` + original pathname). */
+export const REMOTE_PREFIX = '/remote'
+
+/** Connection-plugin method prefix under the gated channel. */
+export const REMOTE_API_PREFIX = `${REMOTE_PREFIX}/api`
+
+/** WebSocket event-stream paths served by the channel (client rewrites to these). */
+export const REMOTE_API_PATHS = {
+  mux: `${REMOTE_API_PREFIX}/events.mux`,
+  host: `${REMOTE_API_PREFIX}/events.host`,
+} as const
+
+/**
+ * Exact upgrade paths registered on webServer (the SDK matches upgrades by
+ * exact path, not prefix). Query strings ride on the request URL.
+ */
+export const REMOTE_UPGRADE_PATHS = [
+  REMOTE_API_PATHS.mux,
+  REMOTE_API_PATHS.host,
+  `${REMOTE_PREFIX}/sidebar/ws/terminal`,
+  `${REMOTE_PREFIX}/sidebar/ws/agent-terminals`,
+  `${REMOTE_API_PREFIX}/dsh-ssh/terminal`,
+] as const
+
+/** Plugin-manager HTTP prefix: install/remove stay physically local. */
+export const PLUGIN_MANAGER_PATH = '/api/plugin-manager'
+
+/** Desktop-launcher HTTP prefix: shortcut create and host shutdown stay physically local. */
+export const DESKTOP_LAUNCHER_PATH = '/api/dsh-desktop-launcher'
+
+/** Family settings-bridge HTTP prefix: describe/mutate stay physically local. */
+export const WEB_UI_SETTINGS_BRIDGE_PATH = '/api/dsh-web-ui-settings'
+
+/**
+ * Loopback-only methods of the host API surface, mirrored from
+ * client-connection's `PRIVILEGED_METHODS` (pinned by
+ * tests/remote-contract.spec.ts against the installed SDK). They stay
+ * unreachable from a paired remote desktop, matching the SDK's own stance
+ * that the configuration plane is loopback-same-origin only.
+ */
+export const LOOPBACK_ONLY_METHODS = new Set([
+  'agentPreset.read',
+  'agentPreset.copy',
+  'agentPreset.openDocument',
+  'agentPreset.remove',
+  'host.pickDirectory',
+  'host.openPath',
+  'settings.describe',
+  'settings.openDocument',
+  'settings.update',
+  'settings.replace',
+  'settings.mutate',
+  'credentials.describe',
+  'credentials.set',
+  'credentials.unset',
+  'llm.discoverModels',
+])

package/src/routes.ts

@@ -88,6 +88,7 @@ export const PAIR_PATHS = {
   issue: '/api/pair/issue',
   accept: '/api/pair/accept',
   stop: '/api/pair/stop',
+  revoke: '/api/pair/revoke',
   heartbeat: '/api/pair/heartbeat',
   status: '/api/pair/status',
   events: '/api/pair/events',
@@ -108,6 +109,9 @@ export const issuePayloadSchema = z.object({
 export const acceptPayloadSchema = z.object({
   token: z.string().default(''),
 })
+export const revokePayloadSchema = z.object({
+  deviceId: z.string().min(1),
+})
 export const pairActionPayloadSchema = z.object({}).passthrough()
 
 /**
@@ -310,7 +314,8 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
       writeJson(res, 400, { ok: false, code: 'bad-payload' })
       return
     }
-    const result = service.accept(payload.token)
+    const ua = req.headers['user-agent']
+    const result = service.accept(payload.token, typeof ua === 'string' ? ua : undefined)
     if (!result.ok) {
       writeJson(res, result.code === 'used' ? 409 : 404, { ok: false, code: result.code })
       return
@@ -342,6 +347,26 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
     writeJson(res, 200, { ok: true })
   }
 
+  const handleRevoke = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (!requireMethod(req, res, 'POST')) return
+    if (!loopbackFence(req)) {
+      writeJson(res, 403, { ok: false, code: 'forbidden' })
+      return
+    }
+    const body = await readJsonBody(req)
+    const payload = parsePairPayload(revokePayloadSchema, body)
+    if (payload === undefined) {
+      writeJson(res, 400, { ok: false, code: 'bad-payload' })
+      return
+    }
+    const revoked = service.revoke(payload.deviceId)
+    if (!revoked) {
+      writeJson(res, 404, { ok: false, code: 'unknown-device' })
+      return
+    }
+    writeJson(res, 200, { ok: true })
+  }
+
   const handleHeartbeat = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     if (!requireMethod(req, res, 'POST')) return
     if (!lanFence(req)) {
@@ -371,10 +396,13 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
     const paired = deviceId !== undefined && service.hasDevice(deviceId)
     const snapshot = service.snapshot()
     // Unpaired LAN/tunnel clients get only the pairing-relevant fields; the
-    // token expiry, device roster, and public tunnel URL are an oracle for
-    // targeting and timing and stay behind a live device cookie.
+    // token expiry, public tunnel URL, and counts are an oracle for targeting
+    // and stay behind a live device cookie. The per-device roster (ids are
+    // session credentials) is never returned here — only the loopback events
+    // stream carries it to the desktop panel.
+    const { devices: _devices, ...rest } = snapshot
     const visible = paired
-      ? snapshot
+      ? rest
       : { phase: snapshot.phase, lanAvailable: snapshot.lanAvailable, lanAddresses: snapshot.lanAddresses }
     writeJson(res, 200, { ok: true, paired, ...visible })
   }
@@ -394,6 +422,7 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
     { kind: 'exact', path: PAIR_PATHS.issue, handler: handleIssue },
     { kind: 'exact', path: PAIR_PATHS.accept, handler: handleAccept },
     { kind: 'exact', path: PAIR_PATHS.stop, handler: handleStop },
+    { kind: 'exact', path: PAIR_PATHS.revoke, handler: handleRevoke },
     { kind: 'exact', path: PAIR_PATHS.heartbeat, handler: handleHeartbeat },
     { kind: 'exact', path: PAIR_PATHS.status, handler: handleStatus },
     { kind: 'exact', path: PAIR_PATHS.events, handler: handleEvents },