FaceVault - Secure File Storage with Face-Based Encryption

FaceVault is a cutting-edge web application that combines military-grade encryption with biometric face authentication to provide unparalleled security for your sensitive files. Files are encrypted end-to-end on your device before being stored, ensuring that only you can access them using your face as the key.

Features

• 🔐 End-to-End Encryption: Files are encrypted client-side before upload using AES-256-GCM
• 👤 Face-Based Authentication: Your face acts as the key to unlock your encrypted files
• 🛡️ Zero-Knowledge Architecture: Server never sees your private keys or face data
• 📱 Multi-Device Support: Works on any modern browser with camera access
• 🚀 Military-Grade Security: RSA-OAEP 2048 + AES-GCM 256 encryption
• 🌐 Self-Hostable: Run your own instance with Docker

How It Works

1. Registration: Create an account with email/password and enroll your face
2. File Encryption: Files are encrypted on your device before upload
3. Secure Storage: Encrypted files are stored on the server (never decrypted)
4. Face Authentication: Your face unlocks the decryption key locally
5. File Access: Files are decrypted on your device for viewing/downloading

Security Model

Key Management

• Asymmetric key pairs (RSA-OAEP 2048) generated entirely client-side
• Private keys are wrapped with a KEK derived from your face template
• Public keys stored on server for file encryption
• Zero plaintext private keys ever leave your device

Biometric Security

• Face detection and recognition performed entirely client-side
• Multi-angle enrollment with liveness detection
• Face templates stored only in your browser's IndexedDB
• No raw face images stored or transmitted

File Encryption

• Files encrypted with AES-GCM 256 before leaving your device
• AES keys encrypted with your public key
• Server only stores encrypted blobs and metadata

Architecture

See ARCHITECTURE.md for detailed system architecture and data flow diagrams.

Tech Stack

Frontend

• React with TypeScript
• Tailwind CSS for styling
• shadcn/ui components
• Web Crypto API for encryption
• face-api.js for face recognition
• IndexedDB for local storage

Backend

• Node.js with Express
• TypeScript for type safety
• PostgreSQL for metadata storage
• Drizzle ORM for database operations

Security

• RSA-OAEP for asymmetric encryption
• AES-GCM for symmetric encryption
• PBKDF2 for key derivation
• Rate limiting and security middleware

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL database (local or Neon.tech)
• Modern web browser with camera access

Development Setup

1. Clone the repository:

git clone https://github.com/yourusername/facevault.git
cd facevault

2. Install dependencies:

npm install

3. Set up environment variables:

# For local PostgreSQL database
cp .env.example .env
# Edit .env with your configuration

# For Neon.tech database
cp .env.neon.example .env
# Edit .env with your Neon.tech configuration

4. Database Configuration: The application supports two database options that can be configured via environment variables:

• Local PostgreSQL: Set DATABASE_TYPE=local (default)
• Neon.tech: Set DATABASE_TYPE=neon

Example for local PostgreSQL:

DATABASE_URL=postgresql://username:password@localhost:5432/database_name
DATABASE_TYPE=local

Example for Neon.tech:

DATABASE_URL=postgresql://username:password@ep-xxx.us-east-2.aws.neon.tech/neondb
DATABASE_TYPE=neon

5. Start the development server:

npm run dev

Docker Setup

docker-compose up -d

Testing

Run unit tests:

npm test

Run integration tests:

npm run test:integration

API Documentation

Authentication

• POST /api/register - User registration
• POST /api/login - User login
• POST /api/logout - User logout
• POST /api/recovery/request - Password recovery request
• POST /api/recovery/verify - Password recovery verification

File Management

• POST /api/files/upload - Upload encrypted file
• GET /api/files - List user files
• GET /api/files/:id/download - Download encrypted file
• DELETE /api/files/:id - Delete file

User Management

• GET /api/user - Get user info
• POST /api/user/keys - Update user keys

Security Considerations

See SECURITY.md for detailed security considerations, privacy choices, and potential risks.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• face-api.js for face recognition
• Web Crypto API for client-side cryptography
• shadcn/ui for UI components
• All the open-source libraries that made this project possible

For a complete list of third-party dependencies and their licenses, see THIRD-PARTY-NOTICES.md.

Disclaimer

This is a demonstration project for educational purposes. While it implements strong security measures, it has not been audited by security professionals. Use at your own risk in production environments.