A modern, secure desktop application for encrypting and decrypting folders with military-grade cryptography
Streaming encryption • Zero-knowledge architecture • Professional-grade security
Features • Quick Start • Documentation • Contributing
Most encryption tools are either:
- Too complex for everyday users
- Or rely on cloud-based processing
I built FolderVault to explore:
- How encryption actually works in real-world applications
- How to handle large files securely using streaming
- How to design systems with privacy-first architecture
This project helped me understand:
- Applied cryptography (AES-256-GCM)
- Secure key derivation (scrypt)
- Practical challenges in file encryption systems
| 🔒 Security | ⚡ Performance | 🎨 User Experience |
|---|---|---|
| AES-256-GCM authenticated encryption | Streaming I/O - minimal RAM usage | Drag & drop folder selection |
| scrypt KDF (N=16384, r=8, p=1) | Per-file progress tracking | Real-time ETA and speed metrics |
| Zero-knowledge architecture | Cooperative cancellation | Modern, intuitive UI |
| Secure-delete option (multi-pass) | Atomic operations | Live progress bars |
- ✅ AES-256-GCM - Industry-standard authenticated encryption
- ✅ scrypt Key Derivation - Memory-hard password hashing (N=16384, r=8, p=1)
- ✅ Unique Salt & IV - Each file gets its own salt and initialization vector
- ✅ Authentication Tags - Prevents tampering and ensures data integrity
- ✅ Local Key Derivation - Passwords never leave your machine
- ✅ Secure Delete - Multi-pass overwrite for original files (best-effort)
- 🚀 Streaming Pipeline - Handles large files without loading into memory
- 📊 Real-time Progress - Per-file and overall progress tracking
- ⏱️ ETA Calculation - Estimated time remaining with speed metrics
- 🛑 Cancellation Support - Stop operations safely at any time
- 💾 Atomic Writes - Decrypted files written to temp, then renamed atomically
- 🖱️ Drag & Drop - Simply drag folders into the app
- 📁 Folder Browser - Native folder picker integration
- 📈 Visual Progress - Beautiful progress bars and status indicators
- 🔄 Live Updates - Real-time file processing status
- 📝 Activity Log - Detailed operation logs for troubleshooting
- Node.js 16+ and npm
- Windows 10/11 (currently optimized for Windows)
- Git (for cloning the repository)
📦 Option 1: Development Mode (Recommended for Contributors)
# 1. Clone the repository
git clone https://github.com/yourname/folder-vault.git
cd folder-vault
# 2. Install dependencies
npm ci
# 3. Run the application
npm start🎯 Option 2: Quick Test (3 Commands)
# Install dependencies
npm ci
# Run the app
npm start
# Run automated tests
npm run test-harness📦 Option 3: Build Portable Executable
# Build a portable Windows executable
npm run build
# Output will be in ./dist/FolderVault-win32-x64/
# Just run FolderVault.exe - no installation needed!
⚠️ Note: Unsigned builds may trigger Windows SmartScreen warnings. This is expected for test builds.
┌─────────────────────────────────────────────────────────┐
│ FolderVault │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Renderer │ ◄─────► │ Preload │ │
│ │ (UI Layer) │ IPC │ (Bridge) │ │
│ └──────────────┘ └──────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌──────────────┐ │
│ └─────────────►│ Main Process│ │
│ │ (Crypto) │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
Each encrypted file follows this structure:
┌──────────┬──────────┬──────────┬──────────────┬──────────────┐
│ MAGIC │ SALT │ IV │ CIPHERTEXT │ AUTH_TAG │
│ (8 B) │ (16 B) │ (12 B) │ (varies) │ (16 B) │
└──────────┴──────────┴──────────┴──────────────┴──────────────┘
- MAGIC: File identifier (
ELECTRON) - SALT: Random 16-byte salt for key derivation
- IV: 12-byte initialization vector for GCM mode
- CIPHERTEXT: Encrypted file content
- AUTH_TAG: 16-byte authentication tag (GCM)
FolderVault/
├── main.js # Electron main process (crypto operations)
├── preload.js # Secure IPC bridge
├── renderer.js # UI logic and event handling
├── renderer.css # Application styles
├── index.html # Application UI structure
├── test_harness.js # Automated test suite
└── package.json # Dependencies and scripts
🔧 Advanced Configuration
If you plan to distribute FolderVault publicly, code signing is recommended:
-
Obtain a Certificate: Get a code-signing certificate (PFX) from a CA (DigiCert, Sectigo, GlobalSign)
-
Sign the Executable:
signtool sign /f C:\path\to\your.pfx /p YourPfxPassword `
/tr http://timestamp.digicert.com /td SHA256 /fd SHA256 `
C:\path\to\FolderVault.exe
# Verify the signature
signtool verify /pa /v C:\path\to\FolderVault.exe- CI/CD Integration: For automated signing, consider using:
- GitHub Actions with secrets
- Azure Key Vault
- Managed signing services
⚠️ Important Security Notes
- SSDs: Secure-delete cannot guarantee erasure on SSDs due to wear-leveling
- Network Filesystems: May not support secure overwrite operations
- Cloud Sync: Files synced to OneDrive/Dropbox may retain versions
- Best Practice: Use secure-delete as an additional layer, not a guarantee
- ✅ Passwords are never transmitted over the network
- ✅ Keys are derived locally using scrypt
- ✅ Keys are zeroed from memory after use
⚠️ Remember: If you lose your password, files cannot be recovered
- Strong Passwords: Use long, complex passwords (16+ characters)
- Backup: Keep encrypted backups in multiple locations
- Testing: Test decryption before deleting originals
- Updates: Keep the application updated for security patches
Run the Test Suite
The project includes a comprehensive test harness:
npm run test-harnessWhat it tests:
- ✅ Encryption/decryption correctness
- ✅ Wrong password handling
- ✅ Secure delete functionality
- ✅ Cancellation support
- ✅ File format validation
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Quick Contribution Guide
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Test thoroughly (
npm run test-harness) - Commit with clear messages
- Push to your branch
- Open a Pull Request
- Keep PRs focused and small
- Include tests for new features
- For cryptographic changes, include rationale and tests
- Follow existing code style
- Update documentation as needed
Common Issues & Solutions
Solution:
- Ensure Node.js 16+ is installed
- Try running from a local path (not OneDrive):
C:\dev\folder-vault - Clear
node_modulesand reinstall:rm -r node_modules && npm ci
Solution:
- This is expected for unsigned builds
- For production, obtain a code-signing certificate
- Users can click "More info" → "Run anyway" for test builds
Solution:
- Secure-delete is best-effort and may not work on:
- SSDs (wear-leveling)
- Network filesystems
- Cloud-synced folders
- Consider using "Keep originals" option for important files
Solution:
- Run as administrator if needed
- Check folder permissions
- Ensure files aren't locked by other applications
Click to view performance metrics
Add your performance benchmarks here
Example format:
- Small files (< 1 MB): ~50-100 files/sec
- Medium files (1-100 MB): ~10-50 MB/sec
- Large files (> 100 MB): Streaming, memory-efficient
- Encryption is easy to use but hard to implement correctly
- Secure file handling is more complex than algorithms themselves
- Performance + security trade-offs matter in real systems
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 HNikhil
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
- Built with Electron
- Uses Node.js crypto module
- Inspired by the need for simple, secure file encryption
Made with ❤️ by HNikhil