browser-commander 0.20.0 → 0.21.0

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

@@ -0,0 +1,281 @@
+import {
+  createDecipheriv,
+  createHash,
+  createHmac,
+  pbkdf2Sync,
+} from 'node:crypto';
+
+import { readDatabaseSnapshot } from './sqlite-snapshot.js';
+import {
+  decodeDerElement,
+  decodeDerSequence,
+  oidToString,
+} from './firefox-der.js';
+
+/**
+ * NSS decryption for Firefox saved logins.
+ *
+ * Firefox does not use OSCrypt; it stores logins in `logins.json` and protects
+ * them with NSS. The decryption key lives in `key4.db`:
+ *
+ * - `metadata` (id `password`) holds a global salt and a password-check blob.
+ * - `nssPrivate` holds the encrypted 3DES key used for the actual logins.
+ *
+ * Two encryption schemes appear in the wild:
+ *
+ * - Modern Firefox wraps the key with PKCS#5 PBES2 (PBKDF2-HMAC-SHA256 then
+ *   AES-256-CBC). The PBKDF2 password is `SHA1(globalSalt + primaryPassword)`
+ *   and NSS stores only 14 IV bytes, so the real 16-byte CBC IV is
+ *   `0x04 0x0e` followed by those bytes.
+ * - Legacy profiles use `pbeWithSha1AndTripleDES-CBC`: a SHA1-based KDF derives
+ *   a 3DES key and IV directly from the global salt, the entry salt and the
+ *   primary password.
+ *
+ * The individual login fields are always 3DES-CBC (`des-ede3-cbc`) under the
+ * recovered key. If a primary password is set and no correct one is supplied,
+ * the password-check fails and the caller reports `primary-password-set`
+ * instead of guessing.
+ *
+ * References:
+ * - https://searchfox.org/mozilla-central/source/security/nss (NSS sources)
+ * - https://github.com/unode/firefox_decrypt (the reference algorithm)
+ */
+
+const OID = Object.freeze({
+  PBES2: '1.2.840.113549.1.5.13',
+  PBKDF2: '1.2.840.113549.1.5.12',
+  DES_EDE3_CBC: '1.2.840.113549.3.7',
+  PBE_SHA1_3DES: '1.2.840.113549.1.12.5.1.3',
+});
+
+const PASSWORD_CHECK = Buffer.from('password-check\u0002\u0002', 'latin1');
+
+/** Thrown when a primary (master) password blocks decryption. */
+export class PrimaryPasswordError extends Error {
+  constructor(message = 'Firefox primary password is set') {
+    super(message);
+    this.name = 'PrimaryPasswordError';
+  }
+}
+
+function derChildren(element) {
+  return element.children ?? decodeDerSequence(element.content);
+}
+
+function integerValue(element) {
+  let value = 0;
+  for (const byte of element.content) {
+    value = value * 256 + byte;
+  }
+  return value;
+}
+
+/**
+ * Decrypt a PBES2 (PBKDF2-HMAC-SHA256 + AES-256-CBC) blob NSS wrote.
+ *
+ * @param {Object} algorithmParams - The parsed PBES2 parameters SEQUENCE
+ * @param {Buffer} ciphertext
+ * @param {Buffer} globalSalt
+ * @param {Buffer} primaryPassword
+ * @returns {Buffer}
+ */
+function decryptPbes2(
+  algorithmParams,
+  ciphertext,
+  globalSalt,
+  primaryPassword
+) {
+  const [kdf, encryptionScheme] = derChildren(algorithmParams);
+  const [, pbkdf2Params] = derChildren(kdf);
+  const params = derChildren(pbkdf2Params);
+  const entrySalt = params[0].content;
+  const iterationCount = integerValue(params[1]);
+  const keyLength = integerValue(params[2]);
+  const [, ivElement] = derChildren(encryptionScheme);
+
+  // This is not password storage: key4.db fixes the scheme as
+  // PBKDF2(SHA-1(globalSalt + primaryPassword)), and reading the profile
+  // Firefox wrote requires reproducing it byte for byte.
+  const passwordHash = createHash('sha1')
+    .update(Buffer.concat([globalSalt, primaryPassword]))
+    .digest();
+  const key = pbkdf2Sync(
+    passwordHash,
+    entrySalt,
+    iterationCount,
+    keyLength,
+    'sha256'
+  );
+  const iv = Buffer.concat([Buffer.from([0x04, 0x0e]), ivElement.content]);
+  const decipher = createDecipheriv('aes-256-cbc', key, iv);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+function pkcs7Unpad(buffer) {
+  const padLength = buffer[buffer.length - 1];
+  if (padLength > 0 && padLength <= buffer.length) {
+    return buffer.subarray(0, buffer.length - padLength);
+  }
+  return buffer;
+}
+
+/**
+ * Decrypt the legacy pbeWithSha1AndTripleDES-CBC key blob.
+ *
+ * @param {Object} algorithmParams - SEQUENCE { entrySalt OCTETSTRING, iterations INT }
+ * @param {Buffer} ciphertext
+ * @param {Buffer} globalSalt
+ * @param {Buffer} primaryPassword
+ * @returns {Buffer}
+ */
+function decryptPbeSha1Triple3Des(
+  algorithmParams,
+  ciphertext,
+  globalSalt,
+  primaryPassword
+) {
+  const params = derChildren(algorithmParams);
+  const entrySalt = params[0].content;
+
+  // NSS's SHA1-based PKCS#12 KDF for pbeWithSha1AndTripleDES-CBC. The entry
+  // salt is right-padded with zeros to 20 bytes, and the 3DES key and IV are
+  // derived through three chained HMAC-SHA1 rounds. The format is fixed by
+  // NSS, so the SHA-1 password hash cannot be swapped for a slower one.
+  const hp = createHash('sha1')
+    .update(Buffer.concat([globalSalt, primaryPassword]))
+    .digest();
+  const pes = Buffer.concat([
+    entrySalt,
+    Buffer.alloc(Math.max(20 - entrySalt.length, 0)),
+  ]).subarray(0, 20);
+  const chp = createHash('sha1')
+    .update(Buffer.concat([hp, entrySalt]))
+    .digest();
+  const k1 = createHmac('sha1', chp)
+    .update(Buffer.concat([pes, entrySalt]))
+    .digest();
+  const tk = createHmac('sha1', chp).update(pes).digest();
+  const k2 = createHmac('sha1', chp)
+    .update(Buffer.concat([tk, entrySalt]))
+    .digest();
+  const derived = Buffer.concat([k1, k2]);
+  const key = derived.subarray(0, 24);
+  const iv = derived.subarray(derived.length - 8);
+  const decipher = createDecipheriv('des-ede3-cbc', key, iv);
+  decipher.setAutoPadding(false);
+  const plaintext = Buffer.concat([
+    decipher.update(ciphertext),
+    decipher.final(),
+  ]);
+  return pkcs7Unpad(plaintext);
+}
+
+function decryptNssBlob(blob, globalSalt, primaryPassword) {
+  const top = decodeDerElement(blob);
+  const [algorithmId, cipherElement] = derChildren(top);
+  const algorithmChildren = derChildren(algorithmId);
+  const oid = oidToString(algorithmChildren[0].content);
+  const params = algorithmChildren[1];
+  if (oid === OID.PBES2) {
+    return decryptPbes2(
+      params,
+      cipherElement.content,
+      globalSalt,
+      primaryPassword
+    );
+  }
+  if (oid === OID.PBE_SHA1_3DES) {
+    return decryptPbeSha1Triple3Des(
+      params,
+      cipherElement.content,
+      globalSalt,
+      primaryPassword
+    );
+  }
+  throw new Error(`Unsupported NSS key algorithm ${oid}`);
+}
+
+/**
+ * Recover the 3DES login key from a `key4.db` snapshot.
+ *
+ * @param {Object} db - An open, read-only key4.db handle
+ * @param {Buffer} primaryPassword - Empty when no primary password is set
+ * @returns {Buffer} The 24-byte 3DES key
+ */
+export function recoverFirefoxKeyFromDatabase(
+  db,
+  primaryPassword = Buffer.alloc(0)
+) {
+  const meta = db
+    .prepare("SELECT item1, item2 FROM metadata WHERE id = 'password'")
+    .get();
+  if (!meta) {
+    throw new Error('key4.db has no password metadata');
+  }
+  const globalSalt = Buffer.from(meta.item1);
+  let check;
+  try {
+    check = decryptNssBlob(
+      Buffer.from(meta.item2),
+      globalSalt,
+      primaryPassword
+    );
+  } catch {
+    // A wrong or missing primary password makes the CBC padding check fail;
+    // treat any decryption failure of the password-check blob as a locked key.
+    throw new PrimaryPasswordError();
+  }
+  if (!check.subarray(0, PASSWORD_CHECK.length).equals(PASSWORD_CHECK)) {
+    throw new PrimaryPasswordError();
+  }
+  const priv = db.prepare('SELECT a11, a102 FROM nssPrivate').get();
+  if (!priv) {
+    throw new Error('key4.db has no nssPrivate key');
+  }
+  const decrypted = decryptNssBlob(
+    Buffer.from(priv.a11),
+    globalSalt,
+    primaryPassword
+  );
+  return decrypted.subarray(0, 24);
+}
+
+/**
+ * Decrypt one NSS-protected `logins.json` field (username or password).
+ *
+ * @param {string} base64Value - `encryptedUsername`/`encryptedPassword`
+ * @param {Buffer} key - The 24-byte 3DES key
+ * @returns {string}
+ */
+export function decryptFirefoxField(base64Value, key) {
+  const top = decodeDerElement(Buffer.from(base64Value, 'base64'));
+  const [, algorithm, cipherElement] = derChildren(top);
+  const algorithmChildren = derChildren(algorithm);
+  const iv = algorithmChildren[1].content;
+  const decipher = createDecipheriv('des-ede3-cbc', key, iv);
+  decipher.setAutoPadding(false);
+  const plaintext = Buffer.concat([
+    decipher.update(cipherElement.content),
+    decipher.final(),
+  ]);
+  return pkcs7Unpad(plaintext).toString('utf8');
+}
+
+/**
+ * Recover the login key from a `key4.db` file path (taking a read-only
+ * snapshot so a running Firefox is never disturbed).
+ *
+ * @param {Object} options
+ * @param {string} options.key4Path
+ * @param {Buffer} [options.primaryPassword]
+ * @returns {Promise<Buffer>}
+ */
+export function recoverFirefoxKey({
+  key4Path,
+  primaryPassword = Buffer.alloc(0),
+}) {
+  return readDatabaseSnapshot({
+    sourcePath: key4Path,
+    read: (db) => recoverFirefoxKeyFromDatabase(db, primaryPassword),
+  });
+}

package/src/browser/migration/firefox.js

@@ -0,0 +1,334 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { profileFileIfPresent } from './fs-utils.js';
+
+import { openSqliteDatabase } from '../browser-cookie-database.js';
+import { mapFirefoxCookieRows } from '../browser-cookies.js';
+import { readDatabaseSnapshot } from './sqlite-snapshot.js';
+import { encryptChromiumValue } from './chromium-crypto.js';
+import { firefoxBookmarksToChrome } from './firefox-bookmarks.js';
+import {
+  PrimaryPasswordError,
+  decryptFirefoxField,
+  recoverFirefoxKeyFromDatabase,
+} from './firefox-nss.js';
+
+/**
+ * Firefox → Chromium profile migration.
+ *
+ * Firefox stores its data very differently from Chromium, so each data class is
+ * translated rather than copied:
+ *
+ * - **cookies:** read from `cookies.sqlite` (`moz_cookies`, unencrypted) and
+ *   returned in the same shape as the Chromium reader so the launcher can seed
+ *   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.
+ * - **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`.
+ *
+ * Every database is read through a consistent read-only snapshot, so a running
+ * Firefox is never disturbed.
+ */
+
+const FIREFOX_ROOT_GUIDS = Object.freeze({
+  toolbar_____: 'toolbar',
+  menu________: 'menu',
+  unfiled_____: 'unfiled',
+});
+
+// A conservative Chrome `Login Data` schema. Chrome re-keys or upgrades this on
+// first launch; the columns below are the long-stable core of the `logins`
+// table plus the `meta` version marker.
+const CHROME_LOGINS_SCHEMA = `
+CREATE TABLE meta (key LONGVARCHAR NOT NULL UNIQUE PRIMARY KEY, value LONGVARCHAR);
+INSERT INTO meta (key, value) VALUES ('version', '34');
+INSERT INTO meta (key, value) VALUES ('last_compatible_version', '1');
+CREATE TABLE logins (
+  origin_url VARCHAR NOT NULL,
+  action_url VARCHAR,
+  username_element VARCHAR,
+  username_value VARCHAR,
+  password_element VARCHAR,
+  password_value BLOB,
+  submit_element VARCHAR,
+  signon_realm VARCHAR NOT NULL,
+  date_created INTEGER NOT NULL,
+  blacklisted_by_user INTEGER NOT NULL,
+  scheme INTEGER NOT NULL,
+  password_type INTEGER,
+  times_used INTEGER,
+  form_data BLOB,
+  display_name VARCHAR,
+  icon_url VARCHAR,
+  federation_url VARCHAR,
+  skip_zero_click INTEGER,
+  generation_upload_status INTEGER,
+  possible_username_pairs BLOB,
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  date_last_used INTEGER NOT NULL DEFAULT 0,
+  moving_blocked_for BLOB,
+  date_password_modified INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (origin_url, username_element, username_value, password_element, signon_realm)
+);
+`;
+
+function signonRealm(originUrl) {
+  try {
+    const url = new URL(originUrl);
+    return `${url.protocol}//${url.host}/`;
+  } catch {
+    return originUrl;
+  }
+}
+
+/**
+ * Read Firefox cookies from `cookies.sqlite` in the same shape as the Chromium
+ * cookie reader.
+ *
+ * @param {Object} options
+ * @param {string} options.profileDir
+ * @param {string[]} [options.domains]
+ * @returns {Promise<Object[]>}
+ */
+export async function readFirefoxCookies({ profileDir, domains }) {
+  const cookiePath = await profileFileIfPresent(profileDir, 'cookies.sqlite');
+  if (!cookiePath) {
+    return [];
+  }
+  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();
+      // 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
+        )
+      );
+    },
+  });
+}
+
+/**
+ * Convert Firefox bookmarks to a Chrome `Bookmarks` file in the target profile.
+ *
+ * @param {Object} options
+ * @param {string} options.profileDir - Firefox source profile
+ * @param {string} options.targetProfileDir
+ * @returns {Promise<{migrated: number, skipped: Array, warnings: Array}>}
+ */
+export async function migrateFirefoxBookmarks({
+  profileDir,
+  targetProfileDir,
+}) {
+  const placesPath = await profileFileIfPresent(profileDir, 'places.sqlite');
+  if (!placesPath) {
+    return {
+      migrated: 0,
+      skipped: [
+        { type: 'bookmarks', item: 'places.sqlite', reason: 'source-missing' },
+      ],
+      warnings: [],
+    };
+  }
+  const rows = await readDatabaseSnapshot({
+    sourcePath: placesPath,
+    read: (db) =>
+      db
+        .prepare(
+          `SELECT b.id, b.parent, b.type, b.title, b.guid, p.url
+             FROM moz_bookmarks b
+             LEFT JOIN moz_places p ON b.fk = p.id
+            ORDER BY b.parent, b.position`
+        )
+        .all()
+        .map((row) => ({
+          id: Number(row.id),
+          parent: Number(row.parent),
+          type: Number(row.type),
+          title: row.title,
+          url: row.url,
+          root: FIREFOX_ROOT_GUIDS[row.guid] ?? null,
+        })),
+  });
+  const { document, count } = firefoxBookmarksToChrome({ rows });
+  await mkdir(targetProfileDir, { recursive: true });
+  await writeFile(
+    path.join(targetProfileDir, 'Bookmarks'),
+    JSON.stringify(document)
+  );
+  return { migrated: count, skipped: [], warnings: [] };
+}
+
+/**
+ * Count Firefox history and report it (Chrome's schema is incompatible).
+ *
+ * @param {Object} options
+ * @param {string} options.profileDir
+ * @returns {Promise<{migrated: number, skipped: Array, warnings: Array}>}
+ */
+export async function reportFirefoxHistory({ profileDir }) {
+  const placesPath = await profileFileIfPresent(profileDir, 'places.sqlite');
+  if (!placesPath) {
+    return { migrated: 0, skipped: [], warnings: [] };
+  }
+  const count = await readDatabaseSnapshot({
+    sourcePath: placesPath,
+    read: (db) =>
+      Number(db.prepare('SELECT COUNT(*) AS c FROM moz_places').get().c),
+  });
+  return {
+    migrated: 0,
+    skipped: [
+      {
+        type: 'history',
+        item: 'places.sqlite',
+        reason: 'firefox-history-schema-incompatible',
+      },
+    ],
+    warnings: [
+      {
+        type: 'history',
+        item: 'places.sqlite',
+        reason: 'not-migrated',
+        detail: `Firefox has ${count} history entries; Chrome's History schema is incompatible, so history is reported but not converted.`,
+      },
+    ],
+  };
+}
+
+/**
+ * Decrypt Firefox logins and write them into a Chrome `Login Data`.
+ *
+ * @param {Object} options
+ * @param {string} options.profileDir - Firefox source profile
+ * @param {string} options.targetProfileDir
+ * @param {string} options.platform
+ * @param {Buffer} options.targetKey - The dedicated Chrome profile's key
+ * @param {string} [options.targetPrefix]
+ * @param {Buffer} [options.primaryPassword]
+ * @returns {Promise<{migrated: number, skipped: Array, warnings: Array}>}
+ */
+export async function migrateFirefoxPasswords({
+  profileDir,
+  targetProfileDir,
+  platform,
+  targetKey,
+  targetPrefix = platform === 'win32' ? 'v10' : 'v11',
+  primaryPassword = Buffer.alloc(0),
+}) {
+  const loginsPath = await profileFileIfPresent(profileDir, 'logins.json');
+  const key4Path = await profileFileIfPresent(profileDir, 'key4.db');
+  if (!loginsPath || !key4Path) {
+    return {
+      migrated: 0,
+      skipped: [
+        { type: 'passwords', item: 'logins.json', reason: 'source-missing' },
+      ],
+      warnings: [],
+    };
+  }
+  if (!Buffer.isBuffer(targetKey)) {
+    throw new TypeError('migrateFirefoxPasswords requires a target key');
+  }
+
+  let key;
+  try {
+    key = await readDatabaseSnapshot({
+      sourcePath: key4Path,
+      read: (db) => recoverFirefoxKeyFromDatabase(db, primaryPassword),
+    });
+  } catch (error) {
+    if (error instanceof PrimaryPasswordError) {
+      return {
+        migrated: 0,
+        skipped: [
+          {
+            type: 'passwords',
+            item: 'logins.json',
+            reason: 'primary-password-set',
+          },
+        ],
+        warnings: [],
+      };
+    }
+    throw error;
+  }
+
+  const logins = JSON.parse(await readFile(loginsPath, 'utf8')).logins ?? [];
+  const decrypted = [];
+  const skipped = [];
+  for (const login of logins) {
+    try {
+      decrypted.push({
+        origin: login.hostname,
+        username: decryptFirefoxField(login.encryptedUsername, key),
+        password: decryptFirefoxField(login.encryptedPassword, key),
+      });
+    } catch (error) {
+      skipped.push({
+        type: 'passwords',
+        item: login.hostname ?? '(unknown)',
+        reason: 'decrypt-failed',
+        detail: error.message,
+      });
+    }
+  }
+
+  await mkdir(targetProfileDir, { recursive: true });
+  const targetPath = path.join(targetProfileDir, 'Login Data');
+  const db = await openSqliteDatabase(targetPath);
+  let migrated = 0;
+  try {
+    db.exec(CHROME_LOGINS_SCHEMA);
+    const insert = db.prepare(
+      `INSERT OR IGNORE INTO logins (
+         origin_url, action_url, username_element, username_value,
+         password_element, password_value, submit_element, signon_realm,
+         date_created, blacklisted_by_user, scheme, password_type, times_used,
+         date_last_used, date_password_modified
+       ) VALUES (?, ?, '', ?, '', ?, '', ?, 0, 0, 0, 0, 0, 0, 0)`
+    );
+    for (const entry of decrypted) {
+      const encrypted = encryptChromiumValue({
+        plaintext: entry.password,
+        key: targetKey,
+        platform,
+        prefix: targetPrefix,
+      });
+      insert.run(
+        entry.origin,
+        entry.origin,
+        entry.username,
+        encrypted,
+        signonRealm(entry.origin)
+      );
+      migrated += 1;
+    }
+  } finally {
+    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 };
+}

package/src/browser/migration/fs-utils.js

@@ -0,0 +1,51 @@
+import { access, readFile } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Small filesystem helpers shared by the migration data-class modules.
+ */
+
+/**
+ * Return true when a path exists (of any type).
+ *
+ * @param {string} filePath
+ * @returns {Promise<boolean>}
+ */
+export async function pathExists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read and parse a JSON file, returning null when it is missing or malformed.
+ *
+ * @param {string} filePath
+ * @returns {Promise<Object|null>}
+ */
+export async function readJsonIfPresent(filePath) {
+  if (!(await pathExists(filePath))) {
+    return null;
+  }
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a file inside a profile directory, or null when it is absent.
+ *
+ * @param {string} profileDir
+ * @param {string} name - File name relative to the profile
+ * @returns {Promise<string|null>}
+ */
+export async function profileFileIfPresent(profileDir, name) {
+  const filePath = path.join(profileDir, name);
+  return (await pathExists(filePath)) ? filePath : null;
+}