@cloudflare/sandbox 0.7.4 → 0.7.5

package/dist/index.js

@@ -1,6 +1,7 @@
 import { _ as getEnvString, a as isExecResult, c as shellEscape, d as TraceContext, f as Execution, g as filterEnvVars, h as extractRepoName, i as isWSStreamChunk, l as createLogger, m as GitLogger, n as isWSError, o as isProcess, p as ResultImpl, r as isWSResponse, s as isProcessStatus, t as generateRequestId, u as createNoOpLogger, v as partitionEnvVars } from "./dist-D9B_6gn_.js";
-import { t as ErrorCode } from "./errors-Bzl0ZNia.js";
+import { t as ErrorCode } from "./errors-CYUY62c6.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
+import { AwsClient } from "aws4fetch";
 
 //#region src/errors/classes.ts
 /**
@@ -511,6 +512,75 @@ var ProcessExitedBeforeReadyError = class extends SandboxError {
 		return this.context.exitCode;
 	}
 };
+/**
+* Error thrown when a backup is not found in R2
+*/
+var BackupNotFoundError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "BackupNotFoundError";
+	}
+	get backupId() {
+		return this.context.backupId;
+	}
+};
+/**
+* Error thrown when a backup has expired (past its TTL)
+*/
+var BackupExpiredError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "BackupExpiredError";
+	}
+	get backupId() {
+		return this.context.backupId;
+	}
+	get expiredAt() {
+		return this.context.expiredAt;
+	}
+};
+/**
+* Error thrown when backup configuration or inputs are invalid
+*/
+var InvalidBackupConfigError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "InvalidBackupConfigError";
+	}
+	get reason() {
+		return this.context.reason;
+	}
+};
+/**
+* Error thrown when backup creation fails
+*/
+var BackupCreateError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "BackupCreateError";
+	}
+	get dir() {
+		return this.context.dir;
+	}
+	get backupId() {
+		return this.context.backupId;
+	}
+};
+/**
+* Error thrown when backup restoration fails
+*/
+var BackupRestoreError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "BackupRestoreError";
+	}
+	get dir() {
+		return this.context.dir;
+	}
+	get backupId() {
+		return this.context.backupId;
+	}
+};
 
 //#endregion
 //#region src/errors/adapter.ts
@@ -557,6 +627,11 @@ function createErrorFromResponse(errorResponse) {
 		case ErrorCode.GIT_CHECKOUT_FAILED: return new GitCheckoutError(errorResponse);
 		case ErrorCode.INVALID_GIT_URL: return new InvalidGitUrlError(errorResponse);
 		case ErrorCode.GIT_OPERATION_FAILED: return new GitError(errorResponse);
+		case ErrorCode.BACKUP_NOT_FOUND: return new BackupNotFoundError(errorResponse);
+		case ErrorCode.BACKUP_EXPIRED: return new BackupExpiredError(errorResponse);
+		case ErrorCode.INVALID_BACKUP_CONFIG: return new InvalidBackupConfigError(errorResponse);
+		case ErrorCode.BACKUP_CREATE_FAILED: return new BackupCreateError(errorResponse);
+		case ErrorCode.BACKUP_RESTORE_FAILED: return new BackupRestoreError(errorResponse);
 		case ErrorCode.INTERPRETER_NOT_READY: return new InterpreterNotReadyError(errorResponse);
 		case ErrorCode.CONTEXT_NOT_FOUND: return new ContextNotFoundError(errorResponse);
 		case ErrorCode.CODE_EXECUTION_ERROR: return new CodeExecutionError(errorResponse);
@@ -1254,6 +1329,60 @@ var BaseHttpClient = class {
 	}
 };
 
+//#endregion
+//#region src/clients/backup-client.ts
+/**
+* Client for backup operations.
+*
+* Handles communication with the container's backup endpoints.
+* The container creates/extracts squashfs archives locally.
+* R2 upload/download is handled by the Sandbox DO, not by this client.
+*/
+var BackupClient = class extends BaseHttpClient {
+	/**
+	* Tell the container to create a squashfs archive from a directory.
+	* @param dir - Directory to back up
+	* @param archivePath - Where the container should write the archive
+	* @param sessionId - Session context
+	*/
+	async createArchive(dir, archivePath, sessionId) {
+		try {
+			const data = {
+				dir,
+				archivePath,
+				sessionId
+			};
+			const response = await this.post("/api/backup/create", data);
+			this.logSuccess("Backup archive created", `${dir} -> ${archivePath}`);
+			return response;
+		} catch (error) {
+			this.logError("createArchive", error);
+			throw error;
+		}
+	}
+	/**
+	* Tell the container to restore a squashfs archive into a directory.
+	* @param dir - Target directory
+	* @param archivePath - Path to the archive file in the container
+	* @param sessionId - Session context
+	*/
+	async restoreArchive(dir, archivePath, sessionId) {
+		try {
+			const data = {
+				dir,
+				archivePath,
+				sessionId
+			};
+			const response = await this.post("/api/backup/restore", data);
+			this.logSuccess("Backup archive restored", `${archivePath} -> ${dir}`);
+			return response;
+		} catch (error) {
+			this.logError("restoreArchive", error);
+			throw error;
+		}
+	}
+};
+
 //#endregion
 //#region src/clients/command-client.ts
 /**
@@ -2010,6 +2139,7 @@ var UtilityClient = class extends BaseHttpClient {
 * WebSocket mode reduces sub-request count when running inside Workers/Durable Objects.
 */
 var SandboxClient = class {
+	backup;
 	commands;
 	files;
 	processes;
@@ -2032,6 +2162,7 @@ var SandboxClient = class {
 			...options,
 			transport: this.transport ?? options.transport
 		};
+		this.backup = new BackupClient(clientOptions);
 		this.commands = new CommandClient(clientOptions);
 		this.files = new FileClient(clientOptions);
 		this.processes = new ProcessClient(clientOptions);
@@ -2567,7 +2698,7 @@ function buildS3fsSource(bucket, prefix) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.7.4";
+const SDK_VERSION = "0.7.5";
 
 //#endregion
 //#region src/sandbox.ts
@@ -2612,7 +2743,14 @@ function connect(stub) {
 		return await stub.fetch(portSwitchedRequest);
 	};
 }
-var Sandbox = class extends Container {
+/**
+* Type guard for R2Bucket binding.
+* Checks for the minimal R2Bucket interface methods we use.
+*/
+function isR2Bucket(value) {
+	return typeof value === "object" && value !== null && "put" in value && typeof value.put === "function" && "get" in value && typeof value.get === "function" && "head" in value && typeof value.head === "function" && "delete" in value && typeof value.delete === "function";
+}
+var Sandbox = class Sandbox extends Container {
 	defaultPort = 3e3;
 	sleepAfter = "10m";
 	client;
@@ -2626,6 +2764,24 @@ var Sandbox = class extends Container {
 	keepAliveEnabled = false;
 	activeMounts = /* @__PURE__ */ new Map();
 	transport = "http";
+	backupBucket = null;
+	/**
+	* Serializes backup operations to prevent concurrent create/restore on the same sandbox.
+	*
+	* This is in-memory state — it resets if the Durable Object is evicted and
+	* re-instantiated (e.g. after sleep). This is acceptable because the container
+	* filesystem is also lost on eviction, so there is no archive to race on.
+	*/
+	backupInProgress = Promise.resolve();
+	/**
+	* R2 presigned URL credentials for direct container-to-R2 transfers.
+	* All four fields plus the R2 binding must be configured for backup to work.
+	*/
+	r2AccessKeyId = null;
+	r2SecretAccessKey = null;
+	r2AccountId = null;
+	backupBucketName = null;
+	r2Client = null;
 	/**
 	* Default container startup timeouts (conservative for production)
 	* Based on Cloudflare docs: "Containers take several minutes to provision"
@@ -2668,6 +2824,16 @@ var Sandbox = class extends Container {
 		const transportEnv = envObj?.SANDBOX_TRANSPORT;
 		if (transportEnv === "websocket") this.transport = "websocket";
 		else if (transportEnv != null && transportEnv !== "http") this.logger.warn(`Invalid SANDBOX_TRANSPORT value: "${transportEnv}". Must be "http" or "websocket". Defaulting to "http".`);
+		const backupBucket = envObj?.BACKUP_BUCKET;
+		if (isR2Bucket(backupBucket)) this.backupBucket = backupBucket;
+		this.r2AccountId = getEnvString(envObj, "CLOUDFLARE_ACCOUNT_ID") ?? null;
+		this.r2AccessKeyId = getEnvString(envObj, "R2_ACCESS_KEY_ID") ?? null;
+		this.r2SecretAccessKey = getEnvString(envObj, "R2_SECRET_ACCESS_KEY") ?? null;
+		this.backupBucketName = getEnvString(envObj, "BACKUP_BUCKET_NAME") ?? null;
+		if (this.r2AccessKeyId && this.r2SecretAccessKey) this.r2Client = new AwsClient({
+			accessKeyId: this.r2AccessKeyId,
+			secretAccessKey: this.r2SecretAccessKey
+		});
 		this.client = this.createSandboxClient();
 		this.codeInterpreter = new CodeInterpreter(this);
 		this.ctx.blockConcurrencyWhile(async () => {
@@ -3896,7 +4062,9 @@ var Sandbox = class extends Container {
 			listCodeContexts: () => this.codeInterpreter.listCodeContexts(),
 			deleteCodeContext: (contextId) => this.codeInterpreter.deleteCodeContext(contextId),
 			mountBucket: (bucket, mountPath, options) => this.mountBucket(bucket, mountPath, options),
-			unmountBucket: (mountPath) => this.unmountBucket(mountPath)
+			unmountBucket: (mountPath) => this.unmountBucket(mountPath),
+			createBackup: (options) => this.createBackup(options),
+			restoreBackup: (backup) => this.restoreBackup(backup)
 		};
 	}
 	async createCodeContext(options) {
@@ -3914,6 +4082,471 @@ var Sandbox = class extends Container {
 	async deleteCodeContext(contextId) {
 		return this.codeInterpreter.deleteCodeContext(contextId);
 	}
+	/** UUID v4 format validator for backup IDs */
+	static UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+	/**
+	* Validate that a directory path is safe for backup operations.
+	* Rejects empty, relative, traversal, and null-byte paths.
+	*/
+	static validateBackupDir(dir, label) {
+		if (!dir || !dir.startsWith("/")) throw new InvalidBackupConfigError({
+			message: `${label} must be an absolute path`,
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: `${label} must be an absolute path` },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		if (dir.includes("\0")) throw new InvalidBackupConfigError({
+			message: `${label} must not contain null bytes`,
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: `${label} must not contain null bytes` },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		if (dir.split("/").includes("..")) throw new InvalidBackupConfigError({
+			message: `${label} must not contain ".." path segments`,
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: `${label} must not contain ".." path segments` },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	/**
+	* Returns the R2 bucket or throws if backup is not configured.
+	*/
+	requireBackupBucket() {
+		if (!this.backupBucket) throw new InvalidBackupConfigError({
+			message: "Backup not configured. Add a BACKUP_BUCKET R2 binding to your wrangler.jsonc.",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "Missing BACKUP_BUCKET R2 binding" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		return this.backupBucket;
+	}
+	static PRESIGNED_URL_EXPIRY_SECONDS = 3600;
+	/**
+	* Ensure a dedicated session for backup operations exists.
+	* Isolates backup shell commands (curl, stat, rm, mkdir) from user exec()
+	* calls to prevent session state interference and interleaving.
+	*/
+	async ensureBackupSession() {
+		const sessionId = "__sandbox_backup__";
+		try {
+			await this.client.utils.createSession({
+				id: sessionId,
+				cwd: "/"
+			});
+		} catch (error) {
+			if (!(error instanceof SessionAlreadyExistsError)) throw error;
+		}
+		return sessionId;
+	}
+	/**
+	* Returns validated presigned URL configuration or throws if not configured.
+	* All credential fields plus the R2 binding are required for backup to work.
+	*/
+	requirePresignedUrlSupport() {
+		if (!this.r2Client || !this.r2AccountId || !this.backupBucketName) {
+			const missing = [];
+			if (!this.r2AccountId) missing.push("CLOUDFLARE_ACCOUNT_ID");
+			if (!this.r2AccessKeyId) missing.push("R2_ACCESS_KEY_ID");
+			if (!this.r2SecretAccessKey) missing.push("R2_SECRET_ACCESS_KEY");
+			if (!this.backupBucketName) missing.push("BACKUP_BUCKET_NAME");
+			throw new InvalidBackupConfigError({
+				message: `Backup requires R2 presigned URL credentials. Missing: ${missing.join(", ")}. Set these as environment variables or secrets in your wrangler.jsonc.`,
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: `Missing env vars: ${missing.join(", ")}` },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		return {
+			client: this.r2Client,
+			accountId: this.r2AccountId,
+			bucketName: this.backupBucketName
+		};
+	}
+	/**
+	* Generate a presigned GET URL for downloading an object from R2.
+	* The container can curl this URL directly without credentials.
+	*/
+	async generatePresignedGetUrl(r2Key) {
+		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
+		const encodedBucket = encodeURIComponent(bucketName);
+		const encodedKey = r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/");
+		const url = new URL(`https://${accountId}.r2.cloudflarestorage.com/${encodedBucket}/${encodedKey}`);
+		url.searchParams.set("X-Amz-Expires", String(Sandbox.PRESIGNED_URL_EXPIRY_SECONDS));
+		return (await client.sign(new Request(url), { aws: { signQuery: true } })).url;
+	}
+	/**
+	* Generate a presigned PUT URL for uploading an object to R2.
+	* The container can curl PUT to this URL directly without credentials.
+	*/
+	async generatePresignedPutUrl(r2Key) {
+		const { client, accountId, bucketName } = this.requirePresignedUrlSupport();
+		const encodedBucket = encodeURIComponent(bucketName);
+		const encodedKey = r2Key.split("/").map((seg) => encodeURIComponent(seg)).join("/");
+		const url = new URL(`https://${accountId}.r2.cloudflarestorage.com/${encodedBucket}/${encodedKey}`);
+		url.searchParams.set("X-Amz-Expires", String(Sandbox.PRESIGNED_URL_EXPIRY_SECONDS));
+		return (await client.sign(new Request(url, { method: "PUT" }), { aws: { signQuery: true } })).url;
+	}
+	/**
+	* Upload a backup archive via presigned PUT URL.
+	* The container curls the archive directly to R2, bypassing the DO.
+	* ~24 MB/s throughput vs ~0.6 MB/s for base64 readFile.
+	*/
+	async uploadBackupPresigned(archivePath, r2Key, archiveSize, backupId, dir, backupSession) {
+		const presignedUrl = await this.generatePresignedPutUrl(r2Key);
+		this.logger.info("Uploading backup via presigned PUT", {
+			r2Key,
+			archiveSize,
+			backupId
+		});
+		const curlCmd = [
+			"curl -sSf",
+			"-X PUT",
+			"-H 'Content-Type: application/octet-stream'",
+			"--connect-timeout 10",
+			"--max-time 300",
+			"--retry 2",
+			"--retry-max-time 60",
+			`--data-binary @${shellEscape(archivePath)}`,
+			shellEscape(presignedUrl)
+		].join(" ");
+		const result = await this.execWithSession(curlCmd, backupSession, { timeout: 31e4 });
+		if (result.exitCode !== 0) throw new BackupCreateError({
+			message: `Presigned URL upload failed (exit code ${result.exitCode}): ${result.stderr}`,
+			code: ErrorCode.BACKUP_CREATE_FAILED,
+			httpStatus: 500,
+			context: {
+				dir,
+				backupId
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const head = await this.requireBackupBucket().head(r2Key);
+		if (!head || head.size !== archiveSize) throw new BackupCreateError({
+			message: `Upload verification failed: expected ${archiveSize} bytes, got ${head?.size ?? 0}`,
+			code: ErrorCode.BACKUP_CREATE_FAILED,
+			httpStatus: 500,
+			context: {
+				dir,
+				backupId
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	}
+	/**
+	* Download a backup archive via presigned GET URL.
+	* The container curls the archive directly from R2, bypassing the DO.
+	* ~93 MB/s throughput vs ~0.6 MB/s for base64 writeFile.
+	*/
+	async downloadBackupPresigned(archivePath, r2Key, expectedSize, backupId, dir, backupSession) {
+		const presignedUrl = await this.generatePresignedGetUrl(r2Key);
+		this.logger.info("Downloading backup via presigned GET", {
+			r2Key,
+			expectedSize,
+			backupId
+		});
+		await this.execWithSession("mkdir -p /var/backups", backupSession);
+		const tmpPath = `${archivePath}.tmp`;
+		const curlCmd = [
+			"curl -sSf",
+			"--connect-timeout 10",
+			"--max-time 300",
+			"--retry 2",
+			"--retry-max-time 60",
+			`-o ${shellEscape(tmpPath)}`,
+			shellEscape(presignedUrl)
+		].join(" ");
+		const result = await this.execWithSession(curlCmd, backupSession, { timeout: 31e4 });
+		if (result.exitCode !== 0) {
+			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession).catch(() => {});
+			throw new BackupRestoreError({
+				message: `Presigned URL download failed (exit code ${result.exitCode}): ${result.stderr}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(tmpPath)}`, backupSession);
+		const actualSize = parseInt(sizeCheck.stdout.trim(), 10);
+		if (actualSize !== expectedSize) {
+			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession).catch(() => {});
+			throw new BackupRestoreError({
+				message: `Downloaded archive size mismatch: expected ${expectedSize}, got ${actualSize}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		const mvResult = await this.execWithSession(`mv ${shellEscape(tmpPath)} ${shellEscape(archivePath)}`, backupSession);
+		if (mvResult.exitCode !== 0) {
+			await this.execWithSession(`rm -f ${shellEscape(tmpPath)}`, backupSession).catch(() => {});
+			throw new BackupRestoreError({
+				message: `Failed to finalize downloaded archive: ${mvResult.stderr}`,
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+	}
+	/**
+	* Serialize backup operations on this sandbox instance.
+	* Concurrent backup/restore calls are queued so the multi-step
+	* create-archive → read → upload (or download → write → extract) flow
+	* is not interleaved with another backup operation on the same directory.
+	*/
+	enqueueBackupOp(fn) {
+		const next = this.backupInProgress.then(fn, () => fn());
+		this.backupInProgress = next.catch(() => {});
+		return next;
+	}
+	/**
+	* Create a backup of a directory and upload it to R2.
+	*
+	* Flow:
+	*   1. Container creates squashfs archive from the directory
+	*   2. Container uploads the archive directly to R2 via presigned URL
+	*   3. DO writes metadata to R2
+	*   4. Container cleans up the local archive
+	*
+	* The returned DirectoryBackup handle is serializable. Store it anywhere
+	* (KV, D1, DO storage) and pass it to restoreBackup() later.
+	*
+	* Concurrent backup/restore calls on the same sandbox are serialized.
+	*
+	* Partially-written files in the target directory may not be captured
+	* consistently. Completed writes are captured.
+	*
+	* NOTE: Expired backups are not automatically deleted from R2. Configure
+	* R2 lifecycle rules on the BACKUP_BUCKET to garbage-collect objects
+	* under the `backups/` prefix after the desired retention period.
+	*/
+	async createBackup(options) {
+		this.requireBackupBucket();
+		return this.enqueueBackupOp(() => this.doCreateBackup(options));
+	}
+	async doCreateBackup(options) {
+		const bucket = this.requireBackupBucket();
+		this.requirePresignedUrlSupport();
+		const DEFAULT_TTL_SECONDS = 259200;
+		const MAX_NAME_LENGTH = 256;
+		const { dir, name, ttl = DEFAULT_TTL_SECONDS } = options;
+		Sandbox.validateBackupDir(dir, "BackupOptions.dir");
+		if (name !== void 0) {
+			if (typeof name !== "string" || name.length > MAX_NAME_LENGTH) throw new InvalidBackupConfigError({
+				message: `BackupOptions.name must be a string of at most ${MAX_NAME_LENGTH} characters`,
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: `name must be a string of at most ${MAX_NAME_LENGTH} characters` },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			if (/[\u0000-\u001f\u007f]/.test(name)) throw new InvalidBackupConfigError({
+				message: "BackupOptions.name must not contain control characters",
+				code: ErrorCode.INVALID_BACKUP_CONFIG,
+				httpStatus: 400,
+				context: { reason: "name must not contain control characters" },
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+		if (ttl <= 0) throw new InvalidBackupConfigError({
+			message: "BackupOptions.ttl must be a positive number of seconds",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "ttl must be a positive number of seconds" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const backupSession = await this.ensureBackupSession();
+		const backupId = crypto.randomUUID();
+		const archivePath = `/var/backups/${backupId}.sqsh`;
+		this.logger.info("Creating backup", {
+			backupId,
+			dir,
+			name
+		});
+		const createResult = await this.client.backup.createArchive(dir, archivePath, backupSession);
+		if (!createResult.success) throw new BackupCreateError({
+			message: "Container failed to create backup archive",
+			code: ErrorCode.BACKUP_CREATE_FAILED,
+			httpStatus: 500,
+			context: {
+				dir,
+				backupId
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const r2Key = `backups/${backupId}/data.sqsh`;
+		const metaKey = `backups/${backupId}/meta.json`;
+		try {
+			await this.uploadBackupPresigned(archivePath, r2Key, createResult.sizeBytes, backupId, dir, backupSession);
+			const metadata = {
+				id: backupId,
+				dir,
+				name: name || null,
+				sizeBytes: createResult.sizeBytes,
+				ttl,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			await bucket.put(metaKey, JSON.stringify(metadata));
+			this.logger.info("Backup uploaded to R2", {
+				backupId,
+				r2Key,
+				sizeBytes: createResult.sizeBytes
+			});
+			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession).catch(() => {});
+			return {
+				id: backupId,
+				dir
+			};
+		} catch (error) {
+			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession).catch(() => {});
+			await bucket.delete(r2Key).catch(() => {});
+			await bucket.delete(metaKey).catch(() => {});
+			throw error;
+		}
+	}
+	/**
+	* Restore a backup from R2 into a directory.
+	*
+	* Flow:
+	*   1. DO reads metadata from R2 and checks TTL
+	*   2. Container downloads the archive directly from R2 via presigned URL
+	*   3. Container mounts the squashfs archive with FUSE overlayfs
+	*
+	* The target directory becomes an overlay mount with the backup as a
+	* read-only lower layer and a writable upper layer for copy-on-write.
+	* Any processes writing to the directory should be stopped first.
+	*
+	* **Mount Lifecycle**: The FUSE overlay mount persists only while the
+	* container is running. When the sandbox sleeps or the container restarts,
+	* the mount is lost and the directory becomes empty. Re-restore from the
+	* backup handle to recover. This is an ephemeral restore, not a persistent
+	* extraction.
+	*
+	* The backup is restored into `backup.dir`. This may differ from the
+	* directory that was originally backed up, allowing cross-directory restore.
+	*
+	* Overlapping backups are independent: restoring a parent directory
+	* overwrites everything inside it, including subdirectories that were
+	* backed up separately. When restoring both, restore the parent first.
+	*
+	* Concurrent backup/restore calls on the same sandbox are serialized.
+	*/
+	async restoreBackup(backup) {
+		this.requireBackupBucket();
+		return this.enqueueBackupOp(() => this.doRestoreBackup(backup));
+	}
+	async doRestoreBackup(backup) {
+		const bucket = this.requireBackupBucket();
+		this.requirePresignedUrlSupport();
+		const { id: backupId, dir } = backup;
+		if (!backupId || typeof backupId !== "string") throw new InvalidBackupConfigError({
+			message: "Invalid backup: missing or invalid id",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "missing or invalid id" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		if (!Sandbox.UUID_REGEX.test(backupId)) throw new InvalidBackupConfigError({
+			message: "Invalid backup: id must be a valid UUID (e.g. from createBackup)",
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: "id must be a valid UUID" },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		Sandbox.validateBackupDir(dir, "Invalid backup: dir");
+		this.logger.info("Restoring backup", {
+			backupId,
+			dir
+		});
+		const metaKey = `backups/${backupId}/meta.json`;
+		const metaObject = await bucket.get(metaKey);
+		if (!metaObject) throw new BackupNotFoundError({
+			message: `Backup not found: ${backupId}. Verify the backup ID is correct and the backup has not been deleted.`,
+			code: ErrorCode.BACKUP_NOT_FOUND,
+			httpStatus: 404,
+			context: { backupId },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const metadata = await metaObject.json();
+		const TTL_BUFFER_MS = 60 * 1e3;
+		const createdAt = new Date(metadata.createdAt).getTime();
+		if (Number.isNaN(createdAt)) throw new BackupRestoreError({
+			message: `Backup metadata has invalid createdAt timestamp: ${metadata.createdAt}`,
+			code: ErrorCode.BACKUP_RESTORE_FAILED,
+			httpStatus: 500,
+			context: {
+				dir,
+				backupId
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const expiresAt = createdAt + metadata.ttl * 1e3;
+		if (Date.now() + TTL_BUFFER_MS > expiresAt) throw new BackupExpiredError({
+			message: `Backup ${backupId} has expired (created: ${metadata.createdAt}, TTL: ${metadata.ttl}s). Create a new backup.`,
+			code: ErrorCode.BACKUP_EXPIRED,
+			httpStatus: 400,
+			context: {
+				backupId,
+				expiredAt: new Date(expiresAt).toISOString()
+			},
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const r2Key = `backups/${backupId}/data.sqsh`;
+		const archiveHead = await bucket.head(r2Key);
+		if (!archiveHead) throw new BackupNotFoundError({
+			message: `Backup archive not found in R2: ${backupId}. The archive may have been deleted by R2 lifecycle rules.`,
+			code: ErrorCode.BACKUP_NOT_FOUND,
+			httpStatus: 404,
+			context: { backupId },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const backupSession = await this.ensureBackupSession();
+		const archivePath = `/var/backups/${backupId}.sqsh`;
+		try {
+			const mountGlob = `/var/backups/mounts/${backupId}`;
+			await this.execWithSession(`/usr/bin/fusermount3 -uz ${shellEscape(dir)} 2>/dev/null || true`, backupSession).catch(() => {});
+			await this.execWithSession(`for d in ${shellEscape(mountGlob)}_*/lower ${shellEscape(mountGlob)}/lower; do [ -d "$d" ] && /usr/bin/fusermount3 -uz "$d" 2>/dev/null; done; true`, backupSession).catch(() => {});
+			const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(archivePath)} 2>/dev/null || echo 0`, backupSession).catch(() => ({ stdout: "0" }));
+			if (Number.parseInt((sizeCheck.stdout ?? "0").trim(), 10) !== archiveHead.size) await this.downloadBackupPresigned(archivePath, r2Key, archiveHead.size, backupId, dir, backupSession);
+			if (!(await this.client.backup.restoreArchive(dir, archivePath, backupSession)).success) throw new BackupRestoreError({
+				message: "Container failed to restore backup archive",
+				code: ErrorCode.BACKUP_RESTORE_FAILED,
+				httpStatus: 500,
+				context: {
+					dir,
+					backupId
+				},
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			this.logger.info("Backup restored", {
+				backupId,
+				dir
+			});
+			return {
+				success: true,
+				dir,
+				id: backupId
+			};
+		} catch (error) {
+			await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession).catch(() => {});
+			throw error;
+		}
+	}
 };
 
 //#endregion
@@ -4036,5 +4669,5 @@ async function collectFile(stream) {
 }
 
 //#endregion
-export { BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
+export { BackupClient, BackupCreateError, BackupExpiredError, BackupNotFoundError, BackupRestoreError, BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidBackupConfigError, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.js.map