A local, encrypted password manager with a built-in web UI.

Interactive UI to manage passwords

Passwords are stored in ~/.sspwd/default/vault.db — fully encrypted with a key derived from your master password. Nothing leaves your machine.

Backend

• Python — package language
• FastAPI — REST API for the web UI
• SQLite — local encrypted vault database
• Argon2id + AES-256-GCM — key derivation and authenticated encryption
• pytest — test suite with coverage reporting

Frontend

• React — interactive UI
• Vite — frontend build tool and dev server
• TypeScript — type-safe components
• Tailwind CSS — utility-first styling
• Iconify — service and brand icons

CLI

• Click — CLI commands (serve, add, list, get, delete, projects)

Packaging

• PyPI — distributed as an installable Python package

pip install sspwd

Requires Python ≥ 3.10.

Alternatively, to install sspwd as a global CLI tool in an isolated environment, use pipx:

brew install pipx && pipx ensurepath && pipx install sspwd

Restart your terminal or run source ~/.zshrc, then use sspwd.

sspwd serve

Opens http://127.0.0.1:7523 in your browser — no password required at startup. The UI launches in demo mode (mockData). Select a project from the dropdown to unlock it with its master password, or create a new one.

mockData        ← demo data, no password needed
default    🔒   ← click to unlock with master password
work       🔒   ← separate encrypted vault
+ new           ← create a new project

# Start the server (opens browser automatically)
sspwd serve

# Start without opening the browser
sspwd serve --no-browser

# Work with a specific project
sspwd add --project work
sspwd list --project work
sspwd list --project work --search github

# Show a single entry by ID (reveals password)
sspwd get 3 --project work

# Delete an entry
sspwd delete 3 --project work

# List all existing projects
sspwd projects

# Change master password
sspwd change-password --project demo

All CLI commands that access a vault will prompt for the master password.

flowchart TD
    A([sspwd serve]) --> B[FastAPI server starts ➜ opens UI]

    B --> D{Select<br>a project}

    D -->|New project| E[Enter name + set master password]
    D -->|Existing project| F[Enter master password]

    E --> G[Argon2id derives 256-bit key from password + salt]
    F --> G

    G --> H{verify.bin<br>decryption}
    H -->|InvalidTag| I[Wrong password ➜ 401 Unauthorized]
    H -->|OK| J[Project unlocked ➜ entries loaded]

    J --> L{Action}

    L -->|Add / Edit| M[AES-256-GCM encrypt password + notes]
    M --> N[(~/.sspwd/project/vault.db )]

    L -->|Delete| N
    L -->|Upload icon| O[(~/.sspwd/project/icons/)]

    N --> P[Key discarded on server exit]
    O --> P

Each project is a completely isolated, separately encrypted vault:

~/.sspwd/
├── default/          ← created automatically on first use
│   ├── vault.db      ← encrypted entries
│   ├── salt.bin      ← 32-byte random salt (unique per project)
│   ├── verify.bin    ← encrypted sentinel for password verification
│   └── icons/        ← uploaded custom icons
├── work/
│   └── ...
└── private/
    └── ...

Projects can have different master passwords. Switching between them in the UI prompts for the relevant password only once per server session.

Vault files explained

The master password is never stored anywhere. It is entered in the browser UI, used to derive the AES key via Argon2id, and the key lives only in process memory for the lifetime of the server session. Stopping sspwd serve discards it.

Backup: Your vault is local only — there is no sync. Back it up with:

rsync -av ~/.sspwd/ ~/path/to/backup/

Browser managers (Safari Keychain, Chrome Passwords) sync to Apple/Google servers by default. Even with strong client-side encryption, you are trusting a corporation's infrastructure, account security, and update pipeline. Their browser extension autofill is also a real attack surface — extensions request access to read and modify all pages, making a compromised extension a universal credential harvester. In comparison, the copy-paste method is more deliberate and phishing-resistant.

1Password / Bitwarden are the closest conceptual relatives — master password, local encryption, structured entries. Bitwarden is open-source and self-hostable. Their advantage is cross-device sync and mobile apps; their disadvantage is mandatory account setup, cloud dependency (unless self-hosted), and no project isolation without a paid Teams plan.

macOS Keychain is local and OS-integrated but has no organisational structure, no web UI, is macOS-only, and is difficult to export or script against.

sspwd's advantage is zero setup, zero accounts, zero cloud, and the ability to keep personal, work, and project credentials in cleanly separated encrypted vaults — with a searchable, filterable UI accessible from any browser on localhost.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-change)
3. Make your changes
4. Run the test suite: pytest --cov=src --cov-report=term-missing
5. Submit a pull request

MIT — see LICENSE.