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

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.14",
+	"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)

package/src/errors.ts

@@ -1,4 +1,5 @@
 import type { ProviderErrorCategory } from "./observability.js";
+import type { HttpRedirectFailureReason } from "./types.js";
 
 // Versioned, cross-realm brands. `Symbol.for` resolves to the same symbol in
 // any copy/entrypoint of this SDK major version, so an error created by a
@@ -148,6 +149,33 @@ export class TransportError extends ProviderError {
 	}
 }
 
+export type HttpRedirectErrorOptions = TransportErrorOptions & {
+	reason: HttpRedirectFailureReason;
+	/** Redacted redirect target suitable for provider diagnostics. */
+	target?: string;
+};
+
+/** Raised when an opt-in ctx.http redirect policy refuses or cannot resolve a hop. */
+export class HttpRedirectError extends TransportError {
+	readonly reason: HttpRedirectFailureReason;
+	readonly target?: string;
+
+	constructor(message: string, options: HttpRedirectErrorOptions) {
+		const { reason, target, ...transportOptions } = options;
+		super(message, {
+			...transportOptions,
+			code: `http_redirect_${reason}`,
+			details: {
+				reason,
+				...(target ? { target } : {}),
+			},
+		});
+		this.name = "HttpRedirectError";
+		this.reason = reason;
+		this.target = target;
+	}
+}
+
 // Cross-module type guards. Prefer these over `instanceof` at any boundary that
 // may receive an error from a different copy/entrypoint of the SDK (see the HTTP
 // server error boundary). They recognize branded errors regardless of which

package/src/index.ts

@@ -73,6 +73,8 @@ export { createHttpClient } from "./runtime/http.js";
 export {
 	createNativeNetworkClient,
 	deriveNativeCredentialAffinityKey,
+	NativeEgressGrantExpiredError,
+	NativeEgressNotDeclaredError,
 	NativeIdleTimeoutError,
 	NativeNetworkError,
 	NativeProxyExpiredError,
@@ -189,6 +191,9 @@ export type {
 	HealthJourneyStep,
 	HttpClient,
 	HttpMethod,
+	HttpRedirectFailureReason,
+	HttpRedirectPolicy,
+	HttpRedirectPolicyMode,
 	HttpResponse,
 	HttpRetryOptions,
 	HttpRetrySummary,
@@ -280,6 +285,7 @@ export type {
 	ProviderSttMode,
 	ProviderSupportLevel,
 	RequestOptions,
+	RedirectRunReason,
 	Rfc3339Instant,
 	SchemaLike,
 	SmsOrigin,

package/src/native-egress-policy.ts

@@ -0,0 +1,285 @@
+import type {
+	NativeProviderConfig,
+	NativeTcpDynamicEgressRule,
+	NativeTcpEgressRule,
+	NativeTcpPortRange,
+	NativeTcpTlsMode,
+} from "./types.js";
+
+type NativeNetworkDeclaration = NonNullable<NativeProviderConfig["network"]>;
+
+const NATIVE_PROVIDER_FIELD_RECORD = {
+	network: true,
+} satisfies { readonly [K in keyof Required<NativeProviderConfig>]: true };
+const NATIVE_NETWORK_FIELD_RECORD = {
+	tcp: true,
+	dynamicTcp: true,
+} satisfies { readonly [K in keyof Required<NativeNetworkDeclaration>]: true };
+const NATIVE_TCP_RULE_FIELD_RECORD = {
+	host: true,
+	ports: true,
+	tls: true,
+} satisfies { readonly [K in keyof Required<NativeTcpEgressRule>]: true };
+const NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD = {
+	sourceHost: true,
+	sourceHostSuffixes: true,
+	sourcePorts: true,
+	sourcePortRanges: true,
+	targetHostSuffixes: true,
+	targetPorts: true,
+	targetPortRanges: true,
+	tls: true,
+	ttlMs: true,
+	maxGrants: true,
+} satisfies { readonly [K in keyof Required<NativeTcpDynamicEgressRule>]: true };
+const NATIVE_TCP_PORT_RANGE_FIELD_RECORD = {
+	start: true,
+	end: true,
+} satisfies { readonly [K in keyof Required<NativeTcpPortRange>]: true };
+
+const NATIVE_PROVIDER_FIELDS = Object.keys(NATIVE_PROVIDER_FIELD_RECORD);
+const NATIVE_NETWORK_FIELDS = Object.keys(NATIVE_NETWORK_FIELD_RECORD);
+const NATIVE_TCP_RULE_FIELDS = Object.keys(NATIVE_TCP_RULE_FIELD_RECORD);
+const NATIVE_DYNAMIC_TCP_RULE_FIELDS = Object.keys(NATIVE_DYNAMIC_TCP_RULE_FIELD_RECORD);
+const NATIVE_TCP_PORT_RANGE_FIELDS = Object.keys(NATIVE_TCP_PORT_RANGE_FIELD_RECORD);
+
+export type StaticEgressRuleSnapshot = {
+	readonly host: string;
+	readonly ports: readonly number[];
+	readonly tls: NativeTcpTlsMode;
+};
+
+export type DynamicEgressRuleSnapshot = {
+	readonly sourceHost?: string;
+	readonly sourceHostSuffixes: readonly string[];
+	readonly sourcePorts: readonly number[];
+	readonly sourcePortRanges: readonly NativeTcpPortRange[];
+	readonly targetHostSuffixes: readonly string[];
+	readonly targetPorts: readonly number[];
+	readonly targetPortRanges: readonly NativeTcpPortRange[];
+	readonly tls: NativeTcpTlsMode;
+	readonly ttlMs?: number;
+	readonly maxGrants?: number;
+};
+
+export type NativeEgressPolicySnapshot = {
+	readonly staticRules: readonly StaticEgressRuleSnapshot[];
+	readonly dynamicRules: readonly DynamicEgressRuleSnapshot[];
+};
+
+export class NativeEgressPolicyValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "NativeEgressPolicyValidationError";
+	}
+}
+
+function fail(message: string): never {
+	throw new NativeEgressPolicyValidationError(message);
+}
+
+function dataRecord(
+	value: unknown,
+	fieldPath: string,
+	allowed: readonly string[],
+): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		fail(`${fieldPath} must be an object`);
+	const prototype = Reflect.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null)
+		fail(`${fieldPath} must be a plain object`);
+	const record: Record<string, unknown> = {};
+	for (const key of Reflect.ownKeys(value)) {
+		if (typeof key !== "string") fail(`${fieldPath} must not contain symbol fields`);
+		if (!allowed.includes(key)) fail(`Unknown field ${fieldPath}.${key}`);
+		const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+		if (!descriptor || !("value" in descriptor)) fail(`${fieldPath}.${key} must be a data field`);
+		record[key] = descriptor.value;
+	}
+	return record;
+}
+
+function dataArray(value: unknown, fieldPath: string): readonly unknown[] {
+	if (!Array.isArray(value)) fail(`${fieldPath} must be an array`);
+	const result: unknown[] = [];
+	for (const key of Reflect.ownKeys(value)) {
+		if (key === "length") continue;
+		if (typeof key !== "string" || !/^(?:0|[1-9]\d*)$/.test(key))
+			fail(`${fieldPath} must not contain non-index fields`);
+		const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+		if (!descriptor || !("value" in descriptor)) fail(`${fieldPath}[${key}] must be a data field`);
+		result[Number(key)] = descriptor.value;
+	}
+	if (result.length !== value.length) fail(`${fieldPath} must not be sparse`);
+	for (let index = 0; index < result.length; index += 1) {
+		if (!(index in result)) fail(`${fieldPath} must not be sparse`);
+	}
+	return result;
+}
+
+function hasControlCharacter(value: string): boolean {
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+
+function host(value: unknown, fieldPath: string, suffix = false): string {
+	if (
+		typeof value !== "string" ||
+		!value.trim() ||
+		hasControlCharacter(value) ||
+		/\s/.test(value) ||
+		value.includes("://")
+	)
+		fail(`${fieldPath} must be a non-empty hostname`);
+	if (value.includes("*"))
+		fail(`${fieldPath} must be an exact ${suffix ? "DNS suffix" : "hostname"}, not a wildcard`);
+	const normalized = value.trim().toLowerCase().replace(/\.$/, "");
+	if (!normalized) fail(`${fieldPath} must be a non-empty hostname`);
+	return normalized;
+}
+
+function port(value: unknown, fieldPath: string): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > 65_535)
+		fail(`${fieldPath} must be an integer from 1 to 65535`);
+	return value;
+}
+
+function ports(value: unknown, fieldPath: string): readonly number[] {
+	return dataArray(value, fieldPath).map((value, index) => port(value, `${fieldPath}[${index}]`));
+}
+
+function hostSuffixes(value: unknown, fieldPath: string): readonly string[] {
+	return dataArray(value, fieldPath).map((value, index) =>
+		host(value, `${fieldPath}[${index}]`, true),
+	);
+}
+
+function ranges(value: unknown, fieldPath: string): readonly NativeTcpPortRange[] {
+	return dataArray(value, fieldPath).map((value, index) => {
+		const rangePath = `${fieldPath}[${index}]`;
+		const record = dataRecord(value, rangePath, NATIVE_TCP_PORT_RANGE_FIELDS);
+		const start = port(record.start, `${rangePath}.start`);
+		const end = port(record.end, `${rangePath}.end`);
+		if (start > end) fail(`${rangePath}.start must not exceed end`);
+		return { start, end };
+	});
+}
+
+function tls(value: unknown, fieldPath: string): NativeTcpTlsMode {
+	if (value !== "required" && value !== "allowed" && value !== "disabled")
+		fail(`${fieldPath} must be required, allowed, or disabled`);
+	return value;
+}
+
+function positiveInteger(value: unknown, fieldPath: string): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+		fail(`${fieldPath} must be a positive integer`);
+	return value;
+}
+
+export function parseNativeEgressPolicy(value: unknown): NativeEgressPolicySnapshot {
+	try {
+		const policy = dataRecord(value, "native.network", NATIVE_NETWORK_FIELDS);
+		const staticRules =
+			policy.tcp === undefined
+				? []
+				: dataArray(policy.tcp, "native.network.tcp").map((value, index) => {
+						const fieldPath = `native.network.tcp[${index}]`;
+						const rule = dataRecord(value, fieldPath, NATIVE_TCP_RULE_FIELDS);
+						const declaredPorts = ports(rule.ports, `${fieldPath}.ports`);
+						if (declaredPorts.length === 0) fail(`${fieldPath}.ports must not be empty`);
+						return {
+							host: host(rule.host, `${fieldPath}.host`),
+							ports: declaredPorts,
+							tls: tls(rule.tls, `${fieldPath}.tls`),
+						};
+					});
+		const dynamicRules =
+			policy.dynamicTcp === undefined
+				? []
+				: dataArray(policy.dynamicTcp, "native.network.dynamicTcp").map((value, index) => {
+						const fieldPath = `native.network.dynamicTcp[${index}]`;
+						const rule = dataRecord(value, fieldPath, NATIVE_DYNAMIC_TCP_RULE_FIELDS);
+						const sourceHost =
+							rule.sourceHost === undefined
+								? undefined
+								: host(rule.sourceHost, `${fieldPath}.sourceHost`);
+						const sourceHostSuffixes =
+							rule.sourceHostSuffixes === undefined
+								? []
+								: hostSuffixes(rule.sourceHostSuffixes, `${fieldPath}.sourceHostSuffixes`);
+						if (sourceHost === undefined && sourceHostSuffixes.length === 0)
+							fail(
+								`${fieldPath} must declare sourceHost or a non-empty sourceHostSuffixes list`,
+							);
+						const sourcePorts =
+							rule.sourcePorts === undefined
+								? []
+								: ports(rule.sourcePorts, `${fieldPath}.sourcePorts`);
+						const sourcePortRanges =
+							rule.sourcePortRanges === undefined
+								? []
+								: ranges(rule.sourcePortRanges, `${fieldPath}.sourcePortRanges`);
+						if (sourcePorts.length === 0 && sourcePortRanges.length === 0)
+							fail(
+								`${fieldPath} must declare a non-empty sourcePorts or sourcePortRanges list`,
+							);
+						const targetHostSuffixes = hostSuffixes(
+							rule.targetHostSuffixes,
+							`${fieldPath}.targetHostSuffixes`,
+						);
+						if (targetHostSuffixes.length === 0)
+							fail(`${fieldPath}.targetHostSuffixes must not be empty`);
+						const targetPorts =
+							rule.targetPorts === undefined
+								? []
+								: ports(rule.targetPorts, `${fieldPath}.targetPorts`);
+						const targetPortRanges =
+							rule.targetPortRanges === undefined
+								? []
+								: ranges(rule.targetPortRanges, `${fieldPath}.targetPortRanges`);
+						if (targetPorts.length === 0 && targetPortRanges.length === 0)
+							fail(
+								`${fieldPath} must declare a non-empty targetPorts or targetPortRanges list`,
+							);
+						return {
+							...(sourceHost === undefined ? {} : { sourceHost }),
+							sourceHostSuffixes,
+							sourcePorts,
+							sourcePortRanges,
+							targetHostSuffixes,
+							targetPorts,
+							targetPortRanges,
+							tls: tls(rule.tls, `${fieldPath}.tls`),
+							...(rule.ttlMs === undefined
+								? {}
+								: { ttlMs: positiveInteger(rule.ttlMs, `${fieldPath}.ttlMs`) }),
+							...(rule.maxGrants === undefined
+								? {}
+								: { maxGrants: positiveInteger(rule.maxGrants, `${fieldPath}.maxGrants`) }),
+						};
+					});
+		return { staticRules, dynamicRules };
+	} catch (error) {
+		if (error instanceof NativeEgressPolicyValidationError) throw error;
+		throw new NativeEgressPolicyValidationError(
+			"Native egress policy could not be inspected safely",
+		);
+	}
+}
+
+export function validateNativeProviderConfig(value: unknown): void {
+	if (value === undefined) return;
+	try {
+		const native = dataRecord(value, "native", NATIVE_PROVIDER_FIELDS);
+		if (native.network !== undefined) parseNativeEgressPolicy(native.network);
+	} catch (error) {
+		if (error instanceof NativeEgressPolicyValidationError) throw error;
+		throw new NativeEgressPolicyValidationError(
+			"Native provider config could not be inspected safely",
+		);
+	}
+}

package/src/provider.ts

@@ -37,6 +37,7 @@ export {
 } from "./define.js";
 export {
 	AuthError,
+	HttpRedirectError,
 	isProviderError,
 	isSessionExpiredError,
 	isTransportError,
@@ -91,6 +92,9 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthScheduleRandomization,
+	HttpRedirectFailureReason,
+	HttpRedirectPolicy,
+	HttpRedirectPolicyMode,
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,
@@ -150,6 +154,7 @@ export type {
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderSupportLevel,
+	RedirectRunReason,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
 	StandardSchemaV1,
@@ -161,6 +166,8 @@ export type {
 export {
 	createNativeNetworkClient,
 	deriveNativeCredentialAffinityKey,
+	NativeEgressGrantExpiredError,
+	NativeEgressNotDeclaredError,
 	NativeIdleTimeoutError,
 	NativeNetworkError,
 	NativeProxyExpiredError,