TrustVault 🔐

A secure, enterprise-grade password management system built with modern web technologies. TrustVault provides encrypted credential storage, role-based access control, audit logging, and team collaboration features.

📋 Table of Contents

• Overview
• Features
• Technology Stack
• Security Architecture
• System Requirements
• Installation & Setup
  • Local Development Setup
  • Docker Deployment
• Configuration
• API Documentation
• User Roles & Permissions
• Project Structure
• Development Guide
• Deployment Guide
• Security Best Practices
• Troubleshooting
• Contributing
• License

🎯 Overview

TrustVault is a full-stack password management application designed for teams and organizations that need secure credential storage with enterprise features. It implements industry-standard encryption practices with a two-tier key management system (Master Key + Data Encryption Key), comprehensive audit logging, and fine-grained access controls.

Key Highlights

• 🔒 Military-Grade Encryption: AES-256-GCM encryption for all sensitive data
• 👥 Team Collaboration: Share credentials securely with users and groups
• 📊 Audit Logging: Complete audit trail of all vault operations
• 🔑 Key Rotation: Automatic re-encryption during master key rotation
• 🚀 Modern Tech Stack: React 19, Node.js, MongoDB, Docker
• ⚡ Real-time Updates: React Query for optimized data fetching
• 🎨 Beautiful UI: Tailwind CSS with responsive design

✨ Features

Core Vault Features

• Secure Credential Storage

  • Store passwords, usernames, URLs, and notes with end-to-end encryption
  • Organize credentials with tags and categories
  • Quick search and filter capabilities
  • Password reveal with audit logging

• Sharing & Collaboration

  • Share credentials with individual users or groups
  • Two access levels: View-only and Edit permissions
  • Granular permission management per item

Security Features

• Advanced Encryption

  • AES-256-GCM encryption algorithm
  • Two-tier key management (Master Key + DEK)
  • Secure key wrapping and unwrapping
  • Key rotation with automatic re-encryption

• Authentication & Authorization

  • JWT-based authentication with access and refresh tokens
  • Argon2 password hashing
  • Role-based access control (RBAC)
  • Rate limiting to prevent brute force attacks
  • Secure session management with HTTP-only cookies

• Password Recovery

  • Forgot password flow with OTP verification
  • Time-limited OTP codes (5 minutes expiry)
  • Secure password reset mechanism

Administrative Features

• User Management

  • Create, update, and deactivate user accounts
  • Assign roles (User, Admin)
  • Monitor user activity and last login
  • Bulk user operations

• Group Management

  • Create and manage user groups
  • Assign users to multiple groups
  • Share credentials with entire groups
  • Group-based permissions

• Audit Logging

  • Comprehensive audit trail for all operations
  • Track who accessed what and when
  • Filter logs by user, action type, and date range
  • Export audit logs for compliance

• Security Settings

  • Master key rotation interface
  • View security status and key information
  • Monitor encryption key versions

User Features

• My Vault Dashboard

  • View all accessible credentials
  • Create and manage personal vault items
  • Access shared credentials
  • Quick search and filtering

• Activity Tracking

  • Personal activity log
  • View recent actions
  • Track credential access history

🛠 Technology Stack

Backend

• Runtime: Node.js (v18+)
• Framework: Express.js v5
• Database: MongoDB (Mongoose ODM)
• Authentication: JWT (jsonwebtoken)
• Encryption: Node.js Crypto (AES-256-GCM)
• Password Hashing: Argon2
• Security Headers: Helmet
• Rate Limiting: rate-limiter-flexible
• Logging: Winston
• Validation: Joi

Frontend

• Framework: React 19
• Build Tool: Vite 7
• Routing: React Router DOM v7
• State Management: React Query (TanStack Query v5)
• HTTP Client: Axios
• Styling: Tailwind CSS v4
• UI Components: Custom components with Lucide icons
• Form Validation: Zod v4

DevOps & Deployment

• Containerization: Docker & Docker Compose
• Web Server: Nginx (for frontend static files)
• Process Management: PM2 (optional for production)
• Environment Management: dotenv

🔐 Security Architecture

Encryption Model

TrustVault uses a two-tier key management system:

1. Master Encryption Key (MEK)

   • 32-byte key stored as base64 in environment variables
   • Never stored in the database
   • Used to encrypt/decrypt the Data Encryption Key (DEK)

2. Data Encryption Key (DEK)

   • 32-byte key generated on first initialization
   • Encrypted (wrapped) with the Master Key and stored in database
   • Loaded into memory on server startup
   • Used to encrypt/decrypt all vault items

Data Flow

Plaintext Data → Encrypt with DEK → Ciphertext + IV + AuthTag → Store in DB
DB → Ciphertext + IV + AuthTag → Decrypt with DEK → Plaintext Data

Key Rotation Process

When a master key rotation is initiated:

1. Generate new Data Encryption Key (DEK)
2. Re-encrypt all vault items with new DEK
3. Wrap new DEK with Master Key
4. Archive old key version
5. Update security settings with new key version

Authentication Flow

1. User logs in with email/password
2. Server validates credentials (Argon2 hash verification)
3. Server generates access token (2 min expiry) and refresh token (7 days)
4. Access token sent in response, refresh token in HTTP-only cookie
5. Client includes access token in Authorization header
6. When access token expires, client uses refresh token to get new access token

💻 System Requirements

Minimum Requirements

• Node.js: v18.0.0 or higher
• npm: v8.0.0 or higher
• MongoDB: v5.0 or higher
• RAM: 2GB minimum, 4GB recommended
• Disk Space: 1GB minimum

Supported Platforms

• Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
• macOS (10.15+)
• Windows 10/11 (with WSL2 for Docker)

📦 Installation & Setup

Local Development Setup

1. Clone the Repository

git clone https://github.com/sahanRanasingha/TrustVault.git
cd TrustVault

2. Setup Backend (Server)

cd server

# Install dependencies
npm install

# Generate a 32-byte master key (base64 encoded)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Copy .env.example to .env
cp .env.example .env

# Edit .env and set your values:
# - MASTER_KEY: Use the generated key from above
# - JWT_SECRET: Any secure random string
# - MONGO_URI: Your MongoDB connection string
nano .env

3. Setup Database

Make sure MongoDB is running:

# If using local MongoDB
sudo systemctl start mongod

# Or using Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

Seed the database with initial admin user:

cd server
npm run seed

Default admin credentials:

• Email: admin@trustvault.com
• Password: Admin@123

⚠️ Change the default password immediately after first login!

4. Setup Frontend (Client)

cd ../client

# Install dependencies
npm install

# Copy .env.example if exists, or create .env
echo "VITE_API_URL=http://localhost:5000/api" > .env

5. Start Development Servers

Terminal 1 - Backend:

cd server
npm run dev

Terminal 2 - Frontend:

cd client
npm run dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend API: http://localhost:5000
• MongoDB: localhost:27017

Docker Deployment

Docker deployment is the recommended way to run TrustVault in production.

1. Prerequisites

• Docker (v20.10+)
• Docker Compose (v2.0+)

2. Generate Master Key

# Generate a 32-byte master key
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

3. Create Environment File

Create a .env file in the root directory (where docker-compose.yml is):

# Create .env file
cat > .env << EOF
MASTER_KEY=YOUR_GENERATED_KEY_HERE
EOF

Replace YOUR_GENERATED_KEY_HERE with the key generated in step 2.

4. Build and Start Containers

# Build and start all services
docker-compose up --build -d

# View logs
docker-compose logs -f

# Check service status
docker-compose ps

5. Initialize Database

# Seed the database with initial admin user
docker-compose exec server npm run seed

6. Access the Application

The application will be available at:

• Frontend: http://localhost (port 80)
• Backend API: http://localhost:5000
• MongoDB: localhost:27017

7. Docker Management Commands

# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: Deletes all data)
docker-compose down -v

# Restart a specific service
docker-compose restart server

# View logs for specific service
docker-compose logs -f server

# Execute command in container
docker-compose exec server npm run seed

# Rebuild specific service
docker-compose up -d --build server

⚙️ Configuration

Server Configuration (.env)

# Server Settings
PORT=5000
NODE_ENV=development  # or 'production'

# Database
MONGO_URI=mongodb://localhost:27017/trustvault

# JWT Settings
JWT_SECRET=your_jwt_secret_key_here
JWT_ACCESS_EXPIRY=2m      # Access token expiry (2 minutes)
JWT_REFRESH_EXPIRY=7d     # Refresh token expiry (7 days)

# Encryption
MASTER_KEY=base64_encoded_32_byte_key_here

# CORS
CLIENT_URL=http://localhost:5173  # Frontend URL

Client Configuration (.env)

# API Endpoint
VITE_API_URL=http://localhost:5000/api

Production Configuration

For production deployment, ensure:

1. Strong JWT Secret: Use a cryptographically secure random string
2. Secure Master Key: Keep the master key in a secure vault (e.g., AWS Secrets Manager, Azure Key Vault)
3. HTTPS: Use SSL/TLS certificates (Let's Encrypt recommended)
4. Environment: Set NODE_ENV=production
5. Database: Use MongoDB Atlas or a secured MongoDB cluster
6. CORS: Set CLIENT_URL to your production domain
7. Rate Limiting: Adjust rate limits based on your needs
8. Logging: Configure Winston to write logs to files

📚 API Documentation

Authentication Endpoints

POST /api/auth/login

Login with email and password.

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response:

{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_id",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "user"
  }
}

POST /api/auth/logout

Logout and clear refresh token.

Headers: Authorization: Bearer {accessToken}

GET /api/auth/me

Get current user information.

Headers: Authorization: Bearer {accessToken}

POST /api/auth/refresh

Refresh access token using refresh token cookie.

POST /api/auth/forgot-password

Initiate password recovery.

Request Body:

{
  "email": "user@example.com"
}

POST /api/auth/verify-otp

Verify OTP code.

Request Body:

{
  "email": "user@example.com",
  "otp": "123456"
}

POST /api/auth/reset-password

Reset password after OTP verification.

Request Body:

{
  "email": "user@example.com",
  "otp": "123456",
  "newPassword": "NewSecurePassword123!"
}

Vault Item Endpoints

All vault endpoints require authentication (Authorization: Bearer {token}).

GET /api/vault-items

Get all vault items accessible to the user.

Query Parameters:

• search: Search in title, url, tags (optional)

POST /api/vault-items

Create a new vault item.

Request Body:

{
  "title": "Gmail Account",
  "url": "https://mail.google.com",
  "username": "user@gmail.com",
  "password": "securepassword",
  "notes": "Personal email account",
  "tags": ["email", "personal"],
  "sharedWithUsers": [
    {
      "user": "user_id",
      "accessLevel": "view"
    }
  ],
  "sharedWithGroups": [
    {
      "group": "group_id",
      "accessLevel": "edit"
    }
  ]
}

GET /api/vault-items/:id

Get vault item metadata (without sensitive data).

GET /api/vault-items/:id/reveal

Reveal encrypted data (username, password, notes).

PATCH /api/vault-items/:id

Update a vault item.

DELETE /api/vault-items/:id

Delete a vault item.

User Management Endpoints (Admin Only)

GET /api/users

Get all users.

POST /api/users

Create a new user.

PATCH /api/users/:id

Update user information.

DELETE /api/users/:id

Deactivate a user.

Group Management Endpoints (Admin Only)

GET /api/groups

Get all groups.

POST /api/groups

Create a new group.

PATCH /api/groups/:id

Update group information.

DELETE /api/groups/:id

Delete a group.

POST /api/groups/:id/members

Update group members.

Audit Log Endpoints

GET /api/audit-logs

Get audit logs (admin: all logs, user: own logs).

Query Parameters:

• userId: Filter by user
• action: Filter by action type
• startDate: Filter by start date
• endDate: Filter by end date

Security Endpoints (Admin Only)

GET /api/security/status

Get current security status and key information.

POST /api/security/rotate-key

Rotate the Data Encryption Key (DEK).

👥 User Roles & Permissions

User Role

Permissions:

• View own vault items
• Create vault items
• Edit own vault items
• Delete own vault items
• Access shared vault items (based on permission level)
• View own activity logs

Restrictions:

• Cannot access admin panel
• Cannot manage other users
• Cannot manage groups
• Cannot view all audit logs
• Cannot rotate encryption keys

Admin Role

All User Permissions, plus:

• Access admin panel
• Manage all users (create, edit, deactivate)
• Manage all groups
• View all audit logs
• Access security settings
• Rotate encryption keys
• View system security status

📁 Project Structure

TrustVault/
├── client/                     # Frontend React application
│   ├── public/                 # Static assets
│   ├── src/
│   │   ├── components/         # Reusable React components
│   │   │   ├── ConfirmModal.jsx
│   │   │   ├── GroupModal.jsx
│   │   │   ├── Layout.jsx
│   │   │   ├── ProtectedRoute.jsx
│   │   │   ├── VaultDetailModal.jsx
│   │   │   └── VaultModal.jsx
│   │   ├── context/            # React Context providers
│   │   │   └── AuthContext.jsx
│   │   ├── lib/                # Utility libraries
│   │   │   ├── axios.js        # Axios configuration
│   │   │   └── utils.js        # Helper functions
│   │   ├── pages/              # Page components
│   │   │   ├── Admin/          # Admin pages
│   │   │   │   ├── AuditLogList.jsx
│   │   │   │   ├── GroupList.jsx
│   │   │   │   ├── SecuritySettings.jsx
│   │   │   │   └── UserList.jsx
│   │   │   ├── ForgotPasswordPage.jsx
│   │   │   ├── LoginPage.jsx
│   │   │   ├── MyActivity.jsx
│   │   │   ├── UnauthorizedPage.jsx
│   │   │   └── VaultList.jsx
│   │   ├── App.jsx             # Main App component
│   │   └── main.jsx            # Entry point
│   ├── .dockerignore
│   ├── Dockerfile
│   ├── nginx.conf              # Nginx configuration for Docker
│   ├── package.json
│   ├── tailwind.config.js
│   └── vite.config.js
│
├── server/                     # Backend Node.js application
│   ├── controllers/            # Route controllers
│   │   ├── auditController.js
│   │   ├── authController.js
│   │   ├── groupController.js
│   │   ├── securityController.js
│   │   ├── userController.js
│   │   └── vaultController.js
│   ├── crypto/                 # Encryption utilities
│   │   ├── encryption.js       # AES-256-GCM encryption
│   │   └── keyManager.js       # Key management (DEK/MEK)
│   ├── middleware/             # Express middleware
│   │   ├── auth.js             # JWT authentication
│   │   ├── errorHandler.js     # Global error handler
│   │   └── rbac.js             # Role-based access control
│   ├── models/                 # Mongoose models
│   │   ├── AuditLog.js
│   │   ├── Group.js
│   │   ├── KeyHistory.js
│   │   ├── SecuritySettings.js
│   │   ├── User.js
│   │   └── VaultItem.js
│   ├── routes/                 # API routes
│   │   ├── audit.js
│   │   ├── auth.js
│   │   ├── groups.js
│   │   ├── security.js
│   │   ├── users.js
│   │   └── vault.js
│   ├── services/               # Business logic services
│   ├── utils/                  # Utility functions
│   │   └── logger.js           # Winston logger
│   ├── .dockerignore
│   ├── .env.example            # Environment template
│   ├── app.js                  # Express app configuration
│   ├── db.js                   # MongoDB connection
│   ├── Dockerfile
│   ├── package.json
│   ├── seed.js                 # Database seeding script
│   └── server.js               # Server entry point
│
├── .gitignore
├── docker-compose.yml          # Docker Compose configuration
├── README-DOCKER.md            # Docker-specific instructions
└── README.md                   # This file

🔧 Development Guide

Running Tests

# Backend tests (if configured)
cd server
npm test

# Frontend tests (if configured)
cd client
npm test

Linting

# Backend linting
cd server
npm run lint

# Frontend linting
cd client
npm run lint

Database Seeding

To reset the database with fresh seed data:

cd server
npm run seed

This creates:

• Default admin user (admin@trustvault.com / Admin@123)
• Sample user (user@example.com / User@123)
• Sample groups
• Sample vault items

Adding New Features

1. Backend API Endpoint

   • Create controller in server/controllers/
   • Define route in server/routes/
   • Add validation with Joi
   • Update audit logging if needed

2. Frontend Component

   • Create component in client/src/components/ or client/src/pages/
   • Add routing in App.jsx
   • Use React Query for data fetching
   • Follow existing patterns for consistency

Code Style

• JavaScript: ESLint configuration provided
• React: Functional components with hooks
• CSS: Tailwind CSS utility classes
• Naming: camelCase for variables, PascalCase for components
• File Structure: Group related files together

🚀 Deployment Guide

Production Deployment with Docker

1. Prepare Server

   # Update system
   sudo apt update && sudo apt upgrade -y
   
   # Install Docker and Docker Compose
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo usermod -aG docker $USER

2. Clone and Configure

   git clone https://github.com/sahanRanasingha/TrustVault.git
   cd TrustVault
   
   # Generate and set master key
   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" > master_key.txt
   echo "MASTER_KEY=$(cat master_key.txt)" > .env
   
   # Secure the key file
   chmod 600 .env master_key.txt

3. Configure Production Settings

   Edit docker-compose.yml to use production environment:

   environment:
     - NODE_ENV=production
     - CLIENT_URL=https://your-domain.com

4. Setup SSL/TLS

   Use Let's Encrypt with Nginx:

   sudo apt install certbot python3-certbot-nginx
   sudo certbot --nginx -d your-domain.com

5. Deploy

   docker-compose up -d --build
   docker-compose exec server npm run seed

6. Setup Monitoring

   # View logs
   docker-compose logs -f
   
   # Monitor container health
   docker-compose ps

Production Deployment without Docker

1. Install Dependencies

   # Node.js
   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
   sudo apt install -y nodejs
   
   # MongoDB
   # Follow: https://docs.mongodb.com/manual/installation/
   
   # PM2
   sudo npm install -g pm2

2. Setup Application

   git clone https://github.com/sahanRanasingha/TrustVault.git
   cd TrustVault
   
   # Backend
   cd server
   npm install
   cp .env.example .env
   # Edit .env with production values
   
   # Frontend
   cd ../client
   npm install
   npm run build

3. Start Services

   # Start backend with PM2
   cd server
   pm2 start server.js --name trustvault-api
   pm2 save
   pm2 startup
   
   # Setup Nginx for frontend
   sudo cp client/nginx.conf /etc/nginx/sites-available/trustvault
   sudo ln -s /etc/nginx/sites-available/trustvault /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl restart nginx

Environment-Specific Configuration

Development

• Debug logging enabled
• Hot reload for both frontend and backend
• CORS allows localhost origins
• Short JWT expiry for testing

Production

• Error logging only
• Optimized builds
• CORS restricted to production domain
• Longer JWT expiry
• Rate limiting enforced
• Security headers enabled

🔒 Security Best Practices

For Administrators

1. Master Key Security

   • Never commit master key to version control
   • Store in secure vault (AWS Secrets Manager, Azure Key Vault)
   • Rotate periodically (every 90 days recommended)
   • Use strong, random 32-byte keys

2. Database Security

   • Use strong MongoDB credentials
   • Enable MongoDB authentication
   • Use encrypted connections (TLS/SSL)
   • Regular backups with encryption
   • Restrict network access

3. Application Security

   • Keep dependencies updated
   • Use HTTPS in production
   • Enable HSTS headers
   • Regular security audits
   • Monitor audit logs

4. User Management

   • Enforce strong password policies
   • Regularly review user permissions
   • Deactivate unused accounts
   • Monitor suspicious activity

For Users

1. Strong Passwords

   • Use unique passwords for TrustVault
   • Minimum 12 characters
   • Mix of uppercase, lowercase, numbers, symbols

2. Account Security

   • Don't share credentials
   • Log out when finished
   • Report suspicious activity
   • Regularly review shared items

3. Sharing Practices

   • Only share when necessary
   • Use view-only when possible
   • Regularly audit shared items
   • Remove access when no longer needed

🐛 Troubleshooting

Common Issues

Cannot Connect to Database

Error: MongooseServerSelectionError

Solutions:

• Ensure MongoDB is running: sudo systemctl status mongod
• Check MONGO_URI in .env
• Verify network connectivity
• Check MongoDB logs: /var/log/mongodb/mongod.log

Invalid Master Key Error

Error: MASTER_KEY must be 32 bytes

Solutions:

• Generate new key: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
• Ensure key is base64 encoded
• No spaces or newlines in key

CORS Errors

Error: Access-Control-Allow-Origin

Solutions:

• Check CLIENT_URL in server .env
• Ensure URL includes protocol (http:// or https://)
• No trailing slash in URL

JWT Token Expired

Error: Token expired

Solutions:

• Access token expires in 2 minutes (by design)
• Refresh token should automatically renew it
• If refresh token expired, log in again
• Check JWT_REFRESH_EXPIRY in .env

Docker Build Fails

Solutions:

• Check Docker daemon is running
• Ensure sufficient disk space
• Clear Docker cache: docker system prune -a
• Check Dockerfile syntax

Port Already in Use

Error: EADDRINUSE

Solutions:

# Find process using port
sudo lsof -i :5000

# Kill process
sudo kill -9 <PID>

Getting Help

If you encounter issues:

1. Check the logs:

   # Docker logs
   docker-compose logs -f server
   
   # Server logs
   tail -f server/combined.log
   tail -f server/error.log

2. Enable debug mode:

   NODE_ENV=development

3. Verify configuration:

   # Check environment variables
   cd server
   node -e "require('dotenv').config(); console.log(process.env)"

🤝 Contributing

We welcome contributions! Please follow these guidelines:

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

Code Standards

• Follow existing code style
• Add comments for complex logic
• Update documentation
• Write tests for new features
• Ensure all tests pass

📄 License

This project is licensed under the ISC License.

👨‍💻 Author

Sahan Ranasingha

• GitHub: @sahanRanasingha

🙏 Acknowledgments

• React team for amazing frontend framework
• Express.js for robust backend framework
• MongoDB for flexible database
• All open-source contributors

---

⚠️ Security Notice: This is a password manager. Always follow security best practices, keep your master key secure, and regularly update dependencies. Never expose your master key or JWT secret.

📧 Support: For issues and questions, please open an issue on GitHub.

🌟 Star this repository if you find it useful!