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

package/src/runtime/diagnostic-redactor.ts

@@ -6,6 +6,7 @@ import {
 	REDACTED_QUERY_VALUE,
 	type SensitiveValueVariant,
 } from "./request-options.js";
+import { RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES } from "./resolver-span-attributes.js";
 
 export type DiagnosticRedactor = (text: string) => string;
 export const REDACTION_FAILED = "[REDACTION_FAILED]";
@@ -577,11 +578,19 @@ export function redactDiagnosticAttributeKey(key: string, redact?: DiagnosticRed
 export function redactCriticalDiagnosticText(text: string, redact?: DiagnosticRedactor): string {
 	return redactDiagnosticText(text, redact ? (criticalRedactors.get(redact) ?? redact) : undefined);
 }
+/**
+ * The redactor for one attribute value. A value its producer declares as a closed-enum literal for
+ * this key is a contract, like a typed number: exhaustion suppression skips it, while registered
+ * credentials still match. Any other value under the same key stays free text.
+ */
 export function diagnosticAttributeRedactor(
 	key: string,
 	redact?: DiagnosticRedactor,
+	value?: unknown,
 ): DiagnosticRedactor | undefined {
-	if (CLOSED_ENUM_ATTRIBUTE_KEYS.has(key)) return diagnosticStructuredRedactor(redact);
+	if (typeof value === "string" && CLOSED_ENUM_ATTRIBUTE_VALUES.get(key)?.has(value)) {
+		return diagnosticStructuredRedactor(redact);
+	}
 	return CRITICAL_ATTRIBUTE_KEYS.has(key) && redact
 		? (criticalRedactors.get(redact) ?? redact)
 		: redact;
@@ -600,18 +609,15 @@ const CRITICAL_ATTRIBUTE_KEYS = new Set([
 	"http.status_code",
 ]);
 
-// SDK-owned closed enums are contracts, like typed numbers and booleans. This
-// exempts only exhaustion suppression; registered credentials still match.
-const CLOSED_ENUM_ATTRIBUTE_KEYS = new Set([
-	"outcome",
-	"code",
-	"errorClass",
-	"phase",
-	"cacheStatus",
-	"identitySource",
-	"taxonomy",
-	"taxonomyVersion",
-]);
+// SDK-owned closed enums are contracts, like typed numbers and booleans. The table is the
+// producers' own declaration of which span attributes are closed enums and of every literal each
+// one can carry; it exempts only exhaustion suppression, and registered credentials still match.
+const CLOSED_ENUM_ATTRIBUTE_VALUES: ReadonlyMap<string, ReadonlySet<string>> = new Map(
+	Object.entries(RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES).map(([key, values]) => [
+		key,
+		new Set<string>(values),
+	]),
+);
 
 // Bigints normalize to strings for OTLP. Carry their type policy through internal
 // detached copies without treating arbitrary numeric-looking free text as typed.

package/src/runtime/executor.ts

@@ -39,6 +39,9 @@ export async function executeOperation<
 	if (!operation) {
 		throw new ProviderError(`Unknown operation: ${provider.id}/${operationId}`, {
 			code: "NOT_FOUND",
+			// No upstream was asked: keep the registered NOT_FOUND code from
+			// attributing this to one.
+			category: "provider_error",
 			fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
 		});
 	}

package/src/runtime/http.ts

@@ -4,7 +4,7 @@ import {
 	resolvePolicyTransportAttemptCap,
 	resolveProxyConfigAsync,
 } from "../config/loader.js";
-import { HttpRedirectError, ProviderError, TransportError } from "../errors.js";
+import { ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import type {
 	HttpAttemptContext,
@@ -36,7 +36,13 @@ import {
 	type HttpTelemetrySink,
 	type HttpAttemptTelemetryEvent,
 } from "./http-telemetry.js";
-import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl } from "./redirects.js";
+import {
+	invalidRedirectPolicy,
+	isRedirectStatus,
+	nextSameOriginRedirectHop,
+	normalizeRedirectPolicy,
+	type RedirectPolicyTransport,
+} from "./redirects.js";
 import {
 	normalizeHttpRequestBody,
 	redactSensitiveError,
@@ -578,7 +584,8 @@ function normalizeHttpMethod(method: string): Uppercase<HttpMethod> {
 	}
 }
 
-function isAbsoluteUrl(url: string): boolean {
+/** Whether `url` carries its own scheme, so it needs no `upstream.baseUrl` to resolve. */
+export function isAbsoluteUrl(url: string): boolean {
 	return /^[a-z][a-z\d+\-.]*:/i.test(url);
 }
 
@@ -589,74 +596,24 @@ function resolveHttpUrl(baseUrl: string | undefined, url: string): string {
 type NativeFetchInit = RequestInit & { proxy?: string };
 
 const MAX_HTTP_REDIRECT_HOPS = 20;
-const HTTP_REDIRECT_POLICY_FIELDS = new Set(["mode", "maxHops"]);
+const HTTP_REDIRECT_POLICY_TRANSPORT: RedirectPolicyTransport = {
+	label: "ctx.http",
+	maxHops: MAX_HTTP_REDIRECT_HOPS,
+};
 const REDIRECT_BODY_HEADERS = new Set([
 	"content-encoding",
 	"content-language",
 	"content-location",
 	"content-type",
 ]);
-const MALFORMED_REDIRECT_TARGET = "[malformed redirect target]";
-
-function invalidHttpRedirectPolicy(message: string, cause?: Error): TransportError {
-	return new TransportError(`Invalid ctx.http redirectPolicy: ${message}`, {
-		code: "http_redirect_policy_invalid",
-		...(cause ? { cause } : {}),
-	});
-}
-
-/** Snapshot untrusted caller input synchronously, before proxy resolution or fetch. */
-function normalizeHttpRedirectPolicy(value: unknown): HttpRedirectPolicy | undefined {
-	if (value === undefined) return undefined;
-	if (value === null || typeof value !== "object" || Array.isArray(value)) {
-		throw invalidHttpRedirectPolicy("expected an object");
-	}
-
-	try {
-		const keys = Reflect.ownKeys(value);
-		for (const key of keys) {
-			if (typeof key !== "string" || !HTTP_REDIRECT_POLICY_FIELDS.has(key)) {
-				throw invalidHttpRedirectPolicy(`unknown field ${String(key)}`);
-			}
-		}
-		for (const field of HTTP_REDIRECT_POLICY_FIELDS) {
-			const descriptor = Object.getOwnPropertyDescriptor(value, field);
-			if (!descriptor || !("value" in descriptor)) {
-				throw invalidHttpRedirectPolicy(`${field} must be an own data property`);
-			}
-		}
-
-		const record = value as Record<string, unknown>;
-		if (record.mode !== "same-origin") {
-			throw invalidHttpRedirectPolicy('mode must be "same-origin"');
-		}
-		if (
-			typeof record.maxHops !== "number" ||
-			!Number.isInteger(record.maxHops) ||
-			record.maxHops < 0 ||
-			record.maxHops > MAX_HTTP_REDIRECT_HOPS
-		) {
-			throw invalidHttpRedirectPolicy(
-				`maxHops must be an integer from 0 to ${MAX_HTTP_REDIRECT_HOPS}`,
-			);
-		}
-
-		return { mode: "same-origin", maxHops: record.maxHops };
-	} catch (error) {
-		if (error instanceof TransportError) throw error;
-		throw invalidHttpRedirectPolicy(
-			"could not be inspected safely",
-			error instanceof Error ? error : undefined,
-		);
-	}
-}
 
 function snapshotHttpRedirectPolicy(options: RequestOptions): HttpRedirectPolicy | undefined {
 	try {
-		return normalizeHttpRedirectPolicy(options.redirectPolicy);
+		return normalizeRedirectPolicy(options.redirectPolicy, HTTP_REDIRECT_POLICY_TRANSPORT);
 	} catch (error) {
 		if (error instanceof TransportError) throw error;
-		throw invalidHttpRedirectPolicy(
+		throw invalidRedirectPolicy(
+			HTTP_REDIRECT_POLICY_TRANSPORT,
 			"could not be read safely",
 			error instanceof Error ? error : undefined,
 		);
@@ -669,21 +626,6 @@ function withoutRedirectBodyHeaders(headers: HeadersInit | undefined): Headers {
 	return nextHeaders;
 }
 
-function redirectDiagnosticTarget(value: string): string {
-	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;
-	}
-}
-
 function discardRedirectResponseBody(response: Response): void {
 	try {
 		const cancellation = response.body?.cancel();
@@ -729,47 +671,17 @@ async function fetchWithHttpRedirectPolicy(
 
 		const location = response.headers.get("location");
 		discardRedirectResponseBody(response);
-		let nextUrlString: string | undefined;
-		try {
-			nextUrlString = resolveRedirectUrl(location || undefined, currentUrl);
-		} catch {
-			const target = MALFORMED_REDIRECT_TARGET;
-			throw new HttpRedirectError(`Redirect response has malformed Location target ${target}`, {
-				reason: "missing_location",
-				target,
-				status: response.status,
-			});
-		}
-
-		const decision = evaluateRedirectHop({
+		const decision = nextSameOriginRedirectHop({
+			policy,
+			initialOrigin,
+			currentUrl,
+			responseUrl: currentUrl,
 			status: response.status,
 			method,
-			nextUrl: nextUrlString,
-			shouldStop: nextUrlString ? new URL(nextUrlString).origin !== initialOrigin : false,
-			redirectCount: followedHops + 1,
-			maxHops: policy.maxHops,
+			location: location ?? undefined,
+			followedHops,
 			visitedRequests,
 		});
-		if (decision.kind === "stop") {
-			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(currentUrl)} is missing Location`;
-				}
-			})();
-			throw new HttpRedirectError(message, {
-				reason: decision.reason,
-				...(target ? { target } : {}),
-				status: response.status,
-			});
-		}
 		if (decision.nextMethod !== method) {
 			body = undefined;
 			headers = withoutRedirectBodyHeaders(headers);

package/src/runtime/instrumentation.ts

@@ -26,6 +26,7 @@ import {
 	type TraceContext,
 } from "./trace.js";
 import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 
 export interface InstrumentationOptions extends CreateTraceContextOptions {}
 
@@ -707,7 +708,9 @@ function wrapNamespace<T extends object>(
 						"resolver.solve",
 						() => Reflect.apply(value, namespaceTarget, [args[0], args[1], recorder]),
 						{
-							attributes: challengeKind ? { challenge_kind: challengeKind } : undefined,
+							attributes: challengeKind
+								? resolverSpanAttributes({ challenge_kind: challengeKind })
+								: undefined,
 						},
 					);
 				};

package/src/runtime/provider.ts

@@ -13,3 +13,18 @@ export function getProviderBaseUrl(provider: ProviderDefinition): string | undef
 
 	return undefined;
 }
+
+/**
+ * The base `ctx.stealth` resolves relative request URLs (and seeds its cookie
+ * jar's default origin) against: the provider's first declared
+ * `upstream.baseUrl`, else `https://<allowedHosts[0]>`. `undefined` means the
+ * provider declares neither, and `serve` binds no stealth transport at all.
+ */
+export function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undefined {
+	const baseUrl = getProviderBaseUrl(provider);
+	if (baseUrl) {
+		return baseUrl;
+	}
+	const firstHost = provider.allowedHosts?.[0];
+	return firstHost ? `https://${firstHost}` : undefined;
+}

package/src/runtime/redirect-hop-headers.ts

@@ -0,0 +1,71 @@
+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: ReadonlySet<string> = 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: ReadonlySet<string> = new Set([
+	"authorization",
+	"proxy-authorization",
+]);
+
+/** One redirect hop: the URL the headers were sent to, and the next request. */
+export interface RedirectHop {
+	readonly from: string;
+	readonly to: string;
+	readonly methodChanged: boolean;
+}
+
+/**
+ * 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: URL): string {
+	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<T>(
+	hop: RedirectHop,
+	headers: Readonly<Record<string, T>>,
+): Record<string, T> {
+	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/src/runtime/redirects.ts

@@ -1,4 +1,5 @@
-import type { HttpRedirectFailureReason } from "../types.js";
+import { HttpRedirectError, TransportError } from "../errors.js";
+import type { HttpRedirectFailureReason, HttpRedirectPolicy } from "../types.js";
 
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 
@@ -64,3 +65,151 @@ export function evaluateRedirectHop<TMethod extends string>(input: {
 	}
 	return { kind: "follow", nextMethod, nextUrl: input.nextUrl };
 }
+
+const REDIRECT_POLICY_FIELDS = new Set(["mode", "maxHops"]);
+export 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 function invalidRedirectPolicy(
+	transport: RedirectPolicyTransport,
+	message: string,
+	cause?: Error,
+): TransportError {
+	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: unknown,
+	transport: RedirectPolicyTransport,
+): HttpRedirectPolicy | undefined {
+	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 as Record<string, unknown>;
+		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: string): string {
+	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<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 } {
+	let nextUrl: string | undefined;
+	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/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;
+}