@backblaze-labs/b2-sdk 0.1.0

package/dist/http/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sources":["../../src/http/transport.ts"],"sourcesContent":["import { B2Error, ExpiredAuthTokenError, NetworkError, classifyError } from '../errors/index.ts'\nimport type { B2ErrorResponse } from '../types/errors.ts'\nimport { DEFAULT_RETRY_OPTIONS, type RetryOptions, computeBackoff, sleep } from './retry.ts'\nimport { UrlGuard } from './url-guard.ts'\nimport { getUserAgent } from './user-agent.ts'\n\n/** Describes an outgoing HTTP request to the B2 API. */\nexport interface HttpRequest {\n  /** Fully qualified URL to send the request to. */\n  readonly url: string\n  /** HTTP method. B2 uses GET for downloads (HEAD to fetch only headers) and POST for all other operations. */\n  readonly method: 'GET' | 'HEAD' | 'POST'\n  /** Request headers. Authorization and content-type are typically included. */\n  readonly headers?: Record<string, string>\n  /** Request body. Used for POST requests (JSON payloads or file uploads). */\n  readonly body?: BodyInit | null\n  /** Optional abort signal for request cancellation. */\n  readonly signal?: AbortSignal\n}\n\n/** Represents a parsed HTTP response from the B2 API. */\nexport interface HttpResponse {\n  /** HTTP status code. */\n  readonly status: number\n  /** Response headers. */\n  readonly headers: Headers\n  /** Response body as a readable stream, or null for empty responses. */\n  readonly body: ReadableStream<Uint8Array> | null\n  /** Parses the response body as JSON. */\n  json<T>(): Promise<T>\n  /** Reads the response body as a UTF-8 string. */\n  text(): Promise<string>\n  /** Reads the response body as an ArrayBuffer. */\n  arrayBuffer(): Promise<ArrayBuffer>\n}\n\n/**\n * Transport layer abstraction for sending HTTP requests.\n * Implementations handle the actual network I/O and can be composed\n * (e.g. wrapping a {@link FetchTransport} with a {@link RetryTransport}).\n */\nexport interface HttpTransport {\n  /** Sends an HTTP request and returns the response. */\n  send(request: HttpRequest): Promise<HttpResponse>\n}\n\n/**\n * Default transport implementation using the global `fetch` API.\n * Automatically sets the User-Agent header on each request and applies the\n * SSRF {@link UrlGuard} (if configured) before opening the connection.\n */\nexport class FetchTransport implements HttpTransport {\n  /** User-Agent string sent with every request. */\n  private readonly userAgent: string\n  /** SSRF allow-list applied to every outgoing URL. Mutable so `B2Client.authorize()` can lock it down post-auth. */\n  readonly urlGuard: UrlGuard\n\n  /**\n   * Creates a new FetchTransport.\n   * @param options - Optional configuration: custom User-Agent prefix and SSRF guard.\n   */\n  constructor(options?: { userAgent?: string; urlGuard?: UrlGuard }) {\n    this.userAgent = getUserAgent(options?.userAgent)\n    this.urlGuard = options?.urlGuard ?? new UrlGuard()\n  }\n\n  /**\n   * Sends the request using the global `fetch` function.\n   * @param request - The HTTP request to execute.\n   *\n   * @returns The HTTP response.\n   *\n   * @throws B2SsrfError when the URL fails the configured SSRF guard.\n   */\n  async send(request: HttpRequest): Promise<HttpResponse> {\n    this.urlGuard.check(request.url)\n\n    const headers = new Headers(request.headers)\n    if (!headers.has('User-Agent')) {\n      headers.set('User-Agent', this.userAgent)\n    }\n\n    const response = await fetch(request.url, {\n      method: request.method,\n      headers,\n      body: request.body ?? null,\n      ...(request.signal !== undefined ? { signal: request.signal } : {}),\n    })\n\n    return {\n      status: response.status,\n      headers: response.headers,\n      body: response.body,\n      json: <T>() => response.json() as Promise<T>,\n      text: () => response.text(),\n      arrayBuffer: () => response.arrayBuffer(),\n    }\n  }\n}\n\n/** Configuration for {@link RetryTransport}. */\nexport interface RetryTransportOptions {\n  /** The underlying transport to delegate requests to. */\n  readonly transport: HttpTransport\n  /** Override default retry settings (max retries, delays). */\n  readonly retry?: Partial<RetryOptions>\n  /**\n   * Callback invoked on expired auth token errors. Must refresh\n   * credentials AND return the fresh auth token. The transport\n   * substitutes the new token into `request.headers.Authorization`\n   * before retrying — without this, the retried request would still\n   * carry the expired token captured by the original caller and the\n   * loop would never make progress.\n   */\n  readonly onReauth?: () => Promise<string>\n  /**\n   * Sleep implementation used between retry attempts. Defaults to the real\n   * `sleep` from `./retry.js`. Test code can inject a no-op to avoid real\n   * delays without relying on module mocking (which differs across runners).\n   *\n   * @internal\n   */\n  readonly sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>\n}\n\n/**\n * Transport wrapper that adds automatic retry with exponential backoff.\n * Handles transient B2 errors (408, 429, 503), expired auth tokens,\n * and network failures. Delegates to an inner {@link HttpTransport}.\n */\nexport class RetryTransport implements HttpTransport {\n  /** The wrapped transport that performs actual HTTP requests. */\n  private readonly inner: HttpTransport\n  /** Resolved retry options (defaults merged with user overrides). */\n  private readonly options: RetryOptions\n  /** Optional callback to refresh auth credentials on 401 — returns the fresh token. */\n  private readonly onReauth?: () => Promise<string>\n  /** Sleep implementation used between retries; injectable for tests. */\n  private readonly sleepImpl: (ms: number, signal?: AbortSignal) => Promise<void>\n\n  /**\n   * Creates a new RetryTransport.\n   * @param opts - Retry transport configuration.\n   */\n  constructor(opts: RetryTransportOptions) {\n    this.inner = opts.transport\n    this.options = { ...DEFAULT_RETRY_OPTIONS, ...opts.retry }\n    if (opts.onReauth !== undefined) this.onReauth = opts.onReauth\n    this.sleepImpl = opts.sleepImpl ?? sleep\n  }\n\n  /**\n   * Sends the request with automatic retry on transient failures.\n   * On expired auth tokens, calls {@link RetryTransportOptions.onReauth} and retries.\n   * @param originalRequest - The HTTP request to execute. The caller's\n   *   reference is not mutated; on reauth, a copy with a refreshed\n   *   Authorization header is sent.\n   *\n   * @returns The HTTP response.\n   */\n  async send(originalRequest: HttpRequest): Promise<HttpResponse> {\n    // `request` is reassigned (not mutated) when reauth produces a\n    // fresh Authorization header, so the caller's `originalRequest`\n    // stays untouched.\n    let request: HttpRequest = originalRequest\n    let lastError: B2Error | NetworkError | undefined\n\n    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {\n      if (attempt > 0 && lastError) {\n        const retryAfter = lastError instanceof NetworkError ? undefined : lastError.retryAfter\n        const delay = computeBackoff(attempt - 1, this.options, retryAfter)\n        await this.sleepImpl(delay, request.signal)\n      }\n\n      try {\n        const response = await this.inner.send(request)\n\n        if (response.status >= 200 && response.status < 300) {\n          return response\n        }\n\n        let errorBody: B2ErrorResponse\n        try {\n          errorBody = await response.json<B2ErrorResponse>()\n        } catch {\n          errorBody = {\n            status: response.status,\n            code: 'internal_error',\n            message: `HTTP ${response.status}`,\n          }\n        }\n\n        const retryAfterHeader = response.headers.get('Retry-After')\n        const retryAfterSec = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : undefined\n        const requestId = response.headers.get('X-Bz-Request-Id') ?? undefined\n\n        const error = classifyError(errorBody, {\n          ...(retryAfterSec !== undefined ? { retryAfter: retryAfterSec } : {}),\n          ...(requestId !== undefined ? { requestId } : {}),\n        })\n\n        if (error instanceof ExpiredAuthTokenError && this.onReauth) {\n          // Reauth returns the FRESH token; build a new request with a\n          // shallow-copied headers object so the Authorization swap\n          // doesn't mutate the caller's original request (which they\n          // may hold for retry / introspection). Without this swap the\n          // retry would carry the expired token captured at\n          // request-build time and bounce off the server again,\n          // exhausting the retry budget.\n          const freshToken = await this.onReauth()\n          request = {\n            ...request,\n            headers: { ...(request.headers ?? {}), Authorization: freshToken },\n          }\n          continue\n        }\n\n        if (!error.retryable || attempt === this.options.maxRetries) {\n          throw error\n        }\n\n        lastError = error\n      } catch (err) {\n        if (err instanceof B2Error || err instanceof NetworkError) {\n          throw err\n        }\n\n        if (err instanceof DOMException && err.name === 'AbortError') {\n          throw err\n        }\n\n        const networkErr = new NetworkError(\n          err instanceof Error ? err.message : 'Network error',\n          err,\n        )\n\n        if (attempt === this.options.maxRetries) {\n          throw networkErr\n        }\n\n        lastError = networkErr\n      }\n    }\n\n    throw lastError ?? new NetworkError('Max retries exceeded')\n  }\n}\n"],"names":[],"mappings":";;;;AAmDO,MAAM,eAAwC;AAAA;AAAA,EAElC;AAAA;AAAA,EAER;AAAA;AAAA;AAAA;AAAA;AAAA,EAMT,YAAY,SAAuD;AACjE,SAAK,YAAY,aAAa,SAAS,SAAS;AAChD,SAAK,WAAW,SAAS,YAAY,IAAI,SAAA;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,KAAK,SAA6C;AACtD,SAAK,SAAS,MAAM,QAAQ,GAAG;AAE/B,UAAM,UAAU,IAAI,QAAQ,QAAQ,OAAO;AAC3C,QAAI,CAAC,QAAQ,IAAI,YAAY,GAAG;AAC9B,cAAQ,IAAI,cAAc,KAAK,SAAS;AAAA,IAC1C;AAEA,UAAM,WAAW,MAAM,MAAM,QAAQ,KAAK;AAAA,MACxC,QAAQ,QAAQ;AAAA,MAChB;AAAA,MACA,MAAM,QAAQ,QAAQ;AAAA,MACtB,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,WAAW,CAAA;AAAA,IAAC,CAClE;AAED,WAAO;AAAA,MACL,QAAQ,SAAS;AAAA,MACjB,SAAS,SAAS;AAAA,MAClB,MAAM,SAAS;AAAA,MACf,MAAM,MAAS,SAAS,KAAA;AAAA,MACxB,MAAM,MAAM,SAAS,KAAA;AAAA,MACrB,aAAa,MAAM,SAAS,YAAA;AAAA,IAAY;AAAA,EAE5C;AACF;AAgCO,MAAM,eAAwC;AAAA;AAAA,EAElC;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,YAAY,MAA6B;AACvC,SAAK,QAAQ,KAAK;AAClB,SAAK,UAAU,EAAE,GAAG,uBAAuB,GAAG,KAAK,MAAA;AACnD,QAAI,KAAK,aAAa,OAAW,MAAK,WAAW,KAAK;AACtD,SAAK,YAAY,KAAK,aAAa;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAM,KAAK,iBAAqD;AAI9D,QAAI,UAAuB;AAC3B,QAAI;AAEJ,aAAS,UAAU,GAAG,WAAW,KAAK,QAAQ,YAAY,WAAW;AACnE,UAAI,UAAU,KAAK,WAAW;AAC5B,cAAM,aAAa,qBAAqB,eAAe,SAAY,UAAU;AAC7E,cAAM,QAAQ,eAAe,UAAU,GAAG,KAAK,SAAS,UAAU;AAClE,cAAM,KAAK,UAAU,OAAO,QAAQ,MAAM;AAAA,MAC5C;AAEA,UAAI;AACF,cAAM,WAAW,MAAM,KAAK,MAAM,KAAK,OAAO;AAE9C,YAAI,SAAS,UAAU,OAAO,SAAS,SAAS,KAAK;AACnD,iBAAO;AAAA,QACT;AAEA,YAAI;AACJ,YAAI;AACF,sBAAY,MAAM,SAAS,KAAA;AAAA,QAC7B,QAAQ;AACN,sBAAY;AAAA,YACV,QAAQ,SAAS;AAAA,YACjB,MAAM;AAAA,YACN,SAAS,QAAQ,SAAS,MAAM;AAAA,UAAA;AAAA,QAEpC;AAEA,cAAM,mBAAmB,SAAS,QAAQ,IAAI,aAAa;AAC3D,cAAM,gBAAgB,mBAAmB,OAAO,SAAS,kBAAkB,EAAE,IAAI;AACjF,cAAM,YAAY,SAAS,QAAQ,IAAI,iBAAiB,KAAK;AAE7D,cAAM,QAAQ,cAAc,WAAW;AAAA,UACrC,GAAI,kBAAkB,SAAY,EAAE,YAAY,cAAA,IAAkB,CAAA;AAAA,UAClE,GAAI,cAAc,SAAY,EAAE,UAAA,IAAc,CAAA;AAAA,QAAC,CAChD;AAED,YAAI,iBAAiB,yBAAyB,KAAK,UAAU;AAQ3D,gBAAM,aAAa,MAAM,KAAK,SAAA;AAC9B,oBAAU;AAAA,YACR,GAAG;AAAA,YACH,SAAS,EAAE,GAAI,QAAQ,WAAW,CAAA,GAAK,eAAe,WAAA;AAAA,UAAW;AAEnE;AAAA,QACF;AAEA,YAAI,CAAC,MAAM,aAAa,YAAY,KAAK,QAAQ,YAAY;AAC3D,gBAAM;AAAA,QACR;AAEA,oBAAY;AAAA,MACd,SAAS,KAAK;AACZ,YAAI,eAAe,WAAW,eAAe,cAAc;AACzD,gBAAM;AAAA,QACR;AAEA,YAAI,eAAe,gBAAgB,IAAI,SAAS,cAAc;AAC5D,gBAAM;AAAA,QACR;AAEA,cAAM,aAAa,IAAI;AAAA,UACrB,eAAe,QAAQ,IAAI,UAAU;AAAA,UACrC;AAAA,QAAA;AAGF,YAAI,YAAY,KAAK,QAAQ,YAAY;AACvC,gBAAM;AAAA,QACR;AAEA,oBAAY;AAAA,MACd;AAAA,IACF;AAEA,UAAM,aAAa,IAAI,aAAa,sBAAsB;AAAA,EAC5D;AACF;"}

package/dist/http/url-guard.cjs

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const errors_index = require("../errors/index.cjs");
+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 errors_index.B2SsrfError(`malformed URL rejected by SSRF guard: ${rawUrl}`, rawUrl);
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (isLiteralIp(host)) {
+      throw new errors_index.B2SsrfError(
+        `literal IP host not allowed by SSRF guard (use a hostname): ${host}`,
+        rawUrl
+      );
+    }
+    if (isInternalHostname(host)) {
+      throw new errors_index.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 errors_index.B2SsrfError(
+      `host outside allowed B2 realm: ${host} (allowed suffixes: ${this.allowedSuffixes.join(", ")})`,
+      rawUrl
+    );
+  }
+}
+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();
+}
+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;
+}
+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;
+}
+exports.UrlGuard = UrlGuard;
+exports.deriveAllowedSuffixes = deriveAllowedSuffixes;
+//# sourceMappingURL=url-guard.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"url-guard.cjs","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":["B2SsrfError"],"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,IAAIA,aAAAA,YAAY,yCAAyC,MAAM,IAAI,MAAM;AAAA,IACjF;AAEA,UAAM,OAAO,OAAO,SAAS,YAAA;AAE7B,QAAI,YAAY,IAAI,GAAG;AACrB,YAAM,IAAIA,aAAAA;AAAAA,QACR,+DAA+D,IAAI;AAAA,QACnE;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,mBAAmB,IAAI,GAAG;AAC5B,YAAM,IAAIA,aAAAA,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,IAAIA,aAAAA;AAAAA,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;;;"}

package/dist/http/url-guard.d.cts

@@ -0,0 +1,88 @@
+/**
+ * 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. */
+export declare class UrlGuard {
+    private 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: readonly string[]): void;
+    /**
+     * Returns the current allowed-suffix list (for tests and diagnostics).
+     *
+     * @returns The currently-configured list of allowed host suffixes.
+     */
+    getAllowedSuffixes(): readonly string[];
+    /**
+     * 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: string): void;
+}
+/**
+ * Extract host suffixes to allow from a B2 authorize-account response.
+ *
+ * Derives the parent domain (last two labels) of each realm URL — so
+ * `api.us-west-004.backblazeb2.com` becomes `backblazeb2.com`. 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.
+ */
+export declare function deriveAllowedSuffixes(storageApi: {
+    apiUrl: string;
+    downloadUrl: string;
+    s3ApiUrl: string;
+}): readonly string[];
+//# sourceMappingURL=url-guard.d.ts.map

package/dist/http/url-guard.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-guard.d.ts","sourceRoot":"","sources":["../../src/http/url-guard.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,oEAAoE;AACpE,qBAAa,QAAQ;IACnB,OAAO,CAAC,eAAe,CAAwB;IAE/C;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAIrD;;;;OAIG;IACH,kBAAkB,IAAI,SAAS,MAAM,EAAE;IAIvC;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAiC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,SAAS,MAAM,EAAE,CAepB"}

package/dist/http/url-guard.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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. */
+export declare class UrlGuard {
+    private 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: readonly string[]): void;
+    /**
+     * Returns the current allowed-suffix list (for tests and diagnostics).
+     *
+     * @returns The currently-configured list of allowed host suffixes.
+     */
+    getAllowedSuffixes(): readonly string[];
+    /**
+     * 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: string): void;
+}
+/**
+ * Extract host suffixes to allow from a B2 authorize-account response.
+ *
+ * Derives the parent domain (last two labels) of each realm URL — so
+ * `api.us-west-004.backblazeb2.com` becomes `backblazeb2.com`. 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.
+ */
+export declare function deriveAllowedSuffixes(storageApi: {
+    apiUrl: string;
+    downloadUrl: string;
+    s3ApiUrl: string;
+}): readonly string[];
+//# sourceMappingURL=url-guard.d.ts.map

package/dist/http/url-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-guard.d.ts","sourceRoot":"","sources":["../../src/http/url-guard.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,oEAAoE;AACpE,qBAAa,QAAQ;IACnB,OAAO,CAAC,eAAe,CAAwB;IAE/C;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAIrD;;;;OAIG;IACH,kBAAkB,IAAI,SAAS,MAAM,EAAE;IAIvC;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAiC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,SAAS,MAAM,EAAE,CAepB"}

package/dist/http/url-guard.js

@@ -0,0 +1,97 @@
+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
+    );
+  }
+}
+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();
+}
+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;
+}
+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;
+}
+export {
+  UrlGuard,
+  deriveAllowedSuffixes
+};
+//# sourceMappingURL=url-guard.js.map

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

@@ -0,0 +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;"}

package/dist/http/user-agent.cjs

@@ -0,0 +1,51 @@
+"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";
+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 };
+}
+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;
+}
+exports.SDK_PACKAGE = SDK_PACKAGE;
+exports.SDK_PRODUCT = SDK_PRODUCT;
+exports.getUserAgent = getUserAgent;
+//# sourceMappingURL=user-agent.cjs.map

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

@@ -0,0 +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;;;;"}

package/dist/http/user-agent.d.cts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare const SDK_PACKAGE = "@backblaze-labs/b2-sdk";
+/**
+ * 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.
+ */
+export declare function getUserAgent(custom?: string): string;
+//# sourceMappingURL=user-agent.d.ts.map

package/dist/http/user-agent.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.d.ts","sourceRoot":"","sources":["../../src/http/user-agent.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,WAAW,sBAAsB,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,WAAW,2BAA2B,CAAA;AAyEnD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAOpD"}

package/dist/http/user-agent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare const SDK_PACKAGE = "@backblaze-labs/b2-sdk";
+/**
+ * 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.
+ */
+export declare function getUserAgent(custom?: string): string;
+//# sourceMappingURL=user-agent.d.ts.map

package/dist/http/user-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.d.ts","sourceRoot":"","sources":["../../src/http/user-agent.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,WAAW,sBAAsB,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,WAAW,2BAA2B,CAAA;AAyEnD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAOpD"}

package/dist/http/user-agent.js

@@ -0,0 +1,51 @@
+import { VERSION } from "../version.js";
+const SDK_PRODUCT = "b2-sdk-typescript";
+const SDK_PACKAGE = "@backblaze-labs/b2-sdk";
+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 };
+}
+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;
+}
+export {
+  SDK_PACKAGE,
+  SDK_PRODUCT,
+  getUserAgent
+};
+//# sourceMappingURL=user-agent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.js","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":[],"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,IAAI,OAAO,KAAK,MAAM,KAAK,IAAI,CAAC;AAC3D,SAAO,SAAS,GAAG,MAAM,IAAI,IAAI,KAAK;AACxC;"}