hushvault-cli 0.1.0__py3-none-any.whl

hushvault_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: hushvault-cli
+Version: 0.1.0
+Summary: A zero-dependency secrets manager built entirely from the Python standard library
+Author: Pranav Salian
+Project-URL: Repository, https://github.com/Pranav-s-salian/Vault-ai
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Vault
+
+A zero-dependency secrets manager. Everything is built from the Python
+standard library — no `requirements.txt`, no pip packages. See
+[STDLIB.md](STDLIB.md) for exactly which stdlib modules replace which
+third-party packages, and [THREAT_MODEL.md](THREAT_MODEL.md) for what
+Vault does and does not protect against.
+
+## Installation
+
+Nothing beyond Python 3.10+ is required — clone the repository, then run
+the installer for your OS:
+
+macOS/Linux:
+
+```sh
+chmod +x install.sh && ./install.sh
+```
+
+Windows:
+
+```
+install.bat
+```
+
+After installing, `vault` works as a plain command from any directory —
+no need to `cd` into the repo or type `python -m vault` — for example:
+
+```
+vault init
+vault set KEY value
+vault run -- your-command
+vault ui
+```
+
+### macOS
+
+`install.sh` creates a wrapper at `/usr/local/bin/vault` (using `sudo`
+only if that directory isn't already writable by you). The master key is
+stored in the macOS Keychain (service `vault-cli`, account `master-key`)
+via the built-in `security` command-line tool.
+
+### Windows
+
+`install.bat` creates `vault.bat` in this project folder and, if the
+folder isn't already on your `PATH`, adds it there via `setx` — reopen
+your terminal afterward for that change to take effect. The master key is
+stored, DPAPI-encrypted, at `%APPDATA%\vault-cli\master.key`. DPAPI ties
+the encryption to your Windows user account, so only that account can
+decrypt it.
+
+### Running without installing
+
+You can also run Vault directly from the repo without installing a global
+command — `./run.sh init` (macOS/Linux) or `python -m vault init`
+(Windows), from inside the project directory.
+
+## CLI commands
+
+All commands operate on the vault file at `~/.vault/secrets.json` by
+default.
+
+### `vault init`
+
+Generate a new 32-byte master key and store it in the OS keychain.
+
+```
+$ vault init
+vault initialized — master key stored in the OS keychain
+```
+
+### `vault set KEY VALUE`
+
+Encrypt and store a secret.
+
+```
+$ vault set DB_PASSWORD hunter2
+stored 'DB_PASSWORD'
+```
+
+### `vault get KEY`
+
+Decrypt and print a secret's value. A warning is printed to stderr first,
+since the value will appear in your terminal (and possibly shell
+history).
+
+```
+$ vault get DB_PASSWORD
+warning: printing a secret to the terminal may be recorded in your shell history
+hunter2
+```
+
+### `vault list`
+
+List secret names only — values are never shown.
+
+```
+$ vault list
+DB_PASSWORD
+TEST_KEY
+```
+
+### `vault delete KEY`
+
+Remove a secret.
+
+```
+$ vault delete DB_PASSWORD
+deleted 'DB_PASSWORD'
+```
+
+### `vault run -- COMMAND...`
+
+Decrypt every secret, inject them into the environment alongside the rest
+of `os.environ`, and run `COMMAND`. Decrypted values live only in memory
+for the duration of the subprocess.
+
+```
+$ vault run -- python3 -c "import os; print(os.environ['TEST_KEY'])"
+hello123
+```
+
+### `vault ui`
+
+Launch the local web UI (see below).
+
+```
+$ vault ui
+vault UI running at http://127.0.0.1:52341/?token=<random-token>
+press Ctrl+C to stop
+```
+
+## The UI
+
+`vault ui` starts a local HTTP server bound to `127.0.0.1` only (never
+`0.0.0.0`), generates a random session token, and opens your browser to
+the vault page with that token pre-filled in the URL. Every API request
+must include the same token or it is rejected with `403`.
+
+From the page you can:
+
+- see a table of secret names (values are hidden by default),
+- add a new secret via the form,
+- click **Reveal** to briefly show a secret's value (it re-hides itself
+  after a few seconds),
+- click **Delete** to remove a secret.
+
+No frameworks, no build step, no external CDN — the whole UI is one
+static `index.html` with inline `<style>` and `<script>`, served by
+`http.server` from the stdlib.

hushvault_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+vault/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vault/__main__.py,sha256=GXj0jsKoHwK_oG8_lNstlIqvDRDM2watruECr-WKsK8,88
+vault/cipher.py,sha256=WYAdX6eFxJcpn8etmsD-_K7at_afP8mgswUX6IMqMMY,5474
+vault/cli.py,sha256=36VHgdbVY-Hwu0jFuJU4ijaz9O6aYBZPGT4bV8q_sU4,6156
+vault/keychain.py,sha256=sbgSBe6uflaCV7ospkLZYXi1MbYQzSuhWVwPzxWvWKQ,3963
+vault/runner.py,sha256=R9f_3ON24gcZCUJoFso0uOoBf-F_DSX9AGA327L8nMw,880
+vault/store.py,sha256=OCNm2S3MEpoCMgZQSk2u1Y_cE9lGGg1856Nnf4TLNQA,1947
+vault/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vault/ui/server.py,sha256=9PispW3TzkJszea38xMRHXhQ6kdmJYnWkaomT8PGO7Y,5136
+vault/ui/static/index.html,sha256=2FZmK9UguMmbQBUm83z-qjUoJy2JtcSt9R3DvkXNf0I,14289
+hushvault_cli-0.1.0.dist-info/METADATA,sha256=TfnWbwFrfRrparQo9rcjyNyHAE09OY8ufy4p1zH-hjY,4165
+hushvault_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hushvault_cli-0.1.0.dist-info/entry_points.txt,sha256=10OpHfWkme8X-4t0O_3Zjfd2BfmUkxGqBBL2hbl6w1g,41
+hushvault_cli-0.1.0.dist-info/top_level.txt,sha256=9e6d_YtmUyWnk8SQbezOngdSMUxhE38mT8uUTWox24o,6
+hushvault_cli-0.1.0.dist-info/RECORD,,

hushvault_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hushvault_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vault = vault.cli:main

hushvault_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vault

vault/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from vault.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

vault/cipher.py

@@ -0,0 +1,150 @@
+"""
+vault/cipher.py — Encryption engine for Vault CLI.
+
+Zero third-party dependencies. Uses only Python stdlib:
+    hashlib, hmac, secrets, base64
+
+Design:
+    HMAC-derived keystream (CTR-mode analogue) + encrypt-then-MAC.
+    Two domain-separated keys are derived per operation — one for
+    encryption, one for authentication — so the two operations can
+    never interfere.
+
+    The nonce is ALWAYS generated internally by encrypt(); callers
+    never supply it. Reusing a nonce with the same key would break
+    the entire scheme.
+"""
+
+import base64
+import hashlib
+import hmac
+import secrets
+
+
+# ---------------------------------------------------------------------------
+# Key derivation
+# ---------------------------------------------------------------------------
+
+def derive_keys(master_key: bytes, nonce: bytes) -> tuple[bytes, bytes]:
+    """
+    Derive two domain-separated 32-byte keys from master_key + nonce.
+
+    Returns:
+        (enc_key, mac_key)
+        enc_key  — used only to produce the encryption keystream
+        mac_key  — used only to compute / verify the authentication tag
+    """
+    enc_key = hmac.new(master_key, b"encrypt" + nonce, hashlib.sha256).digest()
+    mac_key = hmac.new(master_key, b"auth"    + nonce, hashlib.sha256).digest()
+    return enc_key, mac_key
+
+
+# ---------------------------------------------------------------------------
+# Keystream generation
+# ---------------------------------------------------------------------------
+
+def generate_keystream(enc_key: bytes, nonce: bytes, length: int) -> bytes:
+    """
+    Produce `length` pseudo-random bytes using HMAC-SHA256 in counter mode.
+
+    Each 32-byte block is HMAC(enc_key, nonce || counter).
+    Blocks are concatenated and truncated to exactly `length` bytes.
+
+    Args:
+        enc_key: 32-byte derived encryption key
+        nonce:   per-encrypt random value
+        length:  number of keystream bytes required (may be 0)
+
+    Returns:
+        Exactly `length` bytes of keystream.
+    """
+    output: bytes = b""
+    counter: int = 0
+    while len(output) < length:
+        block = hmac.new(
+            enc_key,
+            nonce + counter.to_bytes(4, "big"),
+            hashlib.sha256,
+        ).digest()
+        output += block
+        counter += 1
+    return output[:length]
+
+
+# ---------------------------------------------------------------------------
+# Encrypt
+# ---------------------------------------------------------------------------
+
+def encrypt(master_key: bytes, plaintext: bytes) -> dict:
+    """
+    Encrypt `plaintext` under `master_key`.
+
+    Generates a fresh random nonce on every call — nonces are NEVER
+    reused even if the same key and plaintext are supplied twice.
+
+    Returns a dict with three base64-encoded string fields:
+        "nonce"      — 16-byte random value used for this operation
+        "ciphertext" — XOR of plaintext with the keystream
+        "tag"        — HMAC-SHA256 over (nonce || ciphertext), for integrity
+
+    The tag is computed over the *ciphertext* (encrypt-then-MAC), which
+    means tampered bytes are detected before any decryption occurs.
+    """
+    # Fresh nonce every call — this is non-negotiable.
+    nonce: bytes = secrets.token_bytes(16)
+
+    enc_key, mac_key = derive_keys(master_key, nonce)
+
+    keystream: bytes = generate_keystream(enc_key, nonce, len(plaintext))
+    ciphertext: bytes = bytes(p ^ k for p, k in zip(plaintext, keystream))
+
+    # Authenticate nonce + ciphertext so that any tampering is detected.
+    tag: bytes = hmac.new(mac_key, nonce + ciphertext, hashlib.sha256).digest()
+
+    return {
+        "nonce":      base64.b64encode(nonce).decode(),
+        "ciphertext": base64.b64encode(ciphertext).decode(),
+        "tag":        base64.b64encode(tag).decode(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Decrypt
+# ---------------------------------------------------------------------------
+
+def decrypt(master_key: bytes, blob: dict) -> bytes:
+    """
+    Decrypt a blob produced by encrypt().
+
+    The tag is verified with a constant-time comparison BEFORE any
+    decryption happens. If the tag is wrong (tampered ciphertext, wrong
+    key, corrupted data) a ValueError is raised immediately and no
+    plaintext — not even a partial byte — is returned.
+
+    Args:
+        master_key: same key that was passed to encrypt()
+        blob:       dict with "nonce", "ciphertext", "tag" keys
+
+    Returns:
+        Original plaintext bytes.
+
+    Raises:
+        ValueError: if the integrity check fails for any reason.
+        KeyError:   if the blob is missing a required field.
+    """
+    nonce:      bytes = base64.b64decode(blob["nonce"])
+    ciphertext: bytes = base64.b64decode(blob["ciphertext"])
+    tag:        bytes = base64.b64decode(blob["tag"])
+
+    enc_key, mac_key = derive_keys(master_key, nonce)
+
+    # Verify integrity first — constant-time to avoid timing attacks.
+    expected_tag: bytes = hmac.new(
+        mac_key, nonce + ciphertext, hashlib.sha256
+    ).digest()
+
+    if not hmac.compare_digest(tag, expected_tag):
+        raise ValueError("tampered or corrupted data — refusing to decrypt")
+
+    keystream: bytes = generate_keystream(enc_key, nonce, len(ciphertext))
+    return bytes(c ^ k for c, k in zip(ciphertext, keystream))

vault/cli.py

@@ -0,0 +1,192 @@
+"""
+vault/cli.py — Command-line interface for Vault.
+
+Subcommands:
+    vault init
+    vault set KEY VALUE
+    vault get KEY
+    vault list
+    vault delete KEY
+    vault run -- COMMAND...
+    vault ui
+"""
+
+import argparse
+import pathlib
+import sys
+
+from vault import keychain, store
+from vault.runner import run_with_secrets
+
+DEFAULT_VAULT_PATH = pathlib.Path.home() / ".vault" / "secrets.json"
+
+KNOWN_COMMANDS = ["init", "set", "get", "list", "delete", "run", "ui"]
+
+BOLD = "\033[1m"
+CYAN = "\033[36m"
+RESET = "\033[0m"
+
+
+def _use_color() -> bool:
+    return sys.stdout.isatty()
+
+
+def _supports_unicode_box() -> bool:
+    encoding = getattr(sys.stdout, "encoding", None) or ""
+    try:
+        "┌─┐│└┘—".encode(encoding)
+        return True
+    except (UnicodeEncodeError, LookupError):
+        return False
+
+
+def print_menu() -> None:
+    """Print the friendly no-args / --help welcome screen."""
+    bold = BOLD if _use_color() else ""
+    cyan = CYAN if _use_color() else ""
+    reset = RESET if _use_color() else ""
+    unicode_ok = _supports_unicode_box()
+
+    dash = "─" if unicode_ok else "-"
+    top_left, top_right = ("┌", "┐") if unicode_ok else ("+", "+")
+    bottom_left, bottom_right = ("└", "┘") if unicode_ok else ("+", "+")
+    side = "│" if unicode_ok else "|"
+    em_dash = "—" if unicode_ok else "-"
+
+    title = f"VAULT {em_dash} zero-dependency secrets manager"
+    inner_width = len(title) + 4  # 2 spaces of padding on each side
+    print(f"{bold}{top_left}{dash * inner_width}{top_right}{reset}")
+    print(f"{bold}{side}  {title}  {side}{reset}")
+    print(f"{bold}{bottom_left}{dash * inner_width}{bottom_right}{reset}")
+    print()
+    print("Usage: vault <command> [arguments]")
+    print()
+    print("Commands:")
+    commands = [
+        ("init", "", "Set up the vault and generate a master key"),
+        ("set", "<key> <value>", "Store a new secret"),
+        ("get", "<key>", "Retrieve a secret's value"),
+        ("list", "", "List all stored secret names"),
+        ("delete", "<key>", "Remove a secret"),
+        ("run", "-- <command>", "Run a command with secrets injected as env vars"),
+        ("ui", "", "Launch the local dashboard in your browser"),
+    ]
+    for name, args_str, desc in commands:
+        label = f"{name} {args_str}".rstrip()
+        print(f"  {cyan}{label:<21}{reset} {desc}")
+    print()
+    print("Examples:")
+    print("  vault init")
+    print("  vault set API_KEY sk_live_abc123")
+    print("  vault run -- python app.py")
+    print("  vault ui")
+    print()
+    print("Run 'vault <command> --help' for details on a specific command.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="vault", description="Zero-dependency secrets manager")
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+
+    subparsers.add_parser("init", help="generate and store a new master key")
+
+    set_parser = subparsers.add_parser("set", help="store a secret")
+    set_parser.add_argument("name")
+    set_parser.add_argument("value")
+
+    get_parser = subparsers.add_parser("get", help="retrieve a secret")
+    get_parser.add_argument("name")
+
+    subparsers.add_parser("list", help="list secret names")
+
+    delete_parser = subparsers.add_parser("delete", help="remove a secret")
+    delete_parser.add_argument("name")
+
+    run_parser = subparsers.add_parser("run", help="run a command with secrets injected as env vars")
+    run_parser.add_argument("command", nargs=argparse.REMAINDER)
+
+    subparsers.add_parser("ui", help="launch the local web UI")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    if len(argv) == 0 or argv[0] in ("-h", "--help"):
+        print_menu()
+        return 0
+
+    if argv[0] not in KNOWN_COMMANDS:
+        print(f"error: '{argv[0]}' is not a recognized vault command\n", file=sys.stderr)
+        print_menu()
+        return 1
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.subcommand == "init":
+            keychain.init_master_key()
+            print("vault initialized — master key stored in the OS keychain")
+            return 0
+
+        if args.subcommand == "set":
+            master_key = keychain.get_master_key()
+            store.set_secret(DEFAULT_VAULT_PATH, master_key, args.name, args.value)
+            print(f"stored '{args.name}'")
+            return 0
+
+        if args.subcommand == "get":
+            master_key = keychain.get_master_key()
+            value = store.get_secret(DEFAULT_VAULT_PATH, master_key, args.name)
+            print(
+                "warning: printing a secret to the terminal may be recorded in your "
+                "shell history",
+                file=sys.stderr,
+            )
+            print(value)
+            return 0
+
+        if args.subcommand == "list":
+            for name in store.list_secrets(DEFAULT_VAULT_PATH):
+                print(name)
+            return 0
+
+        if args.subcommand == "delete":
+            store.delete_secret(DEFAULT_VAULT_PATH, args.name)
+            print(f"deleted '{args.name}'")
+            return 0
+
+        if args.subcommand == "run":
+            command = args.command
+            # argparse.REMAINDER keeps a leading "--" if present; strip it.
+            if command and command[0] == "--":
+                command = command[1:]
+            if not command:
+                print("error: no command given to `vault run`", file=sys.stderr)
+                return 1
+            master_key = keychain.get_master_key()
+            return run_with_secrets(DEFAULT_VAULT_PATH, master_key, command)
+
+        if args.subcommand == "ui":
+            from vault.ui.server import serve
+            serve(DEFAULT_VAULT_PATH)
+            return 0
+
+    except KeyError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except RuntimeError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

vault/keychain.py

@@ -0,0 +1,132 @@
+"""
+vault/keychain.py — OS-native master key storage.
+
+The 32-byte master key never touches the vault's own JSON file. Instead it
+is handed off to the operating system's native secret storage:
+
+    macOS   -> Keychain, via the `security` CLI (generic password item).
+    Windows -> DPAPI, via PowerShell's SecureString cmdlets. The DPAPI
+               ciphertext (bound to the current Windows user account) is
+               written to a file under %APPDATA%/vault-cli/master.key.
+
+Only stdlib (subprocess, platform, secrets, pathlib, os) is used — no
+third-party keyring library.
+"""
+
+import os
+import pathlib
+import platform
+import secrets
+import subprocess
+
+SERVICE_NAME = "vault-cli"
+ACCOUNT_NAME = "master-key"
+
+
+def _windows_key_path() -> pathlib.Path:
+    appdata = os.environ.get("APPDATA")
+    base = pathlib.Path(appdata) if appdata else pathlib.Path.home() / "AppData" / "Roaming"
+    return base / "vault-cli" / "master.key"
+
+
+def _init_macos(key_hex: str) -> None:
+    # -U allows updating an existing item instead of failing if one exists.
+    subprocess.run(
+        [
+            "security", "add-generic-password",
+            "-s", SERVICE_NAME,
+            "-a", ACCOUNT_NAME,
+            "-w", key_hex,
+            "-U",
+        ],
+        check=True,
+        capture_output=True,
+    )
+
+
+def _get_macos() -> str:
+    result = subprocess.run(
+        [
+            "security", "find-generic-password",
+            "-s", SERVICE_NAME,
+            "-a", ACCOUNT_NAME,
+            "-w",
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip()
+
+
+def _init_windows(key_hex: str) -> None:
+    key_path = _windows_key_path()
+    key_path.parent.mkdir(parents=True, exist_ok=True)
+
+    script = (
+        "$secure = ConvertTo-SecureString -String $env:VAULT_MASTER_KEY_HEX "
+        "-AsPlainText -Force; "
+        "ConvertFrom-SecureString -SecureString $secure "
+        f"| Set-Content -Path '{key_path}' -Encoding ASCII"
+    )
+    env = dict(os.environ)
+    env["VAULT_MASTER_KEY_HEX"] = key_hex
+    subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+        check=True,
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+def _get_windows() -> str:
+    key_path = _windows_key_path()
+    if not key_path.exists():
+        raise RuntimeError("vault not initialized — run `vault init` first")
+
+    script = (
+        f"$encrypted = Get-Content -Path '{key_path}' -Encoding ASCII; "
+        "$secure = ConvertTo-SecureString -String $encrypted; "
+        "$bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure); "
+        "[System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)"
+    )
+    result = subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", script],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip()
+
+
+def init_master_key() -> bytes:
+    """Generate a fresh 32-byte master key and store it in the OS keychain."""
+    key = secrets.token_bytes(32)
+    key_hex = key.hex()
+
+    system = platform.system()
+    if system == "Darwin":
+        _init_macos(key_hex)
+    elif system == "Windows":
+        _init_windows(key_hex)
+    else:
+        raise NotImplementedError(f"vault keychain support is not implemented for '{system}'")
+
+    return key
+
+
+def get_master_key() -> bytes:
+    """Retrieve the master key previously stored by init_master_key()."""
+    system = platform.system()
+    if system == "Darwin":
+        try:
+            key_hex = _get_macos()
+        except subprocess.CalledProcessError:
+            raise RuntimeError("vault not initialized — run `vault init` first")
+    elif system == "Windows":
+        key_hex = _get_windows()
+    else:
+        raise NotImplementedError(f"vault keychain support is not implemented for '{system}'")
+
+    return bytes.fromhex(key_hex)

vault/runner.py

@@ -0,0 +1,28 @@
+"""
+vault/runner.py — Run a subprocess with vault secrets injected into its
+environment.
+
+Decrypted secret values exist only as local variables for the duration of
+this call; they are never written to a file or logged, and the dict holding
+them goes out of scope as soon as the subprocess finishes.
+"""
+
+import os
+import pathlib
+import subprocess
+
+from vault.store import list_secrets, get_secret
+
+
+def run_with_secrets(vault_path: pathlib.Path, master_key: bytes, command: list[str]) -> int:
+    """Decrypt every secret in the vault, merge into the environment, and
+    run `command`. Returns the subprocess's exit code."""
+    decrypted = {
+        name: get_secret(vault_path, master_key, name)
+        for name in list_secrets(vault_path)
+    }
+
+    merged_env = {**os.environ, **decrypted}
+
+    result = subprocess.run(command, env=merged_env)
+    return result.returncode

vault/store.py

@@ -0,0 +1,61 @@
+"""
+vault/store.py — Vault file storage layer.
+
+Loads and saves the vault's JSON file on disk, and provides secret-level
+operations (set/get/list/delete) built on top of vault/cipher.py.
+
+Vault file format:
+    {
+        "SECRET_NAME": {"nonce": "...", "ciphertext": "...", "tag": "..."},
+        ...
+    }
+"""
+
+import json
+import pathlib
+
+from vault.cipher import decrypt, encrypt
+
+
+def load_vault(path: pathlib.Path) -> dict:
+    """Load the vault JSON file. Returns {} if it doesn't exist."""
+    if not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_vault(path: pathlib.Path, data: dict) -> None:
+    """Write the vault as pretty-printed JSON, creating parent dirs if needed."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, sort_keys=True)
+
+
+def set_secret(path: pathlib.Path, master_key: bytes, name: str, value: str) -> None:
+    """Encrypt `value` and store it under `name`."""
+    data = load_vault(path)
+    data[name] = encrypt(master_key, value.encode("utf-8"))
+    save_vault(path, data)
+
+
+def get_secret(path: pathlib.Path, master_key: bytes, name: str) -> str:
+    """Decrypt and return the value stored under `name`."""
+    data = load_vault(path)
+    if name not in data:
+        raise KeyError(f"no secret named '{name}' in vault")
+    return decrypt(master_key, data[name]).decode("utf-8")
+
+
+def list_secrets(path: pathlib.Path) -> list[str]:
+    """Return the names of all secrets in the vault — never their values."""
+    return sorted(load_vault(path).keys())
+
+
+def delete_secret(path: pathlib.Path, name: str) -> None:
+    """Remove the entry named `name`. Raises KeyError if it doesn't exist."""
+    data = load_vault(path)
+    if name not in data:
+        raise KeyError(f"no secret named '{name}' in vault")
+    del data[name]
+    save_vault(path, data)

vault/ui/server.py

@@ -0,0 +1,139 @@
+"""
+vault/ui/server.py — Local web UI for Vault.
+
+Uses only http.server from the stdlib (no Flask, no other framework).
+Binds to 127.0.0.1 only. A random per-session token, generated at startup,
+must be supplied on every API request (query param `token` or header
+`X-Vault-Token`) or the request is rejected with 403.
+"""
+
+import json
+import pathlib
+import secrets
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from vault import keychain, store
+
+STATIC_DIR = pathlib.Path(__file__).parent / "static"
+HOST = "127.0.0.1"
+
+
+def _make_handler(vault_path: pathlib.Path, master_key: bytes, token: str):
+    class Handler(BaseHTTPRequestHandler):
+        def _check_token(self) -> bool:
+            parsed = urlparse(self.path)
+            query = parse_qs(parsed.query)
+            supplied = query.get("token", [None])[0] or self.headers.get("X-Vault-Token")
+            return supplied == token
+
+        def _send_json(self, status: int, payload) -> None:
+            body = json.dumps(payload).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def _read_json_body(self) -> dict:
+            length = int(self.headers.get("Content-Length", 0))
+            raw = self.rfile.read(length) if length else b"{}"
+            return json.loads(raw.decode("utf-8"))
+
+        def do_GET(self):
+            parsed = urlparse(self.path)
+
+            if parsed.path == "/":
+                index_html = (STATIC_DIR / "index.html").read_text(encoding="utf-8")
+                body = index_html.encode("utf-8")
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+                return
+
+            if parsed.path == "/api/keys":
+                if not self._check_token():
+                    self._send_json(403, {"error": "invalid or missing token"})
+                    return
+                self._send_json(200, store.list_secrets(vault_path))
+                return
+
+            self._send_json(404, {"error": "not found"})
+
+        def do_POST(self):
+            parsed = urlparse(self.path)
+
+            if not self._check_token():
+                self._send_json(403, {"error": "invalid or missing token"})
+                return
+
+            if parsed.path == "/api/keys":
+                try:
+                    payload = self._read_json_body()
+                    name, value = payload["name"], payload["value"]
+                except (json.JSONDecodeError, KeyError):
+                    self._send_json(400, {"error": "expected JSON body {name, value}"})
+                    return
+                store.set_secret(vault_path, master_key, name, value)
+                self._send_json(200, {"ok": True})
+                return
+
+            if parsed.path.startswith("/api/keys/") and parsed.path.endswith("/reveal"):
+                name = parsed.path[len("/api/keys/"):-len("/reveal")]
+                try:
+                    value = store.get_secret(vault_path, master_key, name)
+                except KeyError as e:
+                    self._send_json(404, {"error": str(e)})
+                    return
+                self._send_json(200, {"value": value})
+                return
+
+            self._send_json(404, {"error": "not found"})
+
+        def do_DELETE(self):
+            parsed = urlparse(self.path)
+
+            if not self._check_token():
+                self._send_json(403, {"error": "invalid or missing token"})
+                return
+
+            if parsed.path.startswith("/api/keys/"):
+                name = parsed.path[len("/api/keys/"):]
+                try:
+                    store.delete_secret(vault_path, name)
+                except KeyError as e:
+                    self._send_json(404, {"error": str(e)})
+                    return
+                self._send_json(200, {"ok": True})
+                return
+
+            self._send_json(404, {"error": "not found"})
+
+        def log_message(self, format, *args):
+            pass  # silence default request logging to stderr
+
+    return Handler
+
+
+def serve(vault_path: pathlib.Path, port: int = 0) -> None:
+    """Start the UI server and open it in the browser. Blocks until Ctrl+C."""
+    master_key = keychain.get_master_key()
+    token = secrets.token_urlsafe(16)
+
+    handler_cls = _make_handler(vault_path, master_key, token)
+    httpd = ThreadingHTTPServer((HOST, port), handler_cls)
+    actual_port = httpd.server_address[1]
+    url = f"http://{HOST}:{actual_port}/?token={token}"
+
+    threading.Thread(target=lambda: webbrowser.open(url), daemon=True).start()
+
+    print(f"vault UI running at {url}")
+    print("press Ctrl+C to stop")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        httpd.shutdown()

vault/ui/static/index.html

@@ -0,0 +1,464 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Vault</title>
+<style>
+  :root {
+    color-scheme: light dark;
+    --bg: #f4f5f7;
+    --bg-elevated: #fbfbfc;
+    --panel: #ffffff;
+    --panel-hover: #f7f8fa;
+    --border: #e3e4e8;
+    --border-strong: #d1d3d9;
+    --text: #16171a;
+    --muted: #6b6d76;
+    --muted-2: #9497a1;
+    --accent: #2f5eff;
+    --accent-hover: #1f4bef;
+    --accent-soft: #eaefff;
+    --danger: #e0393e;
+    --danger-soft: #fdecec;
+    --success: #1a9c6e;
+    --success-soft: #e9f9f1;
+    --shadow: 0 1px 2px rgba(20, 21, 26, 0.04), 0 8px 24px rgba(20, 21, 26, 0.06);
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0f1013;
+      --bg-elevated: #14151a;
+      --panel: #1a1b21;
+      --panel-hover: #20212a;
+      --border: #2b2d36;
+      --border-strong: #3a3c48;
+      --text: #f1f2f4;
+      --muted: #9a9ca6;
+      --muted-2: #6f7180;
+      --accent: #5b7fff;
+      --accent-hover: #7a97ff;
+      --accent-soft: #1c2440;
+      --danger: #f0605f;
+      --danger-soft: #331e1f;
+      --success: #3ecf94;
+      --success-soft: #123328;
+      --shadow: 0 1px 2px rgba(0, 0, 0, 0.3), 0 12px 32px rgba(0, 0, 0, 0.35);
+    }
+  }
+
+  * { box-sizing: border-box; }
+
+  html, body {
+    min-height: 100%;
+  }
+
+  body {
+    margin: 0;
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, "Segoe UI", system-ui, sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  .topbar {
+    position: sticky;
+    top: 0;
+    z-index: 10;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 1.1rem clamp(1.5rem, 4vw, 3.5rem);
+    background: color-mix(in srgb, var(--bg-elevated) 92%, transparent);
+    backdrop-filter: blur(8px);
+    border-bottom: 1px solid var(--border);
+  }
+
+  .brand { display: flex; align-items: center; gap: 0.65rem; }
+
+  .brand-mark {
+    width: 34px;
+    height: 34px;
+    border-radius: 9px;
+    background: linear-gradient(135deg, var(--accent), #7a97ff);
+    display: grid;
+    place-items: center;
+    box-shadow: 0 4px 14px color-mix(in srgb, var(--accent) 45%, transparent);
+  }
+  .brand-mark svg { width: 18px; height: 18px; stroke: white; }
+
+  .brand-name { font-size: 1.05rem; font-weight: 650; letter-spacing: -0.01em; }
+
+  .topbar-meta {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--muted);
+    font-size: 0.8rem;
+  }
+  .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--success); flex-shrink: 0;
+         box-shadow: 0 0 0 3px var(--success-soft); }
+
+  main {
+    max-width: 880px;
+    margin: 0 auto;
+    padding: clamp(1.75rem, 4vw, 3rem) clamp(1.25rem, 4vw, 2rem) 5rem;
+  }
+
+  .page-head { margin-bottom: 1.75rem; }
+  .page-head h1 { margin: 0 0 0.35rem; font-size: 1.6rem; letter-spacing: -0.015em; }
+  .page-head p { margin: 0; color: var(--muted); font-size: 0.95rem; }
+
+  .panel {
+    background: var(--panel);
+    border: 1px solid var(--border);
+    border-radius: 16px;
+    box-shadow: var(--shadow);
+    overflow: hidden;
+    margin-bottom: 1.75rem;
+  }
+
+  .panel-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 1.15rem 1.5rem;
+    border-bottom: 1px solid var(--border);
+  }
+  .panel-header h2 { margin: 0; font-size: 0.95rem; font-weight: 600; }
+  .count-badge {
+    font-size: 0.75rem;
+    color: var(--muted);
+    background: var(--bg);
+    border: 1px solid var(--border);
+    border-radius: 999px;
+    padding: 0.2rem 0.65rem;
+  }
+
+  table { width: 100%; border-collapse: collapse; }
+  thead th {
+    text-align: left;
+    padding: 0.6rem 1.5rem;
+    font-size: 0.7rem;
+    font-weight: 600;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--muted-2);
+    background: var(--bg-elevated);
+    border-bottom: 1px solid var(--border);
+  }
+  tbody tr { border-bottom: 1px solid var(--border); transition: background 0.12s ease; }
+  tbody tr:last-child { border-bottom: none; }
+  tbody tr:hover { background: var(--panel-hover); }
+  td { padding: 0.85rem 1.5rem; vertical-align: middle; }
+  td.name { font-weight: 550; }
+  td.value {
+    font-family: "SF Mono", "Cascadia Code", Consolas, monospace;
+    font-size: 0.88rem;
+    color: var(--muted);
+    letter-spacing: 0.03em;
+  }
+  td.value.revealed { color: var(--accent); }
+  td.actions { text-align: right; white-space: nowrap; }
+
+  .empty-row td { padding: 3rem 1.5rem; text-align: center; }
+  .empty-state { color: var(--muted); font-size: 0.9rem; }
+  .empty-state .glyph { font-size: 1.6rem; display: block; margin-bottom: 0.5rem; opacity: 0.6; }
+
+  button {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    border: 1px solid var(--border-strong);
+    background: var(--panel);
+    color: var(--text);
+    border-radius: 8px;
+    padding: 0.4rem 0.75rem;
+    cursor: pointer;
+    font-size: 0.82rem;
+    font-weight: 500;
+    font-family: inherit;
+    transition: border-color 0.12s ease, color 0.12s ease, background 0.12s ease, transform 0.05s ease;
+  }
+  button svg { width: 14px; height: 14px; }
+  button:hover { border-color: var(--accent); color: var(--accent); }
+  button:active { transform: translateY(1px); }
+  button:disabled { opacity: 0.55; cursor: default; pointer-events: none; }
+  button.danger:hover { border-color: var(--danger); color: var(--danger); }
+  button.icon-btn { margin-left: 0.5rem; }
+  button.icon-btn:first-child { margin-left: 0; }
+
+  button.primary {
+    background: var(--accent);
+    border-color: var(--accent);
+    color: white;
+    padding: 0.55rem 1.1rem;
+    font-weight: 600;
+  }
+  button.primary:hover { background: var(--accent-hover); border-color: var(--accent-hover); color: white; }
+
+  .add-form {
+    display: flex;
+    gap: 0.75rem;
+    padding: 1.25rem 1.5rem;
+    background: var(--bg-elevated);
+  }
+  .field { flex: 1; display: flex; flex-direction: column; gap: 0.35rem; }
+  .field label {
+    font-size: 0.7rem;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    color: var(--muted-2);
+  }
+  input {
+    padding: 0.6rem 0.75rem;
+    border: 1px solid var(--border-strong);
+    border-radius: 8px;
+    background: var(--panel);
+    color: var(--text);
+    font-size: 0.92rem;
+    font-family: inherit;
+    outline: none;
+    transition: border-color 0.12s ease, box-shadow 0.12s ease;
+  }
+  input:focus { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
+  .add-form .submit-field { justify-content: flex-end; }
+  .add-form button.primary { align-self: flex-end; height: 2.5rem; }
+
+  #status {
+    display: none;
+    align-items: center;
+    gap: 0.5rem;
+    margin: -0.25rem 0 1.5rem;
+    padding: 0.65rem 1rem;
+    border-radius: 10px;
+    font-size: 0.85rem;
+    border: 1px solid transparent;
+  }
+  #status.visible { display: flex; }
+  #status.error { background: var(--danger-soft); color: var(--danger); border-color: color-mix(in srgb, var(--danger) 25%, transparent); }
+  #status.success { background: var(--success-soft); color: var(--success); border-color: color-mix(in srgb, var(--success) 25%, transparent); }
+
+  footer {
+    text-align: center;
+    color: var(--muted-2);
+    font-size: 0.78rem;
+    padding-top: 0.5rem;
+  }
+
+  @media (max-width: 560px) {
+    .add-form { flex-direction: column; }
+    .add-form .submit-field { align-items: stretch; }
+    .add-form button.primary { width: 100%; height: auto; }
+    td.actions button span.label { display: none; }
+  }
+</style>
+</head>
+<body>
+  <div class="topbar">
+    <div class="brand">
+      <div class="brand-mark">
+        <svg viewBox="0 0 24 24" fill="none" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <rect x="4" y="10" width="16" height="10" rx="2"></rect>
+          <path d="M8 10V7a4 4 0 0 1 8 0v3"></path>
+        </svg>
+      </div>
+      <span class="brand-name">Vault</span>
+    </div>
+    <div class="topbar-meta">
+      <span class="dot"></span>
+      <span>127.0.0.1 · token-protected session</span>
+    </div>
+  </div>
+
+  <main>
+    <div class="page-head">
+      <h1>Secrets</h1>
+      <p>Local secrets manager — nothing leaves this machine.</p>
+    </div>
+
+    <div id="status"></div>
+
+    <div class="panel">
+      <div class="panel-header">
+        <h2>Stored secrets</h2>
+        <span class="count-badge" id="count-badge">0</span>
+      </div>
+      <table>
+        <thead>
+          <tr><th>Name</th><th>Value</th><th></th></tr>
+        </thead>
+        <tbody id="rows"></tbody>
+      </table>
+    </div>
+
+    <div class="panel">
+      <form id="add-form" class="add-form">
+        <div class="field">
+          <label for="name-input">Name</label>
+          <input id="name-input" placeholder="API_KEY" autocomplete="off" required>
+        </div>
+        <div class="field">
+          <label for="value-input">Value</label>
+          <input id="value-input" type="text" placeholder="secret value" autocomplete="off" required>
+        </div>
+        <div class="field submit-field">
+          <button type="submit" class="primary">Add secret</button>
+        </div>
+      </form>
+    </div>
+
+    <footer>Served locally over HTTP — access requires the session token in the URL.</footer>
+  </main>
+
+<script>
+const params = new URLSearchParams(window.location.search);
+const TOKEN = params.get("token") || "";
+
+const ICONS = {
+  reveal: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M1 12s4-7 11-7 11 7 11 7-4 7-11 7-11-7-11-7Z"/><circle cx="12" cy="12" r="3"/></svg>',
+  hide: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3l18 18"/><path d="M10.6 5.1A11 11 0 0 1 12 5c7 0 11 7 11 7a13.5 13.5 0 0 1-3 3.6M6.5 6.7C3.7 8.5 1 12 1 12s4 7 11 7c1.4 0 2.7-.2 3.9-.6"/><path d="M9.9 9.9a3 3 0 0 0 4.2 4.2"/></svg>',
+  trash: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 6h18"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2m3 0-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/></svg>',
+};
+
+let statusTimer = null;
+
+function setStatus(msg, kind) {
+  const el = document.getElementById("status");
+  clearTimeout(statusTimer);
+  if (!msg) {
+    el.classList.remove("visible", "error", "success");
+    return;
+  }
+  el.textContent = msg;
+  el.classList.add("visible");
+  el.classList.remove("error", "success");
+  el.classList.add(kind === "error" ? "error" : "success");
+  if (kind !== "error") {
+    statusTimer = setTimeout(() => el.classList.remove("visible"), 3000);
+  }
+}
+
+async function api(path, options = {}) {
+  const url = new URL(path, window.location.origin);
+  url.searchParams.set("token", TOKEN);
+  const res = await fetch(url, {
+    ...options,
+    headers: { "X-Vault-Token": TOKEN, "Content-Type": "application/json", ...(options.headers || {}) },
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || `request failed (${res.status})`);
+  }
+  return res.json();
+}
+
+async function loadKeys() {
+  try {
+    const names = await api("/api/keys");
+    renderRows(names);
+  } catch (err) {
+    setStatus(err.message, "error");
+  }
+}
+
+function renderRows(names) {
+  const tbody = document.getElementById("rows");
+  document.getElementById("count-badge").textContent = names.length;
+  tbody.innerHTML = "";
+
+  if (names.length === 0) {
+    const tr = document.createElement("tr");
+    tr.className = "empty-row";
+    const td = document.createElement("td");
+    td.colSpan = 3;
+    td.innerHTML = '<div class="empty-state"><span class="glyph">🔒</span>No secrets yet — add one below.</div>';
+    tr.appendChild(td);
+    tbody.appendChild(tr);
+    return;
+  }
+
+  for (const name of names) {
+    const tr = document.createElement("tr");
+
+    const nameTd = document.createElement("td");
+    nameTd.className = "name";
+    nameTd.textContent = name;
+
+    const valueTd = document.createElement("td");
+    valueTd.className = "value";
+    valueTd.textContent = "••••••••";
+
+    const actionsTd = document.createElement("td");
+    actionsTd.className = "actions";
+
+    const revealBtn = document.createElement("button");
+    revealBtn.className = "icon-btn";
+    revealBtn.innerHTML = `${ICONS.reveal}<span class="label">Reveal</span>`;
+    revealBtn.onclick = () => revealValue(name, valueTd, revealBtn);
+
+    const deleteBtn = document.createElement("button");
+    deleteBtn.className = "icon-btn danger";
+    deleteBtn.innerHTML = `${ICONS.trash}<span class="label">Delete</span>`;
+    deleteBtn.onclick = () => deleteKey(name);
+
+    actionsTd.appendChild(revealBtn);
+    actionsTd.appendChild(deleteBtn);
+
+    tr.appendChild(nameTd);
+    tr.appendChild(valueTd);
+    tr.appendChild(actionsTd);
+    tbody.appendChild(tr);
+  }
+}
+
+async function revealValue(name, valueTd, revealBtn) {
+  try {
+    revealBtn.disabled = true;
+    const { value } = await api(`/api/keys/${encodeURIComponent(name)}/reveal`, { method: "POST" });
+    valueTd.textContent = value;
+    valueTd.classList.add("revealed");
+    setTimeout(() => {
+      valueTd.textContent = "••••••••";
+      valueTd.classList.remove("revealed");
+      revealBtn.disabled = false;
+    }, 5000);
+  } catch (err) {
+    setStatus(err.message, "error");
+    revealBtn.disabled = false;
+  }
+}
+
+async function deleteKey(name) {
+  try {
+    await api(`/api/keys/${encodeURIComponent(name)}`, { method: "DELETE" });
+    setStatus(`Deleted '${name}'`, "success");
+    await loadKeys();
+  } catch (err) {
+    setStatus(err.message, "error");
+  }
+}
+
+document.getElementById("add-form").addEventListener("submit", async (e) => {
+  e.preventDefault();
+  const nameInput = document.getElementById("name-input");
+  const valueInput = document.getElementById("value-input");
+  try {
+    await api("/api/keys", {
+      method: "POST",
+      body: JSON.stringify({ name: nameInput.value, value: valueInput.value }),
+    });
+    setStatus(`Stored '${nameInput.value}'`, "success");
+    nameInput.value = "";
+    valueInput.value = "";
+    nameInput.focus();
+    await loadKeys();
+  } catch (err) {
+    setStatus(err.message, "error");
+  }
+});
+
+loadKeys();
+</script>
+</body>
+</html>