@unrdf/hooks 5.0.1

package/src/hooks/security/error-sanitizer.mjs

@@ -0,0 +1,257 @@
+/**
+ * @file Error Message Sanitizer
+ * @module error-sanitizer
+ *
+ * @description
+ * Sanitizes error messages to prevent information disclosure vulnerabilities.
+ * Removes sensitive data like passwords, file paths, stack traces, and environment variables.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Schema for sanitization options
+ */
+const SanitizationOptionsSchema = z
+  .object({
+    removeStackTraces: z.boolean().default(true),
+    removeFilePaths: z.boolean().default(true),
+    removeCredentials: z.boolean().default(true),
+    removeEnvironmentVars: z.boolean().default(true),
+    genericErrorMessage: z.string().default('An error occurred'),
+  })
+  .strict();
+
+/**
+ * Patterns to detect and sanitize sensitive information
+ */
+const SENSITIVE_PATTERNS = {
+  // File paths (absolute paths)
+  filePaths: [
+    /\/[a-zA-Z0-9_\-./]+\.js(?::\d+:\d+)?/g, // Unix paths with line numbers
+    /\\[a-zA-Z0-9_\-.\\]+\.js(?::\d+:\d+)?/g, // Windows paths
+    /\/app\/[^\s]*/g, // Docker app paths
+    /\/usr\/[^\s]*/g, // System paths
+    /\/etc\/[^\s]*/g,
+    /\/var\/[^\s]*/g,
+    /\/home\/[^\s]*/g,
+    /C:\\[^\s]*/g, // Windows paths
+    /D:\\[^\s]*/g,
+  ],
+
+  // Database connection strings
+  credentials: [
+    /\b(?:postgres|mysql|mongodb):\/\/[^:\s]+:[^@\s]+@[^\s]+/gi, // DB URLs with passwords
+    /password\s*[:=]\s*["']?[^"'\s]+["']?/gi, // password= or password:
+    /api[_-]?key\s*[:=]\s*["']?[^"'\s]+["']?/gi, // API keys
+    /secret\s*[:=]\s*["']?[^"'\s]+["']?/gi, // secrets
+    /token\s*[:=]\s*["']?[^"'\s]+["']?/gi, // tokens
+    /authorization\s*:\s*["']?[^"'\s]+["']?/gi, // auth headers
+  ],
+
+  // Environment variables
+  environmentVars: [
+    /\bDATABASE_URL\s*=\s*[^\s]+/gi,
+    /API_KEY\s*=\s*[^\s]+/gi,
+    /SECRET\s*=\s*[^\s]+/gi,
+    /PASSWORD\s*=\s*[^\s]+/gi,
+    /TOKEN\s*=\s*[^\s]+/gi,
+    /\w+_KEY\s*=\s*[^\s]+/gi,
+    /\w+_SECRET\s*=\s*[^\s]+/gi,
+  ],
+
+  // Stack trace patterns
+  stackTraces: [
+    /\bat\s+[^\s]+\s+\([^)]+:\d+:\d+\)/g, // at Function (file:line:col)
+    /at\s+[^(]+\([^)]+\)/g, // at Function(...)
+    /^\s*at\s.+$/gm, // Full stack trace lines
+  ],
+};
+
+/**
+ * Error Sanitizer for preventing information disclosure
+ */
+export class ErrorSanitizer {
+  /**
+   * @param {Object} [options] - Sanitization options
+   */
+  constructor(options = {}) {
+    const validated = SanitizationOptionsSchema.parse(options);
+    this.options = validated;
+  }
+
+  /**
+   * Sanitize an error message
+   * @param {Error | string} error - Error to sanitize
+   * @returns {string} Sanitized error message
+   */
+  sanitize(error) {
+    let message = error instanceof Error ? error.message : String(error);
+
+    // Remove credentials
+    if (this.options.removeCredentials) {
+      message = this._removeCredentials(message);
+    }
+
+    // Remove file paths
+    if (this.options.removeFilePaths) {
+      message = this._removeFilePaths(message);
+    }
+
+    // Remove environment variables
+    if (this.options.removeEnvironmentVars) {
+      message = this._removeEnvironmentVars(message);
+    }
+
+    // If sanitization removed too much, return generic message
+    if (message.trim().length < 10) {
+      return this.options.genericErrorMessage;
+    }
+
+    return message;
+  }
+
+  /**
+   * Sanitize a complete error object
+   * @param {Error} error - Error object
+   * @returns {Object} Sanitized error object
+   */
+  sanitizeError(error) {
+    if (!error || typeof error !== 'object') {
+      return {
+        message: this.options.genericErrorMessage,
+        sanitized: true,
+      };
+    }
+
+    const sanitized = {
+      message: this.sanitize(error.message || 'Unknown error'),
+      sanitized: true,
+    };
+
+    // Only include stack if not removing stack traces
+    if (!this.options.removeStackTraces && error.stack) {
+      sanitized.stack = this._sanitizeStack(error.stack);
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Remove credential patterns from text
+   * @param {string} text - Text to sanitize
+   * @returns {string} Sanitized text
+   * @private
+   */
+  _removeCredentials(text) {
+    let sanitized = text;
+
+    for (const pattern of SENSITIVE_PATTERNS.credentials) {
+      sanitized = sanitized.replace(pattern, match => {
+        if (match.includes('://')) {
+          // Replace password in connection string
+          return match.replace(/:\/\/[^:]+:[^@]+@/, '://***:***@');
+        }
+        // Replace entire credential assignment
+        return match.split(/[:=]/)[0] + '=***';
+      });
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Remove file path patterns from text
+   * @param {string} text - Text to sanitize
+   * @returns {string} Sanitized text
+   * @private
+   */
+  _removeFilePaths(text) {
+    let sanitized = text;
+
+    for (const pattern of SENSITIVE_PATTERNS.filePaths) {
+      sanitized = sanitized.replace(pattern, '[file path removed]');
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Remove environment variable patterns from text
+   * @param {string} text - Text to sanitize
+   * @returns {string} Sanitized text
+   * @private
+   */
+  _removeEnvironmentVars(text) {
+    let sanitized = text;
+
+    for (const pattern of SENSITIVE_PATTERNS.environmentVars) {
+      sanitized = sanitized.replace(pattern, match => {
+        return match.split('=')[0] + '=***';
+      });
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Sanitize stack trace
+   * @param {string} stack - Stack trace
+   * @returns {string} Sanitized stack trace
+   * @private
+   */
+  _sanitizeStack(stack) {
+    let sanitized = stack;
+
+    // Remove file paths from stack trace
+    for (const pattern of SENSITIVE_PATTERNS.filePaths) {
+      sanitized = sanitized.replace(pattern, '[sanitized]');
+    }
+
+    // Remove full stack trace lines if configured
+    if (this.options.removeStackTraces) {
+      return 'Stack trace removed for security';
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Check if text contains sensitive information
+   * @param {string} text - Text to check
+   * @returns {boolean} True if sensitive info detected
+   */
+  containsSensitiveInfo(text) {
+    for (const patterns of Object.values(SENSITIVE_PATTERNS)) {
+      for (const pattern of patterns) {
+        if (pattern.test(text)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+}
+
+/**
+ * Create an error sanitizer instance
+ * @param {Object} [options] - Sanitization options
+ * @returns {ErrorSanitizer} Sanitizer instance
+ */
+export function createErrorSanitizer(options = {}) {
+  return new ErrorSanitizer(options);
+}
+
+/**
+ * Default error sanitizer instance (strict mode)
+ */
+export const defaultErrorSanitizer = new ErrorSanitizer();
+
+/**
+ * Sanitize an error message (convenience function)
+ * @param {Error | string} error - Error to sanitize
+ * @returns {string} Sanitized error message
+ */
+export function sanitizeError(error) {
+  return defaultErrorSanitizer.sanitize(error);
+}

package/src/hooks/security/path-validator.mjs

@@ -0,0 +1,194 @@
+/**
+ * @file Path Traversal Validator
+ * @module path-validator
+ *
+ * @description
+ * Validates file paths to prevent directory traversal and unauthorized file access attacks.
+ */
+
+import { z } from 'zod';
+import { resolve, normalize, _isAbsolute } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Schema for path validation options
+ */
+const PathValidationOptionsSchema = z
+  .object({
+    basePath: z.string().optional(),
+    allowAbsolutePaths: z.boolean().default(false),
+    allowedDirectories: z.array(z.string()).default([]),
+    blockedDirectories: z
+      .array(z.string())
+      .default([
+        '/etc',
+        '/usr',
+        '/bin',
+        '/sbin',
+        '/var',
+        '/root',
+        'C:\\Windows',
+        'C:\\System32',
+        'D:\\Windows',
+      ]),
+  })
+  .strict();
+
+/**
+ * Path Validator for preventing traversal attacks
+ */
+export class PathValidator {
+  /**
+   * @param {Object} [options] - Validation options
+   */
+  constructor(options = {}) {
+    const validated = PathValidationOptionsSchema.parse(options);
+    this.basePath = validated.basePath || process.cwd();
+    this.allowAbsolutePaths = validated.allowAbsolutePaths;
+    this.allowedDirectories = validated.allowedDirectories;
+    this.blockedDirectories = validated.blockedDirectories;
+  }
+
+  /**
+   * Validate a file URI for path traversal attacks
+   * @param {string} uri - File URI to validate
+   * @returns {Object} Validation result { valid, violations, sanitizedPath }
+   */
+  validateFileUri(uri) {
+    const violations = [];
+
+    if (!uri || typeof uri !== 'string') {
+      return {
+        valid: false,
+        violations: ['Invalid URI: must be a non-empty string'],
+        sanitizedPath: null,
+      };
+    }
+
+    try {
+      // Convert file:// URI to path
+      let filePath = uri;
+      if (uri.startsWith('file://')) {
+        filePath = fileURLToPath(uri);
+      } else if (uri.includes('://')) {
+        violations.push('Only file:// URIs are supported');
+        return { valid: false, violations, sanitizedPath: null };
+      }
+
+      // Decode URI encoding (including double encoding)
+      let decodedPath = filePath;
+      let previousPath = '';
+      // Decode up to 3 times to catch double/triple encoding
+      for (let i = 0; i < 3 && decodedPath !== previousPath; i++) {
+        previousPath = decodedPath;
+        decodedPath = decodeURIComponent(decodedPath);
+      }
+
+      // Check for null byte injection
+      if (decodedPath.includes('\x00') || decodedPath.includes('%00')) {
+        violations.push('Null byte injection detected');
+        return { valid: false, violations, sanitizedPath: null };
+      }
+
+      // Check for path traversal patterns
+      if (this._hasTraversalPattern(decodedPath)) {
+        violations.push('Path traversal pattern detected');
+        return { valid: false, violations, sanitizedPath: null };
+      }
+
+      // Normalize and resolve path
+      const normalizedPath = normalize(decodedPath);
+      const resolvedPath = resolve(this.basePath, normalizedPath);
+
+      // Check if resolved path is within base path
+      if (!this.allowAbsolutePaths && !resolvedPath.startsWith(resolve(this.basePath))) {
+        violations.push('Path escapes base directory');
+        return { valid: false, violations, sanitizedPath: null };
+      }
+
+      // Check against blocked directories
+      for (const blockedDir of this.blockedDirectories) {
+        if (resolvedPath.startsWith(blockedDir)) {
+          violations.push(`Access to blocked directory: ${blockedDir}`);
+          return { valid: false, violations, sanitizedPath: null };
+        }
+      }
+
+      // If allowed directories are specified, check inclusion
+      if (this.allowedDirectories.length > 0) {
+        const isAllowed = this.allowedDirectories.some(allowedDir =>
+          resolvedPath.startsWith(resolve(allowedDir))
+        );
+        if (!isAllowed) {
+          violations.push('Path not in allowed directories');
+          return { valid: false, violations, sanitizedPath: null };
+        }
+      }
+
+      return {
+        valid: true,
+        violations: [],
+        sanitizedPath: resolvedPath,
+      };
+    } catch (error) {
+      violations.push(`Path validation error: ${error.message}`);
+      return { valid: false, violations, sanitizedPath: null };
+    }
+  }
+
+  /**
+   * Check for path traversal patterns
+   * @param {string} path - Path to check
+   * @returns {boolean} True if traversal pattern detected
+   * @private
+   */
+  _hasTraversalPattern(path) {
+    const traversalPatterns = [
+      /\.\.\//g, // ../
+      /\.\.\\/g, // ..\
+      /\.\.%2f/gi, // ..%2f (URL encoded)
+      /\.\.%5c/gi, // ..%5c (URL encoded)
+      /\.\.%252f/gi, // ..%252f (double URL encoded)
+      /\.\.%255c/gi, // ..%255c (double URL encoded)
+      /\.\.%c0%af/gi, // Unicode bypass
+      /\.\.%c1%9c/gi, // Unicode bypass
+    ];
+
+    return traversalPatterns.some(pattern => pattern.test(path));
+  }
+
+  /**
+   * Sanitize a file path (best effort - returns null if unsafe)
+   * @param {string} path - Path to sanitize
+   * @returns {string | null} Sanitized path or null if unsafe
+   */
+  sanitizePath(path) {
+    const validation = this.validateFileUri(path);
+    return validation.valid ? validation.sanitizedPath : null;
+  }
+}
+
+/**
+ * Create a path validator instance
+ * @param {Object} [options] - Validation options
+ * @returns {PathValidator} Validator instance
+ */
+export function createPathValidator(options = {}) {
+  return new PathValidator(options);
+}
+
+/**
+ * Default path validator instance
+ */
+export const defaultPathValidator = new PathValidator();
+
+/**
+ * Validate a file URI (convenience function)
+ * @param {string} uri - URI to validate
+ * @param {string} [basePath] - Base path for validation
+ * @returns {Object} Validation result
+ */
+export function validatePath(uri, basePath) {
+  const validator = basePath ? new PathValidator({ basePath }) : defaultPathValidator;
+  return validator.validateFileUri(uri);
+}