browser-commander 0.15.0 → 0.16.1

package/src/browser/browser-cookie-database.js

@@ -0,0 +1,35 @@
+import BetterSqlite3 from 'better-sqlite3';
+
+let builtInSqlitePromise;
+
+function loadBuiltInSqlite() {
+  builtInSqlitePromise ??= import('node:sqlite')
+    .then(({ DatabaseSync }) => DatabaseSync)
+    .catch(() => null);
+  return builtInSqlitePromise;
+}
+
+/** Open SQLite without requiring a native addon on Node versions that provide it. */
+export async function openSqliteDatabase(
+  filename,
+  { fileMustExist = false, readOnly = false } = {}
+) {
+  const DatabaseSync = await loadBuiltInSqlite();
+  if (DatabaseSync) {
+    return new DatabaseSync(filename, { readOnly });
+  }
+  return new BetterSqlite3(filename, {
+    fileMustExist,
+    readonly: readOnly,
+  });
+}
+
+/** Configure a statement to preserve Chromium's 64-bit timestamp values. */
+export function preserveIntegerPrecision(statement) {
+  if (typeof statement.setReadBigInts === 'function') {
+    statement.setReadBigInts(true);
+  } else {
+    statement.safeIntegers();
+  }
+  return statement;
+}

package/src/browser/browser-cookies.js

@@ -0,0 +1,343 @@
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  clearBrowserCookieMemoryCache,
+  getCachedCredential,
+  normalizeCookieCache,
+  readCookieResultCache,
+  writeCookieResultCache,
+} from './browser-cookie-cache.js';
+import {
+  chromiumSameSite,
+  decodeChromiumCookiePlaintext,
+  decryptChromiumCookie,
+  deriveChromiumCookieKey,
+  firefoxSameSite,
+} from './browser-cookie-crypto.js';
+import {
+  decryptWindowsDpapi,
+  readSafeStoragePassword,
+  readWindowsEncryptionKey,
+} from './browser-cookie-credentials.js';
+import {
+  openSqliteDatabase,
+  preserveIntegerPrecision,
+} from './browser-cookie-database.js';
+import {
+  findCookieDatabase,
+  listBrowserProfiles,
+  normalizeCookieBrowser,
+  resolveBrowserProfile,
+} from './browser-profiles.js';
+
+const CHROME_EPOCH_OFFSET_SECONDS = 11_644_473_600n;
+const MICROSECONDS_PER_SECOND = 1_000_000n;
+
+function toNumber(value) {
+  return typeof value === 'bigint' ? Number(value) : Number(value ?? 0);
+}
+
+function chromiumExpires(value) {
+  const microseconds = BigInt(value ?? 0);
+  if (microseconds === 0n) {
+    return -1;
+  }
+  return Number(
+    microseconds / MICROSECONDS_PER_SECOND - CHROME_EPOCH_OFFSET_SECONDS
+  );
+}
+
+function firefoxExpires(value) {
+  const expires = toNumber(value);
+  return expires > 0 ? expires : -1;
+}
+
+function queryRows(database, query, domainFilter) {
+  const statement = preserveIntegerPrecision(database.prepare(query));
+  return domainFilter ? statement.all(`%${domainFilter}%`) : statement.all();
+}
+
+function readDatabaseVersion(database) {
+  try {
+    const row = database
+      .prepare("SELECT value FROM meta WHERE key = 'version'")
+      .get();
+    return Number(row?.value ?? 0);
+  } catch {
+    return 0;
+  }
+}
+
+function readFirefoxRows(database, domainFilter) {
+  return queryRows(
+    database,
+    `SELECT name, value, host, path, expiry, isSecure, isHttpOnly, sameSite
+       FROM moz_cookies
+      ${domainFilter ? 'WHERE host LIKE ?' : ''}
+      ORDER BY host, name, path`,
+    domainFilter
+  );
+}
+
+function readChromiumRows(database, domainFilter) {
+  return queryRows(
+    database,
+    `SELECT host_key, name, value, encrypted_value, path, expires_utc,
+            is_secure, is_httponly, samesite
+       FROM cookies
+      ${domainFilter ? 'WHERE host_key LIKE ?' : ''}
+      ORDER BY host_key, name, path`,
+    domainFilter
+  );
+}
+
+function mapFirefoxRows(rows) {
+  return rows.map((row) => ({
+    name: row.name,
+    value: row.value,
+    domain: row.host,
+    path: row.path || '/',
+    expires: firefoxExpires(row.expiry),
+    httpOnly: Boolean(row.isHttpOnly),
+    secure: Boolean(row.isSecure),
+    sameSite: firefoxSameSite(row.sameSite),
+  }));
+}
+
+function encryptionPrefix(encryptedValue) {
+  return Buffer.from(encryptedValue).subarray(0, 3).toString('ascii');
+}
+
+function chromiumKeyForPrefix(context, prefix) {
+  if (context.platform === 'linux' && prefix === 'v10') {
+    return deriveChromiumCookieKey('peanuts', 'linux');
+  }
+  if (context.platform === 'linux' || context.platform === 'darwin') {
+    const identity = `${context.browser}:${context.platform}:safe-storage`;
+    if (!context.credentialKeys.has(identity)) {
+      context.credentialKeys.set(
+        identity,
+        getCachedCredential({
+          cache: context.cache,
+          identity,
+          refresh: context.refresh,
+          now: context.now,
+          metadata: {
+            browser: context.browser,
+            platform: context.platform,
+            source: 'safe-storage',
+          },
+          create: async () =>
+            deriveChromiumCookieKey(
+              await context.readSafeStoragePassword({
+                browser: context.browser,
+                platform: context.platform,
+                environment: context.environment,
+              }),
+              context.platform
+            ),
+        })
+      );
+    }
+    return context.credentialKeys.get(identity);
+  }
+  if (context.platform === 'win32') {
+    const identity = `${context.browser}:win32:legacy-aes-key`;
+    if (!context.credentialKeys.has(identity)) {
+      context.credentialKeys.set(
+        identity,
+        getCachedCredential({
+          cache: context.cache,
+          identity,
+          refresh: context.refresh,
+          now: context.now,
+          metadata: {
+            browser: context.browser,
+            platform: context.platform,
+            source: 'dpapi',
+          },
+          create: () =>
+            context.readWindowsEncryptionKey({
+              localStatePath: path.join(
+                path.dirname(context.profile.path),
+                'Local State'
+              ),
+              environment: context.environment,
+              decryptDpapi: context.decryptWindowsDpapi,
+            }),
+        })
+      );
+    }
+    return context.credentialKeys.get(identity);
+  }
+  throw new Error(
+    `Chromium cookie decryption is unsupported on ${context.platform}`
+  );
+}
+
+async function decryptChromiumRow(row, databaseVersion, context) {
+  if (row.value) {
+    return row.value;
+  }
+  const encryptedValue = Buffer.from(row.encrypted_value);
+  if (encryptedValue.length === 0) {
+    return '';
+  }
+  const prefix = encryptionPrefix(encryptedValue);
+  if (context.platform === 'win32' && prefix !== 'v10' && prefix !== 'v11') {
+    if (prefix === 'v20') {
+      return decryptChromiumCookie({
+        encryptedValue,
+        host: row.host_key,
+        databaseVersion,
+        platform: context.platform,
+        key: Buffer.alloc(32),
+      });
+    }
+    const plaintext = await context.decryptWindowsDpapi(encryptedValue, {
+      environment: context.environment,
+    });
+    return decodeChromiumCookiePlaintext({
+      plaintext,
+      host: row.host_key,
+      databaseVersion,
+    });
+  }
+  const key = await chromiumKeyForPrefix(context, prefix);
+  return decryptChromiumCookie({
+    encryptedValue,
+    host: row.host_key,
+    databaseVersion,
+    platform: context.platform,
+    key,
+  });
+}
+
+async function mapChromiumRows(rows, databaseVersion, context) {
+  const cookies = [];
+  for (const row of rows) {
+    try {
+      cookies.push({
+        name: row.name,
+        value: await decryptChromiumRow(row, databaseVersion, context),
+        domain: row.host_key,
+        path: row.path || '/',
+        expires: chromiumExpires(row.expires_utc),
+        httpOnly: Boolean(row.is_httponly),
+        secure: Boolean(row.is_secure),
+        sameSite: chromiumSameSite(row.samesite),
+      });
+    } catch (error) {
+      if (!context.ignoreDecryptionErrors) {
+        throw new Error(
+          `Could not decrypt cookie ${row.name} for ${row.host_key}: ${error.message}`
+        );
+      }
+    }
+  }
+  return cookies;
+}
+
+async function openCookieDatabase(cookiePath) {
+  try {
+    return await openSqliteDatabase(cookiePath, {
+      fileMustExist: true,
+      readOnly: true,
+    });
+  } catch (error) {
+    throw new Error(`Could not open browser cookie database: ${error.message}`);
+  }
+}
+
+/**
+ * Read cookies from an installed browser profile in Playwright/Puppeteer shape.
+ * Use dependency injection only for deterministic platform and credential tests.
+ */
+export async function readBrowserCookiesWithDependencies(
+  options,
+  dependencies = {}
+) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('readBrowserCookies requires an options object');
+  }
+  const browser = normalizeCookieBrowser(options.browser);
+  const platform = dependencies.platform ?? process.platform;
+  const homeDir = dependencies.homeDir ?? os.homedir();
+  const environment = dependencies.environment ?? process.env;
+  const profile = await resolveBrowserProfile({
+    browser,
+    profile: options.profile,
+    platform,
+    homeDir,
+    environment,
+  });
+  const cookiePath = await findCookieDatabase(browser, profile.path, platform);
+  if (!cookiePath) {
+    throw new Error(`No cookie database exists in ${profile.path}`);
+  }
+  const cache = normalizeCookieCache(
+    options.cache,
+    homeDir,
+    options.ttlMinutes
+  );
+  const identity = JSON.stringify({
+    browser,
+    profile: profile.path,
+    domainFilter: options.domainFilter ?? null,
+    ignoreDecryptionErrors: options.ignoreDecryptionErrors === true,
+  });
+  const now = dependencies.now ?? Date.now;
+  const cachedCookies = await readCookieResultCache({
+    cache,
+    identity,
+    refresh: options.refresh === true,
+    now,
+  });
+  if (cachedCookies) {
+    return cachedCookies;
+  }
+
+  const database = await openCookieDatabase(cookiePath);
+  let cookies;
+  try {
+    if (browser === 'firefox') {
+      cookies = mapFirefoxRows(readFirefoxRows(database, options.domainFilter));
+    } else {
+      const databaseVersion = readDatabaseVersion(database);
+      const rows = readChromiumRows(database, options.domainFilter);
+      cookies = await mapChromiumRows(rows, databaseVersion, {
+        browser,
+        cache,
+        credentialKeys: new Map(),
+        decryptWindowsDpapi:
+          dependencies.decryptWindowsDpapi ?? decryptWindowsDpapi,
+        environment,
+        ignoreDecryptionErrors: options.ignoreDecryptionErrors === true,
+        now,
+        platform,
+        profile,
+        readSafeStoragePassword:
+          dependencies.readSafeStoragePassword ?? readSafeStoragePassword,
+        readWindowsEncryptionKey:
+          dependencies.readWindowsEncryptionKey ?? readWindowsEncryptionKey,
+        refresh: options.refresh === true,
+      });
+    }
+  } finally {
+    database.close();
+  }
+  await writeCookieResultCache({ cache, identity, cookies, now });
+  return cookies;
+}
+
+/** Read cookies from an installed Chrome, Edge, Brave, Chromium, or Firefox. */
+export function readBrowserCookies(options) {
+  return readBrowserCookiesWithDependencies(options);
+}
+
+export {
+  clearBrowserCookieMemoryCache,
+  decryptChromiumCookie,
+  listBrowserProfiles,
+};

package/src/browser/browser-profiles.js

@@ -0,0 +1,280 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const SUPPORTED_COOKIE_BROWSERS = [
+  'chrome',
+  'edge',
+  'brave',
+  'chromium',
+  'firefox',
+];
+
+function platformPath(platform) {
+  return platform === 'win32' ? path.win32 : path;
+}
+
+export function normalizeCookieBrowser(browser) {
+  const normalized = browser === 'msedge' ? 'edge' : browser;
+  if (!SUPPORTED_COOKIE_BROWSERS.includes(normalized)) {
+    throw new Error(
+      `Unsupported browser: ${browser}. Expected one of ${SUPPORTED_COOKIE_BROWSERS.join(', ')}`
+    );
+  }
+  return normalized;
+}
+
+export function browserProfileRoot(
+  browser,
+  {
+    platform = process.platform,
+    homeDir = os.homedir(),
+    environment = process.env,
+  } = {}
+) {
+  const normalizedBrowser = normalizeCookieBrowser(browser);
+  const pathApi = platformPath(platform);
+  if (platform === 'darwin') {
+    const support = pathApi.join(homeDir, 'Library', 'Application Support');
+    const roots = {
+      brave: pathApi.join(support, 'BraveSoftware', 'Brave-Browser'),
+      chrome: pathApi.join(support, 'Google', 'Chrome'),
+      chromium: pathApi.join(support, 'Chromium'),
+      edge: pathApi.join(support, 'Microsoft Edge'),
+      firefox: pathApi.join(support, 'Firefox'),
+    };
+    return roots[normalizedBrowser];
+  }
+  if (platform === 'win32') {
+    const localAppData =
+      environment.LOCALAPPDATA ?? pathApi.join(homeDir, 'AppData', 'Local');
+    const roamingAppData =
+      environment.APPDATA ?? pathApi.join(homeDir, 'AppData', 'Roaming');
+    const roots = {
+      brave: pathApi.join(
+        localAppData,
+        'BraveSoftware',
+        'Brave-Browser',
+        'User Data'
+      ),
+      chrome: pathApi.join(localAppData, 'Google', 'Chrome', 'User Data'),
+      chromium: pathApi.join(localAppData, 'Chromium', 'User Data'),
+      edge: pathApi.join(localAppData, 'Microsoft', 'Edge', 'User Data'),
+      firefox: pathApi.join(roamingAppData, 'Mozilla', 'Firefox'),
+    };
+    return roots[normalizedBrowser];
+  }
+  const roots = {
+    brave: pathApi.join(homeDir, '.config', 'BraveSoftware', 'Brave-Browser'),
+    chrome: pathApi.join(homeDir, '.config', 'google-chrome'),
+    chromium: pathApi.join(homeDir, '.config', 'chromium'),
+    edge: pathApi.join(homeDir, '.config', 'microsoft-edge'),
+    firefox: pathApi.join(homeDir, '.mozilla', 'firefox'),
+  };
+  return roots[normalizedBrowser];
+}
+
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function chromiumCookiePaths(profilePath, pathApi = path) {
+  return [
+    pathApi.join(profilePath, 'Network', 'Cookies'),
+    pathApi.join(profilePath, 'Cookies'),
+  ];
+}
+
+export async function findCookieDatabase(browser, profilePath, platform) {
+  const pathApi = platformPath(platform ?? process.platform);
+  if (normalizeCookieBrowser(browser) === 'firefox') {
+    const candidate = pathApi.join(profilePath, 'cookies.sqlite');
+    return (await pathExists(candidate)) ? candidate : null;
+  }
+  for (const candidate of chromiumCookiePaths(profilePath, pathApi)) {
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function listChromiumProfiles(browser, root, platform) {
+  if (!(await pathExists(root))) {
+    return [];
+  }
+  const pathApi = platformPath(platform);
+  const localState = await readJson(pathApi.join(root, 'Local State'));
+  const infoCache = localState.profile?.info_cache ?? {};
+  const names = new Set(Object.keys(infoCache));
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+      if (
+        entry.isDirectory() &&
+        (entry.name === 'Default' || entry.name.startsWith('Profile '))
+      ) {
+        names.add(entry.name);
+      }
+    }
+  } catch {
+    return [];
+  }
+
+  const profiles = [];
+  for (const name of names) {
+    const profilePath = pathApi.join(root, name);
+    if (!(await findCookieDatabase(browser, profilePath, platform))) {
+      continue;
+    }
+    profiles.push({
+      browser,
+      name,
+      displayName: infoCache[name]?.name ?? name,
+      path: profilePath,
+      isDefault:
+        name === (localState.profile?.last_used ?? 'Default') ||
+        (names.size === 1 && name === 'Default'),
+    });
+  }
+  return profiles.sort(
+    (left, right) =>
+      Number(right.isDefault) - Number(left.isDefault) ||
+      left.name.localeCompare(right.name)
+  );
+}
+
+function parseIni(text) {
+  const sections = [];
+  let current;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const sectionMatch = /^\[([^\]]+)]$/.exec(line);
+    if (sectionMatch) {
+      current = { section: sectionMatch[1] };
+      sections.push(current);
+      continue;
+    }
+    const separator = line.indexOf('=');
+    if (current && separator > 0 && !line.startsWith(';')) {
+      current[line.slice(0, separator)] = line.slice(separator + 1);
+    }
+  }
+  return sections;
+}
+
+async function listFirefoxProfiles(root, platform) {
+  if (!(await pathExists(root))) {
+    return [];
+  }
+  const pathApi = platformPath(platform);
+  let sections = [];
+  try {
+    sections = parseIni(
+      await readFile(pathApi.join(root, 'profiles.ini'), 'utf8')
+    );
+  } catch {
+    const profilesRoot = pathApi.join(root, 'Profiles');
+    try {
+      const entries = await readdir(profilesRoot, { withFileTypes: true });
+      sections = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({
+          section: 'Profile',
+          Name: entry.name,
+          Path: entry.name,
+          ProfilesRoot: profilesRoot,
+        }));
+    } catch {
+      return [];
+    }
+  }
+
+  const profiles = [];
+  for (const section of sections.filter(({ section }) =>
+    section.startsWith('Profile')
+  )) {
+    if (!section.Path) {
+      continue;
+    }
+    const relativeRoot = section.ProfilesRoot ?? root;
+    const profilePath =
+      section.IsRelative === '0'
+        ? section.Path
+        : pathApi.resolve(relativeRoot, section.Path);
+    if (!(await findCookieDatabase('firefox', profilePath, platform))) {
+      continue;
+    }
+    const displayName = section.Name ?? pathApi.basename(profilePath);
+    profiles.push({
+      browser: 'firefox',
+      name: displayName,
+      displayName,
+      path: profilePath,
+      isDefault: section.Default === '1',
+    });
+  }
+  return profiles.sort(
+    (left, right) =>
+      Number(right.isDefault) - Number(left.isDefault) ||
+      left.name.localeCompare(right.name)
+  );
+}
+
+/** Discover cookie-bearing profiles from installed browsers. */
+export async function listBrowserProfiles({
+  browser,
+  platform = process.platform,
+  homeDir = os.homedir(),
+  environment = process.env,
+} = {}) {
+  const browsers = browser
+    ? [normalizeCookieBrowser(browser)]
+    : SUPPORTED_COOKIE_BROWSERS;
+  const profiles = [];
+  for (const candidate of browsers) {
+    const root = browserProfileRoot(candidate, {
+      platform,
+      homeDir,
+      environment,
+    });
+    profiles.push(
+      ...(candidate === 'firefox'
+        ? await listFirefoxProfiles(root, platform)
+        : await listChromiumProfiles(candidate, root, platform))
+    );
+  }
+  return profiles;
+}
+
+export async function resolveBrowserProfile(options) {
+  const browser = normalizeCookieBrowser(options.browser);
+  const profiles = await listBrowserProfiles({ ...options, browser });
+  const requested = options.profile;
+  const selected = requested
+    ? profiles.find(
+        ({ name, displayName, path: profilePath }) =>
+          requested === name ||
+          requested === displayName ||
+          requested === platformPath(options.platform).basename(profilePath)
+      )
+    : (profiles.find(({ isDefault }) => isDefault) ?? profiles[0]);
+  if (!selected) {
+    const detail = requested ? ` profile "${requested}"` : ' profile';
+    throw new Error(`Could not find a cookie database for ${browser}${detail}`);
+  }
+  return selected;
+}

package/src/exports.js

@@ -43,6 +43,10 @@ export {
 
 // Re-export browser management
 export { connectBrowser } from './browser/connector.js';
+export {
+  listBrowserProfiles,
+  readBrowserCookies,
+} from './browser/browser-cookies.js';
 export {
   launchAndConnectRealBrowser,
   launchRealBrowser,

package/tests/fixtures/browser-cookie-cache-worker.mjs

@@ -0,0 +1,21 @@
+import { appendFile } from 'node:fs/promises';
+
+import { getCachedCredential } from '../../src/browser/browser-cookie-cache.js';
+
+const [, , cacheDir, credentialReads] = process.argv;
+
+await getCachedCredential({
+  cache: { enabled: true, dir: cacheDir, ttlSeconds: 60 },
+  identity: 'chrome:linux:safe-storage',
+  refresh: false,
+  metadata: {
+    browser: 'chrome',
+    platform: 'linux',
+    source: 'safe-storage',
+  },
+  create: async () => {
+    await appendFile(credentialReads, `${process.pid}\n`, 'utf8');
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    return Buffer.alloc(16, 7);
+  },
+});