tapimo 0.1.0 → 0.3.0

package/src/App.ts

@@ -1,19 +1,17 @@
-import type { Context, MiddlewareHandler } from 'hono'
+import type { Context } from 'hono'
 import { Hono } from 'hono'
 import { compress as hono_compress } from 'hono/compress'
 import { cors as hono_cors } from 'hono/cors'
 import { HTTPException } from 'hono/http-exception'
 import { requestId, type RequestIdVariables } from 'hono/request-id'
 import { generateSpecs } from 'hono-openapi'
-import { Handler as vocs_Handler } from 'vocs/server'
-import * as z from 'zod/mini'
 
+import type * as Analytics from './analytics/Analytics.js'
 import * as ApiKey from './ApiKey.js'
 import * as Assets from './Assets.js'
 import * as Auth from './internal/Auth.js'
 import * as Db from './db/Db.js'
 import * as EdgeCache from './internal/EdgeCache.js'
-import * as Handler from './Handler.js'
 import * as Log from './internal/Log.js'
 import * as MetricSink from './internal/MetricSink.js'
 import type * as Metrics from './Metrics.js'
@@ -21,34 +19,30 @@ import * as OpenApi from './internal/OpenApi.js'
 import * as Store from './internal/Store.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 type * as Tidx from './internal/Tidx.js'
 import * as Timing from './internal/Timing.js'
-import * as VerifiedTokens from './internal/VerifiedTokens.js'
 import * as Viem from './internal/Viem.js'
 
 import openrpcSpec from './openrpc.json' with { type: 'json' }
 
-import { transactions as transactionActivities } from './apps/activities.js'
-import { addresses } from './apps/addresses.js'
-import { blocks, blocksByTimestampCompat } from './apps/blocks.js'
-import { coingecko } from './apps/coingecko.js'
-import { exchanges } from './apps/exchanges.js'
-import { feeAmm } from './apps/fee-amm.js'
-import { indexer } from './apps/indexer.js'
-import { receipts } from './apps/receipts.js'
-import { rpc as rpcApp } from './apps/rpc.js'
-import { tokens } from './apps/tokens.js'
-import { transactions } from './apps/transactions.js'
-import { transfers } from './apps/transfers.js'
-import { verifiedTokens } from './apps/verified-tokens.js'
-import { tokenlist } from './apps/tokenlist.js'
-import { schema as webhookSchema, webhooks } from './apps/webhooks.js'
+import * as Metadata from './apps/metadata.js'
+import * as Data from './apps/data/App.js'
+import * as Platform from './apps/platform/App.js'
+
+export import data = Data.data
+export import platform = Platform.platform
+
+/** The chain-data route group; see {@link data}. */
+export type DataApp = ReturnType<typeof data>
+/** The tenant-platform route group; see {@link platform}. */
+export type PlatformApp = ReturnType<typeof platform>
 
 /** Hono environment variables set by the Tempo API app. */
 export type Environment = {
   Variables: Auth.Variables &
     RequestIdVariables & {
+      /** ClickHouse-backed analytics store, or a per-request factory; undefined when usage analytics is unconfigured. Resolve at the leaf with `Analytics.get`. */
+      analytics: Analytics.Source | undefined
       /** Base path for this API app. */
       basePath: string
       /** Default Tempo chain id for this API app. */
@@ -83,15 +77,18 @@ export type Environment = {
 }
 
 /**
- * Tempo API Hono app with shared API dependencies. Inferred from `create`.
- * The `path` generic is pinned to `'/'` (its default) so the resulting Hono
- * `BasePath` is a concrete literal; without the explicit type argument
- * `ReturnType<typeof create>` would resolve `path` to its constraint
- * (`string`), and Hono's `MergePath<string, '/foo'>` would surface every
- * endpoint key as `` `… ${string}/foo` `` — which can be satisfied but never
- * autocompleted.
+ * The canonical fully-composed Tempo API app ({@link create} with both route
+ * groups). {@link Client} and the reference worker target this type; a subset
+ * consumer infers its own narrower type from its own composition chain.
  */
-export type App = ReturnType<typeof create<'/'>>
+export type App = ReturnType<typeof compose>
+
+// Type anchor only — never invoked. Expresses the canonical composition so
+// `App` (and thus `Client`) reflect the full route surface; real consumers
+// compose explicitly.
+function compose(options: create.Options) {
+  return create(options).route('/', data()).route('/', platform())
+}
 
 /** Node.js request listener for `node:http` and compatible interfaces. */
 export type Listener = (incoming: unknown, outgoing: unknown) => Promise<void>
@@ -99,6 +96,12 @@ export type Listener = (incoming: unknown, outgoing: unknown) => Promise<void>
 /** HTTP endpoints owned by Tempo API handlers, used for typed auth overrides. */
 export type Endpoint = Auth.Endpoint<App>
 
+/** Stripe billing capability for platform billing routes; owned by {@link platform}. */
+export type Billing = Platform.Billing
+
+/** Transactional email sender for platform emails; owned by {@link platform}. */
+export type Email = Platform.Email
+
 /** One static API asset resolved from packaged data. */
 export type Asset = {
   /** Loaded asset response. */
@@ -118,7 +121,7 @@ const infoDescription = 'REST API for reading and interacting with Tempo'
 
 /** Creates the Tempo API Hono app. */
 export function create<const path extends string = '/'>(options: create.Options<path>) {
-  const { assets, defaultChainId = Viem.defaultChainId, path = '/' as path, rpc } = options
+  const { path = '/' as path } = options
 
   // Capture as the literal generic so `Hono.basePath(...)` preserves the
   // typed prefix. testClient's `Client<T, ...>` inference collapses to a
@@ -136,31 +139,6 @@ export function create<const path extends string = '/'>(options: create.Options<
   // `options.db`, API-key records in `options.kv`.
   const store = options.cache?.store ?? Store.memory()
 
-  // Memoize one viem client per resolved upstream. Clients are stateless HTTP
-  // transports, so reusing them avoids per-request construction cost. The cache
-  // key is the resolved output (`url` + `basicAuth` + `chainId`), not the
-  // principal, so a resolver `rpc` may branch on any principal field while
-  // client cardinality stays bounded by the number of distinct upstreams —
-  // callers that resolve to the same upstream share a client.
-  const clients = new Map<string, ReturnType<typeof Viem.getClient>>()
-  const getClient = (chainId = defaultChainId, principal: Auth.Principal | null = null) => {
-    // Resolve to derive the cache key; `Viem.getClient` re-resolves to build the
-    // client on a miss. `resolve` is pure and cheap, so the extra call is free.
-    const { url, basicAuth } = Viem.resolve(rpc, { chainId, principal })
-    const cacheKey = `${url}|${basicAuth ?? ''}|${chainId}`
-    const existing = clients.get(cacheKey)
-    if (existing) return existing
-    const client = Viem.getClient({ chainId, principal, rpc })
-    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. The same factory backs the scheduled
-  // webhook poller (`Webhooks.createPoller`), keeping client construction in
-  // one place.
-  const getTidx = Tidx.createGetClient({ defaultChainId, tidx: options.tidx })
-
   // Build the app in two phases: register middleware imperatively, then chain
   // route mounts so the merged Hono schema flows through the return type. The
   // chained type is what makes `testClient(create())` produce typed path
@@ -217,69 +195,35 @@ export function create<const path extends string = '/'>(options: create.Options<
         },
       }),
     )
-  // The chain ids this deployment serves: the built-in public chains plus the
-  // configured `defaultChainId` and any explicit `supportedChainIds`. Exposed on
-  // context so mounted apps with a path `chainId` (e.g. GeckoTerminal) can guard
-  // it too.
-  const supportedChainIds = new Set<number>([
-    ...Object.keys(Viem.url).map(Number),
-    ...Object.keys(Tidx.url).map(Number),
-    defaultChainId,
-    ...(options.supportedChainIds ?? []),
-  ])
 
   // Normalize the `db` option: the plain form is `{ source }` with no cached
   // side; `cached` falls back to `source` so consumers never branch.
   const db = 'source' in options.db ? options.db : { source: options.db }
 
+  // Normalize the `analytics` option: accept the bare source or `{ source }`,
+  // mirroring `db`. Undefined leaves usage analytics unconfigured (501).
+  const analytics =
+    options.analytics === undefined
+      ? undefined
+      : 'source' in options.analytics
+        ? options.analytics.source
+        : options.analytics
+
+  // Built-in auth: the session surface (mounted last) plus the enforcement
+  // middleware (installed below), wired together in `Auth.install`.
+  const auth = Auth.install({ auth: options.auth, db: db.source, kv: options.kv })
+
   base.use('*', Timing.middleware())
   base.use('*', async (c, next) => {
-    // Put app-level dependencies on Hono context so mounted handlers only
-    // receive request-local state from `c`.
+    c.set('analytics', analytics)
     c.set('basePath', basePath)
-    c.set('chainId', defaultChainId)
     c.set('db', db.source)
     c.set('dbCached', db.cached ?? db.source)
-    c.set('getAsset', createGetAsset({ assets, basePath, origin: new URL(c.req.url).origin }))
-    c.set('getClient', (chainId) => getClient(chainId, Auth.getPrincipal(c)))
-    c.set('getTidx', (chainId) => getTidx(chainId, Auth.getPrincipal(c)))
     c.set('kv', options.kv)
-    c.set('rpc', rpc)
     c.set('store', store)
-    c.set('supportedChainIds', supportedChainIds)
-    c.set('tidx', options.tidx)
-    // Feature configs default to enabled empty configs; `false` disables.
-    c.set('verifiedTokens', options.verifiedTokens === false ? undefined : (options.verifiedTokens ?? {})) // prettier-ignore
-    c.set('webhook', options.webhook === false ? undefined : (options.webhook ?? {}))
     await next()
   })
 
-  // Reject a syntactically valid `chainId` this deployment does not serve before
-  // it reaches an upstream — an unknown chain otherwise hits the configured
-  // RPC/indexer (a static `tidx.baseUrl` answers for any chain id) and comes
-  // back as an opaque `upstream_error`.
-  base.use('*', async (c, next) => {
-    const raw = c.req.query('chainId') ?? c.req.query('chain_id')
-    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)
-  })
-  // Skip the static asset route entirely when no store is configured; token
-  // logo URIs simply go unresolved.
-  if (assets)
-    base.use('/assets/*', async (c, next) => {
-      const key = stripAssetPath(c.req.path, basePath).replace(/^\/+/, '')
-      const asset = key ? await assets.get(key) : undefined
-      if (!asset) return next()
-      return c.body(asset.body, 200, {
-        'Cache-Control': 'public, max-age=86400',
-        'Content-Type': asset.contentType,
-      })
-    })
-
   // Safety net: any non-2xx response (auth/validation errors, MPP `402`
   // challenges, rate-limit `429`s, upstream `502`s, etc.) must never be
   // cached. This wraps endpoint middleware and handlers registered below.
@@ -295,106 +239,79 @@ export function create<const path extends string = '/'>(options: create.Options<
   // latency.
   if (options.cache?.edge !== false) base.use('*', EdgeCache.middleware<Environment>({ store }))
 
-  const base_routed = base.get('/health', OpenApi.describeRoute({ hide: true }), (c) =>
+  const app = base.get('/health', OpenApi.describeRoute({ hide: true }), (c) =>
     c.json({ status: 'ok' }, 200),
   )
 
-  for (const middleware of options.middleware ?? []) base_routed.use('*', middleware)
-
-  const app = base_routed
-    .route('/v1/addresses', addresses())
-    .route('/v1/blocks', blocks())
-    .route('/v1/exchange', exchanges())
-    .route('/v1/fee-amm', feeAmm())
-    .route('/v1/indexer', indexer())
-    .route('/v1/tokenlist', tokenlist())
-    .route('/v1/tokens', tokens())
-    .route('/v1/transactions', receipts())
-    .route('/v1/transactions', transactions())
-    .route('/v1/transactions', transactionActivities())
-    .route('/v1/transfers', transfers())
-    .route('/v1/verified-tokens', verifiedTokens())
-    .route('/v1/webhooks', webhooks({ enabled: options.webhook !== false }))
-    .route('/rpc', rpcApp())
-    .use(
-      '/rpc/relay',
-      Auth.policy({ apiKey: { scopes: ['rpc-relay'] }, mpp: false, public: false }),
-      OpenApi.describeRoute({ hide: true, summary: 'Relay RPC' }),
-    )
-    .use(
-      '/rpc/relay/*',
-      Auth.policy({ apiKey: { scopes: ['rpc-relay'] }, mpp: false, public: false }),
-      OpenApi.describeRoute({ hide: true, summary: 'Relay RPC' }),
-    )
-    .route(
-      '/rpc/relay',
-      Handler.relay({
-        cache: store,
-        getClient: (chainId) => getClient(chainId as Viem.ChainId | undefined),
-        ...(options.verifiedTokens === false
-          ? {}
-          : {
-              resolveTokens: async (chainId: number) => {
-                const snapshot = await VerifiedTokens.read(Db.get(db.cached ?? db.source), chainId)
-                return snapshot?.list.map((token) => token.address) ?? []
-              },
-            }),
-      }),
+  // Built-in enforcement: default-closed policies over OpenAPI-registered
+  // routes. `auth: false` leaves policies unenforced (tests only).
+  if (auth.middleware) app.use('*', auth.middleware)
+
+  // Collect each mounted group's OpenAPI metadata: Hono's `.route()` drops
+  // sub-app metadata, so a group attaches it to its instance (a WeakMap) and we
+  // read it back here. Patching the runtime method, not the type, keeps `hc`.
+  const metadata: create.Metadata[] = []
+  const route = app.route.bind(app)
+  ;(app as unknown as { route: typeof route }).route = ((path, sub) => {
+    const entry = Metadata.read(sub)
+    if (entry) metadata.push(entry)
+    return route(path, sub)
+  }) as typeof route
+
+  // Register the JSON error envelopes eagerly (they don't depend on mounted
+  // routes) so error handling is live before the first request and a consumer's
+  // `withSentry(app)` sees them already in place.
+  app.notFound((c) =>
+    Response.error(c, { code: 'not_found', message: 'Route not found', status: 404 }),
+  )
+  app.onError((cause, c) => {
+    if (cause instanceof HTTPException) return errorFromException(c, cause)
+
+    // Redact any leaked API-key token from the logged error/stack.
+    console.error(
+      ApiKey.redact(cause instanceof Error ? (cause.stack ?? cause.message) : String(cause)),
     )
-    .route('/gecko', coingecko())
-    // Hidden compatibility route for the prior Tempo API's
-    // `GET /chains/:chainId/blocks/by-timestamp` (chain id in the path).
-    .route('/chains', blocksByTimestampCompat())
-
-  const spec = (async () => {
-    // OAS 3.1 `webhooks`: document the signed envelope Tempo API POSTs to subscriber
-    // URLs (an outbound payload, not an endpoint of this API). Only when enabled.
-    const webhooksDoc = (() => {
-      if (options.webhook === false) return {}
-      // `io: 'output'` documents the delivered (serialized) shape; `unrepresentable: 'any'`
-      // tolerates the transaction payload's transforms (e.g. lazy fee-token metadata),
-      // which have no JSON-Schema form, by emitting `{}` for those nodes rather than throwing.
-      const envelope = z.toJSONSchema(webhookSchema.Envelope, {
-        io: 'output',
-        target: 'draft-2020-12',
-        unrepresentable: 'any',
-      })
-      delete envelope.$schema
-      const header = (name: string, description: string) => ({
-        description,
-        in: 'header' as const,
-        name,
-        required: true,
-        schema: { type: 'string' as const },
-      })
-      return {
-        webhooks: {
-          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`, or `ping`.'), // prettier-ignore
-              ],
-              requestBody: {
-                content: { 'application/json': { schema: envelope } },
-                required: true,
-              },
-              responses: { '2xx': { description: 'Delivery acknowledged.' } },
-              summary: 'Webhook event delivery',
-              tags: ['Webhooks'],
-            },
-          },
-        },
-      }
+    return Response.error(c, {
+      code: 'internal_error',
+      message: 'Internal server error',
+      status: 500,
+    })
+  })
+
+  // Mount the OpenAPI/OpenRPC documents and docs reference lazily on the first
+  // request, so the document sees the full route surface without a `seal()`
+  // step. The patched `fetch` runs this before Hono builds its matcher.
+  //
+  // Spec generation stays lazy: ordinary API traffic only installs the routes,
+  // while `/openapi.json` and the Vocs handler start the memoized build.
+  let spec: ReturnType<typeof buildSpec> | undefined
+  const getSpec = () => (spec ??= buildSpec())
+  const buildSpec = async () => {
+    // Merge each mounted group's contributed OpenAPI metadata (tags, security
+    // schemes, webhooks block). Unused tags/schemes don't render, so a subset
+    // app's document carries only what its groups contributed.
+    // The built-in session surface's metadata appends after every mounted
+    // group's, so consumer-mounted groups lead the document order.
+    const metadata_all = (() => {
+      const entry = auth.app ? Metadata.read(auth.app) : undefined
+      return entry ? [...metadata, entry] : metadata
+    })()
+    const contributedSchemes = Object.assign({}, ...metadata_all.map((m) => m.securitySchemes ?? {})) // prettier-ignore
+    const tags = metadata_all.flatMap((m) => m.tags ?? [])
+    // Tag groups contributed under the same name merge into one sidebar group,
+    // deduped and filtered to defined tags (a group may list a tag another
+    // surface defines, e.g. `Auth` from the built-in session surface).
+    const tagGroups = (() => {
+      const defined = new Set(tags.map((tag) => tag.name))
+      const groups = new Map<string, { name: string; tags: string[] }>()
+      for (const { name, tags: members } of metadata_all.flatMap((m) => m['x-tagGroups'] ?? []))
+        groups.set(name, { name, tags: [...(groups.get(name)?.tags ?? []), ...members] })
+      return [...groups.values()]
+        .map((group) => ({
+          ...group,
+          tags: [...new Set(group.tags)].filter((tag) => defined.has(tag)),
+        })) // prettier-ignore
+        .filter((group) => group.tags.length > 0)
     })()
     const generated = await generateSpecs(app, {
       documentation: {
@@ -414,6 +331,7 @@ export function create<const path extends string = '/'>(options: create.Options<
               scheme: 'bearer',
               type: 'http',
             },
+            ...contributedSchemes,
           },
         },
         info: {
@@ -427,71 +345,24 @@ export function create<const path extends string = '/'>(options: create.Options<
             { url: basePath || '/', description: 'Relative to the host serving this document.' },
           ]),
         ],
-        tags: [
-          {
-            name: 'Activities',
-            description: 'A readable feed of what an account did onchain.',
-          },
-          {
-            name: 'Balances',
-            description: 'How much of each token an account holds.',
-          },
-          {
-            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.",
-          },
-          {
-            name: 'Fee AMM',
-            description: 'Pools that convert stablecoins to pay fees.',
-          },
-          {
-            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.',
-          },
-          {
-            name: 'Verified Tokens',
-            description: 'A curated, trusted list of TIP-20 tokens.',
-          },
-          ...(options.webhook !== false
-            ? [
-                {
-                  name: 'Webhooks',
-                  description: 'Get signed callbacks when onchain events happen.',
-                },
-              ]
-            : []),
-          {
-            name: 'Indexer',
-            description: "Run read-only SQL queries against Tempo's indexed data.",
-          },
-          {
-            name: 'RPC',
-            description:
-              'Direct access to the chain over Ethereum JSON-RPC. Not part of the stable API contract; best-effort support only. No compatibility, latency, availability, or data-freshness guarantees. Breaking changes may happen with limited notice.',
-          },
-          {
-            name: 'CoinGecko',
-            description: "Exchange data in CoinGecko's GeckoTerminal format.",
-          },
-        ],
+        tags,
+        ...(tagGroups.length ? { 'x-tagGroups': tagGroups } : {}),
       },
     })
-    // Set per-operation `security` and the `402` payment-challenge response from
-    // each route's resolved auth policy (the single source of truth), so the
-    // anonymous option and `402` appear only where the public/MPP lanes are
-    // enabled — not on every operation via the document default.
+    // Document the outbound `webhooks` block only when the webhook routes are
+    // actually mounted; a disabled feature hides its routes, so it must not
+    // advertise deliveries.
+    const hasWebhookRoutes = Object.keys(generated.paths).some((path) =>
+      /\/webhooks(\/|$)/.test(path),
+    )
+    const webhookBlocks = hasWebhookRoutes ? metadata_all.flatMap((m) => (m.webhooks ? [m.webhooks()] : [])) : [] // prettier-ignore
+    const webhooksDoc = webhookBlocks.length
+      ? { webhooks: Object.assign({}, ...webhookBlocks) }
+      : {}
+    // Set per-operation `security` and the `402` payment-challenge response
+    // from each route's resolved auth policy (the single source of truth), so
+    // the anonymous option and `402` appear only where the public/MPP lanes
+    // are enabled, not on every operation via the document default.
     applyAccess(generated.paths, Auth.describeAccess(app))
     // Point the `/rpc` operation at the OpenRPC document via `x-openrpc`.
     applyOpenrpcLink(generated.paths, basePath)
@@ -501,53 +372,34 @@ export function create<const path extends string = '/'>(options: create.Options<
     // tag and preserves document path order within a tag, so reordering here
     // drives the sidebar sub-item order.
     return { ...generated, ...webhooksDoc, paths: sortPaths(generated.paths) }
-  })()
+  }
+  let finalized = false
+  const finalize = () => {
+    if (finalized) return
+    finalized = true
 
-  app.get('/openapi.json', async (c) => c.json(await spec))
-
-  // The OpenRPC document is a committed build artifact (no runtime generator);
-  // see scripts/openrpc/build.ts and `pnpm openrpc:build`.
-  app.get('/openrpc.json', (c) => c.json(openrpcSpec))
-
-  if (options.docs !== false)
-    app.route(
-      '/',
-      vocs_Handler.openApi(
-        {
-          // Inline the OpenRPC doc so vocs expands it without a self-subrequest
-          // (see `inlineOpenrpc`); the public `/openapi.json` keeps the URL ref.
-          spec: spec.then(inlineOpenrpc),
-          sidebar: { collapsed: true },
-          vocs: { logoUrl: OpenApi.logoUrl, title: 'Tempo API Reference', ...options.docs },
-        },
-        { fallback: 'next', css: OpenApi.css },
-      ),
-    )
+    app.get('/openapi.json', async (c) => c.json(await getSpec()))
 
-  app.notFound((c) =>
-    Response.error(c, { code: 'not_found', message: 'Route not found', status: 404 }),
-  )
+    // The OpenRPC document is a committed build artifact (no runtime generator);
+    // see scripts/openrpc/build.ts and `pnpm openrpc:build`.
+    app.get('/openrpc.json', (c) => c.json(openrpcSpec))
 
-  app.onError((cause, c) => {
-    if (cause instanceof HTTPException) return errorFromException(c, cause)
+    // Mount each docs group's reference factory (see `docs()` in `tapimo/docs`)
+    // last, so its catch-all sits behind every API route and the documents
+    // above — regardless of where the group sat in the composition chain.
+    for (const entry of metadata) if (entry.docs) app.route('/', entry.docs({ spec: getSpec }))
+  }
 
-    // Redact any leaked API-key token from the logged error/stack.
-    console.error(
-      ApiKey.redact(cause instanceof Error ? (cause.stack ?? cause.message) : String(cause)),
-    )
-    return Response.error(c, {
-      code: 'internal_error',
-      message: 'Internal server error',
-      status: 500,
-    })
-  })
+  // Patch `fetch` to finalize once before dispatch. `request()` reads
+  // `this.fetch` dynamically so it picks up the patch, and the captured
+  // `originalFetch` still dispatches as a bare value (used by `App.listener`).
+  const originalFetch = app.fetch
+  ;(app as unknown as { fetch: typeof originalFetch }).fetch = ((request, ...rest) => {
+    finalize()
+    return originalFetch(request, ...rest)
+  }) as typeof originalFetch
 
-  // Return the typed chained Hono directly. Spreading `store`/`listener` onto
-  // the app would intersect the inferred Hono type and breaks `testClient`'s
-  // schema inference for downstream consumers. The cache `store` is owned by
-  // the caller (pass `options.cache.store`), and a Node listener is produced on
-  // demand via `App.listener(app)`.
-  return app
+  return route('/', auth.app ?? new Hono<Environment>())
 }
 
 /**
@@ -561,10 +413,16 @@ export function listener(app: { fetch: NodeFetch }): Listener {
 }
 
 export declare namespace create {
-  /** Options for creating the Tempo API Hono app. */
+  /**
+   * Options for creating the Tempo API Hono app — the shared core:
+   * db/cache/kv/auth capabilities and cross-cutting middleware. Chain-data
+   * configuration belongs to {@link data}; email to {@link platform}.
+   */
   type Options<path extends string = '/'> = {
-    /** Static API asset store for the current runtime (e.g. `Assets.cloudflareR2(...)`). Omit to skip static assets — token logo URIs go unresolved. */
-    assets?: Assets | undefined
+    /** Analytics store for usage reads (e.g. `Analytics.clickhouse(...)`), or a per-request factory. Accepts `{ source }` to mirror `db`. Omit to leave usage analytics unconfigured — usage routes answer 501. Ingest happens outside this app (queue consumer via `Analytics.handleQueue`). */
+    analytics?: Analytics.Source | { source: Analytics.Source } | undefined
+    /** Authentication: lane defaults, quotas, and credentials for the built-in enforcement middleware, plus the `session` sign-in surface. Omit for default-closed policies with in-memory rate limiting; pass false to leave policies unenforced (tests only). */
+    auth?: Auth.install.Options['auth'] | false | undefined
     /** Caching configuration: the cache store plus the edge response cache toggle. */
     cache?: Cache | undefined
     /** Response compression for API handlers. Disabled by default; pass true for defaults or a config object to customize. Leave disabled when fronted by a proxy/CDN that already compresses. */
@@ -573,32 +431,16 @@ export declare namespace create {
     cors?: boolean | Cors | undefined
     /** Authoritative Postgres store backing stateful features (webhooks, verified tokens). Pass a long-lived `Db.postgres(...)` singleton on Node, or a factory (`() => Db.postgres(...)`) on Workers so each request builds a fresh Hyperdrive-pooled connection. Pass `{ source, cached }` to route staleness-tolerant reads (verified tokens) through a second, query-caching Hyperdrive config; `source` stays uncached for read-after-write correctness. Apply migrations out of band via `tapimo admin migrate`. */
     db: Db.Source | { cached?: Db.Source | undefined; source: Db.Source }
-    /** Default Tempo chain id for requests that omit `chainId`. */
-    defaultChainId?: Viem.ChainId | undefined
     /** KV state store backing API-key records (e.g. `Store.cloudflareKv(...)`). Omit to leave API-key auth closed — every token resolves to `null`. */
     kv?: Kv | undefined
-    /** Vocs API reference options. Set to false to disable the `/` docs page. */
-    docs?: Docs | false | undefined
     /** Request logging. Disabled by default. Pass `true` to emit one canonical structured log entry per request through the level-matched console method (indexed by Workers Logs); a level (e.g. `'warn'`) to emit only that level and above (dropping successful-request info lines); or an emit function for a custom sink. */
     logger?: boolean | Log.Level | Logger | undefined
     /** Metrics backend. Disabled by default; pass a backend (e.g. `Metrics.cloudflare()`) to emit request (HTTP) metrics per response. Pass the same backend to the webhook poller/queue handlers so they emit over it too. */
     metrics?: Metrics.Metrics | undefined
-    /** Hono middleware to run before API handlers mount. */
-    middleware?: readonly MiddlewareHandler[] | undefined
     /** Base path to mount API handlers under. Provided as a literal via the `path` generic so the resulting Hono schema keeps typed route paths for `testClient`. */
     path?: path | undefined
     /** OpenAPI `servers` for the generated document. Defaults to a single relative server (the host serving the doc), so the reference targets the deployment it is served from. Set the canonical public URL(s) here, e.g. `[{ url: 'https://api.tempo.xyz' }]`. */
     servers?: readonly Server[] | undefined
-    /** Extra Tempo chain ids this deployment serves, in addition to the built-in public chains and the configured `defaultChainId`. A request for a `chainId` outside this set is rejected with a clear 400 instead of reaching an upstream. */
-    supportedChainIds?: readonly number[] | undefined
-    /** Tempo RPC options. */
-    rpc?: Rpc | 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 (subscription/delivery rows live in `db`). Pass `false` to disable: the `/webhooks` routes stay mounted (for a stable schema and typed test client) but return `404` and are hidden from the OpenAPI document. */
-    webhook?: Webhook | false | undefined
   }
 
   /** KV state-store configuration. */
@@ -620,27 +462,6 @@ export declare namespace create {
     store?: Store.Store | undefined
   }
 
-  /** Verified-token feature configuration. */
-  type VerifiedTokens = {
-    /**
-     * Per-isolate soft-refresh window in milliseconds. Within this window
-     * verified-token lookups are served from the in-memory snapshot with no
-     * database I/O; after it, the next lookup re-checks the head version
-     * (single-flight) and recompiles only when it changed. Defaults to 10_000.
-     */
-    refreshMs?: number | undefined
-  }
-
-  /** Webhook feature configuration. */
-  type Webhook = {
-    /**
-     * Maximum active subscriptions a single owner may hold. Creation is rejected
-     * with `403 limit_exceeded` once reached. Defaults to 100; bounds the
-     * spam/SSRF surface and unbounded downstream delivery cost per owner.
-     */
-    maxPerOwner?: number | undefined
-  }
-
   /** Binary asset store for static API assets (e.g. `Assets.cloudflareR2(...)`). */
   type Assets = Assets.Assets
 
@@ -650,8 +471,14 @@ export declare namespace create {
   /** CORS middleware options. */
   type Cors = NonNullable<Parameters<typeof hono_cors>[0]>
 
-  /** Vocs API reference options (theme, top navigation, logo, socials, …). */
-  type Docs = NonNullable<Parameters<typeof vocs_Handler.openApi>[0]['vocs']>
+  /** Reference-UI factory a docs group carries via {@link Metadata} (see `docs()` in `tapimo/docs`): given the app's OpenAPI document builder, returns an app that {@link create} mounts at the root on finalize. */
+  type Docs = (context: DocsContext) => Hono<any, any, any>
+
+  /** Context the app provides to a docs group's reference factory. */
+  type DocsContext = {
+    /** Memoized OpenAPI document builder — the same document served at `/openapi.json`. */
+    spec: () => Promise<{ paths: Record<string, unknown> }>
+  }
 
   /** Custom request-log sink, receiving one canonical entry per request. */
   type Logger = Log.Emit
@@ -665,10 +492,39 @@ export declare namespace create {
   }
 
   /**
-   * Tempo RPC options: a static config, or a per-request resolver function that
-   * routes by request principal to a separate (e.g. public, no-auth) RPC.
+   * What a route group contributes to the composed app beyond its routes:
+   * OpenAPI document metadata (tags, security schemes, outbound webhooks block)
+   * and an optional docs-UI factory. `create` collects these off each mounted
+   * group (via {@link Metadata}); unused entries don't render.
    */
-  type Rpc = Viem.getClient.Rpc
+  type Metadata = {
+    /** Reference-UI factory mounted at the root on finalize (see `docs()` in `tapimo/docs`). */
+    docs?: Docs | undefined
+    /** Security scheme definitions this group's routes reference (e.g. the session cookie). */
+    securitySchemes?: Record<string, unknown> | undefined
+    /** Root-level OpenAPI tag definitions for this group's operations. */
+    tags?: readonly Tag[] | undefined
+    /** Builds the OAS 3.1 `webhooks` block documenting outbound deliveries, emitted only when the group's webhook routes are mounted. Called during spec generation only, keeping schema conversion off isolate startup. */
+    webhooks?: (() => Record<string, unknown>) | undefined
+    /** Vocs tag-group metadata for grouping root tags in the reference. */
+    'x-tagGroups'?: readonly TagGroup[] | undefined
+  }
+
+  /** One root-level OpenAPI tag definition. */
+  type Tag = {
+    /** Human-readable summary shown in the reference sidebar. */
+    description: string
+    /** Tag name referenced by operations. */
+    name: string
+  }
+
+  /** One Vocs OpenAPI tag group. */
+  type TagGroup = {
+    /** Section name shown by tag-group-aware references. */
+    name: string
+    /** Root tag names in this group. */
+    tags: readonly string[]
+  }
 }
 
 function getRequestId(c: Context<Environment>) {
@@ -746,10 +602,11 @@ function sortPaths(paths: PathsObject): PathsObject {
 
 /**
  * Sets per-operation `security` and the `402` payment-challenge response from
- * each route's resolved access lanes (see {@link Auth.describeAccess}). The
- * anonymous (`{}`) security option and the `402` response are emitted only where
- * the route's policy enables the public and MPP lanes respectively; required
- * API-key scopes are surfaced as the `x-required-scopes` extension.
+ * each route's resolved access lanes (see {@link Auth.describeAccess}).
+ * Security options compose from the enabled lanes — API keys (header +
+ * bearer), sessions (cookie + bearer token), anonymous (`{}`) — and the `402`
+ * response is emitted only where the MPP lane is enabled; required API-key
+ * scopes are surfaced as the `x-required-scopes` extension.
  */
 function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAccess>) {
   for (const item of Object.values(paths)) {
@@ -757,7 +614,12 @@ function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAc
       if (!isMutableOperation(op)) continue
       const lanes = access[op.operationId]
       if (!lanes) continue
-      op.security = [{ apiKey: [] }, { bearerAuth: [] }, ...(lanes.public ? [{}] : [])]
+      const security = [
+        ...(lanes.apiKey ? [{ apiKey: [] }, { bearerAuth: [] }] : []),
+        ...(lanes.session ? [{ session: [] }, ...(lanes.apiKey ? [] : [{ bearerAuth: [] }])] : []),
+        ...(lanes.public ? [{}] : []),
+      ]
+      if (security.length > 0) op.security = security
       if (lanes.scopes.length > 0) op['x-required-scopes'] = [...lanes.scopes]
       if (lanes.mpp) op.responses = { ...op.responses, 402: OpenApi.paymentChallengeRef }
       else if (op.responses) delete op.responses['402']
@@ -772,7 +634,7 @@ function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAc
  * method/param/return schemas it accepts.
  *
  * The public `/openapi.json` keeps a URL reference (small, conventional). The
- * docs handler instead receives the document inlined — see `inlineOpenrpc`.
+ * docs handler instead inlines the document — see `inlineOpenrpc` in `tapimo/docs`.
  */
 function applyOpenrpcLink(paths: PathsObject, basePath: string) {
   // `basePath` is `/` at the root mount and `/api` etc. otherwise; strip any
@@ -783,31 +645,6 @@ function applyOpenrpcLink(paths: PathsObject, basePath: string) {
       if (isMutableOperation(op) && isRpcOperation(op)) op['x-openrpc'] = url
 }
 
-/**
- * Returns a shallow copy of `spec` with the JSON-RPC passthrough operation's
- * `x-openrpc` replaced by the inline OpenRPC document, for the docs handler.
- *
- * Vocs expands `x-openrpc` at request time. A URL reference (as kept in the
- * public `/openapi.json`) would make the docs worker fetch its own
- * `/openrpc.json` — a self-subrequest that is unreliable on Cloudflare Workers
- * and silently falls back to a single, unexpanded operation. Inlining the
- * committed artifact keeps expansion deterministic across local and deployed
- * environments, without bloating the public spec. Only the affected path/op are
- * cloned; the rest of the (large) document is shared by reference.
- */
-function inlineOpenrpc<spec extends { paths: Record<string, unknown> }>(spec: spec): spec {
-  const paths: Record<string, unknown> = {}
-  for (const [pathname, item] of Object.entries(spec.paths)) {
-    let next = item
-    if (isRecord(item))
-      for (const [method, op] of Object.entries(item))
-        if (isMutableOperation(op) && isRpcOperation(op))
-          next = { ...item, [method]: { ...op, 'x-openrpc': openrpcSpec } }
-    paths[pathname] = next
-  }
-  return { ...spec, paths }
-}
-
 type PathsObject = Awaited<ReturnType<typeof generateSpecs>>['paths']
 type PathItem = PathsObject[string]
 type Operation = { summary?: string | undefined }
@@ -839,45 +676,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === 'object' && !Array.isArray(value)
 }
 
-function createGetAsset(options: createGetAsset.Options): GetAsset {
-  const { assets, basePath, origin } = options
-  // Without an asset store, every lookup misses so callers fall back to their
-  // "no static data" behavior (undefined logo URIs).
-  if (!assets) return () => undefined
-  return async (chainId, path) => {
-    // Public URLs include `/assets/:chainId`, but the store is keyed by
-    // `:chainId/:path` (e.g. an R2 object key), decoupled from the URL shape.
-    // `path` may be absolute (`Path.join` returns a leading slash); strip it so
-    // the key is `:chainId/:path`, not `:chainId//:path`.
-    const pathname = Path.join(basePath, 'assets', String(chainId), path)
-    const key = `${chainId}/${path.replace(/^\/+/, '')}`
-    const asset = await assets.get(key)
-    if (!asset) return undefined
-    // Return an absolute public URL (scheme + host) against the request origin
-    // so logo URLs work for any consumer regardless of the API's domain.
-    return {
-      response: new globalThis.Response(asset.body, {
-        headers: { 'Content-Type': asset.contentType },
-      }),
-      uri: new URL(pathname, origin).toString(),
-    }
-  }
-}
-
-declare namespace createGetAsset {
-  type Options = {
-    assets?: create.Assets | undefined
-    basePath: string
-    origin: string
-  }
-}
-
-function stripAssetPath(path: string, basePath: string) {
-  for (const prefix of [`${Path.join(basePath, 'assets')}/`, '/assets/'])
-    if (path.startsWith(prefix)) return `/${path.slice(prefix.length)}`
-  return path
-}
-
 type GetNodeRequestListener = (typeof import('@hono/node-server'))['getRequestListener']
 type NodeFetch = Parameters<GetNodeRequestListener>[0]
 type NodeRequestListener = ReturnType<GetNodeRequestListener>