Metadata-Version: 2.4
Name: auraprotector-agent
Version: 0.2.0
Summary: AuraProtector in-process agent for Python ASGI runtimes.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/auraguard-co/AuraProtector
Project-URL: Repository, https://github.com/auraguard-co/AuraProtector
Project-URL: Issues, https://github.com/auraguard-co/AuraProtector/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.26
Requires-Dist: cryptography>=42
Dynamic: license-file

# auraprotector-agent (Python)

Python in-process agent for ASGI runtimes (FastAPI/Starlette/etc).

## Install

```bash
pip install auraprotector-agent
```

## FastAPI usage

```py
from fastapi import FastAPI
from auraprotector_agent.asgi import UltimateProtectorMiddleware

app = FastAPI()

app.add_middleware(
    UltimateProtectorMiddleware,
    license_key="UP_LIVE_...",
    api_url="https://YOUR_CLOUD/api",
)

```

## Zero-code-ish usage (env wrapper)

If you can change *how* the app is created (but don't want to paste config into code),
wrap the ASGI app using env vars:

```py
import os
from fastapi import FastAPI
from auraprotector_agent import wrap_asgi_app

app = wrap_asgi_app(FastAPI())

# env:
# UP_LICENSE_KEY=UP_LIVE_...
# UP_API_URL=https://YOUR_CLOUD/api
```

### Optional: sitecustomize bootstrap

The platform can generate a `sitecustomize.py` helper inside the **Python auto bundle**.
If that file is on `PYTHONPATH`, Python auto-imports it on startup.
Set `UP_ASGI_APP="module:app"` and it will best-effort wrap that object automatically (fail-open).

## Notes

- PyPI distribution name: `auraprotector-agent`
- Import path: `auraprotector_agent` (recommended)
- Legacy import path still supported: `ultimateprotector_agent`


## Options

- `license_key` (required)
- `api_url` (required) e.g. `https://cloud.example/api`
- `sync_interval_seconds` (default: `60`)
- `allow_sample_rate` (default: `0.01`)
- `only_paths`: list[str] exact (`/checkout`) or prefix (`/product/*`)
- `except_paths`: list[str]
- `only_regex`: str (Python regex)

## Changelog

### 0.2.0

- **HMAC payload verification** — Rules payloads are now authenticated with HMAC-SHA256 before decryption. Requires platform ≥ 2026-04.
- **`X-Agent-Version` header** — Sent on every `/verify` request for dashboard version tracking.
- **`outdated` status handling** — If the cloud responds with `outdated`, the agent fails open and stops protecting until updated.

### 0.1.1

- Initial stable release with AES-256-CBC encrypted rules sync.
