# Cookie Sessions

How `SameSession` reads pages behind a login by decrypting cookies from your local Chrome profile and injecting them into a throwaway browser.

## Usage

```go
result, err := browser.Fetch(ctx, "https://example.com/profile", 60*time.Second, &browser.Option{
	SameSession: true,
	Profile:     "Default",
})
```

Your own Chrome is never touched: the cookie database is copied to a temporary directory first, and the browser that loads the page runs on that copy. `Profile` names a subdirectory of the Chrome profile root (`Default`, `Profile 1`, ...).

## Flow

```mermaid
graph TB
    A[launchWithSnapshot] --> B[Copy Cookies / -wal / -shm to temp dir]
    B --> C[Read Chrome Safe Storage password]
    C --> D[Derive 16-byte key with PBKDF2-SHA1]
    D --> E[Read cookies through sqlite3]
    E --> F[AES-128-CBC decrypt v10 values]
    F --> G[Launch Chrome on the temp profile]
    G --> H[SetCookies injection]
```

## Decryption and injection

| Parameter | Value |
|---|---|
| Password source (macOS) | `security find-generic-password -w -s "Chrome Safe Storage" -a Chrome` |
| Password source (Linux) | `secret-tool lookup application chrome`, then `application chromium` |
| Key derivation | PBKDF2-SHA1, salt `saltysalt`, 1003 iterations, 16-byte key |
| Cipher | AES-128-CBC, IV of 16 space characters, PKCS#7 padding |
| Encrypted marker | `v10` prefix; values without it are used as stored |
| Plaintext prefix | The first 32 bytes after decryption are stripped |

Each row of the `cookies` table becomes a CDP cookie with domain, path, expiry (converted from the WebKit epoch), `Secure`, `HTTPOnly` and `SameSite`. Rows that fail to decode are skipped.

### Injection

Cookies without a domain or name are dropped, and an empty path becomes `/`. If the batch injection fails, cookies are injected one by one and the run continues as long as at least one lands; zero successes returns `inject cookies (0/N)`.

## Failure behavior

| Situation | Result |
|---|---|
| Profile root unknown (not macOS/Linux) or `Profile` directory missing | Falls back to a regular cached browser without cookies |
| Keychain, `secret-tool`, `sqlite3` or launch failure | The error is returned; no fallback |
| Session ends | Browser closed and temporary directory removed, even on error |

Routing still applies: a `SameSession` call can be retried headed when blocked, and each attempt builds its own temporary profile. See [Fetch Routing](/core-concepts-routing).