tapimo 0.0.0 → 0.0.2

package/src/internal/Auth.ts

@@ -0,0 +1,1012 @@
+import type { Context as hono_Context, Hono, MiddlewareHandler } from 'hono'
+import type { HonoBase } from 'hono/hono-base'
+import { createMiddleware } from 'hono/factory'
+import { matchedRoutes } from 'hono/route'
+import type { MergePath, RouterRoute, Schema as core_Schema } from 'hono/types'
+import { findTargetHandler } from 'hono/utils/handler'
+import { Credential, type Method } from 'mppx'
+import { Mppx, tempo } from 'mppx/hono'
+
+import * as ApiKeySource from '../ApiKeySource.js'
+import * as ApiKey from '../ApiKey.js'
+import * as OpenApi from './OpenApi.js'
+import * as RateLimit from './RateLimit.js'
+import * as Response from './Response.js'
+import * as Schema from './Schema.js'
+import * as Scope from '../Scope.js'
+import * as Viem from './Viem.js'
+
+const policySymbol = Symbol('tempo-api.auth.policy')
+
+/** Auth context consumed by Tempo API handlers. */
+export type Context = {
+  /** API key authentication configuration. */
+  apiKey?:
+    | {
+        /**
+         * API-key quotas keyed by quota scope. The reserved `'*'` entry is the
+         * config default; any other key sets that scope's quota. Mirrors the
+         * per-key {@link ApiKey.ApiKey.rateLimits} shape.
+         */
+        rateLimits?: Record<string, RateLimit.Limit> | undefined
+        /** Backing API-key source. */
+        source: ApiKeySource.Source
+      }
+    | undefined
+  /** MPP payment configuration. */
+  mpp?: Mpp | undefined
+  /** Rate-limit store used by API handlers. */
+  rateLimit?: RateLimit.Store | undefined
+}
+
+/** Hono environment variables set by auth middleware. */
+export type Environment = {
+  Variables: Variables
+}
+
+/**
+ * HTTP endpoint key inferred from a Hono app schema. The schema is matched
+ * against `HonoBase` (which carries it as its 2nd generic) rather than `Hono`
+ * (which re-declares only 3 generics and loses the inferred schema when used
+ * as a value type from `ReturnType<typeof create>`).
+ */
+export type Endpoint<app extends Hono<any, any>, mount extends string = '/'> =
+  app extends HonoBase<any, infer schema extends core_Schema, any>
+    ? endpoint.FromSchema<schema, mount>
+    : never
+
+/** Metadata for an accepted payment. */
+export type Payment = {
+  /** Verified MPP payer identifier. */
+  payer?: string | undefined
+  /** Why payment was required for the request. */
+  reason: 'api_key_over_quota' | 'public_over_quota'
+  /** Payment protocol kind. */
+  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 payment handler consumed by auth policies. */
+type Mpp = {
+  /** Creates a Hono middleware for a Tempo charge. */
+  charge(options: Charge): MiddlewareHandler
+}
+
+/**
+ * Route-level auth policy override. Each lane is independent: `true` enables it
+ * with the middleware defaults, `false` disables it, an object enables it with
+ * the given overrides, and omitting it inherits the resolved policy. Lanes are
+ * default-closed except `apiKey` (see {@link middleware}), so a route that
+ * declares nothing — or declares only `apiKey` — is API-key-only.
+ */
+export type PolicyOverride = {
+  /** API-key lane: pass quota/scopes overrides, or a boolean to enable/disable. */
+  apiKey?:
+    | {
+        /** API-key quota override for this route (a protective per-route cap). */
+        rateLimit?: RateLimit.Limit | undefined
+        /** Required API-key scopes override for this route. */
+        scopes?: readonly Scope.Id[] | undefined
+      }
+    | boolean
+    | undefined
+  /** MPP paid lane: object to override the charge, or boolean to enable/disable. */
+  mpp?:
+    | {
+        /** Tempo charge override for this route. */
+        charge?: Charge | undefined
+      }
+    | boolean
+    | undefined
+  /** Public lane: object to override the quota, or boolean to enable/disable. */
+  public?:
+    | {
+        /** Anonymous public quota override for this route. */
+        rateLimit?: RateLimit.Limit | undefined
+      }
+    | boolean
+    | undefined
+}
+
+/** Authenticated or anonymous caller. */
+export type Principal =
+  | {
+      /** Resolved API key. */
+      apiKey: ApiKey.ApiKey
+      /** Key environment (`production` accesses any chain; `sandbox` is non-mainnet only). */
+      environment: ApiKey.ApiKey['environment']
+      /** Principal id. */
+      id: string
+      /** Owning organization id. */
+      orgId: string
+      /** Payment metadata for paid overflow requests. */
+      payment?: Payment | undefined
+      /** Principal kind. */
+      type: 'api_key'
+    }
+  | {
+      /** Public quota identity. */
+      id: string
+      /** Payment metadata for paid overflow requests. */
+      payment?: Payment | undefined
+      /** Principal kind. */
+      type: 'public'
+    }
+
+/** Hono variables set by auth middleware. */
+export type Variables = {
+  /** Auth context consumed by protected handlers. */
+  auth: Context
+  /** Authenticated or anonymous caller. */
+  principal?: Principal | undefined
+}
+
+/** Reads the authenticated principal from a Hono context. */
+export function getPrincipal<environment extends Environment>(c: hono_Context<environment>) {
+  return c.get('principal') ?? null
+}
+
+/**
+ * Always false at runtime, but typed as `boolean` so handlers can include a
+ * never-reached access-error branch in Hono's inferred response union.
+ */
+export const narrowAccess = false as boolean
+
+/** Typed auth/payment error response for Hono client inference. Never reached at runtime. */
+export function accessError(c: hono_Context) {
+  const status = Number(c.req.header('tempo-narrow-access-status'))
+  if (status === 400)
+    return Response.error(c, {
+      code: 'api_key_malformed',
+      message: 'Malformed API key',
+      status: 400,
+    })
+  if (status === 401) {
+    const code =
+      c.req.header('tempo-narrow-access-code') === 'api_key_missing'
+        ? 'api_key_missing'
+        : 'api_key_invalid'
+    return Response.error(c, {
+      code,
+      message: 'Missing or invalid API key',
+      status: 401,
+    })
+  }
+  if (status === 403)
+    return Response.error(c, {
+      code: 'api_key_forbidden',
+      message: 'API key missing required scope',
+      status: 403,
+    })
+  const code =
+    c.req.header('tempo-narrow-access-code') === 'rate_limit_exceeded'
+      ? 'rate_limit_exceeded'
+      : 'payment_required'
+  return Response.error(c, {
+    code,
+    message: 'Payment required or rate limit exceeded',
+    status: 429,
+  })
+}
+
+/** Typed auth/payment error response for Hono client inference. Never reached at runtime. */
+export function paidAccessError(c: hono_Context) {
+  const status = Number(c.req.header('tempo-narrow-access-status'))
+  if (status !== 402) return accessError(c)
+  // MPP owns the 402 challenge body and headers; it is intentionally not the
+  // API's JSON error envelope.
+  return c.body(null, 402)
+}
+
+/** Creates auth middleware for protected OpenAPI routes. */
+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 defaults = laneDefaults(options)
+  const base = basePolicy(options, defaults)
+  // Resolution is cached per isolate by default (positive 60s / negative 10s,
+  // keyed by token sha256 — see `ApiKeySource.cached`) so hot keys skip the
+  // backend read on the auth path of every request. Pass `apiKey.cache: false`
+  // when instant revocation matters more than the per-request read.
+  const source = (() => {
+    if (options.apiKey === false || !options.apiKey?.source) return ApiKeySource.noop
+    if (options.apiKey.cache === false) return options.apiKey.source
+    return ApiKeySource.cached(options.apiKey.source, options.apiKey.cache)
+  })()
+  const auth: Context = {
+    ...(options.apiKey === false
+      ? {}
+      : {
+          apiKey: {
+            ...(options.apiKey?.rateLimits ? { rateLimits: options.apiKey.rateLimits } : {}),
+            source,
+          },
+        }),
+    ...(options.mpp === false
+      ? {}
+      : {
+          mpp: Mppx.create({
+            ...mpp,
+            methods: [tempo.charge({ amount: '0.001', ...charge })],
+            secretKey: mpp.secretKey ?? crypto.randomUUID(),
+          }),
+        }),
+    rateLimit: RateLimit.memory(options.rateLimit),
+  }
+
+  return createMiddleware<environment>((c, next) => {
+    const route = openApiRoute(c)
+    if (!route) return next()
+
+    const { key, description } = route
+    const overrides = options.overrides as
+      | Record<string, PolicyOverride | false | undefined>
+      | undefined
+    const endpointPolicy = resolvePolicy(
+      base,
+      defaults,
+      [...policies(c), overrides?.[key]],
+      description,
+    )
+    if (!endpointPolicy) return next()
+
+    c.set('auth', auth)
+    return require<environment>(endpointPolicy)(c, next)
+  })
+}
+
+export declare namespace middleware {
+  /** Per-route policy overrides keyed by HTTP endpoint. */
+  type Overrides<endpoint extends string = string> = Partial<
+    Record<NoInfer<endpoint>, PolicyOverride | false | undefined>
+  >
+
+  /** Options for creating auth middleware. */
+  type Options<endpoint extends string = string> = {
+    /** Default API-key access policy. Pass false to disable API-key access. */
+    apiKey?:
+      | {
+          /**
+           * Resolve-cache tuning for the source (per-isolate, positive 60s /
+           * negative 10s by default), or `false` to resolve uncached on every
+           * request — e.g. when instant revocation matters more than the
+           * per-request backend read.
+           */
+          cache?: ApiKeySource.cached.Options | false | undefined
+          /** API-key quotas keyed by quota scope (reserved `'*'` is the config default). */
+          rateLimits?: Record<string, RateLimit.Limit> | undefined
+          /** Backing API-key source. Defaults to an empty source (rejects all). */
+          source?: ApiKeySource.Source | undefined
+          /** Required API-key scopes. */
+          scopes?: readonly Scope.Id[] | undefined
+        }
+      | false
+      | undefined
+    /** MPP payment options. Pass false to disable paid overflow. */
+    mpp?: MppOptions | false | undefined
+    /** Per-route policy overrides keyed by HTTP endpoint, e.g. `GET /tokens/:token`. */
+    overrides?: Overrides<endpoint> | undefined
+    /** Default public access policy. Pass false to disable anonymous access. */
+    public?:
+      | {
+          /** Anonymous public quota for protected routes. */
+          rateLimit?: RateLimit.Limit | undefined
+        }
+      | false
+      | undefined
+    /** Rate-limit store options. */
+    rateLimit?: RateLimit.memory.Options | undefined
+  }
+
+  /** 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
+  }
+}
+
+/** Creates route middleware that contributes an auth policy override. */
+export function policy(options: PolicyOverride): MiddlewareHandler {
+  const middleware = createMiddleware((_, next) => next()) as MiddlewareHandler & PolicyHandler
+  middleware[policySymbol] = options
+  return middleware
+}
+
+export declare namespace endpoint {
+  /**
+   * HTTP endpoint key inferred from a Hono app schema. Distributes over the
+   * schema union so the `BlankSchema | MergeSchemaPath<...>` shape Hono
+   * produces from `.basePath(...).route(...)` chains contributes its typed
+   * routes (a non-distributing mapped type would collapse `BlankSchema` to
+   * `never` and infect the whole union).
+   */
+  type FromSchema<schema extends core_Schema, mount extends string = '/'> = schema extends infer s
+    ? {
+        [path in keyof s & string]: {
+          [method in keyof s[path] &
+            `$${string}`]: `${Method<method>} ${Path<MergePath<mount, path>>}`
+        }[keyof s[path] & `$${string}`]
+      }[keyof s & string]
+    : never
+
+  /** HTTP method string extracted from Hono's schema method key. */
+  type Method<method extends string> = method extends `$${infer value}` ? Uppercase<value> : never
+
+  /** Public endpoint path with Hono route regex constraints removed. */
+  type Path<path extends string> = path extends `${infer head}/${infer tail}`
+    ? `${Segment<head>}/${Path<tail>}`
+    : Segment<path>
+
+  /** Public endpoint path segment with any regex constraint removed. */
+  type Segment<segment extends string> = segment extends `:${infer parameter}{${string}`
+    ? `:${parameter}`
+    : segment
+}
+
+/** Per-lane default config a route inherits when it enables a lane. */
+type LaneDefaults = {
+  apiKey: NonNullable<require.Policy['apiKey']>
+  mpp: NonNullable<require.Policy['mpp']>
+  public: NonNullable<require.Policy['public']>
+}
+
+type OpenApiHandler = {
+  [OpenApi.uniqueSymbol]?: OpenApi.HandlerUniqueProperty | undefined
+}
+
+type OpenApiRoute = {
+  key: string
+  description: string | undefined
+}
+
+type PolicyHandler = {
+  [policySymbol]?: PolicyOverride | undefined
+}
+
+function laneDefaults(options: middleware.Options): LaneDefaults {
+  const apiKey = options.apiKey === false ? undefined : options.apiKey
+  const public_ = options.public === false ? undefined : options.public
+  return {
+    apiKey: {
+      // `rateLimit` is intentionally omitted: `policy.apiKey.rateLimit` means an
+      // explicit per-route cap (precedence tier 2), not the config default. The
+      // config default (tier 5) lives on `auth.apiKey.rateLimits['*']` and is
+      // applied by `resolveApiKeyLimit` at consume time.
+      //
+      // Default-closed to a full-access key: a route that declares no scopes
+      // requires the `'*'` wildcard, so a narrowly-scoped key only reaches
+      // routes that explicitly grant its scope. Routes opt into specific
+      // catalog scopes via `Auth.policy`.
+      scopes: apiKey?.scopes ?? [Scope.wildcard],
+    },
+    mpp: { charge: {} },
+    public: { rateLimit: public_?.rateLimit ?? { perMinute: 60 } },
+  }
+}
+
+/**
+ * Base policy before route overrides. Default-closed except the API-key lane:
+ * a route that declares nothing is API-key-only, and must opt into the public
+ * and paid lanes explicitly. This makes a partial override fail safe — omitting
+ * a lane leaves it closed rather than silently inheriting open access.
+ */
+function basePolicy(options: middleware.Options, defaults: LaneDefaults): require.Policy {
+  return options.apiKey === false ? {} : { apiKey: defaults.apiKey }
+}
+
+function resolvePolicy(
+  base: require.Policy,
+  defaults: LaneDefaults,
+  overrides: readonly (PolicyOverride | false | undefined)[],
+  description: string | undefined,
+): require.Policy | undefined {
+  let apiKey = base.apiKey
+  let mpp = base.mpp
+  let public_ = base.public
+
+  for (const override of overrides) {
+    if (override === false) return undefined
+    if (!override) continue
+    apiKey = resolveApiKeyLane(apiKey, override.apiKey, defaults.apiKey)
+    mpp = resolveMppLane(mpp, override.mpp, defaults.mpp)
+    public_ = resolvePublicLane(public_, override.public, defaults.public)
+  }
+
+  // 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 (!apiKey && !mpp && !public_) return undefined
+  return {
+    ...(apiKey ? { apiKey } : {}),
+    ...(mpp ? { mpp } : {}),
+    ...(public_ ? { public: public_ } : {}),
+  }
+}
+
+function resolveApiKeyLane(
+  current: require.Policy['apiKey'],
+  override: PolicyOverride['apiKey'],
+  default_: LaneDefaults['apiKey'],
+): require.Policy['apiKey'] {
+  if (override === undefined) return current
+  if (override === false) return undefined
+  if (override === true) return current ?? default_
+  const base = current ?? default_
+  return {
+    rateLimit: override.rateLimit ?? base.rateLimit,
+    scopes: override.scopes ?? base.scopes,
+  }
+}
+
+function resolveMppLane(
+  current: require.Policy['mpp'],
+  override: PolicyOverride['mpp'],
+  default_: LaneDefaults['mpp'],
+): require.Policy['mpp'] {
+  if (override === undefined) return current
+  if (override === false) return undefined
+  if (override === true) return current ?? default_
+  const base = current ?? default_
+  return { charge: { ...base.charge, ...override.charge } }
+}
+
+function resolvePublicLane(
+  current: require.Policy['public'],
+  override: PolicyOverride['public'],
+  default_: LaneDefaults['public'],
+): require.Policy['public'] {
+  if (override === undefined) return current
+  if (override === false) return undefined
+  if (override === true) return current ?? default_
+  const base = current ?? default_
+  return { rateLimit: override.rateLimit ?? base.rateLimit }
+}
+
+function openApiRoute(c: hono_Context): OpenApiRoute | undefined {
+  const route = matchedRoutes(c)
+    .slice(c.req.routeIndex + 1)
+    .find((route) => !!openApiSpec(route))
+  if (!route) return undefined
+
+  const spec = openApiSpec(route)
+  if (!spec) return undefined
+
+  const description = typeof spec.summary === 'string' ? spec.summary : spec.description
+  return {
+    key: endpointKey(c, route),
+    description: typeof description === 'string' ? description : undefined,
+  }
+}
+
+function policies(c: hono_Context) {
+  return matchedRoutes(c)
+    .slice(c.req.routeIndex + 1)
+    .map(policyFromRoute)
+    .filter((policy): policy is PolicyOverride => policy !== undefined)
+}
+
+function openApiSpec(route: RouterRoute) {
+  const handler = findTargetHandler(route.handler) as OpenApiHandler
+  const metadata = handler[OpenApi.uniqueSymbol]
+  if (!metadata || !('spec' in metadata)) return undefined
+  return metadata.spec
+}
+
+function policyFromRoute(route: RouterRoute) {
+  const handler = findTargetHandler(route.handler) as PolicyHandler
+  return handler[policySymbol]
+}
+
+/** Resolved access lanes for one documented operation. */
+export type OperationAccess = {
+  /** Whether MPP payment is accepted (enables the `402` payment-challenge response). */
+  mpp: boolean
+  /** Whether anonymous public-quota access is allowed (keeps the anonymous security option). */
+  public: boolean
+  /** Required API-key scopes (`[]` accepts any valid key); empty when the API-key lane is disabled. */
+  scopes: readonly Scope.Id[]
+}
+
+/**
+ * Maps each documented operation id to its resolved access lanes by reading the
+ * `policy` overrides co-located on the app's routes. This is the single source
+ * of truth for per-operation `security` and the `402` response in the generated
+ * OpenAPI document (see `App.create`): the API-key lane is default-on, and the
+ * public/MPP lanes apply only where a route opts in via {@link policy}.
+ */
+export function describeAccess(app: Hono<any, any>): Record<string, OperationAccess> {
+  const groups = new Map<string, { operationId?: string; overrides: PolicyOverride[] }>()
+  for (const route of app.routes) {
+    const key = `${route.method} ${route.path}`
+    const group = groups.get(key) ?? { overrides: [] }
+    const spec = openApiSpec(route) as { operationId?: unknown } | undefined
+    if (typeof spec?.operationId === 'string') group.operationId = spec.operationId
+    const override = policyFromRoute(route)
+    if (override) group.overrides.push(override)
+    groups.set(key, group)
+  }
+
+  const access: Record<string, OperationAccess> = {}
+  for (const { operationId, overrides } of groups.values()) {
+    if (!operationId) continue
+    let apiKey = true
+    let scopes: readonly Scope.Id[] = []
+    let public_ = false
+    let mpp = false
+    for (const override of overrides) {
+      if (override.apiKey !== undefined) apiKey = override.apiKey !== false
+      if (override.apiKey && override.apiKey !== true && override.apiKey.scopes)
+        scopes = override.apiKey.scopes
+      if (override.public !== undefined) public_ = override.public !== false
+      if (override.mpp !== undefined) mpp = override.mpp !== false
+    }
+    access[operationId] = { mpp, public: public_, scopes: apiKey ? scopes : [] }
+  }
+  return access
+}
+
+function endpointKey(c: hono_Context, route: RouterRoute) {
+  return `${route.method.toUpperCase()} ${stripBasePath(normalizeRoutePath(route.path), basePath(c))}`
+}
+
+function normalizeRoutePath(path: string) {
+  // Hono stores regex-constrained params as `:name{...}`. Auth overrides use
+  // the stable public route shape, e.g. `GET /tokens/:symbol`.
+  return path
+    .split('/')
+    .map((segment) => {
+      if (!segment.startsWith(':')) return segment
+      const pattern = segment.indexOf('{')
+      return pattern === -1 ? segment : segment.slice(0, pattern)
+    })
+    .join('/')
+}
+
+function stripBasePath(path: string, basePath: string | undefined) {
+  if (!basePath || basePath === '/') return path
+  if (path === basePath) return '/'
+  if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length)
+  return path
+}
+
+function basePath(c: hono_Context) {
+  const variables = c.var as Record<string, unknown>
+  return typeof variables['basePath'] === 'string' ? variables['basePath'] : undefined
+}
+
+/** Requires route access through API key, public quota, or MPP payment. */
+export function require<environment extends Environment = Environment>(
+  policy: require.Policy,
+): MiddlewareHandler<environment> {
+  return createMiddleware<environment>(async (c, next) => {
+    const auth = c.get('auth')
+    const credential = getApiKeyCredential(c)
+    // The deprecated `key` query param has now been consumed for auth. Strip it
+    // from the request URL so it never reaches a route's query validator —
+    // endpoint query schemas are `z.strictObject`, so an unexpected `key`
+    // param would otherwise fail validation with `query_invalid`, breaking the
+    // legacy `?key=...` lane on every strict-query endpoint.
+    stripLegacyAuthQuery(c)
+    if (credential === false)
+      return jsonError(c, {
+        code: 'api_key_malformed',
+        message: 'Malformed API key',
+        status: 400,
+      })
+
+    const hasPayment = hasPaymentCredential(c) && isPaymentEnabled(auth, policy)
+    if (credential) {
+      const apiKey = await auth.apiKey?.source.resolve(credential.token)
+      if (!apiKey)
+        return jsonError(c, {
+          code: 'api_key_invalid',
+          message: 'Invalid API key',
+          status: 401,
+        })
+
+      // Sandbox keys are restricted to non-mainnet chains. An explicit
+      // `chainId` of mainnet makes the key unusable for this request, so it is
+      // ignored and the request falls through to the public policy below (as if
+      // no key were presented). A request that omits `chainId` is steered to
+      // testnet so a sandbox key still "just works" without passing `?chainId`.
+      const explicitChain = explicitChainId(c)
+      const sandboxOnMainnet =
+        apiKey.environment === 'sandbox' &&
+        explicitChain !== undefined &&
+        Viem.isMainnet(explicitChain)
+
+      if (!sandboxOnMainnet) {
+        if (
+          apiKey.environment === 'sandbox' &&
+          explicitChain === undefined &&
+          Viem.isMainnet((c.get('chainId' as never) as number | undefined) ?? Viem.defaultChainId)
+        )
+          // `chainId` lives on the app's `Variables`, not the narrower auth
+          // contract, so it is read/written through an untyped cast.
+          c.set('chainId' as never, Viem.chainId.testnet as never)
+
+        const principal = principalFromApiKey(apiKey)
+        c.set('principal', principal)
+        const missing = apiKey.scopes.includes(Scope.wildcard)
+          ? []
+          : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? [])
+        if (missing.length > 0)
+          return jsonError(c, {
+            code: 'api_key_forbidden',
+            message: 'API key missing required scope',
+            status: 403,
+          })
+
+        if (hasPayment)
+          return requirePayment(c, next, {
+            auth,
+            payment: { reason: 'api_key_over_quota', type: 'mpp' },
+            policy,
+            principal,
+          })
+
+        if (policy.apiKey) {
+          // A route consumes exactly one quota bucket: its single required scope,
+          // else `'*'` (zero scopes). Routes today require at most one scope; a
+          // future multi-scope route buckets against its first scope.
+          const scope = policy.apiKey.scopes[0] ?? Scope.wildcard
+          const limit = resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope })
+          const result = await consumeRateLimit(auth, {
+            key: `api_key:${apiKey.id}:scope:${scope}`,
+            limit,
+          })
+          if (result) {
+            setRateLimitHeaders(c, result)
+            // Surface the bucket so callers can correlate a 429 with the exhausted
+            // quota. Set before the over-quota branch so it rides the 429 (an MPP
+            // 402 challenge is owned by mppx and drops these headers — by design).
+            c.header('RateLimit-Scope', scope)
+          }
+          if (result && !result.allowed)
+            return requirePaymentOrRateLimit(c, next, {
+              auth,
+              payment: { reason: 'api_key_over_quota', type: 'mpp' },
+              policy,
+              principal,
+              rateLimit: result,
+            })
+        }
+
+        return next()
+      }
+    }
+
+    const publicPrincipal = principalFromPublic(c)
+    if (hasPayment) {
+      c.set('principal', publicPrincipal)
+      return requirePayment(c, next, {
+        auth,
+        payment: { reason: 'public_over_quota', type: 'mpp' },
+        policy,
+        principal: publicPrincipal,
+      })
+    }
+
+    const limit = policy.public?.rateLimit
+    if (limit) {
+      const result = await consumeRateLimit(auth, {
+        key: `public:${publicPrincipal.id}`,
+        limit,
+      })
+      if (result) setRateLimitHeaders(c, result)
+      if (!result || result.allowed) {
+        c.set('principal', publicPrincipal)
+        return next()
+      }
+
+      c.set('principal', publicPrincipal)
+      return requirePaymentOrRateLimit(c, next, {
+        auth,
+        payment: { reason: 'public_over_quota', type: 'mpp' },
+        policy,
+        principal: publicPrincipal,
+        rateLimit: result,
+      })
+    }
+
+    if (isPaymentEnabled(auth, policy)) {
+      c.set('principal', publicPrincipal)
+      return requirePayment(c, next, {
+        auth,
+        payment: { reason: 'public_over_quota', type: 'mpp' },
+        policy,
+        principal: publicPrincipal,
+      })
+    }
+
+    return jsonError(c, {
+      code: 'api_key_missing',
+      message: 'Missing API key',
+      status: 401,
+    })
+  })
+}
+
+export declare namespace require {
+  /** Route access policy. */
+  type Policy = {
+    /** API-key access policy. */
+    apiKey?:
+      | {
+          /** API-key quota override for this route (a protective per-route cap). */
+          rateLimit?: RateLimit.Limit | undefined
+          /**
+           * Required API-key scopes. Defaults to `['*']`, so a route that does
+           * not declare scopes requires a full-access key; narrow it by listing
+           * catalog scopes via {@link policy}.
+           */
+          scopes: readonly (Scope.Id | typeof Scope.wildcard)[]
+        }
+      | undefined
+    /** MPP payment access policy. */
+    mpp?:
+      | {
+          /** Tempo charge policy. */
+          charge: Charge
+        }
+      | undefined
+    /** Public access policy. */
+    public?:
+      | {
+          /** Anonymous public quota for this route. */
+          rateLimit: RateLimit.Limit
+        }
+      | undefined
+  }
+}
+
+type ApiKeyCredential = {
+  token: string
+}
+
+type PaymentAccess = {
+  auth: Context
+  payment: Omit<Payment, 'payer'>
+  policy: require.Policy
+  principal: Principal
+}
+
+type RateLimitAccess = PaymentAccess & {
+  rateLimit: RateLimit.Result
+}
+
+function consumeRateLimit(
+  auth: Context,
+  options: RateLimit.Store.ConsumeOptions,
+): Promise<RateLimit.Result | null> {
+  if (!auth.rateLimit) return Promise.resolve(null)
+  // Fail open: a rate-limit store error (e.g. a lost Durable Object
+  // connection) degrades to unenforced quota instead of failing the request.
+  return auth.rateLimit.consume(options).catch((error) => {
+    console.error('[auth] rate-limit consume failed; failing open', error)
+    return null
+  })
+}
+
+/**
+ * Resolves the rate limit for an API-key request against a quota bucket.
+ * Most-specific wins: a per-key per-scope grant is the only thing that pierces a
+ * route's protective cap; the per-key `'*'` default does not (so a premium key
+ * can't silently blow past an expensive endpoint's ceiling). Per-key values live
+ * in the optional {@link ApiKey.ApiKey.rateLimits} map and stay `undefined` until a
+ * record source populates them, so until then only tiers 2/4/5/6 apply.
+ */
+function resolveApiKeyLimit(options: resolveApiKeyLimit.Options): RateLimit.Limit {
+  const { apiKey, auth, policy, scope } = options
+  return (
+    apiKey.rateLimits?.[scope] ?? // 1. per-key, per-scope
+    policy?.rateLimit ?? // 2. route override (protective cap)
+    apiKey.rateLimits?.[Scope.wildcard] ?? // 3. per-key default
+    auth.apiKey?.rateLimits?.[scope] ?? // 4. config per-scope
+    auth.apiKey?.rateLimits?.[Scope.wildcard] ?? { perMinute: 100 } // 5. config default // 6. hardcoded fallback
+  )
+}
+
+declare namespace resolveApiKeyLimit {
+  type Options = {
+    /** Resolved API key (carries per-key overrides). */
+    apiKey: ApiKey.ApiKey
+    /** Auth context (carries config defaults). */
+    auth: Context
+    /** Route API-key policy (carries the per-route cap). */
+    policy: require.Policy['apiKey']
+    /** Quota bucket the request consumes. */
+    scope: string
+  }
+}
+
+function getApiKeyCredential(c: hono_Context): ApiKeyCredential | false | null {
+  const header = c.req.header('tempo-api-key')
+  if (header) return { token: header }
+
+  // `Authorization: Bearer` compatibility fallback. Must not consume or reject
+  // `Authorization: Payment` (MPP), which is a distinct credential — a request
+  // carrying only a payment scheme falls through to the deprecated lanes below
+  // (which find nothing) and resolves to no API-key credential.
+  const authorization = c.req.header('authorization')
+  if (authorization && !Credential.extractPaymentScheme(authorization)) {
+    const match = /^Bearer\s+(.+)$/i.exec(authorization)
+    if (!match?.[1]) return false
+    return { token: match[1] }
+  }
+
+  // Deprecated fallbacks carried over from the v1 API so existing integrations
+  // keep authenticating: the `x-api-key` header and the `key` query parameter.
+  const legacyHeader = c.req.header('x-api-key')
+  if (legacyHeader) return { token: legacyHeader }
+
+  const legacyQuery = c.req.query('key')
+  if (legacyQuery) return { token: legacyQuery }
+
+  return null
+}
+
+/**
+ * Remove the deprecated `key` auth query param from the request URL once it has
+ * been read for authentication. Route query schemas are strict
+ * (`z.strictObject`), so leaving `key` in the query string would make the
+ * downstream validator reject the request as `query_invalid`. Stripping it
+ * keeps the legacy `?key=...` auth lane working on strict-query endpoints
+ * (e.g. `GET /v1/tokens`).
+ */
+function stripLegacyAuthQuery(c: hono_Context) {
+  const url = new URL(c.req.url)
+  if (!url.searchParams.has('key')) return
+  url.searchParams.delete('key')
+  c.req.raw = new Request(url, c.req.raw)
+}
+
+/**
+ * Reads an explicit `chainId`/`chain_id` query parameter, normalized to a
+ * numeric chain id. Returns `undefined` when absent or malformed (a malformed
+ * value falls through to the route's own validation). Mirrors the resolution in
+ * `App.create`'s unsupported-chain guard.
+ */
+function explicitChainId(c: hono_Context): number | undefined {
+  const raw = c.req.query('chainId') ?? c.req.query('chain_id')
+  if (raw === undefined) return undefined
+  const parsed = Schema.ChainId.safeParse(raw)
+  return parsed.success ? parsed.data : undefined
+}
+
+function getRequestId(c: hono_Context) {
+  const variables = c.var as Record<string, unknown>
+  return typeof variables['requestId'] === 'string' ? variables['requestId'] : undefined
+}
+
+function hasPaymentCredential(c: hono_Context) {
+  const authorization = c.req.header('authorization')
+  if (!authorization) return false
+  return !!Credential.extractPaymentScheme(authorization)
+}
+
+function isPaymentEnabled(auth: Context, policy: require.Policy) {
+  return !!auth.mpp && !!policy.mpp
+}
+
+function jsonError(c: hono_Context, options: jsonError.Options) {
+  const requestId = getRequestId(c)
+  // Auth error envelopes embed per-request state and must not be cached.
+  c.header('Cache-Control', 'no-store')
+  c.set('errorCode', options.code)
+  return c.json(
+    {
+      error: {
+        code: options.code,
+        message: options.message,
+      },
+      ...(requestId === undefined ? {} : { requestId }),
+    },
+    options.status,
+  )
+}
+
+declare namespace jsonError {
+  type Options = {
+    code: string
+    message: string
+    status: 400 | 401 | 403 | 429
+  }
+}
+
+function payer(c: hono_Context) {
+  try {
+    return Credential.fromRequest(c.req.raw).source
+  } catch {
+    return undefined
+  }
+}
+
+function principalFromApiKey(apiKey: ApiKey.ApiKey): Principal {
+  return {
+    apiKey,
+    environment: apiKey.environment,
+    id: apiKey.id,
+    orgId: apiKey.orgId,
+    type: 'api_key',
+  }
+}
+
+function principalFromPublic(c: hono_Context): Principal {
+  const forwarded = c.req.header('x-forwarded-for')?.split(',')[0]?.trim()
+  return {
+    id:
+      c.req.header('cf-connecting-ip') ??
+      c.req.header('x-real-ip') ??
+      forwarded ??
+      c.req.header('x-test-client-ip') ??
+      'anonymous',
+    type: 'public',
+  }
+}
+
+async function requirePayment<environment extends Environment>(
+  c: hono_Context<environment>,
+  next: () => Promise<void>,
+  options: PaymentAccess,
+) {
+  const middleware = options.auth.mpp?.charge(options.policy.mpp?.charge ?? {})
+  if (!middleware)
+    return jsonError(c, {
+      code: 'payment_required',
+      message: 'Payment required',
+      status: 429,
+    })
+
+  return middleware(c, async () => {
+    const payer_ = payer(c)
+    c.set('principal', {
+      ...options.principal,
+      payment: {
+        ...options.payment,
+        ...(payer_ === undefined ? {} : { payer: payer_ }),
+      },
+    })
+    await next()
+  })
+}
+
+function requirePaymentOrRateLimit<environment extends Environment>(
+  c: hono_Context<environment>,
+  next: () => Promise<void>,
+  options: RateLimitAccess,
+) {
+  if (isPaymentEnabled(options.auth, options.policy)) return requirePayment(c, next, options)
+
+  c.header(
+    'Retry-After',
+    String(Math.max(options.rateLimit.reset - Math.ceil(Date.now() / 1_000), 1)),
+  )
+  return jsonError(c, {
+    code: 'rate_limit_exceeded',
+    message: 'Rate limit exceeded',
+    status: 429,
+  })
+}
+
+function setRateLimitHeaders(c: hono_Context, result: RateLimit.Result) {
+  c.header('RateLimit-Limit', String(result.limit))
+  c.header('RateLimit-Remaining', String(result.remaining))
+  c.header('RateLimit-Reset', String(result.reset))
+}