@apifuse/provider-sdk 2.2.0-beta.23 → 2.2.0-beta.25

package/src/define.ts

@@ -20,21 +20,24 @@ import type {
 	HealthJourneySchedule,
 	HealthScheduleRandomization,
 	InferSchemaOutput,
+	NativeProviderConfig,
 	OperationDefinition,
 	OperationHandlerResult,
 	OperationHttpStreamTransport,
 	OperationSseTransport,
 	OperationTransport,
 	OperationWebSocketTransport,
-	NativeProviderConfig,
-	ProviderOcrConfig,
 	ProviderAccessConfig,
+	ProviderChallengeKind,
 	ProviderDefinition,
+	ProviderOcrConfig,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
 	ProviderProxyConfig,
 	ProviderProxyProvider,
 	ProviderPublicProfile,
+	ProviderResolverConfig,
+	ProviderResolverVendor,
 	ProviderReviewed,
 	ProviderSecretDeclaration,
 	ProviderStreamEvent,
@@ -126,6 +129,30 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ] as const;
 const VALID_PROVIDER_OCR_MODES = ["optional", "required"] as const;
 const VALID_PROVIDER_STT_MODES = ["optional", "required"] as const;
+function exhaustiveLiteralArray<TUnion extends string>() {
+	return <const TValues extends readonly TUnion[]>(
+		values: TValues,
+		..._missing: Exclude<TUnion, TValues[number]> extends never
+			? []
+			: ["Missing runtime values", Exclude<TUnion, TValues[number]>]
+	): TValues => values;
+}
+
+export const VALID_PROVIDER_RESOLVER_VENDORS = exhaustiveLiteralArray<ProviderResolverVendor>()([
+	"browser",
+	"capsolver",
+	"capmonster",
+	"2captcha",
+	"custom",
+] as const);
+export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderChallengeKind>()([
+	"turnstile",
+	"recaptcha_v2",
+	"recaptcha_v3",
+	"hcaptcha",
+	"cloudflare_interstitial",
+	"aws_waf",
+] as const);
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
 const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
@@ -134,9 +161,8 @@ const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
 // credential fails at build/validation time rather than during a live outage: a
 // declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
 // exactly the failure class the multi-vendor chain exists to remove. Vendors
-// absent from this map (e.g. `custom`/`decodo`, whose credentials come from the
-// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) impose
-// no declaration requirement.
+// absent from this map (the deprecated `custom`/`decodo` values have no managed
+// adapter) impose no declaration requirement.
 const VENDOR_REQUIRED_SECRETS: Partial<Record<ProviderProxyProvider, readonly string[]>> = {
 	smartproxy: [SMARTPROXY_APP_KEY_SECRET],
 	nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
@@ -252,6 +278,7 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	proxy?: ProviderProxyConfig;
 	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
+	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
 	reviewed?: ProviderReviewed;
@@ -681,9 +708,21 @@ function validateProviderProxy(config: {
 	const deprecatedVendors = vendorChain.filter(
 		(vendor) => vendor === "decodo" || vendor === "custom",
 	);
+	if (
+		proxy.mode === "required" &&
+		vendorChain.length > 0 &&
+		deprecatedVendors.length === vendorChain.length
+	) {
+		throw new ValidationError(
+			`Provider "${config.id}" requires proxy egress but declares only deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}.`,
+			{
+				fix: `Use proxy.provider or proxy.providers with "smartproxy" and/or "nodemaven".`,
+			},
+		);
+	}
 	if (deprecatedVendors.length > 0) {
 		console.warn(
-			`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven", or the APIFUSE__PROXY__URL bring-your-own escape hatch.`,
+			`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven".`,
 		);
 	}
 }
@@ -712,6 +751,53 @@ function validateProviderOcr(config: { id: string; ocr?: ProviderOcrConfig }): v
 	assertLiteralField(ocr.mode, "ocr.mode", VALID_PROVIDER_OCR_MODES, config.id);
 }
 
+function validateProviderResolver(config: { id: string; resolver?: ProviderResolverConfig }): void {
+	const resolver = config.resolver;
+	if (resolver === undefined) return;
+	if (!resolver || typeof resolver !== "object" || Array.isArray(resolver)) {
+		throw new ValidationError(`Provider "${config.id}" has invalid resolver: must be an object.`, {
+			fix: `Set resolver for provider "${config.id}" to { vendors: ["2captcha"], kinds: ["turnstile"] }.`,
+		});
+	}
+	rejectUnknownFields(resolver, new Set(["vendors", "kinds"]), "resolver", config.id);
+	validateResolverLiteralArray(
+		resolver.vendors,
+		"resolver.vendors",
+		VALID_PROVIDER_RESOLVER_VENDORS,
+		config.id,
+	);
+	validateResolverLiteralArray(
+		resolver.kinds,
+		"resolver.kinds",
+		VALID_PROVIDER_CHALLENGE_KINDS,
+		config.id,
+	);
+}
+
+function validateResolverLiteralArray<TValue extends string>(
+	value: readonly TValue[],
+	field: string,
+	validValues: readonly TValue[],
+	providerId: string,
+): void {
+	if (!Array.isArray(value)) {
+		throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an array.`, {
+			fix: `Set ${field} for provider "${providerId}" to an array containing only: ${validValues.join(", ")}.`,
+		});
+	}
+	for (const [index, item] of value.entries()) {
+		if (typeof item === "string" && validValues.some((validValue) => validValue === item)) {
+			continue;
+		}
+		throw new ValidationError(
+			`Provider "${providerId}" has invalid ${field}[${index}]: ${JSON.stringify(item)}. Expected one of: ${validValues.join(", ")}`,
+			{
+				fix: `Set ${field}[${index}] for provider "${providerId}" to one of ${validValues.map((validValue) => `"${validValue}"`).join(", ")}.`,
+			},
+		);
+	}
+}
+
 function validateOperationIds(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
@@ -1309,7 +1395,12 @@ function suggestField(unknown: string, candidates: ReadonlySet<string>): string
 	return best;
 }
 
-function rejectUnknownFields(value: object, allowed: ReadonlySet<string>, fieldPath: string): void {
+function rejectUnknownFields(
+	value: object,
+	allowed: ReadonlySet<string>,
+	fieldPath: string,
+	providerId?: string,
+): void {
 	for (const key of Object.keys(value)) {
 		if (allowed.has(key)) continue;
 		const hint = suggestField(key, allowed);
@@ -1317,7 +1408,11 @@ function rejectUnknownFields(value: object, allowed: ReadonlySet<string>, fieldP
 			hint
 				? `Unknown field "${key}" on ${fieldPath}. Did you mean "${hint}"?`
 				: `Unknown field "${key}" on ${fieldPath}.`,
-			{ fix: `Remove ${fieldPath}.${key} or rename it.` },
+			{
+				fix: providerId
+					? `Remove ${fieldPath}.${key} from provider "${providerId}" or rename it.`
+					: `Remove ${fieldPath}.${key} or rename it.`,
+			},
 		);
 	}
 }
@@ -2403,6 +2498,7 @@ export function defineProvider<
 	validateProviderProxy(config);
 	validateProviderOcr(config);
 	validateProviderStt(config);
+	validateProviderResolver(config);
 	if (config.runtime === "browser" && !config.browser)
 		throw new ProviderError(
 			`Provider "${config.id}" must define browser.engine when runtime is "browser"`,
@@ -2428,6 +2524,7 @@ export function defineProvider<
 		proxy: config.proxy,
 		ocr: config.ocr,
 		stt: config.stt,
+		resolver: config.resolver,
 		browser: config.browser,
 		auth: config.auth,
 		reviewed: config.reviewed,

package/src/index.ts

@@ -6,7 +6,6 @@ export * from "./choice-token.js";
 export type {
 	ApiFuseConfig,
 	BrowserConfig,
-	ProxyConfig,
 	ProxyProtocol,
 	ProxyResolutionOptions,
 	ProxyResolutionSource,
@@ -53,6 +52,7 @@ export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
 export {
+	APIFUSE__CACHE__KEY_PEPPER_ENV,
 	createBypassProviderCache,
 	createProviderCache,
 	type ProviderCacheOptions,
@@ -101,6 +101,18 @@ export {
 } from "./runtime/instrumentation.js";
 export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export {
+	APIFUSE__CDP_POOL__URL,
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__TIMEOUT_MS,
+	createResolverClientFromEnv,
+	createUnsupportedResolverClient,
+	DEFAULT_RESOLVER_TIMEOUT_MS,
+	invalidateResolverSolution,
+	type ResolverRuntimeOptions,
+} from "./runtime/resolver.js";
 export {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -177,6 +189,7 @@ export type {
 	AuthMode,
 	AuthTurn,
 	Bcp47Locale,
+	BrowserCookie,
 	BrowserEngine,
 	BrowserOptions,
 	BrowserResourceBody,
@@ -185,6 +198,7 @@ export type {
 	BrowserResourcePolicy,
 	BrowserResourceRequest,
 	BrowserResourceRoute,
+	ChallengeSolution,
 	ConnectionMode,
 	ContextDeclaration,
 	CookieJar,
@@ -285,6 +299,8 @@ export type {
 	ProviderChoiceContext,
 	ProviderChoiceIssueOptions,
 	ProviderChoiceParseOptions,
+	ProviderChallenge,
+	ProviderChallengeKind,
 	ProviderContext,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
@@ -309,6 +325,8 @@ export type {
 	ProviderPublicProfile,
 	ProviderReviewed,
 	ProviderResolvedFile,
+	ProviderResolverConfig,
+	ProviderResolverVendor,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
 	ProviderStateDurationString,
@@ -319,6 +337,7 @@ export type {
 	ProviderSupportLevel,
 	RequestOptions,
 	RedirectRunReason,
+	ResolverContext,
 	Rfc3339Instant,
 	SchemaLike,
 	SmsOrigin,
@@ -328,6 +347,7 @@ export type {
 	StandardSchemaV1,
 	StateCasResult,
 	StateNamespaceOptions,
+	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
 	StealthClient,

package/src/provider.ts

@@ -162,6 +162,7 @@ export type {
 	StandardSchemaV1,
 	StateCasResult,
 	StateNamespaceOptions,
+	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
 } from "./types.js";

package/src/runtime/auth-flow.ts

@@ -10,6 +10,7 @@ import type {
 	SttContext,
 } from "../types.js";
 import { createUnsupportedOcrClient } from "./ocr.js";
+import { createUnsupportedResolverClient } from "./resolver.js";
 import { createUnsupportedSttClient } from "./stt.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
@@ -75,6 +76,7 @@ export function createFlowContext(options: {
 		context: createScratchpad(options.allowedKeys, options.initialContext),
 		ocr: options.ocr ?? createUnsupportedOcrClient(),
 		stt: options.stt ?? createUnsupportedSttClient(),
+		resolver: createUnsupportedResolverClient("Resolver is not available in auth flow context"),
 		auth: createAuthFlowHelpers(),
 	};
 }

package/src/runtime/browser.ts

@@ -6,6 +6,7 @@ import type {
 	BrowserChallengeRequest,
 	BrowserChallengeResult,
 	BrowserClient as BrowserClientContract,
+	BrowserCookie,
 	BrowserEngine,
 	BrowserFrame,
 	BrowserLocator,
@@ -545,6 +546,10 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 		await this.page.close();
 	}
 
+	async cookies(): Promise<readonly BrowserCookie[]> {
+		return (await this.page.context().cookies()).map(toBrowserCookie);
+	}
+
 	async withResourcePolicy<T>(policy: BrowserResourcePolicy, run: () => Promise<T>): Promise<T> {
 		const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
 		const handler = async (route: Route): Promise<void> => {
@@ -845,6 +850,64 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+function isBrowserCookieSameSite(value: unknown): value is BrowserCookie["sameSite"] {
+	return value === "Strict" || value === "Lax" || value === "None";
+}
+
+function toBrowserCookie(cookie: {
+	readonly name: string;
+	readonly value: string;
+	readonly domain: string;
+	readonly path: string;
+	readonly expires?: number;
+	readonly httpOnly: boolean;
+	readonly secure: boolean;
+	readonly sameSite?: unknown;
+}): BrowserCookie {
+	return {
+		name: cookie.name,
+		value: cookie.value,
+		domain: cookie.domain,
+		path: cookie.path,
+		...(cookie.expires !== undefined && cookie.expires > 0 ? { expires: cookie.expires } : {}),
+		httpOnly: cookie.httpOnly,
+		secure: cookie.secure,
+		...(isBrowserCookieSameSite(cookie.sameSite) ? { sameSite: cookie.sameSite } : {}),
+	};
+}
+
+function parseCdpCookies(value: unknown): readonly BrowserCookie[] {
+	if (!Array.isArray(value)) {
+		throw new Error("CDP Network.getCookies returned an invalid cookie list");
+	}
+
+	return value.map((cookie) => {
+		if (
+			!isRecord(cookie) ||
+			typeof cookie.name !== "string" ||
+			typeof cookie.value !== "string" ||
+			typeof cookie.domain !== "string" ||
+			typeof cookie.path !== "string" ||
+			typeof cookie.expires !== "number" ||
+			typeof cookie.httpOnly !== "boolean" ||
+			typeof cookie.secure !== "boolean"
+		) {
+			throw new Error("CDP Network.getCookies returned an invalid cookie");
+		}
+
+		return toBrowserCookie({
+			name: cookie.name,
+			value: cookie.value,
+			domain: cookie.domain,
+			path: cookie.path,
+			expires: cookie.expires,
+			httpOnly: cookie.httpOnly,
+			secure: cookie.secure,
+			sameSite: cookie.sameSite,
+		});
+	});
+}
+
 function parsePoolAcquireResponse(value: unknown): PoolAcquireResponse {
 	if (
 		!isRecord(value) ||
@@ -1200,6 +1263,12 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		return Buffer.from(String(result.data ?? ""), "base64");
 	}
 
+	async cookies(): Promise<readonly BrowserCookie[]> {
+		await this.initialize();
+		const result = await this.pageClient.send("Network.getCookies");
+		return parseCdpCookies(result.cookies);
+	}
+
 	async close(): Promise<void> {
 		if (this.closed) {
 			return;

package/src/runtime/cache.ts

@@ -1,6 +1,7 @@
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 
 import { providerCacheRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
 import type {
 	ProviderCache,
 	ProviderCacheGetOrSetOptions,
@@ -43,9 +44,12 @@ export type ProviderCacheOptions = {
 	now?: () => number;
 };
 
+export const APIFUSE__CACHE__KEY_PEPPER_ENV = "APIFUSE__CACHE__KEY_PEPPER";
+
 const DEFAULT_PREFIX = "apifuse:provider-cache:v1";
 const DEFAULT_MEMORY_MAX_ENTRIES = 1_000;
 const DEFAULT_REDIS_TIMEOUT_MS = 150;
+const SECRET_SCOPED_KEY_MARKER = "[secret-scoped";
 const SECRET_FIELD_NAMES = new Set([
 	"authorization",
 	"cookie",
@@ -61,6 +65,7 @@ const SECRET_FIELD_NAMES = new Set([
 ]);
 
 const sharedBackends = new Map<string, SharedCacheBackend>();
+let warnedAboutUnpepperedSecretKeys = false;
 
 function backendKey(redisUrl: string | undefined): string {
 	return redisUrl ?? "memory";
@@ -107,19 +112,178 @@ function shouldRedactField(name: string, extra: Set<string>): boolean {
 	);
 }
 
-function normalizeKeyPart(value: unknown, extra: Set<string>): unknown {
+type NormalizedKeyPart = {
+	value: unknown;
+	secretScoped: boolean;
+};
+
+function unsupportedSecretValue(path: string, reason: string): never {
+	throw new ProviderError(`Secret cache-key values must be JSON-safe; ${reason} at ${path}.`, {
+		code: "CACHE_KEY_SECRET_VALUE_UNSUPPORTED",
+		fix: "Convert the secret cache-key selector to JSON-safe primitives, arrays, or plain objects.",
+	});
+}
+
+function assertJsonSafeSecretValue(
+	value: unknown,
+	reportedPath: string,
+	ancestors = new Set<object>(),
+): void {
+	if (value === undefined) return;
+	if (value === null || typeof value === "string" || typeof value === "boolean") return;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value))
+			unsupportedSecretValue(reportedPath, "non-finite numbers are unsupported");
+		if (Object.is(value, -0))
+			unsupportedSecretValue(reportedPath, "negative zero is unsupported");
+		return;
+	}
+	if (typeof value !== "object") {
+		unsupportedSecretValue(reportedPath, `${typeof value} values are unsupported`);
+	}
+	if (ancestors.has(value))
+		unsupportedSecretValue(reportedPath, "cyclic values are unsupported");
+
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			if (Object.getOwnPropertySymbols(value).length > 0) {
+				unsupportedSecretValue(reportedPath, "symbol-keyed array properties are unsupported");
+			}
+			const expectedNames = new Set(["length"]);
+			for (let index = 0; index < value.length; index += 1) {
+				const key = String(index);
+				expectedNames.add(key);
+				const descriptor = Object.getOwnPropertyDescriptor(value, key);
+				if (!descriptor)
+					unsupportedSecretValue(reportedPath, "sparse arrays are unsupported");
+				if (!descriptor.enumerable || !("value" in descriptor)) {
+					unsupportedSecretValue(reportedPath, "array accessors are unsupported");
+				}
+				assertJsonSafeSecretValue(descriptor.value, reportedPath, ancestors);
+			}
+			if (Object.getOwnPropertyNames(value).some((name) => !expectedNames.has(name))) {
+				unsupportedSecretValue(reportedPath, "custom array properties are unsupported");
+			}
+			return;
+		}
+
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) {
+			unsupportedSecretValue(reportedPath, "non-plain objects are unsupported");
+		}
+		if (Object.getOwnPropertySymbols(value).length > 0) {
+			unsupportedSecretValue(reportedPath, "symbol-keyed properties are unsupported");
+		}
+		for (const key of Object.getOwnPropertyNames(value)) {
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			if (!descriptor?.enumerable || !("value" in descriptor)) {
+				unsupportedSecretValue(
+					reportedPath,
+					"non-enumerable properties and accessors are unsupported",
+				);
+			}
+			assertJsonSafeSecretValue(descriptor.value, reportedPath, ancestors);
+		}
+	} finally {
+		ancestors.delete(value);
+	}
+}
+
+function containsUndefined(value: unknown): boolean {
+	if (value === undefined) return true;
+	if (Array.isArray(value)) return value.some(containsUndefined);
+	if (isRecord(value)) return Object.values(value).some(containsUndefined);
+	return false;
+}
+
+function tagSecretValue(value: unknown): unknown {
+	if (value === undefined) return ["undefined"];
+	if (value === null) return ["null"];
+	if (typeof value === "string") return ["string", value];
+	if (typeof value === "number") return ["number", value];
+	if (typeof value === "boolean") return ["boolean", value];
+	if (Array.isArray(value)) return ["array", value.map(tagSecretValue)];
+	return [
+		"object",
+		Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+			key,
+			tagSecretValue(entry),
+		]),
+	];
+}
+
+function serializeSecretValue(value: unknown): string {
+	if (!containsUndefined(value)) return JSON.stringify([value]);
+	return `undefined-v1:${JSON.stringify(tagSecretValue(value))}`;
+}
+
+function warnAboutUnpepperedSecretKey(): void {
+	if (warnedAboutUnpepperedSecretKeys) return;
+	warnedAboutUnpepperedSecretKeys = true;
+	console.warn(
+		JSON.stringify({
+			level: "warn",
+			event: "provider_cache_secret_key_unpeppered",
+			message: `Secret-bearing cache keys are using unkeyed SHA-256 because ${APIFUSE__CACHE__KEY_PEPPER_ENV} is not configured.`,
+		}),
+	);
+}
+
+function normalizeKeyPart(
+	value: unknown,
+	extra: Set<string>,
+	pepper: string | undefined,
+): NormalizedKeyPart {
 	if (Array.isArray(value)) {
-		return value.map((entry) => normalizeKeyPart(entry, extra));
+		const entries = value.map((entry) => normalizeKeyPart(entry, extra, pepper));
+		return {
+			value: entries.map((entry) => entry.value),
+			secretScoped: entries.some((entry) => entry.secretScoped),
+		};
 	}
 	if (isRecord(value)) {
-		const normalized: Record<string, unknown> = {};
+		const normalized: Record<string, unknown> = Object.create(null);
+		let secretScoped = false;
 		for (const key of Object.keys(value).sort()) {
-			if (shouldRedactField(key, extra)) continue;
-			normalized[key] = normalizeKeyPart(value[key], extra);
+			const part = shouldRedactField(key, extra)
+				? hashSecretValue(value[key], key, extra, pepper)
+				: normalizeKeyPart(value[key], extra, pepper);
+			normalized[key] = part.value;
+			secretScoped ||= part.secretScoped;
 		}
-		return normalized;
+		return { value: normalized, secretScoped };
+	}
+	return { value, secretScoped: false };
+}
+
+function hashSecretValue(
+	value: unknown,
+	fieldName: string,
+	extra: Set<string>,
+	pepper: string | undefined,
+): NormalizedKeyPart {
+	assertJsonSafeSecretValue(value, `${fieldName} (inside secret value)`);
+	const canonical = serializeSecretValue(normalizeKeyPart(value, extra, pepper).value);
+	if (pepper === undefined) {
+		warnAboutUnpepperedSecretKey();
+		const digest = createHash("sha256").update(canonical).digest("hex");
+		return { value: `sha256:${digest}`, secretScoped: true };
 	}
-	return value;
+	const digest = createHmac("sha256", pepper).update(canonical).digest("hex");
+	return { value: `hmac-sha256:${digest}`, secretScoped: true };
+}
+
+function metadataKeys(
+	events: ProviderCacheLookupMeta[],
+	secretScopedKeys: Set<string>,
+): string[] {
+	let secretScopedIndex = 0;
+	return Array.from(new Set(events.map((event) => event.key))).map((key) => {
+		if (!secretScopedKeys.has(key)) return key;
+		secretScopedIndex += 1;
+		return `${SECRET_SCOPED_KEY_MARKER}#${secretScopedIndex}]`;
+	});
 }
 
 function stableHash(value: unknown): string {
@@ -198,10 +362,13 @@ async function withRedisFallback<T>(operation: () => Promise<T>): Promise<T | un
 
 export function createProviderCache(options: ProviderCacheOptions): ProviderCache {
 	const redisUrl = options.redisUrl ?? providerCacheRedisUrlFromEnv();
+	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
 	const backend = getSharedBackend(redisUrl);
 	const memoryMaxEntries = Math.max(1, options.memoryMaxEntries ?? DEFAULT_MEMORY_MAX_ENTRIES);
 	const now = options.now ?? Date.now;
 	const events: ProviderCacheLookupMeta[] = [];
+	const secretScopedKeys = new Set<string>();
 
 	function record(meta: ProviderCacheLookupMeta): void {
 		events.push(meta);
@@ -353,8 +520,10 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 	return {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
-			const normalized = normalizeKeyPart(parts, extra);
-			return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+			const normalized = normalizeKeyPart(parts, extra, pepper);
+			const key = `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized.value)}`;
+			if (normalized.secretScoped) secretScopedKeys.add(key);
+			return key;
 		},
 
 		async get<T = unknown>(key: string): Promise<ProviderCacheResult<T> | null> {
@@ -413,7 +582,7 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 			return {
 				hit: events.some((event) => event.hit),
 				stale: events.some((event) => event.stale),
-				keys: Array.from(new Set(events.map((event) => event.key))),
+				keys: metadataKeys(events, secretScopedKeys),
 				source: sourceSummary(events),
 			};
 		},
@@ -423,13 +592,18 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 export function createBypassProviderCache(
 	options: Pick<ProviderCacheOptions, "providerId">,
 ): ProviderCache {
+	const configuredPepper = process.env[APIFUSE__CACHE__KEY_PEPPER_ENV];
+	const pepper = configuredPepper && configuredPepper.length > 0 ? configuredPepper : undefined;
 	const events: ProviderCacheLookupMeta[] = [];
+	const secretScopedKeys = new Set<string>();
 
 	return {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
-			const normalized = normalizeKeyPart(parts, extra);
-			return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+			const normalized = normalizeKeyPart(parts, extra, pepper);
+			const key = `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized.value)}`;
+			if (normalized.secretScoped) secretScopedKeys.add(key);
+			return key;
 		},
 
 		async get<T = unknown>(_key: string): Promise<ProviderCacheResult<T> | null> {
@@ -464,7 +638,7 @@ export function createBypassProviderCache(
 			return {
 				hit: false,
 				stale: false,
-				keys: Array.from(new Set(events.map((event) => event.key))),
+				keys: metadataKeys(events, secretScopedKeys),
 				source: sourceSummary(events),
 			};
 		},
@@ -478,4 +652,5 @@ export function resetProviderCacheForTests(): void {
 		backend.redis?.disconnect();
 	}
 	sharedBackends.clear();
+	warnedAboutUnpepperedSecretKeys = false;
 }

package/src/runtime/http.ts

@@ -517,7 +517,6 @@ async function resolveNativeProxy(
 	const resolvedProxy = await resolveProxyConfigAsync({
 		proxy: options.proxy ?? clientOptions.proxy,
 		upstream: clientOptions.upstream,
-		apifuseConfig: clientOptions.apifuseConfig,
 		proxyPolicy: clientOptions.proxyPolicy,
 		affinityKey: clientOptions.affinityKey,
 		proxyAttempt: computeProxyAttemptIndex({