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

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;
+}

package/src/runtime/resolver-usage.ts

@@ -4,6 +4,7 @@ import type {
 	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";
 
@@ -22,9 +23,11 @@ export type ResolverPaidUsageEndpoint =
  * 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: "metered" | "unconfirmed" }
+	{ readonly billable_units: 0 | 1; readonly billing: ResolverPaidUsageBilling }
 > = {
 	"capsolver:create_task": { billable_units: 1, billing: "metered" },
 	"twocaptcha:create_task": { billable_units: 1, billing: "metered" },
@@ -78,7 +81,7 @@ export async function recordPaidResolverCreate<T>(options: {
 		}
 		return options.create();
 	}
-	const baseAttributes = {
+	const baseAttributes = resolverSpanAttributes({
 		vendor: options.vendor,
 		challenge_kind: options.kind,
 		endpoint: options.endpoint,
@@ -87,10 +90,10 @@ export async function recordPaidResolverCreate<T>(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/src/runtime/resolver-vendors/browser.ts

@@ -8,6 +8,7 @@ import type {
 } from "../../types.js";
 import { type BrowserClientOptions, createBrowserClient } from "../browser.js";
 import type { TraceRecorder } from "../trace.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import type { BrowserTelemetrySink } from "../browser-telemetry.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
 import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
@@ -218,15 +219,15 @@ async function runBoundedCleanup(
 
 	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/src/runtime/resolver-vendors/capsolver.ts

@@ -3,6 +3,7 @@ import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind } from
 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 type { TraceRecorder } from "../trace.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import {
@@ -413,7 +414,7 @@ function spanErrorAttributes(
 	phase: CapsolverOperationPhase,
 ): Record<string, unknown> | undefined {
 	if (error instanceof ResolverVendorUnavailableError) {
-		return {
+		return resolverSpanAttributes({
 			unavailability_reason: error.reason,
 			transport_phase: error.phase,
 			...(error instanceof CapsolverUnavailableError
@@ -425,21 +426,21 @@ function spanErrorAttributes(
 						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;
 }
@@ -606,10 +607,10 @@ export function createCapsolverResolverVendorAdapter(
 				};
 				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();
@@ -689,10 +690,10 @@ export function createCapsolverResolverVendorAdapter(
 				};
 				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/src/runtime/resolver-vendors/twocaptcha.ts

@@ -1,6 +1,7 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
 import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import {
 	type ResolverIdentity,
@@ -300,19 +301,19 @@ function spanErrorAttributes(
 	phase: TwoCaptchaOperationPhase,
 ): Record<string, unknown> | undefined {
 	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;
 }
@@ -468,10 +469,10 @@ export function createTwoCaptchaResolverVendorAdapter(
 				};
 				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();
@@ -517,10 +518,10 @@ export function createTwoCaptchaResolverVendorAdapter(
 				};
 				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/src/runtime/resolver.ts

@@ -64,6 +64,7 @@ import {
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 	kindRequiresClientProfile,
 } from "./resolver-config.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 import type { TraceRecorder } from "./trace.js";
 import type { BrowserTelemetrySink } from "./browser-telemetry.js";
@@ -595,7 +596,7 @@ function unavailableAttempt(
 
 function unavailableSpanAttributes(error: ResolverVendorUnavailableError): Record<string, unknown> {
 	const attempt = unavailableAttempt(error);
-	return {
+	return resolverSpanAttributes({
 		unavailability_reason: error.reason,
 		missing_fields: error.missingFields,
 		cause_name: attempt.cause?.name,
@@ -603,7 +604,7 @@ function unavailableSpanAttributes(error: ResolverVendorUnavailableError): Recor
 		upstream_host: attempt.upstreamHost,
 		transport_phase: attempt.phase,
 		transport_round: attempt.round,
-	};
+	});
 }
 
 type ResolverAttemptDiagnostics = {
@@ -994,8 +995,8 @@ async function invalidateResolverSolutionWithOutcome(
 		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 }),
 	});
 }
 
@@ -1257,12 +1258,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/src/runtime/stealth-owned-headers.ts

@@ -1,20 +1,28 @@
+import { SDKError } from "../errors.js";
+
 /**
  * Header names the stealth transport owns.
  *
  * `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 const SDK_OWNED_EXACT_CHROME_HEADERS: ReadonlySet<string> = new Set([
 	"host",
@@ -39,3 +47,21 @@ export function isStealthOwnedHeaderName(name: string): boolean {
 		SDK_OWNED_EXACT_CHROME_HEADERS.has(lower) || lower.startsWith(SDK_OWNED_CHROME_HEADER_PREFIX)
 	);
 }
+
+/**
+ * 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 function assertCallerHeadersSupported(
+	headers: Readonly<Record<string, string | readonly string[] | undefined>>,
+): void {
+	for (const [name, value] of Object.entries(headers)) {
+		if (value === undefined || !isStealthOwnedHeaderName(name)) continue;
+		throw new SDKError(
+			`Stealth transport owns the "${name.toLowerCase()}" header; remove it from headers.`,
+			{ code: "STEALTH_HEADER_OVERRIDE_UNSUPPORTED" },
+		);
+	}
+}

package/src/runtime/stealth-telemetry.ts

@@ -22,7 +22,12 @@ export type StealthTelemetryErrorCode =
 	| "PROXY_REQUIRED"
 	| "other";
 
-export type StealthTelemetryRequestClass = "navigation" | "script_navigation" | "xhr" | "post";
+export type StealthTelemetryRequestClass =
+	| "navigation"
+	| "script_navigation"
+	| "form_post"
+	| "xhr"
+	| "post";
 
 export type StealthTelemetryAttemptKind = "request" | "resolver" | "proxy_diagnostic";