@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/http/url-guard.js

@@ -1,97 +1,159 @@
 import { B2SsrfError } from "../errors/index.js";
-class UrlGuard {
-  allowedSuffixes = [];
-  /**
-   * Lock the guard to the given host suffixes. A suffix matches a host
-   * either exactly or as a `*.suffix` subdomain. For example,
-   * `backblazeb2.com` allows `api.backblazeb2.com` and
-   * `s3.us-west-004.backblazeb2.com`.
-   *
-   * Passing an empty array disables the guard (used by the simulator and
-   * other test setups). Production code should always lock the guard after
-   * a successful `b2_authorize_account`.
-   *
-   * @param suffixes - Allowed host suffixes.
-   */
-  setAllowedSuffixes(suffixes) {
-    this.allowedSuffixes = suffixes;
-  }
-  /**
-   * Returns the current allowed-suffix list (for tests and diagnostics).
-   *
-   * @returns The currently-configured list of allowed host suffixes.
-   */
-  getAllowedSuffixes() {
-    return this.allowedSuffixes;
-  }
-  /**
-   * Validate `rawUrl` against the allow-list. Throws {@link B2SsrfError} if
-   * the URL points at a literal IP, a known-internal hostname, or a host
-   * outside the allowed suffixes. Permissive (no-op) when no suffixes have
-   * been configured yet.
-   *
-   * @param rawUrl - The URL the caller is about to fetch.
-   *
-   * @throws A `B2SsrfError` when the URL is rejected.
-   */
-  check(rawUrl) {
-    if (this.allowedSuffixes.length === 0) return;
-    let parsed;
-    try {
-      parsed = new URL(rawUrl);
-    } catch {
-      throw new B2SsrfError(`malformed URL rejected by SSRF guard: ${rawUrl}`, rawUrl);
-    }
-    const host = parsed.hostname.toLowerCase();
-    if (isLiteralIp(host)) {
-      throw new B2SsrfError(
-        `literal IP host not allowed by SSRF guard (use a hostname): ${host}`,
-        rawUrl
-      );
-    }
-    if (isInternalHostname(host)) {
-      throw new B2SsrfError(`internal hostname not allowed by SSRF guard: ${host}`, rawUrl);
-    }
-    for (const suffix of this.allowedSuffixes) {
-      const lowered = suffix.toLowerCase();
-      if (host === lowered || host.endsWith(`.${lowered}`)) return;
-    }
-    throw new B2SsrfError(
-      `host outside allowed B2 realm: ${host} (allowed suffixes: ${this.allowedSuffixes.join(", ")})`,
-      rawUrl
-    );
-  }
-}
+//#region src/http/url-guard.ts
+/**
+* URL allow-list guard. Defends against SSRF / URL-substitution attacks where
+* a compromised or hostile B2 endpoint returns an upload URL pointing at an
+* internal service (e.g. cloud metadata at `169.254.169.254`).
+*
+* The guard is built once per `B2Client` and updated by `B2Client.authorize()`.
+* Before authorization it is permissive (so the very first
+* `b2_authorize_account` request, whose URL the user configured, can succeed).
+* After authorization it is locked to host suffixes derived from the realm's
+* apiUrl/downloadUrl/s3ApiUrl, plus the well-known B2 upload-pod parent
+* domain `backblaze.com`.
+*
+* The guard runs in `FetchTransport` before any outgoing request. It rejects:
+*
+*   1. Literal IPv4/IPv6 addresses (defense in depth, covers attempts to
+*      bypass DNS-based checks with raw IPs).
+*   2. Well-known internal hostnames (`localhost`, `metadata`,
+*      `metadata.google.internal`, `.internal`, `.local`).
+*   3. Hosts not matching any allowed suffix once the SDK is locked.
+*
+* Users supplying a custom `transport` to `B2Client` bypass the guard. That
+* is their responsibility to document for their threat model.
+*
+* Threat-model note: the guard checks the URL's hostname before the
+* `fetch()` call. It does NOT pin the resolved IP. A DNS rebinding attack
+* could in principle resolve a permitted hostname to an internal IP between
+* the guard's check and `fetch()`'s own resolution. This is theoretical
+* against B2 because the allow-list is locked to a small set of stable
+* Backblaze hostnames (the realm's apiUrl/downloadUrl/s3ApiUrl plus the
+* `backblaze.com` parent), and DNS rebinding requires a hostname under
+* attacker control. Defense in depth — pinning the IP from the first
+* resolution and rejecting subsequent mismatches — would break legitimate
+* CDN failovers and is not justified at this surface area. If your
+* threat model requires it, supply a custom transport that does.
+*/
+/** A URL allow-list that can be reconfigured after construction. */
+var UrlGuard = class {
+	allowedSuffixes = [];
+	/**
+	* Lock the guard to the given host suffixes. A suffix matches a host
+	* either exactly or as a `*.suffix` subdomain. For example,
+	* `backblazeb2.com` allows `api.backblazeb2.com` and
+	* `s3.us-west-004.backblazeb2.com`.
+	*
+	* Passing an empty array disables the guard (used by the simulator and
+	* other test setups). Production code should always lock the guard after
+	* a successful `b2_authorize_account`.
+	*
+	* @param suffixes - Allowed host suffixes.
+	*/
+	setAllowedSuffixes(suffixes) {
+		this.allowedSuffixes = suffixes;
+	}
+	/**
+	* Returns the current allowed-suffix list (for tests and diagnostics).
+	*
+	* @returns The currently-configured list of allowed host suffixes.
+	*/
+	getAllowedSuffixes() {
+		return this.allowedSuffixes;
+	}
+	/**
+	* Validate `rawUrl` against the allow-list. Throws {@link B2SsrfError} if
+	* the URL points at a literal IP, a known-internal hostname, or a host
+	* outside the allowed suffixes. Permissive (no-op) when no suffixes have
+	* been configured yet.
+	*
+	* @param rawUrl - The URL the caller is about to fetch.
+	*
+	* @throws A `B2SsrfError` when the URL is rejected.
+	*/
+	check(rawUrl) {
+		if (this.allowedSuffixes.length === 0) return;
+		let parsed;
+		try {
+			parsed = new URL(rawUrl);
+		} catch {
+			throw new B2SsrfError(`malformed URL rejected by SSRF guard: ${rawUrl}`, rawUrl);
+		}
+		const host = parsed.hostname.toLowerCase();
+		if (isLiteralIp(host)) throw new B2SsrfError(`literal IP host not allowed by SSRF guard (use a hostname): ${host}`, rawUrl);
+		if (isInternalHostname(host)) throw new B2SsrfError(`internal hostname not allowed by SSRF guard: ${host}`, rawUrl);
+		if (hostMatchesAnyAllowedSuffix(host, this.allowedSuffixes)) return;
+		throw new B2SsrfError(`host outside allowed B2 realm: ${host} (allowed suffixes: ${this.allowedSuffixes.join(", ")})`, rawUrl);
+	}
+};
+/**
+* Extract host suffixes to allow from a B2 authorize-account response.
+*
+* Known B2 realm hosts under `backblazeb2.com` are collapsed to that parent.
+* Unknown or custom realm hosts are used as scoped suffixes: the returned
+* hostname and its subdomains are allowed, but sibling hosts and parent
+* domains are not. This avoids accidentally trusting broad public suffixes
+* such as `co.uk`.
+*
+* Always includes `backblaze.com` because upload-pod URLs returned by
+* `b2_get_upload_url` use that parent domain (`pod-NNN-NNNN-NN.backblaze.com`)
+* rather than `backblazeb2.com`.
+*
+* @param storageApi - The `apiInfo.storageApi` portion of the authorize response.
+*
+* @returns Sorted list of unique host suffixes to allow.
+*/
 function deriveAllowedSuffixes(storageApi) {
-  const suffixes = /* @__PURE__ */ new Set(["backblaze.com"]);
-  for (const url of [storageApi.apiUrl, storageApi.downloadUrl, storageApi.s3ApiUrl]) {
-    try {
-      const host = new URL(url).hostname;
-      const parts = host.split(".");
-      if (parts.length >= 2) {
-        suffixes.add(parts.slice(-2).join("."));
-      }
-    } catch {
-    }
-  }
-  return Array.from(suffixes).sort();
+	const suffixes = /* @__PURE__ */ new Set(["backblaze.com"]);
+	for (const url of [
+		storageApi.apiUrl,
+		storageApi.downloadUrl,
+		storageApi.s3ApiUrl
+	]) try {
+		const host = new URL(url).hostname;
+		suffixes.add(host === "backblazeb2.com" || host.endsWith(".backblazeb2.com") ? "backblazeb2.com" : host);
+	} catch {}
+	return Array.from(suffixes).sort();
+}
+/**
+* Checks a hostname against one allowed suffix using the SDK's exact-or-subdomain rule.
+*
+* @param hostname - URL hostname to check.
+* @param suffix - Domain suffix that may match exactly or as a parent domain.
+*
+* @returns Whether the hostname is exactly the suffix or a subdomain of it.
+*/
+function hostMatchesAllowedSuffix(hostname, suffix) {
+	const host = hostname.toLowerCase();
+	const lowered = suffix.toLowerCase();
+	return host === lowered || host.endsWith(`.${lowered}`);
+}
+/**
+* Checks a hostname against an allowed-suffix list.
+*
+* @param hostname - URL hostname to check.
+* @param suffixes - Domain suffixes to test with the SDK's suffix-matching rule.
+*
+* @returns Whether any suffix matches the hostname.
+*/
+function hostMatchesAnyAllowedSuffix(hostname, suffixes) {
+	return suffixes.some((suffix) => hostMatchesAllowedSuffix(hostname, suffix));
 }
 function isLiteralIp(host) {
-  if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) return true;
-  if (host.includes(":")) return true;
-  return false;
+	if (/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) return true;
+	if (host.includes(":")) return true;
+	return false;
 }
 function isInternalHostname(host) {
-  if (host === "localhost") return true;
-  if (host.endsWith(".localhost")) return true;
-  if (host === "metadata") return true;
-  if (host === "metadata.google.internal") return true;
-  if (host.endsWith(".internal")) return true;
-  if (host.endsWith(".local")) return true;
-  return false;
+	if (host === "localhost") return true;
+	if (host.endsWith(".localhost")) return true;
+	if (host === "metadata") return true;
+	if (host === "metadata.google.internal") return true;
+	if (host.endsWith(".internal")) return true;
+	if (host.endsWith(".local")) return true;
+	return false;
 }
-export {
-  UrlGuard,
-  deriveAllowedSuffixes
-};
-//# sourceMappingURL=url-guard.js.map
+//#endregion
+export { UrlGuard, deriveAllowedSuffixes, hostMatchesAllowedSuffix, hostMatchesAnyAllowedSuffix };
+
+//# sourceMappingURL=url-guard.js.map

package/dist/http/url-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"url-guard.js","sources":["../../src/http/url-guard.ts"],"sourcesContent":["/**\n * URL allow-list guard. Defends against SSRF / URL-substitution attacks where\n * a compromised or hostile B2 endpoint returns an upload URL pointing at an\n * internal service (e.g. cloud metadata at `169.254.169.254`).\n *\n * The guard is built once per `B2Client` and updated by `B2Client.authorize()`.\n * Before authorization it is permissive (so the very first\n * `b2_authorize_account` request, whose URL the user configured, can succeed).\n * After authorization it is locked to host suffixes derived from the realm's\n * apiUrl/downloadUrl/s3ApiUrl, plus the well-known B2 upload-pod parent\n * domain `backblaze.com`.\n *\n * The guard runs in `FetchTransport` before any outgoing request. It rejects:\n *\n *   1. Literal IPv4/IPv6 addresses (defense in depth, covers attempts to\n *      bypass DNS-based checks with raw IPs).\n *   2. Well-known internal hostnames (`localhost`, `metadata`,\n *      `metadata.google.internal`, `.internal`, `.local`).\n *   3. Hosts not matching any allowed suffix once the SDK is locked.\n *\n * Users supplying a custom `transport` to `B2Client` bypass the guard. That\n * is their responsibility to document for their threat model.\n *\n * Threat-model note: the guard checks the URL's hostname before the\n * `fetch()` call. It does NOT pin the resolved IP. A DNS rebinding attack\n * could in principle resolve a permitted hostname to an internal IP between\n * the guard's check and `fetch()`'s own resolution. This is theoretical\n * against B2 because the allow-list is locked to a small set of stable\n * Backblaze hostnames (the realm's apiUrl/downloadUrl/s3ApiUrl plus the\n * `backblaze.com` parent), and DNS rebinding requires a hostname under\n * attacker control. Defense in depth — pinning the IP from the first\n * resolution and rejecting subsequent mismatches — would break legitimate\n * CDN failovers and is not justified at this surface area. If your\n * threat model requires it, supply a custom transport that does.\n */\n\nimport { B2SsrfError } from '../errors/index.ts'\n\n/** A URL allow-list that can be reconfigured after construction. */\nexport class UrlGuard {\n  private allowedSuffixes: readonly string[] = []\n\n  /**\n   * Lock the guard to the given host suffixes. A suffix matches a host\n   * either exactly or as a `*.suffix` subdomain. For example,\n   * `backblazeb2.com` allows `api.backblazeb2.com` and\n   * `s3.us-west-004.backblazeb2.com`.\n   *\n   * Passing an empty array disables the guard (used by the simulator and\n   * other test setups). Production code should always lock the guard after\n   * a successful `b2_authorize_account`.\n   *\n   * @param suffixes - Allowed host suffixes.\n   */\n  setAllowedSuffixes(suffixes: readonly string[]): void {\n    this.allowedSuffixes = suffixes\n  }\n\n  /**\n   * Returns the current allowed-suffix list (for tests and diagnostics).\n   *\n   * @returns The currently-configured list of allowed host suffixes.\n   */\n  getAllowedSuffixes(): readonly string[] {\n    return this.allowedSuffixes\n  }\n\n  /**\n   * Validate `rawUrl` against the allow-list. Throws {@link B2SsrfError} if\n   * the URL points at a literal IP, a known-internal hostname, or a host\n   * outside the allowed suffixes. Permissive (no-op) when no suffixes have\n   * been configured yet.\n   *\n   * @param rawUrl - The URL the caller is about to fetch.\n   *\n   * @throws A `B2SsrfError` when the URL is rejected.\n   */\n  check(rawUrl: string): void {\n    if (this.allowedSuffixes.length === 0) return\n\n    let parsed: URL\n    try {\n      parsed = new URL(rawUrl)\n    } catch {\n      throw new B2SsrfError(`malformed URL rejected by SSRF guard: ${rawUrl}`, rawUrl)\n    }\n\n    const host = parsed.hostname.toLowerCase()\n\n    if (isLiteralIp(host)) {\n      throw new B2SsrfError(\n        `literal IP host not allowed by SSRF guard (use a hostname): ${host}`,\n        rawUrl,\n      )\n    }\n\n    if (isInternalHostname(host)) {\n      throw new B2SsrfError(`internal hostname not allowed by SSRF guard: ${host}`, rawUrl)\n    }\n\n    for (const suffix of this.allowedSuffixes) {\n      const lowered = suffix.toLowerCase()\n      if (host === lowered || host.endsWith(`.${lowered}`)) return\n    }\n\n    throw new B2SsrfError(\n      `host outside allowed B2 realm: ${host} (allowed suffixes: ${this.allowedSuffixes.join(', ')})`,\n      rawUrl,\n    )\n  }\n}\n\n/**\n * Extract host suffixes to allow from a B2 authorize-account response.\n *\n * Derives the parent domain (last two labels) of each realm URL — so\n * `api.us-west-004.backblazeb2.com` becomes `backblazeb2.com`. Always\n * includes `backblaze.com` because upload-pod URLs returned by\n * `b2_get_upload_url` use that parent domain (`pod-NNN-NNNN-NN.backblaze.com`)\n * rather than `backblazeb2.com`.\n *\n * @param storageApi - The `apiInfo.storageApi` portion of the authorize response.\n *\n * @returns Sorted list of unique host suffixes to allow.\n */\nexport function deriveAllowedSuffixes(storageApi: {\n  apiUrl: string\n  downloadUrl: string\n  s3ApiUrl: string\n}): readonly string[] {\n  const suffixes = new Set<string>(['backblaze.com'])\n  for (const url of [storageApi.apiUrl, storageApi.downloadUrl, storageApi.s3ApiUrl]) {\n    try {\n      const host = new URL(url).hostname\n      const parts = host.split('.')\n      if (parts.length >= 2) {\n        suffixes.add(parts.slice(-2).join('.'))\n      }\n    } catch {\n      // Skip malformed URLs. The auth response is from B2 itself; malformed\n      // entries would already have caused other failures upstream.\n    }\n  }\n  return Array.from(suffixes).sort()\n}\n\nfunction isLiteralIp(host: string): boolean {\n  // IPv4 dotted quad: e.g. 169.254.169.254\n  if (/^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$/.test(host)) return true\n  // IPv6: URL.hostname strips the brackets but keeps colons. Any colon in a\n  // hostname is an IPv6 literal.\n  if (host.includes(':')) return true\n  return false\n}\n\nfunction isInternalHostname(host: string): boolean {\n  if (host === 'localhost') return true\n  if (host.endsWith('.localhost')) return true\n  if (host === 'metadata') return true\n  if (host === 'metadata.google.internal') return true\n  if (host.endsWith('.internal')) return true\n  if (host.endsWith('.local')) return true\n  return false\n}\n"],"names":[],"mappings":";AAuCO,MAAM,SAAS;AAAA,EACZ,kBAAqC,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAc7C,mBAAmB,UAAmC;AACpD,SAAK,kBAAkB;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,qBAAwC;AACtC,WAAO,KAAK;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAM,QAAsB;AAC1B,QAAI,KAAK,gBAAgB,WAAW,EAAG;AAEvC,QAAI;AACJ,QAAI;AACF,eAAS,IAAI,IAAI,MAAM;AAAA,IACzB,QAAQ;AACN,YAAM,IAAI,YAAY,yCAAyC,MAAM,IAAI,MAAM;AAAA,IACjF;AAEA,UAAM,OAAO,OAAO,SAAS,YAAA;AAE7B,QAAI,YAAY,IAAI,GAAG;AACrB,YAAM,IAAI;AAAA,QACR,+DAA+D,IAAI;AAAA,QACnE;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,mBAAmB,IAAI,GAAG;AAC5B,YAAM,IAAI,YAAY,gDAAgD,IAAI,IAAI,MAAM;AAAA,IACtF;AAEA,eAAW,UAAU,KAAK,iBAAiB;AACzC,YAAM,UAAU,OAAO,YAAA;AACvB,UAAI,SAAS,WAAW,KAAK,SAAS,IAAI,OAAO,EAAE,EAAG;AAAA,IACxD;AAEA,UAAM,IAAI;AAAA,MACR,kCAAkC,IAAI,uBAAuB,KAAK,gBAAgB,KAAK,IAAI,CAAC;AAAA,MAC5F;AAAA,IAAA;AAAA,EAEJ;AACF;AAeO,SAAS,sBAAsB,YAIhB;AACpB,QAAM,WAAW,oBAAI,IAAY,CAAC,eAAe,CAAC;AAClD,aAAW,OAAO,CAAC,WAAW,QAAQ,WAAW,aAAa,WAAW,QAAQ,GAAG;AAClF,QAAI;AACF,YAAM,OAAO,IAAI,IAAI,GAAG,EAAE;AAC1B,YAAM,QAAQ,KAAK,MAAM,GAAG;AAC5B,UAAI,MAAM,UAAU,GAAG;AACrB,iBAAS,IAAI,MAAM,MAAM,EAAE,EAAE,KAAK,GAAG,CAAC;AAAA,MACxC;AAAA,IACF,QAAQ;AAAA,IAGR;AAAA,EACF;AACA,SAAO,MAAM,KAAK,QAAQ,EAAE,KAAA;AAC9B;AAEA,SAAS,YAAY,MAAuB;AAE1C,MAAI,uCAAuC,KAAK,IAAI,EAAG,QAAO;AAG9D,MAAI,KAAK,SAAS,GAAG,EAAG,QAAO;AAC/B,SAAO;AACT;AAEA,SAAS,mBAAmB,MAAuB;AACjD,MAAI,SAAS,YAAa,QAAO;AACjC,MAAI,KAAK,SAAS,YAAY,EAAG,QAAO;AACxC,MAAI,SAAS,WAAY,QAAO;AAChC,MAAI,SAAS,2BAA4B,QAAO;AAChD,MAAI,KAAK,SAAS,WAAW,EAAG,QAAO;AACvC,MAAI,KAAK,SAAS,QAAQ,EAAG,QAAO;AACpC,SAAO;AACT;"}
+{"version":3,"file":"url-guard.js","names":[],"sources":["../../src/http/url-guard.ts"],"sourcesContent":["/**\n * URL allow-list guard. Defends against SSRF / URL-substitution attacks where\n * a compromised or hostile B2 endpoint returns an upload URL pointing at an\n * internal service (e.g. cloud metadata at `169.254.169.254`).\n *\n * The guard is built once per `B2Client` and updated by `B2Client.authorize()`.\n * Before authorization it is permissive (so the very first\n * `b2_authorize_account` request, whose URL the user configured, can succeed).\n * After authorization it is locked to host suffixes derived from the realm's\n * apiUrl/downloadUrl/s3ApiUrl, plus the well-known B2 upload-pod parent\n * domain `backblaze.com`.\n *\n * The guard runs in `FetchTransport` before any outgoing request. It rejects:\n *\n *   1. Literal IPv4/IPv6 addresses (defense in depth, covers attempts to\n *      bypass DNS-based checks with raw IPs).\n *   2. Well-known internal hostnames (`localhost`, `metadata`,\n *      `metadata.google.internal`, `.internal`, `.local`).\n *   3. Hosts not matching any allowed suffix once the SDK is locked.\n *\n * Users supplying a custom `transport` to `B2Client` bypass the guard. That\n * is their responsibility to document for their threat model.\n *\n * Threat-model note: the guard checks the URL's hostname before the\n * `fetch()` call. It does NOT pin the resolved IP. A DNS rebinding attack\n * could in principle resolve a permitted hostname to an internal IP between\n * the guard's check and `fetch()`'s own resolution. This is theoretical\n * against B2 because the allow-list is locked to a small set of stable\n * Backblaze hostnames (the realm's apiUrl/downloadUrl/s3ApiUrl plus the\n * `backblaze.com` parent), and DNS rebinding requires a hostname under\n * attacker control. Defense in depth — pinning the IP from the first\n * resolution and rejecting subsequent mismatches — would break legitimate\n * CDN failovers and is not justified at this surface area. If your\n * threat model requires it, supply a custom transport that does.\n */\n\nimport { B2SsrfError } from '../errors/index.ts'\n\n/** A URL allow-list that can be reconfigured after construction. */\nexport class UrlGuard {\n  private allowedSuffixes: readonly string[] = []\n\n  /**\n   * Lock the guard to the given host suffixes. A suffix matches a host\n   * either exactly or as a `*.suffix` subdomain. For example,\n   * `backblazeb2.com` allows `api.backblazeb2.com` and\n   * `s3.us-west-004.backblazeb2.com`.\n   *\n   * Passing an empty array disables the guard (used by the simulator and\n   * other test setups). Production code should always lock the guard after\n   * a successful `b2_authorize_account`.\n   *\n   * @param suffixes - Allowed host suffixes.\n   */\n  setAllowedSuffixes(suffixes: readonly string[]): void {\n    this.allowedSuffixes = suffixes\n  }\n\n  /**\n   * Returns the current allowed-suffix list (for tests and diagnostics).\n   *\n   * @returns The currently-configured list of allowed host suffixes.\n   */\n  getAllowedSuffixes(): readonly string[] {\n    return this.allowedSuffixes\n  }\n\n  /**\n   * Validate `rawUrl` against the allow-list. Throws {@link B2SsrfError} if\n   * the URL points at a literal IP, a known-internal hostname, or a host\n   * outside the allowed suffixes. Permissive (no-op) when no suffixes have\n   * been configured yet.\n   *\n   * @param rawUrl - The URL the caller is about to fetch.\n   *\n   * @throws A `B2SsrfError` when the URL is rejected.\n   */\n  check(rawUrl: string): void {\n    if (this.allowedSuffixes.length === 0) return\n\n    let parsed: URL\n    try {\n      parsed = new URL(rawUrl)\n    } catch {\n      throw new B2SsrfError(`malformed URL rejected by SSRF guard: ${rawUrl}`, rawUrl)\n    }\n\n    const host = parsed.hostname.toLowerCase()\n\n    if (isLiteralIp(host)) {\n      throw new B2SsrfError(\n        `literal IP host not allowed by SSRF guard (use a hostname): ${host}`,\n        rawUrl,\n      )\n    }\n\n    if (isInternalHostname(host)) {\n      throw new B2SsrfError(`internal hostname not allowed by SSRF guard: ${host}`, rawUrl)\n    }\n\n    if (hostMatchesAnyAllowedSuffix(host, this.allowedSuffixes)) return\n\n    throw new B2SsrfError(\n      `host outside allowed B2 realm: ${host} (allowed suffixes: ${this.allowedSuffixes.join(', ')})`,\n      rawUrl,\n    )\n  }\n}\n\n/**\n * Extract host suffixes to allow from a B2 authorize-account response.\n *\n * Known B2 realm hosts under `backblazeb2.com` are collapsed to that parent.\n * Unknown or custom realm hosts are used as scoped suffixes: the returned\n * hostname and its subdomains are allowed, but sibling hosts and parent\n * domains are not. This avoids accidentally trusting broad public suffixes\n * such as `co.uk`.\n *\n * Always includes `backblaze.com` because upload-pod URLs returned by\n * `b2_get_upload_url` use that parent domain (`pod-NNN-NNNN-NN.backblaze.com`)\n * rather than `backblazeb2.com`.\n *\n * @param storageApi - The `apiInfo.storageApi` portion of the authorize response.\n *\n * @returns Sorted list of unique host suffixes to allow.\n */\nexport function deriveAllowedSuffixes(storageApi: {\n  apiUrl: string\n  downloadUrl: string\n  s3ApiUrl: string\n}): readonly string[] {\n  const suffixes = new Set<string>(['backblaze.com'])\n  for (const url of [storageApi.apiUrl, storageApi.downloadUrl, storageApi.s3ApiUrl]) {\n    try {\n      const host = new URL(url).hostname\n      suffixes.add(\n        host === 'backblazeb2.com' || host.endsWith('.backblazeb2.com') ? 'backblazeb2.com' : host,\n      )\n    } catch {\n      // Skip malformed URLs. The auth response is from B2 itself; malformed\n      // entries would already have caused other failures upstream.\n    }\n  }\n  return Array.from(suffixes).sort()\n}\n\n/**\n * Checks a hostname against one allowed suffix using the SDK's exact-or-subdomain rule.\n *\n * @param hostname - URL hostname to check.\n * @param suffix - Domain suffix that may match exactly or as a parent domain.\n *\n * @returns Whether the hostname is exactly the suffix or a subdomain of it.\n */\nexport function hostMatchesAllowedSuffix(hostname: string, suffix: string): boolean {\n  const host = hostname.toLowerCase()\n  const lowered = suffix.toLowerCase()\n  return host === lowered || host.endsWith(`.${lowered}`)\n}\n\n/**\n * Checks a hostname against an allowed-suffix list.\n *\n * @param hostname - URL hostname to check.\n * @param suffixes - Domain suffixes to test with the SDK's suffix-matching rule.\n *\n * @returns Whether any suffix matches the hostname.\n */\nexport function hostMatchesAnyAllowedSuffix(\n  hostname: string,\n  suffixes: readonly string[],\n): boolean {\n  return suffixes.some((suffix) => hostMatchesAllowedSuffix(hostname, suffix))\n}\n\nfunction isLiteralIp(host: string): boolean {\n  // IPv4 dotted quad: e.g. 169.254.169.254\n  if (/^\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}$/.test(host)) return true\n  // IPv6: URL.hostname strips the brackets but keeps colons. Any colon in a\n  // hostname is an IPv6 literal.\n  if (host.includes(':')) return true\n  return false\n}\n\nfunction isInternalHostname(host: string): boolean {\n  if (host === 'localhost') return true\n  if (host.endsWith('.localhost')) return true\n  if (host === 'metadata') return true\n  if (host === 'metadata.google.internal') return true\n  if (host.endsWith('.internal')) return true\n  if (host.endsWith('.local')) return true\n  return false\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAa,WAAb,MAAsB;CACpB,kBAA6C,CAAC;;;;;;;;;;;;;CAc9C,mBAAmB,UAAmC;EACpD,KAAK,kBAAkB;CACzB;;;;;;CAOA,qBAAwC;EACtC,OAAO,KAAK;CACd;;;;;;;;;;;CAYA,MAAM,QAAsB;EAC1B,IAAI,KAAK,gBAAgB,WAAW,GAAG;EAEvC,IAAI;EACJ,IAAI;GACF,SAAS,IAAI,IAAI,MAAM;EACzB,QAAQ;GACN,MAAM,IAAI,YAAY,yCAAyC,UAAU,MAAM;EACjF;EAEA,MAAM,OAAO,OAAO,SAAS,YAAY;EAEzC,IAAI,YAAY,IAAI,GAClB,MAAM,IAAI,YACR,+DAA+D,QAC/D,MACF;EAGF,IAAI,mBAAmB,IAAI,GACzB,MAAM,IAAI,YAAY,gDAAgD,QAAQ,MAAM;EAGtF,IAAI,4BAA4B,MAAM,KAAK,eAAe,GAAG;EAE7D,MAAM,IAAI,YACR,kCAAkC,KAAK,sBAAsB,KAAK,gBAAgB,KAAK,IAAI,EAAE,IAC7F,MACF;CACF;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,sBAAsB,YAIhB;CACpB,MAAM,2BAAW,IAAI,IAAY,CAAC,eAAe,CAAC;CAClD,KAAK,MAAM,OAAO;EAAC,WAAW;EAAQ,WAAW;EAAa,WAAW;CAAQ,GAC/E,IAAI;EACF,MAAM,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;EAC1B,SAAS,IACP,SAAS,qBAAqB,KAAK,SAAS,kBAAkB,IAAI,oBAAoB,IACxF;CACF,QAAQ,CAGR;CAEF,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,KAAK;AACnC;;;;;;;;;AAUA,SAAgB,yBAAyB,UAAkB,QAAyB;CAClF,MAAM,OAAO,SAAS,YAAY;CAClC,MAAM,UAAU,OAAO,YAAY;CACnC,OAAO,SAAS,WAAW,KAAK,SAAS,IAAI,SAAS;AACxD;;;;;;;;;AAUA,SAAgB,4BACd,UACA,UACS;CACT,OAAO,SAAS,MAAM,WAAW,yBAAyB,UAAU,MAAM,CAAC;AAC7E;AAEA,SAAS,YAAY,MAAuB;CAE1C,IAAI,uCAAuC,KAAK,IAAI,GAAG,OAAO;CAG9D,IAAI,KAAK,SAAS,GAAG,GAAG,OAAO;CAC/B,OAAO;AACT;AAEA,SAAS,mBAAmB,MAAuB;CACjD,IAAI,SAAS,aAAa,OAAO;CACjC,IAAI,KAAK,SAAS,YAAY,GAAG,OAAO;CACxC,IAAI,SAAS,YAAY,OAAO;CAChC,IAAI,SAAS,4BAA4B,OAAO;CAChD,IAAI,KAAK,SAAS,WAAW,GAAG,OAAO;CACvC,IAAI,KAAK,SAAS,QAAQ,GAAG,OAAO;CACpC,OAAO;AACT"}

package/dist/http/user-agent.cjs

@@ -1,51 +1,91 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const version = require("../version.cjs");
-const SDK_PRODUCT = "b2-sdk-typescript";
-const SDK_PACKAGE = "@backblaze-labs/b2-sdk";
+const require_version = require("../version.cjs");
+//#region src/http/user-agent.ts
+/**
+* Stable identifier Backblaze can grep server logs for to find every request
+* issued by this SDK regardless of how the User-Agent comment evolves.
+* Treat as part of the public contract: do NOT rename without coordinating.
+*/
+var SDK_PRODUCT = "b2-sdk-typescript";
+/**
+* The npm package name. Embedded in the User-Agent comment alongside
+* {@link SDK_PRODUCT} so log queries that grep on either token work.
+*/
+var SDK_PACKAGE = "@backblaze-labs/b2-sdk";
+/**
+* Best-effort detection of the JS runtime and host OS. Used to populate the
+* User-Agent comment so server-side logs can spot Bun/Deno adoption and
+* triage OS-specific issues without asking for a repro environment.
+*
+* @returns The detected runtime, OS, and architecture tokens.
+*/
 function detectPlatform() {
-  const g = globalThis;
-  if (typeof g["Deno"] !== "undefined") {
-    const deno = g["Deno"];
-    return {
-      runtime: deno.version?.deno ? `deno/${deno.version.deno}` : "deno",
-      os: deno.build?.os,
-      arch: deno.build?.arch
-    };
-  }
-  if (typeof g["Bun"] !== "undefined") {
-    const bun = g["Bun"];
-    const proc = g["process"];
-    return {
-      runtime: bun.version ? `bun/${bun.version}` : "bun",
-      os: proc?.platform,
-      arch: proc?.arch
-    };
-  }
-  if (typeof g["process"] !== "undefined") {
-    const proc = g["process"];
-    if (proc.versions?.node) {
-      return {
-        runtime: `node/${proc.versions.node}`,
-        os: proc.platform,
-        arch: proc.arch
-      };
-    }
-  }
-  if (typeof g["navigator"] !== "undefined") {
-    return { runtime: "browser", os: void 0, arch: void 0 };
-  }
-  return { runtime: "unknown", os: void 0, arch: void 0 };
+	const g = globalThis;
+	if (typeof g["Deno"] !== "undefined") {
+		const deno = g["Deno"];
+		return {
+			runtime: deno.version?.deno ? `deno/${deno.version.deno}` : "deno",
+			os: deno.build?.os,
+			arch: deno.build?.arch
+		};
+	}
+	if (typeof g["Bun"] !== "undefined") {
+		const bun = g["Bun"];
+		const proc = g["process"];
+		return {
+			runtime: bun.version ? `bun/${bun.version}` : "bun",
+			os: proc?.platform,
+			arch: proc?.arch
+		};
+	}
+	if (typeof g["process"] !== "undefined") {
+		const proc = g["process"];
+		if (proc.versions?.node) return {
+			runtime: `node/${proc.versions.node}`,
+			os: proc.platform,
+			arch: proc.arch
+		};
+	}
+	if (typeof g["navigator"] !== "undefined") return {
+		runtime: "browser",
+		os: void 0,
+		arch: void 0
+	};
+	return {
+		runtime: "unknown",
+		os: void 0,
+		arch: void 0
+	};
 }
+/**
+* Build the User-Agent header value the SDK sends on every B2 request.
+*
+* The product token, npm package name, language label, runtime, OS, and
+* architecture are emitted in that order, separated by semicolons inside a
+* single parenthesised comment block. OS and architecture are omitted on
+* runtimes that don't expose them (notably browsers). A custom prefix passed
+* via `B2ClientOptions.userAgent` is prepended verbatim so app-level
+* identifiers come first. See the README "Identifying your traffic" section
+* for examples.
+*
+* @param custom - Optional prefix prepended to the default User-Agent.
+*
+* @returns The formatted User-Agent header string.
+*/
 function getUserAgent(custom) {
-  const { runtime, os, arch } = detectPlatform();
-  const parts = ["typescript", SDK_PACKAGE, runtime];
-  if (os !== void 0) parts.push(os);
-  if (arch !== void 0) parts.push(arch);
-  const base = `${SDK_PRODUCT}/${version.VERSION} (${parts.join("; ")})`;
-  return custom ? `${custom} ${base}` : base;
+	const { runtime, os, arch } = detectPlatform();
+	const parts = [
+		"typescript",
+		SDK_PACKAGE,
+		runtime
+	];
+	if (os !== void 0) parts.push(os);
+	if (arch !== void 0) parts.push(arch);
+	const base = `${SDK_PRODUCT}/${require_version.VERSION} (${parts.join("; ")})`;
+	return custom ? `${custom} ${base}` : base;
 }
+//#endregion
 exports.SDK_PACKAGE = SDK_PACKAGE;
 exports.SDK_PRODUCT = SDK_PRODUCT;
 exports.getUserAgent = getUserAgent;
-//# sourceMappingURL=user-agent.cjs.map
+
+//# sourceMappingURL=user-agent.cjs.map

package/dist/http/user-agent.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"user-agent.cjs","sources":["../../src/http/user-agent.ts"],"sourcesContent":["import { VERSION } from '../version.ts'\n\n/**\n * Stable identifier Backblaze can grep server logs for to find every request\n * issued by this SDK regardless of how the User-Agent comment evolves.\n * Treat as part of the public contract: do NOT rename without coordinating.\n */\nexport const SDK_PRODUCT = 'b2-sdk-typescript'\n\n/**\n * The npm package name. Embedded in the User-Agent comment alongside\n * {@link SDK_PRODUCT} so log queries that grep on either token work.\n */\nexport const SDK_PACKAGE = '@backblaze-labs/b2-sdk'\n\n/** Detected runtime + OS information for the User-Agent comment. */\ninterface Platform {\n  /** Runtime identifier: `node/<x.y.z>`, `bun/<x.y.z>`, `deno/<x.y.z>`, `browser`, or `unknown`. */\n  readonly runtime: string\n  /** OS identifier (`linux`, `darwin`, `win32`, etc.) when available, or `undefined`. */\n  readonly os: string | undefined\n  /** CPU architecture (`x64`, `arm64`, etc.) when available, or `undefined`. */\n  readonly arch: string | undefined\n}\n\n/**\n * Best-effort detection of the JS runtime and host OS. Used to populate the\n * User-Agent comment so server-side logs can spot Bun/Deno adoption and\n * triage OS-specific issues without asking for a repro environment.\n *\n * @returns The detected runtime, OS, and architecture tokens.\n */\nfunction detectPlatform(): Platform {\n  const g = globalThis as Record<string, unknown>\n\n  // Deno: Deno.version.deno, Deno.build.{os,arch}.\n  if (typeof g['Deno'] !== 'undefined') {\n    const deno = g['Deno'] as {\n      version?: { deno?: string }\n      build?: { os?: string; arch?: string }\n    }\n    return {\n      runtime: deno.version?.deno ? `deno/${deno.version.deno}` : 'deno',\n      os: deno.build?.os,\n      arch: deno.build?.arch,\n    }\n  }\n\n  // Bun: globalThis.Bun.version, process.platform/arch (Bun is Node-compat).\n  if (typeof g['Bun'] !== 'undefined') {\n    const bun = g['Bun'] as { version?: string }\n    const proc = g['process'] as { platform?: string; arch?: string } | undefined\n    return {\n      runtime: bun.version ? `bun/${bun.version}` : 'bun',\n      os: proc?.platform,\n      arch: proc?.arch,\n    }\n  }\n\n  // Node: process.versions.node, process.platform, process.arch.\n  if (typeof g['process'] !== 'undefined') {\n    const proc = g['process'] as {\n      versions?: { node?: string }\n      platform?: string\n      arch?: string\n    }\n    if (proc.versions?.node) {\n      return {\n        runtime: `node/${proc.versions.node}`,\n        os: proc.platform,\n        arch: proc.arch,\n      }\n    }\n  }\n\n  // Browsers (and other navigator-only runtimes like Cloudflare Workers,\n  // Vercel Edge, etc.). We deliberately do NOT parse the existing navigator\n  // UA — that's noisy, often spoofed, and the request layer already adds the\n  // browser's own UA on top.\n  if (typeof g['navigator'] !== 'undefined') {\n    return { runtime: 'browser', os: undefined, arch: undefined }\n  }\n\n  return { runtime: 'unknown', os: undefined, arch: undefined }\n}\n\n/**\n * Build the User-Agent header value the SDK sends on every B2 request.\n *\n * The product token, npm package name, language label, runtime, OS, and\n * architecture are emitted in that order, separated by semicolons inside a\n * single parenthesised comment block. OS and architecture are omitted on\n * runtimes that don't expose them (notably browsers). A custom prefix passed\n * via `B2ClientOptions.userAgent` is prepended verbatim so app-level\n * identifiers come first. See the README \"Identifying your traffic\" section\n * for examples.\n *\n * @param custom - Optional prefix prepended to the default User-Agent.\n *\n * @returns The formatted User-Agent header string.\n */\nexport function getUserAgent(custom?: string): string {\n  const { runtime, os, arch } = detectPlatform()\n  const parts = ['typescript', SDK_PACKAGE, runtime]\n  if (os !== undefined) parts.push(os)\n  if (arch !== undefined) parts.push(arch)\n  const base = `${SDK_PRODUCT}/${VERSION} (${parts.join('; ')})`\n  return custom ? `${custom} ${base}` : base\n}\n"],"names":["VERSION"],"mappings":";;;AAOO,MAAM,cAAc;AAMpB,MAAM,cAAc;AAmB3B,SAAS,iBAA2B;AAClC,QAAM,IAAI;AAGV,MAAI,OAAO,EAAE,MAAM,MAAM,aAAa;AACpC,UAAM,OAAO,EAAE,MAAM;AAIrB,WAAO;AAAA,MACL,SAAS,KAAK,SAAS,OAAO,QAAQ,KAAK,QAAQ,IAAI,KAAK;AAAA,MAC5D,IAAI,KAAK,OAAO;AAAA,MAChB,MAAM,KAAK,OAAO;AAAA,IAAA;AAAA,EAEtB;AAGA,MAAI,OAAO,EAAE,KAAK,MAAM,aAAa;AACnC,UAAM,MAAM,EAAE,KAAK;AACnB,UAAM,OAAO,EAAE,SAAS;AACxB,WAAO;AAAA,MACL,SAAS,IAAI,UAAU,OAAO,IAAI,OAAO,KAAK;AAAA,MAC9C,IAAI,MAAM;AAAA,MACV,MAAM,MAAM;AAAA,IAAA;AAAA,EAEhB;AAGA,MAAI,OAAO,EAAE,SAAS,MAAM,aAAa;AACvC,UAAM,OAAO,EAAE,SAAS;AAKxB,QAAI,KAAK,UAAU,MAAM;AACvB,aAAO;AAAA,QACL,SAAS,QAAQ,KAAK,SAAS,IAAI;AAAA,QACnC,IAAI,KAAK;AAAA,QACT,MAAM,KAAK;AAAA,MAAA;AAAA,IAEf;AAAA,EACF;AAMA,MAAI,OAAO,EAAE,WAAW,MAAM,aAAa;AACzC,WAAO,EAAE,SAAS,WAAW,IAAI,QAAW,MAAM,OAAA;AAAA,EACpD;AAEA,SAAO,EAAE,SAAS,WAAW,IAAI,QAAW,MAAM,OAAA;AACpD;AAiBO,SAAS,aAAa,QAAyB;AACpD,QAAM,EAAE,SAAS,IAAI,KAAA,IAAS,eAAA;AAC9B,QAAM,QAAQ,CAAC,cAAc,aAAa,OAAO;AACjD,MAAI,OAAO,OAAW,OAAM,KAAK,EAAE;AACnC,MAAI,SAAS,OAAW,OAAM,KAAK,IAAI;AACvC,QAAM,OAAO,GAAG,WAAW,IAAIA,QAAAA,OAAO,KAAK,MAAM,KAAK,IAAI,CAAC;AAC3D,SAAO,SAAS,GAAG,MAAM,IAAI,IAAI,KAAK;AACxC;;;;"}
+{"version":3,"file":"user-agent.cjs","names":[],"sources":["../../src/http/user-agent.ts"],"sourcesContent":["import { VERSION } from '../version.ts'\n\n/**\n * Stable identifier Backblaze can grep server logs for to find every request\n * issued by this SDK regardless of how the User-Agent comment evolves.\n * Treat as part of the public contract: do NOT rename without coordinating.\n */\nexport const SDK_PRODUCT = 'b2-sdk-typescript'\n\n/**\n * The npm package name. Embedded in the User-Agent comment alongside\n * {@link SDK_PRODUCT} so log queries that grep on either token work.\n */\nexport const SDK_PACKAGE = '@backblaze-labs/b2-sdk'\n\n/** Detected runtime + OS information for the User-Agent comment. */\ninterface Platform {\n  /** Runtime identifier: `node/<x.y.z>`, `bun/<x.y.z>`, `deno/<x.y.z>`, `browser`, or `unknown`. */\n  readonly runtime: string\n  /** OS identifier (`linux`, `darwin`, `win32`, etc.) when available, or `undefined`. */\n  readonly os: string | undefined\n  /** CPU architecture (`x64`, `arm64`, etc.) when available, or `undefined`. */\n  readonly arch: string | undefined\n}\n\n/**\n * Best-effort detection of the JS runtime and host OS. Used to populate the\n * User-Agent comment so server-side logs can spot Bun/Deno adoption and\n * triage OS-specific issues without asking for a repro environment.\n *\n * @returns The detected runtime, OS, and architecture tokens.\n */\nfunction detectPlatform(): Platform {\n  const g = globalThis as Record<string, unknown>\n\n  // Deno: Deno.version.deno, Deno.build.{os,arch}.\n  if (typeof g['Deno'] !== 'undefined') {\n    const deno = g['Deno'] as {\n      version?: { deno?: string }\n      build?: { os?: string; arch?: string }\n    }\n    return {\n      runtime: deno.version?.deno ? `deno/${deno.version.deno}` : 'deno',\n      os: deno.build?.os,\n      arch: deno.build?.arch,\n    }\n  }\n\n  // Bun: globalThis.Bun.version, process.platform/arch (Bun is Node-compat).\n  if (typeof g['Bun'] !== 'undefined') {\n    const bun = g['Bun'] as { version?: string }\n    const proc = g['process'] as { platform?: string; arch?: string } | undefined\n    return {\n      runtime: bun.version ? `bun/${bun.version}` : 'bun',\n      os: proc?.platform,\n      arch: proc?.arch,\n    }\n  }\n\n  // Node: process.versions.node, process.platform, process.arch.\n  if (typeof g['process'] !== 'undefined') {\n    const proc = g['process'] as {\n      versions?: { node?: string }\n      platform?: string\n      arch?: string\n    }\n    if (proc.versions?.node) {\n      return {\n        runtime: `node/${proc.versions.node}`,\n        os: proc.platform,\n        arch: proc.arch,\n      }\n    }\n  }\n\n  // Browsers (and other navigator-only runtimes like Cloudflare Workers,\n  // Vercel Edge, etc.). We deliberately do NOT parse the existing navigator\n  // UA — that's noisy, often spoofed, and the request layer already adds the\n  // browser's own UA on top.\n  if (typeof g['navigator'] !== 'undefined') {\n    return { runtime: 'browser', os: undefined, arch: undefined }\n  }\n\n  return { runtime: 'unknown', os: undefined, arch: undefined }\n}\n\n/**\n * Build the User-Agent header value the SDK sends on every B2 request.\n *\n * The product token, npm package name, language label, runtime, OS, and\n * architecture are emitted in that order, separated by semicolons inside a\n * single parenthesised comment block. OS and architecture are omitted on\n * runtimes that don't expose them (notably browsers). A custom prefix passed\n * via `B2ClientOptions.userAgent` is prepended verbatim so app-level\n * identifiers come first. See the README \"Identifying your traffic\" section\n * for examples.\n *\n * @param custom - Optional prefix prepended to the default User-Agent.\n *\n * @returns The formatted User-Agent header string.\n */\nexport function getUserAgent(custom?: string): string {\n  const { runtime, os, arch } = detectPlatform()\n  const parts = ['typescript', SDK_PACKAGE, runtime]\n  if (os !== undefined) parts.push(os)\n  if (arch !== undefined) parts.push(arch)\n  const base = `${SDK_PRODUCT}/${VERSION} (${parts.join('; ')})`\n  return custom ? `${custom} ${base}` : base\n}\n"],"mappings":";;;;;;;AAOA,IAAa,cAAc;;;;;AAM3B,IAAa,cAAc;;;;;;;;AAmB3B,SAAS,iBAA2B;CAClC,MAAM,IAAI;CAGV,IAAI,OAAO,EAAE,YAAY,aAAa;EACpC,MAAM,OAAO,EAAE;EAIf,OAAO;GACL,SAAS,KAAK,SAAS,OAAO,QAAQ,KAAK,QAAQ,SAAS;GAC5D,IAAI,KAAK,OAAO;GAChB,MAAM,KAAK,OAAO;EACpB;CACF;CAGA,IAAI,OAAO,EAAE,WAAW,aAAa;EACnC,MAAM,MAAM,EAAE;EACd,MAAM,OAAO,EAAE;EACf,OAAO;GACL,SAAS,IAAI,UAAU,OAAO,IAAI,YAAY;GAC9C,IAAI,MAAM;GACV,MAAM,MAAM;EACd;CACF;CAGA,IAAI,OAAO,EAAE,eAAe,aAAa;EACvC,MAAM,OAAO,EAAE;EAKf,IAAI,KAAK,UAAU,MACjB,OAAO;GACL,SAAS,QAAQ,KAAK,SAAS;GAC/B,IAAI,KAAK;GACT,MAAM,KAAK;EACb;CAEJ;CAMA,IAAI,OAAO,EAAE,iBAAiB,aAC5B,OAAO;EAAE,SAAS;EAAW,IAAI,KAAA;EAAW,MAAM,KAAA;CAAU;CAG9D,OAAO;EAAE,SAAS;EAAW,IAAI,KAAA;EAAW,MAAM,KAAA;CAAU;AAC9D;;;;;;;;;;;;;;;;AAiBA,SAAgB,aAAa,QAAyB;CACpD,MAAM,EAAE,SAAS,IAAI,SAAS,eAAe;CAC7C,MAAM,QAAQ;EAAC;EAAc;EAAa;CAAO;CACjD,IAAI,OAAO,KAAA,GAAW,MAAM,KAAK,EAAE;CACnC,IAAI,SAAS,KAAA,GAAW,MAAM,KAAK,IAAI;CACvC,MAAM,OAAO,GAAG,YAAY,GAAG,gBAAA,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE;CAC5D,OAAO,SAAS,GAAG,OAAO,GAAG,SAAS;AACxC"}

package/dist/http/user-agent.js

@@ -1,51 +1,89 @@
 import { VERSION } from "../version.js";
-const SDK_PRODUCT = "b2-sdk-typescript";
-const SDK_PACKAGE = "@backblaze-labs/b2-sdk";
+//#region src/http/user-agent.ts
+/**
+* Stable identifier Backblaze can grep server logs for to find every request
+* issued by this SDK regardless of how the User-Agent comment evolves.
+* Treat as part of the public contract: do NOT rename without coordinating.
+*/
+var SDK_PRODUCT = "b2-sdk-typescript";
+/**
+* The npm package name. Embedded in the User-Agent comment alongside
+* {@link SDK_PRODUCT} so log queries that grep on either token work.
+*/
+var SDK_PACKAGE = "@backblaze-labs/b2-sdk";
+/**
+* Best-effort detection of the JS runtime and host OS. Used to populate the
+* User-Agent comment so server-side logs can spot Bun/Deno adoption and
+* triage OS-specific issues without asking for a repro environment.
+*
+* @returns The detected runtime, OS, and architecture tokens.
+*/
 function detectPlatform() {
-  const g = globalThis;
-  if (typeof g["Deno"] !== "undefined") {
-    const deno = g["Deno"];
-    return {
-      runtime: deno.version?.deno ? `deno/${deno.version.deno}` : "deno",
-      os: deno.build?.os,
-      arch: deno.build?.arch
-    };
-  }
-  if (typeof g["Bun"] !== "undefined") {
-    const bun = g["Bun"];
-    const proc = g["process"];
-    return {
-      runtime: bun.version ? `bun/${bun.version}` : "bun",
-      os: proc?.platform,
-      arch: proc?.arch
-    };
-  }
-  if (typeof g["process"] !== "undefined") {
-    const proc = g["process"];
-    if (proc.versions?.node) {
-      return {
-        runtime: `node/${proc.versions.node}`,
-        os: proc.platform,
-        arch: proc.arch
-      };
-    }
-  }
-  if (typeof g["navigator"] !== "undefined") {
-    return { runtime: "browser", os: void 0, arch: void 0 };
-  }
-  return { runtime: "unknown", os: void 0, arch: void 0 };
+	const g = globalThis;
+	if (typeof g["Deno"] !== "undefined") {
+		const deno = g["Deno"];
+		return {
+			runtime: deno.version?.deno ? `deno/${deno.version.deno}` : "deno",
+			os: deno.build?.os,
+			arch: deno.build?.arch
+		};
+	}
+	if (typeof g["Bun"] !== "undefined") {
+		const bun = g["Bun"];
+		const proc = g["process"];
+		return {
+			runtime: bun.version ? `bun/${bun.version}` : "bun",
+			os: proc?.platform,
+			arch: proc?.arch
+		};
+	}
+	if (typeof g["process"] !== "undefined") {
+		const proc = g["process"];
+		if (proc.versions?.node) return {
+			runtime: `node/${proc.versions.node}`,
+			os: proc.platform,
+			arch: proc.arch
+		};
+	}
+	if (typeof g["navigator"] !== "undefined") return {
+		runtime: "browser",
+		os: void 0,
+		arch: void 0
+	};
+	return {
+		runtime: "unknown",
+		os: void 0,
+		arch: void 0
+	};
 }
+/**
+* Build the User-Agent header value the SDK sends on every B2 request.
+*
+* The product token, npm package name, language label, runtime, OS, and
+* architecture are emitted in that order, separated by semicolons inside a
+* single parenthesised comment block. OS and architecture are omitted on
+* runtimes that don't expose them (notably browsers). A custom prefix passed
+* via `B2ClientOptions.userAgent` is prepended verbatim so app-level
+* identifiers come first. See the README "Identifying your traffic" section
+* for examples.
+*
+* @param custom - Optional prefix prepended to the default User-Agent.
+*
+* @returns The formatted User-Agent header string.
+*/
 function getUserAgent(custom) {
-  const { runtime, os, arch } = detectPlatform();
-  const parts = ["typescript", SDK_PACKAGE, runtime];
-  if (os !== void 0) parts.push(os);
-  if (arch !== void 0) parts.push(arch);
-  const base = `${SDK_PRODUCT}/${VERSION} (${parts.join("; ")})`;
-  return custom ? `${custom} ${base}` : base;
+	const { runtime, os, arch } = detectPlatform();
+	const parts = [
+		"typescript",
+		SDK_PACKAGE,
+		runtime
+	];
+	if (os !== void 0) parts.push(os);
+	if (arch !== void 0) parts.push(arch);
+	const base = `${SDK_PRODUCT}/${VERSION} (${parts.join("; ")})`;
+	return custom ? `${custom} ${base}` : base;
 }
-export {
-  SDK_PACKAGE,
-  SDK_PRODUCT,
-  getUserAgent
-};
-//# sourceMappingURL=user-agent.js.map
+//#endregion
+export { SDK_PACKAGE, SDK_PRODUCT, getUserAgent };
+
+//# sourceMappingURL=user-agent.js.map