tapimo 0.7.2 → 0.9.0

package/src/internal/Auth.test.ts

@@ -21,6 +21,7 @@ import * as TestStore from '../../test/Store.js'
 import * as Tempo from '../../test/Tempo.js'
 
 const key = {
+  allowedIps: [],
   environment: 'production',
   id: 'key_test',
   name: 'Test key',
@@ -295,6 +296,135 @@ describe('require', () => {
         }
       `)
     })
+
+    test.each([
+      ['tempo-api-key', '/protected', { 'tempo-api-key': token }],
+      ['Bearer', '/protected', { authorization: `Bearer ${token}` }],
+      ['x-api-key', '/protected', { 'x-api-key': token }],
+      ['query key', `/protected?key=${token}`, {}],
+    ] as const)('enforces an allowlist for the %s credential', async (_name, path, credential) => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request(path, {
+        headers: { ...credential, 'cf-connecting-ip': '198.51.100.7' },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+    })
+
+    test('rejects a missing client IP', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+    })
+
+    test('does not trust a Cloudflare IP header outside Cloudflare', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          'cf-connecting-ip': '203.0.113.7',
+          'tempo-api-key': token,
+        },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchObject({ error: { code: 'api_key_ip_forbidden' } })
+    })
+
+    test('uses the Cloudflare IP header with Cloudflare request metadata', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const request = Object.assign(
+        new Request('http://localhost/protected', {
+          headers: {
+            'cf-connecting-ip': '203.0.113.7',
+            'tempo-api-key': token,
+          },
+        }),
+        { cf: {} },
+      )
+      const response = await app.fetch(request)
+
+      expect(response.status).toBe(200)
+    })
+
+    test('uses the configured trusted client-IP resolver', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          publicClientIp: (request) => request.headers.get('x-real-ip') ?? undefined,
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          'cf-connecting-ip': '198.51.100.7',
+          'tempo-api-key': token,
+          'x-real-ip': '203.0.113.7',
+        },
+      })
+
+      expect(response.status).toBe(200)
+    })
+
+    test('treats an empty allowlist as unrestricted', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({ keys: [{ ...key, allowedIps: [], token }] }),
+          },
+          rateLimit: RateLimit.memory(),
+        },
+      })
+      const response = await app.request('/protected', {
+        headers: { 'tempo-api-key': token },
+      })
+
+      expect(response.status).toBe(200)
+    })
   })
 
   describe('session', () => {
@@ -383,6 +513,37 @@ describe('require', () => {
       `)
     })
 
+    test('applies the session-only route error before key restrictions', async () => {
+      const app = createApp({
+        auth: {
+          apiKey: {
+            resolve: TestApp.resolver({
+              keys: [{ ...key, allowedIps: ['203.0.113.0/24'], token }],
+            }),
+          },
+          publicClientIp: (request) => request.headers.get('x-real-ip') ?? undefined,
+          rateLimit: RateLimit.memory(),
+        },
+        policy: { session: true },
+      })
+      const response = await app.request('/protected', {
+        headers: {
+          'tempo-api-key': token,
+          'x-real-ip': '198.51.100.7',
+        },
+      })
+
+      expect(response.status).toBe(403)
+      expect(await response.json()).toMatchInlineSnapshot(`
+        {
+          "error": {
+            "code": "forbidden",
+            "message": "API key not permitted for this route",
+          },
+        }
+      `)
+    })
+
     test('is not consulted on lane-less routes', async () => {
       const app = createSessionApp({
         policy: {},
@@ -1095,6 +1256,34 @@ describe('require', () => {
       })
     })
 
+    test('session challenge rejects a chain outside the configured allowlist', async () => {
+      const mpp = Object.assign(
+        createMppServer({
+          chainId: Viem.chainId.mainnet,
+          getClient: ({ chainId = Viem.chainId.mainnet }) => Viem.getClient({ chainId }),
+        }),
+        { sessionChainIds: new Set([Viem.chainId.mainnet, Viem.chainId.testnet]) },
+      )
+      const app = createApp({
+        auth: {
+          apiKey: { resolve: TestApp.resolver({ keys: [{ ...key, token }] }) },
+          mpp,
+          rateLimit: overQuota(),
+        },
+        policy: {
+          mpp: { session: { amount: '1' } },
+          public: { rateLimit: { perMinute: 1 } },
+        },
+      })
+
+      const response = await app.request('/protected?chainId=31318')
+      const body = await response.json()
+
+      expect(response.status).toBe(429)
+      expect(response.headers.has('www-authenticate')).toBe(false)
+      expect(body).toMatchObject({ error: { code: 'payment_required' } })
+    })
+
     test('route session overrides propagate to the challenge', async () => {
       const mpp = createMppServer()
       const app = createApp({
@@ -1228,7 +1417,7 @@ describe('require', () => {
       })
     })
 
-    test('rejects a voucher that exceeds the channel deposit', async () => {
+    test('tops up the channel before signing a voucher that exceeds its deposit', async () => {
       const mpp = createMppServer()
       const app = createApp({
         auth: {
@@ -1243,14 +1432,25 @@ describe('require', () => {
       })
       const client = createMppClient(app)
 
-      // The opening deposit covers one request; the second voucher overruns
-      // it and the low-level client cannot top up, so the server re-challenges.
+      // The opening deposit covers one request. The client tops up the channel
+      // before signing the second voucher.
       const first = await client.fetch('http://tempo-api.test/protected')
       const second = await client.fetch('http://tempo-api.test/protected')
 
       expect(first.status).toBe(200)
-      expect(second.status).toBe(402)
-      expect(second.headers.get('www-authenticate')?.startsWith('Payment ')).toBe(true)
+      expect(second.status).toBe(200)
+
+      const receipt1 = sessionReceipt(first)
+      const receipt2 = sessionReceipt(second)
+      expect(receipt2).toMatchObject({
+        channelId: receipt1.channelId,
+        spent: '2000000',
+      })
+
+      const state = await Actions.channel.getStates(Tempo.client, {
+        channel: receipt1.channelId,
+      })
+      expect(state.deposit).toBe(2_000_000n)
     })
 
     test('rejects a malformed payment credential with a fresh challenge', async () => {

package/src/internal/Auth.ts

@@ -18,6 +18,7 @@ import * as ApiKeys from '../ApiKeys.js'
 import * as Db from '../db/Db.js'
 import type * as Store from './Store.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'
@@ -116,6 +117,8 @@ type MppHandler = {
   session(options: Mpp.Session): MiddlewareHandler
   /** Resolves the chain from a challenge issued by this server. */
   sessionChainId?: ((c: hono_Context) => number | undefined) | undefined
+  /** Chains accepted from request-driven Tempo Session payment overrides. */
+  sessionChainIds?: ReadonlySet<number> | undefined
 }
 
 /**
@@ -438,12 +441,16 @@ export function accessError(c: hono_Context) {
       status: 401,
     })
   }
-  if (status === 403)
+  if (status === 403) {
+    const ipForbidden = c.req.header('tempo-narrow-access-code') === 'api_key_ip_forbidden'
     return Response.error(c, {
-      code: 'api_key_forbidden',
-      message: 'API key missing required scope',
+      code: ipForbidden ? 'api_key_ip_forbidden' : 'api_key_forbidden',
+      message: ipForbidden
+        ? 'API key not permitted from this IP address'
+        : 'API key missing required scope',
       status: 403,
     })
+  }
   const code =
     c.req.header('tempo-narrow-access-code') === 'rate_limit_exceeded'
       ? 'rate_limit_exceeded'
@@ -499,6 +506,7 @@ export function middleware<
   const {
     rateLimit: mppRateLimit = defaultMppRateLimit,
     session: session_ = {},
+    sessionChainIds,
     ...mpp
   } = options.mpp === false ? {} : (options.mpp ?? {})
   const secretKey = resolveMppSecretKey(mpp.secretKey)
@@ -511,8 +519,8 @@ export function middleware<
   // store is configured, every token resolves to `null` (closed).
   // Resolution is cached per isolate by default (positive 60s / negative 10s,
   // 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.
+  // 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)
@@ -560,6 +568,7 @@ export function middleware<
               ],
             }).session,
             sessionChainId: (c) => paymentSessionChainId(c, secretKey),
+            ...(sessionChainIds ? { sessionChainIds: new Set(sessionChainIds) } : {}),
           },
         }),
     rateLimit: RateLimit.memory(options.rateLimit),
@@ -606,8 +615,8 @@ export declare namespace middleware {
           /**
            * 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.
+           * when immediate key updates matter more than the per-request
+           * backend read.
            */
           cache?: Cache | false | undefined
           /** API-key quotas keyed by quota scope (reserved `'*'` is the config default). */
@@ -624,7 +633,7 @@ export declare namespace middleware {
     /** Default public access policy. Pass false to disable anonymous access. */
     public?:
       | {
-          /** Resolves the client IP from trusted runtime or proxy metadata. Defaults to `cf-connecting-ip`. */
+          /** Resolves the client IP from trusted runtime or proxy metadata. Required outside Cloudflare for API-key allowlists. */
           clientIp?: ((request: Request) => string | undefined) | undefined
           /** Anonymous public quota for protected routes. */
           rateLimit?: RateLimit.Limit | undefined
@@ -661,6 +670,8 @@ export declare namespace middleware {
     rateLimit?: RateLimit.Limit | undefined
     /** Global Tempo Session options passed to the MPP method instantiator. */
     session?: NonNullable<Parameters<typeof tempo.session>[0]> | undefined
+    /** Chains accepted from request-driven Tempo Session payment overrides. Omit to preserve the MPP client's chain support. */
+    sessionChainIds?: readonly number[] | undefined
   }
 }
 
@@ -1448,6 +1459,28 @@ export function require<environment extends Environment = Environment>(
       const principal = principalFromApiKey(apiKey)
       c.set('principal', principal)
 
+      // Default-deny: routes with no API-key lane allow only the super admin.
+      // A valid key is authenticated but forbidden.
+      if (!policy.apiKey)
+        return jsonError(c, {
+          code: 'forbidden',
+          message: 'API key not permitted for this route',
+          status: 403,
+        })
+
+      if (
+        apiKey.allowedIps.length &&
+        !(await IpAllowlist.allows(c, {
+          address: trustedClientIp(c, auth),
+          rules: apiKey.allowedIps,
+        }))
+      )
+        return jsonError(c, {
+          code: 'api_key_ip_forbidden',
+          message: 'API key not permitted from this IP address',
+          status: 403,
+        })
+
       if (
         apiKey.environment === 'sandbox' &&
         explicitChain !== undefined &&
@@ -1459,14 +1492,6 @@ export function require<environment extends Environment = Environment>(
           status: 403,
         })
 
-      // Default-deny: routes with no API-key lane allow only the super admin.
-      // A valid key is authenticated but forbidden.
-      if (!policy.apiKey)
-        return jsonError(c, {
-          code: 'forbidden',
-          message: 'API key not permitted for this route',
-          status: 403,
-        })
       const missing = apiKey.scopes.includes(Scope.wildcard)
         ? []
         : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? [])
@@ -1821,6 +1846,17 @@ function getApiKeyCredential(c: hono_Context): ApiKeyCredential | false | null {
   return null
 }
 
+function clientIp(c: hono_Context, auth: Context): string | undefined {
+  return 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)
+  // Cloudflare supplies both the request metadata and this header.
+  if (!('cf' in c.req.raw)) return undefined
+  return c.req.header('cf-connecting-ip')
+}
+
 /** Removes the reserved auth query parameter before route validation. */
 function stripApiKeyQuery(c: hono_Context) {
   const url = new URL(c.req.url)
@@ -1936,7 +1972,7 @@ function principalFromApiKey(apiKey: ApiKey.ApiKey): Principal {
 }
 
 function principalFromPublic(c: hono_Context, auth: Context): Principal {
-  const ip = auth.publicClientIp ? auth.publicClientIp(c.req.raw) : c.req.header('cf-connecting-ip')
+  const ip = clientIp(c, auth)
   return {
     id: ip ? RateLimit.normalizeIp(ip) : 'anonymous',
     type: 'public',
@@ -1961,8 +1997,16 @@ async function requirePayment<environment extends Environment>(
   }
 
   const session = options.policy.mpp?.session ?? {}
+  const explicit = explicitChainId(c)
+  const sessionChainIds = options.auth.mpp?.sessionChainIds
+  if (explicit !== undefined && sessionChainIds && !sessionChainIds.has(explicit))
+    return jsonError(c, {
+      code: 'payment_required',
+      message: 'Payment is not available for the requested chain',
+      status: 429,
+    })
   const chainId =
-    explicitChainId(c) ??
+    explicit ??
     (c.req.method === 'POST' && session.scope?.startsWith('GET ')
       ? options.auth.mpp?.sessionChainId?.(c)
       : undefined)
@@ -2056,7 +2100,7 @@ const cachedMaxEntries = 10_000
  * (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
+ * plaintext. Key updates may remain stale for up to `ttl`, the accepted
  * trade-off for removing a backend read from the auth path.
  */
 function cachedResolve(

package/src/internal/Cache.test.ts

@@ -52,7 +52,7 @@ describe('response', () => {
       expect(etag(first)).toMatchInlineSnapshot(`"<etag>"`)
       expect(first.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"9"`)
       expect(first.headers.get('vary')).toMatchInlineSnapshot(
-        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+        `"Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key"`,
       )
 
       expect(await second.json()).toMatchInlineSnapshot(`
@@ -66,7 +66,7 @@ describe('response', () => {
       expect(second.headers.get('etag') === first.headers.get('etag')).toMatchInlineSnapshot(`true`)
       expect(second.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"8"`)
       expect(second.headers.get('vary')).toMatchInlineSnapshot(
-        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+        `"Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key"`,
       )
 
       expect(third.status).toMatchInlineSnapshot(`304`)
@@ -77,11 +77,45 @@ describe('response', () => {
       expect(third.headers.get('etag') === first.headers.get('etag')).toMatchInlineSnapshot(`true`)
       expect(third.headers.get('ratelimit-remaining')).toMatchInlineSnapshot(`"8"`)
       expect(third.headers.get('vary')).toMatchInlineSnapshot(
-        `"Accept-Encoding, Authorization, Tempo-API-Key"`,
+        `"Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key"`,
       )
     })
   })
 
+  test('varies cached responses by the legacy API-key header', async () => {
+    await withCaches(async () => {
+      let calls = 0
+      const app = new Hono()
+      app.get('/', Cache.response({ key: (c) => c.req.url, name: 'test' }), (c) =>
+        c.json({ calls: ++calls, token: c.req.header('x-api-key') }),
+      )
+
+      const first = await app.request('/', { headers: { 'x-api-key': 'one' } })
+      const second = await app.request('/', { headers: { 'x-api-key': 'two' } })
+      const hit = await app.request('/', { headers: { 'x-api-key': 'one' } })
+
+      expect(calls).toMatchInlineSnapshot(`2`)
+      expect(await first.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 1,
+          "token": "one",
+        }
+      `)
+      expect(await second.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 2,
+          "token": "two",
+        }
+      `)
+      expect(await hit.json()).toMatchInlineSnapshot(`
+        {
+          "calls": 1,
+          "token": "one",
+        }
+      `)
+    })
+  })
+
   test('stores entries with the shared policy form, not the client form', async () => {
     await withCaches(async (stores) => {
       const app = new Hono()

package/src/internal/Cache.ts

@@ -57,7 +57,7 @@ export function response<environment extends Env>(
   options: response.Options<environment>,
 ): MiddlewareHandler<environment> {
   const defaultCacheControl = options.cacheControl ?? policies.default
-  const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key']
+  const vary = options.vary ?? ['Accept-Encoding', 'Authorization', 'Tempo-API-Key', 'X-API-Key']
   // hono/cache suffixes its key with `::<directive>=<value>` for every
   // configured vary directive (trimmed, lowercased, deduped). Mirror that
   // normalization so the `no-cache` purge below deletes exactly the entry the

package/src/internal/EdgeCache.test.ts

@@ -37,18 +37,18 @@ describe('middleware', () => {
     expect(second.headers.get('vary')).toMatchInlineSnapshot(`"Accept-Encoding"`)
   })
 
-  test('serves authenticated requests from the same shared cache entry', async () => {
+  test('bypasses the cache for credential headers', async () => {
     const { app, store, downstreamCalls } = createApp()
 
-    // An authenticated request warms the cache; subsequent requests — whether
-    // authenticated (with any key) or anonymous — are all served from the one
-    // shared entry without re-running downstream auth/rate-limiting.
     await app.request('/cached', { headers: { authorization: 'Bearer one' } })
+    await app.request('/cached', { headers: { authorization: 'Basic malformed' } })
+    await app.request('/cached', { headers: { authorization: 'Payment paid' } })
     await app.request('/cached', { headers: { 'tempo-api-key': 'two' } })
-    await app.request('/cached')
+    await app.request('/cached', { headers: { 'x-api-key': 'three' } })
 
-    expect(downstreamCalls()).toMatchInlineSnapshot(`1`)
-    expect(store.size).toMatchInlineSnapshot(`1`)
+    expect(downstreamCalls()).toMatchInlineSnapshot(`5`)
+    expect(store.gets).toMatchInlineSnapshot(`0`)
+    expect(store.size).toMatchInlineSnapshot(`0`)
   })
 
   test('bypasses the cache for query API key credentials', async () => {

package/src/internal/EdgeCache.ts

@@ -48,8 +48,8 @@ const volatileHeaders = [
 /**
  * Serves GET responses from the edge cache store BEFORE auth and rate-limiting
  * run, so cache hits skip the per-request store round-trips that dominate
- * latency — for every caller, authenticated or not. Place this ahead of the
- * auth middleware.
+ * latency. Credential-bearing requests bypass this layer so per-key policy
+ * enforcement always runs. Place this ahead of the auth middleware.
  *
  * Only 2xx responses from routes that opted into caching (via `Cache.response`,
  * which publishes the `edgeCache` policy) are stored, and the policy is only
@@ -84,8 +84,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') &&
+      // Credential-bearing requests must reach auth for per-key policy enforcement.
+      !hasCredential(c.req.raw) &&
       isCacheableRoute(c)
     const key = eligible
       ? await routeCacheKey(c).catch(() => {
@@ -144,6 +144,15 @@ export function middleware<environment extends Env>(
   }
 }
 
+function hasCredential(request: Request): boolean {
+  return (
+    request.headers.has('tempo-api-key') ||
+    request.headers.has('x-api-key') ||
+    request.headers.has('authorization') ||
+    new URL(request.url).searchParams.has('key')
+  )
+}
+
 // Marks handlers whose route publishes an edge-cache policy; the middleware
 // pays the store lookup only when a matched handler carries it.
 const cacheableSymbol = Symbol('tempoApi.edgeCacheable')

package/src/internal/IpAllowlist.test.ts

@@ -0,0 +1,52 @@
+import { Hono } from 'hono'
+
+import * as IpAllowlist from './IpAllowlist.js'
+
+describe('isRule', () => {
+  test.each([
+    ['203.0.113.7', true],
+    ['0.0.0.0/0', true],
+    ['203.0.113.0/24', true],
+    ['203.0.113.7/32', true],
+    ['2001:db8::7', true],
+    ['::/0', true],
+    ['2001:db8::/32', true],
+    ['2001:db8::7/128', true],
+    ['::ffff:192.0.2.1', true],
+    ['203.0.113.0/33', false],
+    ['2001:db8::/129', false],
+    ['203.0.113.0/-1', false],
+    ['203.0.113.999', false],
+    ['2001:db8::1%eth0', false],
+    ['203.0.113.0/24/1', false],
+    [' 203.0.113.7', false],
+    ['203.0.113.7 ', false],
+    ['*', false],
+    ['', false],
+  ])('%s -> %s', (rule, expected) => {
+    expect(IpAllowlist.isRule(rule)).toBe(expected)
+  })
+})
+
+describe('allows', () => {
+  test.each([
+    ['203.0.113.7', ['203.0.113.7'], true],
+    ['203.0.113.7', ['0.0.0.0/0'], true],
+    ['203.0.113.7', ['203.0.113.0/24'], true],
+    ['203.0.113.0', ['203.0.113.0/24'], true],
+    ['203.0.113.255', ['203.0.113.0/24'], true],
+    ['203.0.114.7', ['203.0.113.0/24'], false],
+    ['2001:db8:1::7', ['2001:db8::/32'], true],
+    ['2001:db8::7', ['2001:db8::7/128'], true],
+    ['2001:db8::8', ['2001:db8::7/128'], false],
+    ['2001:db9::7', ['2001:db8::/32'], false],
+    ['203.0.113.7', ['2001:db8::/32'], false],
+    ['::ffff:192.0.2.1', ['::ffff:192.0.2.1'], true],
+    ['not-an-ip', ['203.0.113.0/24'], false],
+  ])('%s in %j -> %s', async (address, rules, expected) => {
+    const app = new Hono().get('/', async (c) =>
+      c.json({ allowed: await IpAllowlist.allows(c, { address, rules }) }),
+    )
+    expect(await (await app.request('/')).json()).toEqual({ allowed: expected })
+  })
+})

package/src/internal/IpAllowlist.ts

@@ -0,0 +1,39 @@
+import type { Context } from 'hono'
+import { ipRestriction } from 'hono/ip-restriction'
+
+/** Returns whether a value is an IPv4/IPv6 address or CIDR range. */
+export function isRule(value: string): boolean {
+  if (value === '*' || value.trim() !== value || value.split('/').length > 2) return false
+  try {
+    ipRestriction(() => '', { allowList: [value] })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Returns whether the client address matches at least one allowlist rule. */
+export async function allows(c: Context, options: allows.Options): Promise<boolean> {
+  const { address, rules } = options
+  if (!address) return false
+  try {
+    const denied = await ipRestriction(
+      () => address,
+      { allowList: [...rules] },
+      () => new Response(null, { status: 403 }),
+    )(c, async () => {})
+    return denied === undefined
+  } catch {
+    return false
+  }
+}
+
+export declare namespace allows {
+  /** Inputs used to check a client address. */
+  type Options = {
+    /** Trusted client IP address. */
+    address?: string | undefined
+    /** Exact IP and CIDR rules to match. */
+    rules: readonly string[]
+  }
+}