@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/tap-vc.js

@@ -0,0 +1,245 @@
+/**
+ * BOTCHA Verifiable Credentials — W3C VC Data Model 2.0
+ *
+ * Implements:
+ *   - VC issuance: sign a BotchaVerification credential as a JWT
+ *   - VC verification: validate signature, expiry, and issuer
+ *   - Credential schema aligned with the VC Data Model 2.0 spec
+ *
+ * Encoding:
+ *   VCs are encoded as JWT-VCs per the VC Data Model 2.0 spec.
+ *   The JWT payload contains a "vc" claim with the JSON-LD credential,
+ *   plus standard JWT claims (iss, sub, jti, iat, nbf, exp).
+ *
+ * Signing:
+ *   - Preferred: ES256 with the BOTCHA JWT_SIGNING_KEY (verifiable offline)
+ *   - Fallback:  HS256 with JWT_SECRET (verifiable only by botcha.ai)
+ *
+ * Standards:
+ *   - W3C VC Data Model 2.0: https://www.w3.org/TR/vc-data-model-2.0/
+ *   - VC-JWT: https://www.w3.org/TR/vc-data-model-2.0/#json-web-token
+ *   - DID Core 1.0: https://www.w3.org/TR/did-core/
+ */
+import { SignJWT, jwtVerify, importJWK, decodeProtectedHeader } from 'jose';
+import { getSigningPublicKeyJWK } from './auth.js';
+// ============ CONSTANTS ============
+const VC_ISSUER_DID = 'did:web:botcha.ai';
+const VC_CONTEXT_V2 = 'https://www.w3.org/ns/credentials/v2';
+const DEFAULT_VC_DURATION = 86_400; // 24 hours (seconds)
+const MAX_VC_DURATION = 86_400 * 30; // 30 days (seconds)
+// ============ ISSUANCE ============
+/**
+ * Issue a W3C Verifiable Credential for a successful BOTCHA verification.
+ *
+ * The VC is encoded as a JWT-VC signed with BOTCHA's ES256 key.
+ * If no ES256 key is available, falls back to HS256.
+ *
+ * The JWT payload includes:
+ *   iss = did:web:botcha.ai
+ *   sub = agent DID or agent_id
+ *   jti = credential ID (urn:botcha:vc:<uuid>)
+ *   vc  = the full JSON-LD credential object
+ *   type = "botcha-vc" (BOTCHA-specific claim for quick type-checking)
+ */
+export async function issueVC(options, signingKey, secret) {
+    try {
+        if (!signingKey && !secret) {
+            return { success: false, error: 'No signing key or secret provided' };
+        }
+        const durationSeconds = Math.min(options.duration_seconds ?? DEFAULT_VC_DURATION, MAX_VC_DURATION);
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + durationSeconds * 1_000);
+        const credentialId = `urn:botcha:vc:${crypto.randomUUID()}`;
+        // Build credentialSubject
+        const credentialSubject = {
+            agent_id: options.agent_id || 'anonymous',
+            app_id: options.app_id,
+            challenge_type: options.challenge_type || 'speed',
+            solve_time_ms: options.solve_time_ms,
+            trust_level: options.trust_level || 'basic',
+        };
+        if (options.capabilities && options.capabilities.length > 0) {
+            credentialSubject.capabilities = options.capabilities;
+        }
+        // Set subject DID if agent has one
+        if (options.agent_did) {
+            credentialSubject.id = options.agent_did;
+        }
+        // Build the JSON-LD VC object
+        const vc = {
+            '@context': [VC_CONTEXT_V2],
+            type: ['VerifiableCredential', 'BotchaVerification'],
+            id: credentialId,
+            issuer: VC_ISSUER_DID,
+            validFrom: now.toISOString(),
+            validUntil: expiresAt.toISOString(),
+            credentialSubject,
+        };
+        // Determine signing key + algorithm
+        let signKey;
+        let protectedHeader;
+        if (signingKey) {
+            signKey = (await importJWK(signingKey, 'ES256'));
+            protectedHeader = {
+                alg: 'ES256',
+                kid: signingKey.kid || 'botcha-signing-1',
+                typ: 'JWT',
+            };
+        }
+        else {
+            // HS256 fallback — valid JWT but not verifiable offline
+            signKey = new TextEncoder().encode(secret);
+            protectedHeader = { alg: 'HS256', typ: 'JWT' };
+        }
+        // JWT-VC claim mapping (VC Data Model 2.0 §6.3.1):
+        //   iss  → issuer
+        //   sub  → credentialSubject.id (or agent_id)
+        //   jti  → id (credential identifier)
+        //   nbf  → validFrom
+        //   exp  → validUntil
+        //   vc   → the JSON-LD credential object
+        const jwtPayload = {
+            vc,
+            type: 'botcha-vc', // BOTCHA-specific type claim for fast filtering
+        };
+        const subjectId = credentialSubject.id || options.agent_id || 'anonymous';
+        const vcJwt = await new SignJWT(jwtPayload)
+            .setProtectedHeader(protectedHeader)
+            .setIssuer(VC_ISSUER_DID)
+            .setSubject(subjectId)
+            .setJti(credentialId)
+            .setIssuedAt()
+            .setNotBefore(Math.floor(now.getTime() / 1_000))
+            .setExpirationTime(Math.floor(expiresAt.getTime() / 1_000))
+            .sign(signKey);
+        return {
+            success: true,
+            vc,
+            vc_jwt: vcJwt,
+            credential_id: credentialId,
+            issued_at: now.toISOString(),
+            expires_at: expiresAt.toISOString(),
+        };
+    }
+    catch (error) {
+        console.error('VC issuance failed:', error);
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'VC issuance failed',
+        };
+    }
+}
+// ============ VERIFICATION ============
+/**
+ * Verify a BOTCHA VC JWT.
+ *
+ * Checks (in order):
+ *   1. JWT signature (ES256 or HS256)
+ *   2. JWT expiration (exp claim)
+ *   3. Token type claim = "botcha-vc"
+ *   4. Issuer claim = "did:web:botcha.ai"
+ *   5. Presence of `vc` claim with credentialSubject
+ *
+ * Returns the decoded VC and credential subject if valid.
+ */
+export async function verifyVC(vcJwt, signingKey, secret) {
+    try {
+        if (!signingKey && !secret) {
+            return { valid: false, error: 'No verification key or secret provided' };
+        }
+        // Detect algorithm from token header
+        const header = decodeProtectedHeader(vcJwt);
+        let verifyKey;
+        let algorithms;
+        if (header.alg === 'ES256' && signingKey) {
+            const publicKeyJwk = getSigningPublicKeyJWK(signingKey);
+            verifyKey = (await importJWK(publicKeyJwk, 'ES256'));
+            algorithms = ['ES256'];
+        }
+        else if (secret) {
+            verifyKey = new TextEncoder().encode(secret);
+            algorithms = ['HS256'];
+        }
+        else {
+            return {
+                valid: false,
+                error: `Token signed with ${header.alg} but no compatible key provided`,
+            };
+        }
+        const { payload } = await jwtVerify(vcJwt, verifyKey, { algorithms });
+        // Check BOTCHA-specific type claim
+        if (payload.type !== 'botcha-vc') {
+            return {
+                valid: false,
+                error: `Invalid token type "${payload.type}". Expected "botcha-vc".`,
+            };
+        }
+        // Check issuer
+        if (payload.iss !== VC_ISSUER_DID) {
+            return {
+                valid: false,
+                error: `Invalid issuer "${payload.iss}". Expected "${VC_ISSUER_DID}".`,
+            };
+        }
+        // Extract VC object
+        const vc = payload.vc;
+        if (!vc || !vc.credentialSubject) {
+            return {
+                valid: false,
+                error: 'VC payload is missing or malformed (no credentialSubject)',
+            };
+        }
+        return {
+            valid: true,
+            vc,
+            credential_subject: vc.credentialSubject,
+            issuer: payload.iss,
+            credential_id: payload.jti,
+            issued_at: payload.iat
+                ? new Date(payload.iat * 1_000).toISOString()
+                : undefined,
+            expires_at: payload.exp
+                ? new Date(payload.exp * 1_000).toISOString()
+                : undefined,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : 'VC verification failed',
+        };
+    }
+}
+// ============ UTILITIES ============
+/**
+ * Extract the BOTCHA access_token payload from the Authorization header.
+ * Returns null if the token is missing or cannot be decoded (does NOT verify).
+ */
+export function extractVCPayloadClaims(vcJwt) {
+    try {
+        const parts = vcJwt.split('.');
+        if (parts.length !== 3)
+            return null;
+        const padded = parts[1] + '='.repeat((4 - (parts[1].length % 4)) % 4);
+        const decoded = JSON.parse(atob(padded.replace(/-/g, '+').replace(/_/g, '/')));
+        const vc = decoded?.vc;
+        if (!vc?.credentialSubject)
+            return null;
+        const cs = vc.credentialSubject;
+        return {
+            agent_id: cs.agent_id,
+            app_id: cs.app_id,
+            solve_time_ms: cs.solve_time_ms,
+            challenge_type: cs.challenge_type,
+            trust_level: cs.trust_level,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export default {
+    issueVC,
+    verifyVC,
+    extractVCPayloadClaims,
+};

package/dist/tap-x402-routes.d.ts

@@ -0,0 +1,89 @@
+/**
+ * x402 Payment Gating — Route Handlers
+ *
+ * Exposes BOTCHA's x402-compliant API endpoints:
+ *
+ *   POST /v1/x402/verify-payment   — Facilitator: verify a payment proof
+ *   GET  /v1/x402/challenge        — Pay-for-verification (402 → X-Payment → token)
+ *   GET  /agent-only/x402          — Demo: requires BOTCHA token + x402 payment
+ *   POST /v1/x402/webhook          — Settlement notifications from facilitators
+ *
+ * All endpoints are built for Cloudflare Workers (Hono framework, no Node APIs).
+ */
+import type { Context } from 'hono';
+/**
+ * POST /v1/x402/verify-payment
+ *
+ * Acts as a lightweight x402-compatible facilitator.
+ * Accepts a payment proof (base64-encoded X-Payment payload) and
+ * verifies: structure, recipient, amount, deadline, nonce, signature.
+ *
+ * Request body:
+ *   { payment: "<base64-encoded X402PaymentProof>" }
+ *   OR submit the raw X-Payment header value directly in the body field.
+ *
+ * Response:
+ *   200 { verified: true, txHash, payer, amount, network }
+ *   400 { verified: false, error, errorCode }
+ */
+export declare function verifyPaymentRoute(c: Context): Promise<Response>;
+/**
+ * GET /v1/x402/challenge
+ *
+ * The flagship pay-for-verification endpoint.
+ *
+ * Without X-Payment header → 402 Payment Required
+ * With valid X-Payment header → 200 with BOTCHA access_token
+ *
+ * This allows agents to get a BOTCHA verification token by paying
+ * $0.001 USDC instead of solving a challenge.
+ *
+ * x402 standard flow:
+ *   1. Agent: GET /v1/x402/challenge
+ *   2. Server: 402 + X-Payment-Required: { amount, payTo, asset, ... }
+ *   3. Agent: signs ERC-3009 transferWithAuthorization
+ *   4. Agent: GET /v1/x402/challenge + X-Payment: <base64-proof>
+ *   5. Server: 200 + { access_token, ... } + X-Payment-Response: { success, txHash }
+ */
+export declare function x402ChallengeRoute(c: Context): Promise<Response>;
+/**
+ * GET /agent-only/x402
+ *
+ * Demo endpoint: requires BOTH BOTCHA Bearer token + x402 micropayment.
+ * Reference implementation for "verified + paid" double-gated resources.
+ *
+ * Without token → 401 (get BOTCHA verified first)
+ * Without payment → 402 (pay $0.001 USDC)
+ * With both → 200 (access granted)
+ */
+export declare function agentOnlyX402Route(c: Context): Promise<Response>;
+/**
+ * POST /v1/x402/webhook
+ *
+ * Receive x402 settlement notifications from facilitators (Coinbase CDP, etc.)
+ *
+ * This endpoint:
+ * - Validates the webhook signature (HMAC-SHA256 of payload with BOTCHA_WEBHOOK_SECRET)
+ * - Updates payment records
+ * - Credits agent reputation on successful payment
+ * - Returns 200 to acknowledge receipt
+ *
+ * Expected payload: X402WebhookEvent
+ */
+export declare function x402WebhookRoute(c: Context): Promise<Response>;
+/**
+ * GET /v1/x402/info
+ *
+ * Public endpoint: returns x402 payment configuration for this BOTCHA instance.
+ * Agents can discover pricing, wallet, and supported networks.
+ */
+export declare function x402InfoRoute(c: Context): Promise<Response>;
+declare const _default: {
+    verifyPaymentRoute: typeof verifyPaymentRoute;
+    x402ChallengeRoute: typeof x402ChallengeRoute;
+    agentOnlyX402Route: typeof agentOnlyX402Route;
+    x402WebhookRoute: typeof x402WebhookRoute;
+    x402InfoRoute: typeof x402InfoRoute;
+};
+export default _default;
+//# sourceMappingURL=tap-x402-routes.d.ts.map

package/dist/tap-x402-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tap-x402-routes.d.ts","sourceRoot":"","sources":["../src/tap-x402-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAqEpC;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmFtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA6ItE;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsJtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsEpE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiDjE;;;;;;;;AAgDD,wBAME"}