refactor(utm): enhance UTM parameter validation to return detailed results and improve sanitization logic

Author: Dobrunia

src/models/usersFactory.ts

@@ -4,7 +4,6 @@ import { Collection, Db } from 'mongodb';
 import DataLoaders from '../dataLoaders';
 import { UserDBScheme } from '@hawk.so/types';
 import { Analytics, AnalyticsEventTypes } from '../utils/analytics';
-import { sanitizeUtmParams, validateUtmParams } from '../utils/utm/utm';
 
 /**
  * Users factory to work with User Model
@@ -79,9 +78,8 @@ export default class UsersFactory extends AbstractModelFactory<UserDBScheme, Use
       notifications: UserModel.generateDefaultNotificationsSettings(email),
     };
 
-    if (validateUtmParams(utm)) {
-      const sanitizedUtm = sanitizeUtmParams(utm);
-      userData.utm = sanitizedUtm;
+    if (utm && Object.keys(utm).length > 0) {
+      userData.utm = utm;
     }
 
     const userId = (await this.collection.insertOne(userData)).insertedId;

src/resolvers/user.ts

@@ -12,6 +12,7 @@ import { UserDBScheme } from '@hawk.so/types';
 import * as telegram from '../utils/telegram';
 import { MongoError } from 'mongodb';
 import { validateUtmParams, sanitizeUtmParams } from '../utils/utm/utm';
+import HawkCatcher from '@hawk.so/nodejs';
 
 /**
  * See all types and fields here {@see ../typeDefs/user.graphql}
@@ -47,12 +48,34 @@ export default {
       { factories }: ResolverContextBase
     ): Promise<boolean | string> {
       // Validate and sanitize UTM parameters
-      if (!validateUtmParams(utm)) {
-        throw new UserInputError('Invalid UTM parameters provided');
+      let sanitizedUtm;
+      if (utm) {
+        const validationResult = validateUtmParams(utm);
+
+        if (validationResult.isValid) {
+          // All UTM parameters are valid
+          sanitizedUtm = sanitizeUtmParams(utm, validationResult);
+        } else if (validationResult.validKeys.length > 0) {
+          // Some UTM parameters are valid, save only those
+          sanitizedUtm = sanitizeUtmParams(utm, validationResult);
+
+          // Log the invalid keys for monitoring
+          HawkCatcher.send(new Error('Some UTM parameters are invalid'), {
+            email,
+            utm,
+            invalidKeys: JSON.stringify(validationResult.invalidKeys),
+            validKeys: JSON.stringify(validationResult.validKeys),
+          });
+        } else {
+          // No valid UTM parameters
+          HawkCatcher.send(new Error('All UTM parameters are invalid'), {
+            email,
+            utm,
+            invalidKeys: JSON.stringify(validationResult.invalidKeys),
+          });
+        }
       }
 
-      const sanitizedUtm = sanitizeUtmParams(utm);
-
       let user;
 
       try {

src/utils/utm/utm.ts

@@ -23,69 +23,96 @@ const INVALID_UTM_CHARACTERS = /[^a-zA-Z0-9\s\-_.]/g;
 const MAX_UTM_VALUE_LENGTH = 200;
 
 /**
- * Validates UTM parameters
+ * Validates UTM parameters per key
  * @param utm - Data form where user went to sign up. Used for analytics purposes
- * @returns boolean - true if valid, false if invalid
+ * @returns object with validation results per key and overall validity
  */
-export function validateUtmParams(utm: UserDBScheme['utm']): boolean {
+export function validateUtmParams(utm: UserDBScheme['utm']): {
+  isValid: boolean;
+  validKeys: string[];
+  invalidKeys: string[];
+} {
   if (!utm) {
-    return true;
+    return { isValid: true, validKeys: [], invalidKeys: [] };
   }
 
   // Check if utm is an object
   if (typeof utm !== 'object' || Array.isArray(utm)) {
-    return false;
+    return { isValid: false, validKeys: [], invalidKeys: ['_structure'] };
   }
 
   const providedKeys = Object.keys(utm);
 
   // Check if utm object is not empty
   if (providedKeys.length === 0) {
-    return true; // Empty object is valid
+    return { isValid: true, validKeys: [], invalidKeys: [] };
   }
 
-  // Check if all provided keys are valid UTM keys
-  const hasInvalidKeys = providedKeys.some((key) => !VALID_UTM_KEYS.includes(key));
-  if (hasInvalidKeys) {
-    return false;
-  }
+  const validKeys: string[] = [];
+  const invalidKeys: string[] = [];
 
-  // Check if values are strings and not too long
   for (const [key, value] of Object.entries(utm)) {
+    // Check if key is valid UTM key
+    if (!VALID_UTM_KEYS.includes(key)) {
+      invalidKeys.push(key);
+      continue;
+    }
+
+    // Check if value is valid
     if (value !== undefined && value !== null) {
       if (typeof value !== 'string') {
-        return false;
+        invalidKeys.push(key);
+        continue;
       }
 
       // Check length
       if (value.length === 0 || value.length > MAX_UTM_VALUE_LENGTH) {
-        return false;
+        invalidKeys.push(key);
+        continue;
       }
 
-      // Check for valid characters - only allow alphanumeric, spaces, hyphens, underscores, dots
+      // Check for valid characters
       if (!VALID_UTM_CHARACTERS.test(value)) {
-        return false;
+        invalidKeys.push(key);
+        continue;
       }
     }
+
+    validKeys.push(key);
   }
 
-  return true;
+  return {
+    isValid: invalidKeys.length === 0,
+    validKeys,
+    invalidKeys,
+  };
 }
 
 /**
- * Sanitizes UTM parameters by removing invalid characters
+ * Sanitizes UTM parameters by keeping only valid keys and cleaning values
  * @param utm - Data form where user went to sign up. Used for analytics purposes
- * @returns sanitized UTM parameters or undefined if invalid
+ * @param validationResult - Optional validation result to use valid keys from
+ * @returns sanitized UTM parameters or undefined if no valid data
  */
-export function sanitizeUtmParams(utm: UserDBScheme['utm']): UserDBScheme['utm'] {
+export function sanitizeUtmParams(
+  utm: UserDBScheme['utm'],
+  validationResult?: { validKeys: string[]; invalidKeys: string[] }
+): UserDBScheme['utm'] {
   if (!utm) {
     return undefined;
   }
 
   const sanitized: UserDBScheme['utm'] = {};
 
-  for (const [key, value] of Object.entries(utm)) {
-    if (VALID_UTM_KEYS.includes(key) && value && typeof value === 'string') {
+  // Use validation result if provided, otherwise validate inline
+  const keysToProcess = validationResult
+    ? validationResult.validKeys
+    : Object.keys(utm).filter((key) => VALID_UTM_KEYS.includes(key));
+
+  for (const key of keysToProcess) {
+    const value = (utm as any)[key];
+
+    if (value && typeof value === 'string') {
       // Sanitize value: keep only allowed characters and limit length
       const cleanValue = value
         .replace(INVALID_UTM_CHARACTERS, '')

test/utils/utm.test.ts

@@ -2,84 +2,144 @@ import { validateUtmParams, sanitizeUtmParams } from '../../src/utils/utm/utm';
 
 describe('UTM Utils', () => {
   describe('validateUtmParams', () => {
-    it('should return true for undefined or null utm', () => {
-      expect(validateUtmParams(undefined)).toBe(true);
-      expect(validateUtmParams(null as any)).toBe(true);
+    it('should return valid result for undefined or null utm', () => {
+      expect(validateUtmParams(undefined)).toEqual({
+        isValid: true,
+        validKeys: [],
+        invalidKeys: [],
+      });
+      expect(validateUtmParams(null as any)).toEqual({
+        isValid: true,
+        validKeys: [],
+        invalidKeys: [],
+      });
     });
 
-    it('should return true for empty object', () => {
-      expect(validateUtmParams({})).toBe(true);
+    it('should return valid result for empty object', () => {
+      expect(validateUtmParams({})).toEqual({ isValid: true, validKeys: [], invalidKeys: [] });
     });
 
-    it('should return false for non-object types', () => {
-      expect(validateUtmParams('string' as any)).toBe(false);
-      expect(validateUtmParams(123 as any)).toBe(false);
-      expect(validateUtmParams(true as any)).toBe(false);
-      expect(validateUtmParams([] as any)).toBe(false);
+    it('should return invalid result for non-object types', () => {
+      expect(validateUtmParams('string' as any)).toEqual({
+        isValid: false,
+        validKeys: [],
+        invalidKeys: ['_structure'],
+      });
+      expect(validateUtmParams(123 as any)).toEqual({
+        isValid: false,
+        validKeys: [],
+        invalidKeys: ['_structure'],
+      });
+      expect(validateUtmParams(true as any)).toEqual({
+        isValid: false,
+        validKeys: [],
+        invalidKeys: ['_structure'],
+      });
+      expect(validateUtmParams([] as any)).toEqual({
+        isValid: false,
+        validKeys: [],
+        invalidKeys: ['_structure'],
+      });
     });
 
-    it('should return false for invalid UTM keys', () => {
-      expect(validateUtmParams({ invalidKey: 'value' } as any)).toBe(false);
-      expect(validateUtmParams({ source: 'google', invalidKey: 'value' } as any)).toBe(false);
+    it('should identify invalid UTM keys', () => {
+      const result1 = validateUtmParams({ invalidKey: 'value' } as any);
+      expect(result1.isValid).toBe(false);
+      expect(result1.invalidKeys).toContain('invalidKey');
+      expect(result1.validKeys).toEqual([]);
+
+      const result2 = validateUtmParams({ source: 'google', invalidKey: 'value' } as any);
+      expect(result2.isValid).toBe(false);
+      expect(result2.invalidKeys).toContain('invalidKey');
+      expect(result2.validKeys).toContain('source');
     });
 
-    it('should return true for valid UTM keys', () => {
-      expect(validateUtmParams({ source: 'google' })).toBe(true);
-      expect(validateUtmParams({ medium: 'cpc' })).toBe(true);
-      expect(validateUtmParams({ campaign: 'spring_2025' })).toBe(true);
-      expect(validateUtmParams({ content: 'ad_variant_a' })).toBe(true);
-      expect(validateUtmParams({ term: 'error_tracker' })).toBe(true);
+    it('should return valid result for valid UTM keys', () => {
+      const result1 = validateUtmParams({ source: 'google' });
+      expect(result1.isValid).toBe(true);
+      expect(result1.validKeys).toContain('source');
+      expect(result1.invalidKeys).toEqual([]);
+
+      const result2 = validateUtmParams({ medium: 'cpc' });
+      expect(result2.isValid).toBe(true);
+      expect(result2.validKeys).toContain('medium');
     });
 
-    it('should return true for multiple valid UTM keys', () => {
+    it('should validate multiple UTM keys correctly', () => {
       const validUtm = {
         source: 'google',
         medium: 'cpc',
         campaign: 'spring_2025_launch',
         content: 'ad_variant_a',
         term: 'error_tracker',
       };
-      expect(validateUtmParams(validUtm)).toBe(true);
+      const result = validateUtmParams(validUtm);
+      expect(result.isValid).toBe(true);
+      expect(result.validKeys).toEqual(['source', 'medium', 'campaign', 'content', 'term']);
+      expect(result.invalidKeys).toEqual([]);
     });
 
-    it('should return false for non-string values', () => {
-      expect(validateUtmParams({ source: 123 } as any)).toBe(false);
-      expect(validateUtmParams({ source: true } as any)).toBe(false);
-      expect(validateUtmParams({ source: {} } as any)).toBe(false);
-      expect(validateUtmParams({ source: [] } as any)).toBe(false);
+    it('should identify non-string values as invalid', () => {
+      const result1 = validateUtmParams({ source: 123 } as any);
+      expect(result1.isValid).toBe(false);
+      expect(result1.invalidKeys).toContain('source');
+
+      const result2 = validateUtmParams({ source: 'google', medium: true } as any);
+      expect(result2.isValid).toBe(false);
+      expect(result2.validKeys).toContain('source');
+      expect(result2.invalidKeys).toContain('medium');
     });
 
-    it('should return false for empty string values', () => {
-      expect(validateUtmParams({ source: '' })).toBe(false);
+    it('should identify empty string values as invalid', () => {
+      const result = validateUtmParams({ source: '' });
+      expect(result.isValid).toBe(false);
+      expect(result.invalidKeys).toContain('source');
     });
 
-    it('should return false for values that are too long', () => {
+    it('should identify values that are too long as invalid', () => {
       const longValue = 'a'.repeat(201);
-      expect(validateUtmParams({ source: longValue })).toBe(false);
+      const result = validateUtmParams({ source: longValue });
+      expect(result.isValid).toBe(false);
+      expect(result.invalidKeys).toContain('source');
     });
 
-    it('should return true for values at maximum length', () => {
+    it('should accept values at maximum length', () => {
       const maxLengthValue = 'a'.repeat(200);
-      expect(validateUtmParams({ source: maxLengthValue })).toBe(true);
+      const result = validateUtmParams({ source: maxLengthValue });
+      expect(result.isValid).toBe(true);
+      expect(result.validKeys).toContain('source');
+    });
+
+    it('should identify values with invalid characters', () => {
+      const result = validateUtmParams({ source: 'google@example' });
+      expect(result.isValid).toBe(false);
+      expect(result.invalidKeys).toContain('source');
     });
 
-    it('should return false for values with invalid characters', () => {
-      expect(validateUtmParams({ source: 'google@example' })).toBe(false);
-      expect(validateUtmParams({ source: 'google#hash' })).toBe(false);
-      expect(validateUtmParams({ source: 'google$money' })).toBe(false);
-      expect(validateUtmParams({ source: 'google%percent' })).toBe(false);
+    it('should accept values with valid characters', () => {
+      const result = validateUtmParams({ source: 'google-ads' });
+      expect(result.isValid).toBe(true);
+      expect(result.validKeys).toContain('source');
     });
 
-    it('should return true for values with valid characters', () => {
-      expect(validateUtmParams({ source: 'google-ads' })).toBe(true);
-      expect(validateUtmParams({ source: 'google_ads' })).toBe(true);
-      expect(validateUtmParams({ source: 'google.com' })).toBe(true);
-      expect(validateUtmParams({ source: 'Google Ads 123' })).toBe(true);
+    it('should handle mixed valid and invalid keys', () => {
+      const input = {
+        source: 'google',
+        medium: 'invalid@chars',
+        campaign: 'valid_campaign',
+        invalidKey: 'value',
+      } as any;
+      const result = validateUtmParams(input);
+      expect(result.isValid).toBe(false);
+      expect(result.validKeys).toEqual(['source', 'campaign']);
+      expect(result.invalidKeys).toEqual(['medium', 'invalidKey']);
     });
 
     it('should handle undefined and null values in object', () => {
-      expect(validateUtmParams({ source: 'google', medium: undefined })).toBe(true);
-      expect(validateUtmParams({ source: 'google', medium: null as any })).toBe(true);
+      const result = validateUtmParams({ source: 'google', medium: undefined });
+      expect(result.isValid).toBe(true);
+      expect(result.validKeys).toContain('source');
+      expect(result.validKeys).toContain('medium');
     });
   });