@scrylog/cli 0.3.0 → 0.3.1

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

@@ -1,808 +0,0 @@
-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;
-}
-
-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) {
-    if (!entry.macOSPath) return "";
-    return join(home, "Library", "Application Support", entry.macOSPath);
-  }
-  if (IS_WINDOWS) {
-    const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
-    if (!entry.windowsPath) return "";
-    return join(appData, entry.windowsPath);
-  }
-  // Linux
-  if (!entry.linuxPath) return "";
-  return join(home, ".config", entry.linuxPath);
-}
-
-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());
-}
-
-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 = 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;
-  }
-}
-
-/**
- * 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") {
-    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(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);
-    }
-    return decrypted;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * 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;
-
-  // 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 });
-      const stmt = db.query("SELECT name, value, host, expiry FROM moz_cookies WHERE host LIKE ?");
-      const rows = stmt.all(`%${domain}`) as Array<{
-        name: string;
-        value: string;
-        host: string;
-        expiry: number;
-      }>;
-      const cookies: BrowserCookie[] = [];
-      for (const row of rows) {
-        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 locked or corrupt DB
-    } finally {
-      db?.close();
-    }
-  }
-
-  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;
-  if (!existsSync(SAFARI_COOKIE_PATH)) return cookies;
-
-  try {
-    const data = readFileSync(SAFARI_COOKIE_PATH);
-    // Simple binarycookies parser
-    // 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);
-    let offset = 8;
-    const pageSizes: number[] = [];
-    for (let i = 0; i < numPages; i++) {
-      pageSizes.push(data.readUInt32BE(offset));
-      offset += 4;
-    }
-
-    for (const pageSize of pageSizes) {
-      const pageEnd = offset + pageSize;
-      if (pageEnd > data.length) break;
-      // Page header: "page" + 4 bytes count
-      if (data.toString("ascii", offset, offset + 4) !== "page") {
-        offset += pageSize;
-        continue;
-      }
-      const numCookies = data.readUInt32BE(offset + 4);
-      let cookieOffset = offset + 8;
-      for (let i = 0; i < numCookies; i++) {
-        // Each cookie record: size (4) + unknown (4) + flags (4) + hasPort (4)
-        // + port (4) + urlOffset (4) + nameOffset (4) + pathOffset (4) + valueOffset (4)
-        // + tail (8) = 40 bytes header, then strings
-        const size = data.readUInt32BE(cookieOffset);
-        const urlOffset = data.readUInt32BE(cookieOffset + 20);
-        const nameOffset = data.readUInt32BE(cookieOffset + 24);
-        const pathOffset = data.readUInt32BE(cookieOffset + 28);
-        const valueOffset = data.readUInt32BE(cookieOffset + 32);
-
-        const url = data.toString("utf8", cookieOffset + urlOffset, cookieOffset + nameOffset - 1);
-        const name = data.toString("utf8", cookieOffset + nameOffset, cookieOffset + pathOffset - 1);
-        const value = data.toString("utf8", cookieOffset + valueOffset, cookieOffset + size);
-
-        if (cookieDomainMatches(url, domain)) {
-          cookies.push({ name, value });
-        }
-
-        cookieOffset += size;
-        if (cookieOffset > pageEnd) break;
-      }
-      offset += pageSize;
-    }
-  } catch {
-    // Ignore errors
-  }
-
-  return cookies;
-}
-
-// ---------------------------------------------------------------------------
-// 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("; ");
-}