uvd-x402-sdk 2.63.0 → 2.64.0

package/README.md

@@ -1280,3 +1280,92 @@ const isHealthy = await client.healthCheck();
 ## License
 
 MIT
+
+## DX402 — evidence that outlives the session
+
+x402 settles payment on-chain forever but delivers the resource **once** and
+keeps nothing. DX402 seals a copy of the response to the payer's own public key
+— recovered from the payment signature itself — and anchors it. No registration,
+no extra round trip: paying *is* publishing your encryption key.
+
+### Seller: one call
+
+```ts
+import { anchorEvidence, evidenceHeader } from 'uvd-x402-sdk';
+
+const result = await anchorEvidence(body, {
+  paymentId, network: 'base', txHash,
+  payer: payerAddr, payee: myAddr, payerKey: payerPubkey,
+  sign: (digest) => myCustodian.sign(digest),   // a callable, not a key
+});
+res.setHeader('X-Durable-Evidence', evidenceHeader(result));
+```
+
+**It never throws.** Every failure resolves to `result.skipped`, because
+evidence is an addition to the payment path and must never be a gate in front of
+it. An unreachable facilitator costs the receipt, never the sale.
+
+`sign` takes a **callable rather than a private key** so a custodian can sign:
+it receives the 32-byte digest and returns a signature without the seed ever
+leaving it.
+
+### Buyer: come back months later
+
+```ts
+import { recoverEvidence, evidenceFromHeaders } from 'uvd-x402-sdk';
+
+const evidence = evidenceFromHeaders(res.headers);
+const body = await recoverEvidence(evidence, myPrivateKey);
+```
+
+This needs permission from nobody. The ciphertext was sealed to the wallet that
+paid, so recovery is arithmetic rather than an access-control decision anyone
+could refuse. The `contentHash` check runs automatically and throws
+`ContentHashMismatch` — it is what catches a seller who anchored something other
+than what it served.
+
+### `verified` vs `signed` — read this before you branch on either
+
+Since facilitator **1.87.0** a signature alone does not make an anchor final:
+
+| field | means | supersedable by |
+|---|---|---|
+| `verified: true` | the **chain** confirmed this address is the payee | nothing — final |
+| `signed: true` | the claimant controls the address it *declared* | a verified anchor |
+| neither | anyone could have written it | either of the above |
+
+To reach `verified` you must send `proofOfPayment`. Without it the facilitator
+has checked no chain and answers `notVerifiedReason: "dx402_proof_missing"` —
+your signature was still accepted (`signed: true`), authorship simply was not
+certified.
+
+Why the split: `verified` was previously decided against the `payee` field *in
+the request*, which the caller supplies. Proving "I control the address I typed
+into my own request" was enough to own a stranger's evidence permanently.
+
+### Choosing where evidence is stored
+
+```ts
+import { availableBackends } from 'uvd-x402-sdk';
+
+for (const b of await availableBackends()) {
+  console.log(b.id, b.retention, b.revocable ? 'deletable' : 'IRREVERSIBLE');
+}
+
+await anchorEvidence(body, { ...opts, storage: 'ipfs-private' });
+```
+
+Ask rather than assume: what exists depends on the deployment, and you may be
+pointed at a facilitator that is not ours. `revocable: false` means the
+`retentionUntil` in the **signed** receipt cannot be honoured — on public IPFS,
+unpinning removes the facilitator's copy, not the network's.
+
+### Limits
+
+- Inline anchors cap at **64 KiB of request** (~47 KB of plaintext); the SDK
+  returns `skipped: 'too_large'` before touching the network.
+- Anchoring with `retention: 'permanent'` is **irrevocable**.
+- On Solana, `verified` is not reachable yet — the on-chain gate cannot read
+  that payment, so `signed: true` is the honest maximum.
+
+Full guide: [DX402.md](https://github.com/UltravioletaDAO/x402-rs/blob/main/docs/DX402.md)

package/dist/index.d.mts

@@ -283,6 +283,17 @@ interface AnchorOptions {
      * proves more may supersede it.
      */
     proofOfPayment?: Record<string, unknown>;
+    /**
+     * Which backend to anchor to (`"s3"`, `"ipfs-private"`, `"ipfs-public"`).
+     * Omit to take the facilitator's default.
+     *
+     * Ask {@link availableBackends} what a given facilitator offers rather than
+     * assuming — it depends on the deployment, and you may be pointed at one that
+     * is not ours. **`ipfs-public` is irreversible**: the bytes become permanently
+     * resolvable by anyone, and nobody, the facilitator included, can take them
+     * down.
+     */
+    storage?: string;
     /**
      * `(digest) => "0x..."`. A callable rather than a private key is what lets a
      * custodian sign: it receives the digest and returns the signature without the
@@ -323,6 +334,37 @@ declare function sellerDigestFor(paymentId: string, contentHash: string, payee:
  */
 declare const ANCHOR_MAX_REQUEST_BYTES: number;
 declare function anchorEvidence(body: Uint8Array, opts: AnchorOptions): Promise<Record<string, unknown>>;
+/** One storage option a facilitator offers, from `GET /dx402/stats`. */
+interface BackendOffer {
+    id: string;
+    retention: string;
+    /**
+     * Whether the bytes can actually be removed when retention expires.
+     *
+     * `false` means the `retentionUntil` in the signed receipt **cannot be
+     * honoured**: on public IPFS, unpinning removes the facilitator's copy, not
+     * the network's.
+     */
+    revocable: boolean;
+    /** Whether anyone resolves the bytes without going through the facilitator. */
+    public: boolean;
+    enabled: boolean;
+    disabledReason?: string;
+}
+/**
+ * Ask a facilitator which storage backends it actually offers.
+ *
+ * Ask instead of assuming. What exists depends on the deployment — one without
+ * a Pinata credential offers only `s3` — and an integrator may be pointed at a
+ * facilitator that is not ours. A hardcoded list in your code is a promise
+ * somebody else has to keep.
+ *
+ * Resolves to `[]` rather than rejecting when the facilitator is unreachable or
+ * does not run DX402 — same discipline as {@link anchorEvidence}.
+ */
+declare function availableBackends(facilitator?: string, opts?: {
+    fetch?: typeof fetch;
+}): Promise<BackendOffer[]>;
 /** Encode an anchor result for the `X-Durable-Evidence` response header. */
 declare function evidenceHeader(evidence: unknown): string;
 
@@ -973,4 +1015,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, 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, ZERO_ADDRESS, anchorDigest, anchorEvidence, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };
+export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, type AnchoredEvidence, type BackendOffer, 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, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };

package/dist/index.d.ts

@@ -283,6 +283,17 @@ interface AnchorOptions {
      * proves more may supersede it.
      */
     proofOfPayment?: Record<string, unknown>;
+    /**
+     * Which backend to anchor to (`"s3"`, `"ipfs-private"`, `"ipfs-public"`).
+     * Omit to take the facilitator's default.
+     *
+     * Ask {@link availableBackends} what a given facilitator offers rather than
+     * assuming — it depends on the deployment, and you may be pointed at one that
+     * is not ours. **`ipfs-public` is irreversible**: the bytes become permanently
+     * resolvable by anyone, and nobody, the facilitator included, can take them
+     * down.
+     */
+    storage?: string;
     /**
      * `(digest) => "0x..."`. A callable rather than a private key is what lets a
      * custodian sign: it receives the digest and returns the signature without the
@@ -323,6 +334,37 @@ declare function sellerDigestFor(paymentId: string, contentHash: string, payee:
  */
 declare const ANCHOR_MAX_REQUEST_BYTES: number;
 declare function anchorEvidence(body: Uint8Array, opts: AnchorOptions): Promise<Record<string, unknown>>;
+/** One storage option a facilitator offers, from `GET /dx402/stats`. */
+interface BackendOffer {
+    id: string;
+    retention: string;
+    /**
+     * Whether the bytes can actually be removed when retention expires.
+     *
+     * `false` means the `retentionUntil` in the signed receipt **cannot be
+     * honoured**: on public IPFS, unpinning removes the facilitator's copy, not
+     * the network's.
+     */
+    revocable: boolean;
+    /** Whether anyone resolves the bytes without going through the facilitator. */
+    public: boolean;
+    enabled: boolean;
+    disabledReason?: string;
+}
+/**
+ * Ask a facilitator which storage backends it actually offers.
+ *
+ * Ask instead of assuming. What exists depends on the deployment — one without
+ * a Pinata credential offers only `s3` — and an integrator may be pointed at a
+ * facilitator that is not ours. A hardcoded list in your code is a promise
+ * somebody else has to keep.
+ *
+ * Resolves to `[]` rather than rejecting when the facilitator is unreachable or
+ * does not run DX402 — same discipline as {@link anchorEvidence}.
+ */
+declare function availableBackends(facilitator?: string, opts?: {
+    fetch?: typeof fetch;
+}): Promise<BackendOffer[]>;
 /** Encode an anchor result for the `X-Durable-Evidence` response header. */
 declare function evidenceHeader(evidence: unknown): string;
 
@@ -973,4 +1015,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, 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, ZERO_ADDRESS, anchorDigest, anchorEvidence, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };
+export { ANCHOR_MAX_REQUEST_BYTES, type AnchorOptions, type AnchoredEvidence, type BackendOffer, 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, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildSignatureBase, buildSignatureParams, computeEscrowNonce, contentHash, createSignedFetch, dereferencePointer, paymentId as dx402PaymentId, ed25519ToX25519, evidenceFromHeaders, evidenceHeader, fetchNonce, getFacilitatorAddress, isEndToEnd, matchesFilters, parseEvidenceHeader, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, recoverEvidence, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };

package/dist/index.js

@@ -1628,6 +1628,9 @@ async function anchorEvidence(body, opts) {
     if (opts.proofOfPayment) {
       payload.proofOfPayment = opts.proofOfPayment;
     }
+    if (opts.storage) {
+      payload.storage = opts.storage;
+    }
     if (opts.sign) {
       const digest = sellerDigestFor(opts.paymentId, hash, opts.payee, opts.network);
       if (digest === void 0) {
@@ -1665,6 +1668,17 @@ async function anchorEvidence(body, opts) {
     return { v: 1, skipped: "anchor_failed" };
   }
 }
+async function availableBackends(facilitator = "https://facilitator.ultravioletadao.xyz", opts = {}) {
+  try {
+    const doFetch = opts.fetch ?? fetch;
+    const res = await doFetch(`${facilitator.replace(/\/+$/, "")}/dx402/stats`);
+    if (!res.ok) return [];
+    const body = await res.json();
+    return body.backends ?? [];
+  } catch {
+    return [];
+  }
+}
 function evidenceHeader(evidence) {
   const bytes = new TextEncoder().encode(JSON.stringify(evidence));
   return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -4331,6 +4345,7 @@ exports.X402_HEADER_NAMES = X402_HEADER_NAMES;
 exports.ZERO_ADDRESS = ZERO_ADDRESS;
 exports.anchorDigest = anchorDigest;
 exports.anchorEvidence = anchorEvidence;
+exports.availableBackends = availableBackends;
 exports.buildEscrowPreAuth = buildEscrowPreAuth;
 exports.buildPaymentRequirements = buildPaymentRequirements;
 exports.buildSettleRequest = buildSettleRequest;