UCP Integration
Verify Universal Commerce Protocol (UCP) webhooks, map orders to verifiable PEAC receipts, and assemble dispute evidence. The current signing model is verified with RFC 9421 HTTP Message Signatures and RFC 9530 Content-Digest, with the signer bound through the UCP-Agent profile.
Package: @peac/mappings-ucp
What It Does
UCP delivers commerce events (such as orders) as signed HTTP webhooks. The mapping verifies the webhook signature, then maps the order into a portable PEAC receipt that can be verified offline and carried across systems.
1. A signed UCP webhook arrives
The platform receives an order webhook with Signature-Input, Signature, Content-Digest, and UCP-Agent headers, plus the raw request body.
2. Verify the signature and body integrity
verifyUcpHttpSignature checks the RFC 9421 signature over the covered components and the RFC 9530 Content-Digest over the raw bytes, and binds the signer to the expected UCP-Agent profile. It performs no network I/O.
3. Map the order to a PEAC receipt
Once verified, mapUcpOrderToReceipt produces PEAC claims for the order; sign turns them into a compact JWS that any verifier can confirm offline.
Install
pnpm add @peac/mappings-ucp @peac/crypto
Verify a UCP webhook (RFC 9421)
verifyUcpHttpSignature is the current, recommended path. Resolve the signer's /.well-known/ucp profile with an SSRF-safe fetch and pass it in; the verifier itself makes no outbound requests.
import { verifyUcpHttpSignature, mapUcpOrderToReceipt } from '@peac/mappings-ucp';
import { sign, generateKeypair } from '@peac/crypto';
const { privateKey } = await generateKeypair();
// Verify the current UCP signing model (RFC 9421 HTTP Message Signature).
// The /.well-known/ucp profile is resolved by the caller (SSRF-safe) and
// passed in; this function performs no network I/O.
const result = await verifyUcpHttpSignature({
signature_input: req.headers['signature-input'],
signature: req.headers['signature'],
method: 'POST',
url: 'https://platform.example.com/webhooks/ucp/orders',
headers: {
'content-type': req.headers['content-type'],
'content-digest': req.headers['content-digest'],
'idempotency-key': req.headers['idempotency-key'],
'ucp-agent': req.headers['ucp-agent'],
},
body_bytes: rawBody,
profile: ucpProfile,
expected_profile_url: 'https://business.example.com/.well-known/ucp', // bind the signer
});
if (result.valid) {
// Map the order to PEAC claims, then sign a portable receipt
const claims = mapUcpOrderToReceipt({
order: body.order,
issuer: 'https://platform.example.com',
subject: 'buyer:123',
currency: 'USD',
});
const receiptJws = await sign(claims, privateKey, 'peac-2026-03');
}What is verified
| Check | What it confirms |
|---|---|
| RFC 9421 signature | The covered request components were signed by the keyid's key (ES256 / ES384 over raw r||s) |
RFC 9530 Content-Digest | The digest matches the raw request body bytes (the body was not altered) |
UCP-Agent binding | The signer's profile URL matches expected_profile_url (https-only, no credentials) |
| Required components | The signature covers the method, URL, and the required headers for the ucp-request policy |
Order receipts and dispute evidence
Beyond verification, the package maps UCP orders into PEAC receipts and assembles portable dispute evidence:
mapUcpOrderToReceiptmaps an order into PEAC commerce claims;extractLineItemSummaryandcalculateOrderStatssummarize line items without storing raw payloadscreateUcpDisputeEvidenceassembles a portable evidence bundle for offline review- Stable
E_UCP_*error codes viaErrorCodesfor verification and mapping failures
Legacy webhook path
verifyUcpWebhookSignature (and parseDetachedJws) verify the legacy Request-Signature detached-JWS model. They are retained and deprecated; new integrations should use verifyUcpHttpSignature. There is no silent fallback between the two paths.
Semantic Boundary
PEAC is the evidence layer. It verifies and records UCP webhook observations and maps orders to portable receipts. It does not place or settle orders, process payments, manage carts or fulfillment, or operate the commerce platform. A UCP receipt proves what the verified webhook attested, not more.
Links
Portable Commerce Evidence
A verified UCP order becomes a portable PEAC receipt that travels across MCP, A2A, ACP, x402, and HTTP. A verifier needs only the issuer's public key to confirm it offline.