Metadata-Version: 2.4
Name: mevault
Version: 0.3.0
Summary: MeVault Python SDK — request secrets from the local MeVault broker
Project-URL: Homepage, https://github.com/thecalebyte/mevault-cli
Project-URL: Documentation, https://github.com/thecalebyte/mevault-cli/blob/main/docs/sdk.md
Project-URL: Bug Tracker, https://github.com/thecalebyte/mevault-cli/issues
License: Apache-2.0
Keywords: credentials,mevault,secrets,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# MeVault Python SDK

Request secrets from the [MeVault](https://github.com/thecalebyte/mevault-cli) broker in Python — no passwords, no env-var leakage, no subprocesses.

## Requirements

- Python 3.9+
- Windows (the broker communicates over a Windows named pipe)
- MeVault broker running and vault unlocked

## Installation

```bash
pip install mevault
```

Or from source:

```bash
cd sdk/python
pip install -e .
```

## Usage

### Synchronous

```python
from mevault import get_secret, get_optional_secret
from mevault.exceptions import VaultLocked, SecretNotFound, MeVaultUnavailable

# Raises SecretNotFound if the secret doesn't exist.
db_password = get_secret("DB_PASSWORD")

# Returns None (or a custom default) if the secret doesn't exist.
api_key = get_optional_secret("OPTIONAL_API_KEY", default="")
```

### Asynchronous

```python
import asyncio
from mevault import async_get_secret

async def main():
    token = await async_get_secret("AUTH_TOKEN")
    # use token ...

asyncio.run(main())
```

## Error handling

| Exception | When raised |
|---|---|
| `MeVaultUnavailable` | Broker not running / pipe not found |
| `VaultLocked` | Vault is locked — user must unlock MeVault |
| `SecretNotFound` | No secret with that name |
| `AccessDenied` | Process not permitted to read the secret |
| `SessionExpired` | Broker session expired — user must re-authenticate |
| `ProtocolError` | Malformed or oversized broker response |

All exceptions derive from `MeVaultError`.

```python
from mevault.exceptions import MeVaultError

try:
    value = get_secret("MY_SECRET")
except MeVaultError as exc:
    # Handle any MeVault error generically.
    print(f"MeVault error: {exc}")
```

## Security notes

- Secret values are **never** logged or printed by the SDK.
- `SecretValue.__repr__` and `__str__` return `<redacted>` to prevent accidental exposure in logs or tracebacks.
- The SDK does **not** accept vault passwords and does **not** spawn subprocesses.
- The SDK does **not** place secrets in environment variables.
- Each request uses a fresh pipe connection, closed immediately after the response is received.
