# How Agent Reach Handles Restricted File Permissions for Credentials

> Agent Reach secures credentials by enforcing owner-only file permissions and validating them with the doctor command, preventing leaks on multi-user systems.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) (lines 50-60), the `Config.save()` method creates the file using `os.open` with explicit mode flags:

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

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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()`:

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

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

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

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) validates mode bits and warns users if [`config.yaml`](https://github.com/Panniantong/Agent-Reach/blob/main/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.