@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/src/dev.ts

@@ -1,9 +1,12 @@
 import { serve } from "./server/serve.js";
+import type { ProviderEngine } from "./engine.js";
 import type { ProviderDefinition } from "./types.js";
 
 export interface DevServerOptions {
 	port?: number;
 	sessionDbPath?: string;
+	/** Override the default in-process engine attachment. */
+	engine?: ProviderEngine;
 }
 
 export function createDevServer(
@@ -14,7 +17,7 @@ export function createDevServer(
 
 	return {
 		start: () => {
-			void serve(provider, { port });
+			void serve(provider, { port, engine: options?.engine });
 			console.log(
 				`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`,
 			);

package/src/engine.ts

@@ -0,0 +1,279 @@
+import { ProviderError } from "./errors.js";
+import {
+	OTEL_EXPORTER_OTLP_ENDPOINT,
+	OTEL_EXPORTER_OTLP_HEADERS,
+	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+	OTEL_EXPORTER_OTLP_TRACES_HEADERS,
+	OTEL_RESOURCE_ATTRIBUTES,
+	OTEL_SERVICE_NAME,
+} from "./runtime/otlp.js";
+import type {
+	AuthContext,
+	BrowserClient,
+	CredentialContext,
+	EnvContext,
+	HttpClient,
+	NativeContext,
+	OcrContext,
+	ProviderCache,
+	ProviderChoiceContext,
+	ProviderContext,
+	ProviderDefinition,
+	ProviderFilesContext,
+	ProviderRequestContext,
+	ProviderRuntimeState,
+	ResolverContext,
+	StealthClient,
+	SttContext,
+	TraceContext,
+} from "./types.js";
+
+/** Versioned envelope protocol used by out-of-process engine transports. */
+export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1" as const;
+
+/** Credential names owned by the engine and forbidden in provider declarations. */
+export const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES = [
+	"APIFUSE__PROXY__SMARTPROXY_APP_KEY",
+	"APIFUSE__PROXY__NODEMAVEN_USERNAME",
+	"APIFUSE__PROXY__NODEMAVEN_PASSWORD",
+] as const;
+
+const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET = new Set<string>(
+	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+);
+
+/**
+ * Environment names are compared case-insensitively: Windows resolves `otel_exporter_otlp_headers`
+ * to the same variable as `OTEL_EXPORTER_OTLP_HEADERS`, so a mixed-case alias must be treated as
+ * the engine-owned name it resolves to.
+ */
+function canonicalEnvName(name: string): string {
+	return name.toUpperCase();
+}
+
+export function isEngineOwnedProxyCredentialName(name: string): boolean {
+	return ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET.has(canonicalEnvName(name));
+}
+
+/**
+ * Trace-export configuration owned by the engine and forbidden in provider
+ * declarations. The header variables carry collector credentials; the rest are
+ * engine deployment settings a provider has no reason to read.
+ */
+export const ENGINE_OWNED_TELEMETRY_ENV_NAMES = [
+	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
+	OTEL_EXPORTER_OTLP_ENDPOINT,
+	OTEL_EXPORTER_OTLP_TRACES_HEADERS,
+	OTEL_EXPORTER_OTLP_HEADERS,
+	OTEL_SERVICE_NAME,
+	OTEL_RESOURCE_ATTRIBUTES,
+] as const;
+
+const ENGINE_OWNED_TELEMETRY_ENV_NAME_SET = new Set<string>(ENGINE_OWNED_TELEMETRY_ENV_NAMES);
+
+export function isEngineOwnedTelemetryEnvName(name: string): boolean {
+	return ENGINE_OWNED_TELEMETRY_ENV_NAME_SET.has(canonicalEnvName(name));
+}
+
+/** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
+export function isEngineOwnedEnvName(name: string): boolean {
+	return isEngineOwnedProxyCredentialName(name) || isEngineOwnedTelemetryEnvName(name);
+}
+
+/** Capture credentials in the engine host before constructing provider bindings. */
+export function readEngineProxyCredentials(
+	environment: Readonly<Record<string, string | undefined>> = process.env,
+): Readonly<Record<string, string>> {
+	return Object.fromEntries(
+		ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES.flatMap((name) => {
+			const value = environment[name]?.trim();
+			return value ? [[name, value] as const] : [];
+		}),
+	);
+}
+
+/** Build the exact environment projection permitted to enter a provider runtime. */
+export function createProviderEnvironment(
+	environment: Readonly<Record<string, string | undefined>>,
+	declaredNames: readonly string[],
+): Readonly<Record<string, string>> {
+	return Object.fromEntries(
+		declaredNames.flatMap((name) => {
+			if (isEngineOwnedEnvName(name)) return [];
+			const value = environment[name];
+			return value === undefined ? [] : [[name, value] as const];
+		}),
+	);
+}
+
+/**
+ * Request/response is the first remote transport lane. Stream and session
+ * handles are separate lanes so lifecycle-bearing capabilities are never
+ * disguised as ordinary JSON calls.
+ */
+export interface ProviderEngineTransport {
+	request<TResponse = unknown>(request: ProviderEngineRequest): Promise<TResponse>;
+	openStream?(request: ProviderEngineRequest): Promise<ReadableStream<Uint8Array>>;
+	openSession?(request: ProviderEngineRequest): Promise<ProviderEngineSession>;
+}
+
+export interface ProviderEngineRequest {
+	readonly version: typeof PROVIDER_ENGINE_PROTOCOL_VERSION;
+	readonly providerId: string;
+	readonly requestId: string;
+	readonly capability: ProviderCapabilityKey;
+	readonly method: string;
+	readonly payload: unknown;
+}
+
+export interface ProviderEngineSession {
+	request<TResponse = unknown>(method: string, payload: unknown): Promise<TResponse>;
+	close(): Promise<void>;
+}
+
+/** Capability implementations owned by the engine rather than provider code. */
+export interface ProviderEngineCapabilitySurface {
+	readonly http: HttpClient;
+	readonly browser: BrowserClient;
+	readonly stealth: StealthClient;
+	readonly stt: SttContext;
+	readonly ocr: OcrContext;
+	readonly resolver: ResolverContext;
+	readonly cache: ProviderCache;
+	readonly state: ProviderRuntimeState;
+}
+
+/** Engine-resident-only capabilities, kept separate from the portable surface. */
+export interface ProviderEngineResidentSurface {
+	readonly native: NativeContext;
+}
+
+export const PROVIDER_CAPABILITY_KEYS = [
+	"env",
+	"credential",
+	"http",
+	"files",
+	"native",
+	"cache",
+	"state",
+	"stealth",
+	"browser",
+	"auth",
+	"ocr",
+	"stt",
+	"resolver",
+	"choice",
+] as const;
+
+export type ProviderCapabilityKey = (typeof PROVIDER_CAPABILITY_KEYS)[number];
+
+export type ProviderEngineBindingCandidates = Partial<
+	ProviderEngineCapabilitySurface &
+		ProviderEngineResidentSurface & {
+			readonly env: EnvContext;
+			readonly credential: CredentialContext;
+			readonly files: ProviderFilesContext;
+			readonly auth: AuthContext;
+			readonly choice: ProviderChoiceContext;
+		}
+> & {
+	readonly request?: ProviderRequestContext;
+	readonly trace: TraceContext;
+};
+
+export interface ProviderEngineAttachmentInput {
+	readonly provider: ProviderDefinition;
+	readonly bindings: ProviderEngineBindingCandidates;
+}
+
+/** Attachment boundary shared by in-process development and remote RPC bridges. */
+export interface ProviderEngine {
+	attach<TDeclaration extends object = Record<string, unknown>>(
+		input: ProviderEngineAttachmentInput,
+	): ProviderContext<TDeclaration>;
+}
+
+const CAPABILITY_KEY_SET = new Set<string>(PROVIDER_CAPABILITY_KEYS);
+
+function declaresCapability(
+	provider: ProviderDefinition,
+	capability: ProviderCapabilityKey,
+): boolean {
+	return Object.hasOwn(provider, capability) && provider[capability] !== undefined;
+}
+
+function attachmentError(
+	provider: ProviderDefinition,
+	capability: ProviderCapabilityKey,
+): ProviderError {
+	return new ProviderError(
+		`Provider engine could not attach declared capability "${capability}" for provider "${provider.id}"`,
+		{
+			code: "PROVIDER_ENGINE_ATTACHMENT_FAILED",
+			details: { providerId: provider.id, capability },
+			fix: `Configure the engine binding for "${capability}" before starting the provider.`,
+		},
+	);
+}
+
+function undeclaredCapabilityError(
+	provider: ProviderDefinition,
+	capability: ProviderCapabilityKey,
+): ProviderError {
+	return new ProviderError(
+		`Provider "${provider.id}" accessed undeclared capability "${capability}"; add the "${capability}" declaration`,
+		{
+			code: "PROVIDER_CAPABILITY_UNDECLARED",
+			details: { providerId: provider.id, capability },
+			fix: `Add ${capability}: {} to the provider declaration, or remove the access.`,
+		},
+	);
+}
+
+function attachInProcess<TDeclaration extends object>(
+	input: ProviderEngineAttachmentInput,
+): ProviderContext<TDeclaration> {
+	const { provider, bindings } = input;
+	if (provider.runtimeTarget === "vanilla" && declaresCapability(provider, "native")) {
+		throw new ProviderError(
+			`Provider "${provider.id}" cannot attach capability "native" to runtime target "vanilla"; native requires an engine-resident runtime`,
+			{
+				code: "PROVIDER_RUNTIME_CAPABILITY_CONFLICT",
+				details: { providerId: provider.id, capability: "native", runtimeTarget: "vanilla" },
+			},
+		);
+	}
+
+	const context: Record<PropertyKey, unknown> = { trace: bindings.trace };
+	if (bindings.request !== undefined) context.request = bindings.request;
+	for (const capability of PROVIDER_CAPABILITY_KEYS) {
+		if (!declaresCapability(provider, capability)) continue;
+		const binding = bindings[capability];
+		if (binding === undefined || binding === null) throw attachmentError(provider, capability);
+		context[capability] = binding;
+	}
+
+	return new Proxy(context, {
+		get(target, property, receiver) {
+			if (
+				typeof property === "string" &&
+				CAPABILITY_KEY_SET.has(property) &&
+				!declaresCapability(provider, property as ProviderCapabilityKey)
+			) {
+				throw undeclaredCapabilityError(provider, property as ProviderCapabilityKey);
+			}
+			return Reflect.get(target, property, receiver);
+		},
+		has(target, property) {
+			if (typeof property === "string" && CAPABILITY_KEY_SET.has(property)) {
+				return declaresCapability(provider, property as ProviderCapabilityKey);
+			}
+			return Reflect.has(target, property);
+		},
+	}) as ProviderContext<TDeclaration>;
+}
+
+/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+export function createInProcessProviderEngine(): ProviderEngine {
+	return { attach: attachInProcess };
+}

package/src/error-observability.ts

@@ -0,0 +1,64 @@
+import { isProviderError, type ProviderErrorObservability } from "./errors.js";
+
+const PROVIDER_OBSERVABILITY_TOKEN_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+const PROVIDER_OBSERVABILITY_FINGERPRINT_PATTERN = /^[A-Fa-f0-9]{12}$/;
+const MAX_PROVIDER_OBSERVABILITY_MESSAGE_LENGTH = 10_000_000;
+
+/**
+ * Extracts only own data properties from branded provider errors. In
+ * particular, descriptor reads reject options/observability accessors without
+ * invoking provider-controlled getters.
+ */
+export function safeProviderErrorObservability(
+	error: unknown,
+): ProviderErrorObservability | undefined {
+	if (!isProviderError(error)) return undefined;
+	let candidate: unknown;
+	let reason: unknown;
+	let fingerprint: unknown;
+	let messageLength: unknown;
+	try {
+		const optionsDescriptor = Object.getOwnPropertyDescriptor(error, "options");
+		if (optionsDescriptor === undefined || !Object.hasOwn(optionsDescriptor, "value")) {
+			return undefined;
+		}
+		const options = optionsDescriptor.value;
+		if (options === null || typeof options !== "object" || Array.isArray(options)) {
+			return undefined;
+		}
+		const observabilityDescriptor = Object.getOwnPropertyDescriptor(options, "observability");
+		if (observabilityDescriptor === undefined || !Object.hasOwn(observabilityDescriptor, "value")) {
+			return undefined;
+		}
+		candidate = observabilityDescriptor.value;
+		if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+			return undefined;
+		}
+		const ownValue = (key: keyof ProviderErrorObservability): unknown => {
+			const descriptor = Object.getOwnPropertyDescriptor(candidate as object, key);
+			return descriptor && Object.hasOwn(descriptor, "value") ? descriptor.value : undefined;
+		};
+		reason = ownValue("reason");
+		fingerprint = ownValue("fingerprint");
+		messageLength = ownValue("messageLength");
+	} catch {
+		return undefined;
+	}
+	const safe: ProviderErrorObservability = {
+		...(typeof reason === "string" && PROVIDER_OBSERVABILITY_TOKEN_PATTERN.test(reason)
+			? { reason }
+			: {}),
+		...(typeof fingerprint === "string" &&
+		PROVIDER_OBSERVABILITY_FINGERPRINT_PATTERN.test(fingerprint)
+			? { fingerprint }
+			: {}),
+		...(typeof messageLength === "number" &&
+		Number.isInteger(messageLength) &&
+		messageLength >= 0 &&
+		messageLength <= MAX_PROVIDER_OBSERVABILITY_MESSAGE_LENGTH
+			? { messageLength }
+			: {}),
+	};
+
+	return Object.keys(safe).length > 0 ? safe : undefined;
+}

package/src/error-resolution.ts

@@ -0,0 +1,127 @@
+import type { ProviderErrorStatus } from "./types.js";
+
+// 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",
+	"OCR_UPSTREAM_FAILED",
+	"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",
+	"OCR_UNAVAILABLE",
+	"UNSUPPORTED_OCR_BACKEND",
+	"STT_UNAVAILABLE",
+	"UNSUPPORTED_STT_BACKEND",
+	"OUTPUT_VALIDATION_FAILED",
+	"NOT_FOUND",
+	"not_found",
+]);
+
+// Canonical SDK status mapping for recognized provider-thrown error codes.
+// serve.ts toStatusCode consults this map (after operation-declared overrides
+// for non-SDK-owned codes), and the authoring lint treats these codes as
+// SDK-registered. Add new codes here instead of duplicating literals in
+// either consumer.
+export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus> =
+	new Map<string, ProviderErrorStatus>([
+		["AUTH_REQUIRED", 401],
+		["reauth_required", 401],
+		// Unprovisioned declared secret: a deployment/config defect, never an
+		// upstream failure — explicit 400.
+		["MISSING_SECRET", 400],
+		["NOT_FOUND", 404],
+		["not_found", 404],
+		["NO_DATA", 404],
+		["RATE_LIMITED", 429],
+		["UPSTREAM_RATE_LIMIT", 429],
+		["LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR", 429],
+		// Deterministic upstream business refusal (honest-provider-error-
+		// contract): the upstream evaluated the request and said no under its
+		// own rules — a conflict with upstream state, never a 5xx.
+		["UPSTREAM_REJECTED", 409],
+		["UPSTREAM_ERROR", 502],
+		["BLOCKED", 502],
+		["OCR_UNAVAILABLE", 503],
+		["UNSUPPORTED_OCR_BACKEND", 503],
+		["STT_UNAVAILABLE", 503],
+		["UNSUPPORTED_STT_BACKEND", 503],
+		["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+	]);

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
@@ -10,6 +11,7 @@ const PROVIDER_ERROR_BRAND = Symbol.for("@apifuse/provider-sdk/error-brand@1");
 const PROVIDER_ERROR_BRAND_VALUE = 1;
 const SESSION_EXPIRED_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/session-expired@1");
 const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
+const VALIDATION_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/validation@1");
 
 // Defines a non-enumerable, non-writable, non-configurable own data property.
 // Immutable + own means a guard can trust it via a single descriptor read
@@ -44,6 +46,22 @@ export type ProviderErrorOptions = {
 	cause?: Error;
 	category?: ProviderErrorCategory;
 	retryable?: boolean;
+	/** Provider-authored, bounded metadata safe for operational logs and error headers. */
+	observability?: ProviderErrorObservability;
+};
+
+/**
+ * Provider-authored error diagnostics whose runtime values are validated before emission.
+ * Classification tokens such as `reason` are source literals, not runtime user input or
+ * credentials. The gateway removes the observability header from tenant responses.
+ */
+export type ProviderErrorObservability = {
+	/** A 1-64 character `[A-Za-z0-9_.-]` classification token, for example `LOGIN_COMPLETE_FAILED`. */
+	reason?: string;
+	/** A provider-computed 12-hex-character fingerprint of private diagnostic input. */
+	fingerprint?: string;
+	/** The non-negative length of the private diagnostic input, capped at 10,000,000. */
+	messageLength?: number;
 };
 
 export class ProviderError extends Error {
@@ -79,6 +97,21 @@ export class SDKError extends ProviderError {
 	}
 }
 
+/** Raised when persisted stealth cookies use a store version this SDK cannot read. */
+export class StealthCookieStoreVersionError extends SDKError {
+	constructor(public readonly version: unknown) {
+		const displayedVersion =
+			typeof version === "string" || typeof version === "number"
+				? String(version)
+				: "missing or invalid";
+		super(`Unsupported stealth cookie store version: ${displayedVersion}`, {
+			code: "unsupported_stealth_cookie_store_version",
+			details: { receivedVersion: version, supportedVersions: [1] },
+		});
+		this.name = "StealthCookieStoreVersionError";
+	}
+}
+
 export class AuthError extends ProviderError {
 	constructor(message: string, options?: ProviderErrorOptions) {
 		super(message, options);
@@ -110,6 +143,7 @@ export class ValidationError extends ProviderError {
 		super(message, options);
 		this.name = "ValidationError";
 		this.zodError = options?.zodError;
+		defineErrorBrand(this, VALIDATION_BRAND, true);
 	}
 }
 
@@ -131,6 +165,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
@@ -147,6 +208,13 @@ export function isTransportError(value: unknown): value is TransportError {
 	return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
 }
 
+export function isValidationError(value: unknown): value is ValidationError {
+	return (
+		isProviderError(value) &&
+		(hasOwnBrand(value, VALIDATION_BRAND, true) || value.name === "ValidationError")
+	);
+}
+
 export class ProviderSecretError extends ProviderError {
 	constructor(message: string, options?: ProviderErrorOptions) {
 		super(message, { code: "provider_secret_error", ...options });