tapimo 0.7.0 → 0.7.2

package/src/App.ts

@@ -5,6 +5,7 @@ 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 +19,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,6 +29,7 @@ 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 Management from './apps/management/App.js'
 import * as Mpp from './apps/mpp/App.js'
@@ -62,6 +65,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 +85,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 &
@@ -108,7 +113,7 @@ function compose(options: create.Options) {
   return create(options)
     .route('/', data())
     .route('/', relay())
-    .route('/', mpp())
+    .route('/', mpp({ state: Store.memory() }))
     .route('/', management())
 }
 
@@ -141,10 +146,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,11 +193,22 @@ 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(),
   ])
 
   // Build the app in two phases: register middleware imperatively, then chain
@@ -242,6 +276,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 +315,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()
   })
 
@@ -425,15 +473,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 +522,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 +555,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 +565,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 +664,192 @@ 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` keeps discovery reads first, then groups its three create operations;
+  // the collection list precedes create because both share one path.
+  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('Funding'))) {
+        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 = { 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.`)
   }
 }

package/src/Assets.ts

@@ -18,6 +18,8 @@ export type Asset = {
 export type Assets = {
   /** Reads an asset by `key`, or `undefined` when absent. */
   get(key: string): Promise<Asset | undefined>
+  /** Lists asset keys matching `prefix`, when the backend supports enumeration. */
+  list?: ((prefix: string) => Promise<readonly string[]>) | undefined
   /** Stores an asset at `key`, replacing any existing object. Omit for read-only stores. */
   put?: ((key: string, asset: Asset) => Promise<void>) | undefined
 }
@@ -26,9 +28,6 @@ export type Assets = {
 export function cloudflareR2(bucket: cloudflareR2.Bucket): Assets {
   return {
     async get(key) {
-      // Legacy source-extension aliases may sort before the extensionless key.
-      const { objects } = await bucket.list({ limit: 1_000, prefix: key })
-      if (!objects.some((object) => object.key === key)) return undefined
       const object = await bucket.get(key)
       if (!object) return undefined
       return {
@@ -36,6 +35,21 @@ export function cloudflareR2(bucket: cloudflareR2.Bucket): Assets {
         contentType: object.httpMetadata?.contentType ?? 'application/octet-stream',
       }
     },
+    async list(prefix) {
+      const keys: string[] = []
+      let cursor: string | undefined
+      for (;;) {
+        const page = await bucket.list({
+          ...(cursor === undefined ? {} : { cursor }),
+          limit: 1_000,
+          prefix,
+        })
+        keys.push(...page.objects.map((object) => object.key))
+        if (!page.truncated) return keys
+        if (!page.cursor) throw new Error('R2 returned a truncated asset list without a cursor.')
+        cursor = page.cursor
+      }
+    },
     put: (key, { body, contentType }) =>
       bucket.put(key, body, { httpMetadata: { contentType } }).then(() => undefined),
   }
@@ -52,9 +66,20 @@ export declare namespace cloudflareR2 {
       httpMetadata?: { contentType?: string | undefined } | undefined
     } | null>
     /** Lists objects matching a key prefix. */
-    list(options: { limit: number; prefix: string }): Promise<{
+    list(options: {
+      /** Continues a previous truncated listing. */
+      cursor?: string | undefined
+      /** Maximum objects returned in one page. */
+      limit: number
+      /** Object-key prefix to match. */
+      prefix: string
+    }): Promise<{
+      /** Cursor for the next page. */
+      cursor?: string | undefined
       /** Matching objects. */
       objects: readonly { key: string }[]
+      /** Whether more matching objects remain. */
+      truncated: boolean
     }>
     /** Writes an object. */
     put(