tapimo 0.7.0 → 0.7.2

package/src/internal/Viem.test.ts

@@ -1,3 +1,7 @@
+import { ZoneRpcAuthentication } from 'ox/tempo'
+import { defineChain, type Chain } from 'viem'
+import { tempoTestnet } from 'viem/tempo/chains'
+
 import type * as Auth from './Auth.js'
 import * as Viem from './Viem.js'
 
@@ -11,6 +15,21 @@ const apiKeyPrincipal: Auth.Principal = {
   orgId: 'org_test',
   type: 'api_key',
 }
+const zone = defineChain({
+  ...tempoTestnet,
+  contracts: {
+    ...tempoTestnet.contracts,
+    messenger: { address: '0x0000000000000000000000000000000000000001' },
+    portal: { address: '0x0000000000000000000000000000000000000002' },
+  },
+  id: 421_700_001,
+  name: 'Zone E',
+  rpcUrls: {
+    default: { http: ['https://zone.rpc.test'] },
+    internal: { http: ['https://internal.zone.rpc.test'] },
+  },
+  sourceId: tempoTestnet.id,
+}) satisfies Chain
 
 describe('isMainnet', () => {
   test('is true only for the mainnet chain id', () => {
@@ -24,15 +43,41 @@ describe('isMainnet', () => {
   })
 })
 
-describe('resolve', () => {
+describe('configuredChainIds', () => {
+  test('returns ids from object and serialized URL maps', () => {
+    expect(Viem.configuredChainIds({ 31_318: 'https://nextfork.tidx.test' })).toEqual([31_318])
+    expect(
+      Viem.configuredChainIds(
+        JSON.stringify({
+          31_318: 'https://nextfork.tidx.test',
+          421_700_002: 'https://zone.tidx.test',
+        }),
+      ),
+    ).toEqual([31_318, 421_700_002])
+  })
+
+  test('returns no ids for shared URLs and dynamic resolvers', () => {
+    expect(Viem.configuredChainIds('https://tidx.test')).toEqual([])
+    expect(Viem.configuredChainIds(() => 'https://tidx.test')).toEqual([])
+  })
+
+  test('rejects malformed chain-id maps', () => {
+    for (const chainId of ['-1', '0', '031318', '0x7a56', '1e3', '9007199254740992', 'devnet'])
+      expect(() =>
+        Viem.configuredChainIds(JSON.stringify({ [chainId]: 'https://tidx.test' })),
+      ).toThrow('Expected a URL or a chain-id-to-URL JSON object.')
+  })
+})
+
+describe('resolveRpc', () => {
   test('defaults to the per-chain RPC URL', () => {
-    expect(Viem.resolve(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(undefined, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
         "url": "https://rpc.tempo.xyz",
       }
     `)
-    expect(Viem.resolve(undefined, { chainId: 42431, principal: null })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(undefined, { chainId: 42431, principal: null })).toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
         "url": "https://rpc.testnet.tempo.xyz",
@@ -42,8 +87,8 @@ describe('resolve', () => {
 
   test('uses a static config override', () => {
     expect(
-      Viem.resolve(
-        { basicAuth: 'user:pass', url: (chainId) => `https://${chainId}.rpc.test` },
+      Viem.resolveRpc(
+        { auth: 'user:pass', url: (chainId) => `https://${chainId}.rpc.test` },
         { chainId: 4217, principal: null },
       ),
     ).toMatchInlineSnapshot(`
@@ -54,15 +99,62 @@ describe('resolve', () => {
     `)
   })
 
+  test('selects RPC URLs by chain id', () => {
+    const rpc = {
+      publicZoneUrl: JSON.stringify({ 421_700_001: 'https://public.zone.rpc.test' }),
+      url: JSON.stringify({ 4217: 'https://mainnet.rpc.test' }),
+    }
+
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+      {
+        "basicAuth": undefined,
+        "url": "https://mainnet.rpc.test",
+      }
+    `)
+    expect(Viem.resolveRpc(rpc, { chainId: zone.id, principal: null, zone }))
+      .toMatchInlineSnapshot(`
+      {
+        "basicAuth": undefined,
+        "publicZoneUrl": "https://public.zone.rpc.test",
+        "url": "https://internal.zone.rpc.test",
+      }
+    `)
+  })
+
+  test('selects auth and scheme by chain id', () => {
+    const rpc = { auth: { 4217: 'mainnet:secret', 42431: 'testnet-token' } }
+
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null }).basicAuth).toBe(
+      'mainnet:secret',
+    )
+    expect(Viem.resolveRpc(rpc, { chainId: 42431, principal: null }).bearerAuth).toBe(
+      'testnet-token',
+    )
+    expect(
+      Viem.resolveRpc(rpc, { chainId: 421_700_001, principal: null }).basicAuth,
+    ).toBeUndefined()
+  })
+
+  test('parses serialized Basic auth by chain id', () => {
+    const rpc = { auth: JSON.stringify({ 4217: 'mainnet:secret' }) }
+
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null }).basicAuth).toBe(
+      'mainnet:secret',
+    )
+    expect(Viem.resolveRpc(rpc, { chainId: 42431, principal: null }).basicAuth).toBeUndefined()
+  })
+
   test('the static form ignores the principal', () => {
-    const rpc = { basicAuth: 'user:pass', url: () => 'https://internal.rpc' }
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: publicPrincipal })).toMatchInlineSnapshot(`
+    const rpc = { auth: 'user:pass', url: () => 'https://internal.rpc' }
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: publicPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
       }
     `)
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: apiKeyPrincipal })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: apiKeyPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
@@ -71,17 +163,19 @@ describe('resolve', () => {
   })
 
   test('the resolver form routes anonymous callers to a separate upstream', () => {
-    const rpc = ({ principal }: Viem.resolve.Context) =>
+    const rpc = ({ principal }: Viem.resolveRpc.Context) =>
       principal?.type === 'public'
         ? { url: 'https://rpc.tempo.xyz' }
-        : { basicAuth: 'user:pass', url: 'https://internal.rpc' }
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: publicPrincipal })).toMatchInlineSnapshot(`
+        : { auth: 'user:pass', url: 'https://internal.rpc' }
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: publicPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
         "url": "https://rpc.tempo.xyz",
       }
     `)
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: apiKeyPrincipal })).toMatchInlineSnapshot(`
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: apiKeyPrincipal }))
+      .toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
@@ -90,11 +184,11 @@ describe('resolve', () => {
   })
 
   test('a null principal (trusted poller) takes the non-public branch', () => {
-    const rpc = ({ principal }: Viem.resolve.Context) =>
+    const rpc = ({ principal }: Viem.resolveRpc.Context) =>
       principal?.type === 'public'
         ? { url: 'https://rpc.tempo.xyz' }
-        : { basicAuth: 'user:pass', url: 'https://internal.rpc' }
-    expect(Viem.resolve(rpc, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
+        : { auth: 'user:pass', url: 'https://internal.rpc' }
+    expect(Viem.resolveRpc(rpc, { chainId: 4217, principal: null })).toMatchInlineSnapshot(`
       {
         "basicAuth": "user:pass",
         "url": "https://internal.rpc",
@@ -104,7 +198,7 @@ describe('resolve', () => {
 
   test('a resolver that omits url falls back to the built-in public host', () => {
     const rpc = () => ({})
-    expect(Viem.resolve(rpc, { chainId: 42431, principal: publicPrincipal }))
+    expect(Viem.resolveRpc(rpc, { chainId: 42431, principal: publicPrincipal }))
       .toMatchInlineSnapshot(`
       {
         "basicAuth": undefined,
@@ -112,6 +206,65 @@ describe('resolve', () => {
       }
     `)
   })
+
+  test('a resolver that omits url falls back to the Zone internal host', () => {
+    expect(Viem.resolveRpc(() => ({}), { chainId: zone.id, principal: publicPrincipal, zone }))
+      .toMatchInlineSnapshot(`
+      {
+        "basicAuth": undefined,
+        "publicZoneUrl": "https://zone.rpc.test",
+        "url": "https://internal.zone.rpc.test",
+      }
+    `)
+  })
+})
+
+describe('getClient', () => {
+  test('sends inferred Bearer auth', async () => {
+    const fetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ id: 1, jsonrpc: '2.0', result: '0x1079' }))
+    try {
+      const client = Viem.getClient({
+        chainId: 4217,
+        rpc: { auth: 'rpc-token', url: 'https://internal.rpc.test' },
+      })
+      await client.getChainId()
+
+      const [input, init] = fetch.mock.calls[0]!
+      const upstream = new Request(input, init)
+      expect(upstream.headers.get('authorization')).toBe('Bearer rpc-token')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
+
+  test('does not send RPC auth to a public Zone URL', async () => {
+    const fetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ id: 1, jsonrpc: '2.0', result: '0x1079' }))
+    try {
+      const client = Viem.getClient({
+        chainId: zone.id,
+        rpc: {
+          auth: 'rpc:secret',
+          publicZoneUrl: 'https://public.zone.rpc.test',
+          url: 'https://internal.rpc.test',
+        },
+        zone,
+        zoneToken: 'zone-token',
+      })
+      await client.getChainId()
+
+      const [input, init] = fetch.mock.calls[0]!
+      const upstream = new Request(input, init)
+      expect(upstream.url).toBe('https://public.zone.rpc.test/')
+      expect(upstream.headers.get('authorization')).toBeNull()
+      expect(upstream.headers.get(ZoneRpcAuthentication.headerName)).toBe('zone-token')
+    } finally {
+      fetch.mockRestore()
+    }
+  })
 })
 
 describe('createGetClient', () => {
@@ -120,7 +273,7 @@ describe('createGetClient', () => {
       rpc: ({ principal }) =>
         principal?.type === 'public'
           ? { url: 'https://rpc.tempo.xyz' }
-          : { basicAuth: 'user:pass', url: 'https://internal.rpc' },
+          : { auth: 'user:pass', url: 'https://internal.rpc' },
     })
 
     expect(getClient(4217, apiKeyPrincipal)).toBe(getClient(4217, apiKeyPrincipal))

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,29 @@ 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)
+
+/** 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 +71,27 @@ 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 } : {}),
     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 +102,18 @@ 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
     /**
      * 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 +124,27 @@ 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 } = 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
       ? {
           headers: {
-            ...(basicAuth ? { Authorization: `Basic ${btoa(basicAuth)}` } : {}),
+            ...(authorization ? { Authorization: authorization } : {}),
             ...(zoneToken ? { [ZoneRpcAuthentication.headerName]: zoneToken } : {}),
           },
         }
@@ -134,16 +168,21 @@ 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 } = resolveRpc(rpc, {
+      chainId,
+      principal,
+      zone: zones.get(chainId),
+    })
+    const cacheKey = JSON.stringify([url, basicAuth, bearerAuth, chainId])
     const existing = clients.get(cacheKey)
     if (existing) return existing
 
     const client = getClient({
       chainId,
-      rpc: { basicAuth, url: () => url },
+      rpc: { auth: basicAuth ?? bearerAuth, url: () => url },
     })
     clients.set(cacheKey, client)
     return client
@@ -157,6 +196,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 +223,68 @@ 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
         /** 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
         /** 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', () => {