Metadata-Version: 2.4
Name: naturalis-vault
Version: 0.2.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
uv add naturalis-vault

# pip
pip install naturalis-vault
```

## Usage

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

# Obtain a token (opens browser for OIDC login)
token = refresh_vault_token()

# Retrieve a secret
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. The package automatically retrieves the VAULT_TOKEN environment variable if it was set.

```python
vault = Vault(
    secret_path="team/project/production",
)
```

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

```python
import os
from datetime import date

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

# Consider the vault token to be fresh if it was last refreshed today
if os.getenv("VAULT_TOKEN_LAST_REFRESH") != today and token:
    token = refresh_vault_token()
    os.environ["VAULT_TOKEN"] = token
    os.environ["VAULT_TOKEN_LAST_REFRESH"] = today
```
