@workerdeck/server 0.6.0 → 0.7.0

package/build/index.mjs

@@ -1,13 +1,369 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
-import { dirname, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { WebSocketServer } from "ws";
 import { listSessions } from "@anthropic-ai/claude-agent-sdk";
 import { BrowserBridgeExecutor, SessionRunner, checkClaudeAuth } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
 import { PROTOCOL_VERSION, PROVIDER_PERMISSION_MODES, supportsPermissionMode } from "@workerdeck/protocol";
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+//#region src/host-files.ts
+/**
+* Built once at startup from operator config. Roots are canonicalized here
+* because resolution produces realpath'd targets: a root that is itself a
+* symlink (`/tmp` -> `/private/tmp` on macOS) would otherwise contain nothing.
+* A misdeclared root throws rather than silently guarding the wrong tree —
+* same stance as profile config dirs in server.ts. An empty list is legal and
+* refuses everything; "no roots means allow all" is `cwdAllowed`'s contract,
+* never this module's.
+*/
+function createHostFileRoots(roots) {
+	return { roots: roots.map((configured) => {
+		if (invalidRequest(configured)) throw new Error(`createHostFileRoots: root must be an absolute path: ${JSON.stringify(configured)}`);
+		let canonical;
+		try {
+			canonical = realpathSync(configured);
+		} catch {
+			throw new Error(`createHostFileRoots: root does not exist: ${configured}`);
+		}
+		if (!lstatSync(canonical).isDirectory()) throw new Error(`createHostFileRoots: root is not a directory: ${configured}`);
+		return {
+			configured,
+			canonical
+		};
+	}) };
+}
+function refuse(status, error) {
+	return {
+		ok: false,
+		status,
+		error
+	};
+}
+/** The uniform filesystem refusal — see the disclosure policy in the header.
+* The string is deliberately constant: a distinct message is as much an oracle
+* as a distinct status. */
+function notFound() {
+	return refuse(404, "not found");
+}
+/** NUL is rejected before any fs call — Node throws a TypeError on NUL paths,
+* and that must surface as a refusal, not a 500. Relative paths are refused
+* outright rather than resolved against a cwd this API never promised. */
+function invalidRequest(requested) {
+	return requested.length === 0 || requested.includes("\0") || !isAbsolute(requested);
+}
+/** Both sides are realpath output, so this is a pure lexical question — but a
+* bare prefix check gets the boundary wrong (`/x/app` would swallow
+* `/x/application`). `relative` answers it exactly: inside iff the walk from
+* root to candidate is empty or never has to leave through `..`. */
+function contained(rootCanonical, candidate) {
+	const rel = relative(rootCanonical, candidate);
+	return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function rootContaining(roots, canonical) {
+	return roots.roots.find((root) => contained(root.canonical, canonical));
+}
+/**
+* For read/list: the target must exist. realpath is handed the request whole —
+* no lexical `..` collapsing first, because `root/link/..` is lexically `root`
+* but physically the link target's parent, and only the physical answer is the
+* true one. Symlinks that canonicalize *inside* a root are followed and served:
+* containment is a property of the canonical target, not of the route to it —
+* the operator granted the whole subtree, so nothing new becomes reachable.
+*/
+function resolveExisting(roots, requested) {
+	if (invalidRequest(requested)) return refuse(403, "invalid path");
+	let canonical;
+	try {
+		canonical = realpathSync(requested);
+	} catch {
+		return notFound();
+	}
+	const root = rootContaining(roots, canonical);
+	if (!root) return notFound();
+	let target;
+	try {
+		target = lstatSync(canonical);
+	} catch {
+		return notFound();
+	}
+	if (target.isFile()) return {
+		ok: true,
+		path: canonical,
+		root: root.canonical,
+		kind: "file"
+	};
+	if (target.isDirectory()) return {
+		ok: true,
+		path: canonical,
+		root: root.canonical,
+		kind: "dir"
+	};
+	return refuse(403, "not a regular file or directory");
+}
+/**
+* For write: the target may not exist, so realpath cannot be asked directly.
+* An existing target reuses read semantics — writing *through* a symlink that
+* canonicalizes inside a root is allowed (`root/link -> root/real.txt` edits
+* real.txt), same reasoning as {@link resolveExisting}. A missing target
+* canonicalizes its immediate parent and re-checks: only the final component
+* may be new, and anything already sitting there — in practice a dangling
+* symlink — is refused, because open(2) with O_CREAT follows it and would
+* create the file wherever it points. That refusal is `not found`, not 403: a
+* link to an existing outside file already answers 404 via the exists branch,
+* so a distinct status for the dangling case would hand back exactly the
+* existence bit the uniform 404 exists to withhold.
+*/
+function resolveForWrite(roots, requested) {
+	if (invalidRequest(requested)) return refuse(403, "invalid path");
+	try {
+		const canonical = realpathSync(requested);
+		const root = rootContaining(roots, canonical);
+		if (!root) return notFound();
+		const target = lstatSync(canonical);
+		if (target.isDirectory()) return refuse(403, "is a directory");
+		if (!target.isFile()) return refuse(403, "not a regular file");
+		return {
+			ok: true,
+			path: canonical,
+			root: root.canonical,
+			kind: "file"
+		};
+	} catch {}
+	const base = basename(requested);
+	if (base === "" || base === "." || base === "..") return refuse(403, "invalid path");
+	let parent;
+	try {
+		parent = realpathSync(dirname(requested));
+	} catch {
+		return notFound();
+	}
+	const root = rootContaining(roots, parent);
+	if (!root) return notFound();
+	try {
+		if (!lstatSync(parent).isDirectory()) return notFound();
+	} catch {
+		return notFound();
+	}
+	const path = join(parent, base);
+	if (!contained(root.canonical, path)) return notFound();
+	try {
+		lstatSync(path);
+	} catch (err) {
+		if (err.code === "ENOENT") return {
+			ok: true,
+			path,
+			root: root.canonical,
+			kind: "file"
+		};
+		return notFound();
+	}
+	return notFound();
+}
+/** lstat semantics on purpose: a listing shows a symlink AS a symlink — the
+* server never follows one while rendering a directory. Following happens only
+* when the entry is itself requested, through {@link resolveExisting}, which
+* refuses it if it escapes. `readdir(withFileTypes)` already answers without
+* following, so this is classification, not I/O. */
+function entryKind(entry) {
+	if (entry.isSymbolicLink()) return "symlink";
+	if (entry.isFile()) return "file";
+	if (entry.isDirectory()) return "dir";
+	return "other";
+}
+const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const O_NONBLOCK = constants.O_NONBLOCK ?? 0;
+/**
+* The open half of the resolve→open discipline; pass `ResolveOutcome.path`,
+* never the requested string. O_NOFOLLOW turns a final component swapped for a
+* symlink inside the race window into ELOOP instead of a follow; O_NONBLOCK
+* makes a swapped-in fifo open instantly instead of parking the request until a
+* writer appears (it is inert for regular files); the fstat gate refuses
+* anything that is not a plain file before a byte is read — `/dev/zero` would
+* otherwise be an unbounded read.
+*/
+function readContained(path) {
+	let fd;
+	try {
+		fd = openSync(path, constants.O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+	} catch (err) {
+		return err.code === "ENOENT" ? notFound() : refuse(403, "refused");
+	}
+	try {
+		if (!fstatSync(fd).isFile()) return refuse(403, "not a regular file");
+		return {
+			ok: true,
+			data: readFileSync(fd)
+		};
+	} catch {
+		return refuse(403, "refused");
+	} finally {
+		closeSync(fd);
+	}
+}
+/**
+* O_CREAT|O_NOFOLLOW refuses (ELOOP) a symlink planted at the final component
+* after resolve — the exact swap that would land the write at the link's
+* target. Truncation happens via ftruncate only AFTER the fd is proven to be a
+* regular file, so a swapped-in device or fifo is never truncated or written;
+* O_NONBLOCK turns the reader-less-fifo open from a hang into ENXIO.
+*/
+function writeContained(path, data) {
+	let fd;
+	try {
+		fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | O_NOFOLLOW | O_NONBLOCK, 420);
+	} catch (err) {
+		return err.code === "ENOENT" ? notFound() : refuse(403, "refused");
+	}
+	try {
+		if (!fstatSync(fd).isFile()) return refuse(403, "not a regular file");
+		ftruncateSync(fd);
+		writeFileSync(fd, data);
+		return { ok: true };
+	} catch {
+		return refuse(403, "refused");
+	} finally {
+		closeSync(fd);
+	}
+}
+//#endregion
+//#region src/host-file-search.ts
+/**
+* The recursive half of the host-file routes: what `@file` autocomplete needs and
+* `/fs/list` deliberately isn't. Listing answers "what is in this directory"; this
+* answers "which file in this tree did you mean", which is a different query and a
+* different cost model.
+*
+* Kept out of `host-files.ts` on purpose. That module is the audited containment
+* core; this one walks *inside* an already-resolved, already-contained directory
+* and never resolves a path of its own. Its one security-relevant rule is that it
+* does not follow symlinks — see the walk below.
+*/
+/**
+* Directories a source tree keeps that nobody types `@` looking for, and that are
+* usually most of the entries on disk. Skipping them is what makes the walk cheap
+* enough to run per keystroke; the operator can replace the list via
+* `hostFiles.ignore`.
+*/
+const DEFAULT_IGNORED_DIRS = [
+	".git",
+	".hg",
+	".svn",
+	"node_modules",
+	".next",
+	".nuxt",
+	".svelte-kit",
+	".turbo",
+	".cache",
+	"dist",
+	"build",
+	"out",
+	"target",
+	".venv",
+	"venv",
+	"__pycache__",
+	".pytest_cache",
+	".gradle",
+	"Pods",
+	"DerivedData"
+];
+/**
+* Breadth-first so shallow files rank first before scoring even runs — for a bare
+* `@` that ordering *is* the ranking, and for a query it breaks ties the way a
+* person expects (`src/index.ts` over `src/a/b/c/index.ts`).
+*
+* Symlinks are skipped outright, as files and as directories. As directories it is
+* the difference between a bounded walk and an unbounded one (a cycle, or a link
+* to `/`); as files it keeps this function's output within the tree it was handed,
+* so nothing it offers can be a path that `resolveExisting` would later refuse.
+* A tree that genuinely lives behind symlinks is not autocompletable — an accepted
+* cost for not having to re-derive containment here.
+*/
+function searchFiles(base, options = {}) {
+	const limit = options.limit ?? 50;
+	const maxScanned = options.maxScanned ?? 2e4;
+	const ignore = new Set(options.ignore ?? DEFAULT_IGNORED_DIRS);
+	const needle = (options.query ?? "").toLowerCase();
+	const found = [];
+	const queue = [{
+		dir: base,
+		depth: 0
+	}];
+	let scanned = 0;
+	let exhausted = true;
+	while (queue.length > 0) {
+		const { dir, depth } = queue.shift();
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (++scanned > maxScanned) {
+				exhausted = false;
+				queue.length = 0;
+				break;
+			}
+			const kind = entryKind(entry);
+			if (kind === "dir") {
+				if (!ignore.has(entry.name)) queue.push({
+					dir: join(dir, entry.name),
+					depth: depth + 1
+				});
+				continue;
+			}
+			if (kind !== "file") continue;
+			const path = join(dir, entry.name);
+			const rel = relative(base, path);
+			const score = scoreMatch(rel, entry.name, needle);
+			if (score !== null) found.push({
+				file: {
+					path,
+					relative: rel
+				},
+				score,
+				depth
+			});
+		}
+	}
+	found.sort((a, b) => b.score - a.score || a.depth - b.depth || a.file.relative.length - b.file.relative.length || a.file.relative.localeCompare(b.file.relative));
+	return {
+		matches: found.slice(0, limit).map((f) => f.file),
+		truncated: !exhausted || found.length > limit
+	};
+}
+/**
+* Subsequence matching, like every `@`-picker worth using: `seslist` finds
+* `SessionListView.swift`. Returns null for no match.
+*
+* Scored so the two things people actually mean win — a hit in the filename beats
+* one buried in the directory path, and characters typed consecutively beat the
+* same characters scattered — rather than trying to be a ranking engine.
+*/
+function scoreMatch(relativePath, name, needle) {
+	if (needle === "") return 0;
+	const inName = subsequenceScore(name.toLowerCase(), needle);
+	if (inName !== null) return inName + 1e3;
+	return subsequenceScore(relativePath.toLowerCase(), needle);
+}
+function subsequenceScore(haystack, needle) {
+	let score = 0;
+	let from = 0;
+	let previous = -2;
+	for (const char of needle) {
+		const at = haystack.indexOf(char, from);
+		if (at === -1) return null;
+		if (at === previous + 1) score += 8;
+		if (at === 0) score += 4;
+		from = at + 1;
+		previous = at;
+	}
+	return score - haystack.length / 100;
+}
+//#endregion
 //#region src/registry.ts
 /** In-memory session table. Terminal sessions stay listed until removed or the process exits. */
 var SessionRegistry = class {
@@ -831,6 +1187,21 @@ const CONTENT_TYPES = {
 	xml: "application/xml; charset=utf-8",
 	svg: "image/svg+xml; charset=utf-8"
 };
+/** sha256 hex — the currency of the conditional-write protocol on `/fs/write`. */
+function hashBytes(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+* The file's text, or null if it isn't text. Decoding never fails in Node — invalid
+* bytes become U+FFFD — so the only honest test is a round trip: if re-encoding the
+* decoded string reproduces the original bytes, nothing was lost and the client can
+* safely edit and send it back. Anything else ships base64, which an editor can
+* refuse to open rather than silently corrupt on save.
+*/
+function asUtf8(bytes) {
+	const text = bytes.toString("utf8");
+	return Buffer.from(text, "utf8").equals(bytes) ? text : null;
+}
 function contentTypeFor(filename) {
 	return CONTENT_TYPES[filename.includes(".") ? filename.split(".").pop().toLowerCase() : ""] ?? "text/plain; charset=utf-8";
 }
@@ -1248,6 +1619,234 @@ function createWorkerServer(options = {}) {
 		}
 		return null;
 	};
+	const hostFileRootPaths = options.hostFiles?.roots ?? options.allowedCwdRoots;
+	const hostFiles = hostFileRootPaths?.length ? createHostFileRoots(hostFileRootPaths) : null;
+	const hostFilesWritable = options.hostFiles?.write === true;
+	const maxHostFileBytes = options.hostFiles?.maxFileBytes ?? 1024 * 1024;
+	const maxHostDirEntries = options.hostFiles?.maxEntries ?? 5e3;
+	/**
+	* `{basePath}/fs/*` — the operator's real tree. Authorized by the auth key alone
+	* and deliberately outside the agent permission flow: the caller is the operator.
+	*
+	* Every path in here goes through `host-files.ts` first, which canonicalizes and
+	* *then* re-checks containment. The naive prefix compare `cwdAllowed` does would
+	* be wrong at this door — the agent writes into these trees, and a symlink it
+	* created is a path the operator never typed.
+	*/
+	const handleHostFiles = async (req, res, pathname) => {
+		if (!hostFiles) {
+			json(res, 404, { error: "host file access is not configured on this server" });
+			return;
+		}
+		const route = pathname.slice((basePath + "/fs/").length);
+		const url = new URL(req.url ?? "/", "http://internal");
+		const requested = url.searchParams.get("path");
+		if (route === "roots") {
+			if (req.method !== "GET") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			json(res, 200, {
+				roots: hostFiles.roots.map(({ canonical }) => ({
+					path: canonical,
+					name: basename(canonical) || canonical
+				})),
+				canWrite: hostFilesWritable
+			});
+			return;
+		}
+		if (route === "find") {
+			if (req.method !== "GET") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			if (!requested) {
+				json(res, 400, { error: "path is required" });
+				return;
+			}
+			const resolved = resolveExisting(hostFiles, requested);
+			if (!resolved.ok) {
+				json(res, resolved.status, { error: resolved.error });
+				return;
+			}
+			if (resolved.kind !== "dir") {
+				json(res, 400, { error: "not a directory" });
+				return;
+			}
+			const asked = Number(url.searchParams.get("limit") ?? "");
+			const limit = Number.isFinite(asked) && asked > 0 ? Math.min(asked, 200) : 50;
+			const result = searchFiles(resolved.path, {
+				query: url.searchParams.get("q") ?? "",
+				limit,
+				ignore: options.hostFiles?.ignore
+			});
+			json(res, 200, {
+				base: resolved.path,
+				...result
+			});
+			return;
+		}
+		if (route === "list" || route === "read") {
+			if (req.method !== "GET") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			if (!requested) {
+				json(res, 400, { error: "path is required" });
+				return;
+			}
+			const resolved = resolveExisting(hostFiles, requested);
+			if (!resolved.ok) {
+				json(res, resolved.status, { error: resolved.error });
+				return;
+			}
+			if (route === "list") {
+				if (resolved.kind !== "dir") {
+					json(res, 400, { error: "not a directory" });
+					return;
+				}
+				let names;
+				try {
+					names = readdirSync(resolved.path, { withFileTypes: true });
+				} catch {
+					json(res, 403, { error: "directory is not readable" });
+					return;
+				}
+				const truncated = names.length > maxHostDirEntries;
+				const entries = names.slice(0, maxHostDirEntries).map((entry) => {
+					const path = join(resolved.path, entry.name);
+					const type = entryKind(entry);
+					let bytes;
+					let modifiedAt;
+					if (type === "file") try {
+						const s = lstatSync(path);
+						bytes = s.size;
+						modifiedAt = s.mtimeMs;
+					} catch {}
+					return {
+						name: entry.name,
+						path,
+						type,
+						bytes,
+						modifiedAt
+					};
+				});
+				entries.sort((a, b) => {
+					const rank = (t) => t === "dir" ? 0 : 1;
+					return rank(a.type) - rank(b.type) || a.name.localeCompare(b.name);
+				});
+				json(res, 200, {
+					path: resolved.path,
+					entries,
+					...truncated ? { truncated } : {}
+				});
+				return;
+			}
+			if (resolved.kind !== "file") {
+				json(res, 400, { error: "not a regular file" });
+				return;
+			}
+			let modifiedAt = 0;
+			try {
+				const stats = lstatSync(resolved.path);
+				if (stats.size > maxHostFileBytes) {
+					json(res, 413, { error: `file is larger than ${maxHostFileBytes} bytes` });
+					return;
+				}
+				modifiedAt = stats.mtimeMs;
+			} catch {
+				json(res, 404, { error: "not found" });
+				return;
+			}
+			const read = readContained(resolved.path);
+			if (!read.ok) {
+				json(res, read.status, { error: read.error });
+				return;
+			}
+			if (read.data.length > maxHostFileBytes) {
+				json(res, 413, { error: `file is larger than ${maxHostFileBytes} bytes` });
+				return;
+			}
+			const text = asUtf8(read.data);
+			json(res, 200, {
+				path: resolved.path,
+				content: text ?? read.data.toString("base64"),
+				encoding: text === null ? "base64" : "utf8",
+				bytes: read.data.length,
+				hash: hashBytes(read.data),
+				modifiedAt
+			});
+			return;
+		}
+		if (route === "write") {
+			if (req.method !== "PUT") {
+				json(res, 405, { error: "method not allowed" });
+				return;
+			}
+			if (!hostFilesWritable) {
+				json(res, 403, { error: "host file writes are not enabled on this server" });
+				return;
+			}
+			const body = await readJsonBody(req, maxBodyBytes);
+			if (!body.path || typeof body.path !== "string") {
+				json(res, 400, { error: "path is required" });
+				return;
+			}
+			if (typeof body.content !== "string") {
+				json(res, 400, { error: "content is required" });
+				return;
+			}
+			if (body.encoding !== void 0 && body.encoding !== "utf8" && body.encoding !== "base64") {
+				json(res, 400, { error: "encoding must be 'utf8' or 'base64'" });
+				return;
+			}
+			const resolved = resolveForWrite(hostFiles, body.path);
+			if (!resolved.ok) {
+				json(res, resolved.status, { error: resolved.error });
+				return;
+			}
+			const next = Buffer.from(body.content, body.encoding ?? "utf8");
+			if (next.length > maxHostFileBytes) {
+				json(res, 413, { error: `content is larger than ${maxHostFileBytes} bytes` });
+				return;
+			}
+			const current = readContained(resolved.path);
+			if (!current.ok && current.status !== 404) {
+				json(res, current.status, { error: current.error });
+				return;
+			}
+			const existing = current.ok ? current.data : null;
+			if (existing && !body.expectedHash) {
+				json(res, 409, { error: "file exists — pass expectedHash to overwrite it" });
+				return;
+			}
+			if (existing && hashBytes(existing) !== body.expectedHash) {
+				json(res, 409, { error: "file changed on disk since it was read" });
+				return;
+			}
+			if (!existing && body.expectedHash) {
+				json(res, 409, { error: "file no longer exists" });
+				return;
+			}
+			const written = writeContained(resolved.path, next);
+			if (!written.ok) {
+				json(res, written.status, { error: written.error });
+				return;
+			}
+			let writtenAt = 0;
+			try {
+				writtenAt = lstatSync(resolved.path).mtimeMs;
+			} catch {}
+			json(res, 200, {
+				path: resolved.path,
+				bytes: next.length,
+				hash: hashBytes(next),
+				modifiedAt: writtenAt
+			});
+			return;
+		}
+		json(res, 404, { error: "not found" });
+	};
 	const listSdkSessions = options.listSdkSessions ?? defaultSdkSessionLister;
 	const handleSdkSessions = async (req, res) => {
 		if (req.method !== "GET") {
@@ -1526,6 +2125,14 @@ function createWorkerServer(options = {}) {
 			await handleSdkSessions(req, res);
 			return;
 		}
+		if (pathname.startsWith(basePath + "/fs/")) {
+			if (!(await authenticate(req)).ok) {
+				json(res, 401, { error: "unauthorized" });
+				return;
+			}
+			await handleHostFiles(req, res, pathname);
+			return;
+		}
 		const route = parseRoute(req.url ?? "/");
 		if (!route || route.ws) {
 			json(res, 404, { error: "not found" });