mpp-server-middleware

name	mpp-server-middleware
description	Implement MPP server-side middleware for Hono, Express, Next.js, and Elysia. Use when protecting API routes with HTTP 402 payment gates, configuring payment methods, or setting up the Mppx server instance.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

MPP Server Middleware

Before writing code

Fetch live docs:

1. Fetch https://www.npmjs.com/package/mppx for the current server middleware API and configuration options
2. Web-search mppx server middleware hono express next.js elysia for framework-specific integration patterns
3. Web-search site:github.com stripe-samples machine-payments server for official server sample code
4. Fetch https://docs.stripe.com/payments/machine/mpp for Stripe-side server configuration

Conceptual Architecture

What the Server Middleware Does

The mppx server middleware intercepts requests to protected routes and implements the full HTTP 402 challenge-response flow:

1. Intercept — Middleware runs before your route handler
2. Challenge — If no Authorization: Payment header, returns 402 with WWW-Authenticate: Payment challenge
3. Verify — If credential present, validates proof of payment (on-chain verification, SPT validation, etc.)
4. Pass-through — On successful verification, calls the next handler
5. Receipt — Adds Payment-Receipt header to the response

Mppx.create() Configuration

The central factory creates the server instance:

const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY,  // 32-byte hex for HMAC challenge binding
  methods: [/* payment method configurations */],
});

The secretKey is critical — it binds challenges to prevent forgery and replay attacks.

Supported Frameworks

Framework	Middleware Pattern	Notes
Hono	app.get('/path', mppx.charge(...), handler)	Native middleware chaining
Express	app.get('/path', mppx.charge(...), handler)	Standard Express middleware
Next.js	Route handler wrapping	App Router and Pages Router
Elysia	Plugin-style integration	Bun-native framework

Route Protection

Two middleware functions match the two payment intents:

• mppx.charge({ amount }) — Per-request payment gate (charge intent)
• mppx.session({ maxAmount }) — Session-based streaming payment gate (session intent)

Amount Specification

• Amounts are strings representing the smallest currency unit
• For USDC: '100' = $0.01 (USDC has 6 decimals, so 100 = 0.000100, but convention varies by method)
• For Stripe: follows Stripe's minor-unit convention (cents)
• Always verify exact amount semantics in the SDK docs for your payment method

Multiple Payment Methods

A single server can accept multiple payment methods simultaneously:

const mppx = Mppx.create({
  secretKey: process.env.MPP_SECRET_KEY,
  methods: [
    tempo.charge({ /* Tempo config */ }),
    stripe.charge({ /* Stripe config */ }),
  ],
});

The client selects which method to use when fulfilling the challenge.

Dynamic Pricing

For routes where the price depends on the request:

• Use a pricing function that receives the request and returns the amount
• Implement custom middleware that computes the price and passes it to mppx.charge()

Error Responses

The middleware returns RFC 9457 Problem Details on payment errors:

Status	Type	When
402	payment-required	No credential provided
402	verification-failed	Invalid proof of payment
402	payment-expired	Challenge or credential expired
402	malformed-credential	Unparseable credential

Best Practices

• Always use environment variables for secretKey, never hardcode
• Set appropriate challenge expiration times (not too short for UX, not too long for security)
• Log payment verification results (without sensitive data) for debugging
• Implement health check endpoints outside the payment middleware
• Use HTTPS in production (TLS 1.2+ required by spec)
• Add CORS headers if the API is consumed from browsers

Fetch the latest mppx package README for exact middleware API signatures, configuration options, and framework-specific examples before implementing.