# Security Model for Storing Local Cookies and Tokens in Agent Reach

> Agent Reach secures local cookies and tokens with a defense-in-depth model. Owner-only files and private directories keep your credentials safe from unauthorized access.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: security
- Published: 2026-07-15

---

**Agent Reach implements a defense-in-depth security model that stores all cookies and tokens in owner-only files with `0o600` permissions inside private `0o700` directories, ensuring no other user or process can access your credentials.**

Agent Reach, an open-source automation framework maintained in the **Panniantong/Agent-Reach** repository, extracts sensitive session data from browsers and CLI tools. Understanding its **security model for storing local cookies and tokens** is critical for users who need to protect authentication credentials from unauthorized access while maintaining seamless automation workflows.

## Owner-Only File Creation

The foundation of Agent Reach’s credential protection lies in the `_open_owner_only()` helper function defined in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) (lines 49‑68). This utility creates files with restrictive permissions from the moment of creation:

- Opens files using `os.O_WRONLY | os.O_CREAT | os.O_TRUNC` flags
- Sets the initial mode to `0o600` (read/write for owner only)
- Immediately calls `os.chmod()` after opening to guarantee the file never becomes world-readable, even transiently

This atomic approach ensures that sensitive tokens written to disk are inaccessible to any other user account on the system.

## Private Directory Isolation

Before writing any credential file, Agent Reach calls `make_private_dir()` from `agent_reach/utils/paths` to create the target directory. This function establishes directories with mode `0o700`, which prevents other users from listing directory contents or accessing files within, even if they somehow gained access to the parent path.

This directory-level protection applies consistently across all storage locations, including `~/.agent-reach/`, `~/.config/xfetch/`, and `~/.config/bird/`.

## In-Memory Browser Cookie Handling

Browser-extracted credentials follow a strict memory-only policy by default. The `extract_all()` function (lines 42‑46 in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py)) returns cookie values only in memory and never persists them to disk unless the user explicitly executes:

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

```

When that command is invoked, the extracted data flows through the same owner-only helpers described above, ensuring temporary memory storage and permanent disk storage maintain identical security postures.

## Legacy Sync Helpers for Third-Party Tools

Agent Reach includes specialized synchronization functions that secure credentials for external CLI tools using the same permission model.

### Xfetch Session Synchronization

The `_sync_xfetch_session` function writes JSON session data to `~/.config/xfetch/session.json`. Like all Agent Reach credential files, this uses the `_open_owner_only()` routine to enforce `0o600` permissions, preventing session hijacking via world-readable config files.

### Bird CLI Environment Variables

The `_sync_bird_env` function creates `~/.config/bird/credentials.env` with the same `0o600` protection. Crucially, this helper sanitizes all token values using `shlex.quote()` before writing, ensuring that tokens containing quotes, `$` variables, or backticks cannot execute arbitrary shell commands when the file is sourced.

```python
def _sync_bird_env(auth_token: str, ct0: str) -> None:
    from agent_reach.utils.paths import make_private_dir
    bird_dir = os.path.join(os.path.expanduser("~"), ".config", "bird")
    make_private_dir(bird_dir)                 # creates 0o700 directory

    env_path = os.path.join(bird_dir, "credentials.env")
    with _open_owner_only(env_path) as f:       # creates 0o600 file

        f.write(f"AUTH_TOKEN={shlex.quote(auth_token)}\n")
        f.write(f"CT0={shlex.quote(ct0)}\n")

```

## Centralized Configuration Security

The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages the user-specific configuration file under `~/.agent-reach/`. When the CLI writes this file, it employs the same `make_private_dir()` and owner-only file logic, guaranteeing that the central config file maintains `0o600` permissions and its containing directory remains `0o700`.

## Fail-Safe Error Handling

All write operations throughout the codebase are wrapped in `try/except` blocks. If any permission-setting step fails—such as when encountering a read-only filesystem or missing parent directory—the exception is caught and handled silently without crashing the process. This prevents accidental credential exposure through stack traces or error logs that might otherwise leak sensitive file paths or token values.

## Practical Implementation Example

To extract cookies from Chrome and save them securely using Agent Reach’s security model:

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

cfg = Config()                     # loads ~/.agent-reach config (owner‑only)

results = configure_from_browser("chrome", cfg)

# results is a list like:

# [('Twitter/X', True, 'auth_token + ct0'), ('XiaoHongShu', True, '12 cookies'), …]

```

The `configure_from_browser` function automatically handles the permission-hardened storage, ensuring your Twitter/X `auth_token` and `ct0` values, or XiaoHongShu session cookies, are written exclusively to your user account.

## Summary

- **Owner-only files**: All credential files are created with `0o600` permissions using the `_open_owner_only()` helper in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py).
- **Private directories**: `make_private_dir()` from `agent_reach/utils/paths` ensures containing directories are `0o700`.
- **Memory-first design**: Browser cookies remain in memory unless explicitly saved via the configure command.
- **Input sanitization**: Token values are quoted with `shlex.quote()` before writing to shell-sourced files like `~/.config/bird/credentials.env`.
- **Fail-safe operations**: All disk writes use exception handling to prevent credential leakage through error messages.

## Frequently Asked Questions

### What file permissions does Agent Reach use for stored tokens?

Agent Reach uses `0o600` (read/write for owner only) for all credential files and `0o700` (owner-only access) for containing directories. This is enforced by the `_open_owner_only()` function in [`agent_reach/cookie_extract.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cookie_extract.py) and the `make_private_dir()` utility, ensuring no other system user can read your extracted cookies or tokens.

### Does Agent Reach store browser cookies automatically?

No. The `extract_all()` function (lines 42‑46) returns cookie values only in memory. Persistent storage occurs only when you explicitly run `agent-reach configure --from-browser`, at which point the data is written through the secure, owner-only file helpers to prevent unauthorized access.

### How does Agent Reach prevent token injection in shell files?

When writing to shell-sourced files like `~/.config/bird/credentials.env`, the `_sync_bird_env` function sanitizes all values using `shlex.quote()`. This escapes special characters including quotes, dollar signs, and backticks, preventing malicious tokens from executing arbitrary commands when the file is sourced.

### Where is the configuration stored on disk?

Agent Reach stores its central configuration in `~/.agent-reach/` under the user’s home directory. The `Config` class in [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) manages this location, applying the same `0o700` directory and `0o600` file permissions used throughout the codebase. Legacy integrations may also use `~/.config/xfetch/` or `~/.config/bird/` with identical protections.