FileStorage File Name validation (#71)

* Updated filename validator wiht custom messages.

Author: FrostyApeOne

src/DfE.CoreLibs.FileStorage/Interfaces/IFileStorageService.cs

@@ -18,13 +18,14 @@ public interface IFileStorageService
     /// </summary>
     /// <param name="path">Relative path of the file within the storage provider. Must not be null or empty.</param>
     /// <param name="content">Stream containing the data to upload. Must be readable and not null.</param>
+    /// <param name="originalFileName">Original Filename.</param>
     /// <param name="token">Optional cancellation token to cancel the operation.</param>
     /// <returns>A task that represents the asynchronous upload operation.</returns>
     /// <exception cref="ArgumentNullException">Thrown when <paramref name="path"/> or <paramref name="content"/> is null.</exception>
     /// <exception cref="ArgumentException">Thrown when <paramref name="path"/> is empty or <paramref name="content"/> is not readable.</exception>
     /// <exception cref="FileStorageException">Thrown when the upload operation fails.</exception>
     /// <exception cref="OperationCanceledException">Thrown when the operation is cancelled via the cancellation token.</exception>
-    Task UploadAsync(string path, Stream content, CancellationToken token = default);
+    Task UploadAsync(string path, Stream content, string? originalFileName = null, CancellationToken token = default);
 
     /// <summary>
     /// Retrieves a file from the specified <paramref name="path"/>.

src/DfE.CoreLibs.FileStorage/LocalFileStorageExample.md

@@ -14,7 +14,8 @@ This guide shows how to use the Local File Storage provider in the DfE.CoreLibs.
       "CreateDirectoryIfNotExists": true,
       "AllowOverwrite": true,
       "MaxFileSizeBytes": 104857600,
-      "AllowedExtensions": ["jpg", "png", "pdf", "docx", "xlsx"]
+      "AllowedExtensions": ["jpg", "png", "pdf", "docx", "xlsx"],
+      "AllowedFileNamePattern": "^[a-zA-Z0-9_-]+$"
     }
   }
 }
@@ -203,12 +204,39 @@ public class DocumentService
 - Files without extensions are rejected when `AllowedExtensions` is configured
 - The validation checks the last extension in filenames with multiple dots (e.g., "file.backup.jpg" is validated as "jpg")
 
+### Filename Pattern Examples
+
+```json
+{
+  "FileStorage": {
+    "Provider": "Local",
+    "Local": {
+      "BaseDirectory": "C:\\FileStorage",
+      "AllowedFileNamePattern": "^[a-zA-Z0-9_-]+$"
+    }
+  }
+}
+```
+
+**Filename Pattern Options**:
+- `"^[a-zA-Z0-9_-]+$"` - Only letters, numbers, underscore, and hyphens (default recommended pattern)
+- `"^[A-Z]{2}[0-9]{3}$"` - 2 uppercase letters followed by 3 digits (e.g., "AB123")
+- `"^[a-z0-9]+$"` - Only lowercase letters and numbers
+- `null` or empty - No filename pattern validation (allows all characters)
+
+**Filename Pattern Validation Notes**:
+- If `AllowedFileNamePattern` is null or empty, no filename pattern validation is applied
+- Pattern validation applies only to the filename part (without extension), not the directory path
+- Uses .NET regular expressions with compiled optimization for performance
+- Invalid regex patterns will throw `FileStorageConfigurationException` during service initialization
+
 ## Security Features
 
 - **Directory Traversal Protection**: The service prevents access to files outside the base directory
 - **Path Normalization**: All paths are normalized to prevent security issues
 - **File Size Limits**: Configurable maximum file size to prevent abuse
 - **File Extension Validation**: Restrict uploads to specific file types for security
+- **Filename Pattern Validation**: Restrict filenames to match specific patterns, preventing malicious or problematic filenames
 
 ## Error Handling
 
@@ -226,6 +254,14 @@ When file extension validation is enabled, the service will throw `FileStorageEx
 - **No extension**: "File extension is required. Allowed extensions: jpg, png, pdf"
 - **Invalid extension**: "File extension 'exe' is not allowed. Allowed extensions: jpg, png, pdf"
 
+### Filename Pattern Validation Errors
+
+When filename pattern validation is enabled, the service will throw `FileStorageException` with specific messages:
+
+- **Invalid filename**: "Filename 'file with spaces' does not match the allowed pattern. Pattern: ^[a-zA-Z0-9_-]+$"
+- **Missing filename**: "Filename is required when filename pattern validation is enabled. Pattern: ^[a-zA-Z0-9_-]+$"
+- **Invalid pattern at startup**: "Invalid filename pattern: [unclosed" (throws `FileStorageConfigurationException`)
+
 ## Best Practices
 
 1. **Use relative paths**: Always use relative paths within your storage structure

src/DfE.CoreLibs.FileStorage/Services/AzureFileStorageService.cs

@@ -47,7 +47,7 @@ internal AzureFileStorageService(IShareClientWrapper clientWrapper)
     }
 
     /// <inheritdoc />
-    public async Task UploadAsync(string path, Stream content, CancellationToken token = default)
+    public async Task UploadAsync(string path, Stream content, string? originalFileName = null,  CancellationToken token = default)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(path);
         ArgumentNullException.ThrowIfNull(content);

src/DfE.CoreLibs.FileStorage/Services/LocalFileStorageService.cs

@@ -2,7 +2,9 @@
 using DfE.CoreLibs.FileStorage.Settings;
 using DfE.CoreLibs.FileStorage.Exceptions;
 using System.IO;
+using System.Text.RegularExpressions;
 using FileNotFoundException = DfE.CoreLibs.FileStorage.Exceptions.FileNotFoundException;
+using System.Xml.Linq;
 
 namespace DfE.CoreLibs.FileStorage.Services;
 
@@ -16,6 +18,9 @@ public class LocalFileStorageService : IFileStorageService
     private readonly bool _allowOverwrite;
     private readonly long _maxFileSizeBytes;
     private readonly string[] _allowedExtensions;
+    private readonly Regex? _allowedFileNamePattern;
+    private readonly string _friendlyAllowedFileNamePattern;
+    private readonly string _friendlyAllowedFileExtensionsPattern;
 
     /// <summary>
     /// Creates a new instance of the service using the provided configuration <paramref name="options"/>.
@@ -28,10 +33,25 @@ public LocalFileStorageService(FileStorageOptions options)
         ArgumentNullException.ThrowIfNull(options);
 
         var localOptions = options.Local;
+        _friendlyAllowedFileNamePattern = localOptions.AllowedFileNamePatternFriendlyList;
+        _friendlyAllowedFileExtensionsPattern = localOptions.AllowedExtensionsFriendlyList;
         _createDirectoryIfNotExists = localOptions.CreateDirectoryIfNotExists;
         _allowOverwrite = localOptions.AllowOverwrite;
         _maxFileSizeBytes = localOptions.MaxFileSizeBytes;
         _allowedExtensions = localOptions.AllowedExtensions ?? Array.Empty<string>();
+        
+        // Initialize filename pattern if specified
+        if (!string.IsNullOrWhiteSpace(localOptions.AllowedFileNamePattern))
+        {
+            try
+            {
+                _allowedFileNamePattern = new Regex(localOptions.AllowedFileNamePattern, RegexOptions.Compiled);
+            }
+            catch (ArgumentException ex)
+            {
+                throw new FileStorageConfigurationException($"Invalid filename pattern: {localOptions.AllowedFileNamePattern}", ex);
+            }
+        }
 
         // Determine base directory
         if (string.IsNullOrWhiteSpace(localOptions.BaseDirectory))
@@ -66,13 +86,35 @@ public LocalFileStorageService(FileStorageOptions options)
     /// <summary>
     /// Internal constructor used for testing with custom settings.
     /// </summary>
-    internal LocalFileStorageService(string baseDirectory, bool createDirectoryIfNotExists = true, bool allowOverwrite = true, long maxFileSizeBytes = 100 * 1024 * 1024, string[] allowedExtensions = null)
+    internal LocalFileStorageService(string baseDirectory, 
+        bool createDirectoryIfNotExists = true, 
+        bool allowOverwrite = true, 
+        long maxFileSizeBytes = 100 * 1024 * 1024, 
+        string[] allowedExtensions = null, 
+        string allowedFileNamePattern = null, 
+        string? friendlyAllowedFileNamePattern = "a-z A-Z 0-9 _ - no-space", 
+        string? friendlyAllowedFileExtensionsPattern = "\"jpg\", \"png\", \"pdf\", \"docx\"")
     {
         _baseDirectory = Path.GetFullPath(baseDirectory);
+        _friendlyAllowedFileNamePattern = friendlyAllowedFileNamePattern;
+        _friendlyAllowedFileExtensionsPattern = friendlyAllowedFileExtensionsPattern;
         _createDirectoryIfNotExists = createDirectoryIfNotExists;
         _allowOverwrite = allowOverwrite;
         _maxFileSizeBytes = maxFileSizeBytes;
         _allowedExtensions = allowedExtensions ?? Array.Empty<string>();
+        
+        // Initialize filename pattern if specified
+        if (!string.IsNullOrWhiteSpace(allowedFileNamePattern))
+        {
+            try
+            {
+                _allowedFileNamePattern = new Regex(allowedFileNamePattern, RegexOptions.Compiled);
+            }
+            catch (ArgumentException ex)
+            {
+                throw new FileStorageConfigurationException($"Invalid filename pattern: {allowedFileNamePattern}", ex);
+            }
+        }
 
         if (_createDirectoryIfNotExists && !Directory.Exists(_baseDirectory))
         {
@@ -81,7 +123,7 @@ internal LocalFileStorageService(string baseDirectory, bool createDirectoryIfNot
     }
 
     /// <inheritdoc />
-    public async Task UploadAsync(string path, Stream content, CancellationToken token = default)
+    public async Task UploadAsync(string path, Stream content, string? originalFileName = null, CancellationToken token = default)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(path);
         ArgumentNullException.ThrowIfNull(content);
@@ -99,13 +141,28 @@ public async Task UploadAsync(string path, Stream content, CancellationToken tok
                 var fileExtension = Path.GetExtension(path);
                 if (string.IsNullOrEmpty(fileExtension))
                 {
-                    throw new FileStorageException($"File extension is required. Allowed extensions: {string.Join(", ", _allowedExtensions)}");
+                    throw new FileStorageException($"File extension is required. Allowed extensions: {_friendlyAllowedFileExtensionsPattern}");
                 }
 
                 var extensionWithoutDot = fileExtension.TrimStart('.');
                 if (!_allowedExtensions.Contains(extensionWithoutDot, StringComparer.OrdinalIgnoreCase))
                 {
-                    throw new FileStorageException($"File extension '{extensionWithoutDot}' is not allowed. Allowed extensions: {string.Join(", ", _allowedExtensions)}");
+                    throw new FileStorageException($"File extension '{extensionWithoutDot}' is not allowed. Allowed extensions: {_friendlyAllowedFileExtensionsPattern}");
+                }
+            }
+
+            // Validate filename pattern if configured
+            if (_allowedFileNamePattern != null && originalFileName != null)
+            {
+                var fileName = Path.GetFileNameWithoutExtension(originalFileName);
+                if (string.IsNullOrEmpty(fileName))
+                {
+                    throw new FileStorageException($"Filename is required when filename pattern validation is enabled. Pattern: {_friendlyAllowedFileNamePattern}");
+                }
+
+                if (!_allowedFileNamePattern.IsMatch(fileName))
+                {
+                    throw new FileStorageException($"Filename '{fileName}' does not match the allowed pattern. Pattern: {_friendlyAllowedFileNamePattern}");
                 }
             }
 

src/DfE.CoreLibs.FileStorage/Settings/LocalFileStorageOptions.cs

@@ -33,4 +33,24 @@ public class LocalFileStorageOptions
     /// Example: ["jpg", "png", "pdf", "docx"]
     /// </summary>
     public string[] AllowedExtensions { get; set; } = Array.Empty<string>();
+
+    /// <summary>
+    /// Friendly human-readable list of allowed file extensions.
+    /// Example: ["jpg", "png", "pdf", "docx"]
+    /// </summary>
+    public string AllowedExtensionsFriendlyList { get; set; } = "\"jpg\", \"png\", \"pdf\", \"docx\"";
+
+    /// <summary>
+    /// Regular expression pattern for allowed file names. 
+    /// If null or empty, no filename pattern validation is applied.
+    /// Default pattern allows letters, numbers, underscores, and hyphens.
+    /// Example: "^[a-zA-Z0-9_-]+$"
+    /// </summary>
+    public string? AllowedFileNamePattern { get; set; } = null;
+
+    /// <summary>
+    /// Friendly and human-readable list of allowed file name characters. 
+    /// Example: a-zA-Z0-9_-
+    /// </summary>
+    public string AllowedFileNamePatternFriendlyList { get; set; } = "a-z A-Z 0-9 _ - no-space";
 } 

src/Tests/DfE.CoreLibs.FileStorage.Tests/LocalFileStorageIntegrationTests.cs

@@ -252,7 +252,10 @@ public async Task UploadWithCustomSettings_ShouldRespectConfiguration()
             ["FileStorage:Local:MaxFileSizeBytes"] = "1024", // 1KB limit
             ["FileStorage:Local:AllowedExtensions:0"] = "jpg",
             ["FileStorage:Local:AllowedExtensions:1"] = "png",
-            ["FileStorage:Local:AllowedExtensions:2"] = "pdf"
+            ["FileStorage:Local:AllowedExtensions:2"] = "pdf",
+            ["FileStorage:Local:AllowedExtensionsFriendlyList"] = "jpg, png, pdf",
+            ["FileStorage:Local:AllowedFileNamePatternFriendlyList"] = "a-z A-Z 0-9 _ - no-space"
+
         });
 
         services.AddFileStorage(configuration);

src/Tests/DfE.CoreLibs.FileStorage.Tests/Services/AzureFileStorageServiceTests.cs

@@ -335,7 +335,7 @@ public async Task AllMethods_WithCancellationToken_ShouldPassTokenToClient()
         _mockFileClient.DownloadAsync(cancellationToken).ThrowsAsync(new OperationCanceledException());
 
         // Act & Assert - All methods should pass the cancellation token and throw when cancelled
-        await Assert.ThrowsAsync<OperationCanceledException>(() => _service.UploadAsync(path, content, cancellationToken));
+        await Assert.ThrowsAsync<OperationCanceledException>(() => _service.UploadAsync(path, content, originalFileName: null, cancellationToken));
         await Assert.ThrowsAsync<OperationCanceledException>(() => _service.DownloadAsync(path, cancellationToken));
         await Assert.ThrowsAsync<OperationCanceledException>(() => _service.DeleteAsync(path, cancellationToken));
         await Assert.ThrowsAsync<OperationCanceledException>(() => _service.ExistsAsync(path, cancellationToken));

src/Tests/DfE.CoreLibs.FileStorage.Tests/Services/IFileStorageServiceTests.cs

@@ -56,12 +56,14 @@ public void IFileStorageService_UploadAsync_ShouldHaveCorrectSignature()
         // Assert
         Assert.NotNull(method);
         Assert.Equal(typeof(Task), method.ReturnType);
-        Assert.Equal(3, method.GetParameters().Length);
+        Assert.Equal(4, method.GetParameters().Length);
 
         var parameters = method.GetParameters();
         Assert.Equal(typeof(string), parameters[0].ParameterType);
         Assert.Equal(typeof(Stream), parameters[1].ParameterType);
-        Assert.Equal(typeof(CancellationToken), parameters[2].ParameterType);
+        Assert.Equal(typeof(string), parameters[2].ParameterType);
+        Assert.Equal(typeof(CancellationToken), parameters[3].ParameterType);
+
         Assert.True(parameters[2].HasDefaultValue);
     }
 
@@ -140,7 +142,7 @@ public void IFileStorageService_ShouldSupportCancellation()
         var cancellationToken = new CancellationToken(true); // Cancelled token
 
         // Act & Assert - All methods should support cancellation
-        Assert.ThrowsAsync<OperationCanceledException>(() => service.UploadAsync("test.txt", new MemoryStream(), cancellationToken));
+        Assert.ThrowsAsync<OperationCanceledException>(() => service.UploadAsync("test.txt", new MemoryStream(), originalFileName: null, cancellationToken));
         Assert.ThrowsAsync<OperationCanceledException>(() => service.DownloadAsync("test.txt", cancellationToken));
         Assert.ThrowsAsync<OperationCanceledException>(() => service.DeleteAsync("test.txt", cancellationToken));
         Assert.ThrowsAsync<OperationCanceledException>(() => service.ExistsAsync("test.txt", cancellationToken));