mppx 0.0.1 → 0.1.0

package/src/server/Mppx.test-d.ts

@@ -0,0 +1,343 @@
+import { tempo } from 'mppx/server'
+import { createClient, http } from 'viem'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { describe, expectTypeOf, test } from 'vitest'
+import * as Intent from '../Intent.js'
+import * as MethodIntent from '../MethodIntent.js'
+import * as z from '../zod.js'
+import * as Mppx from './Mppx.js'
+
+const account = privateKeyToAccount(generatePrivateKey())
+const getClient = () => createClient({ account, transport: http() })
+
+const fooCharge = MethodIntent.fromIntent(Intent.charge, {
+  method: 'test',
+  schema: {
+    credential: {
+      payload: z.object({ signature: z.string() }),
+    },
+    request: {
+      requires: ['recipient'],
+    },
+  },
+})
+
+describe('Mppx', () => {
+  test('has methods and realm properties', () => {
+    const method = MethodIntent.toServer(fooCharge, {
+      async verify() {
+        return {
+          method: 'test',
+          reference: '0x123',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    })
+
+    const handler = Mppx.create({
+      methods: [method],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    expectTypeOf(handler.methods).toEqualTypeOf([method] as const)
+    expectTypeOf(handler.realm).toBeString()
+  })
+
+  test('has intent functions matching method intents', () => {
+    const method = MethodIntent.toServer(fooCharge, {
+      async verify() {
+        return {
+          method: 'test',
+          reference: '0x123',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    })
+
+    const handler = Mppx.create({
+      methods: [method],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    expectTypeOf(handler.charge).toBeFunction()
+  })
+
+  test('intent function options include request', () => {
+    const method = MethodIntent.toServer(fooCharge, {
+      async verify() {
+        return {
+          method: 'test',
+          reference: '0x123',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    })
+
+    const handler = Mppx.create({
+      methods: [method],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    handler.charge({
+      amount: '1000',
+      currency: '0x1234',
+      decimals: 6,
+      expires: '2025-01-01T00:00:00Z',
+      recipient: '0xabc',
+    })
+  })
+
+  test('intent function returns handler that accepts Request', async () => {
+    const method = MethodIntent.toServer(fooCharge, {
+      async verify() {
+        return {
+          method: 'test',
+          reference: '0x123',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    })
+
+    const handler = Mppx.create({
+      methods: [method],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    const chargeHandler = handler.charge({
+      amount: '1000',
+      currency: '0x1234',
+      decimals: 6,
+      expires: '2025-01-01T00:00:00Z',
+      recipient: '0xabc',
+    })
+
+    const result = await chargeHandler(new Request('https://example.com'))
+
+    if (result.status === 402) {
+      expectTypeOf(result.challenge).toEqualTypeOf<Response>()
+    } else {
+      expectTypeOf(result.withReceipt).toBeFunction()
+    }
+  })
+
+  test('multiple method intents', () => {
+    const authorize = Intent.from({
+      name: 'authorize',
+      schema: {
+        request: z.object({
+          scope: z.string(),
+          duration: z.number(),
+        }),
+      },
+    })
+
+    const fooAuthorize = MethodIntent.fromIntent(authorize, {
+      method: 'test',
+      schema: {
+        credential: {
+          payload: z.object({ token: z.string() }),
+        },
+      },
+    })
+
+    const chargeMethod = MethodIntent.toServer(fooCharge, {
+      defaults: {
+        currency: '0x1234',
+        recipient: '0xabc',
+      },
+      async verify() {
+        return {
+          method: 'test',
+          reference: '0x123',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    })
+
+    const authorizeMethod = MethodIntent.toServer(fooAuthorize, {
+      async verify() {
+        return {
+          method: 'test',
+          reference: '0x456',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    })
+
+    const handler = Mppx.create({
+      methods: [chargeMethod, authorizeMethod],
+      realm: 'api.example.com',
+      secretKey: 'secret',
+    })
+
+    handler.charge({
+      amount: '1000',
+      currency: '0x1234',
+      decimals: 6,
+      recipient: '0xabc',
+    })
+
+    handler.authorize({
+      scope: 'read',
+      duration: 3600,
+    })
+  })
+
+  describe('defaults', () => {
+    test('defaulted fields are optional in intent options', () => {
+      const handler = Mppx.create({
+        methods: [tempo({ currency: '0x1234', recipient: '0xabc', getClient })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+
+      // currency and recipient should be optional since they're in defaults
+      handler.charge({
+        amount: '1000',
+        decimals: 6,
+      })
+
+      // But can still be overridden
+      handler.charge({
+        amount: '1000',
+        currency: '0x5678',
+        decimals: 6,
+        recipient: '0xdef',
+      })
+    })
+
+    test('non-defaulted fields remain required', () => {
+      const handler = Mppx.create({
+        methods: [tempo({ currency: '0x1234', getClient })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+
+      // recipient is still required since it's not in defaults
+      handler.charge({
+        amount: '1000',
+        decimals: 6,
+        recipient: '0xabc',
+      })
+    })
+
+    test('no defaults means all fields required', () => {
+      const handler = Mppx.create({
+        methods: [tempo({ getClient })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+
+      // All required fields must be provided
+      handler.charge({
+        amount: '1000',
+        currency: '0x1234',
+        decimals: 6,
+        recipient: '0xabc',
+      })
+    })
+
+    test('type: defaulted fields are optional in options type', () => {
+      const handler = Mppx.create({
+        methods: [tempo({ currency: '0x1234', recipient: '0xabc', getClient })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+
+      type ChargeOptions = Parameters<typeof handler.charge>[0]
+
+      // currency and recipient should be optional (include undefined)
+      expectTypeOf<ChargeOptions['currency']>().toEqualTypeOf<string | undefined>()
+      expectTypeOf<ChargeOptions['recipient']>().toEqualTypeOf<string | undefined>()
+
+      // amount should still be required (no undefined)
+      expectTypeOf<ChargeOptions['amount']>().toEqualTypeOf<string>()
+    })
+
+    test('account as Account defaults recipient', () => {
+      const handler = Mppx.create({
+        methods: [tempo.charge({ currency: '0x1234', account })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+
+      // recipient is defaulted via account, so it should be optional
+      handler.charge({
+        amount: '1000',
+        decimals: 6,
+      })
+
+      // can still override recipient
+      handler.charge({
+        amount: '1000',
+        decimals: 6,
+        recipient: '0xdef',
+      })
+    })
+
+    test('account as Account with feePayer: true', () => {
+      const handler = Mppx.create({
+        methods: [tempo.charge({ currency: '0x1234', account, feePayer: true })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+
+      handler.charge({
+        amount: '1000',
+        decimals: 6,
+      })
+    })
+  })
+
+  describe('session getClient', () => {
+    test('tempo.session requires getClient', () => {
+      Mppx.create({
+        methods: [
+          tempo.session({
+            currency: '0x1234',
+            recipient: '0xabc',
+            getClient,
+          }),
+        ],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+    })
+
+    test('combined tempo() requires getClient', () => {
+      Mppx.create({
+        methods: [tempo({ currency: '0x1234', recipient: '0xabc', getClient })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+    })
+
+    test('tempo.charge does not require getClient', () => {
+      Mppx.create({
+        methods: [tempo.charge({ currency: '0x1234', recipient: '0xabc' })],
+        realm: 'api.example.com',
+        secretKey: 'secret',
+      })
+    })
+  })
+})
+
+describe('create.Config', () => {
+  test('requires methods, realm, and secretKey', () => {
+    type Config = Mppx.create.Config
+
+    expectTypeOf<Config>().toHaveProperty('methods')
+    expectTypeOf<Config>().toHaveProperty('realm')
+    expectTypeOf<Config>().toHaveProperty('secretKey')
+  })
+})

package/src/server/Mppx.test.ts

@@ -0,0 +1,342 @@
+import { Challenge, Credential, Intent, MethodIntent, z } from 'mppx'
+import { Mppx, Transport, tempo } from 'mppx/server'
+import { describe, expect, test } from 'vitest'
+import * as Http from '~test/Http.js'
+import { accounts, asset, client } from '~test/tempo/viem.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+const method = tempo({
+  getClient: () => client,
+})
+
+describe('create', () => {
+  test('default', () => {
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+
+    expect(handler.realm).toBe(realm)
+    expect(handler.transport.name).toBe('http')
+    expect(typeof handler.charge).toBe('function')
+  })
+
+  test('behavior: with mcp transport', () => {
+    const handler = Mppx.create({ methods: [method], realm, secretKey, transport: Transport.mcp() })
+
+    expect(handler.transport.name).toBe('mcp')
+  })
+})
+
+describe('request handler', () => {
+  test('returns 402 when no Authorization header', async () => {
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+
+    const request = new Request('https://example.com/resource')
+
+    const result = await handler.charge({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })(request)
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    expect(result.challenge.headers.get('WWW-Authenticate')).toContain('Payment')
+
+    const body = (await result.challenge.json()) as object
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "Payment is required for "api.example.com".",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "PaymentRequiredError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-required",
+      }
+    `)
+  })
+
+  test('returns 402 with challenge for malformed credential', async () => {
+    const request = new Request('https://example.com/resource', {
+      headers: { Authorization: 'Payment invalid' },
+    })
+
+    const result = await Mppx.create({ methods: [method], realm, secretKey }).charge({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })(request)
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const body = (await result.challenge.json()) as object
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "Credential is malformed: Invalid base64url or JSON..",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "MalformedCredentialError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/malformed-credential",
+      }
+    `)
+  })
+
+  test('returns 402 when challenge ID mismatch', async () => {
+    const wrongChallenge = Challenge.from({
+      id: 'wrong-id',
+      intent: 'charge',
+      method: 'tempo',
+      realm,
+      request: { amount: '1000', currency: asset, recipient: accounts[0].address },
+    })
+    const credential = Credential.from({
+      challenge: wrongChallenge,
+      payload: { signature: '0x123', type: 'transaction' },
+    })
+
+    const request = new Request('https://example.com/resource', {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+
+    const result = await Mppx.create({ methods: [method], realm, secretKey }).charge({
+      amount: '1000',
+      currency: asset,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: accounts[0].address,
+    })(request)
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const body = (await result.challenge.json()) as object
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "Challenge "wrong-id" is invalid: challenge was not issued by this server.",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "InvalidChallengeError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge",
+      }
+    `)
+  })
+
+  test('returns 402 when payload schema validation fails', 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,
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+
+    const credential = Credential.from({
+      challenge,
+      payload: { invalidField: 'bad' },
+    })
+
+    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 { detail: string }
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      detail: '[detail]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "[detail]",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "InvalidPayloadError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/invalid-payload",
+      }
+    `)
+    expect(body.detail).toContain('Credential payload is invalid')
+  })
+})
+
+describe('request handler (node)', () => {
+  test('returns 402 when no Authorization header', async () => {
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+
+    const server = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        handler.charge({
+          amount: '1000',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const response = await fetch(server.url)
+    expect(response.status).toBe(402)
+    expect(response.headers.get('WWW-Authenticate')).toContain('Payment')
+
+    const body = (await response.json()) as object
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "Payment is required for "api.example.com".",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "PaymentRequiredError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/payment-required",
+      }
+    `)
+
+    server.close()
+  })
+
+  test('returns 200 with Payment-Receipt header on success', async () => {
+    const handler = Mppx.create({ methods: [method], realm, secretKey })
+    const expires = new Date(Date.now() + 60_000).toISOString()
+
+    const server = await Http.createServer(async (req, res) => {
+      const result = await Mppx.toNodeListener(
+        handler.charge({
+          amount: '1000',
+          currency: asset,
+          expires,
+          recipient: accounts[0].address,
+        }),
+      )(req, res)
+      if (result.status === 402) return
+      res.end('OK')
+    })
+
+    const firstResponse = await fetch(server.url)
+    expect(firstResponse.status).toBe(402)
+
+    const challenge = Challenge.fromResponse(firstResponse)
+
+    const credential = Credential.from({
+      challenge,
+      payload: { signature: '0x123', type: 'transaction' },
+    })
+
+    const response = await fetch(server.url, {
+      headers: { Authorization: Credential.serialize(credential) },
+    })
+
+    expect(response.status).toBe(402)
+
+    const body = (await response.json()) as { detail: string }
+    expect({
+      ...body,
+      challengeId: '[challengeId]',
+      detail: '[detail]',
+      instance: '[instance]',
+    }).toMatchInlineSnapshot(`
+      {
+        "challengeId": "[challengeId]",
+        "detail": "[detail]",
+        "instance": "[instance]",
+        "status": 402,
+        "title": "VerificationFailedError",
+        "type": "https://tempoxyz.github.io/payment-auth-spec/problems/verification-failed",
+      }
+    `)
+    expect(body.detail).toContain('Payment verification failed')
+
+    server.close()
+  })
+})
+
+describe('receipt handling', () => {
+  test('returns 200 when verify returns a success receipt', async () => {
+    const mockCharge = MethodIntent.fromIntent(Intent.charge, {
+      method: 'mock',
+      schema: {
+        credential: {
+          payload: z.object({ token: z.string() }),
+        },
+        request: {
+          requires: ['recipient'],
+        },
+      },
+    })
+
+    const mockMethod = MethodIntent.toServer(mockCharge, {
+      async verify() {
+        return {
+          method: 'mock',
+          reference: 'tx-success-456',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    })
+
+    const handler = Mppx.create({
+      methods: [mockMethod],
+      realm,
+      secretKey,
+    })
+
+    const handle = handler.charge({
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    const firstResult = await handle(new Request('https://example.com/resource'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+
+    const credential = Credential.from({
+      challenge,
+      payload: { token: 'valid-token' },
+    })
+
+    const result = await handle(
+      new Request('https://example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(200)
+  })
+})