@apifuse/provider-sdk 2.2.0-beta.68 → 2.2.0-beta.69

package/dist/runtime/redirect-hop-headers.js

@@ -0,0 +1,58 @@
+import { getPublicSuffix } from "tough-cookie";
+/**
+ * Request-body header names a redirect drops when it changes the method
+ * (Fetch "request-body-header name").
+ */
+const REDIRECT_BODY_HEADERS = new Set([
+    "content-encoding",
+    "content-language",
+    "content-location",
+    "content-type",
+]);
+/**
+ * Credentials a redirect never carries to another origin. Fetch removes
+ * `Authorization` on a cross-origin redirect; `Proxy-Authorization` is a
+ * credential of the same kind.
+ */
+const CROSS_ORIGIN_CREDENTIAL_HEADERS = new Set([
+    "authorization",
+    "proxy-authorization",
+]);
+/**
+ * Schemeful site (HTML "same site"): scheme plus registrable domain from the
+ * public suffix list, or the bare host when there is none (an IP address or
+ * a single-label host).
+ */
+function schemefulSite(url) {
+    const host = url.hostname;
+    const registrable = getPublicSuffix(host, { allowSpecialUseDomain: true, ignoreError: true });
+    return `${url.protocol}//${registrable ?? host}`;
+}
+/**
+ * The caller headers the next redirect hop carries, derived from the headers
+ * the previous hop sent. Both stealth redirect walkers compute every hop's
+ * headers here, so the rules hold on every path:
+ *
+ * - a method change drops the request-body headers;
+ * - a cross-origin hop drops `Authorization` and `Proxy-Authorization`;
+ * - a cross-site hop drops an explicit `Cookie`, after which the session
+ *   cookie jar supplies cookies by its own domain rules, as a browser does.
+ *
+ * A header dropped on one hop stays dropped for the rest of the chain.
+ */
+export function redirectHopHeaders(hop, headers) {
+    const from = new URL(hop.from);
+    const to = new URL(hop.to);
+    const crossOrigin = from.origin !== to.origin;
+    const crossSite = schemefulSite(from) !== schemefulSite(to);
+    return Object.fromEntries(Object.entries(headers).filter(([name]) => {
+        const lower = name.toLowerCase();
+        if (hop.methodChanged && REDIRECT_BODY_HEADERS.has(lower))
+            return false;
+        if (crossOrigin && CROSS_ORIGIN_CREDENTIAL_HEADERS.has(lower))
+            return false;
+        if (crossSite && lower === "cookie")
+            return false;
+        return true;
+    }));
+}

package/dist/runtime/redirects.d.ts

@@ -1,4 +1,5 @@
-import type { HttpRedirectFailureReason } from "../types.js";
+import { TransportError } from "../errors.js";
+import type { HttpRedirectFailureReason, HttpRedirectPolicy } from "../types.js";
 export type RedirectHopDecision<TMethod extends string> = {
     kind: "follow";
     nextMethod: TMethod | "GET";
@@ -27,3 +28,34 @@ export declare function evaluateRedirectHop<TMethod extends string>(input: {
     maxHops: number;
     visitedRequests: ReadonlySet<string>;
 }): RedirectHopDecision<TMethod>;
+export declare const MALFORMED_REDIRECT_TARGET = "[malformed redirect target]";
+/** The transport a redirectPolicy belongs to: its name in diagnostics and its own hop limit. */
+export interface RedirectPolicyTransport {
+    readonly label: string;
+    readonly maxHops: number;
+}
+export declare function invalidRedirectPolicy(transport: RedirectPolicyTransport, message: string, cause?: Error): TransportError;
+/** Snapshot untrusted caller input synchronously, before proxy resolution or fetch. */
+export declare function normalizeRedirectPolicy(value: unknown, transport: RedirectPolicyTransport): HttpRedirectPolicy | undefined;
+export declare function redirectDiagnosticTarget(value: string): string;
+/**
+ * One hop of a same-origin `redirectPolicy` walk, shared by ctx.http and
+ * ctx.stealth so both follow and refuse identically: returns the next request
+ * inside the initial origin, or throws the `HttpRedirectError` naming why the
+ * walk stopped (cross-origin target, maxHops, loop, missing or malformed
+ * Location) before any request leaves for that target.
+ */
+export declare function nextSameOriginRedirectHop<TMethod extends string>(input: {
+    policy: HttpRedirectPolicy;
+    initialOrigin: string;
+    currentUrl: string;
+    responseUrl: string;
+    status: number;
+    method: TMethod;
+    location: string | undefined;
+    followedHops: number;
+    visitedRequests: ReadonlySet<string>;
+}): {
+    nextMethod: TMethod | "GET";
+    nextUrl: string;
+};

package/dist/runtime/redirects.js

@@ -1,3 +1,4 @@
+import { HttpRedirectError, TransportError } from "../errors.js";
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 export function isRedirectStatus(status) {
     return REDIRECT_STATUSES.has(status);
@@ -34,3 +35,115 @@ export function evaluateRedirectHop(input) {
     }
     return { kind: "follow", nextMethod, nextUrl: input.nextUrl };
 }
+const REDIRECT_POLICY_FIELDS = new Set(["mode", "maxHops"]);
+export const MALFORMED_REDIRECT_TARGET = "[malformed redirect target]";
+export function invalidRedirectPolicy(transport, message, cause) {
+    return new TransportError(`Invalid ${transport.label} redirectPolicy: ${message}`, {
+        code: "http_redirect_policy_invalid",
+        ...(cause ? { cause } : {}),
+    });
+}
+/** Snapshot untrusted caller input synchronously, before proxy resolution or fetch. */
+export function normalizeRedirectPolicy(value, transport) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw invalidRedirectPolicy(transport, "expected an object");
+    }
+    try {
+        const keys = Reflect.ownKeys(value);
+        for (const key of keys) {
+            if (typeof key !== "string" || !REDIRECT_POLICY_FIELDS.has(key)) {
+                throw invalidRedirectPolicy(transport, `unknown field ${String(key)}`);
+            }
+        }
+        for (const field of REDIRECT_POLICY_FIELDS) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, field);
+            if (!descriptor || !("value" in descriptor)) {
+                throw invalidRedirectPolicy(transport, `${field} must be an own data property`);
+            }
+        }
+        const record = value;
+        if (record.mode !== "same-origin") {
+            throw invalidRedirectPolicy(transport, 'mode must be "same-origin"');
+        }
+        if (typeof record.maxHops !== "number" ||
+            !Number.isInteger(record.maxHops) ||
+            record.maxHops < 0 ||
+            record.maxHops > transport.maxHops) {
+            throw invalidRedirectPolicy(transport, `maxHops must be an integer from 0 to ${transport.maxHops}`);
+        }
+        return { mode: "same-origin", maxHops: record.maxHops };
+    }
+    catch (error) {
+        if (error instanceof TransportError)
+            throw error;
+        throw invalidRedirectPolicy(transport, "could not be inspected safely", error instanceof Error ? error : undefined);
+    }
+}
+export function redirectDiagnosticTarget(value) {
+    try {
+        const parsed = new URL(value);
+        // Origin omits URL userinfo. Keeping only origin + path makes diagnostics
+        // useful while structurally excluding every query value and fragment,
+        // including attacker-chosen keys the provider did not declare sensitive.
+        const redactedQuery = parsed.search ? "?[REDACTED]" : "";
+        return parsed.origin === "null"
+            ? `${parsed.protocol}<opaque-target>`
+            : `${parsed.origin}${parsed.pathname}${redactedQuery}`;
+    }
+    catch {
+        return MALFORMED_REDIRECT_TARGET;
+    }
+}
+/**
+ * One hop of a same-origin `redirectPolicy` walk, shared by ctx.http and
+ * ctx.stealth so both follow and refuse identically: returns the next request
+ * inside the initial origin, or throws the `HttpRedirectError` naming why the
+ * walk stopped (cross-origin target, maxHops, loop, missing or malformed
+ * Location) before any request leaves for that target.
+ */
+export function nextSameOriginRedirectHop(input) {
+    let nextUrl;
+    try {
+        nextUrl = resolveRedirectUrl(input.location || undefined, input.responseUrl);
+    }
+    catch {
+        const target = MALFORMED_REDIRECT_TARGET;
+        throw new HttpRedirectError(`Redirect response has malformed Location target ${target}`, {
+            reason: "missing_location",
+            target,
+            status: input.status,
+        });
+    }
+    const decision = evaluateRedirectHop({
+        status: input.status,
+        method: input.method,
+        nextUrl,
+        shouldStop: nextUrl ? new URL(nextUrl).origin !== input.initialOrigin : false,
+        redirectCount: input.followedHops + 1,
+        maxHops: input.policy.maxHops,
+        visitedRequests: input.visitedRequests,
+    });
+    if (decision.kind === "follow") {
+        return { nextMethod: decision.nextMethod, nextUrl: decision.nextUrl };
+    }
+    const target = decision.nextUrl ? redirectDiagnosticTarget(decision.nextUrl) : undefined;
+    const message = (() => {
+        switch (decision.reason) {
+            case "stopped":
+                return `Redirect policy refused cross-origin target ${target}`;
+            case "max_hops":
+                return `Redirect policy reached maxHops before target ${target}`;
+            case "loop":
+                return `Redirect loop refused target ${target}`;
+            case "missing_location":
+                return `Redirect response from ${redirectDiagnosticTarget(input.currentUrl)} is missing Location`;
+        }
+    })();
+    throw new HttpRedirectError(message, {
+        reason: decision.reason,
+        ...(target ? { target } : {}),
+        status: input.status,
+    });
+}

package/dist/runtime/resolver-span-attributes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Closed-enum span attributes emitted by the resolver, by attribute key. A value listed here is an
+ * SDK-declared literal, so fail-closed diagnostic redaction keeps it the way it keeps a typed
+ * number; any other value under the same key is still free text. Registered credentials are
+ * matched either way.
+ */
+export declare const RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES: {
+    readonly vendor: readonly ["browser", "capsolver", "capmonster", "2captcha", "hypersolutions", "custom"];
+    readonly challenge_kind: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor", "akamai_sbsd"];
+    readonly endpoint: readonly ["capsolver:create_task", "twocaptcha:create_task", "hyper:ip", "hyper:sbsd_create"];
+    readonly billing: readonly ["metered", "unconfirmed"];
+    readonly outcome: readonly ["success", "vendor_error", "timeout", "abandoned", "cache_disabled", "entry_deleted", "index_entry_deleted", "not_cookie_solution", "solution_not_cached"];
+    readonly unavailability_reason: readonly ["missing_credentials", "missing_proxy_identity", "missing_client_profile", "missing_challenge_input", "missing_transport", "allocation_exhausted", "transport_failure", "timeout", "not_implemented"];
+    readonly verdict_reason: readonly ["human_puzzle", "solve_failed"];
+    readonly transport_phase: readonly ["create_task", "poll_result", "cleanup", "measure_ip", "fetch_script", "generate_payload", "post_payload"];
+    readonly resolver_identity_source: readonly ["declared", "defaulted"];
+    readonly operation: readonly ["client.close", "context.close"];
+};
+type ResolverClosedEnumSpanAttributes = typeof RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES;
+type Present<T> = Exclude<T, undefined>;
+/** Properties typed as a finite union of string literals, never plain `string`. */
+type FiniteStringKeys<T> = {
+    [K in keyof T]-?: [Present<T[K]>] extends [never] ? never : [Present<T[K]>] extends [string] ? string extends Present<T[K]> ? never : K : never;
+}[keyof T];
+type DeclaredClosedEnumAttributes<T> = {
+    [K in keyof T]: K extends FiniteStringKeys<T> ? K extends keyof ResolverClosedEnumSpanAttributes ? [Present<T[K]>] extends [ResolverClosedEnumSpanAttributes[K][number]] ? T[K] : never : never : T[K];
+};
+/**
+ * Resolver span attributes. Every property typed as a finite string union must be declared in
+ * `RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES` with all of its members, so a new closed-enum attribute
+ * cannot silently become free text that fail-closed redaction suppresses.
+ */
+export declare function resolverSpanAttributes<const T extends Record<string, unknown>>(attributes: T & DeclaredClosedEnumAttributes<T>): T;
+export {};

package/dist/runtime/resolver-span-attributes.js

@@ -0,0 +1,93 @@
+// Type-only imports: the diagnostic redactor reads this table, so it must not pull the resolver
+// runtime (or anything that imports the redactor) into module evaluation.
+/** Every member of a closed string union, as runtime values; a missing or extra member fails tsc. */
+function closedEnumValues() {
+    return (values, ..._missing) => values;
+}
+const RESOLVER_PAID_USAGE_OUTCOMES = closedEnumValues()([
+    "success",
+    "vendor_error",
+    "timeout",
+    "abandoned",
+]);
+// `resolver.cache.invalidate` outcomes. The union stays private to resolver.ts; its producer's
+// `resolverSpanAttributes` call fails to compile if it can emit an outcome missing here.
+const RESOLVER_CACHE_INVALIDATION_OUTCOMES = [
+    "cache_disabled",
+    "entry_deleted",
+    "index_entry_deleted",
+    "not_cookie_solution",
+    "solution_not_cached",
+];
+/**
+ * Closed-enum span attributes emitted by the resolver, by attribute key. A value listed here is an
+ * SDK-declared literal, so fail-closed diagnostic redaction keeps it the way it keeps a typed
+ * number; any other value under the same key is still free text. Registered credentials are
+ * matched either way.
+ */
+export const RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES = {
+    vendor: closedEnumValues()([
+        "browser",
+        "capsolver",
+        "capmonster",
+        "2captcha",
+        "hypersolutions",
+        "custom",
+    ]),
+    challenge_kind: closedEnumValues()([
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
+        "akamai_sbsd",
+    ]),
+    endpoint: closedEnumValues()([
+        "capsolver:create_task",
+        "twocaptcha:create_task",
+        "hyper:ip",
+        "hyper:sbsd_create",
+    ]),
+    billing: closedEnumValues()(["metered", "unconfirmed"]),
+    outcome: [...RESOLVER_PAID_USAGE_OUTCOMES, ...RESOLVER_CACHE_INVALIDATION_OUTCOMES],
+    unavailability_reason: closedEnumValues()([
+        "missing_credentials",
+        "missing_proxy_identity",
+        "missing_client_profile",
+        "missing_challenge_input",
+        "missing_transport",
+        "allocation_exhausted",
+        "transport_failure",
+        "timeout",
+        "not_implemented",
+    ]),
+    verdict_reason: closedEnumValues()([
+        "human_puzzle",
+        "solve_failed",
+    ]),
+    transport_phase: closedEnumValues()([
+        "create_task",
+        "poll_result",
+        "cleanup",
+        "measure_ip",
+        "fetch_script",
+        "generate_payload",
+        "post_payload",
+    ]),
+    resolver_identity_source: closedEnumValues()(["declared", "defaulted"]),
+    operation: closedEnumValues()([
+        "client.close",
+        "context.close",
+    ]),
+};
+/**
+ * Resolver span attributes. Every property typed as a finite string union must be declared in
+ * `RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES` with all of its members, so a new closed-enum attribute
+ * cannot silently become free text that fail-closed redaction suppresses.
+ */
+export function resolverSpanAttributes(attributes) {
+    return attributes;
+}

package/dist/runtime/resolver-usage.d.ts

@@ -4,6 +4,14 @@ import type { TraceRecorder } from "./trace.js";
 export declare const RESOLVER_PAID_USAGE_SPAN = "resolver.usage";
 export type ResolverPaidUsageOutcome = "success" | "vendor_error" | "timeout" | "abandoned";
 export type ResolverPaidUsageEndpoint = "capsolver:create_task" | "twocaptcha:create_task" | "hyper:ip" | "hyper:sbsd_create";
+/**
+ * How one call to the endpoint is counted. `metered` endpoints are the vendors' task or
+ * payload creation calls: the SDK counts one unit per call (the vendor ledger stays
+ * authoritative for refunds of failed tasks). Hyper's `/ip` reflector is authenticated
+ * but has no published price, so it is recorded with 0 units and `billing: "unconfirmed"`
+ * rather than invented as a paid unit; the span still proves the call was made.
+ */
+export type ResolverPaidUsageBilling = "metered" | "unconfirmed";
 /**
  * Records one `resolver.usage` span around a paid vendor call. Callers validate credentials
  * and transport first, so a span means a potentially billable request was attempted (a

package/dist/runtime/resolver-usage.js

@@ -1,11 +1,5 @@
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 export const RESOLVER_PAID_USAGE_SPAN = "resolver.usage";
-/**
- * How one call to the endpoint is counted. `metered` endpoints are the vendors' task or
- * payload creation calls: the SDK counts one unit per call (the vendor ledger stays
- * authoritative for refunds of failed tasks). Hyper's `/ip` reflector is authenticated
- * but has no published price, so it is recorded with 0 units and `billing: "unconfirmed"`
- * rather than invented as a paid unit; the span still proves the call was made.
- */
 const ENDPOINT_BILLING = {
     "capsolver:create_task": { billable_units: 1, billing: "metered" },
     "twocaptcha:create_task": { billable_units: 1, billing: "metered" },
@@ -42,7 +36,7 @@ export async function recordPaidResolverCreate(options) {
         }
         return options.create();
     }
-    const baseAttributes = {
+    const baseAttributes = resolverSpanAttributes({
         vendor: options.vendor,
         challenge_kind: options.kind,
         endpoint: options.endpoint,
@@ -51,10 +45,10 @@ export async function recordPaidResolverCreate(options) {
         ...(options.usage ? { vendor_index: options.usage.vendorIndex } : {}),
         ...(options.round === undefined ? {} : { round: options.round }),
         resolver_identity_scope: options.usage?.resolverIdentityScope,
-    };
+    });
     return options.traceRecorder.runSpan(RESOLVER_PAID_USAGE_SPAN, options.create, {
         attributes: baseAttributes,
-        onSuccess: () => ({ outcome: "success" }),
-        onError: (error) => ({ outcome: errorOutcome(error, options.signal) }),
+        onSuccess: () => resolverSpanAttributes({ outcome: "success" }),
+        onError: (error) => resolverSpanAttributes({ outcome: errorOutcome(error, options.signal) }),
     });
 }

package/dist/runtime/resolver-vendors/browser.js

@@ -1,5 +1,6 @@
 import { isProviderError } from "../../errors.js";
 import { createBrowserClient } from "../browser.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
 import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
 import { ResolverVendorUnavailableError, } from "./types.js";
@@ -141,15 +142,15 @@ async function runBoundedCleanup(cleanup, timeoutMs, challengeKind, operation, t
     }
     await traceRecorder
         .runSpan("resolver.vendor.cleanup", boundedCleanup, {
-        attributes: {
+        attributes: resolverSpanAttributes({
             vendor: BROWSER_VENDOR_ID,
             challenge_kind: challengeKind,
             operation,
-        },
+        }),
         onError(error) {
-            return {
+            return resolverSpanAttributes({
                 error_message: error instanceof Error ? error.message : String(error),
-            };
+            });
         },
     })
         .catch(() => undefined);

package/dist/runtime/resolver-vendors/capsolver.js

@@ -2,6 +2,7 @@ import { getStealthProfile } from "../../stealth/profiles.js";
 import { redactSensitiveText } from "../request-options.js";
 import { DEFAULT_STEALTH_PROFILE } from "../stealth.js";
 import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, resolverVendorSupports, } from "./types.js";
 const CAPSOLVER_VENDOR_ID = "capsolver";
@@ -263,7 +264,7 @@ function endpoint(baseUrl, path) {
 }
 function spanErrorAttributes(error, phase) {
     if (error instanceof ResolverVendorUnavailableError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: error.reason,
             transport_phase: error.phase,
             ...(error instanceof CapsolverUnavailableError
@@ -275,21 +276,21 @@ function spanErrorAttributes(error, phase) {
                     response_length: error.responseLength,
                 }
                 : {}),
-        };
+        });
     }
     if (error instanceof CapsolverVerdictError) {
-        return {
+        return resolverSpanAttributes({
             verdict_reason: error.reason,
             transport_phase: error.phase,
             vendor_error_code: error.errorCode,
             vendor_error_description: error.errorDescription,
-        };
+        });
     }
     if (error instanceof CapsolverSolveTimeoutError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: "timeout",
             transport_phase: phase,
-        };
+        });
     }
     return undefined;
 }
@@ -436,10 +437,10 @@ export function createCapsolverResolverVendorAdapter(options) {
                 };
                 const taskId = traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: CAPSOLVER_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "create_task"),
                     })
                     : await createTask();
@@ -506,10 +507,10 @@ export function createCapsolverResolverVendorAdapter(options) {
                 };
                 return traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: CAPSOLVER_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "poll_result"),
                     })
                     : await pollResult();

package/dist/runtime/resolver-vendors/twocaptcha.js

@@ -1,4 +1,5 @@
 import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, resolverVendorSupports, } from "./types.js";
 const TWOCAPTCHA_VENDOR_ID = "2captcha";
@@ -198,19 +199,19 @@ function endpoint(baseUrl, path) {
 }
 function spanErrorAttributes(error, phase) {
     if (error instanceof ResolverVendorUnavailableError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: error.reason,
             transport_phase: error.phase,
-        };
+        });
     }
     // The solve budget raises TwoCaptchaSolveTimeoutError inside the spanned closure and
     // the outer catch converts it only after the span has been finalized, so the span has
     // to recognize it here or slow solves lose exactly the attribution these spans add.
     if (error instanceof TwoCaptchaSolveTimeoutError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: "timeout",
             transport_phase: phase,
-        };
+        });
     }
     return undefined;
 }
@@ -345,10 +346,10 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                 };
                 const taskId = traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: TWOCAPTCHA_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "create_task"),
                     })
                     : await createTask();
@@ -387,10 +388,10 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                 };
                 return traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: TWOCAPTCHA_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "poll_result"),
                     })
                     : await pollResult();

package/dist/runtime/resolver.js

@@ -13,6 +13,7 @@ import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocap
 import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, attachResolverVendorPollObserver, resolveProviderResolverVendors, resolverVendorSupports, } from "./resolver-vendors/types.js";
 import { createUnsupportedResolverClient, inheritResolverTelemetryBinding, registerResolverTelemetryBinding, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 import { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, kindRequiresClientProfile, } from "./resolver-config.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
@@ -356,7 +357,7 @@ function unavailableAttempt(error, forTelemetry = false) {
 }
 function unavailableSpanAttributes(error) {
     const attempt = unavailableAttempt(error);
-    return {
+    return resolverSpanAttributes({
         unavailability_reason: error.reason,
         missing_fields: error.missingFields,
         cause_name: attempt.cause?.name,
@@ -364,7 +365,7 @@ function unavailableSpanAttributes(error) {
         upstream_host: attempt.upstreamHost,
         transport_phase: attempt.phase,
         transport_round: attempt.round,
-    };
+    });
 }
 function resolverTelemetryPhase(value) {
     return value === "create_task" ||
@@ -657,8 +658,8 @@ async function invalidateResolverSolutionWithOutcome(resolver, challenge, soluti
         return await invalidate();
     }
     return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
-        attributes: { challenge_kind: challenge.kind },
-        onSuccess: (outcome) => ({ outcome }),
+        attributes: resolverSpanAttributes({ challenge_kind: challenge.kind }),
+        onSuccess: (outcome) => resolverSpanAttributes({ outcome }),
     });
 }
 /** Remove the cached entry for the exact solution object returned by this resolver. */
@@ -864,12 +865,12 @@ function createResolverChainClient(options) {
                         };
                         solution = traceRecorder
                             ? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
-                                attributes: {
+                                attributes: resolverSpanAttributes({
                                     vendor: adapter.id,
                                     challenge_kind: challenge.kind,
                                     client_profile: options.clientProfile,
                                     resolver_identity_source: identityResolution.userAgentSource,
-                                },
+                                }),
                                 onError(error) {
                                     return error instanceof ResolverVendorUnavailableError
                                         ? unavailableSpanAttributes(error)

package/dist/runtime/stealth-owned-headers.d.ts

@@ -3,18 +3,24 @@
  *
  * `ctx.stealth` composes these from the Chrome emulation and the request class,
  * so a caller value is rejected at request time with `SDKError` code
- * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` (`assertCallerHeadersSupported` in
- * stealth.ts). The `browser-version-literal` lint reports a subset of these
- * names — the `sec-fetch-*` and `sec-ch-ua*` families — in files that use
- * `ctx.stealth` (`isReportedOwnedHeaderName` in lint.ts). Both read this
- * module, so the lint cannot claim a rejection the runtime does not perform;
- * it reports deliberately less than the runtime rejects (host, connection,
+ * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` ({@link assertCallerHeadersSupported}).
+ * The offline test harness (`runStandardTests`) calls the same function on
+ * every `ctx.stealth` request it serves, so a provider test fails exactly where
+ * production would, whichever file or variable the header came from. That is
+ * the cross-file enforcement.
+ *
+ * The `browser-version-literal` lint reports a subset of these names — the
+ * `sec-fetch-*` and `sec-ch-ua*` families — in files that use `ctx.stealth`
+ * (`isReportedOwnedHeaderName` in lint.ts). Both read this module, so the lint
+ * cannot claim a rejection the runtime does not perform; it reports
+ * deliberately less than the runtime rejects (host, connection,
  * accept-encoding and a non-literal user-agent stay silent — see that
  * predicate for why), so a green `apifuse check` is not proof that no owned
  * header is set.
  *
- * Leaf module by design: no imports, so the lazily loaded CLI lint path does
- * not pull the stealth runtime in.
+ * Kept off the stealth runtime: the only import is `errors.js`, whose own
+ * imports are type-only, so the lazily loaded CLI lint path does not pull the
+ * stealth runtime in.
  */
 export declare const SDK_OWNED_EXACT_CHROME_HEADERS: ReadonlySet<string>;
 export declare const SDK_OWNED_CHROME_HEADER_PREFIX = "sec-fetch-";
@@ -24,3 +30,10 @@ export declare const SDK_OWNED_CHROME_HEADER_PREFIX = "sec-fetch-";
  * `sec-fetch-*` name.
  */
 export declare function isStealthOwnedHeaderName(name: string): boolean;
+/**
+ * Throws `SDKError` `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` for the first caller
+ * header `ctx.stealth` owns. An `undefined` value is skipped, as the transport
+ * drops it before sending. The stealth runtime and the offline test harness
+ * both call this, so the two cannot disagree about what is rejected.
+ */
+export declare function assertCallerHeadersSupported(headers: Readonly<Record<string, string | readonly string[] | undefined>>): void;