mppx 0.6.22 → 0.6.24

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,8yteAA8yte,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,4mueAA4mue,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.6.22",
+  "version": "0.6.24",
   "main": "./dist/index.js",
   "license": "MIT",
   "files": [

package/src/Credential.test.ts

@@ -198,6 +198,29 @@ describe('deserialize', () => {
     expect(credential.challenge.request).toEqual({ amount: '1000' })
   })
 
+  test('security: drops injected meta when opaque is a string', () => {
+    const encoded = Base64.fromString(
+      JSON.stringify({
+        challenge: {
+          id: 'opaque123',
+          intent: 'charge',
+          meta: { _mppx_scope: 'GET /admin' },
+          method: 'tempo',
+          opaque: 'eyJfbXBweF9zY29wZSI6IkdFVCAvcHVibGljIn0',
+          realm: 'api.example.com',
+          request: 'eyJhbW91bnQiOiIxMDAwIn0',
+        },
+        payload: { signature: '0x1234' },
+      }),
+      { pad: false, url: true },
+    )
+
+    const credential = Credential.deserialize(`Payment ${encoded}`)
+
+    expect(credential.challenge.opaque).toBe('eyJfbXBweF9zY29wZSI6IkdFVCAvcHVibGljIn0')
+    expect(credential.challenge.meta).toBeUndefined()
+  })
+
   test('behavior: preserves non-json opaque string credentials', () => {
     const encoded = Base64.fromString(
       JSON.stringify({

package/src/Credential.ts

@@ -64,13 +64,14 @@ export function deserialize<payload = unknown>(value: string): Credential<payloa
     const json = Base64.toString(prefixMatch[1])
     const parsed = JSON.parse(json) as {
       challenge: Omit<Challenge.Challenge, 'meta' | 'opaque' | 'request'> & {
+        meta?: unknown
         opaque?: unknown
         request: string
       }
       payload: payload
       source?: string
     }
-    const { opaque: challengeOpaque, request, ...challengeFields } = parsed.challenge
+    const { opaque: challengeOpaque, request, meta: _meta, ...challengeFields } = parsed.challenge
     const { meta, opaque } = normalizeCredentialOpaque(challengeOpaque)
     const challenge = Challenge.Schema.parse({
       ...challengeFields,

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

@@ -68,6 +68,19 @@ describe('create.Config', () => {
     expectTypeOf(mppx.fetch).toBeFunction()
   })
 
+  test('orderChallenges receives supported challenge candidates', () => {
+    const mppx = Mppx.create({
+      methods: [tempo({ account: {} as Account })],
+      orderChallenges: (candidates) => {
+        expectTypeOf(candidates[0]?.challenge.method).toEqualTypeOf<'tempo' | undefined>()
+        expectTypeOf(candidates[0]?.method.name).toEqualTypeOf<'tempo' | undefined>()
+        return candidates
+      },
+    })
+
+    expectTypeOf(mppx.fetch).toBeFunction()
+  })
+
   test('client events expose typed payloads', () => {
     const method = charge()
     const mppx = Mppx.create({

package/src/client/Mppx.test.ts

@@ -485,6 +485,58 @@ describe('createCredential', () => {
     expect(parsed.challenge.method).toBe('stripe')
   })
 
+  test('behavior: createCredential accepts request-local challenge ordering', async () => {
+    const testMethod = Method.toClient(
+      Method.from({
+        name: 'test',
+        intent: 'test',
+        schema: Methods.charge.schema,
+      }),
+      {
+        async createCredential({ challenge }) {
+          return Credential.serialize({
+            challenge,
+            payload: { signature: `0x${challenge.id}`, type: 'transaction' },
+          })
+        },
+      },
+    )
+
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [testMethod],
+    })
+
+    const first = Challenge.from({
+      id: '1111',
+      realm,
+      method: 'test',
+      intent: 'test',
+      request: { currency: 'pathusd' },
+    })
+    const second = Challenge.from({
+      id: '2222',
+      realm,
+      method: 'test',
+      intent: 'test',
+      request: { currency: 'usdc' },
+    })
+    const response = new Response(null, {
+      status: 402,
+      headers: {
+        'WWW-Authenticate': `${Challenge.serialize(first)}, ${Challenge.serialize(second)}`,
+      },
+    })
+
+    const credential = await mppx.createCredential(response, undefined, {
+      orderChallenges: (candidates) =>
+        candidates.filter(({ challenge }) => challenge.request.currency === 'usdc'),
+    })
+    const parsed = Credential.deserialize(credential)
+
+    expect(parsed.challenge.id).toBe('2222')
+  })
+
   test('behavior: passes context to createCredential', async () => {
     const mppx = Mppx.create({
       polyfill: false,

package/src/client/Mppx.ts

@@ -30,7 +30,7 @@ export type Mppx<
   createCredential: (
     response: Transport.ResponseOf<transport>,
     context?: AnyContextFor<FlattenMethods<methods>> | undefined,
-    options?: createCredential.Options | undefined,
+    options?: createCredential.Options<FlattenMethods<methods>> | undefined,
   ) => Promise<string>
   /** Register a client event handler by canonical event name. */
   on<name extends Fetch.ClientEventName<FlattenMethods<methods>, EventResponseOf<transport>>>(
@@ -101,6 +101,7 @@ export function create<
 >(config: create.Config<methods, transport>): Mppx<methods, transport> {
   const {
     onChallenge,
+    orderChallenges,
     polyfill = true,
     acceptPaymentPolicy = polyfill && typeof globalThis.location !== 'undefined'
       ? 'same-origin'
@@ -122,6 +123,7 @@ export function create<
     ...(config.fetch && { fetch: config.fetch }),
     eventDispatcher: events,
     ...(resolvedOnChallenge && { onChallenge: resolvedOnChallenge }),
+    ...(orderChallenges && { orderChallenges }),
     methods,
   } satisfies Fetch.from.Config<FlattenMethods<methods>>
   const fetch = Fetch.from<FlattenMethods<methods>>(config_fetch)
@@ -181,7 +183,7 @@ export function create<
     async createCredential(
       response: Transport.ResponseOf<transport>,
       context?: unknown,
-      options?: createCredential.Options,
+      options?: createCredential.Options<FlattenMethods<methods>>,
     ) {
       const challenges = transport.getChallenges
         ? transport.getChallenges(response as never)
@@ -191,7 +193,12 @@ export function create<
       let challenge: Challenge.Challenge | undefined
       let mi: FlattenMethods<methods>[number] | undefined
       try {
-        const selected = AcceptPayment.selectChallenge(challenges, methods, preferences)
+        const candidates = AcceptPayment.selectChallengeCandidates(challenges, methods, preferences)
+        const orderedCandidates = await resolveChallengeOrder(
+          candidates,
+          options?.orderChallenges ?? orderChallenges,
+        )
+        const selected = orderedCandidates[0]
         if (!selected)
           throw new Error(
             `No method found for challenges: ${challenges.map((challenge) => `${challenge.method}.${challenge.intent}`).join(', ')}. Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
@@ -246,9 +253,11 @@ export function create<
 }
 
 export declare namespace createCredential {
-  type Options = {
+  type Options<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[]> = {
     /** Request-local Accept-Payment override for manual rawFetch + createCredential flows. */
     acceptPayment?: string | readonly AcceptPayment.Entry[] | undefined
+    /** Request-local challenge filtering and sorting. */
+    orderChallenges?: AcceptPayment.OrderChallenges<methods> | undefined
   }
 }
 
@@ -288,6 +297,8 @@ export declare namespace create {
           },
         ) => Promise<string | undefined>)
       | undefined
+    /** Filters and sorts supported challenges before credential creation. */
+    orderChallenges?: AcceptPayment.OrderChallenges<FlattenMethods<methods>> | undefined
     /** Client-declared supported payment methods, keyed by typed `method/intent` strings. */
     paymentPreferences?: AcceptPayment.Config<FlattenMethods<methods>> | undefined
     /** Array of methods to use. Accepts individual clients or tuples (e.g. from `tempo()`). */
@@ -431,6 +442,13 @@ function resolveChallengePreferences(
   return typeof override === 'string' ? AcceptPayment.parse(override) : override
 }
 
+async function resolveChallengeOrder<methods extends readonly Method.AnyClient[]>(
+  candidates: readonly AcceptPayment.ChallengeCandidate<methods[number]>[],
+  orderChallenges: AcceptPayment.OrderChallenges<methods> | undefined,
+): Promise<readonly AcceptPayment.ChallengeCandidate<methods[number]>[]> {
+  return orderChallenges ? orderChallenges(candidates) : candidates
+}
+
 async function createCredentialForMethod(
   challenge: Challenge.Challenge,
   mi: Method.AnyClient,

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

@@ -46,6 +46,17 @@ describe('Fetch.from', () => {
     })
   })
 
+  test('behavior: accepts challenge ordering hook', () => {
+    const fetch = Fetch.from({
+      methods: [charge()],
+      orderChallenges: (candidates) => candidates,
+    })
+
+    expectTypeOf(fetch).toBeCallableWith('https://example.com', {
+      orderChallenges: (candidates) => candidates,
+    })
+  })
+
   test('behavior: events infer payload types from methods', () => {
     const method = charge()
     const dispatcher = Fetch.createEventDispatcher<[typeof method]>()

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

@@ -1,4 +1,4 @@
-import { Errors, Receipt } from 'mppx'
+import { Challenge, 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'
@@ -1097,6 +1097,122 @@ describe('Fetch.from: 402 retry path', () => {
     expect(response.status).toBe(200)
   })
 
+  test('orderChallenges filters and sorts supported challenges before signing', async () => {
+    let callCount = 0
+    const pathUsd = Challenge.from({
+      id: 'pathusd',
+      realm: 'test',
+      method: 'test',
+      intent: 'test',
+      request: { chainId: 11155111, currency: 'pathusd' },
+    })
+    const usdc = Challenge.from({
+      id: 'usdc',
+      realm: 'test',
+      method: 'test',
+      intent: 'test',
+      request: { chainId: 8453, currency: 'usdc' },
+    })
+    const createCredential = vi.fn(
+      async ({ challenge }: { challenge: Challenge.Challenge }) => `credential-${challenge.id}`,
+    )
+
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      callCount++
+      if (callCount === 1) {
+        return new Response(null, {
+          status: 402,
+          headers: {
+            'WWW-Authenticate': `${Challenge.serialize(pathUsd)}, ${Challenge.serialize(usdc)}`,
+          },
+        })
+      }
+
+      expect(new Headers(init?.headers).get('Authorization')).toBe('credential-usdc')
+      return new Response('OK', { status: 200 })
+    }
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      methods: [{ ...noopMethod, createCredential }],
+      orderChallenges: (candidates) =>
+        candidates.filter(({ challenge }) => challenge.request.currency === 'usdc'),
+    })
+
+    const response = await fetch('https://example.com/api')
+
+    expect(response.status).toBe(200)
+    expect(createCredential).toHaveBeenCalledOnce()
+    expect(createCredential.mock.calls[0]?.[0].challenge.id).toBe('usdc')
+  })
+
+  test('request-local orderChallenges overrides configured ordering', async () => {
+    let callCount = 0
+    const first = Challenge.from({
+      id: 'first',
+      realm: 'test',
+      method: 'test',
+      intent: 'test',
+      request: { currency: 'first' },
+    })
+    const second = Challenge.from({
+      id: 'second',
+      realm: 'test',
+      method: 'test',
+      intent: 'test',
+      request: { currency: 'second' },
+    })
+    const createCredential = vi.fn(
+      async ({ challenge }: { challenge: Challenge.Challenge }) => `credential-${challenge.id}`,
+    )
+
+    const mockFetch: typeof globalThis.fetch = async (_input, init) => {
+      callCount++
+      if (callCount === 1) {
+        return new Response(null, {
+          status: 402,
+          headers: {
+            'WWW-Authenticate': `${Challenge.serialize(first)}, ${Challenge.serialize(second)}`,
+          },
+        })
+      }
+
+      expect(new Headers(init?.headers).get('Authorization')).toBe('credential-second')
+      return new Response('OK', { status: 200 })
+    }
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      methods: [{ ...noopMethod, createCredential }],
+      orderChallenges: (candidates) =>
+        candidates.filter(({ challenge }) => challenge.id === 'first'),
+    })
+
+    const response = await fetch('https://example.com/api', {
+      orderChallenges: (candidates) =>
+        candidates.filter(({ challenge }) => challenge.id === 'second'),
+    })
+
+    expect(response.status).toBe(200)
+    expect(createCredential.mock.calls[0]?.[0].challenge.id).toBe('second')
+  })
+
+  test('throws when orderChallenges rejects every supported challenge', async () => {
+    const mockFetch: typeof globalThis.fetch = async () => make402()
+    const createCredential = vi.fn(async () => 'credential')
+
+    const fetch = Fetch.from({
+      fetch: mockFetch,
+      methods: [{ ...noopMethod, createCredential }],
+      orderChallenges: () => [],
+    })
+
+    await expect(fetch('https://example.com/api')).rejects.toThrow(
+      'No method found for challenges: test.test',
+    )
+    expect(createCredential).not.toHaveBeenCalled()
+  })
+
   test('falls back to configured preferences when explicit Accept-Payment is invalid', async () => {
     let callCount = 0
     const mockFetch: typeof globalThis.fetch = async (_input, init) => {

package/src/client/internal/Fetch.ts

@@ -161,6 +161,7 @@ export function from<const methods extends readonly Method.AnyClient[]>(
     fetch = globalThis.fetch,
     methods,
     onChallenge,
+    orderChallenges,
   } = config
   const events = config.eventDispatcher ?? createEventDispatcher()
   const resolvedAcceptPayment = acceptPayment ?? AcceptPayment.resolve(methods)
@@ -186,7 +187,11 @@ export function from<const methods extends readonly Method.AnyClient[]>(
 
     // Only extract context for payment handling after confirming 402.
     const context = (init as Record<string, unknown> | undefined)?.context
-    const { context: _, ...fetchInit } = (initialRequest.init ?? {}) as Record<string, unknown>
+    const {
+      context: _,
+      orderChallenges: requestOrderChallenges,
+      ...fetchInit
+    } = (initialRequest.init ?? {}) as Record<string, unknown>
 
     let challenge: Challenge.Challenge | undefined
     let challenges: readonly Challenge.Challenge[] | undefined
@@ -196,11 +201,17 @@ export function from<const methods extends readonly Method.AnyClient[]>(
       // Parse all challenges from the response (supports merged WWW-Authenticate headers).
       challenges = Challenge.fromResponseList(response)
 
-      const selected = AcceptPayment.selectChallenge(
+      const candidates = AcceptPayment.selectChallengeCandidates(
         challenges,
         methods,
         paymentPreferences.entries,
       )
+      const orderedCandidates = await resolveChallengeOrder(
+        candidates,
+        (requestOrderChallenges as AcceptPayment.OrderChallenges<methods> | undefined) ??
+          orderChallenges,
+      )
+      const selected = orderedCandidates[0]
       if (!selected)
         throw new Error(
           `No method found for challenges: ${challenges.map((c) => `${c.method}.${c.intent}`).join(', ')}. Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
@@ -322,6 +333,8 @@ export declare namespace from {
           },
         ) => Promise<string | undefined>)
       | undefined
+    /** Filters and sorts supported challenges before credential creation. */
+    orderChallenges?: AcceptPayment.OrderChallenges<methods> | undefined
   }
 
   type Fetch<methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[]> = (
@@ -333,6 +346,8 @@ export declare namespace from {
     globalThis.RequestInit & {
       /** Context to pass to the method intent's createCredential. */
       context?: AnyContextFor<methods>
+      /** Request-local challenge filtering and sorting. */
+      orderChallenges?: AcceptPayment.OrderChallenges<methods> | undefined
     }
 }
 
@@ -783,6 +798,13 @@ function resolvePaymentPreferences<methods extends readonly Method.AnyClient[]>(
   }
 }
 
+async function resolveChallengeOrder<methods extends readonly Method.AnyClient[]>(
+  candidates: readonly AcceptPayment.ChallengeCandidate<methods[number]>[],
+  orderChallenges: AcceptPayment.OrderChallenges<methods> | undefined,
+): Promise<readonly AcceptPayment.ChallengeCandidate<methods[number]>[]> {
+  return orderChallenges ? orderChallenges(candidates) : candidates
+}
+
 /** @internal */
 function shouldInjectForPolicy(
   input: RequestInfo | URL,

package/src/internal/AcceptPayment.test.ts

@@ -152,6 +152,32 @@ describe('AcceptPayment', () => {
     expect(selected?.method).toEqual({ name: 'tempo', intent: 'session' })
   })
 
+  test('selectChallengeCandidates returns supported offers with methods and response indexes', () => {
+    const candidates = AcceptPayment.selectChallengeCandidates(
+      [
+        { id: '1', intent: 'charge', method: 'unknown', realm: 'test', request: {} },
+        { id: '2', intent: 'session', method: 'tempo', realm: 'test', request: {} },
+        { id: '3', intent: 'charge', method: 'stripe', realm: 'test', request: {} },
+      ],
+      [
+        { name: 'tempo', intent: 'session' },
+        { name: 'stripe', intent: 'charge' },
+      ] as const,
+      AcceptPayment.parse('stripe/charge;q=0.5, tempo/session;q=0.9'),
+    )
+
+    expect(
+      candidates.map(({ challenge, index, method }) => ({
+        id: challenge.id,
+        index,
+        key: AcceptPayment.keyOf(method),
+      })),
+    ).toEqual([
+      { id: '2', index: 1, key: 'tempo/session' },
+      { id: '3', index: 2, key: 'stripe/charge' },
+    ])
+  })
+
   test('selectChallenge honors a specific opt-out over a broader wildcard', () => {
     const selected = AcceptPayment.selectChallenge(
       [

package/src/internal/AcceptPayment.ts

@@ -1,10 +1,30 @@
 import type * as Challenge from '../Challenge.js'
+import type { MaybePromise } from './types.js'
 
 type MethodLike = {
   intent: string
   name: string
 }
 
+/** Supported challenge paired with the configured client method that can sign it. */
+export type ChallengeCandidate<method extends MethodLike = MethodLike> = method extends MethodLike
+  ? {
+      challenge: Challenge.Challenge<Record<string, unknown>, method['intent'], method['name']>
+      index: number
+      method: method
+    }
+  : never
+
+/**
+ * Hook for filtering and sorting supported challenges before credential creation.
+ *
+ * Return candidates in preference order. The SDK signs the first returned
+ * candidate. Return an empty array to reject all offered challenges.
+ */
+export type OrderChallenges<methods extends readonly MethodLike[]> = (
+  candidates: readonly ChallengeCandidate<methods[number]>[],
+) => MaybePromise<readonly ChallengeCandidate<methods[number]>[]>
+
 /** Typed `method/intent` key for a configured payment capability. */
 export type Key<methods extends readonly MethodLike[]> = methods[number] extends infer mi
   ? mi extends { name: infer name extends string; intent: infer intent extends string }
@@ -144,23 +164,48 @@ export function selectChallenge<const methods extends readonly MethodLike[]>(
       method: methods[number]
     }
   | undefined {
+  const candidate = selectChallengeCandidates(challenges, methods, preferences)[0]
+  if (!candidate) return undefined
+
+  return {
+    challenge: candidate.challenge,
+    method: candidate.method,
+  }
+}
+
+/** Returns supported challenge candidates ordered by client payment preferences. */
+export function selectChallengeCandidates<const methods extends readonly MethodLike[]>(
+  challenges: readonly Challenge.Challenge[],
+  methods: methods,
+  preferences: readonly Entry[],
+): ChallengeCandidate<methods[number]>[] {
   const methodByKey = new Map<string, methods[number]>()
   for (const method of methods) {
     const key = keyOf(method)
     if (!methodByKey.has(key)) methodByKey.set(key, method)
   }
 
-  const ranked = rank(
-    challenges.filter((challenge) => methodByKey.has(keyOf(challenge))),
-    preferences,
-  )
-  const challenge = ranked[0]
-  if (!challenge) return undefined
+  return challenges
+    .map((challenge, index) => {
+      const method = methodByKey.get(keyOf(challenge))
+      if (!method) return undefined
 
-  return {
-    challenge,
-    method: methodByKey.get(keyOf(challenge))!,
-  }
+      const match = bestMatch(challenge, preferences)
+      if (!match || match.q <= 0) return undefined
+
+      return {
+        challenge,
+        index,
+        match,
+        method,
+      } as ChallengeCandidate<methods[number]> & { match: Match }
+    })
+    .filter((candidate): candidate is NonNullable<typeof candidate> => Boolean(candidate))
+    .sort((left, right) => right.match.q - left.match.q || left.index - right.index)
+    .map((candidate) => {
+      const { match: _match, ...rest } = candidate
+      return rest as unknown as ChallengeCandidate<methods[number]>
+    })
 }
 
 /** Returns the canonical `method/intent` key for a method or challenge-like value. */

package/src/server/Mppx.test.ts

@@ -4415,6 +4415,30 @@ describe('verifyCredential', () => {
     )
   })
 
+  test('rejects direct credential objects with forged meta and valid opaque', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaChargeServer],
+      realm,
+      secretKey,
+    })
+
+    const challenge = await mppx.challenge.alpha.charge({
+      ...challengeOpts,
+      scope: 'GET /public',
+    })
+    const credential = Credential.from({
+      challenge: {
+        ...challenge,
+        meta: { _mppx_scope: 'GET /admin' },
+      },
+      payload: { token: 'valid' },
+    })
+
+    await expect(mppx.verifyCredential(credential, { scope: 'GET /admin' })).rejects.toThrow(
+      "credential scope does not match this route's requirements",
+    )
+  })
+
   test('verifies route requirements using the echoed challenge realm when host was auto-detected', async () => {
     const mppx = Mppx.create({
       methods: [alphaChargeServer],

package/src/server/Mppx.ts

@@ -1919,13 +1919,14 @@ function hydrateCredentialMeta<payload>(
   credential: Credential.Credential<payload>,
 ): Credential.Credential<payload> {
   const { challenge } = credential
-  if (challenge.meta !== undefined || challenge.opaque === undefined) return credential
+  if (challenge.opaque === undefined) return credential
+  const hydratedChallenge = Challenge.Schema.parse({
+    ...challenge,
+    meta: PaymentRequest.deserialize(challenge.opaque),
+  })
   return {
     ...credential,
-    challenge: {
-      ...challenge,
-      meta: PaymentRequest.deserialize(challenge.opaque) as Record<string, string>,
-    },
+    challenge: hydratedChallenge,
   }
 }