Sweet Cookie 🍪 — Browser cookies, without the native-addon crumbs

Sweet Cookie is a TypeScript library and CLI for reading cookies from inline payloads or local Chrome, Edge, Firefox, and Safari profiles. It is for local Node.js and Bun tools that need HTTP headers or browser-compatible cookie objects without native Node addons.

$ npx @steipete/sweet-cookie example.com --inline-json \
  '[{"name":"session","value":"demo","domain":"example.com","path":"/"}]' --format header
Cookie: session=demo

Install

Run the CLI without installing it:

npx @steipete/sweet-cookie --help

Or add the library to a project:

npm install @steipete/sweet-cookie

Node.js 22 or newer is required. The library also supports Bun through bun:sqlite.

Quick start

Inline cookies are deterministic and work on every supported platform. Sweet Cookie filters them to the requested URL and returns before reading local browser databases.

import { getCookies, toCookieHeader } from "@steipete/sweet-cookie";

const { cookies } = await getCookies({
	url: "https://example.com/",
	inlineCookiesJson: '[{"name":"session","value":"demo","domain":"example.com"}]',
});

console.log(toCookieHeader(cookies)); // session=demo

For a local browser profile, omit the inline payload and choose one or more backends:

import { getCookies } from "@steipete/sweet-cookie";

const { cookies, warnings } = await getCookies({
	url: "https://example.com/",
	names: ["session", "csrf"],
	browsers: ["chrome", "firefox"],
});

for (const warning of warnings) console.warn(warning);

Sources and browser support

Sweet Cookie checks inline JSON, base64, or file inputs first. The first inline source that yields cookies wins; otherwise, local browser backends run in order and either merge results or return the first successful result.

Source	macOS	Windows	Linux
Inline payload	✓	✓	✓
Chrome / Chromium	✓	✓	✓
Edge	✓	✓	✓
Firefox	✓	✓	✓
Safari	✓	—	—

Local reads copy browser databases before querying them with node:sqlite or bun:sqlite. Platform decryption uses the macOS Keychain, Windows DPAPI, or Linux keyring tools with bounded helper timeouts. Failures that do not invalidate the whole result are returned in warnings, without raw cookie values.

See the usage guide for source ordering, profile selection, environment variables, and platform details.

Profiles

Profile selectors accept a display name, profile directory, or cookie database path. Arrays read several selected profiles; ALL_PROFILES discovers every local profile supported by that backend.

import { ALL_PROFILES, getCookies } from "@steipete/sweet-cookie";

const { cookies } = await getCookies({
	url: "https://example.com/",
	browsers: ["chrome"],
	chromeProfile: ALL_PROFILES,
});

Chrome and Edge use their default profile when no selector is provided. Firefox prefers default-release; Safari has a cookie-file override rather than a profile selector.

Extension exporter

The Chrome Manifest V3 extension in apps/extension exports cookies from the current profile as JSON, base64, or a downloaded file. Use it when app-bound encryption, keychain prompts, remote execution, or another browser boundary prevents a local database read.

The extension requests host access when you export, runs only after a user action, makes no network requests, and stores no cookie values. Its payload is accepted directly through inlineCookiesJson, inlineCookiesBase64, or inlineCookiesFile. See the extension and payload specification.

Reference

• Usage and API guide
• Cookie extraction and extension specification
• Package API types
• Full CLI help

Development

Repository development requires Node.js 22.13 or newer and pnpm 11.18.

pnpm install --frozen-lockfile
pnpm check
pnpm build
pnpm test
pnpm test:bun

License

MIT. See packages/core/LICENSE.