@apifuse/provider-sdk 2.2.0-beta.58 → 2.2.0-beta.60

package/src/runtime/egress-lease.ts

@@ -0,0 +1,341 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+
+import type { ProxyVendorName } from "../config/loader.js";
+import { SDKError } from "../errors.js";
+
+/**
+ * AES-256-GCM key for the engine ceremony egress lease handle (ADR-0010 v1.1).
+ * Engine host only: the `APIFUSE__ENGINE__` family is rejected from provider
+ * secrets and filtered from provider env projections. Supply at least 32 random
+ * bytes (for example `openssl rand -base64 32`). Rotating the key fails
+ * verification of every outstanding handle (`EGRESS_LEASE_INVALID`, 409): the
+ * affected ceremonies restart; they do not expire.
+ */
+export const APIFUSE__ENGINE__CEREMONY_LEASE_KEY = "APIFUSE__ENGINE__CEREMONY_LEASE_KEY";
+
+/** Internal option key shared only by the server assembler and stealth runtime. */
+export const ENGINE_CEREMONY_EGRESS_LEASE = Symbol.for(
+	"@apifuse/provider-sdk/engine-ceremony-egress-lease",
+);
+
+const HANDLE_VERSION = 1;
+const HANDLE_MAX_BYTES = 16_384;
+const AEAD_NONCE_BYTES = 12;
+const AEAD_TAG_BYTES = 16;
+const AEAD_ALGORITHM = "aes-256-gcm";
+const AEAD_KEY_DOMAIN = "apifuse:ceremony-egress-lease:v1\0";
+const LEASE_KEY_MIN_BYTES = 32;
+
+export type CeremonyEgressBinding = {
+	readonly vendor: ProxyVendorName;
+	readonly proxyUrl: string;
+	readonly poolIndex: number;
+	readonly affinityKey: string;
+	readonly refreshEpoch: number;
+	/**
+	 * Vendor session lifetime the endpoint was allocated for (`proxy.session.lifetimeMinutes`,
+	 * Smartproxy `life`, NodeMaven SID window). It is the upper bound of the lease, counted
+	 * from the mint (the first successful attempt), so a Smartproxy lease can outlive the
+	 * vendor session by the extraction-cache reuse window; expiry then drops and rebinds.
+	 * The bound is not a vendor guarantee (ADR-0010: a raw Smartproxy endpoint is not a hard
+	 * lease): the stealth runtime releases the binding as soon as the endpoint fails at the
+	 * transport, so a dead endpoint is left before the lifetime elapses.
+	 */
+	readonly lifetimeMinutes: number;
+};
+
+type CeremonyEgressLeasePayloadV1 = CeremonyEgressBinding & {
+	readonly version: typeof HANDLE_VERSION;
+	readonly tenantId: string;
+	readonly providerId: string;
+	readonly flowId: string;
+	readonly mintedAtMs: number;
+	readonly expiresAtMs: number;
+};
+
+type CeremonyEgressLeaseScopeV1 = Pick<
+	CeremonyEgressLeasePayloadV1,
+	"tenantId" | "providerId" | "flowId" | "affinityKey"
+>;
+
+export type CeremonyEgressLeaseRuntime = {
+	/** Exact egress bound to this ceremony; undefined until the first successful attempt binds one. */
+	readonly binding: CeremonyEgressBinding | undefined;
+	/**
+	 * Drops the binding once its vendor session lifetime has elapsed so the next attempt
+	 * selects and binds a fresh endpoint. Returns true when a binding was dropped: the
+	 * caller must also discard challenge state that was only valid for that endpoint.
+	 */
+	dropExpiredBinding(): boolean;
+	/**
+	 * Drops the binding unconditionally; the stealth runtime calls this when the bound
+	 * endpoint fails at the transport. Same return and caller obligation as
+	 * `dropExpiredBinding`.
+	 */
+	dropBinding(): boolean;
+	/**
+	 * Number of bindings dropped so far (expiry or release). Every stealth session created
+	 * from one client shares the lease; a session compares this to what it last observed to
+	 * retire endpoint-bound challenge state and replay records after another session moved
+	 * the ceremony.
+	 */
+	readonly generation: number;
+	bind(binding: CeremonyEgressBinding): void;
+	handle(): string | undefined;
+};
+
+/** The caller presented a handle this engine cannot verify for this ceremony (409). */
+function invalidLease(): never {
+	throw new SDKError("The engine ceremony egress lease is invalid", {
+		code: "EGRESS_LEASE_INVALID",
+		fix: "Restart the authentication ceremony to obtain a new engine-owned egress lease.",
+	});
+}
+
+/** The engine violated its own binding invariant (500); never attributable to the caller. */
+function bindingFault(message: string): never {
+	throw new SDKError(message, {
+		code: "EGRESS_LEASE_BINDING_INVALID",
+		fix: "This is an SDK or provider-runtime fault; the ceremony lease cannot bind the selected egress.",
+	});
+}
+
+function encryptionKey(key: string): Buffer {
+	return createHash("sha256").update(AEAD_KEY_DOMAIN, "utf8").update(key, "utf8").digest();
+}
+
+/** Fixed field order and JSON.stringify's compact form are the canonical AAD encoding. */
+function scopeAad(scope: CeremonyEgressLeaseScopeV1): Buffer {
+	return Buffer.from(
+		JSON.stringify({
+			version: HANDLE_VERSION,
+			tenantId: scope.tenantId,
+			providerId: scope.providerId,
+			flowId: scope.flowId,
+			affinityKey: scope.affinityKey,
+		}),
+		"utf8",
+	);
+}
+
+function encodeHandle(
+	payload: CeremonyEgressLeasePayloadV1,
+	key: string,
+	scope: CeremonyEgressLeaseScopeV1,
+): string {
+	const nonce = randomBytes(AEAD_NONCE_BYTES);
+	const cipher = createCipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+		authTagLength: AEAD_TAG_BYTES,
+	});
+	cipher.setAAD(scopeAad(scope));
+	const ciphertext = Buffer.concat([
+		cipher.update(JSON.stringify(payload), "utf8"),
+		cipher.final(),
+	]);
+	return [
+		`v${HANDLE_VERSION}`,
+		nonce.toString("base64url"),
+		ciphertext.toString("base64url"),
+		cipher.getAuthTag().toString("base64url"),
+	].join(".");
+}
+
+function isFiniteInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isPositiveFinite(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function decodeHandle(
+	handle: string,
+	key: string,
+	scope: CeremonyEgressLeaseScopeV1,
+): CeremonyEgressLeasePayloadV1 {
+	if (Buffer.byteLength(handle, "utf8") > HANDLE_MAX_BYTES) return invalidLease();
+	const parts = handle.split(".");
+	if (
+		parts.length !== 4 ||
+		parts[0] !== `v${HANDLE_VERSION}` ||
+		parts.slice(1).some((part) => !/^[A-Za-z0-9_-]+$/u.test(part))
+	) {
+		return invalidLease();
+	}
+	let parsed: unknown;
+	try {
+		const nonce = Buffer.from(parts[1]!, "base64url");
+		const ciphertext = Buffer.from(parts[2]!, "base64url");
+		const tag = Buffer.from(parts[3]!, "base64url");
+		if (
+			nonce.byteLength !== AEAD_NONCE_BYTES ||
+			tag.byteLength !== AEAD_TAG_BYTES ||
+			ciphertext.byteLength === 0
+		) {
+			return invalidLease();
+		}
+		const decipher = createDecipheriv(AEAD_ALGORITHM, encryptionKey(key), nonce, {
+			authTagLength: AEAD_TAG_BYTES,
+		});
+		decipher.setAAD(scopeAad(scope));
+		decipher.setAuthTag(tag);
+		const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+		parsed = JSON.parse(plaintext.toString("utf8"));
+	} catch {
+		return invalidLease();
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return invalidLease();
+	const candidate = parsed as Partial<CeremonyEgressLeasePayloadV1>;
+	if (
+		candidate.version !== HANDLE_VERSION ||
+		(candidate.vendor !== "smartproxy" && candidate.vendor !== "nodemaven") ||
+		typeof candidate.proxyUrl !== "string" ||
+		!candidate.proxyUrl ||
+		!isFiniteInteger(candidate.poolIndex) ||
+		typeof candidate.affinityKey !== "string" ||
+		!candidate.affinityKey ||
+		!isFiniteInteger(candidate.refreshEpoch) ||
+		typeof candidate.tenantId !== "string" ||
+		!candidate.tenantId ||
+		typeof candidate.providerId !== "string" ||
+		!candidate.providerId ||
+		typeof candidate.flowId !== "string" ||
+		!candidate.flowId ||
+		!isFiniteInteger(candidate.mintedAtMs) ||
+		!isFiniteInteger(candidate.expiresAtMs) ||
+		candidate.expiresAtMs <= candidate.mintedAtMs ||
+		!isPositiveFinite(candidate.lifetimeMinutes)
+	) {
+		return invalidLease();
+	}
+	try {
+		const proxy = new URL(candidate.proxyUrl);
+		if (proxy.protocol !== "http:" && proxy.protocol !== "socks5:") return invalidLease();
+	} catch {
+		return invalidLease();
+	}
+	return candidate as CeremonyEgressLeasePayloadV1;
+}
+
+function bindingOf(payload: CeremonyEgressLeasePayloadV1): CeremonyEgressBinding {
+	return {
+		vendor: payload.vendor,
+		proxyUrl: payload.proxyUrl,
+		poolIndex: payload.poolIndex,
+		affinityKey: payload.affinityKey,
+		refreshEpoch: payload.refreshEpoch,
+		lifetimeMinutes: payload.lifetimeMinutes,
+	};
+}
+
+export function createCeremonyEgressLeaseRuntime(options: {
+	readonly tenantId?: string;
+	readonly providerId: string;
+	readonly flowId: string;
+	readonly affinityKey: string;
+	readonly handle?: string;
+	/** Server-only registration before a handle can reach request diagnostics. */
+	readonly onHandle?: (handle: string) => void;
+	readonly environment?: Readonly<Record<string, string | undefined>>;
+	readonly now?: () => number;
+}): CeremonyEgressLeaseRuntime {
+	const environment = options.environment ?? process.env;
+	const now = options.now ?? Date.now;
+	if (typeof options.tenantId !== "string" || !options.tenantId.trim()) {
+		throw new SDKError("A tenant is required for an engine ceremony egress lease", {
+			code: "EGRESS_LEASE_INVALID",
+			fix: "Restart the authentication ceremony with its tenant identity.",
+		});
+	}
+	const scope: CeremonyEgressLeaseScopeV1 = {
+		tenantId: options.tenantId,
+		providerId: options.providerId,
+		flowId: options.flowId,
+		affinityKey: options.affinityKey,
+	};
+	const key = readDiagnosticEnv(APIFUSE__ENGINE__CEREMONY_LEASE_KEY, environment)?.trim();
+	if (!key) {
+		throw new SDKError("The engine ceremony egress lease key is not configured", {
+			code: "EGRESS_LEASE_KEY_MISSING",
+			fix: `Configure ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} in the engine host.`,
+		});
+	}
+	// The key is the whole authenticity boundary of a handle (a verified handle's proxyUrl
+	// becomes the ceremony egress), so the documented minimum is enforced, not advisory.
+	if (Buffer.byteLength(key, "utf8") < LEASE_KEY_MIN_BYTES) {
+		throw new SDKError(
+			`The engine ceremony egress lease key is shorter than ${LEASE_KEY_MIN_BYTES} bytes`,
+			{
+				code: "EGRESS_LEASE_KEY_WEAK",
+				fix: `Set ${APIFUSE__ENGINE__CEREMONY_LEASE_KEY} to at least ${LEASE_KEY_MIN_BYTES} random bytes (for example \`openssl rand -base64 32\`).`,
+			},
+		);
+	}
+	let payload: CeremonyEgressLeasePayloadV1 | undefined;
+	let currentHandle: string | undefined;
+	let generation = 0;
+
+	const dropBinding = (): boolean => {
+		if (!payload) return false;
+		payload = undefined;
+		currentHandle = undefined;
+		generation += 1;
+		return true;
+	};
+	const dropExpiredBinding = (): boolean =>
+		payload !== undefined && now() >= payload.expiresAtMs ? dropBinding() : false;
+
+	if (options.handle !== undefined) {
+		options.onHandle?.(options.handle);
+		// Scope mismatch fails GCM authentication because scope is AAD; there is
+		// deliberately no post-decrypt scope comparison fallback.
+		payload = decodeHandle(options.handle, key, scope);
+		currentHandle = options.handle;
+		// An expired but authentic handle is not a fault: the ceremony continues on a
+		// freshly selected endpoint and the next turn receives the new handle.
+		dropExpiredBinding();
+	}
+
+	return {
+		get binding() {
+			return payload ? bindingOf(payload) : undefined;
+		},
+		dropExpiredBinding,
+		dropBinding,
+		get generation() {
+			return generation;
+		},
+		bind(binding) {
+			if (payload) {
+				// The stealth runtime reuses the bound endpoint while a binding exists and
+				// never rebinds it; a second bind is an engine invariant break.
+				return bindingFault("The ceremony egress lease is already bound");
+			}
+			if (
+				binding.affinityKey !== options.affinityKey ||
+				!binding.proxyUrl ||
+				(binding.vendor !== "smartproxy" && binding.vendor !== "nodemaven") ||
+				!isFiniteInteger(binding.poolIndex) ||
+				!isPositiveFinite(binding.lifetimeMinutes)
+			) {
+				return bindingFault("The selected egress cannot be bound to the ceremony lease");
+			}
+			const mintedAtMs = now();
+			payload = {
+				version: HANDLE_VERSION,
+				tenantId: scope.tenantId,
+				providerId: options.providerId,
+				flowId: options.flowId,
+				...binding,
+				mintedAtMs,
+				expiresAtMs: mintedAtMs + binding.lifetimeMinutes * 60_000,
+			};
+			currentHandle = encodeHandle(payload, key, scope);
+			options.onHandle?.(currentHandle);
+		},
+		handle() {
+			return currentHandle;
+		},
+	};
+}

package/src/runtime/env.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { isEngineOwnedEnvName } from "../engine.js";
 import type { EnvContext } from "../types.js";
 
@@ -20,7 +21,7 @@ export function createEnvContext(allowedKeys?: string[]): EnvContext {
 				return undefined;
 			}
 
-			return process.env[key];
+			return readDiagnosticEnv(key);
 		},
 	};
 }

package/src/runtime/http.ts

@@ -654,6 +654,7 @@ async function resolveNativeProxy(
 		// supported here, so a socks5 policy fails loudly rather than downgrading.
 		transportProtocols: ["http"],
 		telemetry: clientOptions.telemetry,
+		engineCredentials: clientOptions.engineCredentials,
 	});
 	if (resolvedProxy.shouldWarn) {
 		warn(

package/src/runtime/instrumentation.ts

@@ -1,3 +1,4 @@
+import { registerDiagnosticSensitiveValues } from "./diagnostic-redactor.js";
 import type {
 	HttpStreamResponse,
 	ProviderContext,
@@ -570,6 +571,7 @@ function wrapStealthRedirects(
 		run(...args: Parameters<StealthSession["redirects"]["run"]>) {
 			const diagnosticArgs = [args[0].url, args[0]];
 			const diagnostics = snapshotRequestDiagnostics("stealth", "fetch", diagnosticArgs);
+			registerDiagnosticSensitiveValues(trace, diagnostics.sensitiveValues);
 			let result: ReturnType<StealthSession["redirects"]["run"]>;
 			try {
 				result = redirects.run(...args);
@@ -750,6 +752,7 @@ function wrapNamespace<T extends object>(
 					return Reflect.apply(value, namespaceTarget, args);
 				}
 				const requestDiagnostics = snapshotRequestDiagnostics(namespace, methodName, args);
+				registerDiagnosticSensitiveValues(trace, requestDiagnostics.sensitiveValues);
 				// Invoke first and decide by the RETURN VALUE. `runSpan` always
 				// returns a Promise, so unconditionally span-wrapping every member
 				// silently rewrote synchronous contracts: `ctx.state.namespace()`

package/src/runtime/ocr.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError } from "../errors.js";
 import type {
 	OcrCaptchaCandidate,
@@ -96,7 +97,7 @@ export function createUnsupportedOcrClient(reason?: string): OcrContext {
 }
 
 function normalizedEnvValue(env: EnvLike, key: string): string | undefined {
-	const value = env[key]?.trim();
+	const value = readDiagnosticEnv(key, env)?.trim();
 	return value ? value : undefined;
 }
 

package/src/runtime/otlp.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { AsyncResource } from "node:async_hooks";
 
 import type { TraceSpan } from "../types.js";
@@ -153,12 +154,12 @@ export function resolveOTLPExportOptions(
 		{ source: EXPLICIT_ENDPOINT_SOURCE, value: explicit.endpoint, appendPath: false },
 		{
 			source: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
-			value: env[OTEL_EXPORTER_OTLP_TRACES_ENDPOINT],
+			value: readDiagnosticEnv(OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, env),
 			appendPath: false,
 		},
 		{
 			source: OTEL_EXPORTER_OTLP_ENDPOINT,
-			value: env[OTEL_EXPORTER_OTLP_ENDPOINT],
+			value: readDiagnosticEnv(OTEL_EXPORTER_OTLP_ENDPOINT, env),
 			appendPath: true,
 		},
 	];
@@ -173,11 +174,11 @@ export function resolveOTLPExportOptions(
 	}
 	const endpoint = candidate.appendPath ? appendTracesPath(parsed.url) : candidate.value;
 
-	const tracesHeaders = presentValue(env[OTEL_EXPORTER_OTLP_TRACES_HEADERS]);
+	const tracesHeaders = presentValue(readDiagnosticEnv(OTEL_EXPORTER_OTLP_TRACES_HEADERS, env));
 	const headersSource =
 		tracesHeaders !== undefined ? OTEL_EXPORTER_OTLP_TRACES_HEADERS : OTEL_EXPORTER_OTLP_HEADERS;
 	const envHeaders = parseHeaderList(
-		tracesHeaders ?? presentValue(env[OTEL_EXPORTER_OTLP_HEADERS]),
+		tracesHeaders ?? presentValue(readDiagnosticEnv(OTEL_EXPORTER_OTLP_HEADERS, env)),
 	);
 	if (!headersAreSendable(envHeaders)) {
 		return { status: "invalid", source: headersSource, reason: INVALID_HEADERS };

package/src/runtime/proxy-nodemaven.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { createHash, randomBytes } from "node:crypto";
 
 import type { ProviderProxyPolicy } from "../types.js";
@@ -43,11 +44,11 @@ export function hasNodemavenCredentials(): boolean {
 }
 
 function readNodemavenUsername(): string | undefined {
-	return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+	return readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)?.trim() || undefined;
 }
 
 function readNodemavenPassword(): string | undefined {
-	return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+	return readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)?.trim() || undefined;
 }
 
 function resolveNodemavenFilter(value: string | undefined): string {

package/src/runtime/proxy-retry-policy.ts

@@ -7,6 +7,7 @@ import {
 	HttpRetryPreset,
 	HttpRetryUnsafeMethodPolicy,
 } from "../types.js";
+import { isSensitiveKey } from "./request-options.js";
 
 export type NormalizedProxyTransportRetryOptions = Required<
 	Pick<
@@ -364,10 +365,20 @@ export function validateUnsafeProxyTransportRetryMethods(
 export function isProxyTransportRetryMethod(
 	method: HttpMethod | string,
 	options: NormalizedProxyTransportRetryOptions,
+	request?: {
+		readonly body?: unknown;
+		readonly headers?: Readonly<Record<string, string | readonly string[] | undefined>>;
+	},
 ): boolean {
-	return options.methods
+	const methodAllowed = options.methods
 		.map((allowedMethod) => allowedMethod.toUpperCase())
 		.includes(method.toUpperCase());
+	if (!methodAllowed || request === undefined) return methodAllowed;
+	if (request.body !== undefined) return false;
+	return !Object.keys(request.headers ?? {}).some((name) => {
+		const normalized = name.toLowerCase();
+		return normalized === "cookie" || normalized === "proxy-authorization" || isSensitiveKey(name);
+	});
 }
 
 export function shouldRetryProxyTransportError(

package/src/runtime/request-options.ts

@@ -1,3 +1,4 @@
+import { isProviderError } from "../errors.js";
 import type {
 	HttpClient,
 	RequestOptions,
@@ -5,7 +6,6 @@ import type {
 	RequestParams,
 	RequestParamValue,
 } from "../types.js";
-import { isProviderError } from "../errors.js";
 
 export const REDACTED_QUERY_VALUE = "[REDACTED]";
 
@@ -161,15 +161,34 @@ export function serializeRequestUrl(
 	};
 }
 
-const MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH = 4;
+const MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH = 8;
 
-function normalizePercentEscapes(value: string): string {
+export function normalizePercentEscapes(value: string): string {
 	return value.replace(/%[\da-f]{2}/gi, (percentEscape) => percentEscape.toUpperCase());
 }
 
 function sensitiveValueVariants(value: string): string[] {
 	if (!value || value === REDACTED_QUERY_VALUE) return [];
 
+	// Owner-visible policy: short credentials are literal, case-sensitive tokens only.
+	// Encoded short needles collide with benign cursors and ordinary diagnostic text.
+	if (value.length < 8) return [value];
+	// These ASCII characters are identical under NFC, JSON, URI-component and
+	// form encoding. Avoid constructing those identical variants for common tokens.
+	if (/^[A-Za-z0-9._*-]+$/.test(value)) {
+		const base64 = Buffer.from(value, "utf8").toString("base64");
+		const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+		return [
+			...new Set([
+				value,
+				base64,
+				base64.replace(/=+$/, ""),
+				base64Url,
+				base64Url.replace(/=+$/, ""),
+			]),
+		];
+	}
+	const normalized = value.normalize("NFC");
 	const formEncoded = new URLSearchParams({ value }).toString().slice("value=".length);
 	let componentEncoded: string;
 	try {
@@ -179,15 +198,42 @@ function sensitiveValueVariants(value: string): string[] {
 		// still safe to scrub, and URLSearchParams supplies its well-formed form.
 		componentEncoded = value;
 	}
-	return [...new Set([value, componentEncoded, formEncoded].map(normalizePercentEscapes))];
-}
-
-type SensitiveValueVariant = { value: string; requiresTokenBoundary: boolean };
+	const base64 = Buffer.from(value, "utf8").toString("base64");
+	const base64Url = base64.replaceAll("+", "-").replaceAll("/", "_");
+	const jsonEscaped = JSON.stringify(value).slice(1, -1);
+	return [
+		...new Set(
+			[
+				value,
+				normalized,
+				componentEncoded,
+				formEncoded,
+				jsonEscaped,
+				base64,
+				base64.replace(/=+$/, ""),
+				base64Url,
+				base64Url.replace(/=+$/, ""),
+			].map(normalizePercentEscapes),
+		),
+	];
+}
+
+export type SensitiveValueVariant = {
+	value: string;
+	requiresTokenBoundary: boolean;
+	caseInsensitive: boolean;
+};
 
-function allSensitiveValueVariants(sensitiveValues: readonly string[]): SensitiveValueVariant[] {
+export function allSensitiveValueVariants(
+	sensitiveValues: readonly string[],
+): SensitiveValueVariant[] {
 	const variants = new Map<string, SensitiveValueVariant>();
 	for (const sensitiveValue of sensitiveValues) {
 		const requiresTokenBoundary = sensitiveValue.length < MIN_UNSCOPED_SENSITIVE_VALUE_LENGTH;
+		// Long values are unlikely to be ordinary prose, so case folding is worth
+		// the extra over-redaction protection. Values of 4-7 characters remain
+		// case-sensitive because they commonly occur as words and identifiers.
+		const caseInsensitive = sensitiveValue.length >= 8;
 		for (const value of sensitiveValueVariants(sensitiveValue)) {
 			const existing = variants.get(value);
 			variants.set(value, {
@@ -195,6 +241,7 @@ function allSensitiveValueVariants(sensitiveValues: readonly string[]): Sensitiv
 				requiresTokenBoundary: existing
 					? existing.requiresTokenBoundary && requiresTokenBoundary
 					: requiresTokenBoundary,
+				caseInsensitive: existing ? existing.caseInsensitive || caseInsensitive : caseInsensitive,
 			});
 		}
 	}
@@ -209,28 +256,29 @@ function isTokenCharacter(value: string | undefined): boolean {
 }
 
 function replaceSensitiveVariant(text: string, variant: SensitiveValueVariant): string {
-	const pattern = variant.value.replace(/%([\da-f]{2})|[.*+?^${}()|[\]\\]/gi, (match, hex) => {
-		if (hex) {
-			return `%${[...String(hex)]
-				.map((character) =>
-					/[a-f]/i.test(character)
-						? `[${character.toLowerCase()}${character.toUpperCase()}]`
-						: character,
-				)
-				.join("")}`;
-		}
-		return `\\${match}`;
-	});
-	return text.replace(new RegExp(pattern, "gu"), (match, offset: number, source: string) => {
-		const end = offset + match.length;
+	const normalized = normalizePercentEscapes(text);
+	const comparable = variant.caseInsensitive ? normalized.toLowerCase() : text;
+	const needle = variant.caseInsensitive ? variant.value.toLowerCase() : variant.value;
+	let cursor = 0;
+	let output = "";
+	for (
+		let index = comparable.indexOf(needle);
+		index !== -1;
+		index = comparable.indexOf(needle, index + 1)
+	) {
+		const end = index + needle.length;
 		if (
 			variant.requiresTokenBoundary &&
-			(isTokenCharacter(source[offset - 1]) || isTokenCharacter(source[end]))
-		) {
-			return match;
-		}
-		return REDACTED_QUERY_VALUE;
-	});
+			(isTokenCharacter(comparable[index - 1]) || isTokenCharacter(comparable[end]))
+		)
+			continue;
+		// Unicode folding can change offsets; suppress the field instead of slicing a secret.
+		if (comparable.length !== text.length) return REDACTED_QUERY_VALUE;
+		output += text.slice(cursor, index) + REDACTED_QUERY_VALUE;
+		cursor = end;
+		index = end - 1;
+	}
+	return cursor ? output + text.slice(cursor) : text;
 }
 
 /** Scrubs raw and URL-encoded secret values from diagnostic text. */

package/src/runtime/request-telemetry.ts

@@ -1,6 +1,7 @@
 import { PROVIDER_OBSERVABILITY_TAXONOMY_VERSION } from "../observability.js";
 import type { ProxyTelemetrySink } from "../config/loader.js";
 import type { ProxyTelemetryLogPayload } from "./proxy-telemetry.js";
+import type { ResolverTelemetryLogPayload } from "./resolver-telemetry.js";
 import type { Span, TraceContext } from "./trace.js";
 
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
@@ -57,9 +58,7 @@ export type GatewayIngestible<T> = 0 extends 1 & T
 										? never
 										: unknown extends U
 											? never
-											: [U] extends [
-													number | boolean | ClosedEnum<string> | GatewayIngestible<U>,
-												]
+											: [U] extends [number | boolean | ClosedEnum<string> | GatewayIngestible<U>]
 												? T[K]
 												: never
 									: [NonNullable<T[K]>] extends [object]
@@ -86,9 +85,7 @@ export type TenantNeutral<T> = 0 extends 1 & T
 						? never
 						: unknown extends T[K]
 							? never
-							: [NonNullable<T[K]>] extends [
-									string[] & { readonly __tenantOpaqueCacheKeys: true },
-								]
+							: [NonNullable<T[K]>] extends [string[] & { readonly __tenantOpaqueCacheKeys: true }]
 								? K extends "keys"
 									? T[K]
 									: never
@@ -123,7 +120,8 @@ export interface TelemetryContributor<Log extends object, Header extends object>
 
 export type RequestTelemetryLogPayload = {
 	proxy?: ProxyTelemetryLogPayload;
-} & Partial<Record<Exclude<TelemetryKey, "proxy">, object>>;
+	resolver?: ResolverTelemetryLogPayload;
+} & Partial<Record<Exclude<TelemetryKey, "proxy" | "resolver">, object>>;
 
 type RegisteredTelemetryContributor = {
 	readonly key: TelemetryKey;