tapimo 0.0.2 → 0.1.0

package/src/index.ts

@@ -1,10 +1,12 @@
 export * as ApiKey from './ApiKey.js'
-export * as ApiKeySource from './ApiKeySource.js'
+export * as ApiKeys from './ApiKeys.js'
 export * as App from './App.js'
 export * as Assets from './Assets.js'
 export * as Auth from './Auth.js'
-export * as Cli from './Cli.js'
+export * as Cli from './cli/Cli.js'
 export * as Client from './Client.js'
+export * as Db from './db/Db.js'
+export * as Handler from './Handler.js'
 export * as Log from './internal/Log.js'
 export * as Metrics from './Metrics.js'
 export * as RateLimit from './internal/RateLimit.js'

package/src/internal/Auth.test.ts

@@ -1,7 +1,7 @@
 import { Hono } from 'hono'
 import { requestId } from 'hono/request-id'
 import { Mppx, tempo } from 'mppx/hono'
-import { RateLimit } from 'cadent'
+import { RateLimit } from 'tapimo'
 import * as ApiKey from '../ApiKey.js'
 import * as Auth from './Auth.js'
 import * as Log from './Log.js'
@@ -96,7 +96,7 @@ describe('require', () => {
       // the downstream validator rejects it as `query_invalid` and the legacy
       // `?key=...` lane breaks on every strict-query endpoint.
       const auth = {
-        apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+        apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
         rateLimit: RateLimit.memory(),
       }
       const app = new Hono<Auth.Environment>()
@@ -241,7 +241,7 @@ describe('require', () => {
       const app = createApp({
         auth: {
           apiKey: {
-            source: TestApp.source({
+            resolve: TestApp.resolver({
               keys: [{ ...key, scopes: [Scope.wildcard], token }],
             }),
           },
@@ -273,7 +273,7 @@ describe('require', () => {
     function createChainApp(options: { public?: boolean } = {}) {
       const auth: Auth.Context = {
         apiKey: {
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [
               { ...key, scopes: [Scope.wildcard], token },
               {
@@ -399,7 +399,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuota(),
         },
@@ -420,7 +420,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuotaOnce(),
         },
@@ -451,7 +451,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuota(),
         },
@@ -477,7 +477,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuotaOnce(),
         },
@@ -537,7 +537,7 @@ describe('require', () => {
     test('returns rate-limit error without payment context', async () => {
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           rateLimit: overQuota(),
         },
         policy: { public: { rateLimit: { perMinute: 1 } } },
@@ -561,7 +561,7 @@ describe('require', () => {
       try {
         const app = createApp({
           auth: {
-            apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+            apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
             rateLimit: {
               async consume() {
                 throw new Error('Network connection lost.')
@@ -594,7 +594,7 @@ describe('require', () => {
       try {
         const app = createApp({
           auth: {
-            apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+            apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
             rateLimit: {
               async consume() {
                 throw new Error('Network connection lost.')
@@ -632,7 +632,7 @@ describe('require', () => {
       const auth = {
         apiKey: {
           rateLimits: { 'data:read': { perMinute: 1 }, 'webhooks:write': { perMinute: 1 } },
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [{ ...key, scopes: [Scope.wildcard], token }],
           }),
         },
@@ -686,7 +686,7 @@ describe('require', () => {
       const auth = {
         apiKey: {
           rateLimits: { 'data:read': { perMinute: 1_000 } },
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [{ ...key, scopes: [Scope.wildcard], token }],
           }),
         },
@@ -710,7 +710,7 @@ describe('require', () => {
     })
 
     test('per-key default overrides config default but not a route cap', async () => {
-      const source = TestApp.source({
+      const resolve = TestApp.resolver({
         keys: [
           {
             ...key,
@@ -723,7 +723,7 @@ describe('require', () => {
 
       const open = createScopedApp({
         auth: {
-          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, source },
+          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, resolve },
           rateLimit: RateLimit.memory(),
         },
         routes: [{ path: '/protected', policy: { apiKey: { scopes: ['data:read'] } } }],
@@ -734,7 +734,7 @@ describe('require', () => {
 
       const capped = createScopedApp({
         auth: {
-          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, source },
+          apiKey: { rateLimits: { '*': { perMinute: 1_000 } }, resolve },
           rateLimit: RateLimit.memory(),
         },
         routes: [
@@ -757,7 +757,7 @@ describe('require', () => {
     test('per-key per-scope overrides everything including a route cap', async () => {
       const auth = {
         apiKey: {
-          source: TestApp.source({
+          resolve: TestApp.resolver({
             keys: [
               {
                 ...key,
@@ -790,7 +790,7 @@ describe('require', () => {
       const entries: Log.Entry[] = []
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           rateLimit: overQuota(),
         },
         logger: (entry) => void entries.push(entry),
@@ -817,7 +817,7 @@ describe('require', () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
-          apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
           mpp,
           rateLimit: overQuota(),
         },
@@ -846,7 +846,7 @@ function createScopedApp(options: {
 }) {
   const auth = options.auth ?? {
     apiKey: {
-      source: TestApp.source({ keys: [{ ...key, scopes: [Scope.wildcard], token }] }),
+      resolve: TestApp.resolver({ keys: [{ ...key, scopes: [Scope.wildcard], token }] }),
     },
     rateLimit: RateLimit.memory(),
   }
@@ -872,7 +872,7 @@ type Options = {
 
 function createApp(options: Options = {}) {
   const auth = options.auth ?? {
-    apiKey: { source: TestApp.source({ keys: [{ ...key, token }] }) },
+    apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
     rateLimit: RateLimit.memory(),
   }
   const app = new Hono<Auth.Environment>()

package/src/internal/Auth.ts

@@ -7,8 +7,9 @@ import { findTargetHandler } from 'hono/utils/handler'
 import { Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
 
-import * as ApiKeySource from '../ApiKeySource.js'
 import * as ApiKey from '../ApiKey.js'
+import * as ApiKeys from '../ApiKeys.js'
+import type * as Store from './Store.js'
 import * as OpenApi from './OpenApi.js'
 import * as RateLimit from './RateLimit.js'
 import * as Response from './Response.js'
@@ -29,8 +30,8 @@ export type Context = {
          * per-key {@link ApiKey.ApiKey.rateLimits} shape.
          */
         rateLimits?: Record<string, RateLimit.Limit> | undefined
-        /** Backing API-key source. */
-        source: ApiKeySource.Source
+        /** Resolves a presented token against the app's KV store on `c`. */
+        resolve: (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null>
       }
     | undefined
   /** MPP payment configuration. */
@@ -217,14 +218,20 @@ export function middleware<
   const { charge = {}, ...mpp } = options.mpp === false ? {} : (options.mpp ?? {})
   const defaults = laneDefaults(options)
   const base = basePolicy(options, defaults)
+  // Keys resolve against the app's KV state store on request context
+  // (`App.create({ kv })`), so the middleware needs no storage wiring; when no
+  // store is configured, every token resolves to `null` (closed).
   // Resolution is cached per isolate by default (positive 60s / negative 10s,
-  // keyed by token sha256 — see `ApiKeySource.cached`) so hot keys skip the
-  // backend read on the auth path of every request. Pass `apiKey.cache: false`
-  // when instant revocation matters more than the per-request read.
-  const source = (() => {
-    if (options.apiKey === false || !options.apiKey?.source) return ApiKeySource.noop
-    if (options.apiKey.cache === false) return options.apiKey.source
-    return ApiKeySource.cached(options.apiKey.source, options.apiKey.cache)
+  // keyed by token sha256) so hot keys skip the backend read on the auth path
+  // of every request. Pass `apiKey.cache: false` when instant revocation
+  // matters more than the per-request read.
+  const resolve = (() => {
+    const uncached = (c: hono_Context, token: string) => {
+      const kv = contextKv(c)
+      return kv ? ApiKeys.resolve(kv.store, token) : 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
@@ -232,7 +239,7 @@ export function middleware<
       : {
           apiKey: {
             ...(options.apiKey?.rateLimits ? { rateLimits: options.apiKey.rateLimits } : {}),
-            source,
+            resolve,
           },
         }),
     ...(options.mpp === false
@@ -280,16 +287,14 @@ export declare namespace middleware {
     apiKey?:
       | {
           /**
-           * Resolve-cache tuning for the source (per-isolate, positive 60s /
-           * negative 10s by default), or `false` to resolve uncached on every
-           * request — e.g. when instant revocation matters more than the
-           * per-request backend read.
+           * Resolve-cache tuning (per-isolate, positive 60s / negative 10s by
+           * default), or `false` to resolve uncached on every request — e.g.
+           * when instant revocation matters more than the per-request backend
+           * read.
            */
-          cache?: ApiKeySource.cached.Options | false | undefined
+          cache?: Cache | false | undefined
           /** API-key quotas keyed by quota scope (reserved `'*'` is the config default). */
           rateLimits?: Record<string, RateLimit.Limit> | undefined
-          /** Backing API-key source. Defaults to an empty source (rejects all). */
-          source?: ApiKeySource.Source | undefined
           /** Required API-key scopes. */
           scopes?: readonly Scope.Id[] | undefined
         }
@@ -311,6 +316,16 @@ export declare namespace middleware {
     rateLimit?: RateLimit.memory.Options | undefined
   }
 
+  /** Resolve-cache tuning for API-key resolution. */
+  type Cache = {
+    /** Time-to-live for negative (`null`) results in milliseconds. */
+    negativeTtl?: number | undefined
+    /** Clock used for expiry. */
+    now?: (() => number) | undefined
+    /** Time-to-live for positive results in milliseconds. */
+    ttl?: number | undefined
+  }
+
   /** MPP payment options used by auth middleware. */
   type MppOptions = Omit<NonNullable<Parameters<typeof Mppx.create>[0]>, 'methods'> & {
     /** Global Tempo charge options passed to the MPP method instantiator. */
@@ -612,7 +627,7 @@ export function require<environment extends Environment = Environment>(
 
     const hasPayment = hasPaymentCredential(c) && isPaymentEnabled(auth, policy)
     if (credential) {
-      const apiKey = await auth.apiKey?.source.resolve(credential.token)
+      const apiKey = await auth.apiKey?.resolve(c, credential.token)
       if (!apiKey)
         return jsonError(c, {
           code: 'api_key_invalid',
@@ -1010,3 +1025,61 @@ function setRateLimitHeaders(c: hono_Context, result: RateLimit.Result) {
   c.header('RateLimit-Remaining', String(result.remaining))
   c.header('RateLimit-Reset', String(result.reset))
 }
+
+// Reads the app's KV state store from request context (set by `App.create`
+// from its `kv` option); `undefined` leaves API-key auth closed.
+function contextKv(c: hono_Context): { store: Store.State } | undefined {
+  return (c.get as (key: string) => unknown)('kv') as { store: Store.State } | undefined
+}
+
+/** Maximum resolve-cache entries held per isolate before eviction. */
+const cachedMaxEntries = 10_000
+
+/**
+ * Wraps token resolution with a short-TTL per-isolate cache so hot keys skip
+ * the backend read on every request. Positive results cache for `ttl`
+ * (default 60s), negative for `negativeTtl` (default 10s) so a freshly minted
+ * key is usable quickly; concurrent misses for one token are single-flighted.
+ * Entries are keyed by the token's sha256 (`ApiKey.hash`) — never the
+ * plaintext. A revoked key may stay resolvable for up to `ttl` — the accepted
+ * trade-off for removing a backend read from the auth path.
+ */
+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)
+      }
+      cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value })
+      return value
+    })()
+    flights.set(key, flight)
+    try {
+      return await flight
+    } finally {
+      flights.delete(key)
+    }
+  }
+}

package/src/internal/RateLimit.test.ts

@@ -1,4 +1,4 @@
-import { RateLimit, Store } from 'cadent'
+import { RateLimit, Store } from 'tapimo'
 
 describe('memory', () => {
   test('tracks fixed-window quota in a store', async () => {

package/src/internal/RpcSchema.ts

@@ -0,0 +1,10 @@
+import type { RpcSchema } from 'ox'
+
+/**
+ * Ox-compatible JSON-RPC schema union used to type the relay handler's incoming
+ * requests (`RpcRequest.RpcRequest<Ox>`). The relay switches on `request.method`
+ * string literals and casts params per method, so a permissive schema whose
+ * `params` is an array is sufficient — the full method-by-method schema union
+ * from the accounts SDK is not needed here.
+ */
+export type Ox = RpcSchema.Generic<string, readonly unknown[]>

package/src/internal/Store.test.ts

@@ -1,4 +1,4 @@
-import { Store } from 'cadent'
+import { Store } from 'tapimo'
 
 describe('from', () => {
   const ops = {
@@ -68,7 +68,89 @@ describe('increment', () => {
   })
 })
 
+describe('update', () => {
+  test('falls back to a get + put read-modify-write without a native swap', async () => {
+    const cells = new Map<string, string>()
+    const store = Store.from({
+      async delete(key) {
+        cells.delete(key)
+      },
+      async get(key) {
+        return cells.get(key) ?? null
+      },
+      async list() {
+        return { keys: [] }
+      },
+      async put(key, value) {
+        cells.set(key, value)
+      },
+    })
+
+    expect(await Store.update(store, 'value', (current) => `${current ?? 'start'}+`)).toMatchInlineSnapshot(`"start+"`) // prettier-ignore
+    expect(await Store.update(store, 'value', (current) => `${current}+`)).toMatchInlineSnapshot(`"start++"`) // prettier-ignore
+  })
+
+  test('retries the transform when the compare-and-swap loses', async () => {
+    const store = Store.memory()
+    await store.put('value', 'a')
+
+    // Interleave a competing write between the read and the swap once.
+    let raced = false
+    const get = store.get.bind(store)
+    store.get = async (key) => {
+      const current = await get(key)
+      if (!raced) {
+        raced = true
+        await store.put('value', 'b')
+      }
+      return current
+    }
+
+    const transforms: (null | string)[] = []
+    const written = await Store.update(store, 'value', (current) => {
+      transforms.push(current)
+      return `${current}c`
+    })
+
+    expect(written).toMatchInlineSnapshot(`"bc"`)
+    expect(transforms).toMatchInlineSnapshot(`
+      [
+        "a",
+        "b",
+      ]
+    `)
+  })
+
+  test('fails after exhausting compare-and-swap attempts', async () => {
+    const store = Store.memory()
+    await store.put('value', 'a')
+
+    // Every read is immediately invalidated by a competing write.
+    const get = store.get.bind(store)
+    store.get = async (key) => {
+      const current = await get(key)
+      await store.put('value', `${current}!`)
+      return current
+    }
+
+    await expect(
+      Store.update(store, 'value', (current) => `${current}c`, { attempts: 2 }),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Store.UpdateContentionError: Store update on "value" lost 2 compare-and-swap attempts.]`,
+    )
+  })
+})
+
 describe('memory', () => {
+  test('swaps atomically against the expected value', async () => {
+    const store = Store.memory()
+
+    expect(await store.swap!('value', null, 'first')).toMatchInlineSnapshot(`true`)
+    expect(await store.swap!('value', null, 'clobber')).toMatchInlineSnapshot(`false`)
+    expect(await store.swap!('value', 'first', 'second')).toMatchInlineSnapshot(`true`)
+    expect(await store.get('value')).toMatchInlineSnapshot(`"second"`)
+  })
+
   test('treats expired entries as absent', async () => {
     const store = Store.memory()
 
@@ -193,6 +275,16 @@ describe('cloudflareKv', () => {
 })
 
 describe('durableObject', () => {
+  // The stub contract requires native `increment` and `swap` (our DO class
+  // implements them); derive them for the in-memory fakes.
+  function stubFor(backing: Store.State): Store.durableObject.Stub {
+    return {
+      ...backing,
+      increment: (key, options) => Store.increment(backing, key, options),
+      swap: (key, expected, next, options) => backing.swap!(key, expected, next, options),
+    }
+  }
+
   test('adapts a Durable Object namespace without caching stubs', async () => {
     const calls: string[] = []
     const backing = Store.memory({
@@ -201,12 +293,7 @@ describe('durableObject', () => {
     const namespace = {
       getByName(name) {
         calls.push(name)
-        // The stub contract requires a native `increment` (our DO class
-        // implements it); derive one for the in-memory fake.
-        return {
-          ...backing,
-          increment: (key, options) => Store.increment(backing, key, options),
-        }
+        return stubFor(backing)
       },
     } satisfies Store.durableObject.Namespace
     const store = Store.durableObject(namespace, { name: 'tempo-api' })
@@ -250,6 +337,7 @@ describe('durableObject', () => {
           increment: (key, options) => Store.increment(backing, key, options),
           list: (options) => backing.list(options),
           put: (key, value, options) => backing.put(key, value, options),
+          swap: (key, expected, next, options) => backing.swap!(key, expected, next, options),
         } satisfies Store.durableObject.Stub
         return new Proxy(stub, {
           get(target, method: string) {
@@ -294,7 +382,7 @@ describe('durableObject', () => {
       getByName() {
         stubs += 1
         return {
-          ...backing,
+          ...stubFor(backing),
           increment: (key, options) => {
             if (failures > 0) {
               failures -= 1
@@ -317,7 +405,7 @@ describe('durableObject', () => {
     const namespace = {
       getByName() {
         return {
-          ...Store.memory(),
+          ...stubFor(Store.memory()),
           increment: () => {
             attempts += 1
             throw Object.assign(new Error('Network connection lost.'), { retryable: true })
@@ -339,7 +427,7 @@ describe('durableObject', () => {
       ({
         getByName() {
           return {
-            ...Store.memory(),
+            ...stubFor(Store.memory()),
             increment: () => {
               attempts += 1
               throw error