@apifuse/provider-sdk 2.1.0-beta.0 → 2.1.0-beta.10

package/bin/apifuse.ts

@@ -28,7 +28,7 @@ await module.main();
 
 function printHelp() {
 	console.log(`
-apifuse - ApiFuse Provider SDK CLI
+apifuse - APIFuse Provider SDK CLI
 
 Commands:`);
 	for (const name of COMMAND_ORDER) {

package/dist/ceremonies/index.d.ts

@@ -0,0 +1,41 @@
+import type { AuthFlowDefinition, AuthTurn } from "../types";
+type JsonObject = Record<string, unknown>;
+export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
+export declare function createOAuth2Ceremony(options: {
+    authorizeUrl: string;
+    tokenUrl: string;
+    clientIdEnvKey: string;
+    clientSecretEnvKey: string;
+    scopes: string[];
+    usePKCE?: boolean;
+}): AuthFlowDefinition;
+export declare function createDeviceFlowCeremony(options: {
+    deviceCodeUrl: string;
+    tokenUrl: string;
+    clientIdEnvKey: string;
+    clientSecretEnvKey?: string;
+    scopes: string[];
+}): AuthFlowDefinition;
+export declare function createWebAuthnCeremony(options: {
+    rpId: string;
+    challengeUrl?: string;
+    verifyUrl?: string;
+    timeoutMs?: number;
+}): AuthFlowDefinition;
+export declare function createMagicLinkCeremony(options: {
+    sendUrl: string;
+    verifyUrl: string;
+    emailField?: string;
+    expiresInMs?: number;
+}): AuthFlowDefinition;
+export declare function createFormCeremony(options: {
+    schema: JsonObject;
+    hint?: string;
+    mapCredential?: (input: Record<string, unknown>) => JsonObject;
+}): AuthFlowDefinition;
+export declare function combineCeremonies(...ceremonies: AuthFlowDefinition[]): AuthFlowDefinition;
+export declare function createSwitchCeremony(options: {
+    choices: Record<string, AuthFlowDefinition>;
+    prompt?: string;
+}): AuthFlowDefinition;
+export {};

package/dist/ceremonies/index.js

@@ -0,0 +1,490 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import Ajv from "ajv";
+import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors";
+const ajv = new Ajv({ allErrors: true, strict: true, strictSchema: true });
+const authTurnSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["kind", "turnId"],
+    properties: {
+        kind: { type: "string", minLength: 1 },
+        turnId: { type: "string", minLength: 1 },
+        expiresAt: { type: "string", minLength: 1 },
+        data: {
+            type: "object",
+            additionalProperties: true,
+        },
+        expectedInput: {
+            type: "object",
+            additionalProperties: true,
+        },
+        hint: { type: "string" },
+        hintKey: { type: "string" },
+        timing: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                suggestedPollIntervalMs: { type: "number", minimum: 1 },
+                maxWaitMs: { type: "number", minimum: 1 },
+            },
+        },
+    },
+};
+const validateAuthTurn = ajv.compile(authTurnSchema);
+const OAUTH2_STATE_KEY = "__oauth2_state";
+const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
+const DEVICE_FLOW_KEY = "__device_flow";
+const MAGIC_LINK_KEY = "__magic_link";
+const COMBINED_STAGE_KEY = "__combined_stage";
+const SWITCH_SELECTION_KEY = "__switch_selection";
+const FORM_FIELD_ORDER_EXTENSION = "x-apifuse-field-order";
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function ensureRecord(value) {
+    return isRecord(value) ? value : {};
+}
+function createTurn(kind, options = {}) {
+    return {
+        kind,
+        turnId: randomUUID(),
+        ...options,
+    };
+}
+function createExpiresAt(ttlMs) {
+    return new Date(Date.now() + ttlMs).toISOString();
+}
+function getRequiredEnv(ctx, key) {
+    const value = ctx.env.get(key);
+    if (!value) {
+        throw new ProviderSecretError(`Missing required secret: ${key}`);
+    }
+    return value;
+}
+function toBase64Url(input) {
+    return input
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
+}
+function createCodeVerifier() {
+    return toBase64Url(randomBytes(32));
+}
+function createCodeChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error("Unexpected ceremony error");
+}
+function toRetryTurn(error, hint) {
+    const normalizedError = normalizeError(error);
+    if (normalizedError instanceof FlowExpiredError) {
+        return validateCeremonyOutput(createTurn("abort", {
+            hint: normalizedError.message,
+            data: { code: normalizedError.code ?? "flow_expired" },
+        }));
+    }
+    const retryData = normalizedError instanceof ValidationError
+        ? { errors: normalizedError.zodError }
+        : { error: normalizedError.message };
+    return validateCeremonyOutput(createTurn("retry", {
+        hint: `${hint}: ${normalizedError.message}`,
+        data: retryData,
+    }));
+}
+async function runCeremonyHandler(handler, hint, ctx, input) {
+    try {
+        return validateCeremonyOutput(await handler(ctx, input));
+    }
+    catch (error) {
+        return toRetryTurn(error, hint);
+    }
+}
+function getString(input, key) {
+    const value = input[key];
+    return typeof value === "string" ? value : undefined;
+}
+function getNestedRecord(ctx, key) {
+    return ensureRecord(ctx.context.get(key));
+}
+function buildJsonSchemaForm(expectedInput, hint) {
+    return createTurn("form", {
+        hint,
+        expectedInput: withDeclaredFormFieldOrder(expectedInput),
+        data: {},
+    });
+}
+function withDeclaredFormFieldOrder(expectedInput) {
+    const properties = expectedInput.properties;
+    if (!isRecord(properties)) {
+        return expectedInput;
+    }
+    const existingOrder = expectedInput[FORM_FIELD_ORDER_EXTENSION];
+    if (Array.isArray(existingOrder) &&
+        existingOrder.every((value) => typeof value === "string")) {
+        return expectedInput;
+    }
+    return {
+        ...expectedInput,
+        [FORM_FIELD_ORDER_EXTENSION]: Object.keys(properties),
+    };
+}
+export function validateCeremonyOutput(turn) {
+    if (!validateAuthTurn(turn)) {
+        const detail = validateAuthTurn.errors
+            ?.map((error) => `${error.instancePath || "$"} ${error.message ?? "invalid"}`)
+            .join("; ");
+        throw new TurnValidationError(detail || "Invalid AuthTurn output");
+    }
+    return turn;
+}
+export function createOAuth2Ceremony(options) {
+    return {
+        start: (ctx) => runCeremonyHandler(async () => {
+            const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
+            getRequiredEnv(ctx, options.clientSecretEnvKey);
+            const state = toBase64Url(randomBytes(24));
+            ctx.context.set(OAUTH2_STATE_KEY, state);
+            const authorizeUrl = new URL(options.authorizeUrl);
+            authorizeUrl.searchParams.set("response_type", "code");
+            authorizeUrl.searchParams.set("client_id", clientId);
+            authorizeUrl.searchParams.set("state", state);
+            if (options.scopes.length > 0) {
+                authorizeUrl.searchParams.set("scope", options.scopes.join(" "));
+            }
+            if (options.usePKCE) {
+                const verifier = createCodeVerifier();
+                ctx.context.set(OAUTH2_PKCE_VERIFIER_KEY, verifier);
+                authorizeUrl.searchParams.set("code_challenge", createCodeChallenge(verifier));
+                authorizeUrl.searchParams.set("code_challenge_method", "S256");
+            }
+            return createTurn("redirect", {
+                data: { url: authorizeUrl.toString() },
+                hint: "Open the provider authorization page to continue.",
+                expectedInput: {
+                    type: "object",
+                    required: ["code", "state"],
+                    properties: {
+                        code: { type: "string" },
+                        state: { type: "string" },
+                    },
+                },
+            });
+        }, "OAuth start failed", ctx),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
+            const code = getString(input, "code");
+            const receivedState = getString(input, "state");
+            const storedState = ctx.context.get(OAUTH2_STATE_KEY);
+            const codeVerifier = ctx.context.get(OAUTH2_PKCE_VERIFIER_KEY);
+            if (!code || !receivedState || receivedState !== storedState) {
+                throw new ValidationError("OAuth callback payload is invalid.");
+            }
+            const tokenResponse = await ctx.http.post(options.tokenUrl, {
+                grant_type: "authorization_code",
+                code,
+                client_id: getRequiredEnv(ctx, options.clientIdEnvKey),
+                client_secret: getRequiredEnv(ctx, options.clientSecretEnvKey),
+                ...(options.usePKCE
+                    ? typeof codeVerifier === "string"
+                        ? { code_verifier: codeVerifier }
+                        : {}
+                    : {}),
+            });
+            return createTurn("complete", {
+                data: { credential: ensureRecord(tokenResponse.data) },
+                hint: "OAuth flow completed.",
+            });
+        }, "OAuth token exchange failed", ctx, input),
+        abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
+    };
+}
+export function createDeviceFlowCeremony(options) {
+    return {
+        start: (ctx) => runCeremonyHandler(async () => {
+            const response = await ctx.http.post(options.deviceCodeUrl, {
+                client_id: getRequiredEnv(ctx, options.clientIdEnvKey),
+                scope: options.scopes.join(" "),
+            });
+            const data = ensureRecord(response.data);
+            ctx.context.set(DEVICE_FLOW_KEY, data);
+            return createTurn("message", {
+                data: {
+                    user_code: getString(data, "user_code") ?? "",
+                    verification_uri: getString(data, "verification_uri") ?? "",
+                },
+                hint: "Enter the code on the verification page, then poll for completion.",
+                timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 120_000 },
+            });
+        }, "Device flow start failed", ctx),
+        continue: async () => validateCeremonyOutput(createTurn("poll", {
+            hint: "Continue polling until the device flow completes.",
+            timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 120_000 },
+        })),
+        poll: (ctx) => runCeremonyHandler(async () => {
+            const deviceData = getNestedRecord(ctx, DEVICE_FLOW_KEY);
+            const deviceCode = getString(deviceData, "device_code");
+            if (!deviceCode) {
+                throw new FlowExpiredError("Device flow state is missing.");
+            }
+            const response = await ctx.http.post(options.tokenUrl, {
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: deviceCode,
+                client_id: getRequiredEnv(ctx, options.clientIdEnvKey),
+                ...(options.clientSecretEnvKey
+                    ? {
+                        client_secret: getRequiredEnv(ctx, options.clientSecretEnvKey),
+                    }
+                    : {}),
+            });
+            const data = ensureRecord(response.data);
+            const errorCode = getString(data, "error");
+            if (errorCode === "authorization_pending" ||
+                errorCode === "slow_down") {
+                return createTurn("poll", {
+                    data,
+                    hint: "Authorization pending.",
+                    timing: {
+                        suggestedPollIntervalMs: errorCode === "slow_down" ? 10_000 : 5_000,
+                        maxWaitMs: 120_000,
+                    },
+                });
+            }
+            if (errorCode === "expired_token") {
+                throw new FlowExpiredError("Device code expired.");
+            }
+            return createTurn("complete", {
+                data: { credential: data },
+                hint: "Device flow completed.",
+            });
+        }, "Device flow polling failed", ctx),
+        abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
+    };
+}
+export function createWebAuthnCeremony(options) {
+    return {
+        start: (ctx) => runCeremonyHandler(async () => {
+            const challenge = toBase64Url(randomBytes(32));
+            ctx.context.set("__webauthn_challenge", challenge);
+            if (options.challengeUrl) {
+                await ctx.http.post(options.challengeUrl, {
+                    challenge,
+                    rpId: options.rpId,
+                });
+            }
+            return createTurn("challenge", {
+                data: { challenge, rpId: options.rpId },
+                hint: "Complete the WebAuthn prompt in your browser.",
+                expiresAt: createExpiresAt(options.timeoutMs ?? 60_000),
+                expectedInput: {
+                    type: "object",
+                    required: ["attestation"],
+                    properties: { attestation: { type: "object" } },
+                },
+            });
+        }, "WebAuthn start failed", ctx),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
+            if (!isRecord(input.attestation)) {
+                throw new ValidationError("WebAuthn attestation is required.");
+            }
+            const challenge = ctx.context.get("__webauthn_challenge");
+            if (typeof challenge !== "string" || challenge.length === 0) {
+                throw new FlowExpiredError("WebAuthn challenge has expired.");
+            }
+            if (options.verifyUrl) {
+                await ctx.http.post(options.verifyUrl, {
+                    challenge,
+                    attestation: input.attestation,
+                    rpId: options.rpId,
+                });
+            }
+            return createTurn("complete", {
+                data: { credential: { attestation: input.attestation } },
+                hint: "WebAuthn ceremony completed.",
+            });
+        }, "WebAuthn verification failed", ctx, input),
+        abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
+    };
+}
+export function createMagicLinkCeremony(options) {
+    const emailField = options.emailField ?? "email";
+    return {
+        start: (ctx, input = {}) => runCeremonyHandler(async () => {
+            const email = getString(input, emailField);
+            if (!email) {
+                return buildJsonSchemaForm({
+                    type: "object",
+                    required: [emailField],
+                    properties: {
+                        [emailField]: { type: "string", format: "email" },
+                    },
+                }, "Provide the email address to receive a magic link.");
+            }
+            await ctx.http.post(options.sendUrl, { email });
+            ctx.context.set(MAGIC_LINK_KEY, {
+                email,
+                expiresAt: createExpiresAt(options.expiresInMs ?? 300_000),
+            });
+            return createTurn("message", {
+                data: { email },
+                hint: "Check your email for the magic link, then poll for completion.",
+                timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
+            });
+        }, "Magic link start failed", ctx, input),
+        continue: async () => validateCeremonyOutput(createTurn("poll", {
+            hint: "Continue polling for magic link completion.",
+            timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
+        })),
+        poll: (ctx) => runCeremonyHandler(async () => {
+            const state = getNestedRecord(ctx, MAGIC_LINK_KEY);
+            const email = getString(state, "email");
+            const expiresAt = getString(state, "expiresAt");
+            if (!email || !expiresAt) {
+                throw new FlowExpiredError("Magic link state is missing.");
+            }
+            if (new Date(expiresAt).getTime() < Date.now()) {
+                throw new FlowExpiredError("Magic link expired.");
+            }
+            const response = await ctx.http.post(options.verifyUrl, { email });
+            const data = ensureRecord(response.data);
+            if (data.completed !== true) {
+                return createTurn("poll", {
+                    data,
+                    hint: "Waiting for the magic link click.",
+                    timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
+                });
+            }
+            return createTurn("complete", {
+                data: { credential: ensureRecord(data.credential) },
+                hint: "Magic link completed.",
+            });
+        }, "Magic link polling failed", ctx),
+        abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
+    };
+}
+export function createFormCeremony(options) {
+    return {
+        start: async () => validateCeremonyOutput(buildJsonSchemaForm(options.schema, options.hint ?? "Provide the required input to continue.")),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
+            const { prevalidate } = await import("../runtime/prevalidate");
+            const result = prevalidate(options.schema, input);
+            if (!result.valid) {
+                throw new ValidationError("Form input failed validation.", {
+                    zodError: result.errors,
+                });
+            }
+            return createTurn("complete", {
+                data: {
+                    credential: options.mapCredential
+                        ? options.mapCredential(input)
+                        : input,
+                },
+                hint: "Form completed.",
+            });
+        }, "Form submission failed", ctx, input),
+        abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
+    };
+}
+export function combineCeremonies(...ceremonies) {
+    function getStage(ctx) {
+        const rawStage = ctx.context.get(COMBINED_STAGE_KEY);
+        return typeof rawStage === "number" ? rawStage : 0;
+    }
+    return {
+        start: (ctx) => runCeremonyHandler(async () => {
+            ctx.context.set(COMBINED_STAGE_KEY, 0);
+            const first = ceremonies[0];
+            if (!first) {
+                throw new ValidationError("At least one ceremony is required.");
+            }
+            return await first.start(ctx);
+        }, "Combined ceremony start failed", ctx),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
+            const stage = getStage(ctx);
+            const current = ceremonies[stage];
+            if (!current) {
+                throw new FlowExpiredError("Combined ceremony stage is invalid.");
+            }
+            const result = await current.continue(ctx, input);
+            if (result.kind !== "complete") {
+                return result;
+            }
+            const nextStage = stage + 1;
+            const nextCeremony = ceremonies[nextStage];
+            if (!nextCeremony) {
+                return result;
+            }
+            ctx.context.set(COMBINED_STAGE_KEY, nextStage);
+            return await nextCeremony.start(ctx);
+        }, "Combined ceremony continue failed", ctx, input),
+        poll: (ctx) => runCeremonyHandler(async () => {
+            const current = ceremonies[getStage(ctx)];
+            if (!current?.poll) {
+                throw new ValidationError("Current ceremony does not support polling.");
+            }
+            return await current.poll(ctx);
+        }, "Combined ceremony poll failed", ctx),
+        abort: (ctx) => runCeremonyHandler(async () => {
+            const current = ceremonies[getStage(ctx)];
+            if (current?.abort) {
+                return await current.abort(ctx);
+            }
+            return createTurn("abort", { hint: "Combined ceremony aborted." });
+        }, "Combined ceremony abort failed", ctx),
+    };
+}
+export function createSwitchCeremony(options) {
+    const choiceKeys = Object.keys(options.choices);
+    return {
+        start: async () => validateCeremonyOutput(createTurn("multi_choice", {
+            data: { choices: choiceKeys },
+            hint: options.prompt ?? "Choose an authentication method.",
+            expectedInput: {
+                type: "object",
+                required: ["choice"],
+                properties: {
+                    choice: { type: "string", enum: choiceKeys },
+                },
+            },
+        })),
+        continue: (ctx, input = {}) => runCeremonyHandler(async () => {
+            const storedChoice = ctx.context.get(SWITCH_SELECTION_KEY);
+            const choice = typeof storedChoice === "string"
+                ? storedChoice
+                : getString(input, "choice");
+            if (!choice || !options.choices[choice]) {
+                throw new ValidationError("A valid choice is required.");
+            }
+            ctx.context.set(SWITCH_SELECTION_KEY, choice);
+            const ceremony = options.choices[choice];
+            if (storedChoice === undefined) {
+                return await ceremony.start(ctx);
+            }
+            return await ceremony.continue(ctx, input);
+        }, "Switch ceremony failed", ctx, input),
+        poll: (ctx) => runCeremonyHandler(async () => {
+            const choice = ctx.context.get(SWITCH_SELECTION_KEY);
+            if (typeof choice !== "string") {
+                throw new FlowExpiredError("No selected ceremony is active.");
+            }
+            const ceremony = options.choices[choice];
+            if (!ceremony?.poll) {
+                throw new ValidationError("Selected ceremony does not support polling.");
+            }
+            return await ceremony.poll(ctx);
+        }, "Switch ceremony poll failed", ctx),
+        abort: (ctx) => runCeremonyHandler(async () => {
+            const choice = ctx.context.get(SWITCH_SELECTION_KEY);
+            if (typeof choice === "string") {
+                const ceremony = options.choices[choice];
+                if (ceremony?.abort) {
+                    return await ceremony.abort(ctx);
+                }
+            }
+            return createTurn("abort", { hint: "Switch ceremony aborted." });
+        }, "Switch ceremony abort failed", ctx),
+    };
+}

package/dist/choice-token.d.ts

@@ -0,0 +1,24 @@
+export type ProviderChoiceTokenPayload = Record<string, unknown>;
+export type ProviderChoiceTokenErrorReason = "invalid_shape" | "invalid_signature" | "invalid_payload" | "invalid_binding" | "stale";
+export declare class ProviderChoiceTokenError extends Error {
+    readonly reason: ProviderChoiceTokenErrorReason;
+    constructor(reason: ProviderChoiceTokenErrorReason, message: string);
+}
+export interface CreateProviderChoiceTokenOptions<TPayload extends ProviderChoiceTokenPayload> {
+    prefix: string;
+    payload: TPayload;
+    secret: string;
+}
+export interface ParseProviderChoiceTokenOptions {
+    token: string;
+    prefix: string;
+    secret: string;
+}
+export interface FreshProviderChoiceIssuedAtOptions {
+    ttlMs: number;
+    nowMs?: number;
+    futureToleranceMs?: number;
+}
+export declare function createProviderChoiceToken<TPayload extends ProviderChoiceTokenPayload>(options: CreateProviderChoiceTokenOptions<TPayload>): string;
+export declare function parseProviderChoiceToken(options: ParseProviderChoiceTokenOptions): ProviderChoiceTokenPayload;
+export declare function assertFreshProviderChoiceIssuedAt(issuedAtMs: unknown, options: FreshProviderChoiceIssuedAtOptions): number;

package/dist/choice-token.js

@@ -0,0 +1,74 @@
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
+export class ProviderChoiceTokenError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "ProviderChoiceTokenError";
+        this.reason = reason;
+    }
+}
+export function createProviderChoiceToken(options) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", choiceEncryptionKey(options.secret), iv);
+    const encryptedPayload = Buffer.concat([
+        cipher.update(JSON.stringify(options.payload), "utf8"),
+        cipher.final(),
+    ]).toString("base64url");
+    const authTag = cipher.getAuthTag().toString("base64url");
+    const encodedIv = iv.toString("base64url");
+    const signature = signProviderChoiceTokenBody(`${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`, options.secret);
+    return `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}.${signature}`;
+}
+export function parseProviderChoiceToken(options) {
+    const [actualPrefix, encodedIv, encryptedPayload, authTag, signature, ...extra] = options.token.split(".");
+    if (actualPrefix !== options.prefix ||
+        !encodedIv ||
+        !encryptedPayload ||
+        !authTag ||
+        !signature ||
+        extra.length > 0) {
+        throw new ProviderChoiceTokenError("invalid_shape", "Provider choice token shape is invalid.");
+    }
+    const signedBody = `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`;
+    const expectedSignature = signProviderChoiceTokenBody(signedBody, options.secret);
+    const actualBuffer = Buffer.from(signature);
+    const expectedBuffer = Buffer.from(expectedSignature);
+    if (actualBuffer.length !== expectedBuffer.length ||
+        !timingSafeEqual(actualBuffer, expectedBuffer)) {
+        throw new ProviderChoiceTokenError("invalid_signature", "Provider choice token signature is invalid.");
+    }
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", choiceEncryptionKey(options.secret), Buffer.from(encodedIv, "base64url"));
+        decipher.setAuthTag(Buffer.from(authTag, "base64url"));
+        const decrypted = Buffer.concat([
+            decipher.update(Buffer.from(encryptedPayload, "base64url")),
+            decipher.final(),
+        ]).toString("utf8");
+        const parsed = JSON.parse(decrypted);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("payload is not an object");
+        }
+        return Object.fromEntries(Object.entries(parsed));
+    }
+    catch {
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token payload is invalid.");
+    }
+}
+export function assertFreshProviderChoiceIssuedAt(issuedAtMs, options) {
+    const parsed = typeof issuedAtMs === "number" ? issuedAtMs : Number(issuedAtMs);
+    const nowMs = options.nowMs ?? Date.now();
+    const futureToleranceMs = options.futureToleranceMs ?? 30_000;
+    if (!Number.isFinite(parsed) ||
+        parsed <= 0 ||
+        nowMs - parsed > options.ttlMs ||
+        parsed - nowMs > futureToleranceMs) {
+        throw new ProviderChoiceTokenError("stale", "Provider choice token is stale.");
+    }
+    return parsed;
+}
+function choiceEncryptionKey(secret) {
+    return createHash("sha256").update(secret).digest();
+}
+function signProviderChoiceTokenBody(body, secret) {
+    return createHmac("sha256", secret).update(body).digest("base64url");
+}

package/dist/cli/commands.d.ts

@@ -0,0 +1,10 @@
+export type ApifuseCommandName = "create" | "dev" | "check" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
+export type ApifuseCommandManifest = {
+    name: ApifuseCommandName;
+    summary: string;
+    usage: string;
+    examples: string[];
+    modulePath: string;
+};
+export declare const COMMAND_MANIFEST: Record<ApifuseCommandName, ApifuseCommandManifest>;
+export declare const COMMAND_ORDER: ApifuseCommandName[];