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

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/errors.d.ts

@@ -7,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;

package/dist/fixture-sanitization.js

@@ -2,6 +2,9 @@ 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 EMAIL_ADDRESS_RUN = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+const DIAGNOSTIC_URL_SENTINEL_DELIMITER = String.fromCodePoint(0);
+const DIAGNOSTIC_URL_SENTINEL_RUN = new RegExp(`${DIAGNOSTIC_URL_SENTINEL_DELIMITER}APIFUSE_URL(\\d+)${DIAGNOSTIC_URL_SENTINEL_DELIMITER}`, "g");
 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) {
@@ -125,9 +128,15 @@ export function requestPathForFixture(value) {
 }
 /** 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}`);
+    const retainedUrls = [];
+    // Remove attacker-controlled NUL delimiters before introducing internal URL sentinels.
+    let sanitized = encodeDiagnosticControls(value)
+        .replace(URL_RUN, (url) => {
+        const index = retainedUrls.push(sanitizeUrlForLogs(url)) - 1;
+        return `${DIAGNOSTIC_URL_SENTINEL_DELIMITER}APIFUSE_URL${index}${DIAGNOSTIC_URL_SENTINEL_DELIMITER}`;
+    })
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED_FIXTURE_VALUE}`)
+        .replace(EMAIL_ADDRESS_RUN, REDACTED_FIXTURE_VALUE);
     sanitized = redactSensitiveAssignments(sanitized);
     sanitized = sanitized.replace(OPAQUE_TOKEN_RUN, (candidate, offset, source) => {
         if (/^(?:request|trace|correlation)[-_]?id[:=]/i.test(candidate))
@@ -137,6 +146,7 @@ export function sanitizeDiagnosticText(value) {
             return candidate;
         return isSensitiveFixtureValue(candidate) ? REDACTED_FIXTURE_VALUE : candidate;
     });
+    sanitized = sanitized.replace(DIAGNOSTIC_URL_SENTINEL_RUN, (_match, index) => retainedUrls[Number(index)] ?? REDACTED_FIXTURE_VALUE);
     return encodeDiagnosticControls(sanitized);
 }
 function redactSensitiveAssignments(value) {

package/dist/index.d.ts

@@ -42,7 +42,7 @@ export { APIFUSE__OCR__API_KEY_ENV, APIFUSE__OCR__BACKEND_ENV, APIFUSE__OCR__BAS
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
-export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ServeOptions, serve, } from "./server/serve.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ProviderErrorCauseFrame, type ServeOptions, serve, } from "./server/serve.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
 export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";

package/dist/provider.d.ts

@@ -7,7 +7,7 @@ export type { ProviderBuilder, ProviderContextOf, ProviderDeclaration, } from ".
 export type { JsonPrimitive, JsonValue } from "./contract-json.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export type { AssertionExpression, AssertionPredicate, AttemptReference, AssertResult, AssertStep, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialReference, CredentialRefDeclaration, EstablishedConnectionReference, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JsonTemplate, JournalPolicy, ManualTriggerPolicy, NonEmpty, OperationResult, OperationStep, Operand, Quantifier, ReferenceNode, Reference, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ExtractResult, ValueType, } from "./health-scenario.js";
-export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, type ProviderErrorObservability, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";

package/dist/runtime/executor.js

@@ -1,3 +1,4 @@
+import { safeProviderErrorObservability } from "../error-observability.js";
 import { isSessionExpiredError, isValidationError, ProviderError, SessionExpiredError, ValidationError, } from "../errors.js";
 import { z } from "zod";
 import { parseSchema } from "../schema.js";
@@ -6,6 +7,12 @@ export function isStreamingOperation(provider, operationId) {
     const kind = provider.operations[operationId]?.transport?.kind ?? "json";
     return kind !== "json";
 }
+function preservedSessionExpiredOptions(error) {
+    const observability = safeProviderErrorObservability(error);
+    return observability
+        ? { observability, retryable: true }
+        : { retryable: true };
+}
 /**
  * Execute a provider operation by calling its handler.
  *
@@ -55,7 +62,10 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
         // executor's, which `instanceof` would miss — dropping the retryable
         // upgrade and stranding an operation that opted into auth refresh.
         if (isSessionExpiredError(error) && operation.retryOnAuthRefresh) {
-            throw new SessionExpiredError(error.message, { retryable: true });
+            // Preserve provider-authored safe metadata while forcing the retry signal.
+            // `cause` intentionally remains dropped, matching the pre-existing
+            // reconstruction semantics.
+            throw new SessionExpiredError(error.message, preservedSessionExpiredOptions(error));
         }
         throw error;
     }

package/dist/server/error-observability.d.ts

@@ -0,0 +1 @@
+export { safeProviderErrorObservability } from "../error-observability.js";

package/dist/server/error-observability.js

@@ -0,0 +1 @@
+export { safeProviderErrorObservability } from "../error-observability.js";

package/dist/server/index.d.ts

@@ -1,6 +1,7 @@
 export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
 export type { ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "../runtime/proxy-telemetry.js";
-export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";

package/dist/server/self-test.js

@@ -792,6 +792,9 @@ async function executeSelfTestCase(execution, operationId, suite, healthCase, ca
         const { startedAtMs, finish } = caseScope;
         try {
             return await runWithCaseTimeout(async () => {
+                if (healthCase.assertions === undefined) {
+                    throw new Error(`Self-test cannot execute declarative health-check case "${healthCase.name}"; run its scenario through the health monitor.`);
+                }
                 const resolvedInput = resolveHealthCheckInputDateTokens(healthCase.input);
                 const preparedInput = healthCase.prepareInput
                     ? await healthCase.prepareInput({

package/dist/server/serve-implementation.d.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { z } from "zod";
+import { type ProviderErrorObservability } from "../errors.js";
 import { type ProviderErrorCategory } from "../observability.js";
 import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 import type { OcrContext, ProviderContext, ProviderDefinition, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
@@ -12,6 +13,7 @@ export type ErrorObservabilityDetails = {
     taxonomyVersion: string;
     retryable: boolean;
     upstreamStatus?: number;
+    providerObservability?: ProviderErrorObservability;
 };
 export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
     requestId: z.ZodString;
@@ -92,6 +94,8 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     errorCategory?: ProviderErrorCategory;
     taxonomyVersion?: string;
     retryable?: boolean;
+    providerObservability?: ProviderErrorObservability;
+    causeChain?: ProviderErrorCauseFrame[];
     signal?: "unregistered_provider_error_code";
     signalFix?: string;
     issues?: Array<{
@@ -180,6 +184,14 @@ export type ProviderServerOptions = {
         readonly timeoutMs?: number;
     };
 };
+export type ProviderErrorCauseFrame = {
+    errorClass: string;
+    code?: string;
+    message: string;
+    messageLength: number;
+    messageFingerprint: string;
+    providerObservability?: ProviderErrorObservability;
+};
 /**
  * Primary, cross-runtime app factory. Declared capability ESM is preloaded
  * asynchronously, so this path works on Bun and every supported Node release.