"""Request signature validation helpers.

The implementation is intentionally light. It provides a stable interface for
future HMAC or signed webhook validation without imposing a specific auth
scheme on the existing apps.
"""

from __future__ import annotations

import hmac
from hashlib import sha256


class SignatureValidator:
    """Validate signed requests using a shared-secret HMAC contract."""

    def validate(self, *, payload: bytes, provided_signature: str | None, secret: str | None) -> bool:
        """Return ``True`` when the provided signature matches the payload.

        Empty signatures are treated as invalid so callers can decide whether
        the endpoint requires signatures or supports anonymous traffic.
        """
        if not payload or not provided_signature or not secret:
            return False
        expected = hmac.new(secret.encode("utf-8"), payload, sha256).hexdigest()
        return hmac.compare_digest(expected, provided_signature.strip())