@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

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

@@ -0,0 +1,31 @@
+import type { NativeTcpPortRange, NativeTcpTlsMode } from "./types.js";
+export type StaticEgressRuleSnapshot = {
+    readonly host: string;
+    readonly ports: readonly number[];
+    readonly tls: NativeTcpTlsMode;
+};
+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;
+    readonly ttlMs?: number;
+    readonly maxGrants?: number;
+};
+export type NativeEgressPolicySnapshot = {
+    readonly staticRules: readonly StaticEgressRuleSnapshot[];
+    readonly dynamicRules: readonly DynamicEgressRuleSnapshot[];
+};
+export declare class NativeEgressPolicyValidationError extends Error {
+    constructor(message: string);
+}
+export declare function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnapshot;
+export declare function validateNativeProviderConfig(value: unknown): void;

package/dist/native-egress-policy.js

@@ -0,0 +1,288 @@
+import { canonicalizeEgressHost, classifyEgressHost, formatIpv6, parseIpv4Cidr, parseIpv6Cidr, } from "./native-address.js";
+const NATIVE_PROVIDER_FIELD_RECORD = {
+    network: true,
+};
+const NATIVE_NETWORK_FIELD_RECORD = {
+    tcp: true,
+    dynamicTcp: true,
+};
+const NATIVE_TCP_RULE_FIELD_RECORD = {
+    host: true,
+    ports: true,
+    tls: true,
+};
+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,
+    ttlMs: true,
+    maxGrants: true,
+};
+const NATIVE_TCP_PORT_RANGE_FIELD_RECORD = {
+    start: true,
+    end: true,
+};
+const NATIVE_PROVIDER_FIELDS = Object.keys(NATIVE_PROVIDER_FIELD_RECORD);
+const NATIVE_NETWORK_FIELDS = Object.keys(NATIVE_NETWORK_FIELD_RECORD);
+const NATIVE_TCP_RULE_FIELDS = Object.keys(NATIVE_TCP_RULE_FIELD_RECORD);
+const NATIVE_DYNAMIC_TCP_RULE_FIELDS = Object.keys(NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD);
+const NATIVE_TCP_PORT_RANGE_FIELDS = Object.keys(NATIVE_TCP_PORT_RANGE_FIELD_RECORD);
+export class NativeEgressPolicyValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NativeEgressPolicyValidationError";
+    }
+}
+function fail(message) {
+    throw new NativeEgressPolicyValidationError(message);
+}
+function dataRecord(value, fieldPath, allowed) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail(`${fieldPath} must be an object`);
+    const prototype = Reflect.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        fail(`${fieldPath} must be a plain object`);
+    const record = {};
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== "string")
+            fail(`${fieldPath} must not contain symbol fields`);
+        if (!allowed.includes(key))
+            fail(`Unknown field ${fieldPath}.${key}`);
+        const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor))
+            fail(`${fieldPath}.${key} must be a data field`);
+        record[key] = descriptor.value;
+    }
+    return record;
+}
+function dataArray(value, fieldPath) {
+    if (!Array.isArray(value))
+        fail(`${fieldPath} must be an array`);
+    const result = [];
+    for (const key of Reflect.ownKeys(value)) {
+        if (key === "length")
+            continue;
+        if (typeof key !== "string" || !/^(?:0|[1-9]\d*)$/.test(key))
+            fail(`${fieldPath} must not contain non-index fields`);
+        const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+        if (!descriptor || !("value" in descriptor))
+            fail(`${fieldPath}[${key}] must be a data field`);
+        result[Number(key)] = descriptor.value;
+    }
+    if (result.length !== value.length)
+        fail(`${fieldPath} must not be sparse`);
+    for (let index = 0; index < result.length; index += 1) {
+        if (!(index in result))
+            fail(`${fieldPath} must not be sparse`);
+    }
+    return result;
+}
+function host(value, fieldPath, suffix = false) {
+    if (typeof value === "string" && value.includes("*"))
+        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;
+}
+function port(value, fieldPath) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 65_535)
+        fail(`${fieldPath} must be an integer from 1 to 65535`);
+    return value;
+}
+function ports(value, fieldPath) {
+    return dataArray(value, fieldPath).map((value, index) => port(value, `${fieldPath}[${index}]`));
+}
+function hostSuffixes(value, fieldPath) {
+    return dataArray(value, fieldPath).map((value, index) => host(value, `${fieldPath}[${index}]`, true));
+}
+function ipv4Cidrs(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 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 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}]`;
+        const record = dataRecord(value, rangePath, NATIVE_TCP_PORT_RANGE_FIELDS);
+        const start = port(record.start, `${rangePath}.start`);
+        const end = port(record.end, `${rangePath}.end`);
+        if (start > end)
+            fail(`${rangePath}.start must not exceed end`);
+        return { start, end };
+    });
+}
+function tls(value, fieldPath) {
+    if (value !== "required" && value !== "allowed" && value !== "disabled")
+        fail(`${fieldPath} must be required, allowed, or disabled`);
+    return value;
+}
+function positiveInteger(value, fieldPath) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+        fail(`${fieldPath} must be a positive integer`);
+    return value;
+}
+export function parseNativeEgressPolicy(value) {
+    try {
+        const policy = dataRecord(value, "native.network", NATIVE_NETWORK_FIELDS);
+        const staticRules = policy.tcp === undefined
+            ? []
+            : dataArray(policy.tcp, "native.network.tcp").map((value, index) => {
+                const fieldPath = `native.network.tcp[${index}]`;
+                const rule = dataRecord(value, fieldPath, NATIVE_TCP_RULE_FIELDS);
+                const declaredPorts = ports(rule.ports, `${fieldPath}.ports`);
+                if (declaredPorts.length === 0)
+                    fail(`${fieldPath}.ports must not be empty`);
+                return {
+                    host: host(rule.host, `${fieldPath}.host`),
+                    ports: declaredPorts,
+                    tls: tls(rule.tls, `${fieldPath}.tls`),
+                };
+            });
+        const dynamicRules = policy.dynamicTcp === undefined
+            ? []
+            : dataArray(policy.dynamicTcp, "native.network.dynamicTcp").map((value, index) => {
+                const fieldPath = `native.network.dynamicTcp[${index}]`;
+                const rule = dataRecord(value, fieldPath, NATIVE_DYNAMIC_TCP_RULE_FIELDS);
+                const sourceHost = rule.sourceHost === undefined
+                    ? undefined
+                    : host(rule.sourceHost, `${fieldPath}.sourceHost`);
+                const sourceHostSuffixes = rule.sourceHostSuffixes === undefined
+                    ? []
+                    : hostSuffixes(rule.sourceHostSuffixes, `${fieldPath}.sourceHostSuffixes`);
+                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`);
+                const sourcePortRanges = rule.sourcePortRanges === undefined
+                    ? []
+                    : 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`);
+                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`);
+                const targetPortRanges = rule.targetPortRanges === undefined
+                    ? []
+                    : ranges(rule.targetPortRanges, `${fieldPath}.targetPortRanges`);
+                if (targetPorts.length === 0 && targetPortRanges.length === 0)
+                    fail(`${fieldPath} must declare a non-empty targetPorts or targetPortRanges list`);
+                return {
+                    ...(sourceHost === undefined ? {} : { sourceHost }),
+                    sourceHostSuffixes,
+                    sourceIpv4Cidrs,
+                    sourceIpv6Cidrs,
+                    sourcePorts,
+                    sourcePortRanges,
+                    targetHostSuffixes,
+                    targetIpv4Cidrs,
+                    targetIpv6Cidrs,
+                    targetPorts,
+                    targetPortRanges,
+                    tls: tls(rule.tls, `${fieldPath}.tls`),
+                    ...(rule.ttlMs === undefined
+                        ? {}
+                        : { ttlMs: positiveInteger(rule.ttlMs, `${fieldPath}.ttlMs`) }),
+                    ...(rule.maxGrants === undefined
+                        ? {}
+                        : { maxGrants: positiveInteger(rule.maxGrants, `${fieldPath}.maxGrants`) }),
+                };
+            });
+        return { staticRules, dynamicRules };
+    }
+    catch (error) {
+        if (error instanceof NativeEgressPolicyValidationError)
+            throw error;
+        throw new NativeEgressPolicyValidationError("Native egress policy could not be inspected safely");
+    }
+}
+export function validateNativeProviderConfig(value) {
+    if (value === undefined)
+        return;
+    try {
+        const native = dataRecord(value, "native", NATIVE_PROVIDER_FIELDS);
+        if (native.network !== undefined)
+            parseNativeEgressPolicy(native.network);
+    }
+    catch (error) {
+        if (error instanceof NativeEgressPolicyValidationError)
+            throw error;
+        throw new NativeEgressPolicyValidationError("Native provider config could not be inspected safely");
+    }
+}

package/dist/observability.d.ts

@@ -1,5 +1,8 @@
-export declare const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
-export declare const PROVIDER_ERROR_CATEGORIES: readonly ["ok", "timeout", "network", "upstream_http", "upstream_rate_limited", "upstream_auth", "upstream_schema_drift", "proxy_pool", "anti_bot_blocked", "credential_expired", "credential_unavailable", "input_validation", "output_validation", "provider_error", "internal_error", "unclassified"];
+export declare const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-08-07";
+export declare const PROVIDER_ERROR_CATEGORIES: readonly ["ok", "timeout", "network", "upstream_http", "upstream_rate_limited", "upstream_auth", "upstream_rejected", "upstream_schema_drift", "proxy_pool", "anti_bot_blocked", "credential_expired", "credential_unavailable", "input_validation", "output_validation", "provider_error", "internal_error", "dependency_unavailable", "unsupported_transport", "client_cancelled", "unclassified"];
 export type ProviderErrorCategory = (typeof PROVIDER_ERROR_CATEGORIES)[number];
 export declare function categoryForStatus(status: number): ProviderErrorCategory;
 export declare function isRetryableCategory(category: ProviderErrorCategory): boolean;
+export declare const PROVIDER_ERROR_SOURCES: readonly ["client", "upstream_rule", "upstream_failure", "apifuse"];
+export type ProviderErrorSource = (typeof PROVIDER_ERROR_SOURCES)[number];
+export declare function sourceForCategory(category: ProviderErrorCategory): ProviderErrorSource;