mppx 0.6.31 → 0.8.0

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

@@ -0,0 +1,1397 @@
+import { createClient, custom, encodeFunctionResult, type Address, type Hex } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { describe, expect, test, vi } from 'vp/test'
+
+import * as Challenge from '../../../Challenge.js'
+import * as Constants from '../../../Constants.js'
+import * as Credential from '../../../Credential.js'
+import type { ChannelEntry } from '../client/ChannelOps.js'
+import { createJsonChannelStore, entryKey, type ChannelStore } from '../client/ChannelStore.js'
+import * as Channel from '../precompile/Channel.js'
+import { escrowAbi } from '../precompile/escrow.abi.js'
+import { tip20ChannelEscrow } from '../precompile/Protocol.js'
+import { createSessionReceipt, serializeSessionReceipt } from '../precompile/Protocol.js'
+import type { NeedVoucherEvent, SessionReceipt } from '../precompile/Protocol.js'
+import { formatNeedVoucherEvent, parseEvent } from '../precompile/Protocol.js'
+import type { SessionCredentialPayload } from '../precompile/Protocol.js'
+import { computeFallbackCloseAmount, sessionManager } from './SessionManager.js'
+
+const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
+const challengeId = 'test-challenge-1'
+const realm = 'test.example.com'
+const account = privateKeyToAccount(
+  '0xac0974bec39a17e36ba6a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+)
+
+const client = createClient({
+  account,
+  chain: { id: 4217 } as never,
+  transport: custom({
+    async request(args) {
+      if (args.method === 'eth_chainId') return '0x1079'
+      if (args.method === 'eth_getTransactionCount') return '0x0'
+      if (args.method === 'eth_estimateGas') return '0x5208'
+      if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+      if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+      if (args.method === 'eth_call')
+        return encodeFunctionResult({
+          abi: escrowAbi,
+          functionName: 'getChannelState',
+          result: { settled: 0n, deposit: 10_000_000n, closeRequestedAt: 0 },
+        })
+      throw new Error(`unexpected rpc request: ${args.method}`)
+    },
+  }),
+})
+
+const storedDescriptor = {
+  authorizedSigner: account.address,
+  expiringNonceHash: `0x${'11'.repeat(32)}` as Hex,
+  operator: '0x0000000000000000000000000000000000000000' as Address,
+  payee: '0x742d35cc6634c0532925a3b844bc9e7595f8fe00' as Address,
+  payer: account.address,
+  salt: `0x${'22'.repeat(32)}` as Hex,
+  token: '0x20c0000000000000000000000000000000000001' as Address,
+}
+
+const storedChannelId = Channel.computeId({
+  ...storedDescriptor,
+  chainId: 4217,
+  escrow: tip20ChannelEscrow,
+})
+
+function channelEntry(overrides: Partial<ChannelEntry> = {}): ChannelEntry {
+  return {
+    channelId: storedChannelId,
+    cumulativeAmount: 1_000_000n,
+    deposit: 10_000_000n,
+    descriptor: storedDescriptor,
+    escrow: tip20ChannelEscrow,
+    chainId: 4217,
+    opened: true,
+    ...overrides,
+  }
+}
+
+/**
+ * In-memory {@link ChannelStore} with spied `set`/`delete`, optionally seeded.
+ * Seeded entries live in the entry index, so the plugin resumes them from
+ * `store.get(resolved.key)` after a 402 (there is no first-request hint).
+ */
+function makeChannelStore(seed: readonly ChannelEntry[] = []) {
+  const map = new Map<string, ChannelEntry>(seed.map((entry) => [entryKey(entry), entry]))
+  const set = vi.fn((entry: ChannelEntry) => {
+    map.set(entryKey(entry), entry)
+  })
+  const remove = vi.fn((key: string) => {
+    map.delete(key)
+  })
+  const store: ChannelStore = {
+    get: (key) => map.get(key),
+    set,
+    delete: remove,
+  }
+  return { store, set, delete: remove, map }
+}
+
+function makeChallenge(overrides: Record<string, unknown> = {}): Challenge.Challenge {
+  return Challenge.from({
+    id: challengeId,
+    realm,
+    method: 'tempo',
+    intent: 'session',
+    request: {
+      amount: '1000000',
+      currency: '0x20c0000000000000000000000000000000000001',
+      recipient: '0x742d35cc6634c0532925a3b844bc9e7595f8fe00',
+      decimals: 6,
+      methodDetails: {
+        escrowContract: tip20ChannelEscrow,
+        chainId: 4217,
+        sessionProtocol: Constants.SessionProtocols.v2,
+      },
+      ...overrides,
+    },
+  })
+}
+
+function makeChargeChallenge(overrides: Record<string, unknown> = {}): Challenge.Challenge {
+  return Challenge.from({
+    id: 'charge-bootstrap',
+    realm,
+    method: 'tempo',
+    intent: 'charge',
+    request: {
+      amount: '0',
+      currency: '0x20c0000000000000000000000000000000000001',
+      recipient: '0x742d35cc6634c0532925a3b844bc9e7595f8fe00',
+      methodDetails: { chainId: 4217 },
+      ...overrides,
+    },
+  })
+}
+
+function make402Response(challenge?: Challenge.Challenge): Response {
+  const c = challenge ?? makeChallenge()
+  return new Response(null, {
+    status: 402,
+    headers: { 'WWW-Authenticate': Challenge.serialize(c) },
+  })
+}
+
+function makeOkResponse(body?: string): Response {
+  return new Response(body ?? 'ok', { status: 200 })
+}
+
+function makeSseResponse(events: string[]): Response {
+  const body = events.join('')
+  return new Response(body, {
+    status: 200,
+    headers: { 'Content-Type': 'text/event-stream' },
+  })
+}
+
+describe('Session', () => {
+  describe('computeFallbackCloseAmount', () => {
+    test('uses matching close-ready receipt spend first', () => {
+      const receipt = createSessionReceipt({
+        acceptedCumulative: 100n,
+        challengeId,
+        channelId,
+        spent: 80n,
+      })
+
+      expect(
+        computeFallbackCloseAmount({
+          challengeId,
+          channelId,
+          closeReadyReceipt: receipt,
+          cumulativeAmount: 100n,
+          deliveredChunks: 10n,
+          socketChallengeId: challengeId,
+          socketChannelId: channelId,
+          spent: 50n,
+          tickCost: 10n,
+        }),
+      ).toBe(80n)
+    })
+
+    test('uses matching socket delivery estimate clamped to cumulative authorization', () => {
+      expect(
+        computeFallbackCloseAmount({
+          challengeId,
+          channelId,
+          cumulativeAmount: 90n,
+          deliveredChunks: 10n,
+          socketChallengeId: challengeId,
+          socketChannelId: channelId,
+          spent: 40n,
+          tickCost: 10n,
+        }),
+      ).toBe(90n)
+    })
+
+    test('uses receipt-tracked spend when no socket estimate applies', () => {
+      expect(
+        computeFallbackCloseAmount({
+          challengeId,
+          channelId,
+          cumulativeAmount: 100n,
+          deliveredChunks: 10n,
+          socketChallengeId: 'other-challenge',
+          socketChannelId: channelId,
+          spent: 40n,
+          tickCost: 10n,
+        }),
+      ).toBe(40n)
+    })
+  })
+
+  describe('parseEvent round-trip via SSE', () => {
+    test('parses message events from SSE stream', () => {
+      const raw = 'event: message\ndata: hello world\n\n'
+      const event = parseEvent(raw)
+      expect(event).toEqual({ type: 'message', data: 'hello world' })
+    })
+
+    test('parses payment-need-voucher events', () => {
+      const params: NeedVoucherEvent = {
+        channelId,
+        requiredCumulative: '6000000',
+        acceptedCumulative: '5000000',
+        deposit: '10000000',
+      }
+      const raw = formatNeedVoucherEvent(params)
+      const event = parseEvent(raw)
+      expect(event).toEqual({ type: 'payment-need-voucher', data: params })
+    })
+  })
+
+  describe('session creation', () => {
+    test('creates session with initial state', () => {
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        maxDeposit: '10',
+      })
+
+      expect(s.channelId).toBeUndefined()
+      expect(s.cumulative).toBe(0n)
+      expect(s.opened).toBe(false)
+    })
+  })
+
+  describe('.fetch()', () => {
+    test('passes through non-402 responses', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(makeOkResponse('hello'))
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const res = await s.fetch('https://api.example.com/data')
+      expect(res.status).toBe(200)
+      expect(await res.text()).toBe('hello')
+      expect(mockFetch).toHaveBeenCalledOnce()
+    })
+
+    test('rejects a concurrent request while one is in flight', async () => {
+      let release!: () => void
+      const gate = new Promise<void>((resolve) => {
+        release = resolve
+      })
+      const mockFetch = vi.fn().mockImplementation(async () => {
+        await gate
+        return makeOkResponse('hello')
+      })
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const first = s.fetch('https://api.example.com/data')
+      await expect(s.fetch('https://api.example.com/data')).rejects.toThrow(
+        'concurrent requests on one manager are not supported',
+      )
+
+      release()
+      expect((await first).status).toBe(200)
+
+      // The guard clears after the in-flight request settles.
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(200)
+    })
+
+    test('binds the default global fetch for browser runtimes', async () => {
+      const originalFetch = globalThis.fetch
+      const mockFetch = vi.fn(function (this: unknown) {
+        expect(this).toBe(globalThis)
+        return Promise.resolve(makeOkResponse('hello'))
+      })
+      globalThis.fetch = mockFetch as typeof globalThis.fetch
+      try {
+        const s = sessionManager({
+          account: '0x0000000000000000000000000000000000000001',
+        })
+
+        const res = await s.fetch('https://api.example.com/data')
+
+        expect(res.status).toBe(200)
+        expect(mockFetch).toHaveBeenCalledOnce()
+      } finally {
+        globalThis.fetch = originalFetch
+      }
+    })
+
+    test('resumes a seeded channel after a 402 without a first-request hint', async () => {
+      const posted: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) posted.push(payload)
+        if (!payload) return Promise.resolve(make402Response())
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        channelStore: makeChannelStore([channelEntry()]).store,
+      })
+
+      await s.fetch('https://api.example.com/data')
+
+      // No persisted hint: the first request carries no Payment-Session header,
+      // and the channel is resumed from the entry index with a voucher.
+      expect(new Headers(mockFetch.mock.calls[0]?.[1]?.headers).get('Payment-Session')).toBeNull()
+      expect(posted[0]).toMatchObject({ action: 'voucher', channelId: storedChannelId })
+    })
+
+    test('seeds a same-route HEAD snapshot into the entry index and resumes it', async () => {
+      const { store, set } = makeChannelStore()
+      const posted: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const headers = new Headers(init?.headers)
+        if (init?.method === 'HEAD' && !headers.get(Constants.Headers.authorization)) {
+          expect(headers.get(Constants.Headers.acceptPayment)).toBe('tempo/charge')
+          return Promise.resolve(make402Response(makeChargeChallenge()))
+        }
+        if (init?.method === 'HEAD') {
+          const credential = Credential.deserialize(headers.get(Constants.Headers.authorization)!)
+          expect(credential.payload).toMatchObject({ type: 'proof' })
+          return Promise.resolve(
+            new Response(null, {
+              status: 204,
+              headers: {
+                [Constants.Headers.paymentSessionSnapshot]: sessionManager.serializeSnapshot({
+                  acceptedCumulative: '1000000',
+                  chainId: 4217,
+                  channelId: storedChannelId,
+                  deposit: '10000000',
+                  descriptor: storedDescriptor,
+                  escrow: tip20ChannelEscrow,
+                  requiredCumulative: '1000000',
+                  settled: '0',
+                  spent: '0',
+                  units: 0,
+                }),
+              },
+            }),
+          )
+        }
+        // The seeded snapshot is not sent as a first-request hint; the content
+        // request gets a 402 and resumes from the entry index with a voucher.
+        const authorization = headers.get(Constants.Headers.authorization)
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) posted.push(payload)
+        if (!payload) return Promise.resolve(make402Response())
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        bootstrap: true,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        channelStore: store,
+      })
+
+      const response = await s.fetch('https://api.example.com/data')
+
+      expect(response.status).toBe(200)
+      expect(set).toHaveBeenCalledWith(expect.objectContaining({ channelId: storedChannelId }))
+      expect(posted[0]).toMatchObject({ action: 'voucher', channelId: storedChannelId })
+      const contentCall = mockFetch.mock.calls.find((call) => call[1]?.method !== 'HEAD')
+      expect(new Headers(contentCall?.[1]?.headers).get('Payment-Session')).toBeNull()
+    })
+
+    test('does not answer non-zero bootstrap charge challenges', async () => {
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const headers = new Headers(init?.headers)
+        if (init?.method === 'HEAD' && !headers.get(Constants.Headers.authorization)) {
+          return Promise.resolve(make402Response(makeChargeChallenge({ amount: '1' })))
+        }
+        if (init?.method === 'HEAD') throw new Error('unexpected bootstrap authorization')
+        expect(headers.get(Constants.Headers.paymentSession)).toBeNull()
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        bootstrap: true,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const response = await s.fetch('https://api.example.com/data')
+
+      expect(response.status).toBe(200)
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+    })
+
+    test('falls back to normal fetch when bootstrap is unsupported', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(new Response(null, { status: 404 }))
+        .mockResolvedValueOnce(makeOkResponse())
+      const s = sessionManager({
+        account,
+        bootstrap: true,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const response = await s.fetch('https://api.example.com/data')
+
+      expect(response.status).toBe(200)
+      expect(s.channelId).toBeUndefined()
+      expect(mockFetch).toHaveBeenCalledTimes(2)
+      expect(mockFetch.mock.calls[0]?.[1]).toMatchObject({ method: 'HEAD' })
+      expect(new Headers(mockFetch.mock.calls[1]?.[1]?.headers).get('Payment-Session')).toBeNull()
+    })
+
+    test('drops a stale stored channel the server rejects and retries with a fresh one', async () => {
+      const { store, delete: remove } = makeChannelStore([channelEntry()])
+      const postedPayloads: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const headers = new Headers(init?.headers)
+        const authorization = headers.get(Constants.Headers.authorization)
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) postedPayloads.push(payload)
+
+        if (!payload) return Promise.resolve(make402Response())
+        // Reject any reuse of the stale stored channel; accept a freshly opened one.
+        if (payload.channelId === storedChannelId)
+          return Promise.resolve(new Response('gone', { status: 500 }))
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+        channelStore: store,
+      })
+
+      const response = await s.fetch('https://api.example.com/data')
+
+      expect(response.status).toBe(200)
+      expect(remove).toHaveBeenCalledOnce()
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['voucher', 'open'])
+      expect(s.opened).toBe(true)
+      expect(s.channelId).not.toBe(storedChannelId)
+    })
+
+    test('does not bootstrap when disabled', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(makeOkResponse())
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      await s.fetch('https://api.example.com/data')
+
+      expect(mockFetch).toHaveBeenCalledOnce()
+      expect(new Headers(mockFetch.mock.calls[0]?.[1]?.headers).get('Payment-Session')).toBeNull()
+    })
+
+    test('uses stored channel details when the server does not return a snapshot', async () => {
+      const postedPayloads: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) postedPayloads.push(payload)
+
+        if (!payload) return Promise.resolve(make402Response())
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        channelStore: makeChannelStore([channelEntry()]).store,
+      })
+
+      await s.fetch('https://api.example.com/data')
+
+      expect(postedPayloads[0]).toMatchObject({
+        action: 'voucher',
+        channelId: storedChannelId,
+      })
+    })
+
+    test('resumes a persisted channel across a restart via the entry index', async () => {
+      // A shared durable KV backing two manager instances simulates a restart:
+      // the second manager shares only what survived to disk.
+      const backend = new Map<string, string>()
+      const durableStore = () =>
+        createJsonChannelStore({
+          get: (key) => backend.get(key),
+          set: (key, value) => {
+            backend.set(key, value)
+          },
+          delete: (key) => {
+            backend.delete(key)
+          },
+        })
+
+      const openFetch = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization) return Promise.resolve(make402Response())
+        return Promise.resolve(makeOkResponse())
+      })
+      const first = sessionManager({
+        account,
+        client,
+        fetch: openFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+        channelStore: durableStore(),
+      })
+      await first.fetch('https://api.example.com/data')
+      const channelId = first.channelId
+      expect(channelId).toBeDefined()
+
+      // The durable channel entry must have reached the KV.
+      expect([...backend.keys()].some((key) => key.startsWith('chan:'))).toBe(true)
+      // No persistent hints are written; only the durable channel entry survives.
+      expect([...backend.keys()].some((key) => key.startsWith('hint:'))).toBe(false)
+
+      const posted: SessionCredentialPayload[] = []
+      const resumeFetch = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) posted.push(payload)
+        if (!payload) return Promise.resolve(make402Response())
+        return Promise.resolve(makeOkResponse())
+      })
+      const restarted = sessionManager({
+        account,
+        client,
+        fetch: resumeFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+        channelStore: durableStore(),
+      })
+      await restarted.fetch('https://api.example.com/data')
+
+      // The first request carries no hint header; after the 402 the restarted
+      // manager resumes the persisted channel from the entry index with a
+      // voucher rather than opening a new one.
+      expect(new Headers(resumeFetch.mock.calls[0]?.[1]?.headers).get('Payment-Session')).toBeNull()
+      expect(posted[0]).toMatchObject({ action: 'voucher', channelId })
+    })
+
+    test('persists opened channels and deletes closed channels when supported', async () => {
+      const { store, set, delete: remove } = makeChannelStore()
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        callCount++
+
+        if (callCount === 1) return Promise.resolve(make402Response())
+        if (payload?.action === 'open') {
+          return Promise.resolve(
+            new Response('ok', {
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: BigInt(payload.cumulativeAmount),
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: 0n,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+        if (payload?.action === 'close') {
+          return Promise.resolve(
+            new Response('ok', {
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: BigInt(payload.cumulativeAmount),
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: BigInt(payload.cumulativeAmount),
+                    txHash: `0x${'aa'.repeat(32)}`,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+        channelStore: store,
+      })
+
+      await s.fetch('https://api.example.com/data')
+      expect(set).toHaveBeenCalledWith(
+        expect.objectContaining({
+          channelId: s.channelId,
+          opened: true,
+        }),
+      )
+
+      await s.close()
+      expect(remove).toHaveBeenCalledOnce()
+    })
+
+    test('rolls back state when opening a channel throws', async () => {
+      const failingClient = createClient({
+        account,
+        chain: { id: 4217 } as never,
+        transport: custom({
+          async request(args) {
+            if (args.method === 'eth_chainId') return '0x1079'
+            if (args.method === 'eth_getTransactionCount') return '0x0'
+            if (args.method === 'eth_estimateGas') throw new Error('insufficient balance')
+            if (args.method === 'eth_maxPriorityFeePerGas') return '0x1'
+            if (args.method === 'eth_getBlockByNumber') return { baseFeePerGas: '0x1' }
+            throw new Error(`unexpected rpc request: ${args.method}`)
+          },
+        }),
+      })
+      const mockFetch = vi.fn().mockResolvedValue(make402Response())
+      const s = sessionManager({
+        account,
+        client: failingClient,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      await expect(s.fetch('https://api.example.com/data')).rejects.toThrow(/insufficient balance/)
+
+      expect(s.state).toEqual({ status: 'idle' })
+      expect(s.opened).toBe(false)
+      expect(s.cumulative).toBe(0n)
+    })
+
+    test('automatically top-ups and retries when an HTTP session exceeds deposit', async () => {
+      const postedPayloads: SessionCredentialPayload[] = []
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        callCount++
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) postedPayloads.push(payload)
+
+        if (callCount === 1)
+          return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '1000000' })))
+
+        if (payload?.action === 'open') {
+          return Promise.resolve(
+            make402Response(
+              makeChallenge({
+                methodDetails: {
+                  escrowContract: tip20ChannelEscrow,
+                  chainId: 4217,
+                  sessionSnapshot: {
+                    acceptedCumulative: '2000000',
+                    chainId: 4217,
+                    channelId: payload.channelId,
+                    deposit: '1000000',
+                    descriptor: payload.descriptor,
+                    escrow: tip20ChannelEscrow,
+                    requiredCumulative: '2000000',
+                    settled: '0',
+                    spent: '1000000',
+                    units: 1,
+                  },
+                },
+              }),
+            ),
+          )
+        }
+
+        if (payload?.action === 'topUp') return Promise.resolve(makeOkResponse())
+
+        if (payload?.action === 'voucher') {
+          return Promise.resolve(
+            new Response('paid', {
+              status: 200,
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: 2_000_000n,
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: 2_000_000n,
+                    units: 2,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      const response = await s.fetch('https://api.example.com/data')
+
+      expect(response.status).toBe(200)
+      expect(await response.text()).toBe('paid')
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['open', 'topUp', 'voucher'])
+      expect(s.state).toMatchObject({
+        status: 'active',
+        acceptedCumulative: '2000000',
+        deposit: '2000000',
+        spent: '2000000',
+        units: 2,
+      })
+    })
+
+    test('preemptively top-ups before signing an HTTP voucher that exceeds deposit', async () => {
+      const postedPayloads: SessionCredentialPayload[] = []
+      let challengeCount = 0
+      const receipt = (payload: Extract<SessionCredentialPayload, { channelId: Hex }>) =>
+        new Response('paid', {
+          status: 200,
+          headers: {
+            'Payment-Receipt': serializeSessionReceipt(
+              createSessionReceipt({
+                acceptedCumulative: BigInt(
+                  'cumulativeAmount' in payload ? payload.cumulativeAmount : '1000000',
+                ),
+                challengeId,
+                channelId: payload.channelId,
+                spent: BigInt('cumulativeAmount' in payload ? payload.cumulativeAmount : '1000000'),
+                units:
+                  'cumulativeAmount' in payload && payload.cumulativeAmount === '2000000' ? 2 : 1,
+              }),
+            ),
+          },
+        })
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) postedPayloads.push(payload)
+
+        if (!payload) {
+          challengeCount++
+          return Promise.resolve(
+            make402Response(
+              makeChallenge(challengeCount === 1 ? { suggestedDeposit: '1000000' } : {}),
+            ),
+          )
+        }
+        if (payload.action === 'topUp') return Promise.resolve(makeOkResponse())
+        if (payload.action === 'open' || payload.action === 'voucher')
+          return Promise.resolve(receipt(payload))
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      await s.fetch('https://api.example.com/data')
+      const response = await s.fetch('https://api.example.com/data')
+
+      expect(response.status).toBe(200)
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['open', 'topUp', 'voucher'])
+      expect(s.state).toMatchObject({
+        status: 'active',
+        acceptedCumulative: '2000000',
+        deposit: '2000000',
+        spent: '2000000',
+        units: 2,
+      })
+    })
+  })
+
+  describe('.topUp()', () => {
+    test('posts a precompile top-up credential for the active channel', async () => {
+      const postedPayloads: SessionCredentialPayload[] = []
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        callCount++
+        const authorization = new Headers(init?.headers).get('Authorization')
+        if (authorization) {
+          postedPayloads.push(
+            Credential.deserialize<SessionCredentialPayload>(authorization).payload,
+          )
+        }
+        if (callCount === 1)
+          return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '5000000' })))
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      await s.fetch('https://api.example.com/data')
+      expect(s.state).toMatchObject({
+        status: 'active',
+        acceptedCumulative: '1000000',
+        deposit: '5000000',
+      })
+      const receipt = await s.topUp('1')
+
+      expect(receipt).toBeUndefined()
+      expect(s.state).toMatchObject({
+        status: 'active',
+        acceptedCumulative: '1000000',
+        deposit: '6000000',
+      })
+      expect(postedPayloads[0]?.action).toBe('open')
+      expect(postedPayloads[1]?.action).toBe('topUp')
+      const openPayload = postedPayloads[0]
+      const topUpPayload = postedPayloads[1]
+      if (openPayload?.action !== 'open' || topUpPayload?.action !== 'topUp') {
+        throw new Error('expected open then top-up payloads')
+      }
+      expect(topUpPayload.channelId).toBe(openPayload.channelId)
+      expect(topUpPayload.descriptor).toEqual(openPayload.descriptor)
+      expect(topUpPayload.additionalDeposit).toBe('1000000')
+    })
+
+    test('rejects top-up before a channel is open', async () => {
+      const s = sessionManager({
+        account,
+        client,
+        fetch: vi.fn() as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      await expect(s.topUp('1')).rejects.toThrow('Cannot top up session: no open channel.')
+    })
+
+    test('rolls back optimistic vouchers when the paid retry fails', async () => {
+      const postedPayloads: SessionCredentialPayload[] = []
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        callCount++
+        const authorization = new Headers(init?.headers).get('Authorization')
+        if (authorization) {
+          postedPayloads.push(
+            Credential.deserialize<SessionCredentialPayload>(authorization).payload,
+          )
+        }
+        if (callCount === 1)
+          return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '3000000' })))
+        if (callCount === 3) return Promise.resolve(make402Response())
+        if (callCount === 4) return Promise.resolve(make402Response())
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '3',
+      })
+
+      await s.fetch('https://api.example.com/data')
+      expect(s.cumulative).toBe(1000000n)
+
+      const failed = await s.fetch('https://api.example.com/data')
+      expect(failed.status).toBe(402)
+      expect(s.cumulative).toBe(1000000n)
+
+      await s.topUp('1')
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['open', 'voucher', 'topUp'])
+      const topUpPayload = postedPayloads[2]
+      if (topUpPayload?.action !== 'topUp') throw new Error('expected top-up payload')
+      expect(topUpPayload.additionalDeposit).toBe('1000000')
+    })
+  })
+
+  describe('.sse() event parsing', () => {
+    test('yields only message data from SSE stream', async () => {
+      const events = [
+        'event: message\ndata: chunk1\n\n',
+        'event: message\ndata: chunk2\n\n',
+        `event: payment-receipt\ndata: ${JSON.stringify({
+          method: 'tempo',
+          intent: 'session',
+          status: 'success',
+          timestamp: '2025-01-01T00:00:00.000Z',
+          reference: channelId,
+          challengeId,
+          channelId,
+          acceptedCumulative: '2000000',
+          spent: '2000000',
+          units: 2,
+        } satisfies SessionReceipt)}\n\n`,
+      ]
+
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation(() => {
+        callCount++
+        if (callCount === 1) return Promise.resolve(makeSseResponse(events))
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      // Manually set channel state to skip auto-open flow
+      ;(s as any).__test_setChannel?.()
+
+      const receiptCb = vi.fn()
+      const iterable = await s.sse('https://api.example.com/stream', {
+        onReceipt: receiptCb,
+      })
+
+      const messages: string[] = []
+      for await (const msg of iterable) {
+        messages.push(msg)
+      }
+
+      expect(messages).toEqual(['chunk1', 'chunk2'])
+      expect(receiptCb).toHaveBeenCalledOnce()
+      expect(receiptCb.mock.calls[0]![0].units).toBe(2)
+    })
+
+    test('posts precompile SSE top-up vouchers with the channel descriptor', async () => {
+      const requestedUrls: string[] = []
+      const postedPayloads: SessionCredentialPayload[] = []
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation((input, init?: RequestInit) => {
+        callCount++
+        requestedUrls.push(input.toString())
+        const authorization = new Headers(init?.headers).get('Authorization')
+        if (authorization) {
+          postedPayloads.push(
+            Credential.deserialize<SessionCredentialPayload>(authorization).payload,
+          )
+        }
+        if (callCount === 1) return Promise.resolve(make402Response())
+        if (callCount === 2) {
+          const openPayload = postedPayloads[0]
+          if (openPayload?.action !== 'open') throw new Error('expected open payload')
+          const needVoucher: NeedVoucherEvent = {
+            channelId: openPayload.channelId,
+            requiredCumulative: '2000000',
+            acceptedCumulative: '1000000',
+            deposit: '10000000',
+          }
+          return Promise.resolve(
+            makeSseResponse([
+              'event: message\ndata: chunk1\n\n',
+              formatNeedVoucherEvent(needVoucher),
+              'event: message\ndata: chunk2\n\n',
+            ]),
+          )
+        }
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      const iterable = await s.sse('https://api.example.com/stream?prompt=paid')
+      const messages: string[] = []
+      for await (const msg of iterable) messages.push(msg)
+
+      expect(messages).toEqual(['chunk1', 'chunk2'])
+      expect(postedPayloads[0]?.action).toBe('open')
+      expect(postedPayloads[1]?.action).toBe('voucher')
+      const openPayload = postedPayloads[0]
+      const voucherPayload = postedPayloads[1]
+      if (openPayload?.action !== 'open' || voucherPayload?.action !== 'voucher')
+        throw new Error('expected open then voucher payloads')
+      expect(voucherPayload.channelId).toBe(openPayload.channelId)
+      expect(voucherPayload.descriptor).toEqual(openPayload.descriptor)
+      expect(voucherPayload.cumulativeAmount).toBe('2000000')
+      expect(requestedUrls[2]).toBe('https://api.example.com/stream')
+    })
+
+    test('ignores precompile SSE voucher requests for a different channel', async () => {
+      const mismatchedChannelId = `0x${'ff'.repeat(32)}` as Hex
+      const needVoucher: NeedVoucherEvent = {
+        channelId: mismatchedChannelId,
+        requiredCumulative: '2000000',
+        acceptedCumulative: '1000000',
+        deposit: '10000000',
+      }
+      const events = [
+        'event: message\ndata: chunk1\n\n',
+        formatNeedVoucherEvent(needVoucher),
+        'event: message\ndata: chunk2\n\n',
+      ]
+      const postedPayloads: SessionCredentialPayload[] = []
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        callCount++
+        const authorization = new Headers(init?.headers).get('Authorization')
+        if (authorization) {
+          postedPayloads.push(
+            Credential.deserialize<SessionCredentialPayload>(authorization).payload,
+          )
+        }
+        if (callCount === 1) return Promise.resolve(make402Response())
+        if (callCount === 2) return Promise.resolve(makeSseResponse(events))
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      const iterable = await s.sse('https://api.example.com/stream')
+      const messages: string[] = []
+      for await (const msg of iterable) messages.push(msg)
+
+      expect(messages).toEqual(['chunk1', 'chunk2'])
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['open'])
+      expect(callCount).toBe(2)
+    })
+
+    test('retries for the event stream after an open management response', async () => {
+      const postedPayloads: SessionCredentialPayload[] = []
+      let callCount = 0
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        callCount++
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) postedPayloads.push(payload)
+
+        if (!payload) {
+          return Promise.resolve(make402Response(makeChallenge({ suggestedDeposit: '5000000' })))
+        }
+
+        if (payload.action === 'open') {
+          return Promise.resolve(
+            new Response(null, {
+              status: 200,
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: 1_000_000n,
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: 1_000_000n,
+                    units: 1,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+
+        if (payload.action === 'voucher') {
+          return Promise.resolve(
+            makeSseResponse([
+              'event: message\ndata: chunk1\n\n',
+              'event: message\ndata: chunk2\n\n',
+              `event: payment-receipt\ndata: ${JSON.stringify(
+                createSessionReceipt({
+                  acceptedCumulative: BigInt(payload.cumulativeAmount),
+                  challengeId,
+                  channelId: payload.channelId,
+                  spent: BigInt(payload.cumulativeAmount),
+                  units: 2,
+                }),
+              )}\n\n`,
+            ]),
+          )
+        }
+
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+      })
+
+      const iterable = await s.sse('https://api.example.com/stream')
+      const messages: string[] = []
+      for await (const msg of iterable) messages.push(msg)
+
+      expect(messages).toEqual(['chunk1', 'chunk2'])
+      expect(postedPayloads.map((payload) => payload.action)).toEqual(['open', 'voucher'])
+      expect(callCount).toBe(4)
+      expect(s.state).toMatchObject({
+        status: 'active',
+        acceptedCumulative: '2000000',
+        deposit: '5000000',
+        spent: '2000000',
+        units: 2,
+      })
+    })
+  })
+
+  describe('error handling', () => {
+    test('.sse() silently skips payment-need-voucher when no channel open', async () => {
+      const needVoucher: NeedVoucherEvent = {
+        channelId,
+        requiredCumulative: '2000000',
+        acceptedCumulative: '1000000',
+        deposit: '10000000',
+      }
+
+      const events = [
+        'event: message\ndata: chunk1\n\n',
+        formatNeedVoucherEvent(needVoucher),
+        'event: message\ndata: chunk2\n\n',
+      ]
+
+      const mockFetch = vi.fn().mockResolvedValue(makeSseResponse(events))
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const iterable = await s.sse('https://api.example.com/stream')
+
+      const messages: string[] = []
+      for await (const msg of iterable) {
+        messages.push(msg)
+      }
+
+      expect(messages).toEqual(['chunk1', 'chunk2'])
+      expect(mockFetch).toHaveBeenCalledOnce()
+    })
+  })
+
+  describe('.sse() headers normalization', () => {
+    test('preserves Headers instance properties when passed as headers', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(makeSseResponse(['event: message\ndata: ok\n\n']))
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      const iterable = await s.sse('https://api.example.com/stream', {
+        headers: new Headers({ 'Content-Type': 'application/json', 'X-Custom': 'value' }),
+      })
+
+      for await (const _ of iterable) {
+        // drain
+      }
+
+      const calledHeaders = new Headers((mockFetch.mock.calls[0]![1] as RequestInit).headers)
+      expect(calledHeaders.get('content-type')).toBe('application/json')
+      expect(calledHeaders.get('x-custom')).toBe('value')
+      expect(calledHeaders.get('accept')).toBe('text/event-stream')
+    })
+  })
+
+  describe('.close()', () => {
+    test('is no-op when not opened', async () => {
+      const mockFetch = vi.fn()
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+      })
+
+      await s.close()
+      expect(mockFetch).not.toHaveBeenCalled()
+    })
+
+    test('tracks spent from HTTP error receipts and closes at that amount', async () => {
+      const postedPayloads: SessionCredentialPayload[] = []
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+        if (payload) postedPayloads.push(payload)
+
+        if (!payload)
+          return Promise.resolve(
+            make402Response(makeChallenge({ amount: '1', suggestedDeposit: '2' })),
+          )
+        if (payload.action === 'open') {
+          return Promise.resolve(
+            new Response('upstream failed', {
+              status: 500,
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: BigInt(payload.cumulativeAmount),
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: 1n,
+                    units: 1,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+        if (payload.action === 'close') {
+          return Promise.resolve(
+            new Response(null, {
+              status: 200,
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: BigInt(payload.cumulativeAmount),
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: BigInt(payload.cumulativeAmount),
+                    units: 1,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        decimals: 0,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '2',
+      })
+
+      const response = await s.fetch('https://api.example.com/resource')
+      expect(response.status).toBe(500)
+      expect(response.receipt?.spent).toBe('1')
+
+      const closeReceipt = await s.close()
+      expect(closeReceipt?.status).toBe('success')
+      expect(closeReceipt?.spent).toBe('1')
+      expect(s.state).toMatchObject({
+        status: 'closed',
+        channelId: closeReceipt?.channelId,
+      })
+      const closePayload = postedPayloads.find((payload) => payload.action === 'close')
+      expect(closePayload?.cumulativeAmount).toBe('1')
+    })
+
+    test('rejects receipts that exceed the locally signed voucher', async () => {
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+
+        if (!payload)
+          return Promise.resolve(
+            make402Response(makeChallenge({ amount: '1', suggestedDeposit: '3' })),
+          )
+        if (payload.action === 'open') {
+          return Promise.resolve(
+            new Response('ok', {
+              status: 200,
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: 3n,
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: 3n,
+                    units: 1,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        decimals: 0,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '3',
+      })
+
+      await expect(s.fetch('https://api.example.com/resource')).rejects.toThrow(
+        'receipt accepted cumulative exceeds local voucher state',
+      )
+    })
+
+    test('surfaces close failure problem details', async () => {
+      const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
+        const authorization = new Headers(init?.headers).get('Authorization')
+        const payload = authorization
+          ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
+          : undefined
+
+        if (!payload)
+          return Promise.resolve(
+            make402Response(makeChallenge({ amount: '1', suggestedDeposit: '2' })),
+          )
+        if (payload.action === 'open') {
+          return Promise.resolve(
+            new Response('ok', {
+              status: 200,
+              headers: {
+                'Payment-Receipt': serializeSessionReceipt(
+                  createSessionReceipt({
+                    acceptedCumulative: BigInt(payload.cumulativeAmount),
+                    challengeId,
+                    channelId: payload.channelId,
+                    spent: 1n,
+                    units: 1,
+                  }),
+                ),
+              },
+            }),
+          )
+        }
+        if (payload.action === 'close') {
+          return Promise.resolve(
+            new Response('close failed', {
+              status: 500,
+              headers: {
+                'WWW-Authenticate': 'Payment error="close_failed"',
+              },
+            }),
+          )
+        }
+        return Promise.resolve(makeOkResponse())
+      })
+
+      const s = sessionManager({
+        account,
+        client,
+        decimals: 0,
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '2',
+      })
+
+      const response = await s.fetch('https://api.example.com/resource')
+      expect(response.status).toBe(200)
+      expect(response.receipt?.spent).toBe('1')
+
+      await expect(s.close()).rejects.toThrow(
+        'Close request failed with status 500: close failed [WWW-Authenticate: Payment error="close_failed"]',
+      )
+    })
+  })
+})