@hoardodile/host 0.0.0

package/src/sandbox/host.unit.test.ts

@@ -0,0 +1,330 @@
+import { tmpdir } from "node:os"
+import { join, resolve, sep } from "node:path"
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+import type { ResourceAPI } from "../types.ts"
+import {
+	createPluginSandbox,
+	DEFAULT_SANDBOX_CONFIG,
+	type PluginSandbox,
+	type PluginSandboxConfig,
+} from "./host.ts"
+
+/**
+ * Deterministic lifecycle tests: a scripted fake ChildProcess lets us hit
+ * race windows (stale messages, concurrent loads) that real forked
+ * processes only reproduce flakily. Only this file sees the mock — the
+ * real `spawn` probe answers the first permission-flag candidate so the
+ * sandbox never actually starts a process here.
+ */
+const mocks = vi.hoisted(() => {
+	class FakeChild {
+		static instances: FakeChild[] = []
+		private readonly listeners = new Map<
+			string,
+			((...args: unknown[]) => void)[]
+		>()
+		readonly sent: unknown[] = []
+		readonly args: unknown[]
+		killed = false
+
+		constructor(...args: unknown[]) {
+			this.args = args
+			FakeChild.instances.push(this)
+		}
+
+		on(event: string, fn: (...args: unknown[]) => void): this {
+			const list = this.listeners.get(event) ?? []
+			list.push(fn)
+			this.listeners.set(event, list)
+			return this
+		}
+
+		emit(event: string, ...args: unknown[]): void {
+			for (const fn of this.listeners.get(event) ?? []) fn(...args)
+		}
+
+		send(msg: unknown): void {
+			this.sent.push(msg)
+		}
+
+		kill(): void {
+			this.killed = true
+		}
+
+		ref(): this {
+			return this
+		}
+
+		unref(): this {
+			return this
+		}
+	}
+	return { FakeChild }
+})
+
+vi.mock("node:child_process", () => ({
+	fork: (...args: unknown[]) => new mocks.FakeChild(...args),
+	spawn: (...args: unknown[]) => {
+		const child = new mocks.FakeChild(...args)
+		// The permission-flag probe resolves as soon as the listeners are
+		// attached — report the first candidate as accepted.
+		queueMicrotask(() => child.emit("exit", 0))
+		return child
+	},
+}))
+
+function unitConfig(overrides: Partial<PluginSandboxConfig> = {}) {
+	return {
+		...DEFAULT_SANDBOX_CONFIG,
+		...overrides,
+	} satisfies PluginSandboxConfig
+}
+
+function lastChild(): InstanceType<typeof mocks.FakeChild> {
+	const child = mocks.FakeChild.instances.at(-1)
+	if (child === undefined) throw new Error("no sandbox child spawned")
+	return child
+}
+
+function createStubApi(overrides: Partial<ResourceAPI> = {}): ResourceAPI {
+	return {
+		logInfo() {},
+		logWarn() {},
+		logError() {},
+		context: { detect: undefined },
+		listFileNames: async () => [],
+		readFile: async () => new Uint8Array(),
+		statFile: async () => ({ sizeBytes: 0 }),
+		statFiles: async (paths) => paths.map(() => ({ sizeBytes: 0 })),
+		sniff: async () => undefined,
+		probe: async () => ({ kind: "unknown", reason: "unavailable" }),
+		hashBytes: async () => "ab",
+		computeImageHashes: async () => undefined,
+		listContainer: async () => ({ entries: [] }),
+		extractArchive: async () => ({ entries: [] }),
+		download: async () => {
+			throw new Error("stub: download not configured")
+		},
+		statAsset: async () => undefined,
+		readAsset: async () => new Uint8Array(),
+		deleteAsset: async () => ({ existed: false }),
+		...overrides,
+	}
+}
+
+/** Flush microtasks and pending macrotasks. */
+function flush(): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+describe("plugin sandbox lifecycle (fake child process)", () => {
+	let sandbox: PluginSandbox | undefined
+
+	beforeEach(() => {
+		mocks.FakeChild.instances.length = 0
+	})
+
+	afterEach(async () => {
+		await sandbox?.disposeAll()
+		sandbox = undefined
+		vi.restoreAllMocks()
+	})
+
+	test("a plugin that fails to load has its sandbox child terminated", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {})
+		sandbox = createPluginSandbox(unitConfig())
+		const load = sandbox.loadPlugin({
+			id: "bad",
+			mainPath: "/plugins/bad/main.js",
+			eager: true,
+		})
+		// The fork happens after the (mocked) permission-flag probe settles.
+		await flush()
+		const child = lastChild()
+		child.emit("message", {
+			type: "loaded",
+			ok: false,
+			error: { name: "Error", message: "import exploded" },
+		})
+		await expect(load).resolves.toBeUndefined()
+		expect(child.killed).toBe(true)
+	})
+
+	test("messages from a stale child are ignored", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {})
+		sandbox = createPluginSandbox(unitConfig())
+		// Unload mid-load: the first child's waiter rejects, load returns
+		// undefined, and the child is terminated.
+		const first = sandbox.loadPlugin({
+			id: "p",
+			mainPath: "/p/main.js",
+			eager: true,
+		})
+		await flush()
+		const stale = lastChild()
+		sandbox.unloadPlugin("p")
+		await expect(first).resolves.toBeUndefined()
+		expect(stale.killed).toBe(true)
+
+		// Respawn for the same id.
+		const second = sandbox.loadPlugin({
+			id: "p",
+			mainPath: "/p/main.js",
+			eager: true,
+		})
+		await flush()
+		const current = lastChild()
+		expect(current).not.toBe(stale)
+
+		// The stale child's late "loaded" must not resolve the new spawn's
+		// load waiter — the second load stays pending until ITS child loads.
+		let secondSettled = false
+		void second.then(() => {
+			secondSettled = true
+		})
+		stale.emit("message", { type: "loaded", ok: true, hooks: ["detect"] })
+		await flush()
+		expect(secondSettled).toBe(false)
+
+		current.emit("message", { type: "loaded", ok: true, hooks: ["detect"] })
+		const plugin = await second
+		if (plugin === undefined) throw new Error("plugin load failed")
+
+		// A stale "result" must not resolve a pending call on the new child.
+		const detect = plugin.detect(createStubApi())
+		// Let invoke() register the pending call before delivering results.
+		await flush()
+		stale.emit("message", {
+			type: "result",
+			callId: 1,
+			ok: true,
+			value: { ok: false, reasons: ["stale"] },
+		})
+		current.emit("message", {
+			type: "result",
+			callId: 1,
+			ok: true,
+			value: { ok: true },
+		})
+		await expect(detect).resolves.toEqual({ ok: true })
+	})
+
+	test("concurrent loadPlugin calls for the same id keep the newer state alive", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {})
+		sandbox = createPluginSandbox(unitConfig())
+		const first = sandbox.loadPlugin({
+			id: "p",
+			mainPath: "/p/old.js",
+			eager: true,
+		})
+		await flush()
+		const c1 = lastChild()
+
+		// Second load for the same id while the first is still in flight:
+		// the old child is NOT torn down until the new bundle loads — a
+		// failed reload must never strand the previous child.
+		const second = sandbox.loadPlugin({
+			id: "p",
+			mainPath: "/p/new.js",
+			eager: true,
+		})
+		await flush()
+		expect(c1.killed).toBe(false)
+		const c2 = lastChild()
+		expect(c2).not.toBe(c1)
+
+		// Both bundles load; the newer state owns the id and retires the
+		// previous child only then.
+		c1.emit("message", { type: "loaded", ok: true, hooks: ["detect"] })
+		await first
+		c2.emit("message", { type: "loaded", ok: true, hooks: ["detect"] })
+		const plugin = await second
+		if (plugin === undefined) throw new Error("plugin load failed")
+		expect(c1.killed).toBe(true)
+
+		const detect = plugin.detect(createStubApi())
+		await flush()
+		c2.emit("message", {
+			type: "result",
+			callId: 1,
+			ok: true,
+			value: { ok: true },
+		})
+		await expect(detect).resolves.toEqual({ ok: true })
+
+		// The newer state is still tracked — dispose terminates its child.
+		await sandbox.disposeAll()
+		expect(c2.killed).toBe(true)
+	})
+
+	test("a failed reload keeps the previous child alive and serving", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {})
+		sandbox = createPluginSandbox(unitConfig())
+		const first = sandbox.loadPlugin({
+			id: "p",
+			mainPath: "/p/old.js",
+			eager: true,
+		})
+		await flush()
+		const c1 = lastChild()
+		c1.emit("message", { type: "loaded", ok: true, hooks: ["detect"] })
+		await expect(first).resolves.toBeDefined()
+
+		// Reload with a bundle that fails to import: the load rejects, the
+		// previous child must survive and keep answering hooks.
+		const reload = sandbox.loadPlugin({
+			id: "p",
+			mainPath: "/p/broken.js",
+			eager: true,
+		})
+		await flush()
+		const c2 = lastChild()
+		expect(c2).not.toBe(c1)
+		expect(c1.killed).toBe(false)
+
+		c2.emit("message", {
+			type: "loaded",
+			ok: false,
+			error: { name: "Error", message: "import exploded" },
+		})
+		const restored = await reload
+		if (restored === undefined) throw new Error("reload should fall back")
+		expect(c1.killed).toBe(false)
+
+		// The restored definition still routes through the old child.
+		const detect = restored.detect(createStubApi())
+		await flush()
+		c1.emit("message", {
+			type: "result",
+			callId: 1,
+			ok: true,
+			value: { ok: true },
+		})
+		await expect(detect).resolves.toEqual({ ok: true })
+	})
+
+	test("spawn passes the asset vault dir as an extra read grant and argv", async () => {
+		const vaultDir = join(tmpdir(), "vaults", "p")
+		sandbox = createPluginSandbox(unitConfig({ assetVaultDir: vaultDir }))
+		const plugin = sandbox.loadPlugin({
+			id: "vault-grant",
+			mainPath: "/p/main.js",
+			eager: true,
+		})
+		await flush()
+		const child = lastChild()
+		const [, spawnArgs, spawnOpts] = child.args as [
+			string,
+			string[],
+			{ execArgv: string[] },
+		]
+		expect(spawnArgs.at(2)).toBe(vaultDir)
+		// host.ts grants `${resolve(assetVaultDir)}${sep}` — the asserts
+		// mirror it so POSIX (sep "/") and Windows (sep "\\") both hold.
+		expect(
+			spawnOpts.execArgv.includes(`--allow-fs-read=${resolve(vaultDir)}${sep}`),
+		).toBe(true)
+		child.emit("message", { type: "loaded", ok: true, hooks: ["detect"] })
+		await expect(plugin).resolves.toBeDefined()
+	})
+})

package/src/sandbox/protocol.test.ts

@@ -0,0 +1,85 @@
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { describe, expect, test } from "vitest"
+import {
+	API_METHOD_NAMES,
+	deserializeError,
+	HOOK_NAMES,
+	LOG_METHOD_NAMES,
+	serializeError,
+} from "./protocol.ts"
+
+/**
+ * worker-entry.mjs is plain JS without access to workspace TS sources, so it
+ * keeps its own copies of the hook/API name lists. A drift between the two
+ * copies only surfaces at runtime as "unknown API method" RPC failures —
+ * this test is the compile-time sync guarantee.
+ */
+const workerEntrySource = readFileSync(
+	fileURLToPath(new URL("./worker-entry.mjs", import.meta.url)),
+	"utf-8",
+)
+
+/** Extract the double-quoted items of the first `[...]` list after `name`. */
+function extractStringList(source: string, name: string): string[] {
+	// Anchor on the declaration — the file header mentions the same names.
+	const start = source.indexOf(`const ${name}`)
+	if (start === -1) throw new Error(`${name} not found in worker-entry.mjs`)
+	const open = source.indexOf("[", start)
+	const close = source.indexOf("]", open)
+	if (open === -1 || close === -1) {
+		throw new Error(`${name} list not found in worker-entry.mjs`)
+	}
+	const out: string[] = []
+	for (const m of source.slice(open, close).matchAll(/"([^"]+)"/g)) {
+		if (m[1] !== undefined) out.push(m[1])
+	}
+	return out
+}
+
+describe("protocol ↔ worker-entry name lists", () => {
+	test("HOOK_NAMES match in contract order", () => {
+		expect(extractStringList(workerEntrySource, "HOOK_NAMES")).toEqual([
+			...HOOK_NAMES,
+		])
+	})
+
+	test("API_METHOD_NAMES match in contract order", () => {
+		expect(extractStringList(workerEntrySource, "API_METHOD_NAMES")).toEqual([
+			...API_METHOD_NAMES,
+		])
+	})
+
+	test("LOG_METHOD_NAMES match", () => {
+		expect(
+			extractStringList(workerEntrySource, "LOG_METHOD_NAMES").sort(),
+		).toEqual([...LOG_METHOD_NAMES].sort())
+	})
+})
+
+describe("error code over the sandbox IPC", () => {
+	test("the asset vocabulary round-trips via `code` (name restored verbatim)", () => {
+		const denied = new Error("declined")
+		denied.name = "DENIED"
+		const serialized = serializeError(denied)
+		expect(serialized.code).toBe("DENIED")
+		const restored = deserializeError(serialized)
+		expect(restored.name).toBe("DENIED")
+		expect(restored.message).toBe("declined")
+	})
+
+	test("plain errors carry no code and keep their own name", () => {
+		const serialized = serializeError(new TypeError("boom"))
+		expect(serialized.code).toBeUndefined()
+		expect(deserializeError(serialized).name).toBe("TypeError")
+	})
+
+	test("an explicit wire code wins over the legacy name field", () => {
+		const restored = deserializeError({
+			name: "SomeOldName",
+			code: "POLICY",
+			message: "nope",
+		})
+		expect(restored.name).toBe("POLICY")
+	})
+})

package/src/sandbox/protocol.ts

@@ -0,0 +1,147 @@
+/**
+ * Wire protocol between the plugin sandbox host (server process) and the
+ * sandbox child entry (`worker-entry.mjs`), which runs as a forked child
+ * process with structured-clone IPC. The entry file is plain JS without
+ * access to workspace TS sources, so it keeps its own copy of the
+ * method/hook name lists — keep the two in sync (enforced by
+ * `protocol.test.ts`).
+ */
+
+/**
+ * Plugin hook names the host can invoke, in contract order — defined in
+ * `@hoardodile/sdk-types`, re-exported so host internals keep one import
+ * point.
+ */
+import { HOOK_NAMES, type HookName } from "@hoardodile/sdk-types"
+import { PLUGIN_ASSET_ERROR_NAMES } from "@hoardodile/sdk-types/plugin-asset-limits"
+
+export { HOOK_NAMES, type HookName }
+
+/** ResourceAPI method names bridged over RPC. */
+export const API_METHOD_NAMES = [
+	"logInfo",
+	"logWarn",
+	"logError",
+	"listFileNames",
+	"readFile",
+	"statFile",
+	"statFiles",
+	"sniff",
+	"probe",
+	"hashBytes",
+	"computeImageHashes",
+	"listContainer",
+	"extractArchive",
+	"download",
+	"statAsset",
+	"readAsset",
+	"deleteAsset",
+] as const
+
+export type ApiMethodName = (typeof API_METHOD_NAMES)[number]
+
+/** Fire-and-forget log methods — no response round-trip. */
+export const LOG_METHOD_NAMES: ReadonlySet<ApiMethodName> = new Set([
+	"logInfo",
+	"logWarn",
+	"logError",
+])
+
+export type SerializedError = {
+	readonly name: string
+	readonly message: string
+	readonly stack?: string
+	/**
+	 * Machine-readable plugin error code (`DENIED`/`UNAVAILABLE`/`POLICY`)
+	 * carried verbatim on the wire — the single field the host side reads
+	 * to restore the plugin-facing `err.name`.
+	 */
+	readonly code?: string
+}
+
+// -- host → worker --
+
+export type LoadRequest = {
+	readonly type: "load"
+	readonly mainPath: string
+}
+
+export type InvokeRequest = {
+	readonly type: "invoke"
+	readonly callId: number
+	readonly hook: HookName
+}
+
+export type ApiResponse = {
+	readonly type: "apiResult"
+	readonly apiCallId: number
+	readonly ok: boolean
+	readonly value?: unknown
+	readonly error?: SerializedError
+}
+
+// -- worker → host --
+
+export type LoadResponse = {
+	readonly type: "loaded"
+	readonly ok: boolean
+	readonly hooks?: readonly HookName[]
+	readonly error?: SerializedError
+}
+
+export type InvokeResponse = {
+	readonly type: "result"
+	readonly callId: number
+	readonly ok: boolean
+	readonly value?: unknown
+	readonly error?: SerializedError
+}
+
+export type ApiRequest = {
+	readonly type: "api"
+	readonly callId: number
+	readonly apiCallId: number
+	readonly method: ApiMethodName
+	readonly args: readonly unknown[]
+}
+
+export type LogRequest = {
+	readonly type: "log"
+	readonly callId: number
+	readonly method: "logInfo" | "logWarn" | "logError"
+	readonly args: readonly unknown[]
+}
+
+export type WorkerMessage =
+	| LoadResponse
+	| InvokeResponse
+	| ApiRequest
+	| LogRequest
+
+export function serializeError(err: unknown): SerializedError {
+	if (err instanceof Error) {
+		return {
+			name: err.name,
+			message: err.message,
+			stack: err.stack,
+			// The vocabulary errors carry their code in `name`; the wire
+			// keeps an explicit `code` field so the receiving side never
+			// re-parses or re-derives it.
+			code: isAssetErrorName(err.name) ? err.name : undefined,
+		}
+	}
+	return { name: "Error", message: String(err) }
+}
+
+export function deserializeError(err: SerializedError): Error {
+	const e = new Error(err.message)
+	// `code` is authoritative when present (the vocabulary survived);
+	// `name` falls back for plain host errors.
+	e.name = err.code ?? err.name
+	if (err.stack !== undefined) e.stack = err.stack
+	return e
+}
+
+function isAssetErrorName(name: string): boolean {
+	return (PLUGIN_ASSET_ERROR_NAMES as readonly string[]).includes(name)
+}

package/src/sandbox/sandboxed-plugin.ts

@@ -0,0 +1,30 @@
+import { definePlugin } from "../define-plugin.ts"
+import type { PluginDefinition, ResourceAPI } from "../types.ts"
+import type { HookName } from "./protocol.ts"
+
+export type InvokeFn = (hook: HookName, api: ResourceAPI) => Promise<unknown>
+
+/**
+ * Build a contract-compliant {@link PluginDefinition} that forwards hooks
+ * into a sandboxed worker. Only hooks the plugin actually implements are
+ * exposed — presence is semantic (orchestrators branch on e.g.
+ * `plugin.listFiles === undefined`).
+ */
+export function createSandboxedPlugin(
+	hooks: readonly HookName[],
+	invoke: InvokeFn,
+): PluginDefinition {
+	// RPC boundary: hook signatures share the shape `(api) => Promise<unknown>`;
+	// the concrete return type is enforced by the plugin contract at runtime.
+	const definition: Record<string, (api: ResourceAPI) => Promise<unknown>> = {}
+	for (const hook of hooks) {
+		definition[hook] = async (api: ResourceAPI) => invoke(hook, api)
+	}
+	if (definition.detect === undefined) {
+		definition.detect = async () => ({
+			ok: false,
+			reasons: ["plugin does not implement detect()"],
+		})
+	}
+	return definePlugin(definition as unknown as PluginDefinition)
+}