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

package/src/config/loader.ts

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

package/src/define.ts

@@ -1,5 +1,6 @@
 import ms from "ms";
 
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
 import {
 	NativeEgressPolicyValidationError,
@@ -56,6 +57,7 @@ import {
 	STREAM_IDLE_TIMEOUT_MS_MIN,
 	STREAM_MAX_DURATION_MS_MAX,
 	STREAM_MAX_DURATION_MS_MIN,
+	VALID_OPERATION_ERROR_STATUSES,
 } from "./types.js";
 
 type ProviderImplementationSourceAccess =
@@ -800,6 +802,36 @@ function validateOperationObservability(
 	}
 }
 
+function validateOperationErrorCodes(
+	providerId: string,
+	operations: Record<string, ProviderOperation>,
+): void {
+	for (const [operationName, operation] of Object.entries(operations)) {
+		for (const [index, errorCode] of (operation.docs?.errorCodes ?? []).entries()) {
+			if (
+				errorCode.status !== undefined &&
+				!VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)
+			) {
+				const field = `operations.${operationName}.docs.errorCodes[${index}].status`;
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid ${field}: ${String(errorCode.status)} is not an emittable provider error status.`,
+					{
+						fix: `Set ${field} to one of ${VALID_OPERATION_ERROR_STATUSES.join(", ")}, or omit it.`,
+					},
+				);
+			}
+			if (
+				errorCode.status !== undefined &&
+				SDK_RUNTIME_OWNED_ERROR_CODES.has(errorCode.code)
+			) {
+				console.warn(
+					`[provider-sdk] Provider "${providerId}" operation "${operationName}" declares status ${errorCode.status} for SDK-owned error code "${errorCode.code}"; the declared status is documentation-only and will be ignored at runtime.`,
+				);
+			}
+		}
+	}
+}
+
 const JSON_TRANSPORT_FIELDS = new Set(["kind"]);
 const SSE_TRANSPORT_FIELDS = new Set([
 	"kind",
@@ -2185,6 +2217,7 @@ export function defineProvider<
 	validateOperationIds(config.id, config.operations);
 	validateOperationAnnotations(config.id, config.operations);
 	validateOperationObservability(config.id, config.operations);
+	validateOperationErrorCodes(config.id, config.operations);
 	validateOperationTransports(config.id, config.operations);
 	validateOperationContracts(config.id, config.operations);
 	validateToolRouterMetadata(config.id, config.operations);

package/src/error-resolution.ts

@@ -0,0 +1,91 @@
+// This set suppresses the unregistered-provider-error-code signal for codes
+// intentionally emitted by SDK paths. It is not the complete authority for
+// runtime error resolution: branded errors and additional canonical SDK codes
+// must also remain immune to provider-declared status/retryability overrides.
+export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+	"MISSING_SECRET",
+	"AUTH_PROMPT_UNAVAILABLE",
+	"BROWSER_CDP_POOL_REQUIRED",
+	"BROWSER_RUNTIME_UNSUPPORTED",
+	"STEALTH_RUNTIME_UNSUPPORTED",
+	"SSE_EVENT_UNDECLARED",
+	"STREAM_EVENT_TOO_LARGE",
+	"STREAM_CHUNK_TOO_LARGE",
+	"SSE_RESULT_UNSUPPORTED",
+	"STREAM_RESULT_UNSUPPORTED",
+	"AUTH_FLOW_NOT_CONFIGURED",
+	"refresh_not_supported",
+	"RUNTIME_UNSUPPORTED",
+	"PROVIDER_STATE_UNSUPPORTED",
+	"CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+	"CHOICE_STATE_PAYLOAD_TOO_LARGE",
+	"CHOICE_STATE_UNAVAILABLE",
+	"CHOICE_CONTEXT_REQUIRED",
+	"unsupported_stealth_cookie_store_version",
+	"provider_secret_error",
+	"credential_key_error",
+	"credential_mode_error",
+	"flow_expired",
+	"turn_validation_error",
+	"context_access_error",
+	"UNSUPPORTED_STT_OPTION",
+	"INVALID_STT_AUDIO",
+	"STT_AUDIO_TOO_LARGE",
+	"STT_UPSTREAM_FAILED",
+	"INVALID_STT_VERIFICATION_CODE_OPTIONS",
+	"NO_CODE_FOUND",
+	"AMBIGUOUS_CODE",
+	"retry_invalid_policy",
+	"retry_unsafe_method",
+	"stealth_cookie_store_serialize_failed",
+	"response_too_large",
+	"transport_stream_unavailable",
+	"transport_invalid_method",
+	"http_transport_override_unsupported",
+	"http_redirect_policy_invalid",
+	"http_redirect_stopped",
+	"http_redirect_max_hops",
+	"http_redirect_missing_location",
+	"http_redirect_loop",
+	"transport_invalid_url",
+	"retry_exhausted",
+	"auth_abort_unsafe_data",
+	"credentials_auth_missing_credential_keys",
+	"credentials_auth_missing_credential",
+	"credentials_auth_invalid_login_result",
+	"credentials_auth_unknown_challenge",
+	"credentials_auth_unknown_pending_challenge",
+	"STATEFUL_FORWARDING_NOT_CONFIGURED",
+	"STATEFUL_FORWARDING_SIGNATURE_MISSING",
+	"STATEFUL_FORWARDING_NONCE_INVALID",
+	"STATEFUL_FORWARDING_TIMESTAMP_INVALID",
+	"STATEFUL_FORWARDING_SIGNATURE_INVALID",
+	"STATEFUL_FORWARDING_REPLAY_DETECTED",
+	"STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+	"STATEFUL_FORWARDING_ENVELOPE_INVALID",
+	"STATEFUL_FORWARDING_PROVIDER_MISMATCH",
+	"STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+	"STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+	"STATEFUL_FORWARDING_REQUEST_FAILED",
+	"STATEFUL_FORWARDING_CONTEXT_MISSING",
+	"STATEFUL_FORWARDING_BAD_RESPONSE",
+	"STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+	"STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+	"STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+	"STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+	"STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+	"STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+]);
+
+// Complete code authority for provider-declared runtime resolution. Keep this
+// separate from signal suppression: declarations may document these codes, but
+// their status and retryability can never override the SDK's canonical result.
+export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
+	...SDK_OWNED_PROVIDER_ERROR_CODES,
+	"reauth_required",
+	"STT_UNAVAILABLE",
+	"UNSUPPORTED_STT_BACKEND",
+	"OUTPUT_VALIDATION_FAILED",
+	"NOT_FOUND",
+	"not_found",
+]);

package/src/index.ts

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

package/src/native-egress-policy.ts

@@ -5,6 +5,7 @@ import type {
 	NativeTcpPortRange,
 	NativeTcpTlsMode,
 } from "./types.js";
+import { canonicalizeEgressHost, parseIpv4Cidr } from "./native-ipv4.js";
 
 type NativeNetworkDeclaration = NonNullable<NativeProviderConfig["network"]>;
 
@@ -26,6 +27,7 @@ const NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD = {
 	sourcePorts: true,
 	sourcePortRanges: true,
 	targetHostSuffixes: true,
+	targetIpv4Cidrs: true,
 	targetPorts: true,
 	targetPortRanges: true,
 	tls: true,
@@ -55,6 +57,7 @@ export type DynamicEgressRuleSnapshot = {
 	readonly sourcePorts: readonly number[];
 	readonly sourcePortRanges: readonly NativeTcpPortRange[];
 	readonly targetHostSuffixes: readonly string[];
+	readonly targetIpv4Cidrs: readonly string[];
 	readonly targetPorts: readonly number[];
 	readonly targetPortRanges: readonly NativeTcpPortRange[];
 	readonly tls: NativeTcpTlsMode;
@@ -117,28 +120,12 @@ function dataArray(value: unknown, fieldPath: string): readonly unknown[] {
 	return result;
 }
 
-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 host(value: unknown, fieldPath: string, suffix = false): string {
-	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) fail(`${fieldPath} must be a non-empty hostname`);
-	return normalized;
+	const canonical = canonicalizeEgressHost(value);
+	if (!canonical.ok) fail(`${fieldPath} must be a non-empty hostname`);
+	return canonical.host;
 }
 
 function port(value: unknown, fieldPath: string): number {
@@ -157,6 +144,24 @@ function hostSuffixes(value: unknown, fieldPath: string): readonly string[] {
 	);
 }
 
+function ipv4Cidrs(value: unknown, fieldPath: string): readonly string[] {
+	const seen = new Set<string>();
+	return dataArray(value, fieldPath).map((value, index) => {
+		const cidrPath = `${fieldPath}[${index}]`;
+		if (typeof value !== "string") fail(`${cidrPath} must be an IPv4 CIDR in a.b.c.d/nn form`);
+		const parsed = parseIpv4Cidr(value);
+		if (!parsed.ok) {
+			if (parsed.reason === "non-canonical-network")
+				fail(`${cidrPath} must use the canonical network address with no host bits set`);
+			fail(`${cidrPath} must be an IPv4 CIDR in a.b.c.d/nn form`);
+		}
+		const duplicateKey = `${parsed.network}/${parsed.prefix}`;
+		if (seen.has(duplicateKey)) fail(`${fieldPath} must not contain duplicate CIDRs`);
+		seen.add(duplicateKey);
+		return value;
+	});
+}
+
 function ranges(value: unknown, fieldPath: string): readonly NativeTcpPortRange[] {
 	return dataArray(value, fieldPath).map((value, index) => {
 		const rangePath = `${fieldPath}[${index}]`;
@@ -212,9 +217,7 @@ export function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnaps
 								? []
 								: hostSuffixes(rule.sourceHostSuffixes, `${fieldPath}.sourceHostSuffixes`);
 						if (sourceHost === undefined && sourceHostSuffixes.length === 0)
-							fail(
-								`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes list`,
-							);
+							fail(`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes list`);
 						const sourcePorts =
 							rule.sourcePorts === undefined
 								? []
@@ -224,15 +227,19 @@ export function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnaps
 								? []
 								: 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 =
+							rule.targetHostSuffixes === undefined
+								? []
+								: hostSuffixes(rule.targetHostSuffixes, `${fieldPath}.targetHostSuffixes`);
+						const targetIpv4Cidrs =
+							rule.targetIpv4Cidrs === undefined
+								? []
+								: ipv4Cidrs(rule.targetIpv4Cidrs, `${fieldPath}.targetIpv4Cidrs`);
+						if (targetHostSuffixes.length === 0 && targetIpv4Cidrs.length === 0)
 							fail(
-								`${fieldPath} must declare a non-empty sourcePorts or sourcePortRanges list`,
+								`${fieldPath} must declare a non-empty targetHostSuffixes or targetIpv4Cidrs list`,
 							);
-						const targetHostSuffixes = hostSuffixes(
-							rule.targetHostSuffixes,
-							`${fieldPath}.targetHostSuffixes`,
-						);
-						if (targetHostSuffixes.length === 0)
-							fail(`${fieldPath}.targetHostSuffixes must not be empty`);
 						const targetPorts =
 							rule.targetPorts === undefined
 								? []
@@ -242,15 +249,14 @@ export function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnaps
 								? []
 								: ranges(rule.targetPortRanges, `${fieldPath}.targetPortRanges`);
 						if (targetPorts.length === 0 && targetPortRanges.length === 0)
-							fail(
-								`${fieldPath} must declare a non-empty targetPorts or targetPortRanges list`,
-							);
+							fail(`${fieldPath} must declare a non-empty targetPorts or targetPortRanges list`);
 						return {
 							...(sourceHost === undefined ? {} : { sourceHost }),
 							sourceHostSuffixes,
 							sourcePorts,
 							sourcePortRanges,
 							targetHostSuffixes,
+							targetIpv4Cidrs,
 							targetPorts,
 							targetPortRanges,
 							tls: tls(rule.tls, `${fieldPath}.tls`),