Security Architecture

Overview

StarkFi follows a zero-trust security architecture — private keys never leave their secure environment, all transactions require simulation before execution, and every data layer enforces strict isolation.

This page covers the security model across all four entry points: CLI, MCP Server, Agent Skills, and Telegram Bot.

Key Isolation

TEE (Trusted Execution Environment)

Private keys are generated and stored inside Privy's Trusted Execution Environment. Neither the CLI, the auth server, nor the MCP server can access raw key material.

CLI / MCP → Auth Server → Privy TEE
                              ↓
                    Sign inside TEE
                              ↓
                    Return signature only

The Auth Server acts as a proxy — it forwards signing requests to the TEE and returns only the resulting signature. The server itself never holds or processes private keys.

Confidential Key Storage

Tongo Cash private keys are stored locally with strict permissions:

The key is used only for local ZK proof generation. It is never sent to the auth server, MCP server, or any external endpoint.

Authentication Security

JWT Authorization

All authenticated endpoints require a valid JWT token:

Rate Limiting

Session Lifecycle

Login → OTP → Verify → JWT issued → Session saved locally
                                          ↓
                        Auto-cleared on expiry or manual logout

Sessions persist across terminal restarts. Expired sessions are automatically detected and cleared — users are prompted to re-authenticate.

Transaction Security

Mandatory Simulation

Every transactional operation passes through sendWithPreflight(), which executes a dry-run simulation before submitting to the network:

User request → Build transaction → Simulate (dry-run)
                                        ↓
                              Simulation passes? → Execute on-chain
                              Simulation fails?  → Return error (no gas spent)

This catches reverts, insufficient balances, and invalid parameters before spending gas.

Quote-First Policy

All DeFi operations follow a quote → confirm → execute pattern:

This applies to swaps, staking, lending, DCA, and batch operations. AI agents are instructed via system prompts to never skip the quote step.

MCP Security Model

Tool Sandboxing

The MCP server enforces security through multiple mechanisms:

Tool Hint Classification

Telegram Bot Security

API Key Encryption

User-provided AI API keys are encrypted at rest using AES-256-GCM:

Messages containing API keys are automatically deleted from the Telegram chat after processing.

Per-User MCP Isolation

Each Telegram user gets a dedicated MCP child process with an isolated environment:

User A → McpProcessPool → Child Process A (isolated XDG home)
User B → McpProcessPool → Child Process B (isolated XDG home)

Rate Limiting

The bot enforces per-user rate limiting using a token bucket algorithm:

Error Masking

Sensitive information is filtered from error messages before they reach users or AI agents:

Both CLI (formatError()) and MCP (withErrorHandling()) use the same error sanitization pipeline, ensuring consistent security regardless of the entry point.

Security Checklist

See Also

• Auth Server — Detailed server endpoints, middleware, and setup
• Error Handling — 36 typed error codes and retry logic
• AVNU Paymaster — Gas abstraction security model
• Telegram Bot — Bot setup and BYOK model