@dupecom/botcha-cloudflare 0.15.0 → 0.18.0

package/dist/static.js

@@ -87,6 +87,59 @@ curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 | \`POST\` | \`/v1/sessions/tap\` | Create TAP session with intent validation |
 | \`GET\` | \`/v1/sessions/:id/tap\` | Get TAP session info |
 
+### TAP Full Spec — JWKS & Keys (v0.16.0)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/.well-known/jwks\` | JWK Set for app's TAP agents (Visa spec standard) |
+| \`GET\` | \`/v1/keys\` | List keys (supports ?keyID= for Visa compat) |
+| \`GET\` | \`/v1/keys/:keyId\` | Get specific key by ID |
+| \`POST\` | \`/v1/agents/:id/tap/rotate-key\` | Rotate agent's key pair |
+
+### TAP Full Spec — 402 Micropayments (v0.16.0)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/invoices\` | Create invoice for gated content |
+| \`GET\` | \`/v1/invoices/:id\` | Get invoice details |
+| \`POST\` | \`/v1/invoices/:id/verify-iou\` | Verify Browsing IOU |
+
+### TAP Full Spec — Verification (v0.16.0)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/verify/consumer\` | Verify Agentic Consumer (Layer 2) |
+| \`POST\` | \`/v1/verify/payment\` | Verify Agentic Payment Container (Layer 3) |
+| \`POST\` | \`/v1/verify/delegation\` | Verify delegation chain validity |
+| \`POST\` | \`/v1/verify/attestation\` | Verify attestation token + check capability |
+
+### Delegation Chains
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/delegations\` | Create delegation (grantor→grantee) |
+| \`GET\` | \`/v1/delegations/:id\` | Get delegation details |
+| \`GET\` | \`/v1/delegations\` | List delegations for agent |
+| \`POST\` | \`/v1/delegations/:id/revoke\` | Revoke delegation (cascades) |
+
+### Capability Attestation
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`POST\` | \`/v1/attestations\` | Issue attestation token (can/cannot rules) |
+| \`GET\` | \`/v1/attestations/:id\` | Get attestation details |
+| \`GET\` | \`/v1/attestations\` | List attestations for agent |
+| \`POST\` | \`/v1/attestations/:id/revoke\` | Revoke attestation |
+
+### Agent Reputation Scoring
+
+| Method | Path | Description |
+|--------|------|-------------|
+| \`GET\` | \`/v1/reputation/:agent_id\` | Get agent reputation score |
+| \`POST\` | \`/v1/reputation/events\` | Record a reputation event |
+| \`GET\` | \`/v1/reputation/:agent_id/events\` | List reputation events |
+| \`POST\` | \`/v1/reputation/:agent_id/reset\` | Reset reputation (admin) |
+
 ### Challenges
 
 | Method | Path | Description |
@@ -262,8 +315,10 @@ API-Format: OpenAPI 3.1.0
 
 # Documentation
 Docs: https://botcha.ai
+Docs: https://botcha.ai/whitepaper
 Docs: https://github.com/dupe-com/botcha#readme
 Docs: https://www.npmjs.com/package/@dupecom/botcha
+Whitepaper: https://botcha.ai/whitepaper
 
 # Verification Methods
 Feature: Web Bot Auth (cryptographic signatures)
@@ -287,6 +342,7 @@ Feature: Trusted Agent Protocol (TAP) — cryptographic agent auth with HTTP Mes
 Feature: TAP Capabilities (action + resource scoping for agent sessions)
 Feature: TAP Trust Levels (basic, verified, enterprise)
 Feature: TAP Showcase Homepage (botcha.ai — one of the first services to implement Visa's Trusted Agent Protocol)
+Feature: TAP Full Spec v0.16.0 — Ed25519, RFC 9421 full compliance, JWKS infrastructure, Layer 2 Consumer Recognition, Layer 3 Payment Container, 402 micropayments, CDN edge verification, Visa key federation
 
 # Endpoints
 # Challenge Endpoints
@@ -341,6 +397,41 @@ Endpoint: GET https://botcha.ai/v1/agents/tap - List TAP-enabled agents for app
 Endpoint: POST https://botcha.ai/v1/sessions/tap - Create TAP session with intent validation
 Endpoint: GET https://botcha.ai/v1/sessions/:id/tap - Get TAP session info
 
+# TAP Full Spec — JWKS & Key Management (v0.16.0)
+Endpoint: GET https://botcha.ai/.well-known/jwks - JWK Set for app's TAP agents (Visa spec standard)
+Endpoint: GET https://botcha.ai/v1/keys - List keys (supports ?keyID= query for Visa compatibility)
+Endpoint: GET https://botcha.ai/v1/keys/:keyId - Get specific key by ID
+Endpoint: POST https://botcha.ai/v1/agents/:id/tap/rotate-key - Rotate agent's key pair
+
+# TAP Full Spec — 402 Micropayments (v0.16.0)
+Endpoint: POST https://botcha.ai/v1/invoices - Create invoice for gated content (402 flow)
+Endpoint: GET https://botcha.ai/v1/invoices/:id - Get invoice details
+Endpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IOU against invoice
+
+# TAP Full Spec — Consumer & Payment Verification (v0.16.0)
+Endpoint: POST https://botcha.ai/v1/verify/consumer - Verify Agentic Consumer object (Layer 2)
+Endpoint: POST https://botcha.ai/v1/verify/payment - Verify Agentic Payment Container (Layer 3)
+
+# TAP Delegation Chains (v0.17.0)
+Endpoint: POST https://botcha.ai/v1/delegations - Create delegation (grantor→grantee with capability subset)
+Endpoint: GET https://botcha.ai/v1/delegations/:id - Get delegation details
+Endpoint: GET https://botcha.ai/v1/delegations - List delegations for agent (?agent_id=&direction=in|out|both)
+Endpoint: POST https://botcha.ai/v1/delegations/:id/revoke - Revoke delegation (cascades to sub-delegations)
+Endpoint: POST https://botcha.ai/v1/verify/delegation - Verify entire delegation chain
+
+# TAP Capability Attestation (v0.17.0)
+Endpoint: POST https://botcha.ai/v1/attestations - Issue capability attestation token (can/cannot rules with action:resource patterns)
+Endpoint: GET https://botcha.ai/v1/attestations/:id - Get attestation details
+Endpoint: GET https://botcha.ai/v1/attestations - List attestations for agent (?agent_id=)
+Endpoint: POST https://botcha.ai/v1/attestations/:id/revoke - Revoke attestation (token rejected on future verification)
+Endpoint: POST https://botcha.ai/v1/verify/attestation - Verify attestation token + optionally check specific capability
+
+# Agent Reputation Scoring (v0.18.0)
+Endpoint: GET https://botcha.ai/v1/reputation/:agent_id - Get agent reputation score (0-1000, 5 tiers)
+Endpoint: POST https://botcha.ai/v1/reputation/events - Record a reputation event (18 action types, 6 categories)
+Endpoint: GET https://botcha.ai/v1/reputation/:agent_id/events - List reputation events (?category=&limit=)
+Endpoint: POST https://botcha.ai/v1/reputation/:agent_id/reset - Reset reputation to default (admin action)
+
 # Legacy Endpoints
 Endpoint: GET https://botcha.ai/api/challenge - Generate standard challenge
 Endpoint: POST https://botcha.ai/api/challenge - Verify standard challenge
@@ -411,7 +502,7 @@ Multi-Tenant-Token-Claim: Tokens include app_id claim when app_id provided
 # TRUSTED AGENT PROTOCOL (TAP)
 TAP-Description: Enterprise-grade cryptographic agent auth using HTTP Message Signatures (RFC 9421)
 TAP-Register: POST /v1/agents/register/tap with {name, public_key, signature_algorithm, capabilities, trust_level}
-TAP-Algorithms: ecdsa-p256-sha256, rsa-pss-sha256
+TAP-Algorithms: ed25519 (Visa recommended), ecdsa-p256-sha256, rsa-pss-sha256
 TAP-Trust-Levels: basic, verified, enterprise
 TAP-Capabilities: Array of {action, resource, constraints} — scoped access control
 TAP-Session-Create: POST /v1/sessions/tap with {agent_id, user_context, intent}
@@ -419,10 +510,26 @@ TAP-Session-Get: GET /v1/sessions/:id/tap — includes time_remaining
 TAP-Get-Agent: GET /v1/agents/:id/tap — includes public_key for verification
 TAP-List-Agents: GET /v1/agents/tap?app_id=...&tap_only=true
 TAP-Middleware-Modes: tap, signature-only, challenge-only, flexible
-TAP-SDK-TS: registerTAPAgent(options), getTAPAgent(agentId), listTAPAgents(tapOnly?), createTAPSession(options), getTAPSession(sessionId)
-TAP-SDK-Python: register_tap_agent(name, ...), get_tap_agent(agent_id), list_tap_agents(tap_only?), create_tap_session(agent_id, user_context, intent), get_tap_session(session_id)
+TAP-SDK-TS: registerTAPAgent(options), getTAPAgent(agentId), listTAPAgents(tapOnly?), createTAPSession(options), getTAPSession(sessionId), getJWKS(), getKeyById(keyId), rotateAgentKey(agentId), createInvoice(data), getInvoice(id), verifyBrowsingIOU(invoiceId, token), createDelegation(options), getDelegation(id), listDelegations(agentId, options?), revokeDelegation(id, reason?), verifyDelegationChain(id), issueAttestation(options), getAttestation(id), listAttestations(agentId), revokeAttestation(id, reason?), verifyAttestation(token, action?, resource?), getReputation(agentId), recordReputationEvent(options), listReputationEvents(agentId, options?), resetReputation(agentId)
+TAP-SDK-Python: register_tap_agent(name, ...), get_tap_agent(agent_id), list_tap_agents(tap_only?), create_tap_session(agent_id, user_context, intent), get_tap_session(session_id), get_jwks(), get_key_by_id(key_id), rotate_agent_key(agent_id), create_invoice(data), get_invoice(id), verify_browsing_iou(invoice_id, token), create_delegation(grantor_id, grantee_id, capabilities, ...), get_delegation(id), list_delegations(agent_id, ...), revoke_delegation(id, reason?), verify_delegation_chain(id), issue_attestation(agent_id, can, cannot?, ...), get_attestation(id), list_attestations(agent_id), revoke_attestation(id, reason?), verify_attestation(token, action?, resource?), get_reputation(agent_id), record_reputation_event(agent_id, category, action, ...), list_reputation_events(agent_id, category?, limit?), reset_reputation(agent_id)
 TAP-Middleware-Import: import { createTAPVerifyMiddleware } from '@dupecom/botcha/middleware'
 
+# TAP FULL SPEC v0.16.0
+TAP-RFC-9421: Full compliance — @authority, @path, expires, nonce, tag params
+TAP-Nonce-Replay: 8-minute TTL nonce-based replay protection
+TAP-Tags: agent-browser-auth (browsing), agent-payer-auth (payment)
+TAP-Layer-2: Agentic Consumer Recognition — OIDC ID tokens, obfuscated identity, contextual data
+TAP-Layer-3: Agentic Payment Container — card metadata, credential hash, encrypted payload, Browsing IOU
+TAP-JWKS: GET /.well-known/jwks — JWK Set endpoint for key discovery
+TAP-Key-Rotation: POST /v1/agents/:id/tap/rotate-key — rotate keys, invalidate old
+TAP-402-Flow: POST /v1/invoices → GET /v1/invoices/:id → POST /v1/invoices/:id/verify-iou
+TAP-Edge-Verify: createTAPEdgeMiddleware for Cloudflare Workers CDN edge verification
+TAP-Visa-Federation: Trust keys from https://mcp.visa.com/.well-known/jwks (3-tier cache: memory → KV → HTTP)
+TAP-Delegation: POST /v1/delegations → GET /v1/delegations/:id → POST /v1/delegations/:id/revoke → POST /v1/verify/delegation
+TAP-Attestation: POST /v1/attestations → GET /v1/attestations/:id → POST /v1/attestations/:id/revoke → POST /v1/verify/attestation
+TAP-Attestation-Patterns: action:resource format with wildcards (*:*, read:*, *:invoices), deny takes precedence over allow
+TAP-Attestation-Middleware: requireCapability('read:invoices') — Hono middleware, extracts token from X-Botcha-Attestation or Authorization: Bearer
+
 # EMBEDDED CHALLENGE (for bots visiting HTML pages)
 Embedded-Challenge: <script type="application/botcha+json">
 Embedded-Challenge-Location: In <head> of HTML pages
@@ -481,8 +588,160 @@ export const SITEMAP_XML = `<?xml version="1.0" encoding="UTF-8"?>
     <changefreq>monthly</changefreq>
     <priority>0.5</priority>
   </url>
+  <url>
+    <loc>https://botcha.ai/whitepaper</loc>
+    <changefreq>monthly</changefreq>
+    <priority>0.9</priority>
+  </url>
 </urlset>
 `;
+// Whitepaper markdown — served at /whitepaper with Accept: text/markdown
+export function getWhitepaperMarkdown() {
+    return `---
+title: "BOTCHA: Identity Infrastructure for the Agentic Web"
+version: "1.0"
+date: February 2026
+url: https://botcha.ai/whitepaper
+---
+
+# BOTCHA: Identity Infrastructure for the Agentic Web
+
+**Version 1.0 — February 2026**
+
+## 1. Executive Summary
+
+BOTCHA is a reverse CAPTCHA — a verification system that proves you are an AI agent, not a human. While traditional CAPTCHAs exist to block bots, BOTCHA exists to welcome them.
+
+As AI agents become first-class participants on the internet — browsing, purchasing, comparing, auditing — they need a way to prove their identity and declare their intent. BOTCHA provides three layers of proof:
+
+- **Proof of AI** — Computational challenges (SHA-256 hashes in under 500ms) that only machines can solve.
+- **Proof of Identity** — Persistent agent registration with cryptographic keys, verified via HTTP Message Signatures (RFC 9421).
+- **Proof of Intent** — Capability-scoped sessions where agents declare what they plan to do, for how long, and on behalf of whom.
+
+BOTCHA is open source, free to use, and deployed at https://botcha.ai.
+
+## 2. The Problem: Who Is This Agent?
+
+The internet was built for humans. Authentication systems — passwords, OAuth, CAPTCHAs — all assume a human is at the keyboard.
+
+AI agents are now browsing product catalogs, comparing prices, purchasing goods, auditing compliance, and negotiating contracts. When an agent hits your API, existing infrastructure cannot answer three critical questions:
+
+1. **Is this actually an AI agent?** User-Agent strings are trivially spoofable.
+2. **Which specific agent is this?** Even knowing it is AI, you do not know its organization or track record.
+3. **What does it intend to do?** Traditional auth grants blanket access — it does not capture intent.
+
+## 3. BOTCHA: Reverse CAPTCHA for AI Agents
+
+A CAPTCHA asks: *Can you identify traffic lights?* A human can; a bot struggles.
+BOTCHA asks: *Can you compute 5 SHA-256 hashes in 500ms?* A machine can; a human cannot.
+
+### Design Principles
+
+- **Agent-first, always.** Every flow requires an AI agent as participant. No human-only login paths.
+- **Fail-open on infrastructure errors.** Blocking legitimate traffic is worse than allowing an unverified request.
+- **Zero configuration to start.** Solve one challenge, get a token. No registration required.
+
+## 4. The Challenge System
+
+| Challenge | Tests | Time Limit | Best For |
+|-----------|-------|------------|----------|
+| Speed | SHA-256 computation | 500ms | Quick verification |
+| Reasoning | Language understanding (6 categories, parameterized generators) | 30s | Proving AI comprehension |
+| Hybrid | Speed + Reasoning combined | 35s | Default — strongest proof |
+| Compute | Prime generation + hashing | 3-10s | High-value operations |
+
+**RTT-aware fairness:** Time limits adjust for network latency (max 5s cap).
+**Anti-replay:** Challenges deleted from storage on first verification attempt.
+**Anti-gaming:** Parameterized question generators; no static question bank.
+
+## 5. The Trusted Agent Protocol (TAP)
+
+Solving a challenge proves you are *a bot*. TAP proves you are *a specific, trusted bot*.
+
+Inspired by Visa's Trusted Agent Protocol (https://developer.visa.com/capabilities/trusted-agent-protocol/overview), BOTCHA's TAP provides:
+
+- **Persistent agent identity** — unique ID, name, operator metadata
+- **Cryptographic verification** — ECDSA P-256 / RSA-PSS public keys; HTTP Message Signatures (RFC 9421)
+- **Capability-based access control** — browse, search, compare, purchase, audit
+- **Intent-scoped sessions** — time-limited, validated against capabilities
+- **Trust levels** — basic, verified, enterprise
+
+### Verification Hierarchy
+
+| Layer | Proves | Mechanism |
+|-------|--------|-----------|
+| Anonymous | "I am a bot" | Speed challenge <500ms |
+| App-scoped | "I belong to this org" | Challenge + app_id |
+| Agent identity | "I am this specific bot" | Registered ID + capabilities |
+| Cryptographic | "I can prove it" | RFC 9421 signatures |
+| Dual auth | "Verified + proven" | Challenge + signature |
+| Intent-scoped | "I intend to do this now" | Validated session |
+
+## 6. Architecture
+
+- **Runtime:** Cloudflare Workers (300+ edge locations)
+- **Storage:** Workers KV with TTLs
+- **Tokens:** HMAC-SHA256 JWTs (5-min access, 1-hr refresh)
+- **TAP Signatures:** ECDSA P-256 or RSA-PSS SHA-256
+- **Rate Limits:** 100 challenges/hour/app (fail-open)
+
+## 7. Integration
+
+### Client SDKs
+
+\`\`\`typescript
+import { BotchaClient } from '@dupecom/botcha';
+const client = new BotchaClient();
+const response = await client.fetch('https://api.example.com/products');
+\`\`\`
+
+\`\`\`python
+from botcha import BotchaClient
+async with BotchaClient() as client:
+    response = await client.fetch("https://api.example.com/products")
+\`\`\`
+
+### Server-side Verification
+
+Express: \`@botcha/verify\` · FastAPI/Django: \`botcha-verify\` · Hono middleware included.
+
+### CLI
+
+\`\`\`bash
+npm install -g @dupecom/botcha-cli
+botcha init --email you@company.com
+botcha tap register --name "my-agent" --capabilities browse,search
+botcha tap session --action browse --resource products --duration 1h
+\`\`\`
+
+## 8. The Agent Infrastructure Stack
+
+\`\`\`
+Layer 3: Identity        TAP (BOTCHA)     Who agents are
+Layer 2: Communication   A2A (Google)     How agents talk
+Layer 1: Tools           MCP (Anthropic)  What agents access
+\`\`\`
+
+MCP gives agents tools. A2A lets agents communicate. TAP proves identity and scopes authorization.
+
+## 9. Use Cases
+
+- **E-commerce:** Agents register capabilities, create scoped purchase sessions, full audit trail.
+- **API access control:** Speed challenge gates endpoints; no API keys needed.
+- **Multi-agent systems:** Coordinator delegates to capability-scoped sub-agents.
+- **Compliance:** TAP audit logging records every agent interaction with intent and context.
+
+## 10. Roadmap
+
+**Shipped:** Challenge types, JWT tokens, multi-tenant apps, agent registry, TAP, dashboard, SDKs (TS/Python), CLI, LangChain, discovery standards.
+
+**Planned:** Agent SSO (cross-service verification), IETF RFC contribution.
+
+---
+
+Website: https://botcha.ai · GitHub: https://github.com/dupe-com/botcha · npm: @dupecom/botcha · PyPI: botcha
+`;
+}
 // OpenAPI spec - keeping this as a function to allow dynamic version
 export function getOpenApiSpec(version) {
     return {
@@ -1167,7 +1426,7 @@ export function getOpenApiSpec(version) {
                                         "operator": { type: "string", description: "Operator/organization name" },
                                         "version": { type: "string", description: "Agent version" },
                                         "public_key": { type: "string", description: "PEM-encoded public key" },
-                                        "signature_algorithm": { type: "string", enum: ["ecdsa-p256-sha256", "rsa-pss-sha256"], description: "Signature algorithm (required if public_key provided)" },
+                                        "signature_algorithm": { type: "string", enum: ["ed25519", "ecdsa-p256-sha256", "rsa-pss-sha256"], description: "Signature algorithm (required if public_key provided)" },
                                         "trust_level": { type: "string", enum: ["basic", "verified", "enterprise"], description: "Agent trust level (default: basic)" },
                                         "capabilities": {
                                             type: "array",
@@ -1294,6 +1553,555 @@ export function getOpenApiSpec(version) {
                         "404": { description: "Session not found or expired" }
                     }
                 }
+            },
+            "/.well-known/jwks": {
+                get: {
+                    summary: "Get JWK Set (Visa TAP spec standard)",
+                    description: "Retrieve the JWK Set containing public keys for all TAP agents registered in your app. Follows Visa TAP specification standard.",
+                    operationId: "getJWKS",
+                    responses: {
+                        "200": {
+                            description: "JWK Set with array of keys",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            "keys": {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        "kty": { type: "string", description: "Key type (EC, RSA, OKP)" },
+                                                        "kid": { type: "string", description: "Key ID" },
+                                                        "use": { type: "string", description: "Public key use (sig)" },
+                                                        "alg": { type: "string", description: "Algorithm (ES256, RS256, EdDSA)" }
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "/v1/keys": {
+                get: {
+                    summary: "List keys or get key by ID",
+                    description: "List all keys or get a specific key using ?keyID= query parameter (Visa compatibility).",
+                    operationId: "getKeys",
+                    parameters: [
+                        {
+                            name: "keyID",
+                            in: "query",
+                            schema: { type: "string" },
+                            description: "Optional key ID for Visa TAP compatibility"
+                        }
+                    ],
+                    responses: {
+                        "200": { description: "Key list or specific key" }
+                    }
+                }
+            },
+            "/v1/keys/{keyId}": {
+                get: {
+                    summary: "Get key by ID",
+                    description: "Retrieve a specific public key by key ID.",
+                    operationId: "getKeyById",
+                    parameters: [
+                        {
+                            name: "keyId",
+                            in: "path",
+                            required: true,
+                            schema: { type: "string" }
+                        }
+                    ],
+                    responses: {
+                        "200": { description: "Public key details" },
+                        "404": { description: "Key not found" }
+                    }
+                }
+            },
+            "/v1/agents/{id}/tap/rotate-key": {
+                post: {
+                    summary: "Rotate agent key pair",
+                    description: "Generate a new key pair for the agent and invalidate the old one.",
+                    operationId: "rotateAgentKey",
+                    parameters: [
+                        {
+                            name: "id",
+                            in: "path",
+                            required: true,
+                            schema: { type: "string" }
+                        }
+                    ],
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "algorithm": {
+                                            type: "string",
+                                            enum: ["ed25519", "ecdsa-p256-sha256", "rsa-pss-sha256"],
+                                            description: "Algorithm for new key (default: ed25519)"
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Key rotated successfully" }
+                    }
+                }
+            },
+            "/v1/invoices": {
+                post: {
+                    summary: "Create invoice for 402 micropayment",
+                    description: "Create an invoice for gated content. Used with Browsing IOU flow.",
+                    operationId: "createInvoice",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["amount", "currency", "description"],
+                                    properties: {
+                                        "amount": { type: "integer", description: "Amount in cents" },
+                                        "currency": { type: "string", description: "Currency code (USD, EUR, etc.)" },
+                                        "description": { type: "string" },
+                                        "metadata": { type: "object" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "201": { description: "Invoice created" }
+                    }
+                }
+            },
+            "/v1/invoices/{id}": {
+                get: {
+                    summary: "Get invoice details",
+                    operationId: "getInvoice",
+                    parameters: [
+                        {
+                            name: "id",
+                            in: "path",
+                            required: true,
+                            schema: { type: "string" }
+                        }
+                    ],
+                    responses: {
+                        "200": { description: "Invoice details" },
+                        "404": { description: "Invoice not found" }
+                    }
+                }
+            },
+            "/v1/invoices/{id}/verify-iou": {
+                post: {
+                    summary: "Verify Browsing IOU",
+                    description: "Verify a Browsing IOU (payment intent token) against an invoice.",
+                    operationId: "verifyBrowsingIOU",
+                    parameters: [
+                        {
+                            name: "id",
+                            in: "path",
+                            required: true,
+                            schema: { type: "string" }
+                        }
+                    ],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["iou_token"],
+                                    properties: {
+                                        "iou_token": { type: "string" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "IOU verified" },
+                        "400": { description: "Invalid IOU" }
+                    }
+                }
+            },
+            "/v1/verify/consumer": {
+                post: {
+                    summary: "Verify Agentic Consumer object (Layer 2)",
+                    description: "Verify an agenticConsumer object including ID token, contextual data, and signature chain.",
+                    operationId: "verifyConsumer",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["agenticConsumer", "signature"],
+                                    properties: {
+                                        "agenticConsumer": {
+                                            type: "object",
+                                            properties: {
+                                                "idToken": { type: "string", description: "OIDC ID token" },
+                                                "country": { type: "string" },
+                                                "postalCode": { type: "string" },
+                                                "ipAddress": { type: "string" },
+                                                "nonce": { type: "string" }
+                                            }
+                                        },
+                                        "signature": { type: "string" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Consumer verified" },
+                        "400": { description: "Invalid consumer object" }
+                    }
+                }
+            },
+            "/v1/verify/payment": {
+                post: {
+                    summary: "Verify Agentic Payment Container (Layer 3)",
+                    description: "Verify an agenticPaymentContainer object including card metadata, credential hash, and encrypted payload.",
+                    operationId: "verifyPayment",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["agenticPaymentContainer", "signature"],
+                                    properties: {
+                                        "agenticPaymentContainer": {
+                                            type: "object",
+                                            properties: {
+                                                "lastFour": { type: "string" },
+                                                "par": { type: "string", description: "Payment Account Reference" },
+                                                "credentialHash": { type: "string" },
+                                                "encryptedPayload": { type: "string" },
+                                                "nonce": { type: "string" }
+                                            }
+                                        },
+                                        "signature": { type: "string" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Payment verified" },
+                        "400": { description: "Invalid payment container" }
+                    }
+                }
+            },
+            "/v1/delegations": {
+                post: {
+                    summary: "Create delegation",
+                    description: "Create a delegation from one agent to another. Grants a subset of the grantor's capabilities to the grantee.",
+                    operationId: "createDelegation",
+                    parameters: [{ name: "app_id", in: "query", required: true, schema: { type: "string" } }],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["grantor_id", "grantee_id", "capabilities"],
+                                    properties: {
+                                        "grantor_id": { type: "string", description: "Agent granting capabilities" },
+                                        "grantee_id": { type: "string", description: "Agent receiving capabilities" },
+                                        "capabilities": { type: "array", items: { type: "object" }, description: "Capabilities to delegate (subset of grantor's)" },
+                                        "duration_seconds": { type: "integer", description: "Duration in seconds (default: 3600)" },
+                                        "max_depth": { type: "integer", description: "Max sub-delegation depth (default: 3)" },
+                                        "parent_delegation_id": { type: "string", description: "Parent delegation ID for sub-delegation" },
+                                        "metadata": { type: "object", description: "Optional context metadata" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "201": { description: "Delegation created" },
+                        "400": { description: "Invalid request or capability escalation" },
+                        "403": { description: "Insufficient capabilities or depth limit" },
+                        "409": { description: "Cycle detected in chain" }
+                    }
+                },
+                get: {
+                    summary: "List delegations",
+                    description: "List delegations for an agent.",
+                    operationId: "listDelegations",
+                    parameters: [
+                        { name: "app_id", in: "query", required: true, schema: { type: "string" } },
+                        { name: "agent_id", in: "query", required: true, schema: { type: "string" } },
+                        { name: "direction", in: "query", schema: { type: "string", enum: ["in", "out", "both"] } },
+                        { name: "include_revoked", in: "query", schema: { type: "boolean" } },
+                        { name: "include_expired", in: "query", schema: { type: "boolean" } }
+                    ],
+                    responses: {
+                        "200": { description: "Delegation list" }
+                    }
+                }
+            },
+            "/v1/delegations/{id}": {
+                get: {
+                    summary: "Get delegation details",
+                    operationId: "getDelegation",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "Delegation details" },
+                        "404": { description: "Delegation not found or expired" }
+                    }
+                }
+            },
+            "/v1/delegations/{id}/revoke": {
+                post: {
+                    summary: "Revoke delegation",
+                    description: "Revoke a delegation and cascade to all sub-delegations.",
+                    operationId: "revokeDelegation",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } },
+                        { name: "app_id", in: "query", required: true, schema: { type: "string" } }
+                    ],
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "reason": { type: "string", description: "Revocation reason" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Delegation revoked" },
+                        "404": { description: "Delegation not found" }
+                    }
+                }
+            },
+            "/v1/verify/delegation": {
+                post: {
+                    summary: "Verify delegation chain",
+                    description: "Verify an entire delegation chain is valid (not revoked, not expired, capabilities are valid subsets).",
+                    operationId: "verifyDelegationChain",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["delegation_id"],
+                                    properties: {
+                                        "delegation_id": { type: "string", description: "The leaf delegation to verify" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Chain is valid — returns chain and effective capabilities" },
+                        "400": { description: "Chain is invalid — returns error reason" }
+                    }
+                }
+            },
+            "/v1/attestations": {
+                post: {
+                    summary: "Issue attestation",
+                    description: "Issue a capability attestation token for an agent. Grants fine-grained action:resource permissions with explicit deny.",
+                    operationId: "issueAttestation",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["agent_id", "can"],
+                                    properties: {
+                                        "agent_id": { type: "string", description: "Agent to issue attestation for" },
+                                        "can": { type: "array", items: { type: "string" }, description: "Allowed capability patterns (action:resource)" },
+                                        "cannot": { type: "array", items: { type: "string" }, description: "Denied capability patterns (overrides can)" },
+                                        "restrictions": { type: "object", description: "Optional restrictions (max_amount, rate_limit)" },
+                                        "duration_seconds": { type: "integer", description: "Attestation lifetime (default: 3600)" },
+                                        "delegation_id": { type: "string", description: "Optional link to delegation chain" },
+                                        "metadata": { type: "object", description: "Optional context metadata" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "201": { description: "Attestation issued — includes signed JWT token" },
+                        "400": { description: "Invalid request" },
+                        "403": { description: "Agent does not belong to app" },
+                        "404": { description: "Agent not found" }
+                    }
+                },
+                get: {
+                    summary: "List attestations",
+                    description: "List attestations for an agent.",
+                    operationId: "listAttestations",
+                    parameters: [
+                        { name: "app_id", in: "query", required: true, schema: { type: "string" } },
+                        { name: "agent_id", in: "query", required: true, schema: { type: "string" } }
+                    ],
+                    responses: {
+                        "200": { description: "Attestation list" }
+                    }
+                }
+            },
+            "/v1/attestations/{id}": {
+                get: {
+                    summary: "Get attestation details",
+                    operationId: "getAttestation",
+                    parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+                    responses: {
+                        "200": { description: "Attestation details" },
+                        "404": { description: "Attestation not found or expired" }
+                    }
+                }
+            },
+            "/v1/attestations/{id}/revoke": {
+                post: {
+                    summary: "Revoke attestation",
+                    description: "Revoke an attestation. Token will be rejected on future verification.",
+                    operationId: "revokeAttestation",
+                    parameters: [
+                        { name: "id", in: "path", required: true, schema: { type: "string" } },
+                        { name: "app_id", in: "query", required: true, schema: { type: "string" } }
+                    ],
+                    requestBody: {
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    properties: {
+                                        "reason": { type: "string", description: "Revocation reason" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Attestation revoked" },
+                        "404": { description: "Attestation not found" }
+                    }
+                }
+            },
+            "/v1/verify/attestation": {
+                post: {
+                    summary: "Verify attestation token",
+                    description: "Verify an attestation JWT token and optionally check a specific capability.",
+                    operationId: "verifyAttestation",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["token"],
+                                    properties: {
+                                        "token": { type: "string", description: "Attestation JWT token" },
+                                        "action": { type: "string", description: "Optional capability action to check (e.g. read)" },
+                                        "resource": { type: "string", description: "Optional capability resource to check (e.g. invoices)" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": { description: "Token valid — returns payload or capability check result" },
+                        "401": { description: "Invalid or expired token" },
+                        "403": { description: "Capability denied" }
+                    }
+                }
+            },
+            "/v1/reputation/{agent_id}": {
+                get: {
+                    summary: "Get agent reputation",
+                    description: "Get the reputation score for an agent. Returns score (0-1000), tier, event counts, and category breakdown.",
+                    operationId: "getReputation",
+                    parameters: [
+                        { name: "agent_id", in: "path", required: true, schema: { type: "string" }, description: "Agent ID" },
+                        { name: "app_id", in: "query", schema: { type: "string" }, description: "App ID for authentication" }
+                    ],
+                    responses: {
+                        "200": { description: "Reputation score with tier and category breakdown" },
+                        "404": { description: "Agent not found" }
+                    }
+                }
+            },
+            "/v1/reputation/events": {
+                post: {
+                    summary: "Record reputation event",
+                    description: "Record a behavioral event that affects an agent's reputation score. 18 action types across 6 categories.",
+                    operationId: "recordReputationEvent",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["agent_id", "category", "action"],
+                                    properties: {
+                                        "agent_id": { type: "string", description: "Agent to record event for" },
+                                        "category": { type: "string", enum: ["verification", "attestation", "delegation", "session", "violation", "endorsement"], description: "Event category" },
+                                        "action": { type: "string", description: "Event action (e.g. challenge_solved, abuse_detected)" },
+                                        "source_agent_id": { type: "string", description: "Source agent for endorsements" },
+                                        "metadata": { type: "object", additionalProperties: { type: "string" }, description: "Optional key/value metadata" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "201": { description: "Event recorded — returns event details and updated score" },
+                        "400": { description: "Invalid category/action or self-endorsement" },
+                        "404": { description: "Agent not found" }
+                    }
+                }
+            },
+            "/v1/reputation/{agent_id}/events": {
+                get: {
+                    summary: "List reputation events",
+                    description: "List reputation events for an agent with optional category filter.",
+                    operationId: "listReputationEvents",
+                    parameters: [
+                        { name: "agent_id", in: "path", required: true, schema: { type: "string" }, description: "Agent ID" },
+                        { name: "category", in: "query", schema: { type: "string" }, description: "Filter by category" },
+                        { name: "limit", in: "query", schema: { type: "integer", maximum: 100 }, description: "Max events (default: 50, max: 100)" }
+                    ],
+                    responses: {
+                        "200": { description: "List of reputation events" }
+                    }
+                }
+            },
+            "/v1/reputation/{agent_id}/reset": {
+                post: {
+                    summary: "Reset reputation",
+                    description: "Reset an agent's reputation to default (500 neutral). Admin action — clears all event history.",
+                    operationId: "resetReputation",
+                    parameters: [
+                        { name: "agent_id", in: "path", required: true, schema: { type: "string" }, description: "Agent ID" }
+                    ],
+                    responses: {
+                        "200": { description: "Reputation reset to default" },
+                        "404": { description: "Agent not found" }
+                    }
+                }
             }
         },
         components: {