@cloudflare/sandbox 0.13.0-next.769.1 → 1.0.0-rc.0

package/dist/index.mjs

@@ -0,0 +1,2452 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+import * as z from "zod/mini";
+import { constants } from "node:os";
+import { AwsClient } from "aws4fetch";
+//#region src/directory-backups/gateway.ts
+const PART_PATH = /^\/parts\/([1-9][0-9]{0,8})$/;
+const RANGE = /^bytes=([0-9]{1,15})-([0-9]{1,15})$/;
+const MAX_DETAIL_LENGTH = 1024;
+/**
+* Serves the container's requests for the operation that holds the lock: part uploads for a
+* write grant, byte ranges for a read grant, and nothing else. The key comes from props, never
+* from the request.
+*/
+async function handleDirectoryBackupRequest(request, props, resolveBucket) {
+	if (props.protocolVersion !== 1) return text(500, "gateway protocol is incompatible");
+	switch (props.mode) {
+		case "write": return servePart(request, resolveBucket(props.binding), props.key, props.uploadId);
+		case "read": return serveRange(request, resolveBucket(props.binding), props.key);
+		default: return text(403, "no directory backup operation holds a grant");
+	}
+}
+/** `PUT /parts/<N>`: uploads one part of the granted multipart upload. */
+async function servePart(request, bucket, key, uploadId) {
+	const part = PART_PATH.exec(new URL(request.url).pathname);
+	if (request.method !== "PUT" || part === null) return text(403, "the grant allows only part uploads");
+	const length = Number(request.headers.get("content-length") ?? NaN);
+	if (!Number.isSafeInteger(length) || length <= 0 || request.body === null) return text(411, "a part needs a Content-Length");
+	try {
+		const { readable, writable } = new FixedLengthStream(length);
+		const upload = bucket.resumeMultipartUpload(key, uploadId);
+		const [uploaded] = await Promise.all([upload.uploadPart(Number(part[1]), readable), request.body.pipeTo(writable)]);
+		return Response.json({ etag: uploaded.etag });
+	} catch (error) {
+		return text(502, error instanceof Error ? error.message : "R2 rejected the part");
+	}
+}
+/** `GET /object` with `Range: bytes=a-b`: reads one range of the granted object. */
+async function serveRange(request, bucket, key) {
+	const range = RANGE.exec(request.headers.get("range") ?? "");
+	if (request.method !== "GET" || new URL(request.url).pathname !== "/object" || range === null) return text(403, "the grant allows only ranged reads of the backup");
+	const offset = Number(range[1]);
+	const last = Number(range[2]);
+	if (last < offset) return text(416, "invalid range");
+	try {
+		const object = await bucket.get(key, { range: {
+			offset,
+			length: last - offset + 1
+		} });
+		if (object === null) return text(404, "the backup object does not exist");
+		const end = Math.min(last, object.size - 1);
+		if (end < offset) return text(416, "the range starts past the end of the object");
+		return new Response(object.body, {
+			status: 206,
+			headers: { "content-range": `bytes ${offset}-${end}/${object.size}` }
+		});
+	} catch (error) {
+		return text(502, error instanceof Error ? error.message : "R2 rejected the range");
+	}
+}
+function text(status, detail) {
+	return new Response(detail.slice(0, MAX_DETAIL_LENGTH), { status });
+}
+//#endregion
+//#region src/directory-backups/directory-backup-gateway.ts
+/**
+* Moves directory backups between a container and an R2 bucket binding. Export it from the
+* Worker and pass `ctx.exports.DirectoryBackupGateway` to `DirectoryBackups`.
+*
+* The container reaches `fetch()` through the outbound intercept and can only use the grant
+* its current operation holds. The other methods are for the Durable Object alone.
+*/
+var DirectoryBackupGateway = class extends WorkerEntrypoint {
+	fetch(request) {
+		return handleDirectoryBackupRequest(request, this.ctx.props, this.#bucket);
+	}
+	async createUpload(name) {
+		const { bucket, key } = this.#control();
+		const options = { httpMetadata: { contentType: "application/zstd" } };
+		if (name !== void 0) options.customMetadata = { name };
+		return (await bucket.createMultipartUpload(key, options)).uploadId;
+	}
+	async completeUpload(uploadId, parts) {
+		const { bucket, key } = this.#control();
+		return (await bucket.resumeMultipartUpload(key, uploadId).complete(parts.map(({ partNumber, etag }) => ({
+			partNumber,
+			etag
+		})))).size;
+	}
+	async abortUpload(uploadId) {
+		const { bucket, key } = this.#control();
+		await bucket.resumeMultipartUpload(key, uploadId).abort();
+	}
+	async deleteObject() {
+		const { bucket, key } = this.#control();
+		await bucket.delete(key);
+	}
+	/** The bucket and key of a control call. Only the Durable Object holds control props. */
+	#control() {
+		const props = this.ctx.props;
+		if (props.protocolVersion !== 1 || props.mode !== "control") throw new Error("DirectoryBackupGateway control methods require control props");
+		return {
+			bucket: this.#bucket(props.binding),
+			key: props.key
+		};
+	}
+	#bucket = (binding) => {
+		const value = Object.getOwnPropertyDescriptor(this.env, binding)?.value;
+		if (value === void 0 || !bucketSchema.safeParse(value).success) throw new TypeError(`env.${binding} is not an R2 bucket binding`);
+		return value;
+	};
+};
+const bucketSchema = z.object({
+	get: z.function(),
+	delete: z.function(),
+	createMultipartUpload: z.function(),
+	resumeMultipartUpload: z.function()
+});
+//#endregion
+//#region src/shared/errors.ts
+const FILE_OPERATIONS = [
+	"readFile",
+	"writeFile",
+	"stat",
+	"lstat",
+	"readDirectory",
+	"mkdir",
+	"rename",
+	"remove",
+	"backup",
+	"restore"
+];
+const CANONICAL_ERRNO_NAMES = /* @__PURE__ */ new Map();
+for (const [name, value] of Object.entries(constants.errno)) if (name.startsWith("E") && !CANONICAL_ERRNO_NAMES.has(value)) CANONICAL_ERRNO_NAMES.set(value, name);
+for (const preferred of [
+	"EAGAIN",
+	"EDEADLK",
+	"EOPNOTSUPP"
+]) {
+	const value = constants.errno[preferred];
+	if (value !== void 0) CANONICAL_ERRNO_NAMES.set(value, preferred);
+}
+var FileError = class extends Error {
+	name = "SandboxFileError";
+	code;
+	operation;
+	path;
+	destination;
+	detail;
+	constructor(context, code, detail) {
+		const subject = context.destination === void 0 ? `'${context.path}'` : `'${context.path}' to '${context.destination}'`;
+		super(`${context.operation} ${subject}: ${detail}`);
+		this.code = code;
+		this.operation = context.operation;
+		this.path = context.path;
+		if (context.destination !== void 0) this.destination = context.destination;
+		this.detail = detail;
+	}
+};
+const SandboxFileError = { 
+/** Recognizes local and JSRPC-crossed SandboxFileError values. */
+is(cause) {
+	return cause instanceof Error && cause.name === "SandboxFileError" && hasOwn(cause, "code", isFileErrorCode) && hasOwn(cause, "operation", isFileOperation) && hasOwn(cause, "path", isString) && hasOptionalOwn(cause, "destination", isString) && hasOwn(cause, "detail", isString);
+} };
+var ProtocolError = class extends Error {
+	name = "SandboxProtocolError";
+	code = "SANDBOX_PROTOCOL_ERROR";
+	detail;
+	constructor(detail, cause) {
+		super(detail, cause === void 0 ? void 0 : { cause });
+		this.detail = detail;
+	}
+};
+const SandboxProtocolError = { 
+/** Recognizes local and JSRPC-crossed SandboxProtocolError values. */
+is(cause) {
+	return cause instanceof Error && cause.name === "SandboxProtocolError" && hasOwn(cause, "code", (value) => value === "SANDBOX_PROTOCOL_ERROR") && hasOwn(cause, "detail", isString);
+} };
+var S3MountError = class extends Error {
+	name = "SandboxS3MountError";
+	code;
+	operation;
+	path;
+	detail;
+	constructor(code, operation, path, detail) {
+		super(`${operation} '${path}': ${detail}`);
+		this.code = code;
+		this.operation = operation;
+		this.path = path;
+		this.detail = detail;
+	}
+};
+const SandboxS3MountError = { 
+/** Recognizes local and JSRPC-crossed SandboxS3MountError values. */
+is(cause) {
+	return cause instanceof Error && cause.name === "SandboxS3MountError" && hasOwn(cause, "code", isS3MountErrorCode) && hasOwn(cause, "operation", isS3MountOperation) && hasOwn(cause, "path", isString) && hasOwn(cause, "detail", isString);
+} };
+var BackupError = class extends Error {
+	name = "SandboxBackupError";
+	code;
+	operation;
+	path;
+	detail;
+	constructor(code, operation, path, detail) {
+		super(`${operation} '${path}': ${detail}`);
+		this.code = code;
+		this.operation = operation;
+		this.path = path;
+		this.detail = detail;
+	}
+};
+const SandboxBackupError = { 
+/** Recognizes local and JSRPC-crossed SandboxBackupError values. */
+is(cause) {
+	return cause instanceof Error && cause.name === "SandboxBackupError" && hasOwn(cause, "code", isBackupErrorCode) && hasOwn(cause, "operation", isBackupOperation) && hasOwn(cause, "path", isString) && hasOwn(cause, "detail", isString);
+} };
+function backupError(code, operation, path, detail) {
+	return new BackupError(code, operation, path, detail);
+}
+function protocolError(detail, cause) {
+	return new ProtocolError(detail, cause);
+}
+function s3MountError(code, operation, path, detail) {
+	return new S3MountError(code, operation, path, detail);
+}
+function fileErrorFromErrno(context, errno, detail) {
+	const code = CANONICAL_ERRNO_NAMES.get(errno) ?? "UNKNOWN";
+	return new FileError(context, code, detail.length > 0 ? detail : code);
+}
+function hasOwn(owner, key, predicate) {
+	const descriptor = Object.getOwnPropertyDescriptor(owner, key);
+	return descriptor !== void 0 && predicate(descriptor.value);
+}
+function hasOptionalOwn(owner, key, predicate) {
+	const descriptor = Object.getOwnPropertyDescriptor(owner, key);
+	return descriptor === void 0 || descriptor.value === void 0 || predicate(descriptor.value);
+}
+function isString(value) {
+	return typeof value === "string";
+}
+function isFileErrorCode(value) {
+	return isString(value) && (value === "UNKNOWN" || /^E[A-Z0-9]+$/.test(value));
+}
+function isFileOperation(value) {
+	return FILE_OPERATIONS.some((operation) => operation === value);
+}
+function isS3MountErrorCode(value) {
+	return value === "S3_MOUNT_CONFLICT" || value === "S3_MOUNT_BUSY" || value === "S3_MOUNT_FAILED" || value === "S3_MOUNT_INCOMPATIBLE";
+}
+function isBackupErrorCode(value) {
+	return value === "BACKUP_NOT_FOUND" || value === "BACKUP_INTEGRITY" || value === "BACKUP_TRANSFER";
+}
+function isBackupOperation(value) {
+	return value === "backup" || value === "restore" || value === "delete";
+}
+function isS3MountOperation(value) {
+	return value === "mount" || value === "inspect" || value === "unmount";
+}
+//#endregion
+//#region src/shared/options.ts
+const optionsSchema = z.object({});
+function validateOptions(options, rules) {
+	if (!optionsSchema.safeParse(options).success) throw new TypeError("options must be an object");
+	for (const [name, value] of Object.entries(options)) {
+		if (value === void 0) continue;
+		if (!Object.hasOwn(rules, name)) throw new TypeError(`unknown option "${name}"`);
+		const rule = rules[name];
+		if (!rule.schema.safeParse(value).success) throw new TypeError(`${name} ${rule.requirement}`);
+	}
+}
+//#endregion
+//#region src/directory-backups/contracts.ts
+/** The only archive format this version writes and reads. */
+const DIRECTORY_BACKUP_FORMAT = "tar+zstd/1";
+//#endregion
+//#region src/shared/shim.ts
+const SHIM_PATH = "/usr/local/bin/sandbox-shim";
+const MAGIC = new Uint8Array([
+	83,
+	66,
+	88,
+	70
+]);
+const PROTOCOL_VERSION = 1;
+const HEADER_LENGTH = 10;
+const ERROR_PREFIX_LENGTH = 4;
+const FRAME_SUCCESS = 0;
+const FRAME_FILE_ERROR = 1;
+const FRAME_DATA = 2;
+const jsonSchema = z.json();
+const jsonDecoder = new TextDecoder("utf-8", { fatal: true });
+var AbortMonitor = class {
+	/**
+	* The signal to pass to `exec()`, which follows the caller's until the shim settles. The
+	* caller's signal can outlive the call, as AbortSignal.timeout() does, and signalling an exited
+	* process logs a runtime error. Undefined when the process must not be signalled.
+	*/
+	signal;
+	#promise;
+	#dispose = () => void 0;
+	constructor(signal, abort) {
+		if (signal === void 0) return;
+		const linked = new AbortController();
+		if (abort === "kill") this.signal = linked.signal;
+		this.#promise = new Promise((_, reject) => {
+			if (signal.aborted) {
+				linked.abort(signal.reason);
+				reject(signal.reason);
+				return;
+			}
+			const onAbort = () => {
+				this.dispose();
+				linked.abort(signal.reason);
+				reject(signal.reason);
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+			this.#dispose = () => signal.removeEventListener("abort", onAbort);
+		});
+		this.#promise.catch(() => void 0);
+	}
+	waitFor(operation) {
+		if (this.#promise === void 0) return operation;
+		return Promise.race([this.#promise, operation]);
+	}
+	dispose() {
+		this.#dispose();
+		this.#dispose = () => void 0;
+	}
+};
+var ShimSession = class ShimSession {
+	process;
+	#abort;
+	#settled = false;
+	constructor(process, abort) {
+		this.process = process;
+		this.#abort = abort;
+	}
+	static async start(container, command, options, abort = "kill") {
+		const monitor = new AbortMonitor(options.signal, abort);
+		const starting = container.exec(command, {
+			...options,
+			signal: monitor.signal
+		});
+		try {
+			return new ShimSession(await monitor.waitFor(starting), monitor);
+		} catch (error) {
+			monitor.dispose();
+			if (abort === "stdin") starting.then(closeStdin$1, () => void 0);
+			throw error;
+		}
+	}
+	openStderrControl() {
+		if (this.process.stderr === null) throw protocolError("sandbox-shim did not provide stderr");
+		return new ShimControl(this.process.stderr.getReader(), this);
+	}
+	openStdoutControl() {
+		if (this.process.stdout === null) throw protocolError("sandbox-shim did not provide stdout");
+		return new ShimControl(this.process.stdout.getReader(), this);
+	}
+	openStdoutReader() {
+		if (this.process.stdout === null) throw protocolError("sandbox-shim did not provide stdout");
+		return this.process.stdout.getReader();
+	}
+	openStdinWriter() {
+		if (this.process.stdin === null) throw protocolError("sandbox-shim did not provide stdin");
+		return this.process.stdin.getWriter();
+	}
+	waitFor(operation) {
+		return this.#abort.waitFor(operation);
+	}
+	finish() {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#abort.dispose();
+	}
+	/**
+	* Waits for a shim that already reported its outcome to exit, so cleanup does not signal an
+	* exited process. Never throws: the reported outcome stays authoritative, and if the exit is
+	* not observed, terminate() still cleans up.
+	*/
+	async settle() {
+		try {
+			await this.waitFor(this.process.exitCode);
+			this.finish();
+		} catch {}
+	}
+	terminate() {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#abort.dispose();
+		try {
+			this.process.kill(9);
+		} catch {}
+	}
+};
+var ShimControl = class {
+	#reader;
+	#session;
+	#pending = /* @__PURE__ */ new Uint8Array();
+	constructor(reader, session) {
+		this.#reader = reader;
+		this.#session = session;
+	}
+	async readFrame() {
+		const header = await this.#readExactly(HEADER_LENGTH);
+		validateHeader(header);
+		const frameKind = header[5];
+		const payloadLength = new DataView(header.buffer, header.byteOffset + 6, 4).getUint32(0, true);
+		if (frameKind === FRAME_SUCCESS) {
+			if (payloadLength !== 0) throw protocolError("sandbox-shim returned invalid control data");
+			return { kind: "success" };
+		}
+		if (frameKind === FRAME_DATA) return {
+			kind: "data",
+			payload: await this.#readExactly(payloadLength)
+		};
+		if (frameKind !== FRAME_FILE_ERROR) throw protocolError(`sandbox-shim returned unknown control status ${frameKind}`);
+		if (payloadLength < ERROR_PREFIX_LENGTH) throw protocolError("sandbox-shim returned invalid control data");
+		if (payloadLength > 65540) throw protocolError("sandbox-shim error message exceeded its size limit");
+		const payload = await this.#readExactly(payloadLength);
+		const errno = new DataView(payload.buffer, payload.byteOffset, ERROR_PREFIX_LENGTH).getInt32(0, true);
+		if (errno <= 0) throw protocolError(`sandbox-shim returned invalid errno ${errno}`);
+		return {
+			kind: "fileError",
+			errno,
+			detail: decodeErrorDetail(payload.subarray(ERROR_PREFIX_LENGTH))
+		};
+	}
+	async expectEnd() {
+		if (!(this.#pending.length === 0 ? await this.#session.waitFor(this.#reader.read()) : {
+			done: false,
+			value: this.#pending
+		}).done) throw protocolError("sandbox-shim returned trailing control data");
+	}
+	discard(reason) {
+		this.#reader.cancel(reason).then(() => this.#reader.releaseLock(), () => this.#reader.releaseLock());
+	}
+	releaseLock() {
+		this.#reader.releaseLock();
+	}
+	async #readExactly(length) {
+		const result = new Uint8Array(length);
+		let offset = 0;
+		while (offset < length) {
+			if (this.#pending.length === 0) {
+				const next = await this.#session.waitFor(this.#reader.read());
+				if (next.done) throw protocolError("sandbox-shim returned truncated control data");
+				this.#pending = next.value;
+			}
+			const count = Math.min(length - offset, this.#pending.length);
+			result.set(this.#pending.subarray(0, count), offset);
+			this.#pending = this.#pending.subarray(count);
+			offset += count;
+		}
+		return result;
+	}
+};
+/** Decodes a data frame's payload as JSON, or throws a protocol error that says `invalid`. */
+function parseJsonPayload(payload, invalid) {
+	try {
+		const parsed = jsonSchema.safeParse(JSON.parse(jsonDecoder.decode(payload)));
+		if (parsed.success) return parsed.data;
+	} catch (cause) {
+		throw protocolError(invalid, cause);
+	}
+	throw protocolError(invalid);
+}
+function closeStdin$1(process) {
+	process.stdin?.close().catch(() => void 0);
+}
+function decodeErrorDetail(bytes) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch (cause) {
+		throw protocolError("sandbox-shim returned a non-UTF-8 error message", cause);
+	}
+}
+function validateHeader(header) {
+	for (let index = 0; index < MAGIC.length; index += 1) if (header[index] !== MAGIC[index]) throw protocolError("sandbox-shim returned invalid protocol magic");
+	if (header[4] !== PROTOCOL_VERSION) throw protocolError(`sandbox-shim protocol ${header[4]} is not supported`);
+}
+//#endregion
+//#region src/directory-backups/protocol.ts
+/** The one intercepted host every operation's grant is registered on. */
+const GATEWAY_HOST = "backups.sandbox.internal";
+const ACKNOWLEDGEMENT = new Uint8Array([1]);
+const messageSchema = z.object({ kind: z.string() });
+const errorSchema = z.object({
+	kind: z.literal("error"),
+	code: z.string(),
+	detail: z.string()
+});
+const lockedSchema = z.strictObject({ kind: z.literal("locked") });
+/**
+* Runs one `directory-backup` shim exchange: wait for the lock, register the grant, acknowledge,
+* wait for the result, then deny and close stdin, in that order on every path. The shim holds
+* the lock until stdin closes, so a later operation's grant can't be overwritten by this
+* operation's deny.
+*
+* An abort closes stdin rather than killing the shim, which then removes whatever it had
+* partly written, and rejects at once with the signal's reason.
+*/
+async function runShimExchange(container, exchange) {
+	const { signal } = exchange;
+	signal?.throwIfAborted();
+	const operation = exchange.command;
+	const session = await ShimSession.start(container, [
+		SHIM_PATH,
+		"directory-backup",
+		exchange.command,
+		JSON.stringify(exchange.request)
+	], {
+		stdin: "pipe",
+		stdout: "pipe",
+		stderr: "ignore",
+		signal
+	}, "stdin");
+	let control;
+	let input;
+	let granting;
+	let released = false;
+	const release = async () => {
+		if (released) return;
+		released = true;
+		if (granting !== void 0) {
+			await granting.catch(() => void 0);
+			await exchange.deny().catch(() => void 0);
+		}
+		if (input !== void 0) closeStdin(input);
+	};
+	try {
+		control = session.openStdoutControl();
+		input = session.openStdinWriter();
+		const locked = await readMessage(control, operation, exchange.path);
+		if (!lockedSchema.safeParse(locked).success) throw protocolError("sandbox-shim did not report that it holds the backup lock");
+		granting = exchange.grant();
+		await session.waitFor(granting);
+		await session.waitFor(input.write(ACKNOWLEDGEMENT));
+		const result = await readMessage(control, operation, exchange.path);
+		const done = exchange.done.safeParse(result);
+		if (!done.success) throw protocolError("sandbox-shim returned an invalid backup result");
+		await release();
+		await control.expectEnd();
+		const exitCode = await session.waitFor(session.process.exitCode);
+		if (exitCode !== 0) throw protocolError(`sandbox-shim exited with code ${exitCode}`);
+		control.releaseLock();
+		return done.data;
+	} catch (error) {
+		await release();
+		control?.discard(error);
+		throw error;
+	} finally {
+		session.finish();
+	}
+}
+async function readMessage(control, operation, path) {
+	const frame = await control.readFrame();
+	if (frame.kind === "fileError") throw fileErrorFromErrno({
+		operation: operation === "backup" ? "backup" : "restore",
+		path
+	}, frame.errno, frame.detail);
+	if (frame.kind !== "data") throw protocolError("sandbox-shim did not return backup data");
+	const value = parseJsonPayload(frame.payload, "sandbox-shim returned invalid backup data");
+	if (!messageSchema.safeParse(value).success) throw protocolError("sandbox-shim returned invalid backup data");
+	const failure = errorSchema.safeParse(value);
+	if (failure.success) throw shimFailure(failure.data.code, failure.data.detail, operation, path);
+	return value;
+}
+function shimFailure(code, detail, operation, path) {
+	switch (code) {
+		case "integrity": return backupError("BACKUP_INTEGRITY", operation, path, detail);
+		case "notFound": return backupError("BACKUP_NOT_FOUND", operation, path, detail);
+		case "transfer": return backupError("BACKUP_TRANSFER", operation, path, detail);
+		case "protocol": return protocolError(detail);
+		default: return protocolError(`sandbox-shim returned unknown backup error code "${code}"`);
+	}
+}
+function closeStdin(input) {
+	input.close().catch(() => void 0);
+}
+//#endregion
+//#region src/directory-backups/directory-backups.ts
+const absolutePath = z.string().check(z.startsWith("/"), z.refine((value) => !value.includes("\0")));
+const SIGNAL = {
+	schema: z.instanceof(AbortSignal),
+	requirement: "must be an AbortSignal"
+};
+const DIR = {
+	schema: absolutePath,
+	requirement: "must be an absolute path without NUL"
+};
+const BACKUP_OPTIONS = {
+	dir: DIR,
+	name: {
+		schema: z.string(),
+		requirement: "must be a string"
+	},
+	exclude: {
+		schema: z.array(z.string()),
+		requirement: "must be an array of strings"
+	},
+	gitignore: {
+		schema: z.boolean(),
+		requirement: "must be a boolean"
+	},
+	signal: SIGNAL
+};
+const RESTORE_OPTIONS = {
+	dir: DIR,
+	signal: SIGNAL
+};
+const DELETE_OPTIONS = { signal: SIGNAL };
+const sha256Schema = z.string().check(z.regex(/^[0-9a-f]{64}$/));
+const recordSchema = z.object({
+	id: z.string().check(z.regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/)),
+	dir: absolutePath,
+	size: z.number().check(z.refine((value) => Number.isSafeInteger(value) && value > 0)),
+	name: z.optional(z.string()),
+	sha256: sha256Schema,
+	format: z.literal(DIRECTORY_BACKUP_FORMAT)
+});
+const backupDoneSchema = z.strictObject({
+	kind: z.literal("done"),
+	size: z.number().check(z.refine((value) => Number.isSafeInteger(value) && value > 0)),
+	sha256: sha256Schema,
+	parts: z.array(z.strictObject({
+		partNumber: z.number().check(z.int(), z.positive()),
+		etag: z.string()
+	})).check(z.minLength(1))
+});
+const restoreDoneSchema = z.strictObject({ kind: z.literal("done") });
+/**
+* Saves one directory from the running Container to an R2 bucket, and restores it as
+* ordinary files into a Container, which may run a different image.
+*
+* One backup or restore runs at a time per Container; others wait their turn, so
+* `Promise.all()` over several directories works. Start the Container first: this class never
+* starts, retries, or times out anything. The application stores the returned records and
+* decides when to delete them.
+*/
+var DirectoryBackups = class {
+	#container;
+	#gateway;
+	#binding;
+	#prefix;
+	constructor(container, gateway, storage) {
+		if (!z.string().check(z.minLength(1)).safeParse(storage.binding).success) throw new TypeError("storage.binding must name an R2 bucket binding");
+		const prefix = storage.prefix ?? "";
+		if (!z.string().safeParse(prefix).success || prefix !== "" && !prefix.endsWith("/")) throw new TypeError("storage.prefix must be a string that ends in \"/\"");
+		this.#container = container;
+		this.#gateway = gateway;
+		this.#binding = storage.binding;
+		this.#prefix = prefix;
+	}
+	/**
+	* Backs up `dir` and returns its record. Pause writers in `dir` first: files that change
+	* while it's read are captured as they are at that moment.
+	*
+	* @throws {SandboxFileError} `dir` is missing or not a directory, a file can't be read, or an
+	*   exclude pattern is invalid (`EINVAL`).
+	* @throws {SandboxBackupError} `BACKUP_TRANSFER` when a part upload fails, or
+	*   `BACKUP_INTEGRITY` when R2 stored a different size than was uploaded.
+	*/
+	async backup(options) {
+		validateOptions(options, BACKUP_OPTIONS);
+		if (options.dir === void 0) throw new TypeError("dir must be an absolute path without NUL");
+		const { dir, name, signal } = options;
+		const id = crypto.randomUUID();
+		const control = this.#control(this.#key(id));
+		const { uploadId, done } = await this.#upload(control, this.#key(id), options);
+		let size;
+		try {
+			signal?.throwIfAborted();
+			size = await control.completeUpload(uploadId, done.parts);
+		} catch (error) {
+			await control.abortUpload(uploadId).catch(() => void 0);
+			throw error;
+		}
+		if (size !== done.size) {
+			await control.deleteObject().catch(() => void 0);
+			throw backupError("BACKUP_INTEGRITY", "backup", dir, `R2 stored ${size} bytes, but the container uploaded ${done.size}`);
+		}
+		const record = {
+			id,
+			dir,
+			size,
+			sha256: done.sha256,
+			format: DIRECTORY_BACKUP_FORMAT
+		};
+		return name === void 0 ? record : {
+			...record,
+			name
+		};
+	}
+	/**
+	* Replaces `options.dir`, or the record's `dir`, with the backup's contents. The directory is
+	* extracted beside the target and swapped in only after the download is verified, so a failed
+	* or aborted restore leaves the target as it was. The target's parent must exist; the target
+	* need not.
+	*
+	* @throws {SandboxFileError} The target's parent is missing (`ENOENT`), the target isn't a
+	*   directory (`ENOTDIR`) or is a mount point (`EBUSY`), the swap fails (for example `EXDEV`),
+	*   or the disk fills (`ENOSPC`).
+	* @throws {SandboxBackupError} `BACKUP_NOT_FOUND`, `BACKUP_INTEGRITY`, or `BACKUP_TRANSFER`.
+	*/
+	async restore(backup, options = {}) {
+		validateOptions(options, RESTORE_OPTIONS);
+		const record = parseRecord(backup);
+		const dir = options.dir ?? record.dir;
+		const key = this.#key(record.id);
+		await runShimExchange(this.#container, {
+			command: "restore",
+			request: {
+				gateway: GATEWAY_HOST,
+				dir,
+				size: record.size,
+				sha256: record.sha256
+			},
+			path: dir,
+			signal: options.signal,
+			done: restoreDoneSchema,
+			grant: () => this.#register({
+				protocolVersion: 1,
+				mode: "read",
+				binding: this.#binding,
+				key
+			}),
+			deny: () => this.#deny()
+		});
+	}
+	/**
+	* Deletes the backup's object. Needs no running Container. Deleting an object that is already
+	* gone succeeds. A restore reading it at the same time fails, and nothing is swapped.
+	*/
+	async delete(backup, options = {}) {
+		validateOptions(options, DELETE_OPTIONS);
+		const record = parseRecord(backup);
+		options.signal?.throwIfAborted();
+		await this.#control(this.#key(record.id)).deleteObject();
+	}
+	/**
+	* Runs the shim's backup into a new multipart upload, which its grant creates once the shim
+	* holds the lock. Aborts the upload if the backup fails.
+	*/
+	async #upload(control, key, options) {
+		const { dir } = options;
+		let uploadId;
+		try {
+			const done = await runShimExchange(this.#container, {
+				command: "backup",
+				request: {
+					gateway: GATEWAY_HOST,
+					dir,
+					exclude: [...options.exclude ?? []],
+					gitignore: options.gitignore ?? false
+				},
+				path: dir,
+				signal: options.signal,
+				done: backupDoneSchema,
+				grant: async () => {
+					uploadId = await control.createUpload(options.name);
+					await this.#register({
+						protocolVersion: 1,
+						mode: "write",
+						binding: this.#binding,
+						key,
+						uploadId
+					});
+				},
+				deny: () => this.#deny()
+			});
+			if (uploadId === void 0) throw new Error("the backup finished without an upload");
+			return {
+				uploadId,
+				done
+			};
+		} catch (error) {
+			if (uploadId !== void 0) await control.abortUpload(uploadId).catch(() => void 0);
+			throw error;
+		}
+	}
+	#key(id) {
+		return `${this.#prefix}${id}.tar.zst`;
+	}
+	#control(key) {
+		return this.#gateway({ props: {
+			protocolVersion: 1,
+			mode: "control",
+			binding: this.#binding,
+			key
+		} });
+	}
+	#register(props) {
+		return this.#container.interceptOutboundHttp(GATEWAY_HOST, this.#gateway({ props }));
+	}
+	#deny() {
+		return this.#register({
+			protocolVersion: 1,
+			mode: "deny"
+		});
+	}
+};
+function parseRecord(backup) {
+	const parsed = recordSchema.safeParse(backup);
+	if (!parsed.success) throw new TypeError(`backup must be a directory backup record in format "${DIRECTORY_BACKUP_FORMAT}"`);
+	return parsed.data;
+}
+//#endregion
+//#region src/files/command.ts
+/**
+* Starts the shim for one file command. A relative path is joined onto `cwd`, so the shim always
+* receives absolute paths and `exec()` never receives `cwd`: a missing `cwd` then fails the file
+* operation with `ENOENT` instead of failing to start the process. Only `user` and `signal`
+* reach `exec()`.
+*/
+function startFileCommand(container, command, stdio) {
+	const { cwd, user, signal } = command.options;
+	const execOptions = { ...stdio };
+	if (user !== void 0) execOptions.user = user;
+	if (signal !== void 0) execOptions.signal = signal;
+	const paths = command.paths.map((path) => resolvePath(path, cwd));
+	return ShimSession.start(container, [
+		SHIM_PATH,
+		command.name,
+		...paths,
+		...command.flags ?? []
+	], execOptions);
+}
+function resolvePath(path, cwd) {
+	return cwd === void 0 || path.startsWith("/") ? path : `${cwd}/${path}`;
+}
+async function runFileCommand(container, request) {
+	const session = await startFileCommand(container, request, {
+		stdout: "pipe",
+		stderr: "ignore"
+	});
+	let control;
+	try {
+		control = session.openStdoutControl();
+		const frame = await control.readFrame();
+		await control.expectEnd();
+		if (frame.kind === "fileError") {
+			await session.settle();
+			throw fileErrorFromErrno(request.error, frame.errno, frame.detail);
+		}
+		if (frame.kind !== request.expected) throw protocolError(request.expected === "data" ? "sandbox-shim did not return command data" : "sandbox-shim did not confirm command completion");
+		const exitCode = await session.waitFor(session.process.exitCode);
+		if (exitCode !== 0) throw protocolError(`sandbox-shim exited with code ${exitCode}`);
+		control.releaseLock();
+		session.finish();
+		return frame.kind === "data" ? frame.payload : void 0;
+	} catch (error) {
+		session.terminate();
+		control?.discard(error);
+		throw error;
+	}
+}
+//#endregion
+//#region src/files/content.ts
+function fileContentStream(content) {
+	if (content instanceof ReadableStream) return content;
+	if (content instanceof Blob) return content.stream();
+	let bytes;
+	if (typeof content === "string") bytes = new TextEncoder().encode(content);
+	else if (content instanceof ArrayBuffer) bytes = new Uint8Array(content);
+	else {
+		bytes = new Uint8Array(content.byteLength);
+		bytes.set(new Uint8Array(content.buffer, content.byteOffset, content.byteLength));
+	}
+	return new ReadableStream({ start(controller) {
+		controller.enqueue(bytes);
+		controller.close();
+	} });
+}
+//#endregion
+//#region src/files/file-type.ts
+function decodeFileType(value) {
+	switch (value) {
+		case 0: return "file";
+		case 1: return "directory";
+		case 2: return "symlink";
+		case 3: return "blockDevice";
+		case 4: return "characterDevice";
+		case 5: return "fifo";
+		case 6: return "socket";
+		default: throw protocolError("sandbox-shim returned an unknown file type");
+	}
+}
+//#endregion
+//#region src/files/read-directory.ts
+async function readDirectory(container, path, options) {
+	return decodeEntries(await runFileCommand(container, {
+		name: "read-directory",
+		paths: [path],
+		options,
+		error: {
+			operation: "readDirectory",
+			path
+		},
+		expected: "data"
+	}));
+}
+function decodeEntries(payload) {
+	const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+	let offset = 0;
+	const count = readUint32(view, offset);
+	offset += 4;
+	const entries = [];
+	for (let index = 0; index < count; index += 1) {
+		const type = decodeFileType(readByte(payload, offset));
+		offset += 1;
+		const nameLength = readUint16(view, offset);
+		offset += 2;
+		const name = decodeText(readBytes(payload, offset, nameLength));
+		offset += nameLength;
+		entries.push({
+			name,
+			type
+		});
+	}
+	if (offset !== payload.length) throw protocolError("sandbox-shim returned trailing directory data");
+	return entries;
+}
+function readByte(payload, offset) {
+	const value = payload[offset];
+	if (value === void 0) throw protocolError("sandbox-shim returned truncated directory data");
+	return value;
+}
+function readUint16(view, offset) {
+	if (offset + 2 > view.byteLength) throw protocolError("sandbox-shim returned truncated directory data");
+	return view.getUint16(offset, true);
+}
+function readUint32(view, offset) {
+	if (offset + 4 > view.byteLength) throw protocolError("sandbox-shim returned truncated directory data");
+	return view.getUint32(offset, true);
+}
+function readBytes(payload, offset, length) {
+	if (offset + length > payload.length) throw protocolError("sandbox-shim returned truncated directory data");
+	return payload.subarray(offset, offset + length);
+}
+function decodeText(bytes) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch (cause) {
+		throw protocolError("sandbox-shim returned invalid UTF-8 in directory entry name", cause);
+	}
+}
+//#endregion
+//#region src/files/read-file.ts
+async function readFile(container, path, options) {
+	const session = await startFileCommand(container, {
+		name: "read",
+		paths: [path],
+		options
+	}, {
+		stdout: "pipe",
+		stderr: "pipe"
+	});
+	let control;
+	let output;
+	try {
+		control = session.openStderrControl();
+		output = session.openStdoutReader();
+		const opening = await control.readFrame();
+		if (opening.kind === "fileError") {
+			await control.expectEnd();
+			await session.settle();
+			throw fileErrorFromErrno({
+				operation: "readFile",
+				path
+			}, opening.errno, opening.detail);
+		}
+		if (opening.kind !== "success") throw protocolError("sandbox-shim returned data before file bytes");
+		const terminal = readTerminalControl(control);
+		terminal.catch(() => void 0);
+		return new Response(responseBody(session, control, output, terminal, path));
+	} catch (error) {
+		terminateRead(session, control, output, error);
+		throw error;
+	}
+}
+function responseBody(session, control, output, terminalFrame, path) {
+	return new ReadableStream({
+		pull: async (controller) => {
+			try {
+				const next = await session.waitFor(output.read());
+				if (!next.done) {
+					controller.enqueue(next.value);
+					return;
+				}
+				const terminal = await session.waitFor(terminalFrame);
+				if (terminal.kind === "fileError") {
+					await session.settle();
+					throw fileErrorFromErrno({
+						operation: "readFile",
+						path
+					}, terminal.errno, terminal.detail);
+				}
+				if (terminal.kind !== "success") throw protocolError("sandbox-shim returned data after file bytes");
+				output.releaseLock();
+				control.releaseLock();
+				session.finish();
+				controller.close();
+			} catch (error) {
+				terminateRead(session, control, output, error);
+				controller.error(error);
+			}
+		},
+		cancel: (reason) => terminateRead(session, control, output, reason)
+	});
+}
+async function readTerminalControl(control) {
+	const frame = await control.readFrame();
+	await control.expectEnd();
+	return frame;
+}
+function terminateRead(session, control, output, reason) {
+	session.terminate();
+	control?.discard(reason);
+	if (output !== void 0) output.cancel(reason).then(() => output.releaseLock(), () => output.releaseLock());
+}
+//#endregion
+//#region src/files/stat-file.ts
+const STAT_PAYLOAD_LENGTH = 45;
+async function statFile(container, path, options, operation) {
+	const payload = await runFileCommand(container, {
+		name: operation,
+		paths: [path],
+		options,
+		error: {
+			operation,
+			path
+		},
+		expected: "data"
+	});
+	if (payload.length !== STAT_PAYLOAD_LENGTH) throw protocolError(`sandbox-shim returned invalid ${operation} data`);
+	const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+	return {
+		type: decodeFileType(payload[0]),
+		size: view.getBigUint64(1, true),
+		mode: view.getUint32(9, true),
+		uid: view.getUint32(13, true),
+		gid: view.getUint32(17, true),
+		accessedAt: decodeDate(view.getBigInt64(21, true)),
+		modifiedAt: decodeDate(view.getBigInt64(29, true)),
+		changedAt: decodeDate(view.getBigInt64(37, true))
+	};
+}
+function decodeDate(milliseconds) {
+	const value = Number(milliseconds);
+	if (!Number.isSafeInteger(value)) throw protocolError("sandbox-shim returned an out-of-range timestamp");
+	const date = new Date(value);
+	if (Number.isNaN(date.valueOf())) throw protocolError("sandbox-shim returned an out-of-range timestamp");
+	return date;
+}
+//#endregion
+//#region src/files/write-file.ts
+async function writeFile(container, path, source, options) {
+	let session;
+	let control;
+	let input;
+	let sourceReader;
+	try {
+		session = await startFileCommand(container, {
+			name: "write",
+			paths: [path],
+			options
+		}, {
+			stdin: "pipe",
+			stdout: "pipe",
+			stderr: "ignore"
+		});
+		control = session.openStdoutControl();
+		input = session.openStdinWriter();
+		const opening = await control.readFrame();
+		if (opening.kind === "fileError") {
+			await control.expectEnd();
+			await session.settle();
+		}
+		expectSuccess(opening, path);
+		sourceReader = source.getReader();
+		const pumping = pumpSource(session, sourceReader, input);
+		const terminal = terminalResult(session, control);
+		const first = await Promise.race([pumping, terminal]);
+		if (first.kind === "frame" || first.kind === "failure") {
+			handleTerminal(first, path);
+			handlePump(await pumping);
+		} else if (first.kind === "sourceFailure") throw first.error;
+		else if (first.kind === "inputFailure") {
+			const result = await terminal;
+			if (result.kind === "frame" && result.frame.kind === "fileError") expectSuccess(result.frame, path);
+			if (result.kind === "failure") throw result.error;
+			throw first.error;
+		} else handleTerminal(await terminal, path);
+		const exitCode = await session.waitFor(session.process.exitCode);
+		if (exitCode !== 0) throw protocolError(`sandbox-shim exited with code ${exitCode}`);
+		sourceReader.releaseLock();
+		input.releaseLock();
+		control.releaseLock();
+		session.finish();
+	} catch (error) {
+		session?.terminate();
+		if (input !== void 0) discardInput(input, error);
+		control?.discard(error);
+		if (sourceReader === void 0) source.cancel(error).catch(() => void 0);
+		else discardSource(sourceReader, error);
+		throw error;
+	}
+}
+async function pumpSource(session, source, input) {
+	while (true) {
+		try {
+			await session.waitFor(input.ready);
+		} catch (error) {
+			return {
+				kind: "inputFailure",
+				error
+			};
+		}
+		let next;
+		try {
+			next = await session.waitFor(source.read());
+		} catch (error) {
+			return {
+				kind: "sourceFailure",
+				error
+			};
+		}
+		if (next.done) try {
+			await session.waitFor(input.close());
+			return { kind: "complete" };
+		} catch (error) {
+			return {
+				kind: "inputFailure",
+				error
+			};
+		}
+		if (!(next.value instanceof Uint8Array)) return {
+			kind: "sourceFailure",
+			error: /* @__PURE__ */ new TypeError("writeFile stream chunks must be Uint8Array values")
+		};
+		try {
+			await session.waitFor(input.write(next.value));
+		} catch (error) {
+			return {
+				kind: "inputFailure",
+				error
+			};
+		}
+	}
+}
+async function terminalResult(session, control) {
+	try {
+		const frame = await control.readFrame();
+		await control.expectEnd();
+		if (frame.kind === "fileError") await session.settle();
+		return {
+			kind: "frame",
+			frame
+		};
+	} catch (error) {
+		return {
+			kind: "failure",
+			error
+		};
+	}
+}
+function handleTerminal(result, path) {
+	if (result.kind === "failure") throw result.error;
+	expectSuccess(result.frame, path);
+}
+function handlePump(result) {
+	if (result.kind !== "complete") throw result.error;
+}
+function expectSuccess(frame, path) {
+	if (frame.kind === "fileError") throw fileErrorFromErrno({
+		operation: "writeFile",
+		path
+	}, frame.errno, frame.detail);
+	if (frame.kind !== "success") throw protocolError("sandbox-shim returned data while writing a file");
+}
+function discardInput(input, reason) {
+	input.abort(reason).then(() => input.releaseLock(), () => input.releaseLock());
+}
+function discardSource(source, reason) {
+	source.cancel(reason).then(() => source.releaseLock(), () => source.releaseLock());
+}
+//#endregion
+//#region src/files/files.ts
+const FLAG = {
+	schema: z.boolean(),
+	requirement: "must be a boolean"
+};
+const FILE_OPTIONS = {
+	cwd: {
+		schema: z.string().check(z.startsWith("/")),
+		requirement: "must be an absolute path"
+	},
+	user: {
+		schema: z.string().check(z.regex(/^[0-9]+:[0-9]+$/)),
+		requirement: "must be numeric user and group IDs, as \"uid:gid\""
+	},
+	signal: {
+		schema: z.instanceof(AbortSignal),
+		requirement: "must be an AbortSignal"
+	}
+};
+const MKDIR_OPTIONS = {
+	...FILE_OPTIONS,
+	recursive: FLAG
+};
+const REMOVE_OPTIONS = {
+	...FILE_OPTIONS,
+	recursive: FLAG,
+	force: FLAG
+};
+/**
+* Structured file operations for a sandbox workspace.
+*
+* Operations run against the current native container execution. Its image must provide the matching shim at
+* `/usr/local/bin/sandbox-shim`.
+*/
+var Files = class {
+	#container;
+	constructor(container) {
+		this.#container = container;
+	}
+	/**
+	* Streams bytes from a path in the running container using native Linux file semantics.
+	*
+	* Native container, transport, and abort failures propagate unchanged.
+	*
+	* @param path - Absolute path, or a relative path when `options.cwd` is provided.
+	* @param options - Native execution options relevant to opening the file.
+	* @returns A binary response whose body applies backpressure to the container process. A
+	*   file-streaming or native transport failure can surface while the body is consumed.
+	* @throws {TypeError} The path is empty, contains NUL, or is relative without `cwd`, or an
+	*   option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure before returning the
+	*   response. A late file-streaming failure errors the response body with the same error type.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async readFile(path, options = {}) {
+		validateOptions(options, FILE_OPTIONS);
+		validatePath(path, options.cwd);
+		return readFile(this.#container, path, options);
+	}
+	/**
+	* Creates or truncates a file and streams content into it using native Linux semantics.
+	*
+	* The destination is opened before a caller-provided stream is consumed. Failures after that
+	* point can leave a created, truncated, or partially written file. Native container, transport,
+	* source-stream, and abort failures propagate unchanged.
+	*
+	* @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+	*   or an option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async writeFile(path, content, options = {}) {
+		validateOptions(options, FILE_OPTIONS);
+		validatePath(path, options.cwd);
+		await writeFile(this.#container, path, fileContentStream(content), options);
+	}
+	/**
+	* Returns metadata for a path using native Linux filesystem semantics.
+	*
+	* Native container, transport, and abort failures propagate unchanged.
+	*
+	* @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+	*   or an option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async stat(path, options = {}) {
+		validateOptions(options, FILE_OPTIONS);
+		validatePath(path, options.cwd);
+		return statFile(this.#container, path, options, "stat");
+	}
+	/**
+	* Returns metadata for a path without following its final symlink.
+	*
+	* Native container, transport, and abort failures propagate unchanged.
+	*
+	* @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+	*   or an option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async lstat(path, options = {}) {
+		validateOptions(options, FILE_OPTIONS);
+		validatePath(path, options.cwd);
+		return statFile(this.#container, path, options, "lstat");
+	}
+	/**
+	* Returns the immediate entries from a directory in native enumeration order.
+	*
+	* The directory path may resolve through a symlink, but entry types describe the entries
+	* themselves and do not follow symlinks. The operation does not recurse or retrieve metadata
+	* for each child.
+	* Native container, transport, and abort failures propagate unchanged.
+	*
+	* @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+	*   or an option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async readDirectory(path, options = {}) {
+		validateOptions(options, FILE_OPTIONS);
+		validatePath(path, options.cwd);
+		return readDirectory(this.#container, path, options);
+	}
+	/**
+	* Creates a directory using native Linux filesystem semantics.
+	*
+	* By default only the final directory is created. With `recursive`, missing parents are
+	* created and an existing target directory is accepted. Partial parent creation can remain
+	* after failure or cancellation.
+	* Native container, transport, and abort failures propagate unchanged.
+	*
+	* @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+	*   or an option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async mkdir(path, options = {}) {
+		validateOptions(options, MKDIR_OPTIONS);
+		validatePath(path, options.cwd);
+		await runFileCommand(this.#container, {
+			name: "mkdir",
+			paths: [path],
+			flags: options.recursive ? ["--recursive"] : [],
+			options,
+			error: {
+				operation: "mkdir",
+				path
+			},
+			expected: "success"
+		});
+	}
+	/**
+	* Renames a file, directory, or symlink using native Linux filesystem semantics.
+	*
+	* Existing destinations are replaced when Linux permits it. Cross-filesystem renames fail
+	* with `EXDEV`; no copy-and-remove fallback is attempted.
+	* Native container, transport, and abort failures propagate unchanged.
+	*
+	* @throws {TypeError} A path is empty, contains NUL, or is relative without an absolute `cwd`,
+	*   or an option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async rename(source, destination, options = {}) {
+		validateOptions(options, FILE_OPTIONS);
+		validatePath(source, options.cwd);
+		validatePath(destination, options.cwd);
+		await runFileCommand(this.#container, {
+			name: "rename",
+			paths: [source, destination],
+			options,
+			error: {
+				operation: "rename",
+				path: source,
+				destination
+			},
+			expected: "success"
+		});
+	}
+	/**
+	* Removes a file or symlink using native Linux filesystem semantics.
+	*
+	* Directories are rejected unless `recursive` is set. Recursive removal does not follow
+	* symlinks and can leave partial effects after failure or cancellation. `force` ignores only
+	* a missing target. Native container, transport, and abort failures propagate unchanged.
+	*
+	* @throws {TypeError} The path is empty, contains NUL, or is relative without an absolute `cwd`,
+	*   or an option is unknown or invalid.
+	* @throws {SandboxFileError} The container reports a filesystem failure.
+	* @throws {SandboxProtocolError} The package and `sandbox-shim` cannot complete their protocol.
+	*/
+	async remove(path, options = {}) {
+		validateOptions(options, REMOVE_OPTIONS);
+		validatePath(path, options.cwd);
+		const flags = [];
+		if (options.recursive) flags.push("--recursive");
+		if (options.force) flags.push("--force");
+		await runFileCommand(this.#container, {
+			name: "remove",
+			paths: [path],
+			flags,
+			options,
+			error: {
+				operation: "remove",
+				path
+			},
+			expected: "success"
+		});
+	}
+};
+function validatePath(path, cwd) {
+	if (typeof path !== "string") throw new TypeError("path must be a string");
+	if (path.length === 0) throw new TypeError("path must not be empty");
+	if (path.includes("\0")) throw new TypeError("path cannot contain NUL characters");
+	if (!path.startsWith("/") && cwd === void 0) throw new TypeError("cwd is required when path is relative");
+}
+//#endregion
+//#region src/shared/bounded-body.ts
+async function readBoundedBody(body, limit, cancelReason) {
+	if (body === null) return { status: "absent" };
+	const reader = body.getReader();
+	const chunks = [];
+	let length = 0;
+	try {
+		while (true) {
+			const result = await reader.read();
+			if (result.done) break;
+			length += result.value.byteLength;
+			if (length > limit) {
+				await reader.cancel(cancelReason);
+				return { status: "exceeded" };
+			}
+			chunks.push(result.value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const bytes = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return {
+		status: "complete",
+		bytes
+	};
+}
+//#endregion
+//#region src/s3-mounts/credentials.ts
+const CREDENTIAL_PROVIDER_URL = "https://credentials.sandbox.internal/";
+const MAX_CREDENTIAL_RESPONSE_BYTES = 16384;
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const credentialResponseSchema = z.strictObject({
+	accessKeyId: z.string().check(z.minLength(1), z.regex(/^[^\0]+$/)),
+	secretAccessKey: z.string().check(z.minLength(1), z.regex(/^[^\0]+$/)),
+	sessionToken: z.optional(z.string().check(z.minLength(1), z.regex(/^[^\0]+$/))),
+	expiresAt: z.number().check(z.int())
+});
+var CredentialProviderError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "CredentialProviderError";
+	}
+};
+async function resolveS3Credentials(credentials, signal) {
+	if (credentials.type === "static") return credentials;
+	signal.throwIfAborted();
+	let response;
+	try {
+		response = await credentials.fetcher.fetch(CREDENTIAL_PROVIDER_URL, {
+			headers: { accept: "application/json" },
+			signal
+		});
+	} catch (error) {
+		if (signal.aborted) throw signal.reason;
+		throw new CredentialProviderError("credential provider request failed", { cause: error });
+	}
+	if (!response.ok) throw new CredentialProviderError(`credential provider returned HTTP ${response.status}`);
+	const credentialsResponse = await readCredentialResponse(response.body);
+	if (credentialsResponse.expiresAt <= Date.now()) throw new CredentialProviderError("credential provider returned invalid or expired credentials");
+	return {
+		accessKeyId: credentialsResponse.accessKeyId,
+		secretAccessKey: credentialsResponse.secretAccessKey,
+		sessionToken: credentialsResponse.sessionToken
+	};
+}
+async function readCredentialResponse(body) {
+	const result = await readBoundedBody(body, MAX_CREDENTIAL_RESPONSE_BYTES, "credential provider response exceeded the gateway limit");
+	if (result.status === "absent") throw new CredentialProviderError("credential provider returned invalid JSON");
+	if (result.status === "exceeded") throw new CredentialProviderError("credential provider response is too large");
+	try {
+		const parsed = credentialResponseSchema.safeParse(JSON.parse(decoder.decode(result.bytes)));
+		if (!parsed.success) throw new CredentialProviderError("credential provider returned invalid or expired credentials");
+		return parsed.data;
+	} catch (error) {
+		if (error instanceof CredentialProviderError) throw error;
+		throw new CredentialProviderError("credential provider returned invalid JSON", { cause: error });
+	}
+}
+//#endregion
+//#region src/s3-mounts/route.ts
+function routeHost(routeId) {
+	return `s3-${routeId}.sandbox.internal`;
+}
+//#endregion
+//#region src/s3-mounts/gateway-policy.ts
+const LIST_V1_PARAMETERS = /* @__PURE__ */ new Set([
+	"delimiter",
+	"encoding-type",
+	"marker",
+	"max-keys",
+	"prefix"
+]);
+const LIST_V2_PARAMETERS = /* @__PURE__ */ new Set([
+	"continuation-token",
+	"delimiter",
+	"encoding-type",
+	"fetch-owner",
+	"list-type",
+	"max-keys",
+	"prefix",
+	"start-after"
+]);
+const SUPPORTED_AMZ_HEADERS = /* @__PURE__ */ new Set([
+	"authorization",
+	"x-amz-content-sha256",
+	"x-amz-copy-source",
+	"x-amz-copy-source-if-match",
+	"x-amz-copy-source-if-modified-since",
+	"x-amz-copy-source-if-none-match",
+	"x-amz-copy-source-if-unmodified-since",
+	"x-amz-copy-source-range",
+	"x-amz-date",
+	"x-amz-metadata-directive",
+	"x-amz-security-token"
+]);
+const COPY_CONTROL_HEADERS = [
+	"x-amz-copy-source-if-match",
+	"x-amz-copy-source-if-modified-since",
+	"x-amz-copy-source-if-none-match",
+	"x-amz-copy-source-if-unmodified-since",
+	"x-amz-copy-source-range"
+];
+async function authorizeS3Request(request, props) {
+	const url = new URL(request.url);
+	if (url.hostname !== routeHost(props.routeId)) return { detail: "request host does not match the mount route" };
+	if (usesAwsChunkedPayload(request.headers)) return { detail: "aws-chunked payloads are not supported" };
+	const unsupportedHeader = unsupportedAmzHeader(request.headers);
+	if (unsupportedHeader !== void 0) return { detail: `S3 header ${unsupportedHeader} is not permitted for this mount` };
+	const target = parseTarget(url.pathname);
+	if (target === void 0 || target.bucket !== props.source.bucket) return { detail: "request is outside the mounted bucket" };
+	const operation = classifyS3fsOperation(request.method.toUpperCase(), target.key, url);
+	if (operation === void 0) return { detail: "request is not a supported s3fs operation" };
+	if (props.access === "read-only" && operation.mutation) return { detail: "the mount is read-only" };
+	if (operation.kind === "object") {
+		if (!isObjectWithinPrefix(target.key, props.keyPrefix)) return { detail: "request is outside the mounted key prefix" };
+	} else if (operation.kind === "list" && !isListWithinPrefix(operation.prefix, props.keyPrefix)) return { detail: "list request is outside the mounted key prefix" };
+	const copySource = request.headers.get("x-amz-copy-source");
+	if (copySource === null && COPY_CONTROL_HEADERS.some((name) => request.headers.has(name))) return { detail: "copy controls require a copy source" };
+	if (copySource !== null) {
+		if (operation.kind !== "object" || request.method.toUpperCase() !== "PUT") return { detail: "copy source is not valid for this operation" };
+		if (!isScopedCopySource(copySource, props)) return { detail: "copy source is outside the mounted bucket or key prefix" };
+	}
+	const metadataDirective = request.headers.get("x-amz-metadata-directive");
+	if (metadataDirective !== null && (copySource === null || metadataDirective !== "COPY" && metadataDirective !== "REPLACE")) return { detail: "invalid copy metadata directive" };
+	if (hasMetadataHeader(request.headers) && (operation.kind !== "object" || request.method.toUpperCase() !== "PUT" && request.method.toUpperCase() !== "POST")) return { detail: "object metadata is not valid for this operation" };
+	return {
+		inspection: isInspectionRequest(request, operation, props),
+		upstreamUrl: upstreamUrl(url, props.source.endpoint)
+	};
+}
+function unsupportedAmzHeader(headers) {
+	for (const [name] of headers) {
+		const lowerName = name.toLowerCase();
+		if (lowerName.startsWith("x-amz-") && !lowerName.startsWith("x-amz-meta-") && !SUPPORTED_AMZ_HEADERS.has(lowerName)) return lowerName;
+	}
+}
+function hasMetadataHeader(headers) {
+	for (const [name] of headers) if (name.toLowerCase().startsWith("x-amz-meta-")) return true;
+	return false;
+}
+function isAuthorizedS3Request(authorization) {
+	return "upstreamUrl" in authorization;
+}
+function classifyS3fsOperation(method, key, url) {
+	if (hasDuplicateParameters(url.searchParams)) return void 0;
+	if (key === "") return classifyBucketOperation(method, url.searchParams);
+	return classifyObjectOperation(method, url.searchParams);
+}
+function classifyBucketOperation(method, parameters) {
+	if (method === "HEAD" && parameters.size === 0) return {
+		kind: "bucket",
+		mutation: false
+	};
+	if (method !== "GET") return void 0;
+	if (hasExactEmptyParameters(parameters, ["location"])) return {
+		kind: "bucket",
+		mutation: false
+	};
+	return classifyListOperation(parameters);
+}
+function classifyListOperation(parameters) {
+	const listType = parameters.get("list-type");
+	if (listType === "2") {
+		if (!hasOnlyAllowedParameters(parameters, LIST_V2_PARAMETERS)) return void 0;
+		if (!hasValidListParameters(parameters, 2)) return void 0;
+		return {
+			kind: "list",
+			mutation: false,
+			prefix: parameters.get("prefix") ?? void 0,
+			version: 2
+		};
+	}
+	if (listType !== null || !hasOnlyAllowedParameters(parameters, LIST_V1_PARAMETERS)) return;
+	if (!hasValidListParameters(parameters, 1)) return void 0;
+	return {
+		kind: "list",
+		mutation: false,
+		prefix: parameters.get("prefix") ?? void 0,
+		version: 1
+	};
+}
+function classifyObjectOperation(method, parameters) {
+	if (parameters.size === 0) {
+		if (method === "GET" || method === "HEAD") return {
+			kind: "object",
+			mutation: false
+		};
+		if (method === "PUT" || method === "DELETE") return {
+			kind: "object",
+			mutation: true
+		};
+		return;
+	}
+	if (method === "POST" && hasExactEmptyParameters(parameters, ["uploads"])) return {
+		kind: "object",
+		mutation: true
+	};
+	if (method === "PUT" && hasExactParameters(parameters, ["partNumber", "uploadId"]) && isIntegerInRange(parameters.get("partNumber"), 1, 1e4) && isNonEmpty(parameters.get("uploadId"))) return {
+		kind: "object",
+		mutation: true
+	};
+	if ((method === "POST" || method === "DELETE") && hasExactParameters(parameters, ["uploadId"]) && isNonEmpty(parameters.get("uploadId"))) return {
+		kind: "object",
+		mutation: true
+	};
+}
+function hasValidListParameters(parameters, version) {
+	const maxKeys = parameters.get("max-keys");
+	if (maxKeys !== null && !isIntegerInRange(maxKeys, 0, 1e3)) return false;
+	const encodingType = parameters.get("encoding-type");
+	if (encodingType !== null && encodingType !== "url") return false;
+	if (version === 2) {
+		const fetchOwner = parameters.get("fetch-owner");
+		if (fetchOwner !== null && fetchOwner !== "true" && fetchOwner !== "false") return false;
+		if (parameters.has("continuation-token") && parameters.has("start-after")) return false;
+		if (parameters.has("continuation-token") && !isNonEmpty(parameters.get("continuation-token"))) return false;
+	}
+	return true;
+}
+function parseTarget(pathname) {
+	if (!pathname.startsWith("/")) return void 0;
+	const separator = pathname.indexOf("/", 1);
+	const encodedBucket = separator === -1 ? pathname.slice(1) : pathname.slice(1, separator);
+	if (encodedBucket === "") return void 0;
+	const encodedKey = separator === -1 ? "" : pathname.slice(separator + 1);
+	try {
+		return {
+			bucket: decodeURIComponent(encodedBucket),
+			key: decodeURIComponent(encodedKey)
+		};
+	} catch {
+		return;
+	}
+}
+function isObjectWithinPrefix(key, prefix) {
+	if (prefix === void 0) return true;
+	return key === prefix.slice(0, -1) || key.startsWith(prefix);
+}
+function isListWithinPrefix(value, prefix) {
+	if (prefix === void 0) return true;
+	return value !== void 0 && (value === prefix || value.startsWith(prefix));
+}
+function hasDuplicateParameters(parameters) {
+	const names = /* @__PURE__ */ new Set();
+	for (const name of parameters.keys()) {
+		if (names.has(name)) return true;
+		names.add(name);
+	}
+	return false;
+}
+function hasOnlyAllowedParameters(parameters, allowed) {
+	for (const name of parameters.keys()) if (!allowed.has(name)) return false;
+	return true;
+}
+function hasExactParameters(parameters, expected) {
+	if (parameters.size !== expected.length) return false;
+	return expected.every((name) => parameters.has(name));
+}
+function hasExactEmptyParameters(parameters, expected) {
+	return hasExactParameters(parameters, expected) && expected.every((name) => parameters.get(name) === "");
+}
+function isIntegerInRange(value, minimum, maximum) {
+	if (value === null) return false;
+	if (!/^(?:0|[1-9][0-9]*)$/.test(value)) return false;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum;
+}
+function isNonEmpty(value) {
+	return value !== null && value !== "";
+}
+function isScopedCopySource(value, props) {
+	if (value === "" || value.includes("?")) return false;
+	let decodedPath;
+	try {
+		decodedPath = decodeURIComponent(value);
+	} catch {
+		return false;
+	}
+	const path = decodedPath.startsWith("/") ? decodedPath.slice(1) : decodedPath;
+	const separator = path.indexOf("/");
+	if (separator <= 0 || separator === path.length - 1) return false;
+	const key = path.slice(separator + 1);
+	return path.slice(0, separator) === props.source.bucket && isObjectWithinPrefix(key, props.keyPrefix);
+}
+function isInspectionRequest(request, operation, props) {
+	if (operation.kind !== "list" || operation.version !== 2 || request.headers.get("user-agent") !== "sandbox-shim/1") return false;
+	return new URL(request.url).searchParams.get("max-keys") === "1" && operation.prefix === props.keyPrefix;
+}
+function upstreamUrl(url, endpoint) {
+	const upstream = new URL(endpoint);
+	upstream.pathname = url.pathname;
+	upstream.search = url.search;
+	return upstream.toString();
+}
+function usesAwsChunkedPayload(headers) {
+	if (headers.get("x-amz-content-sha256")?.startsWith("STREAMING-") === true) return true;
+	return (headers.get("content-encoding") ?? "").split(",").some((encoding) => encoding.trim().toLowerCase() === "aws-chunked");
+}
+//#endregion
+//#region src/s3-mounts/gateway.ts
+const INSPECTION_VERSION_HEADER = "x-sandbox-s3-gateway-version";
+const INSPECTION_RESULT_HEADER = "x-sandbox-s3-inspection-result";
+const INSPECTION_DETAIL_HEADER = "x-sandbox-s3-inspection-detail";
+const MAX_INSPECTION_DETAIL_LENGTH = 1024;
+const MAX_S3_ERROR_BODY_BYTES = 65536;
+const FORWARDED_HEADERS = /* @__PURE__ */ new Set([
+	"content-length",
+	"content-md5",
+	"content-type",
+	"if-match",
+	"if-modified-since",
+	"if-none-match",
+	"if-unmodified-since",
+	"range",
+	"x-amz-copy-source",
+	"x-amz-copy-source-if-match",
+	"x-amz-copy-source-if-modified-since",
+	"x-amz-copy-source-if-none-match",
+	"x-amz-copy-source-if-unmodified-since",
+	"x-amz-copy-source-range",
+	"x-amz-metadata-directive"
+]);
+async function handleS3GatewayRequest(request, props) {
+	if (props.protocolVersion !== 1) return inspectionResponse("gateway-protocol", "gateway protocol is incompatible", 500);
+	if (props.mode === "deny") return inspectionResponse("rejected-access", "mount route has been revoked", 403);
+	const authorization = await authorizeS3Request(request, props);
+	if (!isAuthorizedS3Request(authorization)) return inspectionResponse("rejected-access", authorization.detail, 403);
+	let credentials;
+	try {
+		credentials = await resolveS3Credentials(props.source.credentials, request.signal);
+	} catch (error) {
+		if (request.signal.aborted) throw request.signal.reason;
+		return inspectionResponse("gateway-credential-provider", error instanceof CredentialProviderError ? error.message : "credential provider failed", 503);
+	}
+	const client = new AwsClient({
+		accessKeyId: credentials.accessKeyId,
+		secretAccessKey: credentials.secretAccessKey,
+		sessionToken: credentials.sessionToken,
+		service: "s3",
+		region: props.source.region,
+		retries: 0
+	});
+	let upstream;
+	try {
+		upstream = await client.fetch(authorization.upstreamUrl, {
+			method: request.method,
+			headers: forwardingHeaders(request.headers),
+			body: request.body,
+			signal: request.signal
+		});
+	} catch (error) {
+		if (!authorization.inspection) throw error;
+		return inspectionResponse("unavailable", error instanceof Error ? error.message : "upstream request failed", 503);
+	}
+	if (!authorization.inspection) return upstream;
+	return classifyInspectionResponse(upstream);
+}
+function forwardingHeaders(incoming) {
+	const headers = new Headers();
+	for (const [name, value] of incoming) {
+		const lowerName = name.toLowerCase();
+		if (lowerName === "x-amz-content-sha256") {
+			if (isPayloadHash(value)) headers.set(name, value);
+			continue;
+		}
+		if (FORWARDED_HEADERS.has(lowerName) || lowerName.startsWith("x-amz-meta-")) headers.set(name, value);
+	}
+	if (!headers.has("x-amz-content-sha256")) headers.set("x-amz-content-sha256", "UNSIGNED-PAYLOAD");
+	return headers;
+}
+function isPayloadHash(value) {
+	return value === "UNSIGNED-PAYLOAD" || /^[a-fA-F0-9]{64}$/.test(value);
+}
+async function classifyInspectionResponse(response) {
+	if (response.ok) return inspectionResponse("usable", "upstream list request succeeded", response.status);
+	if (response.status === 401) return inspectionResponse("rejected-credentials", `upstream rejected credentials with HTTP ${response.status}`, response.status);
+	if (response.status === 403) {
+		const code = await readS3ErrorCode(response.body);
+		return inspectionResponse(code !== void 0 && CREDENTIAL_ERROR_CODES.has(code) ? "rejected-credentials" : "rejected-access", code === void 0 ? "upstream denied the inspection request" : `upstream denied the inspection request with ${code}`, response.status);
+	}
+	if (response.status === 404) return inspectionResponse("rejected-not-found", "upstream bucket was not found", response.status);
+	if (response.status === 429 || response.status >= 500) return inspectionResponse("unavailable", `upstream returned HTTP ${response.status}`, response.status);
+	return inspectionResponse("rejected-other", `upstream rejected the request with HTTP ${response.status}`, response.status);
+}
+const CREDENTIAL_ERROR_CODES = /* @__PURE__ */ new Set([
+	"AuthorizationHeaderMalformed",
+	"ExpiredToken",
+	"InvalidAccessKeyId",
+	"InvalidToken",
+	"RequestTimeTooSkewed",
+	"SignatureDoesNotMatch",
+	"TokenRefreshRequired"
+]);
+async function readS3ErrorCode(body) {
+	const result = await readBoundedBody(body, MAX_S3_ERROR_BODY_BYTES, "S3 error body exceeded the inspection limit");
+	if (result.status !== "complete") return void 0;
+	return /<Code>([A-Za-z0-9]+)<\/Code>/.exec(new TextDecoder().decode(result.bytes))?.[1];
+}
+function inspectionResponse(result, detail, status) {
+	const boundedDetail = detail.slice(0, MAX_INSPECTION_DETAIL_LENGTH);
+	return new Response(null, {
+		status,
+		headers: {
+			[INSPECTION_VERSION_HEADER]: "1",
+			[INSPECTION_RESULT_HEADER]: result,
+			[INSPECTION_DETAIL_HEADER]: encodeURIComponent(boundedDetail)
+		}
+	});
+}
+//#endregion
+//#region src/s3-mounts/s3-gateway.ts
+var S3Gateway = class extends WorkerEntrypoint {
+	fetch(request) {
+		return handleS3GatewayRequest(request, this.ctx.props);
+	}
+};
+//#endregion
+//#region src/s3-mounts/request.ts
+const objectSchema = z.object({});
+const stringSchema = z.string();
+const fetcherSchema = z.object({ fetch: z.function() });
+const finiteNumberSchema = z.number().check(z.refine(Number.isFinite));
+const RESERVED_GUEST_PATHS = [
+	"/proc/self/mountinfo",
+	"/run/sandbox/s3-mounts",
+	"/usr/local/bin/sandbox-shim"
+];
+const RESERVED_S3FS_OPTIONS = /* @__PURE__ */ new Set([
+	"ahbe_conf",
+	"allow_other",
+	"compat_dir",
+	"credlib",
+	"ecs",
+	"endpoint",
+	"f",
+	"fg",
+	"foreground",
+	"fsname",
+	"host",
+	"iam_role",
+	"ibm_iam_auth",
+	"logfile",
+	"nomixupload",
+	"noproxy",
+	"passwd_file",
+	"profile",
+	"proxy",
+	"proxy_cred_file",
+	"public_bucket",
+	"ro",
+	"rw",
+	"subtype",
+	"use_path_request_style",
+	"use_proxy",
+	"use_session_token",
+	"url"
+]);
+function canonicalizeS3MountRequest(request) {
+	if (!objectSchema.safeParse(request).success) throw new TypeError("request must be an object");
+	const mountPath = canonicalizeMountPath(request.mountPath);
+	if (RESERVED_GUEST_PATHS.some((reserved) => pathsOverlap(mountPath, reserved))) throw new TypeError("mountPath overlaps files required by @cloudflare/sandbox");
+	return {
+		mountPath,
+		source: canonicalizeSource(request.source),
+		keyPrefix: canonicalizeKeyPrefix(request.keyPrefix),
+		access: canonicalizeAccess(request.access),
+		s3fsOptions: canonicalizeS3fsOptions(request.s3fsOptions)
+	};
+}
+function canonicalizeMountPath(value) {
+	const parsed = stringSchema.safeParse(value);
+	if (!parsed.success || !parsed.data.startsWith("/") || parsed.data.includes("\0")) throw new TypeError("mountPath must be an absolute path without NUL bytes");
+	value = parsed.data;
+	if (value === "/") throw new TypeError("mountPath must not be the filesystem root");
+	const segments = value.split("/");
+	if (value.endsWith("/") || segments.some((segment, index) => index > 0 && (segment === "" || segment === "." || segment === ".."))) throw new TypeError("mountPath must be a normalized non-root path");
+	return value;
+}
+function observedConfiguration(request) {
+	return {
+		source: {
+			type: "s3",
+			endpoint: request.source.endpoint,
+			region: request.source.region,
+			bucket: request.source.bucket
+		},
+		keyPrefix: request.keyPrefix,
+		access: request.access,
+		s3fsOptions: request.s3fsOptions
+	};
+}
+function pathsOverlap(left, right) {
+	return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+function canonicalizeAccess(value) {
+	if (value !== "read-only" && value !== "read-write") throw new TypeError("access must be \"read-only\" or \"read-write\"");
+	return value;
+}
+function canonicalizeKeyPrefix(value) {
+	if (value === void 0 || value === "") return void 0;
+	const parsed = stringSchema.safeParse(value);
+	if (!parsed.success || parsed.data.startsWith("/") || parsed.data.includes("\0")) throw new TypeError("keyPrefix must not start with '/' or contain NUL bytes");
+	return `${parsed.data.replace(/\/+$/, "")}/`;
+}
+function canonicalizeSource(source) {
+	if (!objectSchema.safeParse(source).success) throw new TypeError("source must be an object");
+	if (source.type !== "s3") throw new TypeError("source.type must be \"s3\"");
+	const bucket = requiredString(source.bucket, "source.bucket");
+	if (bucket.startsWith("-") || bucket.includes("/") || bucket.includes(":")) throw new TypeError("source.bucket must not start with '-' or contain '/' or ':'");
+	return {
+		type: "s3",
+		endpoint: canonicalizeEndpoint(source.endpoint),
+		region: requiredString(source.region, "source.region"),
+		bucket,
+		credentials: canonicalizeCredentials(source.credentials)
+	};
+}
+function canonicalizeEndpoint(value) {
+	const endpoint = requiredString(value, "source.endpoint");
+	let parsed;
+	try {
+		parsed = new URL(endpoint);
+	} catch {
+		throw new TypeError("source.endpoint must be a valid URL");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new TypeError("source.endpoint must use HTTP or HTTPS");
+	if (parsed.username !== "" || parsed.password !== "" || parsed.pathname !== "/" || parsed.search !== "" || parsed.hash !== "") throw new TypeError("source.endpoint must be an HTTP(S) origin without credentials, a path, query, or fragment");
+	return parsed.toString();
+}
+function canonicalizeCredentials(credentials) {
+	if (!objectSchema.safeParse(credentials).success) throw new TypeError("source.credentials must be an object");
+	if (credentials.type === "static") return {
+		type: "static",
+		accessKeyId: requiredString(credentials.accessKeyId, "credentials.accessKeyId"),
+		secretAccessKey: requiredString(credentials.secretAccessKey, "credentials.secretAccessKey"),
+		sessionToken: credentials.sessionToken === void 0 ? void 0 : requiredString(credentials.sessionToken, "credentials.sessionToken")
+	};
+	if (credentials.type === "provider") {
+		if (!fetcherSchema.safeParse(credentials.fetcher).success) throw new TypeError("provider credentials require a Fetcher");
+		return {
+			type: "provider",
+			fetcher: credentials.fetcher
+		};
+	}
+	throw new TypeError("credentials.type must be \"static\" or \"provider\"");
+}
+function canonicalizeS3fsOptions(options) {
+	if (options === void 0) return [];
+	if (!objectSchema.safeParse(options).success) throw new TypeError("s3fsOptions must be an object");
+	const normalized = [];
+	for (const [name, value] of Object.entries(options)) {
+		if (name === "" || name.includes("\0") || name.includes(",") || name.includes("=")) throw new TypeError("s3fs option names must not be empty or contain NUL, ',' or '='");
+		if (RESERVED_S3FS_OPTIONS.has(name.toLowerCase())) throw new TypeError(`s3fs option "${name}" is owned by @cloudflare/sandbox`);
+		if (value === false) continue;
+		if (value === true) {
+			normalized.push({ name });
+			continue;
+		}
+		const numberValue = finiteNumberSchema.safeParse(value);
+		if (numberValue.success) {
+			normalized.push({
+				name,
+				value: String(numberValue.data)
+			});
+			continue;
+		}
+		const stringValue = stringSchema.safeParse(value);
+		if (!stringValue.success || stringValue.data.includes("\0") || stringValue.data.includes(",")) throw new TypeError(`s3fs option "${name}" has an invalid value`);
+		normalized.push({
+			name,
+			value: stringValue.data
+		});
+	}
+	return normalized.sort((left, right) => {
+		if (left.name < right.name) return -1;
+		if (left.name > right.name) return 1;
+		return 0;
+	});
+}
+function requiredString(value, name) {
+	const parsed = stringSchema.safeParse(value);
+	if (!parsed.success || parsed.data === "" || parsed.data.includes("\0")) throw new TypeError(`${name} must be a non-empty string without NUL bytes`);
+	return parsed.data;
+}
+//#endregion
+//#region src/s3-mounts/protocol.ts
+const ROUTE_READY = new Uint8Array([1]);
+const routeIdSchema = z.string().check(z.regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,58}[A-Za-z0-9])?$/));
+const keyPrefixSchema = z.optional(z.string().check(z.refine((value) => value.endsWith("/"))));
+const s3fsOptionSchema = z.object({
+	name: z.string(),
+	value: z.optional(z.string())
+});
+const observedConfigurationSchema = z.object({
+	source: z.object({
+		type: z.literal("s3"),
+		endpoint: z.string(),
+		region: z.string(),
+		bucket: z.string()
+	}),
+	keyPrefix: keyPrefixSchema,
+	access: z.union([z.literal("read-only"), z.literal("read-write")]),
+	s3fsOptions: z.array(s3fsOptionSchema)
+});
+const markerSchema = z.object({
+	protocolVersion: z.literal(1),
+	routeId: routeIdSchema,
+	mountPath: z.string(),
+	configuration: observedConfigurationSchema
+});
+const fuseSchema = z.discriminatedUnion("status", [
+	z.object({ status: z.literal("connected") }),
+	z.object({ status: z.literal("disconnected") }),
+	z.object({
+		status: z.literal("indeterminate"),
+		detail: z.string()
+	})
+]);
+const guestStateSchema = z.discriminatedUnion("kind", [
+	z.object({ kind: z.literal("absent") }),
+	z.object({
+		kind: z.literal("unmanaged"),
+		filesystemType: z.string()
+	}),
+	z.object({
+		kind: z.literal("incompatible"),
+		protocolVersion: z.number().check(z.int())
+	}),
+	z.object({
+		kind: z.literal("stale"),
+		marker: markerSchema
+	}),
+	z.object({
+		kind: z.literal("managed"),
+		marker: markerSchema,
+		fuse: fuseSchema
+	})
+]);
+const gatewayStateSchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("gatewayUnreachable"),
+		detail: z.string()
+	}),
+	z.object({
+		kind: z.literal("gatewayError"),
+		reason: z.union([
+			z.literal("credential-provider"),
+			z.literal("protocol"),
+			z.literal("internal")
+		]),
+		detail: z.string()
+	}),
+	z.object({ kind: z.literal("usable") }),
+	z.object({
+		kind: z.literal("upstreamUnavailable"),
+		detail: z.string()
+	}),
+	z.object({
+		kind: z.literal("upstreamRejected"),
+		reason: z.union([
+			z.literal("credentials"),
+			z.literal("access"),
+			z.literal("not-found"),
+			z.literal("other")
+		]),
+		detail: z.string()
+	})
+]);
+const inspectionEvidenceSchema = z.object({
+	state: guestStateSchema,
+	gateway: z.optional(gatewayStateSchema)
+});
+const envelopeSchema = z.discriminatedUnion("ok", [z.object({
+	ok: z.literal(true),
+	value: z.json()
+}), z.object({
+	ok: z.literal(false),
+	error: z.object({
+		kind: z.string(),
+		detail: z.string()
+	})
+})]);
+const routeSelectionSchema = z.object({
+	kind: z.literal("route"),
+	routeId: routeIdSchema
+});
+function mountGuest(container, request, options, installRoute) {
+	return invokeInteractive(container, ["mount", JSON.stringify(request)], "mount", request.mountPath, options, false, installRoute);
+}
+function inspectGuestMount(container, mountPath, options) {
+	return invokeOnce(container, ["inspect", mountPath], "inspect", mountPath, options, (value) => parseInspectionEvidence(value, mountPath));
+}
+function unmountGuest(container, mountPath, options, denyRoute) {
+	return invokeInteractive(container, ["unmount", mountPath], "unmount", mountPath, options, true, denyRoute);
+}
+async function invokeInteractive(container, command, operation, mountPath, options, allowImmediateCompletion, handleRoute) {
+	const session = await startSession(container, command, options, true);
+	let control;
+	let input;
+	try {
+		control = session.openStdoutControl();
+		const first = await readEnvelope(control, operation, mountPath);
+		if (first === null) {
+			if (!allowImmediateCompletion) throw protocolError("sandbox-shim returned invalid S3 mount route selection");
+			await finishSession(session, control);
+			session.finish();
+			return;
+		}
+		const routeId = parseRouteSelection(first);
+		if (routeId === void 0) throw protocolError("sandbox-shim returned invalid S3 mount route selection");
+		await session.waitFor(handleRoute(routeId));
+		options.signal?.throwIfAborted();
+		input = session.openStdinWriter();
+		await session.waitFor(input.write(ROUTE_READY));
+		await session.waitFor(input.close());
+		input.releaseLock();
+		input = void 0;
+		let terminal;
+		try {
+			terminal = await readEnvelope(control, operation, mountPath);
+		} catch (error) {
+			if (!SandboxS3MountError.is(error)) throw error;
+			await finishSession(session, control);
+			session.finish();
+			control = void 0;
+			throw error;
+		}
+		if (terminal !== null) throw protocolError("sandbox-shim returned invalid S3 mount completion data");
+		await finishSession(session, control);
+		session.finish();
+	} catch (error) {
+		session.terminate();
+		if (input !== void 0) input.abort(error).then(() => input?.releaseLock(), () => input?.releaseLock());
+		control?.discard(error);
+		throw error;
+	}
+}
+async function invokeOnce(container, command, operation, mountPath, options, parseValue) {
+	const session = await startSession(container, command, options, false);
+	let control;
+	try {
+		control = session.openStdoutControl();
+		const parsed = parseValue(await readEnvelope(control, operation, mountPath));
+		if (parsed === void 0) throw protocolError("sandbox-shim returned invalid S3 mount command data");
+		await finishSession(session, control);
+		session.finish();
+		return parsed;
+	} catch (error) {
+		session.terminate();
+		control?.discard(error);
+		throw error;
+	}
+}
+function startSession(container, command, options, interactive) {
+	const execOptions = {
+		signal: options.signal,
+		stdout: "pipe",
+		stderr: "ignore"
+	};
+	if (interactive) execOptions.stdin = "pipe";
+	return ShimSession.start(container, [
+		SHIM_PATH,
+		"s3-mount",
+		...command
+	], execOptions);
+}
+async function finishSession(session, control) {
+	await control.expectEnd();
+	const exitCode = await session.waitFor(session.process.exitCode);
+	if (exitCode !== 0) throw protocolError(`sandbox-shim exited with code ${exitCode}`);
+	control.releaseLock();
+}
+async function readEnvelope(control, operation, mountPath) {
+	const frame = await control.readFrame();
+	if (frame.kind !== "data") throw protocolError("sandbox-shim did not return S3 mount command data");
+	return decodeEnvelope(parseJsonPayload(frame.payload, "sandbox-shim returned invalid S3 mount command data"), operation, mountPath);
+}
+function decodeEnvelope(value, operation, mountPath) {
+	const parsed = envelopeSchema.safeParse(value);
+	if (!parsed.success) throw protocolError("sandbox-shim returned an invalid S3 mount result");
+	if (!parsed.data.ok) {
+		const { detail, kind } = parsed.data.error;
+		if (kind === "protocol") throw protocolError(detail);
+		const code = errorCode(kind);
+		if (code === void 0) throw protocolError(`sandbox-shim returned unknown S3 mount error kind "${kind}"`);
+		throw s3MountError(code, operation, mountPath, detail);
+	}
+	return parsed.data.value;
+}
+function errorCode(kind) {
+	switch (kind) {
+		case "busy": return "S3_MOUNT_BUSY";
+		case "conflict": return "S3_MOUNT_CONFLICT";
+		case "failed": return "S3_MOUNT_FAILED";
+		case "incompatible": return "S3_MOUNT_INCOMPATIBLE";
+		default: return;
+	}
+}
+function parseRouteSelection(value) {
+	const selection = routeSelectionSchema.safeParse(value);
+	return selection.success ? selection.data.routeId : void 0;
+}
+function parseInspectionEvidence(value, expectedMountPath) {
+	const evidence = inspectionEvidenceSchema.safeParse(value);
+	if (!evidence.success) return void 0;
+	const state = parseGuestMountState(evidence.data.state, expectedMountPath);
+	if (state === void 0) return void 0;
+	if (state.kind !== "stale" && state.kind !== "managed") return evidence.data.gateway === void 0 ? { state } : void 0;
+	return evidence.data.gateway === void 0 ? void 0 : {
+		state,
+		gateway: parseGatewayState(evidence.data.gateway)
+	};
+}
+function parseGuestMountState(state, expectedMountPath) {
+	switch (state.kind) {
+		case "absent": return { kind: "absent" };
+		case "unmanaged": return {
+			kind: "unmanaged",
+			filesystemType: state.filesystemType
+		};
+		case "incompatible": return { kind: "incompatible" };
+		case "stale": {
+			const marker = parseMarker(state.marker, expectedMountPath);
+			return marker === void 0 ? void 0 : {
+				kind: "stale",
+				marker
+			};
+		}
+		case "managed": {
+			const marker = parseMarker(state.marker, expectedMountPath);
+			const fuse = parseFuseState(state.fuse);
+			return marker === void 0 || fuse === void 0 ? void 0 : {
+				kind: "managed",
+				marker,
+				fuse
+			};
+		}
+		default: return;
+	}
+}
+function parseMarker(marker, expectedMountPath) {
+	if (marker.mountPath !== expectedMountPath) return void 0;
+	return {
+		protocolVersion: 1,
+		routeId: marker.routeId,
+		mountPath: expectedMountPath,
+		configuration: marker.configuration
+	};
+}
+function parseFuseState(state) {
+	return state;
+}
+function parseGatewayState(state) {
+	switch (state.kind) {
+		case "gatewayUnreachable": return {
+			status: "unreachable",
+			detail: state.detail
+		};
+		case "gatewayError": return {
+			status: "error",
+			reason: state.reason,
+			detail: state.detail
+		};
+		case "usable": return {
+			status: "reachable",
+			upstream: { status: "usable" }
+		};
+		case "upstreamUnavailable": return {
+			status: "reachable",
+			upstream: {
+				status: "unavailable",
+				detail: state.detail
+			}
+		};
+		case "upstreamRejected": return {
+			status: "reachable",
+			upstream: {
+				status: "rejected",
+				reason: state.reason,
+				detail: state.detail
+			}
+		};
+	}
+}
+//#endregion
+//#region src/s3-mounts/reconcile.ts
+function assembleInspection(mountPath, evidence) {
+	const state = evidence.state;
+	switch (state.kind) {
+		case "absent": return {
+			mountPath,
+			attachment: { status: "absent" }
+		};
+		case "unmanaged": return {
+			mountPath,
+			attachment: {
+				status: "unmanaged",
+				filesystemType: state.filesystemType
+			}
+		};
+		case "incompatible": return {
+			mountPath,
+			attachment: { status: "incompatible" }
+		};
+		case "stale": return {
+			mountPath,
+			attachment: {
+				status: "stale",
+				configuration: state.marker.configuration
+			},
+			gateway: gatewayFor(evidence)
+		};
+		case "managed": return {
+			mountPath,
+			attachment: {
+				status: "managed",
+				configuration: state.marker.configuration
+			},
+			fuse: state.fuse,
+			gateway: gatewayFor(evidence)
+		};
+	}
+}
+function gatewayFor(evidence) {
+	if ("gateway" in evidence) return evidence.gateway;
+	throw protocolError("sandbox-shim omitted managed mount gateway evidence");
+}
+//#endregion
+//#region src/s3-mounts/s3-mounts.ts
+/**
+* Attaches an S3-compatible bucket or prefix to a running Container.
+*
+* Use this for a few long-lived mounts in one job or session. Calling `mount()`
+* again with the same settings reuses the existing mount. `unmount()` stops
+* access and unmounts the path. It does not fully clean up the Container's
+* intercept. For a new job or tenant, use a new sandbox name.
+*
+* Start the Container before calling `mount()`. This class never starts,
+* monitors, or replaces it. The mounted path is not a POSIX filesystem. Do not
+* use it for locking or atomic rename.
+*/
+var S3Mounts = class {
+	#container;
+	#gateway;
+	constructor(container, gateway) {
+		this.#container = container;
+		this.#gateway = gateway;
+	}
+	/**
+	* Creates the mount, reuses a matching mount, or repairs leftover state.
+	*
+	* Reuse does not consume another Container intercept. Use `inspect()` to read
+	* current state without changing it.
+	*/
+	async mount(request, options = {}) {
+		const canonical = canonicalizeS3MountRequest(request);
+		options.signal?.throwIfAborted();
+		let installedRouteId;
+		try {
+			await mountGuest(this.#container, {
+				protocolVersion: 1,
+				candidateRouteId: crypto.randomUUID(),
+				mountPath: canonical.mountPath,
+				configuration: observedConfiguration(canonical)
+			}, options, async (routeId) => {
+				installedRouteId = routeId;
+				const gateway = this.#gateway({ props: {
+					protocolVersion: 1,
+					mode: "active",
+					routeId,
+					source: canonical.source,
+					keyPrefix: canonical.keyPrefix,
+					access: canonical.access
+				} });
+				try {
+					await this.#container.interceptOutboundHttp(routeHost(routeId), gateway);
+				} finally {
+					if (options.signal?.aborted) try {
+						await this.#denyRoute(routeId);
+					} catch {}
+				}
+			});
+		} catch (error) {
+			if (installedRouteId !== void 0) try {
+				await this.#denyRoute(installedRouteId);
+			} catch {}
+			throw error;
+		}
+	}
+	/**
+	* Reports the current path without changing it.
+	*
+	* Waits for an in-flight `mount()` or `unmount()` on the same path first.
+	* Gateway evidence can be newer than the guest snapshot. Pass `signal` when
+	* the application needs a deadline.
+	*/
+	async inspect(mountPath, options = {}) {
+		const canonicalPath = canonicalizeMountPath(mountPath);
+		return assembleInspection(canonicalPath, await inspectGuestMount(this.#container, canonicalPath, options));
+	}
+	/**
+	* Stops new access, then unmounts the path.
+	*
+	* This does not remove the Container intercept. If denying access fails, the
+	* filesystem stays mounted. If the filesystem is busy, access stays denied
+	* and you can retry. This never force-unmounts.
+	*/
+	async unmount(mountPath, options = {}) {
+		const canonicalPath = canonicalizeMountPath(mountPath);
+		await unmountGuest(this.#container, canonicalPath, options, (routeId) => this.#denyRoute(routeId));
+	}
+	async #denyRoute(routeId) {
+		const denyGateway = this.#gateway({ props: {
+			protocolVersion: 1,
+			mode: "deny",
+			routeId
+		} });
+		await this.#container.interceptOutboundHttp(routeHost(routeId), denyGateway);
+	}
+};
+//#endregion
+export { DirectoryBackupGateway, DirectoryBackups, Files, S3Gateway, S3Mounts, SandboxBackupError, SandboxFileError, SandboxProtocolError, SandboxS3MountError };