@hoardodile/host 0.0.0

package/src/hoard/plugin-vault.test.ts

@@ -0,0 +1,160 @@
+import { mkdtempSync } from "node:fs"
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { afterEach, describe, expect, test } from "vitest"
+import {
+	commitVaultFile,
+	discardVaultTempFile,
+	PluginVaultPathError,
+	parsePluginVaultDest,
+	vaultFileSha256,
+	vaultReadFile,
+	vaultRemoveFile,
+	vaultStatFile,
+	vaultTempFile,
+	vaultTotalSize,
+} from "./plugin-vault.ts"
+
+const roots: string[] = []
+
+function vaultDir(): string {
+	const root = mkdtempSync(join(tmpdir(), "hoardodile-vault-"))
+	roots.push(root)
+	return join(root, "vault")
+}
+
+afterEach(async () => {
+	await Promise.all(
+		roots.splice(0).map((r) => rm(r, { recursive: true, force: true })),
+	)
+})
+
+describe("parsePluginVaultDest (isolation)", () => {
+	// Portability: the fixture dir must be a real absolute path on every
+	// OS — a hardcoded Windows drive path broke the POSIX runners.
+	const dir = join(tmpdir(), "vaults", "p")
+
+	test("accepts nested relative destinations", () => {
+		expect(parsePluginVaultDest(dir, "runtime/live2d.min.js")).toEqual({
+			rel: "runtime/live2d.min.js",
+			// assertInside returns `resolve(candidate)`.
+			abs: resolve(dir, "runtime", "live2d.min.js"),
+		})
+	})
+
+	test("rejects traversal", () => {
+		for (const dest of ["../main.js", "a/../../main.js", "..", "a/.."]) {
+			expect(() => parsePluginVaultDest(dir, dest)).toThrow(
+				PluginVaultPathError,
+			)
+		}
+	})
+
+	test("rejects absolute destinations and drive letters", () => {
+		// path-guard-exempt: Windows-style destinations are the behavior under test.
+		for (const dest of ["/etc/passwd", "C:\\windows\\x", "//host/share"]) {
+			expect(() => parsePluginVaultDest(dir, dest)).toThrow()
+		}
+	})
+
+	test("rejects empty segments, reserved names and trailing dots", () => {
+		for (const dest of [
+			"",
+			"a//b",
+			"a/",
+			"CON",
+			"aux.txt",
+			"a/.",
+			"a..",
+			"x.",
+		]) {
+			expect(() => parsePluginVaultDest(dir, dest)).toThrow()
+		}
+	})
+})
+
+describe("vault primitives", () => {
+	test("stat/read/write/commit/remove round-trip with atomic commits", async () => {
+		const dir = vaultDir()
+		await mkdir(dir, { recursive: true })
+
+		expect(await vaultStatFile(dir, "runtime/a.mjs")).toBeUndefined()
+		expect(await vaultRemoveFile(dir, "runtime/a.mjs")).toBe(false)
+
+		const temp = vaultTempFile(dir)
+		await writeFile(temp, "const a = 1\n")
+		const commit = await commitVaultFile({
+			vaultDir: dir,
+			rel: "runtime/a.mjs",
+			tempPath: temp,
+			maxFileBytes: 1024,
+			maxTotalBytes: 4096,
+		})
+		expect(commit.sizeBytes).toBe(12)
+		expect(commit.sha256).toMatch(/^[0-9a-f]{64}$/)
+
+		expect(await vaultStatFile(dir, "runtime/a.mjs")).toEqual({
+			sizeBytes: 12,
+		})
+		expect(
+			new TextDecoder().decode(
+				await vaultReadFile(dir, "runtime/a.mjs", 1_000_000),
+			),
+		).toBe("const a = 1\n")
+		expect(await vaultFileSha256(dir, "runtime/a.mjs")).toBe(commit.sha256)
+		expect(await vaultTotalSize(dir)).toBe(12)
+		expect(await vaultRemoveFile(dir, "runtime/a.mjs")).toBe(true)
+		expect(await vaultTotalSize(dir)).toBe(0)
+	})
+
+	test("commit rejects oversized files and over-quota totals (no partial file)", async () => {
+		const dir = vaultDir()
+		await mkdir(dir, { recursive: true })
+		await writeFile(join(dir, "existing.bin"), "x".repeat(100))
+
+		const tooBig = vaultTempFile(dir)
+		await writeFile(tooBig, "x".repeat(200 + 1))
+		await expect(
+			commitVaultFile({
+				vaultDir: dir,
+				rel: "big.bin",
+				tempPath: tooBig,
+				maxFileBytes: 100,
+				maxTotalBytes: 200,
+			}),
+		).rejects.toThrow(/download cap/)
+		await expect(vaultStatFile(dir, "big.bin")).resolves.toBeUndefined()
+
+		// Replacing an existing file counts the old bytes only once.
+		const fresh = vaultTempFile(dir)
+		await writeFile(fresh, "y".repeat(150))
+		await expect(
+			commitVaultFile({
+				vaultDir: dir,
+				rel: "existing.bin",
+				tempPath: fresh,
+				maxFileBytes: 1000,
+				maxTotalBytes: 200,
+			}),
+		).resolves.toMatchObject({ sizeBytes: 150 })
+		expect(await vaultTotalSize(dir)).toBe(150)
+	})
+
+	test("delete refuses directories and outside-the-vault paths", async () => {
+		const dir = vaultDir()
+		await mkdir(join(dir, "sub"), { recursive: true })
+		await expect(vaultRemoveFile(dir, "sub")).rejects.toThrow(/not a file/)
+		await expect(vaultRemoveFile(dir, "../outside")).rejects.toThrow()
+	})
+
+	test("discard removes temp files without throwing", async () => {
+		const dir = vaultDir()
+		await mkdir(dir, { recursive: true })
+		const temp = vaultTempFile(dir)
+		await writeFile(temp, "partial")
+		await discardVaultTempFile(temp)
+		await expect(readFile(temp)).rejects.toThrow()
+		await expect(discardVaultTempFile(temp)).resolves.toBeUndefined()
+	})
+})

package/src/hoard/plugin-vault.ts

@@ -0,0 +1,233 @@
+/**
+ * The plugin asset vault storage primitives: resolving vault-relative
+ * destinations (the isolation boundary — a `dest` can never escape the
+ * plugin's own vault), reading/statting vault files, removing them, and
+ * committing downloaded files atomically.
+ *
+ * The vault root is `<version>/plugins/<id>/vault` (see
+ * {@link VersionPaths.pluginVaultDir}); the primitives operate on an
+ * explicit vault directory so the server can pass the `latest` version
+ * for writes (inside `writeVersioned`) or the active version for reads.
+ *
+ * Cost note (deliberate): the vault lives inside the versioned tree, so
+ * each archive version snapshots a full copy of it — durability over
+ * deduplication, same as `resources/<id>/data/`.
+ *
+ * Misuse answers {@link PluginAssetError} with `POLICY` so the plugin
+ * sees a machine-readable rejection before any network happens.
+ */
+import { createHash, randomUUID } from "node:crypto"
+import { createReadStream } from "node:fs"
+import { mkdir, readFile, rename, rm, stat } from "node:fs/promises"
+import { join, resolve } from "node:path"
+import { pluginAssetError } from "@hoardodile/sdk-types"
+import { sumDirSizes } from "./dir-size.ts"
+import { assertInside, assertSafeSegment } from "./paths.ts"
+
+/** Thrown when a vault path violates the isolation rules (POLICY). */
+export class PluginVaultPathError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "PluginVaultPathError"
+	}
+}
+
+/**
+ * Parse a vault-relative destination and resolve it against the vault
+ * root. Every segment goes through {@link assertSafeSegment} (no empty
+ * segments, `.`/`..`, separators inside a segment, drive letters,
+ * control chars, Windows-reserved names, trailing dot/space) and the
+ * final path is re-checked with {@link assertInside} — doubly so, the
+ * whole point is that a downloaded file can only ever land inside the
+ * plugin's own vault.
+ */
+export function parsePluginVaultDest(
+	vaultDir: string,
+	dest: string,
+): { readonly rel: string; readonly abs: string } {
+	if (dest.length === 0) {
+		throw new PluginVaultPathError("plugin vault destination must not be empty")
+	}
+	const segments = dest.split("/")
+	let abs = vaultDir
+	for (const segment of segments) {
+		if (segment.length === 0) {
+			throw new PluginVaultPathError(
+				`plugin vault destination must not contain empty segments: ${JSON.stringify(dest)}`,
+			)
+		}
+		try {
+			abs = join(abs, assertSafeSegment(segment))
+		} catch (err) {
+			// assertSafeSegment answers plain Errors — the boundary keeps
+			// one vocabulary so callers can map them to POLICY uniformly.
+			throw new PluginVaultPathError(
+				err instanceof Error ? err.message : String(err),
+			)
+		}
+	}
+	try {
+		const resolved = assertInside(vaultDir, abs)
+		return { rel: segments.join("/"), abs: resolved }
+	} catch (err) {
+		throw new PluginVaultPathError(
+			err instanceof Error ? err.message : String(err),
+		)
+	}
+}
+
+/**
+ * Byte size of a vault file (or `undefined` when absent or not a
+ * regular file). The cheap presence check `download` builds on.
+ */
+export async function vaultStatFile(
+	vaultDir: string,
+	rel: string,
+): Promise<{ readonly sizeBytes: number } | undefined> {
+	const { abs } = parsePluginVaultDest(vaultDir, rel)
+	const info = await stat(abs).catch(() => undefined)
+	if (info === undefined || !info.isFile()) return undefined
+	return { sizeBytes: info.size }
+}
+
+/** Stream a vault file's bytes (bounded by `maxBytes`). */
+export async function vaultReadFile(
+	vaultDir: string,
+	rel: string,
+	maxBytes: number,
+): Promise<Uint8Array> {
+	const { abs } = parsePluginVaultDest(vaultDir, rel)
+	const info = await stat(abs).catch(() => undefined)
+	if (info === undefined || !info.isFile()) {
+		throw pluginAssetError("POLICY", `plugin vault file not found: ${rel}`)
+	}
+	if (info.size > maxBytes) {
+		throw pluginAssetError(
+			"POLICY",
+			`plugin vault file "${rel}" exceeds the ${maxBytes}-byte read cap`,
+		)
+	}
+	const bytes = await readFile(abs)
+	return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+}
+
+/**
+ * Remove a vault file. Idempotent (absent → false); directories and
+ * anything outside the vault are rejected.
+ */
+export async function vaultRemoveFile(
+	vaultDir: string,
+	rel: string,
+): Promise<boolean> {
+	const { abs } = parsePluginVaultDest(vaultDir, rel)
+	const info = await stat(abs).catch(() => undefined)
+	if (info === undefined) return false
+	if (!info.isFile()) {
+		throw pluginAssetError(
+			"POLICY",
+			`plugin vault destination is not a file: ${rel}`,
+		)
+	}
+	await rm(abs)
+	return true
+}
+
+/**
+ * Path of the caller's download temp file inside the vault (host-side
+ * staging — never a user-visible name). The downloader streams into it;
+ * {@link commitVaultFile} renames it into place.
+ */
+export function vaultTempFile(vaultDir: string): string {
+	return join(vaultDir, `.${randomUUID()}.tmp`)
+}
+
+/** Delete a temp file (download failure path). */
+export async function discardVaultTempFile(tempPath: string): Promise<void> {
+	await rm(tempPath, { force: true }).catch(() => {})
+}
+
+/**
+ * Commit a downloaded temp file into the vault: mkdir the nested
+ * destination, verify the per-plugin total-size budget (the destination's
+ * own previous bytes count against the quota only once — re-downloading
+ * replaces, it does not add), then rename the temp file into place
+ * (atomic — the final path never holds a partial download).
+ */
+export async function commitVaultFile(opts: {
+	readonly vaultDir: string
+	readonly rel: string
+	readonly tempPath: string
+	readonly maxFileBytes: number
+	readonly maxTotalBytes: number
+}): Promise<{ readonly sizeBytes: number; readonly sha256: string }> {
+	const { abs } = parsePluginVaultDest(opts.vaultDir, opts.rel)
+	const existing = await stat(abs).catch(() => undefined)
+	if (existing !== undefined && !existing.isFile()) {
+		throw pluginAssetError(
+			"POLICY",
+			`plugin vault destination is not a file: ${opts.rel}`,
+		)
+	}
+	const tempInfo = await stat(opts.tempPath).catch(() => undefined)
+	if (tempInfo === undefined || !tempInfo.isFile()) {
+		throw pluginAssetError(
+			"POLICY",
+			`plugin vault download lost its staging file: ${opts.rel}`,
+		)
+	}
+	if (tempInfo.size > opts.maxFileBytes) {
+		throw pluginAssetError(
+			"POLICY",
+			`plugin vault file "${opts.rel}" exceeds the ${opts.maxFileBytes}-byte download cap`,
+		)
+	}
+	const currentTotal = await vaultTotalSize(opts.vaultDir)
+	const replacedBytes = existing?.isFile() ? existing.size : 0
+	if (currentTotal - replacedBytes + tempInfo.size > opts.maxTotalBytes) {
+		throw pluginAssetError(
+			"POLICY",
+			`plugin vault "${opts.rel}" would exceed the ${opts.maxTotalBytes}-byte plugin quota (current ${currentTotal})`,
+		)
+	}
+	await mkdir(resolve(abs, ".."), { recursive: true })
+	await rename(opts.tempPath, abs)
+	return { sizeBytes: tempInfo.size, sha256: await hashFileAbs(abs) }
+}
+
+/**
+ * Total bytes of the vault's regular files (shared directory-size walk;
+ * host temp staging files — leading `.` — are excluded as transient).
+ */
+export async function vaultTotalSize(vaultDir: string): Promise<number> {
+	return sumDirSizes(vaultDir, { excludeDotPrefix: true })
+}
+
+/** sha256 of a vault file's bytes (streamed; callers verify pins against it). */
+export async function vaultFileSha256(
+	vaultDir: string,
+	rel: string,
+): Promise<string> {
+	const { abs } = parsePluginVaultDest(vaultDir, rel)
+	const info = await stat(abs).catch(() => undefined)
+	if (info === undefined || !info.isFile()) {
+		throw pluginAssetError("POLICY", `plugin vault file not found: ${rel}`)
+	}
+	return hashFileAbs(abs)
+}
+
+async function hashFileAbs(abs: string): Promise<string> {
+	const hash = createHash("sha256")
+	await new Promise<void>((resolveDone, reject) => {
+		const stream = createReadStream(abs)
+		stream.on("data", (chunk: string | Buffer) => hash.update(chunk))
+		stream.on("end", () => resolveDone())
+		stream.on("error", reject)
+	})
+	return hash.digest("hex")
+}
+
+/** Result of {@link commitVaultFile}: the stored file's identity. */
+export type VaultCommitResult = {
+	readonly sizeBytes: number
+	readonly sha256: string
+}

package/src/hoard/sanitize.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "vitest"
+import {
+	createOccupiedNames,
+	occupyEntryName,
+	sanitizeEntryName,
+	uniqueEntryName,
+} from "./sanitize.ts"
+
+describe("sanitizeEntryName", () => {
+	test("replaces Windows-forbidden characters with underscores", () => {
+		expect(sanitizeEntryName('a<b>c:d"e|f?g*h')).toBe("a_b_c_d_e_f_g_h")
+	})
+
+	test("treats backslashes as separators", () => {
+		expect(sanitizeEntryName("dir\\sub\\file.txt")).toBe("dir/sub/file.txt")
+	})
+
+	test("strips control characters", () => {
+		expect(sanitizeEntryName("a\x01b\x1f.txt")).toBe("ab.txt")
+	})
+
+	test("rejects null bytes", () => {
+		expect(sanitizeEntryName("a\u0000b")).toBeUndefined()
+	})
+
+	test("drops . and .. segments instead of escaping", () => {
+		expect(sanitizeEntryName("../a/./b.txt")).toBe("a/b.txt")
+		expect(sanitizeEntryName("../../etc/passwd")).toBe("etc/passwd")
+	})
+
+	test("strips leading dots (metadata namespace) and trailing dots/spaces", () => {
+		expect(sanitizeEntryName(".hidden.txt")).toBe("hidden.txt")
+		expect(sanitizeEntryName("...dots.txt")).toBe("dots.txt")
+		expect(sanitizeEntryName("name.")).toBe("name")
+		expect(sanitizeEntryName("name ")).toBe("name")
+		expect(sanitizeEntryName("dir./file. ")).toBe("dir/file")
+	})
+
+	test("prefixes Windows reserved base names incl. extension variants", () => {
+		expect(sanitizeEntryName("CON")).toBe("_CON")
+		expect(sanitizeEntryName("con.txt")).toBe("_con.txt")
+		expect(sanitizeEntryName("COM1")).toBe("_COM1")
+		expect(sanitizeEntryName("LPT9.x")).toBe("_LPT9.x")
+		expect(sanitizeEntryName("NUL")).toBe("_NUL")
+		expect(sanitizeEntryName("CONIN$")).toBe("_CONIN$")
+		expect(sanitizeEntryName("CONOUT$.txt")).toBe("_CONOUT$.txt")
+		expect(sanitizeEntryName("COM0")).toBe("_COM0")
+		expect(sanitizeEntryName("COM\u00b9")).toBe("_COM\u00b9")
+		expect(sanitizeEntryName("LPT\u00b3.bin")).toBe("_LPT\u00b3.bin")
+	})
+
+	test("preserves subdirectory structure", () => {
+		expect(sanitizeEntryName("Chapter 1/001.jpg")).toBe("Chapter 1/001.jpg")
+	})
+
+	test("normalizes to NFC", () => {
+		const decomposed = "cafe\u0301.txt"
+		expect(sanitizeEntryName(decomposed)).toBe("caf\u00e9.txt")
+	})
+
+	test("caps segments at 240 UTF-8 bytes", () => {
+		const long = `${"中".repeat(200)}.txt`
+		const result = sanitizeEntryName(long)
+		expect(result).toBeDefined()
+		const name = result!.split("/").at(-1)!
+		expect(Buffer.byteLength(name, "utf8")).toBeLessThanOrEqual(243)
+		expect(name.includes("\uFFFD")).toBe(false)
+	})
+
+	test("caps emoji segments by bytes, not code units", () => {
+		const long = "😀".repeat(200)
+		const result = sanitizeEntryName(long)
+		expect(result).toBeDefined()
+		expect(Buffer.byteLength(result!, "utf8")).toBeLessThanOrEqual(240)
+	})
+
+	test("returns undefined for unusable names", () => {
+		expect(sanitizeEntryName("")).toBeUndefined()
+		expect(sanitizeEntryName("....")).toBeUndefined()
+		expect(sanitizeEntryName("\u0000")).toBeUndefined()
+		expect(sanitizeEntryName("///")).toBeUndefined()
+	})
+
+	test("rejects relative paths over the total length cap", () => {
+		const segments = Array.from({ length: 300 }, () => "abc")
+		expect(sanitizeEntryName(segments.join("/"))).toBeUndefined()
+	})
+})
+
+describe("uniqueEntryName", () => {
+	test("appends -N suffix on exact collisions", () => {
+		const occupied = createOccupiedNames({ files: ["a.png"] })
+		expect(uniqueEntryName(occupied, "a.png")).toBe("a-1.png")
+		occupyEntryName(occupied, "a-1.png")
+		expect(uniqueEntryName(occupied, "a.png")).toBe("a-2.png")
+	})
+
+	test("collides case-insensitively", () => {
+		expect(
+			uniqueEntryName(createOccupiedNames({ files: ["A.PNG"] }), "a.png"),
+		).toBe("a-1.png")
+	})
+
+	test("keeps the extension in the suffix", () => {
+		expect(
+			uniqueEntryName(createOccupiedNames({ files: ["page.jpg"] }), "page.jpg"),
+		).toBe("page-1.jpg")
+		expect(
+			uniqueEntryName(createOccupiedNames({ files: ["page"] }), "page"),
+		).toBe("page-1")
+	})
+
+	test("resolves file-vs-directory prefix collisions on the colliding segment", () => {
+		expect(
+			uniqueEntryName(createOccupiedNames({ files: ["x"] }), "x/y.txt"),
+		).toBe("x-1/y.txt")
+		expect(
+			uniqueEntryName(createOccupiedNames({ files: ["a/b"] }), "a/b/c.txt"),
+		).toBe("a/b-1/c.txt")
+		expect(
+			uniqueEntryName(createOccupiedNames({ files: ["x", "x-1"] }), "x/y.txt"),
+		).toBe("x-2/y.txt")
+	})
+
+	test("directory ancestors do not collide with nested entries", () => {
+		const occupied = createOccupiedNames()
+		occupyEntryName(occupied, "src/a.txt")
+		expect(uniqueEntryName(occupied, "src/sub/b.txt")).toBe("src/sub/b.txt")
+		expect(uniqueEntryName(occupied, "src/c.txt")).toBe("src/c.txt")
+	})
+
+	test("an installed file blocks the exact path of a later directory root", () => {
+		const occupied = createOccupiedNames()
+		occupyEntryName(occupied, "x/y.txt")
+		expect(occupied.dirs.has("x")).toBe(true)
+		expect(uniqueEntryName(occupied, "x")).toBe("x-1")
+	})
+
+	test("suffixing retries until the whole path is free", () => {
+		const occupied = createOccupiedNames({ files: ["a.png", "a-1.png"] })
+		expect(uniqueEntryName(occupied, "a.png")).toBe("a-2.png")
+	})
+
+	test("untouched names pass through", () => {
+		expect(
+			uniqueEntryName(createOccupiedNames({ files: ["other.png"] }), "a.png"),
+		).toBe("a.png")
+	})
+})