keystash 0.1.0__tar.gz

keystash-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        exclude:
+          - os: macos-latest
+            python-version: "3.9"
+          - os: windows-latest
+            python-version: "3.9"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+      - name: Lint
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        run: ruff check src tests

keystash-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+# Publishes with PyPI Trusted Publishing (OIDC) — no API token stored.
+# One-time setup on pypi.org: Account settings → Publishing → add a
+# "pending publisher" with:
+#   owner: thu-lawyer, repository: keystash, workflow: publish.yml,
+#   environment: pypi
+# Then run this workflow from the Actions tab (or publish a GitHub release).
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

keystash-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Environments
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# NEVER commit a real vault
+*.keystash
+*.kstash
+vault.enc*

keystash-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thu-lawyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keystash-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: keystash
+Version: 0.1.0
+Summary: Local-first encrypted vault for API keys, tokens and passwords — one file, fuzzy search, env injection, expiry tracking.
+Project-URL: Homepage, https://github.com/thu-lawyer/keystash
+Project-URL: Repository, https://github.com/thu-lawyer/keystash
+Project-URL: Issues, https://github.com/thu-lawyer/keystash/issues
+Project-URL: Changelog, https://github.com/thu-lawyer/keystash/releases
+Author: thu-lawyer
+License: MIT
+License-File: LICENSE
+Keywords: api-key,cli,developer-tools,password,password-manager,secrets,token,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# keystash 🔑
+
+**Local-first encrypted vault for API keys, tokens and passwords — one file, fuzzy search, env injection, expiry tracking.**
+
+Your LLM API keys, cloud tokens and passwords are scattered across `.env` files, shell
+histories and notes apps. `keystash` puts them in **one encrypted file** that you own:
+no server, no account, no subscription. Sync that file with iCloud / Dropbox / SeaDrive /
+Syncthing — it's ciphertext, so syncing it is safe.
+
+```bash
+pip install keystash
+```
+
+## Why keystash
+
+| | keystash | pass / gopass | Bitwarden / 1Password | Infisical / Vault |
+|---|---|---|---|---|
+| Setup | `pip install` + one password | GPG key ceremony | Account + app | Self-host a server |
+| Storage | one encrypted file you own | many GPG files | vendor cloud | server |
+| Offline | ✅ always | ✅ | partial | ❌ |
+| Dev workflow (env injection, `run`) | ✅ built-in | ❌ | ❌ | ✅ (heavy) |
+| Token expiry tracking | ✅ built-in | ❌ | ❌ | enterprise |
+
+## Quick start
+
+```bash
+# 1. Create your vault (encrypted with AES-128-CBC + HMAC, PBKDF2-HMAC-SHA256 600k iters)
+keystash init
+
+# 2. Store a secret
+keystash add openai --secret sk-... --tags llm,prod --expires 2027-01-31 --env-var OPENAI_API_KEY
+
+# 3. Retrieve it
+keystash get openai              # masked preview
+keystash get openai -c           # → clipboard, auto-clears after 30 s
+keystash get openai -q           # raw secret for scripts: export K=$(keystash get openai -q)
+
+# 4. Find things (fuzzy)
+keystash ls                      # everything, expiry warnings included
+keystash ls oprod                # fuzzy: matches openai-prod
+keystash ls --tag llm --json
+
+# 5. Inject secrets into any command — nothing touches your shell or disk
+keystash run -n openai -n anthropic -- python train.py
+keystash run --tag llm -- python train.py
+eval "$(keystash env --tag llm)" # or export them explicitly
+
+# 6. Migrate off plaintext .env files
+keystash import .env             # then delete the .env file
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Create the vault |
+| `add NAME` | Store a secret (`-s` value, `-g LEN` to generate, `-t` tags, `--expires YYYY-MM-DD`, `--env-var`) |
+| `get NAME` | Show (`-r` reveal), copy (`-c`), raw output (`-q`) |
+| `ls [QUERY]` | List / fuzzy search (`--tag`, `--json`) |
+| `edit NAME` | Update any field in place |
+| `rm NAME` | Delete an entry |
+| `gen [LEN]` | Generate a strong secret (`--save NAME` to store it) |
+| `env NAME…` / `--tag` | Print `export` lines for shell eval |
+| `run -n NAME… -- CMD` | Run a command with secrets injected as env vars (`--tag` selects by tag) |
+| `import FILE` | Bulk-import `.env` or JSON |
+| `export` | Export metadata (or secrets with `--with-secrets`) as JSON / dotenv |
+| `status` | Vault health + expired / expiring-soon report |
+
+## Multi-machine sync
+
+The vault is a single encrypted file. Point `KEYSTASH_VAULT` at any synced folder:
+
+```bash
+export KEYSTASH_VAULT="~/CloudStorage/SeaDrive/vault.json"   # or iCloud, Dropbox, …
+```
+
+Each write re-encrypts with a fresh random salt, so last-writer-wins applies —
+prefer one writer per vault at a time, like any sync file.
+
+## Security model
+
+- **Cipher:** Fernet (AES-128-CBC + HMAC-SHA256, encrypt-then-MAC) via `cryptography`.
+- **Key derivation:** PBKDF2-HMAC-SHA256, 600 000 iterations, per-save 128-bit random salt.
+- **File mode:** `0600`; nothing is ever written to disk in plaintext.
+- **Clipboard:** copied secrets are auto-cleared after 30 s (best effort, detached process).
+- **No network.** No telemetry. The CLI is fully offline.
+- Secrets live in process memory only while a command runs; Python cannot guarantee
+  zeroization after exit — the same is true of any CLI in a GC'd language.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `KEYSTASH_VAULT` | Vault file path (also `--vault`) |
+| `KEYSTASH_PASSWORD` | Master password (for scripts/CI; prefer the interactive prompt) |
+
+## Development
+
+```bash
+git clone https://github.com/thu-lawyer/keystash && cd keystash
+uv pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[MIT](LICENSE)

keystash-0.1.0/README.md

@@ -0,0 +1,107 @@
+# keystash 🔑
+
+**Local-first encrypted vault for API keys, tokens and passwords — one file, fuzzy search, env injection, expiry tracking.**
+
+Your LLM API keys, cloud tokens and passwords are scattered across `.env` files, shell
+histories and notes apps. `keystash` puts them in **one encrypted file** that you own:
+no server, no account, no subscription. Sync that file with iCloud / Dropbox / SeaDrive /
+Syncthing — it's ciphertext, so syncing it is safe.
+
+```bash
+pip install keystash
+```
+
+## Why keystash
+
+| | keystash | pass / gopass | Bitwarden / 1Password | Infisical / Vault |
+|---|---|---|---|---|
+| Setup | `pip install` + one password | GPG key ceremony | Account + app | Self-host a server |
+| Storage | one encrypted file you own | many GPG files | vendor cloud | server |
+| Offline | ✅ always | ✅ | partial | ❌ |
+| Dev workflow (env injection, `run`) | ✅ built-in | ❌ | ❌ | ✅ (heavy) |
+| Token expiry tracking | ✅ built-in | ❌ | ❌ | enterprise |
+
+## Quick start
+
+```bash
+# 1. Create your vault (encrypted with AES-128-CBC + HMAC, PBKDF2-HMAC-SHA256 600k iters)
+keystash init
+
+# 2. Store a secret
+keystash add openai --secret sk-... --tags llm,prod --expires 2027-01-31 --env-var OPENAI_API_KEY
+
+# 3. Retrieve it
+keystash get openai              # masked preview
+keystash get openai -c           # → clipboard, auto-clears after 30 s
+keystash get openai -q           # raw secret for scripts: export K=$(keystash get openai -q)
+
+# 4. Find things (fuzzy)
+keystash ls                      # everything, expiry warnings included
+keystash ls oprod                # fuzzy: matches openai-prod
+keystash ls --tag llm --json
+
+# 5. Inject secrets into any command — nothing touches your shell or disk
+keystash run -n openai -n anthropic -- python train.py
+keystash run --tag llm -- python train.py
+eval "$(keystash env --tag llm)" # or export them explicitly
+
+# 6. Migrate off plaintext .env files
+keystash import .env             # then delete the .env file
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Create the vault |
+| `add NAME` | Store a secret (`-s` value, `-g LEN` to generate, `-t` tags, `--expires YYYY-MM-DD`, `--env-var`) |
+| `get NAME` | Show (`-r` reveal), copy (`-c`), raw output (`-q`) |
+| `ls [QUERY]` | List / fuzzy search (`--tag`, `--json`) |
+| `edit NAME` | Update any field in place |
+| `rm NAME` | Delete an entry |
+| `gen [LEN]` | Generate a strong secret (`--save NAME` to store it) |
+| `env NAME…` / `--tag` | Print `export` lines for shell eval |
+| `run -n NAME… -- CMD` | Run a command with secrets injected as env vars (`--tag` selects by tag) |
+| `import FILE` | Bulk-import `.env` or JSON |
+| `export` | Export metadata (or secrets with `--with-secrets`) as JSON / dotenv |
+| `status` | Vault health + expired / expiring-soon report |
+
+## Multi-machine sync
+
+The vault is a single encrypted file. Point `KEYSTASH_VAULT` at any synced folder:
+
+```bash
+export KEYSTASH_VAULT="~/CloudStorage/SeaDrive/vault.json"   # or iCloud, Dropbox, …
+```
+
+Each write re-encrypts with a fresh random salt, so last-writer-wins applies —
+prefer one writer per vault at a time, like any sync file.
+
+## Security model
+
+- **Cipher:** Fernet (AES-128-CBC + HMAC-SHA256, encrypt-then-MAC) via `cryptography`.
+- **Key derivation:** PBKDF2-HMAC-SHA256, 600 000 iterations, per-save 128-bit random salt.
+- **File mode:** `0600`; nothing is ever written to disk in plaintext.
+- **Clipboard:** copied secrets are auto-cleared after 30 s (best effort, detached process).
+- **No network.** No telemetry. The CLI is fully offline.
+- Secrets live in process memory only while a command runs; Python cannot guarantee
+  zeroization after exit — the same is true of any CLI in a GC'd language.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `KEYSTASH_VAULT` | Vault file path (also `--vault`) |
+| `KEYSTASH_PASSWORD` | Master password (for scripts/CI; prefer the interactive prompt) |
+
+## Development
+
+```bash
+git clone https://github.com/thu-lawyer/keystash && cd keystash
+uv pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[MIT](LICENSE)

keystash-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "keystash"
+version = "0.1.0"
+description = "Local-first encrypted vault for API keys, tokens and passwords — one file, fuzzy search, env injection, expiry tracking."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "thu-lawyer" }]
+keywords = [
+  "password",
+  "password-manager",
+  "api-key",
+  "secrets",
+  "vault",
+  "cli",
+  "token",
+  "developer-tools",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "typer>=0.12",
+  "rich>=13.0",
+  "cryptography>=41.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/thu-lawyer/keystash"
+Repository = "https://github.com/thu-lawyer/keystash"
+Issues = "https://github.com/thu-lawyer/keystash/issues"
+Changelog = "https://github.com/thu-lawyer/keystash/releases"
+
+[project.scripts]
+keystash = "keystash.cli:app"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/keystash"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+# Keep Optional[...]/List[...] annotations: typer evaluates them at runtime,
+# where `X | None` would fail on Python 3.9 — so the UP rules must stay off.
+select = ["E4", "E7", "E9", "F", "I", "B", "DTZ"]
+ignore = [
+  "B008",   # typer's Option()/Argument() in defaults is the framework idiom
+  "DTZ011", # local-date semantics are intentional for expiry display
+]

keystash-0.1.0/src/keystash/__init__.py

@@ -0,0 +1,3 @@
+"""keystash — local-first encrypted vault for API keys, tokens and passwords."""
+
+__version__ = "0.1.0"

keystash-0.1.0/src/keystash/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m keystash`."""
+
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()