Mpp Conformance

---
name: mpp-conformance
description: 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.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
disable-model-invocation: true
---

# MPP Conformance & Production Readiness

## Before writing code

**Fetch live docs**:
1. Fetch `https://paymentauth.org/` for the canonical specification requirements
2. Fetch `https://datatracker.ietf.org/doc/draft-ryan-httpauth-payment/` for the IETF draft compliance requirements
3. Web-search `site:docs.stripe.com payments machine mpp production` for Stripe production readiness
4. Web-search `site:paymentauth.org draft-payment-discovery` for service discovery compliance

## Protocol Compliance Checklist

### HTTP 402 Response

- [ ] Returns `402 Payment Required` status code for unpaid requests
- [ ] Includes `WWW-Authenticate: Payment <base64url-challenge>` header
- [ ] Challenge contains required fields: `id`, `realm`, `method`, `intent`, `request`
- [ ] Challenge JSON is RFC 8785 canonicalized before base64url encoding
- [ ] Challenge size under 8KB
- [ ] Error body follows RFC 9457 Problem Details format

### Authorization Header

- [ ] Accepts `Authorization: Payment <base64url-credential>` header
- [ ] Parses credential correctly (base64url decode → JSON)
- [ ] Validates payment proof against the payment method
- [ ] Returns appropriate error for invalid credentials

### Payment-Receipt Header

- [ ] Returns `Payment-Receipt: <base64url-receipt>` on successful payment
- [ ] Receipt contains: status, method, timestamp, reference
- [ ] Receipt is delivered atomically with the resource

### Challenge Binding

- [ ] Uses 32-byte secret key for HMAC challenge binding
- [ ] Challenge IDs are unique and non-guessable
- [ ] Challenges have expiration timestamps
- [ ] Expired challenges are rejected
- [ ] Each challenge can only be consumed once (replay protection)

### Transport Security

- [ ] TLS 1.2+ on all endpoints (TLS 1.3 recommended)
- [ ] HTTPS only (port 443)
- [ ] `Cache-Control: no-store` on responses with credentials
- [ ] No plaintext credential logging

### Payment Methods

- [ ] At least one payment method configured
- [ ] Tempo: correct chain ID (4217), valid USDC contract address, valid recipient
- [ ] Stripe: valid API key, correct SPT handling
- [ ] Payment verification is atomic (no partial states)

### Service Discovery

- [ ] `GET /openapi.json` returns valid OpenAPI 3.x document
- [ ] `x-service-info` extension present with categories and docs
- [ ] `x-payment-info` extension on each payable operation
- [ ] All payable operations declare `402` response
- [ ] OpenAPI document under 64 KB
- [ ] `Cache-Control: max-age=300` on discovery endpoints
- [ ] `llms.txt` available with service description

### Error Handling

- [ ] `payment-required` for initial challenges
- [ ] `verification-failed` for invalid proofs
- [ ] `payment-expired` for expired challenges/credentials
- [ ] `malformed-credential` for unparseable credentials
- [ ] All errors include RFC 9457 `type` URLs

## Production Readiness Checklist

### Security

- [ ] Secret key stored in environment variable or secrets manager
- [ ] No hardcoded Stripe keys, wallet keys, or SPT tokens
- [ ] Key rotation strategy documented
- [ ] Rate limiting implemented
- [ ] DDoS protection (Cloudflare, AWS Shield, etc.)

### Monitoring

- [ ] Payment success/failure metrics collected
- [ ] Challenge issuance rate tracked
- [ ] Revenue per endpoint dashboarded
- [ ] Alert on verification failure spikes
- [ ] Tempo chain health monitored (if using Tempo)
- [ ] Stripe API availability monitored (if using Stripe)

### Reliability

- [ ] Health check endpoint (outside payment gate)
- [ ] Graceful degradation if payment provider is down
- [ ] Credential store (Redis/DB) for replay protection has failover
- [ ] Load tested with expected traffic volume

### Operations

- [ ] Deployment does not interrupt active payment sessions
- [ ] Secret key rotation does not invalidate in-flight challenges
- [ ] Refund process documented and tested
- [ ] Billing reconciliation process defined

Fetch the latest specification and IETF draft for any newly added compliance requirements before running conformance checks.