Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -5,24 +5,25 @@ import { getTrustedClientIp } from "./IpUtils";
const req = (headers: Record<string, string>) => new Request("https://app.example.test/", { headers });
describe("getTrustedClientIp", () => {
it("prefers the Cloudflare-set CF-Connecting-IP over a spoofable X-Forwarded-For", () => {
it("accepts Cloudflare's client header only behind a Cloudflare peer", () => {
expect(
getTrustedClientIp(req({ "x-forwarded-for": "1.2.3.4, 10.0.0.1", "cf-connecting-ip": "203.0.113.5" })),
getTrustedClientIp(req({ "x-forwarded-for": "1.2.3.4, 173.245.48.10", "cf-connecting-ip": "203.0.113.5" })),
).toBe("203.0.113.5");
});
it("never trusts X-Forwarded-For or X-Client-IP, even when they are the only headers present", () => {
expect(getTrustedClientIp(req({ "x-forwarded-for": "203.0.113.9" }))).toBe("unknown");
it("uses only the rightmost Traefik-appended XFF hop and ignores X-Client-IP", () => {
expect(getTrustedClientIp(req({ "x-forwarded-for": "1.2.3.4, 203.0.113.9" }))).toBe("203.0.113.9");
expect(getTrustedClientIp(req({ "x-client-ip": "203.0.113.9" }))).toBe("unknown");
});
it("falls back to True-Client-Ip then X-Real-IP", () => {
expect(getTrustedClientIp(req({ "true-client-ip": "198.51.100.7" }))).toBe("198.51.100.7");
it("never accepts True-Client-Ip without a verified peer and falls back to X-Real-IP", () => {
expect(getTrustedClientIp(req({ "true-client-ip": "198.51.100.7" }))).toBe("unknown");
expect(getTrustedClientIp(req({ "x-real-ip": "198.51.100.8" }))).toBe("198.51.100.8");
});
it("ignores non-IP trusted-header values and returns unknown when nothing valid is present", () => {
expect(getTrustedClientIp(req({ "cf-connecting-ip": "not-an-ip" }))).toBe("unknown");
expect(getTrustedClientIp(req({ "cf-connecting-ip": "203.0.113.7" }))).toBe("unknown");
expect(getTrustedClientIp(req({}))).toBe("unknown");
});
});
@@ -1,4 +1,5 @@
import isIP from "is-ip";
import { getTrustedProxyClientIp } from "@hivegrid/foundation/trusted-client-ip";
/**
* This is the list of headers, in order of preference, that will be used to
@@ -67,31 +68,19 @@ export function getClientIPAddress(requestOrHeaders: Request | Headers): string
}
/**
* Trusted client-IP headers, in order of preference. These are set by the
* edge/proxy and OVERWRITE any client-supplied value, so — unlike
* X-Forwarded-For's leftmost entry or X-Client-IP — they cannot be spoofed by
* the client. In this estate every public request passes through Cloudflare
* (proxied), which sets CF-Connecting-IP. X-Real-IP is the immediate reverse
* proxy (Traefik) hop as a fallback for non-Cloudflare paths.
*/
const trustedHeaderNames = Object.freeze(["CF-Connecting-IP", "True-Client-Ip", "X-Real-IP"] as const);
/**
* Get the client IP from a TRUSTED, proxy-set header only. Use this for
* security-sensitive decisions (rate limiting, abuse throttles) where an
* attacker must not be able to rotate their apparent IP by forging
* X-Forwarded-For. Returns "unknown" when no trusted header is present (e.g.
* local development without a proxy) so callers can still key a shared bucket.
* Resolve the client IP from the Traefik-appended peer and, only when that peer
* belongs to Cloudflare, CF-Connecting-IP. Returns "unknown" without a
* verifiable proxy peer so security-sensitive callers share a bounded bucket.
*/
export function getTrustedClientIp(requestOrHeaders: Request | Headers): string {
const headers = requestOrHeaders instanceof Request ? requestOrHeaders.headers : requestOrHeaders;
for (const headerName of trustedHeaderNames) {
const value = headers.get(headerName)?.trim();
if (value && isIP(value)) {
return value;
}
}
return "unknown";
return getTrustedProxyClientIp((name) => headers.get(name)) ?? "unknown";
}
/** Trusted client IP for persistence/audit call sites where no value is preferable to a synthetic marker. */
export function getTrustedClientIpOrNull(requestOrHeaders: Request | Headers): string | null {
const value = getTrustedClientIp(requestOrHeaders);
return value === "unknown" ? null : value;
}
function parseForwardedHeader(value: string | null): string | null {