feat: Implement requested changes

SECURITY_ANALYSIS.md

@@ -0,0 +1,310 @@
+# Security Analysis and Improvement Recommendations
+
+## 1. Security Vulnerabilities Analysis
+
+### 1.1 Input Validation
+
+#### File Path Validation in MomentLocale.php
+**Issue**: The locale loading mechanism uses dynamic file inclusion without strict validation.
+
+```php
+// Line 68 in MomentLocale.php
+self::$localeContent = require $pathFile;
+```
+
+**Risk**: While the code constructs the path internally, it still accepts user input for locale names which could potentially be exploited.
+
+**Recommendation**:
+- Add whitelist validation for locale names
+- Use realpath() to ensure the file is within the expected directory
+- Validate that the loaded file returns an array
+
+#### Regex Pattern Security
+**Status**: SAFE - All regex patterns are properly escaped and use delimiters correctly.
+- No use of dangerous `/e` modifier in preg_replace
+- All patterns use proper unicode flag `/u` where needed
+- User input is not directly used in regex patterns
+
+### 1.2 File Operations
+
+#### Dynamic File Inclusion
+**Issue**: The `require` statement in MomentLocale.php (line 68) dynamically includes locale files.
+
+**Risk**: Medium - While the path is constructed internally, improper locale names could lead to path traversal.
+
+**Recommendation**:
+```php
+private static function findLocaleFile()
+{
+    $locale = preg_replace('/[^a-zA-Z0-9_-]/', '', self::$locale);
+    $basePathFile = __DIR__ . '/Locales/' . $locale;
+    $pathFile = $basePathFile . '.php';
+
+    if (file_exists($pathFile)) {
+        $realPath = realpath($pathFile);
+        $expectedDir = realpath(__DIR__ . '/Locales');
+
+        // Ensure the file is within the expected directory
+        if (strpos($realPath, $expectedDir) !== 0) {
+            return null;
+        }
+
+        return $realPath;
+    }
+
+    // ... rest of the method
+}
+```
+
+### 1.3 Timezone Handling
+
+**Status**: SAFE - The code properly uses PHP's built-in DateTimeZone class which handles validation internally.
+
+### 1.4 Exception Handling
+
+**Issue**: MomentException is too generic and doesn't provide specific error types.
+
+**Recommendation**: Create specific exception types:
+```php
+class MomentLocaleException extends MomentException {}
+class MomentFormatException extends MomentException {}
+class MomentTimezoneException extends MomentException {}
+```
+
+## 2. Locale Loading Mechanism Review
+
+### Current Implementation Issues:
+1. No validation of locale file contents
+2. No caching mechanism for loaded locales
+3. Potential for repeated file system access
+
+### Recommendations:
+```php
+private static $localeCache = [];
+
+public static function loadLocaleContent()
+{
+    $locale = self::$locale;
+
+    // Check cache first
+    if (isset(self::$localeCache[$locale])) {
+        self::$localeContent = self::$localeCache[$locale];
+        return;
+    }
+
+    $pathFile = self::findLocaleFile();
+
+    if (!$pathFile) {
+        throw new MomentLocaleException('Locale does not exist: ' . $locale);
+    }
+
+    // Load and validate
+    $content = require $pathFile;
+
+    if (!is_array($content)) {
+        throw new MomentLocaleException('Invalid locale file format');
+    }
+
+    // Validate required keys
+    $requiredKeys = ['months', 'monthsShort', 'weekdays', 'weekdaysShort'];
+    foreach ($requiredKeys as $key) {
+        if (!isset($content[$key])) {
+            throw new MomentLocaleException("Missing required key '$key' in locale file");
+        }
+    }
+
+    self::$localeCache[$locale] = $content;
+    self::$localeContent = $content;
+}
+```
+
+## 3. Value Objects Improvements
+
+### MomentFromVo.php
+1. Add type declarations for all properties
+2. Add validation in setters
+3. Make properties private with proper getters/setters
+
+```php
+private function setDirection(string $direction): self
+{
+    if (!in_array($direction, ['-', '+', 'future', 'past'], true)) {
+        throw new \InvalidArgumentException('Invalid direction value');
+    }
+
+    $this->direction = $direction;
+    return $this;
+}
+```
+
+### MomentPeriodVo.php
+1. Add validation to ensure startDate < endDate
+2. Add interval validation
+3. Consider making the class immutable
+
+```php
+public function setInterval(int $interval): self
+{
+    if ($interval <= 0) {
+        throw new \InvalidArgumentException('Interval must be positive');
+    }
+
+    $this->interval = $interval;
+    return $this;
+}
+```
+
+## 4. CustomFormats Implementation
+
+**Current Status**: The MomentJs.php implementation is secure but could be improved.
+
+### Recommendations:
+1. Make the tokens array immutable
+2. Add validation when setting custom tokens
+3. Consider using constants for token definitions
+
+```php
+public function setTokens(array $options): self
+{
+    foreach ($options as $key => $value) {
+        if (!is_string($key) || !is_string($value)) {
+            throw new \InvalidArgumentException('Token keys and values must be strings');
+        }
+    }
+
+    $this->tokens = array_merge($this->tokens, $options);
+    return $this;
+}
+```
+
+## 5. Deprecated PHP Functions
+
+**Status**: GOOD - No deprecated PHP functions found in the codebase.
+
+## 6. General Security Recommendations
+
+### 6.1 Add Input Sanitization Helper
+```php
+class MomentSanitizer
+{
+    public static function sanitizeLocale(string $locale): string
+    {
+        // Only allow alphanumeric, underscore, and hyphen
+        return preg_replace('/[^a-zA-Z0-9_-]/', '', $locale);
+    }
+
+    public static function sanitizeTimezone(string $timezone): string
+    {
+        // Validate against known timezones
+        $validTimezones = timezone_identifiers_list();
+        if (!in_array($timezone, $validTimezones, true)) {
+            throw new MomentTimezoneException('Invalid timezone: ' . $timezone);
+        }
+        return $timezone;
+    }
+}
+```
+
+### 6.2 Add Rate Limiting for Locale Loading
+To prevent potential DoS attacks through repeated locale loading:
+```php
+private static $localeLoadCount = [];
+private static $localeLoadLimit = 100;
+
+private static function checkLocaleLoadLimit(string $locale): void
+{
+    $key = $locale . '_' . date('YmdH');
+
+    if (!isset(self::$localeLoadCount[$key])) {
+        self::$localeLoadCount[$key] = 0;
+    }
+
+    if (++self::$localeLoadCount[$key] > self::$localeLoadLimit) {
+        throw new MomentException('Locale load limit exceeded');
+    }
+}
+```
+
+### 6.3 Add Logging for Security Events
+```php
+interface MomentLoggerInterface
+{
+    public function logSecurityEvent(string $event, array $context = []): void;
+}
+
+class MomentSecurityLogger
+{
+    private static ?MomentLoggerInterface $logger = null;
+
+    public static function setLogger(MomentLoggerInterface $logger): void
+    {
+        self::$logger = $logger;
+    }
+
+    public static function log(string $event, array $context = []): void
+    {
+        if (self::$logger) {
+            self::$logger->logSecurityEvent($event, $context);
+        }
+    }
+}
+```
+
+## 7. Error Handling Improvements
+
+### 7.1 Add Error Context
+```php
+class MomentException extends \Exception
+{
+    private array $context = [];
+
+    public function __construct(string $message = "", int $code = 0, ?\Throwable $previous = null, array $context = [])
+    {
+        parent::__construct($message, $code, $previous);
+        $this->context = $context;
+    }
+
+    public function getContext(): array
+    {
+        return $this->context;
+    }
+}
+```
+
+### 7.2 Add Graceful Degradation
+For non-critical features like locale loading, consider fallback options:
+```php
+public static function setLocale($locale, $findSimilar = false, $fallbackToDefault = true)
+{
+    try {
+        self::$locale = $locale;
+        self::$findSimilar = $findSimilar;
+        self::loadLocaleContent();
+    } catch (MomentException $e) {
+        if ($fallbackToDefault && $locale !== 'en_US') {
+            self::setLocale('en_US', false, false);
+        } else {
+            throw $e;
+        }
+    }
+}
+```
+
+## 8. PHP 8.3 Compatibility
+
+The codebase appears to be compatible with PHP 8.3. However, consider:
+1. Using constructor property promotion where applicable
+2. Adding proper type declarations throughout
+3. Using the nullsafe operator where appropriate
+4. Consider using enums for constants like date formats
+
+## Summary
+
+Overall, the codebase is relatively secure but could benefit from:
+1. **Critical**: Input validation for locale names before file operations
+2. **Important**: Implementing a caching mechanism for loaded locales
+3. **Important**: Adding specific exception types for better error handling
+4. **Nice to have**: Making value objects more robust with validation
+5. **Nice to have**: Adding security logging capabilities
+
+The most critical security concern is the dynamic file inclusion in locale loading, which should be addressed with proper validation and sandboxing.