browser-commander 0.24.0 → 0.26.0

package/src/browser/migration/password-metadata.js

@@ -0,0 +1,95 @@
+import { matchesDomains } from './domains.js';
+
+/** Filter Login Data associations after pruning logins; never retain source keys. */
+export async function migratePasswordMetadata({
+  db,
+  domains,
+  rewriteValue,
+  skipped,
+  warnings,
+}) {
+  const tables = db
+    .prepare("SELECT name FROM sqlite_master WHERE type='table'")
+    .all()
+    .map((row) => row.name);
+  for (const table of ['password_notes', 'insecure_credentials']) {
+    if (tables.includes(table)) {
+      db.exec(
+        `DELETE FROM ${table} WHERE NOT EXISTS (SELECT 1 FROM logins WHERE logins.id=${table}.parent_id)`
+      );
+    }
+  }
+  if (tables.includes('password_notes')) {
+    const rows = db
+      .prepare(
+        'SELECT password_notes.rowid AS rowid,logins.origin_url,password_notes.value FROM password_notes JOIN logins ON logins.id=password_notes.parent_id'
+      )
+      .all();
+    for (const row of rows) {
+      const result = await rewriteValue(row.value, row.origin_url);
+      if (result.reason) {
+        db.prepare('DELETE FROM password_notes WHERE rowid=?').run(row.rowid);
+        skipped.push({
+          type: 'passwords',
+          item: `password_notes/${row.rowid}`,
+          ...result,
+        });
+      } else {
+        db.prepare('UPDATE password_notes SET value=? WHERE rowid=?').run(
+          result.value,
+          row.rowid
+        );
+      }
+    }
+  }
+  const syncTables = [
+    'sync_entities_metadata',
+    'sync_model_metadata',
+    'incoming_sharing_invitation_sync_entities_metadata',
+    'incoming_sharing_invitation_sync_model_metadata',
+  ];
+  for (const table of syncTables) {
+    if (tables.includes(table)) {
+      resetMetadata(db, table, 'sync-metadata-reset', warnings);
+    }
+  }
+  if (!domains?.length) {
+    return;
+  }
+  if (tables.includes('stats')) {
+    for (const row of db
+      .prepare('SELECT rowid AS rowid,origin_domain FROM stats')
+      .all()) {
+      if (!matchesDomains(row.origin_domain ?? '', domains)) {
+        db.prepare('DELETE FROM stats WHERE rowid=?').run(row.rowid);
+      }
+    }
+  }
+  const known = new Set([
+    'logins',
+    'meta',
+    'password_notes',
+    'insecure_credentials',
+    'stats',
+    ...syncTables,
+  ]);
+  for (const table of tables) {
+    if (!known.has(table) && !table.startsWith('sqlite_')) {
+      resetMetadata(db, table, 'unsupported-password-metadata', warnings);
+    }
+  }
+}
+
+function resetMetadata(db, table, reason, warnings) {
+  // Only the identifier comes from the database; quote it rather than execute it.
+  const quoted = `"${table.replaceAll('"', '""')}"`;
+  const { changes } = db.prepare(`DELETE FROM ${quoted}`).run();
+  if (changes) {
+    warnings.push({
+      type: 'passwords',
+      item: table,
+      reason,
+      detail: `${changes} copied metadata rows removed`,
+    });
+  }
+}

package/src/browser/migration/passwords.js

@@ -6,6 +6,8 @@ import { decryptChromiumCookie } from '../browser-cookie-crypto.js';
 import { openSqliteDatabase } from '../browser-cookie-database.js';
 import { withDatabaseSnapshot } from './sqlite-snapshot.js';
 import { encryptChromiumValue } from './chromium-crypto.js';
+import { matchesDomains } from './domains.js';
+import { migratePasswordMetadata } from './password-metadata.js';
 
 /**
  * Saved-password migration.
@@ -49,6 +51,44 @@ function hostFromOrigin(originUrl) {
   }
 }
 
+async function rewriteSecret(
+  value,
+  origin,
+  { platform, resolveSourceKey, targetKey, targetPrefix }
+) {
+  const encryptedValue = toBuffer(value);
+  if (!encryptedValue.length) {
+    return { value: encryptedValue };
+  }
+  const prefix = encryptedValue.subarray(0, 3).toString('ascii');
+  if (prefix === 'v20') {
+    return { reason: 'app-bound-v20' };
+  }
+  if (prefix !== 'v10' && prefix !== 'v11') {
+    return { reason: 'unsupported-encryption' };
+  }
+  let plaintext;
+  try {
+    plaintext = decryptChromiumCookie({
+      encryptedValue,
+      host: hostFromOrigin(origin),
+      databaseVersion: 0,
+      platform,
+      key: await resolveSourceKey(prefix),
+    });
+  } catch (error) {
+    return { reason: 'decrypt-failed', detail: error.message };
+  }
+  return {
+    value: encryptChromiumValue({
+      plaintext,
+      key: targetKey,
+      platform,
+      prefix: targetPrefix,
+    }),
+  };
+}
+
 /**
  * Migrate saved passwords into the target profile's `Login Data`.
  *
@@ -69,6 +109,7 @@ export async function migratePasswords({
   resolveSourceKey,
   targetKey,
   targetPrefix = platform === 'win32' ? 'v10' : 'v11',
+  domains,
 }) {
   const sourcePath = path.join(sourceProfileDir, 'Login Data');
   if (!(await pathExists(sourcePath))) {
@@ -112,56 +153,52 @@ export async function migratePasswords({
         const update = db.prepare(
           'UPDATE logins SET password_value = ? WHERE rowid = ?'
         );
+        const remove = db.prepare('DELETE FROM logins WHERE rowid = ?');
+        const skip = (row, reason, detail) => {
+          remove.run(row.rowid);
+          skipped.push({
+            type: 'passwords',
+            item: row.origin_url ?? '(unknown)',
+            reason,
+            ...(detail ? { detail } : {}),
+          });
+        };
         for (const row of rows) {
-          const encryptedValue = toBuffer(row.password_value);
-          if (encryptedValue.length === 0) {
+          if (!matchesDomains(row.origin_url ?? '', domains)) {
+            remove.run(row.rowid);
             continue;
           }
-          const prefix = encryptedValue.subarray(0, 3).toString('ascii');
-          if (prefix === 'v20') {
-            skipped.push({
-              type: 'passwords',
-              item: row.origin_url ?? '(unknown)',
-              reason: 'app-bound-v20',
-            });
-            continue;
-          }
-          if (prefix !== 'v10' && prefix !== 'v11') {
-            skipped.push({
-              type: 'passwords',
-              item: row.origin_url ?? '(unknown)',
-              reason: 'unsupported-encryption',
-            });
-            continue;
-          }
-          let plaintext;
-          try {
-            const key = await resolveSourceKey(prefix);
-            plaintext = decryptChromiumCookie({
-              encryptedValue,
-              host: hostFromOrigin(row.origin_url),
-              databaseVersion: 0,
-              platform,
-              key,
-            });
-          } catch (error) {
-            skipped.push({
-              type: 'passwords',
-              item: row.origin_url ?? '(unknown)',
-              reason: 'decrypt-failed',
-              detail: error.message,
-            });
+          const encryptedValue = toBuffer(row.password_value);
+          if (encryptedValue.length === 0) {
             continue;
           }
-          const reencrypted = encryptChromiumValue({
-            plaintext,
-            key: targetKey,
+          const result = await rewriteSecret(encryptedValue, row.origin_url, {
             platform,
-            prefix: targetPrefix,
+            resolveSourceKey,
+            targetKey,
+            targetPrefix,
           });
-          update.run(reencrypted, row.rowid);
+          if (result.reason) {
+            skip(row, result.reason, result.detail);
+            continue;
+          }
+          update.run(result.value, row.rowid);
           migrated += 1;
         }
+        await migratePasswordMetadata({
+          db,
+          domains,
+          skipped,
+          warnings,
+          rewriteValue: (value, origin) =>
+            rewriteSecret(value, origin, {
+              platform,
+              resolveSourceKey,
+              targetKey,
+              targetPrefix,
+            }),
+        });
+        db.exec('VACUUM');
       } finally {
         db.close();
       }

package/src/browser/migration/safari-import.js

@@ -0,0 +1,100 @@
+import path from 'node:path';
+import { findSafariFile } from '../safari-access.js';
+import {
+  readSafariBookmarks,
+  readSafariHistory,
+  readSafariPasswords,
+} from './safari.js';
+import {
+  writeChromiumBookmarks,
+  writeChromiumHistory,
+} from './chromium-writers.js';
+import { writeChromiumPasswords } from './firefox.js';
+
+function findStore(profileDir, name, legacyDir) {
+  return findSafariFile([
+    path.join(profileDir, 'Safari', name),
+    path.join(profileDir, name),
+    ...(legacyDir ? [path.join(legacyDir, name)] : []),
+  ]);
+}
+
+export async function migrateSafariClass({
+  type,
+  profileDir,
+  targetProfileDir,
+  domains,
+  passwordCsv,
+  passwordKeys,
+  platform,
+  legacyDir,
+}) {
+  const skipped = (reason, detail) => ({
+    migrated: 0,
+    skipped: [
+      { type, item: profileDir, reason, ...(detail ? { detail } : {}) },
+    ],
+    warnings: [],
+  });
+  if (type === 'preferences' || type === 'extensions') {
+    return skipped(
+      'safari-class-not-supported',
+      'Safari preferences and extensions do not use Chromium formats.'
+    );
+  }
+  if (type === 'passwords') {
+    if (!passwordCsv) {
+      return skipped(
+        'safari-password-export-required',
+        'Export Passwords from Safari or the Passwords app to CSV, then supply passwordCsv (CLI: --password-csv).'
+      );
+    }
+    const entries = await readSafariPasswords(passwordCsv, domains);
+    if (!passwordKeys?.targetKey) {
+      return skipped(
+        'target-key-unavailable',
+        'Supply the dedicated target profile encryption key; no plaintext passwords are written.'
+      );
+    }
+    const migrated = await writeChromiumPasswords({
+      entries,
+      targetProfileDir,
+      platform,
+      ...passwordKeys,
+    });
+    return { migrated, skipped: [], warnings: [] };
+  }
+  const filename = await findStore(
+    profileDir,
+    type === 'bookmarks' ? 'Bookmarks.plist' : 'History.db',
+    legacyDir
+  );
+  if (!filename) {
+    return skipped('source-missing');
+  }
+  if (type === 'bookmarks') {
+    const entries = await readSafariBookmarks(filename);
+    const hasReadingList = (nodes) =>
+      nodes.some(
+        (node) => node.readingList || hasReadingList(node.children ?? [])
+      );
+    const migrated = await writeChromiumBookmarks(targetProfileDir, entries);
+    const warnings = hasReadingList(entries)
+      ? [
+          {
+            type,
+            item: filename,
+            reason: 'safari-reading-list-translated',
+            detail:
+              'Reading-list URLs become bookmarks; read status and preview metadata are not translated.',
+          },
+        ]
+      : [];
+    return { migrated, skipped: [], warnings };
+  }
+  const migrated = await writeChromiumHistory(
+    targetProfileDir,
+    await readSafariHistory(filename, domains)
+  );
+  return { migrated, skipped: [], warnings: [] };
+}

package/src/browser/migration/safari.js

@@ -0,0 +1,110 @@
+import { open, readFile } from 'node:fs/promises';
+import * as bplist from 'bplist-parser';
+import * as plist from 'plist';
+import { parse } from 'csv-parse/sync';
+import { matchesDomains } from './domains.js';
+import { readDatabaseSnapshot } from './sqlite-snapshot.js';
+
+import { withSafariAccess } from '../safari-access.js';
+export { withSafariAccess } from '../safari-access.js';
+
+export function readSafariPlist(filename) {
+  return withSafariAccess(filename, async () => {
+    const bytes = await readFile(filename);
+    return bytes.subarray(0, 8).toString() === 'bplist00'
+      ? bplist.parseBuffer(bytes)[0]
+      : plist.parse(bytes.toString('utf8'));
+  });
+}
+
+/** Canonical bookmark tree, including nested reading-list entries. */
+export async function readSafariBookmarks(filename) {
+  const document = await readSafariPlist(filename);
+  function convert(node, readingList = false) {
+    const isReadingList =
+      readingList ||
+      node.Title === 'com.apple.ReadingList' ||
+      Boolean(node.ReadingList);
+    if (node.WebBookmarkType === 'WebBookmarkTypeLeaf') {
+      if (!node.URLString) {
+        return null;
+      }
+      return {
+        type: 'url',
+        name: node.URIDictionary?.title ?? node.Title ?? node.URLString,
+        url: node.URLString,
+        readingList: isReadingList,
+      };
+    }
+    return {
+      type: 'folder',
+      name: isReadingList ? 'Reading List' : (node.Title ?? ''),
+      children: (node.Children ?? [])
+        .map((child) => convert(child, isReadingList))
+        .filter(Boolean),
+    };
+  }
+  return (document.Children ?? []).map((node) => convert(node)).filter(Boolean);
+}
+
+/** All visits, in Unix microseconds; the source is read through online backup. */
+export function readSafariHistory(filename, domains) {
+  return withSafariAccess(filename, async () => {
+    // Surface an OS access error before SQLite wraps it as SQLITE_CANTOPEN.
+    const file = await open(filename, 'r');
+    await file.close();
+    return readDatabaseSnapshot({
+      sourcePath: filename,
+      read: (db) =>
+        db
+          .prepare(
+            `SELECT i.url, v.title, v.visit_time FROM history_items i
+       JOIN history_visits v ON i.id = v.history_item ORDER BY v.visit_time, v.id`
+          )
+          .all()
+          .filter((row) => matchesDomains(row.url, domains))
+          .map((row) => ({
+            url: row.url,
+            title: row.title ?? '',
+            time: Math.round((row.visit_time + 978307200) * 1000000),
+          })),
+    });
+  });
+}
+
+/** Only an explicitly supplied Safari/Passwords export is read. */
+export async function readSafariPasswords(filename, domains) {
+  const rows = parse(await readFile(filename), {
+    columns: (columns) => {
+      if (
+        !['URL', 'Username', 'Password'].every((column) =>
+          columns.includes(column)
+        )
+      ) {
+        throw new TypeError(
+          'Safari password CSV must have URL, Username and Password columns'
+        );
+      }
+      return columns;
+    },
+    bom: true,
+    skip_empty_lines: true,
+  });
+  return rows
+    .filter((row) => row.URL && matchesDomains(row.URL, domains))
+    .map((row) => {
+      if (
+        typeof row.Username !== 'string' ||
+        typeof row.Password !== 'string'
+      ) {
+        throw new TypeError(
+          'Safari password CSV must have URL, Username and Password columns'
+        );
+      }
+      return {
+        origin: row.URL,
+        username: row.Username,
+        password: row.Password,
+      };
+    });
+}

package/src/browser/migration/sqlite-snapshot.js

@@ -1,4 +1,4 @@
-import { copyFile, mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { pathExists } from './fs-utils.js';
@@ -11,49 +11,12 @@ import { openSqliteDatabase } from '../browser-cookie-database.js';
  * Read a Chromium SQLite database (History, Top Sites, Login Data, Web Data)
  * while the source browser is running, without ever writing to the source.
  *
- * Chrome keeps these databases open in WAL mode and, on Windows, holds a share
- * lock that stops another process from opening the file at all. Two techniques
- * cover both cases:
- *
- * 1. The SQLite Online Backup API (`better-sqlite3`'s `.backup()`), which
- *    copies a transactionally consistent snapshot even while the source is
- *    being written. This is the same mechanism `browser-cookie-database.js`
- *    relies on for a stable read, and SQLite documents it as the correct way
- *    to snapshot a live database
- *    (https://www.sqlite.org/backup.html).
- * 2. When the source cannot be opened at all (a Windows exclusive lock), the
- *    file and its `-wal`/`-journal` sidecars are copied to a temporary
- *    directory and the copy is opened instead. Copying the sidecars keeps the
- *    committed-but-not-checkpointed pages, so the copy is consistent.
- *
- * Both paths open the source with `readOnly`, so nothing is written back.
+ * SQLite online backup includes committed WAL data without writing to the
+ * source. If a sharing/exclusive lock prevents backup, callers receive guidance
+ * to close the browser or supply a consistent snapshot. A sequential copy of a
+ * live database and its sidecars cannot guarantee consistency.
  */
 
-const SQLITE_SIDECARS = ['-wal', '-shm', '-journal'];
-
-/**
- * Copy a SQLite file and its sidecars into a temporary directory.
- *
- * @param {string} sourcePath
- * @returns {Promise<{snapshotPath: string, cleanup: function(): Promise<void>}>}
- */
-async function copyDatabaseFiles(sourcePath) {
-  const dir = await mkdtemp(path.join(os.tmpdir(), 'browser-commander-snap-'));
-  const base = path.basename(sourcePath);
-  const snapshotPath = path.join(dir, base);
-  await copyFile(sourcePath, snapshotPath);
-  for (const suffix of SQLITE_SIDECARS) {
-    const sidecar = `${sourcePath}${suffix}`;
-    if (await pathExists(sidecar)) {
-      await copyFile(sidecar, `${snapshotPath}${suffix}`);
-    }
-  }
-  return {
-    snapshotPath,
-    cleanup: () => rm(dir, { recursive: true, force: true, maxRetries: 3 }),
-  };
-}
-
 /**
  * Produce a consistent, read-only snapshot copy of a live Chromium database in
  * a temporary directory, then hand its path to a reader. The snapshot is always
@@ -74,7 +37,6 @@ export async function withDatabaseSnapshot({ sourcePath, read }) {
   const cleanupDir = () =>
     rm(dir, { recursive: true, force: true, maxRetries: 3 });
 
-  let copyFallback;
   try {
     // The backup API needs to open the source. It opens read-only, so nothing
     // is written to the user's real database.
@@ -83,31 +45,35 @@ export async function withDatabaseSnapshot({ sourcePath, read }) {
       source = new BetterSqlite3(sourcePath, {
         readonly: true,
         fileMustExist: true,
+        timeout: 1000,
       });
-    } catch {
-      source = null;
-    }
-    if (source) {
-      try {
-        await source.backup(snapshotPath);
-      } finally {
-        source.close();
-      }
-    } else {
-      // The source is locked exclusively (Windows); fall back to copying the
-      // file and its sidecars, then read that copy.
-      await cleanupDir();
-      copyFallback = await copyDatabaseFiles(sourcePath);
+      // Detect an exclusive lock before better-sqlite3's initial zero-page
+      // transfer can mistake SQLITE_BUSY for an empty completed backup.
+      source.pragma('schema_version');
+      let remaining = Infinity;
+      let lastProgress = Date.now();
+      await source.backup(snapshotPath, {
+        progress: ({ remainingPages }) => {
+          if (remainingPages < remaining) {
+            lastProgress = Date.now();
+          } else if (Date.now() - lastProgress >= 1000) {
+            throw new Error('SQLite backup made no progress');
+          }
+          remaining = remainingPages;
+          return 256;
+        },
+      });
+    } catch (cause) {
+      throw new Error(
+        `Consistent SQLite snapshot unavailable for ${sourcePath}; close the source browser and retry, or supply a consistent read-only snapshot. ${cause.message}`,
+        { cause }
+      );
+    } finally {
+      source?.close();
     }
-
-    const readPath = copyFallback?.snapshotPath ?? snapshotPath;
-    return await read(readPath);
+    return await read(snapshotPath);
   } finally {
-    if (copyFallback) {
-      await copyFallback.cleanup();
-    } else {
-      await cleanupDir();
-    }
+    await cleanupDir();
   }
 }
 

package/src/browser/migration/validation.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { physicalPath } from '../browser-profile-files.js';
+import { browserFamily } from '../browser-sources.js';
+import { assertDedicatedUserDataDir } from '../system-browser.js';
+import { validateDomains } from './domains.js';
+
+export function validateMigrationOptions({
+  include,
+  domains,
+  targetBrowser,
+  to,
+  platform,
+  homeDir,
+  environment,
+  classes,
+  includePaymentCards = false,
+}) {
+  if (typeof includePaymentCards !== 'boolean') {
+    throw new TypeError('includePaymentCards must be a boolean');
+  }
+  if (
+    !Array.isArray(include) ||
+    include.some((type) => !classes.includes(type))
+  ) {
+    throw new TypeError(
+      `include must contain supported data classes: ${classes.join(', ')}`
+    );
+  }
+  validateDomains(domains);
+  if (targetBrowser && browserFamily(targetBrowser) !== 'chromium') {
+    throw new TypeError(
+      `Migration target ${targetBrowser} does not yet have a supported target file writer`
+    );
+  }
+  assertDedicatedUserDataDir(to, { platform, homeDir, environment });
+}
+
+export function validateMigrationPaths(source, target) {
+  const sourcePath = physicalPath(source);
+  const targetPath = physicalPath(target);
+  const within = (parent, child) =>
+    child === parent || child.startsWith(`${parent}${path.sep}`);
+  if (within(sourcePath, targetPath) || within(targetPath, sourcePath)) {
+    throw new TypeError(
+      'Migration source and target directories must not overlap'
+    );
+  }
+}

package/src/browser/real-browser.js

@@ -1,5 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { findBrowserSource } from './browser-sources.js';
+import { launchSafari } from './safari-launch.js';
+import { isSafariChannel } from './safari-support.js';
 
 import { startProcess } from '../utilities/subprocess.js';
 import {
@@ -408,12 +411,19 @@ async function spawnOnFreePort({
 /** Reject a launch request before anything touches the disk. */
 function validateLaunchRequest({
   argOptions,
+  channel,
   userDataDir,
   remoteDebuggingPort,
   endpoint,
   attach,
   migrateFrom,
 }) {
+  const source = findBrowserSource(channel);
+  if (source && source.family !== 'chromium') {
+    throw new Error(
+      `${channel} does not support CDP; use its documented WebDriver setup when available`
+    );
+  }
   if (endpoint) {
     throw new Error(
       'launchAndConnectRealBrowser creates its own endpoint; use connectBrowser to attach to an existing endpoint'
@@ -507,13 +517,16 @@ async function runPreLaunchMigration({
   if (!migrateFrom) {
     return { migration: undefined, migratedCookies: [] };
   }
-  const { include, domains, ...from } = migrateFrom;
+  const { include, domains, passwordCsv, includePaymentCards, ...from } =
+    migrateFrom;
   try {
     const report = await migrate({
       from,
       to: path.join(userDataDir, 'Default'),
       include,
       domains,
+      passwordCsv,
+      includePaymentCards,
       targetBrowser: channel,
     });
     const { cookies, ...migration } = report;
@@ -552,6 +565,9 @@ export async function launchAndConnectRealBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (isSafariChannel(options.channel ?? options.browser)) {
+    return launchSafari(options, dependencies);
+  }
   const {
     engine = 'playwright',
     channel = 'chrome',
@@ -588,6 +604,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
   };
   validateLaunchRequest({
     argOptions,
+    channel,
     userDataDir: requestedUserDataDir,
     remoteDebuggingPort,
     endpoint: cdpEndpoint || wsEndpoint,