klavex 0.1.0__tar.gz

klavex-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store
+.idea/
+.vscode/

klavex-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

klavex-0.1.0/IMPLEMENTATION.md

@@ -0,0 +1,343 @@
+# Klavex CLI — Implementation Plan
+
+The third repo in the Klavex stack. Sibling to `klavex-frontend` (dashboard) and `klavex-backend` (FastAPI on Lambda).
+
+## Goal
+
+A Python package (`pip install klavex`) that:
+
+1. Logs in through the browser — no passwords typed into a terminal.
+2. Pulls environment variables from a Klavex project/environment the user has access to.
+3. **Injects them into a child process at runtime.** Never writes a `.env` to disk.
+
+This is the load-bearing claim of the product: "no plaintext secrets on disk." The CLI is what makes that claim true at the point of use. If the CLI ever writes secrets to a file by default, the entire pitch collapses.
+
+The replaced workflow:
+
+```bash
+# Before
+cat > .env <<EOF
+DATABASE_URL=postgres://...
+STRIPE_KEY=sk_live_...
+EOF
+npm start
+
+# After
+klavex run -- npm start    # vars exist only in npm's process env
+```
+
+## Naming
+
+| Thing                | Name              |
+| -------------------- | ----------------- |
+| Repo directory       | `klavex-cli`    |
+| Python package       | `klavex`      |
+| PyPI distribution    | `klavex`      |
+| Binary on `$PATH`    | `klavex` (+ `kx` short alias) |
+| Project pinning file | `.klavex`     |
+
+Matches the existing `klavex-*` repo convention while letting the PyPI/CLI surface the product name.
+
+## Stack
+
+| Layer        | Choice                                | Why                                                                          |
+| ------------ | ------------------------------------- | ---------------------------------------------------------------------------- |
+| Python       | 3.10+                                 | Match macOS/Ubuntu LTS defaults; `match` statements + better typing          |
+| CLI framework| `typer`                               | Type-hinted args, auto-help, mature; `click` underneath if we ever need it   |
+| HTTP         | `httpx`                               | Sync API today; async-ready if we add streaming reveals later                |
+| Token store  | `keyring`                             | OS-native: macOS Keychain / Linux Secret Service / Windows Credential Mgr   |
+| Build        | `hatchling` via `pyproject.toml`      | PEP 621 standard, no `setup.py`                                              |
+| Lint/format  | `ruff`                                | Replaces black + flake8 + isort                                              |
+| Tests        | `pytest` + `respx` (httpx mocking)    | Fast, no real network in unit tests                                          |
+| Packaging    | `uv build` then `twine upload`        | `uv` is faster than `python -m build`; output is the same wheel              |
+
+## Repo layout
+
+```
+klavex-cli/
+├── pyproject.toml
+├── README.md                  # User-facing install + usage
+├── IMPLEMENTATION.md          # This file
+├── LICENSE
+├── .gitignore
+├── .python-version            # 3.10
+├── src/
+│   └── klavex/
+│       ├── __init__.py        # __version__
+│       ├── __main__.py        # python -m klavex
+│       ├── cli.py             # typer app entry
+│       ├── auth.py            # browser-callback + device-code flows
+│       ├── api.py             # httpx-based backend client
+│       ├── tokens.py          # keyring read/write, refresh
+│       ├── config.py          # ~/.config/klavex/config.toml + .klavex
+│       ├── inject.py          # subprocess env injection (the core)
+│       ├── errors.py          # typed exceptions → exit codes
+│       └── commands/
+│           ├── __init__.py
+│           ├── login.py
+│           ├── logout.py
+│           ├── whoami.py
+│           ├── projects.py
+│           ├── envs.py
+│           ├── vars.py
+│           ├── run.py         # the headline command
+│           ├── export.py      # opt-in only, prints to stdout with a warning
+│           ├── use.py         # writes .klavex pin file
+│           └── status.py
+└── tests/
+    ├── conftest.py
+    ├── test_auth.py
+    ├── test_inject.py
+    ├── test_config.py
+    └── test_commands/
+        └── ...
+```
+
+## Commands
+
+```
+klavex login                          # browser login, stores token in keychain
+klavex logout                         # delete token from keychain
+klavex whoami                         # show current user + team
+klavex status                         # show login state + active project pin
+
+klavex projects                       # list projects in your team
+klavex envs <project_id|slug>         # list environments in a project
+klavex vars -e <env_id>               # list variable NAMES (no values, ever)
+
+klavex run -e <env_id> -- <cmd...>    # spawn cmd with vars in os.environ
+klavex run -- npm start               # uses .klavex pin
+klavex export -e <env_id>             # PRINT export statements (gated, see below)
+
+klavex use -p <project> -e <env>      # writes .klavex to cwd
+```
+
+`run` is the headline. Everything else exists to support it.
+
+### Why `run` and not `export`
+
+`klavex export | source` is the obvious shortcut, but it leaves the secrets in the parent shell's environment forever — visible to every later command, every other process the shell spawns, every shell history mishap. We support `export` because power users will demand it, but it prints a one-line warning to stderr and is documented as a footgun. The default verb is `run`.
+
+## Auth flow — browser callback (primary)
+
+This is the same pattern `gh auth login --web` and `gcloud auth login` use. Faster UX than device-code when a browser is available.
+
+```
+┌───────────┐                   ┌──────────┐                ┌─────────┐
+│  CLI      │                   │ Browser  │                │ API     │
+└─────┬─────┘                   └────┬─────┘                └────┬────┘
+      │                              │                           │
+   1. Bind 127.0.0.1:<random_port>   │                           │
+      Generate state, code_verifier  │                           │
+      │                              │                           │
+   2. webbrowser.open(                                            │
+        https://app.klavex.dev/cli/authorize                  │
+          ?callback=http://127.0.0.1:PORT                         │
+          &state=...&code_challenge=...&device_name=hostname)     │
+      │ ──────────────────────────► │                            │
+      │                              │  3. User logs in (or is)   │
+      │                              │     already logged in.     │
+      │                              │     Frontend POSTs to:     │
+      │                              │     /cli/exchange          │
+      │                              │ ─────────────────────────► │
+      │                              │                            │
+      │                              │  4. Backend verifies the   │
+      │                              │     dashboard session,     │
+      │                              │     mints a CLI token,     │
+      │                              │     redirects to callback  │
+      │                              │     with ?code=...&state=. │
+      │                              │ ◄───────────────────────── │
+      │                              │                            │
+   5. Local server receives /callback                             │
+      Verifies state, sends:                                      │
+      POST /cli/token                                             │
+        { code, code_verifier }                                   │
+      │ ──────────────────────────────────────────────────────►  │
+      │                                                           │
+   6. { cli_token, expires_at, user, team }                       │
+      │ ◄──────────────────────────────────────────────────────  │
+      │                                                           │
+   7. keyring.set_password("klavex", "default", cli_token)    │
+      Browser tab shows "You can close this tab"                  │
+```
+
+Key properties:
+
+- **PKCE** (RFC 7636). The `code_verifier` never leaves the CLI; the browser only sees a `code_challenge`. So even if the redirect URL is logged somewhere, the auth code alone is useless.
+- **State** parameter. Random per-flow. Defends against the browser opening a stale callback into a fresh CLI invocation.
+- **Loopback only**, port chosen at runtime. No need to register a fixed port; matches OAuth 2.0 for native apps (RFC 8252 §7.3).
+- The local HTTP server serves exactly **one route** (`/callback`), accepts exactly **one request**, then shuts down. Hard 60-second timeout.
+- The CLI token is **distinct from a dashboard session token**. Backend stores it in a new `klavex-cli-tokens` table with `(user_id, device_name, created_at, last_used_at, revoked_at)`. Listing/revoking lives under Settings → CLI in the dashboard.
+
+### Device-code fallback
+
+For headless servers (CI, SSH-only boxes) where `webbrowser.open` can't do anything useful:
+
+```bash
+klavex login --device
+# Visit https://app.klavex.dev/cli/device and enter: ABCD-1234
+# Waiting for confirmation...
+```
+
+Mirrors GitHub's `gh auth login` device flow. Same backend `/cli/device-code` + `/cli/token` (poll) endpoints. Same final token in the keychain.
+
+### Token storage
+
+```python
+# tokens.py
+import keyring
+SERVICE = "klavex"
+
+def store(token: str, profile: str = "default") -> None:
+    keyring.set_password(SERVICE, profile, token)
+
+def load(profile: str = "default") -> str | None:
+    return keyring.get_password(SERVICE, profile)
+```
+
+If `keyring` can't find a backend (rare — usually a stripped-down container), we **refuse to store** and fall back to memory-only auth (token re-issued every CLI invocation). We never silently write the token to a plaintext file. That's the whole product.
+
+The cli token lives until either (a) the backend's expiry (e.g. 90 days idle), (b) the user revokes it from the dashboard, or (c) `klavex logout` clears it locally. Refresh is not needed for the CLI token specifically — it's long-lived but revocable.
+
+## The injection mechanism (`run`)
+
+This is twelve lines of code and the entire reason the product exists.
+
+```python
+# inject.py
+import os, subprocess, sys
+
+def run(env_vars: dict[str, str], argv: list[str]) -> int:
+    if not argv:
+        raise UsageError("Nothing to run. Pass a command after --.")
+    # Child inherits parent env, then overrides with fetched secrets.
+    # Secrets are NEVER written to disk and NEVER appear in the parent shell.
+    child_env = {**os.environ, **env_vars}
+    proc = subprocess.run(argv, env=child_env)
+    return proc.returncode
+```
+
+Notes:
+
+- We `subprocess.run` (not `os.execvpe`) so that we can wrap the call later with telemetry/audit hooks if needed. Exit code is propagated.
+- On POSIX, `argv[0]` is resolved via `$PATH` because we don't pass `shell=True`. So `klavex run -- npm start` works without invoking a shell. **Never use `shell=True`** — it'd let unescaped values in args become shell injection.
+- We **don't** use `os.environ.update()`. The parent CLI process's env stays clean; secrets only exist in the child.
+- We support `--no-inherit` for the paranoid case where you only want the secrets, not your shell's `PATH`/`HOME`/etc. Default is inherit because most apps need `PATH`.
+
+### Project pinning (`.klavex`)
+
+A small TOML file in the project root, like `.nvmrc` or `.python-version`:
+
+```toml
+# .klavex
+project = "proj_a1b2c3d4e5f6"
+default_env = "env_dev_xyz"
+```
+
+`klavex run -- npm start` walks up from cwd looking for `.klavex`, then uses the pinned project + default env. `-e` overrides. Committed to git.
+
+`klavex use -p <project> -e <env>` writes this file.
+
+## Backend client
+
+```python
+# api.py
+import httpx, os
+from .tokens import load
+
+def _client() -> httpx.Client:
+    base = os.environ.get("KLAVEX_API_URL",
+                          "https://<api-gateway-id>.amazonaws.com/api")
+    token = load() or _fail_unauthenticated()
+    return httpx.Client(
+        base_url=base,
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=httpx.Timeout(10.0, connect=5.0),
+    )
+```
+
+Endpoints used (alignment with backend):
+
+| CLI command          | HTTP call                                     |
+| -------------------- | --------------------------------------------- |
+| `login`              | `POST /cli/device-code`, `POST /cli/token`    |
+| `logout`             | `DELETE /cli/tokens/me`                       |
+| `whoami`             | `GET /auth/me`                                |
+| `projects`           | `GET /projects`                               |
+| `envs <p>`           | `GET /projects/{p}/environments`              |
+| `vars -e <e>`        | `GET /environments/{e}/variables` (names only — see below) |
+| `run -e <e>`         | `POST /environments/{e}/variables:reveal`     |
+
+**`POST :reveal` does not exist on the backend yet.** This is STEP-3 backlog item #1 in the frontend repo's `CLAUDE.md`. Today, `GET /environments/{id}/variables` returns plaintext, which the dashboard masks client-side. The CLI **must not ship** against that endpoint — the audit trail would be wrong (no `variable_revealed_cli` action) and there's no IP whitelist enforcement. We block the CLI's release on the backend exposing a real reveal endpoint. See "Backend prerequisites" below.
+
+## Configuration
+
+| Path                                        | Contents                                |
+| ------------------------------------------- | --------------------------------------- |
+| OS keychain (`klavex` service)          | CLI token                               |
+| `~/.config/klavex/config.toml`          | API URL override, default profile, telemetry opt-out |
+| `<project>/.klavex`                     | Per-project pin (committed)             |
+| `$KLAVEX_API_URL` env var               | Override for staging/local              |
+
+Nothing in `config.toml` is sensitive. The keychain is the only place a token lives.
+
+## Errors and exit codes
+
+```
+0    success
+1    generic error
+2    usage error (bad args)
+3    not authenticated
+4    network / API unreachable
+5    permission denied (logged in but no access)
+6    project/env not found
+130  interrupted (Ctrl-C, propagated)
+```
+
+Typed exceptions in `errors.py` map to exit codes in `cli.py`. Each error renders a one-line human message + a `--debug` flag for the full traceback.
+
+## Security checklist
+
+- [ ] Secrets only ever exist in the child process's memory.
+- [ ] Token in OS keychain only. No fallback to plaintext file.
+- [ ] PKCE on the browser flow.
+- [ ] State parameter validated on callback.
+- [ ] Loopback redirect, ephemeral port, single request, 60s timeout.
+- [ ] No `shell=True` in `subprocess` calls.
+- [ ] `export` command warns to stderr that it's a footgun.
+- [ ] CLI token is rate-limited and IP-whitelisted server-side (STEP-3 #2).
+- [ ] Reveal calls write `variable_revealed_cli` audit rows.
+- [ ] `--debug` does not log the token, the bearer header, or any var values.
+- [ ] `httpx` TLS verification on by default; no `verify=False` flag.
+- [ ] Variable values are never written to logs, telemetry, or crash reports.
+
+## Backend prerequisites (blocks CLI v1)
+
+These are all in the frontend's `RECONCILIATION.md` STEP-3 backlog already. Listing here so the CLI is honest about what it depends on:
+
+1. **`/cli/device-code`, `/cli/token` endpoints + `klavex-cli-tokens` table.** STEP-3 #3.
+2. **`/cli/exchange` endpoint** for the browser-callback flow (mints a one-shot code from a logged-in dashboard session).
+3. **`POST /environments/{id}/variables:reveal`** that returns plaintext, runs IP whitelist enforcement, and writes a `variable_revealed_cli` audit row. STEP-3 #1.
+4. **IP whitelist middleware** enforced on the reveal endpoint. STEP-3 #2.
+5. **`/cli/authorize` page in the dashboard** (frontend) — the page the CLI redirects to. Shows "Klavex CLI on `<hostname>` wants to access your account." with Approve/Cancel.
+6. **Settings → CLI Tokens tab** in the dashboard for listing/revoking. STEP-3 #3 again.
+
+## Phasing
+
+**v0.1 — auth only.** `login`, `logout`, `whoami`, `status`. No reveal. Lets us validate the browser flow and token storage end-to-end with minimal backend work.
+
+**v0.2 — read paths.** `projects`, `envs`, `vars` (names only). Confirms the API client + auth middleware story.
+
+**v0.3 — `run`.** Requires the reveal endpoint. The point of the whole project. Ship this and the CLI is useful.
+
+**v0.4 — polish.** `export` (with the footgun warning), `use`, `.klavex` pinning, shell completion (`typer`'s built-in), better error messages.
+
+**v0.5 — distribution.** PyPI publish. Homebrew tap (a small formula that does `pip install klavex` into an isolated venv and symlinks the binary). Docs site link.
+
+## Open questions
+
+1. **Refresh story.** CLI tokens are long-lived (90 days idle). If a token expires mid-`run`, we currently fail with exit 3 and ask the user to re-login. Acceptable? Or do we want silent re-login via a stored refresh token? Storing two tokens means two keychain entries.
+2. **Multiple profiles.** `--profile work` for users who belong to multiple teams under different accounts. Easy to add to `keyring` (it's just a profile-keyed entry). Defer to v0.4.
+3. **Caching.** Do we cache `projects`/`envs` listings? Probably no — they're cheap and freshness matters for permission changes. **Never cache reveal results.**
+4. **Telemetry.** Anonymous CLI version + command name pings, opt-out via `config.toml` and `KLAVEX_NO_TELEMETRY=1`. Decide before v0.5.
+5. **Shell integration.** A future `klavex shell -e dev` that spawns a subshell with vars set, like `aws-vault exec`. Strictly worse than `run` for security but users will ask for it. Defer.

klavex-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: klavex
+Version: 0.1.0
+Summary: Klavex CLI — pull environment variables into a process without writing secrets to disk.
+Author: Klavex
+License: Proprietary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: keyring<26,>=24
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: tomli-w<2.0,>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# klavex
+
+CLI for [Klavex](https://klavex.dev). Pulls environment variables from your team's vault and injects them into a child process — secrets never touch disk.
+
+```bash
+pip install klavex
+klavex login
+klavex run -- npm start
+```
+
+See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for the design.
+
+## Commands
+
+| Command | Status |
+| --- | --- |
+| `klavex login` | v0.1 |
+| `klavex logout` | v0.1 |
+| `klavex whoami` | v0.1 |
+| `klavex status` | v0.1 |
+| `klavex projects` | v0.2 |
+| `klavex envs <project>` | v0.2 |
+| `klavex vars -e <env>` | v0.2 |
+| `klavex run -e <env> -- <cmd>` | v0.3 (blocked on backend reveal endpoint) |
+| `klavex export -e <env>` | v0.4 |
+| `klavex use -p <project> -e <env>` | v0.4 |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+klavex --version
+pytest
+ruff check .
+mypy
+```
+
+Override the API URL for staging or local:
+
+```bash
+export KLAVEX_API_URL=http://localhost:8000
+```

klavex-0.1.0/README.md

@@ -0,0 +1,42 @@
+# klavex
+
+CLI for [Klavex](https://klavex.dev). Pulls environment variables from your team's vault and injects them into a child process — secrets never touch disk.
+
+```bash
+pip install klavex
+klavex login
+klavex run -- npm start
+```
+
+See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for the design.
+
+## Commands
+
+| Command | Status |
+| --- | --- |
+| `klavex login` | v0.1 |
+| `klavex logout` | v0.1 |
+| `klavex whoami` | v0.1 |
+| `klavex status` | v0.1 |
+| `klavex projects` | v0.2 |
+| `klavex envs <project>` | v0.2 |
+| `klavex vars -e <env>` | v0.2 |
+| `klavex run -e <env> -- <cmd>` | v0.3 (blocked on backend reveal endpoint) |
+| `klavex export -e <env>` | v0.4 |
+| `klavex use -p <project> -e <env>` | v0.4 |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+klavex --version
+pytest
+ruff check .
+mypy
+```
+
+Override the API URL for staging or local:
+
+```bash
+export KLAVEX_API_URL=http://localhost:8000
+```

klavex-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "klavex"
+description = "Klavex CLI — pull environment variables into a process without writing secrets to disk."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Klavex" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: Microsoft :: Windows",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dynamic = ["version"]
+dependencies = [
+  "typer>=0.12,<1.0",
+  "httpx>=0.27,<1.0",
+  "keyring>=24,<26",
+  "platformdirs>=4,<5",
+  "tomli>=2.0; python_version < '3.11'",
+  "tomli-w>=1.0,<2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-cov>=5",
+  "respx>=0.21",
+  "ruff>=0.6",
+  "mypy>=1.11",
+]
+
+[project.scripts]
+klavex = "klavex.cli:main"
+kx = "klavex.cli:main"
+
+[tool.hatch.version]
+path = "src/klavex/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/klavex"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E", "F", "W",   # pycodestyle + pyflakes
+  "I",             # isort
+  "B",             # bugbear
+  "UP",            # pyupgrade
+  "SIM",           # simplify
+  "RUF",           # ruff-specific
+]
+ignore = ["E501"]  # line length handled by formatter
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/klavex"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

klavex-0.1.0/src/klavex/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

klavex-0.1.0/src/klavex/__main__.py

@@ -0,0 +1,4 @@
+from klavex.cli import app
+
+if __name__ == "__main__":
+    app()