@apifuse/provider-sdk 2.2.0-beta.33 → 2.2.0-beta.36

package/src/ceremonies/index.ts

@@ -7,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;
@@ -224,6 +225,18 @@ export function validateCeremonyOutput(turn: unknown): AuthTurn {
 	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: {
 	authorizeUrl: string;
 	tokenUrl: string;
@@ -232,7 +245,7 @@ export function createOAuth2Ceremony(options: {
 	scopes: string[];
 	usePKCE?: boolean;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -306,7 +319,7 @@ export function createOAuth2Ceremony(options: {
 				input,
 			),
 		abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
-	};
+	});
 }
 
 /**
@@ -384,7 +397,7 @@ export function createDeviceFlowCeremony(options: {
 	clientSecretEnvKey?: string;
 	scopes: string[];
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -461,7 +474,7 @@ export function createDeviceFlowCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
-	};
+	});
 }
 
 export function createWebAuthnCeremony(options: {
@@ -470,7 +483,7 @@ export function createWebAuthnCeremony(options: {
 	verifyUrl?: string;
 	timeoutMs?: number;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -529,7 +542,7 @@ export function createWebAuthnCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
-	};
+	});
 }
 
 export function createMagicLinkCeremony(options: {
@@ -539,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 });
@@ -570,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 () => {
@@ -616,7 +630,7 @@ export function createMagicLinkCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
-	};
+	});
 }
 
 export function createFormCeremony(options: {
@@ -624,7 +638,7 @@ export function createFormCeremony(options: {
 	hint?: string;
 	mapCredential?: (input: Record<string, unknown>) => JsonObject;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				buildJsonSchemaForm(
@@ -656,7 +670,7 @@ export function createFormCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
-	};
+	});
 }
 
 export function combineCeremonies(...ceremonies: AuthFlowDefinition[]): AuthFlowDefinition {
@@ -739,7 +753,7 @@ export function createSwitchCeremony(options: {
 }): AuthFlowDefinition {
 	const choiceKeys = Object.keys(options.choices);
 
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				createTurn("multi_choice", {
@@ -811,5 +825,5 @@ export function createSwitchCeremony(options: {
 				"Switch ceremony abort failed",
 				ctx,
 			),
-	};
+	});
 }

package/src/cli/templates/provider/Dockerfile.tpl

@@ -1,6 +1,6 @@
 FROM oven/bun:1.2-alpine
 WORKDIR /provider
-COPY package.json bun.lockb* ./
+COPY package.json bun.lock ./
 RUN bun install --frozen-lockfile
 COPY . .
 EXPOSE 3000

package/src/define.ts

@@ -249,17 +249,318 @@ type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaL
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
 
-type AuthStartNoInputGuard<TConfig> = TConfig extends {
+type AuthStartHandlerNoInputGuard<TStart> = TStart extends (...args: infer TArgs) => unknown
+	? TArgs["length"] extends 0 | 1
+		? unknown
+		: {
+				"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+			}
+	: unknown;
+
+export type AuthStartNoInputGuard<TConfig> = TConfig extends {
 	auth?: { flow?: { start: infer TStart } };
 }
-	? TStart extends (...args: infer TArgs) => unknown
-		? TArgs extends [unknown]
-			? unknown
-			: {
-					"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+	? AuthStartHandlerNoInputGuard<TStart>
+	: TConfig extends { start: infer TStart }
+		? AuthStartHandlerNoInputGuard<TStart>
+		: unknown;
+
+function splitAuthStartParameters(parameters: string): string[] | undefined {
+	const parts: string[] = [];
+	let start = 0;
+	let round = 0;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+
+	for (let index = 0; index < parameters.length; index++) {
+		const character = parameters[index];
+		const nextCharacter = parameters[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) {
+				escaped = false;
+			} else if (character === "\\") {
+				escaped = true;
+			} else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) {
+				quote = undefined;
+			}
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && parameters.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && parameters.startsWith("->", index + 1)) return undefined;
+		if (character === "(") round++;
+		else if (character === ")") round--;
+		else if (character === "[") square++;
+		else if (character === "]") square--;
+		else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+		} else if (character === "," && round === 0 && square === 0 && curly === 0) {
+			parts.push(parameters.slice(start, index));
+			start = index + 1;
+		}
+		if (round < 0 || square < 0 || curly < 0) return undefined;
+	}
+
+	if (
+		quote ||
+		blockComment ||
+		templateDepths.length > 0 ||
+		round !== 0 ||
+		square !== 0 ||
+		curly !== 0
+	)
+		return undefined;
+	parts.push(parameters.slice(start));
+	return parts;
+}
+
+function authStartParameterList(source: string): string | undefined {
+	let index = 0;
+	while (index < source.length && /\s/.test(source[index] ?? "")) index++;
+	if (index >= source.length) return undefined;
+
+	let openIndex = -1;
+	let parenthesizedArrow = false;
+	let asyncMethodOrArrow = false;
+	const skipTrivia = () => {
+		while (index < source.length) {
+			if (/\s/.test(source[index] ?? "")) {
+				index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "/") {
+				index += 2;
+				while (index < source.length && source[index] !== "\n" && source[index] !== "\r") index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "*") {
+				const end = source.indexOf("*/", index + 2);
+				if (end < 0) {
+					index = source.length;
+					return;
 				}
-		: unknown
-	: unknown;
+				index = end + 2;
+				continue;
+			}
+			return;
+		}
+	};
+
+	const initial = source.slice(index);
+	const isAsync = initial.startsWith("async") && !/[\w$]/.test(initial[5] ?? "");
+	if (isAsync) {
+		index += 5;
+		skipTrivia();
+	}
+
+	const afterAsync = source.slice(index);
+	const isFunction = afterAsync.startsWith("function") && !/[\w$]/.test(afterAsync[8] ?? "");
+	if (isFunction) {
+		index += 8;
+		skipTrivia();
+		if (source[index] === "*") {
+			index++;
+			skipTrivia();
+		}
+	} else if (source[index] === "*") {
+		index++;
+		skipTrivia();
+	}
+
+	if (source[index] === "(") {
+		openIndex = index;
+		parenthesizedArrow = !isFunction;
+		asyncMethodOrArrow = isAsync && !isFunction;
+	} else if (isFunction) {
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		skipTrivia();
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	} else {
+		const identifierStart = index;
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		const firstIdentifier = source.slice(identifierStart, index);
+		skipTrivia();
+		if (source[index] === "=" && source[index + 1] === ">") return undefined;
+		if (source[index] !== "(") {
+			if (firstIdentifier !== "get" && firstIdentifier !== "set") return undefined;
+			if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+			index++;
+			while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+			skipTrivia();
+		}
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	}
+	if (openIndex < 0) return undefined;
+
+	let depth = 1;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+	for (index = openIndex + 1; index < source.length; index++) {
+		const character = source[index];
+		const nextCharacter = source[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) escaped = false;
+			else if (character === "\\") escaped = true;
+			else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) quote = undefined;
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && source.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && source.startsWith("->", index + 1)) return undefined;
+		if (character === "(") depth++;
+		else if (character === ")") {
+			depth--;
+			if (depth === 0 && square === 0 && curly === 0) {
+				const closeIndex = index;
+				if (parenthesizedArrow) {
+					index++;
+					skipTrivia();
+					const hasArrow = source[index] === "=" && source[index + 1] === ">";
+					if (!hasArrow && (!asyncMethodOrArrow || source[index] !== "{")) return undefined;
+				}
+				return source.slice(openIndex + 1, closeIndex);
+			}
+			if (depth < 0) return undefined;
+		} else if (character === "[") square++;
+		else if (character === "]") {
+			square--;
+			if (square < 0) return undefined;
+		} else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+			if (curly < 0) return undefined;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Conservative defense in depth for defaulted second parameters, which
+ * JavaScript intentionally omits from Function.length. Ambiguous source is
+ * ignored so this check can never reject a valid provider on weak evidence.
+ */
+function authStartHasHiddenInput(start: unknown): boolean {
+	let source: string;
+	try {
+		source = Function.prototype.toString.call(start);
+	} catch {
+		return false;
+	}
+	if (
+		!source ||
+		source.includes("[native code]") ||
+		/^\s*(?:async\s+)?function\s+bound\b/.test(source)
+	)
+		return false;
+
+	const parameters = authStartParameterList(source);
+	if (!parameters) return false;
+	const parts = splitAuthStartParameters(parameters);
+	if (!parts || parts.length < 2) return false;
+
+	// Require ordinary, readable source formatting. This intentionally fails
+	// open for minified output and for transpilers that rewrite defaults.
+	const commaIndex = parameters.indexOf(",");
+	if (commaIndex < 0 || !/\s/.test(parameters[commaIndex + 1] ?? "")) return false;
+	const first = parts[0].trim();
+	const second = parts[1].trim();
+	const identifier = /^[_$A-Za-z][_$A-Za-z0-9]*/;
+	const firstName = first.match(identifier)?.[0];
+	const secondName = second.match(identifier)?.[0];
+	if (!firstName || !secondName || firstName.length < 3 || secondName.length < 3) return false;
+	return /\s=\s/.test(second);
+}
 
 export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
 	id: string;
@@ -510,6 +811,24 @@ function validateProviderShape(config: unknown): void {
 			},
 		);
 	}
+	if (
+		auth &&
+		typeof auth === "object" &&
+		"flow" in auth &&
+		auth.flow &&
+		typeof auth.flow === "object" &&
+		"start" in auth.flow &&
+		typeof auth.flow.start === "function" &&
+		auth.flow.start.length <= 1 &&
+		authStartHasHiddenInput(auth.flow.start)
+	) {
+		throw new ProviderError(
+			`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`,
+			{
+				fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+			},
+		);
+	}
 	const access = config.access;
 	if (access !== undefined) {
 		if (!access || typeof access !== "object" || Array.isArray(access)) {

package/src/index.ts

@@ -33,6 +33,7 @@ export {
 	defineSmsOtpMatcher,
 	defineStreamOperation,
 	every,
+	type AuthStartNoInputGuard,
 	type ProviderConfig,
 } from "./define.js";
 export type { DevServerOptions } from "./dev.js";

package/src/runtime/auth-flow.ts

@@ -6,6 +6,7 @@ import type {
 	FlowContext,
 	HttpClient,
 	OcrContext,
+	ProviderRuntimeState,
 	StealthClient,
 	SttContext,
 } from "../types.js";
@@ -59,6 +60,8 @@ export function createFlowContext(options: {
 	providerId: string;
 	connectionId?: string;
 	externalRef?: string;
+	/** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+	state?: ProviderRuntimeState;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
 	ocr?: OcrContext;
@@ -71,6 +74,7 @@ export function createFlowContext(options: {
 		tenantId: options.tenantId,
 		providerId: options.providerId,
 		http: options.http,
+		state: options.state,
 		stealth: options.stealth,
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),

package/src/runtime/browser.ts

@@ -816,6 +816,10 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 		return await this.page.evaluate(fn);
 	}
 
+	async userAgent(): Promise<string> {
+		return await this.evaluate<string>("navigator.userAgent");
+	}
+
 	async waitForSelector(selector: string, options?: { timeout?: number }): Promise<void> {
 		await this.page.waitForSelector(selector, options);
 	}
@@ -1509,6 +1513,10 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		return await this.evaluateWithContext<T>(fn);
 	}
 
+	async userAgent(): Promise<string> {
+		return await this.evaluate<string>("navigator.userAgent");
+	}
+
 	async evaluateInFrame<T>(frameId: string, fn: string | (() => T)): Promise<T> {
 		await this.initialize();
 		const contextId = await this.getFrameExecutionContextId(frameId);