@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/ceremonies/index.ts

@@ -1,7 +1,5 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 
-import Ajv2020 from "ajv/dist/2020.js";
-
 import { AUTH_TURN_SCHEMA, type KnownAuthTurnKind } from "../auth-turn/index.js";
 import {
 	FlowExpiredError,
@@ -9,6 +7,7 @@ import {
 	TurnValidationError,
 	ValidationError,
 } from "../errors.js";
+import type { AuthStartNoInputGuard } from "../define.js";
 import type { AuthFlowDefinition, AuthFlowInputHandler, AuthTurn, FlowContext } from "../types.js";
 
 type TurnKind = KnownAuthTurnKind;
@@ -16,16 +15,26 @@ 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";
@@ -36,6 +45,56 @@ 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 : {};
 }
@@ -153,14 +212,29 @@ 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;
+}
+
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export function defineAuthFlow<const TFlow extends AuthFlowDefinition>(
+	flow: TFlow & AuthStartNoInputGuard<TFlow>,
+): TFlow {
+	return flow;
 }
 
 export function createOAuth2Ceremony(options: {
@@ -171,7 +245,7 @@ export function createOAuth2Ceremony(options: {
 	scopes: string[];
 	usePKCE?: boolean;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -245,7 +319,75 @@ export function createOAuth2Ceremony(options: {
 				input,
 			),
 		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: {
@@ -255,7 +397,7 @@ export function createDeviceFlowCeremony(options: {
 	clientSecretEnvKey?: string;
 	scopes: string[];
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -332,7 +474,7 @@ export function createDeviceFlowCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
-	};
+	});
 }
 
 export function createWebAuthnCeremony(options: {
@@ -341,7 +483,7 @@ export function createWebAuthnCeremony(options: {
 	verifyUrl?: string;
 	timeoutMs?: number;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -400,7 +542,7 @@ export function createWebAuthnCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
-	};
+	});
 }
 
 export function createMagicLinkCeremony(options: {
@@ -410,23 +552,31 @@ export function createMagicLinkCeremony(options: {
 	expiresInMs?: number;
 }): AuthFlowDefinition {
 	const emailField = options.emailField ?? "email";
+	const buildEmailForm = () =>
+		buildJsonSchemaForm(
+			{
+				type: "object",
+				required: [emailField],
+				properties: {
+					[emailField]: { type: "string", format: "email" },
+				},
+			},
+			"Provide the email address to receive a magic link.",
+		);
 
-	return {
-		start: (ctx, input = {}) =>
+	return defineAuthFlow({
+		start: (ctx) =>
+			runCeremonyHandler(
+				async () => buildEmailForm(),
+				"Magic link start failed",
+				ctx,
+			),
+		continue: (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.",
-						);
+						return buildEmailForm();
 					}
 
 					await ctx.http.post(options.sendUrl, { email });
@@ -441,17 +591,10 @@ export function createMagicLinkCeremony(options: {
 						timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
 					});
 				},
-				"Magic link start failed",
+				"Magic link continuation 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 () => {
@@ -487,7 +630,7 @@ export function createMagicLinkCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
-	};
+	});
 }
 
 export function createFormCeremony(options: {
@@ -495,7 +638,7 @@ export function createFormCeremony(options: {
 	hint?: string;
 	mapCredential?: (input: Record<string, unknown>) => JsonObject;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				buildJsonSchemaForm(
@@ -527,7 +670,7 @@ export function createFormCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
-	};
+	});
 }
 
 export function combineCeremonies(...ceremonies: AuthFlowDefinition[]): AuthFlowDefinition {
@@ -610,7 +753,7 @@ export function createSwitchCeremony(options: {
 }): AuthFlowDefinition {
 	const choiceKeys = Object.keys(options.choices);
 
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				createTurn("multi_choice", {
@@ -682,5 +825,5 @@ export function createSwitchCeremony(options: {
 				"Switch ceremony abort failed",
 				ctx,
 			),
-	};
+	});
 }

package/src/cli/commands.ts

@@ -3,6 +3,9 @@ export type ApifuseCommandName =
 	| "dev"
 	| "check"
 	| "sync-assets"
+	| "migrate-shape"
+	| "migrate-operation-declaration"
+	| "migrate-deployment"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -55,6 +58,37 @@ export const COMMAND_MANIFEST: Record<
 		examples: ["apifuse sync-assets .", "apifuse sync-assets . --check"],
 		modulePath: "./apifuse-sync-assets",
 	},
+	"migrate-shape": {
+		name: "migrate-shape",
+		summary:
+			"Migrate a provider to the phase-separated SDK: two-phase defineProvider in index.ts and curried defineOperation across sources.",
+		usage: "apifuse migrate-shape [path] [--check] [--json]",
+		examples: ["apifuse migrate-shape .", "apifuse migrate-shape . --check"],
+		modulePath: "./apifuse-migrate-shape",
+	},
+	"migrate-operation-declaration": {
+		name: "migrate-operation-declaration",
+		summary:
+			"Migrate legacy nested operation declarations to the ADR-0009 flat shape, refusing ambiguous safety or metadata.",
+		usage: "apifuse migrate-operation-declaration [path] [--check] [--json]",
+		examples: [
+			"apifuse migrate-operation-declaration .",
+			"apifuse migrate-operation-declaration . --check --json",
+		],
+		modulePath: "./apifuse-migrate-operation-declaration",
+	},
+	"migrate-deployment": {
+		name: "migrate-deployment",
+		summary:
+			"Retire a legacy deploy.ts: hoist its non-default values into the defineProvider() deployment key and delete the file.",
+		usage:
+			"apifuse migrate-deployment [path] [--check] [--json] [--drop-codeowners-lock]",
+		examples: [
+			"apifuse migrate-deployment .",
+			"apifuse migrate-deployment . --check --json",
+		],
+		modulePath: "./apifuse-migrate-deployment",
+	},
 	"submit-check": {
 		name: "submit-check",
 		summary:
@@ -113,6 +147,9 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"dev",
 	"check",
 	"sync-assets",
+	"migrate-shape",
+	"migrate-operation-declaration",
+	"migrate-deployment",
 	"submit-check",
 	"record",
 	"test",

package/src/cli/create.ts

@@ -26,7 +26,7 @@ export const CATEGORY_OPTIONS = [
 	"other",
 ] as const;
 export const AUTH_MODE_OPTIONS = ["none", "platform-managed", "credentials", "oauth2"] as const;
-export const RUNTIME_OPTIONS = ["standard", "browser"] as const;
+export const RUNTIME_OPTIONS = ["standard", "shared", "browser"] as const;
 export const PRESET_OPTIONS = ["standalone", "monorepo"] as const;
 
 export type CreateCategory = (typeof CATEGORY_OPTIONS)[number];
@@ -102,7 +102,7 @@ Options:
   --display-name <name>
   --category <category>
   --auth-mode <mode>
-  --runtime <standard|browser>
+  --runtime <standard|shared|browser>
   --yes
   --dry-run
   --json
@@ -519,6 +519,12 @@ export async function buildProviderCreatePlan(
 				sdkSpecifier,
 			}),
 		},
+		{
+			path: resolve(providerRoot, "provider.json"),
+			content: await renderTemplate("provider.json.tpl", {
+				PROVIDER_ID: options.name,
+			}),
+		},
 		{
 			path: resolve(providerRoot, "Dockerfile"),
 			content: await renderTemplate("Dockerfile.tpl", {}),