diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c8193a5..32d638b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ All notable changes to DreamCoder will be documented in this file. ### Added +- **Remote serving mode (server only).** Start the server with `--remote-serving` (or `SERVER_REMOTE_SERVING=1`) to run it on a remote host behind an SSH tunnel without trusting the tunnel. In this mode every `/api` and `/ws` request needs the H5 access token, whatever its address or `Origin`; the server only listens on a loopback address, answers only requests whose `Host` is a loopback name, refuses proxied requests, and does not serve the H5 control plane, the terminal socket or the browser-host endpoints. Off by default; nothing changes without the flag. This is the server half of the remote agent backend: the desktop app cannot connect to a remote server yet. The design, setup, the `401` check that detects a server which ignores the flag, and the limits that remain are in `docs/features/remote-backend/tech-design.md` (Part of #24). - **Sessions can start other sessions and message each other.** The agent can start a new session with `StartSession`, either fresh with a brief or as a fork of its own conversation, optionally in a new git worktree; you approve every new session, whatever the permission mode. Any session can message any other with `SendMessage`, across projects: a message wakes the receiver, and a progress report from a child to its parent waits for the parent's next turn instead of interrupting it (a parent that is already working sees it right away). Reports waiting for the parent are listed above its message box. The server stamps who sent each message, so a session cannot pass itself off as you or as another session. `ListSessions` lists sessions, and `RenameSession` lets the agent rename its own session (#239). - **Sessions are nested in the sidebar.** Sessions the agent started, and conversations you forked, appear under the session they came from, with an icon for each kind and a count that collapses or expands them. Messages from another session appear in the conversation as a one-line row with the sender, which expands to the full text (#239). - **Project board.** Each project gets a persistent board of tasks and sub-tasks that you and your sessions share; every worktree of the project uses the same board. Open it from the project in the sidebar. A task records its owner, reviewer and creator, acceptance criteria, priority, dependencies, progress, and the owner's and reviewer's reports. Sessions read and update the board with four tools (`KanbanList`, `KanbanGet`, `KanbanCreate`, `KanbanUpdate`): they split work into sub-tasks, record progress, block a task with a question, submit their work and review it. The board notifies the sessions involved when they are assigned, when work is submitted, blocked, sent back, reset or cancelled, and when you comment. `StartSession` can start a session as a task's owner or reviewer. The board page has a board view and a hierarchy view, opens a task in the side panel, and lists what waits on you under "Needs me": blocked tasks, deliveries to accept and tasks whose owner session is gone. You approve every time a session creates the board, starts a session on a task, cancels a task, changes acceptance criteria it did not set, or makes itself a reviewer; only a task's creator or you choose its reviewer (#242). diff --git a/docs/README.md b/docs/README.md index f907457c..2baa8a8c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,6 +14,7 @@ - [computer-use](features/computer-use/tech-design.md): Computer Use through cua-driver, with its [decision records](features/computer-use/adr.md). - [kanban](features/kanban/README.md): a persistent project board shared by people and agent sessions (first version implemented on `feat/kanban`). - [performance](features/performance/optimization-report.md): performance audit report. + - [remote-backend](features/remote-backend/tech-design.md): remote serving mode, the server half of running the sidecar on a remote host behind an SSH tunnel. - [session-links](features/session-links/tech-design.md): sessions that start other sessions and message each other. - [session-state](features/session-state/tech-design.md): session state owned by the server. - [side-chat](features/side-chat/tech-design.md): side chats, forked from a session and shown as tabs in its side panel. diff --git a/docs/features/remote-backend/tech-design.md b/docs/features/remote-backend/tech-design.md new file mode 100644 index 00000000..610b9c4f --- /dev/null +++ b/docs/features/remote-backend/tech-design.md @@ -0,0 +1,102 @@ +# Remote serving mode + +Part of [RFC #24](https://github.com/GoDiao/dreamcoder/issues/24). This is the server half only: an opt-in mode that lets the sidecar run on a remote host and be reached through an SSH tunnel without trusting the tunnel. It does not add a remote connection to the desktop app, SSH orchestration, or a remote installer. It is not a complete remote backend and is not ready for production use: read "Not mitigated" before relying on it. + +## Why a mode is needed + +The sidecar treats a request as the local desktop app when it comes from a loopback address with no `Origin`, a loopback `Origin`, or `dreamcoder://localhost` (`classifyH5Request` in `src/server/h5AccessPolicy.ts`). Such requests need no token on `/api`, `/ws` and `/terminal`. + +An SSH local forward ends at the remote host's loopback interface, so every tunneled request, and every other process on that host, looks like the desktop app. SSH authenticates whoever opens the tunnel; it does not tell the sidecar which principal is calling. The agent's own shell commands are such a process. + +## What the mode does + +Start the server with `--remote-serving` or `SERVER_REMOTE_SERVING=1`. Without either, nothing changes. + +| Check | Effect | +| --- | --- | +| Startup | Refuses a non-loopback `--host`, and refuses `--auth-required` / `SERVER_AUTH_REQUIRED` together with the mode. `SERVER_REMOTE_SERVING` must be `1` or `0` (or empty); any other value, such as `true`, stops the server instead of leaving the mode off. | +| `Host` header | Must name a loopback host (`127.0.0.1`, `localhost`, `[::1]`). Anything else is refused with 403, before the URL is parsed. | +| Forwarding headers | `Forwarded`, `X-Forwarded-For/Host/Proto`, `X-Real-IP` and `Via` are refused with 403. | +| `/api/*`, `/ws/*` | The H5 access token is required for every request, whatever the address or `Origin`. `OPTIONS` preflights still reach the existing CORS handling. | +| H5 access not enabled | Operator routes answer 503. | +| `/api/h5-access/*` | Refused with 403, except `/api/h5-access/verify`. The token cannot be minted, rotated or read over HTTP. | +| `/terminal`, `/browser-host`, `/browser-mcp`, `/web-clone-browser*` | Refused with 403. A remote sidecar has no desktop browser host, and the terminal is not served in this version. | +| `/sdk/*` | Loopback, no `Origin`, and the per-session token, as before. No operator token. | +| `/proxy/*` | Loopback and no `Origin` (a browser can no longer reach it). No credential, as before. | +| Anything else | `GET`/`HEAD` only (the H5 bundle, `/health`, `/ui-pages/*`). Other methods get 403. | + +The H5 token is the only operator credential. The CLI process and the tools it starts never receive it: the server stores only its hash, and the CLI's environment is built from the server's own environment and the provider settings. + +## Supported setup and threat assumptions + +- One OS user owns the remote host's sidecar. Do not use a shared host. +- The only way in is an SSH local forward from the operator's machine. Do not put a reverse proxy in front. +- The adversary is a permission-gated agent, including one steered by prompt injection, and network peers without the token. The mode stops them approving their own permission prompts, changing a session's permission mode, opening a shell, or editing MCP configuration through the operator routes. + +## Mitigated by this change (covered by `src/server/__tests__/remote-serving.test.ts`) + +- Tokenless access to `/api` and `/ws` from loopback, from a tunnel, or with a desktop, loopback or foreign `Origin`. +- A wrong, empty, malformed, regenerated or hash-as-token credential. +- A browser page, or a DNS-rebinding page, reaching `/sdk` or `/proxy` or any operator route with a hostile `Host`. +- Operator routes answering while H5 access is off or after it is disabled. +- A non-loopback bind and a combination with `--auth-required`. +- Remote use of the H5 control plane, the terminal socket and the browser-host endpoints. + +## Not mitigated (known limits) + +These are documented, not fixed by this change. + +- **A server that ignores the mode fails open.** A build older than this change does not know `--remote-serving` and trusts the tunnel. The server's argument parser also ignores spellings it does not recognize (`--remote-serve`, `--remote-serving=true`), so a typo leaves the mode off without an error. Nothing enforces the check below automatically: you must run it yourself, every time, before using the server. +- **The `/sdk` session token is in the CLI's command line** (`--sdk-url …?token=…`). Any process of the same OS user can read it and send control requests (`session_start`, `session_send`, kanban) as that session. The approval for `StartSession` is checked in the CLI tool, not on the server. `session_start` has no permission-mode field and the new session inherits its parent's mode, so this does not raise a permission mode. +- **`/proxy` has no credential.** The CLI sends a placeholder key, so the route is protected only by loopback and the absence of `Origin`. A process on the host, or a reverse proxy that adds no forwarding header, can use the configured provider through it. +- **A valid token is full authority over the host account.** It reaches every session, any working directory, MCP `command` entries, and `bypassPermissions`. There is no per-client or per-session scope. +- **`GET /api/sessions/repository-context?workDir=…` adds any directory to the `/api/filesystem` allowlist.** The allowlist therefore limits nothing for a token holder; it exposes directory and file names and image files. +- **`/ui-pages/*` needs no credential.** The page address is the capability. Pages are served with `sandbox allow-scripts` and `connect-src 'none'`, so a page cannot reach the API. +- **Rejecting forwarding headers is a heuristic.** A proxy that adds none and rewrites `Host` to a loopback name is not detected. +- **No TLS and no rate limiting.** Traffic is plain HTTP inside the tunnel. +- **The agent can edit the sidecar's own settings files** if you approve a write there. + +## Setup + +On the remote host, enable H5 access once, then restart the server with the mode on. + +```bash +# terminal 1: start the server normally, on loopback only +bun run src/server/index.ts --host 127.0.0.1 --port 3456 + +# terminal 2: enable H5 access; the token is printed once and only its hash is stored +curl -s -X POST http://127.0.0.1:3456/api/h5-access/enable + +# stop the server in terminal 1 (Ctrl-C), then start it again in remote-serving mode +bun run src/server/index.ts --host 127.0.0.1 --port 3456 --remote-serving +``` + +Do this before any session is running: until the restart, the first server still trusts loopback. Provider keys and settings live on the remote host. + +On your machine, forward a local port to the remote loopback port. `-L` is the right direction; `-R` forwards the other way. + +```bash +ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:3456:127.0.0.1:3456 user@remote-host +``` + +## Verify before you send the token + +A server that ignores `--remote-serving` (an older build) treats the tunnel as trusted. Check before you use it: + +```bash +curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3456/api/status +``` + +It must print `401`. `200` means the server is not enforcing the mode (an older build, or a flag that was not recognized): stop and fix it before you use the server. With the token, the same request must return `200`: + +```bash +curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3456/api/status +``` + +## Rollback + +Restart without `--remote-serving` and without `SERVER_REMOTE_SERVING`. The mode stores nothing and changes no settings schema. + +## Not covered here + +The desktop app connecting to a remote sidecar, the SSH tunnel manager, reconnect and version negotiation, a remote terminal, and moving the `/sdk` token and the `StartSession` approval to the server are separate follow-ups. diff --git a/src/server/__tests__/remote-serving.test.ts b/src/server/__tests__/remote-serving.test.ts new file mode 100644 index 00000000..b519e17b --- /dev/null +++ b/src/server/__tests__/remote-serving.test.ts @@ -0,0 +1,464 @@ +import { afterEach, beforeEach, describe, expect, test } from 'bun:test' +import * as fs from 'node:fs/promises' +import * as os from 'node:os' +import * as path from 'node:path' +import { fileURLToPath } from 'node:url' +import { startServer } from '../index.js' +import { REMOTE_SERVING_ENV } from '../remoteServing.js' +import { conversationService } from '../services/conversationService.js' +import { H5AccessService } from '../services/h5AccessService.js' +import { ManagedSettingsService } from '../services/managedSettingsService.js' +import { ProviderService } from '../services/providerService.js' +import { peekSessionRuntime } from '../ws/sessionRuntime.js' + +type Booted = { http: string; ws: string; port: number } + +const ENV_KEYS = [REMOTE_SERVING_ENV, 'SERVER_AUTH_REQUIRED', 'DREAMCODER_CONFIG_DIR', 'CLAUDE_CLI_PATH', 'CLAUDE_H5_DIST_DIR', 'ANTHROPIC_API_KEY'] as const +const FORWARDING_HEADERS = ['Forwarded', 'X-Forwarded-For', 'X-Forwarded-Host', 'X-Forwarded-Proto', 'X-Real-IP', 'Via'] + +let server: ReturnType | undefined +let tmpDir = '' +let booted: Booted +let token = '' +let savedEnv: Record = {} +let savedServerPort = 3456 + +async function waitForHealth(url: string, attempts = 60): Promise { + for (let attempt = 0; attempt < attempts; attempt += 1) { + try { + const response = await fetch(`${url}/health`) + if (response.ok) return + } catch {} + await Bun.sleep(50) + } + throw new Error(`Timed out waiting for ${url}`) +} + +async function boot(options: { remoteServing: boolean; enableH5?: boolean; host?: string; rawEnv?: string }): Promise { + if (options.rawEnv !== undefined) process.env[REMOTE_SERVING_ENV] = options.rawEnv + else if (options.remoteServing) process.env[REMOTE_SERVING_ENV] = '1' + else delete process.env[REMOTE_SERVING_ENV] + if (options.enableH5 !== false) token = (await new H5AccessService().enable()).token + server = startServer(0, options.host ?? '127.0.0.1') + const port = server.port as number + booted = { http: `http://127.0.0.1:${port}`, ws: `ws://127.0.0.1:${port}`, port } + await waitForHealth(booted.http) + return booted +} + +function bearer(value: string): Record { + return { Authorization: `Bearer ${value}` } +} + +function upgradeHeaders(extra: Record = {}): Record { + return { Connection: 'Upgrade', Upgrade: 'websocket', ...extra } +} + +function request(pathname: string, init: RequestInit = {}): Promise { + return fetch(`${booted.http}${pathname}`, init) +} + +type SocketOutcome = { opened: boolean; closeCode: number | null; messages: Array> } + +function observeSocket( + url: string, + options: { onOpen?: (ws: WebSocket) => void; settleMs?: number; until?: (messages: Array>) => boolean } = {}, +): Promise { + return new Promise((resolve) => { + const outcome: SocketOutcome = { opened: false, closeCode: null, messages: [] } + const ws = new WebSocket(url) + let finished = false + const finish = () => { + if (finished) return + finished = true + clearTimeout(timer) + try { ws.close() } catch {} + resolve(outcome) + } + const timer = setTimeout(finish, options.settleMs ?? 1500) + ws.addEventListener('open', () => { + outcome.opened = true + options.onOpen?.(ws) + }) + ws.addEventListener('message', (event) => { + try { outcome.messages.push(JSON.parse(String(event.data))) } catch {} + if (options.until?.(outcome.messages)) finish() + }) + ws.addEventListener('close', (event) => { + outcome.closeCode = event.code + finish() + }) + ws.addEventListener('error', finish) + }) +} + +async function freePort(): Promise { + const probe = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') }) + const port = probe.port as number + probe.stop(true) + return port +} + +function spawnServerProcess(args: string[]) { + const env: Record = { ...process.env, DREAMCODER_CONFIG_DIR: tmpDir } + delete env[REMOTE_SERVING_ENV] + delete env.SERVER_AUTH_REQUIRED + return Bun.spawn(['bun', 'run', 'src/server/index.ts', ...args], { cwd: process.cwd(), env, stdout: 'ignore', stderr: 'ignore' }) +} + +async function storedTokenHash(): Promise { + const settings = await new ManagedSettingsService().readSettings() + return String((settings.h5Access as { tokenHash: string }).tokenHash) +} + +beforeEach(async () => { + tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'remote-serving-test-')) + savedEnv = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]])) + savedServerPort = ProviderService.getServerPort() + process.env.DREAMCODER_CONFIG_DIR = tmpDir + delete process.env.SERVER_AUTH_REQUIRED + delete process.env.ANTHROPIC_API_KEY + const dist = path.join(tmpDir, 'dist') + process.env.CLAUDE_H5_DIST_DIR = dist + await fs.mkdir(path.join(dist, 'assets'), { recursive: true }) + await fs.writeFile(path.join(dist, 'index.html'), 'H5 Shell', 'utf-8') + await fs.writeFile(path.join(dist, 'assets/app.js'), 'window.__h5 = true', 'utf-8') +}) + +afterEach(async () => { + server?.stop(true) + server = undefined + for (const sessionId of conversationService.getActiveSessions()) conversationService.stopSession(sessionId) + ProviderService.setServerPort(savedServerPort) + for (const key of ENV_KEYS) { + if (savedEnv[key] === undefined) delete process.env[key] + else process.env[key] = savedEnv[key] + } + await fs.rm(tmpDir, { recursive: true, force: true }) +}) + +describe('default mode is unchanged', () => { + test('loopback requests without a token keep working, which is what the deployment probe detects', async () => { + await boot({ remoteServing: false }) + expect((await request('/api/status')).status).toBe(200) + const outcome = await observeSocket(`${booted.ws}/ws/default-mode-session`) + expect(outcome.opened).toBe(true) + }) +}) + +describe('remote-serving operator surfaces', () => { + beforeEach(async () => { + await boot({ remoteServing: true }) + }) + + test('deployment probe: a tokenless request is refused on /api and /ws', async () => { + expect((await request('/api/status')).status).toBe(401) + expect((await request('/ws/probe-session', { headers: upgradeHeaders() })).status).toBe(401) + }) + + test.each([ + ['no Origin', {}], + ['desktop app origin', { Origin: 'dreamcoder://localhost' }], + ['loopback dev server origin', { Origin: 'http://localhost:5173' }], + ['loopback ip origin', { Origin: 'http://127.0.0.1:9' }], + ['foreign origin', { Origin: 'https://evil.example' }], + ])('a tokenless request is refused with %s', async (_label, headers) => { + expect((await request('/api/sessions', { headers })).status).toBe(401) + expect((await request('/api/status', { headers })).status).toBe(401) + expect((await request('/ws/some-session', { headers: upgradeHeaders(headers) })).status).toBe(401) + }) + + test('a valid operator token is accepted for HTTP and WebSocket', async () => { + expect((await request('/api/status', { headers: bearer(token) })).status).toBe(200) + const outcome = await observeSocket(`${booted.ws}/ws/operator-session?token=${token}`) + expect(outcome.opened).toBe(true) + expect(outcome.messages.some((message) => message.type === 'connected')).toBe(true) + }) + + test('a valid token with a loopback or desktop origin is accepted', async () => { + for (const origin of ['dreamcoder://localhost', 'http://127.0.0.1:4000']) { + const response = await request('/api/status', { headers: { ...bearer(token), Origin: origin } }) + expect(response.status).toBe(200) + } + }) + + test('wrong, empty, stored-hash and malformed credentials are refused', async () => { + const hash = await storedTokenHash() + const attempts: Array> = [ + bearer('wrong-token'), + bearer(hash), + { Authorization: 'Bearer' }, + { Authorization: 'Bearer ' }, + { Authorization: 'bearer' }, + { Authorization: token }, + { Authorization: `Basic ${token}` }, + { Authorization: `Bearer ${token}` }, + ] + for (const headers of attempts) { + expect((await request('/api/status', { headers })).status).toBe(401) + } + expect((await request(`/ws/x?token=${hash}`, { headers: upgradeHeaders() })).status).toBe(401) + expect((await request('/ws/x?token=', { headers: upgradeHeaders() })).status).toBe(401) + expect((await request('/api/status', { headers: bearer(token) })).status).toBe(200) + }) + + test('a regenerated token revokes the previous one', async () => { + const previous = token + const next = (await new H5AccessService().regenerateToken()).token + expect((await request('/api/status', { headers: bearer(previous) })).status).toBe(401) + expect((await request('/api/status', { headers: bearer(next) })).status).toBe(200) + }) + + test('the operator token is not stored in plaintext', async () => { + const settings = JSON.stringify(await new ManagedSettingsService().readSettings()) + expect(settings.includes(token)).toBe(false) + }) + + test('the H5 control plane cannot be used over HTTP, even with a valid token', async () => { + const hashBefore = await storedTokenHash() + for (const [method, pathname] of [ + ['GET', '/api/h5-access'], + ['PUT', '/api/h5-access'], + ['POST', '/api/h5-access/enable'], + ['POST', '/api/h5-access/regenerate'], + ['POST', '/api/h5-access/disable'], + ] as const) { + const response = await request(pathname, { method, headers: { ...bearer(token), 'Content-Type': 'application/json' }, body: method === 'PUT' ? '{}' : undefined }) + expect(`${method} ${pathname} ${response.status}`).toBe(`${method} ${pathname} 403`) + } + expect(await storedTokenHash()).toBe(hashBefore) + expect((await request('/api/h5-access/verify', { method: 'POST', headers: bearer(token) })).status).toBe(200) + expect((await request('/api/h5-access/verify', { method: 'POST' })).status).toBe(401) + }) + + test('the terminal socket is not served', async () => { + expect((await request('/terminal?cols=80&rows=24', { headers: upgradeHeaders(bearer(token)) })).status).toBe(403) + expect((await request(`/terminal?token=${token}`, { headers: upgradeHeaders() })).status).toBe(403) + }) + + test('browser host endpoints are not served', async () => { + expect((await request('/browser-host', { headers: upgradeHeaders() })).status).toBe(403) + expect((await request('/browser-mcp', { method: 'POST', headers: bearer(token) })).status).toBe(403) + expect((await request('/web-clone-browser', { method: 'POST', headers: bearer(token) })).status).toBe(403) + }) + + test('requests that carry forwarding headers are refused', async () => { + for (const header of FORWARDING_HEADERS) { + expect((await request('/health', { headers: { [header]: '203.0.113.9' } })).status).toBe(403) + expect((await request('/api/status', { headers: { ...bearer(token), [header]: '203.0.113.9' } })).status).toBe(403) + expect((await request('/', { headers: { [header]: '203.0.113.9' } })).status).toBe(403) + } + }) + + test('requests whose Host header is not a loopback name are refused', async () => { + const hostile = ['evil.example', 'evil.example:80', 'localhost.evil.example', '127.0.0.1.evil.example', '127.0.0.1@evil.example', 'evil.example@127.0.0.1', '127.0.0.1/evil'] + for (const host of hostile) { + expect(`${host} ${(await request('/health', { headers: { Host: host } })).status}`).toBe(`${host} 403`) + expect(`${host} ${(await request('/api/status', { headers: { ...bearer(token), Host: host } })).status}`).toBe(`${host} 403`) + expect(`${host} ${(await request('/proxy/v1/messages', { method: 'POST', headers: { Host: host }, body: '{}' })).status}`).toBe(`${host} 403`) + } + }) + + test.each([['127.0.0.1'], ['localhost'], ['[::1]']])('a loopback Host header (%s) is accepted', async (name) => { + const response = await request('/api/status', { headers: { ...bearer(token), Host: `${name}:${booted.port}` } }) + expect(response.status).toBe(200) + }) + + test('public bootstrap routes stay public and carry no operator data', async () => { + expect((await request('/health')).status).toBe(200) + const shell = await request('/') + expect(shell.status).toBe(200) + expect(await shell.text()).toContain('H5 Shell') + expect((await request('/assets/app.js')).status).toBe(200) + }) + + test('state-changing requests to unknown paths are refused', async () => { + for (const method of ['POST', 'PUT', 'DELETE', 'PATCH']) { + const response = await request('/not-a-route', { method, headers: bearer(token) }) + expect(response.status).toBe(403) + } + }) + + test('encoded and case-varied paths do not reach operator handlers', async () => { + for (const pathname of ['/%61pi/status', '//api/status', '/API/status', '/api%2Fstatus', '/./api/status']) { + const body = await (await request(pathname)).text() + expect(body.includes('"version"')).toBe(false) + } + }) + + test('a refused WebSocket upgrade allocates no session runtime', async () => { + const outcomes = await Promise.all( + Array.from({ length: 20 }, (_, index) => observeSocket(`${booted.ws}/ws/flood-${index}`, { settleMs: 500 })), + ) + expect(outcomes.every((outcome) => !outcome.opened)).toBe(true) + for (let index = 0; index < 20; index += 1) { + expect(peekSessionRuntime(`flood-${index}`)).toBeUndefined() + } + }) + + test('a permission response cannot resolve a request from another session', async () => { + const outcome = await observeSocket(`${booted.ws}/ws/session-b?token=${token}`, { + onOpen: (ws) => ws.send(JSON.stringify({ type: 'permission_response', requestId: 'request-from-session-a', allowed: true })), + }) + const error = outcome.messages.find((message) => message.type === 'error') + expect(error?.code).toBe('PERMISSION_REQUEST_EXPIRED') + }) + + test('a disallowed browser origin is still refused by CORS', async () => { + const preflight = await request('/api/status', { method: 'OPTIONS', headers: { Origin: 'https://evil.example', 'Access-Control-Request-Method': 'GET' } }) + expect(preflight.status).toBe(403) + }) + + test('tokens never reach the server log', async () => { + const captured: string[] = [] + const originals = { log: console.log, warn: console.warn, error: console.error, info: console.info } + const capture = (...args: unknown[]) => { captured.push(args.map(String).join(' ')) } + console.log = capture + console.warn = capture + console.error = capture + console.info = capture + try { + await request('/api/status', { headers: bearer(token) }) + await request('/api/status', { headers: bearer('wrong-token') }) + await observeSocket(`${booted.ws}/ws/log-session?token=${token}`) + await observeSocket(`${booted.ws}/ws/log-session?token=wrong-token`) + } finally { + Object.assign(console, originals) + } + const joined = captured.join('\n') + expect(joined.includes(token)).toBe(false) + expect(joined.includes('wrong-token')).toBe(false) + }) +}) + +describe('remote-serving internal principals', () => { + beforeEach(async () => { + await boot({ remoteServing: true }) + }) + + test('/sdk needs no operator token but still needs a session token', async () => { + const withoutToken = await observeSocket(`${booted.ws}/sdk/no-such-session`) + expect(withoutToken.opened).toBe(true) + expect(withoutToken.closeCode).toBe(1008) + const withOperatorToken = await observeSocket(`${booted.ws}/sdk/no-such-session?token=${token}`) + expect(withOperatorToken.closeCode).toBe(1008) + }) + + test('/sdk refuses browser origins', async () => { + for (const origin of ['http://localhost:3000', 'http://127.0.0.1:5173', 'dreamcoder://localhost', 'https://evil.example']) { + expect((await request('/sdk/some-session', { headers: upgradeHeaders({ Origin: origin }) })).status).toBe(403) + } + }) + + test('/proxy accepts only credential-less non-browser callers', async () => { + const post = (headers: Record) => request('/proxy/v1/messages', { method: 'POST', headers: { 'Content-Type': 'application/json', ...headers }, body: '{}' }) + expect((await post({})).status).not.toBe(403) + for (const origin of ['http://127.0.0.1:5173', 'http://localhost:3000', 'dreamcoder://localhost', 'https://evil.example']) { + expect((await post({ Origin: origin })).status).toBe(403) + } + }) + + test('a CLI session streams a turn using only its own session token', async () => { + process.env.CLAUDE_CLI_PATH = fileURLToPath(new URL('./fixtures/mock-sdk-cli.ts', import.meta.url)) + const providers = new ProviderService() + const provider = await providers.addProvider({ + presetId: 'custom', + name: 'Remote Serving Test Provider', + apiKey: 'key-remote-serving', + baseUrl: 'http://127.0.0.1:1/anthropic', + apiFormat: 'anthropic', + runtimeKind: 'anthropic_compatible', + models: [{ id: 'main' }, { id: 'sonnet' }, { id: 'opus' }, { id: 'haiku' }], + fastModel: 'haiku', + }) + await providers.activateProvider(provider.id) + + const outcome = await observeSocket(`${booted.ws}/ws/remote-serving-turn?token=${token}`, { + settleMs: 12000, + onOpen: (ws) => ws.send(JSON.stringify({ type: 'user_message', content: 'Hello from a remote operator' })), + until: (messages) => messages.some((message) => message.type === 'message_complete'), + }) + const types = outcome.messages.map((message) => message.type) + expect(types).toContain('content_delta') + expect(types).toContain('message_complete') + }, 20000) +}) + +describe('remote-serving command line', () => { + test('the --remote-serving flag turns the mode on', async () => { + token = (await new H5AccessService().enable()).token + const port = await freePort() + const child = spawnServerProcess(['--host', '127.0.0.1', '--port', String(port), '--remote-serving']) + try { + await waitForHealth(`http://127.0.0.1:${port}`, 200) + expect((await fetch(`http://127.0.0.1:${port}/api/status`)).status).toBe(401) + expect((await fetch(`http://127.0.0.1:${port}/api/status`, { headers: bearer(token) })).status).toBe(200) + } finally { + child.kill() + await child.exited + } + }, 30000) + + test('the flag with a non-loopback --host exits with an error and never listens', async () => { + const port = await freePort() + const child = spawnServerProcess(['--host', '0.0.0.0', '--port', String(port), '--remote-serving']) + const outcome = await Promise.race([child.exited, Bun.sleep(15000).then(() => 'timeout' as const)]) + if (outcome === 'timeout') child.kill() + expect(outcome).toBe(1) + await expect(fetch(`http://127.0.0.1:${port}/health`)).rejects.toThrow() + }, 30000) +}) + +describe('remote-serving startup guards', () => { + test('refuses to listen on a non-loopback address', async () => { + process.env[REMOTE_SERVING_ENV] = '1' + for (const host of ['0.0.0.0', '::', '192.168.1.10', 'example.com']) { + expect(() => startServer(0, host)).toThrow(/loopback/i) + } + }) + + test.each([['true'], ['yes'], ['on'], ['2'], [' 1']])('an unrecognized SERVER_REMOTE_SERVING value (%p) is an error, never a silent off', (value) => { + process.env[REMOTE_SERVING_ENV] = value + expect(() => startServer(0, '127.0.0.1')).toThrow(/SERVER_REMOTE_SERVING must be 1 or 0/) + }) + + test.each([['0'], ['']])('SERVER_REMOTE_SERVING=%p leaves the mode off', async (value) => { + await boot({ remoteServing: false, rawEnv: value }) + expect((await request('/api/status')).status).toBe(200) + }) + + test('refuses to combine with explicit server auth', async () => { + process.env[REMOTE_SERVING_ENV] = '1' + process.env.SERVER_AUTH_REQUIRED = '1' + expect(() => startServer(0, '127.0.0.1')).toThrow(/auth-required|SERVER_AUTH_REQUIRED/i) + }) + + test('refuses every operator request while H5 access is not enabled', async () => { + await boot({ remoteServing: true, enableH5: false }) + expect((await request('/api/status')).status).toBe(503) + expect((await request('/api/status', { headers: bearer('anything') })).status).toBe(503) + expect((await request('/ws/not-ready', { headers: upgradeHeaders() })).status).toBe(503) + expect((await request('/health')).status).toBe(200) + }) + + test('disabling H5 access closes the surface at once', async () => { + await boot({ remoteServing: true }) + expect((await request('/api/status', { headers: bearer(token) })).status).toBe(200) + await new H5AccessService().disable() + expect((await request('/api/status', { headers: bearer(token) })).status).toBe(503) + }) +}) + +describe('rollback', () => { + test('restarting without the flag restores default behavior and leaves settings untouched', async () => { + await boot({ remoteServing: true }) + const before = JSON.stringify(await new ManagedSettingsService().readSettings()) + await request('/api/status') + await request('/api/status', { headers: bearer(token) }) + server?.stop(true) + server = undefined + expect(JSON.stringify(await new ManagedSettingsService().readSettings())).toBe(before) + await boot({ remoteServing: false, enableH5: false }) + expect((await request('/api/status')).status).toBe(200) + }) +}) diff --git a/src/server/index.ts b/src/server/index.ts index 735def55..a838c51a 100644 --- a/src/server/index.ts +++ b/src/server/index.ts @@ -24,6 +24,7 @@ import { handleWebCloneRoute } from './browserHost/webClone.js' import { WEB_CLONE_BROWSER_PATH } from './browserHost/names.js' import { startBrowserHostTokenReader } from './browserHost/stdinToken.js' import { H5AccessService } from './services/h5AccessService.js' +import { assertRemoteServingStartup, guardRemoteServing, isRemoteServingRequested, refuseUnlessLoopbackHost } from './remoteServing.js' import { setServerEndpoint } from './ws/sessionRuntime.js' function readArgValue(flag: string): string | undefined { @@ -43,12 +44,13 @@ function resolveServerOptions() { const host = readArgValue('--host') || process.env.SERVER_HOST || '127.0.0.1' const cliPath = readArgValue('--cli-path') const authRequired = hasArgFlag('--auth-required') + const remoteServing = hasArgFlag('--remote-serving') if (cliPath) { process.env.CLAUDE_CLI_PATH = cliPath } - return { port, host, authRequired } + return { port, host, authRequired, remoteServing } } const SERVER_OPTIONS = resolveServerOptions() @@ -144,6 +146,8 @@ export function startServer(port = PORT, host = HOST) { const forceAuth = SERVER_OPTIONS.authRequired || process.env.SERVER_AUTH_REQUIRED === '1' + const remoteServing = isRemoteServingRequested(SERVER_OPTIONS.remoteServing) + if (remoteServing) assertRemoteServingStartup({ host, authRequired: forceAuth }) const h5AccessService = new H5AccessService() let server: ReturnType> @@ -155,12 +159,20 @@ export function startServer(port = PORT, host = HOST) { idleTimeout: 60, async fetch(req, server) { + if (remoteServing) { + const hostRefusal = refuseUnlessLoopbackHost(req) + if (hostRefusal) return hostRefusal + } await ensurePersistentStorageUpgraded() const url = new URL(req.url) const origin = req.headers.get('Origin') const clientAddress = server.requestIP(req)?.address ?? null const h5RequestContext = { clientAddress } const h5Settings = await h5AccessService.getSettings() + if (remoteServing) { + const refusal = await guardRemoteServing({ request: req, url, clientAddress, h5Enabled: h5Settings.enabled }) + if (refusal) return refusal + } const h5PublicOrigin = originFromUrl(h5Settings.publicBaseUrl) const cors = await resolveCors(origin, url.origin, { h5Enabled: h5Settings.enabled, @@ -426,6 +438,7 @@ export function startServer(port = PORT, host = HOST) { const mem = process.memoryUsage() console.log(`[mem:sidecar] server:startup rss=${(mem.rss/1024/1024).toFixed(1)}MB heapUsed=${(mem.heapUsed/1024/1024).toFixed(1)}MB`) console.log(`[Server] Claude Code API server running at http://${host}:${port}`) + if (remoteServing) console.log('[Server] Remote-serving mode: every /api and /ws request needs the H5 access token') return server } diff --git a/src/server/remoteServing.ts b/src/server/remoteServing.ts new file mode 100644 index 00000000..239762b0 --- /dev/null +++ b/src/server/remoteServing.ts @@ -0,0 +1,102 @@ +import { BROWSER_MCP_PATH, WEB_CLONE_BROWSER_PATH } from './browserHost/names.js' +import { BROWSER_HOST_PATH } from './browserHost/protocol.js' +import { isLocalNonBrowserRequest, isLoopbackHost } from './h5AccessPolicy.js' +import { requireH5Token } from './middleware/auth.js' + +export const REMOTE_SERVING_ENV = 'SERVER_REMOTE_SERVING' + +const FORWARDING_HEADERS = ['forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'via'] +const H5_ACCESS_PATH = '/api/h5-access' +const H5_VERIFY_PATH = '/api/h5-access/verify' +const WEB_CLONE_PREFIX = `${WEB_CLONE_BROWSER_PATH}/` + +export type RemoteServingRequest = { + request: Request + url: URL + clientAddress: string | null + h5Enabled: boolean +} + +export function isRemoteServingRequested(flagPresent: boolean): boolean { + const value = process.env[REMOTE_SERVING_ENV] + if (value !== undefined && value !== '' && value !== '0' && value !== '1') { + throw new Error(`${REMOTE_SERVING_ENV} must be 1 or 0, not "${value}".`) + } + return flagPresent || value === '1' +} + +export function assertRemoteServingStartup({ host, authRequired }: { host: string; authRequired: boolean }): void { + if (!isLoopbackHost(host)) { + throw new Error(`Remote-serving mode listens on a loopback address only, not "${host}". Reach it through an SSH tunnel.`) + } + if (authRequired) { + throw new Error('Remote-serving mode cannot be combined with --auth-required or SERVER_AUTH_REQUIRED.') + } +} + +function hasLoopbackHost(request: Request): boolean { + const host = request.headers.get('host') + if (!host || !/^[^\s@/\\?#]+$/.test(host)) return false + try { + return isLoopbackHost(new URL(`http://${host}`).hostname) + } catch { + return false + } +} + +export function refuseUnlessLoopbackHost(request: Request): Response | null { + return hasLoopbackHost(request) + ? null + : refuse(403, 'Remote-serving mode only answers requests addressed to a loopback host name.') +} + +function refuse(status: 403 | 503, message: string): Response { + return Response.json({ error: status === 403 ? 'Forbidden' : 'Service Unavailable', message }, { status }) +} + +function isBrowserHostPath(pathname: string): boolean { + return pathname === BROWSER_HOST_PATH || + pathname === BROWSER_MCP_PATH || + pathname === WEB_CLONE_BROWSER_PATH || + pathname.startsWith(WEB_CLONE_PREFIX) +} + +function isOperatorPath(pathname: string): boolean { + return pathname.startsWith('/api/') || pathname.startsWith('/ws/') +} + +export async function guardRemoteServing({ request, url, clientAddress, h5Enabled }: RemoteServingRequest): Promise { + if (FORWARDING_HEADERS.some((name) => request.headers.has(name))) { + return refuse(403, 'Remote-serving mode does not accept proxied requests.') + } + + const { pathname } = url + + if (pathname === '/health') return null + + if (pathname === '/terminal' || isBrowserHostPath(pathname)) { + return refuse(403, 'This endpoint is not available in remote-serving mode.') + } + + if (pathname.startsWith('/sdk/') || pathname.startsWith('/proxy/')) { + return isLocalNonBrowserRequest(clientAddress, request.headers.get('Origin')) + ? null + : refuse(403, 'This endpoint only accepts local, non-browser callers.') + } + + if (pathname.startsWith(H5_ACCESS_PATH) && pathname !== H5_VERIFY_PATH) { + return refuse(403, 'H5 access settings cannot be changed in remote-serving mode.') + } + + if (isOperatorPath(pathname)) { + if (request.method === 'OPTIONS') return null + if (!h5Enabled) { + return refuse(503, 'Remote-serving mode needs H5 access to be enabled with an access token.') + } + return requireH5Token(request, pathname.startsWith('/ws/') ? url.searchParams.get('token') : null) + } + + if (request.method === 'GET' || request.method === 'HEAD') return null + + return refuse(403, 'This request is not accepted in remote-serving mode.') +}