@hoardodile/host 0.0.0

package/src/archive/zip-entries.ts

@@ -0,0 +1,336 @@
+import { createReadStream, type ReadStream } from "node:fs"
+import { stat } from "node:fs/promises"
+import { Readable } from "node:stream"
+import { buffer } from "node:stream/consumers"
+import { createInflateRaw } from "node:zlib"
+import yauzl from "yauzl"
+import { invalid } from "../errors.ts"
+
+/**
+ * Central directory entry shape exposed for the read-path cache. Mirrors
+ * the fields yauzl surfaces, plus `dataOffset` resolved from the local
+ * header. `dataOffset` and `dataSize` together pinpoint the entry's raw
+ * bytes inside the zip file; for STORED entries those bytes are the file
+ * itself and can be streamed via {@link streamRange} with a
+ * `[start, end]` window.
+ *
+ * The central directory is parsed by yauzl (the only listing engine —
+ * the hand-rolled fast parser was removed; ZIP64 falls out naturally).
+ */
+export type ZipEntry = {
+	readonly name: string
+	readonly compressionMethod: number
+	/** General-purpose bit 0: the entry data is encrypted. */
+	readonly encrypted: boolean
+	readonly uncompressedSize: number
+	readonly compressedSize: number
+	readonly crc32: number
+	readonly localHeaderOffset: number
+	/**
+	 * Absolute byte offset of the entry's raw data inside the zip file.
+	 * Computed as `localHeaderOffset + 30 + nameLen + extraLen` where
+	 * nameLen and extraLen are read from the local file header (not the
+	 * central directory) because they can differ between the two.
+	 */
+	readonly dataOffset: number
+	readonly dataSize: number
+	readonly modifiedAt: number
+}
+
+/**
+ * Random-access byte view over a zip archive. File-backed archives
+ * (uploaded archive files and CLI fixtures) read via the filesystem;
+ * nested archives — a zip entry inside the container — implement the same
+ * range reads over the outer entry's inflated bytes. Everything in this
+ * module that needs the archive's bytes takes a {@link ArchiveSource},
+ * so the container and the plugin API resolve nested zips through one
+ * code path.
+ */
+export type ArchiveSource = {
+	/** Total archive size in bytes. */
+	readonly size: number
+	/** Read the inclusive byte range `[start, end]`. */
+	readonly readRange: (start: number, end: number) => Promise<Buffer>
+}
+
+const RANGE_READ_CHUNK_BYTES = 256 * 1024
+
+/** Wrap an on-disk zip in a {@link ArchiveSource}. */
+export async function createFileArchiveSource(
+	zipPath: string,
+): Promise<ArchiveSource> {
+	const info = await stat(zipPath)
+	return {
+		size: info.size,
+		readRange: (start, end) => readFileRange(zipPath, start, end),
+	}
+}
+
+/**
+ * Read the central directory of the zip behind `source`, plus enough of
+ * each local file header to compute `dataOffset`. Returns a flat list of
+ * records ready for caching. Directory entries (names ending in `/`) are
+ * excluded.
+ *
+ * The listing goes through yauzl over the {@link ArchiveSource} (via its
+ * random-access-reader bridge); yauzl handles ZIP64 and validates entry
+ * names while parsing. The `dataOffset` for byte-range access is
+ * resolved from each local file header afterwards — callers that only
+ * need names and sizes (e.g. the legacy-name decode truth) pass
+ * `{ dataOffsets: false }` so the per-entry random reads are skipped and
+ * `dataOffset` is left at 0.
+ *
+ * @throws DomainError `resource.archive_open_failed` when the zip cannot
+ *   be parsed.
+ */
+export async function listZipEntriesFromSource(
+	source: ArchiveSource,
+	opts: { readonly dataOffsets?: boolean } = {},
+): Promise<readonly ZipEntry[]> {
+	const zipfile = await openZipFromSource(source)
+	const records: ZipEntry[] = []
+	try {
+		for await (const entry of zipfile.eachEntry()) {
+			if (entry.fileName.endsWith("/")) continue
+			const dataOffset =
+				opts.dataOffsets === false
+					? 0
+					: await resolveDataOffsetFromSource(
+							source,
+							entry.relativeOffsetOfLocalHeader,
+						)
+			records.push({
+				name: entry.fileName,
+				compressionMethod: entry.compressionMethod,
+				encrypted: entry.isEncrypted(),
+				uncompressedSize: entry.uncompressedSize,
+				compressedSize: entry.compressedSize,
+				crc32: entry.crc32,
+				localHeaderOffset: entry.relativeOffsetOfLocalHeader,
+				dataOffset,
+				dataSize: entry.compressedSize,
+				modifiedAt: entry.getLastModDate().getTime(),
+			})
+		}
+	} catch (err) {
+		// yauzl surfaces malformed central directories as plain errors
+		// (e.g. encrypted stored entries with inconsistent sizes) — map
+		// them onto the documented taxonomy.
+		throw invalid(
+			"resource.archive_open_failed",
+			err instanceof Error ? err.message : "could not read archive entries",
+			{ size: source.size },
+		)
+	} finally {
+		zipfile.close()
+	}
+	return records
+}
+
+/** Read the central directory of the zip at `zipPath`. */
+export async function listZipEntries(
+	zipPath: string,
+	opts: { readonly dataOffsets?: boolean } = {},
+): Promise<readonly ZipEntry[]> {
+	return listZipEntriesFromSource(await createFileArchiveSource(zipPath), opts)
+}
+
+/**
+ * Stream one entry's *decompressed* bytes from `source`. STORED entries
+ * map to a byte-range stream of the raw data; DEFLATE entries inflate on
+ * the fly. Encrypted entries and other compression methods reject with a
+ * clear reason (there is no key to decrypt with). Callers are responsible
+ * for consuming or destroying the stream (a dangling stream leaks an
+ * inflate context).
+ */
+export function openZipEntryStream(
+	source: ArchiveSource,
+	record: ZipEntry,
+): Readable {
+	if (record.encrypted) {
+		throw invalid(
+			"resource.archive_open_failed",
+			`zip entry "${record.name}" is encrypted — password-protected archives are not supported`,
+			{ name: record.name },
+		)
+	}
+	switch (record.compressionMethod) {
+		case 0:
+			return streamRange(
+				source,
+				record.dataOffset,
+				record.dataOffset + record.dataSize - 1,
+			)
+		case 8: {
+			const raw = streamRange(
+				source,
+				record.dataOffset,
+				record.dataOffset + record.dataSize - 1,
+			)
+			const inflater = createInflateRaw()
+			raw.on("error", (err) => inflater.destroy(err))
+			return raw.pipe(inflater)
+		}
+		default:
+			throw invalid(
+				"resource.archive_open_failed",
+				`unsupported zip entry compression method ${record.compressionMethod} for "${record.name}"`,
+				{ method: record.compressionMethod, name: record.name },
+			)
+	}
+}
+
+/** Stream the inclusive byte range `[start, end]` in bounded chunks. */
+export function streamRange(
+	source: ArchiveSource,
+	start: number,
+	end: number,
+): Readable {
+	return Readable.from(
+		(async function* rangeChunks() {
+			let pos = start
+			while (pos <= end) {
+				const to = Math.min(end, pos + RANGE_READ_CHUNK_BYTES - 1)
+				const chunk = await source.readRange(pos, to)
+				if (chunk.length === 0) return
+				yield chunk
+				pos += chunk.length
+			}
+		})(),
+	)
+}
+
+/** Stream `zipPath` bytes in the range `[start, end]` (inclusive). */ export function readZipRange(
+	zipPath: string,
+	start: number,
+	end: number,
+): ReadStream {
+	return createReadStream(zipPath, { start, end })
+}
+
+/**
+ * Read an inclusive byte range from `path`. Uses a read stream so offsets
+ * beyond 2 GiB work on Node versions where `fs.read` position must fit in
+ * Int32 (older releases assert instead of throwing).
+ */
+export async function readFileRange(
+	path: string,
+	start: number,
+	end: number,
+): Promise<Buffer> {
+	if (
+		!Number.isFinite(start) ||
+		!Number.isFinite(end) ||
+		!Number.isInteger(start) ||
+		!Number.isInteger(end) ||
+		start < 0 ||
+		end < start
+	) {
+		throw invalid(
+			"resource.file_read_failed",
+			`invalid byte range ${start}..${end}`,
+			{ path, start, end },
+		)
+	}
+	const length = end - start + 1
+	if (length <= 0) return Buffer.alloc(0)
+	return buffer(readZipRange(path, start, end))
+}
+
+function openZipFromSource(source: ArchiveSource): Promise<yauzl.ZipFile> {
+	const reader = new RangeReader(source)
+	return yauzl
+		.fromRandomAccessReaderPromise(reader, source.size, {
+			lazyEntries: true,
+			decodeStrings: true,
+		})
+		.catch((err: unknown) => {
+			reader.close(() => {})
+			throw invalid(
+				"resource.archive_open_failed",
+				err instanceof Error ? err.message : "could not open archive",
+				{ size: source.size },
+			)
+		})
+}
+
+/**
+ * yauzl's random-access-reader bridge. yauzl 3.x reads through
+ * `createReadStream`/`read`, which are built on `_readStreamForRange`;
+ * a subclass therefore only supplies range streams (chunked, so entries
+ * are never buffered whole) plus `_close` (see yauzl's README).
+ */
+class RangeReader extends yauzl.RandomAccessReader {
+	// Explicit field + assignment: this package ships source to Node's
+	// type-stripping loader (no build step), which rejects parameter
+	// properties.
+	private readonly source: ArchiveSource
+
+	constructor(source: ArchiveSource) {
+		super()
+		this.source = source
+	}
+
+	override _readStreamForRange(start: number, end: number): Readable {
+		// yauzl's `end` is exclusive (it asserts exactly `end - start`
+		// bytes); `streamRange` takes an inclusive end.
+		return streamRange(this.source, start, end - 1)
+	}
+
+	// yauzl's runtime contract calls `_close` even though the shipped
+	// types only expose the public `close` — no `override` here.
+	_close(callback: (err?: Error | null) => void): void {
+		callback(null)
+	}
+}
+
+async function resolveDataOffsetFromSource(
+	source: ArchiveSource,
+	localHeaderOffset: number,
+): Promise<number> {
+	if (localHeaderOffset + 30 > source.size) {
+		throw invalid(
+			"resource.archive_open_failed",
+			`truncated local file header at offset ${localHeaderOffset}`,
+			{ localHeaderOffset },
+		)
+	}
+	const head = await source.readRange(localHeaderOffset, localHeaderOffset + 29)
+	if (head.length < 30) {
+		throw invalid(
+			"resource.archive_open_failed",
+			`truncated local file header at offset ${localHeaderOffset}`,
+			{ localHeaderOffset },
+		)
+	}
+	const sig = head.readUInt32LE(0)
+	if (sig !== 0x04034b50) {
+		throw invalid(
+			"resource.archive_open_failed",
+			`bad local file header signature at offset ${localHeaderOffset}`,
+			{ localHeaderOffset, sig: sig.toString(16) },
+		)
+	}
+	const nameLen = head.readUInt16LE(26)
+	const extraLen = head.readUInt16LE(28)
+	return localHeaderOffset + 30 + nameLen + extraLen
+}
+
+/**
+ * yauzl validates entry names while parsing the central directory and
+ * rejects traversal/absolute names with a plain `Error`. Reclassify
+ * those as the documented `resource.archive_invalid_entry` domain error
+ * so every caller observes the same error taxonomy.
+ */
+export function normalizeZipError(err: unknown): unknown {
+	if (!(err instanceof Error)) return err
+	const message = err.message
+	if (
+		message.startsWith("invalid relative path: ") ||
+		message.startsWith("absolute path: ") ||
+		message.startsWith("invalid characters in fileName: ")
+	) {
+		return invalid("resource.archive_invalid_entry", message, {})
+	}
+	return err
+}

package/src/capability-guard.ts

@@ -0,0 +1,73 @@
+import type { PluginManifest } from "@hoardodile/sdk-types"
+import type {
+	PluginCapabilityGate,
+	PluginCapabilityKey,
+} from "@hoardodile/sdk-types/plugin-capabilities"
+import { PLUGIN_CAPABILITY_GATES } from "@hoardodile/sdk-types/plugin-capabilities"
+import type { PluginRegistryEntry } from "./api-types.ts"
+
+/**
+ * Capabilities a plugin manifest can declare — derived from the single
+ * {@link PLUGIN_CAPABILITY_GATES} table (which is itself keyed by the
+ * manifest's `PluginPermissions` keys), so the guard can never drift.
+ */
+export type PluginCapability = PluginCapabilityKey
+
+/** Gate metadata a consumer may want (e.g. for tooltips). */
+export type { PluginCapabilityGate }
+
+/**
+ * Permission checks against a plugin's declared manifest permissions,
+ * reading the capability vocabulary from the shared gates table.
+ * The server uses these before routing any plugin-scoped work so a
+ * manifest that does not declare a capability cannot trigger it.
+ */
+export type CapabilityGuard = {
+	/** Check whether a manifest grants the given capability. */
+	readonly check: (
+		manifest: PluginManifest,
+		capability: PluginCapability,
+	) => boolean
+	/** Assert that a manifest grants the given capability; throw if not. */
+	readonly require: (
+		manifest: PluginManifest,
+		capability: PluginCapability,
+	) => void
+	/** Filter entries to only those that grant the given capability. */
+	readonly filter: (
+		entries: readonly PluginRegistryEntry[],
+		capability: PluginCapability,
+	) => readonly PluginRegistryEntry[]
+}
+
+/** Create a stateless capability guard over manifest permissions. */
+export function createCapabilityGuard(): CapabilityGuard {
+	function check(
+		manifest: PluginManifest,
+		capability: PluginCapability,
+	): boolean {
+		return manifest.permissions[capability] === true
+	}
+
+	function require(
+		manifest: PluginManifest,
+		capability: PluginCapability,
+	): void {
+		if (!check(manifest, capability)) {
+			throw new Error(
+				`${capability} permission denied for plugin ${manifest.id}`,
+			)
+		}
+	}
+
+	function filter(
+		entries: readonly PluginRegistryEntry[],
+		capability: PluginCapability,
+	): readonly PluginRegistryEntry[] {
+		return entries.filter((e) => check(e.manifest, capability))
+	}
+
+	return { check, require, filter }
+}
+
+export { PLUGIN_CAPABILITY_GATES }

package/src/container.ts

@@ -0,0 +1,62 @@
+import type { Readable } from "node:stream"
+
+/**
+ * Read-only view over a resource's source data, regardless of storage
+ * shape — a zip archive, a raw directory, or an in-memory fixture. The
+ * {@link ResourceAPI} builder consumes this interface, so every backend
+ * (fixture / directory / zip / the server's artifact view) behaves
+ * identically behind a plugin hook.
+ *
+ * `relPath` values are entry names as they appear in the container (may
+ * contain `/`). Containers are immutable for the lifetime of a build:
+ * the server's per-version archives never change, and the directory
+ * container documents reads as snapshot-only.
+ */
+export type ResourceContainer = {
+	/** List every entry name in the container. Always flat. */
+	readonly listEntries: () => Promise<readonly string[]>
+	/** Read `relPath` in full. Throws when the entry does not exist. */
+	readonly readEntry: (relPath: string) => Promise<Buffer>
+	/**
+	 * Read the byte range `[start, end)` of `relPath` (`end` exclusive).
+	 * The range is clamped to the entry size; an out-of-range start
+	 * resolves to an empty buffer.
+	 */
+	readonly readEntrySlice: (
+		relPath: string,
+		start: number,
+		end: number,
+	) => Promise<Buffer>
+	/**
+	 * Stream entry bytes without buffering the whole entry. `path` is
+	 * the absolute on-disk file backing a literal entry, when there is
+	 * one — consumers serve ranges through `createReadStream(path,
+	 * {start, end})` windows instead of draining + discarding the
+	 * stream's prefix.
+	 */
+	readonly openEntryStream: (relPath: string) => Promise<{
+		readonly stream: Readable
+		readonly size: number
+		/** Modification time of the underlying file, when known. */
+		readonly mtimeMs?: number
+		/** Absolute path of the backing file, when literal and seekable. */
+		readonly path?: string
+	}>
+	/**
+	 * Resolve `relPath` to its byte length. Returns `undefined` when the
+	 * entry does not exist (the caller decides how to report that).
+	 */
+	readonly resolveByteRange: (
+		relPath: string,
+	) => Promise<{ readonly size: number } | undefined>
+	/**
+	 * Optional capability: resolve `relPath` to an absolute on-disk path
+	 * when its bytes can be read as a seekable file (no extraction, no
+	 * decompression). Consumers like the thumbnail pipeline hand such
+	 * paths straight to ffmpeg/libvips instead of piping streams.
+	 * Returns `undefined` when the container cannot provide one.
+	 */
+	readonly resolveSeekablePath?: (
+		relPath: string,
+	) => Promise<string | undefined>
+}

package/src/contract/container-fixture.ts

@@ -0,0 +1,74 @@
+import { Readable } from "node:stream"
+import type { ResourceContainer } from "../container.ts"
+
+/** Declarative in-memory content for a {@link ResourceContainer}. */
+export type ContainerFixtureConfig = {
+	/** Entry name → content. Names may contain `/` for nesting. */
+	readonly files?: Readonly<Record<string, string | Uint8Array>>
+}
+
+/**
+ * An in-memory {@link ResourceContainer} driven by a declarative config.
+ * The test double in the container contract suite: every assertion runs
+ * against it, the directory container and the zip container, and the
+ * three must agree.
+ */
+export function createContainerFixture(
+	config: ContainerFixtureConfig = {},
+): ResourceContainer {
+	const files = config.files ?? {}
+
+	function bytesOf(relPath: string): Uint8Array | undefined {
+		const content = files[relPath]
+		if (content === undefined) return undefined
+		return typeof content === "string"
+			? new TextEncoder().encode(content)
+			: content
+	}
+
+	return {
+		async listEntries(): Promise<readonly string[]> {
+			return Object.keys(files)
+		},
+
+		async readEntry(relPath: string): Promise<Buffer> {
+			const bytes = bytesOf(relPath)
+			if (bytes === undefined) {
+				throw new Error(`fixture container has no entry ${relPath}`)
+			}
+			return Buffer.from(bytes)
+		},
+
+		async readEntrySlice(
+			relPath: string,
+			start: number,
+			end: number,
+		): Promise<Buffer> {
+			const bytes = bytesOf(relPath)
+			if (bytes === undefined) {
+				throw new Error(`fixture container has no entry ${relPath}`)
+			}
+			const clampedStart = Math.min(Math.max(0, start), bytes.length)
+			const clampedEnd = Math.min(Math.max(clampedStart, end), bytes.length)
+			return Buffer.from(bytes.subarray(clampedStart, clampedEnd))
+		},
+
+		async openEntryStream(relPath: string): Promise<{
+			readonly stream: Readable
+			readonly size: number
+		}> {
+			const bytes = bytesOf(relPath)
+			if (bytes === undefined) {
+				throw new Error(`fixture container has no entry ${relPath}`)
+			}
+			return { stream: Readable.from(bytes), size: bytes.length }
+		},
+
+		async resolveByteRange(
+			relPath: string,
+		): Promise<{ readonly size: number } | undefined> {
+			const bytes = bytesOf(relPath)
+			return bytes === undefined ? undefined : { size: bytes.length }
+		},
+	}
+}

package/src/contract/index.ts

@@ -0,0 +1,10 @@
+export type { ContainerFixtureConfig } from "./container-fixture.ts"
+export { createContainerFixture } from "./container-fixture.ts"
+export type {
+	ContainerContractCase,
+	ContractBackend,
+} from "./suite.ts"
+export {
+	CONTAINER_CONTRACT_CASES,
+	containerContractSuite,
+} from "./suite.ts"

package/src/contract/suite.test.ts

@@ -0,0 +1,101 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { afterAll, describe, expect, test } from "vitest"
+import { createPluginResourceAPI } from "../api.ts"
+import { createDirectoryContainer } from "../directory-container.ts"
+import { createPluginSandbox, DEFAULT_SANDBOX_CONFIG } from "../sandbox/host.ts"
+import { createContainerFixture } from "./container-fixture.ts"
+import { type ContractBackend, containerContractSuite } from "./suite.ts"
+
+const tempRoots: string[] = []
+
+function withTempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "host-contract-"))
+	tempRoots.push(dir)
+	return dir
+}
+
+const FIXTURE_BACKEND: ContractBackend = {
+	name: "fixture",
+	build: async (files) =>
+		createPluginResourceAPI({ view: createContainerFixture({ files }) }),
+}
+
+const DIRECTORY_BACKEND: ContractBackend = {
+	name: "directory",
+	build: async (files) => {
+		const dir = withTempDir()
+		for (const [name, content] of Object.entries(files)) {
+			const abs = join(dir, name)
+			mkdirSync(dirname(abs), { recursive: true })
+			writeFileSync(
+				abs,
+				Buffer.from(
+					typeof content === "string"
+						? new TextEncoder().encode(content)
+						: content,
+				),
+			)
+		}
+		return createPluginResourceAPI({ view: createDirectoryContainer(dir) })
+	},
+}
+
+describe("container contract suite", () => {
+	containerContractSuite([FIXTURE_BACKEND, DIRECTORY_BACKEND])
+
+	test("sandboxed hooks see identical results across backends", async () => {
+		const files = { "blob.bin": Uint8Array.from([1, 2, 3, 4, 250]) }
+		const sandbox = createPluginSandbox({
+			...DEFAULT_SANDBOX_CONFIG,
+			watchdogMs: 5_000,
+			hardTimeoutMs: 10_000,
+		})
+		try {
+			const mainPath = fileURLToPath(
+				new URL("../sandbox/fixtures/echo-plugin.mjs", import.meta.url),
+			)
+			const plugin = await sandbox.loadPlugin({
+				id: "echo-contract",
+				mainPath,
+				eager: false,
+			})
+			if (plugin === undefined) {
+				throw new Error("echo fixture failed to load")
+			}
+			const detect = plugin.detect
+			const sourceMeta = plugin.sourceMeta
+			const listFiles = plugin.listFiles
+			if (
+				detect === undefined ||
+				sourceMeta === undefined ||
+				listFiles === undefined
+			) {
+				throw new Error("echo fixture missing hooks")
+			}
+
+			const outputs: unknown[] = []
+			for (const backend of [FIXTURE_BACKEND, DIRECTORY_BACKEND]) {
+				const api = await backend.build(files)
+				outputs.push([
+					await detect(api),
+					await sourceMeta(api),
+					await listFiles(api),
+				])
+			}
+			for (let i = 1; i < outputs.length; i++) {
+				expect(outputs[i]).toEqual(outputs[0])
+			}
+		} finally {
+			await sandbox.disposeAll()
+		}
+	})
+})
+
+afterAll(() => {
+	for (const root of tempRoots) {
+		rmSync(root, { recursive: true, force: true })
+	}
+})