midline-agent 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `midline-agent`, compiled from git history. Dates reflect commit dates, newest first.
 
+## 2026-09-21
+- feat: `midlineMiddleware({ trustProxy })` records the end user's IP from `X-Forwarded-For` when the server
+  sits behind a load balancer or CDN, instead of the proxy's address
+- feat: `captureIp: false` (env `MIDLINE_CAPTURE_IP=false`) stops the Node agent recording IP addresses;
+  the browser SDK's `captureIp: false` asks the Midline server not to keep the visitor's (0.7.0)
+
 ## 2026-09-20
 - feat: `midline-agent sourcemaps upload <dir> --release <name>` uploads a build's source maps to Midline
   so stack traces show original code. Authenticates with a project server API key; browser keys are refused

package/README.md

@@ -78,6 +78,21 @@ app.use(midlineErrorHandler()); // after your routes; passes the error on untouc
 app.listen(3000);
 ```
 
+#### Behind a load balancer or CDN
+
+By default the IP recorded for each request is Express's `req.ip`. Behind a load balancer that is the
+load balancer's address, not your user's. Tell the middleware how many proxies sit in front of your server
+and it reads the real address from `X-Forwarded-For`:
+
+```ts
+app.use(midlineMiddleware({ trustProxy: 1 })); // one load balancer or CDN in front
+```
+
+It counts that many hops in from the end of the chain, so an address a client puts in the header
+itself is ignored. Leave it unset if clients reach your server directly, or if you already set
+`app.set("trust proxy", …)` yourself. `trustProxy: true` believes the whole header, which is only safe when
+nothing can reach the server except through your proxies.
+
 ### NestJS
 
 ```ts
@@ -249,6 +264,7 @@ MidlineAgent.init({
   redactFields?: string[],        // added to the built-in list (maskFields still works)
   redactHeaders?: string[],
   captureConsole?: boolean,       // MIDLINE_CAPTURE_CONSOLE — also send what the process prints (off by default)
+  captureIp?: boolean,            // MIDLINE_CAPTURE_IP — record the caller's IP (on by default; false leaves it out)
 
   // Delivery
   flushIntervalMs?: number,       // default 1500
@@ -270,6 +286,7 @@ MidlineAgent.init({
 MIDLINE_API_KEY=...
 MIDLINE_ENDPOINT=https://api.usemidline.com
 # MIDLINE_CAPTURE_CONSOLE=true
+# MIDLINE_CAPTURE_IP=false
 
 # proxy mode
 TARGET_API_URL=http://localhost:4000
@@ -309,6 +326,45 @@ const app = await NestFactory.create(AppModule); // startup lines are captured f
 
 ---
 
+## IP addresses
+
+Request events carry the address of whoever made the request. It shows in the dashboard as the **IP address**
+column on Logs and on the Visitors page's **Recent visitors** table. Where it comes from depends on how you
+connect:
+
+| You use | Address recorded |
+| --- | --- |
+| Express or NestJS middleware | Express's `req.ip`. With `trustProxy`, the client read from `X-Forwarded-For`. |
+| Plain Node `http` middleware | The socket's peer. With `trustProxy`, the client read from `X-Forwarded-For`. |
+| Proxy mode | The socket's peer. With `trustForwardedHeaders`, the first `X-Forwarded-For` entry. |
+| Browser SDK | The address the Midline server saw the browser connect from. Nothing to configure, and any IP the page sends is ignored. |
+
+- **Behind a load balancer or CDN**, set `trustProxy` (see [Express](#behind-a-load-balancer-or-cdn)) or every request shows the
+  proxy's address instead of your user's.
+- **On your own machine** every caller is `::1` or `127.0.0.1`: the address a computer uses for itself. Real addresses
+  appear once real traffic reaches the service.
+- **A self-hosted Midline server** that sits behind a proxy needs `TRUST_PROXY=<number of proxies>` in its own
+  environment, so browser events record the visitor rather than the proxy. Left unset, `X-Forwarded-For` is ignored,
+  which stops a client from choosing the address that is recorded.
+
+### Not recording IP addresses
+
+An IP address can count as personal data. To keep it out entirely:
+
+```ts
+MidlineAgent.init({ apiKey: process.env.MIDLINE_API_KEY, captureIp: false }); // or MIDLINE_CAPTURE_IP=false
+```
+
+```ts
+Midline.init({ apiKey: "pk_…", captureIp: false }); // browser SDK
+```
+
+The Node agent drops the address in your process, so it is never sent. The browser SDK can only ask: the address is read by
+the Midline server, which then doesn't store it. A server that predates 0.7.0 ignores the request, so update a
+self-hosted server before relying on it. Events without an address show "—" in the dashboard.
+
+---
+
 ## Sensitive data
 
 Redaction happens **in your process, before an event is queued**. What's masked never reaches a
@@ -426,6 +482,7 @@ the browser will block the call's preflight.
 | `captureRequests` | `"failed"` | `"failed"` (4xx, 5xx, network errors), `"all"`, or `false`. Every call is a breadcrumb either way. |
 | `captureWebVitals` | `true` | Reported once, when the page is first hidden. |
 | `capturePageviews` | `true` | A `pageview` event on load and on every SPA route change (`pushState`/`replaceState`/`popstate`), tagged with a per-tab `sessionId` — what the dashboard's visitor and funnel views are built from. |
+| `captureIp` | `true` | The visitor's IP is read by the Midline server from the connection, not by the browser. `false` asks the server not to keep it. Needs a server that supports it (an older one ignores the request). |
 | `captureConsole` | `false` | `true` for `error` and `warn`, or a list of levels. Lines appear on the Terminal page. Opt-in because wrapped console calls show the SDK as their source in devtools. |
 | `tracePropagationTargets` | same origin | Strings match as URL prefixes (or path prefixes starting with `/`); RegExps match the full URL. |
 | `ignoreErrors`, `ignoreUrls` | `[]` | Strings match as substrings. |

package/dist/agent.js

@@ -363,7 +363,7 @@ class MidlineAgent {
             timestamp: validTimestamp(event.timestamp),
             // Clamped to the server's validation limits: one over-long field would
             // otherwise get every event rejected.
-            ip: clamp(event.ip, 64),
+            ip: config.captureIp ? clamp(event.ip, 64) : undefined,
             userAgent: clamp(event.userAgent, 512),
             service: clamp(config.serviceName, 128),
             environment: clamp(config.environment, 128),

package/dist/browser/client.js

@@ -82,6 +82,7 @@ function resolve(config) {
         consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
         captureWebVitals: config.captureWebVitals !== false,
         capturePageviews: config.capturePageviews !== false,
+        captureIp: config.captureIp !== false,
         tracePropagationTargets: config.tracePropagationTargets,
         ignoreErrors: config.ignoreErrors ?? [],
         ignoreUrls: config.ignoreUrls ?? [],
@@ -372,6 +373,9 @@ class BrowserClient {
             runtime: "browser",
             page: { url: this.pageUrl(), path: this.currentRoute() },
         };
+        // The IP is read server-side from the connection, so all the SDK can do is ask for it not to be kept.
+        if (!this.config.captureIp)
+            metadata.captureIp = false;
         if (this.user && (this.user.id || this.user.username))
             metadata.user = { ...this.user };
         if (Object.keys(this.tags).length)

package/dist/browser/types.d.ts

@@ -42,6 +42,13 @@ export interface MidlineBrowserConfig {
      * funnel view in the Midline dashboard is built from. Default true.
      */
     capturePageviews?: boolean;
+    /**
+     * Let Midline record the visitor's IP address. Default true. Your visitors' IP is read by the
+     * Midline server from the connection — the browser can't know it — so set this to false to ask
+     * the server not to keep it. Needs a Midline server that supports it; an older one ignores the
+     * request and keeps the address.
+     */
+    captureIp?: boolean;
     /**
      * Requests that get a W3C `traceparent` header, so the backend's midline-agent
      * links its request to this page. Strings match as URL prefixes (or path prefixes

package/dist/browser/version.d.ts

@@ -1,2 +1,2 @@
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-export declare const BROWSER_SDK_VERSION = "0.6.0";
+export declare const BROWSER_SDK_VERSION = "0.7.0";

package/dist/browser/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BROWSER_SDK_VERSION = void 0;
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-exports.BROWSER_SDK_VERSION = "0.6.0";
+exports.BROWSER_SDK_VERSION = "0.7.0";

package/dist/client-ip.d.ts

@@ -0,0 +1,20 @@
+import type { IncomingMessage } from "http";
+/**
+ * How many reverse proxies (load balancer, CDN) sit between the internet and this server.
+ * `true` trusts the whole `X-Forwarded-For` chain, so the leftmost entry is the client.
+ */
+export type TrustProxy = boolean | number;
+type WithExpressIp = IncomingMessage & {
+    ip?: string;
+};
+/**
+ * The address of whoever called this server.
+ *
+ * Without `trustProxy` this is Express's `req.ip` (which follows the app's own `trust proxy`
+ * setting) or the socket's peer. Behind a load balancer that is the load balancer, not the
+ * user — so with `trustProxy` the client is read from `X-Forwarded-For` instead, counting
+ * `trustProxy` hops in from the end of the chain: the entries a client prepends itself
+ * are ignored, and only what your own proxies appended is believed.
+ */
+export declare function clientIp(req: WithExpressIp, trustProxy?: TrustProxy): string | undefined;
+export {};

package/dist/client-ip.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientIp = clientIp;
+const tap_1 = require("./tap");
+/**
+ * The address of whoever called this server.
+ *
+ * Without `trustProxy` this is Express's `req.ip` (which follows the app's own `trust proxy`
+ * setting) or the socket's peer. Behind a load balancer that is the load balancer, not the
+ * user — so with `trustProxy` the client is read from `X-Forwarded-For` instead, counting
+ * `trustProxy` hops in from the end of the chain: the entries a client prepends itself
+ * are ignored, and only what your own proxies appended is believed.
+ */
+function clientIp(req, trustProxy) {
+    const peer = req.socket?.remoteAddress;
+    if (trustProxy === undefined || trustProxy === false || trustProxy === 0) {
+        return req.ip ?? peer;
+    }
+    const forwarded = ((0, tap_1.headerValue)(req.headers["x-forwarded-for"]) ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const chain = peer ? [...forwarded, peer] : forwarded;
+    if (!chain.length) {
+        return undefined;
+    }
+    const index = trustProxy === true ? 0 : Math.max(0, chain.length - 1 - trustProxy);
+    return chain[index];
+}

package/dist/config.d.ts

@@ -27,6 +27,7 @@ export interface ResolvedConfig {
     redactHeaders: string[];
     capture: ResolvedCapture;
     captureConsole: boolean;
+    captureIp: boolean;
     onError?: (message: string) => void;
     debug: boolean;
     flushIntervalMs: number;

package/dist/config.js

@@ -205,6 +205,7 @@ function resolveConfig(config) {
         redactHeaders: config.redactHeaders ?? [],
         capture: resolveCapture(config.capture),
         captureConsole: config.captureConsole ?? envFlag("MIDLINE_CAPTURE_CONSOLE") ?? false,
+        captureIp: config.captureIp ?? envFlag("MIDLINE_CAPTURE_IP") ?? true,
         onError: config.onError,
         debug: config.debug ?? envFlag("MIDLINE_DEBUG") ?? false,
         flushIntervalMs: positiveInt(config.flushIntervalMs, 1500, 50, 60000),

package/dist/esm/browser/client.js

@@ -76,6 +76,7 @@ function resolve(config) {
         consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
         captureWebVitals: config.captureWebVitals !== false,
         capturePageviews: config.capturePageviews !== false,
+        captureIp: config.captureIp !== false,
         tracePropagationTargets: config.tracePropagationTargets,
         ignoreErrors: config.ignoreErrors ?? [],
         ignoreUrls: config.ignoreUrls ?? [],
@@ -366,6 +367,9 @@ export class BrowserClient {
             runtime: "browser",
             page: { url: this.pageUrl(), path: this.currentRoute() },
         };
+        // The IP is read server-side from the connection, so all the SDK can do is ask for it not to be kept.
+        if (!this.config.captureIp)
+            metadata.captureIp = false;
         if (this.user && (this.user.id || this.user.username))
             metadata.user = { ...this.user };
         if (Object.keys(this.tags).length)

package/dist/esm/browser/version.js

@@ -1,2 +1,2 @@
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-export const BROWSER_SDK_VERSION = "0.6.0";
+export const BROWSER_SDK_VERSION = "0.7.0";

package/dist/middleware.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "http";
 import { MidlineAgent } from "./agent";
+import { TrustProxy } from "./client-ip";
 import { CaptureOptions } from "./types";
 export interface MidlineMiddlewareOptions {
     /** Defaults to the agent created by `MidlineAgent.init()`, looked up per request. */
@@ -8,6 +9,14 @@ export interface MidlineMiddlewareOptions {
     capture?: CaptureOptions;
     /** Return true to leave a request out, e.g. health checks. */
     ignore?: (req: IncomingMessage) => boolean;
+    /**
+     * How many reverse proxies (load balancer, CDN) sit in front of this server. Set it so the
+     * recorded IP is the end user's rather than the proxy's; `1` for one load balancer. Left unset,
+     * the address is Express's `req.ip`, which follows your app's own `trust proxy` setting.
+     * `true` trusts the whole `X-Forwarded-For` chain — only safe if nothing reaches the server
+     * except through your proxies, since a client could otherwise claim any address.
+     */
+    trustProxy?: TrustProxy;
 }
 /**
  * Records every request that passes through. Mount it before your routes.

package/dist/middleware.js

@@ -4,6 +4,7 @@ exports.midlineMiddleware = midlineMiddleware;
 const agent_1 = require("./agent");
 const breadcrumbs_1 = require("./breadcrumbs");
 const config_1 = require("./config");
+const client_ip_1 = require("./client-ip");
 const context_1 = require("./context");
 const tap_1 = require("./tap");
 /**
@@ -59,7 +60,7 @@ function observe(req, res, options, captureOverride) {
                 url,
                 statusCode,
                 durationMs: Number(process.hrtime.bigint() - started) / 1e6,
-                ip: req.ip ?? req.socket?.remoteAddress,
+                ip: (0, client_ip_1.clientIp)(req, options.trustProxy),
                 userAgent: (0, tap_1.headerValue)(req.headers["user-agent"]),
                 routeTemplate: typeof routePath === "string" ? `${req.baseUrl ?? ""}${routePath}` : undefined,
                 aborted,

package/dist/types.d.ts

@@ -62,6 +62,12 @@ export interface MidlineConfig {
      * startup lines. Off by default. Env fallback: `MIDLINE_CAPTURE_CONSOLE`.
      */
     captureConsole?: boolean;
+    /**
+     * Record the caller's IP address on request events. Default true. Set to false to
+     * leave it out entirely, e.g. where IPs count as personal data you don't want to hold:
+     * the address is dropped in this process and never sent. Env fallback: `MIDLINE_CAPTURE_IP`.
+     */
+    captureIp?: boolean;
     /** Set to false to keep the agent inert. Env fallback: `MIDLINE_ENABLED`. */
     enabled?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "midline-agent",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Midline \u2014 request, error and security monitoring for Node, and error, network, Web Vitals and pageview/visitor monitoring for browsers",
   "homepage": "https://usemidline.com",
   "main": "dist/index.js",

package/src/agent.ts

@@ -433,7 +433,7 @@ export class MidlineAgent {
       timestamp: validTimestamp(event.timestamp),
       // Clamped to the server's validation limits: one over-long field would
       // otherwise get every event rejected.
-      ip: clamp(event.ip, 64),
+      ip: config.captureIp ? clamp(event.ip, 64) : undefined,
       userAgent: clamp(event.userAgent, 512),
       service: clamp(config.serviceName, 128),
       environment: clamp(config.environment, 128),

package/src/browser/client.ts

@@ -59,6 +59,7 @@ interface Resolved {
   consoleLevels: ConsoleLevel[];
   captureWebVitals: boolean;
   capturePageviews: boolean;
+  captureIp: boolean;
   tracePropagationTargets?: Array<string | RegExp>;
   ignoreErrors: Array<string | RegExp>;
   ignoreUrls: Array<string | RegExp>;
@@ -126,6 +127,7 @@ function resolve(config: MidlineBrowserConfig): Resolved {
     consoleLevels: levels.filter((level) => level in CONSOLE_SEVERITY),
     captureWebVitals: config.captureWebVitals !== false,
     capturePageviews: config.capturePageviews !== false,
+    captureIp: config.captureIp !== false,
     tracePropagationTargets: config.tracePropagationTargets,
     ignoreErrors: config.ignoreErrors ?? [],
     ignoreUrls: config.ignoreUrls ?? [],
@@ -454,6 +456,8 @@ export class BrowserClient {
       runtime: "browser",
       page: { url: this.pageUrl(), path: this.currentRoute() },
     };
+    // The IP is read server-side from the connection, so all the SDK can do is ask for it not to be kept.
+    if (!this.config.captureIp) metadata.captureIp = false;
     if (this.user && (this.user.id || this.user.username)) metadata.user = { ...this.user };
     if (Object.keys(this.tags).length) metadata.tags = { ...this.tags };
     const nav = this.win.navigator;

package/src/browser/types.ts

@@ -48,6 +48,13 @@ export interface MidlineBrowserConfig {
    * funnel view in the Midline dashboard is built from. Default true.
    */
   capturePageviews?: boolean;
+  /**
+   * Let Midline record the visitor's IP address. Default true. Your visitors' IP is read by the
+   * Midline server from the connection — the browser can't know it — so set this to false to ask
+   * the server not to keep it. Needs a Midline server that supports it; an older one ignores the
+   * request and keeps the address.
+   */
+  captureIp?: boolean;
 
   /**
    * Requests that get a W3C `traceparent` header, so the backend's midline-agent

package/src/browser/version.ts

@@ -1,2 +1,2 @@
 /** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
-export const BROWSER_SDK_VERSION = "0.6.0";
+export const BROWSER_SDK_VERSION = "0.7.0";

package/src/client-ip.ts

@@ -0,0 +1,38 @@
+import type { IncomingMessage } from "http";
+import { headerValue } from "./tap";
+
+/**
+ * How many reverse proxies (load balancer, CDN) sit between the internet and this server.
+ * `true` trusts the whole `X-Forwarded-For` chain, so the leftmost entry is the client.
+ */
+export type TrustProxy = boolean | number;
+
+type WithExpressIp = IncomingMessage & { ip?: string };
+
+/**
+ * The address of whoever called this server.
+ *
+ * Without `trustProxy` this is Express's `req.ip` (which follows the app's own `trust proxy`
+ * setting) or the socket's peer. Behind a load balancer that is the load balancer, not the
+ * user — so with `trustProxy` the client is read from `X-Forwarded-For` instead, counting
+ * `trustProxy` hops in from the end of the chain: the entries a client prepends itself
+ * are ignored, and only what your own proxies appended is believed.
+ */
+export function clientIp(req: WithExpressIp, trustProxy?: TrustProxy): string | undefined {
+  const peer = req.socket?.remoteAddress;
+  if (trustProxy === undefined || trustProxy === false || trustProxy === 0) {
+    return req.ip ?? peer;
+  }
+
+  const forwarded = (headerValue(req.headers["x-forwarded-for"]) ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const chain = peer ? [...forwarded, peer] : forwarded;
+  if (!chain.length) {
+    return undefined;
+  }
+
+  const index = trustProxy === true ? 0 : Math.max(0, chain.length - 1 - trustProxy);
+  return chain[index];
+}

package/src/config.ts

@@ -37,6 +37,7 @@ export interface ResolvedConfig {
   redactHeaders: string[];
   capture: ResolvedCapture;
   captureConsole: boolean;
+  captureIp: boolean;
   onError?: (message: string) => void;
   debug: boolean;
   flushIntervalMs: number;
@@ -209,6 +210,7 @@ export function resolveConfig(config: MidlineConfig): ResolvedConfig {
     redactHeaders: config.redactHeaders ?? [],
     capture: resolveCapture(config.capture),
     captureConsole: config.captureConsole ?? envFlag("MIDLINE_CAPTURE_CONSOLE") ?? false,
+    captureIp: config.captureIp ?? envFlag("MIDLINE_CAPTURE_IP") ?? true,
     onError: config.onError,
     debug: config.debug ?? envFlag("MIDLINE_DEBUG") ?? false,
     flushIntervalMs: positiveInt(config.flushIntervalMs, 1500, 50, 60_000),

package/src/middleware.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "http";
 import { MidlineAgent } from "./agent";
 import { addBreadcrumb } from "./breadcrumbs";
 import { ResolvedCapture, resolveCapture } from "./config";
+import { clientIp, TrustProxy } from "./client-ip";
 import { createRequestContext, setRequestContext } from "./context";
 import { BodyTap, headerValue, isCompressed } from "./tap";
 import { CaptureOptions } from "./types";
@@ -13,6 +14,14 @@ export interface MidlineMiddlewareOptions {
   capture?: CaptureOptions;
   /** Return true to leave a request out, e.g. health checks. */
   ignore?: (req: IncomingMessage) => boolean;
+  /**
+   * How many reverse proxies (load balancer, CDN) sit in front of this server. Set it so the
+   * recorded IP is the end user's rather than the proxy's; `1` for one load balancer. Left unset,
+   * the address is Express's `req.ip`, which follows your app's own `trust proxy` setting.
+   * `true` trusts the whole `X-Forwarded-For` chain — only safe if nothing reaches the server
+   * except through your proxies, since a client could otherwise claim any address.
+   */
+  trustProxy?: TrustProxy;
 }
 
 /** The Express additions this reads when they exist. Plain `http` requests work too. */
@@ -87,7 +96,7 @@ function observe(
         url,
         statusCode,
         durationMs: Number(process.hrtime.bigint() - started) / 1e6,
-        ip: req.ip ?? req.socket?.remoteAddress,
+        ip: clientIp(req, options.trustProxy),
         userAgent: headerValue(req.headers["user-agent"]),
         routeTemplate: typeof routePath === "string" ? `${req.baseUrl ?? ""}${routePath}` : undefined,
         aborted,

package/src/types.ts

@@ -69,6 +69,12 @@ export interface MidlineConfig {
    * startup lines. Off by default. Env fallback: `MIDLINE_CAPTURE_CONSOLE`.
    */
   captureConsole?: boolean;
+  /**
+   * Record the caller's IP address on request events. Default true. Set to false to
+   * leave it out entirely, e.g. where IPs count as personal data you don't want to hold:
+   * the address is dropped in this process and never sent. Env fallback: `MIDLINE_CAPTURE_IP`.
+   */
+  captureIp?: boolean;
 
   /** Set to false to keep the agent inert. Env fallback: `MIDLINE_ENABLED`. */
   enabled?: boolean;

package/test/browser.test.js

@@ -277,6 +277,19 @@ test("browser: user, tags and a rate limit", async () => {
   });
 });
 
+test("browser: captureIp false asks the server not to keep the IP, and is otherwise silent", async () => {
+  await withSdk({}, async ({ sent }) => {
+    Midline.captureMessage("default");
+    await Midline.flush();
+    assert.equal("captureIp" in sent()[0].metadata, false);
+  });
+  await withSdk({ captureIp: false }, async ({ sent }) => {
+    Midline.captureMessage("private");
+    await Midline.flush();
+    assert.equal(sent()[0].metadata.captureIp, false);
+  });
+});
+
 test("browser: console capture is opt-in and never loops", async () => {
   await withSdk({ captureConsole: true }, async ({ win, sent }) => {
     win.console.error("payment failed", { token: "secret-token", amount: 5 });

package/test/middleware.test.js

@@ -176,3 +176,75 @@ test("plain node http servers work with the same middleware", async () => {
     await collector.close();
   }
 });
+
+test("express: the recorded IP is the end user's when trustProxy says how many proxies are in front", async () => {
+  const collector = await startSocketCollector();
+  const agent = new MidlineAgent({ apiKey: "ak_ip", endpoint: collector.url, flushIntervalMs: 60_000 });
+
+  const serve = async (options) => {
+    const app = express();
+    app.use(midlineMiddleware({ agent, ...options }));
+    app.get("/ping", (_req, res) => res.json({ ok: true }));
+    return listen(app);
+  };
+  const ipAfter = async (server, headers) => {
+    const before = collector.events().length;
+    await request(`http://127.0.0.1:${server.port}/ping`, { headers });
+    await waitFor(() => agent.queued > 0);
+    await agent.flush();
+    return collector.events().slice(before).pop().ip;
+  };
+
+  const plain = await serve({});
+  const oneProxy = await serve({ trustProxy: 1 });
+  const wholeChain = await serve({ trustProxy: true });
+
+  try {
+    // No trustProxy and no Express setting: the address the socket saw, never the header.
+    assert.match(await ipAfter(plain, { "x-forwarded-for": "203.0.113.50" }), /127\.0\.0\.1$/);
+    // One proxy in front: the address it appended, not what the client prepended.
+    assert.equal(await ipAfter(oneProxy, { "x-forwarded-for": "6.6.6.6, 203.0.113.50" }), "203.0.113.50");
+    assert.equal(await ipAfter(oneProxy, { "x-forwarded-for": "203.0.113.50" }), "203.0.113.50");
+    // No header at all: falls back to the socket peer.
+    assert.match(await ipAfter(oneProxy, {}), /127\.0\.0\.1$/);
+    assert.equal(await ipAfter(wholeChain, { "x-forwarded-for": "203.0.113.50, 10.0.0.1" }), "203.0.113.50");
+  } finally {
+    agent.close();
+    await Promise.all([plain.close(), oneProxy.close(), wholeChain.close(), collector.close()]);
+  }
+});
+
+test("express: captureIp false keeps the caller's address out of every event", async () => {
+  const collector = await startSocketCollector();
+  const record = async (options) => {
+    const agent = new MidlineAgent({ apiKey: "ak_noip", endpoint: collector.url, flushIntervalMs: 60_000, ...options });
+    const app = express();
+    app.use(midlineMiddleware({ agent }));
+    app.get("/ping", (_req, res) => res.json({ ok: true }));
+    const server = await listen(app);
+    try {
+      const before = collector.events().length;
+      await request(`http://127.0.0.1:${server.port}/ping`);
+      await waitFor(() => agent.queued > 0);
+      await agent.flush();
+      return collector.events().slice(before).pop();
+    } finally {
+      agent.close();
+      await server.close();
+    }
+  };
+
+  try {
+    assert.match((await record({})).ip, /127\.0\.0\.1$/);
+    assert.equal((await record({ captureIp: false })).ip, undefined);
+
+    process.env.MIDLINE_CAPTURE_IP = "false";
+    try {
+      assert.equal((await record({})).ip, undefined);
+    } finally {
+      delete process.env.MIDLINE_CAPTURE_IP;
+    }
+  } finally {
+    await collector.close();
+  }
+});