browser-commander 0.24.0 → 0.26.0

package/src/browser/launcher.js

@@ -17,6 +17,8 @@ import { resolveSystemBrowserExecutable } from './system-browser.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
 import { attachDownloads } from '../downloads/attach.js';
 import { launchWebDriver } from './webdriver.js';
+import { launchSafari } from './safari-launch.js';
+import { isSafariChannel } from './safari-support.js';
 import {
   loadStorageState,
   restorePlaywrightStorageState,
@@ -300,6 +302,18 @@ export async function launchBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (isSafariChannel(options.channel ?? options.browser)) {
+    validateLaunchMode({
+      engine: options.engine ?? 'playwright',
+      launch: options.launch ?? 'real',
+      attach: options.attach,
+    });
+    return await launchSafari(options, dependencies);
+  }
+  return await launchNonSafariBrowser(options, dependencies);
+}
+
+async function launchNonSafariBrowser(options, dependencies) {
   const {
     engine = 'playwright',
     launch = 'real',

package/src/browser/migration/capabilities.json

@@ -0,0 +1,117 @@
+{
+  "schemaVersion": 1,
+  "classes": [
+    "cookies",
+    "bookmarks",
+    "history",
+    "passwords",
+    "preferences",
+    "extensions",
+    "localStorage",
+    "indexedDB",
+    "sessionStorage",
+    "autofill",
+    "paymentCards",
+    "searchEngines",
+    "siteSettings",
+    "openTabs",
+    "downloads",
+    "readingList",
+    "clientCertificates",
+    "passkeys"
+  ],
+  "sourceFamilies": ["chromium", "firefox", "safari"],
+  "targetFamilies": ["chromium", "firefox", "webkit"],
+  "imports": {
+    "chromium": {
+      "chromium": [
+        "seed",
+        "copy",
+        "snapshot",
+        "rekey",
+        "copy",
+        "copy",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "consent/unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "non-exportable"
+      ]
+    },
+    "firefox": {
+      "chromium": [
+        "seed",
+        "translate",
+        "translate",
+        "NSS/rekey",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "consent/unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "non-exportable"
+      ]
+    },
+    "safari": {
+      "chromium": [
+        "seed",
+        "translate",
+        "translate",
+        "CSV/rekey",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "consent/unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "unsupported",
+        "non-exportable"
+      ]
+    }
+  },
+  "wholeProfileMigration": {
+    "chromium": "not implemented",
+    "firefox": "not implemented",
+    "webkit": "not implemented"
+  },
+  "pendingClasses": [
+    "localStorage",
+    "indexedDB",
+    "sessionStorage",
+    "autofill",
+    "paymentCards",
+    "searchEngines",
+    "siteSettings",
+    "openTabs",
+    "downloads",
+    "readingList",
+    "clientCertificates"
+  ],
+  "installedBrowserLaunch": {
+    "chromium": "CDP",
+    "firefox": "explicit WebDriver setup",
+    "safari": "explicit safaridriver setup",
+    "detection": "unsupported"
+  }
+}

package/src/browser/migration/chromium-history.sql

@@ -0,0 +1,22 @@
+-- Core tables match Chromium History schema 70 (compatible version 16).
+-- Chromium initializes remaining ancillary tables when it opens the profile.
+CREATE TABLE meta (key LONGVARCHAR NOT NULL UNIQUE PRIMARY KEY, value LONGVARCHAR);
+INSERT INTO meta VALUES ('version', '70'), ('last_compatible_version', '16');
+CREATE TABLE urls (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, url LONGVARCHAR, title LONGVARCHAR,
+  visit_count INTEGER DEFAULT 0 NOT NULL, typed_count INTEGER DEFAULT 0 NOT NULL,
+  last_visit_time INTEGER DEFAULT 0 NOT NULL, hidden INTEGER DEFAULT 0 NOT NULL
+);
+CREATE TABLE visits (
+  id INTEGER PRIMARY KEY AUTOINCREMENT, url INTEGER NOT NULL,
+  visit_time INTEGER NOT NULL, from_visit INTEGER DEFAULT 0,
+  external_referrer_url TEXT, transition INTEGER DEFAULT 0 NOT NULL,
+  segment_id INTEGER DEFAULT 0, visit_duration INTEGER DEFAULT 0 NOT NULL,
+  incremented_omnibox_typed_score BOOLEAN DEFAULT FALSE NOT NULL,
+  opener_visit INTEGER DEFAULT 0, originator_cache_guid TEXT DEFAULT '',
+  originator_visit_id INTEGER DEFAULT 0, originator_from_visit INTEGER DEFAULT 0,
+  originator_opener_visit INTEGER DEFAULT 0, is_known_to_sync BOOLEAN DEFAULT FALSE NOT NULL,
+  consider_for_ntp_most_visited BOOLEAN DEFAULT FALSE NOT NULL,
+  visited_link_id INTEGER DEFAULT 0 NOT NULL, app_id TEXT
+);
+CREATE TABLE visit_source (id INTEGER PRIMARY KEY, source INTEGER NOT NULL);

package/src/browser/migration/chromium-writers.js

@@ -0,0 +1,85 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { openSqliteDatabase } from '../browser-cookie-database.js';
+
+export async function writeChromiumBookmarks(targetProfileDir, entries) {
+  let id = 3;
+  let count = 0;
+  function convert(node) {
+    const result = {
+      id: String(++id),
+      date_added: '13300000000000000',
+      name: node.name,
+      type: node.type,
+    };
+    if (node.type === 'url') {
+      count += 1;
+      result.url = node.url;
+    } else {
+      result.date_modified = result.date_added;
+      result.children = (node.children ?? []).map(convert);
+    }
+    return result;
+  }
+  const roots = Object.fromEntries(
+    ['bookmark_bar', 'other', 'synced'].map((name, index) => [
+      name,
+      {
+        id: String(index + 1),
+        name,
+        type: 'folder',
+        date_added: '13300000000000000',
+        date_modified: '13300000000000000',
+        children: name === 'other' ? entries.map(convert) : [],
+      },
+    ])
+  );
+  await mkdir(targetProfileDir, { recursive: true });
+  await writeFile(
+    path.join(targetProfileDir, 'Bookmarks'),
+    JSON.stringify({ version: 1, roots })
+  );
+  return count;
+}
+
+export async function writeChromiumHistory(targetProfileDir, entries) {
+  await mkdir(targetProfileDir, { recursive: true });
+  const db = await openSqliteDatabase(path.join(targetProfileDir, 'History'));
+  try {
+    db.exec(
+      await readFile(new URL('./chromium-history.sql', import.meta.url), 'utf8')
+    );
+    const urls = new Map();
+    const insertUrl = db.prepare(
+      'INSERT INTO urls (url,title,visit_count,last_visit_time) VALUES (?,?,0,0)'
+    );
+    const updateUrl = db.prepare(
+      'UPDATE urls SET title=?, visit_count=visit_count+1,last_visit_time=max(last_visit_time,?) WHERE id=?'
+    );
+    const insertVisit = db.prepare(
+      'INSERT INTO visits (url,visit_time) VALUES (?,?)'
+    );
+    db.exec('BEGIN');
+    try {
+      for (const entry of entries) {
+        if (!urls.has(entry.url)) {
+          urls.set(
+            entry.url,
+            insertUrl.run(entry.url, entry.title).lastInsertRowid
+          );
+        }
+        const id = urls.get(entry.url);
+        const time = BigInt(entry.time) + 11644473600000000n;
+        updateUrl.run(entry.title, time, id);
+        insertVisit.run(id, time);
+      }
+      db.exec('COMMIT');
+    } catch (error) {
+      db.exec('ROLLBACK');
+      throw error;
+    }
+  } finally {
+    db.close();
+  }
+  return entries.length;
+}

package/src/browser/migration/cookies.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 
 import { pathExists } from './fs-utils.js';
+import { matchesDomains } from './domains.js';
 
 import { readBrowserCookies } from '../browser-cookies.js';
 
@@ -130,7 +131,9 @@ export async function migrateCookies({
       );
     }
   }
-  const cookies = [...seen.values()];
+  const cookies = [...seen.values()].filter((cookie) =>
+    matchesDomains(cookie.domain, domains)
+  );
 
   const skipped = [];
   for (const cookie of cookies) {

package/src/browser/migration/data-classes.js

@@ -0,0 +1,68 @@
+/** Explicit reports for selected classes without a native target writer. */
+export const ADDITIONAL_DATA_CLASSES = Object.freeze([
+  'localStorage',
+  'indexedDB',
+  'sessionStorage',
+  'autofill',
+  'paymentCards',
+  'searchEngines',
+  'siteSettings',
+  'openTabs',
+  'downloads',
+  'readingList',
+  'clientCertificates',
+  'passkeys',
+]);
+
+export function reportAdditionalClasses({
+  selected,
+  profileDir,
+  includePaymentCards,
+}) {
+  return ADDITIONAL_DATA_CLASSES.filter((type) => selected.has(type)).flatMap(
+    (type) => reportAdditionalClass({ type, profileDir, includePaymentCards })
+  );
+}
+
+export function reportAdditionalClass({
+  type,
+  profileDir,
+  includePaymentCards,
+}) {
+  const entry = (item, reason, detail) => ({ type, item, reason, detail });
+  if (type === 'passkeys') {
+    return ['iCloud Keychain', 'Google Password Manager', 'Windows Hello'].map(
+      (provider) =>
+        entry(
+          provider,
+          'passkey-not-exportable',
+          `${provider} private keys cannot be exported by copying browser profile files. Provider-authorized transfer may be available separately. Sign in once with the platform passkey in a dedicated persistent profile and retain its session.`
+        )
+    );
+  }
+  if (type === 'paymentCards' && !includePaymentCards) {
+    return [
+      entry(
+        profileDir,
+        'payment-card-consent-required',
+        'Payment cards require includePaymentCards=true (Python/Rust: include_payment_cards; CLI: --include-payment-cards). Selecting the class alone does not grant consent.'
+      ),
+    ];
+  }
+  if (type === 'clientCertificates') {
+    return [
+      entry(
+        profileDir,
+        'client-certificates-os-export-required',
+        'Client certificate private keys require an authorized export from the OS or NSS store. Hardware-backed or non-exportable keys cannot be copied from browser profile files.'
+      ),
+    ];
+  }
+  return [
+    entry(
+      profileDir,
+      'data-class-not-supported',
+      `A native source reader and compatible target writer for ${type} are not implemented; no data was copied.`
+    ),
+  ];
+}

package/src/browser/migration/domains.js

@@ -0,0 +1,32 @@
+/** Site filters match a host or its subdomains, never an unrelated suffix. */
+export function matchesDomains(value, domains) {
+  if (!domains?.length) {
+    return true;
+  }
+  let host;
+  try {
+    host = value.includes('://') ? new URL(value).hostname : value;
+  } catch {
+    return false;
+  }
+  host = host.replace(/^\./, '').toLowerCase().replace(/\.$/, '');
+  return domains.some((domain) => {
+    const filter = domain.replace(/^\./, '').toLowerCase().replace(/\.$/, '');
+    return host === filter || host.endsWith(`.${filter}`);
+  });
+}
+
+export function validateDomains(domains) {
+  if (domains === undefined) {
+    return;
+  }
+  if (
+    !Array.isArray(domains) ||
+    domains.some(
+      (domain) =>
+        typeof domain !== 'string' || !domain || /[\s/:]/u.test(domain)
+    )
+  ) {
+    throw new TypeError('domains must be an array of host names');
+  }
+}

package/src/browser/migration/firefox-history.js

@@ -0,0 +1,106 @@
+import { matchesDomains } from './domains.js';
+import { profileFileIfPresent } from './fs-utils.js';
+import { readDatabaseSnapshot } from './sqlite-snapshot.js';
+import { writeChromiumHistory } from './chromium-writers.js';
+import { preserveIntegerPrecision } from '../browser-cookie-database.js';
+
+/** Translate individual Firefox visits using a consistent read-only snapshot. */
+export async function migrateFirefoxHistory({
+  profileDir,
+  targetProfileDir,
+  domains,
+}) {
+  const sourcePath = await profileFileIfPresent(profileDir, 'places.sqlite');
+  const entry = (reason, detail, item = 'places.sqlite') => ({
+    type: 'history',
+    item,
+    reason,
+    detail,
+  });
+  if (!sourcePath) {
+    return { migrated: 0, skipped: [entry('source-missing')], warnings: [] };
+  }
+  const rows = await readDatabaseSnapshot({
+    sourcePath,
+    read: (db) => {
+      for (const [table, required] of [
+        ['moz_places', ['id', 'url', 'title']],
+        ['moz_historyvisits', ['id', 'place_id', 'visit_date']],
+      ]) {
+        const columns = new Set(
+          db
+            .prepare(`PRAGMA table_info(${table})`)
+            .all()
+            .map(({ name }) => name)
+        );
+        if (!required.every((name) => columns.has(name))) {
+          return null;
+        }
+      }
+      return preserveIntegerPrecision(
+        db.prepare(
+          'SELECT p.url,p.title,v.id,v.visit_date AS time FROM moz_historyvisits v JOIN moz_places p ON v.place_id=p.id ORDER BY v.visit_date,v.id'
+        )
+      ).all();
+    },
+  });
+  if (rows === null) {
+    return {
+      migrated: 0,
+      skipped: [
+        entry(
+          'source-format-unsupported',
+          'Firefox history requires moz_places and moz_historyvisits with URL, title and integer visit dates; no target was written.'
+        ),
+      ],
+      warnings: [],
+    };
+  }
+  const skipped = [];
+  const visits = [];
+  for (const row of rows) {
+    if (typeof row.url !== 'string' || !row.url) {
+      skipped.push(
+        entry(
+          'invalid-history-url',
+          'The visit URL is not a nonempty string.',
+          `places.sqlite visit ${row.id}`
+        )
+      );
+      continue;
+    }
+    if (!matchesDomains(row.url, domains)) {
+      continue;
+    }
+    if (
+      typeof row.time !== 'bigint' ||
+      row.time < -11644473600000000n ||
+      row.time > 9211727563254775807n
+    ) {
+      skipped.push(
+        entry(
+          'invalid-history-timestamp',
+          'The visit date is not an integer representable in the target history format.',
+          `places.sqlite visit ${row.id}`
+        )
+      );
+      continue;
+    }
+    visits.push({ url: row.url, title: row.title ?? '', time: row.time });
+  }
+  const migrated = visits.length
+    ? await writeChromiumHistory(targetProfileDir, visits)
+    : 0;
+  return {
+    migrated,
+    skipped,
+    warnings: migrated
+      ? [
+          entry(
+            'firefox-history-metadata-not-translated',
+            'URL/title and visit dates were translated; Firefox transition types, referring visits and sync metadata were not copied.'
+          ),
+        ]
+      : [],
+  };
+}

package/src/browser/migration/firefox.js

@@ -1,9 +1,10 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { matchesDomains } from './domains.js';
 import { profileFileIfPresent } from './fs-utils.js';
 
 import { openSqliteDatabase } from '../browser-cookie-database.js';
-import { mapFirefoxCookieRows } from '../browser-cookies.js';
+import { mapFirefoxCookieRows, readFirefoxRows } from '../browser-cookies.js';
 import { readDatabaseSnapshot } from './sqlite-snapshot.js';
 import { encryptChromiumValue } from './chromium-crypto.js';
 import { firefoxBookmarksToChrome } from './firefox-bookmarks.js';
@@ -24,8 +25,8 @@ import {
  *   them over CDP.
  * - **bookmarks:** read from `places.sqlite` (`moz_bookmarks` + `moz_places`)
  *   and converted to Chrome's `Bookmarks` JSON.
- * - **history:** counted from `places.sqlite` and reported; it is not written,
- *   because Chrome's `History` schema is incompatible with Firefox's.
+ * - **history:** translated from `moz_historyvisits` into Chrome's `History`,
+ *   preserving individual visit dates and reporting untranslated metadata.
  * - **passwords:** decrypted from `logins.json` with the NSS key in `key4.db`
  *   and re-encrypted into a Chrome `Login Data`. When a primary password is set
  *   and not supplied, they are reported as `primary-password-set`.
@@ -102,20 +103,11 @@ export async function readFirefoxCookies({ profileDir, domains }) {
   return readDatabaseSnapshot({
     sourcePath: cookiePath,
     read: (db) => {
-      const rows = db
-        .prepare(
-          `SELECT name, value, host, path, expiry, isSecure, isHttpOnly, sameSite
-             FROM moz_cookies ORDER BY host, name, path`
-        )
-        .all();
+      const rows = readFirefoxRows(db);
       // The installed-browser cookie reader owns the row → cookie mapping, so
       // a migrated cookie and an imported one always have the same shape.
       return mapFirefoxCookieRows(
-        rows.filter((row) =>
-          Array.isArray(domains) && domains.length > 0
-            ? domains.some((domain) => (row.host ?? '').includes(domain))
-            : true
-        )
+        rows.filter((row) => matchesDomains(row.host ?? '', domains))
       );
     },
   });
@@ -228,6 +220,7 @@ export async function migrateFirefoxPasswords({
   targetKey,
   targetPrefix = platform === 'win32' ? 'v10' : 'v11',
   primaryPassword = Buffer.alloc(0),
+  domains,
 }) {
   const loginsPath = await profileFileIfPresent(profileDir, 'logins.json');
   const key4Path = await profileFileIfPresent(profileDir, 'key4.db');
@@ -271,6 +264,9 @@ export async function migrateFirefoxPasswords({
   const decrypted = [];
   const skipped = [];
   for (const login of logins) {
+    if (!matchesDomains(login.hostname ?? '', domains)) {
+      continue;
+    }
     try {
       decrypted.push({
         origin: login.hostname,
@@ -287,6 +283,33 @@ export async function migrateFirefoxPasswords({
     }
   }
 
+  const migrated = await writeChromiumPasswords({
+    entries: decrypted,
+    targetProfileDir,
+    platform,
+    targetKey,
+    targetPrefix,
+  });
+
+  const warnings = [];
+  if (migrated > 0) {
+    warnings.push({
+      type: 'passwords',
+      item: 'Login Data',
+      reason: 'reencrypted-for-chrome',
+      detail: `${migrated} Firefox logins were decrypted and re-encrypted into a Chrome Login Data; Chrome may re-key the store on first launch.`,
+    });
+  }
+  return { migrated, skipped, warnings };
+}
+
+export async function writeChromiumPasswords({
+  entries,
+  targetProfileDir,
+  platform,
+  targetKey,
+  targetPrefix,
+}) {
   await mkdir(targetProfileDir, { recursive: true });
   const targetPath = path.join(targetProfileDir, 'Login Data');
   const db = await openSqliteDatabase(targetPath);
@@ -301,7 +324,7 @@ export async function migrateFirefoxPasswords({
          date_last_used, date_password_modified
        ) VALUES (?, ?, '', ?, '', ?, '', ?, 0, 0, 0, 0, 0, 0, 0)`
     );
-    for (const entry of decrypted) {
+    for (const entry of entries) {
       const encrypted = encryptChromiumValue({
         plaintext: entry.password,
         key: targetKey,
@@ -321,14 +344,5 @@ export async function migrateFirefoxPasswords({
     db.close();
   }
 
-  const warnings = [];
-  if (migrated > 0) {
-    warnings.push({
-      type: 'passwords',
-      item: 'Login Data',
-      reason: 'reencrypted-for-chrome',
-      detail: `${migrated} Firefox logins were decrypted and re-encrypted into a Chrome Login Data; Chrome may re-key the store on first launch.`,
-    });
-  }
-  return { migrated, skipped, warnings };
+  return migrated;
 }