05/07: updated markdown documents

2026-05-07 17:18:51 -04:00
parent 2f9d4996a8
commit c054147018
2 changed files with 804 additions and 0 deletions
@@ -0,0 +1,288 @@
+# 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
+- **Advanced Settings per password item** — Autofill (on/off), Autologin (auto-submit form), Reprompt (re-verify master password before use); all stored encrypted inside `enc_data` — zero-knowledge, no schema change
+- **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; share with any registered user
+- **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
+- **Account MFA** — TOTP-based login (Google Authenticator / Authy)
+- **Master password change** — atomic zero-knowledge re-encryption of entire vault including item names
+- **Account recovery** — 128-bit recovery code; server never stores it
+- **Audit log** — server-side trail of all create/edit/delete/import/export actions
+- **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)
+- **Advanced Settings enforcement** — respects per-item settings from the web vault:
+  - **Autofill off** — hides the fill button; item still appears in the list but cannot be auto-filled
+  - **Autologin** — after filling, automatically clicks the submit button (400 ms delay for SPA compatibility)
+  - **Reprompt** — shows a master-password overlay before filling, copying, or accessing the item
+- **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; rendered with `position: fixed` to escape list overflow clipping; auto-flips above button when near bottom nav
+- **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
+      │
+      └─ 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
+```
+
+A database breach exposes only encrypted ciphertext. The server cannot read vault names, passwords, or tags.
+
+---
+
+## 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) |
+| 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) |
+
+---
+
+## Project Structure
+
+```
+passkeeper/
+├── app/                  # Flask application
+│   ├── models/           # SQLAlchemy models
+│   ├── routes/           # API blueprints (auth, vault, folders, sharing, emergency)
+│   ├── services/         # Auth (Argon2id, JWT, TOTP encryption)
+│   ├── 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 |
+| 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 (ECDH re-encryption) |
+| POST | `/api/emergency` | Create emergency access grant |
+| POST | `/api/auth/change-password` | Atomic vault re-encryption |
+| POST | `/api/auth/recover` | Account recovery (one-time) |
+
+---
+
+## 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.
+
+**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.
+
+---
+
+## Advanced Settings (Password Items)
+
+Three optional boolean fields stored inside `enc_data` alongside credentials — zero-knowledge, no schema change required.
+
+| Setting | Default | Effect |
+|---|---|---|
+| **Autofill** | ✅ Enabled | Extension shows the fill button; disabling hides it (item still visible in the list) |
+| **Autologin** | ☐ Off | After filling credentials, the extension automatically submits the login form |
+| **Reprompt** | ☐ Off | Before filling or copying, a master-password overlay must be passed |
+
+Configure in the **Advanced Settings** collapsible at the bottom of the password item modal in the web vault. The section starts collapsed to keep the UI clean.
+
+---
+
+## 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`.