@dexterai/x402 1.4.1 → 1.5.0

package/dist/server/index.d.cts

@@ -1,5 +1,5 @@
-import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, a as PaymentRequired } from '../types-B7T6dZ-y.cjs';
-export { B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, b as SOLANA_MAINNET_NETWORK, c as USDC_BASE, U as USDC_MINT } from '../types-B7T6dZ-y.cjs';
+import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, c as PaymentRequired } from '../types-CcVAaoro.cjs';
+export { d as AccessPassClaims, A as AccessPassClientConfig, b as AccessPassInfo, a as AccessPassTier, B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, e as SOLANA_MAINNET_NETWORK, f as USDC_BASE, U as USDC_MINT } from '../types-CcVAaoro.cjs';
 import { Request, RequestHandler } from 'express';
 
 /**
@@ -308,6 +308,104 @@ interface X402Request extends Request {
  */
 declare function x402Middleware(config: X402MiddlewareConfig): RequestHandler;
 
+/**
+ * x402 Access Pass Middleware
+ *
+ * Pay once, get a time-limited JWT for unlimited API requests.
+ * Supports both predefined tiers and custom durations.
+ *
+ * @example Tier-based pricing
+ * ```typescript
+ * app.use('/api', x402AccessPass({
+ *   payTo: 'YourSolanaAddress...',
+ *   tiers: {
+ *     '1h':  '0.50',   // $0.50 for 1 hour
+ *     '24h': '2.00',   // $2.00 for 24 hours
+ *   },
+ * }));
+ * ```
+ *
+ * @example Rate-based custom durations
+ * ```typescript
+ * app.use('/api', x402AccessPass({
+ *   payTo: 'YourSolanaAddress...',
+ *   ratePerHour: '0.50',  // $0.50/hour, any duration
+ * }));
+ * ```
+ *
+ * @example Both tiers and custom durations
+ * ```typescript
+ * app.use('/api', x402AccessPass({
+ *   payTo: 'YourSolanaAddress...',
+ *   tiers: { '1h': '0.50', '24h': '2.00' },
+ *   ratePerHour: '0.50',  // fallback for custom durations
+ * }));
+ * ```
+ */
+
+/**
+ * Access pass middleware configuration
+ */
+interface X402AccessPassConfig {
+    /** Address to receive payments (Solana pubkey or EVM address) */
+    payTo: string;
+    /** CAIP-2 network identifier @default 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' */
+    network?: string;
+    /** x402 facilitator URL @default 'https://x402-facilitator.dexter.cash' */
+    facilitatorUrl?: string;
+    /** Asset config @default USDC on specified network */
+    asset?: {
+        address: string;
+        decimals: number;
+    };
+    /**
+     * Predefined pricing tiers.
+     * Keys are tier IDs (e.g., '5m', '1h', '24h').
+     * Values are prices in USD (e.g., '0.50').
+     * Duration is parsed from the ID: '5m' = 5 minutes, '1h' = 1 hour, '24h' = 24 hours, '7d' = 7 days.
+     */
+    tiers?: Record<string, string>;
+    /**
+     * Rate per hour in USD for custom durations.
+     * When set, buyers can request any duration via ?duration=<seconds> query param.
+     */
+    ratePerHour?: string;
+    /** HMAC secret for JWT signing. Auto-generated if not provided. */
+    secret?: Buffer;
+    /** Issuer string for JWT 'iss' claim @default 'x402-access-pass' */
+    issuer?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Description shown in 402 response */
+    description?: string;
+}
+/**
+ * Extended request with access pass info
+ */
+interface X402AccessPassRequest extends Request {
+    /** Access pass info (present when request is authenticated via valid pass) */
+    accessPass?: {
+        tier: string;
+        duration: number;
+        expiresAt: string;
+        payer: string;
+        network: string;
+    };
+    /** x402 payment info (present when a new pass was just purchased) */
+    x402?: {
+        transaction: string;
+        payer: string;
+        network: string;
+    };
+}
+/**
+ * Create x402 access pass middleware for Express.
+ *
+ * Protects routes with time-limited access passes purchased via x402 payments.
+ * Supports predefined tiers, custom durations, or both.
+ */
+declare function x402AccessPass(config: X402AccessPassConfig): RequestHandler;
+
 /**
  * Dynamic Pricing for x402
  *
@@ -751,4 +849,4 @@ declare const MODEL_PRICING_MAP: Record<string, {
     tier: string;
 }>;
 
-export { type AssetConfig, type BuildRequirementsOptions, type DynamicPricing, type DynamicPricingConfig, FacilitatorClient, MODEL_PRICING, MODEL_PRICING_MAP, MODEL_REGISTRY, type ModelApiType, type ModelDefinition, type ModelModality, type ModelParameters, type ModelPricing$1 as ModelPricing, type ModelTier, PaymentAccept, PaymentRequired, type PriceQuote, type ModelPricing as RegistryModelPricing, SettleResponse, type SupportedKind, type SupportedResponse, type TokenPriceQuote, type TokenPricing, type TokenPricingConfig, VerifyResponse, type X402MiddlewareConfig, type X402Request, type X402Server, type X402ServerConfig, countTokens, createDynamicPricing, createTokenPricing, createX402Server, estimateCost, findModel, formatModelPricing, formatPricing, formatTokenPricing, getActiveModels, getAvailableModelIds, getAvailableModels, getCheapestModel, getModel, getModelsByFamily, getModelsByTier, getTextModels, isValidModel, isValidModelId, x402Middleware };
+export { type AssetConfig, type BuildRequirementsOptions, type DynamicPricing, type DynamicPricingConfig, FacilitatorClient, MODEL_PRICING, MODEL_PRICING_MAP, MODEL_REGISTRY, type ModelApiType, type ModelDefinition, type ModelModality, type ModelParameters, type ModelPricing$1 as ModelPricing, type ModelTier, PaymentAccept, PaymentRequired, type PriceQuote, type ModelPricing as RegistryModelPricing, SettleResponse, type SupportedKind, type SupportedResponse, type TokenPriceQuote, type TokenPricing, type TokenPricingConfig, VerifyResponse, type X402AccessPassConfig, type X402AccessPassRequest, type X402MiddlewareConfig, type X402Request, type X402Server, type X402ServerConfig, countTokens, createDynamicPricing, createTokenPricing, createX402Server, estimateCost, findModel, formatModelPricing, formatPricing, formatTokenPricing, getActiveModels, getAvailableModelIds, getAvailableModels, getCheapestModel, getModel, getModelsByFamily, getModelsByTier, getTextModels, isValidModel, isValidModelId, x402AccessPass, x402Middleware };

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, a as PaymentRequired } from '../types-B7T6dZ-y.js';
-export { B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, b as SOLANA_MAINNET_NETWORK, c as USDC_BASE, U as USDC_MINT } from '../types-B7T6dZ-y.js';
+import { P as PaymentAccept, V as VerifyResponse, S as SettleResponse, c as PaymentRequired } from '../types-CcVAaoro.js';
+export { d as AccessPassClaims, A as AccessPassClientConfig, b as AccessPassInfo, a as AccessPassTier, B as BASE_MAINNET_NETWORK, D as DEXTER_FACILITATOR_URL, e as SOLANA_MAINNET_NETWORK, f as USDC_BASE, U as USDC_MINT } from '../types-CcVAaoro.js';
 import { Request, RequestHandler } from 'express';
 
 /**
@@ -308,6 +308,104 @@ interface X402Request extends Request {
  */
 declare function x402Middleware(config: X402MiddlewareConfig): RequestHandler;
 
+/**
+ * x402 Access Pass Middleware
+ *
+ * Pay once, get a time-limited JWT for unlimited API requests.
+ * Supports both predefined tiers and custom durations.
+ *
+ * @example Tier-based pricing
+ * ```typescript
+ * app.use('/api', x402AccessPass({
+ *   payTo: 'YourSolanaAddress...',
+ *   tiers: {
+ *     '1h':  '0.50',   // $0.50 for 1 hour
+ *     '24h': '2.00',   // $2.00 for 24 hours
+ *   },
+ * }));
+ * ```
+ *
+ * @example Rate-based custom durations
+ * ```typescript
+ * app.use('/api', x402AccessPass({
+ *   payTo: 'YourSolanaAddress...',
+ *   ratePerHour: '0.50',  // $0.50/hour, any duration
+ * }));
+ * ```
+ *
+ * @example Both tiers and custom durations
+ * ```typescript
+ * app.use('/api', x402AccessPass({
+ *   payTo: 'YourSolanaAddress...',
+ *   tiers: { '1h': '0.50', '24h': '2.00' },
+ *   ratePerHour: '0.50',  // fallback for custom durations
+ * }));
+ * ```
+ */
+
+/**
+ * Access pass middleware configuration
+ */
+interface X402AccessPassConfig {
+    /** Address to receive payments (Solana pubkey or EVM address) */
+    payTo: string;
+    /** CAIP-2 network identifier @default 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' */
+    network?: string;
+    /** x402 facilitator URL @default 'https://x402-facilitator.dexter.cash' */
+    facilitatorUrl?: string;
+    /** Asset config @default USDC on specified network */
+    asset?: {
+        address: string;
+        decimals: number;
+    };
+    /**
+     * Predefined pricing tiers.
+     * Keys are tier IDs (e.g., '5m', '1h', '24h').
+     * Values are prices in USD (e.g., '0.50').
+     * Duration is parsed from the ID: '5m' = 5 minutes, '1h' = 1 hour, '24h' = 24 hours, '7d' = 7 days.
+     */
+    tiers?: Record<string, string>;
+    /**
+     * Rate per hour in USD for custom durations.
+     * When set, buyers can request any duration via ?duration=<seconds> query param.
+     */
+    ratePerHour?: string;
+    /** HMAC secret for JWT signing. Auto-generated if not provided. */
+    secret?: Buffer;
+    /** Issuer string for JWT 'iss' claim @default 'x402-access-pass' */
+    issuer?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Description shown in 402 response */
+    description?: string;
+}
+/**
+ * Extended request with access pass info
+ */
+interface X402AccessPassRequest extends Request {
+    /** Access pass info (present when request is authenticated via valid pass) */
+    accessPass?: {
+        tier: string;
+        duration: number;
+        expiresAt: string;
+        payer: string;
+        network: string;
+    };
+    /** x402 payment info (present when a new pass was just purchased) */
+    x402?: {
+        transaction: string;
+        payer: string;
+        network: string;
+    };
+}
+/**
+ * Create x402 access pass middleware for Express.
+ *
+ * Protects routes with time-limited access passes purchased via x402 payments.
+ * Supports predefined tiers, custom durations, or both.
+ */
+declare function x402AccessPass(config: X402AccessPassConfig): RequestHandler;
+
 /**
  * Dynamic Pricing for x402
  *
@@ -751,4 +849,4 @@ declare const MODEL_PRICING_MAP: Record<string, {
     tier: string;
 }>;
 
-export { type AssetConfig, type BuildRequirementsOptions, type DynamicPricing, type DynamicPricingConfig, FacilitatorClient, MODEL_PRICING, MODEL_PRICING_MAP, MODEL_REGISTRY, type ModelApiType, type ModelDefinition, type ModelModality, type ModelParameters, type ModelPricing$1 as ModelPricing, type ModelTier, PaymentAccept, PaymentRequired, type PriceQuote, type ModelPricing as RegistryModelPricing, SettleResponse, type SupportedKind, type SupportedResponse, type TokenPriceQuote, type TokenPricing, type TokenPricingConfig, VerifyResponse, type X402MiddlewareConfig, type X402Request, type X402Server, type X402ServerConfig, countTokens, createDynamicPricing, createTokenPricing, createX402Server, estimateCost, findModel, formatModelPricing, formatPricing, formatTokenPricing, getActiveModels, getAvailableModelIds, getAvailableModels, getCheapestModel, getModel, getModelsByFamily, getModelsByTier, getTextModels, isValidModel, isValidModelId, x402Middleware };
+export { type AssetConfig, type BuildRequirementsOptions, type DynamicPricing, type DynamicPricingConfig, FacilitatorClient, MODEL_PRICING, MODEL_PRICING_MAP, MODEL_REGISTRY, type ModelApiType, type ModelDefinition, type ModelModality, type ModelParameters, type ModelPricing$1 as ModelPricing, type ModelTier, PaymentAccept, PaymentRequired, type PriceQuote, type ModelPricing as RegistryModelPricing, SettleResponse, type SupportedKind, type SupportedResponse, type TokenPriceQuote, type TokenPricing, type TokenPricingConfig, VerifyResponse, type X402AccessPassConfig, type X402AccessPassRequest, type X402MiddlewareConfig, type X402Request, type X402Server, type X402ServerConfig, countTokens, createDynamicPricing, createTokenPricing, createX402Server, estimateCost, findModel, formatModelPricing, formatPricing, formatTokenPricing, getActiveModels, getAvailableModelIds, getAvailableModels, getCheapestModel, getModel, getModelsByFamily, getModelsByTier, getTextModels, isValidModel, isValidModelId, x402AccessPass, x402Middleware };

package/dist/server/index.js

@@ -357,6 +357,245 @@ function x402Middleware(config) {
   };
 }
 
+// src/server/access-pass.ts
+import crypto from "crypto";
+var DURATION_REGEX = /^(\d+)(m|h|d|w)$/;
+function parseTierDuration(tierId) {
+  const match = tierId.match(DURATION_REGEX);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "m":
+      return value * 60;
+    case "h":
+      return value * 3600;
+    case "d":
+      return value * 86400;
+    case "w":
+      return value * 604800;
+    default:
+      return null;
+  }
+}
+function formatDuration(seconds) {
+  if (seconds >= 604800 && seconds % 604800 === 0) return `${seconds / 604800} week${seconds / 604800 > 1 ? "s" : ""}`;
+  if (seconds >= 86400 && seconds % 86400 === 0) return `${seconds / 86400} day${seconds / 86400 > 1 ? "s" : ""}`;
+  if (seconds >= 3600 && seconds % 3600 === 0) return `${seconds / 3600} hour${seconds / 3600 > 1 ? "s" : ""}`;
+  if (seconds >= 60 && seconds % 60 === 0) return `${seconds / 60} minute${seconds / 60 > 1 ? "s" : ""}`;
+  return `${seconds} second${seconds > 1 ? "s" : ""}`;
+}
+function signJwt(payload, secret) {
+  const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
+  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const sig = crypto.createHmac("sha256", secret).update(`${header}.${body}`).digest("base64url");
+  return `${header}.${body}.${sig}`;
+}
+function verifyJwt(token, secret) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const [header, body, sig] = parts;
+    const expected = crypto.createHmac("sha256", secret).update(`${header}.${body}`).digest("base64url");
+    if (sig !== expected) return null;
+    const payload = JSON.parse(Buffer.from(body, "base64url").toString());
+    if (payload.exp && Date.now() / 1e3 > payload.exp) return null;
+    if (payload.sub !== "x402-access-pass") return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+var DEFAULT_NETWORK2 = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+var USDC_DECIMALS2 = 6;
+function x402AccessPass(config) {
+  const {
+    payTo,
+    network = DEFAULT_NETWORK2,
+    asset,
+    facilitatorUrl,
+    tiers: tierPrices,
+    ratePerHour,
+    secret = crypto.randomBytes(32),
+    issuer = "x402-access-pass",
+    verbose = false,
+    description
+  } = config;
+  if (!tierPrices && !ratePerHour) {
+    throw new Error("x402AccessPass: at least one of `tiers` or `ratePerHour` is required");
+  }
+  const log = verbose ? console.log.bind(console, "[x402:access-pass]") : () => {
+  };
+  const decimals = asset?.decimals ?? USDC_DECIMALS2;
+  const builtTiers = [];
+  if (tierPrices) {
+    for (const [id, price] of Object.entries(tierPrices)) {
+      const seconds = parseTierDuration(id);
+      if (!seconds) {
+        console.warn(`x402AccessPass: skipping tier "${id}" \u2014 unrecognized duration format (use 5m, 1h, 24h, 7d)`);
+        continue;
+      }
+      builtTiers.push({
+        id,
+        label: formatDuration(seconds),
+        seconds,
+        price,
+        priceAtomic: toAtomicUnits(parseFloat(price), decimals)
+      });
+    }
+    builtTiers.sort((a, b) => a.seconds - b.seconds);
+  }
+  const server = createX402Server({
+    payTo,
+    network,
+    asset,
+    facilitatorUrl
+  });
+  const passInfo = {
+    tiers: builtTiers.length > 0 ? builtTiers : void 0,
+    ratePerHour: ratePerHour || void 0,
+    issuer
+  };
+  const passInfoEncoded = btoa(JSON.stringify(passInfo));
+  function calculateCustomPrice(durationSeconds) {
+    if (!ratePerHour) {
+      throw new Error("Custom durations not supported \u2014 no ratePerHour configured");
+    }
+    const hours = durationSeconds / 3600;
+    const price = (parseFloat(ratePerHour) * hours).toFixed(decimals > 4 ? 4 : 2);
+    return { price, priceAtomic: toAtomicUnits(parseFloat(price), decimals) };
+  }
+  function resolvePricing(req) {
+    const tierParam = req.query.tier;
+    const durationParam = req.query.duration;
+    if (tierParam) {
+      const found = builtTiers.find((t) => t.id === tierParam);
+      if (found) {
+        return { tier: found.id, seconds: found.seconds, price: found.price, priceAtomic: found.priceAtomic, label: found.label };
+      }
+    }
+    if (durationParam) {
+      const seconds = parseInt(durationParam, 10);
+      if (seconds > 0 && ratePerHour) {
+        const pricing2 = calculateCustomPrice(seconds);
+        return { tier: "custom", seconds, ...pricing2, label: formatDuration(seconds) };
+      }
+    }
+    if (builtTiers.length > 0) {
+      const t = builtTiers[0];
+      return { tier: t.id, seconds: t.seconds, price: t.price, priceAtomic: t.priceAtomic, label: t.label };
+    }
+    const pricing = calculateCustomPrice(3600);
+    return { tier: "custom", seconds: 3600, ...pricing, label: "1 hour" };
+  }
+  return async (req, res, next) => {
+    try {
+      const auth = req.headers.authorization;
+      if (auth?.startsWith("Bearer ")) {
+        const claims = verifyJwt(auth.slice(7), secret);
+        if (claims) {
+          log("Valid access pass:", claims.tier, "| expires:", new Date(claims.exp * 1e3).toISOString());
+          req.accessPass = {
+            tier: claims.tier,
+            duration: claims.duration,
+            expiresAt: new Date(claims.exp * 1e3).toISOString(),
+            payer: claims.payer,
+            network: claims.network
+          };
+          return next();
+        }
+        log("Invalid or expired access pass token");
+      }
+      const paymentSignature = req.headers["payment-signature"];
+      if (paymentSignature) {
+        log("Payment signature received, verifying for pass purchase...");
+        const verifyResult = await server.verifyPayment(paymentSignature);
+        if (!verifyResult.isValid) {
+          log("Payment verification failed:", verifyResult.invalidReason);
+          res.status(402).json({ error: "Payment verification failed", reason: verifyResult.invalidReason });
+          return;
+        }
+        const settleResult = await server.settlePayment(paymentSignature);
+        if (!settleResult.success) {
+          log("Payment settlement failed:", settleResult.errorReason);
+          res.status(402).json({ error: "Payment settlement failed", reason: settleResult.errorReason });
+          return;
+        }
+        log("Payment settled:", settleResult.transaction);
+        const pricing2 = resolvePricing(req);
+        const now = Math.floor(Date.now() / 1e3);
+        const claims = {
+          sub: "x402-access-pass",
+          tier: pricing2.tier,
+          duration: pricing2.seconds,
+          iat: now,
+          exp: now + pricing2.seconds,
+          payer: verifyResult.payer ?? "",
+          network,
+          iss: issuer
+        };
+        const jwt = signJwt(claims, secret);
+        req.x402 = {
+          transaction: settleResult.transaction,
+          payer: verifyResult.payer ?? "",
+          network
+        };
+        const paymentResponseData = {
+          success: true,
+          transaction: settleResult.transaction,
+          network,
+          payer: verifyResult.payer ?? ""
+        };
+        res.setHeader("PAYMENT-RESPONSE", btoa(JSON.stringify(paymentResponseData)));
+        res.setHeader("ACCESS-PASS", jwt);
+        res.json({
+          accessPass: {
+            token: jwt,
+            tier: pricing2.tier,
+            duration: pricing2.label,
+            durationSeconds: pricing2.seconds,
+            expiresAt: new Date((now + pricing2.seconds) * 1e3).toISOString(),
+            usage: "Include on subsequent requests as: Authorization: Bearer <token>"
+          },
+          transaction: settleResult.transaction,
+          payer: verifyResult.payer
+        });
+        return;
+      }
+      log("No access pass or payment, returning 402");
+      const pricing = resolvePricing(req);
+      const amountAtomic = pricing.priceAtomic;
+      const resourceUrl = `${req.protocol}://${req.get("host")}${req.originalUrl}`;
+      const requirements = await server.buildRequirements({
+        amountAtomic,
+        resourceUrl,
+        description: description || `Access pass: ${pricing.label}`,
+        mimeType: "application/json"
+      });
+      const encoded = server.encodeRequirements(requirements);
+      res.setHeader("PAYMENT-REQUIRED", encoded);
+      res.setHeader("X-ACCESS-PASS-TIERS", passInfoEncoded);
+      res.status(402).json({
+        error: "Access pass required",
+        message: "Purchase an access pass to unlock unlimited API access for a time window.",
+        accepts: requirements.accepts,
+        resource: requirements.resource,
+        accessPass: {
+          tiers: builtTiers.length > 0 ? builtTiers : void 0,
+          ratePerHour: ratePerHour || void 0,
+          usage: "Add ?tier=<id> or ?duration=<seconds> to your payment request to choose a pass duration."
+        }
+      });
+    } catch (error) {
+      log("Access pass middleware error:", error);
+      res.status(500).json({
+        error: "Payment processing error",
+        message: error instanceof Error ? error.message : "Unknown error"
+      });
+    }
+  };
+}
+
 // src/server/dynamic-pricing.ts
 function simpleHash(str) {
   let hash = 2166136261;
@@ -1156,6 +1395,7 @@ export {
   getTextModels,
   isValidModel,
   isValidModelId,
+  x402AccessPass,
   x402Middleware
 };
 //# sourceMappingURL=index.js.map