feat(extensions): add optional signed Offer & Receipt extension (draft, addresses #496)

[alftom]

Description

This PR proposes and implements an optional Offer & Receipt extension for x402, along with a reference TypeScript implementation and documentation. It is intended as a response to the discussion in #496.

What this introduces

• Signed Offers: optional, signed metadata attached to 402 Payment Required responses (accepts[])
• Signed Receipts: optional, signed acknowledgements returned on successful payment and service delivery
• Extension-only design:
  • fully opt-in
  • no behavior change unless explicitly enabled
  • no impact on existing x402 flows
• TypeScript reference implementation under typescript/packages/extensions/
• Server and client usage examples
• A written extension spec:
  • specs/extensions/extension-offer-and-receipt.md

The goal is to enable portable, verifiable proofs of paid service that can be reused outside the original request/response flow (e.g. disputes, auditing, or trust signals). One concrete use case: the OMATrust project (part of OMA3) plans to use these receipts as proofs for verified user-review attestations.

What this PR is not

• It does not require signed offers or receipts
• It does not mandate key-binding, identity, or attestation systems

Key authorization (e.g. whether a signing key is bound to a service identity) is intentionally treated as verifier policy, not a protocol requirement. The extension only defines the data model and signing semantics.

Intent of this PR

This PR is opened as a Draft to request maintainer and community feedback on the concept and integration surface before additional hardening.

In particular, feedback is requested on:

1. Whether signed offers and/or receipts belong as an x402 extension
2. Whether the framework-adapter integration surface is appropriate
3. Whether the extension spec and field placement make sense
4. Whether this functionality should live in x402 or remain out-of-band

If there is alignment on the concept, follow-up work can add:

• E2E extension tests
• additional adversarial / tamper test coverage
• expanded examples across frameworks
• JSDoc documentation

Tests

• TypeScript unit tests for the Offer/Receipt extension
  (typescript/packages/extensions/test/offer-receipt.test.ts)
• All existing repository tests pass
• Build and typecheck are clean across the monorepo

No E2E extension test is included in this PR; this is intentional for the draft stage and can be added once maintainers confirm interest in the extension.

Checklist

• I have formatted my code
• Lint passes (JSDoc documentation pending - will add before marking ready)
• All new and existing tests pass
• My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@alftom is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.