tapimo 0.13.0 → 0.15.0

package/src/App.ts

@@ -15,6 +15,7 @@ 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 core_Email from './internal/Email.js'
 import * as Log from './internal/Log.js'
 import * as MetricSink from './internal/MetricSink.js'
 import type * as Metrics from './Metrics.js'
@@ -26,6 +27,7 @@ import * as Response from './internal/Response.js'
 import * as Scope from './Scope.js'
 import type * 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 type * as Webhooks from './internal/Webhooks.js'
 
@@ -34,21 +36,21 @@ 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 Routes from './apps/routes/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 routes = Routes.routes
 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 Routes API group; see {@link routes}. */
+export type RoutesApp = ReturnType<typeof routes>
 /** The management route group; see {@link management}. */
 export type ManagementApp = ReturnType<typeof management>
 /** The MPP credential relay route group; see {@link mpp}. */
@@ -59,6 +61,7 @@ export type RelayApp = ReturnType<typeof relay>
 /** Hono environment variables set by the Tempo API app. */
 export type Environment = {
   Variables: Auth.Variables &
+    core_Email.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
@@ -72,6 +75,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
+      /** Bounded operational metrics backend, or undefined when metrics are disabled. */
+      metrics: Metrics.Metrics | undefined
       /** Providers registered by the host application. */
       providers: readonly Provider.Provider[]
       /** Issuable API-key scope catalog, including host-defined entries. */
@@ -92,6 +97,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
+      /** Vercel workload-identity policy used for mainnet Zone authorization. */
+      vercelOidc: VercelOidc.create.Policy | undefined
       /** Zone chain ids inferred from the current API key, or undefined for single-chain requests. */
       zoneChainIds: readonly Viem.ChainId[] | undefined
       /** Zone chains keyed by chain id; empty when none are configured. */
@@ -121,7 +128,7 @@ 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('/', routes())
     .route('/', relay())
     .route('/', mpp({ state: Store.memory() }))
     .route('/', management())
@@ -136,14 +143,19 @@ export type Endpoint = Auth.Endpoint<App>
 /** Stripe billing capability for management billing routes; owned by {@link management}. */
 export type Billing = Management.Billing
 
-/** Transactional email sender for management emails; owned by {@link management}. */
-export type Email = Management.Email
+/** Transactional email capability shared by authentication and route groups. */
+export type Email = core_Email.Sender
+
+export declare namespace Email {
+  /** One transactional message. */
+  type Message = core_Email.Message
+}
 
 /** Webhook capability shared by subscription routes and the host poller. */
 export type Webhook = {
   /** Application events produced by the host outside the chain poller. */
   applicationEventTypes?: readonly Webhooks.EventType[] | undefined
-  /** Maximum live (unexpired) subscriptions per owner. Defaults to 100. */
+  /** Maximum live subscriptions per direct owner, shared across API-key organizations created by one user. Defaults to 100. */
   maxPerOwner?: number | undefined
   /** Chain ids the host actively polls for webhook events. */
   supportedChainIds: readonly number[]
@@ -236,14 +248,13 @@ export function create<const path extends string = '/'>(options: create.Options<
   // basePath that would collapse them to an index signature).
   const base = new Hono<Environment>().basePath(basePath)
 
-  if (options.cors !== false)
-    base.use('*', hono_cors(typeof options.cors === 'object' ? options.cors : undefined))
   if (options.compress)
     base.use(
       '*',
       hono_compress(typeof options.compress === 'object' ? options.compress : undefined),
     )
-  base.use('*', requestId())
+  // Billing deduplicates analytics retries by this ID, so callers must never supply it.
+  base.use('*', requestId({ headerName: '' }))
   base.use('*', async (c, next) => {
     await next()
     c.header('tempo-request-id', c.get('requestId'))
@@ -296,6 +307,7 @@ export function create<const path extends string = '/'>(options: create.Options<
     requestTimeoutMs,
     (c) =>
       new HTTPException(504, {
+        message: 'Request timed out',
         res: Response.error(c, {
           code: 'request_timeout',
           message: 'Request timed out',
@@ -340,9 +352,12 @@ export function create<const path extends string = '/'>(options: create.Options<
 
   // Built-in auth: the session surface (mounted last) plus the enforcement
   // middleware (installed below), wired together in `Auth.install`.
+  let email = options.email
   const auth = Auth.install({
     auth: options.auth,
+    basePath,
     db: db.source,
+    email: () => email,
     getClient,
     kv: options.kv,
     scopeCatalog,
@@ -355,13 +370,16 @@ export function create<const path extends string = '/'>(options: create.Options<
     c.set('chainId', defaultChainId)
     c.set('db', db.source)
     c.set('dbCached', db.cached ?? db.source)
+    c.set('email', email)
     c.set('getClient', (chainId) => getClient(chainId, Auth.getPrincipal(c)))
     c.set('kv', options.kv)
+    c.set('metrics', options.metrics)
     c.set('providers', providers)
     c.set('rpc', options.rpc)
     c.set('scopeCatalog', scopeCatalog)
     c.set('store', Store.withRequest(store, c.req, { waitUntil: getWaitUntil(c) }))
     c.set('supportedChainIds', supportedChainIds)
+    c.set('vercelOidc', options.vercelOidc)
     c.set('zones', zones)
     await next()
   })
@@ -376,6 +394,13 @@ export function create<const path extends string = '/'>(options: create.Options<
     c.res.headers.set('Cache-Control', 'no-store')
   })
 
+  // Cached valid keys on API-key routes skip the edge backstop. Cold and
+  // invalid credentials consume it before any KV lookup.
+  if (auth.edgeRateLimit) base.use('*', auth.edgeRateLimit)
+
+  if (options.cors !== false)
+    base.use('*', hono_cors(typeof options.cors === 'object' ? options.cors : undefined))
+
   // Serve GETs from the cache store before user middleware (auth, rate limiting)
   // runs, so cache hits skip the per-request store round-trips that dominate
   // latency.
@@ -397,7 +422,15 @@ export function create<const path extends string = '/'>(options: create.Options<
 
     const chainId = c.get('chainId')
     const principal = Auth.getPrincipal(c)
-    if (c.get('zones').has(chainId)) {
+    const zone = c.get('zones').get(chainId)
+    if (zone) {
+      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) ||
@@ -414,7 +447,7 @@ export function create<const path extends string = '/'>(options: create.Options<
     if (
       principal?.type === 'api_key' &&
       principal.environment === 'sandbox' &&
-      Viem.isMainnet(chainId)
+      Viem.isMainnet(c.get('zones').get(chainId)?.sourceId ?? chainId)
     )
       return Response.error(c, {
         code: 'api_key_forbidden',
@@ -433,6 +466,7 @@ export function create<const path extends string = '/'>(options: create.Options<
   const route = app.route.bind(app)
   ;(app as unknown as { route: typeof route }).route = ((path, sub) => {
     const entry = Metadata.read(sub)
+    email ??= core_Email.read(sub)
     if (entry) {
       metadata.push(entry)
       for (const chainId of entry.supportedChainIds ?? []) supportedChainIds.add(chainId)
@@ -558,14 +592,24 @@ export function create<const path extends string = '/'>(options: create.Options<
       /\/webhooks(\/|$)/.test(path),
     )
     const webhookBlocks = hasWebhookRoutes ? metadata_all.flatMap((m) => (m.webhooks ? [m.webhooks()] : [])) : [] // prettier-ignore
+    const webhookSchemas = Object.assign({}, ...webhookBlocks.map((block) => block.schemas ?? {}))
+    if (Object.keys(webhookSchemas).length) {
+      for (const [name, schema] of Object.entries(webhookSchemas))
+        OpenApiDocument.recoverExamples(schema, generated.components.schemas?.[name], generated)
+      generated.components.schemas = {
+        ...generated.components.schemas,
+        ...webhookSchemas,
+      }
+    }
     const webhooksDoc = webhookBlocks.length
-      ? { webhooks: Object.assign({}, ...webhookBlocks) }
+      ? { webhooks: Object.assign({}, ...webhookBlocks.map((block) => block.document)) }
       : {}
     // 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.
     OpenApiDocument.applyAccess(generated.paths, Auth.describeAccess(app))
+    OpenApiDocument.removePrivateFields(generated.paths)
     // Point the `/rpc` operation at the OpenRPC document via `x-openrpc`.
     OpenApiDocument.applyOpenrpcLink(generated.paths, basePath)
     // Re-order paths so list endpoints appear before get endpoints inside each
@@ -573,7 +617,13 @@ export function create<const path extends string = '/'>(options: create.Options<
     // 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: OpenApiDocument.sortPaths(generated.paths) }
+    const document = {
+      ...generated,
+      ...webhooksDoc,
+      paths: OpenApiDocument.sortPaths(generated.paths),
+    }
+    OpenApiDocument.normalizeExamples(document)
+    return document
   }
   let finalized = false
   const finalize = () => {
@@ -605,7 +655,8 @@ export function create<const path extends string = '/'>(options: create.Options<
     return originalFetch(request, ...rest)
   }) as typeof originalFetch
 
-  return route('/', auth.app ?? new Hono<Environment>())
+  // Preserve the hosted auth client contract when tests disable auth at runtime.
+  return route('/', auth.app ?? (new Hono<Environment>() as NonNullable<typeof auth.app>))
 }
 
 /**
@@ -621,8 +672,7 @@ export function listener(app: { fetch: NodeServer.Fetch }): Listener {
 export declare namespace create {
   /**
    * Options for creating the Tempo API Hono app: shared chain, RPC, database,
-   * cache, authentication, and cross-cutting configuration. Email belongs to
-   * {@link management}.
+   * cache, authentication, and cross-cutting configuration.
    */
   type Options<path extends string = '/'> = {
     /** 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`). */
@@ -639,6 +689,8 @@ export declare namespace create {
     db: Db.Source | { cached?: Db.Source | undefined; source: Db.Source }
     /** Default Tempo chain id for requests that omit `chainId`. */
     defaultChainId?: Viem.ChainId | undefined
+    /** Transactional email sender shared by authentication and mounted route groups. */
+    email?: Email | 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
     /** 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. */
@@ -657,6 +709,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
+    /** Vercel workload-identity verifier for mainnet Zone shadow evaluation. */
+    vercelOidc?: VercelOidc.create.Policy | undefined
     /** Zone chains served by this deployment. Pass true to use the hosted Zone list. */
     zones?: true | readonly Chain[] | undefined
   }
@@ -725,11 +779,19 @@ export declare namespace create {
     /** 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
+    webhooks?: (() => Webhooks) | undefined
     /** Vocs tag-group metadata for grouping root tags in the reference. */
     'x-tagGroups'?: readonly TagGroup[] | undefined
   }
 
+  /** Root webhooks document and schemas contributed by one route group. */
+  type Webhooks = {
+    /** Root `webhooks` entries keyed by event name. */
+    document: Record<string, unknown>
+    /** Named schemas referenced only from outbound webhook operations. */
+    schemas?: Record<string, unknown> | undefined
+  }
+
   /** One root-level OpenAPI tag definition. */
   type Tag = {
     /** Human-readable summary shown in the reference sidebar. */
@@ -772,6 +834,247 @@ async function errorFromException(c: Context<Environment>, cause: HTTPException)
 }
 
 namespace OpenApiDocument {
+  /** Copies examples from an equivalent input schema into its output representation. */
+  export function recoverExamples(target: unknown, source: unknown, root: unknown) {
+    if (!target || typeof target !== 'object' || Array.isArray(target)) return
+    if (!source || typeof source !== 'object' || Array.isArray(source)) return
+
+    const current = target as Record<string, unknown>
+    const source_raw = source as Record<string, unknown>
+    const source_resolved = (() => {
+      if (typeof source_raw['$ref'] !== 'string') return source_raw
+      const resolved = resolvePointer(root, source_raw['$ref'])
+      return resolved && typeof resolved === 'object' && !Array.isArray(resolved)
+        ? (resolved as Record<string, unknown>)
+        : source_raw
+    })()
+    const source_aligned = (() => {
+      for (const name of ['anyOf', 'oneOf']) {
+        const branches = source_resolved[name]
+        if (!Array.isArray(branches)) continue
+        for (const branch of branches) {
+          if (!branch || typeof branch !== 'object' || Array.isArray(branch)) continue
+          const candidate = branch as Record<string, unknown>
+          const resolved = (() => {
+            if (typeof candidate['$ref'] !== 'string') return candidate
+            const value = resolvePointer(root, candidate['$ref'])
+            return value && typeof value === 'object' && !Array.isArray(value)
+              ? (value as Record<string, unknown>)
+              : candidate
+          })()
+          if (
+            (current['type'] !== undefined && current['type'] === resolved['type']) ||
+            ('properties' in current && 'properties' in resolved) ||
+            ('items' in current && 'items' in resolved)
+          )
+            return resolved
+        }
+      }
+      return source_resolved
+    })()
+    if (!('example' in current) && 'example' in source_aligned)
+      current['example'] = source_aligned['example']
+    if (!('examples' in current) && 'examples' in source_aligned)
+      current['examples'] = source_aligned['examples']
+
+    const targetProperties = current['properties'] as Record<string, unknown> | undefined
+    const sourceProperties = source_aligned['properties'] as Record<string, unknown> | undefined
+    if (targetProperties && sourceProperties)
+      for (const [name, child] of Object.entries(targetProperties))
+        recoverExamples(child, sourceProperties[name], root)
+
+    if (current['items']) recoverExamples(current['items'], source_aligned['items'], root)
+    for (const name of ['allOf', 'anyOf', 'oneOf']) {
+      const targets = current[name]
+      const sources = source_aligned[name]
+      if (!Array.isArray(targets) || !Array.isArray(sources)) continue
+      for (const [index, child] of targets.entries()) recoverExamples(child, sources[index], root)
+    }
+  }
+
+  /** Publishes literal examples and propagates schema examples through nested representations. */
+  export function normalizeExamples(value: unknown) {
+    normalize(value, value)
+  }
+
+  function normalize(value: unknown, root: unknown, inherited: readonly unknown[] = []) {
+    if (!value || typeof value !== 'object') return
+    if (Array.isArray(value)) {
+      for (const item of value) normalize(item, root, inherited)
+      return
+    }
+
+    const current = value as Record<string, unknown>
+    const compatible = inherited.filter((example) => matchesSchemaType(current, example))
+    if (!('example' in current) && !('examples' in current)) {
+      if ('const' in current) current['examples'] = [current['const']]
+      else if (Array.isArray(current['enum']) && current['enum'].length)
+        current['examples'] = [current['enum'][0]]
+      else if (compatible.length) current['examples'] = [...new Set(compatible)]
+    }
+    const examples = [
+      ...('example' in current ? [current['example']] : []),
+      ...(Array.isArray(current['examples']) ? current['examples'] : []),
+    ]
+    const properties = current['properties'] as Record<string, unknown> | undefined
+    if (properties)
+      for (const [name, child] of Object.entries(properties))
+        normalize(
+          child,
+          root,
+          examples.flatMap((example) => {
+            if (!example || typeof example !== 'object' || Array.isArray(example)) return []
+            return name in example ? [(example as Record<string, unknown>)[name]] : []
+          }),
+        )
+    if (current['items'])
+      normalize(
+        current['items'],
+        root,
+        examples.flatMap((example) => (Array.isArray(example) ? example : [])),
+      )
+    // Composition branches may share a JSON type while accepting different
+    // values. Keep inherited examples on the union instead of copying invalid
+    // values into each representation.
+    for (const name of ['allOf', 'anyOf', 'oneOf'])
+      if (current[name]) normalize(current[name], root)
+    for (const [name, child] of Object.entries(current))
+      if (!['allOf', 'anyOf', 'example', 'examples', 'items', 'oneOf', 'properties'].includes(name))
+        normalize(child, root)
+
+    if (!('$ref' in current) && !('example' in current) && !('examples' in current)) {
+      const [found, example] = deriveExample(root, current)
+      if (found) current['examples'] = [example]
+    }
+  }
+
+  type DerivedExample = readonly [found: boolean, value: unknown]
+
+  function deriveExample(
+    root: unknown,
+    schema: Record<string, unknown>,
+    seen: ReadonlySet<string> = new Set(),
+  ): DerivedExample {
+    if ('example' in schema) return [true, schema['example']]
+    if (Array.isArray(schema['examples']) && schema['examples'].length)
+      return [true, schema['examples'][0]]
+
+    const schemaLike = [
+      '$ref',
+      'allOf',
+      'anyOf',
+      'const',
+      'enum',
+      'items',
+      'oneOf',
+      'properties',
+      'type',
+    ].some((name) => name in schema)
+    if (!schemaLike) return [false, undefined]
+
+    if ('const' in schema) return [true, schema['const']]
+    if (Array.isArray(schema['enum']) && schema['enum'].length) return [true, schema['enum'][0]]
+    if ('default' in schema) return [true, schema['default']]
+
+    if (typeof schema['$ref'] === 'string' && !seen.has(schema['$ref'])) {
+      const target = resolvePointer(root, schema['$ref'])
+      if (target && typeof target === 'object' && !Array.isArray(target))
+        return deriveExample(
+          root,
+          target as Record<string, unknown>,
+          new Set([...seen, schema['$ref']]),
+        )
+    }
+
+    for (const name of ['oneOf', 'anyOf'])
+      if (Array.isArray(schema[name]))
+        for (const branch of schema[name]) {
+          if (!branch || typeof branch !== 'object' || Array.isArray(branch)) continue
+          const result = deriveExample(root, branch as Record<string, unknown>, seen)
+          if (result[0]) return result
+        }
+
+    if (Array.isArray(schema['allOf'])) {
+      const merged: Record<string, unknown> = {}
+      let found = false
+      for (const branch of schema['allOf']) {
+        if (!branch || typeof branch !== 'object' || Array.isArray(branch)) continue
+        const result = deriveExample(root, branch as Record<string, unknown>, seen)
+        if (!result[0] || !result[1] || typeof result[1] !== 'object' || Array.isArray(result[1]))
+          continue
+        Object.assign(merged, result[1])
+        found = true
+      }
+      if (found) return [true, merged]
+    }
+
+    if (schema['type'] === 'array' && schema['items']) {
+      const items = schema['items']
+      if (items && typeof items === 'object' && !Array.isArray(items)) {
+        const result = deriveExample(root, items as Record<string, unknown>, seen)
+        if (result[0]) return [true, [result[1]]]
+      }
+    }
+
+    const properties = schema['properties']
+    if (properties && typeof properties === 'object' && !Array.isArray(properties)) {
+      const example: Record<string, unknown> = {}
+      const required = new Set(Array.isArray(schema['required']) ? schema['required'] : [])
+      for (const [name, property] of Object.entries(properties)) {
+        if (!required.has(name)) continue
+        if (!property || typeof property !== 'object' || Array.isArray(property)) continue
+        const result = deriveExample(root, property as Record<string, unknown>, seen)
+        if (result[0]) example[name] = result[1]
+        else return [false, undefined]
+      }
+      return [true, example]
+    }
+
+    if (schema['type'] === 'object') return [true, {}]
+
+    return [false, undefined]
+  }
+
+  function resolvePointer(root: unknown, pointer: string) {
+    if (!pointer.startsWith('#/')) return undefined
+    return pointer
+      .slice(2)
+      .split('/')
+      .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+      .reduce<unknown>((value, part) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+        return (value as Record<string, unknown>)[part]
+      }, root)
+  }
+
+  function matchesSchemaType(schema: Record<string, unknown>, value: unknown) {
+    switch (schema['type']) {
+      case 'array':
+        return Array.isArray(value)
+      case 'boolean':
+        return typeof value === 'boolean'
+      case 'integer':
+        return typeof value === 'number' && Number.isInteger(value)
+      case 'null':
+        return value === null
+      case 'number':
+        return typeof value === 'number'
+      case 'object':
+        return !!value && typeof value === 'object' && !Array.isArray(value)
+      case 'string':
+        return typeof value === 'string'
+      default:
+        return true
+    }
+  }
+
+  /** Removes route-composition metadata that is not part of an OpenAPI operation. */
+  export function removePrivateFields(paths: PathsObject) {
+    for (const item of Object.values(paths))
+      for (const op of Object.values(item as Record<string, unknown>))
+        if (isMutableOperation(op)) delete op.hide
+  }
+
   // 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
@@ -797,13 +1100,13 @@ namespace OpenApiDocument {
   //   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',
-    'listFundingDeposits',
+  // Route deposit paths preserve their resource-specific sidebar order.
+  const routesDepositOperationOrder = [
+    'createRoutesDepositAddress',
+    'reconcileRoutesDepositAddress',
+    'getRoutesDepositAddress',
+    'getRoutesDeposit',
+    'listRoutesDeposits',
   ] as const
 
   export function sortPaths(paths: PathsObject): PathsObject {
@@ -821,12 +1124,12 @@ namespace OpenApiDocument {
         return 3
       }
       if (operations.some((op) => isOperation(op) && op.tags?.includes('Deposit Addresses'))) {
-        const index = fundingDepositOperationOrder.findIndex((operationId) =>
+        const index = routesDepositOperationOrder.findIndex((operationId) =>
           operations.some((op) => isOperation(op) && op.operationId === operationId),
         )
         if (index >= 0) return index
       }
-      if (/\/v1\/funding(?:\/|$)/.test(entry[0])) {
+      if (/\/v1\/routes(?:\/|$)/.test(entry[0])) {
         if (has('Create')) return 1
         if (has('Get transfer')) return 2
         return 0
@@ -862,7 +1165,7 @@ namespace OpenApiDocument {
             : []),
           ...(lanes.public ? [{}] : []),
         ]
-        if (security.length > 0) op.security = security
+        if (security.length > 0 || lanes.bypass) 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']
@@ -873,8 +1176,8 @@ namespace OpenApiDocument {
   /**
    * 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.
+   * schemas in OpenAPI are generic, so this lets consumers discover each
+   * method's specific parameter and return schemas.
    *
    * The public `/openapi.json` keeps a URL reference (small, conventional). The
    * docs handler instead inlines the document — see `inlineOpenrpc` in `tapimo/docs`.
@@ -892,6 +1195,7 @@ namespace OpenApiDocument {
   type PathItem = PathsObject[string]
   type Operation = { operationId?: string | undefined; summary?: string | undefined }
   type MutableOperation = {
+    hide?: boolean | undefined
     operationId: string
     responses?: Record<string, unknown> | undefined
     security?: unknown

package/src/Assets.test.ts

@@ -9,10 +9,10 @@ describe('url', () => {
     } as const
 
     expect(Assets.url(options)).toBe(
-      'https://api.tempo.xyz/assets/4217/icons/0x20c000000000000000000000b9537d11c60e8b50',
+      'https://api.tempo.xyz/assets/4217/icons/0x20c000000000000000000000b9537d11c60e8b50?__response=svg-sandbox-v1',
     )
     expect(Assets.url({ ...options, basePath: '/api/' })).toBe(
-      'https://api.tempo.xyz/api/assets/4217/icons/0x20c000000000000000000000b9537d11c60e8b50',
+      'https://api.tempo.xyz/api/assets/4217/icons/0x20c000000000000000000000b9537d11c60e8b50?__response=svg-sandbox-v1',
     )
   })
 })

package/src/Assets.ts

@@ -6,6 +6,8 @@
  * (`Admin.create`'s `assets`, read + write).
  */
 
+import * as AssetResponse from './internal/AssetResponse.js'
+
 /** A static asset: its bytes plus content type. */
 export type Asset = {
   /** Asset bytes. */
@@ -29,7 +31,7 @@ export function url(options: url.Options) {
   const basePath = options.basePath?.replace(/^\/+|\/+$/g, '')
   const path = options.path.replace(/^\/+/, '')
   const pathname = [basePath, 'assets', String(options.chainId), path].filter(Boolean).join('/')
-  return new URL(`/${pathname}`, options.origin).toString()
+  return AssetResponse.versionUrl(new URL(`/${pathname}`, options.origin).toString())
 }
 
 export declare namespace url {

package/src/Auth.test-d.ts

@@ -1,7 +1,7 @@
 import { Hono } from 'hono'
 import { testClient } from 'hono/testing'
 import { expectTypeOf } from 'vite-plus/test'
-import { App, Auth } from 'tapimo'
+import { App, Auth } from 'tapimo/server'
 
 describe('Auth', () => {
   test('exports the external route-authoring surface', () => {