feat: add IP filter middleware by Octo8080X · Pull Request #3035 · freshframework/fresh

Octo8080X · 2025-06-14T05:02:28Z

Add an IP restriction middleware for Fresh, ported from Hono's IP restriction middleware.

Supports deny lists, allow lists, and CIDR subnet matching. Deny rules take precedence over allow rules.

app.use(ipFilter({
  denyList: ["192.168.1.10", "10.0.0.0/8"],
  allowList: ["192.168.1.0/24"],
}));

Closes #3011

…ction middleware

…ction tests

…e file naming

iuioiua

First pass

iuioiua · 2025-06-14T07:38:39Z

+export type AddressType = "IPv4" | "IPv6";
+
+export type NetAddrInfo = {
+  /**
+   * Transport protocol type
+   */
+  transport?: "tcp" | "udp";
+  /**
+   * Transport port number
+   */
+  port: number;
+  address: string;
+  addressType?: AddressType;
+};
+
+export interface ConnInfo {
+  /**
+   * Remote information
+   */
+  remote: NetAddrInfo;
+}


These types already exist within the Deno runtime API. See https://docs.deno.com/api/deno/network.

iuioiua · 2025-06-14T07:40:16Z

Each test should be wrapped in a Deno.test() call.

@iuioiua san.

Thanks for your comment!
Sorry if I’m mistaken, but I thought when writing in a BDD style, Deno.test would be replaced by describe. Was I incorrect about that?

https://jsr.io/@std/testing/doc/bdd#:~:text=()%2C%2018)%3B%0A%7D)%3B-,Mixed%20test%20grouping,-Both%20nested%20test

I looked at the other code as well.
I understand now that using Deno.test instead of a BDD style is the standard.
I’ll prepare a fix.

iuioiua · 2025-06-14T07:41:53Z

There's a lot of IP address logic here that might be valuable in other domains. I recommend creating an issue for the Standard Library for any useful utilities to @std/net.

The part you’re pointing out is indeed a generic utility — in Hono, it’s placed in utils as well.
I’ll go ahead and create an issue for now.

@iuioiua

I have created an issue.Thanks.
denoland/std#6722

Octo8080X · 2025-10-07T14:23:26Z

@iuioiua
Hello.
The processing logic for IP addresses has been refactored and isolated into @std/net.
The middleware has been subsequently reconstructed utilizing this new module. Your review is requested.

iuioiua · 2025-10-14T06:33:39Z

+import type { Middleware } from "./mod.ts";
+import { isIPv4, isIPv6, matchSubnets } from "@std/net/unstable-ip";
+
+export type AddressType = "IPv6" | "IPv4" | "none";


I suggest using Deno.NetworkInterfaceInfo.family instead of this new type.

iuioiua · 2025-10-14T06:38:02Z

+function findType(addr: string): AddressType {
+  if (isIPv4(addr)) {
+    return "IPv4";
+  } else if (isIPv6(addr)) {
+    return "IPv6";
+  }
+  return "none";
+}


See first comment.

Suggested change

function findType(addr: string): AddressType {

if (isIPv4(addr)) {

return "IPv4";

} else if (isIPv6(addr)) {

return "IPv6";

}

return "none";

}

function findType(addr: string): Deno.NetworkInterfaceInfo.family | undefined {

if (isIPv4(addr)) {

return "IPv4";

} else if (isIPv6(addr)) {

return "IPv6";

}

return undefined;

}

iuioiua · 2025-10-14T06:42:24Z

+    headers: {
+      "Content-Type": "text/plain",
+    },


Not needed. The content-type header by default is "text/plain;charset=UTF-8" anyway.

Suggested change

headers: {

"Content-Type": "text/plain",

},

iuioiua · 2025-10-14T06:42:49Z

+export interface IPRestrictionRules {
+  denyList?: string[];
+  allowList?: string[];
+}


This interface and its properties should have JSDocs.

iuioiua · 2025-10-14T06:55:11Z

+    if (!ctx.info.remoteAddr.hostname) {
+      return blockError();
+    }


IIUC, this conditional will never be true because ctx.info.remoteAddr.hostname is always defined.

Suggested change

if (!ctx.info.remoteAddr.hostname) {

return blockError();

}

iuioiua · 2025-10-14T22:07:32Z

+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}))
+ * ```
+ *
+ * @example custom error handling


Nit

Suggested change

* @example custom error handling

* @example Custom error handling

iuioiua · 2025-10-14T22:08:15Z

+ * @example custom error handling
+ * ```ts
+ * const customOnError: IpRestrictionOptions = {
+ *   onError: () => {


I think we should show how the onErrors parameters can be used here.

I've gone ahead and added the usage examples.

iuioiua · 2025-10-14T22:09:10Z

+function buildMatcher(ipList: string[]) {
+  return (addr: string) => {
+    return matchSubnets(addr, ipList);
+  };
+}


Not needed if we go ahead with using matchSubnets inline, as stated below.

Suggested change

function buildMatcher(ipList: string[]) {

return (addr: string) => {

return matchSubnets(addr, ipList);

};

}

iuioiua · 2025-10-14T22:11:11Z

+
+  const denyMatcher = buildMatcher(denyList);
+  const allowMatcher = buildMatcher(allowList);
+


Something like this will avoid the need for if (options?.onError) conditionals and being inline makes the behaviour of onError more immediately understood.

Suggested change

const onError = options?.onError ?? (() =>

new Response("Forbidden", {

status: 403,

headers: {

"Content-Type": "text/plain",

},

}));

I've made the adjustment to make it inline. Thanks!

iuioiua · 2025-10-14T22:13:14Z

+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))
+ * ```
+ */
+export function ipRestriction<State>(


I'm not strongly for or against this name... Are we sure about this name? Any other alternatives?

@iuioiua
How about 'IpRule' or 'IpFilter' instead of 'IP Restriction'? They sound pretty good.

ipFilter sounds okay to me.

…to8080X/fresh into feature/add_ip_restriction_middleware

iuioiua

Getting closer to being ready, IMO. Few nits. HMU on Discord (same username) if you want to chat about any of this.

iuioiua · 2025-10-20T21:29:25Z

+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))
+ * ```
+ */
+export function ipRestriction<State>(


ipFilter sounds okay to me.

iuioiua · 2025-10-20T21:31:19Z

+    }
+
+    if (matchSubnets(addr, rules.allowList || [])) {
+      const res = await ctx.next();


Suggested change

const res = await ctx.next();

return ctx.next();

Again, awaiting ctx.next() adds no value.

iuioiua · 2025-10-20T21:32:08Z

+    }
+
+    if ((rules.allowList || []).length === 0) {
+      return await ctx.next();


Suggested change

return await ctx.next();

return ctx.next();

Ditto

iuioiua · 2025-10-20T21:32:48Z

+      return await ctx.next();
+    } else {
+      if (options?.onError) {
+        return await options.onError({ addr, type }, ctx);


Suggested change

return await options.onError({ addr, type }, ctx);

return options.onError({ addr, type }, ctx);

Ditto

iuioiua · 2025-10-20T21:36:10Z

+): Middleware<State> {
+  return async function ipRestriction<State>(ctx: Context<State>) {


Suggested change

): Middleware<State> {

return async function ipRestriction<State>(ctx: Context<State>) {

): Middleware<State> {

const onBlock = options.onError ?? () => new Response("Forbidden", { status: 403 });

return async function ipRestriction<State>(ctx: Context<State>) {

Reminder: avoids having to write if (options?.onError) blocks and makes things clear more immediately.

iuioiua · 2025-10-20T21:48:26Z

+      if (options?.onError) {
+        return options.onError({ addr, type }, ctx);
+      }
+      return blockError();


Ditto. See comment about onError being defined within the exported function.

iuioiua · 2025-10-20T21:49:08Z

+      if (options?.onError) {
+        return await options.onError({ addr, type }, ctx);
+      }


Ditto. See comment about onError being defined within the exported function.

iuioiua · 2025-10-20T21:50:32Z

+/**
+ * IP restriction Middleware for Fresh.
+ *
+ * @param rules rules `{ denyList: string[], allowList: string[] }`.


Suggested change

* @param rules rules `{ denyList: string[], allowList: string[] }`.

* @param rules Deny and allow rules object.

How you had it isn't how @param JSDoc tags should be written. They need to be written in natural human language describing what the variable is.

iuioiua · 2025-10-20T21:51:11Z

+ * ```ts
+ * const app = new App<State>()
+ *
+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}))


Suggested change

* app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}))

* app.use(ipRestriction({

* denyList: ["192.168.1.10", "2001:db8::1"],

* }));

Nit

iuioiua · 2025-10-20T21:52:09Z

+ *     return new Response("custom onError", { status: 401 });
+ *   },
+ * };
+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))


Suggested change

* app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))

* app.use(ipRestriction({

* denyList: ["192.168.1.10", "2001:db8::1"]

* }, customOnError));

Nit

iuioiua

Getting closer.

iuioiua · 2025-10-21T21:18:29Z

Should these changes be reverted?

I think ip_filter is necessary because it relies on @std/net.

iuioiua · 2025-10-21T21:24:16Z

+export interface ipFilterOptions {
+  onError?: <State>(
+    remote: {
+      addr: string;
+      type: Deno.NetworkInterfaceInfo["family"] | undefined;
+    },
+    ctx: Context<State>,
+  ) => Response | Promise<Response>;
+}


This interface and its properties need documentation.

We have addressed this matter.

iuioiua · 2025-10-21T21:26:13Z

+    }
+
+    const addr = ctx.info.remoteAddr.hostname;
+    const type = findType(addr);


I think whether you're using addr and type is unrelated to my point 😛

See my suggestion below.

iuioiua · 2025-10-21T21:34:43Z

+    }
+
+    const addr = ctx.info.remoteAddr.hostname;
+    const type = findType(addr);


Suggested change

const type = findType(addr);

const type = IPv4(addr) ? "IPv4" : "IPv6";

I seem to have been overthinking it unnecessarily. I would like to adopt your proposal.

iuioiua · 2025-10-21T21:37:36Z

+    if (type == undefined) {
+      return blockError();
+    }


Yes, I do think it's unnecessary because type can only ever be IPv4 or IPv6.

iuioiua · 2025-10-21T21:42:47Z

+      throw new TypeError(
+        "Unsupported transport protocol. TCP & UDP is supported.",
+      );


Suggested change

throw new TypeError(

"Unsupported transport protocol. TCP & UDP is supported.",

);

return ctx.next();

iuioiua · 2025-10-21T21:44:10Z

+    if (
+      ctx.info.remoteAddr.transport !== "udp" &&
+      ctx.info.remoteAddr.transport !== "tcp"
+    ) {
+      throw new TypeError(
+        "Unsupported transport protocol. TCP & UDP is supported.",
+      );
+    }


Sorry, to correct my stance, yes, we should return early if not UDP or TCP traffic, because an IP address isn't being used. But I don't think throwing is the correct behaviour. Instead, we should just pass through. See my suggestion above.

iuioiua · 2025-10-21T21:49:12Z

+  rules: IpFilterRules,
+  options?: ipFilterOptions,
+): Middleware<State> {
+  const onBlock = options?.onError ?? (() => blockError());


Suggested change

const onBlock = options?.onError ?? (() => blockError());

const onBlock = options?.onError ?? (() => new Response("Forbidden", { status: 403 }));

So the reader doesn't have to scroll back up to see what onBlock does by default (since it's simple anyway).

iuioiua · 2025-10-21T21:52:40Z

+    if ((rules.allowList || []).length === 0) {
+      return ctx.next();
+    } else {
+      return onBlock({ addr, type }, ctx);


Suggested change

if ((rules.allowList || []).length === 0) {

return ctx.next();

} else {

return onBlock({ addr, type }, ctx);

return onBlock({ addr, type }, ctx);

I believe this first if statement is already covered by the preceding allow block.

this section is needs.

This is because there were cases where the permission list was not explicitly set.
However, as pointed out, some parts seemed unnecessary, so I have reorganized the content.

Thank you

iuioiua · 2025-10-21T21:55:20Z

+}
+
+/**
+ * IP restriction Middleware for Fresh.


You should explain this filter. I.e. the precedence of rules. So deny rules take precedence over allow rules and traffic not matching any rule is denied by default (implicit deny).

I mentioned this matter.

Thankyou

iuioiua

LGTM 👍🏾

Octo8080X · 2026-01-24T07:20:06Z

@marvinhagemeister

Thank you for the review on this PR a while back. It’s been about two months since iuioiua-san kindly provided feedback, and I truly appreciate the support. Please let me know if there is anything additional I can do to help get this merged—I'm ready to jump back in and make any necessary updates immediately.

- Rename ipFilterOptions to IpFilterOptions (PascalCase convention) - Rename onError to onBlocked (clearer naming) - Remove unused undefined from type field - Fix typos: remortAddr -> remoteAddr, arrow -> allow - Remove Japanese comments - Export IpFilterOptions from mod.ts - Simplify test helper (remove unnecessary branching) - Update JSDoc examples Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add docs/latest/plugins/ip-filter.md covering deny lists, allow lists, CIDR subnet matching, combined rules, and custom blocked responses. Register the page in the TOC under Plugins. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Octo8080X added 7 commits June 14, 2025 13:48

Refactor IP restriction middleware: clean up debug logs and improve flow

571b272

Remove unnecessary comments and console.log statements from IP restri…

194b59e

…ction middleware

Remove unnecessary comments and console.log statements from IP restri…

8362db1

…ction tests

Update exports in mod.ts for ipRestriction and related types

167feba

Export IPRestrictionRules type from ip_restriction in mod.ts

7ae6fc3

Rename test file to ip_restriction_test.ts for consistency with sourc…

0eb73c3

…e file naming

Export getIP from ip_restriction in mod.ts for middleware completeness

72ae3bd

iuioiua suggested changes Jun 14, 2025

View reviewed changes

Octo8080X and others added 9 commits June 14, 2025 19:26

Fix ipRestriction middleware tests and improve coverage

5987fc8

Export IPRestrictionRules type from ip_restriction module

2e93114

Merge branch 'main' into feature/add_ip_restriction_middleware

2deeb7c

Merge branch 'main' into feature/add_ip_restriction_middleware

25c2cdb

update

4e5ae78

use @std/net

caae853

update export

9db23e6

update docs

c93fd79

Merge branch 'main' into feature/add_ip_restriction_middleware

8e79b17

Octo8080X requested review from iuioiua and marvinhagemeister October 8, 2025 12:52

Merge branch 'main' into feature/add_ip_restriction_middleware

bc7f51e

iuioiua suggested changes Oct 14, 2025

View reviewed changes

Octo8080X added 4 commits October 21, 2025 00:43

fix

53612b9

Merge branch 'feature/add_ip_restriction_middleware' of github.com:Oc…

2645569

…to8080X/fresh into feature/add_ip_restriction_middleware

fix

abd6665

fix

f14e7dc

iuioiua suggested changes Oct 20, 2025

View reviewed changes

Octo8080X and others added 3 commits October 21, 2025 21:23

rename and fix

1468cde

Merge branch 'main' into feature/add_ip_restriction_middleware

e37ad41

fix

25d5d2d

Octo8080X and others added 4 commits October 21, 2025 21:27

fix

dfe28d4

fix

a7ab3de

fix

df3b5da

Merge branch 'main' into feature/add_ip_restriction_middleware

c22c4bf

iuioiua reviewed Oct 21, 2025

View reviewed changes

Octo8080X and others added 12 commits November 11, 2025 23:28

Merge branch 'main' into feature/add_ip_restriction_middleware

7236b07

merge main

3f3d37d

fix

007e150

add document

4b15afe

organized method

4c2f7a6

Merge branch 'denoland:main' into feature/add_ip_restriction_middleware

9ef84c7

logic update

5383f74

logic update

75805b8

logic update

f50aa69

logic update

5e2be56

update coments

ab623c8

restore lockfile

34407e8

Octo8080X requested a review from iuioiua November 22, 2025 14:02

iuioiua approved these changes Nov 23, 2025

View reviewed changes

Octo8080X and others added 3 commits December 23, 2025 23:45

Merge branch 'main' into feature/add_ip_restriction_middleware

ef5ff80

Merge branch 'main' into feature/add_ip_restriction_middleware

4328d63

add @std/net

4e16d46

bartlomieju changed the title ~~Feature/add ip restriction middleware~~ feat: add IP filter middleware Mar 26, 2026

bartlomieju and others added 2 commits March 27, 2026 07:49

Merge branch 'main' into feature/add_ip_restriction_middleware

a42a3c4

bartlomieju merged commit 566a6ce into freshframework:main Mar 29, 2026
7 checks passed

	* @example custom error handling
	* @example Custom error handling


		const denyMatcher = buildMatcher(denyList);
		const allowMatcher = buildMatcher(allowList);

+  const onError = options?.onError ?? (() =>
+    new Response("Forbidden", {
+      status: 403,
+      headers: {
+        "Content-Type": "text/plain",
+      },
+    }));

	return await options.onError({ addr, type }, ctx);
	return options.onError({ addr, type }, ctx);

		): Middleware<State> {
		return async function ipRestriction<State>(ctx: Context<State>) {

	* @param rules rules `{ denyList: string[], allowList: string[] }`.
	* @param rules Deny and allow rules object.

	const type = findType(addr);
	const type = IPv4(addr) ? "IPv4" : "IPv6";

	const onBlock = options?.onError ?? (() => blockError());
	const onBlock = options?.onError ?? (() => new Response("Forbidden", { status: 403 }));

Conversation

Octo8080X commented Jun 14, 2025 • edited by bartlomieju Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iuioiua left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Octo8080X Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Octo8080X commented Oct 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iuioiua left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iuioiua left a comment

Choose a reason for hiding this comment

Uh oh!

Octo8080X commented Jun 14, 2025 •

edited by bartlomieju

Loading

Octo8080X Jun 14, 2025 •

edited

Loading