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

package/dist/runtime/native-network.js

@@ -2,16 +2,20 @@ import { createHash } from "node:crypto";
 import { Socket } from "node:net";
 import { connect as connectTlsSocket } from "node:tls";
 import { SocksClient } from "socks";
-import { ProxyResolutionError } from "../config/loader.js";
+import { assertTunnelingScheme, ProxyResolutionError, SMARTPROXY_APP_KEY_ENV, VENDOR_DEFAULT_PROTOCOL, resolveWithVendor, } from "../config/loader.js";
 import { TransportError } from "../errors.js";
 import { NativeEgressPolicyValidationError, parseNativeEgressPolicy, } from "../native-egress-policy.js";
-import { hasNodemavenCredentials, nodemavenSessionWindow, synthesizeNodemavenProxy, } from "./proxy-nodemaven.js";
+import { canonicalizeEgressHost, classifyEgressHost, embeddedIpv4FromIpv6, ipv4InCidr, ipv6InCidr, parseIpv6, parseStrictIpv4, } from "../native-address.js";
+import { createEnvContext } from "./env.js";
+import { NODEMAVEN_FILTER_ENV, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, nodemavenSessionWindow, synthesizeNodemavenProxy, } from "./proxy-nodemaven.js";
+import { redactSensitiveError } from "./request-options.js";
 export class NativeNetworkError extends TransportError {
-    constructor(message, code) {
+    constructor(message, code, cause) {
         const isEgressPolicyFailure = code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
         super(message, {
             code,
             status: 0,
+            ...(cause ? { cause } : {}),
             ...(isEgressPolicyFailure ? { category: "provider_error", retryable: false } : {}),
         });
         this.name = "NativeNetworkError";
@@ -20,6 +24,10 @@ export class NativeNetworkError extends TransportError {
         return super.code;
     }
 }
+function safeDiagnosticEgressHost(value) {
+    const canonical = canonicalizeEgressHost(value);
+    return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
 export class NativeProxyExpiredError extends NativeNetworkError {
     expiresAt;
     constructor(expiresAt) {
@@ -30,14 +38,15 @@ export class NativeProxyExpiredError extends NativeNetworkError {
 }
 /** Raised before transport setup when a native destination is not authorized. */
 export class NativeEgressNotDeclaredError extends NativeNetworkError {
-    host;
     port;
     tls;
+    host;
     constructor(host, port, tls) {
-        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${host}:${port}`, "native_egress_not_declared");
-        this.host = host;
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`, "native_egress_not_declared");
         this.port = port;
         this.tls = tls;
+        this.host = diagnosticHost;
         this.name = "NativeEgressNotDeclaredError";
     }
 }
@@ -46,16 +55,17 @@ export class NativeEgressNotDeclaredError extends NativeNetworkError {
  * its expiry remains in the client's bounded recent-expiry evidence window.
  */
 export class NativeEgressGrantExpiredError extends NativeNetworkError {
-    host;
     port;
     tls;
     expiresAt;
+    host;
     constructor(host, port, tls, expiresAt) {
-        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${host}:${port}`, "native_egress_grant_expired");
-        this.host = host;
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`, "native_egress_grant_expired");
         this.port = port;
         this.tls = tls;
         this.expiresAt = expiresAt;
+        this.host = diagnosticHost;
         this.name = "NativeEgressGrantExpiredError";
     }
 }
@@ -66,17 +76,69 @@ export class NativeIdleTimeoutError extends NativeNetworkError {
         this.name = "NativeIdleTimeoutError";
     }
 }
+const VENDOR_CREDENTIAL_NAMES = {
+    smartproxy: [SMARTPROXY_APP_KEY_ENV],
+    nodemaven: [NODEMAVEN_USERNAME_ENV, NODEMAVEN_PASSWORD_ENV],
+};
+/** Build a resolver over the SDK's existing injectable environment context. */
+export function createEnvVendorCredentialResolver(env = createEnvContext()) {
+    return (vendor) => {
+        const names = VENDOR_CREDENTIAL_NAMES[vendor] ?? [];
+        const values = {};
+        const missing = [];
+        for (const name of names) {
+            const value = env.get(name)?.trim();
+            if (value)
+                values[name] = value;
+            else
+                missing.push(name);
+        }
+        if (missing.length > 0 || names.length === 0)
+            return { kind: "absent", missing };
+        if (vendor === "nodemaven") {
+            const filter = env.get(NODEMAVEN_FILTER_ENV)?.trim();
+            if (filter)
+                values[NODEMAVEN_FILTER_ENV] = filter;
+        }
+        return { kind: "present", values };
+    };
+}
+function skipped(reason) {
+    return { kind: "skipped", reason };
+}
+function lookupCredentials(input) {
+    try {
+        return input.credentials(input.vendor);
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            cause: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
 function synthesizeNodemavenGateway(input) {
-    if (input.vendor !== "nodemaven" || !hasNodemavenCredentials())
+    if (input.vendor !== "nodemaven")
         return undefined;
-    // NodeMaven defaults ctx.http to HTTP CONNECT because SOCKS5 adds ~500ms per
-    // request. Native LOCO pays this once per long-lived connection and must reach
-    // arbitrary destination ports, so SOCKS5 is mandatory here.
+    const lookup = lookupCredentials(input);
+    if (lookup.kind === "error") {
+        return skipped({ kind: "credential_lookup_failed", cause: lookup.cause });
+    }
+    if (lookup.kind === "absent") {
+        return skipped({ kind: "credentials_absent", missing: lookup.missing });
+    }
     const sessionWindow = nodemavenSessionWindow(input.policy, input.now);
     const synthesized = synthesizeNodemavenProxy({
         policy: input.policy,
+        credentials: {
+            username: lookup.values[NODEMAVEN_USERNAME_ENV] ?? "",
+            password: lookup.values[NODEMAVEN_PASSWORD_ENV] ?? "",
+            ...(lookup.values[NODEMAVEN_FILTER_ENV]
+                ? { filter: lookup.values[NODEMAVEN_FILTER_ENV] }
+                : {}),
+        },
         affinityKey: input.affinityKey,
-        protocol: "socks5",
+        protocol: input.protocol,
         poolIndex: 0,
         refreshEpoch: sessionWindow.refreshEpoch,
         now: input.now,
@@ -90,7 +152,48 @@ function synthesizeNodemavenGateway(input) {
         expiresAt: synthesized.expiresAt,
     };
 }
+async function synthesizeSmartproxyGateway(input) {
+    if (input.vendor !== "smartproxy")
+        return undefined;
+    const lookup = lookupCredentials(input);
+    if (lookup.kind === "error") {
+        return skipped({ kind: "credential_lookup_failed", cause: lookup.cause });
+    }
+    if (lookup.kind === "absent") {
+        return skipped({ kind: "credentials_absent", missing: lookup.missing });
+    }
+    try {
+        const resolved = await resolveWithVendor("smartproxy", input.policy, {
+            proxyPolicy: input.policy,
+            affinityKey: input.affinityKey,
+            protocol: input.protocol,
+        }, {
+            protocol: input.protocol,
+            poolIndex: 0,
+            refreshEpoch: 0,
+            credentials: lookup.values,
+            ambientDefaults: false,
+            sharedCache: false,
+        });
+        if (!resolved.url) {
+            return skipped({ kind: "allocation_failed", cause: new Error("No endpoint returned") });
+        }
+        return {
+            url: resolved.url,
+            vendor: "smartproxy",
+            sticky: isStickyPolicy(input.policy),
+        };
+    }
+    catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        return skipped({
+            kind: "allocation_failed",
+            cause: redactSensitiveError(cause, Object.values(lookup.values)),
+        });
+    }
+}
 const DEFAULT_GATEWAY_SYNTHESIZERS = [
+    synthesizeSmartproxyGateway,
     synthesizeNodemavenGateway,
 ];
 /** Domain-separated, process-independent affinity derived from credential identity. */
@@ -116,29 +219,104 @@ function resolveNativeVendorChain(policy) {
     }
     return chain;
 }
-/** Resolve the first configured native gateway without invoking an allocator API. */
-export function resolveNativeGatewayProxy(input) {
+function isProxyProtocol(value) {
+    return value === "http" || value === "socks5";
+}
+function isSkippedSynthesis(result) {
+    return "kind" in result && result.kind === "skipped";
+}
+function sanitizeVendorResolutionCause(error, vendor, credentials) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    try {
+        const lookup = credentials(vendor);
+        return lookup.kind === "present"
+            ? redactSensitiveError(cause, Object.values(lookup.values))
+            : cause;
+    }
+    catch {
+        return cause;
+    }
+}
+function sanitizeVendorSkipReason(reason, vendor, credentials) {
+    return reason.kind === "allocation_failed" || reason.kind === "credential_lookup_failed"
+        ? {
+            ...reason,
+            cause: sanitizeVendorResolutionCause(reason.cause, vendor, credentials),
+        }
+        : reason;
+}
+function defaultVendorProtocol(vendor) {
+    return vendor === "smartproxy" || vendor === "nodemaven"
+        ? VENDOR_DEFAULT_PROTOCOL[vendor]
+        : "http";
+}
+async function resolveNativeGatewayProxyDetailed(input) {
     if (input.policy.mode === "disabled")
-        return undefined;
+        return { skips: [] };
     const synthesizers = input.gatewaySynthesizers ?? DEFAULT_GATEWAY_SYNTHESIZERS;
+    const credentials = input.credentials ?? createEnvVendorCredentialResolver();
     const now = input.now ?? Date.now();
+    const skips = [];
     for (const vendor of resolveNativeVendorChain(input.policy)) {
+        const protocol = input.protocol ?? defaultVendorProtocol(vendor);
+        if (!isProxyProtocol(protocol)) {
+            skips.push({ vendor, reason: { kind: "protocol_unsupported", protocol: String(protocol) } });
+            continue;
+        }
+        let vendorSkip;
         for (const synthesize of synthesizers) {
-            const resolved = synthesize({
-                vendor,
-                policy: input.policy,
-                affinityKey: input.affinityKey,
-                now,
-            });
-            if (resolved && resolved.vendor === vendor)
-                return resolved;
+            try {
+                const resolved = await synthesize({
+                    vendor,
+                    policy: input.policy,
+                    affinityKey: input.affinityKey,
+                    now,
+                    protocol,
+                    credentials,
+                });
+                if (!resolved)
+                    continue;
+                if (isSkippedSynthesis(resolved)) {
+                    vendorSkip = sanitizeVendorSkipReason(resolved.reason, vendor, credentials);
+                    continue;
+                }
+                if (resolved.vendor === vendor) {
+                    assertTunnelingScheme(resolved.url);
+                    return { proxy: resolved, skips };
+                }
+            }
+            catch (error) {
+                vendorSkip = {
+                    kind: "allocation_failed",
+                    cause: sanitizeVendorResolutionCause(error, vendor, credentials),
+                };
+            }
         }
+        skips.push({ vendor, reason: vendorSkip ?? { kind: "adapter_unavailable" } });
     }
-    return undefined;
+    return { skips };
+}
+/** Resolve the first configured native gateway, including allocation vendors. */
+export async function resolveNativeGatewayProxy(input) {
+    return (await resolveNativeGatewayProxyDetailed(input)).proxy;
 }
-function proxyRequiredError(policy) {
+function formatVendorSkip(skip) {
+    switch (skip.reason.kind) {
+        case "credentials_absent":
+            return `${skip.vendor}: credentials absent (missing ${skip.reason.missing.join(", ") || "unspecified variables"})`;
+        case "protocol_unsupported":
+            return `${skip.vendor}: protocol ${skip.reason.protocol} is unsupported`;
+        case "allocation_failed":
+            return `${skip.vendor}: allocation failed (${skip.reason.cause.message})`;
+        case "credential_lookup_failed":
+            return `${skip.vendor}: credential lookup failed (${skip.reason.cause.message})`;
+        case "adapter_unavailable":
+            return `${skip.vendor}: no native adapter is registered`;
+    }
+}
+function proxyRequiredError(policy, skips) {
     const chain = resolveNativeVendorChain(policy).filter((vendor) => vendor === "smartproxy" || vendor === "nodemaven");
-    return new ProxyResolutionError("PROXY_REQUIRED", `Native proxy egress is required but no gateway vendor in [${chain.join(", ") || "none"}] resolved.`, { vendorChain: chain });
+    return new ProxyResolutionError("PROXY_REQUIRED", `Native proxy egress is required but the vendor chain was exhausted: ${skips.map(formatVendorSkip).join("; ") || "no vendors declared"}.`, { vendorChain: chain });
 }
 function deadlineFrom(timeoutMs) {
     if (timeoutMs === undefined)
@@ -154,8 +332,8 @@ function abortError() {
 function timeoutError() {
     return new NativeNetworkError("Native connection timed out", "native_connection_timeout");
 }
-function failedError() {
-    return new NativeNetworkError("Native connection failed", "native_connection_failed");
+function failedError(cause) {
+    return new NativeNetworkError("Native connection failed", "native_connection_failed", cause);
 }
 function assertCanStart(signal, deadline) {
     if (signal?.aborted)
@@ -186,7 +364,7 @@ async function waitForSocketEvent(socket, event, signal, deadline) {
                 resolve();
         };
         const onReady = () => finish();
-        const onError = () => finish(failedError());
+        const onError = (cause) => finish(failedError(cause));
         const onClose = () => finish(failedError());
         const onAbort = () => finish(abortError());
         socket.once(event, onReady);
@@ -230,7 +408,104 @@ function parseSocks5Proxy(proxyUrl) {
         throw new NativeNetworkError("Native proxy URL is invalid", "native_proxy_invalid");
     }
 }
-async function waitForSocksHandshake(proxySocket, promise, signal, deadline) {
+function parseHttpConnectProxy(proxyUrl) {
+    let parsed;
+    try {
+        parsed = new URL(proxyUrl);
+    }
+    catch {
+        throw new NativeNetworkError("Native proxy URL is invalid", "native_proxy_invalid");
+    }
+    const port = Number(parsed.port || "80");
+    if (parsed.protocol !== "http:" ||
+        !parsed.hostname ||
+        !Number.isInteger(port) ||
+        port <= 0 ||
+        parsed.pathname !== "/" ||
+        parsed.search ||
+        parsed.hash) {
+        throw new NativeNetworkError("Native proxy URL is invalid", "native_proxy_invalid");
+    }
+    try {
+        return {
+            host: parsed.hostname,
+            port,
+            ...(parsed.username ? { userId: decodeURIComponent(parsed.username) } : {}),
+            ...(parsed.password ? { password: decodeURIComponent(parsed.password) } : {}),
+        };
+    }
+    catch {
+        throw new NativeNetworkError("Native proxy URL is invalid", "native_proxy_invalid");
+    }
+}
+const SOCKS5_REPLY_CODES = {
+    Failure: 0x01,
+    NotAllowed: 0x02,
+    NetworkUnreachable: 0x03,
+    HostUnreachable: 0x04,
+    ConnectionRefused: 0x05,
+    TTLExpired: 0x06,
+    CommandNotSupported: 0x07,
+    AddressNotSupported: 0x08,
+};
+function socks5ReplyCode(error) {
+    const match = /Socks5 proxy rejected connection - ([A-Za-z]+)/i.exec(error.message);
+    if (!match?.[1])
+        return undefined;
+    const reply = Object.entries(SOCKS5_REPLY_CODES).find(([name]) => name.toLowerCase() === match[1]?.toLowerCase());
+    return reply?.[1];
+}
+function sanitizeProxyFailureCause(error, proxyUrl, credentials) {
+    // socks' SocksClientError retains the live socket in options. It is neither
+    // useful diagnostic payload nor serializable, so preserve the original error
+    // while replacing only that options object with a socket-free snapshot.
+    const options = Reflect.get(error, "options");
+    if (options && typeof options === "object" && !Array.isArray(options)) {
+        const snapshot = { ...options };
+        delete snapshot.existing_socket;
+        try {
+            Reflect.set(error, "options", snapshot);
+        }
+        catch {
+            // The recursive redactor below clones readonly diagnostics safely.
+        }
+    }
+    const replyCode = socks5ReplyCode(error);
+    if (replyCode !== undefined) {
+        try {
+            Object.defineProperty(error, "socks5ReplyCode", {
+                value: replyCode,
+                configurable: true,
+                enumerable: true,
+                writable: false,
+            });
+        }
+        catch {
+            // The reply label remains in message if an exotic error is immutable.
+        }
+    }
+    let redactedProxyUrl = proxyUrl;
+    try {
+        const parsed = new URL(proxyUrl);
+        parsed.username = "[REDACTED]";
+        parsed.password = "[REDACTED]";
+        redactedProxyUrl = parsed.toString();
+    }
+    catch {
+        // parseSocks5Proxy already validated this URL; keep a defensive fallback.
+    }
+    return redactSensitiveError(error, [
+        credentials.userId,
+        credentials.password,
+        credentials.userId !== undefined || credentials.password !== undefined
+            ? `${credentials.userId ?? ""}:${credentials.password ?? ""}`
+            : undefined,
+        credentials.userId !== undefined || credentials.password !== undefined
+            ? Buffer.from(`${credentials.userId ?? ""}:${credentials.password ?? ""}`).toString("base64")
+            : undefined,
+    ].filter((value) => typeof value === "string" && value.length > 0), proxyUrl, redactedProxyUrl);
+}
+async function waitForSocksHandshake(proxySocket, promise, signal, deadline, sanitizeFailure) {
     assertCanStart(signal, deadline);
     return await new Promise((resolve, reject) => {
         let settled = false;
@@ -261,7 +536,7 @@ async function waitForSocksHandshake(proxySocket, promise, signal, deadline) {
             timer = setTimeout(() => finish(timeoutError()), remaining);
         void promise.then((result) => finish(undefined, result.socket), (error) => finish(error instanceof Error && /\b(?:timed out|timeout)\b/i.test(error.message)
             ? timeoutError()
-            : failedError()));
+            : failedError(sanitizeFailure(error instanceof Error ? error : new Error(String(error))))));
     });
 }
 async function connectSocksTunnel(proxy, input, deadline, beforeDestinationConnect) {
@@ -286,7 +561,117 @@ async function connectSocksTunnel(proxy, input, deadline, beforeDestinationConne
         existing_socket: proxySocket,
         ...(remaining === undefined ? {} : { timeout: Math.max(1, remaining) }),
     });
-    return await waitForSocksHandshake(proxySocket, handshake, input.signal, deadline);
+    return await waitForSocksHandshake(proxySocket, handshake, input.signal, deadline, (error) => sanitizeProxyFailureCause(error, proxy.url, parsed));
+}
+function connectAuthority(host, port) {
+    return `${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${port}`;
+}
+function connectStatusError(statusLine, statusCode) {
+    const error = new Error(`HTTP CONNECT proxy rejected tunnel: ${statusLine || "invalid response"}`);
+    Object.defineProperties(error, {
+        connectStatusLine: {
+            value: statusLine || "invalid response",
+            configurable: true,
+            enumerable: true,
+        },
+        ...(statusCode === undefined
+            ? {}
+            : {
+                connectStatusCode: {
+                    value: statusCode,
+                    configurable: true,
+                    enumerable: true,
+                },
+            }),
+    });
+    return error;
+}
+async function waitForConnectResponse(proxySocket, signal, deadline, sanitizeFailure) {
+    assertCanStart(signal, deadline);
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let buffered = Buffer.alloc(0);
+        let timer;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            proxySocket.off("data", onData);
+            proxySocket.off("error", onError);
+            proxySocket.off("close", onClose);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error) {
+                proxySocket.on("error", () => undefined);
+                proxySocket.destroy();
+                reject(error);
+            }
+            else
+                resolve(proxySocket);
+        };
+        const onError = (cause) => finish(failedError(sanitizeFailure(cause)));
+        const onClose = () => finish(failedError(sanitizeFailure(new Error("HTTP CONNECT proxy closed before response"))));
+        const onAbort = () => finish(abortError());
+        const onData = (chunk) => {
+            buffered = Buffer.concat([buffered, chunk]);
+            if (buffered.length > 64 * 1024) {
+                finish(failedError(sanitizeFailure(connectStatusError("response headers too large"))));
+                return;
+            }
+            const headerEnd = buffered.indexOf("\r\n\r\n");
+            if (headerEnd < 0)
+                return;
+            const header = buffered.subarray(0, headerEnd).toString("latin1");
+            const statusLine = header.split("\r\n", 1)[0] ?? "";
+            const match = /^HTTP\/1\.[01] ([0-9]{3})(?: |$)/.exec(statusLine);
+            const statusCode = match?.[1] ? Number(match[1]) : undefined;
+            if (statusCode === undefined || statusCode < 200 || statusCode >= 300) {
+                finish(failedError(sanitizeFailure(connectStatusError(statusLine, statusCode))));
+                return;
+            }
+            const remaining = buffered.subarray(headerEnd + 4);
+            cleanup();
+            if (remaining.length > 0)
+                proxySocket.unshift(remaining);
+            finish();
+        };
+        proxySocket.on("data", onData);
+        proxySocket.once("error", onError);
+        proxySocket.once("close", onClose);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const remaining = remainingMs(deadline);
+        if (remaining !== undefined)
+            timer = setTimeout(() => finish(timeoutError()), remaining);
+    });
+}
+async function connectHttpTunnel(proxy, input, deadline, beforeDestinationConnect) {
+    const parsed = parseHttpConnectProxy(proxy.url);
+    const proxySocket = await connectPlainSocket(parsed.host, parsed.port, input.signal, deadline);
+    const sanitizeFailure = (error) => sanitizeProxyFailureCause(error, proxy.url, parsed);
+    try {
+        beforeDestinationConnect();
+    }
+    catch (error) {
+        proxySocket.destroy();
+        throw error;
+    }
+    const authority = connectAuthority(input.host, input.port);
+    const authorization = parsed.userId !== undefined || parsed.password !== undefined
+        ? `Proxy-Authorization: Basic ${Buffer.from(`${parsed.userId ?? ""}:${parsed.password ?? ""}`).toString("base64")}\r\n`
+        : "";
+    const response = waitForConnectResponse(proxySocket, input.signal, deadline, sanitizeFailure);
+    proxySocket.write(`CONNECT ${authority} HTTP/1.1\r\nHost: ${authority}\r\n${authorization}Proxy-Connection: Keep-Alive\r\n\r\n`);
+    return await response;
+}
+async function connectProxyTunnel(proxy, input, deadline, beforeDestinationConnect) {
+    assertTunnelingScheme(proxy.url);
+    return new URL(proxy.url).protocol === "http:"
+        ? await connectHttpTunnel(proxy, input, deadline, beforeDestinationConnect)
+        : await connectSocksTunnel(proxy, input, deadline, beforeDestinationConnect);
 }
 async function upgradeTls(socket, input, deadline) {
     assertCanStart(input.signal, deadline);
@@ -399,7 +784,7 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
         if (closeReason)
             throw closeReason;
         if (terminalError)
-            throw failedError();
+            throw failedError(terminalError);
         const chunk = socket.read();
         if (chunk) {
             resetIdleTimer();
@@ -456,7 +841,7 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
             await new Promise((resolve, reject) => {
                 socket.write(data, (error) => {
                     if (error)
-                        reject(failedError());
+                        reject(failedError(error));
                     else
                         resolve();
                 });
@@ -474,7 +859,7 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
         },
     };
 }
-async function resolveConnectionProxy(options, input) {
+async function resolveConnectionProxy(options, input, deadline) {
     const policy = options.proxyPolicy;
     if (!policy || policy.mode === "disabled")
         return undefined;
@@ -483,31 +868,85 @@ async function resolveConnectionProxy(options, input) {
         (isStickyPolicy(policy) && options.credentialIdentity !== undefined
             ? deriveNativeCredentialAffinityKey(options.credentialIdentity)
             : undefined);
-    const resolved = resolveNativeGatewayProxy({
+    const resolution = await waitForProxyResolution(resolveNativeGatewayProxyDetailed({
         policy,
         affinityKey,
+        protocol: options.proxyProtocol,
+        credentials: options.credentials,
         gatewaySynthesizers: options.gatewaySynthesizers,
+    }), input.signal, deadline);
+    if (!resolution.proxy && policy.mode === "required") {
+        throw proxyRequiredError(policy, resolution.skips);
+    }
+    return resolution.proxy;
+}
+async function waitForProxyResolution(promise, signal, deadline) {
+    assertCanStart(signal, deadline);
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const finish = (value, error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error !== undefined)
+                reject(error);
+            else
+                resolve(value);
+        };
+        const onAbort = () => finish(undefined, abortError());
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const remaining = remainingMs(deadline);
+        if (remaining !== undefined) {
+            timer = setTimeout(() => finish(undefined, timeoutError()), remaining);
+        }
+        void promise.then((value) => finish(value), (error) => finish(undefined, error));
     });
-    if (!resolved && policy.mode === "required")
-        throw proxyRequiredError(policy);
-    return resolved;
 }
 export const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;
-function normalizeEgressHost(host) {
-    return host.trim().toLowerCase().replace(/\.$/, "");
-}
 function invalidPolicy(message) {
     return new NativeNetworkError(message, "native_egress_policy_invalid");
 }
 function matchesDnsSuffix(host, suffix) {
     return host === suffix || host.endsWith(`.${suffix}`);
 }
-function matchesSourceHost(rule, host) {
-    const hasSelector = rule.sourceHost !== undefined || rule.sourceHostSuffixes.length > 0;
+/** Internal validator-independent source selector matcher. */
+export function matchesSourceHost(rule, host) {
+    const kind = classifyEgressHost(host);
+    if (kind === "numeric-ambiguous")
+        return false;
+    const hasSelector = rule.sourceHost !== undefined ||
+        rule.sourceHostSuffixes.length > 0 ||
+        rule.sourceIpv4Cidrs.length > 0 ||
+        rule.sourceIpv6Cidrs.length > 0;
     if (!hasSelector)
         return false;
-    return (host === rule.sourceHost ||
-        rule.sourceHostSuffixes.some((suffix) => matchesDnsSuffix(host, suffix)));
+    if (host === rule.sourceHost)
+        return true;
+    return matchesHostFamilySelectors(host, rule.sourceHostSuffixes, rule.sourceIpv4Cidrs, rule.sourceIpv6Cidrs);
+}
+function matchesHostFamilySelectors(host, hostSuffixes, ipv4Cidrs, ipv6Cidrs) {
+    const kind = classifyEgressHost(host);
+    if (kind === "ipv4") {
+        const address = parseStrictIpv4(host);
+        return address !== undefined && ipv4Cidrs.some((cidr) => ipv4InCidr(address, cidr));
+    }
+    if (kind === "ipv4-mapped-ipv6") {
+        const address = parseIpv6(host);
+        const embedded = address && embeddedIpv4FromIpv6(address);
+        return embedded !== undefined && ipv4Cidrs.some((cidr) => ipv4InCidr(embedded, cidr));
+    }
+    if (kind === "ipv6") {
+        const address = parseIpv6(host);
+        return address !== undefined && ipv6Cidrs.some((cidr) => ipv6InCidr(address, cidr));
+    }
+    return kind === "dns" && hostSuffixes.some((suffix) => matchesDnsSuffix(host, suffix));
 }
 function matchesPortSelectors(port, ports, ranges) {
     if (ports.length === 0 && ranges.length === 0)
@@ -523,37 +962,29 @@ function grantTlsFitsRule(grant, rule) {
         (grant === "disabled" && rule === "disabled"));
 }
 function matchesDynamicRuleSelectors(rule, input) {
-    const sourceHost = normalizeEgressHost(input.sourceHost);
-    const targetHost = normalizeEgressHost(input.host);
-    return (matchesSourceHost(rule, sourceHost) &&
+    return (matchesSourceHost(rule, input.sourceHost) &&
         matchesPortSelectors(input.sourcePort, rule.sourcePorts, rule.sourcePortRanges) &&
-        rule.targetHostSuffixes.some((suffix) => matchesDnsSuffix(targetHost, suffix)) &&
+        matchesDynamicTargetHost(rule, input.host) &&
         matchesPortSelectors(input.port, rule.targetPorts, rule.targetPortRanges) &&
         grantTlsFitsRule(input.tls, rule.tls));
 }
+function matchesDynamicTargetHost(rule, targetHost) {
+    return matchesHostFamilySelectors(targetHost, rule.targetHostSuffixes, rule.targetIpv4Cidrs, rule.targetIpv6Cidrs);
+}
 function invalidGrant(message) {
     return new NativeNetworkError(message, "native_egress_grant_invalid");
 }
-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 canonicalGrantHost(value) {
+    if (typeof value === "string" && value.includes("*"))
+        throw invalidGrant("Native TCP egress grant hosts must be exact non-empty hostnames");
+    const canonical = canonicalizeEgressHost(value);
+    if (!canonical.ok)
+        throw invalidGrant("Native TCP egress grant hosts must be exact non-empty hostnames");
+    return canonical.host;
 }
 function assertValidGrantInput(input) {
-    if (!normalizeEgressHost(input.sourceHost) ||
-        !normalizeEgressHost(input.host) ||
-        hasControlCharacter(input.sourceHost) ||
-        hasControlCharacter(input.host) ||
-        /\s/.test(input.sourceHost) ||
-        /\s/.test(input.host) ||
-        input.sourceHost.includes("://") ||
-        input.host.includes("://") ||
-        input.sourceHost.includes("*") ||
-        input.host.includes("*"))
-        throw invalidGrant("Native TCP egress grant hosts must be exact non-empty hostnames");
+    canonicalGrantHost(input.sourceHost);
+    canonicalGrantHost(input.host);
     if (!Number.isSafeInteger(input.sourcePort) ||
         input.sourcePort < 1 ||
         input.sourcePort > 65_535 ||
@@ -566,42 +997,46 @@ function assertValidGrantInput(input) {
     if (input.ttlMs !== undefined && (!Number.isSafeInteger(input.ttlMs) || input.ttlMs <= 0))
         throw invalidGrant("Native TCP egress grant ttlMs must be a positive integer");
 }
-/** Internal canonical snapshot shared by production and SDK transport test doubles. */
-export function snapshotNativeConnectInput(input) {
+function invalidNativeConnectInput(field, reason) {
+    return new NativeNetworkError(`Native connection input rejected: field=${field}; reason=${reason}`, "native_egress_input_invalid");
+}
+function inspectNativeConnectInputField(input, field) {
     try {
-        const host = input.host;
-        const port = input.port;
-        const serverName = input.serverName;
-        const rejectUnauthorized = input.rejectUnauthorized;
-        const idleTimeoutMs = input.idleTimeoutMs;
-        const timeoutMs = input.timeoutMs;
-        const signal = input.signal;
-        const affinityKey = input.affinityKey;
-        const snapshot = {
-            host,
-            port,
-            ...(serverName === undefined ? {} : { serverName }),
-            ...(rejectUnauthorized === undefined ? {} : { rejectUnauthorized }),
-            ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
-            ...(timeoutMs === undefined ? {} : { timeoutMs }),
-            ...(signal === undefined ? {} : { signal }),
-            ...(affinityKey === undefined ? {} : { affinityKey }),
-        };
-        if (typeof snapshot.host !== "string" ||
-            !snapshot.host.trim() ||
-            hasControlCharacter(snapshot.host) ||
-            !Number.isInteger(snapshot.port) ||
-            snapshot.port < 1 ||
-            snapshot.port > 65_535)
-            throw new TypeError("invalid native connection target");
-        return snapshot;
+        return input[field];
     }
     catch {
-        throw new NativeNetworkError("Native connection input could not be inspected safely", "native_egress_input_invalid");
+        throw invalidNativeConnectInput(field, "inspection-failure");
     }
 }
 /** Internal canonical snapshot shared by production and SDK transport test doubles. */
+export function snapshotNativeConnectInput(input) {
+    const host = inspectNativeConnectInputField(input, "host");
+    const canonicalHost = canonicalizeEgressHost(host);
+    if (!canonicalHost.ok)
+        throw invalidNativeConnectInput("host", canonicalHost.reason);
+    const port = inspectNativeConnectInputField(input, "port");
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw invalidNativeConnectInput("port", "port-range");
+    const serverName = inspectNativeConnectInputField(input, "serverName");
+    const rejectUnauthorized = inspectNativeConnectInputField(input, "rejectUnauthorized");
+    const idleTimeoutMs = inspectNativeConnectInputField(input, "idleTimeoutMs");
+    const timeoutMs = inspectNativeConnectInputField(input, "timeoutMs");
+    const signal = inspectNativeConnectInputField(input, "signal");
+    const affinityKey = inspectNativeConnectInputField(input, "affinityKey");
+    return {
+        host: canonicalHost.host,
+        port,
+        ...(serverName === undefined ? {} : { serverName }),
+        ...(rejectUnauthorized === undefined ? {} : { rejectUnauthorized }),
+        ...(idleTimeoutMs === undefined ? {} : { idleTimeoutMs }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(signal === undefined ? {} : { signal }),
+        ...(affinityKey === undefined ? {} : { affinityKey }),
+    };
+}
+/** Internal canonical snapshot shared by production and SDK transport test doubles. */
 export function snapshotNativeGrantInput(input) {
+    let snapshot;
     try {
         const sourceHost = input.sourceHost;
         const sourcePort = input.sourcePort;
@@ -609,7 +1044,7 @@ export function snapshotNativeGrantInput(input) {
         const port = input.port;
         const tls = input.tls;
         const ttlMs = input.ttlMs;
-        return {
+        snapshot = {
             sourceHost,
             sourcePort,
             host,
@@ -621,6 +1056,12 @@ export function snapshotNativeGrantInput(input) {
     catch {
         throw new NativeNetworkError("Native TCP egress grant input could not be inspected safely", "native_egress_input_invalid");
     }
+    assertValidGrantInput(snapshot);
+    return {
+        ...snapshot,
+        sourceHost: canonicalGrantHost(snapshot.sourceHost),
+        host: canonicalGrantHost(snapshot.host),
+    };
 }
 /** Internal authorization seam shared by production and SDK transport test doubles. */
 export function createNativeEgressAuthorization(options) {
@@ -678,21 +1119,20 @@ export function createNativeEgressAuthorization(options) {
     const assertConnect = (input, tls) => {
         if (!declared)
             return;
-        const host = normalizeEgressHost(input.host);
         const now = Date.now();
         purgeInactive(now);
-        if (staticRules.some((rule) => rule.host === host && rule.ports.includes(input.port) && tlsModeAllows(rule.tls, tls)))
+        if (staticRules.some((rule) => rule.host === input.host &&
+            rule.ports.includes(input.port) &&
+            tlsModeAllows(rule.tls, tls)))
             return;
         const matching = grants.filter((grant) => !grant.revoked &&
-            grant.host === host &&
+            grant.host === input.host &&
             grant.port === input.port &&
             tlsModeAllows(grant.tls, tls));
         if (matching.length > 0)
             return;
         const expired = [...expiredEvidence.values()]
-            .filter((grant) => grant.host === host &&
-            grant.port === input.port &&
-            tlsModeAllows(grant.tls, tls))
+            .filter((grant) => grant.host === input.host && grant.port === input.port && tlsModeAllows(grant.tls, tls))
             .sort((left, right) => (right.expiresAtMs ?? 0) - (left.expiresAtMs ?? 0))[0];
         if (expired?.expiresAtMs !== undefined)
             throw new NativeEgressGrantExpiredError(input.host, input.port, tls, new Date(expired.expiresAtMs).toISOString());
@@ -701,15 +1141,51 @@ export function createNativeEgressAuthorization(options) {
     const grantLocal = (input) => {
         assertValidGrantInput(input);
         const ruleIndex = dynamicRules.findIndex((rule) => matchesDynamicRuleSelectors(rule, input));
-        if (ruleIndex < 0)
-            throw new NativeNetworkError(`Native TCP egress grant is not declared for ${input.host}:${input.port} (${input.tls})`, "native_egress_not_declared");
+        if (ruleIndex < 0) {
+            const diagnosticSourceHost = safeDiagnosticEgressHost(input.sourceHost);
+            const diagnosticTargetHost = safeDiagnosticEgressHost(input.host);
+            const sourceMatchingRuleIndices = dynamicRules.flatMap((rule, index) => matchesSourceHost(rule, input.sourceHost) &&
+                matchesPortSelectors(input.sourcePort, rule.sourcePorts, rule.sourcePortRanges)
+                ? [index]
+                : []);
+            const targetKind = classifyEgressHost(diagnosticTargetHost);
+            let selectorDetails;
+            if (sourceMatchingRuleIndices.length > 0) {
+                const failedByRule = [];
+                for (const index of sourceMatchingRuleIndices) {
+                    const rule = dynamicRules[index];
+                    if (!rule)
+                        continue;
+                    const failedDimensions = [];
+                    if (!matchesDynamicTargetHost(rule, input.host))
+                        failedDimensions.push("target-host");
+                    if (!matchesPortSelectors(input.port, rule.targetPorts, rule.targetPortRanges))
+                        failedDimensions.push("target-port");
+                    if (!grantTlsFitsRule(input.tls, rule.tls))
+                        failedDimensions.push("tls");
+                    failedByRule.push(`rule ${index}: ${failedDimensions.join(", ")}`);
+                }
+                selectorDetails = `source-matching rule indices: [${sourceMatchingRuleIndices.join(", ")}]; failed selector dimensions by rule: ${failedByRule.join("; ")}`;
+            }
+            else {
+                const failedByRule = dynamicRules.map((rule, index) => {
+                    const failedDimensions = [];
+                    if (!matchesSourceHost(rule, input.sourceHost))
+                        failedDimensions.push("source-host");
+                    if (!matchesPortSelectors(input.sourcePort, rule.sourcePorts, rule.sourcePortRanges))
+                        failedDimensions.push("source-port");
+                    return `rule ${index}: ${failedDimensions.join(", ")}`;
+                });
+                selectorDetails = `source-matching rule indices: []; failed selector dimensions by rule: ${failedByRule.join("; ")}`;
+            }
+            throw new NativeNetworkError(`Native TCP egress grant is not declared for source ${diagnosticSourceHost}:${input.sourcePort} to target ${diagnosticTargetHost}:${input.port} (${input.tls}); target kind: ${targetKind}; ${selectorDetails}`, "native_egress_not_declared");
+        }
         const rule = dynamicRules[ruleIndex];
         if (!rule)
             throw invalidGrant("Native TCP egress declaration is missing its matched rule");
         if (input.ttlMs !== undefined && rule.ttlMs !== undefined && input.ttlMs > rule.ttlMs)
             throw invalidGrant(`Native TCP egress grant ttlMs ${input.ttlMs} exceeds declared maximum ${rule.ttlMs}`);
         const now = Date.now();
-        const targetHost = normalizeEgressHost(input.host);
         purgeInactive(now);
         const activeForRule = grants.filter((grant) => grant.ruleIndex === ruleIndex &&
             !grant.revoked &&
@@ -722,7 +1198,7 @@ export function createNativeEgressAuthorization(options) {
             throw invalidGrant("Native TCP egress grant expiry exceeds the supported date range");
         const stored = {
             ruleIndex,
-            host: targetHost,
+            host: input.host,
             port: input.port,
             tls: input.tls,
             ...(expiresAtMs === undefined ? {} : { expiresAtMs }),
@@ -797,10 +1273,10 @@ export function createNativeNetworkClient(options = {}) {
             egress.assertConnect(request, "disabled");
             const deadline = deadlineFrom(request.timeoutMs);
             assertCanStart(request.signal, deadline);
-            const proxy = await resolveConnectionProxy(options, request);
+            const proxy = await resolveConnectionProxy(options, request, deadline);
             egress.assertConnect(request, "disabled");
             const socket = proxy
-                ? await connectSocksTunnel(proxy, request, deadline, () => egress.assertConnect(request, "disabled"))
+                ? await connectProxyTunnel(proxy, request, deadline, () => egress.assertConnect(request, "disabled"))
                 : await connectPlainSocket(request.host, request.port, request.signal, deadline);
             return createNativeNetworkConnection(socket, proxy, options, request.idleTimeoutMs);
         },
@@ -809,10 +1285,10 @@ export function createNativeNetworkClient(options = {}) {
             egress.assertConnect(request, "required");
             const deadline = deadlineFrom(request.timeoutMs);
             assertCanStart(request.signal, deadline);
-            const proxy = await resolveConnectionProxy(options, request);
+            const proxy = await resolveConnectionProxy(options, request, deadline);
             egress.assertConnect(request, "required");
             const tunnel = proxy
-                ? await connectSocksTunnel(proxy, request, deadline, () => egress.assertConnect(request, "required"))
+                ? await connectProxyTunnel(proxy, request, deadline, () => egress.assertConnect(request, "required"))
                 : undefined;
             const socket = await upgradeTls(tunnel, request, deadline);
             return createNativeNetworkConnection(socket, proxy, options, request.idleTimeoutMs);