Vault - Personal Credential Manager

A production-ready, secure credential vault built with Next.js 14, TypeScript, Supabase, and end-to-end encryption.

Features

• 🔐 End-to-End Encryption: AES-256-GCM encryption at the application level
• 🔑 Master Password Protection: Separate master password required even with OAuth login
• 🛡️ Row Level Security: Database-level access control via Supabase RLS
• 🔍 Advanced Search: Full-text search across titles, URLs, and tags
• 🏷️ Tag System: Organize credentials with custom tags
• 📊 Audit Logging: Track all view/copy operations
• 🔒 Auto-Lock: Automatic vault locking after inactivity
• 📱 Responsive Design: Works on desktop, tablet, and mobile
• 🌙 Dark Mode: System preference + manual toggle
• ⚡ Server Components: Optimized performance with Next.js 14

Tech Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Database & Auth: Supabase (PostgreSQL + Auth)
• Styling: Tailwind CSS + shadcn/ui
• Encryption: AES-256-GCM (Node.js crypto)

Prerequisites

• Node.js 18+ and npm/yarn/pnpm
• Supabase account and project
• OpenSSL (for generating encryption keys)

Setup Instructions

1. Clone and Install

git clone <repository-url>
cd PasswordManager
npm install

2. Set Up Supabase

1. Create a new Supabase project at supabase.com
2. Go to SQL Editor and run the schema from sql/vault_schema.sql
3. Enable Google OAuth in Authentication > Providers (optional)
4. Get your project URL and API keys from Settings > API

3. Generate Encryption Key

# Generate a 32-byte hex encryption key
openssl rand -hex 32

IMPORTANT: Save this key securely. If lost, all encrypted data cannot be decrypted.

4. Configure Environment Variables

Create a .env.local file in the root directory:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key
VAULT_ENCRYPTION_KEY=your_64_character_hex_key_from_step_3
NODE_ENV=development

Security Notes:

• Never commit .env.local to version control
• The VAULT_ENCRYPTION_KEY is critical - store it securely
• In production, use environment variables from your hosting provider

5. Install shadcn/ui Components

The app uses shadcn/ui components. Install them via CLI:

npx shadcn-ui@latest add button
npx shadcn-ui@latest add input
npx shadcn-ui@latest add card
npx shadcn-ui@latest add dialog
npx shadcn-ui@latest add table
npx shadcn-ui@latest add badge

6. Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

Database Schema

All database tables are prefixed with vault_:

• vault_users - Extended user profiles with master password hashes
• vault_credentials - Encrypted credentials
• vault_tags - Tag definitions
• vault_credential_tags - Many-to-many credential-tag relationships
• vault_audit_logs - Audit trail for sensitive operations

Running the Schema

1. Open Supabase Dashboard
2. Go to SQL Editor
3. Copy and paste the contents of sql/vault_schema.sql
4. Run the script

The schema includes:

• UUID primary keys
• Foreign key constraints
• Indexes for performance
• Row Level Security (RLS) policies
• Triggers for updated_at timestamps

Security Architecture

Encryption

• Algorithm: AES-256-GCM (authenticated encryption)
• Key Management: Environment variable (32-byte hex)
• IV Generation: Cryptographically secure random per encryption
• Storage Format: Base64-encoded (IV + AuthTag + Ciphertext)

Critical: The encryption key must be:

• Stored securely (never in code)
• Rotated periodically (see Key Rotation below)
• Backed up securely (losing it = losing all data)

Master Password

• Hashing: bcrypt with 12 rounds
• Storage: Hashed in vault_users table
• Verification: Required even for OAuth users
• Session: Stored in HTTP-only cookie (server-side)

Row Level Security (RLS)

All tables have RLS policies ensuring users can only access their own data:

-- Example policy
CREATE POLICY "Users can view own credentials"
  ON vault_credentials FOR SELECT
  USING (auth.uid() = user_id);

Rate Limiting

• Login attempts: 5 per 15 minutes per IP
• Master password: 10 per 15 minutes per user
• Decryption: 10 per minute per user
• Credential creation: 50 per hour per user

Auto-Lock

• Default timeout: 15 minutes of inactivity
• Configurable via VAULT_AUTO_LOCK_TIMEOUT_MS environment variable
• Client-side activity tracking
• Server-side session invalidation

Key Rotation

If you need to rotate the encryption key:

1. Backup all data - Export credentials (they'll need re-encryption)
2. Generate new key: openssl rand -hex 32
3. Update environment variable with new key
4. Re-encrypt all credentials:
   • Fetch all credentials
   • Decrypt with old key
   • Encrypt with new key
   • Update in database

Warning: This is a complex operation. Test in development first.

Master Password Reset

If a user forgets their master password:

1. Data cannot be recovered - This is by design for security
2. User must reset:
   • Delete their vault_users record
   • Delete all their credentials (or they'll be orphaned)
   • User sets new master password on next login

Alternative: Implement a recovery flow with backup encryption keys (advanced, not included).

Deployment

Vercel (Recommended)

1. Push code to GitHub
2. Import project in Vercel
3. Add environment variables in Vercel dashboard
4. Deploy

Other Platforms

The app is a standard Next.js application and can be deployed to:

• Vercel
• Netlify
• AWS Amplify
• Railway
• Any Node.js hosting

Environment Variables: Ensure all variables from .env.local are set in your hosting platform.

Production Checklist

• Encryption key set and secure
• Supabase RLS policies enabled
• HTTPS enabled (required for secure cookies)
• Environment variables configured
• Database backups configured
• Rate limiting tested
• Auto-lock timeout configured
• Console logs disabled (handled by next.config.js)

Development

Project Structure

/app
  /(auth)          # Authentication pages
  /(vault)         # Vault dashboard pages
  /api             # API routes
/lib
  encryption.ts    # AES-256-GCM encryption
  supabase.ts      # Supabase clients
  auth.ts          # Master password management
  security.ts      # Security utilities
  types.ts         # TypeScript types
/components
  /vault           # Vault-specific components
  /ui              # shadcn/ui components
/sql
  vault_schema.sql # Database schema

Key Files

• middleware.ts - Route protection and auth checks
• app/(vault)/actions.ts - Server actions for CRUD operations
• lib/encryption.ts - Encryption/decryption logic
• lib/auth.ts - Master password verification

Security Best Practices

1. Never log secrets - Console logs are disabled in production
2. Use HTTPS - Required for secure cookies
3. Rotate keys - Periodically rotate encryption keys
4. Monitor audit logs - Review vault_audit_logs regularly
5. Backup database - Regular backups of Supabase database
6. Keep dependencies updated - Regular security updates
7. Use strong master passwords - Minimum 12 characters enforced

Troubleshooting

"VAULT_ENCRYPTION_KEY not set" warning

This is expected in development if you haven't set the key. Set it in .env.local or use the dev fallback (insecure, development only).

"Vault is locked" error

The vault auto-locks after inactivity. Enter your master password to unlock.

OAuth not working

1. Check Supabase dashboard > Authentication > Providers
2. Ensure redirect URL is configured correctly
3. Check browser console for errors

Database connection errors

1. Verify Supabase URL and keys in .env.local
2. Check Supabase project status
3. Ensure RLS policies are set up correctly

License

This project is private and proprietary.

Support

For issues and questions, please contact the development team.

---

Security Notice: This application handles sensitive credentials. Use at your own risk. Always follow security best practices and keep dependencies updated.