Metadata-Version: 2.4
Name: pv-dotenv
Version: 0.1.0
Summary: Drop-in replacement for python-dotenv that resolves psamvault: placeholders at runtime
Author-email: Marvinphil Annorbah <mphilannorbah@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/psam-717/psamvault
Project-URL: Repository, https://github.com/psam-717/psamvault
Project-URL: Documentation, https://github.com/psam-717/psamvault
Keywords: psamvault,dotenv,env,secrets,credentials,vault
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
Requires-Dist: keyring>=24.0
Requires-Dist: cryptography>=41.0
Requires-Dist: httpx>=0.25
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"

# pv-dotenv

**Drop-in replacement for `python-dotenv`** that resolves `psamvault:` placeholders at runtime.

Keep your `.env` files safe from AI agents. The agent sees only placeholders. Your app gets the real secrets.

## Why?

```env
# Before: secrets in plaintext — any agent reading .env can see them
DATABASE_URL=postgresql://user:password@neon.tech/db
JWT_SECRET=your-secret-key

# After: placeholders — agent sees nothing, app resolves at runtime
DATABASE_URL=psamvault:DATABASE_URL
JWT_SECRET=psamvault:JWT_SECRET
```

## Installation

```bash
pip install pv-dotenv
```

## Quick Start

Replace your existing `dotenv` import:

```python
# Before (python-dotenv):
from dotenv import load_dotenv
load_dotenv()

# After (pv-dotenv):
from pv_dotenv import load_dotenv
load_dotenv()
```

**Everything else stays the same.** Your code reads from `os.environ` exactly as before.

### With project scoping

If you used `scan_and_protect(project_name="my-project")`, pass the same name:

```python
load_dotenv(project_name="my-project")
```

### Without modifying `os.environ`

```python
from pv_dotenv import resolve_dotenv

values = resolve_dotenv()
# → {"DATABASE_URL": "postgresql://...", "JWT_SECRET": "..."}
```

### Override existing env vars

By default, existing environment variables are **not** overwritten. To force override:

```python
load_dotenv(override=True)
```

## How It Works

1. Reads your `.env` file (or custom path)
2. For each `psamvault:KEY` value:
   - Fetches the encrypted blob from the psamvault backend
   - Decrypts it locally using your Vault Encryption Key (VEK)
   - Sets `os.environ[KEY]` to the real value
3. Non-`psamvault:` values (like `NODE_ENV=production`) pass through unchanged

### Auth

| Path | Source | Works Where |
|------|--------|-------------|
| **A: OS Keychain** | `psamvault login` | Your dev machine |
| **B: Env Vars** | `PSAMVAULT_VEK` + `PSAMVAULT_TOKEN` | Docker, CI, servers |

Path A requires no setup beyond `psamvault login`. Path B is for environments without a keychain (Docker, CI, servers).

## Prerequisites

- Python 3.10+
- A psamvault account — `pipx install psamvault` and `psamvault login`

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest
```

## Related

| Package | What It Does |
|---------|-------------|
| [`psamvault-cli`](https://github.com/psam-717/psamvault-cli) | CLI + MCP server — manage your vault |
| `pv-dotenv` | SDK — resolve placeholders at runtime |
