How aashmitmckenzie/secure-vault works
Project Type and Purpose
• This is a full-stack web application (“Secret Vault 2.0”) whose purpose is to securely store, retrieve, and audit user credentials.
• It uses a FastAPI backend (Python) exposing a RESTful API, a static HTML/CSS/JS frontend, an embedded SQLite database, and optional integration with HashiCorp Vault, Google OAuth, and an email/SMS service for notifications.
File Structure
Top-level directories and files reveal:
• main.py (entry point, mounts routes & static‐file serving)
• auth.py, crud.py, notify.py, encryption.py, vault_client.py, database.py, models.py (core modules implementing API controllers, business logic, data access, encryption & KMS integration)
• frontend/ (static assets: HTML pages, CSS, JS served by FastAPI at /app/)
• scripts (add_demo_credentials.py, setup_admin.py, create_dummy_user.py, backup.py, check_db.py, check_audit.py, quick_test.py) for CLI tasks, seeding, health checks
• config.py, security.py (configuration loader, security utilities)
• email_service.py, verify_email.py, notifications.py (outbound email/SMS)
• logger.py, server.log, secret_vault.log (audit & system logging)
• requirements.txt, encryption_key.key or environment‐backed KMS
README for Additional Insights
• Features: AES-256 (Fernet) encryption of stored passwords, bcrypt for user‐passwords, multi-authentication (email/password + Google OAuth), audit logging, expiration tracking, search/filter.
• SQLite database with two tables: credentials & audit_logs.
• Optional HashiCorp Vault for storing the master Fernet key.
• External email provider & Google OAuth as third-party dependencies.
• Docker/Docker-Compose support for containerized deploy.
Main Components and Their Interactions
a. Frontend (User’s Browser)
• HTML/CSS/JS pages under frontend/ accessed at /app/
• Communicates with backend over REST (AJAX/fetch)
b. Backend API (FastAPI)
• main.py initializes FastAPI, mounts routers from auth.py, crud.py, audit modules, system health, and static file handlers.
• Controllers handle HTTP requests, invoke Services & Data modules.
c. Services / Business Logic
• auth.py: user authentication (bcrypt, JWT/HTTPBasic), Google OAuth handshake.
• crud.py: credential CRUD operations, integrates encryption.py.
• encryption.py: Fernet key management, encrypt/decrypt payloads via local key or vault_client.py.
• vault_client.py: optional HashiCorp Vault integration for KMS.
• email_service.py & verify_email.py: send email verifications and notifications.
• notifications.py: in-app or outbound notifications.
• check_db.py / check_audit.py: internal health checks.
d. Data Layer
• database.py: SQLAlchemy session & connection to SQLite file (secret_vault.db)
• models.py: ORM & Pydantic schemas for credentials & audit_logs tables
e. External Services
• HashiCorp Vault (KV store)
• Google OAuth provider
• SMTP/Third-party email API
f. Logging & Auditing
• logger.py writes to secret_vault.log & server.log
• audit tables store user actions
g. CLI & Utilities
• Scripts (add_demo_credentials.py, add_test_users.py, create_dummy_user.py, setup_admin.py) for seeding/test data
• backup.py dumps DB, quick_test.py for smoke testing
Relationships & Data Flows (
• Browser → FastAPI (REST calls: /auth, /credentials, /audit, /system/*)
• FastAPI → CRUD layer → Database (SQLite)
• CRUD layer ↔ Encryption service (encrypt/decrypt)
• Encryption service ↔ Vault (optional KMS)
• FastAPI → Google OAuth endpoint (external)
• FastAPI → Email service (SMTP/API)
• FastAPI → logger/audit subsystem → log files & audit table
• CLI scripts → directly invoke API endpoints or Data layer for setup/maintenance
Architectural Patterns & Principles
• Layered architecture: Presentation (frontend), API/Controller, Service/Domain, Data/Repository
• Modular feature separation: auth, credentials, audit, system
• Single origin for static assets + API, simplifying CORS
• Optional KMS abstraction allowing local key fallback