mppx 0.6.1 → 0.6.3

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.
  */
@@ -180,13 +191,6 @@ type ChallengeFn<method extends Method.Method, defaults extends Record<string, u
   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.
  *
@@ -295,11 +299,24 @@ export function create<
     // Validate payload against method schema
     mi.schema.credential.payload.parse(credential.payload)
 
+    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({
@@ -307,9 +324,9 @@ export function create<
           credential,
           defaults: mi.defaults,
           expires: credential.challenge.expires,
-          meta: options?.meta,
+          meta: expectedMeta,
           method: mi,
-          realm: options?.realm ?? realm,
+          realm: expectedRealm,
           request: mi.request as never,
           routeRequest: options?.request ?? {},
           secretKey: secretKey!,
@@ -399,13 +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 { 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] = (() => {
@@ -424,7 +446,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           defaults,
           description,
           expires,
-          meta,
+          meta: effectiveMeta,
           method,
           realm,
           request: parameters.request,
@@ -603,6 +625,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           ...method,
           ...defaults,
           ...options,
+          ...(staticMeta !== undefined ? { meta: staticMeta } : {}),
           name: method.name,
           intent: method.intent,
           _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
@@ -627,12 +650,14 @@ 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 effectiveMeta = Scope.merge({ meta, scope })
     const expires =
       'expires' in options ? (options.expires as string | undefined) : Expires.minutes(5)
 
@@ -640,7 +665,7 @@ function createChallengeFn(parameters: {
       defaults,
       description,
       expires,
-      meta,
+      meta: effectiveMeta,
       method,
       realm,
       request: parameters.request,
@@ -950,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> =
@@ -970,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 }
+}

package/src/tempo/client/SessionManager.ts

@@ -778,9 +778,21 @@ export function sessionManager(parameters: sessionManager.Parameters): SessionMa
       })
       if (!response.ok) {
         const body = await response.text().catch(() => '')
+        const detail = (() => {
+          if (!body) return ''
+          if (!response.headers.get('Content-Type')?.includes('application/problem+json')) {
+            return body
+          }
+          try {
+            const problem = JSON.parse(body) as { detail?: string }
+            return problem.detail ?? body
+          } catch {
+            return body
+          }
+        })()
         const wwwAuth = response.headers.get('WWW-Authenticate') ?? ''
         throw new Error(
-          `Close request failed with status ${response.status}${body ? `: ${body}` : ''}${wwwAuth ? ` [WWW-Authenticate: ${wwwAuth}]` : ''}`,
+          `Close request failed with status ${response.status}${detail ? `: ${detail}` : ''}${wwwAuth ? ` [WWW-Authenticate: ${wwwAuth}]` : ''}`,
         )
       }
       const receiptHeader = response.headers.get('Payment-Receipt')

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

@@ -7,7 +7,7 @@ import {
   Transport as ServerTransport,
   tempo as tempo_server,
 } from 'mppx/server'
-import { Base64 } from 'ox'
+import { Base64, Secp256k1 } from 'ox'
 import {
   type Address,
   createClient,
@@ -17,7 +17,7 @@ import {
   signatureToCompactSignature,
 } from 'viem'
 import { waitForTransactionReceipt } from 'viem/actions'
-import { Addresses } from 'viem/tempo'
+import { Account as TempoAccount, Actions, Addresses } from 'viem/tempo'
 import { beforeAll, beforeEach, describe, expect, expectTypeOf, test } from 'vp/test'
 import { WebSocketServer } from 'ws'
 import { nodeEnv } from '~test/config.js'
@@ -50,7 +50,8 @@ import {
 import type * as Methods from '../Methods.js'
 import * as ChannelStore from '../session/ChannelStore.js'
 import { deserializeSessionReceipt } from '../session/Receipt.js'
-import type { SessionReceipt } from '../session/Types.js'
+import { serializeSessionReceipt } from '../session/Receipt.js'
+import type { SessionCredentialPayload, SessionReceipt } from '../session/Types.js'
 import { signVoucher } from '../session/Voucher.js'
 import * as TempoWs from '../session/Ws.js'
 import { charge, session, settle } from './Session.js'
@@ -1886,6 +1887,77 @@ describe.runIf(isLocalnet)('session', () => {
       expect(ch!.settledOnChain).toBe(5000000n)
     })
 
+    test('accepts a Tempo access-key account for settlement', async () => {
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer()
+
+      await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'settle-access-key-open', channelId }),
+          payload: {
+            action: 'open' as const,
+            type: 'transaction' as const,
+            channelId,
+            transaction: serializedTransaction,
+            cumulativeAmount: '5000000',
+            signature: await signTestVoucher(channelId, 5000000n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      const privateKey = Secp256k1.randomPrivateKey()
+      const accessKey = TempoAccount.fromSecp256k1(privateKey, {
+        access: recipientAccount,
+      })
+
+      await Actions.accessKey.authorizeSync(client, {
+        account: recipientAccount,
+        accessKey,
+        feeToken: currency,
+      })
+
+      const settleTxHash = await settle(store, client, channelId, {
+        escrowContract,
+        account: accessKey,
+      })
+      expect(settleTxHash).toMatch(/^0x/)
+
+      const ch = await store.getChannel(channelId)
+      expect(ch!.settledOnChain).toBe(5000000n)
+    })
+
+    test('rejects a raw delegated key account with a helpful error', async () => {
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer()
+
+      await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'settle-raw-access-key-open', channelId }),
+          payload: {
+            action: 'open' as const,
+            type: 'transaction' as const,
+            channelId,
+            transaction: serializedTransaction,
+            cumulativeAmount: '5000000',
+            signature: await signTestVoucher(channelId, 5000000n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      const rawAccessKey = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey())
+
+      await expect(
+        settle(store, client, channelId, {
+          escrowContract,
+          account: rawAccessKey,
+        }),
+      ).rejects.toThrow(
+        `Cannot settle channel ${channelId}: tx sender ${rawAccessKey.address} is not the channel payee ${recipientAccount.address}. If using an access key, pass a Tempo access-key account whose address is the payee wallet, not the raw delegated key address.`,
+      )
+    })
+
     test('settle rejects when no channel found', async () => {
       const fakeChannelId =
         '0x0000000000000000000000000000000000000000000000000000000000000000' as Hex
@@ -1895,6 +1967,196 @@ describe.runIf(isLocalnet)('session', () => {
     })
   })
 
+  describe('close account shapes', () => {
+    test('root payee account closes successfully', async () => {
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer()
+      await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'close-root-payee-open', channelId }),
+          payload: {
+            action: 'open' as const,
+            type: 'transaction' as const,
+            channelId,
+            transaction: serializedTransaction,
+            cumulativeAmount: '1000000',
+            signature: await signTestVoucher(channelId, 1000000n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      const closeReceipt = await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'close-root-payee', channelId }),
+          payload: {
+            action: 'close' as const,
+            channelId,
+            cumulativeAmount: '1000000',
+            signature: await signTestVoucher(channelId, 1000000n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      expect(closeReceipt.status).toBe('success')
+      expect((await store.getChannel(channelId))?.finalized).toBe(true)
+    })
+
+    test('payee access-key account closes successfully', async () => {
+      const accessKey = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey(), {
+        access: recipientAccount,
+      })
+
+      await Actions.accessKey.authorizeSync(client, {
+        account: recipientAccount,
+        accessKey,
+        feeToken: currency,
+      })
+
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer({ account: accessKey })
+      await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'close-access-key-open', channelId }),
+          payload: {
+            action: 'open' as const,
+            type: 'transaction' as const,
+            channelId,
+            transaction: serializedTransaction,
+            cumulativeAmount: '1000000',
+            signature: await signTestVoucher(channelId, 1000000n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      const closeReceipt = await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'close-access-key', channelId }),
+          payload: {
+            action: 'close' as const,
+            channelId,
+            cumulativeAmount: '1000000',
+            signature: await signTestVoucher(channelId, 1000000n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      expect(closeReceipt.status).toBe('success')
+      expect((await store.getChannel(channelId))?.finalized).toBe(true)
+    })
+
+    test('raw delegated server key fails clearly during close', async () => {
+      const rawAccessKey = TempoAccount.fromSecp256k1(Secp256k1.randomPrivateKey())
+      const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)
+      const server = createServer({ account: rawAccessKey, recipient })
+      await server.verify({
+        credential: {
+          challenge: makeChallenge({ id: 'close-raw-access-key-open', channelId }),
+          payload: {
+            action: 'open' as const,
+            type: 'transaction' as const,
+            channelId,
+            transaction: serializedTransaction,
+            cumulativeAmount: '1000000',
+            signature: await signTestVoucher(channelId, 1000000n),
+          },
+        },
+        request: makeRequest(),
+      })
+
+      await expect(
+        server.verify({
+          credential: {
+            challenge: makeChallenge({ id: 'close-raw-access-key', channelId }),
+            payload: {
+              action: 'close' as const,
+              channelId,
+              cumulativeAmount: '1000000',
+              signature: await signTestVoucher(channelId, 1000000n),
+            },
+          },
+          request: makeRequest(),
+        }),
+      ).rejects.toThrow(
+        `Cannot close channel ${channelId}: tx sender ${rawAccessKey.address} is not the channel payee ${recipientAccount.address}. If using an access key, pass a Tempo access-key account whose address is the payee wallet, not the raw delegated key address.`,
+      )
+    })
+
+    test('sessionManager.close surfaces problem details from HTTP close failures', async () => {
+      const challenge = makeChallenge({
+        id: 'close-http-failure',
+        channelId: '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex,
+      })
+      let requests = 0
+
+      const fetch = async (_input: RequestInfo | URL, init?: RequestInit) => {
+        requests++
+
+        const authorization = new Headers(init?.headers).get('Authorization')
+        if (!authorization) {
+          return new Response(null, {
+            status: 402,
+            headers: { 'WWW-Authenticate': Challenge.serialize(challenge) },
+          })
+        }
+
+        const credential = Credential.deserialize<SessionCredentialPayload>(authorization)
+        if (credential.payload.action === 'open') {
+          return new Response('ok', {
+            status: 200,
+            headers: {
+              'Payment-Receipt': serializeSessionReceipt({
+                method: 'tempo',
+                intent: 'session',
+                status: 'success',
+                timestamp: new Date().toISOString(),
+                reference: credential.payload.channelId,
+                challengeId: credential.challenge.id,
+                channelId: credential.payload.channelId,
+                acceptedCumulative: credential.payload.cumulativeAmount,
+                spent: credential.payload.cumulativeAmount,
+                units: 1,
+              }),
+            },
+          })
+        }
+
+        if (credential.payload.action === 'close') {
+          return new Response(
+            JSON.stringify({ detail: 'raw delegated key is not the payee wallet' }),
+            {
+              status: 400,
+              headers: { 'Content-Type': 'application/problem+json' },
+            },
+          )
+        }
+
+        throw new Error(
+          `unexpected payment action ${(credential.payload as { action: string }).action}`,
+        )
+      }
+
+      const manager = sessionManager({
+        account: payer,
+        client,
+        escrowContract,
+        fetch,
+        maxDeposit: '1',
+      })
+
+      const response = await manager.fetch('https://api.example.com/resource')
+      expect(response.status).toBe(200)
+
+      await expect(manager.close()).rejects.toThrow(
+        'Close request failed with status 400: raw delegated key is not the payee wallet',
+      )
+      expect(requests).toBe(3)
+    })
+  })
+
   describe('non-persistent storage recovery', () => {
     test('open on existing on-chain channel initializes settledOnChain from chain', async () => {
       const { channelId, serializedTransaction } = await createSignedOpenTransaction(10000000n)

package/src/tempo/server/Session.ts

@@ -369,6 +369,22 @@ export declare namespace session {
   }
 }
 
+function assertSettlementSender(parameters: {
+  operation: 'close' | 'settle'
+  channelId: Hex
+  payee: Address
+  sender: Address | undefined
+}) {
+  const { operation, channelId, payee, sender } = parameters
+  if (!sender) return
+  if (sender.toLowerCase() === payee.toLowerCase()) return
+  throw new BadRequestError({
+    reason:
+      `Cannot ${operation} channel ${channelId}: tx sender ${sender} is not the channel payee ${payee}. ` +
+      'If using an access key, pass a Tempo access-key account whose address is the payee wallet, not the raw delegated key address.',
+  })
+}
+
 /**
  * One-shot settle: reads highest voucher from store and submits on-chain.
  */
@@ -393,6 +409,13 @@ export async function settle(
     defaults.escrowContract[chainId as keyof typeof defaults.escrowContract]
   if (!resolvedEscrow) throw new Error(`No escrow contract for chainId ${chainId}.`)
 
+  assertSettlementSender({
+    operation: 'settle',
+    channelId,
+    payee: channel.payee,
+    sender: options?.account?.address ?? client.account?.address,
+  })
+
   const settledAmount = channel.highestVoucher.cumulativeAmount
   const txHash = await settleOnChain(client, resolvedEscrow, channel.highestVoucher, {
     ...(options?.feePayer && options?.account
@@ -891,6 +914,13 @@ async function handleClose(
     throw new InvalidSignatureError({ reason: 'invalid voucher signature' })
   }
 
+  assertSettlementSender({
+    operation: 'close',
+    channelId: payload.channelId,
+    payee: onChain.payee,
+    sender: account?.address ?? client.account?.address,
+  })
+
   const txHash = await closeOnChain(client, methodDetails.escrowContract, voucher, {
     ...(feePayer && account ? { feePayer, account } : { account }),
   })