mppx 0.6.14 → 0.6.16

package/dist/tempo/server/internal/html.gen.js.map

@@ -1 +1 @@
-{"version":3,"file":"html.gen.js","sourceRoot":"","sources":["../../../../src/tempo/server/internal/html.gen.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,IAAI,GAAG,wxucAAwxuc,CAAA"}
+{"version":3,"file":"html.gen.js","sourceRoot":"","sources":["../../../../src/tempo/server/internal/html.gen.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,MAAM,CAAC,MAAM,IAAI,GAAG,206tBAA206tB,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "main": "./dist/index.js",
   "license": "MIT",
   "files": [
@@ -105,7 +105,7 @@
     "@modelcontextprotocol/sdk": ">=1.25.0",
     "elysia": ">=1",
     "express": ">=5",
-    "hono": ">=4.12.14",
+    "hono": ">=4.12.16",
     "viem": ">=2.47.5"
   },
   "peerDependenciesMeta": {
@@ -123,8 +123,8 @@
     }
   },
   "dependencies": {
-    "incur": "^0.3.25",
-    "ox": "0.14.18",
+    "incur": "^0.4.5",
+    "ox": "0.14.20",
     "zod": "^4.3.6"
   },
   "repository": {

package/src/Challenge.test.ts

@@ -693,7 +693,8 @@ describe('opaque', () => {
       meta: { pi: 'pi_3abc123XYZ' },
     })
 
-    expect(challenge.opaque).toEqual({ pi: 'pi_3abc123XYZ' })
+    expect(challenge.meta).toEqual({ pi: 'pi_3abc123XYZ' })
+    expect(challenge.opaque).toBe('eyJwaSI6InBpXzNhYmMxMjNYWVoifQ')
     expect((challenge.request as Record<string, unknown>).opaque).toBeUndefined()
   })
 
@@ -710,10 +711,11 @@ describe('opaque', () => {
       meta: { payment_intent: 'pi_3abc123XYZ' },
     })
 
-    expect(challenge.opaque).toEqual({ payment_intent: 'pi_3abc123XYZ' })
+    expect(challenge.meta).toEqual({ payment_intent: 'pi_3abc123XYZ' })
+    expect(challenge.opaque).toBe('eyJwYXltZW50X2ludGVudCI6InBpXzNhYmMxMjNYWVoifQ')
   })
 
-  test('behavior: challenge.opaque is undefined when no meta', () => {
+  test('behavior: challenge opaque and meta are undefined when no meta', () => {
     const challenge = Challenge.from({
       id: 'abc123',
       realm: 'api.example.com',
@@ -723,9 +725,10 @@ describe('opaque', () => {
     })
 
     expect(challenge.opaque).toBeUndefined()
+    expect(challenge.meta).toBeUndefined()
   })
 
-  test('behavior: opaque roundtrips through serialize/deserialize', () => {
+  test('behavior: opaque roundtrips through serialize/deserialize as a raw string', () => {
     const original = Challenge.from({
       id: 'abc123',
       realm: 'api.example.com',
@@ -738,10 +741,21 @@ describe('opaque', () => {
     const header = Challenge.serialize(original)
     const deserialized = Challenge.deserialize(header)
 
-    expect(deserialized.opaque).toEqual({ pi: 'pi_3abc123XYZ', deposit: 'dep_456' })
+    expect(deserialized.opaque).toBe('eyJkZXBvc2l0IjoiZGVwXzQ1NiIsInBpIjoicGlfM2FiYzEyM1hZWiJ9')
+    expect(deserialized.meta).toBeUndefined()
   })
 
-  test('behavior: meta with empty object produces opaque: {}', () => {
+  test('behavior: deserialize does not parse non-json opaque', () => {
+    const header =
+      'Payment id="abc123", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwMDAwIn0", opaque="eXkgd3Jvbmc"'
+
+    const challenge = Challenge.deserialize(header)
+
+    expect(challenge.opaque).toBe('eXkgd3Jvbmc')
+    expect(challenge.meta).toBeUndefined()
+  })
+
+  test('behavior: meta with empty object produces opaque string and meta: {}', () => {
     const challenge = Challenge.from({
       id: 'abc123',
       realm: 'api.example.com',
@@ -751,7 +765,8 @@ describe('opaque', () => {
       meta: {},
     })
 
-    expect(challenge.opaque).toEqual({})
+    expect(challenge.meta).toEqual({})
+    expect(challenge.opaque).toBe('e30')
   })
 
   test('hmac: opaque affects challenge ID', () => {
@@ -844,7 +859,8 @@ describe('opaque', () => {
 
     const tampered = {
       ...challenge,
-      opaque: { pi: 'pi_TAMPERED' },
+      meta: { pi: 'pi_TAMPERED' },
+      opaque: 'eyJwaSI6InBpX1RBTVBFUkVEIn0',
     }
     expect(Challenge.verify(tampered, { secretKey: 'my-secret' })).toBe(false)
   })
@@ -863,7 +879,7 @@ describe('opaque', () => {
       },
     })
 
-    expect(challenge.opaque).toEqual({
+    expect(challenge.meta).toEqual({
       payment_intent: 'pi_3abc123XYZ',
       customer: 'cus_xyz',
       session_id: 'sess_abc',

package/src/Challenge.ts

@@ -29,8 +29,10 @@ export const Schema = z.object({
   intent: z.string(),
   /** Payment method (e.g., "tempo", "stripe"). */
   method: z.string(),
-  /** Optional server-defined correlation data. Flat string-to-string map; clients MUST NOT modify. */
-  opaque: z.optional(z.record(z.string(), z.string())),
+  /** Optional parsed server-defined correlation data. */
+  meta: z.optional(z.record(z.string(), z.string())),
+  /** Optional server-defined correlation data. Raw base64url string; clients MUST NOT modify. */
+  opaque: z.optional(z.string()),
   /** Server realm (e.g., hostname). */
   realm: z.string(),
   /** Method-specific request data. */
@@ -128,8 +130,13 @@ export function from<
   } = parameters
 
   const expires = parameters.expires as string
+  const opaque =
+    parameters.opaque ?? (meta !== undefined ? PaymentRequest.serialize(meta) : undefined)
   const id = secretKey
-    ? computeId({ ...parameters, expires, ...(meta && { opaque: meta }) }, { secretKey })
+    ? computeId(
+        { ...parameters, expires, ...(meta !== undefined && { meta }), opaque },
+        { secretKey },
+      )
     : (parameters as { id: string }).id
 
   return Schema.parse({
@@ -141,7 +148,8 @@ export function from<
     ...(description && { description }),
     ...(digest && { digest }),
     ...(expires && { expires }),
-    ...(meta && { opaque: meta }),
+    ...(meta !== undefined && { meta }),
+    ...(opaque !== undefined && { opaque }),
   }) as from.ReturnType<parameters, methods>
 }
 
@@ -170,6 +178,8 @@ export declare namespace from {
     intent: string
     /** Optional server-defined correlation data (serialized as `opaque` on the challenge). Flat string-to-string map; clients MUST NOT modify. */
     meta?: Record<string, string> | undefined
+    /** Optional raw base64url-encoded server-defined correlation data. Clients MUST NOT modify. */
+    opaque?: string | undefined
     /** Payment method (e.g., "tempo", "stripe"). */
     method: string
     /** Server realm (e.g., hostname). */
@@ -294,8 +304,9 @@ export function serialize(challenge: Challenge): string {
   if (challenge.description !== undefined) parts.push(`description="${challenge.description}"`)
   if (challenge.digest !== undefined) parts.push(`digest="${challenge.digest}"`)
   if (challenge.expires !== undefined) parts.push(`expires="${challenge.expires}"`)
-  if (challenge.opaque !== undefined)
-    parts.push(`opaque="${PaymentRequest.serialize(challenge.opaque)}"`)
+  if (challenge.opaque !== undefined) parts.push(`opaque="${challenge.opaque}"`)
+  else if (challenge.meta !== undefined)
+    parts.push(`opaque="${PaymentRequest.serialize(challenge.meta)}"`)
 
   return `Payment ${parts.join(', ')}`
 }
@@ -335,7 +346,7 @@ export function deserialize<const methods extends readonly Method.Method[] | und
     {
       ...rest,
       request: PaymentRequest.deserialize(request),
-      ...(opaque && { meta: PaymentRequest.deserialize(opaque) as Record<string, string> }),
+      ...(opaque && { opaque }),
     } as from.Parameters,
     options,
   )
@@ -604,9 +615,9 @@ export declare namespace verify {
   }
 }
 
-/** Alias for `challenge.opaque`. Extracts server-defined correlation data from a challenge. */
+/** Extracts parsed server-defined correlation data from a challenge when available. */
 export function meta(challenge: Challenge): Record<string, string> | undefined {
-  return challenge.opaque
+  return challenge.meta
 }
 
 /**
@@ -631,7 +642,7 @@ function idBindingInput(challenge: Omit<Challenge, 'id'>): string {
     PaymentRequest.serialize(challenge.request),
     challenge.expires ?? '',
     challenge.digest ?? '',
-    challenge.opaque ? PaymentRequest.serialize(challenge.opaque) : '',
+    challenge.opaque ?? (challenge.meta ? PaymentRequest.serialize(challenge.meta) : ''),
   ].join('|')
 }
 

package/src/Credential.test.ts

@@ -111,6 +111,24 @@ describe('serialize', () => {
 
     expect(parsed.challenge.opaque).toBe('eyJwaSI6InBpXzNhYmMxMjNYWVoifQ')
   })
+
+  test('behavior: echoes raw opaque unchanged', () => {
+    const rawChallenge = Challenge.deserialize(
+      'Payment id="opaque123", realm="api.example.com", method="tempo", intent="charge", request="eyJhbW91bnQiOiIxMDAwIn0", opaque="eXkgd3Jvbmc"',
+    )
+    const credential = Credential.from({
+      challenge: rawChallenge,
+      payload: { signature: '0x1234' },
+    })
+
+    const header = Credential.serialize(credential)
+    const encoded = header.replace(/^Payment\s+/i, '')
+    const parsed = JSON.parse(Base64.toString(encoded)) as {
+      challenge: { opaque?: unknown }
+    }
+
+    expect(parsed.challenge.opaque).toBe('eXkgd3Jvbmc')
+  })
 })
 
 describe('deserialize', () => {
@@ -175,7 +193,31 @@ describe('deserialize', () => {
 
     const credential = Credential.deserialize(`Payment ${encoded}`)
 
-    expect(credential.challenge.opaque).toEqual({ pi: 'pi_3abc123XYZ' })
+    expect(credential.challenge.opaque).toBe('eyJwaSI6InBpXzNhYmMxMjNYWVoifQ')
+    expect(credential.challenge.meta).toBeUndefined()
+    expect(credential.challenge.request).toEqual({ amount: '1000' })
+  })
+
+  test('behavior: preserves non-json opaque string credentials', () => {
+    const encoded = Base64.fromString(
+      JSON.stringify({
+        challenge: {
+          id: 'opaque123',
+          intent: 'charge',
+          method: 'tempo',
+          opaque: 'eXkgd3Jvbmc',
+          realm: 'api.example.com',
+          request: 'eyJhbW91bnQiOiIxMDAwIn0',
+        },
+        payload: { signature: '0x1234' },
+      }),
+      { pad: false, url: true },
+    )
+
+    const credential = Credential.deserialize(`Payment ${encoded}`)
+
+    expect(credential.challenge.opaque).toBe('eXkgd3Jvbmc')
+    expect(credential.challenge.meta).toBeUndefined()
     expect(credential.challenge.request).toEqual({ amount: '1000' })
   })
 
@@ -197,7 +239,27 @@ describe('deserialize', () => {
 
     const credential = Credential.deserialize(`Payment ${encoded}`)
 
-    expect(credential.challenge.opaque).toEqual({ pi: 'pi_3abc123XYZ' })
+    expect(credential.challenge.opaque).toBe('eyJwaSI6InBpXzNhYmMxMjNYWVoifQ')
+    expect(credential.challenge.meta).toEqual({ pi: 'pi_3abc123XYZ' })
+  })
+
+  test('error: rejects legacy object-shaped opaque with non-string values', () => {
+    const encoded = Base64.fromString(
+      JSON.stringify({
+        challenge: {
+          id: 'opaque123',
+          intent: 'charge',
+          method: 'tempo',
+          opaque: { pi: 123 },
+          realm: 'api.example.com',
+          request: 'eyJhbW91bnQiOiIxMDAwIn0',
+        },
+        payload: { signature: '0x1234' },
+      }),
+      { pad: false, url: true },
+    )
+
+    expect(() => Credential.deserialize(`Payment ${encoded}`)).toThrow('Invalid base64url or JSON.')
   })
 
   test('error: throws for missing Payment scheme', () => {

package/src/Credential.ts

@@ -63,27 +63,20 @@ export function deserialize<payload = unknown>(value: string): Credential<payloa
   try {
     const json = Base64.toString(prefixMatch[1])
     const parsed = JSON.parse(json) as {
-      challenge: Omit<Challenge.Challenge, 'opaque' | 'request'> & {
-        opaque?: Record<string, string> | string
+      challenge: Omit<Challenge.Challenge, 'meta' | 'opaque' | 'request'> & {
+        opaque?: unknown
         request: string
       }
       payload: payload
       source?: string
     }
+    const { opaque: challengeOpaque, request, ...challengeFields } = parsed.challenge
+    const { meta, opaque } = normalizeCredentialOpaque(challengeOpaque)
     const challenge = Challenge.Schema.parse({
-      ...parsed.challenge,
-      ...(parsed.challenge.opaque !== undefined && {
-        // TODO: Drop the legacy object-shaped `opaque` fallback after old mppx
-        // clients are no longer in circulation. Older mppx versions echoed
-        // `opaque` as an expanded JSON object in credentials, but the Payment
-        // auth spec requires clients to return the original base64url string
-        // unchanged in the credential challenge object.
-        opaque:
-          typeof parsed.challenge.opaque === 'string'
-            ? (PaymentRequest.deserialize(parsed.challenge.opaque) as Record<string, string>)
-            : parsed.challenge.opaque,
-      }),
-      request: PaymentRequest.deserialize(parsed.challenge.request),
+      ...challengeFields,
+      ...(meta !== undefined && { meta }),
+      ...(opaque !== undefined && { opaque }),
+      request: PaymentRequest.deserialize(request),
     })
     return {
       challenge,
@@ -95,6 +88,28 @@ export function deserialize<payload = unknown>(value: string): Credential<payloa
   }
 }
 
+function normalizeCredentialOpaque(value: unknown): {
+  meta?: Record<string, string> | undefined
+  opaque?: string | undefined
+} {
+  if (value === undefined) return {}
+  if (typeof value === 'string') return { opaque: value }
+  if (!isStringRecord(value)) throw new Error('Invalid opaque.')
+
+  // Older mppx clients emitted credential challenge `opaque` as an expanded
+  // object. Keep accepting that legacy shape, but normalize it back to the
+  // spec-required base64url string.
+  return {
+    meta: value,
+    opaque: PaymentRequest.serialize(value),
+  }
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  return Object.values(value).every((entry) => typeof entry === 'string')
+}
+
 /**
  * Creates a credential from the given parameters.
  *
@@ -156,8 +171,8 @@ export function fromRequest<payload = unknown>(request: Request): Credential<pay
 
 /**
  * Serializes a credential to the Authorization header format.
- * When present, `challenge.opaque` is encoded as the base64url string required
- * by the Payment auth credential format.
+ * When present, `challenge.opaque` is emitted unchanged as the base64url string
+ * required by the Payment auth credential format.
  *
  * @param credential - The credential to serialize.
  * @returns A string suitable for the Authorization header value.
@@ -171,11 +186,12 @@ export function fromRequest<payload = unknown>(request: Request): Credential<pay
  * ```
  */
 export function serialize(credential: Credential): string {
-  const { opaque, request, ...challenge } = credential.challenge
+  const { meta, opaque, request, ...challenge } = credential.challenge
+  const wireOpaque = opaque ?? (meta !== undefined ? PaymentRequest.serialize(meta) : undefined)
   const wire = {
     challenge: {
       ...challenge,
-      ...(opaque !== undefined && { opaque: PaymentRequest.serialize(opaque) }),
+      ...(wireOpaque !== undefined && { opaque: wireOpaque }),
       request: PaymentRequest.serialize(request),
     },
     payload: credential.payload,

package/src/client/Mppx.test.ts

@@ -1,8 +1,8 @@
-import { Challenge, Credential, Mcp, Method, Receipt } from 'mppx'
+import { Challenge, Credential, Errors, Mcp, Method, Receipt } from 'mppx'
 import { Mppx, Transport, tempo } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { Methods } from 'mppx/tempo'
-import { afterEach, describe, expect, test } from 'vp/test'
+import { afterEach, describe, expect, test, vi } from 'vp/test'
 import * as Http from '~test/Http.js'
 import { accounts, asset, client } from '~test/tempo/viem.js'
 
@@ -134,6 +134,42 @@ describe('createCredential', () => {
     )
   })
 
+  test('behavior: rejects expired challenges before creating credential', async () => {
+    const createCredential = vi.fn(async ({ challenge }) =>
+      Credential.serialize({
+        challenge,
+        payload: { signature: '0xsignature', type: 'transaction' },
+      }),
+    )
+    const method = Method.toClient(Methods.charge, { createCredential })
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [method],
+    })
+
+    const challenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() - 60_000).toISOString(),
+      request: {
+        amount: '1000',
+        currency: '0x1234567890123456789012345678901234567890',
+        decimals: 6,
+        recipient: '0x1234567890123456789012345678901234567890',
+      },
+    })
+
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': Challenge.serialize(challenge),
+      },
+    })
+
+    await expect(mppx.createCredential(response)).rejects.toThrow(Errors.PaymentExpiredError)
+    expect(createCredential).not.toHaveBeenCalled()
+  })
+
   test('behavior: routes to correct method with multiple methods', async () => {
     const stripeCharge = Method.from({
       name: 'stripe',
@@ -165,7 +201,6 @@ describe('createCredential', () => {
       realm,
       method: 'stripe',
       intent: 'charge',
-      expires: new Date(Date.now() + 60_000).toISOString(),
       request: {
         amount: '2000',
         currency: '0xabcd',
@@ -294,6 +329,7 @@ describe('createCredential', () => {
       realm,
       method: 'stripe',
       intent: 'charge',
+      expires: new Date(Date.now() + 60_000).toISOString(),
       request: {
         amount: '2000',
         currency: '0xabcd',

package/src/client/Mppx.ts

@@ -1,4 +1,5 @@
 import type * as Challenge from '../Challenge.js'
+import * as Expires from '../Expires.js'
 import * as AcceptPayment from '../internal/AcceptPayment.js'
 import type * as Method from '../Method.js'
 import type * as z from '../zod.js'
@@ -106,6 +107,7 @@ export function create<
         )
 
       const { challenge, method: mi } = selected
+      if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
 
       const parsedContext =
         mi.context && context !== undefined ? mi.context.parse(context) : undefined

package/src/client/internal/Fetch.test.ts

@@ -1,4 +1,4 @@
-import { Receipt } from 'mppx'
+import { Errors, Receipt } from 'mppx'
 import { tempo } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import { createClient, defineChain } from 'viem'
@@ -335,14 +335,15 @@ const noopMethod = {
 } as any
 
 /** Builds a valid 402 response with a WWW-Authenticate header. */
-function make402(overrides?: { method?: string; intent?: string }) {
+function make402(overrides?: { expires?: string; intent?: string; method?: string }) {
   const method = overrides?.method ?? 'test'
   const intent = overrides?.intent ?? 'test'
+  const expires = overrides?.expires ? `, expires="${overrides.expires}"` : ''
   const request = btoa(JSON.stringify({ amount: '1' }))
     .replace(/\+/g, '-')
     .replace(/\//g, '_')
     .replace(/=+$/, '')
-  const header = `Payment id="abc", realm="test", method="${method}", intent="${intent}", request="${request}"`
+  const header = `Payment id="abc", realm="test", method="${method}", intent="${intent}", request="${request}"${expires}`
   return new Response(null, {
     status: 402,
     headers: { 'WWW-Authenticate': header },
@@ -603,6 +604,24 @@ describe('Fetch.from: init passthrough (non-402)', () => {
 })
 
 describe('Fetch.from: 402 retry path', () => {
+  test('rejects expired challenges before hooks or credential creation', async () => {
+    const createCredential = vi.fn(async () => 'credential')
+    const onChallenge = vi.fn(async () => undefined)
+    const mockFetch = vi.fn(async () =>
+      make402({ expires: new Date(Date.now() - 60_000).toISOString() }),
+    )
+    const fetch = Fetch.from({
+      fetch: mockFetch as typeof globalThis.fetch,
+      methods: [{ ...noopMethod, createCredential }],
+      onChallenge,
+    })
+
+    await expect(fetch('https://example.com/api')).rejects.toThrow(Errors.PaymentExpiredError)
+    expect(onChallenge).not.toHaveBeenCalled()
+    expect(createCredential).not.toHaveBeenCalled()
+    expect(mockFetch).toHaveBeenCalledTimes(1)
+  })
+
   test('strips context from init on retry', async () => {
     const calls: { init: RequestInit | undefined }[] = []
     let callCount = 0

package/src/client/internal/Fetch.ts

@@ -1,4 +1,5 @@
 import * as Challenge from '../../Challenge.js'
+import * as Expires from '../../Expires.js'
 import * as AcceptPayment from '../../internal/AcceptPayment.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
@@ -80,6 +81,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
       )
 
     const { challenge, method: mi } = selected
+    if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
 
     const onChallengeCredential = onChallenge
       ? await onChallenge(challenge, {

package/src/mcp-sdk/client/McpClient.test.ts

@@ -2,11 +2,12 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { McpError } from '@modelcontextprotocol/sdk/types.js'
-import { Challenge, Mcp as core_Mcp } from 'mppx'
+import { Challenge, Credential, Errors, Mcp as core_Mcp, Method } from 'mppx'
 import { tempo as tempo_client } from 'mppx/client'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
+import { Methods } from 'mppx/tempo'
 import { createClient } from 'viem'
-import { afterEach, beforeEach, describe, expect, test } from 'vp/test'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vp/test'
 import { accounts, asset, chain, http, client as testClient } from '~test/tempo/viem.js'
 
 import * as McpServer_transport from '../server/Transport.js'
@@ -187,6 +188,42 @@ describe('McpClient.wrap', () => {
       'No compatible payment method. Server offers: unknown_method.charge. Client has: tempo.charge',
     )
   })
+
+  test('behavior: rejects expired challenges before creating credential', async () => {
+    const challenge = Challenge.fromMethod(Methods.charge, {
+      realm,
+      secretKey,
+      expires: new Date(Date.now() - 60_000).toISOString(),
+      request: {
+        amount: '1',
+        currency: asset,
+        decimals: 6,
+        recipient: accounts[0].address,
+      },
+    })
+
+    server.registerTool('expired_tool', { description: 'Tool' }, async () => {
+      throw new McpError(core_Mcp.paymentRequiredCode, 'Payment Required', {
+        httpStatus: 402,
+        challenges: [challenge],
+      })
+    })
+
+    const createCredential = vi.fn(async ({ challenge }) =>
+      Credential.serialize({
+        challenge,
+        payload: { signature: '0xsignature', type: 'transaction' },
+      }),
+    )
+    const mcp = McpClient.wrap(client, {
+      methods: [Method.toClient(Methods.charge, { createCredential })],
+    })
+
+    await expect(mcp.callTool({ name: 'expired_tool', arguments: {} })).rejects.toThrow(
+      Errors.PaymentExpiredError,
+    )
+    expect(createCredential).not.toHaveBeenCalled()
+  })
 })
 
 describe('isPaymentRequiredError', () => {

package/src/mcp-sdk/client/McpClient.ts

@@ -3,6 +3,7 @@ import type { McpError } from '@modelcontextprotocol/sdk/types.js'
 
 import type * as Challenge from '../../Challenge.js'
 import * as Credential from '../../Credential.js'
+import * as Expires from '../../Expires.js'
 import * as AcceptPayment from '../../internal/AcceptPayment.js'
 import * as core_Mcp from '../../Mcp.js'
 import type * as Method from '../../Method.js'
@@ -186,6 +187,8 @@ async function createCredential<methods extends readonly Method.AnyClient[]>(
       `No method found for "${challenge.method}.${challenge.intent}". Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
     )
 
+  if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
+
   const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined
   return mi.createCredential(
     parsedContext !== undefined ? { challenge, context: parsedContext } : ({ challenge } as never),

package/src/middlewares/hono.test.ts

@@ -180,7 +180,7 @@ describe('scope binding', () => {
     expect(challengeResponse.status).toBe(402)
 
     const challenge = Challenge.fromResponse(challengeResponse)
-    expect(challenge.opaque).toEqual({ _mppx_scope: 'GET /alpha/:id' })
+    expect(challenge.opaque).toBe('eyJfbXBweF9zY29wZSI6IkdFVCAvYWxwaGEvOmlkIn0')
 
     const credential = Credential.from({ challenge, payload: { token: 'valid' } })
     const replay = await fetch(`${server.url}/beta/1`, {
@@ -207,7 +207,7 @@ describe('scope binding', () => {
     expect(challengeResponse.status).toBe(402)
 
     const challenge = Challenge.fromResponse(challengeResponse)
-    expect(challenge.opaque).toEqual({ _mppx_scope: 'shared-scope' })
+    expect(challenge.opaque).toBe('eyJfbXBweF9zY29wZSI6InNoYXJlZC1zY29wZSJ9')
 
     const credential = Credential.from({ challenge, payload: { token: 'valid' } })
     const replay = await fetch(`${server.url}/beta/2`, {

package/src/proxy/Proxy.test.ts

@@ -771,7 +771,7 @@ describe('create', () => {
     expect(challengeResponse.status).toBe(402)
 
     const challenge = Challenge.fromResponse(challengeResponse)
-    expect(challenge.opaque).toEqual({ _mppx_scope: 'GET /api/v1/alpha' })
+    expect(challenge.opaque).toBe('eyJfbXBweF9zY29wZSI6IkdFVCAvYXBpL3YxL2FscGhhIn0')
 
     const credential = Credential.from({ challenge, payload: { token: 'valid' } })
     const replay = await fetch(`${proxyServer.url}/api/v1/beta`, {
@@ -813,7 +813,7 @@ describe('create', () => {
     expect(challengeResponse.status).toBe(402)
 
     const challenge = Challenge.fromResponse(challengeResponse)
-    expect(challenge.opaque).toEqual({ _mppx_scope: 'shared-scope' })
+    expect(challenge.opaque).toBe('eyJfbXBweF9zY29wZSI6InNoYXJlZC1zY29wZSJ9')
 
     const credential = Credential.from({ challenge, payload: { token: 'valid' } })
     const replay = await fetch(`${proxyServer.url}/api/v1/beta`, {