tapimo 0.7.0 → 0.7.2

package/src/db/tables/sponsoredTransactions.ts

@@ -1,4 +1,4 @@
-import type { ExpressionBuilder, Selectable } from 'kysely'
+import type { ExpressionBuilder, Selectable, SqlBool } from 'kysely'
 import { sql } from 'kysely'
 
 import * as Id from '../../internal/Id.js'
@@ -11,6 +11,9 @@ export type Table = db_Schema.SponsoredTransaction
 /** A stored sponsored-transaction row. */
 export type Record = Selectable<Table>
 
+/** How long failed fill intents remain eligible for on-chain reconciliation. */
+export const failedIntentRecoveryTtlMs = 86_400_000
+
 /**
  * Records one sponsorship commitment as `pending`, keyed by its fee-payer
  * sign payload. Written after fee-payer signing and before any broadcast, so
@@ -37,7 +40,7 @@ export async function upsert(db: Db.Db, input: upsert.Input): Promise<Record> {
     id: Id.generate('stx'),
     meterReportedAt: null,
     orgId: input.orgId,
-    projectId: input.projectId,
+    projectId: input.projectId ?? null,
     signPayload: input.signPayload,
     status: 'pending',
     transaction: input.transaction,
@@ -92,8 +95,8 @@ export declare namespace upsert {
     feeToken?: string | undefined
     /** Organization id (`org_…`) the spend attributes to. */
     orgId: string
-    /** Project id (`prj_…`) the spend attributes to. */
-    projectId: string
+    /** Project id (`prj_…`) the spend attributes to; omit for organization-level spend. */
+    projectId?: string | undefined
     /** Fee-payer sign payload — a stable identity for the sponsored envelope. */
     signPayload: string
     /** Serialized sponsored transaction, kept for observability beyond log retention. */
@@ -199,9 +202,15 @@ export async function assignTransactionHash(
         !['failed', 'pending'].includes(record.status)
       )
         return
+      const failedSince = new Date(Date.now() - failedIntentRecoveryTtlMs).toISOString()
+      if (
+        record.status === 'failed' &&
+        (record.finalizedAt === null || record.finalizedAt < failedSince)
+      )
+        return
       if (record.status === 'failed' && record.billable && limit)
         await sql`select pg_advisory_xact_lock(${billingLockClass}, hashtext(${record.orgId}))`.execute(tx.kysely) // prettier-ignore
-      await tx.kysely
+      let query = tx.kysely
         .updateTable('sponsored_transactions')
         .set({
           ...(record.status === 'failed' ? { createdAt: new Date().toISOString() } : {}),
@@ -212,7 +221,10 @@ export async function assignTransactionHash(
         .where('id', '=', id)
         .where('status', '=', record.status)
         .where('transactionHash', 'is', null)
-        .execute()
+      if (record.status === 'failed')
+        query = query.where(sql<SqlBool>`exists (select 1 from organizations where organizations.id = sponsored_transactions.org_id)`) // prettier-ignore
+      const updated = await query.executeTakeFirst()
+      if (updated.numUpdatedRows === 0n) return
       if (record.status === 'failed' && record.billable && limit) {
         const committed = await spend(tx, {
           chainIds: limit.chainIds,

package/src/db/tables/users.ts

@@ -21,6 +21,22 @@ export function get(db: Db.Db, id: string): Promise<Record | undefined> {
   return db.kysely.selectFrom('users').selectAll().where('id', '=', id).executeTakeFirst()
 }
 
+/**
+ * Reads users by id for operational identity displays.
+ *
+ * @param db - The database.
+ * @param ids - User ids to read.
+ * @returns Matching user records.
+ */
+export function listByIds(db: Db.Db, ids: readonly string[]): Promise<Record[]> {
+  if (ids.length === 0) return Promise.resolve([])
+  return db.kysely
+    .selectFrom('users')
+    .selectAll()
+    .where('id', 'in', [...ids])
+    .execute()
+}
+
 /**
  * Reads a user by wallet address (compared lowercase).
  *

package/src/db/tables/verifiedTokens.ts

@@ -1,21 +1,24 @@
-import type { Selectable } from 'kysely'
+import type { ColumnType } from 'kysely'
 import type { Hex } from 'ox'
 
 import type * as VerifiedTokens from '../../internal/VerifiedTokens.js'
 import type * as Db from '../Db.js'
 import type * as db_Schema from '../Schema.js'
 
-/** Columns of the `verified_tokens` table, derived from `Schema.VerifiedToken`. */
-export type Table = db_Schema.VerifiedToken
+/** A bigint chain id, read as a string from pg and written as a number. */
+type ChainId = ColumnType<string, number, number>
 
-/** Columns of the `verified_token_lists` table, derived from `Schema.VerifiedTokenList`. */
-export type ListTable = db_Schema.VerifiedTokenList
+/** Columns of the `verified_tokens` table. */
+export type Table = Omit<db_Schema.VerifiedToken, 'chainId'> & { chainId: ChainId }
+
+/** Columns of the `verified_token_lists` table. */
+export type ListTable = Omit<db_Schema.VerifiedTokenList, 'chainId'> & { chainId: ChainId }
 
 /** A stored verified-token row. */
-export type Row = Selectable<Table>
+export type Row = db_Schema.VerifiedToken
 
 /** A chain's list-level metadata. */
-export type Meta = Selectable<ListTable>
+export type Meta = db_Schema.VerifiedTokenList
 
 /**
  * Reads a chain's list metadata — the "head" the soft-refresh cache compares
@@ -25,12 +28,13 @@ export type Meta = Selectable<ListTable>
  * @param chainId - The chain id.
  * @returns The metadata, or `undefined` when the chain has no list yet.
  */
-export function head(db: Db.Db, chainId: number): Promise<Meta | undefined> {
-  return db.kysely
+export async function head(db: Db.Db, chainId: number): Promise<Meta | undefined> {
+  const row = await db.kysely
     .selectFrom('verified_token_lists')
     .selectAll()
-    .where('chainId', '=', chainId)
+    .where('chainId', '=', String(chainId))
     .executeTakeFirst()
+  return row ? { ...row, chainId: Number(row.chainId) } : undefined
 }
 
 /**
@@ -40,13 +44,14 @@ export function head(db: Db.Db, chainId: number): Promise<Meta | undefined> {
  * @param chainId - The chain id.
  * @returns The rows.
  */
-export function list(db: Db.Db, chainId: number): Promise<Row[]> {
-  return db.kysely
+export async function list(db: Db.Db, chainId: number): Promise<Row[]> {
+  const rows = await db.kysely
     .selectFrom('verified_tokens')
     .selectAll()
-    .where('chainId', '=', chainId)
+    .where('chainId', '=', String(chainId))
     .orderBy('position')
     .execute()
+  return rows.map((row) => ({ ...row, chainId: Number(row.chainId) }))
 }
 
 /**
@@ -59,7 +64,7 @@ export function list(db: Db.Db, chainId: number): Promise<Row[]> {
  * @param input - The validated list and its new version metadata.
  */
 export async function publish(db: Db.Db, chainId: number, input: publish.Input): Promise<void> {
-  await db.kysely.deleteFrom('verified_tokens').where('chainId', '=', chainId).execute()
+  await db.kysely.deleteFrom('verified_tokens').where('chainId', '=', String(chainId)).execute()
   if (input.tokens.length > 0)
     await db.kysely
       .insertInto('verified_tokens')

package/src/db/tables/webhookSubscriptions.ts

@@ -46,8 +46,13 @@ export function toSubscription(row: Record): Webhooks.Subscription {
  *
  * @param db - The database.
  * @param subscription - The subscription to insert.
+ * @param options - Initial cursor options.
  */
-export async function insert(db: Db.Db, subscription: Webhooks.Subscription): Promise<void> {
+export async function insert(
+  db: Db.Db,
+  subscription: Webhooks.Subscription,
+  options: insert.Options = {},
+): Promise<void> {
   await db.kysely
     .insertInto('webhook_subscriptions')
     .values({
@@ -63,7 +68,7 @@ export async function insert(db: Db.Db, subscription: Webhooks.Subscription): Pr
       lastDeliveryAt: subscription.lastDeliveryAt ?? null,
       ownerId: ownerId(subscription.owner),
       ownerType: subscription.owner.type,
-      pollerCursor: null,
+      pollerCursor: options.pollerCursor ?? null,
       secret: subscription.secret,
       status: subscription.status,
       updatedAt: subscription.updatedAt,
@@ -71,6 +76,14 @@ export async function insert(db: Db.Db, subscription: Webhooks.Subscription): Pr
     .execute()
 }
 
+export declare namespace insert {
+  /** Options for {@link insert}. */
+  type Options = {
+    /** Initial poller cursor committed with the subscription. */
+    pollerCursor?: string | undefined
+  }
+}
+
 /**
  * Inserts a subscription when its owner remains below the configured cap.
  * An owner-scoped transaction lock serializes the count and insert.
@@ -85,7 +98,11 @@ export async function insertWithinLimit(
     await sql`select pg_advisory_xact_lock(${subscriptionLimitLockClass}, hashtext(${owner}))`.execute(tx.kysely) // prettier-ignore
     const existing = await count(tx, subscription.owner, options.now)
     if (existing >= options.maxPerOwner) return false
-    await insert(tx, subscription)
+    await insert(
+      tx,
+      subscription,
+      options.pollerCursor === undefined ? {} : { pollerCursor: options.pollerCursor },
+    )
     return true
   })
 }
@@ -97,6 +114,8 @@ export declare namespace insertWithinLimit {
     maxPerOwner: number
     /** ISO timestamp used to exclude expired rows from the count. */
     now: string
+    /** Initial poller cursor committed with the subscription. */
+    pollerCursor?: string | undefined
   }
 }
 
@@ -312,6 +331,42 @@ export async function setCursor(db: Db.Db, id: string, cursor: string): Promise<
     .execute()
 }
 
+/**
+ * Writes a poller cursor only when the stored cursor still matches the caller's
+ * observed value.
+ *
+ * @param db - The database.
+ * @param options - Subscription, expected cursor, and next cursor.
+ * @returns Whether the cursor was updated.
+ */
+export async function compareAndSetCursor(
+  db: Db.Db,
+  options: compareAndSetCursor.Options,
+): Promise<boolean> {
+  let query = db.kysely
+    .updateTable('webhook_subscriptions')
+    .set({ pollerCursor: options.cursor })
+    .where('id', '=', options.subscriptionId)
+  query =
+    options.expectedCursor === null
+      ? query.where('pollerCursor', 'is', null)
+      : query.where('pollerCursor', '=', options.expectedCursor)
+  const result = await query.executeTakeFirst()
+  return result.numUpdatedRows > 0n
+}
+
+export declare namespace compareAndSetCursor {
+  /** Options for {@link compareAndSetCursor}. */
+  type Options = {
+    /** Next keyset cursor. */
+    cursor: string
+    /** Cursor observed before scanning, or null for an uninitialized subscription. */
+    expectedCursor: string | null
+    /** Subscription whose cursor advances. */
+    subscriptionId: string
+  }
+}
+
 /**
  * Records a successful delivery: resets the consecutive-failure counter and
  * stamps `lastDeliveryAt`.

package/src/handlers/relay.test.ts

@@ -1,3 +1,5 @@
+/** @module-tag localnet */
+
 import type { RpcRequest } from 'ox'
 import { SignatureEnvelope, TxEnvelopeTempo } from 'ox/tempo'
 import { parseUnits, type Address, type BaseError } from 'viem'

package/src/handlers/relay.ts

@@ -152,7 +152,7 @@ export function relay(options: relay.Options = {}): Handler {
               : undefined
           const externalFeePayerUrl =
             typeof parameters['feePayer'] === 'string'
-              ? normalizeExternalFeePayerUrl(parameters['feePayer'], {
+              ? ExternalFeePayerUrl.normalize(parameters['feePayer'], {
                   allowUnsafe: internal_allowUnsafeUrls,
                 })
               : undefined
@@ -1563,118 +1563,114 @@ function mergeCallsFromRequest(
   return merged
 }
 
-/** Normalizes external fee-payer relay URLs before forwarding fill payloads. */
-function normalizeExternalFeePayerUrl(
-  value: string,
-  options: normalizeExternalFeePayerUrl.Options = {},
-): string {
-  let url: URL
-  try {
-    url = new URL(value)
-  } catch {
-    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL.' })
-  }
-
-  const allowUnsafe = options.allowUnsafe === true
-  if (url.protocol !== 'http:' && url.protocol !== 'https:')
-    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
-  if (!allowUnsafe && url.protocol !== 'https:')
-    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
-  if (!allowUnsafe && isUnsafeHostname(url.hostname))
-    throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL host.' })
-
-  url.username = ''
-  url.password = ''
-  url.hash = ''
-  return url.href
-}
-
-declare namespace normalizeExternalFeePayerUrl {
+namespace ExternalFeePayerUrl {
   type Options = {
     /** Whether to allow non-HTTPS or local/private external fee payer URLs. */
     allowUnsafe?: boolean | undefined
   }
-}
 
-function isUnsafeHostname(hostname: string): boolean {
-  const host = normalizeHostname(hostname)
-  if (host === 'localhost' || host.endsWith('.localhost')) return true
-  const ipv4 = parseIpv4(host)
-  if (ipv4) return isUnsafeIpv4(ipv4)
-  if (!host.includes(':')) return false
-  const ipv6 = parseIpv6(host)
-  if (!ipv6) return true
-  return isUnsafeIpv6(ipv6)
-}
+  /** Normalizes external fee-payer relay URLs before forwarding fill payloads. */
+  export function normalize(value: string, options: Options = {}): string {
+    let url: URL
+    try {
+      url = new URL(value)
+    } catch {
+      throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL.' })
+    }
 
-function normalizeHostname(hostname: string): string {
-  return hostname
-    .toLowerCase()
-    .replace(/^\[|\]$/g, '')
-    .split('%')[0]!
-}
+    const allowUnsafe = options.allowUnsafe === true
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+      throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
+    if (!allowUnsafe && url.protocol !== 'https:')
+      throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL protocol.' })
+    if (!allowUnsafe && isUnsafeHostname(url.hostname))
+      throw new RpcResponse.InvalidParamsError({ message: 'Invalid fee payer URL host.' })
+
+    url.username = ''
+    url.password = ''
+    url.hash = ''
+    return url.href
+  }
 
-function parseIpv4(value: string): [number, number, number, number] | undefined {
-  const parts = value.split('.')
-  if (parts.length !== 4 || parts.some((part) => !/^\d+$/.test(part))) return undefined
-  const numbers = parts.map((part) => Number(part))
-  if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return undefined
-  return numbers as [number, number, number, number]
-}
+  function isUnsafeHostname(hostname: string): boolean {
+    const host = normalizeHostname(hostname)
+    if (host === 'localhost' || host.endsWith('.localhost')) return true
+    const ipv4 = parseIpv4(host)
+    if (ipv4) return isUnsafeIpv4(ipv4)
+    if (!host.includes(':')) return false
+    const ipv6 = parseIpv6(host)
+    if (!ipv6) return true
+    return isUnsafeIpv6(ipv6)
+  }
 
-function isUnsafeIpv4(parts: [number, number, number, number]): boolean {
-  const [a, b] = parts
-  if (a === 0 || a === 10 || a === 127) return true
-  if (a === 100 && b >= 64 && b <= 127) return true
-  if (a === 169 && b === 254) return true
-  if (a === 172 && b >= 16 && b <= 31) return true
-  if (a === 192 && b === 168) return true
-  if (a >= 224) return true
-  return false
-}
+  function normalizeHostname(hostname: string): string {
+    return hostname
+      .toLowerCase()
+      .replace(/^\[|\]$/g, '')
+      .split('%')[0]!
+  }
 
-function parseIpv6(
-  value: string,
-): [number, number, number, number, number, number, number, number] | undefined {
-  const halves = value.split('::')
-  if (halves.length > 2) return undefined
+  function parseIpv4(value: string): [number, number, number, number] | undefined {
+    const parts = value.split('.')
+    if (parts.length !== 4 || parts.some((part) => !/^\d+$/.test(part))) return undefined
+    const numbers = parts.map((part) => Number(part))
+    if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return undefined
+    return numbers as [number, number, number, number]
+  }
 
-  const left = halves[0] ? halves[0].split(':') : []
-  const right = halves[1] ? halves[1].split(':') : []
-  const missing = halves.length === 2 ? 8 - left.length - right.length : 0
-  if (missing < 0) return undefined
+  function isUnsafeIpv4(parts: [number, number, number, number]): boolean {
+    const [a, b] = parts
+    if (a === 0 || a === 10 || a === 127) return true
+    if (a === 100 && b >= 64 && b <= 127) return true
+    if (a === 169 && b === 254) return true
+    if (a === 172 && b >= 16 && b <= 31) return true
+    if (a === 192 && b === 168) return true
+    return a >= 224
+  }
 
-  const parts = [...left, ...Array(missing).fill('0'), ...right]
-  if (parts.length !== 8) return undefined
+  function parseIpv6(
+    value: string,
+  ): [number, number, number, number, number, number, number, number] | undefined {
+    const halves = value.split('::')
+    if (halves.length > 2) return undefined
 
-  const numbers = parts.map((part) =>
-    /^[\da-f]{1,4}$/i.test(part) ? Number.parseInt(part, 16) : NaN,
-  )
-  if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 0xffff)) return undefined
-  return numbers as [number, number, number, number, number, number, number, number]
-}
+    const left = halves[0] ? halves[0].split(':') : []
+    const right = halves[1] ? halves[1].split(':') : []
+    const missing = halves.length === 2 ? 8 - left.length - right.length : 0
+    if (missing < 0) return undefined
 
-function isUnsafeIpv6(parts: [number, number, number, number, number, number, number, number]) {
-  const [a] = parts
-  if (parts.every((part) => part === 0)) return true
-  if (parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1) return true
-  if ((a & 0xfe00) === 0xfc00) return true
-  if ((a & 0xffc0) === 0xfe80) return true
-  if ((a & 0xffc0) === 0xfec0) return true
-  if ((a & 0xff00) === 0xff00) return true
-
-  const ipv4 = ipv4FromIpv6(parts)
-  if (ipv4) return isUnsafeIpv4(ipv4)
-  return false
-}
+    const parts = [...left, ...Array(missing).fill('0'), ...right]
+    if (parts.length !== 8) return undefined
 
-function ipv4FromIpv6(
-  parts: [number, number, number, number, number, number, number, number],
-): [number, number, number, number] | undefined {
-  const mapped = parts.slice(0, 5).every((part) => part === 0) && parts[5] === 0xffff
-  const compatible = parts.slice(0, 6).every((part) => part === 0)
-  if (!mapped && !compatible) return undefined
-  return [parts[6]! >> 8, parts[6]! & 0xff, parts[7]! >> 8, parts[7]! & 0xff]
+    const numbers = parts.map((part) =>
+      /^[\da-f]{1,4}$/i.test(part) ? Number.parseInt(part, 16) : NaN,
+    )
+    if (numbers.some((part) => !Number.isInteger(part) || part < 0 || part > 0xffff))
+      return undefined
+    return numbers as [number, number, number, number, number, number, number, number]
+  }
+
+  function isUnsafeIpv6(parts: [number, number, number, number, number, number, number, number]) {
+    const [a] = parts
+    if (parts.every((part) => part === 0)) return true
+    if (parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1) return true
+    if ((a & 0xfe00) === 0xfc00) return true
+    if ((a & 0xffc0) === 0xfe80) return true
+    if ((a & 0xffc0) === 0xfec0) return true
+    if ((a & 0xff00) === 0xff00) return true
+
+    const ipv4 = ipv4FromIpv6(parts)
+    return ipv4 ? isUnsafeIpv4(ipv4) : false
+  }
+
+  function ipv4FromIpv6(
+    parts: [number, number, number, number, number, number, number, number],
+  ): [number, number, number, number] | undefined {
+    const mapped = parts.slice(0, 5).every((part) => part === 0) && parts[5] === 0xffff
+    const compatible = parts.slice(0, 6).every((part) => part === 0)
+    if (!mapped && !compatible) return undefined
+    return [parts[6]! >> 8, parts[6]! & 0xff, parts[7]! >> 8, parts[7]! & 0xff]
+  }
 }
 
 /**

package/src/internal/Auth.test.ts

@@ -1889,6 +1889,54 @@ describe('ensureProject', () => {
   })
 })
 
+describe('parseCredential', () => {
+  test('parses credentials keyed by chain id', () => {
+    const credential = Auth.parseCredential(
+      JSON.stringify({ 4217: 'mainnet:secret', 421700001: 'zone:secret' }),
+    )
+
+    expect(credential).toEqual({ 4217: 'mainnet:secret', 421700001: 'zone:secret' })
+  })
+
+  test('supports a shared credential', () => {
+    expect(Auth.parseCredential('shared:secret')).toBe('shared:secret')
+  })
+
+  test('rejects malformed credential maps', () => {
+    expect(() => Auth.parseCredential('{"4217":1}')).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Expected a credential or a chain-id-to-credential JSON object.]`,
+    )
+  })
+})
+
+describe('resolveCredential', () => {
+  test('infers Basic auth from a credential containing a colon', () => {
+    expect(Auth.resolveCredential({ chainId: 4217, value: 'user:password' })).toEqual({
+      basicAuth: 'user:password',
+    })
+  })
+
+  test('infers Bearer auth from a credential without a colon', () => {
+    expect(Auth.resolveCredential({ chainId: 4217, value: 'bearer-token' })).toEqual({
+      basicAuth: undefined,
+      bearerAuth: 'bearer-token',
+    })
+  })
+
+  test('selects a credential by chain id', () => {
+    const value = JSON.stringify({ 4217: 'mainnet:secret', 421700001: 'zone-token' })
+
+    expect(Auth.resolveCredential({ chainId: 4217, value })).toEqual({
+      basicAuth: 'mainnet:secret',
+    })
+    expect(Auth.resolveCredential({ chainId: 421700001, value })).toEqual({
+      basicAuth: undefined,
+      bearerAuth: 'zone-token',
+    })
+    expect(Auth.resolveCredential({ chainId: 42431, value })).toEqual({ basicAuth: undefined })
+  })
+})
+
 function createScopedApp(options: {
   auth?: Auth.Context | undefined
   routes: readonly { path: string; policy: Auth.require.Policy }[]

package/src/internal/Auth.ts

@@ -9,6 +9,7 @@ import { findTargetHandler } from 'hono/utils/handler'
 import { Challenge, Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
 import { Addresses } from 'viem/tempo'
+import { tempoMainnet } from 'viem/tempo/chains'
 import * as z from 'zod/mini'
 
 import type * as App from '../App.js'
@@ -26,7 +27,6 @@ import * as Response from './Response.js'
 import * as Schema from './Schema.js'
 import * as Scope from '../Scope.js'
 import * as Users from '../db/tables/users.js'
-import * as Viem from './Viem.js'
 
 const policySymbol = Symbol('tempo-api.auth.policy')
 const mppManagementSymbol = Symbol('tempo-api.auth.mpp-management')
@@ -1451,7 +1451,7 @@ export function require<environment extends Environment = Environment>(
       if (
         apiKey.environment === 'sandbox' &&
         explicitChain !== undefined &&
-        Viem.isMainnet(explicitChain)
+        explicitChain === tempoMainnet.id
       )
         return jsonError(c, {
           code: 'api_key_forbidden',
@@ -1644,6 +1644,65 @@ type RateLimitAccess = PaymentAccess & {
   rateLimit: RateLimit.Result
 }
 
+/** Shared or per-chain credentials. */
+export type ChainCredential = string | Record<number, string>
+
+/** Parses shared or per-chain credentials from an environment value. */
+export function parseCredential(value: ChainCredential | undefined): parseCredential.ReturnType {
+  if (!value) return undefined
+  if (typeof value !== 'string') return value
+  const credentials = (() => {
+    try {
+      return JSON.parse(value) as unknown
+    } catch {
+      return value
+    }
+  })()
+  if (typeof credentials === 'string') return credentials
+  if (
+    !credentials ||
+    typeof credentials !== 'object' ||
+    Array.isArray(credentials) ||
+    Object.values(credentials).some((credential) => typeof credential !== 'string')
+  )
+    throw new Error('Expected a credential or a chain-id-to-credential JSON object.')
+  return credentials as Record<number, string>
+}
+
+export declare namespace parseCredential {
+  /** Parsed shared or per-chain credentials. */
+  type ReturnType = ChainCredential | undefined
+}
+
+/** Resolves a chain credential and infers its HTTP authorization scheme. */
+export function resolveCredential(
+  options: resolveCredential.Options,
+): resolveCredential.ReturnType {
+  const credentials = parseCredential(options.value)
+  const credential = typeof credentials === 'string' ? credentials : credentials?.[options.chainId]
+  if (!credential) return { basicAuth: undefined }
+  if (credential.includes(':')) return { basicAuth: credential }
+  return { basicAuth: undefined, bearerAuth: credential }
+}
+
+export declare namespace resolveCredential {
+  /** Options for resolving a chain credential. */
+  type Options = {
+    /** Chain id selecting a per-chain credential. */
+    chainId: number
+    /** Shared or per-chain credentials. */
+    value?: ChainCredential | undefined
+  }
+
+  /** Resolved HTTP authorization credentials. */
+  type ReturnType = {
+    /** Basic credentials inferred from a value containing a colon. */
+    basicAuth: string | undefined
+    /** Bearer credential inferred from a value without a colon. */
+    bearerAuth?: string | undefined
+  }
+}
+
 /**
  * How long to wait for the rate-limit counter before failing open. A hot
  * counter backend (e.g. a single Durable Object serving one busy quota bucket)