@scrylog/cli 0.2.0 → 0.3.0

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

@@ -1,21 +1,28 @@
-import * as child_process from "node:child_process";
 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
 // ---------------------------------------------------------------------------
 
-interface ChromiumProfileEntry {
+export interface ChromiumProfileEntry {
   /** Unique browser ID, e.g. "chrome", "brave", "claude-desktop" */
   id: string;
   /** Relative path under ~/Library/Application Support/ on macOS */
@@ -28,9 +35,21 @@ interface ChromiumProfileEntry {
   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;
 }
 
-interface GeckoProfileEntry {
+export interface GeckoProfileEntry {
   /** Unique browser ID, e.g. "firefox", "zen" */
   id: string;
   /**
@@ -103,13 +122,18 @@ export const CHROMIUM_PROFILES: ChromiumProfileEntry[] = [
     keychainAccount: "Yandex",
   },
   {
-    // Claude Desktop app (Electron/Chromium) — macOS and Windows only
+    // 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,
   },
 ];
 
@@ -150,7 +174,19 @@ function geckoProfilesRoot(entry: GeckoProfileEntry): string {
     return "";
   }
   // Linux
-  return join(home, ".mozilla", entry.profilesFolder, "Profiles");
+  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);
 }
 
 // ---------------------------------------------------------------------------
@@ -159,23 +195,24 @@ function geckoProfilesRoot(entry: GeckoProfileEntry): string {
 
 /**
  * Derives the Chromium AES-128-CBC key for a given Keychain service label.
- * macOS: reads from Keychain via `security` then applies PBKDF2.
+ * macOS: reads through the Keychain coordinator (async, single-flight, cooldown).
  * Linux/Windows: uses the fixed "peanuts" PBKDF2 key (no Keychain).
  */
-export function getChromiumSafeStorageKey(service: string, _account: string): Buffer | null {
+export async function getChromiumSafeStorageKey(
+  service: string,
+  account: string,
+  coordinator: KeychainCoordinator = keychainCoordinator,
+): Promise<Buffer | null> {
   try {
     if (IS_MAC) {
-      const password = child_process.execSync(`security find-generic-password -s "${service}" -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) {
-      // DPAPI not implemented; fall back to peanuts key (partial compatibility)
-      return pbkdf2Sync("peanuts", "saltysalt", 1003, 16, "sha1");
+      // Chromium uses DPAPI on Windows; plaintext rows can still be imported.
+      return null;
     }
 
     // Linux
@@ -264,70 +301,180 @@ function decryptChromiumCookie(encrypted: Buffer, key: Buffer, dbVersion = 0): s
   return raw.toString("utf8");
 }
 
-export function readChromiumCookies(entry: ChromiumProfileEntry, domain: string): BrowserCookie[] {
-  const cookies: BrowserCookie[] = [];
-  const rootPath = chromiumRootPath(entry);
-  if (!rootPath || !existsSync(rootPath)) return cookies;
+export interface ChromiumCookieRows {
+  dbVersion: number;
+  plaintext: BrowserCookie[];
+  encrypted: Array<{ name: string; encrypted: Buffer }>;
+}
 
-  // Resolve decryption key only if we found a root (avoids Keychain prompts for absent browsers)
-  const key = getChromiumSafeStorageKey(
-    entry.keychainService ?? "",
-    entry.keychainAccount ?? ""
-  );
+/**
+ * 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;
-      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<{
-          name: string;
-          encrypted_value: Uint8Array;
-          host_key: string;
-        }>;
-        for (const row of rows) {
-          const value = decryptChromiumCookie(Buffer.from(row.encrypted_value), key, dbVersion);
-          if (value !== null) {
-            cookies.push({ name: row.name, value });
-          }
-        }
-      } catch {
-        // Ignore permission errors, locked DB (SQLITE_BUSY), etc.
-      } finally {
-        db?.close();
-      }
+      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 cookies;
+  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 readGeckoCookies(entry: GeckoProfileEntry, domain: string): BrowserCookie[] {
-  const cookies: BrowserCookie[] = [];
+export function readGeckoCookieCandidates(
+  entry: GeckoProfileEntry,
+  domain: string,
+  allowedNames?: ReadonlySet<string>,
+): BrowserCookieCandidate[] {
+  const candidates: BrowserCookieCandidate[] = [];
   const profilesRoot = geckoProfilesRoot(entry);
-  if (!profilesRoot || !existsSync(profilesRoot)) return cookies;
+  if (!profilesRoot || !existsSync(profilesRoot)) return candidates;
 
   let profileNames: string[];
   try {
@@ -341,7 +488,7 @@ export function readGeckoCookies(entry: GeckoProfileEntry, domain: string): Brow
         return bScore - aScore;
       });
   } catch {
-    return cookies;
+    return candidates;
   }
 
   for (const profileName of profileNames) {
@@ -350,12 +497,22 @@ export function readGeckoCookies(entry: GeckoProfileEntry, domain: string): Brow
     let db: Database | undefined;
     try {
       db = new Database(dbPath, { readonly: true });
-      const stmt = db.query("SELECT name, value FROM moz_cookies WHERE host LIKE ?");
-      const rows = stmt.all(`%${domain}%`) as Array<{ name: string; value: string }>;
+      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) break; // first-profile-wins within a browser
+      if (cookies.length > 0) {
+        candidates.push({ browser: entry.id, profile: join(profilesRoot, profileName), database: dbPath, cookies });
+      }
     } catch {
       // Ignore locked or corrupt DB
     } finally {
@@ -363,7 +520,11 @@ export function readGeckoCookies(entry: GeckoProfileEntry, domain: string): Brow
     }
   }
 
-  return cookies;
+  return candidates;
+}
+
+export function readGeckoCookies(entry: GeckoProfileEntry, domain: string): BrowserCookie[] {
+  return readGeckoCookieCandidates(entry, domain).flatMap((candidate) => candidate.cookies);
 }
 
 // ---------------------------------------------------------------------------
@@ -413,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 });
         }
 
@@ -435,7 +596,7 @@ function readSafariCookies(domain: string): BrowserCookie[] {
 
 /**
  * Extract cookies for the given domain from all available browser sources.
- * Sources are tried in order that minimises Keychain prompts:
+ * 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
@@ -443,7 +604,7 @@ function readSafariCookies(domain: string): BrowserCookie[] {
  * Returns the first source that yields ≥1 matching cookie; subsequent sources
  * are skipped (first-source-wins).
  */
-export function extractCookies(domain: string): BrowserCookie[] {
+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);
@@ -458,13 +619,190 @@ export function extractCookies(domain: string): BrowserCookie[] {
 
   // 3. Chromium catalog — may trigger Keychain prompts on macOS
   for (const entry of CHROMIUM_PROFILES) {
-    const cookies = readChromiumCookies(entry, domain);
+    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("; ");
 }