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

package/dist/native-address.js

@@ -0,0 +1,281 @@
+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 IPV6_GROUP_PATTERN = /^[\da-fA-F]{1,4}$/;
+const FORMAT_CONTROL_PATTERN = /\p{Cf}/u;
+const RESERVED_EGRESS_HOST_DELIMITERS = ["/", "\\", "?", "#", "@", "[", "]", " ", "%"];
+const IPV4_MAPPED_PREFIX = Uint8Array.of(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff);
+const IPV4_COMPATIBLE_MIN = Uint8Array.of(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2);
+const IPV4_COMPATIBLE_MAX = Uint8Array.of(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff, 0xff, 0xff);
+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;
+}
+function ipv4HexGroups(value) {
+    const address = parseStrictIpv4(value);
+    if (address === undefined)
+        return undefined;
+    return [((address >>> 16) & 0xffff).toString(16), (address & 0xffff).toString(16)];
+}
+/** Parse the RFC 4291 IPv6 text forms accepted at both policy and runtime boundaries. */
+export function parseIpv6(value) {
+    if (!value || value.includes("%") || value.includes("[") || value.includes("]"))
+        return undefined;
+    if (value.indexOf("::") !== value.lastIndexOf("::"))
+        return undefined;
+    let text = value;
+    if (text.includes(".")) {
+        const finalColon = text.lastIndexOf(":");
+        if (finalColon < 0)
+            return undefined;
+        const groups = ipv4HexGroups(text.slice(finalColon + 1));
+        if (!groups)
+            return undefined;
+        text = `${text.slice(0, finalColon + 1)}${groups[0]}:${groups[1]}`;
+    }
+    const compression = text.indexOf("::");
+    let groups;
+    if (compression >= 0) {
+        const leftText = text.slice(0, compression);
+        const rightText = text.slice(compression + 2);
+        const left = leftText ? leftText.split(":") : [];
+        const right = rightText ? rightText.split(":") : [];
+        if (left.some((group) => !IPV6_GROUP_PATTERN.test(group)) ||
+            right.some((group) => !IPV6_GROUP_PATTERN.test(group)) ||
+            left.length + right.length >= 8)
+            return undefined;
+        groups = [...left, ...Array(8 - left.length - right.length).fill("0"), ...right];
+    }
+    else {
+        groups = text.split(":");
+        if (groups.length !== 8 || groups.some((group) => !IPV6_GROUP_PATTERN.test(group)))
+            return undefined;
+    }
+    const bytes = new Uint8Array(16);
+    for (let index = 0; index < groups.length; index += 1) {
+        const group = groups[index];
+        if (group === undefined)
+            return undefined;
+        const parsed = Number.parseInt(group, 16);
+        bytes[index * 2] = parsed >>> 8;
+        bytes[index * 2 + 1] = parsed & 0xff;
+    }
+    return bytes;
+}
+function prefixMatches(address, network, prefix) {
+    const wholeBytes = Math.floor(prefix / 8);
+    for (let index = 0; index < wholeBytes; index += 1) {
+        if (address[index] !== network[index])
+            return false;
+    }
+    const remainingBits = prefix % 8;
+    if (remainingBits === 0)
+        return true;
+    const mask = (0xff << (8 - remainingBits)) & 0xff;
+    return ((address[wholeBytes] ?? 0) & mask) === ((network[wholeBytes] ?? 0) & mask);
+}
+function compareIpv6(left, right) {
+    for (let index = 0; index < 16; index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+function cidrMaximum(network, prefix) {
+    const maximum = network.slice();
+    for (let bit = prefix; bit < 128; bit += 1) {
+        const byteIndex = Math.floor(bit / 8);
+        maximum[byteIndex] = (maximum[byteIndex] ?? 0) | (1 << (7 - (bit % 8)));
+    }
+    return maximum;
+}
+function rangesOverlap(leftMin, leftMax, rightMin, rightMax) {
+    return compareIpv6(leftMin, rightMax) <= 0 && compareIpv6(rightMin, leftMax) <= 0;
+}
+function ipv6CidrOverlap(network, prefix) {
+    const maximum = cidrMaximum(network, prefix);
+    const mappedMin = new Uint8Array(16);
+    mappedMin.set(IPV4_MAPPED_PREFIX);
+    const mappedMax = mappedMin.slice();
+    mappedMax.fill(0xff, 12);
+    if (rangesOverlap(network, maximum, mappedMin, mappedMax))
+        return "ipv4-mapped";
+    if (rangesOverlap(network, maximum, IPV4_COMPATIBLE_MIN, IPV4_COMPATIBLE_MAX))
+        return "ipv4-compatible";
+    return undefined;
+}
+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 parseIpv6Cidr(value) {
+    const separator = value.indexOf("/");
+    if (separator <= 0 || separator !== value.lastIndexOf("/"))
+        return { ok: false, reason: "malformed" };
+    const address = parseIpv6(value.slice(0, separator));
+    const prefixText = value.slice(separator + 1);
+    const prefix = Number(prefixText);
+    if (address === undefined ||
+        !Number.isInteger(prefix) ||
+        prefix < 0 ||
+        prefix > 128 ||
+        String(prefix) !== prefixText)
+        return { ok: false, reason: "malformed" };
+    const network = address.slice();
+    const wholeBytes = Math.floor(prefix / 8);
+    const remainingBits = prefix % 8;
+    if (remainingBits > 0) {
+        const mask = (0xff << (8 - remainingBits)) & 0xff;
+        network[wholeBytes] = (network[wholeBytes] ?? 0) & mask;
+    }
+    network.fill(0, wholeBytes + (remainingBits > 0 ? 1 : 0));
+    if (compareIpv6(address, network) !== 0)
+        return { ok: false, reason: "non-canonical-network" };
+    const overlap = ipv6CidrOverlap(network, prefix);
+    if (overlap)
+        return { ok: false, reason: "malformed", overlap };
+    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));
+}
+export function ipv6InCidr(address, cidr) {
+    if (address.length !== 16)
+        return false;
+    const parsed = parseIpv6Cidr(cidr);
+    return parsed.ok && prefixMatches(address, parsed.network, parsed.prefix);
+}
+export function embeddedIpv4FromIpv6(address) {
+    if (address.length !== 16)
+        return undefined;
+    const mapped = IPV4_MAPPED_PREFIX.every((byte, index) => address[index] === byte);
+    const compatible = address.slice(0, 12).every((byte) => byte === 0);
+    const embedded = ((address[12] ?? 0) * 0x1000000 +
+        (address[13] ?? 0) * 0x10000 +
+        (address[14] ?? 0) * 0x100 +
+        (address[15] ?? 0)) >>>
+        0;
+    if (mapped || (compatible && embedded !== 0 && embedded !== 1))
+        return embedded;
+    return undefined;
+}
+export function formatIpv6(address) {
+    if (address.length !== 16)
+        throw new TypeError("IPv6 addresses must contain exactly 16 bytes");
+    const groups = Array.from({ length: 8 }, (_, index) => (((address[index * 2] ?? 0) << 8) | (address[index * 2 + 1] ?? 0)).toString(16));
+    let bestStart = -1;
+    let bestLength = 0;
+    for (let index = 0; index < groups.length;) {
+        if (groups[index] !== "0") {
+            index += 1;
+            continue;
+        }
+        let end = index + 1;
+        while (end < groups.length && groups[end] === "0")
+            end += 1;
+        if (end - index > bestLength && end - index >= 2) {
+            bestStart = index;
+            bestLength = end - index;
+        }
+        index = end;
+    }
+    if (bestStart < 0)
+        return groups.join(":");
+    const left = groups.slice(0, bestStart).join(":");
+    const right = groups.slice(bestStart + bestLength).join(":");
+    return `${left}::${right}`;
+}
+/** The single family and ambiguity classifier used by policy and runtime matching. */
+export function classifyEgressHost(host) {
+    if (hasReservedEgressHostDelimiter(host) ||
+        hasEgressHostControlCharacter(host) ||
+        /\s/u.test(host))
+        return "numeric-ambiguous";
+    if (parseStrictIpv4(host) !== undefined)
+        return "ipv4";
+    const ipv6 = parseIpv6(host);
+    if (ipv6)
+        return embeddedIpv4FromIpv6(ipv6) === undefined ? "ipv6" : "ipv4-mapped-ipv6";
+    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" };
+    const ipv6 = parseIpv6(raw);
+    if (ipv6)
+        return { ok: true, host: formatIpv6(ipv6) };
+    // 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 (classifyEgressHost(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 };
+}

package/dist/native-egress-policy.d.ts

@@ -7,9 +7,13 @@ export type StaticEgressRuleSnapshot = {
 export type DynamicEgressRuleSnapshot = {
     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 targetIpv4Cidrs: readonly string[];
+    readonly targetIpv6Cidrs: readonly string[];
     readonly targetPorts: readonly number[];
     readonly targetPortRanges: readonly NativeTcpPortRange[];
     readonly tls: NativeTcpTlsMode;

package/dist/native-egress-policy.js

@@ -1,3 +1,4 @@
+import { canonicalizeEgressHost, classifyEgressHost, formatIpv6, parseIpv4Cidr, parseIpv6Cidr, } from "./native-address.js";
 const NATIVE_PROVIDER_FIELD_RECORD = {
     network: true,
 };
@@ -13,9 +14,13 @@ const NATIVE_TCP_RULE_FIELD_RECORD = {
 const NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD = {
     sourceHost: true,
     sourceHostSuffixes: true,
+    sourceIpv4Cidrs: true,
+    sourceIpv6Cidrs: true,
     sourcePorts: true,
     sourcePortRanges: true,
     targetHostSuffixes: true,
+    targetIpv4Cidrs: true,
+    targetIpv6Cidrs: true,
     targetPorts: true,
     targetPortRanges: true,
     tls: true,
@@ -81,27 +86,20 @@ 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;
+    const kind = classifyEgressHost(canonical.host);
+    if (kind === "numeric-ambiguous")
+        fail(`${fieldPath} value is an unresolvable numeric-ambiguous spelling`);
+    if (suffix && kind !== "dns") {
+        const family = kind === "ipv4" ? "IPv4" : "IPv6";
+        fail(`${fieldPath} must be a DNS suffix, not an ${family} literal`);
+    }
+    return canonical.host;
 }
 function port(value, fieldPath) {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 65_535)
@@ -114,6 +112,48 @@ 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 ipv6Cidrs(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 IPv6 CIDR in address/nn form`);
+        const parsed = parseIpv6Cidr(value);
+        if (!parsed.ok) {
+            if (parsed.reason === "non-canonical-network")
+                fail(`${cidrPath} must use the canonical network address with no host bits set`);
+            if (parsed.overlap === "ipv4-mapped")
+                fail(`${cidrPath} overlaps IPv4-mapped ::ffff:0:0/96 address space`);
+            if (parsed.overlap === "ipv4-compatible")
+                fail(`${cidrPath} overlaps IPv4-compatible ::/96 address space`);
+            fail(`${cidrPath} must be an IPv6 CIDR in address/nn form`);
+        }
+        const duplicateKey = `${formatIpv6(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}]`;
@@ -163,8 +203,17 @@ export function parseNativeEgressPolicy(value) {
                 const sourceHostSuffixes = rule.sourceHostSuffixes === undefined
                     ? []
                     : hostSuffixes(rule.sourceHostSuffixes, `${fieldPath}.sourceHostSuffixes`);
-                if (sourceHost === undefined && sourceHostSuffixes.length === 0)
-                    fail(`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes list`);
+                const sourceIpv4Cidrs = rule.sourceIpv4Cidrs === undefined
+                    ? []
+                    : ipv4Cidrs(rule.sourceIpv4Cidrs, `${fieldPath}.sourceIpv4Cidrs`);
+                const sourceIpv6Cidrs = rule.sourceIpv6Cidrs === undefined
+                    ? []
+                    : ipv6Cidrs(rule.sourceIpv6Cidrs, `${fieldPath}.sourceIpv6Cidrs`);
+                if (sourceHost === undefined &&
+                    sourceHostSuffixes.length === 0 &&
+                    sourceIpv4Cidrs.length === 0 &&
+                    sourceIpv6Cidrs.length === 0)
+                    fail(`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes, sourceIpv4Cidrs, or sourceIpv6Cidrs list`);
                 const sourcePorts = rule.sourcePorts === undefined
                     ? []
                     : ports(rule.sourcePorts, `${fieldPath}.sourcePorts`);
@@ -173,9 +222,19 @@ 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`);
+                const targetIpv6Cidrs = rule.targetIpv6Cidrs === undefined
+                    ? []
+                    : ipv6Cidrs(rule.targetIpv6Cidrs, `${fieldPath}.targetIpv6Cidrs`);
+                if (targetHostSuffixes.length === 0 &&
+                    targetIpv4Cidrs.length === 0 &&
+                    targetIpv6Cidrs.length === 0)
+                    fail(`${fieldPath} must declare a non-empty targetHostSuffixes, targetIpv4Cidrs, or targetIpv6Cidrs list`);
                 const targetPorts = rule.targetPorts === undefined
                     ? []
                     : ports(rule.targetPorts, `${fieldPath}.targetPorts`);
@@ -187,9 +246,13 @@ export function parseNativeEgressPolicy(value) {
                 return {
                     ...(sourceHost === undefined ? {} : { sourceHost }),
                     sourceHostSuffixes,
+                    sourceIpv4Cidrs,
+                    sourceIpv6Cidrs,
                     sourcePorts,
                     sourcePortRanges,
                     targetHostSuffixes,
+                    targetIpv4Cidrs,
+                    targetIpv6Cidrs,
                     targetPorts,
                     targetPortRanges,
                     tls: tls(rule.tls, `${fieldPath}.tls`),

package/dist/provider.d.ts

@@ -8,5 +8,5 @@ export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } f
 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, 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, 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 { 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,12 @@
 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 DynamicEgressRuleSnapshot } from "../native-egress-policy.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 +15,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 +25,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 +43,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 +86,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,13 +102,17 @@ 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;
+/** Internal validator-independent source selector matcher. */
+export declare function matchesSourceHost(rule: DynamicEgressRuleSnapshot, host: string): boolean;
 /** Internal canonical snapshot shared by production and SDK transport test doubles. */
 export declare function snapshotNativeConnectInput(input: NativeNetworkConnectInput): NativeNetworkConnectInput;
 /** Internal canonical snapshot shared by production and SDK transport test doubles. */