mppx 0.6.23 → 0.6.25

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

@@ -30,11 +30,11 @@ function makeChallenge(overrides: Record<string, unknown> = {}): Challenge.Chall
   })
 }
 
-function make402Response(challenge?: Challenge.Challenge): Response {
-  const c = challenge ?? makeChallenge()
+function make402Response(...challenges: Challenge.Challenge[]): Response {
+  const entries = challenges.length ? challenges : [makeChallenge()]
   return new Response(null, {
     status: 402,
-    headers: { 'WWW-Authenticate': Challenge.serialize(c) },
+    headers: { 'WWW-Authenticate': entries.map(Challenge.serialize).join(', ') },
   })
 }
 
@@ -111,6 +111,87 @@ describe('Session', () => {
         'no `deposit` or `maxDeposit` configured',
       )
     })
+
+    test('passes supported challenges through the ordering hook', async () => {
+      const first = makeChallenge({ currency: 'pathusd' })
+      const second = makeChallenge({ currency: 'usdc' })
+      const mockFetch = vi.fn().mockResolvedValue(make402Response(first, second))
+      const orderChallenges = vi.fn(
+        (candidates: Parameters<NonNullable<sessionManager.Parameters['orderChallenges']>>[0]) =>
+          candidates.slice(1, 1),
+      )
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+        orderChallenges,
+      })
+
+      await expect(s.fetch('https://api.example.com/data')).rejects.toThrow(
+        'No method found for challenges: tempo.session, tempo.session',
+      )
+      expect(orderChallenges).toHaveBeenCalledOnce()
+      expect(
+        orderChallenges.mock.calls[0]?.[0].map(({ challenge, index }) => ({
+          currency: challenge.request.currency,
+          index,
+        })),
+      ).toEqual([
+        { currency: 'pathusd', index: 0 },
+        { currency: 'usdc', index: 1 },
+      ])
+    })
+
+    test('request-local ordering overrides the session manager ordering hook', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(make402Response())
+      const configuredOrderChallenges = vi.fn(
+        (candidates: Parameters<NonNullable<sessionManager.Parameters['orderChallenges']>>[0]) =>
+          candidates,
+      )
+      const requestOrderChallenges = vi.fn(
+        (
+          _candidates: Parameters<NonNullable<sessionManager.Parameters['orderChallenges']>>[0],
+        ) => [],
+      )
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+        orderChallenges: configuredOrderChallenges,
+      })
+
+      await expect(
+        s.fetch('https://api.example.com/data', {
+          orderChallenges: requestOrderChallenges,
+        }),
+      ).rejects.toThrow('No method found for challenges: tempo.session')
+      expect(configuredOrderChallenges).not.toHaveBeenCalled()
+      expect(requestOrderChallenges).toHaveBeenCalledOnce()
+    })
+  })
+
+  describe('.ws()', () => {
+    test('applies challenge ordering to the HTTP probe', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(make402Response())
+      const orderChallenges = vi.fn(
+        (
+          _candidates: Parameters<NonNullable<sessionManager.Parameters['orderChallenges']>>[0],
+        ) => [],
+      )
+
+      const s = sessionManager({
+        account: '0x0000000000000000000000000000000000000001',
+        fetch: mockFetch as typeof globalThis.fetch,
+        maxDeposit: '10',
+        orderChallenges,
+        webSocket: vi.fn() as never,
+      })
+
+      await expect(s.ws('wss://api.example.com/session')).rejects.toThrow(
+        'No payment challenge received from HTTP endpoint for this WebSocket URL.',
+      )
+      expect(orderChallenges).toHaveBeenCalledOnce()
+    })
   })
 
   describe('.open()', () => {

package/src/tempo/client/SessionManager.ts

@@ -4,6 +4,7 @@ import { parseUnits, type Address } from 'viem'
 import * as Challenge from '../../Challenge.js'
 import * as Fetch from '../../client/internal/Fetch.js'
 import * as PaymentCredential from '../../Credential.js'
+import * as AcceptPayment from '../../internal/AcceptPayment.js'
 import type * as Account from '../../viem/Account.js'
 import type * as Client from '../../viem/Client.js'
 import { deserializeSessionReceipt } from '../session/Receipt.js'
@@ -28,6 +29,12 @@ type CloseReadyWaiter = {
   resolve(receipt: SessionReceipt): void
 }
 
+type SessionMethod = ReturnType<typeof sessionPlugin>
+type SessionOrderChallenges = AcceptPayment.OrderChallenges<readonly [SessionMethod]>
+type SessionRequestInit = RequestInit & {
+  orderChallenges?: SessionOrderChallenges | undefined
+}
+
 const WebSocketReadyState = {
   CONNECTING: 0,
   OPEN: 1,
@@ -45,10 +52,10 @@ export type SessionManager = {
   readonly opened: boolean
 
   open(options?: { deposit?: bigint }): Promise<void>
-  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<PaymentResponse>
+  fetch(input: RequestInfo | URL, init?: SessionRequestInit): Promise<PaymentResponse>
   sse(
     input: RequestInfo | URL,
-    init?: RequestInit & {
+    init?: SessionRequestInit & {
       onReceipt?: ((receipt: SessionReceipt) => void) | undefined
       signal?: AbortSignal | undefined
     },
@@ -57,6 +64,7 @@ export type SessionManager = {
     input: string | URL,
     init?: {
       onReceipt?: ((receipt: SessionReceipt) => void) | undefined
+      orderChallenges?: SessionOrderChallenges | undefined
       protocols?: string | string[] | undefined
       signal?: AbortSignal | undefined
     },
@@ -134,6 +142,7 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       lastChallenge = challenge
       return undefined
     },
+    orderChallenges: parameters.orderChallenges,
   })
 
   function updateSpentFromReceipt(receipt: SessionReceipt | null | undefined) {
@@ -252,7 +261,10 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
     })
   }
 
-  async function doFetch(input: RequestInfo | URL, init?: RequestInit): Promise<PaymentResponse> {
+  async function doFetch(
+    input: RequestInfo | URL,
+    init?: SessionRequestInit,
+  ): Promise<PaymentResponse> {
     lastUrl = input
     const response = await wrappedFetch(input, init)
     return toPaymentResponse(response)
@@ -536,9 +548,17 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
         )
       }
 
-      const challenge = Challenge.fromResponseList(probe).find(
-        (item) => item.method === method.name && item.intent === method.intent,
+      const candidates = AcceptPayment.selectChallengeCandidates(
+        Challenge.fromResponseList(probe),
+        [method] as const,
+        AcceptPayment.resolve([method] as const).entries,
       )
+      const challenge = (
+        await resolveSessionChallengeOrder(
+          candidates,
+          init?.orderChallenges ?? parameters.orderChallenges,
+        )
+      )[0]?.challenge
       if (!challenge) {
         throw new Error(
           'No payment challenge received from HTTP endpoint for this WebSocket URL. The server may not require payment or did not advertise a challenge.',
@@ -844,7 +864,17 @@ export declare namespace sessionManager {
       fetch?: typeof globalThis.fetch | undefined
       /** Maximum deposit in human-readable units (e.g. `'10'` for 10 tokens). Converted to raw units via `decimals`. */
       maxDeposit?: string | undefined
+      /** Filters and sorts supported session challenges before credential creation. */
+      orderChallenges?: SessionOrderChallenges | undefined
       /** Optional websocket constructor for runtimes without a global WebSocket. */
       webSocket?: WebSocketConstructor | undefined
     }
 }
+
+async function resolveSessionChallengeOrder(
+  candidates: readonly AcceptPayment.ChallengeCandidate<SessionMethod>[],
+  override: SessionOrderChallenges | undefined,
+): Promise<readonly AcceptPayment.ChallengeCandidate<SessionMethod>[]> {
+  const orderChallenges = override
+  return orderChallenges ? orderChallenges(candidates) : candidates
+}

package/src/tempo/server/AtomicStore.test-d.ts

@@ -18,6 +18,17 @@ test('tempo.charge store parameter requires AtomicStore', () => {
   tempo.charge({ store: Store.memory() })
 })
 
+test('tempo.charge validateSender exposes only sender context', () => {
+  tempo.charge({
+    validateSender({ expectedSender, sender, source }) {
+      expectTypeOf(expectedSender).toEqualTypeOf<`0x${string}`>()
+      expectTypeOf(sender).toEqualTypeOf<`0x${string}`>()
+      expectTypeOf(source).toEqualTypeOf<{ address: `0x${string}`; chainId: number } | undefined>()
+      return true
+    },
+  })
+})
+
 test('tempo.session store parameter requires AtomicStore', () => {
   type SessionParameters = NonNullable<Parameters<typeof tempo.session>[0]>
   expectTypeOf<SessionParameters['store']>().toEqualTypeOf<Store.AtomicStore | undefined>()

package/src/tempo/server/Charge.test.ts

@@ -3881,6 +3881,195 @@ describe('tempo', () => {
       httpServer.close()
     })
 
+    test('server accepts hash transfers from a different source when validateSender allows it', async () => {
+      let validateSenderCalled = false
+      const validatingServer = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient() {
+              return client
+            },
+            currency: asset,
+            account: accounts[0],
+            validateSender({ expectedSender, sender, source }) {
+              validateSenderCalled = true
+              expect(sender.toLowerCase()).toBe(accounts[1].address.toLowerCase())
+              expect(expectedSender.toLowerCase()).toBe(accounts[2].address.toLowerCase())
+              expect(source).toEqual({
+                address: accounts[2].address,
+                chainId: chain.id,
+              })
+              return true
+            },
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          validatingServer.charge({ amount: '1', decimals: 6 }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await fetch(httpServer.url)
+      expect(response.status).toBe(402)
+
+      const challenge = Challenge.fromResponse(response, {
+        methods: [tempo_client.charge()],
+      })
+      const memo = Attribution.encode({ challengeId: challenge.id, serverId: challenge.realm })
+
+      const { receipt } = await Actions.token.transferSync(client, {
+        account: accounts[1],
+        amount: BigInt(challenge.request.amount),
+        memo: memo as Hex.Hex,
+        to: challenge.request.recipient as Hex.Hex,
+        token: challenge.request.currency as Hex.Hex,
+      })
+
+      const credential = Credential.from({
+        challenge,
+        payload: { hash: receipt.transactionHash, type: 'hash' as const },
+        source: `did:pkh:eip155:${chain.id}:${accounts[2].address}`,
+      })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: Credential.serialize(credential) },
+        })
+        expect(response.status).toBe(200)
+        expect(validateSenderCalled).toBe(true)
+      }
+
+      httpServer.close()
+    })
+
+    test('server rejects hash transfers that reuse one transferWithMemo for duplicate expected transfers', async () => {
+      const validatingServer = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient() {
+              return client
+            },
+            currency: asset,
+            account: accounts[0],
+            validateSender() {
+              return true
+            },
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          validatingServer.charge({
+            amount: '2',
+            currency: asset,
+            recipient: accounts[0].address,
+            splits: [{ amount: '1', recipient: accounts[0].address }],
+          }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await fetch(httpServer.url)
+      expect(response.status).toBe(402)
+
+      const challenge = Challenge.fromResponse(response, {
+        methods: [tempo_client.charge()],
+      })
+      const memo = Attribution.encode({ challengeId: challenge.id, serverId: challenge.realm })
+      const splits = challenge.request.methodDetails?.splits ?? []
+      const primaryAmount = BigInt(challenge.request.amount) - BigInt(splits[0]!.amount)
+
+      const { receipt } = await Actions.token.transferSync(client, {
+        account: accounts[1],
+        amount: primaryAmount,
+        memo: memo as Hex.Hex,
+        to: challenge.request.recipient as Hex.Hex,
+        token: challenge.request.currency as Hex.Hex,
+      })
+
+      const credential = Credential.from({
+        challenge,
+        payload: { hash: receipt.transactionHash, type: 'hash' as const },
+        source: `did:pkh:eip155:${chain.id}:${accounts[2].address}`,
+      })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: Credential.serialize(credential) },
+        })
+        expect(response.status).toBe(402)
+        const body = (await response.json()) as { detail: string }
+        expect(body.detail).toContain('no matching transfer found')
+      }
+
+      httpServer.close()
+    })
+
+    test('server skips validateSender when hash transfer source already matches', async () => {
+      const validatingServer = Mppx_server.create({
+        methods: [
+          tempo_server.charge({
+            getClient() {
+              return client
+            },
+            currency: asset,
+            account: accounts[0],
+            validateSender() {
+              throw new Error('validateSender should not run for matching senders')
+            },
+          }),
+        ],
+        realm,
+        secretKey,
+      })
+      const httpServer = await Http.createServer(async (req, res) => {
+        const result = await Mppx_server.toNodeListener(
+          validatingServer.charge({ amount: '1', decimals: 6 }),
+        )(req, res)
+        if (result.status === 402) return
+        res.end('OK')
+      })
+
+      const response = await fetch(httpServer.url)
+      expect(response.status).toBe(402)
+
+      const challenge = Challenge.fromResponse(response, {
+        methods: [tempo_client.charge()],
+      })
+      const memo = Attribution.encode({ challengeId: challenge.id, serverId: challenge.realm })
+
+      const { receipt } = await Actions.token.transferSync(client, {
+        account: accounts[1],
+        amount: BigInt(challenge.request.amount),
+        memo: memo as Hex.Hex,
+        to: challenge.request.recipient as Hex.Hex,
+        token: challenge.request.currency as Hex.Hex,
+      })
+
+      const credential = Credential.from({
+        challenge,
+        payload: { hash: receipt.transactionHash, type: 'hash' as const },
+        source: `did:pkh:eip155:${chain.id}:${accounts[1].address}`,
+      })
+
+      {
+        const response = await fetch(httpServer.url, {
+          headers: { Authorization: Credential.serialize(credential) },
+        })
+        expect(response.status).toBe(200)
+      }
+
+      httpServer.close()
+    })
+
     test('server rejects hash credentials with malformed source', async () => {
       const httpServer = await Http.createServer(async (req, res) => {
         const result = await Mppx_server.toNodeListener(

package/src/tempo/server/Charge.ts

@@ -63,6 +63,7 @@ export function charge<const parameters extends charge.Parameters>(
     feePayerPolicy,
     html,
     memo,
+    validateSender,
     waitForConfirmation = true,
   } = parameters
   const store = (parameters.store ?? Store.memory()) as Store.AtomicStore<charge.StoreItemMap>
@@ -230,10 +231,12 @@ export function charge<const parameters extends charge.Parameters>(
             })
             const receipt = await getTransactionReceipt(client, { hash })
             const sender = source?.address ?? receipt.from
-            const matchedLogs = assertTransferLogs(receipt, {
+            const matchedLogs = await assertTransferLogs(receipt, {
               currency,
               sender,
+              source,
               transfers: expectedTransfers,
+              validateSender,
             })
             // Only verify challenge binding when using auto-generated attribution memos.
             // Explicit memos (set by the server) are strictly matched by assertTransferLogs
@@ -415,7 +418,7 @@ export function charge<const parameters extends charge.Parameters>(
               const receipt = await sendRawTransactionSync(client, {
                 serializedTransaction: serializedTransaction_final,
               })
-              const matchedLogs = assertTransferLogs(receipt, {
+              const matchedLogs = await assertTransferLogs(receipt, {
                 currency,
                 sender: transaction.from! as `0x${string}`,
                 transfers,
@@ -490,6 +493,17 @@ export declare namespace charge {
 
   type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.charge>, 'feePayer' | 'recipient'>
 
+  type ValidateSender = (parameters: ValidateSenderParameters) => boolean | Promise<boolean>
+
+  type ValidateSenderParameters = {
+    /** Actual TIP-20 `Transfer.from` address. */
+    sender: `0x${string}`
+    /** Address that mppx would normally require as the sender. */
+    expectedSender: `0x${string}`
+    /** Parsed hash credential source when the credential includes one. */
+    source?: { address: `0x${string}`; chainId: number } | undefined
+  }
+
   type Parameters = {
     /** Render payment page when Accept header is text/html (e.g. in browsers) */
     html?: boolean | Html.Config | undefined
@@ -519,6 +533,12 @@ export declare namespace charge {
      * proofs are visible across all server instances.
      */
     store?: Store.AtomicStore | undefined
+    /**
+     * Validates a TIP-20 transfer sender when it differs from the credential
+     * source. Core verification still validates amount, currency, recipient,
+     * memo binding, transaction success, and replay protection.
+     */
+    validateSender?: ValidateSender | undefined
     /**
      * Whether to wait for the charge transaction to confirm on-chain before
      * responding. @default true
@@ -687,29 +707,17 @@ type TransferLog =
       address: `0x${string}`
     }
 
-function assertTransferLogs(
+async function assertTransferLogs(
   receipt: TransactionReceipt,
   parameters: {
     currency: `0x${string}`
     sender: `0x${string}`
+    source?: { address: `0x${string}`; chainId: number } | undefined
     transfers: readonly ExpectedTransfer[]
+    validateSender?: charge.ValidateSender | undefined
   },
-): TransferLog[] {
-  const transferLogs = parseEventLogs({
-    abi: Abis.tip20,
-    eventName: 'Transfer',
-    logs: receipt.logs,
-  }).map((log) => ({ ...log, kind: 'transfer' as const }))
-
-  const memoLogs = parseEventLogs({
-    abi: Abis.tip20,
-    eventName: 'TransferWithMemo',
-    logs: receipt.logs,
-  }).map((log) => ({ ...log, kind: 'memo' as const }))
-
-  // Prefer memo logs so allowAnyMemo matches TransferWithMemo before Transfer,
-  // preserving the memo for challenge binding verification.
-  const logs = [...memoLogs, ...transferLogs]
+): Promise<TransferLog[]> {
+  const logs = getTransferLogEffects(receipt)
   const used = new Set<number>()
   const matched: TransferLog[] = []
 
@@ -722,18 +730,31 @@ function assertTransferLogs(
   })
 
   for (const transfer of sorted) {
-    const matchIndex = logs.findIndex((log, index) => {
-      if (used.has(index)) return false
-      if (!TempoAddress.isEqual(log.address, parameters.currency)) return false
-      if (!TempoAddress.isEqual(log.args.from, parameters.sender)) return false
-      if (!TempoAddress.isEqual(log.args.to, transfer.recipient)) return false
-      if (log.args.amount.toString() !== transfer.amount) return false
-      if (transfer.memo) {
-        return log.kind === 'memo' && log.args.memo.toLowerCase() === transfer.memo.toLowerCase()
-      }
-      if (transfer.allowAnyMemo) return log.kind === 'transfer' || log.kind === 'memo'
-      return log.kind === 'transfer'
-    })
+    let matchIndex = -1
+    for (const [index, log] of logs.entries()) {
+      if (used.has(index)) continue
+      if (!TempoAddress.isEqual(log.address, parameters.currency)) continue
+      if (!TempoAddress.isEqual(log.args.to, transfer.recipient)) continue
+      if (log.args.amount.toString() !== transfer.amount) continue
+      const memoMatches = (() => {
+        if (transfer.memo)
+          return log.kind === 'memo' && log.args.memo.toLowerCase() === transfer.memo.toLowerCase()
+        if (transfer.allowAnyMemo) return log.kind === 'transfer' || log.kind === 'memo'
+        return log.kind === 'transfer'
+      })()
+      if (!memoMatches) continue
+      if (
+        !(await isValidTransferSender({
+          expectedSender: parameters.sender,
+          sender: log.args.from,
+          source: parameters.source,
+          validateSender: parameters.validateSender,
+        }))
+      )
+        continue
+      matchIndex = index
+      break
+    }
 
     if (matchIndex === -1) {
       throw new MismatchError('Payment verification failed: no matching transfer found.', {
@@ -750,6 +771,102 @@ function assertTransferLogs(
   return matched
 }
 
+type ParsedTransferLog =
+  | {
+      kind: 'transfer'
+      args: { from: `0x${string}`; to: `0x${string}`; amount: bigint }
+      address: `0x${string}`
+      logIndex: number
+    }
+  | {
+      kind: 'memo'
+      args: { from: `0x${string}`; to: `0x${string}`; amount: bigint; memo: `0x${string}` }
+      address: `0x${string}`
+      logIndex: number
+    }
+
+function getTransferLogEffects(receipt: TransactionReceipt): TransferLog[] {
+  const transferLogs = parseEventLogs({
+    abi: Abis.tip20,
+    eventName: 'Transfer',
+    logs: receipt.logs,
+  }).map(
+    (log) =>
+      ({
+        address: log.address,
+        args: log.args,
+        kind: 'transfer',
+        logIndex: log.logIndex,
+      }) as ParsedTransferLog,
+  )
+
+  const memoLogs = parseEventLogs({
+    abi: Abis.tip20,
+    eventName: 'TransferWithMemo',
+    logs: receipt.logs,
+  }).map(
+    (log) =>
+      ({
+        address: log.address,
+        args: log.args,
+        kind: 'memo',
+        logIndex: log.logIndex,
+      }) as ParsedTransferLog,
+  )
+
+  const logs = [...transferLogs, ...memoLogs].sort((a, b) => a.logIndex - b.logIndex)
+  const effects: TransferLog[] = []
+
+  for (let index = 0; index < logs.length; index++) {
+    const log = logs[index]!
+    const next = logs[index + 1]
+    if (next && log.kind !== next.kind && isSameTransferLog(log, next)) {
+      const memoLog = log.kind === 'memo' ? log : next.kind === 'memo' ? next : undefined
+      if (!memoLog) continue
+      effects.push({
+        address: memoLog.address,
+        args: memoLog.args,
+        kind: 'memo',
+      })
+      index++
+      continue
+    }
+
+    effects.push({
+      address: log.address,
+      args: log.args,
+      kind: log.kind,
+    } as TransferLog)
+  }
+
+  return effects
+}
+
+function isSameTransferLog(a: ParsedTransferLog, b: ParsedTransferLog): boolean {
+  return (
+    TempoAddress.isEqual(a.address, b.address) &&
+    TempoAddress.isEqual(a.args.from, b.args.from) &&
+    TempoAddress.isEqual(a.args.to, b.args.to) &&
+    a.args.amount === b.args.amount &&
+    Math.abs(a.logIndex - b.logIndex) === 1
+  )
+}
+
+async function isValidTransferSender(parameters: {
+  expectedSender: `0x${string}`
+  sender: `0x${string}`
+  source?: { address: `0x${string}`; chainId: number } | undefined
+  validateSender?: charge.ValidateSender | undefined
+}): Promise<boolean> {
+  if (TempoAddress.isEqual(parameters.sender, parameters.expectedSender)) return true
+  if (!parameters.validateSender) return false
+  return parameters.validateSender({
+    expectedSender: parameters.expectedSender,
+    sender: parameters.sender,
+    source: parameters.source,
+  })
+}
+
 /** @internal */
 function getHashStoreKey(hash: `0x${string}`): `mppx:charge:${string}` {
   return `mppx:charge:${hash.toLowerCase()}`