@serverkgg/bridge 0.0.1

package/src/runtime/bridgeFiles.ts

@@ -0,0 +1,412 @@
+import type { Dirent } from "node:fs";
+import { chown, mkdir, readdir, rename, rm, writeFile } from "node:fs/promises";
+import type { BridgeDownloadOptions, BridgeFileEntry, BridgeFiles } from "../context";
+import { compileGlob } from "../utils";
+import type { BridgeLogger } from "./bridgeLog";
+import { BridgePathError, resolveWithin, toSegments } from "./bridgePath";
+import { isPrivileged } from "./bridgePrivilege";
+import { readZip } from "./bridgeZip";
+
+const READ_LIMIT = 4 * 1024 * 1024;
+
+const DOWNLOAD_LIMIT = 512 * 1024 * 1024;
+
+const DOWNLOAD_TIMEOUT_MS = 300_000;
+
+const ARCHIVE_LIMIT = 256 * 1024 * 1024;
+
+const WALK_DEPTH = 12;
+
+const WALK_LIMIT = 4096;
+
+const MILESTONE_STEP = 25;
+
+const USER_AGENT = "serverk-bridge/1.0 (serverk.gg)";
+
+const DIGEST_LENGTHS: Record<string, number> = {
+	sha1: 40,
+	sha256: 64,
+	sha512: 128,
+};
+
+export interface BridgeFilesOptions {
+	root: string;
+	uid: number;
+	gid: number;
+	onLog: BridgeLogger;
+}
+
+const parseDigest = (digest: string) => {
+	const [algo, expected] = digest.split(":");
+
+	if (!algo || !expected || DIGEST_LENGTHS[algo] !== expected.length) {
+		throw new BridgePathError("invalid", `digest "${digest}" is not supported`);
+	}
+
+	return {
+		algo: algo as "sha1" | "sha256" | "sha512",
+		expected,
+	};
+};
+
+const directorySize = async (path: string, depth: number): Promise<number> => {
+	if (depth > WALK_DEPTH) {
+		return 0;
+	}
+
+	let entries: Dirent[];
+
+	try {
+		entries = await readdir(path, {
+			withFileTypes: true,
+		});
+	} catch {
+		return 0;
+	}
+
+	let total = 0;
+
+	for (const entry of entries) {
+		if (entry.isSymbolicLink()) {
+			continue;
+		}
+
+		const absolute = `${path}/${entry.name}`;
+
+		if (entry.isDirectory()) {
+			total += await directorySize(absolute, depth + 1);
+
+			continue;
+		}
+
+		if (entry.isFile()) {
+			total += Bun.file(absolute).size;
+		}
+	}
+
+	return total;
+};
+
+const walk = async (directory: string, prefix: string, depth: number, out: BridgeFileEntry[]) => {
+	if (depth > WALK_DEPTH || out.length >= WALK_LIMIT) {
+		return;
+	}
+
+	let entries: Dirent[];
+
+	try {
+		entries = await readdir(directory, {
+			withFileTypes: true,
+		});
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		if (out.length >= WALK_LIMIT) {
+			return;
+		}
+
+		if (entry.isSymbolicLink()) {
+			continue;
+		}
+
+		const relative = prefix.length === 0 ? entry.name : `${prefix}/${entry.name}`;
+		const absolute = `${directory}/${entry.name}`;
+
+		if (entry.isDirectory()) {
+			await walk(absolute, relative, depth + 1, out);
+
+			continue;
+		}
+
+		if (!entry.isFile()) {
+			continue;
+		}
+
+		const file = Bun.file(absolute);
+
+		out.push({
+			path: relative,
+			name: entry.name,
+			directory: false,
+			sizeBytes: file.size,
+			modifiedAt: new Date(file.lastModified).toISOString(),
+		});
+	}
+};
+
+export const createBridgeFiles = (options: BridgeFilesOptions): BridgeFiles => {
+	const own = async (path: string) => {
+		if (!isPrivileged()) {
+			return;
+		}
+
+		await chown(path, options.uid, options.gid);
+	};
+
+	const ensureDirectory = async (relative: string) => {
+		const segments = toSegments(relative);
+
+		let current = options.root;
+
+		for (const segment of segments) {
+			current = `${current}/${segment}`;
+
+			await mkdir(current, {
+				recursive: true,
+			});
+
+			await own(current);
+		}
+
+		return current;
+	};
+
+	const ensureParent = async (relative: string) => {
+		const segments = toSegments(relative);
+
+		await ensureDirectory(segments.slice(0, -1).join("/"));
+	};
+
+	return {
+		async read(path) {
+			const resolved = await resolveWithin(options.root, path);
+
+			if (!resolved.exists || resolved.isDirectory) {
+				throw new BridgePathError("missing", `path "${path}" is not a readable file`);
+			}
+
+			if (resolved.sizeBytes > READ_LIMIT) {
+				throw new BridgePathError("invalid", `path "${path}" is larger than the read limit`);
+			}
+
+			return await Bun.file(resolved.target).text();
+		},
+
+		async write(path, content) {
+			await ensureParent(path);
+
+			const resolved = await resolveWithin(options.root, path);
+
+			await writeFile(resolved.target, content, "utf8");
+			await own(resolved.target);
+		},
+
+		async list(glob) {
+			const pattern = compileGlob(glob);
+			const entries: BridgeFileEntry[] = [];
+
+			await walk(options.root, "", 0, entries);
+
+			return entries.filter((entry) => pattern.test(entry.path));
+		},
+
+		async remove(path) {
+			const resolved = await resolveWithin(options.root, path);
+
+			if (resolved.isRoot) {
+				throw new BridgePathError("invalid", "the server directory cannot be removed");
+			}
+
+			await rm(resolved.target, {
+				force: true,
+				recursive: true,
+			});
+		},
+
+		async move(from, to) {
+			const source = await resolveWithin(options.root, from);
+			const destination = await resolveWithin(options.root, to);
+
+			if (source.isRoot || destination.isRoot) {
+				throw new BridgePathError("invalid", "the server directory cannot be moved");
+			}
+
+			if (!source.exists) {
+				throw new BridgePathError("missing", `"${from}" does not exist`);
+			}
+
+			if (destination.exists) {
+				throw new BridgePathError("invalid", `"${to}" already exists`);
+			}
+
+			await rename(source.target, destination.target);
+		},
+
+		async ensure(...paths) {
+			for (const path of paths) {
+				await ensureDirectory(path);
+			}
+		},
+
+		async exists(path) {
+			try {
+				return (await resolveWithin(options.root, path)).exists;
+			} catch {
+				return false;
+			}
+		},
+
+		async size(path) {
+			const resolved = await resolveWithin(options.root, path);
+
+			if (!resolved.exists) {
+				return 0;
+			}
+
+			return resolved.isDirectory ? await directorySize(resolved.target, 0) : resolved.sizeBytes;
+		},
+
+		async download(path, url, downloadOptions: BridgeDownloadOptions = {}) {
+			const remote = new URL(url);
+
+			if (remote.protocol !== "https:") {
+				throw new BridgePathError("invalid", `url "${url}" is not https`);
+			}
+
+			const limit = downloadOptions.sizeBytes ?? DOWNLOAD_LIMIT;
+
+			if (limit > DOWNLOAD_LIMIT) {
+				throw new BridgePathError("invalid", `download of ${limit} bytes exceeds the limit`);
+			}
+
+			const response = await fetch(url, {
+				headers: {
+					"user-agent": USER_AGENT,
+				},
+				redirect: "follow",
+				signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+			});
+
+			if (!response.ok || !response.body) {
+				throw new BridgePathError("missing", `${url} answered ${response.status}`);
+			}
+
+			await ensureParent(path);
+
+			const resolved = await resolveWithin(options.root, path);
+			const staging = `${resolved.target}.download`;
+
+			const declared = Number(response.headers.get("content-length"));
+			const totalBytes =
+				Number.isSafeInteger(declared) && declared > 0 ? declared : (downloadOptions.sizeBytes ?? null);
+
+			const hasher = downloadOptions.digest ? new Bun.CryptoHasher(parseDigest(downloadOptions.digest).algo) : null;
+			const writer = Bun.file(staging).writer();
+
+			options.onLog("downloading", {
+				file: resolved.relative,
+				sizeBytes: totalBytes,
+			});
+
+			let readBytes = 0;
+
+			let milestone = 0;
+
+			try {
+				for await (const chunk of response.body) {
+					readBytes += chunk.byteLength;
+
+					if (readBytes > limit) {
+						throw new BridgePathError("invalid", `${url} returned more than ${limit} bytes`);
+					}
+
+					hasher?.update(chunk);
+					writer.write(chunk);
+
+					await writer.flush();
+
+					if (totalBytes !== null) {
+						const reached = Math.floor((readBytes / totalBytes) * 100);
+
+						if (reached >= milestone + MILESTONE_STEP && reached < 100) {
+							milestone = Math.floor(reached / MILESTONE_STEP) * MILESTONE_STEP;
+
+							options.onLog("downloading", {
+								file: resolved.relative,
+								percent: milestone,
+							});
+						}
+					}
+				}
+
+				await writer.end();
+
+				if (downloadOptions.sizeBytes !== undefined && readBytes !== downloadOptions.sizeBytes) {
+					throw new BridgePathError(
+						"invalid",
+						`${url} returned ${readBytes} bytes, expected ${downloadOptions.sizeBytes}`,
+					);
+				}
+
+				if (hasher && downloadOptions.digest) {
+					const { expected } = parseDigest(downloadOptions.digest);
+
+					if (hasher.digest("hex") !== expected) {
+						throw new BridgePathError("invalid", `${url} failed digest verification`);
+					}
+				}
+			} catch (error) {
+				writer.end();
+
+				await rm(staging, {
+					force: true,
+				});
+
+				throw error;
+			}
+
+			await rename(staging, resolved.target);
+			await own(resolved.target);
+
+			options.onLog("downloaded", {
+				file: resolved.relative,
+				sizeBytes: readBytes,
+			});
+		},
+
+		async extract(path, destination, extensions) {
+			const resolved = await resolveWithin(options.root, path);
+
+			if (!resolved.exists || resolved.isDirectory) {
+				throw new BridgePathError("missing", `path "${path}" is not a readable archive`);
+			}
+
+			if (resolved.sizeBytes > ARCHIVE_LIMIT) {
+				throw new BridgePathError("invalid", `archive "${path}" is larger than the extract limit`);
+			}
+
+			const allowed = extensions?.map((extension) => extension.toLowerCase());
+			const target = await ensureDirectory(destination);
+			const buffer = Buffer.from(await Bun.file(resolved.target).arrayBuffer());
+			const written: string[] = [];
+
+			for (const entry of readZip(buffer)) {
+				const name = entry.name.split("/").at(-1) ?? "";
+				const extension = name.split(".").at(-1)?.toLowerCase() ?? "";
+
+				if (name.length === 0 || name.startsWith(".")) {
+					continue;
+				}
+
+				if (allowed !== undefined && !allowed.includes(extension)) {
+					continue;
+				}
+
+				const relative = toSegments(destination).length === 0 ? name : `${toSegments(destination).join("/")}/${name}`;
+
+				await Bun.write(`${target}/${name}`, entry.data);
+				await own(`${target}/${name}`);
+
+				written.push(relative);
+			}
+
+			if (written.length === 0) {
+				throw new BridgePathError("invalid", `archive "${path}" contained no matching files`);
+			}
+
+			return written;
+		},
+	};
+};

package/src/runtime/bridgeLog.ts

@@ -0,0 +1,15 @@
+export type BridgeLogger = (message: string, fields?: Record<string, unknown>) => void;
+
+export const log: BridgeLogger = (message, fields = {}) => {
+	process.stdout.write(
+		`${JSON.stringify({
+			source: "bridge",
+			message,
+			...fields,
+		})}\n`,
+	);
+};
+
+export const errorText = (error: unknown) => {
+	return error instanceof Error ? error.message : String(error);
+};

package/src/runtime/bridgeNet.ts

@@ -0,0 +1,59 @@
+import type { BridgeNet, BridgeRequestOptions } from "../context";
+
+const REQUEST_TIMEOUT_MS = 15_000;
+
+const RESPONSE_LIMIT = 8 * 1024 * 1024;
+
+const USER_AGENT = "serverk-bridge/1.0 (serverk.gg)";
+
+export class BridgeNetError extends Error {
+	readonly status: number | null;
+
+	constructor(status: number | null, message: string) {
+		super(message);
+
+		this.name = "BridgeNetError";
+		this.status = status;
+	}
+}
+
+export const createBridgeNet = (): BridgeNet => {
+	const request = async (url: string, options: BridgeRequestOptions = {}) => {
+		const remote = new URL(url);
+
+		if (remote.protocol !== "https:") {
+			throw new BridgeNetError(null, `"${url}" is not https`);
+		}
+
+		const response = await fetch(url, {
+			headers: {
+				"user-agent": USER_AGENT,
+				...options.headers,
+			},
+			redirect: "follow",
+			signal: AbortSignal.timeout(options.timeoutMs ?? REQUEST_TIMEOUT_MS),
+		});
+
+		if (!response.ok) {
+			throw new BridgeNetError(response.status, `${url} answered ${response.status}`);
+		}
+
+		const body = await response.text();
+
+		if (body.length > RESPONSE_LIMIT) {
+			throw new BridgeNetError(null, `${url} returned more than ${RESPONSE_LIMIT} bytes`);
+		}
+
+		return body;
+	};
+
+	return {
+		async json<Result>(url: string, options?: BridgeRequestOptions) {
+			return JSON.parse(await request(url, options)) as Result;
+		},
+
+		async text(url: string, options?: BridgeRequestOptions) {
+			return await request(url, options);
+		},
+	};
+};

package/src/runtime/bridgePath.ts

@@ -0,0 +1,132 @@
+import { lstat, realpath } from "node:fs/promises";
+
+export class BridgePathError extends Error {
+	readonly kind: "invalid" | "missing";
+
+	constructor(kind: "invalid" | "missing", message: string) {
+		super(message);
+
+		this.name = "BridgePathError";
+		this.kind = kind;
+	}
+}
+
+export interface ResolvedPath {
+	target: string;
+	name: string;
+	relative: string;
+	root: string;
+	isRoot: boolean;
+	exists: boolean;
+	isDirectory: boolean;
+	sizeBytes: number;
+	modifiedAt: string;
+}
+
+export const toSegments = (rawPath: string) => {
+	const segments = rawPath.split("/").filter((segment) => segment.length > 0 && segment !== ".");
+
+	if (segments.some((segment) => segment === ".." || segment.includes("\\"))) {
+		throw new BridgePathError("invalid", `path "${rawPath}" is not allowed`);
+	}
+
+	return segments;
+};
+
+export const resolveWithin = async (root: string, rawPath: string): Promise<ResolvedPath> => {
+	const segments = toSegments(rawPath);
+
+	let base: string;
+
+	try {
+		base = await realpath(root);
+	} catch {
+		throw new BridgePathError("missing", `the server directory "${root}" does not exist`);
+	}
+
+	if (segments.length === 0) {
+		return {
+			target: base,
+			name: "",
+			relative: "",
+			root: base,
+			isRoot: true,
+			exists: true,
+			isDirectory: true,
+			sizeBytes: 0,
+			modifiedAt: "",
+		};
+	}
+
+	const name = segments.at(-1) ?? "";
+	const parentSegments = segments.slice(0, -1);
+
+	let parent: string;
+
+	try {
+		parent = await realpath(
+			[
+				base,
+				...parentSegments,
+			].join("/"),
+		);
+	} catch {
+		return {
+			target: [
+				base,
+				...segments,
+			].join("/"),
+			name,
+			relative: segments.join("/"),
+			root: base,
+			isRoot: false,
+			exists: false,
+			isDirectory: false,
+			sizeBytes: 0,
+			modifiedAt: "",
+		};
+	}
+
+	if (parent !== base && !parent.startsWith(`${base}/`)) {
+		throw new BridgePathError("invalid", `path "${rawPath}" escapes the server directory`);
+	}
+
+	const target = `${parent}/${name}`;
+	const relative = segments.join("/");
+
+	try {
+		const info = await lstat(target);
+
+		if (info.isSymbolicLink()) {
+			throw new BridgePathError("invalid", `path "${rawPath}" is a symlink`);
+		}
+
+		return {
+			target,
+			name,
+			relative,
+			root: base,
+			isRoot: false,
+			exists: true,
+			isDirectory: info.isDirectory(),
+			sizeBytes: info.size,
+			modifiedAt: info.mtime.toISOString(),
+		};
+	} catch (error) {
+		if (error instanceof BridgePathError) {
+			throw error;
+		}
+
+		return {
+			target,
+			name,
+			relative,
+			root: base,
+			isRoot: false,
+			exists: false,
+			isDirectory: false,
+			sizeBytes: 0,
+			modifiedAt: "",
+		};
+	}
+};

package/src/runtime/bridgePrivilege.ts

@@ -0,0 +1,99 @@
+const UID_SETTLE_MS = 3000;
+
+const UID_POLL_MS = 25;
+
+const SETPRIV = "setpriv";
+
+const PROBE_COMMAND = [
+	"sleep",
+	"5",
+];
+
+let nativeUid: boolean | null = null;
+
+export const isPrivileged = () => {
+	return typeof process.getuid === "function" && process.getuid() === 0;
+};
+
+export const readEffectiveUid = async (pid: number) => {
+	try {
+		const status = await Bun.file(`/proc/${pid}/status`).text();
+		const line = status.split("\n").find((entry) => entry.startsWith("Uid:"));
+		const effective = line?.split(/\s+/).at(2);
+
+		return effective === undefined ? null : Number(effective);
+	} catch {
+		return null;
+	}
+};
+
+export const settleUid = async (pid: number, expected: number) => {
+	let observed = await readEffectiveUid(pid);
+
+	for (let waited = 0; observed !== expected && observed !== null && waited < UID_SETTLE_MS; waited += UID_POLL_MS) {
+		await Bun.sleep(UID_POLL_MS);
+
+		observed = await readEffectiveUid(pid);
+	}
+
+	return observed;
+};
+
+const spawnWithUid = (command: string[], uid: number, gid: number) => {
+	const credentials: object = {
+		uid,
+		gid,
+	};
+
+	return Bun.spawn(command, {
+		...credentials,
+		stderr: "ignore",
+		stdin: "ignore",
+		stdout: "ignore",
+	});
+};
+
+export const probeNativeUid = async (uid: number, gid: number) => {
+	if (nativeUid !== null) {
+		return nativeUid;
+	}
+
+	try {
+		const probe = spawnWithUid(PROBE_COMMAND, uid, gid);
+		const observed = await settleUid(probe.pid, uid);
+
+		probe.kill("SIGKILL");
+
+		nativeUid = observed === uid;
+	} catch {
+		nativeUid = false;
+	}
+
+	return nativeUid;
+};
+
+export const setprivArgv = (command: string[], uid: number, gid: number) => {
+	if (!Bun.which(SETPRIV)) {
+		throw new Error(
+			`this runtime ignores the spawn uid option and ${SETPRIV} is missing from the game image, so the bridge cannot start the game as uid ${uid}`,
+		);
+	}
+
+	return [
+		SETPRIV,
+		`--reuid=${uid}`,
+		`--regid=${gid}`,
+		"--clear-groups",
+		"--",
+		...command,
+	];
+};
+
+export const unprivilegedArgv = async (command: string[], uid: number, gid: number) => {
+	const native = await probeNativeUid(uid, gid);
+
+	return {
+		argv: native ? command : setprivArgv(command, uid, gid),
+		native,
+	};
+};