browser-commander 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.23.0
+
+### Minor Changes
+
+- b56775b: Add Safari and Safari Technology Preview cookie sources, including installed,
+  default/auto and custom-directory import, counts-only domain discovery, validated
+  binarycookies decoding and actionable Full Disk Access errors. Migration reports
+  unsupported Safari classes and the SameSite Lax fallback. Other Safari stores,
+  Firefox/WebKit targets, full clones and additional data classes remain tracked in
+  issues #117–#120; this release does not claim full Safari profile import.
+
 ## 0.22.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Universal browser automation library that supports both Playwright and Puppeteer with a unified API",
   "main": "src/index.js",
   "bin": {

package/src/browser/browser-cookies.js

@@ -33,6 +33,11 @@ import {
   resolveSourceBrowser,
 } from './browser-profiles.js';
 import { resolveDefaultBrowser } from './default-browser.js';
+import {
+  countSafariCookies,
+  parseSafariCookies,
+  readSafariCookieFile,
+} from './safari-cookies.js';
 
 const CHROME_EPOCH_OFFSET_SECONDS = 11_644_473_600n;
 const MICROSECONDS_PER_SECOND = 1_000_000n;
@@ -319,6 +324,14 @@ export async function readBrowserCookiesWithDependencies(
     return cachedCookies;
   }
 
+  if (browserFamily(browser) === 'safari') {
+    const cookies = parseSafariCookies(
+      await readSafariCookieFile(cookiePath, { environment }),
+      options.domainFilter
+    );
+    await writeCookieResultCache({ cache, identity, cookies, now });
+    return cookies;
+  }
   const database = await openCookieDatabase(cookiePath);
   let cookies;
   try {
@@ -426,8 +439,15 @@ export async function listCookieSources({
     let error;
     let database;
     try {
-      database = await openCookieDatabase(cookiePath);
-      counts = countCookiesByDomain(database, family, domains);
+      if (family === 'safari') {
+        counts = countSafariCookies(
+          await readSafariCookieFile(cookiePath, { environment }),
+          domains
+        );
+      } else {
+        database = await openCookieDatabase(cookiePath);
+        counts = countCookiesByDomain(database, family, domains);
+      }
     } catch (openError) {
       error = openError.message;
     } finally {
@@ -514,12 +534,24 @@ export async function resolveImportSource({
     environment,
     runCommand,
   });
-  const holders = (
-    await listCookieSources({ domains, platform, homeDir, environment })
-  ).filter((source) => !source.error);
+  const listedSources = await listCookieSources({
+    domains,
+    platform,
+    homeDir,
+    environment,
+  });
+  const holders = listedSources.filter((source) => !source.error);
   const fromDefault = holders.filter(
     (source) => source.browser === systemDefault
   );
+  const unreadableDefault = listedSources.find(
+    (source) => source.browser === systemDefault && source.error
+  );
+  if (fromDefault.length === 0 && unreadableDefault) {
+    throw new Error(
+      `Could not inspect the default browser (${systemDefault}): ${unreadableDefault.error}`
+    );
+  }
   const candidates = fromDefault.length > 0 ? fromDefault : holders;
   if (candidates.length === 0) {
     if (!systemDefault) {

package/src/browser/browser-profiles.js

@@ -10,6 +10,7 @@ import {
   resolveBrowserRoots,
 } from './browser-sources.js';
 import { resolveDefaultBrowser } from './default-browser.js';
+import { findSafariCookieFile } from './safari-cookies.js';
 
 /**
  * Keywords that select the operating-system default browser instead of a named
@@ -112,6 +113,9 @@ function chromiumCookiePaths(profilePath, pathApi = path) {
 
 export async function findCookieDatabase(browser, profilePath, platform) {
   const pathApi = platformPath(platform ?? process.platform);
+  if (browserFamily(browser) === 'safari') {
+    return findSafariCookieFile(profilePath);
+  }
   if (browserFamily(browser) === 'firefox') {
     const candidate = pathApi.join(profilePath, 'cookies.sqlite');
     return (await pathExists(candidate)) ? candidate : null;
@@ -274,6 +278,20 @@ async function listProfilesForBrowser(browser, platform, homeDir, environment) {
   const family = browserFamily(browser);
   const profiles = [];
   for (const root of roots) {
+    if (family === 'safari') {
+      if (await findSafariCookieFile(root)) {
+        return [
+          {
+            browser,
+            name: 'Default',
+            displayName: 'Default',
+            path: root,
+            isDefault: true,
+          },
+        ];
+      }
+      continue;
+    }
     profiles.push(
       ...(family === 'firefox'
         ? await listFirefoxProfiles(browser, root, platform)

package/src/browser/browser-sources.json

@@ -394,6 +394,36 @@
         "darwin": ["org.floorp.Floorp"],
         "linux": ["floorp.desktop"]
       }
+    },
+    {
+      "id": "safari",
+      "family": "safari",
+      "aliases": ["apple-safari"],
+      "singleProfile": true,
+      "roots": {
+        "darwin": [
+          "{home}/Library/Containers/com.apple.Safari/Data/Library",
+          "{home}/Library"
+        ]
+      },
+      "default": {
+        "darwin": ["com.apple.safari"]
+      }
+    },
+    {
+      "id": "safari-technology-preview",
+      "family": "safari",
+      "aliases": ["safari-tp", "safari-preview"],
+      "singleProfile": true,
+      "roots": {
+        "darwin": [
+          "{home}/Library/Containers/com.apple.SafariTechnologyPreview/Data/Library",
+          "{home}/Library/Safari Technology Preview"
+        ]
+      },
+      "default": {
+        "darwin": ["com.apple.safaritechnologypreview"]
+      }
     }
   ]
 }

package/src/browser/migration/index.js

@@ -114,6 +114,34 @@ function mergeReport(report, className, fragment) {
   report.warnings.push(...(fragment.warnings ?? []));
 }
 
+function reportSafariClasses(report, selected) {
+  for (const type of ALL_DATA_CLASSES.filter(
+    (name) => name !== 'cookies' && selected.has(name)
+  )) {
+    report.skipped.push({
+      type,
+      item: report.source.browser,
+      reason:
+        type === 'passwords'
+          ? 'safari-password-export-required'
+          : 'safari-class-not-supported',
+      detail:
+        type === 'passwords'
+          ? 'Safari passwords live in the Keychain. Export Passwords from Safari or the Passwords app to CSV; CSV import is tracked separately and is not supported yet.'
+          : 'Safari currently supports cookie import only; this data class has not been translated.',
+    });
+  }
+  if (report.cookies.length > 0) {
+    report.warnings.push({
+      type: 'cookies',
+      item: report.source.browser,
+      reason: 'safari-samesite-unavailable',
+      detail:
+        'Cookies.binarycookies does not store SameSite; imported cookies use Lax.',
+    });
+  }
+}
+
 async function resolvePasswordKeys({
   keys,
   browser,
@@ -234,6 +262,11 @@ export async function migrateProfile({
     }
   }
 
+  if (browserFamily(browser) === 'safari') {
+    reportSafariClasses(report, selected);
+    return report;
+  }
+
   if (selected.has('bookmarks')) {
     mergeReport(
       report,

package/src/browser/safari-cookies.js

@@ -0,0 +1,173 @@
+/** Read Safari's unencrypted, mixed-endian Cookies.binarycookies store.
+ * Format: https://github.com/libyal/dtformats/blob/main/documentation/Safari%20Cookies.asciidoc
+ * No SameSite attribute is stored in this format; use Lax and report that loss.
+ */
+import { readFile as readFileBytes, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { TextDecoder } from 'node:util';
+
+const APPLE_EPOCH = 978_307_200;
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+function invalid(detail) {
+  throw new Error(`Invalid Safari binarycookies: ${detail}`);
+}
+
+function bounded(data, offset, size) {
+  if (offset < 0 || size < 0 || offset + size > data.length) {
+    invalid('truncated or out-of-range data');
+  }
+  return data.subarray(offset, offset + size);
+}
+
+function uint(data, offset, bigEndian = false) {
+  const bytes = bounded(data, offset, 4);
+  return bigEndian ? bytes.readUInt32BE() : bytes.readUInt32LE();
+}
+
+function string(record, field) {
+  const offset = uint(record, field);
+  if (offset < 56 || offset >= record.length) {
+    invalid('string offset');
+  }
+  const end = record.indexOf(0, offset);
+  if (end < 0) {
+    invalid('unterminated string');
+  }
+  try {
+    return utf8.decode(record.subarray(offset, end));
+  } catch {
+    return invalid('invalid UTF-8');
+  }
+}
+
+/** Validate all structural offsets before walking records; counts are bounded
+ * by the file size, so forged counts cannot cause unbounded allocations.
+ */
+function* records(data) {
+  if (bounded(data, 0, 4).toString('ascii') !== 'cook') {
+    invalid('file signature');
+  }
+  const pages = uint(data, 4, true);
+  bounded(data, 8, pages * 4);
+  let pageStart = 8 + pages * 4;
+  for (let index = 0; index < pages; index += 1) {
+    const page = bounded(data, pageStart, uint(data, 8 + index * 4, true));
+    pageStart += page.length;
+    if (uint(page, 0) !== 0x00010000) {
+      invalid('page signature');
+    }
+    const count = uint(page, 4);
+    const headerSize = 8 + count * 4;
+    bounded(page, 0, headerSize);
+    let previousEnd = headerSize;
+    for (let cookie = 0; cookie < count; cookie += 1) {
+      const start = uint(page, 8 + cookie * 4);
+      if (start < previousEnd) {
+        invalid('overlapping record');
+      }
+      const size = uint(page, start);
+      if (size < 56) {
+        invalid('short record');
+      }
+      const record = bounded(page, start, size);
+      previousEnd = start + size;
+      yield record;
+    }
+  }
+  // Safari may append a checksum and a plist trailer. They are not cookies.
+}
+
+/** Decode cookies in automation shape, using the existing substring filter. */
+export function parseSafariCookies(data, domainFilter) {
+  const cookies = [];
+  for (const record of records(data)) {
+    const domain = string(record, 16);
+    if (
+      domainFilter &&
+      !domain.toLowerCase().includes(domainFilter.toLowerCase())
+    ) {
+      continue;
+    }
+    const expiry = record.readDoubleLE(40) + APPLE_EPOCH;
+    if (
+      !Number.isFinite(expiry) ||
+      Math.abs(expiry) > Number.MAX_SAFE_INTEGER
+    ) {
+      invalid('expiry');
+    }
+    const flags = uint(record, 8);
+    cookies.push({
+      name: string(record, 20),
+      value: string(record, 28),
+      domain,
+      path: string(record, 24) || '/',
+      expires: Math.floor(expiry),
+      httpOnly: Boolean(flags & 4),
+      secure: Boolean(flags & 1),
+      sameSite: 'Lax',
+    });
+  }
+  return cookies;
+}
+
+/** Counts decode only domain strings. Names and values are never decoded. */
+export function countSafariCookies(data, domains) {
+  const byDomain = domains?.length
+    ? Object.fromEntries(domains.map((domain) => [domain, 0]))
+    : null;
+  let total = 0;
+  for (const record of records(data)) {
+    const host = string(record, 16).toLowerCase();
+    total += 1;
+    for (const domain of Object.keys(byDomain ?? {})) {
+      if (host.includes(domain.toLowerCase())) {
+        byDomain[domain] += 1;
+      }
+    }
+  }
+  return { total, byDomain };
+}
+
+/** A protected path is still a source: preserve it for an actionable read error. */
+export async function findSafariCookieFile(profileDir, statFile = stat) {
+  for (const candidate of [
+    path.join(profileDir, 'Cookies', 'Cookies.binarycookies'),
+    path.join(profileDir, 'Cookies.binarycookies'),
+  ]) {
+    try {
+      if ((await statFile(candidate)).isFile()) {
+        return candidate;
+      }
+    } catch (error) {
+      if (['EPERM', 'EACCES'].includes(error.code)) {
+        return candidate;
+      }
+      if (!['ENOENT', 'ENOTDIR'].includes(error.code)) {
+        throw error;
+      }
+    }
+  }
+  return null;
+}
+
+export async function readSafariCookieFile(
+  filePath,
+  { environment = process.env, readFile = readFileBytes } = {}
+) {
+  try {
+    return await readFile(filePath);
+  } catch (error) {
+    if (!['EPERM', 'EACCES'].includes(error.code)) {
+      throw error;
+    }
+    const app =
+      environment.__CFBundleIdentifier ||
+      environment.TERM_PROGRAM ||
+      process.execPath;
+    throw new Error(
+      `Safari cookie access denied (${error.code}) at ${filePath}. Grant Full Disk Access to ${app}, the app running Browser Commander, then retry: x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles`,
+      { cause: error }
+    );
+  }
+}

package/tests/unit/browser/safari-cookies.test.js

@@ -0,0 +1,246 @@
+// feature-parity: sources.safari-cookies@native-typed
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import { describe, it } from 'node:test';
+
+import {
+  listCookieSources,
+  readBrowserCookiesWithDependencies,
+  resolveImportSource,
+} from '../../../src/browser/browser-cookies.js';
+import { listBrowserProfiles } from '../../../src/browser/browser-profiles.js';
+import { migrateProfile } from '../../../src/browser/migration/index.js';
+import { runCli } from '../../../src/cli/main.js';
+import { runScript } from '../../../src/cli/script.js';
+import {
+  findSafariCookieFile,
+  parseSafariCookies,
+  readSafariCookieFile,
+} from '../../../src/browser/safari-cookies.js';
+import { repoPath } from '../../helpers/repo.js';
+import { useTempDirectories } from '../../helpers/temp-directory.js';
+
+const fixture = await readFile(
+  repoPath('tests/fixtures/safari/Cookies.binarycookies')
+);
+const expected = JSON.parse(
+  await readFile(repoPath('tests/fixtures/safari/expected.json'), 'utf8')
+);
+const makeDirectory = useTempDirectories();
+const safariDefault = async () =>
+  '( { LSHandlerURLScheme = https; LSHandlerRoleAll = "com.apple.Safari"; } )';
+
+async function installed(browser = 'safari', legacy = false) {
+  const homeDir = await makeDirectory('bc-safari-');
+  const bundle =
+    browser === 'safari'
+      ? 'com.apple.Safari'
+      : 'com.apple.SafariTechnologyPreview';
+  const root = legacy
+    ? path.join(homeDir, 'Library')
+    : path.join(homeDir, 'Library', 'Containers', bundle, 'Data', 'Library');
+  await mkdir(path.join(root, 'Cookies'), { recursive: true });
+  const file = path.join(root, 'Cookies', 'Cookies.binarycookies');
+  await copyFile(repoPath('tests/fixtures/safari/Cookies.binarycookies'), file);
+  return { homeDir, root, file, platform: 'darwin', environment: {} };
+}
+
+describe('Safari cookies', { timeout: 10000 }, () => {
+  it('decodes multiple pages, flags, UTF-8 and Apple epoch without guessing session cookies', () => {
+    assert.deepEqual(parseSafariCookies(fixture), expected);
+  });
+
+  it('rejects truncated data and forged counts, record sizes, offsets, strings and expiry', () => {
+    // The last eight bytes are an optional footer; every shorter prefix is invalid.
+    for (let end = 0; end < fixture.length - 8; end += 1) {
+      assert.throws(
+        () => parseSafariCookies(fixture.subarray(0, end)),
+        /Invalid Safari binarycookies/
+      );
+    }
+    for (const [offset, value] of [
+      [4, 0xffffffff],
+      [24, 0xffffffff],
+      [28, 0xffffffff],
+      [40, 0xffffffff],
+      [56, 0],
+    ]) {
+      const broken = Buffer.from(fixture);
+      broken.writeUInt32LE(value, offset);
+      assert.throws(
+        () => parseSafariCookies(broken),
+        /Invalid Safari binarycookies/
+      );
+    }
+    const broken = Buffer.from(fixture);
+    broken.writeDoubleLE(NaN, 80);
+    assert.throws(
+      () => parseSafariCookies(broken),
+      /Invalid Safari binarycookies/
+    );
+  });
+
+  it('reads both Safari variants and the legacy path without a keystore', async () => {
+    for (const [browser, legacy] of [
+      ['safari', false],
+      ['safari-technology-preview', false],
+      ['safari', true],
+    ]) {
+      const options = await installed(browser, legacy);
+      const before = await readFile(options.file);
+      const profiles = await listBrowserProfiles({ ...options, browser });
+      assert.equal(profiles[0].path, options.root);
+      const cookies = await readBrowserCookiesWithDependencies(
+        { browser, cache: false },
+        options
+      );
+      assert.deepEqual(cookies, expected);
+      assert.deepEqual(await readFile(options.file), before);
+    }
+  });
+
+  it('lists counts without decoding cookie values and supports default domain import', async () => {
+    const options = await installed();
+    const damagedValue = Buffer.from(fixture);
+    damagedValue[40 + damagedValue.readUInt32LE(68)] = 0xff;
+    await writeFile(options.file, damagedValue);
+    const sources = await listCookieSources({
+      ...options,
+      domains: ['GITHUB.COM'],
+    });
+    assert.equal(sources.length, 1);
+    assert.equal(sources[0].cookies, 4);
+    assert.deepEqual(sources[0].byDomain, { 'GITHUB.COM': 2 });
+    assert.ok(!JSON.stringify(sources).includes('fixture-token'));
+    await writeFile(options.file, fixture);
+    const source = await resolveImportSource({
+      ...options,
+      browser: 'default',
+      domains: ['github.com'],
+      runCommand: safariDefault,
+    });
+    assert.equal(source.browser, 'safari');
+    assert.equal(source.warning, null);
+    const report = await migrateProfile({
+      ...options,
+      from: { browser: 'auto' },
+      to: path.join(options.homeDir, 'target'),
+      domains: ['github.com', 'GITHUB.COM'],
+      runCommand: safariDefault,
+    });
+    assert.deepEqual(report.cookies, expected.slice(0, 2));
+    assert.equal(report.migrated.cookies, 2);
+    assert.equal(report.skipped.length, 5);
+    assert.equal(
+      report.skipped.find((entry) => entry.type === 'passwords').reason,
+      'safari-password-export-required'
+    );
+    assert.ok(
+      report.warnings.some(
+        (entry) => entry.reason === 'safari-samesite-unavailable'
+      )
+    );
+  });
+
+  it('reads an explicit source directory and reports actionable Full Disk Access errors', async () => {
+    const options = await installed();
+    const cookies = await readBrowserCookiesWithDependencies(
+      {
+        browser: 'safari',
+        profileDir: options.root,
+        domainFilter: 'github.com',
+        cache: false,
+      },
+      { homeDir: path.join(options.homeDir, 'empty') }
+    );
+    assert.deepEqual(cookies, expected.slice(0, 2));
+    const error = Object.assign(new Error('Operation not permitted'), {
+      code: 'EPERM',
+    });
+    assert.ok(
+      await findSafariCookieFile(options.root, async () => {
+        throw error;
+      })
+    );
+    await assert.rejects(
+      readSafariCookieFile(options.file, {
+        environment: { TERM_PROGRAM: 'TestTerminal' },
+        readFile: async () => {
+          throw error;
+        },
+      }),
+      /Full Disk Access.*TestTerminal.*x-apple.systempreferences:com.apple.preference.security\?Privacy_AllFiles/
+    );
+  });
+
+  it('preserves unreadable source errors instead of silently treating the default as empty', async () => {
+    const options = await installed();
+    await writeFile(options.file, Buffer.from('corrupt'));
+    const sources = await listCookieSources({
+      ...options,
+      domains: ['github.com'],
+    });
+    assert.match(sources[0].error, /Invalid Safari binarycookies/);
+    await assert.rejects(
+      resolveImportSource({
+        ...options,
+        browser: 'default',
+        domains: ['github.com'],
+        runCommand: safariDefault,
+      }),
+      /Could not inspect the default browser.*Invalid Safari binarycookies/
+    );
+  });
+
+  it('imports through the CLI and command-stream dispatcher using the real reader', async () => {
+    const options = await installed();
+    const to = path.join(options.homeDir, 'target');
+    const output = new PassThrough();
+    const chunks = [];
+    output.on('data', (chunk) => chunks.push(chunk.toString()));
+    const exitCode = await runCli(
+      [
+        'profile',
+        'migrate',
+        '--from',
+        'safari',
+        '--user-data-dir',
+        options.root,
+        '--include',
+        'cookies',
+        '--domain',
+        'github.com',
+        '--to',
+        to,
+      ],
+      {
+        stdout: output,
+        stdin: new PassThrough(),
+        signals: new EventEmitter(),
+      }
+    );
+    const report = JSON.parse(chunks.join(''));
+    assert.equal(exitCode, 0, JSON.stringify(report));
+    assert.deepEqual(report.cookies, expected.slice(0, 2));
+    const script = await runScript({
+      steps: [
+        {
+          method: 'profile.migrate',
+          params: {
+            from: 'safari',
+            userDataDir: options.root,
+            to,
+            include: ['cookies'],
+            domains: ['github.com'],
+          },
+        },
+      ],
+    });
+    assert.equal(script.failed, false, JSON.stringify(script));
+    assert.deepEqual(script.results[0].result.cookies, expected.slice(0, 2));
+    assert.deepEqual(await readFile(options.file), fixture);
+  });
+});