tapimo 0.4.1 → 0.4.4

package/src/internal/Auth.ts

@@ -9,6 +9,7 @@ import { findTargetHandler } from 'hono/utils/handler'
 import { decodeJwt } from 'jose'
 import { Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
+import { Addresses } from 'viem/tempo'
 import * as z from 'zod/mini'
 
 import type * as App from '../App.js'
@@ -30,6 +31,7 @@ import * as Users from '../db/tables/users.js'
 import * as Viem from './Viem.js'
 
 const policySymbol = Symbol('tempo-api.auth.policy')
+const defaultMppRateLimit = { perMinute: 100 } satisfies RateLimit.Limit
 
 /** Auth context consumed by Tempo API handlers. */
 export type Context = {
@@ -47,7 +49,7 @@ export type Context = {
       }
     | undefined
   /** MPP payment configuration. */
-  mpp?: Mpp | undefined
+  mpp?: MppHandler | undefined
   /**
    * Configured default anonymous public quota. Used as the throttle ceiling for
    * sandbox keys without active billing on routes that expose no public lane
@@ -89,22 +91,27 @@ export type Payment = {
   type: 'mpp'
 }
 
-/** MPP charge options used by route access policies. */
-export type Charge = Method.RequestDefaults<ReturnType<typeof tempo.charge>> & {
-  /** Optional human-readable payment description. */
-  description?: string | undefined
-  /** Optional challenge expiration timestamp or date. */
-  expires?: Date | string | undefined
-  /** Optional server-defined correlation data. */
-  meta?: Record<string, string> | undefined
-  /** Optional route/resource scope bound to the challenge. */
-  scope?: string | undefined
+/** MPP route-policy types. Distinct from the SIWE {@link Session} capability. */
+export declare namespace Mpp {
+  /** MPP Session request options used by route access policies. */
+  type Session = Method.RequestDefaults<ReturnType<typeof tempo.session>> & {
+    /** Optional human-readable payment description. */
+    description?: string | undefined
+    /** Optional challenge expiration timestamp or date. */
+    expires?: Date | string | undefined
+    /** Optional server-defined correlation data. */
+    meta?: Record<string, string> | undefined
+    /** Optional route/resource scope bound to the challenge. */
+    scope?: string | undefined
+  }
 }
 
 /** MPP payment handler consumed by auth policies. */
-type Mpp = {
-  /** Creates a Hono middleware for a Tempo charge. */
-  charge(options: Charge): MiddlewareHandler
+type MppHandler = {
+  /** Paid-request quota per access principal. */
+  rateLimit?: RateLimit.Limit | undefined
+  /** Creates a Hono middleware for a Tempo Session payment. */
+  session(options: Mpp.Session): MiddlewareHandler
 }
 
 /**
@@ -127,11 +134,13 @@ export type PolicyOverride = {
       }
     | boolean
     | undefined
-  /** MPP paid lane: object to override the charge, or boolean to enable/disable. */
+  /** MPP paid lane: object to override the Session request, or boolean to enable/disable. */
   mpp?:
     | {
-        /** Tempo charge override for this route. */
-        charge?: Charge | undefined
+        /** Paid-request quota override for this route (a protective per-route cap). */
+        rateLimit?: RateLimit.Limit | undefined
+        /** Tempo Session request override for this route. */
+        session?: Mpp.Session | undefined
       }
     | boolean
     | undefined
@@ -160,7 +169,7 @@ export type Principal =
       orgId: string
       /** Payment metadata for paid overflow requests. */
       payment?: Payment | undefined
-      /** Owning project id, when the key carries project attribution. */
+      /** Attributed project id, when present. */
       projectId?: string | undefined
       /** Principal kind. */
       type: 'api_key'
@@ -205,9 +214,9 @@ export type Principal =
 export type Variables = {
   /** Auth context consumed by protected handlers. */
   auth: Context
-  /** Caller's membership resolved by {@link ensureOrg}; absent for `super_admin`. */
+  /** 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} for the current request. */
+  /** Organization resolved by {@link ensureOrg} or {@link ensureProject} for the current request. */
   org?: Organizations.Record | undefined
   /** Authenticated or anonymous caller. */
   principal?: Principal | undefined
@@ -221,13 +230,7 @@ export function getPrincipal<environment extends Environment>(c: hono_Context<en
 }
 
 /**
- * Guards org-scoped routes (`:orgId`). Sessions reach only organizations they
- * are members of; the super admin reaches any. Missing or foreign
- * organizations return `404`, so foreign org ids are indistinguishable from
- * absent ones; a member below the required role gets `403` (the resource is
- * visible to them, the action is not). The resolved organization and
- * membership land on context — read them with {@link org} and
- * {@link membership}.
+ * Guards `:orgId` routes and resolves the organization. Sessions require membership, API keys require ownership, and the super admin bypasses ownership.
  */
 export function ensureOrg(options: ensureOrg.Options = {}): MiddlewareHandler {
   const { role: minimum = 'member' } = options
@@ -243,11 +246,17 @@ export function ensureOrg(options: ensureOrg.Options = {}): MiddlewareHandler {
     const orgId = c.req.param('orgId' as never) as string | undefined
     if (!orgId) return notFound()
     const principal = getPrincipal(c)
-    if (principal?.type !== 'session' && principal?.type !== 'super_admin') return notFound()
+    if (
+      principal?.type !== 'api_key' &&
+      principal?.type !== 'session' &&
+      principal?.type !== 'super_admin'
+    )
+      return notFound()
+    if (principal.type === 'api_key' && principal.orgId !== orgId) return notFound()
     const db = Db.get(contextDb(c))
     const record = await Organizations.get(db, orgId)
     if (!record) return notFound()
-    if (principal.type !== 'super_admin') {
+    if (principal.type === 'session') {
       const member = await Memberships.get(db, orgId, principal.id)
       if (!member) return notFound()
       if (Memberships.rank[member.role] < Memberships.rank[minimum])
@@ -267,16 +276,13 @@ export function ensureOrg(options: ensureOrg.Options = {}): MiddlewareHandler {
 export declare namespace ensureOrg {
   /** Options for the org guard. */
   type Options = {
-    /** Minimum role required; defaults to `member` (any membership). */
+    /** Minimum session role; defaults to `member`. */
     role?: Memberships.Role | undefined
   }
 }
 
 /**
- * Guards project-scoped routes (`:projectId`) nested under {@link ensureOrg},
- * which must run first. Projects resolve only within the scoped organization;
- * missing or cross-org projects return `404`. The resolved project lands on
- * context — read it with {@link project}.
+ * Guards `:projectId` routes and resolves the project. Flat routes authorize against its organization; nested routes preserve the scope from {@link ensureOrg}.
  */
 export function ensureProject(): MiddlewareHandler {
   // Typed loosely (like {@link policy}) so route chains keep their inferred
@@ -290,10 +296,32 @@ export function ensureProject(): MiddlewareHandler {
       })
     const projectId = c.req.param('projectId' as never) as string | undefined
     if (!projectId) return notFound()
+    const principal = getPrincipal(c)
+    if (
+      principal?.type !== 'api_key' &&
+      principal?.type !== 'session' &&
+      principal?.type !== 'super_admin'
+    )
+      return notFound()
+    const db = Db.get(contextDb(c))
+    const record = await Projects.get(db, projectId)
+    if (!record) return notFound()
     const scoped = c.get('org')
-    if (!scoped) return notFound()
-    const record = await Projects.get(Db.get(contextDb(c)), projectId)
-    if (!record || record.orgId !== scoped.id) return notFound()
+    if (scoped) {
+      if (record.orgId !== scoped.id) return notFound()
+      c.set('project', record)
+      await next()
+      return undefined
+    }
+    if (principal.type === 'api_key' && principal.orgId !== record.orgId) return notFound()
+    const organization = await Organizations.get(db, record.orgId)
+    if (!organization) return notFound()
+    if (principal.type === 'session') {
+      const member = await Memberships.get(db, record.orgId, principal.id)
+      if (!member) return notFound()
+      c.set('membership', member)
+    }
+    c.set('org', organization)
     c.set('project', record)
     await next()
     return undefined
@@ -318,7 +346,7 @@ export function ensureOrgError(c: hono_Context) {
 
 /** Typed project-scope error response for Hono client inference. Never reached at runtime. */
 export function ensureProjectError(c: hono_Context) {
-  // Project routes run the org scope first, so either not-found can surface.
+  // Nested project routes run the org scope first, so either not-found can surface.
   const code =
     c.req.header('tempo-narrow-scope-code') === 'organization_not_found'
       ? ('organization_not_found' as const)
@@ -330,19 +358,20 @@ export function ensureProjectError(c: hono_Context) {
   })
 }
 
-/** Reads the caller's membership resolved by {@link ensureOrg}; `undefined` for `super_admin`. */
+/** Reads the caller's membership resolved by the organization or project guard; `undefined` for API keys and `super_admin`. */
 export function membership<environment extends Environment>(
   c: hono_Context<environment>,
 ): Memberships.Record | undefined {
   return c.get('membership')
 }
 
-/** Reads the organization resolved by {@link ensureOrg}; throws when the middleware did not run. */
+/** Reads the organization resolved by the organization or project guard; throws when neither middleware ran. */
 export function org<environment extends Environment>(
   c: hono_Context<environment>,
 ): Organizations.Record {
   const record = c.get('org')
-  if (!record) throw new Error('`orgScope` middleware must run before reading the organization')
+  if (!record)
+    throw new Error('`ensureOrg` or `ensureProject` must run before reading the organization')
   return record
 }
 
@@ -351,7 +380,7 @@ export function project<environment extends Environment>(
   c: hono_Context<environment>,
 ): Projects.Record {
   const record = c.get('project')
-  if (!record) throw new Error('`projectScope` middleware must run before reading the project')
+  if (!record) throw new Error('`ensureProject` must run before reading the project')
   return record
 }
 
@@ -445,7 +474,11 @@ export function middleware<
   endpoint extends string = string,
   environment extends Environment = Environment,
 >(options: middleware.Options<endpoint>): MiddlewareHandler<environment> {
-  const { charge = {}, ...mpp } = options.mpp === false ? {} : (options.mpp ?? {})
+  const {
+    rateLimit: mppRateLimit = defaultMppRateLimit,
+    session: session_ = {},
+    ...mpp
+  } = options.mpp === false ? {} : (options.mpp ?? {})
   const defaults = laneDefaults(options)
   // Default-deny: no lanes open until a route grants them via `policy`.
   // Otherwise the `super_admin` principal bypasses lane checks entirely.
@@ -460,7 +493,9 @@ export function middleware<
   const resolve = (() => {
     const uncached = (c: hono_Context, token: string) => {
       const kv = contextKv(c)
-      return kv ? ApiKeys.resolve(kv.store, token) : Promise.resolve(null)
+      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 ?? {})
@@ -481,11 +516,23 @@ export function middleware<
     ...(options.mpp === false
       ? {}
       : {
-          mpp: Mppx.create({
-            ...mpp,
-            methods: [tempo.charge({ amount: '0.001', ...charge })],
-            secretKey: mpp.secretKey ?? crypto.randomUUID(),
-          }),
+          mpp: {
+            rateLimit: mppRateLimit,
+            session: Mppx.create({
+              ...mpp,
+              // Defaults only; global `session` options may override, including
+              // enabling same-route HEAD bootstrap.
+              methods: [
+                tempo.session({
+                  amount: '0.0001',
+                  bootstrap: false,
+                  currency: Addresses.pathUsd,
+                  unitType: 'request',
+                  ...session_,
+                }),
+              ],
+            }).session,
+          },
         }),
     rateLimit: RateLimit.memory(options.rateLimit),
     ...(options.session ? { session: options.session } : {}),
@@ -554,6 +601,8 @@ export declare namespace middleware {
       | undefined
     /** Rate-limit store options. */
     rateLimit?: RateLimit.memory.Options | 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. */
     session?: Session | undefined
     /**
@@ -576,8 +625,10 @@ export declare namespace middleware {
 
   /** MPP payment options used by auth middleware. */
   type MppOptions = Omit<NonNullable<Parameters<typeof Mppx.create>[0]>, 'methods'> & {
-    /** Global Tempo charge options passed to the MPP method instantiator. */
-    charge?: NonNullable<Parameters<typeof tempo.charge>[0]> | undefined
+    /** Paid-request quota per access principal. Defaults to 100 per minute. */
+    rateLimit?: RateLimit.Limit | undefined
+    /** Global Tempo Session options passed to the MPP method instantiator. */
+    session?: NonNullable<Parameters<typeof tempo.session>[0]> | undefined
   }
 }
 
@@ -678,7 +729,7 @@ function handlerError(description: string) {
  * disables both.
  */
 export function install(options: install.Options) {
-  const { db, kv } = options
+  const { db, kv, scopeCatalog } = options
   const { session: options_session, ...options_middleware } =
     options.auth === false ? {} : (options.auth ?? {})
   if (options_session && !kv)
@@ -894,7 +945,11 @@ export function install(options: install.Options) {
   const middleware_ =
     options.auth === false
       ? undefined
-      : middleware({ ...options_middleware, ...(app ? { session: app.session } : {}) })
+      : middleware({
+          ...options_middleware,
+          ...(app ? { session: app.session } : {}),
+          scopeCatalog,
+        })
 
   return { app, middleware: middleware_ }
 }
@@ -903,7 +958,7 @@ export declare namespace install {
   /** Options for building the built-in auth pieces. */
   type Options = {
     auth:
-      | (Omit<middleware.Options, 'session'> & {
+      | (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`. */
           session?: Session | undefined
         })
@@ -913,6 +968,8 @@ export declare namespace install {
     db: Db.Source
     /** KV state store, or undefined when key auth is closed. */
     kv: { store: Store.State } | undefined
+    /** Scope catalog accepted while resolving API-key records. */
+    scopeCatalog: Scope.Catalog
   }
 
   /** Session sign-in surface configuration: `true` for defaults, or a config object. */
@@ -1013,7 +1070,7 @@ function laneDefaults(options: middleware.Options): LaneDefaults {
       // catalog scopes via `Auth.policy`.
       scopes: apiKey?.scopes ?? [Scope.wildcard],
     },
-    mpp: { charge: {} },
+    mpp: { session: {} },
     public: { rateLimit: public_?.rateLimit ?? { perMinute: 60 } },
     session: true,
   }
@@ -1042,8 +1099,8 @@ function resolvePolicy(
   // The OpenAPI summary/description rides along as the payment-challenge
   // description. It is metadata, not a policy override, so it only applies when
   // the paid lane is actually enabled and has no explicit description already.
-  if (mpp && description !== undefined && mpp.charge.description === undefined)
-    mpp = { charge: { ...mpp.charge, description } }
+  if (mpp && description !== undefined && mpp.session.description === undefined)
+    mpp = { ...mpp, session: { ...mpp.session, description } }
 
   // A lane-less policy stays enforced for super admin; only an explicit
   // `false` override opts a route out of auth entirely.
@@ -1079,7 +1136,10 @@ function resolveMppLane(
   if (override === false) return undefined
   if (override === true) return current ?? default_
   const base = current ?? default_
-  return { charge: { ...base.charge, ...override.charge } }
+  return {
+    rateLimit: override.rateLimit ?? base.rateLimit,
+    session: { ...base.session, ...override.session },
+  }
 }
 
 function resolvePublicLane(
@@ -1229,12 +1289,20 @@ export function require<environment extends Environment = Environment>(
   return createMiddleware<environment>(async (c, next) => {
     const auth = c.get('auth')
     const credential = getApiKeyCredential(c)
-    // The deprecated `key` query param has now been consumed for auth. Strip it
-    // from the request URL so it never reaches a route's query validator —
-    // endpoint query schemas are `z.strictObject`, so an unexpected `key`
-    // param would otherwise fail validation with `query_invalid`, breaking the
-    // legacy `?key=...` lane on every strict-query endpoint.
-    stripLegacyAuthQuery(c)
+    const hasQueryApiKey = new URL(c.req.url).searchParams.has('key')
+    // Auth owns `key`; strict route schemas must not validate it.
+    stripApiKeyQuery(c)
+    const proceed = async () => {
+      await next()
+      // Query credential responses must not enter shared caches.
+      const cacheControl = c.res.headers.get('Cache-Control')?.toLowerCase()
+      if (
+        hasQueryApiKey &&
+        !cacheControl?.includes('no-store') &&
+        !cacheControl?.includes('private')
+      )
+        c.res.headers.set('Cache-Control', 'private')
+    }
     if (credential === false)
       return jsonError(c, {
         code: 'api_key_malformed',
@@ -1248,7 +1316,7 @@ export function require<environment extends Environment = Environment>(
       // It must never reach KV resolution or scope/quota checks.
       if (auth.superAdmin && ApiKey.hash(credential.token) === auth.superAdmin.tokenHash) {
         c.set('principal', { actor: 'super_admin', id: 'super_admin', type: 'super_admin' })
-        return next()
+        return proceed()
       }
 
       const apiKey = await auth.apiKey?.resolve(c, credential.token)
@@ -1260,7 +1328,7 @@ export function require<environment extends Environment = Environment>(
           const session = await resolveSession(c, auth)
           if (session) {
             c.set('principal', session)
-            return next()
+            return proceed()
           }
         }
         return jsonError(c, {
@@ -1319,7 +1387,7 @@ export function require<environment extends Environment = Environment>(
       const throttled = apiKey.environment === 'sandbox' && apiKey.billingActive !== true
 
       if (hasPayment && !throttled)
-        return requirePayment(c, next, {
+        return requirePayment(c, proceed, {
           auth,
           payment: { reason: 'api_key_over_quota', type: 'mpp' },
           policy,
@@ -1351,7 +1419,7 @@ export function require<environment extends Environment = Environment>(
           // 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, next, {
+          return requirePaymentOrRateLimit(c, proceed, {
             auth,
             payment: { reason: 'api_key_over_quota', type: 'mpp' },
             policy,
@@ -1361,7 +1429,7 @@ export function require<environment extends Environment = Environment>(
         }
       }
 
-      return next()
+      return proceed()
     }
 
     // Cookie sessions carry no Authorization credential; resolve the session
@@ -1371,14 +1439,14 @@ export function require<environment extends Environment = Environment>(
       const session = await resolveSession(c, auth)
       if (session) {
         c.set('principal', session)
-        return next()
+        return proceed()
       }
     }
 
     const publicPrincipal = principalFromPublic(c)
     if (hasPayment) {
       c.set('principal', publicPrincipal)
-      return requirePayment(c, next, {
+      return requirePayment(c, proceed, {
         auth,
         payment: { reason: 'public_over_quota', type: 'mpp' },
         policy,
@@ -1395,11 +1463,11 @@ export function require<environment extends Environment = Environment>(
       if (result) setRateLimitHeaders(c, result)
       if (!result || result.allowed) {
         c.set('principal', publicPrincipal)
-        return next()
+        return proceed()
       }
 
       c.set('principal', publicPrincipal)
-      return requirePaymentOrRateLimit(c, next, {
+      return requirePaymentOrRateLimit(c, proceed, {
         auth,
         payment: { reason: 'public_over_quota', type: 'mpp' },
         policy,
@@ -1410,7 +1478,7 @@ export function require<environment extends Environment = Environment>(
 
     if (isPaymentEnabled(auth, policy)) {
       c.set('principal', publicPrincipal)
-      return requirePayment(c, next, {
+      return requirePayment(c, proceed, {
         auth,
         payment: { reason: 'public_over_quota', type: 'mpp' },
         policy,
@@ -1445,8 +1513,10 @@ export declare namespace require {
     /** MPP payment access policy. */
     mpp?:
       | {
-          /** Tempo charge policy. */
-          charge: Charge
+          /** Paid-request quota override for this route (a protective per-route cap). */
+          rateLimit?: RateLimit.Limit | undefined
+          /** Tempo Session request policy. */
+          session: Mpp.Session
         }
       | undefined
     /** Public access policy. */
@@ -1574,10 +1644,8 @@ function getApiKeyCredential(c: hono_Context): ApiKeyCredential | false | null {
   const header = c.req.header('tempo-api-key')
   if (header) return { token: header }
 
-  // `Authorization: Bearer` compatibility fallback. Must not consume or reject
-  // `Authorization: Payment` (MPP), which is a distinct credential — a request
-  // carrying only a payment scheme falls through to the deprecated lanes below
-  // (which find nothing) and resolves to no API-key credential.
+  // Bearer supports clients unable to set the canonical header. Payment
+  // credentials belong to MPP and must pass through untouched.
   const authorization = c.req.header('authorization')
   if (authorization && !Credential.extractPaymentScheme(authorization)) {
     const match = /^Bearer\s+(.+)$/i.exec(authorization)
@@ -1585,26 +1653,18 @@ function getApiKeyCredential(c: hono_Context): ApiKeyCredential | false | null {
     return { token: match[1] }
   }
 
-  // Deprecated fallbacks carried over from the v1 API so existing integrations
-  // keep authenticating: the `x-api-key` header and the `key` query parameter.
+  // `x-api-key` remains a deprecated compatibility header.
   const legacyHeader = c.req.header('x-api-key')
   if (legacyHeader) return { token: legacyHeader }
 
-  const legacyQuery = c.req.query('key')
-  if (legacyQuery) return { token: legacyQuery }
+  const apiKey = c.req.query('key')
+  if (apiKey) return { token: apiKey }
 
   return null
 }
 
-/**
- * Remove the deprecated `key` auth query param from the request URL once it has
- * been read for authentication. Route query schemas are strict
- * (`z.strictObject`), so leaving `key` in the query string would make the
- * downstream validator reject the request as `query_invalid`. Stripping it
- * keeps the legacy `?key=...` auth lane working on strict-query endpoints
- * (e.g. `GET /v1/tokens`).
- */
-function stripLegacyAuthQuery(c: hono_Context) {
+/** Removes the reserved auth query parameter before route validation. */
+function stripApiKeyQuery(c: hono_Context) {
   const url = new URL(c.req.url)
   if (!url.searchParams.has('key')) return
   url.searchParams.delete('key')
@@ -1701,7 +1761,19 @@ async function requirePayment<environment extends Environment>(
   next: () => Promise<void>,
   options: PaymentAccess,
 ) {
-  const middleware = options.auth.mpp?.charge(options.policy.mpp?.charge ?? {})
+  if (hasPaymentCredential(c)) {
+    const result = await consumeRateLimit(options.auth, {
+      key: `mpp:${options.principal.type}:${options.principal.id}`,
+      limit: options.policy.mpp?.rateLimit ?? options.auth.mpp?.rateLimit ?? defaultMppRateLimit,
+    })
+    if (result) {
+      setRateLimitHeaders(c, result)
+      c.header('RateLimit-Scope', 'mpp')
+      if (!result.allowed) return rateLimitExceeded(c, result)
+    }
+  }
+
+  const middleware = options.auth.mpp?.session(options.policy.mpp?.session ?? {})
   if (!middleware)
     return jsonError(c, {
       code: 'payment_required',

package/src/internal/Cursor.test.ts

@@ -18,6 +18,14 @@ describe('Cursor', () => {
     ])
   })
 
+  test('round-trips a timestamp/id tuple', () => {
+    const token = Cursor.encode(['2026-01-01T00:00:00.000Z', 'org_abc123'])
+    expect(Cursor.decode(token, ['timestamp', 'id'])).toEqual([
+      '2026-01-01T00:00:00.000Z',
+      'org_abc123',
+    ])
+  })
+
   test('returns undefined for malformed, mis-typed, or wrong-arity tokens', () => {
     expect(Cursor.decode('not-base64!!', ['int', 'int'])).toBeUndefined()
     expect(Cursor.decode(btoa('{"oops":true}'), ['int', 'int'])).toBeUndefined()
@@ -27,6 +35,7 @@ describe('Cursor', () => {
     expect(Cursor.decode(btoa('[-1,2]'), ['int', 'int'])).toBeUndefined()
     expect(Cursor.decode(btoa('["x",2]'), ['uint', 'int'])).toBeUndefined()
     expect(Cursor.decode(btoa('["0xnotanaddress",2]'), ['address', 'int'])).toBeUndefined()
+    expect(Cursor.decode(btoa('["org_abc\' OR 1=1"]'), ['id'])).toBeUndefined()
   })
 
   test('renders injection-safe SQL literals per field kind', () => {
@@ -35,6 +44,7 @@ describe('Cursor', () => {
     expect(Cursor.literal('0xAbC0000000000000000000000000000000000000', 'address')).toBe(
       "'0xabc0000000000000000000000000000000000000'",
     )
+    expect(Cursor.literal('org_abc123', 'id')).toBe("'org_abc123'")
     expect(Cursor.literal('2024-01-01T00:00:00Z', 'timestamp')).toBe("'2024-01-01T00:00:00Z'")
   })
 

package/src/internal/Cursor.ts

@@ -16,7 +16,7 @@
 export type Cursor = (string | number)[]
 
 /** The kind of a cursor field, determining its validation and SQL literal form. */
-export type Field = 'int' | 'uint' | 'address' | 'timestamp'
+export type Field = 'address' | 'id' | 'int' | 'timestamp' | 'uint'
 
 /** Encodes a positional tuple as an opaque, URL-safe token. */
 export function encode(values: Cursor): string {
@@ -76,6 +76,8 @@ export function literal(value: string | number, field: Field): string {
       return String(value)
     case 'address':
       return `'${String(value).toLowerCase()}'`
+    case 'id':
+      return `'${String(value)}'`
     case 'timestamp':
       return `'${String(value)}'`
   }
@@ -135,6 +137,8 @@ function isValid(value: unknown, field: Field): boolean {
       return typeof value === 'string' && /^\d+$/.test(value)
     case 'address':
       return typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value)
+    case 'id':
+      return typeof value === 'string' && /^[A-Za-z0-9_-]+$/.test(value)
     case 'timestamp':
       return typeof value === 'string' && !Number.isNaN(Date.parse(value))
   }

package/src/internal/EdgeCache.test.ts

@@ -51,6 +51,17 @@ describe('middleware', () => {
     expect(store.size).toMatchInlineSnapshot(`1`)
   })
 
+  test('bypasses the cache for query API key credentials', async () => {
+    const { app, store, downstreamCalls } = createApp()
+
+    await app.request('/cached?key=opaque-secret')
+    await app.request('/cached?key=opaque-secret')
+
+    expect(downstreamCalls()).toMatchInlineSnapshot(`2`)
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
+  })
+
   test('refreshes the entry when the request sends `Cache-Control: no-cache`', async () => {
     const { app, store, downstreamCalls } = createApp()
 

package/src/internal/EdgeCache.ts

@@ -80,6 +80,8 @@ export function middleware<environment extends Env>(
       store !== undefined &&
       c.req.method === 'GET' &&
       !c.req.raw.headers.has('range') &&
+      // Query credentials must reach auth and never enter cache keys.
+      !new URL(c.req.url).searchParams.has('key') &&
       isCacheableRoute(c)
     const key = eligible ? cacheKey(c.req.url) : undefined