Metadata-Version: 2.4
Name: guhio
Version: 1.0.1
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<46,>=42.0.0
Requires-Dist: flask<4,>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

<h1>
  <img src="https://raw.githubusercontent.com/dhiraj-salian/guhio/refs/heads/main/src/guhio/static/logo.svg" width="120" alt="Guhio logo" align="center">
  guhio
</h1>

[![PyPI version](https://img.shields.io/pypi/v/guhio.svg)](https://pypi.org/project/guhio/)

Guhio (Sanskrit: गुह्य, "secret") is a local password vault for agent workflows.
Humans store credentials outside the agent context, and agents use them by name
without ever seeing the plaintext values.

## Features

- Encrypted local vault using PBKDF2-HMAC-SHA256 (600,000 iterations) and
  Fernet symmetric encryption (AES-128-CBC + HMAC).
- Atomic, permission-restricted vault writes.
- CLI with secure `getpass` prompts and a non-interactive `exec` mode that
  injects credentials as environment variables.
- Encrypted CLI sessions so you unlock once and run multiple commands.
- Local web dashboard for managing credentials in a browser.
- Agent skill under `.claude/skills/guhio/` following the
  [Agent Skills specification](https://agentskills.io/specification).

## Installation

```bash
pip install guhio
```

## Quick start

```bash
# Create a vault
 guhio init

# Add a credential (value is prompted securely)
 guhio add github

# Unlock once and reuse the session
 eval $(guhio unlock)

# Use the credential without exposing the value
 guhio exec --with github:GITHUB_TOKEN --expand -- \
   curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

# Lock the vault and clear the session
 guhio lock
```

## Commands

| Command | Purpose |
|---------|---------|
| `guhio init` | Create a new vault. |
| `guhio add <name>` | Add a credential. Use `--value <value>` to skip prompting. |
| `guhio list` | List credential names and creation times. |
| `guhio get <name>` | Print a credential value. |
| `guhio unlock` | Unlock the vault and print `export GUHIO_SESSION=...`. |
| `guhio lock` | Clear the CLI session. |
| `guhio exec --with <name>:<ENV_VAR> [--expand] -- <command>` | Run a command with the credential injected as an environment variable. |
| `guhio remove <name>` | Delete a credential. |
| `guhio dashboard` | Start the local web dashboard (default `http://127.0.0.1:5000`). |
| `guhio --version` / `guhio version` | Show the installed Guhio version. |

## Authentication

The master password can be supplied in three ways, in order of precedence:

1. `GUHIO_SESSION` environment variable from `guhio unlock`.
2. `GUHIO_MASTER_PASSWORD` environment variable.
3. The hidden `--password <pw>` flag.
4. Interactive `getpass` prompt.

Run `guhio lock` to remove the session file at `~/.guhio/session.json`.

## Environment variables

| Variable | Purpose |
|----------|---------|
| `GUHIO_VAULT` | Path to the vault file (default: `~/.guhio/vault.json`). |
| `GUHIO_MASTER_PASSWORD` | Master password for non-interactive use. |
| `GUHIO_SESSION` | Session token from `guhio unlock`. |
| `GUHIO_HOST` / `GUHIO_PORT` | Dashboard bind address and port. |

## Dashboard

```bash
guhio dashboard              # http://127.0.0.1:5000
guhio dashboard --port 8080
```

The dashboard stores unlocked vaults in server-side memory; sessions disappear
when the server restarts. Do not expose the dashboard to untrusted networks.

## Security notes

- The master password is the only protection for the vault file.
- Vault files and the vault directory are written with restrictive permissions
  (`0600` and `0700` respectively). Writes are atomic and use `O_NOFOLLOW` to
  reject symlink redirection attacks.
- CLI sessions expire after 8 hours. Run `guhio lock` to clear a session
  immediately. Session files are written atomically with mode `0600`.
- The dashboard protects against CSRF (SameSite cookies + Origin validation),
  brute-force unlock (rate limiting with lockout), and sets security headers
  (`X-Content-Type-Options`, `X-Frame-Options`, `Content-Security-Policy`).
  Dashboard sessions expire after 30 minutes of inactivity.
- `guhio exec` runs commands directly (not through a shell). Use `--expand` to
  substitute `$VAR` placeholders, or `sh -c '...'` for full shell features.
  Environment variable names are validated to prevent injection of dangerous
  variables.
- Security-relevant events (unlock, credential add/remove/reveal) are recorded
  in an audit log at `~/.guhio/audit.log` (mode `0600`). No secrets are logged.
- Never commit vault, session, or audit files to version control.

See [SECURITY.md](./SECURITY.md) for the full security model and known
limitations.

## Development and contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, testing, and contribution
guidelines.

## License

MIT
