Browser Cookie Migrator

简体中文

Browser Cookie Migrator transfers cookies between browser profiles through a local encrypted file. It runs as a WebExtension and works with records exposed by the browser's Cookies API.

Cookies can act as account credentials. Review a fixed tag or commit before loading the extension, import only your own export files, and delete them after use. Official packages are not published to extension stores.

How it works

1. Read cookies from the source profile's default store, optionally limited to selected domains.
2. Encrypt the export as a local .bcm file.
3. Decrypt and classify the file in the target profile without writing any cookies.
4. Skip expired, invalid, unsupported, lossy, and observed collision records.
5. Write exact records and read them back for verification.

The extension page uses no remote resources or application network requests. Its content security policy sets connect-src 'none'. Diagnostic logs contain reason codes, timestamps, counts, and browser capability data; cookie names, values, domains, URLs, file names, passphrases, and raw browser errors are excluded.

Browser support

Browser	Minimum version	Build directory
Chrome and Chromium derivatives	Chromium 119	dist/chromium
Firefox	Firefox 142	dist/firefox

The Chromium build covers Chrome, Brave, Arc, Dia, Comet, Edge, and similar desktop browsers that retain the standard extension API. Browser forks may impose additional limits. Firefox has a separate manifest and adapter for its Promise API, partition keys, and first-party isolation fields.

Field-level behavior and tested versions are listed in browser compatibility.

Install from source

Use a revision you have reviewed. Node.js 20 or later is required for the build; the project has no runtime dependencies.

git clone https://github.com/luwux/browser-cookie-migrator.git
cd browser-cookie-migrator
git checkout <reviewed-tag-or-commit>
npm run build

For a Chromium browser:

1. Open the extensions page and enable Developer mode.
2. Choose Load unpacked.
3. Select dist/chromium.

For Firefox:

1. Open about:debugging#/runtime/this-firefox.
2. Choose Load Temporary Add-on.
3. Select dist/firefox/manifest.json.

Firefox removes the temporary add-on when the browser exits. This project does not distribute a signed Firefox package.

Usage

Load the same reviewed revision in both profiles.

In the source profile, enter one or more domains, or explicitly confirm a full default-store export. Set a unique passphrase of at least 20 characters, review the match summary, and save the .bcm file.

In the target profile, select the file and enter its passphrase. Inspect file reports the exact, lossy, unsupported, expired, invalid, and collision totals. Import exact matches writes the exact, non-colliding set.

Run imports in an idle or new profile. Confirm the account shown by important sites afterward. If an operation is interrupted, check the extension's site-access setting and revoke any remaining access manually.

Security

• New .bcm files use AES-256-GCM with a random salt and IV. PBKDF2-HMAC-SHA256 derives the key with 600,000 iterations.
• The manifest declares the cookies permission. <all_urls> is optional host access. The extension requests it during an operation and attempts to revoke it on release, page disconnect, and background startup.
• Import skips target identities observed during collision checks and verifies each write. The Cookies API has no atomic set-if-absent operation, so concurrent browser activity can still create a race.
• .bcm encryption detects modification. The format carries no source signature, and anyone with the passphrase can create a valid file. Import only your own exports.
• Migration covers Cookies API records in the default store. Passwords, bookmarks, history, passkeys, extensions, site storage, private stores, and Firefox Containers are outside its scope.

The project has not received an independent security audit. See the threat model for the full boundary and SECURITY.md for private vulnerability reporting.

Validation

Node tests cover the encrypted format, input limits, cookie identity, collision handling, classification, permission cleanup, and browser adapters.

Browser smoke tests use disposable profiles and synthetic cookies on reserved example domains. Chrome, Brave, Arc, Dia, Comet, and Firefox passed standard and partitioned-cookie round trips. Commands, tested versions, and coverage are recorded in browser compatibility.

Development

npm test
npm run build
npm run check
npm run smoke:chromium
npm run smoke:firefox

The build script copies an explicit source allowlist into dist/chromium and dist/firefox, then checks the manifest security contract and output file set. Test fixtures must use synthetic values and reserved domains. See CONTRIBUTING.md.

Additional documentation:

• Compatibility and validation
• Threat model
• Encrypted file format
• Project research

License

MIT