browser-commander 0.20.0 → 0.21.0

package/src/browser/migration/preferences.js

@@ -0,0 +1,132 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists } from './fs-utils.js';
+
+/**
+ * Preferences migration.
+ *
+ * Chrome's `Preferences` file is a large JSON document. Copying it wholesale
+ * would drag machine- and session-specific state into the dedicated profile
+ * (window placement, the profile's own GAIA identity, per-profile paths), so a
+ * migration copies only a documented, portable subset and merges it into the
+ * target's existing `Preferences`.
+ *
+ * The subset is the settings a person recognizes as "my browser preferences":
+ *
+ * - `intl.accept_languages`   - the Accept-Language list.
+ * - `intl.selected_languages` - the UI language order.
+ * - `spellcheck.dictionaries` - enabled spellcheck dictionaries.
+ * - `default_search_provider_data` - a custom default search engine.
+ * - `browser.theme`           - the applied theme id and colors.
+ * - `extensions.theme`        - the theme extension bookkeeping.
+ * - `homepage`, `homepage_is_newtabpage` - the configured homepage.
+ * - `session.startup_urls`, `session.restore_on_startup` - the on-startup pages.
+ * - `bookmark_bar.show_on_all_tabs` - whether the bookmarks bar is always shown.
+ *
+ * `download.default_directory` is deliberately excluded: a path that exists on
+ * the source machine's account may not exist for the dedicated profile, and a
+ * migrated download location is more surprising than helpful.
+ *
+ * `Secure Preferences` (the file that carries a per-setting HMAC to detect
+ * tampering) is not touched; the settings above live in the plain `Preferences`
+ * file, which Chrome does not HMAC-protect.
+ */
+
+/** Dotted paths copied from the source Preferences into the target. */
+export const MIGRATED_PREFERENCE_PATHS = Object.freeze([
+  'intl.accept_languages',
+  'intl.selected_languages',
+  'spellcheck.dictionaries',
+  'default_search_provider_data',
+  'browser.theme',
+  'extensions.theme',
+  'homepage',
+  'homepage_is_newtabpage',
+  'session.startup_urls',
+  'session.restore_on_startup',
+  'bookmark_bar.show_on_all_tabs',
+]);
+
+function getPath(object, dottedPath) {
+  return dottedPath
+    .split('.')
+    .reduce(
+      (node, key) => (node && typeof node === 'object' ? node[key] : undefined),
+      object
+    );
+}
+
+function setPath(object, dottedPath, value) {
+  const keys = dottedPath.split('.');
+  let node = object;
+  for (const key of keys.slice(0, -1)) {
+    if (!node[key] || typeof node[key] !== 'object') {
+      node[key] = {};
+    }
+    node = node[key];
+  }
+  node[keys.at(-1)] = value;
+}
+
+/**
+ * Merge the selected subset of source Preferences into a target Preferences
+ * object (pure, so it is easy to unit-test).
+ *
+ * @param {Object} source - Parsed source Preferences
+ * @param {Object} target - Parsed target Preferences (mutated and returned)
+ * @param {string[]} [paths=MIGRATED_PREFERENCE_PATHS]
+ * @returns {{merged: Object, migratedPaths: string[]}}
+ */
+export function mergePreferenceSubset(
+  source,
+  target,
+  paths = MIGRATED_PREFERENCE_PATHS
+) {
+  const migratedPaths = [];
+  for (const dottedPath of paths) {
+    const value = getPath(source, dottedPath);
+    if (value !== undefined) {
+      setPath(target, dottedPath, value);
+      migratedPaths.push(dottedPath);
+    }
+  }
+  return { merged: target, migratedPaths };
+}
+
+/**
+ * Migrate the selected Preferences subset 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 migratePreferences({
+  sourceProfileDir,
+  targetProfileDir,
+}) {
+  const sourcePath = path.join(sourceProfileDir, 'Preferences');
+  if (!(await pathExists(sourcePath))) {
+    return {
+      migrated: 0,
+      skipped: [
+        { type: 'preferences', item: 'Preferences', reason: 'source-missing' },
+      ],
+      warnings: [],
+    };
+  }
+  const source = JSON.parse(await readFile(sourcePath, 'utf8'));
+  const targetPath = path.join(targetProfileDir, 'Preferences');
+  let target = {};
+  if (await pathExists(targetPath)) {
+    try {
+      target = JSON.parse(await readFile(targetPath, 'utf8'));
+    } catch {
+      target = {};
+    }
+  }
+  const { merged, migratedPaths } = mergePreferenceSubset(source, target);
+  await mkdir(targetProfileDir, { recursive: true });
+  await writeFile(targetPath, JSON.stringify(merged));
+  return { migrated: migratedPaths.length, skipped: [], warnings: [] };
+}

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

@@ -0,0 +1,138 @@
+import { copyFile, mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pathExists } from './fs-utils.js';
+
+import BetterSqlite3 from 'better-sqlite3';
+
+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.
+ */
+
+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
+ * deleted afterwards, and the source is never modified.
+ *
+ * @param {Object} options
+ * @param {string} options.sourcePath - Path to the source database
+ * @param {function(string): (Promise<T>|T)} options.read - Reader run against the snapshot copy
+ * @returns {Promise<T>}
+ * @template T
+ */
+export async function withDatabaseSnapshot({ sourcePath, read }) {
+  if (!(await pathExists(sourcePath))) {
+    throw new Error(`Source database does not exist: ${sourcePath}`);
+  }
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'browser-commander-snap-'));
+  const snapshotPath = path.join(dir, path.basename(sourcePath));
+  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.
+    let source;
+    try {
+      source = new BetterSqlite3(sourcePath, {
+        readonly: true,
+        fileMustExist: true,
+      });
+    } 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);
+    }
+
+    const readPath = copyFallback?.snapshotPath ?? snapshotPath;
+    return await read(readPath);
+  } finally {
+    if (copyFallback) {
+      await copyFallback.cleanup();
+    } else {
+      await cleanupDir();
+    }
+  }
+}
+
+/**
+ * Open a snapshot database read-only, run a reader, and close it.
+ *
+ * @param {Object} options
+ * @param {string} options.sourcePath
+ * @param {function(Object): (Promise<T>|T)} options.read
+ * @returns {Promise<T>}
+ * @template T
+ */
+export function readDatabaseSnapshot({ sourcePath, read }) {
+  return withDatabaseSnapshot({
+    sourcePath,
+    read: async (snapshotPath) => {
+      const db = await openSqliteDatabase(snapshotPath, {
+        readOnly: true,
+        fileMustExist: true,
+      });
+      try {
+        return await read(db);
+      } finally {
+        db.close();
+      }
+    },
+  });
+}

package/src/browser/open-in-user-browser.js

@@ -0,0 +1,112 @@
+import { runCommand } from '../utilities/subprocess.js';
+
+/**
+ * Hand a URL to the operating system's default browser with no automation
+ * (issue #102). This is the mode for flows where a consumer only needs the
+ * user to see and approve a page - an OAuth screen or a CLI web-login - in the
+ * browser where they are already signed in. Nothing is driven, nothing is
+ * migrated, and no dedicated profile is created.
+ *
+ * Each platform has one canonical opener:
+ * - macOS: `open <url>`
+ * - Linux: `xdg-open <url>` (the freedesktop.org standard launcher)
+ * - Windows: `explorer.exe <url>` (Explorer hands the URL to the registered
+ *   browser without a `cmd.exe` parser seeing its query string)
+ *
+ * All of them run through command-stream (issue #104) with exact argv
+ * boundaries and no shell in between, so a URL can never be reinterpreted as
+ * shell syntax.
+ */
+
+/** Platform openers as [file, ...fixedArgs]; the URL is appended last. */
+const PLATFORM_OPENERS = {
+  darwin: ['open'],
+  linux: ['xdg-open'],
+  win32: ['explorer.exe'],
+};
+
+/**
+ * URL schemes a browser will open. `open`/`xdg-open`/`start` will also happily
+ * launch a local application for another scheme, so the set is deliberately
+ * limited to what "open this page" means.
+ */
+const ALLOWED_PROTOCOLS = new Set([
+  'http:',
+  'https:',
+  'file:',
+  'ftp:',
+  'about:',
+  'chrome:',
+  'edge:',
+  'view-source:',
+]);
+
+/**
+ * Validate a URL string before it reaches an opener.
+ *
+ * A bare string that begins with `-` would be parsed by the opener as an
+ * option rather than a URL, so it is rejected outright; every other string
+ * has to parse as a URL with an allowed scheme.
+ *
+ * @param {string} url
+ * @returns {string} The validated URL
+ */
+export function validateOpenUrl(url) {
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new TypeError('openInUserBrowser requires a URL string');
+  }
+  if (url.startsWith('-')) {
+    throw new Error(
+      `Refusing to open ${JSON.stringify(url)}: a URL cannot start with "-", which an opener would read as an option`
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(
+      `Refusing to open ${JSON.stringify(url)}: it is not a valid absolute URL`
+    );
+  }
+  if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+    throw new Error(
+      `Refusing to open ${JSON.stringify(url)}: ${parsed.protocol} is not one of ${[...ALLOWED_PROTOCOLS].join(', ')}`
+    );
+  }
+  return url;
+}
+
+/**
+ * Build the exact command line for the platform's opener.
+ *
+ * @param {string} url - An already validated URL
+ * @param {string} platform - `process.platform` value
+ * @returns {string[]} `[file, ...args]`
+ */
+export function buildOpenCommand(url, platform) {
+  const opener = PLATFORM_OPENERS[platform];
+  if (!opener) {
+    throw new Error(
+      `openInUserBrowser is not supported on ${platform}; supported platforms are ${Object.keys(PLATFORM_OPENERS).join(', ')}`
+    );
+  }
+  return [...opener, url];
+}
+
+/**
+ * Open a URL in the user's default browser with no automation.
+ *
+ * @param {string} url - The page to open (http/https/file/ftp/about/...)
+ * @param {Object} [options]
+ * @param {string} [options.platform=process.platform] - Injectable for tests
+ * @param {function(string, Array<string>, Object=): Promise<any>} [options.runner=runCommand] - Injectable command runner
+ * @param {Object<string,string>} [options.env] - Environment for the opener process
+ * @returns {Promise<{opened: string, command: string[]}>} The opened URL and the exact command line used
+ */
+export async function openInUserBrowser(url, options = {}) {
+  const { platform = process.platform, runner = runCommand, env } = options;
+  const validated = validateOpenUrl(url);
+  const [file, ...args] = buildOpenCommand(validated, platform);
+  await runner(file, args, env ? { env } : {});
+  return { opened: validated, command: [file, ...args] };
+}