mppx 0.8.14 → 0.8.15

package/src/tempo/session/README.md

@@ -83,6 +83,13 @@ sequenceDiagram
 route handler. `open` and `voucher` used on non-billable requests are also
 management updates.
 
+When `Fetch.from` creates an automatic `open`, it keeps the channel entry
+provisional until the server accepts the response or acknowledges the open with
+a matching receipt or session snapshot. Rejected or unacknowledged opens are
+discarded so the next request retries `open`; concurrent automatic opens for the
+same payment scope are serialized. Direct credential creation and
+`SessionManager` retain their existing lifecycle ownership.
+
 The current HTTP contract is deliberately pre-handler: voucher acceptance and
 default request charging occur before the handler runs. A handler failure can
 therefore follow an accepted voucher and recorded `spent`. Sessions does not

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

@@ -16,7 +16,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 { channelKey, createChannelStore } from './ChannelStore.js'
 import { session } from './Session.js'
 
 const account = privateKeyToAccount(
@@ -60,6 +60,13 @@ type SessionChallenge = Challenge<
   typeof Methods.session.name
 >
 
+const defaultChannelKey = channelKey({
+  chainId,
+  escrow: tip20ChannelEscrow,
+  payee: descriptor.payee,
+  token: descriptor.token,
+})
+
 function makeChallenge(overrides: Partial<SessionChallenge['request']> = {}): SessionChallenge {
   const request: SessionChallenge['request'] = {
     amount: '100',
@@ -78,6 +85,83 @@ function makeChallenge(overrides: Partial<SessionChallenge['request']> = {}): Se
   }
 }
 
+function makeSessionChallenge(
+  overrides: Partial<SessionChallenge['request']> = {},
+): SessionChallenge {
+  return makeChallenge({
+    ...overrides,
+    methodDetails: {
+      chainId,
+      escrowContract: tip20ChannelEscrow,
+      sessionProtocol: Constants.SessionProtocols.v2,
+      ...overrides.methodDetails,
+    },
+  })
+}
+
+function paymentRequired(challenge: SessionChallenge, headers?: HeadersInit): Response {
+  const responseHeaders = new Headers(headers)
+  responseHeaders.set(Constants.Headers.wwwAuthenticate, serializeChallenge(challenge))
+  return new Response(null, {
+    headers: responseHeaders,
+    status: 402,
+  })
+}
+
+function withSnapshot(
+  payload: Types.SessionCredentialPayload,
+  acceptedCumulative?: string,
+): SessionChallenge {
+  if (payload.action !== 'open') throw new Error('expected open credential')
+  return {
+    ...makeSessionChallenge({
+      methodDetails: {
+        chainId,
+        escrowContract: tip20ChannelEscrow,
+        sessionProtocol: Constants.SessionProtocols.v2,
+        sessionSnapshot: {
+          acceptedCumulative: acceptedCumulative ?? payload.cumulativeAmount,
+          chainId,
+          channelId: payload.channelId,
+          deposit: '1000',
+          descriptor: payload.descriptor,
+          escrow: tip20ChannelEscrow,
+          requiredCumulative: '200',
+          settled: '0',
+          spent: payload.cumulativeAmount,
+        },
+      },
+    }),
+    id: 'replacement-id',
+  }
+}
+
+function makeSessionMethod(
+  channelStore = createChannelStore(),
+  parameters: Partial<session.Parameters> = {},
+) {
+  return session({
+    account,
+    channelStore,
+    decimals: 0,
+    getClient: () => client,
+    maxDeposit: '1000',
+    ...parameters,
+  })
+}
+
+function makeSessionFetch(
+  fetch: typeof globalThis.fetch,
+  channelStore = createChannelStore(),
+  maxPaymentRetries?: number,
+) {
+  return Fetch.from({
+    fetch,
+    maxPaymentRetries,
+    methods: [makeSessionMethod(channelStore)],
+  })
+}
+
 function deserialize(credential: string) {
   return Credential.deserialize(credential).payload as Types.SessionCredentialPayload
 }
@@ -233,14 +317,16 @@ describe('precompile client session', () => {
       header: string | null
       method: string | undefined
     }[] = []
+    const vouchers: string[] = []
     let opened: Extract<Types.SessionCredentialPayload, { action: 'open' }> | undefined
+    const paymentRequired = () =>
+      new Response(null, {
+        status: 402,
+        headers: { [Constants.Headers.wwwAuthenticate]: serializeChallenge(challenge) },
+      })
     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) },
-        })
+      if (!authorization) return paymentRequired()
 
       const payload = deserialize(authorization)
       actions.push(payload.action)
@@ -250,6 +336,8 @@ describe('precompile client session', () => {
       }
       if (payload.action === 'topUp') return new Response(null, { status: 204 })
       if (payload.action !== 'voucher' || !opened) throw new Error('expected open voucher')
+      vouchers.push(authorization)
+      if (vouchers.length === 1) return paymentRequired()
 
       paidRequests.push({
         body: init?.body ?? null,
@@ -278,11 +366,192 @@ describe('precompile client session', () => {
     })
 
     expect(await response.text()).toBe('paid')
-    expect(actions).toEqual(['open', 'topUp', 'voucher'])
+    expect(actions).toEqual(['open', 'topUp', 'voucher', 'voucher'])
+    expect(new Set(vouchers).size).toBe(1)
     expect(paidRequests).toEqual([{ body: 'request-body', header: 'preserved', method: 'POST' }])
   })
 
-  test('does not top up a stored channel owned by another account', async () => {
+  test('retries an open rejected by a replacement challenge', async () => {
+    const challenge = makeSessionChallenge({ suggestedDeposit: '1000' })
+    const replacement = { ...challenge, id: 'replacement-id' }
+    const channelStore = createChannelStore()
+    const actions: Types.SessionCredentialPayload['action'][] = []
+    let paidRequests = 0
+    const fetch = makeSessionFetch(async (_input, init) => {
+      const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+      if (!authorization) return paymentRequired(challenge)
+      actions.push(deserialize(authorization).action)
+      if (++paidRequests === 1) return paymentRequired(replacement)
+      return new Response('rejected', { status: 500 })
+    }, channelStore)
+
+    expect((await fetch('https://example.com/resource')).status).toBe(500)
+    expect(actions).toEqual(['open', 'open'])
+    expect(await channelStore.get(defaultChannelKey)).toBeUndefined()
+  })
+
+  test('retries an open after the paid request throws', async () => {
+    const challenge = makeSessionChallenge({ suggestedDeposit: '1000' })
+    const actions: Types.SessionCredentialPayload['action'][] = []
+    const fetch = makeSessionFetch(async (_input, init) => {
+      const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+      if (!authorization) return paymentRequired(challenge)
+      actions.push(deserialize(authorization).action)
+      throw new Error('paid request failed')
+    })
+
+    await expect(fetch('https://example.com/resource')).rejects.toThrow('paid request failed')
+    await expect(fetch('https://example.com/resource')).rejects.toThrow('paid request failed')
+    expect(actions).toEqual(['open', 'open'])
+  })
+
+  test('keeps an open acknowledged by a payment receipt', async () => {
+    const challenge = makeSessionChallenge({ suggestedDeposit: '1000' })
+    const channelStore = createChannelStore()
+    const actions: Types.SessionCredentialPayload['action'][] = []
+    const credentials: string[] = []
+    let paidRequests = 0
+    const fetch = makeSessionFetch(async (_input, init) => {
+      const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+      if (!authorization) return paymentRequired(challenge)
+      const payload = deserialize(authorization)
+      actions.push(payload.action)
+      credentials.push(authorization)
+      if (++paidRequests === 1) return paymentRequired(challenge)
+      if (paidRequests > 2) return new Response('rejected', { status: 500 })
+      return paymentRequired(challenge, {
+        [Constants.Headers.paymentReceipt]: Types.serializeSessionReceipt(
+          Types.createSessionReceipt({
+            acceptedCumulative: 100n,
+            challengeId: challenge.id,
+            channelId: payload.channelId,
+            spent: 100n,
+          }),
+        ),
+      })
+    }, channelStore)
+
+    expect((await fetch('https://example.com/resource')).status).toBe(500)
+    expect(actions).toEqual(['open', 'open', 'voucher'])
+    expect(credentials[0]).toBe(credentials[1])
+    expect(await channelStore.get(defaultChannelKey)).toMatchObject({ opened: true })
+  })
+
+  test.each([
+    [
+      'keeps an open acknowledged by the final session snapshot',
+      undefined,
+      ['open', 'voucher'],
+      true,
+    ],
+    [
+      'fails closed on malformed acknowledgement snapshots without leaking the open lock',
+      'not-a-number',
+      ['open', 'open'],
+      undefined,
+    ],
+  ])('%s', async (_name, acceptedCumulative, expectedActions, expectedOpened) => {
+    const challenge = makeSessionChallenge({ suggestedDeposit: '1000' })
+    const channelStore = createChannelStore()
+    const actions: Types.SessionCredentialPayload['action'][] = []
+    let paidRequests = 0
+    const fetch = makeSessionFetch(
+      async (_input, init) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization) return paymentRequired(challenge)
+        const payload = deserialize(authorization)
+        actions.push(payload.action)
+        if (++paidRequests > 1) return new Response('rejected', { status: 500 })
+        return paymentRequired(withSnapshot(payload, acceptedCumulative))
+      },
+      channelStore,
+      1,
+    )
+
+    expect((await fetch('https://example.com/resource')).status).toBe(402)
+    expect((await fetch('https://example.com/resource')).status).toBe(500)
+    expect(actions).toEqual(expectedActions)
+    expect((await channelStore.get(defaultChannelKey))?.opened).toBe(expectedOpened)
+  })
+
+  test('keeps an acknowledged open when challenge ordering throws', async () => {
+    const challenge = makeSessionChallenge({ suggestedDeposit: '1000' })
+    const channelStore = createChannelStore()
+    const actions: Types.SessionCredentialPayload['action'][] = []
+    let ordered = 0
+    let paidRequests = 0
+    const fetch = Fetch.from({
+      fetch: async (_input, init) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization) return paymentRequired(challenge)
+        const payload = deserialize(authorization)
+        actions.push(payload.action)
+        if (++paidRequests > 1) return new Response('paid')
+        return paymentRequired(withSnapshot(payload))
+      },
+      methods: [makeSessionMethod(channelStore)],
+      orderChallenges(candidates) {
+        if (++ordered === 2) throw new Error('ordering failed')
+        return candidates
+      },
+    })
+
+    await expect(fetch('https://example.com/resource')).rejects.toThrow('ordering failed')
+    expect(await (await fetch('https://example.com/resource')).text()).toBe('paid')
+    expect(actions).toEqual(['open', 'voucher'])
+    expect(await channelStore.get(defaultChannelKey)).toMatchObject({ opened: true })
+  })
+
+  test('serializes concurrent opens against the committed channel', async () => {
+    const challenge = makeSessionChallenge()
+    const channelStore = createChannelStore()
+    const actions: Types.SessionCredentialPayload['action'][] = []
+    const vouchers: bigint[] = []
+    const firstGate = Promise.withResolvers<void>()
+    const firstRequest = Promise.withResolvers<void>()
+    const waitersReady = Promise.withResolvers<void>()
+    let credentialPlans = 0
+    const fetch = Fetch.from({
+      fetch: async (input, init) => {
+        const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+        if (!authorization) return paymentRequired(challenge)
+        const payload = deserialize(authorization)
+        actions.push(payload.action)
+        if (payload.action === 'topUp') return new Response(null, { status: 204 })
+        if (payload.action === 'voucher') vouchers.push(BigInt(payload.cumulativeAmount))
+        if (input.toString().endsWith('/first')) {
+          firstRequest.resolve()
+          await firstGate.promise
+          return new Response('paid')
+        }
+        return new Response('rejected', { status: 500 })
+      },
+      methods: [
+        makeSessionMethod(channelStore, {
+          resolveAccount() {
+            if (++credentialPlans === 3) waitersReady.resolve()
+            return account
+          },
+        }),
+      ],
+    })
+
+    const first = fetch('https://example.com/first')
+    await firstRequest.promise
+    const second = fetch('https://example.com/second')
+    const third = fetch('https://example.com/third')
+    await waitersReady.promise
+    firstGate.resolve()
+
+    expect((await first).status).toBe(200)
+    expect((await second).status).toBe(500)
+    expect((await third).status).toBe(500)
+    expect(actions).toEqual(['open', 'topUp', 'voucher', 'topUp', 'voucher'])
+    expect(vouchers).toEqual([200n, 300n])
+    expect(await channelStore.get(defaultChannelKey)).toMatchObject({ opened: true })
+  })
+
+  test('replaces a stored channel owned by another account', async () => {
     const channelStore = createChannelStore()
     const foreign = '0x0000000000000000000000000000000000000004' as Address
     await channelStore.set({
@@ -295,29 +564,21 @@ describe('precompile client session', () => {
       opened: true,
     })
     const actions: Types.SessionCredentialPayload['action'][] = []
-    const challenge = makeChallenge({
-      methodDetails: {
-        chainId,
-        escrowContract: tip20ChannelEscrow,
-        sessionProtocol: Constants.SessionProtocols.v2,
-      },
-    })
-    const fetch = Fetch.from({
-      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) },
-          })
-        actions.push(deserialize(authorization).action)
-        return new Response('paid')
-      },
-      methods: [session({ account, channelStore, decimals: 0, getClient: () => client })],
-    })
+    const challenge = makeSessionChallenge({ suggestedDeposit: '1000' })
+    const fetch = makeSessionFetch(async (_input, init) => {
+      const authorization = new Headers(init?.headers).get(Constants.Headers.authorization)
+      if (!authorization) return paymentRequired(challenge)
+      actions.push(deserialize(authorization).action)
+      return new Response('paid')
+    }, channelStore)
 
     expect(await (await fetch('https://example.com/resource')).text()).toBe('paid')
-    expect(actions).toEqual(['open'])
+    expect(await (await fetch('https://example.com/resource')).text()).toBe('paid')
+    expect(actions).toEqual(['open', 'voucher'])
+    expect(await channelStore.get(defaultChannelKey)).toMatchObject({
+      descriptor: { authorizedSigner: account.address, payer: account.address },
+      opened: true,
+    })
   })
 
   test('uses a matching server snapshot deposit when checking headroom', async () => {
@@ -519,12 +780,17 @@ describe('precompile client session', () => {
     expect(openDeposit(payload)).toBe(100n)
   })
 
-  test('rejects open when maxDeposit is below the request amount', async () => {
+  test('rejects open above maxDeposit without leaking the Fetch lock', async () => {
     const method = session({ account, decimals: 0, maxDeposit: '50', getClient: () => client })
+    const fetch = Fetch.from({
+      fetch: async () => paymentRequired(makeSessionChallenge()),
+      methods: [method],
+    })
 
-    await expect(
-      method.createCredential({ challenge: makeChallenge(), context: {} }),
-    ).rejects.toThrow('requested voucher amount 100 exceeds local maxDeposit 50')
+    for (let attempt = 0; attempt < 2; attempt++)
+      await expect(fetch('https://example.com/resource')).rejects.toThrow(
+        'requested voucher amount 100 exceeds local maxDeposit 50',
+      )
   })
 
   test('rejects explicit opening deposits below the request amount', async () => {

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

@@ -3,6 +3,7 @@ import { tempo as tempo_chain } from 'viem/chains'
 
 import * as MethodChallenge from '../../../client/internal/MethodChallenge.js'
 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'
@@ -16,6 +17,7 @@ import * as defaults from '../../internal/defaults.js'
 import * as Methods from '../../Methods.js'
 import * as Channel from '../precompile/Channel.js'
 import {
+  deserializeSessionReceipt,
   isEventStream,
   readSessionChallengeAmount,
   requireSessionCredentialContext,
@@ -35,6 +37,7 @@ import {
 } from './CredentialState.js'
 import { assertWithinMaxDeposit, resolveAutomaticTopUp } from './Runtime.js'
 import {
+  getSessionSnapshot,
   handleSseNeedVoucher,
   isTip1034SessionChallenge,
   postTopUp,
@@ -45,6 +48,67 @@ import {
 
 export { sessionContextSchema, type SessionContext } from './CredentialState.js'
 
+/** Tail promise for each payment scope, used to serialize automatic opens per store. */
+const channelTails = new WeakMap<ChannelStore, Map<string, Promise<void>>>()
+
+/** Serializes automatic opens for one payment scope across methods sharing a store. */
+async function lockChannel(store: ChannelStore, key: string) {
+  const tails = channelTails.get(store) ?? new Map<string, Promise<void>>()
+  channelTails.set(store, tails)
+  const previous = tails.get(key)
+  let unlock!: () => void
+  const current = new Promise<void>((resolve) => {
+    unlock = resolve
+  })
+  tails.set(key, current)
+  await previous
+  return () => {
+    unlock()
+    if (tails.get(key) === current) tails.delete(key)
+  }
+}
+
+function matchesOpen(
+  opened: ChannelEntry,
+  acknowledgement: { acceptedCumulative: string; channelId: string } | null | undefined,
+): boolean {
+  try {
+    return (
+      acknowledgement?.channelId.toLowerCase() === opened.channelId.toLowerCase() &&
+      BigInt(acknowledgement.acceptedCumulative) === opened.cumulativeAmount
+    )
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Returns whether the server acknowledged an open.
+ *
+ * Receipts must match the originating challenge, channel, and cumulative amount.
+ * Replacement challenges may acknowledge the same channel and amount through a
+ * session snapshot. Malformed acknowledgements are ignored.
+ */
+function acknowledgesOpen(
+  outcome: MethodResponse.AttemptOutcome,
+  challenge: TempoSessionChallenge,
+  opened: ChannelEntry,
+): boolean {
+  try {
+    const receiptHeader = outcome.response?.headers.get(Constants.Headers.paymentReceipt)
+    if (receiptHeader) {
+      const receipt = deserializeSessionReceipt(receiptHeader)
+      if (receipt.challengeId === challenge.id && matchesOpen(opened, receipt)) return true
+    }
+  } catch {}
+  return (
+    outcome.challenges?.some((candidate) => {
+      if (!isTip1034SessionChallenge(candidate)) return false
+      return matchesOpen(opened, getSessionSnapshot(candidate))
+    }) ?? false
+  )
+}
+
 /**
  * Creates the low-level TIP-1034 session payment method for use with `Mppx.create()`.
  *
@@ -100,30 +164,102 @@ export function session(parameters: session.Parameters = {}) {
     )
   }
 
+  const resolveCredentialPlan = async (
+    resolved: ChallengeContext,
+    context: CredentialContext | undefined,
+    entry: ChannelEntry | undefined,
+  ) =>
+    planCredential({
+      account: await resolveCredentialAccount(resolved, context, entry),
+      entry,
+      context,
+      decimals,
+      maxDeposit,
+      resolved,
+    })
+
   const method = Method.toClient(Methods.session, {
     canHandleChallenge: ({ challenge }) => isTip1034SessionChallenge(challenge),
     context: sessionContextSchema,
-    async createCredential({ challenge, context }) {
+    async createCredential(parameters) {
+      const { challenge, context } = parameters
       const resolved = await resolveChallengeContext({
         challenge,
         escrowOverride,
         getClient,
       })
-      const entry = await store.get(resolved.key)
-      const account = await resolveCredentialAccount(resolved, context, entry)
-      const payload = await executeCredentialPlan(
-        planCredential({
-          account,
-          entry,
-          context,
-          decimals,
-          maxDeposit,
-          resolved,
-        }),
-        sink,
-        AutoSwap.resolve(context?.autoSwap ?? autoSwapParameter, AutoSwap.defaultCurrencies),
-      )
-      return serializeCredential(challenge, payload, resolved.chainId, account)
+      const attempt = MethodResponse.getAttempt(parameters)
+      let release = () => {}
+      try {
+        let entry = await store.get(resolved.key)
+        let plan = await resolveCredentialPlan(resolved, context, entry)
+        if (attempt && plan.type === 'open') {
+          release = await lockChannel(store, resolved.key)
+          const nextEntry = await store.get(resolved.key)
+          if (nextEntry?.channelId !== entry?.channelId) {
+            entry = nextEntry
+            if (entry?.opened) {
+              await attempt.prepare()
+              entry = await store.get(resolved.key)
+            }
+            plan = await resolveCredentialPlan(resolved, context, entry)
+          }
+        }
+        let pendingOpen: ChannelEntry | undefined
+        // Defer opens only when low-level Fetch owns the response lifecycle.
+        // SessionManager unregisters this hook and keeps its existing transaction boundary.
+        const credentialSink =
+          attempt && plan.type === 'open'
+            ? {
+                store: {
+                  get: (key: string) => store.get(key),
+                  async set(next: ChannelEntry) {
+                    pendingOpen = next
+                  },
+                  delete: (key: string) => store.delete(key),
+                },
+                notifyUpdate() {},
+              }
+            : sink
+        const payload = await executeCredentialPlan(
+          plan,
+          credentialSink,
+          AutoSwap.resolve(context?.autoSwap ?? autoSwapParameter, AutoSwap.defaultCurrencies),
+        )
+        const credential = await serializeCredential(
+          challenge,
+          payload,
+          resolved.chainId,
+          plan.account,
+        )
+        if (attempt && pendingOpen) {
+          const opened = pendingOpen
+          attempt.settle = async (outcome) => {
+            const accepted =
+              outcome.status === 'accepted' || acknowledgesOpen(outcome, challenge, opened)
+            if (!accepted && outcome.status === 'pending') return false
+            try {
+              if (accepted) {
+                const current = await store.get(resolved.key)
+                if (
+                  !current?.opened ||
+                  current.channelId.toLowerCase() !== opened.channelId.toLowerCase()
+                ) {
+                  await store.set(opened)
+                  sink.notifyUpdate(opened)
+                }
+              }
+              return true
+            } finally {
+              release()
+            }
+          }
+        } else release()
+        return credential
+      } catch (error) {
+        release()
+        throw error
+      }
     },
   })