safeuploads 1.1.1__tar.gz → 1.1.3__tar.gz

{safeuploads-1.1.1 → safeuploads-1.1.3}/.github/workflows/audit-safeuploads.yml

@@ -39,7 +39,7 @@ jobs:
           fetch-depth: 1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.

{safeuploads-1.1.1 → safeuploads-1.1.3}/.github/workflows/conventional-commits.yml

@@ -22,8 +22,13 @@ jobs:
           fetch-depth: 0
 
       - name: Validate PR title
-        # The PR title is passed through an environment variable to prevent
-        # shell injection via crafted titles (see security-and-owasp guidelines).
+        # The title only changes on opened/edited/reopened. Skipping it on
+        # `synchronize` keeps a push to a branch shared with another open PR
+        # (for example a WIP umbrella PR) from failing on that PR's title
+        # before the commit-range check below can run.
+        if: github.event.action != 'synchronize'
+        # The PR title is untrusted data: passed through an environment variable
+        # (never interpolated into the shell) to the trusted base-ref checker.
         env:
           PR_TITLE: ${{ github.event.pull_request.title }}
         run: |

{safeuploads-1.1.1 → safeuploads-1.1.3}/.github/workflows/docs.yml

@@ -40,7 +40,7 @@ jobs:
           fetch-depth: 1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.
@@ -78,4 +78,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

{safeuploads-1.1.1 → safeuploads-1.1.3}/.github/workflows/fuzz.yml

@@ -28,7 +28,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libmagic1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           version-file: pyproject.toml
 

{safeuploads-1.1.1 → safeuploads-1.1.3}/.github/workflows/lint-and-test.yml

@@ -32,7 +32,7 @@ jobs:
           fetch-depth: 1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.
@@ -50,6 +50,34 @@ jobs:
       - name: Type check with mypy
         run: uv run mypy
 
+  # ----------------------------------------------------------------
+  # Type check with ty (advisory)
+  # ty is pre-1.0 and runs beside mypy for evaluation: findings are
+  # reported but never block a merge. mypy is the gate.
+  # ----------------------------------------------------------------
+  typecheck-ty:
+    name: Type check (ty, advisory)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        with:
+          version-file: pyproject.toml
+
+      - name: Install dependencies
+        # Same environment as the mypy step: ty resolves third-party types from it.
+        run: uv sync --frozen --dev --extra fastapi
+
+      - name: Type check (ty)
+        run: uv run --no-sync ty check --python .venv
+
   # ----------------------------------------------------------------
   # Test
   # Runs the full pytest suite with coverage. Only runs after lint
@@ -68,7 +96,7 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libmagic1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           version-file: pyproject.toml
 
@@ -82,7 +110,7 @@ jobs:
         run: uv run pytest --cov-fail-under=90
 
       - name: Upload coverage report
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         if: always()
         with:
           name: safeuploads-coverage

{safeuploads-1.1.1 → safeuploads-1.1.3}/.github/workflows/publish-safeuploads.yml

@@ -36,7 +36,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
           # and local development are held to the same floor and ceiling.
@@ -122,7 +122,7 @@ jobs:
       # attests everything it downloads, so a stray checksum or SBOM file there
       # would end up in the attestation.
       - name: Upload build artifacts
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: safeuploads-dist
           path: dist/
@@ -130,7 +130,7 @@ jobs:
           retention-days: 90
 
       - name: Upload release metadata
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: safeuploads-release-metadata
           path: release-metadata/
@@ -149,22 +149,22 @@ jobs:
       id-token: write
     steps:
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
         with:
           # This job never checks the repository out, so there is no
           # pyproject.toml to read `required-version` from; keep this in step
           # with the floor declared there.
-          version: "0.12.5"
+          version: "0.13.5"
           enable-cache: false
 
       - name: Download build artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: safeuploads-dist
           path: dist/
 
       - name: Generate PEP 740 attestations
-        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
+        uses: astral-sh/attest-action@39b6ce43875c196a579e31635b11aa2a2036384a # v0.0.7
 
       - name: Publish to PyPI
         run: uv publish --trusted-publishing always dist/*.whl dist/*.tar.gz

safeuploads-1.1.3/.github/workflows/test-matrix-safeuploads.yml

@@ -0,0 +1,104 @@
+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
+#     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
+#     installed (no optional extras, no dev group), proving
+#     python-magic and defusedxml are truly sufficient on their own
+#     and the `fastapi` extra stays optional.
+
+on:
+  push:
+    branches:
+      - main
+    paths: &paths
+      - safeuploads/**
+      - tests/**
+      - pyproject.toml
+      - uv.lock
+      - .github/workflows/test-matrix-safeuploads.yml
+      - .github/scripts/smoke_import.py
+  pull_request:
+    branches:
+      - main
+    paths: *paths
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # 1. Every supported Python version, with the full dependency set.
+  test-python-matrix:
+    name: safeuploads (py${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.13", "3.14", "3.15"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libmagic1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        with:
+          # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
+          # and local development are held to the same floor and ceiling.
+          version-file: pyproject.toml
+
+      - name: Sync dependencies
+        run: uv sync --frozen --dev --extra fastapi --python ${{ matrix.python }}
+
+      - name: Run tests
+        run: uv run --no-sync --python ${{ matrix.python }} pytest
+
+  # 2. Bare import with only the base dependencies (no extras, no dev group):
+  #    proves `import safeuploads` works with zero extras installed.
+  import-base-deps:
+    name: safeuploads (bare import, no extras)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libmagic1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@18d369b23da25a81e9458561248e1aafff6a70fa # v10.3.1
+        with:
+          # Resolve uv from `[tool.uv] required-version` in pyproject.toml, so CI
+          # and local development are held to the same floor and ceiling.
+          version-file: pyproject.toml
+
+      - name: Install base dependencies only (no optional extras, no dev group)
+        # --no-dev installs the base runtime dependencies + the project only;
+        # the fastapi extra and the dev dependency group stay out.
+        # --no-editable installs safeuploads as a real distribution (not a
+        # path into the checkout), so the smoke test actually validates an
+        # install.
+        run: uv sync --frozen --no-dev --no-editable
+
+      # Run from outside the repository root so the local `safeuploads/`
+      # package directory cannot shadow the installed distribution:
+      # otherwise this would validate the working tree rather than what a
+      # user actually gets.
+      - name: Import safeuploads without optional extras
+        run: |
+          set -euo pipefail
+          cp -r .venv "$RUNNER_TEMP/base-venv"
+          cd "$RUNNER_TEMP"
+          VIRTUAL_ENV="$RUNNER_TEMP/base-venv" uv run --no-project python "$GITHUB_WORKSPACE/.github/scripts/smoke_import.py"

safeuploads-1.1.3/CHANGELOG.md

@@ -0,0 +1,123 @@
+# 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.3] - 2026-10-22
+
+### Changed
+
+- Development: the Astral `ty` type checker runs beside mypy as an advisory CI job (`Type check (ty, advisory)`); mypy remains the gate.
+- `SeekableFile.read` and `seek` take positional-only parameters, so `BytesIO` and `SpooledTemporaryFile` satisfy the protocol under `ty`. No runtime change.
+- `UploadFileProtocol.seek` may return `int | None`, so FastAPI/Starlette's `UploadFile` (whose `seek` returns `None`) satisfies the protocol under strict type checking. No runtime change.
+
+## [1.1.2] - 2026-10-22
+
+### Changed
+
+- Updated all dependency groups to their latest versions.
+- Updated uv to 0.13.5.
+- Updated GitHub Actions to their latest releases, pinned by commit hash.
+
+## [1.1.1] - 2026-08-19
+
+### Changed
+
+- Migrated CI/CD from Forgejo/Codeberg to GitHub Actions: lint & test, scheduled fuzz, docs deploy, PyPI publish, and Conventional Commits checks.
+- Added Dependabot configuration, a `CODEOWNERS` file, and a scheduled dependency-vulnerability audit workflow (`pip-audit`).
+- Updated all repository, documentation, and badge links from Codeberg to GitHub.
+
+## [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.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
+[1.1.1]: https://github.com/endurain-project/safeuploads/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/endurain-project/safeuploads/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/endurain-project/safeuploads/releases/tag/v1.0.1
+[1.0.0]: https://github.com/endurain-project/safeuploads/releases/tag/v1.0.0
+[0.1.2]: https://github.com/endurain-project/safeuploads/releases/tag/v0.1.2
+[0.1.1]: https://github.com/endurain-project/safeuploads/releases/tag/v0.1.1
+[0.1.0]: https://github.com/endurain-project/safeuploads/releases/tag/v0.1.0

{safeuploads-1.1.1 → safeuploads-1.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: safeuploads
-Version: 1.1.1
+Version: 1.1.3
 Summary: A comprehensive file security system for validating uploads and preventing attacks
 Author-email: João Vitória Silva <joao@endurain.com>
 License: MIT

{safeuploads-1.1.1 → safeuploads-1.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "safeuploads"
-version = "1.1.1"
+version = "1.1.3"
 description = "A comprehensive file security system for validating uploads and preventing attacks"
 authors = [
     {name = "João Vitória Silva",email = "joao@endurain.com"}
@@ -24,6 +24,7 @@ dev = [
     "ruff>=0.9.0",
     "hypothesis>=6.100,<7.0",
     "mypy>=1.20.2",
+    "ty>=0.0.83",
     "types-defusedxml",
     # HTTP stack for the FastAPI multipart integration test
     "httpx>=0.27,<1.0",
@@ -40,7 +41,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.uv]
-required-version = "0.12.5"
+required-version = "0.13.5"
 exclude-newer = "30 days"
 
 [tool.ruff]
@@ -165,3 +166,11 @@ exclude = ["tests/"]
 [[tool.mypy.overrides]]
 module = ["magic", "fastapi"]
 ignore_missing_imports = true
+
+# ``ty`` runs beside mypy as an advisory, non-blocking CI job (it is pre-1.0);
+# mypy stays the gate. Same scope as ``[tool.mypy]``.
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.src]
+include = ["safeuploads"]

{safeuploads-1.1.1 → safeuploads-1.1.3}/safeuploads/protocols.py

@@ -23,7 +23,7 @@ class SeekableFile(Protocol):
         tell: Return current file pointer position.
     """
 
-    def read(self, size: int = -1) -> bytes:
+    def read(self, size: int = -1, /) -> bytes:
         """
         Read bytes from the file.
 
@@ -35,7 +35,7 @@ class SeekableFile(Protocol):
         """
         ...  # pragma: no cover
 
-    def seek(self, offset: int, whence: int = 0) -> int:
+    def seek(self, offset: int, whence: int = 0, /) -> int:
         """
         Move file pointer to specified position.
 
@@ -76,7 +76,7 @@ class UploadFileProtocol(Protocol):
     filename: str | None
     size: int | None
 
-    async def read(self, size: int = -1) -> bytes:
+    async def read(self, size: int = -1, /) -> bytes:
         """
         Read bytes from the uploaded file.
 
@@ -88,7 +88,7 @@ class UploadFileProtocol(Protocol):
         """
         ...  # pragma: no cover
 
-    async def seek(self, offset: int) -> int:
+    async def seek(self, offset: int) -> int | None:
         """
         Move file pointer to specified position.
 
@@ -96,6 +96,7 @@ class UploadFileProtocol(Protocol):
             offset: Position to move to in bytes.
 
         Returns:
-            New position in the file.
+            New position in the file, or None for implementations
+            (such as Starlette's UploadFile) that return nothing.
         """
         ...  # pragma: no cover