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

package/src/runtime/native-network.ts

@@ -4,18 +4,35 @@ import { connect as connectTlsSocket, type TLSSocket } from "node:tls";
 
 import { SocksClient } from "socks";
 
-import { ProxyResolutionError } from "../config/loader.js";
+import {
+	assertTunnelingScheme,
+	ProxyResolutionError,
+	SMARTPROXY_APP_KEY_ENV,
+	type ProxyProtocol,
+	VENDOR_DEFAULT_PROTOCOL,
+	resolveWithVendor,
+} from "../config/loader.js";
 import { TransportError } from "../errors.js";
 import {
+	type DynamicEgressRuleSnapshot,
 	NativeEgressPolicyValidationError,
 	parseNativeEgressPolicy,
-	type DynamicEgressRuleSnapshot,
 	type StaticEgressRuleSnapshot,
 } from "../native-egress-policy.js";
+import {
+	canonicalizeEgressHost,
+	classifyEgressHost,
+	type EgressHostCanonicalizationFailure,
+	embeddedIpv4FromIpv6,
+	ipv4InCidr,
+	ipv6InCidr,
+	parseIpv6,
+	parseStrictIpv4,
+} from "../native-address.js";
 import type {
 	NativeNetworkClient,
-	NativeNetworkConnection,
 	NativeNetworkConnectInput,
+	NativeNetworkConnection,
 	NativeNetworkDynamicGrantOptions,
 	NativeNetworkEgressGrant,
 	NativeProviderConfig,
@@ -26,12 +43,17 @@ import type {
 	NativeTcpTlsMode,
 	ProviderProxyPolicy,
 	ProviderProxyProvider,
+	EnvContext,
 } from "../types.js";
+import { createEnvContext } from "./env.js";
 import {
-	hasNodemavenCredentials,
+	NODEMAVEN_FILTER_ENV,
+	NODEMAVEN_PASSWORD_ENV,
+	NODEMAVEN_USERNAME_ENV,
 	nodemavenSessionWindow,
 	synthesizeNodemavenProxy,
 } from "./proxy-nodemaven.js";
+import { redactSensitiveError } from "./request-options.js";
 
 export type NativeNetworkErrorCode =
 	| "native_connection_aborted"
@@ -51,12 +73,13 @@ export type NativeNetworkErrorCode =
 	| "native_proxy_invalid";
 
 export class NativeNetworkError extends TransportError {
-	constructor(message: string, code: NativeNetworkErrorCode) {
+	constructor(message: string, code: NativeNetworkErrorCode, cause?: Error) {
 		const isEgressPolicyFailure =
 			code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
 		super(message, {
 			code,
 			status: 0,
+			...(cause ? { cause } : {}),
 			...(isEgressPolicyFailure ? { category: "provider_error" as const, retryable: false } : {}),
 		});
 		this.name = "NativeNetworkError";
@@ -67,6 +90,11 @@ export class NativeNetworkError extends TransportError {
 	}
 }
 
+function safeDiagnosticEgressHost(value: unknown): string {
+	const canonical = canonicalizeEgressHost(value);
+	return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
+
 export class NativeProxyExpiredError extends NativeNetworkError {
 	constructor(readonly expiresAt: string) {
 		super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
@@ -76,15 +104,19 @@ export class NativeProxyExpiredError extends NativeNetworkError {
 
 /** Raised before transport setup when a native destination is not authorized. */
 export class NativeEgressNotDeclaredError extends NativeNetworkError {
+	readonly host: string;
+
 	constructor(
-		readonly host: string,
+		host: string,
 		readonly port: number,
 		readonly tls: "required" | "disabled",
 	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
 		super(
-			`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${host}:${port}`,
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`,
 			"native_egress_not_declared",
 		);
+		this.host = diagnosticHost;
 		this.name = "NativeEgressNotDeclaredError";
 	}
 }
@@ -94,16 +126,20 @@ export class NativeEgressNotDeclaredError extends NativeNetworkError {
  * its expiry remains in the client's bounded recent-expiry evidence window.
  */
 export class NativeEgressGrantExpiredError extends NativeNetworkError {
+	readonly host: string;
+
 	constructor(
-		readonly host: string,
+		host: string,
 		readonly port: number,
 		readonly tls: "required" | "disabled",
 		readonly expiresAt: string,
 	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
 		super(
-			`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${host}:${port}`,
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`,
 			"native_egress_grant_expired",
 		);
+		this.host = diagnosticHost;
 		this.name = "NativeEgressGrantExpiredError";
 	}
 }
@@ -111,10 +147,7 @@ export class NativeEgressGrantExpiredError extends NativeNetworkError {
 /** Raised when an established connection exceeds its opt-in read-idle window. */
 export class NativeIdleTimeoutError extends NativeNetworkError {
 	constructor() {
-		super(
-			"Native network socket timed out while reading.",
-			"native_connection_idle_timeout",
-		);
+		super("Native network socket timed out while reading.", "native_connection_idle_timeout");
 		this.name = "NativeIdleTimeoutError";
 	}
 }
@@ -128,17 +161,38 @@ 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;
+) => 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[];
 };
 
@@ -147,6 +201,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. */
@@ -160,19 +218,74 @@ export type NativeNetworkClientOptions = {
 	readonly grantTcpEgress?: (input: NativeNetworkDynamicGrantOptions) => NativeNetworkEgressGrant;
 };
 
-function synthesizeNodemavenGateway(
+const VENDOR_CREDENTIAL_NAMES: Readonly<Partial<Record<ProviderProxyProvider, readonly string[]>>> =
+	{
+		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: EnvContext = createEnvContext(),
+): VendorCredentialResolver {
+	return (vendor) => {
+		const names = VENDOR_CREDENTIAL_NAMES[vendor] ?? [];
+		const values: Record<string, string> = {};
+		const missing: string[] = [];
+		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: NativeGatewayProxySkipReason): NativeGatewayProxySynthesisResult {
+	return { kind: "skipped", reason };
+}
+
+function lookupCredentials(
 	input: NativeGatewayProxySynthesisInput,
-): NativeGatewayProxy | undefined {
-	if (input.vendor !== "nodemaven" || !hasNodemavenCredentials()) return undefined;
+): VendorCredentialLookup | { readonly kind: "error"; readonly cause: Error } {
+	try {
+		return input.credentials(input.vendor);
+	} catch (error) {
+		return {
+			kind: "error",
+			cause: error instanceof Error ? error : new Error(String(error)),
+		};
+	}
+}
 
-	// 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.
+function synthesizeNodemavenGateway(
+	input: NativeGatewayProxySynthesisInput,
+): NativeGatewayProxySynthesisResult {
+	if (input.vendor !== "nodemaven") 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 });
+	}
 	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,
@@ -187,7 +300,54 @@ function synthesizeNodemavenGateway(
 	};
 }
 
+async function synthesizeSmartproxyGateway(
+	input: NativeGatewayProxySynthesisInput,
+): Promise<NativeGatewayProxySynthesisResult> {
+	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: readonly NativeGatewayProxySynthesizer[] = [
+	synthesizeSmartproxyGateway,
 	synthesizeNodemavenGateway,
 ];
 
@@ -216,35 +376,135 @@ function resolveNativeVendorChain(policy: ProviderProxyPolicy): ProviderProxyPro
 	return chain;
 }
 
-/** Resolve the first configured native gateway without invoking an allocator API. */
-export function resolveNativeGatewayProxy(
+type NativeGatewayVendorSkip = {
+	readonly vendor: ProviderProxyProvider;
+	readonly reason: NativeGatewayProxySkipReason | { readonly kind: "adapter_unavailable" };
+};
+
+function isProxyProtocol(value: unknown): value is ProxyProtocol {
+	return value === "http" || value === "socks5";
+}
+
+function isSkippedSynthesis(
+	result: Exclude<NativeGatewayProxySynthesisResult, undefined>,
+): result is { readonly kind: "skipped"; readonly reason: NativeGatewayProxySkipReason } {
+	return "kind" in result && result.kind === "skipped";
+}
+
+function sanitizeVendorResolutionCause(
+	error: unknown,
+	vendor: ProviderProxyProvider,
+	credentials: VendorCredentialResolver,
+): Error {
+	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: NativeGatewayProxySkipReason,
+	vendor: ProviderProxyProvider,
+	credentials: VendorCredentialResolver,
+): NativeGatewayProxySkipReason {
+	return reason.kind === "allocation_failed" || reason.kind === "credential_lookup_failed"
+		? {
+				...reason,
+				cause: sanitizeVendorResolutionCause(reason.cause, vendor, credentials),
+			}
+		: reason;
+}
+
+function defaultVendorProtocol(vendor: ProviderProxyProvider): ProxyProtocol {
+	return vendor === "smartproxy" || vendor === "nodemaven"
+		? VENDOR_DEFAULT_PROTOCOL[vendor]
+		: "http";
+}
+
+async function resolveNativeGatewayProxyDetailed(
 	input: NativeGatewayProxyResolutionInput,
-): NativeGatewayProxy | undefined {
-	if (input.policy.mode === "disabled") return undefined;
+): Promise<{ proxy?: NativeGatewayProxy; skips: readonly NativeGatewayVendorSkip[] }> {
+	if (input.policy.mode === "disabled") return { skips: [] };
 	const synthesizers = input.gatewaySynthesizers ?? DEFAULT_GATEWAY_SYNTHESIZERS;
+	const credentials = input.credentials ?? createEnvVendorCredentialResolver();
 	const now = input.now ?? Date.now();
+	const skips: NativeGatewayVendorSkip[] = [];
 	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: NativeGatewayVendorSkip["reason"] | undefined;
 		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 };
 }
 
-function proxyRequiredError(policy: ProviderProxyPolicy): ProxyResolutionError {
+/** Resolve the first configured native gateway, including allocation vendors. */
+export async function resolveNativeGatewayProxy(
+	input: NativeGatewayProxyResolutionInput,
+): Promise<NativeGatewayProxy | undefined> {
+	return (await resolveNativeGatewayProxyDetailed(input)).proxy;
+}
+
+function formatVendorSkip(skip: NativeGatewayVendorSkip): string {
+	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: ProviderProxyPolicy,
+	skips: readonly NativeGatewayVendorSkip[],
+): ProxyResolutionError {
 	const chain = resolveNativeVendorChain(policy).filter(
 		(vendor): vendor is "smartproxy" | "nodemaven" =>
 			vendor === "smartproxy" || vendor === "nodemaven",
 	);
 	return new ProxyResolutionError(
 		"PROXY_REQUIRED",
-		`Native proxy egress is required but no gateway vendor in [${chain.join(", ") || "none"}] resolved.`,
+		`Native proxy egress is required but the vendor chain was exhausted: ${skips.map(formatVendorSkip).join("; ") || "no vendors declared"}.`,
 		{ vendorChain: chain },
 	);
 }
@@ -268,8 +528,8 @@ function timeoutError(): NativeNetworkError {
 	return new NativeNetworkError("Native connection timed out", "native_connection_timeout");
 }
 
-function failedError(): NativeNetworkError {
-	return new NativeNetworkError("Native connection failed", "native_connection_failed");
+function failedError(cause?: Error): NativeNetworkError {
+	return new NativeNetworkError("Native connection failed", "native_connection_failed", cause);
 }
 
 function assertCanStart(signal: AbortSignal | undefined, deadline: Deadline): void {
@@ -302,7 +562,7 @@ async function waitForSocketEvent(
 			} else resolve();
 		};
 		const onReady = () => finish();
-		const onError = () => finish(failedError());
+		const onError = (cause: Error) => finish(failedError(cause));
 		const onClose = () => finish(failedError());
 		const onAbort = () => finish(abortError());
 
@@ -357,11 +617,129 @@ function parseSocks5Proxy(proxyUrl: string): {
 	}
 }
 
+function parseHttpConnectProxy(proxyUrl: string): {
+	host: string;
+	port: number;
+	userId?: string;
+	password?: string;
+} {
+	let parsed: URL;
+	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,
+} as const;
+
+function socks5ReplyCode(error: Error): number | undefined {
+	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: Error,
+	proxyUrl: string,
+	credentials: { readonly userId?: string; readonly password?: string },
+): Error {
+	// 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 as Record<string, unknown>) };
+		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): value is string => typeof value === "string" && value.length > 0),
+		proxyUrl,
+		redactedProxyUrl,
+	);
+}
+
 async function waitForSocksHandshake(
 	proxySocket: Socket,
 	promise: ReturnType<typeof SocksClient.createConnection>,
 	signal: AbortSignal | undefined,
 	deadline: Deadline,
+	sanitizeFailure: (error: Error) => Error,
 ): Promise<Socket> {
 	assertCanStart(signal, deadline);
 	return await new Promise<Socket>((resolve, reject) => {
@@ -391,7 +769,9 @@ async function waitForSocksHandshake(
 				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))),
+							),
 				),
 		);
 	});
@@ -423,7 +803,138 @@ async function connectSocksTunnel(
 		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: string, port: number): string {
+	return `${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${port}`;
+}
+
+function connectStatusError(statusLine: string, statusCode?: number): Error {
+	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: Socket,
+	signal: AbortSignal | undefined,
+	deadline: Deadline,
+	sanitizeFailure: (error: Error) => Error,
+): Promise<Socket> {
+	assertCanStart(signal, deadline);
+	return await new Promise<Socket>((resolve, reject) => {
+		let settled = false;
+		let buffered = Buffer.alloc(0);
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		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?: Error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			if (error) {
+				proxySocket.on("error", () => undefined);
+				proxySocket.destroy();
+				reject(error);
+			} else resolve(proxySocket);
+		};
+		const onError = (cause: Error) => finish(failedError(sanitizeFailure(cause)));
+		const onClose = () =>
+			finish(failedError(sanitizeFailure(new Error("HTTP CONNECT proxy closed before response"))));
+		const onAbort = () => finish(abortError());
+		const onData = (chunk: Buffer) => {
+			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: NativeGatewayProxy,
+	input: NativeNetworkConnectInput,
+	deadline: Deadline,
+	beforeDestinationConnect: () => void,
+): Promise<Socket> {
+	const parsed = parseHttpConnectProxy(proxy.url);
+	const proxySocket = await connectPlainSocket(parsed.host, parsed.port, input.signal, deadline);
+	const sanitizeFailure = (error: 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: NativeGatewayProxy,
+	input: NativeNetworkConnectInput,
+	deadline: Deadline,
+	beforeDestinationConnect: () => void,
+): Promise<Socket> {
+	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(
@@ -473,12 +984,15 @@ export function createNativeNetworkConnection(
 	const resetIdleTimer = () => {
 		clearIdleTimer();
 		if (idleTimeoutMs === undefined || socket.readableEnded || socket.destroyed) return;
-		idleTimer = setTimeout(() => {
-			idleTimer = undefined;
-			if (socket.readableEnded || socket.destroyed) return;
-			closeReason = new NativeIdleTimeoutError();
-			socket.destroy(closeReason);
-		}, Math.max(0, idleTimeoutMs));
+		idleTimer = setTimeout(
+			() => {
+				idleTimer = undefined;
+				if (socket.readableEnded || socket.destroyed) return;
+				closeReason = new NativeIdleTimeoutError();
+				socket.destroy(closeReason);
+			},
+			Math.max(0, idleTimeoutMs),
+		);
 		idleTimer.unref?.();
 	};
 	const clearLifecycle = () => {
@@ -541,7 +1055,7 @@ export function createNativeNetworkConnection(
 
 	const read = async (): Promise<Uint8Array | null> => {
 		if (closeReason) throw closeReason;
-		if (terminalError) throw failedError();
+		if (terminalError) throw failedError(terminalError);
 		const chunk = socket.read() as Buffer | null;
 		if (chunk) {
 			resetIdleTimer();
@@ -596,7 +1110,7 @@ export function createNativeNetworkConnection(
 			}
 			await new Promise<void>((resolve, reject) => {
 				socket.write(data, (error) => {
-					if (error) reject(failedError());
+					if (error) reject(failedError(error));
 					else resolve();
 				});
 			});
@@ -617,6 +1131,7 @@ export function createNativeNetworkConnection(
 async function resolveConnectionProxy(
 	options: NativeNetworkClientOptions,
 	input: NativeNetworkConnectInput,
+	deadline: Deadline,
 ): Promise<NativeGatewayProxy | undefined> {
 	const policy = options.proxyPolicy;
 	if (!policy || policy.mode === "disabled") return undefined;
@@ -626,13 +1141,54 @@ async function resolveConnectionProxy(
 		(isStickyPolicy(policy) && options.credentialIdentity !== undefined
 			? deriveNativeCredentialAffinityKey(options.credentialIdentity)
 			: undefined);
-	const resolved = resolveNativeGatewayProxy({
-		policy,
-		affinityKey,
-		gatewaySynthesizers: options.gatewaySynthesizers,
+	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<T>(
+	promise: Promise<T>,
+	signal: AbortSignal | undefined,
+	deadline: Deadline,
+): Promise<T> {
+	assertCanStart(signal, deadline);
+	return await new Promise<T>((resolve, reject) => {
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const cleanup = () => {
+			if (timer) clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		const finish = (value?: T, error?: unknown) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			if (error !== undefined) reject(error);
+			else resolve(value as T);
+		};
+		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;
 }
 
 type NativeConnectTls = "required" | "disabled";
@@ -648,10 +1204,6 @@ type StoredEgressGrant = {
 
 export const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;
 
-function normalizeEgressHost(host: string): string {
-	return host.trim().toLowerCase().replace(/\.$/, "");
-}
-
 function invalidPolicy(message: string): NativeNetworkError {
 	return new NativeNetworkError(message, "native_egress_policy_invalid");
 }
@@ -660,15 +1212,48 @@ function matchesDnsSuffix(host: string, suffix: string): boolean {
 	return host === suffix || host.endsWith(`.${suffix}`);
 }
 
-function matchesSourceHost(rule: DynamicEgressRuleSnapshot, host: string): boolean {
-	const hasSelector = rule.sourceHost !== undefined || rule.sourceHostSuffixes.length > 0;
+/** Internal validator-independent source selector matcher. */
+export function matchesSourceHost(rule: DynamicEgressRuleSnapshot, host: string): boolean {
+	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: string,
+	hostSuffixes: readonly string[],
+	ipv4Cidrs: readonly string[],
+	ipv6Cidrs: readonly string[],
+): boolean {
+	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: number,
 	ports: readonly number[],
@@ -694,43 +1279,40 @@ function matchesDynamicRuleSelectors(
 	rule: DynamicEgressRuleSnapshot,
 	input: NativeNetworkDynamicGrantOptions,
 ): boolean {
-	const sourceHost = normalizeEgressHost(input.sourceHost);
-	const targetHost = normalizeEgressHost(input.host);
 	return (
-		matchesSourceHost(rule, sourceHost) &&
+		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: DynamicEgressRuleSnapshot, targetHost: string): boolean {
+	return matchesHostFamilySelectors(
+		targetHost,
+		rule.targetHostSuffixes,
+		rule.targetIpv4Cidrs,
+		rule.targetIpv6Cidrs,
+	);
+}
+
 function invalidGrant(message: string): NativeNetworkError {
 	return new NativeNetworkError(message, "native_egress_grant_invalid");
 }
 
-function hasControlCharacter(value: string): boolean {
-	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: unknown): string {
+	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: NativeNetworkDynamicGrantOptions): void {
-	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 ||
@@ -746,51 +1328,65 @@ function assertValidGrantInput(input: NativeNetworkDynamicGrantOptions): void {
 		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(
+type NativeConnectInputRejectionReason =
+	| EgressHostCanonicalizationFailure
+	| "port-range"
+	| "inspection-failure";
+
+function invalidNativeConnectInput(
+	field: keyof NativeNetworkConnectInput,
+	reason: NativeConnectInputRejectionReason,
+): NativeNetworkError {
+	return new NativeNetworkError(
+		`Native connection input rejected: field=${field}; reason=${reason}`,
+		"native_egress_input_invalid",
+	);
+}
+
+function inspectNativeConnectInputField<K extends keyof NativeNetworkConnectInput>(
 	input: NativeNetworkConnectInput,
-): NativeNetworkConnectInput {
+	field: K,
+): NativeNetworkConnectInput[K] {
 	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: NativeNetworkConnectInput = {
-			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: NativeNetworkConnectInput,
+): NativeNetworkConnectInput {
+	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: NativeNetworkDynamicGrantOptions,
 ): NativeNetworkDynamicGrantOptions {
+	let snapshot: NativeNetworkDynamicGrantOptions;
 	try {
 		const sourceHost = input.sourceHost;
 		const sourcePort = input.sourcePort;
@@ -798,7 +1394,7 @@ export function snapshotNativeGrantInput(
 		const port = input.port;
 		const tls = input.tls;
 		const ttlMs = input.ttlMs;
-		return {
+		snapshot = {
 			sourceHost,
 			sourcePort,
 			host,
@@ -812,6 +1408,12 @@ export function snapshotNativeGrantInput(
 			"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. */
@@ -869,20 +1471,21 @@ export function createNativeEgressAuthorization(options: NativeNetworkClientOpti
 
 	const assertConnect = (input: NativeNetworkConnectInput, tls: NativeConnectTls): void => {
 		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),
+					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),
 		);
@@ -890,9 +1493,7 @@ export function createNativeEgressAuthorization(options: NativeNetworkClientOpti
 		const expired = [...expiredEvidence.values()]
 			.filter(
 				(grant) =>
-					grant.host === host &&
-					grant.port === input.port &&
-					tlsModeAllows(grant.tls, tls),
+					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)
@@ -908,11 +1509,45 @@ export function createNativeEgressAuthorization(options: NativeNetworkClientOpti
 	const grantLocal = (input: NativeNetworkDynamicGrantOptions): NativeNetworkEgressGrant => {
 		assertValidGrantInput(input);
 		const ruleIndex = dynamicRules.findIndex((rule) => matchesDynamicRuleSelectors(rule, input));
-		if (ruleIndex < 0)
+		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: string;
+			if (sourceMatchingRuleIndices.length > 0) {
+				const failedByRule: string[] = [];
+				for (const index of sourceMatchingRuleIndices) {
+					const rule = dynamicRules[index];
+					if (!rule) continue;
+					const failedDimensions: string[] = [];
+					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: string[] = [];
+					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 ${input.host}:${input.port} (${input.tls})`,
+				`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)
@@ -920,7 +1555,6 @@ export function createNativeEgressAuthorization(options: NativeNetworkClientOpti
 				`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) =>
@@ -939,7 +1573,7 @@ export function createNativeEgressAuthorization(options: NativeNetworkClientOpti
 			throw invalidGrant("Native TCP egress grant expiry exceeds the supported date range");
 		const stored: StoredEgressGrant = {
 			ruleIndex,
-			host: targetHost,
+			host: input.host,
 			port: input.port,
 			tls: input.tls,
 			...(expiresAtMs === undefined ? {} : { expiresAtMs }),
@@ -1023,10 +1657,10 @@ export function createNativeNetworkClient(
 			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, () =>
+				? await connectProxyTunnel(proxy, request, deadline, () =>
 						egress.assertConnect(request, "disabled"),
 					)
 				: await connectPlainSocket(request.host, request.port, request.signal, deadline);
@@ -1037,10 +1671,10 @@ export function createNativeNetworkClient(
 			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, () =>
+				? await connectProxyTunnel(proxy, request, deadline, () =>
 						egress.assertConnect(request, "required"),
 					)
 				: undefined;