browser-commander 0.21.2 → 0.23.0

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,
@@ -101,6 +114,34 @@ function mergeReport(report, className, fragment) {
   report.warnings.push(...(fragment.warnings ?? []));
 }
 
+function reportSafariClasses(report, selected) {
+  for (const type of ALL_DATA_CLASSES.filter(
+    (name) => name !== 'cookies' && selected.has(name)
+  )) {
+    report.skipped.push({
+      type,
+      item: report.source.browser,
+      reason:
+        type === 'passwords'
+          ? 'safari-password-export-required'
+          : 'safari-class-not-supported',
+      detail:
+        type === 'passwords'
+          ? 'Safari passwords live in the Keychain. Export Passwords from Safari or the Passwords app to CSV; CSV import is tracked separately and is not supported yet.'
+          : 'Safari currently supports cookie import only; this data class has not been translated.',
+    });
+  }
+  if (report.cookies.length > 0) {
+    report.warnings.push({
+      type: 'cookies',
+      item: report.source.browser,
+      reason: 'safari-samesite-unavailable',
+      detail:
+        'Cookies.binarycookies does not store SameSite; imported cookies use Lax.',
+    });
+  }
+}
+
 async function resolvePasswordKeys({
   keys,
   browser,
@@ -120,7 +161,7 @@ async function resolvePasswordKeys({
     platform,
     environment,
   });
-  const resolveSourceKey = CHROMIUM_BROWSERS.has(browser)
+  const resolveSourceKey = isChromiumBrowser(browser)
     ? createSourceKeyResolver({
         browser,
         platform,
@@ -156,6 +197,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 +205,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 +235,9 @@ export async function migrateProfile({
     warnings: [],
     cookies: [],
   };
+  if (source.warning) {
+    report.warnings.push(source.warning);
+  }
 
   if (selected.has('cookies')) {
     if (isFirefox) {
@@ -207,6 +262,11 @@ export async function migrateProfile({
     }
   }
 
+  if (browserFamily(browser) === 'safari') {
+    reportSafariClasses(report, selected);
+    return report;
+  }
+
   if (selected.has('bookmarks')) {
     mergeReport(
       report,

package/src/browser/safari-cookies.js

@@ -0,0 +1,173 @@
+/** Read Safari's unencrypted, mixed-endian Cookies.binarycookies store.
+ * Format: https://github.com/libyal/dtformats/blob/main/documentation/Safari%20Cookies.asciidoc
+ * No SameSite attribute is stored in this format; use Lax and report that loss.
+ */
+import { readFile as readFileBytes, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+
+const APPLE_EPOCH = 978_307_200;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+function invalid(detail) {
+  throw new Error(`Invalid Safari binarycookies: ${detail}`);
+}
+
+function bounded(data, offset, size) {
+  if (offset < 0 || size < 0 || offset + size > data.length) {
+    invalid('truncated or out-of-range data');
+  }
+  return data.subarray(offset, offset + size);
+}
+
+function uint(data, offset, bigEndian = false) {
+  const bytes = bounded(data, offset, 4);
+  return bigEndian ? bytes.readUInt32BE() : bytes.readUInt32LE();
+}
+
+function string(record, field) {
+  const offset = uint(record, field);
+  if (offset < 56 || offset >= record.length) {
+    invalid('string offset');
+  }
+  const end = record.indexOf(0, offset);
+  if (end < 0) {
+    invalid('unterminated string');
+  }
+  try {
+    return utf8.decode(record.subarray(offset, end));
+  } catch {
+    return invalid('invalid UTF-8');
+  }
+}
+
+/** Validate all structural offsets before walking records; counts are bounded
+ * by the file size, so forged counts cannot cause unbounded allocations.
+ */
+function* records(data) {
+  if (bounded(data, 0, 4).toString('ascii') !== 'cook') {
+    invalid('file signature');
+  }
+  const pages = uint(data, 4, true);
+  bounded(data, 8, pages * 4);
+  let pageStart = 8 + pages * 4;
+  for (let index = 0; index < pages; index += 1) {
+    const page = bounded(data, pageStart, uint(data, 8 + index * 4, true));
+    pageStart += page.length;
+    if (uint(page, 0) !== 0x00010000) {
+      invalid('page signature');
+    }
+    const count = uint(page, 4);
+    const headerSize = 8 + count * 4;
+    bounded(page, 0, headerSize);
+    let previousEnd = headerSize;
+    for (let cookie = 0; cookie < count; cookie += 1) {
+      const start = uint(page, 8 + cookie * 4);
+      if (start < previousEnd) {
+        invalid('overlapping record');
+      }
+      const size = uint(page, start);
+      if (size < 56) {
+        invalid('short record');
+      }
+      const record = bounded(page, start, size);
+      previousEnd = start + size;
+      yield record;
+    }
+  }
+  // Safari may append a checksum and a plist trailer. They are not cookies.
+}
+
+/** Decode cookies in automation shape, using the existing substring filter. */
+export function parseSafariCookies(data, domainFilter) {
+  const cookies = [];
+  for (const record of records(data)) {
+    const domain = string(record, 16);
+    if (
+      domainFilter &&
+      !domain.toLowerCase().includes(domainFilter.toLowerCase())
+    ) {
+      continue;
+    }
+    const expiry = record.readDoubleLE(40) + APPLE_EPOCH;
+    if (
+      !Number.isFinite(expiry) ||
+      Math.abs(expiry) > Number.MAX_SAFE_INTEGER
+    ) {
+      invalid('expiry');
+    }
+    const flags = uint(record, 8);
+    cookies.push({
+      name: string(record, 20),
+      value: string(record, 28),
+      domain,
+      path: string(record, 24) || '/',
+      expires: Math.floor(expiry),
+      httpOnly: Boolean(flags & 4),
+      secure: Boolean(flags & 1),
+      sameSite: 'Lax',
+    });
+  }
+  return cookies;
+}
+
+/** Counts decode only domain strings. Names and values are never decoded. */
+export function countSafariCookies(data, domains) {
+  const byDomain = domains?.length
+    ? Object.fromEntries(domains.map((domain) => [domain, 0]))
+    : null;
+  let total = 0;
+  for (const record of records(data)) {
+    const host = string(record, 16).toLowerCase();
+    total += 1;
+    for (const domain of Object.keys(byDomain ?? {})) {
+      if (host.includes(domain.toLowerCase())) {
+        byDomain[domain] += 1;
+      }
+    }
+  }
+  return { total, byDomain };
+}
+
+/** A protected path is still a source: preserve it for an actionable read error. */
+export async function findSafariCookieFile(profileDir, statFile = stat) {
+  for (const candidate of [
+    path.join(profileDir, 'Cookies', 'Cookies.binarycookies'),
+    path.join(profileDir, 'Cookies.binarycookies'),
+  ]) {
+    try {
+      if ((await statFile(candidate)).isFile()) {
+        return candidate;
+      }
+    } catch (error) {
+      if (['EPERM', 'EACCES'].includes(error.code)) {
+        return candidate;
+      }
+      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) {
+        throw error;
+      }
+    }
+  }
+  return null;
+}
+
+export async function readSafariCookieFile(
+  filePath,
+  { environment = process.env, readFile = readFileBytes } = {}
+) {
+  try {
+    return await readFile(filePath);
+  } catch (error) {
+    if (!['EPERM', 'EACCES'].includes(error.code)) {
+      throw error;
+    }
+    const app =
+      environment.__CFBundleIdentifier ||
+      environment.TERM_PROGRAM ||
+      process.execPath;
+    throw new Error(
+      `Safari cookie access denied (${error.code}) at ${filePath}. Grant Full Disk Access to ${app}, the app running Browser Commander, then retry: x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`,
+      { cause: error }
+    );
+  }
+}

package/src/cli/args.js

@@ -78,11 +78,17 @@ export const COMMANDS = Object.freeze({
       domain: STRINGS,
     },
   },
+  'cookies sources': {
+    positionals: [],
+    options: { domain: STRINGS },
+  },
   'profile migrate': {
     positionals: [],
     options: {
       from: STRING,
       profile: STRING,
+      'user-data-dir': STRING,
+      'target-browser': STRING,
       to: STRING,
       include: STRING,
       domain: STRINGS,
@@ -92,6 +98,10 @@ export const COMMANDS = Object.freeze({
     positionals: [],
     options: { from: STRING, profile: STRING, to: STRING },
   },
+  'profile sources': {
+    positionals: [],
+    options: { browser: STRING },
+  },
   attach: {
     positionals: [],
     options: { mode: STRING, port: STRING, timeout: STRING },

package/src/cli/commands.js

@@ -210,6 +210,8 @@ async function profileMigrate(parsed, io) {
     await dispatchOnce(io, 'profile.migrate', {
       from: requireOption(options, 'from', 'profile migrate'),
       profile: options.profile,
+      userDataDir: options.userDataDir,
+      targetBrowser: options.targetBrowser,
       to: options.to,
       include: options.include
         ?.split(',')
@@ -220,6 +222,29 @@ async function profileMigrate(parsed, io) {
   );
 }
 
+/**
+ * List the installed browser profiles that hold cookies (names and counts
+ * only, never values), optionally filtered and counted by `--domain`.
+ */
+async function cookieSources(parsed, io) {
+  const { options } = parsed;
+  return done(
+    await dispatchOnce(io, 'cookies.sources', {
+      domains: options.domain,
+    })
+  );
+}
+
+/** List installed browser profiles, optionally for one `--browser`. */
+async function profileSources(parsed, io) {
+  const { options } = parsed;
+  return done(
+    await dispatchOnce(io, 'profile.sources', {
+      browser: options.browser,
+    })
+  );
+}
+
 /** Copy a real profile into `--to` (or a new temporary directory). */
 async function profileSnapshot(parsed, io) {
   const { options } = parsed;
@@ -323,8 +348,10 @@ export const COMMAND_HANDLERS = Object.freeze({
     profile: options.profile,
     domains: options.domain,
   })),
+  'cookies sources': cookieSources,
   'profile migrate': profileMigrate,
   'profile snapshot': profileSnapshot,
+  'profile sources': profileSources,
   attach,
   doctor,
   run,

package/src/cli/high-level-methods.js

@@ -191,12 +191,18 @@ async function importCookies(state, params) {
 }
 
 function migrateProfile(state, params) {
+  // The CLI passes the source browser flat (`--from`, `--profile`,
+  // `--user-data-dir`); migrateProfile expects them grouped under `from`.
   return state.dependencies.migrateProfile({
-    from: params.from,
-    profile: params.profile,
+    from: {
+      browser: requireString(params, 'from'),
+      profile: params.profile,
+      userDataDir: params.userDataDir,
+    },
     to: params.to,
     include: params.include,
     domains: params.domains,
+    targetBrowser: params.targetBrowser,
   });
 }
 
@@ -209,6 +215,24 @@ function snapshotProfile(state, params) {
   });
 }
 
+/** List browsers/profiles holding cookies, with optional per-domain counts. */
+async function cookieSources(state, params) {
+  const domains = params.domains;
+  if (domains !== undefined && !Array.isArray(domains)) {
+    throw invalidParams('domains must be an array of strings');
+  }
+  return { sources: await state.dependencies.listCookieSources({ domains }) };
+}
+
+/** List the installed browser profiles (never cookie values). */
+async function profileSources(state, params) {
+  return {
+    profiles: await state.dependencies.listBrowserProfiles({
+      browser: params.browser,
+    }),
+  };
+}
+
 function relayOf(state) {
   if (!state.relay) {
     throw invalidParams('No extension is attached; call attach first');
@@ -298,8 +322,10 @@ export const HIGH_LEVEL_METHODS = Object.freeze({
   'trace.start': traceStart,
   'trace.stop': traceStop,
   'cookies.import': importCookies,
+  'cookies.sources': cookieSources,
   'profile.migrate': migrateProfile,
   'profile.snapshot': snapshotProfile,
+  'profile.sources': profileSources,
   attach,
   'attach.tabs': attachTabs,
   'attach.send': attachSend,

package/src/cli/modules.js

@@ -64,6 +64,12 @@ export const DEFAULT_DEPENDENCIES = Object.freeze({
   writeTraceViewer,
   readBrowserCookies: async (options) =>
     (await import('../browser/browser-cookies.js')).readBrowserCookies(options),
+  listCookieSources: async (options) =>
+    (await import('../browser/browser-cookies.js')).listCookieSources(options),
+  listBrowserProfiles: async (options) =>
+    (await import('../browser/browser-profiles.js')).listBrowserProfiles(
+      options
+    ),
   loadEngine: (name) => importOptional(name, `The ${name} engine`),
   openInUserBrowser: async (url) =>
     (

package/src/exports.js

@@ -60,8 +60,12 @@ export {
 export { connectBrowser } from './browser/connector.js';
 export {
   listBrowserProfiles,
+  listCookieSources,
   readBrowserCookies,
+  resolveImportSource,
 } from './browser/browser-cookies.js';
+export { resolveDefaultBrowser } from './browser/default-browser.js';
+export { BROWSER_IDS, findBrowserSource } from './browser/browser-sources.js';
 export {
   launchAndConnectRealBrowser,
   launchRealBrowser,

package/tests/helpers/cli-fakes.js

@@ -158,6 +158,27 @@ export function createFakeDependencies() {
       { name: 'sid', value: '1', domain: `.${domainFilter}`, path: '/' },
       { name: 'bad', value: '2', domain: `.${domainFilter}`, path: '/' },
     ],
+    listCookieSources: async ({ domains } = {}) => [
+      {
+        browser: 'chrome',
+        profile: 'Default',
+        path: '/home/user/.config/google-chrome/Default',
+        isDefault: true,
+        cookies: 7,
+        byDomain: domains
+          ? Object.fromEntries(domains.map((d) => [d, 1]))
+          : null,
+      },
+    ],
+    listBrowserProfiles: async ({ browser } = {}) => [
+      {
+        browser: browser ?? 'chrome',
+        name: 'Default',
+        displayName: 'Default',
+        path: `/home/user/.config/${browser ?? 'google-chrome'}/Default`,
+        isDefault: true,
+      },
+    ],
     loadEngine: async (name) => ({ default: new FakeEngine(name) }),
     openInUserBrowser: async (url) => ({ opened: url, command: ['open', url] }),
     migrateProfile: async (options) => ({ migrated: {}, options }),

package/tests/helpers/migration-fixtures.js

@@ -8,7 +8,7 @@
  */
 
 import assert from 'node:assert';
-import { readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import BetterSqlite3 from 'better-sqlite3';
@@ -148,6 +148,35 @@ export async function writeFirefoxCookies(profileDir, rows) {
   return cookiePath;
 }
 
+/**
+ * Write a Linux Firefox-family install under `home` with one default profile,
+ * listed in `profiles.ini`, whose `cookies.sqlite` holds `rows`.
+ *
+ * @param {string} home - Home directory the install lives under
+ * @param {Array<Object>} rows - Cookie rows, as for `writeFirefoxCookies`
+ * @param {Object} [options]
+ * @param {string} [options.root='.mozilla/firefox'] - Install root, relative
+ *   to `home` (a fork such as LibreWolf uses its own)
+ * @param {string} [options.name='default-release'] - Profile name
+ * @returns {Promise<string>} The profile directory
+ */
+export async function writeFirefoxProfile(
+  home,
+  rows,
+  { root = '.mozilla/firefox', name = 'default-release' } = {}
+) {
+  const rootPath = path.join(home, ...root.split('/'));
+  const profileName = `xyz.${name}`;
+  const profilePath = path.join(rootPath, profileName);
+  await mkdir(profilePath, { recursive: true });
+  await writeFile(
+    path.join(rootPath, 'profiles.ini'),
+    `[Profile0]\nName=${name}\nIsRelative=1\nPath=${profileName}\nDefault=1\n`
+  );
+  await writeFirefoxCookies(profilePath, rows);
+  return profilePath;
+}
+
 /**
  * Write a Firefox `places.sqlite` with a toolbar bookmark and, unless
  * `withMenuBookmark` is false, a bookmarks-menu one. Each bookmark has its own

package/tests/unit/browser/browser-cookies-profiledir.test.js

@@ -0,0 +1,36 @@
+import assert from 'node:assert';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import { readBrowserCookiesWithDependencies } from '../../../src/browser/browser-cookies.js';
+import { writeFirefoxCookies } from '../../helpers/migration-fixtures.js';
+import { useTempDirectories } from '../../helpers/temp-directory.js';
+
+const makeDirectory = useTempDirectories();
+
+describe('readBrowserCookies honours an explicit profileDir', () => {
+  it('reads cookies from the given directory, not the default profile root', async () => {
+    const temporaryDirectory = await makeDirectory('bc-profiledir-');
+    // A custom userDataDir that is NOT under the default profile root.
+    const customProfile = path.join(temporaryDirectory, 'custom', 'profile');
+    await mkdir(customProfile, { recursive: true });
+    await writeFirefoxCookies(customProfile, [
+      { name: 'sid', value: 'abc', host: '.example.com' },
+    ]);
+
+    // homeDir points somewhere with no browser data, so a reader that ignored
+    // profileDir and re-resolved the default profile would find nothing.
+    const emptyHome = path.join(temporaryDirectory, 'empty-home');
+    await mkdir(emptyHome, { recursive: true });
+
+    const cookies = await readBrowserCookiesWithDependencies(
+      { browser: 'firefox', profileDir: customProfile },
+      { platform: 'linux', homeDir: emptyHome }
+    );
+
+    assert.equal(cookies.length, 1);
+    assert.equal(cookies[0].name, 'sid');
+    assert.equal(cookies[0].domain, '.example.com');
+  });
+});

package/tests/unit/browser/browser-cookies.test.js

@@ -37,7 +37,7 @@ import {
   listBrowserProfiles as publicListBrowserProfiles,
   readBrowserCookies as publicReadBrowserCookies,
 } from '../../../src/index.js';
-import { writeFirefoxCookies } from '../../helpers/migration-fixtures.js';
+import { writeFirefoxProfile } from '../../helpers/migration-fixtures.js';
 
 const CHROME_EPOCH_OFFSET_SECONDS = 11_644_473_600;
 const execFile = promisify(execFileCallback);
@@ -134,16 +134,7 @@ async function createChromiumProfile({ homeDir, rows, profile = 'Default' }) {
 }
 
 async function createFirefoxProfile({ homeDir, rows }) {
-  const root = path.join(homeDir, '.mozilla', 'firefox');
-  const profileName = 'fixture.default-release';
-  const profilePath = path.join(root, profileName);
-  await mkdir(profilePath, { recursive: true });
-  await writeFile(
-    path.join(root, 'profiles.ini'),
-    `[Profile0]\nName=default-release\nIsRelative=1\nPath=${profileName}\nDefault=1\n`
-  );
-  const cookiePath = await writeFirefoxCookies(profilePath, rows);
-  return { cookiePath, profilePath, root };
+  return { profilePath: await writeFirefoxProfile(homeDir, rows) };
 }
 
 describe('installed browser cookie import', () => {