@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/runtime/resolver-span-attributes.ts

@@ -0,0 +1,139 @@
+import type { ProxyUserAgentSource } from "../config/loader.js";
+import type { ProviderChallengeKind, ProviderResolverVendor } from "../types.js";
+import type { ResolverTelemetryPhase } from "./resolver-telemetry.js";
+import type {
+	ResolverPaidUsageBilling,
+	ResolverPaidUsageEndpoint,
+	ResolverPaidUsageOutcome,
+} from "./resolver-usage.js";
+import type {
+	ResolverChallengeVerdictReason,
+	ResolverVendorUnavailableReason,
+} from "./resolver-vendors/types.js";
+
+// 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<TUnion extends string>() {
+	return <const TValues extends readonly TUnion[]>(
+		values: TValues,
+		..._missing: Exclude<TUnion, TValues[number]> extends never
+			? []
+			: ["Missing closed-enum values", Exclude<TUnion, TValues[number]>]
+	): TValues => values;
+}
+
+const RESOLVER_PAID_USAGE_OUTCOMES = closedEnumValues<ResolverPaidUsageOutcome>()([
+	"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",
+] as const;
+
+/**
+ * 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<ProviderResolverVendor>()([
+		"browser",
+		"capsolver",
+		"capmonster",
+		"2captcha",
+		"hypersolutions",
+		"custom",
+	]),
+	challenge_kind: closedEnumValues<ProviderChallengeKind>()([
+		"turnstile",
+		"recaptcha_v2",
+		"recaptcha_v3",
+		"hcaptcha",
+		"cloudflare_interstitial",
+		"aws_waf",
+		"akamai_sec_cpt",
+		"akamai_sensor",
+		"akamai_sbsd",
+	]),
+	endpoint: closedEnumValues<ResolverPaidUsageEndpoint>()([
+		"capsolver:create_task",
+		"twocaptcha:create_task",
+		"hyper:ip",
+		"hyper:sbsd_create",
+	]),
+	billing: closedEnumValues<ResolverPaidUsageBilling>()(["metered", "unconfirmed"]),
+	outcome: [...RESOLVER_PAID_USAGE_OUTCOMES, ...RESOLVER_CACHE_INVALIDATION_OUTCOMES],
+	unavailability_reason: closedEnumValues<ResolverVendorUnavailableReason>()([
+		"missing_credentials",
+		"missing_proxy_identity",
+		"missing_client_profile",
+		"missing_challenge_input",
+		"missing_transport",
+		"allocation_exhausted",
+		"transport_failure",
+		"timeout",
+		"not_implemented",
+	]),
+	verdict_reason: closedEnumValues<ResolverChallengeVerdictReason>()([
+		"human_puzzle",
+		"solve_failed",
+	]),
+	transport_phase: closedEnumValues<ResolverTelemetryPhase>()([
+		"create_task",
+		"poll_result",
+		"cleanup",
+		"measure_ip",
+		"fetch_script",
+		"generate_payload",
+		"post_payload",
+	]),
+	resolver_identity_source: closedEnumValues<ProxyUserAgentSource>()(["declared", "defaulted"]),
+	operation: closedEnumValues<"client.close" | "context.close">()([
+		"client.close",
+		"context.close",
+	]),
+} as const;
+
+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 function resolverSpanAttributes<const T extends Record<string, unknown>>(
+	attributes: T & DeclaredClosedEnumAttributes<T>,
+): T {
+	return attributes;
+}

package/src/runtime/resolver-telemetry.ts

@@ -0,0 +1,362 @@
+import { Buffer } from "node:buffer";
+import type { ProviderChallengeKind, ProviderResolverVendor } from "../types.js";
+import { closedEnum, type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
+import type { ResolverVendorUnavailableReason } from "./resolver-vendors/types.js";
+
+/**
+ * Result of the resolver call. `solved` means the adapter returned a solution;
+ * for SBSD this means payload acceptance, even when `verified` is false.
+ * It does not assert that a later protected request succeeded. Stealth reports
+ * that verification separately through the refetch status and challenge outcome.
+ */
+export type ResolverTelemetryOutcome = "solved" | "cached" | "exhausted" | "aborted" | "error";
+export type ResolverTelemetryCacheStatus = "hit" | "miss" | "disabled" | "not_cacheable";
+export type ResolverTelemetryIdentitySource = "declared" | "defaulted" | "none";
+export type ResolverTelemetryPhase =
+	| "create_task"
+	| "poll_result"
+	| "cleanup"
+	| "measure_ip"
+	| "fetch_script"
+	| "generate_payload"
+	| "post_payload";
+export type ResolverTelemetryAttemptOutcome = "ok" | "error";
+export type ResolverTelemetryErrorClass =
+	| ResolverVendorUnavailableReason
+	| "aborted"
+	| "unexpected";
+export type ResolverTelemetryCacheWriteReason = "no_expires" | "not_cacheable" | "error";
+
+export type ResolverIdentityTelemetryEvent = {
+	readonly source: ResolverTelemetryIdentitySource;
+	readonly failure?: ResolverVendorUnavailableReason;
+};
+
+export type ResolverCacheReadTelemetryEvent = {
+	readonly status: ResolverTelemetryCacheStatus;
+	readonly challengeKind: ProviderChallengeKind;
+};
+
+export type ResolverCacheWriteTelemetryEvent = {
+	readonly written: boolean;
+	readonly reason?: ResolverTelemetryCacheWriteReason;
+};
+
+export type ResolverVendorAttemptTelemetryEvent = {
+	readonly vendor: ProviderResolverVendor;
+	readonly phase: ResolverTelemetryPhase;
+	readonly outcome: ResolverTelemetryAttemptOutcome;
+	readonly ms: number;
+	readonly pollCount?: number;
+	readonly errorClass?: ResolverTelemetryErrorClass;
+	readonly vendorErrorCode?: string;
+	readonly vendorErrorDescription?: string;
+	/** Operator-only diagnostics; free text is redacted, detached and bounded by the collector. */
+	readonly diagnostics?: {
+		readonly cause?: { readonly name: string; readonly message: string };
+		readonly upstreamHost?: string;
+		readonly missingFields?: readonly string[];
+		readonly round?: number;
+		/** One-based position in the supporting vendor chain. */
+		readonly attemptIndex?: number;
+		/** Actual adapter phase, including phases outside the header's closed enum. */
+		readonly phase?: string;
+	};
+};
+
+export type ResolverFailoverTelemetryEvent = {
+	readonly from: ProviderResolverVendor;
+	readonly to: ProviderResolverVendor;
+	readonly reason: ResolverVendorUnavailableReason;
+};
+
+export type ResolverOutcomeTelemetryEvent = {
+	readonly outcome: ResolverTelemetryOutcome;
+	readonly solveMs: number;
+	readonly challengeKind: ProviderChallengeKind;
+};
+
+export interface ResolverTelemetrySink {
+	recordIdentity(event: ResolverIdentityTelemetryEvent): void;
+	recordCacheRead(event: ResolverCacheReadTelemetryEvent): void;
+	recordCacheWrite(event: ResolverCacheWriteTelemetryEvent): void;
+	recordVendorAttempt(event: ResolverVendorAttemptTelemetryEvent): void;
+	recordFailover(event: ResolverFailoverTelemetryEvent): void;
+	recordOutcome(event: ResolverOutcomeTelemetryEvent): void;
+}
+
+export type ResolverAttemptSample = {
+	v: ProviderResolverVendor;
+	p: ResolverTelemetryPhase;
+	o: ResolverTelemetryAttemptOutcome;
+	ms: number;
+	c?: string;
+	e?: ResolverTelemetryErrorClass;
+	diagnostics?: ResolverVendorAttemptTelemetryEvent["diagnostics"];
+};
+
+export type ResolverTelemetryLogPayload = {
+	/** Adapter result; `solved` includes unverified payload acceptance. Read the protected refetch status/challenge outcome for verification. */
+	outcome?: ResolverTelemetryOutcome;
+	challengeKind?: ProviderChallengeKind;
+	cacheStatus?: ResolverTelemetryCacheStatus;
+	cacheWrite?: {
+		written: boolean;
+		reason?: ResolverTelemetryCacheWriteReason;
+	};
+	identitySource?: ResolverTelemetryIdentitySource;
+	identityFailure?: ResolverVendorUnavailableReason;
+	solveMs?: number;
+	attempts: number;
+	failovers: number;
+	vendorChain: ProviderResolverVendor[];
+	vendorUsed?: ProviderResolverVendor;
+	pollCount: number;
+	attemptSamples?: ResolverAttemptSample[];
+	attemptSamplesDropped?: number;
+	lastVendorErrorDescription?: string;
+};
+
+export type ResolverTelemetryHeaderPayload = {
+	/** Same adapter-result semantics as the log outcome; `solved` does not imply protected-refetch success. */
+	outcome?: ClosedEnum<ResolverTelemetryOutcome>;
+	cacheStatus?: ClosedEnum<ResolverTelemetryCacheStatus>;
+	solveMs?: number;
+	attempts: number;
+	failovers: number;
+	vendorUsed?: ClosedEnum<ProviderResolverVendor>;
+	vendorChain: ClosedEnum<ProviderResolverVendor>[];
+	pollCount: number;
+	identitySource?: ClosedEnum<ResolverTelemetryIdentitySource>;
+	attemptSamples?: {
+		v: ClosedEnum<ProviderResolverVendor>;
+		p: ClosedEnum<ResolverTelemetryPhase>;
+		o: ClosedEnum<ResolverTelemetryAttemptOutcome>;
+		ms: number;
+		c?: ClosedEnum<string>;
+	}[];
+};
+
+const MAX_RESOLVER_ATTEMPT_SAMPLES = 24;
+const MAX_RESOLVER_VENDOR_CHAIN = 64;
+const MAX_DIAGNOSTIC_TEXT = 300;
+const MAX_MISSING_FIELDS = 24;
+const HEADER_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+
+function boundedInteger(value: number): number {
+	return Math.max(0, Math.floor(Number.isFinite(value) ? value : 0));
+}
+
+export function boundedText(value: string, redact?: (text: string) => string): string {
+	let result = value;
+	try {
+		result = redact?.(value) ?? value;
+	} catch {
+		return "[REDACTION_FAILED]";
+	}
+	// Copy code units through an independent UTF-16 buffer. A sliced string can
+	// otherwise keep a multi-megabyte vendor response alive in both JSC and V8.
+	// Preserve lone surrogates deliberately, including a pair split at the limit.
+	const length = Math.min(result.length, MAX_DIAGNOSTIC_TEXT);
+	const units = Buffer.alloc(length * 2);
+	for (let index = 0; index < length; index += 1) {
+		units.writeUInt16LE(result.charCodeAt(index), index * 2);
+	}
+	return units.toString("utf16le");
+}
+
+function boundedDiagnostics(
+	diagnostics: NonNullable<ResolverVendorAttemptTelemetryEvent["diagnostics"]>,
+	redact?: (text: string) => string,
+): NonNullable<ResolverAttemptSample["diagnostics"]> {
+	return {
+		...(diagnostics.cause
+			? {
+					cause: {
+						name: boundedText(diagnostics.cause.name, redact),
+						message: boundedText(diagnostics.cause.message, redact),
+					},
+				}
+			: {}),
+		...(diagnostics.upstreamHost
+			? { upstreamHost: boundedText(diagnostics.upstreamHost, redact) }
+			: {}),
+		...(diagnostics.missingFields
+			? {
+					missingFields: diagnostics.missingFields
+						.slice(0, MAX_MISSING_FIELDS)
+						.map((field) => boundedText(field, redact)),
+				}
+			: {}),
+		...(diagnostics.round === undefined ? {} : { round: boundedInteger(diagnostics.round) }),
+		...(diagnostics.attemptIndex === undefined
+			? {}
+			: { attemptIndex: boundedInteger(diagnostics.attemptIndex) }),
+		...(diagnostics.phase ? { phase: boundedText(diagnostics.phase, redact) } : {}),
+	};
+}
+
+export class ResolverTelemetryCollector
+	implements
+		ResolverTelemetrySink,
+		TelemetryContributor<ResolverTelemetryLogPayload, ResolverTelemetryHeaderPayload>
+{
+	readonly key = "resolver" as const;
+	readonly #redact: ((text: string) => string) | undefined;
+	#identity: ResolverIdentityTelemetryEvent | undefined;
+	#cacheRead: ResolverCacheReadTelemetryEvent | undefined;
+	#cacheWrite: ResolverCacheWriteTelemetryEvent | undefined;
+	#outcome: ResolverOutcomeTelemetryEvent | undefined;
+	#attempts = 0;
+	#failovers = 0;
+	#pollCount = 0;
+	#vendorChain: ProviderResolverVendor[] = [];
+	#vendorUsed: ProviderResolverVendor | undefined;
+	#attemptSamples: ResolverAttemptSample[] = [];
+	#attemptSamplesDropped = 0;
+	#lastVendorErrorDescription: string | undefined;
+
+	constructor(options: { redact?: (text: string) => string } = {}) {
+		this.#redact = options.redact;
+	}
+
+	recordIdentity(event: ResolverIdentityTelemetryEvent): void {
+		this.#identity = { ...event };
+	}
+
+	recordCacheRead(event: ResolverCacheReadTelemetryEvent): void {
+		this.#cacheRead = { ...event };
+	}
+
+	recordCacheWrite(event: ResolverCacheWriteTelemetryEvent): void {
+		this.#cacheWrite = { ...event };
+	}
+
+	recordVendorAttempt(event: ResolverVendorAttemptTelemetryEvent): void {
+		const ms = boundedInteger(event.ms);
+		const pollCount = event.pollCount === undefined ? 0 : boundedInteger(event.pollCount);
+		this.#pollCount += pollCount;
+		if (event.phase !== "cleanup") {
+			this.#attempts += 1;
+			if (
+				this.#vendorChain.length < MAX_RESOLVER_VENDOR_CHAIN &&
+				this.#vendorChain.at(-1) !== event.vendor
+			) {
+				this.#vendorChain.push(event.vendor);
+			}
+			if (event.outcome === "ok") this.#vendorUsed = event.vendor;
+		}
+		if (this.#attemptSamples.length < MAX_RESOLVER_ATTEMPT_SAMPLES) {
+			this.#attemptSamples.push({
+				v: event.vendor,
+				p: event.phase,
+				o: event.outcome,
+				ms,
+				...(event.vendorErrorCode ? { c: boundedText(event.vendorErrorCode, this.#redact) } : {}),
+				...(event.errorClass ? { e: event.errorClass } : {}),
+				...(event.diagnostics
+					? { diagnostics: boundedDiagnostics(event.diagnostics, this.#redact) }
+					: {}),
+			});
+		} else {
+			this.#attemptSamplesDropped += 1;
+		}
+		if (event.vendorErrorDescription) {
+			this.#lastVendorErrorDescription = boundedText(event.vendorErrorDescription, this.#redact);
+		}
+	}
+
+	recordFailover(_event: ResolverFailoverTelemetryEvent): void {
+		this.#failovers += 1;
+	}
+
+	recordOutcome(event: ResolverOutcomeTelemetryEvent): void {
+		this.#outcome = { ...event, solveMs: boundedInteger(event.solveMs) };
+	}
+
+	toLogPayload(): ResolverTelemetryLogPayload | undefined {
+		if (
+			!this.#identity &&
+			!this.#cacheRead &&
+			!this.#cacheWrite &&
+			!this.#outcome &&
+			this.#attempts === 0 &&
+			this.#attemptSamples.length === 0 &&
+			this.#failovers === 0
+		) {
+			return undefined;
+		}
+		return {
+			...(this.#outcome
+				? {
+						outcome: this.#outcome.outcome,
+						challengeKind: this.#outcome.challengeKind,
+						solveMs: this.#outcome.solveMs,
+					}
+				: this.#cacheRead
+					? { challengeKind: this.#cacheRead.challengeKind }
+					: {}),
+			...(this.#cacheRead ? { cacheStatus: this.#cacheRead.status } : {}),
+			...(this.#cacheWrite ? { cacheWrite: { ...this.#cacheWrite } } : {}),
+			...(this.#identity
+				? {
+						identitySource: this.#identity.source,
+						...(this.#identity.failure ? { identityFailure: this.#identity.failure } : {}),
+					}
+				: {}),
+			attempts: this.#attempts,
+			failovers: this.#failovers,
+			vendorChain: [...this.#vendorChain],
+			...(this.#vendorUsed ? { vendorUsed: this.#vendorUsed } : {}),
+			pollCount: this.#pollCount,
+			...(this.#attemptSamples.length > 0
+				? {
+						attemptSamples: this.#attemptSamples.map((sample) => ({
+							...sample,
+							...(sample.diagnostics
+								? {
+										diagnostics: {
+											...sample.diagnostics,
+											...(sample.diagnostics.cause
+												? { cause: { ...sample.diagnostics.cause } }
+												: {}),
+											...(sample.diagnostics.missingFields
+												? { missingFields: [...sample.diagnostics.missingFields] }
+												: {}),
+										},
+									}
+								: {}),
+						})),
+					}
+				: {}),
+			...(this.#attemptSamplesDropped > 0
+				? { attemptSamplesDropped: this.#attemptSamplesDropped }
+				: {}),
+			...(this.#lastVendorErrorDescription
+				? { lastVendorErrorDescription: this.#lastVendorErrorDescription }
+				: {}),
+		};
+	}
+
+	toHeaderPayload(log: ResolverTelemetryLogPayload): ResolverTelemetryHeaderPayload {
+		const attemptSamples = log.attemptSamples?.map((sample) => ({
+			v: closedEnum(sample.v),
+			p: closedEnum(sample.p),
+			o: closedEnum(sample.o),
+			ms: sample.ms,
+			...(sample.c && HEADER_TOKEN.test(sample.c) ? { c: closedEnum(sample.c) } : {}),
+		}));
+		return {
+			...(log.outcome ? { outcome: closedEnum(log.outcome) } : {}),
+			...(log.cacheStatus ? { cacheStatus: closedEnum(log.cacheStatus) } : {}),
+			...(log.solveMs === undefined ? {} : { solveMs: log.solveMs }),
+			attempts: log.attempts,
+			failovers: log.failovers,
+			...(log.vendorUsed ? { vendorUsed: closedEnum(log.vendorUsed) } : {}),
+			vendorChain: log.vendorChain.map((vendor) => closedEnum(vendor)),
+			pollCount: log.pollCount,
+			...(log.identitySource ? { identitySource: closedEnum(log.identitySource) } : {}),
+			...(attemptSamples && attemptSamples.length > 0 ? { attemptSamples } : {}),
+		};
+	}
+}

package/src/runtime/resolver-usage.ts

@@ -0,0 +1,99 @@
+import type { ProviderChallengeKind, ProviderResolverVendor } from "../types.js";
+import type {
+	ResolverPaidUsageContext,
+	ResolverVendorUnavailableError,
+} from "./resolver-vendors/types.js";
+import type { TraceRecorder } from "./trace.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
+
+export 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";
+
+const ENDPOINT_BILLING: Record<
+	ResolverPaidUsageEndpoint,
+	{ readonly billable_units: 0 | 1; readonly billing: ResolverPaidUsageBilling }
+> = {
+	"capsolver:create_task": { billable_units: 1, billing: "metered" },
+	"twocaptcha:create_task": { billable_units: 1, billing: "metered" },
+	"hyper:ip": { billable_units: 0, billing: "unconfirmed" },
+	"hyper:sbsd_create": { billable_units: 1, billing: "metered" },
+};
+
+function errorOutcome(error: unknown, signal: AbortSignal): ResolverPaidUsageOutcome {
+	const signalReason = signal.reason;
+	const errorName = error instanceof Error ? error.name : "";
+	const reasonName = signalReason instanceof Error ? signalReason.name : "";
+	const unavailableReason = (error as Partial<ResolverVendorUnavailableError> | undefined)?.reason;
+	if (
+		unavailableReason === "timeout" ||
+		/timeout/iu.test(errorName) ||
+		/timeout/iu.test(reasonName)
+	) {
+		return "timeout";
+	}
+	if (signal.aborted) return "abandoned";
+	return "vendor_error";
+}
+
+const warnedSinks = new WeakSet<(message: string) => void>();
+
+/**
+ * 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
+ * failed create the vendor may still bill is a span too). Without a trace recorder the call
+ * still runs; the lost billing record is warned once per warn sink.
+ */
+export async function recordPaidResolverCreate<T>(options: {
+	readonly traceRecorder?: TraceRecorder;
+	readonly vendor: ProviderResolverVendor;
+	readonly kind: ProviderChallengeKind;
+	readonly endpoint: ResolverPaidUsageEndpoint;
+	/** 1-based round for endpoints called more than once per solve (Hyper payload rounds). */
+	readonly round?: number;
+	readonly signal: AbortSignal;
+	readonly usage?: ResolverPaidUsageContext;
+	readonly warn?: (message: string) => void;
+	readonly create: () => Promise<T>;
+}): Promise<T> {
+	if (!options.traceRecorder) {
+		const warn = options.warn ?? console.warn;
+		if (!warnedSinks.has(warn)) {
+			warnedSinks.add(warn);
+			warn(
+				`[provider-sdk] Paid resolver call ${options.endpoint} ran without a trace recorder; its resolver.usage record is lost (reported once).`,
+			);
+		}
+		return options.create();
+	}
+	const baseAttributes = resolverSpanAttributes({
+		vendor: options.vendor,
+		challenge_kind: options.kind,
+		endpoint: options.endpoint,
+		...ENDPOINT_BILLING[options.endpoint],
+		// Only the resolver chain knows the vendor's position; a direct adapter call has none.
+		...(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: () => resolverSpanAttributes({ outcome: "success" }),
+		onError: (error) => resolverSpanAttributes({ outcome: errorOutcome(error, options.signal) }),
+	});
+}

package/src/runtime/resolver-vendors/bindings.ts

@@ -0,0 +1,61 @@
+import type { ProviderChallenge, ProviderChallengeKind } from "../../types.js";
+import type { ResolverIssuingIdentity } from "./types.js";
+
+type ResolverChallengeBinding = {
+	readonly cacheable: boolean;
+	readonly identityBinding: "none" | "identity_scoped" | "portable";
+	readonly directCacheable: boolean;
+};
+
+// An IP-bound artifact minted without any recorded egress identity is unsafe to
+// share. The Akamai kinds therefore reject direct caching, while Cloudflare
+// keeps its pre-existing direct-cache behavior pending measurement.
+export const RESOLVER_CHALLENGE_BINDINGS = {
+	turnstile: { cacheable: false, identityBinding: "none", directCacheable: false },
+	recaptcha_v2: { cacheable: false, identityBinding: "none", directCacheable: false },
+	recaptcha_v3: { cacheable: false, identityBinding: "none", directCacheable: false },
+	hcaptcha: { cacheable: false, identityBinding: "none", directCacheable: false },
+	cloudflare_interstitial: {
+		cacheable: true,
+		identityBinding: "identity_scoped",
+		directCacheable: true,
+	},
+	aws_waf: { cacheable: true, identityBinding: "portable", directCacheable: true },
+	akamai_sec_cpt: {
+		cacheable: true,
+		identityBinding: "identity_scoped",
+		directCacheable: false,
+	},
+	akamai_sensor: {
+		cacheable: true,
+		identityBinding: "identity_scoped",
+		directCacheable: false,
+	},
+	akamai_sbsd: {
+		cacheable: false,
+		identityBinding: "identity_scoped",
+		directCacheable: false,
+	},
+} as const satisfies Readonly<Record<ProviderChallengeKind, ResolverChallengeBinding>>;
+
+export function resolverChallengeIsCacheable(challenge: ProviderChallenge): boolean {
+	return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].cacheable;
+}
+
+export function resolverChallengeAllowsDirectCache(challenge: ProviderChallenge): boolean {
+	return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].directCacheable;
+}
+
+export function resolverChallengeIsIdentityScoped(challenge: ProviderChallenge): boolean {
+	return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "identity_scoped";
+}
+
+export function resolverChallengeIssuingIdentity(
+	challenge: ProviderChallenge,
+	identity: ResolverIssuingIdentity,
+): ResolverIssuingIdentity {
+	if (RESOLVER_CHALLENGE_BINDINGS[challenge.kind].identityBinding === "portable") {
+		return { userAgent: identity.userAgent };
+	}
+	return identity;
+}