@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/dist/runtime/instrumentation.d.ts

@@ -2,7 +2,7 @@ import type { ProviderContext } from "../types.js";
 import { type CreateTraceContextOptions, type TraceContext } from "./trace.js";
 export interface InstrumentationOptions extends CreateTraceContextOptions {
 }
-export type InstrumentedProviderContext<T extends ProviderContext> = Omit<T, "trace"> & {
+export type InstrumentedProviderContext<T extends Pick<ProviderContext, "trace">> = Omit<T, "trace"> & {
     trace: TraceContext;
 };
-export declare function wrapWithInstrumentation<T extends ProviderContext>(ctx: T, options?: InstrumentationOptions): InstrumentedProviderContext<T>;
+export declare function wrapWithInstrumentation<T extends Pick<ProviderContext, "trace">>(ctx: T, options?: InstrumentationOptions): InstrumentedProviderContext<T>;

package/dist/runtime/instrumentation.js

@@ -1,5 +1,14 @@
+import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
+import { parseHttpRequestInvocation, isSensitiveKey, redactSensitiveError, redactSensitiveText, redactUrlQueryParams, requestOptionsFromHttpInvocation, serializeRequestUrl, } from "./request-options.js";
 import { createTraceContext, getTraceRecorder, } from "./trace.js";
+import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
 const BROWSER_PAGE_METHODS = new Set(["goto", "fill", "click", "type", "waitForSelector"]);
+const DIAGNOSTIC_BASE_URL = "http://apifuse-instrumentation.invalid";
+function isThenable(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof value.then === "function");
+}
 function getErrorStatus(error) {
     if (typeof error === "object" &&
         error !== null &&
@@ -46,8 +55,173 @@ function getUrl(namespace, args, result) {
     }
     return undefined;
 }
+function requestOptionsForInvocation(namespace, methodName, args) {
+    if (namespace === "http") {
+        const invocation = parseHttpRequestInvocation(methodName, [...args]);
+        return invocation ? requestOptionsFromHttpInvocation(invocation) : undefined;
+    }
+    if (namespace !== "stealth" || methodName !== "fetch" || typeof args[0] !== "string") {
+        return undefined;
+    }
+    const options = args[1];
+    return options !== null && typeof options === "object" && !Array.isArray(options)
+        ? options
+        : undefined;
+}
+function fallbackSensitiveValues(options) {
+    const sensitiveParams = options?.sensitiveParams;
+    if (!sensitiveParams || typeof sensitiveParams !== "object")
+        return [];
+    return Object.values(sensitiveParams).map(String);
+}
+function stripDiagnosticBase(url) {
+    return url.startsWith(DIAGNOSTIC_BASE_URL) ? url.slice(DIAGNOSTIC_BASE_URL.length) || "/" : url;
+}
+function serializeDiagnosticUrl(url, options) {
+    try {
+        return {
+            degraded: false,
+            serializedUrl: serializeRequestUrl(url, options?.params, options?.sensitiveParams),
+        };
+    }
+    catch {
+        try {
+            const absoluteUrl = new URL(url, DIAGNOSTIC_BASE_URL).toString();
+            const serialized = serializeRequestUrl(absoluteUrl, options?.params, options?.sensitiveParams);
+            return {
+                degraded: false,
+                serializedUrl: {
+                    requestUrl: stripDiagnosticBase(serialized.requestUrl),
+                    redactedUrl: stripDiagnosticBase(serialized.redactedUrl),
+                    sensitiveValues: serialized.sensitiveValues,
+                },
+            };
+        }
+        catch {
+            const sensitiveParamNames = Object.keys(options?.sensitiveParams ?? {});
+            const structural = redactUrlQueryParams(url, sensitiveParamNames);
+            return {
+                degraded: true,
+                serializedUrl: {
+                    requestUrl: url,
+                    redactedUrl: structural.redactedUrl,
+                    sensitiveValues: [
+                        ...new Set([...fallbackSensitiveValues(options), ...structural.sensitiveValues]),
+                    ],
+                },
+            };
+        }
+    }
+}
+function snapshotRequestDiagnostics(namespace, methodName, args) {
+    const options = requestOptionsForInvocation(namespace, methodName, args);
+    const url = typeof args[0] === "string" ? args[0] : undefined;
+    const hasSensitiveParams = Boolean(options?.sensitiveParams && Object.keys(options.sensitiveParams).length > 0);
+    const sensitiveParamNames = Object.keys(options?.sensitiveParams ?? {});
+    const diagnosticUrl = hasSensitiveParams && url ? serializeDiagnosticUrl(url, options) : undefined;
+    const traceUrl = hasSensitiveParams && url
+        ? serializeDiagnosticUrl(url, { sensitiveParams: options?.sensitiveParams }).serializedUrl
+            .redactedUrl
+        : undefined;
+    return {
+        ...(diagnosticUrl?.degraded ? { diagnosticUrlDegraded: true } : {}),
+        ...(hasSensitiveParams ? { requestId: crypto.randomUUID() } : {}),
+        serializedUrl: diagnosticUrl?.serializedUrl,
+        sensitiveParamNames,
+        sensitiveValues: diagnosticUrl?.serializedUrl.sensitiveValues ?? fallbackSensitiveValues(options),
+        traceUrl,
+    };
+}
+function sanitizeRequestError(error, diagnostics) {
+    return redactSensitiveError(error, diagnostics.sensitiveValues, diagnostics.serializedUrl?.requestUrl, diagnostics.serializedUrl?.redactedUrl);
+}
+function isHttpStreamResponse(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "body" in value &&
+        value.body instanceof ReadableStream);
+}
+function instrumentHttpStreamConsumption(value, recorder, args, diagnostics) {
+    const source = value.body;
+    let reader;
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                reader ??= source.getReader();
+                const chunk = await reader.read();
+                if (chunk.done) {
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(chunk.value);
+            }
+            catch (error) {
+                const sanitizedError = sanitizeRequestError(error, diagnostics);
+                try {
+                    await recorder.runSpan("http.stream.consume", () => {
+                        throw sanitizedError;
+                    }, {
+                        onError: (spanError) => buildSpanAttributes("http", "stream", args, undefined, spanError, diagnostics),
+                    });
+                }
+                catch (recordedError) {
+                    controller.error(recordedError);
+                }
+            }
+        },
+        async cancel(reason) {
+            try {
+                await (reader ? reader.cancel(reason) : source.cancel(reason));
+            }
+            catch (error) {
+                throw sanitizeRequestError(error, diagnostics);
+            }
+        },
+    }, { highWaterMark: 0 });
+    const instrumented = {
+        ...value,
+        body,
+        bytes: () => readableBytes(body),
+        textChunks: () => readableTextChunks(body),
+        lines: () => readableLines(body),
+    };
+    try {
+        Object.assign(value, instrumented);
+        return value;
+    }
+    catch {
+        return instrumented;
+    }
+}
+function isAsyncIterable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Symbol.asyncIterator in value &&
+        typeof value[Symbol.asyncIterator] === "function");
+}
+function instrumentHttpSseConsumption(value, recorder, args, diagnostics) {
+    const source = value;
+    return {
+        async *[Symbol.asyncIterator]() {
+            try {
+                for await (const event of source)
+                    yield event;
+            }
+            catch (error) {
+                const sanitizedError = sanitizeRequestError(error, diagnostics);
+                return await recorder.runSpan("http.sse.consume", () => {
+                    throw sanitizedError;
+                }, {
+                    onError: (spanError) => buildSpanAttributes("http", "sse", args, undefined, spanError, diagnostics),
+                });
+            }
+        },
+    };
+}
 function getMethod(namespace, methodName, args) {
     if (namespace === "http") {
+        // Preserve the original instrumentation contract: generic entry points are
+        // reported as REQUEST/STREAM/SSE, independent of transport options.
         return methodName.toUpperCase();
     }
     if (namespace === "stealth") {
@@ -59,15 +233,23 @@ function getMethod(namespace, methodName, args) {
     }
     return undefined;
 }
-function buildSpanAttributes(namespace, methodName, args, result, error) {
+function buildSpanAttributes(namespace, methodName, args, result, error, diagnostics = { sensitiveParamNames: [], sensitiveValues: [] }) {
     const attributes = {};
-    const url = getUrl(namespace, args, result);
+    const rawUrl = getUrl(namespace, args, result);
+    const structuralUrl = diagnostics.traceUrl ?? rawUrl;
+    const url = structuralUrl
+        ? redactSensitiveText(structuralUrl, diagnostics.sensitiveValues, diagnostics.serializedUrl?.requestUrl, diagnostics.serializedUrl?.redactedUrl)
+        : undefined;
     const method = getMethod(namespace, methodName, args);
     const status = error ? getErrorStatus(error) : getResponseStatus(namespace, result);
     const duration = error ? undefined : getResponseDuration(result);
     if (url) {
         attributes.url = url;
     }
+    if (diagnostics.requestId)
+        attributes.request_id = diagnostics.requestId;
+    if (diagnostics.diagnosticUrlDegraded)
+        attributes.redaction_degraded = true;
     if (method) {
         attributes.method = method;
     }
@@ -86,6 +268,51 @@ function buildSpanAttributes(namespace, methodName, args, result, error) {
     }
     return attributes;
 }
+function isStealthRedirectRunResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "reason" in value &&
+        typeof value.reason === "string" &&
+        "hops" in value &&
+        Array.isArray(value.hops) &&
+        "final" in value &&
+        typeof value.final === "object" &&
+        value.final !== null);
+}
+function buildStealthRedirectAttributes(args, result, error, diagnostics) {
+    const attributes = buildSpanAttributes("stealth", "fetch", args, undefined, error, diagnostics);
+    if (!isStealthRedirectRunResult(result))
+        return attributes;
+    attributes.redirect_reason = result.reason;
+    attributes.redirect_hop_count = result.hops.length;
+    attributes.status = result.final.status;
+    if (result.hops.length > 0) {
+        const sensitiveValues = new Set(diagnostics.sensitiveValues);
+        const path = result.hops
+            .map((hop) => {
+            const hopUrl = hop.nextUrl ?? hop.url;
+            const responseSensitiveParamNames = [...queryParamNames(hopUrl)].filter(isSensitiveKey);
+            const structural = redactUrlQueryParams(hopUrl, [
+                ...new Set([...diagnostics.sensitiveParamNames, ...responseSensitiveParamNames]),
+            ]);
+            for (const value of structural.sensitiveValues)
+                sensitiveValues.add(value);
+            const safeUrl = redactSensitiveText(structural.redactedUrl, [...sensitiveValues]);
+            return `${hop.method} ${hop.status} ${safeUrl}`;
+        })
+            .join(" -> ");
+        attributes.redirect_path = redactSensitiveText(path, [...sensitiveValues], diagnostics.serializedUrl?.requestUrl, diagnostics.serializedUrl?.redactedUrl);
+    }
+    return attributes;
+}
+function queryParamNames(url) {
+    const queryStart = url.indexOf("?");
+    if (queryStart === -1)
+        return new Set();
+    const fragmentStart = url.indexOf("#", queryStart);
+    const query = url.slice(queryStart + 1, fragmentStart === -1 ? undefined : fragmentStart);
+    return new Set(new URLSearchParams(query).keys());
+}
 function getBrowserPageAttributes(methodName, args, elapsedMs, error) {
     const attributes = {};
     if (methodName === "goto") {
@@ -146,18 +373,83 @@ function wrapPage(page, trace) {
         },
     });
 }
-function wrapNamespace(namespace, target, trace) {
+function wrapStealthRedirects(redirects, trace) {
+    const recorder = getTraceRecorder(trace);
+    if (!recorder)
+        return redirects;
+    return {
+        run(...args) {
+            const diagnosticArgs = [args[0].url, args[0]];
+            const diagnostics = snapshotRequestDiagnostics("stealth", "fetch", diagnosticArgs);
+            let result;
+            try {
+                result = redirects.run(...args);
+            }
+            catch (error) {
+                const sanitizedError = sanitizeRequestError(error, diagnostics);
+                recorder
+                    .runSpan("stealth.redirects.run", () => {
+                    throw sanitizedError;
+                }, {
+                    onError: (spanError) => buildStealthRedirectAttributes(diagnosticArgs, undefined, spanError, diagnostics),
+                })
+                    .catch(() => undefined);
+                throw sanitizedError;
+            }
+            const sanitizedResult = Promise.resolve(result).catch((error) => {
+                throw sanitizeRequestError(error, diagnostics);
+            });
+            return recorder.runSpan("stealth.redirects.run", () => sanitizedResult, {
+                onSuccess: (spanResult) => buildStealthRedirectAttributes(diagnosticArgs, spanResult, undefined, diagnostics),
+                onError: (error) => buildStealthRedirectAttributes(diagnosticArgs, undefined, error, diagnostics),
+            });
+        },
+    };
+}
+function wrapStealthSession(session, trace) {
+    const wrappedSession = wrapNamespace("stealth", session, trace);
+    const redirects = wrapStealthRedirects(session.redirects, trace);
+    return new Proxy(wrappedSession, {
+        get(target, property, receiver) {
+            return property === "redirects" ? redirects : Reflect.get(target, property, receiver);
+        },
+    });
+}
+function wrapNamespace(namespace, target, trace, shouldInstrument) {
     const recorder = getTraceRecorder(trace);
     if (!recorder) {
         return target;
     }
     const wrappedMethods = new Map();
+    const resolverMetadata = namespace === "resolver" ? { target, traceRecorder: recorder } : undefined;
     return new Proxy(target, {
         get(namespaceTarget, property, receiver) {
+            if (property === RESOLVER_INSTRUMENTATION_METADATA && resolverMetadata) {
+                return resolverMetadata;
+            }
             const value = Reflect.get(namespaceTarget, property, receiver);
             if (typeof value !== "function" || property === "constructor") {
                 return value;
             }
+            if (namespace === "resolver" && property === "solve") {
+                if (wrappedMethods.has(property)) {
+                    return wrappedMethods.get(property);
+                }
+                const wrapped = (...args) => {
+                    const challenge = args[0];
+                    const challengeKind = typeof challenge === "object" &&
+                        challenge !== null &&
+                        "kind" in challenge &&
+                        typeof challenge.kind === "string"
+                        ? challenge.kind
+                        : undefined;
+                    return recorder.runSpan("resolver.solve", () => Reflect.apply(value, namespaceTarget, [args[0], args[1], recorder]), {
+                        attributes: challengeKind ? { challenge_kind: challengeKind } : undefined,
+                    });
+                };
+                wrappedMethods.set(property, wrapped);
+                return wrapped;
+            }
             if (namespace === "browser" && property === "newPage") {
                 if (wrappedMethods.has(property)) {
                     return wrappedMethods.get(property);
@@ -214,10 +506,75 @@ function wrapNamespace(namespace, target, trace) {
                 wrappedMethods.set(property, wrapped);
                 return wrapped;
             }
-            const wrapped = (...args) => recorder.runSpan(`${namespace}.${methodName}`, () => Reflect.apply(value, namespaceTarget, args), {
-                onSuccess: (result) => buildSpanAttributes(namespace, methodName, args, result),
-                onError: (error) => buildSpanAttributes(namespace, methodName, args, undefined, error),
-            });
+            const wrapped = (...args) => {
+                if (shouldInstrument && !shouldInstrument(methodName, args)) {
+                    return Reflect.apply(value, namespaceTarget, args);
+                }
+                const requestDiagnostics = snapshotRequestDiagnostics(namespace, methodName, args);
+                // Invoke first and decide by the RETURN VALUE. `runSpan` always
+                // returns a Promise, so unconditionally span-wrapping every member
+                // silently rewrote synchronous contracts: `ctx.state.namespace()`
+                // (a sync factory) came back as a Promise, and every method call on
+                // it threw a raw TypeError — surfaced in production as catchtable's
+                // deterministic CONFIRM_STATE_UNAVAILABLE on 2026-07-27 (and the
+                // 2026-07-22 reserve internal_error loop before it). Sync members
+                // keep their sync contract; only genuinely async operations are
+                // recorded as spans.
+                let result;
+                try {
+                    result = Reflect.apply(value, namespaceTarget, args);
+                }
+                catch (error) {
+                    const sanitizedError = sanitizeRequestError(error, requestDiagnostics);
+                    // A promise-returning implementation may still throw
+                    // SYNCHRONOUSLY during pre-flight validation. Preserve the
+                    // synchronous throw contract, but keep recording the failure
+                    // span (the pre-fidelity wrapper captured these).
+                    recorder
+                        .runSpan(`${namespace}.${methodName}`, () => {
+                        throw sanitizedError;
+                    }, {
+                        onError: (spanError) => buildSpanAttributes(namespace, methodName, args, undefined, spanError, requestDiagnostics),
+                    })
+                        .catch(() => undefined);
+                    throw sanitizedError;
+                }
+                if (!isThenable(result)) {
+                    // The state namespace factory returns the object whose METHODS
+                    // are the operations worth tracing — instrument that object so
+                    // `state.get`/`state.compareAndSet`/… spans exist (they never
+                    // could before: the factory's return value was destroyed).
+                    if (namespace === "state" &&
+                        methodName === "namespace" &&
+                        typeof result === "object" &&
+                        result !== null) {
+                        return wrapNamespace(namespace, result, trace);
+                    }
+                    if (namespace === "stealth" &&
+                        methodName === "createSession" &&
+                        typeof result === "object" &&
+                        result !== null) {
+                        return wrapStealthSession(result, trace);
+                    }
+                    return result;
+                }
+                const sanitizedResult = Promise.resolve(result).catch((error) => {
+                    throw sanitizeRequestError(error, requestDiagnostics);
+                });
+                const tracedResult = recorder.runSpan(`${namespace}.${methodName}`, () => sanitizedResult, {
+                    onSuccess: (spanResult) => buildSpanAttributes(namespace, methodName, args, spanResult, undefined, requestDiagnostics),
+                    onError: (error) => buildSpanAttributes(namespace, methodName, args, undefined, error, requestDiagnostics),
+                });
+                return namespace === "http" && methodName === "stream"
+                    ? tracedResult.then((spanResult) => isHttpStreamResponse(spanResult)
+                        ? instrumentHttpStreamConsumption(spanResult, recorder, args, requestDiagnostics)
+                        : spanResult)
+                    : namespace === "http" && methodName === "sse"
+                        ? tracedResult.then((spanResult) => isAsyncIterable(spanResult)
+                            ? instrumentHttpSseConsumption(spanResult, recorder, args, requestDiagnostics)
+                            : spanResult)
+                        : tracedResult;
+            };
             wrappedMethods.set(property, wrapped);
             return wrapped;
         },
@@ -240,7 +597,8 @@ export function wrapWithInstrumentation(ctx, options = {}) {
                 property === "stealth" ||
                 property === "browser" ||
                 property === "session" ||
-                property === "state") {
+                property === "state" ||
+                property === "resolver") {
                 const namespace = property;
                 if (wrappedTargets.has(namespace)) {
                     return wrappedTargets.get(namespace);

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

@@ -0,0 +1,33 @@
+import { TransportError } from "../errors.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 {
+    constructor(message: string, code: NativeNetworkErrorCode, cause?: Error);
+    get code(): NativeNetworkErrorCode;
+}
+export declare function safeDiagnosticEgressHost(value: unknown): string;
+export declare class NativeProxyExpiredError extends NativeNetworkError {
+    readonly expiresAt: string;
+    constructor(expiresAt: string);
+}
+/** Raised before transport setup when a native destination is not authorized. */
+export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
+    readonly port: number;
+    readonly tls: "required" | "disabled";
+    readonly host: string;
+    constructor(host: string, port: number, tls: "required" | "disabled");
+}
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export declare class NativeEgressGrantExpiredError extends NativeNetworkError {
+    readonly port: number;
+    readonly tls: "required" | "disabled";
+    readonly expiresAt: string;
+    readonly host: string;
+    constructor(host: string, port: number, tls: "required" | "disabled", expiresAt: string);
+}
+/** Raised when an established connection exceeds its opt-in read-idle window. */
+export declare class NativeIdleTimeoutError extends NativeNetworkError {
+    constructor();
+}

package/dist/runtime/native-network-errors.js

@@ -0,0 +1,69 @@
+import { TransportError } from "../errors.js";
+import { canonicalizeEgressHost } from "../native-address.js";
+export class NativeNetworkError extends TransportError {
+    constructor(message, code, cause) {
+        const isEgressPolicyFailure = code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
+        super(message, {
+            code,
+            status: 0,
+            ...(cause ? { cause } : {}),
+            ...(isEgressPolicyFailure ? { category: "provider_error", retryable: false } : {}),
+        });
+        this.name = "NativeNetworkError";
+    }
+    get code() {
+        return super.code;
+    }
+}
+export function safeDiagnosticEgressHost(value) {
+    const canonical = canonicalizeEgressHost(value);
+    return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
+export class NativeProxyExpiredError extends NativeNetworkError {
+    expiresAt;
+    constructor(expiresAt) {
+        super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
+        this.expiresAt = expiresAt;
+        this.name = "NativeProxyExpiredError";
+    }
+}
+/** Raised before transport setup when a native destination is not authorized. */
+export class NativeEgressNotDeclaredError extends NativeNetworkError {
+    port;
+    tls;
+    host;
+    constructor(host, port, tls) {
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`, "native_egress_not_declared");
+        this.port = port;
+        this.tls = tls;
+        this.host = diagnosticHost;
+        this.name = "NativeEgressNotDeclaredError";
+    }
+}
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export class NativeEgressGrantExpiredError extends NativeNetworkError {
+    port;
+    tls;
+    expiresAt;
+    host;
+    constructor(host, port, tls, expiresAt) {
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`, "native_egress_grant_expired");
+        this.port = port;
+        this.tls = tls;
+        this.expiresAt = expiresAt;
+        this.host = diagnosticHost;
+        this.name = "NativeEgressGrantExpiredError";
+    }
+}
+/** Raised when an established connection exceeds its opt-in read-idle window. */
+export class NativeIdleTimeoutError extends NativeNetworkError {
+    constructor() {
+        super("Native network socket timed out while reading.", "native_connection_idle_timeout");
+        this.name = "NativeIdleTimeoutError";
+    }
+}

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

@@ -0,0 +1,96 @@
+import { Socket } from "node:net";
+import { type TLSSocket } from "node:tls";
+import { type ProxyProtocol } from "../config/loader.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 { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./native-network-errors.js";
+export type { NativeNetworkErrorCode } from "./native-network-errors.js";
+export type NativeGatewayProxy = NativeProxyEgressInfo & {
+    readonly url: string;
+};
+export type NativeGatewayProxySynthesisInput = {
+    readonly vendor: ProviderProxyProvider;
+    readonly policy: ProviderProxyPolicy;
+    readonly affinityKey?: string;
+    readonly now: number;
+    readonly protocol: ProxyProtocol;
+    readonly credentials: VendorCredentialResolver;
+};
+export type VendorCredentialLookup = {
+    readonly kind: "present";
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "absent";
+    readonly missing: readonly string[];
+};
+export type VendorCredentialResolver = (vendor: ProviderProxyProvider) => VendorCredentialLookup;
+export type NativeGatewayProxySkipReason = {
+    readonly kind: "credentials_absent";
+    readonly missing: readonly string[];
+} | {
+    readonly kind: "protocol_unsupported";
+    readonly protocol: string;
+} | {
+    readonly kind: "allocation_failed";
+    readonly cause: Error;
+} | {
+    readonly kind: "credential_lookup_failed";
+    readonly cause: Error;
+};
+export type NativeGatewayProxySynthesisResult = NativeGatewayProxy | {
+    readonly kind: "skipped";
+    readonly reason: NativeGatewayProxySkipReason;
+} | undefined;
+/** A vendor adapter in the ordered native gateway resolution chain. */
+export type NativeGatewayProxySynthesizer = (input: NativeGatewayProxySynthesisInput) => NativeGatewayProxySynthesisResult | Promise<NativeGatewayProxySynthesisResult>;
+export type NativeGatewayProxyResolutionInput = {
+    readonly policy: ProviderProxyPolicy;
+    readonly affinityKey?: string;
+    readonly now?: number;
+    readonly protocol?: ProxyProtocol;
+    readonly credentials?: VendorCredentialResolver;
+    readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
+};
+export type NativeNetworkClientOptions = {
+    readonly proxyPolicy?: ProviderProxyPolicy;
+    readonly affinityKey?: string;
+    /** Stable credential/account identity; hashed before vendor synthesis. */
+    readonly credentialIdentity?: string;
+    /** Vendor credential lookup; defaults to the process EnvContext. */
+    readonly credentials?: VendorCredentialResolver;
+    /** Explicit CONNECT/SOCKS5 override; vendors otherwise choose their default. */
+    readonly proxyProtocol?: ProxyProtocol;
+    /** Vendor adapters in priority order within each policy vendor slot. */
+    readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
+    /** Warning-level lifecycle diagnostic sink. */
+    readonly warn?: (message: string) => void;
+    /**
+     * Provider-declared native egress. Undefined preserves legacy unrestricted
+     * behavior; any provided declaration, including an empty object, is enforced.
+     */
+    readonly egress?: NonNullable<NativeProviderConfig["network"]>;
+    /** Additional deployment authorization layered on top of SDK enforcement. */
+    readonly grantTcpEgress?: (input: NativeNetworkDynamicGrantOptions) => NativeNetworkEgressGrant;
+};
+/** Build a resolver over the SDK's existing injectable environment context. */
+export declare function createEnvVendorCredentialResolver(env?: EnvContext): VendorCredentialResolver;
+/** Domain-separated, process-independent affinity derived from credential identity. */
+export declare function deriveNativeCredentialAffinityKey(credentialIdentity: string): string;
+/** Resolve the first configured native gateway, including allocation vendors. */
+export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResolutionInput): Promise<NativeGatewayProxy | undefined>;
+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. */
+export declare function snapshotNativeGrantInput(input: NativeNetworkDynamicGrantOptions): NativeNetworkDynamicGrantOptions;
+/** Internal authorization seam shared by production and SDK transport test doubles. */
+export declare function createNativeEgressAuthorization(options: NativeNetworkClientOptions): {
+    assertConnect(input: NativeNetworkConnectInput, tls: NativeConnectTls): void;
+    grant(input: NativeNetworkDynamicGrantOptions): NativeNetworkEgressGrant;
+};
+/** Create the SDK byte-stream runtime with provider-declared egress enforcement. */
+export declare function createNativeNetworkClient(options?: NativeNetworkClientOptions): NativeNetworkClient;