@zero-transfer/sdk 0.4.0 → 0.4.6

package/dist/index.mjs

@@ -6104,7 +6104,7 @@ var SshTransportPacketUnprotector = class {
   }
   /**
    * Feeds raw encrypted bytes from the socket and returns any fully decoded payloads.
-   * Maintains internal framing state across calls — pass each `data` event chunk directly.
+   * Maintains internal framing state across calls - pass each `data` event chunk directly.
    */
   pushBytes(chunk) {
     this.framePendingRaw = Buffer16.concat([this.framePendingRaw, chunk]);
@@ -6612,7 +6612,7 @@ var SshTransportConnection = class {
   assertConnected() {
     if (!this.connected) {
       throw new ProtocolError({
-        message: "SshTransportConnection is not yet connected \u2014 call connect() first",
+        message: "SshTransportConnection is not yet connected - call connect() first",
         protocol: "sftp",
         retryable: false
       });
@@ -6952,14 +6952,14 @@ function sftpStatusToError(status, path2) {
     case SFTP_STATUS.NO_SUCH_FILE:
       return new PathNotFoundError({
         details: { path: path2, sftpMessage: status.errorMessage },
-        message: `SFTP: no such file or directory${path2 !== void 0 ? ` \u2014 ${path2}` : ""}`,
+        message: `SFTP: no such file or directory${path2 !== void 0 ? ` - ${path2}` : ""}`,
         protocol: "sftp",
         retryable: false
       });
     case SFTP_STATUS.PERMISSION_DENIED:
       return new PermissionDeniedError({
         details: { path: path2, sftpMessage: status.errorMessage },
-        message: `SFTP: permission denied${path2 !== void 0 ? ` \u2014 ${path2}` : ""}`,
+        message: `SFTP: permission denied${path2 !== void 0 ? ` - ${path2}` : ""}`,
         protocol: "sftp",
         retryable: false
       });
@@ -6967,21 +6967,21 @@ function sftpStatusToError(status, path2) {
     case SFTP_STATUS.CONNECTION_LOST:
       return new ConnectionError({
         details: { sftpMessage: status.errorMessage, statusCode: status.statusCode },
-        message: `SFTP: connection error \u2014 ${status.errorMessage}`,
+        message: `SFTP: connection error - ${status.errorMessage}`,
         protocol: "sftp",
         retryable: true
       });
     case SFTP_STATUS.OP_UNSUPPORTED:
       return new UnsupportedFeatureError({
         details: { sftpMessage: status.errorMessage },
-        message: `SFTP: operation unsupported \u2014 ${status.errorMessage}`,
+        message: `SFTP: operation unsupported - ${status.errorMessage}`,
         protocol: "sftp",
         retryable: false
       });
     case SFTP_STATUS.BAD_MESSAGE:
       return new ProtocolError({
         details: { sftpMessage: status.errorMessage },
-        message: `SFTP: bad message \u2014 ${status.errorMessage}`,
+        message: `SFTP: bad message - ${status.errorMessage}`,
         protocol: "sftp",
         retryable: false
       });
@@ -6989,7 +6989,7 @@ function sftpStatusToError(status, path2) {
       return new ZeroTransferError({
         code: "SFTP_FAILURE",
         details: { sftpMessage: status.errorMessage, statusCode: status.statusCode },
-        message: `SFTP: operation failed (status ${status.statusCode}) \u2014 ${status.errorMessage}`,
+        message: `SFTP: operation failed (status ${status.statusCode}) - ${status.errorMessage}`,
         protocol: "sftp",
         retryable: false
       });
@@ -9092,6 +9092,9 @@ function concatChunks(chunks, totalSize) {
 // src/providers/cloud/OneDriveProvider.ts
 var ONEDRIVE_DRIVE_BASE = "https://graph.microsoft.com/v1.0/me/drive";
 var ONEDRIVE_CHECKSUM_CAPABILITIES = ["sha1", "sha256", "quickxorhash"];
+var ONEDRIVE_CHUNK_ALIGNMENT = 320 * 1024;
+var DEFAULT_ONEDRIVE_PART_SIZE = 10 * 1024 * 1024;
+var DEFAULT_ONEDRIVE_THRESHOLD = 4 * 1024 * 1024;
 function createOneDriveProviderFactory(options = {}) {
   const id = options.id ?? "one-drive";
   const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -9102,6 +9105,37 @@ function createOneDriveProviderFactory(options = {}) {
       retryable: false
     });
   }
+  const multipartEnabled = options.multipart?.enabled ?? true;
+  const partSizeBytes = options.multipart?.partSizeBytes ?? DEFAULT_ONEDRIVE_PART_SIZE;
+  const thresholdBytes = options.multipart?.thresholdBytes ?? DEFAULT_ONEDRIVE_THRESHOLD;
+  if (multipartEnabled) {
+    if (!Number.isInteger(partSizeBytes) || partSizeBytes <= 0) {
+      throw new ConfigurationError({
+        details: { partSizeBytes },
+        message: "OneDriveMultipartOptions.partSizeBytes must be a positive integer",
+        retryable: false
+      });
+    }
+    if (partSizeBytes % ONEDRIVE_CHUNK_ALIGNMENT !== 0) {
+      throw new ConfigurationError({
+        details: { partSizeBytes },
+        message: `OneDrive multipart partSizeBytes must be a multiple of ${String(ONEDRIVE_CHUNK_ALIGNMENT)} bytes (320 KiB)`,
+        retryable: false
+      });
+    }
+    if (!Number.isInteger(thresholdBytes) || thresholdBytes < 0) {
+      throw new ConfigurationError({
+        details: { thresholdBytes },
+        message: "OneDriveMultipartOptions.thresholdBytes must be a non-negative integer",
+        retryable: false
+      });
+    }
+  }
+  const multipart = {
+    enabled: multipartEnabled,
+    partSizeBytes,
+    thresholdBytes
+  };
   const capabilities = {
     atomicRename: false,
     authentication: ["token", "oauth"],
@@ -9111,13 +9145,17 @@ function createOneDriveProviderFactory(options = {}) {
     list: true,
     maxConcurrency: 4,
     metadata: ["modifiedAt", "createdAt", "uniqueId"],
-    notes: [
-      "OneDrive provider performs single-shot uploads via PUT /content; resumable upload sessions are not yet supported."
+    notes: multipartEnabled ? [
+      `OneDrive upload session enabled by default (partSize=${String(multipart.partSizeBytes)}B, threshold=${String(multipart.thresholdBytes)}B).`,
+      "Payloads at or below the threshold automatically fall back to single-shot PUT /content.",
+      "Pass `multipart: { enabled: false }` to force the legacy single-shot behaviour."
+    ] : [
+      "OneDrive provider performs single-shot uploads via PUT /content; resumable upload sessions are disabled."
     ],
     provider: id,
     readStream: true,
     resumeDownload: true,
-    resumeUpload: false,
+    resumeUpload: multipartEnabled,
     serverSideCopy: false,
     serverSideMove: false,
     stat: true,
@@ -9131,7 +9169,8 @@ function createOneDriveProviderFactory(options = {}) {
       defaultHeaders: { ...options.defaultHeaders ?? {} },
       driveBaseUrl,
       fetch: fetchImpl,
-      id
+      id,
+      multipart
     }),
     id
   };
@@ -9165,6 +9204,7 @@ var OneDriveProvider = class {
       driveBaseUrl: this.internals.driveBaseUrl,
       fetch: this.internals.fetch,
       id: this.internals.id,
+      multipart: this.internals.multipart,
       token
     };
     if (profile.timeoutMs !== void 0) sessionOptions.timeoutMs = profile.timeoutMs;
@@ -9268,12 +9308,19 @@ var OneDriveTransferOperations = class {
     if (request.offset !== void 0 && request.offset > 0) {
       throw new UnsupportedFeatureError({
         details: { offset: request.offset },
-        message: "OneDrive provider does not yet support resumable upload sessions",
+        message: "OneDrive provider does not yet support cross-attempt resume of upload sessions",
         retryable: false
       });
     }
     const normalized = normalizeRemotePath(request.endpoint.path);
+    const multipart = this.options.multipart;
     const buffered = await collectChunks3(request.content);
+    if (!multipart.enabled || buffered.byteLength <= multipart.thresholdBytes) {
+      return this.singleShotPut(request, normalized, buffered);
+    }
+    return this.writeUploadSession(request, normalized, buffered);
+  }
+  async singleShotPut(request, normalized, buffered) {
     const url = `${this.options.driveBaseUrl}${itemSegment(normalized)}/content`;
     const response = await graphFetch(this.options, "PUT", url, {
       ...request.signal !== void 0 ? { signal: request.signal } : {},
@@ -9293,6 +9340,77 @@ var OneDriveTransferOperations = class {
     if (checksum !== void 0) result.checksum = checksum;
     return result;
   }
+  async writeUploadSession(request, normalized, buffered) {
+    const partSize = this.options.multipart.partSizeBytes;
+    const total = buffered.byteLength;
+    const sessionUrl = `${this.options.driveBaseUrl}${itemSegment(normalized)}/createUploadSession`;
+    const initiate = await graphFetch(this.options, "POST", sessionUrl, {
+      ...request.signal !== void 0 ? { signal: request.signal } : {},
+      body: new TextEncoder().encode(
+        JSON.stringify({ item: { "@microsoft.graph.conflictBehavior": "replace" } })
+      ),
+      extraHeaders: { "content-type": "application/json" }
+    });
+    if (!initiate.ok) {
+      throw mapOneDriveResponseError(initiate, normalized, await safeReadText3(initiate));
+    }
+    const initiateBody = await initiate.json();
+    const uploadUrl = initiateBody.uploadUrl;
+    if (typeof uploadUrl !== "string" || uploadUrl === "") {
+      throw new ConnectionError({
+        details: { path: normalized },
+        message: "OneDrive createUploadSession returned no uploadUrl",
+        retryable: true
+      });
+    }
+    let bytesTransferred = 0;
+    let finalItem;
+    try {
+      while (bytesTransferred < total) {
+        request.throwIfAborted();
+        const chunkEnd = Math.min(bytesTransferred + partSize, total);
+        const chunk = buffered.subarray(bytesTransferred, chunkEnd);
+        const response = await graphSessionFetch(this.options, uploadUrl, {
+          ...request.signal !== void 0 ? { signal: request.signal } : {},
+          body: chunk,
+          extraHeaders: {
+            "content-length": String(chunk.byteLength),
+            "content-range": `bytes ${String(bytesTransferred)}-${String(chunkEnd - 1)}/${String(total)}`,
+            "content-type": "application/octet-stream"
+          }
+        });
+        if (response.status === 202) {
+          bytesTransferred = chunkEnd;
+          request.reportProgress(bytesTransferred, total);
+          continue;
+        }
+        if (response.status === 200 || response.status === 201) {
+          bytesTransferred = chunkEnd;
+          request.reportProgress(bytesTransferred, total);
+          finalItem = await response.json();
+          break;
+        }
+        throw mapOneDriveResponseError(response, normalized, await safeReadText3(response));
+      }
+    } catch (error) {
+      void graphSessionFetch(this.options, uploadUrl, { method: "DELETE" }).catch(() => void 0);
+      throw error;
+    }
+    if (finalItem === void 0) {
+      throw new ConnectionError({
+        details: { path: normalized },
+        message: "OneDrive upload session did not return a final DriveItem",
+        retryable: true
+      });
+    }
+    const result = {
+      bytesTransferred,
+      totalBytes: bytesTransferred
+    };
+    const checksum = preferHash(finalItem.file?.hashes);
+    if (checksum !== void 0) result.checksum = checksum;
+    return result;
+  }
   async fetchItem(normalized) {
     const url = `${this.options.driveBaseUrl}${itemSegment(normalized)}`;
     const response = await graphFetch(this.options, "GET", url);
@@ -9339,6 +9457,45 @@ async function graphFetch(options, method, url, fetchOptions = {}) {
     if (timer !== void 0) clearTimeout(timer);
   }
 }
+async function graphSessionFetch(options, uploadUrl, fetchOptions = {}) {
+  const headers = {
+    ...fetchOptions.extraHeaders ?? {}
+  };
+  const init = { headers, method: fetchOptions.method ?? "PUT" };
+  if (fetchOptions.body !== void 0) {
+    init.body = fetchOptions.body;
+  }
+  const controller = new AbortController();
+  const upstream = fetchOptions.signal ?? null;
+  if (upstream !== null) {
+    if (upstream.aborted) controller.abort(upstream.reason);
+    else upstream.addEventListener("abort", () => controller.abort(upstream.reason));
+  }
+  let timer;
+  if (options.timeoutMs !== void 0 && options.timeoutMs > 0) {
+    timer = setTimeout(
+      () => controller.abort(new Error("OneDrive upload session request timed out")),
+      options.timeoutMs
+    );
+  }
+  try {
+    return await options.fetch(uploadUrl, { ...init, signal: controller.signal });
+  } catch (error) {
+    const safeUrl = redactSessionUrl(uploadUrl);
+    throw new ConnectionError({
+      cause: error,
+      details: { url: safeUrl },
+      message: `OneDrive upload session request to ${safeUrl} failed`,
+      retryable: true
+    });
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+function redactSessionUrl(url) {
+  const queryStart = url.indexOf("?");
+  return queryStart === -1 ? url : `${url.slice(0, queryStart)}?<redacted>`;
+}
 function mapOneDriveResponseError(response, contextPath, bodyText) {
   const details = {
     bodyText: bodyText.slice(0, 500),
@@ -9460,8 +9617,12 @@ async function collectChunks3(source) {
 }
 
 // src/providers/cloud/AzureBlobProvider.ts
+import { randomBytes as cryptoRandomBytes } from "crypto";
 var AZURE_BLOB_API_VERSION = "2023-11-03";
 var AZURE_CHECKSUM_CAPABILITIES = ["md5"];
+var DEFAULT_AZURE_PART_SIZE = 8 * 1024 * 1024;
+var DEFAULT_AZURE_THRESHOLD = 8 * 1024 * 1024;
+var AZURE_MAX_PART_SIZE = 4e3 * 1024 * 1024;
 function createAzureBlobProviderFactory(options) {
   if (typeof options.container !== "string" || options.container === "") {
     throw new ConfigurationError({
@@ -9479,6 +9640,37 @@ function createAzureBlobProviderFactory(options) {
   }
   const endpoint = resolveAzureEndpoint(options);
   const apiVersion = options.apiVersion ?? AZURE_BLOB_API_VERSION;
+  const multipartEnabled = options.multipart?.enabled ?? true;
+  const partSizeBytes = options.multipart?.partSizeBytes ?? DEFAULT_AZURE_PART_SIZE;
+  const thresholdBytes = options.multipart?.thresholdBytes ?? DEFAULT_AZURE_THRESHOLD;
+  if (multipartEnabled) {
+    if (!Number.isInteger(partSizeBytes) || partSizeBytes <= 0) {
+      throw new ConfigurationError({
+        details: { partSizeBytes },
+        message: "AzureBlobMultipartOptions.partSizeBytes must be a positive integer",
+        retryable: false
+      });
+    }
+    if (partSizeBytes > AZURE_MAX_PART_SIZE) {
+      throw new ConfigurationError({
+        details: { maxBytes: AZURE_MAX_PART_SIZE, partSizeBytes },
+        message: `AzureBlobMultipartOptions.partSizeBytes must not exceed ${String(AZURE_MAX_PART_SIZE)} bytes (4000 MiB)`,
+        retryable: false
+      });
+    }
+    if (!Number.isInteger(thresholdBytes) || thresholdBytes < 0) {
+      throw new ConfigurationError({
+        details: { thresholdBytes },
+        message: "AzureBlobMultipartOptions.thresholdBytes must be a non-negative integer",
+        retryable: false
+      });
+    }
+  }
+  const multipart = {
+    enabled: multipartEnabled,
+    partSizeBytes,
+    thresholdBytes
+  };
   const capabilities = {
     atomicRename: false,
     authentication: ["token", "oauth"],
@@ -9488,13 +9680,17 @@ function createAzureBlobProviderFactory(options) {
     list: true,
     maxConcurrency: 4,
     metadata: ["modifiedAt", "uniqueId"],
-    notes: [
-      "Azure Blob provider performs single-shot block-blob uploads via PUT; staged-block + Put Block List uploads are not yet supported."
+    notes: multipartEnabled ? [
+      `Azure Blob staged-block upload enabled by default (partSize=${String(multipart.partSizeBytes)}B, threshold=${String(multipart.thresholdBytes)}B).`,
+      "Payloads at or below the threshold automatically fall back to single-shot block-blob PUT.",
+      "Pass `multipart: { enabled: false }` to force the legacy single-shot behaviour."
+    ] : [
+      "Azure Blob provider performs single-shot block-blob uploads via PUT; entire object is buffered in memory before transmission."
     ],
     provider: id,
     readStream: true,
     resumeDownload: true,
-    resumeUpload: false,
+    resumeUpload: multipartEnabled,
     serverSideCopy: false,
     serverSideMove: false,
     stat: true,
@@ -9511,6 +9707,7 @@ function createAzureBlobProviderFactory(options) {
       endpoint,
       fetch: fetchImpl,
       id,
+      multipart,
       ...options.sasToken !== void 0 ? { sasToken: options.sasToken } : {}
     }),
     id
@@ -9556,7 +9753,8 @@ var AzureBlobProvider = class {
       defaultHeaders: this.internals.defaultHeaders,
       endpoint: this.internals.endpoint,
       fetch: this.internals.fetch,
-      id: this.internals.id
+      id: this.internals.id,
+      multipart: this.internals.multipart
     };
     if (bearerToken !== void 0) sessionOptions.bearerToken = bearerToken;
     if (this.internals.sasToken !== void 0) sessionOptions.sasToken = this.internals.sasToken;
@@ -9691,12 +9889,19 @@ var AzureBlobTransferOperations = class {
     if (request.offset !== void 0 && request.offset > 0) {
       throw new UnsupportedFeatureError({
         details: { offset: request.offset },
-        message: "Azure Blob provider does not yet support staged-block resumable uploads",
+        message: "Azure Blob provider does not yet support cross-attempt resume of staged-block uploads",
         retryable: false
       });
     }
     const normalized = normalizeRemotePath(request.endpoint.path);
-    const buffered = await collectChunks4(request.content);
+    const multipart = this.options.multipart;
+    if (!multipart.enabled) {
+      const buffered = await collectChunks4(request.content);
+      return this.singleShotPut(request, normalized, buffered);
+    }
+    return this.writeStagedBlocks(request, normalized);
+  }
+  async singleShotPut(request, normalized, buffered) {
     const url = buildBlobUrl(this.options, normalized);
     const response = await azureFetch(this.options, "PUT", url, {
       ...request.signal !== void 0 ? { signal: request.signal } : {},
@@ -9718,6 +9923,92 @@ var AzureBlobTransferOperations = class {
     if (md5 !== null && md5 !== "") result.checksum = md5;
     return result;
   }
+  async writeStagedBlocks(request, normalized) {
+    const multipart = this.options.multipart;
+    const partSize = multipart.partSizeBytes;
+    const iterator = request.content[Symbol.asyncIterator]();
+    const uploadNonce = generateUploadNonce();
+    const initialBuffer = [];
+    let initialSize = 0;
+    while (initialSize <= multipart.thresholdBytes) {
+      const next = await iterator.next();
+      if (next.done === true) break;
+      const chunk = next.value;
+      if (chunk.byteLength === 0) continue;
+      initialBuffer.push(chunk);
+      initialSize += chunk.byteLength;
+    }
+    if (initialSize <= multipart.thresholdBytes) {
+      return this.singleShotPut(request, normalized, concatChunks2(initialBuffer, initialSize));
+    }
+    const blockIds = [];
+    let bytesTransferred = 0;
+    let partNumber = 1;
+    let buffer = [...initialBuffer];
+    let bufferSize = initialSize;
+    const flushBlocks = async (final) => {
+      while (bufferSize >= partSize || final && bufferSize > 0) {
+        const take = Math.min(bufferSize, partSize);
+        const sliced = sliceFromBuffers(buffer, take);
+        buffer = sliced.remaining;
+        bufferSize -= sliced.bytes.byteLength;
+        const blockId = encodeBlockId(uploadNonce, partNumber);
+        const blockUrl = buildBlobUrl(this.options, normalized, {
+          blockid: blockId,
+          comp: "block"
+        });
+        const response = await azureFetch(this.options, "PUT", blockUrl, {
+          ...request.signal !== void 0 ? { signal: request.signal } : {},
+          body: sliced.bytes,
+          extraHeaders: { "content-type": "application/octet-stream" }
+        });
+        if (!response.ok) {
+          throw mapAzureResponseError(response, normalized, await safeReadText4(response));
+        }
+        blockIds.push(blockId);
+        bytesTransferred += sliced.bytes.byteLength;
+        request.reportProgress(bytesTransferred, void 0);
+        partNumber += 1;
+      }
+    };
+    await flushBlocks(false);
+    while (true) {
+      request.throwIfAborted();
+      const next = await iterator.next();
+      if (next.done === true) break;
+      if (next.value.byteLength === 0) continue;
+      buffer.push(next.value);
+      bufferSize += next.value.byteLength;
+      await flushBlocks(false);
+    }
+    await flushBlocks(true);
+    if (blockIds.length === 0) {
+      throw new ConnectionError({
+        message: "Azure Blob staged-block upload completed with zero blocks",
+        retryable: false
+      });
+    }
+    const commitUrl = buildBlobUrl(this.options, normalized, { comp: "blocklist" });
+    const xmlBody = buildBlockListXml(blockIds);
+    const commitResponse = await azureFetch(this.options, "PUT", commitUrl, {
+      ...request.signal !== void 0 ? { signal: request.signal } : {},
+      body: new TextEncoder().encode(xmlBody),
+      extraHeaders: {
+        "content-type": "application/xml",
+        "x-ms-blob-content-type": "application/octet-stream"
+      }
+    });
+    if (!commitResponse.ok) {
+      throw mapAzureResponseError(commitResponse, normalized, await safeReadText4(commitResponse));
+    }
+    const result = {
+      bytesTransferred,
+      totalBytes: bytesTransferred
+    };
+    const md5 = commitResponse.headers.get("content-md5");
+    if (md5 !== null && md5 !== "") result.checksum = md5;
+    return result;
+  }
 };
 async function azureFetch(options, method, url, fetchOptions = {}) {
   const headers = {
@@ -9763,14 +10054,17 @@ function buildContainerUrl(options, params) {
   appendSas(search, options.sasToken);
   return `${options.endpoint}/${encodeURIComponent(options.container)}?${search.toString()}`;
 }
-function buildBlobUrl(options, normalized) {
+function buildBlobUrl(options, normalized, extraParams) {
   const blobPath = normalized.replace(/^\/+/u, "");
   const encoded = blobPath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
   const base = `${options.endpoint}/${encodeURIComponent(options.container)}/${encoded}`;
-  if (options.sasToken !== void 0 && options.sasToken !== "") {
-    return `${base}?${options.sasToken}`;
+  const search = new URLSearchParams();
+  if (extraParams !== void 0) {
+    for (const [k, v] of Object.entries(extraParams)) search.set(k, v);
   }
-  return base;
+  appendSas(search, options.sasToken);
+  const query = search.toString();
+  return query === "" ? base : `${base}?${query}`;
 }
 function appendSas(search, sasToken) {
   if (sasToken === void 0 || sasToken === "") return;
@@ -9922,11 +10216,63 @@ async function collectChunks4(source) {
   }
   return out;
 }
+function concatChunks2(chunks, totalSize) {
+  const out = new Uint8Array(totalSize);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+function sliceFromBuffers(buffers, size) {
+  const out = new Uint8Array(size);
+  let offset = 0;
+  let i = 0;
+  while (offset < size && i < buffers.length) {
+    const chunk = buffers[i];
+    if (chunk === void 0) {
+      i += 1;
+      continue;
+    }
+    const remaining = size - offset;
+    if (chunk.byteLength <= remaining) {
+      out.set(chunk, offset);
+      offset += chunk.byteLength;
+      i += 1;
+    } else {
+      out.set(chunk.subarray(0, remaining), offset);
+      const leftover = chunk.subarray(remaining);
+      const next = buffers.slice(i + 1);
+      next.unshift(leftover);
+      return { bytes: out, remaining: next };
+    }
+  }
+  return { bytes: out.subarray(0, offset), remaining: buffers.slice(i) };
+}
+function encodeBlockId(nonce, partNumber) {
+  const padded = String(partNumber).padStart(9, "0");
+  const raw = `${nonce}-${padded}`;
+  return Buffer.from(raw, "utf8").toString("base64");
+}
+function generateUploadNonce() {
+  return cryptoRandomBytes(4).toString("hex");
+}
+function buildBlockListXml(blockIds) {
+  const items = blockIds.map((id) => `<Latest>${escapeXml(id)}</Latest>`).join("");
+  return `<?xml version="1.0" encoding="utf-8"?><BlockList>${items}</BlockList>`;
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
 
 // src/providers/cloud/GcsProvider.ts
 var GCS_JSON_API_BASE = "https://storage.googleapis.com/storage/v1";
 var GCS_UPLOAD_API_BASE = "https://storage.googleapis.com/upload/storage/v1";
 var GCS_CHECKSUM_CAPABILITIES = ["md5", "crc32c"];
+var GCS_CHUNK_ALIGNMENT = 256 * 1024;
+var DEFAULT_GCS_PART_SIZE = 8 * 1024 * 1024;
+var DEFAULT_GCS_THRESHOLD = 8 * 1024 * 1024;
 function createGcsProviderFactory(options) {
   if (typeof options.bucket !== "string" || options.bucket === "") {
     throw new ConfigurationError({
@@ -9944,6 +10290,37 @@ function createGcsProviderFactory(options) {
   }
   const apiBaseUrl = (options.apiBaseUrl ?? GCS_JSON_API_BASE).replace(/\/+$/u, "");
   const uploadBaseUrl = (options.uploadBaseUrl ?? GCS_UPLOAD_API_BASE).replace(/\/+$/u, "");
+  const multipartEnabled = options.multipart?.enabled ?? true;
+  const partSizeBytes = options.multipart?.partSizeBytes ?? DEFAULT_GCS_PART_SIZE;
+  const thresholdBytes = options.multipart?.thresholdBytes ?? DEFAULT_GCS_THRESHOLD;
+  if (multipartEnabled) {
+    if (!Number.isInteger(partSizeBytes) || partSizeBytes <= 0) {
+      throw new ConfigurationError({
+        details: { partSizeBytes },
+        message: "GcsMultipartOptions.partSizeBytes must be a positive integer",
+        retryable: false
+      });
+    }
+    if (partSizeBytes % GCS_CHUNK_ALIGNMENT !== 0) {
+      throw new ConfigurationError({
+        details: { partSizeBytes },
+        message: `GCS multipart partSizeBytes must be a multiple of ${String(GCS_CHUNK_ALIGNMENT)} bytes (256 KiB)`,
+        retryable: false
+      });
+    }
+    if (!Number.isInteger(thresholdBytes) || thresholdBytes < 0) {
+      throw new ConfigurationError({
+        details: { thresholdBytes },
+        message: "GcsMultipartOptions.thresholdBytes must be a non-negative integer",
+        retryable: false
+      });
+    }
+  }
+  const multipart = {
+    enabled: multipartEnabled,
+    partSizeBytes,
+    thresholdBytes
+  };
   const capabilities = {
     atomicRename: false,
     authentication: ["token", "oauth"],
@@ -9953,13 +10330,17 @@ function createGcsProviderFactory(options) {
     list: true,
     maxConcurrency: 4,
     metadata: ["modifiedAt", "createdAt", "uniqueId"],
-    notes: [
-      "GCS provider performs single-shot media uploads via /upload?uploadType=media; resumable upload sessions are not yet supported."
+    notes: multipartEnabled ? [
+      `GCS resumable-upload session enabled by default (partSize=${String(multipart.partSizeBytes)}B, threshold=${String(multipart.thresholdBytes)}B).`,
+      "Payloads at or below the threshold automatically fall back to single-shot uploadType=media POST.",
+      "Pass `multipart: { enabled: false }` to force the legacy single-shot behaviour."
+    ] : [
+      "GCS provider performs single-shot media uploads via /upload?uploadType=media; resumable upload sessions are disabled."
     ],
     provider: id,
     readStream: true,
     resumeDownload: true,
-    resumeUpload: false,
+    resumeUpload: multipartEnabled,
     serverSideCopy: false,
     serverSideMove: false,
     stat: true,
@@ -9975,6 +10356,7 @@ function createGcsProviderFactory(options) {
       defaultHeaders: { ...options.defaultHeaders ?? {} },
       fetch: fetchImpl,
       id,
+      multipart,
       uploadBaseUrl
     }),
     id
@@ -10010,6 +10392,7 @@ var GcsProvider = class {
       defaultHeaders: this.internals.defaultHeaders,
       fetch: this.internals.fetch,
       id: this.internals.id,
+      multipart: this.internals.multipart,
       token,
       uploadBaseUrl: this.internals.uploadBaseUrl
     };
@@ -10131,13 +10514,20 @@ var GcsTransferOperations = class {
     if (request.offset !== void 0 && request.offset > 0) {
       throw new UnsupportedFeatureError({
         details: { offset: request.offset },
-        message: "GCS provider does not yet support resumable upload sessions",
+        message: "GCS provider does not yet support cross-attempt resume of upload sessions",
         retryable: false
       });
     }
     const normalized = normalizeRemotePath(request.endpoint.path);
     const objectName = toGcsObjectName(normalized);
-    const buffered = await collectChunks5(request.content);
+    const multipart = this.options.multipart;
+    if (!multipart.enabled) {
+      const buffered = await collectChunks5(request.content);
+      return this.singleShotMedia(request, normalized, objectName, buffered);
+    }
+    return this.writeResumableSession(request, normalized, objectName);
+  }
+  async singleShotMedia(request, normalized, objectName, buffered) {
     const url = `${this.options.uploadBaseUrl}/b/${encodeURIComponent(this.options.bucket)}/o?uploadType=media&name=${encodeURIComponent(objectName)}`;
     const response = await gcsFetch(this.options, "POST", url, {
       ...request.signal !== void 0 ? { signal: request.signal } : {},
@@ -10156,6 +10546,124 @@ var GcsTransferOperations = class {
     if (typeof item.md5Hash === "string" && item.md5Hash !== "") result.checksum = item.md5Hash;
     return result;
   }
+  async writeResumableSession(request, normalized, objectName) {
+    const multipart = this.options.multipart;
+    const partSize = multipart.partSizeBytes;
+    const iterator = request.content[Symbol.asyncIterator]();
+    const initialBuffer = [];
+    let initialSize = 0;
+    while (initialSize <= multipart.thresholdBytes) {
+      const next = await iterator.next();
+      if (next.done === true) break;
+      const chunk = next.value;
+      if (chunk.byteLength === 0) continue;
+      initialBuffer.push(chunk);
+      initialSize += chunk.byteLength;
+    }
+    if (initialSize <= multipart.thresholdBytes) {
+      return this.singleShotMedia(
+        request,
+        normalized,
+        objectName,
+        concatChunks3(initialBuffer, initialSize)
+      );
+    }
+    const initiateUrl = `${this.options.uploadBaseUrl}/b/${encodeURIComponent(this.options.bucket)}/o?uploadType=resumable&name=${encodeURIComponent(objectName)}`;
+    const initiateResponse = await gcsFetch(this.options, "POST", initiateUrl, {
+      ...request.signal !== void 0 ? { signal: request.signal } : {},
+      body: new TextEncoder().encode("{}"),
+      extraHeaders: {
+        "content-type": "application/json; charset=UTF-8",
+        "x-upload-content-type": "application/octet-stream"
+      }
+    });
+    if (!initiateResponse.ok) {
+      throw mapGcsResponseError(initiateResponse, normalized, await safeReadText5(initiateResponse));
+    }
+    const sessionUri = initiateResponse.headers.get("location");
+    if (sessionUri === null || sessionUri === "") {
+      throw new ConnectionError({
+        details: { path: normalized },
+        message: "GCS resumable session initiation returned no Location header",
+        retryable: true
+      });
+    }
+    let bytesTransferred = 0;
+    let buffer = [...initialBuffer];
+    let bufferSize = initialSize;
+    let sourceExhausted = false;
+    let finalItem;
+    const flushChunks = async (final) => {
+      while (bufferSize >= partSize || final && bufferSize > 0) {
+        const take = final ? bufferSize : partSize;
+        const sliced = sliceFromBuffers2(buffer, take);
+        buffer = sliced.remaining;
+        bufferSize -= sliced.bytes.byteLength;
+        const chunkStart = bytesTransferred;
+        const chunkEnd = chunkStart + sliced.bytes.byteLength - 1;
+        const totalRange = final ? String(chunkEnd + 1) : "*";
+        const headers = {
+          "content-length": String(sliced.bytes.byteLength),
+          "content-range": `bytes ${String(chunkStart)}-${String(chunkEnd)}/${totalRange}`,
+          "content-type": "application/octet-stream"
+        };
+        const response = await gcsSessionFetch(this.options, sessionUri, {
+          ...request.signal !== void 0 ? { signal: request.signal } : {},
+          body: sliced.bytes,
+          extraHeaders: headers
+        });
+        if (response.status === 308) {
+          bytesTransferred += sliced.bytes.byteLength;
+          request.reportProgress(bytesTransferred, void 0);
+          continue;
+        }
+        if (response.status === 200 || response.status === 201) {
+          bytesTransferred += sliced.bytes.byteLength;
+          request.reportProgress(bytesTransferred, bytesTransferred);
+          finalItem = await response.json();
+          return;
+        }
+        throw mapGcsResponseError(response, normalized, await safeReadText5(response));
+      }
+    };
+    try {
+      await flushChunks(false);
+      while (!sourceExhausted) {
+        request.throwIfAborted();
+        const next = await iterator.next();
+        if (next.done === true) {
+          sourceExhausted = true;
+          break;
+        }
+        if (next.value.byteLength === 0) continue;
+        buffer.push(next.value);
+        bufferSize += next.value.byteLength;
+        await flushChunks(false);
+        if (finalItem !== void 0) break;
+      }
+      if (finalItem === void 0) {
+        await flushChunks(true);
+      }
+    } catch (error) {
+      void gcsSessionFetch(this.options, sessionUri, { method: "DELETE" }).catch(() => void 0);
+      throw error;
+    }
+    if (finalItem === void 0) {
+      throw new ConnectionError({
+        details: { path: normalized },
+        message: "GCS resumable upload did not return a final object",
+        retryable: true
+      });
+    }
+    const result = {
+      bytesTransferred,
+      totalBytes: bytesTransferred
+    };
+    if (typeof finalItem.md5Hash === "string" && finalItem.md5Hash !== "") {
+      result.checksum = finalItem.md5Hash;
+    }
+    return result;
+  }
 };
 async function gcsFetch(options, method, url, fetchOptions = {}) {
   const headers = {
@@ -10314,6 +10822,81 @@ async function collectChunks5(source) {
   }
   return out;
 }
+function concatChunks3(chunks, totalSize) {
+  const out = new Uint8Array(totalSize);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+function sliceFromBuffers2(buffers, size) {
+  const out = new Uint8Array(size);
+  let offset = 0;
+  let i = 0;
+  while (offset < size && i < buffers.length) {
+    const chunk = buffers[i];
+    if (chunk === void 0) {
+      i += 1;
+      continue;
+    }
+    const remaining = size - offset;
+    if (chunk.byteLength <= remaining) {
+      out.set(chunk, offset);
+      offset += chunk.byteLength;
+      i += 1;
+    } else {
+      out.set(chunk.subarray(0, remaining), offset);
+      const leftover = chunk.subarray(remaining);
+      const next = buffers.slice(i + 1);
+      next.unshift(leftover);
+      return { bytes: out, remaining: next };
+    }
+  }
+  return { bytes: out.subarray(0, offset), remaining: buffers.slice(i) };
+}
+async function gcsSessionFetch(options, sessionUri, fetchOptions = {}) {
+  const headers = {
+    ...options.defaultHeaders,
+    ...fetchOptions.extraHeaders ?? {},
+    authorization: `Bearer ${options.token}`
+  };
+  const init = { headers, method: fetchOptions.method ?? "PUT" };
+  if (fetchOptions.body !== void 0) {
+    init.body = fetchOptions.body;
+  }
+  const controller = new AbortController();
+  const upstream = fetchOptions.signal ?? null;
+  if (upstream !== null) {
+    if (upstream.aborted) controller.abort(upstream.reason);
+    else upstream.addEventListener("abort", () => controller.abort(upstream.reason));
+  }
+  let timer;
+  if (options.timeoutMs !== void 0 && options.timeoutMs > 0) {
+    timer = setTimeout(
+      () => controller.abort(new Error("GCS resumable session request timed out")),
+      options.timeoutMs
+    );
+  }
+  try {
+    return await options.fetch(sessionUri, { ...init, signal: controller.signal });
+  } catch (error) {
+    const safeUrl = redactSessionUrl2(sessionUri);
+    throw new ConnectionError({
+      cause: error,
+      details: { url: safeUrl },
+      message: `GCS resumable session request to ${safeUrl} failed`,
+      retryable: true
+    });
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+function redactSessionUrl2(url) {
+  const queryStart = url.indexOf("?");
+  return queryStart === -1 ? url : `${url.slice(0, queryStart)}?<redacted>`;
+}
 
 // src/providers/local/LocalProvider.ts
 import { createReadStream } from "fs";
@@ -10534,9 +11117,9 @@ async function collectTransferContent(request) {
     byteLength += clonedChunk.byteLength;
     request.reportProgress(byteLength, request.totalBytes);
   }
-  return concatChunks2(chunks, byteLength);
+  return concatChunks4(chunks, byteLength);
 }
-function concatChunks2(chunks, byteLength) {
+function concatChunks4(chunks, byteLength) {
   const content = new Uint8Array(byteLength);
   let offset = 0;
   for (const chunk of chunks) {
@@ -11110,9 +11693,9 @@ async function collectTransferContent2(request) {
     byteLength += clonedChunk.byteLength;
     request.reportProgress(byteLength, request.totalBytes);
   }
-  return concatChunks3(chunks, byteLength);
+  return concatChunks5(chunks, byteLength);
 }
-function concatChunks3(chunks, byteLength) {
+function concatChunks5(chunks, byteLength) {
   const content = new Uint8Array(byteLength);
   let offset = 0;
   for (const chunk of chunks) {
@@ -12285,7 +12868,7 @@ var S3TransferOperations = class {
     const flushPart = async (final) => {
       while (bufferSize >= partSize || final && bufferSize > 0) {
         const take = final ? bufferSize : partSize;
-        const partBytes = sliceFromBuffers(buffer, take);
+        const partBytes = sliceFromBuffers3(buffer, take);
         buffer = partBytes.remaining;
         bufferSize -= partBytes.bytes.byteLength;
         const partUrl = new URL(objectUrl.toString());
@@ -12474,7 +13057,7 @@ function concat(chunks, totalSize) {
   }
   return out;
 }
-function sliceFromBuffers(buffers, size) {
+function sliceFromBuffers3(buffers, size) {
   const out = new Uint8Array(size);
   let offset = 0;
   let i = 0;
@@ -12506,11 +13089,11 @@ async function abortMultipart(options, objectUrl, uploadId) {
 }
 function buildCompleteMultipartBody(parts) {
   const partsXml = parts.map(
-    (part) => `<Part><PartNumber>${String(part.partNumber)}</PartNumber><ETag>${escapeXml(part.etag)}</ETag></Part>`
+    (part) => `<Part><PartNumber>${String(part.partNumber)}</PartNumber><ETag>${escapeXml2(part.etag)}</ETag></Part>`
   ).join("");
   return `<?xml version="1.0" encoding="UTF-8"?><CompleteMultipartUpload>${partsXml}</CompleteMultipartUpload>`;
 }
-function escapeXml(value) {
+function escapeXml2(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
 function parseListObjectsV2(xml, prefix) {
@@ -12659,8 +13242,8 @@ function formatCapabilityMatrixMarkdown(matrix = getBuiltinCapabilityMatrix()) {
     const c = entry.capabilities;
     const yesNo = (value) => value ? "\u2705" : "\u274C";
     const sideways = `${yesNo(c.serverSideCopy)} / ${yesNo(c.serverSideMove)}`;
-    const checksums = c.checksum.length === 0 ? "\u2014" : c.checksum.join(", ");
-    const auth = c.authentication.length === 0 ? "\u2014" : c.authentication.join(", ");
+    const checksums = c.checksum.length === 0 ? "-" : c.checksum.join(", ");
+    const auth = c.authentication.length === 0 ? "-" : c.authentication.join(", ");
     return `| ${entry.label} | ${yesNo(c.list)} | ${yesNo(c.stat)} | ${yesNo(c.readStream)} | ${yesNo(c.writeStream)} | ${yesNo(c.resumeDownload)} | ${yesNo(c.resumeUpload)} | ${sideways} | ${checksums} | ${auth} |`;
   });
   return [header, divider, ...rows].join("\n");
@@ -13246,6 +13829,84 @@ function mapFtp550(details) {
   return new PermissionDeniedError(details);
 }
 
+// src/protocols/ssh/runSshCommand.ts
+import { connect } from "net";
+var DEFAULT_PORT = 22;
+var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+var DEFAULT_HANDSHAKE_TIMEOUT_MS = 1e4;
+var DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+async function runSshCommand(options) {
+  const {
+    host,
+    port = DEFAULT_PORT,
+    command,
+    auth,
+    transport: transportOptions,
+    connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS,
+    maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES
+  } = options;
+  const socket = await openTcpSocket(host, port, connectTimeoutMs);
+  const transport = new SshTransportConnection({
+    handshakeTimeoutMs: DEFAULT_HANDSHAKE_TIMEOUT_MS,
+    ...transportOptions
+  });
+  try {
+    const handshake = await transport.connect(socket);
+    const authSession = new SshAuthSession(transport);
+    await authSession.authenticate({
+      credential: auth,
+      sessionId: handshake.keyExchange.sessionId
+    });
+    const conn = new SshConnectionManager(transport);
+    const channel = await conn.openExecChannel(command);
+    const pump = conn.start();
+    pump.catch(() => {
+    });
+    const chunks = [];
+    let bytesReceived = 0;
+    try {
+      for await (const chunk of channel.receiveData()) {
+        bytesReceived += chunk.length;
+        if (bytesReceived > maxOutputBytes) {
+          throw new Error(
+            `runSshCommand: stdout exceeded ${maxOutputBytes} bytes (set maxOutputBytes to allow more)`
+          );
+        }
+        chunks.push(chunk);
+      }
+    } finally {
+      channel.close();
+    }
+    const stdout = Buffer.concat(chunks);
+    return {
+      stdout,
+      stdoutText: stdout.toString("utf8"),
+      bytesReceived
+    };
+  } finally {
+    transport.disconnect();
+  }
+}
+function openTcpSocket(host, port, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const socket = connect({ host, port });
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(
+        new Error(`runSshCommand: TCP connect to ${host}:${port} timed out after ${timeoutMs}ms`)
+      );
+    }, timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      resolve(socket);
+    });
+    socket.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+  });
+}
+
 // src/transfers/TransferPlan.ts
 function createTransferPlan(input) {
   const plan = {
@@ -15284,6 +15945,19 @@ var defaultRunner = ({ client, route, signal }) => {
   const options = { client, route, signal };
   return runRoute(options);
 };
+
+// src/utils/mainModule.ts
+import { fileURLToPath } from "url";
+function isMainModule(importMetaUrl) {
+  if (typeof process === "undefined" || !process.argv || process.argv.length < 2) {
+    return false;
+  }
+  try {
+    return process.argv[1] === fileURLToPath(importMetaUrl);
+  } catch {
+    return false;
+  }
+}
 export {
   AbortError,
   ApprovalRegistry,
@@ -15383,6 +16057,7 @@ export {
   inboxFailedPath,
   inboxProcessedPath,
   isClassicProviderId,
+  isMainModule,
   isSensitiveKey,
   joinRemotePath,
   matchKnownHosts,
@@ -15415,6 +16090,7 @@ export {
   resolveSecret,
   runConnectionDiagnostics,
   runRoute,
+  runSshCommand,
   serializeRemoteManifest,
   signWebhookPayload,
   sortRemoteEntries,