@od-oneapp/analytics 2026.1.1301

package/src/shared/utils/security.ts

@@ -0,0 +1,545 @@
+/**
+ * @fileoverview Security and sanitization utilities for analytics data
+ *
+ * This module provides comprehensive security utilities for analytics data:
+ *
+ * - **PII Detection**: Detects personally identifiable information (emails, phones, SSNs, credit cards, IPs)
+ * - **PII Redaction**: Redacts PII from strings before sending to analytics
+ * - **XSS Protection**: Strips HTML and script tags to prevent XSS attacks
+ * - **Property Validation**: Validates property keys to prevent prototype pollution
+ * - **Payload Sanitization**: Comprehensive sanitization with size limits and depth checks
+ * - **Size Limits**: Enforces maximum property and payload sizes
+ *
+ * **Security Features**:
+ * - Maximum property value size: 100KB
+ * - Maximum payload size: 1MB
+ * - Maximum nesting depth: 10 levels
+ * - Dangerous key filtering (prevents prototype pollution)
+ * - HTML/script tag removal
+ *
+ * @module @od-oneapp/analytics/shared/utils/security
+ */
+
+import { logWarn } from '@repo/shared/logger';
+
+/**
+ * Maximum allowed property value size (100KB).
+ *
+ * Prevents sending excessively large property values to analytics providers.
+ *
+ * @internal
+ */
+const MAX_PROPERTY_VALUE_SIZE = 100 * 1024;
+
+/**
+ * Maximum allowed total payload size (1MB).
+ *
+ * Prevents sending excessively large payloads to analytics providers.
+ *
+ * @internal
+ */
+const MAX_PAYLOAD_SIZE = 1024 * 1024;
+
+/**
+ * Maximum allowed object nesting depth.
+ *
+ * Prevents deeply nested objects that could cause performance issues or stack overflows.
+ *
+ * @internal
+ */
+const MAX_DEPTH = 10;
+
+/**
+ * PII patterns for detection and filtering
+ * Note: These regexes are intentionally complex for accurate PII detection.
+ * They are used only on bounded, sanitized input with size limits.
+ */
+/* eslint-disable security/detect-unsafe-regex */
+const PII_PATTERNS = {
+  email: /\b[\w%+.-]+@[\d.A-Za-z-]+\.[A-Za-z|]{2,}\b/g,
+  phone: /\b(?:\+?1[.-]?)?\(?(\d{3})\)?[.-]?(\d{3})[.-]?(\d{4})\b/g,
+  ssn: /\b\d{3}-?\d{2}-?\d{4}\b/g,
+  creditCard: /\b(?:\d{4}[ -]?){3}\d{4}\b/g,
+  ipv4: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+  ipv6: /\b(?:[\da-f]{1,4}:){7}[\da-f]{1,4}\b/gi,
+};
+/* eslint-enable security/detect-unsafe-regex */
+
+/**
+ * Dangerous property keys that should never be allowed
+ */
+const DANGEROUS_KEYS = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+  '__defineGetter__',
+  '__defineSetter__',
+  '__lookupGetter__',
+  '__lookupSetter__',
+]);
+
+/**
+ * HTML/Script patterns for XSS protection
+ * Note: These regexes are intentionally complex for accurate XSS detection.
+ * They are used only on bounded, sanitized input with size limits.
+ */
+/* eslint-disable security/detect-unsafe-regex */
+const XSS_PATTERNS = {
+  scriptTag: /<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi,
+  onEvent: /\bon\w+\s*=\s*["'][^"']*["']/gi,
+  javascript: /javascript:/gi,
+  dataUri: /data:text\/html/gi,
+};
+/* eslint-enable security/detect-unsafe-regex */
+
+/**
+ * Sanitization options.
+ *
+ * Configures how sanitization should be performed, including size limits,
+ * depth limits, and what content to strip.
+ */
+export interface SanitizationOptions {
+  /** Maximum object nesting depth */
+  maxDepth?: number;
+  /** Maximum size per property value in bytes */
+  maxPropertySize?: number;
+  /** Maximum total payload size in bytes */
+  maxPayloadSize?: number;
+  /** Pattern for allowed property keys */
+  allowedKeyPattern?: RegExp;
+  /** Whether to strip PII */
+  stripPII?: boolean;
+  /** Whether to strip HTML/scripts */
+  stripHTML?: boolean;
+  /** Whether to allow prototype pollution keys */
+  allowDangerousKeys?: boolean;
+}
+
+/**
+ * Sanitization result.
+ *
+ * Contains the sanitized data, whether modifications were made, and any warnings
+ * generated during sanitization.
+ */
+export interface SanitizationResult<T = unknown> {
+  /** Sanitized data */
+  data: T;
+  /** Whether sanitization made changes */
+  modified: boolean;
+  /** Warnings generated during sanitization */
+  warnings: string[];
+}
+
+/**
+ * Check if a value contains PII (Personally Identifiable Information).
+ *
+ * Detects common PII patterns including:
+ * - Email addresses
+ * - Phone numbers
+ * - Social Security Numbers
+ * - Credit card numbers
+ * - IPv4 and IPv6 addresses
+ *
+ * @param {string} value - String value to check for PII
+ * @returns {boolean} `true` if PII is detected, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (containsPII(userInput)) {
+ *   const sanitized = redactPII(userInput);
+ *   // Use sanitized value
+ * }
+ * ```
+ */
+export function containsPII(value: string): boolean {
+  return Object.values(PII_PATTERNS).some(pattern => pattern.test(value));
+}
+
+/**
+ * Redact PII from a string.
+ *
+ * Replaces detected PII patterns with `[REDACTED_TYPE]` placeholders.
+ * Useful for logging or analytics where PII should not be stored.
+ *
+ * @param {string} value - String value to redact PII from
+ * @returns {string} String with PII redacted
+ *
+ * @example
+ * ```typescript
+ * const sanitized = redactPII('Contact john@example.com at 555-1234');
+ * // Returns: 'Contact [REDACTED_EMAIL] at [REDACTED_PHONE]'
+ * ```
+ */
+export function redactPII(value: string): string {
+  let redacted = value;
+
+  for (const [type, pattern] of Object.entries(PII_PATTERNS)) {
+    redacted = redacted.replace(pattern, `[REDACTED_${type.toUpperCase()}]`);
+  }
+
+  return redacted;
+}
+
+/**
+ * Strip HTML and script tags from a string.
+ *
+ * Removes HTML tags, script tags, event handlers, and other potentially dangerous
+ * content to prevent XSS attacks. Also removes `data:text/html` URIs.
+ *
+ * @param {string} value - String value to strip HTML from
+ * @returns {string} String with HTML and scripts removed
+ *
+ * @example
+ * ```typescript
+ * const sanitized = stripHTML('<script>alert("xss")</script>Hello');
+ * // Returns: 'Hello'
+ * ```
+ */
+export function stripHTML(value: string): string {
+  let stripped = value;
+
+  for (const pattern of Object.values(XSS_PATTERNS)) {
+    stripped = stripped.replace(pattern, '');
+  }
+
+  // Additional cleanup for remaining tags
+  stripped = stripped.replaceAll(/<[^>]*>/g, '');
+
+  return stripped;
+}
+
+/**
+ * Validate that a property key is safe.
+ *
+ * Checks for dangerous keys that could cause prototype pollution or other
+ * security issues. Also validates against allowed key patterns if provided.
+ *
+ * @param {string} key - Property key to validate
+ * @param {SanitizationOptions} [options] - Sanitization options
+ * @returns {{ valid: boolean; reason?: string }} Validation result with reason if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = isValidPropertyKey('__proto__');
+ * if (!result.valid) {
+ *   console.warn('Unsafe key:', result.reason);
+ * }
+ * ```
+ */
+export function isValidPropertyKey(
+  key: string,
+  options: SanitizationOptions = {},
+): { valid: boolean; reason?: string } {
+  // Check for dangerous keys
+  if (!options.allowDangerousKeys && DANGEROUS_KEYS.has(key)) {
+    return { valid: false, reason: 'Dangerous key that could cause prototype pollution' };
+  }
+
+  // Check against allowed pattern
+  if (options.allowedKeyPattern && !options.allowedKeyPattern.test(key)) {
+    return { valid: false, reason: 'Key does not match allowed pattern' };
+  }
+
+  // Check for special characters that could cause issues
+  if (/[<>[\\\]{}]/.test(key)) {
+    return { valid: false, reason: 'Key contains potentially dangerous characters' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Get the size of a value in bytes
+ */
+function getValueSize(value: unknown): number {
+  if (typeof value === 'string') {
+    return new Blob([value]).size;
+  }
+
+  try {
+    return new Blob([JSON.stringify(value)]).size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Sanitize a single property value
+ */
+function sanitizeValue(
+  value: unknown,
+  options: SanitizationOptions,
+  warnings: string[],
+): { value: unknown; modified: boolean } {
+  if (value === null || value === undefined) {
+    return { value, modified: false };
+  }
+
+  let modified = false;
+
+  // Handle strings
+  if (typeof value === 'string') {
+    let sanitized = value;
+
+    // Check size
+    const size = getValueSize(value);
+    const maxSize = options.maxPropertySize ?? MAX_PROPERTY_VALUE_SIZE;
+
+    if (size > maxSize) {
+      sanitized = value.slice(0, Math.max(0, maxSize));
+      warnings.push(`String value truncated from ${size} to ${maxSize} bytes`);
+      modified = true;
+    }
+
+    // Strip PII if requested
+    if (options.stripPII && containsPII(sanitized)) {
+      sanitized = redactPII(sanitized);
+      warnings.push('PII detected and redacted from value');
+      modified = true;
+    }
+
+    // Strip HTML if requested
+    if (options.stripHTML) {
+      const stripped = stripHTML(sanitized);
+      if (stripped !== sanitized) {
+        sanitized = stripped;
+        warnings.push('HTML/scripts stripped from value');
+        modified = true;
+      }
+    }
+
+    return { value: sanitized, modified };
+  }
+
+  // Handle numbers, booleans, etc.
+  if (typeof value !== 'object') {
+    return { value, modified: false };
+  }
+
+  // Arrays and objects handled by sanitizeProperties
+  return { value, modified: false };
+}
+
+/**
+ * Sanitize analytics properties recursively.
+ *
+ * Comprehensive sanitization of analytics properties including:
+ * - Size limit enforcement
+ * - Depth limit enforcement
+ * - PII detection and redaction
+ * - HTML/script tag removal
+ * - Dangerous key filtering
+ * - Circular reference detection
+ *
+ * @param {T} properties - Properties to sanitize
+ * @param {SanitizationOptions} [options] - Sanitization options
+ * @returns {SanitizationResult<T>} Sanitization result with sanitized data and warnings
+ *
+ * @throws {Error} If properties contain circular references or exceed payload size limit
+ *
+ * @example
+ * ```typescript
+ * const result = sanitizeProperties({
+ *   user_email: 'test@example.com',
+ *   phone: '555-1234',
+ *   description: '<script>alert("xss")</script>Hello',
+ * }, {
+ *   stripPII: true,
+ *   stripHTML: true,
+ * });
+ *
+ * console.log(result.data);
+ * // {
+ * //   user_email: '[REDACTED_EMAIL]',
+ * //   phone: '[REDACTED_PHONE]',
+ * //   description: 'Hello'
+ * // }
+ * ```
+ */
+export function sanitizeProperties<T extends Record<string, unknown>>(
+  properties: T,
+  options: SanitizationOptions = {},
+): SanitizationResult<T> {
+  const warnings: string[] = [];
+  let modified = false;
+
+  // Check for circular references
+  try {
+    JSON.stringify(properties);
+  } catch {
+    throw new Error('Properties contain circular references');
+  }
+
+  // Check total payload size
+  const totalSize = getValueSize(properties);
+  const maxPayloadSize = options.maxPayloadSize ?? MAX_PAYLOAD_SIZE;
+
+  if (totalSize > maxPayloadSize) {
+    throw new Error(`Payload size ${totalSize} bytes exceeds maximum ${maxPayloadSize} bytes`);
+  }
+
+  /**
+   * Recursive sanitization helper
+   */
+  function sanitizeRecursive(
+    obj: Record<string, unknown>,
+    depth: number = 0,
+  ): Record<string, unknown> {
+    const maxDepth = options.maxDepth ?? MAX_DEPTH;
+
+    if (depth > maxDepth) {
+      warnings.push(`Maximum nesting depth ${maxDepth} exceeded, truncating`);
+      modified = true;
+      return {};
+    }
+
+    const sanitized: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(obj)) {
+      // Validate key
+      const keyValidation = isValidPropertyKey(key, options);
+      if (!keyValidation.valid) {
+        warnings.push(`Skipping dangerous key "${key}": ${keyValidation.reason}`);
+        modified = true;
+        continue;
+      }
+
+      // Handle null/undefined
+      if (value === null || value === undefined) {
+        sanitized[key] = value;
+        continue;
+      }
+
+      // Handle arrays
+      if (Array.isArray(value)) {
+        sanitized[key] = value.map(item => {
+          if (typeof item === 'object' && item !== null) {
+            return sanitizeRecursive(item as Record<string, unknown>, depth + 1);
+          }
+
+          const result = sanitizeValue(item, options, warnings);
+          if (result.modified) modified = true;
+          return result.value;
+        });
+        continue;
+      }
+
+      // Handle objects
+      if (typeof value === 'object') {
+        sanitized[key] = sanitizeRecursive(value as Record<string, unknown>, depth + 1);
+        continue;
+      }
+
+      // Handle primitives
+      const result = sanitizeValue(value, options, warnings);
+      if (result.modified) modified = true;
+      sanitized[key] = result.value;
+    }
+
+    return sanitized;
+  }
+
+  const sanitized = sanitizeRecursive(properties) as T;
+
+  // Log warnings in development
+  if (warnings.length > 0 && process.env.NODE_ENV === 'development') {
+    logWarn('Analytics properties sanitization warnings', { warnings });
+  }
+
+  return {
+    data: sanitized,
+    modified,
+    warnings,
+  };
+}
+
+/**
+ * Validate event name.
+ *
+ * Checks that an event name is safe and follows best practices:
+ * - Non-empty string
+ * - Not exceeding 255 characters
+ * - No XSS patterns
+ *
+ * @param {string} event - Event name to validate
+ * @returns {{ valid: boolean; reason?: string }} Validation result with reason if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateEventName('Button Clicked');
+ * if (!result.valid) {
+ *   console.error('Invalid event name:', result.reason);
+ * }
+ * ```
+ */
+export function validateEventName(event: string): {
+  valid: boolean;
+  reason?: string;
+} {
+  if (!event || typeof event !== 'string') {
+    return { valid: false, reason: 'Event name must be a non-empty string' };
+  }
+
+  if (event.trim() === '') {
+    return { valid: false, reason: 'Event name cannot be empty or whitespace only' };
+  }
+
+  if (event.length > 255) {
+    return { valid: false, reason: 'Event name cannot exceed 255 characters' };
+  }
+
+  // Check for XSS patterns
+  if (Object.values(XSS_PATTERNS).some(pattern => pattern.test(event))) {
+    return { valid: false, reason: 'Event name contains potentially malicious content' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Safe property value types that can be tracked.
+ *
+ * Only includes primitive types that are safe to send to analytics providers.
+ */
+export type SafePropertyValue = string | number | boolean | null | undefined;
+
+/**
+ * Safe properties object type.
+ *
+ * Properties object with only safe value types.
+ */
+export type SafeProperties = Record<string, SafePropertyValue | SafePropertyValue[]>;
+
+/**
+ * Create a type-safe analytics properties object.
+ *
+ * Sanitizes raw properties and returns a type-safe properties object.
+ * Automatically strips PII in production and HTML/scripts always.
+ *
+ * @param {Record<string, unknown>} properties - Raw properties to make safe
+ * @returns {SafeProperties} Type-safe properties object
+ *
+ * @example
+ * ```typescript
+ * const safeProps = createSafeProperties({
+ *   userId: 'user-123',
+ *   email: 'user@example.com', // Will be redacted in production
+ *   html: '<script>alert("xss")</script>' // Will be stripped
+ * });
+ * ```
+ */
+export function createSafeProperties(properties: Record<string, unknown>): SafeProperties {
+  const result = sanitizeProperties(properties, {
+    stripPII: process.env.NODE_ENV === 'production',
+    stripHTML: true,
+    allowDangerousKeys: false,
+  });
+
+  if (result.warnings.length > 0 && process.env.NODE_ENV === 'development') {
+    logWarn('Created safe properties with sanitization', {
+      warnings: result.warnings,
+    });
+  }
+
+  return result.data as SafeProperties;
+}

package/src/shared/utils/validation-client.ts

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Client-safe validation utilities for analytics configuration
+ * Client-safe validation utilities for analytics configuration
+ * This file contains only validation functions that are safe to use in browser environments
+ */
+
+import { PROVIDER_REQUIREMENTS } from './config';
+
+import type { AnalyticsConfig, ProviderConfig } from '../types/types';
+
+interface ValidationError {
+  field: string;
+  message: string;
+  provider: string;
+}
+
+interface ValidationResult {
+  errors: ValidationError[];
+  isValid: boolean;
+  warnings: string[];
+}
+
+/**
+ * Comprehensive configuration validation (client-safe version)
+ * Accepts unknown input for defensive validation of potentially malformed configs
+ */
+export function validateAnalyticsConfig(config: unknown): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: string[] = [];
+
+  // Check if config exists and is an object
+  if (!config || typeof config !== 'object') {
+    errors.push({
+      provider: 'global',
+      field: 'config',
+      message: 'Analytics configuration is required and must be an object',
+    });
+    return { isValid: false, errors, warnings };
+  }
+
+  const typedConfig = config as AnalyticsConfig;
+
+  // Check if providers object exists
+  if (!typedConfig.providers || typeof typedConfig.providers !== 'object') {
+    errors.push({
+      provider: 'global',
+      field: 'providers',
+      message: 'Providers configuration is required and must be an object',
+    });
+    return { isValid: false, errors, warnings };
+  }
+
+  // Check if at least one provider is configured
+  const providerCount = Object.keys(typedConfig.providers).length;
+  if (providerCount === 0) {
+    warnings.push('No providers configured. Analytics will not track any events.');
+  }
+
+  // Validate each provider
+  for (const [providerName, providerConfig] of Object.entries(typedConfig.providers)) {
+    const providerErrors = validateProvider(providerName, providerConfig);
+    errors.push(...providerErrors);
+  }
+
+  // Environment-specific warnings
+  if (typedConfig.providers.mixpanel) {
+    warnings.push(
+      'Mixpanel provider configured on client-side. Consider using server-side for better performance.',
+    );
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validate a single provider configuration
+ */
+export function validateProvider(providerName: string, config: ProviderConfig): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Check if provider is known
+  const knownProviders = ['segment', 'posthog', 'vercel', 'console', 'mixpanel'];
+  if (!knownProviders.includes(providerName)) {
+    errors.push({
+      provider: providerName,
+      field: 'name',
+      message: `Unknown provider '${providerName}'. Known providers: ${knownProviders.join(', ')}`,
+    });
+    return errors;
+  }
+
+  // Check required fields
+  const requiredFields = PROVIDER_REQUIREMENTS[providerName] ?? [];
+  for (const field of requiredFields) {
+    const value = config[field as keyof ProviderConfig];
+
+    if (!value) {
+      errors.push({
+        provider: providerName,
+        field,
+        message: `Required field '${field}' is missing for provider '${providerName}'`,
+      });
+    } else if (typeof value === 'string' && value.trim() === '') {
+      errors.push({
+        provider: providerName,
+        field,
+        message: `Required field '${field}' cannot be empty for provider '${providerName}'`,
+      });
+    }
+  }
+
+  // Provider-specific validation
+  switch (providerName) {
+    case 'segment':
+      if (config.writeKey && !isValidSegmentWriteKey(config.writeKey)) {
+        errors.push({
+          provider: providerName,
+          field: 'writeKey',
+          message: 'Segment writeKey appears to be invalid format',
+        });
+      }
+      break;
+
+    case 'posthog':
+      if (config.apiKey && !isValidPostHogApiKey(config.apiKey)) {
+        errors.push({
+          provider: providerName,
+          field: 'apiKey',
+          message: 'PostHog apiKey appears to be invalid format',
+        });
+      }
+      break;
+  }
+
+  return errors;
+}
+
+/**
+ * Helper functions for format validation
+ */
+function isValidSegmentWriteKey(writeKey: string): boolean {
+  // Segment write keys are typically 32 characters, alphanumeric
+  return /^[\dA-Za-z]{20,40}$/.test(writeKey);
+}
+
+function isValidPostHogApiKey(apiKey: string): boolean {
+  // PostHog API keys start with 'phc_' followed by alphanumeric characters
+  return /^phc_[\dA-Za-z]{43}$/.test(apiKey);
+}
+
+/**
+ * Utility to validate configuration (client-safe version without throwing)
+ * Returns validation result instead of throwing errors
+ */
+export function validateConfig(config: AnalyticsConfig): ValidationResult {
+  return validateAnalyticsConfig(config);
+}