@mcpaid/sdk 2.0.0 → 2.0.1

package/README.md

@@ -4,7 +4,7 @@
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Base Mainnet](https://img.shields.io/badge/Base%20Mainnet-EVM%208453-blue)](https://basescan.org)
 [![Circle USDC](https://img.shields.io/badge/USDC-0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913-brightgreen)](https://basescan.org/token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
-[![Test Suite](https://img.shields.io/badge/tests-141%20passing-success.svg)](test)
+[![Test Suite](https://img.shields.io/badge/tests-163%20passing-success.svg)](test)
 
 **MCPaid** enables developers of [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers to seamlessly monetize tools with pay-per-use micropayments (e.g. $0.005 / call), gasless AI agent authorizations via **HTTP 402 + EIP-712**, and **automated 60-second on-chain USDC payouts on Base L2**.
 
@@ -27,16 +27,22 @@
    - When a developer requests a withdrawal, Cloudflare Workers' isolated cron relayer automatically executes the on-chain ERC-20 transfer on Base L2 every **60 seconds**, stamping confirmed BaseScan receipts directly into the dashboard.
    - **Zero HTTP Attack Surface**: All payout execution paths run strictly via internal edge cron triggers or authenticated local operator scripts (`mcpaid relayer --run`).
 
-4. **Zero-Config Live Development Tunnel (`mcpaid dev`)**:
+4. **Cryptographic Edge Receipts (`X-MCPaid-Receipt`) & Downstream Enforcement**:
+   - Single-use, tamper-proof HMAC-SHA256 payment receipts injected by the edge gateway on proxied requests.
+   - Downstream origin backends, microservices, and databases verify payment proofs in **5 lines of code**, preventing forked clients or scrapers from bypassing the edge gateway.
+   - Per-server secret derivation via HKDF-SHA256 (`mcpaid_sec_...`) with zero-downtime 1-hour grace window key rotation.
+   - Built-in anti-replay nonce claim store (`MemoryReceiptStore`, `D1ReceiptStore`) and drop-in Express middleware (`createReceiptMiddleware`).
+
+5. **Zero-Config Live Development Tunnel (`mcpaid dev`)**:
    - Monetize MCP servers running locally on hardware (`http://127.0.0.1:3000/mcp`) without buying domains or renting cloud VPS servers.
    - Launches an encrypted TLS 1.3 tunnel with an integrated **Security Shield** that drops direct bypass traffic with `403 Forbidden`.
 
-5. **Server Management & Anti-Hijacking Security**:
+6. **Server Management & Anti-Hijacking Security**:
    - Clean-slate server de-registration via Web Dashboard or CLI (`mcpaid server remove <id>`).
    - Ownership verification ensures server IDs cannot be overwritten by unauthorized third parties.
    - Passwordless 2FA email authentication with 30-day sliding-window sessions.
 
-6. **Agent Safety Circuit Breakers**:
+7. **Agent Safety Circuit Breakers**:
    - Built-in velocity limiters (sliding 1-minute window).
    - Spend ceiling hard caps (`maxPricePerCallUsd`, `maxTotalBudgetUsd`).
    - Infinite duplicate parameter loop detection.
@@ -316,6 +322,170 @@ print("Tool Result:", resp.json()["result"])
 
 ---
 
+## 🧾 Edge Receipts: Downstream Payment Enforcement
+
+When an agent invokes a paid MCP tool, MCPaid's edge verifies the 402 micropayment, credits your ledger, and proxies the request to your upstream server. But what if your upstream server forwards the call to a downstream backend, database, microservice, or webhook (e.g. committing a database write, enqueueing an expensive job, or calling third-party APIs)?
+
+Without cryptographic proof, your downstream backend cannot distinguish an authorized edge-settled call from an attacker or forked CLI hitting your internal endpoints directly.
+
+**Edge Receipts** solve this downstream trust boundary:
+1. When a paid call settles, the edge gateway mints a cryptographically signed receipt and injects it as an `X-MCPaid-Receipt` HTTP header (base64url-encoded JSON).
+2. Your downstream backend verifies the receipt in **5 lines of code** with anti-replay defense and tool binding.
+
+```
+[ AI Agent ]
+     │
+     │ 1. POST /mcp/:serverId (tools/call)
+     ▼
+[ MCPaid Edge Gateway ]
+     │
+     │ 2. HTTP 402 Payment Required (Price + Nonce)
+     ▼
+[ AI Agent Pays ]
+     │
+     │ 3. Signs gasless EIP-712 micro-permit & replays
+     ▼
+[ MCPaid Edge Gateway ]
+     │
+     │ 4. Settles micropayment on Base L2 ledger (97% Dev / 3% Platform)
+     │ 5. Mints signed receipt & proxies call with X-MCPaid-Receipt header
+     ▼
+[ Downstream Server / Origin Backend ]
+     │
+     │ 6. Verifies receipt in 5 lines (HMAC-SHA256 + atomic nonce claim)
+     ▼
+[ Commits DB write / executes heavy compute / returns response ]
+```
+
+### 1. Retrieve Your Server's Receipt Secret
+
+Each server has a deterministic receipt secret derived via `HKDF-SHA256` from the edge master secret. Retrieve it via the CLI:
+
+```bash
+# Display your server's receipt secret
+npx @mcpaid/sdk server receipt-secret <serverId>
+
+# Rotate secret (previous secret remains valid for 1-hour grace window)
+npx @mcpaid/sdk server receipt-secret <serverId> --rotate
+
+# Automatically append or update MCPAID_RECEIPT_SECRET in your local .env
+npx @mcpaid/sdk server receipt-secret <serverId> --env
+```
+
+### 2. Downstream Verification Code Snippets
+
+#### Option A: Express / Node.js Middleware
+
+Use the built-in `createReceiptMiddleware` for drop-in Express protection:
+
+```typescript
+import express from 'express';
+import { createReceiptMiddleware, MemoryReceiptStore } from '@mcpaid/sdk';
+
+const app = express();
+app.use(express.json());
+
+// Reject direct scrapers or un-settled calls in 5 lines
+app.post(
+  '/v1/heavy-compute',
+  createReceiptMiddleware({
+    secret: process.env.MCPAID_RECEIPT_SECRET!,
+    expectedTool: 'heavy_compute',
+    store: new MemoryReceiptStore(), // Prevents replay attacks
+  }),
+  (req: any, res) => {
+    // req.mcpaidReceipt contains verified settlement metadata
+    res.json({ success: true, payer: req.mcpaidReceipt.agentWallet });
+  }
+);
+
+app.listen(3000);
+```
+
+#### Option B: Cloudflare Worker / Serverless Edge
+
+Validate inside a Cloudflare Worker or Edge Function using `verifyEdgeReceipt` and SQLite/D1 replay storage:
+
+```typescript
+import { verifyEdgeReceipt, D1ReceiptStore } from '@mcpaid/sdk';
+
+export default {
+  async fetch(request: Request, env: any): Promise<Response> {
+    const error = await verifyEdgeReceipt(
+      {
+        secret: env.MCPAID_RECEIPT_SECRET,
+        previousSecret: env.MCPAID_PREVIOUS_RECEIPT_SECRET, // 1-hr rotation grace window
+        store: new D1ReceiptStore(env.DB),                 // Atomic SQLite anti-replay
+      },
+      {
+        receipt: request.headers.get('X-MCPaid-Receipt'),
+        expectedTool: 'cloud_sync_push',
+        maxAgeSeconds: 300, // 5-minute expiry
+      }
+    );
+
+    if (error) {
+      return new Response(JSON.stringify({ error: 'payment_required', message: error }), {
+        status: 402,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // Proceed with state-changing database write or API call
+    return new Response(JSON.stringify({ status: 'committed' }), { status: 200 });
+  },
+};
+```
+
+#### Option C: Python Downstream Backend (FastAPI / Flask)
+
+Verify receipts in Python using standard library cryptographic primitives (`hmac`, `hashlib`):
+
+```python
+import base64, hashlib, hmac, json, os, time
+from fastapi import FastAPI, Header, HTTPException
+
+app = FastAPI()
+SECRET = os.environ["MCPAID_RECEIPT_SECRET"]
+claimed_nonces = set()
+
+def verify_receipt(receipt_header: str, expected_tool: str) -> dict:
+    if not receipt_header:
+        raise HTTPException(status_code=402, detail="Missing X-MCPaid-Receipt header")
+    
+    # Pad base64url string if necessary and decode
+    padded = receipt_header + "=" * ((4 - len(receipt_header) % 4) % 4)
+    receipt = json.loads(base64.urlsafe_b64decode(padded).decode("utf-8"))
+    
+    if receipt.get("v") != 1 or receipt.get("toolName") != expected_tool:
+        raise HTTPException(status_code=402, detail="Invalid receipt tool or version")
+    
+    if time.time() > receipt.get("exp", 0) + 60:
+        raise HTTPException(status_code=402, detail="Receipt expired")
+    
+    # Recompute HMAC-SHA256 on canonical JSON without 'sig'
+    sig = receipt.pop("sig", "")
+    canonical = json.dumps(receipt, sort_keys=True, separators=(",", ":"))
+    computed = hmac.new(SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()
+    
+    if not hmac.compare_digest(sig, computed):
+        raise HTTPException(status_code=402, detail="Cryptographic signature mismatch")
+    
+    nonce = receipt["challengeNonce"]
+    if nonce in claimed_nonces:
+        raise HTTPException(status_code=402, detail="Receipt replay attack detected")
+    claimed_nonces.add(nonce)
+    
+    return receipt
+
+@app.post("/v1/db-commit")
+def commit_action(x_mcpaid_receipt: str = Header(None)):
+    verified = verify_receipt(x_mcpaid_receipt, expected_tool="db_commit")
+    return {"status": "success", "amount_paid_micro": verified["amountMicro"]}
+```
+
+---
+
 ## 🛠️ CLI Command Reference
 
 | Command | Arguments / Flags | Description |
@@ -327,6 +497,7 @@ print("Tool Result:", resp.json()["result"])
 | `mcpaid publish` | `[config-path] [--gateway <url>]` | Publish and monetize an MCP server on MCPaid Edge Gateway. |
 | `mcpaid server list` | `—` | List all MCP servers and pricing rules registered under your account. |
 | `mcpaid server remove` | `<server-id>` | Disconnect and permanently remove an MCP server (clean slate). |
+| `mcpaid server receipt-secret` | `<id> [--rotate] [--env]` | Retrieve or rotate HMAC-SHA256 Edge Receipt secret for backend verification. |
 | `mcpaid login` | `[--email <addr>]` | Sign in with passwordless 2FA email confirmation code. |
 | `mcpaid whoami` | `—` | Display authenticated developer profile and payout wallet. |
 | `mcpaid logout` | `—` | Revoke active session token and wipe local credentials. |
@@ -352,16 +523,16 @@ print("Tool Result:", resp.json()["result"])
 
 ## 🧪 Comprehensive Test Suite
 
-MCPaid includes **150 automated unit and integration tests** across 23 suites covering edge handlers, cryptographic verifiers, smart contract splits, financial ledgers, and the automated relayer:
+MCPaid includes **163 automated unit and integration tests** across 25 suites covering edge handlers, cryptographic verifiers, smart contract splits, financial ledgers, edge receipts, and the automated relayer:
 
 ```bash
 npm test
 ```
 
 ```
-# tests 150
-# suites 23
-# pass 150
+# tests 163
+# suites 25
+# pass 163
 # fail 0
 ```
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAqDH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,wBAAgB,eAAe,IAAI,cAAc,GAAG,IAAI,CASvD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAG3D;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAOvC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW9F;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW7D;AA8gBD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAmB5D;AA+6BD,wBAAsB,MAAM,kBAkE3B"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAqDH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,wBAAgB,eAAe,IAAI,cAAc,GAAG,IAAI,CASvD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAG3D;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAOvC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW9F;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAE9E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW7D;AA+gBD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAmB5D;AAkkCD,wBAAsB,MAAM,kBAkE3B"}

package/dist/cli.js

@@ -126,6 +126,7 @@ Commands:
   server add [config-path] Register an MCP server on MCPaid Edge Gateway
   server list              List your registered MCP servers
   server remove <id>       Disconnect and remove an MCP server from MCPaid
+  server receipt-secret <id> View or rotate Edge Receipt secret for backend verification (--rotate, --env)
   login                    Sign in to your MCPaid developer account
   logout                   Log out and remove local credentials
   whoami                   Show currently authenticated developer account
@@ -1124,6 +1125,7 @@ Choose how to proceed:
         creds.payoutWallet = config.payoutWallet;
         saveCredentials(creds);
     }
+    const receiptSecret = data.receiptSecret;
     console.log(`
 ======================================================
 🎉 MCP Server Successfully Published to MCPaid!
@@ -1133,6 +1135,7 @@ Choose how to proceed:
 • Edge Gateway: ${gatewayUrl}/mcp/${config.serverId}
 • Upstream:     ${upstreamUrl}
 • Payout:       ${config.payoutWallet} (Base L2)
+${receiptSecret ? `• Edge Receipt Secret: ${receiptSecret}` : ''}
 • Configured Tools (${config.tools.length}):
 ${config.tools.map((t) => `   • ${t.toolName.padEnd(20)} -> ${t.type === 'free' ? 'FREE' : `$${t.priceUsd} USDC`}`).join('\n')}
 
@@ -1140,6 +1143,31 @@ ${config.tools.map((t) => `   • ${t.toolName.padEnd(20)} -> ${t.type === 'free
   npx @mcpaid/sdk bridge --gateway ${gatewayUrl}/mcp/${config.serverId}
 ======================================================
 `);
+    if (receiptSecret) {
+        console.log(`🔐 Downstream Verification:
+Use verifyEdgeReceipt() from @mcpaid/sdk in your backend to ensure callers actually paid at the edge.`);
+        const envPath = resolve(process.cwd(), '.env');
+        const hasEnvFlag = hasFlag(args, 'env');
+        const shouldSave = hasEnvFlag
+            ? true
+            : (await promptQuestion('Save MCPAID_RECEIPT_SECRET to .env? (Y/n): ')).toLowerCase() !== 'n';
+        if (shouldSave) {
+            try {
+                let envContent = existsSync(envPath) ? readFileSync(envPath, 'utf-8') : '';
+                if (envContent.includes('MCPAID_RECEIPT_SECRET=')) {
+                    envContent = envContent.replace(/MCPAID_RECEIPT_SECRET=.*/g, `MCPAID_RECEIPT_SECRET=${receiptSecret}`);
+                }
+                else {
+                    envContent += `\n# MCPaid Edge Receipt Secret for backend verification\nMCPAID_RECEIPT_SECRET=${receiptSecret}\n`;
+                }
+                writeFileSync(envPath, envContent, 'utf-8');
+                console.log(`✅ Saved MCPAID_RECEIPT_SECRET to ${envPath}\n`);
+            }
+            catch (err) {
+                console.warn(`Could not update .env: ${err.message}`);
+            }
+        }
+    }
 }
 async function handleServerList() {
     const args = process.argv.slice(3);
@@ -1253,6 +1281,110 @@ Clean slate achieved. You can republish anytime with:
 npx @mcpaid/sdk publish
 `);
 }
+async function handleServerReceiptSecret(targetServerId) {
+    const args = process.argv.slice(3);
+    const gatewayUrl = getFlagValue(args, 'gateway') || process.env.MCPAID_GATEWAY_URL || 'https://mcpaid.dev';
+    const isRotate = args.includes('--rotate') || args.includes('-r');
+    const isSaveEnv = args.includes('--env') || args.includes('-e');
+    let serverId = targetServerId;
+    if (serverId && serverId.startsWith('-')) {
+        serverId = undefined;
+    }
+    if (!serverId) {
+        const nonFlags = args.filter(a => !a.startsWith('-') && a !== 'receipt-secret' && a !== 'secret');
+        if (nonFlags.length > 0) {
+            serverId = nonFlags[0];
+        }
+    }
+    const creds = loadCredentials();
+    const token = creds?.token || process.env.MCPAID_TOKEN;
+    if (!token) {
+        console.log('❌ You must be logged in to access server receipt secrets.');
+        console.log('Run: npx @mcpaid/sdk login');
+        return;
+    }
+    if (!serverId) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        serverId = await new Promise((res) => {
+            rl.question('Enter the ID of the MCP server: ', (ans) => {
+                rl.close();
+                res(ans.trim());
+            });
+        });
+    }
+    if (!serverId) {
+        console.error('❌ Error: Server ID is required. Example: npx @mcpaid/sdk server receipt-secret my-server');
+        return;
+    }
+    if (isRotate) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ans = await new Promise((res) => {
+            rl.question(`⚠️  Rotate Edge Receipt secret for "${serverId}"? (Previous secret remains valid for 1-hour grace window) (y/N): `, (a) => {
+                rl.close();
+                res(a.trim().toLowerCase());
+            });
+        });
+        if (ans !== 'y' && ans !== 'yes') {
+            console.log('Operation cancelled.');
+            return;
+        }
+    }
+    const endpoint = isRotate
+        ? `${gatewayUrl}/v1/servers/${encodeURIComponent(serverId)}/receipt-secret/rotate`
+        : `${gatewayUrl}/v1/servers/${encodeURIComponent(serverId)}/receipt-secret`;
+    const res = await fetch(endpoint, {
+        method: isRotate ? 'POST' : 'GET',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok || !data.success) {
+        console.error(`❌ Failed to retrieve receipt secret: ${data.error || JSON.stringify(data)}`);
+        return;
+    }
+    console.log(`
+======================================================
+🔑 MCPaid Edge Receipt Secret
+======================================================
+• Server ID:       ${data.serverId}
+• Receipt Secret:  ${data.receiptSecret}
+${data.previousReceiptSecret ? `• Previous Secret: ${data.previousReceiptSecret} (1-hr grace window active)` : ''}
+======================================================
+📋 Downstream Backend Verification (TypeScript / Node):
+  import { verifyEdgeReceipt } from '@mcpaid/sdk';
+
+  const err = await verifyEdgeReceipt(env, {
+    receipt: request.headers.get('X-MCPaid-Receipt'),
+    expectedTool: 'my_paid_tool',
+  });
+======================================================
+`);
+    if (isSaveEnv) {
+        const envPath = resolve(process.cwd(), '.env');
+        let envContent = existsSync(envPath) ? readFileSync(envPath, 'utf-8') : '';
+        if (envContent.includes('MCPAID_RECEIPT_SECRET=')) {
+            envContent = envContent.replace(/MCPAID_RECEIPT_SECRET=.*/g, `MCPAID_RECEIPT_SECRET=${data.receiptSecret}`);
+        }
+        else {
+            envContent += `\n# MCPaid Edge Receipt Secret for backend verification\nMCPAID_RECEIPT_SECRET=${data.receiptSecret}\n`;
+        }
+        if (data.previousReceiptSecret) {
+            if (envContent.includes('MCPAID_PREVIOUS_RECEIPT_SECRET=')) {
+                envContent = envContent.replace(/MCPAID_PREVIOUS_RECEIPT_SECRET=.*/g, `MCPAID_PREVIOUS_RECEIPT_SECRET=${data.previousReceiptSecret}`);
+            }
+            else {
+                envContent += `MCPAID_PREVIOUS_RECEIPT_SECRET=${data.previousReceiptSecret}\n`;
+            }
+        }
+        writeFileSync(envPath, envContent, 'utf-8');
+        console.log(`✅ Saved MCPAID_RECEIPT_SECRET to ${envPath}\n`);
+        if (data.previousReceiptSecret) {
+            console.log(`ℹ️  Saved MCPAID_PREVIOUS_RECEIPT_SECRET (active for 1-hr grace period)`);
+        }
+    }
+}
 async function handleServer() {
     const sub = process.argv[3];
     if (sub === 'list' || sub === 'ls') {
@@ -1264,13 +1396,17 @@ async function handleServer() {
     if (sub === 'remove' || sub === 'rm' || sub === 'delete' || sub === 'disconnect') {
         return handleServerRemove(process.argv[4]);
     }
+    if (sub === 'receipt-secret' || sub === 'secret') {
+        return handleServerReceiptSecret(process.argv[4]);
+    }
     console.log(`
 Usage: npx @mcpaid/sdk server <command>
 
 Commands:
-  add [config-path]   Publish and monetize an MCP server on MCPaid Edge Gateway
-  list                List all MCP servers registered under your account
-  remove <server-id>  Disconnect and remove an MCP server from MCPaid network
+  add [config-path]          Publish and monetize an MCP server on MCPaid Edge Gateway
+  list                       List all MCP servers registered under your account
+  remove <server-id>         Disconnect and remove an MCP server from MCPaid network
+  receipt-secret <server-id> Retrieve or rotate Edge Receipt secret for backend verification (--rotate, --env)
 `);
 }
 async function handleWithdraw(amountArg) {