@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/dist/config/loader.js

@@ -1,7 +1,12 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import Redis from "ioredis";
+import { Redis } from "ioredis";
+import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_FILTER_ENV, NODEMAVEN_MAX_POOL_SIZE, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, 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();
@@ -160,9 +171,7 @@ function toProxyDiagnostics(value) {
         return undefined;
     const diagnostics = {};
     for (const [key, item] of Object.entries(value)) {
-        if (typeof item === "string" ||
-            typeof item === "number" ||
-            typeof item === "boolean") {
+        if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
             diagnostics[key] = item;
         }
     }
@@ -234,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;
@@ -249,9 +263,7 @@ function applyStickyProxySession(proxyUrl) {
 }
 function buildSmartproxyUsername(username, sessionId, sessionDuration) {
     const parts = username.split("_");
-    const configuredLife = parts
-        .find((part) => part.startsWith("life-"))
-        ?.slice("life-".length);
+    const configuredLife = parts.find((part) => part.startsWith("life-"))?.slice("life-".length);
     const baseUsername = parts
         .filter((part) => !part.startsWith("session-") && !part.startsWith("life-"))
         .join("_");
@@ -259,9 +271,7 @@ function buildSmartproxyUsername(username, sessionId, sessionDuration) {
 }
 function buildDecodoUsername(username, sessionId, sessionDuration) {
     const withoutSticky = username.replace(/-session-.+-sessionduration-\d+$/, "");
-    const baseUsername = withoutSticky.startsWith("user-")
-        ? withoutSticky
-        : `user-${withoutSticky}`;
+    const baseUsername = withoutSticky.startsWith("user-") ? withoutSticky : `user-${withoutSticky}`;
     return `${baseUsername}-session-${sessionId}-sessionduration-${sessionDuration}`;
 }
 function syncProxyEnv(config) {
@@ -305,47 +315,201 @@ 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 };
+}
+/**
+ * Resolve the proxy URL for a provider-owned consumer such as a CAPTCHA solver.
+ * Vendor allocation and failover remain owned by the SDK.
+ */
+export async function resolveProxy(options = {}) {
+    const resolved = await resolveProxyConfigAsync(options);
+    const vendor = vendorFromResolvedSource(resolved.source);
+    return vendor ? { ...resolved, vendor } : resolved;
+}
+/**
+ * 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).
+ */
+export 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.`);
+    }
+}
+export async function resolveWithVendor(vendor, policy, options, context) {
+    if (vendor === "nodemaven") {
+        const startedAt = Date.now();
+        const username = (context.credentials === undefined
+            ? process.env[NODEMAVEN_USERNAME_ENV]
+            : context.credentials[NODEMAVEN_USERNAME_ENV])?.trim();
+        const password = (context.credentials === undefined
+            ? process.env[NODEMAVEN_PASSWORD_ENV]
+            : context.credentials[NODEMAVEN_PASSWORD_ENV])?.trim();
+        const filter = context.credentials === undefined
+            ? process.env[NODEMAVEN_FILTER_ENV]
+            : context.credentials[NODEMAVEN_FILTER_ENV];
+        if (!username || !password) {
+            throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`, { vendor: "nodemaven" });
+        }
+        const synthesized = synthesizeNodemavenProxy({
+            policy,
+            credentials: {
+                username,
+                password,
+                ...(filter ? { filter } : {}),
+            },
+            affinityKey: options.affinityKey,
+            protocol: context.protocol,
+            poolIndex: context.poolIndex,
+            refreshEpoch: context.refreshEpoch,
+            country: resolveSmartproxyCountry(policy, context.ambientDefaults !== false),
+        });
+        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 = (context.credentials === undefined
+        ? process.env[SMARTPROXY_APP_KEY_ENV]
+        : context.credentials[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, context.ambientDefaults !== false);
+    const allocated = await allocateSmartproxy(policy, appKey, lifetimeMinutes, options.affinityKey, context.protocol, context.ambientDefaults !== false, context.sharedCache !== false);
+    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) {
@@ -357,19 +521,178 @@ 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);
+}
+function vendorMaxPoolSize(vendor) {
+    return vendor === "nodemaven" ? NODEMAVEN_MAX_POOL_SIZE : SMARTPROXY_MAX_POOL_SIZE;
+}
+/**
+ * Absolute upper bound on a chain's attempt span — the sum of each vendor's
+ * *maximum* pool size. Unlike `resolvePolicyProxyPoolSpan` (the configured
+ * span), this backstop is independent of `session.poolSize`, so it never
+ * truncates a legitimately large pool below the point where the flat attempt
+ * index would cross into the next vendor (e.g. a 50-slot NodeMaven pool).
+ */
+export function maxPolicyProxyPoolSpan(policy) {
+    const chain = resolveVendorChain(policy);
+    if (chain.length === 0)
+        return SMARTPROXY_MAX_POOL_SIZE;
+    return chain.reduce((sum, vendor) => sum + vendorMaxPoolSize(vendor), 0);
+}
+const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE", "TRACE"]);
+/**
+ * Transport-retry attempt cap for a policy-managed request. A transport failure
+ * rotates the flat attempt index onto the *next* endpoint (and, once the index
+ * passes the primary vendor's pool span, the *next vendor*), so the cap must be
+ * the chain's full pool span for failover to reach the fallback vendor — the
+ * per-endpoint retry budget (default 3) never gets there.
+ *
+ * The span only widens beyond the caller's retry budget when ALL hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — `HttpRetryOptions.attempts`
+ *    is the documented total-attempt ceiling and must be honoured verbatim;
+ *  - the method is safe/idempotent — an unsafe request must never be duplicated
+ *    across the pool even if some framework default would allow it;
+ *  - the policy resolves a non-empty *registry* vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) and credential-less policies
+ *    resolve no allocator pool, so every attempt would hit the same endpoint
+ *    with no possible crossover — they keep the retry budget.
+ *
+ * The widened cap is bounded by the chain's true maximum span (sum of each
+ * vendor's max pool size), so a large NodeMaven pool (≤50) stays reachable and
+ * a pathological chain can never spin unbounded.
+ */
+/**
+ * True when a policy request is in *implicit chain-rotation* mode: successive
+ * transport attempts rotate the flat index across the concatenated vendor pool
+ * spans (and, past the primary vendor's span, into the fallback vendor). This is
+ * the ONLY mode in which the transport loop widens its attempt cap AND
+ * de-duplicates repeated endpoints — the two behaviours must share one predicate
+ * so they never diverge. It holds when ALL of the widening conditions hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — its `attempts` ceiling is
+ *    the documented contract and must be honoured verbatim against whatever
+ *    endpoint each attempt resolves (even a repeated one), so no de-duplication;
+ *  - the method is safe/idempotent — an unsafe request is never duplicated;
+ *  - the policy resolves a non-empty registry vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) resolve the same URL every
+ *    attempt, so there is nothing to rotate or de-duplicate.
+ */
+export function policyRotatesTransportVendorChain(input) {
+    if (!input.usesPolicyAllocator || !input.policy || input.explicitRetry) {
+        return false;
+    }
+    if (UNSAFE_TRANSPORT_RETRY_METHODS.has(input.method.toUpperCase())) {
+        return false;
+    }
+    return resolveVendorChain(input.policy).length > 0;
+}
+export function resolvePolicyTransportAttemptCap(input) {
+    const budget = Math.max(1, Math.floor(input.retryAttempts));
+    if (!policyRotatesTransportVendorChain({
+        policy: input.policy,
+        usesPolicyAllocator: input.usesPolicyAllocator,
+        explicitRetry: input.explicitRetry,
+        method: input.method,
+    })) {
+        return budget;
+    }
+    const span = Math.min(maxPolicyProxyPoolSpan(input.policy), resolvePolicyProxyPoolSpan(input.policy));
+    return Math.max(budget, span);
+}
+/**
+ * A registry vendor chain (smartproxy/nodemaven) resolves a potentially
+ * *different* endpoint per flat attempt index, so a transport retry should
+ * advance across endpoints and de-duplicate once the chain stops yielding new
+ * ones. Static/custom/decodo policies (empty registry chain) resolve the *same*
+ * URL every attempt by design — retrying that same endpoint is intended, so the
+ * transport loop must not de-duplicate them.
+ */
+export function policyResolvesRegistryVendorChain(policy) {
+    return Boolean(policy) && resolveVendorChain(policy).length > 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) {
+function resolveSmartproxyCountry(policy, ambientDefaults = true) {
     return (policy.geo?.country ??
-        process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ??
-        undefined);
+        (ambientDefaults
+            ? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() || undefined
+            : undefined));
 }
-function resolveSmartproxyLifetime(policy) {
+function resolveSmartproxyLifetime(policy, ambientDefaults = true) {
     const configuredLifetime = policy.session?.lifetimeMinutes ??
-        readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30);
+        (ambientDefaults ? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30) : 30);
     return Math.min(SMARTPROXY_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configuredLifetime)));
 }
 function readPositiveNumberEnv(name, fallback) {
@@ -389,26 +712,27 @@ function selectProxyPoolIndex(poolSize, attempt = 0) {
     if (poolSize <= 1) {
         return 0;
     }
-    const normalizedAttempt = Number.isFinite(attempt)
-        ? Math.max(0, Math.floor(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, appKey, affinityKey, lifetimeMinutes, protocol, ambientDefaults = true) {
     const poolSize = resolveSmartproxyPoolSize(policy);
     return JSON.stringify({
         provider: "smartproxy",
-        country: resolveSmartproxyCountry(policy),
+        credentialHash: createHash("sha256")
+            .update("apifuse-smartproxy-credential:v1\0")
+            .update(appKey)
+            .digest("hex"),
+        protocol,
+        country: resolveSmartproxyCountry(policy, ambientDefaults),
         affinity: policy.session?.affinity ?? "request",
-        affinityKey: (policy.session?.affinity ?? "request") === "request"
-            ? undefined
-            : affinityKey,
+        affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
         lifetimeMinutes,
         poolSize,
     });
 }
-async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey) {
-    const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes);
+async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey, protocol, ambientDefaults = true, sharedCache = true) {
+    const cacheKey = buildSmartproxyCacheKey(policy, appKey, affinityKey, lifetimeMinutes, protocol, ambientDefaults);
     const startedAt = Date.now();
     const now = startedAt;
     const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
@@ -416,7 +740,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, ambientDefaults, sharedCache);
             return {
                 pool: cached,
                 telemetry: telemetryForPool(cached, "soft_stale_refresh", startedAt, {
@@ -429,7 +753,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey)
             telemetry: telemetryForPool(cached, "memory_hit", startedAt),
         };
     }
-    if (!skipCached) {
+    if (!skipCached && sharedCache) {
         const redisResult = await readSmartproxyRedisPool(cacheKey, startedAt);
         if (redisResult)
             return redisResult;
@@ -444,7 +768,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, ambientDefaults, sharedCache).finally(() => {
         proxyInflight.delete(cacheKey);
     });
     proxyInflight.set(cacheKey, promise);
@@ -475,9 +799,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, ambientDefaults, sharedCache) {
     try {
-        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), {
+        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), protocol, ambientDefaults, sharedCache, {
             background: true,
         });
     }
@@ -485,10 +809,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 = {}) {
-    const redis = getProxyRedis();
+async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, ambientDefaults, sharedCache, options = {}) {
+    const redis = sharedCache ? getProxyRedis() : undefined;
     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, ambientDefaults });
     }
     const poolKey = smartproxyRedisPoolKey(cacheKey);
     const lockKey = smartproxyRedisLockKey(cacheKey);
@@ -499,11 +823,11 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
         if (acquired === "OK") {
             try {
                 return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, {
-                    cacheStatus: options.background
-                        ? "soft_stale_refresh"
-                        : "allocator",
+                    cacheStatus: options.background ? "soft_stale_refresh" : "allocator",
                     redis,
                     poolKey,
+                    protocol,
+                    ambientDefaults,
                 });
             }
             finally {
@@ -526,8 +850,7 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
         if (typeof pttl === "number" && pttl <= 0) {
             continue;
         }
-        if (Date.now() - startedAt >
-            SMARTPROXY_LOCK_POLL_MAX_MS - SMARTPROXY_DEADLINE_MARGIN_MS) {
+        if (Date.now() - startedAt > SMARTPROXY_LOCK_POLL_MAX_MS - SMARTPROXY_DEADLINE_MARGIN_MS) {
             break;
         }
         await sleep(Math.min(500, Math.max(50, typeof pttl === "number" ? pttl : 100)));
@@ -559,7 +882,7 @@ function sleep(ms, signal) {
     });
 }
 function smartproxyAllocatorDeadlineMs() {
-    return (smartproxyAllocatorDeadlineMsForTests ?? SMARTPROXY_ALLOCATOR_DEADLINE_MS);
+    return smartproxyAllocatorDeadlineMsForTests ?? SMARTPROXY_ALLOCATOR_DEADLINE_MS;
 }
 function createDeadlineAbortController(deadlineAt) {
     const controller = new AbortController();
@@ -617,7 +940,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, options.ambientDefaults);
     const allocatorStartedAt = Date.now();
     const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
     let allocation;
@@ -627,7 +950,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;
@@ -649,9 +972,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
         }
     }
     const allocatorMs = Math.max(0, Date.now() - allocatorStartedAt);
-    const allocatorAttempts = allocation?.attempt ??
-        lastFailure?.attempt ??
-        SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS;
+    const allocatorAttempts = allocation?.attempt ?? lastFailure?.attempt ?? SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS;
     const allocatorBodyClass = lastFailure?.bodyClass ?? allocation?.bodyClass ?? "usable_proxy_endpoints";
     const allocatorStatus = lastFailure ? lastFailure.status : allocation?.status;
     if (!allocation) {
@@ -677,7 +998,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
         expiresAt: allocatedAt + ttlMs,
         diagnostics: {
             provider: "smartproxy",
-            country: resolveSmartproxyCountry(policy) ?? "default",
+            country: resolveSmartproxyCountry(policy, options.ambientDefaults) ?? "default",
             lifetimeMinutes,
             affinity: policy.session?.affinity ?? "request",
             rawConnect: true,
@@ -712,7 +1033,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 {
@@ -755,7 +1076,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 {
@@ -790,35 +1111,41 @@ 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, ambientDefaults = true) {
     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",
     });
-    const country = resolveSmartproxyCountry(policy);
+    const country = resolveSmartproxyCountry(policy, ambientDefaults);
     if (country) {
         params.set("cc", country);
     }
-    return `https://www.smartproxy.org/web_v1/ip/get-ip-v3?${params.toString()}`;
+    // www.smartproxy.org stopped serving the extraction API on 2026-07-21 (the
+    // 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 [];
     }
     try {
         const parsed = JSON.parse(trimmed);
-        const data = parsed && typeof parsed === "object" && "data" in parsed
-            ? parsed.data
-            : undefined;
-        const list = data && typeof data === "object" && "list" in data
-            ? data.list
-            : undefined;
+        const data = parsed && typeof parsed === "object" && "data" in parsed ? parsed.data : undefined;
+        const list = data && typeof data === "object" && "list" in data ? data.list : undefined;
         if (Array.isArray(list)) {
             return list
                 .map((item) => {
@@ -826,11 +1153,10 @@ function parseSmartproxyAllocatorProxies(body) {
                     return null;
                 }
                 const ip = "ip" in item && typeof item.ip === "string" ? item.ip : "";
-                const port = "port" in item &&
-                    (typeof item.port === "string" || typeof item.port === "number")
+                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);
         }
@@ -842,7 +1168,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) {
@@ -870,11 +1196,14 @@ 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 appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+    if (!appKey)
+        return undefined;
+    const cacheKey = buildSmartproxyCacheKey(policy, appKey, 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);