@ssebastien/tcmd 0.1.3 → 0.1.7

package/src/js/tcmd/web/opfs.js

@@ -15,9 +15,17 @@
 // creating parents) backs the demo seeding in `web/main.js`.
 //
 // Trash: OPFS has no system trash, so `trash(paths)` moves entries into a
-// `/.trash` directory at the storage root, where they stay browsable.
+// `/.trash` directory at the storage root, recording original paths in
+// `/.trash/index.json` so `trashList()`/`restore()` can browse and undelete
+// them across reloads.
 
+import { mapLimit } from "../core/concurrency.js"
 import { basename, extname, join, normalize, parent, split } from "../core/path.js"
+import { PREVIEW_BYTES } from "../core/preview.js"
+
+// Constant: OPFS_READDIR_CONCURRENCY
+// Bounded window for the per-entry `getFile` metadata calls of a listing.
+const OPFS_READDIR_CONCURRENCY = 64
 
 // Function: createOpfsFs
 // Builds the filesystem adapter. `root` overrides the OPFS root handle (tests);
@@ -129,23 +137,36 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 	}
 
 	// Function: readDir
-	// Lists `path` as FileEntry-like rows.
+	// Lists `path` as FileEntry-like rows. Directory handles arrive through an
+	// async iterator, but each file's metadata (`getFile`) is an independent
+	// async call, so the entries are mapped with a bounded window instead of
+	// one await at a time.
 	async function readDir(path) {
 		const directory = await resolveDir(normalize(path))
-		const entries = []
-		for await (const handle of directory.values()) entries.push(await toEntry(path, handle))
-		return entries
+		const handles = []
+		for await (const handle of directory.values()) handles.push(handle)
+		return mapLimit(handles, OPFS_READDIR_CONCURRENCY, (handle) => toEntry(path, handle))
 	}
 
 	// Function: readTextHead
 	// Leading `maxBytes` of a text file, decoded as UTF-8.
-	async function readTextHead(path, maxBytes = 65536) {
+	async function readTextHead(path, maxBytes = PREVIEW_BYTES) {
 		const handle = await resolveFile(normalize(path))
 		if (!handle) throw notFound(path)
 		const file = await handle.getFile()
 		return file.slice(0, maxBytes).text()
 	}
 
+	// Function: readBytes
+	// Leading `maxBytes` of a file as raw bytes, for the compressed previews
+	// `core/session` decompresses.
+	async function readBytes(path, maxBytes = PREVIEW_BYTES) {
+		const handle = await resolveFile(normalize(path))
+		if (!handle) throw notFound(path)
+		const file = await handle.getFile()
+		return new Uint8Array(await file.slice(0, maxBytes).arrayBuffer())
+	}
+
 	// Function: du
 	// Recursive size in bytes; unreadable entries contribute 0.
 	async function du(path) {
@@ -176,14 +197,19 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 	// Function: copy
 	// Recursive copy of a file or directory; an existing directory target is
 	// merged into (the operations layer already appends the basename when the
-	// user copies "into" a directory).
+	// user copies "into" a directory), but colliding entries are never replaced.
 	async function copy(from, to) {
+		assertOutsideTrash(to)
+		return withPathLock(to, () => copyEntry(from, to))
+	}
+
+	async function copyEntry(from, to) {
+		await assertCopySafe(from, to)
 		const stats = await stat(from)
-		if (!stats) throw notFound(from)
 		if (stats.isDir) {
 			if (!(await stat(to))?.isDir) await ensureDir(to)
 			for await (const handle of (await resolveDir(from)).values()) {
-				await copy(join(from, handle.name), join(to, handle.name))
+				await copyEntry(join(from, handle.name), join(to, handle.name))
 			}
 			return
 		}
@@ -195,6 +221,25 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 		await writable.close()
 	}
 
+	async function assertCopySafe(from, to) {
+		const sourcePath = normalize(from)
+		const targetPath = normalize(to)
+		const source = await stat(sourcePath)
+		if (!source) throw notFound(from)
+		if (
+			sourcePath === targetPath ||
+			(source.isDir && targetPath.startsWith(sourcePath === "/" ? "/" : `${sourcePath}/`))
+		) {
+			throw new Error(`cannot copy a path into itself: ${to}`)
+		}
+		const destination = await stat(targetPath)
+		if (!destination) return
+		if (!source.isDir || !destination.isDir) throw pathExistsError(to)
+		for (const entry of await readDir(sourcePath)) {
+			await assertCopySafe(entry.path, join(targetPath, entry.name))
+		}
+	}
+
 	// Function: eraseOne
 	// Removes one entry (recursively for directories); the root is a no-op.
 	async function eraseOne(path) {
@@ -204,19 +249,174 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 		await directory.removeEntry(basename(normalized), { recursive: true })
 	}
 
+	// Function: mkdir
+	// Creates `path` (and its parents) as a directory.
+	async function mkdir(path) {
+		const normalized = normalize(path)
+		assertOutsideTrash(normalized)
+		if (normalized === "/") return
+		return withPathLock(normalized, () => ensureDir(normalized))
+	}
+
+	// Constant: TRASH_DIR / TRASH_INDEX
+	// Trashed entries live under `/.trash/<name>` and the original paths are
+	// recorded in `/.trash/index.json`, so a restore survives a reload.
+	const TRASH_DIR = "/.trash"
+	const TRASH_INDEX = `${TRASH_DIR}/index.json`
+
+	// Function: readTrashIndex
+	// The trash index rows, or [] when the index is missing.
+	async function readTrashIndex() {
+		try {
+			const handle = await resolveFile(TRASH_INDEX)
+			if (!handle) return []
+			const parsed = JSON.parse(await (await handle.getFile()).text())
+			if (!Array.isArray(parsed)) throw new Error("invalid OPFS trash index")
+			return parsed
+		} catch (error) {
+			if (error?.code === "ENOENT" || error?.name === "NotFoundError") return []
+			throw error
+		}
+	}
+
+	async function writeTrashIndex(rows) {
+		await writeTextFile(TRASH_INDEX, JSON.stringify(rows))
+	}
+
 	// Function: trash
-	// Moves entries into `/.trash` under a timestamped name, keeping them
-	// available for inspection instead of deleting them.
+	// Moves entries into `/.trash` under a timestamped name, recording each
+	// original path in the index so it can be listed and restored.
 	let trashSeq = 0
+	let trashQueue = Promise.resolve()
+	const pathQueues = new Map()
+	function withPathLocks(paths, action) {
+		const keys = [
+			...new Set(
+				paths.flatMap((path) => {
+					const chain = []
+					let current = normalize(path)
+					while (current !== "/") {
+						chain.push(current)
+						current = parent(current) ?? "/"
+					}
+					if (!chain.length) chain.push("/")
+					return chain
+				}),
+			),
+		].sort()
+		const locks = globalThis.navigator?.locks
+		const run = (index) => {
+			if (index === keys.length) return action()
+			const key = keys[index]
+			if (locks?.request) return locks.request(`tcmd-opfs-path:${key}`, { mode: "exclusive" }, () => run(index + 1))
+			const previous = pathQueues.get(key) ?? Promise.resolve()
+			let release
+			const gate = new Promise((resolve) => (release = resolve))
+			const tail = previous.then(() => gate)
+			pathQueues.set(key, tail)
+			return previous.then(() => run(index + 1)).finally(() => {
+				release()
+				if (pathQueues.get(key) === tail) pathQueues.delete(key)
+			})
+		}
+		return run(0)
+	}
+	const withPathLock = (path, action) => withPathLocks([path], action)
+
+	function withTrashLock(action) {
+		const locks = globalThis.navigator?.locks
+		if (locks?.request) return locks.request("tcmd-opfs-trash-index", { mode: "exclusive" }, action)
+		// ponytail: fallback serialization is adapter-local; Web Locks handles tabs where available.
+		const pending = trashQueue.then(action, action)
+		trashQueue = pending.catch(() => {})
+		return pending
+	}
+
 	async function trash(paths) {
-		await ensureDir("/.trash")
-		for (const path of paths) {
-			const normalized = normalize(path)
-			if (normalized === "/") continue
-			const name = `${Date.now()}-${++trashSeq}-${basename(normalized)}`
-			await copy(normalized, join("/.trash", name))
-			await eraseOne(normalized)
+		return withTrashLock(async () => {
+			await ensureDir(TRASH_DIR)
+			const index = await readTrashIndex()
+			const trashed = []
+			for (const path of paths) {
+				const normalized = normalize(path)
+				if (normalized === "/") continue
+				assertOutsideTrash(normalized)
+				await withPathLocks([normalized, TRASH_DIR], async () => {
+					let name
+					let to
+					do {
+						name = `${Date.now()}-${++trashSeq}-${basename(normalized)}`
+						to = join(TRASH_DIR, name)
+					} while (await stat(to))
+					await copyEntry(normalized, to)
+					const row = { name, originalPath: normalized, deletedAt: new Date().toISOString() }
+					index.push(row)
+					try {
+						await writeTrashIndex(index)
+					} catch (error) {
+						index.pop()
+						await eraseOne(to)
+						throw error
+					}
+					trashed.push({ from: normalized, to, name })
+					// Persist the restore record before removing the source. If removing
+					// it fails, both copies remain discoverable rather than losing the
+					// only restore metadata.
+					await eraseOne(normalized)
+				})
+			}
+			return trashed
+		})
+	}
+
+	// Function: trashList
+	// The trash rows, newest first. Entries whose copy is gone are skipped.
+	async function trashList() {
+		const index = await readTrashIndex()
+		const rows = []
+		for (const row of index) {
+			const trashPath = join(TRASH_DIR, row.name)
+			const stats = await stat(trashPath)
+			if (!stats) continue
+			rows.push({
+				name: row.name,
+				originalPath: row.originalPath ?? null,
+				deletedAt: row.deletedAt ?? null,
+				trashPath,
+				isDir: Boolean(stats.isDir),
+			})
 		}
+		return rows.sort((a, b) => `${b.deletedAt ?? ""}`.localeCompare(`${a.deletedAt ?? ""}`))
+	}
+
+	// Function: restore
+	// Moves trashed entries back to their recorded original paths.
+	async function restore(trashPaths) {
+		return withTrashLock(async () => {
+			const wanted = new Set((trashPaths ?? []).map((path) => normalize(path)))
+			const index = await readTrashIndex()
+			const rows = index.filter((row) => wanted.has(normalize(join(TRASH_DIR, row.name))) && row.originalPath)
+			if (rows.length !== wanted.size) throw new Error("unknown trash entry")
+			const destinations = rows.map((row) => normalize(row.originalPath))
+			if (new Set(destinations).size !== destinations.length) throw pathExistsError(destinations[0])
+			for (const destination of destinations) assertOutsideTrash(destination)
+			assertNoNestedDestinations(destinations)
+			for (const row of rows) {
+				if (await stat(row.originalPath)) throw pathExistsError(row.originalPath)
+			}
+			let remaining = index.slice()
+			for (const row of rows) {
+				const trashPath = join(TRASH_DIR, row.name)
+				await withPathLocks([trashPath, row.originalPath], async () => {
+					await ensureDir(parent(row.originalPath) ?? "/")
+					if (await stat(row.originalPath)) throw pathExistsError(row.originalPath)
+					await copyEntry(trashPath, row.originalPath)
+					remaining = remaining.filter((candidate) => candidate !== row)
+					await writeTrashIndex(remaining)
+					await eraseOne(trashPath)
+				})
+			}
+		})
 	}
 
 	// Function: touch
@@ -224,21 +424,29 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 	// (OPFS exposes no utimes).
 	async function touch(path) {
 		const normalized = normalize(path)
-		const stats = await stat(normalized)
-		if (stats?.isDir) return
-		const directory = await resolveDir(parent(normalized) ?? "/")
-		const handle = await directory.getFileHandle(basename(normalized), { create: true })
-		if (!stats) return
-		const bytes = await (await handle.getFile()).arrayBuffer()
-		const writable = await handle.createWritable()
-		await writable.write(bytes)
-		await writable.close()
+		assertOutsideTrash(normalized)
+		return withPathLock(normalized, async () => {
+			const stats = await stat(normalized)
+			if (stats?.isDir) return
+			const directory = await resolveDir(parent(normalized) ?? "/")
+			const handle = await directory.getFileHandle(basename(normalized), { create: true })
+			if (!stats) return
+			const bytes = await (await handle.getFile()).arrayBuffer()
+			const writable = await handle.createWritable()
+			await writable.write(bytes)
+			await writable.close()
+		})
 	}
 
 	// Function: writeText
 	// Creates (or replaces) a UTF-8 text file, creating parent directories.
 	async function writeText(path, text) {
 		const normalized = normalize(path)
+		assertOutsideTrash(normalized)
+		return withPathLock(normalized, () => writeTextFile(normalized, text))
+	}
+
+	async function writeTextFile(normalized, text) {
 		const directory = await resolveDir(parent(normalized) ?? "/", { create: true })
 		const handle = await directory.getFileHandle(basename(normalized), { create: true })
 		const writable = await handle.createWritable()
@@ -246,21 +454,64 @@ function createOpfsFs({ root, home = "/home/tester" } = {}) {
 		await writable.close()
 	}
 
+	function assertOutsideTrash(path) {
+		const normalized = normalize(path)
+		if (normalized === TRASH_DIR || normalized.startsWith(`${TRASH_DIR}/`)) {
+			const error = new Error(`reserved OPFS trash path: ${normalized}`)
+			error.code = "EPERM"
+			throw error
+		}
+	}
+
 	return {
 		readDir,
 		stat,
+		async realpath(path) {
+			const normalized = normalize(path)
+			if (!(await stat(normalized))) throw notFound(path)
+			return normalized
+		},
 		isDir: async (path) => Boolean((await stat(path))?.isDir),
 		readTextHead,
+		readBytes,
 		du,
 		disk,
 		copy,
 		move: async (from, to) => {
-			await copy(from, to)
-			await eraseOne(from)
+			assertOutsideTrash(from)
+			assertOutsideTrash(to)
+			return withPathLocks([from, to], async () => {
+				if (await stat(to)) throw pathExistsError(to)
+				await copyEntry(from, to)
+				await eraseOne(from)
+			})
+		},
+		// OPFS has no links, ownership or permission modes. The operations
+		// report a clear error instead of silently doing nothing.
+		hardlink: async () => {
+			throw new Error("hard links are not available in the browser filesystem")
+		},
+		symlink: async () => {
+			throw new Error("symbolic links are not available in the browser filesystem")
 		},
+		chmod: async () => {
+			throw new Error("permission modes are not available in the browser filesystem")
+		},
+		chown: async () => {
+			throw new Error("ownership is not available in the browser filesystem")
+		},
+		unlink: async (path) => {
+			throw new Error(`not a symbolic link: ${path}`)
+		},
+		mkdir,
 		trash,
+		trashList,
+		restore,
 		erase: async (paths) => {
-			for (const path of paths) await eraseOne(path)
+			for (const path of paths) {
+				assertOutsideTrash(path)
+				await withPathLock(path, () => eraseOne(path))
+			}
 		},
 		touch,
 		writeText,
@@ -277,6 +528,22 @@ function notFound(path) {
 	return error
 }
 
+function pathExistsError(path) {
+	const error = new Error(`destination already exists: ${path}`)
+	error.code = "EEXIST"
+	return error
+}
+
+function assertNoNestedDestinations(paths) {
+	for (let i = 0; i < paths.length; i++) {
+		for (let j = i + 1; j < paths.length; j++) {
+			if (paths[j].startsWith(`${paths[i]}/`) || paths[i].startsWith(`${paths[j]}/`)) {
+				throw pathExistsError(paths[j])
+			}
+		}
+	}
+}
+
 export { createOpfsFs }
 
 // EOF

package/src/js/tcmd/web/seed.js

@@ -23,9 +23,9 @@ const DEMO_TREE = {
 		"- Left/Backspace  go to the parent directory",
 		"- Tab  switch pane",
 		"- Space  mark the current entry",
-		"- b / g  record / jump to a bookmark",
-		"- ^P  command palette",
-		"- :  scripting mode (copy, move, delete, ...)",
+		"- b  bookmarks (filter, add current path, Enter open, Del remove)",
+		"- :  command panel (operations and app actions)",
+		"- !  shell command",
 		"- q  quit (unmounts the UI; reload to start over)",
 		"",
 		"Open/edit/run are not available in the browser: the web uses the null",
@@ -47,7 +47,7 @@ const DEMO_TREE = {
 		"----",
 		"[x] two panes",
 		"[x] named bookmarks",
-		"[x] command palette",
+		"[x] command panel",
 		"[ ] quick find",
 	].join("\n"),
 	"/documents/welcome.txt": [

package/src/js/tcmd/web/server.js

@@ -8,13 +8,16 @@
 // filesystem API (`/api/*`) over the Node filesystem adapter, so browsers
 // without OPFS (or users who want to browse real files) can run the web UI.
 //
-// Security: binds to loopback only by default and requires the per-process
-// token, injected into `index.html` at serve time, on every API request. When
-// `root` is set, every path is confined to it. This is a local development
+// Security: binds to loopback only by default (`HOST` overrides the address)
+// and requires the per-process token, injected into `index.html` at serve
+// time, on every API request. When `root` is set, every path is confined to
+// it. This is a local development
 // tool, not a sandbox: it serves the same files `bun run tcmd` can reach, so
 // do not expose the port.
 
-import { resolve as resolvePath, sep } from "node:path"
+import nodeFs from "node:fs/promises"
+import { dirname, isAbsolute, relative, resolve as resolvePath, sep } from "node:path"
+import { encodeBase64 } from "../core/base64.js"
 import { createNodeFs } from "../core/fs.js"
 
 // Constant: TOKEN_PLACEHOLDER
@@ -24,33 +27,78 @@ const TOKEN_PLACEHOLDER = "__TCMD_TOKEN__"
 // Function: createWebServer
 // Builds the server. `port` 0 picks a free port (tests); `root` defaults to
 // "/" (the whole filesystem, like the TUI); `token` defaults to a fresh UUID.
+// `hostname` and `port` default to the HOST and PORT environment variables.
 function createWebServer({
 	root = process.env.TCMD_WEB_ROOT ?? "/",
 	port = Number(process.env.PORT ?? 8787),
-	hostname = "127.0.0.1",
+	hostname = process.env.HOST || "127.0.0.1",
 	publicDir = new URL("../../../../public/", import.meta.url),
 	token = crypto.randomUUID(),
 } = {}) {
 	const fs = createNodeFs()
 	const base = resolvePath(root)
 	const rootHref = publicDir instanceof URL ? publicDir : new URL(`${publicDir.replace(/\/?$/, "/")}`, "file:///")
+	let realBasePromise
 
 	// Function: withinRoot
 	// True when `path` is the configured root or inside it.
 	function withinRoot(path) {
+		if (typeof path !== "string" || !path) return false
 		const resolved = resolvePath(path)
-		return base === sep || resolved === base || resolved.startsWith(base + sep)
+		return isWithin(base, resolved)
 	}
 
 	// Function: confine
-	// Resolves a client path and rejects it when it escapes the root.
-	function confine(path) {
+	// Resolves a client path and rejects lexical or symlink escapes from root.
+	async function confine(path) {
 		if (typeof path !== "string" || !path) throw httpError(400, "missing path")
 		const resolved = resolvePath(path)
 		if (!withinRoot(resolved)) throw httpError(403, `path outside ${base}`)
+		realBasePromise ??= nodeFs.realpath(base)
+		const realBase = await realBasePromise
+		const candidate = resolvePath(realBase, relative(base, resolved))
+		await checkSymlinks(candidate, realBase)
 		return resolved
 	}
 
+	// Function: confineSymlinkTarget
+	// Validates a symlink target without rewriting it: an absolute target is
+	// resolved as-is, a relative one against the link's directory, and either
+	// must stay inside the configured root. The original target text is passed
+	// to `fs.symlink`, so relative links keep working if the tree moves.
+	function confineSymlinkTarget(target, link) {
+		if (typeof target !== "string" || !target) throw httpError(400, "missing target")
+		const resolved = isAbsolute(target) ? resolvePath(target) : resolvePath(dirname(link), target)
+		if (!isWithin(base, resolved)) throw httpError(403, `target outside ${base}`)
+		return target
+	}
+
+	// Function: checkSymlinks
+	// Resolves each existing symlink component and ensures its target stays in
+	// root. Dangling links are checked too, so a later write cannot follow one
+	// outside the configured tree.
+	async function checkSymlinks(path, realBase, seen = new Set()) {
+		if (!isWithin(realBase, path)) throw httpError(403, `path outside ${base}`)
+		let current = realBase
+		for (const part of relative(realBase, path).split(sep).filter(Boolean)) {
+			current = resolvePath(current, part)
+			let stats
+			try {
+				stats = await nodeFs.lstat(current)
+			} catch (error) {
+				if (error?.code === "ENOENT") return
+				throw error
+			}
+			if (!stats.isSymbolicLink()) continue
+			if (seen.has(current) || seen.size >= 40) throw httpError(403, "symbolic link loop")
+			const nextSeen = new Set(seen)
+			nextSeen.add(current)
+			const target = resolvePath(dirname(current), await nodeFs.readlink(current))
+			await checkSymlinks(target, realBase, nextSeen)
+			current = target
+		}
+	}
+
 	// Function: jsonBody
 	// Reads a JSON request body; other content types are refused so cross-site
 	// form posts cannot reach the mutations.
@@ -73,42 +121,92 @@ function createWebServer({
 			home: withinRoot(fs.home()) ? fs.home() : base,
 			cwd: withinRoot(fs.cwd()) ? fs.cwd() : base,
 		}),
-		"GET /api/readDir": (_request, url) => fs.readDir(confine(url.searchParams.get("path"))),
-		"GET /api/stat": (_request, url) => fs.stat(confine(url.searchParams.get("path"))),
+		"GET /api/readDir": async (_request, url) => fs.readDir(await confine(url.searchParams.get("path"))),
+		"GET /api/stat": async (_request, url) => fs.stat(await confine(url.searchParams.get("path"))),
+		"GET /api/realpath": async (_request, url) => fs.realpath(await confine(url.searchParams.get("path"))),
 		"GET /api/readTextHead": async (_request, url) => {
-			const path = confine(url.searchParams.get("path"))
+			const path = await confine(url.searchParams.get("path"))
 			const maxBytes = clampBytes(url.searchParams.get("maxBytes"))
 			return fs.readTextHead(path, maxBytes)
 		},
-		"GET /api/du": (_request, url) => fs.du(confine(url.searchParams.get("path"))),
-		"GET /api/disk": (_request, url) => fs.disk(confine(url.searchParams.get("path"))),
+		"GET /api/readBytes": async (_request, url) => {
+			const path = await confine(url.searchParams.get("path"))
+			const maxBytes = clampBytes(url.searchParams.get("maxBytes"))
+			return { base64: encodeBase64(await fs.readBytes(path, maxBytes)) }
+		},
+		"GET /api/du": async (_request, url) => fs.du(await confine(url.searchParams.get("path"))),
+		"GET /api/disk": async (_request, url) => fs.disk(await confine(url.searchParams.get("path"))),
 		"POST /api/copy": async (request) => {
 			const body = await jsonBody(request)
-			return fs.copy(confine(body.from), confine(body.to))
+			const [from, to] = await Promise.all([confine(body.from), confine(body.to)])
+			return fs.copy(from, to)
 		},
 		"POST /api/move": async (request) => {
 			const body = await jsonBody(request)
-			return fs.move(confine(body.from), confine(body.to))
+			const [from, to] = await Promise.all([confine(body.from), confine(body.to)])
+			return fs.move(from, to)
+		},
+		"POST /api/hardlink": async (request) => {
+			const body = await jsonBody(request)
+			const [from, to] = await Promise.all([confine(body.from), confine(body.to)])
+			return fs.hardlink(from, to)
+		},
+		"POST /api/symlink": async (request) => {
+			const body = await jsonBody(request)
+			const link = await confine(body.link)
+			return fs.symlink(confineSymlinkTarget(body.target, link), link)
+		},
+		"POST /api/chmod": async (request) => {
+			const body = await jsonBody(request)
+			const mode = Number(body.mode)
+			if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) throw httpError(400, "invalid mode")
+			return fs.chmod(await confine(body.path), mode)
+		},
+		"POST /api/chown": async (request) => {
+			const body = await jsonBody(request)
+			if (typeof body.owner !== "string" || !body.owner) throw httpError(400, "missing owner")
+			return fs.chown(await confine(body.path), body.owner)
+		},
+		"POST /api/unlink": async (request) => {
+			const body = await jsonBody(request)
+			return fs.unlink(await confine(body.path))
+		},
+		"POST /api/mkdir": async (request) => {
+			const body = await jsonBody(request)
+			return fs.mkdir(await confine(body.path))
 		},
 		"POST /api/trash": async (request) => {
 			const body = await jsonBody(request)
-			return fs.trash(confinePaths(body.paths))
+			return fs.trash(await confinePaths(body.paths))
+		},
+		"GET /api/trashList": async () => (await fs.trashList()).filter((row) => withinRoot(row.originalPath)),
+		"POST /api/restore": async (request) => {
+			const body = await jsonBody(request)
+			if (!Array.isArray(body.paths)) throw httpError(400, "expected a paths array")
+			// Only trash entries whose original destinations are inside this
+			// server's root are visible or restorable.
+			const known = new Set((await fs.trashList()).filter((row) => withinRoot(row.originalPath)).map((row) => row.trashPath))
+			for (const path of body.paths) {
+				if (!known.has(path)) throw httpError(403, `unknown trash entry: ${path}`)
+			}
+			// Revalidate the metadata destination at the point it is used, too.
+			return fs.restore(body.paths, { validateDestination: confine })
 		},
 		"POST /api/erase": async (request) => {
 			const body = await jsonBody(request)
-			return fs.erase(confinePaths(body.paths))
+			return fs.erase(await confinePaths(body.paths))
 		},
 		"POST /api/touch": async (request) => {
 			const body = await jsonBody(request)
-			return fs.touch(confine(body.path))
+			return fs.touch(await confine(body.path))
 		},
 	}
 
 	// Function: confinePaths
 	// Validates a `paths` array before a bulk operation.
-	function confinePaths(paths) {
+	async function confinePaths(paths) {
 		if (!Array.isArray(paths)) throw httpError(400, "expected a paths array")
-		return paths.map(confine)
+		return Promise.all(paths.map(confine))
 	}
 
 	// Function: handleApi
@@ -123,7 +221,7 @@ function createWebServer({
 			const value = await route(request, url)
 			return json(value === undefined ? { ok: true } : value)
 		} catch (error) {
-			const status = error?.status ?? (error?.code === "ENOENT" ? 404 : 500)
+			const status = error?.status ?? (error?.code === "ENOENT" ? 404 : error?.code === "EEXIST" ? 409 : 500)
 			return json({ error: `${error?.message ?? error}` }, status)
 		}
 	}
@@ -170,6 +268,11 @@ function json(payload, status = 200) {
 	return Response.json(payload, { status, headers: { "Cache-Control": "no-store" } })
 }
 
+function isWithin(root, path) {
+	const relativePath = relative(root, path)
+	return relativePath === "" || (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath))
+}
+
 // Function: httpError
 // Error carrying the HTTP status the API should answer with.
 function httpError(status, message) {