@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/http/transport.js.map

@@ -1 +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":"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"}
+{"version":3,"file":"transport.js","names":[],"sources":["../../src/http/transport.ts"],"sourcesContent":["import {\n  B2Error,\n  B2RedirectError,\n  B2SsrfError,\n  classifyError,\n  ExpiredAuthTokenError,\n  NetworkError,\n} from '../errors/index.ts'\nimport type { B2ErrorResponse } from '../types/errors.ts'\nimport { computeBackoff, DEFAULT_RETRY_OPTIONS, type RetryOptions, sleep } from './retry.ts'\nimport { UrlGuard } from './url-guard.ts'\nimport { getUserAgent } from './user-agent.ts'\n\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])\nconst MAX_SAME_ORIGIN_REDIRECTS = 5\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  /** Optional per-request retry override. */\n  readonly retry?: Partial<RetryOptions>\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 * Redirect following is disabled so redirected URLs cannot bypass the guard or\n * receive credential-bearing headers without an explicit checked request.\n */\nexport class FetchTransport implements HttpTransport {\n  /** User-Agent string sent with every request. */\n  private readonly userAgent: string\n  /** Whether same-origin GET/HEAD redirects should be followed after guard checks. */\n  private readonly followSameOriginRedirects: boolean\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?: {\n    userAgent?: string\n    urlGuard?: UrlGuard\n    /**\n     * Follow same-origin GET/HEAD redirects after checking the target with the\n     * URL guard. POST redirects are still blocked to avoid replaying\n     * credential-bearing payloads to an unexpected endpoint. Defaults to true.\n     */\n    followSameOriginRedirects?: boolean\n  }) {\n    this.userAgent = getUserAgent(options?.userAgent)\n    this.followSameOriginRedirects = options?.followSameOriginRedirects ?? true\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   * @throws B2RedirectError when a response attempts to redirect.\n   */\n  async send(request: HttpRequest): Promise<HttpResponse> {\n    let currentRequest = request\n    let redirectCount = 0\n\n    while (true) {\n      this.urlGuard.check(currentRequest.url)\n\n      const headers = new Headers(currentRequest.headers)\n      if (!headers.has('User-Agent')) {\n        headers.set('User-Agent', this.userAgent)\n      }\n\n      const timeoutScope = createRequestTimeoutScope(currentRequest)\n      let response: Response\n      try {\n        response = await fetch(currentRequest.url, {\n          method: currentRequest.method,\n          headers,\n          body: currentRequest.body ?? null,\n          redirect: 'manual',\n          ...(timeoutScope.signal !== undefined ? { signal: timeoutScope.signal } : {}),\n        })\n      } catch (err) {\n        timeoutScope.dispose()\n        if (timeoutScope.timedOut) {\n          throw createRequestTimeoutError(timeoutScope)\n        }\n        throw err\n      }\n\n      if (isBlockedRedirect(response)) {\n        const location = response.headers.get('Location')\n        if (\n          this.followSameOriginRedirects &&\n          location !== null &&\n          redirectCount < MAX_SAME_ORIGIN_REDIRECTS &&\n          canFollowSameOriginRedirect(currentRequest, location)\n        ) {\n          const nextUrl = new URL(location, currentRequest.url).toString()\n          await cancelResponseBody(response)\n          timeoutScope.dispose()\n          this.urlGuard.check(nextUrl)\n          currentRequest = { ...currentRequest, url: nextUrl }\n          redirectCount += 1\n          continue\n        }\n\n        await cancelResponseBody(response)\n        timeoutScope.dispose()\n        throw new B2RedirectError(currentRequest.url, response.status, location)\n      }\n\n      return createTimedHttpResponse(response, timeoutScope)\n    }\n  }\n}\n\ninterface RequestTimeoutScope {\n  readonly signal?: AbortSignal\n  readonly timeoutMs: number\n  readonly timedOut: boolean\n  reset(): void\n  dispose(): void\n}\n\nfunction createRequestTimeoutScope(request: HttpRequest): RequestTimeoutScope {\n  const timeoutMs = request.retry?.requestTimeoutMs ?? DEFAULT_RETRY_OPTIONS.requestTimeoutMs\n  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {\n    const scope: RequestTimeoutScope = {\n      timeoutMs: 0,\n      timedOut: false,\n      reset() {},\n      dispose() {},\n    }\n    if (request.signal !== undefined) return { ...scope, signal: request.signal }\n    return scope\n  }\n\n  const controller = new AbortController()\n  let timedOut = false\n  let timer: ReturnType<typeof setTimeout>\n  const abortFromUpstream = (): void => {\n    clearTimeout(timer)\n    controller.abort(request.signal?.reason ?? new DOMException('Aborted', 'AbortError'))\n  }\n  const armTimer = (): ReturnType<typeof setTimeout> => {\n    const nextTimer = setTimeout(() => {\n      timedOut = true\n      controller.abort(new DOMException('HTTP request timed out', 'TimeoutError'))\n    }, timeoutMs)\n    unrefTimer(nextTimer)\n    return nextTimer\n  }\n  timer = armTimer()\n\n  const reset = (): void => {\n    if (timedOut || controller.signal.aborted) return\n    clearTimeout(timer)\n    timer = armTimer()\n  }\n\n  if (request.signal?.aborted === true) {\n    clearTimeout(timer)\n    abortFromUpstream()\n  } else {\n    request.signal?.addEventListener('abort', abortFromUpstream, { once: true })\n  }\n\n  return {\n    signal: controller.signal,\n    timeoutMs,\n    get timedOut() {\n      return timedOut\n    },\n    reset,\n    dispose() {\n      clearTimeout(timer)\n      request.signal?.removeEventListener('abort', abortFromUpstream)\n    },\n  }\n}\n\nfunction unrefTimer(timer: ReturnType<typeof setTimeout>): void {\n  const maybeUnref = (timer as { unref?: () => void }).unref\n  if (typeof maybeUnref === 'function') maybeUnref.call(timer)\n}\n\nfunction createRequestTimeoutError(scope: RequestTimeoutScope): DOMException {\n  return new DOMException(`HTTP request timed out after ${scope.timeoutMs} ms`, 'TimeoutError')\n}\n\nfunction createTimedHttpResponse(\n  response: Response,\n  timeoutScope: RequestTimeoutScope,\n): HttpResponse {\n  const body = response.body\n  if (body === null) timeoutScope.dispose()\n  let timedBody: ReadableStream<Uint8Array> | undefined\n\n  return {\n    status: response.status,\n    headers: response.headers,\n    get body() {\n      if (body === null) return null\n      timedBody ??= createTimedResponseBody(body, timeoutScope)\n      return timedBody\n    },\n    json: <T>() =>\n      readTimedResponseBody(timeoutScope, response, () => response.json() as Promise<T>),\n    text: () => readTimedResponseBody(timeoutScope, response, () => response.text()),\n    arrayBuffer: () => readTimedResponseBody(timeoutScope, response, () => response.arrayBuffer()),\n  }\n}\n\nasync function readTimedResponseBody<T>(\n  timeoutScope: RequestTimeoutScope,\n  response: Response,\n  read: () => Promise<T>,\n): Promise<T> {\n  try {\n    return await raceBodyReadWithAbort(timeoutScope, read(), (reason) =>\n      cancelResponseBody(response, reason),\n    )\n  } catch (err) {\n    if (timeoutScope.timedOut) {\n      throw createRequestTimeoutError(timeoutScope)\n    }\n    throw err\n  } finally {\n    timeoutScope.dispose()\n  }\n}\n\nfunction createTimedResponseBody(\n  body: ReadableStream<Uint8Array>,\n  timeoutScope: RequestTimeoutScope,\n): ReadableStream<Uint8Array> {\n  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined\n  let disposed = false\n  const dispose = (): void => {\n    if (disposed) return\n    disposed = true\n    timeoutScope.dispose()\n  }\n\n  return new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      reader ??= body.getReader()\n      try {\n        const result = await raceBodyReadWithAbort(timeoutScope, reader.read(), (reason) =>\n          reader?.cancel(reason),\n        )\n        if (result.done) {\n          dispose()\n          controller.close()\n          return\n        }\n        timeoutScope.reset()\n        controller.enqueue(result.value)\n      } catch (err) {\n        dispose()\n        if (timeoutScope.timedOut) {\n          controller.error(createRequestTimeoutError(timeoutScope))\n          return\n        }\n        controller.error(err)\n      }\n    },\n    async cancel(reason) {\n      dispose()\n      try {\n        if (reader !== undefined) {\n          await reader.cancel(reason)\n          return\n        }\n        await body.cancel(reason)\n      } catch {\n        // Best-effort cleanup when the caller cancels the wrapper body.\n      }\n    },\n  })\n}\n\nasync function raceBodyReadWithAbort<T>(\n  timeoutScope: RequestTimeoutScope,\n  read: Promise<T>,\n  abortCleanup?: ((reason: unknown) => Promise<void> | void) | undefined,\n): Promise<T> {\n  const signal = timeoutScope.signal\n  if (signal === undefined) return read\n  const abortReason = (): unknown => signal.reason ?? new DOMException('Aborted', 'AbortError')\n  if (signal.aborted) {\n    void read.catch(() => {})\n    const reason = abortReason()\n    await runAbortCleanup(abortCleanup, reason)\n    throw reason\n  }\n\n  let removeAbortListener: (() => void) | undefined\n  const abort = new Promise<never>((_, reject) => {\n    const onAbort = (): void => {\n      const reason = abortReason()\n      void read.catch(() => {})\n      reject(reason)\n      void runAbortCleanup(abortCleanup, reason)\n    }\n    signal.addEventListener('abort', onAbort, { once: true })\n    removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n  })\n\n  try {\n    return await Promise.race([read, abort])\n  } finally {\n    removeAbortListener?.()\n  }\n}\n\nasync function runAbortCleanup(\n  abortCleanup: ((reason: unknown) => Promise<void> | void) | undefined,\n  reason: unknown,\n): Promise<void> {\n  try {\n    await abortCleanup?.(reason)\n  } catch {\n    // Abort cleanup is best-effort and must not mask the abort reason.\n  }\n}\n\nfunction isBlockedRedirect(response: Response): boolean {\n  return response.type === 'opaqueredirect' || REDIRECT_STATUSES.has(response.status)\n}\n\nfunction canFollowSameOriginRedirect(request: HttpRequest, location: string): boolean {\n  if (request.method !== 'GET' && request.method !== 'HEAD') return false\n  try {\n    return new URL(request.url).origin === new URL(location, request.url).origin\n  } catch {\n    return false\n  }\n}\n\nasync function cancelResponseBody(response: Response, reason?: unknown): Promise<void> {\n  try {\n    await response.body?.cancel(reason)\n  } catch {\n    // Best-effort cleanup before throwing the primary error.\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 * Decide whether `url` points at a URL-pinned upload POST endpoint.\n *\n * @param url - Request URL to inspect.\n *\n * @returns Whether the request is a direct upload endpoint.\n */\nfunction isUploadEndpoint(url: string): boolean {\n  const endpoint = b2ApiEndpointName(url)\n  return endpoint === 'b2_upload_file' || endpoint === 'b2_upload_part'\n}\n\nfunction isFinishLargeFileEndpoint(url: string): boolean {\n  return b2ApiEndpointName(url) === 'b2_finish_large_file'\n}\n\nfunction isStartLargeFileEndpoint(url: string): boolean {\n  return b2ApiEndpointName(url) === 'b2_start_large_file'\n}\n\nfunction b2ApiEndpointName(url: string): string | undefined {\n  const [, root, , endpoint] = new URL(url).pathname.split('/')\n  if (root !== 'b2api') return undefined\n  return endpoint\n}\n\nfunction isReplayUnsafePostEndpoint(url: string): boolean {\n  return isUploadEndpoint(url) || isStartLargeFileEndpoint(url) || isFinishLargeFileEndpoint(url)\n}\n\n/**\n * Decide whether a classified error should be retried in place for `url`.\n * Transient errors normally retry; upload endpoints bubble to the upload layer\n * for fresh-URL retry except account-level 429 throttling, where fetching a new\n * upload URL only amplifies the rate limit.\n *\n * @param error - The classified, retryability-tagged error.\n * @param url - The request URL (used to detect upload endpoints).\n *\n * @returns Whether to retry the request in place.\n */\nfunction shouldRetryInPlace(error: B2Error, url: string): boolean {\n  if (!error.retryable) return false\n  if (isStartLargeFileEndpoint(url) || isFinishLargeFileEndpoint(url)) return false\n  if (isUploadEndpoint(url) && error.status === 429) return true\n  if (isUploadEndpoint(url)) return false\n  return true\n}\n\nfunction isRequestTimeoutError(err: unknown): boolean {\n  return err instanceof DOMException && err.name === 'TimeoutError'\n}\n\nfunction isTerminalTransportError(err: unknown): boolean {\n  return (\n    err instanceof B2Error ||\n    err instanceof B2RedirectError ||\n    err instanceof NetworkError ||\n    err instanceof B2SsrfError ||\n    (err instanceof DOMException && err.name === 'AbortError')\n  )\n}\n\n/**\n * Transport wrapper that adds automatic retry with exponential backoff.\n * Handles transient errors (408, 429, and the transient 5xx set 500/502/503/504),\n * expired auth tokens, and network failures. Delegates to an inner\n * {@link HttpTransport}.\n *\n * Upload endpoints (`b2_upload_file` / `b2_upload_part`) are URL-pinned. Their\n * retryable pod failures bubble to the upload layer, which evicts the failed\n * URL, fetches a fresh one, and retries there. HTTP 429 remains an in-place\n * retry so account-level throttling does not trigger extra upload URL fetches.\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    const retryOptions = { ...this.options, ...originalRequest.retry }\n    let lastError: B2Error | NetworkError | undefined\n    let didReauth = false\n    let attempt = 0\n\n    while (attempt <= retryOptions.maxRetries) {\n      throwIfSignalAborted(request.signal)\n\n      if (attempt > 0 && lastError) {\n        const retryAfter = lastError instanceof NetworkError ? undefined : lastError.retryAfter\n        const delay = computeBackoff(attempt - 1, retryOptions, retryAfter)\n        await this.sleepImpl(delay, request.signal)\n      }\n\n      try {\n        const response = await this.inner.send({ ...request, retry: retryOptions })\n        await throwIfSignalAbortedAfterResponse(request.signal, response)\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 (err) {\n          if (isRequestTimeoutError(err)) throw err\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 (\n          error instanceof ExpiredAuthTokenError &&\n          this.onReauth &&\n          !isUploadEndpoint(request.url) &&\n          !didReauth\n        ) {\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          didReauth = true\n          lastError = undefined\n          continue\n        }\n\n        if (!shouldRetryInPlace(error, request.url) || attempt === retryOptions.maxRetries) {\n          throw error\n        }\n\n        lastError = error\n        attempt += 1\n      } catch (err) {\n        throwIfSignalAborted(request.signal)\n        if (isTerminalTransportError(err)) {\n          throw err\n        }\n\n        const networkErr = new NetworkError(\n          err instanceof Error ? err.message : 'Network error',\n          err,\n        )\n\n        if (isReplayUnsafePostEndpoint(request.url) || attempt === retryOptions.maxRetries) {\n          throw networkErr\n        }\n\n        lastError = networkErr\n        attempt += 1\n      }\n    }\n\n    throw lastError ?? new NetworkError('Max retries exceeded')\n  }\n}\n\nfunction throwIfSignalAborted(signal: AbortSignal | undefined): void {\n  if (signal?.aborted === true) {\n    throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n  }\n}\n\nasync function throwIfSignalAbortedAfterResponse(\n  signal: AbortSignal | undefined,\n  response: HttpResponse,\n): Promise<void> {\n  if (signal?.aborted !== true) return\n  const reason = signal.reason ?? new DOMException('Aborted', 'AbortError')\n  try {\n    await response.body?.cancel(reason)\n  } catch {\n    // Best-effort cleanup before preserving the caller's abort reason.\n  }\n  throw reason\n}\n"],"mappings":"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"}

package/dist/http/url-guard.cjs

@@ -1,97 +1,162 @@
-"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
-    );
-  }
-}
+const require_errors_index = require("../errors/index.cjs");
+//#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 require_errors_index.B2SsrfError(`malformed URL rejected by SSRF guard: ${rawUrl}`, rawUrl);
+		}
+		const host = parsed.hostname.toLowerCase();
+		if (isLiteralIp(host)) throw new require_errors_index.B2SsrfError(`literal IP host not allowed by SSRF guard (use a hostname): ${host}`, rawUrl);
+		if (isInternalHostname(host)) throw new require_errors_index.B2SsrfError(`internal hostname not allowed by SSRF guard: ${host}`, rawUrl);
+		if (hostMatchesAnyAllowedSuffix(host, this.allowedSuffixes)) return;
+		throw new require_errors_index.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;
 }
+//#endregion
 exports.UrlGuard = UrlGuard;
 exports.deriveAllowedSuffixes = deriveAllowedSuffixes;
-//# sourceMappingURL=url-guard.cjs.map
+exports.hostMatchesAllowedSuffix = hostMatchesAllowedSuffix;
+exports.hostMatchesAnyAllowedSuffix = hostMatchesAnyAllowedSuffix;
+
+//# sourceMappingURL=url-guard.cjs.map

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

@@ -1 +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;;;"}
+{"version":3,"file":"url-guard.cjs","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,qBAAA,YAAY,yCAAyC,UAAU,MAAM;EACjF;EAEA,MAAM,OAAO,OAAO,SAAS,YAAY;EAEzC,IAAI,YAAY,IAAI,GAClB,MAAM,IAAI,qBAAA,YACR,+DAA+D,QAC/D,MACF;EAGF,IAAI,mBAAmB,IAAI,GACzB,MAAM,IAAI,qBAAA,YAAY,gDAAgD,QAAQ,MAAM;EAGtF,IAAI,4BAA4B,MAAM,KAAK,eAAe,GAAG;EAE7D,MAAM,IAAI,qBAAA,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/url-guard.d.cts

@@ -70,9 +70,13 @@ export declare class UrlGuard {
 /**
  * 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
+ * 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`.
  *
@@ -85,4 +89,22 @@ export declare function deriveAllowedSuffixes(storageApi: {
     downloadUrl: string;
     s3ApiUrl: string;
 }): readonly string[];
+/**
+ * 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.
+ */
+export declare function hostMatchesAllowedSuffix(hostname: string, suffix: string): boolean;
+/**
+ * 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.
+ */
+export declare function hostMatchesAnyAllowedSuffix(hostname: string, suffixes: readonly string[]): boolean;
 //# sourceMappingURL=url-guard.d.ts.map

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

@@ -1 +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"}
+{"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;CA8B5B;AAED;;;;;;;;;;;;;;;;GAgBG;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,CAcpB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIlF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAET"}

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

@@ -70,9 +70,13 @@ export declare class UrlGuard {
 /**
  * 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
+ * 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`.
  *
@@ -85,4 +89,22 @@ export declare function deriveAllowedSuffixes(storageApi: {
     downloadUrl: string;
     s3ApiUrl: string;
 }): readonly string[];
+/**
+ * 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.
+ */
+export declare function hostMatchesAllowedSuffix(hostname: string, suffix: string): boolean;
+/**
+ * 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.
+ */
+export declare function hostMatchesAnyAllowedSuffix(hostname: string, suffixes: readonly string[]): boolean;
 //# sourceMappingURL=url-guard.d.ts.map

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

@@ -1 +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"}
+{"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;CA8B5B;AAED;;;;;;;;;;;;;;;;GAgBG;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,CAcpB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIlF;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAET"}