"""Validation for embedded request images. Callers translate ``EmbeddedImageError`` into their own validation error type. The strict mode verifies the complete raster with Pillow; the signature mode intentionally accepts header-only images for backends that validate only magic bytes before forwarding the image to another service. """ from __future__ import annotations import base64 import binascii import io import re from collections.abc import Iterable MAX_IMAGES = 4 MAX_IMAGE_BYTES = 4 * 1024 * 1024 MAX_IMAGES_BYTES = 8 * 1024 * 1024 _STRICT_DATA_URI = re.compile( r"^data:(image/(?:png|jpe?g|webp));base64,([A-Za-z0-9+/]*={0,2})$", re.IGNORECASE ) _DATA_URL = re.compile(r"^data:([^;,]+);base64,(.*)$", re.DOTALL) _FORMATS = {"image/png": "PNG", "image/jpeg": "JPEG", "image/webp": "WEBP"} class EmbeddedImageError(ValueError): """A request-image failure, with a stable code for the serving layer.""" def __init__(self, code: str, message: str) -> None: super().__init__(message) self.code = code def normalize_embedded_image( value: object, *, strict: bool = False, max_image_bytes: int = MAX_IMAGE_BYTES, max_pixels: int = 16_000_000, ) -> dict[str, str]: """Normalize a data URL or exact ``{content_type, base64}`` object. ``strict=True`` verifies restricted data-URI syntax and complete raster data with Pillow, including the dimension limit. The default checks image signatures and accepts a more permissive data-URL syntax. """ if isinstance(value, str): matched = (_STRICT_DATA_URI if strict else _DATA_URL).fullmatch(value) if matched is None: label = "URI" if strict else "URL" raise EmbeddedImageError( "invalid_image", f"image must be an embedded base64 data {label}" ) value = {"content_type": matched.group(1), "base64": matched.group(2)} if type(value) is not dict or set(value) != {"content_type", "base64"}: raise EmbeddedImageError("invalid_image", "image object has invalid fields") content_type = value["content_type"] encoded = value["base64"] if type(content_type) is not str or type(encoded) is not str: raise EmbeddedImageError("invalid_image", "image fields must be strings") canonical_type = content_type.lower().replace("image/jpg", "image/jpeg") if canonical_type not in _FORMATS: raise EmbeddedImageError("invalid_image", "image content type is not supported") try: decoded = base64.b64decode(encoded, validate=True) except (binascii.Error, ValueError) as error: raise EmbeddedImageError( "invalid_image", "image base64 is malformed" ) from error if not decoded: raise EmbeddedImageError("invalid_image", "image payload is empty") if len(decoded) > max_image_bytes: raise EmbeddedImageError( "image_too_large", "image exceeds the decoded byte limit" ) if strict: _verify_raster(decoded, _FORMATS[canonical_type], max_pixels=max_pixels) elif not _has_image_signature(canonical_type, decoded): raise EmbeddedImageError( "invalid_image", "image payload does not match its content type" ) return { "content_type": canonical_type, "base64": base64.b64encode(decoded).decode("ascii"), } def _verify_raster(data: bytes, expected_format: str, *, max_pixels: int) -> None: from PIL import Image, UnidentifiedImageError try: with Image.open(io.BytesIO(data)) as image: if image.format != expected_format: raise EmbeddedImageError( "invalid_image", "image payload does not match its content type" ) if image.width * image.height > max_pixels: raise EmbeddedImageError( "invalid_image", "image dimensions are too large" ) image.verify() except EmbeddedImageError: raise except ( UnidentifiedImageError, OSError, ValueError, Image.DecompressionBombError, ) as error: raise EmbeddedImageError("invalid_image", "image payload is invalid") from error def _has_image_signature(content_type: str, data: bytes) -> bool: if content_type == "image/png": return data.startswith(b"\x89PNG\r\n\x1a\n") if content_type == "image/jpeg": return data.startswith(b"\xff\xd8\xff") return len(data) >= 12 and data.startswith(b"RIFF") and data[8:12] == b"WEBP" def decoded_base64_size(encoded: str) -> int: """Size of already validated, canonical base64 without decoding again.""" return len(encoded) * 3 // 4 - (len(encoded) - len(encoded.rstrip("="))) def validate_image_count(value: object, *, max_images: int = MAX_IMAGES) -> object: if not isinstance(value, (list, tuple)): raise EmbeddedImageError("invalid_image", "images must be an array") if len(value) > max_images: raise EmbeddedImageError( "too_many_images", "request exceeds the image count limit" ) return value def validate_total_image_bytes( sizes: Iterable[int], *, max_bytes: int = MAX_IMAGES_BYTES ) -> None: if sum(sizes) > max_bytes: raise EmbeddedImageError( "images_too_large", "images exceed the aggregate decoded byte limit" )