browser-commander 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- a23c0fa: Add installed-browser profile discovery and privacy-preserving cookie import for Chrome, Edge, Brave, Chromium, and Firefox, including OS credential caching and Playwright/Puppeteer-compatible output.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -152,8 +152,41 @@ const connection = await launchRealBrowser({
 await connection.browser.close();
 ```
 
-Cookie seeding copies only cookies you explicitly provide; the helper does not
-read, decrypt, or expose cookies from a browser's default profile.
+Cookie seeding copies only cookies you explicitly provide. To seed a dedicated
+profile from one of your installed browser profiles, use the explicit local
+cookie-import helper:
+
+```javascript
+import {
+  launchAndConnectRealBrowser,
+  listBrowserProfiles,
+  readBrowserCookies,
+} from 'browser-commander';
+
+console.log(await listBrowserProfiles({ browser: 'chrome' }));
+
+const cookies = await readBrowserCookies({
+  browser: 'chrome', // chrome, edge, brave, chromium, or firefox
+  profile: 'Default',
+  domainFilter: 'example.com',
+  cache: { ttlMinutes: 60 },
+});
+
+const connection = await launchAndConnectRealBrowser({
+  engine: 'playwright',
+  channel: 'chrome',
+  userDataDir: '/tmp/my-dedicated-profile',
+  seedCookies: cookies,
+});
+```
+
+The import stays on the local machine and runs only when called. It never sends
+cookie data anywhere. Decrypted result and derived-key cache files are stored
+under `~/.browser-commander/cookie-cache/` with owner-only permissions. The
+default 60-minute TTL and a cross-process lock ensure that concurrent or repeated
+scripts touch Keychain, libsecret/KWallet, or DPAPI at most once per TTL window.
+Set `refresh: true` to force a new read, customize `cache.dir`/`ttlMinutes`, or
+set `cache: false` to opt out of disk caching.
 `launchAndConnectRealBrowser()` remains available as a descriptive alias.
 Remote-debugging, loopback, and profile arguments remain managed even when all
 optional defaults are ignored; `headless: true` adds `--headless=new`.
@@ -391,6 +424,48 @@ and profile path alongside `{ browser, page }`.
 of defaults to omit (or `true` to omit all optional defaults). The older
 `args` append option remains supported.
 
+### listBrowserProfiles(options)
+
+Discover cookie-bearing profiles for Chrome, Edge, Brave, Chromium, and Firefox.
+Pass an optional `browser` to narrow discovery. Each result contains
+`{ browser, name, displayName, path, isDefault }`.
+
+### readBrowserCookies(options)
+
+Read cookies from an installed browser profile and return the exact
+`{ name, value, domain, path, expires, httpOnly, secure, sameSite }` shape used by
+Playwright and Puppeteer:
+
+```javascript
+const cookies = await readBrowserCookies({
+  browser: 'firefox',
+  profile: 'default-release', // optional; the default profile is selected first
+  domainFilter: 'example.com', // optional substring match
+  cache: { dir: './private-cookie-cache', ttlMinutes: 30 },
+  refresh: false,
+});
+```
+
+Platform support:
+
+| Browser family                | macOS                                | Linux                                                                       | Windows                                       |
+| ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------- |
+| Chrome, Edge, Brave, Chromium | Keychain + AES-128-CBC (`v10`/`v11`) | libsecret/KWallet + AES-128-CBC (`v11`), or the Chromium `v10` fallback key | DPAPI-protected AES-256-GCM key (`v10`/`v11`) |
+| Firefox                       | `cookies.sqlite`                     | `cookies.sqlite`                                                            | `cookies.sqlite`                              |
+
+Firefox cookie values are stored directly in its local cookie database. Chromium
+database version 24 domain hashes and Chrome's 1601-based timestamps are handled
+automatically. Current Windows Chromium can use app-bound `v20` encryption,
+which intentionally requires the browser's privileged elevation service and
+cannot be decrypted by an ordinary external process. The helper reports that
+boundary instead of bypassing it; use a browser-supported export or an existing
+Browser Commander storage-state file for those cookies. Set
+`ignoreDecryptionErrors: true` only when returning the remaining decryptable
+cookies is acceptable.
+
+Treat imported cookies like passwords: keep cache directories private, use a
+short TTL, never commit them, and seed only a dedicated automation profile.
+
 ### saveStorageState(page, filePath)
 
 Save the current cookies and localStorage in Playwright's portable storage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "type": "module",
@@ -63,6 +63,7 @@
     }
   },
   "dependencies": {
+    "better-sqlite3": "^12.11.1",
     "log-lazy": "^1.0.4",
     "test-anywhere": "^0.9.1"
   },
@@ -72,8 +73,8 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "husky": "^9.1.7",
-    "jsdoc": "^4.0.4",
     "jscpd": "^4.0.5",
+    "jsdoc": "^4.0.4",
     "lint-staged": "^16.2.6",
     "playwright": "^1.56.1",
     "prettier": "^3.6.2",

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

@@ -0,0 +1,278 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { execFile as execFileCallback } from 'node:child_process';
+import {
+  chmod,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+  stat,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const DEFAULT_TTL_MINUTES = 60;
+const LOCK_STALE_MILLISECONDS = 30_000;
+const LOCK_WAIT_MILLISECONDS = 30_000;
+const credentialPromises = new Map();
+const execFile = promisify(execFileCallback);
+let windowsPrincipalPromise;
+
+function hash(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function clearBrowserCookieMemoryCache() {
+  credentialPromises.clear();
+}
+
+export function normalizeCookieCache(cache, homeDir, ttlMinutes) {
+  const selectedTtl = ttlMinutes ?? cache?.ttlMinutes ?? DEFAULT_TTL_MINUTES;
+  if (!Number.isFinite(selectedTtl) || selectedTtl < 0) {
+    throw new RangeError(
+      'cookie cache ttlMinutes must be a non-negative number'
+    );
+  }
+  if (cache === false) {
+    return { enabled: false, ttlSeconds: selectedTtl * 60 };
+  }
+  return {
+    enabled: true,
+    dir: path.resolve(
+      cache?.dir ?? path.join(homeDir, '.browser-commander', 'cookie-cache')
+    ),
+    ttlSeconds: selectedTtl * 60,
+  };
+}
+
+function windowsPrincipal() {
+  windowsPrincipalPromise ??= execFile('whoami', [], {
+    windowsHide: true,
+  }).then(({ stdout }) => stdout.trim());
+  return windowsPrincipalPromise;
+}
+
+async function restrictOwnerOnly(targetPath, directory) {
+  if (process.platform === 'win32') {
+    const principal = await windowsPrincipal();
+    if (!principal) {
+      throw new Error('Could not identify the current Windows user');
+    }
+    const permission = directory ? '(OI)(CI)F' : 'F';
+    await execFile(
+      'icacls',
+      [
+        targetPath,
+        '/inheritance:r',
+        '/grant:r',
+        `${principal}:${permission}`,
+        '/q',
+      ],
+      { windowsHide: true }
+    );
+    return;
+  }
+  await chmod(targetPath, directory ? 0o700 : 0o600);
+}
+
+async function ensureCacheDirectory(cacheDir) {
+  await mkdir(cacheDir, { recursive: true, mode: 0o700 });
+  await restrictOwnerOnly(cacheDir, true);
+}
+
+async function readFreshJson(filePath, ttlSeconds, now) {
+  try {
+    const value = JSON.parse(await readFile(filePath, 'utf8'));
+    const age = now() / 1000 - value.savedAt;
+    return age >= 0 && age <= ttlSeconds ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeOwnerOnlyJson(filePath, value) {
+  const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  const handle = await open(temporaryPath, 'wx', 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(value)}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporaryPath, filePath);
+  } catch (error) {
+    await rm(temporaryPath, { force: true });
+    throw error;
+  }
+  await restrictOwnerOnly(filePath, false);
+}
+
+function cachePath(cacheDir, kind, identity) {
+  return path.join(cacheDir, `${kind}-${hash(identity)}.json`);
+}
+
+export async function readCookieResultCache({
+  cache,
+  identity,
+  refresh,
+  now = Date.now,
+}) {
+  if (!cache.enabled || refresh) {
+    return null;
+  }
+  const cached = await readFreshJson(
+    cachePath(cache.dir, 'cookies', identity),
+    cache.ttlSeconds,
+    now
+  );
+  return cached?.kind === 'cookies' && Array.isArray(cached.cookies)
+    ? cached.cookies
+    : null;
+}
+
+export async function writeCookieResultCache({
+  cache,
+  identity,
+  cookies,
+  now = Date.now,
+}) {
+  if (!cache.enabled) {
+    return;
+  }
+  await ensureCacheDirectory(cache.dir);
+  await writeOwnerOnlyJson(cachePath(cache.dir, 'cookies', identity), {
+    version: 1,
+    kind: 'cookies',
+    savedAt: now() / 1000,
+    cookies,
+  });
+}
+
+async function removeStaleLock(lockPath, now) {
+  try {
+    const lockStat = await stat(lockPath);
+    if (now() - lockStat.mtimeMs > LOCK_STALE_MILLISECONDS) {
+      await rm(lockPath, { force: true });
+    }
+  } catch {
+    // Another process may have released it already.
+  }
+}
+
+async function wait(milliseconds) {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function acquireCredentialLock(lockPath, cachedPath, options) {
+  const startedAt = options.now();
+  while (options.now() - startedAt <= LOCK_WAIT_MILLISECONDS) {
+    try {
+      return await open(lockPath, 'wx', 0o600);
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        throw error;
+      }
+      const cached = await readFreshJson(
+        cachedPath,
+        options.ttlSeconds,
+        options.now
+      );
+      if (
+        cached?.kind === 'derived-key' &&
+        (!options.refresh || cached.savedAt !== options.initialSavedAt)
+      ) {
+        return { cached };
+      }
+      await removeStaleLock(lockPath, options.now);
+      await wait(50);
+    }
+  }
+  throw new Error('timed out waiting for another cookie credential reader');
+}
+
+async function loadOrCreateCredential({
+  cache,
+  identity,
+  refresh,
+  create,
+  now,
+  metadata,
+}) {
+  if (!cache.enabled) {
+    return { key: Buffer.from(await create()), savedAt: now() / 1000 };
+  }
+  await ensureCacheDirectory(cache.dir);
+  const cachedPath = cachePath(cache.dir, 'credential', identity);
+  const lockPath = `${cachedPath}.lock`;
+  const initial = await readFreshJson(cachedPath, cache.ttlSeconds, now);
+  if (!refresh && initial?.kind === 'derived-key') {
+    return {
+      key: Buffer.from(initial.key, 'base64'),
+      savedAt: initial.savedAt,
+    };
+  }
+
+  const acquired = await acquireCredentialLock(lockPath, cachedPath, {
+    initialSavedAt: initial?.savedAt,
+    now,
+    refresh,
+    ttlSeconds: cache.ttlSeconds,
+  });
+  if (acquired.cached) {
+    return {
+      key: Buffer.from(acquired.cached.key, 'base64'),
+      savedAt: acquired.cached.savedAt,
+    };
+  }
+
+  try {
+    const afterLock = await readFreshJson(cachedPath, cache.ttlSeconds, now);
+    if (
+      afterLock?.kind === 'derived-key' &&
+      (!refresh || afterLock.savedAt !== initial?.savedAt)
+    ) {
+      return {
+        key: Buffer.from(afterLock.key, 'base64'),
+        savedAt: afterLock.savedAt,
+      };
+    }
+    const key = Buffer.from(await create());
+    const savedAt = now() / 1000;
+    await writeOwnerOnlyJson(cachedPath, {
+      version: 1,
+      kind: 'derived-key',
+      savedAt,
+      key: key.toString('base64'),
+      ...metadata,
+    });
+    return { key, savedAt };
+  } finally {
+    await acquired.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+export async function getCachedCredential(options) {
+  const memoryIdentity = `${options.cache.dir ?? 'disabled'}:${options.identity}`;
+  const now = options.now ?? Date.now;
+  if (!options.refresh && credentialPromises.has(memoryIdentity)) {
+    const cached = await credentialPromises.get(memoryIdentity);
+    const age = now() / 1000 - cached.savedAt;
+    if (age >= 0 && age <= options.cache.ttlSeconds) {
+      return cached.key;
+    }
+    credentialPromises.delete(memoryIdentity);
+  }
+  const promise = loadOrCreateCredential({ ...options, now });
+  credentialPromises.set(memoryIdentity, promise);
+  try {
+    return (await promise).key;
+  } catch (error) {
+    if (credentialPromises.get(memoryIdentity) === promise) {
+      credentialPromises.delete(memoryIdentity);
+    }
+    throw error;
+  }
+}

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

@@ -0,0 +1,148 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCallback);
+
+const SAFE_STORAGE = {
+  brave: {
+    application: 'brave',
+    folder: 'Brave Keys',
+    service: 'Brave Safe Storage',
+  },
+  chrome: {
+    application: 'chrome',
+    folder: 'Chrome Keys',
+    service: 'Chrome Safe Storage',
+  },
+  chromium: {
+    application: 'chromium',
+    folder: 'Chromium Keys',
+    service: 'Chromium Safe Storage',
+  },
+  edge: {
+    application: 'microsoft-edge',
+    folder: 'Microsoft Edge Keys',
+    service: 'Microsoft Edge Safe Storage',
+  },
+};
+
+async function runCredentialCommand(command, args, environment) {
+  const { stdout } = await execFile(command, args, {
+    encoding: 'utf8',
+    env: environment,
+    maxBuffer: 1024 * 1024,
+    windowsHide: true,
+  });
+  return stdout.trim();
+}
+
+async function readLinuxSafeStoragePassword(browser, environment, runCommand) {
+  const identity = SAFE_STORAGE[browser];
+  try {
+    const password = await runCommand(
+      'secret-tool',
+      ['lookup', 'application', identity.application],
+      environment
+    );
+    if (password) {
+      return password;
+    }
+  } catch {
+    // Try KWallet before reporting that v11 key storage is unavailable.
+  }
+  try {
+    const password = await runCommand(
+      'kwallet-query',
+      ['-r', identity.service, '-f', identity.folder, 'kdewallet'],
+      environment
+    );
+    if (password) {
+      return password;
+    }
+  } catch {
+    // Fall through to the actionable error below.
+  }
+  throw new Error(
+    `Could not read ${identity.service} from libsecret or KWallet; install secret-tool or unlock the browser key store`
+  );
+}
+
+/** Read a Chromium Safe Storage password from the platform credential store. */
+export async function readSafeStoragePassword({
+  browser,
+  platform = process.platform,
+  environment = process.env,
+  runCredentialCommand: runCommand = runCredentialCommand,
+}) {
+  const identity = SAFE_STORAGE[browser];
+  if (!identity) {
+    throw new Error(`No Safe Storage identity is known for ${browser}`);
+  }
+  if (platform === 'darwin') {
+    const password = await runCommand(
+      'security',
+      ['find-generic-password', '-w', '-s', identity.service],
+      environment
+    );
+    if (!password) {
+      throw new Error(`${identity.service} returned an empty password`);
+    }
+    return password;
+  }
+  if (platform === 'linux') {
+    return readLinuxSafeStoragePassword(browser, environment, runCommand);
+  }
+  throw new Error(`Safe Storage passwords are not used on ${platform}`);
+}
+
+const DPAPI_SCRIPT = [
+  '$inputBytes=[Convert]::FromBase64String($args[0])',
+  '$outputBytes=[Security.Cryptography.ProtectedData]::Unprotect(',
+  '  $inputBytes,$null,',
+  '  [Security.Cryptography.DataProtectionScope]::CurrentUser)',
+  '[Convert]::ToBase64String($outputBytes)',
+].join(';');
+
+/** Decrypt bytes with Windows DPAPI in the current user's security context. */
+export async function decryptWindowsDpapi(
+  encryptedValue,
+  { environment = process.env } = {}
+) {
+  const output = await runCredentialCommand(
+    'powershell.exe',
+    [
+      '-NoLogo',
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      DPAPI_SCRIPT,
+      Buffer.from(encryptedValue).toString('base64'),
+    ],
+    environment
+  );
+  return Buffer.from(output, 'base64');
+}
+
+/** Recover the legacy AES-GCM key from a Chromium Local State file. */
+export async function readWindowsEncryptionKey({
+  localStatePath,
+  environment = process.env,
+  decryptDpapi = decryptWindowsDpapi,
+}) {
+  let state;
+  try {
+    state = JSON.parse(await readFile(localStatePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Could not read Chromium Local State: ${error.message}`);
+  }
+  const encoded = state.os_crypt?.encrypted_key;
+  if (!encoded) {
+    throw new Error('Chromium Local State has no os_crypt.encrypted_key');
+  }
+  const encryptedKey = Buffer.from(encoded, 'base64');
+  if (encryptedKey.subarray(0, 5).toString('ascii') !== 'DPAPI') {
+    throw new Error('Chromium Local State key does not have a DPAPI prefix');
+  }
+  return decryptDpapi(encryptedKey.subarray(5), { environment });
+}

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