@hoardodile/host 0.0.0

package/src/hoard/order-manifest.ts

@@ -0,0 +1,131 @@
+import { readFile, rename, rm, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+
+/**
+ * Explicit file order for a resource's content root (`data/`). Uploads
+ * install entries in the user's chosen order and persist that sequence
+ * in this manifest so the display order matches the upload order even
+ * when filenames sort differently. Written at commit time; because it
+ * lives inside the replaced `data/` subtree it is always consistent
+ * with the entries around it.
+ *
+ * The manifest is a JSON array of relative entry names (`/`-separated),
+ * listing the final installed names (after collision suffixing). Reads
+ * are strict: a malformed manifest, or one whose entries do not all
+ * resolve against the actual listing, is ignored entirely and callers
+ * fall back to the natural name sort. Strictness matters because
+ * `createDirectoryContainer` also serves arbitrary user directories
+ * (folder import, plugin dev) that may coincidentally contain a file
+ * named `.order`.
+ */
+export const ORDER_MANIFEST_NAME = ".order"
+
+/** Path of the order manifest inside a resource content root. */
+export function orderManifestPath(dataDir: string): string {
+	return join(dataDir, ORDER_MANIFEST_NAME)
+}
+
+/**
+ * Atomically persist `names` as the manifest of `dataDir` (tmp + rename,
+ * so a concurrent reader never observes a half-written file).
+ */
+export async function writeOrderManifest(
+	dataDir: string,
+	names: readonly string[],
+): Promise<void> {
+	const dest = orderManifestPath(dataDir)
+	const tmp = `${dest}.writing-${process.pid}-${Date.now()}`
+	try {
+		await writeFile(tmp, JSON.stringify(names), "utf8")
+		await rename(tmp, dest)
+	} catch (err) {
+		await rm(tmp, { force: true }).catch(() => {})
+		throw err
+	}
+}
+
+/**
+ * Read the manifest of `dataDir`. Resolves to `undefined` when the
+ * manifest is absent or fails structural validation
+ * ({@link parseOrderManifest}) — callers fall back to natural order.
+ */
+export async function readOrderManifest(
+	dataDir: string,
+): Promise<readonly string[] | undefined> {
+	let raw: string
+	try {
+		raw = await readFile(orderManifestPath(dataDir), "utf8")
+	} catch {
+		return undefined
+	}
+	return parseOrderManifest(raw)
+}
+
+/**
+ * Structural validation of a raw manifest body: a JSON array of
+ * non-empty relative paths with `/` separators that cannot escape the
+ * content root. Returns `undefined` when the body is not a usable
+ * manifest. Semantic validation (entries exist in the listing) happens
+ * in {@link orderEntries}.
+ */
+export function parseOrderManifest(raw: string): readonly string[] | undefined {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch {
+		return undefined
+	}
+	if (!Array.isArray(parsed) || parsed.length === 0) return undefined
+	const names: string[] = []
+	for (const entry of parsed) {
+		if (typeof entry !== "string") return undefined
+		if (!isManifestPathSafe(entry)) return undefined
+		names.push(entry)
+	}
+	if (names.length === 0) return undefined
+	return names
+}
+
+/**
+ * Reorder `listed` by the manifest: entries named by the manifest come
+ * first, in manifest order; entries the manifest does not mention are
+ * appended in natural order. Returns `undefined` when the manifest
+ * cannot be applied against this listing (some manifest entry is
+ * missing — the strict trust rule), so the caller falls back to the
+ * natural sort.
+ */
+export function orderEntries(
+	manifest: readonly string[],
+	listed: readonly string[],
+): readonly string[] | undefined {
+	const available = new Set(listed)
+	const uniqueManifest = new Set<string>()
+	for (const name of manifest) {
+		if (uniqueManifest.has(name)) return undefined
+		uniqueManifest.add(name)
+		if (!available.has(name)) return undefined
+	}
+	const ordered = manifest.filter((name) => available.has(name))
+	const rest = naturalSort(listed.filter((name) => !uniqueManifest.has(name)))
+	return [...ordered, ...rest]
+}
+
+/** Case-insensitive natural name sort (`1 < 2 < 10`, `a < b`). */
+export function naturalSort(names: readonly string[]): readonly string[] {
+	return [...names].sort((a, b) =>
+		a.localeCompare(b, undefined, { sensitivity: "base", numeric: true }),
+	)
+}
+
+function isManifestPathSafe(entry: string): boolean {
+	if (entry.length === 0 || entry.includes("\0") || entry.includes("\\")) {
+		return false
+	}
+	const segments = entry.split("/")
+	for (const segment of segments) {
+		if (segment.length === 0 || segment === "." || segment === "..") {
+			return false
+		}
+	}
+	return true
+}

package/src/hoard/paths.test.ts

@@ -0,0 +1,226 @@
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, test } from "vitest"
+import {
+	assertInside,
+	assertSafeSegment,
+	createStoragePaths,
+	imageVariantKey,
+} from "./paths.ts"
+
+// path-guard-exempt: platform branch, each literal matches its own OS.
+const ROOT = process.platform === "win32" ? "C:\\data\\app" : "/data/app"
+
+describe("createStoragePaths", () => {
+	test("defaults latestVersion from max versions/<n> on disk when omitted", () => {
+		const root = mkdtempSync(join(tmpdir(), "paths-ver-"))
+		try {
+			mkdirSync(join(root, "versions", "1"), { recursive: true })
+			mkdirSync(join(root, "versions", "2"), { recursive: true })
+			const paths = createStoragePaths({ root })
+			expect(paths.latestVersion).toBe(2)
+			expect(paths.activeVersion).toBe(2)
+			expect(paths.active.version).toBe(2)
+			expect(paths.latest.version).toBe(2)
+			expect(paths.active.root).toContain(`${sep()}versions${sep()}2`)
+		} finally {
+			rmSync(root, { recursive: true, force: true })
+		}
+	})
+
+	test("rejects relative roots", () => {
+		expect(() => createStoragePaths({ root: "relative/path" })).toThrow(
+			/absolute path/,
+		)
+	})
+
+	test("builds versions and local subtrees under the root", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		expect(paths.active.root).toContain("versions")
+		expect(paths.local.root).toContain("local")
+		expect(paths.active.root).not.toBe(paths.local.root)
+	})
+
+	test("resource path nests under versions/resources/<id>", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const p = paths.active.resource("res_42")
+		expect(p.endsWith(`resources${sep()}res_42`)).toBe(true)
+		expect(p.startsWith(paths.active.root)).toBe(true)
+	})
+
+	test("version plugins nest under versions/<v>/plugins", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const p = paths.latest.plugins()
+		expect(p.endsWith(`versions${sep()}1${sep()}plugins`)).toBe(true)
+		expect(p.startsWith(paths.latest.root)).toBe(true)
+		expect(p.startsWith(paths.local.root)).toBe(false)
+	})
+
+	test("upload staging root and pool nest under local/.tmp", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const root = paths.local.uploadStagingRoot()
+		expect(root.endsWith(`${sep()}local${sep()}.tmp`)).toBe(true)
+		expect(root.startsWith(paths.local.root)).toBe(true)
+		const pool = paths.local.stagingPoolRoot()
+		expect(pool.startsWith(`${root}${sep()}`)).toBe(true)
+		const file = paths.local.stagingPoolFile(
+			"550e8400-e29b-41d4-a716-446655440000",
+			".png",
+		)
+		expect(file.startsWith(`${pool}${sep()}`)).toBe(true)
+		expect(file.endsWith("550e8400-e29b-41d4-a716-446655440000.png")).toBe(true)
+	})
+
+	test("cache root nests under local/cache", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const cache = paths.local.cache()
+		expect(cache.endsWith(`${sep()}local${sep()}cache`)).toBe(true)
+		expect(cache.startsWith(paths.local.root)).toBe(true)
+	})
+
+	test("derived caches nest under local/cache, persistent dirs do not", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const cache = paths.local.cache()
+		const derived = [
+			paths.local.resource("res_1"),
+			paths.local.character("char_1"),
+			paths.local.resFilesCache("res_1"),
+			paths.local.resFilePreviewDir("res_1"),
+			paths.local.resVideoFrame("res_1", "clip.mp4", 1000),
+			paths.local.resExtractedDir("res_1", 1),
+			paths.local.resExtractedEntry("res_1", 1, "a/b.png"),
+			paths.local.tmp(),
+			paths.local.tmpFile("scratch.bin"),
+		]
+		for (const p of derived) {
+			expect(p.startsWith(`${cache}${sep()}`)).toBe(true)
+		}
+		const persistent = [
+			paths.local.trash(),
+			paths.local.logs(),
+			paths.local.sessionKey(),
+			paths.local.uploadStagingRoot(),
+			paths.local.stagingPoolRoot(),
+		]
+		for (const p of persistent) {
+			expect(p.startsWith(`${cache}${sep()}`)).toBe(false)
+			expect(p.startsWith(paths.local.root)).toBe(true)
+		}
+	})
+
+	test("thumb path nests under local/cache/<kind>/<id>/<variant>.webp", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const r = paths.local.localCover("resource", "res_1", "preview", "webp")
+		expect(r.endsWith(`resources${sep()}res_1${sep()}preview.webp`)).toBe(true)
+		expect(r.startsWith(paths.local.cache())).toBe(true)
+		const c = paths.local.localCover("character", "char_1", "avatar", "webp")
+		expect(c.endsWith(`characters${sep()}char_1${sep()}avatar.webp`)).toBe(true)
+		expect(c.startsWith(paths.local.cache())).toBe(true)
+	})
+
+	test("per-file variant cache basenames fold ext, key and flattened separators", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const variant = paths.local.resFileVariant(
+			"res_1",
+			"dir/page.jpg",
+			"ab12cd34",
+			"avif",
+		)
+		expect(variant).toMatch(/dir__page__jpg__[0-9a-f]{8}__ab12cd34\.avif$/)
+		// Backslash names from odd archives are flattened the same way.
+		const frame = paths.local.resVideoFrame("res_1", "sub\\clip.mp4", 1000)
+		expect(frame).toMatch(/sub__clip__mp4__[0-9a-f]{8}[\\/]1000\.avif$/)
+	})
+
+	test("same-named files in nested folders never share a cache identity", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const a = paths.local.resFileVariant("res_1", "a/tex.png", "k1", "avif")
+		const b = paths.local.resFileVariant("res_1", "b/tex.png", "k1", "avif")
+		expect(a).not.toBe(b)
+		// Same file, same spec: stable identity across calls.
+		const again = paths.local.resFileVariant("res_1", "a/tex.png", "k1", "avif")
+		expect(again).toBe(a)
+	})
+
+	test("flattening ambiguities are disambiguated by the path hash", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		// Both flatten to `a__b__c__png`; only the hash tells them apart.
+		const folderUnderscore = paths.local.resFileVariant(
+			"res_1",
+			"a__b/c.png",
+			"k1",
+			"avif",
+		)
+		const fileUnderscore = paths.local.resFileVariant(
+			"res_1",
+			"a/b__c.png",
+			"k1",
+			"avif",
+		)
+		expect(folderUnderscore).not.toBe(fileUnderscore)
+	})
+
+	test("extracted entries carry the same collision-free identity", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		const first = paths.local.resExtractedEntry("res_1", 1, "a__b/c.png")
+		const second = paths.local.resExtractedEntry("res_1", 1, "a/b__c.png")
+		expect(first).not.toBe(second)
+		expect(first).toMatch(/a__b__c__png__[0-9a-f]{8}$/)
+	})
+
+	test("imageVariantKey is a short stable hex digest", () => {
+		const key = imageVariantKey("avif:inside:4000000:70:90")
+		expect(key).toMatch(/^[0-9a-f]{8}$/)
+		expect(imageVariantKey("avif:inside:4000000:70:90")).toBe(key)
+		expect(imageVariantKey("webp:exact:4000000:70:90")).not.toBe(key)
+	})
+
+	test("rejects path-like ids to prevent directory traversal", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		expect(() => paths.active.resource("../escape")).toThrow(/separators/)
+		expect(() => paths.active.resource("../../etc/passwd")).toThrow(
+			/separators/,
+		)
+		expect(() => paths.active.resource("a\\b")).toThrow(/separators/)
+	})
+
+	test("rejects Windows reserved basenames and trailing dot/space", () => {
+		const paths = createStoragePaths({ root: ROOT })
+		expect(() => paths.active.resource("CON")).toThrow(/reserved/)
+		expect(() => paths.active.resource("prn.txt")).toThrow(/reserved/)
+		expect(() => paths.active.resource("trailing.")).toThrow(/dot or space/)
+		expect(() => paths.active.resource("trailing ")).toThrow(/dot or space/)
+	})
+
+	test("rejects empty and dot segments", () => {
+		expect(() => assertSafeSegment("")).toThrow(/empty/)
+		expect(() => assertSafeSegment(".")).toThrow(/'\.'/)
+		expect(() => assertSafeSegment("..")).toThrow(/'\.\.'/)
+	})
+
+	test("rejects control characters", () => {
+		expect(() => assertSafeSegment("nul\u0000byte")).toThrow(/disallowed/)
+	})
+})
+
+describe("assertInside", () => {
+	test("accepts descendants and the ancestor itself", () => {
+		expect(assertInside(ROOT, ROOT)).toBe(ROOT)
+		const descendant =
+			process.platform === "win32"
+				? `${ROOT}\\sub\\leaf.txt`
+				: `${ROOT}/sub/leaf.txt`
+		expect(assertInside(ROOT, descendant)).toBe(descendant)
+	})
+
+	test("rejects siblings that share a prefix", () => {
+		const sibling =
+			process.platform === "win32" ? `${ROOT}-other` : `${ROOT}-other`
+		expect(() => assertInside(ROOT, sibling)).toThrow(/escapes/)
+	})
+})
+
+function sep(): string {
+	return process.platform === "win32" ? "\\" : "/"
+}