How adityadugad/securevault works
1. Top-level shape
- SecureVault is a two-tier system: a FastAPI backend in app/ and a static browser frontend in static/.
- The frontend is not a SPA framework; it is a set of HTML pages plus JS modules for auth, notes, passwords, todos, OTP, and PQC views.
2. Backend composition and startup
- app/main.py is the composition root: it creates the FastAPI app, registers middleware, wires routers, and triggers startup initialization.
- Startup depends on three schema/bootstrap modules: app/models.py for core user tables, app/vault/vault_models.py for vault tables and migrations, and the security tables described in the README.
- render.yaml indicates deployment on a managed platform, while securevault.db shows the app uses a local SQLite file in development or single-instance deployment.
3. Request routing boundaries
- The backend is divided into feature routers:
- app/auth/auth_routes.py for signup, login, OTP, reset-password
- app/vault/vault_routes.py for notes, passwords, todos, and admin-encrypted-db access
- README-described security routes for sessions/dashboard/risk views
- app/pqc/metrics.py for live PQC benchmarking
- Shared dependencies live in utility modules rather than a service layer, so most business logic is orchestrated directly from route handlers.
4. Authentication flow
- Authentication is multi-step: password → OTP → JWT.
- app/auth/auth_utils.py handles Argon2 hashing and JWT creation/validation.
- app/auth/otp_utils.py manages one-time codes stored in the database, and app/auth/email_utils.py sends those codes through an email provider.
- app/auth/jwt_dependency.py provides an alternate bearer-token dependency; the README notes both JWT validators target the same token shape.
5. Session and security controls
- The system is designed to be stricter than a standard stateless JWT app: the README describes a parallel session/history layer, account lockouts, and security-event logging.
- Rate limiting is central to the security boundary, with sensitive endpoints capped by IP in the SlowAPI-based limiter described in the README.
- Security events such as failed login, wrong OTP, decrypt abuse, and multi-IP access feed a rolling risk score and lockout logic.
6. Encrypted vault subsystem
- app/vault/vault_routes.py and app/vault/vault_utils.py implement the core encrypted storage model for notes, passwords, and tasks.
- The database never stores plaintext secrets; records store ciphertext plus encryption metadata such as nonce, optional KEM ciphertext, and encryption type.
- app/vault/vault_models.py creates and migrates the vault tables so older databases can be upgraded in place.
7. Hybrid cryptography path
- The primary encryption design is ML-KEM / Kyber + AES-256-GCM.
- vault_utils.py obtains or reconstructs an AES key through an external Kyber service, then performs symmetric encryption with AES-GCM.
- If the Kyber service is unavailable, the code falls back to a locally derived backup AES key, so the storage layer remains usable even when the post-quantum service is down.
8. PQC service boundary
- The README shows the Kyber component is not embedded in-process; it is reached over HTTP as an external microservice.
- app/pqc/kyber.py appears to be an alternate or legacy PQC path, while app/pqc/metrics.py provides live benchmark measurements for key generation and encrypt/decrypt timings.
- This creates a clean boundary between the main app and the PQC crypto backend.
9. Persistence model
- SQLite is the only database technology in the repo, accessed via a raw connection object in app/database.py rather than an ORM.
- Data is organized into user identity, OTP, vault content, session/history, and security-log tables.
- The ownership key across most tables is the user email, which acts as the primary application-level partition key.
10. Password intelligence
- app/ml/password_strength_model.py wraps a persisted scikit-learn SVM model stored in app/ml/password_strength_svm.pkl.
- This subsystem is used as a password quality classifier, separate from the normal auth flow, to score user-chosen passwords as weak/medium/strong.
- It is a local inference component; there is no training pipeline in the repo tree.
11. Frontend-to-backend data flow
- The static pages map directly to backend capabilities: signup/login/OTP/reset for auth, dashboard/security views, and dedicated notes/passwords/todos pages for the vault.
- JavaScript files under static/js/ call the API endpoints and drive the user experience around authentication, encrypted CRUD, and password checks.
- Media assets in static/img/ are presentation-only and do not affect backend architecture.
12. External services and operational dependencies
- The system depends on three notable external services:
- an email delivery API for OTPs and security alerts
- the Kyber/ML-KEM microservice for hybrid key establishment
- the hosting/runtime environment that serves the FastAPI app and SQLite file
- Uvicorn is the expected ASGI runtime, and the app likely serves static content alongside API routes in the same deployment unit.
13. Important architectural takeaway
- The dominant boundary in SecureVault is not “frontend vs backend”; it is plaintext vs protected data.
- Every meaningful data path either ends in encrypted storage or in a security-control subsystem, and the design intentionally avoids persisting secrets in clear text.
Main entry points: main.py App main · auth_routes.py Auth routes · database.py SQLite layer · vault_routes.py Vault routes
Components 22
Backend
FastAPI application and internal feature subsystems.
- App main · Creates the FastAPI app, registers middleware and routers, and runs startup initialization.
app/main.py - User models · Core user and identity tables initialized at startup.
app/models.py - Vault models · Encrypted vault tables and in-place migration logic.
app/vault/vault_models.py - Auth routes · Signup, login, OTP, and password reset endpoints.
app/auth/auth_routes.py - Auth utils · Argon2 hashing plus JWT creation and validation.
app/auth/auth_utils.py - OTP utils · Generates and verifies one-time codes persisted in SQLite.
app/auth/otp_utils.py - Email adapter · Sends OTP and security emails through an external provider.
app/auth/email_utils.py - JWT dependency · Alternate bearer-token dependency for protected routes.
app/auth/jwt_dependency.py - Security layer · Session history, lockouts, rate limits, and security-event logging described in the README.
- Vault routes · Notes, passwords, todos, and admin-encrypted database access endpoints.
app/vault/vault_routes.py - Vault crypto · Encrypts and decrypts vault data with metadata such as nonce and KEM ciphertext.
app/vault/vault_utils.py - PQC metrics · Live benchmark measurements for PQC key generation and encrypt/decrypt timings.
app/pqc/metrics.py - Kyber path · Alternate or legacy post-quantum crypto path in the application tree.
app/pqc/kyber.py - Password model · Loads a persisted SVM classifier to score password strength.
app/ml/password_strength_model.py
Frontend
Static HTML and JavaScript client pages.
- Static pages · HTML pages for auth, dashboard, vault views, PQC, and password reset.
static/index.html - Client scripts · JavaScript modules that call API endpoints and drive the browser experience.
static/js/auth.js
Data
SQLite persistence, local files, and deployment manifest.
- SQLite layer · Raw SQLite connection layer shared across the app.
app/database.py - Local DB file · Bundled SQLite database used in development or single-instance deployment.
securevault.db - Deploy config · Managed-platform deployment configuration.
render.yaml
External
Outside services and boundaries the app integrates with.
- Email service · External provider used for OTP and security notifications.
- PQC service · External Kyber or ML-KEM service reached over HTTP.
- Hosting runtime · ASGI hosting environment serving the FastAPI app and static assets.
Connections 25
- App main → User models: bootstraps · Initializes core user tables during app startup.
- App main → Vault models: bootstraps · Initializes encrypted vault tables and migrations.
- App main → Auth routes: registers · Mounts authentication endpoints into the FastAPI app.
- App main → Vault routes: registers · Mounts vault endpoints into the FastAPI app.
- App main → PQC metrics: registers · Exposes PQC benchmarking endpoints.
- App main → Security layer: enforces · Applies middleware and request-level security controls.
- Auth routes → Auth utils: uses · Hashes passwords and issues or validates JWTs.
- Auth routes → OTP utils: uses · Creates and checks one-time passwords.
- Auth routes → Email adapter: uses · Delivers OTP and alert emails.
- Auth routes → JWT dependency: protects · Shares bearer-token validation for guarded auth flows.
- OTP utils → SQLite layer: persists · Stores OTP records in SQLite.
- Vault routes → Vault crypto: uses · Performs encrypted CRUD for vault content.
- Vault routes → Security layer: monitors · Feeds decrypt abuse, lockouts, and access-risk events.
- Vault crypto → SQLite layer: persists · Stores ciphertext and encryption metadata in SQLite.
- Vault crypto → Kyber path: requests key · Obtains or reconstructs the AES key via the PQC boundary.
- Kyber path → PQC service: http service · Reached as an external Kyber or ML-KEM microservice.
- Security layer → SQLite layer: records · Writes session, history, and security logs.
- Security layer → Email adapter: alerts · Can trigger security notifications through email.
- Email adapter → Email service: email api · Uses an external delivery provider.
- Password model → SQLite layer: independent of · Runs locally and does not rely on the main auth flow.
- Static pages → Client scripts: loads · Pages are driven by page-specific JavaScript modules.
- Client scripts → App main: calls api · Browser modules invoke the FastAPI backend.
- Deploy config → Hosting runtime: deploys · Describes the managed deployment entrypoint.
- Local DB file → SQLite layer: backing file · Local SQLite file used by the database layer.
- App main → Hosting runtime: runs on · FastAPI application is served by the deployment runtime.