@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/types/encryption.js

@@ -1,321 +1,375 @@
-const EncryptionAlgorithm = {
-  /** AES with a 256-bit key. The only algorithm B2 currently supports. */
-  Aes256: "AES256"
+//#region src/types/encryption.ts
+/** Named constants for the supported server-side encryption algorithms. */
+var EncryptionAlgorithm = { 
+/** AES with a 256-bit key. The only algorithm B2 currently supports. */
+Aes256: "AES256" };
+/**
+* Named constants for the server-side encryption mode used by a file.
+*
+* Most callers should use the {@link SSE_B2}, {@link SSE_NONE}, and
+* {@link sseCustomer} helpers below which return complete
+* {@link EncryptionSetting} objects. These constants are useful when you
+* need the bare mode discriminator (e.g., when introspecting a file's
+* current encryption setting).
+*/
+var EncryptionMode = {
+	/** B2-managed encryption keys. */
+	SseB2: "SSE-B2",
+	/** Customer-provided encryption keys. */
+	SseC: "SSE-C",
+	/** No encryption. */
+	None: "none"
 };
-const EncryptionMode = {
-  /** B2-managed encryption keys. */
-  SseB2: "SSE-B2",
-  /** Customer-provided encryption keys. */
-  SseC: "SSE-C",
-  /** No encryption. */
-  None: "none"
+/** Pre-built SSE-B2 encryption setting using AES-256. */
+var SSE_B2 = {
+	mode: "SSE-B2",
+	algorithm: "AES256"
 };
-const SSE_B2 = { mode: "SSE-B2", algorithm: "AES256" };
-const SSE_NONE = { mode: "none" };
+/** Pre-built setting indicating no server-side encryption. */
+var SSE_NONE = { mode: "none" };
+/**
+* Creates an SSE-C encryption setting with a customer-provided key.
+* @param customerKey - Base64-encoded 256-bit encryption key.
+* @param customerKeyMd5 - Base64-encoded MD5 digest of the key.
+*
+* @returns An SSE-C encryption setting ready to pass to upload or download calls.
+*/
 function sseCustomer(customerKey, customerKeyMd5) {
-  return { mode: "SSE-C", algorithm: "AES256", customerKey, customerKeyMd5 };
+	return {
+		mode: "SSE-C",
+		algorithm: "AES256",
+		customerKey,
+		customerKeyMd5
+	};
 }
+/**
+* Encodes raw bytes as base64 in an isomorphic way (Node Buffer fallback to btoa).
+*
+* @param bytes - The raw bytes to encode.
+*
+* @returns The base64-encoded string.
+*/
 function bytesToBase64(bytes) {
-  const g = globalThis;
-  if (g.Buffer) {
-    return g.Buffer.from(bytes).toString("base64");
-  }
-  let binary = "";
-  for (const b of bytes) binary += String.fromCharCode(b);
-  return btoa(binary);
+	const g = globalThis;
+	if (g.Buffer) return g.Buffer.from(bytes).toString("base64");
+	let binary = "";
+	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));
-  }
+	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));
+	}
 }
+/**
+* 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).
+*
+* @param data - The bytes to hash.
+*
+* @returns The 16-byte MD5 digest.
+*/
 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 = 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;
-    }
-    a0 = a0 + A >>> 0;
-    b0 = b0 + B >>> 0;
-    c0 = c0 + C >>> 0;
-    d0 = d0 + D >>> 0;
-  }
-  const out = 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;
+	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;
+		}
+		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;
 }
-const KEY_REDACTED = "[redacted SSE-C key]";
-class EncryptionKey {
-  /** Encryption mode discriminant. Always `'SSE-C'` for this class. */
-  mode = "SSE-C";
-  /** Encryption algorithm. B2's S3-compatible API only supports AES-256. */
-  algorithm = "AES256";
-  /** Base64-encoded 256-bit customer key. Logged as `[redacted SSE-C key]` via `toJSON` / `toString`. */
-  customerKey;
-  /** Base64-encoded MD5 digest of the customer key. Required by B2 for integrity verification. */
-  customerKeyMd5;
-  /**
-   * Internal constructor. Use {@link EncryptionKey.fromBytes} or
-   * {@link EncryptionKey.fromBase64} instead.
-   *
-   * @param customerKey - Base64-encoded 256-bit encryption key.
-   * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.
-   *
-   * @internal
-   */
-  constructor(customerKey, customerKeyMd5) {
-    this.customerKey = customerKey;
-    this.customerKeyMd5 = customerKeyMd5;
-  }
-  /**
-   * Builds an EncryptionKey from a raw 32-byte (256-bit) key. Computes the
-   * required base64 MD5 digest internally.
-   *
-   * @param rawKey - The raw 256-bit key as bytes. Must be exactly 32 bytes.
-   *
-   * @returns A safely-wrapped EncryptionKey ready for upload/download.
-   *
-   * @throws If the key is not exactly 32 bytes.
-   */
-  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);
-    return new EncryptionKey(customerKey, customerKeyMd5);
-  }
-  /**
-   * Builds an EncryptionKey from precomputed base64 strings. Use this in
-   * environments where MD5 must be computed externally (e.g., browsers).
-   *
-   * @param customerKey - Base64-encoded 256-bit encryption key.
-   * @param customerKeyMd5 - Base64-encoded MD5 digest of the key.
-   *
-   * @returns A safely-wrapped EncryptionKey ready for upload/download.
-   */
-  static fromBase64(customerKey, customerKeyMd5) {
-    return new EncryptionKey(customerKey, customerKeyMd5);
-  }
-  /**
-   * Hides the key bytes from `JSON.stringify`.
-   *
-   * @returns A redacted shape: same mode and algorithm, but the key and MD5
-   *   replaced with a placeholder string.
-   */
-  toJSON() {
-    return {
-      mode: this.mode,
-      algorithm: this.algorithm,
-      customerKey: KEY_REDACTED,
-      customerKeyMd5: KEY_REDACTED
-    };
-  }
-  /**
-   * Hides the key bytes from default `toString()`.
-   *
-   * @returns A short opaque label indicating this is an SSE-C key.
-   */
-  toString() {
-    return `[EncryptionKey SSE-C ${KEY_REDACTED}]`;
-  }
-  /**
-   * 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")]() {
-    return this.toString();
-  }
-}
-export {
-  EncryptionAlgorithm,
-  EncryptionKey,
-  EncryptionMode,
-  SSE_B2,
-  SSE_NONE,
-  sseCustomer
+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}
+* to construct one from a raw 32-byte key; the MD5 digest is computed internally.
+*/
+var EncryptionKey = class EncryptionKey {
+	/** Encryption mode discriminant. Always `'SSE-C'` for this class. */
+	mode = "SSE-C";
+	/** Encryption algorithm. B2's S3-compatible API only supports AES-256. */
+	algorithm = "AES256";
+	/** Base64-encoded 256-bit customer key. Logged as `[redacted SSE-C key]` via `toJSON` / `toString`. */
+	customerKey;
+	/** Base64-encoded MD5 digest of the customer key. Required by B2 for integrity verification. */
+	customerKeyMd5;
+	/**
+	* Internal constructor. Use {@link EncryptionKey.fromBytes} or
+	* {@link EncryptionKey.fromBase64} instead.
+	*
+	* @param customerKey - Base64-encoded 256-bit encryption key.
+	* @param customerKeyMd5 - Base64-encoded MD5 digest of the key.
+	*
+	* @internal
+	*/
+	constructor(customerKey, customerKeyMd5) {
+		this.customerKey = customerKey;
+		this.customerKeyMd5 = customerKeyMd5;
+	}
+	/**
+	* Builds an EncryptionKey from a raw 32-byte (256-bit) key. Computes the
+	* required base64 MD5 digest internally.
+	*
+	* @param rawKey - The raw 256-bit key as bytes. Must be exactly 32 bytes.
+	*
+	* @returns A safely-wrapped EncryptionKey ready for upload/download.
+	*
+	* @throws If the key is not exactly 32 bytes.
+	*/
+	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);
+		return new EncryptionKey(customerKey, customerKeyMd5);
+	}
+	/**
+	* Builds an EncryptionKey from precomputed base64 strings. Use this in
+	* environments where MD5 must be computed externally (e.g., browsers).
+	*
+	* @param customerKey - Base64-encoded 256-bit encryption key.
+	* @param customerKeyMd5 - Base64-encoded MD5 digest of the key.
+	*
+	* @returns A safely-wrapped EncryptionKey ready for upload/download.
+	*/
+	static fromBase64(customerKey, customerKeyMd5) {
+		return new EncryptionKey(customerKey, customerKeyMd5);
+	}
+	/**
+	* Hides the key bytes from `JSON.stringify`.
+	*
+	* @returns A redacted shape: same mode and algorithm, but the key and MD5
+	*   replaced with a placeholder string.
+	*/
+	toJSON() {
+		return {
+			mode: this.mode,
+			algorithm: this.algorithm,
+			customerKey: KEY_REDACTED,
+			customerKeyMd5: KEY_REDACTED
+		};
+	}
+	/**
+	* Hides the key bytes from default `toString()`.
+	*
+	* @returns A short opaque label indicating this is an SSE-C key.
+	*/
+	toString() {
+		return `[EncryptionKey SSE-C ${KEY_REDACTED}]`;
+	}
+	/**
+	* 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")]() {
+		return this.toString();
+	}
 };
-//# sourceMappingURL=encryption.js.map
+//#endregion
+export { EncryptionAlgorithm, EncryptionKey, EncryptionMode, SSE_B2, SSE_NONE, sseCustomer };
+
+//# sourceMappingURL=encryption.js.map