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

package/AUTHORING.md

@@ -742,6 +742,46 @@ const credentialsAuth = defineCredentialsAuth({
   `bunx playwright install chromium`, or set
   `APIFUSE__CDP_POOL__URL` for remote browser debugging.
 
+### Native gateway adapter migration
+
+Native proxy resolution supports both HTTP CONNECT and SOCKS5 without
+terminating origin TLS. The built-in vendor order follows `proxy.providers`
+exactly: `smartproxy` means the `api.smartproxy.org` allocation vendor (raw
+`ip:port` endpoints), while `nodemaven` is the credentialed gateway. It is not
+the company formerly called Smartproxy; that separate company is represented
+by the deprecated `decodo` name.
+
+Custom `gatewaySynthesizers` must now accept the selected `protocol` and the
+injected `credentials` resolver on `NativeGatewayProxySynthesisInput`.
+Synthesizers may be async because allocation vendors perform network I/O. They
+may return a proxy, `undefined` when they do not implement the offered vendor,
+or `{ kind: "skipped", reason }` so an exhausted required chain can explain an
+absent credential, unsupported protocol, or allocation failure. Accordingly,
+`resolveNativeGatewayProxy(...)` must now be awaited.
+
+Callers that do not supply custom synthesizers or credentials keep env-backed
+behavior. Hosts that already have an allowlisted `EnvContext` can inject it
+explicitly, and vault-backed or per-tenant hosts can supply their own resolver:
+
+```ts
+import {
+  createEnvVendorCredentialResolver,
+  createNativeNetworkClient,
+} from "@apifuse/provider-sdk";
+
+const network = createNativeNetworkClient({
+  proxyPolicy: { mode: "required", providers: ["smartproxy", "nodemaven"] },
+  credentials: createEnvVendorCredentialResolver(ctx.env),
+  // Optional advanced override; omit for each vendor's default.
+  proxyProtocol: "socks5",
+});
+```
+
+Never include credential values in adapter skip messages or thrown errors. The
+SDK redacts built-in proxy URL userinfo, CONNECT authentication, and allocator
+causes, but a custom adapter remains responsible for not publishing secrets in
+its own diagnostics.
+
 ### Limiting stealth response bodies
 
 Set `maxBodyBytes` on `ctx.stealth.fetch()` or `session.redirects.run()` when an

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @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.
+
 ## 2.2.0-beta.16
 
 - Release candidate for main commit c5deb2bc31a4a4a236d27a2ce3d214b533ed358f.
@@ -94,6 +102,7 @@
 
 ## Unreleased
 
+- **Breaking for custom native gateway adapters:** `NativeGatewayProxySynthesisInput` now includes an injected `credentials` resolver and selected `protocol`; synthesizers may return promises and structured skip reasons, and `resolveNativeGatewayProxy` is async. Default callers retain env-backed behavior. Native transport now supports both HTTP CONNECT and SOCKS5, defaults per vendor with an explicit runtime override, registers smartproxy allocation ahead of nodemaven when declared in that order, and reports every exhausted vendor reason without exposing proxy credentials.
 - Honor operation `docs.errorCodes` at runtime: declared provider-owned statuses and retryability now drive the HTTP envelope, observability header, and structured log; invalid statuses fail `defineProvider`, declared codes no longer emit the unregistered-code signal, and `TransportError` status-preservation workarounds are obsolete.
 - Add an opt-in same-origin redirect hop policy to `ctx.http`, with bounded manual following and typed failures before a refused target is requested.
 - Enforce provider-declared native TCP/TLS egress before proxy or socket setup, with revocable and expiring dynamic grants plus typed authorization failures; providers without a native egress declaration retain legacy behavior.

package/dist/config/loader.d.ts

@@ -150,12 +150,31 @@ export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions
  * Vendor allocation and failover remain owned by the SDK.
  */
 export declare function resolveProxy(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * Each vendor's default egress protocol, chosen from live KR benchmarks. HTTP
+ * CONNECT wins for nodemaven (socks5 adds ~500ms through the gateway) and ties
+ * for smartproxy, and is the only protocol ctx.http (Bun native fetch) supports.
+ * Override per call via ProxyResolutionOptions.protocol (harness/tests).
+ */
+export declare const VENDOR_DEFAULT_PROTOCOL: Readonly<Record<ProxyVendorName, ProxyProtocol>>;
 /**
  * Guard the No-MITM invariant: a resolved proxy URL must use a tunnelling scheme
  * (http CONNECT or socks5) so the client TLS handshake reaches the origin
  * end-to-end. Anything else would intercept TLS and break fingerprinting.
  */
 export declare function assertTunnelingScheme(url: string): void;
+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 declare function resolveWithVendor(vendor: ProxyVendorName, policy: ProviderProxyPolicy, options: ProxyResolutionOptions, context: ProxyVendorResolutionContext): Promise<ResolvedProxyConfig>;
 /**
  * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
  * takes precedence over the legacy singular `provider`; the platform default

package/dist/config/loader.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { Redis } from "ioredis";
-import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_MAX_POOL_SIZE, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
+import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_FILTER_ENV, NODEMAVEN_MAX_POOL_SIZE, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
 // "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
 // extraction API (app_key → raw ip:port pool). It is NOT the company formerly
 // named Smartproxy (smartproxy.com), which rebranded to Decodo in 2025 and is
@@ -415,7 +415,7 @@ export async function resolveProxy(options = {}) {
  * 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 = {
+export const VENDOR_DEFAULT_PROTOCOL = {
     smartproxy: "http",
     nodemaven: NODEMAVEN_DEFAULT_PROTOCOL,
 };
@@ -436,16 +436,33 @@ export function assertTunnelingScheme(url) {
         throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `Resolved proxy scheme "${scheme}" is not a tunnelling scheme (expected http or socks5). Refusing to route TLS through a non-tunnelling proxy.`);
     }
 }
-async function resolveWithVendor(vendor, policy, options, context) {
+export async function resolveWithVendor(vendor, policy, options, context) {
     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",
@@ -468,13 +485,15 @@ async function resolveWithVendor(vendor, policy, options, context) {
         };
     }
     // 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("PROXY_ALLOCATION_FAILED", `${SMARTPROXY_APP_KEY_ENV} is not configured.`, { vendor: "smartproxy" });
     }
-    const lifetimeMinutes = resolveSmartproxyLifetime(policy);
-    const allocated = await allocateSmartproxy(policy, appKey, lifetimeMinutes, options.affinityKey, context.protocol);
+    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);
     const url = allocated.pool.urls[poolIndex];
@@ -665,11 +684,15 @@ export function mapFlatAttempt(flat, sizes) {
     }
     return { vendorIndex: 0, poolIndex: 0 };
 }
-function resolveSmartproxyCountry(policy) {
-    return (policy.geo?.country ?? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ?? undefined);
+function resolveSmartproxyCountry(policy, ambientDefaults = true) {
+    return (policy.geo?.country ??
+        (ambientDefaults
+            ? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() || undefined
+            : undefined));
 }
-function resolveSmartproxyLifetime(policy) {
-    const configuredLifetime = policy.session?.lifetimeMinutes ?? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30);
+function resolveSmartproxyLifetime(policy, ambientDefaults = true) {
+    const configuredLifetime = policy.session?.lifetimeMinutes ??
+        (ambientDefaults ? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30) : 30);
     return Math.min(SMARTPROXY_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configuredLifetime)));
 }
 function readPositiveNumberEnv(name, fallback) {
@@ -692,20 +715,24 @@ function selectProxyPoolIndex(poolSize, attempt = 0) {
     const normalizedAttempt = Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
     return normalizedAttempt % poolSize;
 }
-function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol) {
+function buildSmartproxyCacheKey(policy, appKey, affinityKey, lifetimeMinutes, protocol, ambientDefaults = true) {
     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,
         poolSize,
     });
 }
-async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey, protocol) {
-    const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol);
+async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey, protocol, ambientDefaults = true, sharedCache = true) {
+    const cacheKey = buildSmartproxyCacheKey(policy, appKey, affinityKey, lifetimeMinutes, protocol, ambientDefaults);
     const startedAt = Date.now();
     const now = startedAt;
     const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
@@ -713,7 +740,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
     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, {
@@ -726,7 +753,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
             telemetry: telemetryForPool(cached, "memory_hit", startedAt),
         };
     }
-    if (!skipCached) {
+    if (!skipCached && sharedCache) {
         const redisResult = await readSmartproxyRedisPool(cacheKey, startedAt);
         if (redisResult)
             return redisResult;
@@ -741,7 +768,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
             }),
         };
     }
-    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol).finally(() => {
+    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, ambientDefaults, sharedCache).finally(() => {
         proxyInflight.delete(cacheKey);
     });
     proxyInflight.set(cacheKey, promise);
@@ -772,9 +799,9 @@ async function readSmartproxyRedisPool(cacheKey, startedAt) {
         telemetry: telemetryForPool(pool, "redis_hit", startedAt, { redisReadMs }),
     };
 }
-async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol) {
+async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol, ambientDefaults, sharedCache) {
     try {
-        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), protocol, {
+        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), protocol, ambientDefaults, sharedCache, {
             background: true,
         });
     }
@@ -782,10 +809,10 @@ async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes,
         // Soft refresh is opportunistic; current fresh pool remains usable.
     }
 }
-async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, options = {}) {
-    const redis = getProxyRedis();
+async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, ambientDefaults, sharedCache, options = {}) {
+    const redis = sharedCache ? getProxyRedis() : undefined;
     if (!redis || !(await ensureRedisReady(redis))) {
-        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator", protocol });
+        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator", protocol, ambientDefaults });
     }
     const poolKey = smartproxyRedisPoolKey(cacheKey);
     const lockKey = smartproxyRedisLockKey(cacheKey);
@@ -800,6 +827,7 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
                     redis,
                     poolKey,
                     protocol,
+                    ambientDefaults,
                 });
             }
             finally {
@@ -912,7 +940,7 @@ async function readSmartproxyAllocatorBodyWithDeadline(response, signal) {
 }
 async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, options) {
     const poolSize = resolveSmartproxyPoolSize(policy);
-    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, options.protocol);
+    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, options.protocol, options.ambientDefaults);
     const allocatorStartedAt = Date.now();
     const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
     let allocation;
@@ -970,7 +998,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
         expiresAt: allocatedAt + ttlMs,
         diagnostics: {
             provider: "smartproxy",
-            country: resolveSmartproxyCountry(policy) ?? "default",
+            country: resolveSmartproxyCountry(policy, options.ambientDefaults) ?? "default",
             lifetimeMinutes,
             affinity: policy.session?.affinity ?? "request",
             rawConnect: true,
@@ -1090,7 +1118,7 @@ const SMARTPROXY_PROTOCOL_PARAM = {
     http: "1",
     socks5: "2",
 };
-function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, protocol) {
+function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, protocol, ambientDefaults = true) {
     const params = new URLSearchParams({
         app_key: appKey,
         pt: "9",
@@ -1100,7 +1128,7 @@ function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize,
         format: "txt",
         lb: "\\n",
     });
-    const country = resolveSmartproxyCountry(policy);
+    const country = resolveSmartproxyCountry(policy, ambientDefaults);
     if (country) {
         params.set("cc", country);
     }
@@ -1172,7 +1200,10 @@ function markSmartproxyCacheInvalidated(options = {}) {
         return undefined;
     }
     const lifetimeMinutes = resolveSmartproxyLifetime(policy);
-    const cacheKey = buildSmartproxyCacheKey(policy, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);
+    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);
     invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
     proxyCache.delete(cacheKey);
     proxyInflight.delete(cacheKey);

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { type CreateCredentialContextOptions, createCredentialContext, } from ".
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, createEnvVendorCredentialResolver, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, 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";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";

package/dist/index.js

@@ -20,7 +20,7 @@ export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, createEnvVendorCredentialResolver, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
 export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { prevalidate } from "./runtime/prevalidate.js";

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;