# Security Architecture

This page explains toani Vault's security design philosophy and answers the core question: "How secure are credentials really?"

> **Platform-level shared security foundations** (TEE concepts, encryption choices, DCAP, immudb audit principles, and differences from toani Control) are covered in [toani.ai Platform Security Foundations](/about-toani/platform-security.md). For developer technical details, see [Credential Stack Technical Architecture](/toani-vault/credential-stack.md).

## Three Security Commitments

toani Vault's security model is built on three verifiable commitments:

| Commitment                                     | Technical Guarantee                                                                                         |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Credential plaintext never leaves hardware** | Intel SGX TEE memory isolation prevents host OS and platform operators from reading it                      |
| **Every access has a tamper-proof record**     | immudb Merkle Tree audit chain makes any tampering mathematically provable                                  |
| **Code can be independently verified**         | DCAP remote attestation protocol allows anyone to verify that the code running in TEE has not been modified |

> The correspondence between these three and toani.ai's **documentation-level unified commitments** is found in [Platform Security Foundations, Section 1](/about-toani/platform-security.md#unified-security-commitments).

## Why TEE Is Critical

The fundamental flaw in traditional credential management is that credential decryption must happen at the software layer, giving the platform the ability to read plaintext after decryption. TEE narrows decryption and sensitive computation to a hardware-isolated boundary. Intel SGX, memory isolation, remote attestation, and sealed storage are covered in [Platform Security Foundations, Section 2](/about-toani/platform-security.md#tee-fundamentals).

toani Vault chose to make **Intel SGX the primary path**, placing keys, browser sandbox, and enclave-level review in the same product narrative. Even if toani.ai's servers are completely compromised, attackers cannot decrypt stored credential ciphertexts without hardware capability.

## Four-Layer Key Hierarchy

Credential encryption uses a hierarchical key derivation architecture where each credential uses an independent encryption key, maximizing the scope of potential leaks:

<figure><img src="/files/TxXfLxQxIQXFpDQle717" alt=""><figcaption></figcaption></figure>

**Key invariant**: Keys never leave TEE memory. Even with complete database extraction, without the original SGX hardware, no credentials can be decrypted.

## Sandbox Isolation: Beyond Credential Storage

toani Vault's TEE Sandbox is not just secure credential storage; it runs complete browser automation workflows inside the TEE:

**Credential plaintext lifecycle during operations:**

1. Agent sends operation instruction with `{{CREDENTIAL.password}}` placeholder
2. Instruction enters TEE enclave
3. Enclave AI review engine validates operation compliance
4. Credential plaintext is derived and decrypted in enclave memory, replacing placeholders
5. Browser executes operation; memory is immediately zeroed after completion
6. **Results (screenshots/data) return to Agent; plaintext never leaves enclave**

## zkMe Credential Presentation

toani Vault not only manages traditional login credentials but also stores zkMe-issued zero-knowledge verifiable credentials (zkme\_credential) conforming to the W3C Verifiable Credentials standard.

zkMe is a Web3 identity credential network built on zero-knowledge proofs. Its credentials cover a wide range of compliance scenarios:

* **zkKYC Suite**: identity verification (zkPoC), anti-sybil (MeID), proof of location (zkPoL), proof of address (zkPoA), AML compliance (AMLMe)
* **zkOBS Suite**: accredited investor verification (zkPoAI), credit score (zkCredit), account asset proofs
* **zkKYB Suite**: business due diligence (UBO verification, vLEI)
* **zkKYA Suite**: AI agent identity authorization (APC/ACC/AIC/ARC/APF)

toani Vault can store and securely present any of the above zkMe Credential types.

### Same Security Level as Passwords

zkMe Credentials in toani Vault use the identical four-layer key hierarchy applied to username\_password and api\_key:

* **At rest**: The full W3C VC JSON (including credentialSubject, proof, etc.) is stored as AES-256-GCM ciphertext in PostgreSQL
* **In use**: Only inside the TEE enclave, via an HKDF-derived L3 key, can the VC plaintext be decrypted
* **After use**: The credential\_json buffer is immediately zeroized; no residue remains in memory

### Directed Presentation: Submitting zkMe Credentials to Controlled Third Parties

When a third party (e.g. bank, exchange) requires identity or compliance proof, the agent never needs to know the user's real name, ID number, or financial data. toani Vault uses a domain allowlist inside the TEE to ensure the VC is only submitted to user-authorized service domains:

1. The agent requests toani Vault with a zkme\_credential credential ID and operation intent (e.g. "submit KYC verification to chase.com")
2. The TEE enclave decrypts the full W3C VC
3. The Sandbox injects the VC or zkProof into the target page's verification widget via executeScript
4. The third-party service verifies the zkProof or VC signature and confirms the user's identity or qualification
5. **The agent receives only "verification approved"** — it never touches the raw identity or financial fields in the VC

This means: even if the agent process is compromised, the attacker cannot reconstruct the user's raw identity data.

## Audit Log: Mathematically Provable Immutability

Every credential access event is recorded in the immudb immutable database. For the general principles of why immudb and Merkle/hash chain are chosen, see [Platform Security Foundations, Section 5](/about-toani/platform-security.md#immudb-audit-foundations).

toani Vault **product implementation** adds:

* **Ed25519 Digital Signature**: Each log entry is signed by a private key held **inside the TEE enclave**; the signature includes the enclave measurement (MRENCLAVE), and forgery would require simultaneous control of hardware and code
* **Chain Hash**: Each log entry contains the hash digest of the previous one; any tampering invalidates all subsequent record hashes (verifiable via the check endpoint)
* **Merkle Root Anchoring**: The audit tree root hash is published to the toani.ai state contract **approximately every 10 minutes**, enabling cross-organizational independent verification

Compliance coverage: SOC 2 Type II, GDPR Article 30 (processing activity records), ISO 27001.

## Attack Surface Coverage

| Attack Scenario             | toani Vault Defense                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| Database breach             | Contains only ciphertexts; cannot decrypt without SGX hardware                             |
| Server compromise           | TEE memory is inaccessible; root privileges are ineffective                                |
| Malicious Agent instruction | AI review engine blocks anomalous operations from within enclave                           |
| Prompt injection            | Operation intent is independently reviewed inside TEE, not trusting Agent self-declaration |
| Insider threat              | Keys are hardware-managed; no personnel have plaintext access                              |
| Audit log tampering         | Chain Hash plus on-chain anchoring make tampering mathematically provable                  |


---

# 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-vault/security-architecture.md?ask=<question>
```

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.