{"_id":"@algovoi/pef","_rev":"3-f366e68c8933d32aa5b02ede9e8fb562","name":"@algovoi/pef","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@algovoi/pef","version":"0.1.0","keywords":["x402","payment","receipt","jcs","pef","canonicalization","trust","evidence"],"license":"Apache-2.0","_id":"@algovoi/pef@0.1.0","maintainers":[{"name":"algovoi","email":"chopmob@gmail.com"}],"homepage":"https://github.com/chopmob-cloud/algovoi-pef#readme","bugs":{"url":"https://github.com/chopmob-cloud/algovoi-pef/issues"},"dist":{"shasum":"9e245f450ee1e5fb3971f4fa81c7ccad45d3c9cc","tarball":"https://registry.npmjs.org/@algovoi/pef/-/pef-0.1.0.tgz","fileCount":10,"integrity":"sha512-udyg+y8tRD3LkkFYJ+vrtfqzoQb8t+OiOZmquT1DheuF6G6fvzD3PWt/89D2qOvgYDZTscjXB+q504QbQ4xSTw==","signatures":[{"sig":"MEQCIHqpjuvZWH6omofkcdNy+P0P8FmEFFCYwRldChsiSmAuAiBb1Ai7iI4TSYIpJ3A3gJUJikyzzMCePpVqTbLW03le3Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32827},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"d750abd08f3079edd5e021c4b1ab730167bf60a9","scripts":{"test":"node --test dist/index.test.js","build":"tsc"},"_npmUser":{"name":"algovoi","email":"chopmob@gmail.com"},"repository":{"url":"git+https://github.com/chopmob-cloud/algovoi-pef.git","type":"git"},"_npmVersion":"11.6.2","description":"Payment Evidence Frame (PEF) v1 -- AlgoVoi canonical wrapper for payment-lifecycle receipts","directories":{},"_nodeVersion":"24.12.0","dependencies":{"canonicalize":"^1.0.8"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^20.19.41"},"_npmOperationalInternal":{"tmp":"tmp/pef_0.1.0_1780127347226_0.5603378300239183","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@algovoi/pef","version":"0.1.1","keywords":["x402","payment","receipt","jcs","pef","canonicalization","trust","evidence"],"license":"Apache-2.0","_id":"@algovoi/pef@0.1.1","maintainers":[{"name":"algovoi","email":"chopmob@gmail.com"}],"homepage":"https://github.com/chopmob-cloud/algovoi-pef#readme","bugs":{"url":"https://github.com/chopmob-cloud/algovoi-pef/issues"},"dist":{"shasum":"296e3ad033bde78a5d15627b12d6ca730c6540bb","tarball":"https://registry.npmjs.org/@algovoi/pef/-/pef-0.1.1.tgz","fileCount":11,"integrity":"sha512-Tlp2rwK9xDUZAcUB0lwcpm93uRBQqdJ+0Bt6bZKLT/RyeNw2MGALF/3ISXyj0H+zK78I4IqHZOmH72L9bsgEEw==","signatures":[{"sig":"MEYCIQDKvWis4zApLzIf4zf5inH6cSUrGSzxhr1Nf2TcgvQuzgIhAOmRWa+HCWb3KYp3ATmYyZz3bR/QCqFZBeYD1iU5Du+o","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73457},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"af28c3dc87335df4aea7a6a6000a2240515bee0e","scripts":{"test":"node --test dist/index.test.js","build":"tsc"},"_npmUser":{"name":"algovoi","email":"chopmob@gmail.com"},"repository":{"url":"git+https://github.com/chopmob-cloud/algovoi-pef.git","type":"git"},"_npmVersion":"11.6.2","description":"Payment Evidence Frame (PEF) v1 -- AlgoVoi canonical wrapper for payment-lifecycle receipts","directories":{},"_nodeVersion":"24.12.0","dependencies":{"canonicalize":"^1.0.8"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^20.19.41"},"_npmOperationalInternal":{"tmp":"tmp/pef_0.1.1_1782161973526_0.8434122114028353","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@algovoi/pef","version":"0.1.2","description":"Payment Evidence Frame (PEF) v1 -- AlgoVoi canonical wrapper for payment-lifecycle receipts","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","test":"node --test dist/index.test.js"},"keywords":["x402","payment","receipt","jcs","pef","canonicalization","trust","evidence"],"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/chopmob-cloud/algovoi-pef.git"},"dependencies":{"canonicalize":"^1.0.8"},"devDependencies":{"@types/node":"^20.19.41","typescript":"^5.9.3"},"gitHead":"dd631efdf7cceefed82b83a4fbcc16761561ce73","_id":"@algovoi/pef@0.1.2","bugs":{"url":"https://github.com/chopmob-cloud/algovoi-pef/issues"},"homepage":"https://github.com/chopmob-cloud/algovoi-pef#readme","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-9EBs6ZY6UM9neUteCXxgFKdbM/35mfHD3atBSJBAH+jEdgOa2w8kMifgYX7hPyc/Dwd/0JVAL4r3DvK4T/vg1A==","shasum":"a06d3d27c098a26f0c756257f19b80d679bc5a35","tarball":"https://registry.npmjs.org/@algovoi/pef/-/pef-0.1.2.tgz","fileCount":10,"unpackedSize":43908,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDmPg6QVFYNzJA3+9NtaSLuAxn1JnfSqgjjeN76EsZ4aQIhAL2loWUfFW0T3gpqPHUxsi51OHcjNL/eAGLhKbL8jcpQ"}]},"_npmUser":{"name":"algovoi","email":"chopmob@gmail.com"},"directories":{},"maintainers":[{"name":"algovoi","email":"chopmob@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pef_0.1.2_1782163559075_0.39779554929517835"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-30T07:49:07.047Z","modified":"2026-06-22T21:25:59.324Z","0.1.0":"2026-05-30T07:49:07.424Z","0.1.1":"2026-06-22T20:59:33.680Z","0.1.2":"2026-06-22T21:25:59.223Z"},"bugs":{"url":"https://github.com/chopmob-cloud/algovoi-pef/issues"},"license":"Apache-2.0","homepage":"https://github.com/chopmob-cloud/algovoi-pef#readme","keywords":["x402","payment","receipt","jcs","pef","canonicalization","trust","evidence"],"repository":{"type":"git","url":"git+https://github.com/chopmob-cloud/algovoi-pef.git"},"description":"Payment Evidence Frame (PEF) v1 -- AlgoVoi canonical wrapper for payment-lifecycle receipts","maintainers":[{"name":"algovoi","email":"chopmob@gmail.com"}],"readme":"> **AlgoVoi is available for acquisition** -- [docs.algovoi.co.uk/acquisition](https://docs.algovoi.co.uk/acquisition)\r\n\r\n---\r\n\r\n# algovoi-pef\r\n\r\n[![PyPI](https://img.shields.io/pypi/v/algovoi-pef)](https://pypi.org/project/algovoi-pef/)\r\n[![npm](https://img.shields.io/npm/v/@algovoi/pef)](https://www.npmjs.com/package/@algovoi/pef)\r\n[![Cross-validated](https://img.shields.io/badge/cross--validated-64%2F64-brightgreen)](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/blob/main/_attestations/2026-05-30-8-impl-pef-v1.md)\r\n[![Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-green)](./LICENSE)\r\n\r\n**Payment Evidence Frame (PEF) v1** -- a canonical wrapper format for\r\nAlgoVoi payment-lifecycle receipts. Each frame carries a byte-deterministic\r\n`frame_id` (SHA-256 of the JCS-canonical preimage) and an optional detached\r\nRFC 9421 signature field.\r\n\r\nNormative spec: [`draft-hopley-x402-payment-evidence-frame-00`](https://datatracker.ietf.org/doc/draft-hopley-x402-payment-evidence-frame/) (IETF I-D, published 2026-05-30).  \r\nCanonicalisation pin: `urn:x402:canonicalisation:jcs-rfc8785-v1`.\r\n\r\n## Install\r\n\r\n```bash\r\npip install algovoi-pef          # Python\r\nnpm install @algovoi/pef         # TypeScript / JavaScript\r\n```\r\n\r\n## Quick start\r\n\r\n```python\r\nfrom algovoi_pef import build_pef, verify_pef\r\n\r\n# Wrap a compliance receipt in a PEF frame\r\nframe = build_pef(\r\n    claim_type=\"payment_admission\",\r\n    receipt={\r\n        \"canon_version\": \"urn:x402:canonicalisation:jcs-rfc8785-v1\",\r\n        \"jurisdiction_flags\": [\"EU\", \"UK\"],\r\n        \"payer_ref\": \"sha256:abc123...\",\r\n        \"prev_hash\": None,\r\n        \"screen_provider_did\": \"did:web:api.algovoi.co.uk\",\r\n        \"screen_result\": \"ALLOW\",\r\n        \"screen_timestamp_ms\": 1748534600000,\r\n    },\r\n    frame_provider_did=\"did:web:api.algovoi.co.uk\",\r\n    frame_timestamp_ms=1748534600000,\r\n)\r\n\r\nresult = verify_pef(frame)\r\nassert result[\"valid\"]\r\nprint(frame[\"frame_id\"])\r\n# sha256:09929082c83d5006f61f06bb12eb58cc2c21acebd70a31bca3cb26169c11b6bf\r\n```\r\n\r\n```typescript\r\nimport { buildPef, verifyPef } from \"@algovoi/pef\";\r\n\r\nconst frame = buildPef({\r\n  claim_type: \"payment_settlement\",\r\n  receipt: {\r\n    canon_version: \"urn:x402:canonicalisation:jcs-rfc8785-v1\",\r\n    settled_payment_ref: \"sha256:abc123...\",\r\n    settlement_chain: \"ethereum:84532\",\r\n    settlement_provider_did: \"did:web:api.algovoi.co.uk\",\r\n    settlement_result: \"SETTLED\",\r\n    settlement_timestamp_ms: 1748534700000,\r\n  },\r\n  frame_provider_did: \"did:web:api.algovoi.co.uk\",\r\n  frame_timestamp_ms: 1748534700000,\r\n});\r\n\r\nconst result = verifyPef(frame);\r\nconsole.log(result.valid);   // true\r\nconsole.log(frame.frame_id); // sha256:...\r\n```\r\n\r\n## Claim types\r\n\r\nPEF defines five claim types, each mapping to an IETF I-D-anchored receipt format:\r\n\r\n| `claim_type` | `receipt_format` | IETF I-D | Platform source |\r\n|---|---|---|---|\r\n| `payment_admission` | `compliance-receipt-v1` | `draft-hopley-x402-compliance-receipt` | `/compliance/screen` |\r\n| `payment_settlement` | `settlement-attestation-v1` | `draft-hopley-x402-settlement-attestation` | `/checkout/{t}/verify` |\r\n| `payment_cancellation` | `cancellation-receipt-v1` | `draft-hopley-x402-cancellation-receipt` | mandate cancel endpoints |\r\n| `payment_refund` | `refund-receipt-v1` | `draft-hopley-x402-refund-receipt` | refund endpoints |\r\n| `composite_verdict` | `composite-trust-query-v1` | `draft-hopley-x402-composite-trust-query` | `/compliance/trust-query` |\r\n\r\n## Frame structure\r\n\r\n```json\r\n{\r\n  \"canon_version\":      \"urn:x402:canonicalisation:jcs-rfc8785-v1\",\r\n  \"claim_type\":         \"payment_admission\",\r\n  \"frame_id\":           \"sha256:<64-hex-chars>\",\r\n  \"frame_provider_did\": \"did:web:api.algovoi.co.uk\",\r\n  \"frame_timestamp_ms\": 1748534600000,\r\n  \"pef_version\":        \"1\",\r\n  \"receipt\":            { \"...\" : \"...\" },\r\n  \"receipt_format\":     \"compliance-receipt-v1\",\r\n  \"receipt_hash\":       \"sha256:<64-hex-chars>\",\r\n  \"signature\":          \"<RFC 9421 detached JWS -- optional>\"\r\n}\r\n```\r\n\r\n### frame_id derivation\r\n\r\n```\r\nreceipt_hash = \"sha256:\" + hex(sha256(JCS(receipt)))\r\n\r\npreimage = {\r\n  canon_version, claim_type, frame_provider_did,\r\n  frame_timestamp_ms, pef_version, receipt,\r\n  receipt_format, receipt_hash\r\n}\r\n\r\nframe_id = \"sha256:\" + hex(sha256(JCS(preimage)))\r\n```\r\n\r\n`signature` is appended after `frame_id` is set and is excluded from both\r\nhash inputs. Signing the `frame_id` (rather than the full frame body) keeps\r\nthe signature stable across re-serialisations.\r\n\r\n## API\r\n\r\n### Python\r\n\r\n```python\r\nfrom algovoi_pef import build_pef, verify_pef, pef_frame_id, CLAIM_TYPES\r\n\r\n# Build a frame\r\nframe = build_pef(\r\n    claim_type=\"payment_admission\",   # str -- must be in CLAIM_TYPES\r\n    receipt={...},                    # dict\r\n    frame_provider_did=\"did:...\",     # str\r\n    frame_timestamp_ms=1748534600000, # int, epoch-ms\r\n    signature=\"...\",                  # str, optional RFC 9421 JWS\r\n)\r\n\r\n# Verify structural integrity (does NOT verify the RFC 9421 signature)\r\nresult = verify_pef(frame)\r\n# {\"valid\": True, \"errors\": []}\r\n\r\n# Re-derive frame_id from an existing frame\r\nfid = pef_frame_id(frame)\r\n\r\n# Inspect the closed enum\r\nprint(CLAIM_TYPES)\r\n# {\"payment_admission\": \"compliance-receipt-v1\", ...}\r\n```\r\n\r\n### TypeScript\r\n\r\n```typescript\r\nimport {\r\n  buildPef, verifyPef, pefFrameId,\r\n  CLAIM_TYPES, PEF_VERSION, CANON_VERSION,\r\n  type BuildPefOptions, type Pef, type VerifyResult,\r\n} from \"@algovoi/pef\";\r\n\r\nconst frame: Pef        = buildPef({ claim_type, receipt, frame_provider_did, frame_timestamp_ms });\r\nconst result: VerifyResult = verifyPef(frame);\r\nconst fid: string       = pefFrameId(frame);\r\n```\r\n\r\n## Platform integration\r\n\r\n`shared.utils.pef_wrapper` in the AlgoVoi gateway provides soft-import helpers\r\nso each router can emit PEF-wrapped receipts alongside existing fields:\r\n\r\n```python\r\nfrom shared.utils.pef_wrapper import (\r\n    wrap_compliance_receipt,      # payment_admission\r\n    wrap_settlement_attestation,  # payment_settlement\r\n    wrap_cancellation_receipt,    # payment_cancellation\r\n    wrap_refund_receipt,          # payment_refund\r\n    wrap_trust_query_response,    # composite_verdict\r\n)\r\n\r\n# compliance_gate.py -- returns None gracefully if algovoi-pef not installed\r\npef_frame = wrap_compliance_receipt(\r\n    compliance_receipt_dict,\r\n    screen_timestamp_ms=screen_ts,\r\n)\r\n```\r\n\r\nAll wrappers use `pef_or_none()` -- they return `None` during a rolling deploy\r\nbefore `algovoi-pef` is added to the platform requirements, so existing API\r\nresponses are unaffected.\r\n\r\n## Cross-implementation validation\r\n\r\n`frame_id` derivation has been independently validated across **eight JCS\r\nimplementations in eight programming languages** -- **64/64 byte-for-byte\r\nagreements** across all five claim types (both `receipt_hash` and `frame_id`\r\nlayers per vector):\r\n\r\n| Language | Runtime | JCS library | Author |\r\n|---|---|---|---|\r\n| Python | CPython 3.12 | `rfc8785` 0.1.4 | Trail of Bits |\r\n| JavaScript | Node.js v24 | `canonicalize` 1.0.8 | Samuel Erdtman |\r\n| Ruby | Ruby 3.4 | `json-canonicalization` 1.0.0 | RubyGems community |\r\n| PHP | PHP 8.4 | inline pure-stdlib JCS | AlgoVoi |\r\n| Go | Go 1.26 | `gowebpki/jcs` v1.0.1 | Web PKI Working Group |\r\n| Rust | Rust 1.95 | `serde_jcs` 0.2.0 | l1h3r |\r\n| Java | JDK 17 | `erdtman/java-json-canonicalization` 1.1 | Anders Rundgren (RFC 8785 author) + Samuel Erdtman |\r\n| .NET | .NET 9 | `Baqhub.Packages.JsonCanonicalization` 1.0.1 | Baqhub |\r\n\r\nFull attestation record and reproducible runner harnesses:\r\n[`_attestations/2026-05-30-8-impl-pef-v1.md`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/blob/main/_attestations/2026-05-30-8-impl-pef-v1.md)\r\nin [`chopmob-cloud/algovoi-jcs-conformance-vectors`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors).\r\n\r\nThe same corpus now has **576/576 cumulative byte-for-byte agreements** across\r\neight vector sets covering the full AlgoVoi agentic-payment receipt stack\r\n(admission, settlement, cancellation, refund, composite verdict, PEF).\r\n\r\n## Tests\r\n\r\n```bash\r\n# Unit tests (24 tests)\r\npython -m pytest tests/test_pef.py -v\r\n\r\n# Integration smoke tests -- platform-realistic receipt shapes + JS parity (32 tests)\r\npython -m pytest tests/test_smoke_pef_platform.py -v\r\n\r\n# Full suite (56 tests)\r\npython -m pytest tests/ -v\r\n\r\n# Live API integration test (requires network access to api.algovoi.co.uk)\r\npython -m pytest tests/test_smoke_pef_platform.py -v -m live\r\n\r\n# TypeScript tests (20 tests)\r\nnpm run build && npm test\r\n```\r\n\r\n## Specification\r\n\r\n- **Normative spec**: [`draft-hopley-x402-payment-evidence-frame-00`](https://datatracker.ietf.org/doc/draft-hopley-x402-payment-evidence-frame/) (IETF I-D, published 2026-05-30)\r\n- **Canonicalisation pin**: [`draft-hopley-x402-canonicalisation-jcs-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/)\r\n- **Receipt format I-Ds**:\r\n  - [`draft-hopley-x402-compliance-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-compliance-receipt/)\r\n  - [`draft-hopley-x402-settlement-attestation`](https://datatracker.ietf.org/doc/draft-hopley-x402-settlement-attestation/)\r\n  - [`draft-hopley-x402-cancellation-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-cancellation-receipt/)\r\n  - [`draft-hopley-x402-refund-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-refund-receipt/)\r\n  - [`draft-hopley-x402-composite-trust-query`](https://datatracker.ietf.org/doc/draft-hopley-x402-composite-trust-query/)\r\n- **Upstream x402 PRs**:\r\n  [#2493](https://github.com/x402-foundation/x402/pull/2493) /\r\n  [#2494](https://github.com/x402-foundation/x402/pull/2494) /\r\n  [#2495](https://github.com/x402-foundation/x402/pull/2495) /\r\n  [#2524](https://github.com/x402-foundation/x402/pull/2524) /\r\n  [#2525](https://github.com/x402-foundation/x402/pull/2525)\r\n- **Conformance vectors**: [`pef_v1`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/pef_v1) in `chopmob-cloud/algovoi-jcs-conformance-vectors`\r\n\r\n## Acknowledgments\r\n\r\nCross-implementation validation is possible because of the independent JCS\r\nlibraries listed in the matrix above. AlgoVoi acknowledges with thanks:\r\nTrail of Bits (`rfc8785`), Samuel Erdtman (`canonicalize` and\r\n`java-json-canonicalization`), Anders Rundgren (RFC 8785 author, Java\r\nimplementation), Web PKI Working Group (`gowebpki/jcs`), l1h3r (`serde_jcs`),\r\nBaqhub (`Baqhub.Packages.JsonCanonicalization`), and the RubyGems community\r\n(`json-canonicalization`).\r\n\r\n## Licence\r\n\r\nApache 2.0. See [LICENSE](./LICENSE).\r\n\r\n## Author\r\n\r\nAlgoVoi (Christopher Hopley, [`chopmob-cloud`](https://github.com/chopmob-cloud))\r\n## Attribution\r\n\r\nThis package is Apache-2.0. Use it freely and build whatever you are building on top of it. The only ask is the one the licence already makes: keep the NOTICE, and name who authored the substrate. To attribute it in your own product, add this to your NOTICE file:\r\n\r\n```\r\nThis product includes the AlgoVoi substrate,\r\nauthored by Christopher Hopley / AlgoVoi (chopmob-cloud), Apache-2.0.\r\nhttps://docs.algovoi.co.uk/canonicalisation-substrate\r\n```\r\n\r\nThe full invitation is at https://docs.algovoi.co.uk/canonicalisation-substrate#adopt-the-substrate\r\n","readmeFilename":"README.md"}