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

Agent-Reach authenticates to Twitter/X and XiaoHongShu by extracting session cookies from local browsers via 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 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 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, 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, 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) 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:

agent-reach configure --from-browser chrome

Programmatic Cookie Configuration

For custom workflows, import the extraction function directly:

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:

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:

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 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 injects Bearer tokens and CSRF headers, while 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, 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, 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 stores credentials in the user's home directory with restricted access, treating session tokens as sensitive configuration data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}