psamvault 0.1.0__tar.gz

psamvault-0.1.0/.gitignore

@@ -0,0 +1,127 @@
+# =============================================================================
+# Python
+# =============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+lib/
+lib64/
+wheels/
+
+# =============================================================================
+# Virtual environment
+# =============================================================================
+cli_venv/
+.venv/
+venv/
+env/
+ENV/
+
+# =============================================================================
+# Environment variables — never commit secrets
+# =============================================================================
+.env
+.env.local
+*.env
+.env.bak
+
+# =============================================================================
+# psamvault session file — contains access token, refresh token, kdf_salt
+# This file lives at ~/.psamvault/session.json on the user's machine.
+# If it ever ends up inside the project folder, never commit it.
+# =============================================================================
+.psamvault/
+session.json
+*.session.json
+
+# =============================================================================
+# Packaging and distribution
+# If you ever publish psamvault to PyPI, these get generated automatically
+# =============================================================================
+dist/
+build/
+*.egg-info/
+MANIFEST
+
+# =============================================================================
+# IDE and editors
+# =============================================================================
+
+# VSCode
+.vscode/
+*.code-workspace
+
+# PyCharm / JetBrains
+.idea/
+*.iml
+*.iws
+*.ipr
+
+# Vim / Neovim
+*.swp
+*.swo
+*~
+
+# Emacs
+\#*\#
+.\#*
+
+# =============================================================================
+# OS generated files
+# =============================================================================
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+*.lnk
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.Spotlight-V100
+.Trashes
+
+# Linux
+*~
+
+# =============================================================================
+# Testing
+# =============================================================================
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+nosetests.xml
+test-results/
+
+# =============================================================================
+# Type checking
+# =============================================================================
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+
+# =============================================================================
+# Logs
+# =============================================================================
+*.log
+logs/

psamvault-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: psamvault
+Version: 0.1.0
+Summary: A secure command-line password vault.
+Project-URL: Homepage, https://github.com/psam-717/psamvault-cli
+Project-URL: Repository, https://github.com/psam-717/psamvault-cli
+Project-URL: Issues, https://github.com/psam-717/psamvault-cli/issues
+License: MIT
+Keywords: cli,encryption,password,security,vault
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyperclip>=1.9.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# psamvault
+
+A secure command-line password vault for the terminal.
+
+Your credentials are **encrypted locally** before being sent to the server — the server never sees your plaintext passwords or your encryption key.
+
+---
+
+## How it works
+
+```
+login password
+      │
+      ▼
+HMAC-SHA256 + pepper  →  master password
+                                │
+                                ▼
+              PBKDF2 (600k rounds) + kdf_salt  →  login key
+                                                        │
+                                                        ▼
+                                              decrypt VEK (AES-256-GCM)
+                                                        │
+                                                        ▼
+                                              VEK encrypts every vault entry
+```
+
+- **Pepper** — unique per device, stored in `~/.psamvault/config.env`. Never sent to the server.
+- **VEK (Vault Encryption Key)** — a random 32-byte key generated at signup. Stored encrypted on the server; decrypted locally at login.
+- **kdf_salt** — stored on the server, tied to your account. Ensures two users with the same password get different keys.
+
+---
+
+## Installation
+
+```bash
+pip install psamvault
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/psam-717/psamvault-cli
+cd psamvault-cli/cli
+pip install -e .
+```
+
+---
+
+## Workflow
+
+### 1. Configure
+
+Run this **once** after installing. It generates your pepper and saves the API URL.
+
+```bash
+psamvault configure
+```
+
+```
+ psamvault setup
+
+ Press Enter to accept the default value shown in brackets.
+
+ API URL [https://psam-vault-backend.onrender.com]:
+ Generating a secure pepper for your vault...
+ Configuration saved to ~/.psamvault/config.env
+```
+
+> ⚠️ **Back up `~/.psamvault/config.env`** — it contains your pepper. Losing it means losing access to your vault.
+
+To review your current config:
+
+```bash
+psamvault config-show
+```
+
+---
+
+### 2. Sign up
+
+```bash
+psamvault signup
+```
+
+Creates your account. Your VEK is generated locally, encrypted with your login key, and only the encrypted copy is sent to the server.
+
+Password requirements:
+- At least 8 characters
+- At least one uppercase letter
+- At least one digit
+
+---
+
+### 3. Log in
+
+```bash
+psamvault login
+```
+
+Decrypts your VEK locally using your login password and saves it to a local session file (`~/.psamvault/session.json`). All vault commands use this session — you won't be prompted for your password again until the session expires.
+
+---
+
+### 4. Check who's logged in
+
+```bash
+psamvault whoami
+```
+
+---
+
+## Vault commands
+
+### Add a credential
+
+```bash
+psamvault add github.com --user me@example.com --pass mysecret
+psamvault add github.com --user me@example.com --pass mysecret --notes "2FA enabled"
+psamvault add github.com --user me@example.com   # prompts for password
+```
+
+### Retrieve a credential
+
+```bash
+psamvault get github.com
+psamvault get github.com --copy   # copies password to clipboard, clears after 30s
+```
+
+### List all entries
+
+```bash
+psamvault list
+```
+
+Shows site name, username hint, and last-updated date. Does not decrypt entries.
+
+### Update a credential
+
+```bash
+psamvault update github.com --pass mynewpassword
+psamvault update github.com --user newuser@example.com --pass newpass
+psamvault update github.com --notes "2FA disabled"
+```
+
+### Delete a credential
+
+```bash
+psamvault delete github.com
+```
+
+Permanent — prompts for confirmation first.
+
+### Generate a secure password
+
+```bash
+psamvault generate                          # 20-char password with symbols
+psamvault generate --length 32
+psamvault generate --length 16 --no-symbols
+psamvault generate --length 20 --no-digits
+psamvault generate --save github.com --user me@example.com  # generate and save
+```
+
+Uses Python's `secrets` module (cryptographically secure).
+
+---
+
+## Recovery commands
+
+### Generate recovery codes
+
+Run this while logged in to protect your account against a forgotten password.
+
+```bash
+psamvault generate-codes
+```
+
+Generates **8 one-time recovery codes**. Each code encrypts your VEK — store them somewhere safe. Running this replaces all existing codes.
+
+### Check remaining codes
+
+```bash
+psamvault remaining-codes
+```
+
+### Recover your account (forgotten password)
+
+```bash
+psamvault recover
+```
+
+Use one of your saved recovery codes to reset your login password without losing your vault data. The VEK is recovered and re-wrapped with your new login key — no vault re-encryption needed.
+
+---
+
+## Log out
+
+```bash
+psamvault logout
+```
+
+Revokes the refresh token on the server and deletes the local session file. Your encrypted vault data remains safely on the server.
+
+---
+
+## Command groups
+
+All commands are available at the root level and also under grouped sub-commands:
+
+| Root shorthand | Grouped form |
+|---|---|
+| `psamvault login` | `psamvault auth login` |
+| `psamvault add` | `psamvault vault add` |
+| `psamvault generate-codes` | `psamvault recovery generate-codes` |
+
+Run any group without a subcommand to see its full command table:
+
+```bash
+psamvault auth
+psamvault vault
+psamvault recovery
+```
+
+---
+
+## Configuration files
+
+| File | Purpose |
+|---|---|
+| `~/.psamvault/config.env` | API URL and pepper — **back this up** |
+| `~/.psamvault/session.json` | Active session tokens and decrypted VEK |
+
+Both files are restricted to owner read/write only (`chmod 600`).
+
+---
+
+## Security notes
+
+- Your **login password** is never stored or transmitted in plaintext
+- Your **VEK** is stored locally only during an active session
+- The server stores only **encrypted blobs** — it cannot decrypt your vault
+- **AES-256-GCM** is used for all encryption (authenticated — detects tampering)
+- **PBKDF2-HMAC-SHA256** with 600,000 iterations for key derivation (NIST recommended minimum)

psamvault-0.1.0/README.md

@@ -0,0 +1,242 @@
+# psamvault
+
+A secure command-line password vault for the terminal.
+
+Your credentials are **encrypted locally** before being sent to the server — the server never sees your plaintext passwords or your encryption key.
+
+---
+
+## How it works
+
+```
+login password
+      │
+      ▼
+HMAC-SHA256 + pepper  →  master password
+                                │
+                                ▼
+              PBKDF2 (600k rounds) + kdf_salt  →  login key
+                                                        │
+                                                        ▼
+                                              decrypt VEK (AES-256-GCM)
+                                                        │
+                                                        ▼
+                                              VEK encrypts every vault entry
+```
+
+- **Pepper** — unique per device, stored in `~/.psamvault/config.env`. Never sent to the server.
+- **VEK (Vault Encryption Key)** — a random 32-byte key generated at signup. Stored encrypted on the server; decrypted locally at login.
+- **kdf_salt** — stored on the server, tied to your account. Ensures two users with the same password get different keys.
+
+---
+
+## Installation
+
+```bash
+pip install psamvault
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/psam-717/psamvault-cli
+cd psamvault-cli/cli
+pip install -e .
+```
+
+---
+
+## Workflow
+
+### 1. Configure
+
+Run this **once** after installing. It generates your pepper and saves the API URL.
+
+```bash
+psamvault configure
+```
+
+```
+ psamvault setup
+
+ Press Enter to accept the default value shown in brackets.
+
+ API URL [https://psam-vault-backend.onrender.com]:
+ Generating a secure pepper for your vault...
+ Configuration saved to ~/.psamvault/config.env
+```
+
+> ⚠️ **Back up `~/.psamvault/config.env`** — it contains your pepper. Losing it means losing access to your vault.
+
+To review your current config:
+
+```bash
+psamvault config-show
+```
+
+---
+
+### 2. Sign up
+
+```bash
+psamvault signup
+```
+
+Creates your account. Your VEK is generated locally, encrypted with your login key, and only the encrypted copy is sent to the server.
+
+Password requirements:
+- At least 8 characters
+- At least one uppercase letter
+- At least one digit
+
+---
+
+### 3. Log in
+
+```bash
+psamvault login
+```
+
+Decrypts your VEK locally using your login password and saves it to a local session file (`~/.psamvault/session.json`). All vault commands use this session — you won't be prompted for your password again until the session expires.
+
+---
+
+### 4. Check who's logged in
+
+```bash
+psamvault whoami
+```
+
+---
+
+## Vault commands
+
+### Add a credential
+
+```bash
+psamvault add github.com --user me@example.com --pass mysecret
+psamvault add github.com --user me@example.com --pass mysecret --notes "2FA enabled"
+psamvault add github.com --user me@example.com   # prompts for password
+```
+
+### Retrieve a credential
+
+```bash
+psamvault get github.com
+psamvault get github.com --copy   # copies password to clipboard, clears after 30s
+```
+
+### List all entries
+
+```bash
+psamvault list
+```
+
+Shows site name, username hint, and last-updated date. Does not decrypt entries.
+
+### Update a credential
+
+```bash
+psamvault update github.com --pass mynewpassword
+psamvault update github.com --user newuser@example.com --pass newpass
+psamvault update github.com --notes "2FA disabled"
+```
+
+### Delete a credential
+
+```bash
+psamvault delete github.com
+```
+
+Permanent — prompts for confirmation first.
+
+### Generate a secure password
+
+```bash
+psamvault generate                          # 20-char password with symbols
+psamvault generate --length 32
+psamvault generate --length 16 --no-symbols
+psamvault generate --length 20 --no-digits
+psamvault generate --save github.com --user me@example.com  # generate and save
+```
+
+Uses Python's `secrets` module (cryptographically secure).
+
+---
+
+## Recovery commands
+
+### Generate recovery codes
+
+Run this while logged in to protect your account against a forgotten password.
+
+```bash
+psamvault generate-codes
+```
+
+Generates **8 one-time recovery codes**. Each code encrypts your VEK — store them somewhere safe. Running this replaces all existing codes.
+
+### Check remaining codes
+
+```bash
+psamvault remaining-codes
+```
+
+### Recover your account (forgotten password)
+
+```bash
+psamvault recover
+```
+
+Use one of your saved recovery codes to reset your login password without losing your vault data. The VEK is recovered and re-wrapped with your new login key — no vault re-encryption needed.
+
+---
+
+## Log out
+
+```bash
+psamvault logout
+```
+
+Revokes the refresh token on the server and deletes the local session file. Your encrypted vault data remains safely on the server.
+
+---
+
+## Command groups
+
+All commands are available at the root level and also under grouped sub-commands:
+
+| Root shorthand | Grouped form |
+|---|---|
+| `psamvault login` | `psamvault auth login` |
+| `psamvault add` | `psamvault vault add` |
+| `psamvault generate-codes` | `psamvault recovery generate-codes` |
+
+Run any group without a subcommand to see its full command table:
+
+```bash
+psamvault auth
+psamvault vault
+psamvault recovery
+```
+
+---
+
+## Configuration files
+
+| File | Purpose |
+|---|---|
+| `~/.psamvault/config.env` | API URL and pepper — **back this up** |
+| `~/.psamvault/session.json` | Active session tokens and decrypted VEK |
+
+Both files are restricted to owner read/write only (`chmod 600`).
+
+---
+
+## Security notes
+
+- Your **login password** is never stored or transmitted in plaintext
+- Your **VEK** is stored locally only during an active session
+- The server stores only **encrypted blobs** — it cannot decrypt your vault
+- **AES-256-GCM** is used for all encryption (authenticated — detects tampering)
+- **PBKDF2-HMAC-SHA256** with 600,000 iterations for key derivation (NIST recommended minimum)