tapimo 0.0.0 → 0.0.2

package/src/apps/rpc.test.ts

@@ -0,0 +1,302 @@
+import type * as Viem from '../internal/Viem.js'
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+
+const runtime = Runtime.get()
+
+describe('POST /rpc', () => {
+  test('routes by principal: a resolver sees the request principal and routes accordingly', async () => {
+    const fetch = mockRpc()
+    // A resolver that routes API-key principals to the private upstream and
+    // everything else (here, the keyless `auth: false` caller) to the public one.
+    const rpc = ({ principal }: Viem.resolve.Context) =>
+      principal?.type === 'api_key'
+        ? { basicAuth: 'rpc-secret', url: 'https://internal.rpc.test/json-rpc' }
+        : { url: 'https://public.rpc.test/json-rpc' }
+
+    try {
+      // Auth disabled ⇒ no API-key principal ⇒ public RPC, no basic auth.
+      const publicApp = TestApp.create({ auth: false, rpc })
+      await publicApp.fetch(
+        new Request('http://tempo-api.test/rpc', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          method: 'POST',
+        }),
+      )
+
+      // Valid API key ⇒ api_key principal ⇒ private profile: internal RPC + basic auth.
+      const authedApp = TestApp.create({ rpc })
+      await authedApp.fetch(
+        new Request('http://tempo-api.test/rpc', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          headers: { 'tempo-api-key': TestApp.key.token },
+          method: 'POST',
+        }),
+      )
+
+      expect(fetch.calls[0]?.url).toMatchInlineSnapshot(`"https://public.rpc.test/json-rpc"`)
+      expect(fetch.calls[0]?.headers['authorization']).toMatchInlineSnapshot(`null`)
+      expect(fetch.calls[1]?.url).toMatchInlineSnapshot(`"https://internal.rpc.test/json-rpc"`)
+      expect(fetch.calls[1]?.headers['authorization']).toMatchInlineSnapshot(
+        `"Basic cnBjLXNlY3JldA=="`,
+      )
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('proxies JSON-RPC requests to the configured upstream RPC', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create({
+        auth: false,
+        rpc: {
+          basicAuth: 'rpc-secret',
+          url: (chainId) => `https://${chainId}.rpc.test/json-rpc`,
+        },
+      })
+
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId', params: [] }),
+          headers: {
+            authorization: 'Bearer caller-secret',
+            'content-type': 'application/json',
+            cookie: 'session=secret',
+            'tempo-api-key': 'caller-key',
+            'x-client-trace': 'trace_test',
+          },
+          method: 'POST',
+        }),
+      )
+      const body = await response.json()
+      const call = fetch.calls[0]!
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(response.headers.get('x-upstream')).toMatchInlineSnapshot(`"rpc"`)
+      expect(body).toMatchInlineSnapshot(`
+        {
+          "id": 1,
+          "jsonrpc": "2.0",
+          "result": "0xa5bf",
+        }
+      `)
+      expect(call.method).toMatchInlineSnapshot(`"POST"`)
+      expect(call.url).toBe(`https://${runtime.chainId}.rpc.test/json-rpc`)
+      expect(call.body).toMatchInlineSnapshot(
+        `"{"id":1,"jsonrpc":"2.0","method":"eth_chainId","params":[]}"`,
+      )
+      expect(call.headers['authorization']).toMatchInlineSnapshot(`"Basic cnBjLXNlY3JldA=="`)
+      expect(call.headers['cookie']).toMatchInlineSnapshot(`null`)
+      expect(call.headers['tempo-api-key']).toMatchInlineSnapshot(`null`)
+      expect(call.headers['x-client-trace']).toMatchInlineSnapshot(`"trace_test"`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('routes anonymous requests to the public RPC without basic auth', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create({
+        rpc: {
+          basicAuth: 'rpc-secret',
+          url: (chainId) => `https://${chainId}.rpc.test/json-rpc`,
+        },
+      })
+
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc/testnet', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(fetch.calls[0]?.url).toMatchInlineSnapshot(`"https://rpc.testnet.tempo.xyz/"`)
+      expect(fetch.calls[0]?.headers['authorization']).toMatchInlineSnapshot(`null`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('uses the requested chain id for upstream URL resolution', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create({
+        auth: false,
+        rpc: { url: (chainId) => `https://${chainId}.rpc.test` },
+      })
+
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc/4217', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(fetch.calls[0]?.url).toMatchInlineSnapshot(`"https://4217.rpc.test/"`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('uses mainnet for the mainnet shortcut', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create({
+        auth: false,
+        rpc: { url: (chainId) => `https://${chainId}.rpc.test` },
+      })
+
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc/mainnet', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(fetch.calls[0]?.url).toMatchInlineSnapshot(`"https://4217.rpc.test/"`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('uses testnet for the testnet shortcut', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create({
+        auth: false,
+        rpc: { url: (chainId) => `https://${chainId}.rpc.test` },
+      })
+
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc/testnet', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toMatchInlineSnapshot(`200`)
+      expect(fetch.calls[0]?.url).toMatchInlineSnapshot(`"https://42431.rpc.test/"`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('rejects invalid chain ids before proxying upstream', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create({ auth: false })
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc/0', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          method: 'POST',
+        }),
+      )
+      const body = (await response.json()) as Record<string, unknown>
+      const { requestId, ...stable } = body
+
+      expect(response.status).toMatchInlineSnapshot(`400`)
+      expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+      expect(stable).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "chain_id_invalid",
+            "message": "Invalid chain id",
+          },
+        }
+      `)
+      expect(fetch.calls).toMatchInlineSnapshot(`[]`)
+    } finally {
+      fetch.restore()
+    }
+  })
+
+  test('requires the read scope for API keys', async () => {
+    const fetch = mockRpc()
+
+    try {
+      const app = TestApp.create({
+        auth: {
+          source: TestApp.source({
+            keys: [
+              {
+                id: 'key_indexer_only',
+                orgId: 'org_test',
+                scopes: ['indexer:query'],
+                token: 'secret_indexer_key',
+              },
+            ],
+          }),
+        },
+      })
+      const response = await app.fetch(
+        new Request('http://tempo-api.test/rpc', {
+          body: JSON.stringify({ id: 1, jsonrpc: '2.0', method: 'eth_chainId' }),
+          headers: { 'tempo-api-key': 'secret_indexer_key' },
+          method: 'POST',
+        }),
+      )
+      const body = (await response.json()) as Record<string, unknown>
+      const { requestId, ...stable } = body
+
+      expect(response.status).toMatchInlineSnapshot(`403`)
+      expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+      expect(stable).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "api_key_forbidden",
+            "message": "API key missing required scope",
+          },
+        }
+      `)
+      expect(fetch.calls).toMatchInlineSnapshot(`[]`)
+    } finally {
+      fetch.restore()
+    }
+  })
+})
+
+function mockRpc() {
+  const original = globalThis.fetch
+  const calls: {
+    body: string
+    headers: Record<string, string | null>
+    method: string
+    url: string
+  }[] = []
+  const spy = vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+    const request = input instanceof Request ? input : new Request(input, init)
+    calls.push({
+      body: await request.text(),
+      headers: {
+        authorization: request.headers.get('authorization'),
+        cookie: request.headers.get('cookie'),
+        'tempo-api-key': request.headers.get('tempo-api-key'),
+        'x-client-trace': request.headers.get('x-client-trace'),
+      },
+      method: request.method,
+      url: request.url,
+    })
+    return new Response(JSON.stringify({ id: 1, jsonrpc: '2.0', result: '0xa5bf' }), {
+      headers: { 'content-type': 'application/json', 'x-upstream': 'rpc' },
+    })
+  })
+
+  return {
+    calls,
+    restore() {
+      spy.mockRestore()
+      globalThis.fetch = original
+    },
+  }
+}

package/src/apps/rpc.ts

@@ -0,0 +1,222 @@
+import { Hono, type Context, type TypedResponse } from 'hono'
+import * as z from 'zod/mini'
+
+import type * as App from '../App.js'
+import * as Auth from '../internal/Auth.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Response from '../internal/Response.js'
+import * as Schema from '../internal/Schema.js'
+import * as Viem from '../internal/Viem.js'
+
+// Request headers that must not be forwarded upstream: hop-by-hop headers, the
+// inbound host, and any caller auth so the consumer's Tempo API credentials never
+// reach the RPC service (the proxy injects its own RPC basic auth instead).
+const strippedHeaders = new Set([
+  'authorization',
+  'connection',
+  'cookie',
+  'host',
+  'keep-alive',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  'tempo-api-key',
+])
+
+/** Never reached; carries typed passthrough response variants into Hono client inference. */
+const narrowPassthrough = false as boolean
+
+/** Zod schemas owned by the raw RPC passthrough. */
+export namespace schema {
+  /** JSON-RPC request identifier. */
+  export const Id = z
+    .union([z.string(), z.number(), z.null()])
+    .check(z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'))
+
+  /** JSON-RPC error payload. */
+  export const Error = z
+    .object({
+      code: z
+        .number()
+        .check(
+          z.int(),
+          z.describe('Numeric JSON-RPC error code returned by the upstream RPC server.'),
+        ),
+      data: z
+        .optional(z.unknown())
+        .check(z.describe('Optional extra error details returned by the upstream RPC server.')),
+      message: z.string().check(z.describe('Human-readable JSON-RPC error message.')),
+    })
+    .check(z.describe('JSON-RPC error object returned when a method fails.'))
+
+  /** JSON-RPC request payload. */
+  export const Request = z
+    .object({
+      id: z
+        .optional(Id)
+        .check(
+          z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'),
+        ),
+      jsonrpc: z.literal('2.0').check(z.describe('JSON-RPC protocol version; Tempo uses `2.0`.')),
+      method: z
+        .string()
+        .check(z.describe('Ethereum JSON-RPC method to call, such as `eth_blockNumber`.')),
+      params: z
+        .optional(z.unknown())
+        .check(z.describe('Parameters for the JSON-RPC method, usually an array.')),
+    })
+    .check(z.describe('One Ethereum JSON-RPC request to send to Tempo.'))
+
+  /** JSON-RPC response payload. */
+  export const Response = z
+    .object({
+      error: z
+        .optional(Error)
+        .check(z.describe('JSON-RPC error object returned when a method fails.')),
+      id: z
+        .optional(Id)
+        .check(
+          z.describe('Client-supplied JSON-RPC request id used to match responses to requests.'),
+        ),
+      jsonrpc: z.literal('2.0').check(z.describe('JSON-RPC protocol version; Tempo uses `2.0`.')),
+      result: z
+        .optional(z.unknown())
+        .check(z.describe('Result returned by the upstream RPC method.')),
+    })
+    .check(z.describe('One JSON-RPC response returned by Tempo.'))
+
+  /** JSON-RPC request or batch request payload. */
+  export const RequestBody = z
+    .union([Request, z.array(Request)])
+    .check(z.describe('A single JSON-RPC request or an array of requests for batch calls.'))
+
+  /** JSON-RPC response or batch response payload. */
+  export const ResponseBody = z
+    .union([Response, z.array(Response)])
+    .check(z.describe('A single JSON-RPC response or an array of responses for batch calls.'))
+}
+
+/** Creates the raw Tempo RPC passthrough handler. */
+export function rpc() {
+  return new Hono<App.Environment>().post(
+    '/:chain{mainnet|testnet|[0-9]+}?',
+    Auth.policy({ apiKey: { scopes: ['data:read'] }, public: true }),
+    OpenApi.describeRoute({
+      description:
+        'Sends a single or batch Ethereum JSON-RPC request directly to Tempo. Use `/rpc/testnet`, `/rpc/mainnet`, or `/rpc/:chain` to choose a chain. This passthrough is not part of the stable API contract and is supported on a best-effort basis only. It has no compatibility, latency, availability, or data-freshness guarantees, and breaking changes may happen with limited notice.',
+      operationId: 'rpcRequest',
+      parameters: [
+        {
+          description:
+            'Optional chain selector. Use the alias `mainnet` or `testnet`, or a numeric chain id (mainnet is `4217`).',
+          example: 'testnet',
+          in: 'path' as const,
+          name: 'chain',
+          required: false,
+          schema: { pattern: '^(mainnet|testnet|[0-9]+)$', type: 'string' as const },
+        },
+      ],
+      requestBody: {
+        content: {
+          'application/json': {
+            example: { jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] },
+          },
+        },
+        required: true,
+      },
+      responses: OpenApi.responses({
+        errors: {
+          400: {
+            description: 'The chain id is invalid or this API deployment does not support it.',
+            codes: ['chain_id_invalid', 'chain_id_unsupported'],
+          },
+          502: 'The upstream Tempo RPC endpoint could not complete the request.',
+        },
+        success: {
+          description: 'JSON-RPC response returned by the upstream Tempo RPC endpoint.',
+          example: { jsonrpc: '2.0', id: 1, result: '0x10f2c' },
+          schema: schema.ResponseBody,
+        },
+      }),
+      summary: 'Call JSON-RPC',
+      tags: ['RPC'],
+    }),
+    (c) => {
+      if (Auth.narrowAccess) return Auth.accessError(c)
+
+      const chainId = resolveChainId(c)
+      if (!chainId)
+        return Response.error(c, {
+          code: 'chain_id_invalid',
+          message: 'Invalid chain id',
+          status: 400,
+        })
+
+      if (narrowPassthrough)
+        return c.json(Response.validated(schema.ResponseBody, { jsonrpc: '2.0' }), 200)
+      return passthrough(c, chainId)
+    },
+  )
+}
+
+async function passthrough(
+  c: Context<App.Environment>,
+  chainId: z.output<typeof Schema.ChainId>,
+): Promise<globalThis.Response & TypedResponse<never, never, never>> {
+  const rpc = c.get('rpc')
+  const principal = Auth.getPrincipal(c)
+  const upstream_rpc = principal?.type === 'public' && typeof rpc !== 'function' ? undefined : rpc
+  // Anonymous callers use the built-in public RPC unless a resolver chooses a
+  // different public upstream.
+  const { basicAuth, url } = Viem.resolve(upstream_rpc, { chainId, principal })
+  // The chain id is syntactically valid but this deployment has no RPC upstream
+  // configured for it (no `rpc` config and no built-in default).
+  if (!url)
+    return Response.error(c, {
+      code: 'chain_id_unsupported',
+      message: 'Unsupported chain id',
+      status: 400,
+    }) as never
+  const upstream = new URL(url)
+
+  const headers = new Headers()
+  for (const [name, value] of c.req.raw.headers)
+    if (!strippedHeaders.has(name.toLowerCase())) headers.set(name, value)
+  if (basicAuth) headers.set('authorization', `Basic ${btoa(basicAuth)}`)
+
+  // `duplex` is required when streaming a request body, but is not yet in
+  // the DOM `RequestInit` type.
+  const init: RequestInit & { duplex?: 'half' } = {
+    headers,
+    method: c.req.method,
+    redirect: 'manual',
+    signal: AbortSignal.timeout(35_000),
+  }
+  if (c.req.raw.body) {
+    init.body = c.req.raw.body
+    init.duplex = 'half'
+  }
+
+  try {
+    const response = await fetch(new Request(upstream, init))
+
+    // Stream the upstream response back verbatim so JSON-RPC bodies, status
+    // codes, and headers survive exactly as clients expect.
+    return c.newResponse(response.body, response) as globalThis.Response &
+      TypedResponse<never, never, never>
+  } catch (cause) {
+    // Timeouts and network failures become the standard 502 envelope instead
+    // of an unhandled 500.
+    return Response.upstream(c, cause) as never
+  }
+}
+
+function resolveChainId(c: Context<App.Environment>) {
+  const parameter = c.req.param('chain')
+  if (parameter === undefined) return c.get('chainId')
+
+  const parsed = Schema.ChainId.safeParse(parameter)
+  return parsed.success ? parsed.data : undefined
+}

package/src/apps/tokenlist.test.ts

@@ -0,0 +1,80 @@
+import { Store } from 'cadent'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import * as Tokenlist from './tokenlist.js'
+
+/** Reader key for the data routes. */
+const reader = {
+  id: 'key_reader',
+  orgId: 'org_test',
+  scopes: ['data:read'],
+  token: 'secret_reader',
+} satisfies TestApp.source.Key
+
+/** A known list published into the store before exercising the read endpoint. */
+const seedList = [
+  { address: '0x20c0000000000000000000000000000000001001', currency: 'USD', decimals: 6, logoUri: 'https://example.com/susd.svg', name: 'Seed USD', symbol: 'sUSD' }, // prettier-ignore
+  { address: '0x20c0000000000000000000000000000000001002', currency: 'EUR', decimals: 2, name: 'Seed EUR', symbol: 'sEUR' }, // prettier-ignore
+] as const
+const chainId = Runtime.get().chainId
+
+/** RequestInit carrying a bearer token for the given key. */
+function as(key: { token: string }) {
+  return { headers: { authorization: `Bearer ${key.token}` } } as const
+}
+
+/** Client whose verified-token store holds a published {@link seedList} snapshot. */
+async function seeded() {
+  const store = Store.memory()
+  await VerifiedTokens.replace(store, chainId, seedList)
+  return TestApp.client({
+    auth: { source: TestApp.source({ keys: [reader] }) },
+    verifiedTokens: { store },
+  })
+}
+
+describe('GET /tokenlist', () => {
+  test('serves verified tokens in the Uniswap token-list format', async () => {
+    const response = await (await seeded()).v1.tokenlist.$get({ query: {} }, as(reader))
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Tokenlist.schema.getTokenList.Response)
+
+    expect(body.name).toMatch(/^Tempo/)
+    expect(body.version).toEqual({ major: 1, minor: 0, patch: 2 })
+
+    // Token entries carry the standard fields, scoped to the requested chain,
+    // with no `extensions`; a curated `logoUri` is preserved when present.
+    expect(body.tokens).toEqual([
+      {
+        address: '0x20c0000000000000000000000000000000001001',
+        chainId,
+        decimals: 6,
+        logoURI: 'https://example.com/susd.svg',
+        name: 'Seed USD',
+        symbol: 'sUSD',
+      },
+      {
+        address: '0x20c0000000000000000000000000000000001002',
+        chainId,
+        decimals: 2,
+        name: 'Seed EUR',
+        symbol: 'sEUR',
+      },
+    ])
+    expect(body.tokens[0]).not.toHaveProperty('extensions')
+  })
+
+  test('serves an empty list for a chain with no verified tokens', async () => {
+    const response = await (
+      await seeded()
+    ).v1.tokenlist.$get({ query: { chainId: '4217' } }, as(reader))
+    expect(response.status).toBe(200)
+    const body = await TestApp.json(response, Tokenlist.schema.getTokenList.Response)
+
+    expect(body.name).toBe('Tempo Mainnet')
+    expect(body.tokens).toEqual([])
+    expect(body.version.patch).toBe(0)
+  })
+})