mppx 0.8.14 → 0.8.15

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

@@ -113,6 +113,20 @@ function makeChannelStore(seed: readonly ChannelEntry[] = []) {
   return { store, set, delete: remove, map }
 }
 
+function makeDurableChannelStore() {
+  const backend = new Map<string, string>()
+  const store = createJsonChannelStore({
+    get: (key) => backend.get(key),
+    set: (key, value) => {
+      backend.set(key, value)
+    },
+    delete: (key) => {
+      backend.delete(key)
+    },
+  })
+  return { backend, store }
+}
+
 function makeChallenge(overrides: Record<string, unknown> = {}): Challenge.Challenge {
   return Challenge.from({
     id: challengeId,
@@ -657,7 +671,7 @@ describe('Session', () => {
       })
     })
 
-    test('rolls back an optimistic open when a replacement challenge does not reference it', async () => {
+    test('rolls back optimistic opens across replacement challenges', async () => {
       const { store, delete: remove } = makeChannelStore()
       const postedPayloads: SessionCredentialPayload[] = []
       const challenge = (feePayer: boolean) =>
@@ -669,6 +683,8 @@ describe('Session', () => {
             feePayer,
           },
         })
+      const original = challenge(true)
+      const replacement = challenge(false)
       let openCount = 0
       const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
         const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
@@ -677,10 +693,11 @@ describe('Session', () => {
           : undefined
         if (payload) postedPayloads.push(payload)
 
-        if (!payload) return Promise.resolve(make402Response(challenge(true)))
+        if (!payload) return Promise.resolve(make402Response(original))
         if (payload.action === 'open') {
           openCount++
-          if (openCount === 1) return Promise.resolve(make402Response(challenge(false)))
+          if (openCount === 1) return Promise.resolve(make402Response(replacement))
+          if (openCount === 2) return Promise.resolve(make402Response(original))
           return Promise.resolve(makeOkResponse())
         }
         return Promise.resolve(new Response('unexpected voucher', { status: 500 }))
@@ -696,12 +713,33 @@ describe('Session', () => {
       const response = await s.fetch('https://api.example.com/data')
 
       expect(response.status).toBe(200)
-      // A replacement challenge with no snapshot means the server did not
-      // acknowledge the optimistic open, so the next credential must open again.
-      expect(postedPayloads.map((payload) => payload.action)).toEqual(['open', 'open'])
-      expect(postedPayloads[0]?.channelId).not.toBe(postedPayloads[1]?.channelId)
-      expect(remove).toHaveBeenCalledOnce()
-      expect(s.channelId).toBe(postedPayloads[1]?.channelId)
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['open', 'open', 'open'])
+      expect(new Set(postedPayloads.map((payload) => payload.channelId)).size).toBe(3)
+      expect(remove).toHaveBeenCalledTimes(2)
+      expect(s.channelId).toBe(postedPayloads[2]?.channelId)
+    })
+
+    test('reuses prepared voucher state when an identical challenge succeeds', async () => {
+      const vouchers: Extract<SessionCredentialPayload, { action: 'voucher' }>[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization) return Promise.resolve(make402Response())
+        const payload = Credential.deserialize<SessionCredentialPayload>(authorization).payload
+        if (payload.action !== 'voucher') throw new Error('expected voucher')
+        vouchers.push(payload)
+        return Promise.resolve(vouchers.length === 1 ? make402Response() : makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        channelStore: makeChannelStore([channelEntry()]).store,
+      })
+
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(200)
+      expect(vouchers.map((voucher) => voucher.cumulativeAmount)).toEqual(['2000000', '2000000'])
+      expect(s.cumulative).toBe(2_000_000n)
+      expect(s.state.status).toBe('active')
     })
 
     test('does not bootstrap when disabled', async () => {
@@ -989,6 +1027,60 @@ describe('Session', () => {
       })
     })
 
+    test('preserves a snapshot-acknowledged open when its voucher fails', async () => {
+      const { backend, store } = makeDurableChannelStore()
+      const payloads: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization)
+          return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '10000000' })))
+        const payload = Credential.deserialize<SessionCredentialPayload>(authorization).payload
+        payloads.push(payload)
+        if (payload.action !== 'open')
+          return Promise.resolve(new Response('failed', { status: 500 }))
+        return Promise.resolve(
+          make402Response(
+            makeChallenge({
+              methodDetails: {
+                escrowContract: tip20ChannelEscrow,
+                chainId: 4217,
+                sessionProtocol: Constants.SessionProtocols.v2,
+                sessionSnapshot: {
+                  acceptedCumulative: '1000000',
+                  chainId: 4217,
+                  channelId: payload.channelId,
+                  deposit: '10000000',
+                  descriptor: payload.descriptor,
+                  escrow: tip20ChannelEscrow,
+                  requiredCumulative: '2000000',
+                  settled: '0',
+                  spent: '1000000',
+                  units: 1,
+                },
+              },
+            }),
+          ),
+        )
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+        channelStore: store,
+      })
+
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(500)
+      expect(payloads.map((payload) => payload.action)).toEqual(['open', 'voucher'])
+      expect(s.channelId).toBe(payloads[0]?.channelId)
+      expect(s.cumulative).toBe(1_000_000n)
+      expect(JSON.parse([...backend.values()][0]!)).toMatchObject({
+        channelId: payloads[0]?.channelId,
+        cumulativeAmount: '1000000',
+        opened: true,
+      })
+    })
+
     test('preemptively top-ups before signing an HTTP voucher that exceeds deposit', async () => {
       const postedPayloads: SessionCredentialPayload[] = []
       let challengeCount = 0
@@ -1055,6 +1147,121 @@ describe('Session', () => {
         units: 2,
       })
     })
+
+    test('preserves a successful automatic top-up when the paid retry fails', async () => {
+      const { map, store } = makeChannelStore()
+      const payloads: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization)
+          return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '1000000' })))
+        const payload = Credential.deserialize<SessionCredentialPayload>(authorization).payload
+        payloads.push(payload)
+        if (payload.action === 'open')
+          return Promise.resolve(
+            new Response('ok', {
+              headers: {
+                [Constants.Headers.paymentReceipt]: serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: 1_000_000n,
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: 1_000_000n,
+                    units: 3,
+                  }),
+                ),
+              },
+            }),
+          )
+        if (payload.action === 'topUp') return Promise.resolve(new Response(null, { status: 204 }))
+        return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '1000000' })))
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '3',
+        channelStore: store,
+      })
+
+      await s.fetch('https://api.example.com/data')
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(402)
+
+      expect(payloads.map((payload) => payload.action)).toEqual([
+        'open',
+        'topUp',
+        'voucher',
+        'voucher',
+        'voucher',
+      ])
+      expect(s.cumulative).toBe(1_000_000n)
+      expect(s.state).toMatchObject({ status: 'active', deposit: '2000000', units: 3 })
+      expect([...map.values()][0]).toMatchObject({
+        cumulativeAmount: 1_000_000n,
+        deposit: 2_000_000n,
+      })
+    })
+
+    test('preserves a topped-up resumed channel in durable storage after payment fails', async () => {
+      const { store } = makeDurableChannelStore()
+      const seeded = channelEntry({ cumulativeAmount: 1_000_000n, deposit: 1_000_000n })
+      await store.set(seeded)
+      const payloads: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization)
+          return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '1000000' })))
+        const payload = Credential.deserialize<SessionCredentialPayload>(authorization).payload
+        payloads.push(payload)
+        return Promise.resolve(
+          payload.action === 'topUp'
+            ? new Response(null, { status: 204 })
+            : new Response('failed', { status: 500 }),
+        )
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '3',
+        channelStore: store,
+      })
+
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(500)
+
+      expect(payloads.map((payload) => payload.action)).toEqual(['topUp', 'voucher'])
+      expect(s.cumulative).toBe(1_000_000n)
+      expect(s.state).toMatchObject({ status: 'active', deposit: '2000000' })
+      await expect(store.get(entryKey(seeded))).resolves.toMatchObject({
+        cumulativeAmount: 1_000_000n,
+        deposit: 2_000_000n,
+        opened: true,
+      })
+    })
+
+    test.each([
+      ['new', false],
+      ['replacement', true],
+    ] as const)('removes a failed %s durable channel', async (_kind, seeded) => {
+      const { backend, store } = makeDurableChannelStore()
+      if (seeded) await store.set(channelEntry())
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        return Promise.resolve(
+          authorization ? new Response('failed', { status: 500 }) : make402Response(),
+        )
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        channelStore: store,
+      })
+
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(500)
+      expect(s.channelId).toBeUndefined()
+      expect(backend.size).toBe(0)
+    })
   })
 
   describe('.topUp()', () => {

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

@@ -58,6 +58,7 @@ import { applyTopUpResult, resolveManualTopUp, type TopUpRequirement } from './T
 import {
   openWebSocketSession,
   prepareWebSocketSession,
+  probeWebSocketSession,
   type WebSocketDriverOptions,
 } from './Transports.js'
 
@@ -243,11 +244,14 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
 
   /** Removes a failed channel from candidacy for the rest of this manager's life. */
   async function ignoreChannel(entry: ChannelEntry) {
+    const key = entryKey(entry)
     ignoredChannelIds.add(entry.channelId)
-    await Promise.resolve(backing.delete(entryKey(entry))).catch(() => undefined)
+    channelUse?.seenExisting.delete(key)
+    if (channelUse?.resumed === entry) channelUse.resumed = undefined
+    await Promise.resolve(backing.delete(key)).catch(() => undefined)
   }
 
-  async function rollbackCreatedChannelsForRetry() {
+  async function rollbackCreatedChannels() {
     const use = channelUse
     if (!use?.created.size) return
     for (const [key, entry] of use.created) {
@@ -255,19 +259,31 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       await Promise.resolve(backing.delete(key)).catch(() => undefined)
     }
     use.created.clear()
-    restoreRuntime(use.previous)
+    await restoreRuntime(use.committed ?? use.previous)
   }
 
-  function referencesCreatedChannel(challenge: Challenge.Challenge): boolean {
+  /** Commits a newly created channel once an authoritative server snapshot references it. */
+  function commitReferencedChannel(challenge: Challenge.Challenge): boolean {
     const snapshot = Constants.getMethodDetail<{ channelId?: unknown }>(
       challenge.request.methodDetails,
       Constants.MethodDetailKeys.sessionSnapshot,
     )
     if (typeof snapshot?.channelId !== 'string') return false
     const use = channelUse
-    if (!use?.created.size) return false
-    for (const entry of use.created.values()) {
-      if (entry.channelId.toLowerCase() === snapshot.channelId.toLowerCase()) return true
+    if (!use?.created.size || !runtime.channel) return false
+    for (const [key, entry] of use.created) {
+      if (
+        entry.channelId.toLowerCase() !== snapshot.channelId.toLowerCase() ||
+        runtime.channel.channelId.toLowerCase() !== snapshot.channelId.toLowerCase()
+      )
+        continue
+      use.created.delete(key)
+      use.committed = captureRuntimeStateSnapshot({
+        channel: runtime.channel,
+        spent: runtime.spent,
+        state: runtime.state,
+      })
+      return true
     }
     return false
   }
@@ -276,6 +292,14 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     return dispatchSessionEvent(runtime, event)
   }
 
+  function activeUnits() {
+    const state =
+      runtime.state.status === 'active'
+        ? runtime.state
+        : (channelUse?.committed?.state ?? channelUse?.previous.state)
+    return state?.status === 'active' ? state.units : 0
+  }
+
   function commitDurableTopUp(entry: ChannelEntry) {
     const use = channelUse
     const baseline = use?.committed?.channel?.entry ?? use?.resumed
@@ -312,7 +336,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
           challengeId: runtime.lastChallenge.id,
           entry,
           spent: runtime.spent.toString(),
-          units: 0,
+          units: activeUnits(),
         })
       }
       commitDurableTopUp(entry)
@@ -332,11 +356,15 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       const use = channelUse
       const isRepeatedRetryChallenge =
         use && use.challengesReceived > 0 && challenge.id === runtime.lastChallenge?.id
-      if (!referencesCreatedChannel(challenge)) {
-        if (use?.created.size) await rollbackCreatedChannelsForRetry()
-        else if (isRepeatedRetryChallenge) restoreRuntime(use.previous)
-      }
+      const isSameRetryChallenge =
+        isRepeatedRetryChallenge &&
+        Challenge.serialize(challenge) === Challenge.serialize(runtime.lastChallenge!)
       if (use) use.challengesReceived++
+      if (isSameRetryChallenge) return undefined
+      if (!commitReferencedChannel(challenge)) {
+        if (use?.created.size) await rollbackCreatedChannels()
+        else if (isRepeatedRetryChallenge) await restoreRuntime(use.committed ?? use.previous)
+      }
       runtime.lastChallenge = challenge
       dispatch({ type: 'challengeReceived', challengeId: challenge.id })
       return undefined
@@ -558,7 +586,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         challengeId: runtime.lastChallenge.id,
         entry: applied.channel,
         spent: runtime.spent.toString(),
-        units: runtime.state.status === 'active' ? runtime.state.units : 0,
+        units: activeUnits(),
       })
       commitDurableTopUp(applied.channel)
     }
@@ -589,7 +617,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     })
   }
 
-  function restoreCumulative(channelId: Hex.Hex, cumulativeAmount: bigint) {
+  async function restoreCumulative(channelId: Hex.Hex, cumulativeAmount: bigint) {
     const restored = restoreCumulativeAuthorization({
       channel: runtime.channel,
       channelId,
@@ -606,14 +634,16 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         spent: restored.spent,
         units: restored.units,
       })
+      await backing.set(runtime.channel)
     }
   }
 
-  function restoreRuntime(snapshot: RuntimeSnapshot) {
+  async function restoreRuntime(snapshot: RuntimeSnapshot) {
     const restored = restoreRuntimeStateSnapshot(snapshot, runtime.channel)
     runtime.channel = restored.channel
     runtime.spent = restored.spent
     runtime.state = restored.state
+    if (runtime.channel?.opened) await backing.set(runtime.channel)
   }
 
   function toPaymentResponse(response: Response): PaymentResponse {
@@ -679,7 +709,8 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         try {
           response = await wrappedFetch(input, effectiveInit)
         } catch (error) {
-          restoreRuntime(use.committed ?? previous)
+          if (use.created.size) await rollbackCreatedChannels()
+          else await restoreRuntime(use.committed ?? previous)
           if (await retryWithoutResumed()) continue
           throw error
         }
@@ -706,7 +737,8 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
           }
         }
         if (!attemptedHttpManagement && !paymentResponse.ok && !paymentResponse.receipt) {
-          restoreRuntime(use.committed ?? previous)
+          if (use.created.size) await rollbackCreatedChannels()
+          else await restoreRuntime(use.committed ?? previous)
           if (await retryWithoutResumed()) continue
           return paymentResponse
         }
@@ -838,6 +870,20 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         setSocketSession(session) {
           runtime.socketSession = session
         },
+        async refreshChallenge() {
+          const refreshed = await probeWebSocketSession({
+            fetch: config.fetch,
+            input: httpUrl,
+            probeInit: requestInitWithSessionHint(
+              httpUrl,
+              signalInit,
+              runtime.channel?.opened ? runtime.channel.channelId : undefined,
+            ),
+            signal: init?.signal,
+          })
+          runtime.lastChallenge = refreshed.challenge
+          return refreshed.challenge
+        },
         assertVoucherWithinLocalLimit,
         acceptReceipt: updateSpentFromReceipt,
         rejectCloseReady: receipts.rejectCloseReady,

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(