Security Model for Storing Local Cookies and Tokens in Agent Reach

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 (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) returns cookie values only in memory and never persists them to disk unless the user explicitly executes:

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.

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 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:

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.
• 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 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 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.

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