mppx 0.6.31 → 0.8.0

package/src/tempo/server/internal/request-body.test.ts

@@ -9,7 +9,16 @@ import {
 
 describe('request-body', () => {
   describe('hasCapturedRequestBody', () => {
-    test('returns true when the captured request recorded a body stream', () => {
+    test('returns true when the captured request recorded a typed body stream', () => {
+      expect(
+        hasCapturedRequestBody({
+          hasBody: true,
+          headers: new Headers({ 'content-type': 'application/json' }),
+        }),
+      ).toBe(true)
+    })
+
+    test('returns true for captured body streams without body headers', () => {
       expect(
         hasCapturedRequestBody({
           hasBody: true,
@@ -63,7 +72,17 @@ describe('request-body', () => {
       ).toBe(false)
     })
 
-    test('treats POST requests with a body stream and no content-length as content requests', () => {
+    test('treats POST requests with a typed body stream and no content-length as content requests', () => {
+      expect(
+        isSessionContentRequest({
+          hasBody: true,
+          headers: new Headers({ 'content-type': 'application/json' }),
+          method: 'POST',
+        }),
+      ).toBe(true)
+    })
+
+    test('treats POST body streams without body headers as content requests', () => {
       expect(
         isSessionContentRequest({
           hasBody: true,
@@ -107,12 +126,12 @@ describe('request-body', () => {
       expect(shouldChargePlainResponse(input, { action: 'topUp' })).toBe(false)
     })
 
-    test('charges POST content requests detected via the body stream', () => {
+    test('charges POST content requests detected via the typed body stream', () => {
       expect(
         shouldChargePlainResponse(
           {
             hasBody: true,
-            headers: new Headers(),
+            headers: new Headers({ 'content-type': 'application/json' }),
             method: 'POST',
           },
           { action: 'voucher' },
@@ -133,6 +152,20 @@ describe('request-body', () => {
       ).toBe(false)
     })
 
+    test('charges voucher POSTs when runtime reports a body stream', () => {
+      expect(
+        shouldChargePlainResponse(
+          {
+            hasBody: true,
+            headers: new Headers(),
+            method: 'POST',
+            url: new URL('https://api.example.com/session'),
+          },
+          { action: 'voucher' },
+        ),
+      ).toBe(true)
+    })
+
     test('charges bodyless POST query requests', () => {
       expect(
         shouldChargePlainResponse(

package/src/tempo/server/internal/request-body.ts

@@ -1,9 +1,11 @@
 import type * as Method from '../../../Method.js'
-import type { SessionCredentialPayload } from '../../session/Types.js'
+import type { SessionCredentialContext } from '../../session/precompile/Protocol.js'
 
+/** Minimal immutable request shape used to decide whether a session request serves billable content. */
 export type RequestBodyProbe = Pick<Method.CapturedRequest, 'headers' | 'hasBody' | 'method'> &
   Partial<Pick<Method.CapturedRequest, 'url'>>
 
+/** Captures the request fields needed by the session content/management classifier. */
 export function captureRequestBodyProbe(input: Request): RequestBodyProbe {
   return {
     headers: input.headers,
@@ -13,17 +15,25 @@ export function captureRequestBodyProbe(input: Request): RequestBodyProbe {
   }
 }
 
+/** Returns whether request metadata indicates a meaningful body is present. */
 export function hasCapturedRequestBody(
   input: Pick<RequestBodyProbe, 'headers' | 'hasBody'>,
 ): boolean {
+  if (hasBodyFramingHeaders(input)) return true
+  if (input.hasBody === true) return true
+  return false
+}
+
+function hasBodyFramingHeaders(input: Pick<RequestBodyProbe, 'headers'>): boolean {
   const contentLength = input.headers.get('content-length')
-  const headerIndicatesBody =
-    (contentLength !== null && contentLength !== '0') || input.headers.has('transfer-encoding')
+  return (contentLength !== null && contentLength !== '0') || input.headers.has('transfer-encoding')
+}
 
-  if (input.hasBody === true) return true
-  return headerIndicatesBody
+function hasBodyIntentHeaders(input: Pick<RequestBodyProbe, 'headers'>): boolean {
+  return hasBodyFramingHeaders(input) || input.headers.has('content-type')
 }
 
+/** Returns whether a verified session credential should let the application handler serve content. */
 export function isSessionContentRequest(input: RequestBodyProbe): boolean {
   if (input.method === 'HEAD') return false
   if (input.method !== 'POST') return true
@@ -31,10 +41,19 @@ export function isSessionContentRequest(input: RequestBodyProbe): boolean {
   return hasCapturedRequestBody(input)
 }
 
+/** Returns whether a plain non-streaming response should be charged after verification. */
 export function shouldChargePlainResponse(
   input: RequestBodyProbe,
-  payload: Partial<SessionCredentialPayload>,
+  payload: Partial<SessionCredentialContext>,
 ): boolean {
   if (payload.action === 'close' || payload.action === 'topUp') return false
+  if (
+    (payload.action === 'open' || payload.action === 'voucher') &&
+    input.method === 'POST' &&
+    !input.url?.search &&
+    input.hasBody !== true &&
+    !hasBodyIntentHeaders(input)
+  )
+    return false
   return isSessionContentRequest(input)
 }

package/src/tempo/server/internal/transport.test.ts

@@ -4,10 +4,10 @@ import { describe, expect, test } from 'vp/test'
 
 import * as Store from '../../../Store.js'
 import { chainId, escrowContract as escrowContractDefaults } from '../../internal/defaults.js'
-import * as ChannelStore from '../../session/ChannelStore.js'
-import { deserializeSessionReceipt } from '../../session/Receipt.js'
-import { parseEvent } from '../../session/Sse.js'
-import type { SessionReceipt } from '../../session/Types.js'
+import { deserializeSessionReceipt } from '../../session/precompile/Protocol.js'
+import type { SessionReceipt } from '../../session/precompile/Protocol.js'
+import * as ChannelStore from '../../session/server/ChannelStore.js'
+import { parseEvent } from '../../session/server/Sse.js'
 import { markPrepaidSessionTick, sse } from './transport.js'
 
 const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as Hex

package/src/tempo/server/internal/transport.ts

@@ -6,11 +6,13 @@
  * @internal
  */
 import * as Challenge from '../../../Challenge.js'
+import * as Constants from '../../../Constants.js'
 import * as Errors from '../../../Errors.js'
 import * as Transport from '../../../server/Transport.js'
-import * as ChannelStore from '../../session/ChannelStore.js'
-import * as Sse_core from '../../session/Sse.js'
-import type { SessionCredentialPayload, SessionReceipt } from '../../session/Types.js'
+import type { SessionReceipt } from '../../session/precompile/Protocol.js'
+import { requireSessionCredentialContext } from '../../session/precompile/Protocol.js'
+import * as ChannelStore from '../../session/server/ChannelStore.js'
+import * as Sse_core from '../../session/server/Sse.js'
 import { captureRequestBodyProbe, shouldChargePlainResponse } from './request-body.js'
 
 const prepaidSessionTick = Symbol('mppx.prepaidSessionTick')
@@ -18,10 +20,12 @@ const prepaidSessionTick = Symbol('mppx.prepaidSessionTick')
 /** SSE transport with Tempo session controller. */
 export type Sse = Transport.Sse<Sse_core.SessionController>
 
+/** Receipt marker used to avoid double-charging a request already charged during verification. */
 export type PrepaidSessionReceipt = SessionReceipt & {
   [prepaidSessionTick]?: true | undefined
 }
 
+/** Marks a session receipt as already charged for the current request. */
 export function markPrepaidSessionTick(receipt: SessionReceipt): SessionReceipt {
   Object.defineProperty(receipt, prepaidSessionTick, {
     configurable: false,
@@ -83,9 +87,10 @@ export function sse(options: sse.Options & { store: ChannelStore.ChannelStore })
       const verifiedCredential = envelope?.credential ?? credential
       const verifiedChallengeId = envelope?.challenge.id ?? challengeId
       const verifiedRequest = envelope?.request ?? verifiedCredential.challenge.request
-      const payload = verifiedCredential.payload as Partial<SessionCredentialPayload>
-      if (!payload.channelId) throw new Error('No SSE context available')
-
+      const payload = requireSessionCredentialContext(
+        verifiedCredential.payload,
+        'No SSE context available',
+      )
       const channelId = payload.channelId
       const tickCost = BigInt(verifiedCredential.challenge.request.amount as string)
       const unitType =
@@ -146,7 +151,9 @@ export function sse(options: sse.Options & { store: ChannelStore.ChannelStore })
           {
             status: error.status,
             headers: {
-              'WWW-Authenticate': Challenge.serialize(verifiedCredential.challenge),
+              [Constants.Headers.wwwAuthenticate]: Challenge.serialize(
+                verifiedCredential.challenge,
+              ),
               'Cache-Control': 'no-store',
               'Content-Type': 'application/problem+json',
             },
@@ -217,6 +224,7 @@ export function sse(options: sse.Options & { store: ChannelStore.ChannelStore })
   })
 }
 
+/** Type helpers for the Tempo SSE transport adapter. */
 export declare namespace sse {
   type Options = {
     /**
@@ -235,13 +243,14 @@ export declare namespace sse {
   }
 }
 
+type DefaultServeGenerate = AsyncIterable<string> | (() => AsyncIterable<string>)
+
 /** Default SSE serve: iterates values and emits `event: message` per value. */
 export function defaultServe(options: {
-  generate: AsyncIterable<string> | ((...args: any[]) => AsyncIterable<string>)
+  generate: DefaultServeGenerate
   challengeId: string
 }): Response {
-  const iterable =
-    typeof options.generate === 'function' ? options.generate(undefined as any) : options.generate
+  const iterable = typeof options.generate === 'function' ? options.generate() : options.generate
   const encoder = new TextEncoder()
   const stream = new ReadableStream<Uint8Array>({
     async start(controller) {

package/src/tempo/session/Snapshot.test.ts

@@ -0,0 +1,41 @@
+import { Base64 } from 'ox'
+import { describe, expect, test } from 'vp/test'
+
+import { deserializeSnapshot, serializeSnapshot, type SessionSnapshot } from './Snapshot.js'
+
+const descriptor = {
+  authorizedSigner: '0x0000000000000000000000000000000000000001',
+  expiringNonceHash: `0x${'11'.repeat(32)}`,
+  operator: '0x0000000000000000000000000000000000000000',
+  payee: '0x0000000000000000000000000000000000000002',
+  payer: '0x0000000000000000000000000000000000000003',
+  salt: `0x${'22'.repeat(32)}`,
+  token: '0x20c0000000000000000000000000000000000001',
+} as const
+
+const snapshot = {
+  acceptedCumulative: '100',
+  chainId: 4217,
+  channelId: `0x${'aa'.repeat(32)}`,
+  deposit: '1000',
+  descriptor,
+  escrow: '0x4d50500000000000000000000000000000000000',
+  requiredCumulative: '100',
+  settled: '0',
+  spent: '50',
+  units: 5,
+} satisfies SessionSnapshot
+
+describe('SessionSnapshot', () => {
+  test('round-trips a valid snapshot header', () => {
+    expect(deserializeSnapshot(serializeSnapshot(snapshot))).toEqual(snapshot)
+  })
+
+  test('rejects malformed channel descriptors', () => {
+    const value = serializeSnapshot(snapshot)
+    const encoded = JSON.parse(Base64.toString(value)) as SessionSnapshot
+    encoded.descriptor = { ...descriptor, payee: 'not-an-address' as never }
+
+    expect(() => deserializeSnapshot(Base64.fromString(JSON.stringify(encoded)))).toThrow()
+  })
+})

package/src/tempo/session/Snapshot.ts

@@ -0,0 +1,74 @@
+import { isAddress, type Address, type Hex } from 'viem'
+
+import * as HeaderCodec from '../../internal/HeaderCodec.js'
+import * as z from '../../zod.js'
+import type { ChannelDescriptor, RawAmountString } from './precompile/Protocol.js'
+
+/** Server-provided reusable channel state used to bootstrap a client session. */
+export type SessionSnapshot = {
+  /** Highest cumulative voucher amount the server has accepted for this channel. */
+  acceptedCumulative: RawAmountString
+  /** Tempo chain ID used to derive the channel ID and voucher domain. */
+  chainId: number
+  /** TIP-1034 channel ID derived from descriptor, escrow address, and chain ID. */
+  channelId: Hex
+  /** Timestamp when unilateral close was requested, when the channel is closing. */
+  closeRequestedAt?: RawAmountString | undefined
+  /** Current on-chain deposit ceiling for cumulative voucher authorization. */
+  deposit: RawAmountString
+  /** Full descriptor needed to recover the channel without client-side persistence. */
+  descriptor: ChannelDescriptor
+  /** Escrow precompile address used to derive the channel ID. */
+  escrow: Address
+  /** Minimum cumulative authorization needed for the challenged request or stream continuation. */
+  requiredCumulative: RawAmountString
+  /** Amount already settled on-chain. */
+  settled: RawAmountString
+  /** Amount consumed by delivered content according to server accounting. */
+  spent: RawAmountString
+  /** Paid units delivered by the server, when the transport reports them. */
+  units?: number | undefined
+}
+
+const addressSchema = z.custom<Address>(
+  (value) => typeof value === 'string' && isAddress(value, { strict: false }),
+)
+const hashSchema = z.custom<Hex>(
+  (value) => typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value),
+)
+
+const channelDescriptorSchema = z.object({
+  authorizedSigner: addressSchema,
+  expiringNonceHash: hashSchema,
+  operator: addressSchema,
+  payee: addressSchema,
+  payer: addressSchema,
+  salt: hashSchema,
+  token: addressSchema,
+})
+
+const sessionSnapshotSchema = z.object({
+  acceptedCumulative: z.string(),
+  chainId: z.number(),
+  channelId: hashSchema,
+  closeRequestedAt: z.optional(z.string()),
+  deposit: z.string(),
+  descriptor: channelDescriptorSchema,
+  escrow: addressSchema,
+  requiredCumulative: z.string(),
+  settled: z.string(),
+  spent: z.string(),
+  units: z.optional(z.number()),
+})
+
+const sessionSnapshotHeader = HeaderCodec.createJson(sessionSnapshotSchema)
+
+/** Serializes a session snapshot for the `Payment-Session-Snapshot` header. */
+export function serializeSnapshot(snapshot: SessionSnapshot): string {
+  return sessionSnapshotHeader.encode(snapshot)
+}
+
+/** Deserializes a session snapshot from the `Payment-Session-Snapshot` header. */
+export function deserializeSnapshot(value: string): SessionSnapshot {
+  return sessionSnapshotHeader.decode(value) as SessionSnapshot
+}

package/src/tempo/session/client/ChannelOps.test.ts

@@ -0,0 +1,163 @@
+import { Hex } from 'ox'
+import { type Address, createClient, custom, zeroAddress } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { describe, expect, test } from 'vp/test'
+
+import * as Channel from '../precompile/Channel.js'
+import { tip20ChannelEscrow } from '../precompile/Protocol.js'
+import * as Types from '../precompile/Protocol.js'
+import * as Voucher from '../precompile/Voucher.js'
+import * as ChannelOps from './ChannelOps.js'
+
+const account = privateKeyToAccount(
+  '0xac0974bec39a17e36ba6a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+)
+const client = createClient({
+  account,
+  transport: custom({
+    async request() {
+      throw new Error('unexpected rpc request')
+    },
+  }),
+})
+const chainId = 42431
+
+const descriptor = {
+  payer: account.address,
+  payee: '0x0000000000000000000000000000000000000002' as Address,
+  operator: '0x0000000000000000000000000000000000000000' as Address,
+  token: '0x0000000000000000000000000000000000000003' as Address,
+  salt: `0x${'11'.repeat(32)}` as Hex.Hex,
+  authorizedSigner: account.address,
+  expiringNonceHash: `0x${'22'.repeat(32)}` as Hex.Hex,
+} satisfies Channel.ChannelDescriptor
+
+const channelId = Channel.computeId({ ...descriptor, chainId, escrow: tip20ChannelEscrow })
+
+describe('precompile client ChannelOps credential builders', () => {
+  test('resolves escrow from override, challenge hint, or canonical default', () => {
+    const override = '0x0000000000000000000000000000000000000005' as Address
+    const hinted = '0x0000000000000000000000000000000000000006' as Address
+
+    expect(
+      ChannelOps.resolveEscrow(
+        { request: { methodDetails: { escrowContract: hinted } } },
+        override,
+      ),
+    ).toBe(override)
+    expect(
+      ChannelOps.resolveEscrow({ request: { methodDetails: { escrowContract: hinted } } }),
+    ).toBe(hinted)
+    expect(ChannelOps.resolveEscrow({ request: { methodDetails: { escrow: hinted } } })).toBe(
+      hinted,
+    )
+    expect(
+      ChannelOps.resolveEscrow({
+        request: { methodDetails: { escrowContract: 'not-an-address' } },
+      }),
+    ).toBe(tip20ChannelEscrow)
+    expect(ChannelOps.resolveEscrow({ request: { methodDetails: {} } })).toBe(tip20ChannelEscrow)
+  })
+
+  test('creates a verifiable voucher credential for an existing precompile channel', async () => {
+    const cumulativeAmount = Types.uint96(250n)
+    const payload = await ChannelOps.createVoucherPayload(
+      client,
+      account,
+      descriptor,
+      cumulativeAmount,
+      chainId,
+    )
+    if (payload.action !== 'voucher') throw new Error('expected voucher payload')
+
+    expect(payload.channelId).toBe(channelId)
+    expect(payload.descriptor).toEqual(descriptor)
+    expect(payload.cumulativeAmount).toBe('250')
+    expect(
+      Voucher.verifyVoucher(
+        tip20ChannelEscrow,
+        chainId,
+        { channelId, cumulativeAmount, signature: payload.signature },
+        descriptor.authorizedSigner,
+      ),
+    ).toBe(true)
+  })
+
+  test('binds voucher channel ID and signature domain to the provided escrow', async () => {
+    const escrow = '0x0000000000000000000000000000000000000005' as Address
+    const cumulativeAmount = Types.uint96(260n)
+    const expectedChannelId = Channel.computeId({ ...descriptor, chainId, escrow })
+    const payload = await ChannelOps.createVoucherPayload(
+      client,
+      account,
+      descriptor,
+      cumulativeAmount,
+      chainId,
+      escrow,
+    )
+
+    expect(payload.channelId).toBe(expectedChannelId)
+    expect(
+      Voucher.verifyVoucher(
+        escrow,
+        chainId,
+        { channelId: expectedChannelId, cumulativeAmount, signature: payload.signature },
+        descriptor.authorizedSigner,
+      ),
+    ).toBe(true)
+  })
+
+  test('uses the payer as voucher signer when descriptor authorizedSigner is zero', async () => {
+    const zeroSignerDescriptor = {
+      ...descriptor,
+      authorizedSigner: zeroAddress,
+    }
+    const zeroSignerChannelId = Channel.computeId({
+      ...zeroSignerDescriptor,
+      chainId,
+      escrow: tip20ChannelEscrow,
+    })
+    const cumulativeAmount = Types.uint96(275n)
+    const payload = await ChannelOps.createVoucherPayload(
+      client,
+      account,
+      zeroSignerDescriptor,
+      cumulativeAmount,
+      chainId,
+    )
+    if (payload.action !== 'voucher') throw new Error('expected voucher payload')
+
+    expect(payload.channelId).toBe(zeroSignerChannelId)
+    expect(
+      Voucher.verifyVoucher(
+        tip20ChannelEscrow,
+        chainId,
+        { channelId: zeroSignerChannelId, cumulativeAmount, signature: payload.signature },
+        descriptor.payer,
+      ),
+    ).toBe(true)
+  })
+
+  test('creates a close credential with a verifiable voucher signature', async () => {
+    const cumulativeAmount = Types.uint96(300n)
+    const payload = await ChannelOps.createClosePayload(
+      client,
+      account,
+      descriptor,
+      cumulativeAmount,
+      chainId,
+    )
+    if (payload.action !== 'close') throw new Error('expected close payload')
+
+    expect(payload.channelId).toBe(channelId)
+    expect(payload.cumulativeAmount).toBe('300')
+    expect(
+      Voucher.verifyVoucher(
+        tip20ChannelEscrow,
+        chainId,
+        { channelId, cumulativeAmount, signature: payload.signature },
+        descriptor.authorizedSigner,
+      ),
+    ).toBe(true)
+  })
+})