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

package/src/error-resolution.ts

@@ -10,6 +10,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"BROWSER_CDP_POOL_REQUIRED",
 	"BROWSER_RUNTIME_UNSUPPORTED",
 	"STEALTH_RUNTIME_UNSUPPORTED",
+	"STEALTH_HEADER_OVERRIDE_UNSUPPORTED",
 	"SSE_EVENT_UNDECLARED",
 	"STREAM_EVENT_TOO_LARGE",
 	"STREAM_CHUNK_TOO_LARGE",
@@ -51,6 +52,13 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"http_redirect_missing_location",
 	"http_redirect_loop",
 	"transport_invalid_url",
+	"EGRESS_LEASE_INVALID",
+	"EGRESS_LEASE_BINDING_INVALID",
+	"EGRESS_LEASE_KEY_MISSING",
+	"EGRESS_LEASE_KEY_WEAK",
+	"STEALTH_BODY_UNSUPPORTED",
+	"REPLAY_SESSION_MISMATCH",
+	"REPLAY_ALREADY_ATTEMPTED",
 	"retry_exhausted",
 	"auth_abort_unsafe_data",
 	"credentials_auth_missing_credential_keys",
@@ -117,6 +125,11 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		// contract): the upstream evaluated the request and said no under its
 		// own rules — a conflict with upstream state, never a 5xx.
 		["UPSTREAM_REJECTED", 409],
+		// Only an unverifiable or foreign handle is the caller's: key and binding
+		// faults stay unmapped (500) because the engine host, not the caller, owns them.
+		["EGRESS_LEASE_INVALID", 409],
+		["REPLAY_SESSION_MISMATCH", 409],
+		["REPLAY_ALREADY_ATTEMPTED", 409],
 		["UPSTREAM_ERROR", 502],
 		["BLOCKED", 502],
 		["OCR_UNAVAILABLE", 503],

package/src/index.ts

@@ -198,17 +198,43 @@ export {
 	type TelemetryKey,
 	type TenantNeutral,
 } from "./runtime/request-telemetry.js";
+export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
+export {
+	ResolverTelemetryCollector,
+	type ResolverCacheReadTelemetryEvent,
+	type ResolverCacheWriteTelemetryEvent,
+	type ResolverFailoverTelemetryEvent,
+	type ResolverIdentityTelemetryEvent,
+	type ResolverOutcomeTelemetryEvent,
+	type ResolverTelemetryAttemptOutcome,
+	type ResolverAttemptSample,
+	type ResolverTelemetryCacheStatus,
+	type ResolverTelemetryCacheWriteReason,
+	type ResolverTelemetryErrorClass,
+	type ResolverTelemetryHeaderPayload,
+	type ResolverTelemetryIdentitySource,
+	type ResolverTelemetryLogPayload,
+	type ResolverTelemetryOutcome,
+	type ResolverTelemetryPhase,
+	type ResolverTelemetrySink,
+	type ResolverVendorAttemptTelemetryEvent,
+} from "./runtime/resolver-telemetry.js";
 export {
 	APIFUSE__CDP_POOL__URL,
 	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
 	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
 	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
 	APIFUSE__RESOLVER__TIMEOUT_MS,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
-export type { ResolverVendorTransport } from "./runtime/resolver-vendors/types.js";
+export type {
+	ResolverPaidUsageContext,
+	ResolverVendorTransport,
+	ResolverVendorUnavailableReason,
+} from "./runtime/resolver-vendors/types.js";
 export {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -250,6 +276,8 @@ export {
 	type TraceContext,
 } from "./runtime/trace.js";
 export {
+	APIFUSE_CONTENT_PROVENANCE_META_KEY,
+	APIFUSE_CONTENT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
@@ -264,6 +292,7 @@ export {
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
+	untrustedContent,
 	z,
 } from "./schema.js";
 export {
@@ -432,6 +461,7 @@ export type {
 	ProviderRuntimeTarget,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
+	ProviderStealthConfig,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderStreamEvent,
@@ -455,6 +485,7 @@ export type {
 	StateWriteOptions,
 	StealthClient,
 	StealthBrowser,
+	StealthChallengeClassification,
 	StealthCookieStore,
 	StealthCookieStoreV1,
 	StealthFetchOptions,

package/src/lint.ts

@@ -1032,9 +1032,9 @@ function browserVersionLiteralMessage(finding: BrowserVersionLiteralFinding): st
 		case "profile":
 			return `Hardcoded stealth profile "${finding.literal}" pins a browser version and will rot. Select the browser and OS structurally, for example stealth: { browser: "chrome", os: "macos" }.`;
 		case "user-agent":
-			return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal and derive it from the structured profile, for example getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
+			return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal. ctx.stealth owns User-Agent and rejects a caller value with STEALTH_HEADER_OVERRIDE_UNSUPPORTED, so omit the header there and select the profile with stealth: { browser: "chrome", os: "macos" }. For ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
 		case "sec-ch-ua":
-			return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }; derive any explicit User-Agent with getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
+			return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }. ctx.stealth also owns User-Agent, so omit that header there as well; for ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
 	}
 }
 

package/src/provider.ts

@@ -133,9 +133,13 @@ export {
 	createProviderEnvironment,
 	createInProcessProviderEngine,
 	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_RUNTIME_ENV_NAMES,
 	ENGINE_OWNED_TELEMETRY_ENV_NAMES,
 	isEngineOwnedEnvName,
 	isEngineOwnedProxyCredentialName,
+	isEngineOwnedResolverCredentialName,
+	isEngineOwnedRuntimeEnvName,
 	isEngineOwnedTelemetryEnvName,
 	PROVIDER_CAPABILITY_KEYS,
 	PROVIDER_ENGINE_PROTOCOL_VERSION,
@@ -164,6 +168,8 @@ export {
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 } from "./runtime/choice.js";
 export {
+	APIFUSE_CONTENT_PROVENANCE_META_KEY,
+	APIFUSE_CONTENT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
@@ -178,6 +184,7 @@ export {
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
+	untrustedContent,
 	z,
 } from "./schema.js";
 export type {
@@ -261,6 +268,7 @@ export type {
 	ProviderResolvedFile,
 	ProviderRuntimeTarget,
 	ProviderRuntimeState,
+	ProviderStealthConfig,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderSupportLevel,
@@ -273,6 +281,7 @@ export type {
 	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
+	StealthChallengeClassification,
 } from "./types.js";
 export {
 	NativeEgressGrantExpiredError,

package/src/runtime/bounded-expiring-map.ts

@@ -0,0 +1,67 @@
+/**
+ * Map whose entries carry an expiry and whose size is capped.
+ *
+ * Expired entries are dropped when read and swept on every insert, so a
+ * process that keeps minting new keys does not retain dead values. When the
+ * cap is still exceeded after the sweep, the least recently used entry is
+ * evicted and counted in `capacityEvictions` so callers can tell the two
+ * kinds of removal apart. Callers pass `now` explicitly so a single timestamp
+ * is used across a lookup-then-store sequence.
+ */
+export class BoundedExpiringMap<K, V> {
+	readonly #entries = new Map<K, V>();
+	readonly #maxEntries: number;
+	readonly #expiresAt: (value: V) => number;
+	#capacityEvictions = 0;
+
+	constructor(maxEntries: number, expiresAt: (value: V) => number) {
+		if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+			throw new RangeError("maxEntries must be a positive integer");
+		}
+		this.#maxEntries = maxEntries;
+		this.#expiresAt = expiresAt;
+	}
+
+	get size(): number {
+		return this.#entries.size;
+	}
+
+	/** Entries removed to satisfy `maxEntries`; expiry removals are not counted. */
+	get capacityEvictions(): number {
+		return this.#capacityEvictions;
+	}
+
+	get(key: K, now: number): V | undefined {
+		if (!this.#entries.has(key)) return undefined;
+		const value = this.#entries.get(key) as V;
+		this.#entries.delete(key);
+		if (this.#expiresAt(value) <= now) return undefined;
+		// Re-insert so Map iteration order doubles as the LRU order.
+		this.#entries.set(key, value);
+		return value;
+	}
+
+	set(key: K, value: V, now: number): void {
+		for (const [existingKey, existing] of this.#entries) {
+			if (this.#expiresAt(existing) <= now) this.#entries.delete(existingKey);
+		}
+		this.#entries.delete(key);
+		if (this.#expiresAt(value) <= now) return;
+		this.#entries.set(key, value);
+		if (this.#entries.size > this.#maxEntries) {
+			const oldest = this.#entries.keys().next();
+			if (!oldest.done) {
+				this.#entries.delete(oldest.value);
+				this.#capacityEvictions += 1;
+			}
+		}
+	}
+
+	delete(key: K): boolean {
+		return this.#entries.delete(key);
+	}
+
+	clear(): void {
+		this.#entries.clear();
+	}
+}

package/src/runtime/cache.ts

@@ -589,6 +589,13 @@ export function createProviderCache(options: ProviderCacheOptions): ProviderCach
 	};
 }
 
+const bypassCaches = new WeakSet<ProviderCache>();
+
+/** Internal cache capability, separate from hit/miss metadata. */
+export function isProviderCacheBypassed(cache: ProviderCache): boolean {
+	return bypassCaches.has(cache);
+}
+
 export function createBypassProviderCache(
 	options: Pick<ProviderCacheOptions, "providerId">,
 ): ProviderCache {
@@ -597,7 +604,7 @@ export function createBypassProviderCache(
 	const events: ProviderCacheLookupMeta[] = [];
 	const secretScopedKeys = new Set<string>();
 
-	return {
+	const cache: ProviderCache = {
 		key(namespace, parts, keyOptions?: ProviderCacheKeyOptions) {
 			const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
 			const normalized = normalizeKeyPart(parts, extra, pepper);
@@ -643,6 +650,8 @@ export function createBypassProviderCache(
 			};
 		},
 	};
+	bypassCaches.add(cache);
+	return cache;
 }
 
 export function resetProviderCacheForTests(): void {

package/src/runtime/egress-lease.ts

@@ -0,0 +1,336 @@
+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;
+	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 = environment[APIFUSE__ENGINE__CEREMONY_LEASE_KEY]?.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) {
+		// 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);
+		},
+		handle() {
+			return currentHandle;
+		},
+	};
+}

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/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-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;