tapimo 0.14.0 → 0.15.0

package/src/apps/data/routes/tokenlist.ts

@@ -16,80 +16,86 @@ import * as Tokens from './tokens.js'
 /** Zod schemas owned by the tokenlist resource. */
 export namespace schema {
   /** A single token entry in the verified token list format (no `extensions`). */
-  export const Token = z
-    .object({
-      chainId: z
-        .number()
-        .check(
-          z.int(),
-          z.positive(),
-          z.describe('The Tempo chain ID where this token lives.'),
-          z.meta({ examples: [4217] }),
-        ),
-      address: Schema.tokenAddress(Tokens.tokenExample.address).check(
-        z.describe('The TIP-20 token contract address on Tempo.'),
-      ),
-      name: z
-        .string()
-        .check(
-          z.describe('The token’s human-readable name.'),
-          z.meta({ examples: [Tokens.tokenExample.name] }),
-        ),
-      symbol: z
-        .string()
-        .check(
-          z.describe('The short ticker symbol wallets and apps show for this token.'),
-          z.meta({ examples: [Tokens.tokenExample.symbol] }),
+  export const Token = OpenApi.component(
+    z
+      .object({
+        chainId: z
+          .number()
+          .check(
+            z.int(),
+            z.positive(),
+            z.describe('The Tempo chain ID where this token lives.'),
+            z.meta({ examples: [4217] }),
+          ),
+        address: Schema.tokenAddress(Tokens.tokenExample.address).check(
+          z.describe('The TIP-20 token contract address on Tempo.'),
         ),
-      decimals: z
-        .number()
-        .check(
-          z.int(),
-          z.gte(0),
-          z.lte(255),
-          z.describe(
-            'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
+        name: z
+          .string()
+          .check(
+            z.describe('The token’s human-readable name.'),
+            z.meta({ examples: [Tokens.tokenExample.name] }),
+          ),
+        symbol: z
+          .string()
+          .check(
+            z.describe('The short ticker symbol wallets and apps show for this token.'),
+            z.meta({ examples: [Tokens.tokenExample.symbol] }),
+          ),
+        decimals: z
+          .number()
+          .check(
+            z.int(),
+            z.gte(0),
+            z.lte(255),
+            z.describe(
+              'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
+            ),
+            z.meta({ examples: [Tokens.tokenExample.decimals] }),
           ),
-          z.meta({ examples: [Tokens.tokenExample.decimals] }),
+        logoURI: z.optional(z.url()).check(
+          z.describe('The curated URL for this token’s logo image, when one is set.'),
+          z.meta({
+            examples: [Tokens.tokenExample.logoUri],
+          }),
         ),
-      logoURI: z.optional(z.string()).check(
-        z.describe('The curated HTTPS URL for this token’s logo image, when one is set.'),
-        z.meta({
-          examples: [Tokens.tokenExample.logoUri],
-        }),
-      ),
-    })
-    .check(z.describe('One token entry in the standard verified token list format.'))
+      })
+      .check(z.describe('One token entry in the standard verified token list format.')),
+    'TokenListToken',
+  )
 
   /** Semantic version object required by the token-list schema. */
-  export const Version = z
-    .object({
-      major: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('The major number in the token list’s semantic version.'),
-          z.meta({ examples: [1] }),
-        ),
-      minor: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('The minor number in the token list’s semantic version.'),
-          z.meta({ examples: [0] }),
-        ),
-      patch: z
-        .number()
-        .check(
-          z.int(),
-          z.nonnegative(),
-          z.describe('The patch number in the token list’s semantic version.'),
-          z.meta({ examples: [0] }),
-        ),
-    })
-    .check(z.describe('The token list’s semantic version.'))
+  export const Version = OpenApi.component(
+    z
+      .object({
+        major: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('The major number in the token list’s semantic version.'),
+            z.meta({ examples: [1] }),
+          ),
+        minor: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('The minor number in the token list’s semantic version.'),
+            z.meta({ examples: [0] }),
+          ),
+        patch: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('The patch number in the token list’s semantic version.'),
+            z.meta({ examples: [0] }),
+          ),
+      })
+      .check(z.describe('The token list’s semantic version.')),
+    'TokenListVersion',
+  )
 
   /** Schemas for the getTokenList operation. */
   export namespace getTokenList {
@@ -99,24 +105,50 @@ export namespace schema {
       .check(z.describe('Query parameters for fetching the verified token list.'))
 
     /** A Uniswap-compatible token list of all verified tokens on a chain. */
-    export const Response = z
-      .object({
-        name: z
-          .string()
-          .check(
-            z.describe('The human-readable name of this token list.'),
-            z.meta({ examples: ['Tempo Verified Tokens'] }),
-          ),
-        timestamp: z.iso
-          .datetime()
-          .check(
-            z.describe('The ISO 8601 timestamp when this token list was last updated.'),
-            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+    export const Response = OpenApi.component(
+      z
+        .object({
+          name: z
+            .string()
+            .check(
+              z.describe('The human-readable name of this token list.'),
+              z.meta({ examples: ['Tempo Verified Tokens'] }),
+            ),
+          timestamp: z.iso
+            .datetime()
+            .check(
+              z.describe('The ISO 8601 timestamp when this token list was last updated.'),
+              z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+            ),
+          version: z
+            .union([Version])
+            .check(
+              z.describe('The token list’s semantic version.'),
+              z.meta({ examples: [{ major: 1, minor: 0, patch: 2 }] }),
+            ),
+          tokens: z.array(Token).check(
+            z.describe('The verified TIP-20 tokens on this chain.'),
+            z.meta({
+              examples: [
+                [
+                  {
+                    address: Tokens.tokenExample.address,
+                    chainId: Tokens.tokenExampleChainId,
+                    decimals: Tokens.tokenExample.decimals,
+                    logoURI: Tokens.tokenExample.logoUri,
+                    name: Tokens.tokenExample.name,
+                    symbol: Tokens.tokenExample.symbol,
+                  },
+                ],
+              ],
+            }),
           ),
-        version: Version.check(z.describe('The token list’s semantic version.')),
-        tokens: z.array(Token).check(z.describe('The verified TIP-20 tokens on this chain.')),
-      })
-      .check(z.describe('A Uniswap Token Lists-compatible list of Tempo’s verified TIP-20 tokens.'))
+        })
+        .check(
+          z.describe('A Uniswap Token Lists-compatible list of Tempo’s verified TIP-20 tokens.'),
+        ),
+      'TokenListDocument',
+    )
   }
 }
 
@@ -140,6 +172,10 @@ export function tokenlist() {
         'Returns every verified token on a Tempo chain in the standard Uniswap Token Lists format, so wallets and apps can show trusted names, symbols, and logos.',
       operationId: 'getTokenList',
       responses: OpenApi.responses({
+        errors: {
+          400: { codes: ['chain_id_invalid', 'chain_id_unsupported', 'query_invalid'] },
+          502: 'The verified-token store could not complete the request.',
+        },
         success: {
           description: 'A standard token list of Tempo’s verified TIP-20 tokens.',
           example: {
@@ -175,14 +211,23 @@ export function tokenlist() {
             Object.fromEntries(new URL(c.req.url).searchParams),
           )
           const chainId = query.chainId ?? c.get('chainId')
-          const { version } = await VerifiedTokens.snapshot(c, chainId)
-          return `${base}:v:${version}`
+          return versionedCacheKey(c, { base, chainId })
         },
       }),
       anonymousEdgeCache,
     ),
     async (c) => {
       if (Auth.narrowAccess) return Auth.paidAccessError(c)
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'chain_id_invalid',
+          message: 'Invalid chain id',
+        })
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'chain_id_unsupported',
+          message: 'Unsupported chain id',
+        })
       if (OpenApi.narrowValidation)
         return OpenApi.validationError(c, {
           code: 'query_invalid',
@@ -213,6 +258,12 @@ export function tokenlist() {
         }
         return c.json(Response.validated(schema.getTokenList.Response, list), 200)
       } catch (cause) {
+        c.set('providerFailure', {
+          chainId,
+          failure: 'query',
+          id: 'verified_tokens',
+          operation: 'snapshot',
+        })
         return Response.upstream(c, cause)
       }
     },
@@ -228,6 +279,40 @@ function anonymousEdgeCache(c: Context<App.Environment>) {
   )
 }
 
+async function versionedCacheKey(
+  c: Context<App.Environment>,
+  options: versionedCacheKey.Options,
+): Promise<string> {
+  try {
+    const { version } = await VerifiedTokens.snapshot(c, options.chainId)
+    return `${options.base}:v:${version}`
+  } catch (cause) {
+    // Let the handler retry and map a persistent store failure to its public
+    // 502 envelope. A recovered response stays uncached without a version.
+    Cache.setPolicy(c, Cache.policies.noStore)
+    if (cause instanceof Error) {
+      c.set('providerFailure', {
+        chainId: options.chainId,
+        failure: 'query',
+        id: 'verified_tokens',
+        operation: 'snapshot',
+      })
+      c.set('recoveredError', cause)
+    } else throw cause
+    return options.base
+  }
+}
+
+declare namespace versionedCacheKey {
+  /** Inputs used to build a snapshot-versioned cache key. */
+  type Options = {
+    /** Cache key without the verified-token snapshot version. */
+    base: string
+    /** Tempo chain whose verified-token snapshot versions the key. */
+    chainId: number
+  }
+}
+
 async function getTokenLogos(
   c: Context<App.Environment>,
   options: getTokenLogos.Options,

package/src/apps/data/routes/tokens.test.ts

@@ -1,5 +1,8 @@
-import { Schema } from 'tapimo'
+import type { Context } from 'hono'
+import { Schema } from 'tapimo/server'
 
+import type * as App from '../../../App.js'
+import * as Store from '../../../internal/Store.js'
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
 import * as Tokens from './tokens.js'
@@ -18,6 +21,88 @@ function app(options: TestApp.create.Options = {}) {
 
 const verifiedTokenCount = 6
 
+describe('getTokenMetadata', () => {
+  const address = '0x20c0000000000000000000000000000000000001'
+  const chainId = 1337
+  const metadata = {
+    currency: 'USD',
+    decimals: 6,
+    logoURI: '',
+    name: 'Test USD',
+    symbol: 'TUSD',
+    totalSupply: 1_000_000n,
+  }
+
+  function context(store: Store.Store, read: () => Promise<typeof metadata>) {
+    return {
+      get(name: string) {
+        if (name === 'store') return store
+        if (name === 'getClient') return () => ({ token: { getMetadata: read } })
+        throw new Error(`Unexpected context variable: ${name}`)
+      },
+    } as Context<App.Environment>
+  }
+
+  test('times cold and no-cache origin reads but not cache hits', async () => {
+    const source = Store.memory()
+    let reads = 0
+    let origins = 0
+    const read = async () => {
+      reads++
+      return metadata
+    }
+    const resolve = (store: Store.Store) =>
+      Tokens.getTokenMetadata(context(store, read), {
+        address,
+        chainId,
+        timeOrigin: async (fn) => {
+          origins++
+          return fn()
+        },
+      })
+    const requestStore = (cacheControl?: string) =>
+      Store.withRequest(source, {
+        header: (name) => (name === 'cache-control' ? cacheControl : undefined),
+      })
+
+    await resolve(requestStore())
+    await resolve(requestStore())
+    expect({ origins, reads }).toStrictEqual({ origins: 1, reads: 1 })
+
+    await resolve(requestStore('no-cache'))
+    expect({ origins, reads }).toStrictEqual({ origins: 2, reads: 2 })
+  })
+
+  test('attributes one origin read for concurrent coalesced misses', async () => {
+    const source = Store.memory()
+    let origins = 0
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const read = async () => {
+      await gate
+      return metadata
+    }
+    const resolve = () =>
+      Tokens.getTokenMetadata(context(source, read), {
+        address,
+        chainId,
+        timeOrigin: async (fn) => {
+          origins++
+          return fn()
+        },
+      })
+
+    const pending = [resolve(), resolve()]
+    await vi.waitFor(() => expect(origins).toBe(1))
+    release()
+    await Promise.all(pending)
+
+    expect(origins).toBe(1)
+  })
+})
+
 describe('OpenAPI', () => {
   test('publishes generator-ready token and balance contracts', async () => {
     const application = TestApp.create({ auth: false })
@@ -1090,7 +1175,7 @@ describe('GET /tokens/:token', () => {
         "currency": "USDC",
         "decimals": 6,
         "id": "0x20c0000000000000000000009e8d7eb59b783726",
-        "logoUri": "http://localhost/assets/42431/icons/0x20c0000000000000000000009e8d7eb59b783726",
+        "logoUri": "http://localhost/assets/42431/icons/0x20c0000000000000000000009e8d7eb59b783726?__response=svg-sandbox-v1",
         "name": "Bridged USDC (Stargate)",
         "symbol": "USDC.e",
         "verified": true,
@@ -1235,7 +1320,12 @@ describe('GET /tokens/:token/logo', () => {
       )
 
       expect(response.status).toBe(200)
+      expect(response.headers.get('content-security-policy')).toBe(
+        "base-uri 'none'; default-src 'none'; form-action 'none'; frame-ancestors 'none'; img-src data:; sandbox; style-src 'unsafe-inline'",
+      )
       expect(response.headers.get('content-type')).toBe('image/svg+xml')
+      expect(response.headers.get('etag')?.startsWith('"svg-sandbox-v1-')).toBe(true)
+      expect(response.headers.get('x-content-type-options')).toBe('nosniff')
       expect(response.headers.get('cache-control')).toBe(
         'public, max-age=86400, stale-while-revalidate=604800',
       )
@@ -1525,7 +1615,7 @@ describe('GET /tokens/:symbol', () => {
         "currency": "USDC",
         "decimals": 6,
         "id": "0x20c0000000000000000000009e8d7eb59b783726",
-        "logoUri": "http://localhost/assets/42431/icons/0x20c0000000000000000000009e8d7eb59b783726",
+        "logoUri": "http://localhost/assets/42431/icons/0x20c0000000000000000000009e8d7eb59b783726?__response=svg-sandbox-v1",
         "name": "Bridged USDC (Stargate)",
         "symbol": "USDC.e",
         "verified": true,

package/src/apps/data/routes/tokens.ts

@@ -1,11 +1,12 @@
 import { Hono, type Context } from 'hono'
-import { AbiEvent, AbiParameters } from 'ox'
+import { AbiEvent, AbiParameters, Hash } from 'ox'
 import { type Address, ContractFunctionExecutionError } from 'viem'
 import { Abis } from 'viem/tempo'
 import * as z from 'zod/mini'
 
 import * as Assets from '../../../Assets.js'
 import type * as App from '../../../App.js'
+import * as AssetResponse from '../../../internal/AssetResponse.js'
 import * as Auth from '../../../internal/Auth.js'
 import * as Cache from '../../../internal/Cache.js'
 import * as Cursor from '../../../internal/Cursor.js'
@@ -868,8 +869,8 @@ export function tokens() {
       // single shared entry serves authenticated and anonymous callers alike.
       Cache.response<App.Environment>({
         cacheControl: Cache.policies.asset,
-        name: 'tempo-api:tokens:v1',
-        key: (c) => Cache.urlKey(c, schema.getTokenLogo.Query),
+        key: (c) => AssetResponse.versionUrl(Cache.urlKey(c, schema.getTokenLogo.Query)),
+        name: 'tempo-api:tokens:v2',
         vary: ['Accept-Encoding'],
       }),
       async (c) => {
@@ -899,9 +900,9 @@ export function tokens() {
               message: 'Token logo not found',
               status: 404,
             })
-          // `Cache.response` (above) stamps the `asset` Cache-Control / Vary;
-          // only the content type is set here.
-          return c.body(logo.body, 200, { 'Content-Type': logo.contentType })
+          // `Cache.response` stamps the asset Cache-Control and Vary headers.
+          c.header('ETag', tokenLogoEtag(logo))
+          return c.body(logo.body, 200, AssetResponse.headers(logo))
         } catch (cause) {
           // A token whose on-chain metadata read reverts (unregistered TIP-20)
           // has no logo to serve — map it to the route's `404`, not a `502`,
@@ -1412,19 +1413,21 @@ export function getTokenMetadata(c: Context<App.Environment>, options: getTokenM
   const { address, chainId } = options
   const getClient = c.get('getClient')
   const store = c.get('store')
+  const timeOrigin = options.timeOrigin ?? (async <value>(fn: () => Promise<value>) => fn())
 
   return Store.memoize(
-    async () => {
-      const fresh = await getClient(chainId).token.getMetadata({ token: address as Address })
-      return {
-        currency: fresh.currency,
-        decimals: fresh.decimals,
-        logoUri: fresh.logoURI || undefined,
-        name: fresh.name,
-        symbol: fresh.symbol,
-        totalSupply: fresh.totalSupply.toString(),
-      }
-    },
+    () =>
+      timeOrigin(async () => {
+        const fresh = await getClient(chainId).token.getMetadata({ token: address as Address })
+        return {
+          currency: fresh.currency,
+          decimals: fresh.decimals,
+          logoUri: fresh.logoURI || undefined,
+          name: fresh.name,
+          symbol: fresh.symbol,
+          totalSupply: fresh.totalSupply.toString(),
+        }
+      }),
     { key: `token:v1:${chainId}:${address}:metadata`, store, ttl: Ttl.minutes(1) },
   )
 }
@@ -1433,6 +1436,8 @@ declare namespace getTokenMetadata {
   type Options = {
     address: z.output<typeof Schema.Address>
     chainId: z.output<typeof Schema.ChainId>
+    /** Optional wrapper around cache-miss origin reads. */
+    timeOrigin?: (<value>(fn: () => Promise<value>) => Promise<value>) | undefined
   }
 }
 
@@ -1454,7 +1459,11 @@ export async function getTokenLogo(c: Context<App.Environment>, options: getToke
 
   const uri = await Store.memoize(
     async () => (await getAsset(chainId, Path.join('icons', address)))?.uri ?? null,
-    { key: `token:v1:${chainId}:${address}:logo:${origin}`, store, ttl: Ttl.minutes(5) },
+    {
+      key: `token:${AssetResponse.version}:${chainId}:${address}:logo:${origin}`,
+      store,
+      ttl: Ttl.minutes(5),
+    },
   )
   return uri ?? undefined
 }
@@ -1475,10 +1484,10 @@ declare namespace getTokenLogo {
  *    curated icon.
  *
  * Returns `undefined` when neither source yields an image, so the route can
- * map that to a `404`. The curated R2 icon is trusted (we control it); the
- * on-chain `logoURI` is deployer-controlled, so it is fetched through the
- * hardened {@link fetchExternalLogo} (scheme/host allowlist, timeout, size cap,
- * raster-only content type) to bound the SSRF / resource-exhaustion surface.
+ * map that to a `404`. Curated R2 icons can originate in organization token
+ * requests, so the route sandboxes SVG responses. The on-chain `logoURI` is
+ * deployer-controlled and fetched through the hardened {@link fetchExternalLogo}
+ * (scheme/host allowlist, timeout, size cap, raster-only content type).
  */
 async function fetchTokenLogo(
   c: Context<App.Environment>,
@@ -1487,7 +1496,7 @@ async function fetchTokenLogo(
   const { address, chainId } = options
 
   // Curated R2 icon first: our override for tokens with no (or an undesirable)
-  // on-chain logo. Trusted content, served verbatim.
+  // on-chain logo. The response boundary sandboxes requester-supplied SVGs.
   const getAsset = c.get('getAsset')
   const asset = await getAsset(chainId, Path.join('icons', address))
   if (asset)
@@ -1515,6 +1524,13 @@ declare namespace fetchTokenLogo {
   }
 }
 
+// Salting the body hash forces browsers to replace validators created before
+// SVG sandboxing, while preserving conditional requests for unchanged logos.
+function tokenLogoEtag(logo: fetchTokenLogo.Logo) {
+  const digest = Hash.sha256(new Uint8Array(logo.body), { as: 'Hex' }).slice(2)
+  return `"${AssetResponse.version}-${digest}"`
+}
+
 // Cap on proxied logo bytes (1 MiB). A logo larger than this is almost
 // certainly not a real icon; the cap bounds memory for a hostile upstream.
 const maxLogoBytes = 1_000_000

package/src/apps/data/routes/transactions.test.ts

@@ -1,6 +1,6 @@
 /** @module-tag localnet */
 
-import { Schema } from 'tapimo'
+import { Schema } from 'tapimo/server'
 import { Hex } from 'ox'
 import { zeroHash } from 'viem'