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

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 and gated by the capability manifest in 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. 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.

Network Request Protection

Outgoing HTTP requests to AI providers or local LLM endpoints are funneled through 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. 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. 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 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. 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.

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.

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

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

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 maintains strict allow-lists for file system access
• Secret path protection: 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 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 that blocks access to paths matching patterns like ~/.ssh, id_rsa*, and known_hosts. Additionally, the WorkspaceRegistry in 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. 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. 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 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.

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