@idevconn/allowlist-guard 0.0.0 → 0.2.0

package/README.md

@@ -1,11 +1,23 @@
 # @idevconn/allowlist-guard
 
-Global NestJS guard that restricts routes by **source IP / CIDR**. Two independent allowlists: one for protected (authenticated) routes, one for public ("open") routes. Works on Fastify and Express. No runtime dependencies (uses `node:net` `BlockList`).
+Global NestJS guard that restricts routes by **source IP / CIDR**. Two independent allowlists (one for protected/authenticated routes, one for public/"open" routes) plus a global **denylist** to block specific addresses. Works on Fastify and Express. No runtime dependencies (uses `node:net` `BlockList`).
+
+> [!IMPORTANT]
+> **What this guard does NOT protect against.**
+> It decides by the caller's **IP address only**. It does **not** stop Postman, curl, scripts or Playwright/Puppeteer **coming from an allowed IP** — to the server those requests look exactly like your own front end:
+>
+> - `Origin`, `Referer`, `User-Agent` and `Sec-Fetch-*` headers are trivially forged by Postman/curl, so header checks give no protection.
+> - Playwright/Puppeteer drive a real Chromium; headers and fingerprint are indistinguishable from a human's browser.
+> - A secret embedded in a front-end bundle (API key, HMAC) is extractable in a minute.
+> - Anyone with a valid login can replay requests from a script.
+>
+> The allowlist only helps when your legitimate clients have **known, stable IPs** (office, VPN, your own servers): a request from anywhere else gets `403`. For an **open** API (any user from the internet) an IP list is the wrong tool — use authentication, per-account rate limits and quotas, CAPTCHA / bot protection at the edge (e.g. Cloudflare Turnstile / Bot Management), and registration controls. The denylist is not a substitute either: banned clients just change address. Treat this guard as an outer perimeter, not as bot protection.
 
 ## Features
 
 - IPv4 + IPv6, single addresses and CIDR ranges; IPv4-mapped IPv6 (`::ffff:1.2.3.4`) is normalised.
-- Separate lists for `protected` and `public` routes. A list that is unset/blank is **not enforced**, so adopting the guard is non-breaking.
+- **Allow** (`protected`, `public`) and **deny** (`deny`) lists: "only these", "everyone except these", or both. Deny always wins.
+- Separate allowlists for `protected` and `public` routes. A list that is unset/blank is **not enforced**, so adopting the guard is non-breaking.
 - Loopback (`127.0.0.0/8`, `::1`) is allowed once a list is set (local dev, health probes) — disable with `allowLoopback: false` (see below).
 - `@SkipIpAllowlist()` exempts a route or controller (e.g. HMAC-signed provider webhooks whose IPs you cannot pin).
 - A malformed entry throws at boot naming the option — a typo never silently becomes "everyone allowed" or "everyone blocked".
@@ -19,21 +31,25 @@ Global NestJS guard that restricts routes by **source IP / CIDR**. Two independe
 npm install @idevconn/allowlist-guard
 ```
 
-Peer dependencies: `@nestjs/common`, `@nestjs/core` (10 or 11), `reflect-metadata`, `rxjs`; `fastify` only if you use the `/fastify` subpath.
+Peer dependencies: `@nestjs/common`, `@nestjs/core` (10 or 11), `reflect-metadata`, `rxjs`. The `/fastify` subpath has no `fastify` dependency (it is typed structurally).
 
 ## Usage
 
+### Minimal (NestJS on Express, the default adapter)
+
 ```ts
+// app.module.ts
 import { Module } from "@nestjs/common";
 import { IpAllowlistModule } from "@idevconn/allowlist-guard";
+import { AuthModule } from "./auth/auth.module";
 
 @Module({
   imports: [
     // Import BEFORE the module that registers your auth guard, so a blocked IP
     // is rejected before any authentication work.
     IpAllowlistModule.forRoot({
-      protected: process.env.API_IP_ALLOWLIST, // "203.0.113.5, 10.0.0.0/8"
-      public: process.env.API_PUBLIC_IP_ALLOWLIST, // login, lead capture, ...
+      protected: "203.0.113.5, 10.0.0.0/8, 2001:db8::/32", // authenticated routes
+      public: "198.51.100.0/24", // @Public routes: login, lead capture, ...
     }),
     AuthModule,
   ],
@@ -41,61 +57,233 @@ import { IpAllowlistModule } from "@idevconn/allowlist-guard";
 export class AppModule {}
 ```
 
+```ts
+// main.ts
+import { NestFactory } from "@nestjs/core";
+import type { NestExpressApplication } from "@nestjs/platform-express";
+import { AppModule } from "./app.module";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
+  app.set("trust proxy", 1); // behind ONE reverse proxy; see "Getting the real client IP"
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+### Options
+
 | Option              | Meaning                                                                                              |
 | ------------------- | ---------------------------------------------------------------------------------------------------- |
 | `protected`         | Comma-separated string or array of IPs/CIDRs for non-public routes. Unset/blank = not enforced.      |
 | `public`            | Same, for public routes.                                                                             |
+| `deny`              | Denylist for **all** routes: comma-separated string or array of IPs/CIDRs that are always rejected. Wins over the allowlists. Unset/blank = nothing denied. |
 | `publicMetadataKey` | Metadata key marking a route public. Default `'isPublic'` (the common `@Public()` decorator's key).  |
 | `allowLoopback`     | Default `true`. Set `false` if a reverse proxy runs on the same host (see below).                    |
-| `onBlocked`         | `(ip) => void`, called on every blocked request. Default: a rate-limited Nest `Logger.warn`.         |
+| `onBlocked`         | `(ip, reason) => void`, called on every blocked request; `reason` is `"denied"` or `"not_allowed"`. Default: a rate-limited Nest `Logger.warn`. |
 
 **The two lists are independent.** Setting only `protected` leaves `@Public` routes (login, lead capture, ...) open to everyone, and vice versa. Set both if you want the whole surface restricted; exempt individual routes with `@SkipIpAllowlist()`.
 
-Exempt a route:
+### Configuration from the environment (`@nestjs/config`)
+
+`forRoot()` takes plain values, so read them from `process.env`. `ConfigModule.forRoot()` loads `.env` synchronously, so list it **before** the allowlist module:
 
 ```ts
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    IpAllowlistModule.forRoot({
+      protected: process.env.API_IP_ALLOWLIST, // unset/blank => not enforced
+      public: process.env.API_PUBLIC_IP_ALLOWLIST,
+      allowLoopback: process.env.API_IP_ALLOWLIST_ALLOW_LOOPBACK !== "false",
+    }),
+    AuthModule,
+  ],
+})
+export class AppModule {}
+```
+
+```bash
+# .env
+API_IP_ALLOWLIST=203.0.113.5,10.0.0.0/8
+API_PUBLIC_IP_ALLOWLIST=198.51.100.0/24
+```
+
+A malformed entry (`API_IP_ALLOWLIST=203.0.113.5,banana`) throws at boot naming the option, so a typo never silently opens or closes the API.
+
+### NestJS on Fastify
+
+```ts
+// main.ts
+import { NestFactory } from "@nestjs/core";
+import { FastifyAdapter, type NestFastifyApplication } from "@nestjs/platform-fastify";
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import { buildTrustProxy, parseIpAllowlist, restrictRoutesToAllowlist } from "@idevconn/allowlist-guard/fastify";
+import { AppModule } from "./app.module";
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter({
+      // One trusted hop, and only when the socket peer is one of YOUR proxies.
+      trustProxy: buildTrustProxy(process.env.TRUSTED_PROXIES),
+    }),
+  );
+
+  // Swagger UI is a Fastify route outside Nest's guard pipeline: restrict it too,
+  // BEFORE SwaggerModule.setup registers it.
+  const allowed = parseIpAllowlist(process.env.API_IP_ALLOWLIST);
+  const denied = parseIpAllowlist(process.env.API_IP_DENYLIST, "deny", { allowLoopback: false });
+  if (allowed || denied) {
+    restrictRoutesToAllowlist(app.getHttpAdapter().getInstance(), allowed, "/api/docs", denied);
+  }
+  const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
+  SwaggerModule.setup("api/docs", app, document);
+
+  await app.listen(3000, "0.0.0.0");
+}
+bootstrap();
+```
+
+### What gets blocked: allow vs deny
+
+| Configured                               | Result                                                                                         |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| nothing                                  | Guard off: everyone is let in (today's behaviour).                                             |
+| `deny` only                              | **Everyone except the listed IPs/CIDRs** ("block these, allow the rest").                      |
+| `protected` and/or `public` only         | **Only the listed IPs**, per route class (the other class stays open).                         |
+| allowlist(s) + `deny`                    | Allowed IPs get in, **except** any that are also denied. Deny always wins.                     |
+
+Order of checks per request: RPC contexts are exempt → **`deny`** (every route, including `@SkipIpAllowlist` ones) → `@SkipIpAllowlist()` → the route's allowlist (`public` for public routes, otherwise `protected`).
+
+### Blocking specific IPs (denylist)
+
+Let everyone in, but reject some addresses:
+
+```ts
+IpAllowlistModule.forRoot({
+  // IPs and CIDRs (IPv4 + IPv6), comma-separated string or array.
+  deny: "203.0.113.5, 198.51.100.0/24, 2001:db8::/32",
+});
+```
+
+Combine with an allowlist — e.g. a whole office range except one compromised host:
+
+```ts
+IpAllowlistModule.forRoot({
+  protected: "10.0.0.0/8",
+  deny: ["10.1.2.3"], // inside the allowed range, still blocked
+});
+```
+
+From the environment:
+
+```ts
+IpAllowlistModule.forRoot({
+  protected: process.env.API_IP_ALLOWLIST,
+  public: process.env.API_PUBLIC_IP_ALLOWLIST,
+  deny: process.env.API_IP_DENYLIST, // "203.0.113.5,198.51.100.0/24"
+});
+```
+
+Notes:
+
+- `deny` applies to **every** route, including ones marked `@SkipIpAllowlist()` (e.g. webhooks): a banned address is banned everywhere. Be careful not to list a range your providers call from.
+- Loopback is **never** denied implicitly (only if you list it). It is also not allowed implicitly by `deny` alone, because without an allowlist everything not denied is allowed anyway.
+- A malformed entry throws at boot (`deny: invalid IP/CIDR "banana"`), so a typo never silently disables the ban.
+- Identify why a request was blocked in `onBlocked((ip, reason) => ...)`: `"denied"` vs `"not_allowed"`. The default log line differs too (`denylisted IP` / `non-allowlisted IP`).
+- Both outcomes return the same `403 ip_not_allowed`.
+- Without an allowlist the guard can only judge requests that carry a client IP (HTTP). Non-HTTP contexts such as GraphQL/WebSocket have no resolvable `req.ip` here, so a deny-only setup cannot ban them (with an allowlist they are denied, fail closed).
+
+**Limits of IP bans.** An address changes with a VPN, proxy or mobile network, and a ban on a shared address (office, carrier NAT) blocks everyone behind it. To stop a specific *person*, suspend their account; use the denylist for abusive addresses, scanners and floods. For permanent, high-volume blocking prefer the edge (nginx `deny`, Cloudflare WAF, firewall), which stops traffic before it reaches your app.
+
+### Exempting routes
+
+```ts
+import { Controller, Post, SetMetadata } from "@nestjs/common";
 import { SkipIpAllowlist } from "@idevconn/allowlist-guard";
 
-@Public()
-@SkipIpAllowlist() // authenticated by an HMAC signature instead
-@Post("webhooks/:provider")
-receive() {}
+const Public = () => SetMetadata("isPublic", true); // your existing @Public()
+
+@Controller("webhooks")
+export class WebhooksController {
+  // Providers call from IPs you cannot pin; authenticate by HMAC signature instead.
+  @Public()
+  @SkipIpAllowlist()
+  @Post(":provider")
+  receive() {}
+}
 ```
 
-## Getting the real client IP (read this)
+`@SkipIpAllowlist()` also works on a whole controller class (e.g. a health check controller). It exempts a route from the **allowlists only**; the `deny` list still applies.
 
-The guard reads `request.ip` and **never** parses `X-Forwarded-For` itself. Behind a reverse proxy/load balancer, configure your framework's trust-proxy setting so `req.ip` is the real client:
+### Using your own "public" decorator
 
-- **Express:** `app.set("trust proxy", 1)`.
-- **Fastify:**
+If your project marks open routes with a different metadata key, tell the guard:
 
-  ```ts
-  import { buildTrustProxy } from "@idevconn/allowlist-guard/fastify";
+```ts
+export const OPEN_ROUTE = "openRoute";
+export const Open = () => SetMetadata(OPEN_ROUTE, true);
 
-  new FastifyAdapter({ trustProxy: buildTrustProxy(process.env.TRUSTED_PROXIES) });
-  ```
+IpAllowlistModule.forRoot({ public: "198.51.100.0/24", publicMetadataKey: OPEN_ROUTE });
+```
 
-  `buildTrustProxy()` trusts one hop. Hop 0 is the socket peer, so **if the app port is reachable directly, any client can forge `X-Forwarded-For` and pass the allowlist**. Either make the port reachable only via your proxy, or pass `trustedProxies` (the proxy's IP/CIDR) so a direct client's header is ignored.
+### Alerting on blocked requests
 
-Without any trust-proxy setting `req.ip` is the proxy's own address for every client. If that proxy runs on the **same host**, that address is loopback — which is allowed by default, so the allowlist would be wide open. Set `allowLoopback: false` in that setup (and keep trust-proxy configured).
+`onBlocked` runs on **every** blocked request (the default log line is rate-limited to one per IP per minute), so feed metrics from it:
 
-## Routes outside Nest (Swagger UI)
+```ts
+IpAllowlistModule.forRoot({
+  protected: process.env.API_IP_ALLOWLIST,
+  onBlocked: (ip, reason) =>
+    metrics.increment("ip_allowlist.blocked", { ip: ip ?? "unknown", reason }), // "denied" | "not_allowed"
+});
+```
 
-Fastify-native routes never reach Nest guards. Restrict them with the same list, **before** registering them:
+### Using the matcher on its own
 
 ```ts
-import { parseIpAllowlist, restrictRoutesToAllowlist } from "@idevconn/allowlist-guard/fastify";
+import { parseIpAllowlist } from "@idevconn/allowlist-guard";
+
+const isAllowed = parseIpAllowlist("203.0.113.5, 10.0.0.0/8", "myList");
+isAllowed?.("10.4.5.6"); // true  (returns null when the list is blank = not enforced)
+isAllowed?.("::ffff:203.0.113.5"); // true  (IPv4-mapped IPv6 is normalised)
+isAllowed?.("8.8.8.8"); // false
+
+// A denylist matcher: no implicit loopback.
+const isBanned = parseIpAllowlist("203.0.113.5", "deny", { allowLoopback: false });
+isBanned?.("203.0.113.5"); // true
+```
+
+### Local development and tests
+
+Leave the lists (`protected`, `public`, `deny`) unset: nothing is enforced, so `localhost`, Postman and e2e tests work as usual. With a list set, loopback (`127.0.0.1`, `::1`) is still allowed unless `allowLoopback: false`. In e2e tests either leave the lists unset or set `protected` to a test IP and send requests from it (Fastify `app.inject({ remoteAddress })`; Express with `trust proxy` + `X-Forwarded-For`).
 
-const allowed = parseIpAllowlist(process.env.API_IP_ALLOWLIST);
-if (allowed) restrictRoutesToAllowlist(app.getHttpAdapter().getInstance(), allowed, "/api/docs");
-SwaggerModule.setup("api/docs", app, document);
+## Getting the real client IP (read this)
+
+The guard reads `request.ip` and **never** parses `X-Forwarded-For` itself. Behind a reverse proxy/load balancer, configure your framework's trust-proxy setting so `req.ip` is the real client:
+
+- **Express:** `app.set("trust proxy", 1)` (one proxy in front).
+- **Fastify:** `buildTrustProxy(...)` from `@idevconn/allowlist-guard/fastify` (see the Fastify example above). It trusts one hop. Hop 0 is the socket peer, so **if the app port is reachable directly, any client can forge `X-Forwarded-For` and pass the allowlist**. Either make the port reachable only via your proxy, or pass `trustedProxies` (the proxy's IP/CIDR) so a direct client's header is ignored.
+
+Make the proxy **overwrite** the header with the address it saw, not append to a client-supplied one. nginx:
+
+```nginx
+location /api/ {
+  proxy_pass http://127.0.0.1:3000;
+  proxy_set_header X-Forwarded-For $remote_addr;   # overwrite, do not use $proxy_add_x_forwarded_for
+}
 ```
 
-It matches on the resolved route (`routeOptions.url`), not the raw URL, so percent-encoded paths such as `/api/%64ocs` cannot slip past.
+Without any trust-proxy setting `req.ip` is the proxy's own address for every client. If that proxy runs on the **same host**, that address is loopback — which is allowed by default, so the allowlist would be wide open. Set `allowLoopback: false` in that setup (and keep trust-proxy configured). Behind a CDN (e.g. Cloudflare) the proxy chain has two hops; configure the trusted hop count/CIDRs of your CDN accordingly rather than trusting arbitrary headers.
+
+## Routes outside Nest (Swagger UI)
+
+Fastify-native routes never reach Nest guards; `restrictRoutesToAllowlist(instance, allowed, routePrefix, denied?)` (see the Fastify example) applies the same lists to them. Pass `null` as `allowed` to use only a denylist. It matches on the resolved route (`routeOptions.url`), not the raw URL, so percent-encoded paths such as `/api/%64ocs` cannot slip past.
 
 ## Limits
 
-An IP allowlist only helps when your legitimate clients have known IPs. It cannot tell a browser from Postman/Playwright on the same IP — use authentication, rate limiting and bot protection for open APIs.
+See the notice at the top: an IP allowlist is a network perimeter, not bot protection. It cannot tell a browser from Postman or Playwright on the same IP.
 
 ## License
 

package/dist/fastify.cjs

@@ -75,10 +75,11 @@ function buildTrustProxy(trustedProxies) {
   const matcher = parseIpAllowlist(trustedProxies, "trustedProxies");
   return (address, hop) => hop === 0 && (!matcher || matcher(address));
 }
-function restrictRoutesToAllowlist(instance, allowed, routePrefix) {
+function restrictRoutesToAllowlist(instance, allowed, routePrefix, denied = null) {
   instance.addHook("onRequest", (req, reply, done) => {
     const route = req.routeOptions?.url ?? "";
-    if (route.startsWith(routePrefix) && !allowed(req.ip)) {
+    const blocked = route.startsWith(routePrefix) && (denied?.(req.ip) || allowed && !allowed(req.ip));
+    if (blocked) {
       void reply.code(403).send({ statusCode: 403, message: "ip_not_allowed" });
       return;
     }

package/dist/fastify.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fastify/index.ts","../src/ip-matcher.ts"],"sourcesContent":["import type { FastifyInstance } from \"fastify\";\nimport { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n\n/**\n * Fastify `trustProxy` function equal to Express's `trust proxy = 1`: trusts\n * only hop 0 (the socket peer, i.e. your reverse proxy), so a client cannot\n * walk past it with extra X-Forwarded-For entries.\n *\n * Hop 0 is the socket peer itself: if the app port is reachable directly (not\n * only through the proxy), ANY client is hop 0 and can forge X-Forwarded-For,\n * defeating the allowlist. Pass `trustedProxies` (IPs/CIDRs of your proxy) to\n * trust hop 0 only when the peer is one of them; a direct client's header is\n * then ignored. Loopback is always included.\n */\nexport function buildTrustProxy(\n  trustedProxies?: string | readonly string[],\n): (address: string, hop: number) => boolean {\n  const matcher = parseIpAllowlist(trustedProxies, \"trustedProxies\");\n  return (address, hop) => hop === 0 && (!matcher || matcher(address));\n}\n\n/**\n * Restricts Fastify-native routes that live outside Nest's guard pipeline\n * (e.g. Swagger UI under `/api/docs`) with the same allowlist. Register BEFORE\n * those routes are added.\n *\n * Matches on the ROUTE Fastify resolved (`routeOptions.url`), not the raw\n * `req.url`: Fastify percent-decodes the path before routing, so `/api/%64ocs`\n * reaches the docs handler while `req.url.startsWith('/api/docs')` is false.\n */\nexport function restrictRoutesToAllowlist(\n  instance: FastifyInstance,\n  allowed: IpMatcher,\n  routePrefix: string,\n): void {\n  instance.addHook(\"onRequest\", (req, reply, done) => {\n    const route = req.routeOptions?.url ?? \"\";\n    if (route.startsWith(routePrefix) && !allowed(req.ip)) {\n      void reply.code(403).send({ statusCode: 403, message: \"ip_not_allowed\" });\n      return;\n    }\n    done();\n  });\n}\n\nexport { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n","import { BlockList, isIP } from \"node:net\";\n\nexport type IpMatcher = (ip: string | undefined) => boolean;\n\nexport interface ParseOptions {\n  /**\n   * Always allow loopback (`127.0.0.0/8`, `::1`) once a list is set. Default `true`\n   * (local dev, health probes). Set `false` when a reverse proxy runs on the SAME\n   * host and `req.ip` may fall back to its loopback address — otherwise a proxy\n   * without trust-proxy configured makes every client look like 127.0.0.1.\n   */\n  allowLoopback?: boolean;\n}\n\nconst LOOPBACK = [\"127.0.0.0/8\", \"::1\"] as const;\n\n/** `::ffff:1.2.3.4` (what a dual-stack socket reports for IPv4 peers) → `1.2.3.4`. */\nexport function normalizeIp(ip: string): string {\n  const mapped = /^::ffff:(\\d{1,3}(?:\\.\\d{1,3}){3})$/i.exec(ip);\n  return mapped?.[1] ?? ip;\n}\n\nfunction addEntry(list: BlockList, raw: string): void {\n  const [addr = \"\", prefix, ...rest] = raw.split(\"/\");\n  const family = isIP(addr);\n  // A zone id (`fe80::1%eth0`) is accepted by isIP but ignored by BlockList.check,\n  // so `::1%x` would match loopback — never allow one in a list or as a client IP.\n  if (!family || addr.includes(\"%\") || rest.length > 0) {\n    throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  }\n  const type = family === 4 ? \"ipv4\" : \"ipv6\";\n  if (prefix === undefined) {\n    list.addAddress(addr, type);\n    return;\n  }\n  const bits = Number(prefix);\n  const max = family === 4 ? 32 : 128;\n  if (!/^\\d+$/.test(prefix) || bits > max) throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  list.addSubnet(addr, bits, type);\n}\n\n/**\n * Builds a matcher from a comma-separated string or an array of IPs/CIDRs\n * (IPv4 + IPv6). Returns `null` when the list is unset/blank (= not enforced).\n * Loopback is part of an enforced list by default (see `allowLoopback`). Throws on a malformed entry — a typo must not silently turn\n * into \"everyone allowed\" or \"everyone blocked\". `label` names the option in\n * the error message.\n */\nexport function parseIpAllowlist(\n  value: string | readonly string[] | undefined,\n  label = \"allowlist\",\n  { allowLoopback = true }: ParseOptions = {},\n): IpMatcher | null {\n  const raw = typeof value === \"string\" ? value.split(\",\") : (value ?? []);\n  const entries = raw.map((s) => s.trim()).filter(Boolean);\n  if (entries.length === 0) return null;\n\n  const list = new BlockList();\n  for (const entry of [...(allowLoopback ? LOOPBACK : []), ...entries]) {\n    try {\n      addEntry(list, entry);\n    } catch (err) {\n      throw new Error(`${label}: ${(err as Error).message}`, { cause: err });\n    }\n  }\n  return (ip) => {\n    if (!ip || ip.includes(\"%\")) return false;\n    const addr = normalizeIp(ip);\n    const family = isIP(addr);\n    if (!family) return false;\n    return list.check(addr, family === 4 ? \"ipv4\" : \"ipv6\");\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,sBAAgC;AAchC,IAAM,WAAW,CAAC,eAAe,KAAK;AAG/B,SAAS,YAAY,IAAoB;AAC9C,QAAM,SAAS,sCAAsC,KAAK,EAAE;AAC5D,SAAO,SAAS,CAAC,KAAK;AACxB;AAEA,SAAS,SAAS,MAAiB,KAAmB;AACpD,QAAM,CAAC,OAAO,IAAI,QAAQ,GAAG,IAAI,IAAI,IAAI,MAAM,GAAG;AAClD,QAAM,aAAS,sBAAK,IAAI;AAGxB,MAAI,CAAC,UAAU,KAAK,SAAS,GAAG,KAAK,KAAK,SAAS,GAAG;AACpD,UAAM,IAAI,MAAM,oBAAoB,GAAG,GAAG;AAAA,EAC5C;AACA,QAAM,OAAO,WAAW,IAAI,SAAS;AACrC,MAAI,WAAW,QAAW;AACxB,SAAK,WAAW,MAAM,IAAI;AAC1B;AAAA,EACF;AACA,QAAM,OAAO,OAAO,MAAM;AAC1B,QAAM,MAAM,WAAW,IAAI,KAAK;AAChC,MAAI,CAAC,QAAQ,KAAK,MAAM,KAAK,OAAO,IAAK,OAAM,IAAI,MAAM,oBAAoB,GAAG,GAAG;AACnF,OAAK,UAAU,MAAM,MAAM,IAAI;AACjC;AASO,SAAS,iBACd,OACA,QAAQ,aACR,EAAE,gBAAgB,KAAK,IAAkB,CAAC,GACxB;AAClB,QAAM,MAAM,OAAO,UAAU,WAAW,MAAM,MAAM,GAAG,IAAK,SAAS,CAAC;AACtE,QAAM,UAAU,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,OAAO;AACvD,MAAI,QAAQ,WAAW,EAAG,QAAO;AAEjC,QAAM,OAAO,IAAI,0BAAU;AAC3B,aAAW,SAAS,CAAC,GAAI,gBAAgB,WAAW,CAAC,GAAI,GAAG,OAAO,GAAG;AACpE,QAAI;AACF,eAAS,MAAM,KAAK;AAAA,IACtB,SAAS,KAAK;AACZ,YAAM,IAAI,MAAM,GAAG,KAAK,KAAM,IAAc,OAAO,IAAI,EAAE,OAAO,IAAI,CAAC;AAAA,IACvE;AAAA,EACF;AACA,SAAO,CAAC,OAAO;AACb,QAAI,CAAC,MAAM,GAAG,SAAS,GAAG,EAAG,QAAO;AACpC,UAAM,OAAO,YAAY,EAAE;AAC3B,UAAM,aAAS,sBAAK,IAAI;AACxB,QAAI,CAAC,OAAQ,QAAO;AACpB,WAAO,KAAK,MAAM,MAAM,WAAW,IAAI,SAAS,MAAM;AAAA,EACxD;AACF;;;AD1DO,SAAS,gBACd,gBAC2C;AAC3C,QAAM,UAAU,iBAAiB,gBAAgB,gBAAgB;AACjE,SAAO,CAAC,SAAS,QAAQ,QAAQ,MAAM,CAAC,WAAW,QAAQ,OAAO;AACpE;AAWO,SAAS,0BACd,UACA,SACA,aACM;AACN,WAAS,QAAQ,aAAa,CAAC,KAAK,OAAO,SAAS;AAClD,UAAM,QAAQ,IAAI,cAAc,OAAO;AACvC,QAAI,MAAM,WAAW,WAAW,KAAK,CAAC,QAAQ,IAAI,EAAE,GAAG;AACrD,WAAK,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,YAAY,KAAK,SAAS,iBAAiB,CAAC;AACxE;AAAA,IACF;AACA,SAAK;AAAA,EACP,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/fastify/index.ts","../src/ip-matcher.ts"],"sourcesContent":["import { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n\n/**\n * Fastify `trustProxy` function equal to Express's `trust proxy = 1`: trusts\n * only hop 0 (the socket peer, i.e. your reverse proxy), so a client cannot\n * walk past it with extra X-Forwarded-For entries.\n *\n * Hop 0 is the socket peer itself: if the app port is reachable directly (not\n * only through the proxy), ANY client is hop 0 and can forge X-Forwarded-For,\n * defeating the allowlist. Pass `trustedProxies` (IPs/CIDRs of your proxy) to\n * trust hop 0 only when the peer is one of them; a direct client's header is\n * then ignored. Loopback is always included.\n */\nexport function buildTrustProxy(\n  trustedProxies?: string | readonly string[],\n): (address: string, hop: number) => boolean {\n  const matcher = parseIpAllowlist(trustedProxies, \"trustedProxies\");\n  return (address, hop) => hop === 0 && (!matcher || matcher(address));\n}\n\n/**\n * Structural slice of a Fastify instance — deliberately not `FastifyInstance`, so\n * it type-checks even when the app and `@nestjs/platform-fastify` resolve two\n * different copies of `fastify`.\n */\nexport interface FastifyHookHost {\n  addHook(\n    name: \"onRequest\",\n    hook: (\n      req: { ip: string; routeOptions?: { url?: string } },\n      reply: { code(statusCode: number): { send(payload: unknown): unknown } },\n      done: () => void,\n    ) => void,\n  ): unknown;\n}\n\n/**\n * Restricts Fastify-native routes that live outside Nest's guard pipeline\n * (e.g. Swagger UI under `/api/docs`) with the same allowlist. Register BEFORE\n * those routes are added.\n *\n * Matches on the ROUTE Fastify resolved (`routeOptions.url`), not the raw\n * `req.url`: Fastify percent-decodes the path before routing, so `/api/%64ocs`\n * reaches the docs handler while `req.url.startsWith('/api/docs')` is false.\n *\n * `allowed` rejects IPs not on it (pass `null` to skip); `denied` rejects IPs on it.\n */\nexport function restrictRoutesToAllowlist(\n  instance: FastifyHookHost,\n  allowed: IpMatcher | null,\n  routePrefix: string,\n  denied: IpMatcher | null = null,\n): void {\n  instance.addHook(\"onRequest\", (req, reply, done) => {\n    const route = req.routeOptions?.url ?? \"\";\n    const blocked = route.startsWith(routePrefix) && (denied?.(req.ip) || (allowed && !allowed(req.ip)));\n    if (blocked) {\n      void reply.code(403).send({ statusCode: 403, message: \"ip_not_allowed\" });\n      return;\n    }\n    done();\n  });\n}\n\nexport { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n","import { BlockList, isIP } from \"node:net\";\n\nexport type IpMatcher = (ip: string | undefined) => boolean;\n\nexport interface ParseOptions {\n  /**\n   * Always allow loopback (`127.0.0.0/8`, `::1`) once a list is set. Default `true`\n   * (local dev, health probes). Set `false` when a reverse proxy runs on the SAME\n   * host and `req.ip` may fall back to its loopback address — otherwise a proxy\n   * without trust-proxy configured makes every client look like 127.0.0.1.\n   */\n  allowLoopback?: boolean;\n}\n\nconst LOOPBACK = [\"127.0.0.0/8\", \"::1\"] as const;\n\n/** `::ffff:1.2.3.4` (what a dual-stack socket reports for IPv4 peers) → `1.2.3.4`. */\nexport function normalizeIp(ip: string): string {\n  const mapped = /^::ffff:(\\d{1,3}(?:\\.\\d{1,3}){3})$/i.exec(ip);\n  return mapped?.[1] ?? ip;\n}\n\nfunction addEntry(list: BlockList, raw: string): void {\n  const [addr = \"\", prefix, ...rest] = raw.split(\"/\");\n  const family = isIP(addr);\n  // A zone id (`fe80::1%eth0`) is accepted by isIP but ignored by BlockList.check,\n  // so `::1%x` would match loopback — never allow one in a list or as a client IP.\n  if (!family || addr.includes(\"%\") || rest.length > 0) {\n    throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  }\n  const type = family === 4 ? \"ipv4\" : \"ipv6\";\n  if (prefix === undefined) {\n    list.addAddress(addr, type);\n    return;\n  }\n  const bits = Number(prefix);\n  const max = family === 4 ? 32 : 128;\n  if (!/^\\d+$/.test(prefix) || bits > max) throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  list.addSubnet(addr, bits, type);\n}\n\n/**\n * Builds a matcher from a comma-separated string or an array of IPs/CIDRs\n * (IPv4 + IPv6). Returns `null` when the list is unset/blank (= not enforced).\n * Loopback is part of an enforced list by default (see `allowLoopback`). Throws on a malformed entry — a typo must not silently turn\n * into \"everyone allowed\" or \"everyone blocked\". `label` names the option in\n * the error message.\n */\nexport function parseIpAllowlist(\n  value: string | readonly string[] | undefined,\n  label = \"allowlist\",\n  { allowLoopback = true }: ParseOptions = {},\n): IpMatcher | null {\n  const raw = typeof value === \"string\" ? value.split(\",\") : (value ?? []);\n  const entries = raw.map((s) => s.trim()).filter(Boolean);\n  if (entries.length === 0) return null;\n\n  const list = new BlockList();\n  for (const entry of [...(allowLoopback ? LOOPBACK : []), ...entries]) {\n    try {\n      addEntry(list, entry);\n    } catch (err) {\n      throw new Error(`${label}: ${(err as Error).message}`, { cause: err });\n    }\n  }\n  return (ip) => {\n    if (!ip || ip.includes(\"%\")) return false;\n    const addr = normalizeIp(ip);\n    const family = isIP(addr);\n    if (!family) return false;\n    return list.check(addr, family === 4 ? \"ipv4\" : \"ipv6\");\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,sBAAgC;AAchC,IAAM,WAAW,CAAC,eAAe,KAAK;AAG/B,SAAS,YAAY,IAAoB;AAC9C,QAAM,SAAS,sCAAsC,KAAK,EAAE;AAC5D,SAAO,SAAS,CAAC,KAAK;AACxB;AAEA,SAAS,SAAS,MAAiB,KAAmB;AACpD,QAAM,CAAC,OAAO,IAAI,QAAQ,GAAG,IAAI,IAAI,IAAI,MAAM,GAAG;AAClD,QAAM,aAAS,sBAAK,IAAI;AAGxB,MAAI,CAAC,UAAU,KAAK,SAAS,GAAG,KAAK,KAAK,SAAS,GAAG;AACpD,UAAM,IAAI,MAAM,oBAAoB,GAAG,GAAG;AAAA,EAC5C;AACA,QAAM,OAAO,WAAW,IAAI,SAAS;AACrC,MAAI,WAAW,QAAW;AACxB,SAAK,WAAW,MAAM,IAAI;AAC1B;AAAA,EACF;AACA,QAAM,OAAO,OAAO,MAAM;AAC1B,QAAM,MAAM,WAAW,IAAI,KAAK;AAChC,MAAI,CAAC,QAAQ,KAAK,MAAM,KAAK,OAAO,IAAK,OAAM,IAAI,MAAM,oBAAoB,GAAG,GAAG;AACnF,OAAK,UAAU,MAAM,MAAM,IAAI;AACjC;AASO,SAAS,iBACd,OACA,QAAQ,aACR,EAAE,gBAAgB,KAAK,IAAkB,CAAC,GACxB;AAClB,QAAM,MAAM,OAAO,UAAU,WAAW,MAAM,MAAM,GAAG,IAAK,SAAS,CAAC;AACtE,QAAM,UAAU,IAAI,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,OAAO;AACvD,MAAI,QAAQ,WAAW,EAAG,QAAO;AAEjC,QAAM,OAAO,IAAI,0BAAU;AAC3B,aAAW,SAAS,CAAC,GAAI,gBAAgB,WAAW,CAAC,GAAI,GAAG,OAAO,GAAG;AACpE,QAAI;AACF,eAAS,MAAM,KAAK;AAAA,IACtB,SAAS,KAAK;AACZ,YAAM,IAAI,MAAM,GAAG,KAAK,KAAM,IAAc,OAAO,IAAI,EAAE,OAAO,IAAI,CAAC;AAAA,IACvE;AAAA,EACF;AACA,SAAO,CAAC,OAAO;AACb,QAAI,CAAC,MAAM,GAAG,SAAS,GAAG,EAAG,QAAO;AACpC,UAAM,OAAO,YAAY,EAAE;AAC3B,UAAM,aAAS,sBAAK,IAAI;AACxB,QAAI,CAAC,OAAQ,QAAO;AACpB,WAAO,KAAK,MAAM,MAAM,WAAW,IAAI,SAAS,MAAM;AAAA,EACxD;AACF;;;AD3DO,SAAS,gBACd,gBAC2C;AAC3C,QAAM,UAAU,iBAAiB,gBAAgB,gBAAgB;AACjE,SAAO,CAAC,SAAS,QAAQ,QAAQ,MAAM,CAAC,WAAW,QAAQ,OAAO;AACpE;AA6BO,SAAS,0BACd,UACA,SACA,aACA,SAA2B,MACrB;AACN,WAAS,QAAQ,aAAa,CAAC,KAAK,OAAO,SAAS;AAClD,UAAM,QAAQ,IAAI,cAAc,OAAO;AACvC,UAAM,UAAU,MAAM,WAAW,WAAW,MAAM,SAAS,IAAI,EAAE,KAAM,WAAW,CAAC,QAAQ,IAAI,EAAE;AACjG,QAAI,SAAS;AACX,WAAK,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,YAAY,KAAK,SAAS,iBAAiB,CAAC;AACxE;AAAA,IACF;AACA,SAAK;AAAA,EACP,CAAC;AACH;","names":[]}

package/dist/fastify.d.cts

@@ -1,4 +1,3 @@
-import { FastifyInstance } from 'fastify';
 import { I as IpMatcher } from './ip-matcher-D4MA1kIq.cjs';
 export { p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.cjs';
 
@@ -14,6 +13,23 @@ export { p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.cjs';
  * then ignored. Loopback is always included.
  */
 declare function buildTrustProxy(trustedProxies?: string | readonly string[]): (address: string, hop: number) => boolean;
+/**
+ * Structural slice of a Fastify instance — deliberately not `FastifyInstance`, so
+ * it type-checks even when the app and `@nestjs/platform-fastify` resolve two
+ * different copies of `fastify`.
+ */
+interface FastifyHookHost {
+    addHook(name: "onRequest", hook: (req: {
+        ip: string;
+        routeOptions?: {
+            url?: string;
+        };
+    }, reply: {
+        code(statusCode: number): {
+            send(payload: unknown): unknown;
+        };
+    }, done: () => void) => void): unknown;
+}
 /**
  * Restricts Fastify-native routes that live outside Nest's guard pipeline
  * (e.g. Swagger UI under `/api/docs`) with the same allowlist. Register BEFORE
@@ -22,7 +38,9 @@ declare function buildTrustProxy(trustedProxies?: string | readonly string[]): (
  * Matches on the ROUTE Fastify resolved (`routeOptions.url`), not the raw
  * `req.url`: Fastify percent-decodes the path before routing, so `/api/%64ocs`
  * reaches the docs handler while `req.url.startsWith('/api/docs')` is false.
+ *
+ * `allowed` rejects IPs not on it (pass `null` to skip); `denied` rejects IPs on it.
  */
-declare function restrictRoutesToAllowlist(instance: FastifyInstance, allowed: IpMatcher, routePrefix: string): void;
+declare function restrictRoutesToAllowlist(instance: FastifyHookHost, allowed: IpMatcher | null, routePrefix: string, denied?: IpMatcher | null): void;
 
-export { IpMatcher, buildTrustProxy, restrictRoutesToAllowlist };
+export { type FastifyHookHost, IpMatcher, buildTrustProxy, restrictRoutesToAllowlist };

package/dist/fastify.d.ts

@@ -1,4 +1,3 @@
-import { FastifyInstance } from 'fastify';
 import { I as IpMatcher } from './ip-matcher-D4MA1kIq.js';
 export { p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.js';
 
@@ -14,6 +13,23 @@ export { p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.js';
  * then ignored. Loopback is always included.
  */
 declare function buildTrustProxy(trustedProxies?: string | readonly string[]): (address: string, hop: number) => boolean;
+/**
+ * Structural slice of a Fastify instance — deliberately not `FastifyInstance`, so
+ * it type-checks even when the app and `@nestjs/platform-fastify` resolve two
+ * different copies of `fastify`.
+ */
+interface FastifyHookHost {
+    addHook(name: "onRequest", hook: (req: {
+        ip: string;
+        routeOptions?: {
+            url?: string;
+        };
+    }, reply: {
+        code(statusCode: number): {
+            send(payload: unknown): unknown;
+        };
+    }, done: () => void) => void): unknown;
+}
 /**
  * Restricts Fastify-native routes that live outside Nest's guard pipeline
  * (e.g. Swagger UI under `/api/docs`) with the same allowlist. Register BEFORE
@@ -22,7 +38,9 @@ declare function buildTrustProxy(trustedProxies?: string | readonly string[]): (
  * Matches on the ROUTE Fastify resolved (`routeOptions.url`), not the raw
  * `req.url`: Fastify percent-decodes the path before routing, so `/api/%64ocs`
  * reaches the docs handler while `req.url.startsWith('/api/docs')` is false.
+ *
+ * `allowed` rejects IPs not on it (pass `null` to skip); `denied` rejects IPs on it.
  */
-declare function restrictRoutesToAllowlist(instance: FastifyInstance, allowed: IpMatcher, routePrefix: string): void;
+declare function restrictRoutesToAllowlist(instance: FastifyHookHost, allowed: IpMatcher | null, routePrefix: string, denied?: IpMatcher | null): void;
 
-export { IpMatcher, buildTrustProxy, restrictRoutesToAllowlist };
+export { type FastifyHookHost, IpMatcher, buildTrustProxy, restrictRoutesToAllowlist };

package/dist/fastify.js

@@ -7,10 +7,11 @@ function buildTrustProxy(trustedProxies) {
   const matcher = parseIpAllowlist(trustedProxies, "trustedProxies");
   return (address, hop) => hop === 0 && (!matcher || matcher(address));
 }
-function restrictRoutesToAllowlist(instance, allowed, routePrefix) {
+function restrictRoutesToAllowlist(instance, allowed, routePrefix, denied = null) {
   instance.addHook("onRequest", (req, reply, done) => {
     const route = req.routeOptions?.url ?? "";
-    if (route.startsWith(routePrefix) && !allowed(req.ip)) {
+    const blocked = route.startsWith(routePrefix) && (denied?.(req.ip) || allowed && !allowed(req.ip));
+    if (blocked) {
       void reply.code(403).send({ statusCode: 403, message: "ip_not_allowed" });
       return;
     }

package/dist/fastify.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fastify/index.ts"],"sourcesContent":["import type { FastifyInstance } from \"fastify\";\nimport { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n\n/**\n * Fastify `trustProxy` function equal to Express's `trust proxy = 1`: trusts\n * only hop 0 (the socket peer, i.e. your reverse proxy), so a client cannot\n * walk past it with extra X-Forwarded-For entries.\n *\n * Hop 0 is the socket peer itself: if the app port is reachable directly (not\n * only through the proxy), ANY client is hop 0 and can forge X-Forwarded-For,\n * defeating the allowlist. Pass `trustedProxies` (IPs/CIDRs of your proxy) to\n * trust hop 0 only when the peer is one of them; a direct client's header is\n * then ignored. Loopback is always included.\n */\nexport function buildTrustProxy(\n  trustedProxies?: string | readonly string[],\n): (address: string, hop: number) => boolean {\n  const matcher = parseIpAllowlist(trustedProxies, \"trustedProxies\");\n  return (address, hop) => hop === 0 && (!matcher || matcher(address));\n}\n\n/**\n * Restricts Fastify-native routes that live outside Nest's guard pipeline\n * (e.g. Swagger UI under `/api/docs`) with the same allowlist. Register BEFORE\n * those routes are added.\n *\n * Matches on the ROUTE Fastify resolved (`routeOptions.url`), not the raw\n * `req.url`: Fastify percent-decodes the path before routing, so `/api/%64ocs`\n * reaches the docs handler while `req.url.startsWith('/api/docs')` is false.\n */\nexport function restrictRoutesToAllowlist(\n  instance: FastifyInstance,\n  allowed: IpMatcher,\n  routePrefix: string,\n): void {\n  instance.addHook(\"onRequest\", (req, reply, done) => {\n    const route = req.routeOptions?.url ?? \"\";\n    if (route.startsWith(routePrefix) && !allowed(req.ip)) {\n      void reply.code(403).send({ statusCode: 403, message: \"ip_not_allowed\" });\n      return;\n    }\n    done();\n  });\n}\n\nexport { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n"],"mappings":";;;;;AAcO,SAAS,gBACd,gBAC2C;AAC3C,QAAM,UAAU,iBAAiB,gBAAgB,gBAAgB;AACjE,SAAO,CAAC,SAAS,QAAQ,QAAQ,MAAM,CAAC,WAAW,QAAQ,OAAO;AACpE;AAWO,SAAS,0BACd,UACA,SACA,aACM;AACN,WAAS,QAAQ,aAAa,CAAC,KAAK,OAAO,SAAS;AAClD,UAAM,QAAQ,IAAI,cAAc,OAAO;AACvC,QAAI,MAAM,WAAW,WAAW,KAAK,CAAC,QAAQ,IAAI,EAAE,GAAG;AACrD,WAAK,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,YAAY,KAAK,SAAS,iBAAiB,CAAC;AACxE;AAAA,IACF;AACA,SAAK;AAAA,EACP,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/fastify/index.ts"],"sourcesContent":["import { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n\n/**\n * Fastify `trustProxy` function equal to Express's `trust proxy = 1`: trusts\n * only hop 0 (the socket peer, i.e. your reverse proxy), so a client cannot\n * walk past it with extra X-Forwarded-For entries.\n *\n * Hop 0 is the socket peer itself: if the app port is reachable directly (not\n * only through the proxy), ANY client is hop 0 and can forge X-Forwarded-For,\n * defeating the allowlist. Pass `trustedProxies` (IPs/CIDRs of your proxy) to\n * trust hop 0 only when the peer is one of them; a direct client's header is\n * then ignored. Loopback is always included.\n */\nexport function buildTrustProxy(\n  trustedProxies?: string | readonly string[],\n): (address: string, hop: number) => boolean {\n  const matcher = parseIpAllowlist(trustedProxies, \"trustedProxies\");\n  return (address, hop) => hop === 0 && (!matcher || matcher(address));\n}\n\n/**\n * Structural slice of a Fastify instance — deliberately not `FastifyInstance`, so\n * it type-checks even when the app and `@nestjs/platform-fastify` resolve two\n * different copies of `fastify`.\n */\nexport interface FastifyHookHost {\n  addHook(\n    name: \"onRequest\",\n    hook: (\n      req: { ip: string; routeOptions?: { url?: string } },\n      reply: { code(statusCode: number): { send(payload: unknown): unknown } },\n      done: () => void,\n    ) => void,\n  ): unknown;\n}\n\n/**\n * Restricts Fastify-native routes that live outside Nest's guard pipeline\n * (e.g. Swagger UI under `/api/docs`) with the same allowlist. Register BEFORE\n * those routes are added.\n *\n * Matches on the ROUTE Fastify resolved (`routeOptions.url`), not the raw\n * `req.url`: Fastify percent-decodes the path before routing, so `/api/%64ocs`\n * reaches the docs handler while `req.url.startsWith('/api/docs')` is false.\n *\n * `allowed` rejects IPs not on it (pass `null` to skip); `denied` rejects IPs on it.\n */\nexport function restrictRoutesToAllowlist(\n  instance: FastifyHookHost,\n  allowed: IpMatcher | null,\n  routePrefix: string,\n  denied: IpMatcher | null = null,\n): void {\n  instance.addHook(\"onRequest\", (req, reply, done) => {\n    const route = req.routeOptions?.url ?? \"\";\n    const blocked = route.startsWith(routePrefix) && (denied?.(req.ip) || (allowed && !allowed(req.ip)));\n    if (blocked) {\n      void reply.code(403).send({ statusCode: 403, message: \"ip_not_allowed\" });\n      return;\n    }\n    done();\n  });\n}\n\nexport { parseIpAllowlist, type IpMatcher } from \"../ip-matcher.js\";\n"],"mappings":";;;;;AAaO,SAAS,gBACd,gBAC2C;AAC3C,QAAM,UAAU,iBAAiB,gBAAgB,gBAAgB;AACjE,SAAO,CAAC,SAAS,QAAQ,QAAQ,MAAM,CAAC,WAAW,QAAQ,OAAO;AACpE;AA6BO,SAAS,0BACd,UACA,SACA,aACA,SAA2B,MACrB;AACN,WAAS,QAAQ,aAAa,CAAC,KAAK,OAAO,SAAS;AAClD,UAAM,QAAQ,IAAI,cAAc,OAAO;AACvC,UAAM,UAAU,MAAM,WAAW,WAAW,MAAM,SAAS,IAAI,EAAE,KAAM,WAAW,CAAC,QAAQ,IAAI,EAAE;AACjG,QAAI,SAAS;AACX,WAAK,MAAM,KAAK,GAAG,EAAE,KAAK,EAAE,YAAY,KAAK,SAAS,iBAAiB,CAAC;AACxE;AAAA,IACF;AACA,SAAK;AAAA,EACP,CAAC;AACH;","names":[]}

package/dist/index.cjs

@@ -110,6 +110,7 @@ var IpAllowlistGuard = class {
     const parse = { allowLoopback: options.allowLoopback ?? true };
     this.protectedMatcher = parseIpAllowlist(options.protected, "protected", parse);
     this.publicMatcher = parseIpAllowlist(options.public, "public", parse);
+    this.denyMatcher = parseIpAllowlist(options.deny, "deny", { allowLoopback: false });
     this.publicKey = options.publicMetadataKey ?? "isPublic";
   }
   reflector;
@@ -117,36 +118,45 @@ var IpAllowlistGuard = class {
   logger = new import_common2.Logger(IpAllowlistGuard.name);
   protectedMatcher;
   publicMatcher;
+  denyMatcher;
   publicKey;
   lastLogged = /* @__PURE__ */ new Map();
   canActivate(ctx) {
     const type = ctx.getType();
     if (type === "rpc") return true;
+    if (!this.protectedMatcher && !this.publicMatcher && !this.denyMatcher) return true;
+    const ip = type === "http" ? ctx.switchToHttp().getRequest().ip : void 0;
+    if (this.denyMatcher?.(ip)) return this.reject(ip, "denied");
     if (!this.protectedMatcher && !this.publicMatcher) return true;
     const targets = [ctx.getHandler(), ctx.getClass()];
     if (this.reflector.getAllAndOverride(SKIP_IP_ALLOWLIST_KEY, targets)) return true;
     const isPublic = this.reflector.getAllAndOverride(this.publicKey, targets);
     const matcher = isPublic ? this.publicMatcher : this.protectedMatcher;
     if (!matcher) return true;
-    const ip = type === "http" ? ctx.switchToHttp().getRequest().ip : void 0;
     if (matcher(ip)) return true;
-    this.notifyBlocked(ip);
+    return this.reject(ip, "not_allowed");
+  }
+  reject(ip, reason) {
+    this.notifyBlocked(ip, reason);
     throw new import_common2.ForbiddenException("ip_not_allowed");
   }
-  notifyBlocked(ip) {
-    this.options.onBlocked?.(ip);
+  notifyBlocked(ip, reason) {
+    this.options.onBlocked?.(ip, reason);
     const key = ip && (0, import_node_net2.isIP)(ip) ? ip : "invalid";
+    const logKey = `${reason}:${key}`;
     const now = Date.now();
-    const last = this.lastLogged.get(key);
+    const last = this.lastLogged.get(logKey);
     if (last !== void 0 && now - last < LOG_INTERVAL_MS) return;
-    this.lastLogged.delete(key);
-    this.lastLogged.set(key, now);
+    this.lastLogged.delete(logKey);
+    this.lastLogged.set(logKey, now);
     if (this.lastLogged.size > MAX_TRACKED_IPS) {
       const oldest = this.lastLogged.keys().next().value;
       if (oldest !== void 0) this.lastLogged.delete(oldest);
     }
     if (!this.options.onBlocked) {
-      this.logger.warn(`Blocked request from non-allowlisted IP ${key}`);
+      this.logger.warn(
+        reason === "denied" ? `Blocked request from denylisted IP ${key}` : `Blocked request from non-allowlisted IP ${key}`
+      );
     }
   }
 };

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/ip-allowlist.module.ts","../src/ip-allowlist.guard.ts","../src/options.ts","../src/ip-matcher.ts","../src/skip-ip-allowlist.decorator.ts"],"sourcesContent":["export { IpAllowlistModule } from \"./ip-allowlist.module.js\";\nexport { IpAllowlistGuard } from \"./ip-allowlist.guard.js\";\nexport { SkipIpAllowlist, SKIP_IP_ALLOWLIST_KEY } from \"./skip-ip-allowlist.decorator.js\";\nexport { IP_ALLOWLIST_OPTIONS, type IpAllowlistOptions } from \"./options.js\";\nexport { parseIpAllowlist, normalizeIp, type IpMatcher } from \"./ip-matcher.js\";\n","import { Module, type DynamicModule } from \"@nestjs/common\";\nimport { APP_GUARD } from \"@nestjs/core\";\nimport { IpAllowlistGuard } from \"./ip-allowlist.guard.js\";\nimport { IP_ALLOWLIST_OPTIONS, type IpAllowlistOptions } from \"./options.js\";\n\n@Module({})\nexport class IpAllowlistModule {\n  /**\n   * Registers the guard globally (APP_GUARD). Import this module BEFORE the\n   * module that registers your auth guard so a blocked IP is rejected before\n   * any authentication work.\n   */\n  static forRoot(options: IpAllowlistOptions = {}): DynamicModule {\n    return {\n      module: IpAllowlistModule,\n      providers: [\n        { provide: IP_ALLOWLIST_OPTIONS, useValue: options },\n        { provide: APP_GUARD, useClass: IpAllowlistGuard },\n      ],\n    };\n  }\n}\n","import {\n  ForbiddenException,\n  Inject,\n  Injectable,\n  Logger,\n  type CanActivate,\n  type ExecutionContext,\n} from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\nimport { isIP } from \"node:net\";\nimport { IP_ALLOWLIST_OPTIONS, type IpAllowlistOptions } from \"./options.js\";\nimport { parseIpAllowlist, type IpMatcher } from \"./ip-matcher.js\";\nimport { SKIP_IP_ALLOWLIST_KEY } from \"./skip-ip-allowlist.decorator.js\";\n\n// Default log line is rate-limited per IP; the map is bounded by evicting the OLDEST\n// entry, so rotating through many IPs can never switch logging off.\nconst LOG_INTERVAL_MS = 60_000;\nconst MAX_TRACKED_IPS = 1000;\n\n/**\n * Restricts routes by source IP. Reads `request.ip`, which Express/Fastify\n * resolve through their own `trust proxy` setting — configure it so `req.ip`\n * is the real client behind your proxy (see `buildTrustProxy` in the\n * `/fastify` entry). `X-Forwarded-For` is never read here.\n */\n@Injectable()\nexport class IpAllowlistGuard implements CanActivate {\n  private readonly logger = new Logger(IpAllowlistGuard.name);\n  private readonly protectedMatcher: IpMatcher | null;\n  private readonly publicMatcher: IpMatcher | null;\n  private readonly publicKey: string;\n  private readonly lastLogged = new Map<string, number>();\n\n  constructor(\n    @Inject(Reflector) private readonly reflector: Reflector,\n    @Inject(IP_ALLOWLIST_OPTIONS) private readonly options: IpAllowlistOptions,\n  ) {\n    const parse = { allowLoopback: options.allowLoopback ?? true };\n    this.protectedMatcher = parseIpAllowlist(options.protected, \"protected\", parse);\n    this.publicMatcher = parseIpAllowlist(options.public, \"public\", parse);\n    this.publicKey = options.publicMetadataKey ?? \"isPublic\";\n  }\n\n  canActivate(ctx: ExecutionContext): boolean {\n    // Only microservice (RPC) traffic is exempt: it has no client IP and is internal\n    // transport. Any other context type (graphql, ws, ...) is NOT skipped — it has no\n    // resolvable `req.ip` here, so it is denied when a list is enforced (fail closed).\n    const type = ctx.getType<string>();\n    if (type === \"rpc\") return true;\n    if (!this.protectedMatcher && !this.publicMatcher) return true;\n\n    const targets = [ctx.getHandler(), ctx.getClass()];\n    if (this.reflector.getAllAndOverride<boolean>(SKIP_IP_ALLOWLIST_KEY, targets)) return true;\n\n    const isPublic = this.reflector.getAllAndOverride<boolean>(this.publicKey, targets);\n    const matcher = isPublic ? this.publicMatcher : this.protectedMatcher;\n    if (!matcher) return true;\n\n    const ip = type === \"http\" ? ctx.switchToHttp().getRequest<{ ip?: string }>().ip : undefined;\n    if (matcher(ip)) return true;\n\n    this.notifyBlocked(ip);\n    throw new ForbiddenException(\"ip_not_allowed\");\n  }\n\n  private notifyBlocked(ip: string | undefined): void {\n    this.options.onBlocked?.(ip);\n\n    // Never log attacker-controlled text: only a well-formed IP is echoed.\n    const key = ip && isIP(ip) ? ip : \"invalid\";\n    const now = Date.now();\n    const last = this.lastLogged.get(key);\n    if (last !== undefined && now - last < LOG_INTERVAL_MS) return;\n    this.lastLogged.delete(key);\n    this.lastLogged.set(key, now);\n    if (this.lastLogged.size > MAX_TRACKED_IPS) {\n      const oldest = this.lastLogged.keys().next().value;\n      if (oldest !== undefined) this.lastLogged.delete(oldest);\n    }\n    if (!this.options.onBlocked) {\n      this.logger.warn(`Blocked request from non-allowlisted IP ${key}`);\n    }\n  }\n}\n","export const IP_ALLOWLIST_OPTIONS = Symbol(\"IP_ALLOWLIST_OPTIONS\");\n\nexport interface IpAllowlistOptions {\n  /**\n   * Allowlist for protected (non-public) routes: comma-separated string or\n   * array of IPs/CIDRs. Unset/blank = not enforced.\n   */\n  protected?: string | readonly string[];\n  /**\n   * Allowlist for public (\"open\") routes, i.e. routes carrying the metadata key\n   * below. Unset/blank = not enforced.\n   */\n  public?: string | readonly string[];\n  /**\n   * Metadata key that marks a route as public. Defaults to `'isPublic'`, the\n   * key used by the common `@Public()` decorator (`SetMetadata('isPublic', true)`).\n   */\n  publicMetadataKey?: string;\n  /**\n   * Always allow loopback once a list is set. Default `true`. Set `false` if a\n   * reverse proxy runs on the same host and `req.ip` could be its loopback address.\n   */\n  allowLoopback?: boolean;\n  /**\n   * Called on EVERY blocked request (feed your metrics/alerting from here).\n   * The default Nest Logger warning is rate-limited per IP; this hook is not.\n   */\n  onBlocked?: (ip: string | undefined) => void;\n}\n","import { BlockList, isIP } from \"node:net\";\n\nexport type IpMatcher = (ip: string | undefined) => boolean;\n\nexport interface ParseOptions {\n  /**\n   * Always allow loopback (`127.0.0.0/8`, `::1`) once a list is set. Default `true`\n   * (local dev, health probes). Set `false` when a reverse proxy runs on the SAME\n   * host and `req.ip` may fall back to its loopback address — otherwise a proxy\n   * without trust-proxy configured makes every client look like 127.0.0.1.\n   */\n  allowLoopback?: boolean;\n}\n\nconst LOOPBACK = [\"127.0.0.0/8\", \"::1\"] as const;\n\n/** `::ffff:1.2.3.4` (what a dual-stack socket reports for IPv4 peers) → `1.2.3.4`. */\nexport function normalizeIp(ip: string): string {\n  const mapped = /^::ffff:(\\d{1,3}(?:\\.\\d{1,3}){3})$/i.exec(ip);\n  return mapped?.[1] ?? ip;\n}\n\nfunction addEntry(list: BlockList, raw: string): void {\n  const [addr = \"\", prefix, ...rest] = raw.split(\"/\");\n  const family = isIP(addr);\n  // A zone id (`fe80::1%eth0`) is accepted by isIP but ignored by BlockList.check,\n  // so `::1%x` would match loopback — never allow one in a list or as a client IP.\n  if (!family || addr.includes(\"%\") || rest.length > 0) {\n    throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  }\n  const type = family === 4 ? \"ipv4\" : \"ipv6\";\n  if (prefix === undefined) {\n    list.addAddress(addr, type);\n    return;\n  }\n  const bits = Number(prefix);\n  const max = family === 4 ? 32 : 128;\n  if (!/^\\d+$/.test(prefix) || bits > max) throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  list.addSubnet(addr, bits, type);\n}\n\n/**\n * Builds a matcher from a comma-separated string or an array of IPs/CIDRs\n * (IPv4 + IPv6). Returns `null` when the list is unset/blank (= not enforced).\n * Loopback is part of an enforced list by default (see `allowLoopback`). Throws on a malformed entry — a typo must not silently turn\n * into \"everyone allowed\" or \"everyone blocked\". `label` names the option in\n * the error message.\n */\nexport function parseIpAllowlist(\n  value: string | readonly string[] | undefined,\n  label = \"allowlist\",\n  { allowLoopback = true }: ParseOptions = {},\n): IpMatcher | null {\n  const raw = typeof value === \"string\" ? value.split(\",\") : (value ?? []);\n  const entries = raw.map((s) => s.trim()).filter(Boolean);\n  if (entries.length === 0) return null;\n\n  const list = new BlockList();\n  for (const entry of [...(allowLoopback ? LOOPBACK : []), ...entries]) {\n    try {\n      addEntry(list, entry);\n    } catch (err) {\n      throw new Error(`${label}: ${(err as Error).message}`, { cause: err });\n    }\n  }\n  return (ip) => {\n    if (!ip || ip.includes(\"%\")) return false;\n    const addr = normalizeIp(ip);\n    const family = isIP(addr);\n    if (!family) return false;\n    return list.check(addr, family === 4 ? \"ipv4\" : \"ipv6\");\n  };\n}\n","import { SetMetadata } from \"@nestjs/common\";\n\nexport const SKIP_IP_ALLOWLIST_KEY = \"skipIpAllowlist\";\n\n/**\n * Exempts a route (or controller) from the guard. For callers whose IPs cannot\n * be pinned down and that authenticate by other means (e.g. provider webhooks\n * verified by an HMAC signature).\n */\nexport const SkipIpAllowlist = (): MethodDecorator & ClassDecorator =>\n  SetMetadata(SKIP_IP_ALLOWLIST_KEY, true);\n"],"mappings":"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","names":["import_common","import_core","import_common","import_node_net"]}
+{"version":3,"sources":["../src/index.ts","../src/ip-allowlist.module.ts","../src/ip-allowlist.guard.ts","../src/options.ts","../src/ip-matcher.ts","../src/skip-ip-allowlist.decorator.ts"],"sourcesContent":["export { IpAllowlistModule } from \"./ip-allowlist.module.js\";\nexport { IpAllowlistGuard } from \"./ip-allowlist.guard.js\";\nexport { SkipIpAllowlist, SKIP_IP_ALLOWLIST_KEY } from \"./skip-ip-allowlist.decorator.js\";\nexport { IP_ALLOWLIST_OPTIONS, type BlockReason, type IpAllowlistOptions } from \"./options.js\";\nexport { parseIpAllowlist, normalizeIp, type IpMatcher } from \"./ip-matcher.js\";\n","import { Module, type DynamicModule } from \"@nestjs/common\";\nimport { APP_GUARD } from \"@nestjs/core\";\nimport { IpAllowlistGuard } from \"./ip-allowlist.guard.js\";\nimport { IP_ALLOWLIST_OPTIONS, type IpAllowlistOptions } from \"./options.js\";\n\n@Module({})\nexport class IpAllowlistModule {\n  /**\n   * Registers the guard globally (APP_GUARD). Import this module BEFORE the\n   * module that registers your auth guard so a blocked IP is rejected before\n   * any authentication work.\n   */\n  static forRoot(options: IpAllowlistOptions = {}): DynamicModule {\n    return {\n      module: IpAllowlistModule,\n      providers: [\n        { provide: IP_ALLOWLIST_OPTIONS, useValue: options },\n        { provide: APP_GUARD, useClass: IpAllowlistGuard },\n      ],\n    };\n  }\n}\n","import {\n  ForbiddenException,\n  Inject,\n  Injectable,\n  Logger,\n  type CanActivate,\n  type ExecutionContext,\n} from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\nimport { isIP } from \"node:net\";\nimport { IP_ALLOWLIST_OPTIONS, type BlockReason, type IpAllowlistOptions } from \"./options.js\";\nimport { parseIpAllowlist, type IpMatcher } from \"./ip-matcher.js\";\nimport { SKIP_IP_ALLOWLIST_KEY } from \"./skip-ip-allowlist.decorator.js\";\n\n// Default log line is rate-limited per IP; the map is bounded by evicting the OLDEST\n// entry, so rotating through many IPs can never switch logging off.\nconst LOG_INTERVAL_MS = 60_000;\nconst MAX_TRACKED_IPS = 1000;\n\n/**\n * Restricts routes by source IP. Reads `request.ip`, which Express/Fastify\n * resolve through their own `trust proxy` setting — configure it so `req.ip`\n * is the real client behind your proxy (see `buildTrustProxy` in the\n * `/fastify` entry). `X-Forwarded-For` is never read here.\n */\n@Injectable()\nexport class IpAllowlistGuard implements CanActivate {\n  private readonly logger = new Logger(IpAllowlistGuard.name);\n  private readonly protectedMatcher: IpMatcher | null;\n  private readonly publicMatcher: IpMatcher | null;\n  private readonly denyMatcher: IpMatcher | null;\n  private readonly publicKey: string;\n  private readonly lastLogged = new Map<string, number>();\n\n  constructor(\n    @Inject(Reflector) private readonly reflector: Reflector,\n    @Inject(IP_ALLOWLIST_OPTIONS) private readonly options: IpAllowlistOptions,\n  ) {\n    const parse = { allowLoopback: options.allowLoopback ?? true };\n    this.protectedMatcher = parseIpAllowlist(options.protected, \"protected\", parse);\n    this.publicMatcher = parseIpAllowlist(options.public, \"public\", parse);\n    // The denylist never adds loopback implicitly: only what the operator lists.\n    this.denyMatcher = parseIpAllowlist(options.deny, \"deny\", { allowLoopback: false });\n    this.publicKey = options.publicMetadataKey ?? \"isPublic\";\n  }\n\n  canActivate(ctx: ExecutionContext): boolean {\n    // Only microservice (RPC) traffic is exempt: it has no client IP and is internal\n    // transport. Any other context type (graphql, ws, ...) is NOT skipped — it has no\n    // resolvable `req.ip` here, so it is denied when an allowlist is enforced (fail closed).\n    const type = ctx.getType<string>();\n    if (type === \"rpc\") return true;\n    if (!this.protectedMatcher && !this.publicMatcher && !this.denyMatcher) return true;\n\n    const ip = type === \"http\" ? ctx.switchToHttp().getRequest<{ ip?: string }>().ip : undefined;\n\n    // Denylist first, on every route (including @SkipIpAllowlist ones): it wins over any allow.\n    if (this.denyMatcher?.(ip)) return this.reject(ip, \"denied\");\n\n    if (!this.protectedMatcher && !this.publicMatcher) return true;\n    const targets = [ctx.getHandler(), ctx.getClass()];\n    if (this.reflector.getAllAndOverride<boolean>(SKIP_IP_ALLOWLIST_KEY, targets)) return true;\n\n    const isPublic = this.reflector.getAllAndOverride<boolean>(this.publicKey, targets);\n    const matcher = isPublic ? this.publicMatcher : this.protectedMatcher;\n    if (!matcher) return true;\n    if (matcher(ip)) return true;\n\n    return this.reject(ip, \"not_allowed\");\n  }\n\n  private reject(ip: string | undefined, reason: BlockReason): never {\n    this.notifyBlocked(ip, reason);\n    throw new ForbiddenException(\"ip_not_allowed\");\n  }\n\n  private notifyBlocked(ip: string | undefined, reason: BlockReason): void {\n    this.options.onBlocked?.(ip, reason);\n\n    // Never log attacker-controlled text: only a well-formed IP is echoed.\n    const key = ip && isIP(ip) ? ip : \"invalid\";\n    const logKey = `${reason}:${key}`;\n    const now = Date.now();\n    const last = this.lastLogged.get(logKey);\n    if (last !== undefined && now - last < LOG_INTERVAL_MS) return;\n    this.lastLogged.delete(logKey);\n    this.lastLogged.set(logKey, now);\n    if (this.lastLogged.size > MAX_TRACKED_IPS) {\n      const oldest = this.lastLogged.keys().next().value;\n      if (oldest !== undefined) this.lastLogged.delete(oldest);\n    }\n    if (!this.options.onBlocked) {\n      this.logger.warn(\n        reason === \"denied\"\n          ? `Blocked request from denylisted IP ${key}`\n          : `Blocked request from non-allowlisted IP ${key}`,\n      );\n    }\n  }\n}\n","export const IP_ALLOWLIST_OPTIONS = Symbol(\"IP_ALLOWLIST_OPTIONS\");\n\n/** Why a request was rejected: on the denylist, or not on the applicable allowlist. */\nexport type BlockReason = \"denied\" | \"not_allowed\";\n\nexport interface IpAllowlistOptions {\n  /**\n   * Allowlist for protected (non-public) routes: comma-separated string or\n   * array of IPs/CIDRs. Unset/blank = not enforced.\n   */\n  protected?: string | readonly string[];\n  /**\n   * Allowlist for public (\"open\") routes, i.e. routes carrying the metadata key\n   * below. Unset/blank = not enforced.\n   */\n  public?: string | readonly string[];\n  /**\n   * Denylist applied to EVERY route (protected and public): comma-separated string\n   * or array of IPs/CIDRs that are always rejected. Takes precedence over the\n   * allowlists, and — unlike them — also applies to `@SkipIpAllowlist()` routes\n   * (a banned address is banned everywhere). Works alone (\"everyone except these\")\n   * or together with the allowlists. Loopback is never denied implicitly.\n   * Unset/blank = nothing denied.\n   */\n  deny?: string | readonly string[];\n  /**\n   * Metadata key that marks a route as public. Defaults to `'isPublic'`, the\n   * key used by the common `@Public()` decorator (`SetMetadata('isPublic', true)`).\n   */\n  publicMetadataKey?: string;\n  /**\n   * Always allow loopback once a list is set. Default `true`. Set `false` if a\n   * reverse proxy runs on the same host and `req.ip` could be its loopback address.\n   */\n  allowLoopback?: boolean;\n  /**\n   * Called on EVERY blocked request (feed your metrics/alerting from here).\n   * The default Nest Logger warning is rate-limited per IP; this hook is not.\n   */\n  onBlocked?: (ip: string | undefined, reason: BlockReason) => void;\n}\n","import { BlockList, isIP } from \"node:net\";\n\nexport type IpMatcher = (ip: string | undefined) => boolean;\n\nexport interface ParseOptions {\n  /**\n   * Always allow loopback (`127.0.0.0/8`, `::1`) once a list is set. Default `true`\n   * (local dev, health probes). Set `false` when a reverse proxy runs on the SAME\n   * host and `req.ip` may fall back to its loopback address — otherwise a proxy\n   * without trust-proxy configured makes every client look like 127.0.0.1.\n   */\n  allowLoopback?: boolean;\n}\n\nconst LOOPBACK = [\"127.0.0.0/8\", \"::1\"] as const;\n\n/** `::ffff:1.2.3.4` (what a dual-stack socket reports for IPv4 peers) → `1.2.3.4`. */\nexport function normalizeIp(ip: string): string {\n  const mapped = /^::ffff:(\\d{1,3}(?:\\.\\d{1,3}){3})$/i.exec(ip);\n  return mapped?.[1] ?? ip;\n}\n\nfunction addEntry(list: BlockList, raw: string): void {\n  const [addr = \"\", prefix, ...rest] = raw.split(\"/\");\n  const family = isIP(addr);\n  // A zone id (`fe80::1%eth0`) is accepted by isIP but ignored by BlockList.check,\n  // so `::1%x` would match loopback — never allow one in a list or as a client IP.\n  if (!family || addr.includes(\"%\") || rest.length > 0) {\n    throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  }\n  const type = family === 4 ? \"ipv4\" : \"ipv6\";\n  if (prefix === undefined) {\n    list.addAddress(addr, type);\n    return;\n  }\n  const bits = Number(prefix);\n  const max = family === 4 ? 32 : 128;\n  if (!/^\\d+$/.test(prefix) || bits > max) throw new Error(`invalid IP/CIDR \"${raw}\"`);\n  list.addSubnet(addr, bits, type);\n}\n\n/**\n * Builds a matcher from a comma-separated string or an array of IPs/CIDRs\n * (IPv4 + IPv6). Returns `null` when the list is unset/blank (= not enforced).\n * Loopback is part of an enforced list by default (see `allowLoopback`). Throws on a malformed entry — a typo must not silently turn\n * into \"everyone allowed\" or \"everyone blocked\". `label` names the option in\n * the error message.\n */\nexport function parseIpAllowlist(\n  value: string | readonly string[] | undefined,\n  label = \"allowlist\",\n  { allowLoopback = true }: ParseOptions = {},\n): IpMatcher | null {\n  const raw = typeof value === \"string\" ? value.split(\",\") : (value ?? []);\n  const entries = raw.map((s) => s.trim()).filter(Boolean);\n  if (entries.length === 0) return null;\n\n  const list = new BlockList();\n  for (const entry of [...(allowLoopback ? LOOPBACK : []), ...entries]) {\n    try {\n      addEntry(list, entry);\n    } catch (err) {\n      throw new Error(`${label}: ${(err as Error).message}`, { cause: err });\n    }\n  }\n  return (ip) => {\n    if (!ip || ip.includes(\"%\")) return false;\n    const addr = normalizeIp(ip);\n    const family = isIP(addr);\n    if (!family) return false;\n    return list.check(addr, family === 4 ? \"ipv4\" : \"ipv6\");\n  };\n}\n","import { SetMetadata } from \"@nestjs/common\";\n\nexport const SKIP_IP_ALLOWLIST_KEY = \"skipIpAllowlist\";\n\n/**\n * Exempts a route (or controller) from the guard. For callers whose IPs cannot\n * be pinned down and that authenticate by other means (e.g. provider webhooks\n * verified by an HMAC signature).\n */\nexport const SkipIpAllowlist = (): MethodDecorator & ClassDecorator =>\n  SetMetadata(SKIP_IP_ALLOWLIST_KEY, true);\n"],"mappings":"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","names":["import_common","import_core","import_common","import_node_net"]}

package/dist/index.d.cts

@@ -3,6 +3,8 @@ import { Reflector } from '@nestjs/core';
 export { I as IpMatcher, n as normalizeIp, p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.cjs';
 
 declare const IP_ALLOWLIST_OPTIONS: unique symbol;
+/** Why a request was rejected: on the denylist, or not on the applicable allowlist. */
+type BlockReason = "denied" | "not_allowed";
 interface IpAllowlistOptions {
     /**
      * Allowlist for protected (non-public) routes: comma-separated string or
@@ -14,6 +16,15 @@ interface IpAllowlistOptions {
      * below. Unset/blank = not enforced.
      */
     public?: string | readonly string[];
+    /**
+     * Denylist applied to EVERY route (protected and public): comma-separated string
+     * or array of IPs/CIDRs that are always rejected. Takes precedence over the
+     * allowlists, and — unlike them — also applies to `@SkipIpAllowlist()` routes
+     * (a banned address is banned everywhere). Works alone ("everyone except these")
+     * or together with the allowlists. Loopback is never denied implicitly.
+     * Unset/blank = nothing denied.
+     */
+    deny?: string | readonly string[];
     /**
      * Metadata key that marks a route as public. Defaults to `'isPublic'`, the
      * key used by the common `@Public()` decorator (`SetMetadata('isPublic', true)`).
@@ -28,7 +39,7 @@ interface IpAllowlistOptions {
      * Called on EVERY blocked request (feed your metrics/alerting from here).
      * The default Nest Logger warning is rate-limited per IP; this hook is not.
      */
-    onBlocked?: (ip: string | undefined) => void;
+    onBlocked?: (ip: string | undefined, reason: BlockReason) => void;
 }
 
 declare class IpAllowlistModule {
@@ -52,10 +63,12 @@ declare class IpAllowlistGuard implements CanActivate {
     private readonly logger;
     private readonly protectedMatcher;
     private readonly publicMatcher;
+    private readonly denyMatcher;
     private readonly publicKey;
     private readonly lastLogged;
     constructor(reflector: Reflector, options: IpAllowlistOptions);
     canActivate(ctx: ExecutionContext): boolean;
+    private reject;
     private notifyBlocked;
 }
 
@@ -67,4 +80,4 @@ declare const SKIP_IP_ALLOWLIST_KEY = "skipIpAllowlist";
  */
 declare const SkipIpAllowlist: () => MethodDecorator & ClassDecorator;
 
-export { IP_ALLOWLIST_OPTIONS, IpAllowlistGuard, IpAllowlistModule, type IpAllowlistOptions, SKIP_IP_ALLOWLIST_KEY, SkipIpAllowlist };
+export { type BlockReason, IP_ALLOWLIST_OPTIONS, IpAllowlistGuard, IpAllowlistModule, type IpAllowlistOptions, SKIP_IP_ALLOWLIST_KEY, SkipIpAllowlist };

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { Reflector } from '@nestjs/core';
 export { I as IpMatcher, n as normalizeIp, p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.js';
 
 declare const IP_ALLOWLIST_OPTIONS: unique symbol;
+/** Why a request was rejected: on the denylist, or not on the applicable allowlist. */
+type BlockReason = "denied" | "not_allowed";
 interface IpAllowlistOptions {
     /**
      * Allowlist for protected (non-public) routes: comma-separated string or
@@ -14,6 +16,15 @@ interface IpAllowlistOptions {
      * below. Unset/blank = not enforced.
      */
     public?: string | readonly string[];
+    /**
+     * Denylist applied to EVERY route (protected and public): comma-separated string
+     * or array of IPs/CIDRs that are always rejected. Takes precedence over the
+     * allowlists, and — unlike them — also applies to `@SkipIpAllowlist()` routes
+     * (a banned address is banned everywhere). Works alone ("everyone except these")
+     * or together with the allowlists. Loopback is never denied implicitly.
+     * Unset/blank = nothing denied.
+     */
+    deny?: string | readonly string[];
     /**
      * Metadata key that marks a route as public. Defaults to `'isPublic'`, the
      * key used by the common `@Public()` decorator (`SetMetadata('isPublic', true)`).
@@ -28,7 +39,7 @@ interface IpAllowlistOptions {
      * Called on EVERY blocked request (feed your metrics/alerting from here).
      * The default Nest Logger warning is rate-limited per IP; this hook is not.
      */
-    onBlocked?: (ip: string | undefined) => void;
+    onBlocked?: (ip: string | undefined, reason: BlockReason) => void;
 }
 
 declare class IpAllowlistModule {
@@ -52,10 +63,12 @@ declare class IpAllowlistGuard implements CanActivate {
     private readonly logger;
     private readonly protectedMatcher;
     private readonly publicMatcher;
+    private readonly denyMatcher;
     private readonly publicKey;
     private readonly lastLogged;
     constructor(reflector: Reflector, options: IpAllowlistOptions);
     canActivate(ctx: ExecutionContext): boolean;
+    private reject;
     private notifyBlocked;
 }
 
@@ -67,4 +80,4 @@ declare const SKIP_IP_ALLOWLIST_KEY = "skipIpAllowlist";
  */
 declare const SkipIpAllowlist: () => MethodDecorator & ClassDecorator;
 
-export { IP_ALLOWLIST_OPTIONS, IpAllowlistGuard, IpAllowlistModule, type IpAllowlistOptions, SKIP_IP_ALLOWLIST_KEY, SkipIpAllowlist };
+export { type BlockReason, IP_ALLOWLIST_OPTIONS, IpAllowlistGuard, IpAllowlistModule, type IpAllowlistOptions, SKIP_IP_ALLOWLIST_KEY, SkipIpAllowlist };

package/dist/index.js

@@ -37,6 +37,7 @@ var IpAllowlistGuard = class {
     const parse = { allowLoopback: options.allowLoopback ?? true };
     this.protectedMatcher = parseIpAllowlist(options.protected, "protected", parse);
     this.publicMatcher = parseIpAllowlist(options.public, "public", parse);
+    this.denyMatcher = parseIpAllowlist(options.deny, "deny", { allowLoopback: false });
     this.publicKey = options.publicMetadataKey ?? "isPublic";
   }
   reflector;
@@ -44,36 +45,45 @@ var IpAllowlistGuard = class {
   logger = new Logger(IpAllowlistGuard.name);
   protectedMatcher;
   publicMatcher;
+  denyMatcher;
   publicKey;
   lastLogged = /* @__PURE__ */ new Map();
   canActivate(ctx) {
     const type = ctx.getType();
     if (type === "rpc") return true;
+    if (!this.protectedMatcher && !this.publicMatcher && !this.denyMatcher) return true;
+    const ip = type === "http" ? ctx.switchToHttp().getRequest().ip : void 0;
+    if (this.denyMatcher?.(ip)) return this.reject(ip, "denied");
     if (!this.protectedMatcher && !this.publicMatcher) return true;
     const targets = [ctx.getHandler(), ctx.getClass()];
     if (this.reflector.getAllAndOverride(SKIP_IP_ALLOWLIST_KEY, targets)) return true;
     const isPublic = this.reflector.getAllAndOverride(this.publicKey, targets);
     const matcher = isPublic ? this.publicMatcher : this.protectedMatcher;
     if (!matcher) return true;
-    const ip = type === "http" ? ctx.switchToHttp().getRequest().ip : void 0;
     if (matcher(ip)) return true;
-    this.notifyBlocked(ip);
+    return this.reject(ip, "not_allowed");
+  }
+  reject(ip, reason) {
+    this.notifyBlocked(ip, reason);
     throw new ForbiddenException("ip_not_allowed");
   }
-  notifyBlocked(ip) {
-    this.options.onBlocked?.(ip);
+  notifyBlocked(ip, reason) {
+    this.options.onBlocked?.(ip, reason);
     const key = ip && isIP(ip) ? ip : "invalid";
+    const logKey = `${reason}:${key}`;
     const now = Date.now();
-    const last = this.lastLogged.get(key);
+    const last = this.lastLogged.get(logKey);
     if (last !== void 0 && now - last < LOG_INTERVAL_MS) return;
-    this.lastLogged.delete(key);
-    this.lastLogged.set(key, now);
+    this.lastLogged.delete(logKey);
+    this.lastLogged.set(logKey, now);
     if (this.lastLogged.size > MAX_TRACKED_IPS) {
       const oldest = this.lastLogged.keys().next().value;
       if (oldest !== void 0) this.lastLogged.delete(oldest);
     }
     if (!this.options.onBlocked) {
-      this.logger.warn(`Blocked request from non-allowlisted IP ${key}`);
+      this.logger.warn(
+        reason === "denied" ? `Blocked request from denylisted IP ${key}` : `Blocked request from non-allowlisted IP ${key}`
+      );
     }
   }
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ip-allowlist.module.ts","../src/ip-allowlist.guard.ts","../src/options.ts","../src/skip-ip-allowlist.decorator.ts"],"sourcesContent":["import { Module, type DynamicModule } from \"@nestjs/common\";\nimport { APP_GUARD } from \"@nestjs/core\";\nimport { IpAllowlistGuard } from \"./ip-allowlist.guard.js\";\nimport { IP_ALLOWLIST_OPTIONS, type IpAllowlistOptions } from \"./options.js\";\n\n@Module({})\nexport class IpAllowlistModule {\n  /**\n   * Registers the guard globally (APP_GUARD). Import this module BEFORE the\n   * module that registers your auth guard so a blocked IP is rejected before\n   * any authentication work.\n   */\n  static forRoot(options: IpAllowlistOptions = {}): DynamicModule {\n    return {\n      module: IpAllowlistModule,\n      providers: [\n        { provide: IP_ALLOWLIST_OPTIONS, useValue: options },\n        { provide: APP_GUARD, useClass: IpAllowlistGuard },\n      ],\n    };\n  }\n}\n","import {\n  ForbiddenException,\n  Inject,\n  Injectable,\n  Logger,\n  type CanActivate,\n  type ExecutionContext,\n} from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\nimport { isIP } from \"node:net\";\nimport { IP_ALLOWLIST_OPTIONS, type IpAllowlistOptions } from \"./options.js\";\nimport { parseIpAllowlist, type IpMatcher } from \"./ip-matcher.js\";\nimport { SKIP_IP_ALLOWLIST_KEY } from \"./skip-ip-allowlist.decorator.js\";\n\n// Default log line is rate-limited per IP; the map is bounded by evicting the OLDEST\n// entry, so rotating through many IPs can never switch logging off.\nconst LOG_INTERVAL_MS = 60_000;\nconst MAX_TRACKED_IPS = 1000;\n\n/**\n * Restricts routes by source IP. Reads `request.ip`, which Express/Fastify\n * resolve through their own `trust proxy` setting — configure it so `req.ip`\n * is the real client behind your proxy (see `buildTrustProxy` in the\n * `/fastify` entry). `X-Forwarded-For` is never read here.\n */\n@Injectable()\nexport class IpAllowlistGuard implements CanActivate {\n  private readonly logger = new Logger(IpAllowlistGuard.name);\n  private readonly protectedMatcher: IpMatcher | null;\n  private readonly publicMatcher: IpMatcher | null;\n  private readonly publicKey: string;\n  private readonly lastLogged = new Map<string, number>();\n\n  constructor(\n    @Inject(Reflector) private readonly reflector: Reflector,\n    @Inject(IP_ALLOWLIST_OPTIONS) private readonly options: IpAllowlistOptions,\n  ) {\n    const parse = { allowLoopback: options.allowLoopback ?? true };\n    this.protectedMatcher = parseIpAllowlist(options.protected, \"protected\", parse);\n    this.publicMatcher = parseIpAllowlist(options.public, \"public\", parse);\n    this.publicKey = options.publicMetadataKey ?? \"isPublic\";\n  }\n\n  canActivate(ctx: ExecutionContext): boolean {\n    // Only microservice (RPC) traffic is exempt: it has no client IP and is internal\n    // transport. Any other context type (graphql, ws, ...) is NOT skipped — it has no\n    // resolvable `req.ip` here, so it is denied when a list is enforced (fail closed).\n    const type = ctx.getType<string>();\n    if (type === \"rpc\") return true;\n    if (!this.protectedMatcher && !this.publicMatcher) return true;\n\n    const targets = [ctx.getHandler(), ctx.getClass()];\n    if (this.reflector.getAllAndOverride<boolean>(SKIP_IP_ALLOWLIST_KEY, targets)) return true;\n\n    const isPublic = this.reflector.getAllAndOverride<boolean>(this.publicKey, targets);\n    const matcher = isPublic ? this.publicMatcher : this.protectedMatcher;\n    if (!matcher) return true;\n\n    const ip = type === \"http\" ? ctx.switchToHttp().getRequest<{ ip?: string }>().ip : undefined;\n    if (matcher(ip)) return true;\n\n    this.notifyBlocked(ip);\n    throw new ForbiddenException(\"ip_not_allowed\");\n  }\n\n  private notifyBlocked(ip: string | undefined): void {\n    this.options.onBlocked?.(ip);\n\n    // Never log attacker-controlled text: only a well-formed IP is echoed.\n    const key = ip && isIP(ip) ? ip : \"invalid\";\n    const now = Date.now();\n    const last = this.lastLogged.get(key);\n    if (last !== undefined && now - last < LOG_INTERVAL_MS) return;\n    this.lastLogged.delete(key);\n    this.lastLogged.set(key, now);\n    if (this.lastLogged.size > MAX_TRACKED_IPS) {\n      const oldest = this.lastLogged.keys().next().value;\n      if (oldest !== undefined) this.lastLogged.delete(oldest);\n    }\n    if (!this.options.onBlocked) {\n      this.logger.warn(`Blocked request from non-allowlisted IP ${key}`);\n    }\n  }\n}\n","export const IP_ALLOWLIST_OPTIONS = Symbol(\"IP_ALLOWLIST_OPTIONS\");\n\nexport interface IpAllowlistOptions {\n  /**\n   * Allowlist for protected (non-public) routes: comma-separated string or\n   * array of IPs/CIDRs. Unset/blank = not enforced.\n   */\n  protected?: string | readonly string[];\n  /**\n   * Allowlist for public (\"open\") routes, i.e. routes carrying the metadata key\n   * below. Unset/blank = not enforced.\n   */\n  public?: string | readonly string[];\n  /**\n   * Metadata key that marks a route as public. Defaults to `'isPublic'`, the\n   * key used by the common `@Public()` decorator (`SetMetadata('isPublic', true)`).\n   */\n  publicMetadataKey?: string;\n  /**\n   * Always allow loopback once a list is set. Default `true`. Set `false` if a\n   * reverse proxy runs on the same host and `req.ip` could be its loopback address.\n   */\n  allowLoopback?: boolean;\n  /**\n   * Called on EVERY blocked request (feed your metrics/alerting from here).\n   * The default Nest Logger warning is rate-limited per IP; this hook is not.\n   */\n  onBlocked?: (ip: string | undefined) => void;\n}\n","import { SetMetadata } from \"@nestjs/common\";\n\nexport const SKIP_IP_ALLOWLIST_KEY = \"skipIpAllowlist\";\n\n/**\n * Exempts a route (or controller) from the guard. For callers whose IPs cannot\n * be pinned down and that authenticate by other means (e.g. provider webhooks\n * verified by an HMAC signature).\n */\nexport const SkipIpAllowlist = (): MethodDecorator & ClassDecorator =>\n  SetMetadata(SKIP_IP_ALLOWLIST_KEY, true);\n"],"mappings":";;;;;;;;AAAA,SAAS,cAAkC;AAC3C,SAAS,iBAAiB;;;ACD1B;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP,SAAS,iBAAiB;AAC1B,SAAS,YAAY;;;ACTd,IAAM,uBAAuB,uBAAO,sBAAsB;;;ACAjE,SAAS,mBAAmB;AAErB,IAAM,wBAAwB;AAO9B,IAAM,kBAAkB,MAC7B,YAAY,uBAAuB,IAAI;;;AFMzC,IAAM,kBAAkB;AACxB,IAAM,kBAAkB;AASjB,IAAM,mBAAN,MAA8C;AAAA,EAOnD,YACsC,WACW,SAC/C;AAFoC;AACW;AAE/C,UAAM,QAAQ,EAAE,eAAe,QAAQ,iBAAiB,KAAK;AAC7D,SAAK,mBAAmB,iBAAiB,QAAQ,WAAW,aAAa,KAAK;AAC9E,SAAK,gBAAgB,iBAAiB,QAAQ,QAAQ,UAAU,KAAK;AACrE,SAAK,YAAY,QAAQ,qBAAqB;AAAA,EAChD;AAAA,EAPsC;AAAA,EACW;AAAA,EARhC,SAAS,IAAI,OAAO,iBAAiB,IAAI;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA,aAAa,oBAAI,IAAoB;AAAA,EAYtD,YAAY,KAAgC;AAI1C,UAAM,OAAO,IAAI,QAAgB;AACjC,QAAI,SAAS,MAAO,QAAO;AAC3B,QAAI,CAAC,KAAK,oBAAoB,CAAC,KAAK,cAAe,QAAO;AAE1D,UAAM,UAAU,CAAC,IAAI,WAAW,GAAG,IAAI,SAAS,CAAC;AACjD,QAAI,KAAK,UAAU,kBAA2B,uBAAuB,OAAO,EAAG,QAAO;AAEtF,UAAM,WAAW,KAAK,UAAU,kBAA2B,KAAK,WAAW,OAAO;AAClF,UAAM,UAAU,WAAW,KAAK,gBAAgB,KAAK;AACrD,QAAI,CAAC,QAAS,QAAO;AAErB,UAAM,KAAK,SAAS,SAAS,IAAI,aAAa,EAAE,WAA4B,EAAE,KAAK;AACnF,QAAI,QAAQ,EAAE,EAAG,QAAO;AAExB,SAAK,cAAc,EAAE;AACrB,UAAM,IAAI,mBAAmB,gBAAgB;AAAA,EAC/C;AAAA,EAEQ,cAAc,IAA8B;AAClD,SAAK,QAAQ,YAAY,EAAE;AAG3B,UAAM,MAAM,MAAM,KAAK,EAAE,IAAI,KAAK;AAClC,UAAM,MAAM,KAAK,IAAI;AACrB,UAAM,OAAO,KAAK,WAAW,IAAI,GAAG;AACpC,QAAI,SAAS,UAAa,MAAM,OAAO,gBAAiB;AACxD,SAAK,WAAW,OAAO,GAAG;AAC1B,SAAK,WAAW,IAAI,KAAK,GAAG;AAC5B,QAAI,KAAK,WAAW,OAAO,iBAAiB;AAC1C,YAAM,SAAS,KAAK,WAAW,KAAK,EAAE,KAAK,EAAE;AAC7C,UAAI,WAAW,OAAW,MAAK,WAAW,OAAO,MAAM;AAAA,IACzD;AACA,QAAI,CAAC,KAAK,QAAQ,WAAW;AAC3B,WAAK,OAAO,KAAK,2CAA2C,GAAG,EAAE;AAAA,IACnE;AAAA,EACF;AACF;AAzDa,mBAAN;AAAA,EADN,WAAW;AAAA,EASP,0BAAO,SAAS;AAAA,EAChB,0BAAO,oBAAoB;AAAA,GATnB;;;ADpBN,IAAM,oBAAN,MAAwB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAM7B,OAAO,QAAQ,UAA8B,CAAC,GAAkB;AAC9D,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,WAAW;AAAA,QACT,EAAE,SAAS,sBAAsB,UAAU,QAAQ;AAAA,QACnD,EAAE,SAAS,WAAW,UAAU,iBAAiB;AAAA,MACnD;AAAA,IACF;AAAA,EACF;AACF;AAfa,oBAAN;AAAA,EADN,OAAO,CAAC,CAAC;AAAA,GACG;","names":[]}
+{"version":3,"sources":["../src/ip-allowlist.module.ts","../src/ip-allowlist.guard.ts","../src/options.ts","../src/skip-ip-allowlist.decorator.ts"],"sourcesContent":["import { Module, type DynamicModule } from \"@nestjs/common\";\nimport { APP_GUARD } from \"@nestjs/core\";\nimport { IpAllowlistGuard } from \"./ip-allowlist.guard.js\";\nimport { IP_ALLOWLIST_OPTIONS, type IpAllowlistOptions } from \"./options.js\";\n\n@Module({})\nexport class IpAllowlistModule {\n  /**\n   * Registers the guard globally (APP_GUARD). Import this module BEFORE the\n   * module that registers your auth guard so a blocked IP is rejected before\n   * any authentication work.\n   */\n  static forRoot(options: IpAllowlistOptions = {}): DynamicModule {\n    return {\n      module: IpAllowlistModule,\n      providers: [\n        { provide: IP_ALLOWLIST_OPTIONS, useValue: options },\n        { provide: APP_GUARD, useClass: IpAllowlistGuard },\n      ],\n    };\n  }\n}\n","import {\n  ForbiddenException,\n  Inject,\n  Injectable,\n  Logger,\n  type CanActivate,\n  type ExecutionContext,\n} from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\nimport { isIP } from \"node:net\";\nimport { IP_ALLOWLIST_OPTIONS, type BlockReason, type IpAllowlistOptions } from \"./options.js\";\nimport { parseIpAllowlist, type IpMatcher } from \"./ip-matcher.js\";\nimport { SKIP_IP_ALLOWLIST_KEY } from \"./skip-ip-allowlist.decorator.js\";\n\n// Default log line is rate-limited per IP; the map is bounded by evicting the OLDEST\n// entry, so rotating through many IPs can never switch logging off.\nconst LOG_INTERVAL_MS = 60_000;\nconst MAX_TRACKED_IPS = 1000;\n\n/**\n * Restricts routes by source IP. Reads `request.ip`, which Express/Fastify\n * resolve through their own `trust proxy` setting — configure it so `req.ip`\n * is the real client behind your proxy (see `buildTrustProxy` in the\n * `/fastify` entry). `X-Forwarded-For` is never read here.\n */\n@Injectable()\nexport class IpAllowlistGuard implements CanActivate {\n  private readonly logger = new Logger(IpAllowlistGuard.name);\n  private readonly protectedMatcher: IpMatcher | null;\n  private readonly publicMatcher: IpMatcher | null;\n  private readonly denyMatcher: IpMatcher | null;\n  private readonly publicKey: string;\n  private readonly lastLogged = new Map<string, number>();\n\n  constructor(\n    @Inject(Reflector) private readonly reflector: Reflector,\n    @Inject(IP_ALLOWLIST_OPTIONS) private readonly options: IpAllowlistOptions,\n  ) {\n    const parse = { allowLoopback: options.allowLoopback ?? true };\n    this.protectedMatcher = parseIpAllowlist(options.protected, \"protected\", parse);\n    this.publicMatcher = parseIpAllowlist(options.public, \"public\", parse);\n    // The denylist never adds loopback implicitly: only what the operator lists.\n    this.denyMatcher = parseIpAllowlist(options.deny, \"deny\", { allowLoopback: false });\n    this.publicKey = options.publicMetadataKey ?? \"isPublic\";\n  }\n\n  canActivate(ctx: ExecutionContext): boolean {\n    // Only microservice (RPC) traffic is exempt: it has no client IP and is internal\n    // transport. Any other context type (graphql, ws, ...) is NOT skipped — it has no\n    // resolvable `req.ip` here, so it is denied when an allowlist is enforced (fail closed).\n    const type = ctx.getType<string>();\n    if (type === \"rpc\") return true;\n    if (!this.protectedMatcher && !this.publicMatcher && !this.denyMatcher) return true;\n\n    const ip = type === \"http\" ? ctx.switchToHttp().getRequest<{ ip?: string }>().ip : undefined;\n\n    // Denylist first, on every route (including @SkipIpAllowlist ones): it wins over any allow.\n    if (this.denyMatcher?.(ip)) return this.reject(ip, \"denied\");\n\n    if (!this.protectedMatcher && !this.publicMatcher) return true;\n    const targets = [ctx.getHandler(), ctx.getClass()];\n    if (this.reflector.getAllAndOverride<boolean>(SKIP_IP_ALLOWLIST_KEY, targets)) return true;\n\n    const isPublic = this.reflector.getAllAndOverride<boolean>(this.publicKey, targets);\n    const matcher = isPublic ? this.publicMatcher : this.protectedMatcher;\n    if (!matcher) return true;\n    if (matcher(ip)) return true;\n\n    return this.reject(ip, \"not_allowed\");\n  }\n\n  private reject(ip: string | undefined, reason: BlockReason): never {\n    this.notifyBlocked(ip, reason);\n    throw new ForbiddenException(\"ip_not_allowed\");\n  }\n\n  private notifyBlocked(ip: string | undefined, reason: BlockReason): void {\n    this.options.onBlocked?.(ip, reason);\n\n    // Never log attacker-controlled text: only a well-formed IP is echoed.\n    const key = ip && isIP(ip) ? ip : \"invalid\";\n    const logKey = `${reason}:${key}`;\n    const now = Date.now();\n    const last = this.lastLogged.get(logKey);\n    if (last !== undefined && now - last < LOG_INTERVAL_MS) return;\n    this.lastLogged.delete(logKey);\n    this.lastLogged.set(logKey, now);\n    if (this.lastLogged.size > MAX_TRACKED_IPS) {\n      const oldest = this.lastLogged.keys().next().value;\n      if (oldest !== undefined) this.lastLogged.delete(oldest);\n    }\n    if (!this.options.onBlocked) {\n      this.logger.warn(\n        reason === \"denied\"\n          ? `Blocked request from denylisted IP ${key}`\n          : `Blocked request from non-allowlisted IP ${key}`,\n      );\n    }\n  }\n}\n","export const IP_ALLOWLIST_OPTIONS = Symbol(\"IP_ALLOWLIST_OPTIONS\");\n\n/** Why a request was rejected: on the denylist, or not on the applicable allowlist. */\nexport type BlockReason = \"denied\" | \"not_allowed\";\n\nexport interface IpAllowlistOptions {\n  /**\n   * Allowlist for protected (non-public) routes: comma-separated string or\n   * array of IPs/CIDRs. Unset/blank = not enforced.\n   */\n  protected?: string | readonly string[];\n  /**\n   * Allowlist for public (\"open\") routes, i.e. routes carrying the metadata key\n   * below. Unset/blank = not enforced.\n   */\n  public?: string | readonly string[];\n  /**\n   * Denylist applied to EVERY route (protected and public): comma-separated string\n   * or array of IPs/CIDRs that are always rejected. Takes precedence over the\n   * allowlists, and — unlike them — also applies to `@SkipIpAllowlist()` routes\n   * (a banned address is banned everywhere). Works alone (\"everyone except these\")\n   * or together with the allowlists. Loopback is never denied implicitly.\n   * Unset/blank = nothing denied.\n   */\n  deny?: string | readonly string[];\n  /**\n   * Metadata key that marks a route as public. Defaults to `'isPublic'`, the\n   * key used by the common `@Public()` decorator (`SetMetadata('isPublic', true)`).\n   */\n  publicMetadataKey?: string;\n  /**\n   * Always allow loopback once a list is set. Default `true`. Set `false` if a\n   * reverse proxy runs on the same host and `req.ip` could be its loopback address.\n   */\n  allowLoopback?: boolean;\n  /**\n   * Called on EVERY blocked request (feed your metrics/alerting from here).\n   * The default Nest Logger warning is rate-limited per IP; this hook is not.\n   */\n  onBlocked?: (ip: string | undefined, reason: BlockReason) => void;\n}\n","import { SetMetadata } from \"@nestjs/common\";\n\nexport const SKIP_IP_ALLOWLIST_KEY = \"skipIpAllowlist\";\n\n/**\n * Exempts a route (or controller) from the guard. For callers whose IPs cannot\n * be pinned down and that authenticate by other means (e.g. provider webhooks\n * verified by an HMAC signature).\n */\nexport const SkipIpAllowlist = (): MethodDecorator & ClassDecorator =>\n  SetMetadata(SKIP_IP_ALLOWLIST_KEY, true);\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idevconn/allowlist-guard",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Global NestJS guard that restricts routes by source IP/CIDR, with separate allowlists for protected and public routes. Works on Fastify and Express.",
   "license": "Apache-2.0",
   "author": "iDEVconn",
@@ -67,15 +67,9 @@
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
-    "fastify": ">=4.0.0",
     "reflect-metadata": "^0.1.13 || ^0.2.0",
     "rxjs": "^7.0.0"
   },
-  "peerDependenciesMeta": {
-    "fastify": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@changesets/cli": "^3.0.1",
     "@nestjs/common": "^11.2.3",