browser-commander 0.24.0 → 0.25.0

package/tests/unit/browser/migration/firefox-history.test.js

@@ -0,0 +1,130 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { it } from 'node:test';
+
+import BetterSqlite3 from 'better-sqlite3';
+
+import { migrateProfile } from '../../../../src/browser/migration/index.js';
+import { repoPath } from '../../../helpers/repo.js';
+import { useTempDirectories } from '../../../helpers/temp-directory.js';
+
+const makeTempDir = useTempDirectories('bc-ff-history-');
+const schema = await readFile(
+  repoPath('tests/fixtures/firefox-history.sql'),
+  'utf8'
+);
+
+async function importHistory({ sql = schema, domains = [] } = {}) {
+  const source = await makeTempDir();
+  const target = path.join(await makeTempDir(), 'new-profile');
+  const filename = path.join(source, 'places.sqlite');
+  const db = new BetterSqlite3(filename);
+  try {
+    db.exec(sql);
+  } finally {
+    db.close();
+  }
+  const before = await readFile(filename);
+  const report = await migrateProfile({
+    from: { browser: 'firefox', userDataDir: source },
+    to: target,
+    include: ['history'],
+    domains,
+  });
+  assert.deepEqual(await readFile(filename), before);
+  return { report, target };
+}
+
+for (const domains of [[], ['GITHUB.COM.']]) {
+  it(`translates Firefox visits with ${domains.length ? 'exact domain filtering' : 'all domains'}`, async () => {
+    const { report, target } = await importHistory({ domains });
+    const count = domains.length ? 3 : 4;
+    assert.equal(report.migrated.history, count);
+    assert.deepEqual(report.skipped, []);
+    assert.equal(
+      report.warnings[0].reason,
+      'firefox-history-metadata-not-translated'
+    );
+    const db = new BetterSqlite3(path.join(target, 'History'), {
+      readonly: true,
+    });
+    try {
+      const rows = db
+        .prepare(
+          'SELECT url,title,visit_count,last_visit_time FROM urls ORDER BY url'
+        )
+        .safeIntegers()
+        .all();
+      assert.deepEqual(rows.slice(0, 2), [
+        {
+          url: 'https://docs.github.com/second',
+          title: '',
+          visit_count: 1n,
+          last_visit_time: 13344473600000003n,
+        },
+        {
+          url: 'https://github.com/first',
+          title: 'First Ω',
+          visit_count: 2n,
+          last_visit_time: 13344473600000002n,
+        },
+      ]);
+      const times = db
+        .prepare('SELECT visit_time FROM visits ORDER BY visit_time')
+        .safeIntegers()
+        .all();
+      assert.deepEqual(
+        times.map(({ visit_time }) => visit_time),
+        [
+          13344473600000001n,
+          13344473600000002n,
+          13344473600000003n,
+          13344473600000004n,
+        ].slice(0, count)
+      );
+    } finally {
+      db.close();
+    }
+    await assert.rejects(readFile(path.join(target, 'places.sqlite')), {
+      code: 'ENOENT',
+    });
+  });
+}
+
+it('reports a missing Firefox visit table before creating the target', async () => {
+  const { report, target } = await importHistory({
+    sql: 'CREATE TABLE moz_places (id INTEGER PRIMARY KEY, url TEXT, title TEXT)',
+  });
+  assert.equal(report.migrated.history, 0);
+  assert.equal(report.skipped[0].reason, 'source-format-unsupported');
+  assert.match(report.skipped[0].detail, /moz_historyvisits/u);
+  await assert.rejects(readFile(path.join(target, 'History')), {
+    code: 'ENOENT',
+  });
+});
+
+for (const [field, values] of [
+  [
+    'timestamp',
+    ['NULL', "'invalid'", '1.5', '-11644473600000001', '9223372036854775807'],
+  ],
+  ['url', ['NULL', "''", "x'0102'"]],
+]) {
+  it(`reports invalid visit ${field} without losing valid visits`, async () => {
+    for (const value of values) {
+      const extra =
+        field === 'timestamp'
+          ? `INSERT INTO moz_historyvisits VALUES (5,1,${value},1)`
+          : `INSERT INTO moz_places VALUES (5,${value},'Invalid'); INSERT INTO moz_historyvisits VALUES (5,5,1700000000000005,1)`;
+      const { report } = await importHistory({
+        sql: `${schema}\n${extra}`,
+        domains: ['github.com'],
+      });
+      assert.equal(report.migrated.history, 3);
+      assert.equal(report.skipped.length, 1);
+      assert.equal(report.skipped[0].reason, `invalid-history-${field}`);
+      assert.equal(report.skipped[0].item, 'places.sqlite visit 5');
+    }
+  });
+}

package/tests/unit/browser/migration/history-metadata.test.js

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { it } from 'node:test';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { useTempDirectories } from '../../../helpers/temp-directory.js';
+import { migrateHistory } from '../../../../src/browser/migration/history.js';
+
+const temporary = useTempDirectories('bc-history-metadata-');
+for (const domains of [['github.com'], []]) {
+  it(`${domains.length ? 'omits with warnings' : 'preserves'} derived history metadata`, async () => {
+    const source = await temporary();
+    const target = await temporary();
+    const filename = path.join(source, 'History');
+    const db = new Database(filename);
+    db.exec(
+      await readFile(
+        new URL(
+          '../../../../../tests/fixtures/history-opaque-metadata.sql',
+          import.meta.url
+        ),
+        'utf8'
+      )
+    );
+    db.close();
+    const before = await readFile(filename);
+    const report = await migrateHistory({
+      sourceProfileDir: source,
+      targetProfileDir: target,
+      domains,
+    });
+    assert.equal(report.migrated, 1);
+    const copy = new Database(path.join(target, 'History'));
+    try {
+      for (const [table, unfilteredCount] of [
+        ['clusters', 2],
+        ['clusters_and_visits', 3],
+        ['cluster_keywords', 2],
+        ['cluster_visit_duplicates', 2],
+        ['future "history" metadata', 1],
+      ]) {
+        const quoted = `"${table.replaceAll('"', '""')}"`;
+        const count = copy
+          .prepare(`SELECT count(*) AS n FROM ${quoted}`)
+          .get().n;
+        assert.equal(count, domains.length ? 0 : unfilteredCount, table);
+        assert.equal(
+          report.warnings.some(
+            (entry) =>
+              entry.item === table &&
+              entry.reason === 'unsupported-history-metadata'
+          ),
+          Boolean(domains.length)
+        );
+      }
+      assert.equal(
+        copy.prepare('SELECT count(*) AS n FROM urls').get().n,
+        domains.length ? 1 : 2
+      );
+      assert.equal(
+        copy.prepare('SELECT value FROM meta WHERE key=?').get('version').value,
+        70
+      );
+    } finally {
+      copy.close();
+    }
+    const bytes = await readFile(path.join(target, 'History'));
+    assert.equal(
+      bytes.includes(Buffer.from('unrelated-history-marker')),
+      !domains.length
+    );
+    assert.deepEqual(await readFile(filename), before);
+  });
+}

package/tests/unit/browser/migration/index.test.js

@@ -67,7 +67,7 @@ describe('migrateProfile', () => {
     assert.equal(report.migrated.cookies, 1);
     assert.equal(report.migrated.bookmarks, 1);
     assert.equal(report.migrated.passwords, 1);
-    // Firefox history cannot be migrated into Chrome's schema.
+    // This bookmark-only fixture has no Firefox visit table.
     assert.equal(report.migrated.history, 0);
     assert.equal(report.migrated.preferences, 0);
     assert.equal(report.migrated.extensions, 0);
@@ -97,6 +97,21 @@ describe('migrateProfile', () => {
     await assert.rejects(() => readFile(path.join(target, 'Login Data')));
   });
 
+  it('reports unsupported Firefox preferences and extensions explicitly', async () => {
+    const report = await migrateProfile({
+      from: { browser: 'firefox', userDataDir: await makeTempDir() },
+      to: await makeTempDir(),
+      include: ['preferences', 'extensions'],
+    });
+    assert.deepEqual(
+      report.skipped.map(({ type, reason }) => [type, reason]),
+      [
+        ['preferences', 'firefox-class-not-supported'],
+        ['extensions', 'firefox-class-not-supported'],
+      ]
+    );
+  });
+
   it('skips passwords with a warning when no target key is available on Windows', async () => {
     const source = await makeTempDir();
     const target = await makeTempDir();

package/tests/unit/browser/migration/opera-keys.test.js

@@ -0,0 +1,22 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { it } from 'node:test';
+import { localStatePathForProfile } from '../../../../src/browser/migration/os-crypt-keys.js';
+
+it('uses Opera single-profile Local State before a parent fallback', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'bc-opera-'));
+  try {
+    const profile = path.join(root, 'Opera Stable');
+    await mkdir(profile);
+    await writeFile(path.join(root, 'Local State'), '{}');
+    await writeFile(path.join(profile, 'Local State'), '{"os_crypt":{}}');
+    assert.equal(
+      localStatePathForProfile(profile),
+      path.join(profile, 'Local State')
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/tests/unit/browser/migration/safari-data.test.js

@@ -0,0 +1,143 @@
+import assert from 'node:assert/strict';
+import { readFile, copyFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { describe, it } from 'node:test';
+import {
+  readSafariBookmarks,
+  readSafariHistory,
+  readSafariPasswords,
+} from '../../../../src/browser/migration/safari.js';
+import { migrateProfile } from '../../../../src/browser/migration/index.js';
+import { useTempDirectories } from '../../../helpers/temp-directory.js';
+import Database from 'better-sqlite3';
+import path from 'node:path';
+import {
+  deriveChromiumCookieKey,
+  decryptChromiumCookie,
+} from '../../../../src/browser/browser-cookie-crypto.js';
+
+const fixture = (name) =>
+  fileURLToPath(
+    new URL(
+      `../../../../../tests/fixtures/safari-data/${name}`,
+      import.meta.url
+    )
+  );
+
+describe('Safari data sources', () => {
+  for (const format of ['binary', 'xml']) {
+    it(`preserves hierarchy and reading list from ${format} plist`, async () => {
+      const filename = fixture(`Bookmarks-${format}.plist`);
+      const before = await readFile(filename);
+      const tree = await readSafariBookmarks(filename);
+      assert.equal(tree[0].name, 'Work');
+      assert.equal(tree[0].children[0].name, 'Foundation ☃');
+      assert.equal(tree[1].children[0].readingList, true);
+      assert.deepEqual(await readFile(filename), before);
+    });
+  }
+
+  it('preserves all matching visits and converts the Cocoa epoch', async () => {
+    const filename = fixture('History.db');
+    const before = await readFile(filename);
+    const entries = await readSafariHistory(filename, ['github.com']);
+    assert.equal(entries.length, 2);
+    assert.equal(entries[0].time, 1778307200250000);
+    assert.deepEqual(await readFile(filename), before);
+  });
+
+  it('reads explicit BOM UTF-8 CSV with quoted newlines and filters domains', async () => {
+    const entries = await readSafariPasswords(fixture('Passwords.csv'), [
+      'github.com',
+    ]);
+    assert.deepEqual(entries, [
+      {
+        origin: 'https://github.com/login',
+        username: 'a,b',
+        password: 'p"a\nss',
+      },
+    ]);
+  });
+
+  const temporary = useTempDirectories('bc-safari-data-');
+  it('rejects password CSV records with missing or extra fields without changing the source', async () => {
+    for (const record of [
+      'https://github.com,a\n',
+      'https://github.com,a,b,c\n',
+    ]) {
+      const filename = path.join(await temporary(), 'Passwords.csv');
+      await writeFile(filename, `URL,Username,Password\n${record}`);
+      const before = await readFile(filename);
+      await assert.rejects(
+        readSafariPasswords(filename),
+        /Invalid Record Length/u
+      );
+      assert.deepEqual(await readFile(filename), before);
+    }
+  });
+
+  it('migrates custom Safari sources into native Chromium stores with target encryption', async () => {
+    const source = await temporary();
+    const target = await temporary();
+    await copyFile(
+      fixture('Bookmarks-binary.plist'),
+      path.join(source, 'Bookmarks.plist')
+    );
+    await copyFile(fixture('History.db'), path.join(source, 'History.db'));
+    const key = deriveChromiumCookieKey('dedicated-target', 'linux');
+    const report = await migrateProfile({
+      from: { browser: 'safari', userDataDir: source },
+      to: target,
+      include: ['bookmarks', 'history', 'passwords'],
+      domains: ['github.com'],
+      passwordCsv: fixture('Passwords.csv'),
+      platform: 'linux',
+      keys: { targetKey: key, targetPrefix: 'v11' },
+    });
+    assert.equal(report.migrated.bookmarks, 2);
+    assert.equal(report.migrated.history, 2);
+    assert.equal(report.migrated.passwords, 1);
+    assert.deepEqual(report.skipped, []);
+    assert.ok(
+      report.warnings.some(
+        ({ reason }) => reason === 'safari-reading-list-translated'
+      )
+    );
+    const db = new Database(path.join(target, 'Login Data'));
+    try {
+      const rows = db
+        .prepare('SELECT origin_url,password_value FROM logins')
+        .all();
+      assert.equal(rows.length, 1);
+      assert.equal(
+        decryptChromiumCookie({
+          encryptedValue: rows[0].password_value,
+          key,
+          platform: 'linux',
+          databaseVersion: 0,
+          host: 'github.com',
+        }),
+        'p"a\nss'
+      );
+    } finally {
+      db.close();
+    }
+  });
+
+  it('names the executing app and retry link for non-cookie protection failures', async () => {
+    const { withSafariAccess } =
+      await import('../../../../src/browser/safari-access.js');
+    for (const code of ['EPERM', 'EACCES']) {
+      await assert.rejects(
+        withSafariAccess(
+          '/Safari/History.db',
+          () => {
+            throw Object.assign(new Error('protected'), { code });
+          },
+          { TERM_PROGRAM: 'FixtureTerminal' }
+        ),
+        /Full Disk Access to FixtureTerminal.*Privacy_AllFiles/u
+      );
+    }
+  });
+});

package/tests/unit/browser/migration/sqlite-snapshot.test.js

@@ -1,5 +1,6 @@
 import assert from 'node:assert';
-import { stat } from 'node:fs/promises';
+import { stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { describe, it } from 'node:test';
 
 import BetterSqlite3 from 'better-sqlite3';
@@ -58,6 +59,60 @@ describe('withDatabaseSnapshot', () => {
       /does not exist/
     );
   });
+
+  it('does not substitute an unverified file copy when backup fails', async () => {
+    const sourcePath = path.join(await makeTempDir(), 'History');
+    await writeFile(sourcePath, 'not a SQLite database');
+    let readerCalled = false;
+    await assert.rejects(
+      withDatabaseSnapshot({
+        sourcePath,
+        read: () => {
+          readerCalled = true;
+        },
+      }),
+      /Consistent SQLite snapshot unavailable.*close the source browser/iu
+    );
+    assert.equal(readerCalled, false);
+  });
+
+  it(
+    'reports guidance for an exclusive lock without invoking the reader',
+    { timeout: 5000 },
+    async () => {
+      const sourcePath = await makeDatabase(1);
+      const writer = new BetterSqlite3(sourcePath);
+      writer.exec('BEGIN EXCLUSIVE');
+      try {
+        await assert.rejects(
+          withDatabaseSnapshot({
+            sourcePath,
+            read: () => assert.fail('locked snapshot reader invoked'),
+          }),
+          /Consistent SQLite snapshot unavailable.*close the source browser/iu
+        );
+      } finally {
+        writer.exec('ROLLBACK');
+        writer.close();
+      }
+    }
+  );
+
+  it('includes committed WAL records while the source connection stays open', async () => {
+    const sourcePath = await makeDatabase(1);
+    const writer = new BetterSqlite3(sourcePath);
+    writer.pragma('journal_mode = WAL');
+    writer.prepare('UPDATE urls SET title = ?').run('committed WAL title');
+    try {
+      const title = await readDatabaseSnapshot({
+        sourcePath,
+        read: (db) => db.prepare('SELECT title FROM urls').get().title,
+      });
+      assert.equal(title, 'committed WAL title');
+    } finally {
+      writer.close();
+    }
+  });
 });
 
 describe('readDatabaseSnapshot', () => {

package/tests/unit/browser/migration/validation.test.js

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import { readdir } from 'node:fs/promises';
+import { describe, it } from 'node:test';
+import { migrateProfile } from '../../../../src/browser/migration/index.js';
+import { useTempDirectories } from '../../../helpers/temp-directory.js';
+
+const temporary = useTempDirectories('bc-validation-');
+
+describe('migration validation before target mutation', () => {
+  it('rejects unknown classes and invalid domain filters', async () => {
+    for (const options of [
+      { include: ['invented'] },
+      { domains: ['https://example.com'] },
+    ]) {
+      const target = await temporary();
+      await assert.rejects(
+        migrateProfile({ from: { browser: 'chrome' }, to: target, ...options })
+      );
+      assert.deepEqual(await readdir(target), []);
+    }
+  });
+
+  it('rejects unsupported target layouts before creating Chromium files', async () => {
+    const target = await temporary();
+    await assert.rejects(
+      migrateProfile({
+        from: { browser: 'chrome' },
+        to: target,
+        include: ['bookmarks'],
+        targetBrowser: 'firefox',
+      }),
+      /target/u
+    );
+    assert.deepEqual(await readdir(target), []);
+  });
+
+  it('rejects detection-only sources before target mutation', async () => {
+    const source = await temporary();
+    const target = await temporary();
+    await assert.rejects(
+      migrateProfile({
+        from: { browser: 'duckduckgo', userDataDir: source },
+        to: target,
+        include: ['history'],
+      }),
+      /detection/u
+    );
+    assert.deepEqual(await readdir(target), []);
+  });
+
+  it('rejects a target that overlaps the source profile', async () => {
+    const source = await temporary();
+    await assert.rejects(
+      migrateProfile({
+        from: { browser: 'opera', userDataDir: source },
+        to: source,
+        include: ['bookmarks'],
+      }),
+      /overlap/u
+    );
+    assert.deepEqual(await readdir(source), []);
+  });
+});

package/tests/unit/browser/migration/yandex.test.js

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import { it } from 'node:test';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { useTempDirectories } from '../../../helpers/temp-directory.js';
+import { migrateProfile } from '../../../../src/browser/migration/index.js';
+import { encryptChromiumValue } from '../../../../src/browser/migration/chromium-crypto.js';
+import { readMigratedLogins } from '../../../helpers/migration-fixtures.js';
+
+const temporary = useTempDirectories('bc-yandex-');
+function migrateYandexPasswords(source, to, options = {}) {
+  return migrateProfile({
+    from: { browser: 'yandex', userDataDir: source },
+    to,
+    include: ['passwords'],
+    ...options,
+  });
+}
+
+it('identifies Ya Passman Data before prompting for target credentials', async () => {
+  const source = await temporary();
+  const target = await temporary();
+  await mkdir(path.join(source, 'Default'));
+  const db = new Database(path.join(source, 'Default', 'Ya Passman Data'));
+  db.exec(
+    "CREATE TABLE meta(key TEXT,value BLOB); INSERT INTO meta VALUES('local_encryptor_data',x'01')"
+  );
+  db.close();
+  const report = await migrateYandexPasswords(source, target);
+  assert.equal(report.migrated.passwords, 0);
+  assert.equal(
+    report.skipped[0].reason,
+    'yandex-passman-encryption-unsupported'
+  );
+  assert.match(
+    report.skipped[0].detail,
+    /local_encryptor_data.*master password/u
+  );
+});
+
+it('retains supported Login Data beside unsupported Ya Passman Data', async () => {
+  const source = await temporary();
+  const target = await temporary();
+  const profile = path.join(source, 'Default');
+  await mkdir(profile);
+  const passman = path.join(profile, 'Ya Passman Data');
+  await writeFile(passman, 'unsupported-store');
+  const sourceKey = randomBytes(16);
+  const targetKey = randomBytes(16);
+  const loginData = path.join(profile, 'Login Data');
+  const db = new Database(loginData);
+  db.exec(
+    'CREATE TABLE logins(origin_url TEXT,username_value TEXT,password_value BLOB)'
+  );
+  db.prepare('INSERT INTO logins VALUES(?,?,?)').run(
+    'https://example.com',
+    'alice',
+    encryptChromiumValue({
+      plaintext: 'retained-password',
+      key: sourceKey,
+      platform: 'linux',
+      prefix: 'v11',
+    })
+  );
+  db.close();
+  const original = await readFile(loginData);
+  const report = await migrateYandexPasswords(source, target, {
+    platform: 'linux',
+    keys: { targetKey, resolveSourceKey: () => sourceKey },
+  });
+  assert.equal(report.migrated.passwords, 1);
+  assert.equal(
+    report.skipped[0].reason,
+    'yandex-passman-encryption-unsupported'
+  );
+  assert.equal(
+    readMigratedLogins(target, targetKey)[0].password,
+    'retained-password'
+  );
+  assert.deepEqual(await readFile(loginData), original);
+  assert.equal(await readFile(passman, 'utf8'), 'unsupported-store');
+});

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

@@ -203,6 +203,21 @@ describe('launchAndConnectRealBrowser', () => {
     }
   });
 
+  it('rejects non-CDP catalogue browsers before resolving or spawning them', async () => {
+    for (const channel of ['firefox', 'librewolf', 'safari', 'duckduckgo']) {
+      await assert.rejects(
+        launchAndConnectRealBrowserWithDependencies(
+          { channel },
+          {
+            resolveExecutable: () =>
+              assert.fail('non-CDP executable resolution reached'),
+          }
+        ),
+        /does not support CDP/u
+      );
+    }
+  });
+
   it('spawns, waits, connects, and returns process metadata', async () => {
     temporaryDirectory = await makeDedicatedProfile();
     const calls = [];
@@ -285,6 +300,8 @@ describe('launchAndConnectRealBrowser', () => {
           profile: 'Default',
           include: ['cookies', 'bookmarks'],
           domains: ['google.com'],
+          passwordCsv: '/tmp/safari-export.csv',
+          includePaymentCards: true,
         },
       },
       {
@@ -330,6 +347,8 @@ describe('launchAndConnectRealBrowser', () => {
     assert.equal(migrateOptions.targetBrowser, 'chrome');
     assert.deepEqual(migrateOptions.include, ['cookies', 'bookmarks']);
     assert.deepEqual(migrateOptions.domains, ['google.com']);
+    assert.equal(migrateOptions.passwordCsv, '/tmp/safari-export.csv');
+    assert.equal(migrateOptions.includePaymentCards, true);
     assert.deepEqual(migrateOptions.from, {
       browser: 'chrome',
       profile: 'Default',