uvd-x402-sdk 2.53.0 → 2.56.0

package/dist/index.d.mts

@@ -6,6 +6,194 @@ export { a as EIP3009Authorization, E as EIP3009Params } from './wallet-w7BnImDG
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-Z9v4GxOZ.mjs';
 export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, getCorsHeaders } from './backend/index.mjs';
 
+/**
+ * DX402 `durable-evidence`: recover a paid response after the fact.
+ *
+ * x402 settles payment on-chain permanently but delivers the purchased resource
+ * **exactly once**, in the body of a `200 OK`, and keeps nothing. A buyer who did
+ * not capture it at that instant cannot recover it, and neither party can later
+ * prove *what* was delivered — only *that* payment happened.
+ *
+ * DX402 closes that gap. The seller seals a copy of the response to the payer's
+ * own public key — recovered from the payment signature itself — and anchors it.
+ * The buyer gets an `X-Durable-Evidence` header pointing at it.
+ *
+ * **Paying is publishing your encryption key.** No registration, no key
+ * exchange, no extra round trip.
+ *
+ * ```ts
+ * const evidence = evidenceFromHeaders(response.headers);
+ * const body = await recoverEvidence(evidence, myPrivateKey);
+ * ```
+ *
+ * Specification: `docs/plans/dx402/02-SPEC-v0.1.md` in x402-rs.
+ */
+declare const EVIDENCE_HEADER = "X-Durable-Evidence";
+/** Why a party holds a key to this evidence. */
+type RecipientRole = 'payer' | 'seller' | 'auditor';
+declare class DX402Error extends Error {
+    constructor(message: string);
+}
+/**
+ * No evidence was anchored for this payment.
+ *
+ * A normal outcome, not a fault: the body may have exceeded the seller's size
+ * cap, the store may have been unreachable, or the payer may be a
+ * smart-contract wallet with no recoverable key.
+ */
+declare class EvidenceSkipped extends DX402Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * The anchored bytes are not the bytes that were delivered.
+ *
+ * This is the interesting failure: the seller anchored something other than
+ * what it served, which is precisely the fraud `contentHash` exists to expose.
+ * Treat it as evidence of misbehaviour, not a transport glitch.
+ */
+declare class ContentHashMismatch extends DX402Error {
+    readonly anchored: string;
+    readonly actual: string;
+    constructor(anchored: string, actual: string);
+}
+type EvidenceMode = 'direct' | 'escrowed';
+interface AnchoredEvidence {
+    v: number;
+    paymentId: string;
+    pointer: string;
+    backend: string;
+    contentHash: string;
+    cipher: string;
+    keyAlg: 'ECIES-secp256k1' | 'ECIES-X25519';
+    mode: EvidenceMode;
+    retention: string;
+    receipt?: string;
+}
+/**
+ * Whether the facilitator is cryptographically unable to read this payload.
+ *
+ * `direct` and `escrowed` make materially different claims about who can open
+ * the payload, so a caller that cares about confidentiality must check rather
+ * than assume.
+ */
+declare function isEndToEnd(evidence: AnchoredEvidence): boolean;
+/** keccak256 of a body, `0x`-prefixed — matching the facilitator's `contentHash`. */
+declare function contentHash(body: Uint8Array): string;
+/**
+ * Derive the canonical payment identifier: `keccak256(caip2Network || txHash)`.
+ *
+ * This value is the AEAD associated data binding a ciphertext to its payment.
+ * Buyer and seller must derive it identically or decryption fails with no
+ * obvious cause, which is why it lives in the SDK rather than in each caller.
+ */
+declare function paymentId(caip2Network: string, txHash: string): string;
+/** Parse an `X-Durable-Evidence` header value. */
+declare function parseEvidenceHeader(value: string): AnchoredEvidence;
+/**
+ * Pull the anchored evidence out of a response's headers.
+ *
+ * Accepts a `Headers` object or a plain record. Lookup is case-insensitive,
+ * because HTTP does not care and different clients disagree about casing.
+ */
+declare function evidenceFromHeaders(headers: Headers | Record<string, string>): AnchoredEvidence;
+/**
+ * Turn a DX402 pointer into a fetchable URL.
+ *
+ * `s3+https://...` is a scheme tag over an ordinary HTTPS URL; `ipfs://` and
+ * `ar://` go through public gateways. Anything else passes through untouched, so
+ * a caller with their own resolver is not blocked by this function.
+ */
+declare function dereferencePointer(pointer: string): string;
+interface Recipient {
+    role: RecipientRole;
+    alg: 'secp256k1' | 'x25519';
+    ephemeral: Uint8Array;
+    cekNonce: Uint8Array;
+    wrappedCek: Uint8Array;
+}
+interface SealedEnvelope {
+    recipients: Recipient[];
+    bodyNonce: Uint8Array;
+    ciphertext: Uint8Array;
+}
+/**
+ * Who can open this blob, without decrypting anything.
+ *
+ * Worth surfacing: a buyer has to be able to see that the seller — or a
+ * designated auditor — also holds a key to what they bought. Finding that out
+ * afterwards would destroy the privacy property.
+ */
+declare function sealedRoles(raw: Uint8Array): RecipientRole[];
+/**
+ * Parse the sealed-blob layout.
+ *
+ * `MAGIC | version | alg | ephLen | eph | cekNonce | wrappedLen | wrapped |
+ *  bodyNonce | ciphertext`
+ *
+ * Every read is bounds-checked, so a truncated blob is a clear parse failure
+ * rather than an out-of-range surprise later.
+ */
+declare function parseSealed(raw: Uint8Array): SealedEnvelope;
+/**
+ * Decrypt a sealed envelope with whichever recipient slot belongs to `privateKey`.
+ *
+ * Tries every slot: a holder does not necessarily know which one is theirs, and
+ * in a multi-recipient envelope the payer is not always first. A slot that does
+ * not open is skipped, not reported — "that one was not for me" is not an error.
+ */
+declare function unseal(sealed: SealedEnvelope, privateKey: Uint8Array, aad: Uint8Array): Uint8Array;
+/**
+ * Fetch, decrypt and verify the body behind `evidence`.
+ *
+ * `privateKey` is the raw key of the wallet that paid: 32 bytes for both an EVM
+ * secp256k1 key and an ed25519 seed. Hex accepted with or without `0x`.
+ *
+ * In `direct` mode this needs no permission from anyone — the ciphertext was
+ * sealed to the public key of the wallet that paid, so retrieval is arithmetic
+ * rather than an access-control decision that could be refused or misconfigured.
+ *
+ * The `contentHash` check is **not optional**: it is what catches a seller that
+ * anchored something other than what it served.
+ */
+declare function recoverEvidence(evidence: AnchoredEvidence, privateKey: Uint8Array | string, options?: {
+    fetch?: typeof fetch;
+}): Promise<Uint8Array>;
+/**
+ * Map an ed25519 public key to its X25519 form.
+ *
+ * On ed25519 chains (Solana, NEAR, Stellar, Algorand) the address **is** the
+ * public key, so this is all that stands between an address and an encryption
+ * target — no signature, no lookup.
+ */
+declare function ed25519ToX25519(pubkey: Uint8Array): Uint8Array;
+/**
+ * Recover an EVM payer's secp256k1 public key from their payment signature.
+ *
+ * `digest` is the EIP-712 digest the payer actually signed. Getting it wrong
+ * does not throw: it recovers a *different, perfectly valid* key, and the body
+ * would be sealed to a stranger while every log line said success. The token's
+ * EIP-712 domain name varies per chain and even flips between a chain's mainnet
+ * and testnet, so derive it from the same table the facilitator uses.
+ *
+ * Returns the SEC1-compressed key (33 bytes).
+ */
+declare function payerKeyFromEvmSignature(signature: Uint8Array | string, digest: Uint8Array): Uint8Array;
+/**
+ * Seal `body` so that only the holder of the payer's private key can read it.
+ *
+ * `payerKey` is a 33-byte SEC1-compressed secp256k1 key (EVM, XRPL) or a 32-byte
+ * X25519 key from {@link ed25519ToX25519}.
+ *
+ * `paymentIdValue` is bound in as AEAD associated data, which is what stops a
+ * ciphertext from being replayed as the evidence for a different payment.
+ * Derive it with {@link paymentId} on both sides — deriving it differently makes
+ * decryption fail with no obvious cause.
+ *
+ * Returns the bytes to upload. Nothing here touches the network.
+ */
+declare function sealEvidence(body: Uint8Array, payerKey: Uint8Array, paymentIdValue: string): Uint8Array;
+
 /**
  * Facilitator wallet addresses by chain type
  *
@@ -653,4 +841,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-export { type CreateSignedFetchConfig, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, createSignedFetch, fetchNonce, getFacilitatorAddress, matchesFilters, parseTrafficEvent, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents };
+export { type AnchoredEvidence, ContentHashMismatch, type CreateSignedFetchConfig, DX402Error, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, type EvidenceMode, EvidenceSkipped, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type RecipientRole, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, recoverEvidence, sealEvidence, sealedRoles, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };

package/dist/index.d.ts

@@ -6,6 +6,194 @@ export { a as EIP3009Authorization, E as EIP3009Params } from './wallet-w7BnImDG
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-C-KmORG9.js';
 export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, getCorsHeaders } from './backend/index.js';
 
+/**
+ * DX402 `durable-evidence`: recover a paid response after the fact.
+ *
+ * x402 settles payment on-chain permanently but delivers the purchased resource
+ * **exactly once**, in the body of a `200 OK`, and keeps nothing. A buyer who did
+ * not capture it at that instant cannot recover it, and neither party can later
+ * prove *what* was delivered — only *that* payment happened.
+ *
+ * DX402 closes that gap. The seller seals a copy of the response to the payer's
+ * own public key — recovered from the payment signature itself — and anchors it.
+ * The buyer gets an `X-Durable-Evidence` header pointing at it.
+ *
+ * **Paying is publishing your encryption key.** No registration, no key
+ * exchange, no extra round trip.
+ *
+ * ```ts
+ * const evidence = evidenceFromHeaders(response.headers);
+ * const body = await recoverEvidence(evidence, myPrivateKey);
+ * ```
+ *
+ * Specification: `docs/plans/dx402/02-SPEC-v0.1.md` in x402-rs.
+ */
+declare const EVIDENCE_HEADER = "X-Durable-Evidence";
+/** Why a party holds a key to this evidence. */
+type RecipientRole = 'payer' | 'seller' | 'auditor';
+declare class DX402Error extends Error {
+    constructor(message: string);
+}
+/**
+ * No evidence was anchored for this payment.
+ *
+ * A normal outcome, not a fault: the body may have exceeded the seller's size
+ * cap, the store may have been unreachable, or the payer may be a
+ * smart-contract wallet with no recoverable key.
+ */
+declare class EvidenceSkipped extends DX402Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * The anchored bytes are not the bytes that were delivered.
+ *
+ * This is the interesting failure: the seller anchored something other than
+ * what it served, which is precisely the fraud `contentHash` exists to expose.
+ * Treat it as evidence of misbehaviour, not a transport glitch.
+ */
+declare class ContentHashMismatch extends DX402Error {
+    readonly anchored: string;
+    readonly actual: string;
+    constructor(anchored: string, actual: string);
+}
+type EvidenceMode = 'direct' | 'escrowed';
+interface AnchoredEvidence {
+    v: number;
+    paymentId: string;
+    pointer: string;
+    backend: string;
+    contentHash: string;
+    cipher: string;
+    keyAlg: 'ECIES-secp256k1' | 'ECIES-X25519';
+    mode: EvidenceMode;
+    retention: string;
+    receipt?: string;
+}
+/**
+ * Whether the facilitator is cryptographically unable to read this payload.
+ *
+ * `direct` and `escrowed` make materially different claims about who can open
+ * the payload, so a caller that cares about confidentiality must check rather
+ * than assume.
+ */
+declare function isEndToEnd(evidence: AnchoredEvidence): boolean;
+/** keccak256 of a body, `0x`-prefixed — matching the facilitator's `contentHash`. */
+declare function contentHash(body: Uint8Array): string;
+/**
+ * Derive the canonical payment identifier: `keccak256(caip2Network || txHash)`.
+ *
+ * This value is the AEAD associated data binding a ciphertext to its payment.
+ * Buyer and seller must derive it identically or decryption fails with no
+ * obvious cause, which is why it lives in the SDK rather than in each caller.
+ */
+declare function paymentId(caip2Network: string, txHash: string): string;
+/** Parse an `X-Durable-Evidence` header value. */
+declare function parseEvidenceHeader(value: string): AnchoredEvidence;
+/**
+ * Pull the anchored evidence out of a response's headers.
+ *
+ * Accepts a `Headers` object or a plain record. Lookup is case-insensitive,
+ * because HTTP does not care and different clients disagree about casing.
+ */
+declare function evidenceFromHeaders(headers: Headers | Record<string, string>): AnchoredEvidence;
+/**
+ * Turn a DX402 pointer into a fetchable URL.
+ *
+ * `s3+https://...` is a scheme tag over an ordinary HTTPS URL; `ipfs://` and
+ * `ar://` go through public gateways. Anything else passes through untouched, so
+ * a caller with their own resolver is not blocked by this function.
+ */
+declare function dereferencePointer(pointer: string): string;
+interface Recipient {
+    role: RecipientRole;
+    alg: 'secp256k1' | 'x25519';
+    ephemeral: Uint8Array;
+    cekNonce: Uint8Array;
+    wrappedCek: Uint8Array;
+}
+interface SealedEnvelope {
+    recipients: Recipient[];
+    bodyNonce: Uint8Array;
+    ciphertext: Uint8Array;
+}
+/**
+ * Who can open this blob, without decrypting anything.
+ *
+ * Worth surfacing: a buyer has to be able to see that the seller — or a
+ * designated auditor — also holds a key to what they bought. Finding that out
+ * afterwards would destroy the privacy property.
+ */
+declare function sealedRoles(raw: Uint8Array): RecipientRole[];
+/**
+ * Parse the sealed-blob layout.
+ *
+ * `MAGIC | version | alg | ephLen | eph | cekNonce | wrappedLen | wrapped |
+ *  bodyNonce | ciphertext`
+ *
+ * Every read is bounds-checked, so a truncated blob is a clear parse failure
+ * rather than an out-of-range surprise later.
+ */
+declare function parseSealed(raw: Uint8Array): SealedEnvelope;
+/**
+ * Decrypt a sealed envelope with whichever recipient slot belongs to `privateKey`.
+ *
+ * Tries every slot: a holder does not necessarily know which one is theirs, and
+ * in a multi-recipient envelope the payer is not always first. A slot that does
+ * not open is skipped, not reported — "that one was not for me" is not an error.
+ */
+declare function unseal(sealed: SealedEnvelope, privateKey: Uint8Array, aad: Uint8Array): Uint8Array;
+/**
+ * Fetch, decrypt and verify the body behind `evidence`.
+ *
+ * `privateKey` is the raw key of the wallet that paid: 32 bytes for both an EVM
+ * secp256k1 key and an ed25519 seed. Hex accepted with or without `0x`.
+ *
+ * In `direct` mode this needs no permission from anyone — the ciphertext was
+ * sealed to the public key of the wallet that paid, so retrieval is arithmetic
+ * rather than an access-control decision that could be refused or misconfigured.
+ *
+ * The `contentHash` check is **not optional**: it is what catches a seller that
+ * anchored something other than what it served.
+ */
+declare function recoverEvidence(evidence: AnchoredEvidence, privateKey: Uint8Array | string, options?: {
+    fetch?: typeof fetch;
+}): Promise<Uint8Array>;
+/**
+ * Map an ed25519 public key to its X25519 form.
+ *
+ * On ed25519 chains (Solana, NEAR, Stellar, Algorand) the address **is** the
+ * public key, so this is all that stands between an address and an encryption
+ * target — no signature, no lookup.
+ */
+declare function ed25519ToX25519(pubkey: Uint8Array): Uint8Array;
+/**
+ * Recover an EVM payer's secp256k1 public key from their payment signature.
+ *
+ * `digest` is the EIP-712 digest the payer actually signed. Getting it wrong
+ * does not throw: it recovers a *different, perfectly valid* key, and the body
+ * would be sealed to a stranger while every log line said success. The token's
+ * EIP-712 domain name varies per chain and even flips between a chain's mainnet
+ * and testnet, so derive it from the same table the facilitator uses.
+ *
+ * Returns the SEC1-compressed key (33 bytes).
+ */
+declare function payerKeyFromEvmSignature(signature: Uint8Array | string, digest: Uint8Array): Uint8Array;
+/**
+ * Seal `body` so that only the holder of the payer's private key can read it.
+ *
+ * `payerKey` is a 33-byte SEC1-compressed secp256k1 key (EVM, XRPL) or a 32-byte
+ * X25519 key from {@link ed25519ToX25519}.
+ *
+ * `paymentIdValue` is bound in as AEAD associated data, which is what stops a
+ * ciphertext from being replayed as the evidence for a different payment.
+ * Derive it with {@link paymentId} on both sides — deriving it differently makes
+ * decryption fail with no obvious cause.
+ *
+ * Returns the bytes to upload. Nothing here touches the network.
+ */
+declare function sealEvidence(body: Uint8Array, payerKey: Uint8Array, paymentIdValue: string): Uint8Array;
+
 /**
  * Facilitator wallet addresses by chain type
  *
@@ -653,4 +841,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-export { type CreateSignedFetchConfig, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, createSignedFetch, fetchNonce, getFacilitatorAddress, matchesFilters, parseTrafficEvent, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents };
+export { type AnchoredEvidence, ContentHashMismatch, type CreateSignedFetchConfig, DX402Error, type ERC8128RequestOptions, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, type EscrowNetworkConfig, type EscrowPaymentInfo, type EscrowPreAuthParams, type EscrowPreAuthSigner, type EscrowTierWindows, type EvidenceMode, EvidenceSkipped, FACILITATOR_ADDRESSES, type FacilitatorAddresses, KEEPALIVE_INTERVAL_MS, OPERATOR_FEE_BPS, type RecipientRole, type SSEFrame, SSEParser, type SignRequestOptions, type SignRequestWithSignerOptions, type SignatureBaseParams, type SignatureHeaders, type SignatureParamsInput, SigningWalletAdapter, type StreamTrafficEventsOptions, type TrafficEvent, type TrafficEventKind, TrafficStreamError, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, recoverEvidence, sealEvidence, sealedRoles, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };