@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/error-resolution.js

@@ -0,0 +1,243 @@
+// 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",
+    "STEALTH_HEADER_OVERRIDE_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",
+    // Engine attachment (ADR-0011). Registered here so an engine failure is served
+    // as a known SDK code instead of raising a false
+    // `unregistered_provider_error_code` signal on a 500.
+    "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+    "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+    "PROVIDER_ENGINE_UNAVAILABLE",
+    "PROVIDER_ENGINE_MODE_UNSUPPORTED",
+    "PROVIDER_EGRESS_DENIED",
+    "HANDLE_INVALID",
+    "HANDLE_NOT_FOUND",
+    "HANDLE_EXPIRED",
+    "HANDLE_KIND_MISMATCH",
+    "HANDLE_BUSY",
+    "HANDLE_COMMITTED",
+    "HANDLE_CONNECTION_REQUIRED",
+    "HANDLE_STORAGE_UNAVAILABLE",
+    "HANDLE_TOO_LARGE",
+    "HANDLE_INVALID_DATA",
+    "PICK_NOT_OFFERED",
+    "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",
+    "http_header_factory_failed",
+    "EGRESS_LEASE_INVALID",
+    "EGRESS_LEASE_BINDING_INVALID",
+    "EGRESS_LEASE_KEY_MISSING",
+    "EGRESS_LEASE_KEY_WEAK",
+    "STEALTH_BODY_UNSUPPORTED",
+    "REPLAY_SESSION_MISMATCH",
+    "REPLAY_ALREADY_ATTEMPTED",
+    "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_CONTEXT_INVALID",
+    "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",
+]);
+// Registered codes that name an upstream outcome. A row states the status the
+// SDK serves and the observability category together, so an upstream code
+// cannot be registered without saying who failed. Serve reads the category
+// for a `ProviderError` that carries one of these codes and no explicit
+// `category`, and the public `source` follows from it (`sourceForCategory`).
+// Without a row the category defaults to `provider_error` → `source:
+// "apifuse"`, and the health monitor cannot tie a real upstream failure to the
+// upstream: it publishes `monitoring_unavailable` instead of `down`.
+//
+// The category is `categoryForStatus(status)` unless the code names a
+// narrower class than its status can: a schema change, a bot wall, an
+// upstream refusal of the platform-managed key (served 400, see below).
+// Every row is a code the fleet throws for something the upstream did or
+// said; caller-side and SDK-internal codes stay in the table below.
+export const SDK_UPSTREAM_ERROR_CODE_REGISTRY = new Map([
+    // The SDK's own unknown-operation and unknown-route throws reuse the
+    // not-found spellings; they set an explicit category and stay APIFuse's.
+    ["NOT_FOUND", { status: 404, category: "upstream_http" }],
+    ["not_found", { status: 404, category: "upstream_http" }],
+    ["NO_DATA", { status: 404, category: "upstream_http" }],
+    ["RATE_LIMITED", { status: 429, category: "upstream_rate_limited" }],
+    ["UPSTREAM_RATE_LIMIT", { status: 429, category: "upstream_rate_limited" }],
+    [
+        "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR",
+        { status: 429, category: "upstream_rate_limited" },
+    ],
+    // 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", { status: 409, category: "upstream_rejected" }],
+    ["UPSTREAM_ERROR", { status: 502, category: "upstream_http" }],
+    // The upstream's bot wall or request protection refused the request. The
+    // status says only "upstream"; the code says which kind.
+    ["BLOCKED", { status: 502, category: "anti_bot_blocked" }],
+    // Fleet-consensus provider codes. These are thrown by provider code, not
+    // by the SDK, so they are registered here (status mapping) and not in
+    // SDK_RUNTIME_OWNED_ERROR_CODES: an operation-declared status still wins,
+    // exactly as it does for UPSTREAM_ERROR and BLOCKED above. Registering
+    // them stops the fleet from re-declaring the same rows on every
+    // operation, and stops an undeclared throw from being served as 500.
+    //
+    // A platform-managed upstream service key the upstream refuses. With
+    // `auth.mode: "platform-managed"` the caller holds no credential, so 401
+    // ("re-authenticate") tells the caller to do something it cannot do, and
+    // 502 ("upstream is sick") promises a recovery that will never come. It is
+    // a deployment/config defect — the same class as MISSING_SECRET below,
+    // which is already an explicit 400 for that reason. The upstream is still
+    // the one refusing, so the category is `upstream_auth`; the gateway
+    // records it as `provider_error` for every non-`required` connection mode
+    // so the refusal stays provider-alertable.
+    ["UPSTREAM_AUTH_ERROR", { status: 400, category: "upstream_auth" }],
+    // The upstream changed its response shape and the provider cannot
+    // normalize it. 502 because the fault is upstream of us, non-retryable
+    // because a retry returns the same broken payload.
+    ["UPSTREAM_SCHEMA_ERROR", { status: 502, category: "upstream_schema_drift" }],
+]);
+/**
+ * The category a registered upstream code carries when its `ProviderError`
+ * sets none. `undefined` for every other code, which keeps its existing
+ * default.
+ */
+export function registeredUpstreamErrorCategory(code) {
+    return code === undefined ? undefined : SDK_UPSTREAM_ERROR_CODE_REGISTRY.get(code)?.category;
+}
+// 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 — an upstream-attributed code goes in
+// SDK_UPSTREAM_ERROR_CODE_REGISTRY above, which feeds this map.
+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],
+    // Only an unverifiable or foreign handle is the caller's: key and binding
+    // faults stay unmapped (500) because the engine host, not the caller, owns them.
+    ["EGRESS_LEASE_INVALID", 409],
+    ["REPLAY_SESSION_MISMATCH", 409],
+    ["REPLAY_ALREADY_ATTEMPTED", 409],
+    // Handles (ADR-0012): only caller-side faults are mapped. Storage,
+    // connection-scope, size, and schema faults stay 500 because the provider
+    // or host owns them.
+    ["HANDLE_INVALID", 400],
+    ["HANDLE_KIND_MISMATCH", 400],
+    ["PICK_NOT_OFFERED", 400],
+    ["HANDLE_NOT_FOUND", 404],
+    ["HANDLE_EXPIRED", 410],
+    ["HANDLE_COMMITTED", 409],
+    ["HANDLE_BUSY", 409],
+    // Caller-side bad input rejected by the provider (fleet consensus, like
+    // UPSTREAM_AUTH_ERROR and UPSTREAM_SCHEMA_ERROR above). The minority
+    // spellings (INVALID_INPUT / VALIDATION_ERROR / BAD_REQUEST) are
+    // deliberately not registered: they migrate to this spelling on the
+    // contract track, and registering them here would freeze the divergence.
+    ["INVALID_REQUEST", 400],
+    ["OCR_UNAVAILABLE", 503],
+    ["UNSUPPORTED_OCR_BACKEND", 503],
+    ["STT_UNAVAILABLE", 503],
+    ["UNSUPPORTED_STT_BACKEND", 503],
+    ["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+    // The engine is reachable-in-principle but not now: retryable, so the
+    // caller may retry once the engine recovers. Authentication, protocol
+    // mismatch, an unsupported mode and denied egress stay unmapped (500) and
+    // non-retryable: they are deployment or provider faults that no caller
+    // retry can clear, and a retryable 5xx there would turn one bad rollout
+    // into gateway-driven load.
+    ["PROVIDER_ENGINE_UNAVAILABLE", 503],
+    ...Array.from(SDK_UPSTREAM_ERROR_CODE_REGISTRY, ([code, registration]) => [code, registration.status]),
+]);
+// Canonical retryability for the fleet-consensus codes registered above.
+//
+// Runtime retryability still resolves as `instance option ?? declared ??
+// false`, so this map changes no served response: an undeclared throw already
+// defaults to false, which is what every entry here says. It exists so the
+// authoring lint can tell a provider that its declared `retryable` contradicts
+// the registered meaning of the code, instead of the fleet quietly shipping two
+// answers for the same code. Only codes whose retryability was fixed as part of
+// registration belong here — do not backfill opinions the SDK never made.
+export const SDK_CANONICAL_ERROR_CODE_RETRYABILITY = new Map([
+    ["UPSTREAM_AUTH_ERROR", false],
+    ["UPSTREAM_SCHEMA_ERROR", false],
+    ["INVALID_REQUEST", false],
+]);

package/dist/errors.d.ts

@@ -1,4 +1,6 @@
+import type { ProviderErrorMessageParams } from "./i18n/error-messages.js";
 import type { ProviderErrorCategory } from "./observability.js";
+import type { HttpRedirectFailureReason, ProviderLocaleKeyInput } from "./types.js";
 export type ProviderErrorOptions = {
     fix?: string;
     code?: string;
@@ -6,6 +8,40 @@ export type ProviderErrorOptions = {
     cause?: Error;
     category?: ProviderErrorCategory;
     retryable?: boolean;
+    /** Provider-authored, bounded metadata safe for operational logs and error headers. */
+    observability?: ProviderErrorObservability;
+    /**
+     * Locale catalog key for the client-facing `message`, e.g.
+     * `"errors.upstreamSchema.message"`. Resolved at serve time against the
+     * provider's `locales/{en,ko,ja}.json` with the caller's `Accept-Language`,
+     * falling back to `en` and then to the positional `message`.
+     *
+     * The positional `message` stays English: it is what `error.message`, cause
+     * frames, logs and OTLP attributes carry. Only the response envelope is
+     * localized.
+     */
+    messageKey?: ProviderLocaleKeyInput;
+    /** Locale catalog key for the client-facing `fix`. Same resolution as {@link ProviderErrorOptions.messageKey}. */
+    fixKey?: ProviderLocaleKeyInput;
+    /**
+     * Values substituted into `{name}` placeholders of the resolved text.
+     * Strings and finite numbers only; string values are scrubbed and length
+     * capped before substitution because upstream text routinely lands here.
+     */
+    params?: ProviderErrorMessageParams;
+};
+/**
+ * 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 +53,29 @@ export declare class ProviderError extends Error {
 export declare class SDKError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export declare class ProviderEngineProtocolVersionError extends SDKError {
+    readonly receivedVersion: unknown;
+    readonly expectedVersion: string;
+    constructor(receivedVersion: unknown, expectedVersion: string);
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export declare class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message?: string, options?: ProviderErrorOptions);
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export declare class ProviderEngineUnavailableError extends SDKError {
+    constructor(message?: string, cause?: Error);
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export declare class ProviderEgressDeniedError extends ProviderError {
+    constructor(message: string, details?: unknown);
+}
+/** 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 +98,24 @@ 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;
+/** Brands a handle error (ADR-0012) so `isHandleError` works across duplicate SDK module copies. */
+export declare function brandHandleError(target: object): void;
+export declare function hasHandleErrorBrand(value: unknown): boolean;
+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,8 @@ 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");
+const HANDLE_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/handle@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 +59,71 @@ export class SDKError extends ProviderError {
         this.name = "SDKError";
     }
 }
+/** Raised when the remote provider engine speaks an incompatible protocol version. */
+export class ProviderEngineProtocolVersionError extends SDKError {
+    receivedVersion;
+    expectedVersion;
+    constructor(receivedVersion, expectedVersion) {
+        super(`Provider engine protocol version mismatch: expected ${expectedVersion}, received ${String(receivedVersion)}`, {
+            code: "PROVIDER_ENGINE_PROTOCOL_VERSION_MISMATCH",
+            details: { receivedVersion, expectedVersion },
+            fix: "Update @apifuse/provider-sdk or use a compatible APIFuse provider engine.",
+        });
+        this.receivedVersion = receivedVersion;
+        this.expectedVersion = expectedVersion;
+        this.name = "ProviderEngineProtocolVersionError";
+    }
+}
+/** Raised when the remote provider engine rejects a workspace API key. */
+export class ProviderEngineAuthenticationError extends SDKError {
+    constructor(message = "Provider engine authentication failed", options) {
+        super(message, {
+            code: "PROVIDER_ENGINE_AUTHENTICATION_FAILED",
+            fix: "Set APIFUSE__ENGINE__API_KEY to the workspace API key from your APIFuse bounty dashboard.",
+            ...options,
+        });
+        this.name = "ProviderEngineAuthenticationError";
+    }
+}
+/** Raised when the remote engine cannot be reached. There is no local fallback. */
+export class ProviderEngineUnavailableError extends SDKError {
+    constructor(message = "The remote APIFuse provider engine is unavailable", cause) {
+        super(message, {
+            code: "PROVIDER_ENGINE_UNAVAILABLE",
+            retryable: true,
+            fix: "Check network access and the provider engine endpoint, then retry.",
+            ...(cause ? { cause } : {}),
+        });
+        this.name = "ProviderEngineUnavailableError";
+    }
+}
+/** Raised when the engine refuses egress outside the workspace's pinned allowlist. */
+export class ProviderEgressDeniedError extends ProviderError {
+    constructor(message, details) {
+        super(message, {
+            code: "PROVIDER_EGRESS_DENIED",
+            retryable: false,
+            details,
+            fix: "Use a host in the provider's pinned allowedHosts declaration, or request a trusted pin update.",
+        });
+        this.name = "ProviderEgressDeniedError";
+    }
+}
+/** 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 +148,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 +162,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 +194,18 @@ export function isSessionExpiredError(value) {
 export function isTransportError(value) {
     return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
 }
+/** Brands a handle error (ADR-0012) so `isHandleError` works across duplicate SDK module copies. */
+export function brandHandleError(target) {
+    defineErrorBrand(target, HANDLE_BRAND, true);
+}
+export function hasHandleErrorBrand(value) {
+    return (hasOwnBrand(value, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE) &&
+        hasOwnBrand(value, HANDLE_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;