@63klabs/cache-data 1.3.8 → 1.3.10

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

@@ -2,13 +2,62 @@ const RequestInfo = require('./RequestInfo.class');
 const Timer = require('./Timer.class');
 const DebugAndLog = require('./DebugAndLog.class');
 const { safeClone } = require('./utils');
+const ValidationMatcher = require('../utils/ValidationMatcher.class');
+const ValidationExecutor = require('../utils/ValidationExecutor.class');
 
 
 /**
- * Extends RequestInfo
- * Can be used to create a custom ClientRequest object
+ * Extends RequestInfo to provide request validation, parameter extraction, and authentication.
+ * 
+ * ClientRequest processes Lambda API Gateway events and validates parameters using a flexible
+ * validation system that supports global, route-specific, method-specific, and method-and-route
+ * specific validation rules with clear priority ordering.
+ * 
+ * Validation Priority Order (highest to lowest):
+ * 1. Method-and-route match (BY_ROUTE with "METHOD:route")
+ * 2. Route-only match (BY_ROUTE with "route")
+ * 3. Method-only match (BY_METHOD with "METHOD")
+ * 4. Global parameter name
+ * 
+ * Header Key Format Conversion:
+ * 
+ * HTTP headers use kebab-case naming (e.g., 'content-type', 'x-api-key'), but JavaScript
+ * property naming conventions prefer camelCase. ClientRequest automatically converts header
+ * keys from kebab-case to camelCase during validation and parameter extraction to maintain
+ * consistency with JavaScript naming standards.
+ * 
+ * This conversion is necessary because:
+ * - JavaScript object properties conventionally use camelCase
+ * - Accessing headers as object properties (e.g., headers.contentType) is more idiomatic
+ * - Validation rule keys should match JavaScript property naming conventions
+ * 
+ * Conversion Algorithm:
+ * 1. Convert entire header name to lowercase
+ * 2. Replace each hyphen followed by a letter with the uppercase letter
+ * 3. Remove all hyphens
+ * 
+ * Header Key Conversion Reference Table:
+ * 
+ * | HTTP Header (kebab-case)  | JavaScript Property (camelCase) |
+ * |---------------------------|----------------------------------|
+ * | content-type              | contentType                      |
+ * | Content-Type              | contentType                      |
+ * | authorization             | authorization                    |
+ * | x-api-key                 | xApiKey                          |
+ * | X-API-Key                 | xApiKey                          |
+ * | x-custom-header           | xCustomHeader                    |
+ * | if-modified-since         | ifModifiedSince                  |
+ * | if-none-match             | ifNoneMatch                      |
+ * | cache-control             | cacheControl                     |
+ * | user-agent                | userAgent                        |
+ * | accept-encoding           | acceptEncoding                   |
+ * 
+ * When configuring header parameter validation rules, use the camelCase property names
+ * shown in the right column. Use the static method convertHeaderKeyToCamelCase() to
+ * determine the correct property name for any HTTP header
+ * 
  * @example
- * // Initialize ClientRequest with validations
+ * // Initialize ClientRequest with global validations (backwards compatible)
  * ClientRequest.init({
  *   validations: {
  *     referrers: ['example.com', 'myapp.com'],
@@ -25,6 +74,294 @@ const { safeClone } = require('./utils');
  * });
  * 
  * @example
+ * // Initialize with route-specific validations
+ * ClientRequest.init({
+ *   parameters: {
+ *     pathParameters: {
+ *       // Global validation (Priority 4) - applies to all routes
+ *       id: (value) => typeof value === 'string' && value.length > 0,
+ *       
+ *       // Route-specific validations (Priority 2)
+ *       BY_ROUTE: [
+ *         {
+ *           route: "product/{id}",
+ *           validate: (value) => /^P-[0-9]+$/.test(value)
+ *         },
+ *         {
+ *           route: "employee/{id}",
+ *           validate: (value) => /^E-[0-9]+$/.test(value)
+ *         }
+ *       ]
+ *     }
+ *   }
+ * });
+ * 
+ * @example
+ * // Initialize with method-specific validations
+ * ClientRequest.init({
+ *   parameters: {
+ *     pathParameters: {
+ *       id: (value) => typeof value === 'string',
+ *       
+ *       // Method-specific validations (Priority 3)
+ *       BY_METHOD: [
+ *         {
+ *           method: "POST",
+ *           validate: (value) => value.length <= 50
+ *         },
+ *         {
+ *           method: "GET",
+ *           validate: (value) => value.length > 0
+ *         }
+ *       ]
+ *     }
+ *   }
+ * });
+ * 
+ * @example
+ * // Initialize with method-and-route validations (highest priority)
+ * ClientRequest.init({
+ *   parameters: {
+ *     pathParameters: {
+ *       BY_ROUTE: [
+ *         {
+ *           route: "POST:game/join/{id}",  // Priority 1: Method-and-route
+ *           validate: (value) => /^[0-9]{6}$/.test(value)
+ *         },
+ *         {
+ *           route: "GET:game/join/{id}",   // Priority 1: Method-and-route
+ *           validate: (value) => /^[0-9]+$/.test(value)
+ *         }
+ *       ]
+ *     }
+ *   }
+ * });
+ * 
+ * @example
+ * // Multi-parameter validation - validate multiple parameters together
+ * ClientRequest.init({
+ *   parameters: {
+ *     queryStringParameters: {
+ *       BY_ROUTE: [
+ *         {
+ *           route: "search?query,limit",  // Specify multiple parameters
+ *           validate: ({query, limit}) => {
+ *             // Validation function receives object with all specified parameters
+ *             return query.length > 0 && limit >= 1 && limit <= 100;
+ *           }
+ *         }
+ *       ]
+ *     }
+ *   }
+ * });
+ * 
+ * @example
+ * // Header parameter validation with camelCase property names
+ * // Note: HTTP headers are automatically converted from kebab-case to camelCase
+ * ClientRequest.init({
+ *   parameters: {
+ *     headerParameters: {
+ *       // Use camelCase for header validation rules
+ *       contentType: (value) => value === 'application/json',
+ *       authorization: (value) => value.startsWith('Bearer '),
+ *       xApiKey: (value) => /^[a-zA-Z0-9]{32}$/.test(value),
+ *       
+ *       // Use convertHeaderKeyToCamelCase() to determine correct property names
+ *       // ClientRequest.convertHeaderKeyToCamelCase('x-custom-header') returns 'xCustomHeader'
+ *       xCustomHeader: (value) => value.length > 0
+ *     }
+ *   }
+ * });
+ * 
+ * @example
+ * // Body parameter validation - basic single-field validation
+ * // Body content is automatically parsed from JSON before validation
+ * ClientRequest.init({
+ *   parameters: {
+ *     bodyParameters: {
+ *       // Global validation for specific fields
+ *       email: (value) => typeof value === 'string' && value.includes('@'),
+ *       age: (value) => typeof value === 'number' && value >= 0 && value <= 150,
+ *       username: (value) => /^[a-zA-Z0-9_-]{3,20}$/.test(value)
+ *     }
+ *   }
+ * });
+ * 
+ * // In Lambda handler
+ * exports.handler = async (event, context) => {
+ *   // event.body = '{"email":"user@example.com","age":25,"username":"john_doe"}'
+ *   const clientRequest = new ClientRequest(event, context);
+ *   
+ *   if (!clientRequest.isValid()) {
+ *     return { statusCode: 400, body: 'Invalid request body' };
+ *   }
+ *   
+ *   // Access validated body parameters
+ *   const bodyParams = clientRequest.getBodyParameters();
+ *   console.log(bodyParams.email);    // 'user@example.com'
+ *   console.log(bodyParams.age);      // 25
+ *   console.log(bodyParams.username); // 'john_doe'
+ * };
+ * 
+ * @example
+ * // Body parameter validation - multi-field validation
+ * // Validate multiple fields together with complex business logic
+ * ClientRequest.init({
+ *   parameters: {
+ *     bodyParameters: {
+ *       BY_ROUTE: [
+ *         {
+ *           route: 'POST:users',
+ *           validate: ({email, password, confirmPassword}) => {
+ *             // Multi-field validation: password confirmation
+ *             return email && password && 
+ *                    password === confirmPassword &&
+ *                    password.length >= 8 &&
+ *                    email.includes('@');
+ *           }
+ *         },
+ *         {
+ *           route: 'PUT:users/{id}',
+ *           validate: ({email, username}) => {
+ *             // At least one field must be provided for update
+ *             return email || username;
+ *           }
+ *         }
+ *       ]
+ *     }
+ *   }
+ * });
+ * 
+ * @example
+ * // Body parameter validation - error handling for invalid JSON
+ * // ClientRequest handles JSON parsing errors gracefully
+ * exports.handler = async (event, context) => {
+ *   // event.body = 'invalid json{' (malformed JSON)
+ *   const clientRequest = new ClientRequest(event, context);
+ *   
+ *   if (!clientRequest.isValid()) {
+ *     // Validation fails for invalid JSON
+ *     return { 
+ *       statusCode: 400, 
+ *       body: JSON.stringify({ error: 'Invalid request body' })
+ *     };
+ *   }
+ *   
+ *   // This code only runs if body is valid JSON and passes validation
+ *   const bodyParams = clientRequest.getBodyParameters();
+ *   // Process valid body parameters...
+ * };
+ * 
+ * @example
+ * // Body parameter validation - complex nested objects and arrays
+ * ClientRequest.init({
+ *   parameters: {
+ *     bodyParameters: {
+ *       // Validate nested object structure
+ *       user: (value) => {
+ *         return value && 
+ *                typeof value === 'object' &&
+ *                typeof value.name === 'string' &&
+ *                typeof value.email === 'string' &&
+ *                value.email.includes('@');
+ *       },
+ *       
+ *       // Validate array of items
+ *       items: (value) => {
+ *         return Array.isArray(value) &&
+ *                value.length > 0 &&
+ *                value.every(item => 
+ *                  item.id && 
+ *                  typeof item.quantity === 'number' &&
+ *                  item.quantity > 0
+ *                );
+ *       },
+ *       
+ *       // Validate nested array of objects with specific structure
+ *       addresses: (value) => {
+ *         return Array.isArray(value) &&
+ *                value.every(addr =>
+ *                  addr.street &&
+ *                  addr.city &&
+ *                  addr.zipCode &&
+ *                  /^\d{5}$/.test(addr.zipCode)
+ *                );
+ *       }
+ *     }
+ *   }
+ * });
+ * 
+ * // Example request body:
+ * // {
+ * //   "user": {
+ * //     "name": "John Doe",
+ * //     "email": "john@example.com"
+ * //   },
+ * //   "items": [
+ * //     {"id": "item-1", "quantity": 2},
+ * //     {"id": "item-2", "quantity": 1}
+ * //   ],
+ * //   "addresses": [
+ * //     {"street": "123 Main St", "city": "Boston", "zipCode": "02101"}
+ * //   ]
+ * // }
+ * 
+ * exports.handler = async (event, context) => {
+ *   const clientRequest = new ClientRequest(event, context);
+ *   
+ *   if (!clientRequest.isValid()) {
+ *     return { statusCode: 400, body: 'Invalid request body structure' };
+ *   }
+ *   
+ *   const bodyParams = clientRequest.getBodyParameters();
+ *   console.log(bodyParams.user.name);        // 'John Doe'
+ *   console.log(bodyParams.items.length);     // 2
+ *   console.log(bodyParams.addresses[0].city); // 'Boston'
+ * };
+ * 
+ * @example
+ * // Body parameter validation - combining with other parameter types
+ * ClientRequest.init({
+ *   parameters: {
+ *     pathParameters: {
+ *       id: (value) => /^[0-9]+$/.test(value)
+ *     },
+ *     bodyParameters: {
+ *       BY_ROUTE: [
+ *         {
+ *           route: 'PUT:users/{id}',
+ *           validate: ({email, username, bio}) => {
+ *             // Validate update payload
+ *             const hasAtLeastOneField = email || username || bio;
+ *             const emailValid = !email || email.includes('@');
+ *             const usernameValid = !username || /^[a-zA-Z0-9_-]{3,20}$/.test(username);
+ *             const bioValid = !bio || bio.length <= 500;
+ *             
+ *             return hasAtLeastOneField && emailValid && usernameValid && bioValid;
+ *           }
+ *         }
+ *       ]
+ *     }
+ *   }
+ * });
+ * 
+ * exports.handler = async (event, context) => {
+ *   const clientRequest = new ClientRequest(event, context);
+ *   
+ *   if (!clientRequest.isValid()) {
+ *     return { statusCode: 400, body: 'Invalid request' };
+ *   }
+ *   
+ *   // All parameter types are validated
+ *   const userId = clientRequest.getPathParameters().id;
+ *   const updates = clientRequest.getBodyParameters();
+ *   
+ *   // Update user with validated data
+ *   await updateUser(userId, updates);
+ *   return { statusCode: 200, body: 'User updated' };
+ * };
+ * 
+ * @example
  * // Use in Lambda handler
  * exports.handler = async (event, context) => {
  *   const clientRequest = new ClientRequest(event, context);
@@ -61,6 +398,10 @@ class ClientRequest extends RequestInfo {
 	#context = null;
 	#authorizations = safeClone(ClientRequest.#unauthenticatedAuthorizations);
 	#roles = [];
+	
+	/* Validation system */
+	#validationMatchers = {};
+	#validationReason = { isValid: true, statusCode: 200, messages: [] };
 
 	/* The request data */
 	#props = {};
@@ -74,9 +415,36 @@ class ClientRequest extends RequestInfo {
 	}
 
 	/**
-	 * Initializes the request data based on the event. Also sets the 
-	 * validity of the request so it may be checked by .isValid()
-	 * @param {object} event object from Lambda
+	 * Initializes the request data based on the event and performs parameter validation.
+	 * 
+	 * The constructor initializes ValidationMatchers for each parameter type (path, query, header, cookie)
+	 * using the configured validation rules. Validation is performed immediately during construction,
+	 * and the request validity can be checked using isValid().
+	 * 
+	 * Validation uses a four-tier priority system:
+	 * 1. Method-and-route match (BY_ROUTE with "METHOD:route") - Most specific
+	 * 2. Route-only match (BY_ROUTE with "route")
+	 * 3. Method-only match (BY_METHOD with "METHOD")
+	 * 4. Global parameter name - Least specific
+	 * 
+	 * @param {Object} event - Lambda API Gateway event object
+	 * @param {Object} context - Lambda context object
+	 * @example
+	 * // Basic usage
+	 * const clientRequest = new ClientRequest(event, context);
+	 * if (clientRequest.isValid()) {
+	 *   // Process valid request
+	 * }
+	 * 
+	 * @example
+	 * // With route-specific validation
+	 * // If event.resource = "/product/{id}" and event.httpMethod = "GET"
+	 * // ValidationMatcher will check:
+	 * // 1. GET:product/{id} validation (if exists)
+	 * // 2. product/{id} validation (if exists)
+	 * // 3. GET method validation (if exists)
+	 * // 4. Global 'id' parameter validation (if exists)
+	 * const clientRequest = new ClientRequest(event, context);
 	 */
 	constructor(event, context) {
 		super(event);
@@ -100,8 +468,13 @@ class ClientRequest extends RequestInfo {
 			queryStringParameters: {},
 			headerParameters: {},
 			cookieParameters: {},
+			bodyParameters: {},
 			bodyPayload: this.#event?.body || null, // from body
 			client: {
+				ip: this.getClientIp(),
+				userAgent: this.getClientUserAgent(),
+				origin: this.getClientOrigin(),
+				referrer: this.getClientReferrer(),
 				isAuthenticated: this.isAuthenticated(),
 				isGuest: this.isGuest(),
 				authorizations: this.getAuthorizations(),
@@ -111,18 +484,176 @@ class ClientRequest extends RequestInfo {
 			calcMsToDeadline: this.calcMsToDeadline
 		};
 		
+		// >! Initialize ValidationMatchers for each parameter type
+		// >! This enables route-specific and method-specific validations
+		const httpMethod = this.#event.httpMethod || '';
+		const resourcePath = resource || '';
+		const paramValidations = ClientRequest.getParameterValidations();
+		
+		// >! Support both queryParameters and queryStringParameters for backwards compatibility
+		const queryValidations = paramValidations?.queryStringParameters || paramValidations?.queryParameters;
+		
+		this.#validationMatchers = {
+			pathParameters: new ValidationMatcher(paramValidations?.pathParameters, httpMethod, resourcePath),
+			queryStringParameters: new ValidationMatcher(queryValidations, httpMethod, resourcePath),
+			headerParameters: new ValidationMatcher(paramValidations?.headerParameters, httpMethod, resourcePath),
+			cookieParameters: new ValidationMatcher(paramValidations?.cookieParameters, httpMethod, resourcePath),
+			bodyParameters: new ValidationMatcher(paramValidations?.bodyParameters, httpMethod, resourcePath)
+		};
+		
 		this.#validate();
 
 	};
 
 	/**
-	 * This is used to initialize the ClientRequest class for all requests.
-	 * Add ClientRequest.init(options) to the Config.init process or at the
-	 * top of the main index.js file outside of the handler.
-	 * @param {object} options - Configuration options with validations property containing referrers and parameters
-	 * @param {Array<string>} options.referrers - Array of allowed referrers
-	 * @param {object} options.parameters - Object containing parameter validation functions
+	 * Initialize the ClientRequest class with validation configuration.
+	 * 
+	 * This method configures the validation system for all ClientRequest instances.
+	 * Call this once during application initialization, before creating any ClientRequest instances.
+	 * 
+	 * Validation Configuration Structure:
+	 * - referrers: Array of allowed referrer domains (use ['*'] to allow all)
+	 * - parameters: Object containing validation rules for each parameter type
+	 *   - pathParameters, queryStringParameters, headerParameters, cookieParameters, bodyParameters
+	 *   - Each parameter type can have:
+	 *     - Global validations: paramName: (value) => boolean
+	 *     - BY_ROUTE: Array of route-specific validation rules
+	 *     - BY_METHOD: Array of method-specific validation rules
+	 * 
+	 * Parameter Specification Syntax:
+	 * - Path parameters: "route/{param}" - Validates 'param' path parameter
+	 * - Query parameters: "route?param" - Validates 'param' query parameter
+	 * - Multiple parameters: "route?param1,param2" - Validates both parameters together
+	 * - Method-and-route: "METHOD:route" - Applies only to specific HTTP method and route
+	 * 
+	 * @param {Object} options - Configuration options
+	 * @param {Array<string>} [options.referrers] - Array of allowed referrers (use ['*'] for all)
+	 * @param {Object} [options.parameters] - Parameter validation configuration
+	 * @param {Object} [options.parameters.pathParameters] - Path parameter validations
+	 * @param {Object} [options.parameters.queryStringParameters] - Query parameter validations
+	 * @param {Object} [options.parameters.headerParameters] - Header parameter validations
+	 * @param {Object} [options.parameters.cookieParameters] - Cookie parameter validations
+	 * @param {Object} [options.parameters.bodyParameters] - Body parameter validations
+	 * @param {Array<{route: string, validate: Function}>} [options.parameters.*.BY_ROUTE] - Route-specific validations
+	 * @param {Array<{method: string, validate: Function}>} [options.parameters.*.BY_METHOD] - Method-specific validations
+	 * @param {boolean} [options.parameters.excludeParamsWithNoValidationMatch=true] - Exclude parameters without validation rules
 	 * @throws {Error} If options is not an object
+	 * 
+	 * @example
+	 * // Global validations only (backwards compatible)
+	 * ClientRequest.init({
+	 *   referrers: ['example.com'],
+	 *   parameters: {
+	 *     pathParameters: {
+	 *       id: (value) => /^[a-zA-Z0-9-]+$/.test(value)
+	 *     },
+	 *     queryStringParameters: {
+	 *       limit: (value) => !isNaN(value) && value > 0 && value <= 100
+	 *     }
+	 *   }
+	 * });
+	 * 
+	 * @example
+	 * // Route-specific validations (Priority 2)
+	 * ClientRequest.init({
+	 *   parameters: {
+	 *     pathParameters: {
+	 *       id: (value) => typeof value === 'string',  // Global fallback
+	 *       BY_ROUTE: [
+	 *         {
+	 *           route: "product/{id}",
+	 *           validate: (value) => /^P-[0-9]+$/.test(value)
+	 *         },
+	 *         {
+	 *           route: "employee/{id}",
+	 *           validate: (value) => /^E-[0-9]+$/.test(value)
+	 *         }
+	 *       ]
+	 *     }
+	 *   }
+	 * });
+	 * 
+	 * @example
+	 * // Method-specific validations (Priority 3)
+	 * ClientRequest.init({
+	 *   parameters: {
+	 *     pathParameters: {
+	 *       BY_METHOD: [
+	 *         {
+	 *           method: "POST",
+	 *           validate: (value) => value.length <= 50
+	 *         },
+	 *         {
+	 *           method: "GET",
+	 *           validate: (value) => value.length > 0
+	 *         }
+	 *       ]
+	 *     }
+	 *   }
+	 * });
+	 * 
+	 * @example
+	 * // Method-and-route validations (Priority 1 - highest)
+	 * ClientRequest.init({
+	 *   parameters: {
+	 *     pathParameters: {
+	 *       BY_ROUTE: [
+	 *         {
+	 *           route: "POST:game/join/{id}",
+	 *           validate: (value) => /^[0-9]{6}$/.test(value)
+	 *         },
+	 *         {
+	 *           route: "GET:game/join/{id}",
+	 *           validate: (value) => /^[0-9]+$/.test(value)
+	 *         }
+	 *       ]
+	 *     }
+	 *   }
+	 * });
+	 * 
+	 * @example
+	 * // Multi-parameter validation
+	 * ClientRequest.init({
+	 *   parameters: {
+	 *     queryStringParameters: {
+	 *       BY_ROUTE: [
+	 *         {
+	 *           route: "search?query,limit",  // Specify multiple parameters
+	 *           validate: ({query, limit}) => {
+	 *             // Validation function receives object with all parameters
+	 *             return query.length > 0 && limit >= 1 && limit <= 100;
+	 *           }
+	 *         }
+	 *       ]
+	 *     }
+	 *   }
+	 * });
+	 * 
+	 * @example
+	 * // Mixed priority levels
+	 * ClientRequest.init({
+	 *   parameters: {
+	 *     pathParameters: {
+	 *       id: (value) => typeof value === 'string',  // Priority 4: Global
+	 *       BY_METHOD: [
+	 *         {
+	 *           method: "POST",  // Priority 3: Method-only
+	 *           validate: (value) => value.length <= 50
+	 *         }
+	 *       ],
+	 *       BY_ROUTE: [
+	 *         {
+	 *           route: "product/{id}",  // Priority 2: Route-only
+	 *           validate: (value) => /^P-[0-9]+$/.test(value)
+	 *         },
+	 *         {
+	 *           route: "POST:product/{id}",  // Priority 1: Method-and-route
+	 *           validate: (value) => /^P-[0-9]{4}$/.test(value)
+	 *         }
+	 *       ]
+	 *     }
+	 *   }
+	 * });
 	 */
 	static init(options) {
 		if (typeof options === 'object') {
@@ -172,7 +703,7 @@ class ClientRequest extends RequestInfo {
 	 * Parameter validations
 	 * @returns {{
 	 * 	pathParameters?: object,
-	 * 	queryParameters?: object,
+	 * 	queryStringParameters?: object,
 	 * 	headerParameters?: object,
 	 * 	cookieParameters?: object,
 	 * 	bodyParameters?: object
@@ -181,6 +712,47 @@ class ClientRequest extends RequestInfo {
 	static getParameterValidations() {
 		return ClientRequest.#validations.parameters;
 	};
+	/**
+	 * Convert HTTP header key from kebab-case to camelCase.
+	 *
+	 * This utility method helps developers determine the correct key names for header validation rules.
+	 * HTTP headers use kebab-case (e.g., 'content-type'), but ClientRequest converts them to camelCase
+	 * (e.g., 'contentType') during validation for JavaScript property naming conventions.
+	 *
+	 * The conversion algorithm:
+	 * 1. Convert entire string to lowercase
+	 * 2. Replace each hyphen followed by a letter with the uppercase letter
+	 * 3. Remove all hyphens
+	 *
+	 * @param {string} headerKey - HTTP header key in kebab-case (e.g., 'Content-Type', 'x-custom-header')
+	 * @returns {string} Header key in camelCase (e.g., 'contentType', 'xCustomHeader')
+	 * @example
+	 * // Common HTTP headers
+	 * ClientRequest.convertHeaderKeyToCamelCase('content-type');  // 'contentType'
+	 * ClientRequest.convertHeaderKeyToCamelCase('Content-Type');  // 'contentType'
+	 * ClientRequest.convertHeaderKeyToCamelCase('x-api-key');     // 'xApiKey'
+	 *
+	 * @example
+	 * // Multiple hyphens
+	 * ClientRequest.convertHeaderKeyToCamelCase('x-custom-header-name');  // 'xCustomHeaderName'
+	 *
+	 * @example
+	 * // Use in validation configuration
+	 * const headerKey = ClientRequest.convertHeaderKeyToCamelCase('X-Custom-Header');
+	 * // Now use 'xCustomHeader' in validation rules
+	 */
+	static convertHeaderKeyToCamelCase(headerKey) {
+		if (!headerKey || typeof headerKey !== 'string') {
+			return '';
+		}
+
+		// >! Convert to lowercase and replace -([a-z]) with uppercase letter
+		// >! Then remove any remaining hyphens (e.g., from consecutive hyphens or trailing hyphens)
+		// >! This prevents injection via special characters in header names
+		return headerKey.toLowerCase()
+			.replace(/-([a-z])/g, (match, letter) => letter.toUpperCase())
+			.replace(/-/g, '');
+	}
 
 	/**
 	 * Used in the constructor to set validity of the request
@@ -188,80 +760,440 @@ class ClientRequest extends RequestInfo {
 	 */
 	#validate() {
 	
-		let valid = false;
+		const reasons = [];
+		let statusCode = 200;
+
+		// Referrer check
+		const referrerValid = this.isAuthorizedReferrer();
+		if (!referrerValid) {
+			reasons.push("Forbidden");
+			statusCode = this.#upgradeStatusCode(statusCode, 403);
+		}
 
-		// add your additional validations here
-		valid = this.isAuthorizedReferrer() && this.#hasValidPathParameters() && this.#hasValidQueryStringParameters() && this.#hasValidHeaderParameters() && this.#hasValidCookieParameters();
+		// Authentication check
+		const authFailed = this.hasNoAuthorization();
+		if (authFailed) {
+			reasons.push("Unauthorized");
+			statusCode = this.#upgradeStatusCode(statusCode, 401);
+		}
+
+		// Parameter checks - collect invalid parameter names from each
+		const pathResult = this.#hasValidPathParameters();
+		const queryResult = this.#hasValidQueryStringParameters();
+		const headerResult = this.#hasValidHeaderParameters();
+		const cookieResult = this.#hasValidCookieParameters();
+		const bodyResult = this.#hasValidBodyParameters();
+
+		// Collect invalid parameter messages
+		const paramResults = [pathResult, queryResult, headerResult, cookieResult, bodyResult];
+		for (const result of paramResults) {
+			if (result.invalidParams) {
+				for (const paramName of result.invalidParams) {
+					reasons.push(`Invalid parameter: ${paramName}`);
+					statusCode = this.#upgradeStatusCode(statusCode, 400);
+				}
+			}
+		}
+
+		// Handle invalid JSON body
+		if (bodyResult.invalidBody) {
+			reasons.push("Invalid request body");
+			statusCode = this.#upgradeStatusCode(statusCode, 400);
+		}
 
-		// set the variable
+		// Compute combined valid boolean from all check results
+		const valid = referrerValid && !authFailed
+			&& pathResult.isValid && queryResult.isValid && headerResult.isValid
+			&& cookieResult.isValid && bodyResult.isValid;
+
+		// Preserve backwards compatibility
 		super._isValid = valid;
 
+		// Populate validation reason
+		this.#validationReason = {
+			isValid: valid,
+			statusCode: valid ? 200 : statusCode,
+			messages: valid ? [] : reasons
+		};
+
 	};
 
-	#hasValidParameters(paramValidations, clientParameters) {
+	/**
+	 * Returns the higher-priority HTTP status code between two candidates.
+	 * Priority order: 401 > 403 > 400 > 200.
+	 *
+	 * @private
+	 * @param {number} current - The current status code
+	 * @param {number} candidate - The candidate status code to compare
+	 * @returns {number} The status code with higher priority
+	 */
+	#upgradeStatusCode(current, candidate) {
+		const priority = { 401: 3, 403: 2, 400: 1, 200: 0 };
+		return (priority[candidate] || 0) > (priority[current] || 0) ? candidate : current;
+	};
+
+	/**
+	 * Returns a structured validation result object describing why the request
+	 * passed or failed validation. The object includes the validation status,
+	 * an appropriate HTTP status code, and descriptive messages identifying
+	 * each failure.
+	 * 
+	 * A new object is returned on each call to prevent external mutation of
+	 * internal state.
+	 * 
+	 * @returns {{ isValid: boolean, statusCode: number, messages: Array<string> }}
+	 *   A new object on each call containing:
+	 *   - isValid: whether the request passed all validation checks
+	 *   - statusCode: the appropriate HTTP status code (200, 400, 401, or 403)
+	 *   - messages: array of descriptive failure messages (empty when valid)
+	 * @example
+	 * // Valid request
+	 * const reason = clientRequest.getValidationReason();
+	 * // { isValid: true, statusCode: 200, messages: [] }
+	 *
+	 * @example
+	 * // Invalid request with bad parameters
+	 * const reason = clientRequest.getValidationReason();
+	 * // { isValid: false, statusCode: 400, messages: ["Invalid parameter: limit"] }
+	 */
+	getValidationReason() {
+		return {
+			isValid: this.#validationReason.isValid,
+			statusCode: this.#validationReason.statusCode,
+			messages: [...this.#validationReason.messages]
+		};
+	}
+
+	/**
+	 * Validate parameters using ValidationMatcher and ValidationExecutor.
+	 * 
+	 * This method implements the core parameter validation logic:
+	 * 1. Uses ValidationMatcher to find the best matching validation rule (4-tier priority)
+	 * 2. Uses ValidationExecutor to execute validation with appropriate interface (single or multi-parameter)
+	 * 3. Extracts ALL validated parameters specified in the matching rule and returns them
+	 * 4. Respects excludeParamsWithNoValidationMatch flag (default: true)
+	 * 
+	 * When a validation rule matches and validation passes, ALL parameters specified in rule.params
+	 * are extracted from clientParameters and included in the returned params object. This ensures
+	 * that multi-parameter validation rules (e.g., validating query?param1,param2 together) correctly
+	 * extract all validated parameters, not just the one that triggered the rule match.
+	 * 
+	 * For single-parameter validation with multi-placeholder routes (e.g., users/{userId}/posts/{id}):
+	 * - ValidationMatcher returns validateParam field indicating which parameter to validate
+	 * - ValidationExecutor validates only that parameter with single-parameter interface
+	 * - This method extracts ALL parameters from rule.params array (e.g., both userId and id)
+	 * 
+	 * @private
+	 * @param {Object} paramValidations - Parameter validation configuration (may include BY_ROUTE, BY_METHOD, and global validations)
+	 * @param {Object} clientParameters - Parameters from the request (path, query, header, or cookie parameters)
+	 * @param {ValidationMatcher} validationMatcher - ValidationMatcher instance for finding validation rules
+	 * @returns {{isValid: boolean, params: Object}} Object with validation result and extracted parameters
+	 * @example
+	 * // Internal use - validates path parameters
+	 * const { isValid, params } = #hasValidParameters(
+	 *   paramValidations.pathParameters,
+	 *   event.pathParameters,
+	 *   validationMatcher
+	 * );
+	 */
+	#hasValidParameters(paramValidations, clientParameters, validationMatcher) {
 
 		let rValue = {
 			isValid: true,
-			params: {}
+			params: {},
+			invalidParams: []
 		}
 	
-		if (clientParameters && paramValidations) {
+		if (clientParameters) {
+			// >! Check excludeParamsWithNoValidationMatch flag (default: true)
+			const excludeUnmatched = ClientRequest.#validations.parameters?.excludeParamsWithNoValidationMatch !== false;
+
+			// >! When no validation rules exist for this parameter type,
+			// >! pass through all parameters if excludeUnmatched is false
+			if (!paramValidations) {
+				if (!excludeUnmatched) {
+					rValue.params = { ...clientParameters };
+				}
+				return rValue;
+			}
+			
+			// >! Track which parameters have been validated to avoid duplicate validation
+			const validatedParams = new Set();
+			
+			// >! Create normalized parameter map for validation execution
+			// >! Include ALL parameter types so multi-parameter validations can access them
+			const normalizedParams = {};
+			
+			// >! Add path parameters (if available)
+			if (this.#event?.pathParameters) {
+				for (const [key, value] of Object.entries(this.#event.pathParameters)) {
+					const normalizedKey = key.replace(/^\/|\/$/g, '');
+					normalizedParams[normalizedKey] = value;
+				}
+			}
+			
+			// >! Add query parameters (if available, lowercased)
+			if (this.#event?.queryStringParameters) {
+				for (const [key, value] of Object.entries(this.#event.queryStringParameters)) {
+					const normalizedKey = key.toLowerCase().replace(/^\/|\/$/g, '');
+					normalizedParams[normalizedKey] = value;
+				}
+			}
+			
+			// >! Add header parameters (if available, camelCased)
+			if (this.#event?.headers) {
+				for (const [key, value] of Object.entries(this.#event.headers)) {
+					const camelCaseKey = key.toLowerCase().replace(/-([a-z])/g, (g) => g[1].toUpperCase());
+					normalizedParams[camelCaseKey] = value;
+				}
+			}
+			
+			// >! Add cookie parameters (if available)
+			if (this.#event?.cookie) {
+				for (const [key, value] of Object.entries(this.#event.cookie)) {
+					const normalizedKey = key.replace(/^\/|\/$/g, '');
+					normalizedParams[normalizedKey] = value;
+				}
+			}
+			
+			// >! Add client parameters being validated to normalizedParams
+			// >! This ensures validation functions can access the parameters they're validating
+			for (const [key, value] of Object.entries(clientParameters)) {
+				const normalizedKey = key.replace(/^\/|\/$/g, '');
+				normalizedParams[normalizedKey] = value;
+			}
+			
+			// >! Collect valid params separately so we can clear them if any fail
+			const collectedParams = {};
+
 			// Use a for...of loop instead of forEach for better control flow
 			for (const [key, value] of Object.entries(clientParameters)) {
+				// >! Preserve existing parameter key normalization
 				const paramKey = key.replace(/^\/|\/$/g, '');
 				const paramValue = value;
 				
-				if (paramKey in paramValidations) {
-					const validationFunc = paramValidations[paramKey];
-					if (typeof validationFunc === 'function' && validationFunc(paramValue)) {
-						rValue.params[paramKey] = paramValue;
+				// >! Skip parameters that have already been validated
+				if (validatedParams.has(paramKey)) {
+					continue;
+				}
+				
+				// >! Use ValidationMatcher to find the best matching validation rule
+				const rule = validationMatcher.findValidationRule(paramKey);
+				
+				if (rule) {
+					// >! Use ValidationExecutor to execute validation with appropriate interface
+					// Pass normalized parameters so validation functions can access them by normalized names
+					const isValid = ValidationExecutor.execute(rule.validate, rule.params, normalizedParams);
+					
+					if (isValid) {
+						// >! Extract ALL parameters specified in rule.params when validation passes
+						// >! This fixes the bug where only the current paramKey was added
+						for (const ruleParamName of rule.params) {
+							// >! Find the parameter value in clientParameters
+							// >! Use normalized key matching to handle case differences
+							const normalizedRuleParam = ruleParamName.replace(/^\/|\/$/g, '');
+							
+							// >! Search for matching parameter in clientParameters
+							for (const [clientKey, clientValue] of Object.entries(clientParameters)) {
+								const normalizedClientKey = clientKey.replace(/^\/|\/$/g, '');
+								
+								if (normalizedClientKey === normalizedRuleParam) {
+									collectedParams[clientKey] = clientValue;
+									// >! Mark this parameter as validated to avoid duplicate validation
+									validatedParams.add(normalizedClientKey);
+									break;
+								}
+							}
+						}
 					} else {
+						// >! Maintain existing logging for invalid parameters
 						DebugAndLog.warn(`Invalid parameter: ${paramKey} = ${paramValue}`);
 						rValue.isValid = false;
-						rValue.params = {};
-						return rValue; // exit right away
+						rValue.invalidParams.push(paramKey);
 					}
+				} else if (!excludeUnmatched) {
+					// No validation rule found, but excludeUnmatched is false
+					// Include parameter without validation
+					collectedParams[paramKey] = paramValue;
 				}
+				// If excludeUnmatched is true and no rule found, skip parameter (existing behavior)
 			}
+
+			// >! If any parameter failed, clear params (preserves existing behavior)
+			rValue.params = rValue.isValid ? collectedParams : {};
 		}	
 		return rValue;
 	}
 
+	/**
+	 * Validate path parameters from the request.
+	 * 
+	 * Uses ValidationMatcher to find matching validation rules based on route pattern and HTTP method.
+	 * Extracts validated path parameters and stores them in this.#props.pathParameters.
+	 * 
+	 * @private
+	 * @returns {boolean} True if all path parameters are valid, false otherwise
+	 * @example
+	 * // Internal use during request validation
+	 * const isValid = #hasValidPathParameters();
+	 */
 	#hasValidPathParameters() {
-		const { isValid, params } = this.#hasValidParameters(ClientRequest.getParameterValidations()?.pathParameters, this.#event?.pathParameters);
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
+			ClientRequest.getParameterValidations()?.pathParameters,
+			this.#event?.pathParameters,
+			this.#validationMatchers.pathParameters
+		);
 		this.#props.pathParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
+	/**
+	 * Validate query string parameters from the request.
+	 * 
+	 * Normalizes query parameter keys to lowercase before validation.
+	 * Uses ValidationMatcher to find matching validation rules based on route pattern and HTTP method.
+	 * Extracts validated query parameters and stores them in this.#props.queryStringParameters.
+	 * Supports both queryStringParameters and queryParameters for backwards compatibility.
+	 * 
+	 * @private
+	 * @returns {boolean} True if all query string parameters are valid, false otherwise
+	 * @example
+	 * // Internal use during request validation
+	 * const isValid = #hasValidQueryStringParameters();
+	 */
 	#hasValidQueryStringParameters() {
 		// lowercase all the this.#event.queryStringParameters keys
 		const qs = {};
 		for (const key in this.#event.queryStringParameters) {
 			qs[key.toLowerCase()] = this.#event.queryStringParameters[key];
 		}
-		const { isValid, params } = this.#hasValidParameters(ClientRequest.getParameterValidations()?.queryStringParameters, qs);
+		
+		// >! Support both queryParameters and queryStringParameters for backwards compatibility
+		const paramValidations = ClientRequest.getParameterValidations();
+		const queryValidations = paramValidations?.queryStringParameters || paramValidations?.queryParameters;
+		
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
+			queryValidations,
+			qs,
+			this.#validationMatchers.queryStringParameters
+		);
 		this.#props.queryStringParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
-	#hasValidHeaderParameters() {
-		// camel case all the this.#event.headers keys and remove hyphens
-		const headers = {};
-		for (const key in this.#event.headers) {
-			const camelCaseKey = key.toLowerCase().replace(/-([a-z])/g, (g) => g[1].toUpperCase());
-			headers[camelCaseKey] = this.#event.headers[key];
+	/**
+	 * Validate header parameters from the request.
+	 * 
+	 * Normalizes header keys to camelCase (e.g., 'content-type' becomes 'contentType') before validation.
+	 * Uses ValidationMatcher to find matching validation rules based on route pattern and HTTP method.
+	 * Extracts validated header parameters and stores them in this.#props.headerParameters.
+	 * 
+	 * @private
+	 * @returns {boolean} True if all header parameters are valid, false otherwise
+	 * @example
+	 * // Internal use during request validation
+	 * const isValid = #hasValidHeaderParameters();
+	 */
+	/**
+		 * Validate header parameters from the request.
+		 * 
+		 * HTTP headers are automatically converted from kebab-case to camelCase for JavaScript
+		 * property naming conventions. The conversion algorithm:
+		 * 1. Convert entire header key to lowercase
+		 * 2. Replace each hyphen followed by a letter with the uppercase letter
+		 * 3. Remove all hyphens
+		 * 
+		 * This allows validation rules to use JavaScript-friendly property names while
+		 * maintaining compatibility with standard HTTP header naming conventions.
+		 * 
+		 * @private
+		 * @returns {boolean} True if all header parameters are valid, false otherwise
+		 * @example
+		 * // HTTP header conversion examples:
+		 * // 'Content-Type' → 'contentType'
+		 * // 'content-type' → 'contentType'
+		 * // 'X-API-Key' → 'xApiKey'
+		 * // 'x-custom-header' → 'xCustomHeader'
+		 * // 'authorization' → 'authorization' (no hyphens, unchanged)
+		 * 
+		 * // Internal use during request validation
+		 * const isValid = this.#hasValidHeaderParameters();
+		 */
+		#hasValidHeaderParameters() {
+			// camel case all the this.#event.headers keys and remove hyphens
+			const headers = {};
+			for (const key in this.#event.headers) {
+				const camelCaseKey = key.toLowerCase().replace(/-([a-z])/g, (g) => g[1].toUpperCase());
+				headers[camelCaseKey] = this.#event.headers[key];
+			}
+			const { isValid, params, invalidParams } = this.#hasValidParameters(
+				ClientRequest.getParameterValidations()?.headerParameters,
+				headers,
+				this.#validationMatchers.headerParameters
+			);
+			this.#props.headerParameters = params;
+			return { isValid, invalidParams };
 		}
-		const { isValid, params } = this.#hasValidParameters(ClientRequest.getParameterValidations()?.headerParameters, headers);
-		this.#props.headerParameters = params;
-		return isValid;
-	}
 
 	#hasValidCookieParameters() {
-		const { isValid, params } = this.#hasValidParameters(ClientRequest.getParameterValidations()?.cookiearameters, this.#event?.cookie); // TODO
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
+			ClientRequest.getParameterValidations()?.cookieParameters,
+			this.#event?.cookie,
+			this.#validationMatchers.cookieParameters
+		);
 		this.#props.cookieParameters = params;
-		return isValid;
+		return { isValid, invalidParams };
 	}
 
+	/**
+	 * Validate body parameters from the request.
+	 *
+	 * Parses JSON body content before validation. Handles both API Gateway v1 and v2 formats.
+	 * Uses ValidationMatcher to find matching validation rules based on route pattern and HTTP method.
+	 * Extracts validated body parameters and stores them in this.#props.bodyParameters.
+	 *
+	 * Null, undefined, or empty string bodies are treated as empty objects for validation.
+	 * If the body contains invalid JSON, the error is logged and validation fails.
+	 *
+	 * @private
+	 * @returns {boolean} True if all body parameters are valid, false otherwise
+	 * @example
+	 * // Internal use during request validation
+	 * const isValid = #hasValidBodyParameters();
+	 */
+	#hasValidBodyParameters() {
+		// >! Parse body content before validation
+		let bodyObject = {};
+
+		// >! Handle null, undefined, and empty string body cases
+		if (this.#event.body && this.#event.body !== '') {
+			try {
+				// >! Parse JSON with error handling
+				bodyObject = JSON.parse(this.#event.body);
+			} catch (error) {
+				// >! Log JSON parsing errors
+				DebugAndLog.error(
+					`Failed to parse request body as JSON: ${error?.message || 'Unknown error'}`,
+					error?.stack
+				);
+				this.#props.bodyParameters = {};
+				return { isValid: false, invalidParams: [], invalidBody: true };
+			}
+		}
+
+		// >! Use existing validation framework with body validation matcher
+		const { isValid, params, invalidParams } = this.#hasValidParameters(
+			ClientRequest.getParameterValidations()?.bodyParameters,
+			bodyObject,
+			this.#validationMatchers.bodyParameters
+		);
+
+		// >! Store validated parameters
+		this.#props.bodyParameters = params;
+		return { isValid, invalidParams };
+	}
+
+
 
 	// Utility function for getPathArray and getResourceArray
 	// Returns array slice based on n parameter
@@ -389,6 +1321,15 @@ class ClientRequest extends RequestInfo {
 		return this.#props.cookieParameters;
 	};
 
+	/**
+	 * Returns the body parameters received in the request.
+	 * Body parameters are validated in the applications validation functions.
+	 * @returns {object} body parameters
+	 */
+	getBodyParameters() {
+		return this.#props.bodyParameters || {};
+	};
+
 	#authenticate() {
 		// add your authentication logic here
 		this.authenticated = false; // anonymous
@@ -425,9 +1366,11 @@ class ClientRequest extends RequestInfo {
 	isAuthorizedReferrer() {
 		/* Check the array of valid referrers */
 		/* Check if the array includes a wildcard (*) OR if one of the whitelisted referrers matches the end of the referrer */
-		if (ClientRequest.requiresValidReferrer()) {
+		if (!ClientRequest.requiresValidReferrer()) {
+			// Wildcard (*) is in the list, allow all referrers
 			return true;
 		} else {
+			// Check if referrer matches one of the whitelisted referrers
 			for (let i = 0; i < ClientRequest.#validations.referrers.length; i++) {
 				if (this.getClientReferer().endsWith(ClientRequest.#validations.referrers[i])) {
 					return true;
@@ -458,7 +1401,7 @@ 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: {}, bodyPayload: string, client: {isAuthenticated: boolean, isGuest: boolean, authorizations: string[], roles: string[]}, deadline: number, calcMsToDeadline: number}
+	 * @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}
 	 */
 	getProps() {
 		return this.#props;