mppx 0.5.17 → 0.6.0

package/src/server/Mppx.ts

@@ -70,7 +70,32 @@ 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)
+     * ```
+     */
+    verifyCredential(credential: string | Credential.Credential): Promise<Receipt.Receipt>
+  }
 
 /** Extracts the transport override from a method, if any. */
 type TransportOverrideOf<mi> = mi extends { transport?: infer transport }
@@ -136,6 +161,21 @@ 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>
+
 /**
  * Creates a server-side payment handler from methods.
  *
@@ -200,6 +240,56 @@ 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,
+  ): 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)
+
+    // The challenge already contains the request params (HMAC-bound),
+    // so we use them directly — no need for the caller to re-supply.
+    const request = credential.challenge.request as z.input<typeof mi.schema.request>
+
+    return mi.verify({ credential, request } as never)
+  }
+
   function composeFn(
     ...entries: readonly [
       Method.AnyServer | AnyMethodFnWithMethod | string,
@@ -225,9 +315,11 @@ export function create<
 
   return {
     methods,
+    challenge: challengeHandlers,
     compose: composeFn,
     realm: realm as string | undefined,
     transport,
+    verifyCredential: verifyCredentialFn,
     ...handlers,
   } as never
 }
@@ -482,6 +574,53 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
   }
 }
 
+/**
+ * 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 merged = { ...defaults, ...rest }
+    const expires =
+      'expires' in options ? (options.expires as string | undefined) : Expires.minutes(5)
+
+    // Transform request if method provides a `request` function.
+    const request = (
+      parameters.request
+        ? await (parameters.request as (opts: { request: unknown }) => unknown)({
+            request: merged,
+          })
+        : merged
+    ) as never
+
+    const effectiveRealm = realm ?? defaultRealm
+
+    return Challenge.fromMethod(method, {
+      description,
+      expires,
+      meta,
+      realm: effectiveRealm,
+      request,
+      secretKey,
+    })
+  }
+}
+
 function getSafeCredentialReason(error: unknown): string | undefined {
   if (error instanceof Credential.InvalidCredentialEncodingError) return error.message
   if (error instanceof Credential.MissingAuthorizationHeaderError) return error.message
@@ -568,8 +707,8 @@ 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),
   }

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)`,
     })