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

package/dist/server/serve.d.ts

@@ -37,6 +37,7 @@ export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
                 credentials: "credentials";
                 oauth2: "oauth2";
                 "platform-managed": "platform-managed";
+                oauth2_proxied: "oauth2_proxied";
             }>;
             secrets: z.ZodRecord<z.ZodString, z.ZodString>;
             scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -142,14 +143,14 @@ export type ProviderServerOptions = {
      * @example
      * ```ts
      * await serve(provider, {
-     *   shutdown: {
-     *     hooks: [
-     *       async () => { await emitter.flush(); },
-     *       async () => { await sessionManager.closeAll("server-shutdown"); },
-     *       async () => { await lease.release(); },
-     *       async () => { await router.close(); },
-     *     ],
-     *   },
+     *	 shutdown: {
+     *		 hooks: [
+     *			 async () => { await emitter.flush(); },
+     *			 async () => { await sessionManager.closeAll("server-shutdown"); },
+     *			 async () => { await lease.release(); },
+     *			 async () => { await router.close(); },
+     *		 ],
+     *	 },
      * });
      * ```
      */

package/dist/server/serve.js

@@ -296,6 +296,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
         : undefined;
     return {
         context: {
+            flowId: request.flowId,
             connectionId: request.connectionId,
             externalRef: request.externalRef,
             tenantId: request.tenantId ?? "",
@@ -318,7 +319,12 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
                     },
                 }
                 : {}),
-            env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
+            env: createEnvContext([
+                ...(provider.secrets?.map((secret) => secret.name) ?? []),
+                ...(provider.auth?.mode === "oauth2_proxied"
+                    ? ["APIFUSE__AUTH_PROXY__URL"]
+                    : []),
+            ]),
             credential,
             context: flowContextStore.context,
             stt: options.stt ?? createSttClientFromEnv(provider.stt),

package/dist/server/types.d.ts

@@ -4,6 +4,7 @@ export declare const ConnectionModeSchema: z.ZodEnum<{
     credentials: "credentials";
     oauth2: "oauth2";
     "platform-managed": "platform-managed";
+    oauth2_proxied: "oauth2_proxied";
 }>;
 export declare const OperationConnectionSchema: z.ZodObject<{
     id: z.ZodString;
@@ -12,6 +13,7 @@ export declare const OperationConnectionSchema: z.ZodObject<{
         credentials: "credentials";
         oauth2: "oauth2";
         "platform-managed": "platform-managed";
+        oauth2_proxied: "oauth2_proxied";
     }>;
     secrets: z.ZodRecord<z.ZodString, z.ZodString>;
     scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -29,6 +31,7 @@ export declare const OperationRequestSchema: z.ZodObject<{
             credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -119,6 +122,7 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
             credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/server/types.js

@@ -1,7 +1,13 @@
 import { z } from "zod";
 import { PROVIDER_ERROR_SOURCES } from "../observability.js";
 import { HttpRetryPreset } from "../types.js";
-export const ConnectionModeSchema = z.enum(["oauth2", "credentials", "platform-managed", "none"]);
+export const ConnectionModeSchema = z.enum([
+    "oauth2",
+    "oauth2_proxied",
+    "credentials",
+    "platform-managed",
+    "none",
+]);
 export const OperationConnectionSchema = z.object({
     id: z.string(),
     mode: ConnectionModeSchema,

package/dist/testing/run.js

@@ -11,7 +11,13 @@ import { findStreamCaptureGroup, replayStreamEvidence } from "../stream-evidence
 // A single lowercase segment (no hyphen) is a valid id, so the trailing group
 // is optional (`*`), matching providers like `kakaomap`, `kstartup`, `triple`.
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
+const VALID_AUTH_MODES = [
+    "none",
+    "platform-managed",
+    "credentials",
+    "oauth2",
+    "oauth2_proxied",
+];
 const UPDATE_SNAPSHOT_ARGS = new Set(["-u", "--update-snapshots"]);
 const snapshotCaptureStates = new WeakMap();
 function isFixtureEnvelope(value) {
@@ -556,7 +562,7 @@ function formatJsonDiff(current, expected) {
         const expectedLine = expectedLines[index];
         if (currentLine === expectedLine) {
             if (currentLine !== undefined) {
-                lines.push(`  ${currentLine}`);
+                lines.push(`	${currentLine}`);
             }
             continue;
         }

package/dist/types.d.ts

@@ -47,6 +47,8 @@ export interface OperationToolRouterMetadata {
     riskClass?: OperationRiskClass;
     /** OpenAI remote-MCP approval hint. Defaults from riskClass. */
     approval?: OperationApprovalPolicy;
+    /** Canonical operation-level connection requirement consumed by the registry and Gateway. */
+    connectionMode?: "none" | "optional" | "required";
     /** Override connection requirement when provider auth + openWorld inference is insufficient. */
     requiresConnection?: boolean;
     /** Public argument used to resolve the tenant-owned connection. Defaults to externalRef. */
@@ -648,7 +650,7 @@ export interface StealthProfile {
     h2Settings?: Record<string, unknown>;
     headerOrder?: string[];
 }
-export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2";
+export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2" | "oauth2_proxied";
 export type ConnectionMode = AuthMode;
 export type ProviderReviewed = "first-party" | "community" | "staging";
 export type ProviderAccessVisibility = "public" | "early_access";
@@ -658,18 +660,18 @@ export type ProviderProxyMode = "disabled" | "optional" | "required";
  * (a common mistake because the names collide with a well-known rebrand):
  *
  * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
- *   *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
- *   endpoints). This is our own vendor. It is NOT the company formerly named
- *   "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ *	 *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *	 endpoints). This is our own vendor. It is NOT the company formerly named
+ *	 "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
  * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
- *   credentials; geo/session encoded in the username, no allocation API.
+ *	 credentials; geo/session encoded in the username, no allocation API.
  * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
- *   (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
- *   username params. A different company from `smartproxy` above.
- *   **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
- *   or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ *	 (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *	 username params. A different company from `smartproxy` above.
+ *	 **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
+ *	 or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
  * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
- *   `APIFUSE__PROXY__URL` env still works without declaring this value.
+ *	 `APIFUSE__PROXY__URL` env still works without declaring this value.
  */
 export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 export type ProviderProxySessionAffinity = "request" | "operation" | "auth-flow" | "connection";
@@ -715,9 +717,9 @@ export interface ProviderAccessConfig {
      * Provider-level rollout visibility.
      *
      * - `public`: visible in public docs/catalog/OpenAPI and callable through
-     *   the existing provider policy stack.
+     *	 the existing provider policy stack.
      * - `early_access`: hidden from public discovery and callable only when the
-     *   active customer organization has a provider-level access grant.
+     *	 active customer organization has a provider-level access grant.
      *
      * This is intentionally provider-level only. It does not alter auth mode,
      * operation schemas, health-check authoring, `openWorld`, or Connection
@@ -1528,6 +1530,8 @@ export interface AuthFlowTerminalContext {
     }): AuthTurn;
 }
 export interface FlowContext {
+    /** Gateway auth-flow id. Required by flow-scoped auth ceremonies. */
+    flowId?: string;
     connectionId?: string;
     externalRef?: string;
     tenantId: string;
@@ -1633,8 +1637,20 @@ export interface ProviderContext {
     stt: SttContext;
     choice: ProviderChoiceContext;
 }
+export interface ProxiedOAuthConfig {
+    authorizeUrl: string;
+    tokenUrl: string;
+    customScheme: string;
+    rewriteProfile: string;
+    clientIdEnvKey: string;
+    pkce?: "S256" | "none";
+    authorizeParams?: Record<string, string>;
+    tokenParams?: Record<string, string>;
+}
 export interface AuthConfig {
     mode: AuthMode;
+    /** Browser reverse-proxy contract for providers with custom-scheme OAuth callbacks. */
+    proxied?: ProxiedOAuthConfig;
     flow?: AuthFlowDefinition;
 }
 export interface ProviderSecretDeclaration {

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.20",
+	"version": "2.2.0-beta.21",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/ceremonies/index.ts

@@ -26,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";
@@ -248,6 +257,76 @@ export function createOAuth2Ceremony(options: {
 	};
 }
 
+/**
+ * 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;

package/src/define.ts

@@ -84,7 +84,36 @@ interface ProviderImplementationProfile {
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"] as const;
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
+const VALID_AUTH_MODES = [
+	"none",
+	"platform-managed",
+	"credentials",
+	"oauth2",
+	"oauth2_proxied",
+] as const;
+const PROXIED_OAUTH_REQUIRED_FIELDS = [
+	"authorizeUrl",
+	"tokenUrl",
+	"customScheme",
+	"rewriteProfile",
+	"clientIdEnvKey",
+] as const;
+const PROXIED_OAUTH_ALLOWED_FIELDS = new Set([
+	...PROXIED_OAUTH_REQUIRED_FIELDS,
+	"pkce",
+	"authorizeParams",
+	"tokenParams",
+]);
+const PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS = new Set([
+	"client_id",
+	"response_type",
+	"state",
+	"code_challenge",
+	"code_challenge_method",
+]);
+const PROXIED_OAUTH_PROFILE_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PROXIED_OAUTH_ENV_KEY_REGEX = /^[A-Z][A-Z0-9_]*__[A-Z0-9_]+$/;
+const CUSTOM_SCHEME_REGEX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/\S+$/;
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"] as const;
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"] as const;
 const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"] as const;
@@ -303,6 +332,111 @@ function assertLiteralField<TValue extends string>(
 		);
 	}
 }
+
+function validateProxiedOAuthParams(
+	value: unknown,
+	field: "authorizeParams" | "tokenParams",
+	providerId: string,
+): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.${field} must be an object of string values.`,
+		);
+	}
+	for (const [key, paramValue] of Object.entries(value)) {
+		if (!key.trim() || typeof paramValue !== "string") {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must contain non-empty keys and string values.`,
+			);
+		}
+		if (
+			field === "authorizeParams" &&
+			PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())
+		) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.authorizeParams cannot override reserved parameter "${key}".`,
+			);
+		}
+	}
+}
+
+function validateProxiedOAuthAuth(auth: Record<string, unknown>, providerId: string): void {
+	const proxied = auth.proxied;
+	if (auth.mode !== "oauth2_proxied") {
+		if (proxied !== undefined) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied is only valid when auth.mode is "oauth2_proxied".`,
+			);
+		}
+		return;
+	}
+	if (!proxied || typeof proxied !== "object" || Array.isArray(proxied)) {
+		throw new ValidationError(
+			`Provider "${providerId}" with auth.mode "oauth2_proxied" must declare auth.proxied.`,
+		);
+	}
+	const config = Object.fromEntries(Object.entries(proxied));
+	for (const key of Object.keys(config)) {
+		if (!PROXIED_OAUTH_ALLOWED_FIELDS.has(key)) {
+			throw new ValidationError(
+				`Provider "${providerId}" has unknown auth.proxied field "${key}".`,
+			);
+		}
+	}
+	for (const field of PROXIED_OAUTH_REQUIRED_FIELDS) {
+		if (typeof config[field] !== "string" || !config[field].trim()) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must be a non-empty string.`,
+			);
+		}
+	}
+	for (const field of ["authorizeUrl", "tokenUrl"] as const) {
+		try {
+			const endpoint = new URL(String(config[field]));
+			if (
+				endpoint.protocol !== "https:" ||
+				endpoint.username ||
+				endpoint.password ||
+				endpoint.hash
+			) {
+				throw new Error("invalid endpoint");
+			}
+		} catch {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must be an absolute HTTPS URL without credentials or a fragment.`,
+			);
+		}
+	}
+	const customScheme = String(config.customScheme);
+	if (
+		!CUSTOM_SCHEME_REGEX.test(customScheme) ||
+		customScheme.toLowerCase().startsWith("http://") ||
+		customScheme.toLowerCase().startsWith("https://")
+	) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.customScheme must be a non-HTTP custom-scheme URL prefix.`,
+		);
+	}
+	if (!PROXIED_OAUTH_PROFILE_REGEX.test(String(config.rewriteProfile))) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.rewriteProfile must be a kebab-case profile name.`,
+		);
+	}
+	if (!PROXIED_OAUTH_ENV_KEY_REGEX.test(String(config.clientIdEnvKey))) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.clientIdEnvKey must be an APIFuse-style uppercase environment key.`,
+		);
+	}
+	if (config.pkce !== undefined && config.pkce !== "S256" && config.pkce !== "none") {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.pkce must be "S256" or "none".`,
+		);
+	}
+	validateProxiedOAuthParams(config.authorizeParams, "authorizeParams", providerId);
+	validateProxiedOAuthParams(config.tokenParams, "tokenParams", providerId);
+}
+
 function validateProviderShape(config: unknown): void {
 	assertObjectConfig(config);
 	assertRequiredField(config, "id");
@@ -315,6 +449,9 @@ function validateProviderShape(config: unknown): void {
 	const auth = config.auth;
 	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
 		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
+	if (auth && typeof auth === "object" && !Array.isArray(auth)) {
+		validateProxiedOAuthAuth(Object.fromEntries(Object.entries(auth)), 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`,

package/src/index.ts

@@ -277,6 +277,7 @@ export type {
 	ProviderProxyConfig,
 	ProviderProxyMode,
 	ProviderProxyPolicy,
+	ProxiedOAuthConfig,
 	ProviderProxyProvider,
 	ProviderProxySessionAffinity,
 	ProviderPublicConnectionMode,

package/src/lint.ts

@@ -3,7 +3,13 @@ import type { ZodType } from "zod";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 
-type AuthModeLike = "none" | "platform-managed" | "credentials" | "oauth2" | "api-key";
+type AuthModeLike =
+	| "none"
+	| "platform-managed"
+	| "credentials"
+	| "oauth2"
+	| "oauth2_proxied"
+	| "api-key";
 
 type ProviderAuthLike = {
 	mode?: AuthModeLike;

package/src/provider.ts

@@ -148,6 +148,7 @@ export type {
 	ProviderLocaleKeyInput,
 	ProviderLogoProfile,
 	ProviderProxyPolicy,
+	ProxiedOAuthConfig,
 	ProviderPublicConnectionMode,
 	ProviderPublicProfile,
 	ProviderResolvedFile,

package/src/runtime/auth-flow.ts

@@ -48,6 +48,7 @@ export function createScratchpad(
 }
 
 export function createFlowContext(options: {
+	flowId?: string;
 	http: HttpClient;
 	stealth: StealthClient;
 	env: EnvContext;
@@ -60,6 +61,7 @@ export function createFlowContext(options: {
 	stt?: SttContext;
 }): FlowContext {
 	return {
+		flowId: options.flowId,
 		connectionId: options.connectionId,
 		externalRef: options.externalRef,
 		tenantId: options.tenantId,