Get Chromium Cookies

A Bun library and CLI to read and decrypt cookies from Chromium-based browsers (Google Chrome, Chromium) on macOS.

It safely copies the cookie database to a temporary location, fetches the necessary decryption key from the macOS Keychain, and parses the cookies (including modern v10 encrypted values).

[!WARNING] Security & Privacy Warning

This tool is designed to access sensitive user data, including the system's Keychain and the browser's cookie database. It should be used responsibly and with a clear understanding of the security implications. Accessing this data without user consent can be a significant privacy violation.

Features

• Supports Google Chrome and Chromium
• Keychain Integration: Automatically fetches the correct decryption key from the macOS Keychain
• Modern Decryption: Correctly decrypts v10 cookies, including SHA-256 hash validation for newer Chrome formats
• Safe & Non-Destructive: Reads data from a temporary copy of the cookie database; never touches the original
• Domain Filtering: Easily fetch cookies for a specific domain (with smart subdomain matching)
• Profile Support: Can target specific browser profiles (e.g., Profile 1, Default)
• Dual Use: Use as a library or a standalone CLI tool

Prerequisites

• Operating system: macOS only
• Runtime: Bun ≥ 1.0
• No native module compilation — uses Bun's built-in bun:sqlite, so install is just bun install (no node-gyp, no native bindings)

Installation

bun add @mpelka/get-cookies

[!NOTE] Keychain Access Prompt

The first time you run this tool, macOS will prompt for your user password to grant access to the browser's "Safe Storage" entry in your Keychain. You may be prompted twice.

Library usage

import { getChromiumCookiesMacOS } from "@mpelka/get-cookies";

const cookies = await getChromiumCookiesMacOS(
  "chrome",      // 'chrome' | 'chromium'
  "Default",     // profile name; optional, defaults to 'Default'
  "github.com",  // optional domain filter
);

getChromiumCookiesMacOS(browserId, profileName?, domainFilter?)

• browserId — 'chrome' or 'chromium'.
• profileName (optional) — browser profile name. Defaults to 'Default'.
• domainFilter (optional) — domain to filter cookies for (e.g. 'github.com'). Smart matching: passing api.github.com also matches .github.com parent-domain cookies. If omitted, all cookies are returned.

Returns Promise<Cookie[]>.

interface Cookie {
  name: string;
  value: string;
  domain: string;
  path: string;
  expires: number | null; // Unix timestamp (seconds) or null
  secure: boolean;
  httpOnly: boolean;
}

CLI usage

bun x @mpelka/get-cookies github.com
bun x @mpelka/get-cookies google.com chromium
bun x @mpelka/get-cookies developer.mozilla.org chrome "Profile 2"

Output: JSON array of cookie objects.

Migrating from v1

v1 (1.x) ran on Node.js and used the native sqlite3 npm package, which required a native compile step that caused install pain (especially under Bun, which doesn't run npm install scripts by default).

v2 (2.x) is Bun-only and uses bun:sqlite, which ships with Bun. Net result: no native binary download, no node-gyp, no compile step — bun add @mpelka/get-cookies and you're done.

Public API is unchanged. Consumers just need to be running on Bun.

License

MIT