AAP Reference Implementation

Reference implementation of the Agent Authorization Profile (AAP) protocol.

Overview

This is the reference implementation of AAP, providing:

• Authorization Server (AS): Issues AAP tokens with agent, task, and capability claims
• Resource Server (RS): Validates AAP tokens and enforces constraints

Architecture

reference-impl/
├── as/                         # Authorization Server
│   ├── __init__.py
│   ├── __main__.py             # Entry point: python3 -m as
│   ├── server.py               # Flask HTTP server
│   ├── token_issuer.py         # Token generation & exchange
│   ├── policy_engine.py        # Policy evaluation
│   └── config.py               # Configuration
├── rs/                         # Resource Server
│   ├── __init__.py
│   ├── __main__.py             # Entry point: python3 -m rs
│   ├── server.py               # Flask HTTP server
│   ├── validator.py            # Token validation
│   ├── capability_matcher.py   # Action matching
│   └── constraint_enforcer.py  # Constraint enforcement
├── policies/                   # Operator policy definitions
│   └── org-acme-corp.json      # Example policy
├── keys/                       # Signing keys (generated)
├── tests/                      # Test suite
│   ├── conftest.py             # Shared fixtures
│   ├── test_token_issuance.py  # AS token issuance
│   ├── test_token_exchange.py  # Delegation via token exchange
│   ├── test_validation.py      # RS token validation
│   ├── test_constraints.py     # Constraint enforcement
│   ├── test_capability_matcher.py  # Action matching
│   └── test_integration.py     # End-to-end tests
├── scripts/
│   └── generate_keys.sh        # Generate ES256 signing keys
└── requirements.txt            # Python dependencies

Quick Start

Prerequisites

• Python 3.9+
• pip
• OpenSSL (for key generation)

Installation

cd reference-impl

# Install dependencies
pip install -r requirements.txt

# Generate signing keys
bash scripts/generate_keys.sh

Running the Servers

Authorization Server:

cd reference-impl
python3 -m as
# Runs on http://localhost:8080

Resource Server:

cd reference-impl
python3 -m rs
# Runs on http://localhost:8081

Request a Token

curl -X POST http://localhost:8080/token \
  -d "grant_type=client_credentials" \
  -d "client_id=agent-01" \
  -d "client_secret=secret" \
  -d "operator=org:acme-corp" \
  -d "task_id=task-1" \
  -d "task_purpose=research" \
  -d "capabilities=search.web" \
  -d "audience=https://api.example.com"

Use the Token

# Use token at Resource Server
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8081/api/search?q=test&url=https://example.org/data"

Verify JWKS

curl http://localhost:8080/.well-known/jwks.json

Features

Authorization Server

• Token issuance with AAP claims (agent, task, capabilities, delegation, oversight, audit)
• ES256 (ECDSA P-256) signing
• JWKS endpoint with real public key export
• OAuth 2.0 metadata endpoint (RFC 8414)
• Token Exchange for delegation (RFC 8693)
• Policy-based capability evaluation
• Privilege reduction (50% per delegation level)
• Domain narrowing during delegation

Resource Server

• JWT validation (signature, expiration, audience, issuer)
• Agent identity validation
• Task binding validation
• Delegation chain validation (depth + chain length)
• Capability matching with ABNF format validation
• Constraint enforcement:
  • Rate limits (per-minute, per-hour, per-day)
  • Domain allowlist/blocklist with DNS suffix matching
  • Time windows (ISO 8601)
  • HTTP method restrictions
  • Request size limits
• Human oversight enforcement

Running Tests

cd reference-impl

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=as --cov=rs --tb=short

# Run specific test file
pytest tests/test_integration.py -v

Configuration

Environment Variables

Variable	Default	Description
AAP_ISSUER	https://as.example.com	AS issuer identifier
AAP_AS_PORT	8080	AS listen port
AAP_AS_HOST	0.0.0.0	AS listen host
AAP_DEFAULT_TOKEN_LIFETIME	3600	Token lifetime (seconds)
AAP_SIGNING_ALGORITHM	ES256	JWT signing algorithm
AAP_PRIVATE_KEY_PATH	keys/as_private_key.pem	Path to private key
AAP_PUBLIC_KEY_PATH	keys/as_public_key.pem	Path to public key
AAP_KEY_ID	aap-as-key-1	Key ID for JWKS
AAP_POLICY_PATH	policies	Path to policy directory
AAP_RS_PORT	8081	RS listen port
AAP_RS_AUDIENCE	https://api.example.com	RS audience identifier
AAP_TRUSTED_ISSUERS	https://as.example.com	Comma-separated trusted issuers
AAP_DEBUG	false	Enable Flask debug mode

Links

• AAP Specification
• Draft Improvements
• Test Vectors

License

Apache License 2.0