@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.9

package/src/define.ts

@@ -25,6 +25,7 @@ import type {
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
 	ProviderProxyConfig,
+	ProviderProxyProvider,
 	ProviderPublicProfile,
 	ProviderReviewed,
 	ProviderSecretDeclaration,
@@ -78,7 +79,7 @@ const VALID_RUNTIMES = ["standard", "shared", "browser"] as const;
 const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"] as const;
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"] as const;
-const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "decodo", "custom"] as const;
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"] as const;
 const VALID_PROVIDER_PROXY_AFFINITIES = [
 	"request",
 	"operation",
@@ -87,6 +88,20 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ] as const;
 const VALID_PROVIDER_STT_MODES = ["optional", "required"] 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";
+// Per-vendor provider-declared credential secrets. A required-mode chain must
+// declare every secret of every credentialed vendor it names, so a missing
+// 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.
+const VENDOR_REQUIRED_SECRETS: Partial<Record<ProviderProxyProvider, readonly string[]>> = {
+	smartproxy: [SMARTPROXY_APP_KEY_SECRET],
+	nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
+};
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"] as const;
@@ -371,11 +386,24 @@ function validateProviderProxy(config: {
 			},
 		);
 	}
-	rejectUnknownFields(proxy, new Set(["mode", "provider", "geo", "session"]), "proxy");
+	rejectUnknownFields(proxy, new Set(["mode", "provider", "providers", "geo", "session"]), "proxy");
 	assertLiteralField(proxy.mode, "proxy.mode", VALID_PROVIDER_PROXY_MODES, config.id);
 	if (proxy.provider !== undefined) {
 		assertLiteralField(proxy.provider, "proxy.provider", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
 	}
+	if (proxy.providers !== undefined) {
+		if (!Array.isArray(proxy.providers) || proxy.providers.length === 0) {
+			throw new ValidationError(
+				`Provider "${config.id}" has invalid proxy.providers: must be a non-empty array of proxy vendors.`,
+				{
+					fix: `Use proxy.providers: ["smartproxy", "nodemaven"] to declare an ordered fallback chain.`,
+				},
+			);
+		}
+		for (const vendor of proxy.providers) {
+			assertLiteralField(vendor, "proxy.providers[]", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
+		}
+	}
 	if (proxy.geo !== undefined) {
 		if (!proxy.geo || typeof proxy.geo !== "object" || Array.isArray(proxy.geo)) {
 			throw new ValidationError(
@@ -433,19 +461,54 @@ function validateProviderProxy(config: {
 			);
 		}
 	}
-	if (proxy.mode === "required" && proxy.provider === "smartproxy") {
-		const hasSmartproxySecret = config.secrets?.some(
-			(secret) => secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false,
-		);
-		if (!hasSmartproxySecret) {
-			throw new ValidationError(
-				`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`,
-				{
-					fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
-				},
-			);
+	// Every credentialed vendor in a required-mode chain must declare its
+	// provider secret(s) so a missing credential fails at build/validation time,
+	// not during a live outage. This covers the fallback legs too (not just the
+	// first vendor): a declared-but-uncredentialed nodemaven fallback would leave
+	// the chain silently down to a single vendor, reintroducing the SPOF the chain
+	// removes.
+	const vendorChain =
+		proxy.providers && proxy.providers.length > 0
+			? proxy.providers
+			: proxy.provider
+				? [proxy.provider]
+				: [];
+	if (proxy.mode === "required") {
+		for (const vendor of vendorChain) {
+			const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
+			if (!requiredSecrets) continue;
+			for (const secretName of requiredSecrets) {
+				// Match the canonical runtime gate (assertRequiredSecretsPresent /
+				// listMissingRequiredSecrets), which enforces only `required === true`
+				// declarations. A declaration that omits `required` (defaulting to
+				// optional) is skipped at runtime, so accepting it here would pass
+				// validation while leaving the credential unenforced until proxy
+				// resolution during a live request — the fail-open gap this check exists
+				// to close.
+				const declared = config.secrets?.some(
+					(secret) => secret.name === secretName && secret.required === true,
+				);
+				if (!declared) {
+					throw new ValidationError(
+						`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`,
+						{
+							fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
+						},
+					);
+				}
+			}
 		}
 	}
+	// `decodo`/`custom` are deprecated vendor values (string-union members, so the
+	// @deprecated symbol gate can't catch them — warn at validation time instead).
+	const deprecatedVendors = vendorChain.filter(
+		(vendor) => vendor === "decodo" || vendor === "custom",
+	);
+	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.`,
+		);
+	}
 }
 
 function validateProviderStt(config: { id: string; stt?: ProviderSttConfig }): void {

package/src/runtime/choice.ts

@@ -11,7 +11,7 @@ import {
 	ProviderChoiceTokenError,
 	type ProviderChoiceTokenPayload,
 } from "../choice-token.js";
-import { ProviderError } from "../errors.js";
+import { isProviderError, ProviderError } from "../errors.js";
 import type {
 	CredentialContext,
 	EnvContext,
@@ -23,6 +23,7 @@ import type {
 	ProviderRequestContext,
 	ProviderRuntimeState,
 	ProviderStateDurationString,
+	StateValue,
 } from "../types.js";
 
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV =
@@ -359,9 +360,29 @@ async function parseServerStoredChoice(options: {
 		storage,
 		contextState: options.contextState,
 	});
-	const record = await namespace.get<ProviderChoiceTokenPayload>(
-		optionsStateKey(options.handle.state_id),
-	);
+	// Reading a server-stored choice back deserializes a persisted value. A
+	// corrupt/undecodable value would otherwise surface as a raw JSON.parse
+	// SyntaxError (or another unexpected throwable) that escapes the choice error
+	// taxonomy, gets masked as internal_error 500, and is treated as retryable by
+	// the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+	// Convert any non-branded throwable into a branded invalid_payload so it maps
+	// to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+	// ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+	// their category/retryable semantics are preserved.
+	let record: StateValue<ProviderChoiceTokenPayload> | null;
+	try {
+		record = await namespace.get<ProviderChoiceTokenPayload>(
+			optionsStateKey(options.handle.state_id),
+		);
+	} catch (error) {
+		if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+			throw error;
+		}
+		throw new ProviderChoiceTokenError(
+			"invalid_payload",
+			"Provider choice token state payload could not be decoded.",
+		);
+	}
 	if (!record) {
 		throw new ProviderChoiceTokenError(
 			"invalid_payload",

package/src/runtime/http.ts

@@ -1,5 +1,9 @@
 import type { ProxyResolutionOptions } from "../config/loader.js";
-import { resolveProxyConfigAsync } from "../config/loader.js";
+import {
+	policyRotatesTransportVendorChain,
+	resolvePolicyTransportAttemptCap,
+	resolveProxyConfigAsync,
+} from "../config/loader.js";
 import { ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import type {
@@ -8,6 +12,7 @@ import type {
 	HttpResponse,
 	HttpRetrySummary,
 	HttpStreamResponse,
+	ProviderProxyPolicy,
 	RequestOptions,
 	RequestWithMethodOptions,
 	SseMessage,
@@ -41,16 +46,28 @@ type HttpStatusOutcome = {
 	proxyUsed: boolean;
 };
 
-type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome;
+/**
+ * Sentinel returned when a policy-allocator attempt resolved an endpoint that a
+ * prior attempt already tried (an under-filled pool repeats endpoints via the
+ * modulo mapping before the flat offset crosses into the next vendor). The retry
+ * loop advances to the next offset rather than re-issuing the request — but does
+ * NOT treat it as chain exhaustion, so the offset still walks into the fallback
+ * vendor's span.
+ */
+type NativeHttpSkipOutcome = { kind: "dedupe-skip" };
+
+type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome | NativeHttpSkipOutcome;
 
 type NativeHttpAttemptError = TransportError & { proxyUsed?: boolean };
 
-function isHttpStatusOutcome(
-	outcome: HttpResponse | HttpStatusOutcome,
-): outcome is HttpStatusOutcome {
+function isHttpStatusOutcome(outcome: NativeHttpAttemptOutcome): outcome is HttpStatusOutcome {
 	return "kind" in outcome && outcome.kind === "http-status";
 }
 
+function isDedupeSkipOutcome(outcome: NativeHttpAttemptOutcome): outcome is NativeHttpSkipOutcome {
+	return "kind" in outcome && outcome.kind === "dedupe-skip";
+}
+
 async function sleep(ms: number): Promise<void> {
 	if (ms <= 0) return;
 	await new Promise((resolve) => setTimeout(resolve, ms));
@@ -256,6 +273,9 @@ async function resolveNativeProxy(
 			baseProxyAttempt: clientOptions.proxyAttempt,
 			retryAttemptOffset: proxyAttemptOffset,
 		}),
+		// Bun's native fetch proxy option tunnels HTTP CONNECT only; SOCKS5 is not
+		// supported here, so a socks5 policy fails loudly rather than downgrading.
+		transportProtocols: ["http"],
 		telemetry: clientOptions.telemetry,
 	});
 	if (resolvedProxy.shouldWarn) {
@@ -294,6 +314,7 @@ async function fetchNativeHttp(
 	warn: (message: string) => void,
 	statusRetryCodes?: readonly number[],
 	proxyAttemptOffset = 0,
+	dedupe?: { attempted: Set<string> },
 ): Promise<NativeHttpAttemptOutcome> {
 	const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
 	const controller = options.timeout ? new AbortController() : undefined;
@@ -303,7 +324,20 @@ async function fetchNativeHttp(
 
 	let proxy: string | undefined;
 	try {
+		// Resolve inside the try (and after the timeout is armed) so allocator
+		// failures are branded as TransportErrors and count against the request
+		// deadline, exactly as an inline resolve would.
 		proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
+		// For a registry allocator chain, skip an endpoint a prior attempt already
+		// tried rather than re-issuing the same request. Returning the sentinel
+		// (instead of breaking) lets the loop keep advancing the flat offset until
+		// it crosses into the fallback vendor's pool span.
+		if (dedupe && proxy) {
+			if (dedupe.attempted.has(proxy)) {
+				return { kind: "dedupe-skip" };
+			}
+			dedupe.attempted.add(proxy);
+		}
 		const requestInit: NativeFetchInit = {
 			headers: options.headers,
 			method,
@@ -449,6 +483,58 @@ export function createHttpClient(
 			? { ...headersOptions, throwOnHttpError: false }
 			: headersOptions;
 
+		// Span the whole vendor chain on transport failures. Like ctx.stealth, a
+		// policy-managed proxy resolves a *different* endpoint/vendor per attempt
+		// (the flat proxyAttemptOffset rotates across the concatenated vendor pool
+		// spans), so a transport failure should advance to the next endpoint —
+		// potentially crossing into the fallback vendor — rather than stopping at
+		// the per-endpoint retry budget and stranding the request on the primary
+		// vendor. resolvePolicyTransportAttemptCap widens the cap to the chain span
+		// only for implicit, safe-method allocator requests; explicit retry
+		// policies (their documented `attempts` ceiling), unsafe methods, and
+		// static/non-registry vendors keep the retry budget. Status-code retries
+		// stay bounded by the retry budget regardless; only transport rotation gets
+		// the full span.
+		const policyProxy: ProviderProxyPolicy | undefined = (() => {
+			const policy = clientOptions.proxyPolicy ?? clientOptions.upstream?.proxy;
+			return policy && typeof policy === "object" ? policy : undefined;
+		})();
+		const usesPolicyAllocator = Boolean(policyProxy) && !options.proxy && !clientOptions.proxy;
+		const transportAttemptCap = retryOptions
+			? resolvePolicyTransportAttemptCap({
+					policy: policyProxy,
+					usesPolicyAllocator,
+					retryAttempts: retryOptions.attempts,
+					explicitRetry,
+					method: methodName,
+				})
+			: 1;
+
+		// Track resolved endpoints across a policy-allocator chain. Successive
+		// attempts rotate the flat offset across the concatenated vendor pool
+		// spans, but an under-filled allocation (fewer live endpoints than the
+		// configured pool size) makes the modulo mapping repeat endpoints before
+		// the offset reaches the next vendor. Rather than re-hammering an
+		// already-tried endpoint under backoff, fetchNativeHttp returns a skip
+		// sentinel for a duplicate; the loop then advances the flat offset without
+		// issuing the request, so it keeps walking toward — and into — the fallback
+		// vendor's pool span instead of stalling on the primary vendor.
+		// De-duplication is gated on the SAME predicate that widens the attempt cap
+		// (implicit, safe-method, registry-chain rotation). It must NOT engage for
+		// an explicit retry policy: there the caller's `attempts` count is the
+		// contract and each attempt must issue against whatever endpoint it resolves
+		// — even a repeat — instead of being silently skipped (which would collapse
+		// a `poolSize: 1` + `attempts: 3` request to a single fetch).
+		const dedupeAllocatorEndpoints = policyRotatesTransportVendorChain({
+			policy: policyProxy,
+			usesPolicyAllocator,
+			explicitRetry,
+			method: methodName,
+		});
+		const dedupeContext = dedupeAllocatorEndpoints
+			? { attempted: new Set<string>() }
+			: undefined;
+
 		const executeOnce = (proxyAttemptOffset = 0): Promise<NativeHttpAttemptOutcome> =>
 			fetchNativeHttp(
 				baseUrl,
@@ -459,24 +545,52 @@ export function createHttpClient(
 				warnOnce,
 				statusRetryEnabled ? retryOptions?.statusCodes : undefined,
 				proxyAttemptOffset,
+				dedupeContext,
 			);
 
 		if (!retryEnabled || !retryOptions) {
 			const outcome = await executeOnce();
+			if (isDedupeSkipOutcome(outcome)) {
+				// Single-shot path never de-duplicates (dedupeContext is undefined),
+				// but keep the union total.
+				throw new TransportError("HTTP request produced no terminal result", {
+					code: "retry_exhausted",
+				});
+			}
 			if (isHttpStatusOutcome(outcome)) {
 				throw toUpstreamHttpError(outcome.status);
 			}
 			return outcome;
 		}
 
+		let lastError: unknown;
 		let lastErrorCode: string | undefined;
 		let lastStatus: number | undefined;
-		for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
+		// `attempt` walks the flat proxy offset across the full chain span; `issued`
+		// counts requests that were actually sent (skipped duplicate offsets do not
+		// increment it). Retry summaries and the status-retry budget must reflect
+		// issued requests, not the raw offset, so they stay accurate when partial
+		// allocations skip offsets.
+		let issued = 0;
+		for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+			// Whether this offset actually issued a request (vs. a skipped duplicate),
+			// so the catch counts a thrown *transport* failure once without
+			// double-counting a status outcome that already incremented before it
+			// re-threw as an upstream HTTP error.
+			let issuedThisAttempt = false;
 			try {
 				const outcome = await executeOnce(attempt - 1);
+				if (isDedupeSkipOutcome(outcome)) {
+					// Duplicate endpoint from a partial allocation: advance the flat
+					// offset without issuing the request (no backoff, not a failure) so
+					// the loop keeps rotating toward the fallback vendor.
+					continue;
+				}
+				issued += 1;
+				issuedThisAttempt = true;
 				if (isHttpStatusOutcome(outcome)) {
 					lastStatus = outcome.status;
-					if (outcome.retryable && attempt < retryOptions.attempts) {
+					if (outcome.retryable && issued < retryOptions.attempts) {
 						await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
 						continue;
 					}
@@ -488,10 +602,10 @@ export function createHttpClient(
 					throw toUpstreamHttpError(response.status);
 				}
 
-				if (attempt > 1) {
+				if (issued > 1) {
 					const summary: HttpRetrySummary = {
-						attempts: attempt,
-						retries: attempt - 1,
+						attempts: issued,
+						retries: issued - 1,
 						...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
 						transport: "native",
 						...(lastErrorCode ? { lastErrorCode } : {}),
@@ -501,11 +615,13 @@ export function createHttpClient(
 				}
 				return response;
 			} catch (error) {
+				if (!issuedThisAttempt) issued += 1;
+				lastError = error;
 				lastErrorCode = proxyTransportRetryErrorCode(error);
 				lastStatus = proxyTransportRetryErrorStatus(error);
 				const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
 				if (
-					attempt < retryOptions.attempts &&
+					attempt < transportAttemptCap &&
 					shouldRetryProxyTransportAttempt({
 						error,
 						explicitRetry,
@@ -521,6 +637,13 @@ export function createHttpClient(
 			}
 		}
 
+		// Reached when the attempt cap is consumed without a terminal outcome —
+		// e.g. the final offsets of a partial allocation all resolved to
+		// already-tried endpoints and were skipped. Surface the last real transport
+		// failure rather than a synthetic exhaustion error.
+		if (lastError !== undefined) {
+			throw lastError;
+		}
 		throw new TransportError("HTTP retry exhausted without a terminal result", {
 			code: "retry_exhausted",
 		});

package/src/runtime/proxy-errors.ts

@@ -19,10 +19,18 @@ const PROXY_AUTH_IP_DENIED_PATTERN =
 	/\b(?:source|egress|client)\s+ip\b.{0,120}\b(?:deny|denied|unauthori[sz]ed|not\s+authori[sz]ed|white\s*list|allow\s*list)\b|\b(?:white\s*list|allow\s*list)\b.{0,120}\b(?:source|egress|client)\s+ip\b/i;
 const PROXY_EDGE_AUTH_REJECTED_PATTERN =
 	/\bauth\s+ip\s+err\b|\bproxy\b.{0,120}\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b|\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b.{0,120}\bproxy\b/i;
-const PROXY_POOL_STALE_MESSAGE_PATTERN =
-	/\bproxy\b.{0,120}\b(?:pool|lease|expired|unavailable|exhausted|non[\s-]?200\s+code:\s*(?:509|512))\b|\bnon[\s-]?200\s+code:\s*(?:509|512)\b.{0,120}\bproxy\b|\bsmartproxy\b.{0,120}\b(?:509|512)\b/i;
-const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN =
-	/\b(?:smartproxy|proxy)\b.{0,160}\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b|\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b.{0,160}\b(?:smartproxy|proxy)\b/i;
+// Vendor host tokens that can appear in upstream error strings. Adding a proxy
+// vendor updates every classifier below in one place. `proxy` is the generic
+// fallback so vendor-agnostic messages still classify.
+const PROXY_VENDOR_ALTERNATION = "smartproxy|nodemaven|proxy";
+const PROXY_POOL_STALE_MESSAGE_PATTERN = new RegExp(
+	`\\bproxy\\b.{0,120}\\b(?:pool|lease|expired|unavailable|exhausted|non[\\s-]?200\\s+code:\\s*(?:509|512))\\b|\\bnon[\\s-]?200\\s+code:\\s*(?:509|512)\\b.{0,120}\\bproxy\\b|\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,120}\\b(?:509|512)\\b`,
+	"i",
+);
+const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = new RegExp(
+	`\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,160}\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b|\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b.{0,160}\\b(?:${PROXY_VENDOR_ALTERNATION})\\b`,
+	"i",
+);
 
 export function isProxyAuthIpDeniedMessage(message: string): boolean {
 	return PROXY_AUTH_IP_DENIED_PATTERN.test(message);

package/src/runtime/proxy-nodemaven.ts

@@ -0,0 +1,178 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import type { ProviderProxyPolicy } from "../types.js";
+
+export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+
+export const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+
+/** Both schemes tunnel bytes end-to-end, preserving the client TLS handshake. */
+export type ProxyProtocol = "http" | "socks5";
+
+/**
+ * NodeMaven's fastest protocol: HTTP CONNECT. Benchmarks (KR, cold + warm)
+ * showed socks5 through the gateway adds ~500ms per request over http, so
+ * NodeMaven never defaults to socks5.
+ */
+export const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol = "http";
+
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS: Record<ProxyProtocol, { min: number; max: number }> = {
+	http: { min: 8080, max: 9080 },
+	socks5: { min: 1080, max: 2080 },
+};
+
+const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
+const DEFAULT_NODEMAVEN_FILTER = "medium";
+const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
+/** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
+const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
+const SID_LENGTH = 10;
+
+export function hasNodemavenCredentials(): boolean {
+	return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+
+function readNodemavenUsername(): string | undefined {
+	return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+
+function readNodemavenPassword(): string | undefined {
+	return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+
+function resolveNodemavenFilter(): string {
+	const raw = process.env[NODEMAVEN_FILTER_ENV]?.trim().toLowerCase();
+	if (!raw) return DEFAULT_NODEMAVEN_FILTER;
+	if (!NODEMAVEN_FILTERS.has(raw)) {
+		throw new Error(`${NODEMAVEN_FILTER_ENV} must be "medium" or "high"`);
+	}
+	return raw;
+}
+
+export function nodemavenPoolSize(policy: ProviderProxyPolicy): number {
+	return Math.min(
+		NODEMAVEN_MAX_POOL_SIZE,
+		Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)),
+	);
+}
+
+function nodemavenLifetimeMinutes(policy: ProviderProxyPolicy): number {
+	const configured = policy.session?.lifetimeMinutes;
+	if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+		return NODEMAVEN_MAX_LIFETIME_MINUTES;
+	}
+	return Math.min(NODEMAVEN_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configured)));
+}
+
+/** NodeMaven username tokens accept `[a-z0-9]`; slugify geo values to that set. */
+function slugifyGeo(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const slug = value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "");
+	return slug || undefined;
+}
+
+function isStickyAffinity(policy: ProviderProxyPolicy): boolean {
+	return (policy.session?.affinity ?? "request") !== "request";
+}
+
+/**
+ * A sticky sid is deterministic from the affinity key so every process serving
+ * the same connection derives the same egress IP without shared storage. A
+ * rotating sid is random per call (a fresh egress IP per request).
+ */
+function deriveSid(
+	policy: ProviderProxyPolicy,
+	affinityKey: string | undefined,
+	poolIndex: number,
+	refreshEpoch: number,
+): string {
+	if (!isStickyAffinity(policy) || !affinityKey) {
+		return randomBytes(SID_LENGTH).toString("hex").slice(0, SID_LENGTH);
+	}
+	const digest = createHash("sha256")
+		.update(`${affinityKey}:${refreshEpoch}:${poolIndex}`)
+		.digest("hex");
+	// hex digits are a subset of the allowed [a-z0-9] sid charset.
+	return digest.slice(0, SID_LENGTH);
+}
+
+function selectPort(protocol: ProxyProtocol, sid: string, poolIndex: number): number {
+	const { min, max } = NODEMAVEN_PORTS[protocol];
+	const span = max - min + 1;
+	const hashInt = Number.parseInt(
+		createHash("sha256").update(`${sid}:${poolIndex}`).digest("hex").slice(0, 8),
+		16,
+	);
+	return min + (hashInt % span);
+}
+
+export type NodemavenSynthesisInput = {
+	policy: ProviderProxyPolicy;
+	affinityKey: string | undefined;
+	protocol: ProxyProtocol;
+	poolIndex: number;
+	refreshEpoch: number;
+	/** ISO 3166-1 alpha-2, already resolved by the caller (falls back to env). */
+	country?: string;
+};
+
+export type NodemavenSynthesis = {
+	url: string;
+	protocol: ProxyProtocol;
+	diagnostics: Record<string, string | number | boolean>;
+};
+
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export function synthesizeNodemavenProxy(input: NodemavenSynthesisInput): NodemavenSynthesis {
+	const username = readNodemavenUsername();
+	const password = readNodemavenPassword();
+	if (!username || !password) {
+		throw new Error(
+			`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`,
+		);
+	}
+
+	const filter = resolveNodemavenFilter();
+	const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
+	const port = selectPort(input.protocol, sid, input.poolIndex);
+	const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);
+
+	const country = slugifyGeo(input.country ?? input.policy.geo?.country);
+	const region = slugifyGeo(input.policy.geo?.subdivision);
+	const city = slugifyGeo(input.policy.geo?.city);
+
+	const tokens = [username];
+	if (country) tokens.push("country", country);
+	if (region) tokens.push("region", region);
+	if (city) tokens.push("city", city);
+	tokens.push("sid", sid);
+	tokens.push("filter", filter);
+	tokens.push("ipv4", "true");
+	const proxyUsername = tokens.join("-");
+
+	// Username tokens are [a-z0-9-] only, which survive URL encoding unchanged.
+	const url = `${input.protocol}://${proxyUsername}:${encodeURIComponent(password)}@${NODEMAVEN_GATEWAY_HOST}:${port}`;
+
+	return {
+		url,
+		protocol: input.protocol,
+		diagnostics: {
+			vendor: "nodemaven",
+			protocol: input.protocol,
+			sticky: isStickyAffinity(input.policy),
+			filter,
+			lifetimeMinutes,
+			...(country ? { country } : {}),
+		},
+	};
+}