mppx 0.8.11 → 0.8.13

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

@@ -14,6 +14,7 @@ import { createSessionReceipt, serializeSessionReceipt } from '../precompile/Pro
 import type { NeedVoucherEvent, SessionReceipt } from '../precompile/Protocol.js'
 import { formatNeedVoucherEvent, parseEvent } from '../precompile/Protocol.js'
 import type { SessionCredentialPayload } from '../precompile/Protocol.js'
+import * as Voucher from '../precompile/Voucher.js'
 import { computeFallbackCloseAmount, sessionManager } from './SessionManager.js'
 
 const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex
@@ -44,6 +45,24 @@ const client = createClient({
   }),
 })
 
+function channelStateClient(state: { closeRequestedAt: number; deposit: bigint; settled: bigint }) {
+  return createClient({
+    account,
+    chain: { id: 4217 } as never,
+    transport: custom({
+      async request(args) {
+        if (args.method === 'eth_call')
+          return encodeFunctionResult({
+            abi: escrowAbi,
+            functionName: 'getChannelState',
+            result: state,
+          })
+        throw new Error(`unexpected rpc request: ${args.method}`)
+      },
+    }),
+  })
+}
+
 const storedDescriptor = {
   authorizedSigner: account.address,
   expiringNonceHash: `0x${'11'.repeat(32)}` as Hex,
@@ -332,6 +351,17 @@ describe('Session', () => {
     test('seeds a same-route HEAD snapshot and resolves the account when resuming it', async () => {
       const { store, set } = makeChannelStore()
       const posted: SessionCredentialPayload[] = []
+      const highestVoucher = {
+        channelId: storedChannelId,
+        cumulativeAmount: '1000000',
+        signature: await Voucher.signVoucher(
+          client,
+          account,
+          { channelId: storedChannelId, cumulativeAmount: 1_000_000n },
+          tip20ChannelEscrow,
+          4217,
+        ),
+      }
       const resolveAccount = vi.fn(
         (info: Parameters<NonNullable<sessionManager.Parameters['resolveAccount']>>[0]) =>
           info.account,
@@ -356,6 +386,7 @@ describe('Session', () => {
                   deposit: '10000000',
                   descriptor: storedDescriptor,
                   escrow: tip20ChannelEscrow,
+                  highestVoucher,
                   requiredCumulative: '1000000',
                   settled: '0',
                   spent: '0',
@@ -372,7 +403,11 @@ describe('Session', () => {
           ? Credential.deserialize<SessionCredentialPayload>(authorization).payload
           : undefined
         if (payload) posted.push(payload)
-        if (!payload) return Promise.resolve(make402Response())
+        if (!payload) {
+          expect(s.channelId).toBe(storedChannelId)
+          expect(s.cumulative).toBe(1_000_000n)
+          return Promise.resolve(make402Response())
+        }
         return Promise.resolve(makeOkResponse())
       })
       const s = sessionManager({
@@ -389,8 +424,8 @@ 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({
+      expect(resolveAccount).toHaveBeenCalledTimes(2)
+      expect(resolveAccount).toHaveBeenNthCalledWith(1, {
         account,
         chainId: 4217,
         operation: { authority: account.address, kind: 'authorizePaymentChannel' },
@@ -399,6 +434,103 @@ describe('Session', () => {
       expect(new Headers(contentCall?.[1]?.headers).get('Payment-Session')).toBeNull()
     })
 
+    test('does not cache a server snapshot for a channel that is closed on-chain', async () => {
+      const { store, set } = makeChannelStore()
+      const highestVoucher = {
+        channelId: storedChannelId,
+        cumulativeAmount: '1000000',
+        signature: await Voucher.signVoucher(
+          client,
+          account,
+          { channelId: storedChannelId, cumulativeAmount: 1_000_000n },
+          tip20ChannelEscrow,
+          4217,
+        ),
+      }
+      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()))
+        if (init?.method === 'HEAD')
+          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,
+                  highestVoucher,
+                  requiredCumulative: '1000000',
+                  settled: '0',
+                  spent: '0',
+                  units: 0,
+                }),
+              },
+            }),
+          )
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        bootstrap: true,
+        client: channelStateClient({ closeRequestedAt: 0, deposit: 0n, settled: 0n }),
+        fetch: mockFetch as typeof globalThis.fetch,
+        channelStore: store,
+      })
+
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(200)
+      expect(set).not.toHaveBeenCalled()
+    })
+
+    test('does not cache a server snapshot with an invalid highest voucher signature', async () => {
+      const { store, set } = makeChannelStore()
+      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()))
+        if (init?.method === 'HEAD')
+          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,
+                  highestVoucher: {
+                    channelId: storedChannelId,
+                    cumulativeAmount: '1000000',
+                    signature: `0x${'00'.repeat(64)}`,
+                  },
+                  requiredCumulative: '1000000',
+                  settled: '0',
+                  spent: '0',
+                  units: 0,
+                }),
+              },
+            }),
+          )
+        return Promise.resolve(makeOkResponse())
+      })
+      const s = sessionManager({
+        account,
+        bootstrap: true,
+        client,
+        fetch: mockFetch as typeof globalThis.fetch,
+        channelStore: store,
+      })
+
+      expect((await s.fetch('https://api.example.com/data')).status).toBe(200)
+      expect(set).not.toHaveBeenCalled()
+    })
+
     test('does not answer non-zero bootstrap charge challenges', async () => {
       const mockFetch = vi.fn().mockImplementation((_input, init?: RequestInit) => {
         const headers = new Headers(init?.headers)
@@ -1082,7 +1214,7 @@ describe('Session', () => {
       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')
+      expect(requestedUrls[2]).toBe('https://api.example.com/stream?prompt=paid')
     })
 
     test('ignores precompile SSE voucher requests for a different channel', async () => {
@@ -1321,6 +1453,7 @@ describe('Session', () => {
                     challengeId,
                     channelId: payload.channelId,
                     spent: BigInt(payload.cumulativeAmount),
+                    txHash: `0x${'aa'.repeat(32)}` as Hex,
                     units: 1,
                   }),
                 ),

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

@@ -1,22 +1,27 @@
 import type { Hex } from 'ox'
 import { parseUnits, type Address } from 'viem'
+import { tempo as tempo_chain } from 'viem/chains'
 
 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'
+import * as Account from '../../../viem/Account.js'
+import * as Client from '../../../viem/Client.js'
 import { charge as chargePlugin } from '../../client/Charge.js'
+import * as defaults from '../../internal/defaults.js'
 import type { ChannelEntry } from '../client/ChannelOps.js'
 import { createChannelStore, entryKey, type ChannelStore } from '../client/ChannelStore.js'
-import type { SessionContext } from '../client/CredentialState.js'
+import { hydrateSessionSnapshot, type SessionContext } from '../client/CredentialState.js'
 import { session as sessionPlugin } from '../client/Session.js'
+import * as Channel from '../precompile/Channel.js'
 import { deserializeSessionReceipt } from '../precompile/Protocol.js'
 import { readSessionChallengeAmount, type SessionReceipt } from '../precompile/Protocol.js'
 import {
   deserializeSnapshot as deserializeSessionSnapshot,
   serializeSnapshot as serializeSessionSnapshot,
 } from '../Snapshot.js'
+import { registerSessionManagerInternals } from './internal/SessionManager.js'
 import { createSessionReceiptCoordinator } from './ReceiptCoordinator.js'
 import { resolveCloseTarget, type CloseTarget } from './Runtime.js'
 import { assertVoucherWithinLocalLimit as assertVoucherWithinLocalAuthorization } from './Runtime.js'
@@ -34,6 +39,7 @@ import {
 import { closeSocketSession } from './Runtime.js'
 import {
   closeHttpSession,
+  getSessionSnapshot,
   isTempoSessionChallenge,
   managementInput,
   postTopUp,
@@ -46,7 +52,7 @@ import {
   type WebSocketConstructor,
   WebSocketReadyState,
 } from './Transports.js'
-import { openSseSession, type SseDriverOptions } from './Transports.js'
+import { consumeSseSessionResponse, openSseSession, type SseDriverOptions } from './Transports.js'
 import { applyTopUpResult, resolveManualTopUp, type TopUpRequirement } from './Transports.js'
 import {
   openWebSocketSession,
@@ -125,19 +131,6 @@ function isZeroAmountChargeChallenge(challenge: Challenge.Challenge) {
   }
 }
 
-/** Builds a reusable channel entry from a server session snapshot header. */
-function entryFromSnapshot(snapshot: ReturnType<typeof deserializeSessionSnapshot>): ChannelEntry {
-  return {
-    channelId: snapshot.channelId,
-    cumulativeAmount: BigInt(snapshot.acceptedCumulative),
-    deposit: BigInt(snapshot.deposit),
-    descriptor: snapshot.descriptor,
-    escrow: snapshot.escrow,
-    chainId: snapshot.chainId,
-    opened: true,
-  }
-}
-
 function requestInitWithSessionHint(
   input: RequestInfo | URL,
   init: RequestInit | undefined,
@@ -191,6 +184,12 @@ function resolveSessionManagerConfig(parameters: sessionManager.Parameters): Ses
  */
 export function sessionManager(parameters: sessionManager.Parameters): SessionManager {
   const config = resolveSessionManagerConfig(parameters)
+  const getClient = Client.getResolver({
+    chain: tempo_chain,
+    getClient: parameters.client ? () => parameters.client! : parameters.getClient,
+    rpcUrl: defaults.rpcUrl,
+  })
+  const getAccount = Account.getResolver({ account: parameters.account })
   const runtime = createSessionManagerRuntime()
   const receipts = createSessionReceiptCoordinator({
     getSocketSession: () => runtime.socketSession,
@@ -293,6 +292,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       }
     },
   })
+  MethodResponse.unregister(method)
   const chargeMethod = chargePlugin({
     account: parameters.account,
     getClient: parameters.client ? () => parameters.client! : parameters.getClient,
@@ -363,8 +363,27 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
   async function storeSnapshotHeader(response: Response): Promise<ChannelEntry | undefined> {
     const header = response.headers.get(Constants.Headers.paymentSessionSnapshot)
     if (!header) return undefined
-    const entry = entryFromSnapshot(deserializeSessionSnapshot(header))
+    const snapshot = deserializeSessionSnapshot(header)
+    const client = await getClient({ chainId: snapshot.chainId })
+    const defaultAccount = getAccount(client)
+    const authority =
+      BigInt(snapshot.descriptor.authorizedSigner) === 0n
+        ? snapshot.descriptor.payer
+        : snapshot.descriptor.authorizedSigner
+    const account =
+      (await parameters.resolveAccount?.({
+        account: defaultAccount,
+        chainId: snapshot.chainId,
+        operation: {
+          authority,
+          kind: 'authorizePaymentChannel',
+        },
+      })) ?? defaultAccount
+    const { entry, spent } = await hydrateSessionSnapshot({ account, client, snapshot })
+    assertVoucherWithinLocalLimit(entry.cumulativeAmount)
     await Promise.resolve(store.set(entry)).catch(() => undefined)
+    runtime.channel = entry
+    runtime.spent = spent
     return entry
   }
 
@@ -428,8 +447,60 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     })
   }
 
-  function getValidatedFallbackCloseAmount(target: CloseTarget) {
-    const closeAmount = getFallbackCloseAmount(target.challenge, target.channelId)
+  function validateCloseSnapshot(channel: ChannelEntry, challenge: TempoSessionChallenge) {
+    const snapshot = getSessionSnapshot(challenge)
+    if (!snapshot) return undefined
+
+    const computedSnapshotId = Channel.computeId({
+      ...snapshot.descriptor,
+      chainId: snapshot.chainId,
+      escrow: snapshot.escrow,
+    })
+    if (computedSnapshotId.toLowerCase() !== snapshot.channelId.toLowerCase()) {
+      throw new Error('close snapshot descriptor does not match its channel ID')
+    }
+    if (snapshot.channelId.toLowerCase() !== channel.channelId.toLowerCase()) {
+      throw new Error('close snapshot channel ID does not match local session')
+    }
+    if (
+      snapshot.chainId !== channel.chainId ||
+      snapshot.escrow.toLowerCase() !== channel.escrow.toLowerCase()
+    ) {
+      throw new Error('close snapshot payment scope does not match local session')
+    }
+
+    const acceptedCumulative = BigInt(snapshot.acceptedCumulative)
+    const snapshotSpent = BigInt(snapshot.spent)
+    if (acceptedCumulative < 0n || snapshotSpent < 0n) {
+      throw new Error('close snapshot amounts must not be negative')
+    }
+    if (snapshotSpent > acceptedCumulative) {
+      throw new Error('close snapshot spent exceeds accepted cumulative amount')
+    }
+    if (acceptedCumulative > channel.cumulativeAmount) {
+      throw new Error('close snapshot accepted cumulative exceeds local voucher state')
+    }
+    return { acceptedCumulative, spent: snapshotSpent }
+  }
+
+  function applyCloseSnapshot(target: CloseTarget, challenge: TempoSessionChallenge) {
+    const snapshot = validateCloseSnapshot(target.channel, challenge)
+    if (!snapshot) return
+
+    const { acceptedCumulative, spent } = snapshot
+    if (runtime.spent > acceptedCumulative) {
+      throw new Error('close snapshot accepted cumulative is below locally confirmed spend')
+    }
+    if (spent > runtime.spent) runtime.spent = spent
+  }
+
+  function getValidatedFallbackCloseAmount(
+    target: CloseTarget,
+    challenge: TempoSessionChallenge = target.challenge,
+    applySnapshot = false,
+  ) {
+    if (applySnapshot) applyCloseSnapshot(target, challenge)
+    const closeAmount = getFallbackCloseAmount(challenge, target.channelId)
     if (closeAmount > target.channel.cumulativeAmount) {
       throw new Error('fallback close amount exceeds local voucher state')
     }
@@ -467,6 +538,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       spent: runtime.spent,
     })
     if (applied?.channel && runtime.lastChallenge) {
+      await store.set(applied.channel)
       dispatch({
         type: 'activated',
         challengeId: runtime.lastChallenge.id,
@@ -623,6 +695,8 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       createSessionCredential,
       fetch: config.fetch,
       lastUrl: runtime.lastUrl,
+      resolveSignedCloseAmount: (challenge) =>
+        getValidatedFallbackCloseAmount(target, challenge, true),
       signedCloseAmount: getValidatedFallbackCloseAmount(target),
       setChallenge(challenge) {
         runtime.lastChallenge = challenge
@@ -638,6 +712,20 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     return receipt
   }
 
+  const sseDriver = {
+    createSessionCredential,
+    doFetch,
+    fetch: config.fetch,
+    getChannel: () => runtime.channel,
+    getChallenge: () => runtime.lastChallenge,
+    assertVoucherWithinLocalLimit,
+    managementInput,
+    acceptReceipt(receipt: SessionReceipt) {
+      updateSpentFromReceipt(receipt)
+    },
+    topUpIfNeeded,
+  }
+
   const self: SessionManager = {
     get channelId() {
       return runtime.channel?.channelId
@@ -673,19 +761,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     },
 
     async sse(input, init) {
-      return openSseSession(input, init, {
-        createSessionCredential,
-        doFetch,
-        fetch: config.fetch,
-        getChannel: () => runtime.channel,
-        getChallenge: () => runtime.lastChallenge,
-        assertVoucherWithinLocalLimit,
-        managementInput,
-        acceptReceipt(receipt) {
-          updateSpentFromReceipt(receipt)
-        },
-        topUpIfNeeded,
-      })
+      return openSseSession(input, init, sseDriver)
     },
 
     async ws(input, init) {
@@ -766,6 +842,38 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     },
   }
 
+  registerSessionManagerInternals(self, {
+    consumeSseResponse(input, response, options) {
+      return consumeSseSessionResponse(input, response, options, sseDriver)
+    },
+    rehydrate({ channel, challenge, input, spent }) {
+      if (!channel.opened) throw new Error('Cannot restore a closed session channel.')
+      if (!isTempoSessionChallenge(challenge)) {
+        throw new Error('Cannot restore session: challenge is not tempo/session.')
+      }
+      if (spent < 0n) throw new Error('Cannot restore session: spent must not be negative.')
+      if (spent > channel.cumulativeAmount) {
+        throw new Error('Cannot restore session: spent exceeds local voucher state.')
+      }
+      assertVoucherWithinLocalLimit(channel.cumulativeAmount)
+      const snapshot = validateCloseSnapshot(channel, challenge)
+      const restoredSpent = snapshot && snapshot.spent > spent ? snapshot.spent : spent
+
+      runtime.lastUrl = input
+      runtime.lastChallenge = challenge
+      runtime.channel = channel
+      runtime.spent = restoredSpent
+      dispatch({ type: 'challengeReceived', challengeId: challenge.id })
+      dispatch({
+        type: 'activated',
+        challengeId: challenge.id,
+        entry: channel,
+        spent: restoredSpent.toString(),
+        units: 0,
+      })
+    },
+  })
+
   return self
 }