signet-auth 1.0.0-beta.0

package/src/browser/flows/form-login.flow.ts

@@ -0,0 +1,35 @@
+import type { IBrowserPage } from '../../core/interfaces/browser-adapter.js';
+
+/**
+ * Detect and check for common login form patterns.
+ * Returns true if the page appears to be a login page.
+ */
+export async function isLoginPage(page: IBrowserPage): Promise<boolean> {
+  try {
+    const url = page.url().toLowerCase();
+    const loginUrlPatterns = [
+      '/login', '/signin', '/sign-in', '/auth', '/sso', '/oauth',
+      '/adfs/', '/saml/',
+      'login.microsoftonline.com', 'accounts.google.com',
+    ];
+    if (loginUrlPatterns.some(p => url.includes(p))) return true;
+
+    // Check for common form elements
+    const hasLoginForm = await page.evaluate(() => {
+      const inputs = document.querySelectorAll('input');
+      let hasPassword = false;
+      let hasEmail = false;
+      for (const input of inputs) {
+        const type = input.type.toLowerCase();
+        const name = (input.name || input.id || '').toLowerCase();
+        if (type === 'password') hasPassword = true;
+        if (type === 'email' || name.includes('email') || name.includes('user')) hasEmail = true;
+      }
+      return hasPassword || hasEmail;
+    });
+
+    return hasLoginForm;
+  } catch {
+    return false;
+  }
+}

package/src/browser/flows/header-capture.ts

@@ -0,0 +1,128 @@
+import type { IBrowserPage } from '../../core/interfaces/browser-adapter.js';
+import type { XHeaderConfig } from '../../core/types.js';
+
+export interface HeaderCaptureResult {
+  /** Captured headers (keyed by original config name, values last-write-wins) */
+  xHeaders: Record<string, string>;
+  /** Call to remove network listeners */
+  cleanup: () => void;
+}
+
+/**
+ * Start capturing HTTP headers from browser network traffic.
+ *
+ * - Static values are populated immediately.
+ * - Dynamic values are captured via onRequest/onResponse listeners.
+ * - Filters by providerDomains and optional urlPattern per config entry.
+ * - Header name matching is case-insensitive.
+ * - Gracefully degrades if the page doesn't support onRequest/onResponse.
+ *
+ * @param page           Browser page to observe
+ * @param configs        Header capture configurations
+ * @param providerDomains  Domains belonging to the provider (used as URL filter)
+ * @returns xHeaders record and a cleanup function
+ */
+export function startHeaderCapture(
+  page: IBrowserPage,
+  configs: XHeaderConfig[],
+  providerDomains: string[],
+): HeaderCaptureResult {
+  const xHeaders: Record<string, string> = {};
+  const cleanups: Array<() => void> = [];
+
+  // Separate static vs dynamic configs
+  const dynamicConfigs: XHeaderConfig[] = [];
+
+  for (const cfg of configs) {
+    if (cfg.staticValue !== undefined) {
+      xHeaders[cfg.name] = cfg.staticValue;
+    } else {
+      dynamicConfigs.push(cfg);
+    }
+  }
+
+  // If no dynamic configs or page doesn't support interception, return early
+  if (dynamicConfigs.length === 0) {
+    return { xHeaders, cleanup: () => {} };
+  }
+
+  // Build a set of request-source and response-source configs
+  const requestConfigs = dynamicConfigs.filter(c => !c.source || c.source === 'request');
+  const responseConfigs = dynamicConfigs.filter(c => !c.source || c.source === 'response');
+
+  // Helper: check if a URL matches the provider domains and optional urlPattern
+  function matchesUrl(url: string, urlPattern?: string): boolean {
+    // Must match at least one provider domain
+    let domainMatch = false;
+    try {
+      const parsed = new URL(url);
+      for (const domain of providerDomains) {
+        // Support wildcard domains like *.example.com
+        if (domain.startsWith('*.')) {
+          const suffix = domain.slice(1); // .example.com
+          if (parsed.hostname.endsWith(suffix) || parsed.hostname === domain.slice(2)) {
+            domainMatch = true;
+            break;
+          }
+        } else if (parsed.hostname === domain) {
+          domainMatch = true;
+          break;
+        }
+      }
+    } catch {
+      return false;
+    }
+    if (!domainMatch) return false;
+
+    // Optional urlPattern filter (simple substring match on full URL)
+    if (urlPattern) {
+      return url.includes(urlPattern);
+    }
+    return true;
+  }
+
+  // Helper: extract matching headers from a headers record
+  function extractHeaders(
+    configs: XHeaderConfig[],
+    url: string,
+    headers: Record<string, string>,
+  ): void {
+    for (const cfg of configs) {
+      if (!matchesUrl(url, cfg.urlPattern)) continue;
+
+      // Case-insensitive header lookup
+      const lowerName = cfg.name.toLowerCase();
+      for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lowerName) {
+          xHeaders[cfg.name] = value;
+          break;
+        }
+      }
+    }
+  }
+
+  // Set up request listener
+  if (requestConfigs.length > 0 && page.onRequest) {
+    const unsub = page.onRequest((req) => {
+      extractHeaders(requestConfigs, req.url, req.headers);
+    });
+    cleanups.push(unsub);
+  }
+
+  // Set up response listener
+  if (responseConfigs.length > 0 && page.onResponse) {
+    const unsub = page.onResponse((res) => {
+      extractHeaders(responseConfigs, res.url, res.headers);
+    });
+    cleanups.push(unsub);
+  }
+
+  return {
+    xHeaders,
+    cleanup: () => {
+      for (const fn of cleanups) {
+        fn();
+      }
+    },
+  };
+}

package/src/browser/flows/hybrid-flow.ts

@@ -0,0 +1,165 @@
+import type { IBrowserAdapter, IBrowserPage, IBrowserSession } from '../../core/interfaces/browser-adapter.js';
+import type { BrowserLaunchOptions, XHeaderConfig } from '../../core/types.js';
+import type { BrowserConfig } from '../../config/schema.js';
+import type { Result } from '../../core/result.js';
+import { ok, err } from '../../core/result.js';
+import { BrowserError, BrowserTimeoutError, type AuthError } from '../../core/errors.js';
+import { startHeaderCapture } from './header-capture.js';
+
+export interface HybridFlowOptions {
+  entryUrl: string;
+  /** Called on each page to check if auth is complete */
+  isAuthenticated: (page: IBrowserPage) => Promise<boolean>;
+  /** Called once auth is detected to extract credentials */
+  extractCredentials: (page: IBrowserPage, xHeaders?: Record<string, string>, meta?: { immediateAuth: boolean }) => Promise<Result<unknown, AuthError>>;
+  /** Global browser config (timeouts, waitUntil defaults) */
+  browserConfig: BrowserConfig;
+  /** Skip headless, go straight to visible (from provider config) */
+  forceVisible?: boolean;
+  /** Strategy-specific waitUntil override (e.g. cookie strategy uses 'networkidle') */
+  waitUntil?: 'load' | 'networkidle' | 'domcontentloaded' | 'commit';
+  /** Custom browser launch args */
+  browserArgs?: string[];
+  /** X-header configs — extra HTTP headers to capture during browser auth */
+  xHeaders?: XHeaderConfig[];
+  /** Provider domains used for filtering x-header capture */
+  providerDomains?: string[];
+}
+
+/**
+ * Hybrid browser flow: headless → visible fallback.
+ *
+ * 1. Tries headless browser first (fast, no user interaction)
+ * 2. If headless fails (timeout, CAPTCHA, cert dialog), switches to visible
+ * 3. In visible mode, waits for user to complete login manually
+ * 4. Extracts credentials once authenticated
+ *
+ * This flow is adapter-agnostic — works with any IBrowserAdapter.
+ */
+export async function runHybridFlow<T>(
+  adapter: IBrowserAdapter,
+  options: HybridFlowOptions,
+): Promise<Result<T, AuthError>> {
+  const { headlessTimeout, visibleTimeout } = options.browserConfig;
+
+  // Phase 1: Try headless (unless forceVisible)
+  if (!options.forceVisible) {
+    const headlessResult = await attemptAuth<T>(adapter, {
+      ...options,
+      headless: true,
+      timeout: headlessTimeout,
+    });
+    if (headlessResult.ok) return headlessResult;
+
+    console.error(
+      `[signet] Headless auth failed: ${headlessResult.error.message}. Switching to visible mode...`,
+    );
+  }
+
+  // Phase 2: Visible mode (user-assisted)
+  console.error('[signet] Please complete login in the browser window...');
+  return await attemptAuth<T>(adapter, {
+    ...options,
+    headless: false,
+    timeout: visibleTimeout,
+  });
+}
+
+async function attemptAuth<T>(
+  adapter: IBrowserAdapter,
+  options: HybridFlowOptions & { headless: boolean; timeout: number },
+): Promise<Result<T, AuthError>> {
+  let session: IBrowserSession | undefined;
+  let headerCleanup: (() => void) | undefined;
+
+  try {
+    const launchOptions: BrowserLaunchOptions = {
+      headless: options.headless,
+      timeout: options.timeout,
+      args: options.browserArgs,
+    };
+
+    session = await adapter.launch(launchOptions);
+    const page = await session.newPage();
+
+    // Set up x-header capture before navigation (so we capture all traffic)
+    let xHeaders: Record<string, string> | undefined;
+    if (options.xHeaders && options.xHeaders.length > 0) {
+      const capture = startHeaderCapture(
+        page,
+        options.xHeaders,
+        options.providerDomains ?? [],
+      );
+      xHeaders = capture.xHeaders;
+      headerCleanup = capture.cleanup;
+    }
+
+    // Navigate to entry URL
+    // Strategy can override global waitUntil (e.g. cookie forces 'networkidle')
+    const waitUntil = options.waitUntil ?? options.browserConfig.waitUntil;
+    await page.goto(options.entryUrl, {
+      waitUntil,
+      timeout: options.timeout,
+    });
+
+    // Brief pause to let any client-side redirects start
+    await new Promise(resolve => setTimeout(resolve, 1500));
+
+    // Check if already authenticated (cached session/cookies)
+    if (await options.isAuthenticated(page)) {
+      const result = await options.extractCredentials(page, xHeaders, { immediateAuth: true });
+      return result as Result<T, AuthError>;
+    }
+
+    // Wait for authentication to complete (polling)
+    const authenticated = await pollForAuth(
+      page,
+      options.isAuthenticated,
+      options.timeout,
+    );
+
+    if (!authenticated) {
+      return err(
+        new BrowserTimeoutError(
+          'waiting for authentication',
+          options.timeout,
+        ),
+      );
+    }
+
+    const result = await options.extractCredentials(page, xHeaders, { immediateAuth: false });
+    return result as Result<T, AuthError>;
+  } catch (e: unknown) {
+    if (e instanceof BrowserTimeoutError) {
+      return err(e);
+    }
+    return err(new BrowserError((e as Error).message));
+  } finally {
+    if (headerCleanup) {
+      headerCleanup();
+    }
+    if (session) {
+      await session.close().catch(() => {});
+    }
+  }
+}
+
+async function pollForAuth(
+  page: IBrowserPage,
+  isAuthenticated: (page: IBrowserPage) => Promise<boolean>,
+  timeoutMs: number,
+): Promise<boolean> {
+  const pollInterval = 2_000;
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    try {
+      if (await isAuthenticated(page)) return true;
+    } catch {
+      // Page might be navigating — ignore and retry
+    }
+    await new Promise(resolve => setTimeout(resolve, pollInterval));
+  }
+
+  return false;
+}

package/src/browser/flows/oauth-consent.flow.ts

@@ -0,0 +1,200 @@
+import type { IBrowserPage } from '../../core/interfaces/browser-adapter.js';
+import type { BearerCredential } from '../../core/types.js';
+import type { Result } from '../../core/result.js';
+import { ok, err } from '../../core/result.js';
+import { BrowserError, type AuthError } from '../../core/errors.js';
+import { decodeJwt, getJwtExpiresAt } from '../../utils/jwt.js';
+
+const EXPIRY_BUFFER_MS = 60_000; // 1 minute buffer
+
+/** Returns true if the JWT payload has a valid (non-expired) exp claim. */
+function isTokenValid(payload: ReturnType<typeof decodeJwt>): boolean {
+  if (!payload?.exp) return false;
+  return payload.exp * 1000 > Date.now() + EXPIRY_BUFFER_MS;
+}
+
+/**
+ * Extract OAuth tokens from browser localStorage.
+ * Searches for JWT-like strings and validates them against expected audiences.
+ */
+export async function extractOAuthTokens(
+  page: IBrowserPage,
+  options?: {
+    audiences?: string[];
+    extractRefreshToken?: boolean;
+    /** Max retries to wait for tokens to appear (default: 5, 2s apart) */
+    maxRetries?: number;
+  },
+): Promise<Result<BearerCredential, AuthError>> {
+  const maxRetries = options?.maxRetries ?? 5;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const result = await tryExtractTokens(page, options);
+    if (result.ok) return result;
+
+    // If this isn't the last attempt, wait and retry (MSAL may still be writing tokens)
+    if (attempt < maxRetries) {
+      await new Promise(resolve => setTimeout(resolve, 2000));
+    } else {
+      return result; // Return the last error
+    }
+  }
+
+  return err(new BrowserError('Token extraction exhausted all retries.'));
+}
+
+/**
+ * Check if OAuth tokens (JWTs) exist in browser storage.
+ * Used as a guard to ensure MSAL has finished writing tokens before
+ * the browser is closed.
+ */
+export async function hasOAuthTokens(
+  page: IBrowserPage,
+  audiences?: string[],
+): Promise<boolean> {
+  try {
+    const storage = await page.evaluate(() => {
+      const entries: Record<string, string> = {};
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key) entries['local:' + key] = localStorage.getItem(key) ?? '';
+      }
+      for (let i = 0; i < sessionStorage.length; i++) {
+        const key = sessionStorage.key(i);
+        if (key) entries['session:' + key] = sessionStorage.getItem(key) ?? '';
+      }
+      return entries;
+    });
+
+    const jwtRegex = /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+    const tokens: string[] = [];
+
+    for (const value of Object.values(storage)) {
+      const matches = value.match(jwtRegex);
+      if (matches) tokens.push(...matches);
+    }
+
+    if (tokens.length === 0) return false;
+
+    for (const token of tokens) {
+      const payload = decodeJwt(token);
+      if (!payload || !isTokenValid(payload)) continue;
+
+      if (audiences && audiences.length > 0) {
+        const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+        if (audiences.some(a => aud.includes(a))) return true;
+      } else {
+        return true;
+      }
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+async function tryExtractTokens(
+  page: IBrowserPage,
+  options?: {
+    audiences?: string[];
+    extractRefreshToken?: boolean;
+  },
+): Promise<Result<BearerCredential, AuthError>> {
+  try {
+    // Extract all entries from both localStorage and sessionStorage
+    const storage = await page.evaluate(() => {
+      const entries: Record<string, string> = {};
+      // Check localStorage
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key) entries['local:' + key] = localStorage.getItem(key) ?? '';
+      }
+      // Check sessionStorage
+      for (let i = 0; i < sessionStorage.length; i++) {
+        const key = sessionStorage.key(i);
+        if (key) entries['session:' + key] = sessionStorage.getItem(key) ?? '';
+      }
+      return entries;
+    });
+
+    // Find JWTs in localStorage values
+    const jwtRegex = /eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+    const tokens: string[] = [];
+
+    for (const value of Object.values(storage)) {
+      const matches = value.match(jwtRegex);
+      if (matches) tokens.push(...matches);
+    }
+
+    if (tokens.length === 0) {
+      return err(new BrowserError('No OAuth tokens found in browser localStorage.'));
+    }
+
+    // Find the best matching token: must be non-expired, match audience if specified,
+    // and prefer the one with the latest expiry.
+    let bestToken: string | undefined;
+    let bestPayload: ReturnType<typeof decodeJwt> | undefined;
+
+    for (const token of tokens) {
+      const payload = decodeJwt(token);
+      if (!payload || !isTokenValid(payload)) continue;
+
+      if (options?.audiences && options.audiences.length > 0) {
+        const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+        if (!options.audiences.some(a => aud.includes(a))) continue;
+      }
+
+      // Prefer the token with the latest expiry
+      if (!bestPayload || (payload.exp ?? 0) > (bestPayload.exp ?? 0)) {
+        bestToken = token;
+        bestPayload = payload;
+      }
+    }
+
+    if (!bestToken) {
+      return err(new BrowserError(
+        `No valid (non-expired) token matching audiences [${options?.audiences?.join(', ')}] found. ` +
+        `Found ${tokens.length} token(s) in storage.`,
+      ));
+    }
+
+    // Extract refresh token (MSAL format: keys containing "refreshtoken")
+    let refreshToken: string | undefined;
+    if (options?.extractRefreshToken) {
+      for (const [rawKey, value] of Object.entries(storage)) {
+        // Strip the 'local:' or 'session:' prefix for key matching
+        const key = rawKey.replace(/^(local|session):/, '');
+        if (key.toLowerCase().includes('refreshtoken')) {
+          try {
+            const parsed = JSON.parse(value);
+            if (parsed.secret) {
+              refreshToken = parsed.secret;
+              break;
+            }
+          } catch {
+            // Not JSON — skip
+          }
+        }
+      }
+    }
+
+    const expiresAt = bestPayload?.exp
+      ? new Date(bestPayload.exp * 1000).toISOString()
+      : undefined;
+
+    const credential: BearerCredential = {
+      type: 'bearer',
+      accessToken: bestToken,
+      refreshToken,
+      expiresAt,
+      scopes: bestPayload?.scp
+        ? String(bestPayload.scp).split(' ')
+        : undefined,
+    };
+
+    return ok(credential);
+  } catch (e: unknown) {
+    return err(new BrowserError(`Token extraction failed: ${(e as Error).message}`));
+  }
+}