browser-commander 0.21.2 → 0.23.0

package/.jscpd-baseline.json

@@ -19,6 +19,7 @@
     "0fd23be8410c2c95": 1,
     "0fe4f3b5e5e939b3": 1,
     "1019ebbe7f07a5ad": 1,
+    "119f429fe4d23e4a": 1,
     "1273365073edd790": 1,
     "1296adc3c3128048": 1,
     "13c4b58d3ea0719b": 1,
@@ -54,11 +55,11 @@
     "2e70be24d2268673": 1,
     "2f4c9810eae87d6f": 1,
     "2f9e15467cc2f12a": 1,
+    "30da9d4e83f1c939": 1,
     "3101802d3ea65339": 1,
     "33357ce94e07cc4b": 1,
     "35cf2769645f3234": 1,
     "37bd4114d0089f49": 1,
-    "389df6fb4b8315a1": 1,
     "39eaada6d1879f4a": 1,
     "3a9f1672ecc1d55b": 1,
     "3adca52a3f04837c": 1,
@@ -77,6 +78,7 @@
     "4c3b94caa28045d0": 1,
     "4e090d6bb30e6551": 1,
     "4f3c541b3f3e3f23": 1,
+    "4f93b074bc2ac9e8": 1,
     "5085765e1f103f3e": 1,
     "5184c90c9f8406c3": 1,
     "520a28ee2ced56c2": 1,
@@ -153,11 +155,9 @@
     "92ddafa7e65be7eb": 1,
     "94821a4d1b745dfd": 1,
     "97c5a112fdde7be8": 1,
-    "98cc22079feaa004": 1,
     "990d87f21678fa96": 1,
     "9a72b1c2f22156ca": 1,
     "9b6ef4df04562546": 1,
-    "9c055dfd90c369bf": 1,
     "9ee57dcd5e7a6691": 1,
     "9fbb8296259dedbe": 1,
     "a0183465782b0b15": 1,
@@ -167,11 +167,11 @@
     "a305c6cac16f3af5": 1,
     "a4c8498d4f2d2191": 1,
     "a6ad7ab6c05656dc": 1,
+    "a6ffab1aacd00af6": 1,
     "a78d76908162699e": 1,
     "a9bd4ffef6da5faf": 1,
     "a9d71c2e50f1b832": 1,
     "acc95d694eb2f581": 1,
-    "ad4469f2e8131535": 1,
     "ad4cfa76daa1b6fc": 1,
     "ad50b48938af8aef": 1,
     "adae1329361a81a1": 1,
@@ -190,7 +190,6 @@
     "bb269582b94ed42d": 1,
     "bb3e6d0f7e7edccd": 1,
     "bc9115be3a462930": 1,
-    "bccf0d5cc57c08df": 1,
     "bd0ae42c13d5b4f9": 1,
     "bd6c62a6e1c6a071": 1,
     "bdb8ca169be36b80": 1,
@@ -207,10 +206,10 @@
     "c9cf3c28bed33a5b": 1,
     "cab590a1d04b5a05": 1,
     "cbd444e9a6a9072e": 1,
-    "cd49f39b43d14635": 1,
     "cebff7d1cc87f646": 1,
     "cf6116d195199f8a": 1,
     "cfd68135b744c27b": 1,
+    "d016035b3bf3340c": 1,
     "d097f41a6f43e634": 1,
     "d0da8714c4b7de30": 1,
     "d17201496391f6cc": 1,

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.23.0
+
+### Minor Changes
+
+- b56775b: Add Safari and Safari Technology Preview cookie sources, including installed,
+  default/auto and custom-directory import, counts-only domain discovery, validated
+  binarycookies decoding and actionable Full Disk Access errors. Migration reports
+  unsupported Safari classes and the SameSite Lax fallback. Other Safari stores,
+  Firefox/WebKit targets, full clones and additional data classes remain tracked in
+  issues #117–#120; this release does not claim full Safari profile import.
+
+## 0.22.0
+
+### Minor Changes
+
+- f4ce84c: Add a shared catalogue of importable browsers and resolve the system default
+  (#114).
+
+  - `browser-sources.json` is a shared, data-driven catalogue of the browsers
+    Browser Commander can import from — Chrome and its Beta/Dev/Canary channels,
+    Edge channels, Brave variants, Chromium, Opera and Opera GX, Vivaldi, Arc,
+    Yandex, and Firefox with its LibreWolf, Waterfox, Zen, Floorp, Developer
+    Edition and Nightly forks. It records each browser's per-platform profile
+    roots, Chromium Safe Storage identity, and operating-system default
+    identifiers, and ships byte-identical to the Python and Rust packages.
+  - `browser: 'default'` (or `'auto'`) now resolves the operating-system default
+    web browser (macOS LaunchServices, Linux `xdg-settings`/`xdg-mime`, Windows
+    `UserChoice` ProgId) to a catalogue id, so an import follows whichever
+    browser a person actually uses.
+  - Profile discovery and migration classify a browser's engine family from the
+    catalogue instead of a hard-coded list, so every catalogued Chromium variant
+    and Firefox fork is recognised, and reading cookies honours a custom
+    `userDataDir`.
+  - New `cookies sources` and `profile sources` commands (and the
+    `cookies.sources`/`profile.sources` JSON-RPC methods) report which browsers
+    and profiles hold cookies — optionally for specific `--domain`s — as names
+    and counts only, never values.
+  - A `default`/`auto` migration scoped to `domains` falls back from a default
+    browser that holds no cookies for them to the installed profile holding the
+    most, and reports which one with a `default-browser-fallback` warning
+    (`resolveImportSource`). Migrating from Opera or Opera GX now reads their
+    single profile from the user data directory itself.
+
 ## 0.21.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.21.2",
+  "version": "0.23.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "bin": {

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

@@ -1,29 +1,20 @@
 import { readFile } from 'node:fs/promises';
 
 import { runCommand as runSubprocess } from '../utilities/subprocess.js';
+import { safeStorageIdentity } from './browser-sources.js';
 
-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',
-  },
-};
+/**
+ * The Chromium Safe Storage identity for a browser, from the shared
+ * `browser-sources.json` catalogue. Firefox-family browsers return
+ * `undefined` because they do not use OSCrypt.
+ */
+function safeStorageFor(browser) {
+  try {
+    return safeStorageIdentity(browser);
+  } catch {
+    return undefined;
+  }
+}
 
 /**
  * Run a credential tool (`security`, `secret-tool`, `kwallet-query`,
@@ -35,7 +26,7 @@ async function runCredentialCommand(command, args, environment) {
 }
 
 async function readLinuxSafeStoragePassword(browser, environment, runCommand) {
-  const identity = SAFE_STORAGE[browser];
+  const identity = safeStorageFor(browser);
   try {
     const password = await runCommand(
       'secret-tool',
@@ -72,7 +63,7 @@ export async function readSafeStoragePassword({
   environment = process.env,
   runCredentialCommand: runCommand = runCredentialCommand,
 }) {
-  const identity = SAFE_STORAGE[browser];
+  const identity = safeStorageFor(browser);
   if (!identity) {
     throw new Error(`No Safe Storage identity is known for ${browser}`);
   }

package/src/browser/browser-cookies.js

@@ -24,12 +24,20 @@ import {
   openSqliteDatabase,
   preserveIntegerPrecision,
 } from './browser-cookie-database.js';
+import { browserFamily } from './browser-sources.js';
 import {
   findCookieDatabase,
+  isDefaultBrowserKeyword,
   listBrowserProfiles,
-  normalizeCookieBrowser,
   resolveBrowserProfile,
+  resolveSourceBrowser,
 } from './browser-profiles.js';
+import { resolveDefaultBrowser } from './default-browser.js';
+import {
+  countSafariCookies,
+  parseSafariCookies,
+  readSafariCookieFile,
+} from './safari-cookies.js';
 
 const CHROME_EPOCH_OFFSET_SECONDS = 11_644_473_600n;
 const MICROSECONDS_PER_SECOND = 1_000_000n;
@@ -266,20 +274,33 @@ export async function readBrowserCookiesWithDependencies(
   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,
+  const runCommand = dependencies.runCommand;
+  const browser = await resolveSourceBrowser(options.browser, {
     platform,
-    homeDir,
     environment,
+    runCommand,
   });
-  const cookiePath = await findCookieDatabase(browser, profile.path, platform);
+  // A caller that already resolved the profile directory (for example a
+  // migration honouring a custom `userDataDir`) passes it as `profileDir`, so
+  // the reader does not re-resolve the default profile location.
+  const profilePath = options.profileDir
+    ? options.profileDir
+    : (
+        await resolveBrowserProfile({
+          browser,
+          profile: options.profile,
+          platform,
+          homeDir,
+          environment,
+          runCommand,
+        })
+      ).path;
+  const cookiePath = await findCookieDatabase(browser, profilePath, platform);
   if (!cookiePath) {
-    throw new Error(`No cookie database exists in ${profile.path}`);
+    throw new Error(`No cookie database exists in ${profilePath}`);
   }
   const cache = normalizeCookieCache(
     options.cache,
@@ -288,7 +309,7 @@ export async function readBrowserCookiesWithDependencies(
   );
   const identity = JSON.stringify({
     browser,
-    profile: profile.path,
+    profile: profilePath,
     domainFilter: options.domainFilter ?? null,
     ignoreDecryptionErrors: options.ignoreDecryptionErrors === true,
   });
@@ -303,10 +324,18 @@ export async function readBrowserCookiesWithDependencies(
     return cachedCookies;
   }
 
+  if (browserFamily(browser) === 'safari') {
+    const cookies = parseSafariCookies(
+      await readSafariCookieFile(cookiePath, { environment }),
+      options.domainFilter
+    );
+    await writeCookieResultCache({ cache, identity, cookies, now });
+    return cookies;
+  }
   const database = await openCookieDatabase(cookiePath);
   let cookies;
   try {
-    if (browser === 'firefox') {
+    if (browserFamily(browser) === 'firefox') {
       cookies = mapFirefoxCookieRows(
         readFirefoxRows(database, options.domainFilter)
       );
@@ -323,7 +352,7 @@ export async function readBrowserCookiesWithDependencies(
         ignoreDecryptionErrors: options.ignoreDecryptionErrors === true,
         now,
         platform,
-        profile,
+        profile: { path: profilePath },
         readSafeStoragePassword:
           dependencies.readSafeStoragePassword ?? readSafeStoragePassword,
         readWindowsEncryptionKey:
@@ -343,6 +372,217 @@ export function readBrowserCookies(options) {
   return readBrowserCookiesWithDependencies(options);
 }
 
+/**
+ * Count cookies in a database by domain, without ever reading a cookie value.
+ * Only host names and row counts are touched, so this is safe to expose for a
+ * "which browser holds cookies for this domain" listing.
+ */
+function countCookiesByDomain(database, family, domains) {
+  const column = family === 'firefox' ? 'host' : 'host_key';
+  const table = family === 'firefox' ? 'moz_cookies' : 'cookies';
+  const countFor = (filter) => {
+    const query = filter
+      ? `SELECT COUNT(*) AS n FROM ${table} WHERE ${column} LIKE ?`
+      : `SELECT COUNT(*) AS n FROM ${table}`;
+    const statement = database.prepare(query);
+    const row = filter ? statement.get(`%${filter}%`) : statement.get();
+    return Number(row?.n ?? 0);
+  };
+  const total = countFor(null);
+  if (!Array.isArray(domains) || domains.length === 0) {
+    return { total, byDomain: null };
+  }
+  const byDomain = {};
+  for (const domain of domains) {
+    byDomain[domain] = countFor(domain);
+  }
+  return { total, byDomain };
+}
+
+/**
+ * List the installed browser profiles that hold cookies, with per-domain
+ * counts when `domains` is given. Values are never read or returned — this is
+ * the data behind the `cookies sources` command.
+ *
+ * @param {Object} [options]
+ * @param {string[]} [options.domains] - Restrict and count by these domains
+ * @param {string} [options.platform=process.platform]
+ * @param {string} [options.homeDir=os.homedir()]
+ * @param {Object} [options.environment=process.env]
+ * @returns {Promise<Array<Object>>} One entry per profile:
+ *   `{browser, profile, path, isDefault, cookies, byDomain}`, plus `error`
+ *   when the database could not be read
+ */
+export async function listCookieSources({
+  domains,
+  platform = process.platform,
+  homeDir = os.homedir(),
+  environment = process.env,
+} = {}) {
+  const profiles = await listBrowserProfiles({
+    platform,
+    homeDir,
+    environment,
+  });
+  const sources = [];
+  for (const profile of profiles) {
+    const cookiePath = await findCookieDatabase(
+      profile.browser,
+      profile.path,
+      platform
+    );
+    if (!cookiePath) {
+      continue;
+    }
+    const family = browserFamily(profile.browser);
+    let counts;
+    let error;
+    let database;
+    try {
+      if (family === 'safari') {
+        counts = countSafariCookies(
+          await readSafariCookieFile(cookiePath, { environment }),
+          domains
+        );
+      } else {
+        database = await openCookieDatabase(cookiePath);
+        counts = countCookiesByDomain(database, family, domains);
+      }
+    } catch (openError) {
+      error = openError.message;
+    } finally {
+      database?.close();
+    }
+    if (error) {
+      sources.push({
+        browser: profile.browser,
+        profile: profile.name,
+        path: profile.path,
+        isDefault: profile.isDefault,
+        error,
+      });
+      continue;
+    }
+    // When filtering by domain, skip profiles that hold none of them.
+    const matchedCount = counts.byDomain
+      ? Object.values(counts.byDomain).reduce((sum, n) => sum + n, 0)
+      : counts.total;
+    if (Array.isArray(domains) && domains.length > 0 && matchedCount === 0) {
+      continue;
+    }
+    sources.push({
+      browser: profile.browser,
+      profile: profile.name,
+      path: profile.path,
+      isDefault: profile.isDefault,
+      cookies: counts.total,
+      byDomain: counts.byDomain,
+    });
+  }
+  return sources;
+}
+
+function matchedCookies(source) {
+  return Object.values(source.byDomain ?? {}).reduce((sum, n) => sum + n, 0);
+}
+
+/**
+ * Pick the source browser for an import. A `default`/`auto` request scoped to
+ * `domains` uses the system default browser when it holds cookies for them
+ * and otherwise falls back to the installed browser profile holding the most,
+ * so "import my github.com sign-in" works whichever browser has it. Only
+ * names and counts are read (see `listCookieSources`), never cookie values.
+ *
+ * @param {Object} options
+ * @param {string} options.browser - Catalogue id, `default` or `auto`
+ * @param {string[]} [options.domains]
+ * @param {string} [options.platform=process.platform]
+ * @param {string} [options.homeDir=os.homedir()]
+ * @param {Object} [options.environment=process.env]
+ * @param {Function} [options.runCommand] - Injected for default-browser lookup
+ * @returns {Promise<Object>} `{browser, profile, warning}`: `profile` is the
+ *   profile holding the cookies (when one was chosen) and `warning` is a
+ *   migration-report warning explaining a fallback away from the system
+ *   default (reason `default-browser-fallback` or `default-browser-unknown`),
+ *   or `null`
+ */
+export async function resolveImportSource({
+  browser,
+  domains,
+  platform = process.platform,
+  homeDir = os.homedir(),
+  environment = process.env,
+  runCommand,
+}) {
+  if (
+    !isDefaultBrowserKeyword(browser) ||
+    !Array.isArray(domains) ||
+    domains.length === 0
+  ) {
+    return {
+      browser: await resolveSourceBrowser(browser, {
+        platform,
+        environment,
+        runCommand,
+      }),
+      profile: undefined,
+      warning: null,
+    };
+  }
+  const systemDefault = await resolveDefaultBrowser({
+    platform,
+    environment,
+    runCommand,
+  });
+  const listedSources = await listCookieSources({
+    domains,
+    platform,
+    homeDir,
+    environment,
+  });
+  const holders = listedSources.filter((source) => !source.error);
+  const fromDefault = holders.filter(
+    (source) => source.browser === systemDefault
+  );
+  const unreadableDefault = listedSources.find(
+    (source) => source.browser === systemDefault && source.error
+  );
+  if (fromDefault.length === 0 && unreadableDefault) {
+    throw new Error(
+      `Could not inspect the default browser (${systemDefault}): ${unreadableDefault.error}`
+    );
+  }
+  const candidates = fromDefault.length > 0 ? fromDefault : holders;
+  if (candidates.length === 0) {
+    if (!systemDefault) {
+      throw new Error(
+        `Could not determine the system default browser, and no installed browser holds cookies for ${domains.join(', ')}.`
+      );
+    }
+    return { browser: systemDefault, profile: undefined, warning: null };
+  }
+  // The first profile with the most matching cookies; listing order breaks
+  // ties, so a browser's default profile wins over its others.
+  const best = candidates.reduce((chosen, source) =>
+    matchedCookies(source) > matchedCookies(chosen) ? source : chosen
+  );
+  let warning = null;
+  if (best.browser !== systemDefault) {
+    const reason = systemDefault
+      ? `The default browser (${systemDefault}) holds no cookies for`
+      : 'Could not determine the default browser to read cookies for';
+    warning = {
+      type: 'source',
+      item: best.browser,
+      reason: systemDefault
+        ? 'default-browser-fallback'
+        : 'default-browser-unknown',
+      detail: `${reason} ${domains.join(', ')}; imported from ${best.browser} instead.`,
+    };
+  }
+  return { browser: best.browser, profile: best.profile, warning };
+}
+
 export {
   clearBrowserCookieMemoryCache,
   decryptChromiumCookie,