guhio 0.1.0__tar.gz

guhio-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: guhio
+Version: 0.1.0
+Summary: A local password vault for agent workflows (guhio: Sanskrit for secret)
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: flask>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# Guhio
+
+Guhio (Sanskrit: गुह्य, "secret") is a local password vault built for agent
+workflows. It lets humans provide credentials without typing them into an agent
+context, and it lets agents *use* credentials by name without ever seeing the
+plaintext values.
+
+## Features
+
+- **Encrypted local vault** using PBKDF2 key derivation and Fernet symmetric
+  encryption.
+- **Human-friendly CLI** with secure password prompts.
+- **Agent-safe usage** via `guhio exec`, which injects credentials into a
+  subprocess as environment variables.
+- **Agent skill** following the [Agent Skills](https://agentskills.io/specification)
+  format so AI assistants can discover and use the vault safely.
+- **Local web dashboard** for adding, viewing, and managing credentials in a
+  browser.
+
+## Installation
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+```
+
+## CLI Usage
+
+```bash
+# Create a vault
+.venv/bin/python -m guhio.cli init
+
+# Add a credential (prompts securely)
+.venv/bin/python -m guhio.cli add github
+
+# List credentials
+.venv/bin/python -m guhio.cli list
+
+# Use a credential without revealing it
+.venv/bin/python -m guhio.cli exec --with github:GITHUB_TOKEN -- curl \
+  -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
+
+# Remove a credential
+.venv/bin/python -m guhio.cli remove github
+```
+
+The default vault file is `~/.guhio/vault.json`. Use `--vault <path>` to
+override.
+
+## Dashboard
+
+Start the local web dashboard:
+
+```bash
+.venv/bin/python -m guhio.cli dashboard
+```
+
+Then open <http://127.0.0.1:5000> in your browser. The dashboard only binds to
+localhost and requires the master password to unlock the vault.
+
+## Agent Skill
+
+A skill conforming to the [Agent Skills specification](https://agentskills.io/specification)
+is included under `.claude/skills/guhio/`. When loaded, it instructs agents to
+use `guhio exec` for credential-based operations and to direct humans to
+`guhio add` when a credential is missing.
+
+## Development
+
+```bash
+.venv/bin/python -m pytest
+```
+
+## Security Notes
+
+This is an MVP. The vault is only as strong as the master password and the
+security of the machine it runs on. While unlocked, plaintext values reside in
+process memory. Do not commit vault files to version control.

guhio-0.1.0/README.md

@@ -0,0 +1,78 @@
+# Guhio
+
+Guhio (Sanskrit: गुह्य, "secret") is a local password vault built for agent
+workflows. It lets humans provide credentials without typing them into an agent
+context, and it lets agents *use* credentials by name without ever seeing the
+plaintext values.
+
+## Features
+
+- **Encrypted local vault** using PBKDF2 key derivation and Fernet symmetric
+  encryption.
+- **Human-friendly CLI** with secure password prompts.
+- **Agent-safe usage** via `guhio exec`, which injects credentials into a
+  subprocess as environment variables.
+- **Agent skill** following the [Agent Skills](https://agentskills.io/specification)
+  format so AI assistants can discover and use the vault safely.
+- **Local web dashboard** for adding, viewing, and managing credentials in a
+  browser.
+
+## Installation
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+```
+
+## CLI Usage
+
+```bash
+# Create a vault
+.venv/bin/python -m guhio.cli init
+
+# Add a credential (prompts securely)
+.venv/bin/python -m guhio.cli add github
+
+# List credentials
+.venv/bin/python -m guhio.cli list
+
+# Use a credential without revealing it
+.venv/bin/python -m guhio.cli exec --with github:GITHUB_TOKEN -- curl \
+  -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
+
+# Remove a credential
+.venv/bin/python -m guhio.cli remove github
+```
+
+The default vault file is `~/.guhio/vault.json`. Use `--vault <path>` to
+override.
+
+## Dashboard
+
+Start the local web dashboard:
+
+```bash
+.venv/bin/python -m guhio.cli dashboard
+```
+
+Then open <http://127.0.0.1:5000> in your browser. The dashboard only binds to
+localhost and requires the master password to unlock the vault.
+
+## Agent Skill
+
+A skill conforming to the [Agent Skills specification](https://agentskills.io/specification)
+is included under `.claude/skills/guhio/`. When loaded, it instructs agents to
+use `guhio exec` for credential-based operations and to direct humans to
+`guhio add` when a credential is missing.
+
+## Development
+
+```bash
+.venv/bin/python -m pytest
+```
+
+## Security Notes
+
+This is an MVP. The vault is only as strong as the master password and the
+security of the machine it runs on. While unlocked, plaintext values reside in
+process memory. Do not commit vault files to version control.

guhio-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "guhio"
+version = "0.1.0"
+description = "A local password vault for agent workflows (guhio: Sanskrit for secret)"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=42.0.0",
+    "flask>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+guhio = "guhio.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+guhio = ["templates/*.html"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

guhio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

guhio-0.1.0/src/guhio/__init__.py

@@ -0,0 +1,6 @@
+"""Guhio: a local password vault for agent workflows.
+
+guhio (Sanskrit: गुह्य) means "secret" or "hidden".
+"""
+
+__version__ = "0.1.0"

guhio-0.1.0/src/guhio/cli.py

@@ -0,0 +1,309 @@
+"""Command-line interface for the password vault."""
+
+import argparse
+import getpass
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from guhio.store import (
+    EntryNotFoundError,
+    InvalidPasswordError,
+    Vault,
+    VaultError,
+    VaultNotFoundError,
+)
+
+
+def _prompt_password(prompt: str = "Master password: ") -> str:
+    """Prompt for a password without echoing to the terminal."""
+    return getpass.getpass(prompt)
+
+
+def _prompt_new_password() -> str:
+    """Prompt for a new master password twice to avoid typos."""
+    first = getpass.getpass("Set master password: ")
+    second = getpass.getpass("Confirm master password: ")
+    if first != second:
+        print("Passwords do not match.", file=sys.stderr)
+        sys.exit(1)
+    if not first:
+        print("Master password cannot be empty.", file=sys.stderr)
+        sys.exit(1)
+    return first
+
+
+def _read_env_password() -> str | None:
+    """Read the master password from the environment if available."""
+    return os.environ.get("GUHIO_MASTER_PASSWORD")
+
+
+def _get_password_for_unlock(args) -> str:
+    """Determine the master password for unlocking an existing vault."""
+    env_password = _read_env_password()
+    if env_password is not None:
+        return env_password
+    if args.password:
+        return args.password
+    return _prompt_password()
+
+
+def cmd_init(args) -> None:
+    """Create a new vault."""
+    vault = Vault(args.vault)
+    if vault.exists():
+        print(f"Vault already exists at {vault.path}", file=sys.stderr)
+        sys.exit(1)
+    master_password = _prompt_new_password()
+    vault.create(master_password)
+    print(f"Vault created at {vault.path}")
+
+
+def cmd_unlock(args) -> None:
+    """Unlock the vault and keep it unlocked in memory (no-op for CLI)."""
+    vault = Vault(args.vault)
+    password = _get_password_for_unlock(args)
+    try:
+        vault.unlock(password)
+    except InvalidPasswordError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    print("Vault unlocked.")
+
+
+def cmd_add(args) -> None:
+    """Add a new credential to the vault."""
+    vault = Vault(args.vault)
+    password = _get_password_for_unlock(args)
+    try:
+        vault.unlock(password)
+    except InvalidPasswordError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.value:
+        value = args.value
+    else:
+        value = getpass.getpass(f"Enter value for '{args.name}': ")
+    if not value:
+        print("Credential value cannot be empty.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        vault.add(args.name, value)
+    except VaultError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    print(f"Credential '{args.name}' added.")
+
+
+def cmd_list(args) -> None:
+    """List stored credential names."""
+    vault = Vault(args.vault)
+    password = _get_password_for_unlock(args)
+    try:
+        vault.unlock(password)
+    except InvalidPasswordError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    entries = vault.list_entries()
+    if not entries:
+        print("Vault is empty.")
+        return
+    for entry in entries:
+        print(f"{entry.name}\t{entry.created_at.isoformat()}")
+
+
+def cmd_remove(args) -> None:
+    """Remove a credential from the vault."""
+    vault = Vault(args.vault)
+    password = _get_password_for_unlock(args)
+    try:
+        vault.unlock(password)
+    except InvalidPasswordError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        vault.remove(args.name)
+    except EntryNotFoundError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    print(f"Credential '{args.name}' removed.")
+
+
+def cmd_get(args) -> None:
+    """Print a credential value to stdout.
+
+    This subcommand exists for human use and scripts; agents should prefer
+    ``exec`` to avoid exposing values in their context.
+    """
+    vault = Vault(args.vault)
+    password = _get_password_for_unlock(args)
+    try:
+        vault.unlock(password)
+    except InvalidPasswordError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        print(vault.get(args.name))
+    except EntryNotFoundError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _parse_mapping(mapping: str) -> tuple[str, str]:
+    """Parse 'name:ENV_VAR' into credential name and environment variable name."""
+    if ":" not in mapping:
+        return mapping, mapping.upper()
+    name, env_var = mapping.split(":", 1)
+    return name, env_var
+
+
+def cmd_dashboard(args) -> None:
+    """Start the local web dashboard."""
+    from guhio.dashboard import run_dashboard
+
+    print(f"Starting Guhio dashboard at http://{args.host}:{args.port}")
+    print("Press Ctrl+C to stop.")
+    run_dashboard(host=args.host, port=args.port, debug=args.debug)
+
+
+def cmd_exec(args) -> None:
+    """Run a command with credentials injected as environment variables."""
+    vault = Vault(args.vault)
+    password = _get_password_for_unlock(args)
+    try:
+        vault.unlock(password)
+    except InvalidPasswordError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    env = os.environ.copy()
+    for mapping in args.with_:
+        name, env_var = _parse_mapping(mapping)
+        try:
+            env[env_var] = vault.get(name)
+        except EntryNotFoundError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    command = args.command
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command:
+        print("No command provided.", file=sys.stderr)
+        sys.exit(1)
+
+    # Run the command directly; do not invoke a shell so the value stays out of
+    # the command string visible to the agent.
+    try:
+        result = subprocess.run(command, env=env, check=False)
+    except FileNotFoundError as exc:
+        print(f"Error: command not found: {exc}", file=sys.stderr)
+        sys.exit(127)
+    sys.exit(result.returncode)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="guhio",
+        description="Local password vault for agent workflows (guhio: Sanskrit for secret).",
+    )
+    parser.add_argument(
+        "--vault",
+        type=Path,
+        default=os.environ.get("GUHIO_VAULT"),
+        help="Path to the vault file (default: ~/.guhio/vault.json; can also be set via GUHIO_VAULT env var)",
+    )
+    parser.add_argument(
+        "--password",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="Create a new vault")
+    init_parser.set_defaults(func=cmd_init)
+
+    unlock_parser = subparsers.add_parser("unlock", help="Unlock the vault")
+    unlock_parser.set_defaults(func=cmd_unlock)
+
+    add_parser = subparsers.add_parser("add", help="Add a credential")
+    add_parser.add_argument("name", help="Name of the credential")
+    add_parser.add_argument(
+        "--value",
+        default=None,
+        help="Value for the credential (prompted securely if omitted)",
+    )
+    add_parser.set_defaults(func=cmd_add)
+
+    list_parser = subparsers.add_parser("list", help="List stored credentials")
+    list_parser.set_defaults(func=cmd_list)
+
+    remove_parser = subparsers.add_parser("remove", help="Remove a credential")
+    remove_parser.add_argument("name", help="Name of the credential")
+    remove_parser.set_defaults(func=cmd_remove)
+
+    get_parser = subparsers.add_parser("get", help="Print a credential value")
+    get_parser.add_argument("name", help="Name of the credential")
+    get_parser.set_defaults(func=cmd_get)
+
+    exec_parser = subparsers.add_parser(
+        "exec",
+        help="Run a command with credentials injected as environment variables",
+    )
+    exec_parser.add_argument(
+        "--with",
+        dest="with_",
+        action="append",
+        default=[],
+        metavar="NAME:ENV_VAR",
+        help="Inject credential NAME as environment variable ENV_VAR",
+    )
+    exec_parser.add_argument(
+        "command",
+        nargs=argparse.REMAINDER,
+        help="Command and arguments to run",
+    )
+    exec_parser.set_defaults(func=cmd_exec)
+
+    dashboard_parser = subparsers.add_parser(
+        "dashboard",
+        help="Start the local web dashboard for managing credentials",
+    )
+    dashboard_parser.add_argument(
+        "--host",
+        default=os.environ.get("GUHIO_HOST", "127.0.0.1"),
+        help="Host to bind the dashboard to (default: 127.0.0.1; can also be set via GUHIO_HOST env var)",
+    )
+    dashboard_parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("GUHIO_PORT", "5000")),
+        help="Port to bind the dashboard to (default: 5000; can also be set via GUHIO_PORT env var)",
+    )
+    dashboard_parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Run Flask in debug mode (not recommended with vault sessions)",
+    )
+    dashboard_parser.set_defaults(func=cmd_dashboard)
+
+    return parser
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    parser = build_parser()
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

guhio-0.1.0/src/guhio/crypto.py

@@ -0,0 +1,48 @@
+"""Cryptographic helpers for the password vault."""
+
+import base64
+import secrets
+
+from cryptography.fernet import Fernet, InvalidToken
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+
+def derive_key(password: str, salt: bytes) -> bytes:
+    """Derive a Fernet key from a password and salt."""
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt,
+        iterations=600_000,
+    )
+    return base64.urlsafe_b64encode(kdf.derive(password.encode("utf-8")))
+
+
+def generate_salt(size: int = 16) -> bytes:
+    """Generate a random salt."""
+    return secrets.token_bytes(size)
+
+
+def encrypt_value(password: str, plaintext: str, salt: bytes | None = None) -> bytes:
+    """Encrypt a plaintext value with a password.
+
+    If ``salt`` is provided it is used for key derivation; otherwise a new salt
+    is generated and the caller is responsible for storing it.
+    """
+    if salt is None:
+        salt = generate_salt()
+    key = derive_key(password, salt)
+    f = Fernet(key)
+    return f.encrypt(plaintext.encode("utf-8"))
+
+
+def decrypt_value(password: str, salt: bytes, ciphertext: bytes) -> str:
+    """Decrypt a ciphertext value with a password and salt."""
+    key = derive_key(password, salt)
+    f = Fernet(key)
+    try:
+        plaintext = f.decrypt(ciphertext)
+    except InvalidToken as exc:
+        raise ValueError("Invalid master password or corrupted vault") from exc
+    return plaintext.decode("utf-8")

guhio-0.1.0/src/guhio/dashboard.py

@@ -0,0 +1,116 @@
+"""Local web dashboard for managing the Guhio vault."""
+
+import secrets
+
+from flask import Flask, abort, jsonify, render_template, request, session
+
+from guhio.store import EntryNotFoundError, Vault, VaultError
+
+app = Flask(__name__)
+app.secret_key = secrets.token_hex(32)
+
+# Server-side session storage: maps a random token to an unlocked Vault instance.
+# This keeps decrypted values out of cookies and is acceptable for the local,
+# single-user dashboard. Do not use this for a multi-user service.
+_vault_sessions: dict[str, Vault] = {}
+
+
+def _require_vault() -> Vault:
+    """Return the unlocked vault for the current session or abort with 401."""
+    token = session.get("vault_token")
+    vault = _vault_sessions.get(token) if token else None
+    if vault is None or not vault.is_unlocked():
+        abort(401)
+    return vault
+
+
+@app.route("/")
+def index() -> str:
+    """Render the dashboard page."""
+    return render_template("dashboard.html")
+
+
+@app.route("/api/status")
+def status() -> dict:
+    """Return whether the vault is unlocked for this session."""
+    token = session.get("vault_token")
+    vault = _vault_sessions.get(token) if token else None
+    return jsonify({"unlocked": vault is not None and vault.is_unlocked()})
+
+
+@app.route("/api/unlock", methods=["POST"])
+def unlock() -> tuple[dict, int]:
+    """Unlock the vault and create a server-side session."""
+    data = request.get_json(silent=True) or {}
+    password = data.get("password", "")
+
+    vault = Vault()
+    try:
+        vault.unlock(password)
+    except VaultError as exc:
+        return jsonify({"error": str(exc)}), 401
+
+    token = secrets.token_urlsafe(32)
+    _vault_sessions[token] = vault
+    session["vault_token"] = token
+    return jsonify({"unlocked": True})
+
+
+@app.route("/api/lock", methods=["POST"])
+def lock() -> dict:
+    """Lock the vault and clear the server-side session."""
+    token = session.pop("vault_token", None)
+    if token:
+        _vault_sessions.pop(token, None)
+    return jsonify({"unlocked": False})
+
+
+@app.route("/api/credentials", methods=["GET"])
+def list_credentials() -> list[dict]:
+    """List credential names and metadata without values."""
+    vault = _require_vault()
+    entries = vault.list_entries()
+    return jsonify(
+        [
+            {"name": entry.name, "created_at": entry.created_at.isoformat()}
+            for entry in entries
+        ]
+    )
+
+
+@app.route("/api/credentials", methods=["POST"])
+def add_credential() -> tuple[dict, int]:
+    """Add a new credential to the vault."""
+    vault = _require_vault()
+    data = request.get_json(silent=True) or {}
+    name = data.get("name", "").strip()
+    value = data.get("value", "")
+
+    if not name or not value:
+        return jsonify({"error": "Name and value are required"}), 400
+
+    try:
+        vault.add(name, value)
+    except VaultError as exc:
+        return jsonify({"error": str(exc)}), 409
+
+    return jsonify({"ok": True})
+
+
+@app.route("/api/credentials/<path:name>", methods=["DELETE"])
+def remove_credential(name: str) -> tuple[dict, int]:
+    """Remove a credential from the vault."""
+    vault = _require_vault()
+    try:
+        vault.remove(name)
+    except EntryNotFoundError as exc:
+        return jsonify({"error": str(exc)}), 404
+    return jsonify({"ok": True})
+
+
+def run_dashboard(host: str = "127.0.0.1", port: int = 5000, debug: bool = False) -> None:
+    """Start the Flask development server."""
+    # Do not use the reloader: it forks a child process and clears the
+    # in-memory _vault_sessions dictionary, which would lock users out after
+    # every auto-reload.
+    app.run(host=host, port=port, debug=debug, use_reloader=False)