@bsv/sdk 1.8.6 → 1.8.7

package/src/auth/clients/AuthFetch.ts

@@ -18,6 +18,8 @@ interface SimplifiedFetchRequestOptions {
   headers?: Record<string, string>
   body?: any
   retryCounter?: number
+  paymentContext?: PaymentRetryContext
+  paymentRetryAttempts?: number
 }
 
 interface AuthPeer {
@@ -27,6 +29,32 @@ interface AuthPeer {
   pendingCertificateRequests: Array<true>
 }
 
+interface PaymentErrorLogEntry {
+  attempt: number
+  timestamp: string
+  message: string
+  stack?: string
+}
+
+interface PaymentRetryContext {
+  satoshisRequired: number
+  transactionBase64: string
+  derivationPrefix: string
+  derivationSuffix: string
+  serverIdentityKey: string
+  clientIdentityKey: string
+  attempts: number
+  maxAttempts: number
+  errors: PaymentErrorLogEntry[]
+  requestSummary: {
+    url: string
+    method: string
+    headers: Record<string, string>
+    bodyType: string
+    bodyByteLength: number
+  }
+}
+
 const PAYMENT_VERSION = '1.0'
 
 /**
@@ -445,16 +473,12 @@ export class AuthFetch {
     config: SimplifiedFetchRequestOptions = {},
     originalResponse: Response
   ): Promise<Response | null> {
-    // Make sure the server is using the correct payment version
     const paymentVersion = originalResponse.headers.get('x-bsv-payment-version')
     if (!paymentVersion || paymentVersion !== PAYMENT_VERSION) {
       throw new Error(`Unsupported x-bsv-payment-version response header. Client version: ${PAYMENT_VERSION}, Server version: ${paymentVersion}`)
     }
 
-    // Get required headers from the 402 response
-    const satoshisRequiredHeader = originalResponse.headers.get(
-      'x-bsv-payment-satoshis-required'
-    )
+    const satoshisRequiredHeader = originalResponse.headers.get('x-bsv-payment-satoshis-required')
     if (!satoshisRequiredHeader) {
       throw new Error('Missing x-bsv-payment-satoshis-required response header.')
     }
@@ -473,18 +497,117 @@ export class AuthFetch {
       throw new Error('Missing x-bsv-payment-derivation-prefix response header.')
     }
 
-    // Create a random suffix for the derivation path
+    let paymentContext = config.paymentContext
+    if (paymentContext != null) {
+      const requirementsChanged = !this.isPaymentContextCompatible(
+        paymentContext,
+        satoshisRequired,
+        serverIdentityKey,
+        derivationPrefix
+      )
+      if (requirementsChanged) {
+        this.logPaymentAttempt('warn', 'Server adjusted payment requirements; regenerating transaction', this.composePaymentLogDetails(url, paymentContext))
+        paymentContext = await this.createPaymentContext(
+          url,
+          config,
+          satoshisRequired,
+          serverIdentityKey,
+          derivationPrefix
+        )
+      }
+    } else {
+      paymentContext = await this.createPaymentContext(
+        url,
+        config,
+        satoshisRequired,
+        serverIdentityKey,
+        derivationPrefix
+      )
+    }
+
+    if (paymentContext.attempts >= paymentContext.maxAttempts) {
+      throw this.buildPaymentFailureError(url, paymentContext, new Error('Maximum payment attempts exceeded before retrying'))
+    }
+
+    const headersWithPayment: Record<string, string> = {
+      ...(config.headers ?? {})
+    }
+    headersWithPayment['x-bsv-payment'] = JSON.stringify({
+      derivationPrefix: paymentContext.derivationPrefix,
+      derivationSuffix: paymentContext.derivationSuffix,
+      transaction: paymentContext.transactionBase64
+    })
+
+    const nextConfig: SimplifiedFetchRequestOptions = {
+      ...config,
+      headers: headersWithPayment,
+      paymentContext
+    }
+
+    if (typeof nextConfig.retryCounter !== 'number') {
+      nextConfig.retryCounter = 3
+    }
+
+    const attemptNumber = paymentContext.attempts + 1
+    const maxAttempts = paymentContext.maxAttempts
+    paymentContext.attempts = attemptNumber
+    const attemptDetails = this.composePaymentLogDetails(url, paymentContext)
+    this.logPaymentAttempt('warn', `Attempting paid request (${attemptNumber}/${maxAttempts})`, attemptDetails)
+
+    try {
+      const response = await this.fetch(url, nextConfig)
+      this.logPaymentAttempt('info', `Paid request attempt ${attemptNumber} succeeded`, attemptDetails)
+      return response
+    } catch (error) {
+      const errorEntry = this.createPaymentErrorEntry(paymentContext.attempts, error)
+      paymentContext.errors.push(errorEntry)
+      this.logPaymentAttempt('error', `Paid request attempt ${attemptNumber} failed`, {
+        ...attemptDetails,
+        error: {
+          message: errorEntry.message,
+          stack: errorEntry.stack
+        }
+      })
+
+      if (paymentContext.attempts >= paymentContext.maxAttempts) {
+        throw this.buildPaymentFailureError(url, paymentContext, error)
+      }
+
+      const delayMs = this.getPaymentRetryDelay(paymentContext.attempts)
+      await this.wait(delayMs)
+      return this.handlePaymentAndRetry(url, nextConfig, originalResponse)
+    }
+  }
+
+  private isPaymentContextCompatible (
+    context: PaymentRetryContext,
+    satoshisRequired: number,
+    serverIdentityKey: string,
+    derivationPrefix: string
+  ): boolean {
+    return (
+      context.satoshisRequired === satoshisRequired &&
+      context.serverIdentityKey === serverIdentityKey &&
+      context.derivationPrefix === derivationPrefix
+    )
+  }
+
+  private async createPaymentContext (
+    url: string,
+    config: SimplifiedFetchRequestOptions,
+    satoshisRequired: number,
+    serverIdentityKey: string,
+    derivationPrefix: string
+  ): Promise<PaymentRetryContext> {
     const derivationSuffix = await createNonce(this.wallet, undefined, this.originator)
 
-    // Derive the script hex from the server identity key
     const { publicKey: derivedPublicKey } = await this.wallet.getPublicKey({
-      protocolID: [2, '3241645161d8'], // wallet payment protocol
+      protocolID: [2, '3241645161d8'],
       keyID: `${derivationPrefix} ${derivationSuffix}`,
       counterparty: serverIdentityKey
     }, this.originator)
     const lockingScript = new P2PKH().lock(PublicKey.fromString(derivedPublicKey).toAddress()).toHex()
 
-    // Create the payment transaction using createAction
     const { tx } = await this.wallet.createAction({
       description: `Payment for request to ${new URL(url).origin}`,
       outputs: [{
@@ -498,19 +621,205 @@ export class AuthFetch {
       }
     }, this.originator)
 
+    const { publicKey: clientIdentityKey } = await this.wallet.getPublicKey({ identityKey: true }, this.originator)
 
-
-    // Attach the payment to the request headers
-    config.headers = config.headers || {}
-    config.headers['x-bsv-payment'] = JSON.stringify({
+    return {
+      satoshisRequired,
+      transactionBase64: Utils.toBase64(tx),
       derivationPrefix,
       derivationSuffix,
-      transaction: Utils.toBase64(tx)
-    })
-    config.retryCounter ??= 3
+      serverIdentityKey,
+      clientIdentityKey,
+      attempts: 0,
+      maxAttempts: this.getMaxPaymentAttempts(config),
+      errors: [],
+      requestSummary: this.buildPaymentRequestSummary(url, config)
+    }
+  }
+
+  private getMaxPaymentAttempts (config: SimplifiedFetchRequestOptions): number {
+    const attempts = typeof config.paymentRetryAttempts === 'number' ? config.paymentRetryAttempts : undefined
+    if (typeof attempts === 'number' && attempts > 0) {
+      return Math.floor(attempts)
+    }
+    return 3
+  }
+
+  private buildPaymentRequestSummary (
+    url: string,
+    config: SimplifiedFetchRequestOptions
+  ): PaymentRetryContext['requestSummary'] {
+    const headers = { ...(config.headers ?? {}) }
+    const method = typeof config.method === 'string' ? config.method.toUpperCase() : 'GET'
+    const bodySummary = this.describeRequestBodyForLogging(config.body)
+
+    return {
+      url,
+      method,
+      headers,
+      bodyType: bodySummary.type,
+      bodyByteLength: bodySummary.byteLength
+    }
+  }
+
+  private describeRequestBodyForLogging (body: any): { type: string, byteLength: number } {
+    if (body == null) {
+      return { type: 'none', byteLength: 0 }
+    }
+
+    if (typeof body === 'string') {
+      return { type: 'string', byteLength: Utils.toArray(body, 'utf8').length }
+    }
+
+    if (Array.isArray(body)) {
+      if (body.every((item) => typeof item === 'number')) {
+        return { type: 'number[]', byteLength: body.length }
+      }
+      return { type: 'array', byteLength: body.length }
+    }
+
+    if (typeof ArrayBuffer !== 'undefined' && body instanceof ArrayBuffer) {
+      return { type: 'ArrayBuffer', byteLength: body.byteLength }
+    }
+
+    if (typeof ArrayBuffer !== 'undefined' && ArrayBuffer.isView(body)) {
+      return {
+        type: body.constructor != null ? body.constructor.name : 'TypedArray',
+        byteLength: body.byteLength
+      }
+    }
+
+    if (typeof Blob !== 'undefined' && body instanceof Blob) {
+      return { type: 'Blob', byteLength: body.size }
+    }
+
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+      return { type: 'FormData', byteLength: 0 }
+    }
+
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+      const serialized = body.toString()
+      return { type: 'URLSearchParams', byteLength: Utils.toArray(serialized, 'utf8').length }
+    }
+
+    if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+      return { type: 'ReadableStream', byteLength: 0 }
+    }
+
+    try {
+      const serialized = JSON.stringify(body)
+      if (typeof serialized === 'string') {
+        return { type: 'object', byteLength: Utils.toArray(serialized, 'utf8').length }
+      }
+    } catch (_) {
+      // Ignore JSON serialization issues for logging purposes.
+    }
+
+    return { type: typeof body, byteLength: 0 }
+  }
+
+  private composePaymentLogDetails (url: string, context: PaymentRetryContext): Record<string, any> {
+    return {
+      url,
+      request: context.requestSummary,
+      payment: {
+        satoshis: context.satoshisRequired,
+        transactionBase64: context.transactionBase64,
+        derivationPrefix: context.derivationPrefix,
+        derivationSuffix: context.derivationSuffix,
+        serverIdentityKey: context.serverIdentityKey,
+        clientIdentityKey: context.clientIdentityKey
+      },
+      attempts: {
+        used: context.attempts,
+        max: context.maxAttempts
+      },
+      errors: context.errors
+    }
+  }
+
+  private logPaymentAttempt (
+    level: 'info' | 'warn' | 'error',
+    message: string,
+    details: Record<string, any>
+  ): void {
+    const prefix = '[AuthFetch][Payment]'
+    if (level === 'error') {
+      console.error(`${prefix} ${message}`, details)
+    } else if (level === 'warn') {
+      console.warn(`${prefix} ${message}`, details)
+    } else {
+      if (typeof console.info === 'function') {
+        console.info(`${prefix} ${message}`, details)
+      } else {
+        console.log(`${prefix} ${message}`, details)
+      }
+    }
+  }
+
+  private createPaymentErrorEntry (attempt: number, error: unknown): PaymentErrorLogEntry {
+    const entry: PaymentErrorLogEntry = {
+      attempt,
+      timestamp: new Date().toISOString(),
+      message: '',
+      stack: undefined
+    }
+
+    if (error instanceof Error) {
+      entry.message = error.message
+      entry.stack = error.stack ?? undefined
+    } else {
+      entry.message = String(error)
+    }
+
+    return entry
+  }
+
+  private getPaymentRetryDelay (attempt: number): number {
+    const baseDelay = 250
+    const multiplier = Math.min(attempt, 5)
+    return baseDelay * multiplier
+  }
+
+  private async wait (ms: number): Promise<void> {
+    if (ms <= 0) {
+      return
+    }
+    await new Promise(resolve => setTimeout(resolve, ms))
+  }
+
+  private buildPaymentFailureError (
+    url: string,
+    context: PaymentRetryContext,
+    lastError: unknown
+  ): Error {
+    const message = `Paid request to ${url} failed after ${context.attempts}/${context.maxAttempts} attempts. Sent ${context.satoshisRequired} satoshis to ${context.serverIdentityKey}.`
+    const error = new Error(message)
+
+    const failureDetails = {
+      request: context.requestSummary,
+      payment: {
+        satoshis: context.satoshisRequired,
+        transactionBase64: context.transactionBase64,
+        derivationPrefix: context.derivationPrefix,
+        derivationSuffix: context.derivationSuffix,
+        serverIdentityKey: context.serverIdentityKey,
+        clientIdentityKey: context.clientIdentityKey
+      },
+      attempts: {
+        used: context.attempts,
+        max: context.maxAttempts
+      },
+      errors: context.errors
+    }
+
+    ;(error as any).details = failureDetails
+
+    if (lastError instanceof Error) {
+      ;(error as any).cause = lastError
+    }
 
-    // Re-attempt request with payment attached
-    return this.fetch(url, config)
+    return error
   }
 
   private async normalizeBodyToNumberArray(body: BodyInit | null | undefined): Promise<number[]> {

package/src/auth/clients/__tests__/AuthFetch.test.ts

@@ -0,0 +1,262 @@
+import { jest } from '@jest/globals'
+import { AuthFetch } from '../AuthFetch.js'
+import { Utils, PrivateKey } from '../../../primitives/index.js'
+
+jest.mock('../../utils/createNonce.js', () => ({
+  createNonce: jest.fn()
+}))
+
+import { createNonce } from '../../utils/createNonce.js'
+
+type Mutable<T> = {
+  -readonly [P in keyof T]: T[P]
+}
+
+interface TestPaymentContext {
+  satoshisRequired: number
+  transactionBase64: string
+  derivationPrefix: string
+  derivationSuffix: string
+  serverIdentityKey: string
+  clientIdentityKey: string
+  attempts: number
+  maxAttempts: number
+  errors: Array<{
+    attempt: number
+    timestamp: string
+    message: string
+    stack?: string
+  }>
+  requestSummary: {
+    url: string
+    method: string
+    headers: Record<string, string>
+    bodyType: string
+    bodyByteLength: number
+  }
+}
+
+const createNonceMock = createNonce as jest.MockedFunction<typeof createNonce>
+
+function createWalletStub (): any {
+  const identityKey = new PrivateKey(10).toPublicKey().toString()
+  const derivedKey = new PrivateKey(11).toPublicKey().toString()
+
+  return {
+    getPublicKey: jest.fn(async (options: Record<string, any>) => {
+      if (options?.identityKey === true) {
+        return { publicKey: identityKey }
+      }
+      return { publicKey: derivedKey }
+    }),
+    createAction: jest.fn(async () => ({
+      tx: Utils.toArray('mock-transaction', 'utf8')
+    })),
+    createHmac: jest.fn(async () => ({
+      hmac: new Array(32).fill(7)
+    }))
+  }
+}
+
+function createPaymentRequiredResponse (overrides: Record<string, string> = {}): Response {
+  const headers: Record<string, string> = {
+    'x-bsv-payment-version': '1.0',
+    'x-bsv-payment-satoshis-required': '5',
+    'x-bsv-auth-identity-key': 'server-key',
+    'x-bsv-payment-derivation-prefix': 'prefix',
+    ...overrides
+  }
+  return new Response('', { status: 402, headers })
+}
+
+afterEach(() => {
+  jest.restoreAllMocks()
+  createNonceMock.mockReset()
+})
+
+describe('AuthFetch payment handling', () => {
+  test('createPaymentContext builds a complete retry context', async () => {
+    const wallet = createWalletStub()
+    const authFetch = new AuthFetch(wallet as any)
+
+    createNonceMock.mockResolvedValueOnce('suffix-from-test')
+
+    const config = {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: { hello: 'world' }
+    }
+
+    const context = await (authFetch as any).createPaymentContext(
+      'https://api.example.com/resource',
+      config,
+      42,
+      'remote-identity-key',
+      'test-prefix'
+    ) as TestPaymentContext
+
+    expect(context.satoshisRequired).toBe(42)
+    expect(context.serverIdentityKey).toBe('remote-identity-key')
+    expect(context.derivationPrefix).toBe('test-prefix')
+    expect(context.derivationSuffix).toBe('suffix-from-test')
+    expect(context.transactionBase64).toBe(Utils.toBase64(Utils.toArray('mock-transaction', 'utf8')))
+    expect(context.clientIdentityKey).toEqual(expect.any(String))
+    expect(context.attempts).toBe(0)
+    expect(context.maxAttempts).toBe(3)
+    expect(context.errors).toEqual([])
+    expect(context.requestSummary).toMatchObject({
+      url: 'https://api.example.com/resource',
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      bodyType: 'object'
+    })
+    expect(context.requestSummary.bodyByteLength).toBe(
+      Utils.toArray(JSON.stringify(config.body), 'utf8').length
+    )
+
+    expect(wallet.createAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        description: expect.stringContaining('https://api.example.com'),
+        outputs: [
+          expect.objectContaining({
+            satoshis: 42,
+            customInstructions: expect.stringContaining('remote-identity-key')
+          })
+        ]
+      }),
+      undefined
+    )
+  })
+
+  test('handlePaymentAndRetry reuses compatible contexts and adds payment header', async () => {
+    const wallet = createWalletStub()
+    const authFetch = new AuthFetch(wallet as any)
+
+    const paymentContext: TestPaymentContext = {
+      satoshisRequired: 5,
+      transactionBase64: Utils.toBase64([1, 2, 3]),
+      derivationPrefix: 'prefix',
+      derivationSuffix: 'suffix',
+      serverIdentityKey: 'server-key',
+      clientIdentityKey: 'client-key',
+      attempts: 0,
+      maxAttempts: 3,
+      errors: [],
+      requestSummary: {
+        url: 'https://api.example.com/resource',
+        method: 'POST',
+        headers: { 'X-Test': '1' },
+        bodyType: 'none',
+        bodyByteLength: 0
+      }
+    }
+
+    const fetchSpy = jest.spyOn(authFetch, 'fetch').mockResolvedValue({ status: 200 } as Response)
+    jest.spyOn(authFetch as any, 'logPaymentAttempt').mockImplementation(() => {})
+    const createPaymentContextSpy = jest.spyOn(authFetch as any, 'createPaymentContext')
+
+    const config: Mutable<any> = {
+      headers: { 'x-custom': 'value' },
+      paymentContext
+    }
+
+    const response = createPaymentRequiredResponse()
+
+    const result = await (authFetch as any).handlePaymentAndRetry(
+      'https://api.example.com/resource',
+      config,
+      response
+    )
+
+    expect(result).toEqual({ status: 200 })
+    expect(paymentContext.attempts).toBe(1)
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+    const callArgs = fetchSpy.mock.calls[0] as [string, any]
+    const nextConfig = callArgs?.[1]
+    expect(nextConfig).toBeDefined()
+    expect(nextConfig.paymentContext).toBe(paymentContext)
+    expect(nextConfig.retryCounter).toBe(3)
+
+    const paymentHeader = JSON.parse(nextConfig.headers['x-bsv-payment'])
+    expect(paymentHeader).toEqual({
+      derivationPrefix: 'prefix',
+      derivationSuffix: 'suffix',
+      transaction: Utils.toBase64([1, 2, 3])
+    })
+
+    expect(createPaymentContextSpy).not.toHaveBeenCalled()
+  })
+
+  test('handlePaymentAndRetry exhausts attempts and throws detailed error', async () => {
+    const wallet = createWalletStub()
+    const authFetch = new AuthFetch(wallet as any)
+    jest.spyOn(authFetch as any, 'logPaymentAttempt').mockImplementation(() => {})
+    jest.spyOn(authFetch as any, 'wait').mockResolvedValue(undefined)
+
+    const firstError = new Error('payment attempt 1 failed')
+    const secondError = new Error('payment attempt 2 failed')
+    jest.spyOn(authFetch, 'fetch')
+      .mockRejectedValueOnce(firstError)
+      .mockRejectedValueOnce(secondError)
+
+    const paymentContext: TestPaymentContext = {
+      satoshisRequired: 5,
+      transactionBase64: Utils.toBase64([9, 9, 9]),
+      derivationPrefix: 'prefix',
+      derivationSuffix: 'suffix',
+      serverIdentityKey: 'server-key',
+      clientIdentityKey: 'client-key',
+      attempts: 0,
+      maxAttempts: 2,
+      errors: [],
+      requestSummary: {
+        url: 'https://api.example.com/resource',
+        method: 'GET',
+        headers: {},
+        bodyType: 'none',
+        bodyByteLength: 0
+      }
+    }
+
+    const config: Mutable<any> = { paymentContext }
+    const response = createPaymentRequiredResponse()
+
+    await expect((async () => {
+      try {
+        await (authFetch as any).handlePaymentAndRetry(
+          'https://api.example.com/resource',
+          config,
+          response
+        )
+      } catch (error) {
+        const err = error as any
+        expect(err.message).toBe(
+          'Paid request to https://api.example.com/resource failed after 2/2 attempts. Sent 5 satoshis to server-key.'
+        )
+        expect(err.details).toMatchObject({
+          attempts: { used: 2, max: 2 },
+          payment: expect.objectContaining({
+            satoshis: 5,
+            serverIdentityKey: 'server-key',
+            clientIdentityKey: 'client-key'
+          })
+        })
+        expect(err.details.errors).toHaveLength(2)
+        expect(err.details.errors[0]).toEqual(expect.objectContaining({
+          attempt: 1,
+          message: 'payment attempt 1 failed'
+        }))
+        expect(err.details.errors[1]).toEqual(expect.objectContaining({
+          attempt: 2,
+          message: 'payment attempt 2 failed'
+        }))
+        expect(typeof err.details.errors[0].timestamp).toBe('string')
+        expect(err.cause).toBe(secondError)
+        throw error
+      }
+    })()).rejects.toThrow('Paid request to https://api.example.com/resource failed after 2/2 attempts. Sent 5 satoshis to server-key.')
+
+    expect(paymentContext.attempts).toBe(2)
+    expect(paymentContext.errors).toHaveLength(2)
+  })
+})