uvd-x402-sdk 2.55.0 → 2.56.0

package/dist/index.d.mts

@@ -29,6 +29,8 @@ export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, Pay
  * 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);
 }
@@ -103,14 +105,26 @@ declare function evidenceFromHeaders(headers: Headers | Record<string, string>):
  * a caller with their own resolver is not blocked by this function.
  */
 declare function dereferencePointer(pointer: string): string;
-interface SealedEnvelope {
+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.
  *
@@ -121,7 +135,13 @@ interface SealedEnvelope {
  * rather than an out-of-range surprise later.
  */
 declare function parseSealed(raw: Uint8Array): SealedEnvelope;
-/** Decrypt a sealed envelope with the payer's private key. */
+/**
+ * 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`.
@@ -821,4 +841,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-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 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, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };
+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

@@ -29,6 +29,8 @@ export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, Pay
  * 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);
 }
@@ -103,14 +105,26 @@ declare function evidenceFromHeaders(headers: Headers | Record<string, string>):
  * a caller with their own resolver is not blocked by this function.
  */
 declare function dereferencePointer(pointer: string): string;
-interface SealedEnvelope {
+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.
  *
@@ -121,7 +135,13 @@ interface SealedEnvelope {
  * rather than an out-of-range surprise later.
  */
 declare function parseSealed(raw: Uint8Array): SealedEnvelope;
-/** Decrypt a sealed envelope with the payer's private key. */
+/**
+ * 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`.
@@ -821,4 +841,4 @@ interface EscrowPreAuthParams {
  */
 declare function buildEscrowPreAuth(wallet: EscrowPreAuthSigner, params: EscrowPreAuthParams): Promise<string>;
 
-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 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, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, unseal };
+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.js

@@ -12,7 +12,9 @@ var ethers = require('ethers');
 // src/dx402.ts
 var EVIDENCE_HEADER = "X-Durable-Evidence";
 var MAGIC = new Uint8Array([68, 88, 52, 48, 50]);
-var FORMAT_VERSION = 1;
+var FORMAT_V1 = 1;
+var FORMAT_V2 = 2;
+var ROLE_NAMES = ["payer", "seller", "auditor"];
 var NONCE_LEN = 12;
 var CEK_LEN = 32;
 var HKDF_INFO = new TextEncoder().encode("DX402-v1-wrap");
@@ -103,6 +105,9 @@ function dereferencePointer(pointer) {
   if (pointer.startsWith("ar://")) return `https://arweave.net/${pointer.slice(5)}`;
   return pointer;
 }
+function sealedRoles(raw) {
+  return parseSealed(raw).recipients.map((r) => r.role);
+}
 function parseSealed(raw) {
   let pos = 0;
   const take = (n, what) => {
@@ -116,29 +121,38 @@ function parseSealed(raw) {
     if (magic[i] !== MAGIC[i]) throw new DX402Error("not a DX402 sealed blob");
   }
   const version = take(1, "version")[0];
-  if (version !== FORMAT_VERSION) {
-    throw new DX402Error(`unsupported sealed-blob version ${version}`);
-  }
-  const algByte = take(1, "algorithm")[0];
-  if (algByte !== 1 && algByte !== 2) {
-    throw new DX402Error(`unknown key algorithm ${algByte}`);
-  }
-  const ephLen = take(1, "ephemeral key length")[0];
-  const ephemeral = take(ephLen, "ephemeral key");
-  const cekNonce = take(NONCE_LEN, "cek nonce");
-  const lenBytes = take(2, "wrapped key length");
-  const wrappedLen = lenBytes[0] << 8 | lenBytes[1];
-  const wrappedCek = take(wrappedLen, "wrapped cek");
+  let count;
+  if (version === FORMAT_V1) count = 1;
+  else if (version === FORMAT_V2) count = take(1, "recipient count")[0];
+  else throw new DX402Error(`unsupported sealed-blob version ${version}`);
+  if (count === 0) throw new DX402Error("DX402 sealed blob has no recipients");
+  const recipients = [];
+  for (let i = 0; i < count; i++) {
+    let role = "payer";
+    if (version === FORMAT_V2) {
+      const b = take(1, "role")[0];
+      if (b >= ROLE_NAMES.length) throw new DX402Error(`unknown role ${b}`);
+      role = ROLE_NAMES[b];
+    }
+    const algByte = take(1, "algorithm")[0];
+    if (algByte !== 1 && algByte !== 2) {
+      throw new DX402Error(`unknown key algorithm ${algByte}`);
+    }
+    const ephLen = take(1, "ephemeral key length")[0];
+    const ephemeral = take(ephLen, "ephemeral key");
+    const cekNonce = take(NONCE_LEN, "cek nonce");
+    const lenBytes = take(2, "wrapped key length");
+    const wrappedCek = take(lenBytes[0] << 8 | lenBytes[1], "wrapped cek");
+    recipients.push({
+      role,
+      alg: algByte === 1 ? "secp256k1" : "x25519",
+      ephemeral,
+      cekNonce,
+      wrappedCek
+    });
+  }
   const bodyNonce = take(NONCE_LEN, "body nonce");
-  const ciphertext = raw.subarray(pos);
-  return {
-    alg: algByte === 1 ? "secp256k1" : "x25519",
-    ephemeral,
-    cekNonce,
-    wrappedCek,
-    bodyNonce,
-    ciphertext
-  };
+  return { recipients, bodyNonce, ciphertext: raw.subarray(pos) };
 }
 function sharedSecret(sealed, privateKey) {
   if (sealed.alg === "secp256k1") {
@@ -153,13 +167,29 @@ function sharedSecret(sealed, privateKey) {
   return shared;
 }
 function unseal(sealed, privateKey, aad) {
-  const shared = sharedSecret(sealed, privateKey);
-  const wrapKey = hkdf.hkdf(sha2.sha256, shared, aad, HKDF_INFO, 32);
-  const cek = aes.gcm(wrapKey, sealed.cekNonce, aad).decrypt(sealed.wrappedCek);
-  if (cek.length !== CEK_LEN) {
-    throw new DX402Error(`unwrapped CEK is ${cek.length} bytes, expected ${CEK_LEN}`);
+  for (const recipient of sealed.recipients) {
+    let shared;
+    try {
+      shared = sharedSecret(recipient, privateKey);
+    } catch (err) {
+      if (err instanceof DX402Error) throw err;
+      continue;
+    }
+    const wrapKey = hkdf.hkdf(sha2.sha256, shared, aad, HKDF_INFO, 32);
+    let cek;
+    try {
+      cek = aes.gcm(wrapKey, recipient.cekNonce, aad).decrypt(recipient.wrappedCek);
+    } catch {
+      continue;
+    }
+    if (cek.length !== CEK_LEN) {
+      throw new DX402Error(`unwrapped CEK is ${cek.length} bytes, expected ${CEK_LEN}`);
+    }
+    return aes.gcm(cek, sealed.bodyNonce, aad).decrypt(sealed.ciphertext);
   }
-  return aes.gcm(cek, sealed.bodyNonce, aad).decrypt(sealed.ciphertext);
+  throw new DX402Error(
+    "no recipient slot opened -- wrong key, or the blob belongs to another payment"
+  );
 }
 async function recoverEvidence(evidence, privateKey, options = {}) {
   const key = typeof privateKey === "string" ? hexToBytes(privateKey) : privateKey;
@@ -243,7 +273,7 @@ function sealEvidence(body, payerKey, paymentIdValue) {
   let pos = 0;
   out.set(MAGIC, pos);
   pos += MAGIC.length;
-  out[pos++] = FORMAT_VERSION;
+  out[pos++] = FORMAT_V1;
   out[pos++] = algByte;
   out[pos++] = ephemeral.length;
   out.set(ephemeral, pos);
@@ -4132,6 +4162,7 @@ exports.parseTrafficEvent = parseTrafficEvent;
 exports.payerKeyFromEvmSignature = payerKeyFromEvmSignature;
 exports.recoverEvidence = recoverEvidence;
 exports.sealEvidence = sealEvidence;
+exports.sealedRoles = sealedRoles;
 exports.signRequest = signRequest;
 exports.signRequestWithSigner = signRequestWithSigner;
 exports.signRequestWithWallet = signRequestWithWallet;