mppx 0.4.12 → 0.5.1

package/src/middlewares/nextjs.test.ts

@@ -1,17 +1,18 @@
 import * as http from 'node:http'
 
-import { Receipt } from 'mppx'
+import { Challenge, Credential, Receipt } from 'mppx'
 import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
 import { Mppx, discovery } from 'mppx/nextjs'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
+import * as TestHttp from '~test/Http.js'
 import { deployEscrow } from '~test/tempo/session.js'
-import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
+import { accounts, asset, chain, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(handler: (request: Request) => Promise<Response> | Response) {
-  return new Promise<{ url: string; close: () => void }>((resolve) => {
+  return new Promise<TestHttp.TestServer>((resolve) => {
     const server = http.createServer(async (req, res) => {
       const url = `http://localhost${req.url}`
       const headers = new Headers()
@@ -26,23 +27,21 @@ function createServer(handler: (request: Request) => Promise<Response> | Respons
     })
     server.listen(0, () => {
       const { port } = server.address() as { port: number }
-      resolve({
-        url: `http://localhost:${port}`,
-        close: () => server.close(),
-      })
+      resolve(TestHttp.wrapServer(server, { port, url: `http://localhost:${port}` }))
     })
   })
 }
 
 const secretKey = 'test-secret-key'
 
-describe('charge', () => {
+function createChargeHarness(feePayer: boolean) {
   const mppx = Mppx.create({
     methods: [
       tempo_server.charge({
         getClient: () => client,
         currency: asset,
         account: accounts[0],
+        ...(feePayer ? { feePayer: true } : {}),
       }),
     ],
     secretKey,
@@ -58,7 +57,13 @@ describe('charge', () => {
     ],
   })
 
+  return { fetch, mppx }
+}
+
+describe('charge', () => {
   test('returns 402 when no credential', async () => {
+    const { mppx } = createChargeHarness(false)
+
     const handler = mppx.charge({ amount: '1' })(() =>
       Response.json({ fortune: 'You will be rich' }),
     )
@@ -72,6 +77,8 @@ describe('charge', () => {
   })
 
   test('returns 200 with receipt on valid payment', async () => {
+    const { fetch, mppx } = createChargeHarness(false)
+
     const handler = mppx.charge({ amount: '1' })(() =>
       Response.json({ fortune: 'You will be rich' }),
     )
@@ -90,7 +97,108 @@ describe('charge', () => {
     server.close()
   })
 
+  test('fee payer: returns 200 with receipt on valid payment', async () => {
+    const { fetch, mppx } = createChargeHarness(true)
+
+    const handler = mppx.charge({ amount: '1' })(() =>
+      Response.json({ fortune: 'You will be rich' }),
+    )
+
+    const server = await createServer(handler)
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(Receipt.fromResponse(response).status).toBe('success')
+
+    server.close()
+  })
+
+  test('zero-amount charge creates a proof credential and receipt', async () => {
+    const { fetch, mppx } = createChargeHarness(false)
+
+    const handler = mppx.charge({ amount: '0' })((request) =>
+      Response.json({ payer: request.headers.get('Authorization') }),
+    )
+
+    const server = await createServer(handler)
+
+    const challengeResponse = await globalThis.fetch(server.url)
+    expect(challengeResponse.status).toBe(402)
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+
+    const body = (await response.json()) as { payer: string }
+    const credential = Credential.deserialize<{ signature: string; type: 'proof' }>(body.payer)
+    expect(credential.challenge.request.amount).toBe('0')
+    expect(credential.payload.type).toBe('proof')
+    expect(credential.source).toBe(`did:pkh:eip155:${chain.id}:${accounts[1].address}`)
+
+    const receipt = Receipt.fromResponse(response)
+    expect(receipt.reference).toBe(credential.challenge.id)
+
+    server.close()
+  })
+
+  test('zero-amount charge with testnet currency omission creates a proof credential', async () => {
+    const isTestnet = true
+    const mainnetCurrency = '0x20C000000000000000000000b9537d11c60E8b50' as const
+
+    const mppx = Mppx.create({
+      methods: [
+        tempo_server.charge({
+          account: accounts[0],
+          getClient: () => client,
+          ...(isTestnet ? {} : { currency: mainnetCurrency }),
+          recipient: accounts[0].address,
+          testnet: isTestnet,
+        }),
+      ],
+      secretKey,
+    })
+
+    const { fetch } = Mppx_client.create({
+      polyfill: false,
+      methods: [
+        tempo_client.charge({
+          account: accounts[1],
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const handler = mppx.charge({ amount: '0', chainId: chain.id })((request) =>
+      Response.json({ payer: request.headers.get('Authorization') }),
+    )
+
+    const server = await createServer(handler)
+
+    const challengeResponse = await globalThis.fetch(server.url)
+    expect(challengeResponse.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(challengeResponse, {
+      methods: [tempo_client.charge()],
+    })
+    expect(challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+
+    const body = (await response.json()) as { payer: string }
+    const credential = Credential.deserialize<{ signature: string; type: 'proof' }>(body.payer)
+    expect(credential.challenge.request.amount).toBe('0')
+    expect(credential.challenge.request.currency).toBe('0x20c0000000000000000000000000000000000000')
+    expect(credential.payload.type).toBe('proof')
+    expect(credential.source).toBe(`did:pkh:eip155:${chain.id}:${accounts[1].address}`)
+
+    const receipt = Receipt.fromResponse(response)
+    expect(receipt.reference).toBe(credential.challenge.id)
+
+    server.close()
+  })
+
   test('serves /openapi.json from a handler-derived route config', async () => {
+    const { mppx } = createChargeHarness(false)
+
     const pay = mppx.charge({ amount: '1' })
     const server = await createServer(
       discovery(mppx, {
@@ -119,13 +227,7 @@ describe('charge', () => {
 describe('session', () => {
   let escrowContract: Address
 
-  beforeAll(async () => {
-    escrowContract = await deployEscrow()
-    await fundAccount({ address: accounts[2].address, token: Addresses.pathUsd })
-    await fundAccount({ address: accounts[2].address, token: asset })
-  })
-
-  test('returns 402 when no credential', async () => {
+  function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
         tempo_server.session({
@@ -133,12 +235,38 @@ describe('session', () => {
           account: accounts[0],
           currency: asset,
           escrowContract,
-        }),
+          ...(feePayer ? { feePayer: accounts[1] } : {}),
+        } as any),
       ],
       secretKey,
     })
 
-    const handler = mppx.session({ amount: '1', unitType: 'token' })(() =>
+    const { fetch } = Mppx_client.create({
+      polyfill: false,
+      methods: [
+        sessionIntent({
+          account: accounts[2],
+          deposit: '10',
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    return { fetch, mppx }
+  }
+
+  beforeAll(async () => {
+    escrowContract = await deployEscrow()
+    await fundAccount({ address: accounts[1].address, token: Addresses.pathUsd })
+    await fundAccount({ address: accounts[1].address, token: asset })
+    await fundAccount({ address: accounts[2].address, token: Addresses.pathUsd })
+    await fundAccount({ address: accounts[2].address, token: asset })
+  })
+
+  test('returns 402 when no credential', async () => {
+    const { mppx } = createSessionHarness(false)
+
+    const handler = mppx.session({ amount: '1', currency: asset, unitType: 'token' })(() =>
       Response.json({ data: 'streamed' }),
     )
 
@@ -151,31 +279,9 @@ describe('session', () => {
   })
 
   test('returns 200 with receipt on valid payment', async () => {
-    const mppx = Mppx.create({
-      methods: [
-        tempo_server.session({
-          getClient: () => client,
-          account: accounts[0],
-          currency: asset,
-          escrowContract,
-          feePayer: true,
-        }),
-      ],
-      secretKey,
-    })
-
-    const { fetch } = Mppx_client.create({
-      polyfill: false,
-      methods: [
-        sessionIntent({
-          account: accounts[2],
-          deposit: '10',
-          getClient: () => client,
-        }),
-      ],
-    })
+    const { fetch, mppx } = createSessionHarness(false)
 
-    const handler = mppx.session({ amount: '1', unitType: 'token' })(() =>
+    const handler = mppx.session({ amount: '1', currency: asset, unitType: 'token' })(() =>
       Response.json({ data: 'streamed' }),
     )
 
@@ -192,4 +298,19 @@ describe('session', () => {
 
     server.close()
   })
+
+  test('fee payer: returns 200 with receipt on valid payment', async () => {
+    const { fetch, mppx } = createSessionHarness(true)
+
+    const handler = mppx.session({ amount: '1', currency: asset, unitType: 'token' })(() =>
+      Response.json({ data: 'streamed' }),
+    )
+
+    const server = await createServer(handler)
+    const response = await fetch(server.url)
+    expect(response.status).toBe(200)
+    expect(Receipt.fromResponse(response).status).toBe('success')
+
+    server.close()
+  })
 })

package/src/server/Mppx.test.ts

@@ -422,6 +422,92 @@ describe('request handler', () => {
     `)
     expect((body as { detail: string }).detail).toContain('Payment expired at')
   })
+  test('returns 402 when credential challenge has no expires (fail-closed)', async () => {
+    const handle = Mppx.create({ methods: [method], realm, secretKey }).charge({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })
+
+    // Get a valid challenge from the server to capture the exact request shape
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const serverChallenge = Challenge.fromResponse(firstResult.challenge)
+
+    // Re-create the same challenge WITHOUT expires, with a valid HMAC
+    const { expires: _, ...rest } = serverChallenge
+    const challengeNoExpires = Challenge.from({
+      secretKey,
+      realm: rest.realm,
+      method: rest.method,
+      intent: rest.intent,
+      request: rest.request,
+      ...(rest.opaque && { meta: rest.opaque }),
+    })
+
+    const credential = Credential.from({
+      challenge: challengeNoExpires,
+      payload: { signature: '0x123', type: 'transaction' },
+    })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const body = (await result.challenge.json()) as { title: string; detail: string }
+    expect(body.title).toBe('Invalid Challenge')
+    expect(body.detail).toContain('missing required expires')
+  })
+  test('returns 402 when credential challenge has malformed expires', async () => {
+    const handle = Mppx.create({ methods: [method], realm, secretKey }).charge({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })
+
+    // Get a valid challenge from the server to capture the exact request shape
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const serverChallenge = Challenge.fromResponse(firstResult.challenge)
+
+    // Re-create the challenge with a valid HMAC but inject a malformed expires
+    // by patching the challenge object after construction (bypasses zod at build time).
+    const challengeMalformed = {
+      ...serverChallenge,
+      expires: 'not-a-timestamp',
+    }
+
+    const credential = Credential.from({
+      challenge: challengeMalformed as any,
+      payload: { signature: '0x123', type: 'transaction' },
+    })
+
+    // Credential.serialize does not re-validate, so the malformed expires
+    // reaches the server. Deserialization rejects it via zod schema.
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const body = (await result.challenge.json()) as { title: string; detail: string }
+    expect(body.title).toBe('Malformed Credential')
+  })
+
   test('returns 402 when payload schema validation fails', async () => {
     const handle = Mppx.create({ methods: [method], realm, secretKey }).charge({
       amount: '1000',

package/src/server/Mppx.ts

@@ -418,14 +418,14 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           }
         }
 
-        // Reject expired credentials
-        if (credential.challenge.expires && new Date(credential.challenge.expires) < new Date()) {
+        // Reject credentials without expires (fail-closed) or with expired timestamp
+        try {
+          Expires.assert(credential.challenge.expires, credential.challenge.id)
+        } catch (error) {
           const response = await transport.respondChallenge({
             challenge,
             input,
-            error: new Errors.PaymentExpiredError({
-              expires: credential.challenge.expires,
-            }),
+            error: error as Errors.PaymentError,
           })
           return { challenge: response, status: 402 }
         }

package/src/stripe/server/Charge.ts

@@ -1,9 +1,6 @@
 import type * as Credential from '../../Credential.js'
-import {
-  PaymentActionRequiredError,
-  PaymentExpiredError,
-  VerificationFailedError,
-} from '../../Errors.js'
+import { PaymentActionRequiredError, VerificationFailedError } from '../../Errors.js'
+import * as Expires from '../../Expires.js'
 import type { LooseOmit, OneOf } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import type { StripeClient } from '../internal/types.js'
@@ -66,8 +63,7 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
       const { challenge } = credential
       const { request } = challenge
 
-      if (challenge.expires && new Date(challenge.expires) < new Date())
-        throw new PaymentExpiredError({ expires: challenge.expires })
+      Expires.assert(challenge.expires, challenge.id)
 
       const parsed = Methods.charge.schema.credential.payload.safeParse(credential.payload)
       if (!parsed.success) throw new Error('Invalid credential payload: missing or malformed spt')

package/src/tempo/Methods.test.ts

@@ -130,6 +130,32 @@ describe('charge', () => {
     expect(result.success).toBe(false)
   })
 
+  test('schema: rejects zero-amount with splits', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '0',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      splits: [
+        {
+          amount: '0.1',
+          recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        },
+      ],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('schema: accepts zero-amount without splits', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '0',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+    })
+    expect(result.success).toBe(true)
+  })
+
   test('schema: rejects invalid request', () => {
     const result = Methods.charge.schema.request.safeParse({
       amount: '1',

package/src/tempo/Methods.ts

@@ -26,6 +26,7 @@ export const charge = Method.from({
       payload: z.discriminatedUnion('type', [
         z.object({ hash: z.hash(), type: z.literal('hash') }),
         z.object({ signature: z.signature(), type: z.literal('transaction') }),
+        z.object({ signature: z.signature(), type: z.literal('proof') }),
       ]),
     },
     request: z.pipe(

package/src/tempo/client/Charge.ts

@@ -1,6 +1,11 @@
 import type * as Hex from 'ox/Hex'
 import type { Address } from 'viem'
-import { prepareTransactionRequest, sendCallsSync, signTransaction } from 'viem/actions'
+import {
+  prepareTransactionRequest,
+  sendCallsSync,
+  signTypedData,
+  signTransaction,
+} from 'viem/actions'
 import { tempo as tempo_chain } from 'viem/chains'
 import { Actions } from 'viem/tempo'
 
@@ -13,6 +18,7 @@ import * as Attribution from '../Attribution.js'
 import * as AutoSwap from '../internal/auto-swap.js'
 import * as Charge_internal from '../internal/charge.js'
 import * as defaults from '../internal/defaults.js'
+import * as Proof from '../internal/proof.js'
 import * as Methods from '../Methods.js'
 
 /**
@@ -49,11 +55,28 @@ export function charge(parameters: charge.Parameters = {}) {
       const client = await getClient({ chainId })
       const account = getAccount(client, context)
 
+      const { request } = challenge
+      const { amount, methodDetails } = request
+
+      // Zero-amount: sign EIP-712 typed data instead of creating a transaction.
+      if (BigInt(amount) === 0n) {
+        const signature = await signTypedData(client, {
+          account,
+          domain: Proof.domain(chainId!),
+          types: Proof.types,
+          primaryType: 'Proof',
+          message: Proof.message(challenge.id),
+        })
+        return Credential.serialize({
+          challenge,
+          payload: { signature, type: 'proof' },
+          source: Proof.proofSource({ address: account.address, chainId: chainId! }),
+        })
+      }
+
       const mode =
         context?.mode ?? parameters.mode ?? (account.type === 'json-rpc' ? 'push' : 'pull')
 
-      const { request } = challenge
-      const { amount, methodDetails } = request
       const currency = request.currency as Address
 
       if (parameters.expectedRecipients) {

package/src/tempo/internal/charge.test.ts

@@ -0,0 +1,66 @@
+import type { Address } from 'viem'
+import { describe, expect, test } from 'vp/test'
+
+import { getTransfers } from './charge.js'
+
+const recipient = '0x1234567890abcdef1234567890abcdef12345678' as Address
+
+describe('getTransfers', () => {
+  test('returns single transfer when no splits', () => {
+    const transfers = getTransfers({ amount: '100', recipient })
+    expect(transfers).toEqual([{ amount: '100', memo: undefined, recipient }])
+  })
+
+  test('splits amount between primary and split recipients', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    const transfers = getTransfers({
+      amount: '100',
+      methodDetails: { splits: [{ amount: '30', recipient: splitRecipient }] },
+      recipient,
+    })
+    expect(transfers).toHaveLength(2)
+    expect(transfers[0]!.amount).toBe('70')
+    expect(transfers[0]!.recipient).toBe(recipient)
+    expect(transfers[1]!.amount).toBe('30')
+    expect(transfers[1]!.recipient).toBe(splitRecipient)
+  })
+
+  test('throws when amount is zero with no splits', () => {
+    expect(() => getTransfers({ amount: '0', recipient })).toThrow(
+      'split total must be less than total amount',
+    )
+  })
+
+  test('throws when amount is zero with splits', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    expect(() =>
+      getTransfers({
+        amount: '0',
+        methodDetails: { splits: [{ amount: '0', recipient: splitRecipient }] },
+        recipient,
+      }),
+    ).toThrow()
+  })
+
+  test('throws when split total equals amount', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    expect(() =>
+      getTransfers({
+        amount: '100',
+        methodDetails: { splits: [{ amount: '100', recipient: splitRecipient }] },
+        recipient,
+      }),
+    ).toThrow('split total must be less than total amount')
+  })
+
+  test('throws when split total exceeds amount', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    expect(() =>
+      getTransfers({
+        amount: '100',
+        methodDetails: { splits: [{ amount: '200', recipient: splitRecipient }] },
+        recipient,
+      }),
+    ).toThrow('split total must be less than total amount')
+  })
+})

package/src/tempo/internal/proof.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'vp/test'
+
+import * as Proof from './proof.js'
+
+const parseProofSourceCases = [
+  {
+    expected: {
+      address: '0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141',
+      chainId: 42431,
+    },
+    name: 'parses a valid did:pkh:eip155 source',
+    source: 'did:pkh:eip155:42431:0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141',
+  },
+  {
+    expected: null,
+    name: 'rejects non-numeric chain ids',
+    source: 'did:pkh:eip155:not-a-number:0x1234',
+  },
+  {
+    expected: null,
+    name: 'rejects leading-zero chain ids',
+    source: 'did:pkh:eip155:01:0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141',
+  },
+  {
+    expected: null,
+    name: 'rejects unsafe integer chain ids',
+    source: 'did:pkh:eip155:9007199254740992:0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141',
+  },
+  {
+    expected: null,
+    name: 'rejects invalid addresses',
+    source: 'did:pkh:eip155:42431:not-an-address',
+  },
+  {
+    expected: null,
+    name: 'rejects extra path segments',
+    source: 'did:pkh:eip155:42431:0xAbCdEf1234567890AbCdEf1234567890AbCdEf12:extra',
+  },
+  {
+    expected: null,
+    name: 'rejects unsupported namespaces',
+    source: 'did:pkh:solana:42431:0xa5cc3c03994db5b0d9ba5e4f6d2efbd9f213b141',
+  },
+] as const
+
+describe('Proof', () => {
+  test('types has Proof with challengeId field', () => {
+    expect(Proof.types).toEqual({
+      Proof: [{ name: 'challengeId', type: 'string' }],
+    })
+  })
+
+  test('domain returns EIP-712 domain with name, version, chainId', () => {
+    const d = Proof.domain(42431)
+    expect(d).toEqual({ name: 'MPP', version: '1', chainId: 42431 })
+  })
+
+  test('domain uses provided chainId', () => {
+    expect(Proof.domain(1).chainId).toBe(1)
+    expect(Proof.domain(99999).chainId).toBe(99999)
+  })
+
+  test('message wraps challengeId', () => {
+    expect(Proof.message('abc123')).toEqual({ challengeId: 'abc123' })
+  })
+
+  test('proofSource constructs did:pkh DID', () => {
+    expect(Proof.proofSource({ address: '0x1234567890abcdef', chainId: 42431 })).toBe(
+      'did:pkh:eip155:42431:0x1234567890abcdef',
+    )
+  })
+
+  test('proofSource preserves address casing', () => {
+    const address = '0xAbCdEf1234567890AbCdEf1234567890AbCdEf12'
+    expect(Proof.proofSource({ address, chainId: 1 })).toBe(`did:pkh:eip155:1:${address}`)
+  })
+
+  for (const { expected, name, source } of parseProofSourceCases) {
+    test(`parseProofSource ${name}`, () => {
+      expect(Proof.parseProofSource(source)).toEqual(expected)
+    })
+  }
+})