Secure Family Document Vault with Blockchain Verification
A cutting-edge family document management system that combines military-grade encryption, distributed cloud storage, and Ethereum blockchain verification to provide unparalleled security for your family's most important documents.
- AES-256-GCM Encryption: End-to-end encryption for all stored documents
- SHA-256 File Hashing: Cryptographic integrity verification
- Zero-Knowledge Architecture: Server never sees unencrypted data
- Distributed Cloud Storage: Files split across multiple secure nodes
- Ethereum On-Chain Records: Immutable document hashes stored on Ethereum
- Smart Contract Integration: Automated verification and timestamping
- MetaMask Wallet Support: Direct blockchain interaction
- Gas-Optimized Transactions: Cost-effective on-chain operations
- Educational Onboarding: Simple setup for non-technical users
- Role-Based Access Control: Owner and member permissions
- Granular Document Sharing: Share specific documents with family members
- Real-Time Notifications: Instant alerts for security events
- Multi-Device Synchronization: Access from anywhere, anytime
- Category Organization: IDs, Banking, Insurance, Property, Passwords
- Smart Upload Interface: Category-specific forms and validation
- Advanced Search & Filtering: Find documents instantly
- Version Control: Track document changes over time
- Responsive Design: Perfect on desktop, tablet, and mobile
- Dark/Light Mode: Comfortable viewing in any environment
- Smooth Animations: Fluid transitions and micro-interactions
- Accessibility First: WCAG 2.1 AA compliant
- Node.js 18+ and npm
- MongoDB 7.0+
- MetaMask browser extension (optional - for blockchain verification features)
- Git
-
Clone the repository
git clone https://github.com/itzdineshx/Kudumba-Vault.git cd Kudumba-Vault -
Install dependencies
# Install server dependencies cd server && npm install # Install client dependencies cd ../ && npm install
-
Environment Setup
# Copy environment files cp server/.env.example server/.env cp .env.example .env # Edit server/.env with your MongoDB URI and JWT secret # Edit .env with your configuration
-
Start MongoDB
# Using Docker docker run -d -p 27017:27017 --name mongodb mongo:latest # Or using local MongoDB installation mongod
-
Start the application
# Terminal 1: Start the server cd server && npm run dev # Terminal 2: Start the client npm run dev
-
Access the application
- Open http://localhost:5173 in your browser
- Create your family vault account
- Blockchain features are optional - family members can use all core features without MetaMask
- Owners can enable blockchain verification for enhanced security
Kudumba-Vault is designed so that blockchain features are completely optional. Family members can:
- Upload and access documents with full AES-256-GCM encryption
- Share documents securely within the family vault
- Use all core features without any blockchain knowledge
- Receive notifications about shared documents
For users who want maximum security verification:
- MetaMask Setup Guide: In-app tutorials walk through MetaMask installation
- One-Click Connection: Simple "Connect Wallet" button with clear instructions
- Educational Tooltips: Explanations of what blockchain verification does
- Owner-Only Option: Family owners can enable blockchain features for the entire vault
- Fallback Security: All documents remain encrypted even without blockchain
- Same Encryption: AES-256-GCM encryption applies to all documents
- Role-Based Access: Family members see only shared documents
- Audit Logging: All access attempts are tracked
- Zero-Knowledge: Server never sees unencrypted data
Main dashboard showing document categories and family vault overview
Dynamic form for uploading documents with category selection
Document listing with search and filtering capabilities
Document encryption and hashing process visualization
Interface for sharing documents with family members
Blockchain backup and verification features
Secure login interface for family members
Real-time alerts and notifications system
Document recovery and backup restoration
User authorization and permission management
High-level system architecture showing frontend, backend, database, and blockchain integration
Complete application workflow from user registration to document verification
- React 18 with TypeScript for type safety
- Vite for fast development and optimized builds
- Tailwind CSS for utility-first styling
- Framer Motion for smooth animations
- Shadcn/UI for consistent component library
- React Router for client-side routing
- Node.js + Express for RESTful API
- MongoDB + Mongoose for data persistence
- JWT Authentication with role-based access
- Multer for secure file uploads
- Web3.js/Ethers.js for blockchain integration
- AES-256-GCM symmetric encryption
- PBKDF2 key derivation
- HMAC-SHA256 integrity verification
- Zero-trust model implementation
- Rate limiting and CORS protection
- File Reception: Raw file uploaded via HTTPS
- Key Generation: PBKDF2-derived AES-256 key
- Encryption: AES-256-GCM with random IV
- Hashing: SHA-256 hash of original file
- Storage: Encrypted blob stored in MongoDB
- Blockchain: Hash recorded on Ethereum (optional)
- JWT Tokens: Stateless authentication
- Role-Based Permissions: Owner vs Member access
- Document-Level Sharing: Granular permission control
- Session Management: Automatic token refresh
- Audit Logging: All access attempts logged
- HTTPS Only: All communications encrypted
- CORS Protection: Domain whitelisting
- Rate Limiting: DDoS protection
- Input Validation: XSS and injection prevention
- Security Headers: OWASP recommended headers
POST /api/auth/register
POST /api/auth/login
GET /api/auth/meGET /api/documents # List documents (role-filtered)
POST /api/documents # Upload document
GET /api/documents/:id # Get document details
DELETE /api/documents/:id # Delete documentPOST /api/documents/:id/share # Share with member
DELETE /api/documents/:id/revoke # Revoke accessGET /api/members # List family members
POST /api/members # Add family member
DELETE /api/members/:id # Remove member- Fade In/Out: Smooth opacity transitions between routes
- Slide Animations: Directional navigation with spring physics
- Scale Effects: Modal dialogs with bounce animations
- Hover States: Card lift effects with shadow transitions
- Button Animations: Scale and color transitions on interaction
- Loading States: Skeleton screens with shimmer effects
- Progress Bars: Smooth width transitions during uploads
- Field Focus: Border color and label position animations
- Validation: Error state animations with shake effects
- Success States: Checkmark animations with confetti effects
- Chart Animations: SVG path drawing with easing functions
- List Transitions: Staggered item animations on load
- Filter Effects: Smooth category filtering with layout shifts
# Build the frontend
npm run build
# Build the backend
cd server && npm run build# Build and run with Docker Compose
docker-compose up -d
# Or build individual services
docker build -t kudumba-vault-frontend .
docker build -t kudumba-vault-backend .# Server (.env)
MONGODB_URI=mongodb://localhost:27017/kudumba-vault
JWT_SECRET=your-super-secure-jwt-secret-here
PORT=5000
# Client (.env)
VITE_API_URL=http://localhost:5000/api
VITE_BLOCKCHAIN_NETWORK=mainnetWe welcome contributions! Please see our Contributing Guide for details.
# Fork and clone
git clone https://github.com/your-username/Kudumba-Vault.git
cd Kudumba-Vault
# Install dependencies
npm install
cd server && npm install && cd ..
# Start development servers
npm run dev # Frontend on :5173
cd server && npm run dev # Backend on :5000- ESLint and Prettier for code formatting
- Husky pre-commit hooks for quality checks
- Conventional Commits for commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
- Ethereum Foundation for blockchain infrastructure
- MetaMask for wallet integration
- MongoDB for reliable data storage
- React Community for amazing frontend tools
- Open Source Contributors for their valuable contributions
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: support@kudumba-vault.com
Built with ❤️ for families worldwide