hono-cf-access

Access control middleware for Hono leveraging Cloudflare Workers' request.cf properties.

Add country blocking, ASN blocking, and maintenance mode to any route with a single line.

Features

• request.cf native — Uses geo data Cloudflare Workers provides for free
• Declarative API — Declare deny/allow lists, no hand-written conditionals
• Three middlewares — countryBlock(), asnBlock(), maintenance()
• RFC 9457 compliant — application/problem+json error responses
• Customizable — onDenied / onMaintenance escape hatches for custom responses
• fallback option — Controls behavior when request.cf is undefined (local dev)
• cfInfo context variable — Normalized geo data accessible from handlers
• Zero external dependencies — Only requires Hono as a peer dependency

Install

npm install hono-cf-access

Usage

Country Blocking

import { Hono } from 'hono'
import { countryBlock } from 'hono-cf-access'

const app = new Hono()

// Deny access from specific countries
app.use('/api/*', countryBlock({
  deny: ['CN', 'RU'],
}))

// Or allow only specific countries
app.use('/api/*', countryBlock({
  allow: ['JP', 'US', 'GB'],
}))

ASN Blocking

import { asnBlock } from 'hono-cf-access'

// Deny access from specific ASNs
app.use('/api/*', asnBlock({
  deny: [4134, 4837],
}))

// Or allow only specific ASNs
app.use('/api/*', asnBlock({
  allow: [13335, 209242],
}))

Maintenance Mode

import { maintenance } from 'hono-cf-access'

// Static toggle
app.use('/api/*', maintenance({
  enabled: true,
}))

// Dynamic toggle via KV
app.use('/api/*', maintenance({
  enabled: async (c) => {
    const kv = c.env.MAINTENANCE_KV as KVNamespace
    return (await kv.get('maintenance_mode')) === 'true'
  },
}))

// With IP allowlist for admin access
app.use('/api/*', maintenance({
  enabled: true,
  allowedIps: [
    '203.0.113.50',
    '192.168.1.0/24',
  ],
  retryAfter: 3600,
}))

Middleware Chaining

app.use('/api/*',
  countryBlock({ deny: ['CN', 'RU'] }),
  asnBlock({ deny: [4134] }),
  maintenance({ enabled: async (c) => { /* ... */ } }),
)

Each middleware operates independently. If one denies the request, subsequent ones are not executed.

Accessing Geo Data

All middlewares set a cfInfo context variable with normalized geo data:

app.get('/api/info', (c) => {
  const info = c.get('cfInfo')
  // info.country  → 'JP'
  // info.asn      → 13335
  // info.city     → 'Tokyo'
  // info.timezone → 'Asia/Tokyo'
  return c.json(info)
})

Custom Error Responses

countryBlock({
  deny: ['CN'],
  onDenied: (c) => c.html('<h1>Access Denied</h1>', 403),
})

maintenance({
  enabled: true,
  onMaintenance: (c) => c.html('<h1>Under Maintenance</h1>', 503),
})

API

countryBlock(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | deny | string[] | — | Country codes to deny (ISO 3166-1 alpha-2) | | allow | string[] | — | Country codes to allow. All others denied | | fallback | 'allow' \| 'deny' | 'allow' | Behavior when request.cf is undefined | | onDenied | (c: Context) => Response | — | Custom response for denied requests |

deny and allow are mutually exclusive. Specifying both throws at initialization.

asnBlock(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | deny | number[] | — | ASN numbers to deny | | allow | number[] | — | ASN numbers to allow. All others denied | | fallback | 'allow' \| 'deny' | 'allow' | Behavior when request.cf is undefined | | onDenied | (c: Context) => Response | — | Custom response for denied requests |

maintenance(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean \| (c: Context) => boolean \| Promise<boolean> | — | Whether maintenance mode is active | | allowedIps | string[] | — | IPs/CIDRs that bypass maintenance (IPv4 and IPv6) | | retryAfter | number \| string | — | Retry-After header value | | fallback | 'allow' \| 'deny' | 'allow' | Behavior when IP cannot be resolved | | onMaintenance | (c: Context) => Response | — | Custom maintenance response |

CfInfo

interface CfInfo {
  country?: string
  asn?: number
  city?: string
  region?: string
  regionCode?: string
  continent?: string
  latitude?: string
  longitude?: string
  timezone?: string
  postalCode?: string
}

Error Responses

Default responses follow RFC 9457 Problem Details (Content-Type: application/problem+json):

| Scenario | Status | Type | |----------|--------|------| | Country denied | 403 | /errors/country-denied | | ASN denied | 403 | /errors/asn-denied | | Maintenance | 503 | /errors/maintenance | | CF data unavailable (strict) | 403 | /errors/cf-unavailable |

Example response:

{
  "type": "https://hono-cf-access.dev/errors/country-denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access from country 'CN' is not allowed",
  "instance": "/api/data"
}

Difference from @hono/cloudflare-access

• @hono/cloudflare-access: Validates Cloudflare Access JWT tokens (authentication)
• hono-cf-access: Access control using request.cf geo data (authorization/filtering)

License

MIT