@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/README.md

@@ -1,19 +1,18 @@
 # @dupecom/botcha-cloudflare
 
 > **BOTCHA** - Prove you're a bot. Humans need not apply.
-> 
-> **Cloudflare Workers Edition v0.11.0** - Identity layer for AI agents
+>
+> **Cloudflare Workers Edition v0.22.0** - Identity layer for AI agents
 
 Reverse CAPTCHA that verifies AI agents and blocks humans. Running at the edge.
 
-## What's New in v0.11.0
+## What's New in v0.22.0
 
-- **Agent Registry** - Persistent agent identities (POST /v1/agents/register)
-- **Email-tied apps** - Email verification, account recovery, secret rotation
-- **Dashboard** - Per-app metrics with agent-first auth (device code flow)
-- **JWT security** - 1-hr access tokens, refresh tokens, audience claims, IP binding, revocation
-- **Multi-tenant** - Per-app isolation, scoped tokens, rate limiting
-- **Server-side SDKs** - @dupecom/botcha-verify (TS) + botcha-verify (Python)
+- **x402 Payment Gating** — Agents pay $0.001 USDC on Base for a BOTCHA token. No puzzle. (`GET /v1/x402/challenge`)
+- **ANS Integration** — DNS-based agent identity lookup and BOTCHA-issued ownership badges. (`GET /v1/ans/resolve/:name`)
+- **DID/VC Issuer** — BOTCHA issues portable W3C Verifiable Credential JWTs. (`POST /v1/credentials/issue`)
+- **A2A Agent Card Attestation** *(coming soon, PR #26)*
+- **OIDC-A Attestation** *(coming soon, PR #28)*
 
 ## Features
 
@@ -97,10 +96,76 @@ Rate limit headers:
 | `/v1/challenges/:id/verify` | POST | Verify challenge (no JWT) |
 | `/v1/token` | GET | Get challenge for JWT flow |
 | `/v1/token/verify` | POST | Verify challenge → get JWT token |
+| `/v1/token/refresh` | POST | Refresh access token |
+| `/v1/token/revoke` | POST | Revoke token immediately |
+| `/v1/token/validate` | POST | Remote token validation (no shared secret) |
 | `/v1/challenge/stream` | GET | SSE streaming challenge (AI-native) |
 | `/v1/challenge/stream/:session` | POST | SSE action handler (go, solve) |
 | `/agent-only` | GET | Protected endpoint (requires JWT) |
 
+### Well-Known Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/.well-known/did.json` | GET | BOTCHA DID Document (`did:web:botcha.ai`) |
+| `/.well-known/jwks` | GET | JWK Set (TAP agent keys + DID signing keys) |
+| `/.well-known/jwks.json` | GET | JWK Set alias |
+| `/.well-known/ai-plugin.json` | GET | ChatGPT plugin manifest |
+
+### x402 Payment Gating
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/v1/x402/info` | GET | public | Payment config discovery |
+| `/v1/x402/challenge` | GET | public / X-Payment | Pay $0.001 USDC → BOTCHA token |
+| `/v1/x402/verify-payment` | POST | Bearer | Verify x402 payment proof |
+| `/v1/x402/webhook` | POST | — | Settlement notifications |
+| `/agent-only/x402` | GET | Bearer + x402 | Demo: requires both BOTCHA token + payment |
+
+### ANS (Agent Name Service)
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/v1/ans/botcha` | GET | public | BOTCHA's ANS identity |
+| `/v1/ans/resolve/:name` | GET | public | DNS-based ANS lookup |
+| `/v1/ans/resolve/lookup` | GET | public | ANS lookup via `?name=` query param |
+| `/v1/ans/discover` | GET | public | List BOTCHA-verified ANS agents |
+| `/v1/ans/nonce/:name` | GET | Bearer | Nonce for ownership proof |
+| `/v1/ans/verify` | POST | Bearer | Verify ANS ownership → BOTCHA badge |
+
+### DID/VC Issuer
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/v1/credentials/issue` | POST | Bearer | Issue W3C VC JWT |
+| `/v1/credentials/verify` | POST | public | Verify any BOTCHA-issued VC JWT |
+| `/v1/dids/:did/resolve` | GET | public | Resolve `did:web` DIDs |
+
+### A2A Agent Card Attestation *(coming soon — PR #26)*
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/.well-known/agent.json` | GET | public | BOTCHA's A2A Agent Card |
+| `/v1/a2a/agent-card` | GET | public | BOTCHA's A2A Agent Card (alias) |
+| `/v1/a2a/attest` | POST | Bearer | Attest an agent's A2A card |
+| `/v1/a2a/verify-card` | POST | public | Verify an attested card |
+| `/v1/a2a/verify-agent` | POST | public | Verify agent by card or `agent_url` |
+| `/v1/a2a/trust-level/:agent_url` | GET | public | Get trust level for agent URL |
+| `/v1/a2a/cards` | GET | public | Registry browse |
+| `/v1/a2a/cards/:id` | GET | public | Get specific card by ID |
+
+### OIDC-A Attestation *(coming soon — PR #28)*
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/.well-known/oauth-authorization-server` | GET | public | OAuth/OIDC-A discovery |
+| `/v1/attestation/eat` | POST | Bearer | Issue Entity Attestation Token (EAT/RFC 9711) |
+| `/v1/attestation/oidc-agent-claims` | POST | Bearer | Issue OIDC-A agent claims block |
+| `/v1/auth/agent-grant` | POST | Bearer | Agent grant flow (OAuth2-style) |
+| `/v1/auth/agent-grant/:id/status` | GET | Bearer | Grant status |
+| `/v1/auth/agent-grant/:id/resolve` | POST | Bearer | Approve/resolve grant |
+| `/v1/oidc/userinfo` | GET | Bearer | OIDC-A UserInfo |
+
 ### SSE Streaming (AI-Native)
 
 For AI agents that prefer conversational flows, BOTCHA offers Server-Sent Events streaming:

package/dist/agent-auth.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Agent Identity Authentication
+ *
+ * Allows a registered TAP agent to prove its identity by signing a nonce
+ * with its Ed25519 private key. Returns a JWT containing both app_id and
+ * agent_id — so callers know exactly which agent they're talking to.
+ *
+ * Flow:
+ *   1. POST /v1/agents/auth          { agent_id }
+ *      → { challenge_id, nonce, message, expires_in: 60 }
+ *
+ *   2. Agent signs the nonce bytes with its Ed25519 private key
+ *
+ *   3. POST /v1/agents/auth/verify   { challenge_id, agent_id, signature }
+ *      → { access_token, agent_id, app_id, expires_in: 3600 }
+ *
+ * The nonce is a random 32-byte hex string stored in KV with a 60-second TTL.
+ * The signature is base64-encoded Ed25519 signature over the raw nonce bytes.
+ *
+ * Why this matters:
+ *   A challenge-verified JWT (from /v1/token) only proves "I am an AI agent
+ *   for app X". An agent-auth JWT proves "I am specifically agent Y for app X".
+ *   The private key is the agent's persistent credential — the operator stores
+ *   it and provides it to the agent at the start of each session.
+ */
+import type { Context } from 'hono';
+type KVNamespace = {
+    get(key: string, type?: string): Promise<string | null>;
+    put(key: string, value: string, opts?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(opts?: {
+        prefix?: string;
+    }): Promise<{
+        keys: {
+            name: string;
+        }[];
+    }>;
+};
+type Bindings = {
+    AGENTS: KVNamespace;
+    CHALLENGES: KVNamespace;
+    JWT_SECRET: string;
+};
+/**
+ * POST /v1/agents/auth/provider
+ * Re-identify using the agent's provider API key (Anthropic, OpenAI, etc).
+ * The key is never stored — only its SHA-256 hash is compared.
+ *
+ * Body: { provider: 'anthropic' | 'openai' | ..., api_key: 'sk-ant-...', app_id: '...' }
+ */
+export declare function handleAgentAuthProvider(c: Context<{
+    Bindings: Bindings & {
+        APP_ID?: string;
+    };
+}>): Promise<(Response & import("hono").TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    success: true;
+    access_token: string;
+    token_type: string;
+    agent_id: string;
+    app_id: any;
+    provider: any;
+    expires_in: number;
+    message: string;
+    usage: {
+        header: string;
+    };
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export declare function handleAgentAuthChallenge(c: Context<{
+    Bindings: Bindings;
+}>): Promise<(Response & import("hono").TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    success: true;
+    challenge_id: string;
+    nonce: string;
+    agent_id: string;
+    expires_in: number;
+    message: string;
+    instructions: {
+        what_to_sign: string;
+        signature_format: string;
+        next_step: string;
+    };
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export declare function handleAgentAuthVerify(c: Context<{
+    Bindings: Bindings;
+}>): Promise<(Response & import("hono").TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 400, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 404, "json">) | (Response & import("hono").TypedResponse<{
+    success: false;
+    error: string;
+    message: string;
+}, 401, "json">) | (Response & import("hono").TypedResponse<{
+    success: true;
+    access_token: string;
+    token_type: string;
+    agent_id: any;
+    app_id: any;
+    expires_in: number;
+    message: string;
+    usage: {
+        header: string;
+        note: string;
+    };
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
+export {};
+//# sourceMappingURL=agent-auth.d.ts.map

package/dist/agent-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-auth.d.ts","sourceRoot":"","sources":["../src/agent-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAIpC,KAAK,WAAW,GAAG;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAC/Q,KAAK,QAAQ,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AA0BrF;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;;;;;;;;;;;;;;;;;;;;oEA+CrG;AAID,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;;;;;;;;;;;;;;;;;;;;oEA0ChF;AAID,wBAAsB,qBAAqB,CAAC,CAAC,EAAE,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;oEAoD7E"}

package/dist/agent-auth.js

@@ -0,0 +1,210 @@
+/**
+ * Agent Identity Authentication
+ *
+ * Allows a registered TAP agent to prove its identity by signing a nonce
+ * with its Ed25519 private key. Returns a JWT containing both app_id and
+ * agent_id — so callers know exactly which agent they're talking to.
+ *
+ * Flow:
+ *   1. POST /v1/agents/auth          { agent_id }
+ *      → { challenge_id, nonce, message, expires_in: 60 }
+ *
+ *   2. Agent signs the nonce bytes with its Ed25519 private key
+ *
+ *   3. POST /v1/agents/auth/verify   { challenge_id, agent_id, signature }
+ *      → { access_token, agent_id, app_id, expires_in: 3600 }
+ *
+ * The nonce is a random 32-byte hex string stored in KV with a 60-second TTL.
+ * The signature is base64-encoded Ed25519 signature over the raw nonce bytes.
+ *
+ * Why this matters:
+ *   A challenge-verified JWT (from /v1/token) only proves "I am an AI agent
+ *   for app X". An agent-auth JWT proves "I am specifically agent Y for app X".
+ *   The private key is the agent's persistent credential — the operator stores
+ *   it and provides it to the agent at the start of each session.
+ */
+import { SignJWT } from 'jose';
+import { getTAPAgent, listTAPAgents } from './tap-agents';
+const SUPPORTED_PROVIDERS = ['anthropic', 'openai', 'google', 'mistral', 'cohere', 'other'];
+/** SHA-256 hash of a string, returned as hex */
+async function sha256hex(input) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+    return Array.from(new Uint8Array(buf)).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+/** Issue an agent-identity JWT (shared logic) */
+async function issueAgentToken(jwtSecret, agent_id, app_id) {
+    const secret = new TextEncoder().encode(jwtSecret);
+    return new SignJWT({ type: 'botcha-agent-identity', agent_id, app_id })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setSubject(agent_id)
+        .setIssuer('botcha.ai')
+        .setIssuedAt()
+        .setExpirationTime('1h')
+        .setJti(crypto.randomUUID())
+        .sign(secret);
+}
+// ============ PROVIDER KEY AUTH ============
+/**
+ * POST /v1/agents/auth/provider
+ * Re-identify using the agent's provider API key (Anthropic, OpenAI, etc).
+ * The key is never stored — only its SHA-256 hash is compared.
+ *
+ * Body: { provider: 'anthropic' | 'openai' | ..., api_key: 'sk-ant-...', app_id: '...' }
+ */
+export async function handleAgentAuthProvider(c) {
+    const body = await c.req.json().catch(() => ({}));
+    const { provider, api_key, app_id } = body ?? {};
+    if (!provider || !api_key || !app_id) {
+        return c.json({
+            success: false,
+            error: 'MISSING_FIELDS',
+            message: 'provider, api_key, and app_id are required',
+            supported_providers: SUPPORTED_PROVIDERS,
+        }, 400);
+    }
+    if (!SUPPORTED_PROVIDERS.includes(provider)) {
+        return c.json({ success: false, error: 'UNSUPPORTED_PROVIDER', message: `Unsupported provider. Use one of: ${SUPPORTED_PROVIDERS.join(', ')}` }, 400);
+    }
+    // Hash the provided key
+    const keyHash = await sha256hex(api_key.trim());
+    // Scan agents for this app to find a matching hash
+    // Uses the app_agents index for efficiency
+    const listResult = await listTAPAgents(c.env.AGENTS, app_id);
+    const agents = listResult?.agents ?? [];
+    const match = agents.find((a) => a.provider === provider && a.provider_key_hash === keyHash);
+    if (!match) {
+        return c.json({
+            success: false,
+            error: 'AGENT_NOT_FOUND',
+            message: `No agent found for this ${provider} API key on app ${app_id}. Register first via POST /v1/agents/register/tap with provider + api_key.`,
+        }, 404);
+    }
+    const access_token = await issueAgentToken(c.env.JWT_SECRET, match.agent_id, app_id);
+    return c.json({
+        success: true,
+        access_token,
+        token_type: 'Bearer',
+        agent_id: match.agent_id,
+        app_id,
+        provider,
+        expires_in: 3600,
+        message: `Identity verified via ${provider} API key. This token proves you are agent ${match.agent_id}.`,
+        usage: { header: 'Authorization: Bearer <access_token>' },
+    });
+}
+// ============ STEP 1: Issue nonce challenge ============
+export async function handleAgentAuthChallenge(c) {
+    const body = await c.req.json().catch(() => ({}));
+    const agent_id = body?.agent_id;
+    if (!agent_id || typeof agent_id !== 'string') {
+        return c.json({ success: false, error: 'MISSING_AGENT_ID', message: 'agent_id is required' }, 400);
+    }
+    // Look up TAP agent — must have a registered public key
+    const result = await getTAPAgent(c.env.AGENTS, agent_id);
+    if (!result.success || !result.agent) {
+        return c.json({ success: false, error: 'AGENT_NOT_FOUND', message: 'No TAP agent found with that agent_id. Register a keypair first via POST /v1/agents/register/tap' }, 404);
+    }
+    if (!result.agent.public_key) {
+        return c.json({ success: false, error: 'NO_PUBLIC_KEY', message: 'This agent has no registered public key. Re-register via POST /v1/agents/register/tap with a public_key' }, 400);
+    }
+    // Generate a random nonce
+    const nonceBytes = crypto.getRandomValues(new Uint8Array(32));
+    const nonce = Array.from(nonceBytes).map(b => b.toString(16).padStart(2, '0')).join('');
+    const challenge_id = `agentauth_${crypto.randomUUID()}`;
+    // Store: challenge_id → { nonce, agent_id } with 60s TTL
+    await c.env.CHALLENGES.put(`agentauth:${challenge_id}`, JSON.stringify({ nonce, agent_id, created_at: Date.now() }), { expirationTtl: 60 });
+    return c.json({
+        success: true,
+        challenge_id,
+        nonce,
+        agent_id,
+        expires_in: 60,
+        message: 'Sign the nonce bytes with your Ed25519 private key. Submit base64-encoded signature to POST /v1/agents/auth/verify',
+        instructions: {
+            what_to_sign: 'The raw nonce string encoded as UTF-8 bytes',
+            signature_format: 'base64-encoded Ed25519 signature',
+            next_step: 'POST /v1/agents/auth/verify with { challenge_id, agent_id, signature }',
+        },
+    });
+}
+// ============ STEP 2: Verify signature, issue agent JWT ============
+export async function handleAgentAuthVerify(c) {
+    const body = await c.req.json().catch(() => ({}));
+    const { challenge_id, agent_id, signature } = body ?? {};
+    if (!challenge_id || !agent_id || !signature) {
+        return c.json({ success: false, error: 'MISSING_FIELDS', message: 'challenge_id, agent_id, and signature are required' }, 400);
+    }
+    // Retrieve and immediately delete the challenge (one-shot)
+    const raw = await c.env.CHALLENGES.get(`agentauth:${challenge_id}`, 'text');
+    if (!raw) {
+        return c.json({ success: false, error: 'CHALLENGE_NOT_FOUND', message: 'Challenge not found or expired (60s TTL)' }, 404);
+    }
+    await c.env.CHALLENGES.delete(`agentauth:${challenge_id}`);
+    const stored = JSON.parse(raw);
+    // Verify agent_id matches what was challenged
+    if (stored.agent_id !== agent_id) {
+        return c.json({ success: false, error: 'AGENT_MISMATCH', message: 'agent_id does not match the challenged agent' }, 400);
+    }
+    // Look up TAP agent and public key
+    const result = await getTAPAgent(c.env.AGENTS, agent_id);
+    if (!result.success || !result.agent?.public_key) {
+        return c.json({ success: false, error: 'AGENT_NOT_FOUND', message: 'Agent not found' }, 404);
+    }
+    const { public_key, signature_algorithm, app_id } = result.agent;
+    // Verify the signature
+    const valid = await verifyNonceSignature(stored.nonce, signature, public_key, signature_algorithm ?? 'ed25519');
+    if (!valid) {
+        return c.json({ success: false, error: 'INVALID_SIGNATURE', message: 'Signature verification failed. Ensure you signed the raw nonce string with your registered private key.' }, 401);
+    }
+    // Issue agent-identity JWT (1 hour)
+    const access_token = await issueAgentToken(c.env.JWT_SECRET, agent_id, app_id);
+    return c.json({
+        success: true,
+        access_token,
+        token_type: 'Bearer',
+        agent_id,
+        app_id,
+        expires_in: 3600,
+        message: 'Identity verified. This token proves you are specifically this agent.',
+        usage: {
+            header: 'Authorization: Bearer <access_token>',
+            note: 'This token contains your agent_id claim. Services can verify your specific identity without you solving a fresh challenge.',
+        },
+    });
+}
+// ============ Signature verification ============
+async function verifyNonceSignature(nonce, signatureB64, publicKey, algorithm) {
+    try {
+        const sigBytes = Uint8Array.from(atob(signatureB64), c => c.charCodeAt(0));
+        const nonceBytes = new TextEncoder().encode(nonce);
+        let keyData;
+        if (algorithm === 'ed25519') {
+            // Accept raw 32-byte base64 key or SPKI DER base64
+            const raw = Uint8Array.from(atob(publicKey), c => c.charCodeAt(0));
+            if (raw.length === 32) {
+                // Raw key — wrap in SPKI
+                const spki = new Uint8Array(44);
+                // Ed25519 SPKI header (12 bytes)
+                spki.set([0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00]);
+                spki.set(raw, 12);
+                keyData = spki.buffer;
+            }
+            else {
+                keyData = raw.buffer;
+            }
+            const cryptoKey = await crypto.subtle.importKey('spki', keyData, { name: 'Ed25519' }, false, ['verify']);
+            return await crypto.subtle.verify({ name: 'Ed25519' }, cryptoKey, sigBytes, nonceBytes);
+        }
+        // ECDSA P-256
+        if (algorithm === 'ecdsa-p256-sha256') {
+            const raw = Uint8Array.from(atob(publicKey), c => c.charCodeAt(0));
+            const cryptoKey = await crypto.subtle.importKey('spki', raw.buffer, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+            return await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, cryptoKey, sigBytes, nonceBytes);
+        }
+        return false;
+    }
+    catch (e) {
+        console.error('Agent auth signature verification error:', e);
+        return false;
+    }
+}

package/dist/agents.d.ts

@@ -57,6 +57,16 @@ export declare function createAgent(kv: KVNamespace, app_id: string, data: {
  * @returns Agent record or null if not found
  */
 export declare function getAgent(kv: KVNamespace, agent_id: string): Promise<Agent | null>;
+/**
+ * Delete an agent and remove it from the app's agent index.
+ * Also removes from the tap-agents app_agents:{appId} index if present.
+ *
+ * @returns true if deleted, false if not found, null on error
+ */
+export declare function deleteAgent(kv: KVNamespace, agent_id: string, app_id: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
 /**
  * List all agents for an app
  *

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACtF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAIF;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAOxC;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAwCvB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAcvB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,EAAE,CAAC,CAsBlB"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,QAAQ,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACtF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAIF;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAOxC;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAiDvB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAcvB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAmC/C;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,EAAE,CAAC,CAsBlB"}

package/dist/agents.js

@@ -60,10 +60,21 @@ export async function createAgent(kv, app_id, data) {
         }
         // Add new agent_id to the list
         agentIds.push(agent_id);
-        // Store agent record and updated list in parallel
+        // Read tap-agents index too, keep both in sync
+        let tapAgentIds = [];
+        try {
+            const tapList = await kv.get(`app_agents:${app_id}`, 'text');
+            if (tapList)
+                tapAgentIds = JSON.parse(tapList);
+        }
+        catch { }
+        if (!tapAgentIds.includes(agent_id))
+            tapAgentIds.push(agent_id);
+        // Store agent record and update both index keys
         await Promise.all([
             kv.put(`agent:${agent_id}`, JSON.stringify(agent)),
             kv.put(`agents:${app_id}`, JSON.stringify(agentIds)),
+            kv.put(`app_agents:${app_id}`, JSON.stringify(tapAgentIds)),
         ]);
         return agent;
     }
@@ -94,6 +105,45 @@ export async function getAgent(kv, agent_id) {
         return null;
     }
 }
+/**
+ * Delete an agent and remove it from the app's agent index.
+ * Also removes from the tap-agents app_agents:{appId} index if present.
+ *
+ * @returns true if deleted, false if not found, null on error
+ */
+export async function deleteAgent(kv, agent_id, app_id) {
+    try {
+        // Verify agent exists and belongs to the app
+        const existing = await kv.get(`agent:${agent_id}`, 'text');
+        if (!existing) {
+            return { success: false, error: 'Agent not found' };
+        }
+        const agent = JSON.parse(existing);
+        if (agent.app_id !== app_id) {
+            return { success: false, error: 'Agent does not belong to this app' };
+        }
+        // Remove agent record and update both index keys in parallel
+        const [agentsRaw, appAgentsRaw] = await Promise.all([
+            kv.get(`agents:${app_id}`, 'text'),
+            kv.get(`app_agents:${app_id}`, 'text'),
+        ]);
+        const ops = [kv.delete(`agent:${agent_id}`)];
+        if (agentsRaw) {
+            const ids = JSON.parse(agentsRaw).filter((id) => id !== agent_id);
+            ops.push(kv.put(`agents:${app_id}`, JSON.stringify(ids)));
+        }
+        if (appAgentsRaw) {
+            const ids = JSON.parse(appAgentsRaw).filter((id) => id !== agent_id);
+            ops.push(kv.put(`app_agents:${app_id}`, JSON.stringify(ids)));
+        }
+        await Promise.all(ops);
+        return { success: true };
+    }
+    catch (error) {
+        console.error(`Failed to delete agent ${agent_id}:`, error);
+        return { success: false, error: 'Internal server error' };
+    }
+}
 /**
  * List all agents for an app
  *

package/dist/app-gate.d.ts

@@ -0,0 +1,6 @@
+export declare const APP_GATE_OPEN_PATHS: string[];
+export declare function isAppManagementPath(path: string): boolean;
+export declare function isDashboardAuthedPath(path: string, method: string): boolean;
+export declare function isPublicV1Path(path: string): boolean;
+export declare function shouldBypassAppGate(path: string, method?: string): boolean;
+//# sourceMappingURL=app-gate.d.ts.map

package/dist/app-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-gate.d.ts","sourceRoot":"","sources":["../src/app-gate.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,mBAAmB,UAmC/B,CAAC;AAGF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAGD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAM3E;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYpD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAc,GAAG,OAAO,CAEjF"}

package/dist/app-gate.js

@@ -0,0 +1,69 @@
+// Shared app-gate path rules for /v1/* middleware.
+// App gate open paths that do not require app_id.
+export const APP_GATE_OPEN_PATHS = [
+    '/v1/apps', // POST: create app (registration)
+    '/v1/auth/recover', // POST: account recovery
+    '/v1/token/validate', // POST: public token validation — token is credential
+    // x402 endpoints: payment is the credential
+    '/v1/x402/challenge',
+    '/v1/x402/verify-payment',
+    '/v1/x402/webhook',
+    '/v1/x402/info',
+    // Public ANS + DID/VC endpoints under /v1/*
+    '/v1/ans/discover',
+    '/v1/ans/botcha',
+    '/v1/ans/resolve/lookup',
+    '/v1/credentials/verify',
+    // OIDC-A UserInfo accepts BOTCHA access tokens OR EAT bearer tokens.
+    // EAT tokens are not app-gate tokens, so this route must bypass app-gate
+    // and perform its own auth checks in the route handler.
+    '/v1/oidc/userinfo',
+    // Public A2A verification and discovery endpoints
+    '/v1/a2a/agent-card',
+    '/v1/a2a/verify-card',
+    '/v1/a2a/verify-agent',
+    '/v1/a2a/cards',
+    // Agent identity auth — keypair, provider key, or OAuth refresh
+    '/v1/agents/auth',
+    '/v1/agents/auth/verify',
+    '/v1/agents/auth/provider',
+    '/v1/agents/auth/refresh',
+    // OAuth device authorization grant (RFC 8628)
+    '/v1/oauth/device',
+    '/v1/oauth/token',
+    '/v1/oauth/approve',
+    '/v1/oauth/revoke',
+    '/v1/oauth/lookup',
+    '/v1/oauth/status',
+];
+// Pattern-match paths that start with /v1/apps/:id/ (verify-email, resend-verification, etc.)
+export function isAppManagementPath(path) {
+    return /^\/v1\/apps\/[^/]+\/(verify-email|resend-verification)$/.test(path);
+}
+// Dashboard-authed paths — use session cookie, not app_id bearer token
+export function isDashboardAuthedPath(path, method) {
+    // DELETE /v1/agents/:id — session cookie auth via requireDashboardAuth
+    if (method === 'DELETE' && /^\/v1\/agents\/[^/]+$/.test(path))
+        return true;
+    // /device — OAuth agent approval page
+    if (path === '/device')
+        return true;
+    return false;
+}
+export function isPublicV1Path(path) {
+    // Public ANS resolution paths: /v1/ans/resolve/:name
+    if (path.startsWith('/v1/ans/resolve/'))
+        return true;
+    // Public DID resolution path: /v1/dids/:did/resolve
+    if (/^\/v1\/dids\/[^/]+\/resolve$/.test(path))
+        return true;
+    // Public A2A routes with dynamic path params
+    if (path.startsWith('/v1/a2a/cards/'))
+        return true;
+    if (path.startsWith('/v1/a2a/trust-level/'))
+        return true;
+    return false;
+}
+export function shouldBypassAppGate(path, method = 'GET') {
+    return APP_GATE_OPEN_PATHS.includes(path) || isAppManagementPath(path) || isPublicV1Path(path) || isDashboardAuthedPath(path, method);
+}

package/dist/apps.d.ts

@@ -41,6 +41,7 @@ export interface CreateAppResult {
     email: string;
     email_verified: boolean;
     verification_required: boolean;
+    verification_code: string;
 }
 /**
  * Public app info returned by getApp (excludes secrets and internal fields)
@@ -53,6 +54,15 @@ export type PublicAppConfig = {
     email: string;
     email_verified: boolean;
 };
+/**
+ * Thrown when attempting to register an app with an email that's already in use.
+ * Callers should return a 409 Conflict with recovery instructions.
+ */
+export declare class EmailAlreadyRegisteredError extends Error {
+    readonly email: string;
+    readonly existing_app_id: string;
+    constructor(email: string, existing_app_id: string);
+}
 /**
  * Generate a crypto-random app ID
  * Format: 'app_' + 16 hex chars
@@ -98,11 +108,10 @@ export declare function generateVerificationCode(): string;
  */
 export declare function createApp(kv: KVNamespace, email: string, name?: string): Promise<CreateAppResult>;
 /**
- * Get the plaintext verification code for an app (internal use only — for sending via email).
+ * Regenerate a new verification code for an app.
  *
- * This is a separate step because createApp returns the code hash, not the plaintext.
- * Instead, we generate and return code in createApp flow; this function regenerates
- * a new code for resend scenarios.
+ * Used for resend scenarios when the user needs a fresh code.
+ * Returns null if the app doesn't exist or email is already verified.
  */
 export declare function regenerateVerificationCode(kv: KVNamespace, app_id: string): Promise<{
     code: string;