@peac/mappings-ucp 0.12.5 → 0.12.6

package/README.md

@@ -1,13 +1,6 @@
 # @peac/mappings-ucp
 
-Universal Commerce Protocol (UCP) mapping to PEAC receipts and dispute evidence.
-
-## Features
-
-- **Webhook signature verification** - Detached JWS (RFC 7797) with ES256/ES384/ES512
-- **Raw-first, JCS fallback** - Handles UCP's ambiguous canonicalization spec
-- **UCP order to PEAC receipt mapping** - Amounts in minor units (cents)
-- **Dispute evidence generation** - Hardened YAML schema for @peac/audit bundles
+Universal Commerce Protocol (UCP) order mapping to PEAC signed receipts, webhook signature verification, and dispute evidence generation.
 
 ## Installation
 
@@ -15,163 +8,93 @@ Universal Commerce Protocol (UCP) mapping to PEAC receipts and dispute evidence.
 pnpm add @peac/mappings-ucp
 ```
 
-## Usage
-
-### Verify Webhook Signature
-
-```typescript
-import { verifyUcpWebhookSignature } from '@peac/mappings-ucp';
+## What It Does
 
-const result = await verifyUcpWebhookSignature({
-  signature_header: req.headers['request-signature'],
-  body_bytes: rawBody, // Uint8Array
-  profile_url: 'https://business.example.com/.well-known/ucp',
-});
+`@peac/mappings-ucp` maps UCP order data to PEAC receipt claims, verifies UCP webhook signatures using detached JWS (RFC 7797), and generates structured dispute evidence bundles. Order state is kept distinct from payment state: the `payment_state_source` field marks whether payment status was explicitly provided or derived from order fulfillment, so downstream consumers can distinguish observed payment evidence from inferred status.
 
-if (result.valid) {
-  console.log(`Verified using ${result.mode_used} mode`);
-  console.log(`Key: ${result.key?.kid}`);
-} else {
-  console.error(`Verification failed: ${result.error_code}`);
-  console.log('Attempts:', result.attempts);
-}
-```
+## How Do I Use It?
 
-### Map UCP Order to PEAC Receipt
+### Map a UCP order to receipt claims
 
 ```typescript
 import { mapUcpOrderToReceipt } from '@peac/mappings-ucp';
-import { issue } from '@peac/protocol';
 
 const claims = mapUcpOrderToReceipt({
-  order: webhookBody.order,
-  issuer: 'https://platform.example.com',
-  subject: 'buyer:123',
+  order: ucpOrder,
+  issuer: 'https://merchant.example.com',
+  subject: 'agent:shopper-bot-123',
   currency: 'USD',
 });
 
 // Sign with @peac/protocol
-const { jws } = await issue({
-  iss: 'https://platform.example.com',
-  kind: 'evidence',
-  type: 'org.peacprotocol/payment',
-  pillars: ['commerce'],
-  extensions: {
-    'org.peacprotocol/commerce': {
-      payment_rail: 'ucp',
-      amount_minor: String(claims.amount),
-      currency: claims.currency,
-      reference: claims.reference,
-    },
-  },
-  privateKey,
-  kid,
-});
+const receipt = await issue(claims, privateKey, kid);
 ```
 
-### Create Dispute Evidence
+### Verify a UCP webhook signature
 
 ```typescript
-import { createUcpDisputeEvidence } from '@peac/mappings-ucp';
-import { createDisputeBundle } from '@peac/audit';
+import { verifyUcpWebhookSignature } from '@peac/mappings-ucp';
 
-// Create evidence from webhook
-const evidence = await createUcpDisputeEvidence({
+const result = await verifyUcpWebhookSignature({
   signature_header: req.headers['request-signature'],
   body_bytes: rawBody,
-  method: 'POST',
-  path: '/webhooks/ucp/orders',
-  received_at: new Date().toISOString(),
   profile_url: 'https://business.example.com/.well-known/ucp',
-  profile_fetched_at: new Date().toISOString(),
 });
 
-// Create dispute bundle with evidence
-const bundle = await createDisputeBundle({
-  dispute_ref: 'dispute_123',
-  created_by: 'platform:example.com',
-  receipts: [receiptJws],
-  keys: jwks,
-  policy: evidence.evidence_yaml, // UCP evidence stored here
-});
+if (result.valid) {
+  // Signature verified; proceed with order mapping
+}
+```
+
+### Extract line item summaries and order statistics
+
+```typescript
+import { extractLineItemSummary, calculateOrderStats } from '@peac/mappings-ucp';
+
+const summary = extractLineItemSummary(ucpOrder);
+const stats = calculateOrderStats(ucpOrder);
+
+console.log(stats.total_items); // number of line items
+console.log(stats.fulfilled_items); // items marked fulfilled
 ```
 
-## Verification Strategy
-
-UCP's webhook spec says "detached JWT over the request body" but doesn't specify canonicalization (unlike AP2 which requires JCS). This package uses:
-
-1. **Try raw body bytes first** - Most likely what implementers expect
-2. **Fallback to JCS-canonicalized body** - If raw fails and body is valid JSON
-3. **Record all attempts** - For debugging and dispute evidence
-
-Both b64=true (standard) and b64=false (RFC 7797 unencoded payload) are supported.
-
-## Security and Correctness Notes
-
-This verifier implements strict JOSE semantics for audit-grade correctness:
-
-- **RFC 7797 b64=false**: Unencoded payloads are passed as raw bytes to the verification library (not ASCII-decoded strings). This ensures binary payloads and UTF-8 content verify correctly.
-- **JOSE crit semantics**: If the `crit` header is present, ALL entries must be understood by this implementation. Unknown critical parameters cause immediate rejection with a clear error.
-- **Strict header typing**: `crit` must be an array of strings (no objects, numbers, or duplicates). `b64` must be a boolean (not string `"false"` or number `0`).
-- **Single profile fetch**: The verifier returns both the parsed profile and raw JSON, eliminating race conditions and enabling deterministic evidence hashing.
-- **Deterministic evidence**: YAML output uses UTF-8 encoding, LF line endings, and exactly one trailing newline for byte-stable hashing across platforms.
-- **JWS signature format**: Demo/test code uses IEEE P1363 ECDSA signatures (raw R||S) as required by JWS, not DER encoding.
-
-The verification result includes `profile` and `profile_raw` fields, allowing callers to capture evidence without re-fetching.
-
-## Evidence Schema
-
-The evidence YAML uses a hardened schema that cannot be misinterpreted as executable policy:
-
-```yaml
-peac_bundle_metadata_version: 'org.peacprotocol.ucp/0.1'
-kind: 'evidence_attachment'
-scope: 'ucp_webhook'
-
-request:
-  method: 'POST'
-  path: '/webhooks/ucp/orders'
-  received_at: '2026-01-13T12:00:00Z'
-
-payload:
-  raw_sha256_hex: 'abc123...'
-  raw_bytes_b64url: 'eyJ...' # Optional, for bodies <= 256KB
-  jcs_sha256_hex: 'def456...' # If JSON parseable
-  json_parseable: true
-
-signature:
-  header_value: 'eyJhbGc...' # Full Request-Signature header
-  kid: 'business-key-001'
-  alg: 'ES256'
-  b64: null
-  verified: true
-  verification_mode_used: 'raw'
-  verification_attempts:
-    - mode: 'raw'
-      success: true
-
-profile:
-  url: 'https://business.example.com/.well-known/ucp'
-  fetched_at: '2026-01-13T11:59:30Z'
-  profile_jcs_sha256_hex: 'ghi789...'
-  key_jwk:
-    kty: 'EC'
-    crv: 'P-256'
-    kid: 'business-key-001'
-    x: '...'
-    y: '...'
+### Attach and extract evidence carriers on webhook payloads
+
+```typescript
+import {
+  UcpCarrierAdapter,
+  attachCarrierToWebhookPayload,
+  extractCarrierFromWebhookPayload,
+} from '@peac/mappings-ucp';
+
+// Attach a signed receipt carrier to a UCP webhook payload
+attachCarrierToWebhookPayload(webhookPayload, carrier);
+
+// Extract carrier from an incoming webhook payload
+const result = extractCarrierFromWebhookPayload(webhookPayload);
+if (result) {
+  console.log(result.receipts[0].receipt_ref);
+}
+
+// Or use the adapter interface
+const adapter = new UcpCarrierAdapter();
+const extracted = adapter.extract(webhookPayload);
 ```
 
-## Error Codes
+## Integrates With
+
+- `@peac/kernel` (Layer 0): Evidence carrier types and constants
+- `@peac/schema` (Layer 1): Receipt schemas and carrier validation
+- `@peac/protocol` (Layer 3): Sign mapped claims into receipts with `issue()`
+
+## For Agent Developers
+
+If you are building an AI agent that interacts with UCP-based commerce platforms:
 
-| Code                                  | HTTP | Description                      |
-| ------------------------------------- | ---- | -------------------------------- |
-| E_UCP_SIGNATURE_MISSING               | 400  | Request-Signature header missing |
-| E_UCP_SIGNATURE_MALFORMED             | 400  | Invalid detached JWS format      |
-| E_UCP_SIGNATURE_ALGORITHM_UNSUPPORTED | 400  | Algorithm not ES256/ES384/ES512  |
-| E_UCP_KEY_NOT_FOUND                   | 401  | Key ID not in profile            |
-| E_UCP_SIGNATURE_INVALID               | 401  | Signature verification failed    |
-| E_UCP_PROFILE_FETCH_FAILED            | 502  | Failed to fetch UCP profile      |
+- Use `mapUcpOrderToReceipt()` to produce signed evidence of order observations
+- Use `verifyUcpWebhookSignature()` to validate incoming webhook authenticity before mapping
+- Order status reflects fulfillment state; payment status requires explicit `payment_state` when the upstream source provides it
+- See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise protocol overview
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peac/mappings-ucp",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "Google Universal Commerce Protocol (UCP) mapping to PEAC receipts and dispute evidence",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,19 +15,23 @@
     "dist"
   ],
   "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
     "ucp",
-    "google",
-    "commerce",
-    "webhooks",
-    "ap2",
-    "peac"
+    "universal-commerce",
+    "order-management",
+    "payment-evidence"
   ],
   "author": "PEAC Protocol Contributors",
   "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/peacprotocol/peac/issues"
   },
-  "homepage": "https://www.peacprotocol.org",
+  "homepage": "https://github.com/peacprotocol/peac#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peacprotocol/peac.git",
@@ -38,8 +42,8 @@
   },
   "dependencies": {
     "jose": "^5.2.0",
-    "@peac/kernel": "0.12.5",
-    "@peac/schema": "0.12.5"
+    "@peac/kernel": "0.12.6",
+    "@peac/schema": "0.12.6"
   },
   "devDependencies": {
     "typescript": "^5.3.0",