feat: add multi-challenge mppx.compose() combinator

[brendanjryan]

Summary

Adds mppx.compose() — an instance method that lets a single route present multiple payment methods (or the same method with different options) to the client via multiple WWW-Authenticate headers (RFC 9110 §11.6.1). Also adds Mppx.compose() as a static function, Challenge.fromResponseList() for parsing merged responses, and updates the client to automatically select from multiple challenges using the preference order declared in the methods array.

Usage

Server: nested accessors

const mppx = Mppx.create({
  methods: [
    tempo.charge({ currency: USDC, recipient: "0x..." }),
    stripe.charge({ currency: "usd" }),
  ],
  secretKey,
})

// All three accessor styles are equivalent:
mppx.tempo.charge({ amount: "100" })        // nested (new)
mppx["tempo/charge"]({ amount: "100" })     // slash key
mppx.charge({ amount: "100" })              // shorthand (when intent is unique)

Server: multi-challenge combinator

app.get("/api/resource", async (req) => {
  const result = await mppx.compose(
    [mppx.tempo.charge, { amount: "100" }],   // method ref
    ["stripe/charge", { amount: "100" }],      // or string key
  )(req)
  if (result.status === 402) return result.challenge
  return result.withReceipt(new Response("OK"))
})

Server: Mppx.compose() static with nested accessors

app.get("/api/resource", async (req) => {
  const result = await Mppx.compose(
    mppx.tempo.charge({ amount: "100" }),
    mppx.stripe.charge({ amount: "100" }),
  )(req)
  if (result.status === 402) return result.challenge
  return result.withReceipt(new Response("OK"))
})

Server: same method, different currencies

app.get("/api/resource", async (req) => {
  const result = await mppx.compose(
    [tempoCharge, { amount: "100", currency: USDC }],
    [tempoCharge, { amount: "100", currency: PathUSD }],
  )(req)
  if (result.status === 402) return result.challenge
  return result.withReceipt(new Response("OK"))
})

Middleware: nested accessors (Hono)

import { Mppx, tempo } from "mppx/hono"

const mppx = Mppx.create({ methods: [tempo.charge(...)], secretKey })

app.get("/premium", mppx.tempo.charge({ amount: "1" }), (c) =>
  c.json({ data: "paid content" }),
)

Client: automatic preference-based selection

The client automatically handles multi-challenge 402 responses. When multiple challenges are present, it selects the first match based on the order of the methods array — the client controls priority:

const mppx = Mppx.create({
  methods: [
    tempo({ account }),   // preferred — tried first
    stripe({ ... }),      // fallback
  ],
})

// Automatically picks tempo if the server offers both
const response = await mppx.fetch("/api/resource")

Client: manual parsing

const response = await fetch("/api/resource")
if (response.status === 402) {
  const challenges = Challenge.fromResponseList(response)
  // challenges[0] => tempo/charge (USDC)
  // challenges[1] => tempo/charge (PathUSD)
}

The 402 response contains multiple WWW-Authenticate headers:

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment method="tempo" intent="charge" request="..." (USDC)
WWW-Authenticate: Payment method="stripe" intent="charge" request="..." (USD)

Test coverage

Feature	Tests
Nested accessors (mppx.alpha.charge(...))	4 tests — 402→200 flow, identity with slash key, Mppx.compose() static
Middleware wrap() nested support	6 tests — wrapped handler production, end-to-end 402→200, key equivalence, passthrough of compose/realm/transport
String keys in compose()	3 tests — accepts string keys, rejects unknown keys, mixes with method refs
deserializeList quote handling	1 test — "Payment " inside quoted param values
Multi-challenge combinator	12 tests — merged headers, dispatch by method, cross-route protection, withReceipt, currency/recipient disambiguation, pre-dispatch narrowing

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/wevm/mppx@166

commit: b86c8ee

[jxom]

Is it meant to be mppx.challenge?

Suggested change

	* const result = await Mppx.challenge(
	* const result = await mppx.challenge(

[jxom]

I wonder if mppx.compose might be better naming, in case we want to use mppx.challenge for something else (like arbitrary server-defined digests like we discussed earlier? feel like that might be a good name for it)

[brendanjryan]

yeah lets' try compose, I think that is more explicit

[jxom]

can we make sure the types are hooked up well here for these variants with .test-d.ts type tests?