tapimo 0.4.4 → 0.5.1

package/src/apps/data/App.ts

@@ -1,15 +1,19 @@
-import { Hono } from 'hono'
+import { type Context, Hono } from 'hono'
+import { matchedRoutes } from 'hono/route'
+import { ZoneRpcAuthentication } from 'ox/tempo'
 import * as z from 'zod/mini'
 
 import type * as Assets from '../../Assets.js'
 import type * as App from '../../App.js'
-import * as Metadata from '../metadata.js'
 import * as Auth from '../../internal/Auth.js'
+import * as EdgeCache from '../../internal/EdgeCache.js'
 import * as Path from '../../internal/Path.js'
 import * as Response from '../../internal/Response.js'
 import * as Schema from '../../internal/Schema.js'
 import * as Tidx from '../../internal/Tidx.js'
 import * as Viem from '../../internal/Viem.js'
+import * as Scope from '../../Scope.js'
+import * as Metadata from '../metadata.js'
 
 import { transactions as transactionActivities } from './routes/activities.js'
 import { addresses } from './routes/addresses.js'
@@ -29,102 +33,111 @@ import { verifiedTokens } from './routes/verified-tokens.js'
 import { schema as webhookSchema, webhooks } from './routes/webhooks.js'
 
 /**
- * The chain-data route group: read endpoints over blocks, transactions, tokens,
- * the exchange/fee-AMM, and the RPC/indexer passthroughs. It owns all chain
- * configuration and publishes the chain clients on request context.
+ * The chain-data route group extends app context with TIDX, assets, zones,
+ * verified tokens, and webhooks, and exposes indexed and RPC-backed reads.
  *
  * ```ts
  * App.create(options).route('/', data())
  * ```
  */
 export function data(options: data.Options = {}) {
-  const { assets, defaultChainId = Viem.defaultChainId, rpc: rpc_option, tidx } = options
+  const { assets, tidx } = options
 
-  // The chain ids this deployment serves (built-in public chains plus
-  // `defaultChainId` and any explicit `supportedChainIds`). Published on context
-  // so handlers with a path `chainId` can guard it too.
-  const supportedChainIds = new Set<number>([
-    ...Object.keys(Viem.url).map(Number),
-    ...Object.keys(Tidx.url).map(Number),
-    defaultChainId,
-    ...(options.supportedChainIds ?? []),
-  ])
+  // Zone endpoints are explicit trust boundaries; the API never derives them.
+  const zones = new Map((options.zones ?? []).map((zone) => [zone.chainId, zone]))
+  const dataRouteHandlers = new Set<unknown>()
 
-  // Memoize one viem client per resolved upstream (stateless HTTP transports).
-  // Keying on the resolved output (`url`+`basicAuth`+`chainId`), not the
-  // principal, bounds cardinality by the number of distinct upstreams.
-  const clients = new Map<string, ReturnType<typeof Viem.getClient>>()
-  const getClient = (chainId = defaultChainId, principal: Auth.Principal | null = null) => {
-    const { url, basicAuth } = Viem.resolve(rpc_option, { chainId, principal })
-    const cacheKey = `${url}|${basicAuth ?? ''}|${chainId}`
-    const existing = clients.get(cacheKey)
-    if (existing) return existing
-    const client = Viem.getClient({ chainId, principal, rpc: rpc_option })
-    clients.set(cacheKey, client)
-    return client
-  }
-
-  // Memoize TIDX clients per `chainId` so the base URL resolver runs once per
-  // chain instead of on every request.
-  const getTidx = Tidx.createGetClient({ defaultChainId, tidx })
+  const getTidx = Tidx.createGetClient({ tidx })
 
   const app = new Hono<App.Environment>()
     // Publish the chain-data context vars for this group's handlers. Runs after
     // `App.create`'s middleware, so `getClient`/`getTidx` can key on the
     // resolved principal and `getAsset` can read `basePath` off context.
     .use('*', async (c, next) => {
-      c.set('chainId', defaultChainId)
+      const getClient = c.get('getClient')
+      const supportedChainIds = new Set<number>([
+        ...c.get('supportedChainIds'),
+        ...Object.keys(Tidx.url).map(Number),
+        ...zones.keys(),
+      ])
       c.set('getAsset', createGetAsset({ assets, basePath: c.get('basePath'), origin: new URL(c.req.url).origin })) // prettier-ignore
-      c.set('getClient', (chainId) => getClient(chainId, Auth.getPrincipal(c)))
-      c.set('getTidx', (chainId) => getTidx(chainId, Auth.getPrincipal(c)))
-      c.set('rpc', rpc_option)
+      c.set('getClient', (chainId) => getClient(chainId ?? c.get('chainId')))
+      c.set('getTidx', (chainId) => getTidx(chainId ?? c.get('chainId'), Auth.getPrincipal(c)))
       c.set('supportedChainIds', supportedChainIds)
       c.set('tidx', tidx)
       c.set('verifiedTokens', options.verifiedTokens === false ? undefined : (options.verifiedTokens ?? {})) // prettier-ignore
       c.set('webhook', options.webhook === false ? undefined : (options.webhook ?? {}))
+      c.set('zones', zones)
       await next()
     })
-    // Reject a well-formed but unsupported `chainId` before it reaches an
-    // upstream, which would otherwise return an opaque `upstream_error`.
+    // Resolve one chain for every data route before auth and handlers use it.
+    .use('*', async (c, next) => {
+      const defaultChainId = c.get('chainId')
+      const supportedChainIds = c.get('supportedChainIds')
+      const selection = resolveChainSelector({
+        c,
+        defaultChainId,
+        handlers: dataRouteHandlers,
+      })
+      if (!selection.matched) return next()
+      if (selection.conflict || selection.invalid)
+        return Response.error(c, {
+          code: 'chain_id_invalid',
+          message: selection.conflict ? 'Conflicting chain ids' : 'Invalid chain id',
+          status: 400,
+        })
+      if (!supportedChainIds.has(selection.chainId))
+        return Response.unsupportedChainId(c, selection.chainId, supportedChainIds)
+      c.set('chainId', selection.chainId)
+      return next()
+    })
+    // Zone data requires an issued scope. Raw RPC may instead forward the
+    // caller's Zone token to the node that enforces account scoping.
     .use('*', async (c, next) => {
-      const raw = resolveChainSelector({
-        basePath: c.get('basePath') ?? '',
-        path: c.req.path,
-        query: c.req.query('chainId') ?? c.req.query('chain_id'),
+      if (zones.size === 0) return next()
+      const selection = resolveChainSelector({
+        c,
+        defaultChainId: c.get('chainId'),
+        handlers: dataRouteHandlers,
       })
-      if (raw === undefined) return next()
-      // Only reject a well-formed-but-unsupported chain here; malformed values
-      // (e.g. `abc`, `0`) fall through to the route's own query validation.
-      const parsed = Schema.ChainId.safeParse(raw)
-      if (!parsed.success || supportedChainIds.has(parsed.data)) return next()
-      return Response.unsupportedChainId(c, parsed.data, supportedChainIds)
+      if (!selection.matched) return next()
+      const chainId = c.get('chainId')
+      if (!zones.has(chainId)) return next()
+
+      const principal = Auth.getPrincipal(c)
+      const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
+      const allowed =
+        scopes?.includes(Scope.wildcard) ||
+        scopes?.includes(`zone:${chainId}:read`) ||
+        (selection.rpc && Boolean(c.req.header(ZoneRpcAuthentication.headerName)?.trim()))
+      if (!allowed)
+        return Response.error(c, {
+          code: 'api_key_forbidden',
+          message: selection.rpc
+            ? `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\`, or pass a Zone token via \`X-Authorization-Token\`.`
+            : `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\`.`,
+          status: 403,
+        })
+
+      await next()
+      // Defense in depth for cache misses; pre-auth lookups are disabled by
+      // the route eligibility predicate below.
+      c.set('edgeCache', undefined)
     })
     // Sandbox keys are testnet-only. A chain-scoped data route defaults to
     // mainnet, so a sandbox key that omits `chainId` (or targets mainnet) is
     // refused with a clear message telling the caller to pass a testnet
-    // `chainId`. The relay resolves its chain from the request body, not the
-    // query, so it is skipped and enforces the rule in its sponsor validation.
+    // `chainId`.
     .use('*', async (c, next) => {
-      const rpc = Path.join(c.get('basePath') ?? '', 'rpc')
-      const relay = Path.join(rpc, 'relay')
-      if (c.req.path === relay || c.req.path.startsWith(`${relay}/`)) return next()
-
       const principal = Auth.getPrincipal(c)
       if (principal?.type !== 'api_key' || principal.environment !== 'sandbox') return next()
 
-      const raw = resolveChainSelector({
-        basePath: c.get('basePath') ?? '',
-        path: c.req.path,
-        query: c.req.query('chainId') ?? c.req.query('chain_id'),
+      const selection = resolveChainSelector({
+        c,
+        defaultChainId: c.get('chainId'),
+        handlers: dataRouteHandlers,
       })
-      // Absent falls back to the group default (mainnet); a malformed value
-      // stays with the route's own validator rather than the sandbox message.
-      const chainId = (() => {
-        if (raw === undefined) return defaultChainId
-        const parsed = Schema.ChainId.safeParse(raw)
-        return parsed.success ? parsed.data : undefined
-      })()
-      if (chainId === undefined || !Viem.isMainnet(chainId)) return next()
+      if (!selection.matched || !Viem.isMainnet(c.get('chainId'))) return next()
 
       return Response.error(c, {
         code: 'api_key_forbidden',
@@ -149,7 +162,7 @@ export function data(options: data.Options = {}) {
     .route('/', blocks())
     .route('/', exchanges())
     .route('/', feeAmm())
-    .route('/', funding(options.fundingRoutes))
+    .route('/', funding(options.funding))
     .route('/', indexer())
     .route('/', receipts())
     .route('/', tokenlist())
@@ -162,19 +175,28 @@ export function data(options: data.Options = {}) {
     .route('/', rpc())
     .route('/', coingecko())
     .route('/', blocksByTimestampCompat())
-  return Metadata.attach(app, openapi)
-}
-
-function resolveChainSelector(options: {
-  basePath: string
-  path: string
-  query: string | undefined
-}) {
-  const rpc = Path.join(options.basePath, 'rpc')
-  if (options.path === rpc) return undefined
-  if (options.path.startsWith(`${rpc}/`))
-    return options.path.slice(rpc.length + 1).split('/')[0] || undefined
-  return options.query
+  const edgeCacheEligible = (c: Context<App.Environment>) => {
+    const selection = resolveChainSelector({
+      c,
+      defaultChainId: c.get('chainId'),
+      handlers: dataRouteHandlers,
+    })
+    return (
+      selection.matched &&
+      !selection.conflict &&
+      !selection.invalid &&
+      !zones.has(selection.chainId)
+    )
+  }
+  for (const route of app.routes) {
+    if (route.method === 'ALL') continue
+    dataRouteHandlers.add(route.handler)
+    if (zones.size > 0) EdgeCache.setEligibility(route.handler, edgeCacheEligible)
+  }
+  return Metadata.attach(app, {
+    ...openapi,
+    supportedChainIds: [...Object.keys(Tidx.url).map(Number), ...zones.keys()],
+  })
 }
 
 export declare namespace data {
@@ -182,20 +204,27 @@ export declare namespace data {
   type Options = {
     /** Static API asset store for the current runtime (e.g. `Assets.cloudflareR2(...)`). Omit to skip static assets — token logo URIs go unresolved. */
     assets?: Assets.Assets | undefined
-    /** Default Tempo chain id for requests that omit `chainId`. */
-    defaultChainId?: Viem.ChainId | undefined
-    /** Funding route provider adapter configuration. Omit to serve static inventory only. */
-    fundingRoutes?: funding.Options | undefined
-    /** Tempo RPC options: a static config, or a per-request resolver that routes by request principal to a separate (e.g. public, no-auth) RPC. */
-    rpc?: Viem.getClient.Rpc | undefined
-    /** Extra chain ids this deployment serves, beyond the built-in public chains and `defaultChainId`. A `chainId` outside this set is rejected with a 400. */
-    supportedChainIds?: readonly number[] | undefined
+    /** Funding quote provider configuration. */
+    funding?: funding.Options | undefined
     /** TIDX query client options. */
     tidx?: Tidx.getClient.Tidx | undefined
     /** Verified-token feature configuration. Enabled by default (token rows live in `db`; empty until published); pass `false` to always serve an empty verified list. */
     verifiedTokens?: VerifiedTokens | false | undefined
     /** Webhook feature configuration. Enabled by default (rows live in `db`); pass `false` to disable, leaving `/webhooks` mounted but returning `404` and hidden from the OpenAPI document. */
     webhook?: Webhook | false | undefined
+    /**
+     * Zone chains served by this deployment. REST and TIDX require a
+     * `zone:<chainId>:read` scope; raw RPC may forward a Zone token instead.
+     */
+    zones?: readonly Zone[] | undefined
+  }
+
+  /** One zone chain served by this deployment. */
+  type Zone = {
+    /** Zone chain id. Consumer-supplied literal; the API never derives zone chain ids. */
+    chainId: number
+    /** Zone RPC used when forwarding a caller-supplied Zone token. */
+    forwardRpcUrl: string
   }
 
   /** Verified-token feature configuration. */
@@ -219,6 +248,66 @@ export declare namespace data {
   }
 }
 
+function resolveChainSelector(options: {
+  c: Context<App.Environment>
+  defaultChainId: Viem.ChainId
+  handlers: ReadonlySet<unknown>
+}) {
+  let matched = false
+  let path: string | undefined
+  let rpc = false
+  for (const route of matchedRoutes(options.c)) {
+    if (!options.handlers.has(route.handler)) continue
+    matched = true
+    const selector = pathChainSelector(route.path, options.c.req.path)
+    if (selector.name === undefined) continue
+    path = selector.value
+    rpc = selector.name === 'chain'
+    break
+  }
+
+  if (!matched)
+    return {
+      chainId: options.defaultChainId,
+      conflict: false,
+      invalid: false,
+      matched: false,
+      rpc: false,
+    }
+
+  const search = new URL(options.c.req.url).searchParams
+  const raw = [
+    ...(path === undefined ? [] : [path]),
+    ...(rpc ? [] : search.getAll('chainId')),
+    ...(rpc ? [] : search.getAll('chain_id')),
+  ]
+  const parsed = raw.map((value) => Schema.ChainId.safeParse(value))
+  const chainIds = [...new Set(parsed.flatMap((result) => (result.success ? [result.data] : [])))]
+  return {
+    chainId: chainIds[0] ?? options.defaultChainId,
+    conflict: chainIds.length > 1,
+    invalid: parsed.some((result) => !result.success),
+    matched: true,
+    rpc,
+  }
+}
+
+function pathChainSelector(routePath: string, requestPath: string) {
+  const route = routePath.split('/')
+  const request = requestPath.split('/')
+  for (let index = 0; index < route.length; index++) {
+    const segment = route[index] ?? ''
+    for (const name of ['chainId', 'chain'] as const) {
+      const prefix = `:${name}`
+      if (!segment.startsWith(prefix)) continue
+      const suffix = segment.slice(prefix.length)
+      if (suffix !== '' && suffix !== '?' && !suffix.startsWith('{')) continue
+      return { name, value: request[index] || undefined }
+    }
+  }
+  return { name: undefined, value: undefined }
+}
+
 /**
  * The OpenAPI metadata this group owns: its operation tags and the outbound
  * `webhooks` block. Tagged onto the {@link data} instance so `App.create`
@@ -231,8 +320,7 @@ const openapi = {
     { name: 'Blocks', description: 'The ordered batches of transactions making up the chain.' },
     { name: 'Exchange', description: "Tempo's built-in stablecoin exchange: pairs, swaps, orders, prices." }, // prettier-ignore
     { name: 'Fee AMM', description: 'Pools that convert stablecoins to pay fees.' },
-    { name: 'Funding', description: 'Routes and inventory for moving stablecoins into Tempo.' },
-    { name: 'Providers', description: 'Provider metadata, capabilities, and integration status.' },
+    { name: 'Funding', description: 'Live quotes and supported inputs for funding Tempo.' },
     { name: 'Tokens', description: 'TIP-20 token details, supply, and holders.' },
     { name: 'Transactions', description: 'Transactions submitted to Tempo, and their receipts.' },
     { name: 'Transfers', description: 'Token movements from executing transactions.' },
@@ -252,7 +340,6 @@ const openapi = {
         'Exchange',
         'Fee AMM',
         'Funding',
-        'Providers',
         'Tokens',
         'Transactions',
         'Transfers',