@narumitw/pi-sync 0.30.0 → 0.34.0

package/src/git-config.ts

@@ -0,0 +1,136 @@
+const DEFAULT_GIT_BRANCH = "pi-sync";
+const DEFAULT_GIT_DIRECTORY = "pi-sync";
+
+export function normalizeGitRemote(value: string | undefined) {
+	const normalized = normalizeOptionalString(value);
+	if (!normalized) return undefined;
+	if (
+		hasControlCharacter(normalized) ||
+		/\s/u.test(normalized) ||
+		normalized.startsWith("-") ||
+		normalized.includes("\\")
+	) {
+		throw new Error("Invalid pi-sync Git remote.");
+	}
+	if (
+		!normalized.includes("://") &&
+		/^(?:[A-Za-z0-9._-]+@)?(?:\[[0-9A-Fa-f:]+\]|[A-Za-z0-9.-]+):(?!-)[^:].+$/u.test(normalized)
+	) {
+		return normalized;
+	}
+	if (/^[A-Za-z][A-Za-z0-9+.-]*:/u.test(normalized) && !normalized.includes("://")) {
+		throw new Error("Invalid pi-sync Git remote: unsupported transport or remote-helper syntax.");
+	}
+	let url: URL;
+	try {
+		url = new URL(normalized);
+	} catch {
+		throw new Error("Invalid pi-sync Git remote: use an SSH or HTTPS remote.");
+	}
+	if (url.protocol !== "https:" && url.protocol !== "ssh:") {
+		throw new Error("Invalid pi-sync Git remote: only SSH and HTTPS are supported.");
+	}
+	if (url.password || (url.protocol === "https:" && url.username)) {
+		throw new Error("Invalid pi-sync Git remote: URL credentials or userinfo are not allowed.");
+	}
+	if (url.search || url.hash || !url.hostname || !url.pathname || url.pathname === "/") {
+		throw new Error("Invalid pi-sync Git remote.");
+	}
+	return url.toString();
+}
+
+export function normalizeGitRemoteIdentity(value: string) {
+	const normalized = normalizeGitRemote(value);
+	if (!normalized) return "";
+	if (!normalized.includes("://")) {
+		const match =
+			/^(?<user>[A-Za-z0-9._-]+@)?(?<host>\[[0-9A-Fa-f:]+\]|[A-Za-z0-9.-]+):(?<path>.+)$/u.exec(
+				normalized,
+			);
+		if (!match?.groups) return normalized;
+		const userAndHost = `${match.groups.user ?? ""}${match.groups.host.toLowerCase()}`;
+		const remotePath = match.groups.path.replace(/\/+$/gu, "");
+		return remotePath.startsWith("/")
+			? `scp-absolute://${userAndHost}${remotePath}`
+			: `ssh://${userAndHost}/${remotePath}`;
+	}
+	const url = new URL(normalized);
+	url.hostname = url.hostname.toLowerCase();
+	if (url.protocol === "ssh:" && url.port === "22") url.port = "";
+	url.pathname = url.pathname.replace(/\/+$/gu, "");
+	if (url.protocol === "ssh:") {
+		return `ssh://${url.username ? `${url.username}@` : ""}${url.host}${url.pathname}`;
+	}
+	return url.toString();
+}
+
+export function normalizeGitBranch(value: string | undefined) {
+	const branch = normalizeOptionalString(value) ?? DEFAULT_GIT_BRANCH;
+	if (
+		branch === "@" ||
+		branch.startsWith("-") ||
+		branch.startsWith("refs/") ||
+		branch.startsWith("/") ||
+		branch.endsWith("/") ||
+		branch.endsWith(".") ||
+		branch.includes("..") ||
+		branch.includes("@{") ||
+		branch.includes("\\") ||
+		hasControlCharacter(branch) ||
+		/[ ~^:?*[\]]/u.test(branch) ||
+		branch
+			.split("/")
+			.some((segment) => !segment || segment.startsWith(".") || segment.endsWith(".lock"))
+	) {
+		throw new Error("Invalid pi-sync Git branch.");
+	}
+	return branch;
+}
+
+export function normalizeGitDirectory(value: string | undefined) {
+	const directory = trimSlashes(normalizeOptionalString(value) ?? DEFAULT_GIT_DIRECTORY);
+	if (
+		!directory ||
+		directory.startsWith("-") ||
+		directory.includes("\\") ||
+		hasControlCharacter(directory) ||
+		directory
+			.split("/")
+			.some((segment) => !segment || segment === "." || segment === ".." || segment === ".git")
+	) {
+		throw new Error("Invalid pi-sync Git directory.");
+	}
+	return directory;
+}
+
+export function validateGitNamespace(value: string) {
+	if (
+		value.length > 256 ||
+		value === "." ||
+		value === ".." ||
+		value.includes("/") ||
+		value.includes("\\") ||
+		hasControlCharacter(value)
+	) {
+		throw new Error("Invalid pi-sync Git namespace.");
+	}
+}
+
+function normalizeOptionalString(value: unknown) {
+	if (value !== undefined && typeof value !== "string") {
+		throw new Error("Invalid pi-sync settings: expected a string.");
+	}
+	const normalized = value?.trim();
+	return normalized || undefined;
+}
+
+function trimSlashes(value: string) {
+	return value.replace(/^\/+|\/+$/gu, "");
+}
+
+function hasControlCharacter(value: string) {
+	return [...value].some((character) => {
+		const code = character.codePointAt(0) ?? 0;
+		return code < 0x20 || (code >= 0x7f && code <= 0x9f);
+	});
+}

package/src/git-runner.ts

@@ -0,0 +1,276 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_OUTPUT_LIMIT = 1024 * 1024;
+
+export interface GitRunOptions {
+	gitDir?: string;
+	cwd?: string;
+	input?: Buffer | string;
+	env?: NodeJS.ProcessEnv;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	maxOutputBytes?: number;
+	allowFileProtocol?: boolean;
+}
+
+export interface GitRunResult {
+	stdout: Buffer;
+	stderr: Buffer;
+}
+
+export class GitCommandError extends Error {
+	readonly code = "GIT_COMMAND_FAILED";
+	constructor(
+		message: string,
+		readonly exitCode: number | null,
+		readonly stderr: string,
+		options?: ErrorOptions,
+	) {
+		super(message, options);
+		this.name = "GitCommandError";
+	}
+}
+
+export async function runGit(args: string[], options: GitRunOptions = {}): Promise<GitRunResult> {
+	throwIfAborted(options.signal);
+	const hooksPath = process.platform === "win32" ? "NUL" : "/dev/null";
+	const protocolArgs = [
+		"-c",
+		`core.hooksPath=${hooksPath}`,
+		"-c",
+		"gc.auto=0",
+		"-c",
+		"maintenance.auto=false",
+		"-c",
+		"protocol.allow=never",
+		"-c",
+		"protocol.https.allow=always",
+		"-c",
+		"protocol.ssh.allow=always",
+	];
+	if (options.allowFileProtocol) protocolArgs.push("-c", "protocol.file.allow=always");
+	const commandArgs = [
+		...(options.gitDir ? [`--git-dir=${options.gitDir}`] : []),
+		...protocolArgs,
+		...args,
+	];
+	const inheritedEnvironment = Object.fromEntries(
+		Object.entries(process.env).filter(
+			([key]) =>
+				!key.startsWith("GIT_") &&
+				key !== "PAGER" &&
+				key !== "EDITOR" &&
+				key !== "VISUAL" &&
+				key !== "SSH_ASKPASS" &&
+				key !== "SSH_ASKPASS_REQUIRE",
+		),
+	);
+	const allowedGitOverrides = new Set([
+		"GIT_INDEX_FILE",
+		"GIT_AUTHOR_NAME",
+		"GIT_AUTHOR_EMAIL",
+		"GIT_AUTHOR_DATE",
+		"GIT_COMMITTER_NAME",
+		"GIT_COMMITTER_EMAIL",
+		"GIT_COMMITTER_DATE",
+	]);
+	const suppliedEnvironment = Object.fromEntries(
+		Object.entries(options.env ?? {}).filter(
+			([key]) => !key.startsWith("GIT_") || allowedGitOverrides.has(key),
+		),
+	);
+	const env: NodeJS.ProcessEnv = {
+		...inheritedEnvironment,
+		...suppliedEnvironment,
+		LC_ALL: "C",
+		LANG: "C",
+		GIT_CONFIG_NOSYSTEM: "1",
+		GIT_TERMINAL_PROMPT: "0",
+		GCM_INTERACTIVE: "Never",
+		GIT_PAGER: "cat",
+		PAGER: "cat",
+		GIT_EDITOR: "true",
+		EDITOR: "true",
+		VISUAL: "true",
+		GIT_ASKPASS: "",
+		SSH_ASKPASS: "",
+		SSH_ASKPASS_REQUIRE: "never",
+		GIT_SSH_COMMAND: "ssh -oBatchMode=yes",
+	};
+	const child = spawn("git", commandArgs, {
+		cwd: options.cwd,
+		env,
+		stdio: ["pipe", "pipe", "pipe"],
+		detached: process.platform !== "win32",
+		windowsHide: true,
+	});
+	const stdout: Buffer[] = [];
+	const stderr: Buffer[] = [];
+	let total = 0;
+	let settled = false;
+	let terminationError: Error | undefined;
+	let escalationTimer: NodeJS.Timeout | undefined;
+	const limit = options.maxOutputBytes ?? DEFAULT_OUTPUT_LIMIT;
+
+	const terminate = (error: Error) => {
+		if (settled || terminationError) return;
+		terminationError = error;
+		if (child.pid && process.platform !== "win32") {
+			try {
+				process.kill(-child.pid, "SIGTERM");
+			} catch {
+				child.kill("SIGTERM");
+			}
+		} else {
+			child.kill("SIGTERM");
+			if (child.pid && process.platform === "win32") {
+				const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+					stdio: "ignore",
+					windowsHide: true,
+				});
+				killer.on("error", () => undefined);
+				killer.unref();
+			}
+		}
+		escalationTimer = setTimeout(() => {
+			if (settled) return;
+			if (child.pid && process.platform !== "win32") {
+				try {
+					process.kill(-child.pid, "SIGKILL");
+				} catch {
+					child.kill("SIGKILL");
+				}
+			} else {
+				child.kill("SIGKILL");
+			}
+		}, 2_000);
+	};
+	const collect = (target: Buffer[]) => (chunk: Buffer) => {
+		total += chunk.byteLength;
+		if (total > limit) {
+			terminate(new Error(`Git output exceeds the ${limit}-byte limit.`));
+			return;
+		}
+		target.push(Buffer.from(chunk));
+	};
+	child.stdout.on("data", collect(stdout));
+	child.stderr.on("data", collect(stderr));
+	child.stdin.on("error", () => undefined);
+	child.stdin.end(options.input);
+	const onAbort = () =>
+		terminate(
+			options.signal?.reason instanceof Error
+				? options.signal.reason
+				: new DOMException("The operation was aborted", "AbortError"),
+		);
+	options.signal?.addEventListener("abort", onAbort, { once: true });
+	const timer = setTimeout(
+		() =>
+			terminate(
+				new Error(`Git command timed out after ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms.`),
+			),
+		options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+	);
+
+	let result: GitRunResult;
+	try {
+		result = await new Promise<GitRunResult>((resolve, reject) => {
+			child.once("error", reject);
+			child.once("close", (code) => {
+				settled = true;
+				if (escalationTimer) clearTimeout(escalationTimer);
+				const stdoutBuffer = Buffer.concat(stdout);
+				const stderrBuffer = Buffer.concat(stderr);
+				if (terminationError) {
+					reject(terminationError);
+					return;
+				}
+				if (code !== 0) {
+					const stderrText = stderrBuffer.toString("utf8").trim();
+					reject(
+						new GitCommandError(
+							stderrText || `Git exited with status ${code ?? "unknown"}.`,
+							code,
+							stderrText,
+						),
+					);
+					return;
+				}
+				resolve({ stdout: stdoutBuffer, stderr: stderrBuffer });
+			});
+		});
+	} finally {
+		clearTimeout(timer);
+		if (escalationTimer) clearTimeout(escalationTimer);
+		options.signal?.removeEventListener("abort", onAbort);
+	}
+	return result;
+}
+
+export function parseGitBlobBatch(output: Buffer, expectedCount: number, maxContentBytes: number) {
+	if (!Number.isSafeInteger(expectedCount) || expectedCount < 0) {
+		throw new Error("Invalid Git batch object count.");
+	}
+	if (!Number.isSafeInteger(maxContentBytes) || maxContentBytes < 0) {
+		throw new Error("Invalid Git batch content limit.");
+	}
+	const blobs: Buffer[] = [];
+	let offset = 0;
+	let contentBytes = 0;
+	for (let index = 0; index < expectedCount; index += 1) {
+		const headerEnd = output.indexOf(0x0a, offset);
+		if (headerEnd < 0) throw new Error("Git cat-file batch response is truncated.");
+		const header = output.subarray(offset, headerEnd).toString("utf8");
+		if (header.endsWith(" missing")) throw new Error("Git cat-file batch object is missing.");
+		const match = /^(?<object>[0-9a-f]{40}) blob (?<size>0|[1-9][0-9]*)$/u.exec(header);
+		if (!match?.groups) throw new Error("Git cat-file batch response is malformed.");
+		const size = Number(match.groups.size);
+		if (!Number.isSafeInteger(size)) throw new Error("Git cat-file batch size is malformed.");
+		contentBytes += size;
+		if (contentBytes > maxContentBytes) {
+			throw new Error(`Git cat-file batch content exceeds the ${maxContentBytes}-byte limit.`);
+		}
+		const contentStart = headerEnd + 1;
+		const contentEnd = contentStart + size;
+		if (contentEnd >= output.length) throw new Error("Git cat-file batch response is truncated.");
+		if (output[contentEnd] !== 0x0a) {
+			throw new Error("Git cat-file batch response is malformed.");
+		}
+		blobs.push(Buffer.from(output.subarray(contentStart, contentEnd)));
+		offset = contentEnd + 1;
+	}
+	if (offset !== output.length) throw new Error("Git cat-file batch response has trailing data.");
+	return blobs;
+}
+
+export async function readGitBlobs(
+	objects: string[],
+	options: Omit<GitRunOptions, "input" | "maxOutputBytes"> & { maxOutputBytes: number },
+) {
+	if (objects.length === 0) return [];
+	if (!Number.isSafeInteger(options.maxOutputBytes) || options.maxOutputBytes < 0) {
+		throw new Error("Invalid Git batch output limit.");
+	}
+	if (objects.some((object) => !/^[0-9a-f]{40}$/u.test(object))) {
+		throw new Error("Invalid Git blob object id.");
+	}
+	const protocolOverhead = objects.length * 96;
+	if (!Number.isSafeInteger(protocolOverhead + options.maxOutputBytes)) {
+		throw new Error("Invalid Git batch output limit.");
+	}
+	const result = await runGit(["cat-file", "--batch"], {
+		...options,
+		input: `${objects.join("\n")}\n`,
+		maxOutputBytes: options.maxOutputBytes + protocolOverhead,
+	});
+	return parseGitBlobBatch(result.stdout, objects.length, options.maxOutputBytes);
+}
+
+function throwIfAborted(signal?: AbortSignal) {
+	if (!signal?.aborted) return;
+	throw signal.reason instanceof Error
+		? signal.reason
+		: new DOMException("The operation was aborted", "AbortError");
+}

package/src/git-storage.ts

@@ -0,0 +1,288 @@
+import { createHash } from "node:crypto";
+import type { Snapshot } from "./types.js";
+
+export const GIT_MANIFEST_VERSION = 2;
+export const MAX_GIT_MANIFEST_BYTES = 1024 * 1024;
+export const MAX_GIT_TREE_OUTPUT_BYTES = 16 * 1024 * 1024;
+export const MAX_GIT_PAYLOAD_BYTES = 100 * 1024 * 1024;
+export const MAX_GIT_SNAPSHOT_BYTES = 512 * 1024 * 1024;
+const SNAPSHOT_VERSION = 1;
+
+export interface GitManifestFile {
+	path: string;
+	sha256: string;
+	size: number;
+}
+
+export interface GitManifest {
+	version: number;
+	snapshotVersion: number;
+	snapshotId: string;
+	createdAt: string;
+	machine: string;
+	profile: string;
+	syncSessions: boolean;
+	snapshotSyncSessions?: boolean;
+	files: GitManifestFile[];
+}
+
+export interface PreparedGitFile extends GitManifestFile {
+	content: Buffer;
+}
+
+export interface GitTreeEntry {
+	mode: string;
+	type: string;
+	object: string;
+	path: string;
+}
+
+export function isGitPayloadSizeAllowed(size: number) {
+	return Number.isSafeInteger(size) && size >= 0 && size <= MAX_GIT_PAYLOAD_BYTES;
+}
+
+export function requireGitManifest(value: unknown): GitManifest {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("Git publication manifest is malformed.");
+	}
+	const manifest = value as Partial<GitManifest>;
+	if (manifest.version === 1) {
+		throw new Error(
+			"Git publication uses the unsupported pre-release gzip format; recreate this pi-sync-owned test branch.",
+		);
+	}
+	if (
+		manifest.version !== GIT_MANIFEST_VERSION ||
+		manifest.snapshotVersion !== SNAPSHOT_VERSION ||
+		typeof manifest.snapshotId !== "string" ||
+		manifest.snapshotId.length > 512 ||
+		!/^[A-Za-z0-9._-]+$/u.test(manifest.snapshotId) ||
+		typeof manifest.createdAt !== "string" ||
+		manifest.createdAt.length > 64 ||
+		hasControlCharacter(manifest.createdAt) ||
+		Number.isNaN(Date.parse(manifest.createdAt)) ||
+		typeof manifest.machine !== "string" ||
+		manifest.machine.length > 256 ||
+		hasControlCharacter(manifest.machine) ||
+		typeof manifest.profile !== "string" ||
+		manifest.profile.length === 0 ||
+		manifest.profile.length > 256 ||
+		hasControlCharacter(manifest.profile) ||
+		typeof manifest.syncSessions !== "boolean" ||
+		(manifest.snapshotSyncSessions !== undefined &&
+			typeof manifest.snapshotSyncSessions !== "boolean") ||
+		!Array.isArray(manifest.files) ||
+		!hasExactKeys(manifest as Record<string, unknown>, [
+			"version",
+			"snapshotVersion",
+			"snapshotId",
+			"createdAt",
+			"machine",
+			"profile",
+			"syncSessions",
+			...(manifest.snapshotSyncSessions === undefined ? [] : ["snapshotSyncSessions"]),
+			"files",
+		])
+	) {
+		throw new Error("Git publication manifest is malformed.");
+	}
+	let total = 0;
+	const paths = new Set<string>();
+	for (const rawFile of manifest.files) {
+		if (!rawFile || typeof rawFile !== "object" || Array.isArray(rawFile)) {
+			throw new Error("Git publication manifest file is malformed.");
+		}
+		const file = rawFile as Partial<GitManifestFile>;
+		if (
+			!hasExactKeys(file as Record<string, unknown>, ["path", "sha256", "size"]) ||
+			!isSafeSnapshotPath(file.path) ||
+			typeof file.sha256 !== "string" ||
+			!/^[0-9a-f]{64}$/u.test(file.sha256) ||
+			typeof file.size !== "number" ||
+			!isGitPayloadSizeAllowed(file.size) ||
+			paths.has(file.path)
+		) {
+			throw new Error("Git publication manifest file is malformed.");
+		}
+		total += file.size;
+		if (!Number.isSafeInteger(total) || total > MAX_GIT_SNAPSHOT_BYTES) {
+			throw new Error(`Git snapshot content exceeds the ${MAX_GIT_SNAPSHOT_BYTES}-byte limit.`);
+		}
+		paths.add(file.path);
+	}
+	assertNoPathConflicts([...paths]);
+	return manifest as GitManifest;
+}
+
+export function validateGitSnapshot(snapshot: Snapshot, manifest: GitManifest, namespace: string) {
+	const prepared = prepareGitSnapshot(snapshot, namespace);
+	const syncSessions =
+		snapshot.syncSessions === true ||
+		snapshot.files.some((file) => file.path.startsWith("sessions/"));
+	if (
+		snapshot.id !== manifest.snapshotId ||
+		snapshot.createdAt !== manifest.createdAt ||
+		snapshot.machine !== manifest.machine ||
+		snapshot.profile !== manifest.profile ||
+		snapshot.syncSessions !== manifest.snapshotSyncSessions ||
+		syncSessions !== manifest.syncSessions ||
+		prepared.length !== manifest.files.length ||
+		prepared.some((file, index) => {
+			const expected = manifest.files[index];
+			return (
+				!expected ||
+				file.path !== expected.path ||
+				file.sha256 !== expected.sha256 ||
+				file.size !== expected.size
+			);
+		})
+	) {
+		throw new Error("Git snapshot identity does not match its publication manifest.");
+	}
+}
+
+export function prepareGitSnapshot(snapshot: Snapshot, namespace: string) {
+	if (
+		snapshot.version !== SNAPSHOT_VERSION ||
+		typeof snapshot.id !== "string" ||
+		!snapshot.id ||
+		snapshot.id.length > 512 ||
+		!/^[A-Za-z0-9._-]+$/u.test(snapshot.id) ||
+		snapshot.profile !== namespace ||
+		!Array.isArray(snapshot.files) ||
+		typeof snapshot.createdAt !== "string" ||
+		!snapshot.createdAt ||
+		snapshot.createdAt.length > 64 ||
+		hasControlCharacter(snapshot.createdAt) ||
+		Number.isNaN(Date.parse(snapshot.createdAt)) ||
+		typeof snapshot.machine !== "string" ||
+		snapshot.machine.length > 256 ||
+		hasControlCharacter(snapshot.machine)
+	) {
+		throw new Error("Invalid Git snapshot publication.");
+	}
+	const paths = new Set<string>();
+	const prepared: PreparedGitFile[] = [];
+	let total = 0;
+	for (const file of snapshot.files) {
+		if (
+			!isSafeSnapshotPath(file.path) ||
+			typeof file.contentBase64 !== "string" ||
+			typeof file.sha256 !== "string" ||
+			!/^[0-9a-f]{64}$/u.test(file.sha256) ||
+			paths.has(file.path)
+		) {
+			throw new Error("Invalid Git snapshot file.");
+		}
+		const content = Buffer.from(file.contentBase64, "base64");
+		if (content.toString("base64") !== file.contentBase64 || sha256(content) !== file.sha256) {
+			throw new Error("Git snapshot file checksum mismatch.");
+		}
+		if (!isGitPayloadSizeAllowed(content.byteLength)) {
+			throw new Error(
+				`Git snapshot file exceeds GitHub's ${MAX_GIT_PAYLOAD_BYTES}-byte regular-Git limit: ${file.path}`,
+			);
+		}
+		total += content.byteLength;
+		if (!Number.isSafeInteger(total) || total > MAX_GIT_SNAPSHOT_BYTES) {
+			throw new Error(`Git snapshot content exceeds the ${MAX_GIT_SNAPSHOT_BYTES}-byte limit.`);
+		}
+		paths.add(file.path);
+		prepared.push({ path: file.path, sha256: file.sha256, size: content.byteLength, content });
+	}
+	assertNoPathConflicts([...paths]);
+	return prepared;
+}
+
+export function parseGitTree(output: Buffer): GitTreeEntry[] {
+	if (output.byteLength === 0) return [];
+	if (output.at(-1) !== 0) throw new Error("Git publication tree response is malformed.");
+	return output
+		.subarray(0, -1)
+		.toString("utf8")
+		.split("\0")
+		.map((line) => {
+			const match =
+				/^(?<mode>[0-9]{6}) (?<type>blob|tree|commit) (?<object>[0-9a-f]{40})\t(?<path>.+)$/u.exec(
+					line,
+				);
+			if (!match?.groups || hasControlCharacter(match.groups.path)) {
+				throw new Error("Git publication tree response is malformed.");
+			}
+			return {
+				mode: match.groups.mode,
+				type: match.groups.type,
+				object: match.groups.object,
+				path: match.groups.path,
+			};
+		});
+}
+
+export function validateGitPublicationTree(
+	entries: GitTreeEntry[],
+	manifest: GitManifest,
+	manifestPath: string,
+	filePath: (path: string) => string,
+) {
+	const byPath = new Map<string, GitTreeEntry>();
+	for (const entry of entries) {
+		if (byPath.has(entry.path)) throw new Error("Git publication tree contains duplicate paths.");
+		byPath.set(entry.path, entry);
+	}
+	const expectedPaths = [manifestPath, ...manifest.files.map((file) => filePath(file.path))];
+	if (entries.length !== expectedPaths.length || expectedPaths.some((path) => !byPath.has(path))) {
+		throw new Error("Git publication tree has missing or extra files.");
+	}
+	for (const expectedPath of expectedPaths) {
+		const entry = byPath.get(expectedPath);
+		if (entry?.mode !== "100644" || entry.type !== "blob") {
+			throw new Error(`Git publication tree contains a non-regular file: ${expectedPath}`);
+		}
+	}
+	return manifest.files.map((file) => byPath.get(filePath(file.path)) as GitTreeEntry);
+}
+
+function isSafeSnapshotPath(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.length <= 4096 &&
+		!value.startsWith("/") &&
+		!value.includes("\\") &&
+		!hasControlCharacter(value) &&
+		value
+			.split("/")
+			.every(
+				(segment) =>
+					segment && segment !== "." && segment !== ".." && segment.toLowerCase() !== ".git",
+			)
+	);
+}
+
+function hasExactKeys(value: Record<string, unknown>, expected: string[]) {
+	const keys = Object.keys(value).sort();
+	const expectedKeys = [...expected].sort();
+	return (
+		keys.length === expectedKeys.length && keys.every((key, index) => key === expectedKeys[index])
+	);
+}
+
+function assertNoPathConflicts(paths: string[]) {
+	const sorted = [...paths].sort();
+	for (let index = 1; index < sorted.length; index += 1) {
+		const parent = sorted[index - 1];
+		const child = sorted[index];
+		if (parent && child?.startsWith(`${parent}/`)) {
+			throw new Error(`Git snapshot file path conflict: ${parent} and ${child}`);
+		}
+	}
+}
+
+function sha256(value: Buffer) {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function hasControlCharacter(value: string) {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: Reject untrusted terminal/ref controls.
+	return /[\u0000-\u001f\u007f-\u009f]/u.test(value);
+}