@scrylog/cli 0.1.4 → 0.3.0

package/src/usage/resolvers/browser-cookies.ts

@@ -1,131 +1,536 @@
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { createDecipheriv, pbkdf2Sync } from "node:crypto";
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
 import { IS_MAC, IS_WINDOWS } from "../../shared/platform";
+import { keychainCoordinator, type KeychainCoordinator } from "./keychain-coordinator";
 
 export interface BrowserCookie {
   name: string;
   value: string;
 }
 
-const CHROME_COOKIE_PATHS = ((): string[] => {
+export interface BrowserCookieCandidate {
+  browser: string;
+  profile: string;
+  database: string;
+  cookies: BrowserCookie[];
+}
+
+// ---------------------------------------------------------------------------
+// Browser catalog types
+// ---------------------------------------------------------------------------
+
+export interface ChromiumProfileEntry {
+  /** Unique browser ID, e.g. "chrome", "brave", "claude-desktop" */
+  id: string;
+  /** Relative path under ~/Library/Application Support/ on macOS */
+  macOSPath: string;
+  /** Relative path under ~/.config/ on Linux */
+  linuxPath: string;
+  /** Relative path under %APPDATA%/ on Windows */
+  windowsPath: string;
+  /** macOS Keychain service label, e.g. "Chrome Safe Storage" */
+  keychainService?: string;
+  /** macOS Keychain account label, e.g. "Chrome" */
+  keychainAccount?: string;
+  /**
+   * Top-level cookie database file (relative to the resolved platform root)
+   * attempted when the root has no profile subdirectories. Claude Desktop
+   * keeps its Chromium cookie database at the application support root.
+   */
+  rootCookiePath?: string;
+  /**
+   * Apply the Chrome v24+ 32-byte domain-hash strip even when the database
+   * lacks version metadata. Required for the Claude Desktop database, whose
+   * decrypted values carry the strip but report no meta version.
+   */
+  forceDomainHashStrip?: boolean;
+}
+
+export interface GeckoProfileEntry {
+  /** Unique browser ID, e.g. "firefox", "zen" */
+  id: string;
+  /**
+   * Profiles parent folder name.
+   * macOS: ~/Library/Application Support/<profilesFolder>/Profiles
+   * Linux: ~/.mozilla/<profilesFolder>/Profiles
+   */
+  profilesFolder: string;
+}
+
+// ---------------------------------------------------------------------------
+// Browser catalogs
+// ---------------------------------------------------------------------------
+
+export const CHROMIUM_PROFILES: ChromiumProfileEntry[] = [
+  {
+    id: "chrome",
+    macOSPath: "Google/Chrome",
+    linuxPath: "google-chrome",
+    windowsPath: "Google/Chrome/User Data",
+    keychainService: "Chrome Safe Storage",
+    keychainAccount: "Chrome",
+  },
+  {
+    id: "edge",
+    macOSPath: "Microsoft Edge",
+    linuxPath: "microsoft-edge",
+    windowsPath: "Microsoft/Edge/User Data",
+    keychainService: "Microsoft Edge Safe Storage",
+    keychainAccount: "Microsoft Edge",
+  },
+  {
+    id: "brave",
+    macOSPath: "BraveSoftware/Brave-Browser",
+    linuxPath: "BraveSoftware/Brave-Browser",
+    windowsPath: "BraveSoftware/Brave-Browser/User Data",
+    keychainService: "Brave Safe Storage",
+    keychainAccount: "Brave",
+  },
+  {
+    id: "arc",
+    macOSPath: "Arc/User Data",
+    linuxPath: "Arc",
+    windowsPath: "Arc/User Data",
+    keychainService: "Arc Safe Storage",
+    keychainAccount: "Arc",
+  },
+  {
+    id: "vivaldi",
+    macOSPath: "Vivaldi",
+    linuxPath: "vivaldi",
+    windowsPath: "Vivaldi/User Data",
+    keychainService: "Vivaldi Safe Storage",
+    keychainAccount: "Vivaldi",
+  },
+  {
+    id: "chromium",
+    macOSPath: "Chromium",
+    linuxPath: "chromium",
+    windowsPath: "Chromium/User Data",
+    keychainService: "Chromium Safe Storage",
+    keychainAccount: "Chromium",
+  },
+  {
+    id: "yandex",
+    macOSPath: "Yandex/YandexBrowser",
+    linuxPath: "yandex-browser",
+    windowsPath: "Yandex/YandexBrowser/User Data",
+    keychainService: "Yandex Safe Storage",
+    keychainAccount: "Yandex",
+  },
+  {
+    // Claude Desktop app (Electron/Chromium) — macOS and Windows only.
+    // Keeps its Chromium cookie database at the application support root with
+    // no profile subdirectories; its encrypted values carry the Chrome v24+
+    // 32-byte domain-hash prefix despite reporting no meta version.
+    id: "claude-desktop",
+    macOSPath: "Claude",
+    linuxPath: "", // not available on Linux
+    windowsPath: "Anthropic/Claude",
+    keychainService: "Claude Safe Storage",
+    keychainAccount: "Claude",
+    rootCookiePath: "Cookies",
+    forceDomainHashStrip: true,
+  },
+];
+
+export const GECKO_PROFILES: GeckoProfileEntry[] = [
+  { id: "firefox", profilesFolder: "Firefox" },
+  { id: "zen", profilesFolder: "zen" },
+];
+
+const SAFARI_COOKIE_PATH = join(homedir(), "Library", "Cookies", "Cookies.binarycookies");
+
+// ---------------------------------------------------------------------------
+// Platform root resolution
+// ---------------------------------------------------------------------------
+
+function chromiumRootPath(entry: ChromiumProfileEntry): string {
   const home = homedir();
   if (IS_MAC) {
-    return [
-      join(home, "Library", "Application Support", "Google", "Chrome", "Default", "Cookies"),
-      join(home, "Library", "Application Support", "Google", "Chrome", "Profile 1", "Cookies"),
-    ];
+    if (!entry.macOSPath) return "";
+    return join(home, "Library", "Application Support", entry.macOSPath);
   }
   if (IS_WINDOWS) {
-    return [
-      join(home, "AppData", "Local", "Google", "Chrome", "User Data", "Default", "Cookies"),
-    ];
+    const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
+    if (!entry.windowsPath) return "";
+    return join(appData, entry.windowsPath);
   }
-  // Linux / WSL
-  return [
-    join(home, ".config", "google-chrome", "Default", "Cookies"),
-    join(home, ".config", "chromium", "Default", "Cookies"),
-  ];
-})();
+  // Linux
+  if (!entry.linuxPath) return "";
+  return join(home, ".config", entry.linuxPath);
+}
 
-const SAFARI_COOKIE_PATH = join(homedir(), "Library", "Cookies", "Cookies.binarycookies");
+function geckoProfilesRoot(entry: GeckoProfileEntry): string {
+  const home = homedir();
+  if (IS_MAC) {
+    return join(home, "Library", "Application Support", entry.profilesFolder, "Profiles");
+  }
+  if (IS_WINDOWS) {
+    // Firefox on Windows is not in scope; skip
+    return "";
+  }
+  // Linux
+  if (entry.id === "firefox") return join(home, ".mozilla", "firefox");
+  if (entry.id === "zen") return join(home, ".zen");
+  return join(home, ".mozilla", entry.profilesFolder.toLowerCase());
+}
 
-function getChromeSafeStorageKey(): Buffer | null {
+export function cookieDomainMatches(host: string, domain: string): boolean {
+  const normalizedHost = host.trim().toLowerCase().replace(/^\./, "");
+  const normalizedDomain = domain.trim().toLowerCase().replace(/^\./, "");
+  return normalizedHost === normalizedDomain || normalizedHost.endsWith(`.${normalizedDomain}`);
+}
+
+function cookieNameAllowed(name: string, allowedNames?: ReadonlySet<string>): boolean {
+  return !allowedNames || allowedNames.has(name);
+}
+
+// ---------------------------------------------------------------------------
+// Chromium helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Derives the Chromium AES-128-CBC key for a given Keychain service label.
+ * macOS: reads through the Keychain coordinator (async, single-flight, cooldown).
+ * Linux/Windows: uses the fixed "peanuts" PBKDF2 key (no Keychain).
+ */
+export async function getChromiumSafeStorageKey(
+  service: string,
+  account: string,
+  coordinator: KeychainCoordinator = keychainCoordinator,
+): Promise<Buffer | null> {
   try {
     if (IS_MAC) {
-      const password = execSync('security find-generic-password -s "Chrome Safe Storage" -w', {
-        encoding: "utf8",
-        stdio: ["pipe", "pipe", "pipe"],
-      }).trim();
+      const password = await coordinator.read(service, account);
       if (!password) return null;
       return pbkdf2Sync(password, "saltysalt", 1003, 16, "sha1");
     }
 
     if (IS_WINDOWS) {
+      // Chromium uses DPAPI on Windows; plaintext rows can still be imported.
       return null;
     }
+
+    // Linux
     return pbkdf2Sync("peanuts", "saltysalt", 1003, 16, "sha1");
   } catch {
     return null;
   }
 }
 
-function decryptChromeCookie(encrypted: Buffer, key: Buffer, dbVersion = 0): string | null {
-  if (encrypted.length < 3) return null;
-  // v10 or v11 prefix
-  const prefix = encrypted.slice(0, 3).toString("ascii");
+/**
+ * Returns all profile subdirectory paths under rootPath that match the
+ * Chromium naming conventions: Default, Profile *, user-*.
+ */
+export function discoverChromiumProfiles(rootPath: string): string[] {
+  if (!existsSync(rootPath)) return [];
+  let entries: string[];
+  try {
+    entries = readdirSync(rootPath, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((name) => name === "Default" || /^Profile \d+$/.test(name) || /^user-/.test(name))
+    .map((name) => join(rootPath, name));
+}
+
+/**
+ * Returns the two candidate cookie DB paths for a Chromium profile directory.
+ * The caller is responsible for checking existence before opening.
+ */
+export function chromiumCookieDbPaths(profilePath: string): string[] {
+  return [join(profilePath, "Cookies"), join(profilePath, "Network", "Cookies")];
+}
+
+/**
+ * Internal: decrypt AES-128-CBC safeStorage payload, returning raw bytes after
+ * PKCS#7 un-padding.  Returns `null` on decryption failure.  Callers that need
+ * the Chrome v24+ 32-byte domain-hash strip must apply it themselves.
+ */
+function decryptSafeStorageRaw(buf: Buffer, key: Buffer): Buffer | null {
+  if (buf.length < 3) return null;
+  const prefix = buf.slice(0, 3).toString("ascii");
   if (prefix !== "v10" && prefix !== "v11") {
-    // Possibly plain text (older Chrome versions)
-    return encrypted.toString("utf8");
+    return buf; // plain text (older versions)
   }
   const iv = Buffer.alloc(16, 32); // space character (0x20) repeated 16 times
   try {
     const decipher = createDecipheriv("aes-128-cbc", key, iv);
-    let decrypted = Buffer.concat([decipher.update(encrypted.slice(3)), decipher.final()]);
+    let decrypted = Buffer.concat([decipher.update(buf.slice(3)), decipher.final()]);
     // Remove PKCS#7 padding
     const padLen = decrypted[decrypted.length - 1];
     if (padLen > 0 && padLen <= 16) {
       decrypted = decrypted.slice(0, decrypted.length - padLen);
     }
-    // Chrome v24+ prepends a SHA256 hash of the domain (32 bytes) to encrypted values
-    if (dbVersion >= 24 && decrypted.length >= 32) {
-      decrypted = decrypted.slice(32);
-    }
-    return decrypted.toString("utf8");
+    return decrypted;
   } catch {
     return null;
   }
 }
 
-function readChromeCookies(domain: string): BrowserCookie[] {
-  const cookies: BrowserCookie[] = [];
-  const key = getChromeSafeStorageKey();
+/**
+ * Decrypt a Chromium/Electron safeStorage blob (AES-128-CBC, v10/v11 prefix)
+ * and return the result as a UTF-8 string.
+ *
+ * Used for Electron `safeStorage`-encrypted config fields (e.g. `oauth:tokenCache`
+ * in Claude Desktop's `config.json`).  Does **not** strip the Chrome v24+ 32-byte
+ * domain-hash prefix — use `decryptChromiumCookie` for cookie DB values.
+ */
+export function decryptSafeStorageBlob(buf: Buffer, key: Buffer): string | null {
+  const raw = decryptSafeStorageRaw(buf, key);
+  return raw !== null ? raw.toString("utf8") : null;
+}
+
+function decryptChromiumCookie(encrypted: Buffer, key: Buffer, dbVersion = 0): string | null {
+  const raw = decryptSafeStorageRaw(encrypted, key);
+  if (raw === null) return null;
+  // Chrome v24+ prepends a SHA256 hash of the domain (32 bytes) to encrypted cookie values
+  if (encrypted.length >= 3) {
+    const prefix = encrypted.slice(0, 3).toString("ascii");
+    if ((prefix === "v10" || prefix === "v11") && dbVersion >= 24 && raw.length >= 32) {
+      return raw.slice(32).toString("utf8");
+    }
+  }
+  return raw.toString("utf8");
+}
+
+export interface ChromiumCookieRows {
+  dbVersion: number;
+  plaintext: BrowserCookie[];
+  encrypted: Array<{ name: string; encrypted: Buffer }>;
+}
+
+/**
+ * Reads and filters target cookie rows from a Chromium database without any
+ * Safe Storage key request. Rows are partitioned into plaintext values and
+ * encrypted-only rows so callers can decide whether a key read is warranted.
+ */
+export function readChromiumCookieRows(
+  dbPath: string,
+  domain: string,
+  allowedNames?: ReadonlySet<string>,
+  options?: { forceDomainHashStrip?: boolean },
+): ChromiumCookieRows {
+  const rows: ChromiumCookieRows = { dbVersion: 0, plaintext: [], encrypted: [] };
+  let db: Database | undefined;
+  try {
+    db = new Database(dbPath, { readonly: true });
+
+    try {
+      const versionRow = db.query("SELECT value FROM meta WHERE key = 'version'").get() as {
+        value: number;
+      } | null;
+      if (versionRow) rows.dbVersion = Number(versionRow.value);
+    } catch {
+      // Older databases may not have a meta table.
+    }
+    if (options?.forceDomainHashStrip && rows.dbVersion < 24) {
+      rows.dbVersion = 24;
+    }
+
+    const columns = db.query("PRAGMA table_info(cookies)").all() as Array<{ name: string }>;
+    const hasPlaintextValue = columns.some((column) => column.name === "value");
+    const valueColumn = hasPlaintextValue ? "value" : "'' AS value";
+    const rawRows = db.query(
+      `SELECT name, encrypted_value, ${valueColumn}, host_key, expires_utc FROM cookies WHERE host_key LIKE ?`,
+    ).all(`%${domain}`) as Array<{
+      name: string;
+      encrypted_value: Uint8Array | null;
+      value: string | null;
+      host_key: string;
+      expires_utc: number;
+    }>;
+    // expires_utc is microseconds since the Chrome epoch (1601-01-01).
+    const now = (Date.now() / 1000 + 11644473600) * 1_000_000;
+
+    for (const row of rawRows) {
+      if (!cookieDomainMatches(row.host_key, domain) || !cookieNameAllowed(row.name, allowedNames)) {
+        continue;
+      }
+      const expiresUtc = Number(row.expires_utc);
+      if (expiresUtc > 0 && expiresUtc <= now) continue;
+
+      const plaintext = row.value || null;
+      if (plaintext !== null) {
+        rows.plaintext.push({ name: row.name, value: plaintext });
+        continue;
+      }
+      const encrypted = row.encrypted_value ? Buffer.from(row.encrypted_value) : null;
+      if (encrypted) rows.encrypted.push({ name: row.name, encrypted });
+    }
+  } catch {
+    // Ignore permission errors, locked DB (SQLITE_BUSY), and incompatible schemas.
+  } finally {
+    db?.close();
+  }
+  return rows;
+}
+
+function resolveChromiumCookies(rows: ChromiumCookieRows, key: Buffer | null): BrowserCookie[] {
+  const cookies = [...rows.plaintext];
   if (!key) return cookies;
+  for (const pending of rows.encrypted) {
+    const value = decryptChromiumCookie(pending.encrypted, key, rows.dbVersion);
+    if (value !== null) cookies.push({ name: pending.name, value });
+  }
+  return cookies;
+}
+
+export function readChromiumCookieDatabase(
+  dbPath: string,
+  domain: string,
+  key: Buffer | null,
+  allowedNames?: ReadonlySet<string>,
+): BrowserCookie[] {
+  return resolveChromiumCookies(readChromiumCookieRows(dbPath, domain, allowedNames), key);
+}
+
+/**
+ * Reads one Chromium profile database as an isolated candidate. A Safe Storage
+ * key is requested through the coordinator only when filtered rows contain an
+ * encrypted target cookie; plaintext rows and absent targets never trigger one.
+ */
+export async function readChromiumCookieCandidate(
+  profilePath: string,
+  dbPath: string,
+  entry: ChromiumProfileEntry,
+  domain: string,
+  allowedNames?: ReadonlySet<string>,
+  coordinator: KeychainCoordinator = keychainCoordinator,
+): Promise<BrowserCookieCandidate | null> {
+  const rows = readChromiumCookieRows(dbPath, domain, allowedNames, {
+    forceDomainHashStrip: entry.forceDomainHashStrip,
+  });
+  if (rows.plaintext.length === 0 && rows.encrypted.length === 0) return null;
+
+  let cookies = rows.plaintext;
+  if (rows.encrypted.length > 0) {
+    const key = await getChromiumSafeStorageKey(entry.keychainService ?? "", entry.keychainAccount ?? "", coordinator);
+    if (!key) {
+      return rows.plaintext.length > 0
+        ? { browser: entry.id, profile: profilePath, database: dbPath, cookies: rows.plaintext }
+        : null;
+    }
+    cookies = resolveChromiumCookies(rows, key);
+  }
+  if (cookies.length === 0) return null;
+  return { browser: entry.id, profile: profilePath, database: dbPath, cookies };
+}
+
+export async function readChromiumCookieCandidates(
+  entry: ChromiumProfileEntry,
+  domain: string,
+  allowedNames?: ReadonlySet<string>,
+  coordinator: KeychainCoordinator = keychainCoordinator,
+): Promise<BrowserCookieCandidate[]> {
+  const candidates: BrowserCookieCandidate[] = [];
+  const rootPath = chromiumRootPath(entry);
+  if (!rootPath || !existsSync(rootPath)) return candidates;
 
-  for (const dbPath of CHROME_COOKIE_PATHS) {
+  // No Safe Storage key is requested here: each profile database requests the
+  // key lazily through readChromiumCookieCandidate only when an encrypted
+  // target cookie survives filtering.
+  const profiles = discoverChromiumProfiles(rootPath);
+  for (const profilePath of profiles) {
+    for (const dbPath of chromiumCookieDbPaths(profilePath)) {
+      if (!existsSync(dbPath)) continue;
+      const candidate = await readChromiumCookieCandidate(profilePath, dbPath, entry, domain, allowedNames, coordinator);
+      if (candidate) candidates.push(candidate);
+    }
+  }
+  // Root-level cookie databases (Claude Desktop): attempt when the root holds
+  // no profile subdirectories.
+  if (profiles.length === 0 && entry.rootCookiePath) {
+    const rootDb = join(rootPath, entry.rootCookiePath);
+    if (existsSync(rootDb)) {
+      const candidate = await readChromiumCookieCandidate(rootPath, rootDb, entry, domain, allowedNames, coordinator);
+      if (candidate) candidates.push(candidate);
+    }
+  }
+
+  return candidates;
+}
+
+export async function readChromiumCookies(entry: ChromiumProfileEntry, domain: string): Promise<BrowserCookie[]> {
+  const candidates = await readChromiumCookieCandidates(entry, domain);
+  return candidates.flatMap((candidate) => candidate.cookies);
+}
+
+// ---------------------------------------------------------------------------
+// Gecko (Firefox/Zen) support
+// ---------------------------------------------------------------------------
+
+export function readGeckoCookieCandidates(
+  entry: GeckoProfileEntry,
+  domain: string,
+  allowedNames?: ReadonlySet<string>,
+): BrowserCookieCandidate[] {
+  const candidates: BrowserCookieCandidate[] = [];
+  const profilesRoot = geckoProfilesRoot(entry);
+  if (!profilesRoot || !existsSync(profilesRoot)) return candidates;
+
+  let profileNames: string[];
+  try {
+    profileNames = readdirSync(profilesRoot, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && d.name.includes(".default"))
+      .map((d) => d.name)
+      // Prefer .default-release over .default
+      .sort((a, b) => {
+        const aScore = a.endsWith(".default-release") ? 1 : 0;
+        const bScore = b.endsWith(".default-release") ? 1 : 0;
+        return bScore - aScore;
+      });
+  } catch {
+    return candidates;
+  }
+
+  for (const profileName of profileNames) {
+    const dbPath = join(profilesRoot, profileName, "cookies.sqlite");
     if (!existsSync(dbPath)) continue;
     let db: Database | undefined;
     try {
       db = new Database(dbPath, { readonly: true });
-
-      // Chrome v24+ prepends a SHA256 hash (32 bytes) to encrypted cookie values
-      let dbVersion = 0;
-      try {
-        const versionStmt = db.query("SELECT value FROM meta WHERE key = 'version'");
-        const versionRow = versionStmt.get() as { value: number } | null;
-        if (versionRow) dbVersion = Number(versionRow.value);
-      } catch {
-        // meta table may not exist in older DBs
-      }
-
-      const stmt = db.query(
-        "SELECT name, encrypted_value, host_key FROM cookies WHERE host_key LIKE ? AND expires_utc > ?"
-      );
-      const now = (Date.now() + 11644473600000) * 1000; // Chrome epoch offset
-      const rows = stmt.all(`%${domain}%`, now) as Array<{
+      const stmt = db.query("SELECT name, value, host, expiry FROM moz_cookies WHERE host LIKE ?");
+      const rows = stmt.all(`%${domain}`) as Array<{
         name: string;
-        encrypted_value: Uint8Array;
-        host_key: string;
+        value: string;
+        host: string;
+        expiry: number;
       }>;
+      const cookies: BrowserCookie[] = [];
       for (const row of rows) {
-        const value = decryptChromeCookie(Buffer.from(row.encrypted_value), key, dbVersion);
-        if (value !== null) {
-          cookies.push({ name: row.name, value });
-        }
+        if (!cookieDomainMatches(row.host, domain) || !cookieNameAllowed(row.name, allowedNames)) continue;
+        if (Number(row.expiry) > 0 && Number(row.expiry) <= Date.now() / 1000) continue;
+        cookies.push({ name: row.name, value: row.value });
+      }
+      if (cookies.length > 0) {
+        candidates.push({ browser: entry.id, profile: join(profilesRoot, profileName), database: dbPath, cookies });
       }
     } catch {
-      // Ignore permission errors or locked DB
+      // Ignore locked or corrupt DB
     } finally {
       db?.close();
     }
   }
 
-  return cookies;
+  return candidates;
+}
+
+export function readGeckoCookies(entry: GeckoProfileEntry, domain: string): BrowserCookie[] {
+  return readGeckoCookieCandidates(entry, domain).flatMap((candidate) => candidate.cookies);
 }
 
+// ---------------------------------------------------------------------------
+// Safari (macOS-only, unchanged)
+// ---------------------------------------------------------------------------
+
 function readSafariCookies(domain: string): BrowserCookie[] {
   const cookies: BrowserCookie[] = [];
   if (process.platform !== "darwin") return cookies;
@@ -134,7 +539,7 @@ function readSafariCookies(domain: string): BrowserCookie[] {
   try {
     const data = readFileSync(SAFARI_COOKIE_PATH);
     // Simple binarycookies parser
-    // Header: 4 bytes magic "cook", 4 bytes page size, then pages
+    // Header: 4 bytes magic "cook", 4 bytes page count, then pages
     if (data.length < 8 || data.toString("ascii", 0, 4) !== "cook") return cookies;
 
     const numPages = data.readUInt32BE(4);
@@ -169,7 +574,7 @@ function readSafariCookies(domain: string): BrowserCookie[] {
         const name = data.toString("utf8", cookieOffset + nameOffset, cookieOffset + pathOffset - 1);
         const value = data.toString("utf8", cookieOffset + valueOffset, cookieOffset + size);
 
-        if (url.includes(domain)) {
+        if (cookieDomainMatches(url, domain)) {
           cookies.push({ name, value });
         }
 
@@ -185,14 +590,219 @@ function readSafariCookies(domain: string): BrowserCookie[] {
   return cookies;
 }
 
-export function extractCookies(domain: string): BrowserCookie[] {
-  const chrome = readChromeCookies(domain);
-  if (chrome.length > 0) return chrome;
-  // Safari is only available on macOS.
-  if (IS_MAC) return readSafariCookies(domain);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract cookies for the given domain from all available browser sources.
+ * Sources are tried in an order that minimises Keychain prompts:
+ *   macOS:   Gecko (Firefox/Zen) → Safari → Chromium catalog
+ *   Linux:   Gecko → Chromium catalog
+ *   Windows: Gecko (limited) → Chromium catalog
+ *
+ * Returns the first source that yields ≥1 matching cookie; subsequent sources
+ * are skipped (first-source-wins).
+ */
+export async function extractCookies(domain: string): Promise<BrowserCookie[]> {
+  // 1. Gecko sources first — no Keychain prompt, cheap read
+  for (const entry of GECKO_PROFILES) {
+    const cookies = readGeckoCookies(entry, domain);
+    if (cookies.length > 0) return cookies;
+  }
+
+  // 2. Safari (macOS only) — no Keychain prompt
+  if (IS_MAC) {
+    const safari = readSafariCookies(domain);
+    if (safari.length > 0) return safari;
+  }
+
+  // 3. Chromium catalog — may trigger Keychain prompts on macOS
+  for (const entry of CHROMIUM_PROFILES) {
+    const cookies = await readChromiumCookies(entry, domain);
+    if (cookies.length > 0) return cookies;
+  }
+
   return [];
 }
 
+export interface BrowserCookieCursorOptions {
+  /** Browser catalog ids to exclude from Chromium scans (e.g. claude-desktop). */
+  excludeBrowsers?: ReadonlySet<string>;
+  /** Test seam: override the Safari cookie reader. */
+  safariReader?: (domain: string) => BrowserCookie[];
+  /** Test seam: override the Chromium root path resolution per browser id. */
+  chromiumRootResolver?: (entry: ChromiumProfileEntry) => string;
+  /** Test seam: use an isolated Keychain coordinator. */
+  coordinator?: KeychainCoordinator;
+  /**
+   * Catalog entry id attempted before Gecko (Claude Desktop for the claude.ai
+   * cursor). Other cursors leave this unset and keep the standard order.
+   */
+  preferredBrowserId?: string;
+}
+
+/**
+ * Demand-driven browser cookie candidate iterator. Each `next()` call inspects
+ * exactly one source (Gecko profile set, Safari, or one Chromium profile
+ * database) and never inspects later sources speculatively. A Safe Storage key
+ * is requested only when the inspected database holds an encrypted target
+ * cookie.
+ */
+export class BrowserCookieSourceCursor {
+  private readonly safariReader: (domain: string) => BrowserCookie[];
+  private readonly chromiumRootResolver: (entry: ChromiumProfileEntry) => string;
+  private readonly coordinator: KeychainCoordinator;
+  private readonly preferredEntry?: ChromiumProfileEntry;
+  private geckoIndex = 0;
+  private safariChecked = false;
+  private chromiumIndex = 0;
+  private preferredQueue: Array<{ entry: ChromiumProfileEntry; profilePath: string; dbPath?: string }> = [];
+  private preferredQueueBuilt = false;
+  private chromiumQueue: Array<{ entry: ChromiumProfileEntry; profilePath: string; dbPath?: string }> = [];
+
+  constructor(
+    private readonly domain: string,
+    private readonly allowedCookieNames?: readonly string[],
+    private readonly options: BrowserCookieCursorOptions = {},
+  ) {
+    this.safariReader = options.safariReader ?? readSafariCookies;
+    this.chromiumRootResolver = options.chromiumRootResolver ?? chromiumRootPath;
+    this.coordinator = options.coordinator ?? keychainCoordinator;
+    if (options.preferredBrowserId) {
+      this.preferredEntry = CHROMIUM_PROFILES.find((entry) => entry.id === options.preferredBrowserId);
+    }
+  }
+
+  private async pushPreferredSources(
+    entry: ChromiumProfileEntry,
+  ): Promise<void> {
+    const rootPath = this.chromiumRootResolver(entry);
+    if (!rootPath || !existsSync(rootPath)) return;
+    for (const profilePath of discoverChromiumProfiles(rootPath)) {
+      this.preferredQueue.push({ entry, profilePath });
+    }
+    if (this.preferredQueue.length === 0 && entry.rootCookiePath) {
+      const rootDb = join(rootPath, entry.rootCookiePath);
+      if (existsSync(rootDb)) {
+        this.preferredQueue.push({ entry, profilePath: rootPath, dbPath: rootDb });
+      }
+    }
+  }
+
+  private async nextPreferred(): Promise<BrowserCookieCandidate | null> {
+    if (!this.preferredEntry) return null;
+    if (!this.preferredQueueBuilt) {
+      this.preferredQueueBuilt = true;
+      await this.pushPreferredSources(this.preferredEntry);
+    }
+    while (this.preferredQueue.length > 0) {
+      const { entry, profilePath, dbPath } = this.preferredQueue.shift()!;
+      for (const path of dbPath ? [dbPath] : chromiumCookieDbPaths(profilePath)) {
+        if (!existsSync(path)) continue;
+        const candidate = await readChromiumCookieCandidate(
+          profilePath,
+          path,
+          entry,
+          this.domain,
+          this.allowedCookieNames ? new Set(this.allowedCookieNames) : undefined,
+          this.coordinator,
+        );
+        if (candidate) return candidate;
+      }
+    }
+    return null;
+  }
+
+  async next(): Promise<BrowserCookieCandidate | null> {
+    const allowedNames = this.allowedCookieNames ? new Set(this.allowedCookieNames) : undefined;
+
+    const preferred = await this.nextPreferred();
+    if (preferred) return preferred;
+
+    while (this.geckoIndex < GECKO_PROFILES.length) {
+      const entry = GECKO_PROFILES[this.geckoIndex++]!;
+      const candidates = readGeckoCookieCandidates(entry, this.domain, allowedNames);
+      if (candidates.length > 0) return candidates[0]!;
+    }
+
+    if (IS_MAC && !this.safariChecked) {
+      this.safariChecked = true;
+      const cookies = this.safariReader(this.domain).filter((cookie) => cookieNameAllowed(cookie.name, allowedNames));
+      if (cookies.length > 0) {
+        return { browser: "safari", profile: "default", database: SAFARI_COOKIE_PATH, cookies };
+      }
+    }
+
+    for (;;) {
+      if (this.chromiumQueue.length === 0) {
+        const entry = CHROMIUM_PROFILES[this.chromiumIndex++];
+        if (!entry) return null;
+        if (this.options.excludeBrowsers?.has(entry.id)) continue;
+        if (this.preferredEntry && entry.id === this.preferredEntry.id) continue;
+        const rootPath = this.chromiumRootResolver(entry);
+        if (!rootPath || !existsSync(rootPath)) continue;
+        for (const profilePath of discoverChromiumProfiles(rootPath)) {
+          this.chromiumQueue.push({ entry, profilePath });
+        }
+        // Root-level cookie databases (Claude Desktop): attempt when the root
+        // holds no profile subdirectories at all.
+        if (this.chromiumQueue.length === 0 && entry.rootCookiePath) {
+          const rootDb = join(rootPath, entry.rootCookiePath);
+          if (existsSync(rootDb)) {
+            this.chromiumQueue.push({ entry, profilePath: rootPath, dbPath: rootDb });
+          }
+        }
+        continue;
+      }
+      const { entry, profilePath, dbPath } = this.chromiumQueue.shift()!;
+      for (const path of dbPath ? [dbPath] : chromiumCookieDbPaths(profilePath)) {
+        if (!existsSync(path)) continue;
+        const candidate = await readChromiumCookieCandidate(
+          profilePath,
+          path,
+          entry,
+          this.domain,
+          allowedNames,
+          this.coordinator,
+        );
+        if (candidate) return candidate;
+      }
+    }
+  }
+}
+
+export async function extractCookieCandidates(
+  domain: string,
+  allowedCookieNames?: readonly string[],
+  options: BrowserCookieCursorOptions = {},
+): Promise<BrowserCookieCandidate[]> {
+  const cursor = new BrowserCookieSourceCursor(domain, allowedCookieNames, options);
+  const candidates: BrowserCookieCandidate[] = [];
+  for (let candidate = await cursor.next(); candidate !== null; candidate = await cursor.next()) {
+    candidates.push(candidate);
+  }
+  return candidates;
+}
+
+/**
+ * Cheap import-source existence check: no SQLite reads and no Keychain
+ * requests. Used by planning to decide whether a deferred browser import
+ * could yield candidates at all.
+ */
+export function hasBrowserCookieSources(): boolean {
+  for (const entry of GECKO_PROFILES) {
+    const root = geckoProfilesRoot(entry);
+    if (root && existsSync(root)) return true;
+  }
+  if (IS_MAC && existsSync(SAFARI_COOKIE_PATH)) return true;
+  for (const entry of CHROMIUM_PROFILES) {
+    const root = chromiumRootPath(entry);
+    if (root && existsSync(root)) return true;
+  }
+  return false;
+}
+
 export function buildCookieHeader(cookies: BrowserCookie[]): string {
   return cookies.map((c) => `${c.name}=${c.value}`).join("; ");
 }