tapimo 0.0.2 → 0.2.0

package/src/handlers/internal/requestListener.ts

@@ -0,0 +1,273 @@
+// @ts-nocheck
+// Credit: https://github.com/mjackson/remix-the-web/blob/main/packages/node-fetch-server/src/lib/request-listener.ts
+
+import type * as http from 'node:http'
+import type * as http2 from 'node:http2'
+
+export interface RequestListenerOptions {
+  /**
+   * Overrides the host portion of the incoming request URL. By default the request URL host is
+   * derived from the HTTP `Host` header.
+   *
+   * For example, if you have a `$HOST` environment variable that contains the hostname of your
+   * server, you can use it to set the host of all incoming request URLs like so:
+   *
+   * ```ts
+   * createRequestListener(handler, { host: process.env.HOST })
+   * ```
+   */
+  host?: string
+  /**
+   * An error handler that determines the response when the request handler throws an error. By
+   * default a 500 Internal Server Error response will be sent.
+   */
+  onError?: ErrorHandler
+  /**
+   * Overrides the protocol of the incoming request URL. By default the request URL protocol is
+   * derived from the connection protocol. So e.g. when serving over HTTPS (using
+   * `https.createServer()`), the request URL will begin with `https:`.
+   */
+  protocol?: string
+}
+
+/**
+ * Wraps a fetch handler in a Node.js request listener that can be used with:
+ *
+ * - [`http.createServer()`](https://nodejs.org/api/http.html#httpcreateserveroptions-requestlistener)
+ * - [`https.createServer()`](https://nodejs.org/api/https.html#httpscreateserveroptions-requestlistener)
+ * - [`http2.createServer()`](https://nodejs.org/api/http2.html#http2createserveroptions-onrequesthandler)
+ * - [`http2.createSecureServer()`](https://nodejs.org/api/http2.html#http2createsecureserveroptions-onrequesthandler)
+ *
+ * Example:
+ *
+ * ```ts
+ * import * as http from 'node:http';
+ * import { createRequestListener } from '@mjackson/node-fetch-server';
+ *
+ * async function handler(request) {
+ *   return new Response('Hello, world!');
+ * }
+ *
+ * let server = http.createServer(
+ *   createRequestListener(handler)
+ * );
+ *
+ * server.listen(3000);
+ * ```
+ *
+ * @param handler The fetch handler to use for processing incoming requests.
+ * @param options Request listener options.
+ * @returns A Node.js request listener function.
+ */
+export function fromFetchHandler(
+  handler: FetchHandler,
+  options?: RequestListenerOptions,
+): http.RequestListener {
+  const onError = options?.onError ?? defaultErrorHandler
+
+  return async (req, res) => {
+    const request = createRequest(req, res, options)
+    const client = {
+      address: req.socket.remoteAddress!,
+      family: req.socket.remoteFamily! as ClientAddress['family'],
+      port: req.socket.remotePort!,
+    }
+
+    let response: Response
+    try {
+      response = await handler(request, client)
+    } catch (error) {
+      try {
+        response = (await onError(error)) ?? internalServerError()
+      } catch (error) {
+        console.error(`There was an error in the error handler: ${error}`)
+        response = internalServerError()
+      }
+    }
+
+    await sendResponse(res, response)
+  }
+}
+
+function defaultErrorHandler(error: unknown): Response {
+  console.error(error)
+  return internalServerError()
+}
+
+function internalServerError(): Response {
+  return new Response(
+    // "Internal Server Error"
+    new Uint8Array([
+      73, 110, 116, 101, 114, 110, 97, 108, 32, 83, 101, 114, 118, 101, 114, 32, 69, 114, 114, 111,
+      114,
+    ]),
+    {
+      headers: {
+        'Content-Type': 'text/plain',
+      },
+      status: 500,
+    },
+  )
+}
+
+export type RequestOptions = Omit<RequestListenerOptions, 'onError'>
+
+/**
+ * Creates a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object from
+ *
+ * - a [`http.IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage)/[`http.ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) pair
+ * - a [`http2.Http2ServerRequest`](https://nodejs.org/api/http2.html#class-http2http2serverrequest)/[`http2.Http2ServerResponse`](https://nodejs.org/api/http2.html#class-http2http2serverresponse) pair
+ *
+ * @param req The incoming request object.
+ * @param res The server response object.
+ * @param options
+ * @returns A request object.
+ */
+export function createRequest(
+  req: http.IncomingMessage | http2.Http2ServerRequest,
+  res: http.ServerResponse | http2.Http2ServerResponse,
+  options?: RequestOptions,
+): Request {
+  const controller = new AbortController()
+  res.on('close', () => {
+    controller.abort()
+  })
+
+  const method = req.method ?? 'GET'
+  const headers = createHeaders(req)
+
+  const protocol =
+    options?.protocol ?? ('encrypted' in req.socket && req.socket.encrypted ? 'https:' : 'http:')
+  const host = options?.host ?? headers.get('Host') ?? 'localhost'
+  const url = new URL(req.url!, `${protocol}//${host}`)
+
+  const init: RequestInit = { headers, method, signal: controller.signal }
+
+  if (method !== 'GET' && method !== 'HEAD') {
+    init.body = new ReadableStream({
+      start(controller) {
+        req.on('data', (chunk) => {
+          controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength))
+        })
+        req.on('end', () => {
+          controller.close()
+        })
+      },
+    })
+
+    // init.duplex = 'half' must be set when body is a ReadableStream, and Node follows the spec.
+    // However, this property is not defined in the TypeScript types for RequestInit, so we have
+    // to cast it here in order to set it without a type error.
+    // See https://fetch.spec.whatwg.org/#dom-requestinit-duplex
+    ;(init as { duplex: 'half' }).duplex = 'half'
+  }
+
+  return new Request(url, init)
+}
+
+/**
+ * Creates a [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object from the headers in a Node.js
+ * [`http.IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage)/[`http2.Http2ServerRequest`](https://nodejs.org/api/http2.html#class-http2http2serverrequest).
+ *
+ * @param req The incoming request object.
+ * @returns A headers object.
+ */
+export function createHeaders(req: http.IncomingMessage | http2.Http2ServerRequest): Headers {
+  const headers = new Headers()
+
+  const rawHeaders = req.rawHeaders
+  for (let i = 0; i < rawHeaders.length; i += 2) {
+    if (rawHeaders[i]?.startsWith(':')) continue
+    headers.append(rawHeaders[i]!, rawHeaders[i + 1]!)
+  }
+
+  return headers
+}
+
+/**
+ * Sends a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) to the client using a Node.js
+ * [`http.ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse)/[`http2.Http2ServerResponse`](https://nodejs.org/api/http2.html#class-http2http2serverresponse)
+ * object.
+ *
+ * @param res The server response object.
+ * @param response The response to send.
+ */
+export async function sendResponse(
+  res: http.ServerResponse | http2.Http2ServerResponse,
+  response: Response,
+): Promise<void> {
+  // Iterate over response.headers so we are sure to send multiple Set-Cookie headers correctly.
+  // These would incorrectly be merged into a single header if we tried to use
+  // `Object.fromEntries(response.headers.entries())`.
+  const headers: Record<string, string | string[]> = {}
+  for (const [key, value] of response.headers as any) {
+    if (key in headers) {
+      if (Array.isArray(headers[key])) {
+        headers[key].push(value)
+      } else {
+        headers[key] = [headers[key] as string, value]
+      }
+    } else {
+      headers[key] = value
+    }
+  }
+
+  ;(res as any).writeHead(response.status, headers)
+
+  if (response.body != null && res.req.method !== 'HEAD') {
+    for await (const chunk of readStream(response.body)) {
+      // @ts-expect-error - Node typings for http2 require a 2nd parameter to write but it's optional
+      res.write(chunk)
+    }
+  }
+
+  res.end()
+}
+
+export async function* readStream(stream: ReadableStream<Uint8Array>): AsyncIterable<Uint8Array> {
+  const reader = stream.getReader()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    yield value
+  }
+}
+
+export interface ClientAddress {
+  /**
+   * The IP address of the client that sent the request.
+   *
+   * [Node.js Reference](https://nodejs.org/api/net.html#socketremoteaddress)
+   */
+  address: string
+  /**
+   * The family of the client IP address.
+   *
+   * [Node.js Reference](https://nodejs.org/api/net.html#socketremotefamily)
+   */
+  family: 'IPv4' | 'IPv6'
+  /**
+   * The remote port of the client that sent the request.
+   *
+   * [Node.js Reference](https://nodejs.org/api/net.html#socketremoteport)
+   */
+  port: number
+}
+
+/**
+ * A function that handles an error that occurred during request handling. May return a response to
+ * send to the client, or `undefined` to allow the server to send a default error response.
+ *
+ * [MDN `Response` Reference](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+ */
+export type ErrorHandler = (error: unknown) => undefined | Response | Promise<undefined | Response>
+
+/**
+ * A function that handles an incoming request and returns a response.
+ *
+ * [MDN `Request` Reference](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+ *
+ * [MDN `Response` Reference](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+ */
+export type FetchHandler = (request: Request, client: ClientAddress) => Response | Promise<Response>

package/src/handlers/internal/sponsorship.ts

@@ -0,0 +1,245 @@
+import { Hash, type Hex, RpcResponse, Signature } from 'ox'
+import { TxEnvelopeTempo } from 'ox/tempo'
+import type { Address, Client } from 'viem'
+import type { LocalAccount } from 'viem/accounts'
+import { Transaction } from 'viem/tempo'
+
+import * as Utils from './utils.js'
+
+/**
+ * Sponsorship approval callback. The candidate always carries its `chainId`:
+ * raw submissions deserialize it, and fills validate only prepared/filled
+ * transactions.
+ */
+export type Validate = (
+  request: Transaction.TransactionRequest & { chainId?: number | Hex.Hex | undefined },
+) => boolean | Promise<boolean>
+
+/** Returns sponsor metadata for `eth_fillTransaction` responses. */
+export function getSponsor(options: getSponsor.Options): getSponsor.ReturnType {
+  const { account, name, url } = options
+  return {
+    address: account.address,
+    ...(name ? { name } : {}),
+    ...(url ? { url } : {}),
+  }
+}
+
+export declare namespace getSponsor {
+  type Options = {
+    /** Account used for sponsorship. */
+    account: LocalAccount
+    /** Optional display name. */
+    name?: string | undefined
+    /** Optional display URL. */
+    url?: string | undefined
+  }
+
+  type ReturnType = {
+    /** Sponsor address. */
+    address: Address
+    /** Sponsor display name. */
+    name?: string | undefined
+    /** Sponsor display URL. */
+    url?: string | undefined
+  }
+}
+
+/** Returns whether the fee payer approves a filled transaction. */
+export async function shouldSponsor(options: shouldSponsor.Options) {
+  const { sender, transaction, validate } = options
+  if (!validate) return true
+  return await validate({
+    ...transaction,
+    from: sender,
+  } as Transaction.TransactionRequest)
+}
+
+export declare namespace shouldSponsor {
+  type Options = {
+    /** Sender address from the original request. */
+    sender?: Address | undefined
+    /** Filled transaction to validate. */
+    transaction: Record<string, unknown>
+    /** Optional sponsorship approval callback. */
+    validate?: Validate | undefined
+  }
+}
+
+/** Returns whether a raw Tempo transaction is explicitly requesting sponsorship. */
+export function requestsRawSponsorship(serialized: `0x${string}`) {
+  if (!Utils.isSerializedTempoTransaction(serialized)) return false
+  const transaction = Transaction.deserialize(serialized)
+  return 'feePayerSignature' in transaction && transaction.feePayerSignature === null
+}
+
+/** Returns `true` when a fill request already has the fields needed for sponsorship signing. */
+export function isPreparedTransaction(value: Record<string, unknown>) {
+  return (
+    typeof value['from'] === 'string' &&
+    typeof Utils.resolveChainId(value['chainId']) === 'number' &&
+    typeof value['gas'] !== 'undefined' &&
+    typeof value['nonce'] !== 'undefined' &&
+    (typeof value['maxFeePerGas'] !== 'undefined' || typeof value['gasPrice'] !== 'undefined')
+  )
+}
+
+/** Signs a filled transaction as the fee payer. */
+export async function sign(options: sign.Options) {
+  const { account, transaction, sender } = options
+  const from = (transaction['from'] as Address | undefined) ?? sender
+  const { signature: _, ...withoutSenderSig } = transaction
+  const prepared = { ...withoutSenderSig, from }
+
+  if (!prepared.from)
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Transaction sender must be provided before fee payer signing.',
+    })
+  if (!account.sign) throw new Error('Fee payer account cannot sign transactions.')
+
+  const chainId = Utils.resolveChainId(transaction['chainId'])
+  if (chainId === undefined)
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Transaction chainId must be provided before fee payer signing.',
+    })
+
+  const envelope = TxEnvelopeTempo.from(prepared as never)
+  const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(envelope, { sender: prepared.from })
+  const feePayerSignature = Signature.from(await account.sign({ hash: signPayload }))
+
+  // Awaited before the signature leaves the relay: a fill-signed envelope can
+  // broadcast anywhere (even directly to a node), so the commitment records as
+  // an intent — no transaction hash until the sender signs.
+  const feeToken = transaction['feeToken'] as Address | null | undefined
+  await options.onSponsored?.({
+    chainId,
+    ...(feeToken ? { feeToken } : {}),
+    method: 'eth_fillTransaction',
+    sender: prepared.from,
+    signPayload,
+    transaction: TxEnvelopeTempo.serialize(envelope, { feePayerSignature }),
+  })
+
+  return { ...prepared, feePayerSignature }
+}
+
+export declare namespace sign {
+  type Options = {
+    /** Account used as the fee payer. */
+    account: LocalAccount
+    /** Called once the fee payer has signed the fill. Awaited: a throw aborts the fill. */
+    onSponsored?: ((event: SponsoredEvent) => Promise<void> | void) | undefined
+    /** Filled transaction to sign. */
+    transaction: Record<string, unknown>
+    /** Sender address from the original request. */
+    sender?: Address | undefined
+  }
+}
+
+/** Handles `eth_signRawTransaction` and broadcast methods for sponsored Tempo transactions. */
+export async function handleRawTransaction(options: handleRawTransaction.Options) {
+  const { account, feeToken: sponsorFeeToken, getClient, method, request, validate } = options
+  const serialized = request.params?.[0] as `0x76${string}` | undefined
+
+  if (!Utils.isSerializedTempoTransaction(serialized))
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Only Tempo (0x76/0x78) transactions are supported.',
+    })
+
+  const transaction = Transaction.deserialize(serialized)
+  // Prefer sender recovered from raw envelope; multisig finalize path supplies fallback sender.
+  const sender = transaction.from ?? options.sender
+
+  // Sponsorship only applies after sender has signed original transaction.
+  if (!transaction.signature || !sender)
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Transaction must be signed by the sender before fee payer signing.',
+    })
+  if (!account.sign) throw new Error('Fee payer account cannot sign transactions.')
+
+  const client = getClient(transaction.chainId)
+  const feeToken_chain = (client.chain as { feeToken?: Address | undefined } | undefined)?.feeToken
+  const feeToken =
+    (transaction.feeToken as Address | null | undefined) ??
+    sponsorFeeToken ??
+    (await options.getFeeToken?.(transaction.chainId)) ??
+    feeToken_chain
+  const transaction_sponsored = feeToken ? { ...transaction, feeToken } : transaction
+
+  if (validate && !(await validate(transaction_sponsored as Transaction.TransactionRequest)))
+    throw new RpcResponse.InvalidParamsError({
+      message: 'Sponsorship rejected.',
+    })
+
+  const envelope = TxEnvelopeTempo.from(transaction_sponsored as never)
+  const signPayload = TxEnvelopeTempo.getFeePayerSignPayload(envelope, { sender })
+  const feePayerSignature = Signature.from(await account.sign({ hash: signPayload }))
+  const serializedTransaction = TxEnvelopeTempo.serialize(envelope, {
+    feePayerSignature,
+    signature: transaction.signature,
+  })
+
+  // Awaited before any broadcast so a recording failure refuses sponsorship —
+  // no sponsored transaction ever reaches the chain unrecorded.
+  await options.onSponsored?.({
+    chainId: transaction.chainId,
+    ...(feeToken ? { feeToken } : {}),
+    method,
+    sender,
+    signPayload,
+    transaction: serializedTransaction,
+    transactionHash: Hash.keccak256(serializedTransaction),
+  })
+
+  // Raw-sign requests stop after fee-payer signature is added; send methods broadcast it.
+  if (method === 'eth_signRawTransaction') return serializedTransaction
+  return await client.request({
+    method: method as never,
+    params: [serializedTransaction],
+  })
+}
+
+export declare namespace handleRawTransaction {
+  type Options = {
+    /** Account used as the fee payer. */
+    account: LocalAccount
+    /** Optional token the fee payer prefers for sponsored raw transactions. */
+    feeToken?: Address | undefined
+    /** Optional fee-token resolver used when the raw envelope omits `feeToken`. */
+    getFeeToken?: ((chainId: number) => Promise<Address | undefined>) | undefined
+    /** Client resolver keyed by transaction `chainId`. */
+    getClient: (chainId?: number) => Client
+    /** Raw transaction method to handle. */
+    method: 'eth_signRawTransaction' | 'eth_sendRawTransaction' | 'eth_sendRawTransactionSync'
+    /** Called once the fee payer has signed, before any broadcast. Awaited: a throw aborts the request. */
+    onSponsored?: ((event: SponsoredEvent) => Promise<void> | void) | undefined
+    /** Incoming JSON-RPC request. */
+    request: { params?: readonly unknown[] | undefined }
+    /** Sender address to use if it cannot be recovered from the raw envelope. */
+    sender?: Address | undefined
+    /** Optional sponsorship approval callback. */
+    validate?: Validate | undefined
+  }
+}
+
+/** Facts of one sponsorship commitment, emitted at fee-payer signing time. */
+export type SponsoredEvent = {
+  /** Chain the sponsored transaction targets. */
+  chainId: number
+  /** Fee token the sponsorship resolved, when known. */
+  feeToken?: Address | undefined
+  /** Method that triggered sponsorship: a fill (intent) or a raw submission. */
+  method:
+    | 'eth_fillTransaction'
+    | 'eth_signRawTransaction'
+    | 'eth_sendRawTransaction'
+    | 'eth_sendRawTransactionSync'
+  /** Transaction sender. */
+  sender: Address
+  /** Fee-payer sign payload — a stable identity for the sponsored envelope. */
+  signPayload: Hex.Hex
+  /** Serialized sponsored transaction (sender-unsigned for fill intents). */
+  transaction: Hex.Hex
+  /** Transaction hash (keccak256 of the signed envelope); absent for fill intents, whose senders have not signed yet. */
+  transactionHash?: Hex.Hex | undefined
+}