# How Agent-Reach Implements Cookie-Based Authentication for Twitter and XiaoHongShu

> Learn how Agent-Reach uses cookie-based authentication for Twitter and XiaoHongShu. Discover the mechanism for extracting and injecting cookies to authenticate your sessions.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-14

---

**Agent-Reach authenticates to Twitter/X and XiaoHongShu by extracting session cookies from local browsers via [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), mapping them to configuration keys like `twitter_auth_token` and `xhs_cookie`, and injecting them into HTTP headers through platform-specific channel implementations.**

Agent-Reach is an open-source automation framework that eliminates the need for OAuth tokens by reusing existing browser sessions. The **cookie-based authentication mechanism** enables seamless API-like access to platforms that require authenticated sessions without manual cookie copying. This approach centers on the [`cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/cookie_extract.py) module, which interfaces with browser storage to harvest credentials and distribute them to channel implementations.

## How the Cookie Extraction Engine Works

The extraction logic resides in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) and operates through a two-tier library strategy with platform-specific specifications.

### Platform Specifications and Required Cookies

The module defines a `PLATFORM_SPECS` list that declares domain patterns and mandatory cookie names for each supported platform. For **Twitter/X**, the specification requires two distinct cookies: `auth_token` and `ct0`. For **XiaoHongShu**, the mechanism captures the entire cookie header string rather than individual keys. This declarative approach allows the extractor to target specific domains and filter relevant session data from the browser's cookie store.

### Browser Extraction Libraries: rookiepy and browser-cookie3

The `configure_from_browser()` function attempts extraction using **rookiepy**, a Rust-based high-performance library, as the primary engine. If rookiepy fails or returns incomplete data, the system falls back to **browser-cookie3**, a pure-Python alternative. This dual-library approach ensures compatibility across different browser versions and operating systems while maintaining extraction speed.

## Configuration Mapping and Storage

Once extracted, raw cookies undergo normalization and secure storage through the centralized configuration system.

### Mapping Cookies to Config Keys

The `configure_from_browser(browser, config)` function iterates over `PLATFORM_SPECS`, constructs a dictionary of found cookies, and persists them using `config.set()`. Specifically:
- Twitter/X tokens are stored as `twitter_auth_token` and `twitter_ct0`
- XiaoHongShu data is stored as a single string under `xhs_cookie`

These keys reside in the central configuration object managed by [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py), which supports both YAML file and environment variable backends.

### Legacy Compatibility Sync

For interoperability with external tools, the extractor includes two synchronization helpers:
- **`_sync_xfetch_session()`**: Writes Twitter credentials to `~/.config/xfetch/session.json` for the legacy xfetch CLI
- **`_sync_bird_env()`**: Exports credentials to `~/.config/bird/credentials.env` for the bird CLI environment

Both helpers safely quote values and enforce `0600` file permissions to prevent unauthorized access to sensitive session data.

## Channel Implementation: From Config to HTTP Headers

Channel modules consume the stored configuration and translate cookies into valid HTTP headers for authenticated requests.

### Twitter/X Channel Header Injection

In [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py), the channel implementation retrieves `twitter_auth_token` and `twitter_ct0` from the config instance. It injects these into request headers as:
- `Authorization: Bearer <twitter_auth_token>`
- `x-csrf-token: <twitter_ct0>`

This header combination satisfies Twitter's authentication requirements for API-like interactions without OAuth.

### XiaoHongShu Channel Cookie Handling

The XiaoHongShu channel ([`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py)) retrieves the raw `xhs_cookie` string from configuration and appends it directly to the `Cookie` header of each outgoing request. This preserves the full session context required by the platform's web endpoints.

## Practical Implementation Examples

### Extracting Cookies via CLI

Execute the built-in configuration command to harvest cookies from Chrome and populate the system config:

```bash
agent-reach configure --from-browser chrome

```

### Programmatic Cookie Configuration

For custom workflows, import the extraction function directly:

```python
from agent_reach.config import Config
from agent_reach.cookie_extract import configure_from_browser

cfg = Config()
results = configure_from_browser('firefox', cfg)

for platform, success, message in results:
    status = "OK" if success else "FAIL"
    print(f'{platform}: {status} – {message}')

```

### Making Authenticated Requests

Once configured, the `AgentReach` core automatically applies stored credentials during requests:

**Twitter/X Example:**

```python
from agent_reach.core import AgentReach
from agent_reach.config import Config

cfg = Config()
ar = AgentReach(cfg)

response = ar.read('https://x.com/user/status/123456')
print(response.text)

```

**XiaoHongShu Example:**

```python
from agent_reach.core import AgentReach
from agent_reach.config import Config

cfg = Config()
ar = AgentReach(cfg)

response = ar.read('https://www.xiaohongshu.com/explore/123456')
print(response.json())

```

## Summary

- **Extraction Layer**: [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) uses rookiepy with a browser-cookie3 fallback to harvest cookies from local browser storage based on `PLATFORM_SPECS` definitions.
- **Configuration Keys**: Twitter/X requires `twitter_auth_token` and `twitter_ct0`; XiaoHongShu uses a single `xhs_cookie` string.
- **Security Measures**: Legacy sync functions enforce `0600` file permissions and safe quoting when writing to external credential stores.
- **Channel Integration**: [`agent_reach/channels/twitter.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/twitter.py) injects Bearer tokens and CSRF headers, while [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) passes the raw cookie string.
- **Zero OAuth**: The mechanism relies entirely on existing browser sessions, eliminating separate API key management.

## Frequently Asked Questions

### How does Agent-Reach extract cookies without manual copy-pasting?

The framework automates extraction through [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), which queries the browser's SQLite cookie databases directly using rookiepy or browser-cookie3. Users simply specify the browser name (e.g., `chrome`, `firefox`), and the library retrieves all cookies matching the domain patterns defined in `PLATFORM_SPECS`.

### What happens if the primary extraction library fails?

If rookiepy (the Rust-based primary library) fails to read the browser database or returns incomplete data, the `configure_from_browser()` function automatically falls back to browser-cookie3. This ensures robust cross-platform compatibility across different operating systems and browser versions.

### Which specific cookies are required for Twitter/X authentication?

According to the `PLATFORM_SPECS` definition in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py), Twitter/X authentication requires two cookies: `auth_token` (used as the Bearer token in the Authorization header) and `ct0` (used as the x-csrf-token header). Both must be present and valid for authenticated requests to succeed.

### How does the framework handle cookie storage security?

When syncing to legacy tools, the `_sync_xfetch_session()` and `_sync_bird_env()` helpers create files with `0600` permissions (read/write for owner only) and properly quote values to prevent shell injection. The central configuration system in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) stores credentials in the user's home directory with restricted access, treating session tokens as sensitive configuration data.