@idevconn/allowlist-guard 0.0.0-stage → 0.0.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,102 @@
-# 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`).
+
+## 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`; `fastify` only if you use the `/fastify` subpath.
+
+## Usage
+
+```ts
+import { Module } from "@nestjs/common";
+import { IpAllowlistModule } from "@idevconn/allowlist-guard";
+
+@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, ...
+    }),
+    AuthModule,
+  ],
+})
+export class AppModule {}
+```
+
+| 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()`.
+
+Exempt a route:
+
+```ts
+import { SkipIpAllowlist } from "@idevconn/allowlist-guard";
+
+@Public()
+@SkipIpAllowlist() // authenticated by an HMAC signature instead
+@Post("webhooks/:provider")
+receive() {}
+```
+
+## 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)`.
+- **Fastify:**
+
+  ```ts
+  import { buildTrustProxy } from "@idevconn/allowlist-guard/fastify";
+
+  new FastifyAdapter({ trustProxy: buildTrustProxy(process.env.TRUSTED_PROXIES) });
+  ```
+
+  `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.
+
+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).
+
+## Routes outside Nest (Swagger UI)
+
+Fastify-native routes never reach Nest guards. Restrict them with the same list, **before** registering them:
+
+```ts
+import { parseIpAllowlist, restrictRoutesToAllowlist } from "@idevconn/allowlist-guard/fastify";
+
+const allowed = parseIpAllowlist(process.env.API_IP_ALLOWLIST);
+if (allowed) restrictRoutesToAllowlist(app.getHttpAdapter().getInstance(), allowed, "/api/docs");
+SwaggerModule.setup("api/docs", app, document);
+```
+
+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.
+
+## 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 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":[]}

package/dist/fastify.d.cts

@@ -0,0 +1,28 @@
+import { FastifyInstance } from 'fastify';
+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;
+/**
+ * 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: FastifyInstance, allowed: IpMatcher, routePrefix: string): void;
+
+export { IpMatcher, buildTrustProxy, restrictRoutesToAllowlist };

package/dist/fastify.d.ts

@@ -0,0 +1,28 @@
+import { FastifyInstance } from 'fastify';
+import { I as IpMatcher } from './ip-matcher-D4MA1kIq.js';
+export { p as parseIpAllowlist } from './ip-matcher-D4MA1kIq.js';
+
+/**
+ * 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;
+/**
+ * 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: FastifyInstance, allowed: IpMatcher, routePrefix: string): void;
+
+export { IpMatcher, buildTrustProxy, restrictRoutesToAllowlist };

package/dist/fastify.js

@@ -0,0 +1,25 @@
+import {
+  parseIpAllowlist
+} from "./chunk-POEP4ARO.js";
+
+// 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();
+  });
+}
+export {
+  buildTrustProxy,
+  parseIpAllowlist,
+  restrictRoutesToAllowlist
+};
+//# sourceMappingURL=fastify.js.map

package/dist/fastify.js.map

@@ -0,0 +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":[]}

package/dist/index.cjs

@@ -0,0 +1,189 @@
+"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);
+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/index.ts
+var src_exports = {};
+__export(src_exports, {
+  IP_ALLOWLIST_OPTIONS: () => IP_ALLOWLIST_OPTIONS,
+  IpAllowlistGuard: () => IpAllowlistGuard,
+  IpAllowlistModule: () => IpAllowlistModule,
+  SKIP_IP_ALLOWLIST_KEY: () => SKIP_IP_ALLOWLIST_KEY,
+  SkipIpAllowlist: () => SkipIpAllowlist,
+  normalizeIp: () => normalizeIp,
+  parseIpAllowlist: () => parseIpAllowlist
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/ip-allowlist.module.ts
+var import_common3 = require("@nestjs/common");
+var import_core2 = require("@nestjs/core");
+
+// src/ip-allowlist.guard.ts
+var import_common2 = require("@nestjs/common");
+var import_core = require("@nestjs/core");
+var import_node_net2 = require("net");
+
+// src/options.ts
+var IP_ALLOWLIST_OPTIONS = /* @__PURE__ */ Symbol("IP_ALLOWLIST_OPTIONS");
+
+// 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/skip-ip-allowlist.decorator.ts
+var import_common = require("@nestjs/common");
+var SKIP_IP_ALLOWLIST_KEY = "skipIpAllowlist";
+var SkipIpAllowlist = () => (0, import_common.SetMetadata)(SKIP_IP_ALLOWLIST_KEY, true);
+
+// src/ip-allowlist.guard.ts
+var LOG_INTERVAL_MS = 6e4;
+var MAX_TRACKED_IPS = 1e3;
+var IpAllowlistGuard = class {
+  constructor(reflector, options) {
+    this.reflector = reflector;
+    this.options = options;
+    const parse = { allowLoopback: options.allowLoopback ?? true };
+    this.protectedMatcher = parseIpAllowlist(options.protected, "protected", parse);
+    this.publicMatcher = parseIpAllowlist(options.public, "public", parse);
+    this.publicKey = options.publicMetadataKey ?? "isPublic";
+  }
+  reflector;
+  options;
+  logger = new import_common2.Logger(IpAllowlistGuard.name);
+  protectedMatcher;
+  publicMatcher;
+  publicKey;
+  lastLogged = /* @__PURE__ */ new Map();
+  canActivate(ctx) {
+    const type = ctx.getType();
+    if (type === "rpc") return true;
+    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);
+    throw new import_common2.ForbiddenException("ip_not_allowed");
+  }
+  notifyBlocked(ip) {
+    this.options.onBlocked?.(ip);
+    const key = ip && (0, import_node_net2.isIP)(ip) ? ip : "invalid";
+    const now = Date.now();
+    const last = this.lastLogged.get(key);
+    if (last !== void 0 && now - last < LOG_INTERVAL_MS) return;
+    this.lastLogged.delete(key);
+    this.lastLogged.set(key, 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}`);
+    }
+  }
+};
+IpAllowlistGuard = __decorateClass([
+  (0, import_common2.Injectable)(),
+  __decorateParam(0, (0, import_common2.Inject)(import_core.Reflector)),
+  __decorateParam(1, (0, import_common2.Inject)(IP_ALLOWLIST_OPTIONS))
+], IpAllowlistGuard);
+
+// src/ip-allowlist.module.ts
+var IpAllowlistModule = class {
+  /**
+   * Registers the guard globally (APP_GUARD). Import this module BEFORE the
+   * module that registers your auth guard so a blocked IP is rejected before
+   * any authentication work.
+   */
+  static forRoot(options = {}) {
+    return {
+      module: IpAllowlistModule,
+      providers: [
+        { provide: IP_ALLOWLIST_OPTIONS, useValue: options },
+        { provide: import_core2.APP_GUARD, useClass: IpAllowlistGuard }
+      ]
+    };
+  }
+};
+IpAllowlistModule = __decorateClass([
+  (0, import_common3.Module)({})
+], IpAllowlistModule);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IP_ALLOWLIST_OPTIONS,
+  IpAllowlistGuard,
+  IpAllowlistModule,
+  SKIP_IP_ALLOWLIST_KEY,
+  SkipIpAllowlist,
+  normalizeIp,
+  parseIpAllowlist
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,IAAAA,iBAA2C;AAC3C,IAAAC,eAA0B;;;ACD1B,IAAAC,iBAOO;AACP,kBAA0B;AAC1B,IAAAC,mBAAqB;;;ACTd,IAAM,uBAAuB,uBAAO,sBAAsB;;;ACAjE,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;;;ACxEA,oBAA4B;AAErB,IAAM,wBAAwB;AAO9B,IAAM,kBAAkB,UAC7B,2BAAY,uBAAuB,IAAI;;;AHMzC,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,sBAAO,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,kCAAmB,gBAAgB;AAAA,EAC/C;AAAA,EAEQ,cAAc,IAA8B;AAClD,SAAK,QAAQ,YAAY,EAAE;AAG3B,UAAM,MAAM,UAAM,uBAAK,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,MADN,2BAAW;AAAA,EASP,8CAAO,qBAAS;AAAA,EAChB,8CAAO,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,wBAAW,UAAU,iBAAiB;AAAA,MACnD;AAAA,IACF;AAAA,EACF;AACF;AAfa,oBAAN;AAAA,MADN,uBAAO,CAAC,CAAC;AAAA,GACG;","names":["import_common","import_core","import_common","import_node_net"]}

package/dist/index.d.cts

@@ -0,0 +1,70 @@
+import { DynamicModule, CanActivate, ExecutionContext } from '@nestjs/common';
+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;
+interface IpAllowlistOptions {
+    /**
+     * Allowlist for protected (non-public) routes: comma-separated string or
+     * array of IPs/CIDRs. Unset/blank = not enforced.
+     */
+    protected?: string | readonly string[];
+    /**
+     * Allowlist for public ("open") routes, i.e. routes carrying the metadata key
+     * below. Unset/blank = not enforced.
+     */
+    public?: 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)`).
+     */
+    publicMetadataKey?: string;
+    /**
+     * Always allow loopback once a list is set. Default `true`. Set `false` if a
+     * reverse proxy runs on the same host and `req.ip` could be its loopback address.
+     */
+    allowLoopback?: boolean;
+    /**
+     * 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;
+}
+
+declare class IpAllowlistModule {
+    /**
+     * Registers the guard globally (APP_GUARD). Import this module BEFORE the
+     * module that registers your auth guard so a blocked IP is rejected before
+     * any authentication work.
+     */
+    static forRoot(options?: IpAllowlistOptions): DynamicModule;
+}
+
+/**
+ * Restricts routes by source IP. Reads `request.ip`, which Express/Fastify
+ * resolve through their own `trust proxy` setting — configure it so `req.ip`
+ * is the real client behind your proxy (see `buildTrustProxy` in the
+ * `/fastify` entry). `X-Forwarded-For` is never read here.
+ */
+declare class IpAllowlistGuard implements CanActivate {
+    private readonly reflector;
+    private readonly options;
+    private readonly logger;
+    private readonly protectedMatcher;
+    private readonly publicMatcher;
+    private readonly publicKey;
+    private readonly lastLogged;
+    constructor(reflector: Reflector, options: IpAllowlistOptions);
+    canActivate(ctx: ExecutionContext): boolean;
+    private notifyBlocked;
+}
+
+declare const SKIP_IP_ALLOWLIST_KEY = "skipIpAllowlist";
+/**
+ * Exempts a route (or controller) from the guard. For callers whose IPs cannot
+ * be pinned down and that authenticate by other means (e.g. provider webhooks
+ * verified by an HMAC signature).
+ */
+declare const SkipIpAllowlist: () => MethodDecorator & ClassDecorator;
+
+export { IP_ALLOWLIST_OPTIONS, IpAllowlistGuard, IpAllowlistModule, type IpAllowlistOptions, SKIP_IP_ALLOWLIST_KEY, SkipIpAllowlist };

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { DynamicModule, CanActivate, ExecutionContext } from '@nestjs/common';
+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;
+interface IpAllowlistOptions {
+    /**
+     * Allowlist for protected (non-public) routes: comma-separated string or
+     * array of IPs/CIDRs. Unset/blank = not enforced.
+     */
+    protected?: string | readonly string[];
+    /**
+     * Allowlist for public ("open") routes, i.e. routes carrying the metadata key
+     * below. Unset/blank = not enforced.
+     */
+    public?: 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)`).
+     */
+    publicMetadataKey?: string;
+    /**
+     * Always allow loopback once a list is set. Default `true`. Set `false` if a
+     * reverse proxy runs on the same host and `req.ip` could be its loopback address.
+     */
+    allowLoopback?: boolean;
+    /**
+     * 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;
+}
+
+declare class IpAllowlistModule {
+    /**
+     * Registers the guard globally (APP_GUARD). Import this module BEFORE the
+     * module that registers your auth guard so a blocked IP is rejected before
+     * any authentication work.
+     */
+    static forRoot(options?: IpAllowlistOptions): DynamicModule;
+}
+
+/**
+ * Restricts routes by source IP. Reads `request.ip`, which Express/Fastify
+ * resolve through their own `trust proxy` setting — configure it so `req.ip`
+ * is the real client behind your proxy (see `buildTrustProxy` in the
+ * `/fastify` entry). `X-Forwarded-For` is never read here.
+ */
+declare class IpAllowlistGuard implements CanActivate {
+    private readonly reflector;
+    private readonly options;
+    private readonly logger;
+    private readonly protectedMatcher;
+    private readonly publicMatcher;
+    private readonly publicKey;
+    private readonly lastLogged;
+    constructor(reflector: Reflector, options: IpAllowlistOptions);
+    canActivate(ctx: ExecutionContext): boolean;
+    private notifyBlocked;
+}
+
+declare const SKIP_IP_ALLOWLIST_KEY = "skipIpAllowlist";
+/**
+ * Exempts a route (or controller) from the guard. For callers whose IPs cannot
+ * be pinned down and that authenticate by other means (e.g. provider webhooks
+ * verified by an HMAC signature).
+ */
+declare const SkipIpAllowlist: () => MethodDecorator & ClassDecorator;
+
+export { IP_ALLOWLIST_OPTIONS, IpAllowlistGuard, IpAllowlistModule, type IpAllowlistOptions, SKIP_IP_ALLOWLIST_KEY, SkipIpAllowlist };

package/dist/index.js

@@ -0,0 +1,115 @@
+import {
+  __decorateClass,
+  __decorateParam,
+  normalizeIp,
+  parseIpAllowlist
+} from "./chunk-POEP4ARO.js";
+
+// src/ip-allowlist.module.ts
+import { Module } from "@nestjs/common";
+import { APP_GUARD } from "@nestjs/core";
+
+// src/ip-allowlist.guard.ts
+import {
+  ForbiddenException,
+  Inject,
+  Injectable,
+  Logger
+} from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { isIP } from "net";
+
+// src/options.ts
+var IP_ALLOWLIST_OPTIONS = /* @__PURE__ */ Symbol("IP_ALLOWLIST_OPTIONS");
+
+// src/skip-ip-allowlist.decorator.ts
+import { SetMetadata } from "@nestjs/common";
+var SKIP_IP_ALLOWLIST_KEY = "skipIpAllowlist";
+var SkipIpAllowlist = () => SetMetadata(SKIP_IP_ALLOWLIST_KEY, true);
+
+// src/ip-allowlist.guard.ts
+var LOG_INTERVAL_MS = 6e4;
+var MAX_TRACKED_IPS = 1e3;
+var IpAllowlistGuard = class {
+  constructor(reflector, options) {
+    this.reflector = reflector;
+    this.options = options;
+    const parse = { allowLoopback: options.allowLoopback ?? true };
+    this.protectedMatcher = parseIpAllowlist(options.protected, "protected", parse);
+    this.publicMatcher = parseIpAllowlist(options.public, "public", parse);
+    this.publicKey = options.publicMetadataKey ?? "isPublic";
+  }
+  reflector;
+  options;
+  logger = new Logger(IpAllowlistGuard.name);
+  protectedMatcher;
+  publicMatcher;
+  publicKey;
+  lastLogged = /* @__PURE__ */ new Map();
+  canActivate(ctx) {
+    const type = ctx.getType();
+    if (type === "rpc") return true;
+    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);
+    throw new ForbiddenException("ip_not_allowed");
+  }
+  notifyBlocked(ip) {
+    this.options.onBlocked?.(ip);
+    const key = ip && isIP(ip) ? ip : "invalid";
+    const now = Date.now();
+    const last = this.lastLogged.get(key);
+    if (last !== void 0 && now - last < LOG_INTERVAL_MS) return;
+    this.lastLogged.delete(key);
+    this.lastLogged.set(key, 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}`);
+    }
+  }
+};
+IpAllowlistGuard = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(Reflector)),
+  __decorateParam(1, Inject(IP_ALLOWLIST_OPTIONS))
+], IpAllowlistGuard);
+
+// src/ip-allowlist.module.ts
+var IpAllowlistModule = class {
+  /**
+   * Registers the guard globally (APP_GUARD). Import this module BEFORE the
+   * module that registers your auth guard so a blocked IP is rejected before
+   * any authentication work.
+   */
+  static forRoot(options = {}) {
+    return {
+      module: IpAllowlistModule,
+      providers: [
+        { provide: IP_ALLOWLIST_OPTIONS, useValue: options },
+        { provide: APP_GUARD, useClass: IpAllowlistGuard }
+      ]
+    };
+  }
+};
+IpAllowlistModule = __decorateClass([
+  Module({})
+], IpAllowlistModule);
+export {
+  IP_ALLOWLIST_OPTIONS,
+  IpAllowlistGuard,
+  IpAllowlistModule,
+  SKIP_IP_ALLOWLIST_KEY,
+  SkipIpAllowlist,
+  normalizeIp,
+  parseIpAllowlist
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/dist/ip-matcher-D4MA1kIq.d.cts

@@ -0,0 +1,22 @@
+type IpMatcher = (ip: string | undefined) => boolean;
+interface ParseOptions {
+    /**
+     * Always allow loopback (`127.0.0.0/8`, `::1`) once a list is set. Default `true`
+     * (local dev, health probes). Set `false` when a reverse proxy runs on the SAME
+     * host and `req.ip` may fall back to its loopback address — otherwise a proxy
+     * without trust-proxy configured makes every client look like 127.0.0.1.
+     */
+    allowLoopback?: boolean;
+}
+/** `::ffff:1.2.3.4` (what a dual-stack socket reports for IPv4 peers) → `1.2.3.4`. */
+declare function normalizeIp(ip: string): string;
+/**
+ * Builds a matcher from a comma-separated string or an array of IPs/CIDRs
+ * (IPv4 + IPv6). Returns `null` when the list is unset/blank (= not enforced).
+ * Loopback is part of an enforced list by default (see `allowLoopback`). Throws on a malformed entry — a typo must not silently turn
+ * into "everyone allowed" or "everyone blocked". `label` names the option in
+ * the error message.
+ */
+declare function parseIpAllowlist(value: string | readonly string[] | undefined, label?: string, { allowLoopback }?: ParseOptions): IpMatcher | null;
+
+export { type IpMatcher as I, normalizeIp as n, parseIpAllowlist as p };

package/dist/ip-matcher-D4MA1kIq.d.ts

@@ -0,0 +1,22 @@
+type IpMatcher = (ip: string | undefined) => boolean;
+interface ParseOptions {
+    /**
+     * Always allow loopback (`127.0.0.0/8`, `::1`) once a list is set. Default `true`
+     * (local dev, health probes). Set `false` when a reverse proxy runs on the SAME
+     * host and `req.ip` may fall back to its loopback address — otherwise a proxy
+     * without trust-proxy configured makes every client look like 127.0.0.1.
+     */
+    allowLoopback?: boolean;
+}
+/** `::ffff:1.2.3.4` (what a dual-stack socket reports for IPv4 peers) → `1.2.3.4`. */
+declare function normalizeIp(ip: string): string;
+/**
+ * Builds a matcher from a comma-separated string or an array of IPs/CIDRs
+ * (IPv4 + IPv6). Returns `null` when the list is unset/blank (= not enforced).
+ * Loopback is part of an enforced list by default (see `allowLoopback`). Throws on a malformed entry — a typo must not silently turn
+ * into "everyone allowed" or "everyone blocked". `label` names the option in
+ * the error message.
+ */
+declare function parseIpAllowlist(value: string | readonly string[] | undefined, label?: string, { allowLoopback }?: ParseOptions): IpMatcher | null;
+
+export { type IpMatcher as I, normalizeIp as n, parseIpAllowlist as p };

package/package.json

@@ -1,6 +1,103 @@
 {
   "name": "@idevconn/allowlist-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iDEVconn/allowListGuard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iDEVconn/allowListGuard/issues"
+  },
+  "homepage": "https://github.com/iDEVconn/allowListGuard#readme",
+  "keywords": [
+    "nestjs",
+    "guard",
+    "ip",
+    "allowlist",
+    "whitelist",
+    "cidr",
+    "fastify",
+    "express"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./fastify": {
+      "import": {
+        "types": "./dist/fastify.d.ts",
+        "default": "./dist/fastify.js"
+      },
+      "require": {
+        "types": "./dist/fastify.d.cts",
+        "default": "./dist/fastify.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "changeset": "changeset",
+    "version": "changeset version"
+  },
+  "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",
+    "@nestjs/core": "^11.2.3",
+    "@nestjs/platform-express": "^11.2.3",
+    "@nestjs/platform-fastify": "^11.2.3",
+    "@nestjs/testing": "^11.2.3",
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "fastify": "^5.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "esbuild@0.27.7": true
+  }
+}