@dupecom/botcha-cloudflare 0.16.0 → 0.19.0

package/dist/static.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../src/static.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAkMzD;AAED,eAAO,MAAM,UAAU,85CAuDtB,CAAC;AAEF,eAAO,MAAM,MAAM,ssdAyOlB,CAAC;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;CAsB1B,CAAC;AAEF,eAAO,MAAM,WAAW,kwBA4BvB,CAAC;AAGF,wBAAgB,qBAAqB,IAAI,MAAM,CAiJ9C;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAokC7C"}
+{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../src/static.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA0OzD;AAED,eAAO,MAAM,UAAU,85CAuDtB,CAAC;AAEF,eAAO,MAAM,MAAM,gylBA0QlB,CAAC;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;CAsB1B,CAAC;AAEF,eAAO,MAAM,WAAW,+3BAiCvB,CAAC;AAGF,wBAAgB,qBAAqB,IAAI,MAAM,CAiJ9C;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAm5C7C"}

package/dist/static.js

@@ -110,6 +110,35 @@ curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 |--------|------|-------------|
 | \`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
 
@@ -128,6 +157,7 @@ curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 | \`POST\` | \`/v1/token/verify\` | Submit solution → access_token (5min) + refresh_token (1hr) |
 | \`POST\` | \`/v1/token/refresh\` | Refresh access token |
 | \`POST\` | \`/v1/token/revoke\` | Revoke a token |
+| \`POST\` | \`/v1/token/validate\` | Validate a token remotely (no shared secret needed) |
 
 ### Dashboard & Auth
 
@@ -153,7 +183,17 @@ curl https://botcha.ai/agent-only -H "Authorization: Bearer <token>"
 
 **Token lifetimes:** access_token = 5 minutes, refresh_token = 1 hour
 
-**Features:** audience claims, client IP binding, token revocation, refresh tokens
+**Token signing:** ES256 (ECDSA P-256) asymmetric signing. HS256 supported for backward compatibility.
+
+**Features:** audience claims, client IP binding, token revocation, refresh tokens, JWKS public key discovery
+
+## Token Verification (for API providers)
+
+Three ways to verify incoming BOTCHA tokens:
+
+1. **JWKS (Recommended)** — Fetch public keys from \`GET /.well-known/jwks\` and verify ES256 signatures locally. No shared secret needed.
+2. **Remote Validation** — \`POST /v1/token/validate\` with \`{"token": "..."}\`. Simplest approach, no SDK needed.
+3. **Shared Secret (Legacy)** — Verify HS256 tokens with \`BOTCHA_SECRET\`. Requires secret sharing.
 
 ## RTT-Aware Challenges
 
@@ -171,7 +211,7 @@ Formula: \`timeout = 500ms + (2 × RTT) + 100ms buffer\`
 |----------|---------|---------|
 | npm | \`@dupecom/botcha\` | \`npm install @dupecom/botcha\` |
 | PyPI | \`botcha\` | \`pip install botcha\` |
-| Verify (TS) | \`@botcha/verify\` | \`npm install @botcha/verify\` |
+| Verify (TS) | \`@dupecom/botcha-verify\` | \`npm install @dupecom/botcha-verify\` |
 | Verify (Python) | \`botcha-verify\` | \`pip install botcha-verify\` |
 | TAP middleware | \`@dupecom/botcha/middleware\` | \`import { createTAPVerifyMiddleware } from '@dupecom/botcha/middleware'\` |
 
@@ -286,6 +326,7 @@ API-Format: OpenAPI 3.1.0
 
 # Documentation
 Docs: https://botcha.ai
+Docs: https://botcha.ai/docs
 Docs: https://botcha.ai/whitepaper
 Docs: https://github.com/dupe-com/botcha#readme
 Docs: https://www.npmjs.com/package/@dupecom/botcha
@@ -302,7 +343,7 @@ Feature: Token Rotation (5-minute access tokens + 1-hour refresh tokens)
 Feature: Audience Claims (tokens scoped to specific services)
 Feature: Client IP Binding (optional token-to-IP binding)
 Feature: Token Revocation (invalidate tokens before expiry)
-Feature: Server-Side Verification SDK (@botcha/verify for TS, botcha-verify for Python)
+Feature: Server-Side Verification SDK (@dupecom/botcha-verify for TS, botcha-verify for Python)
 Feature: Multi-Tenant API Keys (per-app isolation, rate limiting, and token scoping)
 Feature: Per-App Metrics Dashboard (server-rendered at /dashboard, htmx-powered)
 Feature: Email-Tied App Creation (email required, 6-digit verification, account recovery)
@@ -314,6 +355,9 @@ 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
+Feature: ES256 Asymmetric JWT Signing v0.19.0 — tokens signed with ES256 (ECDSA P-256), public key discovery via JWKS, HS256 still supported for backward compatibility
+Feature: Remote Token Validation v0.19.0 — POST /v1/token/validate for third-party token verification without shared secrets
+Feature: JWKS Public Key Discovery v0.19.0 — GET /.well-known/jwks exposes BOTCHA signing public keys for offline token verification
 
 # Endpoints
 # Challenge Endpoints
@@ -329,6 +373,7 @@ Endpoint: GET https://botcha.ai/v1/token - Get challenge for JWT token flow
 Endpoint: POST https://botcha.ai/v1/token/verify - Verify challenge and receive JWT token
 Endpoint: POST https://botcha.ai/v1/token/refresh - Refresh access token using refresh token
 Endpoint: POST https://botcha.ai/v1/token/revoke - Revoke a token (access or refresh)
+Endpoint: POST https://botcha.ai/v1/token/validate - Validate a BOTCHA token remotely (no shared secret needed)
 
 # Multi-Tenant Endpoints
 Endpoint: POST https://botcha.ai/v1/apps - Create new app (email required, returns app_id + app_secret)
@@ -383,6 +428,26 @@ Endpoint: POST https://botcha.ai/v1/invoices/:id/verify-iou - Verify Browsing IO
 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
@@ -395,7 +460,7 @@ Endpoint: GET https://botcha.ai/agent-only - Protected AI-only resource
 # Usage
 Install-NPM: npm install @dupecom/botcha
 Install-Python: pip install botcha
-Verify-NPM: npm install @botcha/verify
+Verify-NPM: npm install @dupecom/botcha-verify
 Verify-Python: pip install botcha-verify
 License: MIT
 
@@ -418,6 +483,10 @@ Content-Negotiation-Example: curl https://botcha.ai -H "Accept: text/markdown"
 Content-Negotiation-Benefit: 80% fewer tokens vs HTML — ideal for LLM context windows
 
 # JWT TOKEN SECURITY
+Token-Signing: ES256 (ECDSA P-256) asymmetric signing by default. HS256 still supported for backward compatibility.
+Token-JWKS: GET /.well-known/jwks — public keys for offline token verification (no shared secret needed)
+Token-Validate: POST /v1/token/validate with {"token": "<token>"} — remote validation without shared secret
+Token-Verify-Modes: 1. JWKS (recommended, offline) 2. Remote validation (/v1/token/validate) 3. Shared secret (legacy HS256)
 Token-Flow: 1. GET /v1/token (get challenge) → 2. Solve → 3. POST /v1/token/verify (get tokens + human_link)
 Token-Human-Link: /v1/token/verify response includes human_link — give this URL to your human for one-click browser access
 Token-Access-Expiry: 5 minutes (short-lived for security)
@@ -461,8 +530,8 @@ 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), getJWKS(), getKeyById(keyId), rotateAgentKey(agentId), createInvoice(data), getInvoice(id), verifyBrowsingIOU(invoiceId, token)
-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)
+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
@@ -476,6 +545,10 @@ TAP-Key-Rotation: POST /v1/agents/:id/tap/rotate-key — rotate keys, invalidate
 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">
@@ -540,6 +613,11 @@ export const SITEMAP_XML = `<?xml version="1.0" encoding="UTF-8"?>
     <changefreq>monthly</changefreq>
     <priority>0.9</priority>
   </url>
+  <url>
+    <loc>https://botcha.ai/docs</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.9</priority>
+  </url>
 </urlset>
 `;
 // Whitepaper markdown — served at /whitepaper with Accept: text/markdown
@@ -650,7 +728,7 @@ async with BotchaClient() as client:
 
 ### Server-side Verification
 
-Express: \`@botcha/verify\` · FastAPI/Django: \`botcha-verify\` · Hono middleware included.
+Express: \`@dupecom/botcha-verify\` · FastAPI/Django: \`botcha-verify\` · Hono middleware included.
 
 ### CLI
 
@@ -682,7 +760,7 @@ MCP gives agents tools. A2A lets agents communicate. TAP proves identity and sco
 
 **Shipped:** Challenge types, JWT tokens, multi-tenant apps, agent registry, TAP, dashboard, SDKs (TS/Python), CLI, LangChain, discovery standards.
 
-**Planned:** Delegation chains, capability attestation, agent reputation scoring, Agent SSO (cross-service verification), IETF RFC contribution.
+**Planned:** Agent SSO (cross-service verification), IETF RFC contribution.
 
 ---
 
@@ -708,7 +786,7 @@ export function getOpenApiSpec(version) {
             "x-sdk": {
                 npm: "@dupecom/botcha",
                 python: "botcha (pip install botcha)",
-                verify_npm: "@botcha/verify (server-side verification)",
+                verify_npm: "@dupecom/botcha-verify (server-side verification)",
                 verify_python: "botcha-verify (pip install botcha-verify)"
             }
         },
@@ -944,6 +1022,44 @@ export function getOpenApiSpec(version) {
                     }
                 }
             },
+            "/v1/token/validate": {
+                post: {
+                    summary: "Validate a BOTCHA token remotely",
+                    description: "Validate a BOTCHA token without needing the signing secret. Returns the token validity and decoded payload. Supports both ES256 and HS256 tokens.",
+                    operationId: "validateToken",
+                    requestBody: {
+                        required: true,
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["token"],
+                                    properties: {
+                                        "token": { type: "string", description: "The JWT token to validate" }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    responses: {
+                        "200": {
+                            description: "Token validation result",
+                            content: {
+                                "application/json": {
+                                    schema: {
+                                        type: "object",
+                                        properties: {
+                                            "valid": { type: "boolean", description: "Whether the token is valid" },
+                                            "payload": { type: "object", description: "Decoded token payload (if valid)" },
+                                            "error": { type: "string", description: "Error message (if invalid)" }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            },
             "/v1/hybrid": {
                 get: {
                     summary: "Get hybrid challenge",
@@ -1752,6 +1868,303 @@ export function getOpenApiSpec(version) {
                         "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: {