mppx 0.5.13 → 0.5.16

package/src/tempo/server/Session.ts

@@ -37,6 +37,7 @@ import * as Store from '../../Store.js'
 import * as Client from '../../viem/Client.js'
 import * as Account from '../internal/account.js'
 import * as defaults from '../internal/defaults.js'
+import * as FeePayer from '../internal/fee-payer.js'
 import type * as types from '../internal/types.js'
 import * as Methods from '../Methods.js'
 import {
@@ -92,6 +93,7 @@ export function session<const parameters extends session.Parameters>(
     channelStateTtl = 5_000,
     currency = defaults.resolveCurrency(parameters),
     decimals = defaults.decimals,
+    feePayerPolicy,
     store: rawStore = Store.memory(),
     suggestedDeposit,
     unitType,
@@ -179,7 +181,7 @@ export function session<const parameters extends session.Parameters>(
       }
     },
 
-    async verify({ credential, request }) {
+    async verify({ credential, envelope, request }) {
       const { challenge, payload } = credential as Credential.Credential<SessionCredentialPayload>
 
       const resolvedRequest = Methods.session.schema.request.parse(request)
@@ -203,9 +205,10 @@ export function session<const parameters extends session.Parameters>(
             payload,
             methodDetails,
             resolvedFeePayer,
+            feePayerPolicy,
             waitForConfirmation,
           )
-          lastOnChainVerified.set(payload.channelId, Date.now())
+          lastOnChainVerified.set(sessionReceipt.channelId, Date.now())
           break
 
         case 'topUp':
@@ -216,8 +219,9 @@ export function session<const parameters extends session.Parameters>(
             payload,
             methodDetails,
             resolvedFeePayer,
+            feePayerPolicy,
           )
-          lastOnChainVerified.set(payload.channelId, Date.now())
+          lastOnChainVerified.set(sessionReceipt.channelId, Date.now())
           break
 
         case 'voucher':
@@ -251,6 +255,28 @@ export function session<const parameters extends session.Parameters>(
           })
       }
 
+      // In the default HTTP request/response mode, each successful content
+      // request consumes one unit immediately after the credential is accepted.
+      // This keeps equal-voucher replays bounded by the voucher's remaining
+      // balance instead of serving repeated responses for free.
+      if (
+        !parameters.sse &&
+        envelope &&
+        isBillableContentRequest(envelope.capturedRequest) &&
+        (payload.action === 'open' || payload.action === 'voucher')
+      ) {
+        const charged = await charge(
+          store,
+          sessionReceipt.channelId,
+          BigInt(resolvedRequest.amount),
+        )
+        sessionReceipt = {
+          ...sessionReceipt,
+          spent: charged.spent.toString(),
+          units: charged.units,
+        }
+      }
+
       return sessionReceipt
     },
 
@@ -261,28 +287,24 @@ export function session<const parameters extends session.Parameters>(
     //
     // close and topUp are always gated (204) — they are pure management.
     //
-    // open and voucher are gated only for bodyless POSTs (management
-    // updates). POSTs with a body are content requests — the client's
-    // original request piggybacked on the credential — so they fall
-    // through to serve content. GETs always fall through so auto-mode
-    // clients (whose fetch wrapper bundles open+voucher into a single
-    // GET retry) receive content as expected.
-    respond({ credential, input }) {
+    // open and voucher share the same captured-request classifier used
+    // during verification. Non-billable requests are treated as management
+    // updates; billable requests fall through to the application handler.
+    respond({ credential, envelope, input }) {
       const { payload } = credential as Credential.Credential<SessionCredentialPayload>
 
       if (payload.action === 'close') return new Response(null, { status: 204 })
       if (payload.action === 'topUp') return new Response(null, { status: 204 })
 
-      // open and voucher: gate only bodyless POSTs (management updates).
-      // POSTs with a body are content requests — fall through so the
-      // upstream response is returned to the client.
-      if (input.method === 'POST') {
-        const contentLength = input.headers.get('content-length')
-        if (contentLength !== null && contentLength !== '0') return undefined
-        if (input.headers.has('transfer-encoding')) return undefined
-        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),
       }
-      return undefined
+
+      if (isBillableContentRequest(capturedRequest)) return undefined
+      return new Response(null, { status: 204 })
     },
   })
 }
@@ -293,9 +315,13 @@ export declare namespace session {
     'feePayer' | 'recipient'
   >
 
+  type FeePayerPolicy = Partial<FeePayer.Policy>
+
   type Parameters = {
     /** TTL in milliseconds for cached on-chain channel state. After this duration, the server re-queries on-chain state during voucher handling to detect forced close requests. @default 5_000 */
     channelStateTtl?: number | undefined
+    /** Override the fee-sponsor policy used for sponsored open/topUp transactions. */
+    feePayerPolicy?: FeePayerPolicy | undefined
     /** Minimum voucher delta to accept (numeric string, default: "0"). */
     minVoucherDelta?: string | undefined
     /**
@@ -444,6 +470,30 @@ 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.
@@ -561,13 +611,11 @@ async function handleOpen(
   payload: SessionCredentialPayload & { action: 'open' },
   methodDetails: SessionMethodDetails,
   feePayer: viem_Account | undefined,
+  feePayerPolicy: session.FeePayerPolicy | undefined,
   waitForConfirmation: boolean,
 ): Promise<SessionReceipt> {
-  const voucher = parseVoucherFromPayload(
-    payload.channelId,
-    payload.cumulativeAmount,
-    payload.signature,
-  )
+  const channelId = ChannelStore.normalizeChannelId(payload.channelId)
+  const voucher = parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature)
 
   const recipient = challenge.request.recipient as Address
   const currency = challenge.request.currency as Address
@@ -577,9 +625,11 @@ async function handleOpen(
     client,
     serializedTransaction: payload.transaction,
     escrowContract: methodDetails.escrowContract,
-    channelId: payload.channelId,
+    channelId,
     recipient,
     currency,
+    challengeExpires: challenge.expires,
+    feePayerPolicy,
     feePayer,
     waitForConfirmation,
   })
@@ -612,7 +662,7 @@ async function handleOpen(
     throw new InvalidSignatureError({ reason: 'invalid voucher signature' })
   }
 
-  const updated = await store.updateChannel(payload.channelId, (existing) => {
+  const updated = await store.updateChannel(channelId, (existing) => {
     if (existing) {
       if (voucher.cumulativeAmount <= existing.settledOnChain) {
         throw new VerificationFailedError({
@@ -644,7 +694,7 @@ async function handleOpen(
       }
     }
     return {
-      channelId: payload.channelId,
+      channelId,
       chainId: methodDetails.chainId,
       escrowContract: methodDetails.escrowContract,
       closeRequestedAt: onChain.closeRequestedAt,
@@ -667,7 +717,7 @@ async function handleOpen(
 
   return createSessionReceipt({
     challengeId: challenge.id,
-    channelId: payload.channelId,
+    channelId: updated.channelId,
     acceptedCumulative: updated.highestVoucherAmount,
     spent: updated.spent,
     units: updated.units,
@@ -689,8 +739,10 @@ async function handleTopUp(
   payload: SessionCredentialPayload & { action: 'topUp' },
   methodDetails: SessionMethodDetails,
   feePayer: viem_Account | undefined,
+  feePayerPolicy: session.FeePayerPolicy | undefined,
 ): Promise<SessionReceipt> {
-  const channel = await store.getChannel(payload.channelId)
+  const channelId = ChannelStore.normalizeChannelId(payload.channelId)
+  const channel = await store.getChannel(channelId)
   if (!channel) {
     throw new ChannelNotFoundError({ reason: 'channel not found' })
   }
@@ -701,21 +753,23 @@ async function handleTopUp(
     client,
     serializedTransaction: payload.transaction,
     escrowContract: methodDetails.escrowContract,
-    channelId: payload.channelId,
+    channelId,
     currency: challenge.request.currency as Address,
     declaredDeposit,
     previousDeposit: channel.deposit,
+    challengeExpires: challenge.expires,
+    feePayerPolicy,
     feePayer,
   })
 
-  const updated = await store.updateChannel(payload.channelId, (current) => {
+  const updated = await store.updateChannel(channelId, (current) => {
     if (!current) throw new ChannelNotFoundError({ reason: 'channel not found' })
     return { ...current, deposit: onChainDeposit }
   })
 
   return createSessionReceipt({
     challengeId: challenge.id,
-    channelId: payload.channelId,
+    channelId: updated?.channelId ?? channel.channelId,
     acceptedCumulative: updated?.highestVoucherAmount ?? channel.highestVoucherAmount,
     spent: updated?.spent ?? channel.spent,
     units: updated?.units ?? channel.units,
@@ -735,7 +789,8 @@ async function handleVoucher(
   channelStateTtl: number,
   lastOnChainVerified: Map<Hex, number>,
 ): Promise<SessionReceipt> {
-  const channel = await store.getChannel(payload.channelId)
+  const channelId = ChannelStore.normalizeChannelId(payload.channelId)
+  const channel = await store.getChannel(channelId)
   if (!channel) {
     throw new ChannelNotFoundError({ reason: 'channel not found' })
   }
@@ -743,11 +798,7 @@ async function handleVoucher(
     throw new ChannelClosedError({ reason: 'channel is finalized' })
   }
 
-  const voucher = parseVoucherFromPayload(
-    payload.channelId,
-    payload.cumulativeAmount,
-    payload.signature,
-  )
+  const voucher = parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature)
 
   // Use locally-stored channel state as a trusted cache instead of
   // reading on-chain for every voucher. The on-chain state is verified
@@ -759,7 +810,7 @@ async function handleVoucher(
   // To guard against the payer initiating a forced close while vouchers
   // are still being accepted, re-query on-chain state when the cache
   // exceeds the configured staleness TTL (default: 5s).
-  const lastVerified = lastOnChainVerified.get(payload.channelId) ?? 0
+  const lastVerified = lastOnChainVerified.get(channelId) ?? 0
   const isStale = Date.now() - lastVerified > channelStateTtl
 
   const onChain = await (async () => {
@@ -767,13 +818,13 @@ async function handleVoucher(
       const onChainChannel = await getOnChainChannel(
         client,
         methodDetails.escrowContract,
-        payload.channelId,
+        channelId,
       )
-      lastOnChainVerified.set(payload.channelId, Date.now())
+      lastOnChainVerified.set(channelId, Date.now())
       // Persist closeRequestedAt so the cached path detects force-close
       // between re-queries.
       if (onChainChannel.closeRequestedAt !== 0n) {
-        await store.updateChannel(payload.channelId, (current) =>
+        await store.updateChannel(channelId, (current) =>
           current ? { ...current, closeRequestedAt: onChainChannel.closeRequestedAt } : current,
         )
       }
@@ -796,7 +847,7 @@ async function handleVoucher(
     minVoucherDelta,
     challenge,
     channel,
-    channelId: payload.channelId,
+    channelId,
     voucher,
     onChain,
     methodDetails,
@@ -815,7 +866,8 @@ async function handleClose(
   account?: viem_Account,
   feePayer?: viem_Account,
 ): Promise<SessionReceipt> {
-  const channel = await store.getChannel(payload.channelId)
+  const channelId = ChannelStore.normalizeChannelId(payload.channelId)
+  const channel = await store.getChannel(channelId)
   if (!channel) {
     throw new ChannelNotFoundError({ reason: 'channel not found' })
   }
@@ -823,13 +875,9 @@ async function handleClose(
     throw new ChannelClosedError({ reason: 'channel is already finalized' })
   }
 
-  const voucher = parseVoucherFromPayload(
-    payload.channelId,
-    payload.cumulativeAmount,
-    payload.signature,
-  )
+  const voucher = parseVoucherFromPayload(channelId, payload.cumulativeAmount, payload.signature)
 
-  const onChain = await getOnChainChannel(client, methodDetails.escrowContract, payload.channelId)
+  const onChain = await getOnChainChannel(client, methodDetails.escrowContract, channelId)
 
   if (onChain.finalized) {
     throw new ChannelClosedError({ reason: 'channel is finalized on-chain' })
@@ -867,7 +915,7 @@ async function handleClose(
     ...(feePayer && account ? { feePayer, account } : { account }),
   })
 
-  const updated = await store.updateChannel(payload.channelId, (current) => {
+  const updated = await store.updateChannel(channelId, (current) => {
     if (!current) return null
     const updateVoucher = voucher.cumulativeAmount > current.highestVoucherAmount
     return {
@@ -883,7 +931,7 @@ async function handleClose(
 
   return createSessionReceipt({
     challengeId: challenge.id,
-    channelId: payload.channelId,
+    channelId: updated?.channelId ?? channel.channelId,
     acceptedCumulative: voucher.cumulativeAmount,
     spent: updated?.spent ?? channel.spent,
     units: updated?.units ?? channel.units,