Skip to main content
Version: v0.12.4

Paymentauth Integration Kit

Integrate HTTP Payment authentication scheme (draft-ryan-httpauth-payment) evidence with PEAC using @peac/mappings-paymentauth.

Overview​

The paymentauth mapping provides envelope-first parsing for the Payment HTTP authentication scheme. It extracts Challenge, Credential, and Receipt envelopes while preserving raw upstream artifacts and coexisting with the PEAC-Receipt header.

Install​

Terminal
pnpm add @peac/mappings-paymentauth @peac/protocol @peac/crypto

Parse HTTP Payment headers​

parse-headers.ts
import { parseChallenge, parseCredential, parseReceipt } from '@peac/mappings-paymentauth';

// Parse 402 challenge from WWW-Authenticate header
const challenge = parseChallenge(response.headers['www-authenticate']);

// Parse client credential from Authorization header
const credential = parseCredential(request.headers['authorization']);

// Parse upstream receipt from Payment-Receipt header
const receipt = parseReceipt(response.headers['payment-receipt']);

Carrier coexistence​

HTTP responses may carry both headers simultaneously:

  • PEAC-Receipt: signed PEAC interaction record (compact JWS)
  • Payment-Receipt: upstream payment receipt (raw, preserved as-is)

The carrier adapter reads both without conflict. The receipt_ref is computed as sha256(raw_header_value).

JSON-RPC and MCP helpers​

For JSON-RPC transports (including MCP), the package provides error helpers:

jsonrpc-errors.ts
import { paymentRequiredError, paymentFailedError } from '@peac/mappings-paymentauth/jsonrpc';

// -32042: Payment required
const challengeError = paymentRequiredError(challenge);

// -32043: Payment failed
const failedError = paymentFailedError(reason);

MCP-specific extraction functions are available for reading paymentauth artifacts from tool response metadata.

Boundary rules​

  • Preserve raw upstream artifacts; do not synthesize payment finality
  • A paymentauth receipt proves what the upstream server attested, not more
  • Method payloads are treated as unknown (version-agnostic)
  • No network I/O, no implicit fetches
  • Case-insensitive scheme matching per RFC 9110