@idevconn/allowlist-guard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by interface) to the interfaces
+      of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 iDEVconn
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,230 @@
-# Temporary Holding Version
+# @idevconn/allowlist-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`).
+
+> [!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. 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.
+- 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".
+- Rejects with `403 ip_not_allowed`. Default log line is rate-limited per IP (1/min, bounded memory, never echoes malformed input); `onBlocked` is called on **every** blocked request for metrics/alerting.
+- Fails closed: only microservice (`rpc`) contexts are exempt; other non-HTTP contexts (GraphQL, WebSocket) have no resolvable `req.ip` and are denied while a list is enforced.
+- `/fastify` subpath: `buildTrustProxy` and `restrictRoutesToAllowlist` (for routes outside Nest's guard pipeline, e.g. Swagger UI).
+
+## Install
+
+```bash
+npm install @idevconn/allowlist-guard
+```
+
+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: "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,
+  ],
+})
+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.                                                                             |
+| `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`.         |
+
+**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()`.
+
+### 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);
+  if (allowed) {
+    restrictRoutesToAllowlist(app.getHttpAdapter().getInstance(), allowed, "/api/docs");
+  }
+  const document = SwaggerModule.createDocument(app, new DocumentBuilder().build());
+  SwaggerModule.setup("api/docs", app, document);
+
+  await app.listen(3000, "0.0.0.0");
+}
+bootstrap();
+```
+
+### Exempting routes
+
+```ts
+import { Controller, Post, SetMetadata } from "@nestjs/common";
+import { SkipIpAllowlist } from "@idevconn/allowlist-guard";
+
+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() {}
+}
+```
+
+`@SkipIpAllowlist()` also works on a whole controller class (e.g. a health check controller).
+
+### Using your own "public" decorator
+
+If your project marks open routes with a different metadata key, tell the guard:
+
+```ts
+export const OPEN_ROUTE = "openRoute";
+export const Open = () => SetMetadata(OPEN_ROUTE, true);
+
+IpAllowlistModule.forRoot({ public: "198.51.100.0/24", publicMetadataKey: OPEN_ROUTE });
+```
+
+### Alerting on blocked requests
+
+`onBlocked` runs on **every** blocked request (the default log line is rate-limited to one per IP per minute), so feed metrics from it:
+
+```ts
+IpAllowlistModule.forRoot({
+  protected: process.env.API_IP_ALLOWLIST,
+  onBlocked: (ip) => metrics.increment("ip_allowlist.blocked", { ip: ip ?? "unknown" }),
+});
+```
+
+### Using the matcher on its own
+
+```ts
+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
+```
+
+### Local development and tests
+
+Leave the lists 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`).
+
+## 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
+}
+```
+
+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` (see the Fastify example) applies the same list to them. It matches on the resolved route (`routeOptions.url`), not the raw URL, so percent-encoded paths such as `/api/%64ocs` cannot slip past.
+
+## Limits
+
+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
+
+Apache-2.0

package/dist/chunk-POEP4ARO.js

@@ -0,0 +1,63 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/ip-matcher.ts
+import { BlockList, isIP } from "net";
+var LOOPBACK = ["127.0.0.0/8", "::1"];
+function normalizeIp(ip) {
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(ip);
+  return mapped?.[1] ?? ip;
+}
+function addEntry(list, raw) {
+  const [addr = "", prefix, ...rest] = raw.split("/");
+  const family = isIP(addr);
+  if (!family || addr.includes("%") || rest.length > 0) {
+    throw new Error(`invalid IP/CIDR "${raw}"`);
+  }
+  const type = family === 4 ? "ipv4" : "ipv6";
+  if (prefix === void 0) {
+    list.addAddress(addr, type);
+    return;
+  }
+  const bits = Number(prefix);
+  const max = family === 4 ? 32 : 128;
+  if (!/^\d+$/.test(prefix) || bits > max) throw new Error(`invalid IP/CIDR "${raw}"`);
+  list.addSubnet(addr, bits, type);
+}
+function parseIpAllowlist(value, label = "allowlist", { allowLoopback = true } = {}) {
+  const raw = typeof value === "string" ? value.split(",") : value ?? [];
+  const entries = raw.map((s) => s.trim()).filter(Boolean);
+  if (entries.length === 0) return null;
+  const list = new BlockList();
+  for (const entry of [...allowLoopback ? LOOPBACK : [], ...entries]) {
+    try {
+      addEntry(list, entry);
+    } catch (err) {
+      throw new Error(`${label}: ${err.message}`, { cause: err });
+    }
+  }
+  return (ip) => {
+    if (!ip || ip.includes("%")) return false;
+    const addr = normalizeIp(ip);
+    const family = isIP(addr);
+    if (!family) return false;
+    return list.check(addr, family === 4 ? "ipv4" : "ipv6");
+  };
+}
+
+export {
+  __decorateClass,
+  __decorateParam,
+  normalizeIp,
+  parseIpAllowlist
+};
+//# sourceMappingURL=chunk-POEP4ARO.js.map

package/dist/chunk-POEP4ARO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ip-matcher.ts"],"sourcesContent":["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,SAAS,WAAW,YAAY;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,SAAS,KAAK,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,UAAU;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,SAAS,KAAK,IAAI;AACxB,QAAI,CAAC,OAAQ,QAAO;AACpB,WAAO,KAAK,MAAM,MAAM,WAAW,IAAI,SAAS,MAAM;AAAA,EACxD;AACF;","names":[]}

package/dist/fastify.cjs

@@ -0,0 +1,94 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/fastify/index.ts
+var fastify_exports = {};
+__export(fastify_exports, {
+  buildTrustProxy: () => buildTrustProxy,
+  parseIpAllowlist: () => parseIpAllowlist,
+  restrictRoutesToAllowlist: () => restrictRoutesToAllowlist
+});
+module.exports = __toCommonJS(fastify_exports);
+
+// src/ip-matcher.ts
+var import_node_net = require("net");
+var LOOPBACK = ["127.0.0.0/8", "::1"];
+function normalizeIp(ip) {
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(ip);
+  return mapped?.[1] ?? ip;
+}
+function addEntry(list, raw) {
+  const [addr = "", prefix, ...rest] = raw.split("/");
+  const family = (0, import_node_net.isIP)(addr);
+  if (!family || addr.includes("%") || rest.length > 0) {
+    throw new Error(`invalid IP/CIDR "${raw}"`);
+  }
+  const type = family === 4 ? "ipv4" : "ipv6";
+  if (prefix === void 0) {
+    list.addAddress(addr, type);
+    return;
+  }
+  const bits = Number(prefix);
+  const max = family === 4 ? 32 : 128;
+  if (!/^\d+$/.test(prefix) || bits > max) throw new Error(`invalid IP/CIDR "${raw}"`);
+  list.addSubnet(addr, bits, type);
+}
+function parseIpAllowlist(value, label = "allowlist", { allowLoopback = true } = {}) {
+  const raw = typeof value === "string" ? value.split(",") : value ?? [];
+  const entries = raw.map((s) => s.trim()).filter(Boolean);
+  if (entries.length === 0) return null;
+  const list = new import_node_net.BlockList();
+  for (const entry of [...allowLoopback ? LOOPBACK : [], ...entries]) {
+    try {
+      addEntry(list, entry);
+    } catch (err) {
+      throw new Error(`${label}: ${err.message}`, { cause: err });
+    }
+  }
+  return (ip) => {
+    if (!ip || ip.includes("%")) return false;
+    const addr = normalizeIp(ip);
+    const family = (0, import_node_net.isIP)(addr);
+    if (!family) return false;
+    return list.check(addr, family === 4 ? "ipv4" : "ipv6");
+  };
+}
+
+// src/fastify/index.ts
+function buildTrustProxy(trustedProxies) {
+  const matcher = parseIpAllowlist(trustedProxies, "trustedProxies");
+  return (address, hop) => hop === 0 && (!matcher || matcher(address));
+}
+function restrictRoutesToAllowlist(instance, allowed, routePrefix) {
+  instance.addHook("onRequest", (req, reply, done) => {
+    const route = req.routeOptions?.url ?? "";
+    if (route.startsWith(routePrefix) && !allowed(req.ip)) {
+      void reply.code(403).send({ statusCode: 403, message: "ip_not_allowed" });
+      return;
+    }
+    done();
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildTrustProxy,
+  parseIpAllowlist,
+  restrictRoutesToAllowlist
+});
+//# sourceMappingURL=fastify.cjs.map

package/dist/fastify.cjs.map

@@ -0,0 +1 @@
+{"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 */\nexport function restrictRoutesToAllowlist(\n  instance: FastifyHookHost,\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;;;AD3DO,SAAS,gBACd,gBAC2C;AAC3C,QAAM,UAAU,iBAAiB,gBAAgB,gBAAgB;AACjE,SAAO,CAAC,SAAS,QAAQ,QAAQ,MAAM,CAAC,WAAW,QAAQ,OAAO;AACpE;AA2BO,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":[]}

package/dist/fastify.d.cts

@@ -0,0 +1,44 @@
+import { I as IpMatcher } from './ip-matcher-D4MA1kIq.cjs';
+export { p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.cjs';
+
+/**
+ * Fastify `trustProxy` function equal to Express's `trust proxy = 1`: trusts
+ * only hop 0 (the socket peer, i.e. your reverse proxy), so a client cannot
+ * walk past it with extra X-Forwarded-For entries.
+ *
+ * Hop 0 is the socket peer itself: if the app port is reachable directly (not
+ * only through the proxy), ANY client is hop 0 and can forge X-Forwarded-For,
+ * defeating the allowlist. Pass `trustedProxies` (IPs/CIDRs of your proxy) to
+ * trust hop 0 only when the peer is one of them; a direct client's header is
+ * 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
+ * those routes are added.
+ *
+ * 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.
+ */
+declare function restrictRoutesToAllowlist(instance: FastifyHookHost, allowed: IpMatcher, routePrefix: string): void;
+
+export { type FastifyHookHost, IpMatcher, buildTrustProxy, restrictRoutesToAllowlist };