browser-commander 0.20.0 → 0.21.0

package/src/browser/migration/cookies.js

@@ -0,0 +1,155 @@
+import path from 'node:path';
+
+import { pathExists } from './fs-utils.js';
+
+import { readBrowserCookies } from '../browser-cookies.js';
+
+/**
+ * Cookie migration.
+ *
+ * Cookies are read from the source profile with the existing
+ * {@link readBrowserCookies} (which handles the per-platform keystore and the
+ * v10/v11 decryption), optionally filtered by domain, and returned so the
+ * launcher can seed them into the dedicated profile over CDP with the existing
+ * `seedCookies` path. This module does not write anything into the target
+ * profile itself; the CDP seed is what a real, running browser accepts.
+ *
+ * ## Device Bound Session Credentials (DBSC)
+ *
+ * Google has shipped Device Bound Session Credentials: the session is bound to
+ * a private key held in the device's TPM or Secure Enclave, and the short
+ * "session token" cookies are rotated by the browser using that key. The key
+ * cannot leave the profile, so a copied Google session cannot be refreshed
+ * from another profile and expires quickly. Chrome's guidance is to report
+ * this rather than fail silently.
+ *
+ * References:
+ * - https://developer.chrome.com/docs/web-platform/device-bound-session-credentials
+ * - https://github.com/WICG/dbsc (the DBSC explainer)
+ * - https://www.helpnetsecurity.com/2026/04/10/google-chrome-device-bound-session-credentials/
+ *
+ * Detection is twofold:
+ *
+ * 1. By name+domain: the rotating bound cookies Chrome refreshes for a Google
+ *    sign-in are `__Secure-1PSIDTS`, `__Secure-3PSIDTS` and `SIDTS` on
+ *    `google.*`/`accounts.google.com` hosts. These are copied (so the rest of
+ *    the session's cookies stay coherent) but reported in `skipped` with the
+ *    reason `dbsc-bound`, because they will not survive rotation in the new
+ *    profile.
+ * 2. By registration: if the source profile stores a DBSC registration
+ *    database (`DeviceBoundSessions`, written under the profile's `Network`
+ *    directory), a warning is added noting that any cookie covered by a bound
+ *    session is subject to the same limitation. The registration itself is not
+ *    copied because it is bound to the source device's key.
+ */
+
+/** Rotating Google session-token cookies that DBSC binds to the device key. */
+export const DBSC_BOUND_COOKIE_NAMES = Object.freeze([
+  '__Secure-1PSIDTS',
+  '__Secure-3PSIDTS',
+  'SIDTS',
+]);
+
+/** DBSC registration databases Chrome may write in the profile. */
+const DBSC_REGISTRATION_FILES = [
+  'Network/DeviceBoundSessions',
+  'DeviceBoundSessions',
+];
+
+function isGoogleHost(domain) {
+  const host = (domain ?? '').replace(/^\./, '').toLowerCase();
+  return (
+    host === 'google.com' ||
+    host.endsWith('.google.com') ||
+    /(^|\.)google\.[a-z.]+$/.test(host)
+  );
+}
+
+/**
+ * Decide whether a cookie is a DBSC-bound Google session cookie.
+ *
+ * @param {{name: string, domain: string}} cookie
+ * @returns {boolean}
+ */
+export function isDbscBoundCookie(cookie) {
+  return (
+    isGoogleHost(cookie.domain) && DBSC_BOUND_COOKIE_NAMES.includes(cookie.name)
+  );
+}
+
+async function findDbscRegistration(profileDir) {
+  for (const relative of DBSC_REGISTRATION_FILES) {
+    const candidate = path.join(profileDir, relative);
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read cookies from the source browser, tag the DBSC-bound ones, and return the
+ * cookies to seed plus the migration report fragment.
+ *
+ * @param {Object} options
+ * @param {string} options.browser - chrome | edge | brave | chromium
+ * @param {string} [options.profile] - Source profile name
+ * @param {string} [options.sourceProfileDir] - Source profile directory (for DBSC detection)
+ * @param {string[]} [options.domains] - Optional domain filter (substring match)
+ * @param {Function} [options.readCookies=readBrowserCookies] - Injectable reader
+ * @param {Object} [options.readerOptions] - Extra options for the reader (platform, homeDir, ...)
+ * @returns {Promise<{cookies: Object[], migrated: number, skipped: Array, warnings: Array}>}
+ */
+export async function migrateCookies({
+  browser,
+  profile,
+  sourceProfileDir,
+  domains,
+  readCookies = readBrowserCookies,
+  readerOptions = {},
+}) {
+  const domainFilters =
+    Array.isArray(domains) && domains.length > 0 ? domains : [null];
+
+  const seen = new Map();
+  for (const domainFilter of domainFilters) {
+    const batch = await readCookies({
+      browser,
+      profile,
+      domainFilter: domainFilter ?? undefined,
+      ignoreDecryptionErrors: true,
+      ...readerOptions,
+    });
+    for (const cookie of batch) {
+      seen.set(
+        `${cookie.domain}\u0000${cookie.name}\u0000${cookie.path}`,
+        cookie
+      );
+    }
+  }
+  const cookies = [...seen.values()];
+
+  const skipped = [];
+  for (const cookie of cookies) {
+    if (isDbscBoundCookie(cookie)) {
+      skipped.push({
+        type: 'cookies',
+        item: `${cookie.domain} ${cookie.name}`,
+        reason: 'dbsc-bound',
+      });
+    }
+  }
+
+  const warnings = [];
+  if (sourceProfileDir && (await findDbscRegistration(sourceProfileDir))) {
+    warnings.push({
+      type: 'cookies',
+      item: 'DeviceBoundSessions',
+      reason: 'dbsc-registration-present',
+      detail:
+        'The source profile has a Device Bound Session registration; cookies covered by it are bound to the source device key and will expire in the migrated profile.',
+    });
+  }
+
+  return { cookies, migrated: cookies.length, skipped, warnings };
+}

package/src/browser/migration/extensions.js

@@ -0,0 +1,187 @@
+import { cp, mkdir, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists, readJsonIfPresent } from './fs-utils.js';
+
+/**
+ * Extension migration.
+ *
+ * A Chromium extension lives in two places in a profile:
+ *
+ * - its unpacked files under `Extensions/<id>/<version>/`, and
+ * - a bookkeeping entry under `extensions.settings.<id>` in `Secure
+ *   Preferences` (which records the install location, version, granted
+ *   permissions and enabled state).
+ *
+ * This module copies both: the extension's version directory and the
+ * `extensions.settings` entry.
+ *
+ * ## Secure Preferences MAC (honest limitation)
+ *
+ * `Secure Preferences` is protected by a per-entry HMAC ("MAC"). Chrome
+ * computes each MAC with a seed built from a hard-coded key baked into the
+ * browser binary combined with a per-profile/OS identifier (on Windows the seed
+ * is additionally tied to the machine SID via the `machine_id`). Because that
+ * seed differs for the dedicated target profile, a MAC copied from the source
+ * profile will not validate, and Chrome treats an entry with an invalid MAC as
+ * tampering: it disables (or silently drops) the extension on the next launch
+ * and shows the "settings were changed" reset bubble.
+ *
+ * We cannot forge a valid MAC without the browser's embedded key, so the copy
+ * is made on a best-effort basis and every migrated extension is reported with
+ * a warning explaining that the user will likely have to re-enable it (or
+ * re-install it from the Web Store, which restores a valid MAC). This is the
+ * honest, documented behaviour rather than a silent partial success.
+ *
+ * References:
+ * - https://chromium.googlesource.com/chromium/src/+/HEAD/services/preferences/tracked/README.md
+ * - https://www.chromium.org/developers/design-documents/preferences (tracked/protected preferences)
+ *
+ * ## Excluded extensions
+ *
+ * Policy-installed and component/built-in extensions are never copied: they are
+ * managed by enterprise policy or shipped with the browser, so copying their
+ * files into a user profile is both pointless (the browser re-adds them) and
+ * potentially conflicting. They are identified by the `location` value in the
+ * settings entry.
+ */
+
+// Chrome's `Manifest::Location` values. Component/built-in and policy-managed
+// extensions are excluded from a migration.
+const EXCLUDED_LOCATIONS = new Set([
+  5, // COMPONENT
+  7, // EXTERNAL_POLICY_DOWNLOAD
+  9, // EXTERNAL_POLICY
+  10, // EXTERNAL_COMPONENT
+]);
+
+const SECURE_PREFERENCES = 'Secure Preferences';
+
+/**
+ * Decide which extension ids are eligible to migrate from a settings map.
+ *
+ * @param {Object} settings - `extensions.settings` from Secure Preferences
+ * @returns {{eligible: string[], excluded: Array<{id: string, reason: string}>}}
+ */
+export function selectMigratableExtensions(settings) {
+  const eligible = [];
+  const excluded = [];
+  for (const [id, entry] of Object.entries(settings ?? {})) {
+    const location = Number(entry?.location);
+    if (EXCLUDED_LOCATIONS.has(location)) {
+      excluded.push({ id, reason: 'policy-or-component-extension' });
+      continue;
+    }
+    if (entry?.was_installed_by_default === true && !entry?.manifest) {
+      excluded.push({ id, reason: 'default-extension' });
+      continue;
+    }
+    eligible.push(id);
+  }
+  return { eligible, excluded };
+}
+
+async function copyExtensionFiles(
+  sourceExtensionsDir,
+  targetExtensionsDir,
+  id
+) {
+  const sourceDir = path.join(sourceExtensionsDir, id);
+  if (!(await pathExists(sourceDir))) {
+    return false;
+  }
+  await mkdir(targetExtensionsDir, { recursive: true });
+  await cp(sourceDir, path.join(targetExtensionsDir, id), {
+    recursive: true,
+    force: true,
+  });
+  return true;
+}
+
+/**
+ * Migrate extensions from a source profile 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 migrateExtensions({
+  sourceProfileDir,
+  targetProfileDir,
+}) {
+  const skipped = [];
+  const warnings = [];
+
+  const sourceExtensionsDir = path.join(sourceProfileDir, 'Extensions');
+  if (!(await pathExists(sourceExtensionsDir))) {
+    return { migrated: 0, skipped: [], warnings: [] };
+  }
+
+  const securePrefs = await readJsonIfPresent(
+    path.join(sourceProfileDir, SECURE_PREFERENCES)
+  );
+  const settings = securePrefs?.extensions?.settings ?? {};
+
+  // Fall back to the on-disk directory listing when there is no settings map
+  // (for example a snapshot copied without Secure Preferences).
+  let eligible;
+  let excluded;
+  if (Object.keys(settings).length > 0) {
+    ({ eligible, excluded } = selectMigratableExtensions(settings));
+  } else {
+    const entries = await readdir(sourceExtensionsDir, { withFileTypes: true });
+    eligible = entries
+      .filter((entry) => entry.isDirectory() && entry.name !== 'Temp')
+      .map((entry) => entry.name);
+    excluded = [];
+  }
+
+  for (const { id, reason } of excluded) {
+    skipped.push({ type: 'extensions', item: id, reason });
+  }
+
+  const targetExtensionsDir = path.join(targetProfileDir, 'Extensions');
+  const migratedSettings = {};
+  let migrated = 0;
+  for (const id of eligible) {
+    const copied = await copyExtensionFiles(
+      sourceExtensionsDir,
+      targetExtensionsDir,
+      id
+    );
+    if (!copied) {
+      skipped.push({ type: 'extensions', item: id, reason: 'files-missing' });
+      continue;
+    }
+    if (settings[id]) {
+      migratedSettings[id] = settings[id];
+    }
+    migrated += 1;
+  }
+
+  if (migrated > 0) {
+    // Best-effort: write the settings entries into the target Secure
+    // Preferences so Chrome knows about the extensions. The MAC will not
+    // validate for the target profile (see the module comment), so warn.
+    if (Object.keys(migratedSettings).length > 0) {
+      const targetSecurePath = path.join(targetProfileDir, SECURE_PREFERENCES);
+      const targetSecure = (await readJsonIfPresent(targetSecurePath)) ?? {};
+      targetSecure.extensions ??= {};
+      targetSecure.extensions.settings = {
+        ...(targetSecure.extensions.settings ?? {}),
+        ...migratedSettings,
+      };
+      await mkdir(targetProfileDir, { recursive: true });
+      await writeFile(targetSecurePath, JSON.stringify(targetSecure));
+    }
+    warnings.push({
+      type: 'extensions',
+      item: 'Secure Preferences MAC',
+      reason: 'mac-will-not-validate',
+      detail:
+        'Extension files and settings were copied, but Chrome computes a per-profile HMAC over Secure Preferences that cannot be reproduced for the target profile. Chrome will likely disable the migrated extensions on first launch; re-enable them or reinstall from the Web Store to restore a valid MAC.',
+    });
+  }
+
+  return { migrated, skipped, warnings };
+}

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

@@ -0,0 +1,144 @@
+/**
+ * Convert a Firefox `places.sqlite` bookmark tree into Chrome's `Bookmarks`
+ * JSON format.
+ *
+ * Firefox keeps bookmarks in `moz_bookmarks` (a tree of folders/rows, type 1 =
+ * bookmark, type 2 = folder) joined to `moz_places` for the URLs. Chrome keeps
+ * them in a JSON document with three roots (`bookmark_bar`, `other`,
+ * `synced`). The Firefox toolbar maps to Chrome's bookmarks bar; the Firefox
+ * menu and unsorted bookmarks map to Chrome's "other bookmarks".
+ */
+
+// Chrome stores timestamps as microseconds since 1601-01-01; a fixed, valid
+// value is fine for imported bookmarks (Chrome only needs it to be parseable).
+const CHROME_TIMESTAMP = '13300000000000000';
+
+// Firefox root ids (stable across profiles).
+const FIREFOX_ROOT = Object.freeze({
+  TOOLBAR: 'toolbar',
+  MENU: 'menu',
+  UNFILED: 'unfiled',
+});
+
+function buildChromeNode(node, idRef) {
+  if (node.type === 'url') {
+    idRef.value += 1;
+    return {
+      date_added: CHROME_TIMESTAMP,
+      id: String(idRef.value),
+      name: node.title ?? node.url ?? '',
+      type: 'url',
+      url: node.url,
+    };
+  }
+  idRef.value += 1;
+  const id = String(idRef.value);
+  return {
+    children: (node.children ?? []).map((child) =>
+      buildChromeNode(child, idRef)
+    ),
+    date_added: CHROME_TIMESTAMP,
+    date_modified: CHROME_TIMESTAMP,
+    id,
+    name: node.title ?? '',
+    type: 'folder',
+  };
+}
+
+/**
+ * Build the parent→children tree from flat `moz_bookmarks` rows.
+ *
+ * @param {Array<{id: number, parent: number, type: number, title: string, url: (string|null)}>} rows
+ * @returns {Map<number, Array>}
+ */
+function groupByParent(rows) {
+  const byParent = new Map();
+  for (const row of rows) {
+    if (!byParent.has(row.parent)) {
+      byParent.set(row.parent, []);
+    }
+    byParent.get(row.parent).push(row);
+  }
+  return byParent;
+}
+
+function collectChildren(byParent, parentId) {
+  const rows = byParent.get(parentId) ?? [];
+  return rows.map((row) => {
+    if (row.type === 2) {
+      return {
+        type: 'folder',
+        title: row.title,
+        children: collectChildren(byParent, row.id),
+      };
+    }
+    return { type: 'url', title: row.title, url: row.url };
+  });
+}
+
+/**
+ * Convert flat `moz_bookmarks` rows (joined with URLs) to a Chrome Bookmarks
+ * document.
+ *
+ * @param {Object} options
+ * @param {Array} options.rows - Rows with {id, parent, type, title, url, root}
+ * @returns {{document: Object, count: number}}
+ */
+export function firefoxBookmarksToChrome({ rows }) {
+  const byParent = groupByParent(rows);
+  const rootIdByName = {};
+  for (const row of rows) {
+    if (row.root && FIREFOX_ROOT[row.root.toUpperCase()]) {
+      rootIdByName[row.root] = row.id;
+    }
+  }
+
+  const idRef = { value: 0 };
+  const makeRoot = (name, firefoxRootKey, extraRootKeys = []) => {
+    const children = [];
+    for (const key of [firefoxRootKey, ...extraRootKeys]) {
+      const rootId = rootIdByName[key];
+      if (rootId !== undefined && rootId !== null) {
+        for (const child of collectChildren(byParent, rootId)) {
+          children.push(buildChromeNode(child, idRef));
+        }
+      }
+    }
+    idRef.value += 1;
+    return {
+      children,
+      date_added: CHROME_TIMESTAMP,
+      date_modified: CHROME_TIMESTAMP,
+      id: String(idRef.value),
+      name,
+      type: 'folder',
+    };
+  };
+
+  const bookmarkBar = makeRoot('Bookmarks bar', FIREFOX_ROOT.TOOLBAR);
+  const other = makeRoot('Other bookmarks', FIREFOX_ROOT.MENU, [
+    FIREFOX_ROOT.UNFILED,
+  ]);
+  const synced = makeRoot('Mobile bookmarks', '__none__');
+
+  const countUrls = (node) => {
+    if (node.type === 'url') {
+      return 1;
+    }
+    return (node.children ?? []).reduce((sum, c) => sum + countUrls(c), 0);
+  };
+  const count = countUrls(bookmarkBar) + countUrls(other) + countUrls(synced);
+
+  return {
+    document: {
+      checksum: '',
+      roots: {
+        bookmark_bar: bookmarkBar,
+        other,
+        synced,
+      },
+      version: 1,
+    },
+    count,
+  };
+}

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

@@ -0,0 +1,84 @@
+/**
+ * A tiny DER (ASN.1) reader, just enough to walk the structures NSS writes into
+ * Firefox's `key4.db` and the base64 blobs in `logins.json`. It is deliberately
+ * minimal: it understands the tags those structures use (SEQUENCE, OCTET
+ * STRING, INTEGER, OBJECT IDENTIFIER) and returns a small tree, so the NSS
+ * decryption code can read fields by position without a full ASN.1 library
+ * (there is no DER dependency in this project).
+ */
+
+export const DER_TAG = Object.freeze({
+  INTEGER: 0x02,
+  OCTET_STRING: 0x04,
+  NULL: 0x05,
+  OID: 0x06,
+  SEQUENCE: 0x30,
+});
+
+/**
+ * Decode one DER element at `offset`.
+ *
+ * @param {Buffer} buffer
+ * @param {number} [offset=0]
+ * @returns {{tag: number, length: number, header: number, contentStart: number, end: number, content: Buffer, children: (Array|null)}}
+ */
+export function decodeDerElement(buffer, offset = 0) {
+  const tag = buffer[offset];
+  let cursor = offset + 1;
+  let length = buffer[cursor];
+  cursor += 1;
+  if (length & 0x80) {
+    const lengthBytes = length & 0x7f;
+    length = 0;
+    for (let i = 0; i < lengthBytes; i += 1) {
+      length = length * 256 + buffer[cursor];
+      cursor += 1;
+    }
+  }
+  const contentStart = cursor;
+  const end = contentStart + length;
+  const content = buffer.subarray(contentStart, end);
+  const constructed = (tag & 0x20) !== 0;
+  return {
+    tag,
+    length,
+    header: contentStart - offset,
+    contentStart,
+    end,
+    content,
+    children: constructed ? decodeDerSequence(content) : null,
+  };
+}
+
+/**
+ * Decode every element in a constructed value's content.
+ *
+ * @param {Buffer} content
+ * @returns {Array}
+ */
+export function decodeDerSequence(content) {
+  const elements = [];
+  let offset = 0;
+  while (offset < content.length) {
+    const element = decodeDerElement(content, offset);
+    elements.push(element);
+    offset = element.end;
+  }
+  return elements;
+}
+
+/** Format an OBJECT IDENTIFIER element's bytes as a dotted string. */
+export function oidToString(content) {
+  const first = Math.floor(content[0] / 40);
+  const second = content[0] % 40;
+  const parts = [first, second];
+  let value = 0;
+  for (let i = 1; i < content.length; i += 1) {
+    value = value * 128 + (content[i] & 0x7f);
+    if ((content[i] & 0x80) === 0) {
+      parts.push(value);
+      value = 0;
+    }
+  }
+  return parts.join('.');
+}