🔐 Vaulty

A Secure Digital Identity Vault & Verification System

Vaulty is a privacy-first identity document management platform that enables citizens to securely store, share, and verify their identity documents using end-to-end encryption and role-based access control.

---

�️ Security Features

1. Authentication

Feature	Implementation
Single-Factor Auth (SFA)	Password-based login with Argon2 hashing (memory-hard, GPU-resistant)
Multi-Factor Auth (MFA)	Email OTP verification required after password authentication
Session Management	JWT tokens with HS256 signing and 30-minute expiry

2. Access Control (RBAC + ACL)

Role	Permissions
Citizen	Upload documents, approve/reject access requests
Verifier	Request access, view documents (only if approved)
Admin	View system-wide audit logs

3. Encryption & Key Exchange

Purpose	Algorithm
File Encryption	AES-256-GCM (authenticated encryption with 12-byte nonce)
Key Exchange	RSA-2048 OAEP (asymmetric encryption for sharing DEKs)
Digital Signatures	RSA-PSS with SHA-256 (non-repudiation)
Integrity Verification	SHA-256 file hashing

Document Flow:

1. Generate random AES-256 key (DEK)
2. Encrypt document with DEK using AES-256-GCM
3. Encrypt DEK with owner's RSA public key
4. Sign document hash with owner's RSA private key
5. On share: re-encrypt DEK with verifier's public key

4. Attack Mitigations

Attack	Defense
Brute Force	Argon2 slow hashing + login failure logging
SQL Injection	SQLAlchemy ORM (parameterized queries)
Packet Sniffing	RSA-encrypted key exchange
Replay Attack	JWT expiry + AES-GCM nonce
Privilege Escalation	Server-side role verification
Data Breach	Files encrypted at rest (AES-256)
Tampering	Digital signatures + hash verification

5. Audit Logging

All security events are logged including:

• Login success/failure (with IP address)
• MFA verification attempts
• Document upload, view, share events
• Access request approvals/rejections
• Integrity check failures

---

�️ Tech Stack

Backend: FastAPI, SQLAlchemy, Argon2, PyOTP, Cryptography, Python-Jose
Frontend: React 19, Vite, Tailwind CSS

---

📄 Detailed Security Analysis

See SECURITY_REPORT.md for complete security documentation.

---

🚀 Getting Started

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/Mac
pip install -r requirements.txt
echo "SECRET_KEY=your-secret-key" > .env
uvicorn main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

Access the app:

• Frontend: http://localhost:5173
• API Docs: http://localhost:8000/docs