Metadata-Version: 2.4
Name: secretpath
Version: 0.2.0
Summary: A tiny op-first secret resolver with environment fallback.
Keywords: 1password,op,secrets,credentials,environment
Author: Dan O'Leary
Author-email: Dan O'Leary <oleary.dj@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
Requires-Dist: typer>=0.19
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# secretpath

`secretpath` resolves application secrets from a short, explicit provider path:

1. 1Password CLI references through `op read`
2. Environment variables

It is designed for CLIs and local automation that should prefer 1Password when
available, fall back to environment variables when appropriate, and report where
the secret came from without logging the secret itself.

`secretpath` never writes resolved secret values to disk. Its cache is
process-local memory only.

## Install

```bash
pip install secretpath
```

For local development:

```bash
uv sync
uv run pytest
uv run ruff check src tests
```

## Quick Start

```python
from secretpath import resolve_secret

result = resolve_secret(
    "Canvas API key",
    provider="auto",
    op_reference="op://Vault/Canvas/credential",
    env_var="CANVAS_API_KEY",
)

api_key = result.value
print(f"Using API key from {result.source}")
```

Use environment variables to avoid putting `op://...` references in project
files:

```python
result = resolve_secret(
    "ANTHROPIC_API_KEY",
    provider_env="MYAPP_SECRET_PROVIDER",
    op_reference_env="MYAPP_ANTHROPIC_API_KEY_OP_REFERENCE",
)
```

For prefix-based project conventions:

```python
from secretpath import resolve_env_secret

result = resolve_env_secret("ANTHROPIC_API_KEY", prefix="PIPYER")
```

That reads:

- `PIPYER_SECRET_PROVIDER`
- `PIPYER_ANTHROPIC_API_KEY_OP_REFERENCE`
- `ANTHROPIC_API_KEY`

## Named Config

Local `.secretpath.toml` and global `~/.config/secretpath/config.toml` files can
store secret lookup metadata. They should contain references and environment
variable names, not resolved secret values.

```toml
[defaults]
provider = "auto"

[secrets.canvas]
env_var = "CANVAS_API_KEY"
op_reference = "op://Vault/Canvas/credential"

[secrets.anthropic]
env_var = "ANTHROPIC_API_KEY"
op_reference_env = "MYAPP_ANTHROPIC_API_KEY_OP_REFERENCE"
```

Then:

```python
from secretpath import resolve_named_secret

result = resolve_named_secret("canvas")
```

See [docs/config.md](docs/config.md) for precedence and file discovery.

## CLI

The CLI checks whether a secret resolves without printing the secret:

```bash
secretpath check canvas
sp check canvas
secretpath check canvas --json
secretpath list
secretpath config path
secretpath config init
secretpath config show
secretpath doctor
secretpath doctor --check
sp direnv init openai anthropic
secretpath check ANTHROPIC_API_KEY --prefix PIPYER
secretpath check API_KEY --no-config --env-var API_KEY
python -m secretpath check canvas
```

`sp` is a short alias for the `secretpath` command.

See [docs/cli.md](docs/cli.md).

## Behavior

- `provider="auto"` tries `1password` first, then `env`.
- `provider="1password"` only tries `op read`.
- `provider="env"` only reads the environment variable.
- `env_var` defaults to `name`.
- environment-sourced results report `env:<env_var>`, such as `env:CANVAS_API_KEY`.
- `required=False` returns a `SecretMiss` with non-secret attempt metadata.
- resolved values are cached in process memory by default.
- `clear_cache()` clears the process-local cache.
- `clear_cache(name)` clears entries for one logical secret name.

Error messages name providers tried, but intentionally avoid including
`op://...` references, environment variable names, raw `op` stderr, or secret
values.

## Documentation

- [API reference](docs/api.md)
- [Configuration files](docs/config.md)
- [CLI usage](docs/cli.md)
- [Integration patterns](docs/integrations.md)
- [Security model](docs/security.md)

## Why No Durable Secret Cache?

`secretpath` treats 1Password or the environment as the durable authority. A
disk cache would create another secret store with weaker rotation and audit
semantics. The built-in cache is intentionally limited to the current Python
process.
