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

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.

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);

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. If an inline source contains cookies whose isolation cannot be preserved and no later inline source yields cookies, extraction returns an empty result rather than falling back to local browser stores.

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.

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.

On Linux, the Chrome backend searches native and Flatpak Google Chrome roots by default. Set chromiumBrowser to target native or container roots for Chromium or Brave. Firefox searches its native, Snap, and Flatpak profile roots.

Returned cookies preserve hostOnly: host-only cookies match exactly one hostname, while domain cookies may match subdomains. Scope is also part of deduplication, so host-only and domain cookies with the same name, normalized domain, and path remain distinct.

Both scoped records can therefore appear in a library result. toCookieHeader() retains both by default; pass { dedupeByName: true }, as the CLI does, when the target requires one value per cookie name.

Sweet Cookie excludes Chromium partitioned cookies and Firefox partitioned or container-scoped cookies from local database reads because an ordinary replay cannot preserve their isolation context. Inline payloads carrying partition or container provenance are rejected with a warning for the same reason.

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.

Build the extension and load the generated apps/extension/dist directory in Chrome; the source directory is not loadable as-is. Follow the build and loading instructions.

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.

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

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

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

MIT. See packages/core/LICENSE.