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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.8
+
+- Release candidate for main commit 9e8a3f028ee78b9cab29d4aa3f5494ac9cffa65f.
+
 ## 2.2.0-beta.7
 
 - Release candidate for main commit 2ce4ea4bd36ce333eba8b3b474bf6e82b5e9216c.

package/dist/auth-turn/index.d.ts

@@ -87,7 +87,7 @@ export declare const AUTH_TURN_SCHEMA: {
     };
     readonly $defs: {
         readonly completeTurnData: {
-            readonly title: 'Terminal payload for kind "complete"';
+            readonly title: "Terminal payload for kind \"complete\"";
             readonly description: "data payload of a complete turn. The gateway extracts data.credential for persistence; complete turns are never echoed to browsers.";
             readonly type: "object";
             readonly additionalProperties: true;
@@ -104,7 +104,7 @@ export declare const AUTH_TURN_SCHEMA: {
             };
         };
         readonly abortTurnData: {
-            readonly title: 'Terminal payload for kind "abort"';
+            readonly title: "Terminal payload for kind \"abort\"";
             readonly description: "data payload of an abort turn. code, when present, is the machine-readable abort reason.";
             readonly type: "object";
             readonly additionalProperties: true;

package/dist/config/loader.d.ts

@@ -1,5 +1,9 @@
 import { Redis } from "ioredis";
 import type { ProviderProxyPolicy, TraceConfig } from "../types.js";
+import { type ProxyProtocol } from "../runtime/proxy-nodemaven.js";
+export type { ProxyProtocol } from "../runtime/proxy-nodemaven.js";
+/** Proxy vendors the SDK resolves natively (as opposed to the static env path). */
+export type ProxyVendorName = "smartproxy" | "nodemaven";
 export declare const SMARTPROXY_APP_KEY_ENV = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 export declare const SMARTPROXY_MAX_LIFETIME_MINUTES = 2000;
 export declare const DEFAULT_SMARTPROXY_POOL_SIZE = 20;
@@ -42,12 +46,33 @@ export type ProxyResolutionOptions = {
     affinityKey?: string;
     /** Zero-based proxy-pool attempt index used by SDK transports for failover. */
     proxyAttempt?: number;
+    /**
+     * Tunnelling protocols the calling transport can use. When a resolved
+     * protocol is not in this set the resolver fails with
+     * `PROXY_PROTOCOL_UNSUPPORTED` instead of silently downgrading. Unset means
+     * permissive (both protocols allowed).
+     */
+    transportProtocols?: readonly ProxyProtocol[];
+    /**
+     * Explicit protocol override. Internal — for the verification harness and
+     * tests, or an advanced caller. Normal callers omit it and each vendor uses
+     * its own benchmarked default protocol (see VENDOR_DEFAULT_PROTOCOL). Not an
+     * env var and not a provider-policy field.
+     */
+    protocol?: ProxyProtocol;
+    /**
+     * Gateway pool "refresh" generation. Bumped by transports on pool refresh to
+     * derive a fresh gateway session set (ignored by allocation-style vendors,
+     * whose refresh is driven by cache invalidation).
+     */
+    proxyRefreshEpoch?: number;
     telemetry?: ProxyTelemetrySink;
 };
 export type ProxyCacheStatus = "memory_hit" | "redis_hit" | "allocator" | "soft_stale_refresh" | "lock_wait" | "redis_error" | "redis_corrupt" | "disabled";
 export type SmartproxyAllocatorBodyClass = "network_error" | "http_error" | "empty" | "json_without_proxies" | "text_without_proxies" | "usable_proxy_endpoints";
 export type ProxyResolutionTelemetryEvent = {
-    provider: "smartproxy";
+    provider: ProxyVendorName;
+    protocol?: ProxyProtocol;
     cacheStatus: ProxyCacheStatus;
     cacheHit: boolean;
     resolutionMs: number;
@@ -64,7 +89,7 @@ export type ProxyResolutionTelemetryEvent = {
     refreshes?: number;
 };
 export type ProxyAttemptTelemetryEvent = {
-    provider: "smartproxy";
+    provider: ProxyVendorName;
     attempt: number;
     poolIndex?: number;
     proxyHash?: string;
@@ -73,22 +98,40 @@ export type ProxyAttemptTelemetryEvent = {
     status?: number;
     durationMs?: number;
 };
+export type ProxyVendorFailoverTelemetryEvent = {
+    /** Vendor that failed or was skipped. */
+    vendor: ProxyVendorName;
+    /** Vendor tried next, or undefined when the chain is exhausted. */
+    nextVendor?: ProxyVendorName;
+    phase: "resolution" | "transport";
+    reason: "no_credentials" | "allocation_failed" | "pool_exhausted" | "protocol_unsupported";
+    attempt?: number;
+};
 export type ProxyTelemetrySink = {
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
     recordProxyAttempt?(event: ProxyAttemptTelemetryEvent): void;
+    recordProxyVendorFailover?(event: ProxyVendorFailoverTelemetryEvent): void;
 };
 export type ResolvedProxyConfig = {
     shouldWarn: boolean;
     url?: string;
-    source?: "explicit" | "env" | "config" | "smartproxy-allocator";
+    source?: "explicit" | "env" | "config" | "smartproxy-allocator" | "nodemaven-gateway";
+    protocol?: ProxyProtocol;
     diagnostics?: Record<string, string | number | boolean>;
 };
+export type ProxyResolutionErrorCode = "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED" | "PROXY_PROTOCOL_UNSUPPORTED";
 export declare class ProxyResolutionError extends Error {
-    readonly code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED";
+    readonly code: ProxyResolutionErrorCode;
     readonly telemetry?: ProxyResolutionTelemetryEvent;
-    constructor(code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED", message: string, options?: {
+    readonly vendor?: ProxyVendorName;
+    readonly vendorChain?: ProxyVendorName[];
+    readonly protocol?: ProxyProtocol;
+    constructor(code: ProxyResolutionErrorCode, message: string, options?: {
         cause?: unknown;
         telemetry?: ProxyResolutionTelemetryEvent;
+        vendor?: ProxyVendorName;
+        vendorChain?: ProxyVendorName[];
+        protocol?: ProxyProtocol;
     });
 }
 type ProxyRedisClient = Pick<Redis, "connect" | "del" | "eval" | "get" | "on" | "pttl" | "set" | "status">;
@@ -99,9 +142,39 @@ export declare function __setProxyRedisForTests(redis: ProxyRedisClient | undefi
 export declare function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number | undefined): void;
 export declare function resolveProxyConfig(options?: ProxyResolutionOptions): ResolvedProxyConfig;
 export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * Guard the No-MITM invariant: a resolved proxy URL must use a tunnelling scheme
+ * (http CONNECT or socks5) so the client TLS handshake reaches the origin
+ * end-to-end. Anything else would intercept TLS and break fingerprinting.
+ */
+export declare function assertTunnelingScheme(url: string): void;
+/**
+ * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
+ * takes precedence over the legacy singular `provider`; the platform default
+ * env is the final fallback. Non-registry names (decodo/custom) are dropped so
+ * an all-static chain falls through to the legacy env-URL path unchanged.
+ */
+export declare function resolveVendorChain(policy: ProviderProxyPolicy): ProxyVendorName[];
+/**
+ * Total attempt span across a policy's vendor chain — the sum of each vendor's
+ * pool size. Transports use this so successive attempts rotate a vendor's pool
+ * and then fail over to the next vendor via the flat attempt index. With one
+ * vendor this equals that vendor's pool size (today's behaviour).
+ */
+export declare function resolvePolicyProxyPoolSpan(policy: ProviderProxyPolicy): number;
+/** Map a resolved proxy source label to the vendor that served it. */
+export declare function vendorFromResolvedSource(source: ResolvedProxyConfig["source"]): ProxyVendorName | undefined;
+/**
+ * Map a flat attempt index into (vendorIndex, poolIndex) by concatenating each
+ * vendor's pool space in chain order. With a single vendor this reduces to
+ * `attempt % poolSize`, preserving today's behaviour exactly.
+ */
+export declare function mapFlatAttempt(flat: number, sizes: readonly number[]): {
+    vendorIndex: number;
+    poolIndex: number;
+};
 export declare function clearProxyResolutionCache(): void;
 export declare function invalidateProxyResolutionCache(options?: ProxyResolutionOptions): boolean;
 export declare function invalidateProxyResolutionCacheAsync(options?: ProxyResolutionOptions): Promise<boolean>;
 export declare function defineConfig(config: ApiFuseConfig): ApiFuseConfig;
 export declare function loadApiFuseConfig(dir?: string): Promise<ApiFuseConfig>;
-export {};

package/dist/config/loader.js

@@ -2,6 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { Redis } from "ioredis";
+import { NODEMAVEN_DEFAULT_PROTOCOL, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
+// "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
+// extraction API (app_key → raw ip:port pool). It is NOT the company formerly
+// named Smartproxy (smartproxy.com), which rebranded to Decodo in 2025 and is
+// modelled separately as the `decodo` gateway vendor. Do not conflate them.
 export const SMARTPROXY_APP_KEY_ENV = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 export const SMARTPROXY_MAX_LIFETIME_MINUTES = 2000;
 export const DEFAULT_SMARTPROXY_POOL_SIZE = 20;
@@ -15,11 +20,17 @@ export const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
 export class ProxyResolutionError extends Error {
     code;
     telemetry;
+    vendor;
+    vendorChain;
+    protocol;
     constructor(code, message, options) {
         super(message, options);
         this.name = "ProxyResolutionError";
         this.code = code;
         this.telemetry = options?.telemetry;
+        this.vendor = options?.vendor;
+        this.vendorChain = options?.vendorChain;
+        this.protocol = options?.protocol;
     }
 }
 const proxyCache = new Map();
@@ -232,6 +243,11 @@ function applyStickyProxySession(proxyUrl) {
     if (!parsed.hostname || !parsed.username || !parsed.password) {
         return proxyUrl;
     }
+    // This rewrites sticky-session usernames for a bring-your-own *gateway* URL
+    // (APIFUSE__PROXY__URL). The `smartproxy` host here means a smartproxy.com /
+    // Decodo-family gateway that authenticates by username — NOT the
+    // api.smartproxy.org allocation vendor, whose endpoints are raw ip:port with
+    // no credentials and therefore return early above.
     const host = parsed.hostname.toLowerCase();
     if (!host.includes("smartproxy") && !host.includes("decodo")) {
         return proxyUrl;
@@ -299,47 +315,173 @@ export async function resolveProxyConfigAsync(options = {}) {
     if (policy.mode === "disabled") {
         return { shouldWarn: false };
     }
-    const provider = resolveProxyProvider(policy);
-    if (provider !== "smartproxy") {
+    const chain = resolveVendorChain(policy);
+    if (chain.length === 0) {
+        // decodo/custom/env-static providers keep the legacy static-URL path.
         return resolveProxyConfig({
             ...options,
             upstream: { proxy: true },
         });
     }
-    const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
-    if (!appKey) {
-        if (policy.mode === "required") {
-            throw new ProxyResolutionError("PROXY_REQUIRED", `Smartproxy egress is required but ${SMARTPROXY_APP_KEY_ENV} is not configured.`);
+    // Protocol is chosen per vendor (each vendor's benchmarked-best), with an
+    // optional explicit override for the harness/tests. Both are tunnelling
+    // schemes. transportProtocols is what the calling transport can actually use.
+    const transportProtocols = options.transportProtocols ?? ["http", "socks5"];
+    const sizes = chain.map((vendor) => vendorPoolSize(vendor, policy));
+    const total = sizes.reduce((sum, size) => sum + size, 0);
+    const normalizedAttempt = normalizeAttemptIndex(options.proxyAttempt);
+    const { vendorIndex: startVendorIndex, poolIndex: startPoolIndex } = mapFlatAttempt(total > 0 ? normalizedAttempt % total : 0, sizes);
+    const refreshEpoch = normalizeAttemptIndex(options.proxyRefreshEpoch);
+    let lastError;
+    let blockedProtocol;
+    for (let vendorIndex = startVendorIndex; vendorIndex < chain.length; vendorIndex++) {
+        const vendor = chain[vendorIndex];
+        const nextVendor = chain[vendorIndex + 1];
+        const poolIndex = vendorIndex === startVendorIndex ? startPoolIndex : 0;
+        const protocol = options.protocol ?? VENDOR_DEFAULT_PROTOCOL[vendor];
+        if (!vendorHasCredentials(vendor)) {
+            options.telemetry?.recordProxyVendorFailover?.({
+                vendor,
+                nextVendor,
+                phase: "resolution",
+                reason: "no_credentials",
+            });
+            continue;
+        }
+        // The calling transport must be able to use this vendor's protocol; if not,
+        // fail over to the next vendor rather than silently downgrading.
+        if (!transportProtocols.includes(protocol)) {
+            blockedProtocol = protocol;
+            options.telemetry?.recordProxyVendorFailover?.({
+                vendor,
+                nextVendor,
+                phase: "resolution",
+                reason: "protocol_unsupported",
+            });
+            continue;
+        }
+        try {
+            return await resolveWithVendor(vendor, policy, options, {
+                protocol,
+                poolIndex,
+                refreshEpoch,
+            });
+        }
+        catch (error) {
+            // Config/programming errors (invalid filter, etc.) are not vendor
+            // outages — propagate them rather than failing over.
+            if (!(error instanceof ProxyResolutionError)) {
+                throw error;
+            }
+            if (error.telemetry) {
+                options.telemetry?.recordProxyResolution(error.telemetry);
+            }
+            lastError = error;
+            options.telemetry?.recordProxyVendorFailover?.({
+                vendor,
+                nextVendor,
+                phase: "resolution",
+                reason: "allocation_failed",
+            });
         }
-        return { shouldWarn: true };
     }
-    const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+    if (policy.mode === "required") {
+        if (lastError) {
+            throw lastError instanceof ProxyResolutionError
+                ? lastError
+                : new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `All proxy vendors [${chain.join(", ")}] failed for required proxy egress.`, { cause: lastError, vendorChain: chain });
+        }
+        if (blockedProtocol) {
+            throw new ProxyResolutionError("PROXY_PROTOCOL_UNSUPPORTED", `No proxy vendor in [${chain.join(", ")}] could serve a protocol supported by this transport (supports: ${transportProtocols.join(", ")}; vendor wanted "${blockedProtocol}"). Route this provider through the stealth transport.`, { protocol: blockedProtocol, vendorChain: chain });
+        }
+        throw new ProxyResolutionError("PROXY_REQUIRED", `Proxy egress is required but no vendor credentials are configured. Missing: ${chain
+            .map((vendor) => `${missingCredentialEnv(vendor)} (${vendor})`)
+            .join(", ")}.`, { vendorChain: chain });
+    }
+    return { shouldWarn: true };
+}
+/**
+ * Each vendor's default egress protocol, chosen from live KR benchmarks. HTTP
+ * CONNECT wins for nodemaven (socks5 adds ~500ms through the gateway) and ties
+ * for smartproxy, and is the only protocol ctx.http (Bun native fetch) supports.
+ * Override per call via ProxyResolutionOptions.protocol (harness/tests).
+ */
+const VENDOR_DEFAULT_PROTOCOL = {
+    smartproxy: "http",
+    nodemaven: NODEMAVEN_DEFAULT_PROTOCOL,
+};
+/**
+ * Guard the No-MITM invariant: a resolved proxy URL must use a tunnelling scheme
+ * (http CONNECT or socks5) so the client TLS handshake reaches the origin
+ * end-to-end. Anything else would intercept TLS and break fingerprinting.
+ */
+export function assertTunnelingScheme(url) {
+    let scheme;
     try {
-        const allocated = await allocateSmartproxy(policy, appKey, lifetimeMinutes, options.affinityKey);
-        options.telemetry?.recordProxyResolution(allocated.telemetry);
-        const poolIndex = selectProxyPoolIndex(allocated.pool.urls.length, options.proxyAttempt);
+        scheme = new URL(url).protocol.replace(/:$/, "").toLowerCase();
+    }
+    catch {
+        throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `Malformed proxy URL: ${url}`);
+    }
+    if (scheme !== "http" && scheme !== "socks5") {
+        throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `Resolved proxy scheme "${scheme}" is not a tunnelling scheme (expected http or socks5). Refusing to route TLS through a non-tunnelling proxy.`);
+    }
+}
+async function resolveWithVendor(vendor, policy, options, context) {
+    if (vendor === "nodemaven") {
+        const startedAt = Date.now();
+        const synthesized = synthesizeNodemavenProxy({
+            policy,
+            affinityKey: options.affinityKey,
+            protocol: context.protocol,
+            poolIndex: context.poolIndex,
+            refreshEpoch: context.refreshEpoch,
+            country: resolveSmartproxyCountry(policy),
+        });
+        options.telemetry?.recordProxyResolution({
+            provider: "nodemaven",
+            protocol: synthesized.protocol,
+            cacheStatus: "disabled",
+            cacheHit: false,
+            resolutionMs: Math.max(0, Date.now() - startedAt),
+            attempts: 1,
+        });
+        assertTunnelingScheme(synthesized.url);
         return {
             shouldWarn: false,
-            url: allocated.pool.urls[poolIndex],
-            source: "smartproxy-allocator",
+            url: synthesized.url,
+            source: "nodemaven-gateway",
+            protocol: synthesized.protocol,
             diagnostics: {
-                ...allocated.pool.diagnostics,
-                poolSize: allocated.pool.urls.length,
-                poolIndex,
+                ...synthesized.diagnostics,
+                poolIndex: context.poolIndex,
             },
         };
     }
-    catch (error) {
-        if (error instanceof ProxyResolutionError && error.telemetry) {
-            options.telemetry?.recordProxyResolution(error.telemetry);
-        }
-        if (policy.mode === "required") {
-            throw error instanceof ProxyResolutionError
-                ? error
-                : new ProxyResolutionError("PROXY_ALLOCATION_FAILED", "Smartproxy allocator failed for required proxy egress.", { cause: error });
-        }
-        return { shouldWarn: true };
+    // smartproxy allocation-style vendor.
+    const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+    if (!appKey) {
+        // Guarded by vendorHasCredentials; treated as a vendor-internal failure.
+        throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `${SMARTPROXY_APP_KEY_ENV} is not configured.`, { vendor: "smartproxy" });
     }
+    const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+    const allocated = await allocateSmartproxy(policy, appKey, lifetimeMinutes, options.affinityKey, context.protocol);
+    options.telemetry?.recordProxyResolution({ ...allocated.telemetry, protocol: context.protocol });
+    const poolIndex = selectProxyPoolIndex(allocated.pool.urls.length, context.poolIndex);
+    const url = allocated.pool.urls[poolIndex];
+    if (url)
+        assertTunnelingScheme(url);
+    return {
+        shouldWarn: false,
+        url,
+        source: "smartproxy-allocator",
+        protocol: context.protocol,
+        diagnostics: {
+            ...allocated.pool.diagnostics,
+            poolSize: allocated.pool.urls.length,
+            poolIndex,
+        },
+    };
 }
 function resolvePolicy(options) {
     if (options.proxyPolicy) {
@@ -351,8 +493,80 @@ function resolvePolicy(options) {
     }
     return undefined;
 }
-function resolveProxyProvider(policy) {
-    return (policy.provider ?? process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase() ?? "custom");
+function isRegistryVendor(name) {
+    return name === "smartproxy" || name === "nodemaven";
+}
+/**
+ * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
+ * takes precedence over the legacy singular `provider`; the platform default
+ * env is the final fallback. Non-registry names (decodo/custom) are dropped so
+ * an all-static chain falls through to the legacy env-URL path unchanged.
+ */
+export function resolveVendorChain(policy) {
+    const declared = policy.providers?.length
+        ? policy.providers
+        : [policy.provider ?? envDefaultProvider()];
+    const chain = [];
+    for (const name of declared) {
+        if (isRegistryVendor(name) && !chain.includes(name)) {
+            chain.push(name);
+        }
+    }
+    return chain;
+}
+function envDefaultProvider() {
+    const raw = process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase();
+    return raw ?? undefined;
+}
+function vendorHasCredentials(vendor) {
+    if (vendor === "nodemaven")
+        return hasNodemavenCredentials();
+    return Boolean(process.env[SMARTPROXY_APP_KEY_ENV]?.trim());
+}
+function missingCredentialEnv(vendor) {
+    return vendor === "nodemaven" ? "APIFUSE__PROXY__NODEMAVEN_USERNAME" : SMARTPROXY_APP_KEY_ENV;
+}
+function vendorPoolSize(vendor, policy) {
+    return vendor === "nodemaven" ? nodemavenPoolSize(policy) : resolveSmartproxyPoolSize(policy);
+}
+/**
+ * Total attempt span across a policy's vendor chain — the sum of each vendor's
+ * pool size. Transports use this so successive attempts rotate a vendor's pool
+ * and then fail over to the next vendor via the flat attempt index. With one
+ * vendor this equals that vendor's pool size (today's behaviour).
+ */
+export function resolvePolicyProxyPoolSpan(policy) {
+    const chain = resolveVendorChain(policy);
+    if (chain.length === 0)
+        return resolveSmartproxyPoolSize(policy);
+    return chain.reduce((sum, vendor) => sum + vendorPoolSize(vendor, policy), 0);
+}
+/** Map a resolved proxy source label to the vendor that served it. */
+export function vendorFromResolvedSource(source) {
+    if (source === "nodemaven-gateway")
+        return "nodemaven";
+    if (source === "smartproxy-allocator")
+        return "smartproxy";
+    return undefined;
+}
+function normalizeAttemptIndex(attempt) {
+    return Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
+}
+/**
+ * Map a flat attempt index into (vendorIndex, poolIndex) by concatenating each
+ * vendor's pool space in chain order. With a single vendor this reduces to
+ * `attempt % poolSize`, preserving today's behaviour exactly.
+ */
+export function mapFlatAttempt(flat, sizes) {
+    let cursor = flat;
+    for (let vendorIndex = 0; vendorIndex < sizes.length; vendorIndex++) {
+        const size = Math.max(1, sizes[vendorIndex] ?? 1);
+        if (cursor < size) {
+            return { vendorIndex, poolIndex: cursor };
+        }
+        cursor -= size;
+    }
+    return { vendorIndex: 0, poolIndex: 0 };
 }
 function resolveSmartproxyCountry(policy) {
     return (policy.geo?.country ?? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ?? undefined);
@@ -381,10 +595,11 @@ function selectProxyPoolIndex(poolSize, attempt = 0) {
     const normalizedAttempt = Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
     return normalizedAttempt % poolSize;
 }
-function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes) {
+function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol) {
     const poolSize = resolveSmartproxyPoolSize(policy);
     return JSON.stringify({
         provider: "smartproxy",
+        protocol,
         country: resolveSmartproxyCountry(policy),
         affinity: policy.session?.affinity ?? "request",
         affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
@@ -392,8 +607,8 @@ function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes) {
         poolSize,
     });
 }
-async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey) {
-    const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes);
+async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey, protocol) {
+    const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol);
     const startedAt = Date.now();
     const now = startedAt;
     const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
@@ -401,7 +616,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey)
     const cached = proxyCache.get(cacheKey);
     if (!skipCached && cached && isFresh(cached, now)) {
         if (shouldSoftRefresh(cached, now)) {
-            void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes);
+            void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol);
             return {
                 pool: cached,
                 telemetry: telemetryForPool(cached, "soft_stale_refresh", startedAt, {
@@ -429,7 +644,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey)
             }),
         };
     }
-    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt).finally(() => {
+    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol).finally(() => {
         proxyInflight.delete(cacheKey);
     });
     proxyInflight.set(cacheKey, promise);
@@ -460,9 +675,9 @@ async function readSmartproxyRedisPool(cacheKey, startedAt) {
         telemetry: telemetryForPool(pool, "redis_hit", startedAt, { redisReadMs }),
     };
 }
-async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes) {
+async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol) {
     try {
-        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), {
+        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), protocol, {
             background: true,
         });
     }
@@ -470,10 +685,10 @@ async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes)
         // Soft refresh is opportunistic; current fresh pool remains usable.
     }
 }
-async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, options = {}) {
+async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, options = {}) {
     const redis = getProxyRedis();
     if (!redis || !(await ensureRedisReady(redis))) {
-        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator" });
+        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator", protocol });
     }
     const poolKey = smartproxyRedisPoolKey(cacheKey);
     const lockKey = smartproxyRedisLockKey(cacheKey);
@@ -487,6 +702,7 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
                     cacheStatus: options.background ? "soft_stale_refresh" : "allocator",
                     redis,
                     poolKey,
+                    protocol,
                 });
             }
             finally {
@@ -599,7 +815,7 @@ async function readSmartproxyAllocatorBodyWithDeadline(response, signal) {
 }
 async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, options) {
     const poolSize = resolveSmartproxyPoolSize(policy);
-    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize);
+    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, options.protocol);
     const allocatorStartedAt = Date.now();
     const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
     let allocation;
@@ -609,7 +825,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
             lastFailure = smartproxyAllocatorDeadlineFailure(attempt);
             break;
         }
-        const attemptResult = await fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, allocatorDeadlineAt);
+        const attemptResult = await fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, allocatorDeadlineAt, options.protocol);
         if (attemptResult.ok) {
             allocation = attemptResult;
             break;
@@ -692,7 +908,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
         }),
     };
 }
-async function fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, deadlineAt) {
+async function fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, deadlineAt, protocol) {
     const { controller, dispose } = createDeadlineAbortController(deadlineAt);
     let response;
     try {
@@ -735,7 +951,7 @@ async function fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, deadlineAt
             bodyClass: "http_error",
         };
     }
-    const urls = parseSmartproxyAllocatorProxies(body);
+    const urls = parseSmartproxyAllocatorProxies(body, protocol);
     const bodyClass = classifySmartproxyAllocatorBody(body, urls);
     if (urls.length === 0) {
         return {
@@ -770,13 +986,20 @@ function smartproxyAllocatorFailureMessage(failure) {
     }
     return "Smartproxy allocator response did not contain a usable proxy endpoint.";
 }
-function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize) {
+// Smartproxy get-ip-v3 `protocol` param: 1 = HTTP. The SOCKS5 value ("2") is a
+// best-effort mapping pending live vendor confirmation; http is the default and
+// the only value exercised in production today.
+const SMARTPROXY_PROTOCOL_PARAM = {
+    http: "1",
+    socks5: "2",
+};
+function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, protocol) {
     const params = new URLSearchParams({
         app_key: appKey,
         pt: "9",
         num: String(poolSize),
         life: String(lifetimeMinutes),
-        protocol: "1",
+        protocol: SMARTPROXY_PROTOCOL_PARAM[protocol],
         format: "txt",
         lb: "\\n",
     });
@@ -788,7 +1011,8 @@ function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize)
     // old path 404s into the marketing site); the API lives on the api host.
     return `https://api.smartproxy.org/web_v1/ip/get-ip-v3?${params.toString()}`;
 }
-function parseSmartproxyAllocatorProxies(body) {
+function parseSmartproxyAllocatorProxies(body, protocol) {
+    const scheme = protocol === "socks5" ? "socks5" : "http";
     const trimmed = body.trim();
     if (!trimmed) {
         return [];
@@ -807,7 +1031,7 @@ function parseSmartproxyAllocatorProxies(body) {
                 const port = "port" in item && (typeof item.port === "string" || typeof item.port === "number")
                     ? item.port
                     : "";
-                return ip && port ? `http://${ip}:${port}` : null;
+                return ip && port ? `${scheme}://${ip}:${port}` : null;
             })
                 .filter((url) => url !== null);
         }
@@ -819,7 +1043,7 @@ function parseSmartproxyAllocatorProxies(body) {
         .split(/\r?\n/)
         .map((item) => item.trim())
         .filter((item) => /^\d{1,3}(?:\.\d{1,3}){3}:\d{2,5}$/.test(item))
-        .map((line) => `http://${line}`);
+        .map((line) => `${scheme}://${line}`);
 }
 function classifySmartproxyAllocatorBody(body, urls) {
     if (urls.length > 0) {
@@ -847,11 +1071,11 @@ function markSmartproxyCacheInvalidated(options = {}) {
     if (!policy || policy.mode === "disabled") {
         return undefined;
     }
-    if (resolveProxyProvider(policy) !== "smartproxy") {
+    if (!resolveVendorChain(policy).includes("smartproxy")) {
         return undefined;
     }
     const lifetimeMinutes = resolveSmartproxyLifetime(policy);
-    const cacheKey = buildSmartproxyCacheKey(policy, options.affinityKey, lifetimeMinutes);
+    const cacheKey = buildSmartproxyCacheKey(policy, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);
     invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
     proxyCache.delete(cacheKey);
     proxyInflight.delete(cacheKey);