tapimo 0.7.1 → 0.8.0

package/src/App.ts

@@ -1,10 +1,12 @@
 import type { Context } from 'hono'
 import { Hono } from 'hono'
+import { matchedRoutes } from 'hono/route'
 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 type { Chain } from 'viem'
 
 import type * as Analytics from './analytics/Analytics.js'
 import * as ApiKey from './ApiKey.js'
@@ -18,6 +20,7 @@ import type * as Metrics from './Metrics.js'
 import * as OpenApi from './internal/OpenApi.js'
 import * as Store from './internal/Store.js'
 import * as Path from './internal/Path.js'
+import type * as Provider from './internal/Provider.js'
 import * as Response from './internal/Response.js'
 import * as Scope from './Scope.js'
 import type * as Tidx from './internal/Tidx.js'
@@ -27,18 +30,23 @@ import * as Viem from './internal/Viem.js'
 import openrpcSpec from './openrpc.json' with { type: 'json' }
 
 import * as Metadata from './apps/metadata.js'
+import * as Zones from './apps/Zones.js'
 import * as Data from './apps/data/App.js'
+import * as Funding from './apps/funding/App.js'
 import * as Management from './apps/management/App.js'
 import * as Mpp from './apps/mpp/App.js'
 import * as Relay from './apps/relay/App.js'
 
 export import data = Data.data
+export import funding = Funding.funding
 export import management = Management.management
 export import mpp = Mpp.mpp
 export import relay = Relay.relay
 
 /** The chain-data route group; see {@link data}. */
 export type DataApp = ReturnType<typeof data>
+/** The inbound funding route group; see {@link funding}. */
+export type FundingApp = ReturnType<typeof funding>
 /** The management route group; see {@link management}. */
 export type ManagementApp = ReturnType<typeof management>
 /** The MPP credential relay route group; see {@link mpp}. */
@@ -62,6 +70,8 @@ export type Environment = {
       dbCached: Db.Source
       /** KV state store backing API-key records, or undefined when key auth is closed. */
       kv: { store: Store.State } | undefined
+      /** Providers registered by the host application. */
+      providers: readonly Provider.Provider[]
       /** Issuable API-key scope catalog, including host-defined entries. */
       scopeCatalog: Scope.Catalog
       /** Gets one static API asset. */
@@ -80,8 +90,8 @@ export type Environment = {
       tidx: Tidx.getClient.Tidx | undefined
       /** Verified-token feature configuration (refresh window), or undefined when the feature is disabled. Token rows live in `db`. */
       verifiedTokens: { refreshMs?: number | undefined } | undefined
-      /** Zone RPC endpoints keyed by chain id; empty when none are configured. */
-      zones: ReadonlyMap<number, Data.data.Zone>
+      /** Zone chains keyed by chain id; empty when none are configured. */
+      zones: ReadonlyMap<number, Chain>
       /** Webhook feature configuration, or undefined when webhooks are disabled. Rows live in `db`. */
       webhook: Webhook | undefined
     } & EdgeCache.Variables &
@@ -107,8 +117,9 @@ export function from<const app extends Hono<any, any>>(app: app, metadata: creat
 function compose(options: create.Options) {
   return create(options)
     .route('/', data())
+    .route('/', funding())
     .route('/', relay())
-    .route('/', mpp())
+    .route('/', mpp({ state: Store.memory() }))
     .route('/', management())
 }
 
@@ -141,10 +152,28 @@ export type Asset = {
 }
 
 /** Gets one static API asset for a chain, or undefined when it is missing. */
-export type GetAsset = (
+export type GetAsset = ((
   chainId: Viem.ChainId,
   path: string,
-) => Asset | undefined | Promise<Asset | undefined>
+) => Asset | undefined | Promise<Asset | undefined>) & {
+  /** Lists public asset locations under a path prefix, when supported. */
+  list?: GetAsset.List | undefined
+}
+
+export declare namespace GetAsset {
+  /** Lists public asset locations for a chain and path prefix. */
+  type List = (
+    chainId: Viem.ChainId,
+    path: string,
+  ) => Promise<
+    readonly {
+      /** Internal asset-store key. */
+      key: string
+      /** Absolute public API URL for the asset. */
+      uri: string
+    }[]
+  >
+}
 
 /** Top-level OpenAPI `info.description`, rendered above the reference. */
 const infoDescription = 'REST API for reading and interacting with Tempo'
@@ -170,12 +199,24 @@ export function create<const path extends string = '/'>(options: create.Options<
   const store = options.cache?.store ?? Store.memory()
   const scopeCatalog = Scope.extend(options.scopes)
   const defaultChainId = options.defaultChainId ?? Viem.defaultChainId
-  const getClient = Viem.createGetClient({ defaultChainId, rpc: options.rpc })
+  const zones = new Map(
+    (options.zones === true ? Zones.chains : (options.zones ?? [])).map((zone) => [zone.id, zone]),
+  )
+  const getClient = Viem.createGetClient({
+    defaultChainId,
+    rpc: options.rpc,
+    zones: [...zones.values()],
+  })
+  const configuredRpcChainIds =
+    typeof options.rpc === 'function' ? [] : Viem.configuredChainIds(options.rpc?.url)
   const supportedChainIds = new Set<number>([
     ...Object.keys(Viem.url).map(Number),
     defaultChainId,
+    ...configuredRpcChainIds,
     ...(options.supportedChainIds ?? []),
+    ...zones.keys(),
   ])
+  const defaultChainRouteHandlers = new Set<unknown>()
 
   // Build the app in two phases: register middleware imperatively, then chain
   // route mounts so the merged Hono schema flows through the return type. The
@@ -242,6 +283,18 @@ export function create<const path extends string = '/'>(options: create.Options<
   // side; `cached` falls back to `source` so consumers never branch.
   const db = 'source' in options.db ? options.db : { source: options.db }
 
+  const providers = (() => {
+    const values = options.providers ?? []
+    const ids = new Set<string>()
+    for (const provider of values) {
+      if (provider.id.length === 0 || provider.id !== provider.id.trim().toLowerCase())
+        throw new InvalidProviderIdError(provider.id)
+      if (ids.has(provider.id)) throw new DuplicateProviderIdError(provider.id)
+      ids.add(provider.id)
+    }
+    return values
+  })()
+
   // Normalize the `analytics` option: accept the bare source or `{ source }`,
   // mirroring `db`. Undefined leaves usage analytics unconfigured (501).
   const analytics =
@@ -269,10 +322,12 @@ export function create<const path extends string = '/'>(options: create.Options<
     c.set('dbCached', db.cached ?? db.source)
     c.set('getClient', (chainId) => getClient(chainId, Auth.getPrincipal(c)))
     c.set('kv', options.kv)
+    c.set('providers', providers)
     c.set('rpc', options.rpc)
     c.set('scopeCatalog', scopeCatalog)
     c.set('store', store)
     c.set('supportedChainIds', supportedChainIds)
+    c.set('zones', zones)
     await next()
   })
 
@@ -299,6 +354,43 @@ export function create<const path extends string = '/'>(options: create.Options<
   // routes. `auth: false` leaves policies unenforced (tests only).
   if (auth.middleware) app.use('*', auth.middleware)
 
+  // Groups marked as default-chain consumers share the root Zone and sandbox
+  // policy without inheriting another group's chain selectors.
+  app.use('*', async (c, next) => {
+    const matched = matchedRoutes(c).some((route) => defaultChainRouteHandlers.has(route.handler))
+    if (!matched) return next()
+
+    const chainId = c.get('chainId')
+    const principal = Auth.getPrincipal(c)
+    if (c.get('zones').has(chainId)) {
+      const scopes = principal?.type === 'api_key' ? principal.apiKey.scopes : undefined
+      const allowed =
+        scopes?.includes(Scope.wildcard) ||
+        scopes?.includes(`zone:${chainId}:read`) ||
+        scopes?.includes(`zone:${chainId}:write`)
+      if (!allowed)
+        return Response.error(c, {
+          code: 'api_key_forbidden',
+          message: `Chain id ${chainId} is a zone. Use an API key granting \`zone:${chainId}:read\` or \`zone:${chainId}:write\`.`,
+          status: 403,
+        })
+    }
+
+    if (
+      principal?.type === 'api_key' &&
+      principal.environment === 'sandbox' &&
+      Viem.isMainnet(chainId)
+    )
+      return Response.error(c, {
+        code: 'api_key_forbidden',
+        message: 'Sandbox API keys only support testnet. Pass a testnet `chainId`.',
+        status: 403,
+      })
+
+    await next()
+    if (c.get('zones').has(chainId)) c.set('edgeCache', undefined)
+  })
+
   // 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`.
@@ -310,6 +402,15 @@ export function create<const path extends string = '/'>(options: create.Options<
       metadata.push(entry)
       for (const chainId of entry.supportedChainIds ?? []) supportedChainIds.add(chainId)
     }
+    if (Metadata.usesDefaultChain(sub))
+      for (const route of sub.routes) {
+        if (route.method === 'ALL') continue
+        defaultChainRouteHandlers.add(route.handler)
+        EdgeCache.setEligibility(
+          route.handler,
+          (c: Context<Environment>) => !c.get('zones').has(c.get('chainId')),
+        )
+      }
     return route(path, sub)
   }) as typeof route
 
@@ -352,7 +453,11 @@ export function create<const path extends string = '/'>(options: create.Options<
       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 ?? [])
+    const tags = [
+      ...new Map(
+        metadata_all.flatMap((m) => (m.tags ?? []).map((tag) => [tag.name, tag] as const)),
+      ).values(),
+    ]
     // 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).
@@ -425,15 +530,15 @@ export function create<const path extends string = '/'>(options: create.Options<
     // 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))
+    OpenApiDocument.applyAccess(generated.paths, Auth.describeAccess(app))
     // Point the `/rpc` operation at the OpenRPC document via `x-openrpc`.
-    applyOpenrpcLink(generated.paths, basePath)
+    OpenApiDocument.applyOpenrpcLink(generated.paths, basePath)
     // Re-order paths so list endpoints appear before get endpoints inside each
     // tag group in the sidebar. We classify by operation summary, which every
     // handler sets as either "List ..." or "Get ...". The reference groups by
     // 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) }
+    return { ...generated, ...webhooksDoc, paths: OpenApiDocument.sortPaths(generated.paths) }
   }
   let finalized = false
   const finalize = () => {
@@ -474,8 +579,8 @@ export function create<const path extends string = '/'>(options: create.Options<
  * Hono type (which `testClient` needs); intersecting the listener onto the
  * app degrades the typed proxy inference.
  */
-export function listener(app: { fetch: NodeFetch }): Listener {
-  return getRequestListener(app.fetch)
+export function listener(app: { fetch: NodeServer.Fetch }): Listener {
+  return NodeServer.getRequestListener(app.fetch)
 }
 
 export declare namespace create {
@@ -507,6 +612,8 @@ export declare namespace create {
     metrics?: Metrics.Metrics | 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
+    /** Providers available to mounted route groups. */
+    providers?: readonly Provider.Provider[] | undefined
     /** Tempo RPC options, including per-request routing by request principal. */
     rpc?: Viem.getClient.Rpc | 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' }]`. */
@@ -515,6 +622,8 @@ export declare namespace create {
     scopes?: readonly Scope.Entry[] | undefined
     /** Extra chain ids served beyond the built-in chains and `defaultChainId`. */
     supportedChainIds?: readonly number[] | undefined
+    /** Zone chains served by this deployment. Pass true to use the hosted Zone list. */
+    zones?: true | readonly Chain[] | undefined
   }
 
   /** KV state-store configuration. */
@@ -612,157 +721,206 @@ async function errorFromException(c: Context<Environment>, cause: HTTPException)
   const response = cause.getResponse()
   response.headers.set('tempo-request-id', requestId)
 
-  if (!isJson(response)) return response
+  if (!ResponseBody.isJson(response)) return response
 
   const body = await response
     .clone()
     .json()
     .catch(() => null)
-  if (!isRecord(body)) return response
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return response
 
   return c.json({ ...body, requestId }, cause.status, Object.fromEntries(response.headers))
 }
 
-// Reorder OpenAPI `paths` so reads come before writes within each tag group,
-// and shallower paths come before deeper paths inside each bucket so root-level
-// routes ("List tokens" — `/tokens`) win over nested ones ("List address
-// tokens" — `/addresses/{address}/tokens`). Tie-break by original document
-// order to keep registered grouping.
-//
-// A path is ranked as a unit because REST groups verbs onto shared paths (and
-// the reference renders all methods of a path adjacently, in the fixed canonical
-// method order GET→POST→PATCH→DELETE), so two operations on the same path can
-// never be separated or reordered relative to each other.
-//
-// Read-only tags keep lists-before-gets (tiers 0/2). The `Webhooks` tag instead
-// groups all reads (lists, then the item GET) ahead of the item writes, scoped
-// to that tag so the read tags are untouched. The shared-path constraint means
-// the desired "Create, all GETs (lists first), Update, Delete" can only be
-// approximated: `Create webhook` shares `/webhooks` with `List webhooks`, and
-// vocs renders GET before POST, so "List webhooks" unavoidably precedes
-// "Create". `Get`/`Update`/`Delete` all share `/webhooks/{id}`, so they render
-// adjacently as Get→Update→Delete. The `{id}` item is tiered right after the
-// collection root, so `Get/Update/Delete` sit just below `List webhooks/Create`,
-// ahead of the remaining lists and action POSTs. Tiers:
-//   0 collection root (`GET`+`POST /webhooks`)        → "List webhooks, Create webhook"
-//   1 item (`GET`+`PATCH`+`DELETE /webhooks/{id}`)    → "Get, Update, Delete"
-//   2 other list-only paths (`/event-types`, `/deliveries`)
-//   3 other writes/actions (`POST .../ping`, `.../retry`)
-function sortPaths(paths: PathsObject): PathsObject {
-  const entries = Object.entries(paths)
-  const rank = (entry: [string, PathItem]) => {
-    const operations = Object.values(entry[1])
-    const summaries = operations.flatMap((op) =>
-      isOperation(op) && op.summary ? [op.summary] : [],
-    )
-    const has = (prefix: string) => summaries.some((summary) => summary.startsWith(prefix))
-    if (operations.some((op) => isOperation(op) && op.tags?.includes('Webhooks'))) {
-      if (has('Create')) return 0
-      if (has('Get')) return 1
-      if (has('List')) return 2
-      return 3
+namespace OpenApiDocument {
+  // Reorder OpenAPI `paths` so reads come before writes within each tag group,
+  // and shallower paths come before deeper paths inside each bucket so root-level
+  // routes ("List tokens" — `/tokens`) win over nested ones ("List address
+  // tokens" — `/addresses/{address}/tokens`). Tie-break by original document
+  // order to keep registered grouping.
+  //
+  // A path is ranked as a unit because REST groups verbs onto shared paths (and
+  // the reference renders all methods of a path adjacently, in the fixed canonical
+  // method order GET→POST→PATCH→DELETE), so two operations on the same path can
+  // never be separated or reordered relative to each other.
+  //
+  // Read-only tags keep lists-before-gets (tiers 0/2). The `Webhooks` tag instead
+  // groups all reads (lists, then the item GET) ahead of the item writes, scoped
+  // to that tag so the read tags are untouched. The shared-path constraint means
+  // the desired "Create, all GETs (lists first), Update, Delete" can only be
+  // approximated: `Create webhook` shares `/webhooks` with `List webhooks`, and
+  // vocs renders GET before POST, so "List webhooks" unavoidably precedes
+  // "Create". `Get`/`Update`/`Delete` all share `/webhooks/{id}`, so they render
+  // adjacently as Get→Update→Delete. The `{id}` item is tiered right after the
+  // collection root, so `Get/Update/Delete` sit just below `List webhooks/Create`,
+  // ahead of the remaining lists and action POSTs. Tiers:
+  //   0 collection root (`GET`+`POST /webhooks`)        → "List webhooks, Create webhook"
+  //   1 item (`GET`+`PATCH`+`DELETE /webhooks/{id}`)    → "Get, Update, Delete"
+  //   2 other list-only paths (`/event-types`, `/deliveries`)
+  //   3 other writes/actions (`POST .../ping`, `.../retry`)
+  // Funding deposit paths preserve their resource-specific sidebar order.
+  const fundingDepositOperationOrder = [
+    'createFundingDepositAddress',
+    'reconcileFundingDepositAddress',
+    'getFundingDepositAddress',
+    'getFundingDeposit',
+    'listFundingDepositAddressDeposits',
+    'listFundingDeposits',
+  ] as const
+
+  export function sortPaths(paths: PathsObject): PathsObject {
+    const entries = Object.entries(paths)
+    const rank = (entry: [string, PathItem]) => {
+      const operations = Object.values(entry[1])
+      const summaries = operations.flatMap((op) =>
+        isOperation(op) && op.summary ? [op.summary] : [],
+      )
+      const has = (prefix: string) => summaries.some((summary) => summary.startsWith(prefix))
+      if (operations.some((op) => isOperation(op) && op.tags?.includes('Webhooks'))) {
+        if (has('Create')) return 0
+        if (has('Get')) return 1
+        if (has('List')) return 2
+        return 3
+      }
+      if (operations.some((op) => isOperation(op) && op.tags?.includes('Deposit Addresses'))) {
+        const index = fundingDepositOperationOrder.findIndex((operationId) =>
+          operations.some((op) => isOperation(op) && op.operationId === operationId),
+        )
+        if (index >= 0) return index
+      }
+      if (/\/v1\/funding(?:\/|$)/.test(entry[0])) {
+        if (has('Create')) return 1
+        if (has('Get transfer')) return 2
+        return 0
+      }
+      if (has('List')) return has('Create') ? 1 : 0
+      if (has('Get')) return 2
+      if (has('Create')) return 3
+      return 4
     }
-    if (has('List')) return has('Create') ? 1 : 0
-    if (has('Get')) return 2
-    if (has('Create')) return 3
-    return 4
+    const depth = (path: string) =>
+      path.endsWith('/rpc') ? 2 : path.split('/').filter(Boolean).length
+    const indexed = entries.map(
+      (entry, index) => [entry, index, rank(entry), depth(entry[0])] as const,
+    )
+    indexed.sort(([, ai, ar, ad], [, bi, br, bd]) => ar - br || ad - bd || ai - bi)
+    return Object.fromEntries(indexed.map(([entry]) => entry))
   }
-  const depth = (path: string) =>
-    path.endsWith('/rpc') ? 2 : path.split('/').filter(Boolean).length
-  const indexed = entries.map(
-    (entry, index) => [entry, index, rank(entry), depth(entry[0])] as const,
-  )
-  indexed.sort(([, ai, ar, ad], [, bi, br, bd]) => ar - br || ad - bd || ai - bi)
-  return Object.fromEntries(indexed.map(([entry]) => entry))
-}
 
-/**
- * Applies route security, required scopes, and payment responses from resolved access lanes.
- * API keys support header, query, and bearer authentication.
- */
-function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAccess>) {
-  for (const item of Object.values(paths)) {
-    for (const op of Object.values(item as Record<string, unknown>)) {
-      if (!isMutableOperation(op)) continue
-      const lanes = access[op.operationId]
-      if (!lanes) continue
-      const security = [
-        ...(lanes.apiKey ? [{ apiKey: [] }, { queryApiKey: [] }, { 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']
+  /**
+   * Applies route security, required scopes, and payment responses from resolved access lanes.
+   * API keys support header, query, and bearer authentication.
+   */
+  export function applyAccess(paths: PathsObject, access: Record<string, Auth.OperationAccess>) {
+    for (const item of Object.values(paths)) {
+      for (const op of Object.values(item as Record<string, unknown>)) {
+        if (!isMutableOperation(op)) continue
+        const lanes = access[op.operationId]
+        if (!lanes) continue
+        const security = [
+          ...(lanes.apiKey ? [{ apiKey: [] }, { queryApiKey: [] }, { 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']
+      }
     }
   }
-}
 
-/**
- * Links the JSON-RPC passthrough operation to the OpenRPC document (served at
- * `{basePath}/openrpc.json`) via an `x-openrpc` vendor extension. The raw `/rpc`
- * request body is opaque to OpenAPI, so this lets consumers discover the
- * method/param/return schemas it accepts.
- *
- * The public `/openapi.json` keeps a URL reference (small, conventional). The
- * 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
-  // trailing slash so the join never doubles up (`//openrpc.json`).
-  const url = `${basePath.replace(/\/$/, '')}/openrpc.json`
-  for (const item of Object.values(paths))
-    for (const op of Object.values(item as Record<string, unknown>))
-      if (isMutableOperation(op) && isRpcOperation(op)) op['x-openrpc'] = url
-}
+  /**
+   * Links the JSON-RPC passthrough operation to the OpenRPC document (served at
+   * `{basePath}/openrpc.json`) via an `x-openrpc` vendor extension. The raw `/rpc`
+   * request body is opaque to OpenAPI, so this lets consumers discover the
+   * method/param/return schemas it accepts.
+   *
+   * The public `/openapi.json` keeps a URL reference (small, conventional). The
+   * docs handler instead inlines the document — see `inlineOpenrpc` in `tapimo/docs`.
+   */
+  export function applyOpenrpcLink(paths: PathsObject, basePath: string) {
+    // `basePath` is `/` at the root mount and `/api` etc. otherwise; strip any
+    // trailing slash so the join never doubles up (`//openrpc.json`).
+    const url = `${basePath.replace(/\/$/, '')}/openrpc.json`
+    for (const item of Object.values(paths))
+      for (const op of Object.values(item as Record<string, unknown>))
+        if (isMutableOperation(op) && isRpcOperation(op)) op['x-openrpc'] = url
+  }
 
-type PathsObject = Awaited<ReturnType<typeof generateSpecs>>['paths']
-type PathItem = PathsObject[string]
-type Operation = { summary?: string | undefined }
-type MutableOperation = {
-  operationId: string
-  responses?: Record<string, unknown> | undefined
-  security?: unknown
-  'x-openrpc'?: unknown
-  'x-required-scopes'?: unknown
-}
+  type PathsObject = Awaited<ReturnType<typeof generateSpecs>>['paths']
+  type PathItem = PathsObject[string]
+  type Operation = { operationId?: string | undefined; summary?: string | undefined }
+  type MutableOperation = {
+    operationId: string
+    responses?: Record<string, unknown> | undefined
+    security?: unknown
+    'x-openrpc'?: unknown
+    'x-required-scopes'?: unknown
+  }
 
-function isRpcOperation(op: MutableOperation) {
-  return op.operationId === 'rpcRequest'
-}
+  function isRpcOperation(op: MutableOperation) {
+    return op.operationId === 'rpcRequest'
+  }
+
+  function isOperation(value: unknown): value is Operation {
+    return !!value && typeof value === 'object' && 'summary' in value
+  }
 
-function isOperation(value: unknown): value is Operation {
-  return !!value && typeof value === 'object' && 'summary' in value
+  function isMutableOperation(value: unknown): value is MutableOperation {
+    return (
+      !!value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      'operationId' in value &&
+      typeof value.operationId === 'string'
+    )
+  }
 }
 
-function isMutableOperation(value: unknown): value is MutableOperation {
-  return isRecord(value) && typeof value['operationId'] === 'string'
+namespace ResponseBody {
+  export function isJson(response: globalThis.Response) {
+    return response.headers.get('content-type')?.includes('application/json') ?? false
+  }
 }
 
-function isJson(response: globalThis.Response) {
-  return response.headers.get('content-type')?.includes('application/json') ?? false
+namespace NodeServer {
+  type GetRequestListener = (typeof import('@hono/node-server'))['getRequestListener']
+  export type Fetch = Parameters<GetRequestListener>[0]
+  type NodeRequestListener = ReturnType<GetRequestListener>
+
+  export function getRequestListener(fetch: Fetch): Listener {
+    let listener: NodeRequestListener | undefined
+    return async (incoming_, outgoing_) => {
+      // Resolve the Node-only adapter at call time. The split specifier keeps
+      // Worker bundlers from eagerly including a server adapter they never run.
+      if (listener === undefined) {
+        const nodeServer = (await import(
+          /* @vite-ignore */ ['@hono', 'node-server'].join('/')
+        )) as typeof import('@hono/node-server')
+        listener = nodeServer.getRequestListener(fetch)
+      }
+      return listener(incoming_ as never, outgoing_ as never)
+    }
+  }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === 'object' && !Array.isArray(value)
+/** Error thrown when an app registers the same provider identifier more than once. */
+export class DuplicateProviderIdError extends Error {
+  override name = 'App.DuplicateProviderIdError'
+
+  constructor(id: string) {
+    super(`Duplicate provider id "${id}".`)
+  }
 }
 
-type GetNodeRequestListener = (typeof import('@hono/node-server'))['getRequestListener']
-type NodeFetch = Parameters<GetNodeRequestListener>[0]
-type NodeRequestListener = ReturnType<GetNodeRequestListener>
-
-function getRequestListener(fetch: NodeFetch): Listener {
-  let listener: NodeRequestListener | undefined
-  return async (incoming_, outgoing_) => {
-    // Resolve the Node-only adapter at call time. The split specifier keeps
-    // Worker bundlers from eagerly including a server adapter they never run.
-    if (listener === undefined) {
-      const nodeServer = (await import(
-        /* @vite-ignore */ ['@hono', 'node-server'].join('/')
-      )) as typeof import('@hono/node-server')
-      listener = nodeServer.getRequestListener(fetch)
-    }
-    return listener(incoming_ as never, outgoing_ as never)
+/** Error thrown when an app registers a provider with a non-normalized identifier. */
+export class InvalidProviderIdError extends Error {
+  override name = 'App.InvalidProviderIdError'
+
+  constructor(id: string) {
+    super(`Invalid provider id "${id}". Provider ids must be lowercase and trimmed.`)
   }
 }