@jmruthers/pace-core 0.5.136 → 0.5.139

package/src/utils/permissionUtils.test.ts

@@ -0,0 +1,393 @@
+/**
+ * @file Permission Utils Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/PermissionUtils
+ * @since 1.0.0
+ * 
+ * Comprehensive tests for permission utility functions covering all critical functionality.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  transformPermissionMapToBoolean,
+  hasPermission,
+  hasAnyPermission,
+  hasAllPermissions
+} from './permissionUtils';
+
+describe('Permission Utils', () => {
+  describe('transformPermissionMapToBoolean', () => {
+    it('transforms string values correctly', () => {
+      const permissions = {
+        'read:users': 'true',
+        'write:users': 'false',
+        'delete:users': '',
+        'manage:users': 'yes',
+        'view:users': 'no'
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+
+      expect(result).toEqual({
+        'read:users': true,
+        'write:users': false,
+        'delete:users': false,
+        'manage:users': true,
+        'view:users': true
+      });
+    });
+
+    it('transforms boolean values correctly', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true,
+        'manage:users': false
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+
+      expect(result).toEqual({
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true,
+        'manage:users': false
+      });
+    });
+
+    it('transforms mixed types correctly', () => {
+      const permissions = {
+        'read:users': 'true',
+        'write:users': false,
+        'delete:users': 1,
+        'manage:users': 0,
+        'view:users': null,
+        'edit:users': undefined
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+
+      expect(result).toEqual({
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true,
+        'manage:users': false,
+        'view:users': false,
+        'edit:users': false
+      });
+    });
+
+    it('handles empty object', () => {
+      const permissions = {};
+
+      const result = transformPermissionMapToBoolean(permissions);
+
+      expect(result).toEqual({});
+    });
+
+    it('handles null and undefined values', () => {
+      const permissions = {
+        'read:users': null,
+        'write:users': undefined,
+        'delete:users': false,
+        'manage:users': true
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+
+      expect(result).toEqual({
+        'read:users': false,
+        'write:users': false,
+        'delete:users': false,
+        'manage:users': true
+      });
+    });
+
+    it('handles numeric values', () => {
+      const permissions = {
+        'read:users': 1,
+        'write:users': 0,
+        'delete:users': -1,
+        'manage:users': 42
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+
+      expect(result).toEqual({
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true,
+        'manage:users': true
+      });
+    });
+
+    it('handles case-insensitive string values', () => {
+      const permissions = {
+        'read:users': 'TRUE',
+        'write:users': 'FALSE',
+        'delete:users': 'True',
+        'manage:users': 'False'
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+
+      expect(result).toEqual({
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true,
+        'manage:users': false
+      });
+    });
+  });
+
+  describe('hasPermission', () => {
+    it('returns true for granted permission', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true
+      };
+
+      expect(hasPermission(permissions, 'read:users')).toBe(true);
+      expect(hasPermission(permissions, 'delete:users')).toBe(true);
+    });
+
+    it('returns false for denied permission', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true
+      };
+
+      expect(hasPermission(permissions, 'write:users')).toBe(false);
+    });
+
+    it('returns false for non-existent permission', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      expect(hasPermission(permissions, 'manage:users')).toBe(false);
+    });
+
+    it('handles empty permissions object', () => {
+      const permissions = {};
+
+      expect(hasPermission(permissions, 'read:users')).toBe(false);
+    });
+
+    it('handles null/undefined permission', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      expect(hasPermission(permissions, null as any)).toBe(false);
+      expect(hasPermission(permissions, undefined as any)).toBe(false);
+    });
+  });
+
+  describe('hasAnyPermission', () => {
+    it('returns true when at least one permission is granted', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false,
+        'delete:users': false
+      };
+
+      expect(hasAnyPermission(permissions, ['read:users', 'write:users'])).toBe(true);
+      expect(hasAnyPermission(permissions, ['write:users', 'delete:users', 'read:users'])).toBe(true);
+    });
+
+    it('returns false when no permissions are granted', () => {
+      const permissions = {
+        'read:users': false,
+        'write:users': false,
+        'delete:users': false
+      };
+
+      expect(hasAnyPermission(permissions, ['read:users', 'write:users'])).toBe(false);
+    });
+
+    it('returns false for empty permission list', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      expect(hasAnyPermission(permissions, [])).toBe(false);
+    });
+
+    it('returns false when permission list contains non-existent permissions', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      expect(hasAnyPermission(permissions, ['manage:users', 'admin:users'])).toBe(false);
+    });
+
+    it('handles mixed permission states', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true,
+        'manage:users': false
+      };
+
+      expect(hasAnyPermission(permissions, ['read:users', 'write:users'])).toBe(true);
+      expect(hasAnyPermission(permissions, ['write:users', 'manage:users'])).toBe(false);
+      expect(hasAnyPermission(permissions, ['delete:users', 'manage:users'])).toBe(true);
+    });
+
+    it('handles null/undefined permission list', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      expect(hasAnyPermission(permissions, null as any)).toBe(false);
+      expect(hasAnyPermission(permissions, undefined as any)).toBe(false);
+    });
+  });
+
+  describe('hasAllPermissions', () => {
+    it('returns true when all permissions are granted', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': true,
+        'delete:users': true
+      };
+
+      expect(hasAllPermissions(permissions, ['read:users', 'write:users', 'delete:users'])).toBe(true);
+    });
+
+    it('returns false when at least one permission is denied', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false,
+        'delete:users': true
+      };
+
+      expect(hasAllPermissions(permissions, ['read:users', 'write:users'])).toBe(false);
+      expect(hasAllPermissions(permissions, ['read:users', 'write:users', 'delete:users'])).toBe(false);
+    });
+
+    it('returns true for empty permission list', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      expect(hasAllPermissions(permissions, [])).toBe(true);
+    });
+
+    it('returns false when permission list contains non-existent permissions', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': true
+      };
+
+      expect(hasAllPermissions(permissions, ['read:users', 'manage:users'])).toBe(false);
+    });
+
+    it('handles mixed permission states', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': true,
+        'delete:users': false,
+        'manage:users': true
+      };
+
+      expect(hasAllPermissions(permissions, ['read:users', 'write:users'])).toBe(true);
+      expect(hasAllPermissions(permissions, ['read:users', 'write:users', 'delete:users'])).toBe(false);
+      expect(hasAllPermissions(permissions, ['read:users', 'manage:users'])).toBe(true);
+    });
+
+    it('handles null/undefined permission list', () => {
+      const permissions = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      expect(hasAllPermissions(permissions, null as any)).toBe(false);
+      expect(hasAllPermissions(permissions, undefined as any)).toBe(false);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles very large permission objects', () => {
+      const permissions: Record<string, boolean> = {};
+      for (let i = 0; i < 1000; i++) {
+        permissions[`permission:${i}`] = i % 2 === 0;
+      }
+
+      const result = transformPermissionMapToBoolean(permissions);
+      expect(Object.keys(result)).toHaveLength(1000);
+      expect(result['permission:0']).toBe(true);
+      expect(result['permission:1']).toBe(false);
+    });
+
+    it('handles special characters in permission names', () => {
+      const permissions = {
+        'read:users@domain.com': true,
+        'write:users#special': false,
+        'delete:users$with$symbols': true,
+        'manage:users.with.dots': false
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+      expect(result['read:users@domain.com']).toBe(true);
+      expect(result['write:users#special']).toBe(false);
+      expect(result['delete:users$with$symbols']).toBe(true);
+      expect(result['manage:users.with.dots']).toBe(false);
+    });
+
+    it('handles unicode characters in permission names', () => {
+      const permissions = {
+        'read:用户': true,
+        'write:ユーザー': false,
+        'delete:مستخدم': true
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+      expect(result['read:用户']).toBe(true);
+      expect(result['write:ユーザー']).toBe(false);
+      expect(result['delete:مستخدم']).toBe(true);
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('maintains type safety with TypeScript', () => {
+      const permissions: Record<string, boolean> = {
+        'read:users': true,
+        'write:users': false
+      };
+
+      // These should compile without errors
+      const hasRead = hasPermission(permissions, 'read:users');
+      const hasAny = hasAnyPermission(permissions, ['read:users', 'write:users']);
+      const hasAll = hasAllPermissions(permissions, ['read:users']);
+
+      expect(typeof hasRead).toBe('boolean');
+      expect(typeof hasAny).toBe('boolean');
+      expect(typeof hasAll).toBe('boolean');
+    });
+
+    it('handles mixed input types gracefully', () => {
+      const permissions = {
+        'read:users': 'true',
+        'write:users': 1,
+        'delete:users': false,
+        'manage:users': null
+      };
+
+      const result = transformPermissionMapToBoolean(permissions);
+      expect(typeof result['read:users']).toBe('boolean');
+      expect(typeof result['write:users']).toBe('boolean');
+      expect(typeof result['delete:users']).toBe('boolean');
+      expect(typeof result['manage:users']).toBe('boolean');
+    });
+  });
+});

package/src/utils/permissionUtils.ts

@@ -0,0 +1,34 @@
+
+/**
+ * Permission utilities for transforming and managing permissions
+ */
+
+export function transformPermissionMapToBoolean(permissions: Record<string, unknown>): Record<string, boolean> {
+  const result: Record<string, boolean> = {};
+  
+  Object.entries(permissions).forEach(([key, value]) => {
+    if (typeof value === 'string') {
+      // Handle string values - 'false' should be false, empty strings are false, other non-empty strings are true
+      result[key] = value !== '' && value.toLowerCase() !== 'false';
+    } else {
+      result[key] = Boolean(value);
+    }
+  });
+  
+  return result;
+}
+
+export function hasPermission(permissions: Record<string, boolean>, permission: string): boolean {
+  return Boolean(permissions[permission]);
+}
+
+export function hasAnyPermission(permissions: Record<string, boolean>, permissionList: string[] | null | undefined): boolean {
+  if (!permissionList || permissionList.length === 0) return false;
+  return permissionList.some(permission => hasPermission(permissions, permission));
+}
+
+export function hasAllPermissions(permissions: Record<string, boolean>, permissionList: string[] | null | undefined): boolean {
+  if (!permissionList) return false;
+  if (permissionList.length === 0) return true;
+  return permissionList.every(permission => hasPermission(permissions, permission));
+}

package/src/utils/sanitization.ts

@@ -0,0 +1,264 @@
+
+/**
+ * @file Input Sanitization Layer
+ * @package @jmruthers/pace-core
+ * @module Security
+ * @since 0.1.0
+ * 
+ * Comprehensive input sanitization utilities to prevent XSS, injection attacks,
+ * and other security vulnerabilities.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Sanitization options for different contexts
+ */
+export interface SanitizationOptions {
+  allowHtml?: boolean;
+  allowedTags?: string[];
+  maxLength?: number;
+  trim?: boolean;
+  removeScripts?: boolean;
+  removeEvents?: boolean;
+}
+
+/**
+ * Default sanitization options
+ */
+const DEFAULT_OPTIONS: SanitizationOptions = {
+  allowHtml: false,
+  allowedTags: [],
+  maxLength: 1000,
+  trim: true,
+  removeScripts: true,
+  removeEvents: true
+};
+
+/**
+ * Sanitizes user input by removing potentially dangerous characters and patterns
+ */
+export function sanitizeUserInput(input: string, options: SanitizationOptions = {}): string {
+  if (typeof input !== 'string') {
+    return '';
+  }
+
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let sanitized = input;
+
+  // Trim whitespace if requested
+  if (opts.trim) {
+    sanitized = sanitized.trim();
+  }
+
+  // Enforce maximum length
+  if (opts.maxLength && sanitized.length > opts.maxLength) {
+    sanitized = sanitized.substring(0, opts.maxLength);
+  }
+
+  // Remove or escape HTML if not allowed
+  if (!opts.allowHtml) {
+    sanitized = sanitized
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#x27;')
+      .replace(/\//g, '&#x2F;');
+  } else if (opts.allowedTags && opts.allowedTags.length > 0) {
+    // If HTML is allowed, only permit specific tags
+    const allowedTagsRegex = new RegExp(`<(?!\/?(?:${opts.allowedTags.join('|')})\s*\/?>)[^>]+>`, 'gi');
+    sanitized = sanitized.replace(allowedTagsRegex, '');
+  }
+
+  // Remove script tags and javascript: protocols
+  if (opts.removeScripts) {
+    sanitized = sanitized
+      .replace(/<script[^>]*>.*?<\/script>/gi, '')
+      .replace(/javascript:/gi, '')
+      .replace(/vbscript:/gi, '')
+      .replace(/data:/gi, '');
+  }
+
+  // Remove event handlers
+  if (opts.removeEvents) {
+    sanitized = sanitized.replace(/on\w+\s*=/gi, '');
+  }
+
+  return sanitized;
+}
+
+/**
+ * Sanitizes email addresses
+ */
+export function sanitizeEmail(email: string): string {
+  if (typeof email !== 'string') {
+    return '';
+  }
+
+  return email
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w@.-]/g, ''); // Only allow word characters, @, ., and -
+}
+
+/**
+ * Sanitizes phone numbers
+ */
+export function sanitizePhoneNumber(phone: string): string {
+  if (typeof phone !== 'string') {
+    return '';
+  }
+
+  return phone.replace(/[^\d+\-\s()]/g, '').trim();
+}
+
+/**
+ * Sanitizes URLs
+ */
+export function sanitizeUrl(url: string): string {
+  if (typeof url !== 'string') {
+    return '';
+  }
+
+  const sanitized = url.trim();
+  
+  // Only allow http(s) and ftp protocols
+  if (!/^https?:\/\/|^ftp:\/\//i.test(sanitized)) {
+    return '';
+  }
+
+  // Remove javascript: and other dangerous protocols
+  if (/javascript:|data:|vbscript:/i.test(sanitized)) {
+    return '';
+  }
+
+  return sanitized;
+}
+
+/**
+ * Sanitizes file names
+ */
+export function sanitizeFileName(fileName: string): string {
+  if (typeof fileName !== 'string') {
+    return '';
+  }
+
+  return fileName
+    .trim()
+    .replace(/[<>:"/\\|?*]/g, '') // Remove invalid file name characters
+    .replace(/\.\./g, '') // Remove directory traversal attempts
+    .substring(0, 255); // Limit length
+}
+
+/**
+ * Sanitizes SQL input to prevent injection
+ */
+export function sanitizeSqlInput(input: string): string {
+  if (typeof input !== 'string') {
+    return '';
+  }
+
+  return input
+    .replace(/['";\\]/g, '') // Remove SQL special characters
+    .replace(/--.*$/gm, '') // Remove SQL comments
+    .replace(/\/\*.*?\*\//g, '') // Remove SQL block comments
+    .trim();
+}
+
+/**
+ * Validates and sanitizes form data using Zod schemas
+ */
+export function sanitizeFormData<T>(
+  data: unknown,
+  schema: z.ZodSchema<T>,
+  sanitizationRules?: Record<string, SanitizationOptions>
+): { success: boolean; data?: T; error?: string } {
+  try {
+    // First, sanitize string fields if rules are provided
+    if (sanitizationRules && typeof data === 'object' && data !== null) {
+      const sanitizedData = { ...data } as Record<string, unknown>;
+      
+      Object.entries(sanitizationRules).forEach(([field, options]) => {
+        if (typeof sanitizedData[field] === 'string') {
+          sanitizedData[field] = sanitizeUserInput(sanitizedData[field] as string, options);
+        }
+      });
+      
+      data = sanitizedData;
+    }
+
+    // Then validate with Zod schema
+    const result = schema.parse(data);
+    return { success: true, data: result };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return { 
+        success: false, 
+        error: error.errors.map(e => e.message).join(', ') 
+      };
+    }
+    return { 
+      success: false, 
+      error: 'Validation failed' 
+    };
+  }
+}
+
+/**
+ * Content Security Policy (CSP) utilities
+ */
+export const CSP_DIRECTIVES = {
+  default: "default-src 'self'",
+  script: "script-src 'self' 'unsafe-inline'",
+  style: "style-src 'self' 'unsafe-inline'",
+  img: "img-src 'self' data: https:",
+  font: "font-src 'self'",
+  connect: "connect-src 'self'",
+  frame: "frame-src 'none'"
+};
+
+export function generateCSPHeader(customDirectives?: Partial<typeof CSP_DIRECTIVES>): string {
+  const directives = { ...CSP_DIRECTIVES, ...customDirectives };
+  return Object.values(directives).join('; ');
+}
+
+/**
+ * Rate limiting utilities
+ */
+export class RateLimiter {
+  private attempts: Map<string, { count: number; resetTime: number }> = new Map();
+
+  constructor(
+    private maxAttempts: number = 5,
+    private windowMs: number = 15 * 60 * 1000 // 15 minutes
+  ) {}
+
+  isAllowed(identifier: string): boolean {
+    const now = Date.now();
+    const record = this.attempts.get(identifier);
+
+    if (!record || now > record.resetTime) {
+      this.attempts.set(identifier, { count: 1, resetTime: now + this.windowMs });
+      return true;
+    }
+
+    if (record.count >= this.maxAttempts) {
+      return false;
+    }
+
+    record.count++;
+    return true;
+  }
+
+  getRemainingAttempts(identifier: string): number {
+    const record = this.attempts.get(identifier);
+    if (!record || Date.now() > record.resetTime) {
+      return this.maxAttempts;
+    }
+    return Math.max(0, this.maxAttempts - record.count);
+  }
+
+  reset(identifier: string): void {
+    this.attempts.delete(identifier);
+  }
+}