MPP Development Patterns
Before writing code
Fetch live docs:
- Specification: Fetch
https://paymentauth.org/ for canonical security and encoding requirements
- IETF draft: Web-search
site:datatracker.ietf.org draft-ryan-httpauth-payment for the latest RFC draft
- Stripe docs: Fetch
https://docs.stripe.com/payments/machine/mpp for production integration patterns
- SDK: Web-search
site:npmjs.com mppx for error handling and retry APIs
Pattern: HMAC Challenge Binding
The 32-byte secretKey is the server's core security primitive:
- Every challenge ID is HMAC-bound to the secret key
- Prevents challenge forgery — attackers cannot create valid challenges without the key
- Prevents replay attacks — each challenge is unique and bound to the request context
- Generate with
openssl rand -hex 32
- Rotate periodically and support key rollover
const mppx = Mppx.create({
secretKey: process.env.MPP_SECRET_KEY, // 32-byte hex
methods: [/* ... */],
});
Pattern: Replay Protection
Single-use proof semantics prevent double-payment:
- Each credential can only be used once
- Server must track consumed credentials (at least until expiration)
- Atomic verification — check + consume in a single operation
- Use database transactions or atomic operations for credential tracking
- For high-throughput: use in-memory stores (Redis) with TTL matching challenge expiration
Pattern: Transport Security
MPP mandates TLS 1.2+ (TLS 1.3 recommended):
- All endpoints must serve over HTTPS (port 443)
Cache-Control: no-store on all responses containing credentials
- Never log plaintext credentials or payment proofs
- Credentials are treated as sensitive bearer tokens
Pattern: JSON Canonicalization
RFC 8785 canonical JSON is required for deterministic encoding:
- Challenges must use canonical JSON before base64url encoding
- Keeps challenges under 8KB (server-side)
- Clients must handle minimum 4KB challenges
- Use a library for RFC 8785 compliance rather than manual JSON serialization
Pattern: Error Handling
MPP uses RFC 9457 Problem Details for error responses:
{
"type": "https://paymentauth.org/problems/payment-required",
"status": 402,
"detail": "Payment is required.",
"challengeId": "..."
}
Error types:
payment-required — Normal challenge, no payment attempted yet
verification-failed — Invalid proof of payment
payment-expired — Challenge or credential expired
malformed-credential — Cannot parse the credential
Client retry strategy:
payment-required — Normal flow, fulfill and retry
verification-failed — Do NOT retry with same credential (likely invalid)
payment-expired — Request a fresh challenge
malformed-credential — Fix credential encoding, do not retry blindly
Pattern: Receipt Validation
The Payment-Receipt header proves delivery:
- Contains payment status, method, timestamp, reference ID
- Clients should store receipts for accounting and disputes
- Servers should generate receipts atomically with resource delivery
- Receipts serve as proof in billing reconciliation
Pattern: Rate Limiting
Even with payments, implement rate limiting:
- Prevents abuse from clients with large wallets
- Protects upstream resources from overload
- Return 429 with
Retry-After header when exceeded
- Client-side: honor
Retry-After, add jitter
Pattern: Amount Safety
- All amounts as strings representing the smallest currency unit
- Never use floating-point for monetary calculations
- Validate amounts on both client and server
- Reject negative or zero amounts
- Verify amount matches the challenged amount in the credential
Pattern: Secret Management
MPP_SECRET_KEY — 32-byte hex, rotate periodically
STRIPE_SECRET_KEY — Stripe API key, never in code
WALLET_PRIVATE_KEY — Crypto wallet key, use key management service
- Never commit secrets to version control
- Use
.env files for development, secrets manager for production
- Implement key rotation without downtime
Pattern: Monitoring & Observability
- Log every payment challenge issued (without sensitive data)
- Track payment success/failure rates per method
- Monitor challenge expiration rates (too many = too short TTL)
- Alert on verification failure spikes (potential attack)
- Track revenue per endpoint for pricing optimization
- Monitor Tempo chain health and Stripe API availability
- Dashboard payment method distribution
Pattern: Testing
- Use Tempo testnet for development (not mainnet)
- Use Stripe test mode keys and test card tokens
- Test the full 402 flow end-to-end
- Test challenge expiration handling
- Test replay rejection
- Test with multiple payment methods simultaneously
- Load test to verify payment verification throughput
Pattern: Caching
- Service discovery responses (
/openapi.json, /llms.txt) — cache aggressively
- Payment challenges — NEVER cache (time-bound, single-use)
- Credentials — NEVER cache (
Cache-Control: no-store)
- Upstream API responses (for proxies) — cache if idempotent and appropriate
Fetch the latest MPP specification and IETF draft for current security requirements, encoding rules, and best practices before implementing.
1---2name: mpp-dev-patterns3description: Cross-cutting MPP development patterns — security, replay protection, HMAC challenge binding, receipt validation, error handling, retry logic, TLS requirements, and monitoring. Use when designing architecture or solving production concerns.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/mpp-dev-patterns7---89# MPP Development Patterns1011## Before writing code1213**Fetch live docs**:14- Specification: Fetch `https://paymentauth.org/` for canonical security and encoding requirements15- IETF draft: Web-search `site:datatracker.ietf.org draft-ryan-httpauth-payment` for the latest RFC draft16- Stripe docs: Fetch `https://docs.stripe.com/payments/machine/mpp` for production integration patterns17- SDK: Web-search `site:npmjs.com mppx` for error handling and retry APIs1819## Pattern: HMAC Challenge Binding2021The 32-byte `secretKey` is the server's core security primitive:2223- Every challenge ID is HMAC-bound to the secret key24- Prevents challenge forgery — attackers cannot create valid challenges without the key25- Prevents replay attacks — each challenge is unique and bound to the request context26- Generate with `openssl rand -hex 32`27- Rotate periodically and support key rollover2829```typescript30const mppx = Mppx.create({31 secretKey: process.env.MPP_SECRET_KEY, // 32-byte hex32 methods: [/* ... */],33});34```3536## Pattern: Replay Protection3738Single-use proof semantics prevent double-payment:3940- Each credential can only be used once41- Server must track consumed credentials (at least until expiration)42- Atomic verification — check + consume in a single operation43- Use database transactions or atomic operations for credential tracking44- For high-throughput: use in-memory stores (Redis) with TTL matching challenge expiration4546## Pattern: Transport Security4748MPP mandates TLS 1.2+ (TLS 1.3 recommended):4950- All endpoints must serve over HTTPS (port 443)51- `Cache-Control: no-store` on all responses containing credentials52- Never log plaintext credentials or payment proofs53- Credentials are treated as sensitive bearer tokens5455## Pattern: JSON Canonicalization5657RFC 8785 canonical JSON is required for deterministic encoding:5859- Challenges must use canonical JSON before base64url encoding60- Keeps challenges under 8KB (server-side)61- Clients must handle minimum 4KB challenges62- Use a library for RFC 8785 compliance rather than manual JSON serialization6364## Pattern: Error Handling6566MPP uses RFC 9457 Problem Details for error responses:6768```json69{70 "type": "https://paymentauth.org/problems/payment-required",71 "status": 402,72 "detail": "Payment is required.",73 "challengeId": "..."74}75```7677**Error types**:78- `payment-required` — Normal challenge, no payment attempted yet79- `verification-failed` — Invalid proof of payment80- `payment-expired` — Challenge or credential expired81- `malformed-credential` — Cannot parse the credential8283**Client retry strategy**:84- `payment-required` — Normal flow, fulfill and retry85- `verification-failed` — Do NOT retry with same credential (likely invalid)86- `payment-expired` — Request a fresh challenge87- `malformed-credential` — Fix credential encoding, do not retry blindly8889## Pattern: Receipt Validation9091The `Payment-Receipt` header proves delivery:9293- Contains payment status, method, timestamp, reference ID94- Clients should store receipts for accounting and disputes95- Servers should generate receipts atomically with resource delivery96- Receipts serve as proof in billing reconciliation9798## Pattern: Rate Limiting99100Even with payments, implement rate limiting:101102- Prevents abuse from clients with large wallets103- Protects upstream resources from overload104- Return 429 with `Retry-After` header when exceeded105- Client-side: honor `Retry-After`, add jitter106107## Pattern: Amount Safety108109- All amounts as strings representing the smallest currency unit110- Never use floating-point for monetary calculations111- Validate amounts on both client and server112- Reject negative or zero amounts113- Verify amount matches the challenged amount in the credential114115## Pattern: Secret Management116117- `MPP_SECRET_KEY` — 32-byte hex, rotate periodically118- `STRIPE_SECRET_KEY` — Stripe API key, never in code119- `WALLET_PRIVATE_KEY` — Crypto wallet key, use key management service120- Never commit secrets to version control121- Use `.env` files for development, secrets manager for production122- Implement key rotation without downtime123124## Pattern: Monitoring & Observability125126- Log every payment challenge issued (without sensitive data)127- Track payment success/failure rates per method128- Monitor challenge expiration rates (too many = too short TTL)129- Alert on verification failure spikes (potential attack)130- Track revenue per endpoint for pricing optimization131- Monitor Tempo chain health and Stripe API availability132- Dashboard payment method distribution133134## Pattern: Testing135136- Use Tempo testnet for development (not mainnet)137- Use Stripe test mode keys and test card tokens138- Test the full 402 flow end-to-end139- Test challenge expiration handling140- Test replay rejection141- Test with multiple payment methods simultaneously142- Load test to verify payment verification throughput143144## Pattern: Caching145146- Service discovery responses (`/openapi.json`, `/llms.txt`) — cache aggressively147- Payment challenges — NEVER cache (time-bound, single-use)148- Credentials — NEVER cache (`Cache-Control: no-store`)149- Upstream API responses (for proxies) — cache if idempotent and appropriate150151Fetch the latest MPP specification and IETF draft for current security requirements, encoding rules, and best practices before implementing.