tapimo 0.4.3 → 0.5.0

package/src/internal/Auth.ts

@@ -7,8 +7,9 @@ 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'
 
 import type * as App from '../App.js'
@@ -30,6 +31,8 @@ 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. */
 export type Context = {
@@ -47,7 +50,7 @@ export type Context = {
       }
     | undefined
   /** MPP payment configuration. */
-  mpp?: Mpp | undefined
+  mpp?: MppHandler | undefined
   /**
    * Configured default anonymous public quota. Used as the throttle ceiling for
    * sandbox keys without active billing on routes that expose no public lane
@@ -89,22 +92,29 @@ export type Payment = {
   type: 'mpp'
 }
 
-/** MPP charge options used by route access policies. */
-export type Charge = Method.RequestDefaults<ReturnType<typeof tempo.charge>> & {
-  /** Optional human-readable payment description. */
-  description?: string | undefined
-  /** Optional challenge expiration timestamp or date. */
-  expires?: Date | string | undefined
-  /** Optional server-defined correlation data. */
-  meta?: Record<string, string> | undefined
-  /** Optional route/resource scope bound to the challenge. */
-  scope?: string | undefined
+/** MPP route-policy types. Distinct from the SIWE {@link Session} capability. */
+export declare namespace Mpp {
+  /** MPP Session request options used by route access policies. */
+  type Session = Method.RequestDefaults<ReturnType<typeof tempo.session>> & {
+    /** Optional human-readable payment description. */
+    description?: string | undefined
+    /** Optional challenge expiration timestamp or date. */
+    expires?: Date | string | undefined
+    /** Optional server-defined correlation data. */
+    meta?: Record<string, string> | undefined
+    /** Optional route/resource scope bound to the challenge. */
+    scope?: string | undefined
+  }
 }
 
 /** MPP payment handler consumed by auth policies. */
-type Mpp = {
-  /** Creates a Hono middleware for a Tempo charge. */
-  charge(options: Charge): MiddlewareHandler
+type MppHandler = {
+  /** Paid-request quota per access principal. */
+  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
 }
 
 /**
@@ -127,11 +137,13 @@ export type PolicyOverride = {
       }
     | boolean
     | undefined
-  /** MPP paid lane: object to override the charge, or boolean to enable/disable. */
+  /** MPP paid lane: object to override the Session request, or boolean to enable/disable. */
   mpp?:
     | {
-        /** Tempo charge override for this route. */
-        charge?: Charge | undefined
+        /** Paid-request quota override for this route (a protective per-route cap). */
+        rateLimit?: RateLimit.Limit | undefined
+        /** Tempo Session request override for this route. */
+        session?: Mpp.Session | undefined
       }
     | boolean
     | undefined
@@ -273,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
@@ -297,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()
@@ -465,7 +483,12 @@ export function middleware<
   endpoint extends string = string,
   environment extends Environment = Environment,
 >(options: middleware.Options<endpoint>): MiddlewareHandler<environment> {
-  const { charge = {}, ...mpp } = options.mpp === false ? {} : (options.mpp ?? {})
+  const {
+    rateLimit: mppRateLimit = defaultMppRateLimit,
+    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.
@@ -503,11 +526,25 @@ export function middleware<
     ...(options.mpp === false
       ? {}
       : {
-          mpp: Mppx.create({
-            ...mpp,
-            methods: [tempo.charge({ amount: '0.001', ...charge })],
-            secretKey: mpp.secretKey ?? crypto.randomUUID(),
-          }),
+          mpp: {
+            rateLimit: mppRateLimit,
+            session: Mppx.create({
+              ...mpp,
+              ...(secretKey ? { secretKey } : {}),
+              // Defaults only; global `session` options may override, including
+              // enabling same-route HEAD bootstrap.
+              methods: [
+                tempo.session({
+                  amount: '0.0001',
+                  bootstrap: false,
+                  currency: Addresses.pathUsd,
+                  unitType: 'request',
+                  ...session_,
+                }),
+              ],
+            }).session,
+            sessionChainId: (c) => paymentSessionChainId(c, secretKey),
+          },
         }),
     rateLimit: RateLimit.memory(options.rateLimit),
     ...(options.session ? { session: options.session } : {}),
@@ -520,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)
@@ -600,8 +639,10 @@ export declare namespace middleware {
 
   /** MPP payment options used by auth middleware. */
   type MppOptions = Omit<NonNullable<Parameters<typeof Mppx.create>[0]>, 'methods'> & {
-    /** Global Tempo charge options passed to the MPP method instantiator. */
-    charge?: NonNullable<Parameters<typeof tempo.charge>[0]> | undefined
+    /** 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. */
+    session?: NonNullable<Parameters<typeof tempo.session>[0]> | undefined
   }
 }
 
@@ -975,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
@@ -1021,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
@@ -1043,7 +1156,7 @@ function laneDefaults(options: middleware.Options): LaneDefaults {
       // catalog scopes via `Auth.policy`.
       scopes: apiKey?.scopes ?? [Scope.wildcard],
     },
-    mpp: { charge: {} },
+    mpp: { session: {} },
     public: { rateLimit: public_?.rateLimit ?? { perMinute: 60 } },
     session: true,
   }
@@ -1072,8 +1185,8 @@ function resolvePolicy(
   // The OpenAPI summary/description rides along as the payment-challenge
   // description. It is metadata, not a policy override, so it only applies when
   // the paid lane is actually enabled and has no explicit description already.
-  if (mpp && description !== undefined && mpp.charge.description === undefined)
-    mpp = { charge: { ...mpp.charge, description } }
+  if (mpp && description !== undefined && mpp.session.description === undefined)
+    mpp = { ...mpp, session: { ...mpp.session, description } }
 
   // A lane-less policy stays enforced for super admin; only an explicit
   // `false` override opts a route out of auth entirely.
@@ -1085,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'],
@@ -1109,7 +1233,10 @@ function resolveMppLane(
   if (override === false) return undefined
   if (override === true) return current ?? default_
   const base = current ?? default_
-  return { charge: { ...base.charge, ...override.charge } }
+  return {
+    rateLimit: override.rateLimit ?? base.rateLimit,
+    session: { ...base.session, ...override.session },
+  }
 }
 
 function resolvePublicLane(
@@ -1135,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)
@@ -1147,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}`,
   }
 }
 
@@ -1169,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. */
@@ -1223,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) {
@@ -1483,8 +1627,10 @@ export declare namespace require {
     /** MPP payment access policy. */
     mpp?:
       | {
-          /** Tempo charge policy. */
-          charge: Charge
+          /** Paid-request quota override for this route (a protective per-route cap). */
+          rateLimit?: RateLimit.Limit | undefined
+          /** Tempo Session request policy. */
+          session: Mpp.Session
         }
       | undefined
     /** Public access policy. */
@@ -1663,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
 }
@@ -1729,7 +1909,28 @@ async function requirePayment<environment extends Environment>(
   next: () => Promise<void>,
   options: PaymentAccess,
 ) {
-  const middleware = options.auth.mpp?.charge(options.policy.mpp?.charge ?? {})
+  if (hasPaymentCredential(c)) {
+    const result = await consumeRateLimit(options.auth, {
+      key: `mpp:${options.principal.type}:${options.principal.id}`,
+      limit: options.policy.mpp?.rateLimit ?? options.auth.mpp?.rateLimit ?? defaultMppRateLimit,
+    })
+    if (result) {
+      setRateLimitHeaders(c, result)
+      c.header('RateLimit-Scope', 'mpp')
+      if (!result.allowed) return rateLimitExceeded(c, result)
+    }
+  }
+
+  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 {