tapimo 0.4.0 → 0.4.3

package/src/internal/Auth.ts

@@ -160,7 +160,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 +205,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 +221,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 +237,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 +267,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 +287,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 +337,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 +349,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 +371,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
 }
 
@@ -460,7 +480,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 ?? {})
@@ -554,6 +576,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
     /**
@@ -678,7 +702,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 +918,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 +931,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 +941,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. */
@@ -1229,12 +1259,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 +1286,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 +1298,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 +1357,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 +1389,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 +1399,7 @@ export function require<environment extends Environment = Environment>(
         }
       }
 
-      return next()
+      return proceed()
     }
 
     // Cookie sessions carry no Authorization credential; resolve the session
@@ -1371,14 +1409,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 +1433,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 +1448,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,
@@ -1574,10 +1612,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 +1621,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')

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
 

package/src/internal/FundingRoutes.test.ts

@@ -9,6 +9,15 @@ const baseUsdcRequest = {
   sourceToken: 'USDC',
 } as const
 
+const baseAcrossQuoteRequest = {
+  depositor: '0x1111111111111111111111111111111111111111',
+  provider: 'across',
+  sourceAmount: '1000000',
+  sourceAmountUnits: 'baseUnits',
+  sourceChain: 'base',
+  sourceToken: 'USDC',
+} as const
+
 describe('listRoutes', () => {
   test('enriches static candidates with adapter quote probes', async () => {
     let seen: FundingRoutes.QuoteProbeInput | undefined
@@ -200,6 +209,23 @@ describe('listRoutes', () => {
   })
 })
 
+describe('quoteRoute', () => {
+  test('rejects requests without a configured quote capability', async () => {
+    await expect(FundingRoutes.quoteRoute(baseAcrossQuoteRequest)).rejects.toBeInstanceOf(
+      FundingRoutes.ProviderNotConfiguredError,
+    )
+  })
+
+  test('rejects requests outside curated inventory', async () => {
+    await expect(
+      FundingRoutes.quoteRoute({
+        ...baseAcrossQuoteRequest,
+        sourceToken: 'USDT',
+      }),
+    ).rejects.toBeInstanceOf(FundingRoutes.FundingRouteNotFoundError)
+  })
+})
+
 describe('parseInclude', () => {
   test('parses comma-separated include values', () => {
     expect(FundingRoutes.parseInclude('quotes,quotes')).toEqual(['quotes'])