@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

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;
@@ -17,6 +18,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 +45,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;

package/dist/fixture-sanitization.js

@@ -0,0 +1,217 @@
+export const REDACTED_FIXTURE_VALUE = "[REDACTED]";
+const OPAQUE_TOKEN = /^[A-Za-z0-9_+/=.:~-]+$/;
+const OPAQUE_TOKEN_RUN = /[A-Za-z0-9_+/=.:~-]{24,}/g;
+const URL_RUN = /https?:\/\/[^\s"'<>]+/gi;
+const PEM_PRIVATE_KEY = /-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9 ]+ )?PRIVATE KEY-----/g;
+/** Matches credential field names without treating benign prefixes such as `author` as `auth`. */
+export function isSensitiveFixtureKey(key) {
+    const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
+    const candidates = [normalized, normalized.replace(/(?:value|payload|header)$/, "")];
+    return candidates.some((candidate) => /^(?:authorization|authentication|auth|bearer|cookie|credential|password|passwd|privatekey|secret|session|sessionid|token)$/.test(candidate) ||
+        /^(?:api|client|service|access|consumer)(?:key|secret|token)$/.test(candidate) ||
+        /(?:authorization|credential|password|passwd|privatekey|secret|sessionid|token)$/.test(candidate));
+}
+/**
+ * Returns JSON fixture data with credential-bearing keys and heuristic-confirmed string secrets
+ * replaced. Ordinary short prose and identifiers are retained.
+ */
+export function sanitizeFixture(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeFixture(item));
+    }
+    if (typeof value === "string")
+        return sanitizeFixtureString(value);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
+        key,
+        isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeFixture(entryValue),
+    ]));
+}
+/** Applies the shared credential-key policy to ordinary JSON fixtures. */
+export function sanitizeOrdinaryFixture(value) {
+    if (Array.isArray(value))
+        return value.map((item) => sanitizeOrdinaryFixture(item));
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
+        key,
+        isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeOrdinaryFixture(entryValue),
+    ]));
+}
+/** Sanitizes a primitive fixture string only when textual-secret heuristics match. */
+export function sanitizeFixtureString(value) {
+    let sanitized = value.replace(PEM_PRIVATE_KEY, REDACTED_FIXTURE_VALUE);
+    const retainedUrls = [];
+    sanitized = sanitized.replace(URL_RUN, (url) => {
+        const index = retainedUrls.push(isCredentialBearingUrl(url) ? sanitizeUrlForLogs(url) : url) - 1;
+        return `APIFUSEURL${index}X`;
+    });
+    sanitized = redactSensitiveAssignments(sanitized);
+    sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate) => isSensitiveFixtureValue(candidate) ? REDACTED_FIXTURE_VALUE : candidate);
+    sanitized = sanitized.replace(/APIFUSEURL(\d+)X/g, (_match, index) => retainedUrls[Number(index)] ?? REDACTED_FIXTURE_VALUE);
+    return sanitized;
+}
+/** True for opaque values that are unsafe to retain in paths or unstructured text. */
+export function isSensitiveFixtureValue(value) {
+    const candidate = decodePathSegment(value);
+    if (/^bot(?:\d{6,}:)?[A-Za-z0-9_-]{16,}$/i.test(candidate))
+        return true;
+    if (/^\d{6,}:[A-Za-z0-9_-]{20,}$/.test(candidate))
+        return true;
+    if (/^(?:gh[opusr]_|sk[-_]|xox[baprs]-)[A-Za-z0-9_-]{16,}$/i.test(candidate))
+        return true;
+    if (!OPAQUE_TOKEN.test(candidate) || candidate.length < 24)
+        return false;
+    if (/^[a-f0-9]{32,}$/i.test(candidate))
+        return true;
+    return shannonEntropy(candidate) >= 3.5;
+}
+/** Sanitizes every path segment and values following a credential-like segment name. */
+export function sanitizePathname(pathname) {
+    const segments = pathname.split("/");
+    return segments
+        .map((segment, index) => {
+        if (!segment)
+            return segment;
+        const decoded = decodePathSegment(segment);
+        const previous = index > 0 ? decodePathSegment(segments[index - 1]) : "";
+        if (isSensitivePathSegment(decoded) ||
+            isCredentialPathKey(previous) ||
+            isSensitiveFixtureValue(decoded)) {
+            return REDACTED_FIXTURE_VALUE;
+        }
+        return segment;
+    })
+        .join("/");
+}
+function isCredentialPathKey(key) {
+    const finalPathPart = key.split("/").at(-1) ?? "";
+    const baseSegment = finalPathPart.split(";", 1)[0] ?? "";
+    return isSensitiveFixtureKey(baseSegment.split(/[=:]/, 1)[0] ?? "");
+}
+function isSensitivePathSegment(segment) {
+    return segment
+        .split(/[;/]/)
+        .some((part) => isSensitiveFixtureKey(part.split(/[=:]/, 1)[0] ?? ""));
+}
+/** Removes userinfo, query values, fragments, and credential-like path segments from log URLs. */
+export function sanitizeUrlForLogs(value) {
+    try {
+        const parsed = new URL(value, "https://fixture.invalid");
+        const queryMarker = parsed.search ? `?${REDACTED_FIXTURE_VALUE}` : "";
+        const path = sanitizePathname(parsed.pathname);
+        if (parsed.origin === "https://fixture.invalid" && !hasExplicitOrigin(value)) {
+            return `${path}${queryMarker}`;
+        }
+        return `${parsed.origin}${path}${queryMarker}`;
+    }
+    catch {
+        return sanitizePathname(value.split(/[?#]/, 1)[0]);
+    }
+}
+/**
+ * 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 function requestPathForFixture(value) {
+    try {
+        return sanitizePathname(new URL(value, "https://fixture.invalid").pathname);
+    }
+    catch {
+        const path = value.split(/[?#]/, 1)[0];
+        return sanitizePathname(path.startsWith("/") ? path : `/${path}`);
+    }
+}
+/** Scrubs secrets and terminal/log control characters before diagnostic text is emitted. */
+export function sanitizeDiagnosticText(value) {
+    let sanitized = value
+        .replace(URL_RUN, (url) => sanitizeUrlForLogs(url))
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED_FIXTURE_VALUE}`);
+    sanitized = redactSensitiveAssignments(sanitized);
+    sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate, offset, source) => {
+        if (/^(?:request|trace|correlation)[-_]?id[:=]/i.test(candidate))
+            return candidate;
+        const prefix = source.slice(Math.max(0, offset - 32), offset);
+        if (/(?:request|trace|correlation)[-_]?id\s*[:=]\s*$/i.test(prefix))
+            return candidate;
+        return isSensitiveFixtureValue(candidate) ? REDACTED_FIXTURE_VALUE : candidate;
+    });
+    return encodeDiagnosticControls(sanitized);
+}
+function redactSensitiveAssignments(value) {
+    return value.replace(/((["']?)([\w-]+)\2\s*[:=]\s*)("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;&]+)/gi, (match, prefix, _quote, key, assignmentValue) => {
+        if (!isSensitiveFixtureKey(key) && key.toLowerCase() !== "key")
+            return match;
+        const quote = assignmentValue.startsWith('"')
+            ? '"'
+            : assignmentValue.startsWith("'")
+                ? "'"
+                : "";
+        return `${prefix}${quote}${REDACTED_FIXTURE_VALUE}${quote}`;
+    });
+}
+function isCredentialBearingUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return (parsed.username !== "" ||
+            parsed.password !== "" ||
+            parsed.hash !== "" ||
+            parsed.search !== "" ||
+            parsed.pathname.split("/").some((segment, index, segments) => {
+                const decoded = decodePathSegment(segment);
+                const previous = decodePathSegment(segments[index - 1] ?? "");
+                return (isSensitiveFixtureKey(decoded) ||
+                    isCredentialPathKey(previous) ||
+                    isSensitiveFixtureValue(decoded));
+            }));
+    }
+    catch {
+        return false;
+    }
+}
+/** Encodes terminal/log control characters without applying value-level secret heuristics. */
+export function encodeDiagnosticControls(value) {
+    let result = "";
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code === 0x0a || code === 0x0d || code === 0x2028 || code === 0x2029) {
+            result += " ";
+        }
+        else if ((code >= 0 && code <= 0x1f) ||
+            (code >= 0x7f && code <= 0x9f) ||
+            code === 0x061c ||
+            code === 0x200e ||
+            code === 0x200f ||
+            (code >= 0x202a && code <= 0x202e) ||
+            (code >= 0x2066 && code <= 0x2069)) {
+            result += `\\u${code.toString(16).padStart(4, "0")}`;
+        }
+        else {
+            result += character;
+        }
+    }
+    return result;
+}
+function decodePathSegment(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function hasExplicitOrigin(value) {
+    return /^[a-z][a-z\d+.-]*:\/\//i.test(value);
+}
+function shannonEntropy(value) {
+    const counts = new Map();
+    for (const character of value)
+        counts.set(character, (counts.get(character) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const probability = count / value.length;
+        entropy -= probability * Math.log2(probability);
+    }
+    return entropy;
+}