documentation-hub 5.7.2

package/src/utils/pathSecurity.ts

@@ -0,0 +1,232 @@
+import { logger } from './logger';
+
+/**
+ * Path Security Utilities
+ * Provides comprehensive path validation to prevent directory traversal attacks
+ */
+
+const log = logger.namespace('PathSecurity');
+
+/**
+ * Validates that a file path is safe and doesn't contain traversal attempts
+ * @param filePath The path to validate
+ * @param allowedExtensions Optional array of allowed file extensions (e.g., ['.docx', '.doc'])
+ * @returns true if path is safe, false otherwise
+ */
+export function isPathSafe(filePath: string, allowedExtensions?: string[]): boolean {
+  if (!filePath || typeof filePath !== 'string') {
+    log.warn('Invalid path: empty or not a string');
+    return false;
+  }
+
+  // Check for null bytes (poison null byte attack)
+  if (filePath.includes('\0')) {
+    log.error('Security: Path contains null byte', filePath);
+    return false;
+  }
+
+  // Check for directory traversal patterns
+  // NOTE: We need to be careful here - don't reject paths with ".." in folder names
+  // Only reject actual path traversal attempts (/../ or \..\)
+  // IMPORTANT: Match only when ".." is surrounded by path separators to avoid false positives
+  // For example, "DiaTech" should NOT trigger (contains "..") but "C:/Users/../Admin" should
+  const traversalPatterns = [
+    '/../', // Unix-style parent directory traversal
+    '\\..\\', // Windows-style parent directory traversal
+    '%2e%2e%2f', // URL-encoded traversal
+    '%2e%2e%5c',
+    '%252e%252e',
+    '%c0%ae%c0%ae',
+    '0x2e0x2e',
+  ];
+
+  const lowerPath = filePath.toLowerCase();
+
+  // Check for patterns that are clearly traversal attempts
+  for (const pattern of traversalPatterns) {
+    if (lowerPath.includes(pattern)) {
+      log.error('Security: Path contains traversal pattern', { path: filePath, pattern });
+      return false;
+    }
+  }
+
+  // Check for leading traversal attempts (must be at start or after separator)
+  if (lowerPath.startsWith('../') || lowerPath.startsWith('..\\')) {
+    log.error('Security: Path starts with parent directory traversal', filePath);
+    return false;
+  }
+
+  // Check for trailing traversal attempts (must be at end or before separator)
+  if (lowerPath.endsWith('/..') || lowerPath.endsWith('\\..')) {
+    log.error('Security: Path ends with parent directory traversal', filePath);
+    return false;
+  }
+
+  // Check for absolute path indicators on different platforms
+  const isAbsolute =
+    filePath.startsWith('/') || // Unix absolute
+    filePath.startsWith('\\') || // Windows UNC
+    /^[a-zA-Z]:[\\/]/.test(filePath); // Windows drive letter
+
+  if (!isAbsolute) {
+    log.warn('Security: Path is not absolute', filePath);
+    return false;
+  }
+
+  // Validate file extension if specified
+  if (allowedExtensions && allowedExtensions.length > 0) {
+    const hasValidExtension = allowedExtensions.some((ext) =>
+      filePath.toLowerCase().endsWith(ext.toLowerCase())
+    );
+
+    if (!hasValidExtension) {
+      log.error('Security: File extension not allowed', {
+        path: filePath,
+        allowedExtensions,
+      });
+      return false;
+    }
+  }
+
+  // Check for suspicious double extensions that might bypass filters
+  const suspiciousDoubleExtensions = [
+    '.docx.exe',
+    '.docx.scr',
+    '.docx.bat',
+    '.docx.cmd',
+    '.docx.com',
+    '.docx.pif',
+    '.docx.vbs',
+    '.docx.js',
+  ];
+
+  for (const ext of suspiciousDoubleExtensions) {
+    if (lowerPath.endsWith(ext)) {
+      log.error('Security: Suspicious double extension detected', {
+        path: filePath,
+        extension: ext,
+      });
+      return false;
+    }
+  }
+
+  // Check path length (Windows has 260 char limit by default)
+  if (filePath.length > 260) {
+    log.warn('Path exceeds maximum length (260 characters)', filePath.length);
+    // This is a warning not error as some systems support longer paths
+  }
+
+  // Check for special Windows device names
+  const windowsDeviceNames = [
+    'CON',
+    'PRN',
+    'AUX',
+    'NUL',
+    'COM1',
+    'COM2',
+    'COM3',
+    'COM4',
+    'COM5',
+    'COM6',
+    'COM7',
+    'COM8',
+    'COM9',
+    'LPT1',
+    'LPT2',
+    'LPT3',
+    'LPT4',
+    'LPT5',
+    'LPT6',
+    'LPT7',
+    'LPT8',
+    'LPT9',
+  ];
+
+  const fileName = filePath.split(/[\\/]/).pop()?.split('.')[0]?.toUpperCase();
+  if (fileName && windowsDeviceNames.includes(fileName)) {
+    log.error('Security: Windows device name detected', { path: filePath, deviceName: fileName });
+    return false;
+  }
+
+  // Check for URL protocols that shouldn't be in file paths
+  const dangerousProtocols = ['file://', 'http://', 'https://', 'ftp://', 'javascript:', 'data:'];
+
+  for (const protocol of dangerousProtocols) {
+    if (lowerPath.includes(protocol)) {
+      log.error('Security: URL protocol in file path', { path: filePath, protocol });
+      return false;
+    }
+  }
+
+  // All checks passed
+  log.debug('Path validation passed', filePath);
+  return true;
+}
+
+/**
+ * Sanitizes a file path by removing dangerous characters
+ * Note: This should be used with caution as it modifies the path
+ * @param filePath The path to sanitize
+ * @returns Sanitized path or null if path is unsafe
+ */
+export function sanitizePath(filePath: string): string | null {
+  if (!isPathSafe(filePath)) {
+    return null;
+  }
+
+  // Additional sanitization could go here if needed
+  // For now, we just return the validated path
+  return filePath;
+}
+
+/**
+ * Checks if a path is within an allowed directory
+ * @param filePath The path to check
+ * @param allowedPaths Array of allowed base directories
+ * @returns true if path is within an allowed directory
+ */
+export function isPathWithinAllowed(filePath: string, allowedPaths: string[]): boolean {
+  if (!filePath || allowedPaths.length === 0) {
+    return false;
+  }
+
+  // Normalize the file path for comparison
+  const normalizedFilePath = filePath.replace(/\\/g, '/').toLowerCase();
+
+  // Check if file path starts with any allowed path
+  return allowedPaths.some((allowed) => {
+    const normalizedAllowed = allowed.replace(/\\/g, '/').toLowerCase();
+    return normalizedFilePath.startsWith(normalizedAllowed);
+  });
+}
+
+/**
+ * Validates a batch of file paths
+ * @param filePaths Array of paths to validate
+ * @param allowedExtensions Optional array of allowed extensions
+ * @returns Object with valid and invalid paths
+ */
+export function validateBatchPaths(
+  filePaths: string[],
+  allowedExtensions?: string[]
+): {
+  valid: string[];
+  invalid: { path: string; reason: string }[];
+} {
+  const valid: string[] = [];
+  const invalid: { path: string; reason: string }[] = [];
+
+  for (const path of filePaths) {
+    if (isPathSafe(path, allowedExtensions)) {
+      valid.push(path);
+    } else {
+      invalid.push({
+        path,
+        reason: 'Failed security validation',
+      });
+    }
+  }
+
+  log.info(`Batch validation complete: ${valid.length} valid, ${invalid.length} invalid`);
+  return { valid, invalid };
+}

package/src/utils/pathValidator.ts

@@ -0,0 +1,236 @@
+/**
+ * Path validation utilities for secure file operations
+ *
+ * Prevents path traversal attacks and ensures file operations
+ * are restricted to safe directories.
+ *
+ * Security considerations:
+ * - Blocks path traversal attempts (../)
+ * - Validates paths are within allowed directories
+ * - Sanitizes file names
+ * - Prevents access to system files
+ *
+ * Note: Browser-compatible implementation without Node.js path module
+ */
+
+/**
+ * Browser-compatible path utilities
+ */
+const pathUtils = {
+  normalize(p: string): string {
+    // Replace backslashes with forward slashes for consistency
+    let normalized = p.replace(/\\/g, '/');
+
+    // Remove duplicate slashes
+    normalized = normalized.replace(/\/+/g, '/');
+
+    // Handle . and .. segments
+    const parts = normalized.split('/');
+    const result: string[] = [];
+
+    for (const part of parts) {
+      if (part === '..' && result.length > 0 && result[result.length - 1] !== '..') {
+        result.pop();
+      } else if (part !== '.' && part !== '') {
+        result.push(part);
+      }
+    }
+
+    return result.join('/');
+  },
+
+  resolve(...paths: string[]): string {
+    let resolved = '';
+    let isAbsolute = false;
+
+    for (let i = paths.length - 1; i >= 0 && !isAbsolute; i--) {
+      const p = paths[i];
+      if (!p) continue;
+
+      resolved = p + '/' + resolved;
+      isAbsolute = /^([a-zA-Z]:)?\//.test(p);
+    }
+
+    resolved = this.normalize(resolved);
+    return resolved || '.';
+  },
+
+  basename(p: string): string {
+    const normalized = p.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    return parts[parts.length - 1] || '';
+  },
+
+  dirname(p: string): string {
+    const normalized = p.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    parts.pop();
+    return parts.join('/') || '.';
+  },
+
+  join(...paths: string[]): string {
+    return this.normalize(paths.join('/'));
+  },
+};
+
+/**
+ * Checks if a path contains path traversal attempts
+ */
+export function hasPathTraversal(filePath: string): boolean {
+  // Normalize path to resolve any .. or . segments
+  const normalized = pathUtils.normalize(filePath);
+
+  // Check for parent directory references
+  if (normalized.includes('..')) {
+    return true;
+  }
+
+  // Check for absolute path attempts on Windows
+  const isWindows = navigator.userAgent.includes('Windows');
+  if (isWindows) {
+    // Check for drive letter changes (C:, D:, etc.)
+    const driveLetter = filePath.match(/^[a-zA-Z]:/);
+    const normalizedDrive = normalized.match(/^[a-zA-Z]:/);
+
+    if (driveLetter && normalizedDrive) {
+      if (driveLetter[0].toLowerCase() !== normalizedDrive[0].toLowerCase()) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a path is within an allowed directory
+ */
+export function isWithinDirectory(filePath: string, allowedDir: string): boolean {
+  const resolvedPath = pathUtils.resolve(filePath);
+  const resolvedAllowedDir = pathUtils.resolve(allowedDir);
+
+  // On Windows, compare case-insensitively
+  const isWindows = navigator.userAgent.includes('Windows');
+  if (isWindows) {
+    return resolvedPath.toLowerCase().startsWith(resolvedAllowedDir.toLowerCase());
+  }
+
+  return resolvedPath.startsWith(resolvedAllowedDir);
+}
+
+/**
+ * Sanitizes a file name by removing dangerous characters
+ */
+export function sanitizeFileName(fileName: string): string {
+  // Remove or replace dangerous characters
+  // Allow: letters, numbers, spaces, dots, dashes, underscores
+  return fileName.replace(/[^a-zA-Z0-9\s.\-_]/g, '_');
+}
+
+/**
+ * Validates if a file path is safe to use
+ *
+ * @param filePath - The file path to validate
+ * @param allowedDirectories - Optional array of allowed base directories
+ * @returns Object with validation result and error message if invalid
+ */
+export function validateFilePath(
+  filePath: string,
+  allowedDirectories?: string[]
+): { isValid: boolean; error?: string } {
+  // Check for empty or null paths
+  if (!filePath || filePath.trim() === '') {
+    return {
+      isValid: false,
+      error: 'File path is empty',
+    };
+  }
+
+  // Check for path traversal attempts
+  if (hasPathTraversal(filePath)) {
+    return {
+      isValid: false,
+      error: 'Path traversal attempt detected',
+    };
+  }
+
+  // Check for dangerous characters in filename
+  const fileName = pathUtils.basename(filePath);
+  const dangerousChars = /[<>:"|?*]/;
+
+  if (dangerousChars.test(fileName)) {
+    return {
+      isValid: false,
+      error: 'File name contains illegal characters',
+    };
+  }
+
+  // Validate against allowed directories if provided
+  if (allowedDirectories && allowedDirectories.length > 0) {
+    const isInAllowedDir = allowedDirectories.some((allowedDir) =>
+      isWithinDirectory(filePath, allowedDir)
+    );
+
+    if (!isInAllowedDir) {
+      return {
+        isValid: false,
+        error: 'File path is outside allowed directories',
+      };
+    }
+  }
+
+  // Check for system file access attempts
+  const systemPaths = ['/etc', '/sys', '/proc', 'C:\\Windows\\System32', 'C:\\Program Files'];
+
+  const resolvedPath = pathUtils.resolve(filePath);
+  const isWindows = navigator.userAgent.includes('Windows');
+  const isSystemPath = systemPaths.some((sysPath) => {
+    if (isWindows) {
+      return resolvedPath.toLowerCase().startsWith(sysPath.toLowerCase());
+    }
+    return resolvedPath.startsWith(sysPath);
+  });
+
+  if (isSystemPath) {
+    return {
+      isValid: false,
+      error: 'Access to system files is not allowed',
+    };
+  }
+
+  // Path is valid
+  return { isValid: true };
+}
+
+/**
+ * Gets common allowed directories for document operations
+ * Note: Browser environment doesn't have access to environment variables
+ * This function returns empty array in browser, should use IPC in Electron
+ */
+export function getDefaultAllowedDirectories(): string[] {
+  // In browser context, we can't access environment variables or filesystem
+  // This function should be called from Electron main process via IPC
+  return [];
+}
+
+/**
+ * Validates and sanitizes a file path
+ * Returns the sanitized path or throws an error
+ */
+export function validateAndSanitizePath(filePath: string, allowedDirectories?: string[]): string {
+  const validation = validateFilePath(filePath, allowedDirectories);
+
+  if (!validation.isValid) {
+    throw new Error(`Invalid file path: ${validation.error}`);
+  }
+
+  // Resolve to absolute path to prevent any relative path tricks
+  const absolutePath = pathUtils.resolve(filePath);
+
+  // Sanitize the filename
+  const dir = pathUtils.dirname(absolutePath);
+  const fileName = pathUtils.basename(absolutePath);
+  const sanitizedFileName = sanitizeFileName(fileName);
+
+  return pathUtils.join(dir, sanitizedFileName);
+}

package/src/utils/processingTimeEstimator.ts

@@ -0,0 +1,153 @@
+/**
+ * Processing Time Estimator
+ *
+ * Estimates remaining time for document processing based on:
+ * - Number of documents remaining
+ * - Historical processing times
+ * - Power Automate API response time (baseline: 12 seconds)
+ */
+
+interface ProcessingTiming {
+  documentId: string;
+  startTime: number;
+  endTime?: number;
+  apiCallCount: number;
+}
+
+const POWER_AUTOMATE_BASELINE_MS = 12000; // 12 seconds baseline for API response
+const MIN_PROCESSING_TIME_MS = 3000; // Minimum time per document (local processing)
+const MAX_HISTORY_SIZE = 20; // Keep last 20 timings for averaging
+
+class ProcessingTimeEstimator {
+  private timings: ProcessingTiming[] = [];
+  private currentTiming: ProcessingTiming | null = null;
+  private averageApiTime: number = POWER_AUTOMATE_BASELINE_MS;
+
+  /**
+   * Start timing a document
+   */
+  startDocument(documentId: string, apiCallCount: number = 1): void {
+    this.currentTiming = {
+      documentId,
+      startTime: Date.now(),
+      apiCallCount,
+    };
+  }
+
+  /**
+   * End timing for current document
+   */
+  endDocument(): void {
+    if (!this.currentTiming) return;
+
+    this.currentTiming.endTime = Date.now();
+    this.timings.push(this.currentTiming);
+
+    // Keep only recent timings
+    if (this.timings.length > MAX_HISTORY_SIZE) {
+      this.timings = this.timings.slice(-MAX_HISTORY_SIZE);
+    }
+
+    // Update average API time based on actual performance
+    this.updateAverageApiTime();
+    this.currentTiming = null;
+  }
+
+  /**
+   * Record an API call timing
+   */
+  recordApiCallTime(durationMs: number): void {
+    // Exponential moving average with 0.3 weight for new values
+    // This allows the estimate to catch up or slow down based on actual performance
+    const alpha = 0.3;
+    this.averageApiTime = alpha * durationMs + (1 - alpha) * this.averageApiTime;
+  }
+
+  /**
+   * Update the average API time based on completed documents
+   */
+  private updateAverageApiTime(): void {
+    const completedTimings = this.timings.filter(t => t.endTime);
+    if (completedTimings.length === 0) return;
+
+    // Calculate average time per API call
+    const recentTimings = completedTimings.slice(-5); // Use last 5 for responsiveness
+    const totalTime = recentTimings.reduce((sum, t) => sum + (t.endTime! - t.startTime), 0);
+    const totalApiCalls = recentTimings.reduce((sum, t) => sum + t.apiCallCount, 0);
+
+    if (totalApiCalls > 0) {
+      const measuredAverage = totalTime / totalApiCalls;
+      // Blend with baseline to avoid wild swings
+      const alpha = 0.4;
+      this.averageApiTime = alpha * measuredAverage + (1 - alpha) * this.averageApiTime;
+    }
+  }
+
+  /**
+   * Estimate remaining time for pending documents
+   *
+   * @param documentsRemaining Number of documents left to process
+   * @param estimatedApiCallsPerDoc Average API calls per document (default 1)
+   * @returns Estimated time remaining in milliseconds
+   */
+  estimateRemainingTime(documentsRemaining: number, estimatedApiCallsPerDoc: number = 1): number {
+    if (documentsRemaining <= 0) return 0;
+
+    // Time for current document if in progress
+    let currentDocRemaining = 0;
+    if (this.currentTiming) {
+      const elapsed = Date.now() - this.currentTiming.startTime;
+      const estimatedTotal = this.currentTiming.apiCallCount * this.averageApiTime + MIN_PROCESSING_TIME_MS;
+      currentDocRemaining = Math.max(0, estimatedTotal - elapsed);
+    }
+
+    // Time for remaining documents (not including current)
+    const remainingDocsTime = (documentsRemaining - (this.currentTiming ? 1 : 0)) *
+      (estimatedApiCallsPerDoc * this.averageApiTime + MIN_PROCESSING_TIME_MS);
+
+    return currentDocRemaining + remainingDocsTime;
+  }
+
+  /**
+   * Get the current average API response time
+   */
+  getAverageApiTime(): number {
+    return this.averageApiTime;
+  }
+
+  /**
+   * Format milliseconds to human-readable string
+   */
+  static formatTime(ms: number): string {
+    if (ms <= 0) return '0s';
+
+    const seconds = Math.ceil(ms / 1000);
+    if (seconds < 60) return `${seconds}s`;
+
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+
+    if (minutes < 60) {
+      return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+    }
+
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return `${hours}h ${remainingMinutes}m`;
+  }
+
+  /**
+   * Reset all timings
+   */
+  reset(): void {
+    this.timings = [];
+    this.currentTiming = null;
+    this.averageApiTime = POWER_AUTOMATE_BASELINE_MS;
+  }
+}
+
+// Singleton instance
+export const processingTimeEstimator = new ProcessingTimeEstimator();
+
+// Export class for testing
+export { ProcessingTimeEstimator };

package/src/utils/safeJsonParse.ts

@@ -0,0 +1,62 @@
+import { logger } from './logger';
+
+/**
+ * Safely parse JSON with error handling
+ * Returns the parsed value or the default value if parsing fails
+ */
+export function safeJsonParse<T>(
+  jsonString: string | null | undefined,
+  defaultValue: T,
+  context?: string
+): T {
+  if (!jsonString) {
+    return defaultValue;
+  }
+
+  try {
+    return JSON.parse(jsonString) as T;
+  } catch (error) {
+    const log = logger.namespace('SafeJsonParse');
+    log.error(
+      `Failed to parse JSON${context ? ` in ${context}` : ''}:`,
+      error instanceof Error ? error.message : 'Unknown error'
+    );
+    log.debug('Invalid JSON string:', jsonString.substring(0, 100));
+    return defaultValue;
+  }
+}
+
+/**
+ * Safely stringify JSON with error handling
+ * Returns null if stringification fails
+ */
+export function safeJsonStringify(
+  value: unknown,
+  space?: string | number,
+  context?: string
+): string | null {
+  try {
+    return JSON.stringify(value, null, space);
+  } catch (error) {
+    const log = logger.namespace('SafeJsonStringify');
+    log.error(
+      `Failed to stringify JSON${context ? ` in ${context}` : ''}:`,
+      error instanceof Error ? error.message : 'Unknown error'
+    );
+    return null;
+  }
+}
+
+/**
+ * Type guard to check if a value is a valid JSON object
+ */
+export function isValidJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Type guard to check if a value is a valid JSON array
+ */
+export function isValidJsonArray(value: unknown): value is unknown[] {
+  return Array.isArray(value);
+}