diff --git a/README.md b/README.md index d14fc05e..16b3ff10 100644 --- a/README.md +++ b/README.md @@ -728,6 +728,8 @@ rollback. Do not rely on a pre-existing mutable `openswarm:latest` image. Without `OPENSWARM_WEB_TOKEN` the dashboard binds only inside the container — an unauthenticated all-interfaces bind is refused by design — so the published port answers nothing while the daemon itself keeps running. With the token set, browser/API access from the host sends it as the `X-OpenSwarm-Token` header (`/api/health` stays token-less). +**Web terminal (opt-in).** `OPENSWARM_WEB_TERMINAL=1` adds a `/terminal` page: a `bash -l` shell inside the daemon's container (same uid, cwd `OPENSWARM_WORKSPACE_ROOT`, default `/work`). Unset, neither the page nor its WebSocket exists. The upgrade passes the same gate as API mutations (web token, or loopback / trusted Tailscale with a same-host `Origin`); the browser sends the token as a `Sec-WebSocket-Protocol` entry, never in the URL. At most 4 sessions, each closed after 15 minutes without input; starts and stops are logged with the peer address. **Terminal access is access to the container's environment, including every token the daemon holds** — enable it only where the web gate already limits access to the operator. + The compose file wires the persistent and local-data mounts that matter: | Mount | Purpose | diff --git a/docker-compose.yml b/docker-compose.yml index b40e6f36..a39cb2e3 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -25,6 +25,10 @@ services: # web UI writes through a second mount of the same host directory. - OPENSWARM_WAREHOUSE_ROOT=/warehouse - OPENSWARM_WAREHOUSE_WRITE_ROOT=/warehouse-rw + # Web virtual terminal (/terminal): a bash shell INSIDE this container for + # any authorized web client. Off unless set to 1. Whoever can open it can + # read this container's environment, including every token above. + - OPENSWARM_WEB_TERMINAL=${OPENSWARM_WEB_TERMINAL:-} # Provider/API keys come from .env (see env_file) or the shell: # LINEAR_API_KEY, LINEAR_TEAM_ID, DISCORD_TOKEN, DISCORD_CHANNEL_ID, # ATLASCLOUD_API_KEY, OPENROUTER_API_KEY, ... diff --git a/package-lock.json b/package-lock.json index b030c2d3..9ad2bae5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -36,6 +36,7 @@ "nanoid": "^5.1.7", "react": "^19.2.7", "undici": "^6.28.0", + "ws": "^8.23.0", "yaml": "^2.8.2", "zod": "^4.3.6" }, @@ -45,7 +46,10 @@ "devDependencies": { "@types/node": "^22.0.0", "@types/react": "^19.2.17", + "@types/ws": "^8.18.2", "@vitest/coverage-v8": "^4.0.18", + "@xterm/addon-fit": "^0.11.0", + "@xterm/xterm": "^6.0.0", "bun-types": "^1.1.0", "ink-testing-library": "^4.0.0", "jsdom": "^26.1.0", @@ -57,6 +61,9 @@ }, "engines": { "node": ">=22" + }, + "optionalDependencies": { + "node-pty": "^1.1.0" } }, "node_modules/@alcalzone/ansi-tokenize": { @@ -2941,9 +2948,9 @@ "license": "MIT" }, "node_modules/@types/ws": { - "version": "8.18.1", - "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz", - "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==", + "version": "8.18.2", + "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.2.tgz", + "integrity": "sha512-67MQl+fpWKVTT1NYdnmo3U4sc/xPo/zQBncVnI74qmQa0z/b+1g6iYqNmGCPbxO+zz2aklb08a0oHfegiVd0/w==", "license": "MIT", "dependencies": { "@types/node": "*" @@ -3184,6 +3191,23 @@ "node": ">=18.0.0" } }, + "node_modules/@xterm/addon-fit": { + "version": "0.11.0", + "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.11.0.tgz", + "integrity": "sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==", + "dev": true, + "license": "MIT" + }, + "node_modules/@xterm/xterm": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.0.0.tgz", + "integrity": "sha512-TQwDdQGtwwDt+2cgKDLn0IRaSxYu1tSUjgKarSDkUM0ZNiSRXFpjxEsvc/Zgc5kq5omJ+V0a8/kIM2WD3sMOYg==", + "dev": true, + "license": "MIT", + "workspaces": [ + "addons/*" + ] + }, "node_modules/accepts": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz", @@ -6034,6 +6058,13 @@ "node": ">=10" } }, + "node_modules/node-addon-api": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz", + "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==", + "license": "MIT", + "optional": true + }, "node_modules/node-emoji": { "version": "2.2.0", "resolved": "https://registry.npmjs.org/node-emoji/-/node-emoji-2.2.0.tgz", @@ -6069,6 +6100,17 @@ } } }, + "node_modules/node-pty": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/node-pty/-/node-pty-1.1.0.tgz", + "integrity": "sha512-20JqtutY6JPXTUnL0ij1uad7Qe1baT46lyolh2sSENDd4sTzKZ4nmAFkeAARDKwmlLjPx6XKRlwRUxwjOy+lUg==", + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "dependencies": { + "node-addon-api": "^7.1.0" + } + }, "node_modules/nwsapi": { "version": "2.2.24", "resolved": "https://registry.npmjs.org/nwsapi/-/nwsapi-2.2.24.tgz", @@ -7955,9 +7997,9 @@ "license": "ISC" }, "node_modules/ws": { - "version": "8.21.0", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", - "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", + "version": "8.23.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.23.0.tgz", + "integrity": "sha512-wCkmX8QMOrKjgO8HW2WyDbTSGeqkocxgDzS9iR79rEAexty6/2qzilx3Ag8Tqf9ykop3irLKle0MtVn5qjVnoQ==", "license": "MIT", "engines": { "node": ">=10.0.0" diff --git a/package.json b/package.json index 7a9b3fd9..c2a69630 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,7 @@ "dev": "node --env-file=.env --import=tsx src/index.ts", "prestart": "pkill -f 'dist/index.js' 2>/dev/null || true", "build": "tsc", - "postbuild": "chmod +x dist/cli.js && node -e \"const fs=require('node:fs');fs.rmSync('dist/web-static',{recursive:true,force:true});fs.cpSync('web/static','dist/web-static',{recursive:true})\"", + "postbuild": "chmod +x dist/cli.js && node -e \"const fs=require('node:fs');fs.rmSync('dist/web-static',{recursive:true,force:true});fs.cpSync('web/static','dist/web-static',{recursive:true})\" && node scripts/copy-web-vendor.mjs", "start": "node --env-file=.env dist/index.js", "stop": "pkill -f 'node --env-file=.env.*openswarm' 2>/dev/null || echo 'No process running'", "lint": "oxlint src/ web/static/js/", @@ -73,13 +73,17 @@ "nanoid": "^5.1.7", "react": "^19.2.7", "undici": "^6.28.0", + "ws": "^8.23.0", "yaml": "^2.8.2", "zod": "^4.3.6" }, "devDependencies": { "@types/node": "^22.0.0", "@types/react": "^19.2.17", + "@types/ws": "^8.18.2", "@vitest/coverage-v8": "^4.0.18", + "@xterm/addon-fit": "^0.11.0", + "@xterm/xterm": "^6.0.0", "bun-types": "^1.1.0", "ink-testing-library": "^4.0.0", "jsdom": "^26.1.0", @@ -97,5 +101,8 @@ "undici": "^6.28.0", "adm-zip": "^0.6.1", "sharp": "^0.35.0" + }, + "optionalDependencies": { + "node-pty": "^1.1.0" } } diff --git a/scripts/copy-web-vendor.mjs b/scripts/copy-web-vendor.mjs new file mode 100644 index 00000000..7223c44a --- /dev/null +++ b/scripts/copy-web-vendor.mjs @@ -0,0 +1,25 @@ +// Copy browser-side vendor files (xterm.js for the opt-in web terminal, +// AGT-4002) into dist/web-static/vendor. The dashboard loads no third-party +// CDN, so the terminal page needs these served from the daemon itself. +// Runs from postbuild after web/static has been copied. +import { copyFileSync, existsSync, mkdirSync } from 'node:fs'; +import { join } from 'node:path'; + +const target = join('dist', 'web-static', 'vendor', 'xterm'); +const files = [ + ['node_modules/@xterm/xterm/lib/xterm.js', 'xterm.js'], + ['node_modules/@xterm/xterm/css/xterm.css', 'xterm.css'], + ['node_modules/@xterm/addon-fit/lib/addon-fit.js', 'addon-fit.js'], +]; + +mkdirSync(target, { recursive: true }); +let missing = 0; +for (const [from, name] of files) { + if (!existsSync(from)) { + missing += 1; + console.warn(`[copy-web-vendor] missing ${from}; the web terminal page will not load`); + continue; + } + copyFileSync(from, join(target, name)); +} +if (missing === 0) console.log(`[copy-web-vendor] ${files.length} files -> ${target}`); diff --git a/src/support/staticAssets.ts b/src/support/staticAssets.ts index 3c03790c..70e8648e 100644 --- a/src/support/staticAssets.ts +++ b/src/support/staticAssets.ts @@ -154,6 +154,11 @@ export async function readUsageShell(): Promise { return readShellFile('usage.html'); } +/** The opt-in web terminal shell (AGT-4002); routed only when OPENSWARM_WEB_TERMINAL=1. */ +export async function readTerminalShell(): Promise { + return readShellFile('terminal.html'); +} + /** The /app entry document, or null when assets are not present. */ export async function readAppShell(): Promise { return readShellFile('app.html'); diff --git a/src/support/terminalServer.test.ts b/src/support/terminalServer.test.ts new file mode 100644 index 00000000..961383d5 --- /dev/null +++ b/src/support/terminalServer.test.ts @@ -0,0 +1,265 @@ +// AGT-4002: the web terminal is a remote shell, so the tests pin the gate +// first — disabled means absent, unauthorized upgrades are destroyed, a +// foreign Origin cannot ride loopback trust — then the session cap, idle +// timeout and cleanup. No native addon is needed: the pty is injected. + +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { createServer, type IncomingMessage, type Server } from 'node:http'; +import type { AddressInfo } from 'node:net'; +import WebSocket from 'ws'; +import { + CLOSE_TRY_AGAIN_LATER, + SessionLimiter, + TERMINAL_PROTOCOL, + TERMINAL_WS_PATH, + TOKEN_PROTOCOL_PREFIX, + attachTerminalServer, + authorizeTerminalUpgrade, + extractSubprotocolToken, + isWebTerminalEnabled, + parseClientMessage, + startOptionalWebTerminal, + stopOptionalWebTerminal, + type TerminalPty, +} from './terminalServer.js'; +import { tryServePageShell } from './webAppRoutes.js'; + +const tokenProtocol = (token: string) => TOKEN_PROTOCOL_PREFIX + Buffer.from(token).toString('base64url'); + +function fakeReq(opts: { + remote: string; + local?: string; + origin?: string; + host?: string; + protocols?: string[]; + headers?: Record; +}): IncomingMessage { + return { + headers: { + host: opts.host ?? '127.0.0.1:3847', + ...(opts.origin ? { origin: opts.origin } : {}), + ...(opts.protocols ? { 'sec-websocket-protocol': opts.protocols.join(', ') } : {}), + ...opts.headers, + }, + socket: { remoteAddress: opts.remote, localAddress: opts.local ?? '127.0.0.1' }, + } as unknown as IncomingMessage; +} + +let savedEnv: NodeJS.ProcessEnv; +beforeEach(() => { + savedEnv = { ...process.env }; + delete process.env.OPENSWARM_WEB_TOKEN; + delete process.env.OPENSWARM_TRUST_TAILSCALE; + delete process.env.OPENSWARM_WEB_TERMINAL; +}); +afterEach(() => { + process.env = savedEnv; + stopOptionalWebTerminal(); +}); + +describe('opt-in', () => { + it('is enabled only by OPENSWARM_WEB_TERMINAL=1', () => { + expect(isWebTerminalEnabled({})).toBe(false); + expect(isWebTerminalEnabled({ OPENSWARM_WEB_TERMINAL: 'true' })).toBe(false); + expect(isWebTerminalEnabled({ OPENSWARM_WEB_TERMINAL: '1' })).toBe(true); + }); + + it('registers no upgrade handler and no /terminal route when unset', async () => { + const server = createServer(); + await startOptionalWebTerminal(server); + expect(server.listenerCount('upgrade')).toBe(0); + + const res = { writeHead: vi.fn(), end: vi.fn() }; + expect(await tryServePageShell(res as never, '/terminal')).toBe(false); + expect(res.writeHead).not.toHaveBeenCalled(); + }); + + it('registers both when set', async () => { + process.env.OPENSWARM_WEB_TERMINAL = '1'; + const server = createServer(); + await startOptionalWebTerminal(server); + expect(server.listenerCount('upgrade')).toBe(1); + + const res = { writeHead: vi.fn(), end: vi.fn() }; + expect(await tryServePageShell(res as never, '/terminal')).toBe(true); + expect(res.writeHead).toHaveBeenCalledWith(200, expect.anything()); + }); +}); + +describe('protocol parsing', () => { + it('accepts input and clamped resize frames', () => { + expect(parseClientMessage('{"type":"input","data":"ls\\r"}')).toEqual({ type: 'input', data: 'ls\r' }); + expect(parseClientMessage('{"type":"resize","cols":120.7,"rows":9999}')).toEqual({ type: 'resize', cols: 120, rows: 200 }); + }); + + it('drops malformed frames instead of throwing', () => { + for (const raw of ['not json', 'null', '[]', '{"type":"exec"}', '{"type":"input","data":5}', + '{"type":"resize","cols":0,"rows":10}', '{"type":"resize","cols":"80","rows":24}', + JSON.stringify({ type: 'input', data: 'x'.repeat(70 * 1024) })]) { + expect(parseClientMessage(raw)).toBeNull(); + } + }); + + it('reads the token from a subprotocol entry only', () => { + expect(extractSubprotocolToken(fakeReq({ remote: '10.0.0.5', protocols: [TERMINAL_PROTOCOL, tokenProtocol('s3cret')] }))).toBe('s3cret'); + expect(extractSubprotocolToken(fakeReq({ remote: '10.0.0.5', protocols: [TERMINAL_PROTOCOL] }))).toBeNull(); + }); +}); + +describe('upgrade authorization', () => { + it('allows loopback with no Origin or a same-host Origin, like the mutation gate', () => { + expect(authorizeTerminalUpgrade(fakeReq({ remote: '127.0.0.1' }))).toBe(true); + expect(authorizeTerminalUpgrade(fakeReq({ remote: '127.0.0.1', origin: 'http://127.0.0.1:3847' }))).toBe(true); + }); + + it('refuses a foreign Origin even from loopback (cross-site WebSocket hijack)', () => { + expect(authorizeTerminalUpgrade(fakeReq({ remote: '127.0.0.1', origin: 'http://evil.example' }))).toBe(false); + expect(authorizeTerminalUpgrade(fakeReq({ remote: '127.0.0.1', origin: 'http://localhost:9999' }))).toBe(false); + }); + + it('refuses a foreign Origin even with a valid token', () => { + process.env.OPENSWARM_WEB_TOKEN = 's3cret'; + expect(authorizeTerminalUpgrade(fakeReq({ + remote: '10.0.0.5', origin: 'http://evil.example', protocols: [TERMINAL_PROTOCOL, tokenProtocol('s3cret')], + }))).toBe(false); + }); + + it('refuses a remote peer without a credential', () => { + process.env.OPENSWARM_WEB_TOKEN = 's3cret'; + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', host: '10.0.0.1:3847' }))).toBe(false); + }); + + it('accepts a remote peer with the token as a header or as a subprotocol, and only the right token', () => { + process.env.OPENSWARM_WEB_TOKEN = 's3cret'; + const host = '10.0.0.1:3847'; + const origin = 'http://10.0.0.1:3847'; + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', host, headers: { 'x-openswarm-token': 's3cret' } }))).toBe(true); + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', host, protocols: [TERMINAL_PROTOCOL, tokenProtocol('s3cret')] }))).toBe(true); + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', host, protocols: [TERMINAL_PROTOCOL, tokenProtocol('wrong')] }))).toBe(false); + // A remote browser on a page this daemon served: the token decides. + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', host, origin, protocols: [TERMINAL_PROTOCOL, tokenProtocol('s3cret')] }))).toBe(true); + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', host, origin, protocols: [TERMINAL_PROTOCOL] }))).toBe(false); + // Same host, different port: another service on that host is not this daemon. + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', host, origin: 'http://10.0.0.1:8080', protocols: [TERMINAL_PROTOCOL, tokenProtocol('s3cret')] }))).toBe(false); + }); + + it('refuses a subprotocol token when no web token is configured', () => { + expect(authorizeTerminalUpgrade(fakeReq({ remote: '10.0.0.5', protocols: [TERMINAL_PROTOCOL, tokenProtocol('')] }))).toBe(false); + }); +}); + +// ---- Live sessions over a real HTTP server and ws client, fake pty ---- + +class FakePty implements TerminalPty { + written: string[] = []; + sizes: Array<[number, number]> = []; + killed = false; + #data: Array<(d: string) => void> = []; + #exit: Array<(e: { exitCode: number }) => void> = []; + onData(l: (d: string) => void) { this.#data.push(l); } + onExit(l: (e: { exitCode: number }) => void) { this.#exit.push(l); } + write(d: string) { this.written.push(d); } + resize(c: number, r: number) { this.sizes.push([c, r]); } + kill() { this.killed = true; } + emit(d: string) { for (const l of this.#data) l(d); } + exit() { for (const l of this.#exit) l({ exitCode: 0 }); } +} + +describe('sessions', () => { + let server: Server; + let detach: () => void; + let port: number; + let ptys: FakePty[]; + let limiter: SessionLimiter; + + async function start(opts: { max?: number; idleMs?: number } = {}) { + ptys = []; + limiter = new SessionLimiter(opts.max ?? 4); + server = createServer((_req, res) => { res.writeHead(404); res.end(); }); + detach = await attachTerminalServer(server, { + limiter, + idleMs: opts.idleMs ?? 60_000, + log: () => {}, + spawnPty: () => { const p = new FakePty(); ptys.push(p); return p; }, + }); + await new Promise((r) => server.listen(0, '127.0.0.1', r)); + port = (server.address() as AddressInfo).port; + } + + afterEach(async () => { + detach?.(); + await new Promise((r) => server?.close(() => r())); + }); + + const open = (headers: Record = {}, path = TERMINAL_WS_PATH) => + new WebSocket(`ws://127.0.0.1:${port}${path}`, [TERMINAL_PROTOCOL], { headers }); + + const closed = (ws: WebSocket) => new Promise((r) => ws.on('close', (code) => r(code))); + const rejected = (ws: WebSocket) => new Promise((r) => { + ws.on('unexpected-response', (_req, res) => r(res.statusCode ?? 0)); + ws.on('error', () => r(-1)); + }); + + it('destroys an upgrade carrying a foreign Origin with 401', async () => { + await start(); + expect(await rejected(open({ Origin: 'http://evil.example' }))).toBe(401); + expect(ptys).toHaveLength(0); + }); + + it('does not accept upgrades on other paths', async () => { + await start(); + expect(await rejected(open({}, '/api/events'))).toBe(404); + }); + + it('relays output, input and resize, and kills the shell when the socket closes', async () => { + await start(); + const ws = open(); + await new Promise((r) => ws.on('open', () => r())); + expect(ws.protocol).toBe(TERMINAL_PROTOCOL); + await vi.waitFor(() => expect(ptys).toHaveLength(1)); + + const got = new Promise((r) => ws.once('message', (d) => r(String(d)))); + ptys[0].emit('hello\r\n'); + expect(await got).toBe('hello\r\n'); + + ws.send(JSON.stringify({ type: 'input', data: 'ls\r' })); + ws.send(JSON.stringify({ type: 'resize', cols: 100, rows: 30 })); + ws.send('garbage'); + await vi.waitFor(() => expect(ptys[0].sizes).toEqual([[100, 30]])); + expect(ptys[0].written).toEqual(['ls\r']); + + ws.close(); + await vi.waitFor(() => expect(ptys[0].killed).toBe(true)); + expect(limiter.active).toBe(0); + }); + + it('closes a session over the cap with 1013', async () => { + await start({ max: 1 }); + const first = open(); + await new Promise((r) => first.on('open', () => r())); + const second = open(); + expect(await closed(second)).toBe(CLOSE_TRY_AGAIN_LATER); + expect(ptys).toHaveLength(1); + first.close(); + }); + + it('closes an idle session and kills its shell', async () => { + await start({ idleMs: 80 }); + const ws = open(); + const code = closed(ws); + expect(await code).toBe(1000); + await vi.waitFor(() => expect(ptys[0]?.killed).toBe(true)); + expect(limiter.active).toBe(0); + }); + + it('closes the socket when the shell exits', async () => { + await start(); + const ws = open(); + await new Promise((r) => ws.on('open', () => r())); + await vi.waitFor(() => expect(ptys).toHaveLength(1)); + const code = closed(ws); + ptys[0].exit(); + expect(await code).toBe(1000); + expect(limiter.active).toBe(0); + }); +}); diff --git a/src/support/terminalServer.ts b/src/support/terminalServer.ts new file mode 100644 index 00000000..24fb7c9f --- /dev/null +++ b/src/support/terminalServer.ts @@ -0,0 +1,331 @@ +// ============================================ +// OpenSwarm - Web virtual terminal (AGT-4002) +// ============================================ +// +// A browser shell into the daemon's own container, for operating a remote +// daemon (vela) without SSH. It is a remote shell, so: +// +// - It exists only when OPENSWARM_WEB_TERMINAL=1. Unset, neither the /terminal +// page nor the upgrade handler is registered. +// - The WebSocket upgrade never enters web.ts's request handler, so none of the +// HTTP gates run on it. authorizeTerminalUpgrade() applies the mutation gate +// from webAuth.ts explicitly, plus a same-host Origin check: browsers do not +// apply CORS to WebSockets, and loopback is trusted, so without the Origin +// check any page open in the operator's browser could open a shell. +// - A browser cannot set headers on a WebSocket, so the web token travels as a +// Sec-WebSocket-Protocol entry (`openswarm.token.`), never in the +// URL. The server echoes only the plain protocol name back. +// - At most MAX_SESSIONS shells at once, each closed after IDLE_MS without +// input, and every start/stop is logged with the peer address. +// +// Anyone who can open this terminal can read the container's environment, +// including every token the daemon holds. + +import type { IncomingMessage, Server } from 'node:http'; +import type { Duplex } from 'node:stream'; +import { existsSync } from 'node:fs'; +import { homedir } from 'node:os'; +import { getEffectivePort, hasValidWebToken, isAuthorizedMutation, isTrustedLocalOrigin } from './webAuth.js'; + +export const TERMINAL_PAGE_PATH = '/terminal'; +export const TERMINAL_WS_PATH = '/terminal/ws'; +export const TERMINAL_PROTOCOL = 'openswarm.terminal.v1'; +export const TOKEN_PROTOCOL_PREFIX = 'openswarm.token.'; +export const MAX_SESSIONS = 4; +export const IDLE_MS = 15 * 60_000; +/** WebSocket close code "Try Again Later", sent when the session cap is reached. */ +export const CLOSE_TRY_AGAIN_LATER = 1013; +const MAX_INPUT_BYTES = 64 * 1024; +const MAX_COLS = 500; +const MAX_ROWS = 200; + +export function isWebTerminalEnabled(env: NodeJS.ProcessEnv = process.env): boolean { + return env.OPENSWARM_WEB_TERMINAL === '1'; +} + +// ---- Protocol ---- + +export type ClientMessage = + | { type: 'input'; data: string } + | { type: 'resize'; cols: number; rows: number }; + +function clampDimension(value: unknown, max: number): number | null { + if (typeof value !== 'number' || !Number.isFinite(value)) return null; + const n = Math.trunc(value); + return n >= 1 ? Math.min(n, max) : null; +} + +/** Parse one client frame; anything malformed is dropped (null), never thrown. */ +export function parseClientMessage(raw: string): ClientMessage | null { + if (raw.length > MAX_INPUT_BYTES * 2) return null; + let value: unknown; + try { + value = JSON.parse(raw); + } catch { + return null; + } + if (!value || typeof value !== 'object') return null; + const msg = value as Record; + if (msg.type === 'input') { + if (typeof msg.data !== 'string' || Buffer.byteLength(msg.data) > MAX_INPUT_BYTES) return null; + return { type: 'input', data: msg.data }; + } + if (msg.type === 'resize') { + const cols = clampDimension(msg.cols, MAX_COLS); + const rows = clampDimension(msg.rows, MAX_ROWS); + return cols && rows ? { type: 'resize', cols, rows } : null; + } + return null; +} + +// ---- Authentication ---- + +function offeredProtocols(req: IncomingMessage): string[] { + const header = req.headers['sec-websocket-protocol']; + const joined = Array.isArray(header) ? header.join(',') : header ?? ''; + return joined.split(',').map((p) => p.trim()).filter(Boolean); +} + +/** The web token a browser offered as a subprotocol entry, or null. */ +export function extractSubprotocolToken(req: IncomingMessage): string | null { + for (const protocol of offeredProtocols(req)) { + if (!protocol.startsWith(TOKEN_PROTOCOL_PREFIX)) continue; + try { + const token = Buffer.from(protocol.slice(TOKEN_PROTOCOL_PREFIX.length), 'base64url').toString('utf8'); + return token || null; + } catch { + return null; + } + } + return null; +} + +/** The browser page that opened this socket was served by this daemon (same host and port). */ +function isSameHostOrigin(req: IncomingMessage): boolean { + if (isTrustedLocalOrigin(req)) return true; + const { origin, host } = req.headers; + if (!origin || !host) return false; + try { + const o = new URL(origin); + const h = new URL(`${o.protocol}//${host}`); + return (o.protocol === 'http:' || o.protocol === 'https:') + && o.hostname === h.hostname && getEffectivePort(o) === getEffectivePort(h); + } catch { + return false; + } +} + +/** + * The same verdict the HTTP mutation gate gives (token, OR loopback with a + * trusted Origin, OR trusted Tailscale), reached through the gate itself. + * On top of it, any browser-originated upgrade must come from a page this + * daemon served: the ambient-trust paths already demand that inside the gate, + * and this extends it to the token path. + */ +export function authorizeTerminalUpgrade(req: IncomingMessage): boolean { + if (req.headers.origin !== undefined && !isSameHostOrigin(req)) return false; + if (isAuthorizedMutation(req)) return true; + const token = extractSubprotocolToken(req); + if (!token) return false; + // Re-ask the existing token check with the subprotocol token in the header + // it already reads, rather than comparing secrets a second way here. + const view = { headers: { ...req.headers, authorization: undefined, 'x-openswarm-token': token }, socket: req.socket }; + return hasValidWebToken(view as unknown as IncomingMessage); +} + +// ---- Session bookkeeping ---- + +export class SessionLimiter { + #active = 0; + constructor(readonly max: number = MAX_SESSIONS) {} + tryAcquire(): boolean { + if (this.#active >= this.max) return false; + this.#active += 1; + return true; + } + release(): void { + if (this.#active > 0) this.#active -= 1; + } + get active(): number { + return this.#active; + } +} + +export interface IdleTimer { touch(): void; clear(): void } + +/** Calls onIdle once after `ms` without a touch(). */ +export function createIdleTimer(ms: number, onIdle: () => void): IdleTimer { + let timer: ReturnType | null = null; + const arm = () => { + if (timer) clearTimeout(timer); + timer = setTimeout(() => { timer = null; onIdle(); }, ms); + timer.unref?.(); + }; + arm(); + return { + touch: arm, + clear: () => { if (timer) clearTimeout(timer); timer = null; }, + }; +} + +// ---- PTY ---- + +export interface TerminalPty { + onData(listener: (data: string) => void): void; + onExit(listener: (event: { exitCode: number }) => void): void; + write(data: string): void; + resize(cols: number, rows: number): void; + kill(): void; +} + +export type SpawnPty = (options: { cols: number; rows: number; cwd: string }) => TerminalPty | Promise; + +export function terminalWorkingDirectory(env: NodeJS.ProcessEnv = process.env): string { + const root = env.OPENSWARM_WORKSPACE_ROOT?.trim() || '/work'; + return existsSync(root) ? root : homedir(); +} + +/** node-pty is an optional native dependency, loaded only once a session starts. */ +const spawnNodePty: SpawnPty = async ({ cols, rows, cwd }) => { + const pty = await import('node-pty'); + return pty.spawn('bash', ['-l'], { name: 'xterm-256color', cols, rows, cwd, env: process.env as Record }); +}; + +// ---- Wiring ---- + +/** The subset of a `ws` WebSocket this module uses. */ +export interface TerminalSocket { + send(data: string): void; + close(code?: number, reason?: string): void; + on(event: 'message', listener: (data: unknown) => void): void; + on(event: 'close', listener: () => void): void; +} + +export interface TerminalSessionDeps { + spawnPty?: SpawnPty; + limiter?: SessionLimiter; + idleMs?: number; + log?: (line: string) => void; +} + +function peerOf(req: IncomingMessage): string { + return req.socket.remoteAddress ?? 'unknown'; +} + +/** + * Run one terminal session over an accepted socket. Exported so the session + * cap, idle timeout and cleanup can be tested without a real pty or server. + */ +export async function runTerminalSession(socket: TerminalSocket, req: IncomingMessage, deps: TerminalSessionDeps = {}): Promise { + const limiter = deps.limiter ?? new SessionLimiter(); + const log = deps.log ?? ((line: string) => console.log(line)); + const peer = peerOf(req); + if (!limiter.tryAcquire()) { + log(`[Terminal] refused ${peer}: ${limiter.max} sessions already open`); + socket.close(CLOSE_TRY_AGAIN_LATER, 'Too many terminal sessions'); + return; + } + const startedAt = Date.now(); + let closed = false; + let pty: TerminalPty | null = null; + const pending: ClientMessage[] = []; + const idle = createIdleTimer(deps.idleMs ?? IDLE_MS, () => { + log(`[Terminal] idle timeout ${peer}`); + socket.close(1000, 'Idle timeout'); + finish(); + }); + + function finish(): void { + if (closed) return; + closed = true; + idle.clear(); + limiter.release(); + try { pty?.kill(); } catch { /* already gone */ } + log(`[Terminal] session end ${peer} after ${Math.round((Date.now() - startedAt) / 1000)}s (${limiter.active} open)`); + } + + function apply(message: ClientMessage): void { + if (!pty) { pending.push(message); return; } + if (message.type === 'input') pty.write(message.data); + else pty.resize(message.cols, message.rows); + } + + socket.on('message', (data) => { + const message = parseClientMessage(typeof data === 'string' ? data : String(data)); + if (!message) return; + idle.touch(); + apply(message); + }); + socket.on('close', finish); + log(`[Terminal] session start ${peer} (${limiter.active} open)`); + + try { + pty = await (deps.spawnPty ?? spawnNodePty)({ cols: 80, rows: 24, cwd: terminalWorkingDirectory() }); + } catch (err) { + log(`[Terminal] could not start a shell: ${err instanceof Error ? err.message : String(err)}`); + socket.close(1011, 'Shell unavailable'); + finish(); + return; + } + if (closed) { try { pty.kill(); } catch { /* ignore */ } return; } + pty.onData((chunk) => { if (!closed) socket.send(chunk); }); + pty.onExit(() => { socket.close(1000, 'Shell exited'); finish(); }); + for (const message of pending.splice(0)) apply(message); +} + +function rejectUpgrade(socket: Duplex, status: string): void { + socket.write(`HTTP/1.1 ${status}\r\nConnection: close\r\n\r\n`); + socket.destroy(); +} + +/** + * Register the /terminal/ws upgrade handler on `server`. Callers check + * isWebTerminalEnabled() first; this function does not. + */ +export async function attachTerminalServer(server: Server, deps: TerminalSessionDeps = {}): Promise<() => void> { + const { WebSocketServer } = await import('ws'); + const limiter = deps.limiter ?? new SessionLimiter(); + const wss = new WebSocketServer({ + noServer: true, + maxPayload: MAX_INPUT_BYTES * 2, + handleProtocols: (protocols) => (protocols.has(TERMINAL_PROTOCOL) ? TERMINAL_PROTOCOL : false), + }); + const onUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer) => { + const pathname = new URL(req.url ?? '/', 'http://localhost').pathname; + if (pathname !== TERMINAL_WS_PATH) { + // Nothing else in the daemon accepts upgrades; do not leave it hanging. + if (server.listenerCount('upgrade') === 1) rejectUpgrade(socket, '404 Not Found'); + return; + } + if (!authorizeTerminalUpgrade(req)) { + (deps.log ?? console.log)(`[Terminal] rejected upgrade from ${peerOf(req)}`); + rejectUpgrade(socket, '401 Unauthorized'); + return; + } + wss.handleUpgrade(req, socket, head, (ws) => { + void runTerminalSession(ws as unknown as TerminalSocket, req, { ...deps, limiter }); + }); + }; + server.on('upgrade', onUpgrade); + return () => { + server.off('upgrade', onUpgrade); + for (const client of wss.clients) client.terminate(); + wss.close(); + }; +} + +// ---- Daemon lifecycle (called from web.ts) ---- + +let detachTerminal: (() => void) | null = null; + +/** Attach the terminal to the daemon's HTTP server when, and only when, it is enabled. */ +export async function startOptionalWebTerminal(server: Server): Promise { + if (!isWebTerminalEnabled() || detachTerminal) return; + detachTerminal = await attachTerminalServer(server); + console.warn(`[Terminal] web terminal ENABLED at ${TERMINAL_PAGE_PATH}: a shell in this container for any authorized web client`); +} + +export function stopOptionalWebTerminal(): void { + detachTerminal?.(); + detachTerminal = null; +} diff --git a/src/support/web.ts b/src/support/web.ts index 2030b326..7ffda3c2 100644 --- a/src/support/web.ts +++ b/src/support/web.ts @@ -36,6 +36,7 @@ import { writeAuthRequired, writeJson, } from './webAuth.js'; import { execTasks, startExecTask } from './webExecTasks.js'; +import { startOptionalWebTerminal, stopOptionalWebTerminal } from './terminalServer.js'; import { ISSUE_BOARD_HTML } from '../issues/issueBoardHtml.js'; import { createSubIssuesWithDependencies, getTaskSource } from '../automation/runnerExecution.js'; import { refuseForChildCap } from '../automation/decompositionLimits.js'; @@ -1389,6 +1390,7 @@ export async function startWebServer(port: number = 3847): Promise { } }); + void startOptionalWebTerminal(server).catch((err) => console.error('[Terminal] failed to start:', err)); const trustTailscale = process.env.OPENSWARM_TRUST_TAILSCALE === 'true'; // '::' rather than '0.0.0.0'. The Tailscale ULA is IPv6, and binding // IPv4-only left it unreachable — an operator who had allowlisted their @@ -1462,10 +1464,8 @@ export async function startWebServer(port: number = 3847): Promise { * Stop the web server */ export async function stopWebServer(): Promise { - if (gitStatusPoller) { - stopGitStatusPoller(); - gitStatusPoller = null; - } + if (gitStatusPoller) { stopGitStatusPoller(); gitStatusPoller = null; } + stopOptionalWebTerminal(); stopHealthCache(); stopHealthChecker(); stopReposWatcher(); diff --git a/src/support/webAppRoutes.ts b/src/support/webAppRoutes.ts index 347f9bc4..3fd76889 100644 --- a/src/support/webAppRoutes.ts +++ b/src/support/webAppRoutes.ts @@ -43,6 +43,12 @@ const PAGE_SHELLS: Record Promise> = { '/settings': async () => (await import('./staticAssets.js')).readSettingsShell(), '/threads': async () => (await import('./staticAssets.js')).readThreadBoardShell(), '/app': async () => (await import('./staticAssets.js')).readAppShell(), + '/terminal': async () => (await import('./staticAssets.js')).readTerminalShell(), +}; + +/** Pages that exist only behind an opt-in flag; unset, the URL is not routed at all. */ +const GATED_PAGES: Record boolean> = { + '/terminal': () => process.env.OPENSWARM_WEB_TERMINAL === '1', }; /** @@ -56,6 +62,7 @@ export async function tryServePageShell(res: ServerResponse, url: string): Promi // hasOwn, not a bare index: `url` is request input, and this must not // depend on the caller's `/`-prefix invariant surviving a future change. if (!Object.hasOwn(PAGE_SHELLS, url)) return false; + if (Object.hasOwn(GATED_PAGES, url) && !GATED_PAGES[url]()) return false; const load = PAGE_SHELLS[url]; const shell = await load(); if (!shell) { diff --git a/web/static/js/terminal.js b/web/static/js/terminal.js new file mode 100644 index 00000000..5aaf5705 --- /dev/null +++ b/web/static/js/terminal.js @@ -0,0 +1,83 @@ +// Web virtual terminal client (AGT-4002). Opt-in on the server +// (OPENSWARM_WEB_TERMINAL=1); this page is only routed when it is on. +// +// A browser cannot put headers on a WebSocket, so the web token from +// webToken.js travels as a Sec-WebSocket-Protocol entry, never in the URL. +(function () { + 'use strict'; + + var PROTOCOL = 'openswarm.terminal.v1'; + var TOKEN_PREFIX = 'openswarm.token.'; + + function base64url(text) { + var bytes = new TextEncoder().encode(text); + var binary = ''; + for (var i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]); + return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); + } + + function protocols() { + var api = window.OpenSwarmWebToken; + var token = api && typeof api.readToken === 'function' ? api.readToken() : ''; + return token ? [PROTOCOL, TOKEN_PREFIX + base64url(token)] : [PROTOCOL]; + } + + function socketUrl() { + return (location.protocol === 'https:' ? 'wss://' : 'ws://') + location.host + '/terminal/ws'; + } + + var stateEl = document.getElementById('terminal-state'); + var reconnectEl = document.getElementById('terminal-reconnect'); + + function setState(text, tone) { + stateEl.textContent = text; + stateEl.dataset.tone = tone || ''; + } + + if (typeof window.Terminal !== 'function' || !window.FitAddon) { + setState('Terminal assets are missing (run npm run build).', 'danger'); + return; + } + + var term = new window.Terminal({ cursorBlink: true, fontSize: 13, scrollback: 5000 }); + var fit = new window.FitAddon.FitAddon(); + term.loadAddon(fit); + term.open(document.getElementById('terminal')); + var socket = null; + + function send(message) { + if (socket && socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(message)); + } + + function resize() { + try { fit.fit(); } catch { /* hidden or zero-size container */ } + send({ type: 'resize', cols: term.cols, rows: term.rows }); + } + + var CLOSE_REASONS = { 1013: 'Too many terminal sessions are open.', 1011: 'The shell could not start.' }; + + function connect() { + reconnectEl.hidden = true; + setState('Connecting…', 'warn'); + socket = new WebSocket(socketUrl(), protocols()); + socket.onopen = function () { + setState('Connected', 'ok'); + resize(); + term.focus(); + }; + socket.onmessage = function (event) { + if (typeof event.data === 'string') term.write(event.data); + }; + socket.onclose = function (event) { + var reason = CLOSE_REASONS[event.code] || event.reason || (event.code === 1006 ? 'Connection refused or lost (check the web token).' : 'Disconnected.'); + setState(reason, event.code === 1000 ? 'warn' : 'danger'); + reconnectEl.hidden = false; + socket = null; + }; + } + + term.onData(function (data) { send({ type: 'input', data: data }); }); + window.addEventListener('resize', resize); + reconnectEl.addEventListener('click', connect); + connect(); +})(); diff --git a/web/static/terminal.html b/web/static/terminal.html new file mode 100644 index 00000000..f312cf75 --- /dev/null +++ b/web/static/terminal.html @@ -0,0 +1,32 @@ + +OpenSwarm · Terminal + + + + +
+
+
+ Container shell + Connecting… + + +
+
+
+ + + + +