@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/dist/auth.js

@@ -0,0 +1,427 @@
+import { AuthError, ProviderError } from "./errors.js";
+const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
+const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
+const DEFAULT_ABORT_TURN_ID = "auth.abort";
+const DEFAULT_FORM_TURN_ID = "auth.form";
+const DEFAULT_POLL_TURN_ID = "auth.poll";
+const SENSITIVE_ABORT_DATA_KEY_PATTERN = /(authorization|cookie|credential|header|html|password|secret|session|token|apikey)/i;
+function normalizedAuthDataKey(key) {
+    return key.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+function isPlainAuthJsonObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isSensitiveAuthDataKey(key) {
+    return SENSITIVE_ABORT_DATA_KEY_PATTERN.test(normalizedAuthDataKey(key));
+}
+function assertSafeAuthJson(value, path) {
+    if (value === null)
+        return;
+    if (typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw new AuthError(`Auth abort ${path} must be a finite number`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            assertSafeAuthJson(item, `${path}[${index}]`);
+        }
+        return;
+    }
+    if (value instanceof Error) {
+        throw new AuthError(`Auth abort ${path} must not include Error objects`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    if (typeof value !== "object") {
+        throw new AuthError(`Auth abort ${path} must be JSON-safe`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    if (!isPlainAuthJsonObject(value)) {
+        throw new AuthError(`Auth abort ${path} must be a plain JSON object`, {
+            code: "auth_abort_unsafe_data",
+        });
+    }
+    for (const [key, item] of Object.entries(value)) {
+        if (isSensitiveAuthDataKey(key)) {
+            throw new AuthError(`Auth abort ${path}.${key} must not include secrets`, {
+                code: "auth_abort_unsafe_data",
+            });
+        }
+        assertSafeAuthJson(item, `${path}.${key}`);
+    }
+}
+function assertSafeAuthData(data, path) {
+    assertSafeAuthJson(data, path);
+}
+function authTurnBase(options) {
+    return {
+        turnId: options.turnId ?? options.defaultTurnId,
+        ...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
+    };
+}
+function abortData(options) {
+    if (options.actionHint !== undefined) {
+        assertSafeAuthJson(options.actionHint, "actionHint");
+    }
+    if (options.data !== undefined) {
+        assertSafeAuthData(options.data, "data");
+    }
+    return {
+        code: options.code,
+        ...(options.message ? { message: options.message } : {}),
+        ...(options.retry ? { retry: options.retry } : {}),
+        ...(options.actionHint !== undefined ? { actionHint: options.actionHint } : {}),
+        ...(options.fieldErrors ? { fieldErrors: options.fieldErrors } : {}),
+        ...(options.data ? { details: options.data } : {}),
+    };
+}
+export function createAuthFlowHelpers(options = {}) {
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.deadline ? { deadline: options.deadline } : {}),
+        complete({ credential, metadata, data, turnId, expiresAt }) {
+            return {
+                kind: "complete",
+                ...authTurnBase({ turnId, defaultTurnId: DEFAULT_COMPLETE_TURN_ID, expiresAt }),
+                data: {
+                    ...(data ?? {}),
+                    credential,
+                    ...(metadata ? { metadata } : {}),
+                },
+            };
+        },
+        abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt }) {
+            return {
+                kind: "abort",
+                ...authTurnBase({ turnId, defaultTurnId: DEFAULT_ABORT_TURN_ID, expiresAt }),
+                data: abortData({
+                    code,
+                    message,
+                    retry,
+                    actionHint,
+                    fieldErrors,
+                    data,
+                }),
+            };
+        },
+        nextForm(options) {
+            return {
+                kind: "form",
+                ...authTurnBase({
+                    turnId: options.turnId,
+                    defaultTurnId: DEFAULT_FORM_TURN_ID,
+                    expiresAt: options.expiresAt,
+                }),
+                ...(options.hintKey ? { hintKey: options.hintKey } : {}),
+                ...(options.timing ? { timing: options.timing } : {}),
+                ...(options.data ? { data: options.data } : {}),
+                expectedInput: options.expectedInput ?? expectedInputFromFields(options.fields ?? {}),
+            };
+        },
+        nextPoll(options = {}) {
+            return {
+                kind: "poll",
+                ...authTurnBase({
+                    turnId: options.turnId,
+                    defaultTurnId: DEFAULT_POLL_TURN_ID,
+                    expiresAt: options.expiresAt,
+                }),
+                ...(options.hintKey ? { hintKey: options.hintKey } : {}),
+                ...(options.timing ? { timing: options.timing } : {}),
+                ...(options.data ? { data: options.data } : {}),
+            };
+        },
+    };
+}
+export class AuthAbortError extends AuthError {
+    turn;
+    constructor(options) {
+        super(options.message ?? options.code, {
+            code: options.code,
+            retryable: options.retry === "retry",
+        });
+        this.name = "AuthAbortError";
+        this.turn = createAuthFlowHelpers().abort(options);
+    }
+}
+export function credentialsAuthChallenge(challengeId, options = {}) {
+    return {
+        kind: "challenge",
+        challengeId,
+        ...options,
+    };
+}
+function expectedInputFromFields(fields) {
+    return {
+        type: "object",
+        properties: Object.fromEntries(Object.entries(fields).map(([name, field]) => [
+            name,
+            {
+                type: "string",
+                ...(field.type === "email" ? { format: "email" } : {}),
+                ...(field.type === "password" ? { format: "password" } : {}),
+                ...(field.type === "otp" ? { format: "otp" } : {}),
+                ...(field.labelKey ? { nameKey: field.labelKey } : {}),
+                ...(field.descriptionKey ? { descriptionKey: field.descriptionKey } : {}),
+                ...(field.placeholderKey ? { placeholderKey: field.placeholderKey } : {}),
+                ...(field.sensitive || field.type === "password" || field.type === "otp"
+                    ? { sensitive: true }
+                    : {}),
+            },
+        ])),
+        required: Object.entries(fields)
+            .filter(([, field]) => field.required !== false)
+            .map(([name]) => name),
+    };
+}
+function collectMissingFields(fields, input) {
+    return Object.entries(fields)
+        .filter(([, field]) => field.required !== false)
+        .map(([name]) => name)
+        .filter((name) => {
+        const value = input?.[name];
+        return typeof value !== "string" || value.trim().length === 0;
+    });
+}
+function normalizeInput(fields, input) {
+    const result = {};
+    for (const name of Object.keys(fields)) {
+        const value = input?.[name];
+        result[name] = typeof value === "string" ? value : "";
+    }
+    return result;
+}
+function assertCredentialKeys(credentialKeys, credential) {
+    const missing = credentialKeys.filter((key) => {
+        const value = credential[key];
+        return typeof value !== "string" || value.length === 0;
+    });
+    if (missing.length > 0) {
+        throw new ProviderError(`Credentials auth login completed without required credential key(s): ${missing.join(", ")}`, {
+            code: "credentials_auth_missing_credential_keys",
+            fix: "Return every credentialKeys entry from defineCredentialsAuth({ login }) as result.credential. Gateway persists only auth.flow complete data.credential into the connection.",
+        });
+    }
+}
+function getPendingChallenge(ctx) {
+    const value = ctx.context.get(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY);
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (typeof record.challengeId !== "string")
+        return null;
+    const state = record.state && typeof record.state === "object" && !Array.isArray(record.state)
+        ? record.state
+        : {};
+    return {
+        challengeId: record.challengeId,
+        state,
+        ...(typeof record.turnId === "string" ? { turnId: record.turnId } : {}),
+        ...(typeof record.hintKey === "string" ? { hintKey: record.hintKey } : {}),
+        ...(typeof record.expiresAt === "string" ? { expiresAt: record.expiresAt } : {}),
+        ...(record.data && typeof record.data === "object" && !Array.isArray(record.data)
+            ? { data: record.data }
+            : {}),
+        ...(record.timing && typeof record.timing === "object" && !Array.isArray(record.timing)
+            ? { timing: record.timing }
+            : {}),
+    };
+}
+function setPendingChallenge(ctx, challenge) {
+    ctx.context.set(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, challenge);
+}
+function clearPendingChallenge(ctx) {
+    ctx.context.set(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, null);
+}
+function pendingToChallengeRequest(pending) {
+    return {
+        kind: "challenge",
+        challengeId: pending.challengeId,
+        state: pending.state,
+        ...(pending.turnId ? { turnId: pending.turnId } : {}),
+        ...(pending.hintKey ? { hintKey: pending.hintKey } : {}),
+        ...(pending.expiresAt ? { expiresAt: pending.expiresAt } : {}),
+        ...(pending.data ? { data: pending.data } : {}),
+        ...(pending.timing ? { timing: pending.timing } : {}),
+    };
+}
+function retryTurn(expectedInput, missing, retryTurnId) {
+    return {
+        kind: "retry",
+        turnId: retryTurnId,
+        expectedInput,
+        data: {
+            fieldErrors: Object.fromEntries(missing.map((name) => [name, "Required"])),
+            fieldErrorKeys: Object.fromEntries(missing.map((name) => [name, "auth.credentials.fieldRequired"])),
+        },
+    };
+}
+function isChallengeRequest(result) {
+    return "kind" in result && result.kind === "challenge";
+}
+function completeTurn(credentialKeys, result, defaultTurnId) {
+    if (!result.credential ||
+        typeof result.credential !== "object" ||
+        Array.isArray(result.credential)) {
+        throw new ProviderError("Credentials auth login completed without a credential object", {
+            code: "credentials_auth_missing_credential",
+            fix: "Return { credential: { ... } } from defineCredentialsAuth handlers. Gateway persists only auth.flow complete data.credential into the connection.",
+        });
+    }
+    assertCredentialKeys(credentialKeys, result.credential);
+    return {
+        kind: "complete",
+        turnId: result.turnId ?? defaultTurnId,
+        ...(result.expiresAt ? { expiresAt: result.expiresAt } : {}),
+        data: {
+            ...(result.data ?? {}),
+            credential: result.credential,
+        },
+    };
+}
+function challengeTurn(definition, request) {
+    const expectedInput = definition.fields ? expectedInputFromFields(definition.fields) : undefined;
+    return {
+        kind: expectedInput ? "form" : "pending",
+        turnId: request.turnId ?? definition.turnId ?? `credentials.${request.challengeId}`,
+        ...(request.expiresAt ? { expiresAt: request.expiresAt } : {}),
+        ...((request.hintKey ?? definition.hintKey)
+            ? { hintKey: request.hintKey ?? definition.hintKey }
+            : {}),
+        ...((request.timing ?? definition.timing)
+            ? { timing: request.timing ?? definition.timing }
+            : {}),
+        ...(expectedInput ? { expectedInput } : {}),
+        data: {
+            ...(request.data ?? {}),
+            challengeId: request.challengeId,
+        },
+    };
+}
+async function resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId) {
+    if (!result || typeof result !== "object") {
+        throw new AuthError("Credentials auth login did not return a result", {
+            code: "credentials_auth_invalid_login_result",
+            fix: "Return { credential: { ... } } or credentialsAuthChallenge(...) from defineCredentialsAuth handlers.",
+        });
+    }
+    if (!isChallengeRequest(result)) {
+        clearPendingChallenge(ctx);
+        return completeTurn(credentialKeys, result, completeTurnId);
+    }
+    const definition = challenges[result.challengeId];
+    if (!definition) {
+        throw new ProviderError(`Credentials auth requested unknown challenge "${result.challengeId}"`, {
+            code: "credentials_auth_unknown_challenge",
+            fix: `Add challenges.${result.challengeId} to defineCredentialsAuth({ challenges }).`,
+        });
+    }
+    setPendingChallenge(ctx, {
+        challengeId: result.challengeId,
+        state: result.state ?? {},
+        ...(result.turnId ? { turnId: result.turnId } : {}),
+        ...(result.hintKey ? { hintKey: result.hintKey } : {}),
+        ...(result.expiresAt ? { expiresAt: result.expiresAt } : {}),
+        ...(result.data ? { data: result.data } : {}),
+        ...(result.timing ? { timing: result.timing } : {}),
+    });
+    return challengeTurn(definition, result);
+}
+async function continuePendingChallenge(ctx, credentialKeys, challenges, pending, rawInput, completeTurnId) {
+    const definition = challenges[pending.challengeId];
+    if (!definition) {
+        throw new ProviderError(`Credentials auth has pending unknown challenge "${pending.challengeId}"`, { code: "credentials_auth_unknown_pending_challenge" });
+    }
+    if (!definition.fields || !definition.verify) {
+        return challengeTurn(definition, pendingToChallengeRequest(pending));
+    }
+    const missing = collectMissingFields(definition.fields, rawInput);
+    const expectedInput = expectedInputFromFields(definition.fields);
+    if (missing.length > 0) {
+        return retryTurn(expectedInput, missing, definition.retryTurnId ?? `credentials.${pending.challengeId}.retry`);
+    }
+    const result = await definition.verify(ctx, normalizeInput(definition.fields, rawInput), pending.state);
+    return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
+}
+async function pollPendingChallenge(ctx, credentialKeys, challenges, pending, completeTurnId) {
+    const definition = challenges[pending.challengeId];
+    if (!definition) {
+        throw new ProviderError(`Credentials auth has pending unknown challenge "${pending.challengeId}"`, { code: "credentials_auth_unknown_pending_challenge" });
+    }
+    if (!definition.poll) {
+        return challengeTurn(definition, pendingToChallengeRequest(pending));
+    }
+    const result = await definition.poll(ctx, pending.state);
+    if (!result) {
+        return {
+            ...challengeTurn(definition, pendingToChallengeRequest(pending)),
+            turnId: definition.pendingTurnId ??
+                definition.turnId ??
+                `credentials.${pending.challengeId}.pending`,
+        };
+    }
+    return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
+}
+export function defineCredentialsAuth(options) {
+    if (Object.keys(options.fields).length === 0) {
+        throw new ProviderError("defineCredentialsAuth requires at least one field", {
+            fix: 'Pass fields such as { email: { type: "email" }, password: { type: "password" } }.',
+        });
+    }
+    const expectedInput = expectedInputFromFields(options.fields);
+    const retryTurnId = options.retryTurnId ?? "credentials.retry";
+    const completeTurnId = options.completeTurnId ?? "credentials.complete";
+    const challenges = (options.challenges ?? {});
+    return {
+        auth: {
+            mode: "credentials",
+            flow: {
+                start: async () => ({
+                    kind: "form",
+                    turnId: options.startTurnId ?? "credentials.start",
+                    ...(options.hintKey ? { hintKey: options.hintKey } : {}),
+                    expectedInput,
+                }),
+                continue: async (ctx, rawInput) => {
+                    const pending = getPendingChallenge(ctx);
+                    if (pending) {
+                        return await continuePendingChallenge(ctx, options.credentialKeys, challenges, pending, rawInput, completeTurnId);
+                    }
+                    const missing = collectMissingFields(options.fields, rawInput);
+                    if (missing.length > 0) {
+                        return retryTurn(expectedInput, missing, retryTurnId);
+                    }
+                    const result = await options.login(ctx, normalizeInput(options.fields, rawInput));
+                    return await resolveAuthResult(ctx, options.credentialKeys, challenges, result, completeTurnId);
+                },
+                poll: async (ctx) => {
+                    const pending = getPendingChallenge(ctx);
+                    if (!pending) {
+                        return {
+                            kind: "pending",
+                            turnId: "credentials.noPendingChallenge",
+                        };
+                    }
+                    return await pollPendingChallenge(ctx, options.credentialKeys, challenges, pending, completeTurnId);
+                },
+            },
+        },
+        credential: {
+            keys: Array.from(options.credentialKeys),
+            ...(options.storesReusableSecret === undefined
+                ? {}
+                : { storesReusableSecret: options.storesReusableSecret }),
+            ...(options.justification ? { justification: options.justification } : {}),
+        },
+        context: {
+            keys: Array.from(new Set([CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, ...(options.contextKeys ?? [])])),
+        },
+    };
+}

package/dist/ceremonies/index.d.ts

@@ -1,4 +1,4 @@
-import type { AuthFlowDefinition, AuthTurn } from "../types";
+import type { AuthFlowDefinition, AuthTurn } from "../types.js";
 type JsonObject = Record<string, unknown>;
 export declare function validateCeremonyOutput(turn: unknown): AuthTurn;
 export declare function createOAuth2Ceremony(options: {

package/dist/ceremonies/index.js

@@ -1,36 +1,12 @@
 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);
+import Ajv2020 from "ajv/dist/2020.js";
+import { AUTH_TURN_SCHEMA } from "../auth-turn/index.js";
+import { FlowExpiredError, ProviderSecretError, TurnValidationError, ValidationError, } from "../errors.js";
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictSchema: true });
+// Runtime ceremony-output validation derives from the exported versioned
+// contract: it compiles the exact AUTH_TURN_SCHEMA document shipped at
+// dist/auth-turn/auth-turn.v1.schema.json, so the two cannot drift.
+const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
 const DEVICE_FLOW_KEY = "__device_flow";
@@ -62,11 +38,7 @@ function getRequiredEnv(ctx, key) {
     return value;
 }
 function toBase64Url(input) {
-    return input
-        .toString("base64")
-        .replace(/\+/g, "-")
-        .replace(/\//g, "_")
-        .replace(/=+$/g, "");
+    return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
 function createCodeVerifier() {
     return toBase64Url(randomBytes(32));
@@ -124,8 +96,7 @@ function withDeclaredFormFieldOrder(expectedInput) {
         return expectedInput;
     }
     const existingOrder = expectedInput[FORM_FIELD_ORDER_EXTENSION];
-    if (Array.isArray(existingOrder) &&
-        existingOrder.every((value) => typeof value === "string")) {
+    if (Array.isArray(existingOrder) && existingOrder.every((value) => typeof value === "string")) {
         return expectedInput;
     }
     return {
@@ -242,8 +213,7 @@ export function createDeviceFlowCeremony(options) {
             });
             const data = ensureRecord(response.data);
             const errorCode = getString(data, "error");
-            if (errorCode === "authorization_pending" ||
-                errorCode === "slow_down") {
+            if (errorCode === "authorization_pending" || errorCode === "slow_down") {
                 return createTurn("poll", {
                     data,
                     hint: "Authorization pending.",
@@ -369,7 +339,7 @@ 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 { prevalidate } = await import("../runtime/prevalidate.js");
             const result = prevalidate(options.schema, input);
             if (!result.valid) {
                 throw new ValidationError("Form input failed validation.", {
@@ -378,9 +348,7 @@ export function createFormCeremony(options) {
             }
             return createTurn("complete", {
                 data: {
-                    credential: options.mapCredential
-                        ? options.mapCredential(input)
-                        : input,
+                    credential: options.mapCredential ? options.mapCredential(input) : input,
                 },
                 hint: "Form completed.",
             });
@@ -452,9 +420,7 @@ export function createSwitchCeremony(options) {
         })),
         continue: (ctx, input = {}) => runCeremonyHandler(async () => {
             const storedChoice = ctx.context.get(SWITCH_SELECTION_KEY);
-            const choice = typeof storedChoice === "string"
-                ? storedChoice
-                : getString(input, "choice");
+            const choice = typeof storedChoice === "string" ? storedChoice : getString(input, "choice");
             if (!choice || !options.choices[choice]) {
                 throw new ValidationError("A valid choice is required.");
             }

package/dist/cli/commands.d.ts

@@ -1,4 +1,4 @@
-export type ApifuseCommandName = "create" | "dev" | "check" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
+export type ApifuseCommandName = "create" | "dev" | "check" | "sync-assets" | "submit-check" | "bounty-check" | "record" | "test" | "perf";
 export type ApifuseCommandManifest = {
     name: ApifuseCommandName;
     summary: string;

package/dist/cli/commands.js

@@ -23,6 +23,13 @@ export const COMMAND_MANIFEST = {
         examples: ["apifuse check .", "apifuse check providers/korea-air-quality"],
         modulePath: "./apifuse-check",
     },
+    "sync-assets": {
+        name: "sync-assets",
+        summary: "Regenerate SDK-managed agent prompt assets (AGENTS.md, .agents/skills, symlinks, manifest) for the installed SDK version.",
+        usage: "apifuse sync-assets [path] [--check]",
+        examples: ["apifuse sync-assets .", "apifuse sync-assets . --check"],
+        modulePath: "./apifuse-sync-assets",
+    },
     "submit-check": {
         name: "submit-check",
         summary: "Score provider bounty submission readiness and emit checklist evidence.",
@@ -73,6 +80,7 @@ export const COMMAND_ORDER = [
     "create",
     "dev",
     "check",
+    "sync-assets",
     "submit-check",
     "record",
     "test",

package/dist/cli/create.d.ts

@@ -26,7 +26,10 @@ export type CreateResolvedOptions = {
 };
 export type ProviderPlanFile = {
     path: string;
+    /** File content, or the symlink target (relative path) for kind "symlink". */
     content: string;
+    /** Absent kind means "file" (backward compatible with older consumers). */
+    kind?: "file" | "symlink";
 };
 export type ProviderCreatePlan = {
     displayName: string;