bsv-x402 0.3.0 → 0.4.1

package/dist/index.cjs

@@ -53,12 +53,15 @@ function parseBrc105Challenge(response) {
   if (!Number.isFinite(satoshisRequired) || !Number.isInteger(satoshisRequired) || satoshisRequired <= 0) {
     throw new Error("BRC-105: satoshis-required must be a positive integer");
   }
-  const serverIdentityKey = response.headers.get("x-bsv-auth-identity-key");
+  const authIdentityKey = response.headers.get("x-bsv-auth-identity-key") || null;
+  const paymentIdentityKey = response.headers.get("x-bsv-payment-identity-key") || null;
+  const authenticated = authIdentityKey !== null && authIdentityKey.length > 0;
+  const serverIdentityKey = authIdentityKey || paymentIdentityKey;
   if (serverIdentityKey === null || serverIdentityKey.length === 0) {
-    throw new Error("BRC-105: missing or empty x-bsv-auth-identity-key header");
+    throw new Error("BRC-105: missing identity key (expected x-bsv-auth-identity-key or x-bsv-payment-identity-key)");
   }
   if (!/^0[23][0-9a-fA-F]{64}$/.test(serverIdentityKey)) {
-    throw new Error("BRC-105: x-bsv-auth-identity-key must be a 33-byte compressed public key (hex)");
+    throw new Error("BRC-105: identity key must be a 33-byte compressed public key (hex)");
   }
   const derivationPrefix = response.headers.get("x-bsv-payment-derivation-prefix");
   if (derivationPrefix === null || derivationPrefix.length === 0) {
@@ -68,7 +71,8 @@ function parseBrc105Challenge(response) {
     version,
     satoshisRequired,
     serverIdentityKey,
-    derivationPrefix
+    derivationPrefix,
+    authenticated
   };
 }
 
@@ -516,7 +520,8 @@ async function createDerivationSuffix(wallet) {
   const nonceBytes = [...firstHalf, ...hmac];
   return numberArrayToBase64(nonceBytes);
 }
-async function constructBrc105Proof(challenge, wallet) {
+async function constructBrc105Proof(challenge, wallet, origin) {
+  const { publicKey: clientIdentityKey } = await wallet.getPublicKey({ identityKey: true });
   const derivationSuffix = await createDerivationSuffix(wallet);
   const keyID = `${challenge.derivationPrefix} ${derivationSuffix}`;
   const { publicKey: derivedPublicKey } = await wallet.getPublicKey({
@@ -525,12 +530,13 @@ async function constructBrc105Proof(challenge, wallet) {
     counterparty: challenge.serverIdentityKey
   });
   const lockingScript = await pubkeyToP2PKHLockingScript(derivedPublicKey);
+  const description = origin ? `Payment for request to ${origin}` : "BRC-105 payment";
   const result = await wallet.createAction({
-    description: "BRC-105 payment",
+    description,
     outputs: [{
       satoshis: challenge.satoshisRequired,
       lockingScript,
-      description: "BRC-105 payment output",
+      outputDescription: "HTTP request payment",
       customInstructions: JSON.stringify({
         derivationPrefix: challenge.derivationPrefix,
         derivationSuffix,
@@ -553,6 +559,7 @@ async function constructBrc105Proof(challenge, wallet) {
     derivationPrefix: challenge.derivationPrefix,
     derivationSuffix,
     transaction: transactionBase64,
+    clientIdentityKey,
     txid: result.txid
   };
 }
@@ -1165,12 +1172,26 @@ function createX402Fetch(config = {}) {
       let proof;
       try {
         proof = await buildProof();
-      } catch {
+      } catch (err) {
+        console.error(`[x402] Proof construction failed (${protocol}):`, err);
+        config.onProofError?.(err, protocol);
         return originalResponse;
       }
       rl.record(makeLedgerEntry(proof));
       await persist(rl);
-      return retryWithProof(proof);
+      const maxAttempts = 3;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          return await retryWithProof(proof);
+        } catch (err) {
+          if (attempt >= maxAttempts) {
+            console.error(`[x402] Paid request failed after ${maxAttempts} attempts (${protocol}):`, err);
+            return originalResponse;
+          }
+          await new Promise((r) => setTimeout(r, 250 * Math.pow(2, attempt)));
+        }
+      }
+      return originalResponse;
     });
   }
   const fetchFn = async function x402Fetch2(input, init) {
@@ -1226,11 +1247,12 @@ function createX402Fetch(config = {}) {
           if (brc105ProofConstructor) {
             return brc105ProofConstructor(brc105Challenge);
           }
-          return constructBrc105Proof(brc105Challenge, brc105Wallet);
+          return constructBrc105Proof(brc105Challenge, brc105Wallet, origin);
         },
         (proof) => {
           const headers = new Headers(init?.headers);
           headers.set("x-bsv-payment", JSON.stringify(proof));
+          headers.set("x-bsv-auth-identity-key", proof.clientIdentityKey);
           return fetch(input, { ...init, headers });
         },
         (proof) => ({

package/dist/index.d.cts

@@ -13,6 +13,8 @@ interface Brc105Challenge {
     satoshisRequired: number;
     serverIdentityKey: string;
     derivationPrefix: string;
+    /** Whether the identity key came from BRC-103 auth (vs standalone x-bsv-payment-identity-key). */
+    authenticated: boolean;
 }
 /** Minimal wallet interface for BRC-105 proof construction.
  *  Works with both CWIInterface (page context) and WalletInterface (SDK). */
@@ -21,6 +23,8 @@ interface Brc105Wallet {
         protocolID: [number, string];
         keyID: string;
         counterparty: string;
+    } | {
+        identityKey: true;
     }): Promise<{
         publicKey: string;
     }>;
@@ -38,6 +42,7 @@ interface Brc105Proof {
     derivationPrefix: string;
     derivationSuffix: string;
     transaction: string;
+    clientIdentityKey: string;
     txid: string;
 }
 type Brc105ProofConstructor = (challenge: Brc105Challenge) => Promise<Brc105Proof>;
@@ -93,6 +98,7 @@ interface X402Config {
     nightmareConfirmation?: string;
     onLimitReached?: (reason: string) => void;
     onYellowLight?: (detail: YellowLightEvent) => Promise<boolean>;
+    onProofError?: (error: unknown, protocol: PaymentProtocol) => void;
     now?: () => number;
 }
 interface YellowLightEvent {
@@ -135,6 +141,7 @@ interface CWICreateActionOutput {
     satoshis: number;
     lockingScript: string;
     description?: string;
+    outputDescription?: string;
     customInstructions?: string;
 }
 interface CWICreateActionParams {
@@ -194,7 +201,7 @@ declare function parseChallenge(header: string): Challenge;
  * Expects four headers:
  *   - x-bsv-payment-version (must be "1.0")
  *   - x-bsv-payment-satoshis-required (positive integer)
- *   - x-bsv-auth-identity-key (non-empty)
+ *   - x-bsv-auth-identity-key or x-bsv-payment-identity-key (compressed pubkey)
  *   - x-bsv-payment-derivation-prefix (non-empty)
  */
 declare function parseBrc105Challenge(response: Response): Brc105Challenge;
@@ -209,7 +216,7 @@ declare function parseBrc105Challenge(response: Response): Brc105Challenge;
  * 4. Call wallet.createAction with the locking script and custom instructions
  * 5. Convert transaction to base64
  */
-declare function constructBrc105Proof(challenge: Brc105Challenge, wallet: Brc105Wallet): Promise<Brc105Proof>;
+declare function constructBrc105Proof(challenge: Brc105Challenge, wallet: Brc105Wallet, origin?: string): Promise<Brc105Proof>;
 
 /** Anything with a numeric `amount` can be checked against spending limits. */
 type SpendCheckable = Challenge | PaymentRequest;
@@ -267,4 +274,4 @@ type SitePromptFn = (origin: string) => Promise<SitePolicyAction>;
  */
 declare function resolveSitePolicy(origin: string, limits: SpendLimits, twoFactorProvider?: TwoFactorProvider, promptFn?: SitePromptFn): Promise<SitePolicy>;
 
-export { BFG_DAILY_CEILING_SATOSHIS, BFG_PER_TX_CEILING_SATOSHIS, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type Challenge, type LedgerEntry, type LimitCheckResult, type LimitState, LocalStorageAdapter, type PaymentProtocol, type PaymentRequest, type Proof, RateLimiter, type SitePolicy, type SitePolicyAction, type SpendCheckable, type SpendLimits, type SpendMode, type StorageAdapter, TIER_PRESETS, type TierName, type TierPreset, type TimeWindow, type TwoFactorAction, type TwoFactorPolicy, type TwoFactorProvider, WalletTwoFactorProvider, type WindowLimit, type X402Config, type X402FetchFn, type YellowLightEvent, constructBrc105Proof, createX402Fetch, parseBrc105Challenge, parseChallenge, resolveSitePolicy, resolveSpendLimits, x402Fetch };
+export { BFG_DAILY_CEILING_SATOSHIS, BFG_PER_TX_CEILING_SATOSHIS, type BlockSeverity, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type CWICreateActionOutput, type CWICreateActionParams, type CWICreateActionResult, type Challenge, type KeyDeriver, type LedgerEntry, type LimitCheckResult, type LimitState, LocalStorageAdapter, type PaymentProtocol, type PaymentRequest, type Proof, RateLimiter, type SitePolicy, type SitePolicyAction, type SitePromptFn, type SpendCheckable, type SpendLimits, type SpendMode, type StorageAdapter, TIER_PRESETS, type TierName, type TierPreset, type TimeWindow, type TwoFactorAction, type TwoFactorPolicy, type TwoFactorProvider, WalletTwoFactorProvider, type WindowLimit, type X402Config, type X402FetchFn, type YellowLightEvent, constructBrc105Proof, createX402Fetch, parseBrc105Challenge, parseChallenge, resolveSitePolicy, resolveSpendLimits, x402Fetch };

package/dist/index.d.ts

@@ -13,6 +13,8 @@ interface Brc105Challenge {
     satoshisRequired: number;
     serverIdentityKey: string;
     derivationPrefix: string;
+    /** Whether the identity key came from BRC-103 auth (vs standalone x-bsv-payment-identity-key). */
+    authenticated: boolean;
 }
 /** Minimal wallet interface for BRC-105 proof construction.
  *  Works with both CWIInterface (page context) and WalletInterface (SDK). */
@@ -21,6 +23,8 @@ interface Brc105Wallet {
         protocolID: [number, string];
         keyID: string;
         counterparty: string;
+    } | {
+        identityKey: true;
     }): Promise<{
         publicKey: string;
     }>;
@@ -38,6 +42,7 @@ interface Brc105Proof {
     derivationPrefix: string;
     derivationSuffix: string;
     transaction: string;
+    clientIdentityKey: string;
     txid: string;
 }
 type Brc105ProofConstructor = (challenge: Brc105Challenge) => Promise<Brc105Proof>;
@@ -93,6 +98,7 @@ interface X402Config {
     nightmareConfirmation?: string;
     onLimitReached?: (reason: string) => void;
     onYellowLight?: (detail: YellowLightEvent) => Promise<boolean>;
+    onProofError?: (error: unknown, protocol: PaymentProtocol) => void;
     now?: () => number;
 }
 interface YellowLightEvent {
@@ -135,6 +141,7 @@ interface CWICreateActionOutput {
     satoshis: number;
     lockingScript: string;
     description?: string;
+    outputDescription?: string;
     customInstructions?: string;
 }
 interface CWICreateActionParams {
@@ -194,7 +201,7 @@ declare function parseChallenge(header: string): Challenge;
  * Expects four headers:
  *   - x-bsv-payment-version (must be "1.0")
  *   - x-bsv-payment-satoshis-required (positive integer)
- *   - x-bsv-auth-identity-key (non-empty)
+ *   - x-bsv-auth-identity-key or x-bsv-payment-identity-key (compressed pubkey)
  *   - x-bsv-payment-derivation-prefix (non-empty)
  */
 declare function parseBrc105Challenge(response: Response): Brc105Challenge;
@@ -209,7 +216,7 @@ declare function parseBrc105Challenge(response: Response): Brc105Challenge;
  * 4. Call wallet.createAction with the locking script and custom instructions
  * 5. Convert transaction to base64
  */
-declare function constructBrc105Proof(challenge: Brc105Challenge, wallet: Brc105Wallet): Promise<Brc105Proof>;
+declare function constructBrc105Proof(challenge: Brc105Challenge, wallet: Brc105Wallet, origin?: string): Promise<Brc105Proof>;
 
 /** Anything with a numeric `amount` can be checked against spending limits. */
 type SpendCheckable = Challenge | PaymentRequest;
@@ -267,4 +274,4 @@ type SitePromptFn = (origin: string) => Promise<SitePolicyAction>;
  */
 declare function resolveSitePolicy(origin: string, limits: SpendLimits, twoFactorProvider?: TwoFactorProvider, promptFn?: SitePromptFn): Promise<SitePolicy>;
 
-export { BFG_DAILY_CEILING_SATOSHIS, BFG_PER_TX_CEILING_SATOSHIS, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type Challenge, type LedgerEntry, type LimitCheckResult, type LimitState, LocalStorageAdapter, type PaymentProtocol, type PaymentRequest, type Proof, RateLimiter, type SitePolicy, type SitePolicyAction, type SpendCheckable, type SpendLimits, type SpendMode, type StorageAdapter, TIER_PRESETS, type TierName, type TierPreset, type TimeWindow, type TwoFactorAction, type TwoFactorPolicy, type TwoFactorProvider, WalletTwoFactorProvider, type WindowLimit, type X402Config, type X402FetchFn, type YellowLightEvent, constructBrc105Proof, createX402Fetch, parseBrc105Challenge, parseChallenge, resolveSitePolicy, resolveSpendLimits, x402Fetch };
+export { BFG_DAILY_CEILING_SATOSHIS, BFG_PER_TX_CEILING_SATOSHIS, type BlockSeverity, type Brc105Challenge, type Brc105Proof, type Brc105ProofConstructor, type Brc105Wallet, type CWICreateActionOutput, type CWICreateActionParams, type CWICreateActionResult, type Challenge, type KeyDeriver, type LedgerEntry, type LimitCheckResult, type LimitState, LocalStorageAdapter, type PaymentProtocol, type PaymentRequest, type Proof, RateLimiter, type SitePolicy, type SitePolicyAction, type SitePromptFn, type SpendCheckable, type SpendLimits, type SpendMode, type StorageAdapter, TIER_PRESETS, type TierName, type TierPreset, type TimeWindow, type TwoFactorAction, type TwoFactorPolicy, type TwoFactorProvider, WalletTwoFactorProvider, type WindowLimit, type X402Config, type X402FetchFn, type YellowLightEvent, constructBrc105Proof, createX402Fetch, parseBrc105Challenge, parseChallenge, resolveSitePolicy, resolveSpendLimits, x402Fetch };

package/dist/index.js

@@ -15,12 +15,15 @@ function parseBrc105Challenge(response) {
   if (!Number.isFinite(satoshisRequired) || !Number.isInteger(satoshisRequired) || satoshisRequired <= 0) {
     throw new Error("BRC-105: satoshis-required must be a positive integer");
   }
-  const serverIdentityKey = response.headers.get("x-bsv-auth-identity-key");
+  const authIdentityKey = response.headers.get("x-bsv-auth-identity-key") || null;
+  const paymentIdentityKey = response.headers.get("x-bsv-payment-identity-key") || null;
+  const authenticated = authIdentityKey !== null && authIdentityKey.length > 0;
+  const serverIdentityKey = authIdentityKey || paymentIdentityKey;
   if (serverIdentityKey === null || serverIdentityKey.length === 0) {
-    throw new Error("BRC-105: missing or empty x-bsv-auth-identity-key header");
+    throw new Error("BRC-105: missing identity key (expected x-bsv-auth-identity-key or x-bsv-payment-identity-key)");
   }
   if (!/^0[23][0-9a-fA-F]{64}$/.test(serverIdentityKey)) {
-    throw new Error("BRC-105: x-bsv-auth-identity-key must be a 33-byte compressed public key (hex)");
+    throw new Error("BRC-105: identity key must be a 33-byte compressed public key (hex)");
   }
   const derivationPrefix = response.headers.get("x-bsv-payment-derivation-prefix");
   if (derivationPrefix === null || derivationPrefix.length === 0) {
@@ -30,7 +33,8 @@ function parseBrc105Challenge(response) {
     version,
     satoshisRequired,
     serverIdentityKey,
-    derivationPrefix
+    derivationPrefix,
+    authenticated
   };
 }
 
@@ -478,7 +482,8 @@ async function createDerivationSuffix(wallet) {
   const nonceBytes = [...firstHalf, ...hmac];
   return numberArrayToBase64(nonceBytes);
 }
-async function constructBrc105Proof(challenge, wallet) {
+async function constructBrc105Proof(challenge, wallet, origin) {
+  const { publicKey: clientIdentityKey } = await wallet.getPublicKey({ identityKey: true });
   const derivationSuffix = await createDerivationSuffix(wallet);
   const keyID = `${challenge.derivationPrefix} ${derivationSuffix}`;
   const { publicKey: derivedPublicKey } = await wallet.getPublicKey({
@@ -487,12 +492,13 @@ async function constructBrc105Proof(challenge, wallet) {
     counterparty: challenge.serverIdentityKey
   });
   const lockingScript = await pubkeyToP2PKHLockingScript(derivedPublicKey);
+  const description = origin ? `Payment for request to ${origin}` : "BRC-105 payment";
   const result = await wallet.createAction({
-    description: "BRC-105 payment",
+    description,
     outputs: [{
       satoshis: challenge.satoshisRequired,
       lockingScript,
-      description: "BRC-105 payment output",
+      outputDescription: "HTTP request payment",
       customInstructions: JSON.stringify({
         derivationPrefix: challenge.derivationPrefix,
         derivationSuffix,
@@ -515,6 +521,7 @@ async function constructBrc105Proof(challenge, wallet) {
     derivationPrefix: challenge.derivationPrefix,
     derivationSuffix,
     transaction: transactionBase64,
+    clientIdentityKey,
     txid: result.txid
   };
 }
@@ -1127,12 +1134,26 @@ function createX402Fetch(config = {}) {
       let proof;
       try {
         proof = await buildProof();
-      } catch {
+      } catch (err) {
+        console.error(`[x402] Proof construction failed (${protocol}):`, err);
+        config.onProofError?.(err, protocol);
         return originalResponse;
       }
       rl.record(makeLedgerEntry(proof));
       await persist(rl);
-      return retryWithProof(proof);
+      const maxAttempts = 3;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          return await retryWithProof(proof);
+        } catch (err) {
+          if (attempt >= maxAttempts) {
+            console.error(`[x402] Paid request failed after ${maxAttempts} attempts (${protocol}):`, err);
+            return originalResponse;
+          }
+          await new Promise((r) => setTimeout(r, 250 * Math.pow(2, attempt)));
+        }
+      }
+      return originalResponse;
     });
   }
   const fetchFn = async function x402Fetch2(input, init) {
@@ -1188,11 +1209,12 @@ function createX402Fetch(config = {}) {
           if (brc105ProofConstructor) {
             return brc105ProofConstructor(brc105Challenge);
           }
-          return constructBrc105Proof(brc105Challenge, brc105Wallet);
+          return constructBrc105Proof(brc105Challenge, brc105Wallet, origin);
         },
         (proof) => {
           const headers = new Headers(init?.headers);
           headers.set("x-bsv-payment", JSON.stringify(proof));
+          headers.set("x-bsv-auth-identity-key", proof.clientIdentityKey);
           return fetch(input, { ...init, headers });
         },
         (proof) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bsv-x402",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "x402 payment protocol client — a fetch() wrapper that handles 402 payment flows transparently",
   "type": "module",
   "main": "dist/index.cjs",
@@ -25,19 +25,23 @@
     "build:firefox": "tsx plugins/build.ts --target firefox",
     "build:safari": "tsx plugins/build.ts --target safari",
     "build:all": "npm run build && npm run build:plugins",
-    "demo": "npm run build && tsx demo/server.ts"
+    "demo": "npm run build && tsx demo/server.ts",
+    "docs": "typedoc",
+    "postinstall": "patch-package"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/sgbett/bsv-x402.git"
+    "url": "git+https://github.com/sgbett/bsv-x402.git"
   },
   "devDependencies": {
     "@bsv/wallet-toolbox-client": "^2.1.17",
     "@types/chrome": "^0.1.38",
     "@types/express": "^5.0.6",
     "express": "^5.2.1",
+    "patch-package": "^8.0.1",
     "tsup": "^8.0.0",
     "tsx": "^4.21.0",
+    "typedoc": "^0.28.18",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"
   }