mppx 0.8.17 → 0.8.19

package/src/tempo/session/server/Ws.ts

@@ -1,391 +0,0 @@
-import * as Constants from '../../../Constants.js'
-import * as Credential from '../../../Credential.js'
-import {
-  createSessionReceipt,
-  deserializeSessionReceipt,
-  formatApplicationMessage,
-  formatCloseReadyMessage,
-  formatErrorMessage,
-  formatNeedVoucherMessage,
-  formatReceiptMessage,
-  parseMessage,
-  readSessionChallengeAmount,
-  requireSessionCredentialContext,
-  type SessionCredentialContext,
-  type SessionReceipt,
-} from '../precompile/Protocol.js'
-import * as ChannelStore from './ChannelStore.js'
-import type { MeteredStreamOptions, SessionController } from './MeteredStream.js'
-import type { SettleChargedSessionChannel } from './Settlement.js'
-export type { SessionController } from './MeteredStream.js'
-export type { Socket } from './Transports.js'
-import { meterIterable } from './MeteredStream.js'
-import { send, subscribe, toText, type Socket } from './Transports.js'
-
-/** Public WebSocket payment frame helpers. */
-export {
-  formatApplicationMessage,
-  formatAuthorizationMessage,
-  formatCloseReadyMessage,
-  formatCloseRequestMessage,
-  formatErrorMessage,
-  formatNeedVoucherMessage,
-  formatReceiptMessage,
-  parseMessage,
-  type ErrorMessageParameters,
-  type Message,
-} from '../precompile/Protocol.js'
-
-/** Result returned by an HTTP route before upgrading or authorizing a WebSocket session. */
-export type SessionRouteResult =
-  | { status: 402; challenge: Response }
-  | { status: 200; withReceipt(response?: Response): Response }
-
-/** HTTP route used to perform a WebSocket payment probe. */
-export type SessionRoute = (request: Request) => Promise<SessionRouteResult>
-
-type StreamContext = {
-  challengeId: string
-  channelId: SessionCredentialContext['channelId']
-  tickCost: bigint
-}
-
-/** Result of verifying one in-band authorization frame through the HTTP payment route. */
-type AuthorizationResult =
-  | {
-      status: 'accepted'
-      receipt: SessionReceipt
-    }
-  | {
-      status: 'rejected'
-      message: string
-      responseStatus: number
-    }
-
-/** Mutable server-side runtime state for one paid WebSocket connection. */
-type ServeRuntime = {
-  /** Whether the socket has been closed or externally disconnected. */
-  closed: boolean
-  /** Whether a final close-ready receipt has already been sent. */
-  closeReadySent: boolean
-  /** Whether an in-band close request has already been processed. */
-  closeRequestHandled: boolean
-  /** Whether the client has requested close and no new stream should start. */
-  closeRequested: boolean
-  /** Whether application streaming has started for this connection. */
-  streamStarted: boolean
-  /** Active stream task, when application generation is in progress. */
-  streamTask: Promise<void> | null
-  /** Active payment context for the stream. */
-  streamContext: StreamContext | null
-  /** Serialized payment-management action queue. */
-  action: Promise<void>
-  /** Number of queued payment-management messages waiting behind `action`. */
-  queuedActions: number
-}
-
-/**
- * Bridge a WebSocket connection to a Tempo session payment flow.
- *
- * Credential verification is performed by routing each in-band authorization
- * frame through `route` as a **synthetic `POST` request** that carries only
- * the `Authorization` header. The synthetic request does not include cookies,
- * bodies, query parameters, or other headers from the original WebSocket
- * upgrade request. Do not wrap `route` with middleware that depends on
- * HTTP-specific context beyond the `Authorization` header.
- */
-export async function serve(options: serve.Options): Promise<void> {
-  const {
-    amount: expectedAmount,
-    generate,
-    pollIntervalMs = 100,
-    route,
-    socket,
-    store: rawStore,
-    url,
-  } = options
-  const store = 'getChannel' in rawStore ? rawStore : ChannelStore.fromStore(rawStore)
-  const requestUrl = normalizeHttpUrl(url)
-  const maxQueuedPaymentMessages = 32
-
-  const abortController = new AbortController()
-  const runtime: ServeRuntime = {
-    closed: false,
-    closeReadySent: false,
-    closeRequestHandled: false,
-    closeRequested: false,
-    streamStarted: false,
-    streamTask: null,
-    streamContext: null,
-    action: Promise.resolve(),
-    queuedActions: 0,
-  }
-
-  const close = async (code = 1000, reason?: string) => {
-    if (runtime.closed) return
-    runtime.closed = true
-    abortController.abort()
-    unsubscribe()
-    await Promise.resolve(socket.close(code, reason))
-  }
-
-  const sendCloseReady = async () => {
-    if (runtime.closeReadySent || !runtime.streamContext || runtime.closed) return
-    runtime.closeReadySent = true
-
-    const channel = await store.getChannel(runtime.streamContext.channelId)
-    if (!channel) throw new Error('channel not found')
-
-    const receipt = createSessionReceipt({
-      challengeId: runtime.streamContext.challengeId,
-      channelId: runtime.streamContext.channelId,
-      acceptedCumulative: channel.highestVoucherAmount,
-      spent: channel.spent,
-      units: channel.units,
-    })
-    await send(socket, formatCloseReadyMessage(receipt))
-  }
-
-  const runStream = async (context: StreamContext) => {
-    try {
-      for await (const value of meterIterable({
-        store,
-        channelId: context.channelId,
-        tickCost: context.tickCost,
-        generate,
-        onChargeCommitted: options.onChargeCommitted ?? options.settleScheduled,
-        pollIntervalMs,
-        signal: abortController.signal,
-        emitNeedVoucher: (message) => send(socket, message),
-        formatNeedVoucher: formatNeedVoucherMessage,
-      })) {
-        if (abortController.signal.aborted) break
-        await send(socket, formatApplicationMessage(value))
-      }
-
-      if (!abortController.signal.aborted) await sendCloseReady()
-    } catch (error) {
-      if (!abortController.signal.aborted) {
-        await send(
-          socket,
-          formatErrorMessage({
-            message: error instanceof Error ? error.message : 'websocket session failed',
-            status: 500,
-          }),
-        )
-        await close(1011, 'websocket session failed')
-      }
-    } finally {
-      runtime.streamTask = null
-    }
-  }
-
-  const requestClose = async () => {
-    if (runtime.closed) return
-    if (runtime.closeRequestHandled) return
-    runtime.closeRequestHandled = true
-    runtime.closeRequested = true
-    abortController.abort()
-    await runtime.streamTask?.catch(() => {})
-    await sendCloseReady()
-  }
-
-  const processAuthorization = async (authorization: string) => {
-    if (runtime.closed) return
-    const credential = Credential.deserialize(authorization)
-    const payload = requireSessionCredentialContext(credential.payload)
-    if (payload.action === 'close') runtime.closeRequested = true
-
-    if (expectedAmount && credential.challenge.request.amount !== expectedAmount) {
-      await send(
-        socket,
-        formatErrorMessage({
-          message: 'credential amount does not match this endpoint',
-          status: 402,
-        }),
-      )
-      await close(1008, 'credential amount does not match this endpoint')
-      return
-    }
-
-    const authorizationResult = await authorizePaymentFrame({ authorization, requestUrl, route })
-    if (authorizationResult.status === 'rejected') {
-      await send(
-        socket,
-        formatErrorMessage({
-          message: authorizationResult.message,
-          status: authorizationResult.responseStatus,
-        }),
-      )
-      await close(1008, authorizationResult.message)
-      return
-    }
-
-    const { receipt } = authorizationResult
-    if (payload.action === 'voucher' && runtime.streamContext) {
-      runtime.streamContext.challengeId = credential.challenge.id
-    }
-    await send(socket, formatReceiptMessage(receipt))
-
-    if (payload.action === 'close') {
-      await close(1000, 'payment session closed')
-      return
-    }
-
-    if (payload.action === 'topUp') return
-    if (runtime.streamStarted || runtime.closeRequested) return
-    runtime.streamStarted = true
-    runtime.streamContext = {
-      challengeId: credential.challenge.id,
-      channelId: payload.channelId,
-      tickCost: readSessionChallengeAmount(credential.challenge),
-    }
-    // Defer the first application frame until after the client receives the
-    // auth receipt and has a chance to install its own message listeners.
-    setTimeout(() => {
-      if (runtime.closeRequested || runtime.closed || !runtime.streamContext) return
-      runtime.streamTask = runStream(runtime.streamContext)
-    }, 0)
-  }
-
-  const onMessage = (payload: unknown) => {
-    if (runtime.closed) return
-    const raw = toText(payload)
-    if (!raw) return
-    const message = parseMessage(raw)
-    if (!message) return
-
-    if (message.mpp === 'payment-close-request') {
-      runtime.closeRequested = true
-      abortController.abort()
-    }
-
-    const work =
-      message.mpp === 'authorization'
-        ? () => processAuthorization(message.authorization)
-        : message.mpp === 'payment-close-request'
-          ? () => requestClose()
-          : null
-
-    if (!work) return
-    if (runtime.queuedActions >= maxQueuedPaymentMessages) {
-      void send(
-        socket,
-        formatErrorMessage({
-          message: 'too many queued payment messages',
-          status: 429,
-        }),
-      ).catch(() => {})
-      void close(1008, 'too many queued payment messages')
-      return
-    }
-
-    runtime.queuedActions++
-    runtime.action = runtime.action
-      .then(async () => {
-        try {
-          if (runtime.closed) return
-          await work()
-        } finally {
-          runtime.queuedActions--
-        }
-      })
-      .catch(async (error) => {
-        if (!runtime.closed) {
-          await send(
-            socket,
-            formatErrorMessage({
-              message: error instanceof Error ? error.message : 'invalid payment message',
-              status: 400,
-            }),
-          )
-          await close(1008, 'invalid payment message')
-        }
-      })
-  }
-
-  const onClose = () => {
-    if (runtime.closed) return
-    runtime.closed = true
-    abortController.abort()
-    unsubscribe()
-  }
-
-  const unsubscribe = subscribe(socket, {
-    close: onClose,
-    error: onClose,
-    message: onMessage,
-  })
-}
-
-/** Type helpers for {@link serve}. */
-export declare namespace serve {
-  type Options = {
-    /** Expected per-tick amount in raw units. When set, credentials whose
-     *  challenge `request.amount` does not match are rejected. Use this to
-     *  pin the price when the route is backed by `Mppx.compose()` with
-     *  multiple offers — otherwise a client can select the cheapest offer
-     *  and still receive the same stream. */
-    amount?: string | undefined
-    /** Application stream. A manual stream can call `charge(amount)` with a
-     *  per-message raw-unit amount; omitting it uses the challenge tick cost. */
-    generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>)
-    pollIntervalMs?: number | undefined
-    /** Payment route handler. Receives synthetic `POST` requests with only
-     *  the `Authorization` header — no cookies, bodies, or upgrade headers. */
-    route: SessionRoute
-    /** Optional low-level hook invoked after each committed stream charge. */
-    onChargeCommitted?: MeteredStreamOptions['onChargeCommitted']
-    /** @deprecated Use `onChargeCommitted`. */
-    settleScheduled?: SettleChargedSessionChannel | undefined
-    socket: Socket
-    store: ChannelStore.ChannelStore | import('../../../Store.js').Store
-    url: string | URL
-  }
-}
-
-function normalizeHttpUrl(value: string | URL): string {
-  const url = new URL(value.toString())
-  if (url.protocol === 'ws:') url.protocol = 'http:'
-  if (url.protocol === 'wss:') url.protocol = 'https:'
-  return url.toString()
-}
-
-/** Inputs used to verify a WebSocket authorization frame through the HTTP route. */
-type AuthorizePaymentFrameParameters = {
-  /** Serialized `Payment` credential from the WebSocket authorization frame. */
-  authorization: string
-  /** Normalized HTTP URL used for the synthetic management request. */
-  requestUrl: string
-  /** HTTP payment route used to verify management credentials. */
-  route: SessionRoute
-}
-
-/** Verifies a WebSocket authorization frame and returns either a receipt or a payment error. */
-async function authorizePaymentFrame(
-  parameters: AuthorizePaymentFrameParameters,
-): Promise<AuthorizationResult> {
-  const result = await parameters.route(
-    new Request(parameters.requestUrl, {
-      method: 'POST',
-      headers: { [Constants.Headers.authorization]: parameters.authorization },
-    }),
-  )
-
-  if (result.status === 402) {
-    const response = result.challenge
-    return {
-      status: 'rejected',
-      message:
-        (await response.text().catch(() => '')) ||
-        response.statusText ||
-        'payment verification failed',
-      responseStatus: response.status,
-    }
-  }
-
-  const response = result.withReceipt(new Response(null, { status: 204 }))
-  const receiptHeader = response.headers.get(Constants.Headers.paymentReceipt)
-  if (!receiptHeader) throw new Error('management response missing Payment-Receipt header')
-  return { status: 'accepted', receipt: deserializeSessionReceipt(receiptHeader) }
-}

package/src/tempo/session/server/index.ts

@@ -1,12 +0,0 @@
-export { charge, session, settle, settleBatch } from './Session.js'
-/** SSE helpers and types for Tempo session streams. */
-export * as Sse from './Sse.js'
-/** Server-side automatic settlement schedule. */
-export type {
-  OnSessionSettlement,
-  ResolveSessionChannelId,
-  ResolveSessionChannelIdParameters,
-  SessionChannelIdRequest,
-  SessionSettlementContext,
-  SettlementSchedule,
-} from './Session.js'

package/src/tempo/subscription/KeyAuthorization.test.ts

@@ -1,282 +0,0 @@
-import { Rlp } from 'ox'
-import { KeyAuthorization, SignatureEnvelope } from 'ox/tempo'
-import { privateKeyToAccount } from 'viem/accounts'
-import { describe, expect, test } from 'vp/test'
-
-import * as Methods from '../Methods.js'
-import {
-  assertSubscriptionTiming,
-  getSubscriptionRpcAllowedCalls,
-  getSubscriptionScopes,
-  signSubscriptionKeyAuthorization,
-  toSubscriptionExpiryDate,
-  toSubscriptionExpirySeconds,
-  toSubscriptionPeriodSeconds,
-  transferSelector,
-  transferWithMemoSelector,
-  verifySubscriptionKeyAuthorization,
-} from './KeyAuthorization.js'
-import type { SubscriptionAccessKey } from './Types.js'
-
-const secondsPerDay = 86_400
-
-const rootAccount = privateKeyToAccount(
-  '0x0000000000000000000000000000000000000000000000000000000000000001',
-)
-const accessAccount = privateKeyToAccount(
-  '0x0000000000000000000000000000000000000000000000000000000000000002',
-)
-const otherAccessAccount = privateKeyToAccount(
-  '0x0000000000000000000000000000000000000000000000000000000000000003',
-)
-const accessKey = {
-  accessKeyAddress: accessAccount.address,
-  keyType: 'secp256k1',
-} as const satisfies SubscriptionAccessKey
-const currency = '0x20c0000000000000000000000000000000000001'
-const recipient = '0x1234567890abcdef1234567890abcdef12345678'
-const otherRecipient = '0x2222222222222222222222222222222222222222'
-const subscriptionExpires = new Date(
-  Math.ceil((Date.now() + 365 * 24 * 60 * 60 * 1_000) / 1_000) * 1_000,
-).toISOString()
-
-function parseRequest(
-  overrides: Partial<Parameters<typeof Methods.subscription.schema.request.parse>[0]> = {},
-) {
-  return Methods.subscription.schema.request.parse({
-    amount: '10',
-    chainId: 4217,
-    currency,
-    decimals: 6,
-    periodCount: '1',
-    periodUnit: 'day',
-    recipient,
-    subscriptionExpires,
-    ...overrides,
-  })
-}
-
-async function createPayload(request = parseRequest()) {
-  const keyAuthorization = await signSubscriptionKeyAuthorization({
-    accessKey,
-    account: rootAccount,
-    chainId: 4217,
-    request,
-  })
-  if (!keyAuthorization) throw new Error('expected key authorization')
-  return {
-    signature: KeyAuthorization.serialize(keyAuthorization),
-    type: 'keyAuthorization',
-  } as const
-}
-
-function serializeCompositeSignature(
-  type: 'keychain' | 'multisig',
-  inner: SignatureEnvelope.Primitive,
-) {
-  return SignatureEnvelope.serialize(
-    type === 'keychain'
-      ? {
-          inner,
-          type,
-          userAddress: rootAccount.address,
-        }
-      : {
-          account: rootAccount.address,
-          signatures: [inner],
-          type,
-        },
-  )
-}
-
-describe('tempo subscription key authorization', () => {
-  test('signs and verifies a scoped key authorization', async () => {
-    const request = parseRequest()
-    const payload = await createPayload(request)
-
-    const result = verifySubscriptionKeyAuthorization({
-      accessKey,
-      chainId: 4217,
-      payload,
-      request,
-    })
-
-    expect(result.source.address.toLowerCase()).toBe(rootAccount.address.toLowerCase())
-    expect(result.authorization.address.toLowerCase()).toBe(
-      accessKey.accessKeyAddress.toLowerCase(),
-    )
-  })
-
-  test.each(['keychain', 'multisig'] as const)(
-    'rejects %s authorization signatures',
-    async (type) => {
-      const request = parseRequest()
-
-      await expect(
-        signSubscriptionKeyAuthorization({
-          accessKey,
-          account: {
-            async sign({ hash }) {
-              const inner = SignatureEnvelope.from(await rootAccount.sign({ hash }))
-              if (inner.type === 'keychain' || inner.type === 'multisig') {
-                throw new Error('expected primitive signature')
-              }
-              return serializeCompositeSignature(type, inner)
-            },
-          },
-          chainId: 4217,
-          request,
-        }),
-      ).rejects.toThrow('keyAuthorization must use a primitive signature')
-    },
-  )
-
-  test.each(['keychain', 'multisig'] as const)(
-    'rejects serialized %s authorization signatures',
-    async (type) => {
-      const request = parseRequest()
-      const payload = await createPayload(request)
-      const authorization = KeyAuthorization.deserialize(payload.signature)
-      const [authorizationTuple] = KeyAuthorization.toTuple(authorization)
-
-      expect(() =>
-        verifySubscriptionKeyAuthorization({
-          accessKey,
-          chainId: 4217,
-          payload: {
-            ...payload,
-            signature: Rlp.fromHex([
-              authorizationTuple,
-              serializeCompositeSignature(type, authorization.signature!),
-            ]),
-          },
-          request,
-        }),
-      ).toThrow('keyAuthorization must use a primitive signature')
-    },
-  )
-
-  test('builds wallet allowed calls from the subscription request', () => {
-    const request = parseRequest()
-
-    expect(getSubscriptionScopes(request)).toMatchObject([
-      { address: currency, recipients: [recipient], selector: transferWithMemoSelector },
-    ])
-    expect(getSubscriptionRpcAllowedCalls(request)).toMatchObject([
-      {
-        target: currency,
-        selectorRules: [{ recipients: [recipient], selector: transferWithMemoSelector }],
-      },
-    ])
-  })
-
-  test('rejects key authorizations that do not match the request', async () => {
-    const request = parseRequest()
-    const payload = await createPayload(request)
-
-    const cases = [
-      {
-        request: parseRequest({ amount: '11' }),
-        reason: 'keyAuthorization amount mismatch',
-      },
-      {
-        request: parseRequest({ currency: otherRecipient }),
-        reason: 'keyAuthorization currency mismatch',
-      },
-      {
-        request: parseRequest({ periodCount: '2' }),
-        reason: 'keyAuthorization period mismatch',
-      },
-      {
-        request: parseRequest({ recipient: otherRecipient }),
-        reason: 'keyAuthorization recipient mismatch',
-      },
-    ]
-
-    for (const { reason, request } of cases) {
-      expect(() =>
-        verifySubscriptionKeyAuthorization({
-          accessKey,
-          chainId: 4217,
-          payload,
-          request,
-        }),
-      ).toThrow(reason)
-    }
-  })
-
-  test('rejects key authorizations for the wrong access key', async () => {
-    const request = parseRequest()
-    const payload = await createPayload(request)
-
-    expect(() =>
-      verifySubscriptionKeyAuthorization({
-        accessKey: {
-          accessKeyAddress: otherAccessAccount.address,
-          keyType: 'secp256k1',
-        },
-        chainId: 4217,
-        payload,
-        request,
-      }),
-    ).toThrow('keyAuthorization access key mismatch')
-  })
-
-  test('requires transferWithMemo authorization', async () => {
-    const request = parseRequest()
-    const payload = await createPayload(request)
-    const authorization = KeyAuthorization.deserialize(payload.signature)
-    const transferOnly = KeyAuthorization.serialize({
-      ...authorization,
-      scopes: authorization.scopes?.map((scope) => ({
-        ...scope,
-        selector: transferSelector,
-      })),
-    })
-
-    expect(() =>
-      verifySubscriptionKeyAuthorization({
-        accessKey,
-        chainId: 4217,
-        payload: { ...payload, signature: transferOnly },
-        request,
-      }),
-    ).toThrow('keyAuthorization must allow transferWithMemo')
-  })
-
-  test('rejects subscription periods that cannot be represented by the Tempo client', () => {
-    expect(() => toSubscriptionPeriodSeconds({ periodCount: '0', periodUnit: 'day' })).toThrow(
-      'periodCount is invalid',
-    )
-    expect(() =>
-      toSubscriptionPeriodSeconds({
-        periodCount: String(Math.floor(Number.MAX_SAFE_INTEGER / secondsPerDay) + 1),
-        periodUnit: 'day',
-      }),
-    ).toThrow('subscription period cannot be represented exactly by this Tempo client')
-  })
-
-  test('accepts dev-prefixed subscription periods for development and tests', () => {
-    expect(toSubscriptionPeriodSeconds({ periodCount: '15', periodUnit: 'dev_second' })).toBe(15)
-    expect(toSubscriptionPeriodSeconds({ periodCount: '120', periodUnit: 'dev_second' })).toBe(120)
-  })
-
-  test('rejects subscription expiries that cannot be represented by Tempo key authorizations', () => {
-    expect(() =>
-      toSubscriptionExpirySeconds(toSubscriptionExpiryDate('2026-01-01T00:00:00.500Z')),
-    ).toThrow('subscriptionExpires must be representable as whole seconds')
-  })
-
-  test('requires subscription expiry to outlive the challenge expiry', () => {
-    const request = parseRequest({
-      subscriptionExpires: '2026-01-01T00:00:00.000Z',
-    })
-
-    expect(() =>
-      assertSubscriptionTiming({
-        challengeExpires: '2026-01-01T00:00:00.000Z',
-        request,
-      }),
-    ).toThrow('subscriptionExpires must be strictly later than challenge expires')
-  })
-})