NyxVault

A secure, self-hosted password vault with encrypted storage. Built with React, FastAPI, and PostgreSQL.

Features

• 🔐 Secure password storage with AES-256-GCM encryption
• 🔑 Per-user encryption keys derived from master key using HKDF
• 🛡️ Argon2id password hashing for user authentication
• 🍪 HttpOnly cookies for session management
• 🎨 Modern, futuristic UI with black/purple theme
• 📋 One-click copy to clipboard
• 🔍 Search functionality to quickly find accounts
• 🐳 Docker-first deployment

Security Model

Authentication

• User passwords are hashed using Argon2id with secure parameters
• Sessions are managed via JWT tokens stored in HttpOnly cookies
• SameSite=Lax cookie policy for CSRF protection

Encryption at Rest

• All vault passwords are encrypted using AES-256-GCM (authenticated encryption)
• A master key is provided via environment variable
• Per-user keys are derived from the master key using HKDF with user ID as context
• This limits the blast radius: even if a user's data is compromised, other users' data remains secure
• Each encryption uses a random 12-byte nonce stored alongside the ciphertext

Master Key (env) → HKDF(user_id) → User Key → AES-GCM(password, nonce) → Ciphertext

What's Protected

Data	Protection
User passwords	Argon2id hash (never stored in plaintext)
Vault passwords	AES-256-GCM encrypted (never stored in plaintext)
Session tokens	HttpOnly cookies (not accessible to JavaScript)

Quick Start

Prerequisites

• Docker and Docker Compose
• Python 3.11+ (for key generation)

1. Clone and Configure

cd NyxVault

# Copy environment template
cp .env.example .env

2. Generate Security Keys

# Generate master encryption key (32 bytes, base64)
python -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"

# Generate JWT secret key
python -c "import secrets; print(secrets.token_urlsafe(32))"

Edit .env and fill in:

• VAULT_MASTER_KEY: The base64 key from first command
• JWT_SECRET_KEY: The key from second command
• POSTGRES_PASSWORD: A secure database password
• INITIAL_PASSWORD: Initial admin password

3. Start the Application

docker compose up --build

4. Access the App

• Frontend: http://localhost:3000
• API Docs: http://localhost:8000/docs
• Login: Use the credentials from INITIAL_USERNAME and INITIAL_PASSWORD

Development

Running Backend Tests

cd backend
pip install -r requirements.txt
pytest -v

Project Structure

NyxVault/
├── backend/
│   ├── app/
│   │   ├── auth/          # Authentication module
│   │   ├── crypto/        # Encryption utilities
│   │   ├── vault/         # Vault CRUD operations
│   │   ├── main.py        # FastAPI application
│   │   ├── config.py      # Settings from environment
│   │   ├── db.py          # Database configuration
│   │   ├── models.py      # SQLAlchemy models
│   │   └── schemas.py     # Pydantic schemas
│   ├── alembic/           # Database migrations
│   ├── tests/             # Pytest tests
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── api/           # API client
│   │   ├── components/    # React components
│   │   ├── context/       # React contexts
│   │   ├── pages/         # Page components
│   │   └── types/         # TypeScript types
│   ├── Dockerfile         # Dev Dockerfile
│   └── Dockerfile.prod    # Production Dockerfile
├── docker-compose.yml     # Development compose
├── docker-compose.prod.yml # Production compose
└── .env.example

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/auth/login	Login with username/password
POST	/api/auth/logout	Clear session
GET	/api/auth/me	Get current user

Vault

Method	Endpoint	Description
GET	/api/vault/items	List all items (with optional ?query=)
POST	/api/vault/items	Create new item
GET	/api/vault/items/{id}	Get item details (password masked)
PUT	/api/vault/items/{id}	Update item
DELETE	/api/vault/items/{id}	Delete item
POST	/api/vault/items/{id}/reveal	Get decrypted password

Database Migrations

Migrations run automatically on backend startup. To run manually:

# Inside backend container
docker compose exec backend alembic upgrade head

# Create new migration
docker compose exec backend alembic revision --autogenerate -m "description"

Production Deployment

Using Production Docker Compose

# Build and run production containers
docker compose -f docker-compose.prod.yml up --build -d

Environment Variables for Production

# Required for production
VAULT_MASTER_KEY=<strong-32-byte-base64-key>
JWT_SECRET_KEY=<strong-secret>
POSTGRES_PASSWORD=<strong-database-password>
INITIAL_PASSWORD=<strong-admin-password>
CORS_ORIGINS=https://your-domain.com
DEBUG=false

Security Checklist

• Use strong, unique values for all secrets
• Enable HTTPS (use a reverse proxy like Traefik or Caddy)
• Set CORS_ORIGINS to your actual domain
• Change the initial admin password after first login
• Store .env securely (never commit to version control)
• Regularly backup the PostgreSQL volume

Tech Stack

Backend

• FastAPI - Modern Python web framework
• SQLAlchemy 2.0 - ORM with async support
• Alembic - Database migrations
• PostgreSQL - Database
• Argon2 - Password hashing
• Cryptography - AES-GCM encryption

Frontend

• React 18 - UI library
• TypeScript - Type safety
• Vite - Build tool
• TailwindCSS - Styling
• React Router - Client-side routing

Infrastructure

• Docker - Containerization
• Docker Compose - Multi-container orchestration
• Nginx - Production static file serving

License

MIT License - See LICENSE for details.