browser-commander 0.14.0 → 0.16.0

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

@@ -0,0 +1,128 @@
+import {
+  createDecipheriv,
+  createHash,
+  pbkdf2Sync,
+  timingSafeEqual,
+} from 'node:crypto';
+import { TextDecoder } from 'node:util';
+
+const CHROMIUM_CBC_IV = Buffer.alloc(16, 0x20);
+const DOMAIN_HASH_BYTES = 32;
+
+export function deriveChromiumCookieKey(password, platform) {
+  if (platform !== 'darwin' && platform !== 'linux') {
+    throw new Error(`CBC cookie keys are not used on ${platform}`);
+  }
+  return pbkdf2Sync(
+    password,
+    'saltysalt',
+    platform === 'darwin' ? 1003 : 1,
+    16,
+    'sha1'
+  );
+}
+
+function removeDomainHash(plaintext, host, databaseVersion) {
+  if (databaseVersion < 24) {
+    return plaintext;
+  }
+  if (plaintext.length < DOMAIN_HASH_BYTES) {
+    throw new Error('decrypted cookie is missing its domain hash');
+  }
+  const expectedHash = createHash('sha256').update(host).digest();
+  const actualHash = plaintext.subarray(0, DOMAIN_HASH_BYTES);
+  if (!timingSafeEqual(actualHash, expectedHash)) {
+    throw new Error('decrypted cookie domain hash does not match its host');
+  }
+  return plaintext.subarray(DOMAIN_HASH_BYTES);
+}
+
+function decodeCookieValue(plaintext) {
+  return new TextDecoder('utf-8', { fatal: true }).decode(plaintext);
+}
+
+/** Validate and decode plaintext returned by a Chromium platform decryptor. */
+export function decodeChromiumCookiePlaintext({
+  plaintext,
+  host,
+  databaseVersion = 0,
+}) {
+  return decodeCookieValue(
+    removeDomainHash(Buffer.from(plaintext), host, databaseVersion)
+  );
+}
+
+function decryptCbcCookie(encryptedValue, key) {
+  const decipher = createDecipheriv('aes-128-cbc', key, CHROMIUM_CBC_IV);
+  return Buffer.concat([
+    decipher.update(encryptedValue.subarray(3)),
+    decipher.final(),
+  ]);
+}
+
+function decryptGcmCookie(encryptedValue, key) {
+  const payload = encryptedValue.subarray(3);
+  if (payload.length < 12 + 16) {
+    throw new Error('encrypted AES-GCM cookie is truncated');
+  }
+  const nonce = payload.subarray(0, 12);
+  const authenticationTag = payload.subarray(-16);
+  const ciphertext = payload.subarray(12, -16);
+  const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+  decipher.setAuthTag(authenticationTag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+/** Decrypt a Chromium cookie encrypted_value using an already recovered key. */
+export function decryptChromiumCookie({
+  encryptedValue,
+  host,
+  databaseVersion = 0,
+  platform = process.platform,
+  key,
+}) {
+  const encrypted = Buffer.from(encryptedValue);
+  const prefix = encrypted.subarray(0, 3).toString('ascii');
+  if (prefix === 'v20') {
+    throw new Error(
+      'Windows app-bound v20 cookies cannot be decrypted outside the browser; use a browser-supported export or a previously saved storage state'
+    );
+  }
+  if (prefix !== 'v10' && prefix !== 'v11') {
+    throw new Error(
+      'cookie does not use a supported Chromium encryption prefix'
+    );
+  }
+  if (!Buffer.isBuffer(key)) {
+    throw new TypeError('a recovered cookie encryption key is required');
+  }
+  const plaintext =
+    platform === 'win32'
+      ? decryptGcmCookie(encrypted, key)
+      : decryptCbcCookie(encrypted, key);
+  return decodeChromiumCookiePlaintext({
+    plaintext,
+    host,
+    databaseVersion,
+  });
+}
+
+export function chromiumSameSite(value) {
+  if (Number(value) === 2) {
+    return 'Strict';
+  }
+  if (Number(value) === 1) {
+    return 'Lax';
+  }
+  return 'None';
+}
+
+export function firefoxSameSite(value) {
+  if (Number(value) === 2) {
+    return 'Strict';
+  }
+  if (Number(value) === 1) {
+    return 'Lax';
+  }
+  return 'None';
+}

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,
+};