@daloyjs/core 1.0.0 → 1.1.0

package/dist/conn-info.js

@@ -18,6 +18,7 @@
  *
  * @since 0.24.0
  */
+import { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-match.js";
 const CONN_INFO_SYMBOL = Symbol.for("daloyjs.connInfo");
 /**
  * @internal Adapter helper — attach {@link ConnInfo} to a `Request`. Called
@@ -74,6 +75,16 @@ export function assertBehindProxy(cfg) {
                 if (typeof c !== "string" || c.length === 0) {
                     throw new Error("behindProxy.cidrs entries must be non-empty strings.");
                 }
+                // Refuse to boot on an invalid CIDR — a typo'd range must never
+                // silently become "trust nobody" (fail-closed) or, worse, be ignored
+                // (fail-open). Compile once here; request-time resolution reuses the
+                // cached matchers, so the throw surface is construction-only.
+                try {
+                    compileCidrMatcher(c);
+                }
+                catch {
+                    throw new Error(`behindProxy.cidrs: invalid IP/CIDR entry ${JSON.stringify(c)}.`);
+                }
             }
             return;
         }
@@ -122,22 +133,36 @@ export function pickForwardedForByHops(header, hops) {
  * `behindProxy.hops` range: the floor of one exists because a middleware that
  * trusts zero proxy hops has no business reading forwarding headers at all.
  *
+ * `trustedProxies` (a CIDR allowlist of proxy peer addresses) also enables
+ * forwarded-header trust, defaulting to one hop when `trustedHops` is not
+ * set: declaring WHO your proxies are is meaningless unless their headers
+ * are then read. Pair it with {@link resolveTrustedProxyMatchers} and pass
+ * the compiled matchers to {@link resolveForwardedClientIp} so the forwarded
+ * identity is honoured only when the immediate TCP peer is a verified proxy.
+ *
  * @param name - Middleware function name used in error messages.
- * @param opts - The middleware's options object; only the two trust fields are
+ * @param opts - The middleware's options object; only the trust fields are
  *   read, so any middleware option type is structurally acceptable.
  * @returns The number of trusted proxy hops when forwarded-header trust is
- *   enabled — `trustedHops` verbatim, or `1` for a bare
- *   `trustProxyHeaders: true` — or `undefined` when trust is off and the caller
- *   must not read forwarding headers at all.
+ *   enabled — `trustedHops` verbatim, `1` for a bare
+ *   `trustProxyHeaders: true`, or `1` when `trustedProxies` is declared
+ *   without an explicit hop count — or `undefined` when trust is off and the
+ *   caller must not read forwarding headers at all.
  * @throws Error when `trustedHops` is not an integer in [1, 64], or when
- *   `trustProxyHeaders: false` is combined with a `trustedHops` value. That
- *   pairing is a contradiction, and it previously resolved silently in favour
- *   of trust — meaning an explicit opt-out was ignored.
+ *   `trustProxyHeaders: false` is combined with a `trustedHops` value or a
+ *   `trustedProxies` list. Those pairings are contradictions, and the first
+ *   previously resolved silently in favour of trust — meaning an explicit
+ *   opt-out was ignored.
  * @internal
  */
 export function resolveForwardedTrust(name, opts) {
     const hops = opts.trustedHops;
     const trust = opts.trustProxyHeaders;
+    const proxies = opts.trustedProxies;
+    if (trust === false && proxies !== undefined) {
+        throw new Error(`${name}: trustProxyHeaders: false contradicts trustedProxies. ` +
+            "trustedProxies implies proxy-header trust; drop whichever one you did not mean.");
+    }
     if (hops !== undefined) {
         if (!Number.isInteger(hops) || hops < 1 || hops > 64) {
             throw new Error(`${name}: trustedHops must be an integer in [1, 64]; got ${String(hops)}.`);
@@ -148,8 +173,70 @@ export function resolveForwardedTrust(name, opts) {
         }
         return hops;
     }
+    if (proxies !== undefined)
+        return 1;
     return trust === true ? 1 : undefined;
 }
+/**
+ * Validate and compile a middleware's `trustedProxies` CIDR allowlist into
+ * matchers usable with {@link resolveForwardedClientIp}. Called once at
+ * construction so the per-request cost of peer verification is a handful of
+ * byte comparisons, never string parsing.
+ *
+ * The allowlist answers the question `trustedHops` alone cannot: not "how
+ * many proxies are in front of me" but "is the socket actually talking to me
+ * one of MY proxies". Without it, any client that can reach the origin
+ * directly can claim any `X-Forwarded-For` identity — the victim-IP framing
+ * and ban-evasion classes documented on {@link resolveForwardedClientIp}.
+ *
+ * @param name - Middleware function name used in error messages.
+ * @param opts - The middleware's options object; only `trustedProxies` is read.
+ * @returns The compiled matchers, or `undefined` when `trustedProxies` is not
+ *   declared (no peer verification — the pre-existing posture).
+ * @throws Error when the list is empty (a silent "trust nobody" foot-gun) or
+ *   any entry is not a valid IP/CIDR. Both are refuse-at-construction
+ *   misconfigurations, never request-time surprises.
+ * @internal
+ */
+export function resolveTrustedProxyMatchers(name, opts) {
+    const proxies = opts.trustedProxies;
+    if (proxies === undefined)
+        return undefined;
+    if (!Array.isArray(proxies) || proxies.length === 0) {
+        throw new Error(`${name}: trustedProxies must be a non-empty IP/CIDR string array.`);
+    }
+    return proxies.map((entry) => {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new Error(`${name}: trustedProxies entries must be non-empty strings.`);
+        }
+        try {
+            return compileCidrMatcher(entry);
+        }
+        catch {
+            throw new Error(`${name}: trustedProxies — invalid IP/CIDR entry ${JSON.stringify(entry)}.`);
+        }
+    });
+}
+/**
+ * Test whether the immediate TCP peer of `request` is inside the compiled
+ * `trustedProxies` allowlist. Returns `false` when the adapter attached no
+ * connection metadata (pure edge delegators expose no peer socket) — peer
+ * verification fails closed by design.
+ *
+ * @param request - Incoming request whose adapter-attached peer is checked.
+ * @param trustedPeers - Compiled matchers from {@link resolveTrustedProxyMatchers}.
+ * @returns `true` only when a peer address exists and matches the allowlist.
+ * @internal
+ */
+function isTrustedPeer(request, trustedPeers) {
+    const peer = getConnInfo(request)?.remoteAddress;
+    if (!peer)
+        return false;
+    const parsed = parseIp(peer);
+    if (!parsed)
+        return false;
+    return trustedPeers.some((m) => matchesMatcher(parsed, m));
+}
 /**
  * Resolve the client IP from the proxy-set forwarding headers, walking a
  * declared number of trusted hops from the RIGHT side of `X-Forwarded-For`.
@@ -171,17 +258,30 @@ export function resolveForwardedTrust(name, opts) {
  * Security note: this resolver is only meaningful when every request reaches
  * the app through a proxy chain you control that appends (or overwrites)
  * these headers. With no proxy in front, any forwarded-header trust is
- * attacker-controlled by definition.
+ * attacker-controlled by definition. `trustedPeers` closes that gap at the
+ * framework layer: when supplied, the forwarded identity is honoured only
+ * when the immediate TCP peer — the socket actually talking to the adapter,
+ * which a remote client cannot spoof — is inside the declared proxy
+ * allowlist. A direct-to-origin attacker then gets `undefined` (no
+ * identity), so spoofed headers can neither frame a victim nor rotate away
+ * strikes. When conn metadata is absent (peer-less edge platforms),
+ * verification fails closed.
  *
  * @param request - Incoming request whose forwarding headers are read.
  * @param hops - Number of trusted proxy hops; `1` (default) reads the
  *   rightmost entry — the one your immediate proxy appended.
+ * @param trustedPeers - Optional compiled allowlist from
+ *   {@link resolveTrustedProxyMatchers}. When supplied, forwarded headers
+ *   are honoured only if the immediate peer matches; otherwise `undefined`.
  * @returns The resolved client IP, or `undefined` when no forwarded identity
  *   is available. Callers decide their own posture for `undefined`
  *   (fail-closed 403, fail-open skip, or a shared `"global"` bucket).
  * @since 1.0.0-rc.7
  */
-export function resolveForwardedClientIp(request, hops = 1) {
+export function resolveForwardedClientIp(request, hops = 1, trustedPeers) {
+    if (trustedPeers !== undefined && !isTrustedPeer(request, trustedPeers)) {
+        return undefined;
+    }
     const picked = pickForwardedForByHops(request.headers.get("x-forwarded-for"), hops);
     if (picked)
         return picked;
@@ -200,6 +300,16 @@ export function resolveForwardedClientIp(request, hops = 1) {
         return undefined;
     return request.headers.get("x-real-ip") ?? undefined;
 }
+/**
+ * Compiled-CIDR cache for {@link resolveClientIp}'s `{ cidrs }` branch. Keyed
+ * by the config array's identity (stable per `App` instance) so the per-
+ * request hot path never re-parses strings — one compile per App, then byte
+ * comparisons. `App` construction validates via {@link assertBehindProxy}; the
+ * request path still fails closed (returns peer, never trusts XFF) if a
+ * direct caller of the exported {@link resolveClientIp} passes unvalidated
+ * CIDRs and compilation throws.
+ */
+const behindProxyCidrCache = new WeakMap();
 /**
  * Resolve the client IP for this request using the configured
  * {@link BehindProxyConfig}. Returns `undefined` when no trusted source is
@@ -231,11 +341,29 @@ export function resolveClientIp(request, cfg) {
         const xff = request.headers.get("x-forwarded-for");
         return pickForwardedForByHops(xff, cfg.hops) ?? peer;
     }
-    // { cidrs } — out of scope for the trim implementation; falls back to peer.
-    // The CIDR matcher is reused from src/ip-restriction.ts; consumers that
-    // need the full check can compose ipRestriction({ allow: cfg.cidrs }) into
-    // the resolver. We honour the header only if the peer matches one of the
-    // declared CIDRs.
+    // { cidrs } — honour the forwarded identity only when the immediate peer
+    // (the socket a remote client cannot spoof) sits inside one of the declared
+    // proxy ranges. A direct-to-origin caller gets their real peer address and
+    // their spoofed XFF is ignored: no victim-IP framing, no ban evasion.
+    let matchers = behindProxyCidrCache.get(cfg.cidrs);
+    if (!matchers) {
+        try {
+            matchers = cfg.cidrs.map(compileCidrMatcher);
+            behindProxyCidrCache.set(cfg.cidrs, matchers);
+        }
+        catch {
+            // Unvalidated direct call: never trust XFF on a broken allowlist.
+            return peer;
+        }
+    }
+    if (peer) {
+        const parsed = parseIp(peer);
+        if (parsed && matchers.some((m) => matchesMatcher(parsed, m))) {
+            const picked = pickForwardedForByHops(request.headers.get("x-forwarded-for"), 1);
+            if (picked)
+                return picked;
+        }
+    }
     return peer;
 }
 /**

package/dist/fetch-guard.js

@@ -88,7 +88,7 @@
  * @since 0.34.0
  * @module
  */
-import { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-restriction.js";
+import { compileCidrMatcher, matchesMatcher, parseIp, } from "./ip-match.js";
 /**
  * Thrown by {@link fetchGuard} when an outbound request is refused. Never
  * thrown for ordinary network failures — those bubble through unchanged

package/dist/geo-block.d.ts

@@ -133,6 +133,17 @@ export interface GeoBlockOptions {
      * `resolveCountry` is used or a custom `resolveIp` is supplied.
      */
     trustedHops?: number;
+    /**
+     * Declare WHICH proxies are yours: an IP/CIDR allowlist for the immediate
+     * peer's address. Forwarded headers are honoured only when the TCP socket
+     * actually talking to the adapter matches the list — the one property a
+     * remote client cannot spoof — so a direct-to-origin attacker cannot claim
+     * an allowed-country IP. Implies proxy-header trust at one hop unless
+     * {@link trustedHops} says otherwise; validated and compiled at
+     * construction. On peer-less edge platforms verification fails closed.
+     * Ignored when `resolveCountry` is used or a custom `resolveIp` is supplied.
+     */
+    trustedProxies?: readonly string[];
     /**
      * What to do when the country cannot be resolved. Defaults to `false` when
      * an `allow` list is configured (fail closed — an unknown country is not on

package/dist/geo-block.js

@@ -25,7 +25,7 @@
  * @since 0.37.0
  */
 import { ForbiddenError } from "./errors.js";
-import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
+import { resolveForwardedClientIp, resolveForwardedTrust, resolveTrustedProxyMatchers, } from "./conn-info.js";
 /** @internal Validate + normalise a configured country code, or throw. */
 function normalizeConfiguredCode(input) {
     const code = input.trim().toUpperCase();
@@ -45,8 +45,8 @@ function noIpResolver(_ctx) {
  * by the operator's own proxy chain and is therefore the spoof-resistant
  * side — see {@link resolveForwardedClientIp}.
  */
-function forwardedIpResolver(hops) {
-    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
+function forwardedIpResolver(hops, trustedPeers) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops, trustedPeers);
 }
 /**
  * Block or allow requests by client country. Daloy ships no GeoIP database;
@@ -105,7 +105,9 @@ export function geoBlock(opts) {
     const lookupCountry = opts.lookupCountry;
     const resolveCountry = opts.resolveCountry;
     const hops = resolveForwardedTrust("geoBlock()", opts);
-    const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
+    const proxyMatchers = resolveTrustedProxyMatchers("geoBlock()", opts);
+    const resolveIp = opts.resolveIp ??
+        (hops !== undefined ? forwardedIpResolver(hops, proxyMatchers) : noIpResolver);
     return {
         // Runs in `preBody`, not `beforeHandle`. A `beforeHandle` hook that returns
         // a Response ends the chain, so a country gate in that phase is preempted by

package/dist/ip-match.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Leaf IP/CIDR matching primitives shared by network-identity middleware,
+ * `fetchGuard()`, and peer-verified proxy trust.
+ *
+ * Kept free of imports from other framework modules so security-critical
+ * consumers (`conn-info`, `ip-restriction`, `fetch-guard`) can share the
+ * matcher without circular dependencies.
+ *
+ * @internal
+ * @since 1.1.0
+ */
+/** Parsed IP address (shared with `fetchGuard()` and peer trust). */
+export interface ParsedIp {
+    /** Big-endian address bytes: 4 bytes for IPv4, 16 for IPv6. */
+    bytes: Uint8Array;
+    /** Address family: `4` for IPv4, `6` for IPv6. */
+    family: 4 | 6;
+}
+/** Compiled CIDR matcher (shared with `fetchGuard()` and peer trust). */
+export interface IpMatcher {
+    /** Address family the matcher applies to: `4` or `6`. */
+    family: 4 | 6;
+    /** CIDR prefix length in bits (0-32 for IPv4, 0-128 for IPv6). */
+    prefix: number;
+    /** Network address bytes with all host bits masked to zero. */
+    bytes: Uint8Array;
+}
+/**
+ * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing
+ * only the matcher's prefix bits. IPv4-mapped IPv6 addresses
+ * (`::ffff:a.b.c.d`) are normalized so they match IPv4 matchers.
+ *
+ * @param ip Parsed client address from {@link parseIp}.
+ * @param m Compiled matcher from {@link compileCidrMatcher}.
+ * @returns `true` when the address is within the matcher's range.
+ * @internal
+ */
+export declare function matchesMatcher(ip: ParsedIp, m: IpMatcher): boolean;
+/**
+ * Compile an IP or CIDR pattern (e.g. `"10.0.0.0/8"`, `"::1"`) into an
+ * {@link IpMatcher}. A bare address gets a full-length prefix (/32 or /128);
+ * host bits beyond the prefix are masked to zero.
+ *
+ * Error message prefix stays `ipRestriction():` for historical compatibility
+ * with callers that match the string (the matcher was born there).
+ *
+ * @param input IPv4/IPv6 address, optionally with a `/prefix` suffix.
+ * @returns The compiled matcher used by {@link matchesMatcher}.
+ * @throws Error when the address or CIDR prefix is invalid.
+ * @internal
+ */
+export declare function compileCidrMatcher(input: string): IpMatcher;
+/**
+ * Parse an IPv4 or IPv6 address string into raw bytes. Supports IPv6 `::`
+ * compression and IPv4-mapped tails (`::ffff:1.2.3.4`).
+ *
+ * @param input Address string; surrounding whitespace is trimmed.
+ * @returns The parsed address, or `undefined` when the input is not a valid
+ *   IP (callers treat unparseable addresses as a rejection, failing closed).
+ * @internal
+ */
+export declare function parseIp(input: string): ParsedIp | undefined;

package/dist/ip-match.js

@@ -0,0 +1,171 @@
+/**
+ * Leaf IP/CIDR matching primitives shared by network-identity middleware,
+ * `fetchGuard()`, and peer-verified proxy trust.
+ *
+ * Kept free of imports from other framework modules so security-critical
+ * consumers (`conn-info`, `ip-restriction`, `fetch-guard`) can share the
+ * matcher without circular dependencies.
+ *
+ * @internal
+ * @since 1.1.0
+ */
+/**
+ * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing
+ * only the matcher's prefix bits. IPv4-mapped IPv6 addresses
+ * (`::ffff:a.b.c.d`) are normalized so they match IPv4 matchers.
+ *
+ * @param ip Parsed client address from {@link parseIp}.
+ * @param m Compiled matcher from {@link compileCidrMatcher}.
+ * @returns `true` when the address is within the matcher's range.
+ * @internal
+ */
+export function matchesMatcher(ip, m) {
+    const candidate = normalizeFamily(ip, m.family);
+    if (!candidate)
+        return false;
+    const expected = m.bytes;
+    const totalBits = candidate.length * 8;
+    const prefix = Math.min(m.prefix, totalBits);
+    const fullBytes = prefix >> 3;
+    for (let i = 0; i < fullBytes; i++) {
+        if (candidate[i] !== expected[i])
+            return false;
+    }
+    const remaining = prefix - fullBytes * 8;
+    if (remaining === 0)
+        return true;
+    const mask = 0xff << (8 - remaining);
+    return ((candidate[fullBytes] ^ expected[fullBytes]) & mask) === 0;
+}
+/**
+ * Compile an IP or CIDR pattern (e.g. `"10.0.0.0/8"`, `"::1"`) into an
+ * {@link IpMatcher}. A bare address gets a full-length prefix (/32 or /128);
+ * host bits beyond the prefix are masked to zero.
+ *
+ * Error message prefix stays `ipRestriction():` for historical compatibility
+ * with callers that match the string (the matcher was born there).
+ *
+ * @param input IPv4/IPv6 address, optionally with a `/prefix` suffix.
+ * @returns The compiled matcher used by {@link matchesMatcher}.
+ * @throws Error when the address or CIDR prefix is invalid.
+ * @internal
+ */
+export function compileCidrMatcher(input) {
+    let addr = input;
+    let prefixStr;
+    if (input.includes("/")) {
+        const slash = input.indexOf("/");
+        addr = input.slice(0, slash);
+        prefixStr = input.slice(slash + 1);
+    }
+    const parsed = parseIp(addr);
+    if (!parsed) {
+        throw new Error(`ipRestriction(): invalid IP address ${JSON.stringify(input)}.`);
+    }
+    const totalBits = parsed.family === 4 ? 32 : 128;
+    let prefix = totalBits;
+    if (prefixStr !== undefined) {
+        if (!/^\d+$/.test(prefixStr)) {
+            throw new Error(`ipRestriction(): invalid CIDR prefix in ${JSON.stringify(input)}.`);
+        }
+        prefix = Number.parseInt(prefixStr, 10);
+        if (!Number.isInteger(prefix) || prefix < 0 || prefix > totalBits) {
+            throw new Error(`ipRestriction(): invalid CIDR prefix in ${JSON.stringify(input)}.`);
+        }
+    }
+    return { family: parsed.family, prefix, bytes: applyPrefixMask(parsed.bytes, prefix) };
+}
+/**
+ * Parse an IPv4 or IPv6 address string into raw bytes. Supports IPv6 `::`
+ * compression and IPv4-mapped tails (`::ffff:1.2.3.4`).
+ *
+ * @param input Address string; surrounding whitespace is trimmed.
+ * @returns The parsed address, or `undefined` when the input is not a valid
+ *   IP (callers treat unparseable addresses as a rejection, failing closed).
+ * @internal
+ */
+export function parseIp(input) {
+    const trimmed = input.trim();
+    if (trimmed.includes(":"))
+        return parseIPv6(trimmed);
+    return parseIPv4(trimmed);
+}
+function normalizeFamily(ip, family) {
+    if (ip.family === family)
+        return ip.bytes;
+    if (ip.family === 6 && family === 4) {
+        // IPv4-mapped IPv6 (::ffff:a.b.c.d) — accept as IPv4.
+        const b = ip.bytes;
+        const isMapped = b.slice(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff;
+        if (isMapped)
+            return b.slice(12);
+        return undefined;
+    }
+    return undefined;
+}
+function applyPrefixMask(bytes, prefix) {
+    const out = new Uint8Array(bytes);
+    const fullBytes = prefix >> 3;
+    const remaining = prefix - fullBytes * 8;
+    if (remaining > 0 && fullBytes < out.length) {
+        const mask = 0xff << (8 - remaining);
+        out[fullBytes] = out[fullBytes] & mask;
+    }
+    for (let i = fullBytes + (remaining > 0 ? 1 : 0); i < out.length; i++) {
+        out[i] = 0;
+    }
+    return out;
+}
+function parseIPv4(input) {
+    const parts = input.split(".");
+    if (parts.length !== 4)
+        return undefined;
+    const bytes = new Uint8Array(4);
+    for (let i = 0; i < 4; i++) {
+        const part = parts[i];
+        if (!/^\d{1,3}$/.test(part))
+            return undefined;
+        const n = Number.parseInt(part, 10);
+        if (n < 0 || n > 255)
+            return undefined;
+        bytes[i] = n;
+    }
+    return { bytes, family: 4 };
+}
+function parseIPv6(input) {
+    // Support IPv4-mapped tail (::ffff:1.2.3.4).
+    let working = input;
+    const lastColon = working.lastIndexOf(":");
+    if (lastColon !== -1 && working.slice(lastColon + 1).includes(".")) {
+        const v4 = parseIPv4(working.slice(lastColon + 1));
+        if (!v4)
+            return undefined;
+        const hi = (v4.bytes[0] << 8) | v4.bytes[1];
+        const lo = (v4.bytes[2] << 8) | v4.bytes[3];
+        working = working.slice(0, lastColon + 1) + hi.toString(16) + ":" + lo.toString(16);
+    }
+    const parts = working.split("::");
+    if (parts.length > 2)
+        return undefined;
+    const headGroups = parts[0] === "" ? [] : parts[0].split(":");
+    const tailGroups = parts.length === 2 && parts[1] !== "" ? parts[1].split(":") : [];
+    const explicit = headGroups.length + tailGroups.length;
+    if (explicit > 8)
+        return undefined;
+    if (parts.length === 1 && explicit !== 8)
+        return undefined;
+    const missing = parts.length === 2 ? 8 - explicit : 0;
+    const groups = [...headGroups, ...Array.from({ length: missing }, () => "0"), ...tailGroups];
+    if (groups.length !== 8)
+        return undefined;
+    const bytes = new Uint8Array(16);
+    for (let index = 0; index < 8; index++) {
+        const group = groups[index];
+        if (!/^[0-9a-fA-F]{1,4}$/.test(group))
+            return undefined;
+        const n = Number.parseInt(group, 16);
+        bytes[index * 2] = (n >> 8) & 0xff;
+        bytes[index * 2 + 1] = n & 0xff;
+    }
+    return { bytes, family: 6 };
+}

package/dist/ip-reputation.d.ts

@@ -125,6 +125,16 @@ export interface IpReputationOptions {
      * [1, 64]; validated at construction.
      */
     trustedHops?: number;
+    /**
+     * Declare WHICH proxies are yours: an IP/CIDR allowlist for the immediate
+     * peer's address. Forwarded headers are honoured only when the TCP socket
+     * actually talking to the adapter matches the list, so a direct-to-origin
+     * attacker cannot dodge the denylist with a spoofed XFF. Implies
+     * proxy-header trust at one hop unless {@link trustedHops} says otherwise;
+     * validated and compiled at construction. On peer-less edge platforms
+     * verification fails closed (forwarded identity ignored).
+     */
+    trustedProxies?: readonly string[];
     /**
      * `"block"` (default) throws a {@link ForbiddenError} on a match; `"log"`
      * only invokes {@link IpReputationOptions.onMatch} and lets the request

package/dist/ip-reputation.js

@@ -46,8 +46,8 @@
  */
 import { ForbiddenError } from "./errors.js";
 import { fetchGuard } from "./fetch-guard.js";
-import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
-import { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-restriction.js";
+import { resolveForwardedClientIp, resolveForwardedTrust, resolveTrustedProxyMatchers, } from "./conn-info.js";
+import { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-match.js";
 const DEFAULT_REFRESH_MS = 60 * 60_000;
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
 const DEFAULT_MESSAGE = "IP address not permitted";
@@ -119,8 +119,8 @@ export function urlFeed(url, opts = {}) {
  * `X-Forwarded-For` (falling back to `X-Real-IP`) — the spoof-resistant side
  * of the header; see {@link resolveForwardedClientIp}.
  */
-function forwardedIpResolver(hops) {
-    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
+function forwardedIpResolver(hops, trustedPeers) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops, trustedPeers);
 }
 function noIpResolver(_ctx) {
     return undefined;
@@ -158,7 +158,9 @@ export function ipReputation(opts) {
     }
     const message = opts.message ?? DEFAULT_MESSAGE;
     const hops = resolveForwardedTrust("ipReputation()", opts);
-    const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
+    const proxyMatchers = resolveTrustedProxyMatchers("ipReputation()", opts);
+    const resolveIp = opts.resolveIp ??
+        (hops !== undefined ? forwardedIpResolver(hops, proxyMatchers) : noIpResolver);
     // Last-known-good compiled denylist, one entry per feed so a single feed's
     // failed refresh doesn't drop the others.
     let compiled = opts.feeds.map((f) => ({ name: f.name, v4: [], v6: [] }));

package/dist/ip-restriction.d.ts

@@ -8,6 +8,8 @@
  * @since 0.19.0
  */
 import type { Hooks, IdentityGateContext } from "./types.js";
+export type { IpMatcher, ParsedIp } from "./ip-match.js";
+export { compileCidrMatcher, matchesMatcher, parseIp } from "./ip-match.js";
 /**
  * Options for {@link ipRestriction}. At least one of `allow` or `deny` must
  * be provided; supplying both runs deny-first then allow-otherwise (deny
@@ -58,6 +60,17 @@ export interface IpRestrictionOptions {
      * [1, 64]; validated at construction.
      */
     trustedHops?: number;
+    /**
+     * Declare WHICH proxies are yours: an IP/CIDR allowlist for the immediate
+     * peer's address. Forwarded headers are honoured only when the TCP socket
+     * actually talking to the adapter matches the list, so a direct-to-origin
+     * attacker cannot spoof an allow-listed IP or dodge a deny entry. Implies
+     * proxy-header trust at one hop unless {@link trustedHops} says otherwise;
+     * validated and compiled at construction. On peer-less edge platforms
+     * verification fails closed (the request is rejected, since no trustworthy
+     * IP remains).
+     */
+    trustedProxies?: readonly string[];
     /**
      * Response message when a request is rejected. Defaults to
      * `"IP address not permitted"`. Avoid echoing the client IP back —
@@ -65,22 +78,6 @@ export interface IpRestrictionOptions {
      */
     message?: string;
 }
-/** @internal Parsed IP address (shared with `fetchGuard()`). */
-export interface ParsedIp {
-    /** Big-endian address bytes: 4 bytes for IPv4, 16 for IPv6. */
-    bytes: Uint8Array;
-    /** Address family: `4` for IPv4, `6` for IPv6. */
-    family: 4 | 6;
-}
-/** @internal Compiled CIDR matcher (shared with `fetchGuard()`). */
-export interface IpMatcher {
-    /** Address family the matcher applies to: `4` or `6`. */
-    family: 4 | 6;
-    /** CIDR prefix length in bits (0-32 for IPv4, 0-128 for IPv6). */
-    prefix: number;
-    /** Network address bytes with all host bits masked to zero. */
-    bytes: Uint8Array;
-}
 /**
  * Block or allow requests by source IP / CIDR range. In direct Web-standard
  * runtimes, pass `resolveIp` from the adapter-specific connection metadata.
@@ -108,35 +105,3 @@ export interface IpMatcher {
  * @since 0.19.0
  */
 export declare function ipRestriction(opts: IpRestrictionOptions): Hooks;
-/**
- * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing
- * only the matcher's prefix bits. IPv4-mapped IPv6 addresses
- * (`::ffff:a.b.c.d`) are normalized so they match IPv4 matchers.
- *
- * @param ip Parsed client address from {@link parseIp}.
- * @param m Compiled matcher from {@link compileCidrMatcher}.
- * @returns `true` when the address is within the matcher's range.
- * @internal
- */
-export declare function matchesMatcher(ip: ParsedIp, m: IpMatcher): boolean;
-/**
- * Compile an IP or CIDR pattern (e.g. `"10.0.0.0/8"`, `"::1"`) into an
- * {@link IpMatcher}. A bare address gets a full-length prefix (/32 or /128);
- * host bits beyond the prefix are masked to zero.
- *
- * @param input IPv4/IPv6 address, optionally with a `/prefix` suffix.
- * @returns The compiled matcher used by {@link matchesMatcher}.
- * @throws Error when the address or CIDR prefix is invalid.
- * @internal
- */
-export declare function compileCidrMatcher(input: string): IpMatcher;
-/**
- * Parse an IPv4 or IPv6 address string into raw bytes. Supports IPv6 `::`
- * compression and IPv4-mapped tails (`::ffff:1.2.3.4`).
- *
- * @param input Address string; surrounding whitespace is trimmed.
- * @returns The parsed address, or `undefined` when the input is not a valid
- *   IP (callers treat unparseable addresses as a rejection, failing closed).
- * @internal
- */
-export declare function parseIp(input: string): ParsedIp | undefined;