basic-password-manager 0.2.4__tar.gz → 0.4.0__tar.gz

basic_password_manager-0.4.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: basic-password-manager
+Version: 0.4.0
+Summary: The Paladin — a local encrypted password manager that lives in your terminal
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Daisentaur/password-manager
+Project-URL: Changelog, https://github.com/Daisentaur/password-manager/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: argon2-cffi
+Requires-Dist: cryptography
+Requires-Dist: textual
+Requires-Dist: qrcode
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" width="160" alt="The Paladin — a pixel-art knight" />
+</p>
+
+<h1 align="center">The Paladin</h1>
+
+<p align="center"><em>Your passwords, guarded locally. No browser, no cloud, just protection.</em></p>
+
+A password manager that is one encrypted file on my own disk and a small
+terminal app in front of it. No browser, no cloud, no daemon, no ai running 
+in the background, no company holding my secrets. One file, one master password,
+that's the whole thing.
+
+(It installs as `basic-password-manager` because the name "The Paladin" came to me
+quite a while after already starting the project. It answers to `paladin` as is its name)
+
+![unlocking the vault](assets/unlock.gif)
+
+## Install
+
+From PyPI ([pipx](https://pipx.pypa.io) keeps CLI tools out of each other's business):
+
+```bash
+pipx install basic-password-manager    # or: pip install basic-password-manager
+paladin init
+```
+
+From source:
+
+```bash
+git clone https://github.com/Daisentaur/password-manager && cd password-manager
+pipx install .
+```
+
+Hacking on it: `python3 -m venv venv && ./venv/bin/pip install -e .`
+
+## The TUI
+
+Run `paladin` with nothing after it and you get the full app: unlock, arrow
+around, Enter copies the selected password to your clipboard. `n` adds,
+`e` edits, `d` deletes (it asks first), `q` quits. Every key is listed in
+the bottom bar so there's nothing to memorize.
+
+Press `/` and type whatever fragments you remember of whatever it is you're
+looking for it just has to appear *somewhere* in the entry, any field, any
+order. It even searches inside the passwords themselves, for the day all
+you remember is what you typed on that site, so if it's in there the search 
+will for sure find it. Matches get highlighted in the theme's accent, except
+password matches, which quietly show the row and highlight nothing — passwords
+never get displayed, that's the deal).
+
+![searching the vault](assets/search.gif)
+
+The rarer stuff lives in the command palette — `super+p`, commands you will need
+sometimes but deffintely shouldn't crowd the main password list for example, 
+importing your browser's passwords, opening your vault on your phone, and
+changing the master password all live there, along with others.
+
+![the command palette](assets/palette.gif)
+
+And themes. `t` opens the theme picker; the bundled ones — muted-slate (default),
+dawn, matrix — are lifted with love from
+[tuxedo](https://github.com/webstonehq/tuxedo)'s palettes, and all of
+Textual's built-ins are in there too. Your pick sticks across runs. Even the
+knight on the unlock screen dresses to match your theme, try it ;)
+
+![switching themes](assets/themes.gif)
+
+## The CLI
+
+Same vault, no interface, for when you just want the thing:
+
+| Command | What it does |
+|---|---|
+| `paladin init` | create a new empty vault |
+| `paladin add example` | store an entry (prompts for username/password/notes) |
+| `paladin add example --gen` | same, but it invents a strong random password for you |
+| `paladin get example` | copy the password to the clipboard, show the username |
+| `paladin edit example` | update an entry field by field (Enter keeps what's there) |
+| `paladin passwd` | change the master password |
+| `paladin ls` | list entry names |
+| `paladin rm example` | delete an entry |
+| `paladin find "dt bank"` | search names, usernames, notes — every word must match, any order |
+| `paladin gen -l 32` | just print a random password |
+| `paladin import passwords.csv` | import a browser CSV export (see below) |
+| `paladin mobile` | open your vault on your phone (QR + HTTPS tunnel) |
+| `paladin about` | meet the knight |
+
+The vault lives at `~/.local/share/pw-manager/vault`. Point the `PW_VAULT`
+environment variable somewhere else if you disagree.
+
+The `notes` field takes anything you want kept secret next to the password —
+recovery codes, PINs, the answer to "what was your first pet".
+
+### Leaving your browser's password manager
+
+This is why the project exists, so here's the exit route:
+
+1. Export:
+   Chrome → `chrome://password-manager/settings` → "Export passwords".
+   Firefox → `about:logins` → ⋯ menu → "Export passwords".
+   Either way you get a CSV.
+3. `paladin import passwords.csv` 
+4. **Delete that CSV immediately** — it's every password you own, in
+   plaintext: `shred -u passwords.csv`
+5. Turn off password saving in the browser and delete what it stored.
+
+## Your phone
+
+`paladin mobile` (or "Open on phone" in the palette) puts your vault on your
+phone with one QR scan. It spins up a throwaway HTTPS tunnel
+([cloudflared](https://github.com/cloudflare/cloudflared), fetched
+automatically the first time), serves a single page with the *encrypted*
+vault baked in, and prints the URL as a QR in your terminal. Scan it, type
+your master password **on the phone**, and the decryption happens in the
+phone's browser — the laptop, the tunnel, and the network only ever carry
+ciphertext. Nothing is stored on the phone; the page auto-locks after 5
+minutes idle, and the whole session dies when you press Ctrl+C.
+
+It works on any modern phone browser (Safari, Chrome, Firefox…) — no app to
+install. The page opens in whatever TUI theme you had set when you generated
+the QR, knight and all (it won't follow later theme changes — scan again for
+that).
+
+Have your own domain? `paladin mobile --url https://vault.you.dev` serves at
+your subdomain instead of a random tunnel, so a bookmark keeps working (the
+path rotates every 30 days on its own). It serves on `127.0.0.1:8787` by
+default — point your reverse proxy or named tunnel there. Set
+`PALADIN_MOBILE_URL` (and optionally `PALADIN_MOBILE_PORT`) and plain
+`paladin mobile` uses it.
+
+The one thing crossing the internet is the encrypted blob, which is useless
+without the master password that never leaves your phone. The tunnel provider
+sees the same noise anyone else would.
+
+## How it works
+
+Three layers, pretty small. This project exists because I wanted to 
+understand this stuff, I'd be happy if someone learns from this, from me:
+
+### 1. `crypto.py` — password → key, key → ciphertext
+
+An AES key must be 32 unpredictable bytes; your master password is neither.
+**Argon2id** bridges the gap: `derive_key(password, salt)` always returns the
+same 32 bytes for the same inputs — that's what makes unlocking possible at
+all. It's deliberately slow and memory-hungry (64 MiB *per guess*), so
+someone who steals the vault file can't brute-force short passwords on a GPU
+the way they could against a plain hash. The pause when you unlock? That's
+the lock being hard to pick. I've learned to love it.
+
+The **salt** is 16 random bytes stored *unencrypted* in the vault file, and
+that's fine — it's not a secret. Its whole job is making your derived key
+unique so precomputed attack tables are useless. (This took me a while to
+truly believe. It's fine. Smarter people than me checked.)
+
+Encryption is **AES-256-GCM**, which is *authenticated*: decrypt with the
+wrong key, or decrypt a file where even one bit was flipped, and it fails
+loudly instead of handing back plausible garbage. Every encryption uses a
+fresh random 12-byte **nonce** (also stored unencrypted, also not a secret).
+The one iron rule of GCM: a (key, nonce) pair must never repeat — which is
+why it's random every single time.
+
+### 2. `vault.py` — the file format
+
+```
+[4 bytes "PWV1"][16-byte salt][12-byte nonce][ciphertext...]
+```
+
+The ciphertext is just your entries as JSON, encrypted. Load = read → derive
+key → decrypt → `json.loads`. Save = the same backwards, with a fresh salt
+and nonce, written to a temp file and atomically renamed so a crash
+mid-write can't destroy the vault.
+
+Your master password is stored nowhere. Not hashed, not hidden — nowhere.
+"Wrong password" is just the decryption screaming, translated.
+
+### 3. `cli.py` and `tui.py` — the interfaces
+
+Both are thin skins over the two modules above. The TUI (built with
+[Textual](https://textual.textualize.io)) holds the decrypted entries in
+memory for the session; the CLI re-derives the key per command.
+
+Passwords go to the clipboard (`wl-copy`/`xclip`/`xsel`, whichever exists)
+rather than the screen, so they don't sit in your terminal scrollback. One
+deliberate asymmetry: CLI `find` does *not* search passwords, because a CLI
+argument lands in your shell history forever — the TUI search box does,
+because nothing you type there is logged anywhere.
+
+## Backups
+
+Every save keeps the previous version as `vault.bak` next to the vault —
+one-step undo for when a save goes wrong or you delete the wrong entry.
+
+That covers mistakes, not the disk dying. For that: the vault is one file,
+so copy it anywhere. Another disk, a USB stick, even somewhere you don't
+trust — it's gibberish without the master password.
+
+```bash
+cp ~/.local/share/pw-manager/vault /some/backup/location/
+```
+
+### Moving to a new machine (or another OS)
+
+The vault file plus the master password in your head is the *complete*
+system — the salt lives inside the file, nothing belongs to the machine.
+Install the package on the new system, drop your vault at
+`~/.local/share/pw-manager/vault` (don't run `init` — that's for brand-new
+vaults only), and everything works. Dual-booting? Park the vault on a
+partition both systems mount and point both at it:
+`export PW_VAULT=/mnt/shared/vault`.
+
+## Troubleshooting
+
+**"I forgot the master password."** The data is gone. Mathematically gone.
+That's by design: every "forgot password?" flow is a back door, and back doors
+don't check IDs. Pick a long phrase you can't forget (a sentence beats
+`Tr0ub4dor&3`), and know that backups protect you from losing the *file*,
+never from forgetting the *word*.
+
+**"wrong master password (or the vault file is corrupted)"** — 99% of the
+time you typo'd it. If you're *certain* it's right, the file got damaged;
+restore the automatic backup
+(`cp ~/.local/share/pw-manager/vault.bak ~/.local/share/pw-manager/vault`)
+or an off-machine copy.
+
+**Deleted or overwrote an entry by mistake** — the state before your last
+save is sitting in `vault.bak`; restore it as above. One generation only,
+so do it before the next save.
+
+**"not a vault file (bad magic bytes)"** — whatever's at the vault path
+isn't ours (truncated, overwritten, or wrong path). Check `echo $PW_VAULT`
+and restore from a backup.
+
+**"no vault at ..."** — run `paladin init`, or `PW_VAULT` points somewhere
+unexpected.
+
+**Password prints instead of copying** — no clipboard tool found. Install
+one: `sudo apt install wl-clipboard` (Wayland) or `xclip` (X11).
+
+**Unlock feels slow (~1s)** — that's Argon2 doing its job. The delay *is*
+the brute-force resistance. Per command, not per keystroke.
+
+**`MemoryError` from Argon2** — the key derivation wants 64 MiB free;
+something is eating your RAM.
+
+**Import brought in junk** — browser CSVs export everything, including
+accounts from 2013. `paladin rm <name>` the corpses, or prune the CSV first.
+
+## Honest limitations
+
+I'd rather you know these than find them:
+
+- No clipboard auto-clear yet: a copied password stays on the clipboard
+  until you copy over it. Copy something else when you're done.
+- While a command runs, decrypted data briefly exists in process memory.
+  Malware already on your machine could read it — true of every password
+  manager ever made; the vault protects the file at rest, not a compromised
+  machine.
+- Single file, no sync. Syncing is your problem for now.
+
+## Running the checks
+
+```bash
+./venv/bin/python test_vault.py
+```

basic_password_manager-0.4.0/README.md

@@ -0,0 +1,265 @@
+<p align="center">
+  <img src="assets/logo.png" width="160" alt="The Paladin — a pixel-art knight" />
+</p>
+
+<h1 align="center">The Paladin</h1>
+
+<p align="center"><em>Your passwords, guarded locally. No browser, no cloud, just protection.</em></p>
+
+A password manager that is one encrypted file on my own disk and a small
+terminal app in front of it. No browser, no cloud, no daemon, no ai running 
+in the background, no company holding my secrets. One file, one master password,
+that's the whole thing.
+
+(It installs as `basic-password-manager` because the name "The Paladin" came to me
+quite a while after already starting the project. It answers to `paladin` as is its name)
+
+![unlocking the vault](assets/unlock.gif)
+
+## Install
+
+From PyPI ([pipx](https://pipx.pypa.io) keeps CLI tools out of each other's business):
+
+```bash
+pipx install basic-password-manager    # or: pip install basic-password-manager
+paladin init
+```
+
+From source:
+
+```bash
+git clone https://github.com/Daisentaur/password-manager && cd password-manager
+pipx install .
+```
+
+Hacking on it: `python3 -m venv venv && ./venv/bin/pip install -e .`
+
+## The TUI
+
+Run `paladin` with nothing after it and you get the full app: unlock, arrow
+around, Enter copies the selected password to your clipboard. `n` adds,
+`e` edits, `d` deletes (it asks first), `q` quits. Every key is listed in
+the bottom bar so there's nothing to memorize.
+
+Press `/` and type whatever fragments you remember of whatever it is you're
+looking for it just has to appear *somewhere* in the entry, any field, any
+order. It even searches inside the passwords themselves, for the day all
+you remember is what you typed on that site, so if it's in there the search 
+will for sure find it. Matches get highlighted in the theme's accent, except
+password matches, which quietly show the row and highlight nothing — passwords
+never get displayed, that's the deal).
+
+![searching the vault](assets/search.gif)
+
+The rarer stuff lives in the command palette — `super+p`, commands you will need
+sometimes but deffintely shouldn't crowd the main password list for example, 
+importing your browser's passwords, opening your vault on your phone, and
+changing the master password all live there, along with others.
+
+![the command palette](assets/palette.gif)
+
+And themes. `t` opens the theme picker; the bundled ones — muted-slate (default),
+dawn, matrix — are lifted with love from
+[tuxedo](https://github.com/webstonehq/tuxedo)'s palettes, and all of
+Textual's built-ins are in there too. Your pick sticks across runs. Even the
+knight on the unlock screen dresses to match your theme, try it ;)
+
+![switching themes](assets/themes.gif)
+
+## The CLI
+
+Same vault, no interface, for when you just want the thing:
+
+| Command | What it does |
+|---|---|
+| `paladin init` | create a new empty vault |
+| `paladin add example` | store an entry (prompts for username/password/notes) |
+| `paladin add example --gen` | same, but it invents a strong random password for you |
+| `paladin get example` | copy the password to the clipboard, show the username |
+| `paladin edit example` | update an entry field by field (Enter keeps what's there) |
+| `paladin passwd` | change the master password |
+| `paladin ls` | list entry names |
+| `paladin rm example` | delete an entry |
+| `paladin find "dt bank"` | search names, usernames, notes — every word must match, any order |
+| `paladin gen -l 32` | just print a random password |
+| `paladin import passwords.csv` | import a browser CSV export (see below) |
+| `paladin mobile` | open your vault on your phone (QR + HTTPS tunnel) |
+| `paladin about` | meet the knight |
+
+The vault lives at `~/.local/share/pw-manager/vault`. Point the `PW_VAULT`
+environment variable somewhere else if you disagree.
+
+The `notes` field takes anything you want kept secret next to the password —
+recovery codes, PINs, the answer to "what was your first pet".
+
+### Leaving your browser's password manager
+
+This is why the project exists, so here's the exit route:
+
+1. Export:
+   Chrome → `chrome://password-manager/settings` → "Export passwords".
+   Firefox → `about:logins` → ⋯ menu → "Export passwords".
+   Either way you get a CSV.
+3. `paladin import passwords.csv` 
+4. **Delete that CSV immediately** — it's every password you own, in
+   plaintext: `shred -u passwords.csv`
+5. Turn off password saving in the browser and delete what it stored.
+
+## Your phone
+
+`paladin mobile` (or "Open on phone" in the palette) puts your vault on your
+phone with one QR scan. It spins up a throwaway HTTPS tunnel
+([cloudflared](https://github.com/cloudflare/cloudflared), fetched
+automatically the first time), serves a single page with the *encrypted*
+vault baked in, and prints the URL as a QR in your terminal. Scan it, type
+your master password **on the phone**, and the decryption happens in the
+phone's browser — the laptop, the tunnel, and the network only ever carry
+ciphertext. Nothing is stored on the phone; the page auto-locks after 5
+minutes idle, and the whole session dies when you press Ctrl+C.
+
+It works on any modern phone browser (Safari, Chrome, Firefox…) — no app to
+install. The page opens in whatever TUI theme you had set when you generated
+the QR, knight and all (it won't follow later theme changes — scan again for
+that).
+
+Have your own domain? `paladin mobile --url https://vault.you.dev` serves at
+your subdomain instead of a random tunnel, so a bookmark keeps working (the
+path rotates every 30 days on its own). It serves on `127.0.0.1:8787` by
+default — point your reverse proxy or named tunnel there. Set
+`PALADIN_MOBILE_URL` (and optionally `PALADIN_MOBILE_PORT`) and plain
+`paladin mobile` uses it.
+
+The one thing crossing the internet is the encrypted blob, which is useless
+without the master password that never leaves your phone. The tunnel provider
+sees the same noise anyone else would.
+
+## How it works
+
+Three layers, pretty small. This project exists because I wanted to 
+understand this stuff, I'd be happy if someone learns from this, from me:
+
+### 1. `crypto.py` — password → key, key → ciphertext
+
+An AES key must be 32 unpredictable bytes; your master password is neither.
+**Argon2id** bridges the gap: `derive_key(password, salt)` always returns the
+same 32 bytes for the same inputs — that's what makes unlocking possible at
+all. It's deliberately slow and memory-hungry (64 MiB *per guess*), so
+someone who steals the vault file can't brute-force short passwords on a GPU
+the way they could against a plain hash. The pause when you unlock? That's
+the lock being hard to pick. I've learned to love it.
+
+The **salt** is 16 random bytes stored *unencrypted* in the vault file, and
+that's fine — it's not a secret. Its whole job is making your derived key
+unique so precomputed attack tables are useless. (This took me a while to
+truly believe. It's fine. Smarter people than me checked.)
+
+Encryption is **AES-256-GCM**, which is *authenticated*: decrypt with the
+wrong key, or decrypt a file where even one bit was flipped, and it fails
+loudly instead of handing back plausible garbage. Every encryption uses a
+fresh random 12-byte **nonce** (also stored unencrypted, also not a secret).
+The one iron rule of GCM: a (key, nonce) pair must never repeat — which is
+why it's random every single time.
+
+### 2. `vault.py` — the file format
+
+```
+[4 bytes "PWV1"][16-byte salt][12-byte nonce][ciphertext...]
+```
+
+The ciphertext is just your entries as JSON, encrypted. Load = read → derive
+key → decrypt → `json.loads`. Save = the same backwards, with a fresh salt
+and nonce, written to a temp file and atomically renamed so a crash
+mid-write can't destroy the vault.
+
+Your master password is stored nowhere. Not hashed, not hidden — nowhere.
+"Wrong password" is just the decryption screaming, translated.
+
+### 3. `cli.py` and `tui.py` — the interfaces
+
+Both are thin skins over the two modules above. The TUI (built with
+[Textual](https://textual.textualize.io)) holds the decrypted entries in
+memory for the session; the CLI re-derives the key per command.
+
+Passwords go to the clipboard (`wl-copy`/`xclip`/`xsel`, whichever exists)
+rather than the screen, so they don't sit in your terminal scrollback. One
+deliberate asymmetry: CLI `find` does *not* search passwords, because a CLI
+argument lands in your shell history forever — the TUI search box does,
+because nothing you type there is logged anywhere.
+
+## Backups
+
+Every save keeps the previous version as `vault.bak` next to the vault —
+one-step undo for when a save goes wrong or you delete the wrong entry.
+
+That covers mistakes, not the disk dying. For that: the vault is one file,
+so copy it anywhere. Another disk, a USB stick, even somewhere you don't
+trust — it's gibberish without the master password.
+
+```bash
+cp ~/.local/share/pw-manager/vault /some/backup/location/
+```
+
+### Moving to a new machine (or another OS)
+
+The vault file plus the master password in your head is the *complete*
+system — the salt lives inside the file, nothing belongs to the machine.
+Install the package on the new system, drop your vault at
+`~/.local/share/pw-manager/vault` (don't run `init` — that's for brand-new
+vaults only), and everything works. Dual-booting? Park the vault on a
+partition both systems mount and point both at it:
+`export PW_VAULT=/mnt/shared/vault`.
+
+## Troubleshooting
+
+**"I forgot the master password."** The data is gone. Mathematically gone.
+That's by design: every "forgot password?" flow is a back door, and back doors
+don't check IDs. Pick a long phrase you can't forget (a sentence beats
+`Tr0ub4dor&3`), and know that backups protect you from losing the *file*,
+never from forgetting the *word*.
+
+**"wrong master password (or the vault file is corrupted)"** — 99% of the
+time you typo'd it. If you're *certain* it's right, the file got damaged;
+restore the automatic backup
+(`cp ~/.local/share/pw-manager/vault.bak ~/.local/share/pw-manager/vault`)
+or an off-machine copy.
+
+**Deleted or overwrote an entry by mistake** — the state before your last
+save is sitting in `vault.bak`; restore it as above. One generation only,
+so do it before the next save.
+
+**"not a vault file (bad magic bytes)"** — whatever's at the vault path
+isn't ours (truncated, overwritten, or wrong path). Check `echo $PW_VAULT`
+and restore from a backup.
+
+**"no vault at ..."** — run `paladin init`, or `PW_VAULT` points somewhere
+unexpected.
+
+**Password prints instead of copying** — no clipboard tool found. Install
+one: `sudo apt install wl-clipboard` (Wayland) or `xclip` (X11).
+
+**Unlock feels slow (~1s)** — that's Argon2 doing its job. The delay *is*
+the brute-force resistance. Per command, not per keystroke.
+
+**`MemoryError` from Argon2** — the key derivation wants 64 MiB free;
+something is eating your RAM.
+
+**Import brought in junk** — browser CSVs export everything, including
+accounts from 2013. `paladin rm <name>` the corpses, or prune the CSV first.
+
+## Honest limitations
+
+I'd rather you know these than find them:
+
+- No clipboard auto-clear yet: a copied password stays on the clipboard
+  until you copy over it. Copy something else when you're done.
+- While a command runs, decrypted data briefly exists in process memory.
+  Malware already on your machine could read it — true of every password
+  manager ever made; the vault protects the file at rest, not a compromised
+  machine.
+- Single file, no sync. Syncing is your problem for now.
+
+## Running the checks
+
+```bash
+./venv/bin/python test_vault.py
+```