@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/dist/runtime/choice.js

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
-import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token";
-import { ProviderError } from "../errors";
+import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token.js";
+import { isProviderError, ProviderError } from "../errors.js";
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
 const PRIMARY_CHOICE_TOKEN_KID = "v1";
 const MANAGED_CHOICE_TOKEN_VERSION = 1;
@@ -53,7 +53,7 @@ export function createProviderChoiceContext(options) {
         });
     }
     function parse(parseOptions) {
-        const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature,] = parseManagedChoiceTokenParts(parseOptions.token);
+        const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature] = parseManagedChoiceTokenParts(parseOptions.token);
         if (actualPrefix !== parseOptions.prefix ||
             tokenKid !== kid ||
             !encodedIv ||
@@ -68,13 +68,7 @@ export function createProviderChoiceContext(options) {
             purpose: parseOptions.purpose,
             kid: tokenKid,
         });
-        const signedBody = [
-            parseOptions.prefix,
-            tokenKid,
-            encodedIv,
-            encryptedPayload,
-            authTag,
-        ].join(".");
+        const signedBody = [parseOptions.prefix, tokenKid, encodedIv, encryptedPayload, authTag].join(".");
         assertManagedChoiceSignature({
             signedBody,
             signature,
@@ -117,13 +111,11 @@ export function createProviderChoiceContext(options) {
 export function createTestProviderChoiceContext(options) {
     return createProviderChoiceContext({
         ...options,
-        masterSecret: options.masterSecret ??
-            "apifuse-test-provider-runtime-choice-token-master-secret",
+        masterSecret: options.masterSecret ?? "apifuse-test-provider-runtime-choice-token-master-secret",
     });
 }
 function resolveChoiceMasterSecret(options) {
-    const configured = options.masterSecret ??
-        options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
+    const configured = options.masterSecret ?? options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
     const trimmed = configured?.trim();
     if (trimmed)
         return trimmed;
@@ -165,13 +157,7 @@ function encryptManagedChoiceToken(options) {
     ]).toString("base64url");
     const authTag = cipher.getAuthTag().toString("base64url");
     const encodedIv = iv.toString("base64url");
-    const signedBody = [
-        options.prefix,
-        options.kid,
-        encodedIv,
-        encryptedPayload,
-        authTag,
-    ].join(".");
+    const signedBody = [options.prefix, options.kid, encodedIv, encryptedPayload, authTag].join(".");
     const signature = createHmac("sha256", options.keys.signing)
         .update(signedBody)
         .digest("base64url");
@@ -223,7 +209,25 @@ async function parseServerStoredChoice(options) {
         storage,
         contextState: options.contextState,
     });
-    const record = await namespace.get(optionsStateKey(options.handle.state_id));
+    // Reading a server-stored choice back deserializes a persisted value. A
+    // corrupt/undecodable value would otherwise surface as a raw JSON.parse
+    // SyntaxError (or another unexpected throwable) that escapes the choice error
+    // taxonomy, gets masked as internal_error 500, and is treated as retryable by
+    // the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+    // Convert any non-branded throwable into a branded invalid_payload so it maps
+    // to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+    // ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+    // their category/retryable semantics are preserved.
+    let record;
+    try {
+        record = await namespace.get(optionsStateKey(options.handle.state_id));
+    }
+    catch (error) {
+        if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+            throw error;
+        }
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload could not be decoded.");
+    }
     if (!record) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload is missing.");
     }
@@ -345,9 +349,7 @@ function isManagedChoiceEnvelope(value) {
         typeof value.issued_at_ms === "number" &&
         "ttl_ms" in value &&
         typeof value.ttl_ms === "number" &&
-        (!("binding" in value) ||
-            value.binding === undefined ||
-            isChoiceBinding(value.binding)));
+        (!("binding" in value) || value.binding === undefined || isChoiceBinding(value.binding)));
 }
 function isChoicePayload(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
@@ -355,29 +357,23 @@ function isChoicePayload(value) {
 function isChoiceBinding(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
-    return ((!("connection_hash" in value) ||
-        typeof value.connection_hash === "string") &&
+    return ((!("connection_hash" in value) || typeof value.connection_hash === "string") &&
         (!("credential_hash" in value) || typeof value.credential_hash === "string"));
 }
 function assertManagedChoiceEnvelope(envelope, options) {
-    if (envelope.provider_id !== options.providerId ||
-        envelope.purpose !== options.purpose) {
+    if (envelope.provider_id !== options.providerId || envelope.purpose !== options.purpose) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token payload is invalid.");
     }
     assertFreshProviderChoiceIssuedAt(envelope.issued_at_ms, {
         // Clamp to the issuer's embedded TTL so a caller-supplied value cannot
         // silently extend token validity past the deadline the issuer intended.
-        ttlMs: options.ttlMs != null
-            ? Math.min(options.ttlMs, envelope.ttl_ms)
-            : envelope.ttl_ms,
+        ttlMs: options.ttlMs != null ? Math.min(options.ttlMs, envelope.ttl_ms) : envelope.ttl_ms,
         nowMs: options.nowMs,
         futureToleranceMs: options.futureToleranceMs,
     });
 }
 function createChoiceBinding(options) {
-    const connectionHash = options.options?.connection
-        ? hashRequiredConnection(options)
-        : undefined;
+    const connectionHash = options.options?.connection ? hashRequiredConnection(options) : undefined;
     const credentialHash = options.options?.credentialKeys?.length
         ? hashCredentialKeys(options)
         : undefined;

package/dist/runtime/credential.d.ts

@@ -1,4 +1,4 @@
-import type { AuthMode, CredentialContext } from "../types";
+import type { AuthMode, CredentialContext } from "../types.js";
 export interface CreateCredentialContextOptions {
     allowedKeys?: string[];
     mode?: AuthMode;

package/dist/runtime/credential.js

@@ -1,4 +1,4 @@
-import { CredentialModeError } from "../errors";
+import { CredentialModeError } from "../errors.js";
 function getAllowedKeys(allowedKeys, values) {
     if (allowedKeys) {
         return allowedKeys;

package/dist/runtime/env.d.ts

@@ -1,2 +1,2 @@
-import type { EnvContext } from "../types";
+import type { EnvContext } from "../types.js";
 export declare function createEnvContext(allowedKeys?: string[]): EnvContext;

package/dist/runtime/executor.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderContext, ProviderDefinition } from "../types";
+import type { ProviderContext, ProviderDefinition } from "../types.js";
 export declare function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean;
 /**
  * Execute a provider operation by calling its handler.

package/dist/runtime/executor.js

@@ -1,5 +1,7 @@
-import { ProviderError, SessionExpiredError } from "../errors";
-import { parseSchema } from "../schema";
+import { isSessionExpiredError, isValidationError, ProviderError, SessionExpiredError, ValidationError, } from "../errors.js";
+import { z } from "zod";
+import { parseSchema } from "../schema.js";
+import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
     const kind = provider.operations[operationId]?.transport?.kind ?? "json";
     return kind !== "json";
@@ -23,6 +25,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }
+    // SDK-owned secret presence gate (single source of truth): declared
+    // `required: true` secrets are validated here, before input parsing and the
+    // handler, so every invocation path (serve /v1, self-test probes, perf,
+    // record) fails with the same structured MISSING_SECRET error instead of a
+    // handler-specific crash. Providers must not re-check presence locally.
+    assertRequiredSecretsPresent(provider, ctx.env);
     const validatedInput = await parseSchema(operation.input, input, `operations.${operationId}.input`);
     const execute = () => ctx.trace.span(`handler:${operationId}`, () => Promise.resolve(operation.handler(ctx, validatedInput)));
     let result;
@@ -39,7 +47,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
         // operation is safe to re-drive after refresh, which we signal by marking
         // the surfaced error retryable; non-idempotent operations (the default)
         // stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
-        if (error instanceof SessionExpiredError && operation.retryOnAuthRefresh) {
+        // Use the branded guard, not `instanceof`: a handler loaded through a
+        // duplicate/published SDK module can throw a correctly branded
+        // SessionExpiredError whose constructor identity differs from this
+        // 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 });
         }
         throw error;
@@ -47,5 +60,19 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     if (isStreamingOperation(provider, operationId)) {
         return result;
     }
-    return parseSchema(operation.output, result, `operations.${operationId}.output`);
+    try {
+        return await parseSchema(operation.output, result, `operations.${operationId}.output`);
+    }
+    catch (cause) {
+        if (!(cause instanceof z.ZodError) && !isValidationError(cause)) {
+            throw cause;
+        }
+        throw new ValidationError(`Operation handler output failed schema validation.`, {
+            code: "OUTPUT_VALIDATION_FAILED",
+            category: "output_validation",
+            retryable: false,
+            zodError: isValidationError(cause) ? cause.zodError : cause,
+            ...(cause instanceof Error ? { cause } : {}),
+        });
+    }
 }

package/dist/runtime/http.d.ts

@@ -1,5 +1,5 @@
-import type { ProxyResolutionOptions } from "../config/loader";
-import type { HttpClient, HttpRetrySummary } from "../types";
+import type { ProxyResolutionOptions } from "../config/loader.js";
+import type { HttpClient, HttpRetrySummary } from "../types.js";
 export type HttpClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
     userAgent?: string;