@jmruthers/pace-core 0.6.4 → 0.6.6

package/src/utils/persistence/keyDerivation.ts

@@ -0,0 +1,304 @@
+/**
+ * @file Key Derivation Utilities
+ * @package @jmruthers/pace-core
+ * @module Utils/Persistence
+ * @since 1.0.0
+ *
+ * Utilities for automatically deriving stable persistence keys for components.
+ * Provides deterministic key generation based on component props, route, and context.
+ *
+ * Features:
+ * - Automatic key derivation from component props
+ * - Route-based fallbacks when props unavailable
+ * - Stable hashing for fingerprint-based keys
+ * - Support for nested component contexts
+ *
+ * @dependencies
+ * - React Router (optional) - For route-based keys
+ */
+
+/**
+ * Simple hash function for creating stable fingerprints
+ * Uses djb2 algorithm for fast, stable hashing
+ */
+function hashString(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash) + str.charCodeAt(i);
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+  // Convert to positive hex string
+  return Math.abs(hash).toString(16);
+}
+
+/**
+ * Create a stable hash from an array of strings
+ */
+function hashStableFingerprint(values: string[]): string {
+  const normalized = values
+    .filter(Boolean)
+    .map((v) => String(v).toLowerCase().trim())
+    .sort()
+    .join('|');
+  
+  return hashString(normalized);
+}
+
+/**
+ * Normalize a string for use in storage keys
+ * Removes special characters and converts to lowercase
+ * Preserves path structure by keeping slashes
+ */
+function normalizeKey(str: string, preserveSlashes = false): string {
+  if (preserveSlashes) {
+    // For pathnames, preserve slashes but normalize other characters
+    const trimmed = str.toLowerCase().trim();
+    const hasLeadingSlash = trimmed.startsWith('/');
+    const parts = trimmed.split('/').map(segment => segment.replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')).filter(Boolean);
+    const normalized = parts.join('/');
+    return hasLeadingSlash ? `/${normalized}` : normalized;
+  }
+  return str
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Get route pathname if React Router is available
+ * Returns null if router is not available
+ */
+function getRoutePathname(): string | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+
+  try {
+    // Try to use React Router's useLocation if available
+    // Since we can't use hooks here, we'll use window.location as fallback
+    // Components using this should pass location from useLocation() hook
+    return window.location.pathname;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Props for DataTable key derivation
+ */
+export interface DataTableKeyProps {
+  /** RBAC page ID (mandatory, always available) */
+  rbacPageId?: string;
+  /** Table title */
+  title?: string;
+  /** Column IDs for fingerprint fallback */
+  columnIds?: string[];
+}
+
+/**
+ * Derive a persistence key for DataTable component
+ *
+ * Priority order:
+ * 1. rbac.pageId (mandatory prop, always available)
+ * 2. title prop (normalized)
+ * 3. Hashed fingerprint of column IDs
+ * 4. Route pathname + component type (only if not root path)
+ *
+ * @param props - DataTable props
+ * @param location - Optional location from useLocation() hook
+ * @param userId - Optional user ID to scope persistence by user
+ * @returns Derived key or null if no stable key can be determined
+ */
+export function deriveDataTableKey(
+  props: DataTableKeyProps,
+  location?: { pathname: string } | null,
+  userId?: string | null
+): string | null {
+  let baseKey: string | null = null;
+
+  // Priority 1: rbac.pageId (mandatory, always available)
+  if (props.rbacPageId) {
+    baseKey = `datatable:${normalizeKey(props.rbacPageId)}`;
+  }
+  // Priority 2: title prop
+  else if (props.title) {
+    baseKey = `datatable:${normalizeKey(props.title)}`;
+  }
+  // Priority 3: Hashed fingerprint of column IDs (before pathname fallback)
+  else if (props.columnIds && props.columnIds.length > 0) {
+    const fingerprint = hashStableFingerprint(props.columnIds);
+    if (fingerprint) {
+      baseKey = `datatable:${fingerprint}`;
+    }
+  }
+  // Priority 4: Route pathname + component type (only if not root path)
+  else {
+    const pathname = location?.pathname || getRoutePathname();
+    if (pathname && pathname !== '/') {
+      // Preserve path structure with slashes
+      const normalized = normalizeKey(pathname, true);
+      baseKey = `datatable:${normalized}`;
+    }
+  }
+
+  // No stable key can be determined
+  if (!baseKey) {
+    return null;
+  }
+
+  // Scope by user ID if provided (prevents data leakage between users)
+  if (userId) {
+    return `${baseKey}:user:${userId}`;
+  }
+
+  return baseKey;
+}
+
+/**
+ * Props for Dialog key derivation
+ */
+export interface DialogKeyProps {
+  /** Dialog title */
+  title?: string;
+  /** Dialog description (for fingerprint fallback) */
+  description?: string;
+}
+
+/**
+ * Derive a persistence key for Dialog component
+ *
+ * Priority order:
+ * 1. title prop (if stable and provided)
+ * 2. Route pathname + component type
+ * 3. Hashed fingerprint of dialog content structure
+ *
+ * @param props - Dialog props
+ * @param location - Optional location from useLocation() hook
+ * @param userId - Optional user ID to scope persistence by user
+ * @returns Derived key or null if no stable key can be determined
+ */
+export function deriveDialogKey(
+  props: DialogKeyProps,
+  location?: { pathname: string } | null,
+  userId?: string | null
+): string | null {
+  let baseKey: string | null = null;
+
+  // Priority 1: title prop
+  if (props.title) {
+    baseKey = `dialog:${normalizeKey(props.title)}`;
+  }
+  // Priority 2: Route pathname + component type
+  else {
+    const pathname = location?.pathname || getRoutePathname();
+    if (pathname && pathname !== '/') {
+      // Preserve path structure with slashes
+      const normalized = normalizeKey(pathname, true);
+      baseKey = `dialog:${normalized}`;
+    }
+    // Priority 3: Hashed fingerprint of dialog structure
+    else {
+      const fingerprintParts: string[] = [];
+      if (props.description) {
+        fingerprintParts.push(props.description);
+      }
+      
+      if (fingerprintParts.length > 0) {
+        const fingerprint = hashStableFingerprint(fingerprintParts);
+        baseKey = `dialog:${fingerprint}`;
+      }
+    }
+  }
+
+  // No stable key can be determined
+  if (!baseKey) {
+    return null;
+  }
+
+  // Scope by user ID if provided (prevents data leakage between users)
+  if (userId) {
+    return `${baseKey}:user:${userId}`;
+  }
+
+  return baseKey;
+}
+
+/**
+ * Props for Form key derivation
+ */
+export interface FormKeyProps {
+  /** Form field names (for fingerprint fallback) */
+  fieldNames?: string[];
+  /** Parent dialog title (if form is inside dialog) */
+  parentDialogTitle?: string;
+}
+
+/**
+ * Derive a persistence key for Form component
+ *
+ * Priority order:
+ * 1. Parent Dialog's title (if inside Dialog)
+ * 2. Route pathname + form field names hash
+ * 3. Route pathname + component type
+ *
+ * @param props - Form props
+ * @param parentContext - Optional parent context (e.g., Dialog title)
+ * @param location - Optional location from useLocation() hook
+ * @param userId - Optional user ID to scope persistence by user
+ * @returns Derived key or null if no stable key can be determined
+ */
+export function deriveFormKey(
+  props: FormKeyProps = {},
+  parentContext?: { dialogTitle?: string } | null,
+  location?: { pathname: string } | null,
+  userId?: string | null
+): string | null {
+  let baseKey: string | null = null;
+
+  // Priority 1: Parent Dialog's title
+  const dialogTitle = parentContext?.dialogTitle || props.parentDialogTitle;
+  if (dialogTitle) {
+    baseKey = `form:${normalizeKey(dialogTitle)}`;
+  }
+  // Priority 2: Route pathname + form field names hash
+  else {
+    const pathname = location?.pathname || getRoutePathname();
+    if (pathname && pathname !== '/' && props.fieldNames && props.fieldNames.length > 0) {
+      const fieldHash = hashStableFingerprint(props.fieldNames);
+      if (fieldHash) {
+        // Preserve path structure with slashes
+        const normalized = normalizeKey(pathname, true);
+        baseKey = `form:${normalized}:${fieldHash}`;
+      }
+    }
+    // Priority 3: Route pathname + component type
+    else if (pathname && pathname !== '/') {
+      // Preserve path structure with slashes
+      const normalized = normalizeKey(pathname, true);
+      baseKey = `form:${normalized}`;
+    }
+  }
+
+  // No stable key can be determined
+  if (!baseKey) {
+    return null;
+  }
+
+  // Scope by user ID if provided (prevents data leakage between users)
+  if (userId) {
+    return `${baseKey}:user:${userId}`;
+  }
+
+  return baseKey;
+}
+
+/**
+ * Create a stable hash from an array of values
+ * Exported for use in components that need custom fingerprinting
+ *
+ * @param values - Array of string values to hash
+ * @returns Stable hash string
+ */
+export { hashStableFingerprint };
+

package/src/utils/persistence/sensitiveFieldDetection.ts

@@ -0,0 +1,212 @@
+/**
+ * @file Sensitive Field Detection
+ * @package @jmruthers/pace-core
+ * @module Utils/Persistence
+ * @since 1.0.0
+ *
+ * Utilities for detecting and filtering sensitive fields that should not be persisted.
+ * Provides pattern matching and type-based detection for sensitive data.
+ *
+ * Features:
+ * - Pattern-based field name matching
+ * - Input type-based detection
+ * - Safe filtering of sensitive fields from data objects
+ * - Configurable denylist patterns
+ *
+ * Security:
+ * - Defaults to NOT persisting when uncertain
+ * - Comprehensive pattern matching for common sensitive fields
+ * - Type-based detection for password and hidden inputs
+ */
+
+/**
+ * Denylist patterns for sensitive field names (case-insensitive)
+ * Matches any field name containing these patterns
+ */
+const SENSITIVE_FIELD_PATTERNS = [
+  // Authentication and credentials
+  /password/i,
+  /secret/i,
+  /token/i,
+  /key/i,
+  /credential/i,
+  /auth/i,
+  /api[_-]?key/i,
+  /access[_-]?token/i,
+  /refresh[_-]?token/i,
+  /session[_-]?id/i,
+
+  // Payment information
+  /credit[_-]?card/i,
+  /card[_-]?number/i,
+  /cvv/i,
+  /cvc/i,
+  /pin/i,
+  /account[_-]?number/i,
+  /routing[_-]?number/i,
+
+  // Personal identification
+  /ssn/i,
+  /social[_-]?security/i,
+  /tax[_-]?id/i,
+  /driver[_-]?license/i,
+  /passport/i,
+
+  // Medical and health information
+  /medical/i,
+  /health/i,
+  /phi/i, // Protected Health Information
+  /hipaa/i,
+  /diagnosis/i,
+  /prescription/i,
+
+  // Other sensitive data
+  /private[_-]?key/i,
+  /signing[_-]?key/i,
+  /encryption[_-]?key/i,
+];
+
+/**
+ * Sensitive input types that should never be persisted
+ */
+const SENSITIVE_INPUT_TYPES = new Set([
+  'password',
+  'hidden',
+]);
+
+/**
+ * Check if a field name matches sensitive patterns
+ *
+ * @param name - Field name to check
+ * @returns true if field is sensitive
+ */
+function isSensitiveFieldName(name: string): boolean {
+  if (!name || typeof name !== 'string') {
+    return false;
+  }
+
+  const normalizedName = name.trim();
+  if (normalizedName.length === 0) {
+    return false;
+  }
+
+  // Check against denylist patterns
+  return SENSITIVE_FIELD_PATTERNS.some((pattern) => pattern.test(normalizedName));
+}
+
+/**
+ * Check if an input type is sensitive
+ *
+ * @param type - Input type to check
+ * @returns true if input type is sensitive
+ */
+function isSensitiveInputType(type?: string): boolean {
+  if (!type || typeof type !== 'string') {
+    return false;
+  }
+
+  return SENSITIVE_INPUT_TYPES.has(type.toLowerCase().trim());
+}
+
+/**
+ * Check if a field is sensitive based on name and/or type
+ *
+ * @param name - Field name
+ * @param type - Optional input type
+ * @returns true if field should not be persisted
+ *
+ * @example
+ * ```ts
+ * isSensitiveField('password', 'password'); // true
+ * isSensitiveField('email', 'text'); // false
+ * isSensitiveField('api_key', 'text'); // true
+ * ```
+ */
+export function isSensitiveField(name: string, type?: string): boolean {
+  // Check input type first (most reliable)
+  if (isSensitiveInputType(type)) {
+    return true;
+  }
+
+  // Check field name patterns
+  if (isSensitiveFieldName(name)) {
+    return true;
+  }
+
+  // Default to NOT sensitive when uncertain
+  return false;
+}
+
+/**
+ * Filter sensitive fields from a data object
+ *
+ * Creates a new object with only non-sensitive fields.
+ * When uncertain, fields are excluded (safe default).
+ *
+ * @template T - Type of the data object
+ * @param data - Data object to filter
+ * @param fieldNames - Array of field names in the data
+ * @param fieldTypes - Optional map of field names to input types
+ * @returns Filtered data with sensitive fields removed
+ *
+ * @example
+ * ```ts
+ * const data = { name: 'John', password: 'secret123', email: 'john@example.com' };
+ * const filtered = filterSensitiveFields(data, ['name', 'password', 'email'], {
+ *   password: 'password'
+ * });
+ * // Result: { name: 'John', email: 'john@example.com' }
+ * ```
+ */
+export function filterSensitiveFields<T extends Record<string, any>>(
+  data: T,
+  fieldNames: string[],
+  fieldTypes?: Record<string, string>
+): Partial<T> {
+  if (!data || typeof data !== 'object') {
+    return {};
+  }
+
+  const filtered: Partial<T> = {};
+
+  for (const fieldName of fieldNames) {
+    // Skip if field doesn't exist in data
+    if (!(fieldName in data)) {
+      continue;
+    }
+
+    // Get field type if provided
+    const fieldType = fieldTypes?.[fieldName];
+
+    // Check if field is sensitive
+    if (isSensitiveField(fieldName, fieldType)) {
+      // Skip sensitive field
+      continue;
+    }
+
+    // Include non-sensitive field
+    filtered[fieldName as keyof T] = data[fieldName];
+  }
+
+  return filtered;
+}
+
+/**
+ * Get list of sensitive field names from an array of field names
+ *
+ * Useful for logging or debugging which fields were filtered.
+ *
+ * @param fieldNames - Array of field names to check
+ * @param fieldTypes - Optional map of field names to input types
+ * @returns Array of sensitive field names
+ */
+export function getSensitiveFieldNames(
+  fieldNames: string[],
+  fieldTypes?: Record<string, string>
+): string[] {
+  return fieldNames.filter((name) => {
+    const type = fieldTypes?.[name];
+    return isSensitiveField(name, type);
+  });
+}
+

package/src/utils/security/secureStorage.ts

@@ -37,7 +37,7 @@ class SecureStorageImpl {
               false,
               ['encrypt', 'decrypt']
             );
-          } catch (error) {
+          } catch (_error) {
             await this.generateNewKey();
           }
         } else {
@@ -45,7 +45,7 @@ class SecureStorageImpl {
         }
       }
       this.initialized = true;
-    } catch (error) {
+    } catch (_error) {
       this.initialized = true;
     }
   }
@@ -101,7 +101,7 @@ class SecureStorageImpl {
         }
         
         return parsed.value;
-      } catch (error) {
+      } catch (_error) {
         // Silent fail - try plain storage
       }
     }
@@ -120,7 +120,7 @@ class SecureStorageImpl {
       }
       
       return parsed.value || plainData;
-    } catch (error) {
+    } catch (_error) {
       // If parsing fails, return as-is (backward compatibility)
       return plainData;
     }
@@ -163,7 +163,7 @@ class SecureStorageImpl {
       const exportedKey = await window.crypto.subtle.exportKey('raw', this.encryptionKey);
       const keyData = this.arrayBufferToBase64(exportedKey);
       localStorage.setItem('_sec_key', keyData);
-    } catch (error) {
+    } catch (_error) {
       // Silent fail - encryption not available
     }
   }

package/src/utils/storage/helpers.ts

@@ -106,7 +106,7 @@ export async function extractFileMetadata(
       const dimensions = await getImageDimensions(file);
       metadata.width = dimensions.width;
       metadata.height = dimensions.height;
-    } catch (error) {
+    } catch (_error) {
       // Non-critical error - image dimensions are optional metadata
       // Using Logger would be better, but this is in a utility function
       // For now, silently continue - dimensions are optional
@@ -116,7 +116,7 @@ export async function extractFileMetadata(
   // Generate file hash if possible
   try {
     metadata.hash = await generateFileHash(file);
-  } catch (error) {
+  } catch (_error) {
     // Non-critical error - file hash is optional metadata
     // Using Logger would be better, but this is in a utility function
     // For now, silently continue - hash is optional
@@ -320,7 +320,7 @@ export function getPublicUrl(
   }
 
   // Normalise path by trimming whitespace and leading slashes
-  let normalisedPath = path.trim().replace(/^\/+/, '');
+  const normalisedPath = path.trim().replace(/^\/+/, '');
 
   if (!normalisedPath) {
     throw new Error('Storage path cannot be empty after normalisation');