mppx 0.8.9 → 0.8.12

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

@@ -3,7 +3,8 @@ import { privateKeyToAccount } from 'viem/accounts'
 import { Account as TempoAccount, Secp256k1, Transaction } from 'viem/tempo'
 import { describe, expect, test } from 'vp/test'
 
-import type { Challenge } from '../../../Challenge.js'
+import { serialize as serializeChallenge, type Challenge } from '../../../Challenge.js'
+import * as Fetch from '../../../client/internal/Fetch.js'
 import * as Constants from '../../../Constants.js'
 import * as Credential from '../../../Credential.js'
 import * as z from '../../../zod.js'
@@ -13,6 +14,7 @@ import { escrowAbi } from '../precompile/escrow.abi.js'
 import { tip20ChannelEscrow } from '../precompile/Protocol.js'
 import * as Types from '../precompile/Protocol.js'
 import * as Voucher from '../precompile/Voucher.js'
+import { createChannelStore } from './ChannelStore.js'
 import { session } from './Session.js'
 
 const account = privateKeyToAccount(
@@ -126,6 +128,86 @@ describe('precompile client session', () => {
     ).toBe(false)
   })
 
+  test('drives paid SSE responses with a supplied credential', async () => {
+    const challenge = makeChallenge({
+      suggestedDeposit: '100',
+      methodDetails: {
+        chainId,
+        escrowContract: tip20ChannelEscrow,
+        sessionProtocol: Constants.SessionProtocols.v2,
+      },
+    })
+    const channelStore = createChannelStore()
+    const parameters = {
+      account,
+      channelStore,
+      decimals: 0,
+      getClient: () => client,
+      maxDeposit: '300',
+    } as const
+    // The response handler must follow the credential selected by `onChallenge`.
+    const externalCredential = await session(parameters).createCredential({
+      challenge,
+      context: {},
+    })
+    let useExternalCredential = true
+    const actions: Types.SessionCredentialPayload['action'][] = []
+    const rawFetch: typeof globalThis.fetch = async (_input, init) => {
+      const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+      if (!authorization)
+        return new Response(null, {
+          status: 402,
+          headers: { [Constants.Headers.wwwAuthenticate]: serializeChallenge(challenge) },
+        })
+
+      const payload = deserialize(authorization)
+      actions.push(payload.action)
+      if (init?.method === 'POST' || payload.action === 'open')
+        return new Response(null, { status: 204 })
+      if (payload.action !== 'voucher') throw new Error('expected voucher')
+
+      const receipt = Types.createSessionReceipt({
+        acceptedCumulative: 200n,
+        challengeId: challenge.id,
+        channelId: payload.channelId,
+        spent: 200n,
+      })
+      return new Response(
+        [
+          Types.formatMessageEvent('first'),
+          Types.formatNeedVoucherEvent({
+            acceptedCumulative: '100',
+            channelId: payload.channelId,
+            deposit: '100',
+            requiredCumulative: '200',
+          }),
+          Types.formatMessageEvent('second'),
+          Types.formatReceiptEvent(receipt),
+        ].join(''),
+        { headers: { 'content-type': 'text/event-stream' } },
+      )
+    }
+    const fetch = Fetch.from({
+      fetch: rawFetch,
+      methods: [session(parameters)],
+      async onChallenge() {
+        if (!useExternalCredential) return undefined
+        useExternalCredential = false
+        return externalCredential
+      },
+    })
+
+    const response = await fetch('https://example.com/stream', {
+      headers: { accept: 'text/event-stream' },
+    })
+
+    expect(response.headers.get('content-type')).toBe('text/event-stream')
+    expect(await response.text()).toBe(
+      `${Types.formatMessageEvent('first')}${Types.formatMessageEvent('second')}`,
+    )
+    expect(actions).toEqual(['open', 'voucher', 'topUp', 'voucher'])
+  })
+
   test('opens for the current amount without client deposit configuration', async () => {
     const method = session({ account, getClient: () => client })
     const payload = deserialize(

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

@@ -1,7 +1,9 @@
 import { type Address, parseUnits } from 'viem'
 import { tempo as tempo_chain } from 'viem/chains'
 
+import * as MethodResponse from '../../../client/internal/MethodResponse.js'
 import * as Constants from '../../../Constants.js'
+import * as Credential from '../../../Credential.js'
 import * as Method from '../../../Method.js'
 import * as Account from '../../../viem/Account.js'
 import * as Client from '../../../viem/Client.js'
@@ -11,6 +13,7 @@ import type {
 } from '../../client/ResolveAccount.js'
 import * as defaults from '../../internal/defaults.js'
 import * as Methods from '../../Methods.js'
+import { isEventStream, requireSessionCredentialContext } from '../precompile/Protocol.js'
 import { serializeCredential, type ChannelEntry } from './ChannelOps.js'
 import { createChannelStore, type ChannelStore } from './ChannelStore.js'
 import {
@@ -20,6 +23,15 @@ import {
   resolveRecoverContext,
   sessionContextSchema,
 } from './CredentialState.js'
+import { assertWithinMaxDeposit } from './Runtime.js'
+import {
+  handleSseNeedVoucher,
+  isTempoSessionChallenge,
+  managementInput,
+  postTopUp,
+  wrapSseResponse,
+  type SsePaymentDriver,
+} from './Transports.js'
 
 export { sessionContextSchema, type SessionContext } from './CredentialState.js'
 
@@ -52,7 +64,7 @@ export function session(parameters: session.Parameters = {}) {
   const store = channelStore ?? createChannelStore()
   const sink = { store, notifyUpdate: (entry: ChannelEntry) => onChannelUpdate?.(entry) }
 
-  return Method.toClient(Methods.session, {
+  const method = Method.toClient(Methods.session, {
     canHandleChallenge({ challenge }) {
       return (
         Constants.getMethodDetail(
@@ -98,6 +110,66 @@ export function session(parameters: session.Parameters = {}) {
       return serializeCredential(challenge, payload, resolved.chainId, account)
     },
   })
+
+  return MethodResponse.register(
+    method,
+    async ({ challenge, credential, fetch, headers, input, refetch, response, signal }) => {
+      if (!isTempoSessionChallenge(challenge)) return response
+      if (!isEventStream(response)) {
+        const credentialContext = requireSessionCredentialContext(
+          Credential.deserialize(credential).payload,
+        )
+        if (
+          credentialContext.action === 'open' &&
+          headers.get('accept')?.toLowerCase().includes('text/event-stream')
+        )
+          return (await refetch?.()) ?? response
+        return response
+      }
+
+      const channelKey = (
+        await resolveChallengeContext({
+          challenge,
+          escrowOverride,
+          getClient,
+        })
+      ).key
+      let channel = await store.get(channelKey)
+      const driver = {
+        assertVoucherWithinLocalLimit: (cumulativeAmount) =>
+          assertWithinMaxDeposit(cumulativeAmount, maxDeposit),
+        createSessionCredential: (challenge, context) =>
+          method.createCredential({ challenge, context }),
+        fetch,
+        getChannel: () => channel ?? null,
+        managementInput,
+        async topUpIfNeeded({ channelId, deposit, requiredCumulative }) {
+          if (requiredCumulative <= deposit || !channel) return
+          const additionalDeposit = requiredCumulative - deposit
+          await postTopUp({
+            additionalDeposit,
+            challenge,
+            channel,
+            channelId,
+            createSessionCredential: (challenge, context) =>
+              method.createCredential({ challenge, context }),
+            fetch,
+            input,
+          })
+          channel.deposit += additionalDeposit
+          await store.set(channel)
+          sink.notifyUpdate(channel)
+        },
+      } satisfies SsePaymentDriver
+
+      return wrapSseResponse({
+        onNeedVoucher: (event) => handleSseNeedVoucher({ challenge, driver, input }, event),
+        onReceipt() {},
+        response,
+        signal,
+      })
+    },
+  )
 }
 
 /** Type helpers for the low-level TIP-1034 session client method. */

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

@@ -329,9 +329,13 @@ describe('Session', () => {
       expect(posted[0]).toMatchObject({ action: 'voucher', channelId: storedChannelId })
     })
 
-    test('seeds a same-route HEAD snapshot into the entry index and resumes it', async () => {
+    test('seeds a same-route HEAD snapshot and resolves the account when resuming it', async () => {
       const { store, set } = makeChannelStore()
       const posted: SessionCredentialPayload[] = []
+      const resolveAccount = vi.fn(
+        (info: Parameters<NonNullable<sessionManager.Parameters['resolveAccount']>>[0]) =>
+          info.account,
+      )
       const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
         const headers = new Headers(init?.headers)
         if (init?.method === 'HEAD' && !headers.get(Constants.Headers.authorization)) {
@@ -377,6 +381,7 @@ describe('Session', () => {
         client,
         fetch: mockFetch as typeof globalThis.fetch,
         channelStore: store,
+        resolveAccount,
       })
 
       const response = await s.fetch('https://api.example.com/data')
@@ -384,6 +389,12 @@ describe('Session', () => {
       expect(response.status).toBe(200)
       expect(set).toHaveBeenCalledWith(expect.objectContaining({ channelId: storedChannelId }))
       expect(posted[0]).toMatchObject({ action: 'voucher', channelId: storedChannelId })
+      expect(resolveAccount).toHaveBeenCalledOnce()
+      expect(resolveAccount).toHaveBeenCalledWith({
+        account,
+        chainId: 4217,
+        operation: { authority: account.address, kind: 'authorizePaymentChannel' },
+      })
       const contentCall = mockFetch.mock.calls.find((call) => call[1]?.method !== 'HEAD')
       expect(new Headers(contentCall?.[1]?.headers).get('Payment-Session')).toBeNull()
     })

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

@@ -3,6 +3,7 @@ import { parseUnits, type Address } from 'viem'
 
 import * as Challenge from '../../../Challenge.js'
 import * as Fetch from '../../../client/internal/Fetch.js'
+import * as MethodResponse from '../../../client/internal/MethodResponse.js'
 import * as Constants from '../../../Constants.js'
 import type * as Account from '../../../viem/Account.js'
 import type * as Client from '../../../viem/Client.js'
@@ -274,6 +275,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
   const method = sessionPlugin({
     account: parameters.account,
     getClient: parameters.client ? () => parameters.client! : parameters.getClient,
+    resolveAccount: parameters.resolveAccount,
     escrow: parameters.escrow,
     decimals: config.decimals,
     maxDeposit: parameters.maxDeposit,
@@ -292,6 +294,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       }
     },
   })
+  MethodResponse.unregister(method)
   const chargeMethod = chargePlugin({
     account: parameters.account,
     getClient: parameters.client ? () => parameters.client! : parameters.getClient,
@@ -787,6 +790,8 @@ export namespace sessionManager {
       fetch?: typeof globalThis.fetch | undefined
       /** Maximum deposit in human-readable units (e.g. `'10'` for 10 tokens). Converted to raw units via `decimals`. */
       maxDeposit?: string | undefined
+      /** Selects the account that signs session credentials. */
+      resolveAccount?: sessionPlugin.ResolveAccount | undefined
       /** Store for reusable session channels. Defaults to in-memory. */
       channelStore?: ChannelStore | undefined
       /** Optional websocket constructor for runtimes without a global WebSocket. */

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

@@ -19,6 +19,7 @@ import {
   applyTopUpResult,
   closeHttpSession,
   createActiveSocketSession,
+  driveSseResponse,
   isExpectedSocketReceipt,
   managementInput,
   postTopUp,
@@ -31,6 +32,7 @@ import {
   validateSocketCloseReadyReceipt,
   validateSocketPaymentReceipt,
   webSocketProbeUrl,
+  wrapSseResponse,
   type TempoSessionChallenge,
   type TopUpRequirement,
 } from './Transports.js'
@@ -640,6 +642,113 @@ describe('VoucherManagement', () => {
   })
 })
 
+describe('SseDriver', () => {
+  test('preserves application frames and consumes payment receipts', async () => {
+    const receipt = createSessionReceipt({
+      acceptedCumulative: 2n,
+      challengeId: 'challenge-1',
+      channelId: `0x${'01'.repeat(32)}`,
+      spent: 2n,
+    })
+    const acceptReceipt = vi.fn()
+    const response = new Response(
+      [
+        ': keepalive\n\n',
+        'event: custom\ndata: hello\n\n',
+        `event: payment-receipt\ndata: ${JSON.stringify(receipt)}\n\n`,
+      ].join(''),
+    )
+
+    const frames = []
+    for await (const frame of driveSseResponse({
+      async onNeedVoucher() {},
+      onReceipt: acceptReceipt,
+      response,
+    }))
+      frames.push(frame)
+
+    expect(frames).toEqual([
+      { raw: ': keepalive\n\n' },
+      { data: 'hello', raw: 'event: custom\ndata: hello\n\n' },
+    ])
+    expect(acceptReceipt).toHaveBeenCalledWith(receipt)
+  })
+
+  test('wraps standard CRLF streams and preserves response metadata', async () => {
+    const receipt = createSessionReceipt({
+      acceptedCumulative: 2n,
+      challengeId: 'challenge-1',
+      channelId: `0x${'01'.repeat(32)}`,
+      spent: 2n,
+    })
+    const encoder = new TextEncoder()
+    const source = new Response(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode(': keepalive\r\n\r'))
+          controller.enqueue(
+            encoder.encode(
+              [
+                '\nevent: custom\r\ndata: hello\r\n\r\n',
+                `event: payment-receipt\r\ndata: ${JSON.stringify(receipt)}\r\n\r\n`,
+              ].join(''),
+            ),
+          )
+          controller.close()
+        },
+      }),
+      {
+        headers: { 'content-length': '100', 'content-type': 'text/event-stream' },
+        status: 201,
+        statusText: 'Created',
+      },
+    )
+    Object.defineProperty(source, 'url', { value: 'https://example.com/stream' })
+
+    const response = wrapSseResponse({
+      async onNeedVoucher() {},
+      onReceipt() {},
+      response: source,
+    })
+
+    expect(response.status).toBe(201)
+    expect(response.statusText).toBe('Created')
+    expect(response.url).toBe('https://example.com/stream')
+    expect(response.headers.get('content-type')).toBe('text/event-stream')
+    expect(response.headers.has('content-length')).toBe(false)
+    expect(await response.text()).toBe(': keepalive\r\n\r\nevent: custom\r\ndata: hello\r\n\r\n')
+  })
+
+  test.each(['consumer', 'signal'] as const)(
+    'cancels the source stream from %s',
+    async (source) => {
+      const abortController = new AbortController()
+      const cancel = vi.fn()
+      const sourceResponse = new Response(
+        new ReadableStream({
+          cancel,
+          start(controller) {
+            controller.enqueue(new TextEncoder().encode('data: first\n\n'))
+          },
+        }),
+      )
+      const response = wrapSseResponse({
+        async onNeedVoucher() {},
+        onReceipt() {},
+        response: sourceResponse,
+        signal: abortController.signal,
+      })
+
+      const reader = response.body!.getReader()
+      await reader.read()
+      if (source === 'signal') abortController.abort()
+      else await reader.cancel()
+
+      await vi.waitFor(() => expect(cancel).toHaveBeenCalledOnce())
+    },
+  )
+})
+
 describe('WsDriver', () => {
   const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex.Hex
   const challenge: TempoSessionChallenge = {

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

@@ -748,6 +748,17 @@ export type OpenSseSessionParameters = {
   topUpIfNeeded(parameters: TopUpRequirement): Promise<void>
 }
 
+/** Session payment operations shared with fetch-backed streams. */
+export type SsePaymentDriver = Pick<
+  OpenSseSessionParameters,
+  | 'assertVoucherWithinLocalLimit'
+  | 'createSessionCredential'
+  | 'fetch'
+  | 'getChannel'
+  | 'managementInput'
+  | 'topUpIfNeeded'
+>
+
 /**
  * Opens an auto-driving paid SSE stream.
  *
@@ -777,69 +788,182 @@ export async function openSseSession(
   if (!isEventStream(response)) throw new Error('SSE response is not an event stream.')
   if (!response.body) throw new Error('Response has no body.')
 
-  return iterateSseResponse({
-    challenge,
-    driver,
-    input,
-    onReceipt,
+  return iterateSseMessages({
+    onNeedVoucher: (event) => handleSseNeedVoucher({ challenge, driver, input }, event),
+    onReceipt(receipt) {
+      driver.acceptReceipt(receipt)
+      onReceipt?.(receipt)
+    },
     response,
     signal,
   })
 }
 
-type IterateSseResponseParameters = {
-  challenge: TempoSessionChallenge | null
-  driver: OpenSseSessionParameters
-  input: RequestInfo | URL
-  onReceipt?: ((receipt: SessionReceipt) => void) | undefined
+/** Application SSE frame emitted after session payment events are handled. */
+export type SseResponseFrame = {
+  /** Parsed application data, when present. */
+  data?: string | undefined
+  /** Original frame text, including its separator. */
+  raw: string
+}
+
+/** Inputs for driving an open paid SSE response. */
+export type DriveSseResponseParameters = {
+  /** Handles a request for the stream's next cumulative voucher. */
+  onNeedVoucher(event: NeedVoucherEvent): Promise<void>
+  /** Handles a payment receipt emitted by the stream. */
+  onReceipt(receipt: SessionReceipt): void
+  /** Open SSE response to drive. */
   response: Response
+  /** Abort signal used to stop reading the response. */
   signal?: AbortSignal | undefined
 }
 
-async function* iterateSseResponse(
-  parameters: IterateSseResponseParameters,
-): AsyncGenerator<string> {
-  const reader = parameters.response.body!.getReader()
+async function* iterateSseMessages(parameters: DriveSseResponseParameters): AsyncGenerator<string> {
+  for await (const frame of driveSseResponse(parameters)) {
+    if (frame.data !== undefined) yield frame.data
+  }
+}
+
+/** Handles session payment events and yields application SSE frames unchanged. */
+export async function* driveSseResponse(
+  parameters: DriveSseResponseParameters,
+): AsyncGenerator<SseResponseFrame> {
+  if (!parameters.response.body) throw new Error('Response has no body.')
+  const reader = parameters.response.body.getReader()
   const decoder = new TextDecoder()
   let buffer = ''
+  let complete = false
+  const cancel = () => {
+    void reader.cancel(parameters.signal?.reason).catch(() => undefined)
+  }
+  parameters.signal?.addEventListener('abort', cancel, { once: true })
+  if (parameters.signal?.aborted) cancel()
 
   try {
     while (true) {
       if (parameters.signal?.aborted) break
 
       const { done, value } = await reader.read()
-      if (done) break
-
-      buffer += decoder.decode(value, { stream: true })
-      const parts = buffer.split('\n\n')
-      buffer = parts.pop()!
-
-      for (const part of parts) {
+      if (done) {
+        complete = true
+        buffer += decoder.decode()
+      } else buffer += decoder.decode(value, { stream: true })
+
+      while (true) {
+        const separator = findSseSeparator(buffer, done)
+        if (!separator) break
+        const end = separator.index + separator.length
+        const part = buffer.slice(0, separator.index)
+        const raw = buffer.slice(0, end)
+        buffer = buffer.slice(end)
         if (!part.trim()) continue
-        const event = parseEvent(part)
-        if (!event) continue
+        const event = parseEvent(part.replace(/\r\n|\r/g, '\n'))
+        if (!event) {
+          yield { raw }
+          continue
+        }
 
         switch (event.type) {
           case 'message':
-            yield event.data
+            yield { data: event.data, raw }
             break
           case 'payment-need-voucher':
-            await handleSseNeedVoucher(parameters, event.data)
+            await parameters.onNeedVoucher(event.data)
             break
           case 'payment-receipt':
-            parameters.driver.acceptReceipt(event.data)
-            parameters.onReceipt?.(event.data)
+            parameters.onReceipt(event.data)
             break
         }
       }
+      if (done) break
     }
   } finally {
+    parameters.signal?.removeEventListener('abort', cancel)
+    if (!complete) await reader.cancel().catch(() => undefined)
     reader.releaseLock()
   }
 }
 
-async function handleSseNeedVoucher(
-  parameters: IterateSseResponseParameters,
+function findSseSeparator(
+  value: string,
+  complete: boolean,
+): { index: number; length: number } | undefined {
+  for (let index = 0; index < value.length; index++) {
+    const first = lineEndingLength(value, index, complete)
+    if (!first) continue
+    const second = lineEndingLength(value, index + first, complete)
+    if (second) return { index, length: first + second }
+    index += first - 1
+  }
+  return undefined
+}
+
+function lineEndingLength(value: string, index: number, complete: boolean): number {
+  if (value[index] === '\n') return 1
+  if (value[index] !== '\r') return 0
+  if (value[index + 1] === '\n') return 2
+  if (index + 1 === value.length && !complete) return 0
+  return 1
+}
+
+/** Wraps an SSE response while handling session payment frames in-band. */
+export function wrapSseResponse(parameters: DriveSseResponseParameters): Response {
+  const abortController = new AbortController()
+  const abort = () => abortController.abort(parameters.signal?.reason)
+  parameters.signal?.addEventListener('abort', abort, { once: true })
+  if (parameters.signal?.aborted) abort()
+
+  const iterator = driveSseResponse({ ...parameters, signal: abortController.signal })
+  const encoder = new TextEncoder()
+  const headers = new Headers(parameters.response.headers)
+  headers.delete('content-length')
+  const cleanup = () => parameters.signal?.removeEventListener('abort', abort)
+
+  const response = new Response(
+    new ReadableStream({
+      async pull(controller) {
+        try {
+          const frame = await iterator.next()
+          if (frame.done) {
+            cleanup()
+            return controller.close()
+          }
+          controller.enqueue(encoder.encode(frame.value.raw))
+        } catch (error) {
+          cleanup()
+          throw error
+        }
+      },
+      async cancel() {
+        cleanup()
+        abortController.abort()
+        await iterator.return(undefined)
+      },
+    }),
+    {
+      headers,
+      status: parameters.response.status,
+      statusText: parameters.response.statusText,
+    },
+  )
+
+  for (const property of ['redirected', 'type', 'url'] as const)
+    Object.defineProperty(response, property, {
+      configurable: true,
+      get: () => parameters.response[property],
+    })
+
+  return response
+}
+
+/** Handles an in-band voucher request using the shared SSE payment driver. */
+export async function handleSseNeedVoucher(
+  parameters: {
+    challenge: TempoSessionChallenge | null
+    driver: SsePaymentDriver
+    input: RequestInfo | URL
+  },
   event: NeedVoucherEvent,
 ) {
   const channel = parameters.driver.getChannel()

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

@@ -611,6 +611,9 @@ describe('precompile broadcastOpenTransaction', () => {
     expect(broadcastIndex).toBeGreaterThan(-1)
     expect(simulationIndex).toBeGreaterThan(-1)
     expect(simulationIndex).toBeLessThan(broadcastIndex)
+    expect(
+      rpcMethods.slice(0, broadcastIndex).filter((method) => method === 'eth_call'),
+    ).toHaveLength(2)
   })
 
   test('hosted fee-payer relays a sender-signed open without local co-signing', async () => {
@@ -653,6 +656,9 @@ describe('precompile broadcastOpenTransaction', () => {
 
     expect(rpcMethods).toContain('eth_sendRawTransaction')
     expect(rpcMethods).not.toContain('eth_sendRawTransactionSync')
+    expect(rpcMethods.indexOf('eth_call')).toBeLessThan(
+      rpcMethods.indexOf('eth_sendRawTransaction'),
+    )
   })
 
   test('rejects expiring nonce hash mismatches before broadcasting', async () => {
@@ -971,6 +977,9 @@ describe('precompile broadcastTopUpTransaction', () => {
     expect(broadcastIndex).toBeGreaterThan(-1)
     expect(simulationIndex).toBeGreaterThan(-1)
     expect(simulationIndex).toBeLessThan(broadcastIndex)
+    expect(
+      rpcMethods.slice(0, broadcastIndex).filter((method) => method === 'eth_call'),
+    ).toHaveLength(2)
   })
 
   test('rejects top-up calldata amount mismatches before broadcasting', async () => {