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

package/src/error-resolution.ts

@@ -0,0 +1,91 @@
+// This set suppresses the unregistered-provider-error-code signal for codes
+// intentionally emitted by SDK paths. It is not the complete authority for
+// runtime error resolution: branded errors and additional canonical SDK codes
+// must also remain immune to provider-declared status/retryability overrides.
+export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+	"MISSING_SECRET",
+	"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",
+]);
+
+// Complete code authority for provider-declared runtime resolution. Keep this
+// separate from signal suppression: declarations may document these codes, but
+// their status and retryability can never override the SDK's canonical result.
+export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
+	...SDK_OWNED_PROVIDER_ERROR_CODES,
+	"reauth_required",
+	"STT_UNAVAILABLE",
+	"UNSUPPORTED_STT_BACKEND",
+	"OUTPUT_VALIDATION_FAILED",
+	"NOT_FOUND",
+	"not_found",
+]);

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,
@@ -225,6 +230,7 @@ export type {
 	OperationDeprecationMetadata,
 	OperationDocMeta,
 	OperationErrorCode,
+	ProviderErrorStatus,
 	OperationHandlerResult,
 	OperationInputExample,
 	OperationLifecycle,
@@ -280,6 +286,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,
@@ -119,6 +123,7 @@ export type {
 	OperationDefinition,
 	OperationDocMeta,
 	OperationErrorCode,
+	ProviderErrorStatus,
 	OperationInputExample,
 	OperationLifecycle,
 	OperationObservabilityConfig,
@@ -150,6 +155,7 @@ export type {
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderSupportLevel,
+	RedirectRunReason,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
 	StandardSchemaV1,
@@ -161,6 +167,8 @@ export type {
 export {
 	createNativeNetworkClient,
 	deriveNativeCredentialAffinityKey,
+	NativeEgressGrantExpiredError,
+	NativeEgressNotDeclaredError,
 	NativeIdleTimeoutError,
 	NativeNetworkError,
 	NativeProxyExpiredError,