browser-commander 0.21.2 → 0.22.0

package/src/browser/browser-sources.json

@@ -0,0 +1,399 @@
+{
+  "comment": [
+    "Catalogue of installed browsers Browser Commander can import from (issue",
+    "#114). Each entry says where a browser keeps its profiles on every",
+    "platform, how its Chromium Safe Storage key is named, and how the OS",
+    "records it as the default browser, so profile discovery, cookie",
+    "decryption and `browser: 'default'` resolution are all data-driven and",
+    "identical across JavaScript, Python and Rust.",
+    "",
+    "Root templates use these placeholders, expanded per platform:",
+    "  {home}          the user home directory",
+    "  {appSupport}    {home}/Library/Application Support (darwin only)",
+    "  {localAppData}  %LOCALAPPDATA% (win32 only)",
+    "  {appData}       %APPDATA% / roaming (win32 only)",
+    "  {config}        {home}/.config (linux only)",
+    "A browser with \"singleProfile\": true keeps its data in the root itself",
+    "(one profile named \"Default\"); otherwise the root holds Chromium profile",
+    "subdirectories (Default, Profile 1, ...) or a Firefox profiles.ini.",
+    "",
+    "This file is shared, not translated: Python and Rust ship byte-identical",
+    "copies, checked by scripts/check-shared-fingerprint-assets.sh."
+  ],
+  "browsers": [
+    {
+      "id": "chrome",
+      "family": "chromium",
+      "aliases": ["google-chrome", "google chrome"],
+      "roots": {
+        "darwin": ["{appSupport}/Google/Chrome"],
+        "win32": ["{localAppData}/Google/Chrome/User Data"],
+        "linux": ["{config}/google-chrome"]
+      },
+      "safeStorage": {
+        "service": "Chrome Safe Storage",
+        "application": "chrome",
+        "folder": "Chrome Keys"
+      },
+      "default": {
+        "darwin": ["com.google.chrome"],
+        "linux": ["google-chrome.desktop", "google-chrome-stable.desktop"],
+        "win32": ["ChromeHTML"]
+      }
+    },
+    {
+      "id": "chrome-beta",
+      "family": "chromium",
+      "aliases": ["google-chrome-beta"],
+      "roots": {
+        "darwin": ["{appSupport}/Google/Chrome Beta"],
+        "win32": ["{localAppData}/Google/Chrome Beta/User Data"],
+        "linux": ["{config}/google-chrome-beta"]
+      },
+      "safeStorage": {
+        "service": "Chrome Safe Storage",
+        "application": "google-chrome-beta",
+        "folder": "Chrome Keys"
+      },
+      "default": {
+        "darwin": ["com.google.chrome.beta"],
+        "linux": ["google-chrome-beta.desktop"],
+        "win32": ["ChromeBHTML"]
+      }
+    },
+    {
+      "id": "chrome-dev",
+      "family": "chromium",
+      "aliases": ["google-chrome-dev", "google-chrome-unstable"],
+      "roots": {
+        "darwin": ["{appSupport}/Google/Chrome Dev"],
+        "win32": ["{localAppData}/Google/Chrome Dev/User Data"],
+        "linux": ["{config}/google-chrome-unstable"]
+      },
+      "safeStorage": {
+        "service": "Chrome Safe Storage",
+        "application": "google-chrome-unstable",
+        "folder": "Chrome Keys"
+      },
+      "default": {
+        "darwin": ["com.google.chrome.dev"],
+        "linux": ["google-chrome-unstable.desktop"],
+        "win32": ["ChromeDHTML"]
+      }
+    },
+    {
+      "id": "chrome-canary",
+      "family": "chromium",
+      "aliases": ["google-chrome-canary"],
+      "roots": {
+        "darwin": ["{appSupport}/Google/Chrome Canary"],
+        "win32": ["{localAppData}/Google/Chrome SxS/User Data"]
+      },
+      "safeStorage": {
+        "service": "Chrome Safe Storage",
+        "application": "chrome",
+        "folder": "Chrome Keys"
+      },
+      "default": {
+        "darwin": ["com.google.chrome.canary"],
+        "win32": ["ChromeSSHTM"]
+      }
+    },
+    {
+      "id": "chromium",
+      "family": "chromium",
+      "aliases": [],
+      "roots": {
+        "darwin": ["{appSupport}/Chromium"],
+        "win32": ["{localAppData}/Chromium/User Data"],
+        "linux": ["{config}/chromium"]
+      },
+      "safeStorage": {
+        "service": "Chromium Safe Storage",
+        "application": "chromium",
+        "folder": "Chromium Keys"
+      },
+      "default": {
+        "darwin": ["org.chromium.chromium"],
+        "linux": ["chromium.desktop", "chromium-browser.desktop"]
+      }
+    },
+    {
+      "id": "edge",
+      "family": "chromium",
+      "aliases": ["msedge", "microsoft-edge"],
+      "roots": {
+        "darwin": ["{appSupport}/Microsoft Edge"],
+        "win32": ["{localAppData}/Microsoft/Edge/User Data"],
+        "linux": ["{config}/microsoft-edge"]
+      },
+      "safeStorage": {
+        "service": "Microsoft Edge Safe Storage",
+        "application": "microsoft-edge",
+        "folder": "Microsoft Edge Keys"
+      },
+      "default": {
+        "darwin": ["com.microsoft.edgemac"],
+        "linux": ["microsoft-edge.desktop"],
+        "win32": ["MSEdgeHTM"]
+      }
+    },
+    {
+      "id": "edge-beta",
+      "family": "chromium",
+      "aliases": ["microsoft-edge-beta"],
+      "roots": {
+        "darwin": ["{appSupport}/Microsoft Edge Beta"],
+        "win32": ["{localAppData}/Microsoft/Edge Beta/User Data"],
+        "linux": ["{config}/microsoft-edge-beta"]
+      },
+      "safeStorage": {
+        "service": "Microsoft Edge Safe Storage",
+        "application": "microsoft-edge-beta",
+        "folder": "Microsoft Edge Keys"
+      },
+      "default": {
+        "darwin": ["com.microsoft.edgemac.beta"],
+        "linux": ["microsoft-edge-beta.desktop"]
+      }
+    },
+    {
+      "id": "edge-dev",
+      "family": "chromium",
+      "aliases": ["microsoft-edge-dev"],
+      "roots": {
+        "darwin": ["{appSupport}/Microsoft Edge Dev"],
+        "win32": ["{localAppData}/Microsoft/Edge Dev/User Data"],
+        "linux": ["{config}/microsoft-edge-dev"]
+      },
+      "safeStorage": {
+        "service": "Microsoft Edge Safe Storage",
+        "application": "microsoft-edge-dev",
+        "folder": "Microsoft Edge Keys"
+      },
+      "default": {
+        "darwin": ["com.microsoft.edgemac.dev"],
+        "linux": ["microsoft-edge-dev.desktop"]
+      }
+    },
+    {
+      "id": "brave",
+      "family": "chromium",
+      "aliases": ["brave-browser"],
+      "roots": {
+        "darwin": ["{appSupport}/BraveSoftware/Brave-Browser"],
+        "win32": ["{localAppData}/BraveSoftware/Brave-Browser/User Data"],
+        "linux": ["{config}/BraveSoftware/Brave-Browser"]
+      },
+      "safeStorage": {
+        "service": "Brave Safe Storage",
+        "application": "brave",
+        "folder": "Brave Keys"
+      },
+      "default": {
+        "darwin": ["com.brave.browser"],
+        "linux": ["brave-browser.desktop", "brave.desktop"],
+        "win32": ["BraveHTML"]
+      }
+    },
+    {
+      "id": "vivaldi",
+      "family": "chromium",
+      "aliases": [],
+      "roots": {
+        "darwin": ["{appSupport}/Vivaldi"],
+        "win32": ["{localAppData}/Vivaldi/User Data"],
+        "linux": ["{config}/vivaldi"]
+      },
+      "safeStorage": {
+        "service": "Vivaldi Safe Storage",
+        "application": "vivaldi",
+        "folder": "Vivaldi Keys"
+      },
+      "default": {
+        "darwin": ["com.vivaldi.vivaldi"],
+        "linux": ["vivaldi.desktop", "vivaldi-stable.desktop"],
+        "win32": ["VivaldiHTM"]
+      }
+    },
+    {
+      "id": "opera",
+      "family": "chromium",
+      "aliases": [],
+      "singleProfile": true,
+      "roots": {
+        "darwin": ["{appSupport}/com.operasoftware.Opera"],
+        "win32": ["{appData}/Opera Software/Opera Stable"],
+        "linux": ["{config}/opera"]
+      },
+      "safeStorage": {
+        "service": "Opera Safe Storage",
+        "application": "opera",
+        "folder": "Opera Keys"
+      },
+      "default": {
+        "darwin": ["com.operasoftware.opera"],
+        "linux": ["opera.desktop", "opera_opera.desktop"],
+        "win32": ["OperaStable"]
+      }
+    },
+    {
+      "id": "opera-gx",
+      "family": "chromium",
+      "aliases": ["operagx"],
+      "singleProfile": true,
+      "roots": {
+        "darwin": ["{appSupport}/com.operasoftware.OperaGX"],
+        "win32": ["{appData}/Opera Software/Opera GX Stable"],
+        "linux": ["{config}/opera-gx"]
+      },
+      "safeStorage": {
+        "service": "Opera Safe Storage",
+        "application": "opera-gx",
+        "folder": "Opera Keys"
+      },
+      "default": {
+        "darwin": ["com.operasoftware.operagx"],
+        "win32": ["OperaGXStable"]
+      }
+    },
+    {
+      "id": "yandex",
+      "family": "chromium",
+      "aliases": ["yandex-browser", "yandexbrowser"],
+      "roots": {
+        "darwin": ["{appSupport}/Yandex/YandexBrowser"],
+        "win32": ["{localAppData}/Yandex/YandexBrowser/User Data"],
+        "linux": ["{config}/yandex-browser"]
+      },
+      "safeStorage": {
+        "service": "Yandex Safe Storage",
+        "application": "yandex-browser",
+        "folder": "Yandex Keys"
+      },
+      "default": {
+        "darwin": ["ru.yandex.desktop.yandex-browser"],
+        "linux": ["yandex-browser.desktop"],
+        "win32": ["YandexHTML"]
+      }
+    },
+    {
+      "id": "arc",
+      "family": "chromium",
+      "aliases": [],
+      "roots": {
+        "darwin": ["{appSupport}/Arc/User Data"],
+        "win32": [
+          "{localAppData}/Packages/TheBrowserCompany.Arc_ttt1ap7aakyb4/LocalCache/Local/Arc/User Data"
+        ]
+      },
+      "safeStorage": {
+        "service": "Arc Safe Storage",
+        "application": "arc",
+        "folder": "Arc Keys"
+      },
+      "default": {
+        "darwin": ["company.thebrowser.browser"],
+        "win32": ["ArcHTML"]
+      }
+    },
+    {
+      "id": "firefox",
+      "family": "firefox",
+      "aliases": ["mozilla-firefox"],
+      "roots": {
+        "darwin": ["{appSupport}/Firefox"],
+        "win32": ["{appData}/Mozilla/Firefox"],
+        "linux": ["{home}/.mozilla/firefox"]
+      },
+      "default": {
+        "darwin": ["org.mozilla.firefox"],
+        "linux": ["firefox.desktop", "firefox-esr.desktop"],
+        "win32": ["FirefoxHTML", "FirefoxURL"]
+      }
+    },
+    {
+      "id": "firefox-developer",
+      "family": "firefox",
+      "aliases": ["firefox-dev", "firefox-developer-edition"],
+      "roots": {
+        "darwin": ["{appSupport}/Firefox"],
+        "win32": ["{appData}/Mozilla/Firefox"],
+        "linux": ["{home}/.mozilla/firefox"]
+      },
+      "default": {
+        "darwin": ["org.mozilla.firefoxdeveloperedition"]
+      }
+    },
+    {
+      "id": "firefox-nightly",
+      "family": "firefox",
+      "aliases": ["nightly"],
+      "roots": {
+        "darwin": ["{appSupport}/Firefox"],
+        "win32": ["{appData}/Mozilla/Firefox"],
+        "linux": ["{home}/.mozilla/firefox"]
+      },
+      "default": {
+        "darwin": ["org.mozilla.nightly"],
+        "linux": ["firefox-nightly.desktop"]
+      }
+    },
+    {
+      "id": "librewolf",
+      "family": "firefox",
+      "aliases": [],
+      "roots": {
+        "darwin": ["{appSupport}/LibreWolf"],
+        "win32": ["{appData}/librewolf"],
+        "linux": ["{home}/.librewolf"]
+      },
+      "default": {
+        "darwin": ["io.gitlab.librewolf-community"],
+        "linux": ["librewolf.desktop"]
+      }
+    },
+    {
+      "id": "waterfox",
+      "family": "firefox",
+      "aliases": [],
+      "roots": {
+        "darwin": ["{appSupport}/Waterfox"],
+        "win32": ["{appData}/Waterfox"],
+        "linux": ["{home}/.waterfox"]
+      },
+      "default": {
+        "darwin": ["net.waterfox.waterfox"],
+        "linux": ["waterfox.desktop"]
+      }
+    },
+    {
+      "id": "zen",
+      "family": "firefox",
+      "aliases": ["zen-browser"],
+      "roots": {
+        "darwin": ["{appSupport}/zen"],
+        "win32": ["{appData}/zen"],
+        "linux": ["{home}/.zen"]
+      },
+      "default": {
+        "darwin": ["app.zen-browser.zen"],
+        "linux": ["zen.desktop", "zen-browser.desktop"]
+      }
+    },
+    {
+      "id": "floorp",
+      "family": "firefox",
+      "aliases": [],
+      "roots": {
+        "darwin": ["{appSupport}/Floorp"],
+        "win32": ["{appData}/Floorp"],
+        "linux": ["{home}/.floorp"]
+      },
+      "default": {
+        "darwin": ["org.floorp.Floorp"],
+        "linux": ["floorp.desktop"]
+      }
+    }
+  ]
+}

package/src/browser/default-browser.js

@@ -0,0 +1,176 @@
+/**
+ * Resolve the operating-system default web browser to a canonical browser id
+ * from the shared catalogue (#114), so `browser: 'default'` imports from
+ * whichever browser a person actually uses.
+ *
+ * Each platform records the default differently:
+ *
+ * - macOS keeps it in the LaunchServices database as the `https` URL-scheme
+ *   handler's bundle id (`defaults read
+ *   com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers`).
+ * - Linux reports it through `xdg-settings get default-web-browser` (a
+ *   `.desktop` file name), falling back to the `x-scheme-handler/https`
+ *   association from `xdg-mime`.
+ * - Windows stores the `https` UserChoice ProgId under
+ *   `HKCU\...\UrlAssociations\https\UserChoice`.
+ *
+ * Every lookup runs through an injected command runner so the resolver is
+ * deterministic in tests, and the raw identifier is matched against the
+ * `default` identifiers each browser declares in `browser-sources.json`.
+ */
+import { runCommand as runSubprocess } from '../utilities/subprocess.js';
+import { BROWSER_SOURCES } from './browser-sources.js';
+
+async function defaultRunCommand(command, args, environment) {
+  const { stdout } = await runSubprocess(command, args, {
+    env: environment,
+    check: false,
+  });
+  return stdout;
+}
+
+/**
+ * Match a raw OS identifier (bundle id, `.desktop` name or ProgId) to a
+ * canonical browser id. Comparison is case-insensitive because the registry
+ * and the operating systems disagree on casing.
+ */
+function browserForIdentifier(identifier, platform) {
+  if (!identifier) {
+    return null;
+  }
+  const needle = identifier.trim().toLowerCase();
+  if (!needle) {
+    return null;
+  }
+  for (const source of BROWSER_SOURCES) {
+    const identifiers = source.default?.[platform] ?? [];
+    if (identifiers.some((candidate) => candidate.toLowerCase() === needle)) {
+      return source.id;
+    }
+  }
+  return null;
+}
+
+function parseMacLaunchServicesHandler(output) {
+  // `defaults read` prints NeXTSTEP-style plist text; each handler is a brace
+  // block that may carry an LSHandlerURLScheme and an LSHandlerRoleAll bundle
+  // id. Find the block that handles https and read its bundle id.
+  for (const block of output.split('}')) {
+    if (!/LSHandlerURLScheme\s*=\s*"?https"?\s*;/.test(block)) {
+      continue;
+    }
+    const match = /LSHandlerRoleAll\s*=\s*"?([^";]+)"?\s*;/.exec(block);
+    if (match) {
+      return match[1].trim();
+    }
+  }
+  return null;
+}
+
+async function resolveDarwinDefault(runCommand, environment) {
+  const output = await runCommand(
+    'defaults',
+    [
+      'read',
+      'com.apple.LaunchServices/com.apple.launchservices.secure',
+      'LSHandlers',
+    ],
+    environment
+  );
+  return browserForIdentifier(parseMacLaunchServicesHandler(output), 'darwin');
+}
+
+async function resolveLinuxDefault(runCommand, environment) {
+  let desktop = '';
+  try {
+    desktop = (
+      await runCommand(
+        'xdg-settings',
+        ['get', 'default-web-browser'],
+        environment
+      )
+    ).trim();
+  } catch {
+    // xdg-settings may be absent; fall through to the xdg-mime query.
+  }
+  let resolved = browserForIdentifier(desktop, 'linux');
+  if (resolved) {
+    return resolved;
+  }
+  try {
+    const fallback = (
+      await runCommand(
+        'xdg-mime',
+        ['query', 'default', 'x-scheme-handler/https'],
+        environment
+      )
+    ).trim();
+    resolved = browserForIdentifier(fallback, 'linux');
+  } catch {
+    resolved = null;
+  }
+  return resolved;
+}
+
+function parseWindowsProgId(output) {
+  // `reg query` prints `    ProgId    REG_SZ    FirefoxHTML`; take the last
+  // whitespace-separated token of the ProgId line.
+  for (const line of output.split(/\r?\n/)) {
+    if (/\bProgId\b/i.test(line)) {
+      const tokens = line.trim().split(/\s+/);
+      return tokens[tokens.length - 1];
+    }
+  }
+  return null;
+}
+
+async function resolveWindowsDefault(runCommand, environment) {
+  let output;
+  try {
+    output = await runCommand(
+      'reg',
+      [
+        'query',
+        'HKCU\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\https\\UserChoice',
+        '/v',
+        'ProgId',
+      ],
+      environment
+    );
+  } catch {
+    return null;
+  }
+  return browserForIdentifier(parseWindowsProgId(output), 'win32');
+}
+
+/**
+ * Resolve the system default browser to a canonical catalogue id.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.platform=process.platform]
+ * @param {Object<string,string>} [options.environment=process.env]
+ * @param {Function} [options.runCommand] - `(command, args, env) => stdout`
+ * @returns {Promise<string|null>} The browser id, or null when it cannot be resolved
+ */
+export async function resolveDefaultBrowser({
+  platform = process.platform,
+  environment = process.env,
+  runCommand = defaultRunCommand,
+} = {}) {
+  if (platform === 'darwin') {
+    return await resolveDarwinDefault(runCommand, environment);
+  }
+  if (platform === 'linux') {
+    return await resolveLinuxDefault(runCommand, environment);
+  }
+  if (platform === 'win32') {
+    return await resolveWindowsDefault(runCommand, environment);
+  }
+  return null;
+}
+
+export {
+  browserForIdentifier,
+  parseMacLaunchServicesHandler,
+  parseWindowsProgId,
+};

package/src/browser/migration/cookies.js

@@ -116,6 +116,9 @@ export async function migrateCookies({
     const batch = await readCookies({
       browser,
       profile,
+      // Read from the exact directory the migration resolved (which honours a
+      // custom `userDataDir`) instead of re-resolving the default profile.
+      profileDir: sourceProfileDir,
       domainFilter: domainFilter ?? undefined,
       ignoreDecryptionErrors: true,
       ...readerOptions,

package/src/browser/migration/index.js

@@ -1,9 +1,10 @@
 import path from 'node:path';
 import os from 'node:os';
 
+import { resolveImportSource } from '../browser-cookies.js';
+import { browserFamily, isSingleProfileBrowser } from '../browser-sources.js';
 import {
   browserProfileRoot,
-  normalizeCookieBrowser,
   resolveBrowserProfile,
 } from '../browser-profiles.js';
 import { migrateBookmarks } from './bookmarks.js';
@@ -48,7 +49,17 @@ export const ALL_DATA_CLASSES = Object.freeze([
   'extensions',
 ]);
 
-const CHROMIUM_BROWSERS = new Set(['chrome', 'chromium', 'brave', 'edge']);
+// Classification is driven by the shared catalogue so every Chromium variant
+// (vivaldi, opera, arc, the chrome/edge channels, …) and every Firefox fork
+// (librewolf, waterfox, zen, floorp, the firefox channels, …) is handled the
+// same way as its canonical engine, not just the original four browsers.
+function isChromiumBrowser(browser) {
+  return browserFamily(browser) === 'chromium';
+}
+
+function isFirefoxBrowser(browser) {
+  return browserFamily(browser) === 'firefox';
+}
 
 function emptyMigrated() {
   return {
@@ -69,21 +80,23 @@ async function resolveSourceProfileDir({
   homeDir,
   environment,
 }) {
+  // A Chromium profile lives in a named subdirectory of the user data dir,
+  // except in single-profile browsers (Opera) that keep it in the root; for
+  // Firefox the userDataDir already points at the profile.
+  const nestsProfiles =
+    isChromiumBrowser(browser) && !isSingleProfileBrowser(browser);
   if (userDataDir) {
-    // For Chromium a profile lives in a named subdirectory; for Firefox the
-    // userDataDir already points at the profile.
-    if (CHROMIUM_BROWSERS.has(browser)) {
-      return path.join(userDataDir, profile ?? 'Default');
-    }
-    return userDataDir;
+    return nestsProfiles
+      ? path.join(userDataDir, profile ?? 'Default')
+      : userDataDir;
   }
-  if (CHROMIUM_BROWSERS.has(browser)) {
+  if (isChromiumBrowser(browser)) {
     const root = browserProfileRoot(browser, {
       platform,
       homeDir,
       environment,
     });
-    return path.join(root, profile ?? 'Default');
+    return nestsProfiles ? path.join(root, profile ?? 'Default') : root;
   }
   const resolved = await resolveBrowserProfile({
     browser,
@@ -120,7 +133,7 @@ async function resolvePasswordKeys({
     platform,
     environment,
   });
-  const resolveSourceKey = CHROMIUM_BROWSERS.has(browser)
+  const resolveSourceKey = isChromiumBrowser(browser)
     ? createSourceKeyResolver({
         browser,
         platform,
@@ -156,6 +169,7 @@ export async function migrateProfile({
   keys,
   homeDir = os.homedir(),
   environment = process.env,
+  runCommand,
 }) {
   if (!from?.browser) {
     throw new TypeError('migrateProfile requires from.browser');
@@ -163,9 +177,19 @@ export async function migrateProfile({
   if (!to) {
     throw new TypeError('migrateProfile requires a target directory (to)');
   }
-  const browser = normalizeCookieBrowser(from.browser);
-  const profile = from.profile ?? 'Default';
-  const isFirefox = browser === 'firefox';
+  // An explicit userDataDir names the source, so only an installed-browser
+  // import is steered towards the profile holding the requested domains.
+  const source = await resolveImportSource({
+    browser: from.browser,
+    domains: from.userDataDir ? undefined : domains,
+    platform,
+    homeDir,
+    environment,
+    runCommand,
+  });
+  const { browser } = source;
+  const profile = from.profile ?? source.profile ?? 'Default';
+  const isFirefox = isFirefoxBrowser(browser);
   const sourceProfileDir = await resolveSourceProfileDir({
     browser,
     profile,
@@ -183,6 +207,9 @@ export async function migrateProfile({
     warnings: [],
     cookies: [],
   };
+  if (source.warning) {
+    report.warnings.push(source.warning);
+  }
 
   if (selected.has('cookies')) {
     if (isFirefox) {