tapimo 0.7.1 → 0.8.0

package/src/internal/Viem.ts

@@ -1,12 +1,12 @@
 import { ZoneRpcAuthentication } from 'ox/tempo'
 import { createClient, http, publicActions } from 'viem'
-import type { Client as core_Client, HttpTransport, PublicActions } from 'viem'
+import type { Chain as core_Chain, Client as core_Client, HttpTransport, PublicActions } from 'viem'
 import { tempoActions } from 'viem/tempo'
 import type { TempoActions } from 'viem/tempo'
 import { tempoMainnet, tempoTestnet } from 'viem/tempo/chains'
 import type * as z from 'zod/mini'
 
-import type * as Auth from './Auth.js'
+import * as Auth from './Auth.js'
 import type * as Schema from './Schema.js'
 
 /** Known Tempo chains keyed by id, for metadata lookups. */
@@ -41,22 +41,32 @@ export type Chain = Omit<typeof tempoMainnet, 'id'> & { id: ChainId }
 /** Gets a Tempo viem client for a chain id. */
 export type GetClient = (chainId?: ChainId) => getClient.ReturnType
 
-/**
- * Resolves an RPC URL for a Tempo chain id. May return `undefined` to fall back
- * to the built-in {@link url} map (e.g. for a chain the resolver doesn't serve).
- */
-export type UrlResolver = (chainId: ChainId) => string | undefined
+/** Shared, per-chain, or dynamically resolved RPC URLs. */
+export type UrlResolver =
+  | string
+  | Record<number, string>
+  | ((chainId: ChainId) => string | undefined)
+
+/** Headers required when connecting to a Zone upstream. */
+export type ZoneHeaders = Record<string, string>
+
+/** Returns chain ids declared by a static chain-id-to-URL map. */
+export function configuredChainIds(value: UrlResolver | undefined): number[] {
+  const urls = parseUrls(value)
+  if (!urls || typeof urls === 'string' || typeof urls === 'function') return []
+  return Object.keys(urls).map(Number)
+}
 
 /**
  * Resolves the effective RPC config for a single request.
  *
  * Accepts either a static config object or a per-request resolver function. The
- * resolver receives a {@link resolve.Context} (`chainId` plus the request
+ * resolver receives a {@link resolveRpc.Context} (`chainId` plus the request
  * `principal`), so callers can route traffic per caller — e.g. send anonymous
  * (`principal.type === 'public'`) traffic to a separate, no-auth upstream. A
  * `null` principal denotes a trusted, non-request caller (the scheduled
  * webhook poller). A missing `url` falls back to the built-in public host map
- * ({@link url}); a missing `basicAuth` means no Basic auth is sent.
+ * ({@link url}); missing `auth` means no Authorization header is sent.
  *
  * Memoization is keyed on the resolved output (see {@link createGetClient} and
  * {@link Tidx.createGetClient}), not the context, so a resolver may branch on
@@ -64,20 +74,28 @@ export type UrlResolver = (chainId: ChainId) => string | undefined
  * resolve to the same upstream share a client. Pass the result to
  * {@link getClient} (or let `getClient` resolve for you) to build a client.
  */
-export function resolve(
+export function resolveRpc(
   rpc: getClient.Rpc | undefined,
-  context: resolve.Context,
-): resolve.Resolved {
+  context: resolveRpc.Context,
+): resolveRpc.Resolved {
   const config = typeof rpc === 'function' ? rpc(context) : rpc
+  const auth = Auth.resolveCredential({ chainId: context.chainId, value: config?.auth })
+  const publicZoneUrl = context.zone
+    ? (resolveUrl(config?.publicZoneUrl, context.chainId) ?? context.zone.rpcUrls.default.http[0])
+    : undefined
   return {
-    basicAuth: config?.basicAuth,
+    ...auth,
+    ...(publicZoneUrl ? { publicZoneUrl } : {}),
+    ...(context.zone && config?.zoneHeaders ? { zoneHeaders: config.zoneHeaders } : {}),
     url:
-      (typeof config?.url === 'function' ? config.url(context.chainId) : config?.url) ??
+      resolveUrl(config?.url, context.chainId) ??
+      context.zone?.rpcUrls['internal']?.http[0] ??
+      context.zone?.rpcUrls.default.http[0] ??
       url[context.chainId],
   }
 }
 
-export declare namespace resolve {
+export declare namespace resolveRpc {
   /** RPC resolution context. */
   type Context = {
     /** Tempo chain id. */
@@ -88,12 +106,20 @@ export declare namespace resolve {
      * `type: 'public'` principal; authenticated requests a `type: 'api_key'` one.
      */
     principal: Auth.Principal | null
+    /** Zone chain selected for this request, when applicable. */
+    zone?: core_Chain | undefined
   }
 
   /** Resolved RPC config for a single request. */
   type Resolved = {
     /** Basic auth credentials, or undefined to send no Basic auth. */
     basicAuth?: string | undefined
+    /** Bearer auth credential, or undefined to send no Bearer auth. */
+    bearerAuth?: string | undefined
+    /** Public Zone RPC URL that accepts a caller-provided authorization token. */
+    publicZoneUrl?: string | undefined
+    /** Headers sent to Zone RPC upstreams. */
+    zoneHeaders?: ZoneHeaders | undefined
     /**
      * Resolved RPC URL, or `undefined` when neither a configured `rpc` nor the
      * built-in {@link url} map covers the chain (e.g. an unconfigured localnet).
@@ -104,13 +130,28 @@ export declare namespace resolve {
 }
 
 export function getClient(options: getClient.Options): getClient.ReturnType {
-  const { chainId = defaultChainId, principal = null, rpc, zoneToken } = options
-  const { basicAuth, url: rpcUrl } = resolve(rpc, { chainId, principal })
+  const { chainId = defaultChainId, principal = null, rpc, zone, zoneToken } = options
+  const { basicAuth, bearerAuth, publicZoneUrl, url, zoneHeaders } = resolveRpc(rpc, {
+    chainId,
+    principal,
+    zone,
+  })
+  const usePublicZoneUrl = Boolean(zoneToken && publicZoneUrl)
+  const rpcUrl = usePublicZoneUrl ? publicZoneUrl : url
+  // Public Zone endpoints authenticate with the caller's token, never internal RPC credentials.
+  const authorization = usePublicZoneUrl
+    ? undefined
+    : basicAuth
+      ? `Basic ${btoa(basicAuth)}`
+      : bearerAuth
+        ? `Bearer ${bearerAuth}`
+        : undefined
   const fetchOptions =
-    basicAuth || zoneToken
+    authorization || zoneToken || zoneHeaders
       ? {
           headers: {
-            ...(basicAuth ? { Authorization: `Basic ${btoa(basicAuth)}` } : {}),
+            ...(zoneHeaders ? Object.fromEntries(new Headers(zoneHeaders)) : {}),
+            ...(authorization ? { Authorization: authorization } : {}),
             ...(zoneToken ? { [ZoneRpcAuthentication.headerName]: zoneToken } : {}),
           },
         }
@@ -134,16 +175,26 @@ export function getClient(options: getClient.Options): getClient.ReturnType {
 export function createGetClient(options: createGetClient.Options = {}): createGetClient.ReturnType {
   const { defaultChainId: defaultChainId_option = defaultChainId, rpc } = options
   const clients = new Map<string, getClient.ReturnType>()
+  const zones = new Map((options.zones ?? []).map((zone) => [zone.id, zone]))
 
   return (chainId = defaultChainId_option, principal = null) => {
-    const { basicAuth, url } = resolve(rpc, { chainId, principal })
-    const cacheKey = JSON.stringify([url, basicAuth, chainId])
+    const { basicAuth, bearerAuth, url, zoneHeaders } = resolveRpc(rpc, {
+      chainId,
+      principal,
+      zone: zones.get(chainId),
+    })
+    const cacheKey = JSON.stringify([url, basicAuth, bearerAuth, zoneHeaders, chainId])
     const existing = clients.get(cacheKey)
     if (existing) return existing
 
     const client = getClient({
       chainId,
-      rpc: { basicAuth, url: () => url },
+      rpc: {
+        auth: basicAuth ?? bearerAuth,
+        url: () => url,
+        ...(zoneHeaders ? { zoneHeaders } : {}),
+      },
+      zone: zones.get(chainId),
     })
     clients.set(cacheKey, client)
     return client
@@ -157,6 +208,8 @@ export declare namespace createGetClient {
     defaultChainId?: ChainId | undefined
     /** Tempo RPC options applied to every constructed client. */
     rpc?: getClient.Rpc | undefined
+    /** Zone chains whose internal RPC URLs serve as per-chain defaults. */
+    zones?: readonly core_Chain[] | undefined
   }
 
   /** Memoized Tempo client resolver. */
@@ -182,26 +235,72 @@ export declare namespace getClient {
     principal?: Auth.Principal | null | undefined
     /** Tempo RPC options. */
     rpc?: Rpc | undefined
+    /** Zone chain metadata used for RPC URL resolution. */
+    zone?: core_Chain | undefined
     /** Zone authorization token forwarded to the RPC node. */
     zoneToken?: string | undefined
   }
 
   /**
    * Tempo RPC options: either a static config, or a per-request resolver
-   * function that receives a {@link resolve.Context} and returns the config to
+   * function that receives a {@link resolveRpc.Context} and returns the config to
    * use (e.g. routing anonymous callers to a public, no-auth RPC).
    */
   type Rpc =
     | {
-        /** Basic auth credentials for RPC requests. */
-        basicAuth?: string | undefined
+        /** Shared or per-chain RPC credentials. Values containing `:` use Basic auth; others use Bearer auth. */
+        auth?: Auth.ChainCredential | undefined
+        /** Resolves the public Zone RPC URL used with caller-provided authorization. */
+        publicZoneUrl?: UrlResolver | undefined
+        /** Headers sent to Zone RPC upstreams. */
+        zoneHeaders?: ZoneHeaders | undefined
         /** Resolves the RPC URL for a Tempo chain id. */
         url?: UrlResolver | undefined
       }
-    | ((context: resolve.Context) => {
-        /** Basic auth credentials for RPC requests, or undefined for none. */
-        basicAuth?: string | undefined
+    | ((context: resolveRpc.Context) => {
+        /** Shared or per-chain RPC credentials, or undefined for none. */
+        auth?: Auth.ChainCredential | undefined
+        /** Public Zone RPC URL used with caller-provided authorization. */
+        publicZoneUrl?: string | undefined
+        /** Headers sent to Zone RPC upstreams. */
+        zoneHeaders?: ZoneHeaders | undefined
         /** RPC URL to use; falls back to the built-in public host when omitted. */
         url?: string | undefined
       })
 }
+
+/** Resolves a shared or per-chain URL for one chain id. */
+export function resolveUrl(value: UrlResolver | undefined, chainId: ChainId) {
+  if (typeof value === 'function') return value(chainId)
+  const urls = parseUrls(value)
+  if (!urls) return undefined
+  if (typeof urls === 'string') return urls
+  return urls[chainId]
+}
+
+function parseUrls(value: UrlResolver | undefined): Record<number, string> | string | undefined {
+  if (!value || typeof value === 'function') return undefined
+  const urls =
+    typeof value === 'string'
+      ? (() => {
+          try {
+            return JSON.parse(value) as unknown
+          } catch {
+            return value
+          }
+        })()
+      : value
+  if (typeof urls === 'string') return urls
+  if (
+    !urls ||
+    typeof urls !== 'object' ||
+    Array.isArray(urls) ||
+    Object.keys(urls).some((chainId) => {
+      const id = Number(chainId)
+      return !Number.isSafeInteger(id) || id <= 0 || String(id) !== chainId
+    }) ||
+    Object.values(urls).some((url) => typeof url !== 'string')
+  )
+    throw new Error('Expected a URL or a chain-id-to-URL JSON object.')
+  return urls as Record<number, string>
+}

package/src/internal/WebhookDestination.ts

@@ -232,7 +232,7 @@ export const eventTypeHeader = 'tempo-event-type'
  */
 export function sign(options: sign.Options): string {
   const timestamp = options.timestamp ?? Math.floor(Date.now() / 1_000)
-  const v1 = hmac(options.secret, `${timestamp}.${options.body}`)
+  const v1 = Signature.hmac(options.secret, `${timestamp}.${options.body}`)
   return `t=${timestamp},v1=${v1}`
 }
 
@@ -253,15 +253,15 @@ export declare namespace sign {
  * rejects signatures older than `tolerance` seconds (default 300).
  */
 export function verify(options: verify.Options): boolean {
-  const parsed = parseSignature(options.signature)
+  const parsed = Signature.parse(options.signature)
   if (!parsed) return false
 
   const tolerance = options.tolerance ?? 300
   const now = options.now ?? Math.floor(Date.now() / 1_000)
   if (Math.abs(now - parsed.timestamp) > tolerance) return false
 
-  const expected = hmac(options.secret, `${parsed.timestamp}.${options.body}`)
-  return timingSafeEqual(expected, parsed.v1)
+  const expected = Signature.hmac(options.secret, `${parsed.timestamp}.${options.body}`)
+  return Signature.timingSafeEqual(expected, parsed.v1)
 }
 
 export declare namespace verify {
@@ -280,28 +280,30 @@ export declare namespace verify {
   }
 }
 
-function hmac(secret: string, message: string): string {
-  return Hash.hmac256(Hex.fromString(secret), Hex.fromString(message)).slice(2)
-}
+namespace Signature {
+  export function hmac(secret: string, message: string): string {
+    return Hash.hmac256(Hex.fromString(secret), Hex.fromString(message)).slice(2)
+  }
 
-function parseSignature(signature: string): { timestamp: number; v1: string } | null {
-  let timestamp: number | undefined
-  let v1: string | undefined
-  for (const part of signature.split(',')) {
-    const [key, value] = part.split('=', 2)
-    if (key === 't' && value) timestamp = Number(value)
-    else if (key === 'v1' && value) v1 = value
+  export function parse(signature: string): { timestamp: number; v1: string } | null {
+    let timestamp: number | undefined
+    let v1: string | undefined
+    for (const part of signature.split(',')) {
+      const [key, value] = part.split('=', 2)
+      if (key === 't' && value) timestamp = Number(value)
+      else if (key === 'v1' && value) v1 = value
+    }
+    if (timestamp === undefined || Number.isNaN(timestamp) || !v1) return null
+    return { timestamp, v1 }
   }
-  if (timestamp === undefined || Number.isNaN(timestamp) || !v1) return null
-  return { timestamp, v1 }
-}
 
-function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false
-  let mismatch = 0
-  for (let index = 0; index < a.length; index++)
-    mismatch |= a.charCodeAt(index) ^ b.charCodeAt(index)
-  return mismatch === 0
+  export function timingSafeEqual(left: string, right: string): boolean {
+    if (left.length !== right.length) return false
+    let mismatch = 0
+    for (let index = 0; index < left.length; index++)
+      mismatch |= left.charCodeAt(index) ^ right.charCodeAt(index)
+    return mismatch === 0
+  }
 }
 
 /** Thrown when a subscriber URL fails SSRF/format validation. */

package/src/internal/Webhooks.test.ts

@@ -1,5 +1,6 @@
 import { Webhooks } from 'tapimo'
 import * as TestApp from '../../test/App.js'
+import * as Cursor from './Cursor.js'
 
 const apiKeyOwner = { orgId: 'org_1', type: 'api_key' } as const
 const mppOwner = { payer: 'did:pkh:eip155:1:0xabc', type: 'mpp' } as const
@@ -56,6 +57,42 @@ describe('createSubscription', () => {
     expect(read).toEqual(subscription)
   })
 
+  test('commits an initial poller cursor through both insert paths', async () => {
+    const db = TestApp.database()
+    const direct = await Webhooks.createSubscription(db, createInput(), {
+      startBlockNumber: 123,
+    })
+    const capped = await Webhooks.createSubscription(db, createInput({ owner: mppOwner }), {
+      maxPerOwner: 1,
+      startBlockNumber: 456,
+    })
+
+    expect(Cursor.decode((await Webhooks.getCursor(db, direct.id))!, ['int']))
+      .toMatchInlineSnapshot(`
+      [
+        123,
+      ]
+    `)
+    expect(Cursor.decode((await Webhooks.getCursor(db, capped.id))!, ['int']))
+      .toMatchInlineSnapshot(`
+      [
+        456,
+      ]
+    `)
+  })
+
+  test('rejects an invalid initial block number before persisting', async () => {
+    const db = TestApp.database()
+
+    for (const startBlockNumber of [-1, 1.5, Number.MAX_SAFE_INTEGER + 1])
+      await expect(
+        Webhooks.createSubscription(db, createInput(), { startBlockNumber }),
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `[RangeError: startBlockNumber must be a non-negative safe integer.]`,
+      )
+    expect(await Webhooks.listSubscriptions(db, apiKeyOwner)).toEqual([])
+  })
+
   test('sets expiresAt from ttl for MPP-owned subscriptions', async () => {
     const db = TestApp.database()
     const subscription = await Webhooks.createSubscription(
@@ -301,6 +338,28 @@ describe('cursors', () => {
     await Webhooks.setCursor(db, created.id, '12345:7')
     expect(await Webhooks.getCursor(db, created.id)).toMatchInlineSnapshot(`"12345:7"`)
   })
+
+  test('atomically rejects a stale cursor write', async () => {
+    const db = TestApp.database()
+    const created = await Webhooks.createSubscription(db, createInput())
+    const a = Cursor.encode([100, 1])
+    const b = Cursor.encode([100, 2])
+    const results = await Promise.all([
+      Webhooks.compareAndSetCursor(db, {
+        cursor: a,
+        expectedCursor: null,
+        subscriptionId: created.id,
+      }),
+      Webhooks.compareAndSetCursor(db, {
+        cursor: b,
+        expectedCursor: null,
+        subscriptionId: created.id,
+      }),
+    ])
+
+    expect(results.toSorted((a, b) => Number(a) - Number(b))).toEqual([false, true])
+    expect([a, b]).toContain(await Webhooks.getCursor(db, created.id))
+  })
 })
 
 describe('recordSuccess / recordFailure', () => {

package/src/internal/Webhooks.ts

@@ -5,6 +5,7 @@ import type * as Db from '../db/Db.js'
 import * as WebhookDeliveries from '../db/tables/webhookDeliveries.js'
 import * as WebhookSubscriptions from '../db/tables/webhookSubscriptions.js'
 import type * as Metrics from '../Metrics.js'
+import * as Cursor from './Cursor.js'
 import * as Id from './Id.js'
 import * as MetricSink from './MetricSink.js'
 import * as WebhookDestination from './WebhookDestination.js'
@@ -170,9 +171,18 @@ export async function createSubscription(
   options: createSubscription.Options = {},
 ): Promise<Subscription> {
   WebhookDestination.assertDestination(input.destination)
+  if (
+    options.startBlockNumber !== undefined &&
+    (!Number.isSafeInteger(options.startBlockNumber) || options.startBlockNumber < 0)
+  )
+    throw new RangeError('startBlockNumber must be a non-negative safe integer.')
 
   const now = (options.now ?? (() => new Date()))()
   const iso = now.toISOString()
+  // A one-field checkpoint records the live creation head without claiming it
+  // was scanned. The poller expands it using its confirmation depth.
+  const pollerCursor =
+    options.startBlockNumber === undefined ? undefined : Cursor.encode([options.startBlockNumber])
 
   const subscription: Subscription = {
     chainId: input.chainId,
@@ -196,9 +206,15 @@ export async function createSubscription(
     const inserted = await WebhookSubscriptions.insertWithinLimit(db, subscription, {
       maxPerOwner: options.maxPerOwner,
       now: iso,
+      ...(pollerCursor === undefined ? {} : { pollerCursor }),
     })
     if (!inserted) throw new LimitExceededError(options.maxPerOwner)
-  } else await WebhookSubscriptions.insert(db, subscription)
+  } else
+    await WebhookSubscriptions.insert(
+      db,
+      subscription,
+      pollerCursor === undefined ? {} : { pollerCursor },
+    )
   return subscription
 }
 
@@ -209,6 +225,8 @@ export declare namespace createSubscription {
     maxPerOwner?: number | undefined
     /** Clock used for timestamps (injectable for tests). */
     now?: (() => Date) | undefined
+    /** Chain head observed immediately before the subscription becomes visible. */
+    startBlockNumber?: number | undefined
   }
 }
 
@@ -316,6 +334,19 @@ export async function getCursor(db: Db.Db, subscriptionId: string): Promise<stri
   return WebhookSubscriptions.getCursor(db, subscriptionId)
 }
 
+/** Writes a cursor only when its stored value matches the expected cursor. */
+export async function compareAndSetCursor(
+  db: Db.Db,
+  options: compareAndSetCursor.Options,
+): Promise<boolean> {
+  return WebhookSubscriptions.compareAndSetCursor(db, options)
+}
+
+export declare namespace compareAndSetCursor {
+  /** Options for {@link compareAndSetCursor}. */
+  type Options = WebhookSubscriptions.compareAndSetCursor.Options
+}
+
 /** Writes a subscription's keyset cursor. */
 export async function setCursor(db: Db.Db, subscriptionId: string, cursor: string): Promise<void> {
   await WebhookSubscriptions.setCursor(db, subscriptionId, cursor)
@@ -790,18 +821,11 @@ export declare namespace ping {
 }
 
 function generateId(now: Date): string {
-  // Zero-pad the epoch-ms so ids sort chronologically by string comparison
-  // (mirroring delivery ids), letting listSubscriptions page newest-first; 15
-  // digits leaves headroom well past the year 5138.
-  const timestamp = now.getTime().toString().padStart(15, '0')
-  return `wh_${timestamp}_${Id.random()}`
+  return Id.generateSortable('wh', now)
 }
 
 function generateDeliveryId(now: Date): string {
-  // Zero-pad the epoch-ms so ids sort chronologically by string comparison; 15
-  // digits leaves headroom well past the year 5138.
-  const timestamp = now.getTime().toString().padStart(15, '0')
-  return `whd_${timestamp}_${Id.random()}`
+  return Id.generateSortable('whd', now)
 }
 
 function generateSecret(): string {