sweetcookie

README

sweetcookie

Go library to load cookies from local browser profiles.

Supported browsers

• Chromium-family: Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, Opera (macOS / Windows / Linux), Arc (macOS / Windows)
• Firefox (macOS / Windows / Linux)
• Safari (macOS only; reads Cookies.binarycookies)

Usage

package main

import (
	"context"
	"fmt"

	"github.com/steipete/sweetcookie"
)

func main() {
	res, err := sweetcookie.Get(context.Background(), sweetcookie.Options{
		URL:      "https://example.com/",
		Names:    []string{"session", "csrf"},
		Browsers: []sweetcookie.Browser{sweetcookie.BrowserChrome, sweetcookie.BrowserFirefox},
		Mode:     sweetcookie.ModeMerge,
	})
	if err != nil {
		panic(err)
	}
	for _, w := range res.Warnings {
		fmt.Println("warn:", w)
	}
	for _, c := range res.Cookies {
		fmt.Println(c.Source.Browser, c.Domain, c.Name, c.Value)
	}
}

Inline cookies (escape hatch for locked DBs / new encryption schemes):

res, _ := sweetcookie.Get(context.Background(), sweetcookie.Options{
	URL: "https://example.com/",
	Inline: sweetcookie.InlineCookies{
		File: "/path/to/cookies.json",
	},
	Mode: sweetcookie.ModeFirst,
})
_ = res

Notes

• Chrome-family cookie DBs can be locked; sweetcookie snapshots the DB + WAL sidecars before reading.
• macOS: derives legacy Chromium AES-128-CBC key from Keychain “Safe Storage” password via security.
• Windows: uses DPAPI to unwrap the Chromium master key from Local State and decrypts AES-256-GCM cookie values.
• Linux: tries go-keyring first, then shells out to secret-tool (GNOME) or kwallet-query + dbus-send (KDE) to read “Safe Storage”.
• Some very new Chromium Windows “app-bound” cookie encryption variants are not directly decryptable without extra OS-specific plumbing; use inline cookies for those cases.

Development

make ci

Documentation

Overview

Package sweetcookie loads cookies from local browser profiles (Chrome-family including Arc, Firefox, Safari).

This is intended for local tooling (CLI helpers, dev scripts, test harnesses). It reads local browser state, may trigger keychain/keyring prompts, and should not be used in server contexts.

Index

• Variables
• type Browser
  • func DefaultBrowsers() []Browser
• type Cookie
• type InlineCookies
• type Mode
• type Options
• type Result
  • func Get(ctx context.Context, opts Options) (Result, error)
• type SameSite
• type Source

Variables

var ErrNoOrigin = errors.New("sweetcookie: URL or Origins required (or AllowAllHosts)")

ErrNoOrigin is returned when neither URL nor Origins is set and AllowAllHosts is false.

Types

type Browser

type Browser string

Browser identifies a cookie source.

const (
	// BrowserInline is the inline cookie payload source.
	BrowserInline Browser = "inline"

	// BrowserChrome is Google Chrome.
	BrowserChrome Browser = "chrome"
	// BrowserChromium is Chromium.
	BrowserChromium Browser = "chromium"
	// BrowserEdge is Microsoft Edge.
	BrowserEdge Browser = "edge"
	// BrowserBrave is Brave Browser.
	BrowserBrave Browser = "brave"
	// BrowserVivaldi is Vivaldi.
	BrowserVivaldi Browser = "vivaldi"
	// BrowserOpera is Opera.
	BrowserOpera Browser = "opera"
	// BrowserArc is Arc Browser.
	BrowserArc Browser = "arc"

	// BrowserFirefox is Mozilla Firefox.
	BrowserFirefox Browser = "firefox"

	// BrowserSafari is Apple Safari (macOS only).
	BrowserSafari Browser = "safari"
)

func DefaultBrowsers

func DefaultBrowsers() []Browser

DefaultBrowsers returns a default source preference order.

type Cookie

type Cookie struct {
	Name     string
	Value    string
	Domain   string
	Path     string
	Secure   bool
	HTTPOnly bool
	SameSite SameSite

	Expires *time.Time
	Source  Source
}

Cookie is a browser cookie record.

type InlineCookies

type InlineCookies struct {
	// Exactly one of these is expected to be set. If multiple are set, JSON wins over Base64 over File.
	JSON   []byte
	Base64 string
	File   string
}

InlineCookies is an optional cookie payload source (JSON/base64/file).

type Mode

type Mode string

Mode controls how results from multiple sources are combined.

const (
	// ModeMerge merges results from all sources.
	ModeMerge Mode = "merge"
	// ModeFirst returns once at least one cookie is found.
	ModeFirst Mode = "first"
)

type Options

type Options struct {
	// URL is used to filter cookies by (scheme, host, path).
	// If empty, Origins must be set, or AllowAllHosts must be true.
	URL string

	// Origins are additional origins to consider (e.g. OAuth redirects).
	// If set, they are used for filtering alongside URL.
	Origins []string

	// Names is an allowlist of cookie names (empty means "all names").
	Names []string

	// Browsers is a source priority list. If empty, DefaultBrowsers() is used.
	Browsers []Browser

	// Mode controls how multiple sources are combined.
	Mode Mode

	// Profile overrides per-browser selection.
	// For Chromium-family: profile name (e.g. "Default"), profile dir, or explicit Cookies DB path.
	// For Firefox: profile name/dir, or explicit cookies.sqlite path.
	// For Safari: explicit Cookies.binarycookies path (macOS only).
	Profiles map[Browser]string

	// Inline is an optional source that is always tried before browser reads.
	Inline InlineCookies

	IncludeExpired bool
	AllowAllHosts  bool

	// Timeout for OS helper calls (keychain/keyring).
	Timeout time.Duration

	Debug bool
}

Options configures cookie loading and filtering.

type Result

type Result struct {
	Cookies  []Cookie
	Warnings []string
}

Result is returned by Get.

func Get

func Get(ctx context.Context, opts Options) (Result, error)

Get loads cookies from configured sources and returns a filtered, de-duplicated result.

type SameSite

type SameSite string

SameSite is the cookie SameSite attribute.

const (
	// SameSiteNone is SameSite=None.
	SameSiteNone SameSite = "None"
	// SameSiteLax is SameSite=Lax.
	SameSiteLax SameSite = "Lax"
	// SameSiteStrict is SameSite=Strict.
	SameSiteStrict SameSite = "Strict"
)

type Source

type Source struct {
	Browser    Browser
	Profile    string
	StorePath  string
	IsFallback bool
}

Source describes where a cookie came from.