🔐 WalrusVault

A decentralized encrypted file vault built on Sui + Walrus + zkLogin.

🌟 Features

• Zero-Knowledge Authentication: Login with Google using zkLogin (no passwords!)
• End-to-End Encryption: Files are encrypted client-side before upload
• Decentralized Storage: Files stored on Walrus (decentralized blob storage)
• On-Chain Metadata: File metadata secured on Sui blockchain
• Secure Sharing: Share encrypted files with other users via Sui addresses

🏗️ Architecture

┌─────────────┐
│   Frontend  │ (React + TypeScript + Tailwind)
│  (zkLogin)  │
└──────┬──────┘
       │
       ├─────────────┐
       │             │
       ▼             ▼
┌─────────────┐ ┌──────────────┐
│  Walrus     │ │  Sui Chain   │
│  (Storage)  │ │  (Metadata)  │
└─────────────┘ └──────────────┘

🚀 Quick Start

Prerequisites

• Node.js 18+
• Sui CLI (Installation guide)
• Google OAuth Client ID (Setup guide)

1. Clone & Install

cd walrus-vault/frontend
npm install

2. Configure Environment

Create .env file:

VITE_ZKLOGIN_CLIENT_ID=your-google-client-id
VITE_ZKLOGIN_REDIRECT_URI=http://localhost:5173/auth/callback
VITE_SUI_NETWORK=testnet
VITE_SUI_PACKAGE_ID=<deployed-package-id>
VITE_WALRUS_API_URL=https://publisher.walrus-testnet.walrus.space
VITE_WALRUS_AGGREGATOR_URL=https://aggregator.walrus-testnet.walrus.space

3. Deploy Move Contract

cd ../move
sui client switch --env testnet
sui move build
sui client publish --gas-budget 100000000

Copy the published package ID to .env as VITE_SUI_PACKAGE_ID.

4. Run Frontend

cd ../frontend
npm run dev

Visit http://localhost:5173

📖 How It Works

1. Authentication (zkLogin)

• User clicks "Continue with Google"
• Google OAuth flow generates JWT
• JWT + ephemeral keypair → Sui address (deterministic)
• User's keypair stored in session

2. File Upload

• File encrypted with AES-256-GCM (symmetric key)
• Symmetric key encrypted with user's public key
• Encrypted file → uploaded to Walrus → returns CID
• Metadata (CID, encrypted key, URI) → stored on Sui

3. File Download

• Fetch metadata from Sui (by object ID)
• Download encrypted file from Walrus (by CID)
• Decrypt symmetric key with user's private key
• Decrypt file with symmetric key
• Download to browser

4. File Sharing

• Owner re-encrypts symmetric key with recipient's public key
• Call add_grantee() on Sui with recipient address + re-encrypted key
• Recipient can now decrypt the file

🔐 Security Model

• Client-Side Encryption: Files never leave device unencrypted
• Zero-Knowledge Login: No passwords stored anywhere
• Key Derivation: User keys derived from JWT + PIN (optional)
• Access Control: On-chain verification of file ownership & sharing

🧪 Testing

1. Login via zkLogin (Google)
2. Upload a file (e.g., test.pdf)
3. Verify metadata on Sui Explorer
4. Download the file (decrypts automatically)
5. Share with another Sui address
6. Recipient can download & decrypt

📦 Tech Stack

Frontend

• React 18 + TypeScript
• Vite (build tool)
• Tailwind CSS (styling)
• @mysten/dapp-kit (Sui wallet integration)
• @mysten/zklogin (authentication)
• TweetNaCl (encryption)

Backend (On-Chain)

• Sui Move (smart contracts)
• Walrus (decentralized storage)

🛠️ Project Structure

walrus-vault/
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── hooks/           # Custom hooks
│   │   ├── utils/           # Encryption, Walrus, Sui utils
│   │   ├── types/           # TypeScript types
│   │   └── App.tsx
│   └── package.json
└── move/
    ├── sources/
    │   └── walrus_vault.move
    └── Move.toml

🐛 Troubleshooting

zkLogin Issues

• Ensure VITE_ZKLOGIN_CLIENT_ID is correct
• Check redirect URI matches Google OAuth settings
• Clear browser cache & localStorage

Walrus Upload Fails

• Check network (testnet/mainnet)
• Verify Walrus endpoints are reachable
• Ensure file size is within limits

Sui Transaction Fails

• Check gas balance (sui client gas)
• Verify package ID is correct
• Check transaction on Sui Explorer

🔮 Future Enhancements

• Support multiple OAuth providers (GitHub, Discord)
• File versioning & history
• Folder organization
• Public/private file links
• File expiration (time-locked encryption)
• Mobile app (React Native)

📄 License

MIT

🤝 Contributing

PRs welcome! Please open an issue first to discuss changes.

---

Built with ❤️ on Sui + Walrus