tapimo 0.4.4 → 0.5.0

package/src/internal/Auth.ts

@@ -7,7 +7,7 @@ import { matchedRoutes } from 'hono/route'
 import type { MergePath, RouterRoute, Schema as core_Schema } from 'hono/types'
 import { findTargetHandler } from 'hono/utils/handler'
 import { decodeJwt } from 'jose'
-import { Credential, type Method } from 'mppx'
+import { Challenge, Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
 import { Addresses } from 'viem/tempo'
 import * as z from 'zod/mini'
@@ -31,6 +31,7 @@ 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')
 const defaultMppRateLimit = { perMinute: 100 } satisfies RateLimit.Limit
 
 /** Auth context consumed by Tempo API handlers. */
@@ -112,6 +113,8 @@ type MppHandler = {
   rateLimit?: RateLimit.Limit | undefined
   /** Creates a Hono middleware for a Tempo Session payment. */
   session(options: Mpp.Session): MiddlewareHandler
+  /** Resolves the chain from a challenge issued by this server. */
+  sessionChainId?: ((c: hono_Context) => number | undefined) | undefined
 }
 
 /**
@@ -282,7 +285,7 @@ export declare namespace ensureOrg {
 }
 
 /**
- * Guards `:projectId` routes and resolves the project. Flat routes authorize against its organization; nested routes preserve the scope from {@link ensureOrg}.
+ * Resolves `:projectId`, preserving nested organization scope. Sessions require membership; API keys require organization ownership and matching project attribution when present.
  */
 export function ensureProject(): MiddlewareHandler {
   // Typed loosely (like {@link policy}) so route chains keep their inferred
@@ -306,6 +309,12 @@ export function ensureProject(): MiddlewareHandler {
     const db = Db.get(contextDb(c))
     const record = await Projects.get(db, projectId)
     if (!record) return notFound()
+    if (
+      principal.type === 'api_key' &&
+      principal.projectId !== undefined &&
+      principal.projectId !== record.id
+    )
+      return notFound()
     const scoped = c.get('org')
     if (scoped) {
       if (record.orgId !== scoped.id) return notFound()
@@ -479,6 +488,7 @@ export function middleware<
     session: session_ = {},
     ...mpp
   } = options.mpp === false ? {} : (options.mpp ?? {})
+  const secretKey = resolveMppSecretKey(mpp.secretKey)
   const defaults = laneDefaults(options)
   // Default-deny: no lanes open until a route grants them via `policy`.
   // Otherwise the `super_admin` principal bypasses lane checks entirely.
@@ -520,6 +530,7 @@ export function middleware<
             rateLimit: mppRateLimit,
             session: Mppx.create({
               ...mpp,
+              ...(secretKey ? { secretKey } : {}),
               // Defaults only; global `session` options may override, including
               // enabling same-route HEAD bootstrap.
               methods: [
@@ -532,6 +543,7 @@ export function middleware<
                 }),
               ],
             }).session,
+            sessionChainId: (c) => paymentSessionChainId(c, secretKey),
           },
         }),
     rateLimit: RateLimit.memory(options.rateLimit),
@@ -545,17 +557,19 @@ export function middleware<
     const route = openApiRoute(c)
     if (!route) return next()
 
-    const { key, description } = route
+    const { key, description, management, scope } = route
     const overrides = options.overrides as
       | Record<string, PolicyOverride | false | undefined>
       | undefined
-    const endpointPolicy = resolvePolicy(
-      base,
-      defaults,
-      [...policies(c), overrides?.[key]],
-      description,
+    const configuredOverride = overrides?.[key]
+    const routeOverride =
+      management && configuredOverride ? { mpp: configuredOverride.mpp } : configuredOverride
+    const endpointPolicy = bindMppScope(
+      resolvePolicy(base, defaults, [...policies(c), routeOverride], description),
+      scope,
     )
     if (!endpointPolicy) return next()
+    if (management && (!auth.mpp || !endpointPolicy.mpp)) return next()
 
     c.set('auth', auth)
     return require<environment>(endpointPolicy)(c, next)
@@ -1002,6 +1016,55 @@ export function policy(options: PolicyOverride): MiddlewareHandler {
   return middleware
 }
 
+/** Adds management POSTs for OpenAPI-registered MPP GET resources. */
+export function installMppManagementRoutes(
+  app: Hono<any, any>,
+  options: MppManagementOptions = {},
+) {
+  const routes = [...app.routes]
+  const postPaths = new Set(
+    routes.filter((route) => route.method === 'POST').map((route) => route.path),
+  )
+  const targets = new Map<string, MppManagementTarget>()
+
+  for (const route of routes) {
+    if (route.method !== 'GET') continue
+    const target = targets.get(route.path) ?? { path: route.path }
+    const override = policyFromRoute(route)
+    if (override?.mpp !== undefined)
+      target.mpp = resolveMppLane(target.mpp, override.mpp, { session: {} })
+
+    const spec = openApiSpec(route) as MppManagementSpec | undefined
+    if (spec) {
+      target.registered = true
+      const description = typeof spec.summary === 'string' ? spec.summary : spec.description
+      if (typeof description === 'string') target.description = description
+    }
+    targets.set(route.path, target)
+  }
+
+  for (const target of targets.values()) {
+    const key = `GET ${stripBasePath(normalizeRoutePath(target.path), options.basePath)}`
+    const override = options.overrides?.[key]
+    if (override === false) continue
+    const mpp =
+      override?.mpp === undefined
+        ? target.mpp
+        : resolveMppLane(target.mpp, override.mpp, { session: {} })
+    if (!target.registered || !mpp) continue
+    if (postPaths.has(target.path))
+      throw new Error(`MPP management POST conflicts with an existing route: ${target.path}`)
+
+    const management = policy({ mpp }) as MiddlewareHandler & MppManagementHandler
+    management[mppManagementSymbol] = { description: target.description }
+    app.post(
+      stripBasePath(target.path, options.basePath),
+      management,
+      OpenApi.describeRoute({ hide: true }),
+    )
+  }
+}
+
 export declare namespace endpoint {
   /**
    * HTTP endpoint key inferred from a Hono app schema. Distributes over the
@@ -1048,12 +1111,35 @@ type OpenApiHandler = {
 type OpenApiRoute = {
   key: string
   description: string | undefined
+  management: boolean
+  scope: string
 }
 
 type PolicyHandler = {
   [policySymbol]?: PolicyOverride | undefined
 }
 
+type MppManagementHandler = {
+  [mppManagementSymbol]?: { description?: string | undefined } | undefined
+}
+
+type MppManagementOptions = {
+  basePath?: string | undefined
+  overrides?: Record<string, PolicyOverride | false | undefined> | undefined
+}
+
+type MppManagementSpec = {
+  description?: unknown
+  summary?: unknown
+}
+
+type MppManagementTarget = {
+  description?: string | undefined
+  mpp?: NonNullable<require.Policy['mpp']> | undefined
+  path: string
+  registered?: boolean | undefined
+}
+
 function laneDefaults(options: middleware.Options): LaneDefaults {
   const apiKey = options.apiKey === false ? undefined : options.apiKey
   const public_ = options.public === false ? undefined : options.public
@@ -1112,6 +1198,17 @@ function resolvePolicy(
   }
 }
 
+function bindMppScope(policy: require.Policy | undefined, scope: string) {
+  if (!policy?.mpp || policy.mpp.session.scope !== undefined) return policy
+  return {
+    ...policy,
+    mpp: {
+      ...policy.mpp,
+      session: { ...policy.mpp.session, scope },
+    },
+  }
+}
+
 function resolveApiKeyLane(
   current: require.Policy['apiKey'],
   override: PolicyOverride['apiKey'],
@@ -1165,9 +1262,19 @@ function resolveSessionLane(
 }
 
 function openApiRoute(c: hono_Context): OpenApiRoute | undefined {
-  const route = matchedRoutes(c)
-    .slice(c.req.routeIndex + 1)
-    .find((route) => !!openApiSpec(route))
+  const routes = matchedRoutes(c).slice(c.req.routeIndex + 1)
+  const managementRoute = routes.find((route) => !!mppManagementFromRoute(route))
+  if (managementRoute) {
+    const management = mppManagementFromRoute(managementRoute)!
+    return {
+      key: endpointKey(c, managementRoute, 'GET'),
+      description: management.description,
+      management: true,
+      scope: `GET ${managementRoute.path}`,
+    }
+  }
+
+  const route = routes.find((route) => !!openApiSpec(route))
   if (!route) return undefined
 
   const spec = openApiSpec(route)
@@ -1177,6 +1284,8 @@ function openApiRoute(c: hono_Context): OpenApiRoute | undefined {
   return {
     key: endpointKey(c, route),
     description: typeof description === 'string' ? description : undefined,
+    management: false,
+    scope: `${route.method.toUpperCase()} ${route.path}`,
   }
 }
 
@@ -1199,6 +1308,11 @@ function policyFromRoute(route: RouterRoute) {
   return handler[policySymbol]
 }
 
+function mppManagementFromRoute(route: RouterRoute) {
+  const handler = findTargetHandler(route.handler) as MppManagementHandler
+  return handler[mppManagementSymbol]
+}
+
 /** Resolved access lanes for one documented operation. */
 export type OperationAccess = {
   /** Whether API-key access is allowed. */
@@ -1253,8 +1367,8 @@ export function describeAccess(app: Hono<any, any>): Record<string, OperationAcc
   return access
 }
 
-function endpointKey(c: hono_Context, route: RouterRoute) {
-  return `${route.method.toUpperCase()} ${stripBasePath(normalizeRoutePath(route.path), basePath(c))}`
+function endpointKey(c: hono_Context, route: RouterRoute, method = route.method) {
+  return `${method.toUpperCase()} ${stripBasePath(normalizeRoutePath(route.path), basePath(c))}`
 }
 
 function normalizeRoutePath(path: string) {
@@ -1695,6 +1809,40 @@ function hasPaymentCredential(c: hono_Context) {
   return !!Credential.extractPaymentScheme(authorization)
 }
 
+function paymentSessionChainId(c: hono_Context, secretKey: string | undefined): number | undefined {
+  if (!secretKey) return undefined
+  try {
+    const credential = Credential.fromRequest(c.req.raw)
+    if (!Challenge.verify(credential.challenge, { secretKey })) return undefined
+    if (credential.challenge.method !== 'tempo' || credential.challenge.intent !== 'session')
+      return undefined
+    const details = credential.challenge.request['methodDetails']
+    if (!details || typeof details !== 'object') return undefined
+    const chainId = (details as Record<string, unknown>)['chainId']
+    return typeof chainId === 'number' ? chainId : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function resolveMppSecretKey(explicit: string | undefined): string | undefined {
+  if (explicit) return explicit
+  try {
+    const value = typeof process === 'undefined' ? undefined : process.env['MPP_SECRET_KEY']
+    if (value) return value
+  } catch {}
+  try {
+    const deno = (
+      globalThis as typeof globalThis & {
+        Deno?: { env?: { get?: (name: string) => string | undefined } | undefined } | undefined
+      }
+    ).Deno
+    return deno?.env?.get?.('MPP_SECRET_KEY') || undefined
+  } catch {
+    return undefined
+  }
+}
+
 function isPaymentEnabled(auth: Context, policy: require.Policy) {
   return !!auth.mpp && !!policy.mpp
 }
@@ -1773,7 +1921,16 @@ async function requirePayment<environment extends Environment>(
     }
   }
 
-  const middleware = options.auth.mpp?.session(options.policy.mpp?.session ?? {})
+  const session = options.policy.mpp?.session ?? {}
+  const chainId =
+    explicitChainId(c) ??
+    (c.req.method === 'POST' && session.scope?.startsWith('GET ')
+      ? options.auth.mpp?.sessionChainId?.(c)
+      : undefined)
+  const middleware = options.auth.mpp?.session({
+    ...session,
+    ...(chainId === undefined ? {} : { chainId }),
+  })
   if (!middleware)
     return jsonError(c, {
       code: 'payment_required',

package/src/internal/EdgeCache.test.ts

@@ -1,4 +1,4 @@
-import { Hono } from 'hono'
+import { type Context, Hono } from 'hono'
 import { createMiddleware } from 'hono/factory'
 import * as EdgeCache from './EdgeCache.js'
 import type * as Store from './Store.js'
@@ -189,6 +189,19 @@ describe('middleware', () => {
 
     expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
   })
+
+  test('rechecks route eligibility before every cache lookup', async () => {
+    let eligible = true
+    const { app, downstreamCalls, store } = createApp({ eligibility: () => eligible })
+
+    await app.request('/cached')
+    eligible = false
+    await app.request('/cached')
+
+    expect(downstreamCalls()).toBe(2)
+    expect(store.gets).toBe(1)
+    expect(store.size).toBe(1)
+  })
 })
 
 type Environment = { Variables: EdgeCache.Variables }
@@ -221,7 +234,12 @@ function memoryStore() {
   } satisfies Store.Store & { readonly gets: number; readonly size: number }
 }
 
-function createApp(options: { store?: Store.Store | undefined } = {}) {
+function createApp(
+  options: {
+    eligibility?: ((c: Context<Environment>) => boolean) | undefined
+    store?: Store.Store | undefined
+  } = {},
+) {
   const store = memoryStore()
   const edgeStore = 'store' in options ? options.store : store
   let downstream = 0
@@ -234,9 +252,12 @@ function createApp(options: { store?: Store.Store | undefined } = {}) {
   })
   // Routes publishing a policy mount a marked middleware, as `Cache.response`
   // routes do; unmarked routes must skip the lookup entirely.
-  const cacheable = EdgeCache.markCacheable(
+  const cacheable_marked = EdgeCache.markCacheable(
     createMiddleware<Environment>(async (_c, next) => next()),
   )
+  const cacheable = options.eligibility
+    ? EdgeCache.setEligibility(cacheable_marked, options.eligibility)
+    : cacheable_marked
   app.get('/cached', cacheable, (c) => {
     c.set('edgeCache', { maxAge: 30, staleWhileRevalidate: 300 })
     c.header('Age', '123')

package/src/internal/EdgeCache.ts

@@ -135,6 +135,7 @@ export function middleware<environment extends Env>(
 // Marks handlers whose route publishes an edge-cache policy; the middleware
 // pays the store lookup only when a matched handler carries it.
 const cacheableSymbol = Symbol('tempoApi.edgeCacheable')
+const eligibility = new WeakMap<object, (c: Context) => boolean>()
 
 /**
  * Marks a route handler/middleware as publishing an edge-cache policy, so
@@ -147,9 +148,24 @@ export function markCacheable<const handler extends (...args: never[]) => unknow
   return Object.assign(handler, { [cacheableSymbol]: true })
 }
 
-// True when any handler matched for this request is marked cacheable.
+/** Adds a request eligibility check to a cacheable route handler. */
+export function setEligibility<const handler extends (...args: never[]) => unknown>(
+  handler: handler,
+  predicate: (c: Context) => boolean,
+): handler {
+  if (cacheableSymbol in handler) eligibility.set(handler, predicate)
+  return handler
+}
+
+// True when a marked handler matches and every marked handler permits caching.
 function isCacheableRoute(c: Context): boolean {
-  return matchedRoutes(c).some((route) => cacheableSymbol in route.handler)
+  let cacheable = false
+  for (const route of matchedRoutes(c)) {
+    if (!(cacheableSymbol in route.handler)) continue
+    cacheable = true
+    if (eligibility.get(route.handler)?.(c) === false) return false
+  }
+  return cacheable
 }
 
 export declare namespace middleware {

package/src/internal/FundingQuotes.test.ts

@@ -0,0 +1,174 @@
+import * as FundingQuotes from './FundingQuotes.js'
+
+const baseUsdcRequest = {
+  provider: 'relay',
+  sourceAmount: '1000000',
+  sourceAmountUnits: 'baseUnits',
+  sourceChain: 'base',
+  sourceToken: 'USDC',
+} as const
+
+describe('listQuotes', () => {
+  test('returns normalized successful provider quotes', async () => {
+    let seen: FundingQuotes.QuoteProbeInput | undefined
+    const quotes = await FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote(input, signal) {
+            seen = input
+            expect(signal.aborted).toBe(false)
+            return {
+              minimumOutputAmount: '980000',
+              outputAmount: '990000',
+              quality: {
+                estimatedSeconds: 4,
+                liquiditySource: 'providerQuote',
+                sourceDetail: 'providerEndpoint',
+                tier: 'liquid',
+              },
+              sampledAt: '2026-01-01T00:00:00Z',
+              status: 'available',
+            }
+          },
+        },
+      },
+    })
+
+    expect(seen?.candidate.id).toBe('base-usdc-tempo-usdce-relay')
+    expect(quotes).toHaveLength(1)
+    expect(quotes[0]).toMatchObject({
+      id: 'base-usdc-tempo-usdce-relay',
+      quality: {
+        liquiditySource: 'providerQuote',
+        tier: 'liquid',
+      },
+      quote: {
+        inputAmount: '1000000',
+        minimumOutputAmount: '980000',
+        outputAmount: '990000',
+        outputAmountFormatted: '0.99',
+      },
+    })
+  })
+
+  test('returns no static candidates when no adapter is configured', async () => {
+    await expect(FundingQuotes.listQuotes(baseUsdcRequest)).resolves.toEqual([])
+  })
+
+  test('omits provider-declared unavailable quotes', async () => {
+    const quotes = FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote() {
+            return { sampledAt: '2026-01-01T00:00:00Z', status: 'unavailable' }
+          },
+        },
+      },
+    })
+
+    await expect(quotes).resolves.toEqual([])
+  })
+
+  test('rejects provider failures when no quote succeeds', async () => {
+    const quotes = FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote() {
+            throw new Error('upstream unavailable')
+          },
+        },
+      },
+    })
+
+    await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[FundingQuotes.ProviderQuoteError]`,
+    )
+  })
+
+  test('rejects successful provider responses without output amounts', async () => {
+    const quotes = FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote() {
+            return { sampledAt: '2026-01-01T00:00:00Z', status: 'available' }
+          },
+        },
+      },
+    })
+
+    await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[FundingQuotes.ProviderQuoteError]`,
+    )
+  })
+
+  test('aborts providers that exceed the quote deadline', async () => {
+    let aborted = false
+    const quotes = FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapterTimeoutMs: 1,
+      adapters: {
+        relay: {
+          probeQuote(_input, signal) {
+            signal.addEventListener('abort', () => {
+              aborted = true
+            })
+            return new Promise<FundingQuotes.QuoteProbeResult>(() => {})
+          },
+        },
+      },
+    })
+
+    await expect(quotes).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[FundingQuotes.ProviderQuoteError]`,
+    )
+    expect(aborted).toBe(true)
+  })
+
+  test('passes cache policy through to providers', async () => {
+    let seen: FundingQuotes.QuoteProbeInput | undefined
+    await FundingQuotes.listQuotes({
+      ...baseUsdcRequest,
+      adapters: {
+        relay: {
+          async probeQuote(input) {
+            seen = input
+            return { sampledAt: '2026-01-01T00:00:00Z', status: 'unavailable' }
+          },
+        },
+      },
+      cache: { bypass: true },
+    })
+
+    expect(seen?.cache.bypass).toBe(true)
+  })
+})
+
+describe('listChains', () => {
+  test('returns only chain and token inputs with quote inventory', () => {
+    expect(FundingQuotes.listChains().map((chain) => chain.id)).toEqual([
+      'eip155:1',
+      'eip155:8453',
+      'eip155:56',
+    ])
+  })
+})
+
+describe('listProviders', () => {
+  test('reports deployment configuration', () => {
+    expect(FundingQuotes.listProviders()).toMatchInlineSnapshot(`
+      [
+        {
+          "id": "relay",
+          "kind": "solverNetwork",
+          "name": "Relay",
+          "requiresApiKey": false,
+          "status": "unconfigured",
+        },
+      ]
+    `)
+  })
+})