next-geo-block 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bharadwaj Giridhar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# next-geo-block
+
+> Per-page geo-blocking for Next.js. Block specific countries on specific routes — not everything globally.
+
+- **Per-route rules** — block `RU`/`CN` only on `/checkout`, block `KP`/`IR` only on `/admin`, leave everything else open
+- **Works on Vercel out of the box** — reads `x-vercel-ip-country`. Also reads `cf-ipcountry` (Cloudflare) and `x-country-code` (generic)
+- **Optional timezone fallback** — bundled IANA → ISO 3166-1 map (~250 zones) for hosts without an IP-country header
+- **Tiny** — 11.5 kB packed, zero runtime deps, edge-runtime safe
+- **Works with `proxy.ts` (Next 16.2+) and `middleware.ts` (Next 13–16.1)**
+
+```bash
+npm install next-geo-block
+```
+
+---
+
+## Quick start
+
+```ts
+// proxy.ts — Next.js 16.2+    (or middleware.ts on 13–16.1)
+import { createGeoBlock } from 'next-geo-block'
+
+export const proxy = createGeoBlock({
+  rules: [
+    { paths: ['/checkout', '/checkout/*'], block: ['CN', 'RU'] },
+    { paths: ['/admin/*'],                 block: ['CN', 'RU', 'KP', 'IR'] },
+  ],
+})
+
+export const config = {
+  // Keep `/blocked` and static assets out so the proxy never loops.
+  matcher: ['/((?!_next|api|blocked|favicon.ico|.*\\..*).*)'],
+}
+```
+
+Add a `app/blocked/page.tsx`:
+
+```tsx
+export default function Blocked() {
+  return <main>This site isn’t available in your region.</main>
+}
+```
+
+That's it. Blocked countries see your `/blocked` page at the original URL (clean UX, no redirect). Everyone else sees the real page.
+
+---
+
+## How country detection works
+
+```mermaid
+flowchart TD
+    A[Incoming request] --> B{Path matches a rule?}
+    B -->|No| Z1[Pass through]
+    B -->|Yes| C[Try custom headers]
+    C -->|Found| H[Country resolved]
+    C -->|None| D[Try x-vercel-ip-country]
+    D -->|Found, not 'XX'| H
+    D -->|Missing or 'XX'| E[Try cf-ipcountry]
+    E -->|Found, not 'XX'| H
+    E -->|Missing or 'XX'| F[Try x-country-code]
+    F -->|Found| H
+    F -->|None| G{fallbackTimezone enabled?}
+    G -->|No| I{failOpen?}
+    G -->|Yes| J[Read cookie / header,<br/>map IANA tz → country]
+    J -->|Resolved| H
+    J -->|Unknown tz| I
+    H --> K{Country in rule's block list?}
+    K -->|No| Z2[Pass through]
+    K -->|Yes| L[Block: rewrite to /blocked,<br/>or 451, or onBlock]
+    I -->|Open| Z3[Pass through]
+    I -->|Closed| L
+```
+
+---
+
+## API
+
+### `createGeoBlock(options)`
+
+| Option              | Type                       | Default       | Notes                                                                                                                                          |
+| ------------------- | -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rules`             | `GeoBlockRule[]`           | **required**  | Evaluated in order; first match wins.                                                                                                          |
+| `blockedPath`       | `string \| null`           | `'/blocked'`  | Path to rewrite blocked requests to. `null` → return a 451 status instead.                                                                     |
+| `failOpen`          | `boolean`                  | `true`        | When no country can be resolved, let through (`true`) or block (`false`).                                                                      |
+| `onBlock`           | `(ctx) => Response`        | —             | Custom response. Overrides `blockedPath`. Receives `{ request, country, pathname, matchedRule, source }`. Return `NextResponse.next()` for soft-block (log-only). |
+| `countryHeaders`    | `string[]`                 | `[]`          | Extra headers, tried first. Built-ins always tried after.                                                                                      |
+| `fallbackTimezone`  | `boolean \| TimezoneFallback` | `false`    | See [Timezone fallback](#timezone-fallback).                                                                                                   |
+
+### `GeoBlockRule`
+
+```ts
+{
+  paths: Array<string | RegExp>  // see Path pattern syntax below
+  block: string[]                // ISO 3166-1 alpha-2, case-insensitive
+}
+```
+
+### Path pattern syntax
+
+| Pattern                                | Matches                                  | Example match                       |
+| -------------------------------------- | ---------------------------------------- | ----------------------------------- |
+| `/checkout`                            | exact path (+ trailing slash)            | `/checkout`, `/checkout/`           |
+| `/checkout/*`                          | any depth under `/checkout`              | `/checkout/cart`, `/checkout/a/b/c` |
+| `/u/*/settings`                        | single-segment wildcard between literals | `/u/alice/settings`                 |
+| `/^\/api\/v\d+\/private/` _(RegExp)_   | any anchored regex                       | `/api/v2/private/keys`              |
+
+---
+
+## Use cases
+
+### 1. E-commerce: block sanctioned countries from checkout
+
+```ts
+createGeoBlock({
+  rules: [
+    { paths: ['/checkout/*', '/api/checkout/*'], block: ['CU', 'IR', 'KP', 'SY', 'RU'] },
+  ],
+})
+```
+
+Browsing the catalogue stays open; payment endpoints reject sanctioned regions.
+
+### 2. SaaS admin lockdown: only your team's regions
+
+Invert it — allow a list, block everything else:
+
+```ts
+const ALLOWED = new Set(['US', 'CA', 'GB', 'IN'])
+
+createGeoBlock({
+  rules: [{ paths: ['/admin/*'], block: [] }], // matcher only
+  onBlock: () => new NextResponse('Forbidden', { status: 403 }),
+  countryHeaders: [],
+  failOpen: false, // unknown = blocked
+  // Custom logic via onBlock:
+})
+```
+
+For invert-style allowlists, use a tiny custom proxy instead — the package's primary mode is denylist:
+
+```ts
+import { getCountry } from 'next-geo-block'
+import { NextResponse, type NextRequest } from 'next/server'
+
+const ALLOWED = new Set(['US', 'CA', 'GB', 'IN'])
+
+export function proxy(req: NextRequest) {
+  if (!req.nextUrl.pathname.startsWith('/admin')) return NextResponse.next()
+  const c = getCountry(req)
+  if (c && ALLOWED.has(c)) return NextResponse.next()
+  return NextResponse.rewrite(new URL('/blocked', req.url))
+}
+```
+
+### 3. Content licensing: hide region-locked pages
+
+```ts
+createGeoBlock({
+  rules: [
+    { paths: ['/watch/sports/*'],  block: ['US', 'CA'] }, // licence excludes NA
+    { paths: ['/watch/anime/*'],   block: ['JP'] },        // licence excludes JP
+  ],
+  blockedPath: '/region-locked',
+})
+```
+
+### 4. Compliance-driven hard block (no fail-open)
+
+For GDPR-affected pages or KYC flows where unknown ≠ allowed:
+
+```ts
+createGeoBlock({
+  rules: [{ paths: ['/kyc/*'], block: ['IR', 'KP', 'SY', 'CU'] }],
+  failOpen: false,
+  blockedPath: null,           // return 451 Unavailable For Legal Reasons
+  fallbackTimezone: true,      // best-effort signal when header is missing
+})
+```
+
+### 5. Log-only / soft-block (warmup phase)
+
+Roll out without blocking real users — observe what would have been blocked:
+
+```ts
+import { NextResponse } from 'next/server'
+
+createGeoBlock({
+  rules: [{ paths: ['/checkout/*'], block: ['RU', 'CN'] }],
+  onBlock: async ({ country, pathname }) => {
+    await fetch('https://logs.example.com/geo-soft-block', {
+      method: 'POST',
+      body: JSON.stringify({ country, pathname, ts: Date.now() }),
+    })
+    return NextResponse.next() // let it through anyway
+  },
+})
+```
+
+Flip to a real block (drop the `NextResponse.next()`) once the volume looks right.
+
+### 6. Per-environment rules
+
+```ts
+const blockedCountries =
+  process.env.NODE_ENV === 'production' ? ['CN', 'RU', 'KP'] : []
+
+createGeoBlock({
+  rules: [{ paths: ['/checkout/*'], block: blockedCountries }],
+})
+```
+
+---
+
+## Timezone fallback
+
+Hosts that don't terminate at Vercel/Cloudflare often won't inject an IP-country header. Use the client's local timezone (`Intl.DateTimeFormat().resolvedOptions().timeZone`) as a secondary signal.
+
+### How it actually works
+
+Middleware runs on the **edge, before any client JS executes**. It can't read `Intl.DateTimeFormat()` directly — the client has to deliver the timezone over the wire. That means a two-pass model:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant E as Edge (proxy.ts)
+    participant S as Server (page)
+    Note over U,E: First request — no cookie yet
+    U->>E: GET /checkout
+    E->>E: No country header,<br/>no tz cookie
+    E->>S: Pass through (failOpen)
+    S-->>U: HTML + tz-cookie-setter <script>
+    Note over U: Browser sets cookie<br/>client_tz=Asia/Kolkata
+    Note over U,E: Subsequent requests
+    U->>E: GET /admin (cookie set)
+    E->>E: Map Asia/Kolkata → IN
+    E->>U: /blocked content (rewrite)
+```
+
+The first request to a blocked path can slip through; every request afterward (same session, same cookie) is enforced. If first-request enforcement matters, **don't rely on timezone alone** — use a real IP-country header.
+
+### Wiring it up (App Router)
+
+`app/layout.tsx`:
+
+```tsx
+import Script from 'next/script'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <head>
+        <Script id="next-geo-block-tz" strategy="beforeInteractive">
+          {`try{document.cookie='client_tz='+encodeURIComponent(Intl.DateTimeFormat().resolvedOptions().timeZone)+';path=/;max-age=31536000;samesite=lax'}catch(e){}`}
+        </Script>
+      </head>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+Then turn on the fallback:
+
+```ts
+createGeoBlock({
+  rules: [{ paths: ['/checkout/*'], block: ['IN'] }],
+  fallbackTimezone: true, // reads cookie `client_tz` (default)
+})
+```
+
+### API-only routes — header on `fetch`
+
+If the protected route is a client-side `fetch`, skip the cookie and send a header:
+
+```ts
+fetch('/api/private', {
+  headers: { 'x-client-timezone': Intl.DateTimeFormat().resolvedOptions().timeZone },
+})
+```
+
+### Custom names + custom resolver
+
+```ts
+createGeoBlock({
+  rules: [{ paths: ['/admin/*'], block: ['KP'] }],
+  fallbackTimezone: {
+    cookie: 'tz',
+    header: 'x-tz',
+    resolve: (tz) => myMap[tz] ?? undefined, // override bundled IANA map
+  },
+})
+```
+
+### Caveats
+
+- **Spoofable.** A user can clear the cookie or send a fake one. Timezone is a hint, not enforcement.
+- **First-request lag.** The first request has no cookie. `failOpen` decides.
+- **Coverage.** Bundled map covers all canonical IANA zones + common legacy aliases (`Asia/Calcutta`, `Europe/Kiev`, `Asia/Saigon`, all `Australia/*` state aliases). Unknown zones → `undefined`.
+- **Disambiguation.** A few zones span multiple countries (`Europe/Busingen`, `America/Kralendijk`); the bundled map picks the primary. Pass a custom `resolve` for your own rules.
+
+---
+
+## Recipes
+
+### Hard 451 instead of a rewrite
+
+```ts
+createGeoBlock({
+  rules: [{ paths: ['/admin/*'], block: ['KP'] }],
+  blockedPath: null,
+})
+```
+
+### Custom JSON for API routes
+
+```ts
+createGeoBlock({
+  rules: [{ paths: ['/api/*'], block: ['KP'] }],
+  onBlock: ({ country, pathname, source }) =>
+    new Response(
+      JSON.stringify({ error: 'geo_blocked', country, pathname, source }),
+      { status: 403, headers: { 'content-type': 'application/json' } },
+    ),
+})
+```
+
+`source` is `'header'` or `'timezone'` — useful for logging which signal triggered the block.
+
+### Multiple matchers per rule
+
+```ts
+createGeoBlock({
+  rules: [{
+    paths: ['/checkout', '/checkout/*', '/api/checkout/*', /^\/v\d+\/pay/],
+    block: ['CN', 'RU'],
+  }],
+})
+```
+
+### Custom IP-country header (e.g. behind your own CDN)
+
+```ts
+createGeoBlock({
+  rules: [{ paths: ['/*'], block: ['KP'] }],
+  countryHeaders: ['x-my-cdn-country'],
+})
+```
+
+---
+
+## Comparison
+
+| Capability                       | next-geo-block | DIY middleware | `@vercel/edge` geolocation | Cloudflare WAF |
+| -------------------------------- | -------------- | -------------- | -------------------------- | -------------- |
+| Per-route rules                  | ✅              | ✅ (you write)  | ✅ (you write)              | ✅              |
+| Vercel + Cloudflare + generic    | ✅              | ✅ (you write)  | Vercel-only                | CF-only        |
+| Timezone fallback                | ✅              | ❌              | ❌                          | ❌              |
+| Bundled IANA→country map         | ✅              | ❌              | ❌                          | n/a            |
+| No external service              | ✅              | ✅              | ✅                          | ❌              |
+| Lines of user code               | ~5             | ~30+           | ~15+                       | (config UI)    |
+
+---
+
+## Production checklist
+
+Before shipping geo-blocking to production:
+
+- [ ] Add a real `/blocked` page that explains *what* is blocked and *who* to contact for appeals
+- [ ] Decide on `failOpen` policy (default `true` is right for most apps; `false` for compliance)
+- [ ] Confirm your matcher excludes `/blocked` and static assets — otherwise infinite rewrite loop
+- [ ] Test with `curl -H "x-vercel-ip-country: CN"` against `next dev` — the header is **not** set locally
+- [ ] If using timezone fallback: ship the inline `<Script>` and verify the cookie appears in DevTools
+- [ ] If using `failOpen: false`: ensure local dev still works (set a dev header or `failOpen: process.env.NODE_ENV === 'production' ? false : true`)
+- [ ] Log blocks to your observability tool via `onBlock` so you can audit false positives
+- [ ] Review the country list against current sanctions guidance (OFAC SDN, EU restrictive measures) — package ships no opinion on which countries to block
+
+---
+
+## FAQ
+
+**Does this work locally?**
+Yes — but `x-vercel-ip-country` is only set in production by Vercel's edge. Locally, pass it yourself: `curl -H 'x-vercel-ip-country: CN' http://localhost:3000/checkout`.
+
+**Does this work on the Edge runtime?**
+Yes. Zero Node-only imports. Compiles into Vercel Edge Middleware (~39 kB middleware bundle in a real Next 15 app).
+
+**Will this work on Next.js 16?**
+Yes. Use `proxy.ts` instead of `middleware.ts`, export `proxy` instead of `middleware`. The `config.matcher` is identical.
+
+**Can users bypass this with a VPN?**
+Yes. Geo-blocking via IP is best-effort. Anyone determined will route around it. Use this for soft enforcement (UX, licensing, sanctions compliance posture), not as your only line of defence.
+
+**Can users bypass timezone fallback by clearing the cookie?**
+Yes. Timezone is a hint, never enforcement. See [Caveats](#caveats).
+
+**Why does `/checkout` from a blocked country return 200 instead of a redirect?**
+The package uses `NextResponse.rewrite()` — the URL stays `/checkout` but the response body is `/blocked`'s. This is intentional: it's cleaner UX, doesn't leak which page the user tried to reach, and avoids redirect chains. Set `blockedPath: null` for a hard 451 instead.
+
+**Why is Cloudflare's `XX` country code treated as missing?**
+Cloudflare emits `XX` when they can't determine the country (per their docs). Treating it as a real country would prevent the timezone fallback from firing — `XX` is not in any rule's block list, so it would just silently pass through and skip the fallback. We treat it as "unknown" instead.
+
+**Can I use this without Next.js?**
+No — it depends on `next/server` for `NextRequest`/`NextResponse`. For raw Node, fork the ~250 lines of source.
+
+**How do I keep this in sync with sanctions lists?**
+You don't — the package ships zero country opinions. Pull current lists from [OFAC](https://sanctionssearch.ofac.treas.gov/), [EU CFSP](https://www.sanctionsmap.eu/), etc. and pass them in.
+
+---
+
+## License
+
+MIT