browser-commander 0.20.0 → 0.21.0

package/src/browser/migration/history.js

@@ -0,0 +1,103 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists } from './fs-utils.js';
+
+import { withDatabaseSnapshot } from './sqlite-snapshot.js';
+
+/**
+ * History and Top Sites migration.
+ *
+ * Chrome keeps browsing history in the `History` SQLite database and the
+ * new-tab-page thumbnails/most-visited list in `Top Sites`. Both are open and
+ * write-locked while Chrome runs, so a migration takes a consistent snapshot
+ * through the SQLite Online Backup API (see `sqlite-snapshot.js`) and writes
+ * the snapshot into the target profile. The source is opened read-only and is
+ * never modified.
+ *
+ * The snapshot is copied verbatim rather than rebuilt row by row: `History`
+ * carries interdependent tables (`urls`, `visits`, `visit_source`,
+ * `segments`, ...) whose foreign keys must stay consistent, and the backup API
+ * already guarantees a point-in-time consistent copy.
+ */
+
+function snapshotInto({ sourcePath, targetPath }) {
+  return withDatabaseSnapshot({
+    sourcePath,
+    read: async (snapshotPath) => {
+      const { copyFile } = await import('node:fs/promises');
+      await copyFile(snapshotPath, targetPath);
+      // Best-effort URL count for the report.
+      try {
+        const { openSqliteDatabase } =
+          await import('../browser-cookie-database.js');
+        const db = await openSqliteDatabase(targetPath, { readOnly: true });
+        try {
+          const row = db.prepare('SELECT COUNT(*) AS c FROM urls').get();
+          return Number(row?.c ?? 0);
+        } finally {
+          db.close();
+        }
+      } catch {
+        return null;
+      }
+    },
+  });
+}
+
+/**
+ * Migrate History (and Top Sites) into the target profile.
+ *
+ * @param {Object} options
+ * @param {string} options.sourceProfileDir
+ * @param {string} options.targetProfileDir
+ * @returns {Promise<{migrated: number, skipped: Array, warnings: Array}>}
+ */
+export async function migrateHistory({ sourceProfileDir, targetProfileDir }) {
+  const skipped = [];
+  const warnings = [];
+  await mkdir(targetProfileDir, { recursive: true });
+
+  const historySource = path.join(sourceProfileDir, 'History');
+  let urlCount = 0;
+  let migratedDatabases = 0;
+  if (await pathExists(historySource)) {
+    const count = await snapshotInto({
+      sourcePath: historySource,
+      targetPath: path.join(targetProfileDir, 'History'),
+    });
+    urlCount = count ?? 0;
+    migratedDatabases += 1;
+  } else {
+    skipped.push({
+      type: 'history',
+      item: 'History',
+      reason: 'source-missing',
+    });
+  }
+
+  const topSitesSource = path.join(sourceProfileDir, 'Top Sites');
+  if (await pathExists(topSitesSource)) {
+    await snapshotInto({
+      sourcePath: topSitesSource,
+      targetPath: path.join(targetProfileDir, 'Top Sites'),
+    });
+    migratedDatabases += 1;
+  }
+
+  // The report counts the snapshot as one migrated unit (matching the docs
+  // example `"history": 1`), and carries the URL count as a warning detail so
+  // it is visible without changing the report shape.
+  if (urlCount > 0) {
+    warnings.push({
+      type: 'history',
+      item: 'History',
+      reason: 'snapshot-copied',
+      detail: `${urlCount} history URLs copied via the SQLite backup API`,
+    });
+  }
+  return {
+    migrated: migratedDatabases > 0 ? 1 : 0,
+    skipped,
+    warnings,
+  };
+}

package/src/browser/migration/index.js

@@ -0,0 +1,307 @@
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  browserProfileRoot,
+  normalizeCookieBrowser,
+  resolveBrowserProfile,
+} from '../browser-profiles.js';
+import { migrateBookmarks } from './bookmarks.js';
+import { migrateCookies } from './cookies.js';
+import { migrateExtensions } from './extensions.js';
+import {
+  migrateFirefoxBookmarks,
+  migrateFirefoxPasswords,
+  readFirefoxCookies,
+  reportFirefoxHistory,
+} from './firefox.js';
+import { migrateHistory } from './history.js';
+import { migratePasswords } from './passwords.js';
+import { migratePreferences } from './preferences.js';
+import {
+  createSourceKeyResolver,
+  localStatePathForProfile,
+  resolveTargetKey,
+} from './os-crypt-keys.js';
+
+/**
+ * Profile migration orchestrator.
+ *
+ * Copies a person's data from a real browser profile into a dedicated target
+ * profile, one data class at a time, and returns the report shape documented in
+ * `docs/cli-and-bridge.md`. Nothing is ever written to the source profile, and
+ * every database read goes through a consistent read-only snapshot, so the
+ * migration is safe to run while the source browser is open.
+ *
+ * Cookies are returned (not written): a running Chromium re-derives its own
+ * cookie encryption, so the launcher seeds them over CDP with the existing
+ * `seedCookies` path. Every other data class is written into the target profile
+ * directory.
+ */
+
+export const ALL_DATA_CLASSES = Object.freeze([
+  'cookies',
+  'bookmarks',
+  'history',
+  'passwords',
+  'preferences',
+  'extensions',
+]);
+
+const CHROMIUM_BROWSERS = new Set(['chrome', 'chromium', 'brave', 'edge']);
+
+function emptyMigrated() {
+  return {
+    cookies: 0,
+    bookmarks: 0,
+    history: 0,
+    passwords: 0,
+    preferences: 0,
+    extensions: 0,
+  };
+}
+
+async function resolveSourceProfileDir({
+  browser,
+  profile,
+  userDataDir,
+  platform,
+  homeDir,
+  environment,
+}) {
+  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;
+  }
+  if (CHROMIUM_BROWSERS.has(browser)) {
+    const root = browserProfileRoot(browser, {
+      platform,
+      homeDir,
+      environment,
+    });
+    return path.join(root, profile ?? 'Default');
+  }
+  const resolved = await resolveBrowserProfile({
+    browser,
+    profile,
+    platform,
+    homeDir,
+    environment,
+  });
+  return resolved.path;
+}
+
+function mergeReport(report, className, fragment) {
+  report.migrated[className] += fragment.migrated ?? 0;
+  report.skipped.push(...(fragment.skipped ?? []));
+  report.warnings.push(...(fragment.warnings ?? []));
+}
+
+async function resolvePasswordKeys({
+  keys,
+  browser,
+  targetBrowser,
+  platform,
+  sourceProfileDir,
+  environment,
+}) {
+  if (keys?.targetKey) {
+    return keys;
+  }
+  if (platform !== 'darwin' && platform !== 'linux') {
+    return null;
+  }
+  const { key: targetKey, prefix: targetPrefix } = await resolveTargetKey({
+    browser: targetBrowser,
+    platform,
+    environment,
+  });
+  const resolveSourceKey = CHROMIUM_BROWSERS.has(browser)
+    ? createSourceKeyResolver({
+        browser,
+        platform,
+        localStatePath: localStatePathForProfile(sourceProfileDir),
+        environment,
+      })
+    : undefined;
+  return { targetKey, targetPrefix, resolveSourceKey };
+}
+
+/**
+ * Migrate a browser profile into a dedicated target profile directory.
+ *
+ * @param {Object} options
+ * @param {{browser: string, profile: (string|undefined), userDataDir: (string|undefined)}} options.from
+ * @param {string} options.to - Target profile directory
+ * @param {string[]} [options.include=ALL_DATA_CLASSES]
+ * @param {string[]} [options.domains] - Cookie domain filter
+ * @param {string} [options.platform=process.platform]
+ * @param {string} [options.targetBrowser] - Launching browser channel (key derivation)
+ * @param {Object} [options.keys] - Injected password keys {resolveSourceKey, targetKey, targetPrefix, primaryPassword}
+ * @param {string} [options.homeDir]
+ * @param {Object} [options.environment]
+ * @returns {Promise<{source: Object, target: string, migrated: Object, skipped: Array, warnings: Array, cookies: Object[]}>}
+ */
+export async function migrateProfile({
+  from,
+  to,
+  include = ALL_DATA_CLASSES,
+  domains,
+  platform = process.platform,
+  targetBrowser,
+  keys,
+  homeDir = os.homedir(),
+  environment = process.env,
+}) {
+  if (!from?.browser) {
+    throw new TypeError('migrateProfile requires from.browser');
+  }
+  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';
+  const sourceProfileDir = await resolveSourceProfileDir({
+    browser,
+    profile,
+    userDataDir: from.userDataDir,
+    platform,
+    homeDir,
+    environment,
+  });
+  const selected = new Set(include);
+  const report = {
+    source: { browser, profile, userDataDir: from.userDataDir ?? null },
+    target: to,
+    migrated: emptyMigrated(),
+    skipped: [],
+    warnings: [],
+    cookies: [],
+  };
+
+  if (selected.has('cookies')) {
+    if (isFirefox) {
+      const cookies = await readFirefoxCookies({
+        profileDir: sourceProfileDir,
+        domains,
+      });
+      report.cookies = cookies;
+      report.migrated.cookies = cookies.length;
+    } else {
+      const fragment = await migrateCookies({
+        browser,
+        profile,
+        sourceProfileDir,
+        domains,
+        readerOptions: { platform, homeDir, environment },
+      });
+      report.cookies = fragment.cookies;
+      report.migrated.cookies = fragment.migrated;
+      report.skipped.push(...fragment.skipped);
+      report.warnings.push(...fragment.warnings);
+    }
+  }
+
+  if (selected.has('bookmarks')) {
+    mergeReport(
+      report,
+      'bookmarks',
+      isFirefox
+        ? await migrateFirefoxBookmarks({
+            profileDir: sourceProfileDir,
+            targetProfileDir: to,
+          })
+        : await migrateBookmarks({
+            sourceProfileDir,
+            targetProfileDir: to,
+          })
+    );
+  }
+
+  if (selected.has('history')) {
+    mergeReport(
+      report,
+      'history',
+      isFirefox
+        ? await reportFirefoxHistory({ profileDir: sourceProfileDir })
+        : await migrateHistory({
+            sourceProfileDir,
+            targetProfileDir: to,
+          })
+    );
+  }
+
+  if (selected.has('preferences') && !isFirefox) {
+    mergeReport(
+      report,
+      'preferences',
+      await migratePreferences({ sourceProfileDir, targetProfileDir: to })
+    );
+  }
+
+  if (selected.has('extensions') && !isFirefox) {
+    mergeReport(
+      report,
+      'extensions',
+      await migrateExtensions({ sourceProfileDir, targetProfileDir: to })
+    );
+  }
+
+  if (selected.has('passwords')) {
+    const passwordKeys = await resolvePasswordKeys({
+      keys,
+      browser,
+      targetBrowser: targetBrowser ?? (isFirefox ? 'chrome' : browser),
+      platform,
+      sourceProfileDir,
+      environment,
+    });
+    if (!passwordKeys?.targetKey) {
+      report.skipped.push({
+        type: 'passwords',
+        item: 'Login Data',
+        reason: 'target-key-unavailable',
+      });
+      report.warnings.push({
+        type: 'passwords',
+        item: 'Login Data',
+        reason: 'target-key-unavailable',
+        detail:
+          'A target encryption key was not available (on Windows the launcher must generate one and write it into the target Local State); passwords were not migrated.',
+      });
+    } else if (isFirefox) {
+      mergeReport(
+        report,
+        'passwords',
+        await migrateFirefoxPasswords({
+          profileDir: sourceProfileDir,
+          targetProfileDir: to,
+          platform,
+          targetKey: passwordKeys.targetKey,
+          targetPrefix: passwordKeys.targetPrefix,
+          primaryPassword: passwordKeys.primaryPassword,
+        })
+      );
+    } else {
+      mergeReport(
+        report,
+        'passwords',
+        await migratePasswords({
+          sourceProfileDir,
+          targetProfileDir: to,
+          platform,
+          resolveSourceKey: passwordKeys.resolveSourceKey,
+          targetKey: passwordKeys.targetKey,
+          targetPrefix: passwordKeys.targetPrefix,
+        })
+      );
+    }
+  }
+
+  return report;
+}

package/src/browser/migration/os-crypt-keys.js

@@ -0,0 +1,106 @@
+import path from 'node:path';
+
+import { deriveChromiumCookieKey } from '../browser-cookie-crypto.js';
+import {
+  decryptWindowsDpapi,
+  readSafeStoragePassword,
+  readWindowsEncryptionKey,
+} from '../browser-cookie-credentials.js';
+
+/**
+ * Resolve the OSCrypt keys a migration needs: the source profile's key (to
+ * decrypt) and the target profile's key (to re-encrypt). Both sides reuse the
+ * cookie key handling so passwords and cookies share one implementation of the
+ * per-platform keystore. Every keystore call is injectable so the whole thing
+ * runs on Linux in unit tests.
+ *
+ * On macOS and Linux the Safe Storage key is per application, not per profile,
+ * so the target key is looked up for the launching browser channel. On Windows
+ * the target key does not exist yet: the caller generates one with
+ * `createWindowsProfileKey` and writes it into the target `Local State`.
+ */
+
+/**
+ * Build a decryptor key resolver for a source profile, keyed by encryption
+ * prefix (Linux uses a hardcoded key for `v10` and the keyring for `v11`).
+ *
+ * @param {Object} options
+ * @param {string} options.browser
+ * @param {string} options.platform
+ * @param {string} options.localStatePath - Source Local State (Windows key)
+ * @param {Object} [options.environment]
+ * @param {Function} [options.readSafeStoragePassword]
+ * @param {Function} [options.readWindowsEncryptionKey]
+ * @param {Function} [options.decryptWindowsDpapi]
+ * @returns {function(string): Promise<Buffer>}
+ */
+export function createSourceKeyResolver({
+  browser,
+  platform,
+  localStatePath,
+  environment = process.env,
+  readSafeStoragePassword: readSafeStorage = readSafeStoragePassword,
+  readWindowsEncryptionKey: readWindowsKey = readWindowsEncryptionKey,
+  decryptWindowsDpapi: decryptDpapi = decryptWindowsDpapi,
+}) {
+  const cache = new Map();
+  return (prefix) => {
+    const cacheKey = `${prefix}`;
+    if (cache.has(cacheKey)) {
+      return cache.get(cacheKey);
+    }
+    const promise = (async () => {
+      if (platform === 'win32') {
+        return readWindowsKey({
+          localStatePath,
+          environment,
+          decryptDpapi,
+        });
+      }
+      if (platform === 'linux' && prefix === 'v10') {
+        return deriveChromiumCookieKey('peanuts', 'linux');
+      }
+      if (platform === 'linux' || platform === 'darwin') {
+        const password = await readSafeStorage({
+          browser,
+          platform,
+          environment,
+        });
+        return deriveChromiumCookieKey(password, platform);
+      }
+      throw new Error(`OSCrypt keys are unsupported on ${platform}`);
+    })();
+    cache.set(cacheKey, promise);
+    return promise;
+  };
+}
+
+/**
+ * Resolve the target (launching) profile's encryption key on macOS/Linux.
+ *
+ * @param {Object} options
+ * @param {string} options.browser - Launching browser channel
+ * @param {string} options.platform
+ * @param {Object} [options.environment]
+ * @param {Function} [options.readSafeStoragePassword]
+ * @returns {Promise<{key: Buffer, prefix: string}>}
+ */
+export async function resolveTargetKey({
+  browser,
+  platform,
+  environment = process.env,
+  readSafeStoragePassword: readSafeStorage = readSafeStoragePassword,
+}) {
+  if (platform === 'darwin' || platform === 'linux') {
+    const password = await readSafeStorage({ browser, platform, environment });
+    return { key: deriveChromiumCookieKey(password, platform), prefix: 'v11' };
+  }
+  throw new Error(
+    `resolveTargetKey does not derive a Windows key; use createWindowsProfileKey`
+  );
+}
+
+/** Convenience: the Local State path next to a profile directory. */
+export function localStatePathForProfile(profileDir) {
+  return path.join(path.dirname(profileDir), 'Local State');
+}

package/src/browser/migration/passwords.js

@@ -0,0 +1,171 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists } from './fs-utils.js';
+
+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';
+
+/**
+ * Saved-password migration.
+ *
+ * Chrome stores saved passwords in the `Login Data` SQLite database, in the
+ * `logins` table, with `password_value` encrypted exactly like a cookie's
+ * `encrypted_value` (the same OSCrypt keys), except that `Login Data` values
+ * never carry the SHA-256(host) domain-hash prefix the Cookies database adds at
+ * schema version 24.
+ *
+ * Passwords cannot be re-seeded over CDP the way cookies can, so the migration
+ * writes a target `Login Data` directly:
+ *
+ * 1. Take a consistent, read-only snapshot of the source `Login Data` with the
+ *    SQLite Online Backup API (never writing to the running source).
+ * 2. Copy that snapshot to the target path, which preserves Chrome's exact
+ *    schema (tables, indexes, `meta` version rows) verbatim.
+ * 3. Decrypt each `password_value` with the source profile's key and
+ *    re-encrypt it with the dedicated target profile's key, updating the row
+ *    in place. Because only the values are rewritten, the schema Chrome expects
+ *    is untouched.
+ *
+ * The source key handling, the target key, and the platform are all injected so
+ * the whole path is unit-testable on Linux with a fabricated key. Windows
+ * app-bound `v20` values cannot be decrypted outside the browser and are
+ * reported in `skipped` rather than failing the migration.
+ */
+
+function toBuffer(value) {
+  if (value === undefined || value === null) {
+    return Buffer.alloc(0);
+  }
+  return Buffer.isBuffer(value) ? value : Buffer.from(value);
+}
+
+function hostFromOrigin(originUrl) {
+  try {
+    return new URL(originUrl).hostname;
+  } catch {
+    return originUrl ?? '';
+  }
+}
+
+/**
+ * Migrate saved passwords into the target profile's `Login Data`.
+ *
+ * @param {Object} options
+ * @param {string} options.sourceProfileDir
+ * @param {string} options.targetProfileDir
+ * @param {string} [options.platform=process.platform]
+ * @param {function(string): (Promise<Buffer>|Buffer)} options.resolveSourceKey
+ *   Resolve the source decryption key for an encryption prefix (v10/v11).
+ * @param {Buffer} options.targetKey - The dedicated profile's encryption key.
+ * @param {string} [options.targetPrefix] - Version prefix to write (v10/v11).
+ * @returns {Promise<{migrated: number, skipped: Array, warnings: Array}>}
+ */
+export async function migratePasswords({
+  sourceProfileDir,
+  targetProfileDir,
+  platform = process.platform,
+  resolveSourceKey,
+  targetKey,
+  targetPrefix = platform === 'win32' ? 'v10' : 'v11',
+}) {
+  const sourcePath = path.join(sourceProfileDir, 'Login Data');
+  if (!(await pathExists(sourcePath))) {
+    return {
+      migrated: 0,
+      skipped: [
+        { type: 'passwords', item: 'Login Data', reason: 'source-missing' },
+      ],
+      warnings: [],
+    };
+  }
+  if (typeof resolveSourceKey !== 'function') {
+    throw new TypeError(
+      'migratePasswords requires a resolveSourceKey function'
+    );
+  }
+  if (!Buffer.isBuffer(targetKey)) {
+    throw new TypeError('migratePasswords requires a target encryption key');
+  }
+
+  await mkdir(targetProfileDir, { recursive: true });
+  const targetPath = path.join(targetProfileDir, 'Login Data');
+
+  return withDatabaseSnapshot({
+    sourcePath,
+    read: async (snapshotPath) => {
+      // The snapshot copy preserves Chrome's exact schema; re-encrypt values in
+      // place so the target keeps whatever schema version this Chrome build
+      // wrote.
+      await copyFile(snapshotPath, targetPath);
+      const db = await openSqliteDatabase(targetPath, { fileMustExist: true });
+      const skipped = [];
+      const warnings = [];
+      let migrated = 0;
+      try {
+        const rows = db
+          .prepare(
+            'SELECT rowid AS rowid, origin_url, password_value FROM logins'
+          )
+          .all();
+        const update = db.prepare(
+          'UPDATE logins SET password_value = ? WHERE rowid = ?'
+        );
+        for (const row of rows) {
+          const encryptedValue = toBuffer(row.password_value);
+          if (encryptedValue.length === 0) {
+            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,
+            });
+            continue;
+          }
+          const reencrypted = encryptChromiumValue({
+            plaintext,
+            key: targetKey,
+            platform,
+            prefix: targetPrefix,
+          });
+          update.run(reencrypted, row.rowid);
+          migrated += 1;
+        }
+      } finally {
+        db.close();
+      }
+      return { migrated, skipped, warnings };
+    },
+  });
+}