Br Network Security

better-route: Network security and IP allowlists

Use this when an endpoint depends on client IP, especially behind Cloudflare, nginx, a load balancer, or any reverse proxy. Never read forwarded headers directly in handlers.

Trusted proxy resolver

use BetterRoute\Middleware\Network\TrustedProxyClientIpResolver;

$resolver = new TrustedProxyClientIpResolver(
    trustedProxyCidrs: [
        '10.0.0.0/24',
        '2001:db8:1234::/48',
    ],
    forwardedHeaders: ['CF-Connecting-IP', 'X-Forwarded-For']
);

$ip = $resolver->resolve($request);

Forwarded headers are trusted only when the immediate REMOTE_ADDR matches trustedProxyCidrs.

IP allowlist middleware

use BetterRoute\Middleware\Network\IpAllowlistMiddleware;

$allowlist = new IpAllowlistMiddleware(
    allowedCidrs: ['203.0.113.0/24', '2001:db8:feed::/48'],
    ipResolver: $resolver,
    failClosed: true
);

$router->post('/back-channel/logout', $handler)
    ->middleware([$allowlist])
    ->publicRoute();

Rate limiter integration

RateLimitMiddleware accepts the new ClientIpResolverInterface in 0.6.0:

$rateLimit = new RateLimitMiddleware(
    limiter: $limiter,
    limit: 60,
    windowSeconds: 60,
    clientIpResolver: $resolver
);

Critical rules

• Single IP strings are accepted as CIDRs (1.2.3.4 behaves like /32, IPv6 like /128).
• Header order matters; put the most authoritative proxy header first.
• X-Forwarded-For returns the first valid IP from the comma-delimited list.
• If IP is unresolvable and failClosed: true, IpAllowlistMiddleware rejects.
• Keep Cloudflare or provider CIDR lists current; stale proxy ranges cause false denials or unsafe trust.
• IP allowlists are not a replacement for request authentication when IPs are broad or dynamic; combine with HMAC when needed.

Cross-references

• Use br-rate-limiting for throttling semantics and fixed-window stores.
• Use br-hmac-signature for signed requests when IP pinning is too brittle.
• Use br-audit-enrichment if safe client IP should be added to audit events.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lonsdale201
• Source: Lonsdale201/wp-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.