browser-commander 0.20.0 → 0.21.1

package/src/browser/launcher.js

@@ -1,12 +1,19 @@
-import path from 'path';
-import os from 'os';
-import { disableTranslateInPreferences } from '../core/preferences.js';
+import { access } from 'node:fs/promises';
+
+import { assertSupportedEngine } from './connector.js';
 import { emulateMedia } from './media.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
   resolveChromeArgs,
 } from './launch-options.js';
+import {
+  createTemporaryUserDataDir,
+  removeUserDataDir,
+} from './profile-directory.js';
+import { launchRealBrowser } from './real-browser.js';
+import { resolveRestrictions } from './restrictions.js';
+import { resolveSystemBrowserExecutable } from './system-browser.js';
 import { applyFingerprint } from '../fingerprint/apply.js';
 import { attachDownloads } from '../downloads/attach.js';
 import {
@@ -15,171 +22,360 @@ import {
   restorePuppeteerStorageState,
 } from './storage-state.js';
 
+/** How `launchBrowser` starts the browser (issue #103). */
+export const LAUNCH_MODES = Object.freeze(['real', 'engine']);
+
+const loadEngine = {
+  playwright: async () => (await import('playwright')).chromium,
+  puppeteer: async () => (await import('puppeteer')).default,
+};
+
+function validateLaunchMode({ engine, launch, attach }) {
+  assertSupportedEngine(engine);
+  if (!LAUNCH_MODES.includes(launch)) {
+    throw new Error(
+      `Invalid launch mode: ${launch}. Expected 'real' or 'engine'`
+    );
+  }
+  if (attach !== undefined && launch !== 'real') {
+    throw new TypeError(
+      "attach needs launch: 'real'; an engine launch starts its own profile"
+    );
+  }
+}
+
+async function isExecutable(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pick the browser binary for a real launch.
+ *
+ * An explicit `executablePath` or `channel` is honoured as given. Without
+ * either, the installed Google Chrome is preferred - it is the browser a
+ * person would start - and the engine's own downloaded Chromium is the
+ * fallback, so a machine with only `npx playwright install` still works. The
+ * binary is spawned by Browser Commander either way, with the same clean
+ * command line.
+ */
+export async function resolveLaunchExecutable(
+  { engine, channel, executablePath },
+  { resolveSystem = resolveSystemBrowserExecutable, loadEngineModule } = {}
+) {
+  if (executablePath !== undefined || channel !== undefined) {
+    return await resolveSystem({
+      channel: channel ?? 'chrome',
+      executablePath,
+    });
+  }
+  try {
+    return await resolveSystem({ channel: 'chrome' });
+  } catch (error) {
+    const bundled = await (loadEngineModule ?? loadEngine[engine])()
+      .then((module) => module.executablePath())
+      .catch(() => undefined);
+    if (bundled && (await isExecutable(bundled))) {
+      return bundled;
+    }
+    throw error;
+  }
+}
+
+async function launchReal(options, dependencies) {
+  const {
+    engine,
+    channel,
+    executablePath,
+    slowMo,
+    verbose,
+    storageState,
+    ...rest
+  } = options;
+  const launchRealImplementation =
+    dependencies.launchRealBrowser ?? launchRealBrowser;
+  const session = await launchRealImplementation({
+    ...rest,
+    // The channel still names the browser whose profile an attach snapshot
+    // copies and a migration targets; the executable is resolved here.
+    ...(channel ? { channel } : {}),
+    engine,
+    verbose,
+    storageState,
+    executablePath: await resolveLaunchExecutable(
+      { engine, channel, executablePath },
+      dependencies
+    ),
+    ...(slowMo ? { slowMo } : {}),
+  });
+  const {
+    browser: connectedBrowser,
+    page,
+    close,
+    downloads: _none,
+    ...meta
+  } = session;
+  // Playwright's persistent-context launch returned a BrowserContext, so the
+  // real launch returns the attached default context the same way; closing
+  // it closes the browser this call started.
+  const browser =
+    engine === 'playwright' ? connectedBrowser.contexts()[0] : connectedBrowser;
+  if (browser !== connectedBrowser) {
+    browser.close = close;
+  }
+  return { browser, page, close, connectedBrowser, ...meta };
+}
+
+async function launchWithEngine(options, dependencies) {
+  const {
+    engine,
+    userDataDir: requestedUserDataDir,
+    headless,
+    slowMo,
+    args,
+    extraArgs,
+    ignoreDefaultArgs,
+    restrictions,
+    env,
+    colorScheme,
+    channel,
+    executablePath,
+    automationParity,
+    storageState,
+  } = options;
+  const chrome = resolveChromeArgs({
+    args,
+    extraArgs,
+    ignoreDefaultArgs,
+    restrictions,
+  });
+  const restrictionEnv = resolveRestrictions(restrictions).env;
+  const childEnv =
+    env || Object.keys(restrictionEnv).length > 0
+      ? { ...process.env, ...restrictionEnv, ...env }
+      : undefined;
+  const temporaryProfile = !requestedUserDataDir;
+  const userDataDir =
+    requestedUserDataDir ?? (await createTemporaryUserDataDir());
+  const engineModule = await (
+    dependencies.loadEngineModule ?? loadEngine[engine]
+  )();
+  const selection = { channel, executablePath };
+
+  let browser;
+  let page;
+  try {
+    if (engine === 'playwright') {
+      browser = await engineModule.launchPersistentContext(userDataDir, {
+        ...buildPlaywrightLaunchOptions({
+          headless,
+          slowMo,
+          chromeArgs: chrome.args,
+          colorScheme,
+          ...selection,
+          ignoreDefaultArgs: chrome.ignoreDefaultArgs,
+          automationParity,
+        }),
+        ...(childEnv ? { env: childEnv } : {}),
+      });
+      page = browser.pages()[0] ?? (await browser.newPage());
+      await restorePlaywrightStorageState({ context: browser, storageState });
+    } else {
+      browser = await engineModule.launch({
+        ...buildPuppeteerLaunchOptions({
+          headless,
+          chromeArgs: chrome.args,
+          userDataDir,
+          ...selection,
+          ignoreDefaultArgs: chrome.ignoreDefaultArgs,
+          automationParity,
+        }),
+        ...(slowMo ? { slowMo } : {}),
+        ...(childEnv ? { env: childEnv } : {}),
+      });
+      page = (await browser.pages())[0] ?? (await browser.newPage());
+      await restorePuppeteerStorageState({ page, storageState });
+    }
+  } catch (error) {
+    await browser?.close().catch(() => {});
+    if (temporaryProfile) {
+      await removeUserDataDir(userDataDir);
+    }
+    throw error;
+  }
+
+  const originalClose = browser.close.bind(browser);
+  let closing;
+  const close = () => {
+    closing ??= (async () => {
+      await originalClose().catch(() => {});
+      if (temporaryProfile) {
+        await removeUserDataDir(userDataDir);
+      }
+    })();
+    return closing;
+  };
+  browser.close = close;
+  return {
+    browser,
+    page,
+    close,
+    userDataDir,
+    temporaryProfile,
+    args: chrome.args,
+  };
+}
+
+async function unfocusAddressBar(page, verbose, settleMs = 500) {
+  // Bringing the page to front moves focus from the address bar to the page.
+  try {
+    await new Promise((resolve) => setTimeout(resolve, settleMs));
+    await page.bringToFront();
+    if (verbose) {
+      console.log('✅ Address bar unfocused automatically');
+    }
+  } catch (error) {
+    // Ignore errors - this is just a UX improvement
+    if (verbose) {
+      console.log('⚠️  Could not unfocus address bar:', error.message);
+    }
+  }
+}
+
 /**
- * Launch browser with default configuration
+ * Launch a browser.
+ *
+ * By default (`launch: 'real'`) Browser Commander starts the installed Chrome
+ * itself, exactly like a person who wants to attach a debugger would:
+ * `--user-data-dir=<fresh temporary profile> --remote-debugging-port=<reserved
+ * port>` and nothing else, then attaches the engine over CDP (issues #101 and
+ * #103). The profile is deleted on close. Every restriction the library used
+ * to add silently is an explicit opt-in through `restrictions`.
+ *
+ * `launch: 'engine'` keeps the Playwright/Puppeteer-launched browser for CI
+ * and headless use; the switches those engines add are listed in
+ * limitations.json (`engine-launch-switches`).
+ *
  * @param {Object} options - Configuration options
- * @param {string} options.engine - Browser automation engine: 'playwright' or 'puppeteer'
- * @param {string} options.userDataDir - Path to user data directory
- * @param {boolean} options.headless - Run in headless mode (default: false)
- * @param {number} options.slowMo - Slow down operations by ms (default: 150 for Playwright, 0 for Puppeteer)
- * @param {boolean} options.verbose - Enable verbose logging (default: false)
- * @param {string[]} options.args - Custom Chrome arguments to append to the default CHROME_ARGS
- * @param {string[]} [options.extraArgs] - Additional Chrome arguments appended after legacy args
- * @param {boolean|string[]} [options.ignoreDefaultArgs] - Browser Commander defaults to omit, or true for all
+ * @param {string} [options.engine='playwright'] - Browser automation engine: 'playwright' or 'puppeteer'
+ * @param {'real'|'engine'} [options.launch='real'] - Who starts the browser: Browser Commander (a hand-started command line) or the automation engine
+ * @param {string} [options.userDataDir] - Persistent profile directory. When omitted a fresh temporary profile is created and deleted on close.
+ * @param {boolean} [options.headless=false] - Run in headless mode
+ * @param {number} [options.slowMo=0] - Slow down operations by ms
+ * @param {boolean} [options.verbose=false] - Enable verbose logging
+ * @param {string[]} [options.restrictions] - Opt-in restrictions from launch-restrictions.json, such as 'no-extensions' or the 'legacy-defaults' preset
+ * @param {string[]} [options.args] - Additional Chrome arguments
+ * @param {string[]} [options.extraArgs] - Additional Chrome arguments appended after args
+ * @param {boolean|string[]} [options.ignoreDefaultArgs] - Engine default switches to omit, or true for all ('engine' launch only)
+ * @param {Object<string,string>} [options.env] - Extra environment for the browser process only
  * @param {string|null} [options.colorScheme] - Emulate color scheme: 'light', 'dark', 'no-preference', or null to reset
- * @param {string} [options.channel] - Installed browser channel, such as 'chrome', 'chrome-beta', or 'msedge'
+ * @param {string} [options.channel] - Installed browser channel, such as 'chrome', 'chrome-beta', 'msedge', 'brave' or 'chromium'
  * @param {string} [options.executablePath] - Explicit path to a Chrome or Chromium executable
+ * @param {number} [options.remoteDebuggingPort] - Fixed CDP port for the real launch; a free one is reserved when omitted
  * @param {string|Object} [options.storageState] - Playwright-compatible storage state path or object
  * @param {Object} [options.fingerprint] - Environment fields to present to pages, such as userAgent, timezone, locale, hardwareConcurrency or screen. Applied over CDP after launch; see src/fingerprint/profile.js for the full field list and presets.js for ready-made profiles.
- * @param {boolean} [options.automationParity=true] - Keep the command line indistinguishable from a hand-started Chrome. Turning this off restores the pre-parity switches and makes navigator.webdriver true.
+ * @param {boolean} [options.automationParity=true] - Keep navigator.webdriver false where a launch switch would turn it on (headless or engine launches)
  * @param {boolean|Object} [options.downloads] - Manage downloads: true for defaults, or {directory, persist, conflict}. The directory may be an absolute path, 'user-downloads' or 'temporary'.
- * @returns {Promise<{browser: Object, page: Object, downloads: Object|null}>} - Browser, page and the download manager when one was requested
+ * @returns {Promise<{browser: Object, page: Object, downloads: (Object|null), close: function(): Promise<void>, launch: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>}>} Browser (a BrowserContext for Playwright), page, download manager and launch metadata
  */
 export async function launchBrowser(options = {}) {
+  return await launchBrowserWithDependencies(options);
+}
+
+/** Dependency-injected implementation used by {@link launchBrowser} and tests. */
+export async function launchBrowserWithDependencies(
+  options = {},
+  dependencies = {}
+) {
   const {
     engine = 'playwright',
-    userDataDir = path.join(os.homedir(), '.hh-apply', `${engine}-data`),
+    launch = 'real',
     headless = false,
-    slowMo = engine === 'playwright' ? 150 : 0,
+    slowMo = 0,
     verbose = false,
     args = [],
     extraArgs = [],
     ignoreDefaultArgs = [],
+    restrictions = [],
     colorScheme,
-    channel,
-    executablePath,
     storageState,
     fingerprint,
     automationParity = true,
     downloads,
+    ...rest
   } = options;
-
-  const resolvedChromeArgs = resolveChromeArgs({
-    args,
-    extraArgs,
-    ignoreDefaultArgs,
-  });
-  const chromeArgs = resolvedChromeArgs.args;
-
-  if (!['playwright', 'puppeteer'].includes(engine)) {
-    throw new Error(
-      `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
-    );
-  }
-
+  validateLaunchMode({ engine, launch, attach: rest.attach });
+  // Validate arguments before anything is started or written to disk.
+  resolveChromeArgs({ args, extraArgs, ignoreDefaultArgs, restrictions });
   const resolvedStorageState = await loadStorageState(storageState);
 
-  // Set environment variables to suppress warnings
-  process.env.GOOGLE_API_KEY = 'no';
-  process.env.GOOGLE_DEFAULT_CLIENT_ID = 'no';
-  process.env.GOOGLE_DEFAULT_CLIENT_SECRET = 'no';
-
-  // Disable translate in Preferences
-  await disableTranslateInPreferences({ userDataDir });
-
   if (verbose) {
-    console.log(`🚀 Launching browser with ${engine} engine...`);
+    console.log(`🚀 Launching browser with ${engine} engine (${launch})...`);
   }
-
-  let browser;
-  let page;
-
-  if (engine === 'playwright') {
-    const { chromium } = await import('playwright');
-    const contextOptions = buildPlaywrightLaunchOptions({
-      headless,
-      slowMo,
-      chromeArgs,
-      colorScheme,
-      channel,
-      executablePath,
-      ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
-      automationParity,
-    });
-    browser = await chromium.launchPersistentContext(
-      userDataDir,
-      contextOptions
-    );
-    page = browser.pages()[0];
-    await restorePlaywrightStorageState({
-      context: browser,
-      storageState: resolvedStorageState,
-    });
-  } else {
-    const puppeteer = await import('puppeteer');
-    browser = await puppeteer.default.launch(
-      buildPuppeteerLaunchOptions({
-        headless,
-        chromeArgs,
-        userDataDir,
-        channel,
-        executablePath,
-        ignoreDefaultArgs: resolvedChromeArgs.ignoreDefaultArgs,
-        automationParity,
-      })
-    );
-    const pages = await browser.pages();
-    page = pages[0];
-    await restorePuppeteerStorageState({
-      page,
-      storageState: resolvedStorageState,
-    });
-  }
-
+  const common = {
+    ...rest,
+    engine,
+    headless,
+    slowMo,
+    verbose,
+    args,
+    extraArgs,
+    restrictions,
+    automationParity,
+    storageState: resolvedStorageState,
+  };
+  const launched =
+    launch === 'engine'
+      ? await launchWithEngine(
+          { ...common, ignoreDefaultArgs, colorScheme },
+          dependencies
+        )
+      : await launchReal(common, dependencies);
+  const { browser, page } = launched;
   if (verbose) {
     console.log(`✅ Browser launched with ${engine} engine`);
   }
 
-  // Apply color scheme emulation if requested (Puppeteer needs page-level emulation)
-  if (colorScheme !== undefined && engine === 'puppeteer') {
-    try {
-      await emulateMedia({ page, engine, colorScheme });
-      if (verbose) {
-        console.log(`✅ Color scheme set to "${colorScheme}"`);
-      }
-    } catch (error) {
-      if (verbose) {
-        console.log(`⚠️  Could not set color scheme: ${error.message}`);
-      }
+  try {
+    // A Playwright-launched context applies colorScheme itself; an attached
+    // browser and Puppeteer need page-level emulation.
+    const emulateColorScheme =
+      colorScheme !== undefined &&
+      (launch === 'real' || engine === 'puppeteer');
+    if (emulateColorScheme) {
+      await emulateMedia({ page, engine, colorScheme }).catch((error) => {
+        if (verbose) {
+          console.log(`⚠️  Could not set color scheme: ${error.message}`);
+        }
+      });
     }
-  }
 
-  // The fingerprint is applied before the caller can navigate, so the first
-  // document a page loads already sees the configured environment.
-  if (fingerprint !== undefined) {
-    await applyFingerprint({ browser, page, engine, profile: fingerprint });
-    if (verbose) {
-      console.log('✅ Fingerprint profile applied');
+    // The fingerprint is applied before the caller can navigate, so the first
+    // document a page loads already sees the configured environment.
+    if (fingerprint !== undefined) {
+      await applyFingerprint({ browser, page, engine, profile: fingerprint });
+      if (verbose) {
+        console.log('✅ Fingerprint profile applied');
+      }
     }
-  }
 
-  // Unfocus address bar automatically after browser launch
-  // Using page.bringToFront() - confirmed working solution
-  try {
-    // Wait for the browser to fully initialize
-    await new Promise((r) => setTimeout(r, 500));
+    await unfocusAddressBar(page, verbose, dependencies.settleMs);
 
-    // Bring page to front - this removes focus from address bar
-    await page.bringToFront();
-
-    if (verbose) {
-      console.log('✅ Address bar unfocused automatically');
-    }
+    // Downloads are armed before the caller can navigate: a download triggered
+    // by the first page load still lands in the managed directory.
+    const downloadManager = await attachDownloads({
+      engine,
+      browser,
+      page,
+      downloads,
+    });
+    return { ...launched, launch, downloads: downloadManager };
   } catch (error) {
-    // Ignore errors - this is just a UX improvement
-    if (verbose) {
-      console.log('⚠️  Could not unfocus address bar:', error.message);
-    }
+    await launched.close();
+    throw error;
   }
-
-  // Downloads are armed before the caller can navigate: a download triggered
-  // by the first page load still lands in the managed directory.
-  const downloadManager = await attachDownloads({
-    engine,
-    browser,
-    page,
-    downloads,
-  });
-
-  return { browser, page, downloads: downloadManager };
 }

package/src/browser/media.js

@@ -49,6 +49,11 @@ export async function emulateMedia({ page, engine, colorScheme } = {}) {
         { name: 'prefers-color-scheme', value: colorScheme },
       ]);
     }
+  } else if (engine === 'selenium') {
+    throw new Error(
+      'emulateMedia is not available with the selenium engine: WebDriver has ' +
+        'no media emulation command (see the webdriver-no-cdp-emulation limitation)'
+    );
   } else {
     throw new Error(
       `Unsupported engine: ${engine}. Expected 'playwright' or 'puppeteer'`

package/src/browser/migration/bookmarks.js

@@ -0,0 +1,73 @@
+import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathExists } from './fs-utils.js';
+
+/**
+ * Bookmarks migration.
+ *
+ * Chrome stores bookmarks as a single JSON file, `Bookmarks`, in the profile
+ * directory, with a `Bookmarks.bak` backup next to it. The file is
+ * self-contained (there is no companion database), so a migration copies it as
+ * is. Chrome recomputes the tamper-detection `checksum` in `Bookmarks` on the
+ * next launch, so the copy is accepted even though its checksum was written for
+ * the source profile.
+ */
+
+/**
+ * Count the bookmark entries in a Bookmarks JSON tree, for the report.
+ *
+ * @param {Object} bookmarks
+ * @returns {number}
+ */
+export function countBookmarks(bookmarks) {
+  let count = 0;
+  const visit = (node) => {
+    if (!node || typeof node !== 'object') {
+      return;
+    }
+    if (node.type === 'url') {
+      count += 1;
+    }
+    for (const child of node.children ?? []) {
+      visit(child);
+    }
+  };
+  for (const root of Object.values(bookmarks?.roots ?? {})) {
+    visit(root);
+  }
+  return count;
+}
+
+/**
+ * Copy the Bookmarks JSON 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 migrateBookmarks({ sourceProfileDir, targetProfileDir }) {
+  const source = path.join(sourceProfileDir, 'Bookmarks');
+  if (!(await pathExists(source))) {
+    return {
+      migrated: 0,
+      skipped: [
+        {
+          type: 'bookmarks',
+          item: 'Bookmarks',
+          reason: 'source-has-no-bookmarks',
+        },
+      ],
+      warnings: [],
+    };
+  }
+  let count = 0;
+  try {
+    count = countBookmarks(JSON.parse(await readFile(source, 'utf8')));
+  } catch {
+    // A count is best-effort; the copy is what matters.
+  }
+  await mkdir(targetProfileDir, { recursive: true });
+  await copyFile(source, path.join(targetProfileDir, 'Bookmarks'));
+  return { migrated: count, skipped: [], warnings: [] };
+}

package/src/browser/migration/chromium-crypto.js

@@ -0,0 +1,89 @@
+import { createCipheriv, randomBytes } from 'node:crypto';
+
+/**
+ * Re-encryption for Chromium os_crypt values (passwords, and any other value
+ * stored the same way as cookies).
+ *
+ * `browser-cookie-crypto.js` already decrypts these values; this module is the
+ * write side, so a value decrypted from the source profile can be encrypted for
+ * the dedicated target profile's key. It is dependency-injected end to end so
+ * the whole path is unit-testable on Linux with a fabricated key.
+ *
+ * The wire format matches what Chromium's `OSCrypt` writes:
+ * - macOS/Linux: a `v10`/`v11` prefix followed by AES-128-CBC with a fixed
+ *   16-byte IV of `0x20`. The key is PBKDF2-SHA1 of the Safe Storage password.
+ * - Windows: a `v10` prefix followed by a 12-byte nonce, AES-256-GCM
+ *   ciphertext, and the 16-byte auth tag. The key is the random 256-bit key in
+ *   `Local State` `os_crypt.encrypted_key`, itself DPAPI-protected.
+ *
+ * Unlike the Cookies database at schema version 24, `Login Data` values do not
+ * carry the SHA-256(host) domain-hash prefix, so nothing is prepended here.
+ */
+
+const CBC_IV = Buffer.alloc(16, 0x20);
+const GCM_NONCE_BYTES = 12;
+
+/**
+ * Encrypt a value the way Chromium's OSCrypt does for the given platform.
+ *
+ * @param {Object} options
+ * @param {string|Buffer} options.plaintext
+ * @param {Buffer} options.key
+ * @param {string} options.platform - 'darwin' | 'linux' | 'win32'
+ * @param {string} [options.prefix] - Version prefix ('v10' or 'v11')
+ * @returns {Buffer} The encrypted_value blob
+ */
+export function encryptChromiumValue({ plaintext, key, platform, prefix }) {
+  if (!Buffer.isBuffer(key)) {
+    throw new TypeError('a target encryption key is required');
+  }
+  const data = Buffer.isBuffer(plaintext)
+    ? plaintext
+    : Buffer.from(String(plaintext), 'utf8');
+  if (platform === 'win32') {
+    const nonce = randomBytes(GCM_NONCE_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
+    return Buffer.concat([
+      Buffer.from(prefix ?? 'v10'),
+      nonce,
+      ciphertext,
+      cipher.getAuthTag(),
+    ]);
+  }
+  if (platform === 'darwin' || platform === 'linux') {
+    const cipher = createCipheriv('aes-128-cbc', key, CBC_IV);
+    const ciphertext = Buffer.concat([cipher.update(data), cipher.final()]);
+    return Buffer.concat([Buffer.from(prefix ?? 'v10'), ciphertext]);
+  }
+  throw new Error(`Chromium value encryption is unsupported on ${platform}`);
+}
+
+/**
+ * Build the `os_crypt.encrypted_key` a fresh Windows profile needs.
+ *
+ * Chromium generates a random 256-bit key, DPAPI-protects it in the current
+ * user's context, prepends the ASCII tag `DPAPI`, and base64-encodes the result
+ * into `Local State`. This mirrors that so a target profile can decrypt values
+ * we re-encrypt with the returned raw key. `encryptDpapi` is injected so the
+ * generation is testable off Windows.
+ *
+ * @param {Object} [options]
+ * @param {function(Buffer): (Promise<Buffer>|Buffer)} [options.encryptDpapi]
+ * @param {function(): Buffer} [options.generateKey]
+ * @returns {Promise<{key: Buffer, encryptedKeyBase64: string}>}
+ */
+export async function createWindowsProfileKey({
+  encryptDpapi,
+  generateKey = () => randomBytes(32),
+} = {}) {
+  if (typeof encryptDpapi !== 'function') {
+    throw new TypeError(
+      'createWindowsProfileKey requires an encryptDpapi function'
+    );
+  }
+  const key = generateKey();
+  const protectedKey = Buffer.from(await encryptDpapi(key));
+  const tagged = Buffer.concat([Buffer.from('DPAPI'), protectedKey]);
+  return { key, encryptedKeyBase64: tagged.toString('base64') };
+}