@backblaze-labs/b2-sdk 0.2.0 → 0.3.0

package/dist/types/download.d.ts

@@ -1,4 +1,66 @@
+import { SseB2Setting, SseCPublicSetting } from './encryption.js';
 import { BucketId, FileId } from './ids.js';
+import { ReadableFileRetention, ReadableLegalHold } from './lock.js';
+/** HTTP response header names returned by B2 download endpoints. */
+export declare const DownloadHeaderName: {
+    /** Header carrying the response content disposition. */
+    readonly ContentDisposition: "Content-Disposition";
+    /** Header carrying the response content language. */
+    readonly ContentLanguage: "Content-Language";
+    /** Header carrying the response content encoding. */
+    readonly ContentEncoding: "Content-Encoding";
+    /** Header carrying the response content type. */
+    readonly ContentType: "Content-Type";
+    /** Header carrying the response cache policy. */
+    readonly CacheControl: "Cache-Control";
+    /** Header carrying the response expiration time. */
+    readonly Expires: "Expires";
+    /** Header carrying the byte range returned for partial downloads. */
+    readonly ContentRange: "Content-Range";
+    /** Header carrying the response content length. */
+    readonly ContentLength: "Content-Length";
+    /** Header carrying the B2 SHA-1 metadata value. */
+    readonly ContentSha1: "X-Bz-Content-Sha1";
+    /** Header carrying the downloaded file version ID. */
+    readonly FileId: "X-Bz-File-Id";
+    /** Header carrying the URL-encoded downloaded file name. */
+    readonly FileName: "X-Bz-File-Name";
+    /** Header carrying the file upload timestamp. */
+    readonly UploadTimestamp: "X-Bz-Upload-Timestamp";
+    /** Header carrying the B2-managed server-side encryption algorithm. */
+    readonly ServerSideEncryption: "X-Bz-Server-Side-Encryption";
+    /** Header carrying the SSE-C algorithm echo. */
+    readonly ServerSideEncryptionCustomerAlgorithm: "X-Bz-Server-Side-Encryption-Customer-Algorithm";
+    /** Header carrying the SSE-C customer-key MD5 echo. */
+    readonly ServerSideEncryptionCustomerKeyMd5: "X-Bz-Server-Side-Encryption-Customer-Key-Md5";
+    /** Header carrying the Object Lock retention mode. */
+    readonly FileRetentionMode: "X-Bz-File-Retention-Mode";
+    /** Header carrying the Object Lock retain-until timestamp. */
+    readonly FileRetentionRetainUntilTimestamp: "X-Bz-File-Retention-Retain-Until-Timestamp";
+    /** Header carrying the Object Lock legal-hold value. */
+    readonly FileLegalHold: "X-Bz-File-Legal-Hold";
+    /** Header carrying names of metadata headers hidden by missing capabilities. */
+    readonly ClientUnauthorizedToRead: "X-Bz-Client-Unauthorized-To-Read";
+};
+/** HTTP response header name returned by B2 download endpoints. */
+export type DownloadHeaderName = (typeof DownloadHeaderName)[keyof typeof DownloadHeaderName];
+/** Documented download metadata markers B2 may hide when the caller lacks read capabilities. */
+export declare const DownloadClientUnauthorizedToReadMarker: {
+    /** B2-managed encryption metadata is hidden. */
+    readonly ServerSideEncryption: "X-Bz-Server-Side-Encryption";
+    /** SSE-C algorithm metadata is hidden. */
+    readonly ServerSideEncryptionCustomerAlgorithm: "X-Bz-Server-Side-Encryption-Customer-Algorithm";
+    /** SSE-C customer-key MD5 metadata is hidden. */
+    readonly ServerSideEncryptionCustomerKeyMd5: "X-Bz-Server-Side-Encryption-Customer-Key-Md5";
+    /** Object Lock retention mode metadata is hidden. */
+    readonly FileRetentionMode: "X-Bz-File-Retention-Mode";
+    /** Object Lock retain-until timestamp metadata is hidden. */
+    readonly FileRetentionRetainUntilTimestamp: "X-Bz-File-Retention-Retain-Until-Timestamp";
+    /** Object Lock legal-hold metadata is hidden. */
+    readonly FileLegalHold: "X-Bz-File-Legal-Hold";
+};
+/** Documented download metadata marker B2 may hide when the caller lacks read capabilities. */
+export type DownloadClientUnauthorizedToReadMarker = (typeof DownloadClientUnauthorizedToReadMarker)[keyof typeof DownloadClientUnauthorizedToReadMarker];
 /** Request parameters for downloading a file by its ID via `b2_download_file_by_id`. */
 export interface DownloadByIdRequest {
     /** ID of the file version to download. */
@@ -90,12 +152,38 @@ export interface DownloadAuthorizationResponse {
     /** Authorization token to include in download requests. */
     readonly authorizationToken: string;
 }
+/** Customer-managed server-side encryption metadata echoed in B2 download response headers. */
+export interface SseCDownloadSetting extends SseCPublicSetting {
+    /** MD5 digest echoed by `X-Bz-Server-Side-Encryption-Customer-Key-Md5`. */
+    readonly customerKeyMd5: string;
+}
+/** Server-side encryption metadata echoed in B2 download response headers. */
+export type DownloadServerSideEncryption = SseB2Setting | SseCDownloadSetting;
+/** Diagnostic for a present download metadata header the SDK could not parse narrowly. */
+export interface DownloadHeaderParseIssue {
+    /** Header whose value could not be parsed into the current typed SDK model. */
+    readonly headerName: DownloadHeaderName;
+    /** Raw header value that could not be parsed. */
+    readonly value: string;
+}
 /** Parsed headers from a B2 file download response. */
 export interface DownloadHeaders {
     /** MIME type of the downloaded file content. */
     readonly contentType: string;
     /** Size of the downloaded content in bytes. */
     readonly contentLength: number;
+    /** Content-Disposition value computed from upload metadata or the download request. */
+    readonly contentDisposition?: string;
+    /** Content-Language value computed from upload metadata or the download request. */
+    readonly contentLanguage?: string;
+    /** Content-Encoding value computed from upload metadata or the download request. */
+    readonly contentEncoding?: string;
+    /** Cache-Control value computed from upload metadata, bucket defaults, or the download request. */
+    readonly cacheControl?: string;
+    /** Expires value computed from upload metadata or the download request. */
+    readonly expires?: string;
+    /** Content-Range value returned for satisfiable range downloads. */
+    readonly contentRange?: string;
     /** SHA-1 checksum of the full file content, or null for large files. */
     readonly contentSha1: string | null;
     /** ID of the downloaded file version. */
@@ -106,5 +194,15 @@ export interface DownloadHeaders {
     readonly fileInfo: Record<string, string>;
     /** UTC timestamp (milliseconds) when the file was uploaded. */
     readonly uploadTimestamp: number;
+    /** Server-side encryption metadata echoed by B2, when the caller is authorized to read it. */
+    readonly serverSideEncryption?: DownloadServerSideEncryption;
+    /** Object Lock retention metadata, including whether the caller may read it. */
+    readonly fileRetention?: ReadableFileRetention;
+    /** Object Lock legal hold metadata, including whether the caller may read it. */
+    readonly legalHold?: ReadableLegalHold;
+    /** Header names B2 omitted because the caller lacks capability to read them. */
+    readonly clientUnauthorizedToRead?: readonly DownloadClientUnauthorizedToReadMarker[];
+    /** Present metadata headers the SDK could not parse into its current narrow typed model. */
+    readonly headerParseIssues?: readonly DownloadHeaderParseIssue[];
 }
 //# sourceMappingURL=download.d.ts.map

package/dist/types/download.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/types/download.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/types/download.js"],"names":[],"mappings":"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"}

package/dist/types/download.js

@@ -0,0 +1,61 @@
+//#region src/types/download.ts
+/** HTTP response header names returned by B2 download endpoints. */
+var DownloadHeaderName = {
+	/** Header carrying the response content disposition. */
+	ContentDisposition: "Content-Disposition",
+	/** Header carrying the response content language. */
+	ContentLanguage: "Content-Language",
+	/** Header carrying the response content encoding. */
+	ContentEncoding: "Content-Encoding",
+	/** Header carrying the response content type. */
+	ContentType: "Content-Type",
+	/** Header carrying the response cache policy. */
+	CacheControl: "Cache-Control",
+	/** Header carrying the response expiration time. */
+	Expires: "Expires",
+	/** Header carrying the byte range returned for partial downloads. */
+	ContentRange: "Content-Range",
+	/** Header carrying the response content length. */
+	ContentLength: "Content-Length",
+	/** Header carrying the B2 SHA-1 metadata value. */
+	ContentSha1: "X-Bz-Content-Sha1",
+	/** Header carrying the downloaded file version ID. */
+	FileId: "X-Bz-File-Id",
+	/** Header carrying the URL-encoded downloaded file name. */
+	FileName: "X-Bz-File-Name",
+	/** Header carrying the file upload timestamp. */
+	UploadTimestamp: "X-Bz-Upload-Timestamp",
+	/** Header carrying the B2-managed server-side encryption algorithm. */
+	ServerSideEncryption: "X-Bz-Server-Side-Encryption",
+	/** Header carrying the SSE-C algorithm echo. */
+	ServerSideEncryptionCustomerAlgorithm: "X-Bz-Server-Side-Encryption-Customer-Algorithm",
+	/** Header carrying the SSE-C customer-key MD5 echo. */
+	ServerSideEncryptionCustomerKeyMd5: "X-Bz-Server-Side-Encryption-Customer-Key-Md5",
+	/** Header carrying the Object Lock retention mode. */
+	FileRetentionMode: "X-Bz-File-Retention-Mode",
+	/** Header carrying the Object Lock retain-until timestamp. */
+	FileRetentionRetainUntilTimestamp: "X-Bz-File-Retention-Retain-Until-Timestamp",
+	/** Header carrying the Object Lock legal-hold value. */
+	FileLegalHold: "X-Bz-File-Legal-Hold",
+	/** Header carrying names of metadata headers hidden by missing capabilities. */
+	ClientUnauthorizedToRead: "X-Bz-Client-Unauthorized-To-Read"
+};
+/** Documented download metadata markers B2 may hide when the caller lacks read capabilities. */
+var DownloadClientUnauthorizedToReadMarker = {
+	/** B2-managed encryption metadata is hidden. */
+	ServerSideEncryption: DownloadHeaderName.ServerSideEncryption,
+	/** SSE-C algorithm metadata is hidden. */
+	ServerSideEncryptionCustomerAlgorithm: DownloadHeaderName.ServerSideEncryptionCustomerAlgorithm,
+	/** SSE-C customer-key MD5 metadata is hidden. */
+	ServerSideEncryptionCustomerKeyMd5: DownloadHeaderName.ServerSideEncryptionCustomerKeyMd5,
+	/** Object Lock retention mode metadata is hidden. */
+	FileRetentionMode: DownloadHeaderName.FileRetentionMode,
+	/** Object Lock retain-until timestamp metadata is hidden. */
+	FileRetentionRetainUntilTimestamp: DownloadHeaderName.FileRetentionRetainUntilTimestamp,
+	/** Object Lock legal-hold metadata is hidden. */
+	FileLegalHold: DownloadHeaderName.FileLegalHold
+};
+//#endregion
+export { DownloadClientUnauthorizedToReadMarker, DownloadHeaderName };
+
+//# sourceMappingURL=download.js.map

package/dist/types/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","names":[],"sources":["../../src/types/download.ts"],"sourcesContent":["import type { SseB2Setting, SseCPublicSetting } from './encryption.ts'\nimport type { BucketId, FileId } from './ids.ts'\nimport type { ReadableFileRetention, ReadableLegalHold } from './lock.ts'\n\n/** HTTP response header names returned by B2 download endpoints. */\nexport const DownloadHeaderName = {\n  /** Header carrying the response content disposition. */\n  ContentDisposition: 'Content-Disposition',\n  /** Header carrying the response content language. */\n  ContentLanguage: 'Content-Language',\n  /** Header carrying the response content encoding. */\n  ContentEncoding: 'Content-Encoding',\n  /** Header carrying the response content type. */\n  ContentType: 'Content-Type',\n  /** Header carrying the response cache policy. */\n  CacheControl: 'Cache-Control',\n  /** Header carrying the response expiration time. */\n  Expires: 'Expires',\n  /** Header carrying the byte range returned for partial downloads. */\n  ContentRange: 'Content-Range',\n  /** Header carrying the response content length. */\n  ContentLength: 'Content-Length',\n  /** Header carrying the B2 SHA-1 metadata value. */\n  ContentSha1: 'X-Bz-Content-Sha1',\n  /** Header carrying the downloaded file version ID. */\n  FileId: 'X-Bz-File-Id',\n  /** Header carrying the URL-encoded downloaded file name. */\n  FileName: 'X-Bz-File-Name',\n  /** Header carrying the file upload timestamp. */\n  UploadTimestamp: 'X-Bz-Upload-Timestamp',\n  /** Header carrying the B2-managed server-side encryption algorithm. */\n  ServerSideEncryption: 'X-Bz-Server-Side-Encryption',\n  /** Header carrying the SSE-C algorithm echo. */\n  ServerSideEncryptionCustomerAlgorithm: 'X-Bz-Server-Side-Encryption-Customer-Algorithm',\n  /** Header carrying the SSE-C customer-key MD5 echo. */\n  ServerSideEncryptionCustomerKeyMd5: 'X-Bz-Server-Side-Encryption-Customer-Key-Md5',\n  /** Header carrying the Object Lock retention mode. */\n  FileRetentionMode: 'X-Bz-File-Retention-Mode',\n  /** Header carrying the Object Lock retain-until timestamp. */\n  FileRetentionRetainUntilTimestamp: 'X-Bz-File-Retention-Retain-Until-Timestamp',\n  /** Header carrying the Object Lock legal-hold value. */\n  FileLegalHold: 'X-Bz-File-Legal-Hold',\n  /** Header carrying names of metadata headers hidden by missing capabilities. */\n  ClientUnauthorizedToRead: 'X-Bz-Client-Unauthorized-To-Read',\n} as const\n\n/** HTTP response header name returned by B2 download endpoints. */\nexport type DownloadHeaderName = (typeof DownloadHeaderName)[keyof typeof DownloadHeaderName]\n\n/** Documented download metadata markers B2 may hide when the caller lacks read capabilities. */\nexport const DownloadClientUnauthorizedToReadMarker = {\n  /** B2-managed encryption metadata is hidden. */\n  ServerSideEncryption: DownloadHeaderName.ServerSideEncryption,\n  /** SSE-C algorithm metadata is hidden. */\n  ServerSideEncryptionCustomerAlgorithm: DownloadHeaderName.ServerSideEncryptionCustomerAlgorithm,\n  /** SSE-C customer-key MD5 metadata is hidden. */\n  ServerSideEncryptionCustomerKeyMd5: DownloadHeaderName.ServerSideEncryptionCustomerKeyMd5,\n  /** Object Lock retention mode metadata is hidden. */\n  FileRetentionMode: DownloadHeaderName.FileRetentionMode,\n  /** Object Lock retain-until timestamp metadata is hidden. */\n  FileRetentionRetainUntilTimestamp: DownloadHeaderName.FileRetentionRetainUntilTimestamp,\n  /** Object Lock legal-hold metadata is hidden. */\n  FileLegalHold: DownloadHeaderName.FileLegalHold,\n} as const\n\n/** Documented download metadata marker B2 may hide when the caller lacks read capabilities. */\nexport type DownloadClientUnauthorizedToReadMarker =\n  (typeof DownloadClientUnauthorizedToReadMarker)[keyof typeof DownloadClientUnauthorizedToReadMarker]\n\n/** Request parameters for downloading a file by its ID via `b2_download_file_by_id`. */\nexport interface DownloadByIdRequest {\n  /** ID of the file version to download. */\n  readonly fileId: FileId\n  /** Optional byte range to download (e.g., `'bytes=0-999'`). */\n  readonly range?: string\n  /** SSE-C decryption parameters, required if the file was uploaded with SSE-C. */\n  readonly serverSideEncryption?: {\n    /** Encryption algorithm. Always `'AES256'`. */\n    readonly algorithm: 'AES256'\n    /** Base64-encoded customer-provided decryption key. */\n    readonly customerKey: string\n    /** Base64-encoded MD5 digest of the decryption key. */\n    readonly customerKeyMd5: string\n  }\n  /** Override the Content-Disposition header in the download response. */\n  readonly b2ContentDisposition?: string\n  /** Override the Content-Language header in the download response. */\n  readonly b2ContentLanguage?: string\n  /** Override the Content-Encoding header in the download response. */\n  readonly b2ContentEncoding?: string\n  /** Override the Content-Type header in the download response. */\n  readonly b2ContentType?: string\n  /** Override the Cache-Control header in the download response. */\n  readonly b2CacheControl?: string\n  /** Override the Expires header in the download response. */\n  readonly b2Expires?: string\n}\n\n/** Request parameters for downloading a file by bucket name and file name via `b2_download_file_by_name`. */\nexport interface DownloadByNameRequest {\n  /** Name of the bucket containing the file. */\n  readonly bucketName: string\n  /** Full path and name of the file within the bucket. */\n  readonly fileName: string\n  /** Optional byte range to download (e.g., `'bytes=0-999'`). */\n  readonly range?: string\n  /** SSE-C decryption parameters, required if the file was uploaded with SSE-C. */\n  readonly serverSideEncryption?: {\n    /** Encryption algorithm. Always `'AES256'`. */\n    readonly algorithm: 'AES256'\n    /** Base64-encoded customer-provided decryption key. */\n    readonly customerKey: string\n    /** Base64-encoded MD5 digest of the decryption key. */\n    readonly customerKeyMd5: string\n  }\n  /** Override the Content-Disposition header in the download response. */\n  readonly b2ContentDisposition?: string\n  /** Override the Content-Language header in the download response. */\n  readonly b2ContentLanguage?: string\n  /** Override the Content-Encoding header in the download response. */\n  readonly b2ContentEncoding?: string\n  /** Override the Content-Type header in the download response. */\n  readonly b2ContentType?: string\n  /** Override the Cache-Control header in the download response. */\n  readonly b2CacheControl?: string\n  /** Override the Expires header in the download response. */\n  readonly b2Expires?: string\n}\n\n/**\n * Request parameters for the `b2_get_download_authorization` API call.\n * Creates a time-limited token that authorizes downloads of files matching a prefix.\n */\nexport interface DownloadAuthorizationRequest {\n  /** Bucket to authorize downloads from. */\n  readonly bucketId: BucketId\n  /** Only files with names starting with this prefix are authorized. */\n  readonly fileNamePrefix: string\n  /** Duration in seconds that the authorization token remains valid. */\n  readonly validDurationInSeconds: number\n  /** Override the Content-Disposition header in authorized download responses. */\n  readonly b2ContentDisposition?: string\n  /** Override the Content-Language header in authorized download responses. */\n  readonly b2ContentLanguage?: string\n  /** Override the Content-Encoding header in authorized download responses. */\n  readonly b2ContentEncoding?: string\n  /** Override the Content-Type header in authorized download responses. */\n  readonly b2ContentType?: string\n  /** Override the Cache-Control header in authorized download responses. */\n  readonly b2CacheControl?: string\n  /** Override the Expires header in authorized download responses. */\n  readonly b2Expires?: string\n}\n\n/** Response from the `b2_get_download_authorization` API call. */\nexport interface DownloadAuthorizationResponse {\n  /** Bucket the authorization applies to. */\n  readonly bucketId: BucketId\n  /** File name prefix the authorization is scoped to. */\n  readonly fileNamePrefix: string\n  /** Authorization token to include in download requests. */\n  readonly authorizationToken: string\n}\n\n/** Customer-managed server-side encryption metadata echoed in B2 download response headers. */\nexport interface SseCDownloadSetting extends SseCPublicSetting {\n  /** MD5 digest echoed by `X-Bz-Server-Side-Encryption-Customer-Key-Md5`. */\n  readonly customerKeyMd5: string\n}\n\n/** Server-side encryption metadata echoed in B2 download response headers. */\nexport type DownloadServerSideEncryption = SseB2Setting | SseCDownloadSetting\n\n/** Diagnostic for a present download metadata header the SDK could not parse narrowly. */\nexport interface DownloadHeaderParseIssue {\n  /** Header whose value could not be parsed into the current typed SDK model. */\n  readonly headerName: DownloadHeaderName\n  /** Raw header value that could not be parsed. */\n  readonly value: string\n}\n\n/** Parsed headers from a B2 file download response. */\nexport interface DownloadHeaders {\n  /** MIME type of the downloaded file content. */\n  readonly contentType: string\n  /** Size of the downloaded content in bytes. */\n  readonly contentLength: number\n  /** Content-Disposition value computed from upload metadata or the download request. */\n  readonly contentDisposition?: string\n  /** Content-Language value computed from upload metadata or the download request. */\n  readonly contentLanguage?: string\n  /** Content-Encoding value computed from upload metadata or the download request. */\n  readonly contentEncoding?: string\n  /** Cache-Control value computed from upload metadata, bucket defaults, or the download request. */\n  readonly cacheControl?: string\n  /** Expires value computed from upload metadata or the download request. */\n  readonly expires?: string\n  /** Content-Range value returned for satisfiable range downloads. */\n  readonly contentRange?: string\n  /** SHA-1 checksum of the full file content, or null for large files. */\n  readonly contentSha1: string | null\n  /** ID of the downloaded file version. */\n  readonly fileId: FileId\n  /** Full path and name of the downloaded file. */\n  readonly fileName: string\n  /** User-defined key-value metadata stored with the file. */\n  readonly fileInfo: Record<string, string>\n  /** UTC timestamp (milliseconds) when the file was uploaded. */\n  readonly uploadTimestamp: number\n  /** Server-side encryption metadata echoed by B2, when the caller is authorized to read it. */\n  readonly serverSideEncryption?: DownloadServerSideEncryption\n  /** Object Lock retention metadata, including whether the caller may read it. */\n  readonly fileRetention?: ReadableFileRetention\n  /** Object Lock legal hold metadata, including whether the caller may read it. */\n  readonly legalHold?: ReadableLegalHold\n  /** Header names B2 omitted because the caller lacks capability to read them. */\n  readonly clientUnauthorizedToRead?: readonly DownloadClientUnauthorizedToReadMarker[]\n  /** Present metadata headers the SDK could not parse into its current narrow typed model. */\n  readonly headerParseIssues?: readonly DownloadHeaderParseIssue[]\n}\n"],"mappings":";;AAKA,IAAa,qBAAqB;;CAEhC,oBAAoB;;CAEpB,iBAAiB;;CAEjB,iBAAiB;;CAEjB,aAAa;;CAEb,cAAc;;CAEd,SAAS;;CAET,cAAc;;CAEd,eAAe;;CAEf,aAAa;;CAEb,QAAQ;;CAER,UAAU;;CAEV,iBAAiB;;CAEjB,sBAAsB;;CAEtB,uCAAuC;;CAEvC,oCAAoC;;CAEpC,mBAAmB;;CAEnB,mCAAmC;;CAEnC,eAAe;;CAEf,0BAA0B;AAC5B;;AAMA,IAAa,yCAAyC;;CAEpD,sBAAsB,mBAAmB;;CAEzC,uCAAuC,mBAAmB;;CAE1D,oCAAoC,mBAAmB;;CAEvD,mBAAmB,mBAAmB;;CAEtC,mCAAmC,mBAAmB;;CAEtD,eAAe,mBAAmB;AACpC"}

package/dist/types/encryption.cjs

@@ -1,3 +1,4 @@
+const require_md5 = require("../util/md5.cjs");
 //#region src/types/encryption.ts
 /** Named constants for the supported server-side encryption algorithms. */
 var EncryptionAlgorithm = { 
@@ -56,233 +57,61 @@ function bytesToBase64(bytes) {
 	for (const b of bytes) binary += String.fromCharCode(b);
 	return btoa(binary);
 }
-/**
-* Computes the MD5 digest of the given bytes as a base64 string. Prefers
-* `node:crypto` for native speed when available; falls back to a pure-JS
-* implementation in browser / edge runtimes because WebCrypto's
-* `crypto.subtle.digest` deliberately does not support MD5.
-*
-* MD5 is used here only for SSE-C key integrity (matching the B2 wire
-* protocol). It is **not** a security boundary; the customer key itself is
-* the secret. Bundling a pure-JS fallback keeps `EncryptionKey.fromBytes`
-* isomorphic.
-*
-* @param bytes - The bytes to digest.
-*
-* @returns The base64-encoded MD5 digest.
-*/
-async function md5Base64(bytes) {
-	try {
-		const { createHash } = await import("node:crypto");
-		if (typeof createHash !== "function") throw new Error("createHash unavailable");
-		return createHash("md5").update(bytes).digest("base64");
-	} catch {
-		return bytesToBase64(md5Bytes(bytes));
-	}
+var SSE_C_KEY_REDACTION = "[redacted SSE-C key]";
+var NODE_INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
+function sseCKeyRedactedJson(key, options) {
+	return {
+		...options.mode !== void 0 ? { mode: options.mode } : {},
+		algorithm: key.algorithm,
+		customerKey: SSE_C_KEY_REDACTION,
+		customerKeyMd5: SSE_C_KEY_REDACTION
+	};
+}
+function sseCKeyRedactedString(options) {
+	return `[${options.label} ${SSE_C_KEY_REDACTION}]`;
 }
 /**
-* Pure-JS MD5 implementation per RFC 1321. Returns the 16-byte digest of the
-* input. Used as a browser fallback for SSE-C key MD5 computation; not
-* intended for security-sensitive purposes (MD5 is broken cryptographically).
+* Wraps SSE-C key material so diagnostic stringification redacts key fields.
 *
-* @param data - The bytes to hash.
+* The returned object keeps `customerKey` and `customerKeyMd5` readable by
+* property access for request header construction, but makes them
+* non-enumerable so object spread and generic serializers do not copy them.
+* Callers that need wire headers must read those fields directly.
 *
-* @returns The 16-byte MD5 digest.
+* @param key - SSE-C key material to wrap.
+* @param options - Redaction label and optional encryption mode discriminator.
+*
+* @returns A redacted view with the same readable key fields.
 */
-function md5Bytes(data) {
-	const originalBitLength = data.byteLength * 8;
-	const padLength = (data.byteLength + 8 >>> 6) + 1;
-	const padded = new Uint8Array(padLength * 64);
-	padded.set(data);
-	padded[data.byteLength] = 128;
-	const lowBits = originalBitLength >>> 0;
-	const highBits = Math.floor(originalBitLength / 4294967296) >>> 0;
-	const lengthView = new DataView(padded.buffer, padded.byteLength - 8, 8);
-	lengthView.setUint32(0, lowBits, true);
-	lengthView.setUint32(4, highBits, true);
-	const s = [
-		7,
-		12,
-		17,
-		22,
-		7,
-		12,
-		17,
-		22,
-		7,
-		12,
-		17,
-		22,
-		7,
-		12,
-		17,
-		22,
-		5,
-		9,
-		14,
-		20,
-		5,
-		9,
-		14,
-		20,
-		5,
-		9,
-		14,
-		20,
-		5,
-		9,
-		14,
-		20,
-		4,
-		11,
-		16,
-		23,
-		4,
-		11,
-		16,
-		23,
-		4,
-		11,
-		16,
-		23,
-		4,
-		11,
-		16,
-		23,
-		6,
-		10,
-		15,
-		21,
-		6,
-		10,
-		15,
-		21,
-		6,
-		10,
-		15,
-		21,
-		6,
-		10,
-		15,
-		21
-	];
-	const k = new Uint32Array([
-		3614090360,
-		3905402710,
-		606105819,
-		3250441966,
-		4118548399,
-		1200080426,
-		2821735955,
-		4249261313,
-		1770035416,
-		2336552879,
-		4294925233,
-		2304563134,
-		1804603682,
-		4254626195,
-		2792965006,
-		1236535329,
-		4129170786,
-		3225465664,
-		643717713,
-		3921069994,
-		3593408605,
-		38016083,
-		3634488961,
-		3889429448,
-		568446438,
-		3275163606,
-		4107603335,
-		1163531501,
-		2850285829,
-		4243563512,
-		1735328473,
-		2368359562,
-		4294588738,
-		2272392833,
-		1839030562,
-		4259657740,
-		2763975236,
-		1272893353,
-		4139469664,
-		3200236656,
-		681279174,
-		3936430074,
-		3572445317,
-		76029189,
-		3654602809,
-		3873151461,
-		530742520,
-		3299628645,
-		4096336452,
-		1126891415,
-		2878612391,
-		4237533241,
-		1700485571,
-		2399980690,
-		4293915773,
-		2240044497,
-		1873313359,
-		4264355552,
-		2734768916,
-		1309151649,
-		4149444226,
-		3174756917,
-		718787259,
-		3951481745
-	]);
-	let a0 = 1732584193;
-	let b0 = 4023233417;
-	let c0 = 2562383102;
-	let d0 = 271733878;
-	const m = /* @__PURE__ */ new Uint32Array(16);
-	const view = new DataView(padded.buffer);
-	for (let block = 0; block < padded.byteLength; block += 64) {
-		for (let i = 0; i < 16; i++) m[i] = view.getUint32(block + i * 4, true);
-		let A = a0;
-		let B = b0;
-		let C = c0;
-		let D = d0;
-		for (let i = 0; i < 64; i++) {
-			let f;
-			let g;
-			if (i < 16) {
-				f = B & C | ~B & D;
-				g = i;
-			} else if (i < 32) {
-				f = D & B | ~D & C;
-				g = (5 * i + 1) % 16;
-			} else if (i < 48) {
-				f = B ^ C ^ D;
-				g = (3 * i + 5) % 16;
-			} else {
-				f = C ^ (B | ~D);
-				g = 7 * i % 16;
-			}
-			const temp = D;
-			D = C;
-			C = B;
-			const sum = A + f + (k[i] ?? 0) + (m[g] ?? 0) >>> 0;
-			const shift = s[i] ?? 0;
-			const rotated = (sum << shift | sum >>> 32 - shift) >>> 0;
-			B = B + rotated >>> 0;
-			A = temp;
+function redactSseCKeyMaterial(key, options) {
+	const redacted = {
+		...options.mode !== void 0 ? { mode: options.mode } : {},
+		algorithm: key.algorithm
+	};
+	Object.defineProperties(redacted, {
+		customerKey: {
+			value: key.customerKey,
+			enumerable: false
+		},
+		customerKeyMd5: {
+			value: key.customerKeyMd5,
+			enumerable: false
+		},
+		toJSON: {
+			value: () => sseCKeyRedactedJson(key, options),
+			enumerable: false
+		},
+		toString: {
+			value: () => sseCKeyRedactedString(options),
+			enumerable: false
 		}
-		a0 = a0 + A >>> 0;
-		b0 = b0 + B >>> 0;
-		c0 = c0 + C >>> 0;
-		d0 = d0 + D >>> 0;
-	}
-	const out = /* @__PURE__ */ new Uint8Array(16);
-	const outView = new DataView(out.buffer);
-	outView.setUint32(0, a0, true);
-	outView.setUint32(4, b0, true);
-	outView.setUint32(8, c0, true);
-	outView.setUint32(12, d0, true);
-	return out;
+	});
+	Object.defineProperty(redacted, NODE_INSPECT_CUSTOM, {
+		value: () => sseCKeyRedactedString(options),
+		enumerable: false
+	});
+	return redacted;
 }
-var KEY_REDACTED = "[redacted SSE-C key]";
 /**
 * Safe wrapper around an SSE-C customer key. Hides the key bytes from
 * `JSON.stringify`, `console.log`, and Node's `util.inspect`. Use {@link EncryptionKey.fromBytes}
@@ -323,7 +152,7 @@ var EncryptionKey = class EncryptionKey {
 	static async fromBytes(rawKey) {
 		if (rawKey.byteLength !== 32) throw new Error(`SSE-C key must be exactly 32 bytes (256 bits); got ${rawKey.byteLength}.`);
 		const customerKey = bytesToBase64(rawKey);
-		const customerKeyMd5 = await md5Base64(rawKey);
+		const customerKeyMd5 = await require_md5.md5Base64(rawKey);
 		return new EncryptionKey(customerKey, customerKeyMd5);
 	}
 	/**
@@ -345,12 +174,10 @@ var EncryptionKey = class EncryptionKey {
 	*   replaced with a placeholder string.
 	*/
 	toJSON() {
-		return {
-			mode: this.mode,
-			algorithm: this.algorithm,
-			customerKey: KEY_REDACTED,
-			customerKeyMd5: KEY_REDACTED
-		};
+		return sseCKeyRedactedJson(this, {
+			label: "EncryptionKey SSE-C",
+			mode: this.mode
+		});
 	}
 	/**
 	* Hides the key bytes from default `toString()`.
@@ -358,14 +185,14 @@ var EncryptionKey = class EncryptionKey {
 	* @returns A short opaque label indicating this is an SSE-C key.
 	*/
 	toString() {
-		return `[EncryptionKey SSE-C ${KEY_REDACTED}]`;
+		return sseCKeyRedactedString({ label: "EncryptionKey SSE-C" });
 	}
 	/**
 	* Hides the key bytes from Node's `util.inspect` (and therefore `console.log`).
 	*
 	* @returns A short opaque label indicating this is an SSE-C key.
 	*/
-	[Symbol.for("nodejs.util.inspect.custom")]() {
+	[NODE_INSPECT_CUSTOM]() {
 		return this.toString();
 	}
 };
@@ -374,7 +201,9 @@ exports.EncryptionAlgorithm = EncryptionAlgorithm;
 exports.EncryptionKey = EncryptionKey;
 exports.EncryptionMode = EncryptionMode;
 exports.SSE_B2 = SSE_B2;
+exports.SSE_C_KEY_REDACTION = SSE_C_KEY_REDACTION;
 exports.SSE_NONE = SSE_NONE;
+exports.redactSseCKeyMaterial = redactSseCKeyMaterial;
 exports.sseCustomer = sseCustomer;
 
 //# sourceMappingURL=encryption.cjs.map

package/dist/types/encryption.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.cjs","names":[],"sources":["../../src/types/encryption.ts"],"sourcesContent":["/** Named constants for the supported server-side encryption algorithms. */\nexport const EncryptionAlgorithm = {\n  /** AES with a 256-bit key. The only algorithm B2 currently supports. */\n  Aes256: 'AES256',\n} as const\n\n/** Supported server-side encryption algorithm. Derived from {@link EncryptionAlgorithm}. */\nexport type EncryptionAlgorithm = (typeof EncryptionAlgorithm)[keyof typeof EncryptionAlgorithm]\n\n/**\n * Named constants for the server-side encryption mode used by a file.\n *\n * Most callers should use the {@link SSE_B2}, {@link SSE_NONE}, and\n * {@link sseCustomer} helpers below which return complete\n * {@link EncryptionSetting} objects. These constants are useful when you\n * need the bare mode discriminator (e.g., when introspecting a file's\n * current encryption setting).\n */\nexport const EncryptionMode = {\n  /** B2-managed encryption keys. */\n  SseB2: 'SSE-B2',\n  /** Customer-provided encryption keys. */\n  SseC: 'SSE-C',\n  /** No encryption. */\n  None: 'none',\n} as const\n\n/** Server-side encryption mode for files stored in B2. Derived from {@link EncryptionMode}. */\nexport type EncryptionMode = (typeof EncryptionMode)[keyof typeof EncryptionMode]\n\n/** Server-side encryption using B2-managed keys (SSE-B2). */\nexport interface SseB2Setting {\n  /** Encryption mode discriminator. Always `'SSE-B2'`. */\n  readonly mode: 'SSE-B2'\n  /** Encryption algorithm. Always `'AES256'`. */\n  readonly algorithm: EncryptionAlgorithm\n}\n\n/** Server-side encryption using customer-provided keys (SSE-C). */\nexport interface SseCCustomerSetting {\n  /** Encryption mode discriminator. Always `'SSE-C'`. */\n  readonly mode: 'SSE-C'\n  /** Encryption algorithm. Always `'AES256'`. */\n  readonly algorithm: EncryptionAlgorithm\n  /** Base64-encoded 256-bit encryption key provided by the customer. */\n  readonly customerKey: string\n  /** Base64-encoded MD5 digest of the customer-provided key, used for integrity verification. */\n  readonly customerKeyMd5: string\n}\n\n/** Server-side encryption using customer-provided keys as returned by B2 responses. */\nexport interface SseCPublicSetting {\n  /** Encryption mode discriminator. Always `'SSE-C'`. */\n  readonly mode: 'SSE-C'\n  /** Encryption algorithm. Always `'AES256'`. */\n  readonly algorithm: EncryptionAlgorithm\n}\n\n/** Indicates no server-side encryption is applied. */\nexport interface NoEncryption {\n  /** Encryption mode discriminator. Always `'none'`. */\n  readonly mode: 'none'\n}\n\n/** No-encryption shape returned by B2 response objects. */\nexport interface NoEncryptionWireSetting {\n  /** Encryption mode discriminator. B2 response payloads use null for no encryption. */\n  readonly mode: null\n  /** Encryption algorithm. B2 response payloads use null when no encryption is applied. */\n  readonly algorithm: null\n}\n\n/** Union of all server-side encryption settings: B2-managed, customer-provided, or none. */\nexport type EncryptionSetting = SseB2Setting | SseCCustomerSetting | NoEncryption\n\n/** Server-side encryption setting returned by B2 response objects. */\nexport type PublicEncryptionSetting =\n  | SseB2Setting\n  | SseCPublicSetting\n  | NoEncryption\n  | NoEncryptionWireSetting\n\n/** Pre-built SSE-B2 encryption setting using AES-256. */\nexport const SSE_B2: SseB2Setting = { mode: 'SSE-B2', algorithm: 'AES256' }\n\n/** Pre-built setting indicating no server-side encryption. */\nexport const SSE_NONE: NoEncryption = { mode: 'none' }\n\n/**\n * Creates an SSE-C encryption setting with a customer-provided key.\n * @param customerKey - Base64-encoded 256-bit encryption key.\n * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.\n *\n * @returns An SSE-C encryption setting ready to pass to upload or download calls.\n */\nexport function sseCustomer(customerKey: string, customerKeyMd5: string): SseCCustomerSetting {\n  return { mode: 'SSE-C', algorithm: 'AES256', customerKey, customerKeyMd5 }\n}\n\n/**\n * Encodes raw bytes as base64 in an isomorphic way (Node Buffer fallback to btoa).\n *\n * @param bytes - The raw bytes to encode.\n *\n * @returns The base64-encoded string.\n */\nfunction bytesToBase64(bytes: Uint8Array): string {\n  // Prefer Node's Buffer when available (faster), but degrade to btoa() in\n  // browsers / Deno / Workers where Buffer isn't a global. We access via\n  // globalThis to avoid a hard reference to a Node-only symbol — that would\n  // break the type-check in non-Node runtimes (Deno, browser-mode Vitest).\n  const g = globalThis as {\n    Buffer?: { from(b: Uint8Array): { toString(encoding: string): string } }\n  }\n  if (g.Buffer) {\n    return g.Buffer.from(bytes).toString('base64')\n  }\n  let binary = ''\n  for (const b of bytes) binary += String.fromCharCode(b)\n  return btoa(binary)\n}\n\n/**\n * Computes the MD5 digest of the given bytes as a base64 string. Prefers\n * `node:crypto` for native speed when available; falls back to a pure-JS\n * implementation in browser / edge runtimes because WebCrypto's\n * `crypto.subtle.digest` deliberately does not support MD5.\n *\n * MD5 is used here only for SSE-C key integrity (matching the B2 wire\n * protocol). It is **not** a security boundary; the customer key itself is\n * the secret. Bundling a pure-JS fallback keeps `EncryptionKey.fromBytes`\n * isomorphic.\n *\n * @param bytes - The bytes to digest.\n *\n * @returns The base64-encoded MD5 digest.\n */\nasync function md5Base64(bytes: Uint8Array): Promise<string> {\n  try {\n    const { createHash } = await import('node:crypto')\n    // Vite's browser shim resolves the import but does not implement\n    // `createHash`. Probe explicitly so we fall through to the pure-JS path.\n    if (typeof createHash !== 'function') throw new Error('createHash unavailable')\n    return createHash('md5').update(bytes).digest('base64')\n    /* v8 ignore next 3 -- fallback only reachable in non-Node runtimes */\n  } catch {\n    return bytesToBase64(md5Bytes(bytes))\n  }\n}\n\n/**\n * Pure-JS MD5 implementation per RFC 1321. Returns the 16-byte digest of the\n * input. Used as a browser fallback for SSE-C key MD5 computation; not\n * intended for security-sensitive purposes (MD5 is broken cryptographically).\n *\n * @param data - The bytes to hash.\n *\n * @returns The 16-byte MD5 digest.\n */\nfunction md5Bytes(data: Uint8Array): Uint8Array {\n  // Padding: append 0x80, then zeros, then the original length in bits as a\n  // little-endian 64-bit integer, so the total length is a multiple of 64.\n  const originalBitLength = data.byteLength * 8\n  const padLength = ((data.byteLength + 8) >>> 6) + 1\n  const padded = new Uint8Array(padLength * 64)\n  padded.set(data)\n  padded[data.byteLength] = 0x80\n  // Write the 64-bit length (little-endian). JS bitwise ops are 32-bit, so\n  // split into low/high halves.\n  const lowBits = originalBitLength >>> 0\n  const highBits = Math.floor(originalBitLength / 0x1_0000_0000) >>> 0\n  const lengthView = new DataView(padded.buffer, padded.byteLength - 8, 8)\n  lengthView.setUint32(0, lowBits, true)\n  lengthView.setUint32(4, highBits, true)\n\n  // Per-round shift amounts.\n  const s = [\n    7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9,\n    14, 20, 5, 9, 14, 20, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 6, 10, 15, 21,\n    6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21,\n  ]\n  // Per-round sine-derived constants K[i] = floor(2^32 * abs(sin(i + 1))).\n  const k = new Uint32Array([\n    0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee, 0xf57c0faf, 0x4787c62a, 0xa8304613, 0xfd469501,\n    0x698098d8, 0x8b44f7af, 0xffff5bb1, 0x895cd7be, 0x6b901122, 0xfd987193, 0xa679438e, 0x49b40821,\n    0xf61e2562, 0xc040b340, 0x265e5a51, 0xe9b6c7aa, 0xd62f105d, 0x02441453, 0xd8a1e681, 0xe7d3fbc8,\n    0x21e1cde6, 0xc33707d6, 0xf4d50d87, 0x455a14ed, 0xa9e3e905, 0xfcefa3f8, 0x676f02d9, 0x8d2a4c8a,\n    0xfffa3942, 0x8771f681, 0x6d9d6122, 0xfde5380c, 0xa4beea44, 0x4bdecfa9, 0xf6bb4b60, 0xbebfbc70,\n    0x289b7ec6, 0xeaa127fa, 0xd4ef3085, 0x04881d05, 0xd9d4d039, 0xe6db99e5, 0x1fa27cf8, 0xc4ac5665,\n    0xf4292244, 0x432aff97, 0xab9423a7, 0xfc93a039, 0x655b59c3, 0x8f0ccc92, 0xffeff47d, 0x85845dd1,\n    0x6fa87e4f, 0xfe2ce6e0, 0xa3014314, 0x4e0811a1, 0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391,\n  ])\n\n  let a0 = 0x67452301\n  let b0 = 0xefcdab89\n  let c0 = 0x98badcfe\n  let d0 = 0x10325476\n\n  const m = new Uint32Array(16)\n  const view = new DataView(padded.buffer)\n  for (let block = 0; block < padded.byteLength; block += 64) {\n    for (let i = 0; i < 16; i++) m[i] = view.getUint32(block + i * 4, true)\n    let A = a0\n    let B = b0\n    let C = c0\n    let D = d0\n    for (let i = 0; i < 64; i++) {\n      let f: number\n      let g: number\n      if (i < 16) {\n        f = (B & C) | (~B & D)\n        g = i\n      } else if (i < 32) {\n        f = (D & B) | (~D & C)\n        g = (5 * i + 1) % 16\n      } else if (i < 48) {\n        f = B ^ C ^ D\n        g = (3 * i + 5) % 16\n      } else {\n        f = C ^ (B | ~D)\n        g = (7 * i) % 16\n      }\n      const temp = D\n      D = C\n      C = B\n      const sum = (A + f + (k[i] ?? 0) + (m[g] ?? 0)) >>> 0\n      const shift = s[i] ?? 0\n      const rotated = ((sum << shift) | (sum >>> (32 - shift))) >>> 0\n      B = (B + rotated) >>> 0\n      A = temp\n    }\n    a0 = (a0 + A) >>> 0\n    b0 = (b0 + B) >>> 0\n    c0 = (c0 + C) >>> 0\n    d0 = (d0 + D) >>> 0\n  }\n\n  const out = new Uint8Array(16)\n  const outView = new DataView(out.buffer)\n  outView.setUint32(0, a0, true)\n  outView.setUint32(4, b0, true)\n  outView.setUint32(8, c0, true)\n  outView.setUint32(12, d0, true)\n  return out\n}\n\nconst KEY_REDACTED = '[redacted SSE-C key]'\n\n/**\n * Safe wrapper around an SSE-C customer key. Hides the key bytes from\n * `JSON.stringify`, `console.log`, and Node's `util.inspect`. Use {@link EncryptionKey.fromBytes}\n * to construct one from a raw 32-byte key; the MD5 digest is computed internally.\n */\nexport class EncryptionKey {\n  /** Encryption mode discriminant. Always `'SSE-C'` for this class. */\n  readonly mode = 'SSE-C' as const\n  /** Encryption algorithm. B2's S3-compatible API only supports AES-256. */\n  readonly algorithm: EncryptionAlgorithm = 'AES256'\n  /** Base64-encoded 256-bit customer key. Logged as `[redacted SSE-C key]` via `toJSON` / `toString`. */\n  readonly customerKey: string\n  /** Base64-encoded MD5 digest of the customer key. Required by B2 for integrity verification. */\n  readonly customerKeyMd5: string\n\n  /**\n   * Internal constructor. Use {@link EncryptionKey.fromBytes} or\n   * {@link EncryptionKey.fromBase64} instead.\n   *\n   * @param customerKey - Base64-encoded 256-bit encryption key.\n   * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.\n   *\n   * @internal\n   */\n  private constructor(customerKey: string, customerKeyMd5: string) {\n    this.customerKey = customerKey\n    this.customerKeyMd5 = customerKeyMd5\n  }\n\n  /**\n   * Builds an EncryptionKey from a raw 32-byte (256-bit) key. Computes the\n   * required base64 MD5 digest internally.\n   *\n   * @param rawKey - The raw 256-bit key as bytes. Must be exactly 32 bytes.\n   *\n   * @returns A safely-wrapped EncryptionKey ready for upload/download.\n   *\n   * @throws If the key is not exactly 32 bytes.\n   */\n  static async fromBytes(rawKey: Uint8Array): Promise<EncryptionKey> {\n    if (rawKey.byteLength !== 32) {\n      throw new Error(`SSE-C key must be exactly 32 bytes (256 bits); got ${rawKey.byteLength}.`)\n    }\n    const customerKey = bytesToBase64(rawKey)\n    const customerKeyMd5 = await md5Base64(rawKey)\n    return new EncryptionKey(customerKey, customerKeyMd5)\n  }\n\n  /**\n   * Builds an EncryptionKey from precomputed base64 strings. Use this in\n   * environments where MD5 must be computed externally (e.g., browsers).\n   *\n   * @param customerKey - Base64-encoded 256-bit encryption key.\n   * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.\n   *\n   * @returns A safely-wrapped EncryptionKey ready for upload/download.\n   */\n  static fromBase64(customerKey: string, customerKeyMd5: string): EncryptionKey {\n    return new EncryptionKey(customerKey, customerKeyMd5)\n  }\n\n  /**\n   * Hides the key bytes from `JSON.stringify`.\n   *\n   * @returns A redacted shape: same mode and algorithm, but the key and MD5\n   *   replaced with a placeholder string.\n   */\n  toJSON(): {\n    /** Encryption mode discriminant. */\n    mode: 'SSE-C'\n    /** Encryption algorithm. */\n    algorithm: EncryptionAlgorithm\n    /** Always the literal redaction placeholder; the real key never leaves the instance. */\n    customerKey: string\n    /** Always the literal redaction placeholder; the real MD5 never leaves the instance. */\n    customerKeyMd5: string\n  } {\n    return {\n      mode: this.mode,\n      algorithm: this.algorithm,\n      customerKey: KEY_REDACTED,\n      customerKeyMd5: KEY_REDACTED,\n    }\n  }\n\n  /**\n   * Hides the key bytes from default `toString()`.\n   *\n   * @returns A short opaque label indicating this is an SSE-C key.\n   */\n  toString(): string {\n    return `[EncryptionKey SSE-C ${KEY_REDACTED}]`\n  }\n\n  /**\n   * Hides the key bytes from Node's `util.inspect` (and therefore `console.log`).\n   *\n   * @returns A short opaque label indicating this is an SSE-C key.\n   */\n  [Symbol.for('nodejs.util.inspect.custom')](): string {\n    return this.toString()\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"encryption.cjs","names":[],"sources":["../../src/types/encryption.ts"],"sourcesContent":["import { md5Base64 } from '../util/md5.ts'\n\n/** Named constants for the supported server-side encryption algorithms. */\nexport const EncryptionAlgorithm = {\n  /** AES with a 256-bit key. The only algorithm B2 currently supports. */\n  Aes256: 'AES256',\n} as const\n\n/** Supported server-side encryption algorithm. Derived from {@link EncryptionAlgorithm}. */\nexport type EncryptionAlgorithm = (typeof EncryptionAlgorithm)[keyof typeof EncryptionAlgorithm]\n\n/**\n * Named constants for the server-side encryption mode used by a file.\n *\n * Most callers should use the {@link SSE_B2}, {@link SSE_NONE}, and\n * {@link sseCustomer} helpers below which return complete\n * {@link EncryptionSetting} objects. These constants are useful when you\n * need the bare mode discriminator (e.g., when introspecting a file's\n * current encryption setting).\n */\nexport const EncryptionMode = {\n  /** B2-managed encryption keys. */\n  SseB2: 'SSE-B2',\n  /** Customer-provided encryption keys. */\n  SseC: 'SSE-C',\n  /** No encryption. */\n  None: 'none',\n} as const\n\n/** Server-side encryption mode for files stored in B2. Derived from {@link EncryptionMode}. */\nexport type EncryptionMode = (typeof EncryptionMode)[keyof typeof EncryptionMode]\n\n/** Server-side encryption using B2-managed keys (SSE-B2). */\nexport interface SseB2Setting {\n  /** Encryption mode discriminator. Always `'SSE-B2'`. */\n  readonly mode: 'SSE-B2'\n  /** Encryption algorithm. Always `'AES256'`. */\n  readonly algorithm: EncryptionAlgorithm\n}\n\n/** Server-side encryption using customer-provided keys (SSE-C). */\nexport interface SseCCustomerSetting {\n  /** Encryption mode discriminator. Always `'SSE-C'`. */\n  readonly mode: 'SSE-C'\n  /** Encryption algorithm. Always `'AES256'`. */\n  readonly algorithm: EncryptionAlgorithm\n  /** Base64-encoded 256-bit encryption key provided by the customer. */\n  readonly customerKey: string\n  /** Base64-encoded MD5 digest of the customer-provided key, used for integrity verification. */\n  readonly customerKeyMd5: string\n}\n\n/** Server-side encryption using customer-provided keys as returned by B2 responses. */\nexport interface SseCPublicSetting {\n  /** Encryption mode discriminator. Always `'SSE-C'`. */\n  readonly mode: 'SSE-C'\n  /** Encryption algorithm. Always `'AES256'`. */\n  readonly algorithm: EncryptionAlgorithm\n}\n\n/** Indicates no server-side encryption is applied. */\nexport interface NoEncryption {\n  /** Encryption mode discriminator. Always `'none'`. */\n  readonly mode: 'none'\n}\n\n/** No-encryption shape returned by B2 response objects. */\nexport interface NoEncryptionWireSetting {\n  /** Encryption mode discriminator. B2 response payloads use null for no encryption. */\n  readonly mode: null\n  /** Encryption algorithm. B2 response payloads use null when no encryption is applied. */\n  readonly algorithm: null\n}\n\n/** Union of all server-side encryption settings: B2-managed, customer-provided, or none. */\nexport type EncryptionSetting = SseB2Setting | SseCCustomerSetting | NoEncryption\n\n/** Server-side encryption setting returned by B2 response objects. */\nexport type PublicEncryptionSetting =\n  | SseB2Setting\n  | SseCPublicSetting\n  | NoEncryption\n  | NoEncryptionWireSetting\n\n/** Pre-built SSE-B2 encryption setting using AES-256. */\nexport const SSE_B2: SseB2Setting = { mode: 'SSE-B2', algorithm: 'AES256' }\n\n/** Pre-built setting indicating no server-side encryption. */\nexport const SSE_NONE: NoEncryption = { mode: 'none' }\n\n/**\n * Creates an SSE-C encryption setting with a customer-provided key.\n * @param customerKey - Base64-encoded 256-bit encryption key.\n * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.\n *\n * @returns An SSE-C encryption setting ready to pass to upload or download calls.\n */\nexport function sseCustomer(customerKey: string, customerKeyMd5: string): SseCCustomerSetting {\n  return { mode: 'SSE-C', algorithm: 'AES256', customerKey, customerKeyMd5 }\n}\n\n/**\n * Encodes raw bytes as base64 in an isomorphic way (Node Buffer fallback to btoa).\n *\n * @param bytes - The raw bytes to encode.\n *\n * @returns The base64-encoded string.\n */\nfunction bytesToBase64(bytes: Uint8Array): string {\n  // Prefer Node's Buffer when available (faster), but degrade to btoa() in\n  // browsers / Deno / Workers where Buffer isn't a global. We access via\n  // globalThis to avoid a hard reference to a Node-only symbol — that would\n  // break the type-check in non-Node runtimes (Deno, browser-mode Vitest).\n  const g = globalThis as {\n    Buffer?: { from(b: Uint8Array): { toString(encoding: string): string } }\n  }\n  if (g.Buffer) {\n    return g.Buffer.from(bytes).toString('base64')\n  }\n  let binary = ''\n  for (const b of bytes) binary += String.fromCharCode(b)\n  return btoa(binary)\n}\n\nexport const SSE_C_KEY_REDACTION = '[redacted SSE-C key]'\n\nconst NODE_INSPECT_CUSTOM = Symbol.for('nodejs.util.inspect.custom')\n\ninterface SseCKeyMaterial {\n  readonly algorithm: EncryptionAlgorithm\n  readonly customerKey: string\n  readonly customerKeyMd5: string\n}\n\ninterface SseCKeyRedactionOptions {\n  readonly label: string\n  readonly mode?: 'SSE-C'\n}\n\ninterface RedactedSseCKeyJson {\n  readonly mode?: 'SSE-C'\n  readonly algorithm: EncryptionAlgorithm\n  readonly customerKey: string\n  readonly customerKeyMd5: string\n}\n\nfunction sseCKeyRedactedJson(\n  key: SseCKeyMaterial,\n  options: SseCKeyRedactionOptions,\n): RedactedSseCKeyJson {\n  return {\n    ...(options.mode !== undefined ? { mode: options.mode } : {}),\n    algorithm: key.algorithm,\n    customerKey: SSE_C_KEY_REDACTION,\n    // The MD5 is not secret key material, but it is still derived from a\n    // customer-provided key. Keep logged key views fully opaque by default.\n    customerKeyMd5: SSE_C_KEY_REDACTION,\n  }\n}\n\nfunction sseCKeyRedactedString(options: SseCKeyRedactionOptions): string {\n  return `[${options.label} ${SSE_C_KEY_REDACTION}]`\n}\n\n/**\n * Wraps SSE-C key material so diagnostic stringification redacts key fields.\n *\n * The returned object keeps `customerKey` and `customerKeyMd5` readable by\n * property access for request header construction, but makes them\n * non-enumerable so object spread and generic serializers do not copy them.\n * Callers that need wire headers must read those fields directly.\n *\n * @param key - SSE-C key material to wrap.\n * @param options - Redaction label and optional encryption mode discriminator.\n *\n * @returns A redacted view with the same readable key fields.\n */\nexport function redactSseCKeyMaterial<T extends SseCKeyMaterial>(\n  key: T,\n  options: SseCKeyRedactionOptions,\n): T {\n  const redacted = {\n    ...(options.mode !== undefined ? { mode: options.mode } : {}),\n    algorithm: key.algorithm,\n  } as T & {\n    toJSON(): RedactedSseCKeyJson\n    toString(): string\n  }\n\n  Object.defineProperties(redacted, {\n    customerKey: { value: key.customerKey, enumerable: false },\n    customerKeyMd5: { value: key.customerKeyMd5, enumerable: false },\n    toJSON: { value: () => sseCKeyRedactedJson(key, options), enumerable: false },\n    toString: { value: () => sseCKeyRedactedString(options), enumerable: false },\n  })\n  Object.defineProperty(redacted, NODE_INSPECT_CUSTOM, {\n    value: () => sseCKeyRedactedString(options),\n    enumerable: false,\n  })\n\n  return redacted\n}\n\n/**\n * Safe wrapper around an SSE-C customer key. Hides the key bytes from\n * `JSON.stringify`, `console.log`, and Node's `util.inspect`. Use {@link EncryptionKey.fromBytes}\n * to construct one from a raw 32-byte key; the MD5 digest is computed internally.\n */\nexport class EncryptionKey {\n  /** Encryption mode discriminant. Always `'SSE-C'` for this class. */\n  readonly mode = 'SSE-C' as const\n  /** Encryption algorithm. B2's S3-compatible API only supports AES-256. */\n  readonly algorithm: EncryptionAlgorithm = 'AES256'\n  /** Base64-encoded 256-bit customer key. Logged as `[redacted SSE-C key]` via `toJSON` / `toString`. */\n  readonly customerKey: string\n  /** Base64-encoded MD5 digest of the customer key. Required by B2 for integrity verification. */\n  readonly customerKeyMd5: string\n\n  /**\n   * Internal constructor. Use {@link EncryptionKey.fromBytes} or\n   * {@link EncryptionKey.fromBase64} instead.\n   *\n   * @param customerKey - Base64-encoded 256-bit encryption key.\n   * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.\n   *\n   * @internal\n   */\n  private constructor(customerKey: string, customerKeyMd5: string) {\n    this.customerKey = customerKey\n    this.customerKeyMd5 = customerKeyMd5\n  }\n\n  /**\n   * Builds an EncryptionKey from a raw 32-byte (256-bit) key. Computes the\n   * required base64 MD5 digest internally.\n   *\n   * @param rawKey - The raw 256-bit key as bytes. Must be exactly 32 bytes.\n   *\n   * @returns A safely-wrapped EncryptionKey ready for upload/download.\n   *\n   * @throws If the key is not exactly 32 bytes.\n   */\n  static async fromBytes(rawKey: Uint8Array): Promise<EncryptionKey> {\n    if (rawKey.byteLength !== 32) {\n      throw new Error(`SSE-C key must be exactly 32 bytes (256 bits); got ${rawKey.byteLength}.`)\n    }\n    const customerKey = bytesToBase64(rawKey)\n    const customerKeyMd5 = await md5Base64(rawKey)\n    return new EncryptionKey(customerKey, customerKeyMd5)\n  }\n\n  /**\n   * Builds an EncryptionKey from precomputed base64 strings. Use this in\n   * environments where MD5 must be computed externally (e.g., browsers).\n   *\n   * @param customerKey - Base64-encoded 256-bit encryption key.\n   * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.\n   *\n   * @returns A safely-wrapped EncryptionKey ready for upload/download.\n   */\n  static fromBase64(customerKey: string, customerKeyMd5: string): EncryptionKey {\n    return new EncryptionKey(customerKey, customerKeyMd5)\n  }\n\n  /**\n   * Hides the key bytes from `JSON.stringify`.\n   *\n   * @returns A redacted shape: same mode and algorithm, but the key and MD5\n   *   replaced with a placeholder string.\n   */\n  toJSON(): {\n    /** Encryption mode discriminant. */\n    mode: 'SSE-C'\n    /** Encryption algorithm. */\n    algorithm: EncryptionAlgorithm\n    /** Always the literal redaction placeholder; the real key never leaves the instance. */\n    customerKey: string\n    /** Always the literal redaction placeholder; the real MD5 never leaves the instance. */\n    customerKeyMd5: string\n  } {\n    return sseCKeyRedactedJson(this, { label: 'EncryptionKey SSE-C', mode: this.mode }) as {\n      mode: 'SSE-C'\n      algorithm: EncryptionAlgorithm\n      customerKey: string\n      customerKeyMd5: string\n    }\n  }\n\n  /**\n   * Hides the key bytes from default `toString()`.\n   *\n   * @returns A short opaque label indicating this is an SSE-C key.\n   */\n  toString(): string {\n    return sseCKeyRedactedString({ label: 'EncryptionKey SSE-C' })\n  }\n\n  /**\n   * Hides the key bytes from Node's `util.inspect` (and therefore `console.log`).\n   *\n   * @returns A short opaque label indicating this is an SSE-C key.\n   */\n  [NODE_INSPECT_CUSTOM](): string {\n    return this.toString()\n  }\n}\n"],"mappings":";;;AAGA,IAAa,sBAAsB;;AAEjC,QAAQ,SACV;;;;;;;;;;AAcA,IAAa,iBAAiB;;CAE5B,OAAO;;CAEP,MAAM;;CAEN,MAAM;AACR;;AA0DA,IAAa,SAAuB;CAAE,MAAM;CAAU,WAAW;AAAS;;AAG1E,IAAa,WAAyB,EAAE,MAAM,OAAO;;;;;;;;AASrD,SAAgB,YAAY,aAAqB,gBAA6C;CAC5F,OAAO;EAAE,MAAM;EAAS,WAAW;EAAU;EAAa;CAAe;AAC3E;;;;;;;;AASA,SAAS,cAAc,OAA2B;CAKhD,MAAM,IAAI;CAGV,IAAI,EAAE,QACJ,OAAO,EAAE,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,QAAQ;CAE/C,IAAI,SAAS;CACb,KAAK,MAAM,KAAK,OAAO,UAAU,OAAO,aAAa,CAAC;CACtD,OAAO,KAAK,MAAM;AACpB;AAEA,IAAa,sBAAsB;AAEnC,IAAM,sBAAsB,OAAO,IAAI,4BAA4B;AAoBnE,SAAS,oBACP,KACA,SACqB;CACrB,OAAO;EACL,GAAI,QAAQ,SAAS,KAAA,IAAY,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;EAC3D,WAAW,IAAI;EACf,aAAa;EAGb,gBAAgB;CAClB;AACF;AAEA,SAAS,sBAAsB,SAA0C;CACvE,OAAO,IAAI,QAAQ,MAAM,GAAG,oBAAoB;AAClD;;;;;;;;;;;;;;AAeA,SAAgB,sBACd,KACA,SACG;CACH,MAAM,WAAW;EACf,GAAI,QAAQ,SAAS,KAAA,IAAY,EAAE,MAAM,QAAQ,KAAK,IAAI,CAAC;EAC3D,WAAW,IAAI;CACjB;CAKA,OAAO,iBAAiB,UAAU;EAChC,aAAa;GAAE,OAAO,IAAI;GAAa,YAAY;EAAM;EACzD,gBAAgB;GAAE,OAAO,IAAI;GAAgB,YAAY;EAAM;EAC/D,QAAQ;GAAE,aAAa,oBAAoB,KAAK,OAAO;GAAG,YAAY;EAAM;EAC5E,UAAU;GAAE,aAAa,sBAAsB,OAAO;GAAG,YAAY;EAAM;CAC7E,CAAC;CACD,OAAO,eAAe,UAAU,qBAAqB;EACnD,aAAa,sBAAsB,OAAO;EAC1C,YAAY;CACd,CAAC;CAED,OAAO;AACT;;;;;;AAOA,IAAa,gBAAb,MAAa,cAAc;;CAEzB,OAAgB;;CAEhB,YAA0C;;CAE1C;;CAEA;;;;;;;;;;CAWA,YAAoB,aAAqB,gBAAwB;EAC/D,KAAK,cAAc;EACnB,KAAK,iBAAiB;CACxB;;;;;;;;;;;CAYA,aAAa,UAAU,QAA4C;EACjE,IAAI,OAAO,eAAe,IACxB,MAAM,IAAI,MAAM,sDAAsD,OAAO,WAAW,EAAE;EAE5F,MAAM,cAAc,cAAc,MAAM;EACxC,MAAM,iBAAiB,MAAM,YAAA,UAAU,MAAM;EAC7C,OAAO,IAAI,cAAc,aAAa,cAAc;CACtD;;;;;;;;;;CAWA,OAAO,WAAW,aAAqB,gBAAuC;EAC5E,OAAO,IAAI,cAAc,aAAa,cAAc;CACtD;;;;;;;CAQA,SASE;EACA,OAAO,oBAAoB,MAAM;GAAE,OAAO;GAAuB,MAAM,KAAK;EAAK,CAAC;CAMpF;;;;;;CAOA,WAAmB;EACjB,OAAO,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CAC/D;;;;;;CAOA,CAAC,uBAA+B;EAC9B,OAAO,KAAK,SAAS;CACvB;AACF"}