tapimo 0.15.0 → 0.18.0

package/src/internal/Auth.ts

@@ -20,11 +20,11 @@ import * as z from 'zod/mini'
 import type * as App from '../App.js'
 import * as ApiKey from '../ApiKey.js'
 import * as ApiKeys from '../ApiKeys.js'
-import * as ApiKeyAdmissions from '../db/tables/apiKeyAdmissions.js'
-import * as ApiKeyOwnerTombstones from '../db/tables/apiKeyOwnerTombstones.js'
 import * as AuthAccounts from '../db/tables/authAccounts.js'
 import * as BetterAuth from './BetterAuth.js'
+import * as CliAuth from './CliAuth.js'
 import * as Db from '../db/Db.js'
+import * as ExecutionContext from './ExecutionContext.js'
 import type * as Email from './Email.js'
 import * as Memberships from '../db/tables/memberships.js'
 import * as IpAllowlist from './IpAllowlist.js'
@@ -44,29 +44,32 @@ import type * as Viem from './Viem.js'
 
 const policySymbol = Symbol('tempo-api.auth.policy')
 const mppManagementSymbol = Symbol('tempo-api.auth.mpp-management')
+const trustedClientIps = new WeakMap<Request, string>()
 const defaultApiKeyRateLimit = { limit: 10_000, period: 'minute' } satisfies RateLimit.Limit
 const defaultIdentitySessionTtl = 24 * 60 * 60
 const defaultMppRateLimit = { limit: 100, period: 'minute' } satisfies RateLimit.Limit
 const defaultPublicRateLimit = { limit: 60, period: 'minute' } satisfies RateLimit.Limit
 const identityCookieName = 'tempo_identity'
+const privacyUrl = 'https://tempo.xyz/privacy-policy/'
+const termsUrl = 'https://console.tempo.xyz/legal/terms'
 const walletIdentityIssuer = 'https://wallet.tempo.xyz/api/oidc'
 
-type IdentitySession = {
-  /** Wallet address asserted by the identity token. */
-  address: string
-  /** Verified email asserted by the identity token. */
-  email?: string | undefined
+type IdentitySession = WalletSession & {
   /** Unix timestamp when the session expires. */
   expiresAt: number
   /** Unix timestamp when the session was issued. */
   issuedAt: number
+  /** Immutable user bound when the session was issued. */
+  userId: string
 }
 
 type WalletSession = {
   /** Wallet address used to resolve the canonical user. */
   address: string
-  /** Verified email used to reconcile the canonical user. */
+  /** Verified email asserted when the session was issued. */
   email?: string | undefined
+  /** Immutable user binding, absent only in legacy sessions. */
+  userId?: string | undefined
 }
 
 function isIdentityTokenError(error: unknown) {
@@ -144,7 +147,18 @@ export type Payment = {
 }
 
 /** Host-provided request backstop that returns a rejection response when over quota. */
-export type EdgeRateLimit = (request: Request) => Promise<Response | undefined>
+export type EdgeRateLimit = (
+  request: Request,
+  options: EdgeRateLimit.Options,
+) => Promise<Response | undefined>
+
+export namespace EdgeRateLimit {
+  /** Request-specific edge backstop options. */
+  export type Options = {
+    /** Resolves a confirmed credential partition when the shared network limit rejects the request. */
+    resolvePartition?: (() => Promise<string | undefined>) | undefined
+  }
+}
 
 /** MPP route-policy types. Distinct from the authentication {@link Session} capability. */
 export declare namespace Mpp {
@@ -186,6 +200,8 @@ export type PolicyOverride = {
   /** API-key lane: pass quota/scopes overrides, or a boolean to enable/disable. */
   apiKey?:
     | {
+        /** Optional counter bucket that isolates this route's quota. */
+        bucket?: string | undefined
         /** API-key quota override for this route (a protective per-route cap). */
         rateLimit?: RateLimit.Limit | undefined
         /** Required API-key scopes override for this route. */
@@ -196,6 +212,8 @@ export type PolicyOverride = {
   /** MPP paid lane: object to override the Session request, or boolean to enable/disable. */
   mpp?:
     | {
+        /** Optional counter bucket that isolates this route's quota. */
+        bucket?: string | undefined
         /** Paid-request quota override for this route (a protective per-route cap). */
         rateLimit?: RateLimit.Limit | undefined
         /** Tempo Session request override for this route. */
@@ -206,6 +224,8 @@ export type PolicyOverride = {
   /** Public lane: object to override the quota, or boolean to enable/disable. */
   public?:
     | {
+        /** Optional counter bucket that isolates this route's quota. */
+        bucket?: string | undefined
         /** Anonymous public quota override for this route. */
         rateLimit?: RateLimit.Limit | undefined
       }
@@ -215,6 +235,9 @@ export type PolicyOverride = {
   session?: boolean | undefined
 }
 
+/** Credential kind a request presented, recorded before it is resolved. */
+export type CredentialKind = 'api_key' | 'payment'
+
 /** Authenticated or anonymous caller. */
 export type Principal =
   | {
@@ -242,15 +265,17 @@ export type Principal =
       type: 'public'
     }
   | {
+      /** Approved API-key scopes and expiry for a console-authorized CLI device. */
+      cli?: { expiresAt: string; scopes: readonly string[] } | undefined
       /** Verified email bound to the session, when present. */
       email?: string | undefined
       /** Principal id: the user id (`usr_…`). */
       id: string
       /** Identity that established the session, as a provider/subject pair (OIDC `iss`/`sub` semantics). */
       identity: {
-        /** Identity provider: `email`, `wallet`, or an OIDC issuer. */
+        /** Identity provider: `email`, `wallet`, `cli` (a console-approved CLI session), or an OIDC issuer. */
         provider: string
-        /** Provider-scoped subject — the wallet address for `wallet`. */
+        /** Provider-scoped subject: the wallet address for `wallet`, the CLI session id (`cli_…`) for `cli`. */
         subject: string
       }
       /** Payment metadata for paid overflow requests. */
@@ -273,6 +298,8 @@ export type Principal =
 export type Variables = {
   /** Auth context consumed by protected handlers. */
   auth: Context
+  /** Credential kind the request presented, set before resolution so stalled requests stay attributable. */
+  credential?: CredentialKind | undefined
   /** Caller's membership resolved by {@link ensureOrg} or {@link ensureProject}; absent for API keys and `super_admin`. */
   membership?: Memberships.Record | undefined
   /** Organization resolved by {@link ensureOrg} or {@link ensureProject} for the current request. */
@@ -288,6 +315,17 @@ export function getPrincipal<environment extends Environment>(c: hono_Context<en
   return c.get('principal') ?? null
 }
 
+/** Resolves the caller IP from configured trusted metadata. */
+export function getTrustedClientIp<environment extends Environment>(c: hono_Context<environment>) {
+  const auth = c.get('auth')
+  return auth ? trustedClientIp(c, auth) : resolveTrustedClientIp(c.req.raw, undefined)
+}
+
+/** Marks a synthesized in-process request with its trusted caller IP address. */
+export function trustClientIp(request: Request, address: string) {
+  trustedClientIps.set(request, address)
+}
+
 /**
  * Guards `:orgId` routes and resolves the organization. Sessions require membership, API keys require ownership, and the super admin bypasses ownership.
  */
@@ -627,7 +665,7 @@ function createAuthMiddleware<
             ...(sessionChainIds ? { sessionChainIds: new Set(sessionChainIds) } : {}),
           },
         }),
-    rateLimit: RateLimit.memory(options.rateLimit),
+    rateLimit: rateLimitStore(options.rateLimit),
     ...(options.session ? { session: options.session } : {}),
     ...(options.superAdmin?.secret
       ? { superAdmin: { tokenHash: ApiKey.hash(options.superAdmin.secret) } }
@@ -635,6 +673,8 @@ function createAuthMiddleware<
   }
 
   return createMiddleware<environment>((c, next) => {
+    // Every route records its credential, including unprotected and unmatched paths.
+    recordCredential(c, getApiKeyCredential(c))
     const resolved = resolveRequestPolicy(c, { base, defaults, options })
     if (!resolved) return next()
 
@@ -666,8 +706,9 @@ function resolveRequestPolicy(c: hono_Context, options: resolveRequestPolicy.Opt
     const inheritedKey = `${inheritedMethod.toUpperCase()} ${key.slice(key.indexOf(' ') + 1)}`
     return overrides?.[inheritedKey]
   })()
-  const routeOverride =
-    management && configuredOverride ? { mpp: configuredOverride.mpp } : configuredOverride
+  // Generated management routes already materialize the GET's MPP contract.
+  // Reapplying its override would also copy GET-only quota controls.
+  const routeOverride = management ? undefined : configuredOverride
   return {
     management,
     policy: bindMppScope(
@@ -692,8 +733,6 @@ declare namespace resolveRequestPolicy {
 type ApiKeyResolverOptions = {
   /** API-key authentication and cache configuration. */
   apiKey: middleware.Options['apiKey']
-  /** Authoritative owner store used to reject orphaned API keys. */
-  db?: Db.Source | undefined
   /** Scope catalog accepted while resolving records. */
   scopeCatalog: Scope.Catalog | undefined
 }
@@ -707,16 +746,27 @@ type RequestApiKeyResolution = {
 
 function createApiKeyResolver(options: ApiKeyResolverOptions) {
   const requests = new WeakMap<hono_Context, RequestApiKeyResolution>()
-  const uncached = (c: hono_Context, token: string) => {
+  // Requests whose key came from KV in this request: `ApiKeys.resolve` already
+  // read the fences, so reading them again adds a round trip and nothing else.
+  const fenced = new WeakMap<hono_Context, string>()
+  const uncached = async (c: hono_Context, token: string) => {
     const kv = contextKv(c)
-    return kv
-      ? ApiKeys.resolve(kv.store, token, { scopeCatalog: options.scopeCatalog })
-      : Promise.resolve(null)
+    if (!kv) return null
+    const apiKey = await ApiKeys.resolve(kv.store, token, { scopeCatalog: options.scopeCatalog })
+    fenced.set(c, ApiKey.hash(token))
+    return apiKey
   }
   const cache =
     options.apiKey === false || options.apiKey?.cache === false
       ? { invalidate: () => {}, peek: () => undefined, resolve: uncached }
       : cachedResolve(uncached, options.apiKey?.cache ?? {})
+  // A cached record still checks its fences every request, so revocation and
+  // owner deletion never wait for the isolate cache to expire.
+  const active = async (c: hono_Context, token: string, apiKey: ApiKey.ApiKey | null) => {
+    const kv = contextKv(c)
+    if (!apiKey || !kv || fenced.get(c) === ApiKey.hash(token)) return apiKey
+    return (await ApiKeys.isFenced(kv.store, apiKey)) ? null : apiKey
+  }
 
   return {
     peek: (c: hono_Context, token: string) => {
@@ -725,18 +775,16 @@ function createApiKeyResolver(options: ApiKeyResolverOptions) {
       if (existing?.tokenHash === tokenHash) return existing.apiKey
       return cache.peek(token)
     },
+    probe: async (c: hono_Context, token: string) => {
+      // Probes must not warm the resolution cache before rate-limit admission.
+      return active(c, token, await uncached(c, token))
+    },
     resolve: async (c: hono_Context, token: string) => {
       const tokenHash = ApiKey.hash(token)
       const existing = requests.get(c)
       if (existing?.tokenHash === tokenHash) return existing.apiKey
       const cached = await cache.resolve(c, token)
-      const kv = contextKv(c)
-      const apiKey =
-        cached &&
-        ((kv && (await ApiKeys.isOwnerDeleted(kv.store, cached))) ||
-          !(await apiKeyOwnerExists(cached, options.db)))
-          ? null
-          : cached
+      const apiKey = await active(c, token, cached)
       if (cached && !apiKey) cache.invalidate(token)
       requests.set(c, { apiKey, tokenHash })
       return apiKey
@@ -744,15 +792,6 @@ function createApiKeyResolver(options: ApiKeyResolverOptions) {
   }
 }
 
-/** Rejects attributed keys fenced by a committed owner deletion. */
-async function apiKeyOwnerExists(apiKey: ApiKey.ApiKey, source: Db.Source | undefined) {
-  if (!source) return true
-  const db = Db.get(source)
-  if (!(await ApiKeyAdmissions.matches(db, apiKey))) return false
-  if (await ApiKeyOwnerTombstones.isDeleted(db, apiKey)) return false
-  return true
-}
-
 export declare namespace middleware {
   /** Per-route policy overrides keyed by HTTP endpoint. */
   type Overrides<endpoint extends string = string> = Partial<
@@ -792,8 +831,8 @@ export declare namespace middleware {
         }
       | false
       | undefined
-    /** Rate-limit store options. */
-    rateLimit?: RateLimit.memory.Options | undefined
+    /** Rate-limit store, or options for the counter-backed default. */
+    rateLimit?: RateLimit.memory.Options | RateLimit.Store | undefined
     /** Scope catalog accepted while resolving API-key records. */
     scopeCatalog?: Scope.Catalog | undefined
     /** Session lane resolution — the session surface's capability; omit to leave the session lane closed. */
@@ -973,7 +1012,7 @@ export function install(options: install.Options) {
         get email() {
           return options.email()
         },
-        rateLimit: RateLimit.memory(options_middleware.rateLimit),
+        rateLimit: rateLimitStore(options_middleware.rateLimit),
         secret: options_session.secret,
         ...(options_session.google ? { google: options_session.google } : {}),
         ...(options_session.trustedOrigins
@@ -1019,9 +1058,12 @@ export function install(options: install.Options) {
           return value === null ? undefined : (JSON.parse(value) as never)
         },
         async set(key, value, options) {
+          const payload = key.startsWith('session:')
+            ? { ...(value as WalletSession), ...(await bindWalletSession(value as WalletSession)) }
+            : value
           await kv.store.put(
             `auth:${key}`,
-            JSON.stringify(value),
+            JSON.stringify(payload),
             options?.ttl ? { ttl: options.ttl * 1_000 } : {},
           )
         },
@@ -1064,8 +1106,46 @@ export function install(options: install.Options) {
       })
     }
 
+    async function bindWalletSession(payload: WalletSession) {
+      const user = await resolveWallet(payload)
+      if (!user) throw new Error('Authenticated wallet user was not found')
+      if (!user.user.termsSharedAt) await Users.recordTermsShared(Db.get(db), user.user.id)
+      return { email: user.email, userId: user.user.id }
+    }
+
+    async function resolveWalletSession(payload: WalletSession) {
+      // Legacy sessions cannot be safely rebound after an email or wallet reassignment.
+      if (!payload.userId) return null
+      const database = Db.get(db)
+      const [user, linkedUserId] = await Promise.all([
+        Users.get(database, payload.userId),
+        AuthAccounts.getWalletUserId(database, payload.address),
+      ])
+      if (!user || linkedUserId !== payload.userId) return null
+      if (payload.email && (user.email !== payload.email || !user.emailVerified)) return null
+      return { email: user.emailVerified ? user.email : undefined, user }
+    }
+
+    // CLI sessions act as the approving user; the principal's identity names the
+    // CLI session so handlers never mistake it for a wallet sign-in.
+    const resolveCli = async (token: string): Promise<SessionPrincipal | null> => {
+      const record = await CliAuth.resolve(kv.store, token)
+      if (!record) return null
+      const user = await Users.get(Db.get(db), record.userId)
+      if (!user) return null
+      return {
+        cli: { expiresAt: record.expiresAt, scopes: record.scopes ?? [] },
+        ...(user.emailVerified && user.email ? { email: user.email } : {}),
+        id: user.id,
+        identity: { provider: 'cli', subject: record.id },
+        type: 'session',
+      }
+    }
+
     const session: Session = {
       resolve: async (c) => {
+        const bearer = /^Bearer\s+(.+)$/i.exec(c.req.header('authorization') ?? '')?.[1]
+        if (bearer && CliAuth.isToken(bearer)) return resolveCli(bearer)
         const [betterAuth, identitySession, wallet] = await Promise.all([
           (async () => {
             const auth = BetterAuth.fromContext(c, options_betterAuth)
@@ -1097,7 +1177,7 @@ export function install(options: install.Options) {
             if (value === null) return null
             const payload = JSON.parse(value) as IdentitySession
             if (payload.expiresAt <= Math.floor(Date.now() / 1_000)) return null
-            const user = await resolveWallet(payload)
+            const user = await resolveWalletSession(payload)
             if (!user) return null
             return {
               ...(user.email ? { email: user.email } : {}),
@@ -1109,7 +1189,7 @@ export function install(options: install.Options) {
           (async () => {
             const payload = await handler.getSession(c.req.raw)
             if (!payload) return null
-            const user = await resolveWallet(payload)
+            const user = await resolveWalletSession(payload)
             if (!user) return null
             return {
               ...(user.email ? { email: user.email } : {}),
@@ -1130,6 +1210,11 @@ export function install(options: install.Options) {
     const describe = OpenApi.describeRoute({ hide: true })
 
     const app = new Hono<App.Environment>()
+      .use('*', async (c, next) => {
+        await next()
+        c.header('Tempo-Terms-URL', termsUrl)
+        c.header('Tempo-Privacy-URL', privacyUrl)
+      })
       .use('/v1/auth/siwe', policy_public, describe)
       .use('/v1/auth/siwe/*', policy_public, describe)
     // Documented operations: pre-routes carrying the OpenAPI metadata and the
@@ -1245,13 +1330,14 @@ export function install(options: install.Options) {
 
           const address = Address.checksum(claims.subject)
           await Users.upsertByAddress(Db.get(db), { address })
+          const binding = await bindWalletSession({ address, email: claims.email })
           const issuedAt = Math.floor(Date.now() / 1_000)
           const token = Hex.fromBytes(crypto.getRandomValues(new Uint8Array(32))).slice(2)
           await kv.store.put(
             identitySessionKey(token),
             JSON.stringify({
               address,
-              ...(claims.email ? { email: claims.email } : {}),
+              ...binding,
               expiresAt: issuedAt + identitySessionTtl,
               issuedAt,
             } satisfies IdentitySession),
@@ -1273,10 +1359,14 @@ export function install(options: install.Options) {
       createMiddleware<App.Environment>(async (c, next) => {
         const auth = c.get('auth')
         const principal = principalFromPublic(c, auth)
-        const result = await consumeRateLimit(auth, {
-          key: `public:${principal.id}`,
-          limit: auth.publicRateLimit ?? defaultPublicRateLimit,
-        })
+        const result = await Timing.time(c as never, 'rate_limit', () =>
+          consumeRateLimit(auth, {
+            key: `public:${principal.id}`,
+            limit: auth.publicRateLimit ?? defaultPublicRateLimit,
+            principal: `public:${principal.id}`,
+            waitUntil: ExecutionContext.waitUntil(c),
+          }),
+        )
         if (result) {
           setRateLimitHeaders(c, result)
           if (!result.allowed) return rateLimitExceeded(c, result)
@@ -1286,7 +1376,8 @@ export function install(options: install.Options) {
         return undefined
       }),
       OpenApi.describeRoute({
-        description: 'Revokes auth sessions and clears their cookies.',
+        description:
+          'Revokes auth sessions and clears their cookies. A CLI session sent as `Authorization: Bearer` is revoked on its own.',
         hide: false,
         operationId: 'logout',
         responses: {
@@ -1298,6 +1389,21 @@ export function install(options: install.Options) {
         tags: ['Authentication'],
       }),
       async (c) => {
+        // A CLI session carries only its bearer token; revoke it and leave browser sessions alone.
+        const bearer = /^Bearer\s+(.+)$/i.exec(c.req.header('authorization') ?? '')?.[1]
+        if (bearer && CliAuth.isToken(bearer)) {
+          try {
+            await CliAuth.revoke(kv.store, bearer)
+          } catch (cause) {
+            c.error = cause instanceof Error ? cause : new Error('CLI logout failed', { cause })
+            return Response.error(c, {
+              code: 'session_logout_failed',
+              message: 'Session logout failed',
+              status: 500,
+            })
+          }
+          return c.body(null, 204)
+        }
         const walletHeaders = (() => {
           const authorization = c.req.header('authorization')
           const cookie = c.req.header('cookie')
@@ -1394,7 +1500,7 @@ export function install(options: install.Options) {
       Metadata.attach(app, {
         securitySchemes: {
           session: {
-            description: 'Session cookie established by email OTP, Wallet identity, or SIWE sign-in. Browsers send `tempo_auth.session_token`, `tempo_identity`, or `accounts_auth`; Accounts sessions may also use `Authorization: Bearer <token>`.', // prettier-ignore
+            description: 'Session cookie established by email OTP, Wallet identity, or SIWE sign-in. Browsers send `tempo_auth.session_token`, `tempo_identity`, or `accounts_auth`; Accounts sessions may also use `Authorization: Bearer <token>`, and CLI sessions always use `Authorization: Bearer tempo:cli:…`.', // prettier-ignore
             in: 'header',
             name: 'Cookie',
             type: 'apiKey',
@@ -1408,7 +1514,6 @@ export function install(options: install.Options) {
 
   const resolve = createApiKeyResolver({
     apiKey: options_middleware.apiKey,
-    db: options.db,
     scopeCatalog,
   })
   const defaults = laneDefaults(options_middleware)
@@ -1421,14 +1526,17 @@ export function install(options: install.Options) {
 
     return createMiddleware(async (c, next) => {
       const credential = getApiKeyCredential(c)
+      recordCredential(c, credential)
       const resolved = resolveRequestPolicy(c, { base, defaults, options: options_middleware })
       const isSuperAdmin =
         credential &&
         superAdminTokenHash !== undefined &&
         ApiKey.hash(credential.token) === superAdminTokenHash
+      // CLI session tokens are never API keys, so they skip key resolution here too.
       const canUseApiKeyQuota =
         credential &&
         !isSuperAdmin &&
+        !CliAuth.isToken(credential.token) &&
         !hasPaymentCredential(c) &&
         options_middleware.apiKey !== false &&
         resolved?.policy?.apiKey &&
@@ -1437,10 +1545,24 @@ export function install(options: install.Options) {
       if (cached) return next()
 
       const response = await Timing.time(c, 'edge_rate_limit', () =>
-        options_edgeRateLimit(c.req.raw),
+        options_edgeRateLimit(
+          c.req.raw,
+          canUseApiKeyQuota
+            ? {
+                resolvePartition: async () => {
+                  const apiKey =
+                    cached === undefined ? await resolve.probe(c, credential.token) : cached
+                  // Rotating invalid credentials stays in the anonymous transport bucket.
+                  return apiKey ? `api-key:${ApiKey.hash(credential.token)}` : undefined
+                },
+              }
+            : {},
+        ),
       )
       if (response) return response
-      if (canUseApiKeyQuota && cached === undefined) await resolve.resolve(c, credential.token)
+      // Cold keys resolve here, ahead of the auth lane, so time both under one name.
+      if (canUseApiKeyQuota && cached === undefined)
+        await Timing.sum(c as never, 'auth_key', () => resolve.resolve(c, credential.token))
       return next()
     })
   })()
@@ -1612,7 +1734,9 @@ export function installMppManagementRoutes(
     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
+    const management = policy({
+      mpp: { session: mpp.session },
+    }) as MiddlewareHandler & MppManagementHandler
     management[mppManagementSymbol] = { description: target.description }
     app.post(
       stripBasePath(target.path, options.basePath),
@@ -1776,6 +1900,7 @@ function resolveApiKeyLane(
   if (override === true) return current ?? default_
   const base = current ?? default_
   return {
+    bucket: override.bucket ?? base.bucket,
     rateLimit: override.rateLimit ?? base.rateLimit,
     scopes: override.scopes ?? base.scopes,
   }
@@ -1791,6 +1916,7 @@ function resolveMppLane(
   if (override === true) return current ?? default_
   const base = current ?? default_
   return {
+    bucket: override.bucket ?? base.bucket,
     rateLimit: override.rateLimit ?? base.rateLimit,
     session: { ...base.session, ...override.session },
   }
@@ -1805,7 +1931,10 @@ function resolvePublicLane(
   if (override === false) return undefined
   if (override === true) return current ?? default_
   const base = current ?? default_
-  return { rateLimit: override.rateLimit ?? base.rateLimit }
+  return {
+    bucket: override.bucket ?? base.bucket,
+    rateLimit: override.rateLimit ?? base.rateLimit,
+  }
 }
 
 function resolveSessionLane(
@@ -1974,6 +2103,7 @@ export function require<environment extends Environment = Environment>(
   return createMiddleware<environment>(async (c, next) => {
     const auth = c.get('auth')
     const credential = getApiKeyCredential(c)
+    recordCredential(c, credential)
     const hasQueryApiKey = new URL(c.req.url).searchParams.has('key')
     // Auth owns `key`; strict route schemas must not validate it.
     stripApiKeyQuery(c)
@@ -2027,7 +2157,11 @@ export function require<environment extends Environment = Environment>(
         return proceed()
       }
 
-      const apiKey_resolved = await auth.apiKey?.resolve(c, credential.token)
+      // CLI session tokens are prefixed, so they skip the API-key lookup.
+      const cliToken = CliAuth.isToken(credential.token)
+      const apiKey_resolved = cliToken
+        ? null
+        : await Timing.sum(c as never, 'auth_key', () => auth.apiKey?.resolve(c, credential.token))
       if (!apiKey_resolved) {
         if (unsupportedChain)
           return Response.unsupportedChainId(
@@ -2045,6 +2179,21 @@ export function require<environment extends Environment = Environment>(
             return proceed()
           }
         }
+        if (cliToken)
+          return jsonError(
+            c,
+            policy.session
+              ? {
+                  code: 'session_invalid',
+                  message: 'CLI session is invalid or expired. Sign in again.',
+                  status: 401,
+                }
+              : {
+                  code: 'forbidden',
+                  message: 'CLI sessions cannot call this route. Use an API key.',
+                  status: 403,
+                },
+          )
         return jsonError(c, {
           code: 'api_key_invalid',
           message: 'Invalid API key',
@@ -2085,12 +2234,17 @@ export function require<environment extends Environment = Environment>(
         ? (policy.public?.rateLimit ?? auth.publicRateLimit ?? { limit: 60, period: 'minute' })
         : resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope })
       const paid = hasPayment && !throttled
+      const bucket = policy.apiKey.bucket
       const result = paid
         ? null
-        : await consumeRateLimit(auth, {
-            key: `api_key:${apiKey.id}:scope:${scope}`,
-            limit,
-          })
+        : await Timing.time(c as never, 'rate_limit', () =>
+            consumeRateLimit(auth, {
+              key: rateLimitKey(`api_key:${apiKey.id}:scope:${scope}`, bucket),
+              limit,
+              principal: `api_key:${apiKey.id}`,
+              waitUntil: ExecutionContext.waitUntil(c),
+            }),
+          )
       if (result) {
         setRateLimitHeaders(c, result)
         // Surface the bucket so callers can correlate a 429 with the exhausted
@@ -2135,7 +2289,7 @@ export function require<environment extends Environment = Environment>(
       if (missing.length > 0)
         return jsonError(c, {
           code: 'api_key_forbidden',
-          message: 'API key missing required scope',
+          message: `API key is missing required permissions: ${missing.join(', ')}. Use an API key with these scopes.`,
           status: 403,
         })
 
@@ -2187,10 +2341,14 @@ export function require<environment extends Environment = Environment>(
 
     const limit = policy.public?.rateLimit
     if (limit) {
-      const result = await consumeRateLimit(auth, {
-        key: `public:${publicPrincipal.id}`,
-        limit,
-      })
+      const result = await Timing.time(c as never, 'rate_limit', () =>
+        consumeRateLimit(auth, {
+          key: rateLimitKey(`public:${publicPrincipal.id}`, policy.public?.bucket),
+          limit,
+          principal: `public:${publicPrincipal.id}`,
+          waitUntil: ExecutionContext.waitUntil(c),
+        }),
+      )
       if (result) setRateLimitHeaders(c, result)
       if (!result || result.allowed) {
         c.set('principal', publicPrincipal)
@@ -2231,6 +2389,8 @@ export declare namespace require {
     /** API-key access policy. */
     apiKey?:
       | {
+          /** Optional counter bucket that isolates this route's quota. */
+          bucket?: string | undefined
           /** API-key quota override for this route (a protective per-route cap). */
           rateLimit?: RateLimit.Limit | undefined
           /**
@@ -2244,6 +2404,8 @@ export declare namespace require {
     /** MPP payment access policy. */
     mpp?:
       | {
+          /** Optional counter bucket that isolates this route's quota. */
+          bucket?: string | undefined
           /** Paid-request quota override for this route (a protective per-route cap). */
           rateLimit?: RateLimit.Limit | undefined
           /** Tempo Session request policy. */
@@ -2253,6 +2415,8 @@ export declare namespace require {
     /** Public access policy. */
     public?:
       | {
+          /** Optional counter bucket that isolates this route's quota. */
+          bucket?: string | undefined
           /** Anonymous public quota for this route. */
           rateLimit: RateLimit.Limit
         }
@@ -2287,6 +2451,11 @@ type RateLimitAccess = PaymentAccess & {
  */
 const rateLimitConsumeTimeout = 300
 
+/** Accepts a ready store or builds the counter-backed default from its options. */
+function rateLimitStore(options: RateLimit.memory.Options | RateLimit.Store | undefined) {
+  return options && 'consume' in options ? options : RateLimit.memory(options)
+}
+
 /** Consumes one quota and returns null when its counter is unavailable, allowing callers to fail open. */
 export function consumeRateLimit(
   auth: Context,
@@ -2396,12 +2565,22 @@ function getApiKeyCredential(c: hono_Context): ApiKeyCredential | false | null {
   return null
 }
 
+// Recorded before any lookup: requests that stall or are canceled during
+// resolution never receive a principal, but still need caller attribution.
+function recordCredential(c: hono_Context, credential: ApiKeyCredential | false | null) {
+  if (credential) c.set('credential', 'api_key')
+  else if (hasPaymentCredential(c)) c.set('credential', 'payment')
+}
+
 function clientIp(c: hono_Context, auth: Context): string | undefined {
-  return auth.publicClientIp ? auth.publicClientIp(c.req.raw) : c.req.header('cf-connecting-ip')
+  return (
+    trustedClientIps.get(c.req.raw) ??
+    (auth.publicClientIp ? auth.publicClientIp(c.req.raw) : c.req.header('cf-connecting-ip'))
+  )
 }
 
 function trustedClientIp(c: hono_Context, auth: Context): string | undefined {
-  return resolveTrustedClientIp(c.req.raw, auth.publicClientIp)
+  return trustedClientIps.get(c.req.raw) ?? resolveTrustedClientIp(c.req.raw, auth.publicClientIp)
 }
 
 function resolveTrustedClientIp(
@@ -2543,10 +2722,17 @@ async function requirePayment<environment extends Environment>(
   options: PaymentAccess,
 ) {
   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,
-    })
+    const result = await Timing.time(c as never, 'rate_limit', () =>
+      consumeRateLimit(options.auth, {
+        key: rateLimitKey(
+          `mpp:${options.principal.type}:${options.principal.id}`,
+          options.policy.mpp?.bucket,
+        ),
+        limit: options.policy.mpp?.rateLimit ?? options.auth.mpp?.rateLimit ?? defaultMppRateLimit,
+        principal: `mpp:${options.principal.type}:${options.principal.id}`,
+        waitUntil: ExecutionContext.waitUntil(c),
+      }),
+    )
     if (result) {
       setRateLimitHeaders(c, result)
       c.header('RateLimit-Scope', 'mpp')
@@ -2601,6 +2787,10 @@ function requirePaymentOrRateLimit<environment extends Environment>(
   return rateLimitExceeded(c, options.rateLimit)
 }
 
+function rateLimitKey(key: string, bucket: string | undefined) {
+  return bucket === undefined ? key : `${key}:bucket:${bucket}`
+}
+
 /** Emits a `429` with a `Retry-After` derived from the window reset. */
 function rateLimitExceeded(c: hono_Context, result: RateLimit.Result) {
   c.header('Retry-After', String(Math.max(result.reset - Math.ceil(Date.now() / 1_000), 1)))
@@ -2648,22 +2838,16 @@ async function resolveSession(c: hono_Context, auth: Context): Promise<SessionPr
 const cachedMaxEntries = 10_000
 
 /**
- * Wraps token resolution with a short-TTL per-isolate cache so hot keys skip
- * the backend read on every request. Positive results cache for `ttl`
- * (default 60s), negative for `negativeTtl` (default 10s) so a freshly minted
- * key is usable quickly; concurrent misses for one token are single-flighted.
- * Entries are keyed by the token's sha256 (`ApiKey.hash`) — never the
- * plaintext. Key updates may remain stale for up to `ttl`, the accepted
- * trade-off for removing a backend read from the auth path.
+ * Caches completed resolutions per isolate by token hash, with positive and negative TTLs.
+ * Each miss resolves independently so callers never await another request's pending I/O.
  */
-function cachedResolve(
+export function cachedResolve(
   resolve: (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null>,
   options: middleware.Cache,
 ) {
   const { negativeTtl = 10_000, now = Date.now, ttl = 60_000 } = options
   type Cell = { expiresAt: number; value: ApiKey.ApiKey | null }
   const cells = new Map<string, Cell>()
-  const flights = new Map<string, Promise<ApiKey.ApiKey | null>>()
 
   return {
     invalidate(token: string) {
@@ -2684,27 +2868,16 @@ function cachedResolve(
       if (cell && cell.expiresAt > now()) return cell.value
       if (cell) cells.delete(key)
 
-      const existing = flights.get(key)
-      if (existing) return existing
-
-      const flight = (async () => {
-        const value = await resolve(c, token)
-        // Bound the cache: random invalid tokens each add a (negative) entry,
-        // so sweep expired cells at the cap and then drop the oldest.
-        if (cells.size >= cachedMaxEntries) {
-          const time = now()
-          for (const [name, entry] of cells) if (entry.expiresAt <= time) cells.delete(name)
-          while (cells.size >= cachedMaxEntries) cells.delete(cells.keys().next().value as string)
-        }
-        cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value })
-        return value
-      })()
-      flights.set(key, flight)
-      try {
-        return await flight
-      } finally {
-        flights.delete(key)
+      const value = await resolve(c, token)
+      // Bound the cache: random invalid tokens each add a (negative) entry,
+      // so sweep expired cells at the cap and then drop the oldest.
+      if (cells.size >= cachedMaxEntries) {
+        const time = now()
+        for (const [name, entry] of cells) if (entry.expiresAt <= time) cells.delete(name)
+        while (cells.size >= cachedMaxEntries) cells.delete(cells.keys().next().value as string)
       }
+      cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value })
+      return value
     },
   }
 }