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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.18
+
+- Release candidate for main commit cebaf4b994918d2641c0fe6681fbffd3a3284c5d.
+
 ## 2.2.0-beta.17
 
 - Release candidate for main commit 5a0f9127a5861992d5c144b07ad379a085756544.

package/dist/native-address.d.ts

@@ -0,0 +1,43 @@
+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 declare function parseStrictIpv4(value: string): number | undefined;
+/** Parse the RFC 4291 IPv6 text forms accepted at both policy and runtime boundaries. */
+export declare function parseIpv6(value: string): Uint8Array | undefined;
+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 parseIpv6Cidr(value: string): Ipv6CidrParseResult;
+export declare function ipv4InCidr(address: number, cidr: string): boolean;
+export declare function ipv6InCidr(address: Uint8Array, cidr: string): boolean;
+export declare function embeddedIpv4FromIpv6(address: Uint8Array): number | undefined;
+export declare function formatIpv6(address: Uint8Array): string;
+/** The single family and ambiguity classifier used by policy and runtime matching. */
+export declare function classifyEgressHost(host: string): EgressHostKind;
+export declare function hasReservedEgressHostDelimiter(value: string): boolean;
+export declare function hasEgressHostControlCharacter(value: string): boolean;
+export declare function canonicalizeEgressHost(value: unknown): EgressHostCanonicalizationResult;

package/dist/native-address.js

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

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

@@ -7,10 +7,13 @@ export type StaticEgressRuleSnapshot = {
 export type DynamicEgressRuleSnapshot = {
     readonly sourceHost?: string;
     readonly sourceHostSuffixes: readonly string[];
+    readonly sourceIpv4Cidrs: readonly string[];
+    readonly sourceIpv6Cidrs: readonly string[];
     readonly sourcePorts: readonly number[];
     readonly sourcePortRanges: readonly NativeTcpPortRange[];
     readonly targetHostSuffixes: readonly string[];
     readonly targetIpv4Cidrs: readonly string[];
+    readonly targetIpv6Cidrs: readonly string[];
     readonly targetPorts: readonly number[];
     readonly targetPortRanges: readonly NativeTcpPortRange[];
     readonly tls: NativeTcpTlsMode;

package/dist/native-egress-policy.js

@@ -1,4 +1,4 @@
-import { canonicalizeEgressHost, parseIpv4Cidr } from "./native-ipv4.js";
+import { canonicalizeEgressHost, classifyEgressHost, formatIpv6, parseIpv4Cidr, parseIpv6Cidr, } from "./native-address.js";
 const NATIVE_PROVIDER_FIELD_RECORD = {
     network: true,
 };
@@ -14,10 +14,13 @@ const NATIVE_TCP_RULE_FIELD_RECORD = {
 const NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD = {
     sourceHost: true,
     sourceHostSuffixes: true,
+    sourceIpv4Cidrs: true,
+    sourceIpv6Cidrs: true,
     sourcePorts: true,
     sourcePortRanges: true,
     targetHostSuffixes: true,
     targetIpv4Cidrs: true,
+    targetIpv6Cidrs: true,
     targetPorts: true,
     targetPortRanges: true,
     tls: true,
@@ -89,6 +92,13 @@ function host(value, fieldPath, suffix = false) {
     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;
 }
 function port(value, fieldPath) {
@@ -121,6 +131,29 @@ function ipv4Cidrs(value, fieldPath) {
         return value;
     });
 }
+function ipv6Cidrs(value, fieldPath) {
+    const seen = new Set();
+    return dataArray(value, fieldPath).map((value, index) => {
+        const cidrPath = `${fieldPath}[${index}]`;
+        if (typeof value !== "string")
+            fail(`${cidrPath} must be an IPv6 CIDR in address/nn form`);
+        const parsed = parseIpv6Cidr(value);
+        if (!parsed.ok) {
+            if (parsed.reason === "non-canonical-network")
+                fail(`${cidrPath} must use the canonical network address with no host bits set`);
+            if (parsed.overlap === "ipv4-mapped")
+                fail(`${cidrPath} overlaps IPv4-mapped ::ffff:0:0/96 address space`);
+            if (parsed.overlap === "ipv4-compatible")
+                fail(`${cidrPath} overlaps IPv4-compatible ::/96 address space`);
+            fail(`${cidrPath} must be an IPv6 CIDR in address/nn form`);
+        }
+        const duplicateKey = `${formatIpv6(parsed.network)}/${parsed.prefix}`;
+        if (seen.has(duplicateKey))
+            fail(`${fieldPath} must not contain duplicate CIDRs`);
+        seen.add(duplicateKey);
+        return value;
+    });
+}
 function ranges(value, fieldPath) {
     return dataArray(value, fieldPath).map((value, index) => {
         const rangePath = `${fieldPath}[${index}]`;
@@ -170,8 +203,17 @@ export function parseNativeEgressPolicy(value) {
                 const sourceHostSuffixes = rule.sourceHostSuffixes === undefined
                     ? []
                     : hostSuffixes(rule.sourceHostSuffixes, `${fieldPath}.sourceHostSuffixes`);
-                if (sourceHost === undefined && sourceHostSuffixes.length === 0)
-                    fail(`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes list`);
+                const sourceIpv4Cidrs = rule.sourceIpv4Cidrs === undefined
+                    ? []
+                    : ipv4Cidrs(rule.sourceIpv4Cidrs, `${fieldPath}.sourceIpv4Cidrs`);
+                const sourceIpv6Cidrs = rule.sourceIpv6Cidrs === undefined
+                    ? []
+                    : ipv6Cidrs(rule.sourceIpv6Cidrs, `${fieldPath}.sourceIpv6Cidrs`);
+                if (sourceHost === undefined &&
+                    sourceHostSuffixes.length === 0 &&
+                    sourceIpv4Cidrs.length === 0 &&
+                    sourceIpv6Cidrs.length === 0)
+                    fail(`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes, sourceIpv4Cidrs, or sourceIpv6Cidrs list`);
                 const sourcePorts = rule.sourcePorts === undefined
                     ? []
                     : ports(rule.sourcePorts, `${fieldPath}.sourcePorts`);
@@ -186,8 +228,13 @@ export function parseNativeEgressPolicy(value) {
                 const targetIpv4Cidrs = rule.targetIpv4Cidrs === undefined
                     ? []
                     : ipv4Cidrs(rule.targetIpv4Cidrs, `${fieldPath}.targetIpv4Cidrs`);
-                if (targetHostSuffixes.length === 0 && targetIpv4Cidrs.length === 0)
-                    fail(`${fieldPath} must declare a non-empty targetHostSuffixes or targetIpv4Cidrs list`);
+                const targetIpv6Cidrs = rule.targetIpv6Cidrs === undefined
+                    ? []
+                    : ipv6Cidrs(rule.targetIpv6Cidrs, `${fieldPath}.targetIpv6Cidrs`);
+                if (targetHostSuffixes.length === 0 &&
+                    targetIpv4Cidrs.length === 0 &&
+                    targetIpv6Cidrs.length === 0)
+                    fail(`${fieldPath} must declare a non-empty targetHostSuffixes, targetIpv4Cidrs, or targetIpv6Cidrs list`);
                 const targetPorts = rule.targetPorts === undefined
                     ? []
                     : ports(rule.targetPorts, `${fieldPath}.targetPorts`);
@@ -199,10 +246,13 @@ export function parseNativeEgressPolicy(value) {
                 return {
                     ...(sourceHost === undefined ? {} : { sourceHost }),
                     sourceHostSuffixes,
+                    sourceIpv4Cidrs,
+                    sourceIpv6Cidrs,
                     sourcePorts,
                     sourcePortRanges,
                     targetHostSuffixes,
                     targetIpv4Cidrs,
+                    targetIpv6Cidrs,
                     targetPorts,
                     targetPortRanges,
                     tls: tls(rule.tls, `${fieldPath}.tls`),

package/dist/runtime/native-network.d.ts

@@ -2,6 +2,7 @@ import { Socket } from "node:net";
 import { type TLSSocket } from "node:tls";
 import { type ProxyProtocol } from "../config/loader.js";
 import { TransportError } from "../errors.js";
+import { type DynamicEgressRuleSnapshot } from "../native-egress-policy.js";
 import type { NativeNetworkClient, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider, EnvContext } from "../types.js";
 export type NativeNetworkErrorCode = "native_connection_aborted" | "native_connection_closed" | "native_connection_failed" | "native_connection_idle_timeout" | "native_connection_timeout" | "native_egress_authorization_failed" | "native_egress_grant_expired" | "native_egress_grant_invalid" | "native_egress_grant_limit_exceeded" | "native_egress_input_invalid" | "native_egress_not_declared" | "native_egress_policy_invalid" | "native_dynamic_egress_unsupported" | "native_proxy_expired" | "native_proxy_invalid";
 export declare class NativeNetworkError extends TransportError {
@@ -110,6 +111,8 @@ export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResol
 export declare function createNativeNetworkConnection(socket: Socket | TLSSocket, proxy: NativeGatewayProxy | undefined, options: NativeNetworkClientOptions, idleTimeoutMs?: number): NativeNetworkConnection;
 type NativeConnectTls = "required" | "disabled";
 export declare const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;
+/** Internal validator-independent source selector matcher. */
+export declare function matchesSourceHost(rule: DynamicEgressRuleSnapshot, host: string): boolean;
 /** Internal canonical snapshot shared by production and SDK transport test doubles. */
 export declare function snapshotNativeConnectInput(input: NativeNetworkConnectInput): NativeNetworkConnectInput;
 /** Internal canonical snapshot shared by production and SDK transport test doubles. */

package/dist/runtime/native-network.js

@@ -5,7 +5,7 @@ import { SocksClient } from "socks";
 import { assertTunnelingScheme, ProxyResolutionError, SMARTPROXY_APP_KEY_ENV, VENDOR_DEFAULT_PROTOCOL, resolveWithVendor, } from "../config/loader.js";
 import { TransportError } from "../errors.js";
 import { NativeEgressPolicyValidationError, parseNativeEgressPolicy, } from "../native-egress-policy.js";
-import { canonicalizeEgressHost, classifyEgressTargetHost, ipv4InCidr, parseStrictIpv4, } from "../native-ipv4.js";
+import { canonicalizeEgressHost, classifyEgressHost, embeddedIpv4FromIpv6, ipv4InCidr, ipv6InCidr, parseIpv6, parseStrictIpv4, } from "../native-address.js";
 import { createEnvContext } from "./env.js";
 import { NODEMAVEN_FILTER_ENV, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, nodemavenSessionWindow, synthesizeNodemavenProxy, } from "./proxy-nodemaven.js";
 import { redactSensitiveError } from "./request-options.js";
@@ -916,12 +916,37 @@ function invalidPolicy(message) {
 function matchesDnsSuffix(host, suffix) {
     return host === suffix || host.endsWith(`.${suffix}`);
 }
-function matchesSourceHost(rule, host) {
-    const hasSelector = rule.sourceHost !== undefined || rule.sourceHostSuffixes.length > 0;
+/** Internal validator-independent source selector matcher. */
+export function matchesSourceHost(rule, host) {
+    const kind = classifyEgressHost(host);
+    if (kind === "numeric-ambiguous")
+        return false;
+    const hasSelector = rule.sourceHost !== undefined ||
+        rule.sourceHostSuffixes.length > 0 ||
+        rule.sourceIpv4Cidrs.length > 0 ||
+        rule.sourceIpv6Cidrs.length > 0;
     if (!hasSelector)
         return false;
-    return (host === rule.sourceHost ||
-        rule.sourceHostSuffixes.some((suffix) => matchesDnsSuffix(host, suffix)));
+    if (host === rule.sourceHost)
+        return true;
+    return matchesHostFamilySelectors(host, rule.sourceHostSuffixes, rule.sourceIpv4Cidrs, rule.sourceIpv6Cidrs);
+}
+function matchesHostFamilySelectors(host, hostSuffixes, ipv4Cidrs, ipv6Cidrs) {
+    const kind = classifyEgressHost(host);
+    if (kind === "ipv4") {
+        const address = parseStrictIpv4(host);
+        return address !== undefined && ipv4Cidrs.some((cidr) => ipv4InCidr(address, cidr));
+    }
+    if (kind === "ipv4-mapped-ipv6") {
+        const address = parseIpv6(host);
+        const embedded = address && embeddedIpv4FromIpv6(address);
+        return embedded !== undefined && ipv4Cidrs.some((cidr) => ipv4InCidr(embedded, cidr));
+    }
+    if (kind === "ipv6") {
+        const address = parseIpv6(host);
+        return address !== undefined && ipv6Cidrs.some((cidr) => ipv6InCidr(address, cidr));
+    }
+    return kind === "dns" && hostSuffixes.some((suffix) => matchesDnsSuffix(host, suffix));
 }
 function matchesPortSelectors(port, ports, ranges) {
     if (ports.length === 0 && ranges.length === 0)
@@ -944,13 +969,7 @@ function matchesDynamicRuleSelectors(rule, input) {
         grantTlsFitsRule(input.tls, rule.tls));
 }
 function matchesDynamicTargetHost(rule, targetHost) {
-    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);
 }
 function invalidGrant(message) {
     return new NativeNetworkError(message, "native_egress_grant_invalid");
@@ -1129,7 +1148,7 @@ export function createNativeEgressAuthorization(options) {
                 matchesPortSelectors(input.sourcePort, rule.sourcePorts, rule.sourcePortRanges)
                 ? [index]
                 : []);
-            const targetKind = classifyEgressTargetHost(diagnosticTargetHost);
+            const targetKind = classifyEgressHost(diagnosticTargetHost);
             let selectorDetails;
             if (sourceMatchingRuleIndices.length > 0) {
                 const failedByRule = [];

package/dist/types.d.ts

@@ -1090,9 +1090,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
@@ -1103,10 +1104,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/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.17",
+	"version": "2.2.0-beta.18",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",