# Credential Stack

This page details toani Vault's underlying implementation, including the TEE security model, four-layer key hierarchy, Sandbox isolation architecture, and audit log implementation.

> **Platform-level shared explanations** (TEE basics, encryption choices, DCAP, immudb principles, and differences from toani Control): [toani.ai Platform Security Foundations](/about-toani/platform-security.md).

## TEE Security Model

All sensitive operations in toani Vault run within Intel SGX TEE (Trusted Execution Environment).

**TEE general concepts** (memory isolation / EPC, remote attestation, sealed storage) are covered in [Platform Security Foundations, Section 2](/about-toani/platform-security.md#tee-fundamentals). **Intel DCAP and MRENCLAVE** are in [Section 4](/about-toani/platform-security.md#intel-dcap-remote-attestation).

toani Vault's attestation report is available via `GET /api/v1/attestation/report`.

## Four-Layer Key Hierarchy

Credential encryption uses a layered HKDF derivation architecture:

<figure><img src="/files/8senuP6nSm2i6ebc3Mmt" alt=""><figcaption></figcaption></figure>

**Invariants:**

* L3 key is never stored; dynamically derived on each use
* After AES decryption, plaintext in enclave memory is `zeroize`d immediately after use
* Agent operation instructions use `{{CREDENTIAL.xxx}}` placeholders; plaintext substitution happens inside enclave
* Only ciphertexts are stored in database; no keys at any layer are stored

## TEE Sandbox Isolation Architecture

Sandbox runs a complete Chromium browser automation stack inside the TEE enclave with multiple nested isolation layers:

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

### Isolation Layer Responsibilities

| Layer                    | Technology        | Responsibility                                               |
| ------------------------ | ----------------- | ------------------------------------------------------------ |
| **SGX Enclave**          | Intel SGX         | Memory encryption, externally unreadable                     |
| **nsjail**               | Linux nsjail      | Chromium process cannot access host filesystem               |
| **Namespaces**           | Linux Kernel      | Complete process, network, mount isolation                   |
| **Seccomp**              | Seccomp-BPF       | Restrict system calls, prevent escape                        |
| **cgroup**               | Linux cgroup v2   | Limit single session CPU/memory, prevent exhaustion          |
| **Credential Namespace** | Application layer | Credentials isolated per session, not shared across sessions |

### AI Operation Review Engine

Each browser operation is independently reviewed by the LLM review engine in the enclave before execution:

* **Intent Alignment Check**: Is the operation aligned with the session's declared task goal?
* **Scope Boundary Check**: Does the operation exceed the authorized service URL scope?
* **Sensitive Operation Detection**: Are there signs of data exfiltration, cross-site navigation anomalies?

Operations are executed only after passing review; rejections are written to the audit log.

### Credential Injection Timing

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

## zkMe Credential Injection and Directed Presentation

For `zkme_credential` credentials, the injection flow is cryptographically identical to passwords, but adds **semantic review** on top:

### W3C VC Structure

A `zkme_credential`'s `plaintext_data` contains:

* `credential_json` (object): full W3C Verifiable Credential with `@context`, `type`, `issuer`, `credentialSubject`, `proof`
* `did` (string): the user's decentralized identifier
* `zk_proof` (string, optional): zero-knowledge proof generated by zkMe (content varies by credential type)
* `credential_type` (string, optional): zkMe internal credential classification, e.g. `"zkKYC"`, `"zkPoAI"`, `"AMLMe"`, `"zkKYA"`

### AI Review for Directed Presentation

Because zkMe Credentials carry sensitive identity or compliance claims, the in-TEE AI review engine applies two additional constraints before `executeScript` or `fill`, "directed presentation" means the user chooses which third parties receive the credential; scope is controlled via a domain allowlist inside the TEE:

1. **Presentation-scope validation** — confirms the injection target URL belongs to a user-authorized service domain (e.g. `chase.com`), preventing accidental VC submission to phishing sites
2. **Field-leakage detection** — analyzes script content to ensure `credential_json` is not written to globals, `localStorage`, or sent to unexpected API endpoints

After both checks pass, the VC is decrypted in the TEE and injected into the target page's verification widget. The third party (e.g. bank) independently verifies the zkProof or signature; neither toani Vault nor the agent touches the raw personal or financial data needed for verification.

## Audit Log Implementation

**immudb selection rationale, Merkle, Chain Hash, and Ed25519 signature general principles** are in [Platform Security Foundations, Section 5](/about-toani/platform-security.md#immudb-audit-foundations).

### toani Vault Implementation Details (Product-Specific)

* **Ed25519 Single Signature**: Each audit record is signed by an Ed25519 private key held **inside the TEE enclave**; the signature includes the enclave measurement (MRENCLAVE), making forgery practically require simultaneous control of enclave logic and hardware
* **Chain Hash Verification**: Chain digest structure and mathematical properties are in platform documentation; any tampering of intermediate records causes subsequent `chain_hash` values to differ from recalculation, verifiable via `POST /api/v1/audit/logs/:id/verify`
* **On-Chain Anchoring**: immudb's Merkle tree root hash is published to the toani.ai state contract **approximately every 10 minutes**, enabling cross-organizational independent verification. Even if toani Vault servers are fully compromised, already-published root hashes cannot be retrospectively altered

### Audit Event Types

| Event Type                 | Triggered When                            |
| -------------------------- | ----------------------------------------- |
| `session_initiated`        | Create Sandbox session                    |
| `credential_access`        | Credential accessed and decrypted         |
| `sandbox_operation`        | Execute browser operation                 |
| `policy_rejected`          | Operation rejected by policy or AI review |
| `human_approval_requested` | HITL human approval triggered             |
| `human_approval_received`  | Human approval result received            |
| `session_closed`           | Session closed                            |


---

# 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/credential-stack.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.