safeuploads 2.0.0__tar.gz → 2.2.0__tar.gz

{safeuploads-2.0.0 → safeuploads-2.2.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.2.0}/.agents/skills/safeuploads-library/references/testing.md

@@ -9,7 +9,7 @@
 - Markers are declared in `pyproject.toml` (`unit`, `integration`, `slow`, `performance`, `fuzz`) and run with `--strict-markers`; mark a new test accordingly.
 - Skips need `reason=`.
 - Coverage is branch coverage with `fail_under = 90`; it is a ratchet, raise it when coverage rises and never lower it.
-- Tests are deterministic and offline; a performance test asserts a generous bound, never an exact time.
+- Tests are deterministic and offline; a performance test asserts a generous bound, never an exact time, and is deselected by default (`addopts` in `pyproject.toml`), so run it with `-m performance`.
 - Do not mock a validator to test the orchestrator's decision; run the real one on a small payload.
 
 ## Fuzzing
@@ -18,6 +18,7 @@
 
 ```bash
 uv run pytest tests/validators -v
-uv run pytest -m "not performance and not fuzz"
+uv run pytest -m "not fuzz"
+uv run pytest -m performance
 uv run pytest --cov=safeuploads --cov-report=term-missing
 ```

safeuploads-2.2.0/.github/workflows/mirror.yml

@@ -0,0 +1,41 @@
+name: Mirror to GitLab
+
+on:
+  push:
+
+concurrency:
+  group: gitlab-mirror
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Push full mirror to GitLab
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}
+        # Credentials go in per-host Authorization headers passed through
+        # GIT_CONFIG_* environment variables, so they never appear in a
+        # command line, a remote URL or the mirror's stored git config.
+        run: |
+          set -euo pipefail
+          github_auth="$(printf 'x-access-token:%s' "$GITHUB_TOKEN" | base64 -w0)"
+          gitlab_auth="$(printf 'oauth2:%s' "$GITLAB_TOKEN" | base64 -w0)"
+          echo "::add-mask::${github_auth}"
+          echo "::add-mask::${gitlab_auth}"
+          export GIT_CONFIG_COUNT=2
+          export GIT_CONFIG_KEY_0="http.https://github.com/.extraheader"
+          export GIT_CONFIG_VALUE_0="Authorization: Basic ${github_auth}"
+          export GIT_CONFIG_KEY_1="http.https://gitlab.com/.extraheader"
+          export GIT_CONFIG_VALUE_1="Authorization: Basic ${gitlab_auth}"
+          mirror_dir="$RUNNER_TEMP/safeuploads.git"
+          git clone --mirror \
+            "https://github.com/${GITHUB_REPOSITORY}.git" "$mirror_dir"
+          cd "$mirror_dir"
+          git remote set-url --push origin \
+            "https://gitlab.com/endurain-project/safeuploads.git"
+          git push --mirror

{safeuploads-2.0.0 → safeuploads-2.2.0}/.github/workflows/publish-safeuploads.yml

@@ -70,6 +70,11 @@ jobs:
             exit 1
           fi
 
+      # python-magic needs the libmagic shared library at import time; install it
+      # explicitly instead of relying on the runner image, as the test workflows do.
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libmagic1
+
       # The full gate runs on every PR, but a tag can point anywhere in history,
       # so re-run it here: a release must never ship code that does not pass.
       - name: Sync dependencies

{safeuploads-2.0.0 → safeuploads-2.2.0}/.gitignore

@@ -15,6 +15,7 @@ site/
 # Python
 __pycache__
 .ruff_cache/
+.mypy_cache/
 .hypothesis/
 
 # Tests

{safeuploads-2.0.0 → safeuploads-2.2.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.2.0}/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.2.0] - 2026-11-05
+
+### Added
+
+- `ConfigValidationIssue`, exported from `safeuploads` and `safeuploads.exceptions`: the record `validate_instance()` and `validate_configuration()` return and `FileSecurityConfigurationError.errors` carries. It is the same dataclass under a name that does not suggest an exception.
+
+### Deprecated
+
+- `ConfigValidationError` is a deprecated alias of `ConfigValidationIssue` and will be removed in 3.0. Accessing or importing it from `safeuploads` or `safeuploads.exceptions` emits a `DeprecationWarning`; it is no longer in `safeuploads.__all__`. It was never an exception, so `except ConfigValidationError` could not catch anything.
+
+### Changed
+
+- Development: the dev dependency `httpx` is replaced by `httpx2`, which Starlette's `TestClient` now expects.
+- Development: performance tests (`-m performance`) are deselected by default; run them with `pytest -m performance`.
+- CI: the publish workflow installs `libmagic1` explicitly, and the GitLab mirror passes its tokens as HTTP authorization headers through `GIT_CONFIG_*` environment variables instead of embedding them in remote URLs.
+
+## [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 +223,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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: safeuploads
-Version: 2.0.0
+Version: 2.2.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.2.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.2.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.2.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`)
 
 ```
@@ -371,7 +373,7 @@ Exception
 All `FileSecurityError` subclasses carry an `error_code` from
 `ErrorCode` for machine-readable classification.
 `FileSecurityConfigurationError` is separate and exposes its
-`errors` list instead. When no code is passed, the default is:
+`errors` list of `ConfigValidationIssue` records instead. When no code is passed, the default is:
 
 | Exception | Default `ErrorCode` |
 |---|---|
@@ -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.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "safeuploads"
-version = "2.0.0"
+version = "2.2.0"
 description = "A comprehensive file security system for validating uploads and preventing attacks"
 authors = [
     {name = "João Vitória Silva",email = "joao@endurain.com"}
@@ -27,7 +27,7 @@ dev = [
     "ty>=0.0.83",
     "types-defusedxml",
     # HTTP stack for the FastAPI multipart integration test
-    "httpx>=0.27,<1.0",
+    "httpx2>=2.16,<3.0",
     "python-multipart>=0.0.9,<1.0",
 ]
 docs = [
@@ -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
@@ -118,6 +118,10 @@ addopts = [
     "--strict-markers",
     "--strict-config",
     "-ra",
+    # Benchmarks assert wall-clock bounds that depend on the machine;
+    # run them explicitly with `pytest -m performance`.
+    "-m",
+    "not performance",
     "--cov=safeuploads",
     "--cov-report=term-missing",
     "--cov-report=html",

{safeuploads-2.0.0 → safeuploads-2.2.0}/safeuploads/__init__.py

@@ -6,6 +6,7 @@ validating uploads and preventing attacks.
 """
 
 from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING
 
 from .audit import (
     AuditEvent,
@@ -28,7 +29,7 @@ from .enums import (
 )
 from .exceptions import (
     CompressionSecurityError,
-    ConfigValidationError,
+    ConfigValidationIssue,
     ContentThreatError,
     ErrorCode,
     ExtensionSecurityError,
@@ -75,6 +76,16 @@ from .validators import (
     XmlSecurityValidator,
 )
 
+if TYPE_CHECKING:
+    # Deprecated alias, resolved by ``__getattr__`` at runtime
+    from .exceptions import ConfigValidationError as ConfigValidationError
+else:
+    from .exceptions import _resolve_deprecated
+
+    def __getattr__(name: str) -> object:
+        """Resolve deprecated package attributes (PEP 562)."""
+        return _resolve_deprecated(__name__, name)
+
 # Configuration is validated explicitly rather than at import
 # time: FileValidator validates its config on construction, and
 # callers can invoke FileSecurityConfig.validate_and_report() or
@@ -95,7 +106,7 @@ __all__ = [
     "SeekableFile",
     "UploadFileProtocol",
     # Exceptions
-    "ConfigValidationError",
+    "ConfigValidationIssue",
     "FileSecurityConfigurationError",
     "ErrorCode",
     "FileSecurityError",

{safeuploads-2.0.0 → safeuploads-2.2.0}/safeuploads/config.py

@@ -11,7 +11,7 @@ from .enums import (
     DangerousExtensionCategory,
     UnicodeAttackCategory,
 )
-from .exceptions import ConfigValidationError, FileSecurityConfigurationError
+from .exceptions import ConfigValidationIssue, FileSecurityConfigurationError
 from .utils import bytes_to_mb
 
 logger = logging.getLogger(__name__)
@@ -23,9 +23,9 @@ def _config_error(
     component: str,
     recommendation: str,
     severity: str = "error",
-) -> ConfigValidationError:
+) -> ConfigValidationIssue:
     """
-    Build a ConfigValidationError with a default severity.
+    Build a ConfigValidationIssue with a default severity.
 
     Centralizes construction so the many validation branches
     share one call shape instead of repeating every field.
@@ -38,9 +38,9 @@ def _config_error(
         severity: Severity level ('error', 'warning', 'info').
 
     Returns:
-        Populated ConfigValidationError instance.
+        Populated ConfigValidationIssue instance.
     """
-    return ConfigValidationError(
+    return ConfigValidationIssue(
         error_type=error_type,
         message=message,
         severity=severity,
@@ -451,7 +451,7 @@ class FileSecurityConfig:
         return None
 
     @classmethod
-    def validate_configuration(cls) -> list[ConfigValidationError]:
+    def validate_configuration(cls) -> list[ConfigValidationIssue]:
         """
         Validate the class-level default configuration.
 
@@ -460,7 +460,7 @@ class FileSecurityConfig:
         """
         return cls._collect_errors(cls, cls.limits)
 
-    def validate_instance(self) -> list[ConfigValidationError]:
+    def validate_instance(self) -> list[ConfigValidationIssue]:
         """
         Validate this instance's configuration.
 
@@ -479,7 +479,7 @@ class FileSecurityConfig:
         cls,
         config: "FileSecurityConfig | type[FileSecurityConfig]",
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Run all validation routines for the given configuration.
 
@@ -495,7 +495,7 @@ class FileSecurityConfig:
         Returns:
             List of detected validation errors.
         """
-        errors: list[ConfigValidationError] = []
+        errors: list[ConfigValidationIssue] = []
 
         # Validate limit types first so the range checks below
         # never compare a wrongly typed value.
@@ -530,7 +530,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_limit_types(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate that every limit holds a value of its declared type.
 
@@ -577,7 +577,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_file_size_limits(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate the provided file size limits.
 
@@ -708,7 +708,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_streaming_limits(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate streaming, resource and content scan limits.
 
@@ -788,7 +788,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_mime_configurations(
         config: "FileSecurityConfig | type[FileSecurityConfig]",
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate MIME type configurations.
 
@@ -876,7 +876,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_extension_configurations(
         config: "FileSecurityConfig | type[FileSecurityConfig]",
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate file extension configurations.
 
@@ -1028,7 +1028,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_compression_settings(
         limits: SecurityLimits,
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate the provided compression-related limits.
 
@@ -1240,7 +1240,7 @@ class FileSecurityConfig:
         return errors
 
     @classmethod
-    def _validate_enum_consistency(cls) -> list[ConfigValidationError]:
+    def _validate_enum_consistency(cls) -> list[ConfigValidationIssue]:
         """
         Validate enum categories for emptiness and overlaps.
 
@@ -1345,7 +1345,7 @@ class FileSecurityConfig:
     @staticmethod
     def _validate_cross_dependencies(
         config: "FileSecurityConfig | type[FileSecurityConfig]",
-    ) -> list[ConfigValidationError]:
+    ) -> list[ConfigValidationIssue]:
         """
         Validate cross-field configuration constraints.
 
@@ -1452,7 +1452,7 @@ class FileSecurityConfig:
 
     @staticmethod
     def _report_errors(
-        errors: list[ConfigValidationError], strict: bool
+        errors: list[ConfigValidationIssue], strict: bool
     ) -> None:
         """
         Log validation issues and optionally raise.

{safeuploads-2.0.0 → safeuploads-2.2.0}/safeuploads/exceptions.py

@@ -1,7 +1,9 @@
 """File security exception classes and error codes."""
 
+import warnings
 from dataclasses import dataclass
 from enum import StrEnum
+from typing import TYPE_CHECKING
 
 # ============================================================================
 # Configuration Validation
@@ -9,10 +11,14 @@ from enum import StrEnum
 
 
 @dataclass
-class ConfigValidationError:
+class ConfigValidationIssue:
     """
     Configuration validation issue with severity and recommendation.
 
+    A plain record, not an exception: ``validate_instance()`` and
+    ``validate_configuration()`` return a list of them, and
+    ``FileSecurityConfigurationError.errors`` carries them.
+
     Attributes:
         error_type: Type of the validation error.
         message: Human-readable error message.
@@ -28,18 +34,59 @@ class ConfigValidationError:
     recommendation: str = ""
 
 
+_DEPRECATED_NAMES = {"ConfigValidationError": "ConfigValidationIssue"}
+
+if TYPE_CHECKING:
+    # Deprecated alias; at runtime ``__getattr__`` resolves it with a
+    # DeprecationWarning. Removed in 3.0.
+    ConfigValidationError = ConfigValidationIssue
+else:
+
+    def _resolve_deprecated(module: str, name: str) -> object:
+        """
+        Return the object a deprecated name stands for, with a warning.
+
+        Args:
+            module: Name of the module the attribute was looked up on.
+            name: Attribute name being looked up.
+
+        Returns:
+            The object that replaces the deprecated name.
+
+        Raises:
+            AttributeError: ``name`` is not a deprecated name.
+        """
+        new_name = _DEPRECATED_NAMES.get(name)
+        if new_name is None:
+            raise AttributeError(
+                f"module {module!r} has no attribute {name!r}"
+            )
+        warnings.warn(
+            f"{name} is deprecated and will be removed in safeuploads"
+            f" 3.0; use {new_name}",
+            DeprecationWarning,
+            # Skip this helper and the module ``__getattr__``
+            stacklevel=3,
+        )
+        return globals()[new_name]
+
+    def __getattr__(name: str) -> object:
+        """Resolve deprecated module attributes (PEP 562)."""
+        return _resolve_deprecated(__name__, name)
+
+
 class FileSecurityConfigurationError(Exception):
     """
     Configuration validation failed with aggregated errors.
 
     Args:
-        errors: List of ConfigValidationError instances.
+        errors: List of ConfigValidationIssue instances.
 
     Attributes:
         errors: List of validation errors that caused failure.
     """
 
-    def __init__(self, errors: list[ConfigValidationError]):
+    def __init__(self, errors: list[ConfigValidationIssue]):
         """Initialize with validation errors."""
         self.errors = errors
         error_messages = [
@@ -49,7 +96,7 @@ class FileSecurityConfigurationError(Exception):
             f"Configuration validation failed: {'; '.join(error_messages)}"
         )
 
-    def __reduce__(self) -> tuple[type, tuple[list[ConfigValidationError]]]:
+    def __reduce__(self) -> tuple[type, tuple[list[ConfigValidationIssue]]]:
         """Rebuild from ``errors`` so pickling round-trips."""
         return (type(self), (self.errors,))