safeuploads 2.0.0__tar.gz → 2.1.0__tar.gz

{safeuploads-2.0.0 → safeuploads-2.1.0}/.agents/skills/safeuploads-library/SKILL.md

@@ -16,7 +16,7 @@ Where this skill and any of them disagree, they win.
 - Never loosen a default (limit, allow-list, block-list, ratio, depth) to make a test or one caller pass; ask first.
 - Keep the filename check order: Unicode sanitization, then Windows reserved names, then the remaining normalization.
 - Raise a `safeuploads.exceptions` subclass with its `ErrorCode`; the message is safe to show a caller and never contains file contents or filesystem paths.
-- Blocking work (archive inspection, hashing, magic) stays off the event loop; use the existing worker-thread offload and `executor` option.
+- Blocking work (archive inspection, hashing, magic) stays off the event loop: async methods use the existing worker-thread offload and `executor` option; `*_sync` methods run it in the calling thread and keep the event-loop guard.
 - A released `ErrorCode` never changes meaning; a new failure mode gets a new code.
 - A new public name goes in `safeuploads/__init__.py` (`__all__`), `docs/api.md`, the README example if it changes usage, and `CHANGELOG.md`.
 - A rename, removal, signature change, default change that accepts or rejects different input, or `ErrorCode` change is breaking: mark it `!` and say so in the changelog.

{safeuploads-2.0.0 → safeuploads-2.1.0}/AGENTS.md

@@ -92,7 +92,7 @@ uv run pytest
 - Configuration changes go through `FileSecurityConfig` and `SecurityLimits`, and a new field updates their cross-field validation.
 - Failures raise the exceptions in `safeuploads/exceptions.py` (with a stable `ErrorCode`), never a bare `ValueError` or `Exception`.
 - The order of filename checks is significant: Unicode sanitization first, Windows reserved names before other normalization.
-- Blocking inspection never runs on the event loop; it goes through `FileValidator`'s worker-thread offload.
+- Blocking inspection never runs on the event loop: the async `validate_*_file` methods offload it to a worker thread, and the `*_sync` methods run it in the calling thread and refuse to run on an event-loop thread.
 - XML is parsed only through `defusedxml` (XXE-safe); archives are inspected without extracting to disk and under size, ratio, depth and entry limits.
 - Never build a filesystem path from an uploaded filename.
 - Logging uses `logging.getLogger(__name__)` and the `SecurityAuditLogger`; never log file contents.

{safeuploads-2.0.0 → safeuploads-2.1.0}/CHANGELOG.md

@@ -4,6 +4,21 @@ 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).
 
+## [2.1.0] - 2026-11-05
+
+### Added
+
+- `FileValidator.validate_image_file_sync`, `validate_zip_file_sync`, `validate_activity_file_sync` and `validate_gzip_file_sync`: synchronous counterparts of the async `validate_*_file` methods, each taking `(file: SeekableFile, filename: str)` and returning the sanitized filename as `str`. They run the same checks, order, exceptions, error codes and audit events and block the calling thread without the worker-thread offload (the `executor` option applies only to the async methods); called on a thread with a running asyncio event loop they raise `RuntimeError` before reading the file.
+
+### Changed
+
+- Shortened the uv `exclude-newer` cooldown from 30 to 7 days.
+- Updated all dependency groups to their latest versions.
+
+### Security
+
+- `validate_image_file` reads the 8 KB header and the content-analysis sample until the requested size or end of file. An upload object whose `read(n)` returned fewer than `n` bytes before its end left the rest of the sample unscanned, so a polyglot signature past the first short read was accepted.
+
 ## [2.0.0] - 2026-11-01
 
 ### Added
@@ -192,6 +207,7 @@ 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.
 
+[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
 [1.1.2]: https://github.com/endurain-project/safeuploads/compare/v1.1.1...v1.1.2

{safeuploads-2.0.0 → safeuploads-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: safeuploads
-Version: 2.0.0
+Version: 2.1.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
@@ -26,7 +26,7 @@ Secure file upload validation for Python 3.13+ applications. Catches dangerous f
 
 ## Features
 
-- **Framework-agnostic** async validation (FastAPI, generic)
+- **Framework-agnostic** async and sync validation (FastAPI, generic)
 - Filename sanitization and Unicode security checks
 - Extension validation with configurable allow/block lists
 - ZIP bomb detection, nested archive inspection, and recursive structure protection
@@ -71,6 +71,19 @@ async def upload_image(file: UploadFile):
     return {"status": "success", "filename": file.filename}
 ```
 
+For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the sanitized filename:
+
+```python
+from safeuploads import FileValidator
+
+validator = FileValidator()
+
+with open("activity.gpx", "rb") as fh:
+    safe_name = 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.
+
 ## Configuration
 
 ```python

{safeuploads-2.0.0 → safeuploads-2.1.0}/README.md

@@ -12,7 +12,7 @@ Secure file upload validation for Python 3.13+ applications. Catches dangerous f
 
 ## Features
 
-- **Framework-agnostic** async validation (FastAPI, generic)
+- **Framework-agnostic** async and sync validation (FastAPI, generic)
 - Filename sanitization and Unicode security checks
 - Extension validation with configurable allow/block lists
 - ZIP bomb detection, nested archive inspection, and recursive structure protection
@@ -57,6 +57,19 @@ async def upload_image(file: UploadFile):
     return {"status": "success", "filename": file.filename}
 ```
 
+For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the sanitized filename:
+
+```python
+from safeuploads import FileValidator
+
+validator = FileValidator()
+
+with open("activity.gpx", "rb") as fh:
+    safe_name = 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.
+
 ## Configuration
 
 ```python

{safeuploads-2.0.0 → safeuploads-2.1.0}/docs/index.md

@@ -16,7 +16,7 @@ Secure file upload validation for Python 3.13+ applications. Catches dangerous f
 
 ## Features
 
-- **Framework-agnostic** async validation (FastAPI, generic)
+- **Framework-agnostic** async and sync validation (FastAPI, generic)
 - Filename sanitization and Unicode security checks
 - Extension validation with configurable allow/block lists
 - ZIP bomb detection, nested archive inspection, and recursive structure protection
@@ -61,6 +61,19 @@ async def upload_image(file: UploadFile):
     return {"status": "success", "filename": file.filename}
 ```
 
+For synchronous code or worker threads, use the `*_sync` methods. They block the calling thread and return the sanitized filename:
+
+```python
+from safeuploads import FileValidator
+
+validator = FileValidator()
+
+with open("activity.gpx", "rb") as fh:
+    safe_name = 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.
+
 ## Configuration
 
 ```python

{safeuploads-2.0.0 → safeuploads-2.1.0}/docs/security/architecture.md

@@ -38,7 +38,7 @@ safeuploads/
 
 | Component | Responsibility |
 |---|---|
-| `FileValidator` | Orchestrates validation for each file type. Manages streaming, resource monitoring, audit events, offloads blocking inspection to a worker thread (or a configured `executor`), and delegates to validators/inspectors. 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`. |
+| `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. |
 | `SecurityLimits` | Holds numeric thresholds: file sizes, compression ratios, timeouts, entry limits, resource caps. |
 | `BaseValidator` | Abstract base class; validators inherit and implement `validate()`. |
@@ -61,6 +61,8 @@ safeuploads/
 
 ## Validation Pipelines
 
+The `validate_*_file_sync` methods run the identical steps listed below in the calling thread, without the worker-thread offload.
+
 ### Image Validation (`validate_image_file`)
 
 ```
@@ -400,7 +402,7 @@ and content threats, are `FileValidationError` subclasses.
 ## Audit Event Flow
 
 ```
-FileValidator.validate_*()  (_run_validation)
+FileValidator.validate_*()  (_validation_run)
   │
   ├── bind_correlation_id()    # reuses the host's ID, if set
   ├── audit.start()            # VALIDATION_START

{safeuploads-2.0.0 → safeuploads-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "safeuploads"
-version = "2.0.0"
+version = "2.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"}
@@ -42,7 +42,7 @@ build-backend = "hatchling.build"
 
 [tool.uv]
 required-version = "0.13.5"
-exclude-newer = "30 days"
+exclude-newer = "7 days"
 
 [tool.ruff]
 line-length = 79