@apifuse/provider-sdk 2.2.0-beta.16 → 2.2.0-beta.18

package/dist/runtime/proxy-nodemaven.d.ts

@@ -3,6 +3,11 @@ export declare const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAM
 export declare const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
 export declare const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
 export declare const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+export type NodemavenCredentials = {
+    readonly username: string;
+    readonly password: string;
+    readonly filter?: string;
+};
 /** Both schemes tunnel bytes end-to-end, preserving the client TLS handshake. */
 export type ProxyProtocol = "http" | "socks5";
 /**
@@ -23,6 +28,8 @@ export type NodemavenSessionWindow = {
 export declare function nodemavenSessionWindow(policy: ProviderProxyPolicy, now?: number): NodemavenSessionWindow;
 export type NodemavenSynthesisInput = {
     policy: ProviderProxyPolicy;
+    /** Explicit credentials; synthesis never reads process-global state. */
+    credentials: NodemavenCredentials;
     affinityKey: string | undefined;
     protocol: ProxyProtocol;
     poolIndex: number;

package/dist/runtime/proxy-nodemaven.js

@@ -30,8 +30,8 @@ function readNodemavenUsername() {
 function readNodemavenPassword() {
     return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
 }
-function resolveNodemavenFilter() {
-    const raw = process.env[NODEMAVEN_FILTER_ENV]?.trim().toLowerCase();
+function resolveNodemavenFilter(value) {
+    const raw = value?.trim().toLowerCase();
     if (!raw)
         return DEFAULT_NODEMAVEN_FILTER;
     if (!NODEMAVEN_FILTERS.has(raw)) {
@@ -97,12 +97,12 @@ function selectPort(protocol, sid, poolIndex) {
  * There is no allocation API — geo/session are encoded in the username.
  */
 export function synthesizeNodemavenProxy(input) {
-    const username = readNodemavenUsername();
-    const password = readNodemavenPassword();
+    const username = input.credentials.username.trim();
+    const password = input.credentials.password.trim();
     if (!username || !password) {
         throw new Error(`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`);
     }
-    const filter = resolveNodemavenFilter();
+    const filter = resolveNodemavenFilter(input.credentials.filter);
     const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
     const port = selectPort(input.protocol, sid, input.poolIndex);
     const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);

package/dist/server/serve.js

@@ -16,7 +16,7 @@ import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
 import { createHttpClient } from "../runtime/http.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
-import { createNativeNetworkClient } from "../runtime/native-network.js";
+import { createEnvVendorCredentialResolver, createNativeNetworkClient, } from "../runtime/native-network.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
@@ -225,6 +225,7 @@ function createProviderContext(provider, request, operationId, options = {}, sta
                         egress: provider.native.network,
                         proxyPolicy: resolveNativeProxyPolicy(provider),
                         affinityKey: proxyClientOptions.affinityKey,
+                        credentials: createEnvVendorCredentialResolver(env),
                     }),
                 },
             }
@@ -312,6 +313,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
                             egress: provider.native.network,
                             proxyPolicy: resolveNativeProxyPolicy(provider),
                             affinityKey: proxyClientOptions.affinityKey,
+                            credentials: createEnvVendorCredentialResolver(createEnvContext(provider.secrets?.map((secret) => secret.name))),
                         }),
                     },
                 }

package/dist/types.d.ts

@@ -1089,6 +1089,11 @@ export interface NativeTcpEgressRule {
 /**
  * Bounded native TCP egress discovered through a declared bootstrap endpoint.
  * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ * Dynamic rules must declare at least one target host selector through
+ * targetHostSuffixes, targetIpv4Cidrs, and/or targetIpv6Cidrs. Literal grant
+ * sources and targets match only same-family selectors (except exact
+ * sourceHost); DNS names match only host/suffix selectors. IPv4-mapped and
+ * IPv4-compatible IPv6 literals are authorized only by IPv4 CIDRs.
  *
  * Dynamic rules are ordered. The first rule whose source, target, port, and TLS
  * selectors match exclusively owns the grant; its ttlMs and maxGrants bounds
@@ -1099,9 +1104,13 @@ export interface NativeTcpEgressRule {
 export interface NativeTcpDynamicEgressRule {
     readonly sourceHost?: string;
     readonly sourceHostSuffixes?: readonly string[];
+    readonly sourceIpv4Cidrs?: readonly string[];
+    readonly sourceIpv6Cidrs?: readonly string[];
     readonly sourcePorts?: readonly number[];
     readonly sourcePortRanges?: readonly NativeTcpPortRange[];
-    readonly targetHostSuffixes: readonly string[];
+    readonly targetHostSuffixes?: readonly string[];
+    readonly targetIpv4Cidrs?: readonly string[];
+    readonly targetIpv6Cidrs?: readonly string[];
     readonly targetPorts?: readonly number[];
     readonly targetPortRanges?: readonly NativeTcpPortRange[];
     readonly tls: NativeTcpTlsMode;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.16",
+	"version": "2.2.0-beta.18",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/config/loader.ts

@@ -7,7 +7,10 @@ import { Redis } from "ioredis";
 import type { ProviderProxyPolicy, ProviderProxyProvider, TraceConfig } from "../types.js";
 import {
 	NODEMAVEN_DEFAULT_PROTOCOL,
+	NODEMAVEN_FILTER_ENV,
 	NODEMAVEN_MAX_POOL_SIZE,
+	NODEMAVEN_PASSWORD_ENV,
+	NODEMAVEN_USERNAME_ENV,
 	type ProxyProtocol,
 	hasNodemavenCredentials,
 	nodemavenPoolSize,
@@ -683,7 +686,7 @@ export async function resolveProxy(
  * 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: Record<ProxyVendorName, ProxyProtocol> = {
+export const VENDOR_DEFAULT_PROTOCOL: Readonly<Record<ProxyVendorName, ProxyProtocol>> = {
 	smartproxy: "http",
 	nodemaven: NODEMAVEN_DEFAULT_PROTOCOL,
 };
@@ -708,21 +711,59 @@ export function assertTunnelingScheme(url: string): void {
 	}
 }
 
-async function resolveWithVendor(
+export type ProxyVendorResolutionContext = {
+	readonly protocol: ProxyProtocol;
+	readonly poolIndex: number;
+	readonly refreshEpoch: number;
+	/** Explicit vendor credentials. Omit only on the legacy ambient-env path. */
+	readonly credentials?: Readonly<Record<string, string>>;
+	/** Disable non-policy env defaults for deterministic injected adapters. */
+	readonly ambientDefaults?: boolean;
+	/** Disable env-discovered Redis sharing for deterministic injected adapters. */
+	readonly sharedCache?: boolean;
+};
+
+export async function resolveWithVendor(
 	vendor: ProxyVendorName,
 	policy: ProviderProxyPolicy,
 	options: ProxyResolutionOptions,
-	context: { protocol: ProxyProtocol; poolIndex: number; refreshEpoch: number },
+	context: ProxyVendorResolutionContext,
 ): Promise<ResolvedProxyConfig> {
 	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),
+			country: resolveSmartproxyCountry(policy, context.ambientDefaults !== false),
 		});
 		options.telemetry?.recordProxyResolution({
 			provider: "nodemaven",
@@ -746,7 +787,11 @@ async function resolveWithVendor(
 	}
 
 	// smartproxy allocation-style vendor.
-	const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+	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(
@@ -755,13 +800,15 @@ async function resolveWithVendor(
 			{ vendor: "smartproxy" },
 		);
 	}
-	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+	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);
@@ -985,15 +1032,22 @@ export function mapFlatAttempt(
 	return { vendorIndex: 0, poolIndex: 0 };
 }
 
-function resolveSmartproxyCountry(policy: ProviderProxyPolicy): string | undefined {
+function resolveSmartproxyCountry(
+	policy: ProviderProxyPolicy,
+	ambientDefaults = true,
+): string | undefined {
 	return (
-		policy.geo?.country ?? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ?? undefined
+		policy.geo?.country ??
+		(ambientDefaults
+			? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() || undefined
+			: undefined)
 	);
 }
 
-function resolveSmartproxyLifetime(policy: ProviderProxyPolicy): number {
+function resolveSmartproxyLifetime(policy: ProviderProxyPolicy, ambientDefaults = true): number {
 	const configuredLifetime =
-		policy.session?.lifetimeMinutes ?? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30);
+		policy.session?.lifetimeMinutes ??
+		(ambientDefaults ? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30) : 30);
 	return Math.min(SMARTPROXY_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configuredLifetime)));
 }
 
@@ -1024,15 +1078,21 @@ function selectProxyPoolIndex(poolSize: number, attempt = 0): number {
 
 function buildSmartproxyCacheKey(
 	policy: ProviderProxyPolicy,
+	appKey: string,
 	affinityKey: string | undefined,
 	lifetimeMinutes: number,
 	protocol: ProxyProtocol,
+	ambientDefaults = true,
 ): string {
 	const poolSize = resolveSmartproxyPoolSize(policy);
 	return JSON.stringify({
 		provider: "smartproxy",
+		credentialHash: createHash("sha256")
+			.update("apifuse-smartproxy-credential:v1\0")
+			.update(appKey)
+			.digest("hex"),
 		protocol,
-		country: resolveSmartproxyCountry(policy),
+		country: resolveSmartproxyCountry(policy, ambientDefaults),
 		affinity: policy.session?.affinity ?? "request",
 		affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
 		lifetimeMinutes,
@@ -1046,8 +1106,17 @@ async function allocateSmartproxy(
 	lifetimeMinutes: number,
 	affinityKey: string | undefined,
 	protocol: ProxyProtocol,
+	ambientDefaults = true,
+	sharedCache = true,
 ): Promise<SmartproxyAllocationResult> {
-	const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol);
+	const cacheKey = buildSmartproxyCacheKey(
+		policy,
+		appKey,
+		affinityKey,
+		lifetimeMinutes,
+		protocol,
+		ambientDefaults,
+	);
 	const startedAt = Date.now();
 	const now = startedAt;
 	const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
@@ -1055,7 +1124,15 @@ async function allocateSmartproxy(
 	const cached = proxyCache.get(cacheKey);
 	if (!skipCached && cached && isFresh(cached, now)) {
 		if (shouldSoftRefresh(cached, now)) {
-			void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol);
+			void refreshSmartproxyPool(
+				cacheKey,
+				policy,
+				appKey,
+				lifetimeMinutes,
+				protocol,
+				ambientDefaults,
+				sharedCache,
+			);
 			return {
 				pool: cached,
 				telemetry: telemetryForPool(cached, "soft_stale_refresh", startedAt, {
@@ -1069,7 +1146,7 @@ async function allocateSmartproxy(
 		};
 	}
 
-	if (!skipCached) {
+	if (!skipCached && sharedCache) {
 		const redisResult = await readSmartproxyRedisPool(cacheKey, startedAt);
 		if (redisResult) return redisResult;
 	}
@@ -1092,6 +1169,8 @@ async function allocateSmartproxy(
 		lifetimeMinutes,
 		startedAt,
 		protocol,
+		ambientDefaults,
+		sharedCache,
 	).finally(() => {
 		proxyInflight.delete(cacheKey);
 	});
@@ -1131,6 +1210,8 @@ async function refreshSmartproxyPool(
 	appKey: string,
 	lifetimeMinutes: number,
 	protocol: ProxyProtocol,
+	ambientDefaults: boolean,
+	sharedCache: boolean,
 ): Promise<void> {
 	try {
 		await allocateSmartproxyShared(
@@ -1140,6 +1221,8 @@ async function refreshSmartproxyPool(
 			lifetimeMinutes,
 			Date.now(),
 			protocol,
+			ambientDefaults,
+			sharedCache,
 			{
 				background: true,
 			},
@@ -1156,9 +1239,11 @@ async function allocateSmartproxyShared(
 	lifetimeMinutes: number,
 	startedAt: number,
 	protocol: ProxyProtocol,
+	ambientDefaults: boolean,
+	sharedCache: boolean,
 	options: { background?: boolean } = {},
 ): Promise<SmartproxyAllocationResult> {
-	const redis = getProxyRedis();
+	const redis = sharedCache ? getProxyRedis() : undefined;
 	if (!redis || !(await ensureRedisReady(redis))) {
 		return await allocateAndStoreSmartproxyPool(
 			cacheKey,
@@ -1166,7 +1251,7 @@ async function allocateSmartproxyShared(
 			appKey,
 			lifetimeMinutes,
 			startedAt,
-			{ cacheStatus: "allocator", protocol },
+			{ cacheStatus: "allocator", protocol, ambientDefaults },
 		);
 	}
 
@@ -1192,6 +1277,7 @@ async function allocateSmartproxyShared(
 						redis,
 						poolKey,
 						protocol,
+						ambientDefaults,
 					},
 				);
 			} finally {
@@ -1348,6 +1434,7 @@ async function allocateAndStoreSmartproxyPool(
 		redis?: ProxyRedisClient;
 		poolKey?: string;
 		protocol: ProxyProtocol;
+		ambientDefaults: boolean;
 	},
 ): Promise<SmartproxyAllocationResult> {
 	const poolSize = resolveSmartproxyPoolSize(policy);
@@ -1357,6 +1444,7 @@ async function allocateAndStoreSmartproxyPool(
 		lifetimeMinutes,
 		poolSize,
 		options.protocol,
+		options.ambientDefaults,
 	);
 	const allocatorStartedAt = Date.now();
 	const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
@@ -1427,7 +1515,7 @@ async function allocateAndStoreSmartproxyPool(
 		expiresAt: allocatedAt + ttlMs,
 		diagnostics: {
 			provider: "smartproxy",
-			country: resolveSmartproxyCountry(policy) ?? "default",
+			country: resolveSmartproxyCountry(policy, options.ambientDefaults) ?? "default",
 			lifetimeMinutes,
 			affinity: policy.session?.affinity ?? "request",
 			rawConnect: true,
@@ -1590,6 +1678,7 @@ function buildSmartproxyAllocatorUrl(
 	lifetimeMinutes: number,
 	poolSize: number,
 	protocol: ProxyProtocol,
+	ambientDefaults = true,
 ): string {
 	const params = new URLSearchParams({
 		app_key: appKey,
@@ -1600,7 +1689,7 @@ function buildSmartproxyAllocatorUrl(
 		format: "txt",
 		lb: "\\n",
 	});
-	const country = resolveSmartproxyCountry(policy);
+	const country = resolveSmartproxyCountry(policy, ambientDefaults);
 	if (country) {
 		params.set("cc", country);
 	}
@@ -1681,8 +1770,11 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 	}
 
 	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+	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,

package/src/index.ts

@@ -72,6 +72,7 @@ export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
 export {
 	createNativeNetworkClient,
+	createEnvVendorCredentialResolver,
 	deriveNativeCredentialAffinityKey,
 	NativeEgressGrantExpiredError,
 	NativeEgressNotDeclaredError,
@@ -81,10 +82,14 @@ export {
 	resolveNativeGatewayProxy,
 	type NativeGatewayProxy,
 	type NativeGatewayProxyResolutionInput,
+	type NativeGatewayProxySkipReason,
 	type NativeGatewayProxySynthesizer,
+	type NativeGatewayProxySynthesisResult,
 	type NativeGatewayProxySynthesisInput,
 	type NativeNetworkClientOptions,
 	type NativeNetworkErrorCode,
+	type VendorCredentialLookup,
+	type VendorCredentialResolver,
 } from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
 export { generateInsights } from "./runtime/insights.js";