How Agent Reach Handles Restricted File Permissions for Credentials

Agent Reach enforces Unix 0o600 (owner-only read/write) permissions on credential files at creation time using atomic os.open calls, then validates these restrictions during the doctor diagnostic command to prevent credential leakage on multi-user systems.

Agent Reach stores sensitive authentication tokens, cookies, and API keys in a centralized YAML configuration file at ~/.agent-reach/config.yaml. To mitigate unauthorized access on shared machines, the library implements a defense-in-depth strategy that combines strict creation-time permissions with runtime validation. This article examines exactly how Agent Reach handles restricted file permissions for credentials through specific system calls and security audits.

Atomic File Creation with Restricted Permissions

When the Config class persists sensitive data, it bypasses standard file creation methods to eliminate race conditions where credentials might briefly exist with insecure default permissions.

Using os.open for Permission-First Creation

In agent_reach/config.py (lines 50-60), the Config.save() method creates the file using os.open with explicit mode flags:

fd = os.open(
    str(self.config_path),
    os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
    stat.S_IRUSR | stat.S_IWUSR,   # ← 0o600: owner read/write only

)

The bitmask stat.S_IRUSR | stat.S_IWUSR translates to 0o600, granting read and write access exclusively to the file owner. By passing these flags directly to os.open, Agent Reach ensures the file descriptor is created with restrictive permissions before any data is written, preventing the transient exposure window associated with create-then-chmod patterns.

The file descriptor is then wrapped with os.fdopen for standard Python I/O operations:

with os.fdopen(fd, 'w') as f:
    yaml.dump(self._data, f)

If os.open fails (notably on Windows where these Unix-specific mode flags are unsupported), the library falls back to a standard open() call, relying on the doctor command to detect and report any resulting permission issues.

Runtime Permission Validation

Creation-time protections are reinforced by continuous security auditing through the built-in diagnostics tool.

The doctor Command Security Audit

The agent_reach doctor command, implemented in agent_reach/doctor.py (lines 90-104), performs a runtime inspection of the configuration file's access controls. On Unix platforms, it examines the mode bits using pathlib.Path.stat():

mode = config_path.stat().st_mode
if mode & (stat.S_IRGRP | stat.S_IROTH):
    # group-read or others-read → insecure

    lines.append("[bold red][!]  安全提示：config.yaml 权限过宽（其他用户可读）[/bold red]")
    lines.append("   修复：chmod 600 ~/.agent-reach/config.yaml")

If the file is readable by group members or others (stat.S_IRGRP or stat.S_IROTH), the diagnostic outputs a bold red warning and provides the exact remediation command: chmod 600 ~/.agent-reach/config.yaml. This feedback loop ensures users immediately recognize when manual file operations or backup restores have inadvertently weakened the security posture.

Practical Implementation Examples

Storing Credentials with Automatic Permission Enforcement

When using the Config API to store authentication tokens, the restrictive permissions are applied automatically:

from agent_reach.config import Config

cfg = Config()                     # loads ~/.agent-reach/config.yaml

cfg.set("twitter_auth_token", "YOUR_TOKEN")
cfg.set("twitter_ct0", "YOUR_CT0")

# File is written with owner-only read/write permissions (0o600)

Auditing File Permissions

To verify your credential file remains secure, run the diagnostic command:

python -m agent_reach.cli doctor

If permissions are correct, no warnings appear. If the file is world-readable or group-readable, you will see the security alert with remediation instructions.

Manual Remediation

If the doctor command reports overly broad permissions, apply the fix immediately:

chmod 600 ~/.agent-reach/config.yaml

Summary

• Creation-time enforcement: Agent Reach uses os.open with stat.S_IRUSR | stat.S_IWUSR (0o600) in agent_reach/config.py to create the credential file with owner-only permissions atomically
• Race condition prevention: Setting permissions at file descriptor creation eliminates the temporary window where credentials might be readable by others
• Runtime validation: The doctor command in agent_reach/doctor.py validates mode bits and warns users if config.yaml becomes readable by group or others
• Cross-platform handling: Unix systems receive native 0o600 enforcement, while Windows falls back to default creation with diagnostic validation
• User guidance: The CLI provides exact remediation commands (chmod 600) when permission drift is detected

Frequently Asked Questions

What permission mode does Agent Reach use for credential storage?

Agent Reach enforces 0o600 permissions (read and write for owner only) on the ~/.agent-reach/config.yaml file. This corresponds to stat.S_IRUSR | stat.S_IWUSR in Python's stat module, ensuring that no other users on the system—including those in the same group—can access the stored tokens and API keys.

How does Agent Reach prevent race conditions when creating credential files?

Instead of creating a file with default permissions and subsequently modifying them with chmod, Agent Reach uses os.open with the mode flag set to 0o600 at the moment of creation. This atomic approach ensures the file never exists in a world-readable state, eliminating the brief vulnerability window that exists in create-then-chmod patterns.

What happens if I manually change the file permissions after creation?

If you modify the permissions to make the file readable by others (for example, using chmod 644 or copying the file while preserving permissions), the agent-reach doctor command will detect the insecure configuration during its next run. It displays a red warning message and provides the exact command (chmod 600 ~/.agent-reach/config.yaml) required to restore secure permissions.

Does this permission restriction work on Windows?

On Windows, the os.open mode flags used for Unix permission enforcement are not supported, so Agent Reach falls back to standard file creation with default permissions. However, the doctor command still executes the permission check logic and will alert you if the file appears to have overly broad access controls, though Windows uses ACL-based permissions rather than Unix mode bits.

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