mppx 0.3.2 → 0.3.4

package/src/mcp-sdk/server/Transport.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, test } from 'vitest'
+import type { Challenge } from '../../Challenge.js'
+import type { Credential } from '../../Credential.js'
+import { VerificationFailedError } from '../../Errors.js'
+import * as Mcp from '../../Mcp.js'
+import { type Extra, mcpSdk } from './Transport.js'
+
+const challenge: Challenge = {
+  id: 'test-challenge-id',
+  realm: 'api.example.com',
+  method: 'tempo',
+  intent: 'session',
+  request: { amount: '1000000' },
+}
+
+const credential: Credential = {
+  challenge,
+  payload: {
+    action: 'voucher',
+    channelId: '0xabc',
+    cumulativeAmount: '1000000',
+    signature: '0x1234',
+  },
+  source: 'did:pkh:eip155:42431:0x1111111111111111111111111111111111111111',
+}
+
+describe('mcpSdk', () => {
+  describe('getCredential', () => {
+    test('returns credential from _meta', () => {
+      const transport = mcpSdk()
+      const extra: Extra = {
+        _meta: {
+          [Mcp.credentialMetaKey]: credential,
+        },
+      }
+      const result = transport.getCredential(extra)
+      expect(result).toEqual(credential)
+    })
+
+    test('returns null when _meta is undefined', () => {
+      const transport = mcpSdk()
+      const extra: Extra = {}
+      const result = transport.getCredential(extra)
+      expect(result).toBeNull()
+    })
+
+    test('returns null when credential key is missing', () => {
+      const transport = mcpSdk()
+      const extra: Extra = { _meta: { otherKey: 'value' } }
+      const result = transport.getCredential(extra)
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('respondChallenge', () => {
+    test('creates McpError with correct code and challenge data', async () => {
+      const transport = mcpSdk()
+      const result = await transport.respondChallenge({
+        challenge,
+        input: {} as Extra,
+      })
+
+      expect(result).toBeInstanceOf(Error)
+      const err = result as any
+      expect(err.code).toBe(Mcp.paymentRequiredCode)
+      expect(err.message).toContain('Payment Required')
+      expect(err.data?.httpStatus).toBe(402)
+      expect(err.data?.challenges).toEqual([challenge])
+    })
+
+    test('includes problem details when error is provided', async () => {
+      const transport = mcpSdk()
+      const error = new VerificationFailedError({ reason: 'bad signature' })
+      const result = await transport.respondChallenge({
+        challenge,
+        error,
+        input: {} as Extra,
+      })
+
+      const err = result as any
+      expect(err.code).toBe(Mcp.paymentRequiredCode)
+      expect(err.message).toContain('verification failed')
+      expect(err.data?.problem).toBeDefined()
+      expect(err.data?.problem?.type).toBe(error.type)
+      expect(err.data?.problem?.challengeId).toBe(challenge.id)
+    })
+
+    test('uses default message when no error provided', async () => {
+      const transport = mcpSdk()
+      const result = await transport.respondChallenge({
+        challenge,
+        input: {} as Extra,
+      })
+      const err = result as any
+      expect(err.message).toContain('Payment Required')
+    })
+  })
+
+  describe('respondReceipt', () => {
+    test('attaches receipt to response _meta', () => {
+      const transport = mcpSdk()
+      const receipt = {
+        method: 'tempo',
+        status: 'success' as const,
+        timestamp: '2025-06-15T12:00:00.000Z',
+        reference: '0xabc',
+      }
+
+      const response = {
+        content: [{ type: 'text' as const, text: 'hello' }],
+      }
+
+      const result = transport.respondReceipt({
+        challengeId: 'test-challenge-id',
+        receipt,
+        response,
+      })
+
+      expect(result._meta?.[Mcp.receiptMetaKey]).toEqual({
+        ...receipt,
+        challengeId: 'test-challenge-id',
+      })
+    })
+
+    test('preserves existing _meta fields', () => {
+      const transport = mcpSdk()
+      const receipt = {
+        method: 'tempo',
+        status: 'success' as const,
+        timestamp: '2025-06-15T12:00:00.000Z',
+        reference: '0xabc',
+      }
+
+      const response = {
+        _meta: { existingKey: 'value' },
+        content: [{ type: 'text' as const, text: 'hello' }],
+      }
+
+      const result = transport.respondReceipt({
+        challengeId: 'cid',
+        receipt,
+        response,
+      })
+
+      expect(result._meta?.existingKey).toBe('value')
+      expect(result._meta?.[Mcp.receiptMetaKey]).toBeDefined()
+    })
+
+    test('preserves response content', () => {
+      const transport = mcpSdk()
+      const receipt = {
+        method: 'tempo',
+        status: 'success' as const,
+        timestamp: '2025-06-15T12:00:00.000Z',
+        reference: '0xabc',
+      }
+
+      const response = {
+        content: [{ type: 'text' as const, text: 'result data' }],
+      }
+
+      const result = transport.respondReceipt({
+        challengeId: 'cid',
+        receipt,
+        response,
+      })
+
+      expect(result.content).toEqual(response.content)
+    })
+  })
+})

package/src/middlewares/express.test.ts

@@ -6,7 +6,7 @@ import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow } from '~test/tempo/stream.js'
+import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: express.Express) {

package/src/middlewares/hono.test.ts

@@ -7,7 +7,7 @@ import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow } from '~test/tempo/stream.js'
+import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: Hono) {

package/src/middlewares/nextjs.test.ts

@@ -6,7 +6,7 @@ import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vitest'
-import { deployEscrow } from '~test/tempo/stream.js'
+import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(handler: (request: Request) => Promise<Response> | Response) {

package/src/server/Mppx.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import * as Challenge from '../Challenge.js'
 import type * as Credential from '../Credential.js'
 import * as Errors from '../Errors.js'
+import * as Env from '../internal/env.js'
 import type * as Method from '../Method.js'
 import type * as Receipt from '../Receipt.js'
 import type * as z from '../zod.js'
@@ -72,8 +73,8 @@ export function create<
   const transport extends Transport.AnyTransport = Transport.Http,
 >(config: create.Config<methods, transport>): Mppx<methods, transport> {
   const {
-    realm = 'MPP Payment',
-    secretKey = 'tmp',
+    realm = Env.get('realm'),
+    secretKey = Env.get('secretKey'),
     transport = Transport.http() as transport,
   } = config
 
@@ -104,9 +105,9 @@ export declare namespace create {
   > = {
     /** Array of configured methods. @example [tempo()] */
     methods: methods
-    /** Server realm (e.g., hostname). @default "MPP Payment". */
+    /** Server realm (e.g., hostname). Auto-detected from environment variables (`MPP_REALM`, `VERCEL_URL`, `RAILWAY_PUBLIC_DOMAIN`, `RENDER_EXTERNAL_HOSTNAME`, `HOST`, `HOSTNAME`), falling back to `"localhost"`. */
     realm?: string | undefined
-    /** Secret key for HMAC-bound challenge IDs for stateless verification. */
+    /** Secret key for HMAC-bound challenge IDs for stateless verification. Auto-detected from `MPP_SECRET_KEY` environment variable, falling back to a random key. */
     secretKey?: string | undefined
     /** Transport to use. @default Transport.http() */
     transport?: transport | undefined

package/src/server/Transport.test.ts

@@ -124,7 +124,7 @@ describe('http', () => {
 
       expect(response.status).toBe(410)
       const body = await response.json()
-      expect(body.type).toBe('https://paymentauth.org/problems/stream/channel-finalized')
+      expect(body.type).toBe('https://paymentauth.org/problems/session/channel-finalized')
       expect(body.status).toBe(410)
     })
   })

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

@@ -0,0 +1,290 @@
+import { Hex } from 'ox'
+import { type Address, createClient } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { Addresses } from 'viem/tempo'
+import { beforeAll, describe, expect, test } from 'vitest'
+import { deployEscrow, openChannel } from '~test/tempo/session.js'
+import { accounts, asset, chain, client, fundAccount, http } from '~test/tempo/viem.js'
+import type { Challenge } from '../../Challenge.js'
+import * as Credential from '../../Credential.js'
+import { verifyVoucher } from '../session/Voucher.js'
+import {
+  createClosePayload,
+  createOpenPayload,
+  createVoucherPayload,
+  resolveEscrow,
+  serializeCredential,
+  tryRecoverChannel,
+} from './ChannelOps.js'
+
+const escrow42431 = '0x542831e3E4Ace07559b7C8787395f4Fb99F70787' as Address
+
+const localAccount = privateKeyToAccount(
+  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+)
+const localClient = createClient({
+  account: localAccount,
+  transport: http('http://127.0.0.1'),
+})
+
+const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex.Hex
+const escrowContract = '0x1234567890abcdef1234567890abcdef12345678' as Address
+const chainId = 42431
+
+function makeChallenge(overrides?: Partial<Challenge>): Challenge {
+  return {
+    id: 'test-id',
+    realm: 'test.com',
+    method: 'tempo',
+    intent: 'session',
+    request: { amount: '1000000' },
+    ...overrides,
+  }
+}
+
+describe('resolveEscrow', () => {
+  test('prefers challenge.request.methodDetails.escrowContract', () => {
+    const challenge = {
+      request: { methodDetails: { escrowContract: '0xChallengeEscrow' } },
+    }
+    const result = resolveEscrow(challenge, 42431, '0xOverride' as Address)
+    expect(result).toBe('0xChallengeEscrow')
+  })
+
+  test('falls back to escrowContractOverride', () => {
+    const challenge = { request: { methodDetails: {} } }
+    const result = resolveEscrow(challenge, 42431, '0xOverride' as Address)
+    expect(result).toBe('0xOverride')
+  })
+
+  test('falls back to defaults when no override', () => {
+    const challenge = { request: {} }
+    const result = resolveEscrow(challenge, 42431)
+    expect(result).toBe(escrow42431)
+  })
+
+  test('throws when no escrow available', () => {
+    const challenge = { request: {} }
+    expect(() => resolveEscrow(challenge, 99999)).toThrow('No `escrowContract` available')
+  })
+
+  test('falls back to defaults when methodDetails is undefined', () => {
+    const challenge = { request: { methodDetails: undefined } }
+    const result = resolveEscrow(challenge, 42431)
+    expect(result).toBe(escrow42431)
+  })
+})
+
+describe('serializeCredential', () => {
+  test('produces correct DID source string', () => {
+    const challenge = makeChallenge()
+    const payload = {
+      action: 'voucher' as const,
+      channelId,
+      cumulativeAmount: '1000000',
+      signature: '0xsig' as `0x${string}`,
+    }
+
+    const result = serializeCredential(challenge, payload, 42431, localAccount)
+
+    expect(result).toMatch(/^Payment /)
+    const deserialized = Credential.deserialize(result)
+    expect(deserialized.source).toBe(`did:pkh:eip155:42431:${localAccount.address}`)
+  })
+
+  test('encodes chainId in DID source', () => {
+    const challenge = makeChallenge()
+    const payload = {
+      action: 'voucher' as const,
+      channelId,
+      cumulativeAmount: '1000000',
+      signature: '0xsig' as `0x${string}`,
+    }
+
+    const result = serializeCredential(challenge, payload, 4217, localAccount)
+    const deserialized = Credential.deserialize(result)
+    expect(deserialized.source).toContain('did:pkh:eip155:4217:')
+  })
+})
+
+describe('createVoucherPayload', () => {
+  test('returns voucher payload with valid signature', async () => {
+    const result = await createVoucherPayload(
+      localClient,
+      localAccount,
+      channelId,
+      5_000_000n,
+      escrowContract,
+      chainId,
+    )
+
+    expect(result.action).toBe('voucher')
+    expect(result.channelId).toBe(channelId)
+    if (result.action !== 'voucher') throw new Error('unexpected action')
+    expect(result.cumulativeAmount).toBe('5000000')
+    expect(result.signature).toMatch(/^0x[0-9a-f]{130}$/)
+
+    const valid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId, cumulativeAmount: 5_000_000n, signature: result.signature },
+      localAccount.address,
+    )
+    expect(valid).toBe(true)
+  })
+})
+
+describe('createClosePayload', () => {
+  test('returns close payload with valid signature', async () => {
+    const result = await createClosePayload(
+      localClient,
+      localAccount,
+      channelId,
+      5_000_000n,
+      escrowContract,
+      chainId,
+    )
+
+    expect(result.action).toBe('close')
+    expect(result.channelId).toBe(channelId)
+    if (result.action !== 'close') throw new Error('unexpected action')
+    expect(result.cumulativeAmount).toBe('5000000')
+    expect(result.signature).toMatch(/^0x[0-9a-f]{130}$/)
+
+    const valid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId, cumulativeAmount: 5_000_000n, signature: result.signature },
+      localAccount.address,
+    )
+    expect(valid).toBe(true)
+  })
+})
+
+describe('createOpenPayload', () => {
+  const payer = accounts[2]
+  const payee = accounts[1].address
+  const currency = asset
+
+  let escrow: Address
+
+  beforeAll(async () => {
+    escrow = await deployEscrow()
+    await fundAccount({ address: payer.address, token: Addresses.pathUsd })
+    await fundAccount({ address: payer.address, token: currency })
+  })
+
+  test('returns entry with correct fields and valid payload', async () => {
+    const payerClient = createClient({
+      account: payer,
+      chain,
+      transport: http(),
+    })
+
+    const result = await createOpenPayload(payerClient, payer, {
+      escrowContract: escrow,
+      payee,
+      currency,
+      deposit: 10_000_000n,
+      initialAmount: 1_000_000n,
+      chainId: chain.id,
+    })
+
+    expect(result.entry.opened).toBe(true)
+    expect(result.entry.cumulativeAmount).toBe(1_000_000n)
+    expect(result.entry.escrowContract).toBe(escrow)
+    expect(result.entry.chainId).toBe(chain.id)
+    expect(result.entry.channelId).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(result.entry.salt).toMatch(/^0x/)
+
+    expect(result.payload.action).toBe('open')
+    expect(result.payload).toHaveProperty('type', 'transaction')
+    expect(result.payload).toHaveProperty('transaction')
+    expect(result.payload).toHaveProperty('signature')
+    expect(result.payload.channelId).toBe(result.entry.channelId)
+  })
+
+  test('defaults authorizedSigner to account.address', async () => {
+    const payerClient = createClient({
+      account: payer,
+      chain,
+      transport: http(),
+    })
+
+    const result = await createOpenPayload(payerClient, payer, {
+      escrowContract: escrow,
+      payee,
+      currency,
+      deposit: 10_000_000n,
+      initialAmount: 1_000_000n,
+      chainId: chain.id,
+    })
+
+    expect((result.payload as any).authorizedSigner).toBe(payer.address)
+  })
+
+  test('uses custom authorizedSigner when provided', async () => {
+    const customSigner = accounts[5].address
+    const payerClient = createClient({
+      account: payer,
+      chain,
+      transport: http(),
+    })
+
+    const result = await createOpenPayload(payerClient, payer, {
+      authorizedSigner: customSigner,
+      escrowContract: escrow,
+      payee,
+      currency,
+      deposit: 10_000_000n,
+      initialAmount: 1_000_000n,
+      chainId: chain.id,
+    })
+
+    expect((result.payload as any).authorizedSigner).toBe(customSigner)
+  })
+})
+
+describe('tryRecoverChannel', () => {
+  const payer = accounts[3]
+  const payee = accounts[1].address
+  const currency = asset
+
+  let escrow: Address
+  let existingChannelId: `0x${string}`
+
+  beforeAll(async () => {
+    escrow = await deployEscrow()
+    await fundAccount({ address: payer.address, token: Addresses.pathUsd })
+    await fundAccount({ address: payer.address, token: currency })
+
+    const salt = Hex.random(32) as `0x${string}`
+    const result = await openChannel({
+      escrow,
+      payer,
+      payee,
+      token: currency,
+      deposit: 10_000_000n,
+      salt,
+    })
+    existingChannelId = result.channelId
+  })
+
+  test('returns entry when channel has positive deposit and not finalized', async () => {
+    const result = await tryRecoverChannel(client, escrow, existingChannelId, chain.id)
+
+    expect(result).not.toBeUndefined()
+    expect(result!.channelId).toBe(existingChannelId)
+    expect(result!.cumulativeAmount).toBe(0n)
+    expect(result!.opened).toBe(true)
+    expect(result!.escrowContract).toBe(escrow)
+    expect(result!.chainId).toBe(chain.id)
+  })
+
+  test('returns undefined for non-existent channel', async () => {
+    const fakeChannelId =
+      '0x0000000000000000000000000000000000000000000000000000000000000099' as `0x${string}`
+    const result = await tryRecoverChannel(client, escrow, fakeChannelId, chain.id)
+    expect(result).toBeUndefined()
+  })
+})

package/src/tempo/client/ChannelOps.ts

@@ -18,10 +18,10 @@ import { Abis } from 'viem/tempo'
 import type { Challenge } from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
 import * as defaults from '../internal/defaults.js'
-import { escrowAbi, getOnChainChannel } from '../stream/Chain.js'
-import * as Channel from '../stream/Channel.js'
-import type { StreamCredentialPayload } from '../stream/Types.js'
-import { signVoucher } from '../stream/Voucher.js'
+import { escrowAbi, getOnChainChannel } from '../session/Chain.js'
+import * as Channel from '../session/Channel.js'
+import type { SessionCredentialPayload } from '../session/Types.js'
+import { signVoucher } from '../session/Voucher.js'
 
 export type ChannelEntry = {
   channelId: Hex.Hex
@@ -57,7 +57,7 @@ export function resolveEscrow(
 
 export function serializeCredential(
   challenge: Challenge,
-  payload: StreamCredentialPayload,
+  payload: SessionCredentialPayload,
   chainId: number,
   account: viem_Account,
 ): string {
@@ -76,7 +76,7 @@ export async function createVoucherPayload(
   escrowContract: Address,
   chainId: number,
   authorizedSigner?: Address | undefined,
-): Promise<StreamCredentialPayload> {
+): Promise<SessionCredentialPayload> {
   const signature = await signVoucher(
     client,
     account,
@@ -101,7 +101,7 @@ export async function createClosePayload(
   escrowContract: Address,
   chainId: number,
   authorizedSigner?: Address | undefined,
-): Promise<StreamCredentialPayload> {
+): Promise<SessionCredentialPayload> {
   const signature = await signVoucher(
     client,
     account,
@@ -131,7 +131,7 @@ export async function createOpenPayload(
     chainId: number
     feePayer?: boolean | undefined
   },
-): Promise<{ entry: ChannelEntry; payload: StreamCredentialPayload }> {
+): Promise<{ entry: ChannelEntry; payload: SessionCredentialPayload }> {
   const { escrowContract, payee, currency, deposit, initialAmount, chainId, feePayer } = options
   const authorizedSigner = options.authorizedSigner ?? account.address