lifecycleion 0.0.8 → 0.0.10

package/dist/lib/http-client-mock/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/http-client-mock/index.ts","../../../src/lib/http-client/adapters/mock-adapter.ts","../../../src/lib/sleep.ts","../../../src/lib/http-client/consts.ts","../../../src/lib/http-client/utils.ts","../../../src/lib/domain-utils/domain-utils.ts","../../../src/lib/domain-utils/helpers.ts"],"sourcesContent":["export { MockAdapter } from '../http-client/adapters/mock-adapter';\nexport type {\n  MockAdapterConfig,\n  MockAdapterRoutes,\n  MockRequest,\n  MockResponse,\n  MockRouteHandler,\n  MockFormData,\n  MockCookieOptions,\n} from '../http-client/adapters/mock-adapter';\n","import Router from 'find-my-way';\nimport qs from 'qs';\nimport { sleep } from '../../sleep';\nimport { REDIRECT_STATUS_CODES } from '../consts';\nimport {\n  isPlainJSONBodyObject,\n  normalizeAdapterResponseHeaders,\n  parseContentType,\n  resolveDetectedRedirectURL,\n} from '../utils';\nimport type {\n  HTTPAdapter,\n  AdapterRequest,\n  AdapterResponse,\n  AdapterType,\n  ContentType,\n  QueryObject,\n} from '../types';\n\nexport interface MockFormData {\n  /** String fields from the multipart body */\n  fields: Record<string, string>;\n  /** File fields from the multipart body */\n  files: Record<string, File>;\n}\n\nexport interface MockRequest {\n  method: string;\n  path: string;\n  params: Record<string, string>;\n  query: QueryObject;\n  headers: Record<string, string>;\n  /**\n   * Parsed cookies from the `cookie` request header — same data as\n   * `headers.cookie`, pre-parsed for convenience.\n   */\n  cookies: Record<string, string>;\n  /**\n   * Parsed request body for mock handlers.\n   * JSON bodies are parsed, text bodies stay strings, binary bodies stay as\n   * `Uint8Array`, and multipart/form-data bodies become `MockFormData`.\n   */\n  body?: unknown;\n}\n\n/** Cookie attributes for the `MockResponse.cookies` shorthand. */\nexport interface MockCookieOptions {\n  value: string;\n  /** Seconds until the cookie expires. Use `0` or a negative value to expire it immediately. */\n  maxAge?: number;\n  httpOnly?: boolean;\n  secure?: boolean;\n  sameSite?: 'Strict' | 'Lax' | 'None';\n  /** Defaults to `'/'` when omitted. */\n  path?: string;\n  domain?: string;\n}\n\nexport interface MockResponse {\n  status: number;\n  /**\n   * Response entity body. Aligned with outgoing request rules in `serializeBody`\n   * / `assertSupportedRequestBody`, except mock responses do not use `FormData`.\n   *\n   * Supported values (anything else throws when serialized):\n   *\n   * - `undefined` or omitted — no body\n   * - `null` — no body\n   * - `string` — UTF-8 bytes\n   * - `Uint8Array` — raw bytes unchanged\n   * - `ArrayBuffer` — copied to a `Uint8Array`\n   * - plain object (`Object.prototype` or `null` prototype) — JSON\n   * - array — JSON\n   */\n  body?: unknown;\n  /**\n   * Raw response headers. Use `set-cookie: string[]` for multiple cookies,\n   * same as real HTTP. Merged with any entries from `cookies`.\n   */\n  headers?: Record<string, string | string[]>;\n  contentType?: ContentType;\n  delay?: number;\n  /**\n   * Shorthand for setting / deleting cookies without writing raw Set-Cookie\n   * strings. Merged with any `set-cookie` entries already in `headers`.\n   *\n   * - `string` → `name=value; Path=/` — session cookie (no expiry)\n   * - `null` → `name=; Path=/; Max-Age=0` — deletes that same default\n   *   root-scoped cookie\n   * - `MockCookieOptions` → full control over path, domain, and attributes;\n   *   when deleting one of these scoped cookies, the delete cookie must use\n   *   the same identity (name + path + domain) and typically `maxAge: 0`\n   */\n  cookies?: Record<string, string | MockCookieOptions | null>;\n}\n\nexport type MockRouteHandler = (\n  request: MockRequest,\n) => MockResponse | Promise<MockResponse>;\n\nexport interface MockAdapterConfig {\n  defaultDelay?: number;\n  /**\n   * Called when a route handler throws. Return a `MockResponse` to customize\n   * the error response — similar to Fastify's `setErrorHandler`. Falls back to\n   * the default `{ status: 500, body: { message: 'Internal Server Error' } }`\n   * if this handler is not set or if it also throws.\n   */\n  onError?: (\n    req: MockRequest,\n    error: unknown,\n  ) => MockResponse | Promise<MockResponse>;\n}\n\n/**\n * Routes match on **path only** — the domain/host in the request URL is\n * stripped before matching. `http://api.test/users` and\n * `http://auth.test/users` both match a registered `/users` route.\n *\n * **Multiple domains** — use separate `MockAdapter` instances and assign\n * them to the root client and sub-clients respectively:\n *\n * ```ts\n * const apiMock = new MockAdapter();\n * const authMock = new MockAdapter();\n * const client = new HTTPClient({ adapter: apiMock, baseURL: 'https://api.test' });\n * const authClient = client.createSubClient({ adapter: authMock, baseURL: 'https://auth.test' });\n * ```\n *\n * **Cross-domain redirects** — redirects are followed by the same adapter\n * that initiated the request. Since domain is stripped, a redirect to\n * `https://auth.test/callback` will match a `/callback` route on the\n * originating adapter — no special setup needed for single-adapter setups.\n * For separate-adapter setups, register the redirect target path on the\n * originating adapter as well.\n */\n\nexport interface MockAdapterRoutes {\n  get(path: string, handler: MockRouteHandler): void;\n  post(path: string, handler: MockRouteHandler): void;\n  put(path: string, handler: MockRouteHandler): void;\n  patch(path: string, handler: MockRouteHandler): void;\n  delete(path: string, handler: MockRouteHandler): void;\n  head(path: string, handler: MockRouteHandler): void;\n  /** Remove all registered routes. */\n  clear(): void;\n}\n\n// find-my-way requires a handler function; the actual MockRouteHandler lives in store.\nconst noop: Router.Handler<Router.HTTPVersion.V1> = () => {};\n\nexport class MockAdapter implements HTTPAdapter {\n  public readonly routes: MockAdapterRoutes;\n  private readonly router: Router.Instance<Router.HTTPVersion.V1>;\n  private readonly config: MockAdapterConfig;\n\n  constructor(config?: MockAdapterConfig) {\n    this.config = config ?? {};\n\n    this.router = Router({\n      ignoreTrailingSlash: true,\n      ignoreDuplicateSlashes: false,\n      maxParamLength: 100,\n    });\n\n    this.routes = buildRoutes(this.router);\n  }\n\n  public getType(): AdapterType {\n    return 'mock';\n  }\n\n  public async send(request: AdapterRequest): Promise<AdapterResponse> {\n    const { requestURL, method, headers, body } = request;\n    const materializedHeaders = materializeMockRequestHeaders(headers);\n\n    // --- 1. Pre-flight abort check ---\n    // Throw immediately if the signal was already cancelled before we even start.\n    if (request.signal?.aborted) {\n      throwAbortError();\n    }\n\n    // Signal 0% upload — upload is instant for mock, but we fire the event so\n    // progress listeners see the same shape they would from FetchAdapter.\n    request.onUploadProgress?.({ loaded: 0, total: 0, progress: 0 });\n\n    // --- 2. Parse URL ---\n    // Strip host so routes match on path only — same behavior regardless of\n    // whether the client passed an absolute URL (https://api.test/users) or a\n    // path-only URL (/users). Falls back to manual splitting for path-only URLs\n    // that `new URL()` would reject.\n    let path: string;\n    let queryString: string;\n\n    try {\n      const url = new URL(requestURL);\n      path = url.pathname;\n      queryString = url.search.slice(1);\n    } catch {\n      const qIdx = requestURL.indexOf('?');\n\n      if (qIdx >= 0) {\n        path = requestURL.slice(0, qIdx);\n        queryString = requestURL.slice(qIdx + 1);\n      } else {\n        path = requestURL;\n        queryString = '';\n      }\n    }\n\n    // --- 3. Route match & build MockRequest ---\n    // qs handles nested bracket notation (e.g. ?where[active]=true).\n    // cookies are pre-parsed from the `cookie` header for convenience —\n    // the raw header is still available on req.headers.cookie.\n    const query = qs.parse(queryString) as QueryObject;\n    const cookies = parseCookieHeader(materializedHeaders['cookie']);\n    const match = this.router.find(method as Router.HTTPMethod, path);\n    const params = (match?.params ?? {}) as Record<string, string>;\n\n    const mockRequest: MockRequest = {\n      method,\n      path,\n      params,\n      query,\n      headers: materializedHeaders,\n      cookies,\n      body:\n        body instanceof FormData\n          ? extractFormData(body)\n          : parseRequestBody(body, materializedHeaders['content-type']),\n    };\n\n    // --- 4. Invoke handler ---\n    // No registered route → default 404.\n    // To customize the 404 body, register a wildcard route:\n    //   adapter.routes.get('/*', (req) => ({ status: 404, body: { error: '...' } }))\n    //\n    // While if a handler throws → onError (if set),\n    // then falls back to default 500 if onError is unset or also throws.\n\n    let mockResponse: MockResponse;\n\n    if (match === null) {\n      mockResponse = { status: 404, body: { message: 'Not Found' } };\n    } else {\n      const handler = match.store as MockRouteHandler;\n\n      try {\n        // Match real network semantics more closely: once the caller aborts,\n        // stop waiting on an async mock handler and reject immediately.\n        mockResponse = await awaitAbortable(\n          handler(mockRequest),\n          request.signal,\n        );\n      } catch (handlerError) {\n        if (isInternalAbortError(handlerError)) {\n          throwAbortError();\n        }\n\n        if (this.config.onError) {\n          try {\n            mockResponse = await awaitAbortable(\n              this.config.onError(mockRequest, handlerError),\n              request.signal,\n            );\n          } catch (error) {\n            if (isInternalAbortError(error)) {\n              throwAbortError();\n            }\n\n            mockResponse = {\n              status: 500,\n              body: { message: 'Internal Server Error' },\n            };\n          }\n        } else {\n          mockResponse = {\n            status: 500,\n            body: { message: 'Internal Server Error' },\n          };\n        }\n      }\n    }\n\n    // --- 5. Delay ---\n    // Simulates network latency. Per-response delay takes priority over the\n    // adapter default. When a signal is present, the sleep is abort-aware and\n    // throws AbortError immediately instead of waiting out the full duration.\n    const delay = mockResponse.delay ?? this.config.defaultDelay ?? 0;\n\n    if (delay > 0) {\n      // Use abort-aware sleep when a signal is present so cancellation throws\n      // immediately rather than waiting for the full delay to elapse.\n      if (request.signal) {\n        await sleepAbortable(delay, request.signal);\n      } else {\n        await sleep(delay);\n      }\n    }\n\n    // --- 6. Post-delay abort check ---\n    // Catches cancellation when there was no delay (or delay was 0).\n    if (request.signal?.aborted) {\n      throwAbortError();\n    }\n\n    // HEAD / 204 / 304 never expose a body to consumers, even if the handler\n    // returned one. This keeps the mock transport aligned with real HTTP.\n    const responseBody = shouldOmitResponseBody(method, mockResponse.status)\n      ? null\n      : serializeResponseBody(mockResponse);\n\n    // Signal upload complete, then report download size based on serialised body.\n    request.onUploadProgress?.({ loaded: 1, total: 1, progress: 1 });\n\n    request.onDownloadProgress?.({\n      loaded: responseBody?.length ?? 0,\n      total: responseBody?.length ?? 0,\n      progress: 1,\n    });\n\n    // --- 7. Build response headers ---\n    const responseHeaders: AdapterResponse['headers'] = {\n      ...(mockResponse.headers ?? {}),\n    };\n\n    // Merge cookies shorthand into set-cookie headers.\n    // Entries from `cookies` are APPENDED after any existing `headers['set-cookie']`\n    // entries — they are not overwritten. If both set the same cookie name, the\n    // shorthand entry wins because it appears last (last Set-Cookie header for a\n    // given name takes precedence in browsers and CookieJar).\n    if (mockResponse.cookies) {\n      const setCookieEntries = cookiesToSetCookieHeaders(mockResponse.cookies);\n\n      if (setCookieEntries.length > 0) {\n        const existing = responseHeaders['set-cookie'];\n        const existingArr =\n          existing === undefined\n            ? []\n            : Array.isArray(existing)\n              ? existing\n              : [existing];\n        responseHeaders['set-cookie'] = [...existingArr, ...setCookieEntries];\n      }\n    }\n\n    // Auto-set content-type when handler didn't provide one.\n    // Binary responses are intentionally skipped — content-type for binary is\n    // format-specific (image/png, application/pdf, etc.) so the handler is\n    // responsible for setting it via `headers` when it matters.\n    if (!hasHeader(responseHeaders, 'content-type') && responseBody !== null) {\n      const ct =\n        mockResponse.contentType ?? inferContentType(mockResponse.body);\n\n      if (ct === 'json') {\n        responseHeaders['content-type'] = 'application/json';\n      } else if (ct === 'text') {\n        responseHeaders['content-type'] = 'text/plain';\n      }\n    }\n\n    const normalizedResponseHeaders =\n      normalizeAdapterResponseHeaders(responseHeaders);\n\n    const detectedRedirectURL = resolveDetectedRedirectURL(\n      request.requestURL,\n      mockResponse.status,\n      normalizedResponseHeaders,\n    );\n\n    return {\n      status: mockResponse.status,\n      wasRedirectDetected: REDIRECT_STATUS_CODES.has(mockResponse.status),\n      ...(detectedRedirectURL ? { detectedRedirectURL } : {}),\n      headers: normalizedResponseHeaders,\n      body: responseBody,\n    };\n  }\n}\n\n// --- Helpers ---\n\nfunction buildRoutes(\n  router: Router.Instance<Router.HTTPVersion.V1>,\n): MockAdapterRoutes {\n  function on(\n    method: Router.HTTPMethod,\n    path: string,\n    handler: MockRouteHandler,\n  ): void {\n    try {\n      router.on(method, path, noop, handler);\n    } catch (error) {\n      if (isDuplicateRouteRegistrationError(error)) {\n        throw duplicateRouteRegistrationError(method, path, error);\n      }\n\n      throw error;\n    }\n  }\n\n  return {\n    get: (path, handler) => on('GET', path, handler),\n    post: (path, handler) => on('POST', path, handler),\n    put: (path, handler) => on('PUT', path, handler),\n    patch: (path, handler) => on('PATCH', path, handler),\n    delete: (path, handler) => on('DELETE', path, handler),\n    head: (path, handler) => on('HEAD', path, handler),\n    clear: () => router.reset(),\n  };\n}\n\nfunction isDuplicateRouteRegistrationError(error: unknown): error is Error {\n  return (\n    error instanceof Error &&\n    error.message.includes('already declared for route')\n  );\n}\n\nfunction duplicateRouteRegistrationError(\n  method: Router.HTTPMethod,\n  path: string,\n  cause: Error,\n): Error {\n  return new Error(\n    `[MockAdapter] Duplicate route registration for ${method} ${path}. ` +\n      'Routes must be unique per method and normalized path.',\n    { cause },\n  );\n}\n\nfunction parseCookieHeader(\n  cookieHeader: string | undefined,\n): Record<string, string> {\n  if (!cookieHeader) {\n    return {};\n  }\n\n  const cookies: Record<string, string> = {};\n\n  for (const part of cookieHeader.split(';')) {\n    const eqIdx = part.indexOf('=');\n\n    if (eqIdx < 0) {\n      continue;\n    }\n\n    const name = part.slice(0, eqIdx).trim();\n    const value = part.slice(eqIdx + 1).trim();\n\n    if (name) {\n      cookies[name] = value;\n    }\n  }\n\n  return cookies;\n}\n\nfunction materializeMockRequestHeaders(\n  headers: Record<string, string | string[]>,\n): Record<string, string> {\n  const result: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(headers)) {\n    result[key] = Array.isArray(value)\n      ? key.toLowerCase() === 'cookie'\n        ? value.join('; ')\n        : value.join(', ')\n      : value;\n  }\n\n  return result;\n}\n\nfunction cookiesToSetCookieHeaders(\n  cookies: Record<string, string | MockCookieOptions | null>,\n): string[] {\n  return Object.entries(cookies).map(([name, value]) => {\n    // null pairs with the string shorthand above: both use Path=/.\n    // Scoped deletes need explicit path/domain so the cookie identity matches.\n    if (value === null) {\n      return `${name}=; Path=/; Max-Age=0`;\n    }\n\n    // string → session cookie: no expiry, defaults to Path=/.\n    if (typeof value === 'string') {\n      return `${name}=${value}; Path=/`;\n    }\n\n    return serializeMockCookieOptions(name, value);\n  });\n}\n\nfunction serializeMockCookieOptions(\n  name: string,\n  cookie: MockCookieOptions,\n): string {\n  const parts: string[] = [\n    `${name}=${cookie.value}`,\n    `Path=${cookie.path ?? '/'}`,\n  ];\n\n  appendCookieAttribute(parts, 'Max-Age', cookie.maxAge);\n  appendCookieAttribute(parts, 'Domain', cookie.domain);\n\n  if (cookie.httpOnly) {\n    parts.push('HttpOnly');\n  }\n\n  if (cookie.secure) {\n    parts.push('Secure');\n  }\n\n  appendCookieAttribute(parts, 'SameSite', cookie.sameSite);\n\n  return parts.join('; ');\n}\n\nfunction appendCookieAttribute(\n  parts: string[],\n  name: string,\n  value: number | string | undefined,\n): void {\n  if (value !== undefined && value !== '') {\n    parts.push(`${name}=${value}`);\n  }\n}\n\nfunction extractFormData(fd: FormData): MockFormData {\n  const fields: Record<string, string> = {};\n  const files: Record<string, File> = {};\n\n  for (const [key, value] of fd.entries()) {\n    if (typeof value === 'string') {\n      fields[key] = value;\n    } else {\n      files[key] = value;\n    }\n  }\n\n  return { fields, files };\n}\n\nfunction parseRequestBody(\n  body: string | Uint8Array | null | undefined,\n  contentType: string | undefined,\n): unknown {\n  if (body === null || body === undefined) {\n    return undefined;\n  }\n\n  const parsedContentType = parseContentType(contentType);\n\n  if (body instanceof Uint8Array) {\n    // Keep opaque bytes intact so mock handlers can inspect binary payloads\n    // like uploads or octet-stream requests without lossy text decoding.\n    if (parsedContentType === 'binary') {\n      return body;\n    } else if (parsedContentType === 'json') {\n      // JSON requests arrive as bytes from the adapter layer, so decode first\n      // and then match the client response path by attempting JSON.parse().\n      const text = new TextDecoder().decode(body);\n\n      try {\n        return JSON.parse(text);\n      } catch {\n        return text;\n      }\n    } else if (parsedContentType === 'text') {\n      // Text-like bodies should be exposed to mock handlers as plain strings.\n      return new TextDecoder().decode(body);\n    }\n  } else if (parsedContentType === 'json') {\n    // String bodies can still declare JSON; parse when possible but preserve\n    // the original string if the payload is invalid JSON.\n    try {\n      return JSON.parse(body);\n    } catch {\n      return body;\n    }\n  }\n\n  // Plain strings with non-JSON content types are already in the desired form.\n  return body;\n}\n\nfunction serializeResponseBody(response: MockResponse): Uint8Array | null {\n  const { body } = response;\n\n  if (body === undefined || body === null) {\n    return null;\n  } else if (body instanceof Uint8Array) {\n    // Avoid JSON.stringify indexing the buffer into {\"0\":…,\"1\":…}.\n    return body;\n  } else if (body instanceof ArrayBuffer) {\n    return new Uint8Array(body);\n  } else if (typeof body === 'string') {\n    return new TextEncoder().encode(body);\n  } else if (Array.isArray(body) || isPlainJSONBodyObject(body)) {\n    return new TextEncoder().encode(JSON.stringify(body));\n  }\n\n  throw new Error(\n    'Unsupported mock response body type. Supported types: string, Uint8Array, ArrayBuffer, plain object, array, null, and undefined.',\n  );\n}\n\nfunction inferContentType(body: unknown): ContentType {\n  if (typeof body === 'string') {\n    return 'text';\n  } else if (body instanceof Uint8Array || body instanceof ArrayBuffer) {\n    return 'binary';\n  } else {\n    return 'json';\n  }\n}\n\nfunction hasHeader(\n  headers: Record<string, string | string[]>,\n  name: string,\n): boolean {\n  return Object.keys(headers).some(\n    (k) => k.toLowerCase() === name.toLowerCase(),\n  );\n}\n\nclass InternalMockAbortError extends Error {\n  constructor() {\n    super('The operation was aborted.');\n    this.name = 'AbortError';\n  }\n}\n\nfunction isInternalAbortError(error: unknown): error is InternalMockAbortError {\n  return error instanceof InternalMockAbortError;\n}\n\nfunction throwAbortError(): never {\n  const err = new Error('The operation was aborted.');\n  err.name = 'AbortError';\n  throw err;\n}\n\nfunction shouldOmitResponseBody(method: string, status: number): boolean {\n  return method === 'HEAD' || status === 204 || status === 304;\n}\n\nfunction awaitAbortable<T>(\n  value: T | Promise<T>,\n  signal: AbortSignal | undefined,\n): Promise<T> {\n  if (!signal) {\n    return Promise.resolve(value);\n  }\n\n  if (signal.aborted) {\n    throw new InternalMockAbortError();\n  }\n\n  return new Promise<T>((resolve, reject) => {\n    // Cancellation should reject immediately with AbortError, even if the\n    // wrapped handler/onError promise is still pending.\n    const onAbort = () => {\n      signal.removeEventListener('abort', onAbort);\n      reject(new InternalMockAbortError());\n    };\n\n    signal.addEventListener('abort', onAbort, { once: true });\n\n    Promise.resolve(value).then(\n      (result) => {\n        signal.removeEventListener('abort', onAbort);\n        resolve(result);\n      },\n      (error) => {\n        signal.removeEventListener('abort', onAbort);\n        // Preserve real handler failures, only normalize non-Error rejections\n        // so promise rejection values stay lint-safe and predictable.\n        reject(error instanceof Error ? error : new Error(String(error)));\n      },\n    );\n  });\n}\n\n/**\n * Like `sleep()` but throws AbortError immediately if the signal fires during\n * the delay rather than waiting for the full duration to elapse. Cleans up\n * both the timer and the abort listener to avoid leaks.\n */\nfunction sleepAbortable(ms: number, signal: AbortSignal): Promise<void> {\n  if (signal.aborted) {\n    throw new InternalMockAbortError();\n  }\n\n  return new Promise<void>((resolve, reject) => {\n    const onAbort = () => {\n      clearTimeout(id);\n      reject(new InternalMockAbortError());\n    };\n\n    const id = setTimeout(() => {\n      signal.removeEventListener('abort', onAbort);\n      resolve();\n    }, ms);\n\n    signal.addEventListener('abort', onAbort, { once: true });\n  });\n}\n","/**\n * Sleeps the function for the specified number of milliseconds\n * Your code will not do it's next step during this time while you await\n *\n *  ```typescript\n * await sleep(1000);\n * ```\n */\n\nexport async function sleep(time: number): Promise<void> {\n  return new Promise<void>(function (resolve) {\n    setTimeout(function () {\n      resolve();\n    }, time);\n  });\n}\n","import type { HTTPMethod } from './types';\n\n/**\n * HTTP responses that are plausibly transient and worth retrying when a retry\n * policy is explicitly enabled.\n *\n * `status === 0` is included on purpose because browser/XHR-style adapters can\n * surface \"no real HTTP response\" that way when the network is unavailable or\n * the request otherwise fails before a normal status code is received.\n */\nexport const RETRYABLE_STATUS_CODES: ReadonlySet<number> = new Set([\n  // 0: Browser/XHR-style \"no response\" status.\n  0,\n\n  // 408 Request Timeout\n  408,\n  // 429 Too Many Requests\n  429,\n\n  // 500 Internal Server Error\n  500,\n  // 502 Bad Gateway\n  502,\n  // 503 Service Unavailable\n  503,\n  // 504 Gateway Timeout\n  504,\n\n  // 507 Insufficient Storage\n  507,\n  // 509 Bandwidth Limit Exceeded (non-standard)\n  509,\n  // 520 Unknown Error (Cloudflare)\n  520,\n  // 521 Web Server Is Down (Cloudflare)\n  521,\n  // 522 Connection Timed Out (Cloudflare)\n  522,\n  // 523 Origin Is Unreachable (Cloudflare)\n  523,\n  // 524 A Timeout Occurred (Cloudflare)\n  524,\n  // 598 Network Read Timeout Error (non-standard)\n  598,\n  // 599 Network Connect Timeout Error (non-standard)\n  599,\n]);\n\nexport const DEFAULT_TIMEOUT_MS = 30_000;\n\nexport const DEFAULT_REQUEST_ID_HEADER = 'x-local-client-request-id';\n\nexport const DEFAULT_REQUEST_ATTEMPT_HEADER = 'x-local-client-request-attempt';\n\nexport const DEFAULT_USER_AGENT = 'lifecycleion-http-client';\n\nexport const NON_RETRYABLE_HTTP_CLIENT_CALLBACK_ERROR_FLAG =\n  '_lifecycleion_non_retryable_http_client_callback_error';\n\nexport const STREAM_FACTORY_ERROR_FLAG = '_lifecycleion_stream_factory_error';\n\n/**\n * Attached to the AbortError thrown when a StreamResponseFactory returns null\n * or `{ cancel: true, reason? }`. The value is the reason string if provided,\n * or `true` if the factory cancelled without a reason. Lets HTTPClient surface\n * the reason on HTTPClientError.cancelReason.\n */\nexport const STREAM_FACTORY_CANCEL_KEY =\n  '_lifecycleion_stream_factory_cancel_reason';\n\nexport const RESPONSE_STREAM_ABORT_FLAG = '_lifecycleion_response_stream_abort';\n\n/**\n * Set on the AbortError thrown by XHRAdapter's defensive `timeout` event\n * listener. Lets HTTPClient classify the error as a timeout (retryable) rather\n * than an unexpected abort (non-retryable cancel).\n */\nexport const XHR_BROWSER_TIMEOUT_FLAG = '_lifecycleion_xhr_browser_timeout';\n\nexport const HTTP_METHODS: ReadonlyArray<HTTPMethod> = [\n  'GET',\n  'POST',\n  'PUT',\n  'PATCH',\n  'DELETE',\n  'HEAD',\n];\n\n/**\n * Exact-match request headers that browsers either forbid outright or do not\n * let this client set reliably via plain Fetch/XHR headers.\n *\n * Prefix-based rules like `proxy-*` and `sec-*` are handled in `header-utils.ts`.\n */\nexport const BROWSER_RESTRICTED_HEADERS: ReadonlySet<string> = new Set([\n  // Encoding / CORS negotiation headers controlled by the browser.\n  'accept-charset',\n  'accept-encoding',\n  'access-control-request-headers',\n  'access-control-request-method',\n  'access-control-request-private-network',\n\n  // Connection-level transport headers.\n  'connection',\n  'content-length',\n  'date',\n  'expect',\n  'host',\n  'keep-alive',\n  'te',\n  'trailer',\n  'transfer-encoding',\n  'upgrade',\n  'via',\n\n  // Browser-managed request context / privacy headers.\n  'cookie',\n  'dnt',\n  'origin',\n  'referer',\n  'set-cookie',\n  'user-agent',\n]);\n\nexport const BROWSER_RESTRICTED_HEADER_PREFIXES: ReadonlyArray<string> = [\n  'proxy-',\n  'sec-',\n];\n\n/**\n * Headers that can tunnel the real method through POST. Browsers block these\n * when they try to smuggle forbidden transport methods.\n */\nexport const BROWSER_METHOD_OVERRIDE_HEADER_NAMES: ReadonlySet<string> =\n  new Set(['x-http-method', 'x-http-method-override', 'x-method-override']);\n\n/**\n * Methods that browsers do not allow request headers to tunnel via the\n * override headers above.\n */\nexport const BROWSER_FORBIDDEN_METHOD_OVERRIDE_VALUES: ReadonlySet<string> =\n  new Set(['connect', 'trace', 'track']);\n\nexport const DEFAULT_MAX_REDIRECTS = 5;\n\n/**\n * Redirect responses that carry a follow-up `Location` hop. `300` and `304`\n * are excluded because they do not represent an automatic redirect here.\n */\nexport const REDIRECT_STATUS_CODES: ReadonlySet<number> = new Set([\n  // 301 Moved Permanently\n  301,\n  // 302 Found\n  302,\n\n  // 303 See Other\n  303,\n\n  // 307 Temporary Redirect\n  307,\n  // 308 Permanent Redirect\n  308,\n]);\n","import qs from 'qs';\nimport {\n  matchesWildcardDomain,\n  normalizeDomain,\n} from '../domain-utils/domain-utils';\nimport type {\n  ContentType,\n  RequestPhaseName,\n  HTTPClientConfig,\n  AdapterType,\n} from './types';\n\n/**\n * If `path` is an absolute HTTP(S) URL, returns its canonical `href` (normalized\n * scheme/host casing). Otherwise `null`. Protocol-relative `//host` is handled\n * separately in `buildURL`.\n *\n * Rules differ from `resolveAbsoluteURL` (which accepts any absolute scheme).\n * One parse here per request is negligible next to network I/O.\n */\nfunction tryAbsoluteWebHref(path: string): string | null {\n  if (!path || path.startsWith('//')) {\n    return null;\n  }\n\n  try {\n    const u = new URL(path);\n    if (u.protocol === 'http:' || u.protocol === 'https:') {\n      return u.href;\n    }\n  } catch {\n    // not parseable as absolute\n  }\n\n  return null;\n}\n\n/**\n * Builds a request URL string from `baseURL`, `path`, and optional query params\n * (`qs` — nested objects and arrays supported).\n *\n * **Relative paths (usual case)** — When `baseURL` is set and `path` is not\n * absolute, `path` is joined to `baseURL` (leading slash normalized). Example:\n * `baseURL: https://api.test`, `path: /v1/users` → `https://api.test/v1/users`.\n *\n * **Absolute / protocol-relative `path` (escape hatch)** — If `path` is a full\n * `http:` or `https:` URL, it is **not** prefixed with `baseURL` (after\n * normalization via `URL#href`). The same applies to protocol-relative URLs\n * (`//cdn.example/x`): they are left for {@link resolveAbsoluteURL} to resolve\n * using the client `baseURL`’s scheme. Use this for one-off cross-origin calls,\n * CDN assets, or URLs returned by APIs; for strict per-origin clients, prefer\n * relative paths and a dedicated client or `HTTPClient.createSubClient()` per\n * origin.\n */\nexport function buildURL(\n  baseURL: string | undefined,\n  path: string,\n  params?: Record<string, unknown>,\n): string {\n  let url: string;\n\n  const absoluteHref = tryAbsoluteWebHref(path);\n\n  if (baseURL && absoluteHref === null && !path.startsWith('//')) {\n    // Avoid double slashes when joining base + path\n    const base = baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL;\n    const p = path.startsWith('/') ? path : `/${path}`;\n    url = `${base}${p}`;\n  } else if (absoluteHref !== null) {\n    url = absoluteHref;\n  } else {\n    url = path;\n  }\n\n  if (params && Object.keys(params).length > 0) {\n    const [urlWithoutHash, hash = ''] = url.split('#', 2);\n    const queryStartIndex = urlWithoutHash.indexOf('?');\n\n    if (queryStartIndex === -1) {\n      const queryString = qs.stringify(params, { addQueryPrefix: true });\n      url = `${urlWithoutHash}${queryString}${hash ? `#${hash}` : ''}`;\n    } else {\n      const basePath = urlWithoutHash.slice(0, queryStartIndex);\n      const existingQuery = urlWithoutHash.slice(queryStartIndex + 1);\n      // Fragments are preserved only as part of the caller's URL string.\n      // They are not transmitted in HTTP requests, but keeping them intact\n      // makes buildURL safer as a general-purpose URL composition helper.\n      const mergedParams = {\n        ...qs.parse(existingQuery),\n        ...params,\n      };\n\n      const queryString = qs.stringify(mergedParams, { addQueryPrefix: true });\n      url = `${basePath}${queryString}${hash ? `#${hash}` : ''}`;\n    }\n  }\n\n  return url;\n}\n\n/**\n * Best-effort absolute URL for logging, redirects, and hop metadata.\n *\n * - If `url` parses as an absolute URL (has a scheme), returns normalized `href`.\n * - Otherwise, when `baseURL` is set, resolves `url` against it (path-relative,\n *   same-host relative, protocol-relative `//host`, query-only, etc.).\n * - If neither works, returns `url` unchanged (callers without `baseURL` may still\n *   see path-only strings).\n */\nexport function resolveAbsoluteURL(url: string, baseURL?: string): string {\n  if (!url) {\n    return url;\n  }\n\n  try {\n    return new URL(url).href;\n  } catch {\n    // Not a standalone absolute URL\n  }\n\n  if (baseURL) {\n    try {\n      const base = baseURL.endsWith('/') ? baseURL : `${baseURL}/`;\n      return new URL(url, base).href;\n    } catch {\n      // fall through\n    }\n  }\n\n  return url;\n}\n\n/**\n * Browser-aware absolute URL resolution used by HTTPClient before interceptors\n * and adapter dispatch. Starts with normal baseURL resolution, then falls back\n * to the current page/worker location when running in a browser-like runtime.\n */\nexport function resolveAbsoluteURLForRuntime(\n  url: string,\n  baseURL: string | undefined,\n  isBrowserRuntime: boolean,\n): string {\n  const resolved = resolveAbsoluteURL(url, baseURL);\n\n  if (\n    !isBrowserRuntime ||\n    resolved.startsWith('http://') ||\n    resolved.startsWith('https://')\n  ) {\n    return resolved;\n  }\n\n  const browserBase = getBrowserResolutionBase();\n\n  if (!browserBase) {\n    return resolved;\n  }\n\n  return resolveAbsoluteURL(resolved, browserBase);\n}\n\nfunction getBrowserResolutionBase(): string | undefined {\n  if (\n    typeof document !== 'undefined' &&\n    typeof document.baseURI === 'string' &&\n    document.baseURI\n  ) {\n    return document.baseURI;\n  }\n\n  if (\n    typeof window !== 'undefined' &&\n    window.location &&\n    typeof window.location.href === 'string' &&\n    window.location.href\n  ) {\n    return window.location.href;\n  }\n\n  const globalLocation = (globalThis as { location?: { href?: unknown } })\n    .location;\n\n  if (\n    globalLocation &&\n    typeof globalLocation.href === 'string' &&\n    globalLocation.href\n  ) {\n    return globalLocation.href;\n  }\n\n  const selfLocation = (\n    globalThis as { self?: { location?: { href?: unknown } } }\n  ).self?.location;\n\n  if (\n    selfLocation &&\n    typeof selfLocation.href === 'string' &&\n    selfLocation.href\n  ) {\n    return selfLocation.href;\n  }\n\n  return undefined;\n}\n\n/**\n * Normalizes header keys to lowercase.\n */\nexport function normalizeHeaders(\n  headers: Record<string, string>,\n): Record<string, string> {\n  const result: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(headers)) {\n    result[key.toLowerCase()] = value;\n  }\n\n  return result;\n}\n\n/**\n * Merges multiple request-header objects, normalizing keys to lowercase.\n * Later objects win on conflict. Array values replace earlier scalars/arrays\n * wholesale, and single-item arrays are collapsed back to a plain string.\n */\nexport function mergeHeaders(\n  ...headerSets: Array<Record<string, string | string[]> | undefined>\n): Record<string, string | string[]> {\n  const result: Record<string, string | string[]> = {};\n  for (const headers of headerSets) {\n    if (!headers) {\n      continue;\n    }\n\n    for (const [key, value] of Object.entries(headers)) {\n      result[key.toLowerCase()] = Array.isArray(value)\n        ? normalizeMergedHeaderArray(value)\n        : String(value);\n    }\n  }\n\n  return result;\n}\n\nfunction normalizeMergedHeaderArray(value: string[]): string | string[] {\n  const normalized = value.map((item) => String(item));\n  return normalized.length === 1 ? normalized[0] : normalized;\n}\n\nexport function mergeObservedHeaders(\n  ...headerSets: Array<Record<string, string | string[]> | undefined>\n): Record<string, string | string[]> {\n  const result: Record<string, string | string[]> = {};\n\n  for (const headers of headerSets) {\n    if (!headers) {\n      continue;\n    }\n\n    for (const [key, value] of Object.entries(headers)) {\n      result[key.toLowerCase()] = Array.isArray(value)\n        ? value.map((item) => String(item))\n        : String(value);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Parses the Content-Type header into a ContentType enum value.\n */\nexport function parseContentType(\n  contentTypeHeader: string | undefined,\n): ContentType {\n  if (!contentTypeHeader) {\n    return 'binary';\n  } else {\n    const lower = contentTypeHeader.trim().toLowerCase();\n\n    if (lower.includes('application/json') || lower.includes('+json')) {\n      return 'json';\n    } else if (lower.startsWith('text/')) {\n      return 'text';\n    } else if (lower.includes('application/x-www-form-urlencoded')) {\n      return 'text';\n    } else {\n      return 'binary';\n    }\n  }\n}\n\n/**\n * Validates adapter/runtime combinations and redirect config before a client\n * is constructed, so unsupported browser-only/server-only options fail fast\n * with clear errors instead of surfacing later during request dispatch.\n */\nexport function assertSupportedAdapterRuntimeAndConfig(\n  config: HTTPClientConfig,\n  adapterType: AdapterType,\n  isBrowserRuntime: boolean,\n): void {\n  if (\n    config.baseURL !== undefined &&\n    requiresAbsoluteBaseURL(adapterType, isBrowserRuntime)\n  ) {\n    assertValidBaseURL(config.baseURL);\n  }\n\n  if (config.maxRedirects !== undefined && config.followRedirects !== true) {\n    throw new Error('HTTPClient maxRedirects requires followRedirects: true.');\n  }\n\n  if (\n    config.followRedirects === true &&\n    config.maxRedirects !== undefined &&\n    config.maxRedirects < 1\n  ) {\n    throw new Error(\n      'HTTPClient maxRedirects must be greater than or equal to 1 when followRedirects is true.',\n    );\n  }\n\n  if (adapterType === 'xhr' && config.followRedirects === true) {\n    throw new Error(\n      'HTTPClient redirect handling is not supported with XHR adapter. Set followRedirects: false or use a different adapter/runtime.',\n    );\n  }\n\n  if (adapterType === 'xhr' && !hasXMLHttpRequestGlobal()) {\n    throw new Error(\n      'HTTPClient XHR adapter is not supported when XMLHttpRequest is unavailable. Use a browser runtime, install a test shim, or switch to the FetchAdapter/NodeAdapter.',\n    );\n  }\n\n  if (!isBrowserRuntime) {\n    return;\n  }\n\n  if (adapterType === 'node') {\n    throw new Error(\n      'HTTPClient Node adapter is not supported in browser environments.',\n    );\n  }\n\n  // MockAdapter is intentionally allowed in browser runtimes: it is an\n  // in-memory test adapter, so cookie jars and redirect following are local\n  // simulation features rather than forbidden browser networking controls.\n  if ((adapterType === 'fetch' || adapterType === 'xhr') && config.cookieJar) {\n    throw new Error(\n      `HTTPClient cookieJar is not supported with ${adapterType === 'fetch' ? 'FetchAdapter' : 'XHR adapter'} in browser environments. Browsers manage cookies automatically.`,\n    );\n  }\n\n  if ((adapterType === 'fetch' || adapterType === 'xhr') && config.userAgent) {\n    throw new Error(\n      `HTTPClient userAgent is not supported with ${adapterType === 'fetch' ? 'FetchAdapter' : 'XHR adapter'} in browser environments. Browsers do not allow overriding the User-Agent header.`,\n    );\n  }\n\n  if (adapterType === 'fetch' && config.followRedirects === true) {\n    throw new Error(\n      'HTTPClient redirect handling is not supported with FetchAdapter in browser environments. Set followRedirects: false or use a server runtime.',\n    );\n  }\n}\n\nfunction requiresAbsoluteBaseURL(\n  adapterType: AdapterType,\n  isBrowserRuntime: boolean,\n): boolean {\n  if (adapterType === 'node' || adapterType === 'mock') {\n    return true;\n  }\n\n  if (adapterType === 'fetch' && !isBrowserRuntime) {\n    return true;\n  }\n\n  return false;\n}\n\nfunction hasXMLHttpRequestGlobal(): boolean {\n  return (\n    typeof globalThis !== 'undefined' &&\n    typeof (globalThis as { XMLHttpRequest?: unknown }).XMLHttpRequest ===\n      'function'\n  );\n}\n\n/**\n * Converts a Headers object (from fetch) into AdapterResponse headers.\n * `set-cookie` is extracted as `string[]` via `getSetCookie()` — the Fetch API\n * would otherwise incorrectly comma-join multiple Set-Cookie values.\n * All other headers are extracted as plain strings.\n */\nexport function extractFetchHeaders(\n  headers: Headers,\n): Record<string, string | string[]> {\n  const result: Record<string, string | string[]> = {};\n\n  for (const [key, value] of headers.entries()) {\n    const lower = key.toLowerCase();\n\n    if (lower !== 'set-cookie') {\n      result[lower] = value;\n    }\n  }\n\n  // Use getSetCookie() when available (Bun, Node 18.14+, modern browsers)\n  if (typeof headers.getSetCookie === 'function') {\n    const setCookies = headers.getSetCookie();\n\n    if (setCookies.length > 0) {\n      result['set-cookie'] = setCookies;\n    }\n  } else {\n    // Fallback: headers.get() comma-joins — split on ', ' is unreliable for\n    // cookies but better than nothing on older runtimes\n    const raw = headers.get('set-cookie');\n\n    if (raw) {\n      result['set-cookie'] = [raw];\n    }\n  }\n\n  return result;\n}\n\n/**\n * Lowercases all keys on adapter/response header objects. `HTTPClient` runs\n * this on each adapter response before {@link CookieJar.processResponseHeaders}.\n * The jar also normalizes so the same shapes work when feeding headers directly.\n *\n * - Non–`set-cookie` values: if an array appears (unexpected), the first\n *   element is kept when read via {@link scalarHeader}.\n * - `set-cookie`: stored as `string[]` — each array entry is one full\n *   `Set-Cookie` header line (one cookie). A single string value becomes a\n *   one-element array. If the same header appears under keys that differ only\n *   by case, those lines are appended in the order they appear on the input\n *   object.\n */\nexport function normalizeAdapterResponseHeaders(\n  headers: Record<string, string | string[]>,\n): Record<string, string | string[]> {\n  const result: Record<string, string | string[]> = {};\n\n  for (const [key, value] of Object.entries(headers)) {\n    const lower = key.toLowerCase();\n\n    if (lower === 'set-cookie') {\n      const chunk = Array.isArray(value) ? value : [value];\n      const existing = result[lower];\n\n      if (existing === undefined) {\n        result[lower] = chunk;\n      } else {\n        const existingLines = Array.isArray(existing) ? existing : [existing];\n        result[lower] = [...existingLines, ...chunk];\n      }\n    } else {\n      result[lower] = Array.isArray(value) ? (value[0] ?? '') : value;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Reads a single-valued header when keys are already lowercase (e.g. after\n * {@link mergeHeaders} on requests or {@link normalizeAdapterResponseHeaders}\n * on responses). If the stored value is `string[]`, returns the first entry.\n */\nexport function scalarHeader(\n  headers: Record<string, string | string[]>,\n  lowercaseName: string,\n): string | undefined {\n  const v = headers[lowercaseName];\n\n  if (v === undefined) {\n    return undefined;\n  }\n\n  return Array.isArray(v) ? v[0] : v;\n}\n\n/**\n * Resolves a redirect target from response headers when the adapter can\n * observe a redirect response but the client may not follow it itself.\n */\nexport function resolveDetectedRedirectURL(\n  requestURL: string,\n  status: number,\n  headers: Record<string, string | string[]>,\n  baseURL?: string,\n): string | undefined {\n  if (![301, 302, 303, 307, 308].includes(status)) {\n    return undefined;\n  }\n\n  const location = scalarHeader(headers, 'location');\n\n  if (!location) {\n    return undefined;\n  }\n\n  try {\n    const absoluteRequestURL = resolveAbsoluteURL(requestURL, baseURL);\n    return new URL(location, absoluteRequestURL).toString();\n  } catch {\n    return location;\n  }\n}\n\nexport function assertValidBaseURL(\n  baseURL: string,\n  fieldName = 'baseURL',\n): void {\n  try {\n    const url = new URL(baseURL);\n\n    if (url.protocol !== 'http:' && url.protocol !== 'https:') {\n      throw new Error('unsupported protocol');\n    }\n  } catch {\n    throw new Error(\n      `HTTPClient ${fieldName} must be an absolute http(s) URL (for example \"https://api.example.com\").`,\n    );\n  }\n}\n\n/**\n * Detects whether the current runtime looks like a browser environment.\n */\nexport function isBrowserEnvironment(): boolean {\n  if (typeof globalThis === 'undefined') {\n    return false;\n  }\n\n  if ('window' in globalThis && 'document' in globalThis) {\n    return true;\n  }\n\n  const workerGlobalScope = (\n    globalThis as {\n      WorkerGlobalScope?: abstract new (...args: never[]) => unknown;\n    }\n  ).WorkerGlobalScope;\n\n  if (\n    typeof workerGlobalScope === 'function' &&\n    (globalThis as { self?: unknown }).self instanceof workerGlobalScope\n  ) {\n    return true;\n  }\n\n  const constructorName = globalThis.constructor?.name;\n\n  return (\n    !('window' in globalThis) &&\n    !('document' in globalThis) &&\n    typeof constructorName === 'string' &&\n    constructorName.endsWith('WorkerGlobalScope')\n  );\n}\n\n/**\n * Serializes the request body and returns the body + inferred content-type.\n * If `formData` is provided, it takes precedence over `body`.\n */\nexport function serializeBody(body: unknown): {\n  body: string | Uint8Array | FormData | null;\n  contentType: string | null;\n} {\n  assertSupportedRequestBody(body);\n\n  if (body instanceof FormData) {\n    return { body, contentType: null }; // browser/runtime sets multipart boundary automatically\n  } else if (body === undefined || body === null) {\n    return { body: null, contentType: null };\n  } else if (typeof body === 'string') {\n    return { body, contentType: 'text/plain; charset=utf-8' };\n  } else if (body instanceof Uint8Array) {\n    return { body, contentType: 'application/octet-stream' };\n  } else if (Array.isArray(body) || isPlainJSONBodyObject(body)) {\n    return {\n      body: JSON.stringify(body),\n      contentType: 'application/json; charset=utf-8',\n    };\n  } else {\n    throw new Error(\n      'Unsupported request body type. Supported types: string, Uint8Array, FormData, plain object, array, null, and undefined.',\n    );\n  }\n}\n\nexport function assertSupportedRequestBody(body: unknown): void {\n  if (\n    body === undefined ||\n    body === null ||\n    typeof body === 'string' ||\n    body instanceof Uint8Array ||\n    body instanceof FormData ||\n    Array.isArray(body) ||\n    isPlainJSONBodyObject(body)\n  ) {\n    return;\n  }\n\n  throw new Error(\n    'Unsupported request body type. Supported types: string, Uint8Array, FormData, plain object, array, null, and undefined.',\n  );\n}\n\nexport function isPlainJSONBodyObject(\n  value: unknown,\n): value is Record<string, unknown> {\n  if (value === null || typeof value !== 'object' || Array.isArray(value)) {\n    return false;\n  }\n\n  const prototype = Reflect.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\n/**\n * Extracts the hostname from a URL string. Returns empty string on failure.\n */\nexport function extractHostname(url: string): string {\n  try {\n    return new URL(url).hostname;\n  } catch {\n    return '';\n  }\n}\n\n/**\n * Wildcard hostname matching backed by {@link matchesWildcardDomain}.\n *\n * - `*` — global wildcard, matches any valid hostname including apex domains\n * - `*.example.com` — matches exactly one subdomain label (`api.example.com`) but not deeper levels or the apex\n * - `**.example.com` — matches one or more subdomain labels (`api.example.com`, `a.b.example.com`) but not the apex\n * - Exact patterns (no `*`) — normalized comparison, case-insensitive\n * - PSL tail guard active: `*.com`, `**.co.uk`, etc. never match\n * - Pseudo-TLD suffix wildcards are rejected just like PSL tails (`*.localhost`, `*.local`, etc.)\n */\nexport function matchesHostPattern(hostname: string, pattern: string): boolean {\n  if (pattern.includes('*')) {\n    return matchesWildcardDomain(hostname, pattern);\n  }\n\n  const normalizedHostname = normalizeDomain(hostname);\n  const normalizedPattern = normalizeDomain(pattern);\n  return normalizedHostname !== '' && normalizedHostname === normalizedPattern;\n}\n\n/**\n * Checks whether a dot-path key exists in a nested object.\n * Arrays are not traversed — only plain objects at each segment.\n */\nfunction hasNestedKey(obj: Record<string, unknown>, path: string): boolean {\n  const parts = path.split('.');\n  let current: unknown = obj;\n\n  for (const part of parts) {\n    if (!current || typeof current !== 'object' || Array.isArray(current)) {\n      return false;\n    }\n\n    if (!(part in (current as Record<string, unknown>))) {\n      return false;\n    }\n\n    current = (current as Record<string, unknown>)[part];\n  }\n\n  return true;\n}\n\nfunction normalizeMimeType(value: string): string {\n  return value.split(';', 1)[0].trim().toLowerCase();\n}\n\nfunction matchesContentTypePattern(\n  actualHeader: string,\n  pattern: string,\n): boolean {\n  const actual = normalizeMimeType(actualHeader);\n  const expected = normalizeMimeType(pattern);\n\n  if (!actual || !expected) {\n    return false;\n  }\n\n  if (expected.endsWith('/*')) {\n    const expectedType = expected.slice(0, -2);\n    const slashIndex = actual.indexOf('/');\n\n    if (slashIndex === -1) {\n      return false;\n    }\n\n    return actual.slice(0, slashIndex) === expectedType;\n  }\n\n  return actual === expected;\n}\n\n/**\n * Tests whether a request context matches an interceptor/observer filter.\n *\n * Each filter field is optional — omitting it skips that check entirely.\n * All specified fields must match for the function to return true.\n * Within each field, values are matched with OR logic (any one match is sufficient).\n *\n * - `phases`: **OR** allowlist on `phaseType` ({@link RequestPhaseName}). Skipped when\n *   `filter.phases` is omitted or empty.\n * - `statusCodes`: skipped if `context.status` is absent.\n * - `methods`: skipped if `context.method` is absent.\n * - `hosts`: supports exact hostnames and wildcard patterns. `*.example.com` matches\n *   exactly one subdomain label; `**.example.com` matches any depth. Neither matches the\n *   apex — list it explicitly. PSL tail guard prevents `*.com`-style patterns. `*` is a\n *   global wildcard that matches any valid hostname. Skipped if `context.requestURL` is absent.\n * - `schemes`: `'http'` or `'https'`. `requestURL` is absolute whenever the\n *   request could be resolved before dispatch. For `MockAdapter`, path-only\n *   requests without a client `baseURL` are materialized as `http://localhost/...`;\n *   browser adapters fall back to `window.location`, and the Node adapter requires\n *   absolute URLs. Skipped only when `requestURL` is absent.\n * - `bodyContainsKeys`: supports dot paths (e.g. `data.results`). Each segment in\n *   the path must resolve to a plain object for traversal to continue — the final\n *   value can be anything (array, string, null, etc). Array indexing is not supported.\n *   Skipped when `kind` is `'error'`.\n */\nexport function matchesFilter(\n  filter: {\n    statusCodes?: number[];\n    methods?: string[];\n    bodyContainsKeys?: string[];\n    hosts?: string[];\n    schemes?: ('http' | 'https')[];\n    phases?: RequestPhaseName[];\n    contentTypes?: ContentType[];\n    contentTypeHeaders?: string[];\n  },\n  context: {\n    status?: number;\n    method?: string;\n    body?: unknown;\n    requestURL?: string;\n    contentType?: ContentType;\n    contentTypeHeader?: string;\n  },\n  phaseType: RequestPhaseName,\n  kind: 'request' | 'response' | 'error',\n): boolean {\n  if (\n    filter.phases &&\n    filter.phases.length > 0 &&\n    !filter.phases.includes(phaseType)\n  ) {\n    return false;\n  }\n\n  if (filter.statusCodes && context.status !== undefined) {\n    if (!filter.statusCodes.includes(context.status)) {\n      return false;\n    }\n  }\n\n  if (filter.methods && context.method) {\n    if (!filter.methods.includes(context.method)) {\n      return false;\n    }\n  }\n\n  if (filter.contentTypes && filter.contentTypes.length > 0) {\n    if (\n      !context.contentType ||\n      !filter.contentTypes.includes(context.contentType)\n    ) {\n      return false;\n    }\n  }\n\n  if (filter.contentTypeHeaders && filter.contentTypeHeaders.length > 0) {\n    if (\n      !context.contentTypeHeader ||\n      !filter.contentTypeHeaders.some((pattern) =>\n        matchesContentTypePattern(context.contentTypeHeader as string, pattern),\n      )\n    ) {\n      return false;\n    }\n  }\n\n  if (\n    kind !== 'error' &&\n    filter.bodyContainsKeys &&\n    filter.bodyContainsKeys.length > 0\n  ) {\n    if (\n      !context.body ||\n      typeof context.body !== 'object' ||\n      Array.isArray(context.body)\n    ) {\n      return false;\n    }\n\n    const body = context.body as Record<string, unknown>;\n\n    if (!filter.bodyContainsKeys.some((k) => hasNestedKey(body, k))) {\n      return false;\n    }\n  }\n\n  if (filter.hosts && context.requestURL) {\n    const hostname = extractHostname(context.requestURL);\n\n    if (\n      !filter.hosts.some((pattern: string) =>\n        matchesHostPattern(hostname, pattern),\n      )\n    ) {\n      return false;\n    }\n  }\n\n  if (filter.schemes && filter.schemes.length > 0 && context.requestURL) {\n    let scheme: 'http' | 'https' | null = null;\n\n    try {\n      const parsedScheme = new URL(context.requestURL).protocol.replace(\n        ':',\n        '',\n      );\n\n      if (parsedScheme === 'http' || parsedScheme === 'https') {\n        scheme = parsedScheme;\n      }\n    } catch {\n      scheme = null;\n    }\n\n    if (!scheme || !filter.schemes.includes(scheme)) {\n      return false;\n    }\n  }\n\n  return true;\n}\n","import { getDomain, getSubdomain, getPublicSuffix } from 'tldts';\nimport {\n  isAllWildcards,\n  hasPartialLabelWildcard,\n  checkDNSLength,\n  normalizeDomain,\n  isIPv6,\n  toAsciiDots,\n  canonicalizeBracketedIPv6Content,\n  matchesMultiLabelPattern,\n  extractFixedTailAfterLastWildcard,\n  isIPAddress,\n  normalizeWildcardPattern,\n  INTERNAL_PSEUDO_TLDS,\n  INVALID_DOMAIN_CHARS,\n  MAX_LABELS,\n} from './helpers';\n\nexport function safeParseURL(input: string): URL | null {\n  try {\n    return new URL(input);\n  } catch {\n    return null;\n  }\n}\n\nfunction hasValidWildcardOriginHost(url: URL): boolean {\n  return normalizeDomain(url.hostname) !== '';\n}\n\nfunction extractAuthority(input: string, schemeIdx: number): string {\n  const afterScheme = input.slice(schemeIdx + 3);\n  const cut = Math.min(\n    ...[\n      afterScheme.indexOf('/'),\n      afterScheme.indexOf('?'),\n      afterScheme.indexOf('#'),\n    ].filter((i) => i !== -1),\n  );\n\n  return cut === Infinity ? afterScheme : afterScheme.slice(0, cut);\n}\n\nfunction hasDanglingPortInAuthority(input: string): boolean {\n  const schemeIdx = input.indexOf('://');\n  if (schemeIdx === -1) {\n    return false;\n  }\n\n  const authority = extractAuthority(input, schemeIdx);\n  const at = authority.lastIndexOf('@');\n  const hostPort = at === -1 ? authority : authority.slice(at + 1);\n\n  return hostPort.endsWith(':');\n}\n\n/**\n * Normalize a bare origin for consistent comparison.\n * Returns the canonical origin form with a normalized hostname,\n * lowercase scheme, no trailing slash, and default ports removed\n * (80 for http, 443 for https).\n */\nexport function normalizeOrigin(origin: string): string {\n  // Preserve literal \"null\" origin exactly; treat all other invalids as empty sentinel\n  if (origin === 'null') {\n    return 'null';\n  }\n\n  // Normalize Unicode dots before URL parsing for browser compatibility\n  // Chrome allows URLs like https://127。0。0。1\n  const normalizedOrigin = toAsciiDots(origin);\n  if (hasDanglingPortInAuthority(normalizedOrigin)) {\n    return '';\n  }\n\n  const url = safeParseURL(normalizedOrigin);\n  if (url) {\n    // Only normalize bare origins. Allow a single trailing slash so callers\n    // can pass values like \"https://example.com/\" without broadening real paths.\n    if (\n      url.username ||\n      url.password ||\n      (url.pathname && url.pathname !== '/') ||\n      url.search ||\n      url.hash\n    ) {\n      return '';\n    }\n\n    // Normalize hostname with punycode\n    const normalizedHostname = normalizeDomain(url.hostname);\n\n    // If hostname normalization fails (pathological IDN), return original origin\n    // to avoid emitting values like \"https://\" with an empty host.\n    if (normalizedHostname === '') {\n      return '';\n    }\n\n    // Preserve brackets for IPv6 hosts; avoid double-bracketing if already present\n    let host: string;\n    // Extract the raw bracketed host (if present) from the authority portion only\n    // to prevent matching brackets in path/query/fragment portions of full URLs.\n    const schemeSep = normalizedOrigin.indexOf('://');\n    const authority = extractAuthority(normalizedOrigin, schemeSep);\n    const bracketMatch = authority.match(/\\[([^\\]]+)\\]/);\n    const rawBracketContent = bracketMatch ? bracketMatch[1] : null;\n\n    // Decode only for IPv6 detection, not for output\n    const hostnameForIpv6Check = (\n      rawBracketContent ? rawBracketContent : normalizedHostname\n    )\n      .replace(/%25/g, '%')\n      .toLowerCase();\n\n    if (isIPv6(hostnameForIpv6Check)) {\n      // Canonicalize bracket content using shared helper (do not decode %25)\n      const raw = rawBracketContent\n        ? rawBracketContent\n        : normalizedHostname.replace(/^\\[|\\]$/g, '');\n\n      const canon = canonicalizeBracketedIPv6Content(raw);\n\n      host = `[${canon}]`;\n    } else {\n      host = normalizedHostname;\n    }\n\n    // Normalize default ports for http/https\n    let port = '';\n    const protocolLower = url.protocol.toLowerCase();\n    const defaultPort =\n      protocolLower === 'https:'\n        ? '443'\n        : protocolLower === 'http:'\n          ? '80'\n          : '';\n\n    if (url.port) {\n      // Remove default ports for known protocols\n      port = url.port === defaultPort ? '' : `:${url.port}`;\n    } else {\n      // Fallback: some URL implementations with exotic hosts might not populate url.port\n      // even if an explicit port exists in the original string. Detect and normalize manually.\n      // Handle potential userinfo (user:pass@) prefix for future compatibility\n\n      // Try IPv6 bracketed format first\n      let portMatch = authority.match(/^(?:[^@]*@)?\\[[^\\]]+\\]:(\\d+)$/);\n\n      if (portMatch) {\n        const explicit = portMatch[1];\n        port = explicit === defaultPort ? '' : `:${explicit}`;\n      } else {\n        // Fallback for non-IPv6 authorities: detect :port after host\n        portMatch = authority.match(/^(?:[^@]*@)?([^:]+):(\\d+)$/);\n        if (portMatch) {\n          const explicit = portMatch[2];\n          port = explicit === defaultPort ? '' : `:${explicit}`;\n        }\n      }\n    }\n\n    // Explicitly use lowercase protocol for consistency\n    return `${protocolLower}//${host}${port}`;\n  }\n\n  // If URL parsing fails, return empty sentinel (handles invalid URLs).\n  // Literal \"null\" is handled above.\n  return '';\n}\n\n/**\n * Smart wildcard matching for domains (apex must be explicit)\n *\n * Special case: a single \"*\" matches any host (domains and IPs).\n * For non-global patterns, apex domains must be listed explicitly.\n *\n * Pattern matching rules:\n * - \"*.example.com\" matches DIRECT subdomains only:\n *   - \"api.example.com\" ✅ (direct subdomain)\n *   - \"app.api.example.com\" ❌ (nested subdomain - use ** for this)\n * - \"**.example.com\" matches ALL subdomains (including nested):\n *   - \"api.example.com\" ✅ (direct subdomain)\n *   - \"app.api.example.com\" ✅ (nested subdomain)\n *   - \"v2.app.api.example.com\" ✅ (deep nesting)\n * - \"*.*.example.com\" matches exactly TWO subdomain levels:\n *   - \"a.b.example.com\" ✅ (two levels)\n *   - \"api.example.com\" ❌ (one level)\n *   - \"x.y.z.example.com\" ❌ (three levels)\n */\nexport function matchesWildcardDomain(\n  domain: string,\n  pattern: string,\n): boolean {\n  const normalizedDomain = normalizeDomain(domain);\n\n  if (normalizedDomain === '') {\n    return false; // invalid domain cannot match\n  }\n\n  // Normalize pattern preserving wildcard labels and trailing dot handling\n  const normalizedPattern = normalizeWildcardPattern(pattern);\n  if (!normalizedPattern) {\n    return false; // invalid pattern\n  }\n\n  // Check if pattern contains wildcards\n  if (!normalizedPattern.includes('*')) {\n    return false;\n  }\n\n  // Allow single \"*\" as global wildcard - matches both domains and IP addresses\n  if (normalizedPattern === '*') {\n    return true;\n  }\n\n  // Do not wildcard-match IP addresses with non-global patterns; only exact IP matches are supported elsewhere\n  if (isIPAddress(normalizedDomain)) {\n    return false;\n  }\n\n  // Reject other all-wildcards patterns (e.g., \"*.*\", \"**.*\")\n  if (isAllWildcards(normalizedPattern)) {\n    return false;\n  }\n\n  // PSL/IP tail guard: ensure the fixed tail is neither a PSL, a pseudo-TLD, nor an IP.\n  // This prevents patterns like \"*.com\" or \"**.co.uk\" from matching\n\n  const labels = normalizedPattern.split('.');\n  const { fixedTail: fixedTailLabels } =\n    extractFixedTailAfterLastWildcard(labels);\n  if (fixedTailLabels.length === 0) {\n    return false; // require a concrete tail\n  }\n\n  const tail = fixedTailLabels.join('.');\n\n  if (isIPAddress(tail)) {\n    return false; // no wildcarding around IPs\n  }\n\n  const ps = getPublicSuffix(tail);\n\n  if (INTERNAL_PSEUDO_TLDS.has(tail) || (ps && ps === tail)) {\n    return false; // no wildcarding around suffix-like tails\n  }\n\n  // \"**.\" requires at least one label before the remainder, so a domain that\n  // exactly equals the remainder can never match (e.g., \"**.example.com\" ≠ \"example.com\").\n  if (normalizedPattern.startsWith('**.')) {\n    if (normalizedDomain === normalizeDomain(normalizedPattern.slice(3))) {\n      return false;\n    }\n  }\n\n  return matchesMultiLabelPattern(normalizedDomain, normalizedPattern);\n}\n\n/**\n * Smart origin wildcard matching for CORS with URL parsing\n * Supports protocol-specific wildcards and domain wildcards:\n * - * - matches any valid HTTP(S) origin (global wildcard)\n * - https://* or http://* - matches any domain with specific protocol\n * - *.example.com - matches direct subdomains with any protocol (ignores port)\n * - **.example.com - matches all subdomains including nested with any protocol\n * - https://*.example.com or http://*.example.com - matches direct subdomains with specific protocol\n * - https://**.example.com or http://**.example.com - matches all subdomains including nested with specific protocol\n *\n * Protocol support:\n * - For CORS, only http/https are supported; non-HTTP(S) origins never match\n * - Invalid or non-HTTP(S) schemes are rejected early for security\n *\n * Special cases:\n * - \"null\" origins: Cannot be matched by wildcard patterns, only by exact string inclusion in arrays\n *   (Security note: sandboxed/file/data contexts can emit literal \"null\". Treat as lower trust; do not\n *   allow via \"*\" or host wildcards. Include the literal \"null\" explicitly if you want to allow it.)\n * - Apex domains (example.com) must be listed explicitly, wildcards ignore port numbers\n * - Invalid URLs that fail parsing are treated as literal strings (no wildcard matching)\n */\nexport function matchesWildcardOrigin(\n  origin: string,\n  pattern: string,\n): boolean {\n  // Normalize Unicode dots before URL parsing for consistency\n  const normalizedOrigin = toAsciiDots(origin);\n  const normalizedPattern = toAsciiDots(pattern);\n\n  if (hasDanglingPortInAuthority(normalizedOrigin)) {\n    return false;\n  }\n\n  // Parse once and reuse\n  const originURL = safeParseURL(normalizedOrigin);\n\n  // For CORS, only http/https are relevant; reject other schemes early when parsed.\n  if (originURL) {\n    const scheme = originURL.protocol.toLowerCase();\n    if (scheme !== 'http:' && scheme !== 'https:') {\n      return false;\n    }\n\n    if (\n      originURL.username ||\n      originURL.password ||\n      (originURL.pathname && originURL.pathname !== '/') ||\n      originURL.search ||\n      originURL.hash\n    ) {\n      return false;\n    }\n  }\n\n  // Global wildcard: single \"*\" matches any valid HTTP(S) origin\n  if (normalizedPattern === '*') {\n    return originURL !== null && hasValidWildcardOriginHost(originURL);\n  }\n\n  // Protocol-only wildcards: require valid URL parsing for security\n  const patternLower = normalizedPattern.toLowerCase();\n\n  if (patternLower === 'https://*' || patternLower === 'http://*') {\n    if (!originURL) {\n      return false; // must be a valid URL\n    }\n\n    const want = patternLower === 'https://*' ? 'https:' : 'http:';\n    return (\n      originURL.protocol.toLowerCase() === want &&\n      hasValidWildcardOriginHost(originURL)\n    );\n  }\n\n  // Remaining logic requires a parsed URL\n  if (!originURL) {\n    return false;\n  }\n\n  const normalizedHostname = normalizeDomain(originURL.hostname);\n\n  if (normalizedHostname === '') {\n    return false;\n  }\n\n  const originProtocol = originURL.protocol.slice(0, -1).toLowerCase(); // Remove trailing \":\" and lowercase\n\n  // Handle protocol-specific domain wildcards: https://*.example.com\n  if (normalizedPattern.includes('://')) {\n    const [patternProtocol, ...rest] = normalizedPattern.split('://');\n    const domainPattern = rest.join('://');\n\n    // Reject non-domain characters in the domain pattern portion\n    if (INVALID_DOMAIN_CHARS.test(domainPattern)) {\n      return false;\n    }\n\n    // Protocol must match exactly\n    if (originProtocol !== patternProtocol.toLowerCase()) {\n      return false;\n    }\n\n    // Fast reject: domain pattern must contain at least one wildcard and not be all-wildcards\n    if (!domainPattern.includes('*') || isAllWildcards(domainPattern)) {\n      return false;\n    }\n\n    // Check domain pattern using direct domain matching\n    return matchesWildcardDomain(normalizedHostname, domainPattern);\n  }\n\n  // Handle domain wildcard patterns (including multi-label patterns)\n  if (normalizedPattern.includes('*')) {\n    // Fast reject for invalid all-wildcards patterns (e.g., \"*.*\", \"**.*\")\n    // Note: single \"*\" is handled above as global wildcard\n    if (normalizedPattern !== '*' && isAllWildcards(normalizedPattern)) {\n      return false;\n    }\n\n    return matchesWildcardDomain(normalizedHostname, normalizedPattern);\n  }\n\n  return false;\n}\n\n/**\n * Check if a domain matches any pattern in a list\n * Supports exact matches, wildcards, and normalization\n *\n * Validation:\n * - Origin-style patterns (e.g., \"https://*.example.com\") are NOT allowed in domain lists.\n *   If any entry contains \"://\", an error will be thrown to surface misconfiguration early.\n * - Empty or whitespace-only entries are ignored.\n * Use `matchesOriginList` for origin-style patterns.\n */\nexport function matchesDomainList(\n  domain: string,\n  allowedDomains: string[],\n): boolean {\n  const normalizedDomain = normalizeDomain(domain);\n\n  // Early exit: invalid input cannot match any allowed domain\n  if (normalizedDomain === '') {\n    return false;\n  }\n\n  // Trim and filter out empty entries first\n  const cleaned = allowedDomains\n    .map((s) => s.trim())\n    .filter((s) => s.length > 0);\n\n  // Validate: throw if any origin-style patterns are present\n  const ORIGIN_LIKE = /^[a-z][a-z0-9+\\-.]*:\\/\\//i;\n  const originLike = cleaned.filter((s) => ORIGIN_LIKE.test(s));\n\n  if (originLike.length > 0) {\n    throw new Error(\n      `matchesDomainList: origin-style patterns are not allowed in domain lists: ${originLike.join(', ')}`,\n    );\n  }\n\n  for (const allowed of cleaned) {\n    if (allowed.includes('*')) {\n      if (matchesWildcardDomain(domain, allowed)) {\n        return true;\n      }\n      continue;\n    }\n\n    const normalizedAllowed = normalizeDomain(allowed);\n    if (\n      isAllowedExactHostname(normalizedAllowed) &&\n      normalizedDomain === normalizedAllowed\n    ) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\nfunction isAllowedExactHostname(normalizedHostname: string): boolean {\n  if (!normalizedHostname) {\n    return false;\n  }\n\n  // The literal string \"null\" is origin-only and must never match in domain context.\n  // Guard explicitly rather than relying on PSL classification of unknown single-label TLDs.\n  if (normalizedHostname === 'null') {\n    return false;\n  }\n\n  if (\n    isIPAddress(normalizedHostname) ||\n    INTERNAL_PSEUDO_TLDS.has(normalizedHostname)\n  ) {\n    return true;\n  }\n\n  const publicSuffix = getPublicSuffix(normalizedHostname);\n  return !(publicSuffix && publicSuffix === normalizedHostname);\n}\n\n/**\n * Validate a configuration entry for either domain or origin contexts.\n * Non-throwing: returns { valid, info? } where info can carry non-fatal hints.\n *\n * - Domain context: accepts exact domains and domain wildcard patterns.\n * - Origin context: accepts\n *   - exact origins,\n *   - protocol-only wildcards like \"https://*\",\n *   - protocol + domain wildcard like \"https://*.example.com\",\n *   - bare domains (treated like domain context).\n *\n * Common rules:\n * - Only full-label wildcards are allowed (\"*\" or \"**\"); partial label wildcards are invalid.\n * - All-wildcards domain patterns (e.g., \"*.*\") are invalid. The global \"*\" may be allowed\n *   in origin context when explicitly enabled via options.\n * - Wildcards cannot target IP tails.\n * - PSL tail guard also rejects pseudo-TLD suffix wildcards like `*.localhost`.\n */\nexport type WildcardKind = 'none' | 'global' | 'protocol' | 'subdomain';\n\nexport type ValidationResult = {\n  valid: boolean;\n  info?: string;\n  wildcardKind: WildcardKind;\n};\n\nfunction isValidPortString(port: string): boolean {\n  if (!/^\\d+$/.test(port)) {\n    return false;\n  }\n\n  const portNumber = Number(port);\n  return Number.isInteger(portNumber) && portNumber >= 0 && portNumber <= 65535;\n}\n\nexport function validateConfigEntry(\n  entry: string,\n  context: 'domain' | 'origin',\n  options?: { allowGlobalWildcard?: boolean; allowProtocolWildcard?: boolean },\n): ValidationResult {\n  const raw = (entry ?? '').trim();\n  const SCHEME_RE = /^[a-z][a-z0-9+\\-.]*$/i;\n  if (!raw) {\n    return { valid: false, info: 'empty entry', wildcardKind: 'none' };\n  }\n\n  // Normalize options with secure defaults\n  const opts = {\n    allowGlobalWildcard: false,\n    allowProtocolWildcard: true,\n    ...(options ?? {}),\n  } as Required<NonNullable<typeof options>> & {\n    allowGlobalWildcard: boolean;\n    allowProtocolWildcard: boolean;\n  };\n\n  // Helper: validate non-wildcard labels (punycode + DNS limits)\n  function validateConcreteLabels(pattern: string): boolean {\n    const labels = pattern.split('.');\n    const concrete: string[] = [];\n\n    for (const lbl of labels) {\n      if (lbl === '*' || lbl === '**') {\n        continue;\n      }\n\n      if (lbl.length > 63) {\n        return false;\n      }\n\n      const nd = normalizeDomain(lbl);\n\n      if (nd === '') {\n        return false;\n      }\n\n      concrete.push(nd);\n    }\n\n    if (concrete.length > 0) {\n      if (!checkDNSLength(concrete.join('.'))) {\n        return false;\n      }\n    }\n\n    return true;\n  }\n\n  // Helper: PSL tail guard and IP-tail rejection for wildcard patterns\n  function wildcardTailIsInvalid(pattern: string): boolean {\n    const normalized = normalizeWildcardPattern(pattern);\n\n    const labels = normalized.split('.');\n\n    // Extract the fixed tail after the last wildcard\n    const { fixedTail: fixedTailLabels } =\n      extractFixedTailAfterLastWildcard(labels);\n    if (fixedTailLabels.length === 0) {\n      return true; // require a concrete tail\n    }\n\n    const tail = fixedTailLabels.join('.');\n    if (isIPAddress(tail)) {\n      return true; // no wildcarding around IPs\n    }\n    const ps = getPublicSuffix(tail);\n    if (INTERNAL_PSEUDO_TLDS.has(tail) || (ps && ps === tail)) {\n      return true;\n    }\n    return false;\n  }\n\n  // Helper: domain-wildcard structural checks (no URL chars, full labels, etc.)\n  function validateDomainWildcard(pattern: string): ValidationResult {\n    // Normalize Unicode dots and trim\n    const trimmed = pattern\n      .trim()\n      .normalize('NFC')\n      .replace(/[．。｡]/g, '.'); // normalize Unicode dot variants to ASCII\n\n    if (INVALID_DOMAIN_CHARS.test(trimmed)) {\n      return {\n        valid: false,\n        info: 'invalid characters in domain pattern',\n        wildcardKind: 'none',\n      };\n    }\n\n    if (hasPartialLabelWildcard(trimmed)) {\n      return {\n        valid: false,\n        info: 'partial-label wildcards are not allowed',\n        wildcardKind: 'none',\n      };\n    }\n\n    const normalized = normalizeWildcardPattern(trimmed);\n\n    if (!normalized) {\n      return {\n        valid: false,\n        info: 'invalid domain labels',\n        wildcardKind: 'none',\n      };\n    }\n\n    if (normalized.split('.').length > MAX_LABELS) {\n      return {\n        valid: false,\n        info: 'wildcard pattern exceeds label limit',\n        wildcardKind: 'none',\n      };\n    }\n\n    if (isAllWildcards(normalized)) {\n      return {\n        valid: false,\n        info: 'all-wildcards pattern is not allowed',\n        wildcardKind: 'none',\n      };\n    }\n\n    if (!validateConcreteLabels(normalized)) {\n      return {\n        valid: false,\n        info: 'invalid domain labels',\n        wildcardKind: 'none',\n      };\n    }\n\n    if (wildcardTailIsInvalid(normalized)) {\n      return {\n        valid: false,\n        info: 'wildcard tail targets public suffix or IP (disallowed)',\n        wildcardKind: 'none',\n      };\n    }\n\n    return { valid: true, wildcardKind: 'subdomain' };\n  }\n\n  // Helper: exact domain check (no protocols). Reject apex public suffixes.\n  function validateExactDomain(s: string): ValidationResult {\n    // The literal string \"null\" is origin-only; reject it explicitly\n    // rather than relying on PSL classification of unknown single-label TLDs.\n    if (s.toLowerCase() === 'null') {\n      return {\n        valid: false,\n        info: '\"null\" is not a valid domain entry',\n        wildcardKind: 'none',\n      };\n    }\n\n    // Check if it's an IP address first - if so, allow it (consistent with matchesDomainList)\n    // Normalize Unicode dots for consistent IP detection\n    const sDots = toAsciiDots(s);\n    if (isIPAddress(sDots)) {\n      return { valid: true, wildcardKind: 'none' };\n    }\n\n    // For non-IP addresses, reject URL-like characters\n    if (INVALID_DOMAIN_CHARS.test(s)) {\n      return {\n        valid: false,\n        info: 'invalid characters in domain',\n        wildcardKind: 'none',\n      };\n    }\n\n    const nd = normalizeDomain(s);\n\n    if (nd === '') {\n      return { valid: false, info: 'invalid domain', wildcardKind: 'none' };\n    }\n\n    const ps = getPublicSuffix(nd);\n\n    if (ps && ps === nd && !INTERNAL_PSEUDO_TLDS.has(nd)) {\n      return {\n        valid: false,\n        info: 'entry equals a public suffix (not registrable)',\n        wildcardKind: 'none',\n      };\n    }\n    return { valid: true, wildcardKind: 'none' };\n  }\n\n  // Domain context path\n  if (context === 'domain') {\n    // Reject any origin-style entries (with protocols) upfront\n    if (/^[a-z][a-z0-9+\\-.]*:\\/\\//i.test(raw)) {\n      return {\n        valid: false,\n        info: 'protocols are not allowed in domain context',\n        wildcardKind: 'none',\n      };\n    }\n\n    // Special-case: global wildcard in domain context (config-time validation)\n    if (raw === '*') {\n      return opts.allowGlobalWildcard\n        ? { valid: true, wildcardKind: 'global' }\n        : {\n            valid: false,\n            info: \"global wildcard '*' not allowed in this context\",\n            wildcardKind: 'none',\n          };\n    }\n\n    if (raw.includes('*')) {\n      return validateDomainWildcard(raw);\n    }\n    return validateExactDomain(raw);\n  }\n\n  // Origin context\n  // Special-case: literal \"null\" origin is allowed by exact inclusion\n  if (raw === 'null') {\n    return { valid: true, wildcardKind: 'none' };\n  }\n\n  // Special-case: global wildcard in origin context (config-time validation)\n  if (raw === '*') {\n    return opts.allowGlobalWildcard\n      ? { valid: true, wildcardKind: 'global' }\n      : {\n          valid: false,\n          info: \"global wildcard '*' not allowed in this context\",\n          wildcardKind: 'none',\n        };\n  }\n\n  const schemeIdx = raw.indexOf('://');\n  if (schemeIdx === -1) {\n    // Bare domain/or domain pattern allowed in origin lists; reuse domain rules\n    if (raw.includes('*')) {\n      return validateDomainWildcard(raw);\n    }\n    return validateExactDomain(raw);\n  }\n\n  const scheme = raw.slice(0, schemeIdx).toLowerCase();\n  const rest = raw.slice(schemeIdx + 3);\n\n  if (!SCHEME_RE.test(scheme)) {\n    return {\n      valid: false,\n      info: 'invalid scheme in origin',\n      wildcardKind: 'none',\n    };\n  }\n\n  let normalizedRest = rest;\n\n  // Disallow query/fragment in origin entries. Allow a single trailing slash\n  // for exact origins so copied values like \"https://example.com/\" validate\n  // the same way the runtime matchers normalize them.\n  if (normalizedRest.includes('#') || normalizedRest.includes('?')) {\n    return {\n      valid: false,\n      info: 'origin must not contain path, query, or fragment',\n      wildcardKind: 'none',\n    };\n  }\n\n  const slashIdx = normalizedRest.indexOf('/');\n  if (slashIdx !== -1) {\n    const authority = normalizedRest.slice(0, slashIdx);\n    const suffix = normalizedRest.slice(slashIdx);\n\n    if (suffix !== '/' || authority.includes('*')) {\n      return {\n        valid: false,\n        info: 'origin must not contain path, query, or fragment',\n        wildcardKind: 'none',\n      };\n    }\n\n    normalizedRest = authority;\n  }\n\n  if (!normalizedRest) {\n    return {\n      valid: false,\n      info: 'missing host in origin',\n      wildcardKind: 'none',\n    };\n  }\n\n  // Reject userinfo in origin entries for security and clarity\n  if (normalizedRest.includes('@')) {\n    return {\n      valid: false,\n      info: 'origin must not include userinfo',\n      wildcardKind: 'none',\n    };\n  }\n\n  // Protocol-only wildcard: scheme://*\n  if (normalizedRest === '*') {\n    if (scheme !== 'http' && scheme !== 'https') {\n      return {\n        valid: false,\n        info: 'wildcard origins require http or https scheme',\n        wildcardKind: 'none',\n      };\n    }\n\n    if (!opts.allowProtocolWildcard) {\n      return {\n        valid: false,\n        info: 'protocol wildcard not allowed',\n        wildcardKind: 'none',\n      };\n    }\n\n    const info =\n      scheme === 'http' || scheme === 'https'\n        ? undefined\n        : 'non-http(s) scheme; CORS may not match';\n    return { valid: true, info, wildcardKind: 'protocol' };\n  }\n\n  // Extract host (and optional port) while respecting IPv6 brackets\n  let host = normalizedRest;\n  let hasPort = false;\n\n  if (normalizedRest.startsWith('[')) {\n    const end = normalizedRest.indexOf(']');\n    if (end === -1) {\n      return {\n        valid: false,\n        info: 'unclosed IPv6 bracket',\n        wildcardKind: 'none',\n      };\n    }\n    host = normalizedRest.slice(0, end + 1);\n    const after = normalizedRest.slice(end + 1);\n    if (after.startsWith(':')) {\n      const port = after.slice(1);\n\n      if (!isValidPortString(port)) {\n        return {\n          valid: false,\n          info: 'invalid port in origin',\n          wildcardKind: 'none',\n        };\n      }\n\n      // port present -> allowed for exact origins, but reject with wildcard hosts below\n      // leave host as bracketed literal\n      hasPort = true;\n    } else if (after.length > 0) {\n      return {\n        valid: false,\n        info: 'unexpected characters after IPv6 host',\n        wildcardKind: 'none',\n      };\n    }\n  } else {\n    // strip port if present\n    const colon = normalizedRest.indexOf(':');\n    if (colon !== -1) {\n      host = normalizedRest.slice(0, colon);\n      const port = normalizedRest.slice(colon + 1);\n\n      if (!isValidPortString(port)) {\n        return {\n          valid: false,\n          info: 'invalid port in origin',\n          wildcardKind: 'none',\n        };\n      }\n\n      // optional port part is fine for exact origins\n      hasPort = true;\n    }\n  }\n\n  // If wildcard present in origin authority, treat as protocol+domain wildcard\n  if (host.includes('*')) {\n    if (scheme !== 'http' && scheme !== 'https') {\n      return {\n        valid: false,\n        info: 'wildcard origins require http or https scheme',\n        wildcardKind: 'none',\n      };\n    }\n\n    // Forbid ports/brackets with wildcard hosts\n    if (host.includes('[') || host.includes(']')) {\n      return {\n        valid: false,\n        info: 'wildcard host cannot be an IP literal',\n        wildcardKind: 'none',\n      };\n    }\n\n    if (hasPort) {\n      return {\n        valid: false,\n        info: 'ports are not allowed in wildcard origins',\n        wildcardKind: 'none',\n      };\n    }\n\n    // Validate as domain wildcard\n    const verdict = validateDomainWildcard(host);\n    if (!verdict.valid) {\n      return verdict;\n    }\n\n    const info =\n      scheme === 'http' || scheme === 'https'\n        ? undefined\n        : 'non-http(s) scheme; CORS may not match';\n    return { valid: true, info, wildcardKind: 'subdomain' };\n  }\n\n  // Exact origin: allow any scheme; validate host as domain or IP\n  if (host.startsWith('[')) {\n    const bracketContent = host.slice(1, -1);\n\n    if (!isIPv6(bracketContent)) {\n      return {\n        valid: false,\n        info: 'invalid IPv6 literal in origin',\n        wildcardKind: 'none',\n      };\n    }\n\n    const info =\n      scheme === 'http' || scheme === 'https'\n        ? undefined\n        : 'non-http(s) scheme; CORS may not match';\n\n    return { valid: true, info, wildcardKind: 'none' };\n  }\n\n  const hostDots = toAsciiDots(host);\n  if (isIPAddress(hostDots)) {\n    const info =\n      scheme === 'http' || scheme === 'https'\n        ? undefined\n        : 'non-http(s) scheme; CORS may not match';\n    return { valid: true, info, wildcardKind: 'none' };\n  }\n\n  // Domain host\n  const nd = normalizeDomain(host);\n\n  if (nd === '') {\n    return {\n      valid: false,\n      info: 'invalid domain in origin',\n      wildcardKind: 'none',\n    };\n  }\n  const ps = getPublicSuffix(nd);\n  if (ps && ps === nd && !INTERNAL_PSEUDO_TLDS.has(nd)) {\n    return {\n      valid: false,\n      info: 'origin host equals a public suffix (not registrable)',\n      wildcardKind: 'none',\n    };\n  }\n  const info =\n    scheme === 'http' || scheme === 'https'\n      ? undefined\n      : 'non-http(s) scheme; CORS may not match';\n  return { valid: true, info, wildcardKind: 'none' };\n}\n\n/**\n * Parse an exact origin for list matching.\n * Rejects userinfo, non-empty paths, queries, and fragments so malformed inputs\n * are not silently normalized into broader origins.\n */\nfunction parseExactOriginForMatching(entry: string): {\n  normalizedOrigin: string;\n  normalizedHostname: string;\n} | null {\n  if (entry === 'null') {\n    return { normalizedOrigin: 'null', normalizedHostname: '' };\n  }\n\n  const normalized = toAsciiDots(entry);\n  const schemeIdx = normalized.indexOf('://');\n\n  if (schemeIdx !== -1) {\n    const authority = extractAuthority(normalized, schemeIdx);\n    const at = authority.lastIndexOf('@');\n    const hostPort = at === -1 ? authority : authority.slice(at + 1);\n\n    if (hostPort.endsWith(':')) {\n      return null;\n    }\n  }\n\n  const url = safeParseURL(normalized);\n  if (!url) {\n    return null;\n  }\n\n  if (url.username || url.password) {\n    return null;\n  }\n\n  if (url.pathname && url.pathname !== '/') {\n    return null;\n  }\n\n  if (url.search || url.hash) {\n    return null;\n  }\n\n  const normalizedOrigin = normalizeOrigin(entry);\n  if (normalizedOrigin === '') {\n    return null;\n  }\n\n  return {\n    normalizedOrigin,\n    normalizedHostname: normalizeDomain(url.hostname),\n  };\n}\n\nfunction isCredentialsSafeWildcardOriginPattern(pattern: string): boolean {\n  const trimmed = pattern\n    .trim()\n    .normalize('NFC')\n    .replace(/[．。｡]/g, '.');\n\n  function isValidCredentialWildcardHost(hostPattern: string): boolean {\n    if (isAllWildcards(hostPattern)) {\n      return false;\n    }\n\n    if (INVALID_DOMAIN_CHARS.test(hostPattern)) {\n      return false;\n    }\n\n    if (hasPartialLabelWildcard(hostPattern)) {\n      return false;\n    }\n\n    const labels = hostPattern.split('.');\n    const concrete: string[] = [];\n\n    for (const lbl of labels) {\n      if (lbl === '*' || lbl === '**') {\n        continue;\n      }\n\n      if (lbl.length > 63) {\n        return false;\n      }\n\n      const nd = normalizeDomain(lbl);\n      if (nd === '') {\n        return false;\n      }\n\n      concrete.push(nd);\n    }\n\n    if (concrete.length > 0 && !checkDNSLength(concrete.join('.'))) {\n      return false;\n    }\n\n    const normalized = normalizeWildcardPattern(hostPattern);\n    const { fixedTail } = extractFixedTailAfterLastWildcard(\n      (normalized || hostPattern).split('.'),\n    );\n    if (!normalized || fixedTail.length === 0) {\n      return false;\n    }\n\n    const tail = fixedTail.join('.');\n    if (isIPAddress(tail)) {\n      return false;\n    }\n\n    const ps = getPublicSuffix(tail);\n    return !INTERNAL_PSEUDO_TLDS.has(tail) && !(ps && ps === tail);\n  }\n\n  if (!trimmed.includes('*')) {\n    return false;\n  }\n\n  const schemeIdx = trimmed.indexOf('://');\n  if (schemeIdx === -1) {\n    return isValidCredentialWildcardHost(trimmed);\n  }\n\n  const scheme = trimmed.slice(0, schemeIdx).toLowerCase();\n  const host = trimmed.slice(schemeIdx + 3);\n\n  if ((scheme !== 'http' && scheme !== 'https') || host === '*') {\n    return false;\n  }\n\n  return isValidCredentialWildcardHost(host);\n}\n\n/**\n * Helper function to check origin list with wildcard support.\n * Supports exact matches, wildcard matches, and normalization.\n *\n * Exact origins may use non-HTTP(S) schemes and are compared exactly.\n * Wildcard matching remains HTTP(S)-only.\n * Blank allowlist entries are ignored after trimming.\n * Special case: single \"*\" matches any valid HTTP(S) origin.\n *\n * @param origin - The origin to check (undefined for requests without Origin header)\n * @param allowedOrigins - Array of allowed origin patterns\n * @param opts - Options for handling edge cases\n * @param opts.treatNoOriginAsAllowed - If true, allows requests without Origin header when \"*\" is in the allowed list\n */\nexport function matchesOriginList(\n  origin: string | undefined,\n  allowedOrigins: string[],\n  opts: { treatNoOriginAsAllowed?: boolean } = {},\n): boolean {\n  const cleaned = allowedOrigins.map((s) => s.trim()).filter(Boolean);\n\n  if (!origin) {\n    // Only allow requests without Origin header if explicitly opted in AND \"*\" is in the list\n    return !!opts.treatNoOriginAsAllowed && cleaned.includes('*');\n  }\n\n  const parsedOrigin = parseExactOriginForMatching(origin);\n  if (!parsedOrigin) {\n    return false;\n  }\n\n  return cleaned.some((allowed) => {\n    // Global wildcard: single \"*\" matches any origin - delegate to matchesWildcardOrigin for proper validation\n    if (allowed === '*') {\n      return matchesWildcardOrigin(origin, '*');\n    }\n\n    if (allowed.includes('*')) {\n      // Avoid double-normalizing/parsing; wildcard matcher handles parsing + normalization itself\n      // We pass the raw origin/pattern here (vs normalized in the non-wildcard path) because\n      // the wildcard matcher needs to parse the origin as a URL for protocol/host extraction\n      return matchesWildcardOrigin(origin, allowed);\n    }\n\n    if (allowed === 'null') {\n      return parsedOrigin.normalizedOrigin === 'null';\n    }\n\n    if (!allowed.includes('://')) {\n      const normalizedAllowedDomain = normalizeDomain(allowed);\n\n      return (\n        isAllowedExactHostname(normalizedAllowedDomain) &&\n        parsedOrigin.normalizedHostname !== '' &&\n        parsedOrigin.normalizedHostname === normalizedAllowedDomain\n      );\n    }\n\n    const parsedAllowed = parseExactOriginForMatching(allowed);\n    if (!parsedAllowed) {\n      return false;\n    }\n\n    if (!isAllowedExactHostname(parsedAllowed.normalizedHostname)) {\n      return false;\n    }\n\n    return parsedOrigin.normalizedOrigin === parsedAllowed.normalizedOrigin;\n  });\n}\n\n/**\n * Helper function to check if origin matches any pattern in a list (credentials-safe).\n *\n * Exact origins may use non-HTTP(S) schemes and are compared exactly.\n * When `allowWildcardSubdomains` is enabled, only host subdomain wildcard\n * patterns are honored. Global \"*\" and protocol-only wildcards such as\n * \"https://*\" are intentionally not honored in credentials mode.\n * Blank allowlist entries are ignored after trimming.\n */\nexport function matchesCORSCredentialsList(\n  origin: string | undefined,\n  allowedOrigins: string[],\n  options: { allowWildcardSubdomains?: boolean } = {},\n): boolean {\n  if (!origin) {\n    return false;\n  }\n\n  const parsedOrigin = parseExactOriginForMatching(origin);\n  if (!parsedOrigin) {\n    return false;\n  }\n\n  const cleaned = allowedOrigins.map((s) => s.trim()).filter(Boolean);\n\n  const allowWildcard = !!options.allowWildcardSubdomains;\n\n  for (const allowed of cleaned) {\n    // Optional wildcard support for credentials lists (subdomain patterns only)\n    if (allowWildcard && allowed.includes('*')) {\n      if (\n        isCredentialsSafeWildcardOriginPattern(allowed) &&\n        matchesWildcardOrigin(origin, allowed)\n      ) {\n        return true;\n      }\n      continue;\n    }\n\n    if (allowed === 'null') {\n      if (parsedOrigin.normalizedOrigin === 'null') {\n        return true;\n      }\n\n      continue;\n    }\n\n    if (!allowed.includes('://')) {\n      const normalizedAllowedDomain = normalizeDomain(allowed);\n\n      if (\n        isAllowedExactHostname(normalizedAllowedDomain) &&\n        parsedOrigin.normalizedHostname !== '' &&\n        parsedOrigin.normalizedHostname === normalizedAllowedDomain\n      ) {\n        return true;\n      }\n\n      continue;\n    }\n\n    const parsedAllowed = parseExactOriginForMatching(allowed);\n    if (!parsedAllowed) {\n      continue;\n    }\n\n    if (!isAllowedExactHostname(parsedAllowed.normalizedHostname)) {\n      continue;\n    }\n\n    if (parsedOrigin.normalizedOrigin === parsedAllowed.normalizedOrigin) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Result of parsing a Host header\n */\nexport interface ParsedHost {\n  /** Domain/hostname with brackets stripped (e.g., \"[::1]\" → \"::1\") */\n  domain: string;\n  /** Port number as string, or empty string if no port specified */\n  port: string;\n}\n\n/**\n * Parse Host header into domain and port components\n * Supports IPv6 brackets and handles port extraction with strict validation\n *\n * This function is commonly used to parse the HTTP Host header,\n * which may contain:\n * - Regular hostnames: \"example.com\" or \"example.com:8080\"\n * - IPv6 addresses: \"[::1]\" or \"[::1]:8080\"\n * - IPv4 addresses: \"127.0.0.1\" or \"127.0.0.1:8080\"\n *\n * The returned domain has brackets stripped for normalization\n * (e.g., \"[::1]\" → \"::1\"), while port is returned separately.\n *\n * **Strict validation:** For bracketed IPv6 addresses, after the closing bracket `]`,\n * only the following are valid:\n * - Nothing (end of string): `[::1]` → valid\n * - Port with colon: `[::1]:8080` → valid\n * - Any other characters: `[::1]garbage`, `[::1][::2]` → returns empty (malformed)\n *\n * @param host - Host header value (hostname[:port] or [ipv6][:port])\n * @returns Object with domain (without brackets) and port (empty string if no port).\n *          Returns `{ domain: '', port: '' }` for malformed input.\n *\n * @example\n * parseHostHeader('example.com:8080')\n * // => { domain: 'example.com', port: '8080' }\n *\n * parseHostHeader('[::1]:8080')\n * // => { domain: '::1', port: '8080' }\n *\n * parseHostHeader('[2001:db8::1]')\n * // => { domain: '2001:db8::1', port: '' }\n *\n * parseHostHeader('localhost')\n * // => { domain: 'localhost', port: '' }\n *\n * parseHostHeader('[::1][::2]') // malformed\n * // => { domain: '', port: '' }\n */\nexport function parseHostHeader(host: string): ParsedHost {\n  const trimmedHost = host.trim();\n\n  if (!trimmedHost) {\n    return { domain: '', port: '' };\n  }\n\n  function parsePortOrFail(port: string): ParsedHost | null {\n    if (!isValidPortString(port)) {\n      return { domain: '', port: '' };\n    }\n\n    return null;\n  }\n\n  // Handle IPv6 brackets\n  if (trimmedHost.startsWith('[')) {\n    const end = trimmedHost.indexOf(']');\n\n    if (end !== -1) {\n      const domain = trimmedHost.slice(1, end); // Remove brackets for normalization\n      const rest = trimmedHost.slice(end + 1);\n\n      if (!isIPv6(domain)) {\n        return { domain: '', port: '' };\n      }\n\n      // Strict validation: after closing bracket, only allow empty or :port\n      if (rest === '') {\n        return { domain, port: '' };\n      }\n\n      if (rest.startsWith(':')) {\n        const invalid = parsePortOrFail(rest.slice(1));\n        if (invalid) {\n          return invalid;\n        }\n\n        return { domain, port: rest.slice(1) };\n      }\n\n      // Malformed: has junk after closing bracket (e.g., \"[::1]garbage\" or \"[::1][::2]\")\n      return { domain: '', port: '' };\n    }\n\n    // Malformed bracket - missing closing bracket\n    return { domain: '', port: '' };\n  }\n\n  // Regular hostname:port parsing\n  const idx = trimmedHost.indexOf(':');\n\n  if (idx === -1) {\n    return { domain: trimmedHost, port: '' };\n  }\n\n  if (idx === 0) {\n    return { domain: '', port: '' };\n  }\n\n  const invalid = parsePortOrFail(trimmedHost.slice(idx + 1));\n  if (invalid) {\n    return invalid;\n  }\n\n  return {\n    domain: trimmedHost.slice(0, idx),\n    port: trimmedHost.slice(idx + 1),\n  };\n}\n\n/**\n * Helper function to check if domain is apex (no subdomain)\n * Uses tldts to properly handle multi-part TLDs like .co.uk\n */\nexport function isApexDomain(domain: string): boolean {\n  const normalizedDomain = normalizeDomain(domain);\n\n  if (!normalizedDomain || isIPAddress(normalizedDomain)) {\n    return false;\n  }\n\n  // Handle pseudo-TLD domains before tldts, which doesn't know about them.\n  const labels = normalizedDomain.split('.');\n  const lastLabel = labels[labels.length - 1];\n  if (INTERNAL_PSEUDO_TLDS.has(lastLabel)) {\n    if (normalizedDomain === lastLabel) {\n      return true; // bare pseudo-TLD hostname (e.g. localhost, local) → apex\n    }\n    if (lastLabel === 'localhost') {\n      return false; // localhost is a hostname, not a TLD; sub.localhost is not apex\n    }\n    return labels.length === 2; // foo.local → apex; bar.foo.local → not\n  }\n\n  // Use tldts to properly detect apex domains vs subdomains\n  // This correctly handles multi-part TLDs like .co.uk, .com.au, etc.\n  const parsedDomain = getDomain(normalizedDomain);\n  const subdomain = getSubdomain(normalizedDomain);\n\n  // Guard against null returns from tldts for invalid hosts\n  if (!parsedDomain) {\n    return false;\n  }\n\n  // Domain is apex if it matches the parsed domain and has no subdomain\n  return parsedDomain === normalizedDomain && !subdomain;\n}\n\nexport {\n  normalizeDomain,\n  isIPAddress,\n  isIPv4,\n  isIPv6,\n  checkDNSLength,\n  canonicalizeBracketedIPv6Content,\n} from './helpers';\n\nexport { getDomain, getSubdomain } from 'tldts';\n","import { toASCII } from 'tr46';\n\n// Defense-in-depth: cap label processing to avoid pathological patterns\nexport const MAX_LABELS = 32;\n// Extra safety: cap recursive matching steps to avoid exponential blow-ups\nconst STEP_LIMIT = 10_000;\n\n// Invalid domain characters: ports, paths, fragments, brackets, userinfo, backslashes\nexport const INVALID_DOMAIN_CHARS = /[/?#:[\\]@\\\\]/;\n\n// Internal / special-use TLDs that we explicitly treat as non-PSL for wildcard-tail checks.\n// Keep this list explicit—do not guess.\n// Currently: 'localhost', 'local', 'test' (IANA special-use), and 'internal' (common in k8s/corporate).\n// If you want to allow other names (e.g., 'lan'), add them here deliberately.\nexport const INTERNAL_PSEUDO_TLDS = Object.freeze(\n  new Set<string>(['localhost', 'local', 'test', 'internal']),\n);\n\n// Helper functions for wildcard pattern validation\nexport function isAllWildcards(s: string): boolean {\n  return s.split('.').every((l) => l === '*' || l === '**');\n}\n\nexport function hasPartialLabelWildcard(s: string): boolean {\n  return s.split('.').some((l) => l.includes('*') && l !== '*' && l !== '**');\n}\n\n/**\n * Check DNS length constraints for hostnames (non-throwing):\n * - each label <= 63 octets\n * - total FQDN <= 255 octets\n * - max 127 labels (theoretical DNS limit)\n * Assumes ASCII input (post-TR46 processing).\n */\nexport function checkDNSLength(host: string): boolean {\n  const labels = host.split('.');\n\n  // Label count cap for domains (127 is theoretical DNS limit)\n  if (labels.length === 0 || labels.length > 127) {\n    return false;\n  }\n\n  let total = 0;\n  let i = 0;\n\n  for (const lbl of labels) {\n    const isLast = i++ === labels.length - 1;\n\n    if (lbl.length === 0) {\n      // Allow only a *trailing* empty label (for FQDN with a dot)\n      if (!isLast) {\n        return false;\n      }\n      continue;\n    }\n\n    if (lbl.length > 63) {\n      return false;\n    }\n\n    total += lbl.length + 1; // account for dot\n  }\n\n  return total > 0 ? total - 1 <= 255 : false;\n}\n\n// IPv6 regex pattern hoisted to module scope for performance\nconst IPV6_BASE_REGEX =\n  /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/;\n\n/**\n * Check if a string is an IPv4 address\n */\nexport function isIPv4(str: string): boolean {\n  const ipv4Regex =\n    /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;\n  return ipv4Regex.test(str);\n}\n\n/**\n * Check if a string is an IPv6 address\n */\nexport function isIPv6(str: string): boolean {\n  // Zone identifiers are intentionally rejected to keep behavior portable across\n  // Node, Bun, and browser-facing URL handling.\n  const cleaned = str.replace(/^\\[|\\]$/g, '');\n  if (cleaned.includes('%')) {\n    return false;\n  }\n\n  return IPV6_BASE_REGEX.test(cleaned);\n}\n\n/**\n * Check if a string is an IP address (IPv4 or IPv6)\n */\nexport function isIPAddress(str: string): boolean {\n  return isIPv4(str) || isIPv6(str);\n}\n\nfunction canonicalizeIPAddressLiteral(host: string): string | null {\n  const isIPAddressLike =\n    host.includes('.') ||\n    host.includes(':') ||\n    (host.startsWith('[') && host.endsWith(']'));\n\n  if (!isIPAddressLike) {\n    return null;\n  }\n\n  if (isIPv6(host)) {\n    return canonicalizeBracketedIPv6Content(host.replace(/^\\[|\\]$/g, ''));\n  }\n\n  try {\n    const url = new URL(`http://${host}/`);\n    const canonicalHostname = url.hostname.toLowerCase();\n\n    if (isIPv4(canonicalHostname)) {\n      return canonicalHostname;\n    }\n\n    if (isIPv6(canonicalHostname)) {\n      return canonicalHostname.replace(/^\\[|\\]$/g, '');\n    }\n  } catch {\n    // Fall through to regular domain normalization.\n  }\n\n  return null;\n}\n\n/**\n * Canonicalize IPv6 literal content for deterministic origin comparison.\n * Uses the platform URL parser so the result matches WHATWG URL origin semantics.\n */\nexport function canonicalizeBracketedIPv6Content(content: string): string {\n  try {\n    const url = new URL(`http://[${content}]/`);\n    return url.hostname.replace(/^\\[|\\]$/g, '');\n  } catch {\n    // Callers normally validate before canonicalizing; keep this helper\n    // non-throwing as a defensive fallback.\n    return content.toLowerCase();\n  }\n}\n\n/**\n * Extract the fixed tail (non-wildcard labels) after the last wildcard in a pattern.\n * Returns the labels that come after the rightmost wildcard in the pattern.\n *\n * @param patternLabels - Array of pattern labels (e.g., [\"*\", \"api\", \"example\", \"com\"])\n * @returns Object with fixedTailStart index and fixedTail labels array\n */\nexport function extractFixedTailAfterLastWildcard(patternLabels: string[]): {\n  fixedTailStart: number;\n  fixedTail: string[];\n} {\n  // Find the rightmost wildcard\n  let lastWildcardIdx = -1;\n  for (let i = patternLabels.length - 1; i >= 0; i--) {\n    const lbl = patternLabels[i];\n    if (lbl === '*' || lbl === '**') {\n      lastWildcardIdx = i;\n      break;\n    }\n  }\n\n  const fixedTailStart = lastWildcardIdx + 1;\n  const fixedTail = patternLabels.slice(fixedTailStart);\n\n  return { fixedTailStart, fixedTail };\n}\n\n/**\n * Internal recursive helper for wildcard label matching\n */\nfunction matchesWildcardLabelsInternal(\n  domainLabels: string[],\n  patternLabels: string[],\n  domainIndex: number,\n  patternIndex: number,\n  counter: { count: number },\n): boolean {\n  if (++counter.count > STEP_LIMIT) {\n    return false;\n  }\n\n  while (patternIndex < patternLabels.length) {\n    const patternLabel = patternLabels[patternIndex];\n\n    if (patternLabel === '**') {\n      const isLeftmost = patternIndex === 0;\n\n      // ** at index 0 means \"1+ labels\" while interior ** is \"0+\"\n      // If leftmost, require at least one domain label\n      if (isLeftmost) {\n        for (let i = domainIndex + 1; i <= domainLabels.length; i++) {\n          if (\n            matchesWildcardLabelsInternal(\n              domainLabels,\n              patternLabels,\n              i,\n              patternIndex + 1,\n              counter,\n            )\n          ) {\n            return true;\n          }\n        }\n        return false;\n      }\n\n      // Interior **: zero-or-more\n      if (\n        matchesWildcardLabelsInternal(\n          domainLabels,\n          patternLabels,\n          domainIndex,\n          patternIndex + 1,\n          counter,\n        )\n      ) {\n        return true;\n      }\n\n      // Try matching one or more labels\n      for (let i = domainIndex + 1; i <= domainLabels.length; i++) {\n        if (\n          matchesWildcardLabelsInternal(\n            domainLabels,\n            patternLabels,\n            i,\n            patternIndex + 1,\n            counter,\n          )\n        ) {\n          return true;\n        }\n      }\n      return false;\n    } else if (patternLabel === '*') {\n      // * matches exactly one label\n      if (domainIndex >= domainLabels.length) {\n        return false; // Not enough domain labels\n      }\n      domainIndex++;\n      patternIndex++;\n    } else {\n      // Exact label match\n      if (\n        domainIndex >= domainLabels.length ||\n        domainLabels[domainIndex] !== patternLabel\n      ) {\n        return false;\n      }\n      domainIndex++;\n      patternIndex++;\n    }\n  }\n\n  // All pattern labels matched, check if all domain labels are consumed\n  return domainIndex === domainLabels.length;\n}\n\n/**\n * Match domain labels against wildcard pattern labels\n */\nexport function matchesWildcardLabels(\n  domainLabels: string[],\n  patternLabels: string[],\n): boolean {\n  const counter = { count: 0 };\n  return matchesWildcardLabelsInternal(\n    domainLabels,\n    patternLabels,\n    0,\n    0,\n    counter,\n  );\n}\n\n/**\n * Helper function for label-wise wildcard matching\n * Supports patterns like *.example.com, **.example.com, *.*.example.com, etc.\n */\nexport function matchesMultiLabelPattern(\n  domain: string,\n  pattern: string,\n): boolean {\n  const domainLabels = domain.split('.');\n  const patternLabels = pattern.split('.');\n\n  // Guard against pathological label counts\n  if (domainLabels.length > MAX_LABELS || patternLabels.length > MAX_LABELS) {\n    return false;\n  }\n\n  // Pattern must have at least one non-wildcard label (the base domain)\n  if (\n    patternLabels.length === 0 ||\n    patternLabels.every((label) => label === '*' || label === '**')\n  ) {\n    return false;\n  }\n\n  // Extract the fixed tail after the last wildcard\n  const { fixedTailStart, fixedTail } =\n    extractFixedTailAfterLastWildcard(patternLabels);\n\n  // Domain must be at least as long as the fixed tail\n  if (domainLabels.length < fixedTail.length) {\n    return false;\n  }\n\n  // Match fixed tail exactly (right-aligned)\n  for (let i = 0; i < fixedTail.length; i++) {\n    const domainLabel =\n      domainLabels[domainLabels.length - fixedTail.length + i];\n    const patternLabel = fixedTail[i];\n    if (patternLabel !== domainLabel) {\n      return false;\n    }\n  }\n\n  // Now match the left side (which may include wildcards and fixed labels)\n  const remainingDomainLabels = domainLabels.slice(\n    0,\n    domainLabels.length - fixedTail.length,\n  );\n  const leftPatternLabels = patternLabels.slice(0, fixedTailStart);\n\n  if (leftPatternLabels.length === 0) {\n    // No left pattern, so only the fixed tail is required\n    return remainingDomainLabels.length === 0;\n  }\n\n  return matchesWildcardLabels(remainingDomainLabels, leftPatternLabels);\n}\n\n/**\n * Normalize Unicode dot variants to ASCII dots for consistent IP and domain handling\n * @param s - String that may contain Unicode dot variants\n * @returns String with Unicode dots normalized to ASCII dots\n */\nexport function toAsciiDots(s: string): string {\n  return s.replace(/[．。｡]/g, '.'); // fullwidth/japanese/halfwidth\n}\n\n/**\n * Normalize a domain name for consistent comparison\n * Handles trim, lowercase, a single trailing-dot FQDN form, NFC normalization,\n * and punycode conversion for IDN safety. Returns the canonical host form\n * without a trailing dot. Repeated trailing dots are rejected as invalid.\n * IP literals are canonicalized to a stable WHATWG URL-compatible form.\n */\nexport function normalizeDomain(domain: string): string {\n  let trimmed = domain.trim();\n\n  // Normalize Unicode dots BEFORE checking IP for consistent behavior\n  trimmed = toAsciiDots(trimmed);\n\n  // Allow a single trailing dot for FQDNs, but reject repeated trailing dots\n  if (/\\.\\.+$/.test(trimmed)) {\n    return '';\n  }\n\n  if (trimmed.endsWith('.')) {\n    trimmed = trimmed.slice(0, -1);\n  }\n\n  // Canonicalize IP literals up front so exact host checks line up with WHATWG URL parsing.\n  const canonicalIPAddress = canonicalizeIPAddressLiteral(trimmed);\n  if (canonicalIPAddress !== null) {\n    return canonicalIPAddress;\n  }\n\n  // Apply NFC normalization for Unicode domains\n  const normalized = trimmed.normalize('NFC').toLowerCase();\n\n  try {\n    // Use TR46/IDNA processing for robust Unicode domain handling that mirrors browser behavior\n    const ascii = toASCII(normalized, {\n      useSTD3ASCIIRules: true,\n      checkHyphens: true,\n      checkBidi: true,\n      checkJoiners: true,\n      transitionalProcessing: false, // matches modern browser behavior (non-transitional)\n      verifyDNSLength: false, // we already do our own length checks\n    });\n    if (!ascii) {\n      throw new Error('TR46 processing failed');\n    }\n    // Enforce DNS length constraints post-TR46\n    return checkDNSLength(ascii) ? ascii : ''; // return sentinel on invalid DNS lengths\n  } catch {\n    // On TR46 failure, return sentinel empty-string to signal invalid hostname\n    return '';\n  }\n}\n\n/**\n * Normalize a wildcard domain pattern by preserving wildcard labels\n * and punycode only non-wildcard labels. Also trims and removes\n * a trailing dot if present.\n */\nexport function normalizeWildcardPattern(pattern: string): string {\n  let trimmed = pattern\n    .trim()\n    .normalize('NFC')\n    .replace(/[．。｡]/g, '.'); // normalize Unicode dot variants to ASCII\n\n  // Refuse non-domain characters (ports, paths, fragments, brackets, userinfo, backslashes)\n  if (INVALID_DOMAIN_CHARS.test(trimmed)) {\n    return ''; // sentinel for invalid pattern\n  }\n\n  if (trimmed.endsWith('.')) {\n    trimmed = trimmed.slice(0, -1);\n  }\n\n  const labels = trimmed.split('.');\n\n  // Reject empty labels post-split early (e.g., *..example.com)\n  // This avoids double dots slipping to punycode\n  for (const lbl of labels) {\n    if (lbl.length === 0) {\n      return ''; // sentinel for invalid pattern (no empty labels)\n    }\n  }\n\n  const normalizedLabels = [];\n  for (const lbl of labels) {\n    if (lbl === '*' || lbl === '**') {\n      normalizedLabels.push(lbl);\n      continue;\n    }\n\n    // Pre-punycode check for obviously invalid labels\n    if (lbl.length > 63) {\n      return ''; // sentinel for invalid pattern\n    }\n\n    const nd = normalizeDomain(lbl);\n\n    if (nd === '') {\n      // Invalid label after normalization\n      return ''; // sentinel for invalid pattern\n    }\n\n    normalizedLabels.push(nd);\n  }\n\n  // Extract concrete (non-wildcard) labels and validate final ASCII length\n  const concreteLabels = normalizedLabels.filter(\n    (lbl) => lbl !== '*' && lbl !== '**',\n  );\n  if (concreteLabels.length > 0) {\n    const concretePattern = concreteLabels.join('.');\n    // Validate the ASCII length of the concrete parts to prevent pathological long IDNs\n    if (!checkDNSLength(concretePattern)) {\n      return ''; // sentinel for invalid pattern\n    }\n  }\n\n  return normalizedLabels.join('.');\n}\n"],"mappings":"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","names":["import_qs","import_tldts","Router","qs"]}

package/dist/lib/http-client-mock/index.d.cts

@@ -0,0 +1,129 @@
+import { H as HTTPAdapter, Q as QueryObject, C as ContentType, A as AdapterType, a as AdapterRequest, b as AdapterResponse } from '../../types-CUPvmYQ8.cjs';
+import '../../types-D_MywcG0.cjs';
+
+interface MockFormData {
+    /** String fields from the multipart body */
+    fields: Record<string, string>;
+    /** File fields from the multipart body */
+    files: Record<string, File>;
+}
+interface MockRequest {
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    query: QueryObject;
+    headers: Record<string, string>;
+    /**
+     * Parsed cookies from the `cookie` request header — same data as
+     * `headers.cookie`, pre-parsed for convenience.
+     */
+    cookies: Record<string, string>;
+    /**
+     * Parsed request body for mock handlers.
+     * JSON bodies are parsed, text bodies stay strings, binary bodies stay as
+     * `Uint8Array`, and multipart/form-data bodies become `MockFormData`.
+     */
+    body?: unknown;
+}
+/** Cookie attributes for the `MockResponse.cookies` shorthand. */
+interface MockCookieOptions {
+    value: string;
+    /** Seconds until the cookie expires. Use `0` or a negative value to expire it immediately. */
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    /** Defaults to `'/'` when omitted. */
+    path?: string;
+    domain?: string;
+}
+interface MockResponse {
+    status: number;
+    /**
+     * Response entity body. Aligned with outgoing request rules in `serializeBody`
+     * / `assertSupportedRequestBody`, except mock responses do not use `FormData`.
+     *
+     * Supported values (anything else throws when serialized):
+     *
+     * - `undefined` or omitted — no body
+     * - `null` — no body
+     * - `string` — UTF-8 bytes
+     * - `Uint8Array` — raw bytes unchanged
+     * - `ArrayBuffer` — copied to a `Uint8Array`
+     * - plain object (`Object.prototype` or `null` prototype) — JSON
+     * - array — JSON
+     */
+    body?: unknown;
+    /**
+     * Raw response headers. Use `set-cookie: string[]` for multiple cookies,
+     * same as real HTTP. Merged with any entries from `cookies`.
+     */
+    headers?: Record<string, string | string[]>;
+    contentType?: ContentType;
+    delay?: number;
+    /**
+     * Shorthand for setting / deleting cookies without writing raw Set-Cookie
+     * strings. Merged with any `set-cookie` entries already in `headers`.
+     *
+     * - `string` → `name=value; Path=/` — session cookie (no expiry)
+     * - `null` → `name=; Path=/; Max-Age=0` — deletes that same default
+     *   root-scoped cookie
+     * - `MockCookieOptions` → full control over path, domain, and attributes;
+     *   when deleting one of these scoped cookies, the delete cookie must use
+     *   the same identity (name + path + domain) and typically `maxAge: 0`
+     */
+    cookies?: Record<string, string | MockCookieOptions | null>;
+}
+type MockRouteHandler = (request: MockRequest) => MockResponse | Promise<MockResponse>;
+interface MockAdapterConfig {
+    defaultDelay?: number;
+    /**
+     * Called when a route handler throws. Return a `MockResponse` to customize
+     * the error response — similar to Fastify's `setErrorHandler`. Falls back to
+     * the default `{ status: 500, body: { message: 'Internal Server Error' } }`
+     * if this handler is not set or if it also throws.
+     */
+    onError?: (req: MockRequest, error: unknown) => MockResponse | Promise<MockResponse>;
+}
+/**
+ * Routes match on **path only** — the domain/host in the request URL is
+ * stripped before matching. `http://api.test/users` and
+ * `http://auth.test/users` both match a registered `/users` route.
+ *
+ * **Multiple domains** — use separate `MockAdapter` instances and assign
+ * them to the root client and sub-clients respectively:
+ *
+ * ```ts
+ * const apiMock = new MockAdapter();
+ * const authMock = new MockAdapter();
+ * const client = new HTTPClient({ adapter: apiMock, baseURL: 'https://api.test' });
+ * const authClient = client.createSubClient({ adapter: authMock, baseURL: 'https://auth.test' });
+ * ```
+ *
+ * **Cross-domain redirects** — redirects are followed by the same adapter
+ * that initiated the request. Since domain is stripped, a redirect to
+ * `https://auth.test/callback` will match a `/callback` route on the
+ * originating adapter — no special setup needed for single-adapter setups.
+ * For separate-adapter setups, register the redirect target path on the
+ * originating adapter as well.
+ */
+interface MockAdapterRoutes {
+    get(path: string, handler: MockRouteHandler): void;
+    post(path: string, handler: MockRouteHandler): void;
+    put(path: string, handler: MockRouteHandler): void;
+    patch(path: string, handler: MockRouteHandler): void;
+    delete(path: string, handler: MockRouteHandler): void;
+    head(path: string, handler: MockRouteHandler): void;
+    /** Remove all registered routes. */
+    clear(): void;
+}
+declare class MockAdapter implements HTTPAdapter {
+    readonly routes: MockAdapterRoutes;
+    private readonly router;
+    private readonly config;
+    constructor(config?: MockAdapterConfig);
+    getType(): AdapterType;
+    send(request: AdapterRequest): Promise<AdapterResponse>;
+}
+
+export { MockAdapter, type MockAdapterConfig, type MockAdapterRoutes, type MockCookieOptions, type MockFormData, type MockRequest, type MockResponse, type MockRouteHandler };

package/dist/lib/http-client-mock/index.d.ts

@@ -0,0 +1,129 @@
+import { H as HTTPAdapter, Q as QueryObject, C as ContentType, A as AdapterType, a as AdapterRequest, b as AdapterResponse } from '../../types-Hw2PUTIT.js';
+import '../../types-D_MywcG0.js';
+
+interface MockFormData {
+    /** String fields from the multipart body */
+    fields: Record<string, string>;
+    /** File fields from the multipart body */
+    files: Record<string, File>;
+}
+interface MockRequest {
+    method: string;
+    path: string;
+    params: Record<string, string>;
+    query: QueryObject;
+    headers: Record<string, string>;
+    /**
+     * Parsed cookies from the `cookie` request header — same data as
+     * `headers.cookie`, pre-parsed for convenience.
+     */
+    cookies: Record<string, string>;
+    /**
+     * Parsed request body for mock handlers.
+     * JSON bodies are parsed, text bodies stay strings, binary bodies stay as
+     * `Uint8Array`, and multipart/form-data bodies become `MockFormData`.
+     */
+    body?: unknown;
+}
+/** Cookie attributes for the `MockResponse.cookies` shorthand. */
+interface MockCookieOptions {
+    value: string;
+    /** Seconds until the cookie expires. Use `0` or a negative value to expire it immediately. */
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    /** Defaults to `'/'` when omitted. */
+    path?: string;
+    domain?: string;
+}
+interface MockResponse {
+    status: number;
+    /**
+     * Response entity body. Aligned with outgoing request rules in `serializeBody`
+     * / `assertSupportedRequestBody`, except mock responses do not use `FormData`.
+     *
+     * Supported values (anything else throws when serialized):
+     *
+     * - `undefined` or omitted — no body
+     * - `null` — no body
+     * - `string` — UTF-8 bytes
+     * - `Uint8Array` — raw bytes unchanged
+     * - `ArrayBuffer` — copied to a `Uint8Array`
+     * - plain object (`Object.prototype` or `null` prototype) — JSON
+     * - array — JSON
+     */
+    body?: unknown;
+    /**
+     * Raw response headers. Use `set-cookie: string[]` for multiple cookies,
+     * same as real HTTP. Merged with any entries from `cookies`.
+     */
+    headers?: Record<string, string | string[]>;
+    contentType?: ContentType;
+    delay?: number;
+    /**
+     * Shorthand for setting / deleting cookies without writing raw Set-Cookie
+     * strings. Merged with any `set-cookie` entries already in `headers`.
+     *
+     * - `string` → `name=value; Path=/` — session cookie (no expiry)
+     * - `null` → `name=; Path=/; Max-Age=0` — deletes that same default
+     *   root-scoped cookie
+     * - `MockCookieOptions` → full control over path, domain, and attributes;
+     *   when deleting one of these scoped cookies, the delete cookie must use
+     *   the same identity (name + path + domain) and typically `maxAge: 0`
+     */
+    cookies?: Record<string, string | MockCookieOptions | null>;
+}
+type MockRouteHandler = (request: MockRequest) => MockResponse | Promise<MockResponse>;
+interface MockAdapterConfig {
+    defaultDelay?: number;
+    /**
+     * Called when a route handler throws. Return a `MockResponse` to customize
+     * the error response — similar to Fastify's `setErrorHandler`. Falls back to
+     * the default `{ status: 500, body: { message: 'Internal Server Error' } }`
+     * if this handler is not set or if it also throws.
+     */
+    onError?: (req: MockRequest, error: unknown) => MockResponse | Promise<MockResponse>;
+}
+/**
+ * Routes match on **path only** — the domain/host in the request URL is
+ * stripped before matching. `http://api.test/users` and
+ * `http://auth.test/users` both match a registered `/users` route.
+ *
+ * **Multiple domains** — use separate `MockAdapter` instances and assign
+ * them to the root client and sub-clients respectively:
+ *
+ * ```ts
+ * const apiMock = new MockAdapter();
+ * const authMock = new MockAdapter();
+ * const client = new HTTPClient({ adapter: apiMock, baseURL: 'https://api.test' });
+ * const authClient = client.createSubClient({ adapter: authMock, baseURL: 'https://auth.test' });
+ * ```
+ *
+ * **Cross-domain redirects** — redirects are followed by the same adapter
+ * that initiated the request. Since domain is stripped, a redirect to
+ * `https://auth.test/callback` will match a `/callback` route on the
+ * originating adapter — no special setup needed for single-adapter setups.
+ * For separate-adapter setups, register the redirect target path on the
+ * originating adapter as well.
+ */
+interface MockAdapterRoutes {
+    get(path: string, handler: MockRouteHandler): void;
+    post(path: string, handler: MockRouteHandler): void;
+    put(path: string, handler: MockRouteHandler): void;
+    patch(path: string, handler: MockRouteHandler): void;
+    delete(path: string, handler: MockRouteHandler): void;
+    head(path: string, handler: MockRouteHandler): void;
+    /** Remove all registered routes. */
+    clear(): void;
+}
+declare class MockAdapter implements HTTPAdapter {
+    readonly routes: MockAdapterRoutes;
+    private readonly router;
+    private readonly config;
+    constructor(config?: MockAdapterConfig);
+    getType(): AdapterType;
+    send(request: AdapterRequest): Promise<AdapterResponse>;
+}
+
+export { MockAdapter, type MockAdapterConfig, type MockAdapterRoutes, type MockCookieOptions, type MockFormData, type MockRequest, type MockResponse, type MockRouteHandler };