Skip to content
Skills Library
Programming · Learning & explanation

mpp-dev-patterns

/mpp-dev-patterns

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.

Licence
MIT
Last repository change
14.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 14.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author description

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.

How it works

  1. Before writing code
  2. Pattern: HMAC Challenge Binding
  3. Pattern: Replay Protection
  4. Pattern: Transport Security
  5. Pattern: JSON Canonicalization
  6. Pattern: Error Handling
  7. Pattern: Receipt Validation
  8. Pattern: Rate Limiting
  9. Pattern: Amount Safety
  10. Pattern: Secret Management
Original SKILL.md headings · 145 lines, 735 words
SKILL.md preview
---
name: mpp-dev-patterns
description: 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.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# 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

```typescript
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:

```json
{
  "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.

Versions

The database has no other skills named mpp-dev-patterns.

Database snapshot: 13.11.2026 · package version e95b5c3a63bb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100acp-dev-patterns
    Cross-cutting ACP development patterns — idempotency, error handling, 3D Secure flows, request signing, rate limiting, monitoring, and security best practices. Use when designing architecture or solving production concerns.
  • 90mpp-conformance
    Validate MPP implementations against the specification — verify HTTP 402 challenge-response compliance, header formats, payment method correctness, service discovery, and production readiness. Use when auditing an MPP integration or preparing for production launch.
  • 100arc42-chapter-08-cross-cutting-concepts
    Best practices for arc42 Chapter 8 "Cross-cutting Concepts". Use when documenting cross-cutting architecture concepts, identifying reusable patterns, describing domain models, security concepts, error handling strategies, or explaining HOW the architecture works across multiple…
  • 100mpp
    Build with MPP (Machine Payments Protocol), open machine-to-machine payments over HTTP 402. Use for paid APIs, payment-gated endpoints, agent payment flows, MCP tool payments, or metered billing. Covers mppx (TS), pympp, and mpp Rust SDKs.
  • 98error-handling-patterns
    Design error handling strategies for TypeScript and Python applications — exception hierarchies, Result/Either types, retry patterns, error boundaries, and structured error logging. Use when designing error handling architecture, choosing between exceptions and Result types,…
  • 95lightning-amp-mpp
    Multi-Path Payments (MPP) — split a payment across multiple parallel routes; same payment hash, payment_secret binds parts. AMP (Atomic Multipath) — variant where each part has different hash; receiver derives shared secret. USE WHEN: implementing payment splitting, debugging…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.