tapimo 0.11.0 → 0.13.0

package/src/internal/Auth.ts

@@ -587,11 +587,21 @@ export function middleware<
     const overrides = options.overrides as
       | Record<string, PolicyOverride | false | undefined>
       | undefined
-    const configuredOverride = overrides?.[key]
+    const routePolicies = policies(c)
+    const configuredOverride = (() => {
+      const configured = overrides?.[key]
+      if (configured !== undefined) return configured
+      const inheritedMethod = routePolicies.find(
+        (policy) => policy.inheritOverridesFrom,
+      )?.inheritOverridesFrom
+      if (inheritedMethod === undefined) return undefined
+      const inheritedKey = `${inheritedMethod.toUpperCase()} ${key.slice(key.indexOf(' ') + 1)}`
+      return overrides?.[inheritedKey]
+    })()
     const routeOverride =
       management && configuredOverride ? { mpp: configuredOverride.mpp } : configuredOverride
     const endpointPolicy = bindMppScope(
-      resolvePolicy(base, defaults, [...policies(c), routeOverride], description),
+      resolvePolicy(base, defaults, [...routePolicies, routeOverride], description),
       scope,
     )
     if (!endpointPolicy) return next()
@@ -666,7 +676,10 @@ export declare namespace middleware {
   }
 
   /** MPP payment options used by auth middleware. */
-  type MppOptions = Omit<NonNullable<Parameters<typeof Mppx.create>[0]>, 'methods'> & {
+  type MppOptions = Omit<
+    Parameters<typeof Mppx.create<readonly [ReturnType<typeof tempo.session>]>>[0],
+    'methods'
+  > & {
     /** Paid-request quota per access principal. Defaults to 100 per minute. */
     rateLimit?: RateLimit.Limit | undefined
     /** Global Tempo Session options passed to the MPP method instantiator. */
@@ -1000,12 +1013,20 @@ export declare namespace install {
 }
 
 /** Creates route middleware that contributes an auth policy override. */
-export function policy(options: PolicyOverride): MiddlewareHandler {
+export function policy(options: policy.Options): MiddlewareHandler {
   const middleware = createMiddleware((_, next) => next()) as MiddlewareHandler & PolicyHandler
   middleware[policySymbol] = options
   return middleware
 }
 
+export declare namespace policy {
+  /** Route policy plus metadata for compatibility aliases. */
+  type Options = PolicyOverride & {
+    /** HTTP method whose configured override this route inherits when its own is absent. */
+    inheritOverridesFrom?: string | undefined
+  }
+}
+
 /** Adds management POSTs for OpenAPI-registered MPP GET resources. */
 export function installMppManagementRoutes(
   app: Hono<any, any>,
@@ -1106,7 +1127,7 @@ type OpenApiRoute = {
 }
 
 type PolicyHandler = {
-  [policySymbol]?: PolicyOverride | undefined
+  [policySymbol]?: policy.Options | undefined
 }
 
 type MppManagementHandler = {
@@ -1283,7 +1304,7 @@ function policies(c: hono_Context) {
   return matchedRoutes(c)
     .slice(c.req.routeIndex + 1)
     .map(policyFromRoute)
-    .filter((policy): policy is PolicyOverride => policy !== undefined)
+    .filter((routePolicy): routePolicy is policy.Options => routePolicy !== undefined)
 }
 
 function openApiSpec(route: RouterRoute) {
@@ -1433,8 +1454,8 @@ export function require<environment extends Environment = Environment>(
         return proceed()
       }
 
-      const apiKey = await auth.apiKey?.resolve(c, credential.token)
-      if (!apiKey) {
+      const apiKey_resolved = await auth.apiKey?.resolve(c, credential.token)
+      if (!apiKey_resolved) {
         // A bearer session token is indistinguishable from an API key at the
         // header, so a failed key lookup falls through to the session lane
         // before rejecting.
@@ -1452,6 +1473,10 @@ export function require<environment extends Environment = Environment>(
         })
       }
 
+      const scopes = Scope.expandAliases(apiKey_resolved.scopes)
+      const apiKey =
+        scopes === apiKey_resolved.scopes ? apiKey_resolved : { ...apiKey_resolved, scopes }
+
       // Sandbox keys are testnet-only. A sandbox key that explicitly targets
       // mainnet (`?chainId`) is rejected with a clear message rather than
       // steered or downgraded to anonymous, so the caller learns their key does
@@ -1829,7 +1854,8 @@ function getRequestId(c: hono_Context) {
   return typeof variables['requestId'] === 'string' ? variables['requestId'] : undefined
 }
 
-function hasPaymentCredential(c: hono_Context) {
+/** True when the request carries an `Authorization: Payment` MPP credential. */
+export function hasPaymentCredential(c: hono_Context) {
   const authorization = c.req.header('authorization')
   if (!authorization) return false
   return !!Credential.extractPaymentScheme(authorization)

package/src/internal/Cache.ts

@@ -58,10 +58,8 @@ export function response<environment extends Env>(
 ): MiddlewareHandler<environment> {
   const defaultCacheControl = options.cacheControl ?? policies.default
   const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key', 'X-API-Key']
-  // hono/cache suffixes its key with `::<directive>=<value>` for every
-  // configured vary directive (trimmed, lowercased, deduped). Mirror that
-  // normalization so the `no-cache` purge below deletes exactly the entry the
-  // wrapped middleware reads — drift here would make refreshes silently miss.
+  // Mirror hono/cache's vary normalization so the `no-cache` purge below
+  // deletes exactly the entry the wrapped middleware reads.
   const varyKeyDirectives = [
     ...new Set(vary.map((name) => name.trim().toLowerCase()).filter(Boolean)),
   ]
@@ -95,10 +93,19 @@ export function response<environment extends Env>(
     type Caches = { open(name: string): Promise<{ delete(key: string): Promise<unknown> }> }
     const caches = (globalThis as { caches?: Caches }).caches
     if (noCache && !noStore && caches) {
-      let key = await options.key(c)
+      // hono/cache 4.13 wraps generated keys in a canonical URL containing the
+      // request method and vary values. Keep this in sync with its
+      // `createCacheKey` so refreshes remove the stored GET response.
+      const key = await options.key(c)
+      const url = new URL('/.hono/cache', c.req.url)
+      url.searchParams.append('__hono_cache_key', key.split('#', 1)[0] ?? key)
+      url.searchParams.append('__hono_cache_method', c.req.method)
       for (const name of varyKeyDirectives)
-        key += `::${name}=${encodeURIComponent(c.req.raw.headers.get(name) ?? '')}`
-      await (await caches.open(options.name)).delete(key)
+        url.searchParams.append(
+          '__hono_cache_vary',
+          JSON.stringify([name, c.req.raw.headers.get(name) ?? '']),
+        )
+      await (await caches.open(options.name)).delete(url.href)
     }
 
     // Run ETag inside Hono's cache miss path so fresh responses are hashed

package/src/internal/EarnVaults.capabilities.test.ts

@@ -0,0 +1,33 @@
+import * as EarnVaults from './EarnVaults.js'
+
+describe('addZoneRouteCapabilities', () => {
+  test('adds private routing and router swaps', () => {
+    expect(
+      EarnVaults.addZoneRouteCapabilities({
+        asyncRedeem: false,
+        boundedRedeem: true,
+        deposit: true,
+        exactWithdraw: true,
+        inKindDeposit: true,
+        privateRouting: false,
+        redeem: true,
+        routerSwaps: false,
+      }),
+    ).toMatchObject({ privateRouting: true, routerSwaps: true })
+  })
+})
+
+describe('deriveZoneId', () => {
+  test('derives IDs from mainnet and testnet Zone chain schemes', () => {
+    expect([
+      EarnVaults.deriveZoneId(421_700_006),
+      EarnVaults.deriveZoneId(1_424_310_003),
+    ]).toStrictEqual([6, 3])
+  })
+
+  test('rejects a source chain ID', () => {
+    expect(() => EarnVaults.deriveZoneId(31_318)).toThrowErrorMatchingInlineSnapshot(
+      `[EarnVaults.InvalidRegistryError: Chain 31318 does not use a supported Zone chain-ID scheme.]`,
+    )
+  })
+})

package/src/internal/EarnVaults.test.ts

@@ -1,6 +1,7 @@
 import { parseAbi } from 'viem'
 import { tempoTestnet } from 'viem/tempo/chains'
 
+import * as TestEarn from '../../test/Earn.js'
 import * as Runtime from '../../test/runtime.js'
 import * as TestViem from '../../test/Viem.js'
 import * as Zones from '../apps/Zones.js'
@@ -43,6 +44,17 @@ describe('schema.ResolveInput', () => {
   })
 })
 
+describe('schema.ZoneRoute', () => {
+  test('normalizes the router address', () => {
+    expect(
+      EarnVaults.schema.ZoneRoute.parse({
+        ...TestEarn.zoneRoute,
+        earnRouter: TestEarn.zoneRoute.earnRouter.toUpperCase().replace('0X', '0x'),
+      }),
+    ).toStrictEqual(TestEarn.zoneRoute)
+  })
+})
+
 describe('classifyEngineType', () => {
   test('classifies supported capability fingerprints', () => {
     expect([
@@ -193,3 +205,70 @@ describe('resolve', () => {
     60_000,
   )
 })
+
+describe('resolveZoneRoutes', () => {
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'verifies immutable router bindings and derives private tokens',
+    async () => {
+      const getClient = Viem.createGetClient({
+        defaultChainId: tempoTestnet.id,
+        rpc: TestViem.rpc,
+        zones: [TestEarn.zone],
+      })
+      const discovery = await EarnVaults.resolve({
+        getClient,
+        input: {
+          chainId: tempoTestnet.id,
+          vaultAddress: TestEarn.zoneVaultAddress,
+        },
+        zones: [TestEarn.zone],
+      })
+      const routes = await EarnVaults.resolveZoneRoutes({
+        discovery,
+        getClient,
+        routes: [TestEarn.zoneRoute],
+        zones: [TestEarn.zone],
+      })
+
+      expect(routes).toHaveLength(1)
+      expect(routes[0]).toMatchObject({
+        ...TestEarn.zoneRoute,
+        name: TestEarn.zone.name,
+      })
+      expect(routes[0]?.inputTokens).toHaveLength(1)
+      expect(routes[0]?.outputTokens).toStrictEqual(routes[0]?.inputTokens)
+      await expect(
+        EarnVaults.resolveZoneRoutes({
+          discovery,
+          getClient,
+          routes: [TestEarn.zoneRoute, TestEarn.zoneRoute],
+          zones: [TestEarn.zone],
+        }),
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `[EarnVaults.InvalidRegistryError: Zone 1424310003 is configured more than once.]`,
+      )
+      await expect(
+        EarnVaults.resolveZoneRoutes({
+          discovery,
+          getClient,
+          routes: [
+            { ...TestEarn.zoneRoute, deploymentBlock: TestEarn.zoneRoute.deploymentBlock + 1 },
+          ],
+          zones: [TestEarn.zone],
+        }),
+      ).rejects.toMatchObject({
+        result: {
+          issues: [
+            {
+              actual: String(TestEarn.zoneRoute.deploymentBlock + 1),
+              code: 'zone-deployment-block-mismatch',
+              message: 'Earn router deployment block does not match its code boundary.',
+            },
+          ],
+          status: 'mismatch',
+        },
+      })
+    },
+    60_000,
+  )
+})

package/src/internal/EarnVaults.ts

@@ -1,3 +1,4 @@
+import { ZoneId } from 'ox/tempo'
 import {
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
@@ -161,6 +162,28 @@ export namespace schema {
     })
     .check(z.describe('Onchain identity of an Earn vault.'))
 
+  /** Schema for one curated Earn route through a private Zone. */
+  export const ZoneRoute = z
+    .strictObject({
+      chainId: Schema.ChainId.check(
+        z.describe('Private Zone chain id.'),
+        z.meta({ examples: [1424310003] }),
+      ),
+      deploymentBlock: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Parent-chain block that deployed the Earn router.'),
+          z.meta({ examples: [31730087] }),
+        ),
+      earnRouter: Schema.Address.check(
+        z.describe('Parent-chain router for this Zone and Earn vault.'),
+        z.meta({ examples: ['0xebedc74ffeead186acc6cac05eb82fb9e093a7c7'] }),
+      ),
+    })
+    .check(z.describe('Curated Earn route through one private Zone.'))
+
   /** Schema for live state resolved from one Earn vault. */
   export const Discovery = z
     .strictObject({
@@ -228,12 +251,48 @@ export type Discovery = z.output<typeof schema.Discovery>
 /** Onchain identity of an Earn vault. */
 export type ResolveInput = z.output<typeof schema.ResolveInput>
 
+/** Curated Earn route through one private Zone. */
+export type ZoneRoute = z.output<typeof schema.ZoneRoute>
+
+/** Curated Zone route with immutable router bindings resolved onchain. */
+export type ResolvedZoneRoute = ZoneRoute & {
+  /** Tokens accepted by private deposits. */
+  inputTokens: readonly Address[]
+  /** Configured private Zone name. */
+  name: string
+  /** Tokens returned by private redemptions. */
+  outputTokens: readonly Address[]
+}
+
+/** Adds capabilities proven by a verified private Zone route. */
+export function addZoneRouteCapabilities(
+  capabilities: NonNullable<Discovery['capabilities']>,
+): NonNullable<Discovery['capabilities']> {
+  return { ...capabilities, privateRouting: true, routerSwaps: true }
+}
+
+/** Derives a Zone ID from any supported Zone chain-ID scheme. */
+export function deriveZoneId(chainId: number): number {
+  for (const sourceId of [4_217, 42_431] satisfies readonly ZoneId.SourceId[]) {
+    const zoneId = ZoneId.fromChainId(chainId, sourceId)
+    if (zoneId >= 0 && ZoneId.toChainId(zoneId, sourceId) === chainId) return zoneId
+  }
+  throw new InvalidRegistryError(`Chain ${chainId} does not use a supported Zone chain-ID scheme.`)
+}
+
 /** Stable code describing an onchain verification issue. */
 export type VerificationIssueCode =
   | 'chain-mismatch'
   | 'engine-asset-mismatch'
   | 'policy-unsupported'
   | 'read-failed'
+  | 'zone-deployment-block-mismatch'
+  | 'zone-flow-unsupported'
+  | 'zone-id-mismatch'
+  | 'zone-router-invalid'
+  | 'zone-share-mismatch'
+  | 'zone-vault-asset-mismatch'
+  | 'zone-vault-mismatch'
 
 /** One onchain verification issue. */
 export type VerificationIssue = {
@@ -303,6 +362,16 @@ type RouterCapabilities = {
   redeem: boolean
 }
 
+type ZoneRouteBindings = {
+  allowedZoneId: number
+  deposit: boolean
+  earnShare: Address
+  earnVault: Address
+  privateAsset: Address
+  redeem: boolean
+  vaultAsset: Address
+}
+
 type TokenMetadata = Omit<Discovery['assetToken'], 'address'>
 
 const engineBindingsAbi = parseAbi(['function vault() view returns (address)'])
@@ -363,6 +432,139 @@ export declare namespace resolve {
   }
 }
 
+/** Resolves and verifies every curated Zone route for one Earn vault. */
+export async function resolveZoneRoutes(
+  options: resolveZoneRoutes.Options,
+): Promise<ResolvedZoneRoute[]> {
+  const result = z.array(schema.ZoneRoute).safeParse(options.routes)
+  if (!result.success) throw invalid(result.error)
+
+  const chainIds = new Set<number>()
+  const routers = new Set<string>()
+  for (const route of result.data) {
+    if (chainIds.has(route.chainId))
+      throw new InvalidRegistryError(`Zone ${route.chainId} is configured more than once.`)
+    if (routers.has(route.earnRouter))
+      throw new InvalidRegistryError(
+        `Earn router ${route.earnRouter} is configured more than once.`,
+      )
+    chainIds.add(route.chainId)
+    routers.add(route.earnRouter)
+  }
+  if (result.data.length === 0) return []
+
+  const client = options.getClient(options.discovery.chainId)
+  return Promise.all(
+    result.data.map(async (route) => {
+      const zone = options.zones.find((candidate) => candidate.id === route.chainId)
+      if (!zone) throw new InvalidRegistryError(`Zone ${route.chainId} is not configured.`)
+      if (zone.sourceId !== options.discovery.chainId)
+        throw new InvalidRegistryError(
+          `Zone ${route.chainId} does not belong to chain ${options.discovery.chainId}.`,
+        )
+      const expectedZoneId = deriveZoneId(route.chainId)
+
+      const [code, previousCode] = await Promise.all([
+        client.getCode({
+          address: route.earnRouter,
+          blockNumber: BigInt(route.deploymentBlock),
+        }),
+        route.deploymentBlock === 0
+          ? undefined
+          : client.getCode({
+              address: route.earnRouter,
+              blockNumber: BigInt(route.deploymentBlock - 1),
+            }),
+      ])
+      if (!code || code === '0x' || (previousCode !== undefined && previousCode !== '0x'))
+        throw mismatch({
+          discovery: options.discovery,
+          issues: [
+            {
+              actual: String(route.deploymentBlock),
+              code: 'zone-deployment-block-mismatch',
+              message: 'Earn router deployment block does not match its code boundary.',
+            },
+          ],
+        })
+
+      const bindings = await readZoneRouteBindings(client, { earnRouter: route.earnRouter }).catch(
+        (error) => {
+          if (!isMissingOptionalFunctionError(error)) throw error
+          throw mismatch({
+            discovery: options.discovery,
+            issues: [
+              {
+                actual: route.earnRouter,
+                code: 'zone-router-invalid',
+                message: 'Earn router does not expose the required immutable bindings.',
+              },
+            ],
+          })
+        },
+      )
+      const issues: VerificationIssue[] = []
+      if (bindings.allowedZoneId !== expectedZoneId)
+        issues.push({
+          actual: bindings.allowedZoneId.toString(),
+          code: 'zone-id-mismatch',
+          expected: String(expectedZoneId),
+          message: 'Earn router is configured for a different Zone.',
+        })
+      compareAddress(
+        issues,
+        'zone-vault-mismatch',
+        'Earn router is configured for a different Earn vault.',
+        options.discovery.vaultAddress,
+        bindings.earnVault,
+      )
+      compareAddress(
+        issues,
+        'zone-vault-asset-mismatch',
+        'Earn router vault asset does not match the Earn vault.',
+        options.discovery.assetToken.address,
+        bindings.vaultAsset,
+      )
+      compareAddress(
+        issues,
+        'zone-share-mismatch',
+        'Earn router share token does not match the Earn vault.',
+        options.discovery.shareToken.address,
+        bindings.earnShare,
+      )
+      if (!bindings.deposit || !bindings.redeem)
+        issues.push({
+          actual: `deposit=${bindings.deposit},redeem=${bindings.redeem}`,
+          code: 'zone-flow-unsupported',
+          expected: 'deposit=true,redeem=true',
+          message: 'Earn router must support private deposits and redemptions.',
+        })
+      if (issues.length > 0) throw mismatch({ discovery: options.discovery, issues })
+
+      return {
+        ...route,
+        inputTokens: [bindings.privateAsset],
+        name: zone.name,
+        outputTokens: [bindings.privateAsset],
+      }
+    }),
+  )
+}
+
+export declare namespace resolveZoneRoutes {
+  /** Inputs for resolving and verifying curated Zone routes. */
+  type Options = {
+    /** Live state of the Earn vault bound by every router. */
+    discovery: Discovery
+    /** Resolves the parent-chain client used to read each router. */
+    getClient: Viem.GetClient
+    /** Curated Zone routes to verify. */
+    routes: unknown
+    /** Private Zones configured by the API. */
+    zones: readonly Chain[]
+  }
+}
+
 /** Infers the supported engine type from its capability fingerprint. */
 export function classifyEngineType(
   options: classifyEngineType.Options,
@@ -729,6 +931,60 @@ declare namespace readEngineBindings {
   }
 }
 
+async function readZoneRouteBindings(
+  client: Client,
+  options: readZoneRouteBindings.Options,
+): Promise<ZoneRouteBindings> {
+  const [allowedZoneId, earnShare, earnVault, privateAsset, vaultAsset, deposit, redeem] =
+    await Promise.all([
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'allowedZoneId',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'earnShare',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'earnVault',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'privateAsset',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        functionName: 'vaultAsset',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        args: [0],
+        functionName: 'supportsFlow',
+      }),
+      client.readContract({
+        abi: Abis.earnRouter,
+        address: options.earnRouter,
+        args: [1],
+        functionName: 'supportsFlow',
+      }),
+    ])
+  return { allowedZoneId, deposit, earnShare, earnVault, privateAsset, redeem, vaultAsset }
+}
+
+declare namespace readZoneRouteBindings {
+  type Options = {
+    /** Parent-chain Earn router to inspect. */
+    earnRouter: Address
+  }
+}
+
 async function readRouterCapabilities(
   client: Client,
   options: readRouterCapabilities.Options,
@@ -840,6 +1096,27 @@ function compareAddress(
   if (!isAddressEqual(actual, expected)) issues.push({ actual, code, expected, message })
 }
 
+function mismatch(options: mismatch.Options): VerificationError {
+  return new VerificationError({
+    issues: options.issues,
+    snapshot: {
+      assetToken: options.discovery.assetToken,
+      isSynced: options.discovery.state.isAccountingAligned,
+      shareToken: options.discovery.shareToken,
+    },
+    status: 'mismatch',
+  })
+}
+
+declare namespace mismatch {
+  type Options = {
+    /** Live vault state captured with the mismatch. */
+    discovery: Discovery
+    /** Verification issues that rejected the deployment. */
+    issues: readonly VerificationIssue[]
+  }
+}
+
 function unavailable(): VerificationUnavailable {
   return {
     issues: [

package/src/internal/Fetch.test.ts

@@ -0,0 +1,46 @@
+import * as http from 'node:http'
+
+import * as Fetch from './Fetch.js'
+
+describe('withTimeout', () => {
+  test('aborts a fetch after the configured duration', async () => {
+    const server = http.createServer(() => {})
+    const url = await listen(server)
+
+    try {
+      const fetch = Fetch.withTimeout(globalThis.fetch, { timeout: 10 })
+      await expect(fetch(url)).rejects.toMatchObject({ name: 'TimeoutError' })
+    } finally {
+      server.closeAllConnections()
+      await close(server)
+    }
+  })
+})
+
+describe('resolveSignal', () => {
+  test('preserves caller and Request signals', () => {
+    const signal = AbortSignal.timeout(1_000)
+    const request = new Request('https://api.tempo.xyz', { signal })
+
+    expect(Fetch.resolveSignal('https://api.tempo.xyz', { init: { signal }, timeout: 10 })).toBe(
+      signal,
+    )
+    expect(Fetch.resolveSignal(request, { timeout: 10 })).toBe(request.signal)
+  })
+})
+
+function close(server: http.Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()))
+  })
+}
+
+function listen(server: http.Server): Promise<string> {
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address()
+      if (!address || typeof address === 'string') throw new Error('Expected a TCP server address.')
+      resolve(`http://127.0.0.1:${address.port}`)
+    })
+  })
+}