# PassKeeper 🔐

A self-hosted, zero-knowledge password manager — web app and browser extension. Modelled after LastPass, built on Flask + MySQL + Web Crypto API.

Your master password and decrypted vault data **never leave your browser**. The server stores only encrypted blobs it cannot read.

---

## Features

### Web App
- **Zero-knowledge encryption** — AES-256-GCM client-side, 600k-iteration PBKDF2 vault key derivation
- **7 item types** — Passwords, Secure Notes, Payment Cards, Bank Accounts, Addresses, Identities, Passkeys
- **TOTP/2FA support** — per-site TOTP codes stored inside the encrypted vault blob; live 6-digit display with countdown
- **Folder organisation** — create, rename, delete folders; filter vault by folder
- **Item sharing** — zero-knowledge ECDH P-256 re-encryption; share with any registered user
- **Emergency access** — configurable wait-timer access grant for a trusted contact
- **Security dashboard** — weak, reused, and old password detection + **HaveIBeenPwned k-anonymity breach check** (passwords never transmitted)
- **Account MFA** — TOTP-based login verification (Google Authenticator / Authy)
- **Master password change** — atomic zero-knowledge re-encryption of the entire vault
- **Account recovery** — 128-bit recovery code; server never stores it
- **Audit log** — server-side trail of all create/edit/delete actions; no sensitive data ever logged
- **Encrypted item names** — item names stored as AES-256-GCM ciphertext; server holds only the item type as a label
- **Responsive layout** — phone, tablet, laptop, and large desktop breakpoints; collapsible sidebar

### Browser Extension (Chrome / Edge — Manifest V3)
- **Autofill** — detects login forms; injects icon into username and password fields only (scored heuristic, not all text inputs)
- **Suggestion dropdown** — anchored below the focused field; filters as you type; keyboard navigation (↑↓ Enter); fills with one click
- **Smart domain matching** — matches vault items by domain name, handles bare domains (`github.com`) and subdomains
- **Auto-save banner** — prompts to save or update credentials on form submit; duplicate detection; "Never for this site" blocklist
- **Inline password generator** — length slider, charset toggles, strength indicator; fully CSPRNG (`crypto.getRandomValues` throughout)
- **TOTP live display** — 6-digit code + countdown timer per item in the popup
- **SSO bridge** — log in once on the web app; extension picks up the session automatically
- **Idle lock** — configurable auto-lock timeout (1 / 5 / 10 / 30 min / Never)
- **Security** — decrypted vault data stored in `chrome.storage.session` only (memory-only, never written to disk)

---

## 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 (stays in browser memory only)
                                                      │
                                              AES-256-GCM encrypt
                                                      │
                                              enc_data + iv  ──►  POST /api/vault
                                              enc_name + iv_name  (item name, encrypted separately)
```

The server is blind to all vault content. A database breach exposes only encrypted ciphertext.

---

## 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 Manifest V3 |
| Web server | Nginx + Gunicorn + systemd |
| Rate limiting | Flask-Limiter + Redis |
| TLS | Let's Encrypt / Certbot |

---

## Getting Started

### Prerequisites

- Python 3.12+
- MySQL 8.x
- Node.js is **not** required — no build step

### Development (Windows)

```bash
# 1. Clone and set up virtual environment
git clone https://github.com/yourname/passkeeper
cd passkeeper
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# 2. Configure environment
copy .env.example .env
```

Edit `.env`:

```env
FLASK_ENV=development
SECRET_KEY=your-secret-key
JWT_SECRET_KEY=your-jwt-secret
MYSQL_HOST=localhost
MYSQL_USER=passkeeper
MYSQL_PASSWORD=yourpassword
MYSQL_DB=passkeeper
TOTP_ENCRYPTION_KEY=64-char-hex-string   # python -c "import secrets; print(secrets.token_hex(32))"
```

```bash
# 3. Create database
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';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON passkeeper.* TO 'passkeeper'@'localhost'; FLUSH PRIVILEGES;"

# 4. Create tables
python reset_db.py

# 5. Run
python run.py
```

Open `http://localhost:5000`.

### Load the Extension (Chrome)

1. Open `chrome://extensions/`
2. Enable **Developer mode** (top-right toggle)
3. Click **Load unpacked** → select the `extension/` folder
4. Reload the extension after any JS/CSS changes

Content script logs appear in the **page's** DevTools console. Background service worker logs are at `chrome://extensions/` → PassKeeper → "Service Worker".

---

## 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

Copy `scripts/passkeeper.service` to `/etc/systemd/system/passkeeper.service`, then:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now passkeeper
journalctl -xeu passkeeper.service
```

Key flags in the service unit: `--preload` (single app import, lower memory), `WatchdogSec=60s`, `Restart=on-failure`.

### 4. Nginx

Copy `scripts/passkeeper-nginx.conf` to `/etc/nginx/sites-available/passkeeper`, update `server_name`, then:

```bash
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
```

The Nginx config uses an `upstream` block with `proxy_next_upstream` for zero-downtime Gunicorn restarts, dual rate-limit zones (auth endpoints and general API), and `Cache-Control: immutable` for static assets.

### 5. Schema migrations (future updates)

```bash
flask db upgrade
sudo systemctl reload passkeeper
```

---

## Environment Variables

| Variable | Description | Example |
|---|---|---|
| `SECRET_KEY` | Flask session secret | 64-char random hex |
| `JWT_SECRET_KEY` | JWT signing secret | 64-char random hex |
| `MYSQL_HOST` | MySQL host | `localhost` |
| `MYSQL_USER` | MySQL username | `passkeeper` |
| `MYSQL_PASSWORD` | MySQL password | — |
| `MYSQL_DB` | Database name | `passkeeper` |
| `TOTP_ENCRYPTION_KEY` | Server-side AES key for TOTP secrets | 64-char hex |
| `RATELIMIT_STORAGE_URI` | Redis URI for rate limiting | `redis://127.0.0.1:6379/0` |
| `CORS_ORIGINS` | Allowed CORS origins | `https://yourdomain.com` |

Generate secrets:

```bash
python -c "import secrets; print(secrets.token_hex(32))"
```

---

## Project Structure

```
passkeeper/
├── app/                    # Flask application
│   ├── models/             # SQLAlchemy models
│   ├── routes/             # API blueprints (auth, vault, folders, sharing, emergency)
│   ├── services/           # Auth service (Argon2id, JWT, TOTP encryption)
│   ├── static/js/          # Client-side crypto + vault UI
│   └── templates/          # Jinja2 HTML templates
├── extension/              # Chrome extension (Manifest V3)
│   ├── popup/              # Popup UI (HTML + CSS + JS)
│   ├── content/            # Content script (form detection, autofill icon, dropdown)
│   ├── shared/             # Shared crypto (vault key, encryptName/decryptName)
│   ├── bridge/             # SSO bridge (web app ↔ extension session sync)
│   └── background.js       # Service worker (badges, message relay, idle lock)
├── migrations/             # Alembic migration scripts
├── scripts/                # Nginx config, systemd unit, backup scripts
├── reset_db.py             # Dev-only: drop + recreate all tables
├── requirements.txt
├── run.py                  # Development server entry point
└── wsgi.py                 # Gunicorn entry point
```

---

## API Overview

All vault and folder endpoints require `Authorization: Bearer <access_token>`.

| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/auth/register` | Create account |
| POST | `/api/auth/login` | Authenticate; returns tokens or MFA challenge |
| POST | `/api/auth/mfa/verify` | Complete MFA step |
| POST | `/api/auth/refresh` | Rotate refresh token |
| POST | `/api/auth/logout` | Blacklist both tokens |
| GET | `/api/vault` | List all encrypted vault items |
| POST | `/api/vault` | Create item (`enc_data`, `iv`, `enc_name`, `iv_name`) |
| PUT | `/api/vault/<id>` | Update item |
| DELETE | `/api/vault/<id>` | Delete item |
| GET | `/api/folders` | List 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 on password change |
| POST | `/api/auth/recover` | Account recovery (one-time use) |

---

## Backup

Automated MySQL backups with 30-day retention:

```bash
# Install cron job
sudo cp scripts/passkeeper-logrotate /etc/logrotate.d/passkeeper
crontab scripts/backup.cron
```

Manual backup:

```bash
bash scripts/backup_db.sh
```

---

## Licence

MIT — see `LICENSE`.