kv-secrets 0.1.0__tar.gz

kv_secrets-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Test artifacts
+*.db
+*.db-shm
+*.db-wal
+*.log
+
+# Secrets — NEVER commit these
+.env
+.secrets/
+
+# IDE
+.vscode/
+.idea/
+.cursor/
+
+# Server — private (not open source)
+kv_server/
+
+# Reviewer workspace — internal only
+reviewer/
+
+# Deploy artifacts — private
+deploy/

kv_secrets-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kv-secrets contributors
+
+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.

kv_secrets-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: kv-secrets
+Version: 0.1.0
+Summary: Encrypted secrets management for developers and AI agents
+Project-URL: Homepage, https://github.com/sathi/kv-secrets
+Project-URL: Documentation, https://github.com/sathi/kv-secrets#readme
+Project-URL: Issues, https://github.com/sathi/kv-secrets/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,devtools,encryption,mcp,secrets
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: server
+Requires-Dist: aiosqlite>=0.20.0; extra == 'server'
+Requires-Dist: asyncpg>=0.29.0; extra == 'server'
+Requires-Dist: bcrypt>=4.0.0; extra == 'server'
+Requires-Dist: fastapi>=0.110.0; extra == 'server'
+Requires-Dist: python-jose[cryptography]>=3.3.0; extra == 'server'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'server'
+Requires-Dist: stripe>=8.0.0; extra == 'server'
+Requires-Dist: uvicorn>=0.27.0; extra == 'server'

kv_secrets-0.1.0/README.md

@@ -0,0 +1,162 @@
+# kv
+
+Encrypted secrets management for developers and AI coding agents.
+
+**kv** encrypts your API keys, database URLs, and tokens with ChaCha20-Poly1305 — then lets your AI editor (Cursor, Claude Code, VS Code) use them safely through MCP.
+
+```
+pip install kv-secrets
+```
+
+## Why kv?
+
+Your AI coding agent needs your API keys to run and test code. But pasting secrets into chat is dangerous — they end up in logs, training data, and prompt history.
+
+**kv keeps secrets encrypted on disk and injects them only at runtime.** Your AI agent never sees the plaintext values.
+
+## Quick Start
+
+```bash
+# Initialize in your project
+kv init
+
+# Store secrets
+kv set API_KEY sk-live-abc123
+kv set DATABASE_URL postgres://user:pass@host/db
+
+# Run commands with secrets injected
+kv run -- python app.py
+kv run -- npm start
+
+# List keys (values stay hidden)
+kv ls
+```
+
+## MCP Integration (AI Editors)
+
+kv includes an MCP server so Cursor, Claude Code, and VS Code Copilot can manage secrets without ever seeing them.
+
+```bash
+# Auto-configure your editor (one command)
+kv setup cursor
+kv setup claude-code
+kv setup vscode
+```
+
+That's it. Your AI agent now has access to these tools:
+
+| Tool | Profile | What it does |
+|------|---------|-------------|
+| `kv_status` | safe | Check if kv is initialized |
+| `kv_envs` | safe | List environments (dev, staging, prod) |
+| `kv_list` | safe | List secret names (no values) |
+| `kv_run` | safe | Run commands with secrets injected |
+| `kv_set` | mutate | Store a secret (opt-in) |
+| `kv_rm` | mutate | Remove a secret (opt-in) |
+| `kv_get` | reveal | Read a secret value (opt-in) |
+
+**Security profiles** control what your AI can do:
+
+```bash
+# Default: safe only (list + run)
+kv setup cursor
+
+# Allow storing secrets
+kv setup cursor --allow-mutate
+
+# Allow reading values (use with caution)
+kv setup cursor --allow-reveal
+```
+
+## How It Works
+
+```
+You: "run the tests"
+
+AI Agent                          kv
+   |                               |
+   |-- kv_run ["pytest"] --------->|
+   |                               |-- decrypt secrets
+   |                               |-- inject into env
+   |                               |-- subprocess.run(pytest)
+   |                               |-- return exit code only
+   |<-- "exit code: 0" -----------|
+
+Secret values never appear in the chat.
+```
+
+## Encryption
+
+- **Algorithm:** ChaCha20-Poly1305 (AEAD)
+- **Key derivation:** BLAKE2b with environment name as context
+- **Storage:** Binary `.enc` files — safe to commit to git
+- **Master key:** Stored in `.secrets/key` — add to `.gitignore`
+
+## Multi-Environment
+
+```bash
+# Switch environments
+kv env staging
+kv env prod
+
+# Set per-environment secrets
+kv set API_KEY sk-live-prod --env prod
+kv set API_KEY sk-test-dev --env dev
+
+# Run in specific environment
+kv run --env prod -- python deploy.py
+```
+
+## All Commands
+
+```
+kv init          Initialize kv in current project
+kv set KEY VAL   Store an encrypted secret
+kv get KEY       Decrypt and print a secret
+kv ls            List secret names
+kv rm KEY        Remove a secret
+kv run -- CMD    Run command with secrets in env
+kv envs          List environments
+kv env NAME      Switch default environment
+kv export        Export as .env format
+kv import FILE   Import from .env file
+kv status        Show project info
+kv setup EDITOR  Configure MCP for your editor
+kv version       Print version
+```
+
+## Key Sharing
+
+Share the master key with teammates out-of-band (Signal, 1Password, etc.):
+
+```bash
+# Export key as portable string
+kv export-key
+# kvkey_dGhpcyBpcyBhIHRlc3Qga2V5...
+
+# Teammate imports it
+kv import-key kvkey_dGhpcyBpcyBhIHRlc3Qga2V5...
+```
+
+The `.enc` files are safe to commit — without the key, they're just noise.
+
+## Security Model
+
+| What | Where | Safe to share? |
+|------|-------|---------------|
+| `.enc` files | Project dir | Yes (commit to git) |
+| Master key | `.secrets/key` | No (share via secure channel) |
+| Plaintext | Never on disk | N/A |
+
+- Zero-knowledge design — even the cloud sync server (coming soon) never sees plaintext
+- Encrypted blobs are opaque to anyone without the key
+- `kv run` uses `stdout=DEVNULL` — your AI agent only sees exit codes, never output
+
+## Requirements
+
+- Python 3.10+
+- `cryptography` (installed automatically)
+
+## License
+
+MIT

kv_secrets-0.1.0/kv/DESIGN.md

@@ -0,0 +1,139 @@
+# kv — Design Document
+
+## What
+Encrypted secrets management CLI for developers. Local-first, CLI-first, designed to grow into a paid team product.
+
+## Why
+- Dev teams share `.env` files through Slack/email (insecure)
+- dotenvx = encryption only, no team features
+- Doppler = $21/user, cloud-only
+- Vault = overkill for small teams
+- **Gap**: Simple CLI + real encryption + multi-environment + future team sync
+
+## Name Choice: `kv`
+- Two letters, universally understood (key-value)
+- Reads naturally: `kv set`, `kv get`, `kv run`
+- Rejected: `stash` (git collision), `seal` (vague), `crypt` (scary), `vault` (taken)
+
+## Dependency Choice
+- **`cryptography`** (single dependency) — Python stdlib has no symmetric cipher
+- ChaCha20-Poly1305 AEAD — same as WireGuard, TLS 1.3
+- Industry-standard, audited, constant-time
+
+## Encryption Architecture
+- **Master key**: 32 random bytes, stored as base64url in `.secrets/key`
+- **Per-env keys**: Derived via BLAKE2b keyed hash (stdlib) — no per-env key storage
+- **Cipher**: ChaCha20-Poly1305 with 12-byte random nonce + environment name as AAD
+- **Storage**: Entire secrets dict encrypted as single JSON blob (no key name leakage)
+
+## Storage Format
+```
+.secrets/
+  key             # Master key. NEVER committed.
+  config.json     # Project metadata
+  dev.enc         # KV\x00 + version(1) + nonce(12) + ciphertext+tag
+  staging.enc
+  .gitignore      # Auto-generated
+```
+
+## CLI Interface
+```
+kv init                              Initialize project
+kv set KEY=VALUE [-e ENV]            Set a secret
+kv set KEY [-e ENV]                  Set interactively (hidden input)
+kv get KEY [-e ENV]                  Decrypt and print
+kv ls [-e ENV] [--reveal]            List keys
+kv run COMMAND [-e ENV]              Run with secrets injected
+kv export [-e ENV] [-o FILE]         Export as .env
+kv import FILE [-e ENV]              Import .env file
+kv rm KEY [-e ENV]                   Remove a secret
+kv envs                              List environments
+kv env create NAME                   Create environment
+kv env copy SRC DST                  Copy between environments
+kv status                            Project status
+```
+
+## Key Decisions
+1. **Single blob per env** — no key name leakage, atomic reads/writes
+2. **BLAKE2b for key derivation** — master key is high-entropy, no slow KDF needed
+3. **`find_project_root()` walks up dirs** — works from subdirectories (like git)
+4. **Atomic writes** — tmp + `os.replace()` prevents corruption
+5. **`.enc` safe to commit, `key` is not** — enables future git-based team sharing
+
+## Monetization
+- **Free**: Local CLI (12 commands, full encryption, multi-environment)
+- **$15/team/month**: Cloud sync, team management, CI/CD tokens, basic RBAC
+- **$99/team/month**: Rotation automation, advanced RBAC, audit logs
+- Undercuts Doppler ($21/user x 5 = $105/mo) with per-team pricing
+
+## Package Structure
+```
+kv/                       # CLI package
+  __init__.py             # Version
+  __main__.py             # Entry point, Windows fixes
+  cli.py                  # argparse (20 commands), dispatch, ANSI output
+  cli_remote.py           # Remote command handlers (login, push/pull, team, token)
+  crypto.py               # ChaCha20 encrypt/decrypt, BLAKE2b derivation, kvkey_ export/import
+  store.py                # .enc file format, secret CRUD, raw blob read/write, atomic writes
+  env.py                  # Secret injection, .env import/export
+  config.py               # Project init, config.json, find_project_root, sync state
+  auth.py                 # Session management (~/.kv/session.json), auth headers
+  remote.py               # HTTP client (urllib.request), all API calls
+  sync.py                 # Push/pull orchestration, hash computation, conflict detection
+
+kv_server/                # API server package
+  __init__.py             # Version
+  __main__.py             # uvicorn entry (python -m kv_server)
+  app.py                  # FastAPI app factory, CORS, lifespan
+  config.py               # Settings from env vars
+  database.py             # SQLAlchemy models (5 tables), engine, session
+  models.py               # Pydantic request/response schemas
+  auth.py                 # JWT, bcrypt, API token validation
+  billing.py              # Stripe integration (checkout, portal, webhooks)
+  middleware.py            # Rate limiting placeholder
+  routes/
+    __init__.py            # Route registration
+    auth_routes.py         # /auth/register, /auth/login, /auth/refresh
+    sync_routes.py         # /sync/push, /sync/pull, /sync/status
+    team_routes.py         # /team/create, /team/invite, /team/members, /team/revoke
+    token_routes.py        # /tokens/create, /tokens/list, /tokens/revoke
+    billing_routes.py      # /billing/status, /billing/checkout, /billing/portal, /billing/webhook
+```
+
+## Build Status — Local CLI (v0.1)
+- [x] Package entry (__init__, __main__)
+- [x] Encryption engine (crypto.py) — ChaCha20-Poly1305, BLAKE2b derivation, key I/O
+- [x] Project config (config.py) — init, find_project_root, env registry
+- [x] Secret store (store.py) — .enc format, CRUD, atomic writes, tamper detection
+- [x] CLI commands (cli.py) — 12 local commands, ANSI output
+- [x] Env injection + import/export (env.py) — subprocess injection, .env parsing
+- [x] Full test suite — 20/20 local tests passing
+- [x] README.md
+
+## Build Status — Paid Tier (v0.2)
+- [x] Server foundation (kv_server/) — FastAPI, SQLAlchemy, 5 DB tables, JWT auth
+- [x] CLI auth (kv/auth.py) — login/signup/logout, session at ~/.kv/session.json
+- [x] HTTP client (kv/remote.py) — stdlib urllib.request, all API calls
+- [x] Push/pull sync (kv/sync.py) — encrypted blob transfer, hash-based conflict detection
+- [x] Team management — create, invite, members, revoke, kvkey_ key sharing
+- [x] CI/CD tokens — scoped API tokens (pull/push/admin), env restriction, expiry
+- [x] Stripe billing — checkout, portal, webhook handler, trial period
+- [x] CLI commands (cli.py) — expanded to 20 commands total
+- [x] End-to-end test suite — 20/20 integration tests passing
+
+## Paid Tier Architecture
+- **Zero-knowledge**: Server stores raw .enc blobs, never sees plaintext
+- **Auth**: JWT (1h access + 30d refresh) for CLI, API tokens (kvt_...) for CI/CD
+- **Key sharing**: `kvkey_` prefix + base64url master key, shared out-of-band
+- **Sync**: Client reads .enc blob -> base64 -> POST /sync/push, reverse for pull
+- **Conflict resolution**: Last-write-wins with version numbers + blob hashes
+- **Billing**: $15/team/month, 14-day trial, Stripe Checkout + webhooks
+- **Server deps**: fastapi, uvicorn, sqlalchemy[asyncio], aiosqlite, python-jose, bcrypt, stripe
+
+## Gotchas Found During Build
+- `argparse.REMAINDER` field must not collide with subparser `dest` field name — renamed to `cmd`
+- `subprocess.run` needs list args (not joined string) to preserve quoting for `python -c "..."`
+- Optional flags (`-e`, `-q`) MUST come before REMAINDER positional in parser definition
+- passlib + bcrypt compatibility broken on Python 3.12 — use `bcrypt` directly instead
+- SQLite returns naive datetimes — normalize to UTC before comparing with aware datetimes
+- Pydantic `EmailStr` requires `email-validator` package — use plain `str` to avoid extra dep

kv_secrets-0.1.0/kv/README.md

@@ -0,0 +1,175 @@
+# kv
+
+Encrypted secrets management for developers. Set, get, inject — no plaintext `.env` files.
+
+```
+pip install cryptography
+```
+
+```
+python -m kv init
+python -m kv set DATABASE_URL=postgres://localhost/mydb
+python -m kv set API_KEY                          # prompts for value (hidden)
+python -m kv run python app.py                    # secrets injected as env vars
+```
+
+## Why
+
+Teams share `.env` files through Slack and email. That's plaintext secrets in chat logs, email servers, and clipboard history. Existing solutions are either encryption-only (dotenvx), cloud-only and expensive (Doppler at $21/user), or overkill (HashiCorp Vault).
+
+**kv** encrypts secrets locally with ChaCha20-Poly1305 (same cipher as WireGuard and TLS 1.3), supports multiple environments, and injects secrets into any command — all from a two-letter CLI.
+
+## Commands
+
+```
+kv init                              Initialize project
+kv set KEY=VALUE [-e ENV]            Set a secret
+kv set KEY [-e ENV]                  Set interactively (hidden input)
+kv get KEY [-e ENV]                  Decrypt and print a secret
+kv ls [-e ENV] [--reveal]            List secrets (values hidden by default)
+kv rm KEY [-e ENV] [-f]              Remove a secret
+kv run [-e ENV] [-q] COMMAND...      Run command with secrets as env vars
+kv export [-e ENV] [-o FILE]         Export as .env format
+kv import FILE [-e ENV]              Import from .env file
+kv envs                              List all environments
+kv env create NAME                   Create a new environment
+kv env copy SRC DST                  Copy secrets between environments
+kv status                            Project overview
+kv --version                         Print version
+```
+
+### Quick start
+
+```bash
+# Initialize — creates .secrets/ with master key and config
+python -m kv init
+
+# Store secrets
+python -m kv set DATABASE_URL=postgres://localhost:5432/mydb
+python -m kv set STRIPE_KEY=sk_test_abc123
+python -m kv set SESSION_SECRET           # hidden prompt, nothing on screen
+
+# Retrieve
+python -m kv get DATABASE_URL             # prints raw value (pipe-friendly)
+python -m kv ls                           # list keys, values masked
+python -m kv ls --reveal                  # list keys with decrypted values
+
+# Inject into any command
+python -m kv run python app.py
+python -m kv run node server.js
+python -m kv run -e staging python migrate.py
+
+# Multiple environments
+python -m kv set -e staging DATABASE_URL=postgres://staging-host/db
+python -m kv set -e prod DATABASE_URL=postgres://prod-host/db
+python -m kv envs                         # dev, staging, prod
+python -m kv env copy dev staging         # clone secrets across envs
+
+# Import/export
+python -m kv export -o .env               # decrypt to .env file
+python -m kv import legacy.env -e prod    # encrypt from .env file
+
+# Remove
+python -m kv rm API_KEY                   # confirmation prompt
+python -m kv rm API_KEY -f                # skip confirmation
+```
+
+## How it works
+
+### Encryption
+
+- **Cipher**: ChaCha20-Poly1305 AEAD (authenticated encryption with associated data)
+- **Master key**: 32 random bytes generated at `kv init`, stored in `.secrets/key`
+- **Per-environment keys**: Derived from master key via BLAKE2b keyed hash — deterministic, no per-env key storage needed
+- **Nonce**: 12 random bytes per write, prepended to ciphertext
+- **AAD**: Environment name is bound as additional authenticated data — tampering or swapping `.enc` files between environments is detected
+- **Payload**: All secrets for an environment are encrypted as a single JSON blob — key names are never visible without the master key
+
+### Storage
+
+```
+your-project/
+  .secrets/
+    key              Master key (base64url). NEVER commit this.
+    config.json      Project metadata (environments, cipher, version)
+    dev.enc          Encrypted secrets for dev
+    staging.enc      Encrypted secrets for staging
+    prod.enc         Encrypted secrets for prod
+    .gitignore       Auto-generated: ignores key, allows *.enc
+```
+
+The `.gitignore` inside `.secrets/` is auto-configured:
+- `key` is ignored (your master key never enters git)
+- `*.enc` files are allowed (encrypted blobs are safe to commit)
+- `config.json` is allowed (no sensitive data)
+
+This means `.enc` files can live in your repo. Anyone without the `key` file sees binary gibberish. Share the key through a secure channel once — after that, secrets travel with the code.
+
+### Binary format
+
+Each `.enc` file:
+```
+Bytes 0-2:   KV\x00        Magic bytes
+Byte 3:      0x01           Version
+Bytes 4-15:  nonce          12-byte random nonce
+Bytes 16+:   ciphertext     ChaCha20-Poly1305 encrypted payload + 16-byte auth tag
+```
+
+Decrypted payload (JSON):
+```json
+{
+  "_meta": {"updated": "2026-02-18T14:35:00+00:00", "count": 3},
+  "secrets": {
+    "DATABASE_URL": "postgres://localhost/mydb",
+    "API_KEY": "sk-test123",
+    "SESSION_SECRET": "a1b2c3d4"
+  }
+}
+```
+
+## Security model
+
+**What's protected:**
+- Secret values are encrypted at rest with a 256-bit key
+- Secret key names are encrypted (single-blob-per-env design)
+- Environment isolation — per-env derived keys, AAD binding
+- Tamper detection — Poly1305 authentication tag catches any modification
+- Atomic writes — tmp file + `os.replace()` prevents partial writes on crash
+
+**What's NOT protected (yet):**
+- The master key in `.secrets/key` is plaintext on disk (protected by file permissions, `.gitignore`)
+- No access control — anyone with the key can read/write all environments
+- No audit log — no record of who changed what
+- No key rotation — changing the master key requires re-encrypting everything manually
+
+These are the features that make up the paid team tier (cloud sync, RBAC, audit logs, rotation).
+
+## Architecture
+
+```
+kv/
+  __init__.py     Package version
+  __main__.py     Entry point (python -m kv), Windows terminal fixes
+  crypto.py       ChaCha20-Poly1305 encrypt/decrypt, BLAKE2b key derivation
+  store.py        SecretStore class, .enc binary format, atomic CRUD
+  config.py       Project init, find_project_root(), environment registry
+  cli.py          argparse commands, ANSI-colored output
+  env.py          Subprocess injection, .env import/export
+```
+
+**Single dependency**: `cryptography` (for ChaCha20-Poly1305). Everything else is stdlib.
+
+## Platform
+
+Works on Windows, macOS, and Linux. Tested primarily on Windows with PowerShell.
+
+Run from any subdirectory — `kv` walks up the directory tree to find `.secrets/` (like `git` finds `.git/`).
+
+```powershell
+# From project root
+python -m kv set FOO=bar
+
+# From a subdirectory — still works
+cd src/
+python -m kv get FOO    # finds .secrets/ in parent
+```

kv_secrets-0.1.0/kv/__init__.py

@@ -0,0 +1,2 @@
+"""kv — encrypted secrets management for developers."""
+__version__ = "0.1.0"

kv_secrets-0.1.0/kv/__main__.py

@@ -0,0 +1,16 @@
+"""Entry point for python -m kv."""
+
+import os
+import sys
+
+# Windows terminal setup
+if os.name == "nt":
+    os.system("")  # enable ANSI escape codes
+    for stream in (sys.stdout, sys.stderr, sys.stdin):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

kv_secrets-0.1.0/kv/auth.py

@@ -0,0 +1,93 @@
+"""Authentication for kv CLI.
+
+Manages user sessions, login/signup flows, and token storage.
+Session stored at ~/.kv/session.json (per-user, not per-project).
+"""
+
+import json
+import os
+
+
+SESSION_DIR = ".kv"
+SESSION_FILE = "session.json"
+
+# Default server URL — overridden by KV_API_URL env var
+DEFAULT_API_URL = "http://127.0.0.1:8000"
+
+
+def get_user_config_dir():
+    """Get ~/.kv/ directory, create if needed."""
+    home = os.path.expanduser("~")
+    d = os.path.join(home, SESSION_DIR)
+    os.makedirs(d, exist_ok=True)
+    # Restrict permissions on Unix (owner-only access)
+    if os.name != "nt":
+        os.chmod(d, 0o700)
+    return d
+
+
+def session_path():
+    """Full path to session.json."""
+    return os.path.join(get_user_config_dir(), SESSION_FILE)
+
+
+def load_session():
+    """Load the current session, or None if not logged in."""
+    path = session_path()
+    if not os.path.isfile(path):
+        return None
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_session(session):
+    """Write session to disk."""
+    path = session_path()
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(session, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+    # Restrict permissions on Unix (owner-only read/write)
+    if os.name != "nt":
+        os.chmod(path, 0o600)
+
+
+def delete_session():
+    """Remove session file (logout)."""
+    path = session_path()
+    if os.path.isfile(path):
+        os.remove(path)
+
+
+def get_api_url():
+    """Get the API server URL."""
+    session = load_session()
+    if session and session.get("api_url"):
+        return session["api_url"]
+    return os.environ.get("KV_API_URL", DEFAULT_API_URL)
+
+
+def get_auth_headers():
+    """Get Authorization headers from session or KV_TOKEN env var.
+
+    Returns dict with Authorization header, or empty dict.
+    """
+    # CI/CD token takes priority
+    env_token = os.environ.get("KV_TOKEN")
+    if env_token:
+        return {"Authorization": f"Token {env_token}"}
+
+    session = load_session()
+    if session and session.get("token"):
+        return {"Authorization": f"Bearer {session['token']}"}
+
+    return {}
+
+
+def require_session():
+    """Get current session or raise with helpful message."""
+    session = load_session()
+    if not session:
+        raise RuntimeError("not logged in — run 'python -m kv login' first")
+    return session