wais-pod 0.2.0

WAIS — Web Agent Interaction Standard. Core library for agent authentication and site integration.

wais-pod

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) ecosystem.

Install

pip install wais-pod

For FastAPI site integration:

pip install wais-pod[site]

Quick Start

Issuing a PoD Token

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

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:

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.algova.dev"],
)

@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)
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 — Full walkthrough for adding WAIS to your API
• WAIS Specification — Protocol specification

License

MIT — see LICENSE.

---

Built by Deeger.