@clinebot/core 0.0.27 → 0.0.29

package/src/auth/cline.ts

@@ -23,9 +23,17 @@ import {
 const DEFAULT_AUTH_ENDPOINTS = {
 	authorize: "/api/v1/auth/authorize",
 	token: "/api/v1/auth/token",
+	register: "/api/v1/auth/register",
 	refresh: "/api/v1/auth/refresh",
 } as const;
 
+const DEFAULT_WORKOS_ENDPOINTS = {
+	deviceAuthorization: "/user_management/authorize/device",
+	authenticate: "/user_management/authenticate",
+} as const;
+
+const DEFAULT_WORKOS_API_BASE_URL = "https://api.workos.com";
+const DEFAULT_WORKOS_CLIENT_ID = "client_01K3A541FN8TA3EPPHTD2325AR";
 const DEFAULT_CALLBACK_PATH = "/auth";
 const DEFAULT_CALLBACK_PORTS = Array.from(
 	{ length: 11 },
@@ -34,6 +42,8 @@ const DEFAULT_CALLBACK_PORTS = Array.from(
 const DEFAULT_REFRESH_BUFFER_MS = 5 * 60 * 1000;
 const DEFAULT_RETRYABLE_TOKEN_GRACE_MS = 30 * 1000;
 const DEFAULT_HTTP_TIMEOUT_MS = 30 * 1000;
+const DEFAULT_DEVICE_AUTH_EXPIRES_IN_SECONDS = 300;
+const DEFAULT_DEVICE_AUTH_INTERVAL_SECONDS = 5;
 
 export type ClineTokenResolution = {
 	forceRefresh?: boolean;
@@ -68,10 +78,15 @@ type HeaderInput = HeaderMap | (() => Promise<HeaderMap> | HeaderMap);
 export interface ClineOAuthProviderOptions {
 	apiBaseUrl: string;
 	headers?: HeaderInput;
-	callbackPath?: string;
-	callbackPorts?: number[];
 	requestTimeoutMs?: number;
 	telemetry?: ITelemetryService;
+	/**
+	 * Feature flag for WorkOS Device Authorization.
+	 * Defaults to false to preserve legacy callback-based OAuth behavior.
+	 */
+	useWorkOSDeviceAuth?: boolean;
+	callbackPath?: string;
+	callbackPorts?: number[];
 	/**
 	 * Optional identity provider name for token exchange.
 	 */
@@ -112,18 +127,6 @@ class ClineOAuthTokenError extends Error {
 	}
 }
 
-function createState(): string {
-	const cryptoApi = globalThis.crypto;
-	if (!cryptoApi) {
-		return Math.random().toString(16).slice(2);
-	}
-	const bytes = new Uint8Array(16);
-	cryptoApi.getRandomValues(bytes);
-	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join(
-		"",
-	);
-}
-
 function toEpochMs(isoDateTime: string): number {
 	const epoch = Date.parse(isoDateTime);
 	if (Number.isNaN(epoch)) {
@@ -165,22 +168,232 @@ async function resolveHeaders(input?: HeaderInput): Promise<HeaderMap> {
 	return typeof input === "function" ? await input() : input;
 }
 
-async function requestAuthorizationUrl(
+function toSeconds(value: unknown, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+		return fallback;
+	}
+	return Math.floor(value);
+}
+
+async function sleep(ms: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+type WorkOSDeviceAuthorizationResponse = {
+	device_code?: string;
+	user_code?: string;
+	verification_uri?: string;
+	verification_uri_complete?: string;
+	expires_in?: number;
+	interval?: number;
+	error?: string;
+	error_description?: string;
+};
+
+type WorkOSTokenResponse = {
+	access_token?: string;
+	refresh_token?: string;
+	token_type?: string;
+	expires_in?: number;
+	error?: string;
+	error_description?: string;
+};
+
+type WorkOSTokenSuccess = {
+	accessToken: string;
+	refreshToken: string;
+	tokenType: string;
+};
+
+function requireClineTokenResponse(
+	payload: ClineTokenResponse,
+	message: string,
+): ClineAuthResponseData {
+	if (!payload.success || !payload.data?.accessToken) {
+		throw new Error(message);
+	}
+	return payload.data;
+}
+
+async function requestWorkOSDeviceAuthorization(
+	clientId: string,
+	options?: { requestTimeoutMs?: number },
+): Promise<{
+	deviceCode: string;
+	userCode: string;
+	verificationUri: string;
+	verificationUriComplete?: string;
+	expiresInSeconds: number;
+	pollIntervalSeconds: number;
+}> {
+	const response = await fetch(
+		resolveUrl(
+			DEFAULT_WORKOS_API_BASE_URL,
+			DEFAULT_WORKOS_ENDPOINTS.deviceAuthorization,
+		),
+		{
+			method: "POST",
+			headers: {
+				"Content-Type": "application/x-www-form-urlencoded",
+			},
+			body: new URLSearchParams({ client_id: clientId }),
+			signal: AbortSignal.timeout(
+				options?.requestTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
+			),
+		},
+	);
+
+	const json = (await response
+		.json()
+		.catch(() => ({}))) as WorkOSDeviceAuthorizationResponse;
+	if (!response.ok) {
+		throw new ClineOAuthTokenError(
+			`Device authorization failed: ${response.status}${json.error_description ? ` - ${json.error_description}` : ""}`,
+			{ status: response.status, errorCode: json.error },
+		);
+	}
+	if (!json.device_code || !json.user_code || !json.verification_uri) {
+		throw new Error("Invalid WorkOS device authorization response");
+	}
+
+	return {
+		deviceCode: json.device_code,
+		userCode: json.user_code,
+		verificationUri: json.verification_uri,
+		verificationUriComplete: json.verification_uri_complete,
+		expiresInSeconds: toSeconds(
+			json.expires_in,
+			DEFAULT_DEVICE_AUTH_EXPIRES_IN_SECONDS,
+		),
+		pollIntervalSeconds: toSeconds(
+			json.interval,
+			DEFAULT_DEVICE_AUTH_INTERVAL_SECONDS,
+		),
+	};
+}
+
+async function pollWorkOSTokens(options: {
+	clientId: string;
+	deviceCode: string;
+	expiresInSeconds: number;
+	initialPollIntervalSeconds: number;
+	requestTimeoutMs: number;
+	workosApiBaseUrl: string;
+	onProgress?: OAuthLoginCallbacks["onProgress"];
+}): Promise<WorkOSTokenSuccess> {
+	const deadline = Date.now() + options.expiresInSeconds * 1000;
+	let intervalSeconds = Math.max(1, options.initialPollIntervalSeconds);
+
+	while (Date.now() <= deadline) {
+		const response = await fetch(
+			resolveUrl(
+				options.workosApiBaseUrl,
+				DEFAULT_WORKOS_ENDPOINTS.authenticate,
+			),
+			{
+				method: "POST",
+				headers: {
+					"Content-Type": "application/x-www-form-urlencoded",
+				},
+				body: new URLSearchParams({
+					grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+					device_code: options.deviceCode,
+					client_id: options.clientId,
+				}),
+				signal: AbortSignal.timeout(options.requestTimeoutMs),
+			},
+		);
+		const payload = (await response
+			.json()
+			.catch(() => ({}))) as WorkOSTokenResponse;
+		if (response.ok) {
+			if (!payload.access_token || !payload.refresh_token) {
+				throw new Error("Invalid WorkOS token response");
+			}
+			return {
+				accessToken: payload.access_token,
+				refreshToken: payload.refresh_token,
+				tokenType: payload.token_type ?? "Bearer",
+			};
+		}
+
+		switch (payload.error) {
+			case "authorization_pending": {
+				await sleep(intervalSeconds * 1000);
+				break;
+			}
+			case "slow_down": {
+				intervalSeconds += 1;
+				await sleep(intervalSeconds * 1000);
+				break;
+			}
+			case "access_denied":
+			case "expired_token":
+			case "invalid_grant": {
+				throw new ClineOAuthTokenError(
+					payload.error_description || "WorkOS authorization failed",
+					{
+						status: response.status,
+						errorCode: payload.error,
+					},
+				);
+			}
+			default: {
+				throw new ClineOAuthTokenError(
+					`WorkOS token polling failed: ${response.status}${payload.error_description ? ` - ${payload.error_description}` : ""}`,
+					{
+						status: response.status,
+						errorCode: payload.error,
+					},
+				);
+			}
+		}
+
+		options.onProgress?.("Waiting for browser authentication confirmation...");
+	}
+
+	throw new Error("WorkOS device authorization timed out");
+}
+
+async function registerWorkOSTokens(
+	workosTokens: WorkOSTokenSuccess,
 	options: ClineOAuthProviderOptions,
-	params: {
-		callbackUrl: string;
-		state: string;
-	},
-): Promise<string> {
-	const authUrl = new URL(
-		resolveUrl(options.apiBaseUrl, DEFAULT_AUTH_ENDPOINTS.authorize),
+	provider?: string,
+): Promise<ClineOAuthCredentials> {
+	const body = {
+		accessToken: workosTokens.accessToken,
+		refreshToken: workosTokens.refreshToken,
+	};
+
+	const response = await fetch(
+		resolveUrl(options.apiBaseUrl, DEFAULT_AUTH_ENDPOINTS.register),
+		{
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...(await resolveHeaders(options.headers)),
+			},
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(
+				options.requestTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
+			),
+		},
 	);
-	authUrl.searchParams.set("client_type", "extension");
-	authUrl.searchParams.set("callback_url", params.callbackUrl);
-	authUrl.searchParams.set("redirect_uri", params.callbackUrl);
-	authUrl.searchParams.set("state", params.state);
 
-	return authUrl.toString();
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		const details = parseOAuthError(text);
+		throw new ClineOAuthTokenError(
+			`Token registration failed: ${response.status}${details.message ? ` - ${details.message}` : ""}`,
+			{ status: response.status, errorCode: details.code },
+		);
+	}
+
+	const json = (await response.json()) as ClineTokenResponse;
+	return toClineCredentials(
+		requireClineTokenResponse(json, "Invalid token exchange response"),
+		provider ?? options.provider,
+	);
 }
 
 async function exchangeAuthorizationCode(
@@ -222,11 +435,10 @@ async function exchangeAuthorizationCode(
 	}
 
 	const json = (await response.json()) as ClineTokenResponse;
-	if (!json.success || !json.data?.accessToken) {
-		throw new Error("Invalid token exchange response");
-	}
-
-	return toClineCredentials(json.data, provider ?? options.provider);
+	return toClineCredentials(
+		requireClineTokenResponse(json, "Invalid token exchange response"),
+		provider ?? options.provider,
+	);
 }
 
 export async function loginClineOAuth(
@@ -235,76 +447,102 @@ export async function loginClineOAuth(
 	},
 ): Promise<ClineOAuthCredentials> {
 	captureAuthStarted(options.telemetry, options.provider ?? "cline");
+	const useWorkOSDeviceAuth = options.useWorkOSDeviceAuth;
 	const callbackPorts = options.callbackPorts?.length
 		? options.callbackPorts
 		: DEFAULT_CALLBACK_PORTS;
 	const callbackPath = options.callbackPath ?? DEFAULT_CALLBACK_PATH;
-	const state = createState();
-
-	const localServer = await startLocalOAuthServer({
-		ports: callbackPorts,
-		callbackPath,
-	});
-
+	const localServer = useWorkOSDeviceAuth
+		? null
+		: await startLocalOAuthServer({
+				ports: callbackPorts,
+				callbackPath,
+			});
 	const callbackUrl =
-		localServer.callbackUrl ||
+		localServer?.callbackUrl ||
 		`http://127.0.0.1:${callbackPorts[0] ?? DEFAULT_CALLBACK_PORTS[0]}${callbackPath}`;
 
-	const authUrl = await requestAuthorizationUrl(options, {
-		callbackUrl,
-		state,
-	});
-	options.callbacks.onAuth({
-		url: authUrl,
-		instructions: "Continue the authentication process in your browser.",
-	});
-
 	try {
-		let code: string | undefined;
-		let provider = options.provider;
-
-		const authResult = await resolveAuthorizationCodeInput({
-			waitForCallback: localServer.waitForCallback,
-			cancelWait: localServer.cancelWait,
-			onManualCodeInput: options.callbacks.onManualCodeInput,
-			parseOptions: { includeProvider: true },
-		});
-		if (authResult.error) {
-			throw new Error(`OAuth error: ${authResult.error}`);
-		}
-		if (authResult.state && authResult.state !== state) {
-			throw new Error("State mismatch");
-		}
-		code = authResult.code;
-		provider = authResult.provider ?? provider;
+		let credentials: ClineOAuthCredentials;
+		if (useWorkOSDeviceAuth) {
+			const clientId = DEFAULT_WORKOS_CLIENT_ID;
+			const deviceAuthorization = await requestWorkOSDeviceAuthorization(
+				clientId,
+				options,
+			);
+			options.callbacks.onAuth({
+				url:
+					deviceAuthorization.verificationUriComplete ??
+					deviceAuthorization.verificationUri,
+				instructions: `Enter this code in your browser: ${deviceAuthorization.userCode}`,
+			});
 
-		if (!code) {
-			const input = await options.callbacks.onPrompt({
-				message: "Paste the authorization code (or full redirect URL):",
+			const workosTokens = await pollWorkOSTokens({
+				clientId,
+				deviceCode: deviceAuthorization.deviceCode,
+				expiresInSeconds: deviceAuthorization.expiresInSeconds,
+				initialPollIntervalSeconds: deviceAuthorization.pollIntervalSeconds,
+				requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
+				workosApiBaseUrl: DEFAULT_WORKOS_API_BASE_URL,
+				onProgress: options.callbacks.onProgress,
 			});
-			const parsed = parseAuthorizationInput(input, { includeProvider: true });
-			if (parsed.state && parsed.state !== state) {
-				throw new Error("State mismatch");
-			}
-			code = parsed.code;
-			provider = parsed.provider ?? provider;
-		}
 
-		if (!code) {
-			throw new Error("Missing authorization code");
+			credentials = await registerWorkOSTokens(
+				workosTokens,
+				options,
+				options.provider,
+			);
+		} else {
+			const authUrl = new URL(
+				resolveUrl(options.apiBaseUrl, DEFAULT_AUTH_ENDPOINTS.authorize),
+			);
+			authUrl.searchParams.set("client_type", "extension");
+			authUrl.searchParams.set("callback_url", callbackUrl);
+			authUrl.searchParams.set("redirect_uri", callbackUrl);
+			options.callbacks.onAuth({
+				url: authUrl.toString(),
+				instructions: "Continue the authentication process in your browser.",
+			});
+
+			let code: string | undefined;
+			let provider = options.provider;
+			const authResult = await resolveAuthorizationCodeInput({
+				waitForCallback: localServer?.waitForCallback ?? (async () => null),
+				cancelWait: localServer?.cancelWait ?? (() => {}),
+				onManualCodeInput: options.callbacks.onManualCodeInput,
+				parseOptions: { includeProvider: true },
+			});
+			if (authResult.error) {
+				throw new Error(`OAuth error: ${authResult.error}`);
+			}
+			code = authResult.code;
+			provider = authResult.provider ?? provider;
+			if (!code) {
+				const input = await options.callbacks.onPrompt({
+					message: "Paste the authorization code (or full redirect URL):",
+				});
+				const parsed = parseAuthorizationInput(input, {
+					includeProvider: true,
+				});
+				code = parsed.code;
+				provider = parsed.provider ?? provider;
+			}
+			if (!code) {
+				throw new Error("Missing authorization code");
+			}
+			credentials = await exchangeAuthorizationCode(
+				code,
+				callbackUrl,
+				options,
+				provider,
+			);
 		}
 
-		const credentials = await exchangeAuthorizationCode(
-			code,
-			callbackUrl,
-			options,
-			provider,
-		);
-		captureAuthSucceeded(options.telemetry, provider ?? "cline");
+		captureAuthSucceeded(options.telemetry, options.provider ?? "cline");
 		identifyAccount(options.telemetry, {
 			id: credentials.accountId,
 			email: credentials.email,
-			provider: provider ?? "cline",
+			provider: options.provider ?? "cline",
 		});
 		return credentials;
 	} catch (error) {
@@ -315,7 +553,71 @@ export async function loginClineOAuth(
 		);
 		throw error;
 	} finally {
-		localServer.close();
+		localServer?.close();
+	}
+}
+
+export async function startClineDeviceAuth(options?: {
+	requestTimeoutMs?: number;
+}): Promise<{
+	deviceCode: string;
+	userCode: string;
+	verificationUri: string;
+	verificationUriComplete?: string;
+	expiresInSeconds: number;
+	pollIntervalSeconds: number;
+}> {
+	return await requestWorkOSDeviceAuthorization(
+		DEFAULT_WORKOS_CLIENT_ID,
+		options,
+	);
+}
+
+export async function completeClineDeviceAuth(options: {
+	deviceCode: string;
+	expiresInSeconds: number;
+	pollIntervalSeconds: number;
+	apiBaseUrl: string;
+	provider?: string;
+	headers?: HeaderInput;
+	requestTimeoutMs?: number;
+	telemetry?: ITelemetryService;
+}): Promise<ClineOAuthCredentials> {
+	const providerName = options.provider ?? "cline";
+	captureAuthStarted(options.telemetry, providerName);
+	try {
+		const workosTokens = await pollWorkOSTokens({
+			clientId: DEFAULT_WORKOS_CLIENT_ID,
+			deviceCode: options.deviceCode,
+			expiresInSeconds: options.expiresInSeconds,
+			initialPollIntervalSeconds: options.pollIntervalSeconds,
+			requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS,
+			workosApiBaseUrl: DEFAULT_WORKOS_API_BASE_URL,
+		});
+		const credentials = await registerWorkOSTokens(
+			workosTokens,
+			{
+				apiBaseUrl: options.apiBaseUrl,
+				headers: options.headers,
+				requestTimeoutMs: options.requestTimeoutMs,
+				provider: options.provider,
+			},
+			options.provider,
+		);
+		captureAuthSucceeded(options.telemetry, providerName);
+		identifyAccount(options.telemetry, {
+			id: credentials.accountId,
+			email: credentials.email,
+			provider: providerName,
+		});
+		return credentials;
+	} catch (error) {
+		captureAuthFailed(
+			options.telemetry,
+			providerName,
+			error instanceof Error ? error.message : String(error),
+		);
+		throw error;
 	}
 }
 
@@ -351,13 +653,13 @@ export async function refreshClineToken(
 	}
 
 	const json = (await response.json()) as ClineTokenResponse;
-	if (!json.success || !json.data?.accessToken) {
-		throw new Error("Invalid token refresh response");
-	}
-
 	const provider =
 		(current.metadata?.provider as string | undefined) ?? options.provider;
-	return toClineCredentials(json.data, provider, current);
+	return toClineCredentials(
+		requireClineTokenResponse(json, "Invalid token refresh response"),
+		provider,
+		current,
+	);
 }
 
 export async function getValidClineCredentials(
@@ -406,7 +708,7 @@ export function createClineOAuthProvider(
 	return {
 		id: "cline",
 		name: "Cline Account",
-		usesCallbackServer: true,
+		usesCallbackServer: !options.useWorkOSDeviceAuth,
 		async login(callbacks) {
 			return loginClineOAuth({ ...options, callbacks });
 		},

package/src/auth/oca.test.ts

@@ -212,4 +212,129 @@ describe("auth/oca getValidOcaCredentials", () => {
 		expect(result).toBe(current);
 		nowSpy.mockRestore();
 	});
+
+	it("re-discovers token endpoint shortly after discovery fallback errors", async () => {
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(100_000);
+		const fetchMock = vi
+			.fn()
+			// first refresh: discovery fails and fallback endpoint is used
+			.mockImplementationOnce(async () => new Response(null, { status: 503 }))
+			.mockImplementationOnce(
+				async () =>
+					new Response(
+						JSON.stringify({
+							error: "server_error",
+							error_description: "temporary issue",
+						}),
+						{
+							status: 500,
+							headers: { "Content-Type": "application/json" },
+						},
+					),
+			)
+			// second refresh within fallback TTL: discovery should still be cached
+			.mockImplementationOnce(
+				async () =>
+					new Response(
+						JSON.stringify({
+							error: "server_error",
+							error_description: "temporary issue",
+						}),
+						{
+							status: 500,
+							headers: { "Content-Type": "application/json" },
+						},
+					),
+			)
+			// third refresh after fallback TTL: discovery should be retried
+			.mockImplementationOnce(
+				async () =>
+					new Response(
+						JSON.stringify({
+							token_endpoint: "https://idcs.fallback/oauth2/v2/token",
+						}),
+						{
+							status: 200,
+							headers: { "Content-Type": "application/json" },
+						},
+					),
+			)
+			.mockImplementationOnce(
+				async () =>
+					new Response(
+						JSON.stringify({
+							error: "server_error",
+							error_description: "temporary issue",
+						}),
+						{
+							status: 500,
+							headers: { "Content-Type": "application/json" },
+						},
+					),
+			);
+		vi.stubGlobal("fetch", fetchMock);
+
+		const current = createCredentials({ expires: 10_000_000 });
+		const providerOptions = {
+			config: {
+				internal: {
+					clientId: "client-fallback-ttl",
+					idcsUrl: "https://idcs.fallback",
+					scopes: "openid offline_access",
+					baseUrl: "https://oca.example.com",
+				},
+			},
+		};
+
+		const first = await getValidOcaCredentials(
+			current,
+			{ forceRefresh: true },
+			providerOptions,
+		);
+		expect(first).toBe(current);
+
+		nowSpy.mockReturnValue(200_000);
+		const second = await getValidOcaCredentials(
+			current,
+			{ forceRefresh: true },
+			providerOptions,
+		);
+		expect(second).toBe(current);
+
+		nowSpy.mockReturnValue(500_001);
+		const third = await getValidOcaCredentials(
+			current,
+			{ forceRefresh: true },
+			providerOptions,
+		);
+		expect(third).toBe(current);
+
+		expect(fetchMock).toHaveBeenCalledTimes(5);
+		expect(fetchMock).toHaveBeenNthCalledWith(
+			1,
+			"https://idcs.fallback/.well-known/openid-configuration",
+			expect.objectContaining({ method: "GET" }),
+		);
+		expect(fetchMock).toHaveBeenNthCalledWith(
+			2,
+			"https://idcs.fallback/oauth2/v1/token",
+			expect.objectContaining({ method: "POST" }),
+		);
+		expect(fetchMock).toHaveBeenNthCalledWith(
+			3,
+			"https://idcs.fallback/oauth2/v1/token",
+			expect.objectContaining({ method: "POST" }),
+		);
+		expect(fetchMock).toHaveBeenNthCalledWith(
+			4,
+			"https://idcs.fallback/.well-known/openid-configuration",
+			expect.objectContaining({ method: "GET" }),
+		);
+		expect(fetchMock).toHaveBeenNthCalledWith(
+			5,
+			"https://idcs.fallback/oauth2/v2/token",
+			expect.objectContaining({ method: "POST" }),
+		);
+		nowSpy.mockRestore();
+	});
 });