safeuploads 2.2.0__tar.gz → 4.0.0__tar.gz

{safeuploads-2.2.0 → safeuploads-4.0.0}/.agents/skills/safeuploads-library/references/code-standards.md

@@ -1,7 +1,7 @@
 # Code standards
 
 ## Python
-- Python 3.13 syntax (`requires-python = ">=3.13"`): `int | None`, `list[str]`, `dict[str, Any]`; no `typing.Optional/List/Dict`.
+- Python 3.11 syntax and standard library (`requires-python = ">=3.11"`): `int | None`, `list[str]`, `dict[str, Any]`; no `typing.Optional/List/Dict`, and no 3.12+ features such as PEP 695 type parameters, `type` aliases or `typing.override`. The 3.11 CI job is the check.
 - Lines up to 79 characters, enforced by `ruff format` (`line-length = 79`); keep comments and docstrings within it too.
 - Imports grouped stdlib / third-party / local; `TYPE_CHECKING` to avoid cycles.
 - Every module has a top-level docstring.

{safeuploads-2.2.0 → safeuploads-4.0.0}/.github/workflows/test-matrix-safeuploads.yml

@@ -1,7 +1,7 @@
 name: Test matrix safeuploads
 
 # Portability matrix on top of the fast default `Lint & Test` workflow:
-#   * every supported Python version (3.13, 3.14, 3.15) with the full
+#   * every supported Python version (3.11 to 3.15) with the full
 #     dependency set (dev group + fastapi extra), proving the suite
 #     passes on every Python the package declares support for; and
 #   * a bare `import safeuploads` with only the base dependencies
@@ -40,7 +40,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.13", "3.14", "3.15"]
+        python: ["3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

{safeuploads-2.2.0 → safeuploads-4.0.0}/AGENTS.md

@@ -1,6 +1,6 @@
 # safeuploads
 
-Secure file upload validation for Python 3.13+ applications.
+Secure file upload validation for Python 3.11+ applications.
 Catches dangerous filenames, malicious extensions, Windows reserved names, compression bombs, polyglots and unsafe XML before an upload is accepted.
 Runtime dependencies are minimal (`python-magic`, `defusedxml`; FastAPI behind the `fastapi` extra).
 Published to PyPI; the public API is governed by SemVer.
@@ -33,7 +33,7 @@ docs/           Documentation site (mkdocs)
 
 ## Commands
 
-From the repository root (Python 3.13+, `uv`, system `libmagic`):
+From the repository root (Python 3.11+, `uv`, system `libmagic`):
 
 ```bash
 uv sync --dev --extra fastapi
@@ -97,4 +97,4 @@ uv run pytest
 - Never build a filesystem path from an uploaded filename.
 - Logging uses `logging.getLogger(__name__)` and the `SecurityAuditLogger`; never log file contents.
 - Comments and docstrings state what the code does now, not what it used to do.
-- Python 3.13 syntax, 79-character lines (`pyproject.toml`), PEP 257 docstrings with `Args`, `Returns`, `Raises` where applicable.
+- Python 3.11 syntax and standard library (no 3.12+ features), 79-character lines (`pyproject.toml`), PEP 257 docstrings with `Args`, `Returns`, `Raises` where applicable.

{safeuploads-2.2.0 → safeuploads-4.0.0}/CHANGELOG.md

@@ -4,6 +4,63 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] - 2026-11-06
+
+### Added
+
+- WebP image support. `FileSignatureValidator` accepts a RIFF container whose form type at bytes 8-11 is `WEBP` as an image signature; WAV, AVI and other RIFF files are still rejected. `ALLOWED_IMAGE_TYPES` maps `image/webp` to `.webp`.
+- `ValidationResult`, exported from `safeuploads`: a frozen dataclass with the sanitized `filename` and the `mime_type` libmagic detected from the content. A ZIP or gzip that libmagic reports only as `application/octet-stream` (libmagic 5.46 reports every ZIP this way) carries `application/zip` or `application/gzip`, the type its magic signature confirmed. Use `mime_type` for the `Content-Type` of a stored or served copy, and the extension of `filename`, which is checked against `mime_type`, for a stored file's extension, as the integration checklist recommends. `mime_type` alone cannot choose the extension, since GPX and TCX share their XML types.
+- `ErrorCode.EXTENSION_MIME_MISMATCH`, raised with `MimeTypeError` when the content's MIME type is allowed but the filename's extension is not one listed for it. `allowed_mimes` on the error lists the MIME types that extension permits.
+- Image dimension limit against decompression (pixel) bombs. `ImageDimensionValidator`, exported from `safeuploads`, reads width and height from the PNG IHDR chunk, the first JPEG frame header or the first WebP chunk (VP8, VP8L or the VP8X canvas) without decoding pixel data, and rejects an image whose width times height exceeds the new `SecurityLimits.max_image_pixels` (default 89,478,485, Pillow's `Image.MAX_IMAGE_PIXELS`). Configuration validation rejects a limit of 0 or less (`invalid_pixel_limit`) and warns above twice the default (`excessive_pixel_limit`).
+- `ImageDimensionError`, exported from `safeuploads`: a `FileValidationError` with `width`, `height` and `max_pixels`, raised with the new `ErrorCode.IMAGE_DIMENSIONS_EXCEEDED`.
+- `ErrorCode.IMAGE_INVALID_STRUCTURE`, raised with `FileSignatureError` when an image's dimension header is missing, truncated or invalid.
+- `FileSecurityConfig.ALLOWED_IMAGE_TYPES`, `ALLOWED_ZIP_TYPES`, `ALLOWED_ACTIVITY_TYPES` and `ALLOWED_GZIP_TYPES`: read-only mappings from each allowed MIME type to the extensions its content may carry. Configuration validation reports an empty mapping (`empty_mime_set`), a MIME type with no extensions (`empty_extension_set`), and the existing extension format, case and block-list conflict checks on every listed extension.
+
+### Changed
+
+- **Breaking:** every `validate_*_file()` method returns a `ValidationResult` instead of `None`, and every `validate_*_file_sync()` method returns a `ValidationResult` instead of the sanitized filename. Replace `name = validator.validate_image_file_sync(f, name)` with `name = validator.validate_image_file_sync(f, name).filename`.
+- **Breaking:** an upload is rejected with `MimeTypeError` (`EXTENSION_MIME_MISMATCH`) when its extension is not one listed for the MIME type detected from its content, for example a PNG or WebP named `photo.jpg`, or a JPEG named `photo.png`. 3.0.0 accepted any allowed extension with any allowed MIME type of the same category. To accept such a pair, list the extension under that MIME type, for example `".jpg"` under `"image/webp"`.
+- **Breaking:** `validate_image_file()` and `validate_image_file_sync()` accept `.webp` uploads with WebP content under the default configuration, which 3.0.0 rejected. A host that cannot handle WebP after validation removes `image/webp` from `ALLOWED_IMAGE_TYPES`.
+- **Breaking:** `validate_image_file()` and `validate_image_file_sync()` reject an image whose header declares more than `max_image_pixels` pixels with `ImageDimensionError` (`IMAGE_DIMENSIONS_EXCEEDED`), and an image whose dimension header is missing or malformed with `FileSignatureError` (`IMAGE_INVALID_STRUCTURE`): a PNG whose first chunk is not IHDR, a JPEG that reaches scan data or its end without a frame header or declares a zero width or height, or a WebP whose first chunk is not VP8, VP8L or VP8X. 3.0.0 accepted any image with a valid signature. To accept larger images, raise `max_image_pixels`.
+- Image uploads are streamed once to a spooled temporary file, like ZIP, activity and gzip uploads, instead of being read once for the size check and again for content analysis. The client's declared `size` is no longer checked before reading: an oversized image is rejected with the same `FileSizeError` (`FILE_TOO_LARGE`) once the bytes read exceed `max_image_size`, and `size` on the error is the byte count read at that point.
+- **Breaking:** FIT uploads get the MIME check the other formats get: a `.fit` file must be detected as `application/octet-stream`. A fake FIT that libmagic reports as text is now rejected with `EXTENSION_MIME_MISMATCH` before the FIT structure check.
+- **Breaking:** `MimeTypeValidator.enforce()` takes an allowed-types mapping instead of a set of MIME types and checks the filename's extension against it.
+- **Breaking:** `image/jpg` is no longer an allowed image MIME type. It is not a registered type and libmagic reports JPEG content as `image/jpeg`.
+
+### Removed
+
+- **Breaking:** `FileSecurityConfig.ALLOWED_IMAGE_MIMES`, `ALLOWED_ZIP_MIMES`, `ALLOWED_ACTIVITY_MIMES`, `ALLOWED_GZIP_MIMES`, `ALLOWED_IMAGE_EXTENSIONS`, `ALLOWED_ZIP_EXTENSIONS`, `ALLOWED_ACTIVITY_EXTENSIONS` and `ALLOWED_GZIP_EXTENSIONS`. Each pair is replaced by one `ALLOWED_*_TYPES` mapping, so a MIME type and its extensions can no longer be changed apart. A configuration that still sets one of the removed names, on a subclass or an instance, fails validation with `removed_setting`, so `FileValidator` raises `FileSecurityConfigurationError` instead of silently applying the default allow-list. Migrate a narrowed allow-list such as
+
+  ```python
+  config.ALLOWED_IMAGE_MIMES = frozenset({"image/png"})
+  config.ALLOWED_IMAGE_EXTENSIONS = frozenset({".png"})
+  ```
+
+  to
+
+  ```python
+  config.ALLOWED_IMAGE_TYPES = {"image/png": frozenset({".png"})}
+  ```
+
+## [3.0.0] - 2026-11-05
+
+### Added
+
+- Support for Python 3.11 and 3.12; `requires-python` is now `>=3.11` and CI tests 3.11 to 3.15. A Python version stays supported until its CPython end of life and is dropped in the next minor release after that. The Unicode checks use the running Python's Unicode database, so a character assigned after that database's version is rejected as unassigned (for example U+1FAE8 on 3.11).
+
+### Removed
+
+- **Breaking:** the `ConfigValidationError` alias, deprecated in 2.2.0, is removed from `safeuploads` and `safeuploads.exceptions`. Use `ConfigValidationIssue`.
+
+### Security
+
+- ZIP entry names now get the filename checks a top-level upload gets ([GHSA-jjqv-c38c-fjf3](https://github.com/endurain-project/safeuploads/security/advisories/GHSA-jjqv-c38c-fjf3)). `ZipContentInspector` checked entries only against `ZipThreatCategory.EXECUTABLE_FILES`, `SCRIPT_FILES` and `SYSTEM_FILES`, so an entry such as `invoice.docm`, `a.hta`, `CON.txt` or a name with a right-to-left override was accepted although the same name is rejected as an upload. Each entry name is now checked against `DANGEROUS_UNICODE_CHARS` and the rejected Unicode categories, each path component against `WINDOWS_RESERVED_NAMES`, and a file's base name against `BLOCKED_EXTENSIONS` and `COMPOUND_BLOCKED_EXTENSIONS`, on the NFC and NFKC forms, all taken from `FileSecurityConfig`. A failing entry raises `ZipContentError` with `ZIP_CONTENT_THREAT`.
+- The blocked-extension check ignores trailing dots and spaces, as Windows drops them when it saves a file. A filename such as `run.exe ` or `invoice.docm` followed by U+3000 or U+00A0 (which NFKC folds to a space) was accepted as an upload or a ZIP entry; it is now rejected with `EXTENSION_BLOCKED`.
+
+### Changed
+
+- **Breaking:** the ZIP entry name checks under Security reject archives that 2.2.0 accepted under the default configuration, for example archives with `.docm`, `.xlsm`, `.hta`, `.min.css` or `CON.txt` entries. Uploads and entries whose name ends in a blocked extension followed by spaces, such as `run.exe `, are rejected as well. An entry named `.jar`, `.war` or `.ear` whose content is a ZIP now reports `ZIP_CONTENT_THREAT` first instead of `ZIP_NESTED_ARCHIVE`.
+
 ## [2.2.0] - 2026-11-05
 
 ### Added
@@ -223,6 +280,8 @@ Initial release.
 - **MIME type verification:** magic-number validation for common file types.
 - Framework-agnostic async validation, a rich exception hierarchy with machine-readable error codes, secure defaults, and full type hints.
 
+[3.0.0]: https://github.com/endurain-project/safeuploads/compare/v2.2.0...v3.0.0
+[2.2.0]: https://github.com/endurain-project/safeuploads/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/endurain-project/safeuploads/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/endurain-project/safeuploads/compare/v1.1.3...v2.0.0
 [1.1.3]: https://github.com/endurain-project/safeuploads/compare/v1.1.2...v1.1.3

{safeuploads-2.2.0 → safeuploads-4.0.0}/CONTRIBUTING.md

@@ -72,7 +72,7 @@ PRs that are too large to review efficiently will be asked to be split before th
    docs: update the integration checklist
    ```
    Commit subjects and PR titles are validated in CI; see `.agents/skills/conventional-commits/SKILL.md` for the allowed types and scopes.
-5. **Run the checks** from the repository root (Python 3.13+, [uv](https://docs.astral.sh/uv/) and the system `libmagic`):
+5. **Run the checks** from the repository root (Python 3.11+, [uv](https://docs.astral.sh/uv/) and the system `libmagic`):
    ```bash
    uv sync --dev --extra fastapi
    uv run ruff check safeuploads tests examples

{safeuploads-2.2.0 → safeuploads-4.0.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: safeuploads
-Version: 2.2.0
+Version: 4.0.0
 Summary: A comprehensive file security system for validating uploads and preventing attacks
 Author-email: João Vitória Silva <joao@endurain.com>
 License: MIT
 License-File: LICENSE.md
-Requires-Python: >=3.13
+Requires-Python: >=3.11
 Requires-Dist: defusedxml<1.0.0,>=0.7.1
 Requires-Dist: python-magic<0.5.0,>=0.4.27
 Provides-Extra: fastapi
@@ -18,11 +18,11 @@ Description-Content-Type: text/markdown
 [![Release](https://img.shields.io/github/v/release/endurain-project/safeuploads?label=release&color=blue)](https://github.com/endurain-project/safeuploads/releases)
 [![PyPI version](https://img.shields.io/pypi/v/safeuploads)](https://pypi.org/project/safeuploads/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/safeuploads)](https://pypi.org/project/safeuploads/)
-[![Python](https://img.shields.io/badge/python-3.13%2B-blue)](https://pypi.org/project/safeuploads/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/safeuploads/)
 [![Docs](https://img.shields.io/badge/docs-safeuploads.endurain.com-blue)](https://safeuploads.endurain.com/)
 [![Stars](https://img.shields.io/github/stars/endurain-project/safeuploads?label=stars&logo=github)](https://github.com/endurain-project/safeuploads)
 
-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.
+Secure file upload validation for Python 3.11+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
 
 ## Features
 
@@ -46,6 +46,8 @@ Secure file upload validation for Python 3.13+ applications. Catches dangerous f
 pip install safeuploads
 ```
 
+safeuploads supports Python 3.11 and newer. A Python version stays supported until its CPython end of life and is dropped in the next minor release after that.
+
 For FastAPI integration:
 ```bash
 pip install safeuploads[fastapi]
@@ -64,14 +66,17 @@ validator = FileValidator()
 @app.post("/upload")
 async def upload_image(file: UploadFile):
     try:
-        await validator.validate_image_file(file)
+        result = await validator.validate_image_file(file)
     except FileValidationError as e:
         raise HTTPException(status_code=400, detail=str(e))
-    
-    return {"status": "success", "filename": file.filename}
+
+    # Store under a generated name; serve with the detected type
+    return {"filename": result.filename, "content_type": result.mime_type}
 ```
 
-For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the sanitized filename:
+Every validation method returns a `ValidationResult` with the sanitized `filename` and the `mime_type` detected from the content. A file whose extension is not one allowed for its detected type, such as a WebP named `photo.jpg`, is rejected with `MimeTypeError` (`EXTENSION_MIME_MISMATCH`).
+
+For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the same result:
 
 ```python
 from safeuploads import FileValidator
@@ -79,7 +84,7 @@ from safeuploads import FileValidator
 validator = FileValidator()
 
 with open("activity.gpx", "rb") as fh:
-    safe_name = validator.validate_activity_file_sync(fh, "activity.gpx")
+    result = validator.validate_activity_file_sync(fh, "activity.gpx")
 ```
 
 Calling a `*_sync` method on a thread running an asyncio event loop raises `RuntimeError`; await the async method there instead.
@@ -95,8 +100,16 @@ validator = FileValidator()
 # Or customize limits
 config = FileSecurityConfig()
 config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
+config.limits.max_image_pixels = 40_000_000  # 40 megapixels
 config.limits.max_compression_ratio = 50
 
+# Allowed content: each MIME type maps to the extensions its
+# content may carry
+config.ALLOWED_IMAGE_TYPES = {
+    "image/jpeg": frozenset({".jpg", ".jpeg"}),
+    "image/png": frozenset({".png"}),
+}
+
 # Opt in to strict ZIP checking: decompress every entry to
 # reject archives with forged central-directory metadata
 config.limits.verify_zip_decompression = True
@@ -142,9 +155,10 @@ except FileValidationError as err:
 - **Extension Validation**: Allow/block lists with configurable rules, dangerous extension detection
 - **Compression Security**: ZIP bomb detection, nested archive inspection, recursive structure and quine detection, size and ratio limits, optional strict decompression verification
 - **Content Inspection**: Deep ZIP content analysis with configurable depth and entry limits
-- **MIME Type Verification**: Magic number validation for images, ZIP, activity files, and gzip
+- **MIME Type Verification**: Magic number validation for images, ZIP, activity files, and gzip, with the extension required to match the detected type
 - **Streaming Validation**: Memory-efficient processing via `SpooledTemporaryFile` for large files
 - **Resource Monitoring**: wall-clock time and memory limits enforced via `ResourceMonitor` during the work
+- **Image Dimension Limits**: Header-only pixel count check for PNG, JPEG and WebP that rejects decompression (pixel) bombs before the host decodes them
 - **Activity File Support**: GPX, TCX, and FIT file validation with XXE-safe XML parsing and FIT structure checks
 - **Gzip Support**: Gzip archive validation with decompression bomb detection
 - **Content Analysis**: Optional malware signature, web shell, and polyglot file detection
@@ -157,6 +171,7 @@ except FileValidationError as err:
 
 - No built-in rate limiting (application-level concern — see documentation)
 - MIME detection covers first 8 KB; advanced polyglot attacks may require `enable_content_analysis`
+- Images are not decoded: only their dimension headers are checked, so decode and re-encode uploads in an isolated process (see the integration checklist)
 - `SpooledTemporaryFile` uses the system default temp directory
 
 ## Documentation

{safeuploads-2.2.0 → safeuploads-4.0.0}/README.md

@@ -4,11 +4,11 @@
 [![Release](https://img.shields.io/github/v/release/endurain-project/safeuploads?label=release&color=blue)](https://github.com/endurain-project/safeuploads/releases)
 [![PyPI version](https://img.shields.io/pypi/v/safeuploads)](https://pypi.org/project/safeuploads/)
 [![PyPI downloads](https://img.shields.io/pypi/dm/safeuploads)](https://pypi.org/project/safeuploads/)
-[![Python](https://img.shields.io/badge/python-3.13%2B-blue)](https://pypi.org/project/safeuploads/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/safeuploads/)
 [![Docs](https://img.shields.io/badge/docs-safeuploads.endurain.com-blue)](https://safeuploads.endurain.com/)
 [![Stars](https://img.shields.io/github/stars/endurain-project/safeuploads?label=stars&logo=github)](https://github.com/endurain-project/safeuploads)
 
-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.
+Secure file upload validation for Python 3.11+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
 
 ## Features
 
@@ -32,6 +32,8 @@ Secure file upload validation for Python 3.13+ applications. Catches dangerous f
 pip install safeuploads
 ```
 
+safeuploads supports Python 3.11 and newer. A Python version stays supported until its CPython end of life and is dropped in the next minor release after that.
+
 For FastAPI integration:
 ```bash
 pip install safeuploads[fastapi]
@@ -50,14 +52,17 @@ validator = FileValidator()
 @app.post("/upload")
 async def upload_image(file: UploadFile):
     try:
-        await validator.validate_image_file(file)
+        result = await validator.validate_image_file(file)
     except FileValidationError as e:
         raise HTTPException(status_code=400, detail=str(e))
-    
-    return {"status": "success", "filename": file.filename}
+
+    # Store under a generated name; serve with the detected type
+    return {"filename": result.filename, "content_type": result.mime_type}
 ```
 
-For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the sanitized filename:
+Every validation method returns a `ValidationResult` with the sanitized `filename` and the `mime_type` detected from the content. A file whose extension is not one allowed for its detected type, such as a WebP named `photo.jpg`, is rejected with `MimeTypeError` (`EXTENSION_MIME_MISMATCH`).
+
+For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the same result:
 
 ```python
 from safeuploads import FileValidator
@@ -65,7 +70,7 @@ from safeuploads import FileValidator
 validator = FileValidator()
 
 with open("activity.gpx", "rb") as fh:
-    safe_name = validator.validate_activity_file_sync(fh, "activity.gpx")
+    result = validator.validate_activity_file_sync(fh, "activity.gpx")
 ```
 
 Calling a `*_sync` method on a thread running an asyncio event loop raises `RuntimeError`; await the async method there instead.
@@ -81,8 +86,16 @@ validator = FileValidator()
 # Or customize limits
 config = FileSecurityConfig()
 config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
+config.limits.max_image_pixels = 40_000_000  # 40 megapixels
 config.limits.max_compression_ratio = 50
 
+# Allowed content: each MIME type maps to the extensions its
+# content may carry
+config.ALLOWED_IMAGE_TYPES = {
+    "image/jpeg": frozenset({".jpg", ".jpeg"}),
+    "image/png": frozenset({".png"}),
+}
+
 # Opt in to strict ZIP checking: decompress every entry to
 # reject archives with forged central-directory metadata
 config.limits.verify_zip_decompression = True
@@ -128,9 +141,10 @@ except FileValidationError as err:
 - **Extension Validation**: Allow/block lists with configurable rules, dangerous extension detection
 - **Compression Security**: ZIP bomb detection, nested archive inspection, recursive structure and quine detection, size and ratio limits, optional strict decompression verification
 - **Content Inspection**: Deep ZIP content analysis with configurable depth and entry limits
-- **MIME Type Verification**: Magic number validation for images, ZIP, activity files, and gzip
+- **MIME Type Verification**: Magic number validation for images, ZIP, activity files, and gzip, with the extension required to match the detected type
 - **Streaming Validation**: Memory-efficient processing via `SpooledTemporaryFile` for large files
 - **Resource Monitoring**: wall-clock time and memory limits enforced via `ResourceMonitor` during the work
+- **Image Dimension Limits**: Header-only pixel count check for PNG, JPEG and WebP that rejects decompression (pixel) bombs before the host decodes them
 - **Activity File Support**: GPX, TCX, and FIT file validation with XXE-safe XML parsing and FIT structure checks
 - **Gzip Support**: Gzip archive validation with decompression bomb detection
 - **Content Analysis**: Optional malware signature, web shell, and polyglot file detection
@@ -143,6 +157,7 @@ except FileValidationError as err:
 
 - No built-in rate limiting (application-level concern — see documentation)
 - MIME detection covers first 8 KB; advanced polyglot attacks may require `enable_content_analysis`
+- Images are not decoded: only their dimension headers are checked, so decode and re-encode uploads in an isolated process (see the integration checklist)
 - `SpooledTemporaryFile` uses the system default temp directory
 
 ## Documentation

{safeuploads-2.2.0 → safeuploads-4.0.0}/docs/index.md

@@ -12,7 +12,7 @@
     </a>
 </div>
 
-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.
+Secure file upload validation for Python 3.11+ applications. Catches dangerous filenames, malicious extensions, Windows reserved names, and compression-based attacks before you accept an upload.
 
 ## Features
 
@@ -54,14 +54,17 @@ validator = FileValidator()
 @app.post("/upload")
 async def upload_image(file: UploadFile):
     try:
-        await validator.validate_image_file(file)
+        result = await validator.validate_image_file(file)
     except FileValidationError as e:
         raise HTTPException(status_code=400, detail=str(e))
-    
-    return {"status": "success", "filename": file.filename}
+
+    # Store under a generated name; serve with the detected type
+    return {"filename": result.filename, "content_type": result.mime_type}
 ```
 
-For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the sanitized filename:
+Every validation method returns a `ValidationResult` with the sanitized `filename` and the `mime_type` detected from the content. A file whose extension is not one allowed for its detected type, such as a WebP named `photo.jpg`, is rejected with `MimeTypeError` (`EXTENSION_MIME_MISMATCH`).
+
+For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the same result:
 
 ```python
 from safeuploads import FileValidator
@@ -69,7 +72,7 @@ from safeuploads import FileValidator
 validator = FileValidator()
 
 with open("activity.gpx", "rb") as fh:
-    safe_name = validator.validate_activity_file_sync(fh, "activity.gpx")
+    result = validator.validate_activity_file_sync(fh, "activity.gpx")
 ```
 
 Calling a `*_sync` method on a thread running an asyncio event loop raises `RuntimeError`; await the async method there instead.
@@ -85,8 +88,16 @@ validator = FileValidator()
 # Or customize limits
 config = FileSecurityConfig()
 config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
+config.limits.max_image_pixels = 40_000_000  # 40 megapixels
 config.limits.max_compression_ratio = 50
 
+# Allowed content: each MIME type maps to the extensions its
+# content may carry
+config.ALLOWED_IMAGE_TYPES = {
+    "image/jpeg": frozenset({".jpg", ".jpeg"}),
+    "image/png": frozenset({".png"}),
+}
+
 # Opt in to strict ZIP checking: decompress every entry to
 # reject archives with forged central-directory metadata
 config.limits.verify_zip_decompression = True
@@ -132,9 +143,10 @@ except FileValidationError as err:
 - **Extension Validation**: Allow/block lists with configurable rules, dangerous extension detection
 - **Compression Security**: ZIP bomb detection, nested archive inspection, recursive structure and quine detection, size and ratio limits, optional strict decompression verification
 - **Content Inspection**: Deep ZIP content analysis with configurable depth and entry limits
-- **MIME Type Verification**: Magic number validation for images, ZIP, activity files, and gzip
+- **MIME Type Verification**: Magic number validation for images, ZIP, activity files, and gzip, with the extension required to match the detected type
 - **Streaming Validation**: Memory-efficient processing via `SpooledTemporaryFile` for large files
 - **Resource Monitoring**: wall-clock time and memory limits enforced via `ResourceMonitor` during the work
+- **Image Dimension Limits**: Header-only pixel count check for PNG, JPEG and WebP that rejects decompression (pixel) bombs before the host decodes them
 - **Activity File Support**: GPX, TCX, and FIT file validation with XXE-safe XML parsing and FIT structure checks
 - **Gzip Support**: Gzip archive validation with decompression bomb detection
 - **Content Analysis**: Optional malware signature, web shell, and polyglot file detection
@@ -147,6 +159,7 @@ except FileValidationError as err:
 
 - No built-in rate limiting (application-level concern — see [Rate Limiting](rate-limiting.md) guide)
 - MIME detection covers first 8 KB; advanced polyglot attacks may require `enable_content_analysis`
+- Images are not decoded: only their dimension headers are checked, so decode and re-encode uploads in an isolated process (see the integration checklist)
 - `SpooledTemporaryFile` uses the system default temp directory
 
 ## Documentation

{safeuploads-2.2.0 → safeuploads-4.0.0}/docs/security/architecture.md

@@ -25,6 +25,7 @@ safeuploads/
 │   ├── mime_validator.py      # Content MIME detection and enforcement
 │   ├── windows_validator.py   # Windows reserved name checks
 │   ├── fit_validator.py       # FIT container structure checks
+│   ├── image_dimension_validator.py # Pixel count from image headers
 │   ├── compression_validator.py # ZIP bomb detection
 │   └── xml_validator.py       # XXE-safe XML parsing
 └── inspectors/
@@ -39,19 +40,20 @@ safeuploads/
 | Component | Responsibility |
 |---|---|
 | `FileValidator` | Orchestrates validation for each file type. Manages streaming, resource monitoring and audit events, and delegates to validators/inspectors. The async methods offload blocking inspection to a worker thread (or a configured `executor`); the `*_sync` methods run the same pipeline in the calling thread and refuse to run on an event-loop thread. Exposes them as `filename_validator`, `signature_validator`, `mime_validator` and the other validator attributes; `magic_mime` and `magic_available` are properties that delegate to `mime_validator`. |
-| `FileSecurityConfig` | Centralizes all configuration: allowed MIME types, extensions, blocked extensions, Unicode characters, and Windows reserved names. |
+| `FileSecurityConfig` | Centralizes all configuration: allowed MIME types mapped to the extensions each permits, blocked extensions, Unicode characters, and Windows reserved names. |
 | `SecurityLimits` | Holds numeric thresholds: file sizes, compression ratios, timeouts, entry limits, resource caps. |
 | `BaseValidator` | Abstract base class; validators inherit and implement `validate()`. |
 | `UnicodeSecurityValidator` | NFC normalization and dangerous character detection (rejects with `UnicodeSecurityError`). |
 | `ExtensionSecurityValidator` | Blocked, dangerous and compound extension checks. `validate_allowed` checks an extension against the allowlist and the blocked list. |
 | `WindowsSecurityValidator` | Rejects Windows reserved device names. |
 | `FilenameSecurityValidator` | Strips path components and dangerous characters from a filename and limits its length to `max_sanitized_name_length`. |
-| `FileSignatureValidator` | Checks that the file header matches the signatures of the expected type (image, ZIP, gzip, activity or FIT). |
-| `MimeTypeValidator` | Detects the MIME type from content with libmagic (serialized by a lock, never falling back to the filename) and enforces the allowed MIME types. |
+| `FileSignatureValidator` | Checks that the file header matches the signatures of the expected type (image: JPEG, PNG or WebP; ZIP, gzip, activity or FIT). |
+| `MimeTypeValidator` | Detects the MIME type from content with libmagic (serialized by a lock, never falling back to the filename), enforces the allowed MIME types and requires the filename's extension to be one listed for the detected type. |
 | `CompressionSecurityValidator` | Checks compression ratio, uncompressed size, entry count, and nested archive limits, and that the listed entries fill the file exactly. |
 | `XmlSecurityValidator` | Parses XML with `defusedxml`, blocking DTDs and external entities (raises `XmlSecurityError`). |
 | `FitSecurityValidator` | Checks the FIT container: headers, header CRC, data size, CRC-16 per section, and that the sections cover the file exactly. |
-| `ZipContentInspector` | Iterates ZIP entries checking for traversal, executables, scripts, symlinks, and recursive structures. With `allow_nested_archives`, inspects every inner ZIP like the top level. |
+| `ImageDimensionValidator` | Reads width and height from the PNG IHDR chunk, the first JPEG frame header (SOF) or the first WebP chunk (VP8, VP8L or VP8X canvas) without decoding pixels, and rejects an image whose pixel count exceeds `max_image_pixels` (raises `ImageDimensionError`). A missing or malformed dimension header raises `FileSignatureError` with `IMAGE_INVALID_STRUCTURE`. |
+| `ZipContentInspector` | Iterates ZIP entries checking for traversal, executables, scripts, symlinks, and recursive structures, and runs the top-level Unicode, Windows reserved-name and blocked-extension checks on each entry name. With `allow_nested_archives`, inspects every inner ZIP like the top level. |
 | `GzipContentInspector` | Streams gzip decompression, checking ratio and size progressively. |
 | `ContentSecurityInspector` | Scans raw bytes for structurally verified executable headers, web shells, and polyglot patterns (image and activity uploads). |
 | `ResourceMonitor` | Context manager enforcing wall-clock time and peak-RSS memory limits at loop boundaries and on exit. |
@@ -61,7 +63,7 @@ safeuploads/
 
 ## Validation Pipelines
 
-The `validate_*_file_sync` methods run the identical steps listed below in the calling thread, without the worker-thread offload.
+The `validate_*_file_sync` methods run the identical steps listed below in the calling thread, without the worker-thread offload. Every method returns a `ValidationResult` with the sanitized filename and the detected MIME type.
 
 ### Image Validation (`validate_image_file`)
 
@@ -91,14 +93,18 @@ UploadFile
               │
               ▼
 ┌─────────────────────────────┐
-│ 4. File Size Check          │
-│    (chunked progressive)    │
+│ 4. Stream to SpooledTempFile│
+│    (size checked per chunk; │
+│    memory < 10MB → disk)    │
 └─────────────┬───────────────┘
               │
               ▼
 ┌─────────────────────────────┐
-│ 5. MIME Type Detection      │
+│ 5. MIME Type Check          │
 │    (python-magic, first 8KB)│
+│    ├── Type allowed         │
+│    └── Extension listed for │
+│        the detected type    │
 └─────────────┬───────────────┘
               │
               ▼
@@ -109,7 +115,18 @@ UploadFile
               │
               ▼
 ┌─────────────────────────────┐
-│ 7. Content Analysis         │
+│ 7. Dimension Check          │
+│    (header only, no decode) │
+│    ├── PNG IHDR             │
+│    ├── JPEG frame header    │
+│    ├── WebP VP8/VP8L/VP8X   │
+│    └── width × height ≤     │
+│        max_image_pixels     │
+└─────────────┬───────────────┘
+              │
+              ▼
+┌─────────────────────────────┐
+│ 8. Content Analysis         │
 │    (if enabled)             │
 │    ├── Executable signatures│
 │    ├── Script injection     │
@@ -118,13 +135,13 @@ UploadFile
               │
               ▼
 ┌─────────────────────────────┐
-│ 8. ResourceMonitor END      │
+│ 9. ResourceMonitor END      │
 └─────────────┬───────────────┘
               │
               ▼
-┌─────────────────────────────┐
-│ 9. Audit: VALIDATION_SUCCESS│
-└─────────────────────────────┘
+┌──────────────────────────────┐
+│ 10. Audit: VALIDATION_SUCCESS│
+└──────────────────────────────┘
 ```
 
 ### ZIP Validation (`validate_zip_file`)
@@ -162,6 +179,8 @@ UploadFile
               ▼
 ┌─────────────────────────────┐
 │ 6. MIME + Signature Check   │
+│    (extension listed for    │
+│    the detected type)       │
 └─────────────┬───────────────┘
               │
               ▼
@@ -181,7 +200,11 @@ UploadFile
 │    │   ├── Null bytes       │
 │    │   ├── Path traversal   │
 │    │   ├── Absolute paths   │
-│    │   └── Symlinks         │
+│    │   ├── Symlinks         │
+│    │   └── Top-level name   │
+│    │       checks (Unicode, │
+│    │       Windows names,   │
+│    │       blocked exts)    │
 │    ├── Dangerous entry types│
 │    ├── Binary signatures    │
 │    ├── Nested archive magic │
@@ -241,8 +264,10 @@ UploadFile (.gpx, .tcx, .fit)
 │ 5. MIME + Signature Check    │
 │    ├── FIT: binary signature │
 │    │   (.FIT at bytes 8-11)  │
-│    └── GPX/TCX: XML header   │
-│        (<?xml)               │
+│    ├── GPX/TCX: XML header   │
+│    │   (<?xml)               │
+│    └── Extension listed for  │
+│        the detected type     │
 └──────────────┬───────────────┘
                │
                ▼
@@ -306,6 +331,8 @@ UploadFile (.gz)
 ┌──────────────────────────────┐
 │ 5. MIME + Signature Check    │
 │    (gzip magic: \x1f\x8b)   │
+│    (extension listed for     │
+│    the detected type)        │
 └──────────────┬───────────────┘
                │
                ▼
@@ -333,8 +360,7 @@ UploadFile (.gz)
 
 | Stage | What is read | Buffer size |
 |---|---|---|
-| File size check | Chunked reads (`chunk_size`, 64 KB default) | Progressive, discarded after counting |
-| Stream to temp | Chunked reads to `SpooledTemporaryFile` | In-memory up to `max_memory_buffer_size` (10 MB), then disk |
+| Stream to temp (size check) | Chunked reads (`chunk_size`, 64 KB default) to `SpooledTemporaryFile`, counted against the type's size limit | In-memory up to `max_memory_buffer_size` (10 MB), then disk |
 | MIME detection | First 8 KB via `python-magic` | 8 KB |
 | Signature check | First 4-12 bytes depending on format | Minimal |
 | Compression validation | ZIP central directory, local headers and data descriptors | Metadata; entries with a data descriptor are inflated in `chunk_size` chunks |
@@ -343,6 +369,7 @@ UploadFile (.gz)
 | Gzip inspection | Chunked streaming decompression | `chunk_size` at a time |
 | XML validation | Chunked feed to `defusedxml`'s parser, no element tree built | `chunk_size` at a time |
 | FIT validation | Chunked CRC-16 over each section | `chunk_size` at a time |
+| Image dimension check | PNG and WebP: first 30 bytes. JPEG: the marker and length of each segment up to the frame header, skipping segment payloads by seek | Minimal; a run of 0xFF fill bytes is read `chunk_size` at a time |
 | Content analysis | Byte scan of image and activity uploads (not ZIP) | Bounded by `content_scan_max_size` (50 MB); about twice the sample while matching |
 
 ---
@@ -361,6 +388,7 @@ Exception
     │   ├── FileSizeError
     │   ├── MimeTypeError
     │   ├── FileSignatureError
+    │   ├── ImageDimensionError
     │   ├── CompressionSecurityError
     │   │   ├── ZipBombError
     │   │   └── ZipContentError
@@ -384,8 +412,9 @@ All `FileSecurityError` subclasses carry an `error_code` from
 | `ExtensionSecurityError` | `EXTENSION_BLOCKED` |
 | `WindowsReservedNameError` | `WINDOWS_RESERVED_NAME` |
 | `FileSizeError` | `FILE_TOO_LARGE` |
-| `MimeTypeError` | `MIME_TYPE_INVALID` (uploads whose detected MIME is not allowed are reported as `MIME_TYPE_MISMATCH`) |
-| `FileSignatureError` | `FILE_SIGNATURE_MISMATCH` |
+| `MimeTypeError` | `MIME_TYPE_INVALID` (uploads whose detected MIME is not allowed are reported as `MIME_TYPE_MISMATCH`, and an extension not listed for the detected MIME as `EXTENSION_MIME_MISMATCH`) |
+| `FileSignatureError` | `FILE_SIGNATURE_MISMATCH` (a missing or invalid FIT structure is reported as `FIT_INVALID_STRUCTURE`, and a missing or invalid image dimension header as `IMAGE_INVALID_STRUCTURE`) |
+| `ImageDimensionError` | `IMAGE_DIMENSIONS_EXCEEDED` |
 | `CompressionSecurityError` | `ZIP_INVALID_STRUCTURE` |
 | `ZipBombError` | `ZIP_BOMB_DETECTED` |
 | `ZipContentError` | `ZIP_CONTENT_THREAT` (the ZIP inspector passes the code of the first threat found) |