Metadata-Version: 2.5
Name: graftpunk
Version: 1.18.0
Summary: Authenticated browser sessions, captured once and replayed over plain HTTP: stealth login, encrypted at rest, pluggable storage.
Project-URL: Homepage, https://github.com/stavxyz/graftpunk
Project-URL: Repository, https://github.com/stavxyz/graftpunk
Project-URL: Documentation, https://github.com/stavxyz/graftpunk#readme
Project-URL: Changelog, https://github.com/stavxyz/graftpunk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/stavxyz/graftpunk/issues
Author-email: stavxyz <stavxyz@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,automation,browser,cdp,csrf,har,nodriver,requests,scraping,selenium,session
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: brotli>=1.1.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: dill>=0.3.0
Requires-Dist: fpdf2>=2.8.0
Requires-Dist: idna>=3.0
Requires-Dist: packaging>=23.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pyotp>=2.9.0
Requires-Dist: python-slugify>=8.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: rich>=13.0.0
Requires-Dist: structlog>=23.0.0
Requires-Dist: typer>=0.21
Requires-Dist: xlsxwriter>=3.0.0
Provides-Extra: all
Requires-Dist: boto3>=1.34.0; extra == 'all'
Requires-Dist: cssselect>=1.2.0; extra == 'all'
Requires-Dist: httpie>=3.0.0; extra == 'all'
Requires-Dist: jmespath>=1.0.0; extra == 'all'
Requires-Dist: lxml>=5.0.0; extra == 'all'
Requires-Dist: mypy>=1.10.0; extra == 'all'
Requires-Dist: nodriver>=0.48; extra == 'all'
Requires-Dist: openpyxl>=3.1.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
Requires-Dist: pytest-mock>=3.0.0; extra == 'all'
Requires-Dist: pytest-xdist>=3.0.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: requestium>=0.2.5; extra == 'all'
Requires-Dist: ruff>=0.5.0; extra == 'all'
Requires-Dist: selenium-stealth>=1.0.6; extra == 'all'
Requires-Dist: selenium>=4.0.0; extra == 'all'
Requires-Dist: supabase>=2.10.0; extra == 'all'
Requires-Dist: undetected-chromedriver>=3.5.0; extra == 'all'
Requires-Dist: webdriver-manager>=4.0.0; extra == 'all'
Provides-Extra: browser
Requires-Dist: httpie>=3.0.0; extra == 'browser'
Requires-Dist: nodriver>=0.48; extra == 'browser'
Requires-Dist: requestium>=0.2.5; extra == 'browser'
Requires-Dist: selenium-stealth>=1.0.6; extra == 'browser'
Requires-Dist: selenium>=4.0.0; extra == 'browser'
Requires-Dist: undetected-chromedriver>=3.5.0; extra == 'browser'
Requires-Dist: webdriver-manager>=4.0.0; extra == 'browser'
Provides-Extra: dev
Requires-Dist: cssselect>=1.2.0; extra == 'dev'
Requires-Dist: httpie>=3.0.0; extra == 'dev'
Requires-Dist: lxml>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: nodriver>=0.48; extra == 'dev'
Requires-Dist: openpyxl>=3.1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.0.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: requestium>=0.2.5; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: selenium-stealth>=1.0.6; extra == 'dev'
Requires-Dist: selenium>=4.0.0; extra == 'dev'
Requires-Dist: undetected-chromedriver>=3.5.0; extra == 'dev'
Requires-Dist: webdriver-manager>=4.0.0; extra == 'dev'
Provides-Extra: jmespath
Requires-Dist: jmespath>=1.0.0; extra == 'jmespath'
Provides-Extra: nodriver
Requires-Dist: httpie>=3.0.0; extra == 'nodriver'
Requires-Dist: nodriver>=0.48; extra == 'nodriver'
Requires-Dist: requestium>=0.2.5; extra == 'nodriver'
Requires-Dist: selenium-stealth>=1.0.6; extra == 'nodriver'
Requires-Dist: selenium>=4.0.0; extra == 'nodriver'
Requires-Dist: undetected-chromedriver>=3.5.0; extra == 'nodriver'
Requires-Dist: webdriver-manager>=4.0.0; extra == 'nodriver'
Provides-Extra: s3
Requires-Dist: boto3>=1.34.0; extra == 's3'
Provides-Extra: supabase
Requires-Dist: supabase>=2.10.0; extra == 'supabase'
Description-Content-Type: text/markdown

<div align="center">

# 🔌 graftpunk

**Authenticated browser sessions, captured once and replayed over plain HTTP: stealth login, encrypted at rest, pluggable storage.**

[![PyPI](https://img.shields.io/pypi/v/graftpunk.svg)](https://pypi.org/project/graftpunk/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Typed](https://img.shields.io/badge/typed-ty-blue.svg)](https://github.com/astral-sh/ty)

[Installation](#installation) • [Quick Start](#quick-start) • [Plugins](#plugins) • [CLI Reference](#cli-reference) • [Examples](https://github.com/stavxyz/graftpunk/blob/main/examples/README.md) • [Architecture](https://github.com/stavxyz/graftpunk/blob/main/docs/HOW_IT_WORKS.md)

</div>

Log in through a real browser once; graftpunk captures the authenticated session — cookies, browser-fingerprinted headers, CSRF/API tokens — encrypts it at rest, and replays it over plain HTTP from Python or a generated CLI, so a site's own XHR/JSON endpoints become scriptable without a WebDriver in the loop.

---

## The Problem

Plenty of services you have an account with expose no API — an ISP portal, a school or medical portal, a niche shop, a municipal records site. The data is yours and it is one login away, but every request has to look like it came from a browser that already signed in: the right cookies, the browser's own headers, whatever CSRF or bearer token the page minted. Reproducing that by hand for every script is the actual chore.

## The Solution

graftpunk does the login in a real browser (yours, or a declaratively scripted one), captures the resulting session and header fingerprint, stores it encrypted, and hands it back as a `requests`-compatible session — locally, or from S3/Supabase when the same session needs to be shared.

```
  1. LOG IN              2. CACHE               3. SCRIPT

  +-------------+       +-------------+       +-------------+
  |   Browser   |       |  Encrypted  |       |   Python    |
  |   Session   |------>|   Storage   |------>|   Script    |
  |             |       |             |       |             |
  +-------------+       +-------------+       +-------------+

  Log in manually       Session cached        Use the session
  or declaratively      with AES-128          with real browser
  via plugin config     encryption            headers replayed
```

Once your session is cached, you can:

- **Make HTTP requests** with your authenticated cookies *and* real browser headers
- **Reverse-engineer XHR calls** from browser dev tools
- **Build CLI tools** that feel like real APIs
- **Automate downloads** of documents and data
- **Keep sessions alive** with background daemons
- **Capture network traffic** for debugging and auditing

## What You Can Build

Each of these is a plugin command backed by the cached session; graftpunk generates the CLI, injects the session and tokens, and formats the output:

```bash
# Pull your kid's grades and assignments
gp schoolportal grades --student emma --format table

# Download your medical lab results
gp mychart labs --after 2024-06-01 --output ./results/

# Export your energy usage data
gp utility usage --months 12 --format csv > energy.csv

# Scrape your property tax history
gp county assessor --parcel 12345 --format json

# Make ad-hoc requests with cached session cookies + browser headers
gp http get -s mychart https://mychart.example.com/api/appointments
```

These aren't real APIs—they're commands defined in graftpunk plugins that replay the same XHR calls the website makes. To the server, it looks like a browser. To you, it's just automation.

## Installation

Logging in drives a real browser, so the usual install includes the browser stack:

```bash
pip install 'graftpunk[browser]'
```

**Lite install** — no browser:

```bash
pip install graftpunk
```

This gives you the full `gp` CLI and API replay against an **already-cached**
session (`load_session_for_api`, `load_session_for_api_from_bytes`). It cannot
log in, because that needs a browser. Base dependencies are pure-Python or ship
WASM wheels, so this is also the install that works under Pyodide and Cloudflare
Python Workers ([#121](https://github.com/stavxyz/graftpunk/issues/121)). Add
`[browser]` whenever you need `gp <site> login` or `BrowserSession`.

**With cloud storage:**

```bash
pip install graftpunk[supabase]   # Supabase backend
pip install graftpunk[s3]         # AWS S3 backend
pip install graftpunk[all]        # Everything (includes browser)
```

## Quick Start

### 1. Cache a Session

The fastest way is with a plugin. Here's the httpbin example (no auth needed):

```bash
# Drop a YAML plugin into your plugins directory
mkdir -p ~/.config/graftpunk/plugins
cp examples/plugins/httpbin.yaml ~/.config/graftpunk/plugins/

# Use it immediately
gp httpbin ip
gp httpbin headers
gp httpbin status --code 418  # I'm a teapot!
```

For sites that require authentication, plugins can define declarative login:

```bash
# Log in via auto-generated command (opens browser, fills form, caches session)
gp quotes login

# Use the cached session for API calls
gp quotes list
gp quotes random
```

### 2. Use It Programmatically

```python
from graftpunk import GraftpunkClient

# Use plugin commands from Python — same session, tokens, and retries as the CLI
with GraftpunkClient("mybank") as client:
    accounts = client.accounts()
    statements = client.statements(month="january", year=2024)

    # Grouped commands use nested attribute access
    detail = client.accounts.detail(id=42)
```

For lower-level access without plugins, load a session directly:

```python
from graftpunk import load_session_for_api

# Returns a GraftpunkSession with browser headers pre-loaded
api = load_session_for_api("mysite")
response = api.get("https://app.example.com/api/internal/documents")
```

If you already hold the encrypted session blob and can't reach graftpunk's
storage or key file — a Cloudflare Python Worker that read it through an R2
binding, say — go straight from bytes:

```python
from graftpunk import load_session_for_api_from_bytes

api = load_session_for_api_from_bytes(encrypted_bytes, key=fernet_key)
response = api.get("https://app.example.com/api/internal/documents")
```

Both work on the lite install (no `[browser]`). `key=` is optional and defaults
to graftpunk's configured key sources; pass it when the key lives somewhere
graftpunk can't see, like a Worker secret. A bad key raises `EncryptionError`
(fix the key); an unusable session raises `SessionExpiredError` (log in again).

### 3. Keep It Alive

Sessions expire. graftpunk can keep them alive in the background with the keepalive daemon.

## Features

| | Feature | Why It Matters |
|:--|:--|:--|
| 🥷 | **Stealth Mode** | Multiple backends: Selenium with undetected-chromedriver, or NoDriver for CDP-direct automation without WebDriver detection. Bot-detection cookies (Akamai, etc.) are automatically filtered during cookie injection to prevent WAF rejection. |
| 🔒 | **Encrypted Storage** | Sessions encrypted with AES-128 (Fernet). Local by default, optional cloud storage. |
| 🔑 | **Declarative Login** | Define login flows with CSS selectors. graftpunk opens the browser, fills the form, and caches the session. Works in both Python and YAML plugins. |
| 🌐 | **Browser Header Replay** | Captures real browser headers during login and replays them in API calls. Requests look like they came from Chrome, not Python. |
| 🔌 | **Plugin System** | Full command framework with `CommandContext`, resource limits, output formatting, and auto-generated CLI. Python for complex logic, YAML for simple calls. |
| 🛡️ | **Token & CSRF Support** | Declarative token extraction from cookies, headers, or page content. EAFP injection with automatic 403 retry. Tokens cached through session serialization. |
| 📡 | **Observability** | Capture screenshots, HAR files, console logs, and network traffic. Interactive mode lets you browse manually while recording. |
| 🔄 | **Keepalive Daemon** | Background daemon pings sites periodically to prevent session timeout. |
| 🛠️ | **Ad-hoc HTTP** | `gp http get -s <session> <url>` — make one-off authenticated requests without writing a plugin. |
| 📊 | **Multi-View Output** | Commands can define multiple views on response data. Table format renders each view as a separate section. XLSX creates one worksheet per view. `--view` lets you cherry-pick views and columns. |
| 🎨 | **Beautiful CLI** | Rich terminal output with spinners, tables, and color. `--format json\|table\|csv\|xlsx\|raw` on all commands. |

## Plugins

A plugin turns one site into a CLI command group. It declares where the site is, how to log in, and what each command fetches; graftpunk supplies the browser login, the cached session, the browser headers, tokens, retries, and output formatting. Write one in Python for anything with logic in it, or in YAML for plain REST calls. Both support declarative login, resource limits, and output formatting.

Plugins are discovered from three sources: Python packages registered on the `graftpunk.plugins` entry-point group, YAML files in `~/.config/graftpunk/plugins/` (`*.yaml`, `*.yml`), and Python files in the same directory (`*.py`). Two plugins sharing a `site_name` is an error naming both sources, never a silent shadowing. **[Writing a graftpunk plugin](docs/PLUGIN_DEVELOPMENT.md)** is the guide: naming, recording a site, reading the recording, scaffolding, implementing, login, secrets, and tests.

### YAML Plugin (Simple REST Calls)

For straightforward HTTP calls, no Python needed:

```yaml
# ~/.config/graftpunk/plugins/mybank.yaml
site_name: mybank
base_url: "https://secure.mybank.example.com"

login:
  url: /login
  fields:
    username: "input#email"
    password: "input#password"
  submit: "button[type=submit]"

commands:
  accounts:
    help: "List all accounts"
    method: GET
    url: "/api/accounts"
    jmespath: "accounts[].{id: id, name: name, balance: balance}"

  statements:
    help: "Get statements for a month"
    method: GET
    url: "/api/statements"
    params:
      - name: month
        required: true
        help: "Month name"
      - name: year
        type: int
        default: 2024
    timeout: 30
    max_retries: 2
```

### Python Plugin (Complex Logic)

```python
from graftpunk.plugins import CommandContext, LoginConfig, LoginStep, SitePlugin, command


class MyBankPlugin(SitePlugin):
    site_name = "mybank"
    base_url = "https://secure.mybank.example.com"
    backend = "nodriver"  # or "selenium"
    api_version = 1

    login_config = LoginConfig(
        url="/login",
        steps=[
            LoginStep(
                fields={"username": "input#email", "password": "input#password"},
                submit="button[type=submit]",
            ),
        ],
        success=".dashboard",
        # The post-submit wait polls for these until it sees them, or gives up
        # after timeout seconds (30 by default).
        success_url="*/dashboard*",
    )

    @command(help="List all accounts")
    def accounts(self, ctx: CommandContext):
        return ctx.request_json("GET", "/api/accounts")

    @command(help="Get statements for a month")
    def statements(self, ctx: CommandContext, month: str, year: int = 2024):
        return ctx.request_json("GET", f"/api/statements/{year}/{month}")
```

### Using Plugins

```bash
# Login (auto-generated from declarative config)
gp mybank login

# Run commands
gp mybank accounts
gp mybank statements --month january --year 2024 --format table

# List all discovered plugins
gp plugins
```

See [examples/](https://github.com/stavxyz/graftpunk/blob/main/examples/README.md) for working plugins and templates.

## CLI Reference

```
$ gp --help

 Usage: gp [OPTIONS] COMMAND [ARGS]...

 🔌 graftpunk — Authenticated browser sessions, captured once and replayed over
 plain HTTP: stealth login, encrypted at rest, pluggable storage.

 Log in through a real browser once; graftpunk captures the authenticated
 session — cookies, browser-fingerprinted headers, CSRF/API tokens — encrypts
 it at rest, and replays it over plain HTTP from Python or a generated CLI, so
 a site's own XHR/JSON endpoints become scriptable without a WebDriver in the
 loop.

Commands:
  version     Show graftpunk version and installation info.
  plugins     List discovered plugins (storage, handlers, sites, CLI).
  observe     View and manage observability data (HAR, screenshots, logs).
  session     Manage encrypted browser sessions.
  keepalive   Manage the session keepalive daemon.
  http        Make ad-hoc HTTP requests with cached session cookies.
  config      Show configuration; manage the workstation env file.
  plugin      Scaffold, extend, inspect, upgrade, and check a graftpunk plugin project.
```

(Options and the Quick-start block are elided; the full text is `gp --help`.)

### Session Management

```bash
gp session list              # List all cached sessions
gp session show <name>       # Session metadata (domain, cookies, expiry)
gp session clear <name>      # Remove a session (or --all)
gp session export <name>     # Export cookies to HTTPie session format
gp session use <name>        # Set active session for subsequent commands
gp session unset             # Clear active session
```

Sessions are keyed by plugin **and** account: logging into one site as two
accounts caches `myshop@alice` and `myshop@bob` side by side, and `gp session
list` shows which account each one belongs to. Commands pick one with
`--session myshop@alice` (or `GRAFTPUNK_SESSION` / `gp session use`), and
refuse — listing the candidates — when several are cached and none is picked.
The label is derived from the login identifier; `gp <site> login --as work`
names it yourself.

### Ad-hoc HTTP Requests

Make authenticated requests using cached sessions without writing a plugin:

```bash
gp http get -s mybank https://secure.mybank.example.com/api/accounts
gp http post -s mybank https://secure.mybank.example.com/api/transfer --data '{"amount": 100}'
```

Use `--role` to set browser header roles (built-in or plugin-defined):

```bash
gp http get -s mybank --role xhr https://secure.mybank.example.com/api/status
gp http get -s mybank --role api https://secure.mybank.example.com/v2/data  # custom plugin role
```

Supports all HTTP methods: `get`, `post`, `put`, `patch`, `delete`, `head`, `options`.

### Observability

Capture browser activity for debugging:

```bash
# Open authenticated browser and capture network traffic
gp observe -s mybank go https://secure.mybank.example.com/dashboard

# Interactive mode — browse manually, Ctrl+C to save
gp observe -s mybank interactive https://secure.mybank.example.com/dashboard

# Or use the --interactive flag on observe go
gp observe -s mybank go --interactive https://secure.mybank.example.com/dashboard

# View captured data
gp observe list
gp observe show mybank
gp observe clean mybank
```

Interactive mode opens an authenticated browser and records all network traffic (including response bodies) while you click around. Press Ctrl+C to stop — HAR files, screenshots, page source, and console logs are saved automatically.

Pass `--observe full` to any command to capture screenshots, HAR files, and console logs.

### From recording to plugin

Record the site, read the recording, scaffold a project from it, then fill in
the stubs and test them against fixtures. A first capture has no cached session
to name, so it runs `--no-session` and is filed under the name graftpunk infers
from the host, which `gp observe list` prints (`<name>` below). Each step, with
the options and the rules, is in
[Writing a graftpunk plugin](docs/PLUGIN_DEVELOPMENT.md):
[Capture](docs/PLUGIN_DEVELOPMENT.md#capture),
[Understand](docs/PLUGIN_DEVELOPMENT.md#understand), and
[Scaffold](docs/PLUGIN_DEVELOPMENT.md#scaffold).

```bash
gp observe --no-session interactive https://secure.mybank.example.com/dashboard
gp observe digest <name>
gp plugin new mybank --from-run <name>
```

`--command "NAME=METHOD template"`, repeatable, scaffolds only the endpoints you
name, under your names ([Choose the commands
yourself](docs/PLUGIN_DEVELOPMENT.md#choose-the-commands-yourself)).

The generated tests read fixtures. Write the recorded bodies out as captures,
which land in the project's git-ignored `tests/captures/`, then copy each one
into `tests/fixtures/` with its sidecar and replace every value with an
invented one
([Deriving a fixture from a capture](docs/PLUGIN_DEVELOPMENT.md#deriving-a-fixture-from-a-capture)):

```bash
gp observe fixtures <name> --match "GET /api/accounts"
```

Install the project with its `dev` extra, which brings pytest and ruff, then
run the project's gate before every commit
([The gate](docs/PLUGIN_DEVELOPMENT.md#the-gate)):

```bash
pip install -e ".[dev]"
pytest
ruff check .
ruff format --check .
gp plugin check
```

To keep the project current, `gp plugin upgrade` adds the wiring a newer
graftpunk expects, and `gp plugin add-command` adds one command from a later
recording ([Add a command to an existing
plugin](docs/PLUGIN_DEVELOPMENT.md#add-a-command-to-an-existing-plugin)). When
the project's plain `graftpunk>=` bound is below the `major.minor.0` of the
graftpunk you run them with, each one that writes something raises the bound to
that release and tells you to reinstall the project; [The
gate](docs/PLUGIN_DEVELOPMENT.md#the-gate) covers every other form of the
requirement.

```bash
gp plugin upgrade
gp plugin add-command mybank --from-run <name> --command "statements=GET /api/statements"
```

## Configuration

| Variable | Default | Description |
|:---------|:--------|:------------|
| `GRAFTPUNK_STORAGE_BACKEND` | `local` | Storage: `local`, `supabase`, or `s3` |
| `GRAFTPUNK_CONFIG_DIR` | `~/.config/graftpunk` | Config and encryption key location |
| `GRAFTPUNK_SESSION_TTL_HOURS` | `720` | Session lifetime (30 days) |
| `GRAFTPUNK_LOG_LEVEL` | `WARNING` | Logging verbosity |
| `GRAFTPUNK_LOG_FORMAT` | `console` | Log format: `console` or `json` |
| `GRAFTPUNK_BROWSER_EXECUTABLE_PATH` | _(system Chrome)_ | Path to a Chrome/Chromium binary for the `nodriver` backend (e.g. Chrome-for-Testing on machines/CI without a system Chrome install) |
| `GRAFTPUNK_KEEP_ORPHANED_CHROME` | _(unset)_ | Set to `1` to keep the Chrome processes earlier runs left behind, instead of ending them before a `nodriver` browser starts |

CLI flags: `-v` (info), `-vv` (debug), `--log-format json`, `--observe full`, `--network-debug` (wire-level HTTP tracing).

### Workstation configuration (`gp config`)

Persist per-machine environment for gp in `~/.config/graftpunk/env` —
credentials as lazy 1Password (or any) command values, settings as statics:

```bash
gp config set GRAFTPUNK_BROWSER_EXECUTABLE_PATH "/path/to/chrome"
gp config set MYSHOP_USERNAME '$(op read "op://vault/item/username")'
gp config set MYSHOP_PASSWORD '$(op read "op://vault/item/password")'
gp config list
```

Static values load at startup; `$(…)` values run only when a command
actually needs them (login, first access of an allowlisted setting, or a
YAML plugin's `${VAR}` header expansion) — `gp --help` never triggers your
secret manager. Real environment variables always win over the file — a
variable set to the empty string counts as unset, so an accidental
`export FOO=` doesn't shadow a workstation-file value. Single-quote command
values so your shell doesn't evaluate them at `set` time. See
`docs/rfcs/2026-07-28-workstation-env.md` for the full design.

## Browser Backends

graftpunk supports two browser automation backends (both included by default):

| Backend | Best For |
|---------|----------|
| `selenium` | Simple sites, backward compatibility |
| `nodriver` | Enterprise sites, better anti-detection |

**Why NoDriver?** NoDriver uses Chrome DevTools Protocol (CDP) directly without the WebDriver binary, eliminating a common detection vector used by anti-bot systems.

**Bot-detection cookie filtering:** When injecting session cookies into a nodriver browser (for observe mode, token extraction, etc.), graftpunk automatically skips known WAF tracking cookies (Akamai `bm_*`, `ak_bmsc`, `_abck`). These cookies carry stale bot-classification state that causes WAFs to reject the browser with `ERR_HTTP2_PROTOCOL_ERROR`. Disable with `skip_bot_cookies=False` if needed.

```python
from graftpunk import BrowserSession

# Use BrowserSession with explicit backend
session = BrowserSession(backend="nodriver", headless=False)
```

**Custom Chrome binary:** the `nodriver` backend auto-detects a system Chrome. Set `GRAFTPUNK_BROWSER_EXECUTABLE_PATH` to point it at a specific Chrome/Chromium binary (e.g. Chrome-for-Testing) on machines or CI without a system Chrome install.

## Security

### Your Data, Your Rules

graftpunk is for automating access to **your own accounts**. You're not scraping other people's data—you're building tools to access information that already belongs to you.

Some services may consider automation a ToS violation. Use your judgment.

### Encryption

- **Algorithm:** Fernet (AES-128-CBC + HMAC-SHA256)
- **Key storage:** `~/.config/graftpunk/.session_key` with `0600` permissions
- **Integrity:** SHA-256 checksum validated before deserializing

### Best Practices

- Keep your encryption key secure
- Don't share session files
- Run graftpunk on trusted machines
- Use unique, strong passwords for automated accounts

**Pickle warning:** graftpunk uses Python's `pickle` for serialization. Only load sessions you created.

## Development

```bash
git clone https://github.com/stavxyz/graftpunk.git
cd graftpunk
just setup    # Install deps with uv
just check    # Run lint, typecheck, tests
just build    # Build for PyPI
```

Requires [uv](https://docs.astral.sh/uv/) for development. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.

### Releasing

Releases publish to PyPI through GitHub Actions using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) — no API token is stored anywhere.

```bash
just bump X.Y.Z   # opens a version-bump PR (pyproject, uv.lock, CHANGELOG)
# merge the PR, then on an up-to-date main:
just release      # validates, tags vX.Y.Z, and pushes the tag
```

Pushing the tag triggers [`.github/workflows/release.yml`](.github/workflows/release.yml), which runs the tests, builds the sdist/wheel, publishes to PyPI via OIDC, and creates the GitHub release. Because build + publish run in CI on a pinned Python, releasing no longer depends on your local interpreter or any local credentials.

To (re)publish a tag that was cut before this workflow existed, or to retry a failed publish, run the workflow manually (**Actions → Release → Run workflow**) with the tag (e.g. `v1.9.0`).

**One-time setup** (repo owner, on [pypi.org](https://pypi.org/manage/project/graftpunk/settings/publishing/) → graftpunk → Publishing): add a GitHub Actions trusted publisher with owner `stavxyz`, repository `graftpunk`, workflow `release.yml`, and environment `pypi`.

## License

MIT License—see [LICENSE](LICENSE).

## Acknowledgments

- [requestium](https://github.com/tryolabs/requestium) – Selenium + Requests integration
- [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver) – Anti-detection ChromeDriver
- [nodriver](https://github.com/ultrafunkamsterdam/nodriver) – CDP-direct browser automation
- [cryptography](https://cryptography.io/) – Encryption primitives
- [rich](https://github.com/Textualize/rich) – Beautiful terminal output
- [typer](https://typer.tiangolo.com/) – CLI framework

---

<div align="center">
<sub>Built for automating your own data access.</sub>
</div>
