safeuploads 3.0.0__tar.gz → 4.0.0__tar.gz

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

@@ -4,6 +4,44 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: safeuploads
-Version: 3.0.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
@@ -66,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
@@ -81,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.
@@ -97,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
@@ -144,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
@@ -159,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-3.0.0 → safeuploads-4.0.0}/README.md

@@ -52,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
@@ -67,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.
@@ -83,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
@@ -130,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
@@ -145,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-3.0.0 → safeuploads-4.0.0}/docs/index.md

@@ -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-3.0.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,18 +40,19 @@ 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. |
+| `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). |
@@ -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)       │
 └─────────────┬───────────────┘
               │
               ▼
@@ -245,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     │
 └──────────────┬───────────────┘
                │
                ▼
@@ -310,6 +331,8 @@ UploadFile (.gz)
 ┌──────────────────────────────┐
 │ 5. MIME + Signature Check    │
 │    (gzip magic: \x1f\x8b)   │
+│    (extension listed for     │
+│    the detected type)        │
 └──────────────┬───────────────┘
                │
                ▼
@@ -337,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 |
@@ -347,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 |
 
 ---
@@ -365,6 +388,7 @@ Exception
     │   ├── FileSizeError
     │   ├── MimeTypeError
     │   ├── FileSignatureError
+    │   ├── ImageDimensionError
     │   ├── CompressionSecurityError
     │   │   ├── ZipBombError
     │   │   └── ZipContentError
@@ -388,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) |

{safeuploads-3.0.0 → safeuploads-4.0.0}/docs/security/integration-checklist.md

@@ -30,6 +30,12 @@ that addresses it.
   `FileSecurityConfig` (not relying solely on defaults).
 - [ ] `SecurityLimits` tuned for your use case:
     - `max_image_size` — appropriate for expected upload sizes.
+    - `max_image_pixels` — default 89,478,485 (Pillow's
+      `Image.MAX_IMAGE_PIXELS`); lower it to the largest image
+      your application needs. An image whose header declares
+      more pixels is rejected with `IMAGE_DIMENSIONS_EXCEEDED`,
+      and one whose dimension header is missing or malformed
+      with `IMAGE_INVALID_STRUCTURE`.
     - `max_zip_size` — set to the maximum acceptable ZIP size.
     - `max_activity_file_size` — set if accepting GPX/TCX/FIT.
       FIT uploads must be structurally valid (headers, CRCs,
@@ -47,12 +53,15 @@ that addresses it.
   raises `FileSecurityConfigurationError` otherwise), and every
   inner ZIP is inspected like the top level; one that is
   oversized, corrupt or uninspectable is rejected.
-- [ ] Allowed extensions and MIME types reviewed and narrowed
-  to only what your application accepts.
+- [ ] `ALLOWED_*_TYPES` reviewed and narrowed to the MIME types
+  your application accepts and the extensions each may carry.
 - [ ] `FileSecurityConfigurationError` from the `FileValidator`
   constructor handled at startup: it is raised for any
-  error-severity configuration issue (invalid limit types,
-  non-positive limits, empty or uppercase extension entries,
+  error-severity configuration issue (a removed
+  `ALLOWED_*_MIMES` or `ALLOWED_*_EXTENSIONS` setting, invalid
+  limit types, non-positive limits, an empty allowed-types
+  mapping, a MIME
+  type with no extensions, empty or uppercase extension entries,
   empty block lists or reserved names, reserved names that are
   not lowercase, a content scan window smaller than an image or
   activity size limit), including sets overridden on the
@@ -71,6 +80,25 @@ that addresses it.
 - [ ] Consider supplemental antivirus scanning (ClamAV or
   similar) for high-risk environments.
 
+## Image Processing
+
+safeuploads checks the dimensions an image header declares but
+does not decode pixel data, so decoder bugs and corrupt image
+bodies are not caught (see
+[Image Decompression Bombs](threat-model.md#image-decompression-bombs-cwe-400)).
+
+- [ ] Images are decoded, resized or re-encoded in an isolated
+  worker process or container with its own memory and time
+  limits, not in the process that serves requests.
+- [ ] The decoder's own pixel limit stays set at or below
+  `max_image_pixels` (with Pillow, keep `Image.MAX_IMAGE_PIXELS`;
+  never set it to `None`).
+- [ ] A re-encoded copy is stored or served instead of the
+  uploaded bytes, so metadata (EXIF, GPS), data appended to the
+  image and secondary images are dropped.
+- [ ] Image decoder libraries (Pillow, libjpeg-turbo, libpng,
+  libwebp) kept up to date.
+
 ## Audit Logging
 
 - [ ] `enable_audit_logging` set to `True` in production.
@@ -88,8 +116,9 @@ that addresses it.
 - [ ] Application catches specific exception types
   (`FileSizeError`, `ExtensionSecurityError`, etc.) and
   returns user-appropriate messages. Malformed or forbidden XML
-  (`XmlSecurityError`) and content threats
-  (`ContentThreatError`) are `FileValidationError` subclasses.
+  (`XmlSecurityError`), content threats (`ContentThreatError`)
+  and images over the pixel limit (`ImageDimensionError`) are
+  `FileValidationError` subclasses.
 - [ ] `FileProcessingError` (including `ResourceLimitError`) is
   caught as well: it is not a `FileValidationError`, and it is
   raised only for internal errors and exceeded resource limits.
@@ -108,13 +137,20 @@ that addresses it.
 - [ ] Uploaded files stored outside the web-accessible
   document root.
 - [ ] Uploaded files renamed to random identifiers (UUIDs);
-  original filenames stored in metadata only.
+  original filenames stored in metadata only. If the stored name
+  needs an extension, take it from `ValidationResult.filename`,
+  not from the uploaded name: it is sanitized, and its extension
+  is one the configuration lists for the detected MIME type.
+  `mime_type` alone cannot choose it, since GPX and TCX share
+  their XML types. Content is not checked as GPX rather than TCX,
+  so an importer must still handle XML that does not match its
+  extension.
 - [ ] Storage directory permissions restrict access to the
   application user only (`0700` or equivalent).
 - [ ] If serving uploaded files back to users, use:
     - `Content-Disposition: attachment` to force download.
-    - `Content-Type` set from validated MIME type, not from
-      the filename.
+    - `Content-Type` set from `ValidationResult.mime_type`,
+      not from the filename.
     - `X-Content-Type-Options: nosniff` header.
 
 ## Security Headers (for serving uploaded content)
@@ -137,7 +173,7 @@ that addresses it.
   only the time limit applies.
 - [ ] Both limits are checked at loop boundaries (upload
   streaming, ZIP entry loops, gzip decompression, each XML
-  chunk) and on exit; a single blocking call, such as one
+  chunk, each JPEG segment before the frame header) and on exit; a single blocking call, such as one
   `zipfile` central-directory parse or one libmagic call, is
   not interrupted mid-call. A `ResourceLimitError` keeps its
   own `RESOURCE_TIME_EXCEEDED` or `RESOURCE_MEMORY_EXCEEDED`

{safeuploads-3.0.0 → safeuploads-4.0.0}/docs/security/threat-model.md

@@ -397,8 +397,17 @@ extension.
   validated.
 - The detected MIME type is validated against the allowlist for
   the file type being validated.
+- The filename's extension must be one the configuration lists
+  for the detected MIME type (`ALLOWED_*_TYPES`), so a file that
+  is a valid, allowed image under another image format's name
+  (for example a WebP named `photo.jpg`) is rejected with
+  `EXTENSION_MIME_MISMATCH`. Downstream tools that pick a decoder
+  or a `Content-Type` from the extension never see a name that
+  contradicts the content.
 - File signatures (magic bytes) are verified independently of
-  the MIME type.
+  the MIME type. A WebP must carry `WEBP` at bytes 8-11 of its
+  RIFF container, so WAV, AVI and other RIFF files are not
+  accepted as images.
 
 ### Polyglot Files
 
@@ -517,7 +526,8 @@ significantly during validation consumes all available memory.
   same process can also trip the limit; on Windows memory
   accounting is disabled.
 - The limit is checked at loop boundaries (upload streaming, ZIP
-  entry loops, gzip decompression, each XML chunk) and on exit,
+  entry loops, gzip decompression, each XML chunk, each JPEG
+  segment before the frame header) and on exit,
   and raises `ResourceLimitError` with
   `RESOURCE_MEMORY_EXCEEDED`. A single blocking call is not
   interrupted mid-call.
@@ -576,6 +586,73 @@ size, similar to ZIP bombs.
 - Deflate data that `zlib` cannot decode is rejected with
   `CompressionSecurityError` (`ZIP_CORRUPT`).
 
+### Image Decompression Bombs (CWE-400)
+
+**Attack:** A small image whose header declares a huge canvas,
+such as a 50 KB PNG declaring 60,000 × 60,000 pixels or a WebP
+canvas of 16,777,216 × 16,777,216, passes every byte-level
+check and exhausts memory when the host decodes it, for example
+to make a thumbnail. A 24-bit decode needs 3 bytes per pixel,
+so 60,000 × 60,000 pixels is about 10 GB.
+
+**Mitigations:**
+
+- `ImageDimensionValidator` reads width and height from the
+  image header without decoding pixel data, and rejects an
+  image whose width × height exceeds `max_image_pixels` with
+  `ImageDimensionError` (`IMAGE_DIMENSIONS_EXCEEDED`). The
+  default, 89,478,485, is Pillow's `Image.MAX_IMAGE_PIXELS`,
+  about 256 MB decoded at 24 bits per pixel. Configuration
+  validation rejects a limit of 0 or less and warns above twice
+  the default, where Pillow refuses to open an image.
+- PNG: the first chunk must be IHDR with 13 bytes of data, and
+  width and height must be 1 to 2³¹ − 1.
+- JPEG: the marker segments are walked from the start of image
+  to the first frame header (SOF0 to SOF15, except DHT, JPG and
+  DAC). Each segment's payload is skipped by its length, so a
+  frame header behind large EXIF, XMP or ICC segments is still
+  found. Scan data or end of image before a frame header, a
+  truncated segment, a segment length below 2, a standalone
+  marker before the frame, and a zero width or height
+  (including a height deferred to a DNL segment) are rejected
+  with `FileSignatureError` (`IMAGE_INVALID_STRUCTURE`).
+- WebP: the first chunk after the `WEBP` form type must be
+  `VP8 ` (a key frame with a valid start code; the two
+  upscaling bits of each dimension are ignored), `VP8L`
+  (signature 0x2F, version 0) or `VP8X`, whose canvas size is
+  checked. Any other first chunk is rejected with
+  `IMAGE_INVALID_STRUCTURE`.
+- The check runs after the signature check and before content
+  analysis, on the upload streamed to a spooled temp file. The
+  JPEG walk checks the active `ResourceMonitor` on every
+  segment; its cost grows with the number of segments before
+  the frame header, so a 20 MB JPEG made only of 4-byte
+  segments takes seconds, bounded by `max_image_size` and
+  `max_validation_time_seconds`. A run of 0xFF fill bytes is
+  skipped `chunk_size` bytes at a time.
+
+**Decoding trust boundary:**
+
+- safeuploads does **not** decode images. Only the dimension
+  header is parsed: compressed pixel data, ancillary chunks and
+  metadata are not validated, so a truncated or corrupt image
+  body is accepted.
+- Bugs in image decoders (for example CVE-2023-4863 in libwebp)
+  are triggered by decoding. The library cannot detect them, and
+  decoding inside the validator would expose the validating
+  process to them.
+- Only the first image is checked. The APNG and WebP
+  specifications require animation frames to fit the declared
+  canvas, but the number of frames is not limited, and data
+  after a JPEG's end of image (such as the secondary images of
+  an MPO file) is not parsed.
+- A host that decodes uploads should decode in an isolated
+  worker process with a memory limit, keep the decoder's own
+  pixel limit set (for example Pillow's `Image.MAX_IMAGE_PIXELS`)
+  and store a re-encoded copy instead of the original bytes;
+  re-encoding also drops metadata and data appended to the
+  image. See the integration checklist.
+
 ---
 
 ## Audit & Observability

{safeuploads-3.0.0 → safeuploads-4.0.0}/examples/README.md

@@ -130,9 +130,9 @@ validator = FileValidator(config=config)
 ```json
 {
   "error": "invalid_mime_type",
-  "message": "Invalid file type. Detected: application/x-dosexec. Allowed: image/jpeg, image/jpg, image/png",
+  "message": "Invalid file type. Detected: application/x-dosexec. Allowed: image/jpeg, image/png, image/webp",
   "detected_mime": "application/x-dosexec",
-  "allowed_mimes": ["image/jpeg", "image/jpg", "image/png"],
+  "allowed_mimes": ["image/jpeg", "image/png", "image/webp"],
   "error_code": "MIME_TYPE_MISMATCH"
 }
 ```