# How Terax AI Handles Data Privacy and Security: A Defense-in-Depth Architecture

> Discover how Terax AI secures your data with a defense-in-depth architecture. Learn about its five security boundaries, deny-lists, user approvals, and secure credential storage for robust data privacy.

- Repository: [Crynta/terax-ai](https://github.com/crynta/terax-ai)
- Tags: architecture
- Published: 2026-07-06

---

**Terax AI isolates every privileged operation behind five explicit security boundaries—IPC, file-system, network, secret-storage, and terminal I/O—enforcing deny-lists for sensitive paths, requiring user approval for mutating AI tools, and storing credentials exclusively in OS-provided secure stores.**

Terax AI implements a rigorous defense-in-depth security model that protects user data through audited isolation gates. As implemented in the crynta/terax-ai repository, every sensitive operation from file system access to network requests flows through hardened boundaries designed to prevent unauthorized access and data leakage.

## The Five Security Boundaries

Terax AI architecture defines explicit boundaries that isolate privileged operations. Each boundary serves a specific protective function and is implemented in dedicated source modules.

### IPC Command Isolation

All commands sent from the front-end to the native Rust side are strictly controlled. Only commands explicitly listed in [`src-tauri/src/lib.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/lib.rs) and gated by the capability manifest in [`src-tauri/capabilities/default.json`](https://github.com/crynta/terax-ai/blob/main/src-tauri/capabilities/default.json) are allowed to execute. This prevents arbitrary native code execution from the renderer process.

### File System Isolation

All file system reads and writes performed by AI tools or PTY processes flow through [`src/modules/ai/lib/security.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/security.ts). This module enforces a deny-list of secret paths and validates operations against the workspace authorization registry defined in [`src-tauri/src/modules/workspace.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs).

### Network Request Protection

Outgoing HTTP requests to AI providers or local LLM endpoints are funneled through [`src-tauri/src/modules/net.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/net.rs). The system resolves hostnames once, classifies resolved IPs as public, private, loopback, or blocked, and prevents DNS-rebinding attacks by pinning requests to the initially resolved IP addresses.

### Secure Secret Storage

API keys and tokens are stored exclusively in the OS-provided secret store via [`src-tauri/src/modules/secrets.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs). On macOS this uses the Keychain, on Windows the Credential Manager, and on Linux a JSON file with mode 0600. Credentials never appear in logs, disk snapshots, or browser `localStorage`.

### Terminal Escape Sequence Validation

OSC sequences emitted by the PTY are strictly validated in [`src-tauri/src/modules/pty/agent_detect.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/pty/agent_detect.rs). Only known safe commands—OSC 7, OSC 133 variants A/B/C/D, and OSC 777—are parsed, preventing malicious terminal output from mutating application state.

## File System Protection Mechanisms

### Secret Path Deny-List

The [`src/modules/ai/lib/security.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/security.ts) module rejects any read or write operation matching sensitive patterns. The deny-list includes:

- `.env*`, `*.pem`, `*.key`, `id_rsa*`, `known_hosts`
- `~/.ssh`, `~/.gnupg`, `~/.aws`
- `/etc`, `/proc`, `/sys`

Both canonical and resolved paths are checked, ensuring symlinks pointing into protected directories are caught and blocked.

### Workspace Authorization Registry

All filesystem-affecting commands must be authorized by the `WorkspaceRegistry` in [`src-tauri/src/modules/workspace.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs). The registry maintains an allow-list seeded with the launch directory and user home directory. New roots require explicit authorization via `workspace_authorize` or `authorize_user_spawn_cwd`.

## AI Tool Approval Flow

Terax AI distinguishes between read-only and mutating AI tools. Read-only tools such as `read_file`, `list_directory`, `grep`, and `glob` execute automatically after deny-list verification. Mutating tools including `write_file`, `edit`, `run_command`, and `shell_bg_spawn` set `needsApproval: true` in [`src/modules/ai/tools/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/tools.ts).

When a mutating tool is invoked, the Vercel AI SDK pauses execution and emits a `tool-approval-request` UI card. The user must explicitly confirm before the tool proceeds, and confirmation is only sent when `lastAssistantMessageIsCompleteWithApprovalResponses` returns true.

```typescript
import { tool } from '@vercel/ai';

export const writeFile = tool({
  name: 'write_file',
  description: 'Write content to a file (requires approval)',
  input_schema: {
    path: { type: 'string' },
    content: { type: 'string' },
  },
  needsApproval: true,
  handler: async ({ path, content }) => {
    // Executes only after user clicks "Approve"
    await Deno.writeTextFile(path, content);
    return { success: true };
  },
});

```

## Network Security and SSRF Defense

The network boundary in [`src-tauri/src/modules/net.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/net.rs) implements Server-Side Request Forgery (SSRF) protection through a four-step process:

1. **Resolve and classify**: Hostnames are resolved once via `resolve_and_classify`
2. **IP classification**: Each resolved IP is categorized as public, private, loopback, or blocked
3. **Metadata endpoint blocking**: Known cloud-metadata endpoints such as `169.254.169.254` and `metadata.google.internal` are rejected
4. **IP pinning**: Requests are pinned to the initially resolved IPs, preventing DNS-rebinding attacks that redirect traffic after validation

Local LLM endpoints are permitted only after explicit user configuration but undergo identical classification and logging.

```rust
let url = "https://api.openai.com/v1/chat/completions";
let client = reqwest::Client::builder()
    .resolve_to_ip("api.openai.com", "34.193.69.252")
    .build()?;
let resp = client.post(url).json(&payload).send().await?;

```

## Credential Storage Implementation

The [`src-tauri/src/modules/secrets.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs) module handles credential storage using platform-specific secure stores:

- **macOS**: Keychain via the `keyring` crate
- **Windows**: Credential Manager via `keyring`
- **Linux**: Atomic JSON file creation (`.tmp` → rename) with permissions 0600 in the app's local data directory

All entries use the constant service name `"terax-ai"`. The implementation ensures keys never persist in unencrypted logs or browser storage.

```rust
use keyring::Entry;

fn get_api_key(provider: &str) -> anyhow::Result<String> {
    let entry = Entry::new("terax-ai", provider)?;
    entry.get_password()
}

```

## Summary

- **Defense-in-depth architecture**: Five distinct boundaries isolate IPC, file system, network, secrets, and terminal operations
- **Explicit workspace authorization**: The `WorkspaceRegistry` in [`src-tauri/src/modules/workspace.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs) maintains strict allow-lists for file system access
- **Secret path protection**: [`src/modules/ai/lib/security.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/security.ts) enforces deny-lists for SSH keys, environment files, and system directories
- **User-controlled mutations**: Mutating AI tools require explicit approval via `needsApproval: true` before execution
- **SSRF prevention**: [`src-tauri/src/modules/net.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/net.rs) pins resolved IPs and blocks cloud-metadata endpoints
- **OS-native secret storage**: Credentials reside exclusively in platform keychains, never in localStorage or plain text files

## Frequently Asked Questions

### How does Terax AI prevent AI tools from accessing my SSH keys?

Terax AI implements a deny-list in [`src/modules/ai/lib/security.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/security.ts) that blocks access to paths matching patterns like `~/.ssh`, `id_rsa*`, and `known_hosts`. Additionally, the `WorkspaceRegistry` in [`src-tauri/src/modules/workspace.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/workspace.rs) ensures AI tools can only access explicitly authorized directories, preventing traversal into sensitive system folders even through symlink attacks.

### Where does Terax AI store my API keys and credentials?

API keys are stored exclusively in OS-provided secure stores via [`src-tauri/src/modules/secrets.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/secrets.rs). On macOS this is the Keychain, on Windows the Credential Manager, and on Linux a permission-restricted JSON file (mode 0600). The service name `"terax-ai"` isolates these entries from other applications, and credentials never appear in application logs or browser storage.

### Can Terax AI automatically execute shell commands without my permission?

No. Mutating tools including `run_command` and `shell_bg_spawn` set `needsApproval: true` in [`src/modules/ai/tools/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/tools.ts). The Vercel AI SDK pauses execution and displays a `tool-approval-request` card that requires explicit user confirmation. The tool handler only runs after the user clicks approve and the system validates `lastAssistantMessageIsCompleteWithApprovalResponses`.

### How does Terax AI protect against malicious terminal output?

The PTY module in [`src-tauri/src/modules/pty/agent_detect.rs`](https://github.com/crynta/terax-ai/blob/main/src-tauri/src/modules/pty/agent_detect.rs) implements strict OSC (Operating System Command) validation. Only a whitelist of sequences—specifically OSC 7, OSC 133 A/B/C/D, and OSC 777—are parsed and acted upon. All other escape sequences are ignored, preventing malicious terminal applications from injecting commands or manipulating application state through escape sequences.