safeuploads 1.0.1__tar.gz → 1.1.0__tar.gz

safeuploads-1.1.0/.forgejo/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: 🐞 Bug report
+about: Report a bug
+title: "[BUG]: "
+labels: [bug]
+assignees: ''
+---
+
+## Checklist
+
+- [ ] I have searched **existing issues** to make sure this bug hasn't already been reported.
+- [ ] I have checked the **documentation** at [https://safeuploads.endurain.com](https://safeuploads.endurain.com) and didn't find a solution.
+
+## Description
+
+Describe the bug you encountered.
+
+## Steps to Reproduce
+
+1. Version
+2. Go to '...'
+3. Click on '...'
+4. See error
+
+## Expected Behavior
+
+What did you expect to happen?
+
+## Screenshots, logs or files
+
+If applicable, add screenshots, logs or files to help explain your problem. If you do not wish to upload sensitive information to the issue you can send that info to [joao@endurain.com](joao@endurain.com).
+
+## Additional Context
+
+Add any other context about the problem here.

safeuploads-1.1.0/.forgejo/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📚 Documentation
+    url: https://safeuploads.endurain.com
+    about: Please check our documentation before creating an issue.

safeuploads-1.1.0/.forgejo/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: 💡 Feature request
+about: Suggest an idea or enhancement for this project
+title: "[FEATURE]: "
+labels: [enhancement]
+assignees: ''
+---
+
+## Summary
+
+Briefly describe the feature you'd like to see.
+
+## Motivation
+
+Why is this feature important? What problem does it solve?
+
+## Proposed Solution
+
+How would this feature work? Describe any ideas you have.
+
+## Alternatives
+
+Have you considered any alternatives?
+
+## Additional Context
+
+Add screenshots, mockups, or examples if relevant.

safeuploads-1.1.0/.forgejo/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## What does this PR do?
+ 
+A clear description of the change.
+ 
+## Related issue
+ 
+Required for anything beyond a small bug fix or typo.
+Don't forget to reference the issue so it auto-closes works, for example use `Closes #XYZ`
+ 
+## Type of change
+ 
+Check all that apply
+ 
+- [ ] Bug fix
+- [ ] New feature (exception during freeze; link prior discussion/acknowledgment)
+- [ ] Documentation
+- [ ] Refactor / code quality
+- [ ] Translation
+- [ ] Other (describe below)
+
+## Checklist
+ 
+- [ ] This PR is focused on a single concern
+- [ ] An issue was opened and acknowledged before writing this code (if not a small fix)
+- [ ] If this PR introduces a new feature during freeze, it was discussed and explicitly acknowledged first
+- [ ] The PR is under ~300 lines changed, excluding lock files, migrations, and generated code
+- [ ] Tests have been added or updated where applicable
+- [ ] Documentation has been updated where applicable
+- [ ] Commit messages follow Conventional Commits format
+
+## Notes for the reviewer
+ 
+Anything that would help review this. Tricky areas, alternative approaches considered, screenshots, etc.

{safeuploads-1.0.1 → safeuploads-1.1.0}/.forgejo/scripts/check_conventional_commits.py

@@ -57,7 +57,7 @@ _HEADER_RE = re.compile(
     (?P<type>[A-Za-z]+)
     (?:\((?P<scope>[^)]+)\))?
     (?P<breaking>!)?
-    :\ 
+    :\x20
     (?P<description>.+?)
     \s*$
     """,
@@ -102,6 +102,7 @@ def _safe_log_value(value: str) -> str:
 
 
 def _iter_messages(args: argparse.Namespace) -> Iterable[str]:
+    """Yield messages from stdin or CLI arguments."""
     if args.stdin:
         for line in sys.stdin:
             stripped = line.rstrip("\n")
@@ -112,6 +113,7 @@ def _iter_messages(args: argparse.Namespace) -> Iterable[str]:
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Validate all messages and return a process exit code."""
     parser = argparse.ArgumentParser(
         description="Validate Conventional Commits headers.",
     )
@@ -150,8 +152,8 @@ def main(argv: list[str] | None = None) -> int:
 
     if failures:
         print(
-            f"\n{failures} of {checked} message(s) failed Conventional Commits "
-            "validation.",
+            f"\n{failures} of {checked} message(s) failed "
+            "Conventional Commits validation.",
             file=sys.stderr,
         )
         return 1

{safeuploads-1.0.1 → safeuploads-1.1.0}/.forgejo/workflows/conventional-commits.yml

@@ -4,21 +4,17 @@ on:
   pull_request:
     types: [opened, edited, synchronize, reopened]
 
-permissions:
-  contents: read
-  pull-requests: read
-
 concurrency:
   group: ${{ forgejo.workflow }}-${{ forgejo.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
   validate:
-    runs-on: codeberg-small
+    runs-on: local-runner
 
     steps:
       - name: Checkout code
-        uses: https://data.forgejo.org/actions/checkout@v6
+        uses: https://data.forgejo.org/actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
@@ -40,5 +36,5 @@ jobs:
         run: |
           set -euo pipefail
           git fetch --no-tags origin "$BASE_SHA" "$HEAD_SHA"
-          git log --format=%s "$BASE_SHA".."$HEAD_SHA" \
+          git log --no-merges --format=%s "$BASE_SHA".."$HEAD_SHA" \
             | python3 .forgejo/scripts/check_conventional_commits.py --stdin

safeuploads-1.1.0/.forgejo/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Deploy documentation
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: Build docs but do not deploy
+        required: false
+        default: false
+        type: boolean
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'safeuploads/**/*.py'
+      - '.forgejo/workflows/docs.yml'
+
+concurrency:
+  group: ${{ forgejo.workflow }}-${{ forgejo.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  deploy:
+
+    runs-on: local-runner
+
+    steps:
+      - name: Checkout code
+        uses: https://data.forgejo.org/actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: https://data.forgejo.org/astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          working-directory: .
+
+      - name: Sync documentation dependencies
+        working-directory: .
+        run: uv sync --frozen --only-group docs
+      - name: Build documentation
+        run: uv run --no-sync --project safeuploads mkdocs build --site-dir site
+
+      - name: Set dry-run mode
+        if: ${{ inputs.dry-run == true }}
+        run: echo "DOCS_DRY_RUN=true" >> "$FORGEJO_ENV"
+
+      - name: Deploy documentation to Codeberg Pages
+        if: env.DOCS_DRY_RUN != 'true'
+        uses: https://data.forgejo.org/actions/git-pages@5978530ffb9bbe196ad9fdc0c48fdaf1483de4cf # v2.1.0
+        with:
+          site: https://safeuploads.endurain.com/
+          server: codeberg.page
+          token: ${{ forge.token }}
+          source: site/

{safeuploads-1.0.1 → safeuploads-1.1.0}/.forgejo/workflows/fuzz.yml

@@ -15,22 +15,19 @@ concurrency:
 jobs:
   fuzz:
     name: Fuzz
-    runs-on: codeberg-medium-lazy
+    runs-on: local-runner
 
     steps:
       - name: Checkout repository
-        uses: https://data.forgejo.org/actions/checkout@v4
+        uses: https://data.forgejo.org/actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y libmagic1
-
-      - name: Set up Python 3.13
-        uses: https://data.forgejo.org/actions/setup-python@v5
-        with:
-          python-version: "3.13"
+        run: apt-get update && apt-get install -y libmagic1
 
       - name: Install uv
-        run: pip install uv
+        uses: https://data.forgejo.org/astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          working-directory: .
 
       - name: Install dependencies
         run: uv sync --frozen --dev

{safeuploads-1.0.1 → safeuploads-1.1.0}/.forgejo/workflows/lint-and-test.yml

@@ -23,16 +23,15 @@ jobs:
     runs-on: codeberg-tiny
 
     steps:
-      - name: Checkout repository
-        uses: https://data.forgejo.org/actions/checkout@v4
-
-      - name: Set up Python 3.13
-        uses: https://data.forgejo.org/actions/setup-python@v5
+      - name: Checkout code
+        uses: https://data.forgejo.org/actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          python-version: "3.13"
+          fetch-depth: 1
 
       - name: Install uv
-        run: pip install uv
+        uses: https://data.forgejo.org/astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          working-directory: .
 
       - name: Install dependencies
         run: uv sync --frozen --dev
@@ -43,6 +42,9 @@ jobs:
       - name: Check formatting with ruff
         run: uv run ruff format --check safeuploads tests examples
 
+      - name: Type check with mypy
+        run: uv run mypy
+
   # ----------------------------------------------------------------
   # Test
   # Runs the full pytest suite with coverage. Only runs after lint
@@ -50,26 +52,23 @@ jobs:
   # ----------------------------------------------------------------
   test:
     name: Test
-    runs-on: codeberg-medium
+    runs-on: local-runner
     needs: lint
 
     steps:
       - name: Checkout repository
-        uses: https://data.forgejo.org/actions/checkout@v4
+        uses: https://data.forgejo.org/actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y libmagic1
-
-      - name: Set up Python 3.13
-        uses: https://data.forgejo.org/actions/setup-python@v5
-        with:
-          python-version: "3.13"
+        run: apt-get update && apt-get install -y libmagic1
 
       - name: Install uv
-        run: pip install uv
+        uses: https://data.forgejo.org/astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          working-directory: .
 
       - name: Install dependencies
-        run: uv sync --frozen --dev
+        run: uv sync --frozen --dev --extra fastapi
 
       - name: Audit Python dependencies
         run: uvx pip-audit --require-hashes --disable-pip -r <(uv export --frozen --no-header --no-emit-project --no-dev)

{safeuploads-1.0.1 → safeuploads-1.1.0}/.forgejo/workflows/publish.yml

@@ -16,11 +16,11 @@ concurrency:
 jobs:
   publish:
     name: Build & Publish
-    runs-on: codeberg-medium
+    runs-on: local-runner
 
     steps:
       - name: Checkout repository
-        uses: https://data.forgejo.org/actions/checkout@v4
+        uses: https://data.forgejo.org/actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Verify version matches input
         run: |
@@ -38,15 +38,12 @@ jobs:
           echo "Publishing version $PKG_VERSION"
 
       - name: Install system dependencies
-        run: sudo apt-get update && sudo apt-get install -y libmagic1
-
-      - name: Set up Python 3.13
-        uses: https://data.forgejo.org/actions/setup-python@v5
-        with:
-          python-version: "3.13"
+        run: apt-get update && apt-get install -y libmagic1
 
       - name: Install uv
-        run: pip install uv
+        uses: https://data.forgejo.org/astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          working-directory: .
 
       - name: Install dependencies
         run: uv sync --frozen --dev

{safeuploads-1.0.1 → safeuploads-1.1.0}/.forgejo/workflows/renovate.yml

@@ -5,11 +5,6 @@ on:
   schedule:
     - cron: '0 4 * * 0'
 
-permissions:
-  contents: write
-  pull-requests: write
-  issues: write
-
 concurrency:
   group: ${{ forgejo.workflow }}-${{ forgejo.ref }}
   cancel-in-progress: false
@@ -18,16 +13,16 @@ jobs:
 
   renovate:
 
-    runs-on: codeberg-small
+    runs-on: local-runner
 
     steps:
       - name: Checkout code
-        uses: https://data.forgejo.org/actions/checkout@v4
+        uses: https://data.forgejo.org/actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 1
 
       - name: Run Renovate
-        uses: docker://ghcr.io/renovatebot/renovate:latest
+        uses: docker://ghcr.io/renovatebot/renovate@sha256:38aac6e29e09288bc3fb3b95ba9445962508a1081013144d5b6ec5a6735707b9 # 43.168.5
         env:
           LOG_LEVEL: info
           RENOVATE_CONFIG_FILE: renovate.json

safeuploads-1.1.0/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+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).
+
+## [1.1.0] - 2026-07-20
+
+### Added
+
+- `verify_zip_decompression` option that decompresses every ZIP entry
+  to reject archives with forged central-directory metadata.
+- Custom `executor` parameter on `FileValidator` to offload blocking
+  inspection to a bounded thread pool instead of the default
+  `asyncio` pool.
+- Instance-level configuration validation and isolation so a
+  per-instance `limits` object never mutates the shared class
+  defaults.
+- New `SecurityLimits` size limits plus additional recursable-archive
+  types and script patterns for deeper threat detection.
+- `BaseInspector` base class sharing configuration and audit state
+  across inspectors.
+- PEP 561 `py.typed` marker so downstream projects consume the shipped
+  type hints.
+- Integration tests exercising a real Starlette `UploadFile` and an
+  end-to-end FastAPI multipart request.
+
+### Changed
+
+- `ErrorCode` is now a `StrEnum`. This is backward compatible: members
+  still compare and hash equal to their string values, so existing
+  comparisons and JSON serialization are unaffected.
+- Validation flow refactored around a single generic runner for
+  consistent audit logging and error mapping.
+- Thread safety hardened: access to the shared `python-magic` instance
+  is locked, and blocking inspection is offloaded off the event loop.
+- File-size validation now rejects uploads whose declared size already
+  exceeds the limit and verifies the real byte count by streaming.
+- **Potentially breaking:** the public allow-list constants
+  (`ALLOWED_IMAGE_MIMES`, `ALLOWED_ZIP_MIMES`,
+  `ALLOWED_IMAGE_EXTENSIONS`, `ALLOWED_ZIP_EXTENSIONS`) are now
+  immutable `frozenset`s. Read-only use is unaffected; in-place
+  mutation (e.g. `.add(...)`) is no longer supported — assign a new
+  set instead.
+
+### Fixed
+
+- Corrected the filename-sanitization debug log so it reports the true
+  original filename rather than the already-sanitized value.
+- Documentation URLs updated to the new site.
+
+## [1.0.1] - 2026-06-03
+
+### Fixed
+
+- `_stream_to_temp_file` now seeks the original `UploadFile` back to
+  position 0 (#3).
+
+### Changed
+
+- Dependency version bumps.
+
+## [1.0.0] - 2026-03-26
+
+First stable, production-ready release. Every layer of the validation
+pipeline was expanded, hardened, and documented since v0.1.2.
+
+### Added
+
+- **Activity & gzip validation:** `validate_activity_file` (GPX/TCX/FIT)
+  and `validate_gzip_file` with decompression-bomb detection, plus
+  `XmlSecurityValidator` using `defusedxml` to block XXE, DTD, and
+  entity-expansion attacks in XML-based activity files.
+- **Audit logging:** `SecurityAuditLogger`, `AuditEvent`, and
+  `AuditEventType` with per-request correlation IDs, toggled by
+  `enable_audit_logging`.
+- **Content security inspector:** `ContentSecurityInspector` for
+  malware-signature scanning, script/webshell marker detection, and
+  polyglot detection, controlled by `enable_content_analysis` and
+  `content_scan_max_size`.
+- **Nested ZIP complexity checks:** recursive inspection with
+  cumulative entry, depth, hash, and timing checks, archive-quine and
+  ZIP-of-ZIPs detection, and a new `max_total_entries_recursive` limit.
+
+### Changed
+
+- **Security hardening:** streaming file-size enforcement via
+  `chunk_size`, tightened ZIP inspection (null-byte filename detection,
+  monotonic timers, 512-byte content scans, sanitized error messages),
+  and a hardened MIME cache (256 → 64 entries, extension-only
+  derivation).
+- `defusedxml` added as a runtime dependency.
+- FastAPI example now binds to `127.0.0.1` instead of `0.0.0.0`.
+- **Performance:** pre-computed `frozenset` collections, cached lookup
+  sets at initialization, and LRU-cached MIME guessing.
+
+### Other
+
+- Hypothesis fuzz tests and integration suites; GitHub Actions for
+  lint/test, fuzzing, docs, and PyPI publish; Dependabot and
+  `CODEOWNERS`; new security docs (threat model, architecture,
+  integration checklist).
+
+## [0.1.2] - 2025-10-31
+
+### Fixed
+
+- Added `BinaryFileCategory` to the exported enums in
+  `safeuploads/__init__.py` so it is available for external use.
+
+## [0.1.1] - 2025-10-31
+
+### Added
+
+- `max_number_files_same_type` in `SecurityLimits`; `ZipContentInspector`
+  now uses this configurable limit instead of a hardcoded value when
+  checking for excessive files of the same type in a ZIP archive.
+- `BinaryFileCategory` enum categorizing binary file extensions
+  (starting with fitness files such as `.fit`); `ZipContentInspector`
+  skips script-content checks for these binary files.
+
+## [0.1.0] - 2025-10-30
+
+Initial release.
+
+### Added
+
+- **Filename security:** Unicode normalization, directory-traversal
+  protection, Windows reserved-name blocking.
+- **Extension validation:** configurable allow/block lists with
+  dangerous-extension detection.
+- **ZIP bomb protection:** compression-ratio limits, nested-archive
+  inspection, size constraints.
+- **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.
+
+[1.1.0]: https://codeberg.org/endurain-project/safeuploads/compare/v1.0.1...v1.1.0
+[1.0.1]: https://codeberg.org/endurain-project/safeuploads/releases/tag/v1.0.1
+[1.0.0]: https://codeberg.org/endurain-project/safeuploads/releases/tag/v1.0.0
+[0.1.2]: https://codeberg.org/endurain-project/safeuploads/releases/tag/v0.1.2
+[0.1.1]: https://codeberg.org/endurain-project/safeuploads/releases/tag/v0.1.1
+[0.1.0]: https://codeberg.org/endurain-project/safeuploads/releases/tag/v0.1.0

{safeuploads-1.0.1 → safeuploads-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: safeuploads
-Version: 1.0.1
+Version: 1.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
@@ -19,7 +19,7 @@ Description-Content-Type: text/markdown
 [![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/)
-[![Docs](https://img.shields.io/badge/docs-endurain--project.codeberg.page-blue)](https://endurain-project.codeberg.page/safeuploads/)
+[![Docs](https://img.shields.io/badge/docs-endurain--project.codeberg.page-blue)](https://safeuploads.endurain.com/)
 [![Stars](https://img.shields.io/badge/dynamic/json?url=https://codeberg.org/api/v1/repos/endurain-project/safeuploads&query=$.stars_count&label=stars&logo=codeberg)](https://codeberg.org/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.
@@ -84,7 +84,19 @@ config = FileSecurityConfig()
 config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
 config.limits.max_compression_ratio = 50
 
+# Opt in to strict ZIP checking: decompress every entry to
+# reject archives with forged central-directory metadata
+config.limits.verify_zip_decompression = True
+
 validator = FileValidator(config=config)
+
+# Optionally offload blocking inspection to a bounded pool
+from concurrent.futures import ThreadPoolExecutor
+
+pooled_validator = FileValidator(
+    config=config,
+    executor=ThreadPoolExecutor(max_workers=4),
+)
 ```
 
 ## Exception Handling
@@ -113,7 +125,7 @@ except FileValidationError as err:
 
 - **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, recursive structure and quine detection, size and ratio limits
+- **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
 - **Streaming Validation**: Memory-efficient processing via `SpooledTemporaryFile` for large files
@@ -134,11 +146,11 @@ except FileValidationError as err:
 
 ## Documentation
 
-Full documentation is available at the [safeuploads docs site](https://endurain-project.codeberg.page/safeuploads/).
+Full documentation is available at the [safeuploads docs site](https://safeuploads.endurain.com/).
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.
 
 ## Contributing
 

{safeuploads-1.0.1 → safeuploads-1.1.0}/README.md

@@ -5,7 +5,7 @@
 [![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/)
-[![Docs](https://img.shields.io/badge/docs-endurain--project.codeberg.page-blue)](https://endurain-project.codeberg.page/safeuploads/)
+[![Docs](https://img.shields.io/badge/docs-endurain--project.codeberg.page-blue)](https://safeuploads.endurain.com/)
 [![Stars](https://img.shields.io/badge/dynamic/json?url=https://codeberg.org/api/v1/repos/endurain-project/safeuploads&query=$.stars_count&label=stars&logo=codeberg)](https://codeberg.org/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.
@@ -70,7 +70,19 @@ config = FileSecurityConfig()
 config.limits.max_image_size = 10 * 1024 * 1024  # 10 MiB
 config.limits.max_compression_ratio = 50
 
+# Opt in to strict ZIP checking: decompress every entry to
+# reject archives with forged central-directory metadata
+config.limits.verify_zip_decompression = True
+
 validator = FileValidator(config=config)
+
+# Optionally offload blocking inspection to a bounded pool
+from concurrent.futures import ThreadPoolExecutor
+
+pooled_validator = FileValidator(
+    config=config,
+    executor=ThreadPoolExecutor(max_workers=4),
+)
 ```
 
 ## Exception Handling
@@ -99,7 +111,7 @@ except FileValidationError as err:
 
 - **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, recursive structure and quine detection, size and ratio limits
+- **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
 - **Streaming Validation**: Memory-efficient processing via `SpooledTemporaryFile` for large files
@@ -120,11 +132,11 @@ except FileValidationError as err:
 
 ## Documentation
 
-Full documentation is available at the [safeuploads docs site](https://endurain-project.codeberg.page/safeuploads/).
+Full documentation is available at the [safeuploads docs site](https://safeuploads.endurain.com/).
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.
 
 ## Contributing