@reclaimprotocol/agent 0.1.23 → 0.1.24

package/src/live/page.ts

@@ -0,0 +1,145 @@
+/**
+ * The live-view page served to whoever opens the tunnel URL.
+ *
+ * Deliberately dependency-free and inline: it is delivered through a throwaway
+ * tunnel, so it cannot rely on a CDN, a bundler, or anything cached.
+ *
+ * Frames arrive as base64 JPEG over Server-Sent Events rather than a
+ * WebSocket. SSE is one plain GET, so it survives tunnels and proxies that
+ * mishandle upgrades, and it reconnects on its own. Input goes the other way
+ * as small POSTs.
+ */
+
+/** Escape a value for embedding in a single-quoted JS string literal. */
+function js(value: string): string {
+	return value
+		.replace(/\\/g, '\\\\')
+		.replace(/'/g, "\\'")
+		.replace(/</g, '\\x3c')
+}
+
+export interface PageOptions {
+	/** Path prefix that carries the access token, for example `/v/<token>`. */
+	base: string
+	/** Whether to wire up mouse and keyboard forwarding. */
+	interactive: boolean
+	/** Shown in the header so a viewer knows which tab they are watching. */
+	title: string
+}
+
+export function renderViewerPage(opts: PageOptions): string {
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>Reclaim live view</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: #0b0b0c; color: #e7e7ea; display: flex;
+    flex-direction: column; height: 100vh;
+    font: 14px/1.4 ui-sans-serif, system-ui, sans-serif; }
+  header { display: flex; align-items: center; gap: .75rem;
+    padding: .5rem .75rem; border-bottom: 1px solid #26262b; }
+  .dot { width: .5rem; height: .5rem; border-radius: 50%; background: #f5a524; }
+  .dot.live { background: #17c964; }
+  .title { color: #9a9aa4; overflow: hidden; text-overflow: ellipsis;
+    white-space: nowrap; }
+  .badge { margin-left: auto; font-size: 12px; padding: .15rem .4rem;
+    border: 1px solid #26262b; border-radius: .25rem; color: #9a9aa4; }
+  main { flex: 1; min-height: 0; display: grid; place-items: center;
+    padding: .75rem; }
+  img { max-width: 100%; max-height: 100%; display: block;
+    background: #fff; border-radius: .25rem; }
+  img.interactive { cursor: crosshair; }
+  .msg { color: #9a9aa4; }
+</style>
+</head>
+<body>
+<header>
+  <span class="dot" id="dot"></span>
+  <span class="title" id="title">${js(opts.title)}</span>
+  <span class="badge">${opts.interactive ? 'interactive' : 'view only'}</span>
+</header>
+<main><img id="screen" alt="Live view of the browser tab"><p class="msg"
+  id="msg">Connecting…</p></main>
+<script>
+(function () {
+  var BASE = '${js(opts.base)}';
+  var INTERACTIVE = ${opts.interactive ? 'true' : 'false'};
+  var screen = document.getElementById('screen');
+  var msg = document.getElementById('msg');
+  var dot = document.getElementById('dot');
+  var title = document.getElementById('title');
+
+  var es = new EventSource(BASE + '/stream');
+  es.addEventListener('frame', function (e) {
+    var payload = JSON.parse(e.data);
+    screen.src = 'data:image/jpeg;base64,' + payload.data;
+    if (payload.title) { title.textContent = payload.title; }
+    msg.style.display = 'none';
+    dot.className = 'dot live';
+  });
+  es.onerror = function () {
+    dot.className = 'dot';
+    msg.style.display = '';
+    msg.textContent = 'Reconnecting…';
+  };
+
+  if (!INTERACTIVE) { return; }
+  screen.className = 'interactive';
+
+  // The <img> is letterboxed by object-fit, so a click at some point in the
+  // element maps to page coordinates by the ratio of natural to rendered size.
+  function toPage(ev) {
+    var r = screen.getBoundingClientRect();
+    if (!screen.naturalWidth || !r.width) { return null; }
+    return {
+      x: Math.round((ev.clientX - r.left) * (screen.naturalWidth / r.width)),
+      y: Math.round((ev.clientY - r.top) * (screen.naturalHeight / r.height))
+    };
+  }
+
+  function post(body) {
+    return fetch(BASE + '/input', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body)
+    }).catch(function () {});
+  }
+
+  screen.addEventListener('mousedown', function (ev) {
+    var p = toPage(ev); if (!p) { return; }
+    ev.preventDefault();
+    post({ kind: 'mouse', type: 'mousePressed', x: p.x, y: p.y,
+      button: 'left', clickCount: 1 });
+  });
+  screen.addEventListener('mouseup', function (ev) {
+    var p = toPage(ev); if (!p) { return; }
+    post({ kind: 'mouse', type: 'mouseReleased', x: p.x, y: p.y,
+      button: 'left', clickCount: 1 });
+  });
+  screen.addEventListener('wheel', function (ev) {
+    var p = toPage(ev); if (!p) { return; }
+    ev.preventDefault();
+    post({ kind: 'mouse', type: 'mouseWheel', x: p.x, y: p.y,
+      deltaX: ev.deltaX, deltaY: ev.deltaY });
+  }, { passive: false });
+
+  // Typing goes to the page, so the viewer never needs to focus anything.
+  window.addEventListener('keydown', function (ev) {
+    if (ev.metaKey || ev.ctrlKey) { return; }
+    ev.preventDefault();
+    post({ kind: 'key', type: 'keyDown', key: ev.key, code: ev.code });
+  });
+  window.addEventListener('keyup', function (ev) {
+    if (ev.metaKey || ev.ctrlKey) { return; }
+    post({ kind: 'key', type: 'keyUp', key: ev.key, code: ev.code });
+  });
+})();
+</script>
+</body>
+</html>`
+}

package/src/live/tunnel.ts

@@ -0,0 +1,157 @@
+/**
+ * Public HTTPS front door for the local live-view server, via a `cloudflared`
+ * quick tunnel.
+ *
+ * A quick tunnel needs no Cloudflare account and no DNS: `cloudflared` dials
+ * out, Cloudflare hands back a throwaway `*.trycloudflare.com` hostname, and
+ * traffic arrives on the loopback port we pass in. That is the whole reason it
+ * is used here — the developer's machine keeps no inbound port open.
+ *
+ * The tunnel itself carries NO authorization. Anyone holding the hostname can
+ * reach the local server, so the server is the thing that must authenticate
+ * (see `viewer.ts`, which puts an unguessable token in every path).
+ */
+import { spawn } from 'node:child_process'
+import { LOGGER } from '../logger.ts'
+import { type CloudflaredBinary, resolveCloudflared } from './cloudflared.ts'
+
+/** How long to wait for cloudflared to report its hostname before giving up. */
+const URL_TIMEOUT_MS = 30_000
+/** After the hostname is printed, Cloudflare needs a moment before the edge
+ *  routes to it — measured at ~3s. Poll until it answers so the caller never
+ *  hands out a URL that errors, but don't fail the share if it's slow. */
+const READY_TIMEOUT_MS = 20_000
+const READY_POLL_MS = 1_000
+
+/** `https://<something>.trycloudflare.com`, as printed on cloudflared's log
+ *  stream. Anchored to the scheme so a hostname inside prose can't match. */
+const QUICK_TUNNEL_URL = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i
+
+export interface Tunnel {
+	/** The public HTTPS origin Cloudflare assigned. */
+	url: string
+	/** Whether the edge answered before {@link READY_TIMEOUT_MS} elapsed. False
+	 *  means the tunnel is probably still propagating rather than broken — tell
+	 *  the viewer to retry rather than treating the share as failed. */
+	ready: boolean
+	/** Terminate the tunnel. Safe to call more than once. */
+	stop: () => Promise<void>
+	/** Which cloudflared ran, and whether we had to fetch it. */
+	binary: CloudflaredBinary
+}
+
+/**
+ * Poll the public origin until Cloudflare's edge routes to it. ANY HTTP
+ * response counts, including a 404: the live-view server 404s unknown paths,
+ * so a status code at all proves the hop is live.
+ */
+async function waitUntilRouted(url: string): Promise<boolean> {
+	const deadline = Date.now() + READY_TIMEOUT_MS
+	while(Date.now() < deadline) {
+		try {
+			await fetch(url, {
+				method: 'GET',
+				redirect: 'manual',
+				signal: AbortSignal.timeout(READY_POLL_MS * 4),
+			})
+			return true
+		} catch{
+			await new Promise((r) => setTimeout(r, READY_POLL_MS))
+		}
+	}
+
+	return false
+}
+
+/**
+ * Open a quick tunnel to `http://127.0.0.1:<port>` and resolve once
+ * Cloudflare has assigned a hostname.
+ *
+ * Rejects with an actionable message when `cloudflared` is not installed,
+ * exits early, or never reports a hostname.
+ */
+export async function startTunnel(
+	port: number,
+	{ autoInstall = true }: { autoInstall?: boolean } = {},
+): Promise<Tunnel> {
+	// Resolves an existing cloudflared, or fetches one on first use. Throws
+	// with an actionable message when neither is possible.
+	const binary = await resolveCloudflared({ autoInstall })
+	const child = spawn(binary.path, [
+		'tunnel',
+		'--no-autoupdate',
+		'--url', `http://127.0.0.1:${port}`,
+	], { stdio: ['ignore', 'pipe', 'pipe'] })
+
+	const stop = async() => {
+		if(!child.killed) {
+			child.kill('SIGTERM')
+		}
+	}
+
+	return new Promise<Tunnel>((resolve, reject) => {
+		const timer = setTimeout(() => {
+			void stop()
+			reject(new Error(
+				'cloudflared did not report a tunnel hostname within '
+				+ `${URL_TIMEOUT_MS / 1000}s. Check network egress to Cloudflare, `
+				+ 'or run `cloudflared tunnel --url http://127.0.0.1:'
+				+ `${port}` + '` by hand to see its output.',
+			))
+		}, URL_TIMEOUT_MS)
+
+		let settled = false
+		const finish = (fn: () => void) => {
+			if(settled) {
+				return
+			}
+
+			settled = true
+			clearTimeout(timer)
+			fn()
+		}
+
+		// cloudflared logs the assigned hostname to stderr, not stdout. Watch
+		// both so a future version that switches streams still works.
+		const onChunk = (chunk: Buffer) => {
+			const text = chunk.toString()
+			const match = QUICK_TUNNEL_URL.exec(text)
+			if(match) {
+				const url = match[0]
+				finish(() => {
+					void waitUntilRouted(url).then((ready) => {
+						if(!ready) {
+							LOGGER.warn({ url }, 'tunnel not routed yet; returning anyway')
+						}
+
+						resolve({ url, ready, stop, binary })
+					})
+				})
+			}
+		}
+
+		child.stdout?.on('data', onChunk)
+		child.stderr?.on('data', onChunk)
+
+		child.on('error', (err: NodeJS.ErrnoException) => {
+			// `resolveCloudflared` already proved the binary runs, so an ENOENT
+			// here means it vanished between resolving and spawning.
+			finish(() => reject(
+				err.code === 'ENOENT'
+					? new Error(
+						`cloudflared disappeared from ${binary.path} before it could `
+						+ 'start. Retry — the agent will fetch it again if needed.',
+					)
+					: err,
+			))
+		})
+
+		child.on('exit', (code) => {
+			LOGGER.debug({ code }, 'cloudflared exited')
+			finish(() => reject(new Error(
+				`cloudflared exited with code ${code} before reporting a `
+				+ 'hostname.',
+			)))
+		})
+	})
+}

package/src/live/viewer.ts

@@ -0,0 +1,293 @@
+/**
+ * Interactive live view of one attached tab, over a public URL.
+ *
+ * Two halves:
+ *  - OUT: CDP `Page.startScreencast` pushes JPEG frames; each is forwarded to
+ *    every connected browser as a Server-Sent Event and acked back to CDP.
+ *  - IN: the viewer POSTs pointer and key events, which are replayed into the
+ *    page with `Input.dispatch*`.
+ *
+ * Only ever bound to 127.0.0.1. Reaching it from outside is the tunnel's job
+ * (see `tunnel.ts`), and because a quick tunnel is unauthenticated, EVERY
+ * route sits behind an unguessable token in the path. A request without it
+ * gets a flat 404 — not a 401, which would confirm the server exists.
+ *
+ * Interactivity is the caller's choice. `interactive: false` still streams,
+ * but the input route refuses, which is the right setting for showing someone
+ * a run rather than handing them the wheel.
+ */
+import { randomBytes } from 'node:crypto'
+import {
+	createServer,
+	type IncomingMessage,
+	type Server,
+	type ServerResponse,
+} from 'node:http'
+import type { AddressInfo } from 'node:net'
+import type { CdpTabClient } from '../cdp/client.ts'
+import { LOGGER } from '../logger.ts'
+import { renderViewerPage } from './page.ts'
+
+/** JPEG quality for streamed frames. 60 keeps a text-heavy page readable
+ *  while staying small enough for a tunnel's uplink. */
+const FRAME_QUALITY = 60
+/** Cap the streamed frame size. Screencast scales to fit, so this bounds
+ *  bandwidth without changing the page's own layout viewport. */
+const MAX_FRAME_WIDTH = 1280
+const MAX_FRAME_HEIGHT = 800
+/** Bytes accepted on an input POST. Events are tiny; anything larger is
+ *  either a bug or someone probing. */
+const MAX_INPUT_BYTES = 4096
+
+export interface LiveViewOptions {
+	/** The tab to stream. */
+	tab: CdpTabClient
+	/** Forward viewer input into the page. */
+	interactive: boolean
+	/** Shown in the viewer's header. */
+	title?: string
+}
+
+export interface LiveView {
+	/** Loopback origin the tunnel should point at. */
+	localUrl: string
+	/** Port the server bound to. */
+	port: number
+	/** Unguessable path segment guarding every route. */
+	token: string
+	/** Path prefix, `/v/<token>`. Append this to the public origin. */
+	path: string
+	/** Number of viewers currently streaming. */
+	viewers: () => number
+	stop: () => Promise<void>
+}
+
+/**
+ * Start the loopback live-view server for `tab`. Resolves once it is
+ * listening; the screencast starts with the first viewer and stops with the
+ * last, so an idle share costs the page nothing.
+ */
+export async function startLiveView(
+	opts: LiveViewOptions,
+): Promise<LiveView> {
+	const token = randomBytes(24).toString('base64url')
+	const path = `/v/${token}`
+	const clients = new Set<ServerResponse>()
+	let streaming = false
+	let unsubscribe: (() => void) | undefined
+
+	const startScreencast = async() => {
+		if(streaming) {
+			return
+		}
+
+		streaming = true
+		unsubscribe = opts.tab.subscribe('Page.screencastFrame', (frame) => {
+			// Ack first: CDP sends at most one un-acked frame, so a slow or failed
+			// write must not stall the stream.
+			void opts.tab
+				.send('Page.screencastFrameAck', { sessionId: frame.sessionId })
+				.catch(() => {})
+			const payload = JSON.stringify({ data: frame.data })
+			for(const res of clients) {
+				res.write(`event: frame\ndata: ${payload}\n\n`)
+			}
+		})
+		await opts.tab.send('Page.enable')
+		await opts.tab.send('Page.startScreencast', {
+			format: 'jpeg',
+			quality: FRAME_QUALITY,
+			maxWidth: MAX_FRAME_WIDTH,
+			maxHeight: MAX_FRAME_HEIGHT,
+			everyNthFrame: 1,
+		})
+	}
+
+	const stopScreencast = async() => {
+		if(!streaming) {
+			return
+		}
+
+		streaming = false
+		unsubscribe?.()
+		unsubscribe = undefined
+		await opts.tab.send('Page.stopScreencast').catch(() => {})
+	}
+
+	const server = createServer((req, res) => {
+		const url = req.url ?? '/'
+		// Constant prefix check: everything is scoped under the token, so an
+		// unmatched path is indistinguishable from a server that isn't there.
+		if(!url.startsWith(path)) {
+			res.writeHead(404).end('not found')
+			return
+		}
+
+		const route = url.slice(path.length) || '/'
+		if(req.method === 'GET' && (route === '/' || route.startsWith('/?'))) {
+			const body = renderViewerPage({
+				base: path,
+				interactive: opts.interactive,
+				title: opts.title ?? 'Attached tab',
+			})
+			res.writeHead(200, {
+				'content-type': 'text/html; charset=utf-8',
+				// A share URL must never be cached or indexed by anything between
+				// the viewer and here.
+				'cache-control': 'no-store',
+				'referrer-policy': 'no-referrer',
+			}).end(body)
+			return
+		}
+
+		if(req.method === 'GET' && route === '/stream') {
+			res.writeHead(200, {
+				'content-type': 'text/event-stream',
+				'cache-control': 'no-store',
+				connection: 'keep-alive',
+				// Defeat proxy buffering, which would otherwise hold frames back.
+				'x-accel-buffering': 'no',
+			})
+			res.write(': connected\n\n')
+			clients.add(res)
+			void startScreencast().catch((err) => {
+				LOGGER.warn({ err }, 'live view: screencast failed to start')
+			})
+			req.on('close', () => {
+				clients.delete(res)
+				if(!clients.size) {
+					void stopScreencast()
+				}
+			})
+			return
+		}
+
+		if(req.method === 'POST' && route === '/input') {
+			if(!opts.interactive) {
+				res.writeHead(403).end('view only')
+				return
+			}
+
+			readJson(req, MAX_INPUT_BYTES)
+				.then((body) => dispatchInput(opts.tab, body))
+				.then(() => res.writeHead(204).end())
+				.catch((err) => {
+					LOGGER.debug({ err }, 'live view: input rejected')
+					res.writeHead(400).end('bad input')
+				})
+			return
+		}
+
+		res.writeHead(404).end('not found')
+	})
+
+	await new Promise<void>((resolve) => {
+		server.listen(0, '127.0.0.1', resolve)
+	})
+	const port = (server.address() as AddressInfo).port
+
+	return {
+		localUrl: `http://127.0.0.1:${port}`,
+		port,
+		token,
+		path,
+		viewers: () => clients.size,
+		stop: async() => {
+			await stopScreencast()
+			for(const res of clients) {
+				res.end()
+			}
+
+			clients.clear()
+			await closeServer(server)
+		},
+	}
+}
+
+function closeServer(server: Server): Promise<void> {
+	return new Promise((resolve) => {
+		server.close(() => resolve())
+		// A held-open SSE response would otherwise keep the server alive.
+		server.closeAllConnections?.()
+	})
+}
+
+function readJson(
+	req: IncomingMessage,
+	limit: number,
+): Promise<Record<string, unknown>> {
+	return new Promise((resolve, reject) => {
+		let size = 0
+		const chunks: Buffer[] = []
+		req.on('data', (chunk: Buffer) => {
+			size += chunk.length
+			if(size > limit) {
+				reject(new Error('input too large'))
+				req.destroy()
+				return
+			}
+
+			chunks.push(chunk)
+		})
+		req.on('end', () => {
+			try {
+				resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+			} catch(err) {
+				reject(err instanceof Error ? err : new Error('bad json'))
+			}
+		})
+		req.on('error', reject)
+	})
+}
+
+/** Replay one viewer event into the page. Unknown shapes throw, so the route
+ *  answers 400 rather than forwarding something arbitrary to CDP. */
+async function dispatchInput(
+	tab: CdpTabClient,
+	body: Record<string, unknown>,
+): Promise<void> {
+	const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v)
+		? v
+		: 0)
+
+	if(body.kind === 'mouse') {
+		const type = String(body.type)
+		if(!['mousePressed', 'mouseReleased', 'mouseMoved', 'mouseWheel']
+			.includes(type)) {
+			throw new Error(`unsupported mouse type ${type}`)
+		}
+
+		await tab.send('Input.dispatchMouseEvent', {
+			type,
+			x: num(body.x),
+			y: num(body.y),
+			button: type === 'mouseWheel' ? 'none' : 'left',
+			clickCount: type === 'mouseWheel' ? 0 : 1,
+			...(type === 'mouseWheel'
+				? { deltaX: num(body.deltaX), deltaY: num(body.deltaY) }
+				: {}),
+		})
+		return
+	}
+
+	if(body.kind === 'key') {
+		const type = String(body.type)
+		if(type !== 'keyDown' && type !== 'keyUp') {
+			throw new Error(`unsupported key type ${type}`)
+		}
+
+		const key = String(body.key ?? '')
+		// A single printable character needs `text` as well, or the page sees the
+		// keypress but no character is inserted.
+		const text = key.length === 1 ? key : undefined
+		await tab.send('Input.dispatchKeyEvent', {
+			type,
+			key,
+			code: String(body.code ?? ''),
+			...(text && type === 'keyDown' ? { text } : {}),
+		})
+		return
+	}
+
+	throw new Error('unknown event kind')
+}