Metadata-Version: 2.4
Name: dev-vault
Version: 0.1.2
Summary: Developer secret vault + OIDC token provider — for developers, scripts, and AI agents
Author: Caetano Minuzzo
License-Expression: MIT
Project-URL: Homepage, https://github.com/caetanominuzzo/dev-vault
Project-URL: Repository, https://github.com/caetanominuzzo/dev-vault
Project-URL: Issues, https://github.com/caetanominuzzo/dev-vault/issues
Project-URL: Changelog, https://github.com/caetanominuzzo/dev-vault/releases
Keywords: vault,secrets,keyring,cli,oidc,keycloak,token,oauth,ai-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: rich>=13.0.0
Requires-Dist: inquirer>=3.0.0
Requires-Dist: keyring>=24.0.0
Dynamic: license-file

# dev-vault

**All your secrets in one command.** Developer secret vault + OIDC token provider for developers, scripts, and AI agents.

## Why dev-vault?

AI agents need secrets (API keys, bearer tokens) but can't safely read `.env` files, and hardcoding secrets in prompts is a security risk. dev-vault stores secrets in your OS keyring and exposes them via a simple CLI -- the secret never appears in conversation context, only where it's needed.

## Quick Start

```bash
pip install dev-vault
```

### Store a secret

```bash
dv set datadog api_key           # prompts for value (masked)
dv set datadog api_key "abc123"  # inline (for scripts)
dv set datadog app_key "def456"  # multiple fields per item
```

### Retrieve a secret

```bash
dv get datadog                   # primary field -> stdout
dv get datadog api_key           # specific field (planned: prefix matching)
dv get default datadog api_key   # explicit vault
```

### Use with AI agents

```bash
# Agent prompt: "use dv to get the bearer for the endpoint /api/motorcycles"
curl -H "Authorization: Bearer $(dv get prod caetano)" https://api.mottu.com/api/motorcycles

# Agent prompt: "query datadog for error rates"
DD_API_KEY=$(dv get datadog) python check_errors.py

# Or with dv run -- agent just says "run the script"
dv run -- python check_errors.py   # secrets injected from .dv.yaml
```

### Run commands with secrets injected

```bash
# Explicit mapping
dv run -s DD_API_KEY=datadog/api_key -s DD_APP_KEY=datadog/app_key -- python app.py

# Using .dv.yaml manifest (checked into git, no secrets)
dv run -- python app.py
```

### Project manifest (`.dv.yaml`)

Place in your project root. Maps environment variables to secret references:

```yaml
secrets:
  DD_API_KEY: datadog/api_key
  DD_APP_KEY: datadog/app_key
  BEARER_TOKEN: prod/admin@example.com   # OIDC -> fresh token
```

### Template injection

```bash
echo 'KEY={{dv://default/datadog/api_key}}' | dv inject
# Output: KEY=abc123
```

## OIDC Token Provider

dev-vault can fetch fresh OIDC tokens from Keycloak (with more providers planned):

```bash
dv setup                         # interactive wizard
dv get prod admin@example.com    # returns a fresh access_token
dv get prod api-client           # client_credentials flow
```

### Migrating from sso-cli

```bash
pip install dev-vault
dv migrate sso-cli               # imports config + keyring secrets
dv get prod admin@example.com    # same token, new tool
```

## Commands

| Command | Description |
|---------|-------------|
| `dv get [vault] <item> [field]` | Retrieve secret or OIDC token |
| `dv set [vault] <item> <field> [value]` | Store a secret |
| `dv run [-s KEY=ref] -- <cmd>` | Run command with secrets as env vars |
| `dv inject` | Replace `{{dv://...}}` refs in stdin |
| `dv item list\|create\|show\|delete` | Manage items |
| `dv vault list\|create\|delete` | Manage vaults |
| `dv setup [--reset]` | Interactive setup wizard |
| `dv migrate sso-cli` | Import from sso-cli |
| `dv config show` | Display current config |

All commands support `--json` for programmatic output and `-v` for debug logging.

## Security

dev-vault is built with a strict security-first approach:

- **Secrets never touch disk.** All secret values are stored exclusively in the OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager). The config YAML only contains metadata (vault names, item names, field names, OIDC provider URLs).
- **No secrets in logs or output.** Debug/verbose mode (`-v`) never logs secret values. Human-friendly output goes to stderr; only raw secret values go to stdout (for `$(dv get ...)` substitution).
- **Masked input.** Interactive secret entry uses `getpass` (no terminal echo).
- **Subprocess isolation.** `dv run` injects secrets as environment variables only into the child process -- they don't leak into the parent shell or shell history.
- **No network calls for static secrets.** Only OIDC items make network requests, and only to the configured SSO endpoint.
- **Config file permissions.** The config directory (`~/.config/dev-vault/`) inherits your user's default umask. No world-readable files.
- **No telemetry.** dev-vault makes zero calls home. No analytics, no crash reporting.

### Supply chain

- Minimal dependencies: `httpx`, `pyyaml`, `keyring`, `rich`, `inquirer`, `pyperclip` -- all well-established, actively maintained packages.
- Published to PyPI with standard setuptools build.
- Source available on GitHub for audit.

## How It Works

- **Config** location: `~/.config/dev-vault/config.yaml` (XDG-compliant), fallback `~/.dv.yaml`. Override with `DV_CONFIG` env var.
- **OIDC items** fetch fresh tokens on every call (no caching, no stale tokens). Static items return stored keyring values.
- **Secret references** use `dv://vault/item/field` URIs or shorthand (`item/field`, `vault/item`).

---

PyPI package: https://pypi.org/project/dev-vault/

## See Also

- [Agent State](https://agentstate.tech/) -- Persistent memory and tools for AI agents
- [sso-cli](https://pypi.org/project/sso-cli/) -- Single Sign-On token CLI (the ancestor of dev-vault)
- [terminal-to-here](https://github.com/caetanominuzzo/terminal-to-here) -- VS Code extension to open terminal at any folder
