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

package/dist/runtime/insights.d.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 export type InsightSeverity = "info" | "warning" | "error";
 export type Insight = {
     id: string;

package/dist/runtime/insights.js

@@ -1,4 +1,4 @@
-import { computePercentile } from "./perf";
+import { computePercentile } from "./perf.js";
 const LARGE_RESPONSE_BYTES = 100_000;
 const SLOW_TRANSFORM_MS = 10;
 const DNS_WARN_MS = 5;
@@ -188,8 +188,7 @@ function getDnsRepeatedCandidate(spans) {
         if (entry.totalCount < 2) {
             continue;
         }
-        const avgDnsMs = entry.dnsDurations.reduce((sum, value) => sum + value, 0) /
-            entry.dnsDurations.length;
+        const avgDnsMs = entry.dnsDurations.reduce((sum, value) => sum + value, 0) / entry.dnsDurations.length;
         const reuseRate = entry.reuseCount / entry.totalCount;
         if (avgDnsMs > DNS_WARN_MS && reuseRate < 0.2) {
             if (!candidate || avgDnsMs > candidate.avgDnsMs) {
@@ -218,9 +217,7 @@ function getDnsRepeatedInsight(spans) {
 }
 function getProxyOverheadInsight(spans) {
     const requestSpans = spans.filter(isRequestSpan);
-    const proxiedDurations = requestSpans
-        .filter(hasProxy)
-        .map((span) => span.duration_ms);
+    const proxiedDurations = requestSpans.filter(hasProxy).map((span) => span.duration_ms);
     const directDurations = requestSpans
         .filter((span) => !hasProxy(span))
         .map((span) => span.duration_ms);
@@ -230,10 +227,8 @@ function getProxyOverheadInsight(spans) {
             message: "✓ Proxy overhead: insufficient proxy/direct samples",
         };
     }
-    const proxyAvg = proxiedDurations.reduce((sum, value) => sum + value, 0) /
-        proxiedDurations.length;
-    const directAvg = directDurations.reduce((sum, value) => sum + value, 0) /
-        directDurations.length;
+    const proxyAvg = proxiedDurations.reduce((sum, value) => sum + value, 0) / proxiedDurations.length;
+    const directAvg = directDurations.reduce((sum, value) => sum + value, 0) / directDurations.length;
     if (directAvg > 0 && proxyAvg >= directAvg * 2) {
         return {
             triggered: true,
@@ -254,9 +249,7 @@ function getBrowserIdleInsight(spans) {
         if (waitMs !== undefined) {
             return waitMs;
         }
-        return span.name.toLowerCase().includes("wait")
-            ? span.duration_ms
-            : undefined;
+        return span.name.toLowerCase().includes("wait") ? span.duration_ms : undefined;
     })
         .filter((value) => value !== undefined);
     if (waits.length === 0) {

package/dist/runtime/instrumentation.d.ts

@@ -1,5 +1,5 @@
-import type { ProviderContext } from "../types";
-import { type CreateTraceContextOptions, type TraceContext } from "./trace";
+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"> & {

package/dist/runtime/instrumentation.js

@@ -1,11 +1,14 @@
-import { createTraceContext, getTraceRecorder, } from "./trace";
-const BROWSER_PAGE_METHODS = new Set([
-    "goto",
-    "fill",
-    "click",
-    "type",
-    "waitForSelector",
-]);
+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 &&
@@ -52,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") {
@@ -65,22 +233,27 @@ 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 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;
     }
-    if (status !== undefined &&
-        (namespace === "http" || namespace === "stealth")) {
+    if (status !== undefined && (namespace === "http" || namespace === "stealth")) {
         attributes.status = status;
     }
     if (duration !== undefined) {
@@ -95,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") {
@@ -155,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);
@@ -192,8 +475,7 @@ function wrapNamespace(namespace, target, trace) {
                             if (namespaceTarget &&
                                 typeof namespaceTarget === "object" &&
                                 "engine" in namespaceTarget &&
-                                typeof namespaceTarget.engine ===
-                                    "string") {
+                                typeof namespaceTarget.engine === "string") {
                                 attributes.engine = namespaceTarget.engine;
                             }
                             return attributes;
@@ -224,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;
         },
@@ -250,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/keyring.js

@@ -1,4 +1,4 @@
-import { ConfigurationError, decodeMasterKey } from "./key-derivation";
+import { ConfigurationError, decodeMasterKey } from "./key-derivation.js";
 const DEFAULT_KEY_PREFIX = "APIFUSE__KEYRING__MASTER_KEY_V";
 const DEFAULT_ACCEPT_LIST_VAR = "APIFUSE__KEYRING__MASTER_KEY_ACCEPT_LIST";
 const DEFAULT_WRITER_VERSION_VAR = "APIFUSE__KEYRING__MASTER_KEY_WRITER_VERSION";

package/dist/runtime/namespace.js

@@ -1,5 +1,5 @@
 import { createHmac } from "node:crypto";
-import { deriveSubkey } from "./key-derivation";
+import { deriveSubkey } from "./key-derivation.js";
 const HMAC_HEX_LENGTH = 16;
 /**
  * @internal Trusted loaders only; not re-exported to provider-importable paths.

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";
+    }
+}