@serverkgg/bridge 0.0.16 → 0.0.18

package/src/runtime/bridgeFiles.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { deflateRawSync } from "node:zlib";
+import { crc32, deflateRawSync } from "node:zlib";
 import type { BridgeFiles } from "../context";
 import { BridgeDownloadError } from "../core";
 import { type BridgeEgress, BridgeEgressCallError } from "./bridgeEgress";
@@ -47,10 +47,12 @@ interface ArchiveEntry {
 
 interface ArchiveOptions {
 	zip64?: boolean;
+	descriptor?: boolean;
 }
 
 const buildZip = (entries: ArchiveEntry[], archiveOptions: ArchiveOptions = {}) => {
 	const zip64 = archiveOptions.zip64 === true;
+	const descriptor = archiveOptions.descriptor === true;
 	const locals: Buffer[] = [];
 	const centrals: Buffer[] = [];
 
@@ -66,9 +68,11 @@ const buildZip = (entries: ArchiveEntry[], archiveOptions: ArchiveOptions = {})
 
 		local.writeUInt32LE(LOCAL_SIGNATURE, 0);
 		local.writeUInt16LE(20, 4);
+		local.writeUInt16LE(descriptor ? 8 : 0, 6);
 		local.writeUInt16LE(method, 8);
-		local.writeUInt32LE(data.length, 18);
-		local.writeUInt32LE(plain.length, 22);
+		local.writeUInt32LE(descriptor ? 0 : crc32(plain), 14);
+		local.writeUInt32LE(descriptor ? 0 : data.length, 18);
+		local.writeUInt32LE(descriptor ? 0 : plain.length, 22);
 		local.writeUInt16LE(name.length, 26);
 
 		const extra = Buffer.alloc(zip64 ? ZIP64_EXTRA_LENGTH : 0);
@@ -85,7 +89,9 @@ const buildZip = (entries: ArchiveEntry[], archiveOptions: ArchiveOptions = {})
 
 		central.writeUInt32LE(CENTRAL_SIGNATURE, 0);
 		central.writeUInt16LE(20, 6);
+		central.writeUInt16LE(descriptor ? 8 : 0, 8);
 		central.writeUInt16LE(method, 10);
+		central.writeUInt32LE(crc32(plain), 16);
 		central.writeUInt32LE(zip64 ? SIZE_SENTINEL : data.length, 20);
 		central.writeUInt32LE(zip64 ? SIZE_SENTINEL : plain.length, 24);
 		central.writeUInt16LE(name.length, 28);
@@ -94,9 +100,17 @@ const buildZip = (entries: ArchiveEntry[], archiveOptions: ArchiveOptions = {})
 		central.writeUInt32LE(zip64 ? SIZE_SENTINEL : offset, 42);
 
 		locals.push(local, name, data);
+		if (descriptor) {
+			const trailer = Buffer.alloc(16);
+			trailer.writeUInt32LE(0x08_07_4b_50, 0);
+			trailer.writeUInt32LE(crc32(plain), 4);
+			trailer.writeUInt32LE(data.length, 8);
+			trailer.writeUInt32LE(plain.length, 12);
+			locals.push(trailer);
+		}
 		centrals.push(central, name, extra);
 
-		offset += 30 + name.length + data.length;
+		offset += 30 + name.length + data.length + (descriptor ? 16 : 0);
 	}
 
 	const body = Buffer.concat(locals);
@@ -220,6 +234,115 @@ describe("extract", () => {
 		expect(await read("mods/alpha.jar")).toBe("alpha");
 	});
 
+	test("preflights duplicate paths, parent collisions and expansion before writing", async () => {
+		for (const entries of [
+			[
+				{
+					name: "a.txt",
+					content: "a",
+				},
+				{
+					name: "a.txt",
+					content: "b",
+				},
+			],
+			[
+				{
+					name: "a",
+					content: "a",
+				},
+				{
+					name: "a/b.txt",
+					content: "b",
+				},
+			],
+		]) {
+			const path = await archive(entries);
+			await expect(
+				files.extract(path, "staging", {
+					tree: true,
+				}),
+			).rejects.toThrow();
+			expect(await Bun.file(`${root}/staging/a.txt`).exists()).toBe(false);
+			expect(await Bun.file(`${root}/staging/a`).exists()).toBe(false);
+		}
+		const path = await archive([
+			{
+				name: "a.txt",
+				content: "1234",
+			},
+			{
+				name: "b.txt",
+				content: "5678",
+			},
+		]);
+		await expect(
+			files.extract(path, "staging", {
+				tree: true,
+				maxBytes: 7,
+			}),
+		).rejects.toThrow("expanded byte limit");
+		expect(await Bun.file(`${root}/staging/a.txt`).exists()).toBe(false);
+	});
+
+	test("allows a bounded per-entry runtime limit without bypassing archive limits", async () => {
+		const path = await archive([
+			{
+				name: "runtime",
+				content: "12345678",
+			},
+		]);
+		await expect(
+			files.extract(path, "staging", {
+				maxEntryBytes: 7,
+			}),
+		).rejects.toThrow("too large");
+		expect(await Bun.file(`${root}/staging/runtime`).exists()).toBe(false);
+		await expect(
+			files.extract(path, "staging", {
+				maxEntryBytes: 8,
+				maxBytes: 7,
+			}),
+		).rejects.toThrow("expanded byte limit");
+		for (const maxEntryBytes of [
+			0,
+			-1,
+			1.5,
+			Number.NaN,
+			512 * 1024 * 1024 + 1,
+		]) {
+			await expect(
+				files.extract(path, "staging", {
+					maxEntryBytes,
+				}),
+			).rejects.toThrow("entry byte limit is invalid");
+		}
+		await files.extract(path, "staging", {
+			maxEntryBytes: 8,
+		});
+		expect(await read("staging/runtime")).toBe("12345678");
+	});
+
+	test("refuses unsafe unselected entries instead of accepting a partly safe archive", async () => {
+		const path = await archive([
+			{
+				name: "safe/a.txt",
+				content: "ok",
+			},
+			{
+				name: "../escape",
+				content: "bad",
+			},
+		]);
+		await expect(
+			files.extract(path, "staging", {
+				tree: true,
+				select: "safe/",
+			}),
+		).rejects.toThrow();
+		expect(await Bun.file(`${root}/staging/a.txt`).exists()).toBe(false);
+	});
+
 	test("flattens paths with no options at all", async () => {
 		const path = await archive([
 			{
@@ -537,6 +660,122 @@ describe("extract", () => {
 		expect(await read("mods/alpha.jar")).toBe("alpha the deflated");
 	});
 
+	test("rejects stored data corruption before writing the destination", async () => {
+		const data = buildZip([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+			},
+		]);
+		data[30 + "alpha.jar".length] = 0x62;
+		await Bun.write(`${root}/corrupt.zip`, data);
+		await expect(files.extract("corrupt.zip", "mods")).rejects.toThrow("CRC32");
+		expect(await Bun.file(`${root}/mods/alpha.jar`).exists()).toBe(false);
+	});
+
+	test("rejects deflated data with a valid size but incorrect checksum", async () => {
+		const path = await archive([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+				compressed: deflateRawSync(Buffer.from("bravo")),
+			},
+		]);
+		await expect(files.extract(path, "mods")).rejects.toThrow("CRC32");
+		expect(await Bun.file(`${root}/mods/alpha.jar`).exists()).toBe(false);
+	});
+
+	test("rejects local and central compression method disagreement", async () => {
+		const data = buildZip([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+			},
+		]);
+		data.writeUInt16LE(DEFLATED, 8);
+		await Bun.write(`${root}/corrupt.zip`, data);
+		await expect(files.extract("corrupt.zip", "mods")).rejects.toThrow("method");
+	});
+
+	test("rejects local names that differ from the central directory", async () => {
+		const data = buildZip([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+			},
+		]);
+		data[30] = 0x62;
+		await Bun.write(`${root}/corrupt.zip`, data);
+		await expect(files.extract("corrupt.zip", "mods")).rejects.toThrow("local name");
+	});
+
+	test("rejects a local variable header that crosses into the central directory", async () => {
+		const data = buildZip([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+			},
+		]);
+		data.writeUInt16LE(65_535, 28);
+		await Bun.write(`${root}/corrupt.zip`, data);
+		await expect(files.extract("corrupt.zip", "mods")).rejects.toThrow("bounds");
+	});
+
+	test("rejects compressed data ranges that cross the central directory", async () => {
+		const data = buildZip([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+			},
+		]);
+		const central = 30 + "alpha.jar".length + "alpha".length;
+		data.writeUInt32LE(100, central + 20);
+		data.writeUInt32LE(100, 18);
+		await Bun.write(`${root}/corrupt.zip`, data);
+		await expect(files.extract("corrupt.zip", "mods")).rejects.toThrow("bounds");
+	});
+
+	test("accepts descriptor entries with zero local checksum and validates the central checksum", async () => {
+		const path = await archive(
+			[
+				{
+					name: "alpha.jar",
+					content: "alpha",
+					compressed: deflateRawSync(Buffer.from("alpha")),
+				},
+			],
+			{
+				descriptor: true,
+			},
+		);
+		await files.extract(path, "mods");
+		expect(await read("mods/alpha.jar")).toBe("alpha");
+	});
+
+	test("rejects local checksum disagreement", async () => {
+		const data = buildZip([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+			},
+		]);
+		data.writeUInt32LE(0, 14);
+		await Bun.write(`${root}/corrupt.zip`, data);
+		await expect(files.extract("corrupt.zip", "mods")).rejects.toThrow("local checksum");
+	});
+
+	test("rejects local compressed-size disagreement", async () => {
+		const data = buildZip([
+			{
+				name: "alpha.jar",
+				content: "alpha",
+			},
+		]);
+		data.writeUInt32LE(4, 18);
+		await Bun.write(`${root}/corrupt.zip`, data);
+		await expect(files.extract("corrupt.zip", "mods")).rejects.toThrow("local sizes");
+	});
+
 	test("reads a zip64 archive through its locator and extended field", async () => {
 		const path = await archive(
 			[
@@ -677,6 +916,93 @@ describe("extract", () => {
 	});
 });
 
+describe("list", () => {
+	let root = "";
+	let files: BridgeFiles;
+	beforeEach(async () => {
+		root = await mkdtemp(`${tmpdir()}/serverk-bridge-list-`);
+		files = createBridgeFiles({
+			root,
+			uid: 0,
+			gid: 0,
+			egress,
+			onLog: silent,
+		});
+	});
+	afterEach(async () => {
+		await rm(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+	test("filters before the result cap and scopes metadata beyond a large runtime tree", async () => {
+		for (let start = 0; start < 4097; start += 64) {
+			await Promise.all(
+				Array.from(
+					{
+						length: Math.min(64, 4097 - start),
+					},
+					(_, index) => files.write(`behavior_packs/vanilla/data-${start + index}.json`, "{}"),
+				),
+			);
+		}
+		await files.write("behavior_packs/custom/manifest.json", "{}");
+		await files.write("worlds/[world]/world_behavior_packs.json", "[]");
+		expect((await files.list("**/manifest.json")).map((entry) => entry.path)).toEqual([
+			"behavior_packs/custom/manifest.json",
+		]);
+		expect((await files.list("worlds/**")).map((entry) => entry.path)).toEqual([
+			"worlds/[world]/world_behavior_packs.json",
+		]);
+		expect(
+			(
+				await files.list("**/*", {
+					directory: "worlds/[world]",
+				})
+			).map((entry) => entry.path),
+		).toEqual([
+			"worlds/[world]/world_behavior_packs.json",
+		]);
+		await expect(files.list("**/*")).rejects.toThrow("result limit");
+	});
+	test("nonrecursive globs ignore unrelated deep trees and respect wildcard directory boundaries", async () => {
+		await files.write("server.jar", "jar");
+		await files.write("server.properties", "settings");
+		await files.write("mods/custom/plugin.jar", "plugin");
+		await files.write(`unrelated/${new Array(14).fill("nested").join("/")}/ignored.jar`, "unrelated");
+		await files.write(`mods/custom/unrelated/${new Array(14).fill("nested").join("/")}/ignored.jar`, "unrelated");
+		expect((await files.list("*")).map((entry) => entry.path).sort()).toEqual([
+			"server.jar",
+			"server.properties",
+		]);
+		expect((await files.list("*.jar")).map((entry) => entry.path)).toEqual([
+			"server.jar",
+		]);
+		expect((await files.list("mods/*/*.jar")).map((entry) => entry.path)).toEqual([
+			"mods/custom/plugin.jar",
+		]);
+		await expect(files.list("**/*.jar")).rejects.toThrow("directory depth limit");
+	});
+	test("refuses partial deep listings and unsafe listing roots", async () => {
+		await files.write(
+			`${Array.from(
+				{
+					length: 14,
+				},
+				() => "nested",
+			).join("/")}/file.txt`,
+			"data",
+		);
+		await expect(files.list("**/*")).rejects.toThrow("directory depth limit");
+		await expect(
+			files.list("**/*", {
+				directory: "../outside",
+			}),
+		).rejects.toThrow();
+		expect(await files.list("absent/**/*.json")).toEqual([]);
+	});
+});
+
 describe("digest", () => {
 	let root = "";
 	let files: BridgeFiles;

package/src/runtime/bridgeFiles.ts

@@ -27,6 +27,7 @@ const ARCHIVE_LIMIT = 2 * 1024 * 1024 * 1024;
 const WALK_DEPTH = 12;
 
 const WALK_LIMIT = 4096;
+const WALK_SCAN_LIMIT = 100_000;
 
 const MILESTONE_STEP = 25;
 
@@ -188,16 +189,30 @@ const selectedName = (name: string, selects: ArchiveSelect[]) => {
 };
 
 const treeSegments = (name: string) => {
-	if (name.startsWith("/") || /^[A-Za-z]:/.test(name)) {
+	if (
+		name.startsWith("/")
+		|| /^[A-Za-z]:/.test(name)
+		|| Array.from(name).some((character) => character.charCodeAt(0) < 32)
+	) {
 		throw new BridgePathError("invalid", `archive entry "${name}" is an absolute path`);
 	}
 
 	return toSegments(name);
 };
 
-const walk = async (directory: string, prefix: string, depth: number, out: BridgeFileEntry[]) => {
-	if (depth > WALK_DEPTH || out.length >= WALK_LIMIT) {
-		return;
+const walk = async (
+	directory: string,
+	prefix: string,
+	depth: number,
+	out: BridgeFileEntry[],
+	pattern: RegExp,
+	directoryPatterns: RegExp[],
+	scan: {
+		visited: number;
+	},
+) => {
+	if (depth > WALK_DEPTH) {
+		throw new BridgePathError("invalid", "file listing exceeded its directory depth limit");
 	}
 
 	let entries: Dirent[];
@@ -207,12 +222,13 @@ const walk = async (directory: string, prefix: string, depth: number, out: Bridg
 			withFileTypes: true,
 		});
 	} catch {
-		return;
+		throw new BridgePathError("invalid", `could not list directory "${prefix}"`);
 	}
 
 	for (const entry of entries) {
-		if (out.length >= WALK_LIMIT) {
-			return;
+		scan.visited += 1;
+		if (scan.visited > WALK_SCAN_LIMIT) {
+			throw new BridgePathError("invalid", "file listing exceeded its scan limit");
 		}
 
 		if (entry.isSymbolicLink()) {
@@ -223,14 +239,19 @@ const walk = async (directory: string, prefix: string, depth: number, out: Bridg
 		const absolute = `${directory}/${entry.name}`;
 
 		if (entry.isDirectory()) {
-			await walk(absolute, relative, depth + 1, out);
+			if (directoryPatterns.some((candidate) => candidate.test(relative))) {
+				await walk(absolute, relative, depth + 1, out, pattern, directoryPatterns, scan);
+			}
 
 			continue;
 		}
 
-		if (!entry.isFile()) {
+		if (!entry.isFile() || !pattern.test(relative)) {
 			continue;
 		}
+		if (out.length >= WALK_LIMIT) {
+			throw new BridgePathError("invalid", "file listing exceeded its result limit");
+		}
 
 		const file = Bun.file(absolute);
 
@@ -345,13 +366,36 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			await own(resolved.target);
 		},
 
-		async list(glob) {
+		async list(glob, listOptions = {}) {
 			const pattern = compileGlob(glob);
+			const globSegments = glob.split("/");
+			const directoryPatterns = globSegments.flatMap((segment, index) =>
+				index < globSegments.length - 1 || segment === "**"
+					? [
+							compileGlob(globSegments.slice(0, index + 1).join("/")),
+						]
+					: [],
+			);
 			const entries: BridgeFileEntry[] = [];
-
-			await walk(options.root, "", 0, entries);
-
-			return entries.filter((entry) => pattern.test(entry.path));
+			const segments: string[] = [];
+			for (const segment of glob.split("/").slice(0, -1)) {
+				if (/[?*[\]{}!\\]/.test(segment)) {
+					break;
+				}
+				segments.push(segment);
+			}
+			const prefix = toSegments(listOptions.directory ?? segments.join("/")).join("/");
+			const resolved = await resolveWithin(options.root, prefix);
+			if (!resolved.exists) {
+				return [];
+			}
+			if (!resolved.isDirectory) {
+				throw new BridgePathError("invalid", `path "${prefix}" is not a directory to list`);
+			}
+			await walk(resolved.target, prefix, 0, entries, pattern, directoryPatterns, {
+				visited: 0,
+			});
+			return entries;
 		},
 
 		async remove(path) {
@@ -551,8 +595,57 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 			const selects = compileSelects(extractOptions.select, extractOptions.selects);
 			const excluded = compileGlobs(extractOptions.exclude ?? []);
 			const base = toSegments(destination);
-			const target = await ensureDirectory(destination);
-			const archive = await openZip(resolved.target, tree ? ZIP_TREE_ENTRY_LIMIT : ZIP_ENTRY_LIMIT);
+			await ensureDirectory(destination);
+			const archive = await openZip(
+				resolved.target,
+				tree ? ZIP_TREE_ENTRY_LIMIT : ZIP_ENTRY_LIMIT,
+				extractOptions.maxEntryBytes,
+			);
+			const maxBytes = extractOptions.maxBytes ?? ARCHIVE_LIMIT;
+			if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > ARCHIVE_LIMIT) {
+				throw new BridgePathError("invalid", "archive expansion limit is invalid");
+			}
+			const destinations = new Set<string>();
+			let expandedBytes = 0;
+			for (const entry of archive.entries) {
+				treeSegments(entry.name);
+				if (entry.symlink) {
+					throw new BridgePathError("invalid", `archive entry "${entry.name}" is a symlink`);
+				}
+				expandedBytes += entry.sizeBytes;
+				if (!Number.isSafeInteger(expandedBytes) || expandedBytes > maxBytes) {
+					throw new BridgePathError("invalid", "archive exceeds the expanded byte limit");
+				}
+				const selected = selectedName(entry.name, selects);
+				if (selected === null || matchesAny(selected, excluded)) {
+					continue;
+				}
+				const segments = tree
+					? treeSegments(selected)
+					: [
+							selected.split("/").at(-1) ?? "",
+						];
+				const name = segments.at(-1) ?? "";
+				if (!name || segments.some((segment) => segment.startsWith("."))) {
+					continue;
+				}
+				if (allowed !== undefined && !allowed.includes(name.split(".").at(-1)?.toLowerCase() ?? "")) {
+					continue;
+				}
+				const destinationName = segments.join("/");
+				if (destinations.has(destinationName)) {
+					throw new BridgePathError("invalid", `archive has duplicate destination "${destinationName}"`);
+				}
+				destinations.add(destinationName);
+			}
+			for (const name of destinations) {
+				const segments = name.split("/");
+				for (let index = 1; index < segments.length; index++) {
+					if (destinations.has(segments.slice(0, index).join("/"))) {
+						throw new BridgePathError("invalid", `archive file "${name}" conflicts with a parent file`);
+					}
+				}
+			}
 			const directories = new Set<string>();
 			const written: string[] = [];
 
@@ -602,8 +695,9 @@ export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
 					...segments,
 				].join("/");
 
-				await Bun.write(`${target}/${segments.join("/")}`, await archive.read(entry));
-				await own(`${target}/${segments.join("/")}`);
+				const output = await resolveWithin(options.root, relative);
+				await Bun.write(output.target, await archive.read(entry));
+				await own(output.target);
 
 				written.push(relative);
 			}

package/src/runtime/bridgeRegistry.test.ts

@@ -693,3 +693,64 @@ describe("the setup singleton", () => {
 		expect(registryFor(baseDriver()).manifest().setup).toBeNull();
 	});
 });
+
+describe("protected action dispatch", () => {
+	test("advertises protection and refuses old callers before touching files", async () => {
+		let calls = 0;
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				world: {
+					kind: BridgeKind.Actions,
+					protectedActions: [
+						"replace",
+					],
+					actions: {
+						replace: async () => {
+							calls += 1;
+						},
+					},
+				},
+			},
+		});
+		expect(registry.manifest().modules[0]?.protectedActions).toEqual([
+			"replace",
+		]);
+		await expect(registry.invoke("world", "replace")).rejects.toThrow("needs a recovery operation");
+		expect(calls).toBe(0);
+		await registry.invoke("world", "replace", {}, "01993720-0000-7000-8000-000000000001");
+		expect(calls).toBe(1);
+	});
+	test("rejects protection metadata for unknown actions or running-only modules", () => {
+		for (const module of [
+			{
+				kind: BridgeKind.Actions as const,
+				protectedActions: [
+					"missing",
+				],
+				actions: {
+					replace: async () => {},
+				},
+			},
+			{
+				kind: BridgeKind.Actions as const,
+				protectedActions: [
+					"replace",
+				],
+				requiresRunning: true,
+				actions: {
+					replace: async () => {},
+				},
+			},
+		]) {
+			expect(() =>
+				registryFor({
+					...baseDriver(),
+					modules: {
+						world: module,
+					},
+				}).manifest(),
+			).toThrow("protected actions");
+		}
+	});
+});