tapimo 0.14.0 → 0.15.1

package/src/internal/Auth.ts

@@ -1,13 +1,18 @@
 import * as Accounts from 'accounts/server'
+import { splitSetCookieHeader } from 'better-auth/cookies'
 import { Hono } from 'hono'
 import type { Context as hono_Context, MiddlewareHandler } from 'hono'
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie'
 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 * as jose from 'jose'
+import { sql } from 'kysely'
 import { Challenge, Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
+import { Address, Hex } from 'ox'
 import { Addresses } from 'viem/tempo'
 import { tempoMainnet } from 'viem/tempo/chains'
 import * as z from 'zod/mini'
@@ -15,25 +20,69 @@ 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 Db from '../db/Db.js'
-import type * as Store from './Store.js'
+import type * as Email from './Email.js'
 import * as Memberships from '../db/tables/memberships.js'
 import * as IpAllowlist from './IpAllowlist.js'
 import * as Metadata from '../apps/metadata.js'
 import * as OpenApi from './OpenApi.js'
 import * as Organizations from '../db/tables/organizations.js'
+import * as Path from './Path.js'
 import * as Projects from '../db/tables/projects.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 type * as Store from './Store.js'
+import * as Timing from './Timing.js'
 import * as Users from '../db/tables/users.js'
 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 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
+  /** Unix timestamp when the session expires. */
+  expiresAt: number
+  /** Unix timestamp when the session was issued. */
+  issuedAt: number
+}
+
+type WalletSession = {
+  /** Wallet address used to resolve the canonical user. */
+  address: string
+  /** Verified email used to reconcile the canonical user. */
+  email?: string | undefined
+}
+
+function isIdentityTokenError(error: unknown) {
+  return (
+    error instanceof jose.errors.JOSEAlgNotAllowed ||
+    error instanceof jose.errors.JOSENotSupported ||
+    error instanceof jose.errors.JWSInvalid ||
+    error instanceof jose.errors.JWKSNoMatchingKey ||
+    error instanceof jose.errors.JWSSignatureVerificationFailed ||
+    error instanceof jose.errors.JWTClaimValidationFailed ||
+    error instanceof jose.errors.JWTExpired ||
+    error instanceof jose.errors.JWTInvalid ||
+    (error instanceof Error && error.message === 'email not verified')
+  )
+}
 
 /** Auth context consumed by Tempo API handlers. */
 export type Context = {
@@ -95,7 +144,10 @@ export type Payment = {
   type: 'mpp'
 }
 
-/** MPP route-policy types. Distinct from the SIWE {@link Session} capability. */
+/** Host-provided request backstop that returns a rejection response when over quota. */
+export type EdgeRateLimit = (request: Request) => Promise<Response | undefined>
+
+/** MPP route-policy types. Distinct from the authentication {@link Session} capability. */
 export declare namespace Mpp {
   /** MPP Session request options used by route access policies. */
   type Session = Method.RequestDefaults<ReturnType<typeof tempo.session>> & {
@@ -135,6 +187,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. */
@@ -145,6 +199,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. */
@@ -155,12 +211,14 @@ 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
       }
     | boolean
     | undefined
-  /** Session lane: `true` allows signed-in wallet sessions, `false` disables. */
+  /** Session lane: `true` allows signed-in sessions, `false` disables. */
   session?: boolean | undefined
 }
 
@@ -197,7 +255,7 @@ export type Principal =
       id: string
       /** Identity that established the session, as a provider/subject pair (OIDC `iss`/`sub` semantics). */
       identity: {
-        /** Identity provider: `wallet` for SIWE sign-in, an OIDC issuer otherwise. */
+        /** Identity provider: `email`, `wallet`, or an OIDC issuer. */
         provider: string
         /** Provider-scoped subject — the wallet address for `wallet`. */
         subject: string
@@ -237,6 +295,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.
  */
@@ -504,6 +573,20 @@ export function middleware<
   endpoint extends string = string,
   environment extends Environment = Environment,
 >(options: middleware.Options<endpoint>): MiddlewareHandler<environment> {
+  const resolve = createApiKeyResolver({
+    apiKey: options.apiKey,
+    scopeCatalog: options.scopeCatalog,
+  })
+  return createAuthMiddleware(options, resolve)
+}
+
+function createAuthMiddleware<
+  endpoint extends string = string,
+  environment extends Environment = Environment,
+>(
+  options: middleware.Options<endpoint>,
+  resolve: ReturnType<typeof createApiKeyResolver>,
+): MiddlewareHandler<environment> {
   const {
     rateLimit: mppRateLimit = defaultMppRateLimit,
     session: session_ = {},
@@ -522,23 +605,13 @@ export function middleware<
   // keyed by token sha256) so hot keys skip the backend read on the auth path
   // of every request. Pass `apiKey.cache: false` when immediate key updates
   // matter more than the per-request read.
-  const resolve = (() => {
-    const uncached = (c: hono_Context, token: string) => {
-      const kv = contextKv(c)
-      return kv
-        ? ApiKeys.resolve(kv.store, token, { scopeCatalog: options.scopeCatalog })
-        : Promise.resolve(null)
-    }
-    if (options.apiKey === false || options.apiKey?.cache === false) return uncached
-    return cachedResolve(uncached, options.apiKey?.cache ?? {})
-  })()
   const auth: Context = {
     ...(options.apiKey === false
       ? {}
       : {
           apiKey: {
             ...(options.apiKey?.rateLimits ? { rateLimits: options.apiKey.rateLimits } : {}),
-            resolve,
+            resolve: resolve.resolve,
           },
         }),
     // The throttle ceiling for sandbox keys without active billing, so
@@ -580,38 +653,125 @@ export function middleware<
   }
 
   return createMiddleware<environment>((c, next) => {
-    const route = openApiRoute(c)
-    if (!route) return next()
-
-    const { key, description, management, scope } = route
-    const overrides = options.overrides as
-      | Record<string, PolicyOverride | false | undefined>
-      | undefined
-    const routePolicies = policies(c)
-    const configuredOverride = (() => {
-      const configured = overrides?.[key]
-      if (configured !== undefined) return configured
-      const inheritedMethod = routePolicies.find(
-        (policy) => policy.inheritOverridesFrom,
-      )?.inheritOverridesFrom
-      if (inheritedMethod === undefined) return undefined
-      const inheritedKey = `${inheritedMethod.toUpperCase()} ${key.slice(key.indexOf(' ') + 1)}`
-      return overrides?.[inheritedKey]
-    })()
-    const routeOverride =
-      management && configuredOverride ? { mpp: configuredOverride.mpp } : configuredOverride
-    const endpointPolicy = bindMppScope(
-      resolvePolicy(base, defaults, [...routePolicies, routeOverride], description),
-      scope,
-    )
-    if (!endpointPolicy) return next()
-    if (management && (!auth.mpp || !endpointPolicy.mpp)) return next()
+    const resolved = resolveRequestPolicy(c, { base, defaults, options })
+    if (!resolved) return next()
 
     c.set('auth', auth)
-    return require<environment>(endpointPolicy)(c, next)
+    if (!resolved.policy) return next()
+    if (resolved.management && (!auth.mpp || !resolved.policy.mpp)) return next()
+
+    return require<environment>(resolved.policy)(c, next)
   })
 }
 
+function resolveRequestPolicy(c: hono_Context, options: resolveRequestPolicy.Options) {
+  const route = openApiRoute(c)
+  if (!route) return undefined
+
+  const { key, description, management, scope } = route
+  const overrides = options.options.overrides as
+    | Record<string, PolicyOverride | false | undefined>
+    | undefined
+  const routePolicies = policies(c)
+  const configuredOverride = (() => {
+    const configured = overrides?.[key]
+    if (configured !== undefined) return configured
+    const inheritedMethod = routePolicies.find(
+      (routePolicy): routePolicy is policy.Options =>
+        routePolicy !== false && routePolicy.inheritOverridesFrom !== undefined,
+    )?.inheritOverridesFrom
+    if (inheritedMethod === undefined) return undefined
+    const inheritedKey = `${inheritedMethod.toUpperCase()} ${key.slice(key.indexOf(' ') + 1)}`
+    return overrides?.[inheritedKey]
+  })()
+  // 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(
+      resolvePolicy(options.base, options.defaults, [...routePolicies, routeOverride], description),
+      scope,
+    ),
+  }
+}
+
+declare namespace resolveRequestPolicy {
+  /** Inputs used to resolve the current route's authentication policy. */
+  type Options = {
+    /** Default-closed base policy. */
+    base: require.Policy
+    /** Configured lane defaults. */
+    defaults: LaneDefaults
+    /** Authentication middleware options and route overrides. */
+    options: middleware.Options
+  }
+}
+
+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
+}
+
+type RequestApiKeyResolution = {
+  /** Resolved API key, or null when the token is invalid. */
+  apiKey: ApiKey.ApiKey | null
+  /** Hash of the presented token associated with the resolution. */
+  tokenHash: string
+}
+
+function createApiKeyResolver(options: ApiKeyResolverOptions) {
+  const requests = new WeakMap<hono_Context, RequestApiKeyResolution>()
+  const uncached = (c: hono_Context, token: string) => {
+    const kv = contextKv(c)
+    return kv
+      ? ApiKeys.resolve(kv.store, token, { scopeCatalog: options.scopeCatalog })
+      : Promise.resolve(null)
+  }
+  const cache =
+    options.apiKey === false || options.apiKey?.cache === false
+      ? { invalidate: () => {}, peek: () => undefined, resolve: uncached }
+      : cachedResolve(uncached, options.apiKey?.cache ?? {})
+
+  return {
+    peek: (c: hono_Context, token: string) => {
+      const tokenHash = ApiKey.hash(token)
+      const existing = requests.get(c)
+      if (existing?.tokenHash === tokenHash) return existing.apiKey
+      return cache.peek(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
+      if (cached && !apiKey) cache.invalidate(token)
+      requests.set(c, { apiKey, tokenHash })
+      return apiKey
+    },
+  }
+}
+
+/** 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<
@@ -689,7 +849,7 @@ export declare namespace middleware {
   }
 }
 
-/** Zod schemas documenting the session sign-in surface (`/v1/auth/siwe`). */
+/** Zod schemas documenting the session sign-in surface. */
 namespace schema {
   const siweMessage =
     'api.tempo.xyz wants you to sign in with your Ethereum account:\n0x0000000000000000000000000000000000000000\n\nURI: https://api.tempo.xyz\nVersion: 1\nChain ID: 0\nNonce: 3D0sZfnHqTBmc9tKR\nIssued At: 2026-01-01T00:00:00.000Z\nExpiration Time: 2026-01-01T00:10:00.000Z'
@@ -710,64 +870,92 @@ namespace schema {
   /** Schemas for `POST /v1/auth/siwe/challenge`. */
   export namespace challenge {
     /** Request body. Accepted fields beyond this document pass through to the SDK handler. */
-    export const Body = z.object({})
+    export const Body = OpenApi.component(z.object({}), 'SiweChallengeRequest')
 
     /** Response body. */
-    export const Response = z.object({
-      message: z
-        .string()
-        .check(
-          z.describe('Single-use EIP-4361 (SIWE) message to sign and submit for verification.'),
-          z.meta({ examples: [siweMessage] }),
-        ),
-    })
+    export const Response = OpenApi.component(
+      z.object({
+        message: z
+          .string()
+          .check(
+            z.describe('Single-use EIP-4361 (SIWE) message to sign and submit for verification.'),
+            z.meta({ examples: [siweMessage] }),
+          ),
+      }),
+      'SiweChallengeResponse',
+    )
   }
 
   /** Schemas for `POST /v1/auth/siwe` (verify). */
   export namespace verify {
     /** Request body. */
-    export const Body = z.object({
-      address: z
-        .string()
-        .check(
-          z.describe('Wallet address that signed the message; becomes the session subject.'),
-          z.meta({ examples: ['0x0000000000000000000000000000000000000001'] }),
+    export const Body = OpenApi.component(
+      z.object({
+        address: z
+          .string()
+          .check(
+            z.describe('Wallet address that signed the message; becomes the session subject.'),
+            z.meta({ examples: ['0x0000000000000000000000000000000000000001'] }),
+          ),
+        idToken: z.optional(z.string()).check(
+          z.describe('Wallet-minted OIDC identity token (JWT) asserting a verified email, folded onto the session.'), // prettier-ignore
+          z.meta({ examples: ['eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIweDAwMDAifQ.c2lnbmF0dXJl'] }),
         ),
-      idToken: z.optional(z.string()).check(
-        z.describe('Wallet-minted OIDC identity token (JWT) asserting a verified email, folded onto the session.'), // prettier-ignore
-        z.meta({ examples: ['eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIweDAwMDAifQ.c2lnbmF0dXJl'] }),
-      ),
-      keyAuthorization: z.optional(z.string()).check(
-        z.describe('RLP-serialized signed key authorization (TIP-1053) whose witness binds this message; verification recovers over its digest.'), // prettier-ignore
-        z.meta({ examples: [`0x${'aa'.repeat(60)}`] }),
-      ),
-      message: z
-        .string()
-        .check(
-          z.describe('The exact challenge message issued by `POST /v1/auth/siwe/challenge`.'),
-          z.meta({ examples: [siweMessage] }),
+        keyAuthorization: z.optional(z.string()).check(
+          z.describe('RLP-serialized signed key authorization (TIP-1053) whose witness binds this message; verification recovers over its digest.'), // prettier-ignore
+          z.meta({ examples: [`0x${'aa'.repeat(60)}`] }),
         ),
-      returnToken: z.optional(z.boolean()).check(
-        z.describe('Return the session token in the body instead of setting the session cookie.'), // prettier-ignore
-        z.meta({ examples: [true] }),
-      ),
-      signature: z
-        .string()
-        .check(
-          z.describe('Signature over the challenge message (or the key-authorization digest).'),
-          z.meta({ examples: [`0x${'aa'.repeat(65)}`] }),
+        message: z
+          .string()
+          .check(
+            z.describe('The exact challenge message issued by `POST /v1/auth/siwe/challenge`.'),
+            z.meta({ examples: [siweMessage] }),
+          ),
+        returnToken: z.optional(z.boolean()).check(
+          z.describe('Return the session token in the body instead of setting the session cookie.'), // prettier-ignore
+          z.meta({ examples: [true] }),
         ),
-    })
+        signature: z
+          .string()
+          .check(
+            z.describe('Signature over the challenge message (or the key-authorization digest).'),
+            z.meta({ examples: [`0x${'aa'.repeat(65)}`] }),
+          ),
+      }),
+      'SiweVerifyRequest',
+    )
 
     /** Response body. */
-    export const Response = z.object({
-      token: z
-        .optional(z.string())
-        .check(
-          z.describe('Bearer session token; present only when `returnToken` is true.'),
-          z.meta({ examples: ['aa'.repeat(32)] }),
-        ),
-    })
+    export const Response = OpenApi.component(
+      z.object({
+        token: z
+          .optional(z.string())
+          .check(
+            z.describe('Bearer session token; present only when `returnToken` is true.'),
+            z.meta({ examples: ['aa'.repeat(32)] }),
+          ),
+      }),
+      'SiweVerifyResponse',
+    )
+  }
+
+  /** Schemas for `POST /v1/auth/identity`. */
+  export namespace identity {
+    /** Request body. */
+    export const Body = OpenApi.component(
+      z.object({
+        idToken: z
+          .string()
+          .check(
+            z.describe('Wallet-issued OpenID Connect identity token.'),
+            z.meta({ examples: ['eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiIweDAwMDAifQ.c2lnbmF0dXJl'] }),
+          ),
+      }),
+      'IdentitySignInRequest',
+    )
+
+    /** Response body. */
+    export const Response = OpenApi.component(z.object({}), 'IdentitySignInResponse')
   }
 }
 
@@ -787,19 +975,39 @@ function handlerError(description: string) {
  */
 export function install(options: install.Options) {
   const { db, kv, scopeCatalog } = options
-  const { session: options_session, ...options_middleware } =
-    options.auth === false ? {} : (options.auth ?? {})
+  const {
+    edgeRateLimit: options_edgeRateLimit,
+    session: options_session,
+    ...options_middleware
+  } = options.auth === false ? {} : (options.auth ?? {})
+  const publicClientIp =
+    typeof options_middleware.public === 'object' ? options_middleware.public.clientIp : undefined
   if (options_session && !kv)
     throw new Error('`auth.session` requires the `kv` state store: sessions and sign-in challenges persist there.') // prettier-ignore
+  const options_betterAuth = options_session
+    ? {
+        basePath: Path.join(options.basePath, 'v1/auth'),
+        clientIp: (request: Request) => resolveTrustedClientIp(request, publicClientIp),
+        db,
+        get email() {
+          return options.email()
+        },
+        rateLimit: RateLimit.memory(options_middleware.rateLimit),
+        secret: options_session.secret,
+        ...(options_session.google ? { google: options_session.google } : {}),
+        ...(options_session.trustedOrigins
+          ? { trustedOrigins: options_session.trustedOrigins }
+          : {}),
+      }
+    : undefined
 
   // Session sign-in surface (challenge, verify, logout — SIWE wallet sign-in
   // today) plus the capability the session lane resolves through. Public but
   // policy-gated: the hidden describeRoute engages the middleware for the
   // mounted sub-app, and the public lane rate-limits challenge-store writes.
   const app = (() => {
-    if (!options_session || !kv) return undefined
-    const { issuer, origin, requireEmail, ttl } =
-      (typeof options_session === 'object' ? options_session.wallet : undefined) ?? {}
+    if (!options_betterAuth || !options_session || !kv) return undefined
+    const { issuer, origin, requireEmail, ttl } = options_session.wallet ?? {}
 
     const handler = Accounts.Handler.auth({
       getClient: options.getClient,
@@ -839,30 +1047,105 @@ export function install(options: install.Options) {
       },
       ...(ttl ? { ttl } : {}),
     })
+    const identity = options_session.identity
+    const identitySessionTtl = identity?.ttl ?? defaultIdentitySessionTtl
+    const identitySessionKey = (token: string) => `identity:session:${token}`
+
+    async function resolveWallet(payload: WalletSession) {
+      const database = Db.get(db)
+      const verifiedEmail = payload.email?.trim().toLowerCase()
+      return database.kysely.transaction().execute(async (kysely) => {
+        const tx = { ...database, kysely }
+        // Organization creation locks the same address row before resolving
+        // the wallet owner, serializing resource writes with reconciliation.
+        const addressUser = await Users.getByAddressForUpdate(tx, payload.address)
+        if (!addressUser) return null
+        if (verifiedEmail)
+          await sql`SELECT pg_advisory_xact_lock(hashtextextended(${verifiedEmail}, 0))`.execute(
+            kysely,
+          )
+        const linkedUserId = await AuthAccounts.getWalletUserId(tx, payload.address)
+        const linkedUser = linkedUserId ? await Users.get(tx, linkedUserId) : undefined
+        const emailUser = verifiedEmail ? await Users.getByEmail(tx, verifiedEmail) : undefined
+        const walletUser = linkedUser ?? addressUser
+        const walletHasResources =
+          emailUser && walletUser.id !== emailUser.id
+            ? await Memberships.existsForUser(tx, walletUser.id)
+            : false
+        // A verified email reconciles a provisional email-less wallet link.
+        // Keep a provisional owner when changing it would orphan its access.
+        const user = walletHasResources ? walletUser : (emailUser ?? walletUser)
+        if (linkedUser?.id !== user.id)
+          await AuthAccounts.setWalletUser(tx, { address: payload.address, userId: user.id })
+        if (verifiedEmail && (user.email !== verifiedEmail || !user.emailVerified))
+          await Users.setEmail(tx, user.id, verifiedEmail)
+        return { email: verifiedEmail ?? user.email ?? undefined, user }
+      })
+    }
 
     const session: Session = {
       resolve: async (c) => {
-        const payload = await handler.getSession(c.req.raw)
-        if (!payload) return null
-        const database = Db.get(db)
-        const user = await Users.getByAddress(database, payload.address)
-        if (!user) return null
-        // Fold a newly verified email onto the user row: identity tokens are
-        // optional per sign-in, so the column fills lazily.
-        if (payload.email && user.email !== payload.email)
-          await Users.setEmail(database, user.id, payload.email)
-        const email = payload.email ?? user.email ?? undefined
-        return {
-          ...(email ? { email } : {}),
-          id: user.id,
-          identity: { provider: 'wallet', subject: payload.address },
-          type: 'session',
-        }
+        const [betterAuth, identitySession, wallet] = await Promise.all([
+          (async () => {
+            const auth = BetterAuth.fromContext(c, options_betterAuth)
+            const request = BetterAuth.request(c, options_betterAuth)
+            const result = await auth.api.getSession({ headers: request.headers })
+            if (!result) return null
+            const provider =
+              'provider' in result.session && typeof result.session.provider === 'string'
+                ? result.session.provider
+                : undefined
+            if (
+              !provider ||
+              !result.user.email ||
+              (provider === 'email' && !options_betterAuth.email)
+            )
+              return null
+            return {
+              email: result.user.email,
+              id: result.user.id,
+              identity: { provider, subject: result.user.email },
+              type: 'session',
+            } satisfies SessionPrincipal
+          })(),
+          (async () => {
+            if (!identity) return null
+            const token = getCookie(c, identityCookieName)
+            if (!token) return null
+            const value = await kv.store.get(identitySessionKey(token))
+            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)
+            if (!user) return null
+            return {
+              ...(user.email ? { email: user.email } : {}),
+              id: user.user.id,
+              identity: { provider: 'wallet', subject: payload.address },
+              type: 'session',
+            } satisfies SessionPrincipal
+          })(),
+          (async () => {
+            const payload = await handler.getSession(c.req.raw)
+            if (!payload) return null
+            const user = await resolveWallet(payload)
+            if (!user) return null
+            return {
+              ...(user.email ? { email: user.email } : {}),
+              id: user.user.id,
+              identity: { provider: 'wallet', subject: payload.address },
+              type: 'session',
+            } satisfies SessionPrincipal
+          })(),
+        ])
+        if (betterAuth && identitySession && betterAuth.id !== identitySession.id) return null
+        if (betterAuth && wallet && betterAuth.id !== wallet.id) return null
+        if (identitySession && wallet && identitySession.id !== wallet.id) return null
+        return betterAuth ?? identitySession ?? wallet
       },
     }
 
     const policy_public = policy({ public: true })
-    const policy_session = policy({ public: true, session: true })
     const describe = OpenApi.describeRoute({ hide: true })
 
     const app = new Hono<App.Environment>()
@@ -874,10 +1157,8 @@ export function install(options: install.Options) {
     app.post(
       '/v1/auth/siwe/challenge',
       policy_public,
-      OpenApi.validate('json', schema.challenge.Body, {
-        code: 'body_invalid',
-        message: 'Invalid request body',
-      }),
+      OpenApi.documentJsonRequest(schema.challenge.Body),
+      validateJsonRequest(schema.challenge.Body),
       OpenApi.describeRoute({
         description:
           'Issues a single-use SIWE challenge message to sign. The challenge expires after a short TTL.',
@@ -901,10 +1182,8 @@ export function install(options: install.Options) {
     app.post(
       '/v1/auth/siwe',
       policy_public,
-      OpenApi.validate('json', schema.verify.Body, {
-        code: 'body_invalid',
-        message: 'Invalid request body',
-      }),
+      OpenApi.documentJsonRequest(schema.verify.Body),
+      validateJsonRequest(schema.verify.Body),
       OpenApi.describeRoute({
         description:
           'Verifies the signed challenge and establishes a session. Sets a session cookie by default; pass `returnToken` to receive a bearer token instead.',
@@ -933,42 +1212,270 @@ export function install(options: install.Options) {
         tags: ['Authentication'],
       }),
     )
+    if (identity)
+      app.post(
+        '/v1/auth/identity',
+        policy_public,
+        OpenApi.documentJsonRequest(schema.identity.Body),
+        validateJsonRequest(schema.identity.Body),
+        OpenApi.describeRoute({
+          description:
+            'Verifies a Wallet-issued OpenID Connect identity token and establishes a session.',
+          hide: false,
+          operationId: 'verifyIdentity',
+          responses: {
+            200: {
+              content: {
+                'application/json': { schema: OpenApi.resolver(schema.identity.Response) },
+              },
+              description: 'Session established.',
+              headers: {
+                ...OpenApi.successHeaders,
+                'Set-Cookie': {
+                  description: `Session cookie (${identityCookieName}).`,
+                  schema: { type: 'string' },
+                },
+              },
+            },
+            400: OpenApi.standardError(400, 'Malformed request body.', ['body_invalid']),
+            401: OpenApi.standardError(401, 'Identity verification failed.', ['identity_invalid']),
+            429: OpenApi.standardError(429, 'Rate limited.'),
+            500: OpenApi.standardError(500, 'Internal server error.'),
+          },
+          summary: 'Authenticate identity',
+          tags: ['Authentication'],
+        }),
+        async (c) => {
+          const { idToken } = schema.identity.Body.parse(await c.req.json())
+          const claims = await Accounts.Identity.verify(idToken, {
+            audience: identity.audience,
+            issuer: identity.issuer ?? walletIdentityIssuer,
+          }).catch((error) => {
+            // Issuer and network failures must reach the request error signal.
+            if (isIdentityTokenError(error)) return undefined
+            throw error
+          })
+          if (!claims || !Address.validate(claims.subject, { strict: false }))
+            return Response.error(c, {
+              code: 'identity_invalid',
+              message: 'Invalid identity token',
+              status: 401,
+            })
+
+          const address = Address.checksum(claims.subject)
+          await Users.upsertByAddress(Db.get(db), { address })
+          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 } : {}),
+              expiresAt: issuedAt + identitySessionTtl,
+              issuedAt,
+            } satisfies IdentitySession),
+            { ttl: identitySessionTtl * 1_000 },
+          )
+          setCookie(c, identityCookieName, token, {
+            httpOnly: true,
+            maxAge: identitySessionTtl,
+            path: '/',
+            sameSite: 'Lax',
+            secure: new URL(c.req.url).protocol === 'https:',
+          })
+          return c.json({}, 200)
+        },
+      )
     app.post(
-      '/v1/auth/siwe/logout',
-      policy_session,
+      '/v1/auth/logout',
+      policy(false),
+      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,
+        })
+        if (result) {
+          setRateLimitHeaders(c, result)
+          if (!result.allowed) return rateLimitExceeded(c, result)
+        }
+        c.set('principal', principal)
+        await next()
+        return undefined
+      }),
       OpenApi.describeRoute({
-        description: 'Revokes the current session and clears the session cookie.',
+        description: 'Revokes auth sessions and clears their cookies.',
         hide: false,
-        operationId: 'siweLogout',
+        operationId: 'logout',
         responses: {
-          204: { description: 'Session revoked and cookie cleared.' },
+          204: { description: 'Sessions revoked and cookies cleared.' },
           429: OpenApi.standardError(429, 'Rate limited.'),
-          500: OpenApi.standardError(500, 'Internal server error.'),
+          500: OpenApi.standardError(500, 'Session logout failed.', ['session_logout_failed']),
         },
         summary: 'Sign out',
         tags: ['Authentication'],
       }),
+      async (c) => {
+        const walletHeaders = (() => {
+          const authorization = c.req.header('authorization')
+          const cookie = c.req.header('cookie')
+          if (!authorization?.match(/^Bearer\s+.+$/i) || !cookie?.match(/(?:^|;\s*)accounts_auth=/))
+            return [c.req.raw.headers]
+          const bearer = new Headers(c.req.raw.headers)
+          bearer.delete('cookie')
+          const cookie_ = new Headers(c.req.raw.headers)
+          cookie_.delete('authorization')
+          return [bearer, cookie_]
+        })()
+        const [betterAuth, identityLogout, ...accounts] = await Promise.allSettled([
+          BetterAuth.fromContext(c, options_betterAuth).api.signOut({
+            headers: c.req.raw.headers,
+            returnHeaders: true,
+          }),
+          (async () => {
+            const token = getCookie(c, identityCookieName)
+            deleteCookie(c, identityCookieName, { path: '/' })
+            if (token) await kv.store.delete(identitySessionKey(token))
+          })(),
+          ...walletHeaders.map((headers) =>
+            handler.request(
+              new Request(new URL('/logout', c.req.url), {
+                headers,
+                method: 'POST',
+              }),
+            ),
+          ),
+        ])
+
+        if (betterAuth.status === 'fulfilled')
+          for (const cookie of splitSetCookieHeader(
+            betterAuth.value.headers.get('Set-Cookie') ?? '',
+          ))
+            c.header('Set-Cookie', cookie, { append: true })
+        for (const result of accounts)
+          if (result.status === 'fulfilled')
+            for (const cookie of splitSetCookieHeader(result.value.headers.get('Set-Cookie') ?? ''))
+              c.header('Set-Cookie', cookie, { append: true })
+
+        const error = (() => {
+          const rejected = [betterAuth, identityLogout, ...accounts].find(
+            (result) => result.status === 'rejected',
+          )
+          if (rejected?.status === 'rejected')
+            return rejected.reason instanceof Error
+              ? rejected.reason
+              : new Error('Session logout failed', { cause: rejected.reason })
+          const failed = accounts.find(
+            (result) => result.status === 'fulfilled' && !result.value.ok,
+          )
+          if (failed?.status === 'fulfilled')
+            return new Error(`Accounts session logout failed with status ${failed.value.status}`)
+          return undefined
+        })()
+        if (error) {
+          c.error = error
+          return Response.error(c, {
+            code: 'session_logout_failed',
+            message: 'Session logout failed',
+            status: 500,
+          })
+        }
+        return c.body(null, 204)
+      },
     )
+    app.route('/v1/auth/siwe', handler)
+    app.on(['GET', 'POST'], '/v1/auth/*', policy_public, describe, async (c, next) => {
+      if (
+        c.req.method === 'POST' &&
+        stripBasePath(c.req.path, basePath(c)) === '/v1/auth/email-otp/send-verification-otp'
+      ) {
+        const body: unknown = await c.req.raw
+          .clone()
+          .json()
+          .catch(() => undefined)
+        if (body && typeof body === 'object' && 'type' in body && body.type !== 'sign-in')
+          return Response.error(c, {
+            code: 'body_invalid',
+            message: 'Only sign-in OTPs are supported',
+            status: 400,
+          })
+      }
+      const response = await BetterAuth.fromContext(c, options_betterAuth).handler(
+        BetterAuth.request(c, options_betterAuth),
+      )
+      // Leave unmatched paths available to auth providers mounted by the host app.
+      return response.status === 404 ? next() : response
+    })
     return Object.assign(
       // The tag joins the `Management API` group at `management()`'s chosen slot;
       // group listings filter to defined tags, so it drops out when unmounted.
-      Metadata.attach(app.route('/v1/auth/siwe', handler), {
+      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
+            in: 'header',
+            name: 'Cookie',
+            type: 'apiKey',
+          },
+        },
         tags: [{ name: 'Authentication', description: 'Authenticate into the Tempo Platform.' }],
       }),
       { session },
     )
   })()
 
+  const resolve = createApiKeyResolver({
+    apiKey: options_middleware.apiKey,
+    db: options.db,
+    scopeCatalog,
+  })
+  const defaults = laneDefaults(options_middleware)
+  const base: require.Policy = {}
+  const edgeRateLimit = (() => {
+    if (options.auth === false || !options_edgeRateLimit) return undefined
+    const superAdminTokenHash = options_middleware.superAdmin?.secret
+      ? ApiKey.hash(options_middleware.superAdmin.secret)
+      : undefined
+
+    return createMiddleware(async (c, next) => {
+      const credential = getApiKeyCredential(c)
+      const resolved = resolveRequestPolicy(c, { base, defaults, options: options_middleware })
+      const isSuperAdmin =
+        credential &&
+        superAdminTokenHash !== undefined &&
+        ApiKey.hash(credential.token) === superAdminTokenHash
+      const canUseApiKeyQuota =
+        credential &&
+        !isSuperAdmin &&
+        !hasPaymentCredential(c) &&
+        options_middleware.apiKey !== false &&
+        resolved?.policy?.apiKey &&
+        (!resolved.management || (options_middleware.mpp !== false && resolved.policy.mpp))
+      const cached = canUseApiKeyQuota ? resolve.peek(c, credential.token) : undefined
+      if (cached) return next()
+
+      const response = await Timing.time(c, 'edge_rate_limit', () =>
+        options_edgeRateLimit(c.req.raw),
+      )
+      if (response) return response
+      if (canUseApiKeyQuota && cached === undefined) await resolve.resolve(c, credential.token)
+      return next()
+    })
+  })()
   const middleware_ =
     options.auth === false
       ? undefined
-      : middleware({
-          ...options_middleware,
-          ...(app ? { session: app.session } : {}),
-          scopeCatalog,
-        })
+      : createAuthMiddleware(
+          {
+            ...options_middleware,
+            ...(app ? { session: app.session } : {}),
+            scopeCatalog,
+          },
+          resolve,
+        )
 
-  return { app, middleware: middleware_ }
+  return { app, edgeRateLimit, middleware: middleware_ }
 }
 
 export declare namespace install {
@@ -976,13 +1483,19 @@ export declare namespace install {
   type Options = {
     auth:
       | (Omit<middleware.Options, 'scopeCatalog' | 'session'> & {
-          /** Session sign-in surface: mounts `/v1/auth/siwe` (challenge/verify/logout) and enables the session lane. Pass true for defaults or a config object. Requires `kv`. */
+          /** Request backstop skipped for cached API keys on routes with per-key quotas. */
+          edgeRateLimit?: EdgeRateLimit | undefined
+          /** Session sign-in surface: mounts Better Auth, Wallet identity, and SIWE routes and enables the session lane. Requires `kv`. */
           session?: Session | undefined
         })
       | false
       | undefined
+    /** Normalized path prefix that contains the auth surface. */
+    basePath: string
     /** Authoritative database holding user rows. */
     db: Db.Source
+    /** Resolves the transactional email sender shared by authentication and route groups. */
+    email: () => Email.Sender | undefined
     /** Resolves the configured Tempo RPC client used for SIWE signature verification. */
     getClient: (chainId: number) => Viem.getClient.ReturnType
     /** KV state store, or undefined when key auth is closed. */
@@ -991,13 +1504,36 @@ export declare namespace install {
     scopeCatalog: Scope.Catalog
   }
 
-  /** Session sign-in surface configuration: `true` for defaults, or a config object. */
-  type Session =
-    | boolean
-    | {
-        /** SIWE wallet sign-in configuration. */
-        wallet?: Wallet | undefined
-      }
+  /** Session sign-in surface configuration. */
+  type Session = {
+    /** Google OpenID Connect configuration. */
+    google?:
+      | {
+          /** OAuth client identifier. */
+          clientId: string
+          /** OAuth client secret. */
+          clientSecret: string
+        }
+      | undefined
+    /** Wallet-issued OpenID Connect identity sign-in configuration. */
+    identity?: Identity | undefined
+    /** High-entropy secret used to protect Better Auth credentials. */
+    secret: string
+    /** Additional browser origins accepted by Better Auth. */
+    trustedOrigins?: readonly string[] | undefined
+    /** SIWE wallet sign-in configuration. */
+    wallet?: Wallet | undefined
+  }
+
+  /** Wallet-issued OpenID Connect identity sign-in configuration. */
+  type Identity = {
+    /** Expected token audience, usually the Console origin. */
+    audience: string
+    /** Identity issuer override; defaults to Tempo Wallet. */
+    issuer?: string | undefined
+    /** Session lifetime in seconds. Defaults to 24 hours. */
+    ttl?: number | undefined
+  }
 
   /** SIWE wallet sign-in configuration. */
   type Wallet = {
@@ -1005,15 +1541,44 @@ export declare namespace install {
     issuer?: string | undefined
     /** Pinned absolute origin for SIWE domain binding. Required off-Workers; on Workers the edge proxy headers are trusted by default. */
     origin?: string | undefined
-    /** Reject sign-ins that carry no valid identity token, so every session holds a verified email. */
+    /** Reject sign-ins without a valid identity token. Defaults to false. */
     requireEmail?: boolean | undefined
     /** Session and challenge TTL overrides, in seconds. */
     ttl?: { challenge?: number | undefined; session?: number | undefined } | undefined
   }
 }
 
-/** Creates route middleware that contributes an auth policy override. */
-export function policy(options: policy.Options): MiddlewareHandler {
+function validateJsonRequest<const schema extends z.ZodMiniType>(
+  schema: schema,
+): MiddlewareHandler {
+  return async (c, next) => {
+    if (!c.req.header('content-type')?.toLowerCase().startsWith('application/json'))
+      return Response.error(c, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+        status: 400,
+      })
+    const value = await (async () => {
+      try {
+        return await c.req.raw.clone().json()
+      } catch {
+        return undefined
+      }
+    })()
+    const result = schema.safeParse(value)
+    if (!result.success)
+      return Response.error(c, {
+        code: 'body_invalid',
+        details: Response.validationDetails(result.error.issues),
+        message: 'Invalid request body',
+        status: 400,
+      })
+    return next()
+  }
+}
+
+/** Creates route middleware that contributes an auth policy override, or bypasses auth when passed `false`. */
+export function policy(options: policy.Options | false): MiddlewareHandler {
   const middleware = createMiddleware((_, next) => next()) as MiddlewareHandler & PolicyHandler
   middleware[policySymbol] = options
   return middleware
@@ -1042,7 +1607,7 @@ export function installMppManagementRoutes(
     if (route.method !== 'GET') continue
     const target = targets.get(route.path) ?? { path: route.path }
     const override = policyFromRoute(route)
-    if (override?.mpp !== undefined)
+    if (override && override.mpp !== undefined)
       target.mpp = resolveMppLane(target.mpp, override.mpp, { session: {} })
 
     const spec = openApiSpec(route) as MppManagementSpec | undefined
@@ -1066,7 +1631,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),
@@ -1127,7 +1694,7 @@ type OpenApiRoute = {
 }
 
 type PolicyHandler = {
-  [policySymbol]?: policy.Options | undefined
+  [policySymbol]?: policy.Options | false | undefined
 }
 
 type MppManagementHandler = {
@@ -1168,7 +1735,7 @@ function laneDefaults(options: middleware.Options): LaneDefaults {
       scopes: apiKey?.scopes ?? [Scope.wildcard],
     },
     mpp: { session: {} },
-    public: { rateLimit: public_?.rateLimit ?? { limit: 60, period: 'minute' } },
+    public: { rateLimit: public_?.rateLimit ?? defaultPublicRateLimit },
     session: true,
   }
 }
@@ -1230,6 +1797,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,
   }
@@ -1245,6 +1813,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 },
   }
@@ -1259,7 +1828,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(
@@ -1304,7 +1876,7 @@ function policies(c: hono_Context) {
   return matchedRoutes(c)
     .slice(c.req.routeIndex + 1)
     .map(policyFromRoute)
-    .filter((routePolicy): routePolicy is policy.Options => routePolicy !== undefined)
+    .filter((routePolicy): routePolicy is policy.Options | false => routePolicy !== undefined)
 }
 
 function openApiSpec(route: RouterRoute) {
@@ -1328,6 +1900,8 @@ function mppManagementFromRoute(route: RouterRoute) {
 export type OperationAccess = {
   /** Whether API-key access is allowed. */
   apiKey: boolean
+  /** Whether this operation explicitly bypasses auth instead of inheriting document security. */
+  bypass?: true | undefined
   /** 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). */
@@ -1346,14 +1920,14 @@ export type OperationAccess = {
  * operation surfaces only the lanes its route opts into via {@link policy}.
  */
 export function describeAccess(app: Hono<any, any>): Record<string, OperationAccess> {
-  const groups = new Map<string, { operationId?: string; overrides: PolicyOverride[] }>()
+  const groups = new Map<string, { operationId?: string; overrides: (PolicyOverride | false)[] }>()
   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)
+    if (override !== undefined) group.overrides.push(override)
     groups.set(key, group)
   }
 
@@ -1365,7 +1939,12 @@ export function describeAccess(app: Hono<any, any>): Record<string, OperationAcc
     let public_ = false
     let mpp = false
     let session = false
+    let bypass = false
     for (const override of overrides) {
+      if (override === false) {
+        bypass = true
+        break
+      }
       if (override.apiKey !== undefined) apiKey = override.apiKey !== false
       if (override.apiKey && override.apiKey !== true && override.apiKey.scopes)
         scopes = override.apiKey.scopes
@@ -1373,7 +1952,14 @@ export function describeAccess(app: Hono<any, any>): Record<string, OperationAcc
       if (override.mpp !== undefined) mpp = override.mpp !== false
       if (override.session !== undefined) session = override.session !== false
     }
-    access[operationId] = { apiKey, mpp, public: public_, scopes: apiKey ? scopes : [], session }
+    access[operationId] = {
+      apiKey,
+      ...(bypass ? { bypass: true } : {}),
+      mpp,
+      public: public_,
+      scopes: apiKey ? scopes : [],
+      session,
+    }
   }
   return access
 }
@@ -1417,16 +2003,23 @@ export function require<environment extends Environment = Environment>(
     const hasQueryApiKey = new URL(c.req.url).searchParams.has('key')
     // Auth owns `key`; strict route schemas must not validate it.
     stripApiKeyQuery(c)
-    // Reject unknown chains before MPP builds a chain-bound challenge. Route
-    // groups publish their supported chains into the shared app context.
     const chainId = explicitChainId(c)
     const supportedChainIds = (c.var as Record<string, unknown>)['supportedChainIds']
-    if (
-      chainId !== undefined &&
-      supportedChainIds instanceof Set &&
-      !supportedChainIds.has(chainId)
-    )
-      return Response.unsupportedChainId(c, chainId, supportedChainIds)
+    const unsupportedChain = (() => {
+      if (
+        chainId === undefined ||
+        !(supportedChainIds instanceof Set) ||
+        supportedChainIds.has(chainId)
+      )
+        return undefined
+      return { chainId, supportedChainIds }
+    })()
+    if (unsupportedChain && !credential)
+      return Response.unsupportedChainId(
+        c,
+        unsupportedChain.chainId,
+        unsupportedChain.supportedChainIds,
+      )
     const proceed = async () => {
       await next()
       // Query credential responses must not enter shared caches.
@@ -1450,12 +2043,24 @@ export function require<environment extends Environment = Environment>(
       // The super admin secret precedes key lookup: it is not a stored key.
       // It must never reach KV resolution or scope/quota checks.
       if (auth.superAdmin && ApiKey.hash(credential.token) === auth.superAdmin.tokenHash) {
+        if (unsupportedChain)
+          return Response.unsupportedChainId(
+            c,
+            unsupportedChain.chainId,
+            unsupportedChain.supportedChainIds,
+          )
         c.set('principal', { actor: 'super_admin', id: 'super_admin', type: 'super_admin' })
         return proceed()
       }
 
       const apiKey_resolved = await auth.apiKey?.resolve(c, credential.token)
       if (!apiKey_resolved) {
+        if (unsupportedChain)
+          return Response.unsupportedChainId(
+            c,
+            unsupportedChain.chainId,
+            unsupportedChain.supportedChainIds,
+          )
         // A bearer session token is indistinguishable from an API key at the
         // header, so a failed key lookup falls through to the session lane
         // before rejecting.
@@ -1498,6 +2103,34 @@ export function require<environment extends Environment = Environment>(
           status: 403,
         })
 
+      // Non-paid requests consume API-key quota before rejection. Paid
+      // requests use the MPP quota after access checks.
+      const scope = policy.apiKey.scopes[0] ?? Scope.wildcard
+      const throttled = apiKey.environment === 'sandbox' && apiKey.billingActive !== true
+      const limit = throttled
+        ? (policy.public?.rateLimit ?? auth.publicRateLimit ?? { limit: 60, period: 'minute' })
+        : resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope })
+      const paid = hasPayment && !throttled
+      const result = paid
+        ? null
+        : await consumeRateLimit(auth, {
+            key: rateLimitKey(`api_key:${apiKey.id}:scope:${scope}`, policy.apiKey.bucket),
+            limit,
+          })
+      if (result) {
+        setRateLimitHeaders(c, result)
+        // Surface the bucket so callers can correlate a 429 with the exhausted
+        // quota. MPP challenges own their headers and drop these by design.
+        c.header('RateLimit-Scope', scope)
+      }
+
+      if (unsupportedChain)
+        return Response.unsupportedChainId(
+          c,
+          unsupportedChain.chainId,
+          unsupportedChain.supportedChainIds,
+        )
+
       if (
         apiKey.allowedIps.length &&
         !(await IpAllowlist.allows(c, {
@@ -1532,14 +2165,7 @@ export function require<environment extends Environment = Environment>(
           status: 403,
         })
 
-      // Sandbox keys without active billing are throttled to the public quota.
-      // `billingActive` is snapshotted on the key record (stamped at mint,
-      // re-synced when billing changes), so this needs no billing read on the
-      // request path. Resolved before the paid lane so a payment credential
-      // can't buy past the throttle: sandbox is non-billable testnet.
-      const throttled = apiKey.environment === 'sandbox' && apiKey.billingActive !== true
-
-      if (hasPayment && !throttled)
+      if (paid)
         return requirePayment(c, proceed, {
           auth,
           payment: { reason: 'api_key_over_quota', type: 'mpp' },
@@ -1547,39 +2173,17 @@ export function require<environment extends Environment = Environment>(
           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
-        // A throttled sandbox key shares the key's bucket but at the public
-        // ceiling, so activating billing lifts the limit on the same counter.
-        const limit = throttled
-          ? (policy.public?.rateLimit ?? auth.publicRateLimit ?? { limit: 60, period: 'minute' })
-          : resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope })
-        const result = await consumeRateLimit(auth, {
-          key: `api_key:${apiKey.id}:scope:${scope}`,
-          limit,
+      if (result && !result.allowed) {
+        // A throttled sandbox key gets a plain 429, never an MPP challenge. It
+        // must activate billing to lift the ceiling, not pay per request.
+        if (throttled) return rateLimitExceeded(c, result)
+        return requirePaymentOrRateLimit(c, proceed, {
+          auth,
+          payment: { reason: 'api_key_over_quota', type: 'mpp' },
+          policy,
+          principal,
+          rateLimit: result,
         })
-        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) {
-          // A throttled sandbox key gets a plain 429, never an MPP challenge —
-          // it must activate billing to lift the ceiling, not pay per request.
-          if (throttled) return rateLimitExceeded(c, result)
-          return requirePaymentOrRateLimit(c, proceed, {
-            auth,
-            payment: { reason: 'api_key_over_quota', type: 'mpp' },
-            policy,
-            principal,
-            rateLimit: result,
-          })
-        }
       }
 
       return proceed()
@@ -1610,7 +2214,7 @@ export function require<environment extends Environment = Environment>(
     const limit = policy.public?.rateLimit
     if (limit) {
       const result = await consumeRateLimit(auth, {
-        key: `public:${publicPrincipal.id}`,
+        key: rateLimitKey(`public:${publicPrincipal.id}`, policy.public?.bucket),
         limit,
       })
       if (result) setRateLimitHeaders(c, result)
@@ -1653,6 +2257,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
           /**
@@ -1666,6 +2272,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. */
@@ -1675,11 +2283,13 @@ 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
         }
       | undefined
-    /** Session access policy: `true` allows signed-in wallet sessions. */
+    /** Session access policy: `true` allows signed-in sessions. */
     session?: boolean | undefined
   }
 }
@@ -1709,7 +2319,8 @@ type RateLimitAccess = PaymentAccess & {
  */
 const rateLimitConsumeTimeout = 300
 
-function consumeRateLimit(
+/** Consumes one quota and returns null when its counter is unavailable, allowing callers to fail open. */
+export function consumeRateLimit(
   auth: Context,
   options: RateLimit.Store.ConsumeOptions,
 ): Promise<RateLimit.Result | null> {
@@ -1818,14 +2429,24 @@ function getApiKeyCredential(c: hono_Context): ApiKeyCredential | false | null {
 }
 
 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 {
-  if (auth.publicClientIp) return auth.publicClientIp(c.req.raw)
+  return trustedClientIps.get(c.req.raw) ?? resolveTrustedClientIp(c.req.raw, auth.publicClientIp)
+}
+
+function resolveTrustedClientIp(
+  request: Request,
+  resolve: ((request: Request) => string | undefined) | undefined,
+) {
+  if (resolve) return resolve(request)
   // Cloudflare supplies both the request metadata and this header.
-  if (!('cf' in c.req.raw)) return undefined
-  return c.req.header('cf-connecting-ip')
+  if (!('cf' in request)) return undefined
+  return request.headers.get('cf-connecting-ip') ?? undefined
 }
 
 /** Removes the reserved auth query parameter before route validation. */
@@ -1958,7 +2579,10 @@ async function requirePayment<environment extends Environment>(
 ) {
   if (hasPaymentCredential(c)) {
     const result = await consumeRateLimit(options.auth, {
-      key: `mpp:${options.principal.type}:${options.principal.id}`,
+      key: rateLimitKey(
+        `mpp:${options.principal.type}:${options.principal.id}`,
+        options.policy.mpp?.bucket,
+      ),
       limit: options.policy.mpp?.rateLimit ?? options.auth.mpp?.rateLimit ?? defaultMppRateLimit,
     })
     if (result) {
@@ -2015,6 +2639,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)))
@@ -2050,17 +2678,12 @@ export type Session = {
   resolve: (c: hono_Context) => Promise<SessionPrincipal | null>
 }
 
-// Resolve the session lane from the auth context's capability. Failures
-// resolve to `null` so the remaining lanes and the final `401` still apply.
+// Resolve the session lane from the auth context's capability. Dependency
+// failures propagate to the app error boundary instead of becoming a `401`.
 async function resolveSession(c: hono_Context, auth: Context): Promise<SessionPrincipal | null> {
   const session = auth.session
   if (!session) return null
-  try {
-    return await session.resolve(c)
-  } catch (error) {
-    console.error('[auth] session resolve failed; treating as no session', error)
-    return null
-  }
+  return session.resolve(c)
 }
 
 /** Maximum resolve-cache entries held per isolate before eviction. */
@@ -2078,40 +2701,53 @@ const cachedMaxEntries = 10_000
 function cachedResolve(
   resolve: (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null>,
   options: middleware.Cache,
-): (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null> {
+) {
   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 async (c, token) => {
-    // Versioned so a future record-shape change can't serve stale shapes.
-    const key = `v1:${ApiKey.hash(token)}`
-    const cell = cells.get(key)
-    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)
+  return {
+    invalidate(token: string) {
+      cells.delete(`v1:${ApiKey.hash(token)}`)
+    },
+    peek(token: string) {
+      const key = `v1:${ApiKey.hash(token)}`
+      const cell = cells.get(key)
+      if (!cell) return undefined
+      if (cell.expiresAt > now()) return cell.value
+      cells.delete(key)
+      return undefined
+    },
+    async resolve(c: hono_Context, token: string) {
+      // Versioned so a future record-shape change can't serve stale shapes.
+      const key = `v1:${ApiKey.hash(token)}`
+      const cell = cells.get(key)
+      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)
       }
-      cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value })
-      return value
-    })()
-    flights.set(key, flight)
-    try {
-      return await flight
-    } finally {
-      flights.delete(key)
-    }
+    },
   }
 }