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

package/dist/dev.d.ts

@@ -1,7 +1,10 @@
+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 declare function createDevServer(provider: ProviderDefinition, options?: DevServerOptions): {
     start: () => void;

package/dist/dev.js

@@ -3,7 +3,7 @@ export function createDevServer(provider, options) {
     const port = options?.port ?? 3900;
     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}`);
             console.log(`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`);
             console.log(`[apifuse dev] Health: http://localhost:${port}/health`);

package/dist/engine.d.ts

@@ -0,0 +1,78 @@
+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 declare const PROVIDER_ENGINE_PROTOCOL_VERSION: "provider-engine.v1";
+/** Credential names owned by the engine and forbidden in provider declarations. */
+export declare const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES: readonly ["APIFUSE__PROXY__SMARTPROXY_APP_KEY", "APIFUSE__PROXY__NODEMAVEN_USERNAME", "APIFUSE__PROXY__NODEMAVEN_PASSWORD"];
+export declare function isEngineOwnedProxyCredentialName(name: string): boolean;
+/**
+ * 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 declare const ENGINE_OWNED_TELEMETRY_ENV_NAMES: readonly ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_HEADERS", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_SERVICE_NAME", "OTEL_RESOURCE_ATTRIBUTES"];
+export declare function isEngineOwnedTelemetryEnvName(name: string): boolean;
+/** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
+export declare function isEngineOwnedEnvName(name: string): boolean;
+/** Capture credentials in the engine host before constructing provider bindings. */
+export declare function readEngineProxyCredentials(environment?: Readonly<Record<string, string | undefined>>): Readonly<Record<string, string>>;
+/** Build the exact environment projection permitted to enter a provider runtime. */
+export declare function createProviderEnvironment(environment: Readonly<Record<string, string | undefined>>, declaredNames: readonly string[]): Readonly<Record<string, string>>;
+/**
+ * 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 declare const PROVIDER_CAPABILITY_KEYS: readonly ["env", "credential", "http", "files", "native", "cache", "state", "stealth", "browser", "auth", "ocr", "stt", "resolver", "choice"];
+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>;
+}
+/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+export declare function createInProcessProviderEngine(): ProviderEngine;

package/dist/engine.js

@@ -0,0 +1,133 @@
+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";
+/** Versioned envelope protocol used by out-of-process engine transports. */
+export const PROVIDER_ENGINE_PROTOCOL_VERSION = "provider-engine.v1";
+/** 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",
+];
+const ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET = new Set(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) {
+    return name.toUpperCase();
+}
+export function isEngineOwnedProxyCredentialName(name) {
+    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,
+];
+const ENGINE_OWNED_TELEMETRY_ENV_NAME_SET = new Set(ENGINE_OWNED_TELEMETRY_ENV_NAMES);
+export function isEngineOwnedTelemetryEnvName(name) {
+    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) {
+    return isEngineOwnedProxyCredentialName(name) || isEngineOwnedTelemetryEnvName(name);
+}
+/** Capture credentials in the engine host before constructing provider bindings. */
+export function readEngineProxyCredentials(environment = process.env) {
+    return Object.fromEntries(ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES.flatMap((name) => {
+        const value = environment[name]?.trim();
+        return value ? [[name, value]] : [];
+    }));
+}
+/** Build the exact environment projection permitted to enter a provider runtime. */
+export function createProviderEnvironment(environment, declaredNames) {
+    return Object.fromEntries(declaredNames.flatMap((name) => {
+        if (isEngineOwnedEnvName(name))
+            return [];
+        const value = environment[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+}
+export const PROVIDER_CAPABILITY_KEYS = [
+    "env",
+    "credential",
+    "http",
+    "files",
+    "native",
+    "cache",
+    "state",
+    "stealth",
+    "browser",
+    "auth",
+    "ocr",
+    "stt",
+    "resolver",
+    "choice",
+];
+const CAPABILITY_KEY_SET = new Set(PROVIDER_CAPABILITY_KEYS);
+function declaresCapability(provider, capability) {
+    return Object.hasOwn(provider, capability) && provider[capability] !== undefined;
+}
+function attachmentError(provider, capability) {
+    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, capability) {
+    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(input) {
+    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 = { 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)) {
+                throw undeclaredCapabilityError(provider, property);
+            }
+            return Reflect.get(target, property, receiver);
+        },
+        has(target, property) {
+            if (typeof property === "string" && CAPABILITY_KEY_SET.has(property)) {
+                return declaresCapability(provider, property);
+            }
+            return Reflect.has(target, property);
+        },
+    });
+}
+/** Local engine attachment; deployed bridges implement the same interface with RPC clients. */
+export function createInProcessProviderEngine() {
+    return { attach: attachInProcess };
+}

package/dist/error-observability.d.ts

@@ -0,0 +1,7 @@
+import { type ProviderErrorObservability } from "./errors.js";
+/**
+ * Extracts only own data properties from branded provider errors. In
+ * particular, descriptor reads reject options/observability accessors without
+ * invoking provider-controlled getters.
+ */
+export declare function safeProviderErrorObservability(error: unknown): ProviderErrorObservability | undefined;

package/dist/error-observability.js

@@ -0,0 +1,61 @@
+import { isProviderError } 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) {
+    if (!isProviderError(error))
+        return undefined;
+    let candidate;
+    let reason;
+    let fingerprint;
+    let messageLength;
+    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) => {
+            const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+            return descriptor && Object.hasOwn(descriptor, "value") ? descriptor.value : undefined;
+        };
+        reason = ownValue("reason");
+        fingerprint = ownValue("fingerprint");
+        messageLength = ownValue("messageLength");
+    }
+    catch {
+        return undefined;
+    }
+    const safe = {
+        ...(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/dist/error-resolution.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderErrorStatus } from "./types.js";
+export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
+export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;
+export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;

package/dist/error-resolution.js

@@ -0,0 +1,122 @@
+// 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 = new Map([
+    ["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/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import type { ProviderErrorCategory } from "./observability.js";
+import type { HttpRedirectFailureReason } from "./types.js";
 export type ProviderErrorOptions = {
     fix?: string;
     code?: string;
@@ -6,6 +7,21 @@ 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 declare class ProviderError extends Error {
     readonly options?: ProviderErrorOptions | undefined;
@@ -17,6 +33,11 @@ export declare class ProviderError extends Error {
 export declare class SDKError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }
+/** Raised when persisted stealth cookies use a store version this SDK cannot read. */
+export declare class StealthCookieStoreVersionError extends SDKError {
+    readonly version: unknown;
+    constructor(version: unknown);
+}
 export declare class AuthError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }
@@ -39,9 +60,21 @@ export declare class TransportError extends ProviderError {
     readonly upstreamStatus?: number;
     constructor(message: string, options?: TransportErrorOptions);
 }
+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 declare class HttpRedirectError extends TransportError {
+    readonly reason: HttpRedirectFailureReason;
+    readonly target?: string;
+    constructor(message: string, options: HttpRedirectErrorOptions);
+}
 export declare function isProviderError(value: unknown): value is ProviderError;
 export declare function isSessionExpiredError(value: unknown): value is SessionExpiredError;
 export declare function isTransportError(value: unknown): value is TransportError;
+export declare function isValidationError(value: unknown): value is ValidationError;
 export declare class ProviderSecretError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }

package/dist/errors.js

@@ -8,6 +8,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
 // without invoking attacker-controlled getters or accepting inherited brands.
@@ -57,6 +58,21 @@ export class SDKError extends ProviderError {
         this.name = "SDKError";
     }
 }
+/** Raised when persisted stealth cookies use a store version this SDK cannot read. */
+export class StealthCookieStoreVersionError extends SDKError {
+    version;
+    constructor(version) {
+        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.version = version;
+        this.name = "StealthCookieStoreVersionError";
+    }
+}
 export class AuthError extends ProviderError {
     constructor(message, options) {
         super(message, options);
@@ -81,6 +97,7 @@ export class ValidationError extends ProviderError {
         super(message, options);
         this.name = "ValidationError";
         this.zodError = options?.zodError;
+        defineErrorBrand(this, VALIDATION_BRAND, true);
     }
 }
 export class TransportError extends ProviderError {
@@ -94,6 +111,25 @@ export class TransportError extends ProviderError {
         defineErrorBrand(this, TRANSPORT_BRAND, true);
     }
 }
+/** Raised when an opt-in ctx.http redirect policy refuses or cannot resolve a hop. */
+export class HttpRedirectError extends TransportError {
+    reason;
+    target;
+    constructor(message, options) {
+        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
@@ -107,6 +143,10 @@ export function isSessionExpiredError(value) {
 export function isTransportError(value) {
     return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
 }
+export function isValidationError(value) {
+    return (isProviderError(value) &&
+        (hasOwnBrand(value, VALIDATION_BRAND, true) || value.name === "ValidationError"));
+}
 export class ProviderSecretError extends ProviderError {
     constructor(message, options) {
         super(message, { code: "provider_secret_error", ...options });

package/dist/fixture-sanitization.d.ts

@@ -0,0 +1,28 @@
+import type { JsonValue } from "./contract-json.js";
+export declare const REDACTED_FIXTURE_VALUE = "[REDACTED]";
+/** Matches credential field names without treating benign prefixes such as `author` as `auth`. */
+export declare function isSensitiveFixtureKey(key: string): boolean;
+/**
+ * Returns JSON fixture data with credential-bearing keys and heuristic-confirmed string secrets
+ * replaced. Ordinary short prose and identifiers are retained.
+ */
+export declare function sanitizeFixture(value: JsonValue): JsonValue;
+/** Applies the shared credential-key policy to ordinary JSON fixtures. */
+export declare function sanitizeOrdinaryFixture(value: JsonValue): JsonValue;
+/** Sanitizes a primitive fixture string only when textual-secret heuristics match. */
+export declare function sanitizeFixtureString(value: string): string;
+/** True for opaque values that are unsafe to retain in paths or unstructured text. */
+export declare function isSensitiveFixtureValue(value: string): boolean;
+/** Sanitizes every path segment and values following a credential-like segment name. */
+export declare function sanitizePathname(pathname: string): string;
+/** Removes userinfo, query values, fragments, and credential-like path segments from log URLs. */
+export declare function sanitizeUrlForLogs(value: string): string;
+/**
+ * Returns query-free request provenance with each path segment scrubbed for credential-like values.
+ * Origins, URL userinfo, query values, and fragments are never persisted in request provenance.
+ */
+export declare function requestPathForFixture(value: string): string;
+/** Scrubs secrets and terminal/log control characters before diagnostic text is emitted. */
+export declare function sanitizeDiagnosticText(value: string): string;
+/** Encodes terminal/log control characters without applying value-level secret heuristics. */
+export declare function encodeDiagnosticControls(value: string): string;