mppx 0.6.0 → 0.6.2

package/src/server/Mppx.test.ts

@@ -13,6 +13,8 @@ import * as Http from '~test/Http.js'
 import { deployEscrow } from '~test/tempo/session.js'
 import { accounts, asset, client } from '~test/tempo/viem.js'
 
+import type { SessionReceipt } from '../tempo/session/Types.js'
+
 const realm = 'api.example.com'
 const secretKey = 'test-secret-key'
 
@@ -2106,6 +2108,103 @@ describe('cross-route credential replay via scope binding flaw', () => {
     expect(result.status).toBe(402)
   })
 
+  test('rejects same-economics credential replayed across sibling routes with different scope', async () => {
+    const handler = Mppx.create({ methods: [serverMethod], realm, secretKey })
+
+    const routeA = handler.charge({
+      amount: '0.01',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+      scope: 'GET /a',
+    })
+    const routeB = handler.charge({
+      amount: '0.01',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+      scope: 'GET /b',
+    })
+
+    const routeAChallengeResult = await routeA(new Request('https://example.com/a'))
+    expect(routeAChallengeResult.status).toBe(402)
+    if (routeAChallengeResult.status !== 402) throw new Error()
+
+    const routeAChallenge = Challenge.fromResponse(routeAChallengeResult.challenge)
+    expect(routeAChallenge.opaque).toEqual({ _mppx_scope: 'GET /a' })
+
+    const credential = Credential.from({
+      challenge: routeAChallenge,
+      payload: { token: 'valid' },
+    })
+
+    const result = await routeB(
+      new Request('https://example.com/b', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+  })
+
+  test('rejects request-billed credential replayed at token-billed route', async () => {
+    const sessionMethod = Method.from({
+      name: 'mock',
+      intent: 'session',
+      schema: {
+        credential: { payload: z.object({ token: z.string() }) },
+        request: z.object({
+          amount: z.string(),
+          currency: z.string(),
+          recipient: z.string(),
+          unitType: z.string(),
+        }),
+      },
+    })
+
+    const sessionServerMethod = Method.toServer(sessionMethod, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [sessionServerMethod], realm, secretKey })
+
+    const requestRoute = handler.session({
+      amount: '1',
+      currency: '0x0000000000000000000000000000000000000001',
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+      unitType: 'request',
+    })
+    const tokenRoute = handler.session({
+      amount: '1',
+      currency: '0x0000000000000000000000000000000000000001',
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+      unitType: 'token',
+    })
+
+    const first = await requestRoute(new Request('https://example.com/request'))
+    expect(first.status).toBe(402)
+    if (first.status !== 402) throw new Error()
+
+    const credential = Credential.from({
+      challenge: Challenge.fromResponse(first.challenge),
+      payload: { token: 'valid' },
+    })
+
+    const result = await tokenRoute(
+      new Request('https://example.com/token', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+  })
+
   test('rejects credential with mismatched method field', async () => {
     const otherMethod = Method.from({
       name: 'other',
@@ -3033,6 +3132,37 @@ describe('challenge', () => {
     expect(challenge.opaque).toEqual({ checkout_id: 'chk_abc' })
   })
 
+  test('challenge binds scope via reserved opaque metadata', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaChargeServer],
+      realm,
+      secretKey,
+    })
+
+    const challenge = await mppx.challenge.alpha.charge({
+      ...challengeOpts,
+      scope: 'GET /premium',
+    })
+
+    expect(challenge.opaque).toEqual({ _mppx_scope: 'GET /premium' })
+  })
+
+  test('scope throws when it conflicts with reserved meta scope', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaChargeServer],
+      realm,
+      secretKey,
+    })
+
+    await expect(
+      mppx.challenge.alpha.charge({
+        ...challengeOpts,
+        meta: { _mppx_scope: 'GET /other' },
+        scope: 'GET /premium',
+      }),
+    ).rejects.toThrow('Conflicting scope values')
+  })
+
   test('challenge applies schema transforms', async () => {
     // Method with a z.transform that converts decimals
     const transformMethod = Method.from({
@@ -3271,6 +3401,70 @@ describe('verifyCredential', () => {
     expect(receipt.method).toBe('alpha')
   })
 
+  test('verifies a credential when the expected scope matches', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaChargeServer],
+      realm,
+      secretKey,
+    })
+
+    const challenge = await mppx.challenge.alpha.charge({
+      ...challengeOpts,
+      scope: 'GET /premium',
+    })
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const receipt = await mppx.verifyCredential(credential, { scope: 'GET /premium' })
+
+    expect(receipt.status).toBe('success')
+    expect(receipt.method).toBe('alpha')
+  })
+
+  test('rejects a credential when the expected scope mismatches', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaChargeServer],
+      realm,
+      secretKey,
+    })
+
+    const challenge = await mppx.challenge.alpha.charge({
+      ...challengeOpts,
+      scope: 'GET /premium',
+    })
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    await expect(mppx.verifyCredential(credential, { scope: 'GET /other' })).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],
+      secretKey,
+    })
+    const request = {
+      amount: '1000',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x0000000000000000000000000000000000000002',
+    }
+
+    const firstResult = await mppx.charge(request)(new Request('https://api.example.com/premium'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    expect(challenge.realm).toBe('api.example.com')
+
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const receipt = await mppx.verifyCredential(credential, { request })
+
+    expect(receipt.status).toBe('success')
+    expect(receipt.method).toBe('alpha')
+  })
+
   test('verifies a credential for session intent', async () => {
     verifyArgs = undefined
     const mppx = Mppx.create({
@@ -3311,6 +3505,28 @@ describe('verifyCredential', () => {
     expect(receipt.method).toBe('beta')
   })
 
+  test('rejects credential when verified against different route economics', async () => {
+    const mppx = Mppx.create({
+      methods: [alphaChargeServer],
+      realm,
+      secretKey,
+    })
+
+    const challenge = await mppx.challenge.alpha.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    await expect(
+      mppx.verifyCredential(credential, {
+        request: {
+          amount: '100000',
+          currency: '0x0000000000000000000000000000000000000001',
+          decimals: 6,
+          recipient: '0x0000000000000000000000000000000000000002',
+        },
+      }),
+    ).rejects.toThrow()
+  })
+
   test('rejects credential with wrong HMAC (not issued by this server)', async () => {
     const mppx = Mppx.create({
       methods: [alphaChargeServer],
@@ -3698,6 +3914,73 @@ describe('verifyCredential', () => {
     httpServer.close()
   })
 
+  test('verifyCredential charges repeated session voucher content requests when capturedRequest is provided', async () => {
+    const escrowContract = await deployEscrow()
+    const server = Mppx.create({
+      methods: [
+        tempo.session({
+          store: Store.memory(),
+          getClient: () => client,
+          account: accounts[0],
+          currency: asset,
+          escrowContract,
+          chainId: client.chain!.id,
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+    const route = server.session({ amount: '1', unitType: 'request' })
+    const clientMppx = Mppx_client.create({
+      polyfill: false,
+      methods: [
+        tempo_session_client({
+          account: accounts[1],
+          deposit: '10',
+          getClient: () => client,
+        }),
+      ],
+    })
+
+    const openChallengeResponse = await route(new Request('https://example.com/session'))
+    expect(openChallengeResponse.status).toBe(402)
+    if (openChallengeResponse.status !== 402) throw new Error()
+
+    const serializedOpenCredential = await clientMppx.createCredential(
+      openChallengeResponse.challenge,
+    )
+    await server.verifyCredential(serializedOpenCredential)
+
+    const voucherChallengeResponse = await route(new Request('https://example.com/session'))
+    expect(voucherChallengeResponse.status).toBe(402)
+    if (voucherChallengeResponse.status !== 402) throw new Error()
+
+    const serializedVoucherCredential = await clientMppx.createCredential(
+      voucherChallengeResponse.challenge,
+    )
+    const contentRequest = {
+      headers: new Headers(),
+      hasBody: false,
+      method: 'GET',
+      url: new URL('https://example.com/session'),
+    } as const
+    const routeRequest = { amount: '1', unitType: 'request' } as const
+
+    const firstReceipt = (await server.verifyCredential(serializedVoucherCredential, {
+      capturedRequest: contentRequest,
+      request: routeRequest,
+    })) as SessionReceipt
+    const secondReceipt = (await server.verifyCredential(serializedVoucherCredential, {
+      capturedRequest: contentRequest,
+      request: routeRequest,
+    })) as SessionReceipt
+
+    expect(BigInt(firstReceipt.spent)).toBeGreaterThan(0n)
+    expect(firstReceipt.units).toBe(1)
+    expect(BigInt(secondReceipt.spent)).toBeGreaterThan(BigInt(firstReceipt.spent))
+    expect(secondReceipt.units).toBe(2)
+  })
+
   test('verifies a sponsored tempo credential created by the real client', async () => {
     const server = Mppx.create({
       methods: [

package/src/server/Mppx.ts

@@ -13,12 +13,23 @@ import type * as Receipt from '../Receipt.js'
 import type * as z from '../zod.js'
 import * as Html from './internal/html/config.js'
 import { serviceWorker } from './internal/html/serviceWorker.gen.js'
+import * as Scope from './internal/scope.js'
 import * as NodeListener from './NodeListener.js'
 import * as Request from './Request.js'
 import * as Transport from './Transport.js'
 
 export type Methods = readonly (Method.AnyServer | readonly Method.AnyServer[])[]
 
+/** Options for standalone credential verification. */
+export type VerifyCredentialOptions = {
+  capturedRequest?: Method.CapturedRequest | undefined
+  meta?: Record<string, string> | undefined
+  realm?: string | undefined
+  request?: Record<string, unknown> | undefined
+  /** Optional expected route/resource scope bound via challenge `opaque`. */
+  scope?: string | undefined
+}
+
 /**
  * Payment handler.
  */
@@ -92,9 +103,13 @@ export type Mppx<
      * ```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): Promise<Receipt.Receipt>
+    verifyCredential(
+      credential: string | Credential.Credential,
+      options?: VerifyCredentialOptions | undefined,
+    ): Promise<Receipt.Receipt>
   }
 
 /** Extracts the transport override from a method, if any. */
@@ -256,6 +271,7 @@ export function create<
   // 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
 
@@ -283,11 +299,59 @@ export function create<
     // 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>
+    const expectedMeta = Scope.merge({ meta: options?.meta, scope: options?.scope })
+
+    if (options?.scope !== undefined && Scope.read(credential.challenge.opaque) !== options.scope) {
+      throw new Errors.InvalidChallengeError({
+        id: credential.challenge.id,
+        reason: "credential scope does not match this route's requirements",
+      })
+    }
+
+    const shouldValidateRoute =
+      options?.capturedRequest !== undefined ||
+      options?.meta !== undefined ||
+      options?.realm !== undefined ||
+      options?.request !== undefined
+    const expectedRealm =
+      options?.realm ??
+      realm ??
+      (options?.capturedRequest === undefined ? credential.challenge.realm : undefined)
+
+    const request = shouldValidateRoute
+      ? await resolveRouteChallenge({
+          capturedRequest: options?.capturedRequest,
+          credential,
+          defaults: mi.defaults,
+          expires: credential.challenge.expires,
+          meta: expectedMeta,
+          method: mi,
+          realm: expectedRealm,
+          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, request } as never)
+    return mi.verify({ credential, envelope, request } as never)
   }
 
   function composeFn(
@@ -352,14 +416,18 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
   const { defaults, method, realm, respond, secretKey, transport, verify } = parameters
 
   return (options) => {
-    const { description, meta, ...rest } = options
-    const merged = { ...defaults, ...rest }
+    const { description, meta, scope, ...rest } = options
+    const staticMeta = Scope.merge({ meta, scope })
 
     return Object.assign(
       async (input: Transport.InputOf): Promise<MethodFn.Response> => {
         const expires =
           'expires' in options ? (options.expires as string | undefined) : Expires.minutes(5)
         const capturedRequest = await captureRequest(transport, input)
+        const effectiveMeta =
+          scope === undefined && input instanceof globalThis.Request
+            ? Scope.merge({ meta: staticMeta, scope: Scope.get(input) })
+            : staticMeta
 
         // Extract credential once — getCredential may have side effects (e.g. SSE transports).
         const [credential, credentialError] = (() => {
@@ -372,26 +440,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,
+          meta: effectiveMeta,
+          method,
+          realm,
+          request: parameters.request,
+          routeRequest: rest,
           secretKey,
         })
 
@@ -507,6 +566,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).
@@ -565,9 +625,10 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           ...method,
           ...defaults,
           ...options,
+          ...(staticMeta !== undefined ? { meta: staticMeta } : {}),
           name: method.name,
           intent: method.intent,
-          _canonicalRequest: PaymentRequest.fromMethod(method, merged),
+          _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
         },
       },
     )
@@ -589,35 +650,28 @@ function createChallengeFn(parameters: {
   const { defaults, method, realm, secretKey } = parameters
 
   return async (options) => {
-    const { description, meta, ...rest } = options as {
+    const { description, meta, scope, ...rest } = options as {
       description?: string
       expires?: string
       meta?: Record<string, string>
+      scope?: string
       [key: string]: unknown
     }
-    const merged = { ...defaults, ...rest }
+    const effectiveMeta = Scope.merge({ meta, scope })
     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, {
+    return resolveRouteChallenge({
+      defaults,
       description,
       expires,
-      meta,
-      realm: effectiveRealm,
-      request,
+      meta: effectiveMeta,
+      method,
+      realm,
+      request: parameters.request,
+      routeRequest: rest,
       secretKey,
-    })
+    }).then((resolved) => resolved.challenge)
   }
 }
 
@@ -676,6 +730,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() →
@@ -715,7 +818,7 @@ function captureRequestFromInput(input: unknown): Method.CapturedRequest {
 }
 
 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]
@@ -785,6 +888,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: {
@@ -796,6 +900,7 @@ function getPinnedRequestBinding(request: Record<string, unknown>): PinnedReques
       ...(chainId !== undefined ? { chainId } : {}),
       ...(memo !== undefined ? { memo } : {}),
       ...(splits !== undefined ? { splits } : {}),
+      ...(unitType !== undefined ? { unitType } : {}),
     },
   }
 }
@@ -870,6 +975,8 @@ declare namespace MethodFn {
     expires?: string | undefined
     /** Optional server-defined correlation data (serialized as `opaque` in the request). Flat string-to-string map; clients MUST NOT modify. */
     meta?: Record<string, string> | undefined
+    /** Optional route/resource scope bound via reserved challenge metadata. */
+    scope?: string | undefined
   } & Method.WithDefaults<z.input<method['schema']['request']>, defaults>
 
   export type Response<transport extends Transport.AnyTransport = Transport.Http> =
@@ -890,6 +997,7 @@ type ConfiguredHandler = ((input: Request) => Promise<MethodFn.Response<Transpor
     intent: string
     html: Html.Options | undefined
     meta?: Record<string, string> | undefined
+    scope?: string | undefined
     _canonicalRequest: Record<string, unknown>
   }
 }

package/src/server/internal/scope.ts

@@ -0,0 +1,43 @@
+const requestScopes = new WeakMap<Request, string>()
+
+/** Reserved `meta` key used for mppx-managed route/resource scope binding. */
+export const reservedMetaKey = '_mppx_scope'
+
+/** Attaches a trusted adapter-derived scope to a Request for this process only. */
+export function attach(request: Request, scope: string): Request {
+  requestScopes.set(request, scope)
+  return request
+}
+
+/** Reads a previously attached trusted adapter-derived scope from a Request. */
+export function get(request: Request): string | undefined {
+  return requestScopes.get(request)
+}
+
+/** Returns the reserved mppx scope value from challenge metadata, if present. */
+export function read(meta: Record<string, string> | undefined): string | undefined {
+  return meta?.[reservedMetaKey]
+}
+
+/**
+ * Merges the public `scope` option into challenge metadata.
+ *
+ * Throws when both `scope` and `meta._mppx_scope` are provided with different
+ * values so callers have a single authoritative way to bind route scope.
+ */
+export function merge(parameters: {
+  meta?: Record<string, string> | undefined
+  scope?: string | undefined
+}): Record<string, string> | undefined {
+  const { meta, scope } = parameters
+  const metaScope = read(meta)
+
+  if (scope !== undefined && metaScope !== undefined && metaScope !== scope) {
+    throw new Error(
+      `Conflicting scope values: \`scope\` (${scope}) does not match \`meta.${reservedMetaKey}\` (${metaScope}).`,
+    )
+  }
+
+  if (scope === undefined || metaScope === scope) return meta
+  return { ...meta, [reservedMetaKey]: scope }
+}