@apitap/core 1.0.0

package/src/auth/handoff.ts

@@ -0,0 +1,229 @@
+// src/auth/handoff.ts
+import type { AuthManager } from './manager.js';
+import type { StoredSession, StoredAuth } from '../types.js';
+
+export interface HandoffOptions {
+  domain: string;
+  loginUrl?: string;        // URL to navigate to (defaults to https://<domain>)
+  timeout?: number;          // ms, default 300000 (5 minutes)
+}
+
+export interface HandoffResult {
+  success: boolean;
+  cookieCount: number;
+  authDetected?: 'bearer' | 'cookie' | 'api-key';
+  error?: string;
+}
+
+// Session-like cookie name patterns
+const SESSION_COOKIE_PATTERNS = [
+  /sess/i, /auth/i, /token/i, /jwt/i, /login/i,
+  /sid$/i, /^_session/i, /^connect\.sid$/i,
+];
+
+// Tracking/analytics cookie patterns (exclude from session detection)
+const TRACKING_COOKIE_PATTERNS = [
+  /^_ga/i, /^_gid/i, /^_fb/i, /^_gcl/i, /^__utm/i,
+];
+
+/**
+ * Detect whether a response indicates successful login.
+ * Checks for session-like Set-Cookie headers on 2xx responses.
+ */
+export function detectLoginSuccess(
+  headers: Map<string, string>,
+  status: number,
+): boolean {
+  if (status < 200 || status >= 300) return false;
+
+  // Check for auth header
+  const authHeader = headers.get('authorization');
+  if (authHeader && (authHeader.startsWith('Bearer ') || authHeader.startsWith('Basic '))) {
+    return true;
+  }
+
+  // Check for session-like cookies
+  const setCookie = headers.get('set-cookie');
+  if (!setCookie) return false;
+
+  // Parse cookie name from Set-Cookie header
+  const cookieName = setCookie.split('=')[0].trim();
+
+  // Exclude tracking cookies
+  if (TRACKING_COOKIE_PATTERNS.some(p => p.test(cookieName))) return false;
+
+  // Match session-like cookies
+  return SESSION_COOKIE_PATTERNS.some(p => p.test(cookieName));
+}
+
+// Mutex to prevent concurrent handoffs for the same domain
+const handoffLocks = new Map<string, Promise<HandoffResult>>();
+
+/**
+ * Open a visible browser for human authentication.
+ *
+ * Flow:
+ * 1. Launch visible Chromium browser
+ * 2. Navigate to login URL
+ * 3. Wait for human to log in (watches for session cookies / auth headers)
+ * 4. Capture all cookies + detected auth
+ * 5. Store encrypted via AuthManager
+ * 6. Close browser, return result
+ */
+export async function requestAuth(
+  authManager: AuthManager,
+  options: HandoffOptions,
+): Promise<HandoffResult> {
+  const { domain } = options;
+
+  // Mutex: prevent concurrent handoffs for same domain
+  const existing = handoffLocks.get(domain);
+  if (existing) return existing;
+
+  const promise = doHandoff(authManager, options);
+  handoffLocks.set(domain, promise);
+
+  try {
+    return await promise;
+  } finally {
+    handoffLocks.delete(domain);
+  }
+}
+
+async function doHandoff(
+  authManager: AuthManager,
+  options: HandoffOptions,
+): Promise<HandoffResult> {
+  const { domain } = options;
+  const loginUrl = options.loginUrl || `https://${domain}`;
+  const timeout = options.timeout ?? 300_000; // 5 minutes
+
+  const { chromium } = await import('playwright');
+
+  const browser = await chromium.launch({ headless: false });
+
+  try {
+    const context = await browser.newContext();
+
+    // Restore existing session cookies if available (warm start)
+    const cachedSession = await authManager.retrieveSession(domain);
+    if (cachedSession?.cookies?.length) {
+      await context.addCookies(cachedSession.cookies);
+    }
+
+    const page = await context.newPage();
+    let authDetected: 'bearer' | 'cookie' | 'api-key' | undefined;
+    let detectedAuth: StoredAuth | undefined;
+
+    // Watch network responses for auth signals
+    page.on('response', (response) => {
+      const headers = new Map<string, string>();
+      for (const [key, value] of Object.entries(response.headers())) {
+        headers.set(key, value);
+      }
+
+      // Detect auth from request headers
+      const authHeader = response.request().headers()['authorization'];
+      if (authHeader) {
+        if (authHeader.startsWith('Bearer ')) {
+          authDetected = 'bearer';
+          detectedAuth = {
+            type: 'bearer',
+            header: 'authorization',
+            value: authHeader,
+          };
+        } else if (authHeader.toLowerCase().startsWith('apikey ') || authHeader.toLowerCase().startsWith('api-key ')) {
+          authDetected = 'api-key';
+          detectedAuth = {
+            type: 'api-key',
+            header: 'authorization',
+            value: authHeader,
+          };
+        }
+      }
+    });
+
+    // Navigate to login page
+    await page.goto(loginUrl, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+
+    // Poll for login success: check cookies periodically
+    const startTime = Date.now();
+    let loginDetected = false;
+
+    while (Date.now() - startTime < timeout) {
+      await page.waitForTimeout(2000);
+
+      // Check if we've detected session cookies
+      const cookies = await context.cookies();
+      const hasSessionCookie = cookies.some(c =>
+        SESSION_COOKIE_PATTERNS.some(p => p.test(c.name)) &&
+        !TRACKING_COOKIE_PATTERNS.some(p => p.test(c.name))
+      );
+
+      if (hasSessionCookie || authDetected) {
+        // Wait a bit more for any final redirects/requests
+        await page.waitForTimeout(2000);
+        loginDetected = true;
+        break;
+      }
+
+      // Check if browser was closed by user
+      if (page.isClosed()) break;
+    }
+
+    // Capture final cookies
+    const cookies = await context.cookies();
+
+    if (cookies.length === 0 && !authDetected) {
+      return {
+        success: false,
+        cookieCount: 0,
+        error: loginDetected ? undefined : 'Timeout: no login detected within the allowed time',
+      };
+    }
+
+    // Store session cookies
+    const session: StoredSession = {
+      cookies,
+      savedAt: new Date().toISOString(),
+      maxAgeMs: 24 * 60 * 60 * 1000, // 24 hours
+    };
+    await authManager.storeSession(domain, session);
+
+    // Store detected auth header if found
+    if (detectedAuth) {
+      await authManager.store(domain, detectedAuth);
+    } else if (cookies.length > 0) {
+      // Store as cookie auth
+      const sessionCookies = cookies
+        .filter(c => SESSION_COOKIE_PATTERNS.some(p => p.test(c.name)))
+        .filter(c => !TRACKING_COOKIE_PATTERNS.some(p => p.test(c.name)));
+
+      if (sessionCookies.length > 0) {
+        authDetected = 'cookie';
+        const cookieHeader = sessionCookies
+          .map(c => `${c.name}=${c.value}`)
+          .join('; ');
+        await authManager.store(domain, {
+          type: 'cookie',
+          header: 'cookie',
+          value: cookieHeader,
+        });
+      }
+    }
+
+    return {
+      success: true,
+      cookieCount: cookies.length,
+      authDetected,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      cookieCount: 0,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    await browser.close();
+  }
+}

package/src/auth/manager.ts

@@ -0,0 +1,140 @@
+// src/auth/manager.ts
+import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { encrypt, decrypt, deriveKey, type EncryptedData } from './crypto.js';
+import type { StoredAuth, StoredToken, StoredSession } from '../types.js';
+
+const AUTH_FILENAME = 'auth.enc';
+
+/**
+ * Manages encrypted auth credential storage.
+ * All credentials stored in a single encrypted file keyed by domain.
+ */
+export class AuthManager {
+  private key: Buffer;
+  private authPath: string;
+
+  constructor(baseDir: string, machineId: string) {
+    this.key = deriveKey(machineId);
+    this.authPath = join(baseDir, AUTH_FILENAME);
+  }
+
+  /** Store auth credentials for a domain (overwrites existing). */
+  async store(domain: string, auth: StoredAuth): Promise<void> {
+    const allAuth = await this.loadAll();
+    allAuth[domain] = auth;
+    await this.saveAll(allAuth);
+  }
+
+  /** Retrieve auth credentials for a domain. Returns null if not found or decryption fails. */
+  async retrieve(domain: string): Promise<StoredAuth | null> {
+    const allAuth = await this.loadAll();
+    return allAuth[domain] ?? null;
+  }
+
+  /** Check if auth exists for a domain without loading the value. */
+  async has(domain: string): Promise<boolean> {
+    const allAuth = await this.loadAll();
+    return domain in allAuth;
+  }
+
+  /** Store refreshable tokens for a domain (merges with existing auth). */
+  async storeTokens(domain: string, tokens: Record<string, StoredToken>): Promise<void> {
+    const all = await this.loadAll();
+    const existing = all[domain] || { type: 'custom' as const, header: '', value: '' };
+    all[domain] = { ...existing, tokens };
+    await this.saveAll(all);
+  }
+
+  /** Retrieve refreshable tokens for a domain. */
+  async retrieveTokens(domain: string): Promise<Record<string, StoredToken> | null> {
+    const all = await this.loadAll();
+    return all[domain]?.tokens ?? null;
+  }
+
+  /** Store browser session (cookies) for a domain (merges with existing auth). */
+  async storeSession(domain: string, session: StoredSession): Promise<void> {
+    const all = await this.loadAll();
+    const existing = all[domain] || { type: 'custom' as const, header: '', value: '' };
+    all[domain] = { ...existing, session };
+    await this.saveAll(all);
+  }
+
+  /** Retrieve browser session for a domain. */
+  async retrieveSession(domain: string): Promise<StoredSession | null> {
+    const all = await this.loadAll();
+    return all[domain]?.session ?? null;
+  }
+
+  /** Store OAuth credentials for a domain (merges with existing auth). */
+  async storeOAuthCredentials(domain: string, creds: { refreshToken?: string; clientSecret?: string }): Promise<void> {
+    const all = await this.loadAll();
+    const existing = all[domain] || { type: 'custom' as const, header: '', value: '' };
+    if (creds.refreshToken !== undefined) existing.refreshToken = creds.refreshToken;
+    if (creds.clientSecret !== undefined) existing.clientSecret = creds.clientSecret;
+    all[domain] = existing;
+    await this.saveAll(all);
+  }
+
+  /** Retrieve OAuth credentials for a domain. */
+  async retrieveOAuthCredentials(domain: string): Promise<{ refreshToken?: string; clientSecret?: string } | null> {
+    const all = await this.loadAll();
+    const auth = all[domain];
+    if (!auth) return null;
+    if (!auth.refreshToken && !auth.clientSecret) return null;
+    return { refreshToken: auth.refreshToken, clientSecret: auth.clientSecret };
+  }
+
+  /** List all domains with stored auth. */
+  async listDomains(): Promise<string[]> {
+    const all = await this.loadAll();
+    return Object.keys(all);
+  }
+
+  /** Clear all auth for a domain. */
+  async clear(domain: string): Promise<void> {
+    const all = await this.loadAll();
+    delete all[domain];
+    await this.saveAll(all);
+  }
+
+  private async loadAll(): Promise<Record<string, StoredAuth>> {
+    try {
+      const content = await readFile(this.authPath, 'utf-8');
+      const encrypted: EncryptedData = JSON.parse(content);
+      const plaintext = decrypt(encrypted, this.key);
+      return JSON.parse(plaintext);
+    } catch {
+      return {};
+    }
+  }
+
+  private async saveAll(data: Record<string, StoredAuth>): Promise<void> {
+    const dir = join(this.authPath, '..');
+    await mkdir(dir, { recursive: true });
+
+    const plaintext = JSON.stringify(data);
+    const encrypted = encrypt(plaintext, this.key);
+
+    await writeFile(this.authPath, JSON.stringify(encrypted, null, 2) + '\n', { mode: 0o600 });
+    // Ensure permissions even if file existed with different perms
+    await chmod(this.authPath, 0o600);
+  }
+}
+
+/**
+ * Get the machine ID for key derivation.
+ * Linux: /etc/machine-id
+ * Fallback: hostname + homedir (less secure but portable)
+ */
+export async function getMachineId(): Promise<string> {
+  try {
+    const id = await readFile('/etc/machine-id', 'utf-8');
+    return id.trim();
+  } catch {
+    // Fallback for non-Linux systems
+    const { hostname } = await import('node:os');
+    const { homedir } = await import('node:os');
+    return `${hostname()}-${homedir()}`;
+  }
+}

package/src/auth/oauth-refresh.ts

@@ -0,0 +1,120 @@
+// src/auth/oauth-refresh.ts
+import type { OAuthConfig } from '../types.js';
+import type { AuthManager } from './manager.js';
+import { resolveAndValidateUrl } from '../skill/ssrf.js';
+
+export interface OAuthRefreshResult {
+  success: boolean;
+  accessToken?: string;
+  tokenRotated?: boolean;
+  error?: string;
+}
+
+/**
+ * Refresh an OAuth2 access token via the token endpoint using stdlib fetch().
+ * Supports refresh_token and client_credentials grant types.
+ * Handles refresh token rotation (new refresh_token in response).
+ */
+export async function refreshOAuth(
+  domain: string,
+  oauthConfig: OAuthConfig,
+  authManager: AuthManager,
+  options?: { _skipSsrfCheck?: boolean },
+): Promise<OAuthRefreshResult> {
+  const oauthCreds = await authManager.retrieveOAuthCredentials(domain);
+
+  // Build request body based on grant type
+  const body = new URLSearchParams();
+  body.append('grant_type', oauthConfig.grantType);
+  body.append('client_id', oauthConfig.clientId);
+
+  if (oauthConfig.scope) {
+    body.append('scope', oauthConfig.scope);
+  }
+
+  if (oauthConfig.grantType === 'refresh_token') {
+    if (!oauthCreds?.refreshToken) {
+      return { success: false, error: 'No refresh token available' };
+    }
+    body.append('refresh_token', oauthCreds.refreshToken);
+  }
+
+  if (oauthCreds?.clientSecret) {
+    body.append('client_secret', oauthCreds.clientSecret);
+  }
+
+  // SSRF check on token endpoint
+  if (!options?._skipSsrfCheck) {
+    const ssrfCheck = await resolveAndValidateUrl(oauthConfig.tokenEndpoint);
+    if (!ssrfCheck.safe) {
+      return { success: false, error: `Token endpoint blocked: ${ssrfCheck.reason}` };
+    }
+  }
+
+  // Domain match: token endpoint must match skill domain or be a known OAuth provider
+  const KNOWN_OAUTH_HOSTS = [
+    'oauth2.googleapis.com', 'accounts.google.com',
+    'login.microsoftonline.com', 'github.com',
+    'oauth.reddit.com', 'api.twitter.com',
+  ];
+  const tokenHost = new URL(oauthConfig.tokenEndpoint).hostname;
+  if (tokenHost !== domain && !tokenHost.endsWith('.' + domain) && !KNOWN_OAUTH_HOSTS.includes(tokenHost)) {
+    return { success: false, error: `Token endpoint domain mismatch: ${tokenHost} vs ${domain}` };
+  }
+
+  try {
+    const response = await fetch(oauthConfig.tokenEndpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+      signal: AbortSignal.timeout(15_000),  // 15s timeout for token refresh
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => '');
+      return {
+        success: false,
+        error: `Token endpoint returned ${response.status}: ${errorText}`.trim(),
+      };
+    }
+
+    const data = await response.json() as Record<string, unknown>;
+    const accessToken = data.access_token;
+
+    if (typeof accessToken !== 'string') {
+      return { success: false, error: 'No access_token in response' };
+    }
+
+    // Store new access token
+    const existingAuth = await authManager.retrieve(domain);
+    await authManager.store(domain, {
+      type: existingAuth?.type ?? 'bearer',
+      header: existingAuth?.header ?? 'authorization',
+      value: `Bearer ${accessToken}`,
+      tokens: existingAuth?.tokens,
+      session: existingAuth?.session,
+      refreshToken: existingAuth?.refreshToken,
+      clientSecret: existingAuth?.clientSecret,
+    });
+
+    // Handle refresh token rotation
+    let tokenRotated = false;
+    const newRefreshToken = data.refresh_token;
+    if (
+      typeof newRefreshToken === 'string' &&
+      newRefreshToken !== oauthCreds?.refreshToken
+    ) {
+      await authManager.storeOAuthCredentials(domain, {
+        refreshToken: newRefreshToken,
+      });
+      tokenRotated = true;
+    }
+
+    return { success: true, accessToken, tokenRotated };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}