How It Works

The Document Vault operates through two primary flows: uploading documents for encrypted storage, and downloading documents for viewing or sharing. Both flows rely on the TEE attestor to handle encryption and decryption, ensuring that plaintext documents never exist outside of hardware-isolated enclaves.

Upload Flow

When a user uploads a document to the vault, the following sequence executes:

┌──────────────┐    ┌──────────────────┐    ┌─────────────┐    ┌──────────────┐
│ User Browser │───>│ TEE Attestor     │───>│ IPFS/Pinata │    │ Cartesi      │
│              │    │                  │    │             │    │ Rollup       │
│ 1. Select    │    │ 2. Receive file  │    │ 4. Store    │    │              │
│    file      │    │ 3. Encrypt with  │    │    encrypted│    │ 5. Record    │
│              │    │    AES-256-GCM   │    │    file     │    │    metadata  │
└──────────────┘    └──────────────────┘    └─────────────┘    └──────────────┘

Step-by-Step Upload

1. File selection: The user opens the vault interface, selects a file from their device, and chooses a document type (identity, financial, education, legal, or medical).

2. Attestation type selection: The user selects whether the document is self-attested (uploaded by the user without third-party verification) or verified (attested by an institutional verifier).

3. Secure transmission to TEE: The file is transmitted to the TEE attestor over a TLS-encrypted channel. The user's wallet signature accompanies the request to authenticate the upload.

4. Encryption inside the TEE: The TEE derives a unique encryption key for this document and encrypts it using AES-256-GCM. The key derivation uses the user's wallet-derived secret and a per-document salt.

5. IPFS upload: The encrypted file is uploaded to IPFS through Pinata's private gateway. Pinata returns a content identifier (CID) that uniquely addresses the encrypted file on the IPFS network.

6. On-chain metadata submission: The attestor submits metadata to the Cartesi rollup on Arbitrum containing references needed to locate and decrypt the document later (such as the IPFS CID, document type, encryption parameters, user DID, and timestamp).

7. Confirmation: The user receives confirmation that their document has been stored. The plaintext file is purged from the TEE's memory.

Download Flow

When a user wants to retrieve a document from the vault:

┌──────────────┐    ┌──────────────────┐    ┌─────────────┐
│ User Browser │<───│ TEE Attestor     │<───│ IPFS/Pinata │
│              │    │                  │    │             │
│ 4. Receive   │    │ 2. Fetch from    │    │ 1. Retrieve │
│    plaintext │    │    IPFS          │    │    encrypted│
│    file      │    │ 3. Decrypt with  │    │    file     │
│              │    │    AES-256-GCM   │    │             │
└──────────────┘    └──────────────────┘    └─────────────┘

Step-by-Step Download

1. Authentication: The user connects their wallet and signs a message to prove ownership. The attestor verifies the signature against the DID associated with the document.

2. Metadata retrieval: The attestor queries the on-chain metadata to retrieve the IPFS CID and encryption parameters for the requested document.

3. IPFS fetch: The attestor fetches the encrypted file from IPFS via the Pinata private gateway using the stored CID.

4. Decryption inside the TEE: The TEE re-derives the encryption key and decrypts the file using AES-256-GCM. The authentication tag is verified to confirm the ciphertext has not been modified since encryption.

5. Delivery: The plaintext file is transmitted to the user's browser over TLS. The plaintext is then purged from TEE memory.

What Never Leaves the TEE

The following data exists only inside the TEE during operation and is never persisted or transmitted:

• Plaintext document contents during encryption and decryption
• Derived encryption keys
• Wallet-derived secrets used for key derivation

What Gets Stored Where

Data	Storage Location	Encrypted	Access
Document file (ciphertext)	IPFS via Pinata	Yes (AES-256-GCM)	Anyone with the CID (but unreadable)
IPFS CID	Cartesi rollup (on-chain)	No	Public
Document type	Cartesi rollup (on-chain)	No	Public
Encryption parameters	Cartesi rollup (on-chain)	No	Public (useless without wallet secret)
Encryption key	Nowhere (derived in TEE)	N/A	TEE only, during operation
Plaintext document	Nowhere (exists in TEE memory only)	N/A	TEE only, during operation

Failure Modes

• IPFS unavailability: If the Pinata gateway is unreachable, uploads fail gracefully with a user-facing error message.
• TEE failure: If the TEE attestor is unavailable, no encryption or decryption can occur. The system surfaces this as a service unavailability message. No data is at risk because no plaintext exists outside the TEE.
• On-chain submission failure: If the Cartesi rollup transaction fails, the encrypted file may already be on IPFS but will not appear in the user's vault until the on-chain metadata is confirmed.