@peac/mappings-paymentauth 0.12.5 → 0.12.7

package/README.md

@@ -1,31 +1,113 @@
 # @peac/mappings-paymentauth
 
-HTTP Payment authentication scheme (paymentauth/MPP) mapping for PEAC.
+HTTP Payment authentication scheme mapping for PEAC: envelope-first parsing of paymentauth challenges, credentials, and receipts into normalized types and PEAC evidence.
 
-Envelope-first parsing of paymentauth wire artifacts with raw + normalized types. Method-specific payloads are treated as `unknown` because each payment method (card, lightning, stripe, tempo) has its own specification.
+## Installation
 
-## Status
+```bash
+pnpm add @peac/mappings-paymentauth
+```
 
-Experimental. The paymentauth core spec (`draft-ryan-httpauth-payment-01`) is an active individual draft (not standards-track). Discovery and JSON-RPC/MCP transport drafts are at draft-00.
+## What It Does
 
-## Features
+`@peac/mappings-paymentauth` parses and normalizes HTTP Payment authentication scheme headers (aligned with `draft-ryan-httpauth-payment-01`) into structured types, then maps them to PEAC evidence in the Interaction Record format. It handles `WWW-Authenticate`, `Authorization`, and `Payment-Receipt` headers with envelope-first parsing: method-specific payloads are treated as `unknown` and preserved as raw bytes alongside normalized fields. No network I/O.
 
-- Parse `WWW-Authenticate: Payment` challenges (first challenge; separate header lines recommended for multiple challenges)
-- Parse `Authorization: Payment` credentials (base64url-encoded JSON)
-- Parse `Payment-Receipt` headers (base64url-encoded JSON)
-- Normalize to stable PEAC-facing types with `_raw` back-references
-- OpenAPI discovery extraction (`x-service-info`, `x-payment-info`)
-- JSON-RPC error detection (`-32042`, `-32043`)
-- MCP `_meta` key extraction (`org.paymentauth/credential`, `org.paymentauth/receipt`)
-- MCP capability advertisement typing (`experimental.payment`)
+## How Do I Use It?
 
-## Security
+### Parse and normalize a payment challenge
 
-- Raw `Authorization: Payment` and `Payment-Receipt` values never appear in thrown errors
-- Parser limits enforced: header size, param count, payload size, JSON depth
-- Decoded bytes preserved alongside strings for non-UTF-8 safety
-- `redactPaymentauthHeader()` helper for safe logging
+```typescript
+import { parsePaymentauthChallenges, normalizeChallenge } from '@peac/mappings-paymentauth';
 
-## No Network I/O
+const rawChallenges = parsePaymentauthChallenges(
+  'Payment method="stripe", realm="api", request="eyJ..."'
+);
 
-This package contains zero network calls. All functions are pure parsers and normalizers.
+const normalized = normalizeChallenge(rawChallenges[0]);
+console.log(normalized.method); // 'stripe'
+console.log(normalized.realm); // 'api'
+console.log(normalized.intent); // decoded from request parameter
+```
+
+### Map a paymentauth receipt to PEAC evidence
+
+```typescript
+import {
+  parsePaymentauthReceipt,
+  normalizeReceipt,
+  fromPaymentauthReceipt,
+  toCommerceExtensionFields,
+} from '@peac/mappings-paymentauth';
+
+const raw = parsePaymentauthReceipt(headerValue);
+const receipt = normalizeReceipt(raw);
+
+// Map to PEAC PaymentEvidence
+const evidence = fromPaymentauthReceipt(receipt);
+console.log(evidence.rail); // 'paymentauth'
+console.log(evidence.reference); // upstream reference
+
+// Extract commerce extension fields (partial, only from upstream data)
+const commerce = toCommerceExtensionFields(receipt);
+```
+
+### Extract evidence from HTTP response headers
+
+```typescript
+import {
+  extractCarrierFromPaymentauthHeaders,
+  PaymentauthCarrierAdapter,
+} from '@peac/mappings-paymentauth';
+
+// Direct extraction
+const result = extractCarrierFromPaymentauthHeaders(responseHeaders);
+if (result) {
+  console.log(result.receiptJws);
+  console.log(result.receiptRef);
+}
+
+// Or use the CarrierAdapter for transport-agnostic integration
+const adapter = new PaymentauthCarrierAdapter();
+```
+
+### JSON-RPC and MCP transport helpers
+
+```typescript
+import {
+  isPaymentRequiredError,
+  parsePaymentauthFromJsonRpcError,
+  extractCredentialFromMcpMeta,
+  extractReceiptFromMcpMeta,
+} from '@peac/mappings-paymentauth';
+
+// Check if a JSON-RPC error is a payment-required response
+if (isPaymentRequiredError(error)) {
+  const challenges = parsePaymentauthFromJsonRpcError(error);
+  // present payment challenge to user/agent
+}
+
+// Extract paymentauth artifacts from MCP tool _meta
+const credential = extractCredentialFromMcpMeta(meta);
+const receipt = extractReceiptFromMcpMeta(meta);
+```
+
+## Integrates With
+
+- `@peac/kernel` (Layer 0): Core types and constants
+- `@peac/schema` (Layer 1): Zod validators and commerce extension schemas
+- `@peac/protocol` (Layer 3): Receipt issuance using mapped evidence
+- `@peac/mcp-server` (Layer 5): MCP tool server with payment-required flow
+
+## For Agent Developers
+
+If you are building an AI agent that interacts with paymentauth-enabled services: use `parsePaymentauthChallenges` to decode `WWW-Authenticate: Payment` headers, `fromPaymentauthReceipt` to produce PEAC evidence from upstream receipts, and `PaymentauthCarrierAdapter` to carry evidence across HTTP boundaries. The JSON-RPC and MCP helpers handle transport-specific encoding for agent-to-agent and MCP tool call flows. All parsing is offline with no network I/O.
+
+## License
+
+Apache-2.0
+
+---
+
+PEAC Protocol is an open source project stewarded by Originary and community contributors.
+
+[Docs](https://www.peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac) | [Originary](https://www.originary.xyz)

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@peac/mappings-paymentauth",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "description": "HTTP Payment authentication scheme (paymentauth/MPP) mapping for PEAC",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/peacprotocol/peac.git",
+    "url": "git+https://github.com/peacprotocol/peac.git",
     "directory": "packages/mappings/paymentauth"
   },
-  "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
+  "author": "PEAC Protocol Contributors",
   "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/peacprotocol/peac/issues"
@@ -23,14 +23,27 @@
     "access": "public"
   },
   "dependencies": {
-    "@peac/kernel": "0.12.5",
-    "@peac/schema": "0.12.5"
+    "@peac/schema": "0.12.7",
+    "@peac/kernel": "0.12.7"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
     "typescript": "^5.3.3",
     "vitest": "^4.0.0"
   },
+  "keywords": [
+    "peac",
+    "peacprotocol",
+    "interaction-records",
+    "signed-records",
+    "receipts",
+    "originary",
+    "paymentauth",
+    "http-payment",
+    "authentication",
+    "internet-draft",
+    "402-payment"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "vitest run",