Get "real" client IP, host, and protocol from trusted proxy (#53)

Author: zefir-git

src/Request.ts

@@ -19,7 +19,25 @@ export class Request<A> {
     public readonly method: Request.Method;
 
     /**
-     * The request URL.
+     * The original request address, as sent by the last peer. The {@link !URL} `protocol` is always set to `http:` and
+     * the `host` (and related) are always taken from the `HOST` environment variable or defaulted to `localhost`.
+     *
+     * If basic authentication is available to this request via headers, the `username` and `password` fields are
+     * available in the {@link URL} object.
+     */
+    public readonly originalUrl: Readonly<URL>;
+
+    /**
+     * The address requested by the client (first peer). If the request originated from a trusted proxy, this address
+     * will be constructed based on protocol and host provided by the proxy. If the proxy does not specify protocol,
+     * `http:` will be used as a default. If the proxy does not specify host (or the proxy is not trusted), will use the
+     * `Host` request header. If that is not specified either, will use the `HOST` environment variable or default to
+     * `localhost`.
+     *
+     * In short, this is, as closely as possible, the exact URL address the client requested.
+     *
+     * If basic authentication is available to this request via headers, the `username` and `password` fields are
+     * available in the {@link URL} object.
      */
     public readonly url: Readonly<URL>;
 
@@ -34,7 +52,14 @@ export class Request<A> {
     public readonly bodyStream: stream.Readable;
 
     /**
-     * IP address of request sender.
+     * The IP address of the request sender (last peer). This might be a proxy.
+     */
+    public readonly originalIp: IPv4 | IPv6;
+
+    /**
+     * IP address of client (first peer). If the request originated from a trusted proxy, this will be the client IP
+     * indicated by the proxy. Otherwise, if the proxy specifies no client IP, or the proxy is untrusted, this will be
+     * the proxy IP and equivalent to {@link Request#originalIp}.
      */
     public readonly ip: IPv4 | IPv6;
 
@@ -56,25 +81,31 @@ export class Request<A> {
     /**
      * Construct a new Request.
      * @param method See {@link Request#method}.
+     * @param originalUrl See {@link Request#originalUrl}.
      * @param url See {@link Request#url}.
      * @param headers See {@link Request#headers}.
      * @param bodyStream See {@link Request#bodyStream}.
+     * @param originalIp See {@link Request#originalIp}.
      * @param ip See {@link Request#ip}.
      * @param server See {@link Request#server}.
      * @throws {@link !URIError} If the request URL path name contains an invalid URI escape sequence.
      */
     public constructor(
         method: Request<A>["method"],
+        originalUrl: Request<A>["originalUrl"],
         url: Request<A>["url"],
         headers: Request<A>["headers"],
         bodyStream: Request<A>["bodyStream"],
+        originalIp: Request<A>["originalIp"],
         ip: Request<A>["ip"],
         server: Request<A>["server"]
     ) {
         this.method = method;
+        this.originalUrl = originalUrl;
         this.url = url;
         this.headers = headers;
         this.bodyStream = bodyStream;
+        this.originalIp = originalIp;
         this.ip = ip;
         this.server = server;
 
@@ -106,6 +137,18 @@ export class Request<A> {
      * @throws {@link Request.SocketClosedError} If the request socket was closed before the request could be handled.
      */
     public static incomingMessage<A>(incomingMessage: http.IncomingMessage, server: Server<A>) {
+        const remoteAddress = incomingMessage.socket.remoteAddress;
+        if (remoteAddress === undefined)
+            throw new Request.SocketClosedError();
+        const ip = IPAddress.fromString(remoteAddress);
+        const isTrustedProxy = server.trustedProxies.has(ip);
+
+        const headers = Request.headersFromNodeDict(incomingMessage.headers);
+
+        const proxy = isTrustedProxy ? this.getClientInfoFromTrustedProxy(headers) : {};
+
+        const clientIp = proxy.ip ?? ip;
+
         const auth =
             incomingMessage.headers.authorization
                 ?.toLowerCase()
@@ -116,18 +159,28 @@ export class Request<A> {
             ).toString()
             : null;
 
-        const url = `http://${auth ? `${auth}@` : ""}${process.env.HOST ?? "localhost"}${incomingMessage.url ?? "/"}`;
-        if (!URL.canParse(url))
+        const originalUrl = `http://${auth ? `${auth}@` : ""}${process.env.HOST ?? "localhost"}${incomingMessage.url ?? "/"}`;
+        if (!URL.canParse(originalUrl))
             throw new Request.BadUrlError(incomingMessage.url);
+        const clientUrl = new URL(originalUrl);
+        if (proxy.protocol !== undefined)
+            clientUrl.protocol = proxy.protocol + ":";
 
-        const headers = Request.headersFromNodeDict(incomingMessage.headers);
-
-        const remoteAddress = incomingMessage.socket.remoteAddress;
-        if (remoteAddress === undefined)
-            throw new Request.SocketClosedError();
+        const clientHost = proxy.host ?? headers.get("host");
+        if (clientHost !== null)
+            clientUrl.host = clientHost;
 
         try {
-            return new Request<A>(incomingMessage.method as Request.Method, new URL(url), headers, incomingMessage, IPAddress.fromString(remoteAddress), server);
+            return new Request<A>(
+                incomingMessage.method as Request.Method,
+                new URL(originalUrl),
+                clientUrl,
+                headers,
+                incomingMessage,
+                ip,
+                clientIp,
+                server
+            );
         }
         catch (e) {
             if (e instanceof URIError)
@@ -150,6 +203,77 @@ export class Request<A> {
         );
     }
 
+    /**
+     * Extract client IP, protocol, and host, from the information provided by a trusted proxy.
+     * @param headers The HTTP headers sent by a trusted proxy.
+     */
+    private static getClientInfoFromTrustedProxy(headers: Headers): {ip?: IPv4 | IPv6, host?: string, protocol?: "http" | "https"} {
+        if (headers.has("forwarded")) {
+            const forwarded = headers.get("forwarded")!.split(",")[0]!.trim();
+            const forwardedPairs = forwarded.split(";");
+            let ip: IPv4 | IPv6 | undefined = undefined;
+            let host: string | undefined = undefined;
+            let protocol: "http" | "https" | undefined = undefined;
+            for (const pair of forwardedPairs) {
+                let [key, value] = pair.split("=") as [key: string, value?: string];
+                key = key.trim().toLowerCase();
+                value = value?.trim();
+                if (value === undefined || value === "")
+                    continue;
+                if (value.startsWith("\"") && value.endsWith("\""))
+                    value = value.slice(1, -1);
+
+                switch (key) {
+                    case "for": {
+                        if (ip !== undefined)
+                            break;
+                        const [address] = value.split(":") as [ip: string, port: `${number}`];
+                        if (address.startsWith("[") && address.endsWith("]"))
+                            ip = IPv6.fromString(address.slice(1, -1));
+                        else
+                            ip = IPv4.fromString(address);
+                        break;
+                    }
+                    case "host": {
+                        if (host !== undefined)
+                            break;
+                        host = value;
+                        break;
+                    }
+                    case "proto": {
+                        if (protocol !== undefined)
+                            break;
+                        if (value !== "http" && value !== "https")
+                            break;
+                        protocol = value;
+                        break;
+                    }
+                }
+            }
+
+            return {ip, host, protocol};
+        }
+
+        let ip: IPv4 | IPv6 | undefined = undefined;
+        if (headers.has("x-forwarded-for")) {
+            const address = headers.get("x-forwarded-for")!.split(",")[0]!;
+            ip = IPAddress.fromString(address.trim());
+        }
+        else if (headers.has("x-real-ip")) {
+            ip = IPAddress.fromString(headers.get("x-real-ip")!.trim());
+        }
+
+        const host = headers.get("x-forwarded-host") ?? undefined;
+        const proto = headers.get("x-forwarded-proto") ?? undefined;
+        let protocol: "http" | "https" | undefined = undefined;
+        if (proto !== undefined && proto !== "http" && proto !== "https")
+            protocol = undefined;
+        else
+            protocol = proto;
+
+        return {ip, host, protocol};
+    }
+
     /**
      * Attempt to obtain authorisation for this request with one of the {@link Server}’s {@link Authenticator}s.
      * @returns `null` if the request lacks authorisation information.

src/Server.ts

@@ -1,3 +1,4 @@
+import {Network} from "@cldn/ip";
 import EventEmitter from "node:events";
 import http from "node:http";
 import packageJson from "./package.json" with {type: "json"};
@@ -35,6 +36,10 @@ class Server<A> extends EventEmitter<Server.Events> {
     private readonly port?: number;
     private readonly copyOrigin: boolean;
     private readonly handleConditionalRequests: boolean;
+    /**
+     * The network of remote addresses of proxies to trust/
+     */
+    public readonly trustedProxies: Network;
 
     /**
      * Create a new HTTP server.
@@ -54,6 +59,7 @@ class Server<A> extends EventEmitter<Server.Events> {
         this.copyOrigin = options?.copyOrigin ?? false;
         this.handleConditionalRequests = options?.handleConditionalRequests ?? true;
         this._authenticators = options?.authenticators ?? [];
+        this.trustedProxies = options?.trustedProxies ?? new Network();
 
         if (this.port !== undefined) this.listen(this.port).then();
 
@@ -237,6 +243,12 @@ namespace Server {
          * Authenticators for handling request authentication.
          */
         readonly authenticators?: Authenticator<A>[];
+
+        /**
+         * The network of trusted proxies. If specified, headers such as `Forwarded`, `X-Forwarded-For`, and `X-Real-IP`
+         * will be trusted and automatically processed.
+         */
+        readonly trustedProxies?: Network;
     }
 
     /**