# Security Architecture
> **Coming Soon**: Based on current design documents; implementation details will finalize upon official release.
***
This page explains toani Control's security model and design invariants, answering the question: "How are credentials and execution boundaries jointly constrained by hardware and policy?"
> **Platform-level shared security foundation** (TEE concepts, crypto choices, DCAP, immudb, and quick reference for differences from toani Vault):[ toani.ai Platform Security Foundation](/about-toani/platform-security.md). For component-level Execution Plane details, see [Execution Plane Technical Architecture](/toani-control/execution-plane.md).
***
## Three Security Commitments
| Commitment | Technical Guarantee |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Credential plaintext exists only in Execution Plane, within TEE boundary, and transiently** | L1–L3 derivation and decryption completed inside Intel SGX; ciphertext flows through secure channels to connectors; plaintext is `memzero`'d after use |
| **Policy cannot be bypassed by agents or end users** | Execution Plane behavior is determined solely by signed Policy and verified PASETO Action Token |
| **Every execution has a verifiable audit trail** | immudb append-only storage, hash chains/Merkle trees, exportable proof bundles; record fields designed to avoid storing plaintext credentials or parameter values |
***
## Why TEE (with Dual Hardware)
The weakness of traditional "decrypt at cloud, then execute business logic" is: **plaintext necessarily becomes visible to the host and operations staff**. For the general TEE solution and concepts, see [Platform Security Foundation: Section 2](/about-toani/platform-security.md#tee-fundamentals). The diagram below describes toani Control's **product-specific** dual hardware division (SGX key domain vs SEV-SNP/gVisor execution domain):
| Component | TEE / Isolation Technology | Responsibility |
| ------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------- |
| **Key Manager / Token Signer** | Intel SGX (process-level Enclave) | L1–L3 derivation, AES-256-GCM decryption, PASETO v4.local Action Token signing |
| **Connector Sandbox** | AMD SEV-SNP (VM-level) plus gVisor | Network calls, browser automation; credentials injected via **RA-TLS** from SGX |
SGX minimizes the **TCB** for key and token operations; SEV-SNP plus gVisor adds an isolation layer between **execution workloads** and the host machine, aligning the threat model split between "decrypt and sign" and "make external connections and execute."
***
## Four-Layer Key Hierarchy (Overview)
Key material **should only exist in plaintext within the Enclave boundary**; persistence uses only ciphertext and metadata:
**Credential sensitivity levels** (Standard / Privileged / Personal / Biometric-KYC-gated) influence **policy-tied approval** (e.g., high sensitivity requires dual admin approval) and **integration with zkMe identity proofs** (e.g., Class 4 requires valid zkKYC).
***
## Three-Layer Architectural Isolation
| Layer | Who Manages | Absolutely Cannot Do |
| ----------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **L1 Credential Plane** | Enterprise IT/security admins | Application API **never returns** credential plaintext; only fingerprints, IDs, and metadata |
| **L2 Policy Plane** | Enterprise policy admins | Cannot force Execution Plane to skip audit or expand action scope (enforced by Token plus Enclave logic) |
| **L3 Execution Plane** | Platform implementation (customers and users have only observability, not behavioral control) | Plaintext never logged, never exported to Agent process; plaintext zeroed at execution end |
**Design invariant**: L1 and L2 **cannot observe** L3 internal state (such as in-memory plaintext windows); they can only see **execution results, audit summaries, and proofs**.
***
## Connector Sandbox Security Model
All connectors run under unified container security configuration (exact parameters finalize on implementation):
| Constraint | Description |
| ------------------ | --------------------------------------------------------------------------- |
| **Runtime** | gVisor (runsc) system call interception |
| **Network Egress** | Whitelisted target domains declared in Policy |
| **Filesystem** | Root read-only; `/tmp` ephemeral and destroyed with container |
| **Privilege** | Non-root, no Linux capabilities |
| **Seccomp** | Strict whitelist (design target: minimal syscalls) |
| **Memory** | Quota limit; credential buffers `sodium_memzero`'d after use |
| **Lifecycle** | Single execution creates one container; no reuse across requests |
| **Logging** | stdout/stderr filtered before persisting; credential-shaped content avoided |
***
## Threat Model (Summary)
toani Control's design assumptions include: **cloud vendors, OS, and even platform operations staff** cannot be trusted to never inspect plaintext. Typical visibility for each role below (consistent with design documents, provided for risk assessment):
| Threat / Role | Can See | Cannot See |
| --------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Cloud provider | Encrypted memory pages, ciphertext traffic, metadata | L0–L3 plaintext, credential values, decrypted business parameters |
| Platform operations / staff | Tenant metadata, audit hashes, policy config | Tenant L1, credential plaintext, Enclave internal plaintext state |
| Enterprise admin | Own policies, audit views, credential fingerprints | Plaintext "read-back" after Vault write, other tenants' data |
| Enterprise developer | API return values, Execution Receipt | Credential values, TEE internal attestation details, other users' data |
| Controlled Agent process | toani Control API return values | Credentials, TEE key material, lateral data access to other sessions |
| Network eavesdropper | mTLS ciphertext | Plaintext (design goal: TLS 1.3 plus fixed cipher suites plus certificate pinning) |
***
## Known TEE and Implementation Limitations (Transparent Disclosure)
The following limitations help enterprises make informed risk decisions and do not indicate the product is unusable:
| Domain | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Side Channels** | Mitigated by microcode patches and constant-time crypto; new side-channel research may still propose new models |
| **SGX EPC Capacity** | High concurrency may cause paging with latency increase; does not change design confidentiality goals |
| **Hardware Vendor Trust** | Intel and AMD are trust roots in the remote attestation chain; can be combined with multi-vendor verification policies |
| **Decryption Window** | Plaintext exists during decryption and injection in a very brief Enclave window; mitigated by memory page pinning and similar techniques |
***
## Crypto and Protocol Selection
**Cross-product shared** (AES-256-GCM, HKDF-SHA-256, PASETO v4.local basics, DCAP, immudb audit principles): [Platform Security Foundation: Sections 3–5](/about-toani/platform-security.md#cryptographic-primitives-and-protocol-selection-cross-platform).
**toani Control product-specific / Execution chain additions**:
| Category | Selection |
| --------------------------- | --------------------------------------------------------------------------------------- |
| **Dual Hardware Isolation** | Intel SGX (key/Token) + **AMD SEV-SNP** (connector VM) |
| **Connector Runtime** | **gVisor (runsc)** |
| **Credential Injection** | **RA-TLS** (secure injection of short-term credentials from SGX to connector) |
| **Action Token** | PASETO v4.local + **Redis** single-use consumption / short TTL (execution chain) |
| **Transport** | **mTLS 1.3**, restricted to strong cipher suites (management plane and execution chain) |
For more implementation details, see [Execution Plane Technical Architecture](/toani-control/execution-plane.md).
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.toani.ai/toani-control/security-architecture.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.