Security model

Voktty treats the webview, project files, shell processes, network and extensions as separate trust boundaries.

Secret paths

The shared security logic refuses obvious secret paths such as .env*, .ssh, credential stores and keychain directories. Matching normalizes case, separators, trailing dots and spaces, alternate data-stream forms and duplicate separators.

Canonicalization is followed by a second deny-list check. This prevents a symlink or equivalent path from presenting an innocent path while resolving into a protected directory. The deny-list applies to both reads and writes.

Workspace authorization

The Rust WorkspaceRegistry tracks authorized directories for PTY spawns, Git operations and AI tools. The launch directory and home directory are bootstrapped. A user-selected cwd can be explicitly authorized, but a command must not silently escape the selected workspace.

New features that spawn a process or touch files must use this registry rather than adding a parallel allowlist.

AI approvals

Read-only tools can run automatically after security checks. File mutations, command execution, persistent shell sessions and background process spawns require an approval card. An AI-generated request is never permission to skip that card.

Network and SSRF

AI requests and local-model pings run through the Rust proxy. The proxy resolves a hostname once, classifies every resulting IP and blocks cloud metadata endpoints. It pins the connection to the resolved addresses to prevent DNS rebinding between validation and connection.

Local endpoints are allowed when the user configured them, but they still pass through classification and logging rules.

Secrets

Provider keys use the OS keychain through the keyring crate. Linux uses a protected atomic file fallback. Keys are not persisted in settings, localStorage, project memory, logs or extension manifests.

OSC trust

PTY output can update cwd, command state and agent notifications only through recognized OSC sequences. Raw output does not change agent state. This matters for TUIs that repaint the same screen repeatedly.

Extensions

Extensions are local code with access to the registered voktty API. The API is intentionally small, but terminal execution and AI tool registration are consequential. Extension activation is delayed and bounded, but enabled extensions remain trusted code.

Security checklist for changes

  • Validate input in Rust, not only in React.
  • Canonicalize paths before allow or deny decisions.
  • Apply secret-path protection to reads and writes.
  • Route network traffic through the SSRF-aware proxy.
  • Add a denied-input test for every new boundary.
  • Keep tokens and credentials out of logs and command output.