IP Allowlist

IP Allowlist blocks requests unless they come from an allowed IP or CIDR range.

Use it for private networks, internal tools, or trusted proxy traffic.

Basic Usage

import { ipAllowlistPlugin } from "@better-agent/plugins";

const plugin = ipAllowlistPlugin({
  allow: ["203.0.113.10"],
});

By default the plugin reads direct client IP headers like x-real-ip and cf-connecting-ip.

CIDR Ranges

Use CIDR ranges when you want to allow a subnet instead of one exact IP.

const plugin = ipAllowlistPlugin({
  allow: ["203.0.113.0/24", "2001:db8::/32"],
});

Exact IPs and IPv4 or IPv6 CIDR ranges are both supported.

Trust Proxy

Use trustProxy when your app sits behind a trusted proxy that sets x-forwarded-for.

const plugin = ipAllowlistPlugin({
  allow: ["203.0.113.0/24"],
  trustProxy: true,
});

When enabled, the plugin uses the first valid IP from x-forwarded-for.

Custom IP Resolution

Use getIp when your platform exposes the client IP somewhere else.

const plugin = ipAllowlistPlugin({
  allow: ["203.0.113.10"],
  getIp: ({ request }) => request.headers.get("x-my-platform-ip"),
});

Denied Response

If the request IP is missing or not allowed, the plugin returns 403 Forbidden.

const plugin = ipAllowlistPlugin({
  allow: ["203.0.113.10"],
  onDenied: ({ ip }) =>
    new Response(JSON.stringify({ error: "forbidden_ip", ip }), {
      status: 403,
      headers: { "content-type": "application/json" },
    }),
});