291 lines
13 KiB
Markdown
291 lines
13 KiB
Markdown
# PassKeeper 🔐
|
|
|
|
A self-hosted, zero-knowledge password manager — web app and Chrome/Firefox extension. Your master password and decrypted vault data **never leave your browser**.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
### Web App
|
|
- **Zero-knowledge encryption** — AES-256-GCM client-side; 600k-iteration PBKDF2 vault key
|
|
- **7 item types** — Passwords, Secure Notes, Cards, Bank Accounts, Addresses, Identities, Passkeys
|
|
- **Vault item tags** — comma-separated tags stored inside the encrypted blob; sidebar tag filter; live badge preview in modal; no schema change required
|
|
- **Collapsible folder groups** — click any folder header in the vault list to collapse/expand; item count badge and chevron indicator; state persists across re-renders
|
|
- **TOTP / 2FA** — per-site TOTP codes stored in `plain.totp_uri`; live 6-digit display with countdown
|
|
- **Folder organisation** — create, rename, delete; filter vault by folder
|
|
- **Item sharing** — ECDH P-256 zero-knowledge re-encryption; item name encrypted with shared key — server never sees it
|
|
- **Emergency access** — configurable wait-timer access grant for a trusted contact
|
|
- **Security dashboard** — weak / reused / old / **no 2FA saved** / **HaveIBeenPwned breach check** (k-anonymity — passwords never transmitted)
|
|
- **Import / Export** — encrypted JSON backup; CSV export (plaintext, handle carefully); import from Chrome, Bitwarden, and 1Password CSV formats (RFC 4180 compliant parser)
|
|
- **Account MFA** — TOTP-based login (Google Authenticator / Authy); single-use code enforcement prevents replay attacks
|
|
- **Passkeys / WebAuthn** — register device biometrics or hardware keys as a sign-in method; master password still required to unlock vault (zero-knowledge preserved); manage passkeys in Account Settings
|
|
- **Master password change** — atomic zero-knowledge re-encryption of entire vault including item names
|
|
- **Account recovery** — 128-bit recovery code; server never stores it; challenge-response proof prevents forgery
|
|
- **Audit log** — server-side trail of all create/edit/delete/import/export actions; no plaintext names ever logged
|
|
- **Encrypted item names** — `enc_name`/`iv_name`; server holds only the item type as a label
|
|
- **Browser history** — back/forward button works for all views (`history.pushState`)
|
|
- **Web-app auto-lock** — configurable inactivity timeout (5/10/15/30/60 min or Never); stored per browser in `localStorage`
|
|
- **Clipboard auto-clear** — sensitive copies cleared after 30 seconds
|
|
- **Responsive layout** — phone, tablet, laptop, large desktop; collapsible sidebar
|
|
|
|
### Browser Extension (Chrome / Edge — Manifest V3 + Firefox — Manifest V2)
|
|
- **Autofill** — detects login forms; injects icon into username and password fields only (scored heuristic, not all inputs)
|
|
- **Smart domain matching** — matches by domain name; handles bare domains (`github.com`) and subdomains
|
|
- **Suggestion dropdown** — filters as you type; keyboard navigation (↑↓ Enter); one-click fill
|
|
- **Collapsible folder groups** — "All items" tab groups by folder with collapse/expand toggle matching the web app UX
|
|
- **Favorites tab** — items tagged `favorite` in the web app appear in a dedicated tab; marked with ★
|
|
- **Tag display** — purple badge pills on item rows; tags sourced from `plain.tags[]`
|
|
- **Three-dot flyout menu** — contextual actions: Open URL / Copy username / Copy password; built dynamically from what the item has
|
|
- **Dedicated copy-username button** — person icon alongside copy-password in every item row
|
|
- **Auto-save banner** — save/update credentials on form submit; duplicate detection; "Never for this site" blocklist
|
|
- **Pending-save badge** — red `!` on toolbar icon when a credential is waiting to be saved
|
|
- **Inline password generator** — fully CSPRNG (`crypto.getRandomValues` throughout, `Math.random` never called)
|
|
- **TOTP live display** — 6-digit code + countdown per item
|
|
- **SSO bridge** — log in once on the web app; extension picks up the session
|
|
- **Idle lock** — configurable auto-lock (1/5/10/30 min or Never)
|
|
- **Clipboard auto-clear** — passwords/usernames cleared from clipboard after 30 seconds
|
|
- **Keyboard shortcut** — `Ctrl+Shift+L` / `Cmd+Shift+L` to open popup (customisable at `chrome://extensions/shortcuts`)
|
|
- **Firefox compatible** — separate MV2 manifest + background script; same popup/content/bridge code
|
|
|
|
---
|
|
|
|
## Security Architecture
|
|
|
|
```
|
|
Master Password
|
|
│
|
|
├─ PBKDF2(email, 100k iter) ──► authHash ──► POST /api/auth/login
|
|
│ Argon2id(authHash) stored in DB
|
|
│ (transparently rehashed if params upgraded)
|
|
│
|
|
└─ PBKDF2(enc_key_salt, 600k iter) ──► vaultKey (browser memory only)
|
|
│
|
|
AES-256-GCM encrypt
|
|
│
|
|
enc_data + iv (item payload + tags)
|
|
enc_name + iv_name (item name)
|
|
│
|
|
POST /api/vault ──► Server stores ciphertext only
|
|
|
|
Sharing: ECDH(Alice_priv, Bob_pub) ──► sharedKey ──► AES-256-GCM(enc_data + enc_name)
|
|
Server stores only ciphertext — cannot read item content or item name
|
|
```
|
|
|
|
### Security hardening highlights
|
|
- **TOTP replay prevention** — each 6-digit code is single-use (120s window); recorded in `totp_used_codes` table
|
|
- **Recovery proof** — `enc_key_salt` not returned by server during recovery; client must decrypt the recovery blob to prove code possession
|
|
- **folder_id ownership** — all create/update/import operations validate folder belongs to current user
|
|
- **Audit log privacy** — item names and shared item names never appear in server-side audit logs
|
|
- **Extension fingerprinting** — `web_accessible_resources: []` blocks external pages from probing extension files
|
|
- **Passkey / WebAuthn** — FIDO2 assertion proves identity to the server without a password; vault key still derived from master password client-side; `sign_count` updated on each use for clone detection
|
|
|
|
A database breach exposes only encrypted ciphertext. The server cannot read vault names, passwords, tags, or shared item names.
|
|
|
|
---
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|---|---|
|
|
| Backend | Python 3.12, Flask 3.x |
|
|
| Database | MySQL 8.x |
|
|
| Frontend | Vanilla JS, Web Crypto API, Jinja2 |
|
|
| Auth | Argon2id + PBKDF2 + JWT (HS256) + WebAuthn (FIDO2) |
|
|
| Encryption | AES-256-GCM (client-side) |
|
|
| Extension | Chrome MV3 / Firefox MV2 |
|
|
| Web server | Nginx + Gunicorn + systemd |
|
|
| Rate limiting | Flask-Limiter + Redis |
|
|
| TLS | Let's Encrypt / Certbot |
|
|
|
|
---
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
- Python 3.12+
|
|
- MySQL 8.x
|
|
- No Node.js or build step required
|
|
|
|
### Development (Windows)
|
|
|
|
```bash
|
|
git clone https://github.com/yourname/passkeeper
|
|
cd passkeeper
|
|
python -m venv .venv
|
|
.venv\Scripts\activate
|
|
pip install -r requirements.txt
|
|
copy .env.example .env
|
|
```
|
|
|
|
Edit `.env`:
|
|
```env
|
|
FLASK_ENV=development
|
|
SECRET_KEY=<64-char hex>
|
|
JWT_SECRET_KEY=<64-char hex>
|
|
MYSQL_HOST=localhost
|
|
MYSQL_USER=passkeeper
|
|
MYSQL_PASSWORD=yourpassword
|
|
MYSQL_DB=passkeeper
|
|
TOTP_ENCRYPTION_KEY=<64-char hex>
|
|
```
|
|
|
|
```bash
|
|
mysql -u root -p -e "CREATE DATABASE passkeeper CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
|
|
mysql -u root -p -e "CREATE USER 'passkeeper'@'localhost' IDENTIFIED BY 'yourpassword'; GRANT ALL ON passkeeper.* TO 'passkeeper'@'localhost'; FLUSH PRIVILEGES;"
|
|
python reset_db.py
|
|
python run.py
|
|
```
|
|
|
|
Generate secrets:
|
|
```bash
|
|
python -c "import secrets; print(secrets.token_hex(32))"
|
|
```
|
|
|
|
### Load the Extension (Chrome)
|
|
1. `chrome://extensions/` → Enable **Developer mode**
|
|
2. **Load unpacked** → select `extension/` folder
|
|
3. Reload after any JS/CSS changes
|
|
|
|
### Load the Extension (Firefox)
|
|
1. `about:debugging` → **This Firefox** → **Load Temporary Add-on**
|
|
2. Select `extension/manifest.firefox.json`
|
|
|
|
---
|
|
|
|
## Production Deployment
|
|
|
|
### 1. Server dependencies
|
|
```bash
|
|
sudo apt update && sudo apt install python3.12 python3.12-venv mysql-server nginx \
|
|
certbot python3-certbot-nginx redis-server
|
|
```
|
|
|
|
### 2. Application setup
|
|
```bash
|
|
cd /var/www/passkeeper
|
|
python3.12 -m venv .venv && source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cp .env.example .env # set production values
|
|
flask db upgrade # run all migrations
|
|
```
|
|
|
|
### 3. systemd service
|
|
```bash
|
|
sudo cp scripts/passkeeper.service /etc/systemd/system/
|
|
sudo systemctl daemon-reload && sudo systemctl enable --now passkeeper
|
|
```
|
|
|
|
### 4. Nginx
|
|
```bash
|
|
sudo cp scripts/passkeeper-nginx.conf /etc/nginx/sites-available/passkeeper
|
|
sudo ln -s /etc/nginx/sites-available/passkeeper /etc/nginx/sites-enabled/
|
|
sudo certbot --nginx -d yourdomain.com
|
|
sudo nginx -t && sudo systemctl reload nginx
|
|
```
|
|
|
|
### 5. Future schema migrations
|
|
```bash
|
|
flask db upgrade && sudo systemctl reload passkeeper
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `SECRET_KEY` | Flask session secret (64-char hex) |
|
|
| `JWT_SECRET_KEY` | JWT signing secret (64-char hex) |
|
|
| `MYSQL_HOST` / `MYSQL_USER` / `MYSQL_PASSWORD` / `MYSQL_DB` | Database |
|
|
| `TOTP_ENCRYPTION_KEY` | Server-side AES key for TOTP secrets (64-char hex) |
|
|
| `RATELIMIT_STORAGE_URI` | Redis URI — required in production (`redis://127.0.0.1:6379/0`) |
|
|
| `CORS_ORIGINS` | Allowed origins (`*` in dev, domain in prod) |
|
|
| `WEBAUTHN_RP_ID` | Passkey relying party ID — effective domain, no scheme (`pwkeeper.ngodanguyen.tech`) |
|
|
| `WEBAUTHN_RP_NAME` | Passkey relying party display name (`PassKeeper`) |
|
|
| `WEBAUTHN_ORIGINS` | Comma-separated allowed origins for WebAuthn (`https://pwkeeper.ngodanguyen.tech`) |
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
passkeeper/
|
|
├── app/ # Flask application
|
|
│ ├── models/ # SQLAlchemy models
|
|
│ ├── routes/ # API blueprints (auth, vault, folders, sharing, emergency)
|
|
│ ├── services/ # Auth (Argon2id, JWT, TOTP encryption, TOTP replay helpers)
|
|
│ ├── static/js/ # Client-side crypto + vault UI
|
|
│ └── templates/ # Jinja2 templates
|
|
├── extension/ # Browser extension
|
|
│ ├── popup/ # Popup UI
|
|
│ ├── content/ # Content script (autofill, field detection)
|
|
│ ├── shared/ # Shared crypto + Firefox polyfill
|
|
│ ├── bridge/ # SSO bridge
|
|
│ ├── background.js # Chrome MV3 service worker
|
|
│ ├── background.firefox.js # Firefox MV2 background page
|
|
│ ├── manifest.json # Chrome/Edge MV3
|
|
│ └── manifest.firefox.json # Firefox MV2
|
|
├── migrations/ # Alembic migration scripts
|
|
├── scripts/ # Nginx, systemd, backup
|
|
└── requirements.txt
|
|
```
|
|
|
|
---
|
|
|
|
## API Overview
|
|
|
|
All vault/folder endpoints require `Authorization: Bearer <access_token>`.
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| POST | `/api/auth/register` | Create account |
|
|
| POST | `/api/auth/login` | Authenticate |
|
|
| POST | `/api/auth/mfa/verify` | Complete MFA (single-use code) |
|
|
| POST | `/api/auth/refresh` | Rotate tokens |
|
|
| POST | `/api/auth/logout` | Blacklist tokens |
|
|
| GET | `/api/vault` | List encrypted items |
|
|
| POST | `/api/vault` | Create item (`enc_data`, `iv`, `enc_name`, `iv_name`, tags in payload) |
|
|
| PUT | `/api/vault/<id>` | Update item |
|
|
| DELETE | `/api/vault/<id>` | Delete item |
|
|
| GET | `/api/vault/export` | Download encrypted JSON backup |
|
|
| POST | `/api/vault/import` | Bulk import; returns `{ imported, skipped }` |
|
|
| GET/POST | `/api/folders` | List / create folders |
|
|
| POST | `/api/sharing` | Share item — sends `enc_name`/`iv_name` for ZK name |
|
|
| POST | `/api/emergency` | Create emergency access grant |
|
|
| POST | `/api/auth/change-password` | Atomic vault re-encryption |
|
|
| POST | `/api/auth/recover` | Account recovery (one-time) |
|
|
| POST | `/api/webauthn/register/begin` | Start passkey registration |
|
|
| POST | `/api/webauthn/register/complete` | Finish passkey registration |
|
|
| POST | `/api/webauthn/authenticate/begin` | Start passkey login |
|
|
| POST | `/api/webauthn/authenticate/complete` | Complete passkey login → tokens |
|
|
| GET | `/api/webauthn/credentials` | List registered passkeys |
|
|
| DELETE | `/api/webauthn/credentials/<id>` | Remove a passkey |
|
|
|
|
---
|
|
|
|
## Item Tagging
|
|
|
|
Tags are stored as `plain.tags: string[]` inside the encrypted vault blob — the server never sees them and no schema change is required.
|
|
|
|
**Web app:** Add tags in the item edit modal (comma-separated). Tags appear as purple badge pills on item rows. A Tags section in the sidebar lets you filter by any tag. Search respects the active tag filter.
|
|
|
|
**Extension:** Tags appear as `.pk-tag` badges on item rows. Items tagged `favorite` appear in the **Favorites** tab and show a ★ in the site label.
|
|
|
|
---
|
|
|
|
## Backup
|
|
|
|
```bash
|
|
# Install cron job
|
|
sudo cp scripts/passkeeper-logrotate /etc/logrotate.d/passkeeper
|
|
crontab scripts/backup.cron
|
|
|
|
# Manual backup
|
|
bash scripts/backup_db.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Licence
|
|
|
|
MIT — see `LICENSE`. |