MimeMaster 1.0.0-preview.1

🧙‍♂️ MimeMaster

MimeMaster is a fast, accurate .NET library for detecting and validating file types based on file signatures (magic numbers). It provides reliable file type detection regardless of file extensions by examining file headers and trailers.

✨ Features

• 🔍 Accurate MIME type detection based on file signatures
• ✅ File validation against allowed MIME types and size constraints
• 📦 Support for common file formats: PDF, Office documents, images, and more
• 🧩 Extensible design for adding custom file types
• 🔄 Integration with .NET dependency injection

📦 Installation

Package Manager Console

Install-Package MimeMaster

.NET CLI

dotnet add package MimeMaster

🚀 Quick Start

Basic Usage

// Create services manually
var logger = LoggerFactory.Create(builder => builder.AddConsole()).CreateLogger<FileTypeService>();
var fileTypeService = new FileTypeService(logger);

// Detect MIME type
string filePath = "path/to/your/file.pdf";
byte[] fileData = File.ReadAllBytes(filePath);
var fileType = fileTypeService.GetMimeType(filePath, fileData);

Console.WriteLine($"MIME type: {fileType.Mime}");
Console.WriteLine($"Extension: {fileType.Extension}");

With Dependency Injection

// In Startup.ConfigureServices or Program.cs
services.AddMimeMaster();

// In your controller or service
public class MyService
{
    private readonly IFileTypeService _fileTypeService;
    private readonly IValidationService _validationService;
    
    public MyService(IFileTypeService fileTypeService, IValidationService validationService)
    {
        _fileTypeService = fileTypeService;
        _validationService = validationService;
    }
    
    public void ProcessFile(string filePath)
    {
        byte[] fileData = File.ReadAllBytes(filePath);
        
        // Detect MIME type
        var fileType = fileTypeService.GetMimeType(filePath, fileData);
        
        // Validate file
        string allowedMimeTypes = "application/pdf,image/jpeg,image/png";
        long maxFileSize = 5 * 1024 * 1024; // 5MB
        
        var validationResult = _validationService.Validate(
            filePath, 
            fileData, 
            allowedMimeTypes, 
            maxFileSize);
            
        if (validationResult.HasFailed)
        {
            foreach (var invalidFile in validationResult.InvalidFiles)
            {
                Console.WriteLine($"Validation failed: {invalidFile.Errors}");
            }
        }
    }
}

📋 Supported File Types

MimeMaster currently supports the following file types:

• 📄 PDF (.pdf)
• 📝 Word Documents (.doc, .docx)
• 📊 Excel Spreadsheets (.xls, .xlsx)
• 📊 PowerPoint Presentations (.ppt, .pptx)
• 🖼️ Images (.jpg, .jpeg, .png, .bmp, .gif)
• 🎬 Video (.mp4, .flv)
• 📄 Text (.txt, .rtf)

🔍 File Signatures

File signatures, also known as "magic numbers" or "magic bytes," are specific patterns at the beginning (headers) or end (trailers) of a file that identify its type regardless of file extension. MimeMaster uses these signatures to accurately identify file types.

The implementation is inspired by file signature tables and format specifications.

Common File Signatures

Format     Hex Signature                ASCII        Trailer                        Description
-------    -------------                -----        -------                        -----------
DOC/XLS    D0 CF 11 E0 A1 B1 1A E1     ÐÏ.ࡱ.á     -                              MS Office OLE Compound File
PDF        25 50 44 46 2D               %PDF-        0A 25 25 45 4F 46 (.%%EOF)     PDF Document
                                                     0A 25 25 45 4F 46 0A (.%%EOF.)
                                                     0D 0A 25 25 45 4F 46 0D 0A     
                                                     0D 25 25 45 4F 46 0D (.%%EOF.)
PNG        89 50 4E 47 0D 0A 1A 0A      ‰PNG....     49 45 4E 44 AE 42 60 82        PNG Image
                                                     (IEND®B`‚...)
DOCX/PPTX  50 4B 03 04 14 00 06 00      PK......     50 4B 05 06 (PK..) + 18 bytes  Office Open XML (OOXML) Document
XLSX                                                 at the end of the file
JPG        FF D8                         ÿØ          FF D9                          JPEG Image
ZIP        50 4B 03 04                   PK..        -                              ZIP Archive
PST        21 42 44 4E                   !BDN        -                              MS Outlook Personal Folder

MS Office Subheaders

Office binary formats (DOC, XLS, PPT) have specific subheaders at byte offset 512:

Format   Offset        Hex Signature                Description
------   ------        -------------                -----------
DOC      512           EC A5 C1 00                  Word document subheader
XLS      512           FD FF FF FF nn 00            Excel spreadsheet subheader
         or 512        FD FF FF FF nn 02            
         or 512        09 08 10 00 00 06 05 00      
PPT      512           A0 46 1D F0                  PowerPoint presentation subheader
         or 512        00 6E 1E F0
         or 512        0F 00 E8 03
         or 512        FD FF FF FF nn nn 00 00

Microsoft Office OOXML Formats

For Microsoft Office Open XML formats (DOCX, PPTX, XLSX), there is a specific detection pattern:

• Header signature: 50 4B 03 04 14 00 06 00 ("PK......")
• Trailer signature: Look for 50 4B 05 06 ("PK..") followed by 18 additional bytes at the end of the file

Unlike the older Office formats (DOC, PPT, XLS), there is no subheader for OOXML files. OOXML files are essentially ZIP files, so you can rename them with a .ZIP extension and then extract them to examine their contents. Inside, you'll find the [Content_Types].xml file that describes the content types, along with specific XML files:

• DOCX: Look for word/document.xml
• XLSX: Look for xl/workbook.xml
• PPTX: Look for ppt/presentation.xml

When examining the [Content_Types].xml file, look for the <Override PartName= tag, where you will find word, ppt, or xl, respectively.

The library includes signatures for various file formats and can be extended to support additional formats as needed.

📚 API Reference

IFileTypeService

public interface IFileTypeService
{
    FileType GetMimeType(string fileName, byte[] fileData);
}

IValidationService

public interface IValidationService
{
    ValidationResult Validate(
        string fileName, 
        byte[] fileData, 
        string allowedMimeTypes, 
        long maxFileSize, 
        long minFileSize = 0);
}

ValidationErrors

[Flags]
public enum ValidationErrors
{
    None = 0,
    FileTypeNotAllowed = 1 << 0,
    FileTooLarge = 1 << 1,
    FileTooSmall = 1 << 2,
    FileTypeUnknown = 1 << 3
}

📊 Performance

MimeMaster is designed for high-performance applications:

• ⚡ Fast detection: Optimized signature matching algorithms
• 🧠 Low memory overhead: Minimal allocations during detection
• 🔄 Thread-safe: Safe for concurrent use

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• File signatures information sourced from various format specifications and references
• Inspired by other open-source MIME type detection libraries

<p align="center">Made with ❤️ for the .NET community</p>

MimeMaster