Add external browser support for OAuth2 authorization (#375)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

plugins/auth-oauth2/src/grants/authorizationCode.ts

@@ -1,5 +1,6 @@
 import { createHash, randomBytes } from 'node:crypto';
 import type { Context } from '@yaakapp/api';
+import { getRedirectUrlViaExternalBrowser } from '../callbackServer';
 import { fetchAccessToken } from '../fetchAccessToken';
 import { getOrRefreshAccessToken } from '../getOrRefreshAccessToken';
 import type { AccessToken, TokenStoreArgs } from '../store';
@@ -10,6 +11,15 @@ export const PKCE_SHA256 = 'S256';
 export const PKCE_PLAIN = 'plain';
 export const DEFAULT_PKCE_METHOD = PKCE_SHA256;
 
+export type CallbackType = 'localhost' | 'hosted';
+
+export interface ExternalBrowserOptions {
+  useExternalBrowser: boolean;
+  callbackType: CallbackType;
+  /** Port for localhost callback (only used when callbackType is 'localhost') */
+  callbackPort?: number;
+}
+
 export async function getAuthorizationCode(
   ctx: Context,
   contextId: string,
@@ -25,6 +35,7 @@ export async function getAuthorizationCode(
     credentialsInBody,
     pkce,
     tokenName,
+    externalBrowser,
   }: {
     authorizationUrl: string;
     accessTokenUrl: string;
@@ -40,6 +51,7 @@ export async function getAuthorizationCode(
       codeVerifier: string;
     } | null;
     tokenName: 'access_token' | 'id_token';
+    externalBrowser?: ExternalBrowserOptions;
   },
 ): Promise<AccessToken> {
   const tokenArgs: TokenStoreArgs = {
@@ -68,7 +80,6 @@ export async function getAuthorizationCode(
   }
   authorizationUrl.searchParams.set('response_type', 'code');
   authorizationUrl.searchParams.set('client_id', clientId);
-  if (redirectUri) authorizationUrl.searchParams.set('redirect_uri', redirectUri);
   if (scope) authorizationUrl.searchParams.set('scope', scope);
   if (state) authorizationUrl.searchParams.set('state', state);
   if (audience) authorizationUrl.searchParams.set('audience', audience);
@@ -80,12 +91,65 @@ export async function getAuthorizationCode(
     authorizationUrl.searchParams.set('code_challenge_method', pkce.challengeMethod);
   }
 
+  let code: string;
+  let actualRedirectUri: string | null = redirectUri;
+
+  // Use external browser flow if enabled
+  if (externalBrowser?.useExternalBrowser) {
+    const result = await getRedirectUrlViaExternalBrowser(ctx, authorizationUrl, {
+      callbackType: externalBrowser.callbackType,
+      callbackPort: externalBrowser.callbackPort,
+    });
+    // Pass null to skip redirect URI matching — the callback came from our own local server
+    const extractedCode = extractCode(result.callbackUrl, null);
+    if (!extractedCode) {
+      throw new Error('No authorization code found in callback URL');
+    }
+    code = extractedCode;
+    actualRedirectUri = result.redirectUri;
+  } else {
+    // Use embedded browser flow (original behavior)
+    if (redirectUri) {
+      authorizationUrl.searchParams.set('redirect_uri', redirectUri);
+    }
+    code = await getCodeViaEmbeddedBrowser(ctx, contextId, authorizationUrl, redirectUri);
+  }
+
+  console.log('[oauth2] Code found');
+  const response = await fetchAccessToken(ctx, {
+    grantType: 'authorization_code',
+    accessTokenUrl,
+    clientId,
+    clientSecret,
+    scope,
+    audience,
+    credentialsInBody,
+    params: [
+      { name: 'code', value: code },
+      ...(pkce ? [{ name: 'code_verifier', value: pkce.codeVerifier }] : []),
+      ...(actualRedirectUri ? [{ name: 'redirect_uri', value: actualRedirectUri }] : []),
+    ],
+  });
+
+  return storeToken(ctx, tokenArgs, response, tokenName);
+}
+
+/**
+ * Get authorization code using the embedded browser window.
+ * This is the original flow that monitors navigation events.
+ */
+async function getCodeViaEmbeddedBrowser(
+  ctx: Context,
+  contextId: string,
+  authorizationUrl: URL,
+  redirectUri: string | null,
+): Promise<string> {
   const dataDirKey = await getDataDirKey(ctx, contextId);
   const authorizationUrlStr = authorizationUrl.toString();
-  console.log('[oauth2] Authorizing', authorizationUrlStr);
+  console.log('[oauth2] Authorizing via embedded browser', authorizationUrlStr);
 
-  // biome-ignore lint/suspicious/noAsyncPromiseExecutor: none
-  const code = await new Promise<string>(async (resolve, reject) => {
+  // biome-ignore lint/suspicious/noAsyncPromiseExecutor: Required for this pattern
+  return new Promise<string>(async (resolve, reject) => {
     let foundCode = false;
     const { close } = await ctx.window.openUrl({
       dataDirKey,
@@ -110,31 +174,12 @@ export async function getAuthorizationCode(
           return;
         }
 
-        // Close the window here, because we don't need it anymore!
         foundCode = true;
         close();
         resolve(code);
       },
     });
   });
-
-  console.log('[oauth2] Code found');
-  const response = await fetchAccessToken(ctx, {
-    grantType: 'authorization_code',
-    accessTokenUrl,
-    clientId,
-    clientSecret,
-    scope,
-    audience,
-    credentialsInBody,
-    params: [
-      { name: 'code', value: code },
-      ...(pkce ? [{ name: 'code_verifier', value: pkce.codeVerifier }] : []),
-      ...(redirectUri ? [{ name: 'redirect_uri', value: redirectUri }] : []),
-    ],
-  });
-
-  return storeToken(ctx, tokenArgs, response, tokenName);
 }
 
 export function genPkceCodeVerifier() {

plugins/auth-oauth2/src/grants/implicit.ts

@@ -1,7 +1,9 @@
 import type { Context } from '@yaakapp/api';
+import { getRedirectUrlViaExternalBrowser } from '../callbackServer';
 import type { AccessToken, AccessTokenRawResponse } from '../store';
 import { getDataDirKey, getToken, storeToken } from '../store';
 import { isTokenExpired } from '../util';
+import type { ExternalBrowserOptions } from './authorizationCode';
 
 export async function getImplicit(
   ctx: Context,
@@ -15,6 +17,7 @@ export async function getImplicit(
     state,
     audience,
     tokenName,
+    externalBrowser,
   }: {
     authorizationUrl: string;
     responseType: string;
@@ -24,6 +27,7 @@ export async function getImplicit(
     state: string | null;
     audience: string | null;
     tokenName: 'access_token' | 'id_token';
+    externalBrowser?: ExternalBrowserOptions;
   },
 ): Promise<AccessToken> {
   const tokenArgs = {
@@ -43,9 +47,8 @@ export async function getImplicit(
   } catch {
     throw new Error(`Invalid authorization URL "${authorizationUrlRaw}"`);
   }
-  authorizationUrl.searchParams.set('response_type', 'token');
+  authorizationUrl.searchParams.set('response_type', responseType);
   authorizationUrl.searchParams.set('client_id', clientId);
-  if (redirectUri) authorizationUrl.searchParams.set('redirect_uri', redirectUri);
   if (scope) authorizationUrl.searchParams.set('scope', scope);
   if (state) authorizationUrl.searchParams.set('state', state);
   if (audience) authorizationUrl.searchParams.set('audience', audience);
@@ -56,11 +59,55 @@ export async function getImplicit(
     );
   }
 
-  // biome-ignore lint/suspicious/noAsyncPromiseExecutor: none
-  const newToken = await new Promise<AccessToken>(async (resolve, reject) => {
+  let newToken: AccessToken;
+
+  // Use external browser flow if enabled
+  if (externalBrowser?.useExternalBrowser) {
+    const result = await getRedirectUrlViaExternalBrowser(ctx, authorizationUrl, {
+      callbackType: externalBrowser.callbackType,
+      callbackPort: externalBrowser.callbackPort,
+    });
+    newToken = await extractImplicitToken(ctx, result.callbackUrl, tokenArgs, tokenName);
+  } else {
+    // Use embedded browser flow (original behavior)
+    if (redirectUri) {
+      authorizationUrl.searchParams.set('redirect_uri', redirectUri);
+    }
+    newToken = await getTokenViaEmbeddedBrowser(
+      ctx,
+      contextId,
+      authorizationUrl,
+      tokenArgs,
+      tokenName,
+    );
+  }
+
+  return newToken;
+}
+
+/**
+ * Get token using the embedded browser window.
+ * This is the original flow that monitors navigation events.
+ */
+async function getTokenViaEmbeddedBrowser(
+  ctx: Context,
+  contextId: string,
+  authorizationUrl: URL,
+  tokenArgs: {
+    contextId: string;
+    clientId: string;
+    accessTokenUrl: null;
+    authorizationUrl: string;
+  },
+  tokenName: 'access_token' | 'id_token',
+): Promise<AccessToken> {
+  const dataDirKey = await getDataDirKey(ctx, contextId);
+  const authorizationUrlStr = authorizationUrl.toString();
+  console.log('[oauth2] Authorizing via embedded browser (implicit)', authorizationUrlStr);
+
+  // biome-ignore lint/suspicious/noAsyncPromiseExecutor: Required for this pattern
+  return new Promise<AccessToken>(async (resolve, reject) => {
     let foundAccessToken = false;
-    const authorizationUrlStr = authorizationUrl.toString();
-    const dataDirKey = await getDataDirKey(ctx, contextId);
     const { close } = await ctx.window.openUrl({
       dataDirKey,
       url: authorizationUrlStr,
@@ -97,6 +144,56 @@ export async function getImplicit(
       },
     });
   });
-
-  return newToken;
+}
+
+/**
+ * Extract the implicit grant token from a callback URL and store it.
+ */
+async function extractImplicitToken(
+  ctx: Context,
+  callbackUrl: string,
+  tokenArgs: {
+    contextId: string;
+    clientId: string;
+    accessTokenUrl: null;
+    authorizationUrl: string;
+  },
+  tokenName: 'access_token' | 'id_token',
+): Promise<AccessToken> {
+  const url = new URL(callbackUrl);
+
+  // Check for errors
+  if (url.searchParams.has('error')) {
+    throw new Error(`Failed to authorize: ${url.searchParams.get('error')}`);
+  }
+
+  // Extract token from fragment
+  const hash = url.hash.slice(1);
+  const params = new URLSearchParams(hash);
+
+  // Also check query params (in case fragment was converted)
+  const accessToken = params.get(tokenName) ?? url.searchParams.get(tokenName);
+  if (!accessToken) {
+    throw new Error(`No ${tokenName} found in callback URL`);
+  }
+
+  // Build response from params (prefer fragment, fall back to query)
+  const response: AccessTokenRawResponse = {
+    access_token: params.get('access_token') ?? url.searchParams.get('access_token') ?? '',
+    token_type: params.get('token_type') ?? url.searchParams.get('token_type') ?? undefined,
+    expires_in: params.has('expires_in')
+      ? parseInt(params.get('expires_in') ?? '0', 10)
+      : url.searchParams.has('expires_in')
+        ? parseInt(url.searchParams.get('expires_in') ?? '0', 10)
+        : undefined,
+    scope: params.get('scope') ?? url.searchParams.get('scope') ?? undefined,
+  };
+
+  // Include id_token if present
+  const idToken = params.get('id_token') ?? url.searchParams.get('id_token');
+  if (idToken) {
+    response.id_token = idToken;
+  }
+
+  return storeToken(ctx, tokenArgs, response);
 }