Metadata-Version: 2.4
Name: wais-pod
Version: 0.2.3
Summary: WAIS — Web Agent Interaction Standard. Core library for agent authentication and site integration.
Project-URL: Homepage, https://deeger.io
Project-URL: Repository, https://github.com/deegerhq/wais-core
Project-URL: Documentation, https://deeger.io/wais
Author-email: Deeger <hello@deeger.io>
License: MIT
License-File: LICENSE
Keywords: agents,ai,authentication,delegation,wais
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: cryptography>=41.0.0
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Requires-Dist: httpx>=0.25.0; extra == 'fastapi'
Description-Content-Type: text/markdown

# wais-pod

[![PyPI](https://img.shields.io/pypi/v/wais-pod?color=blue)](https://pypi.org/project/wais-pod/)
[![Python](https://img.shields.io/pypi/pyversions/wais-pod)](https://pypi.org/project/wais-pod/)
[![CI](https://github.com/deegerhq/wais-core/actions/workflows/ci.yml/badge.svg)](https://github.com/deegerhq/wais-core/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**Proof of Delegation (PoD)** — Open-source authentication for AI agents.

An open protocol enabling AI agents to prove they act on behalf of authenticated human users with verifiable, scoped authorization. Part of the [WAIS (Web Agent Interaction Standard)](https://deeger.io/wais) ecosystem.

## Install

```bash
pip install wais-pod
```

For FastAPI site integration:

```bash
pip install wais-pod[site]
```

## Quick Start

### Issuing a PoD Token

```python
from pod import PoDIssuer

issuer = PoDIssuer(private_key_pem=YOUR_PRIVATE_KEY)

token = issuer.issue(
    user_hash="sha256-of-user-id",
    agent_id="agent-123",
    audience="https://api.example.com",
    scopes=["api.access", "search.execute"],
    ttl=3600,
)

print(token.compact)  # signed JWT
```

### Verifying a Token

```python
from pod import PoDVerifier

verifier = PoDVerifier(public_key_pem=PLATFORM_PUBLIC_KEY)
result = verifier.verify(token_string, expected_audience="https://api.example.com")

if result.valid:
    print(f"User: {result.user_hash}, Scopes: {result.scopes}")
```

### Site Integration (FastAPI)

Add WAIS support to your existing API in minutes — no breaking changes:

```python
from fastapi import FastAPI, Depends
from contextlib import asynccontextmanager
from pod.site import WAISAuth

wais = WAISAuth(
    site_url="https://api.yoursite.com",
    platform_urls=["https://pod.deeger.io"],
)

@asynccontextmanager
async def lifespan(app):
    await wais.setup()  # fetches platform JWKS
    yield

app = FastAPI(lifespan=lifespan)

@app.post("/v1/search")
async def search(auth=Depends(wais.require(scopes=["api.access"]))):
    if auth.is_wais:
        print(f"WAIS agent acting for user {auth.user_hash}")
    else:
        print(f"Traditional API key: {auth.client}")
```

## What's Inside

| Module | Purpose |
|--------|---------|
| `pod.token` | PoD token data models (JWT payload, constraints, scopes) |
| `pod.issuer` | Token creation and ES256 signing |
| `pod.verifier` | 12-step token verification |
| `pod.dpop` | DPoP proof-of-possession ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) |
| `pod.sd_jwt` | Selective Disclosure JWTs for privacy-preserving identity |
| `pod.scopes` | 30+ standard WAIS scopes with risk levels + custom `x-` scopes |
| `pod.confirmation` | Async challenge/response for high-risk ops and payments |
| `pod.site` | Drop-in FastAPI integration with dual auth |

## Key Concepts

- **Proof of Delegation**: A signed JWT proving an AI agent is authorized to act on behalf of a specific user, with scoped permissions and time limits.
- **DPoP Binding**: Tokens are bound to the agent's key pair — stolen tokens can't be replayed by another agent.
- **Hybrid Scopes**: Standard scopes (fixed risk levels) + custom `x-` scopes (site-defined) + freeform actions.
- **Confirmation Flow**: High-risk operations trigger 402 challenges. Agents poll for user confirmation or payment completion.
- **SD-JWT Passport**: Users carry a privacy-preserving digital identity. Sites request only the claims they need.

## Requirements

- Python >= 3.10
- `cryptography >= 41.0.0` (only runtime dependency)

## Documentation

- [Site Integration Guide](docs/SITE-INTEGRATION.md) — Full walkthrough for adding WAIS to your API
- [WAIS Specification](https://deeger.io/wais) — Protocol specification

## License

MIT — see [LICENSE](LICENSE).

---

Built by [Deeger](https://deeger.io).
