@jmruthers/pace-core 0.6.5 → 0.6.7

package/src/utils/index.ts

@@ -21,7 +21,7 @@ export * from './validation';
 // Explicitly re-export commonly used validation utilities to ensure they're available
 // Import from source modules to avoid re-export issues
 export { validateUserInput, usernameSchema } from './validation/validationUtils';
-export { sanitizeUserInput, sanitizeFormData } from './validation/sanitization';
+export { sanitizeUserInput, sanitizeFormData, sanitizeHtml } from './validation/sanitization';
 export { emailSchema, nameSchema, phoneSchema, urlSchema } from './validation/common';
 export { passwordSchema } from './validation/passwordSchema';
 export { pickSchema, combineSchemas } from './validation/schema';
@@ -178,3 +178,6 @@ export {
   getInFlightRequestStats,
   deduplicatedQuery
 } from './request-deduplication';
+
+// Supabase client creation (restricted wrapper)
+export { createBaseClient } from './supabase/createBaseClient';

package/src/utils/persistence/__tests__/keyDerivation.test.ts

@@ -0,0 +1,135 @@
+/**
+ * @file Key Derivation Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/Persistence/__tests__
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  deriveDataTableKey,
+  deriveDialogKey,
+  deriveFormKey,
+  hashStableFingerprint,
+} from '../keyDerivation';
+
+describe('keyDerivation', () => {
+  describe('deriveDataTableKey', () => {
+    it('should use rbacPageId as primary key', () => {
+      const key = deriveDataTableKey({
+        rbacPageId: 'user-management',
+      });
+      expect(key).toBe('datatable:user-management');
+    });
+
+    it('should fall back to title when rbacPageId not available', () => {
+      const key = deriveDataTableKey({
+        title: 'Users Table',
+      });
+      expect(key).toBe('datatable:users-table');
+    });
+
+    it('should use route pathname as fallback', () => {
+      const key = deriveDataTableKey(
+        {},
+        { pathname: '/users' }
+      );
+      expect(key).toBe('datatable:/users');
+    });
+
+    it('should use column IDs hash as last resort', () => {
+      const key = deriveDataTableKey({
+        columnIds: ['id', 'name', 'email'],
+      });
+      expect(key).toMatch(/^datatable:[a-f0-9]+$/);
+    });
+
+    it('should return null if no stable key can be determined', () => {
+      const key = deriveDataTableKey({});
+      expect(key).toBeNull();
+    });
+  });
+
+  describe('deriveDialogKey', () => {
+    it('should use title as primary key', () => {
+      const key = deriveDialogKey({
+        title: 'Edit User',
+      });
+      expect(key).toBe('dialog:edit-user');
+    });
+
+    it('should use route pathname as fallback', () => {
+      const key = deriveDialogKey(
+        {},
+        { pathname: '/users/edit' }
+      );
+      expect(key).toBe('dialog:/users/edit');
+    });
+
+    it('should return null if no stable key can be determined', () => {
+      const key = deriveDialogKey({});
+      expect(key).toBeNull();
+    });
+  });
+
+  describe('deriveFormKey', () => {
+    it('should use parent dialog title when available', () => {
+      const key = deriveFormKey(
+        {},
+        { dialogTitle: 'Edit User' }
+      );
+      expect(key).toBe('form:edit-user');
+    });
+
+    it('should use route + field names hash as fallback', () => {
+      const key = deriveFormKey(
+        {
+          fieldNames: ['name', 'email'],
+        },
+        null,
+        { pathname: '/users' }
+      );
+      expect(key).toMatch(/^form:\/users:[a-f0-9]+$/);
+    });
+
+    it('should use route pathname as last resort', () => {
+      const key = deriveFormKey(
+        {},
+        null,
+        { pathname: '/users' }
+      );
+      expect(key).toBe('form:/users');
+    });
+
+    it('should return null if no stable key can be determined', () => {
+      const key = deriveFormKey({});
+      expect(key).toBeNull();
+    });
+  });
+
+  describe('hashStableFingerprint', () => {
+    it('should create stable hash from array of strings', () => {
+      const hash1 = hashStableFingerprint(['a', 'b', 'c']);
+      const hash2 = hashStableFingerprint(['a', 'b', 'c']);
+      expect(hash1).toBe(hash2);
+    });
+
+    it('should be order-independent', () => {
+      const hash1 = hashStableFingerprint(['a', 'b', 'c']);
+      const hash2 = hashStableFingerprint(['c', 'b', 'a']);
+      expect(hash1).toBe(hash2);
+    });
+
+    it('should normalize strings (lowercase, trim)', () => {
+      const hash1 = hashStableFingerprint(['A', ' B ', 'C']);
+      const hash2 = hashStableFingerprint(['a', 'b', 'c']);
+      expect(hash1).toBe(hash2);
+    });
+
+    it('should filter out empty values', () => {
+      const hash1 = hashStableFingerprint(['a', '', 'b', 'c']);
+      const hash2 = hashStableFingerprint(['a', 'b', 'c']);
+      expect(hash1).toBe(hash2);
+    });
+  });
+});
+

package/src/utils/persistence/__tests__/sensitiveFieldDetection.test.ts

@@ -0,0 +1,123 @@
+/**
+ * @file Sensitive Field Detection Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/Persistence/__tests__
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  isSensitiveField,
+  filterSensitiveFields,
+  getSensitiveFieldNames,
+} from '../sensitiveFieldDetection';
+
+describe('sensitiveFieldDetection', () => {
+  describe('isSensitiveField', () => {
+    it('should detect password input type', () => {
+      expect(isSensitiveField('password', 'password')).toBe(true);
+      expect(isSensitiveField('userPassword', 'password')).toBe(true);
+    });
+
+    it('should detect hidden input type', () => {
+      expect(isSensitiveField('token', 'hidden')).toBe(true);
+    });
+
+    it('should detect sensitive field names by pattern', () => {
+      expect(isSensitiveField('password', 'text')).toBe(true);
+      expect(isSensitiveField('user_password', 'text')).toBe(true);
+      expect(isSensitiveField('api_key', 'text')).toBe(true);
+      expect(isSensitiveField('secretToken', 'text')).toBe(true);
+      expect(isSensitiveField('credit_card', 'text')).toBe(true);
+      expect(isSensitiveField('ssn', 'text')).toBe(true);
+    });
+
+    it('should not detect non-sensitive fields', () => {
+      expect(isSensitiveField('name', 'text')).toBe(false);
+      expect(isSensitiveField('email', 'email')).toBe(false);
+      expect(isSensitiveField('age', 'number')).toBe(false);
+    });
+
+    it('should be case-insensitive', () => {
+      expect(isSensitiveField('PASSWORD', 'text')).toBe(true);
+      expect(isSensitiveField('Api_Key', 'text')).toBe(true);
+    });
+  });
+
+  describe('filterSensitiveFields', () => {
+    it('should filter out sensitive fields', () => {
+      const data = {
+        name: 'John',
+        email: 'john@example.com',
+        password: 'secret123',
+        api_key: 'key123',
+      };
+
+      const filtered = filterSensitiveFields(data, ['name', 'email', 'password', 'api_key']);
+
+      expect(filtered).toEqual({
+        name: 'John',
+        email: 'john@example.com',
+      });
+      expect(filtered).not.toHaveProperty('password');
+      expect(filtered).not.toHaveProperty('api_key');
+    });
+
+    it('should filter by input type', () => {
+      const data = {
+        name: 'John',
+        password: 'secret123',
+      };
+
+      const filtered = filterSensitiveFields(data, ['name', 'password'], {
+        password: 'password',
+      });
+
+      expect(filtered).toEqual({
+        name: 'John',
+      });
+      expect(filtered).not.toHaveProperty('password');
+    });
+
+    it('should return empty object if all fields are sensitive', () => {
+      const data = {
+        password: 'secret123',
+        api_key: 'key123',
+      };
+
+      const filtered = filterSensitiveFields(data, ['password', 'api_key']);
+
+      expect(filtered).toEqual({});
+    });
+
+    it('should return all fields if none are sensitive', () => {
+      const data = {
+        name: 'John',
+        email: 'john@example.com',
+      };
+
+      const filtered = filterSensitiveFields(data, ['name', 'email']);
+
+      expect(filtered).toEqual(data);
+    });
+  });
+
+  describe('getSensitiveFieldNames', () => {
+    it('should return list of sensitive field names', () => {
+      const sensitive = getSensitiveFieldNames(
+        ['name', 'email', 'password', 'api_key'],
+        {
+          password: 'password',
+        }
+      );
+
+      expect(sensitive).toEqual(['password', 'api_key']);
+    });
+
+    it('should return empty array if no sensitive fields', () => {
+      const sensitive = getSensitiveFieldNames(['name', 'email']);
+
+      expect(sensitive).toEqual([]);
+    });
+  });
+});
+

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 };
+