@apifuse/provider-sdk 2.1.0-beta.6 → 2.1.0-beta.8

package/dist/runtime/choice.js

@@ -0,0 +1,435 @@
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
+import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token";
+import { ProviderError } from "../errors";
+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;
+export function createProviderChoiceContext(options) {
+    const kid = options.kid ?? PRIMARY_CHOICE_TOKEN_KID;
+    const resolveMasterSecret = () => resolveChoiceMasterSecret(options);
+    function issue(issueOptions) {
+        const issuedAtMs = issueOptions.nowMs ?? Date.now();
+        const keys = deriveManagedChoiceKeys({
+            masterSecret: resolveMasterSecret(),
+            providerId: options.providerId,
+            purpose: issueOptions.purpose,
+            kid,
+        });
+        const baseEnvelope = {
+            v: MANAGED_CHOICE_TOKEN_VERSION,
+            provider_id: options.providerId,
+            purpose: issueOptions.purpose,
+            issued_at_ms: issuedAtMs,
+            ttl_ms: issueOptions.ttlMs,
+            binding: createChoiceBinding({
+                keys,
+                options: issueOptions.bind,
+                request: options.request,
+                credential: options.credential,
+                required: true,
+            }),
+        };
+        const resolvedStorage = resolveIssueStorage(issueOptions.storage, issueOptions.payload);
+        if (resolvedStorage.mode === "server") {
+            return issueServerStoredChoice({
+                baseEnvelope,
+                issueOptions,
+                storage: resolvedStorage.storage,
+                contextState: options.state,
+                kid,
+                keys,
+                issuedAtMs,
+            });
+        }
+        const envelope = {
+            ...baseEnvelope,
+            payload: issueOptions.payload,
+        };
+        return encryptManagedChoiceToken({
+            prefix: issueOptions.prefix,
+            kid,
+            envelope,
+            keys,
+        });
+    }
+    function parse(parseOptions) {
+        const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature,] = parseManagedChoiceTokenParts(parseOptions.token);
+        if (actualPrefix !== parseOptions.prefix ||
+            tokenKid !== kid ||
+            !encodedIv ||
+            !encryptedPayload ||
+            !authTag ||
+            !signature) {
+            throw new ProviderChoiceTokenError("invalid_shape", "Provider choice token shape is invalid.");
+        }
+        const keys = deriveManagedChoiceKeys({
+            masterSecret: resolveMasterSecret(),
+            providerId: options.providerId,
+            purpose: parseOptions.purpose,
+            kid: tokenKid,
+        });
+        const signedBody = [
+            parseOptions.prefix,
+            tokenKid,
+            encodedIv,
+            encryptedPayload,
+            authTag,
+        ].join(".");
+        assertManagedChoiceSignature({
+            signedBody,
+            signature,
+            signingKey: keys.signing,
+        });
+        const envelope = decryptManagedChoiceToken({
+            encodedIv,
+            encryptedPayload,
+            authTag,
+            encryptionKey: keys.encryption,
+        });
+        assertManagedChoiceEnvelope(envelope, {
+            providerId: options.providerId,
+            purpose: parseOptions.purpose,
+            ttlMs: parseOptions.ttlMs,
+            nowMs: parseOptions.nowMs,
+            futureToleranceMs: parseOptions.futureToleranceMs,
+        });
+        assertChoiceBindingMatches({
+            actual: envelope.binding,
+            expected: createChoiceBinding({
+                keys,
+                options: parseOptions.bind,
+                request: options.request,
+                credential: options.credential,
+                required: true,
+            }),
+        });
+        if (isServerChoiceHandlePayload(envelope.payload)) {
+            return parseServerStoredChoice({
+                handle: envelope.payload,
+                storage: parseOptions.storage,
+                contextState: options.state,
+            });
+        }
+        return envelope.payload;
+    }
+    return { issue, parse };
+}
+export function createTestProviderChoiceContext(options) {
+    return createProviderChoiceContext({
+        ...options,
+        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 trimmed = configured?.trim();
+    if (trimmed)
+        return trimmed;
+    throw new ProviderError("Provider runtime choice-token master secret is not configured.", {
+        code: "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+        category: "internal_error",
+        retryable: false,
+        details: {
+            secret: PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+        },
+    });
+}
+function deriveManagedChoiceKeys(input) {
+    return {
+        encryption: deriveManagedChoiceKey(input, "encryption"),
+        signing: deriveManagedChoiceKey(input, "signing"),
+        binding: deriveManagedChoiceKey(input, "binding"),
+    };
+}
+function deriveManagedChoiceKey(input, usage) {
+    return createHmac("sha256", input.masterSecret)
+        .update("apifuse-provider-choice-token")
+        .update("\0")
+        .update(input.providerId)
+        .update("\0")
+        .update(input.purpose)
+        .update("\0")
+        .update(input.kid)
+        .update("\0")
+        .update(usage)
+        .digest();
+}
+function encryptManagedChoiceToken(options) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", options.keys.encryption, iv);
+    const encryptedPayload = Buffer.concat([
+        cipher.update(JSON.stringify(options.envelope), "utf8"),
+        cipher.final(),
+    ]).toString("base64url");
+    const authTag = cipher.getAuthTag().toString("base64url");
+    const encodedIv = iv.toString("base64url");
+    const signedBody = [
+        options.prefix,
+        options.kid,
+        encodedIv,
+        encryptedPayload,
+        authTag,
+    ].join(".");
+    const signature = createHmac("sha256", options.keys.signing)
+        .update(signedBody)
+        .digest("base64url");
+    return `${signedBody}.${signature}`;
+}
+async function issueServerStoredChoice(options) {
+    const serializedPayload = serializeChoicePayload(options.issueOptions.payload);
+    const payloadBytes = Buffer.byteLength(serializedPayload, "utf8");
+    if (payloadBytes > options.storage.maxValueBytes) {
+        throw new ProviderError("Provider choice payload exceeds state storage policy.", {
+            code: "CHOICE_STATE_PAYLOAD_TOO_LARGE",
+            category: "input_validation",
+            retryable: false,
+            details: {
+                maxValueBytes: options.storage.maxValueBytes,
+                payloadBytes,
+            },
+        });
+    }
+    const stateId = `choice_${randomBytes(16).toString("base64url")}`;
+    const digest = digestChoicePayload(serializedPayload);
+    const namespace = resolveChoiceStateNamespace({
+        storage: options.storage,
+        contextState: options.contextState,
+        ttlMs: options.issueOptions.ttlMs,
+    });
+    await namespace.set(optionsStateKey(stateId), options.issueOptions.payload, {
+        ttl: stateTtl(options.storage, options.issueOptions.ttlMs),
+    });
+    const envelope = {
+        ...options.baseEnvelope,
+        payload: {
+            storage: "server",
+            state_id: stateId,
+            payload_digest: digest,
+            created_at_ms: options.issuedAtMs,
+        },
+    };
+    return encryptManagedChoiceToken({
+        prefix: options.issueOptions.prefix,
+        kid: options.kid,
+        envelope,
+        keys: options.keys,
+    });
+}
+async function parseServerStoredChoice(options) {
+    const storage = resolveParseStorage(options.storage);
+    const namespace = resolveChoiceStateNamespace({
+        storage,
+        contextState: options.contextState,
+    });
+    const record = await namespace.get(optionsStateKey(options.handle.state_id));
+    if (!record) {
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload is missing.");
+    }
+    const serializedPayload = serializeChoicePayload(record.value);
+    assertPayloadDigestMatches({
+        actual: digestChoicePayload(serializedPayload),
+        expected: options.handle.payload_digest,
+    });
+    return record.value;
+}
+function resolveIssueStorage(storage, payload) {
+    if (!storage || storage.mode === "inline")
+        return { mode: "inline" };
+    if (storage.mode === "server")
+        return { mode: "server", storage };
+    const payloadBytes = Buffer.byteLength(serializeChoicePayload(payload), "utf8");
+    if (payloadBytes <= storage.maxInlineBytes)
+        return { mode: "inline" };
+    return { mode: "server", storage };
+}
+function resolveParseStorage(storage) {
+    if (!storage || storage.mode === "inline") {
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token requires server-side choice storage.");
+    }
+    return storage;
+}
+function resolveChoiceStateNamespace(options) {
+    const state = options.storage.state ?? options.contextState;
+    if (!state) {
+        throw new ProviderError("Provider choice state storage is not available.", {
+            code: "CHOICE_STATE_UNAVAILABLE",
+            category: "internal_error",
+            retryable: false,
+        });
+    }
+    return state.namespace(options.storage.namespace, {
+        defaultTtl: stateTtl(options.storage, options.ttlMs),
+        maxTtl: stateTtl(options.storage, options.ttlMs),
+        maxEntries: options.storage.maxEntries,
+        maxValueBytes: options.storage.maxValueBytes,
+    });
+}
+function stateTtl(storage, ttlMs) {
+    return storage.ttl ?? `${ttlMs ?? 1}ms`;
+}
+function optionsStateKey(stateId) {
+    return stateId;
+}
+function serializeChoicePayload(payload) {
+    return JSON.stringify(payload);
+}
+function digestChoicePayload(serializedPayload) {
+    return createHash("sha256").update(serializedPayload).digest("base64url");
+}
+function isServerChoiceHandlePayload(value) {
+    return (value.storage === "server" &&
+        typeof value.state_id === "string" &&
+        typeof value.payload_digest === "string" &&
+        typeof value.created_at_ms === "number");
+}
+function assertPayloadDigestMatches(options) {
+    const actual = Buffer.from(options.actual);
+    const expected = Buffer.from(options.expected);
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload digest is invalid.");
+    }
+}
+function parseManagedChoiceTokenParts(token) {
+    const parts = token.split(".");
+    if (parts.length !== 6) {
+        throw new ProviderChoiceTokenError("invalid_shape", "Provider choice token shape is invalid.");
+    }
+    return [parts[0], parts[1], parts[2], parts[3], parts[4], parts[5]];
+}
+function assertManagedChoiceSignature(options) {
+    const expected = createHmac("sha256", options.signingKey)
+        .update(options.signedBody)
+        .digest("base64url");
+    const actualBuffer = Buffer.from(options.signature);
+    const expectedBuffer = Buffer.from(expected);
+    if (actualBuffer.length !== expectedBuffer.length ||
+        !timingSafeEqual(actualBuffer, expectedBuffer)) {
+        throw new ProviderChoiceTokenError("invalid_signature", "Provider choice token signature is invalid.");
+    }
+}
+function decryptManagedChoiceToken(options) {
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", options.encryptionKey, Buffer.from(options.encodedIv, "base64url"));
+        decipher.setAuthTag(Buffer.from(options.authTag, "base64url"));
+        const decrypted = Buffer.concat([
+            decipher.update(Buffer.from(options.encryptedPayload, "base64url")),
+            decipher.final(),
+        ]).toString("utf8");
+        const parsed = JSON.parse(decrypted);
+        if (!isManagedChoiceEnvelope(parsed)) {
+            throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token payload is invalid.");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof ProviderChoiceTokenError) {
+            throw error;
+        }
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token payload is invalid.");
+    }
+}
+function isManagedChoiceEnvelope(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    if (!("payload" in value) || !isChoicePayload(value.payload))
+        return false;
+    return ("v" in value &&
+        value.v === MANAGED_CHOICE_TOKEN_VERSION &&
+        "provider_id" in value &&
+        typeof value.provider_id === "string" &&
+        "purpose" in value &&
+        typeof value.purpose === "string" &&
+        "issued_at_ms" in 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)));
+}
+function isChoicePayload(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isChoiceBinding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    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) {
+        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,
+        nowMs: options.nowMs,
+        futureToleranceMs: options.futureToleranceMs,
+    });
+}
+function createChoiceBinding(options) {
+    const connectionHash = options.options?.connection
+        ? hashRequiredConnection(options)
+        : undefined;
+    const credentialHash = options.options?.credentialKeys?.length
+        ? hashCredentialKeys(options)
+        : undefined;
+    if (!connectionHash && !credentialHash)
+        return undefined;
+    return {
+        ...(connectionHash ? { connection_hash: connectionHash } : {}),
+        ...(credentialHash ? { credential_hash: credentialHash } : {}),
+    };
+}
+function hashRequiredConnection(options) {
+    const connectionId = options.request?.connectionId;
+    if (!connectionId) {
+        if (!options.required)
+            return undefined;
+        throw new ProviderError("Provider choice tokens require connection context.", {
+            code: "CHOICE_CONTEXT_REQUIRED",
+            category: "input_validation",
+            retryable: false,
+        });
+    }
+    return createHmac("sha256", options.keys.binding)
+        .update("connection")
+        .update("\0")
+        .update(connectionId)
+        .digest("base64url");
+}
+function hashCredentialKeys(options) {
+    const credentialKeys = options.options?.credentialKeys ?? [];
+    const material = credentialKeys.map((key) => {
+        const value = options.credential?.get(key);
+        if (typeof value !== "string" || value.length === 0) {
+            throw new ProviderError("Provider choice tokens require configured credential binding.", {
+                code: "CHOICE_CONTEXT_REQUIRED",
+                category: "input_validation",
+                retryable: false,
+                details: { credentialKey: key },
+            });
+        }
+        return [key, value];
+    });
+    return createHmac("sha256", options.keys.binding)
+        .update("credential")
+        .update("\0")
+        .update(JSON.stringify(material))
+        .digest("base64url");
+}
+function assertChoiceBindingMatches(options) {
+    if (options.actual?.connection_hash !== options.expected?.connection_hash) {
+        throw new ProviderChoiceTokenError("invalid_binding", "Provider choice token connection binding is invalid.");
+    }
+    if (options.actual?.credential_hash !== options.expected?.credential_hash) {
+        throw new ProviderChoiceTokenError("invalid_binding", "Provider choice token credential binding is invalid.");
+    }
+}

package/dist/runtime/credential.d.ts

@@ -0,0 +1,8 @@
+import type { AuthMode, CredentialContext } from "../types";
+export interface CreateCredentialContextOptions {
+    allowedKeys?: string[];
+    mode?: AuthMode;
+    scopes?: string[];
+    values?: Record<string, string>;
+}
+export declare function createCredentialContext(options?: CreateCredentialContextOptions): CredentialContext;

package/dist/runtime/credential.js

@@ -0,0 +1,61 @@
+import { CredentialModeError } from "../errors";
+function getAllowedKeys(allowedKeys, values) {
+    if (allowedKeys) {
+        return allowedKeys;
+    }
+    return Object.keys(values);
+}
+function normalizeScopes(mode, values, scopes) {
+    if (mode !== "oauth2") {
+        return [];
+    }
+    if (scopes) {
+        return [...scopes];
+    }
+    const rawScopes = values.scope ?? values.scopes;
+    if (!rawScopes) {
+        return [];
+    }
+    return rawScopes
+        .split(/[\s,]+/)
+        .map((scope) => scope.trim())
+        .filter((scope) => scope.length > 0);
+}
+export function createCredentialContext(options = {}) {
+    const mode = options.mode ?? "none";
+    const values = options.values ?? {};
+    const allowedKeys = getAllowedKeys(options.allowedKeys, values);
+    const allowedKeySet = new Set(allowedKeys);
+    const normalizedScopes = normalizeScopes(mode, values, options.scopes);
+    return {
+        mode,
+        get(key) {
+            if (!allowedKeySet.has(key)) {
+                return undefined;
+            }
+            return values[key];
+        },
+        getAll() {
+            const result = {};
+            for (const key of allowedKeys) {
+                const value = values[key];
+                if (value !== undefined) {
+                    result[key] = value;
+                }
+            }
+            return result;
+        },
+        getAccessToken() {
+            if (mode !== "oauth2") {
+                throw new CredentialModeError("Access tokens are only available for oauth2 credential mode.");
+            }
+            return values.access_token;
+        },
+        getScopes() {
+            if (mode !== "oauth2") {
+                throw new CredentialModeError("OAuth scopes are only available for oauth2 credential mode.");
+            }
+            return [...normalizedScopes];
+        },
+    };
+}

package/dist/runtime/env.d.ts

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

package/dist/runtime/env.js

@@ -0,0 +1,10 @@
+export function createEnvContext(allowedKeys) {
+    return {
+        get(key) {
+            if (allowedKeys && !allowedKeys.includes(key)) {
+                return undefined;
+            }
+            return process.env[key];
+        },
+    };
+}

package/dist/runtime/executor.d.ts

@@ -0,0 +1,16 @@
+import type { ProviderContext, ProviderDefinition } from "../types";
+export declare function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean;
+/**
+ * Execute a provider operation by calling its handler.
+ *
+ * SDK auto-wraps every handler call with:
+ * 1. Input Zod validation
+ * 2. Auth auto-refresh (if auth configured)
+ * 3. Trace span
+ * 4. Output Zod validation
+ *
+ * @see openspec/provider-sdk/03-sdk-core.md §3.6
+ */
+export declare function executeOperation(provider: ProviderDefinition, operationId: string, ctx: ProviderContext, input: unknown, _options?: {
+    skipAuth?: boolean;
+}): Promise<unknown>;

package/dist/runtime/executor.js

@@ -0,0 +1,51 @@
+import { ProviderError, SessionExpiredError } from "../errors";
+import { parseSchema } from "../schema";
+export function isStreamingOperation(provider, operationId) {
+    const kind = provider.operations[operationId]?.transport?.kind ?? "json";
+    return kind !== "json";
+}
+/**
+ * Execute a provider operation by calling its handler.
+ *
+ * SDK auto-wraps every handler call with:
+ * 1. Input Zod validation
+ * 2. Auth auto-refresh (if auth configured)
+ * 3. Trace span
+ * 4. Output Zod validation
+ *
+ * @see openspec/provider-sdk/03-sdk-core.md §3.6
+ */
+export async function executeOperation(provider, operationId, ctx, input, _options) {
+    const operation = provider.operations[operationId];
+    if (!operation) {
+        throw new ProviderError(`Unknown operation: ${provider.id}/${operationId}`, {
+            code: "NOT_FOUND",
+            fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
+        });
+    }
+    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;
+    try {
+        result = await execute();
+    }
+    catch (error) {
+        // Session expiry is renewed by Credential Service via the /auth/refresh
+        // route, NOT in-process here: this executor cannot mutate ctx.credential,
+        // so an in-process retry would just repeat the call with the same stale
+        // credential (and risk repeating partial side-effects). Instead we surface
+        // the expiry so Credential Service refreshes and re-drives the operation
+        // with a fresh credential. `retryOnAuthRefresh` declares that this
+        // 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) {
+            throw new SessionExpiredError(error.message, { retryable: true });
+        }
+        throw error;
+    }
+    if (isStreamingOperation(provider, operationId)) {
+        return result;
+    }
+    return parseSchema(operation.output, result, `operations.${operationId}.output`);
+}

package/dist/runtime/http.d.ts

@@ -0,0 +1,8 @@
+import type { ProxyResolutionOptions } from "../config/loader";
+import type { HttpClient, HttpRetrySummary } from "../types";
+export type HttpClientOptions = ProxyResolutionOptions & {
+    warn?: (message: string) => void;
+    userAgent?: string;
+    onRetrySummary?: (summary: HttpRetrySummary) => void;
+};
+export declare function createHttpClient(baseUrl?: string, clientOptions?: HttpClientOptions): HttpClient;