Skip to main content
Version: v0.16.3

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 { parsePaymentauthChallenges, parsePaymentauthCredential, parsePaymentauthReceipt } from '@peac/mappings-paymentauth';

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

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

// Parse the upstream receipt from the Payment-Receipt header
const receipt = parsePaymentauthReceipt(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