tapimo 0.14.0 → 0.15.0

package/src/apps/composition.test.ts

@@ -1,5 +1,5 @@
-import { App, Store } from 'tapimo'
-import { data, funding, management, mpp, relay } from 'tapimo/apps'
+import { data, routes, management, mpp, relay } from 'tapimo/apps'
+import { App, Store } from 'tapimo/server'
 import { Hono } from 'hono'
 import { describeRoute } from 'hono-openapi'
 import * as TestApp from '../../test/App.js'
@@ -92,7 +92,9 @@ describe('App.from()', () => {
         externalKey: { in: 'header', name: 'external-key', type: 'apiKey' },
       },
       tags: [{ description: 'Externally defined routes.', name: 'External' }],
-      webhooks: () => ({ externalEvent: { post: { responses: { 200: { description: 'OK' } } } } }),
+      webhooks: () => ({
+        document: { externalEvent: { post: { responses: { 200: { description: 'OK' } } } } },
+      }),
       'x-tagGroups': [{ name: 'External API', tags: ['External'] }],
     })
     expectTypeOf(external).toEqualTypeOf<typeof group>()
@@ -154,12 +156,12 @@ describe('data()', () => {
     expect(keys.some((path) => path.startsWith('/v1/blocks'))).toBe(true)
     expect(keys.some((path) => path.startsWith('/v1/orgs'))).toBe(false)
     expect(keys.some((path) => path.startsWith('/v1/me'))).toBe(false)
-    expect(keys.some((path) => path.startsWith('/v1/funding'))).toBe(false)
+    expect(keys.some((path) => path.startsWith('/v1/routes'))).toBe(false)
 
     // The omitted management route resolves to a 404 (never mounted), not a 401.
     const orgs = await app.request('/v1/orgs')
     expect(orgs.status).toBe(404)
-    expect((await app.request('/v1/funding/chains')).status).toBe(404)
+    expect((await app.request('/v1/routes/chains')).status).toBe(404)
   })
 
   test('inherits shared chain context', async () => {
@@ -196,6 +198,7 @@ describe('data()', () => {
           4217,
           42431,
           421700001,
+          421700002,
           421700006,
           1424310003,
         ],
@@ -283,41 +286,41 @@ describe('data()', () => {
   })
 })
 
-describe('funding()', () => {
-  test('mounts the Funding & Bridge API independently', async () => {
-    const group = funding()
-    expectTypeOf(App.funding).toEqualTypeOf<typeof funding>()
-    expectTypeOf(group).toEqualTypeOf<App.FundingApp>()
+describe('routes()', () => {
+  test('mounts the Routes API independently', async () => {
+    const group = routes()
+    expectTypeOf(App.routes).toEqualTypeOf<typeof routes>()
+    expectTypeOf(group).toEqualTypeOf<App.RoutesApp>()
     const app = App.create({ auth: false, db: TestApp.database() }).route('/', group)
     const spec = await document(app)
 
     expect(
       Object.keys(spec.paths)
-        .filter((path) => path.startsWith('/v1/funding'))
+        .filter((path) => path.startsWith('/v1/routes'))
         .sort(),
     ).toEqual(
       [
-        '/v1/funding/chains',
-        '/v1/funding/deposit-addresses',
-        '/v1/funding/deposit-addresses/{id}',
-        '/v1/funding/deposit-addresses/{id}/reconcile',
-        '/v1/funding/deposits',
-        '/v1/funding/deposits/{id}',
-        '/v1/funding/providers',
-        '/v1/funding/quotes',
-        '/v1/funding/transfers',
-        '/v1/funding/transfers/vault',
-        '/v1/funding/transfers/zone',
-        '/v1/funding/transfers/{id}',
-        '/v1/funding/transfers/{id}/source-transactions',
+        '/v1/routes/chains',
+        '/v1/routes/deposit-addresses',
+        '/v1/routes/deposit-addresses/{id}',
+        '/v1/routes/deposit-addresses/{id}/reconcile',
+        '/v1/routes/deposits',
+        '/v1/routes/deposits/{id}',
+        '/v1/routes/providers',
+        '/v1/routes/quotes',
+        '/v1/routes/transfers',
+        '/v1/routes/transfers/vault',
+        '/v1/routes/transfers/zone',
+        '/v1/routes/transfers/{id}',
+        '/v1/routes/transfers/{id}/source-transactions',
       ].sort(),
     )
     expect(Object.keys(spec.paths).some((path) => path.startsWith('/v1/tokens'))).toBe(false)
-    expect(spec.paths['/webhooks/funding/{providerId}']).toBeUndefined()
+    expect(spec.paths['/webhooks/routes/{providerId}']).toBeUndefined()
     expect(spec['x-tagGroups']).toEqual([
       {
-        name: 'Funding & Bridge API',
-        tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Funding Transfers'],
+        name: 'Routes API',
+        tags: ['Chains', 'Deposit Addresses', 'Providers', 'Quotes', 'Route Transfers'],
       },
     ])
     expect(
@@ -327,20 +330,20 @@ describe('funding()', () => {
         ),
       ),
     ).toEqual([
-      'listFundingDepositAddresses',
-      'createFundingDepositAddress',
-      'reconcileFundingDepositAddress',
-      'getFundingDepositAddress',
-      'getFundingDeposit',
-      'listFundingDeposits',
+      'listRoutesDepositAddresses',
+      'createRoutesDepositAddress',
+      'reconcileRoutesDepositAddress',
+      'getRoutesDepositAddress',
+      'getRoutesDeposit',
+      'listRoutesDeposits',
     ])
     expect((await app.request('/v1/tokens')).status).toBe(404)
   })
 
-  test('keeps data and funding transfers separate with the same display name', async () => {
+  test('keeps data and route transfers separate with the same display name', async () => {
     const app = App.create({ auth: false, db: TestApp.database() })
       .route('/', data())
-      .route('/', funding())
+      .route('/', routes())
     const spec = await document(app)
     const operationTag = (path: string, method: 'get' | 'post') =>
       (spec.paths[path] as Record<string, { tags?: readonly string[] | undefined } | undefined>)[
@@ -348,15 +351,15 @@ describe('funding()', () => {
       ]?.tags
 
     expect({
-      chains: operationTag('/v1/funding/chains', 'get'),
-      depositAddress: operationTag('/v1/funding/deposit-addresses', 'post'),
-      deposits: operationTag('/v1/funding/deposits', 'get'),
-      providers: operationTag('/v1/funding/providers', 'get'),
-      quotes: operationTag('/v1/funding/quotes', 'get'),
+      chains: operationTag('/v1/routes/chains', 'get'),
+      depositAddress: operationTag('/v1/routes/deposit-addresses', 'post'),
+      deposits: operationTag('/v1/routes/deposits', 'get'),
+      providers: operationTag('/v1/routes/providers', 'get'),
+      quotes: operationTag('/v1/routes/quotes', 'get'),
       tokenTransfers: operationTag('/v1/transfers', 'get'),
-      transfers: operationTag('/v1/funding/transfers', 'get'),
-      vault: operationTag('/v1/funding/transfers/vault', 'post'),
-      zone: operationTag('/v1/funding/transfers/zone', 'post'),
+      transfers: operationTag('/v1/routes/transfers', 'get'),
+      vault: operationTag('/v1/routes/transfers/vault', 'post'),
+      zone: operationTag('/v1/routes/transfers/zone', 'post'),
     }).toEqual({
       chains: ['Chains'],
       depositAddress: ['Deposit Addresses'],
@@ -364,40 +367,40 @@ describe('funding()', () => {
       providers: ['Providers'],
       quotes: ['Quotes'],
       tokenTransfers: ['Transfers'],
-      transfers: ['Funding Transfers'],
-      vault: ['Funding Transfers'],
-      zone: ['Funding Transfers'],
+      transfers: ['Route Transfers'],
+      vault: ['Route Transfers'],
+      zone: ['Route Transfers'],
     })
 
     const groups = Object.fromEntries(
       (spec['x-tagGroups'] ?? []).map((group) => [group.name, group.tags]),
     )
     expect(groups['Data API']).toContain('Transfers')
-    expect(groups['Data API']).not.toContain('Funding Transfers')
-    expect(groups['Funding & Bridge API']).toContain('Funding Transfers')
-    expect(groups['Funding & Bridge API']).not.toContain('Transfers')
+    expect(groups['Data API']).not.toContain('Route Transfers')
+    expect(groups['Routes API']).toContain('Route Transfers')
+    expect(groups['Routes API']).not.toContain('Transfers')
     expect(spec.tags.filter((tag) => tag.name === 'Transfers')).toHaveLength(1)
-    expect(spec.tags.filter((tag) => tag.name === 'Funding Transfers')).toEqual([
+    expect(spec.tags.filter((tag) => tag.name === 'Route Transfers')).toEqual([
       {
-        description: 'Inbound funding transfers.',
-        name: 'Funding Transfers',
+        description: 'Transfers routed between supported chains.',
+        name: 'Route Transfers',
         'x-displayName': 'Transfers',
-        'x-pagePath': 'funding/transfers',
+        'x-pagePath': 'routes/transfers',
       },
     ])
     expect(
       Object.fromEntries(
-        (groups['Funding & Bridge API'] ?? []).map((name) => {
+        (groups['Routes API'] ?? []).map((name) => {
           const tag = spec.tags.find((tag) => tag.name === name)
           return [tag?.['x-displayName'] ?? tag?.name, tag?.['x-pagePath']]
         }),
       ),
     ).toEqual({
-      Chains: 'funding/chains',
-      'Deposit Addresses': 'funding/deposit-addresses',
-      Providers: 'funding/providers',
-      Quotes: 'funding/quotes',
-      Transfers: 'funding/transfers',
+      Chains: 'routes/chains',
+      'Deposit Addresses': 'routes/deposit-addresses',
+      Providers: 'routes/providers',
+      Quotes: 'routes/quotes',
+      Transfers: 'routes/transfers',
     })
   })
 })
@@ -434,7 +437,12 @@ describe('mpp()', () => {
 describe('management()', () => {
   test('mounts management routes and omits data routes', async () => {
     const app = App.create({
-      auth: { session: { wallet: { origin: 'https://test.example' } } },
+      auth: {
+        session: {
+          secret: 'test-better-auth-secret-at-least-32-characters',
+          wallet: { origin: 'https://test.example' },
+        },
+      },
       db: TestApp.database(),
       kv: { store: Store.memory() },
     }).route('/', management())

package/src/apps/data/App.test.ts

@@ -1,11 +1,14 @@
+import * as jose from 'jose'
 import { Secp256k1 } from 'ox'
 import { ZoneRpcAuthentication } from 'ox/tempo'
 import { Challenge, PaymentRequest } from 'mppx'
-import { RateLimit } from 'tapimo'
+import { RateLimit } from 'tapimo/server'
 
 import * as TestApp from '../../../test/App.js'
 import * as Tempo from '../../../test/Tempo.js'
+import type * as Log from '../../internal/Log.js'
 import * as Store from '../../internal/Store.js'
+import * as VercelOidc from '../../internal/VercelOidc.js'
 import * as Viem from '../../internal/Viem.js'
 
 /** A supported non-mainnet chain id, exercising the sandbox testnet allowance. */
@@ -197,10 +200,14 @@ describe('zone chain gate', () => {
     token: 'secret_legacy_moderato',
   } satisfies TestApp.kvStore.Key
 
-  function zoneOptions(chainId: number) {
+  function zoneOptions(
+    chainId: number,
+    options: { sourceChainId?: Viem.ChainId | undefined } = {},
+  ) {
     return TestApp.zone({
       chainId,
       rpcUrl: `https://${chainId}.rpc.test`,
+      ...options,
     })
   }
 
@@ -212,6 +219,14 @@ describe('zone chain gate', () => {
     token: 'secret_zone',
   } satisfies TestApp.kvStore.Key
 
+  /** Zone reader owned by an organization outside the OIDC rollout. */
+  const otherOrganizationReader = {
+    id: 'key_other_organization',
+    orgId: 'org_other',
+    scopes: ['data:read', `zone:${zone}:read`],
+    token: 'secret_other_organization',
+  } satisfies TestApp.kvStore.Key
+
   /** Zone writer: broadcasts signed transactions and reads data for `zone`. */
   const zoneWriter = {
     id: 'key_zone_writer',
@@ -301,6 +316,115 @@ describe('zone chain gate', () => {
     expect(response.status).toBe(200)
   })
 
+  test('enforces Vercel OIDC independently from the existing Zone API key', async () => {
+    const entries: Log.Entry[] = []
+    const { privateKey, publicKey } = await jose.generateKeyPair('RS256', { extractable: true })
+    const issuer = 'https://oidc.vercel.com/privy'
+    const kid = 'vercel-test-key'
+    const jwks = jose.createLocalJWKSet({
+      keys: [{ ...(await jose.exportJWK(publicKey)), kid }],
+    })
+    const vercelOidc = VercelOidc.create(
+      {
+        enforce: true,
+        environments: ['preview', 'production'],
+        issuer,
+        orgIds: [zoneReader.orgId],
+        projectIds: ['prj_expected'],
+        teamId: 'team_privy',
+      },
+      { jwks: () => jwks },
+    )
+    const credential = await new jose.SignJWT({
+      environment: 'preview',
+      owner_id: 'team_privy',
+      project_id: 'prj_expected',
+    })
+      .setProtectedHeader({ alg: 'RS256', kid, typ: 'JWT' })
+      .setIssuer(issuer)
+      .setAudience(String(zone))
+      .setIssuedAt()
+      .setExpirationTime('1h')
+      .sign(privateKey)
+    const app = TestApp.create({
+      auth: { keys: [admin, otherOrganizationReader, zoneReader] },
+      logger: (entry) => void entries.push(entry),
+      vercelOidc,
+      zones: [
+        zoneOptions(zone, { sourceChainId: Viem.chainId.mainnet }),
+        zoneOptions(zoneB, { sourceChainId: Viem.chainId.testnet }),
+      ],
+    })
+    const response = await app.request(`/v1/tokenlist?chainId=${zone}`, {
+      headers: {
+        authorization: `Bearer ${credential}`,
+        'tempo-api-key': zoneReader.token,
+      },
+    })
+
+    expect(response.status).toBe(200)
+    expect(entries[0]).toMatchObject({
+      principal: { id: zoneReader.id, type: 'api_key' },
+      vercelOidc: [
+        {
+          chainId: zone,
+          environment: 'preview',
+          enforce: true,
+          outcome: 'authorized',
+          reason: 'authorized',
+        },
+      ],
+    })
+    const deniedResponse = await app.request(`/v1/tokenlist?chainId=${zone}`, {
+      headers: { 'tempo-api-key': zoneReader.token },
+    })
+    expect(deniedResponse.status).toBe(401)
+    expect(entries[1]).toMatchObject({
+      level: 'warn',
+      vercelOidc: [
+        {
+          chainId: zone,
+          enforce: true,
+          outcome: 'denied',
+          reason: 'missing',
+        },
+      ],
+    })
+    const inferredDeniedResponse = await app.request(
+      `/v1/addresses/${Tempo.accounts[0].address}/activities?chainId=${Viem.chainId.mainnet}&include=zones`,
+      { headers: { 'tempo-api-key': zoneReader.token } },
+    )
+    expect(inferredDeniedResponse.status).toBe(401)
+    expect(entries[2]).toMatchObject({
+      level: 'warn',
+      vercelOidc: [
+        {
+          chainId: zone,
+          enforce: true,
+          outcome: 'denied',
+          reason: 'missing',
+        },
+      ],
+    })
+    const testnetResponse = await app.request(`/v1/tokenlist?chainId=${zoneB}`, {
+      headers: {
+        authorization: `Bearer ${credential}`,
+        'tempo-api-key': admin.token,
+      },
+    })
+    expect(testnetResponse.status).toBe(200)
+    expect(entries[3]).not.toHaveProperty('vercelOidc')
+    const otherOrganizationResponse = await app.request(`/v1/tokenlist?chainId=${zone}`, {
+      headers: { 'tempo-api-key': otherOrganizationReader.token },
+    })
+    expect(otherOrganizationResponse.status).toBe(200)
+    expect(entries[4]).toMatchObject({
+      level: 'info',
+      principal: { id: otherOrganizationReader.id, type: 'api_key' },
+    })
+    expect(entries[4]).not.toHaveProperty('vercelOidc')
+  })
+
   test('the legacy Moderato id and read scope route to current upstreams', async () => {
     const fetch = vi
       .spyOn(globalThis, 'fetch')
@@ -472,6 +596,8 @@ describe('zone chain gate', () => {
 })
 
 describe('sandbox chain guard', () => {
+  const mainnetZone = 421_700_001
+
   test('rejects a sandbox key that omits `chainId` on a mainnet-default deployment', async () => {
     const response = await mainnetDefaultClient().v1.tokenlist.$get({ query: {} }, as(sandbox))
     expect(response.status).toBe(403)
@@ -492,6 +618,32 @@ describe('sandbox chain guard', () => {
     )
   })
 
+  test('rejects a sandbox key on a mainnet-backed Zone', async () => {
+    const key = {
+      ...sandbox,
+      scopes: ['data:read', `zone:${mainnetZone}:read`],
+    } satisfies TestApp.kvStore.Key
+    const client = TestApp.client({
+      auth: { keys: [key] },
+      zones: [
+        TestApp.zone({
+          chainId: mainnetZone,
+          rpcUrl: `https://${mainnetZone}.rpc.test`,
+          sourceChainId: Viem.chainId.mainnet,
+        }),
+      ],
+    })
+    const response = await client.v1.tokenlist.$get(
+      { query: { chainId: String(mainnetZone) } },
+      as(key),
+    )
+
+    expect(response.status).toBe(403)
+    expect(((await response.json()) as { error: { code: string } }).error.code).toBe(
+      'api_key_forbidden',
+    )
+  })
+
   test('allows a sandbox key on a testnet `chainId`', async () => {
     const client = mainnetDefaultClient()
     const response = await client.v1.tokenlist.$get(

package/src/apps/data/App.ts

@@ -5,13 +5,16 @@ 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 EdgeCache from '../../internal/EdgeCache.js'
+import * as OpenApi from '../../internal/OpenApi.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 Timing from '../../internal/Timing.js'
+import * as VercelOidc from '../../internal/VercelOidc.js'
 import * as Viem from '../../internal/Viem.js'
 import * as Scope from '../../Scope.js'
 import * as Metadata from '../metadata.js'
@@ -75,6 +78,16 @@ export function data(options: data.Options = {}) {
       .filter((route) => route.path === '/v1/earn/vaults/:vaultId/positions/:address')
       .map((route) => route.handler),
   )
+  const databaseOnlyRouteHandlers = new Set(
+    earn_routes.routes
+      .filter((route) => route.path === '/v1/earn/rewards/eligibility')
+      .map((route) => route.handler),
+  )
+  const bodyChainRouteHandlers = new Set(
+    earn_routes.routes
+      .filter((route) => route.method === 'POST' && databaseOnlyRouteHandlers.has(route.handler))
+      .map((route) => route.handler),
+  )
 
   const app = new Hono<App.Environment>()
     // Publish the chain-data context vars for this group's handlers. Runs after
@@ -126,6 +139,12 @@ export function data(options: data.Options = {}) {
           message: selection.conflict ? 'Conflicting chain ids' : 'Invalid chain id',
           status: 400,
         })
+      if (matchedRoutes(c).some((route) => databaseOnlyRouteHandlers.has(route.handler))) {
+        if (!supportedChainIds.has(selection.chainId))
+          return Response.unsupportedChainId(c, selection.chainId, supportedChainIds)
+        c.set('chainId', selection.chainId)
+        return next()
+      }
       const principal = Auth.getPrincipal(c)
       const rpc_config = c.get('rpc')
       const tidx_config = c.get('tidx')
@@ -174,6 +193,22 @@ export function data(options: data.Options = {}) {
             message: 'The API key has no readable configured Zones.',
             status: 403,
           })
+        const policy = c.get('vercelOidc')
+        if (policy?.applies(principal)) {
+          const results = await Promise.all(
+            zoneChainIds.flatMap((chainId) => {
+              const zone = zones.get(chainId)
+              if (zone?.sourceId === undefined || !Viem.isMainnet(zone.sourceId)) return []
+              return [policy.verify(c.req.raw, zone)]
+            }),
+          )
+          const failures = results.filter(
+            (result) => VercelOidc.authorizationError(result) !== undefined,
+          )
+          const error = failures[0] && VercelOidc.authorizationError(failures[0])
+          if (results.length > 0) c.set('vercelOidcResults', results)
+          if (error) return Response.error(c, error)
+        }
         c.set('supportedChainIds', new Set([selection.chainId, ...zoneChainIds]))
         c.set('zoneChainIds', zoneChainIds)
         return next()
@@ -182,7 +217,7 @@ export function data(options: data.Options = {}) {
       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.
+    // caller's Zone token to an explicitly configured public node that enforces account scoping.
     .use('*', async (c, next) => {
       const zones = c.get('zones')
       if (zones.size === 0) return next()
@@ -197,9 +232,17 @@ export function data(options: data.Options = {}) {
       if (!selection.matched) return next()
       if (selection.inferredZones) return next()
       const chainId = c.get('chainId')
-      if (!zones.has(chainId)) return next()
+      const zone = zones.get(chainId)
+      if (!zone) return next()
 
       const principal = Auth.getPrincipal(c)
+      if (zone.sourceId !== undefined && Viem.isMainnet(zone.sourceId)) {
+        const policy = c.get('vercelOidc')
+        const result = policy?.applies(principal) ? await policy.verify(c.req.raw, zone) : undefined
+        const error = result && VercelOidc.authorizationError(result)
+        if (result) c.set('vercelOidcResults', [result])
+        if (error) return Response.error(c, error)
+      }
       const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
       const allowed =
         scopes?.includes(Scope.wildcard) ||
@@ -227,6 +270,7 @@ export function data(options: data.Options = {}) {
     .use('*', async (c, next) => {
       const principal = Auth.getPrincipal(c)
       if (principal?.type !== 'api_key' || principal.environment !== 'sandbox') return next()
+      if (matchedRoutes(c).some((route) => bodyChainRouteHandlers.has(route.handler))) return next()
 
       const selection = resolveChainSelector({
         c,
@@ -236,7 +280,12 @@ export function data(options: data.Options = {}) {
         indexerHandlers: indexerRouteHandlers,
         rpcOnlyHandlers: rpcOnlyRouteHandlers,
       })
-      if (!selection.matched || selection.inferredZones || !Viem.isMainnet(c.get('chainId')))
+      const chainId = c.get('chainId')
+      if (
+        !selection.matched ||
+        selection.inferredZones ||
+        !Viem.isMainnet(c.get('zones').get(chainId)?.sourceId ?? chainId)
+      )
         return next()
 
       return Response.error(c, {
@@ -255,7 +304,7 @@ export function data(options: data.Options = {}) {
       if (!asset) return next()
       return c.body(asset.body, 200, {
         'Cache-Control': 'public, max-age=86400',
-        'Content-Type': asset.contentType,
+        ...AssetResponse.headers(asset),
       })
     })
     .route('/', addresses_routes)
@@ -411,6 +460,8 @@ function resolveChainSelector(options: {
 }
 
 function pathChainSelector(routePath: string, requestPath: string) {
+  // Bare RPC always uses the default chain; query parameters never select its upstream.
+  if (routePath.endsWith('/rpc')) return { name: 'chain' as const, value: undefined }
   const route = routePath.split('/')
   const request = requestPath.split('/')
   for (let index = 0; index < route.length; index++) {
@@ -484,42 +535,51 @@ const openapi = {
 function webhooksBlock() {
   const envelope = z.toJSONSchema(webhookSchema.Envelope, {
     io: 'output',
+    override: OpenApi.recoverExamples,
     target: 'draft-2020-12',
     unrepresentable: 'any',
   })
   delete envelope.$schema
-  const header = (name: string, description: string) => ({
+  const header = (name: string, description: string, example: string) => ({
     description,
     in: 'header' as const,
     name,
     required: true,
-    schema: { type: 'string' as const },
+    schema: { examples: [example], type: 'string' as const },
   })
   return {
-    event: {
-      post: {
-        description:
-          'When an event you subscribed to happens, Tempo sends this signed message to your webhook URL as an HTTP POST (the same shape is used by `POST /webhooks/:id/ping` so you can test your endpoint). Always verify the `tempo-signature` header before trusting the body, then reply with any 2xx status to confirm you received it. If your endpoint returns a non-2xx status, times out, or redirects, Tempo retries with increasing delays; an endpoint that keeps failing is eventually disabled.',
-        parameters: [
-          header(
-            'tempo-signature',
-            'Signature proving the message really came from Tempo. An HMAC-SHA256 of the body using your webhook secret, formatted `t=<unix>,v1=<hex>`. Verify this before trusting the payload.',
-          ),
-          header(
-            'tempo-event-id',
-            'A unique, stable id for this event (`evt_…`). The same event may be delivered more than once, so use this id to skip duplicates.',
-          ),
-          header('tempo-event-type', 'What happened: `token:transfer`, `transaction:included`, `log:emitted`, `block:created`, `funding:deposit.updated`, `funding:transfer.updated`, or `ping`.'), // prettier-ignore
-        ],
-        requestBody: {
-          content: { 'application/json': { schema: envelope } },
-          required: true,
+    document: {
+      event: {
+        post: {
+          description:
+            'When an event you subscribed to happens, Tempo sends this signed message to your webhook URL as an HTTP POST (the same shape is used by `POST /webhooks/:id/ping` so you can test your endpoint). Always verify the `tempo-signature` header before trusting the body, then reply with any 2xx status to confirm you received it. If your endpoint returns a non-2xx status, times out, or redirects, Tempo retries with increasing delays; an endpoint that keeps failing is eventually disabled.',
+          parameters: [
+            header(
+              'tempo-signature',
+              'Signature proving the message really came from Tempo. An HMAC-SHA256 of the body using your webhook secret, formatted `t=<unix>,v1=<hex>`. Verify this before trusting the payload.',
+              't=1786543200,v1=5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8',
+            ),
+            header(
+              'tempo-event-id',
+              'A unique, stable id for this event (`evt_…`). The same event may be delivered more than once, so use this id to skip duplicates.',
+              'evt_515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665',
+            ),
+            header('tempo-event-type', 'What happened: `token:transfer`, `transaction:included`, `log:emitted`, `block:created`, `routes:deposit.updated`, `routes:transfer.updated`, or `ping`.', 'token:transfer'), // prettier-ignore
+          ],
+          operationId: 'receiveWebhookEvent',
+          requestBody: {
+            content: {
+              'application/json': { schema: { $ref: '#/components/schemas/WebhookEventEnvelope' } },
+            },
+            required: true,
+          },
+          responses: { '2XX': { description: 'Delivery acknowledged.' } },
+          summary: 'Webhook event delivery',
+          tags: ['Webhooks'],
         },
-        responses: { '2xx': { description: 'Delivery acknowledged.' } },
-        summary: 'Webhook event delivery',
-        tags: ['Webhooks'],
       },
     },
+    schemas: { WebhookEventEnvelope: envelope },
   }
 }
 
@@ -538,7 +598,7 @@ function createGetAsset(options: createGetAsset.Options): App.GetAsset {
     if (!asset) return undefined
     return {
       response: new globalThis.Response(asset.body, {
-        headers: { 'Content-Type': asset.contentType },
+        headers: AssetResponse.headers(asset),
       }),
       uri: Assets.url({ basePath, chainId, origin, path }),
     }