mppx 0.8.14 → 0.8.17

package/src/tempo/session/client/Transports.test.ts

@@ -310,6 +310,28 @@ describe('HttpManagement', () => {
       expect(restoreCumulative).toHaveBeenCalledWith(channelId, 5n)
     })
 
+    test('retryHttpPaymentRequired restores cumulative authorization when retry throws', async () => {
+      const entry = channel({ cumulativeAmount: 5n })
+      const restoreCumulative = vi.fn()
+
+      await expect(
+        retryHttpPaymentRequired({
+          createSessionCredential: async () => 'voucher-credential',
+          fetch: async () => {
+            throw new Error('network failed')
+          },
+          getChannel: () => entry,
+          input: 'https://example.test/resource',
+          response: response402(challenge(snapshot())),
+          restoreCumulative,
+          setChallenge() {},
+          topUpIfNeeded: async () => {},
+        }),
+      ).rejects.toThrow('network failed')
+
+      expect(restoreCumulative).toHaveBeenCalledWith(channelId, 5n)
+    })
+
     test('closeHttpSession posts a close credential and parses the receipt', async () => {
       const entry = channel()
       const createSessionCredential = vi.fn(async (_challenge, context: SessionContext) => {

package/src/tempo/session/client/Transports.ts

@@ -47,6 +47,8 @@ export const WebSocketReadyState = {
 /** Client-side close code used for payment protocol errors. */
 export const ClientWebSocketProtocolErrorCloseCode = 3008
 
+const webSocketChallengeRefreshWindowMs = 5_000
+
 type EventType = 'close' | 'error' | 'message' | 'open'
 type ManagedEventMap = {
   close: { code: number; reason: string; type: 'close'; wasClean: boolean }
@@ -489,7 +491,7 @@ export type RetryHttpPaymentRequiredParameters = {
   /** Failed HTTP response that may contain a session challenge. */
   response: Response
   /** Restores local cumulative authorization if the voucher retry fails. */
-  restoreCumulative(channelId: Hex.Hex, cumulativeAmount: bigint): void
+  restoreCumulative(channelId: Hex.Hex, cumulativeAmount: bigint): void | Promise<void>
   /** Stores the selected follow-up challenge on the manager. */
   setChallenge(challenge: TempoSessionChallenge): void
   /** Performs automatic top-up before the voucher retry when deposit is insufficient. */
@@ -692,18 +694,25 @@ export async function retryHttpPaymentRequired(
     currentChannel.cumulativeAmount > requiredCumulative
       ? currentChannel.cumulativeAmount
       : requiredCumulative
-  const credential = await parameters.createSessionCredential(challenge, {
-    action: 'voucher',
-    channelId: snapshot.channelId,
-    descriptor: currentChannel.descriptor,
-    cumulativeAmountRaw: cumulativeAmount.toString(),
-  })
-  const retry = await parameters.fetch(
-    parameters.input,
-    requestInitWithAuthorization(parameters.input, parameters.init, credential),
-  )
+  const restore = () => parameters.restoreCumulative(snapshot.channelId, cumulativeBeforeVoucher)
+  let retry: Response
+  try {
+    const credential = await parameters.createSessionCredential(challenge, {
+      action: 'voucher',
+      channelId: snapshot.channelId,
+      descriptor: currentChannel.descriptor,
+      cumulativeAmountRaw: cumulativeAmount.toString(),
+    })
+    retry = await parameters.fetch(
+      parameters.input,
+      requestInitWithAuthorization(parameters.input, parameters.init, credential),
+    )
+  } catch (error) {
+    await restore()
+    throw error
+  }
   if (!retry.ok && !retry.headers.get(Constants.Headers.paymentReceipt)) {
-    parameters.restoreCumulative(snapshot.channelId, cumulativeBeforeVoucher)
+    await restore()
   }
   return retry
 }
@@ -1110,6 +1119,15 @@ export type PrepareWebSocketSessionParameters = {
   signal?: AbortSignal | undefined
 }
 
+/** Inputs for probing a paid WebSocket endpoint without creating a credential. */
+export type ProbeWebSocketSessionParameters = Omit<
+  PrepareWebSocketSessionParameters,
+  'createSessionCredential'
+>
+
+/** Result of resolving the current payment challenge for a WebSocket endpoint. */
+export type ProbedWebSocketSession = Omit<PreparedWebSocketSession, 'credential'>
+
 /** Result of the HTTP probe and opening credential creation for a WebSocket session. */
 export type PreparedWebSocketSession = {
   /** Selected tempo/session challenge from the HTTP probe. */
@@ -1173,6 +1191,8 @@ export type OpenWebSocketSessionParameters = {
   getChannel(): ChannelEntry | null
   /** Stores the active socket state in the manager. */
   setSocketSession(session: ActiveSocketSession): void
+  /** Fetches the route's current challenge after the active one expires. */
+  refreshChallenge(): Promise<TempoSessionChallenge>
   /** Validates a cumulative amount against local client policy. */
   assertVoucherWithinLocalLimit(cumulativeAmount: bigint): void
   /** Applies an incoming receipt to manager state. */
@@ -1213,10 +1233,10 @@ export type ValidateSocketPaymentReceiptParameters = ExpectedSocketReceiptParame
   expectedCloseAmount: string | null
 }
 
-/** Probes a WebSocket endpoint over HTTP and creates the opening credential. */
-export async function prepareWebSocketSession(
-  parameters: PrepareWebSocketSessionParameters,
-): Promise<PreparedWebSocketSession> {
+/** Probes a WebSocket endpoint over HTTP and returns its current session challenge. */
+export async function probeWebSocketSession(
+  parameters: ProbeWebSocketSessionParameters,
+): Promise<ProbedWebSocketSession> {
   const wsUrl = new URL(parameters.input.toString())
   const httpUrl = webSocketProbeUrl(wsUrl)
   parameters.onProbeUrl?.(httpUrl)
@@ -1239,12 +1259,22 @@ export async function prepareWebSocketSession(
 
   return {
     challenge,
-    credential: await parameters.createSessionCredential(challenge, {}),
     httpUrl,
     wsUrl,
   }
 }
 
+/** Probes a WebSocket endpoint over HTTP and creates the opening credential. */
+export async function prepareWebSocketSession(
+  parameters: PrepareWebSocketSessionParameters,
+): Promise<PreparedWebSocketSession> {
+  const probed = await probeWebSocketSession(parameters)
+  return {
+    ...probed,
+    credential: await parameters.createSessionCredential(probed.challenge, {}),
+  }
+}
+
 /** Creates the initial runtime state for a paid WebSocket from its opening credential. */
 export function createActiveSocketSession(
   parameters: CreateActiveSocketSessionParameters,
@@ -1452,9 +1482,18 @@ async function handleNeedVoucher(
   event: NeedVoucherEvent,
 ) {
   try {
+    let challenge = parameters.driver.challenge
+    if (
+      challenge.expires &&
+      new Date(challenge.expires).getTime() <= Date.now() + webSocketChallengeRefreshWindowMs
+    ) {
+      challenge = await parameters.driver.refreshChallenge()
+      parameters.driver.challenge = challenge
+      parameters.socketState.challenge = challenge
+    }
     const resolution = await resolveNeedVoucherContext({
       assertVoucherWithinLocalLimit: parameters.driver.assertVoucherWithinLocalLimit,
-      challenge: parameters.driver.challenge,
+      challenge,
       event,
       expectedChannelId: parameters.socketState.channelId,
       getChannel: parameters.driver.getChannel,
@@ -1469,10 +1508,7 @@ async function handleNeedVoucher(
       )
       return
     }
-    const voucher = await parameters.driver.createSessionCredential(
-      parameters.driver.challenge,
-      resolution.context,
-    )
+    const voucher = await parameters.driver.createSessionCredential(challenge, resolution.context)
     parameters.rawSocket.send(Ws.formatAuthorizationMessage(voucher))
   } catch (error) {
     parameters.failSocketFlow(

package/src/tempo/session/precompile/Chain.ts

@@ -522,6 +522,55 @@ async function simulateTempoTransaction(client: Client, request: unknown) {
   await call(client, request as never)
 }
 
+/** Simulates an unsponsored client-signed session transaction without broadcasting it. */
+export async function simulateCredentialTransaction(parameters: {
+  /** viem client used for the read-only execution simulation. */
+  client: TransactionClient
+  /** Fee-payer configuration for the eventual broadcast. Sponsored transactions are simulated after completion. */
+  feePayer?: Account | true | undefined
+  /** Parsed client-signed Tempo transaction. */
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}): Promise<void> {
+  if (parameters.feePayer) return
+  await simulateTempoTransaction(
+    parameters.client,
+    FeePayer.simulationTransaction(parameters.transaction, { feePayer: false }),
+  )
+}
+
+function validateCredentialSponsorship(parameters: {
+  allowedFeeTokens: readonly Address[]
+  challengeExpires?: string | undefined
+  chainId: number
+  details: Record<string, string>
+  feePayer?: Account | true | undefined
+  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}) {
+  const {
+    allowedFeeTokens,
+    challengeExpires,
+    chainId,
+    details,
+    feePayer,
+    feePayerPolicy,
+    transaction,
+  } = parameters
+  if (!feePayer || feePayer === true) return
+  FeePayer.prepareSponsoredTransaction({
+    account: feePayer,
+    allowedFeeTokens,
+    challengeExpires,
+    chainId,
+    details,
+    policy: feePayerPolicy,
+    transaction: {
+      ...transaction,
+      ...(allowedFeeTokens[0] ? { feeToken: transaction.feeToken ?? allowedFeeTokens[0] } : {}),
+    },
+  })
+}
+
 async function signTempoTransaction(client: Client, transaction: unknown): Promise<Hex> {
   return (await signTransaction(client, transaction as never)) as Hex
 }
@@ -874,10 +923,25 @@ export type BroadcastOpenTransactionParameters = {
   serializedTransaction: Hex
 }
 
-/** Broadcast and validate a client-signed TIP-1034 open transaction. */
-export async function broadcastOpenTransaction(
-  parameters: BroadcastOpenTransactionParameters,
-): Promise<BroadcastOpenTransactionResult> {
+/** Inputs for validating a client-signed TIP-1034 open transaction without broadcasting it. */
+export type ValidateOpenCredentialTransactionParameters = Omit<
+  BroadcastOpenTransactionParameters,
+  'beforeBroadcast' | 'client'
+>
+
+/** Validated fields recovered from a client-signed TIP-1034 open transaction. */
+export type ValidatedOpenCredentialTransaction = Omit<
+  BroadcastOpenTransactionResult,
+  'state' | 'txHash'
+> & {
+  /** Parsed client-signed transaction, reused by simulation and broadcast. */
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}
+
+/** Validates the immutable fields of a client-signed TIP-1034 open transaction. */
+export function validateOpenCredentialTransaction(
+  parameters: ValidateOpenCredentialTransactionParameters,
+): ValidatedOpenCredentialTransaction {
   const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
     escrowContract: parameters.escrowContract,
     feePayer: parameters.feePayer,
@@ -909,6 +973,19 @@ export async function broadcastOpenTransaction(
     channelId: parameters.expectedChannelId,
   })
   if (parameters.feePayer) assertSenderSigned(transaction)
+  validateCredentialSponsorship({
+    allowedFeeTokens: [parameters.expectedCurrency],
+    challengeExpires: parameters.challengeExpires,
+    chainId: parameters.chainId,
+    details: {
+      channelId: parameters.expectedChannelId,
+      currency: parameters.expectedCurrency,
+      recipient: parameters.expectedPayee,
+    },
+    feePayer: parameters.feePayer,
+    feePayerPolicy: parameters.feePayerPolicy,
+    transaction,
+  })
   const expiringNonceHash = ChannelUtils.computeExpiringNonceHash(
     ChannelUtils.transactionForExpiringNonceHash({
       feePayer: parameters.feePayer,
@@ -920,10 +997,19 @@ export async function broadcastOpenTransaction(
     throw new VerificationFailedError({
       reason: 'credential expiringNonceHash does not match transaction',
     })
+  return { descriptor, expiringNonceHash, openDeposit: open.deposit, transaction }
+}
+
+/** Broadcast and validate a client-signed TIP-1034 open transaction. */
+export async function broadcastOpenTransaction(
+  parameters: BroadcastOpenTransactionParameters,
+): Promise<BroadcastOpenTransactionResult> {
+  const { descriptor, expiringNonceHash, openDeposit, transaction } =
+    validateOpenCredentialTransaction(parameters)
   await parameters.beforeBroadcast?.({
     descriptor,
     expiringNonceHash,
-    openDeposit: open.deposit,
+    openDeposit,
   })
   const receipt = await sendCredentialTransaction({
     challengeExpires: parameters.challengeExpires,
@@ -952,7 +1038,7 @@ export async function broadcastOpenTransaction(
     emittedExpiringNonceHash: opened.expiringNonceHash,
     escrow: parameters.escrowContract,
     expectedChannelId: parameters.expectedChannelId,
-    openDeposit: open.deposit,
+    openDeposit,
   })
   const chainChannel = await readbackWithRetry(() =>
     getChannel(parameters.client, descriptor, parameters.escrowContract, receipt.blockNumber),
@@ -964,7 +1050,7 @@ export async function broadcastOpenTransaction(
     descriptor,
     state,
     expiringNonceHash: opened.expiringNonceHash,
-    openDeposit: open.deposit,
+    openDeposit,
   }
 }
 
@@ -1004,10 +1090,22 @@ export type BroadcastTopUpTransactionParameters = {
   serializedTransaction: Hex
 }
 
-/** Broadcast and validate a client-signed TIP-1034 top-up transaction. */
-export async function broadcastTopUpTransaction(
-  parameters: BroadcastTopUpTransactionParameters,
-): Promise<BroadcastTopUpTransactionResult> {
+/** Inputs for validating a client-signed TIP-1034 top-up transaction without broadcasting it. */
+export type ValidateTopUpCredentialTransactionParameters = Omit<
+  BroadcastTopUpTransactionParameters,
+  'client'
+>
+
+/** Validated fields recovered from a client-signed TIP-1034 top-up transaction. */
+export type ValidatedTopUpCredentialTransaction = {
+  /** Parsed client-signed transaction, reused by simulation and broadcast. */
+  transaction: ReturnType<(typeof Transaction)['deserialize']>
+}
+
+/** Validates the immutable fields of a client-signed TIP-1034 top-up transaction. */
+export function validateTopUpCredentialTransaction(
+  parameters: ValidateTopUpCredentialTransactionParameters,
+): ValidatedTopUpCredentialTransaction {
   const { transaction, call, prefixCalls } = parsePrecompileCredentialTransaction({
     escrowContract: parameters.escrowContract,
     feePayer: parameters.feePayer,
@@ -1027,6 +1125,28 @@ export async function broadcastTopUpTransaction(
     label: 'topUp',
     prefixCalls,
   })
+  if (parameters.feePayer) assertSenderSigned(transaction)
+  validateCredentialSponsorship({
+    allowedFeeTokens: [parameters.expectedCurrency],
+    challengeExpires: parameters.challengeExpires,
+    chainId: parameters.chainId,
+    details: {
+      additionalDeposit: parameters.additionalDeposit.toString(),
+      channelId: parameters.expectedChannelId,
+      currency: parameters.expectedCurrency,
+    },
+    feePayer: parameters.feePayer,
+    feePayerPolicy: parameters.feePayerPolicy,
+    transaction,
+  })
+  return { transaction }
+}
+
+/** Broadcast and validate a client-signed TIP-1034 top-up transaction. */
+export async function broadcastTopUpTransaction(
+  parameters: BroadcastTopUpTransactionParameters,
+): Promise<BroadcastTopUpTransactionResult> {
+  const { transaction } = validateTopUpCredentialTransaction(parameters)
   const receipt = await sendCredentialTransaction({
     challengeExpires: parameters.challengeExpires,
     chainId: parameters.chainId,

package/src/tempo/session/server/ChannelStore.ts

@@ -240,6 +240,18 @@ export type VerifyAndAcceptVoucherParameters = {
   voucher: SignedVoucher
 }
 
+/** Inputs for validating a cumulative voucher without recording it. */
+export type ValidateVoucherParameters = Omit<
+  VerifyAndAcceptVoucherParameters,
+  'challenge' | 'store'
+>
+
+/** Result of validating a cumulative voucher against persisted channel state. */
+export type VoucherValidation = {
+  /** Whether the voucher was already accepted at the same cumulative amount. */
+  alreadyAccepted: boolean
+}
+
 /** Channel backend-specific fields. */
 export type BackendState = CompatibilityBackendState | PrecompileBackendState
 
@@ -520,12 +532,11 @@ export async function loadPrecompileChannel(
   return channel
 }
 
-/** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
-export async function verifyAndAcceptVoucher(
-  parameters: VerifyAndAcceptVoucherParameters,
-): Promise<SessionReceipt> {
-  const { store, minVoucherDelta, challenge, channel, voucher, channelState, methodDetails } =
-    parameters
+/** Verifies a cumulative voucher without changing persisted channel state. */
+export async function validateVoucher(
+  parameters: ValidateVoucherParameters,
+): Promise<VoucherValidation> {
+  const { minVoucherDelta, channel, voucher, channelState, methodDetails } = parameters
 
   validateChannelState(channelState)
   if (voucher.cumulativeAmount > channelState.deposit)
@@ -546,7 +557,22 @@ export async function verifyAndAcceptVoucher(
     throw new VerificationFailedError({
       reason: 'voucher cumulativeAmount is below on-chain settled amount',
     })
-  if (voucher.cumulativeAmount === channel.highestVoucherAmount)
+  if (voucher.cumulativeAmount === channel.highestVoucherAmount) return { alreadyAccepted: true }
+  const delta = voucher.cumulativeAmount - channel.highestVoucherAmount
+  if (delta < minVoucherDelta)
+    throw new DeltaTooSmallError({
+      reason: `voucher delta ${delta} below minimum ${minVoucherDelta}`,
+    })
+  return { alreadyAccepted: false }
+}
+
+/** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
+export async function verifyAndAcceptVoucher(
+  parameters: VerifyAndAcceptVoucherParameters,
+): Promise<SessionReceipt> {
+  const { store, challenge, channel, voucher, channelState } = parameters
+  const validation = await validateVoucher(parameters)
+  if (validation.alreadyAccepted)
     return createSessionReceipt({
       challengeId: challenge.id,
       channelId: voucher.channelId,
@@ -554,11 +580,6 @@ export async function verifyAndAcceptVoucher(
       spent: channel.spent,
       units: channel.units,
     })
-  const delta = voucher.cumulativeAmount - channel.highestVoucherAmount
-  if (delta < minVoucherDelta)
-    throw new DeltaTooSmallError({
-      reason: `voucher delta ${delta} below minimum ${minVoucherDelta}`,
-    })
   const updated = await store.updateChannel(voucher.channelId, (current) =>
     acceptVoucherStateUpdate({ channelState, current, voucher }),
   )

package/src/tempo/session/server/CredentialVerification.test.ts

@@ -9,11 +9,11 @@ import * as Voucher from '../precompile/Voucher.js'
 import * as ChannelStore from './ChannelStore.js'
 import {
   assertOpenCredentialCoversRequest,
+  broadcastCredentialPayload,
   requireSessionCredentialAction,
   requireSessionCredentialPayload,
   requireSessionCredentialPayloadHeader,
   validateChannelDescriptor,
-  verifyCredentialPayload,
 } from './CredentialVerification.js'
 
 describe('SessionCredentialGuards', () => {
@@ -190,7 +190,7 @@ describe('SessionCredentialGuards', () => {
     })
   })
 
-  describe('verifyCredentialPayload', () => {
+  describe('broadcastCredentialPayload', () => {
     const escrow = '0x4D50500000000000000000000000000000000000' as Address
     const testChainId = chainIds.testnet
     const computedChannelId = Channel.computeId({ ...descriptor, chainId: testChainId, escrow })
@@ -246,7 +246,7 @@ describe('SessionCredentialGuards', () => {
       const verifyVoucher = vi.spyOn(Voucher, 'verifyVoucher').mockResolvedValue(true)
 
       await expect(
-        verifyCredentialPayload({
+        broadcastCredentialPayload({
           challenge,
           channelStateTtl: 60_000,
           chainId: testChainId,
@@ -274,7 +274,7 @@ describe('SessionCredentialGuards', () => {
       const verifyVoucher = vi.spyOn(Voucher, 'verifyVoucher').mockResolvedValue(true)
 
       await expect(
-        verifyCredentialPayload({
+        broadcastCredentialPayload({
           challenge,
           channelStateTtl: 60_000,
           chainId: testChainId,