@tumbaland/backend-core 1.24.0 → 1.25.0

package/dist/app/createBaseApp.d.ts

@@ -18,6 +18,12 @@ export interface CreateBaseAppOptions {
     tracing?: boolean;
     /** Use requestLoggerWithMetrics (adds Prometheus histograms) instead of the plain requestLogger. Default true. */
     metrics?: boolean;
+    /**
+     * Value for Express's `trust proxy`. Defaults to trusting private/loopback
+     * addresses — see the note on tumbaland-proxy below. Pass `false` for a
+     * service exposed directly to clients with no proxy in front of it.
+     */
+    trustProxy?: Parameters<Express['set']>[1];
 }
 /**
  * Assembles the middleware stack every service was hand-rolling in its own
@@ -39,6 +45,24 @@ export interface CreateBaseAppOptions {
  * Services with non-standard body parsing (a webhook needing the raw body,
  * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
  * false` and mount those themselves at the exact point they need to.
+ *
+ * `trust proxy` is on by default because nothing here is reached directly:
+ * every service sits behind tumbaland-proxy, which sets `X-Forwarded-For`.
+ * Left at Express's default (`false`) that header is ignored, which
+ * express-rate-limit reports as `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` — and
+ * it is right to: the limiter would then key every request in the cluster on
+ * the proxy's own container IP, so one busy client could exhaust the window
+ * for everyone.
+ *
+ * The value is `loopback, linklocal, uniquelocal` (private ranges) rather
+ * than a hop count, because the chain length differs per ingress path: a
+ * direct hit arrives as `client` + the proxy's own socket address, while
+ * traffic through the Cloudflare tunnel arrives as `client, 127.0.0.1` (the
+ * local cloudflared) + that same socket address. Express walks the chain
+ * right-to-left and stops at the first address it does not trust, so both
+ * paths land on the real client; a fixed number would be wrong for one of
+ * them. All the intermediaries are private addresses and the client is not,
+ * which is exactly the split this preset encodes.
  */
 export declare function createBaseApp(options?: CreateBaseAppOptions): Express;
 //# sourceMappingURL=createBaseApp.d.ts.map

package/dist/app/createBaseApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createBaseApp.d.ts","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK3D,OAAO,EAAwB,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAI3F,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,cAAc,GAAG,KAAK,CAAC;IACrC,4IAA4I;IAC5I,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kHAAkH;IAClH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAwBzE"}
+{"version":3,"file":"createBaseApp.d.ts","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK3D,OAAO,EAAwB,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAI3F,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,cAAc,GAAG,KAAK,CAAC;IACrC,4IAA4I;IAC5I,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kHAAkH;IAClH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CA2BzE"}

package/dist/app/createBaseApp.js

@@ -32,10 +32,29 @@ const healthController_1 = require("../health/healthController");
  * Services with non-standard body parsing (a webhook needing the raw body,
  * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
  * false` and mount those themselves at the exact point they need to.
+ *
+ * `trust proxy` is on by default because nothing here is reached directly:
+ * every service sits behind tumbaland-proxy, which sets `X-Forwarded-For`.
+ * Left at Express's default (`false`) that header is ignored, which
+ * express-rate-limit reports as `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` — and
+ * it is right to: the limiter would then key every request in the cluster on
+ * the proxy's own container IP, so one busy client could exhaust the window
+ * for everyone.
+ *
+ * The value is `loopback, linklocal, uniquelocal` (private ranges) rather
+ * than a hop count, because the chain length differs per ingress path: a
+ * direct hit arrives as `client` + the proxy's own socket address, while
+ * traffic through the Cloudflare tunnel arrives as `client, 127.0.0.1` (the
+ * local cloudflared) + that same socket address. Express walks the chain
+ * right-to-left and stops at the first address it does not trust, so both
+ * paths land on the real client; a fixed number would be wrong for one of
+ * them. All the intermediaries are private addresses and the client is not,
+ * which is exactly the split this preset encodes.
  */
 function createBaseApp(options = {}) {
-    const { corsOptions, rateLimiter = security_1.standardRateLimiter, parseJson = true, parseCookies = true, tracing = true, metrics = true } = options;
+    const { corsOptions, rateLimiter = security_1.standardRateLimiter, parseJson = true, parseCookies = true, tracing = true, metrics = true, trustProxy = 'loopback, linklocal, uniquelocal' } = options;
     const app = (0, express_1.default)();
+    app.set('trust proxy', trustProxy);
     app.get('/health/live', healthController_1.healthLive);
     app.use(security_1.securityHeaders);
     if (rateLimiter)

package/dist/app/createBaseApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"createBaseApp.js","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":";;;;;AAkDA,sCAwBC;AA1ED,sDAA2D;AAC3D,kEAAyC;AACzC,sDAA6D;AAC7D,wCAA+C;AAC/C,+DAAsF;AACtF,iEAA2F;AAC3F,qDAA8E;AAC9E,iEAAwD;AAsBxD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,EACJ,WAAW,EACX,WAAW,GAAG,8BAAmB,EACjC,SAAS,GAAG,IAAI,EAChB,YAAY,GAAG,IAAI,EACnB,OAAO,GAAG,IAAI,EACd,OAAO,GAAG,IAAI,EACf,GAAG,OAAO,CAAC;IAEZ,MAAM,GAAG,GAAG,IAAA,iBAAO,GAAE,CAAC;IAEtB,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,6BAAU,CAAC,CAAC;IAEpC,GAAG,CAAC,GAAG,CAAC,0BAAe,CAAC,CAAC;IACzB,IAAI,WAAW;QAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,CAAC,mCAAqB,CAAC,CAAC;IAC/B,IAAI,OAAO;QAAE,GAAG,CAAC,GAAG,CAAC,2BAAiB,CAAC,CAAC;IACxC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,wCAAwB,CAAC,CAAC,CAAC,6BAAa,CAAC,CAAC;IAC5D,GAAG,CAAC,GAAG,CAAC,IAAA,qCAAoB,EAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,IAAI,YAAY;QAAE,GAAG,CAAC,GAAG,CAAC,IAAA,uBAAY,GAAE,CAAC,CAAC;IAC1C,IAAI,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,iBAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEvC,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"createBaseApp.js","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":";;;;;AA0EA,sCA2BC;AArGD,sDAA2D;AAC3D,kEAAyC;AACzC,sDAA6D;AAC7D,wCAA+C;AAC/C,+DAAsF;AACtF,iEAA2F;AAC3F,qDAA8E;AAC9E,iEAAwD;AA4BxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,EACJ,WAAW,EACX,WAAW,GAAG,8BAAmB,EACjC,SAAS,GAAG,IAAI,EAChB,YAAY,GAAG,IAAI,EACnB,OAAO,GAAG,IAAI,EACd,OAAO,GAAG,IAAI,EACd,UAAU,GAAG,kCAAkC,EAChD,GAAG,OAAO,CAAC;IAEZ,MAAM,GAAG,GAAG,IAAA,iBAAO,GAAE,CAAC;IAEtB,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;IAEnC,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,6BAAU,CAAC,CAAC;IAEpC,GAAG,CAAC,GAAG,CAAC,0BAAe,CAAC,CAAC;IACzB,IAAI,WAAW;QAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,CAAC,mCAAqB,CAAC,CAAC;IAC/B,IAAI,OAAO;QAAE,GAAG,CAAC,GAAG,CAAC,2BAAiB,CAAC,CAAC;IACxC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,wCAAwB,CAAC,CAAC,CAAC,6BAAa,CAAC,CAAC;IAC5D,GAAG,CAAC,GAAG,CAAC,IAAA,qCAAoB,EAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,IAAI,YAAY;QAAE,GAAG,CAAC,GAAG,CAAC,IAAA,uBAAY,GAAE,CAAC,CAAC;IAC1C,IAAI,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,iBAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEvC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/app/createBaseApp.test.ts

@@ -63,6 +63,37 @@ describe('createBaseApp', () => {
     expect(res.status).toBe(200);
   });
 
+  it('trusts the proxy, so X-Forwarded-For identifies the client rather than being ignored', async () => {
+    const app = createBaseApp();
+    app.get('/whoami', (req, res) => res.json({ ip: req.ip }));
+
+    const res = await request(app).get('/whoami').set('X-Forwarded-For', '203.0.113.7');
+
+    expect(res.body.ip).toBe('203.0.113.7');
+  });
+
+  it('keeps rate-limit buckets per client, not one shared bucket behind the proxy', async () => {
+    const app = createBaseApp({ rateLimiter: (await import('../middleware/security')).createRateLimiter({ windowMs: 60_000, max: 1 }) });
+    app.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    const clientA = await request(app).get('/ping').set('X-Forwarded-For', '203.0.113.7');
+    const clientB = await request(app).get('/ping').set('X-Forwarded-For', '198.51.100.4');
+    const clientAAgain = await request(app).get('/ping').set('X-Forwarded-For', '203.0.113.7');
+
+    expect(clientA.status).toBe(200);
+    expect(clientB.status).toBe(200); // a different client is unaffected by A exhausting its window
+    expect(clientAAgain.status).toBe(429);
+  });
+
+  it('ignores X-Forwarded-For when trustProxy is disabled', async () => {
+    const app = createBaseApp({ trustProxy: false });
+    app.get('/whoami', (req, res) => res.json({ ip: req.ip }));
+
+    const res = await request(app).get('/whoami').set('X-Forwarded-For', '203.0.113.7');
+
+    expect(res.body.ip).not.toBe('203.0.113.7');
+  });
+
   it('mounts /health/live ahead of the rate limiter, so it never gets 429s a busy service would', async () => {
     const app = createBaseApp({ rateLimiter: (await import('../middleware/security')).createRateLimiter({ windowMs: 60_000, max: 1 }) });
     app.get('/ping', (_req, res) => res.json({ ok: true }));

package/src/app/createBaseApp.ts

@@ -25,6 +25,12 @@ export interface CreateBaseAppOptions {
   tracing?: boolean;
   /** Use requestLoggerWithMetrics (adds Prometheus histograms) instead of the plain requestLogger. Default true. */
   metrics?: boolean;
+  /**
+   * Value for Express's `trust proxy`. Defaults to trusting private/loopback
+   * addresses — see the note on tumbaland-proxy below. Pass `false` for a
+   * service exposed directly to clients with no proxy in front of it.
+   */
+  trustProxy?: Parameters<Express['set']>[1];
 }
 
 /**
@@ -47,6 +53,24 @@ export interface CreateBaseAppOptions {
  * Services with non-standard body parsing (a webhook needing the raw body,
  * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
  * false` and mount those themselves at the exact point they need to.
+ *
+ * `trust proxy` is on by default because nothing here is reached directly:
+ * every service sits behind tumbaland-proxy, which sets `X-Forwarded-For`.
+ * Left at Express's default (`false`) that header is ignored, which
+ * express-rate-limit reports as `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` — and
+ * it is right to: the limiter would then key every request in the cluster on
+ * the proxy's own container IP, so one busy client could exhaust the window
+ * for everyone.
+ *
+ * The value is `loopback, linklocal, uniquelocal` (private ranges) rather
+ * than a hop count, because the chain length differs per ingress path: a
+ * direct hit arrives as `client` + the proxy's own socket address, while
+ * traffic through the Cloudflare tunnel arrives as `client, 127.0.0.1` (the
+ * local cloudflared) + that same socket address. Express walks the chain
+ * right-to-left and stops at the first address it does not trust, so both
+ * paths land on the real client; a fixed number would be wrong for one of
+ * them. All the intermediaries are private addresses and the client is not,
+ * which is exactly the split this preset encodes.
  */
 export function createBaseApp(options: CreateBaseAppOptions = {}): Express {
   const {
@@ -55,11 +79,14 @@ export function createBaseApp(options: CreateBaseAppOptions = {}): Express {
     parseJson = true,
     parseCookies = true,
     tracing = true,
-    metrics = true
+    metrics = true,
+    trustProxy = 'loopback, linklocal, uniquelocal'
   } = options;
 
   const app = express();
 
+  app.set('trust proxy', trustProxy);
+
   app.get('/health/live', healthLive);
 
   app.use(securityHeaders);