safeuploads 0.1.0__tar.gz

safeuploads-0.1.0/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2025 João Vitória Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

safeuploads-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: safeuploads
+Version: 0.1.0
+Summary: A comprehensive file security system for validating uploads and preventing attacks
+License: MIT
+License-File: LICENSE.md
+Author: João Vitória Silva
+Author-email: joao@endurain.com
+Requires-Python: >=3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: dev
+Provides-Extra: fastapi
+Requires-Dist: fastapi (>=0.110,<1.0) ; extra == "fastapi"
+Requires-Dist: pytest (>=8.0,<9.0) ; extra == "dev"
+Requires-Dist: pytest-asyncio (>=0.23,<1.0) ; extra == "dev"
+Requires-Dist: pytest-cov (>=4.1,<5.0) ; extra == "dev"
+Requires-Dist: python-magic (>=0.4.27,<0.5.0)
+Description-Content-Type: text/markdown
+
+# safeuploads
+
+![License](https://img.shields.io/github/license/joaovitoriasilva/safeuploads)
+[![GitHub release](https://img.shields.io/github/v/release/joaovitoriasilva/safeuploads)](https://github.com/joaovitoriasilva/safeuploads/releases)
+[![GitHub stars](https://img.shields.io/github/stars/joaovitoriasilva/safeuploads.svg?style=social&label=Star)](https://github.com/joaovitoriasilva/safeuploads/stargazers)
+
+Secure file upload validation for Python 3.13+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
+
+## Features
+
+- **Framework-agnostic** async validation (FastAPI, generic)
+- Filename sanitization and Unicode security checks
+- Extension validation with configurable allow/block lists
+- ZIP bomb detection and content inspection
+- MIME type verification with signature validation
+- Rich exception hierarchy for precise error handling
+- Zero configuration required—secure defaults out of the box
+
+## Installation
+
+```bash
+pip install safeuploads
+```
+
+For FastAPI integration:
+```bash
+pip install safeuploads[fastapi]
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, UploadFile, HTTPException
+from safeuploads import FileValidator
+from safeuploads.exceptions import FileValidationError
+
+app = FastAPI()
+validator = FileValidator()
+
+@app.post("/upload")
+async def upload_image(file: UploadFile):
+    try:
+        await validator.validate_image_file(file)
+    except FileValidationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    
+    return {"status": "success", "filename": file.filename}
+```
+
+## Configuration
+
+```python
+from safeuploads import FileValidator, FileSecurityConfig
+
+# Use default secure configuration
+validator = FileValidator()
+
+# Or customize limits
+config = FileSecurityConfig()
+config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
+config.limits.max_compression_ratio = 50
+
+validator = FileValidator(config=config)
+```
+
+## Exception Handling
+
+```python
+from safeuploads.exceptions import (
+    FileValidationError,      # Base exception
+    FileSizeError,            # File too large
+    ExtensionSecurityError,   # Dangerous extension
+    ZipBombError,             # Compression attack
+)
+
+try:
+    await validator.validate_image_file(file)
+except FileSizeError as err:
+    return {"error": "File too large", "max_size": err.max_size}
+except ExtensionSecurityError as err:
+    return {"error": "File type not allowed", "extension": err.extension}
+except FileValidationError as err:
+    return {"error": str(err), "code": err.error_code}
+```
+
+## Current Status & Roadmap
+
+### What's Working
+
+- **Filename Security**: Unicode normalization, directory traversal prevention, Windows reserved names blocking
+- **Extension Validation**: Allow/block lists with configurable rules, dangerous extension detection
+- **Compression Security**: ZIP bomb detection, nested archive inspection, size and ratio limits
+- **Content Inspection**: Deep ZIP content analysis with configurable depth and entry limits
+- **MIME Type Verification**: Magic number validation for common file types
+- **Rich Exception System**: Machine-readable error codes with detailed context
+
+### Planned Improvements
+
+#### Critical (Pre-1.0)
+- **Streaming Validation**: Memory-efficient processing for large files to prevent resource exhaustion
+- **Resource Limits**: CPU and memory monitoring during validation operations
+- **Rate Limiting Guide**: Documentation and examples for production deployments
+
+#### High Priority
+- **Enhanced ZIP Security**: Protection against recursive ZIP structures and algorithmic complexity attacks
+- **Audit Logging**: Structured logging for security-relevant events with request correlation
+- **Performance Optimizations**: Pattern caching, compiled regex optimization, async I/O improvements
+
+#### Future Enhancements
+- **Additional File Types**: .gpx, .tcx, .fit, .gz
+- **Content Analysis**: Malware signature detection, embedded script scanning
+- **Fuzzing Tests**: Automated testing with malformed and malicious payloads
+- **Security Documentation**: Threat model, architecture diagrams, integration security checklist
+
+### Production Readiness
+
+**Status**: Beta - suitable for testing, not yet recommended for production use
+
+**Before Production**:
+1. Address memory exhaustion vulnerability in ZIP inspection
+2. Implement streaming validation for large files
+3. Complete security audit and penetration testing
+
+**Known Limitations**:
+- No built-in rate limiting (must be implemented at application level)
+- Limited to synchronous content reading in ZIP inspection
+- Performance not yet optimized for high-throughput scenarios
+
+## Documentation
+
+Full documentation available at [link to your docs].
+
+## Sponsors
+
+A huge thank you to the project sponsors! Your support helps keep this project going.
+
+Consider [sponsoring safeuploads on GitHub](https://github.com/sponsors/joaovitoriasilva) to ensure continuous development.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guidelines](CONTRIBUTING.md) for guidelines.
+
+
+

safeuploads-0.1.0/README.md

@@ -0,0 +1,147 @@
+# safeuploads
+
+![License](https://img.shields.io/github/license/joaovitoriasilva/safeuploads)
+[![GitHub release](https://img.shields.io/github/v/release/joaovitoriasilva/safeuploads)](https://github.com/joaovitoriasilva/safeuploads/releases)
+[![GitHub stars](https://img.shields.io/github/stars/joaovitoriasilva/safeuploads.svg?style=social&label=Star)](https://github.com/joaovitoriasilva/safeuploads/stargazers)
+
+Secure file upload validation for Python 3.13+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
+
+## Features
+
+- **Framework-agnostic** async validation (FastAPI, generic)
+- Filename sanitization and Unicode security checks
+- Extension validation with configurable allow/block lists
+- ZIP bomb detection and content inspection
+- MIME type verification with signature validation
+- Rich exception hierarchy for precise error handling
+- Zero configuration required—secure defaults out of the box
+
+## Installation
+
+```bash
+pip install safeuploads
+```
+
+For FastAPI integration:
+```bash
+pip install safeuploads[fastapi]
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, UploadFile, HTTPException
+from safeuploads import FileValidator
+from safeuploads.exceptions import FileValidationError
+
+app = FastAPI()
+validator = FileValidator()
+
+@app.post("/upload")
+async def upload_image(file: UploadFile):
+    try:
+        await validator.validate_image_file(file)
+    except FileValidationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    
+    return {"status": "success", "filename": file.filename}
+```
+
+## Configuration
+
+```python
+from safeuploads import FileValidator, FileSecurityConfig
+
+# Use default secure configuration
+validator = FileValidator()
+
+# Or customize limits
+config = FileSecurityConfig()
+config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
+config.limits.max_compression_ratio = 50
+
+validator = FileValidator(config=config)
+```
+
+## Exception Handling
+
+```python
+from safeuploads.exceptions import (
+    FileValidationError,      # Base exception
+    FileSizeError,            # File too large
+    ExtensionSecurityError,   # Dangerous extension
+    ZipBombError,             # Compression attack
+)
+
+try:
+    await validator.validate_image_file(file)
+except FileSizeError as err:
+    return {"error": "File too large", "max_size": err.max_size}
+except ExtensionSecurityError as err:
+    return {"error": "File type not allowed", "extension": err.extension}
+except FileValidationError as err:
+    return {"error": str(err), "code": err.error_code}
+```
+
+## Current Status & Roadmap
+
+### What's Working
+
+- **Filename Security**: Unicode normalization, directory traversal prevention, Windows reserved names blocking
+- **Extension Validation**: Allow/block lists with configurable rules, dangerous extension detection
+- **Compression Security**: ZIP bomb detection, nested archive inspection, size and ratio limits
+- **Content Inspection**: Deep ZIP content analysis with configurable depth and entry limits
+- **MIME Type Verification**: Magic number validation for common file types
+- **Rich Exception System**: Machine-readable error codes with detailed context
+
+### Planned Improvements
+
+#### Critical (Pre-1.0)
+- **Streaming Validation**: Memory-efficient processing for large files to prevent resource exhaustion
+- **Resource Limits**: CPU and memory monitoring during validation operations
+- **Rate Limiting Guide**: Documentation and examples for production deployments
+
+#### High Priority
+- **Enhanced ZIP Security**: Protection against recursive ZIP structures and algorithmic complexity attacks
+- **Audit Logging**: Structured logging for security-relevant events with request correlation
+- **Performance Optimizations**: Pattern caching, compiled regex optimization, async I/O improvements
+
+#### Future Enhancements
+- **Additional File Types**: .gpx, .tcx, .fit, .gz
+- **Content Analysis**: Malware signature detection, embedded script scanning
+- **Fuzzing Tests**: Automated testing with malformed and malicious payloads
+- **Security Documentation**: Threat model, architecture diagrams, integration security checklist
+
+### Production Readiness
+
+**Status**: Beta - suitable for testing, not yet recommended for production use
+
+**Before Production**:
+1. Address memory exhaustion vulnerability in ZIP inspection
+2. Implement streaming validation for large files
+3. Complete security audit and penetration testing
+
+**Known Limitations**:
+- No built-in rate limiting (must be implemented at application level)
+- Limited to synchronous content reading in ZIP inspection
+- Performance not yet optimized for high-throughput scenarios
+
+## Documentation
+
+Full documentation available at [link to your docs].
+
+## Sponsors
+
+A huge thank you to the project sponsors! Your support helps keep this project going.
+
+Consider [sponsoring safeuploads on GitHub](https://github.com/sponsors/joaovitoriasilva) to ensure continuous development.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guidelines](CONTRIBUTING.md) for guidelines.
+
+

safeuploads-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "safeuploads"
+version = "0.1.0"
+description = "A comprehensive file security system for validating uploads and preventing attacks"
+authors = [
+    {name = "João Vitória Silva",email = "joao@endurain.com"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "python-magic (>=0.4.27,<0.5.0)",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi (>=0.110,<1.0)"]
+dev = [
+    "pytest (>=8.0,<9.0)",
+    "pytest-asyncio (>=0.23,<1.0)",
+    "pytest-cov (>=4.1,<5.0)",
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "-ra",
+    "--cov=safeuploads",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests",
+    "slow: Slow running tests",
+    "performance: Performance and benchmarking tests",
+]
+
+[tool.coverage.run]
+source = ["safeuploads"]
+omit = ["*/tests/*", "*/__pycache__/*"]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]

safeuploads-0.1.0/safeuploads/__init__.py

@@ -0,0 +1,92 @@
+"""
+File Security Module
+
+A comprehensive file security system for validating uploads and preventing attacks.
+"""
+
+# Core classes and configurations
+from .config import SecurityLimits, FileSecurityConfig
+from .exceptions import (
+    ConfigValidationError,
+    FileSecurityConfigurationError,
+    ErrorCode,
+    FileSecurityError,
+    FileValidationError,
+    FilenameSecurityError,
+    UnicodeSecurityError,
+    ExtensionSecurityError,
+    WindowsReservedNameError,
+    FileSizeError,
+    MimeTypeError,
+    FileSignatureError,
+    CompressionSecurityError,
+    ZipBombError,
+    ZipContentError,
+    FileProcessingError,
+)
+from .enums import (
+    DangerousExtensionCategory,
+    CompoundExtensionCategory,
+    UnicodeAttackCategory,
+    SuspiciousFilePattern,
+    ZipThreatCategory,
+)
+
+# Main validator
+from .file_validator import FileValidator
+
+# Specialized validators
+from .validators import (
+    BaseValidator,
+    UnicodeSecurityValidator,
+    ExtensionSecurityValidator,
+    WindowsSecurityValidator,
+    CompressionSecurityValidator,
+)
+
+# Inspectors
+from .inspectors import ZipContentInspector
+
+# Perform configuration validation when module is imported
+# This ensures configuration issues are caught early during application startup
+FileSecurityConfig.validate_and_report(strict=False)
+
+# Export all public APIs
+__all__ = [
+    # Core configuration
+    "SecurityLimits",
+    "FileSecurityConfig",
+    # Exceptions
+    "ConfigValidationError",
+    "FileSecurityConfigurationError",
+    "ErrorCode",
+    "FileSecurityError",
+    "FileValidationError",
+    "FilenameSecurityError",
+    "UnicodeSecurityError",
+    "ExtensionSecurityError",
+    "WindowsReservedNameError",
+    "FileSizeError",
+    "MimeTypeError",
+    "FileSignatureError",
+    "CompressionSecurityError",
+    "ZipBombError",
+    "ZipContentError",
+    "FileProcessingError",
+    # Enums
+    "DangerousExtensionCategory",
+    "CompoundExtensionCategory",
+    "UnicodeAttackCategory",
+    "SuspiciousFilePattern",
+    "ZipThreatCategory",
+    # Main validator
+    "FileValidator",
+    # Specialized validators
+    "BaseValidator",
+    "UnicodeSecurityValidator",
+    "ExtensionSecurityValidator",
+    "WindowsSecurityValidator",
+    "CompressionSecurityValidator",
+    # Inspectors
+    "ZipContentInspector",
+]