@63klabs/cache-data 1.3.10 → 1.3.11

package/CHANGELOG.md

@@ -8,6 +8,12 @@ To report an issue, or to see proposed and upcoming enhancements, check out [63K
 
 Report all vulnerabilities under the [Security menu](https://github.com/63Klabs/cache-data/security/advisories) in the Cache-Data GitHub repository.
 
+## v1.3.11 (2026-04-09)
+
+### Fixed
+
+- **ClientRequest / RequestInfo: X-Forwarded-For and User-Agent header priority** - When API Gateway is behind CloudFront (or any reverse proxy), `getClientIp()` and `getClientUserAgent()` now return the original client values from the `x-forwarded-for` and `user-agent` headers instead of CloudFront's identity values. Falls back to `identity.sourceIp` and `identity.userAgent` when headers are absent. [Spec: 1-3-11-client-request-update-forwarded-for](.kiro/specs/1-3-11-client-request-update-forwarded-for/)
+
 ## v1.3.10 (2026-03-15)
 
 ### Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@63klabs/cache-data",
-  "version": "1.3.10",
+  "version": "1.3.11",
   "description": "A package for AWS Lambda Node.js applications to access and cache data from remote API endpoints (or other sources) utilizing AWS S3 and DynamoDb for the cache storage. Also provides a simple request handling, routing, and response logging framework for running a web service with minimal dependencies.",
   "author": "Chad Kluck (https://chadkluck.me)",
   "license": "MIT",
@@ -28,7 +28,8 @@
     "@eslint/js": "^10.0.1",
     "eslint": "^10.0.1",
     "fast-check": "^4.5.3",
-    "jest": "^30.2.0"  },
+    "jest": "^30.2.0"
+  },
   "overrides": {
     "fast-xml-parser": ">=5.3.4",
     "glob": ">=13.0.6",

package/src/lib/tools/ClientRequest.class.js

@@ -1400,8 +1400,16 @@ class ClientRequest extends RequestInfo {
 	/**
 	 * Get the _processed_ request properties. These are the properties that
 	 * the ClientRequest object took from the event sent to Lambda, validated,
-	 * supplemented, and makes available to controllers. 
-	 * @returns {{ method: string, path: string, pathArray: string[], resource: string, resourceArray[], pathParameters: {}, queryStringParameters: {}, headerParameters: {}, cookieParameters: {}, bodyParameters: {}, bodyPayload: string, client: {ip: string, userAgent: string, origin: string, referrer: string, isAuthenticated: boolean, isGuest: boolean, authorizations: string[], roles: string[]}, deadline: number, calcMsToDeadline: number}
+	 * supplemented, and makes available to controllers.
+	 * 
+	 * Note When accessed behind CloudFront:
+	 * To ensure the user agent is passed along to API Gateway, use the AWS 
+	 * managed Origin Request Policy named AllViewerExceptHostHeader. This 
+	 * forwards the User-Agent along with most other viewer headers while 
+	 * maintaining the correct Host header required for API Gateway to route 
+	 * the request properly.
+	 *
+	 * @returns {{ method: string, path: string, pathArray: string[], resource: string, resourceArray: string[], pathParameters: {}, queryStringParameters: {}, headerParameters: {}, cookieParameters: {}, bodyParameters: {}, bodyPayload: string, client: {ip: string, userAgent: string, origin: string, referrer: string, isAuthenticated: boolean, isGuest: boolean, authorizations: string[], roles: string[]}, deadline: number, calcMsToDeadline: function}
 	 */
 	getProps() {
 		return this.#props;

package/src/lib/tools/RequestInfo.class.js

@@ -130,6 +130,12 @@ class RequestInfo {
 
 	/**
 	 * User Agent of client request
+	 * Note When accessed behind CloudFront:
+	 * To ensure the user agent is passed along to API Gateway, use the AWS 
+	 * managed Origin Request Policy named AllViewerExceptHostHeader. This 
+	 * forwards the User-Agent along with most other viewer headers while 
+	 * maintaining the correct Host header required for API Gateway to route 
+	 * the request properly.
 	 * @returns {string} The user agent string supplied by the client request
 	 */
 	getClientUserAgent() {
@@ -259,9 +265,25 @@ class RequestInfo {
 
 
 	/**
-	 * Obtain lambda event request details for logging
-	 * @param {*} event 
-	 * @returns Information about the requesting client including IP and user agent
+	 * Obtain lambda event request details for logging.
+	 * Parses the API Gateway event to extract client information including IP,
+	 * user agent, origin, referrer, headers, and query parameters.
+	 * 
+	 * For `client.ip`, the `x-forwarded-for` header is preferred over
+	 * `identity.sourceIp`. When `x-forwarded-for` is present and non-empty,
+	 * the first IP from the comma-separated list is used (trimmed). This
+	 * ensures the original client IP is returned when behind a proxy such
+	 * as CloudFront. Falls back to `identity.sourceIp` when the header is
+	 * absent or empty.
+	 * 
+	 * For `client.userAgent`, the `user-agent` header is preferred over
+	 * `identity.userAgent`. When the header is present and non-empty, its
+	 * value is used directly. This ensures the original client user agent
+	 * is returned instead of a proxy identifier (e.g. "Amazon CloudFront").
+	 * Falls back to `identity.userAgent` when the header is absent or empty.
+	 * 
+	 * @param {object} event - API Gateway Lambda event object
+	 * @returns {{ip: string|null, userAgent: string|null, origin: string|null, referrer: string|null, ifModifiedSince: string|null, ifNoneMatch: string|null, accept: string|null, headers: object, parameters: object, body: string|null}} Client request information
 	 */
 	_clientRequestInfo (event) {
 
@@ -292,11 +314,24 @@ class RequestInfo {
 			client.ip = identity.sourceIp;
 		}
 
+		// if x-forwarded-for header is present, prefer it over identity.sourceIp (first IP in the list is the original client)
+		if ( "x-forwarded-for" in headers && headers["x-forwarded-for"] !== null && headers["x-forwarded-for"] !== "" ) {
+			let firstIp = headers["x-forwarded-for"].split(",")[0].trim();
+			if ( firstIp !== "" ) {
+				client.ip = firstIp;
+			}
+		}
+
 		// if there is a user-agent header, set it
 		if ( "userAgent" in identity && identity.userAgent !== null ) {
 			client.userAgent = identity.userAgent;
 		}
 
+		// if user-agent header is present, prefer it over identity.userAgent (original client user agent)
+		if ( "user-agent" in headers && headers["user-agent"] !== null && headers["user-agent"] !== "" ) {
+			client.userAgent = headers["user-agent"];
+		}
+
 		// if there is an origin header, set it
 		if ( headers?.origin) {
 			client.origin = headers.origin;