"""
Optional image storage (S3 / Cloudflare R2).

Privacy contract
----------------
Visitor uploads are NEVER persisted by default. This module is only invoked
when ALL of the following are true:

  1. settings.store_uploads is True (env: STORE_UPLOADS=true)
  2. The request comes from an authenticated user
  3. That user has explicitly opted in to scan history / forensic reports

None of this is wired up in Stage 1. The module exists to make the
architecture visible and to lock in the privacy default at the type level.
"""
from __future__ import annotations


def store_image(scan_id: str, image_bytes: bytes) -> str:  # noqa: ARG001
    """Upload image to blob storage; return the object key.

    Raises
    ------
    PermissionError :
        If called when settings.store_uploads is False, as a defence-in-depth
        check against a future bug accidentally persisting visitor uploads.
    """
    from ..config import settings

    if not settings.store_uploads:
        raise PermissionError(
            "Image storage is disabled by default. Enable explicitly via "
            "STORE_UPLOADS=true AND user opt-in."
        )
    raise NotImplementedError("Blob storage wired up in Stage 2.")