StealthVault

StealthVault is an FHE-enabled document vault that stores document metadata on-chain and keeps document bodies encrypted client-side. Each document is anchored to a locally generated EVM address A. The address A is encrypted with Zama FHE and stored on-chain so only authorized users can decrypt it and use A as the secret key material for encrypting and decrypting the document body.

This repository contains:

• A Hardhat-based smart contract for encrypted document registry and access control.
• Tasks and deployment scripts for local and Sepolia deployments.
• A Vite + React frontend that implements the full creation, decryption, editing, and sharing flow.

Why this project

Traditional document collaboration tools require trusting centralized servers with plain-text data. StealthVault flips the model:

• Documents are created and encrypted entirely on the client.
• The chain stores only ciphertexts and encrypted access keys.
• Access can be delegated without revealing the underlying document key in plain text.

The result is a vault where collaboration is possible without giving the chain, relayers, or storage providers visibility into document contents.

Problems solved

• Key escrow risk: the document encryption key is never stored in plaintext.
• On-chain privacy: the document body is never revealed on-chain, only ciphertext.
• Collaborative access: owners can authorize additional editors without re-encrypting the document for each user manually.
• Separation of concerns: read-only queries use viem, while write operations use ethers and the Zama relayer for encryption.

Core advantages

• End-to-end encryption: the document body is encrypted client-side with AES-GCM derived from A.
• FHE-based key sharing: A is encrypted with Zama FHE, enabling safe on-chain distribution.
• Deterministic access flow: access grants are explicit and auditable on-chain.
• Minimal data exposure: no plaintext document body or plaintext key ever reaches the chain.
• Composable integration: the contract can be integrated into other systems without changing the encryption model.

How it works (end-to-end flow)

1. Create document
   • Generate a random EVM address A locally.
   • Encrypt A with Zama FHE via the relayer.
   • Submit the document name, empty document body, and encrypted A on-chain.
2. Read and decrypt
   • Fetch the encrypted A and document metadata from the chain.
   • Decrypt A in the client.
   • Use A to derive a symmetric key (AES-GCM) and decrypt the document body.
3. Edit and update
   • Edit the document body locally.
   • Encrypt the updated body with the symmetric key derived from A.
   • Submit the encrypted body on-chain.
4. Grant access
   • The owner calls grantAccess with an editor address.
   • The new editor can decrypt A and submit encrypted edits.

Technology stack

• Smart contracts: Hardhat, Solidity
• Confidential compute: Zama FHEVM, relayer SDK
• Frontend: React + Vite (no Tailwind)
• Reads: viem
• Writes: ethers
• Package manager: npm

Project structure

• contracts/: FHE-enabled document registry contracts
• deploy/: Hardhat deploy scripts
• tasks/: CLI tasks for creating documents and granting access
• test/: Contract tests
• frontend/: Vite + React app, no Tailwind, no env vars
• docs/: Zama integration references

Contract design (high level)

• Document metadata: name, owner, encrypted document body, encrypted A.
• Access control: owner-managed allow list stored on-chain.
• Read paths: public view functions that return encrypted data only.
• Write paths: guarded by authorization checks; users submit ciphertext only.

Frontend architecture

• Key management: A is generated and held in memory during the session.
• Encryption: AES-GCM encryption/decryption performed client-side.
• Zama relayer: handles FHE encryption and decryption of A.
• Wallet flow: Rainbow + ethers for signing, viem for reads.
• No persistent storage: no local storage usage; secrets stay in memory only.
• Network policy: frontend targets Sepolia and should not use localhost RPCs.

Security and privacy model

• Threat model: on-chain data, public RPCs, and relayer infrastructure are assumed to be observable by third parties.
• Data exposure: only encrypted content and encrypted keys are stored on-chain.
• Key custody: A is never stored in plaintext on-chain and must be re-derived or re-decrypted by authorized users.
• Access revocation: access removal is possible, but previously authorized users may still have historical ciphertexts. Treat revocation as forward-only.

Limitations

• Gas costs: on-chain storage of ciphertext is more expensive than off-chain storage.
• Metadata visibility: document names are public unless you choose to obfuscate them.
• Revocation scope: removing access does not revoke previously downloaded ciphertext.
• Relayer availability: FHE encryption depends on relayer uptime.

Setup

1. Install dependencies in the root workspace:

   npm install

2. Install frontend deps:

   cd frontend
   npm install

3. Configure environment variables in the repository root .env (private key only, no mnemonic):

   INFURA_API_KEY=your_infura_key
   PRIVATE_KEY=0xabc... # wallet used for deployments
   ETHERSCAN_API_KEY=optional
   

4. Compile and test the contracts:

   npm run compile
   npm test

Local development (contracts and tasks)

• Start a local node (FHE mock): npx hardhat node
• Deploy the contract: npx hardhat deploy --network localhost
• Run a task:

  npx hardhat --network localhost task:create-doc --name "DraftOne"
  npx hardhat --network localhost task:grant-access --name "DraftOne" --editor <address>

Sepolia deployment

• Deploy with the configured private key:

  npx hardhat deploy --network sepolia

• ABI and address are written to deployments/sepolia/StealthVault.json. Copy the ABI/address into frontend/src/config/contracts.ts.
• Optional verification:

  npx hardhat verify --network sepolia <CONTRACT_ADDRESS>

Usage guide (frontend)

1. Create: enter a document name and click create.
2. Decrypt: click decrypt to unlock A and read the document.
3. Edit: update the document body and submit encrypted changes.
4. Share: add an editor address to grant access.

Testing

• Contract tests:

  npm test

• The frontend is validated manually with wallet interactions.

Future roadmap

• Off-chain storage: optional IPFS/Arweave storage for large ciphertexts while keeping hashes on-chain.
• Key rotation: re-encrypt document bodies under a new A to invalidate old ciphertexts.
• Metadata privacy: optional name encryption or name hashing to reduce metadata leakage.
• Role-based permissions: support read-only vs edit-only roles.
• Batch updates: reduce gas for multi-document workflows.
• UX improvements: upload/download helpers, conflict resolution, and activity history.

License

MIT