Metadata-Version: 2.4
Name: naturalis-vault
Version: 0.1.0
Summary: OpenBao Vault wrapper for token generation and secret retrieval
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: hvac>=2.4
Description-Content-Type: text/markdown

# naturalis-vault

OpenBao Vault client library for Naturalis.

- `Vault`: reads secrets from Vault KV v2, given a token
- `refresh_vault_token`: obtains a token via OIDC authentication

The library never writes tokens or secrets to your filesystem. Token persistence
is up to the caller.

## Installation

```sh
uv add naturalis-vault
```

## Usage

```python
from naturalis.vault import Vault, refresh_vault_token

# Obtain a token (opens browser for OIDC login)
token = refresh_vault_token(server_url="https://vault.naturalis.io")

# Use it
vault = Vault(
    secret_path="team/project/production",
    token=token,
)

api_key = vault.get_secret("IMPORTANT_API_KEY")
```

To avoid having to log in on every run, store the token yourself (e.g. in an environment
variable) and pass it directly:

```python
vault = Vault(
    server_url="https://vault.naturalis.io",
    secret_path="team/project/production",
    token=os.getenv("VAULT_TOKEN"),
)
```

Or even monitor the token's last refresh date and regenerate it automatically:

```python
today = str(date.today())
token = os.getenv("VAULT_TOKEN")

# Consider the vault token to be fresh if it was last refreshed today
if not os.getenv("VAULT_TOKEN_LAST_REFRESH") == today and token:
    token = refresh_vault_token(server_url="https://vault.naturalis.io")
```
