mppx 0.5.17 → 0.6.1

package/src/server/Mppx.ts

@@ -70,7 +70,36 @@ export type Mppx<
       ): (input: Request) => Promise<MethodFn.Response<Transport.Http>>
     }
   : {}) &
-  Handlers<FlattenMethods<methods>, transport>
+  Handlers<FlattenMethods<methods>, transport> & {
+    /**
+     * Generate Challenge objects for registered methods without going through
+     * the HTTP 402 request lifecycle. Uses the same options, defaults, and
+     * schema transforms as the corresponding intent handler.
+     *
+     * @example
+     * ```ts
+     * const challenge = await mppx.challenge.tempo.charge({ amount: '25.92' })
+     * ```
+     */
+    challenge: ChallengeHandlers<FlattenMethods<methods>>
+
+    /**
+     * Verify a credential string or object end-to-end: deserialize,
+     * HMAC-check, match to a registered method, validate payload schema,
+     * check expiry, and call the method's verify function.
+     *
+     * @example
+     * ```ts
+     * const receipt = await mppx.verifyCredential('eyJjaGFsbGVuZ2...')
+     * const receipt = await mppx.verifyCredential(credential)
+     * const receipt = await mppx.verifyCredential(credential, { request: { amount: '1000' } })
+     * ```
+     */
+    verifyCredential(
+      credential: string | Credential.Credential,
+      options?: VerifyCredentialOptions | undefined,
+    ): Promise<Receipt.Receipt>
+  }
 
 /** Extracts the transport override from a method, if any. */
 type TransportOverrideOf<mi> = mi extends { transport?: infer transport }
@@ -136,6 +165,28 @@ type Handlers<
 } & UniqueIntentHandlers<methods, transport> &
   NestedHandlers<methods, transport>
 
+/** Nested challenge generators: `mppx.challenge.tempo.charge(...)`. */
+type ChallengeHandlers<methods extends readonly Method.AnyServer[]> = {
+  [name in methods[number]['name']]: {
+    [mi in Extract<methods[number], { name: name }> as mi['intent']]: ChallengeFn<
+      mi,
+      NonNullable<mi['defaults']>
+    >
+  }
+}
+
+/** A function that generates a Challenge object from intent options. */
+type ChallengeFn<method extends Method.Method, defaults extends Record<string, unknown>> = (
+  options: MethodFn.Options<method, defaults>,
+) => Promise<Challenge.Challenge>
+
+export type VerifyCredentialOptions = {
+  capturedRequest?: Method.CapturedRequest | undefined
+  meta?: Record<string, string> | undefined
+  realm?: string | undefined
+  request?: Record<string, unknown> | undefined
+}
+
 /**
  * Creates a server-side payment handler from methods.
  *
@@ -200,6 +251,92 @@ export function create<
     ;(handlers[mi.name] as Record<string, unknown>)[mi.intent] = fn
   }
 
+  // Build challenge generators: mppx.challenge.tempo.charge(...)
+  const challengeHandlers: Record<string, Record<string, unknown>> = {}
+  for (const mi of methods) {
+    if (!challengeHandlers[mi.name]) challengeHandlers[mi.name] = {}
+    challengeHandlers[mi.name]![mi.intent] = createChallengeFn({
+      defaults: mi.defaults,
+      method: mi,
+      realm,
+      request: mi.request as never,
+      secretKey,
+    })
+  }
+
+  // verifyCredential: single-call end-to-end verification
+  async function verifyCredentialFn(
+    input: string | Credential.Credential,
+    options?: VerifyCredentialOptions,
+  ): Promise<Receipt.Receipt> {
+    const credential = typeof input === 'string' ? Credential.deserialize(input) : input
+
+    // HMAC provenance check (secretKey is guaranteed non-null by the guard at the top of create())
+    if (!Challenge.verify(credential.challenge, { secretKey: secretKey! }))
+      throw new Errors.InvalidChallengeError({
+        id: credential.challenge.id,
+        reason: 'challenge was not issued by this server',
+      })
+
+    // Expiry check
+    Expires.assert(credential.challenge.expires, credential.challenge.id)
+
+    // Find matching method by name + intent
+    const { method: credMethod, intent: credIntent } = credential.challenge
+    const mi = (methods as readonly Method.AnyServer[]).find(
+      (m) => m.name === credMethod && m.intent === credIntent,
+    )
+    if (!mi)
+      throw new Errors.InvalidChallengeError({
+        id: credential.challenge.id,
+        reason: `no registered method for ${credMethod}/${credIntent}`,
+      })
+
+    // Validate payload against method schema
+    mi.schema.credential.payload.parse(credential.payload)
+
+    const shouldValidateRoute =
+      options?.capturedRequest !== undefined ||
+      options?.meta !== undefined ||
+      options?.realm !== undefined ||
+      options?.request !== undefined
+
+    const request = shouldValidateRoute
+      ? await resolveRouteChallenge({
+          capturedRequest: options?.capturedRequest,
+          credential,
+          defaults: mi.defaults,
+          expires: credential.challenge.expires,
+          meta: options?.meta,
+          method: mi,
+          realm: options?.realm ?? realm,
+          request: mi.request as never,
+          routeRequest: options?.request ?? {},
+          secretKey: secretKey!,
+        }).then((resolved) => {
+          const mismatch = getPinnedChallengeMismatch(resolved.challenge, credential.challenge)
+          if (mismatch)
+            throw new Errors.InvalidChallengeError({
+              id: credential.challenge.id,
+              reason: `credential ${mismatch} does not match this route's requirements`,
+            })
+
+          return resolved.request as z.input<typeof mi.schema.request>
+        })
+      : (credential.challenge.request as z.input<typeof mi.schema.request>)
+
+    const envelope = options?.capturedRequest
+      ? ({
+          capturedRequest: options.capturedRequest,
+          challenge: credential.challenge,
+          credential,
+          request,
+        } as Method.VerifiedChallengeEnvelope)
+      : undefined
+
+    return mi.verify({ credential, envelope, request } as never)
+  }
+
   function composeFn(
     ...entries: readonly [
       Method.AnyServer | AnyMethodFnWithMethod | string,
@@ -225,9 +362,11 @@ export function create<
 
   return {
     methods,
+    challenge: challengeHandlers,
     compose: composeFn,
     realm: realm as string | undefined,
     transport,
+    verifyCredential: verifyCredentialFn,
     ...handlers,
   } as never
 }
@@ -261,7 +400,6 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
 
   return (options) => {
     const { description, meta, ...rest } = options
-    const merged = { ...defaults, ...rest }
 
     return Object.assign(
       async (input: Transport.InputOf): Promise<MethodFn.Response> => {
@@ -280,26 +418,17 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             return [null, e as Error] as const
           }
         })()
-
-        // Transform request if method provides a `request` function.
-        const request = (
-          parameters.request
-            ? await parameters.request({ capturedRequest, credential, request: merged } as never)
-            : merged
-        ) as never
-
-        // Resolve realm: explicit > env var > request Host header.
-        const effectiveRealm = realm ?? resolveRealmFromCapturedRequest(capturedRequest)
-
-        // Recompute challenge from options. The HMAC-bound ID means we don't need to
-        // store challenges server-side—if the client echoes back a credential with
-        // a matching ID, we know it was issued by us with these exact parameters.
-        const challenge = Challenge.fromMethod(method, {
+        const { challenge, request } = await resolveRouteChallenge({
+          capturedRequest,
+          credential,
+          defaults,
           description,
           expires,
           meta,
-          realm: effectiveRealm,
-          request,
+          method,
+          realm,
+          request: parameters.request,
+          routeRequest: rest,
           secretKey,
         })
 
@@ -415,6 +544,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           capturedRequest,
           challenge: credential.challenge,
           credential,
+          request,
         })
 
         // User-provided verification (e.g., check signature, submit tx, verify payment).
@@ -475,13 +605,51 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           ...options,
           name: method.name,
           intent: method.intent,
-          _canonicalRequest: PaymentRequest.fromMethod(method, merged),
+          _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
         },
       },
     )
   }
 }
 
+/**
+ * Creates a challenge generator for a single method+intent.
+ * Applies the same defaults and request transform as createMethodFn,
+ * but returns a Challenge object directly instead of a request handler.
+ */
+function createChallengeFn(parameters: {
+  defaults?: Record<string, unknown>
+  method: Method.Method
+  realm: string | undefined
+  request?: Method.RequestFn<Method.Method>
+  secretKey: string
+}): (options: Record<string, unknown>) => Promise<Challenge.Challenge> {
+  const { defaults, method, realm, secretKey } = parameters
+
+  return async (options) => {
+    const { description, meta, ...rest } = options as {
+      description?: string
+      expires?: string
+      meta?: Record<string, string>
+      [key: string]: unknown
+    }
+    const expires =
+      'expires' in options ? (options.expires as string | undefined) : Expires.minutes(5)
+
+    return resolveRouteChallenge({
+      defaults,
+      description,
+      expires,
+      meta,
+      method,
+      realm,
+      request: parameters.request,
+      routeRequest: rest,
+      secretKey,
+    }).then((resolved) => resolved.challenge)
+  }
+}
+
 function getSafeCredentialReason(error: unknown): string | undefined {
   if (error instanceof Credential.InvalidCredentialEncodingError) return error.message
   if (error instanceof Credential.MissingAuthorizationHeaderError) return error.message
@@ -537,6 +705,55 @@ function resolveRealmFromCapturedRequest(capturedRequest: Method.CapturedRequest
   return defaultRealm
 }
 
+async function resolveRouteChallenge(parameters: {
+  capturedRequest?: Method.CapturedRequest | undefined
+  credential?: Credential.Credential | null | undefined
+  defaults?: Record<string, unknown> | undefined
+  description?: string | undefined
+  expires?: string | undefined
+  meta?: Record<string, string> | undefined
+  method: Method.Method
+  realm?: string | undefined
+  request?: Method.RequestFn<Method.Method> | undefined
+  routeRequest: Record<string, unknown>
+  secretKey: string
+}): Promise<{
+  challenge: Challenge.Challenge
+  request: Record<string, unknown>
+}> {
+  // Resolve the route's canonical request exactly as the handler path does:
+  const request = await (async () => {
+    // start from defaults + route options, then let the method request hook
+    const merged = { ...parameters.defaults, ...parameters.routeRequest }
+    // normalize or enrich it using the captured request and credential.
+    return parameters.request
+      ? ((await parameters.request({
+          capturedRequest: parameters.capturedRequest,
+          credential: parameters.credential,
+          request: merged,
+        } as never)) as Record<string, unknown>)
+      : merged
+  })()
+
+  const effectiveRealm =
+    parameters.realm ??
+    (parameters.capturedRequest
+      ? resolveRealmFromCapturedRequest(parameters.capturedRequest)
+      : defaultRealm)
+
+  return {
+    challenge: Challenge.fromMethod(parameters.method, {
+      description: parameters.description,
+      expires: parameters.expires,
+      meta: parameters.meta,
+      realm: effectiveRealm,
+      request: request as never,
+      secretKey: parameters.secretKey,
+    }),
+    request,
+  }
+}
+
 /**
  * Captures the transport request into a frozen snapshot at the start of the
  * verification flow. This snapshot is threaded through request() → verify() →
@@ -568,15 +785,15 @@ function captureRequestFromInput(input: unknown): Method.CapturedRequest {
   }
 
   return {
-    hasBody: source.body !== undefined && source.body !== null,
     headers: new Headers(source.headers),
+    hasBody: source.body === undefined ? undefined : source.body !== null,
     method: source.method ?? 'POST',
     url: Transport.safeUrl(source.url),
   }
 }
 
 const coreBindingFields = ['amount', 'currency', 'recipient'] as const
-const methodBindingFields = ['chainId', 'memo', 'splits'] as const
+const methodBindingFields = ['chainId', 'memo', 'splits', 'unitType'] as const
 const pinnedRequestBindingFields = [...coreBindingFields, ...methodBindingFields] as const
 
 type CoreBindingField = (typeof coreBindingFields)[number]
@@ -646,6 +863,7 @@ function getPinnedRequestBinding(request: Record<string, unknown>): PinnedReques
   const memo = normalizeHex(methodDetails.memo)
   const recipient = normalizeScalar(request.recipient ?? methodDetails.recipient)
   const splits = normalizeComparable(methodDetails.splits)
+  const unitType = normalizeScalar(request.unitType ?? methodDetails.unitType)
 
   return {
     coreBinding: {
@@ -657,6 +875,7 @@ function getPinnedRequestBinding(request: Record<string, unknown>): PinnedReques
       ...(chainId !== undefined ? { chainId } : {}),
       ...(memo !== undefined ? { memo } : {}),
       ...(splits !== undefined ? { splits } : {}),
+      ...(unitType !== undefined ? { unitType } : {}),
     },
   }
 }

package/src/server/Transport.test.ts

@@ -38,13 +38,14 @@ describe('http', () => {
       const transport = Transport.http()
       const request = new Request('https://example.com/resource?foo=bar', {
         method: 'POST',
+        body: JSON.stringify({ prompt: 'hello' }),
         headers: { Authorization: Credential.serialize(credential), 'X-Test': '1' },
       })
 
       const captured = await transport.captureRequest?.(request)
       expect(captured).toEqual({
-        hasBody: false,
         headers: new Headers(request.headers),
+        hasBody: true,
         method: 'POST',
         url: new URL('https://example.com/resource?foo=bar'),
       })

package/src/stripe/server/Charge.ts

@@ -94,7 +94,13 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
 
     async verify({ credential, request }) {
       const { challenge } = credential
-      const resolvedRequest = Methods.charge.schema.request.parse(request)
+      const resolvedRequest = (() => {
+        const parsed = Methods.charge.schema.request.safeParse(request)
+        if (parsed.success) return parsed.data
+        // verifyCredential() passes the HMAC-bound challenge request, which is
+        // already in canonical output form and should not be transformed again.
+        return request as unknown as z.output<typeof Methods.charge.schema.request>
+      })()
 
       Expires.assert(challenge.expires, challenge.id)
 

package/src/tempo/server/Charge.ts

@@ -155,13 +155,24 @@ export function charge<const parameters extends charge.Parameters>(
 
     async verify({ credential, request }) {
       const { challenge } = credential
-      const resolvedRequest = Methods.charge.schema.request.parse(request)
+      const resolvedRequest = (() => {
+        const parsed = Methods.charge.schema.request.safeParse(request)
+        if (parsed.success) return parsed.data
+        // verifyCredential() passes the HMAC-bound challenge request, which is
+        // already in canonical output form and should not be transformed again.
+        return request as unknown as z.output<typeof Methods.charge.schema.request>
+      })()
       const chainId = resolvedRequest.methodDetails?.chainId ?? request.chainId
-      const feePayer = typeof request.feePayer === 'object' ? request.feePayer : undefined
 
       const client = await getClient({ chainId })
 
       const { amount, methodDetails } = resolvedRequest
+      const feePayerAccount =
+        typeof request.feePayer === 'object'
+          ? request.feePayer
+          : methodDetails?.feePayer === true
+            ? feePayer
+            : undefined
       const expires = challenge.expires
       const supportedModes = methodDetails?.supportedModes as
         | readonly Methods.ChargeMode[]
@@ -307,9 +318,9 @@ export function charge<const parameters extends charge.Parameters>(
             const resolvedFeeToken = transaction.feeToken ?? expectedFeeToken
 
             const serializedTransaction_final = await (async () => {
-              if (feePayer && methodDetails?.feePayer !== false) {
+              if (feePayerAccount && methodDetails?.feePayer !== false) {
                 const sponsored = FeePayer.prepareSponsoredTransaction({
-                  account: feePayer,
+                  account: feePayerAccount,
                   challengeExpires: expires,
                   chainId: chainId ?? client.chain!.id,
                   details: { amount, currency, recipient },

package/src/tempo/server/Session.test.ts

@@ -1401,6 +1401,32 @@ describe.runIf(isLocalnet)('session', () => {
       ).rejects.toThrow('close voucher amount must be >')
     })
 
+    test('allows zero close for an untouched channel', async () => {
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer()
+
+      await openServerChannel(server, channelId, serializedTransaction)
+
+      const receipt = await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'challenge-zero-close', channelId }),
+          payload: {
+            action: 'close' as const,
+            channelId,
+            cumulativeAmount: '0',
+            signature: await signTestVoucher(channelId, 0n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      expect(receipt.status).toBe('success')
+
+      const ch = await store.getChannel(channelId)
+      expect(ch).not.toBeNull()
+      expect(ch!.finalized).toBe(true)
+    })
+
     test('rejects close exceeding on-chain deposit', async () => {
       const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
       const server = createServer()
@@ -3380,6 +3406,27 @@ describe.runIf(isLocalnet)('session', () => {
       expect(result).toBeUndefined()
     })
 
+    test('returns undefined for open POST with a body stream and no framing headers', () => {
+      const server = createServer()
+      const input = new Request('http://localhost', {
+        body: JSON.stringify({ prompt: 'hello' }),
+        method: 'POST',
+      })
+
+      expect(input.headers.get('content-length')).toBeNull()
+
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'open' },
+        },
+        input,
+      } as any)
+      expect(result).toBeUndefined()
+    })
+
     test('returns undefined for open POST with transfer-encoding header (content request)', () => {
       const server = createServer()
       const result = server.respond!({
@@ -3446,6 +3493,27 @@ describe.runIf(isLocalnet)('session', () => {
       expect(result).toBeUndefined()
     })
 
+    test('returns undefined for voucher POST with a body stream and no framing headers', () => {
+      const server = createServer()
+      const input = new Request('http://localhost', {
+        body: JSON.stringify({ prompt: 'hello' }),
+        method: 'POST',
+      })
+
+      expect(input.headers.get('content-length')).toBeNull()
+
+      const result = server.respond!({
+        credential: {
+          challenge: makeChallenge({
+            channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+          }),
+          payload: { action: 'voucher' },
+        },
+        input,
+      } as any)
+      expect(result).toBeUndefined()
+    })
+
     test('returns undefined for voucher POST with transfer-encoding header (content request)', () => {
       const server = createServer()
       const result = server.respond!({

package/src/tempo/server/Session.ts

@@ -35,6 +35,7 @@ import type { LooseOmit, NoExtraKeys } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import * as Store from '../../Store.js'
 import * as Client from '../../viem/Client.js'
+import type * as z from '../../zod.js'
 import * as Account from '../internal/account.js'
 import * as defaults from '../internal/defaults.js'
 import * as FeePayer from '../internal/fee-payer.js'
@@ -52,6 +53,7 @@ import * as ChannelStore from '../session/ChannelStore.js'
 import { createSessionReceipt } from '../session/Receipt.js'
 import type { SessionCredentialPayload, SessionReceipt, SignedVoucher } from '../session/Types.js'
 import { parseVoucherFromPayload, verifyVoucher } from '../session/Voucher.js'
+import { captureRequestBodyProbe, isSessionContentRequest } from './internal/request-body.js'
 import * as Transport from './internal/transport.js'
 
 /** Challenge methodDetails shape for session methods. */
@@ -184,7 +186,13 @@ export function session<const parameters extends session.Parameters>(
     async verify({ credential, envelope, request }) {
       const { challenge, payload } = credential as Credential.Credential<SessionCredentialPayload>
 
-      const resolvedRequest = Methods.session.schema.request.parse(request)
+      const resolvedRequest = (() => {
+        const parsed = Methods.session.schema.request.safeParse(request)
+        if (parsed.success) return parsed.data
+        // verifyCredential() passes the HMAC-bound challenge request, which is
+        // already in canonical output form and should not be transformed again.
+        return request as unknown as z.output<typeof Methods.session.schema.request>
+      })()
       const methodDetails = resolvedRequest.methodDetails as SessionMethodDetails
       const client = await getClient({ chainId: methodDetails.chainId })
 
@@ -262,7 +270,7 @@ export function session<const parameters extends session.Parameters>(
       if (
         !parameters.sse &&
         envelope &&
-        isBillableContentRequest(envelope.capturedRequest) &&
+        isSessionContentRequest(envelope.capturedRequest) &&
         (payload.action === 'open' || payload.action === 'voucher')
       ) {
         const charged = await charge(
@@ -296,14 +304,8 @@ export function session<const parameters extends session.Parameters>(
       if (payload.action === 'close') return new Response(null, { status: 204 })
       if (payload.action === 'topUp') return new Response(null, { status: 204 })
 
-      const capturedRequest = envelope?.capturedRequest ?? {
-        hasBody: input.body !== null,
-        headers: input.headers,
-        method: input.method,
-        url: new URL(input.url),
-      }
-
-      if (isBillableContentRequest(capturedRequest)) return undefined
+      const request = envelope?.capturedRequest ?? captureRequestBodyProbe(input)
+      if (isSessionContentRequest(request)) return undefined
       return new Response(null, { status: 204 })
     },
   })
@@ -470,30 +472,6 @@ function validateOnChainChannel(
   }
 }
 
-function isBillableContentRequest(input: {
-  hasBody?: boolean | undefined
-  headers: Headers
-  method: string
-}): boolean {
-  if (input.method === 'POST') return hasCapturedRequestBody(input)
-
-  if (input.method === 'HEAD') return false
-
-  return true
-}
-
-function hasCapturedRequestBody(input: {
-  hasBody?: boolean | undefined
-  headers: Headers
-}): boolean {
-  const contentLength = input.headers.get('content-length')
-  const headerIndicatesBody =
-    (contentLength !== null && contentLength !== '0') || input.headers.has('transfer-encoding')
-
-  if (input.hasBody === true) return true
-  return headerIndicatesBody
-}
-
 /**
  * Shared logic for verifying an incremental voucher and updating channel state.
  * Used by both handleVoucher and (indirectly) handleOpen.
@@ -888,7 +866,9 @@ async function handleClose(
       reason: `close voucher amount must be >= ${channel.spent} (spent)`,
     })
   }
-  if (voucher.cumulativeAmount <= onChain.settled) {
+  const isUntouchedZeroClose =
+    voucher.cumulativeAmount === 0n && channel.spent === 0n && onChain.settled === 0n
+  if (!isUntouchedZeroClose && voucher.cumulativeAmount <= onChain.settled) {
     throw new VerificationFailedError({
       reason: `close voucher amount must be > ${onChain.settled} (on-chain settled)`,
     })