fix(relay): key the per-client throttle on the pipeline-stamped client IP, not forwarding headers (#16975)

Merged via /merge-batch (2026-10-17 wave, round 3, maintainer PRs). Validated on a combined board (#16967 + #16975) over the current release/v3.8.52 tip: typecheck:core, open-sse typecheck, eslint on changed files, file-size, changelog-integrity, complexity, cognitive-complexity, env-doc-sync and agent-skills-sync all green; focused tests 70/70 (relay throttle + pipeline client-IP stamp + bifrost sidecar + relay completions errors + hosted-lane concurrency + check-workflows); api-typecheck, boundary 774/774, skills-sync Generated 0 also checked. Remaining CI reds are the inherited base-red #15306.
This commit is contained in:
Diego Rodrigues de Sa e Souza
2026-10-17 12:59:17 -03:00
committed by GitHub
parent ab04570812
commit 5413a24d7e
10 changed files with 437 additions and 19 deletions

View File

@@ -0,0 +1 @@
- **fix(relay):** the relay's per-(token, client) throttle now keys on the client address the authz pipeline resolves at the trust boundary — the connection's peer, or the client a loopback / private-network / Cloudflare / `OMNIROUTE_TRUSTED_PROXIES` proxy reported — forwarded to the route as a stamped header the pipeline strips from client input. Before, it keyed on `X-Forwarded-For` / `X-Real-IP` as sent, so a direct caller could reset the bucket by rotating the header (the per-token limit still applied). Clients behind the same reverse proxy keep separate buckets; when no stamp exists every caller of a token shares one bucket and the forwarding headers remain log-only.

View File

@@ -63,7 +63,7 @@ Unset secrets marked **Yes** are auto-generated on the first run (`JWT_SECRET`,
| `SOURCE_VERSION` | No | _(unset)_ | `next.config.mjs`, `scripts/build/assembleStandalone.mjs` | Second in the chain — set by PaaS builders (e.g. Heroku-style) as the deployed commit. |
| `NEXT_PUBLIC_SW_BUILD_ID` | No | _(derived)_ | `src/shared/components/PwaRegister.tsx` | Build-time public value the client uses to register `/sw.js?v=…`; derived from the two above, then the git SHA. |
| `OMNIROUTE_PEER_STAMP_TOKEN` | No (auto) | _(auto per boot)_ | `src/server/authz/policies/management.ts` | Per-process secret proving the trusted peer-IP stamp came from OmniRoute's own HTTP server (`scripts/dev/peer-stamp.mjs`). The authz middleware trusts request locality (loopback/LAN gating of LOCAL_ONLY routes) only when the stamp carries this token. Auto-generated each boot — leave unset; only pin it for multi-process setups that must share the stamp. |
| `OMNIROUTE_TRUSTED_PROXIES` | No | _(unset)_ | `scripts/dev/peer-stamp.mjs` | Comma-separated IPs or CIDR ranges of reverse proxies whose `X-Forwarded-For` / `X-Real-IP` the IP allow/deny list may believe, on top of loopback, private-network addresses and Cloudflare edges, which are always trusted. Needed only for a proxy on any other public address; otherwise that proxy's own address is what the filter judges. |
| `OMNIROUTE_TRUSTED_PROXIES` | No | _(unset)_ | `scripts/dev/peer-stamp.mjs` | Comma-separated IPs or CIDR ranges of reverse proxies whose `X-Forwarded-For` / `X-Real-IP` the IP allow/deny list may believe, on top of loopback, private-network addresses and Cloudflare edges, which are always trusted. Needed only for a proxy on any other public address; otherwise that proxy's own address is what the filter judges. The relay's per-client throttle (`/api/v1/relay/chat/completions`) keys on the same resolved client address, never on forwarding headers alone. |
### Generation Commands

View File

@@ -81,7 +81,7 @@ export async function OPTIONS() {
export async function POST(request: Request) {
const startTime = Date.now();
const clientIp = getClientIp(request);
const { forensic: clientIp, throttleKey } = getClientIp(request);
const userAgent = sanitizeForensicHeader(request.headers.get("user-agent"));
if (!BIFROST_ENABLED) {
@@ -161,7 +161,7 @@ export async function POST(request: Request) {
// 2a. Per-(token,IP) gate — mirrors the TypeScript relay fallback so the
// sidecar path does not weaken leaked-token abuse protection.
const ipCheck = checkIpRateLimit(token.id, clientIp);
const ipCheck = checkIpRateLimit(token.id, throttleKey);
if (!ipCheck.allowed) {
recordRelayUsage(token.id, {
requestId: request.headers.get("x-request-id") || undefined,

View File

@@ -1,4 +1,8 @@
import { createHash } from "node:crypto";
import {
AUTHZ_HEADER_TRUSTED_CLIENT_IP,
AUTHZ_HEADER_TRUSTED_PEER_IP,
} from "@/server/authz/headers";
// Forensic-only sanitization: client IP / user-agent come from untrusted
// headers and feed recordRelayUsage() rows. Strip CR/LF so a malicious header
@@ -8,12 +12,44 @@ export function sanitizeForensicHeader(value: string | null, max = 256): string
return value.replace(/[\r\n]+/g, " ").slice(0, max);
}
export function getClientIp(request: Request): string {
return sanitizeForensicHeader(
request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
request.headers.get("x-real-ip") ||
null
);
/**
* The client address the relay works with.
*
* - `throttleKey` feeds the per-(token, client) throttle. It is the address the authz
* pipeline stamped after resolving it at the trust boundary: the TCP peer on a direct
* connection, or the client a trusted proxy reported for it (so clients behind one reverse
* proxy are told apart), falling back to the stamped socket peer. When neither stamp exists
* (plain `next dev` without the custom server, or no stamp token) every caller of a token
* shares ONE bucket: X-Forwarded-For / X-Real-IP are client-controlled on a direct
* connection, so keying on them would let a caller reset the bucket by rotating the header.
* The DB-backed per-token limit is the real control in that case.
* - `forensic` is the best-known address for recordRelayUsage() rows: the trusted value when
* stamped, otherwise the forwarding headers — log-only, never a decision input.
*/
export interface RelayClientIp {
throttleKey: string;
forensic: string;
}
/** Throttle key shared by every caller whose address the server could not vouch for. */
export const UNTRUSTED_CLIENT_BUCKET = "untrusted";
export function getClientIp(request: Request): RelayClientIp {
const trusted =
request.headers.get(AUTHZ_HEADER_TRUSTED_CLIENT_IP) ||
request.headers.get(AUTHZ_HEADER_TRUSTED_PEER_IP);
if (trusted) {
const ip = sanitizeForensicHeader(trusted);
return { throttleKey: ip, forensic: ip };
}
return {
throttleKey: UNTRUSTED_CLIENT_BUCKET,
forensic: sanitizeForensicHeader(
request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
request.headers.get("x-real-ip") ||
null
),
};
}
export function extractToken(request: Request): string | null {
@@ -41,7 +77,10 @@ export function hashToken(token: string): string {
const RELAY_IP_PER_MINUTE = Number(process.env.RELAY_IP_PER_MINUTE || "30");
const ipBuckets = new Map<string, { count: number; windowStart: number }>();
export function checkIpRateLimit(tokenId: string, ip: string): { allowed: boolean; resetIn: number } {
export function checkIpRateLimit(
tokenId: string,
ip: string
): { allowed: boolean; resetIn: number } {
if (!Number.isFinite(RELAY_IP_PER_MINUTE) || RELAY_IP_PER_MINUTE <= 0) {
return { allowed: true, resetIn: 0 };
}

View File

@@ -208,7 +208,7 @@ export async function OPTIONS() {
async function postHandler(request: Request) {
const startTime = Date.now();
const clientIp = getClientIp(request);
const { forensic: clientIp, throttleKey } = getClientIp(request);
const userAgent = sanitizeForensicHeader(request.headers.get("user-agent"));
try {
@@ -247,7 +247,7 @@ async function postHandler(request: Request) {
}
// 2a. Per-(token,IP) gate — bounds the blast radius of a leaked token.
const ipCheck = checkIpRateLimit(token.id, clientIp);
const ipCheck = checkIpRateLimit(token.id, throttleKey);
if (!ipCheck.allowed) {
recordRelayUsage(token.id, {
requestId: request.headers.get("x-request-id") || undefined,

View File

@@ -93,6 +93,21 @@ export const AUTHZ_HEADER_PEER_LOCALITY = "x-omniroute-peer-locality";
*/
export const AUTHZ_HEADER_TRUSTED_PEER_IP = "x-omniroute-trusted-peer-ip";
/**
* The resolved client address, stamped by the pipeline AFTER verifying the
* token-stamped CLIENT_IP_HEADER: the TCP peer on a direct connection, or the
* client a trusted proxy reported for it (loopback / private-network /
* Cloudflare proxies and OMNIROUTE_TRUSTED_PROXIES — see peer-stamp.mjs). This
* is what the IP allow/deny list judges, and what route handlers that key a
* per-client control on "who is calling" (e.g. the relay throttle) must read
* instead of X-Forwarded-For / X-Real-IP, which a direct caller controls.
* Unlike AUTHZ_HEADER_TRUSTED_PEER_IP it does not collapse every client behind
* a reverse proxy into the proxy's address. Set only when the stamp token is
* configured and validates; absent otherwise. Stripped from incoming requests
* like all other trusted headers.
*/
export const AUTHZ_HEADER_TRUSTED_CLIENT_IP = "x-omniroute-trusted-client-ip";
/**
* Headers the pipeline must NEVER trust on incoming requests. They are
* stripped before route classification to prevent header-spoofing attacks.
@@ -105,4 +120,5 @@ export const AUTHZ_TRUSTED_HEADERS: ReadonlyArray<string> = [
AUTHZ_HEADER_AUTH_SCOPES,
AUTHZ_HEADER_PEER_LOCALITY,
AUTHZ_HEADER_TRUSTED_PEER_IP,
AUTHZ_HEADER_TRUSTED_CLIENT_IP,
];

View File

@@ -36,6 +36,7 @@ import {
PEER_IP_HEADER,
VIA_PROXY_HEADER,
CLIENT_IP_HEADER,
AUTHZ_HEADER_TRUSTED_CLIENT_IP,
} from "./headers";
import type { AuthSubject, RouteClass, RouteClassification } from "./types";
import type { AuthOutcome, RoutePolicy } from "./context";
@@ -342,6 +343,18 @@ export async function runAuthzPipeline(
if (trustedPeerIp) {
requestHeaders.set(AUTHZ_HEADER_TRUSTED_PEER_IP, trustedPeerIp);
}
// The server stamps the client address to judge (the peer, or what a trusted proxy
// reported for it). Forward it too, so route handlers that key a per-client control on
// "who is calling" (e.g. the relay throttle) read the same resolution as the IP filter
// below — a direct caller cannot move it with X-Forwarded-For, and clients behind one
// reverse proxy are still told apart. Requests without that stamp get no header.
const stampedClientIp = resolveStampedPeer(
request.headers.get(CLIENT_IP_HEADER),
process.env.OMNIROUTE_PEER_STAMP_TOKEN
);
if (stampedClientIp) {
requestHeaders.set(AUTHZ_HEADER_TRUSTED_CLIENT_IP, stampedClientIp);
}
// Local CLI-token auth is decided centrally above. Preserve that trusted
// decision for route-level requireManagementAuth without forwarding the
// machine token itself: custom client auth headers are stripped before the
@@ -384,12 +397,8 @@ export async function runAuthzPipeline(
request.headers.get(VIA_PROXY_HEADER),
process.env.OMNIROUTE_PEER_STAMP_TOKEN
);
// The server stamps the client address to judge (the peer, or what a trusted proxy
// reported for it). Requests without that stamp keep the earlier rule.
const stampedClientIp = resolveStampedPeer(
request.headers.get(CLIENT_IP_HEADER),
process.env.OMNIROUTE_PEER_STAMP_TOKEN
);
// The stamped client address (resolved above) is judged; requests without that stamp
// keep the earlier rule.
const ipVerdict = checkRequestIP(request, stampedClientIp ?? (viaProxy ? null : trustedPeerIp));
if (!ipVerdict.allowed) {
const blocked = NextResponse.json(

View File

@@ -178,7 +178,10 @@ test("bifrost route: shared relay security helpers sanitize forwarded client met
},
});
assert.equal(getClientIp(req), "198.51.100.8");
// Forwarding headers are forensic-only: the throttle must not key on them.
const clientIp = getClientIp(req);
assert.equal(clientIp.forensic, "198.51.100.8");
assert.notEqual(clientIp.throttleKey, "198.51.100.8");
assert.equal(sanitizeForensicHeader("ua\r\nforged"), "ua forged");
});

View File

@@ -0,0 +1,199 @@
// The relay's per-(token, client) throttle must key on a client address the server vouches for —
// the one the authz pipeline stamps after resolving the TCP peer or a trusted proxy's report —
// never on X-Forwarded-For / X-Real-IP, which a direct caller controls and can rotate to reset
// the bucket. Those headers stay useful only as the best-known address for the forensic log row
// when no stamp exists.
import { test } from "node:test";
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
// Isolated DATA_DIR even when run without the suite preamble; a tiny per-client ceiling so the
// bucket semantics can be observed in three requests (read once at module load).
process.env.DATA_DIR ||= fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-relay-throttle-"));
process.env.RELAY_IP_PER_MINUTE = "2";
const relaySecurity =
await import("../../../../src/app/api/v1/relay/chat/completions/relaySecurity.ts");
const authzHeaders = await import("../../../../src/server/authz/headers.ts");
const { getDbInstance } = await import("../../../../src/lib/db/core.ts");
const { getRelayLogs } = await import("../../../../src/lib/db/relayProxies.ts");
const { getClientIp, checkIpRateLimit } = relaySecurity;
// Wire names pinned on purpose: the route and the pipeline must agree on them.
const TRUSTED_CLIENT_IP = "x-omniroute-trusted-client-ip";
const TRUSTED_PEER_IP = "x-omniroute-trusted-peer-ip";
function relayRequest(headers: Record<string, string>) {
return new Request("http://localhost/api/v1/relay/chat/completions", { headers });
}
function freshTokenId() {
return `relay-throttle-${Date.now()}-${Math.random().toString(16).slice(2)}`;
}
test("the relay reads the client address through the pipeline's stamped header", () => {
assert.equal(authzHeaders.AUTHZ_HEADER_TRUSTED_CLIENT_IP, TRUSTED_CLIENT_IP);
});
test("getClientIp: forwarding headers from a direct caller never become the throttle key", () => {
const a = getClientIp(relayRequest({ "x-forwarded-for": "198.51.100.1, 10.0.0.2" }));
const b = getClientIp(relayRequest({ "x-forwarded-for": "198.51.100.2" }));
const c = getClientIp(relayRequest({ "x-real-ip": "198.51.100.3" }));
// Same bucket for every unstamped caller of a token — the per-token DB limit is the control.
assert.equal(a.throttleKey, b.throttleKey);
assert.equal(b.throttleKey, c.throttleKey);
assert.notEqual(a.throttleKey, "198.51.100.1");
// The forensic row still carries the best-known address.
assert.equal(a.forensic, "198.51.100.1");
assert.equal(b.forensic, "198.51.100.2");
assert.equal(c.forensic, "198.51.100.3");
assert.equal(getClientIp(relayRequest({})).forensic, "unknown");
});
test("getClientIp: the stamped client address wins over the peer stamp and forwarding headers", () => {
const resolved = getClientIp(
relayRequest({
[TRUSTED_CLIENT_IP]: "203.0.113.5",
[TRUSTED_PEER_IP]: "10.0.0.2",
"x-forwarded-for": "198.51.100.1",
})
);
assert.equal(resolved.throttleKey, "203.0.113.5");
assert.equal(resolved.forensic, "203.0.113.5");
});
test("getClientIp: falls back to the stamped socket peer when only that stamp exists", () => {
const resolved = getClientIp(
relayRequest({ [TRUSTED_PEER_IP]: "10.0.0.2", "x-forwarded-for": "198.51.100.1" })
);
assert.equal(resolved.throttleKey, "10.0.0.2");
assert.equal(resolved.forensic, "10.0.0.2");
});
test("getClientIp: a stamped address is capped like any logged header", () => {
const resolved = getClientIp(relayRequest({ [TRUSTED_CLIENT_IP]: "a".repeat(300) }));
assert.equal(resolved.forensic.length, 256);
assert.equal(resolved.throttleKey, resolved.forensic);
});
test("throttle: rotating X-Forwarded-For shares one bucket per token", () => {
const tokenId = freshTokenId();
const keyFor = (xff: string) => getClientIp(relayRequest({ "x-forwarded-for": xff })).throttleKey;
assert.equal(checkIpRateLimit(tokenId, keyFor("198.51.100.1")).allowed, true);
assert.equal(checkIpRateLimit(tokenId, keyFor("198.51.100.2")).allowed, true);
assert.equal(checkIpRateLimit(tokenId, keyFor("198.51.100.3")).allowed, false, "3rd request");
});
test("throttle: distinct stamped client addresses get separate buckets", () => {
const tokenId = freshTokenId();
const keyFor = (ip: string) => getClientIp(relayRequest({ [TRUSTED_CLIENT_IP]: ip })).throttleKey;
assert.equal(checkIpRateLimit(tokenId, keyFor("203.0.113.1")).allowed, true);
assert.equal(checkIpRateLimit(tokenId, keyFor("203.0.113.1")).allowed, true);
assert.equal(checkIpRateLimit(tokenId, keyFor("203.0.113.2")).allowed, true, "other client");
assert.equal(checkIpRateLimit(tokenId, keyFor("203.0.113.2")).allowed, true, "other client");
assert.equal(checkIpRateLimit(tokenId, keyFor("203.0.113.1")).allowed, false, "1st client 3rd");
assert.equal(checkIpRateLimit(tokenId, keyFor("203.0.113.2")).allowed, false, "2nd client 3rd");
});
// ── Route level ──────────────────────────────────────────────────────────────
// The token only allows a model the request never asks for, so requests the throttle lets
// through end in a cheap 403 after the gate — no upstream involved. The gate's own answer is the
// 429 scoped "ip".
async function postRelay(rawToken: string, headers: Record<string, string>) {
const { POST } = await import("../../../../src/app/api/v1/relay/chat/completions/route.ts");
return POST(
new Request("http://localhost/api/v1/relay/chat/completions", {
method: "POST",
headers: {
authorization: `Bearer ${rawToken}`,
"content-type": "application/json",
...headers,
},
body: JSON.stringify({
model: "some-other-model",
messages: [{ role: "user", content: "hi" }],
}),
})
);
}
// Seeded like the sibling relay tests: createRelayToken() hashes through a CommonJS `require`
// that the ESM test runtime does not provide.
function seedToken(name: string) {
const id = `rl_test_${Date.now()}_${Math.random().toString(16).slice(2)}`;
const rawToken = `relay_${name}_${Math.random().toString(16).slice(2)}`;
const now = Math.floor(Date.now() / 1000);
getDbInstance()
.prepare(
`INSERT INTO relay_tokens (id, name, token_hash, token_prefix, description, combo_id,
allowed_models, max_tokens_per_request, max_requests_per_minute, max_requests_per_day,
max_cost_per_day, enabled, created_at, updated_at, expires_at, metadata)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?)`
)
.run(
id,
name,
createHash("sha256").update(rawToken).digest("hex"),
"rl_test",
"",
null,
JSON.stringify(["relay-throttle-only-model"]),
128000,
60,
10000,
0,
now,
now,
null,
"{}"
);
return { id, rawToken };
}
test("relay route: a direct caller cannot reset the throttle by rotating X-Forwarded-For", async () => {
const token = seedToken("relay-throttle-rotating-xff");
const first = await postRelay(token.rawToken, { "x-forwarded-for": "198.51.100.1" });
const second = await postRelay(token.rawToken, { "x-forwarded-for": "198.51.100.2" });
const third = await postRelay(token.rawToken, { "x-forwarded-for": "198.51.100.3" });
assert.equal(first.status, 403);
assert.equal(second.status, 403);
assert.equal(third.status, 429, "third request from a 'new' forwarded address");
assert.equal(third.headers.get("X-RateLimit-Scope"), "ip");
// The forensic row keeps the best-known address for the operator.
const [latest] = getRelayLogs(token.id, 1);
assert.equal(latest.status, "rate_limited");
assert.equal(latest.client_ip, "198.51.100.3");
});
test("relay route: clients the pipeline stamped apart get separate buckets", async () => {
const token = seedToken("relay-throttle-stamped-clients");
const stamped = (ip: string, xff: string) => ({
[TRUSTED_CLIENT_IP]: ip,
"x-forwarded-for": xff,
});
assert.equal((await postRelay(token.rawToken, stamped("203.0.113.1", "1.1.1.1"))).status, 403);
assert.equal((await postRelay(token.rawToken, stamped("203.0.113.1", "2.2.2.2"))).status, 403);
// Another client behind the same proxy is not collapsed into the first one's bucket.
assert.equal((await postRelay(token.rawToken, stamped("203.0.113.2", "3.3.3.3"))).status, 403);
const limited = await postRelay(token.rawToken, stamped("203.0.113.1", "4.4.4.4"));
assert.equal(limited.status, 429);
assert.equal(limited.headers.get("X-RateLimit-Scope"), "ip");
const [latest] = getRelayLogs(token.id, 1);
assert.equal(latest.status, "rate_limited");
assert.equal(latest.client_ip, "203.0.113.1", "forensic row carries the trusted address");
});

View File

@@ -0,0 +1,151 @@
// The authz pipeline already resolves a trusted-proxy-aware client address for the IP allow/deny
// list: the TCP peer on a direct connection, or the client a trusted proxy reported for it
// (scripts/dev/peer-stamp.mjs). Route handlers that key a per-client control on "who is calling"
// (the relay throttle) must read that same resolution through a pipeline-stamped header — one the
// pipeline strips from client input first, so a caller can neither pre-set it nor move it with
// X-Forwarded-For on a direct connection.
import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { NextRequest } from "next/server";
import { wrapRequestListenerWithPeerStamp } from "../../../scripts/dev/peer-stamp.mjs";
const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-trusted-client-ip-"));
const ORIGINAL_DATA_DIR = process.env.DATA_DIR;
process.env.DATA_DIR = TEST_DATA_DIR;
process.env.JWT_SECRET = "test-secret-trusted-client-ip";
const core = await import("../../../src/lib/db/core.ts");
const pipeline = await import("../../../src/server/authz/pipeline.ts");
const authzHeaders = await import("../../../src/server/authz/headers.ts");
// The wire name is pinned on purpose: route handlers and the pipeline must agree on it.
const TRUSTED_CLIENT_IP = "x-omniroute-trusted-client-ip";
const RELAY_PATH = "/api/v1/relay/chat/completions";
const ORIGINAL_STAMP_TOKEN = process.env.OMNIROUTE_PEER_STAMP_TOKEN;
const ORIGINAL_TRUSTED_PROXIES = process.env.OMNIROUTE_TRUSTED_PROXIES;
const ORIGINAL_REQUIRE_API_KEY = process.env.REQUIRE_API_KEY;
function restoreEnv(name: string, value: string | undefined) {
if (value === undefined) delete process.env[name];
else process.env[name] = value;
}
test.after(() => {
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
restoreEnv("DATA_DIR", ORIGINAL_DATA_DIR);
restoreEnv("OMNIROUTE_PEER_STAMP_TOKEN", ORIGINAL_STAMP_TOKEN);
restoreEnv("OMNIROUTE_TRUSTED_PROXIES", ORIGINAL_TRUSTED_PROXIES);
restoreEnv("REQUIRE_API_KEY", ORIGINAL_REQUIRE_API_KEY);
});
test.beforeEach(() => {
core.resetDbInstance();
fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
process.env.OMNIROUTE_PEER_STAMP_TOKEN = "stamp-tok";
delete process.env.OMNIROUTE_TRUSTED_PROXIES;
delete process.env.REQUIRE_API_KEY;
});
const DIRECT_CLIENT = "203.0.113.10";
const PROXIED_CLIENT = "198.51.100.7";
const FORGED = "192.0.2.66";
// What the custom server does before the request reaches the pipeline: stamp the socket peer.
function stampedRequest(peer: string, headers: Record<string, string>) {
const stamped: Record<string, string> = {};
wrapRequestListenerWithPeerStamp((req: { headers: Record<string, string> }) => {
Object.assign(stamped, req.headers);
})({ headers: { ...headers }, socket: { remoteAddress: peer } } as never, {} as never);
return new NextRequest(`http://localhost${RELAY_PATH}`, { method: "POST", headers: stamped });
}
// A request that never went through the custom server (plain `next dev`, or a forger that
// skipped it): no stamps at all, only what the client sent.
function unstampedRequest(headers: Record<string, string>) {
return new NextRequest(`http://localhost${RELAY_PATH}`, { method: "POST", headers });
}
// The headers the route handler receives after the pipeline ran.
async function forwardedHeaders(request: NextRequest): Promise<Headers> {
const res = await pipeline.runAuthzPipeline(request, { enforce: true });
assert.equal(res.headers.get("x-middleware-next"), "1", `pipeline blocked: ${res.status}`);
const forwarded = new Headers();
for (const [name, value] of res.headers) {
if (name.startsWith("x-middleware-request-")) {
forwarded.set(name.slice("x-middleware-request-".length), value);
}
}
return forwarded;
}
test("the stamped client-address header is one the pipeline never trusts from a client", () => {
assert.equal(authzHeaders.AUTHZ_HEADER_TRUSTED_CLIENT_IP, TRUSTED_CLIENT_IP);
assert.ok(
authzHeaders.AUTHZ_TRUSTED_HEADERS.includes(TRUSTED_CLIENT_IP),
"must be in AUTHZ_TRUSTED_HEADERS so client-supplied values are stripped before stamping"
);
});
test("a direct client's X-Forwarded-For does not change the forwarded client address", async () => {
for (const forged of [
{ "x-forwarded-for": FORGED },
{ "x-real-ip": FORGED },
{ "x-forwarded-for": `${FORGED}, ${PROXIED_CLIENT}` },
]) {
const forwarded = await forwardedHeaders(stampedRequest(DIRECT_CLIENT, forged));
assert.equal(forwarded.get(TRUSTED_CLIENT_IP), DIRECT_CLIENT, Object.keys(forged)[0]);
}
});
test("behind a trusted proxy the forwarded client address is the one the proxy reported", async () => {
// Loopback proxy (nginx / Caddy on the same host).
let forwarded = await forwardedHeaders(
stampedRequest("127.0.0.1", { "x-forwarded-for": PROXIED_CLIENT })
);
assert.equal(forwarded.get(TRUSTED_CLIENT_IP), PROXIED_CLIENT);
// Two clients behind the same proxy are told apart — they must not collapse into the proxy.
forwarded = await forwardedHeaders(
stampedRequest("127.0.0.1", { "x-forwarded-for": DIRECT_CLIENT })
);
assert.equal(forwarded.get(TRUSTED_CLIENT_IP), DIRECT_CLIENT);
// A proxy on a public address counts only once the operator names it.
const publicProxy = "198.51.100.200";
forwarded = await forwardedHeaders(
stampedRequest(publicProxy, { "x-forwarded-for": PROXIED_CLIENT })
);
assert.equal(forwarded.get(TRUSTED_CLIENT_IP), publicProxy, "unnamed public proxy");
process.env.OMNIROUTE_TRUSTED_PROXIES = "198.51.100.0/24";
forwarded = await forwardedHeaders(
stampedRequest(publicProxy, { "x-forwarded-for": PROXIED_CLIENT })
);
assert.equal(forwarded.get(TRUSTED_CLIENT_IP), PROXIED_CLIENT, "named public proxy");
});
test("a client cannot pre-set the stamped client address", async () => {
// Through the custom server: the injected value is stripped and the real one stamped over it.
let forwarded = await forwardedHeaders(
stampedRequest(DIRECT_CLIENT, { [TRUSTED_CLIENT_IP]: FORGED })
);
assert.equal(forwarded.get(TRUSTED_CLIENT_IP), DIRECT_CLIENT);
// Without the custom server: no stamp means no header reaches the route — never the client's.
forwarded = await forwardedHeaders(
unstampedRequest({ [TRUSTED_CLIENT_IP]: FORGED, "x-forwarded-for": FORGED })
);
assert.equal(forwarded.has(TRUSTED_CLIENT_IP), false, "unstamped request");
// A forged server stamp with the wrong token is not a stamp.
forwarded = await forwardedHeaders(
unstampedRequest({ "x-omniroute-client-ip": `wrong-token|${FORGED}` })
);
assert.equal(forwarded.has(TRUSTED_CLIENT_IP), false, "forged stamp token");
});