npm - @adcp/sdk - Versions diffs - 13.0.0-rc.6 → 13.0.0-rc.8 - Mend

@adcp/sdk 13.0.0-rc.6 → 13.0.0-rc.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1606) hide show

package/dist/lib/errors/index.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../../../src/lib/errors/index.ts"],"sourcesContent":["// Custom error classes for ADCP client library\n\n/*\n Base class for all ADCP client errors\n /\nexport abstract class ADCPError extends Error {\n abstract readonly code: string;\n\n constructor(\n message: string,\n public details?: unknown\n ) {\n super(message);\n this.name = this.constructor.name;\n }\n}\n\n/\n Error thrown when a task times out\n /\nexport class TaskTimeoutError extends ADCPError {\n readonly code = 'TASK_TIMEOUT';\n\n constructor(\n public readonly taskId: string,\n public readonly timeout: number\n ) {\n super(`Task ${taskId} timed out after ${timeout}ms`);\n }\n}\n\n/\n Error thrown when maximum clarification attempts are exceeded\n /\nexport class MaxClarificationError extends ADCPError {\n readonly code = 'MAX_CLARIFICATIONS';\n\n constructor(\n public readonly taskId: string,\n public readonly maxAttempts: number\n ) {\n super(`Task ${taskId} exceeded maximum clarification attempts: ${maxAttempts}`);\n }\n}\n\n/\n Error thrown when a task is deferred to human\n * Contains the token needed to resume the task\n /\nexport class DeferredTaskError extends ADCPError {\n readonly code = 'TASK_DEFERRED';\n\n constructor(public readonly token: string) {\n super(`Task deferred with token: ${token}`);\n }\n}\n\n/\n Error thrown when a task is aborted\n /\nexport class TaskAbortedError extends ADCPError {\n readonly code = 'TASK_ABORTED';\n\n constructor(\n public readonly taskId: string,\n public readonly reason?: string\n ) {\n super(`Task ${taskId} aborted: ${reason \|\| 'No reason provided'}`);\n }\n}\n\n/\n Error thrown when an agent is not found\n /\nexport class AgentNotFoundError extends ADCPError {\n readonly code = 'AGENT_NOT_FOUND';\n\n constructor(\n public readonly agentId: string,\n public readonly availableAgents: string[]\n ) {\n super(`Agent '${agentId}' not found. Available agents: ${availableAgents.join(', ')}`);\n }\n}\n\n/\n Error thrown when an agent doesn't support a task\n /\nexport class UnsupportedTaskError extends ADCPError {\n readonly code = 'UNSUPPORTED_TASK';\n\n constructor(\n public readonly agentId: string,\n public readonly taskName: string,\n public readonly supportedTasks?: string[]\n ) {\n const tasksMsg = supportedTasks ? ` Supported tasks: ${supportedTasks.join(', ')}` : '';\n super(`Agent '${agentId}' does not support task '${taskName}'.${tasksMsg}`);\n }\n}\n\n/\n Error thrown when protocol communication fails\n /\nexport class ProtocolError extends ADCPError {\n readonly code = 'PROTOCOL_ERROR';\n\n constructor(\n public readonly protocol: 'mcp' \| 'a2a',\n message: string,\n public readonly originalError?: Error\n ) {\n super(`${protocol.toUpperCase()} protocol error: ${message}`);\n this.details = { originalError };\n }\n}\n\n/\n Error thrown when validation fails\n /\nexport class ValidationError extends ADCPError {\n readonly code = 'VALIDATION_ERROR';\n\n constructor(\n public readonly field: string,\n public readonly value: unknown,\n public readonly constraint: string\n ) {\n super(`Validation failed for field '${field}': ${constraint}`);\n this.details = { field, value, constraint };\n }\n}\n\n/\n Error thrown when input handler is missing but required\n /\nexport class MissingInputHandlerError extends ADCPError {\n readonly code = 'MISSING_INPUT_HANDLER';\n\n constructor(\n public readonly taskId: string,\n public readonly question: string\n ) {\n super(`Agent requested input but no handler provided. Task: ${taskId}, Question: ${question}`);\n }\n}\n\n/\n Error thrown when conversation context is invalid\n /\nexport class InvalidContextError extends ADCPError {\n readonly code = 'INVALID_CONTEXT';\n\n constructor(\n public readonly contextId: string,\n reason: string\n ) {\n super(`Invalid conversation context '${contextId}': ${reason}`);\n }\n}\n\n/\n Error thrown when configuration is invalid\n /\nexport class ConfigurationError extends ADCPError {\n readonly code = 'CONFIGURATION_ERROR';\n\n constructor(\n message: string,\n public readonly configField?: string\n ) {\n super(`Configuration error: ${message}`);\n this.details = { configField };\n }\n}\n\n/\n OAuth metadata for authentication guidance\n /\nexport interface OAuthMetadataInfo {\n /* URL of the authorization endpoint /\n authorization_endpoint: string;\n /* URL of the token endpoint /\n token_endpoint: string;\n /* URL of the dynamic client registration endpoint (optional) /\n registration_endpoint?: string;\n /* Issuer identifier /\n issuer?: string;\n}\n\n/\n Subset of the parsed `WWW-Authenticate` challenge surfaced on\n * {@link AuthenticationRequiredError}. Mirrors the public shape of\n * `WWWAuthenticateChallenge` from `@adcp/sdk/auth/oauth` without forcing the\n * errors module to depend on the auth subtree (the dependency would invert\n * the build graph).\n \n `scheme` is lowercased per RFC 9110 §11.6.1.\n /\nexport interface AuthChallengeInfo {\n scheme: string;\n realm?: string;\n scope?: string;\n error?: string;\n error_description?: string;\n}\n\n/\n Error thrown when authentication is required to access an MCP endpoint\n \n This error is thrown during MCP endpoint discovery when the server returns\n * a 401 Unauthorized response. The shape of the remediation depends on what\n * the 401 disclosed:\n \n - OAuth metadata (RFC 9728 PRM walk succeeded) → `oauthMetadata` set,\n * message points at the authorization endpoint.\n * - A `WWW-Authenticate` challenge with a non-Bearer scheme (e.g. Basic\n * behind an Apigee/Kong/AWS API GW gateway) → `challenge` set, message\n * names the scheme and the SDK / CLI surface that configures it.\n * - Plain 401 with no metadata → fallback \"provide auth_token\" message.\n \n Consumers branching on `error.challenge?.scheme === 'basic'` can route\n * straight to `auth: { type: 'basic', username, password }` instead of\n * retrying Bearer indefinitely.\n \n @example\n * ```typescript\n * try {\n * await client.getProducts({ brief: 'test' });\n * } catch (error) {\n * if (error instanceof AuthenticationRequiredError) {\n * if (error.challenge?.scheme === 'basic') {\n * // Gateway-fronted agent — configure HTTP Basic\n * reconnect({ auth: { type: 'basic', username, password } });\n * } else if (error.oauthMetadata) {\n * // Redirect user to OAuth flow\n * const authUrl = error.oauthMetadata.authorization_endpoint;\n * console.log(`Please authenticate at: ${authUrl}`);\n * } else {\n * console.log('Authentication required but no scheme metadata available');\n * }\n * }\n * }\n * ```\n /\nexport class AuthenticationRequiredError extends ADCPError {\n readonly code = 'AUTHENTICATION_REQUIRED';\n\n constructor(\n public readonly agentUrl: string,\n public readonly oauthMetadata?: OAuthMetadataInfo,\n message?: string,\n public readonly challenge?: AuthChallengeInfo\n ) {\n const defaultMessage = buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge);\n super(message \|\| defaultMessage);\n // `details` is serialized through error envelopes; surfacing the challenge\n // here lets non-CLI consumers (LLM agents, dashboards, programmatic\n // callers) branch on the scheme without instanceof-checking.\n this.details = { agentUrl, oauthMetadata, challenge };\n }\n\n /\n Check if OAuth authentication is available\n /\n get hasOAuth(): boolean {\n return this.oauthMetadata !== undefined;\n }\n\n /\n Get the authorization URL if OAuth is available\n /\n get authorizationUrl(): string \| undefined {\n return this.oauthMetadata?.authorization_endpoint;\n }\n\n /\n Lowercased scheme from the `WWW-Authenticate` challenge, when present.\n * `'basic'` is the common non-OAuth case — gateway-fronted agents speaking\n * RFC 7617.\n /\n get suggestedScheme(): string \| undefined {\n return this.challenge?.scheme;\n }\n}\n\n/\n Build the default error message. Branches on what the 401 disclosed:\n * - non-Bearer challenge (Basic, Digest, …) → scheme-specific remediation\n * - OAuth metadata → point at the authorization endpoint\n * - nothing → fallback \"provide auth_token\"\n \n The Basic branch names both the SDK shape (`createTestClient({ auth: …\n * type: 'basic' })`) and the CLI shape (`--auth user:pass --auth-scheme\n * basic`) so the same error envelope serves library and CLI consumers.\n /\nfunction buildAuthRequiredMessage(\n agentUrl: string,\n oauthMetadata: OAuthMetadataInfo \| undefined,\n challenge: AuthChallengeInfo \| undefined\n): string {\n if (challenge && challenge.scheme !== 'bearer') {\n if (challenge.scheme === 'basic') {\n return (\n `Authentication required for ${agentUrl}. Agent (or its fronting gateway) speaks HTTP Basic ` +\n `(RFC 7617). Configure via createTestClient({ auth: { type: 'basic', username, password } }) ` +\n `— or from the CLI, --auth <user:pass> --auth-scheme basic.`\n );\n }\n // Digest / Negotiate / NTLM / vendor schemes: we don't have first-class\n // support but the scheme name in the message saves a discovery round-trip.\n const realmHint = challenge.realm ? ` (realm: ${challenge.realm})` : '';\n return (\n `Authentication required for ${agentUrl}. Agent speaks ${challenge.scheme}${realmHint}, ` +\n `which is not natively supported by @adcp/sdk. Configure auth at the transport layer ` +\n `(custom fetch wrapper, reverse-proxy header injection) or contact the agent operator ` +\n `about Bearer / Basic / OAuth support.`\n );\n }\n if (oauthMetadata) {\n return `Authentication required for ${agentUrl}. OAuth available at: ${oauthMetadata.authorization_endpoint}`;\n }\n return `Authentication required for ${agentUrl}. No OAuth metadata available - provide auth_token in agent config.`;\n}\n\n/\n Error thrown when a request reused an `idempotency_key` with a different\n * canonical payload within the seller's replay window.\n \n Recovery: `correctable` — the caller either reused a key by mistake (mint\n * a fresh UUID v4 for the new request) or re-planned with a different payload\n * (an agent whose LLM re-ran and emitted a different request must treat that\n * as a new intent, not a retry).\n \n @example\n * ```typescript\n * try {\n * await client.createMediaBuy({...});\n * } catch (error) {\n * if (error instanceof IdempotencyConflictError) {\n * // Either the key was reused by mistake, or the agent re-planned with\n * // a different payload. Mint a fresh key and try again.\n * }\n * }\n * ```\n /\nexport class IdempotencyConflictError extends ADCPError {\n readonly code = 'IDEMPOTENCY_CONFLICT';\n\n // Exposed via the getter so `console.log(err)` and JSON.stringify don't\n // leak the key (it's a retry-pattern oracle within the seller's TTL).\n // Callers reading `err.idempotencyKey` get it normally.\n readonly idempotencyKey: string \| undefined;\n\n constructor(idempotencyKey: string \| undefined, message?: string) {\n super(\n message \|\|\n 'idempotency_key was used earlier with a different canonical payload. ' +\n 'Use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response.'\n );\n Object.defineProperty(this, 'idempotencyKey', {\n value: idempotencyKey,\n enumerable: false,\n writable: false,\n configurable: false,\n });\n }\n}\n\n/\n Error thrown when a request carries an `idempotency_key` that is past the\n * seller's declared replay window (plus clock-skew tolerance).\n \n Recovery: `correctable`. If the caller knows the prior call succeeded\n * (e.g., they saw the response once, then crashed), they SHOULD fall back\n * to a natural-key lookup (e.g., `get_media_buys` by\n * `context.internal_campaign_id`) rather than minting a new key — otherwise\n * the seller treats the new request as fresh and silently creates a duplicate.\n \n If the caller doesn't know whether the prior call succeeded, a fresh key\n * is safe.\n /\nexport class IdempotencyExpiredError extends ADCPError {\n readonly code = 'IDEMPOTENCY_EXPIRED';\n\n // Non-enumerable so `console.log(err)` / JSON.stringify don't leak it —\n // same reasoning as IdempotencyConflictError.idempotencyKey.\n readonly idempotencyKey: string \| undefined;\n\n constructor(idempotencyKey: string \| undefined, message?: string) {\n super(\n message \|\|\n \"idempotency_key is past the seller's replay window. \" +\n 'If you know the prior call succeeded, look up the resource by natural key before retrying. Otherwise, mint a fresh UUID v4.'\n );\n Object.defineProperty(this, 'idempotencyKey', {\n value: idempotencyKey,\n enumerable: false,\n writable: false,\n configurable: false,\n });\n }\n}\n\nexport interface FeatureUnsupportedErrorOptions {\n message?: string;\n details?: Record<string, unknown>;\n}\n\nexport type ClientPreflightAdcpErrorRecovery = 'transient' \| 'correctable' \| 'terminal';\n\n/\n Protocol-shaped error metadata attached to SDK-local preflight throws.\n * Mirrors the public `TaskResult.adcpError` fields without importing core\n * task types into the errors module.\n /\nexport interface ClientPreflightAdcpErrorInfo {\n code: string;\n message: string;\n recovery?: ClientPreflightAdcpErrorRecovery;\n field?: string;\n suggestion?: string;\n details?: Record<string, unknown>;\n}\n\nexport interface ProtocolFeatureUnsupportedErrorOptions extends FeatureUnsupportedErrorOptions {\n field?: string;\n suggestion?: string;\n recovery?: ClientPreflightAdcpErrorRecovery;\n}\n\nexport const SDK_ERROR_TO_PROTOCOL_ERROR_CODE = {\n FEATURE_UNSUPPORTED: 'UNSUPPORTED_FEATURE',\n} as const;\n\nexport function mapSdkErrorCodeToProtocolErrorCode(code: string): string \| undefined {\n return SDK_ERROR_TO_PROTOCOL_ERROR_CODE[code as keyof typeof SDK_ERROR_TO_PROTOCOL_ERROR_CODE];\n}\n\n/\n Error thrown when a required feature is not supported by the seller or by\n * the configured AdCP version.\n /\nexport class FeatureUnsupportedError extends ADCPError {\n readonly code: string = 'FEATURE_UNSUPPORTED';\n\n constructor(\n public readonly unsupportedFeatures: string[],\n public readonly declaredFeatures: string[],\n public readonly agentUrl?: string,\n options: FeatureUnsupportedErrorOptions = {}\n ) {\n const missing = unsupportedFeatures.join(', ');\n const declared = declaredFeatures.length > 0 ? declaredFeatures.join(', ') : '(none)';\n const urlPart = agentUrl ? ` at ${agentUrl}` : '';\n super(options.message ?? `Seller${urlPart} does not support: ${missing}\\n Declared features: ${declared}`);\n this.details = {\n unsupported_features: unsupportedFeatures,\n declared_features: declaredFeatures,\n ...(options.details ?? {}),\n };\n }\n}\n\n/\n Version-gate error for requests that use a protocol feature outside the\n * configured AdCP release. Kept as a FeatureUnsupportedError subclass so\n * existing catch sites keep working, while `code` carries the AdCP wire code\n * expected by probe/recovery layers.\n /\nexport class ProtocolFeatureUnsupportedError extends FeatureUnsupportedError {\n readonly code: string = 'UNSUPPORTED_FEATURE';\n\n readonly adcpError: ClientPreflightAdcpErrorInfo;\n\n constructor(\n unsupportedFeatures: string[],\n declaredFeatures: string[],\n agentUrl?: string,\n options: ProtocolFeatureUnsupportedErrorOptions = {}\n ) {\n super(unsupportedFeatures, declaredFeatures, agentUrl, options);\n this.adcpError = {\n code: this.code,\n message: this.message,\n recovery: options.recovery ?? 'correctable',\n ...(options.field && { field: options.field }),\n ...(options.suggestion && { suggestion: options.suggestion }),\n ...(isRecord(this.details) && { details: this.details }),\n };\n }\n}\n\nexport function getClientPreflightAdcpError(error: unknown): ClientPreflightAdcpErrorInfo \| undefined {\n if (error instanceof ProtocolFeatureUnsupportedError) {\n return error.adcpError;\n }\n return undefined;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n return Boolean(value) && typeof value === 'object' && !Array.isArray(value);\n}\n\n/\n Error thrown when a response body exceeds the configured `maxResponseBytes`\n * cap on the transport. Surfaced when crawling untrusted agents (registries,\n * federated discovery layers) to prevent a hostile vendor from buffering a\n * large reply before schema validation runs.\n \n Recovery: `terminal` from the SDK's view — repeating the call against the\n * same agent will hit the same cap. The buyer's options are to widen the\n * cap (per-call `transport.maxResponseBytes`) when the agent's payload is\n * legitimately large, or to flag the agent as misbehaving.\n /\nexport class ResponseTooLargeError extends ADCPError {\n readonly code = 'RESPONSE_TOO_LARGE';\n\n constructor(\n public readonly limit: number,\n public readonly bytesRead: number,\n public readonly url: string,\n /\n The parsed value of the `Content-Length` response header when the cap\n * was tripped on the pre-check (before any body bytes were read). Undefined\n * when the response was streamed and exceeded the cap mid-flight, or when\n * the server omitted the header.\n /\n public readonly contentLengthHeader?: number\n ) {\n super(\n contentLengthHeader !== undefined\n ? `Response body declared ${contentLengthHeader} bytes, exceeds maxResponseBytes cap of ${limit} (${url})`\n : `Response body exceeded maxResponseBytes cap of ${limit} after reading ${bytesRead} bytes (${url})`\n );\n this.details = { limit, bytesRead, url, contentLengthHeader };\n }\n}\n\n/\n Error thrown when an `update_media_buy` request is rejected because the\n * action it maps to isn't currently allowed on the buy (AdCP 3.1, RFC #4480).\n \n Typed `details` payload follows `error-details/action-not-allowed.json`:\n * `attempted_action`, `reason`, optional `currently_available_actions[]`.\n \n Recovery branches on `reason`:\n * - `wrong_status`: transition the buy (or wait) to an allowed status.\n * - `not_supported_on_product`: terminal for this buy; pick a different\n * product for future buys that need the action.\n * - `not_supported_on_buy`: terminal; renegotiate buy terms.\n * - `mode_mismatch`: `recovery` is set to a typed hint indicating the\n * required flow (`createProposal`, `waitForApproval`, `reissueAsDirect`)\n * instead of a plain retry.\n /\nexport class ActionNotAllowedError extends ADCPError {\n readonly code = 'ACTION_NOT_ALLOWED';\n\n readonly attemptedAction: ActionNotAllowedErrorDetails['attempted_action'];\n readonly reason: ActionNotAllowedErrorDetails['reason'];\n readonly currentlyAvailableActions: ReadonlyArray<ActionNotAllowedAvailableAction>;\n readonly recovery?: ActionNotAllowedRecovery;\n\n constructor(detailsPayload: ActionNotAllowedErrorDetails, message?: string) {\n super(message ?? buildActionNotAllowedMessage(detailsPayload));\n this.attemptedAction = detailsPayload.attempted_action;\n this.reason = detailsPayload.reason;\n this.currentlyAvailableActions = detailsPayload.currently_available_actions ?? [];\n this.recovery = detailsPayload.reason === 'mode_mismatch' ? buildModeMismatchRecovery(detailsPayload) : undefined;\n this.details = detailsPayload;\n }\n}\n\n/\n Inline copy of the structured payload - duplicated here rather than\n * imported from `media-buy/types` to keep the errors module free of\n * cross-module imports (matches the convention used for the other typed\n * errors in this file).\n /\nexport interface ActionNotAllowedErrorDetails {\n attempted_action: ActionNotAllowedAttemptedAction;\n reason: ActionNotAllowedReasonValue;\n currently_available_actions?: ActionNotAllowedAvailableAction[];\n}\n\nexport type ActionNotAllowedReasonValue =\n \| 'wrong_status'\n \| 'not_supported_on_product'\n \| 'not_supported_on_buy'\n \| 'mode_mismatch';\n\nexport type ActionNotAllowedAttemptedAction = string;\n\nexport interface ActionNotAllowedAvailableAction {\n action: ActionNotAllowedAttemptedAction;\n mode: 'self_serve' \| 'conditional_self_serve' \| 'requires_proposal' \| 'requires_approval';\n sla?: unknown;\n terms_ref?: string;\n}\n\nexport type ActionNotAllowedRecovery =\n \| { kind: 'createProposal'; message: string }\n \| { kind: 'waitForApproval'; message: string }\n \| { kind: 'reissueAsDirect'; message: string };\n\nfunction buildActionNotAllowedMessage(details: ActionNotAllowedErrorDetails): string {\n const prefix = `update_media_buy rejected: \\`${details.attempted_action}\\` not allowed (${details.reason}).`;\n switch (details.reason) {\n case 'wrong_status':\n return `${prefix} transition the buy to an allowed status before retrying.`;\n case 'not_supported_on_product':\n return `${prefix} product does not declare this action; pick a different product for future buys needing it.`;\n case 'not_supported_on_buy':\n return `${prefix} buy was negotiated without this capability; renegotiate buy terms.`;\n case 'mode_mismatch':\n return `${prefix} mode shifted between preflight and dispatch; re-issue through the appropriate flow indicated by available_actions.`;\n }\n}\n\nfunction buildModeMismatchRecovery(details: ActionNotAllowedErrorDetails): ActionNotAllowedRecovery \| undefined {\n const match = details.currently_available_actions?.find(a => a.action === details.attempted_action);\n if (!match) return undefined;\n switch (match.mode) {\n case 'requires_proposal':\n return {\n kind: 'createProposal',\n message:\n `seller now resolves \\`${details.attempted_action}\\` as requires_proposal. ` +\n 'reissue via the proposal lifecycle (`create_proposal` / `finalize_proposal`).',\n };\n case 'requires_approval':\n return {\n kind: 'waitForApproval',\n message:\n `seller now resolves \\`${details.attempted_action}\\` as requires_approval. ` +\n 'expect an async approval callback rather than a direct response.',\n };\n case 'conditional_self_serve':\n return {\n kind: 'reissueAsDirect',\n message:\n `seller resolves \\`${details.attempted_action}\\` as conditional_self_serve: ` +\n 'small mutations clear automatically, larger ones queue. retry; expect a possible async escalation.',\n };\n case 'self_serve':\n return {\n kind: 'reissueAsDirect',\n message: `seller resolves \\`${details.attempted_action}\\` as self_serve. retry the same request.`,\n };\n }\n}\n\n/\n Reason the v3 guard refused a mutating dispatch.\n * - `version`: seller's `major_versions` does not include 3\n * - `idempotency`: seller reports v3 but omits the required\n * `adcp.idempotency.replay_ttl_seconds` declaration\n * - `synthetic`: @deprecated — kept in the union for downstream\n * consumers that pattern-match on the union literal, but the SDK no\n * longer emits it. Sellers whose capabilities are synthesized from\n * `tools/list` are routed through the v2 adapter with a one-time\n * warning; gate retry behavior on `SingleAgentClient.isSyntheticV2()`.\n /\nexport type VersionUnsupportedReason =\n \| 'version'\n \| 'idempotency'\n /* @deprecated SDK no longer emits this reason. See union JSDoc. /\n \| 'synthetic';\n\n/\n Error thrown when a mutating call would dispatch to a seller whose\n * capabilities cannot be corroborated as v3. Provides an explicit\n * pre-flight signal so callers don't silently mutate state on agents\n * that have not negotiated the expected major version.\n \n Agent URL is exposed on the instance (`agentUrl`) but omitted from the\n * default message to avoid leaking seller identity into shared log sinks.\n /\nexport class VersionUnsupportedError extends ADCPError {\n readonly code = 'VERSION_UNSUPPORTED';\n\n constructor(\n public readonly taskType: string,\n public readonly reason: VersionUnsupportedReason,\n public readonly actualVersion: 'v2' \| 'v3',\n public readonly agentUrl?: string\n ) {\n super(\n `Refusing to dispatch mutating task '${taskType}': ` +\n VersionUnsupportedError.explain(reason, actualVersion) +\n ` Pass allowV2: true or requireV3ForMutations: false to override.`\n );\n }\n\n private static explain(reason: VersionUnsupportedReason, actualVersion: 'v2' \| 'v3'): string {\n switch (reason) {\n case 'version':\n return `seller advertises major version '${actualVersion}' but v3 is required.`;\n case 'idempotency':\n return `seller reports v3 but omits adcp.idempotency.replay_ttl_seconds (required by spec).`;\n case 'synthetic':\n return `capabilities were synthesized from a tool list, v3 claim is unverifiable.`;\n }\n }\n}\n\n/\n Check if an error indicates a 401 Unauthorized response\n \n This helper centralizes the fragile logic of detecting 401 errors from\n * various sources (HTTP status codes, error messages, wrapped errors).\n * Used during endpoint discovery to detect authentication requirements.\n \n @param error - The error to check\n * @param got401Flag - Optional flag that was set by tracking HTTP responses\n * @returns true if the error appears to be a 401 authentication error\n /\nexport function is401Error(error: unknown, got401Flag = false): boolean {\n if (got401Flag) {\n return true;\n }\n\n if (!error) {\n return false;\n }\n\n // Check for status property (common in HTTP errors). MCP SDK's\n // `StreamableHTTPClientTransport` throws errors with the HTTP status on\n // `.code`, so we check that too.\n const errorObj = error as Record<string, unknown>;\n const status =\n (errorObj as { status?: number })?.status \|\|\n (errorObj as { response?: { status?: number } })?.response?.status \|\|\n (errorObj as { cause?: { status?: number } })?.cause?.status \|\|\n (errorObj as { code?: unknown })?.code;\n if (status === 401) {\n return true;\n }\n\n // Fall back to string matching in error message. Use word boundaries so\n // we don't misidentify things like \"product prod-401-xyz\" as an HTTP 401,\n // and require \"Unauthorized\" as a whole word rather than as a substring.\n const message = (errorObj as { message?: string })?.message \|\| '';\n return /\\b401\\b/.test(message) \|\| /\\bunauthorized\\b/i.test(message);\n}\n\n/\n Map a structured AdCP error (code + message) to a typed ADCPError subclass\n * when the code has a dedicated class. Returns `undefined` for codes that\n * don't have a typed mapping — callers should continue to use the untyped\n * `AdcpErrorInfo` for those.\n \n Pass the `idempotencyKey` the SDK sent so the constructed error carries it\n * for the caller's recovery logic. The server intentionally omits the key\n * from error bodies (it's a read-oracle), so the transport-layer caller is\n * the authoritative source.\n /\nexport function adcpErrorToTypedError(\n adcpError: { code: string; message?: string; details?: unknown },\n idempotencyKey?: string\n): ADCPError \| undefined {\n switch (adcpError.code) {\n case 'IDEMPOTENCY_CONFLICT':\n return new IdempotencyConflictError(idempotencyKey, adcpError.message);\n case 'IDEMPOTENCY_EXPIRED':\n return new IdempotencyExpiredError(idempotencyKey, adcpError.message);\n case 'ACTION_NOT_ALLOWED': {\n const parsed = parseActionNotAllowedDetails(adcpError.details);\n if (!parsed) return undefined;\n return new ActionNotAllowedError(parsed, adcpError.message);\n }\n default:\n return undefined;\n }\n}\n\nfunction parseActionNotAllowedDetails(raw: unknown): ActionNotAllowedErrorDetails \| undefined {\n if (!raw \|\| typeof raw !== 'object') return undefined;\n const obj = raw as Record<string, unknown>;\n const attempted = obj['attempted_action'];\n const reason = obj['reason'];\n if (typeof attempted !== 'string' \|\| typeof reason !== 'string') return undefined;\n if (!isActionNotAllowedReason(reason)) return undefined;\n\n const rawList = obj['currently_available_actions'];\n let currently: ActionNotAllowedAvailableAction[] \| undefined;\n if (Array.isArray(rawList)) {\n currently = [];\n for (const entry of rawList) {\n if (!entry \|\| typeof entry !== 'object') continue;\n const e = entry as Record<string, unknown>;\n const action = e['action'];\n const mode = e['mode'];\n if (typeof action !== 'string' \|\| typeof mode !== 'string') continue;\n if (!isActionMode(mode)) continue;\n const parsedEntry: ActionNotAllowedAvailableAction = { action, mode };\n if (typeof e['terms_ref'] === 'string') parsedEntry.terms_ref = e['terms_ref'];\n if (e['sla'] !== undefined) parsedEntry.sla = e['sla'];\n currently.push(parsedEntry);\n }\n }\n\n return {\n attempted_action: attempted,\n reason,\n currently_available_actions: currently,\n };\n}\n\nfunction isActionNotAllowedReason(value: string): value is ActionNotAllowedReasonValue {\n return (\n value === 'wrong_status' \|\|\n value === 'not_supported_on_product' \|\|\n value === 'not_supported_on_buy' \|\|\n value === 'mode_mismatch'\n );\n}\n\nfunction isActionMode(value: string): value is ActionNotAllowedAvailableAction['mode'] {\n return (\n value === 'self_serve' \|\|\n value === 'conditional_self_serve' \|\|\n value === 'requires_proposal' \|\|\n value === 'requires_approval'\n );\n}\n\n/\n Type guard to check if an error is an ADCP error\n /\nexport function isADCPError(error: unknown): error is ADCPError {\n return error instanceof ADCPError;\n}\n\n/\n Type guard to check if an error is a specific ADCP error type\n /\nexport function isErrorOfType<T extends ADCPError>(error: unknown, ErrorClass: new (...args: any[]) => T): error is T {\n return error instanceof ErrorClass;\n}\n\n/\n Utility to extract error information for logging/debugging\n */\nexport function extractErrorInfo(error: unknown): {\n message: string;\n code?: string;\n details?: unknown;\n stack?: string;\n} {\n if (isADCPError(error)) {\n return {\n message: error.message,\n code: error.code,\n details: error.details,\n stack: error.stack,\n };\n }\n\n if (error instanceof Error) {\n return {\n message: error.message,\n stack: error.stack,\n };\n }\n\n return {\n message: String(error),\n };\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../../../src/lib/errors/index.ts"],"sourcesContent":["// Custom error classes for ADCP client library\n\n/*\n Base class for all ADCP client errors\n /\nexport abstract class ADCPError extends Error {\n abstract readonly code: string;\n\n constructor(\n message: string,\n public details?: unknown\n ) {\n super(message);\n this.name = this.constructor.name;\n }\n}\n\n/\n Error thrown when a task times out\n /\nexport interface GovernanceOutcomeRecovery {\n checkId: string;\n outcome?: 'completed' \| 'failed';\n outcomeIdempotencyKey?: string;\n}\n\nexport class TaskTimeoutError extends ADCPError {\n readonly code = 'TASK_TIMEOUT';\n /* Retry-safety key for mutating requests that reached dispatch. /\n idempotency_key?: string;\n /* Camel-case compatibility alias for `idempotency_key`. /\n idempotencyKey?: string;\n /* Retry identity when the deadline expires during governance postflight. /\n governanceRecovery?: GovernanceOutcomeRecovery;\n\n constructor(\n public readonly taskId: string,\n public readonly timeout: number\n ) {\n super(`Task ${taskId} timed out after ${timeout}ms`);\n }\n}\n\n/\n Error thrown when maximum clarification attempts are exceeded\n /\nexport class MaxClarificationError extends ADCPError {\n readonly code = 'MAX_CLARIFICATIONS';\n\n constructor(\n public readonly taskId: string,\n public readonly maxAttempts: number\n ) {\n super(`Task ${taskId} exceeded maximum clarification attempts: ${maxAttempts}`);\n }\n}\n\n/\n Error thrown when a task is deferred to human\n * Contains the token needed to resume the task\n /\nexport class DeferredTaskError extends ADCPError {\n readonly code = 'TASK_DEFERRED';\n\n constructor(public readonly token: string) {\n super(`Task deferred with token: ${token}`);\n }\n}\n\n/\n Error thrown when a task is aborted\n /\nexport class TaskAbortedError extends ADCPError {\n readonly code = 'TASK_ABORTED';\n\n constructor(\n public readonly taskId: string,\n public readonly reason?: string\n ) {\n super(`Task ${taskId} aborted: ${reason \|\| 'No reason provided'}`);\n }\n}\n\n/\n Error thrown when an agent is not found\n /\nexport class AgentNotFoundError extends ADCPError {\n readonly code = 'AGENT_NOT_FOUND';\n\n constructor(\n public readonly agentId: string,\n public readonly availableAgents: string[]\n ) {\n super(`Agent '${agentId}' not found. Available agents: ${availableAgents.join(', ')}`);\n }\n}\n\n/\n Error thrown when an agent doesn't support a task\n /\nexport class UnsupportedTaskError extends ADCPError {\n readonly code = 'UNSUPPORTED_TASK';\n\n constructor(\n public readonly agentId: string,\n public readonly taskName: string,\n public readonly supportedTasks?: string[]\n ) {\n const tasksMsg = supportedTasks ? ` Supported tasks: ${supportedTasks.join(', ')}` : '';\n super(`Agent '${agentId}' does not support task '${taskName}'.${tasksMsg}`);\n }\n}\n\n/\n Error thrown when protocol communication fails\n /\nexport class ProtocolError extends ADCPError {\n readonly code = 'PROTOCOL_ERROR';\n\n constructor(\n public readonly protocol: 'mcp' \| 'a2a',\n message: string,\n public readonly originalError?: Error\n ) {\n super(`${protocol.toUpperCase()} protocol error: ${message}`);\n this.details = { originalError };\n }\n}\n\n/\n Error thrown when validation fails\n /\nexport class ValidationError extends ADCPError {\n readonly code = 'VALIDATION_ERROR';\n\n constructor(\n public readonly field: string,\n public readonly value: unknown,\n public readonly constraint: string\n ) {\n super(`Validation failed for field '${field}': ${constraint}`);\n this.details = { field, value, constraint };\n }\n}\n\n/\n Error thrown when input handler is missing but required\n /\nexport class MissingInputHandlerError extends ADCPError {\n readonly code = 'MISSING_INPUT_HANDLER';\n\n constructor(\n public readonly taskId: string,\n public readonly question: string\n ) {\n super(`Agent requested input but no handler provided. Task: ${taskId}, Question: ${question}`);\n }\n}\n\n/\n Error thrown when conversation context is invalid\n /\nexport class InvalidContextError extends ADCPError {\n readonly code = 'INVALID_CONTEXT';\n\n constructor(\n public readonly contextId: string,\n reason: string\n ) {\n super(`Invalid conversation context '${contextId}': ${reason}`);\n }\n}\n\n/\n Error thrown when configuration is invalid\n /\nexport class ConfigurationError extends ADCPError {\n readonly code = 'CONFIGURATION_ERROR';\n\n constructor(\n message: string,\n public readonly configField?: string\n ) {\n super(`Configuration error: ${message}`);\n this.details = { configField };\n }\n}\n\n/\n OAuth metadata for authentication guidance\n /\nexport interface OAuthMetadataInfo {\n /* URL of the authorization endpoint /\n authorization_endpoint: string;\n /* URL of the token endpoint /\n token_endpoint: string;\n /* URL of the dynamic client registration endpoint (optional) /\n registration_endpoint?: string;\n /* Issuer identifier /\n issuer?: string;\n}\n\n/\n Subset of the parsed `WWW-Authenticate` challenge surfaced on\n * {@link AuthenticationRequiredError}. Mirrors the public shape of\n * `WWWAuthenticateChallenge` from `@adcp/sdk/auth/oauth` without forcing the\n * errors module to depend on the auth subtree (the dependency would invert\n * the build graph).\n \n `scheme` is lowercased per RFC 9110 §11.6.1.\n /\nexport interface AuthChallengeInfo {\n scheme: string;\n realm?: string;\n scope?: string;\n error?: string;\n error_description?: string;\n}\n\n/\n Error thrown when authentication is required to access an MCP endpoint\n \n This error is thrown during MCP endpoint discovery when the server returns\n * a 401 Unauthorized response. The shape of the remediation depends on what\n * the 401 disclosed:\n \n - OAuth metadata (RFC 9728 PRM walk succeeded) → `oauthMetadata` set,\n * message points at the authorization endpoint.\n * - A `WWW-Authenticate` challenge with a non-Bearer scheme (e.g. Basic\n * behind an Apigee/Kong/AWS API GW gateway) → `challenge` set, message\n * names the scheme and the SDK / CLI surface that configures it.\n * - Plain 401 with no metadata → fallback \"provide auth_token\" message.\n \n Consumers branching on `error.challenge?.scheme === 'basic'` can route\n * straight to `auth: { type: 'basic', username, password }` instead of\n * retrying Bearer indefinitely.\n \n @example\n * ```typescript\n * try {\n * await client.getProducts({ brief: 'test' });\n * } catch (error) {\n * if (error instanceof AuthenticationRequiredError) {\n * if (error.challenge?.scheme === 'basic') {\n * // Gateway-fronted agent — configure HTTP Basic\n * reconnect({ auth: { type: 'basic', username, password } });\n * } else if (error.oauthMetadata) {\n * // Redirect user to OAuth flow\n * const authUrl = error.oauthMetadata.authorization_endpoint;\n * console.log(`Please authenticate at: ${authUrl}`);\n * } else {\n * console.log('Authentication required but no scheme metadata available');\n * }\n * }\n * }\n * ```\n /\nexport class AuthenticationRequiredError extends ADCPError {\n readonly code = 'AUTHENTICATION_REQUIRED';\n\n constructor(\n public readonly agentUrl: string,\n public readonly oauthMetadata?: OAuthMetadataInfo,\n message?: string,\n public readonly challenge?: AuthChallengeInfo\n ) {\n const defaultMessage = buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge);\n super(message \|\| defaultMessage);\n // `details` is serialized through error envelopes; surfacing the challenge\n // here lets non-CLI consumers (LLM agents, dashboards, programmatic\n // callers) branch on the scheme without instanceof-checking.\n this.details = { agentUrl, oauthMetadata, challenge };\n }\n\n /\n Check if OAuth authentication is available\n /\n get hasOAuth(): boolean {\n return this.oauthMetadata !== undefined;\n }\n\n /\n Get the authorization URL if OAuth is available\n /\n get authorizationUrl(): string \| undefined {\n return this.oauthMetadata?.authorization_endpoint;\n }\n\n /\n Lowercased scheme from the `WWW-Authenticate` challenge, when present.\n * `'basic'` is the common non-OAuth case — gateway-fronted agents speaking\n * RFC 7617.\n /\n get suggestedScheme(): string \| undefined {\n return this.challenge?.scheme;\n }\n}\n\n/\n Build the default error message. Branches on what the 401 disclosed:\n * - non-Bearer challenge (Basic, Digest, …) → scheme-specific remediation\n * - OAuth metadata → point at the authorization endpoint\n * - nothing → fallback \"provide auth_token\"\n \n The Basic branch names both the SDK shape (`createTestClient({ auth: …\n * type: 'basic' })`) and the CLI shape (`--auth user:pass --auth-scheme\n * basic`) so the same error envelope serves library and CLI consumers.\n /\nfunction buildAuthRequiredMessage(\n agentUrl: string,\n oauthMetadata: OAuthMetadataInfo \| undefined,\n challenge: AuthChallengeInfo \| undefined\n): string {\n if (challenge && challenge.scheme !== 'bearer') {\n if (challenge.scheme === 'basic') {\n return (\n `Authentication required for ${agentUrl}. Agent (or its fronting gateway) speaks HTTP Basic ` +\n `(RFC 7617). Configure via createTestClient({ auth: { type: 'basic', username, password } }) ` +\n `— or from the CLI, --auth <user:pass> --auth-scheme basic.`\n );\n }\n // Digest / Negotiate / NTLM / vendor schemes: we don't have first-class\n // support but the scheme name in the message saves a discovery round-trip.\n const realmHint = challenge.realm ? ` (realm: ${challenge.realm})` : '';\n return (\n `Authentication required for ${agentUrl}. Agent speaks ${challenge.scheme}${realmHint}, ` +\n `which is not natively supported by @adcp/sdk. Configure auth at the transport layer ` +\n `(custom fetch wrapper, reverse-proxy header injection) or contact the agent operator ` +\n `about Bearer / Basic / OAuth support.`\n );\n }\n if (oauthMetadata) {\n return `Authentication required for ${agentUrl}. OAuth available at: ${oauthMetadata.authorization_endpoint}`;\n }\n return `Authentication required for ${agentUrl}. No OAuth metadata available - provide auth_token in agent config.`;\n}\n\n/\n Error thrown when a request reused an `idempotency_key` with a different\n * canonical payload within the seller's replay window.\n \n Recovery: `correctable` — the caller either reused a key by mistake (mint\n * a fresh UUID v4 for the new request) or re-planned with a different payload\n * (an agent whose LLM re-ran and emitted a different request must treat that\n * as a new intent, not a retry).\n \n @example\n * ```typescript\n * try {\n * await client.createMediaBuy({...});\n * } catch (error) {\n * if (error instanceof IdempotencyConflictError) {\n * // Either the key was reused by mistake, or the agent re-planned with\n * // a different payload. Mint a fresh key and try again.\n * }\n * }\n * ```\n /\nexport class IdempotencyConflictError extends ADCPError {\n readonly code = 'IDEMPOTENCY_CONFLICT';\n\n // Exposed via the getter so `console.log(err)` and JSON.stringify don't\n // leak the key (it's a retry-pattern oracle within the seller's TTL).\n // Callers reading `err.idempotencyKey` get it normally.\n readonly idempotencyKey: string \| undefined;\n\n constructor(idempotencyKey: string \| undefined, message?: string) {\n super(\n message \|\|\n 'idempotency_key was used earlier with a different canonical payload. ' +\n 'Use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response.'\n );\n Object.defineProperty(this, 'idempotencyKey', {\n value: idempotencyKey,\n enumerable: false,\n writable: false,\n configurable: false,\n });\n }\n}\n\n/\n Error thrown when a request carries an `idempotency_key` that is past the\n * seller's declared replay window (plus clock-skew tolerance).\n \n Recovery: `correctable`. If the caller knows the prior call succeeded\n * (e.g., they saw the response once, then crashed), they SHOULD fall back\n * to a natural-key lookup (e.g., `get_media_buys` by\n * `context.internal_campaign_id`) rather than minting a new key — otherwise\n * the seller treats the new request as fresh and silently creates a duplicate.\n \n If the caller doesn't know whether the prior call succeeded, a fresh key\n * is safe.\n /\nexport class IdempotencyExpiredError extends ADCPError {\n readonly code = 'IDEMPOTENCY_EXPIRED';\n\n // Non-enumerable so `console.log(err)` / JSON.stringify don't leak it —\n // same reasoning as IdempotencyConflictError.idempotencyKey.\n readonly idempotencyKey: string \| undefined;\n\n constructor(idempotencyKey: string \| undefined, message?: string) {\n super(\n message \|\|\n \"idempotency_key is past the seller's replay window. \" +\n 'If you know the prior call succeeded, look up the resource by natural key before retrying. Otherwise, mint a fresh UUID v4.'\n );\n Object.defineProperty(this, 'idempotencyKey', {\n value: idempotencyKey,\n enumerable: false,\n writable: false,\n configurable: false,\n });\n }\n}\n\nexport interface FeatureUnsupportedErrorOptions {\n message?: string;\n details?: Record<string, unknown>;\n}\n\nexport type ClientPreflightAdcpErrorRecovery = 'transient' \| 'correctable' \| 'terminal';\n\n/\n Protocol-shaped error metadata attached to SDK-local preflight throws.\n * Mirrors the public `TaskResult.adcpError` fields without importing core\n * task types into the errors module.\n /\nexport interface ClientPreflightAdcpErrorInfo {\n code: string;\n message: string;\n recovery?: ClientPreflightAdcpErrorRecovery;\n field?: string;\n suggestion?: string;\n details?: Record<string, unknown>;\n}\n\nexport interface ProtocolFeatureUnsupportedErrorOptions extends FeatureUnsupportedErrorOptions {\n field?: string;\n suggestion?: string;\n recovery?: ClientPreflightAdcpErrorRecovery;\n}\n\nexport const SDK_ERROR_TO_PROTOCOL_ERROR_CODE = {\n FEATURE_UNSUPPORTED: 'UNSUPPORTED_FEATURE',\n} as const;\n\nexport function mapSdkErrorCodeToProtocolErrorCode(code: string): string \| undefined {\n return SDK_ERROR_TO_PROTOCOL_ERROR_CODE[code as keyof typeof SDK_ERROR_TO_PROTOCOL_ERROR_CODE];\n}\n\n/\n Error thrown when a required feature is not supported by the seller or by\n * the configured AdCP version.\n /\nexport class FeatureUnsupportedError extends ADCPError {\n readonly code: string = 'FEATURE_UNSUPPORTED';\n\n constructor(\n public readonly unsupportedFeatures: string[],\n public readonly declaredFeatures: string[],\n public readonly agentUrl?: string,\n options: FeatureUnsupportedErrorOptions = {}\n ) {\n const missing = unsupportedFeatures.join(', ');\n const declared = declaredFeatures.length > 0 ? declaredFeatures.join(', ') : '(none)';\n const urlPart = agentUrl ? ` at ${agentUrl}` : '';\n super(options.message ?? `Seller${urlPart} does not support: ${missing}\\n Declared features: ${declared}`);\n this.details = {\n unsupported_features: unsupportedFeatures,\n declared_features: declaredFeatures,\n ...(options.details ?? {}),\n };\n }\n}\n\n/\n Version-gate error for requests that use a protocol feature outside the\n * configured AdCP release. Kept as a FeatureUnsupportedError subclass so\n * existing catch sites keep working, while `code` carries the AdCP wire code\n * expected by probe/recovery layers.\n /\nexport class ProtocolFeatureUnsupportedError extends FeatureUnsupportedError {\n readonly code: string = 'UNSUPPORTED_FEATURE';\n\n readonly adcpError: ClientPreflightAdcpErrorInfo;\n\n constructor(\n unsupportedFeatures: string[],\n declaredFeatures: string[],\n agentUrl?: string,\n options: ProtocolFeatureUnsupportedErrorOptions = {}\n ) {\n super(unsupportedFeatures, declaredFeatures, agentUrl, options);\n this.adcpError = {\n code: this.code,\n message: this.message,\n recovery: options.recovery ?? 'correctable',\n ...(options.field && { field: options.field }),\n ...(options.suggestion && { suggestion: options.suggestion }),\n ...(isRecord(this.details) && { details: this.details }),\n };\n }\n}\n\nexport function getClientPreflightAdcpError(error: unknown): ClientPreflightAdcpErrorInfo \| undefined {\n if (error instanceof ProtocolFeatureUnsupportedError) {\n return error.adcpError;\n }\n return undefined;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n return Boolean(value) && typeof value === 'object' && !Array.isArray(value);\n}\n\n/\n Error thrown when a response body exceeds the configured `maxResponseBytes`\n * cap on the transport. Surfaced when crawling untrusted agents (registries,\n * federated discovery layers) to prevent a hostile vendor from buffering a\n * large reply before schema validation runs.\n \n Recovery: `terminal` from the SDK's view — repeating the call against the\n * same agent will hit the same cap. The buyer's options are to widen the\n * cap (per-call `transport.maxResponseBytes`) when the agent's payload is\n * legitimately large, or to flag the agent as misbehaving.\n /\nexport class ResponseTooLargeError extends ADCPError {\n readonly code = 'RESPONSE_TOO_LARGE';\n\n constructor(\n public readonly limit: number,\n public readonly bytesRead: number,\n public readonly url: string,\n /\n The parsed value of the `Content-Length` response header when the cap\n * was tripped on the pre-check (before any body bytes were read). Undefined\n * when the response was streamed and exceeded the cap mid-flight, or when\n * the server omitted the header.\n /\n public readonly contentLengthHeader?: number\n ) {\n super(\n contentLengthHeader !== undefined\n ? `Response body declared ${contentLengthHeader} bytes, exceeds maxResponseBytes cap of ${limit} (${url})`\n : `Response body exceeded maxResponseBytes cap of ${limit} after reading ${bytesRead} bytes (${url})`\n );\n this.details = { limit, bytesRead, url, contentLengthHeader };\n }\n}\n\n/\n Error thrown when an `update_media_buy` request is rejected because the\n * action it maps to isn't currently allowed on the buy (AdCP 3.1, RFC #4480).\n \n Typed `details` payload follows `error-details/action-not-allowed.json`:\n * `attempted_action`, `reason`, optional `currently_available_actions[]`.\n \n Recovery branches on `reason`:\n * - `wrong_status`: transition the buy (or wait) to an allowed status.\n * - `not_supported_on_product`: terminal for this buy; pick a different\n * product for future buys that need the action.\n * - `not_supported_on_buy`: terminal; renegotiate buy terms.\n * - `mode_mismatch`: `recovery` is set to a typed hint indicating the\n * required flow (`createProposal`, `waitForApproval`, `reissueAsDirect`)\n * instead of a plain retry.\n /\nexport class ActionNotAllowedError extends ADCPError {\n readonly code = 'ACTION_NOT_ALLOWED';\n\n readonly attemptedAction: ActionNotAllowedErrorDetails['attempted_action'];\n readonly reason: ActionNotAllowedErrorDetails['reason'];\n readonly currentlyAvailableActions: ReadonlyArray<ActionNotAllowedAvailableAction>;\n readonly recovery?: ActionNotAllowedRecovery;\n\n constructor(detailsPayload: ActionNotAllowedErrorDetails, message?: string) {\n super(message ?? buildActionNotAllowedMessage(detailsPayload));\n this.attemptedAction = detailsPayload.attempted_action;\n this.reason = detailsPayload.reason;\n this.currentlyAvailableActions = detailsPayload.currently_available_actions ?? [];\n this.recovery = detailsPayload.reason === 'mode_mismatch' ? buildModeMismatchRecovery(detailsPayload) : undefined;\n this.details = detailsPayload;\n }\n}\n\n/\n Inline copy of the structured payload - duplicated here rather than\n * imported from `media-buy/types` to keep the errors module free of\n * cross-module imports (matches the convention used for the other typed\n * errors in this file).\n /\nexport interface ActionNotAllowedErrorDetails {\n attempted_action: ActionNotAllowedAttemptedAction;\n reason: ActionNotAllowedReasonValue;\n currently_available_actions?: ActionNotAllowedAvailableAction[];\n}\n\nexport type ActionNotAllowedReasonValue =\n \| 'wrong_status'\n \| 'not_supported_on_product'\n \| 'not_supported_on_buy'\n \| 'mode_mismatch';\n\nexport type ActionNotAllowedAttemptedAction = string;\n\nexport interface ActionNotAllowedAvailableAction {\n action: ActionNotAllowedAttemptedAction;\n mode: 'self_serve' \| 'conditional_self_serve' \| 'requires_proposal' \| 'requires_approval';\n sla?: unknown;\n terms_ref?: string;\n}\n\nexport type ActionNotAllowedRecovery =\n \| { kind: 'createProposal'; message: string }\n \| { kind: 'waitForApproval'; message: string }\n \| { kind: 'reissueAsDirect'; message: string };\n\nfunction buildActionNotAllowedMessage(details: ActionNotAllowedErrorDetails): string {\n const prefix = `update_media_buy rejected: \\`${details.attempted_action}\\` not allowed (${details.reason}).`;\n switch (details.reason) {\n case 'wrong_status':\n return `${prefix} transition the buy to an allowed status before retrying.`;\n case 'not_supported_on_product':\n return `${prefix} product does not declare this action; pick a different product for future buys needing it.`;\n case 'not_supported_on_buy':\n return `${prefix} buy was negotiated without this capability; renegotiate buy terms.`;\n case 'mode_mismatch':\n return `${prefix} mode shifted between preflight and dispatch; re-issue through the appropriate flow indicated by available_actions.`;\n }\n}\n\nfunction buildModeMismatchRecovery(details: ActionNotAllowedErrorDetails): ActionNotAllowedRecovery \| undefined {\n const match = details.currently_available_actions?.find(a => a.action === details.attempted_action);\n if (!match) return undefined;\n switch (match.mode) {\n case 'requires_proposal':\n return {\n kind: 'createProposal',\n message:\n `seller now resolves \\`${details.attempted_action}\\` as requires_proposal. ` +\n 'reissue via the proposal lifecycle (`create_proposal` / `finalize_proposal`).',\n };\n case 'requires_approval':\n return {\n kind: 'waitForApproval',\n message:\n `seller now resolves \\`${details.attempted_action}\\` as requires_approval. ` +\n 'expect an async approval callback rather than a direct response.',\n };\n case 'conditional_self_serve':\n return {\n kind: 'reissueAsDirect',\n message:\n `seller resolves \\`${details.attempted_action}\\` as conditional_self_serve: ` +\n 'small mutations clear automatically, larger ones queue. retry; expect a possible async escalation.',\n };\n case 'self_serve':\n return {\n kind: 'reissueAsDirect',\n message: `seller resolves \\`${details.attempted_action}\\` as self_serve. retry the same request.`,\n };\n }\n}\n\n/\n Reason the v3 guard refused a mutating dispatch.\n * - `version`: seller's `major_versions` does not include 3\n * - `idempotency`: seller reports v3 but omits the required\n * `adcp.idempotency.replay_ttl_seconds` declaration\n * - `synthetic`: @deprecated — kept in the union for downstream\n * consumers that pattern-match on the union literal, but the SDK no\n * longer emits it. Sellers whose capabilities are synthesized from\n * `tools/list` are routed through the v2 adapter with a one-time\n * warning; gate retry behavior on `SingleAgentClient.isSyntheticV2()`.\n /\nexport type VersionUnsupportedReason =\n \| 'version'\n \| 'idempotency'\n /* @deprecated SDK no longer emits this reason. See union JSDoc. /\n \| 'synthetic';\n\n/\n Error thrown when a mutating call would dispatch to a seller whose\n * capabilities cannot be corroborated as v3. Provides an explicit\n * pre-flight signal so callers don't silently mutate state on agents\n * that have not negotiated the expected major version.\n \n Agent URL is exposed on the instance (`agentUrl`) but omitted from the\n * default message to avoid leaking seller identity into shared log sinks.\n /\nexport class VersionUnsupportedError extends ADCPError {\n readonly code = 'VERSION_UNSUPPORTED';\n\n constructor(\n public readonly taskType: string,\n public readonly reason: VersionUnsupportedReason,\n public readonly actualVersion: 'v2' \| 'v3',\n public readonly agentUrl?: string\n ) {\n super(\n `Refusing to dispatch mutating task '${taskType}': ` +\n VersionUnsupportedError.explain(reason, actualVersion) +\n ` Pass allowV2: true or requireV3ForMutations: false to override.`\n );\n }\n\n private static explain(reason: VersionUnsupportedReason, actualVersion: 'v2' \| 'v3'): string {\n switch (reason) {\n case 'version':\n return `seller advertises major version '${actualVersion}' but v3 is required.`;\n case 'idempotency':\n return `seller reports v3 but omits adcp.idempotency.replay_ttl_seconds (required by spec).`;\n case 'synthetic':\n return `capabilities were synthesized from a tool list, v3 claim is unverifiable.`;\n }\n }\n}\n\n/\n Check if an error indicates a 401 Unauthorized response\n \n This helper centralizes the fragile logic of detecting 401 errors from\n * various sources (HTTP status codes, error messages, wrapped errors).\n * Used during endpoint discovery to detect authentication requirements.\n \n @param error - The error to check\n * @param got401Flag - Optional flag that was set by tracking HTTP responses\n * @returns true if the error appears to be a 401 authentication error\n /\nexport function is401Error(error: unknown, got401Flag = false): boolean {\n if (got401Flag) {\n return true;\n }\n\n if (!error) {\n return false;\n }\n\n // Check for status property (common in HTTP errors). MCP SDK's\n // `StreamableHTTPClientTransport` throws errors with the HTTP status on\n // `.code`, so we check that too.\n const errorObj = error as Record<string, unknown>;\n const status =\n (errorObj as { status?: number })?.status \|\|\n (errorObj as { response?: { status?: number } })?.response?.status \|\|\n (errorObj as { cause?: { status?: number } })?.cause?.status \|\|\n (errorObj as { code?: unknown })?.code;\n if (status === 401) {\n return true;\n }\n\n // Fall back to string matching in error message. Use word boundaries so\n // we don't misidentify things like \"product prod-401-xyz\" as an HTTP 401,\n // and require \"Unauthorized\" as a whole word rather than as a substring.\n const message = (errorObj as { message?: string })?.message \|\| '';\n return /\\b401\\b/.test(message) \|\| /\\bunauthorized\\b/i.test(message);\n}\n\n/\n Map a structured AdCP error (code + message) to a typed ADCPError subclass\n * when the code has a dedicated class. Returns `undefined` for codes that\n * don't have a typed mapping — callers should continue to use the untyped\n * `AdcpErrorInfo` for those.\n \n Pass the `idempotencyKey` the SDK sent so the constructed error carries it\n * for the caller's recovery logic. The server intentionally omits the key\n * from error bodies (it's a read-oracle), so the transport-layer caller is\n * the authoritative source.\n /\nexport function adcpErrorToTypedError(\n adcpError: { code: string; message?: string; details?: unknown },\n idempotencyKey?: string\n): ADCPError \| undefined {\n switch (adcpError.code) {\n case 'IDEMPOTENCY_CONFLICT':\n return new IdempotencyConflictError(idempotencyKey, adcpError.message);\n case 'IDEMPOTENCY_EXPIRED':\n return new IdempotencyExpiredError(idempotencyKey, adcpError.message);\n case 'ACTION_NOT_ALLOWED': {\n const parsed = parseActionNotAllowedDetails(adcpError.details);\n if (!parsed) return undefined;\n return new ActionNotAllowedError(parsed, adcpError.message);\n }\n default:\n return undefined;\n }\n}\n\nfunction parseActionNotAllowedDetails(raw: unknown): ActionNotAllowedErrorDetails \| undefined {\n if (!raw \|\| typeof raw !== 'object') return undefined;\n const obj = raw as Record<string, unknown>;\n const attempted = obj['attempted_action'];\n const reason = obj['reason'];\n if (typeof attempted !== 'string' \|\| typeof reason !== 'string') return undefined;\n if (!isActionNotAllowedReason(reason)) return undefined;\n\n const rawList = obj['currently_available_actions'];\n let currently: ActionNotAllowedAvailableAction[] \| undefined;\n if (Array.isArray(rawList)) {\n currently = [];\n for (const entry of rawList) {\n if (!entry \|\| typeof entry !== 'object') continue;\n const e = entry as Record<string, unknown>;\n const action = e['action'];\n const mode = e['mode'];\n if (typeof action !== 'string' \|\| typeof mode !== 'string') continue;\n if (!isActionMode(mode)) continue;\n const parsedEntry: ActionNotAllowedAvailableAction = { action, mode };\n if (typeof e['terms_ref'] === 'string') parsedEntry.terms_ref = e['terms_ref'];\n if (e['sla'] !== undefined) parsedEntry.sla = e['sla'];\n currently.push(parsedEntry);\n }\n }\n\n return {\n attempted_action: attempted,\n reason,\n currently_available_actions: currently,\n };\n}\n\nfunction isActionNotAllowedReason(value: string): value is ActionNotAllowedReasonValue {\n return (\n value === 'wrong_status' \|\|\n value === 'not_supported_on_product' \|\|\n value === 'not_supported_on_buy' \|\|\n value === 'mode_mismatch'\n );\n}\n\nfunction isActionMode(value: string): value is ActionNotAllowedAvailableAction['mode'] {\n return (\n value === 'self_serve' \|\|\n value === 'conditional_self_serve' \|\|\n value === 'requires_proposal' \|\|\n value === 'requires_approval'\n );\n}\n\n/\n Type guard to check if an error is an ADCP error\n /\nexport function isADCPError(error: unknown): error is ADCPError {\n return error instanceof ADCPError;\n}\n\n/\n Type guard to check if an error is a specific ADCP error type\n /\nexport function isErrorOfType<T extends ADCPError>(error: unknown, ErrorClass: new (...args: any[]) => T): error is T {\n return error instanceof ErrorClass;\n}\n\n/\n Utility to extract error information for logging/debugging\n */\nexport function extractErrorInfo(error: unknown): {\n message: string;\n code?: string;\n details?: unknown;\n stack?: string;\n} {\n if (isADCPError(error)) {\n return {\n message: error.message,\n code: error.code,\n details: error.details,\n stack: error.stack,\n };\n }\n\n if (error instanceof Error) {\n return {\n message: error.message,\n stack: error.stack,\n };\n }\n\n return {\n message: String(error),\n };\n}\n"],"mappings":"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","names":[]}

package/dist/lib/net/ssrf-fetch.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"ssrf-fetch.d.ts","sourceRoot":"","sources":["../../../src/lib/net/ssrf-fetch.ts"],"names":[],"mappings":"AAyCA,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,oBAAoB,GACpB,0BAA0B,GAC1B,mBAAmB,GACnB,WAAW,GACX,wBAAwB,GACxB,iBAAiB,GACjB,oBAAoB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,eAAe,CAI5D,CAAC;AAEH;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEd,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;CAQ/G;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,6DAA6D;IAC7D,IAAI,EAAE,UAAU,CAAC;IACjB,6FAA6F;IAC7F,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC;IACpB,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,~~CAgLzG~~;~~AAED~~;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAWjG"}
1	+ {"version":3,"file":"ssrf-fetch.d.ts","sourceRoot":"","sources":["../../../src/lib/net/ssrf-fetch.ts"],"names":[],"mappings":"AAyCA,MAAM,MAAM,eAAe,GACvB,aAAa,GACb,oBAAoB,GACpB,0BAA0B,GAC1B,mBAAmB,GACnB,WAAW,GACX,wBAAwB,GACxB,iBAAiB,GACjB,oBAAoB,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,eAAe,CAI5D,CAAC;AAEH;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEd,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;CAQ/G;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,mEAAmE;IACnE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,6DAA6D;IAC7D,IAAI,EAAE,UAAU,CAAC;IACjB,6FAA6F;IAC7F,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC;IACpB,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CAoLzG;AAUD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAWjG"}

package/dist/lib/net/ssrf-fetch.js CHANGED Viewed

@@ -50,6 +50,7 @@ class SsrfRefusedError extends Error {
   }
 }
 async function ssrfSafeFetch(url, options = {}) {
+  throwIfSignalAborted(options.signal);
   const allowPrivateIp = options.allowPrivateIp === true;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
@@ -77,12 +78,14 @@ async function ssrfSafeFetch(url, options = {}) {
   try {
     addresses = await (0, import_promises.lookup)(hostname, { all: true });
   } catch (err) {
+    throwIfSignalAborted(options.signal);
     throw new SsrfRefusedError(
       "dns_lookup_failed",
       `DNS lookup failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`,
       { url, hostname }
     );
   }
+  throwIfSignalAborted(options.signal);
   if (addresses.length === 0) {
     throw new SsrfRefusedError("dns_empty", `DNS returned no addresses for ${hostname}`, {
       url,
@@ -129,6 +132,7 @@ async function ssrfSafeFetch(url, options = {}) {
   const ac = new AbortController();
   const onExternalAbort = () => ac.abort(options.signal?.reason);
   options.signal?.addEventListener("abort", onExternalAbort, { once: true });
+  if (options.signal?.aborted) onExternalAbort();
   const timer = setTimeout(() => ac.abort(new Error("ssrf-fetch: timeout")), timeoutMs);
   try {
     const res = options.trustedFetchFn ? await options.trustedFetchFn(url, {
@@ -199,6 +203,13 @@ async function ssrfSafeFetch(url, options = {}) {
     });
   }
 }
+function throwIfSignalAborted(signal) {
+  if (!signal?.aborted) return;
+  if (signal.reason instanceof Error) throw signal.reason;
+  const error = new Error(signal.reason == null ? "The operation was aborted" : String(signal.reason));
+  error.name = "AbortError";
+  throw error;
+}
 function decodeBodyAsJsonOrText(body, contentType) {
   if (body.byteLength === 0) return null;
   const text = Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString("utf8");

package/dist/lib/net/ssrf-fetch.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../../../src/lib/net/ssrf-fetch.ts"],"sourcesContent":["/*\n SSRF-safe HTTP fetch primitive.\n \n Used by compliance probes, storyboard runners, and (future) JWKS /\n * revocation-list resolvers — anywhere the library dispatches a request to a\n * URL that came from counterparty-controlled data and therefore might point at\n * the host's private network or a cloud metadata endpoint.\n \n Guarantees:\n * - Scheme: only `https:` by default; `http:` allowed under the dev-opt-in\n * `allowPrivateIp` flag. `file:`, `ftp:`, `data:`, etc. are always refused.\n * - DNS: resolves every A/AAAA record once, validates the full set, then\n * pins the outbound connection to the first validated address via an\n * undici `Agent` whose `connect.lookup` returns the pinned tuple.\n * Defeats DNS rebinding (attacker returns a public address to the guard\n * lookup and a private address to the connect-time lookup) and any other\n * TOCTOU gap between validation and connect.\n * - IMDS (`169.254.169.254`, `fe80::`) stays refused even under\n * `allowPrivateIp` — cloud metadata exfiltration is never a legitimate\n * dev-loop use case.\n * - Redirects are not followed (`redirect: 'manual'`). The 3xx response is\n * returned with `Location` populated so callers can inspect it, but they\n * MUST NOT re-dispatch to the `Location` URL themselves — that bypasses\n * every guard above. To follow a redirect safely, re-invoke\n * `ssrfSafeFetch` with the new URL so it runs through validation again.\n * - Response body is buffered up to `maxBodyBytes` (default 64 KiB) and\n * returned as raw bytes; the dispatcher is torn down after reading so\n * connection-reuse can't carry an attacker-controlled keepalive.\n \n Returns a fully-buffered result. Callers that need streaming or large bodies\n * should extend this primitive rather than bypass it.\n /\nimport { type LookupAddress, type LookupOptions } from 'dns';\nimport { lookup as dnsLookupAsync } from 'dns/promises';\nimport { Agent, fetch as undiciFetch } from 'undici';\nimport { isAlwaysBlocked, isPrivateIp } from './address-guards';\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_BODY_BYTES = 64 1024;\nconst ALLOWED_SCHEMES = new Set(['https:', 'http:']);\n\nexport type SsrfRefusedCode =\n \| 'invalid_url'\n \| 'scheme_not_allowed'\n \| 'non_https_without_opt_in'\n \| 'dns_lookup_failed'\n \| 'dns_empty'\n \| 'always_blocked_address'\n \| 'private_address'\n \| 'body_exceeds_limit';\n\n/*\n SSRF refusal codes that indicate runtime/network conditions rather than\n * policy refusal. Callers that want to fall back to a \"host unreachable\" or\n * \"treat as unknown\" path on these codes — rather than surfacing the\n * SsrfRefusedError to their own caller — can intersect against this set:\n \n ```ts\n * if (err instanceof SsrfRefusedError && SSRF_TRANSIENT_CODES.has(err.code)) {\n * // network condition, not a policy attack — treat as unreachable\n * } else if (err instanceof SsrfRefusedError) {\n * // policy refusal — must propagate; silently downgrading to \"unreachable\"\n * // reintroduces the catch-swallow class flagged in adcp-client#1618 review\n * throw err;\n * }\n * ```\n \n - `dns_lookup_failed`, `dns_empty`: name does not resolve. CLI fixtures\n * use `.example.invalid` to provoke these — preserving the runtime-error\n path matches pre-`ssrfSafeFetch` native-fetch behavior.\n * - `body_exceeds_limit`: response started OK (validated address, scheme,\n * etc.) but exceeded the caller's defensive cap. The host is real and\n * knows the URL; classifying as \"policy attack\" would be a misread.\n \n NOT in this set: `always_blocked_address`, `private_address`,\n * `scheme_not_allowed`, `non_https_without_opt_in`, `invalid_url`. Those\n * are policy refusals — silently downgrading them to \"unreachable\" or\n * \"suspect\" reintroduces the SSRF gap the gate was added to close.\n \n Added in adcp-client#1633.\n /\nexport const SSRF_TRANSIENT_CODES: ReadonlySet<SsrfRefusedCode> = new Set([\n 'dns_lookup_failed',\n 'dns_empty',\n 'body_exceeds_limit',\n]);\n\n/\n Thrown when the SSRF guard refuses a request before (or during) the fetch.\n * Network failures after the guard passes are not wrapped in this type —\n * callers that want to distinguish \"we refused this\" from \"the remote broke\"\n * can `instanceof SsrfRefusedError` the catch.\n /\nexport class SsrfRefusedError extends Error {\n readonly code: SsrfRefusedCode;\n readonly url: string;\n readonly hostname?: string;\n readonly address?: string;\n\n constructor(code: SsrfRefusedCode, message: string, meta: { url: string; hostname?: string; address?: string }) {\n super(message);\n this.name = 'SsrfRefusedError';\n this.code = code;\n this.url = meta.url;\n this.hostname = meta.hostname;\n this.address = meta.address;\n }\n}\n\nexport interface SsrfFetchOptions {\n method?: string;\n /* Lowercased keys preferred; values preserved verbatim. /\n headers?: Record<string, string>;\n body?: string \| Uint8Array;\n /* Allow `http://` and private/loopback targets. Default false. /\n allowPrivateIp?: boolean;\n /* Overall timeout including DNS + connect + body read. Default 10_000 ms. /\n timeoutMs?: number;\n /* Hard cap on response body bytes. Default 64 KiB. /\n maxBodyBytes?: number;\n /* Caller-provided abort signal, composed with the internal timeout. /\n signal?: AbortSignal;\n /\n Trusted scoped fetch implementation. URL validation and address\n * classification still run before invocation, but DNS pinning is delegated\n * to this implementation because custom fetchers do not accept undici\n * dispatchers. The caller MUST enforce DNS-rebinding protection itself.\n \n This deliberately explicit name prevents callers from mistaking a custom\n * transport for the internally DNS-pinned path.\n /\n trustedFetchFn?: typeof fetch;\n}\n\nexport interface SsrfFetchResult {\n url: string;\n status: number;\n /* Response headers, lowercased. /\n headers: Record<string, string>;\n /* Raw response body bytes (empty Uint8Array if no body). /\n body: Uint8Array;\n /* The validated IP address. The connection used it only when `connectionPinned` is true. /\n pinnedAddress: string;\n pinnedFamily: 4 \| 6;\n /* Whether the internal undici dispatcher pinned the connection to `pinnedAddress`. /\n connectionPinned: boolean;\n}\n\n/\n GET/POST/etc. a URL with SSRF guarding + DNS pinning. Throws\n * {@link SsrfRefusedError} when the guard refuses; other errors (network\n * timeouts, remote resets) propagate as the native fetch error.\n /\nexport async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}): Promise<SsrfFetchResult> {\n const allowPrivateIp = options.allowPrivateIp === true;\n const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n\n let parsed: URL;\n try {\n parsed = new URL(url);\n } catch {\n throw new SsrfRefusedError('invalid_url', `Invalid URL: ${url}`, { url });\n }\n\n // `URL.hostname` wraps IPv6 literals in brackets (`https://[::1]/` →\n // `[::1]`). `dns.lookup` and the address classifier both want the bare\n // form; strip brackets here so IPv6 localhost URLs work under\n // `allowPrivateIp` and so bracketed literals can't slip past classification\n // on a future Node release that tolerates them.\n const hostname = parsed.hostname.replace(/^\\[\|\\]$/g, '');\n\n if (!ALLOWED_SCHEMES.has(parsed.protocol)) {\n throw new SsrfRefusedError(\n 'scheme_not_allowed',\n `Refusing to fetch URL with unsupported scheme: ${parsed.protocol}`,\n { url, hostname }\n );\n }\n if (parsed.protocol !== 'https:' && !allowPrivateIp) {\n throw new SsrfRefusedError('non_https_without_opt_in', `Refusing to fetch non-HTTPS URL: ${url}`, {\n url,\n hostname,\n });\n }\n\n let addresses: { address: string; family: number }[];\n try {\n addresses = await dnsLookupAsync(hostname, { all: true });\n } catch (err) {\n throw new SsrfRefusedError(\n 'dns_lookup_failed',\n `DNS lookup failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`,\n { url, hostname }\n );\n }\n if (addresses.length === 0) {\n throw new SsrfRefusedError('dns_empty', `DNS returned no addresses for ${hostname}`, {\n url,\n hostname,\n });\n }\n // Error messages intentionally do NOT include the resolved IP — a\n // counterparty-supplied hostname that resolves into the caller's internal\n // address space would otherwise leak network topology into compliance\n // reports and log aggregators. The address is still available on the\n // thrown error's `.address` field for programmatic debugging.\n for (const a of addresses) {\n if (isAlwaysBlocked(a.address)) {\n throw new SsrfRefusedError(\n 'always_blocked_address',\n `Refusing to fetch: ${hostname} resolves to an always-blocked address (link-local or cloud metadata)`,\n { url, hostname, address: a.address }\n );\n }\n }\n if (!allowPrivateIp) {\n for (const a of addresses) {\n if (isPrivateIp(a.address)) {\n throw new SsrfRefusedError(\n 'private_address',\n `Refusing to fetch: ${hostname} resolves to a private/loopback address`,\n { url, hostname, address: a.address }\n );\n }\n }\n }\n\n const pinned = addresses[0]!;\n const pinnedFamily = pinned.family === 6 ? 6 : 4;\n const dispatcher = new Agent({\n connect: {\n // All addresses were validated above; pin the connect to the first. The\n // custom lookup also means undici won't re-resolve and pick up a rebind.\n // undici's Agent may call lookup with `{ all: true }` (it does for HTTPS\n // targets under Node 22+), which expects the array form of the callback.\n lookup: (\n _h: string,\n opts: LookupOptions \| undefined,\n cb: (err: NodeJS.ErrnoException \| null, address: string \| LookupAddress[], family?: number) => void\n ) => {\n if (opts?.all) {\n cb(null, [{ address: pinned.address, family: pinnedFamily }]);\n } else {\n cb(null, pinned.address, pinnedFamily);\n }\n },\n },\n });\n\n const ac = new AbortController();\n const onExternalAbort = () => ac.abort(options.signal?.reason);\n options.signal?.addEventListener('abort', onExternalAbort, { once: true });\n const timer = setTimeout(() => ac.abort(new Error('ssrf-fetch: timeout')), timeoutMs);\n\n try {\n const res = options.trustedFetchFn\n ? await options.trustedFetchFn(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n ...(options.body !== undefined && { body: options.body as BodyInit }),\n })\n : await undiciFetch(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n dispatcher,\n ...(options.body !== undefined && { body: options.body }),\n });\n\n const headers: Record<string, string> = {};\n res.headers.forEach((v, k) => {\n headers[k.toLowerCase()] = v;\n });\n\n const reader = res.body?.getReader();\n if (!reader) {\n return {\n url,\n status: res.status,\n headers,\n body: new Uint8Array(),\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n }\n\n const chunks: Uint8Array[] = [];\n let bytes = 0;\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n bytes += value.byteLength;\n if (bytes > maxBodyBytes) {\n await reader.cancel();\n throw new SsrfRefusedError('body_exceeds_limit', `Response body exceeded ${maxBodyBytes} bytes`, {\n url,\n hostname: parsed.hostname,\n address: pinned.address,\n });\n }\n chunks.push(value);\n }\n\n const buf = new Uint8Array(bytes);\n let offset = 0;\n for (const c of chunks) {\n buf.set(c, offset);\n offset += c.byteLength;\n }\n\n return {\n url,\n status: res.status,\n headers,\n body: buf,\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n } finally {\n clearTimeout(timer);\n options.signal?.removeEventListener('abort', onExternalAbort);\n await dispatcher.close().catch(() => {});\n }\n}\n\n/\n Decode a UTF-8 byte buffer as JSON when the content-type declares JSON, or\n * fall back to a UTF-8 string. Handy shared helper for probe-style call sites\n * that don't care about binary bodies.\n */\nexport function decodeBodyAsJsonOrText(body: Uint8Array, contentType: string \| undefined): unknown {\n if (body.byteLength === 0) return null;\n const text = Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString('utf8');\n if (contentType?.toLowerCase().includes('application/json')) {\n try {\n return JSON.parse(text);\n } catch {\n return text;\n }\n }\n return text;\n}\n"],"mappings":"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","names":["dnsLookupAsync","undiciFetch"]}
1	+ {"version":3,"sources":["../../../src/lib/net/ssrf-fetch.ts"],"sourcesContent":["/*\n SSRF-safe HTTP fetch primitive.\n \n Used by compliance probes, storyboard runners, and (future) JWKS /\n * revocation-list resolvers — anywhere the library dispatches a request to a\n * URL that came from counterparty-controlled data and therefore might point at\n * the host's private network or a cloud metadata endpoint.\n \n Guarantees:\n * - Scheme: only `https:` by default; `http:` allowed under the dev-opt-in\n * `allowPrivateIp` flag. `file:`, `ftp:`, `data:`, etc. are always refused.\n * - DNS: resolves every A/AAAA record once, validates the full set, then\n * pins the outbound connection to the first validated address via an\n * undici `Agent` whose `connect.lookup` returns the pinned tuple.\n * Defeats DNS rebinding (attacker returns a public address to the guard\n * lookup and a private address to the connect-time lookup) and any other\n * TOCTOU gap between validation and connect.\n * - IMDS (`169.254.169.254`, `fe80::`) stays refused even under\n * `allowPrivateIp` — cloud metadata exfiltration is never a legitimate\n * dev-loop use case.\n * - Redirects are not followed (`redirect: 'manual'`). The 3xx response is\n * returned with `Location` populated so callers can inspect it, but they\n * MUST NOT re-dispatch to the `Location` URL themselves — that bypasses\n * every guard above. To follow a redirect safely, re-invoke\n * `ssrfSafeFetch` with the new URL so it runs through validation again.\n * - Response body is buffered up to `maxBodyBytes` (default 64 KiB) and\n * returned as raw bytes; the dispatcher is torn down after reading so\n * connection-reuse can't carry an attacker-controlled keepalive.\n \n Returns a fully-buffered result. Callers that need streaming or large bodies\n * should extend this primitive rather than bypass it.\n /\nimport { type LookupAddress, type LookupOptions } from 'dns';\nimport { lookup as dnsLookupAsync } from 'dns/promises';\nimport { Agent, fetch as undiciFetch } from 'undici';\nimport { isAlwaysBlocked, isPrivateIp } from './address-guards';\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_BODY_BYTES = 64 1024;\nconst ALLOWED_SCHEMES = new Set(['https:', 'http:']);\n\nexport type SsrfRefusedCode =\n \| 'invalid_url'\n \| 'scheme_not_allowed'\n \| 'non_https_without_opt_in'\n \| 'dns_lookup_failed'\n \| 'dns_empty'\n \| 'always_blocked_address'\n \| 'private_address'\n \| 'body_exceeds_limit';\n\n/*\n SSRF refusal codes that indicate runtime/network conditions rather than\n * policy refusal. Callers that want to fall back to a \"host unreachable\" or\n * \"treat as unknown\" path on these codes — rather than surfacing the\n * SsrfRefusedError to their own caller — can intersect against this set:\n \n ```ts\n * if (err instanceof SsrfRefusedError && SSRF_TRANSIENT_CODES.has(err.code)) {\n * // network condition, not a policy attack — treat as unreachable\n * } else if (err instanceof SsrfRefusedError) {\n * // policy refusal — must propagate; silently downgrading to \"unreachable\"\n * // reintroduces the catch-swallow class flagged in adcp-client#1618 review\n * throw err;\n * }\n * ```\n \n - `dns_lookup_failed`, `dns_empty`: name does not resolve. CLI fixtures\n * use `.example.invalid` to provoke these — preserving the runtime-error\n path matches pre-`ssrfSafeFetch` native-fetch behavior.\n * - `body_exceeds_limit`: response started OK (validated address, scheme,\n * etc.) but exceeded the caller's defensive cap. The host is real and\n * knows the URL; classifying as \"policy attack\" would be a misread.\n \n NOT in this set: `always_blocked_address`, `private_address`,\n * `scheme_not_allowed`, `non_https_without_opt_in`, `invalid_url`. Those\n * are policy refusals — silently downgrading them to \"unreachable\" or\n * \"suspect\" reintroduces the SSRF gap the gate was added to close.\n \n Added in adcp-client#1633.\n /\nexport const SSRF_TRANSIENT_CODES: ReadonlySet<SsrfRefusedCode> = new Set([\n 'dns_lookup_failed',\n 'dns_empty',\n 'body_exceeds_limit',\n]);\n\n/\n Thrown when the SSRF guard refuses a request before (or during) the fetch.\n * Network failures after the guard passes are not wrapped in this type —\n * callers that want to distinguish \"we refused this\" from \"the remote broke\"\n * can `instanceof SsrfRefusedError` the catch.\n /\nexport class SsrfRefusedError extends Error {\n readonly code: SsrfRefusedCode;\n readonly url: string;\n readonly hostname?: string;\n readonly address?: string;\n\n constructor(code: SsrfRefusedCode, message: string, meta: { url: string; hostname?: string; address?: string }) {\n super(message);\n this.name = 'SsrfRefusedError';\n this.code = code;\n this.url = meta.url;\n this.hostname = meta.hostname;\n this.address = meta.address;\n }\n}\n\nexport interface SsrfFetchOptions {\n method?: string;\n /* Lowercased keys preferred; values preserved verbatim. /\n headers?: Record<string, string>;\n body?: string \| Uint8Array;\n /* Allow `http://` and private/loopback targets. Default false. /\n allowPrivateIp?: boolean;\n /* Overall timeout including DNS + connect + body read. Default 10_000 ms. /\n timeoutMs?: number;\n /* Hard cap on response body bytes. Default 64 KiB. /\n maxBodyBytes?: number;\n /* Caller-provided abort signal, composed with the internal timeout. /\n signal?: AbortSignal;\n /\n Trusted scoped fetch implementation. URL validation and address\n * classification still run before invocation, but DNS pinning is delegated\n * to this implementation because custom fetchers do not accept undici\n * dispatchers. The caller MUST enforce DNS-rebinding protection itself.\n \n This deliberately explicit name prevents callers from mistaking a custom\n * transport for the internally DNS-pinned path.\n /\n trustedFetchFn?: typeof fetch;\n}\n\nexport interface SsrfFetchResult {\n url: string;\n status: number;\n /* Response headers, lowercased. /\n headers: Record<string, string>;\n /* Raw response body bytes (empty Uint8Array if no body). /\n body: Uint8Array;\n /* The validated IP address. The connection used it only when `connectionPinned` is true. /\n pinnedAddress: string;\n pinnedFamily: 4 \| 6;\n /* Whether the internal undici dispatcher pinned the connection to `pinnedAddress`. /\n connectionPinned: boolean;\n}\n\n/\n GET/POST/etc. a URL with SSRF guarding + DNS pinning. Throws\n * {@link SsrfRefusedError} when the guard refuses; other errors (network\n * timeouts, remote resets) propagate as the native fetch error.\n /\nexport async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}): Promise<SsrfFetchResult> {\n throwIfSignalAborted(options.signal);\n const allowPrivateIp = options.allowPrivateIp === true;\n const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n\n let parsed: URL;\n try {\n parsed = new URL(url);\n } catch {\n throw new SsrfRefusedError('invalid_url', `Invalid URL: ${url}`, { url });\n }\n\n // `URL.hostname` wraps IPv6 literals in brackets (`https://[::1]/` →\n // `[::1]`). `dns.lookup` and the address classifier both want the bare\n // form; strip brackets here so IPv6 localhost URLs work under\n // `allowPrivateIp` and so bracketed literals can't slip past classification\n // on a future Node release that tolerates them.\n const hostname = parsed.hostname.replace(/^\\[\|\\]$/g, '');\n\n if (!ALLOWED_SCHEMES.has(parsed.protocol)) {\n throw new SsrfRefusedError(\n 'scheme_not_allowed',\n `Refusing to fetch URL with unsupported scheme: ${parsed.protocol}`,\n { url, hostname }\n );\n }\n if (parsed.protocol !== 'https:' && !allowPrivateIp) {\n throw new SsrfRefusedError('non_https_without_opt_in', `Refusing to fetch non-HTTPS URL: ${url}`, {\n url,\n hostname,\n });\n }\n\n let addresses: { address: string; family: number }[];\n try {\n addresses = await dnsLookupAsync(hostname, { all: true });\n } catch (err) {\n throwIfSignalAborted(options.signal);\n throw new SsrfRefusedError(\n 'dns_lookup_failed',\n `DNS lookup failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`,\n { url, hostname }\n );\n }\n throwIfSignalAborted(options.signal);\n if (addresses.length === 0) {\n throw new SsrfRefusedError('dns_empty', `DNS returned no addresses for ${hostname}`, {\n url,\n hostname,\n });\n }\n // Error messages intentionally do NOT include the resolved IP — a\n // counterparty-supplied hostname that resolves into the caller's internal\n // address space would otherwise leak network topology into compliance\n // reports and log aggregators. The address is still available on the\n // thrown error's `.address` field for programmatic debugging.\n for (const a of addresses) {\n if (isAlwaysBlocked(a.address)) {\n throw new SsrfRefusedError(\n 'always_blocked_address',\n `Refusing to fetch: ${hostname} resolves to an always-blocked address (link-local or cloud metadata)`,\n { url, hostname, address: a.address }\n );\n }\n }\n if (!allowPrivateIp) {\n for (const a of addresses) {\n if (isPrivateIp(a.address)) {\n throw new SsrfRefusedError(\n 'private_address',\n `Refusing to fetch: ${hostname} resolves to a private/loopback address`,\n { url, hostname, address: a.address }\n );\n }\n }\n }\n\n const pinned = addresses[0]!;\n const pinnedFamily = pinned.family === 6 ? 6 : 4;\n const dispatcher = new Agent({\n connect: {\n // All addresses were validated above; pin the connect to the first. The\n // custom lookup also means undici won't re-resolve and pick up a rebind.\n // undici's Agent may call lookup with `{ all: true }` (it does for HTTPS\n // targets under Node 22+), which expects the array form of the callback.\n lookup: (\n _h: string,\n opts: LookupOptions \| undefined,\n cb: (err: NodeJS.ErrnoException \| null, address: string \| LookupAddress[], family?: number) => void\n ) => {\n if (opts?.all) {\n cb(null, [{ address: pinned.address, family: pinnedFamily }]);\n } else {\n cb(null, pinned.address, pinnedFamily);\n }\n },\n },\n });\n\n const ac = new AbortController();\n const onExternalAbort = () => ac.abort(options.signal?.reason);\n options.signal?.addEventListener('abort', onExternalAbort, { once: true });\n if (options.signal?.aborted) onExternalAbort();\n const timer = setTimeout(() => ac.abort(new Error('ssrf-fetch: timeout')), timeoutMs);\n\n try {\n const res = options.trustedFetchFn\n ? await options.trustedFetchFn(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n ...(options.body !== undefined && { body: options.body as BodyInit }),\n })\n : await undiciFetch(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n dispatcher,\n ...(options.body !== undefined && { body: options.body }),\n });\n\n const headers: Record<string, string> = {};\n res.headers.forEach((v, k) => {\n headers[k.toLowerCase()] = v;\n });\n\n const reader = res.body?.getReader();\n if (!reader) {\n return {\n url,\n status: res.status,\n headers,\n body: new Uint8Array(),\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n }\n\n const chunks: Uint8Array[] = [];\n let bytes = 0;\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n bytes += value.byteLength;\n if (bytes > maxBodyBytes) {\n await reader.cancel();\n throw new SsrfRefusedError('body_exceeds_limit', `Response body exceeded ${maxBodyBytes} bytes`, {\n url,\n hostname: parsed.hostname,\n address: pinned.address,\n });\n }\n chunks.push(value);\n }\n\n const buf = new Uint8Array(bytes);\n let offset = 0;\n for (const c of chunks) {\n buf.set(c, offset);\n offset += c.byteLength;\n }\n\n return {\n url,\n status: res.status,\n headers,\n body: buf,\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n } finally {\n clearTimeout(timer);\n options.signal?.removeEventListener('abort', onExternalAbort);\n await dispatcher.close().catch(() => {});\n }\n}\n\nfunction throwIfSignalAborted(signal?: AbortSignal): void {\n if (!signal?.aborted) return;\n if (signal.reason instanceof Error) throw signal.reason;\n const error = new Error(signal.reason == null ? 'The operation was aborted' : String(signal.reason));\n error.name = 'AbortError';\n throw error;\n}\n\n/\n Decode a UTF-8 byte buffer as JSON when the content-type declares JSON, or\n * fall back to a UTF-8 string. Handy shared helper for probe-style call sites\n * that don't care about binary bodies.\n */\nexport function decodeBodyAsJsonOrText(body: Uint8Array, contentType: string \| undefined): unknown {\n if (body.byteLength === 0) return null;\n const text = Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString('utf8');\n if (contentType?.toLowerCase().includes('application/json')) {\n try {\n return JSON.parse(text);\n } catch {\n return text;\n }\n }\n return text;\n}\n"],"mappings":"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","names":["dnsLookupAsync","undiciFetch"]}

package/dist/lib/net/ssrf-fetch.mjs CHANGED Viewed

@@ -24,6 +24,7 @@ class SsrfRefusedError extends Error {
   }
 }
 async function ssrfSafeFetch(url, options = {}) {
+  throwIfSignalAborted(options.signal);
   const allowPrivateIp = options.allowPrivateIp === true;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
@@ -51,12 +52,14 @@ async function ssrfSafeFetch(url, options = {}) {
   try {
     addresses = await dnsLookupAsync(hostname, { all: true });
   } catch (err) {
+    throwIfSignalAborted(options.signal);
     throw new SsrfRefusedError(
       "dns_lookup_failed",
       `DNS lookup failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`,
       { url, hostname }
     );
   }
+  throwIfSignalAborted(options.signal);
   if (addresses.length === 0) {
     throw new SsrfRefusedError("dns_empty", `DNS returned no addresses for ${hostname}`, {
       url,
@@ -103,6 +106,7 @@ async function ssrfSafeFetch(url, options = {}) {
   const ac = new AbortController();
   const onExternalAbort = () => ac.abort(options.signal?.reason);
   options.signal?.addEventListener("abort", onExternalAbort, { once: true });
+  if (options.signal?.aborted) onExternalAbort();
   const timer = setTimeout(() => ac.abort(new Error("ssrf-fetch: timeout")), timeoutMs);
   try {
     const res = options.trustedFetchFn ? await options.trustedFetchFn(url, {
@@ -173,6 +177,13 @@ async function ssrfSafeFetch(url, options = {}) {
     });
   }
 }
+function throwIfSignalAborted(signal) {
+  if (!signal?.aborted) return;
+  if (signal.reason instanceof Error) throw signal.reason;
+  const error = new Error(signal.reason == null ? "The operation was aborted" : String(signal.reason));
+  error.name = "AbortError";
+  throw error;
+}
 function decodeBodyAsJsonOrText(body, contentType) {
   if (body.byteLength === 0) return null;
   const text = Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString("utf8");

package/dist/lib/net/ssrf-fetch.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../../../src/lib/net/ssrf-fetch.ts"],"sourcesContent":["/*\n SSRF-safe HTTP fetch primitive.\n \n Used by compliance probes, storyboard runners, and (future) JWKS /\n * revocation-list resolvers — anywhere the library dispatches a request to a\n * URL that came from counterparty-controlled data and therefore might point at\n * the host's private network or a cloud metadata endpoint.\n \n Guarantees:\n * - Scheme: only `https:` by default; `http:` allowed under the dev-opt-in\n * `allowPrivateIp` flag. `file:`, `ftp:`, `data:`, etc. are always refused.\n * - DNS: resolves every A/AAAA record once, validates the full set, then\n * pins the outbound connection to the first validated address via an\n * undici `Agent` whose `connect.lookup` returns the pinned tuple.\n * Defeats DNS rebinding (attacker returns a public address to the guard\n * lookup and a private address to the connect-time lookup) and any other\n * TOCTOU gap between validation and connect.\n * - IMDS (`169.254.169.254`, `fe80::`) stays refused even under\n * `allowPrivateIp` — cloud metadata exfiltration is never a legitimate\n * dev-loop use case.\n * - Redirects are not followed (`redirect: 'manual'`). The 3xx response is\n * returned with `Location` populated so callers can inspect it, but they\n * MUST NOT re-dispatch to the `Location` URL themselves — that bypasses\n * every guard above. To follow a redirect safely, re-invoke\n * `ssrfSafeFetch` with the new URL so it runs through validation again.\n * - Response body is buffered up to `maxBodyBytes` (default 64 KiB) and\n * returned as raw bytes; the dispatcher is torn down after reading so\n * connection-reuse can't carry an attacker-controlled keepalive.\n \n Returns a fully-buffered result. Callers that need streaming or large bodies\n * should extend this primitive rather than bypass it.\n /\nimport { type LookupAddress, type LookupOptions } from 'dns';\nimport { lookup as dnsLookupAsync } from 'dns/promises';\nimport { Agent, fetch as undiciFetch } from 'undici';\nimport { isAlwaysBlocked, isPrivateIp } from './address-guards';\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_BODY_BYTES = 64 1024;\nconst ALLOWED_SCHEMES = new Set(['https:', 'http:']);\n\nexport type SsrfRefusedCode =\n \| 'invalid_url'\n \| 'scheme_not_allowed'\n \| 'non_https_without_opt_in'\n \| 'dns_lookup_failed'\n \| 'dns_empty'\n \| 'always_blocked_address'\n \| 'private_address'\n \| 'body_exceeds_limit';\n\n/*\n SSRF refusal codes that indicate runtime/network conditions rather than\n * policy refusal. Callers that want to fall back to a \"host unreachable\" or\n * \"treat as unknown\" path on these codes — rather than surfacing the\n * SsrfRefusedError to their own caller — can intersect against this set:\n \n ```ts\n * if (err instanceof SsrfRefusedError && SSRF_TRANSIENT_CODES.has(err.code)) {\n * // network condition, not a policy attack — treat as unreachable\n * } else if (err instanceof SsrfRefusedError) {\n * // policy refusal — must propagate; silently downgrading to \"unreachable\"\n * // reintroduces the catch-swallow class flagged in adcp-client#1618 review\n * throw err;\n * }\n * ```\n \n - `dns_lookup_failed`, `dns_empty`: name does not resolve. CLI fixtures\n * use `.example.invalid` to provoke these — preserving the runtime-error\n path matches pre-`ssrfSafeFetch` native-fetch behavior.\n * - `body_exceeds_limit`: response started OK (validated address, scheme,\n * etc.) but exceeded the caller's defensive cap. The host is real and\n * knows the URL; classifying as \"policy attack\" would be a misread.\n \n NOT in this set: `always_blocked_address`, `private_address`,\n * `scheme_not_allowed`, `non_https_without_opt_in`, `invalid_url`. Those\n * are policy refusals — silently downgrading them to \"unreachable\" or\n * \"suspect\" reintroduces the SSRF gap the gate was added to close.\n \n Added in adcp-client#1633.\n /\nexport const SSRF_TRANSIENT_CODES: ReadonlySet<SsrfRefusedCode> = new Set([\n 'dns_lookup_failed',\n 'dns_empty',\n 'body_exceeds_limit',\n]);\n\n/\n Thrown when the SSRF guard refuses a request before (or during) the fetch.\n * Network failures after the guard passes are not wrapped in this type —\n * callers that want to distinguish \"we refused this\" from \"the remote broke\"\n * can `instanceof SsrfRefusedError` the catch.\n /\nexport class SsrfRefusedError extends Error {\n readonly code: SsrfRefusedCode;\n readonly url: string;\n readonly hostname?: string;\n readonly address?: string;\n\n constructor(code: SsrfRefusedCode, message: string, meta: { url: string; hostname?: string; address?: string }) {\n super(message);\n this.name = 'SsrfRefusedError';\n this.code = code;\n this.url = meta.url;\n this.hostname = meta.hostname;\n this.address = meta.address;\n }\n}\n\nexport interface SsrfFetchOptions {\n method?: string;\n /* Lowercased keys preferred; values preserved verbatim. /\n headers?: Record<string, string>;\n body?: string \| Uint8Array;\n /* Allow `http://` and private/loopback targets. Default false. /\n allowPrivateIp?: boolean;\n /* Overall timeout including DNS + connect + body read. Default 10_000 ms. /\n timeoutMs?: number;\n /* Hard cap on response body bytes. Default 64 KiB. /\n maxBodyBytes?: number;\n /* Caller-provided abort signal, composed with the internal timeout. /\n signal?: AbortSignal;\n /\n Trusted scoped fetch implementation. URL validation and address\n * classification still run before invocation, but DNS pinning is delegated\n * to this implementation because custom fetchers do not accept undici\n * dispatchers. The caller MUST enforce DNS-rebinding protection itself.\n \n This deliberately explicit name prevents callers from mistaking a custom\n * transport for the internally DNS-pinned path.\n /\n trustedFetchFn?: typeof fetch;\n}\n\nexport interface SsrfFetchResult {\n url: string;\n status: number;\n /* Response headers, lowercased. /\n headers: Record<string, string>;\n /* Raw response body bytes (empty Uint8Array if no body). /\n body: Uint8Array;\n /* The validated IP address. The connection used it only when `connectionPinned` is true. /\n pinnedAddress: string;\n pinnedFamily: 4 \| 6;\n /* Whether the internal undici dispatcher pinned the connection to `pinnedAddress`. /\n connectionPinned: boolean;\n}\n\n/\n GET/POST/etc. a URL with SSRF guarding + DNS pinning. Throws\n * {@link SsrfRefusedError} when the guard refuses; other errors (network\n * timeouts, remote resets) propagate as the native fetch error.\n /\nexport async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}): Promise<SsrfFetchResult> {\n const allowPrivateIp = options.allowPrivateIp === true;\n const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n\n let parsed: URL;\n try {\n parsed = new URL(url);\n } catch {\n throw new SsrfRefusedError('invalid_url', `Invalid URL: ${url}`, { url });\n }\n\n // `URL.hostname` wraps IPv6 literals in brackets (`https://[::1]/` →\n // `[::1]`). `dns.lookup` and the address classifier both want the bare\n // form; strip brackets here so IPv6 localhost URLs work under\n // `allowPrivateIp` and so bracketed literals can't slip past classification\n // on a future Node release that tolerates them.\n const hostname = parsed.hostname.replace(/^\\[\|\\]$/g, '');\n\n if (!ALLOWED_SCHEMES.has(parsed.protocol)) {\n throw new SsrfRefusedError(\n 'scheme_not_allowed',\n `Refusing to fetch URL with unsupported scheme: ${parsed.protocol}`,\n { url, hostname }\n );\n }\n if (parsed.protocol !== 'https:' && !allowPrivateIp) {\n throw new SsrfRefusedError('non_https_without_opt_in', `Refusing to fetch non-HTTPS URL: ${url}`, {\n url,\n hostname,\n });\n }\n\n let addresses: { address: string; family: number }[];\n try {\n addresses = await dnsLookupAsync(hostname, { all: true });\n } catch (err) {\n throw new SsrfRefusedError(\n 'dns_lookup_failed',\n `DNS lookup failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`,\n { url, hostname }\n );\n }\n if (addresses.length === 0) {\n throw new SsrfRefusedError('dns_empty', `DNS returned no addresses for ${hostname}`, {\n url,\n hostname,\n });\n }\n // Error messages intentionally do NOT include the resolved IP — a\n // counterparty-supplied hostname that resolves into the caller's internal\n // address space would otherwise leak network topology into compliance\n // reports and log aggregators. The address is still available on the\n // thrown error's `.address` field for programmatic debugging.\n for (const a of addresses) {\n if (isAlwaysBlocked(a.address)) {\n throw new SsrfRefusedError(\n 'always_blocked_address',\n `Refusing to fetch: ${hostname} resolves to an always-blocked address (link-local or cloud metadata)`,\n { url, hostname, address: a.address }\n );\n }\n }\n if (!allowPrivateIp) {\n for (const a of addresses) {\n if (isPrivateIp(a.address)) {\n throw new SsrfRefusedError(\n 'private_address',\n `Refusing to fetch: ${hostname} resolves to a private/loopback address`,\n { url, hostname, address: a.address }\n );\n }\n }\n }\n\n const pinned = addresses[0]!;\n const pinnedFamily = pinned.family === 6 ? 6 : 4;\n const dispatcher = new Agent({\n connect: {\n // All addresses were validated above; pin the connect to the first. The\n // custom lookup also means undici won't re-resolve and pick up a rebind.\n // undici's Agent may call lookup with `{ all: true }` (it does for HTTPS\n // targets under Node 22+), which expects the array form of the callback.\n lookup: (\n _h: string,\n opts: LookupOptions \| undefined,\n cb: (err: NodeJS.ErrnoException \| null, address: string \| LookupAddress[], family?: number) => void\n ) => {\n if (opts?.all) {\n cb(null, [{ address: pinned.address, family: pinnedFamily }]);\n } else {\n cb(null, pinned.address, pinnedFamily);\n }\n },\n },\n });\n\n const ac = new AbortController();\n const onExternalAbort = () => ac.abort(options.signal?.reason);\n options.signal?.addEventListener('abort', onExternalAbort, { once: true });\n const timer = setTimeout(() => ac.abort(new Error('ssrf-fetch: timeout')), timeoutMs);\n\n try {\n const res = options.trustedFetchFn\n ? await options.trustedFetchFn(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n ...(options.body !== undefined && { body: options.body as BodyInit }),\n })\n : await undiciFetch(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n dispatcher,\n ...(options.body !== undefined && { body: options.body }),\n });\n\n const headers: Record<string, string> = {};\n res.headers.forEach((v, k) => {\n headers[k.toLowerCase()] = v;\n });\n\n const reader = res.body?.getReader();\n if (!reader) {\n return {\n url,\n status: res.status,\n headers,\n body: new Uint8Array(),\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n }\n\n const chunks: Uint8Array[] = [];\n let bytes = 0;\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n bytes += value.byteLength;\n if (bytes > maxBodyBytes) {\n await reader.cancel();\n throw new SsrfRefusedError('body_exceeds_limit', `Response body exceeded ${maxBodyBytes} bytes`, {\n url,\n hostname: parsed.hostname,\n address: pinned.address,\n });\n }\n chunks.push(value);\n }\n\n const buf = new Uint8Array(bytes);\n let offset = 0;\n for (const c of chunks) {\n buf.set(c, offset);\n offset += c.byteLength;\n }\n\n return {\n url,\n status: res.status,\n headers,\n body: buf,\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n } finally {\n clearTimeout(timer);\n options.signal?.removeEventListener('abort', onExternalAbort);\n await dispatcher.close().catch(() => {});\n }\n}\n\n/\n Decode a UTF-8 byte buffer as JSON when the content-type declares JSON, or\n * fall back to a UTF-8 string. Handy shared helper for probe-style call sites\n * that don't care about binary bodies.\n */\nexport function decodeBodyAsJsonOrText(body: Uint8Array, contentType: string \| undefined): unknown {\n if (body.byteLength === 0) return null;\n const text = Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString('utf8');\n if (contentType?.toLowerCase().includes('application/json')) {\n try {\n return JSON.parse(text);\n } catch {\n return text;\n }\n }\n return text;\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"sources":["../../../src/lib/net/ssrf-fetch.ts"],"sourcesContent":["/*\n SSRF-safe HTTP fetch primitive.\n \n Used by compliance probes, storyboard runners, and (future) JWKS /\n * revocation-list resolvers — anywhere the library dispatches a request to a\n * URL that came from counterparty-controlled data and therefore might point at\n * the host's private network or a cloud metadata endpoint.\n \n Guarantees:\n * - Scheme: only `https:` by default; `http:` allowed under the dev-opt-in\n * `allowPrivateIp` flag. `file:`, `ftp:`, `data:`, etc. are always refused.\n * - DNS: resolves every A/AAAA record once, validates the full set, then\n * pins the outbound connection to the first validated address via an\n * undici `Agent` whose `connect.lookup` returns the pinned tuple.\n * Defeats DNS rebinding (attacker returns a public address to the guard\n * lookup and a private address to the connect-time lookup) and any other\n * TOCTOU gap between validation and connect.\n * - IMDS (`169.254.169.254`, `fe80::`) stays refused even under\n * `allowPrivateIp` — cloud metadata exfiltration is never a legitimate\n * dev-loop use case.\n * - Redirects are not followed (`redirect: 'manual'`). The 3xx response is\n * returned with `Location` populated so callers can inspect it, but they\n * MUST NOT re-dispatch to the `Location` URL themselves — that bypasses\n * every guard above. To follow a redirect safely, re-invoke\n * `ssrfSafeFetch` with the new URL so it runs through validation again.\n * - Response body is buffered up to `maxBodyBytes` (default 64 KiB) and\n * returned as raw bytes; the dispatcher is torn down after reading so\n * connection-reuse can't carry an attacker-controlled keepalive.\n \n Returns a fully-buffered result. Callers that need streaming or large bodies\n * should extend this primitive rather than bypass it.\n /\nimport { type LookupAddress, type LookupOptions } from 'dns';\nimport { lookup as dnsLookupAsync } from 'dns/promises';\nimport { Agent, fetch as undiciFetch } from 'undici';\nimport { isAlwaysBlocked, isPrivateIp } from './address-guards';\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst DEFAULT_MAX_BODY_BYTES = 64 1024;\nconst ALLOWED_SCHEMES = new Set(['https:', 'http:']);\n\nexport type SsrfRefusedCode =\n \| 'invalid_url'\n \| 'scheme_not_allowed'\n \| 'non_https_without_opt_in'\n \| 'dns_lookup_failed'\n \| 'dns_empty'\n \| 'always_blocked_address'\n \| 'private_address'\n \| 'body_exceeds_limit';\n\n/*\n SSRF refusal codes that indicate runtime/network conditions rather than\n * policy refusal. Callers that want to fall back to a \"host unreachable\" or\n * \"treat as unknown\" path on these codes — rather than surfacing the\n * SsrfRefusedError to their own caller — can intersect against this set:\n \n ```ts\n * if (err instanceof SsrfRefusedError && SSRF_TRANSIENT_CODES.has(err.code)) {\n * // network condition, not a policy attack — treat as unreachable\n * } else if (err instanceof SsrfRefusedError) {\n * // policy refusal — must propagate; silently downgrading to \"unreachable\"\n * // reintroduces the catch-swallow class flagged in adcp-client#1618 review\n * throw err;\n * }\n * ```\n \n - `dns_lookup_failed`, `dns_empty`: name does not resolve. CLI fixtures\n * use `.example.invalid` to provoke these — preserving the runtime-error\n path matches pre-`ssrfSafeFetch` native-fetch behavior.\n * - `body_exceeds_limit`: response started OK (validated address, scheme,\n * etc.) but exceeded the caller's defensive cap. The host is real and\n * knows the URL; classifying as \"policy attack\" would be a misread.\n \n NOT in this set: `always_blocked_address`, `private_address`,\n * `scheme_not_allowed`, `non_https_without_opt_in`, `invalid_url`. Those\n * are policy refusals — silently downgrading them to \"unreachable\" or\n * \"suspect\" reintroduces the SSRF gap the gate was added to close.\n \n Added in adcp-client#1633.\n /\nexport const SSRF_TRANSIENT_CODES: ReadonlySet<SsrfRefusedCode> = new Set([\n 'dns_lookup_failed',\n 'dns_empty',\n 'body_exceeds_limit',\n]);\n\n/\n Thrown when the SSRF guard refuses a request before (or during) the fetch.\n * Network failures after the guard passes are not wrapped in this type —\n * callers that want to distinguish \"we refused this\" from \"the remote broke\"\n * can `instanceof SsrfRefusedError` the catch.\n /\nexport class SsrfRefusedError extends Error {\n readonly code: SsrfRefusedCode;\n readonly url: string;\n readonly hostname?: string;\n readonly address?: string;\n\n constructor(code: SsrfRefusedCode, message: string, meta: { url: string; hostname?: string; address?: string }) {\n super(message);\n this.name = 'SsrfRefusedError';\n this.code = code;\n this.url = meta.url;\n this.hostname = meta.hostname;\n this.address = meta.address;\n }\n}\n\nexport interface SsrfFetchOptions {\n method?: string;\n /* Lowercased keys preferred; values preserved verbatim. /\n headers?: Record<string, string>;\n body?: string \| Uint8Array;\n /* Allow `http://` and private/loopback targets. Default false. /\n allowPrivateIp?: boolean;\n /* Overall timeout including DNS + connect + body read. Default 10_000 ms. /\n timeoutMs?: number;\n /* Hard cap on response body bytes. Default 64 KiB. /\n maxBodyBytes?: number;\n /* Caller-provided abort signal, composed with the internal timeout. /\n signal?: AbortSignal;\n /\n Trusted scoped fetch implementation. URL validation and address\n * classification still run before invocation, but DNS pinning is delegated\n * to this implementation because custom fetchers do not accept undici\n * dispatchers. The caller MUST enforce DNS-rebinding protection itself.\n \n This deliberately explicit name prevents callers from mistaking a custom\n * transport for the internally DNS-pinned path.\n /\n trustedFetchFn?: typeof fetch;\n}\n\nexport interface SsrfFetchResult {\n url: string;\n status: number;\n /* Response headers, lowercased. /\n headers: Record<string, string>;\n /* Raw response body bytes (empty Uint8Array if no body). /\n body: Uint8Array;\n /* The validated IP address. The connection used it only when `connectionPinned` is true. /\n pinnedAddress: string;\n pinnedFamily: 4 \| 6;\n /* Whether the internal undici dispatcher pinned the connection to `pinnedAddress`. /\n connectionPinned: boolean;\n}\n\n/\n GET/POST/etc. a URL with SSRF guarding + DNS pinning. Throws\n * {@link SsrfRefusedError} when the guard refuses; other errors (network\n * timeouts, remote resets) propagate as the native fetch error.\n /\nexport async function ssrfSafeFetch(url: string, options: SsrfFetchOptions = {}): Promise<SsrfFetchResult> {\n throwIfSignalAborted(options.signal);\n const allowPrivateIp = options.allowPrivateIp === true;\n const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n\n let parsed: URL;\n try {\n parsed = new URL(url);\n } catch {\n throw new SsrfRefusedError('invalid_url', `Invalid URL: ${url}`, { url });\n }\n\n // `URL.hostname` wraps IPv6 literals in brackets (`https://[::1]/` →\n // `[::1]`). `dns.lookup` and the address classifier both want the bare\n // form; strip brackets here so IPv6 localhost URLs work under\n // `allowPrivateIp` and so bracketed literals can't slip past classification\n // on a future Node release that tolerates them.\n const hostname = parsed.hostname.replace(/^\\[\|\\]$/g, '');\n\n if (!ALLOWED_SCHEMES.has(parsed.protocol)) {\n throw new SsrfRefusedError(\n 'scheme_not_allowed',\n `Refusing to fetch URL with unsupported scheme: ${parsed.protocol}`,\n { url, hostname }\n );\n }\n if (parsed.protocol !== 'https:' && !allowPrivateIp) {\n throw new SsrfRefusedError('non_https_without_opt_in', `Refusing to fetch non-HTTPS URL: ${url}`, {\n url,\n hostname,\n });\n }\n\n let addresses: { address: string; family: number }[];\n try {\n addresses = await dnsLookupAsync(hostname, { all: true });\n } catch (err) {\n throwIfSignalAborted(options.signal);\n throw new SsrfRefusedError(\n 'dns_lookup_failed',\n `DNS lookup failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`,\n { url, hostname }\n );\n }\n throwIfSignalAborted(options.signal);\n if (addresses.length === 0) {\n throw new SsrfRefusedError('dns_empty', `DNS returned no addresses for ${hostname}`, {\n url,\n hostname,\n });\n }\n // Error messages intentionally do NOT include the resolved IP — a\n // counterparty-supplied hostname that resolves into the caller's internal\n // address space would otherwise leak network topology into compliance\n // reports and log aggregators. The address is still available on the\n // thrown error's `.address` field for programmatic debugging.\n for (const a of addresses) {\n if (isAlwaysBlocked(a.address)) {\n throw new SsrfRefusedError(\n 'always_blocked_address',\n `Refusing to fetch: ${hostname} resolves to an always-blocked address (link-local or cloud metadata)`,\n { url, hostname, address: a.address }\n );\n }\n }\n if (!allowPrivateIp) {\n for (const a of addresses) {\n if (isPrivateIp(a.address)) {\n throw new SsrfRefusedError(\n 'private_address',\n `Refusing to fetch: ${hostname} resolves to a private/loopback address`,\n { url, hostname, address: a.address }\n );\n }\n }\n }\n\n const pinned = addresses[0]!;\n const pinnedFamily = pinned.family === 6 ? 6 : 4;\n const dispatcher = new Agent({\n connect: {\n // All addresses were validated above; pin the connect to the first. The\n // custom lookup also means undici won't re-resolve and pick up a rebind.\n // undici's Agent may call lookup with `{ all: true }` (it does for HTTPS\n // targets under Node 22+), which expects the array form of the callback.\n lookup: (\n _h: string,\n opts: LookupOptions \| undefined,\n cb: (err: NodeJS.ErrnoException \| null, address: string \| LookupAddress[], family?: number) => void\n ) => {\n if (opts?.all) {\n cb(null, [{ address: pinned.address, family: pinnedFamily }]);\n } else {\n cb(null, pinned.address, pinnedFamily);\n }\n },\n },\n });\n\n const ac = new AbortController();\n const onExternalAbort = () => ac.abort(options.signal?.reason);\n options.signal?.addEventListener('abort', onExternalAbort, { once: true });\n if (options.signal?.aborted) onExternalAbort();\n const timer = setTimeout(() => ac.abort(new Error('ssrf-fetch: timeout')), timeoutMs);\n\n try {\n const res = options.trustedFetchFn\n ? await options.trustedFetchFn(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n ...(options.body !== undefined && { body: options.body as BodyInit }),\n })\n : await undiciFetch(url, {\n method: options.method ?? 'GET',\n redirect: 'manual',\n signal: ac.signal,\n headers: options.headers,\n dispatcher,\n ...(options.body !== undefined && { body: options.body }),\n });\n\n const headers: Record<string, string> = {};\n res.headers.forEach((v, k) => {\n headers[k.toLowerCase()] = v;\n });\n\n const reader = res.body?.getReader();\n if (!reader) {\n return {\n url,\n status: res.status,\n headers,\n body: new Uint8Array(),\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n }\n\n const chunks: Uint8Array[] = [];\n let bytes = 0;\n while (true) {\n const { done, value } = await reader.read();\n if (done) break;\n bytes += value.byteLength;\n if (bytes > maxBodyBytes) {\n await reader.cancel();\n throw new SsrfRefusedError('body_exceeds_limit', `Response body exceeded ${maxBodyBytes} bytes`, {\n url,\n hostname: parsed.hostname,\n address: pinned.address,\n });\n }\n chunks.push(value);\n }\n\n const buf = new Uint8Array(bytes);\n let offset = 0;\n for (const c of chunks) {\n buf.set(c, offset);\n offset += c.byteLength;\n }\n\n return {\n url,\n status: res.status,\n headers,\n body: buf,\n pinnedAddress: pinned.address,\n pinnedFamily,\n connectionPinned: !options.trustedFetchFn,\n };\n } finally {\n clearTimeout(timer);\n options.signal?.removeEventListener('abort', onExternalAbort);\n await dispatcher.close().catch(() => {});\n }\n}\n\nfunction throwIfSignalAborted(signal?: AbortSignal): void {\n if (!signal?.aborted) return;\n if (signal.reason instanceof Error) throw signal.reason;\n const error = new Error(signal.reason == null ? 'The operation was aborted' : String(signal.reason));\n error.name = 'AbortError';\n throw error;\n}\n\n/\n Decode a UTF-8 byte buffer as JSON when the content-type declares JSON, or\n * fall back to a UTF-8 string. Handy shared helper for probe-style call sites\n * that don't care about binary bodies.\n */\nexport function decodeBodyAsJsonOrText(body: Uint8Array, contentType: string \| undefined): unknown {\n if (body.byteLength === 0) return null;\n const text = Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString('utf8');\n if (contentType?.toLowerCase().includes('application/json')) {\n try {\n return JSON.parse(text);\n } catch {\n return text;\n }\n }\n return text;\n}\n"],"mappings":"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","names":[]}

package/dist/lib/protocols/abort.d.mts CHANGED Viewed

@@ -6,4 +6,6 @@ export declare function createAbortError(reason?: unknown): Error;
 export declare function createTimeoutError(timeoutMs: number): Error;
 export declare function isAbortOrTimeoutError(error: unknown): boolean;
 export declare function throwIfAborted(signal?: AbortSignal): void;
-export declare function withAbortSignal<T>(signals: Array<AbortSignal | null | undefined>, timeoutMs: number | undefined, fn: (signal?: AbortSignal) => Promise<T>): Promise<T>;
+export declare function withAbortSignal<T>(signals: Array<AbortSignal | null | undefined>, timeoutMs: number | undefined, fn: (signal?: AbortSignal) => Promise<T>, options?: {
+    timeoutError?: Error;
+}): Promise<T>;

package/dist/lib/protocols/abort.d.ts CHANGED Viewed

@@ -6,5 +6,7 @@ export declare function createAbortError(reason?: unknown): Error;
 export declare function createTimeoutError(timeoutMs: number): Error;
 export declare function isAbortOrTimeoutError(error: unknown): boolean;
 export declare function throwIfAborted(signal?: AbortSignal): void;
-export declare function withAbortSignal<T>(signals: Array<AbortSignal | null | undefined>, timeoutMs: number | undefined, fn: (signal?: AbortSignal) => Promise<T>): Promise<T>;
+export declare function withAbortSignal<T>(signals: Array<AbortSignal | null | undefined>, timeoutMs: number | undefined, fn: (signal?: AbortSignal) => Promise<T>, options?: {
+    timeoutError?: Error;
+}): Promise<T>;
 //# sourceMappingURL=abort.d.ts.map

package/dist/lib/protocols/abort.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../../src/lib/protocols/abort.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,eAAO,MAAM,kBAAkB,aAAgB,CAAC;AAEhD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQpH;AAED,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG/F;AAED,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,~~CASxD~~;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAI3D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQ7D;AAED,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAIzD;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,OAAO,EAAE,KAAK,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,EAC9C,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,~~GACvC~~,OAAO,CAAC,CAAC,CAAC,~~CAiDZ~~"}
1	+ {"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../../src/lib/protocols/abort.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,eAAO,MAAM,kBAAkB,aAAgB,CAAC;AAEhD,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQpH;AAED,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAG/F;AAED,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,CAcxD;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CAI3D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQ7D;AAED,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAIzD;AAED,wBAAsB,eAAe,CAAC,CAAC,EACrC,OAAO,EAAE,KAAK,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,EAC9C,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EACxC,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,KAAK,CAAA;CAAO,GACrC,OAAO,CAAC,CAAC,CAAC,CAoDZ"}

package/dist/lib/protocols/abort.js CHANGED Viewed

@@ -45,7 +45,9 @@ function resolveClientRequestTimeoutMs(timeoutMs) {
   return resolveRequestTimeoutMs(timeoutMs);
 }
 function createAbortError(reason) {
-  if (reason instanceof Error && (reason.name === "AbortError" || reason.name === "TimeoutError")) return reason;
+  if (reason instanceof Error && (reason.name === "AbortError" || reason.name === "TimeoutError" || reason.name === "TaskTimeoutError")) {
+    return reason;
+  }
   const error = new Error(reason == null ? "The operation was aborted" : String(reason));
   error.name = "AbortError";
   if (reason instanceof Error) {
@@ -62,15 +64,15 @@ function createTimeoutError(timeoutMs) {
 function isAbortOrTimeoutError(error) {
   if (error == null || typeof error !== "object") return false;
   const value = error;
-  if (value.name === "AbortError" || value.name === "TimeoutError") return true;
-  return value.code === -32001 || value.code === "REQUEST_TIMEOUT";
+  if (value.name === "AbortError" || value.name === "TimeoutError" || value.name === "TaskTimeoutError") return true;
+  return value.code === -32001 || value.code === "REQUEST_TIMEOUT" || value.code === "TASK_TIMEOUT";
 }
 function throwIfAborted(signal) {
   if (signal?.aborted) {
     throw createAbortError(signal.reason);
   }
 }
-async function withAbortSignal(signals, timeoutMs, fn) {
+async function withAbortSignal(signals, timeoutMs, fn, options = {}) {
   const activeSignals = signals.filter((signal) => signal != null);
   for (const signal of activeSignals) {
     throwIfAborted(signal);
@@ -78,17 +80,6 @@ async function withAbortSignal(signals, timeoutMs, fn) {
   if (timeoutMs == null && activeSignals.length === 0) {
     return fn(void 0);
   }
-  if (timeoutMs == null && activeSignals.length === 1) {
-    const signal = activeSignals[0];
-    try {
-      return await fn(signal);
-    } catch (error) {
-      if (signal.aborted) {
-        throw createAbortError(signal.reason);
-      }
-      throw error;
-    }
-  }
   const controller = new AbortController();
   const abort = (reason) => {
     if (!controller.signal.aborted) {
@@ -101,12 +92,23 @@ async function withAbortSignal(signals, timeoutMs, fn) {
     return { signal, listener };
   });
   const timer = timeoutMs == null ? void 0 : setTimeout(() => {
-    abort(createTimeoutError(timeoutMs));
+    abort(options.timeoutError ?? createTimeoutError(timeoutMs));
   }, timeoutMs);
+  let rejectOnAbort;
+  const aborted = new Promise((_resolve, reject) => {
+    rejectOnAbort = () => reject(controller.signal.reason ?? createAbortError());
+    controller.signal.addEventListener("abort", rejectOnAbort, { once: true });
+  });
   try {
-    return await fn(controller.signal);
+    return await Promise.race([fn(controller.signal), aborted]);
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw controller.signal.reason ?? createAbortError();
+    }
+    throw error;
   } finally {
     if (timer) clearTimeout(timer);
+    if (rejectOnAbort) controller.signal.removeEventListener("abort", rejectOnAbort);
     for (const { signal, listener } of listeners) {
       signal.removeEventListener("abort", listener);
     }

package/dist/lib/protocols/abort.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../../../src/lib/protocols/abort.ts"],"sourcesContent":["export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;\nexport const MAX_TIMER_DELAY_MS = 2_147_483_647;\n\nexport function resolveRequestTimeoutMs(timeoutMs: number \| undefined, defaultTimeoutMs?: number): number \| undefined {\n const resolved = timeoutMs ?? defaultTimeoutMs;\n if (resolved == null) return undefined;\n if (resolved === 0) return undefined;\n if (!Number.isFinite(resolved) \|\| resolved < 0 \|\| resolved > MAX_TIMER_DELAY_MS) {\n throw new RangeError(`requestTimeoutMs must be a finite non-negative number <= ${MAX_TIMER_DELAY_MS}`);\n }\n return resolved;\n}\n\nexport function resolveClientRequestTimeoutMs(timeoutMs: number \| undefined): number \| undefined {\n if (timeoutMs === 0) return MAX_TIMER_DELAY_MS;\n return resolveRequestTimeoutMs(timeoutMs);\n}\n\nexport function createAbortError(reason?: unknown): Error {\n if (reason instanceof Error && (reason.name === 'AbortError' \|\| reason.name === 'TimeoutError')) return reason;\n const error = new Error(reason == null ? 'The operation was aborted' : String(reason));\n error.name = 'AbortError';\n if (reason instanceof Error) {\n (error as Error & { cause?: unknown }).cause = reason;\n error.message = reason.message;\n }\n return error;\n}\n\nexport function createTimeoutError(timeoutMs: number): Error {\n const error = new Error(`Request timed out after ${timeoutMs} ms`);\n error.name = 'TimeoutError';\n return error;\n}\n\nexport function isAbortOrTimeoutError(error: unknown): boolean {\n if (error == null \|\| typeof error !== 'object') return false;\n const value = error as { name?: unknown; code?: unknown };\n if (value.name === 'AbortError' \|\| value.name === 'TimeoutError') return true;\n // MCP SDK v1 raises JSON-RPC RequestTimeout (-32001); the v2 packages use\n // the typed SDK error code REQUEST_TIMEOUT. Both represent the same\n // timeout/cancellation boundary and must bypass endpoint fallback.\n return value.code === -32001 \|\| value.code === 'REQUEST_TIMEOUT';\n}\n\nexport function throwIfAborted(signal?: AbortSignal): void {\n if (signal?.aborted) {\n throw createAbortError(signal.reason);\n }\n}\n\nexport async function withAbortSignal<T>(\n signals: Array<AbortSignal \| null \| undefined>,\n timeoutMs: number \| undefined,\n fn: (signal?: AbortSignal) => Promise<T>\n): Promise<T> {\n const activeSignals = signals.filter((signal): signal is AbortSignal => signal != null);\n for (const signal of activeSignals) {\n throwIfAborted(signal);\n }\n\n if (timeoutMs == null && activeSignals.length === 0) {\n return fn(undefined);\n }\n\n ~~if (timeoutMs == null && activeSignals.length === 1) {\n~~ const signal = activeSignals[0]!;\n try {\n return await fn(signal);\n } catch (error) {\n if (signal.aborted) {\n throw createAbortError(signal.reason);\n }\n throw error;\n }\n }\n\n const controller = new AbortController();\n const abort = (reason?: unknown) => {\n if (!controller.signal.aborted) {\n controller.abort(reason);\n }\n };\n\n const listeners = activeSignals.map(signal => {\n const listener = () => abort(createAbortError(signal.reason));\n signal.addEventListener('abort', listener, { once: true });\n return { signal, listener };\n });\n const timer =\n timeoutMs == null\n ? undefined\n : setTimeout(() => {\n abort(createTimeoutError(timeoutMs));\n }, timeoutMs);\n\n try {\n return await fn(controller.signal);\n } finally {\n if (timer) clearTimeout(timer);\n for (const { signal, listener } of listeners) {\n signal.removeEventListener('abort', listener);\n }\n }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,MAAM,6BAA6B;AACnC,MAAM,qBAAqB;AAE3B,SAAS,wBAAwB,WAA+B,kBAA+C;AACpH,QAAM,WAAW,aAAa;AAC9B,MAAI,YAAY,KAAM,QAAO;AAC7B,MAAI,aAAa,EAAG,QAAO;AAC3B,MAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,WAAW,KAAK,WAAW,oBAAoB;AAC/E,UAAM,IAAI,WAAW,4DAA4D,kBAAkB,EAAE;AAAA,EACvG;AACA,SAAO;AACT;AAEO,SAAS,8BAA8B,WAAmD;AAC/F,MAAI,cAAc,EAAG,QAAO;AAC5B,SAAO,wBAAwB,SAAS;AAC1C;AAEO,SAAS,iBAAiB,QAAyB;AACxD,~~MAAI~~,kBAAkB,~~UAAU~~,OAAO,SAAS,gBAAgB,OAAO,SAAS,~~gBAAiB~~,~~QAAO~~;~~AACxG~~,QAAM,QAAQ,IAAI,MAAM,UAAU,OAAO,8BAA8B,OAAO,MAAM,CAAC;AACrF,QAAM,OAAO;AACb,MAAI,kBAAkB,OAAO;AAC3B,IAAC,MAAsC,QAAQ;AAC/C,UAAM,UAAU,OAAO;AAAA,EACzB;AACA,SAAO;AACT;AAEO,SAAS,mBAAmB,WAA0B;AAC3D,QAAM,QAAQ,IAAI,MAAM,2BAA2B,SAAS,KAAK;AACjE,QAAM,OAAO;AACb,SAAO;AACT;AAEO,SAAS,sBAAsB,OAAyB;AAC7D,MAAI,SAAS,QAAQ,OAAO,UAAU,SAAU,QAAO;AACvD,QAAM,QAAQ;AACd,MAAI,MAAM,SAAS,gBAAgB,MAAM,SAAS,~~eAAgB~~,QAAO;~~AAIzE~~,SAAO,MAAM,SAAS,UAAU,MAAM,SAAS;~~AACjD~~;AAEO,SAAS,eAAe,QAA4B;AACzD,MAAI,QAAQ,SAAS;AACnB,UAAM,iBAAiB,OAAO,MAAM;AAAA,EACtC;AACF;AAEA,eAAsB,gBACpB,SACA,WACA,~~IACY~~;AACZ,QAAM,gBAAgB,QAAQ,OAAO,CAAC,WAAkC,UAAU,IAAI;AACtF,aAAW,UAAU,eAAe;AAClC,mBAAe,MAAM;AAAA,EACvB;AAEA,MAAI,aAAa,QAAQ,cAAc,WAAW,GAAG;AACnD,WAAO,GAAG,MAAS;AAAA,EACrB;AAEA,MAAI,aAAa,QAAQ,cAAc,WAAW,GAAG;AACnD,UAAM,SAAS,cAAc,CAAC;AAC9B,QAAI;AACF,aAAO,MAAM,GAAG,MAAM;AAAA,IACxB,SAAS,OAAO;AACd,UAAI,OAAO,SAAS;AAClB,cAAM,iBAAiB,OAAO,MAAM;AAAA,MACtC;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAEA,QAAM,aAAa,IAAI,gBAAgB;AACvC,QAAM,QAAQ,CAAC,WAAqB;AAClC,QAAI,CAAC,WAAW,OAAO,SAAS;AAC9B,iBAAW,MAAM,MAAM;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,YAAY,cAAc,IAAI,YAAU;AAC5C,UAAM,WAAW,MAAM,MAAM,iBAAiB,OAAO,MAAM,CAAC;AAC5D,WAAO,iBAAiB,SAAS,UAAU,EAAE,MAAM,KAAK,CAAC;AACzD,WAAO,EAAE,QAAQ,SAAS;AAAA,EAC5B,CAAC;AACD,QAAM,QACJ,aAAa,OACT,SACA,WAAW,MAAM;AACf,UAAM,mBAAmB,SAAS,CAAC;AAAA,~~EACrC~~,GAAG,SAAS;AAElB,MAAI;~~AACF~~,WAAO,MAAM,GAAG,WAAW,MAAM;AAAA,~~EACnC~~,UAAE;AACA,QAAI,MAAO,cAAa,KAAK;AAC7B,eAAW,EAAE,QAAQ,SAAS,KAAK,WAAW;AAC5C,aAAO,oBAAoB,SAAS,QAAQ;AAAA,IAC9C;AAAA,EACF;AACF;","names":[]}
1	+ {"version":3,"sources":["../../../src/lib/protocols/abort.ts"],"sourcesContent":["export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;\nexport const MAX_TIMER_DELAY_MS = 2_147_483_647;\n\nexport function resolveRequestTimeoutMs(timeoutMs: number \| undefined, defaultTimeoutMs?: number): number \| undefined {\n const resolved = timeoutMs ?? defaultTimeoutMs;\n if (resolved == null) return undefined;\n if (resolved === 0) return undefined;\n if (!Number.isFinite(resolved) \|\| resolved < 0 \|\| resolved > MAX_TIMER_DELAY_MS) {\n throw new RangeError(`requestTimeoutMs must be a finite non-negative number <= ${MAX_TIMER_DELAY_MS}`);\n }\n return resolved;\n}\n\nexport function resolveClientRequestTimeoutMs(timeoutMs: number \| undefined): number \| undefined {\n if (timeoutMs === 0) return MAX_TIMER_DELAY_MS;\n return resolveRequestTimeoutMs(timeoutMs);\n}\n\nexport function createAbortError(reason?: unknown): Error {\n if (\n reason instanceof Error &&\n (reason.name === 'AbortError' \|\| reason.name === 'TimeoutError' \|\| reason.name === 'TaskTimeoutError')\n ) {\n return reason;\n }\n const error = new Error(reason == null ? 'The operation was aborted' : String(reason));\n error.name = 'AbortError';\n if (reason instanceof Error) {\n (error as Error & { cause?: unknown }).cause = reason;\n error.message = reason.message;\n }\n return error;\n}\n\nexport function createTimeoutError(timeoutMs: number): Error {\n const error = new Error(`Request timed out after ${timeoutMs} ms`);\n error.name = 'TimeoutError';\n return error;\n}\n\nexport function isAbortOrTimeoutError(error: unknown): boolean {\n if (error == null \|\| typeof error !== 'object') return false;\n const value = error as { name?: unknown; code?: unknown };\n if (value.name === 'AbortError' \|\| value.name === 'TimeoutError' \|\| value.name === 'TaskTimeoutError') return true;\n // MCP SDK v1 raises JSON-RPC RequestTimeout (-32001); the v2 packages use\n // the typed SDK error code REQUEST_TIMEOUT. Both represent the same\n // timeout/cancellation boundary and must bypass endpoint fallback.\n return value.code === -32001 \|\| value.code === 'REQUEST_TIMEOUT' \|\| value.code === 'TASK_TIMEOUT';\n}\n\nexport function throwIfAborted(signal?: AbortSignal): void {\n if (signal?.aborted) {\n throw createAbortError(signal.reason);\n }\n}\n\nexport async function withAbortSignal<T>(\n signals: Array<AbortSignal \| null \| undefined>,\n timeoutMs: number \| undefined,\n fn: (signal?: AbortSignal) => Promise<T>,\n options: { timeoutError?: Error } = {}\n): Promise<T> {\n const activeSignals = signals.filter((signal): signal is AbortSignal => signal != null);\n for (const signal of activeSignals) {\n throwIfAborted(signal);\n }\n\n if (timeoutMs == null && activeSignals.length === 0) {\n return fn(undefined);\n }\n\n const controller = new AbortController();\n const abort = (reason?: unknown) => {\n if (!controller.signal.aborted) {\n controller.abort(reason);\n }\n };\n\n const listeners = activeSignals.map(signal => {\n const listener = () => abort(createAbortError(signal.reason));\n signal.addEventListener('abort', listener, { once: true });\n return { signal, listener };\n });\n const timer =\n timeoutMs == null\n ? undefined\n : setTimeout(() => {\n abort(options.timeoutError ?? createTimeoutError(timeoutMs));\n }, timeoutMs);\n\n let rejectOnAbort: ((reason: unknown) => void) \| undefined;\n const aborted = new Promise<never>((_resolve, reject) => {\n rejectOnAbort = () => reject(controller.signal.reason ?? createAbortError());\n controller.signal.addEventListener('abort', rejectOnAbort, { once: true });\n });\n\n try {\n // The signal reclaims transports that honor cancellation. The race also\n // guarantees the caller-facing deadline when an intermediate callback or\n // protocol implementation is slow to observe that signal.\n return await Promise.race([fn(controller.signal), aborted]);\n } catch (error) {\n if (controller.signal.aborted) {\n throw controller.signal.reason ?? createAbortError();\n }\n throw error;\n } finally {\n if (timer) clearTimeout(timer);\n if (rejectOnAbort) controller.signal.removeEventListener('abort', rejectOnAbort);\n for (const { signal, listener } of listeners) {\n signal.removeEventListener('abort', listener);\n }\n }\n}\n"],"mappings":"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","names":[]}