@apifuse/provider-sdk 2.2.0-beta.15 → 2.2.0-beta.17

package/dist/native-egress-policy.js

@@ -1,3 +1,4 @@
+import { canonicalizeEgressHost, parseIpv4Cidr } from "./native-ipv4.js";
 const NATIVE_PROVIDER_FIELD_RECORD = {
     network: true,
 };
@@ -16,6 +17,7 @@ const NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD = {
     sourcePorts: true,
     sourcePortRanges: true,
     targetHostSuffixes: true,
+    targetIpv4Cidrs: true,
     targetPorts: true,
     targetPortRanges: true,
     tls: true,
@@ -81,27 +83,13 @@ function dataArray(value, fieldPath) {
     }
     return result;
 }
-function hasControlCharacter(value) {
-    for (let index = 0; index < value.length; index += 1) {
-        const code = value.charCodeAt(index);
-        if (code <= 31 || code === 127)
-            return true;
-    }
-    return false;
-}
 function host(value, fieldPath, suffix = false) {
-    if (typeof value !== "string" ||
-        !value.trim() ||
-        hasControlCharacter(value) ||
-        /\s/.test(value) ||
-        value.includes("://"))
-        fail(`${fieldPath} must be a non-empty hostname`);
-    if (value.includes("*"))
+    if (typeof value === "string" && value.includes("*"))
         fail(`${fieldPath} must be an exact ${suffix ? "DNS suffix" : "hostname"}, not a wildcard`);
-    const normalized = value.trim().toLowerCase().replace(/\.$/, "");
-    if (!normalized)
+    const canonical = canonicalizeEgressHost(value);
+    if (!canonical.ok)
         fail(`${fieldPath} must be a non-empty hostname`);
-    return normalized;
+    return canonical.host;
 }
 function port(value, fieldPath) {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 65_535)
@@ -114,6 +102,25 @@ function ports(value, fieldPath) {
 function hostSuffixes(value, fieldPath) {
     return dataArray(value, fieldPath).map((value, index) => host(value, `${fieldPath}[${index}]`, true));
 }
+function ipv4Cidrs(value, fieldPath) {
+    const seen = new Set();
+    return dataArray(value, fieldPath).map((value, index) => {
+        const cidrPath = `${fieldPath}[${index}]`;
+        if (typeof value !== "string")
+            fail(`${cidrPath} must be an IPv4 CIDR in a.b.c.d/nn form`);
+        const parsed = parseIpv4Cidr(value);
+        if (!parsed.ok) {
+            if (parsed.reason === "non-canonical-network")
+                fail(`${cidrPath} must use the canonical network address with no host bits set`);
+            fail(`${cidrPath} must be an IPv4 CIDR in a.b.c.d/nn form`);
+        }
+        const duplicateKey = `${parsed.network}/${parsed.prefix}`;
+        if (seen.has(duplicateKey))
+            fail(`${fieldPath} must not contain duplicate CIDRs`);
+        seen.add(duplicateKey);
+        return value;
+    });
+}
 function ranges(value, fieldPath) {
     return dataArray(value, fieldPath).map((value, index) => {
         const rangePath = `${fieldPath}[${index}]`;
@@ -173,9 +180,14 @@ export function parseNativeEgressPolicy(value) {
                     : ranges(rule.sourcePortRanges, `${fieldPath}.sourcePortRanges`);
                 if (sourcePorts.length === 0 && sourcePortRanges.length === 0)
                     fail(`${fieldPath} must declare a non-empty sourcePorts or sourcePortRanges list`);
-                const targetHostSuffixes = hostSuffixes(rule.targetHostSuffixes, `${fieldPath}.targetHostSuffixes`);
-                if (targetHostSuffixes.length === 0)
-                    fail(`${fieldPath}.targetHostSuffixes must not be empty`);
+                const targetHostSuffixes = rule.targetHostSuffixes === undefined
+                    ? []
+                    : hostSuffixes(rule.targetHostSuffixes, `${fieldPath}.targetHostSuffixes`);
+                const targetIpv4Cidrs = rule.targetIpv4Cidrs === undefined
+                    ? []
+                    : ipv4Cidrs(rule.targetIpv4Cidrs, `${fieldPath}.targetIpv4Cidrs`);
+                if (targetHostSuffixes.length === 0 && targetIpv4Cidrs.length === 0)
+                    fail(`${fieldPath} must declare a non-empty targetHostSuffixes or targetIpv4Cidrs list`);
                 const targetPorts = rule.targetPorts === undefined
                     ? []
                     : ports(rule.targetPorts, `${fieldPath}.targetPorts`);
@@ -190,6 +202,7 @@ export function parseNativeEgressPolicy(value) {
                     sourcePorts,
                     sourcePortRanges,
                     targetHostSuffixes,
+                    targetIpv4Cidrs,
                     targetPorts,
                     targetPortRanges,
                     tls: tls(rule.tls, `${fieldPath}.tls`),

package/dist/native-ipv4.d.ts

@@ -0,0 +1,22 @@
+export type EgressHostCanonicalizationFailure = "not-string" | "reserved-delimiter" | "control-character" | "whitespace" | "canonicalization-empty";
+export type EgressHostCanonicalizationResult = {
+    readonly ok: true;
+    readonly host: string;
+} | {
+    readonly ok: false;
+    readonly reason: EgressHostCanonicalizationFailure;
+};
+export declare function parseStrictIpv4(value: string): number | undefined;
+export declare function classifyEgressTargetHost(host: string): "ipv4" | "numeric-ambiguous" | "dns";
+export declare function hasReservedEgressHostDelimiter(value: string): boolean;
+export declare function hasEgressHostControlCharacter(value: string): boolean;
+export declare function canonicalizeEgressHost(value: unknown): EgressHostCanonicalizationResult;
+export declare function parseIpv4Cidr(value: string): {
+    readonly ok: true;
+    readonly network: number;
+    readonly prefix: number;
+} | {
+    readonly ok: false;
+    readonly reason: "malformed" | "non-canonical-network";
+};
+export declare function ipv4InCidr(address: number, cidr: string): boolean;

package/dist/native-ipv4.js

@@ -0,0 +1,98 @@
+import { domainToASCII } from "node:url";
+const STRICT_IPV4_PATTERN = /^(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})$/;
+const DECIMAL_COMPONENT_PATTERN = /^\d+$/;
+const HEX_COMPONENT_PATTERN = /^0[xX][\da-fA-F]+$/;
+const FORMAT_CONTROL_PATTERN = /\p{Cf}/u;
+const RESERVED_EGRESS_HOST_DELIMITERS = ["/", "\\", "?", "#", "@", "[", "]", " ", "%"];
+export function parseStrictIpv4(value) {
+    const match = STRICT_IPV4_PATTERN.exec(value);
+    if (!match || match[0] !== value)
+        return undefined;
+    const [, first, second, third, fourth] = match;
+    if (first === undefined || second === undefined || third === undefined || fourth === undefined)
+        return undefined;
+    const octets = [Number(first), Number(second), Number(third), Number(fourth)];
+    if (octets.some((octet) => octet > 255))
+        return undefined;
+    const [a, b, c, d] = octets;
+    if (a === undefined || b === undefined || c === undefined || d === undefined)
+        return undefined;
+    return (a * 0x1000000 + b * 0x10000 + c * 0x100 + d) >>> 0;
+}
+export function classifyEgressTargetHost(host) {
+    if (parseStrictIpv4(host) !== undefined)
+        return "ipv4";
+    if (host.includes(":"))
+        return "numeric-ambiguous";
+    const labels = host.split(".");
+    if (labels.every((label) => DECIMAL_COMPONENT_PATTERN.exec(label)?.[0] === label ||
+        HEX_COMPONENT_PATTERN.exec(label)?.[0] === label))
+        return "numeric-ambiguous";
+    return "dns";
+}
+export function hasReservedEgressHostDelimiter(value) {
+    return RESERVED_EGRESS_HOST_DELIMITERS.some((delimiter) => value.includes(delimiter));
+}
+export function hasEgressHostControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code <= 31 || code === 127)
+            return true;
+    }
+    return FORMAT_CONTROL_PATTERN.test(value);
+}
+export function canonicalizeEgressHost(value) {
+    if (typeof value !== "string")
+        return { ok: false, reason: "not-string" };
+    if (hasReservedEgressHostDelimiter(value))
+        return { ok: false, reason: "reserved-delimiter" };
+    if (hasEgressHostControlCharacter(value))
+        return { ok: false, reason: "control-character" };
+    if (/\s/u.test(value))
+        return { ok: false, reason: "whitespace" };
+    const raw = value.trim();
+    if (!raw)
+        return { ok: false, reason: "canonicalization-empty" };
+    // Classify the spelling with one optional root-label dot removed before IDNA.
+    // This keeps resolver-numeric ASCII forms from being widened into canonical IPv4.
+    const numericCandidate = raw.endsWith(".") ? raw.slice(0, -1) : raw;
+    const normalizedNumericCandidate = numericCandidate.toLowerCase();
+    if (classifyEgressTargetHost(normalizedNumericCandidate) === "numeric-ambiguous")
+        return { ok: true, host: normalizedNumericCandidate };
+    let ascii;
+    try {
+        ascii = domainToASCII(raw).toLowerCase().replace(/\.$/, "");
+    }
+    catch {
+        return { ok: false, reason: "canonicalization-empty" };
+    }
+    if (!ascii || /^\.+$/.test(ascii))
+        return { ok: false, reason: "canonicalization-empty" };
+    return { ok: true, host: ascii };
+}
+export function parseIpv4Cidr(value) {
+    const separator = value.indexOf("/");
+    if (separator <= 0 || separator !== value.lastIndexOf("/"))
+        return { ok: false, reason: "malformed" };
+    const address = parseStrictIpv4(value.slice(0, separator));
+    const prefixText = value.slice(separator + 1);
+    const prefix = Number(prefixText);
+    if (address === undefined ||
+        !Number.isInteger(prefix) ||
+        prefix < 0 ||
+        prefix > 32 ||
+        String(prefix) !== prefixText)
+        return { ok: false, reason: "malformed" };
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    const network = (address & mask) >>> 0;
+    if (address !== network)
+        return { ok: false, reason: "non-canonical-network" };
+    return { ok: true, network, prefix };
+}
+export function ipv4InCidr(address, cidr) {
+    const parsed = parseIpv4Cidr(cidr);
+    if (!parsed.ok)
+        return false;
+    return (parsed.prefix === 0 ||
+        address >>> (32 - parsed.prefix) === parsed.network >>> (32 - parsed.prefix));
+}

package/dist/provider.d.ts

@@ -7,6 +7,6 @@ export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, i
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
-export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
+export { createNativeNetworkClient, createEnvVendorCredentialResolver, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, 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 { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/provider.js

@@ -6,5 +6,5 @@ export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, i
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, createEnvVendorCredentialResolver, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/native-network.d.ts

@@ -1,10 +1,11 @@
 import { Socket } from "node:net";
 import { type TLSSocket } from "node:tls";
+import { type ProxyProtocol } from "../config/loader.js";
 import { TransportError } from "../errors.js";
-import type { NativeNetworkClient, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider } from "../types.js";
+import type { NativeNetworkClient, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider, EnvContext } from "../types.js";
 export type NativeNetworkErrorCode = "native_connection_aborted" | "native_connection_closed" | "native_connection_failed" | "native_connection_idle_timeout" | "native_connection_timeout" | "native_egress_authorization_failed" | "native_egress_grant_expired" | "native_egress_grant_invalid" | "native_egress_grant_limit_exceeded" | "native_egress_input_invalid" | "native_egress_not_declared" | "native_egress_policy_invalid" | "native_dynamic_egress_unsupported" | "native_proxy_expired" | "native_proxy_invalid";
 export declare class NativeNetworkError extends TransportError {
-    constructor(message: string, code: NativeNetworkErrorCode);
+    constructor(message: string, code: NativeNetworkErrorCode, cause?: Error);
     get code(): NativeNetworkErrorCode;
 }
 export declare class NativeProxyExpiredError extends NativeNetworkError {
@@ -13,9 +14,9 @@ export declare class NativeProxyExpiredError extends NativeNetworkError {
 }
 /** Raised before transport setup when a native destination is not authorized. */
 export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
-    readonly host: string;
     readonly port: number;
     readonly tls: "required" | "disabled";
+    readonly host: string;
     constructor(host: string, port: number, tls: "required" | "disabled");
 }
 /**
@@ -23,10 +24,10 @@ export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
  * its expiry remains in the client's bounded recent-expiry evidence window.
  */
 export declare class NativeEgressGrantExpiredError extends NativeNetworkError {
-    readonly host: string;
     readonly port: number;
     readonly tls: "required" | "disabled";
     readonly expiresAt: string;
+    readonly host: string;
     constructor(host: string, port: number, tls: "required" | "disabled", expiresAt: string);
 }
 /** Raised when an established connection exceeds its opt-in read-idle window. */
@@ -41,13 +42,42 @@ export type NativeGatewayProxySynthesisInput = {
     readonly policy: ProviderProxyPolicy;
     readonly affinityKey?: string;
     readonly now: number;
+    readonly protocol: ProxyProtocol;
+    readonly credentials: VendorCredentialResolver;
+};
+export type VendorCredentialLookup = {
+    readonly kind: "present";
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "absent";
+    readonly missing: readonly string[];
+};
+export type VendorCredentialResolver = (vendor: ProviderProxyProvider) => VendorCredentialLookup;
+export type NativeGatewayProxySkipReason = {
+    readonly kind: "credentials_absent";
+    readonly missing: readonly string[];
+} | {
+    readonly kind: "protocol_unsupported";
+    readonly protocol: string;
+} | {
+    readonly kind: "allocation_failed";
+    readonly cause: Error;
+} | {
+    readonly kind: "credential_lookup_failed";
+    readonly cause: Error;
 };
+export type NativeGatewayProxySynthesisResult = NativeGatewayProxy | {
+    readonly kind: "skipped";
+    readonly reason: NativeGatewayProxySkipReason;
+} | undefined;
 /** A vendor adapter in the ordered native gateway resolution chain. */
-export type NativeGatewayProxySynthesizer = (input: NativeGatewayProxySynthesisInput) => NativeGatewayProxy | undefined;
+export type NativeGatewayProxySynthesizer = (input: NativeGatewayProxySynthesisInput) => NativeGatewayProxySynthesisResult | Promise<NativeGatewayProxySynthesisResult>;
 export type NativeGatewayProxyResolutionInput = {
     readonly policy: ProviderProxyPolicy;
     readonly affinityKey?: string;
     readonly now?: number;
+    readonly protocol?: ProxyProtocol;
+    readonly credentials?: VendorCredentialResolver;
     readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
 };
 export type NativeNetworkClientOptions = {
@@ -55,6 +85,10 @@ export type NativeNetworkClientOptions = {
     readonly affinityKey?: string;
     /** Stable credential/account identity; hashed before vendor synthesis. */
     readonly credentialIdentity?: string;
+    /** Vendor credential lookup; defaults to the process EnvContext. */
+    readonly credentials?: VendorCredentialResolver;
+    /** Explicit CONNECT/SOCKS5 override; vendors otherwise choose their default. */
+    readonly proxyProtocol?: ProxyProtocol;
     /** Vendor adapters in priority order within each policy vendor slot. */
     readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
     /** Warning-level lifecycle diagnostic sink. */
@@ -67,10 +101,12 @@ export type NativeNetworkClientOptions = {
     /** Additional deployment authorization layered on top of SDK enforcement. */
     readonly grantTcpEgress?: (input: NativeNetworkDynamicGrantOptions) => NativeNetworkEgressGrant;
 };
+/** Build a resolver over the SDK's existing injectable environment context. */
+export declare function createEnvVendorCredentialResolver(env?: EnvContext): VendorCredentialResolver;
 /** Domain-separated, process-independent affinity derived from credential identity. */
 export declare function deriveNativeCredentialAffinityKey(credentialIdentity: string): string;
-/** Resolve the first configured native gateway without invoking an allocator API. */
-export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResolutionInput): NativeGatewayProxy | undefined;
+/** Resolve the first configured native gateway, including allocation vendors. */
+export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResolutionInput): Promise<NativeGatewayProxy | undefined>;
 export declare function createNativeNetworkConnection(socket: Socket | TLSSocket, proxy: NativeGatewayProxy | undefined, options: NativeNetworkClientOptions, idleTimeoutMs?: number): NativeNetworkConnection;
 type NativeConnectTls = "required" | "disabled";
 export declare const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;