@apifuse/provider-sdk 2.1.0-beta.11 → 2.1.0-beta.13

package/src/cli/create.ts

@@ -734,8 +734,8 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
 			return `{
     mode: "credentials",
     flow: {
-      start: async () => ({
-        kind: "input",
+      start: async (_ctx) => ({
+        kind: "form",
         turnId: crypto.randomUUID(),
         expectedInput: {
           schema: {
@@ -778,7 +778,7 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
 			return `{
     mode: "oauth2",
     flow: {
-      start: async () => ({
+      start: async (_ctx) => ({
         kind: "redirect",
         turnId: crypto.randomUUID(),
         data: {

package/src/define.ts

@@ -374,6 +374,14 @@ function validateProviderShape(config: unknown): void {
 			VALID_AUTH_MODES,
 			String(config.id),
 		);
+	if (auth && typeof auth === "object" && "exchange" in auth) {
+		throw new ProviderError(
+			`Provider "${String(config.id)}" auth.exchange is not part of the Provider SDK auth contract`,
+			{
+				fix: "Use the single canonical auth interface: auth.flow. Gateway calls auth.flow.start/continue/poll/abort/refresh only and persists complete turn data.credential as-is, so put login/token/session exchange inside auth.flow.continue.",
+			},
+		);
+	}
 	if (
 		auth &&
 		typeof auth === "object" &&

package/src/index.ts

@@ -1,5 +1,6 @@
 // @apifuse/provider-sdk
 
+export * from "./auth";
 export * from "./ceremonies";
 export * from "./choice-token";
 export type {
@@ -122,6 +123,12 @@ export type {
 	Bcp47Locale,
 	BrowserEngine,
 	BrowserOptions,
+	BrowserResourceBody,
+	BrowserResourceDecision,
+	BrowserResourceMethod,
+	BrowserResourcePolicy,
+	BrowserResourceRequest,
+	BrowserResourceRoute,
 	ConnectionMode,
 	ContextDeclaration,
 	CookieJar,

package/src/lint.ts

@@ -22,8 +22,12 @@ type ProviderAuthLike = {
 		abort?: unknown;
 		refresh?: unknown;
 	};
+	exchange?: unknown;
 };
 
+const AUTH_OPERATION_ID_PATTERN =
+	/^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
+
 type ProviderContractMetaLike = {
 	publicSchemaFieldNames?: "normalized";
 };
@@ -127,6 +131,10 @@ function lintReviewed(
 	];
 }
 
+function isProviderAuthLike(value: unknown): value is ProviderAuthLike {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
 function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	if (!keys) {
 		return false;
@@ -215,6 +223,15 @@ function lintAuthModel(provider: {
 		});
 	}
 
+	if (isProviderAuthLike(provider.auth) && "exchange" in provider.auth) {
+		diagnostics.push({
+			rule: "auth-exchange-unsupported",
+			level: "error",
+			field: "auth.exchange",
+			message: `${providerLabel} must not define auth.exchange. The Provider SDK has one auth interface: auth.flow. Gateway only calls auth.flow.start/continue/poll/abort/refresh and persists complete turn data.credential as-is; put login/token/session exchange inside auth.flow.continue.`,
+		});
+	}
+
 	if (authMode === "credentials" && credentialKeys.length === 0) {
 		diagnostics.push({
 			rule: "credential-keys-required-when-credentials-mode",
@@ -1006,6 +1023,22 @@ export function lintProvider(
 		...lintSelfHostedBrowserPatterns(provider, options),
 	];
 
+	if (provider.operations) {
+		const authMode = provider.auth?.mode;
+		if (authMode === "credentials" || authMode === "oauth2") {
+			for (const operationKey of Object.keys(provider.operations)) {
+				if (AUTH_OPERATION_ID_PATTERN.test(operationKey)) {
+					diagnostics.push({
+						rule: "auth-operation-unsupported",
+						level: "error",
+						field: `operations.${operationKey}`,
+						message: `Provider "${provider.id ?? "unknown"}" operation "${operationKey}" looks like a login/token/session exchange endpoint. Authenticated providers must expose login through the single auth.flow interface because Gateway persists only auth.flow complete turn data.credential as the connection credential. Move this logic into auth.flow.continue instead of a provider operation.`,
+					});
+				}
+			}
+		}
+	}
+
 	if (!provider.operations) {
 		return diagnostics;
 	}

package/src/provider.ts

@@ -1,3 +1,22 @@
+export {
+	AuthAbortError,
+	credentialsAuthChallenge,
+	createAuthFlowHelpers,
+	defineCredentialsAuth,
+} from "./auth";
+export type {
+	CredentialsAuthChallengeDefinition,
+	CredentialsAuthChallengeRequest,
+	CredentialsAuthCompleteResult,
+	CredentialsAuthCredential,
+	CredentialsAuthField,
+	CredentialsAuthFields,
+	CredentialsAuthFieldType,
+	CredentialsAuthInput,
+	CredentialsAuthLoginResult,
+	DefineCredentialsAuthOptions,
+	DefinedCredentialsAuth,
+} from "./auth";
 export { createFormCeremony } from "./ceremonies";
 export {
 	assertFreshProviderChoiceIssuedAt,
@@ -50,7 +69,12 @@ export {
 	z,
 } from "./schema";
 export type {
+	AuthAbortData,
+	AuthAbortRetry,
+	AuthFlowTerminalContext,
 	AuthMode,
+	AuthSafeData,
+	AuthSafeJson,
 	FlowContext,
 	HealthCheckAssertionContext,
 	HealthCheckCase,

package/src/runtime/auth-flow.ts

@@ -1,4 +1,5 @@
 import { ContextAccessError } from "../errors";
+import { createAuthFlowHelpers } from "../auth";
 import type {
 	ContextScratchpad,
 	EnvContext,
@@ -70,5 +71,6 @@ export function createFlowContext(options: {
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),
 		stt: options.stt ?? createUnsupportedSttClient(),
+		auth: createAuthFlowHelpers(),
 	};
 }

package/src/runtime/browser.ts

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import type { Frame, LaunchOptions, Locator, Page } from "playwright";
+import type { Frame, LaunchOptions, Locator, Page, Request, Route } from "playwright";
 
 import { ProviderError } from "../errors";
 import type {
@@ -11,11 +11,18 @@ import type {
 	BrowserLocator,
 	BrowserOptions,
 	BrowserPage,
+	BrowserResourceBody,
+	BrowserResourceDecision,
+	BrowserResourceMethod,
+	BrowserResourcePolicy,
+	BrowserResourceRequest,
 } from "../types";
 
 const require = createRequire(import.meta.url);
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const SELECTOR_POLL_INTERVAL_MS = 100;
+const RESOURCE_POLICY_ROUTE_PATTERN = "**/*";
+const DEFAULT_RESOURCE_METHODS = ["GET", "HEAD"] as const;
 
 type PlaywrightModule = typeof import("playwright");
 type PlaywrightExtraModule = {
@@ -62,8 +69,153 @@ type CdpFrameTreeNode = {
 	};
 };
 
+type CdpFetchFulfillParams = {
+	readonly requestId: string;
+	readonly responseCode: number;
+	readonly responseHeaders?: readonly {
+		readonly name: string;
+		readonly value: string;
+	}[];
+	readonly body?: string;
+};
+
 type BrowserPageContract = BrowserPage;
 
+function toResourceBody(
+	body: BrowserResourceBody | undefined,
+): Buffer | string | undefined {
+	if (body === undefined || typeof body === "string" || Buffer.isBuffer(body)) {
+		return body;
+	}
+
+	if (body instanceof ArrayBuffer) {
+		return Buffer.from(new Uint8Array(body));
+	}
+
+	return Buffer.from(body);
+}
+
+function isResourceMethod(method: string): method is BrowserResourceMethod {
+	return method === "GET" || method === "HEAD";
+}
+
+async function toResourceRequest(
+	request: Request,
+): Promise<BrowserResourceRequest | null> {
+	const method = request.method().toUpperCase();
+	if (!isResourceMethod(method)) {
+		return null;
+	}
+
+	return {
+		headers: await request.allHeaders(),
+		method,
+		resourceType: request.resourceType(),
+		url: request.url(),
+	};
+}
+
+function toCdpResourceRequest(
+	params: unknown,
+): { requestId: string; request: BrowserResourceRequest } | null {
+	if (!isRecord(params)) {
+		return null;
+	}
+
+	const requestId = params.requestId;
+	const rawRequest = params.request;
+	if (typeof requestId !== "string" || !isRecord(rawRequest)) {
+		return null;
+	}
+
+	const url = rawRequest.url;
+	const method = String(rawRequest.method ?? "").toUpperCase();
+	if (typeof url !== "string" || !isResourceMethod(method)) {
+		return null;
+	}
+
+	return {
+		requestId,
+		request: {
+			headers: toCdpResourceHeaders(rawRequest.headers),
+			method,
+			resourceType:
+				typeof params.resourceType === "string" ? params.resourceType : undefined,
+			url,
+		},
+	};
+}
+
+function getCdpPausedRequestId(params: unknown): string | null {
+	if (!isRecord(params) || typeof params.requestId !== "string") {
+		return null;
+	}
+
+	return params.requestId;
+}
+
+function toCdpResourceHeaders(value: unknown): Record<string, string> {
+	if (!isRecord(value)) {
+		return {};
+	}
+
+	const headers: Record<string, string> = {};
+	for (const [name, headerValue] of Object.entries(value)) {
+		if (typeof headerValue === "string") {
+			headers[name] = headerValue;
+		}
+	}
+
+	return headers;
+}
+
+function matchesResourceRoute(
+	match: BrowserResourcePolicy["routes"][number]["match"],
+	request: BrowserResourceRequest,
+): boolean {
+	if (typeof match === "string") {
+		return request.url === match;
+	}
+	if (match instanceof RegExp) {
+		return match.test(request.url);
+	}
+
+	return match(request);
+}
+
+function toCdpFulfillParams(
+	requestId: string,
+	decision: Extract<BrowserResourceDecision, { readonly action: "fulfill" }>,
+): CdpFetchFulfillParams {
+	const body = toResourceBody(decision.body);
+	return {
+		...(body === undefined
+			? {}
+			: { body: Buffer.from(body).toString("base64") }),
+		...(decision.headers === undefined
+			? {}
+			: {
+					responseHeaders: Object.entries(decision.headers).map(
+						([name, value]) => ({ name, value }),
+					),
+				}),
+		requestId,
+		responseCode: decision.status ?? 200,
+	};
+}
+
+async function fulfillResourceRoute(
+	route: Route,
+	decision: Extract<BrowserResourceDecision, { readonly action: "fulfill" }>,
+): Promise<void> {
+	const body = toResourceBody(decision.body);
+	await route.fulfill({
+		...(body === undefined ? {} : { body }),
+		...(decision.headers === undefined ? {} : { headers: decision.headers }),
+		status: decision.status ?? 200,
+	});
+}
+
 export type BrowserClientOptions = BrowserOptions & {
 	allowedHosts?: string[];
 	cdpUrl?: string;
@@ -398,6 +550,47 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 	async close(): Promise<void> {
 		await this.page.close();
 	}
+
+	async withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T> {
+		const allowedMethods = new Set(
+			policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS,
+		);
+		const handler = async (route: Route): Promise<void> => {
+			const request = await toResourceRequest(route.request());
+			if (!request || !allowedMethods.has(request.method)) {
+				await route.abort("blockedbyclient");
+				return;
+			}
+
+			for (const resourceRoute of policy.routes) {
+				if (!matchesResourceRoute(resourceRoute.match, request)) {
+					continue;
+				}
+
+				const decision = await resourceRoute.handle(request);
+				switch (decision.action) {
+					case "fulfill":
+						await fulfillResourceRoute(route, decision);
+						return;
+					case "block":
+						await route.abort("blockedbyclient");
+						return;
+				}
+			}
+
+			await route.abort("blockedbyclient");
+		};
+
+		await this.page.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+		try {
+			return await run();
+		} finally {
+			await this.page.unroute(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+		}
+	}
 }
 
 class PlaywrightBrowserClient implements SupportedBrowserClient {
@@ -1055,6 +1248,105 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		}
 	}
 
+	async withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T> {
+		const allowedMethods = new Set(
+			policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS,
+		);
+		const handlePausedRequest = (params: unknown): void => {
+			void this.handleResourcePolicyPausedRequest(
+				params,
+				policy,
+				allowedMethods,
+			);
+		};
+
+		const unsubscribe = this.pageClient.on(
+			"Fetch.requestPaused",
+			handlePausedRequest,
+		);
+
+		try {
+			await this.pageClient.send("Fetch.enable", {
+				patterns: [{ requestStage: "Request", urlPattern: "*" }],
+			});
+		} catch (error) {
+			unsubscribe();
+			throw new ProviderError(
+				"CDP browser target does not support BrowserPage.withResourcePolicy()",
+				{
+					cause: error instanceof Error ? error : undefined,
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+					fix: "Use a Chromium CDP target with the Fetch domain enabled, or use the local Playwright browser runtime.",
+				},
+			);
+		}
+
+		try {
+			return await run();
+		} finally {
+			unsubscribe();
+			await this.pageClient.send("Fetch.disable");
+		}
+	}
+
+	private async handleResourcePolicyPausedRequest(
+		params: unknown,
+		policy: BrowserResourcePolicy,
+		allowedMethods: ReadonlySet<BrowserResourceMethod>,
+	): Promise<void> {
+		const requestId = getCdpPausedRequestId(params);
+		if (requestId === null) {
+			return;
+		}
+
+		try {
+			const parsed = toCdpResourceRequest(params);
+			if (!parsed || !allowedMethods.has(parsed.request.method)) {
+				await this.failCdpResourceRequest(requestId);
+				return;
+			}
+
+			for (const resourceRoute of policy.routes) {
+				if (!matchesResourceRoute(resourceRoute.match, parsed.request)) {
+					continue;
+				}
+
+				const decision = await resourceRoute.handle(parsed.request);
+				switch (decision.action) {
+					case "fulfill":
+						await this.pageClient.send(
+							"Fetch.fulfillRequest",
+							toCdpFulfillParams(parsed.requestId, decision),
+						);
+						return;
+					case "block":
+						await this.failCdpResourceRequest(parsed.requestId);
+						return;
+				}
+			}
+
+			await this.failCdpResourceRequest(parsed.requestId);
+		} catch {
+			await this.failCdpResourceRequest(requestId);
+		}
+	}
+
+	private async failCdpResourceRequest(requestId: string): Promise<void> {
+		try {
+			await this.pageClient.send("Fetch.failRequest", {
+				errorReason: "BlockedByClient",
+				requestId,
+			});
+		} catch (error) {
+			if (error instanceof Error) {
+				return;
+			}
+		}
+	}
+
 	private async initialize(): Promise<void> {
 		if (this.initialized) {
 			return;

package/src/server/serve.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 
 import { Hono } from "hono";
 import { z } from "zod";
+import { AuthAbortError, createAuthFlowHelpers } from "../auth";
 import {
 	AuthError,
 	ProviderError,
@@ -329,6 +330,7 @@ function createAuthFlowContext(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
 	options: ProviderServerOptions = {},
+	signal?: AbortSignal,
 ): {
 	context: FlowContext;
 	getPatch: () => Record<string, unknown | null> | undefined;
@@ -383,6 +385,7 @@ function createAuthFlowContext(
 			credential,
 			context: flowContextStore.context,
 			stt: options.stt ?? createSttClientFromEnv(provider.stt),
+			auth: createAuthFlowHelpers({ signal }),
 		},
 		getPatch: flowContextStore.getPatch,
 	};
@@ -1291,6 +1294,7 @@ async function handleAuthFlow(
 	request: AuthFlowRequest,
 	route: AuthRoute,
 	options: ProviderServerOptions = {},
+	signal?: AbortSignal,
 ): Promise<Response | AuthFlowResponse> {
 	const flow = provider.auth?.flow;
 	if (!flow) {
@@ -1303,6 +1307,7 @@ async function handleAuthFlow(
 		provider,
 		request,
 		options,
+		signal,
 	);
 	try {
 		const result =
@@ -1336,6 +1341,11 @@ async function handleAuthFlow(
 				? materializeAuthFlowTurn(provider, request, result)
 				: result;
 		return toAuthFlowResponse(materializedResult, getPatch());
+	} catch (error) {
+		if (error instanceof AuthAbortError) {
+			return toAuthFlowResponse(error.turn, getPatch());
+		}
+		throw error;
 	} finally {
 		context.stealth.close?.();
 	}
@@ -1450,7 +1460,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "start", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"start",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1495,6 +1511,7 @@ export function createServerApp(
 				body,
 				"continue",
 				options,
+				c.req.raw.signal,
 			);
 			logProviderSuccess(
 				logger,
@@ -1535,7 +1552,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "poll", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"poll",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1575,7 +1598,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "refresh", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"refresh",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1615,7 +1644,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "abort", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"abort",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,