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

package/src/native-address.ts

@@ -0,0 +1,340 @@
+import { domainToASCII } from "node:url";
+
+const STRICT_IPV4_PATTERN =
+	/^(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})$/;
+const DECIMAL_COMPONENT_PATTERN = /^\d+$/;
+const HEX_COMPONENT_PATTERN = /^0[xX][\da-fA-F]+$/;
+const IPV6_GROUP_PATTERN = /^[\da-fA-F]{1,4}$/;
+const FORMAT_CONTROL_PATTERN = /\p{Cf}/u;
+const RESERVED_EGRESS_HOST_DELIMITERS = ["/", "\\", "?", "#", "@", "[", "]", " ", "%"];
+
+const IPV4_MAPPED_PREFIX = Uint8Array.of(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff);
+const IPV4_COMPATIBLE_MIN = Uint8Array.of(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2);
+const IPV4_COMPATIBLE_MAX = Uint8Array.of(
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0,
+	0xff,
+	0xff,
+	0xff,
+	0xff,
+);
+
+export type EgressHostKind = "ipv4" | "ipv6" | "ipv4-mapped-ipv6" | "numeric-ambiguous" | "dns";
+
+export type EgressHostCanonicalizationFailure =
+	| "not-string"
+	| "reserved-delimiter"
+	| "control-character"
+	| "whitespace"
+	| "canonicalization-empty";
+
+export type EgressHostCanonicalizationResult =
+	| { readonly ok: true; readonly host: string }
+	| { readonly ok: false; readonly reason: EgressHostCanonicalizationFailure };
+
+export type Ipv6CidrOverlap = "ipv4-mapped" | "ipv4-compatible";
+
+export type Ipv6CidrParseResult =
+	| { readonly ok: true; readonly network: Uint8Array; readonly prefix: number }
+	| {
+			readonly ok: false;
+			readonly reason: "malformed";
+			readonly overlap?: Ipv6CidrOverlap;
+	  }
+	| { readonly ok: false; readonly reason: "non-canonical-network" };
+
+export function parseStrictIpv4(value: string): number | undefined {
+	const match = STRICT_IPV4_PATTERN.exec(value);
+	if (!match || match[0] !== value) return undefined;
+	const [, first, second, third, fourth] = match;
+	if (first === undefined || second === undefined || third === undefined || fourth === undefined)
+		return undefined;
+	const octets = [Number(first), Number(second), Number(third), Number(fourth)];
+	if (octets.some((octet) => octet > 255)) return undefined;
+	const [a, b, c, d] = octets;
+	if (a === undefined || b === undefined || c === undefined || d === undefined) return undefined;
+	return (a * 0x1000000 + b * 0x10000 + c * 0x100 + d) >>> 0;
+}
+
+function ipv4HexGroups(value: string): readonly [string, string] | undefined {
+	const address = parseStrictIpv4(value);
+	if (address === undefined) return undefined;
+	return [((address >>> 16) & 0xffff).toString(16), (address & 0xffff).toString(16)];
+}
+
+/** Parse the RFC 4291 IPv6 text forms accepted at both policy and runtime boundaries. */
+export function parseIpv6(value: string): Uint8Array | undefined {
+	if (!value || value.includes("%") || value.includes("[") || value.includes("]")) return undefined;
+	if (value.indexOf("::") !== value.lastIndexOf("::")) return undefined;
+
+	let text = value;
+	if (text.includes(".")) {
+		const finalColon = text.lastIndexOf(":");
+		if (finalColon < 0) return undefined;
+		const groups = ipv4HexGroups(text.slice(finalColon + 1));
+		if (!groups) return undefined;
+		text = `${text.slice(0, finalColon + 1)}${groups[0]}:${groups[1]}`;
+	}
+
+	const compression = text.indexOf("::");
+	let groups: string[];
+	if (compression >= 0) {
+		const leftText = text.slice(0, compression);
+		const rightText = text.slice(compression + 2);
+		const left = leftText ? leftText.split(":") : [];
+		const right = rightText ? rightText.split(":") : [];
+		if (
+			left.some((group) => !IPV6_GROUP_PATTERN.test(group)) ||
+			right.some((group) => !IPV6_GROUP_PATTERN.test(group)) ||
+			left.length + right.length >= 8
+		)
+			return undefined;
+		groups = [...left, ...Array<string>(8 - left.length - right.length).fill("0"), ...right];
+	} else {
+		groups = text.split(":");
+		if (groups.length !== 8 || groups.some((group) => !IPV6_GROUP_PATTERN.test(group)))
+			return undefined;
+	}
+
+	const bytes = new Uint8Array(16);
+	for (let index = 0; index < groups.length; index += 1) {
+		const group = groups[index];
+		if (group === undefined) return undefined;
+		const parsed = Number.parseInt(group, 16);
+		bytes[index * 2] = parsed >>> 8;
+		bytes[index * 2 + 1] = parsed & 0xff;
+	}
+	return bytes;
+}
+
+function prefixMatches(address: Uint8Array, network: Uint8Array, prefix: number): boolean {
+	const wholeBytes = Math.floor(prefix / 8);
+	for (let index = 0; index < wholeBytes; index += 1) {
+		if (address[index] !== network[index]) return false;
+	}
+	const remainingBits = prefix % 8;
+	if (remainingBits === 0) return true;
+	const mask = (0xff << (8 - remainingBits)) & 0xff;
+	return ((address[wholeBytes] ?? 0) & mask) === ((network[wholeBytes] ?? 0) & mask);
+}
+
+function compareIpv6(left: Uint8Array, right: Uint8Array): number {
+	for (let index = 0; index < 16; index += 1) {
+		const difference = (left[index] ?? 0) - (right[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+
+function cidrMaximum(network: Uint8Array, prefix: number): Uint8Array {
+	const maximum = network.slice();
+	for (let bit = prefix; bit < 128; bit += 1) {
+		const byteIndex = Math.floor(bit / 8);
+		maximum[byteIndex] = (maximum[byteIndex] ?? 0) | (1 << (7 - (bit % 8)));
+	}
+	return maximum;
+}
+
+function rangesOverlap(
+	leftMin: Uint8Array,
+	leftMax: Uint8Array,
+	rightMin: Uint8Array,
+	rightMax: Uint8Array,
+): boolean {
+	return compareIpv6(leftMin, rightMax) <= 0 && compareIpv6(rightMin, leftMax) <= 0;
+}
+
+function ipv6CidrOverlap(network: Uint8Array, prefix: number): Ipv6CidrOverlap | undefined {
+	const maximum = cidrMaximum(network, prefix);
+	const mappedMin = new Uint8Array(16);
+	mappedMin.set(IPV4_MAPPED_PREFIX);
+	const mappedMax = mappedMin.slice();
+	mappedMax.fill(0xff, 12);
+	if (rangesOverlap(network, maximum, mappedMin, mappedMax)) return "ipv4-mapped";
+	if (rangesOverlap(network, maximum, IPV4_COMPATIBLE_MIN, IPV4_COMPATIBLE_MAX))
+		return "ipv4-compatible";
+	return undefined;
+}
+
+export function parseIpv4Cidr(
+	value: string,
+):
+	| { readonly ok: true; readonly network: number; readonly prefix: number }
+	| { readonly ok: false; readonly reason: "malformed" | "non-canonical-network" } {
+	const separator = value.indexOf("/");
+	if (separator <= 0 || separator !== value.lastIndexOf("/"))
+		return { ok: false, reason: "malformed" };
+	const address = parseStrictIpv4(value.slice(0, separator));
+	const prefixText = value.slice(separator + 1);
+	const prefix = Number(prefixText);
+	if (
+		address === undefined ||
+		!Number.isInteger(prefix) ||
+		prefix < 0 ||
+		prefix > 32 ||
+		String(prefix) !== prefixText
+	)
+		return { ok: false, reason: "malformed" };
+	const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+	const network = (address & mask) >>> 0;
+	if (address !== network) return { ok: false, reason: "non-canonical-network" };
+	return { ok: true, network, prefix };
+}
+
+export function parseIpv6Cidr(value: string): Ipv6CidrParseResult {
+	const separator = value.indexOf("/");
+	if (separator <= 0 || separator !== value.lastIndexOf("/"))
+		return { ok: false, reason: "malformed" };
+	const address = parseIpv6(value.slice(0, separator));
+	const prefixText = value.slice(separator + 1);
+	const prefix = Number(prefixText);
+	if (
+		address === undefined ||
+		!Number.isInteger(prefix) ||
+		prefix < 0 ||
+		prefix > 128 ||
+		String(prefix) !== prefixText
+	)
+		return { ok: false, reason: "malformed" };
+	const network = address.slice();
+	const wholeBytes = Math.floor(prefix / 8);
+	const remainingBits = prefix % 8;
+	if (remainingBits > 0) {
+		const mask = (0xff << (8 - remainingBits)) & 0xff;
+		network[wholeBytes] = (network[wholeBytes] ?? 0) & mask;
+	}
+	network.fill(0, wholeBytes + (remainingBits > 0 ? 1 : 0));
+	if (compareIpv6(address, network) !== 0) return { ok: false, reason: "non-canonical-network" };
+	const overlap = ipv6CidrOverlap(network, prefix);
+	if (overlap) return { ok: false, reason: "malformed", overlap };
+	return { ok: true, network, prefix };
+}
+
+export function ipv4InCidr(address: number, cidr: string): boolean {
+	const parsed = parseIpv4Cidr(cidr);
+	if (!parsed.ok) return false;
+	return (
+		parsed.prefix === 0 ||
+		address >>> (32 - parsed.prefix) === parsed.network >>> (32 - parsed.prefix)
+	);
+}
+
+export function ipv6InCidr(address: Uint8Array, cidr: string): boolean {
+	if (address.length !== 16) return false;
+	const parsed = parseIpv6Cidr(cidr);
+	return parsed.ok && prefixMatches(address, parsed.network, parsed.prefix);
+}
+
+export function embeddedIpv4FromIpv6(address: Uint8Array): number | undefined {
+	if (address.length !== 16) return undefined;
+	const mapped = IPV4_MAPPED_PREFIX.every((byte, index) => address[index] === byte);
+	const compatible = address.slice(0, 12).every((byte) => byte === 0);
+	const embedded =
+		((address[12] ?? 0) * 0x1000000 +
+			(address[13] ?? 0) * 0x10000 +
+			(address[14] ?? 0) * 0x100 +
+			(address[15] ?? 0)) >>>
+		0;
+	if (mapped || (compatible && embedded !== 0 && embedded !== 1)) return embedded;
+	return undefined;
+}
+
+export function formatIpv6(address: Uint8Array): string {
+	if (address.length !== 16) throw new TypeError("IPv6 addresses must contain exactly 16 bytes");
+	const groups = Array.from({ length: 8 }, (_, index) =>
+		(((address[index * 2] ?? 0) << 8) | (address[index * 2 + 1] ?? 0)).toString(16),
+	);
+	let bestStart = -1;
+	let bestLength = 0;
+	for (let index = 0; index < groups.length; ) {
+		if (groups[index] !== "0") {
+			index += 1;
+			continue;
+		}
+		let end = index + 1;
+		while (end < groups.length && groups[end] === "0") end += 1;
+		if (end - index > bestLength && end - index >= 2) {
+			bestStart = index;
+			bestLength = end - index;
+		}
+		index = end;
+	}
+	if (bestStart < 0) return groups.join(":");
+	const left = groups.slice(0, bestStart).join(":");
+	const right = groups.slice(bestStart + bestLength).join(":");
+	return `${left}::${right}`;
+}
+
+/** The single family and ambiguity classifier used by policy and runtime matching. */
+export function classifyEgressHost(host: string): EgressHostKind {
+	if (
+		hasReservedEgressHostDelimiter(host) ||
+		hasEgressHostControlCharacter(host) ||
+		/\s/u.test(host)
+	)
+		return "numeric-ambiguous";
+	if (parseStrictIpv4(host) !== undefined) return "ipv4";
+	const ipv6 = parseIpv6(host);
+	if (ipv6) return embeddedIpv4FromIpv6(ipv6) === undefined ? "ipv6" : "ipv4-mapped-ipv6";
+	if (host.includes(":")) return "numeric-ambiguous";
+	const labels = host.split(".");
+	if (
+		labels.every(
+			(label) =>
+				DECIMAL_COMPONENT_PATTERN.exec(label)?.[0] === label ||
+				HEX_COMPONENT_PATTERN.exec(label)?.[0] === label,
+		)
+	)
+		return "numeric-ambiguous";
+	return "dns";
+}
+
+export function hasReservedEgressHostDelimiter(value: string): boolean {
+	return RESERVED_EGRESS_HOST_DELIMITERS.some((delimiter) => value.includes(delimiter));
+}
+
+export function hasEgressHostControlCharacter(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 FORMAT_CONTROL_PATTERN.test(value);
+}
+
+export function canonicalizeEgressHost(value: unknown): EgressHostCanonicalizationResult {
+	if (typeof value !== "string") return { ok: false, reason: "not-string" };
+	if (hasReservedEgressHostDelimiter(value)) return { ok: false, reason: "reserved-delimiter" };
+	if (hasEgressHostControlCharacter(value)) return { ok: false, reason: "control-character" };
+	if (/\s/u.test(value)) return { ok: false, reason: "whitespace" };
+	const raw = value.trim();
+	if (!raw) return { ok: false, reason: "canonicalization-empty" };
+
+	const ipv6 = parseIpv6(raw);
+	if (ipv6) return { ok: true, host: formatIpv6(ipv6) };
+
+	// Classify the spelling with one optional root-label dot removed before IDNA.
+	// This keeps resolver-numeric ASCII forms from being widened into canonical IPv4.
+	const numericCandidate = raw.endsWith(".") ? raw.slice(0, -1) : raw;
+	const normalizedNumericCandidate = numericCandidate.toLowerCase();
+	if (classifyEgressHost(normalizedNumericCandidate) === "numeric-ambiguous")
+		return { ok: true, host: normalizedNumericCandidate };
+
+	let ascii: string;
+	try {
+		ascii = domainToASCII(raw).toLowerCase().replace(/\.$/, "");
+	} catch {
+		return { ok: false, reason: "canonicalization-empty" };
+	}
+	if (!ascii || /^\.+$/.test(ascii)) return { ok: false, reason: "canonicalization-empty" };
+	return { ok: true, host: ascii };
+}

package/src/native-egress-policy.ts

@@ -5,7 +5,13 @@ import type {
 	NativeTcpPortRange,
 	NativeTcpTlsMode,
 } from "./types.js";
-import { canonicalizeEgressHost, parseIpv4Cidr } from "./native-ipv4.js";
+import {
+	canonicalizeEgressHost,
+	classifyEgressHost,
+	formatIpv6,
+	parseIpv4Cidr,
+	parseIpv6Cidr,
+} from "./native-address.js";
 
 type NativeNetworkDeclaration = NonNullable<NativeProviderConfig["network"]>;
 
@@ -24,10 +30,13 @@ const NATIVE_TCP_RULE_FIELD_RECORD = {
 const NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD = {
 	sourceHost: true,
 	sourceHostSuffixes: true,
+	sourceIpv4Cidrs: true,
+	sourceIpv6Cidrs: true,
 	sourcePorts: true,
 	sourcePortRanges: true,
 	targetHostSuffixes: true,
 	targetIpv4Cidrs: true,
+	targetIpv6Cidrs: true,
 	targetPorts: true,
 	targetPortRanges: true,
 	tls: true,
@@ -54,10 +63,13 @@ export type StaticEgressRuleSnapshot = {
 export type DynamicEgressRuleSnapshot = {
 	readonly sourceHost?: string;
 	readonly sourceHostSuffixes: readonly string[];
+	readonly sourceIpv4Cidrs: readonly string[];
+	readonly sourceIpv6Cidrs: readonly string[];
 	readonly sourcePorts: readonly number[];
 	readonly sourcePortRanges: readonly NativeTcpPortRange[];
 	readonly targetHostSuffixes: readonly string[];
 	readonly targetIpv4Cidrs: readonly string[];
+	readonly targetIpv6Cidrs: readonly string[];
 	readonly targetPorts: readonly number[];
 	readonly targetPortRanges: readonly NativeTcpPortRange[];
 	readonly tls: NativeTcpTlsMode;
@@ -125,6 +137,13 @@ function host(value: unknown, fieldPath: string, suffix = false): string {
 		fail(`${fieldPath} must be an exact ${suffix ? "DNS suffix" : "hostname"}, not a wildcard`);
 	const canonical = canonicalizeEgressHost(value);
 	if (!canonical.ok) fail(`${fieldPath} must be a non-empty hostname`);
+	const kind = classifyEgressHost(canonical.host);
+	if (kind === "numeric-ambiguous")
+		fail(`${fieldPath} value is an unresolvable numeric-ambiguous spelling`);
+	if (suffix && kind !== "dns") {
+		const family = kind === "ipv4" ? "IPv4" : "IPv6";
+		fail(`${fieldPath} must be a DNS suffix, not an ${family} literal`);
+	}
 	return canonical.host;
 }
 
@@ -162,6 +181,28 @@ function ipv4Cidrs(value: unknown, fieldPath: string): readonly string[] {
 	});
 }
 
+function ipv6Cidrs(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 IPv6 CIDR in address/nn form`);
+		const parsed = parseIpv6Cidr(value);
+		if (!parsed.ok) {
+			if (parsed.reason === "non-canonical-network")
+				fail(`${cidrPath} must use the canonical network address with no host bits set`);
+			if (parsed.overlap === "ipv4-mapped")
+				fail(`${cidrPath} overlaps IPv4-mapped ::ffff:0:0/96 address space`);
+			if (parsed.overlap === "ipv4-compatible")
+				fail(`${cidrPath} overlaps IPv4-compatible ::/96 address space`);
+			fail(`${cidrPath} must be an IPv6 CIDR in address/nn form`);
+		}
+		const duplicateKey = `${formatIpv6(parsed.network)}/${parsed.prefix}`;
+		if (seen.has(duplicateKey)) fail(`${fieldPath} must not contain duplicate CIDRs`);
+		seen.add(duplicateKey);
+		return value;
+	});
+}
+
 function ranges(value: unknown, fieldPath: string): readonly NativeTcpPortRange[] {
 	return dataArray(value, fieldPath).map((value, index) => {
 		const rangePath = `${fieldPath}[${index}]`;
@@ -216,8 +257,23 @@ export function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnaps
 							rule.sourceHostSuffixes === undefined
 								? []
 								: hostSuffixes(rule.sourceHostSuffixes, `${fieldPath}.sourceHostSuffixes`);
-						if (sourceHost === undefined && sourceHostSuffixes.length === 0)
-							fail(`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes list`);
+						const sourceIpv4Cidrs =
+							rule.sourceIpv4Cidrs === undefined
+								? []
+								: ipv4Cidrs(rule.sourceIpv4Cidrs, `${fieldPath}.sourceIpv4Cidrs`);
+						const sourceIpv6Cidrs =
+							rule.sourceIpv6Cidrs === undefined
+								? []
+								: ipv6Cidrs(rule.sourceIpv6Cidrs, `${fieldPath}.sourceIpv6Cidrs`);
+						if (
+							sourceHost === undefined &&
+							sourceHostSuffixes.length === 0 &&
+							sourceIpv4Cidrs.length === 0 &&
+							sourceIpv6Cidrs.length === 0
+						)
+							fail(
+								`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes, sourceIpv4Cidrs, or sourceIpv6Cidrs list`,
+							);
 						const sourcePorts =
 							rule.sourcePorts === undefined
 								? []
@@ -236,9 +292,17 @@ export function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnaps
 							rule.targetIpv4Cidrs === undefined
 								? []
 								: ipv4Cidrs(rule.targetIpv4Cidrs, `${fieldPath}.targetIpv4Cidrs`);
-						if (targetHostSuffixes.length === 0 && targetIpv4Cidrs.length === 0)
+						const targetIpv6Cidrs =
+							rule.targetIpv6Cidrs === undefined
+								? []
+								: ipv6Cidrs(rule.targetIpv6Cidrs, `${fieldPath}.targetIpv6Cidrs`);
+						if (
+							targetHostSuffixes.length === 0 &&
+							targetIpv4Cidrs.length === 0 &&
+							targetIpv6Cidrs.length === 0
+						)
 							fail(
-								`${fieldPath} must declare a non-empty targetHostSuffixes or targetIpv4Cidrs list`,
+								`${fieldPath} must declare a non-empty targetHostSuffixes, targetIpv4Cidrs, or targetIpv6Cidrs list`,
 							);
 						const targetPorts =
 							rule.targetPorts === undefined
@@ -253,10 +317,13 @@ export function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnaps
 						return {
 							...(sourceHost === undefined ? {} : { sourceHost }),
 							sourceHostSuffixes,
+							sourceIpv4Cidrs,
+							sourceIpv6Cidrs,
 							sourcePorts,
 							sourcePortRanges,
 							targetHostSuffixes,
 							targetIpv4Cidrs,
+							targetIpv6Cidrs,
 							targetPorts,
 							targetPortRanges,
 							tls: tls(rule.tls, `${fieldPath}.tls`),

package/src/runtime/native-network.ts

@@ -21,11 +21,14 @@ import {
 } from "../native-egress-policy.js";
 import {
 	canonicalizeEgressHost,
-	classifyEgressTargetHost,
+	classifyEgressHost,
 	type EgressHostCanonicalizationFailure,
+	embeddedIpv4FromIpv6,
 	ipv4InCidr,
+	ipv6InCidr,
+	parseIpv6,
 	parseStrictIpv4,
-} from "../native-ipv4.js";
+} from "../native-address.js";
 import type {
 	NativeNetworkClient,
 	NativeNetworkConnectInput,
@@ -1209,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[],
@@ -1253,16 +1289,11 @@ function matchesDynamicRuleSelectors(
 }
 
 function matchesDynamicTargetHost(rule: DynamicEgressRuleSnapshot, targetHost: string): boolean {
-	const targetKind = classifyEgressTargetHost(targetHost);
-	if (targetKind === "ipv4") {
-		const targetIp = parseStrictIpv4(targetHost);
-		return (
-			targetIp !== undefined && rule.targetIpv4Cidrs.some((cidr) => ipv4InCidr(targetIp, cidr))
-		);
-	}
-	return (
-		targetKind === "dns" &&
-		rule.targetHostSuffixes.some((suffix) => matchesDnsSuffix(targetHost, suffix))
+	return matchesHostFamilySelectors(
+		targetHost,
+		rule.targetHostSuffixes,
+		rule.targetIpv4Cidrs,
+		rule.targetIpv6Cidrs,
 	);
 }
 
@@ -1487,7 +1518,7 @@ export function createNativeEgressAuthorization(options: NativeNetworkClientOpti
 					? [index]
 					: [],
 			);
-			const targetKind = classifyEgressTargetHost(diagnosticTargetHost);
+			const targetKind = classifyEgressHost(diagnosticTargetHost);
 			let selectorDetails: string;
 			if (sourceMatchingRuleIndices.length > 0) {
 				const failedByRule: string[] = [];

package/src/types.ts

@@ -1319,9 +1319,10 @@ export interface NativeTcpEgressRule {
  * Bounded native TCP egress discovered through a declared bootstrap endpoint.
  * Host suffixes are exact DNS suffixes, not wildcard patterns.
  * Dynamic rules must declare at least one target host selector through
- * targetHostSuffixes and/or targetIpv4Cidrs. IPv4-literal grant targets match
- * only targetIpv4Cidrs, while DNS-name targets match only targetHostSuffixes.
- * CIDRs are exact IPv4 networks in a.b.c.d/nn form.
+ * targetHostSuffixes, targetIpv4Cidrs, and/or targetIpv6Cidrs. Literal grant
+ * sources and targets match only same-family selectors (except exact
+ * sourceHost); DNS names match only host/suffix selectors. IPv4-mapped and
+ * IPv4-compatible IPv6 literals are authorized only by IPv4 CIDRs.
  *
  * Dynamic rules are ordered. The first rule whose source, target, port, and TLS
  * selectors match exclusively owns the grant; its ttlMs and maxGrants bounds
@@ -1332,10 +1333,13 @@ export interface NativeTcpEgressRule {
 export interface NativeTcpDynamicEgressRule {
 	readonly sourceHost?: string;
 	readonly sourceHostSuffixes?: readonly string[];
+	readonly sourceIpv4Cidrs?: readonly string[];
+	readonly sourceIpv6Cidrs?: readonly string[];
 	readonly sourcePorts?: readonly number[];
 	readonly sourcePortRanges?: readonly NativeTcpPortRange[];
 	readonly targetHostSuffixes?: readonly string[];
 	readonly targetIpv4Cidrs?: readonly string[];
+	readonly targetIpv6Cidrs?: readonly string[];
 	readonly targetPorts?: readonly number[];
 	readonly targetPortRanges?: readonly NativeTcpPortRange[];
 	readonly tls: NativeTcpTlsMode;

package/dist/native-ipv4.d.ts

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