@dupecom/botcha-cloudflare 0.20.2 → 0.23.0

package/dist/tap-x402.d.ts

@@ -0,0 +1,222 @@
+/**
+ * x402 Payment Gating — BOTCHA Revenue via HTTP 402
+ *
+ * Implements the x402 HTTP Payment Required protocol so BOTCHA-verified
+ * agents can natively access paid APIs, and BOTCHA earns per-verification.
+ *
+ * Spec: https://x402.org / https://github.com/coinbase/x402
+ *
+ * Flow:
+ *   1. Agent requests a protected resource
+ *   2. Server returns HTTP 402 + X-Payment-Required header (payment details)
+ *   3. Agent signs a ERC-3009 transferWithAuthorization and sends X-Payment header
+ *   4. Server verifies payment on-chain (or via facilitator) and issues BOTCHA token
+ *
+ * Key standard:
+ *   - Scheme: "exact" — fixed USD amount, exact recipient
+ *   - Network: "base" (Base mainnet, chain ID 8453)
+ *   - Token: USDC on Base (6 decimals, 1000 units = $0.001)
+ *   - Verification: ERC-3009 signature (EIP-712 structured data)
+ */
+import type { KVNamespace } from './agents.js';
+import { type ES256SigningKeyJWK } from './auth.js';
+/**
+ * BOTCHA's receiving wallet on Base. Set via BOTCHA_PAYMENT_WALLET env var.
+ * Placeholder: in production, override with BOTCHA_PAYMENT_WALLET secret.
+ * This address (b07ca = "botcha" mapped to hex-safe chars) is not owned by anyone.
+ */
+export declare const BOTCHA_WALLET = "0xb07ca00000000000000000000000000000000001";
+/** USDC contract address on Base (mainnet) */
+export declare const USDC_BASE_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** Base chain ID */
+export declare const BASE_CHAIN_ID = 8453;
+/** Price per BOTCHA verification in USDC atomic units (6 decimals) */
+/** 1000 units = $0.001 USDC */
+export declare const VERIFICATION_PRICE_USDC_UNITS = "1000";
+/** Human-readable price */
+export declare const VERIFICATION_PRICE_HUMAN = "$0.001 USDC";
+/** Payment deadline window (seconds) */
+export declare const PAYMENT_DEADLINE_SECONDS = 300;
+/** KV TTL for x402 nonces (replay protection) */
+export declare const NONCE_TTL_SECONDS = 3600;
+/**
+ * x402 "exact" scheme payment requirements.
+ * This is what goes in the X-Payment-Required header (JSON).
+ */
+export interface X402PaymentRequired {
+    scheme: 'exact';
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+    mimeType: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    asset: string;
+    extra?: {
+        name: string;
+        version: string;
+        botcha_app_id?: string;
+    };
+}
+/**
+ * ERC-3009 transferWithAuthorization payload embedded in X-Payment header.
+ * This is the on-chain payment proof signed by the payer.
+ */
+export interface ERC3009TransferPayload {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+    signature: string;
+    chainId?: number;
+}
+/**
+ * x402 payment proof sent by the agent in the X-Payment header.
+ * Base64-encoded JSON of this structure.
+ */
+export interface X402PaymentProof {
+    scheme: 'exact';
+    network: string;
+    payload: ERC3009TransferPayload;
+}
+/**
+ * Result of x402 payment verification
+ */
+export interface X402VerificationResult {
+    verified: boolean;
+    valid: boolean;
+    txHash?: string;
+    payer?: string;
+    amount?: string;
+    network?: string;
+    error?: string;
+    errorCode?: string;
+}
+/**
+ * x402 webhook event (from Coinbase CDP or other facilitators)
+ */
+export interface X402WebhookEvent {
+    event_type: 'payment.settled' | 'payment.failed' | 'payment.refunded';
+    payment_id: string;
+    tx_hash: string;
+    from: string;
+    to: string;
+    amount: string;
+    token: string;
+    network: string;
+    resource: string;
+    timestamp: string;
+    metadata?: Record<string, string>;
+}
+/**
+ * Record of an x402 payment stored in KV
+ */
+export interface X402PaymentRecord {
+    payment_id: string;
+    payer: string;
+    amount: string;
+    network: string;
+    tx_hash: string;
+    resource: string;
+    nonce: string;
+    botcha_app_id?: string;
+    agent_id?: string;
+    access_token?: string;
+    verified_at: number;
+    status: 'verified' | 'rejected' | 'pending';
+}
+/**
+ * Build a standard x402 payment required descriptor.
+ * Goes into the X-Payment-Required response header.
+ */
+export declare function buildPaymentRequiredDescriptor(resource: string, options?: {
+    description?: string;
+    mimeType?: string;
+    payTo?: string;
+    amount?: string;
+    appId?: string;
+}): X402PaymentRequired;
+/**
+ * Parse and decode an X-Payment header value (base64 JSON)
+ * Returns null if invalid format.
+ */
+export declare function parsePaymentHeader(headerValue: string): X402PaymentProof | null;
+/**
+ * Verify an x402 payment proof.
+ *
+ * Checks:
+ * 1. Network matches Base
+ * 2. Recipient matches BOTCHA wallet
+ * 3. Amount >= required
+ * 4. Deadline has not expired (validBefore)
+ * 5. Nonce has not been replayed (KV check)
+ * 6. EIP-712 signature is valid (ERC-3009)
+ *
+ * Note: This verifies the ERC-3009 typed-data signature locally.
+ * It does not confirm on-chain settlement; use facilitator webhooks for that.
+ */
+export declare function verifyX402Payment(proof: X402PaymentProof, noncesKV: KVNamespace, options?: {
+    requiredRecipient?: string;
+    requiredAmount?: string;
+}): Promise<X402VerificationResult>;
+export declare function buildERC3009TransferDigest(payload: ERC3009TransferPayload): Uint8Array;
+/**
+ * Store a verified x402 payment record in KV
+ */
+export declare function storePaymentRecord(noncesKV: KVNamespace, record: X402PaymentRecord): Promise<void>;
+/**
+ * Get a payment record by ID
+ */
+export declare function getPaymentRecord(noncesKV: KVNamespace, paymentId: string): Promise<X402PaymentRecord | null>;
+/**
+ * Issue a BOTCHA access_token in exchange for a verified x402 payment.
+ * This is the core pay-for-verification flow.
+ *
+ * The issued token is identical to a challenge-solve token —
+ * agents that pay get the same trust level as agents that solve.
+ */
+export declare function issueTokenForPayment(challengesKV: KVNamespace, env: {
+    JWT_SECRET: string;
+    JWT_SIGNING_KEY?: string;
+}, options: {
+    payer: string;
+    paymentId: string;
+    appId?: string;
+    audience?: string;
+    solveTimeMs?: number;
+}, signingKey?: ES256SigningKeyJWK): Promise<{
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    refresh_expires_in: number;
+}>;
+/**
+ * Build the X-Payment-Response header value for successful payment
+ */
+export declare function buildPaymentResponseHeader(result: X402VerificationResult): string;
+/**
+ * Process an inbound x402 webhook event from a facilitator.
+ *
+ * On payment.settled: update agent reputation, store payment record.
+ * On payment.failed: log failure.
+ * On payment.refunded: note in record.
+ */
+export declare function processWebhookEvent(event: X402WebhookEvent, noncesKV: KVNamespace, agentsKV: KVNamespace, sessionsKV: KVNamespace, webhookSecret?: string): Promise<{
+    handled: boolean;
+    message: string;
+}>;
+declare const _default: {
+    buildPaymentRequiredDescriptor: typeof buildPaymentRequiredDescriptor;
+    parsePaymentHeader: typeof parsePaymentHeader;
+    verifyX402Payment: typeof verifyX402Payment;
+    issueTokenForPayment: typeof issueTokenForPayment;
+    buildPaymentResponseHeader: typeof buildPaymentResponseHeader;
+    storePaymentRecord: typeof storePaymentRecord;
+    getPaymentRecord: typeof getPaymentRecord;
+    processWebhookEvent: typeof processWebhookEvent;
+};
+export default _default;
+//# sourceMappingURL=tap-x402.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tap-x402.d.ts","sourceRoot":"","sources":["../src/tap-x402.ts"],"names":[],"mappings":"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"}