@cloudflare/sandbox 0.8.4 → 0.8.5

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as CheckChangesOptions, A as DesktopStopResponse, At as SandboxOptions, B as ExecuteResponse, Bt as ExposePortRequest, C as ClickOptions, Ct as ProcessListResult, D as DesktopStartOptions, Dt as ProcessStatus, E as DesktopClient, Et as ProcessStartResult, F as ScreenshotRegion, Ft as WatchOptions, G as HttpClientOptions, Gt as Execution, H as BaseApiResponse, Ht as PtyOptions, I as ScreenshotResponse, It as isExecResult, J as SessionRequest, K as RequestConfig, Kt as ExecutionResult, L as ScrollDirection, Lt as isProcess, M as ScreenSizeResponse, Mt as StreamOptions, N as ScreenshotBytesResponse, Nt as WaitForLogResult, O as DesktopStartResponse, Ot as RemoteMountBucketOptions, P as ScreenshotOptions, Pt as WaitForPortOptions, Q as BucketProvider, R as TypeOptions, Rt as isProcessStatus, S as WriteFileRequest, St as ProcessKillResult, T as Desktop, Tt as ProcessOptions, U as ContainerStub, Ut as CodeContext, V as BackupClient, Vt as StartProcessRequest, W as ErrorResponse, Wt as CreateContextOptions, X as BaseExecOptions, Y as BackupOptions, Z as BucketCredentials, _ as GitClient, _t as PortExposeResult, a as CreateSessionRequest, at as ExecutionSession, b as MkdirRequest, bt as ProcessCleanupResult, c as DeleteSessionResponse, ct as FileStreamEvent, d as ProcessClient, dt as ISandbox, et as CheckChangesResult, f as PortClient, ft as ListFilesOptions, g as GitCheckoutRequest, gt as PortCloseResult, h as InterpreterClient, ht as MountBucketOptions, i as CommandsResponse, it as ExecResult, j as KeyInput, jt as SessionOptions, k as DesktopStatusResponse, kt as RestoreBackupResult, l as PingResponse, lt as FileWatchSSEEvent, m as ExecutionCallbacks, mt as LogEvent, n as getSandbox, nt as ExecEvent, o as CreateSessionResponse, ot as FileChunk, p as UnexposePortRequest, pt as LocalMountBucketOptions, q as ResponseHandler, qt as RunCodeOptions, r as SandboxClient, rt as ExecOptions, s as DeleteSessionRequest, st as FileMetadata, t as Sandbox, tt as DirectoryBackup, u as UtilityClient, ut as GitCheckoutResult, v as FileClient, vt as PortListResult, w as CursorPositionResponse, wt as ProcessLogsResult, x as ReadFileRequest, xt as ProcessInfoResult, y as FileOperationRequest, yt as Process, z as CommandClient, zt as ExecuteRequest } from "./sandbox-BoLbdjOe.js";
+import { $ as CheckChangesOptions, A as DesktopStopResponse, At as SandboxOptions, B as ExecuteResponse, Bt as ExposePortRequest, C as ClickOptions, Ct as ProcessListResult, D as DesktopStartOptions, Dt as ProcessStatus, E as DesktopClient, Et as ProcessStartResult, F as ScreenshotRegion, Ft as WatchOptions, G as HttpClientOptions, Gt as Execution, H as BaseApiResponse, Ht as PtyOptions, I as ScreenshotResponse, It as isExecResult, J as SessionRequest, K as RequestConfig, Kt as ExecutionResult, L as ScrollDirection, Lt as isProcess, M as ScreenSizeResponse, Mt as StreamOptions, N as ScreenshotBytesResponse, Nt as WaitForLogResult, O as DesktopStartResponse, Ot as RemoteMountBucketOptions, P as ScreenshotOptions, Pt as WaitForPortOptions, Q as BucketProvider, R as TypeOptions, Rt as isProcessStatus, S as WriteFileRequest, St as ProcessKillResult, T as Desktop, Tt as ProcessOptions, U as ContainerStub, Ut as CodeContext, V as BackupClient, Vt as StartProcessRequest, W as ErrorResponse, Wt as CreateContextOptions, X as BaseExecOptions, Y as BackupOptions, Z as BucketCredentials, _ as GitClient, _t as PortExposeResult, a as CreateSessionRequest, at as ExecutionSession, b as MkdirRequest, bt as ProcessCleanupResult, c as DeleteSessionResponse, ct as FileStreamEvent, d as ProcessClient, dt as ISandbox, et as CheckChangesResult, f as PortClient, ft as ListFilesOptions, g as GitCheckoutRequest, gt as PortCloseResult, h as InterpreterClient, ht as MountBucketOptions, i as CommandsResponse, it as ExecResult, j as KeyInput, jt as SessionOptions, k as DesktopStatusResponse, kt as RestoreBackupResult, l as PingResponse, lt as FileWatchSSEEvent, m as ExecutionCallbacks, mt as LogEvent, n as getSandbox, nt as ExecEvent, o as CreateSessionResponse, ot as FileChunk, p as UnexposePortRequest, pt as LocalMountBucketOptions, q as ResponseHandler, qt as RunCodeOptions, r as SandboxClient, rt as ExecOptions, s as DeleteSessionRequest, st as FileMetadata, t as Sandbox, tt as DirectoryBackup, u as UtilityClient, ut as GitCheckoutResult, v as FileClient, vt as PortListResult, w as CursorPositionResponse, wt as ProcessLogsResult, x as ReadFileRequest, xt as ProcessInfoResult, y as FileOperationRequest, yt as Process, z as CommandClient, zt as ExecuteRequest } from "./sandbox-DW5aQ1lD.js";
 import { a as DesktopCoordinateErrorContext, d as ErrorResponse$1, f as OperationType, i as BackupRestoreContext, l as ProcessExitedBeforeReadyContext, n as BackupExpiredContext, o as DesktopErrorContext, p as ErrorCode, r as BackupNotFoundContext, s as InvalidBackupConfigContext, t as BackupCreateContext, u as ProcessReadyTimeoutContext } from "./contexts-CeQR115r.js";
 import { ContainerProxy } from "@cloudflare/containers";
 

package/dist/index.js

@@ -2813,6 +2813,19 @@ var SandboxClient = class {
 	}
 };
 
+//#endregion
+//#region ../shared/src/backup.ts
+/**
+* Absolute directory prefixes supported by backup and restore operations.
+*/
+const BACKUP_ALLOWED_PREFIXES = [
+	"/workspace",
+	"/home",
+	"/tmp",
+	"/var/tmp",
+	"/app"
+];
+
 //#endregion
 //#region src/security.ts
 /**
@@ -3632,7 +3645,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.8.4";
+const SDK_VERSION = "0.8.5";
 
 //#endregion
 //#region src/sandbox.ts
@@ -5554,7 +5567,7 @@ var Sandbox = class Sandbox extends Container {
 	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.
+	* Rejects empty, relative, traversal, null-byte, and unsupported-root paths.
 	*/
 	static validateBackupDir(dir, label) {
 		if (!dir || !dir.startsWith("/")) throw new InvalidBackupConfigError({
@@ -5578,6 +5591,13 @@ var Sandbox = class Sandbox extends Container {
 			context: { reason: `${label} must not contain ".." path segments` },
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
+		if (!BACKUP_ALLOWED_PREFIXES.some((prefix) => dir === prefix || dir.startsWith(`${prefix}/`))) throw new InvalidBackupConfigError({
+			message: `${label} must be inside one of the supported backup roots (${BACKUP_ALLOWED_PREFIXES.join(", ")})`,
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: `${label} must be inside one of the supported backup roots` },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
 	}
 	/**
 	* Returns the R2 bucket or throws if backup is not configured.
@@ -5948,19 +5968,19 @@ var Sandbox = class Sandbox extends Container {
 		const restoreStartTime = Date.now();
 		const bucket = this.requireBackupBucket();
 		this.requirePresignedUrlSupport();
-		const { id: backupId, dir } = backup;
+		const { id, dir } = backup;
 		let outcome = "error";
 		let caughtError;
 		let backupSession;
 		try {
-			if (!backupId || typeof backupId !== "string") throw new InvalidBackupConfigError({
+			if (!id || typeof id !== "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({
+			if (!Sandbox.UUID_REGEX.test(id)) throw new InvalidBackupConfigError({
 				message: "Invalid backup: id must be a valid UUID (e.g. from createBackup)",
 				code: ErrorCode.INVALID_BACKUP_CONFIG,
 				httpStatus: 400,
@@ -5968,13 +5988,13 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			Sandbox.validateBackupDir(dir, "Invalid backup: dir");
-			const metaKey = `backups/${backupId}/meta.json`;
+			const metaKey = `backups/${id}/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.`,
+				message: `Backup not found: ${id}. Verify the backup ID is correct and the backup has not been deleted.`,
 				code: ErrorCode.BACKUP_NOT_FOUND,
 				httpStatus: 404,
-				context: { backupId },
+				context: { backupId: id },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			const metadata = await metaObject.json();
@@ -5986,44 +6006,44 @@ var Sandbox = class Sandbox extends Container {
 				httpStatus: 500,
 				context: {
 					dir,
-					backupId
+					backupId: id
 				},
 				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.`,
+				message: `Backup ${id} has expired (created: ${metadata.createdAt}, TTL: ${metadata.ttl}s). Create a new backup.`,
 				code: ErrorCode.BACKUP_EXPIRED,
 				httpStatus: 400,
 				context: {
-					backupId,
+					backupId: id,
 					expiredAt: new Date(expiresAt).toISOString()
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			const r2Key = `backups/${backupId}/data.sqsh`;
+			const r2Key = `backups/${id}/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.`,
+				message: `Backup archive not found in R2: ${id}. The archive may have been deleted by R2 lifecycle rules.`,
 				code: ErrorCode.BACKUP_NOT_FOUND,
 				httpStatus: 404,
-				context: { backupId },
+				context: { backupId: id },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			backupSession = await this.ensureBackupSession();
-			const archivePath = `/var/backups/${backupId}.sqsh`;
-			const mountGlob = `/var/backups/mounts/${backupId}`;
+			const archivePath = `/var/backups/${id}.sqsh`;
+			const mountGlob = `/var/backups/mounts/${id}`;
 			await this.execWithSession(`/usr/bin/fusermount3 -uz ${shellEscape(dir)} 2>/dev/null || true`, backupSession, { origin: "internal" }).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, { origin: "internal" }).catch(() => {});
 			const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(archivePath)} 2>/dev/null || echo 0`, backupSession, { origin: "internal" }).catch(() => ({ stdout: "0" }));
-			if (Number.parseInt((sizeCheck.stdout ?? "0").trim(), 10) !== archiveHead.size) await this.downloadBackupPresigned(archivePath, r2Key, archiveHead.size, backupId, dir, backupSession);
+			if (Number.parseInt((sizeCheck.stdout ?? "0").trim(), 10) !== archiveHead.size) await this.downloadBackupPresigned(archivePath, r2Key, archiveHead.size, id, 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
+					backupId: id
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
@@ -6031,12 +6051,12 @@ var Sandbox = class Sandbox extends Container {
 			return {
 				success: true,
 				dir,
-				id: backupId
+				id
 			};
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
-			if (backupId && backupSession) {
-				const archivePath = `/var/backups/${backupId}.sqsh`;
+			if (id && backupSession) {
+				const archivePath = `/var/backups/${id}.sqsh`;
 				await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
 			}
 			throw error;
@@ -6046,7 +6066,7 @@ var Sandbox = class Sandbox extends Container {
 				event: "backup.restore",
 				outcome,
 				durationMs: Date.now() - restoreStartTime,
-				backupId,
+				backupId: id,
 				dir,
 				error: caughtError
 			});