@apifuse/provider-sdk 2.2.0-beta.13 → 2.2.0-beta.15

package/dist/server/serve.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
-import { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, } from "../errors.js";
+import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
@@ -15,6 +15,7 @@ import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
 import { createHttpClient } from "../runtime/http.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
+import { createNativeNetworkClient } from "../runtime/native-network.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
@@ -33,6 +34,8 @@ import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { AuthFlowRequestSchema, OperationConnectionSchema, OperationRequestSchema, } from "./types.js";
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
 const retryResponseMeta = new WeakMap();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
@@ -146,6 +149,15 @@ export function resolveProviderProxyAffinityKey(provider, request, operationId)
 function resolveOperationConnectionId(request) {
     return request.connection?.id ?? request.connectionId;
 }
+function resolveNativeProxyPolicy(provider) {
+    if (typeof provider.proxy === "object")
+        return provider.proxy;
+    if (provider.proxy === true)
+        return { mode: "optional" };
+    if (provider.proxy === false)
+        return { mode: "disabled" };
+    return undefined;
+}
 function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
@@ -204,6 +216,17 @@ function createProviderContext(provider, request, operationId, options = {}, sta
                 engine: provider.browser?.engine,
             })
             : createBrowserStub(),
+        ...(provider.native
+            ? {
+                native: {
+                    network: createNativeNetworkClient({
+                        egress: provider.native.network,
+                        proxyPolicy: resolveNativeProxyPolicy(provider),
+                        affinityKey: proxyClientOptions.affinityKey,
+                    }),
+                },
+            }
+            : {}),
         trace: createTraceContext(),
         auth: createAuthStub(),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),
@@ -280,6 +303,17 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
                     ? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
                     : createStealthClient(stealthBaseUrl, stealthClientOptions)
                 : createStealthStub(),
+            ...(provider.native
+                ? {
+                    native: {
+                        network: createNativeNetworkClient({
+                            egress: provider.native.network,
+                            proxyPolicy: resolveNativeProxyPolicy(provider),
+                            affinityKey: proxyClientOptions.affinityKey,
+                        }),
+                    },
+                }
+                : {}),
             env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
             credential,
             context: flowContextStore.context,
@@ -320,25 +354,27 @@ function zodDetails(error) {
     }));
 }
 function toErrorResponse(error, requestId) {
+    const observability = errorObservabilityDetails(error);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
             error: {
                 code: "STATEFUL_FORWARDING_DEADLINE_EXPIRED",
                 message: "Stateful forwarding deadline expired.",
                 ...(requestId ? { requestId } : {}),
-                details: { retryable: false },
+                retryable: observability.retryable,
             },
         };
     }
     if (isProviderError(error)) {
-        const details = publicProviderErrorDetails(error);
+        const details = error.details;
         return {
             error: {
                 code: error.code ?? "provider_error",
                 message: publicProviderErrorMessage(error),
                 ...(requestId ? { requestId } : {}),
+                retryable: observability.retryable,
                 ...(error.fix ? { fix: error.fix } : {}),
-                ...(details ? { details } : {}),
+                ...(details !== undefined ? { details } : {}),
             },
         };
     }
@@ -348,6 +384,7 @@ function toErrorResponse(error, requestId) {
                 code: "invalid_request",
                 message: "Invalid request body",
                 ...(requestId ? { requestId } : {}),
+                retryable: observability.retryable,
                 details: zodDetails(error),
             },
         };
@@ -363,6 +400,7 @@ function toErrorResponse(error, requestId) {
             code: "internal_error",
             message: "Internal error",
             ...(requestId ? { requestId } : {}),
+            retryable: observability.retryable,
             details: {
                 retryable: false,
                 category: "internal_error",
@@ -371,26 +409,6 @@ function toErrorResponse(error, requestId) {
         },
     };
 }
-function publicProviderErrorDetails(error) {
-    const providerDetails = error.details;
-    const observabilityDetails = providerObservabilityDetails(error);
-    if (providerDetails === undefined) {
-        return observabilityDetails;
-    }
-    if (observabilityDetails === undefined) {
-        return providerDetails;
-    }
-    if (isPlainRecord(providerDetails) && isPlainRecord(observabilityDetails)) {
-        return { ...providerDetails, ...observabilityDetails };
-    }
-    return {
-        provider: providerDetails,
-        observability: observabilityDetails,
-    };
-}
-function isPlainRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 // Accepts `unknown` so the branded guards narrow cleanly from the top: the
 // subtype error classes are structurally compatible with ProviderError, so
 // narrowing from a ProviderError-typed value would collapse the negative branch
@@ -449,6 +467,48 @@ function providerObservabilityDetails(error) {
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
+function errorObservabilityDetails(error) {
+    const providerDetails = providerObservabilityDetails(error);
+    if (providerDetails)
+        return providerDetails;
+    if (error instanceof z.ZodError || isValidationError(error)) {
+        return {
+            category: isProviderError(error) && error.options?.category
+                ? error.options.category
+                : "input_validation",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+        };
+    }
+    if (error instanceof StatefulRoutingDeadlineError) {
+        return {
+            category: "timeout",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: false,
+        };
+    }
+    if (isProviderError(error)) {
+        return {
+            category: error.options?.category ?? "provider_error",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: error.options?.retryable ?? false,
+        };
+    }
+    return {
+        category: "internal_error",
+        taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+        retryable: false,
+    };
+}
+function responseWithErrorObservability(response, error) {
+    const headers = new Headers(response.headers);
+    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
 function publicProviderErrorMessage(error) {
     if (isTransportError(error)) {
         if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
@@ -481,9 +541,6 @@ function toStatusCode(error) {
     if (error instanceof StatefulRoutingDeadlineError) {
         return 504;
     }
-    if (isTransportError(error)) {
-        return error.code === "transport_timeout" ? 504 : 502;
-    }
     if (isProviderError(error)) {
         switch (error.code) {
             case "AUTH_REQUIRED":
@@ -509,10 +566,92 @@ function toStatusCode(error) {
             case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
                 return 503;
         }
-        return 400;
+        if (isTransportError(error)) {
+            return error.code === "transport_timeout" ? 504 : 502;
+        }
+        if (isValidationError(error)) {
+            return error.options?.category === "output_validation" ? 500 : 400;
+        }
+        return 500;
     }
     return 500;
 }
+// Codes emitted by SDK-owned paths must never be attributed to provider
+// authors by the unregistered-code signal, even when their intentional status
+// is 500. Provider-authored codes not in this registry retain the signal.
+const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+    "AUTH_PROMPT_UNAVAILABLE",
+    "BROWSER_CDP_POOL_REQUIRED",
+    "BROWSER_RUNTIME_UNSUPPORTED",
+    "STEALTH_RUNTIME_UNSUPPORTED",
+    "SSE_EVENT_UNDECLARED",
+    "STREAM_EVENT_TOO_LARGE",
+    "STREAM_CHUNK_TOO_LARGE",
+    "SSE_RESULT_UNSUPPORTED",
+    "STREAM_RESULT_UNSUPPORTED",
+    "AUTH_FLOW_NOT_CONFIGURED",
+    "refresh_not_supported",
+    "RUNTIME_UNSUPPORTED",
+    "PROVIDER_STATE_UNSUPPORTED",
+    "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+    "CHOICE_STATE_PAYLOAD_TOO_LARGE",
+    "CHOICE_STATE_UNAVAILABLE",
+    "CHOICE_CONTEXT_REQUIRED",
+    "unsupported_stealth_cookie_store_version",
+    "provider_secret_error",
+    "credential_key_error",
+    "credential_mode_error",
+    "flow_expired",
+    "turn_validation_error",
+    "context_access_error",
+    "UNSUPPORTED_STT_OPTION",
+    "INVALID_STT_AUDIO",
+    "STT_AUDIO_TOO_LARGE",
+    "STT_UPSTREAM_FAILED",
+    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+    "NO_CODE_FOUND",
+    "AMBIGUOUS_CODE",
+    "retry_invalid_policy",
+    "retry_unsafe_method",
+    "stealth_cookie_store_serialize_failed",
+    "response_too_large",
+    "transport_stream_unavailable",
+    "transport_invalid_method",
+    "http_transport_override_unsupported",
+    "http_redirect_policy_invalid",
+    "http_redirect_stopped",
+    "http_redirect_max_hops",
+    "http_redirect_missing_location",
+    "http_redirect_loop",
+    "transport_invalid_url",
+    "retry_exhausted",
+    "auth_abort_unsafe_data",
+    "credentials_auth_missing_credential_keys",
+    "credentials_auth_missing_credential",
+    "credentials_auth_invalid_login_result",
+    "credentials_auth_unknown_challenge",
+    "credentials_auth_unknown_pending_challenge",
+    "STATEFUL_FORWARDING_NOT_CONFIGURED",
+    "STATEFUL_FORWARDING_SIGNATURE_MISSING",
+    "STATEFUL_FORWARDING_NONCE_INVALID",
+    "STATEFUL_FORWARDING_TIMESTAMP_INVALID",
+    "STATEFUL_FORWARDING_SIGNATURE_INVALID",
+    "STATEFUL_FORWARDING_REPLAY_DETECTED",
+    "STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+    "STATEFUL_FORWARDING_ENVELOPE_INVALID",
+    "STATEFUL_FORWARDING_PROVIDER_MISMATCH",
+    "STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+    "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+    "STATEFUL_FORWARDING_REQUEST_FAILED",
+    "STATEFUL_FORWARDING_CONTEXT_MISSING",
+    "STATEFUL_FORWARDING_BAD_RESPONSE",
+    "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+    "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+    "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+    "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+    "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+    "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+]);
 function extractRequestId(raw) {
     if (!raw || typeof raw !== "object") {
         return undefined;
@@ -530,7 +669,12 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
                 : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = isProviderError(error) ? providerObservabilityDetails(error) : undefined;
+    const details = errorObservabilityDetails(error);
+    const isUnregisteredProviderErrorCode = status === 500 &&
+        isProviderError(error) &&
+        !isValidationError(error) &&
+        typeof error.code === "string" &&
+        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -544,15 +688,12 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
-        ...(isTransportError(error) && error.upstreamStatus
-            ? { upstreamStatus: error.upstreamStatus }
-            : {}),
-        ...(details
-            ? {
-                errorCategory: details.category,
-                taxonomyVersion: details.taxonomyVersion,
-                retryable: details.retryable,
-            }
+        ...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
+        errorCategory: details.category,
+        taxonomyVersion: details.taxonomyVersion,
+        retryable: details.retryable,
+        ...(isUnregisteredProviderErrorCode
+            ? { signal: "unregistered_provider_error_code" }
             : {}),
         ...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
     });
@@ -1150,12 +1291,10 @@ export function createServerApp(provider, options = {}) {
             missingSecrets: missingSecretsAtBoot,
         });
     }
-    app.notFound((c) => c.json({
-        error: {
-            code: "not_found",
-            message: "Not found",
-        },
-    }, 404));
+    app.notFound((c) => {
+        const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+        return responseWithErrorObservability(c.json(toErrorResponse(error), 404), error);
+    });
     app.get("/health", (c) => c.json({
         status: "ok",
         provider: provider.id,
@@ -1272,7 +1411,7 @@ export function createServerApp(provider, options = {}) {
             }
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/v1/:operation", async (c) => {
@@ -1306,7 +1445,7 @@ export function createServerApp(provider, options = {}) {
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/start", async (c) => {
@@ -1326,7 +1465,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "start", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/continue", async (c) => {
@@ -1346,7 +1485,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "continue", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/poll", async (c) => {
@@ -1366,7 +1505,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "poll", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/refresh", async (c) => {
@@ -1386,7 +1525,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "refresh", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/disconnect", async (c) => {
@@ -1406,7 +1545,7 @@ export function createServerApp(provider, options = {}) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
             logProviderError(logger, provider, "auth", "disconnect", requestId, error, status, finishRequestCost(requestCost));
-            return c.json(toErrorResponse(error, requestId), status);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     return app;

package/dist/server/types.d.ts

@@ -42,6 +42,7 @@ export declare const ErrorEnvelopeSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
     requestId: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodBoolean;
     fix: z.ZodOptional<z.ZodString>;
     details: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
@@ -84,6 +85,7 @@ export declare const OperationErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
@@ -121,6 +123,7 @@ export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;

package/dist/server/types.js

@@ -21,6 +21,7 @@ export const ErrorEnvelopeSchema = z.object({
     code: z.string(),
     message: z.string(),
     requestId: z.string().optional(),
+    retryable: z.boolean(),
     fix: z.string().optional(),
     details: z.unknown().optional(),
 });

package/dist/stateful/stateful-provider-owner-forwarder.js

@@ -9,6 +9,14 @@ export const STATEFUL_FORWARDING_NONCE_HEADER = "x-apifuse-stateful-nonce";
 export const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
 const MAX_FORWARDED_HEADERS = 32;
 const MAX_FORWARDED_HEADER_BYTES = 8 * 1024;
+// Inbound compatibility boundary for rolling deploys: older owner pods omit
+// top-level retryable. Emitted responses remain strict via
+// OperationErrorResponseSchema.
+const ForwardedOperationErrorResponseSchema = OperationErrorResponseSchema.extend({
+    error: OperationErrorResponseSchema.shape.error.extend({
+        retryable: z.boolean().optional().default(false),
+    }),
+});
 const SENSITIVE_HEADER_NAMES = new Set([
     "authorization",
     "cookie",
@@ -183,7 +191,7 @@ async function parseForwardedResponse(response) {
     if (response.ok && success.success) {
         return { output: success.data.data };
     }
-    const error = OperationErrorResponseSchema.safeParse(body);
+    const error = ForwardedOperationErrorResponseSchema.safeParse(body);
     if (error.success) {
         throw new StatefulOwnerForwardingError({
             code: error.data.error.code,

package/dist/testing/run.js

@@ -3,6 +3,7 @@ import { createProviderCache } from "../runtime/cache.js";
 import { createTestProviderChoiceContext } from "../runtime/choice.js";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
 import { createUnsupportedSttClient } from "../runtime/stt.js";
+import { createNativeEgressAuthorization, NativeNetworkError, snapshotNativeConnectInput, snapshotNativeGrantInput, } from "../runtime/native-network.js";
 import { safeParseSchemaSync } from "../schema.js";
 import { requestPathForFixture } from "../fixture-sanitization.js";
 import { findStreamCaptureGroup, replayStreamEvidence } from "../stream-evidence.js";
@@ -183,6 +184,14 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
     };
     const request = { headers: {} };
     const state = createMemoryProviderRuntimeState();
+    const nativeEgress = provider.native
+        ? createNativeEgressAuthorization({ egress: provider.native.network })
+        : undefined;
+    const requireNativeEgress = () => {
+        if (!nativeEgress)
+            throw new NativeNetworkError("Native egress authorization is unavailable", "native_egress_policy_invalid");
+        return nativeEgress;
+    };
     const dispatch = async (call) => {
         const canned = await upstreamStub({ operationName, ...call });
         if (canned === undefined) {
@@ -353,19 +362,29 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
             ? {
                 native: {
                     network: {
-                        connectTcp: async (options) => createNativeConnection(await dispatch({
-                            transport: "native",
-                            method: "connectTcp",
-                            url: `tcp://${options.host}:${options.port}`,
-                            options,
-                        }), dispatch, `tcp://${options.host}:${options.port}`),
-                        connectTls: async (options) => createNativeConnection(await dispatch({
-                            transport: "native",
-                            method: "connectTls",
-                            url: `tls://${options.host}:${options.port}`,
-                            options,
-                        }), dispatch, `tls://${options.host}:${options.port}`),
-                        grantTcpEgress: () => ({ revoke: () => { } }),
+                        connectTcp: async (options) => {
+                            const request = snapshotNativeConnectInput(options);
+                            requireNativeEgress().assertConnect(request, "disabled");
+                            return createNativeConnection(await dispatch({
+                                transport: "native",
+                                method: "connectTcp",
+                                url: `tcp://${request.host}:${request.port}`,
+                                options: request,
+                            }), dispatch, `tcp://${request.host}:${request.port}`);
+                        },
+                        connectTls: async (options) => {
+                            const request = snapshotNativeConnectInput(options);
+                            requireNativeEgress().assertConnect(request, "required");
+                            return createNativeConnection(await dispatch({
+                                transport: "native",
+                                method: "connectTls",
+                                url: `tls://${request.host}:${request.port}`,
+                                options: request,
+                            }), dispatch, `tls://${request.host}:${request.port}`);
+                        },
+                        grantTcpEgress: (input) => {
+                            return requireNativeEgress().grant(snapshotNativeGrantInput(input));
+                        },
                     },
                 },
             }

package/dist/types.d.ts

@@ -859,9 +859,24 @@ export interface RequestOptions {
      */
     throwOnHttpError?: boolean;
     retry?: boolean | HttpRetryPreset | HttpRetryOptions;
+    /**
+     * Opt-in redirect-hop enforcement for ctx.http. When present, redirects are
+     * evaluated before the next request is issued. Existing callers that omit
+     * this policy retain the native fetch redirect behavior.
+     */
+    redirectPolicy?: HttpRedirectPolicy;
 }
+export type RedirectRunReason = "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+export type HttpRedirectPolicyMode = "same-origin";
+export interface HttpRedirectPolicy {
+    /** Only follow redirects whose canonical scheme, host, and port match the initial URL. */
+    mode: HttpRedirectPolicyMode;
+    /** Maximum number of redirect hops that may be followed. Must be an integer from 0 to 20. */
+    maxHops: number;
+}
+export type HttpRedirectFailureReason = Exclude<RedirectRunReason, "completed">;
 export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
-export interface StealthFetchOptions extends RequestOptions {
+export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy"> {
     method?: HttpMethod;
     body?: string | Buffer;
     redirect?: "follow" | "manual" | "error";
@@ -967,7 +982,7 @@ export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "re
 export interface StealthRedirectRunResult {
     final: StealthResponse;
     hops: StealthRedirectHop[];
-    reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    reason: RedirectRunReason;
     /**
      * Complete flat view across all redirect hosts. Attributes and duplicate names are lost.
      * @deprecated Use cookieStore for lossless persistence.
@@ -1072,6 +1087,12 @@ export interface NativeTcpEgressRule {
 /**
  * Bounded native TCP egress discovered through a declared bootstrap endpoint.
  * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ *
+ * Dynamic rules are ordered. The first rule whose source, target, port, and TLS
+ * selectors match exclusively owns the grant; its ttlMs and maxGrants bounds
+ * apply, and an exhausted/shorter rule never falls through to a later overlap.
+ * Every rule must declare a source host selector, source port list/range, and
+ * target port list/range; omitted ttlMs/maxGrants remain unbounded.
  */
 export interface NativeTcpDynamicEgressRule {
     readonly sourceHost?: string;

package/package.json

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

package/src/define.ts

@@ -1,6 +1,10 @@
 import ms from "ms";
 
 import { ProviderError, ValidationError } from "./errors.js";
+import {
+	NativeEgressPolicyValidationError,
+	validateNativeProviderConfig,
+} from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
 import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
 import type {
@@ -2204,6 +2208,13 @@ export function defineProvider<
 	);
 	validateOperationFixtures(config.id, operations);
 	validateProviderDeployment(config.id, config.deployment);
+	try {
+		validateNativeProviderConfig(config.native);
+	} catch (error) {
+		if (error instanceof NativeEgressPolicyValidationError)
+			throw new ValidationError(error.message);
+		throw error;
+	}
 	validateProviderProxy(config);
 	validateProviderStt(config);
 	if (config.runtime === "browser" && !config.browser)