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

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;

package/src/runtime/resolver-config.ts

@@ -1,6 +1,18 @@
+import type { ProviderChallengeKind } from "../types.js";
+
 export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
 export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
 export const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
+export const APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY =
+	"APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY";
 export const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
 export const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
 export const DEFAULT_RESOLVER_TIMEOUT_MS = 180_000;
+
+/**
+ * SBSD is solved on the provider's own admitted session, so the transport profile must be
+ * declared up front. Other kinds, including `akamai_sensor`, keep the profile optional.
+ */
+export function kindRequiresClientProfile(kind: ProviderChallengeKind): boolean {
+	return kind === "akamai_sbsd";
+}

package/src/runtime/resolver-public.ts

@@ -3,6 +3,7 @@ export {
 	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
 	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
 	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
 	APIFUSE__RESOLVER__TIMEOUT_MS,
 	bindResolverSignal,
 	createResolverClient,
@@ -21,3 +22,23 @@ export {
 	type ResolverRuntimeOptions,
 	type ResolverSolutionSource,
 } from "./resolver.js";
+export {
+	type ResolverCacheReadTelemetryEvent,
+	type ResolverCacheWriteTelemetryEvent,
+	type ResolverFailoverTelemetryEvent,
+	type ResolverIdentityTelemetryEvent,
+	type ResolverOutcomeTelemetryEvent,
+	type ResolverTelemetryAttemptOutcome,
+	type ResolverTelemetryCacheStatus,
+	type ResolverTelemetryCacheWriteReason,
+	type ResolverTelemetryErrorClass,
+	type ResolverTelemetryIdentitySource,
+	type ResolverTelemetryOutcome,
+	type ResolverTelemetryPhase,
+	type ResolverTelemetrySink,
+	type ResolverVendorAttemptTelemetryEvent,
+} from "./resolver-telemetry.js";
+export type {
+	ResolverPaidUsageContext,
+	ResolverVendorUnavailableReason,
+} from "./resolver-vendors/types.js";

package/src/runtime/resolver-shared.ts

@@ -1,6 +1,81 @@
 import { ProviderError } from "../errors.js";
 import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
 import type { TraceRecorder } from "./trace.js";
+import type { ResolverTelemetryOutcome, ResolverTelemetrySink } from "./resolver-telemetry.js";
+
+type ResolverTelemetryBinding = (sink: ResolverTelemetrySink) => ResolverContext;
+const telemetryBindings = new WeakMap<ResolverContext, ResolverTelemetryBinding>();
+
+/** Internal contract: reconstruct a chain with a new request sink, without mutating the host chain. */
+export function registerResolverTelemetryBinding(
+	resolver: ResolverContext,
+	bind: ResolverTelemetryBinding,
+): void {
+	telemetryBindings.set(resolver, bind);
+}
+
+/** Preserve reconstruction across SDK wrappers without capturing their current request sink. */
+export function inheritResolverTelemetryBinding(
+	resolver: ResolverContext,
+	wrapper: ResolverContext,
+): void {
+	const bind = telemetryBindings.get(resolver);
+	if (bind) telemetryBindings.set(wrapper, bind);
+}
+
+/** SDK chains expose each vendor invocation; opaque host resolvers expose one custom invocation. */
+export function bindResolverTelemetry(
+	resolver: ResolverContext,
+	sink: ResolverTelemetrySink | undefined,
+): ResolverContext {
+	if (!sink) return resolver;
+	const metadata = (
+		resolver as ResolverContext & {
+			readonly [RESOLVER_INSTRUMENTATION_METADATA]?: { readonly target: ResolverContext };
+		}
+	)[RESOLVER_INSTRUMENTATION_METADATA];
+	if (metadata) return bindResolverTelemetry(metadata.target, sink);
+	const bind = telemetryBindings.get(resolver);
+	if (bind) return bind(sink);
+	const wrapper: ResolverSolveWithRecorder = {
+		async solve(challenge, signal, recorder) {
+			const startedAt = Date.now();
+			let outcome: ResolverTelemetryOutcome = "error";
+			try {
+				const solution = await (resolver as ResolverSolveWithRecorder).solve(
+					challenge,
+					signal,
+					recorder,
+				);
+				outcome = "solved";
+				return solution;
+			} catch (error) {
+				outcome = signal?.aborted
+					? "aborted"
+					: error instanceof ProviderError && error.code === "RESOLVER_CHAIN_EXHAUSTED"
+						? "exhausted"
+						: "error";
+				throw error;
+			} finally {
+				const ms = Date.now() - startedAt;
+				sink.recordVendorAttempt({
+					vendor: "custom",
+					phase: outcome === "solved" ? "poll_result" : "create_task",
+					outcome: outcome === "solved" ? "ok" : "error",
+					ms,
+				});
+				sink.recordOutcome({ outcome, solveMs: ms, challengeKind: challenge.kind });
+			}
+		},
+	};
+	// Rebinding this wrapper returns to the original host, never to its previous sink.
+	registerResolverTelemetryBinding(wrapper, createOpaqueResolverTelemetryBinding(resolver));
+	return wrapper;
+}
+
+function createOpaqueResolverTelemetryBinding(resolver: ResolverContext): ResolverTelemetryBinding {
+	return (sink) => bindResolverTelemetry(resolver, sink);
+}
 
 export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for(
 	"@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata",