feat(middleware): Introduce IP Restriction Middleware

jsr.json

@@ -21,6 +21,7 @@
     "./basic-auth": "./src/middleware/basic-auth/index.ts",
     "./bearer-auth": "./src/middleware/bearer-auth/index.ts",
     "./body-limit": "./src/middleware/body-limit/index.ts",
+    "./ip-restriction": "./src/middleware/ip-restriction/index.ts",
     "./cache": "./src/middleware/cache/index.ts",
     "./cookie": "./src/helper/cookie/index.ts",
     "./accepts": "./src/helper/accepts/index.ts",
@@ -87,7 +88,8 @@
     "./utils/mime": "./src/utils/mime.ts",
     "./utils/stream": "./src/utils/stream.ts",
     "./utils/types": "./src/utils/types.ts",
-    "./utils/url": "./src/utils/url.ts"
+    "./utils/url": "./src/utils/url.ts",
+    "./utils/ipaddr": "./src/utils/ipaddr.ts"
   },
   "publish": {
     "include": [

package.json

@@ -78,6 +78,11 @@
       "import": "./dist/middleware/body-limit/index.js",
       "require": "./dist/cjs/middleware/body-limit/index.js"
     },
+    "./ip-restriction": {
+      "types": "./dist/types/middleware/ip-restriction/index.d.ts",
+      "import": "./dist/middleware/ip-restriction/index.js",
+      "require": "./dist/cjs/middleware/ip-restriction/index.js"
+    },
     "./cache": {
       "types": "./dist/types/middleware/cache/index.d.ts",
       "import": "./dist/middleware/cache/index.js",
@@ -380,6 +385,9 @@
       "body-limit": [
         "./dist/types/middleware/body-limit"
       ],
+      "ip-restriction": [
+        "./dist/types/middleware/ip-restriction"
+      ],
       "cache": [
         "./dist/types/middleware/cache"
       ],

src/middleware/ip-restriction/index.test.ts

@@ -0,0 +1,86 @@
+import { Hono } from '../../hono'
+import { Context } from '../../context'
+import { HonoRequest } from '../../request'
+import type { GetConnInfo } from '../../helper/conninfo'
+import { ipRestriction, isMatchForRule } from '.'
+
+describe('ipRestriction middleware', () => {
+  it('Should restrict', async () => {
+    const getConnInfo: GetConnInfo = (c) => {
+      return {
+        remote: {
+          address: c.env.ip,
+        },
+      }
+    }
+    const app = new Hono<{
+      Bindings: {
+        ip: string
+      }
+    }>()
+    app.use(
+      '/basic',
+      ipRestriction(getConnInfo, {
+        allowList: ['192.168.1.0', '192.168.2.0/24'],
+        denyList: ['192.168.2.10'],
+      })
+    )
+    app.get('/basic', (c) => c.text('Hello World!'))
+
+    app.use(
+      '/allow-empty',
+      ipRestriction(getConnInfo, {
+        denyList: ['192.168.1.0'],
+      })
+    )
+    app.get('/allow-empty', (c) => c.text('Hello World!'))
+
+    expect((await app.request('/basic', {}, { ip: '0.0.0.0' })).status).toBe(403)
+
+    expect((await app.request('/basic', {}, { ip: '192.168.1.0' })).status).toBe(200)
+
+    expect((await app.request('/basic', {}, { ip: '192.168.2.5' })).status).toBe(200)
+    expect((await app.request('/basic', {}, { ip: '192.168.2.10' })).status).toBe(403)
+
+    expect((await app.request('/allow-empty', {}, { ip: '0.0.0.0' })).status).toBe(200)
+
+    expect((await app.request('/allow-empty', {}, { ip: '192.168.1.0' })).status).toBe(403)
+
+    expect((await app.request('/allow-empty', {}, { ip: '192.168.2.5' })).status).toBe(200)
+    expect((await app.request('/allow-empty', {}, { ip: '192.168.2.10' })).status).toBe(200)
+  })
+  it('Custom onerror', async () => {
+    const res = await ipRestriction(
+      () => '0.0.0.0',
+      { denyList: ['0.0.0.0'] },
+      () => new Response('error')
+    )(new Context(new HonoRequest(new Request('http://localhost/'))), async () => void 0)
+    expect(res).toBeTruthy()
+    if (res) {
+      expect(await res.text()).toBe('error')
+    }
+  })
+})
+
+describe('isMatchForRule', () => {
+  it('CIDR Notation', () => {
+    expect(isMatchForRule({ addr: '192.168.2.0', type: 'IPv4' }, '192.168.2.0/24')).toBeTruthy()
+    expect(isMatchForRule({ addr: '192.168.2.1', type: 'IPv4' }, '192.168.2.0/24')).toBeTruthy()
+
+    expect(isMatchForRule({ addr: '::0', type: 'IPv6' }, '::0/1')).toBeTruthy()
+  })
+  it('Static Rules', () => {
+    expect(isMatchForRule({ addr: '192.168.2.1', type: 'IPv4' }, '192.168.2.1')).toBeTruthy()
+    expect(isMatchForRule({ addr: '1234::5678', type: 'IPv6' }, '1234::5678')).toBeTruthy()
+  })
+  it('Function Rules', () => {
+    expect(isMatchForRule({ addr: '0.0.0.0', type: 'IPv4' }, () => true)).toBeTruthy()
+    expect(isMatchForRule({ addr: '0.0.0.0', type: 'IPv4' }, () => false)).toBeFalsy()
+
+    const randIP = Math.random().toString()
+    isMatchForRule({ addr: randIP, type: 'IPv4' }, (ip) => {
+      expect(randIP).toBe(ip.addr)
+      return false
+    })
+  })
+})

src/middleware/ip-restriction/index.ts

@@ -0,0 +1,146 @@
+/**
+ * Middleware for restrict IP Address
+ * @module
+ */
+
+import type { Context, MiddlewareHandler } from '../..'
+import type { AddressType, GetConnInfo } from '../../helper/conninfo'
+import { HTTPException } from '../../http-exception'
+import {
+  convertIPv4ToBinary,
+  convertIPv6ToBinary,
+  distinctRemoteAddr,
+  expandIPv6,
+} from '../../utils/ipaddr'
+
+/**
+ * Function to get IP Address
+ */
+type GetIPAddr = GetConnInfo | ((c: Context) => string)
+
+/**
+ * ### IPv4 and IPv6
+ * - `*` match all
+ *
+ * ### IPv4
+ * - `192.168.2.0` static
+ * - `192.168.2.0/24` CIDR Notation
+ *
+ * ### IPv6
+ * - `::1` static
+ * - `::1/10` CIDR Notation
+ */
+export type IPRestrictRule = string | ((addr: { addr: string; type: AddressType }) => boolean)
+
+const IS_CIDR_NOTATION_REGEX = /\/[0-9]{0,3}$/
+export const isMatchForRule = (
+  remote: {
+    addr: string
+    type: AddressType
+  },
+  rule: IPRestrictRule
+): boolean => {
+  if (rule === '*') {
+    // Match all
+    return true
+  }
+  if (typeof rule === 'function') {
+    return rule(remote)
+  }
+  if (IS_CIDR_NOTATION_REGEX.test(rule) && (remote.type === 'IPv4' || remote.type === 'IPv6')) {
+    const isIPv4 = remote.type === 'IPv4'
+
+    const splitedRule = rule.split('/')
+    // CIDR
+    const baseRuleAddr = splitedRule[0]
+    if (distinctRemoteAddr(baseRuleAddr) !== remote.type) {
+      return false
+    }
+    const prefix = parseInt(splitedRule[1])
+
+    const addrToBinary = isIPv4 ? convertIPv4ToBinary : convertIPv6ToBinary
+
+    const baseRuleMask = addrToBinary(baseRuleAddr)
+    const remoteMask = addrToBinary(remote.addr)
+    const mask = ((1n << BigInt(prefix)) - 1n) << BigInt((isIPv4 ? 32 : 128) - prefix)
+
+    return (remoteMask & mask) === (baseRuleMask & mask)
+  }
+
+  const ruleAddrConnType = distinctRemoteAddr(rule)
+  if (ruleAddrConnType === 'IPv4' || ruleAddrConnType === 'IPv6') {
+    // Static
+    if (ruleAddrConnType !== remote.type) {
+      return false
+    }
+    if (remote.type === 'IPv6') {
+      return expandIPv6(remote.addr) === expandIPv6(rule)
+    }
+    return rule === remote.addr // IPv4
+  }
+  throw new TypeError('Rule is unknown')
+}
+
+/**
+ * Rules for IP Limit Middleware
+ */
+export interface IPRestrictRules {
+  denyList?: IPRestrictRule[]
+  allowList?: IPRestrictRule[]
+}
+
+/**
+ * IP Limit Middleware
+ *
+ * @param getIP function to get IP Address
+ */
+export const ipRestriction = (
+  getIP: GetIPAddr,
+  { denyList = [], allowList = [] }: IPRestrictRules,
+  onError?: (remote: { addr: string; type: AddressType }) => Response | Promise<Response>
+): MiddlewareHandler => {
+  const denyLength = denyList.length
+  const allowLength = allowList.length
+
+  const blockError = (): HTTPException =>
+    new HTTPException(403, {
+      res: new Response('Unauthorized', {
+        status: 403,
+      }),
+    })
+
+  return async function (c, next) {
+    const connInfo = getIP(c)
+    const addr = typeof connInfo === 'string' ? connInfo : connInfo.remote.address
+    if (!addr) {
+      throw blockError()
+    }
+    const type =
+      (typeof connInfo !== 'string' && connInfo.remote.addressType) || distinctRemoteAddr(addr)
+
+    for (let i = 0; i < denyLength; i++) {
+      const isValid = isMatchForRule({ type, addr }, denyList[i])
+      if (isValid) {
+        if (onError) {
+          return onError({ type, addr })
+        }
+        throw blockError()
+      }
+    }
+    for (let i = 0; i < allowLength; i++) {
+      const isValid = isMatchForRule({ type, addr }, allowList[i])
+      if (isValid) {
+        return await next()
+      }
+    }
+
+    if (allowLength === 0) {
+      return await next()
+    } else {
+      if (onError) {
+        return await onError({ addr, type })
+      }
+      throw blockError()
+    }
+  }
+}

src/utils/ipaddr.test.ts

@@ -0,0 +1,39 @@
+import { convertIPv4ToBinary, convertIPv6ToBinary, distinctRemoteAddr, expandIPv6 } from './ipaddr'
+
+describe('expandIPv6', () => {
+  it('Should result be valid', () => {
+    expect(expandIPv6('1::1')).toBe('0001:0000:0000:0000:0000:0000:0000:0001')
+    expect(expandIPv6('::1')).toBe('0000:0000:0000:0000:0000:0000:0000:0001')
+    expect(expandIPv6('2001:2::')).toBe('2001:0002:0000:0000:0000:0000:0000:0000')
+    expect(expandIPv6('2001:2::')).toBe('2001:0002:0000:0000:0000:0000:0000:0000')
+    expect(expandIPv6('2001:0:0:db8::1')).toBe('2001:0000:0000:0db8:0000:0000:0000:0001')
+  })
+})
+describe('distinctRemoteAddr', () => {
+  it('Should result be valud', () => {
+    expect(distinctRemoteAddr('1::1')).toBe('IPv6')
+    expect(distinctRemoteAddr('::1')).toBe('IPv6')
+
+    expect(distinctRemoteAddr('192.168.2.0')).toBe('IPv4')
+    expect(distinctRemoteAddr('192.168.2.0')).toBe('IPv4')
+
+    expect(distinctRemoteAddr('example.com')).toBe('unknown')
+  })
+})
+
+describe('convertIPv4ToBinary', () => {
+  it('Should result is valid', () => {
+    expect(convertIPv4ToBinary('0.0.0.0')).toBe(0n)
+    expect(convertIPv4ToBinary('0.0.0.1')).toBe(1n)
+
+    expect(convertIPv4ToBinary('0.0.1.0')).toBe(1n << 8n)
+  })
+})
+describe('convertIPv6ToBinary', () => {
+  it('Should result is valid', () => {
+    expect(convertIPv6ToBinary('::0')).toBe(0n)
+    expect(convertIPv6ToBinary('::1')).toBe(1n)
+
+    expect(convertIPv6ToBinary('::f')).toBe(15n)
+  })
+})

src/utils/ipaddr.ts

@@ -0,0 +1,72 @@
+/**
+ * Utils for IP Addresses
+ * @module
+ */
+
+import type { AddressType } from '../helper/conninfo'
+
+/**
+ * Expand IPv6 Address
+ * @param ipV6 Shorten IPv6 Address
+ * @return expanded IPv6 Address
+ */
+export const expandIPv6 = (ipV6: string): string => {
+  const sections = ipV6.split(':')
+  for (let i = 0; i < sections.length; i++) {
+    const node = sections[i]
+    if (node !== '') {
+      sections[i] = node.padStart(4, '0')
+    } else {
+      sections[i + 1] === '' && sections.splice(i + 1, 1)
+      sections[i] = new Array(8 - sections.length + 1).fill('0000').join(':')
+    }
+  }
+  return sections.join(':')
+}
+
+const IPV4_REGEX = /^[0-9]{0,3}\.[0-9]{0,3}\.[0-9]{0,3}\.[0-9]{0,3}$/
+
+/**
+ * Distinct Remote Addr
+ * @param remoteAddr Remote Addr
+ */
+export const distinctRemoteAddr = (remoteAddr: string): AddressType => {
+  if (IPV4_REGEX.test(remoteAddr)) {
+    return 'IPv4'
+  }
+  if (remoteAddr.includes(':')) {
+    // Domain can't include `:`
+    return 'IPv6'
+  }
+  return 'unknown'
+}
+
+/**
+ * Convert IPv4 to Uint8Array
+ * @param ipV4 IPv4 Address
+ * @returns BigInt
+ */
+export const convertIPv4ToBinary = (ipV4: string): bigint => {
+  const parts = ipV4.split('.')
+  let result = 0n
+  for (let i = 0; i < 4; i++) {
+    result <<= 8n
+    result += BigInt(parts[i])
+  }
+  return result
+}
+
+/**
+ * Convert IPv6 to Uint8Array
+ * @param ipV6 IPv6 Address
+ * @returns BigInt
+ */
+export const convertIPv6ToBinary = (ipV6: string): bigint => {
+  const sections = expandIPv6(ipV6).split(':')
+  let result = 0n
+  for (let i = 0; i < 8; i++) {
+    result <<= 16n
+    result += BigInt(parseInt(sections[i], 16))
+  }
+  return result
+}