@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/src/ceremonies/index.ts

@@ -1,36 +1,39 @@
 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;
 
 type CeremonyHandler = AuthFlowInputHandler;
 
 type JsonObject = Record<string, unknown>;
-
-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);
+type JsonSchemaNode = {
+	readonly additionalProperties?: boolean;
+	readonly minimum?: number;
+	readonly minLength?: number;
+	readonly properties?: Readonly<Record<string, JsonSchemaNode>>;
+	readonly required?: readonly string[];
+	readonly type?: "number" | "object" | "string";
+};
 
 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";
@@ -41,14 +44,61 @@ function isRecord(value: unknown): value is JsonObject {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+function validateSchemaNode(
+	value: unknown,
+	schema: JsonSchemaNode,
+	path: string,
+	errors: string[],
+): void {
+	if (schema.type === "object") {
+		if (!isRecord(value)) {
+			errors.push(`${path} must be object`);
+			return;
+		}
+		const properties = schema.properties ?? {};
+		for (const required of schema.required ?? []) {
+			if (!Object.hasOwn(value, required) || value[required] === undefined) {
+				errors.push(`${path} must have required property '${required}'`);
+			}
+		}
+		if (schema.additionalProperties === false) {
+			for (const key of Object.keys(value)) {
+				if (!Object.hasOwn(properties, key)) {
+					errors.push(`${path} must NOT have additional property '${key}'`);
+				}
+			}
+		}
+		for (const [key, childSchema] of Object.entries(properties)) {
+			if (Object.hasOwn(value, key) && value[key] !== undefined) {
+				validateSchemaNode(value[key], childSchema, `${path}/${key}`, errors);
+			}
+		}
+		return;
+	}
+
+	if (schema.type === "string") {
+		if (typeof value !== "string") {
+			errors.push(`${path} must be string`);
+		} else if (schema.minLength !== undefined && value.length < schema.minLength) {
+			errors.push(`${path} must NOT have fewer than ${schema.minLength} characters`);
+		}
+		return;
+	}
+
+	if (schema.type === "number") {
+		if (typeof value !== "number" || !Number.isFinite(value)) {
+			errors.push(`${path} must be number`);
+		} else if (schema.minimum !== undefined && value < schema.minimum) {
+			errors.push(`${path} must be >= ${schema.minimum}`);
+		}
+	}
+}
+
 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 +119,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 +176,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 +185,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 +200,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;
 	}
 
@@ -174,16 +211,17 @@ 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"}`,
-			)
-			.join("; ");
-		throw new TurnValidationError(detail || "Invalid AuthTurn output");
+	// Evaluate the exact exported versioned schema without eagerly initializing
+	// a general-purpose JSON Schema compiler in every provider process. Contract
+	// parity tests compare this focused evaluator with AJV over all fixtures and
+	// edge probes, so the runtime and shipped document remain locked together.
+	const errors: string[] = [];
+	validateSchemaNode(turn, AUTH_TURN_SCHEMA, "", errors);
+	if (errors.length > 0) {
+		throw new TurnValidationError(errors.join("; "));
 	}
 
-	return turn;
+	return turn as AuthTurn;
 }
 
 export function createOAuth2Ceremony(options: {
@@ -214,10 +252,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 +305,78 @@ 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 +429,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 +460,7 @@ export function createDeviceFlowCeremony(options: {
 				ctx,
 			),
 		abort: async () =>
-			validateCeremonyOutput(
-				createTurn("abort", { hint: "Device flow aborted." }),
-			),
+			validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
 	};
 }
 
@@ -437,9 +528,7 @@ export function createWebAuthnCeremony(options: {
 				input,
 			),
 		abort: async () =>
-			validateCeremonyOutput(
-				createTurn("abort", { hint: "WebAuthn ceremony aborted." }),
-			),
+			validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
 	};
 }
 
@@ -526,9 +615,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 +635,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 +645,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 +655,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 +711,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 +759,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 +787,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",

package/src/cli/create.ts

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -8,6 +8,11 @@ import { cancel, intro, isCancel, note, outro, select, text } from "@clack/promp
 import { z } from "zod";
 
 import packageJson from "../../package.json";
+import {
+	buildPromptAssetManifest,
+	buildPromptAssetPlanEntries,
+	PROMPT_ASSET_MANIFEST_PATH,
+} from "./prompt-assets.js";
 
 export const PROVIDER_NAME_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 export const CATEGORY_OPTIONS = [
@@ -64,7 +69,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 = {
@@ -410,11 +418,16 @@ export async function buildProviderCreatePlan(
 		);
 	}
 
+	// Exact pin, not a caret range: the prompt-asset freshness gate requires
+	// manifest.sdkVersion === installed SDK version, and the manifest records
+	// this CLI's own version. A caret range would let `bun install` resolve a
+	// newer SDK than the create binary, making a fresh scaffold fail its own
+	// gate. `sync-assets` after an explicit SDK upgrade re-records the version.
 	const sdkSpecifier =
 		options.sdkSpecifier ??
 		(options.preset === "monorepo" && resolvedWorkspaceRoot
 			? "workspace:*"
-			: `^${packageJson.version}`);
+			: packageJson.version);
 	const relativeProviderRoot = relative(cwd, providerRoot) || options.name;
 	const nextDevCommand = `cd ${relativeProviderRoot} && bun run dev`;
 	const packageName =
@@ -538,40 +551,23 @@ export async function buildProviderCreatePlan(
 				PROVIDER_ID: options.name,
 			}),
 		},
-		{
-			path: resolve(providerRoot, "AGENTS.md"),
-			content: await renderTemplate("AGENTS.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "CLAUDE.md"),
-			content: await renderTemplate("CLAUDE.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "normalization-standards", "SKILL.md"),
-			content: await renderTemplate("skills/normalization-standards/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "upstream-contract-verification", "SKILL.md"),
-			content: await renderTemplate("skills/upstream-contract-verification/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "fixtures-and-recording", "SKILL.md"),
-			content: await renderTemplate("skills/fixtures-and-recording/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "pagination-and-counts", "SKILL.md"),
-			content: await renderTemplate("skills/pagination-and-counts/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "health-checks-and-fail-closed", "SKILL.md"),
-			content: await renderTemplate("skills/health-checks-and-fail-closed/SKILL.md.tpl", {}),
-		},
-		{
-			path: resolve(providerRoot, "skills", "upstream-notes", "README.md"),
-			content: await renderTemplate("skills/upstream-notes/README.md.tpl", {}),
-		},
 	];
 
+	const promptAssetEntries = await buildPromptAssetPlanEntries(renderTemplate);
+	for (const entry of promptAssetEntries) {
+		files.push({
+			path: resolve(providerRoot, entry.path),
+			content: entry.content,
+			...(entry.kind === "symlink" ? { kind: "symlink" as const } : {}),
+		});
+	}
+	// Manifest last: writePlan writes in order, so a crash mid-scaffold never
+	// leaves a manifest that claims assets which were not written.
+	files.push({
+		path: resolve(providerRoot, PROMPT_ASSET_MANIFEST_PATH),
+		content: buildPromptAssetManifest(promptAssetEntries, packageJson.version),
+	});
+
 	return {
 		displayName: options.displayName,
 		files,
@@ -614,6 +610,7 @@ function renderPackageJson(input: { packageName: string; sdkSpecifier: string })
 				check: "apifuse check . && bun run type-check",
 				"type-check": "tsc --noEmit",
 				"submit-check": "apifuse submit-check . --markdown submission-report.md",
+				"sync-assets": "apifuse sync-assets .",
 				test: "apifuse test .",
 				record: "apifuse record .",
 				start: "bun start.ts",
@@ -869,6 +866,13 @@ function isApifuseInternalWorkspaceRoot(workspaceRoot: string): boolean {
 async function writePlan(plan: ProviderCreatePlan): Promise<void> {
 	for (const file of plan.files) {
 		await mkdir(dirname(file.path), { recursive: true });
+		if (file.kind === "symlink") {
+			// rm operates on the link itself (lstat semantics) and tolerates
+			// directories, so whatever occupies the path is replaced by the link.
+			await rm(file.path, { recursive: true, force: true });
+			await symlink(file.content, file.path);
+			continue;
+		}
 		await writeFile(file.path, file.content);
 	}
 }
@@ -940,7 +944,10 @@ function printResult(plan: ProviderCreatePlan, jsonMode: boolean, dryRun: boolea
 		},
 		validationCommands: plan.validationCommands,
 		nextDevCommand: plan.nextDevCommand,
-		files: plan.files.map((file) => relative(plan.providerRoot, file.path) || file.path),
+		files: plan.files.map((file) => {
+			const relativePath = relative(plan.providerRoot, file.path) || file.path;
+			return file.kind === "symlink" ? `${relativePath} -> ${file.content} (symlink)` : relativePath;
+		}),
 	};
 
 	if (jsonMode) {