mppx 0.0.1 → 0.1.0

package/src/tempo/stream/Sse.ts

@@ -0,0 +1,375 @@
+/**
+ * SSE (Server-Sent Events) utilities for metered streaming payments.
+ *
+ * Provides event formatting/parsing, balance polling, the core
+ * `serve()` loop that meters an async iterable into a ReadableStream
+ * of SSE events, and helpers (`toResponse`, `fromRequest`) for
+ * building HTTP responses from the stream.
+ */
+import type { Hex } from 'viem'
+import * as Credential from '../../Credential.js'
+import * as ChannelStore from './ChannelStore.js'
+import { createStreamReceipt } from './Receipt.js'
+import type { NeedVoucherEvent, StreamCredentialPayload, StreamReceipt } from './Types.js'
+
+/**
+ * Format a stream receipt as a Server-Sent Event.
+ *
+ * Produces a valid SSE event string with `event: payment-receipt`
+ * and the receipt JSON as the `data` field.
+ */
+export function formatReceiptEvent(receipt: StreamReceipt): string {
+  return `event: payment-receipt\ndata: ${JSON.stringify(receipt)}\n\n`
+}
+
+/**
+ * Format a need-voucher event as a Server-Sent Event.
+ *
+ * Emitted when the channel balance is exhausted mid-stream.
+ * The client responds by sending a new voucher credential to
+ * any mppx-protected endpoint.
+ */
+export function formatNeedVoucherEvent(params: NeedVoucherEvent): string {
+  return `event: payment-need-voucher\ndata: ${JSON.stringify(params)}\n\n`
+}
+
+/**
+ * Parsed SSE event (discriminated union by `type`).
+ */
+export type SseEvent =
+  | { type: 'message'; data: string }
+  | { type: 'payment-need-voucher'; data: NeedVoucherEvent }
+  | { type: 'payment-receipt'; data: StreamReceipt }
+
+/**
+ * Parse a raw SSE event string into a typed event.
+ *
+ * Handles the three event types used by mppx streaming:
+ * - `message` (default / no event field) — application data
+ * - `payment-need-voucher` — balance exhausted, client should send voucher
+ * - `payment-receipt` — final receipt
+ */
+export function parseEvent(raw: string): SseEvent | null {
+  let eventType = 'message'
+  const dataLines: string[] = []
+
+  for (const line of raw.split('\n')) {
+    if (line.startsWith('event: ')) {
+      eventType = line.slice(7).trim()
+    } else if (line.startsWith('data: ')) {
+      dataLines.push(line.slice(6))
+    } else if (line === 'data:') {
+      dataLines.push('')
+    }
+  }
+
+  if (dataLines.length === 0) return null
+  const data = dataLines.join('\n')
+
+  switch (eventType) {
+    case 'message':
+      return { type: 'message', data }
+    case 'payment-need-voucher':
+      return { type: 'payment-need-voucher', data: JSON.parse(data) as NeedVoucherEvent }
+    case 'payment-receipt':
+      return { type: 'payment-receipt', data: JSON.parse(data) as StreamReceipt }
+    default:
+      return { type: 'message', data }
+  }
+}
+
+export type StreamController = {
+  charge(): Promise<void>
+}
+
+/**
+ * Wrap an async iterable with payment metering, producing an SSE stream.
+ *
+ * `generate` may be either:
+ * - An `AsyncIterable<string>` — each yielded value is automatically charged
+ *   (one `tickCost` per value).
+ * - A callback `(stream: StreamController) => AsyncIterable<string>` — the
+ *   generator controls when charges happen by calling `stream.charge()`.
+ *
+ * For each emitted value the stream:
+ * 1. Deducts `tickCost` from the channel balance atomically (auto or manual).
+ * 2. If balance is sufficient, emits `event: message` with the value.
+ * 3. If balance is exhausted, emits `event: payment-need-voucher`
+ *    and polls store until the client tops up the channel.
+ * 4. On generator completion, emits a final `event: payment-receipt`.
+ *
+ * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
+ */
+export function serve(options: serve.Options): ReadableStream<Uint8Array> {
+  const {
+    store,
+    channelId,
+    challengeId,
+    tickCost,
+    generate,
+    pollIntervalMs = 100,
+    signal,
+  } = options
+
+  const encoder = new TextEncoder()
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const aborted = () => signal?.aborted ?? false
+      const emit = (event: string) => controller.enqueue(encoder.encode(event))
+
+      const charge = () =>
+        chargeOrWait({
+          store,
+          channelId,
+          amount: tickCost,
+          emit,
+          pollIntervalMs,
+          signal,
+        })
+
+      const iterable: AsyncIterable<string> =
+        typeof generate === 'function' ? generate({ charge }) : generate
+
+      try {
+        for await (const value of iterable) {
+          if (aborted()) break
+
+          if (typeof generate !== 'function') await charge()
+
+          controller.enqueue(encoder.encode(`event: message\ndata: ${value}\n\n`))
+        }
+
+        if (!aborted()) {
+          const channel = await store.getChannel(channelId)
+          if (channel) {
+            const receipt = createStreamReceipt({
+              challengeId,
+              channelId,
+              acceptedCumulative: channel.highestVoucherAmount,
+              spent: channel.spent,
+              units: channel.units,
+            })
+            controller.enqueue(encoder.encode(formatReceiptEvent(receipt)))
+          }
+        }
+      } catch (e) {
+        if (!aborted()) controller.error(e)
+      } finally {
+        controller.close()
+      }
+    },
+  })
+}
+
+export declare namespace serve {
+  type Options = {
+    store: ChannelStore.ChannelStore
+    channelId: Hex
+    challengeId: string
+    tickCost: bigint
+    generate: AsyncIterable<string> | ((stream: StreamController) => AsyncIterable<string>)
+    pollIntervalMs?: number | undefined
+    signal?: AbortSignal | undefined
+  }
+}
+
+/**
+ * Wrap a `ReadableStream<Uint8Array>` (from {@link serve}) in an HTTP
+ * `Response` with the correct SSE headers.
+ */
+export function toResponse(body: ReadableStream<Uint8Array>): Response {
+  return new Response(body, {
+    headers: {
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'Content-Type': 'text/event-stream; charset=utf-8',
+    },
+  })
+}
+
+/**
+ * Extract `channelId`, `challengeId`, and `tickCost` from a `Request`'s
+ * `Authorization: Payment …` header.
+ *
+ * This is a convenience for callers that receive a raw `Request` and need
+ * the parameters required by {@link serve}.
+ */
+export function fromRequest(request: Request): fromRequest.Context {
+  const header = request.headers.get('Authorization')
+  if (!header) throw new Error('Missing Authorization header.')
+
+  const payment = Credential.extractPaymentScheme(header)
+  if (!payment) throw new Error('Missing Payment credential in Authorization header.')
+
+  const credential = Credential.deserialize(payment)
+  const payload = credential.payload as StreamCredentialPayload
+  return {
+    challengeId: credential.challenge.id,
+    channelId: payload.channelId,
+    tickCost: BigInt(credential.challenge.request.amount as string),
+  }
+}
+
+export declare namespace fromRequest {
+  type Context = {
+    challengeId: string
+    channelId: Hex
+    tickCost: bigint
+  }
+}
+
+/**
+ * Atomically deduct `amount` from a channel, retrying when balance is
+ * insufficient. Uses `store.waitForUpdate()` when available for
+ * event-driven wakeups, falling back to polling otherwise. Emits
+ * `payment-need-voucher` events via `emit` while waiting.
+ */
+async function chargeOrWait(options: {
+  store: ChannelStore.ChannelStore
+  channelId: Hex
+  amount: bigint
+  emit: (event: string) => void
+  pollIntervalMs: number
+  signal?: AbortSignal | undefined
+}): Promise<void> {
+  const { store, channelId, amount, emit, pollIntervalMs, signal } = options
+
+  let result = await ChannelStore.deductFromChannel(store, channelId, amount)
+
+  if (!result.ok) {
+    // Emit a single need-voucher event, then poll/wait until the client
+    // sends an updated voucher. The requiredCumulative is constant here:
+    // `spent` only changes on successful deduction (which exits the loop),
+    // so re-emitting on every poll cycle would just cause redundant
+    // voucher POSTs from the client.
+    emit(
+      formatNeedVoucherEvent({
+        channelId,
+        requiredCumulative: (result.channel.spent + amount).toString(),
+        acceptedCumulative: result.channel.highestVoucherAmount.toString(),
+        deposit: result.channel.deposit.toString(),
+      }),
+    )
+
+    while (!result.ok) {
+      await waitForUpdate(store, channelId, pollIntervalMs, signal)
+      result = await ChannelStore.deductFromChannel(store, channelId, amount)
+    }
+  }
+}
+
+async function waitForUpdate(
+  store: ChannelStore.ChannelStore,
+  channelId: Hex,
+  pollIntervalMs: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (signal?.aborted) throw new Error('Aborted while waiting for voucher')
+  if (store.waitForUpdate) {
+    await Promise.race([store.waitForUpdate(channelId), ...(signal ? [abortPromise(signal)] : [])])
+  } else {
+    await sleep(pollIntervalMs)
+  }
+  if (signal?.aborted) throw new Error('Aborted while waiting for voucher')
+}
+
+function abortPromise(signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve()
+    signal.addEventListener('abort', () => resolve(), { once: true })
+  })
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Check whether a `Response` carries an SSE event stream.
+ *
+ * Returns `true` when the `Content-Type` header starts with
+ * `text/event-stream` (case-insensitive, ignoring charset params).
+ */
+export function isEventStream(response: Response): boolean {
+  const ct = response.headers.get('content-type')
+  return ct?.toLowerCase().startsWith('text/event-stream') ?? false
+}
+
+/**
+ * Parse an SSE `Response` body into an async iterable of `data:` payloads.
+ *
+ * Yields the raw `data:` field content for each SSE event in the stream.
+ * Events whose data matches the `skip` predicate are silently dropped
+ * (e.g. `[DONE]` sentinels used by OpenAI-compatible APIs).
+ *
+ * Each yielded value typically becomes one charge tick when fed to
+ * {@link serve} via the SSE transport's auto-charge mode.
+ *
+ * @example
+ * ```ts
+ * const upstream = await fetch('https://api.example.com/stream')
+ * for await (const data of Sse.iterateData(upstream)) {
+ *   console.log(data)
+ * }
+ * ```
+ */
+export async function* iterateData(
+  response: Response,
+  options?: iterateData.Options,
+): AsyncGenerator<string> {
+  const skip = options?.skip
+  const body = response.body
+  if (!body) return
+
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+
+      buffer += decoder.decode(value, { stream: true })
+
+      // Split on double-newline SSE event boundaries.
+      const events = buffer.split('\n\n')
+      // Last element may be incomplete — keep in buffer.
+      buffer = events.pop() ?? ''
+
+      for (const event of events) {
+        if (!event.trim()) continue
+        const data = extractData(event)
+        if (data === null) continue
+        if (skip?.(data)) continue
+        yield data
+      }
+    }
+
+    // Flush remaining buffer.
+    if (buffer.trim()) {
+      const data = extractData(buffer)
+      if (data !== null && !skip?.(data)) yield data
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+export declare namespace iterateData {
+  type Options = {
+    /** Predicate to skip specific data payloads (e.g. `d => d === '[DONE]'`). */
+    skip?: ((data: string) => boolean) | undefined
+  }
+}
+
+/** Extract the `data:` field value from a single SSE event block. */
+function extractData(event: string): string | null {
+  const dataLines: string[] = []
+  for (const line of event.split('\n')) {
+    if (line.startsWith('data: ')) dataLines.push(line.slice(6))
+    else if (line === 'data:') dataLines.push('')
+  }
+  return dataLines.length > 0 ? dataLines.join('\n') : null
+}

package/src/tempo/stream/Types.ts

@@ -0,0 +1,86 @@
+import type { Address, Hex } from 'viem'
+
+/**
+ * Voucher for cumulative payment.
+ * Cumulative monotonicity prevents replay attacks.
+ */
+export interface Voucher {
+  channelId: Hex
+  cumulativeAmount: bigint
+}
+
+/**
+ * Signed voucher with EIP-712 signature.
+ */
+export interface SignedVoucher extends Voucher {
+  signature: Hex
+}
+
+/**
+ * Stream credential payload (discriminated union).
+ */
+export type StreamCredentialPayload =
+  | {
+      action: 'open'
+      type: 'transaction'
+      channelId: Hex
+      transaction: Hex
+      signature: Hex
+      authorizedSigner?: Address | undefined
+      cumulativeAmount: string
+    }
+  | {
+      action: 'topUp'
+      type: 'transaction'
+      channelId: Hex
+      transaction: Hex
+      additionalDeposit: string
+    }
+  | {
+      action: 'voucher'
+      channelId: Hex
+      cumulativeAmount: string
+      signature: Hex
+    }
+  | {
+      action: 'close'
+      channelId: Hex
+      cumulativeAmount: string
+      signature: Hex
+    }
+
+/**
+ * SSE event emitted when session balance is exhausted mid-stream.
+ * The client responds by sending a new voucher credential.
+ *
+ * Per spec §11.6, the event data contains:
+ * - `channelId` — channel identifier
+ * - `requiredCumulative` — minimum cumulative amount the next voucher must authorize
+ * - `acceptedCumulative` — current highest accepted voucher amount
+ * - `deposit` — current on-chain deposit ceiling; when `requiredCumulative > deposit`
+ *   the client must top up the channel before sending a new voucher
+ */
+export interface NeedVoucherEvent {
+  channelId: Hex
+  requiredCumulative: string
+  acceptedCumulative: string
+  deposit: string
+}
+
+/**
+ * Stream receipt returned in Payment-Receipt header.
+ */
+export interface StreamReceipt {
+  method: 'tempo'
+  intent: 'session'
+  status: 'success'
+  timestamp: string
+  /** Payment reference (channelId). Satisfies Receipt.Receipt contract. */
+  reference: string
+  challengeId: string
+  channelId: Hex
+  acceptedCumulative: string
+  spent: string
+  units?: number | undefined
+  txHash?: Hex | undefined
+}

package/src/tempo/stream/Voucher.test.ts

@@ -0,0 +1,134 @@
+import { createClient, http } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { describe, expect, test } from 'vitest'
+import { parseVoucherFromPayload, signVoucher, verifyVoucher } from './Voucher.js'
+
+const account = privateKeyToAccount(
+  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+)
+const escrowContract = '0x1234567890abcdef1234567890abcdef12345678' as const
+const chainId = 42431
+
+const client = createClient({
+  account,
+  transport: http('http://127.0.0.1'), // only used for local signTypedData
+})
+
+const channelId = '0x0000000000000000000000000000000000000000000000000000000000000001' as const
+const cumulativeAmount = 1000000n
+
+describe('Voucher', () => {
+  test('signVoucher and verifyVoucher round-trip', async () => {
+    const signature = await signVoucher(
+      client,
+      account,
+      { channelId, cumulativeAmount },
+      escrowContract,
+      chainId,
+    )
+    expect(signature).toMatch(/^0x/)
+    expect(signature.length).toBe(132)
+
+    const isValid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId, cumulativeAmount, signature },
+      account.address,
+    )
+    expect(isValid).toBe(true)
+  })
+
+  test('verifyVoucher rejects wrong signer', async () => {
+    const signature = await signVoucher(
+      client,
+      account,
+      { channelId, cumulativeAmount },
+      escrowContract,
+      chainId,
+    )
+
+    const wrongAddress = '0x0000000000000000000000000000000000000001' as const
+    const isValid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId, cumulativeAmount, signature },
+      wrongAddress,
+    )
+    expect(isValid).toBe(false)
+  })
+
+  test('verifyVoucher rejects tampered amount', async () => {
+    const signature = await signVoucher(
+      client,
+      account,
+      { channelId, cumulativeAmount },
+      escrowContract,
+      chainId,
+    )
+
+    const isValid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId, cumulativeAmount: 9999999n, signature },
+      account.address,
+    )
+    expect(isValid).toBe(false)
+  })
+
+  test('verifyVoucher rejects tampered channelId', async () => {
+    const signature = await signVoucher(
+      client,
+      account,
+      { channelId, cumulativeAmount },
+      escrowContract,
+      chainId,
+    )
+
+    const wrongChannelId =
+      '0x0000000000000000000000000000000000000000000000000000000000000099' as const
+    const isValid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId: wrongChannelId, cumulativeAmount, signature },
+      account.address,
+    )
+    expect(isValid).toBe(false)
+  })
+
+  test('verifyVoucher rejects wrong chain ID', async () => {
+    const signature = await signVoucher(
+      client,
+      account,
+      { channelId, cumulativeAmount },
+      escrowContract,
+      chainId,
+    )
+
+    const isValid = await verifyVoucher(
+      escrowContract,
+      99999,
+      { channelId, cumulativeAmount, signature },
+      account.address,
+    )
+    expect(isValid).toBe(false)
+  })
+
+  test('verifyVoucher returns false for invalid signature', async () => {
+    const isValid = await verifyVoucher(
+      escrowContract,
+      chainId,
+      { channelId, cumulativeAmount, signature: '0xdeadbeef' },
+      account.address,
+    )
+    expect(isValid).toBe(false)
+  })
+
+  test('parseVoucherFromPayload', () => {
+    const sig =
+      '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab' as const
+    const voucher = parseVoucherFromPayload(channelId, '5000000', sig)
+    expect(voucher.channelId).toBe(channelId)
+    expect(voucher.cumulativeAmount).toBe(5000000n)
+    expect(voucher.signature).toBe(sig)
+  })
+})

package/src/tempo/stream/Voucher.ts

@@ -0,0 +1,123 @@
+import { type Address, Signature } from 'ox'
+import { SignatureEnvelope } from 'ox/tempo'
+import type { Account, Client, Hex } from 'viem'
+import { isAddressEqual, recoverTypedDataAddress } from 'viem'
+import { signTypedData } from 'viem/actions'
+import type { SignedVoucher, Voucher } from './Types.js'
+
+/** Must match the on-chain TempoStreamChannel DOMAIN_SEPARATOR name. */
+const DOMAIN_NAME = 'Tempo Stream Channel'
+/** Must match the on-chain TempoStreamChannel DOMAIN_SEPARATOR version. */
+const DOMAIN_VERSION = '1'
+
+/**
+ * EIP-712 domain for voucher signing.
+ */
+function getVoucherDomain(escrowContract: Address.Address, chainId: number) {
+  return {
+    name: DOMAIN_NAME,
+    version: DOMAIN_VERSION,
+    chainId,
+    verifyingContract: escrowContract,
+  } as const
+}
+
+/**
+ * EIP-712 types for voucher signing.
+ * Matches @tempo/stream-channels/voucher and on-chain VOUCHER_TYPEHASH.
+ */
+const voucherTypes = {
+  Voucher: [
+    { name: 'channelId', type: 'bytes32' },
+    { name: 'cumulativeAmount', type: 'uint128' },
+  ],
+} as const
+
+/**
+ * Sign a voucher with an account.
+ */
+export async function signVoucher(
+  client: Client,
+  account: Account,
+  message: Voucher,
+  escrowContract: Address.Address,
+  chainId: number,
+  authorizedSigner?: Address.Address | undefined,
+): Promise<Hex> {
+  const signature = await signTypedData(client, {
+    account,
+    domain: getVoucherDomain(escrowContract, chainId),
+    types: voucherTypes,
+    primaryType: 'Voucher',
+    message: {
+      channelId: message.channelId,
+      cumulativeAmount: message.cumulativeAmount,
+    },
+  })
+
+  // When a separate authorizedSigner is used (e.g. access key), unwrap the
+  // keychain envelope — the escrow contract verifies raw ECDSA signatures
+  // against authorizedSigner, not keychain-wrapped ones.
+  // TODO: when TIP-1020 is implemented, we can remove this.
+  if (authorizedSigner) {
+    try {
+      const envelope = SignatureEnvelope.from(signature as SignatureEnvelope.Serialized)
+      if (envelope.type === 'keychain' && envelope.inner.type === 'secp256k1')
+        return Signature.toHex(envelope.inner.signature)
+    } catch {}
+  }
+
+  return signature
+}
+
+/**
+ * Verify a voucher signature matches the expected signer.
+ *
+ * Supports both direct signatures (secp256k1/p256/webAuthn) and
+ * Tempo access key (keychain) signatures. For keychain signatures,
+ * the envelope's `userAddress` is compared to `expectedSigner`.
+ */
+export async function verifyVoucher(
+  escrowContract: Address.Address,
+  chainId: number,
+  voucher: SignedVoucher,
+  expectedSigner: Address.Address,
+): Promise<boolean> {
+  try {
+    const domain = getVoucherDomain(escrowContract, chainId)
+    const message = {
+      channelId: voucher.channelId,
+      cumulativeAmount: voucher.cumulativeAmount,
+    }
+
+    const envelope = SignatureEnvelope.from(voucher.signature as SignatureEnvelope.Serialized)
+
+    if (envelope.type === 'keychain') return isAddressEqual(envelope.userAddress, expectedSigner)
+
+    const signer = await recoverTypedDataAddress({
+      domain,
+      types: voucherTypes,
+      primaryType: 'Voucher',
+      message,
+      signature: voucher.signature,
+    })
+    return isAddressEqual(signer, expectedSigner)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Parse a voucher from credential payload.
+ */
+export function parseVoucherFromPayload(
+  channelId: Hex,
+  cumulativeAmount: string,
+  signature: Hex,
+): SignedVoucher {
+  return {
+    channelId,
+    cumulativeAmount: BigInt(cumulativeAmount),
+    signature,
+  }
+}