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

package/src/auth.ts

@@ -1,4 +1,4 @@
-import { AuthError, ProviderError } from "./errors";
+import { AuthError, ProviderError } from "./errors.js";
 import type {
 	AuthAbortData,
 	AuthConfig,
@@ -10,7 +10,7 @@ import type {
 	CredentialDeclaration,
 	FlowContext,
 	ProviderLocaleKeyInput,
-} from "./types";
+} from "./types.js";
 
 const CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY = "__credentialsAuthChallenge";
 const DEFAULT_COMPLETE_TURN_ID = "auth.complete";
@@ -33,11 +33,7 @@ function isSensitiveAuthDataKey(key: string): boolean {
 	return SENSITIVE_ABORT_DATA_KEY_PATTERN.test(normalizedAuthDataKey(key));
 }
 
-export type CredentialsAuthFieldType =
-	| "string"
-	| "email"
-	| "password"
-	| "otp";
+export type CredentialsAuthFieldType = "string" | "email" | "password" | "otp";
 
 export interface CredentialsAuthField {
 	type?: CredentialsAuthFieldType;
@@ -138,10 +134,9 @@ function abortData(options: {
 	};
 }
 
-export function createAuthFlowHelpers(options: {
-	readonly signal?: AbortSignal;
-	readonly deadline?: string;
-} = {}): AuthFlowTerminalContext {
+export function createAuthFlowHelpers(
+	options: { readonly signal?: AbortSignal; readonly deadline?: string } = {},
+): AuthFlowTerminalContext {
 	return {
 		...(options.signal ? { signal: options.signal } : {}),
 		...(options.deadline ? { deadline: options.deadline } : {}),
@@ -156,16 +151,7 @@ export function createAuthFlowHelpers(options: {
 				},
 			};
 		},
-		abort({
-			code,
-			message,
-			retry,
-			actionHint,
-			fieldErrors,
-			data,
-			turnId,
-			expiresAt,
-		}) {
+		abort({ code, message, retry, actionHint, fieldErrors, data, turnId, expiresAt }) {
 			return {
 				kind: "abort",
 				...authTurnBase({ turnId, defaultTurnId: DEFAULT_ABORT_TURN_ID, expiresAt }),
@@ -190,8 +176,7 @@ export function createAuthFlowHelpers(options: {
 				...(options.hintKey ? { hintKey: options.hintKey } : {}),
 				...(options.timing ? { timing: options.timing } : {}),
 				...(options.data ? { data: options.data } : {}),
-				expectedInput:
-					options.expectedInput ?? expectedInputFromFields(options.fields ?? {}),
+				expectedInput: options.expectedInput ?? expectedInputFromFields(options.fields ?? {}),
 			};
 		},
 		nextPoll(options = {}) {
@@ -223,9 +208,7 @@ export class AuthAbortError extends AuthError {
 	}
 }
 
-export interface CredentialsAuthCompleteResult<
-	TCredentialKeys extends readonly string[],
-> {
+export interface CredentialsAuthCompleteResult<TCredentialKeys extends readonly string[]> {
 	credential: CredentialsAuthCredential<TCredentialKeys>;
 	/** Additional non-credential auth-flow data to return alongside credential. */
 	data?: Record<string, unknown>;
@@ -247,9 +230,7 @@ export interface CredentialsAuthChallengeRequest<TChallengeId extends string = s
 export type CredentialsAuthLoginResult<
 	TCredentialKeys extends readonly string[],
 	TChallengeId extends string = string,
-> =
-	| CredentialsAuthCompleteResult<TCredentialKeys>
-	| CredentialsAuthChallengeRequest<TChallengeId>;
+> = CredentialsAuthCompleteResult<TCredentialKeys> | CredentialsAuthChallengeRequest<TChallengeId>;
 
 export interface CredentialsAuthChallengeDefinition<
 	TFields extends CredentialsAuthFields,
@@ -351,12 +332,8 @@ function expectedInputFromFields(fields: CredentialsAuthFields): Record<string,
 					...(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.descriptionKey ? { descriptionKey: field.descriptionKey } : {}),
+					...(field.placeholderKey ? { placeholderKey: field.placeholderKey } : {}),
 					...(field.sensitive || field.type === "password" || field.type === "otp"
 						? { sensitive: true }
 						: {}),
@@ -437,10 +414,7 @@ function getPendingChallenge(ctx: FlowContext): PendingCredentialsAuthChallenge
 	};
 }
 
-function setPendingChallenge(
-	ctx: FlowContext,
-	challenge: PendingCredentialsAuthChallenge,
-): void {
+function setPendingChallenge(ctx: FlowContext, challenge: PendingCredentialsAuthChallenge): void {
 	ctx.context.set(CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, challenge);
 }
 
@@ -473,9 +447,7 @@ function retryTurn(
 		turnId: retryTurnId,
 		expectedInput,
 		data: {
-			fieldErrors: Object.fromEntries(
-				missing.map((name) => [name, "Required"]),
-			),
+			fieldErrors: Object.fromEntries(missing.map((name) => [name, "Required"])),
 			fieldErrorKeys: Object.fromEntries(
 				missing.map((name) => [name, "auth.credentials.fieldRequired"]),
 			),
@@ -499,18 +471,12 @@ function completeTurn<TCredentialKeys extends readonly string[]>(
 		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.",
-			},
-		);
+		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 as Record<string, unknown>,
-	);
+	assertCredentialKeys(credentialKeys, result.credential as Record<string, unknown>);
 	return {
 		kind: "complete",
 		turnId: result.turnId ?? defaultTurnId,
@@ -523,24 +489,18 @@ function completeTurn<TCredentialKeys extends readonly string[]>(
 }
 
 function challengeTurn(
-	definition: CredentialsAuthChallengeDefinition<
-		CredentialsAuthFields,
-		readonly string[],
-		string
-	>,
+	definition: CredentialsAuthChallengeDefinition<CredentialsAuthFields, readonly string[], string>,
 	request: CredentialsAuthChallengeRequest<string>,
 ): AuthTurn {
-	const expectedInput = definition.fields
-		? expectedInputFromFields(definition.fields)
-		: undefined;
+	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
+		...((request.hintKey ?? definition.hintKey)
 			? { hintKey: request.hintKey ?? definition.hintKey }
 			: {}),
-		...(request.timing ?? definition.timing
+		...((request.timing ?? definition.timing)
 			? { timing: request.timing ?? definition.timing }
 			: {}),
 		...(expectedInput ? { expectedInput } : {}),
@@ -630,13 +590,7 @@ async function continuePendingChallenge<TCredentialKeys extends readonly string[
 		normalizeInput(definition.fields, rawInput),
 		pending.state,
 	);
-	return await resolveAuthResult(
-		ctx,
-		credentialKeys,
-		challenges,
-		result,
-		completeTurnId,
-	);
+	return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
 }
 
 async function pollPendingChallenge<TCredentialKeys extends readonly string[]>(
@@ -669,13 +623,7 @@ async function pollPendingChallenge<TCredentialKeys extends readonly string[]>(
 				`credentials.${pending.challengeId}.pending`,
 		};
 	}
-	return await resolveAuthResult(
-		ctx,
-		credentialKeys,
-		challenges,
-		result,
-		completeTurnId,
-	);
+	return await resolveAuthResult(ctx, credentialKeys, challenges, result, completeTurnId);
 }
 
 export function defineCredentialsAuth<
@@ -697,7 +645,7 @@ export function defineCredentialsAuth<
 ): DefinedCredentialsAuth {
 	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\" } }.",
+			fix: 'Pass fields such as { email: { type: "email" }, password: { type: "password" } }.',
 		});
 	}
 
@@ -737,10 +685,7 @@ export function defineCredentialsAuth<
 						return retryTurn(expectedInput, missing, retryTurnId);
 					}
 
-					const result = await options.login(
-						ctx,
-						normalizeInput(options.fields, rawInput),
-					);
+					const result = await options.login(ctx, normalizeInput(options.fields, rawInput));
 					return await resolveAuthResult(
 						ctx,
 						options.credentialKeys,
@@ -776,10 +721,7 @@ export function defineCredentialsAuth<
 		},
 		context: {
 			keys: Array.from(
-				new Set([
-					CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY,
-					...(options.contextKeys ?? []),
-				]),
+				new Set([CREDENTIALS_AUTH_CHALLENGE_CONTEXT_KEY, ...(options.contextKeys ?? [])]),
 			),
 		},
 	};

package/src/ceremonies/index.ts

@@ -2,19 +2,14 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 
 import Ajv2020 from "ajv/dist/2020.js";
 
-import { AUTH_TURN_SCHEMA, type KnownAuthTurnKind } from "../auth-turn";
+import { AUTH_TURN_SCHEMA, type KnownAuthTurnKind } from "../auth-turn/index.js";
 import {
 	FlowExpiredError,
 	ProviderSecretError,
 	TurnValidationError,
 	ValidationError,
-} from "../errors";
-import type {
-	AuthFlowDefinition,
-	AuthFlowInputHandler,
-	AuthTurn,
-	FlowContext,
-} from "../types";
+} from "../errors.js";
+import type { AuthFlowDefinition, AuthFlowInputHandler, AuthTurn, FlowContext } from "../types.js";
 
 type TurnKind = KnownAuthTurnKind;
 
@@ -31,6 +26,15 @@ const validateAuthTurn = ajv.compile(AUTH_TURN_SCHEMA);
 
 const OAUTH2_STATE_KEY = "__oauth2_state";
 const OAUTH2_PKCE_VERIFIER_KEY = "__oauth2_pkce_verifier";
+export const OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY = "APIFUSE__AUTH_PROXY__URL";
+export const OAUTH2_PROXIED_PKCE_VERIFIER_KEY = "__oauth2_proxied_pkce_verifier";
+const OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS = new Set([
+	"client_id",
+	"response_type",
+	"state",
+	"code_challenge",
+	"code_challenge_method",
+]);
 const DEVICE_FLOW_KEY = "__device_flow";
 const MAGIC_LINK_KEY = "__magic_link";
 const COMBINED_STAGE_KEY = "__combined_stage";
@@ -45,10 +49,7 @@ function ensureRecord(value: unknown): JsonObject {
 	return isRecord(value) ? value : {};
 }
 
-function createTurn(
-	kind: TurnKind,
-	options: Omit<AuthTurn, "kind" | "turnId"> = {},
-): AuthTurn {
+function createTurn(kind: TurnKind, options: Omit<AuthTurn, "kind" | "turnId"> = {}): AuthTurn {
 	return {
 		kind,
 		turnId: randomUUID(),
@@ -69,11 +70,7 @@ function getRequiredEnv(ctx: FlowContext, key: string): string {
 }
 
 function toBase64Url(input: Buffer): string {
-	return input
-		.toString("base64")
-		.replace(/\+/g, "-")
-		.replace(/\//g, "_")
-		.replace(/=+$/g, "");
+	return input.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
 
 function createCodeVerifier(): string {
@@ -130,10 +127,7 @@ async function runCeremonyHandler(
 	}
 }
 
-function getString(
-	input: Record<string, unknown>,
-	key: string,
-): string | undefined {
+function getString(input: Record<string, unknown>, key: string): string | undefined {
 	const value = input[key];
 	return typeof value === "string" ? value : undefined;
 }
@@ -142,10 +136,7 @@ function getNestedRecord(ctx: FlowContext, key: string): JsonObject {
 	return ensureRecord(ctx.context.get(key));
 }
 
-function buildJsonSchemaForm(
-	expectedInput: JsonObject,
-	hint: string,
-): AuthTurn {
+function buildJsonSchemaForm(expectedInput: JsonObject, hint: string): AuthTurn {
 	return createTurn("form", {
 		hint,
 		expectedInput: withDeclaredFormFieldOrder(expectedInput),
@@ -160,10 +151,7 @@ function withDeclaredFormFieldOrder(expectedInput: JsonObject): JsonObject {
 	}
 
 	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;
 	}
 
@@ -176,9 +164,7 @@ function withDeclaredFormFieldOrder(expectedInput: JsonObject): JsonObject {
 export function validateCeremonyOutput(turn: unknown): AuthTurn {
 	if (!validateAuthTurn(turn)) {
 		const detail = validateAuthTurn.errors
-			?.map(
-				(error) => `${error.instancePath || "$"} ${error.message ?? "invalid"}`,
-			)
+			?.map((error) => `${error.instancePath || "$"} ${error.message ?? "invalid"}`)
 			.join("; ");
 		throw new TurnValidationError(detail || "Invalid AuthTurn output");
 	}
@@ -214,10 +200,7 @@ export function createOAuth2Ceremony(options: {
 					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", createCodeChallenge(verifier));
 						authorizeUrl.searchParams.set("code_challenge_method", "S256");
 					}
 
@@ -270,13 +253,80 @@ export function createOAuth2Ceremony(options: {
 				ctx,
 				input,
 			),
-		abort: async () =>
-			validateCeremonyOutput(
-				createTurn("abort", { hint: "OAuth flow aborted." }),
-			),
+		abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
 	};
 }
 
+/**
+ * Builds the start handler for a custom-scheme OAuth provider. The shared
+ * auth-proxy owns state minting and callback capture, while the provider owns
+ * token exchange and any following authentication turns.
+ */
+export function createOAuth2ProxiedStart(
+	options: import("../types.js").ProxiedOAuthConfig,
+): import("../types.js").AuthFlowStartHandler {
+	const pkce = options.pkce ?? "S256";
+
+	return (ctx) =>
+		runCeremonyHandler(
+			async () => {
+				for (const key of Object.keys(options.authorizeParams ?? {})) {
+					if (OAUTH2_PROXIED_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())) {
+						throw new ValidationError(
+							`OAuth2 proxied authorizeParams cannot override reserved parameter "${key}".`,
+						);
+					}
+				}
+				const proxyOrigin = ctx.env.get(OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY);
+				if (!proxyOrigin) {
+					throw new ProviderSecretError(
+						`Missing required platform environment: ${OAUTH2_PROXIED_AUTH_PROXY_ORIGIN_ENV_KEY}`,
+					);
+				}
+				const clientId = getRequiredEnv(ctx, options.clientIdEnvKey);
+				if (!ctx.flowId) {
+					throw new ValidationError(
+						"OAuth2 proxied start requires the gateway flow id.",
+					);
+				}
+
+				const authorizePath = new URL(options.authorizeUrl).pathname;
+				const url = new URL(
+					`/p/${encodeURIComponent(ctx.providerId)}/f/${encodeURIComponent(ctx.flowId)}${authorizePath}`,
+					proxyOrigin,
+				);
+				url.searchParams.set("client_id", clientId);
+				url.searchParams.set("response_type", "code");
+
+				if (pkce === "S256") {
+					const verifier = createCodeVerifier();
+					ctx.context.set(OAUTH2_PROXIED_PKCE_VERIFIER_KEY, verifier);
+					url.searchParams.set("code_challenge", createCodeChallenge(verifier));
+					url.searchParams.set("code_challenge_method", "S256");
+				}
+
+				for (const [key, value] of Object.entries(options.authorizeParams ?? {})) {
+					url.searchParams.set(key, value);
+				}
+
+				return createTurn("redirect", {
+					data: { url: url.toString() },
+					hint: "Open the provider authorization page to continue.",
+					expectedInput: {
+						type: "object",
+						required: ["code", "state"],
+						properties: {
+							code: { type: "string" },
+							state: { type: "string" },
+						},
+					},
+				});
+			},
+			"OAuth2 proxied start failed",
+			ctx,
+		);
+}
+
 export function createDeviceFlowCeremony(options: {
 	deviceCodeUrl: string;
 	tokenUrl: string;
@@ -329,26 +379,19 @@ export function createDeviceFlowCeremony(options: {
 						client_id: getRequiredEnv(ctx, options.clientIdEnvKey),
 						...(options.clientSecretEnvKey
 							? {
-									client_secret: getRequiredEnv(
-										ctx,
-										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"
-					) {
+					if (errorCode === "authorization_pending" || errorCode === "slow_down") {
 						return createTurn("poll", {
 							data,
 							hint: "Authorization pending.",
 							timing: {
-								suggestedPollIntervalMs:
-									errorCode === "slow_down" ? 10_000 : 5_000,
+								suggestedPollIntervalMs: errorCode === "slow_down" ? 10_000 : 5_000,
 								maxWaitMs: 120_000,
 							},
 						});
@@ -367,9 +410,7 @@ export function createDeviceFlowCeremony(options: {
 				ctx,
 			),
 		abort: async () =>
-			validateCeremonyOutput(
-				createTurn("abort", { hint: "Device flow aborted." }),
-			),
+			validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
 	};
 }
 
@@ -437,9 +478,7 @@ export function createWebAuthnCeremony(options: {
 				input,
 			),
 		abort: async () =>
-			validateCeremonyOutput(
-				createTurn("abort", { hint: "WebAuthn ceremony aborted." }),
-			),
+			validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
 	};
 }
 
@@ -526,9 +565,7 @@ export function createMagicLinkCeremony(options: {
 				ctx,
 			),
 		abort: async () =>
-			validateCeremonyOutput(
-				createTurn("abort", { hint: "Magic link flow aborted." }),
-			),
+			validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
 	};
 }
 
@@ -548,7 +585,7 @@ export function createFormCeremony(options: {
 		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.", {
@@ -558,9 +595,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.",
 					});
@@ -570,15 +605,11 @@ export function createFormCeremony(options: {
 				input,
 			),
 		abort: async () =>
-			validateCeremonyOutput(
-				createTurn("abort", { hint: "Form ceremony aborted." }),
-			),
+			validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
 	};
 }
 
-export function combineCeremonies(
-	...ceremonies: AuthFlowDefinition[]
-): AuthFlowDefinition {
+export function combineCeremonies(...ceremonies: AuthFlowDefinition[]): AuthFlowDefinition {
 	function getStage(ctx: FlowContext): number {
 		const rawStage = ctx.context.get(COMBINED_STAGE_KEY);
 		return typeof rawStage === "number" ? rawStage : 0;
@@ -630,9 +661,7 @@ export function combineCeremonies(
 				async () => {
 					const current = ceremonies[getStage(ctx)];
 					if (!current?.poll) {
-						throw new ValidationError(
-							"Current ceremony does not support polling.",
-						);
+						throw new ValidationError("Current ceremony does not support polling.");
 					}
 					return await current.poll(ctx);
 				},
@@ -680,9 +709,7 @@ export function createSwitchCeremony(options: {
 				async () => {
 					const storedChoice = ctx.context.get(SWITCH_SELECTION_KEY);
 					const choice =
-						typeof storedChoice === "string"
-							? storedChoice
-							: getString(input, "choice");
+						typeof storedChoice === "string" ? storedChoice : getString(input, "choice");
 
 					if (!choice || !options.choices[choice]) {
 						throw new ValidationError("A valid choice is required.");
@@ -710,9 +737,7 @@ export function createSwitchCeremony(options: {
 
 					const ceremony = options.choices[choice];
 					if (!ceremony?.poll) {
-						throw new ValidationError(
-							"Selected ceremony does not support polling.",
-						);
+						throw new ValidationError("Selected ceremony does not support polling.");
 					}
 
 					return await ceremony.poll(ctx);

package/src/cli/commands.ts

@@ -2,6 +2,7 @@ export type ApifuseCommandName =
 	| "create"
 	| "dev"
 	| "check"
+	| "sync-assets"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -46,6 +47,14 @@ export const COMMAND_MANIFEST: Record<
 		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:
@@ -103,6 +112,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"create",
 	"dev",
 	"check",
+	"sync-assets",
 	"submit-check",
 	"record",
 	"test",