@alleyboss/micropay-solana-x402-paywall 2.1.2 → 2.3.0

package/README.md

@@ -19,7 +19,7 @@ npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
 | Feature | Description |
 |---------|-------------|
 | 💰 **SOL & USDC Payments** | Native SOL and SPL tokens (USDC, USDT) |
-| 🔐 **x402 Protocol** | HTTP 402 Payment Required standard |
+| 🔐 **x402 Protocol** | Full HTTP 402 compliance with `X-Payment-Required` headers |
 | 🔑 **JWT Sessions** | Secure unlock tracking with anti-replay |
 | 🛡️ **Signature Store** | Prevent double-spend at app layer |
 | 🔌 **Express & Next.js** | Zero-boilerplate middleware |
@@ -82,27 +82,42 @@ import { getSolPrice, formatPriceDisplay, configurePricing } from '@alleyboss/mi
 import { withRetry } from '@alleyboss/micropay-solana-x402-paywall/utils';
 ```
 
-## 🔥 New in v2.1.0
+## 🔥 New in v2.2.0
 
-- **RPC Fallback Support** — Automatic failover on primary RPC failure (configurable, default: off)
-- **Priority Fees** — Compute budget instructions for landing transactions faster (configurable, default: off)
-- **Versioned Transactions** — Full v0 transaction support with lookup tables
-- **TDD Test Suite** — Comprehensive tests with vitest (must pass before npm publish)
+### x402 Protocol Compliance
+
+Full compliance with the [x402.org](https://x402.org) specification:
 
 ```typescript
-// RPC Fallback configuration
-const config = {
-  network: 'mainnet-beta',
-  rpcUrl: 'https://primary-rpc.com',
-  enableFallback: true, // default: false
-  fallbackRpcUrls: [
-    'https://fallback1.com',
-    'https://fallback2.com',
-  ],
-};
+import { create402Response, parsePaymentHeader, encodePaymentRequirement } from '@alleyboss/micropay-solana-x402-paywall/x402';
+
+// Create 402 response with X-Payment-Required header
+const response = create402Response({
+  scheme: 'exact',
+  network: 'solana-mainnet',
+  maxAmountRequired: '10000000',
+  payTo: 'CreatorWallet...',
+  resource: '/api/premium',
+  description: 'Premium content access',
+  maxTimeoutSeconds: 300,
+  asset: 'native',
+});
+// Response includes: X-Payment-Required: <base64-encoded-requirement>
 
+// Parse X-Payment header from client
+const payload = parsePaymentHeader(request.headers.get('x-payment'));
+```
+
+### Previous Features (v2.1.x)
+
+- **RPC Fallback Support** — Automatic failover on primary RPC failure
+- **Priority Fees** — Compute budget instructions for landing transactions faster
+- **Versioned Transactions** — Full v0 transaction support with lookup tables
+- **TDD Test Suite** — Comprehensive tests with vitest
+
+```typescript
 // Priority fees
-import { createPriorityFeeInstructions, estimatePriorityFee } from '@alleyboss/micropay-solana-x402-paywall/solana';
+import { createPriorityFeeInstructions } from '@alleyboss/micropay-solana-x402-paywall/solana';
 
 const instructions = createPriorityFeeInstructions({
   enabled: true,

package/dist/index.cjs

@@ -148,7 +148,8 @@ async function verifyPayment(params) {
     expectedRecipient,
     expectedAmount,
     maxAgeSeconds = 300,
-    clientConfig
+    clientConfig,
+    signatureStore
   } = params;
   if (!isValidSignature(signature)) {
     return { valid: false, confirmed: false, signature, error: "Invalid signature format" };
@@ -159,6 +160,12 @@ async function verifyPayment(params) {
   if (expectedAmount <= 0n) {
     return { valid: false, confirmed: false, signature, error: "Invalid expected amount" };
   }
+  if (signatureStore) {
+    const isUsed = await signatureStore.hasBeenUsed(signature);
+    if (isUsed) {
+      return { valid: false, confirmed: true, signature, error: "Signature already used" };
+    }
+  }
   const effectiveMaxAge = Math.min(Math.max(maxAgeSeconds, 60), 3600);
   const connection = getConnection(clientConfig);
   try {
@@ -267,8 +274,6 @@ function solToLamports(sol) {
   }
   return BigInt(Math.floor(sol * web3_js.LAMPORTS_PER_SOL));
 }
-
-// src/solana/spl.ts
 var SIGNATURE_REGEX2 = /^[1-9A-HJ-NP-Za-km-z]{87,88}$/;
 var WALLET_REGEX2 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 function resolveMintAddress(asset, network) {
@@ -362,8 +367,15 @@ async function verifySPLPayment(params) {
     expectedAmount,
     asset,
     clientConfig,
-    maxAgeSeconds = 300
+    maxAgeSeconds = 300,
+    signatureStore
   } = params;
+  if (signatureStore) {
+    const isUsed = await signatureStore.hasBeenUsed(signature);
+    if (isUsed) {
+      return { valid: false, confirmed: true, signature, error: "Signature already used" };
+    }
+  }
   if (!SIGNATURE_REGEX2.test(signature)) {
     return { valid: false, confirmed: false, signature, error: "Invalid signature format" };
   }
@@ -408,6 +420,27 @@ async function verifySPLPayment(params) {
         error: "No valid token transfer to recipient found"
       };
     }
+    if (transfer.to) {
+      try {
+        const destinationInfo = await connection.getParsedAccountInfo(new web3_js.PublicKey(transfer.to));
+        const owner = destinationInfo.value?.data?.parsed?.info?.owner;
+        if (owner && owner !== expectedRecipient) {
+          return {
+            valid: false,
+            confirmed: true,
+            signature,
+            error: "Recipient mismatch: Token account not owned by merchant"
+          };
+        }
+      } catch (e) {
+        return {
+          valid: false,
+          confirmed: true,
+          signature,
+          error: "Could not verify token account owner"
+        };
+      }
+    }
     if (transfer.mint !== mintAddress) {
       return {
         valid: false,
@@ -829,9 +862,28 @@ function parsePaymentHeader(header) {
     return null;
   }
 }
+function encodePaymentRequirement(requirement) {
+  return Buffer.from(JSON.stringify(requirement)).toString("base64");
+}
 function encodePaymentResponse(response) {
   return Buffer.from(JSON.stringify(response)).toString("base64");
 }
+function create402Response(requirement, body) {
+  const headers = new Headers({
+    "Content-Type": "application/json",
+    "X-Payment-Required": encodePaymentRequirement(requirement)
+  });
+  const responseBody = body || {
+    error: "Payment Required",
+    message: "This resource requires payment to access",
+    x402Version: 1,
+    accepts: [requirement]
+  };
+  return new Response(JSON.stringify(responseBody), {
+    status: 402,
+    headers
+  });
+}
 
 // src/store/memory.ts
 function createMemoryStore(options = {}) {
@@ -976,16 +1028,22 @@ function createPaywallMiddleware(config2) {
     const sessionToken = cookies[cookieName];
     const result = await checkPaywallAccess(path, sessionToken, config2);
     if (!result.allowed && result.requiresPayment) {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (config2.paymentRequirement) {
+        const requirement = typeof config2.paymentRequirement === "function" ? config2.paymentRequirement(path) : config2.paymentRequirement;
+        headers["X-Payment-Required"] = encodePaymentRequirement(requirement);
+      }
       const body = config2.custom402Response ? config2.custom402Response(path) : {
         error: "Payment Required",
         message: "This resource requires payment to access",
+        x402Version: 1,
         path
       };
       return new Response(JSON.stringify(body), {
         status: 402,
-        headers: {
-          "Content-Type": "application/json"
-        }
+        headers
       });
     }
     return null;
@@ -1261,14 +1319,14 @@ async function getSolPrice() {
     }
   }
   if (cachedPrice) {
-    return cachedPrice;
+    return {
+      ...cachedPrice,
+      source: `${cachedPrice.source} (stale)`
+    };
   }
-  return {
-    solPrice: 150,
-    // Reasonable fallback
-    fetchedAt: /* @__PURE__ */ new Date(),
-    source: "fallback"
-  };
+  throw new Error(
+    "Failed to fetch SOL price from all providers. Configure a custom provider or ensure network connectivity."
+  );
 }
 async function lamportsToUsd(lamports) {
   const { solPrice } = await getSolPrice();
@@ -1314,6 +1372,7 @@ exports.checkPaywallAccess = checkPaywallAccess;
 exports.clearPriceCache = clearPriceCache;
 exports.configurePricing = configurePricing;
 exports.create402Headers = create402Headers;
+exports.create402Response = create402Response;
 exports.create402ResponseBody = create402ResponseBody;
 exports.createMemoryStore = createMemoryStore;
 exports.createPaymentFlow = createPaymentFlow;
@@ -1324,6 +1383,7 @@ exports.createRedisStore = createRedisStore;
 exports.createSession = createSession;
 exports.decodePaymentRequired = decodePaymentRequired;
 exports.encodePaymentRequired = encodePaymentRequired;
+exports.encodePaymentRequirement = encodePaymentRequirement;
 exports.encodePaymentResponse = encodePaymentResponse;
 exports.estimatePriorityFee = estimatePriorityFee;
 exports.fetchLookupTables = fetchLookupTables;