sendithq 0.1.0__py3-none-any.whl

sendithq/__init__.py

@@ -0,0 +1,52 @@
+"""SendItWhenever Python SDK — 초정밀 예약 웹훅을 3줄로.
+
+    from sendithq import SendIt
+    sendit = SendIt("sw_live_xxx")
+    sendit.schedule(url="https://api.myapp.com/hook", in_="2h", payload={"id": 42})
+
+비동기는 ``AsyncSendIt`` 를 쓴다. HMAC 검증은 ``SendIt.verify_signature`` / 모듈 함수.
+"""
+
+from __future__ import annotations
+
+from ._async import AsyncSendIt
+from ._signing import SIGNATURE_HEADER, verify_webhook
+from ._sync import SendIt
+from ._version import __version__
+from .duration import parse_duration
+from .errors import SendItError, SendItErrorCode
+from .models import (
+    BulkAccepted,
+    BulkRejected,
+    BulkScheduleResult,
+    DeliveryAttempt,
+    HttpMethod,
+    ListResult,
+    Schedule,
+    ScheduleRef,
+    ScheduleStatus,
+    SigningSecret,
+    SigningSecretPair,
+)
+
+__all__ = [
+    "__version__",
+    "SendIt",
+    "AsyncSendIt",
+    "SendItError",
+    "SendItErrorCode",
+    "parse_duration",
+    "verify_webhook",
+    "SIGNATURE_HEADER",
+    "Schedule",
+    "ScheduleRef",
+    "DeliveryAttempt",
+    "SigningSecret",
+    "SigningSecretPair",
+    "BulkAccepted",
+    "BulkRejected",
+    "BulkScheduleResult",
+    "ListResult",
+    "HttpMethod",
+    "ScheduleStatus",
+]

sendithq/_apikey.py

@@ -0,0 +1,32 @@
+# API Key 포맷 선검증(생성자에서 첫 요청 전에 빈/형식오류를 표면화). 값 자체의 유효성(폐기·오타)은
+# 서버가 UNAUTHORIZED 로 최종 판정한다. 서버와 단일 규칙을 공유하기 위해 KEY_PATTERN 을 포팅한다.
+# 미러: packages/shared/src/crypto/api-key.ts (parseApiKey)
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal, Optional, cast
+
+ApiKeyEnv = Literal["live", "test"]
+
+__all__ = ["ParsedApiKey", "parse_api_key"]
+
+_KEY_PATTERN = re.compile(r"^sw_(live|test)_([A-Za-z0-9_-]{8,})$")
+
+
+@dataclass(frozen=True)
+class ParsedApiKey:
+    env: ApiKeyEnv
+    prefix: str
+    last4: str
+
+
+def parse_api_key(key: str) -> Optional[ParsedApiKey]:
+    """키 포맷을 검증·파싱한다. 형식이 잘못되면 None."""
+    match = _KEY_PATTERN.match(key)
+    if match is None:
+        return None
+    env = cast(ApiKeyEnv, match.group(1))
+    token = match.group(2)
+    return ParsedApiKey(env=env, prefix=f"sw_{env}", last4=token[-4:])

sendithq/_async.py

@@ -0,0 +1,213 @@
+# 비동기 클라이언트(AsyncSendIt) — httpx.AsyncClient 래퍼. 동기판(_sync.SendIt)과 표면 동일,
+# transport 만 await. 미러: packages/sdk/src/index.ts
+
+from __future__ import annotations
+
+import asyncio
+from types import TracebackType
+from typing import Any, List, Mapping, Optional, Sequence, Type, Union
+
+import httpx
+
+from ._base import _BaseSendIt, clean_query
+from ._core import build_clone_body, build_schedule_body, is_retriable, resolve_fire_at
+from .errors import SendItError
+from .models import (
+    BulkScheduleResult,
+    DeliveryAttempt,
+    HttpMethod,
+    ListResult,
+    Schedule,
+    ScheduleRef,
+    ScheduleStatus,
+    SigningSecretPair,
+)
+
+__all__ = ["AsyncSendIt"]
+
+FireAt = Union[str, Any]
+
+
+class _AsyncSigningSecrets:
+    """signing_secrets.get()/rotate() 네임스페이스(코루틴)."""
+
+    def __init__(self, client: "AsyncSendIt") -> None:
+        self._client = client
+
+    async def get(self) -> SigningSecretPair:
+        raw = await self._client._request("GET", "v1/signing-secrets", retryable=True)
+        return SigningSecretPair.from_wire(raw)
+
+    async def rotate(self) -> SigningSecretPair:
+        raw = await self._client._request("POST", "v1/signing-secrets/rotate", retryable=False)
+        return SigningSecretPair.from_wire(raw)
+
+
+class AsyncSendIt(_BaseSendIt):
+    """SendItWhenever 비동기 클라이언트.
+
+        from sendithq import AsyncSendIt
+        async with AsyncSendIt("sw_live_xxx") as sendit:
+            ref = await sendit.schedule(url="https://api.myapp.com/hook", in_="2h")
+    """
+
+    def __init__(self, api_key: str, **kwargs: Any) -> None:
+        super().__init__(api_key, **kwargs)
+        self._http = httpx.AsyncClient(timeout=self._timeout, follow_redirects=False)
+        self.signing_secrets = _AsyncSigningSecrets(self)
+
+    # ── lifecycle ────────────────────────────────────────────────────────────
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncSendIt":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.aclose()
+
+    # ── transport ──────────────────────────────────────────────────────────
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Optional[Any] = None,
+        retryable: bool = False,
+    ) -> Any:
+        url = self._url(path)
+        headers = self._headers(body is not None)
+        content = self._encode(body)
+        max_attempts = self._max_retries + 1 if retryable else 1
+        last: Optional[SendItError] = None
+
+        for attempt in range(max_attempts):
+            try:
+                resp = await self._http.request(
+                    method, url, params=clean_query(query), content=content, headers=headers
+                )
+                return self._process(resp.status_code, resp.text, resp.is_success)
+            except SendItError as err:
+                last = err
+            except httpx.RequestError as err:
+                last = SendItError("NETWORK", str(err) or "request failed")
+
+            if attempt < max_attempts - 1 and is_retriable(last):
+                await asyncio.sleep(self._backoff_seconds(attempt))
+                continue
+            raise last
+        raise last if last is not None else SendItError("NETWORK", "request failed")
+
+    # ── methods ──────────────────────────────────────────────────────────────
+    async def schedule(
+        self,
+        *,
+        url: str,
+        fire_at: Optional[FireAt] = None,
+        in_: Optional[str] = None,
+        payload: Any = None,
+        method: Optional[HttpMethod] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> ScheduleRef:
+        body = build_schedule_body(
+            url=url,
+            fire_at=fire_at,
+            in_=in_,
+            payload=payload,
+            method=method,
+            headers=headers,
+            idempotency_key=idempotency_key,
+        )
+        raw = await self._request(
+            "POST", "v1/schedules", body=body, retryable=idempotency_key is not None
+        )
+        return ScheduleRef.from_wire(raw)
+
+    async def schedule_many(self, items: Sequence[Mapping[str, Any]]) -> BulkScheduleResult:
+        if not items:
+            raise SendItError("VALIDATION", "schedule_many: items must not be empty")
+        bodies = [
+            build_schedule_body(
+                url=it["url"],
+                fire_at=it.get("fire_at"),
+                in_=it.get("in_"),
+                payload=it.get("payload"),
+                method=it.get("method"),
+                headers=it.get("headers"),
+                idempotency_key=it.get("idempotency_key"),
+            )
+            for it in items
+        ]
+        retryable = all(it.get("idempotency_key") is not None for it in items)
+        raw = await self._request(
+            "POST", "v1/schedules/bulk", body={"items": bodies}, retryable=retryable
+        )
+        return BulkScheduleResult.from_wire(raw)
+
+    async def list(
+        self,
+        *,
+        status: Optional[ScheduleStatus] = None,
+        q: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> ListResult:
+        raw = await self._request(
+            "GET",
+            "v1/schedules",
+            query={"status": status, "q": q, "limit": limit, "offset": offset},
+            retryable=True,
+        )
+        return ListResult.from_wire(raw)
+
+    async def get(self, schedule_id: str) -> Schedule:
+        raw = await self._request("GET", f"v1/schedules/{schedule_id}", retryable=True)
+        return Schedule.from_wire(raw)
+
+    async def get_attempts(self, schedule_id: str) -> List[DeliveryAttempt]:
+        raw = await self._request("GET", f"v1/schedules/{schedule_id}/attempts", retryable=True)
+        return [DeliveryAttempt.from_wire(r) for r in raw.get("items", [])]
+
+    async def reschedule(
+        self,
+        schedule_id: str,
+        *,
+        fire_at: Optional[FireAt] = None,
+        in_: Optional[str] = None,
+    ) -> Schedule:
+        raw = await self._request(
+            "PATCH",
+            f"v1/schedules/{schedule_id}",
+            body={"fireAt": resolve_fire_at(fire_at, in_)},
+            retryable=False,
+        )
+        return Schedule.from_wire(raw)
+
+    async def replay(self, schedule_id: str) -> ScheduleRef:
+        raw = await self._request("POST", f"v1/schedules/{schedule_id}/replay", retryable=False)
+        return ScheduleRef.from_wire(raw)
+
+    async def clone(
+        self,
+        schedule_id: str,
+        *,
+        payload: Any,
+        fire_at: Optional[FireAt] = None,
+        in_: Optional[str] = None,
+    ) -> ScheduleRef:
+        body = build_clone_body(payload=payload, fire_at=fire_at, in_=in_)
+        raw = await self._request(
+            "POST", f"v1/schedules/{schedule_id}/clone", body=body, retryable=False
+        )
+        return ScheduleRef.from_wire(raw)
+
+    async def cancel(self, schedule_id: str) -> Schedule:
+        raw = await self._request("DELETE", f"v1/schedules/{schedule_id}", retryable=True)
+        return Schedule.from_wire(raw)

sendithq/_base.py

@@ -0,0 +1,112 @@
+# sync/async 클라이언트 공통 베이스 — 설정·인증헤더·URL·응답처리·서명검증. transport(httpx Client vs
+# AsyncClient)와 재시도 루프만 서브클래스가 구현한다. 미러: packages/sdk/src/{index,client}.ts
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+from ._apikey import parse_api_key
+from ._core import DASHBOARD_URL, to_error
+from ._verify import verify_signature as _verify_signature
+from ._version import __version__
+from .errors import SendItError
+
+DEFAULT_BASE_URL = "https://api.sendit-whenever.com"
+
+
+def _assert_api_key(api_key: str) -> None:
+    """API Key 를 선검증한다 — 빈 값/형식 오류를 첫 요청 전에 친절히 표면화한다.
+
+    포맷 판정은 서버와 단일 규칙(parse_api_key)을 공유한다. 값 자체의 유효성(폐기·오타)은
+    서버가 UNAUTHORIZED 로 최종 판정한다.
+    """
+    if not api_key:
+        raise SendItError(
+            "UNAUTHORIZED",
+            f"SendIt: an API key is required. Create one in your dashboard at {DASHBOARD_URL}",
+        )
+    if parse_api_key(api_key) is None:
+        raise SendItError(
+            "UNAUTHORIZED",
+            'SendIt: malformed API key (expected "sw_live_…" or "sw_test_…"). '
+            f"Check or create your key at {DASHBOARD_URL}",
+        )
+
+
+def clean_query(query: Optional[Mapping[str, Any]]) -> Dict[str, str]:
+    """None 값을 버리고 문자열화한 query 파라미터."""
+    if not query:
+        return {}
+    return {k: str(v) for k, v in query.items() if v is not None}
+
+
+class _BaseSendIt:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        signing_secret: Optional[str] = None,
+    ) -> None:
+        _assert_api_key(api_key)
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._signing_secret = signing_secret
+        self._auth_header = f"Bearer {api_key}"
+
+    # ── request helpers (transport-agnostic) ─────────────────────────────────
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    def _headers(self, has_body: bool) -> Dict[str, str]:
+        headers = {
+            "authorization": self._auth_header,
+            "user-agent": f"sendithq-python/{__version__}",
+        }
+        if has_body:
+            headers["content-type"] = "application/json"
+        return headers
+
+    @staticmethod
+    def _encode(body: Optional[Any]) -> Optional[bytes]:
+        if body is None:
+            return None
+        return json.dumps(body, ensure_ascii=False).encode("utf-8")
+
+    @staticmethod
+    def _process(status_code: int, text: str, is_success: bool) -> Any:
+        """2xx → 파싱된 JSON(빈 본문은 None), 그 외 → SendItError raise."""
+        if is_success:
+            return None if text == "" else json.loads(text)
+        raise to_error(status_code, text)
+
+    def _backoff_seconds(self, attempt: int) -> float:
+        # 200ms, 400ms, 800ms… (지수백오프). 미러: client.ts sleep(2**attempt * 200).
+        return 0.2 * (2.0**attempt)
+
+    # ── signature verification (sync; no IO) ─────────────────────────────────
+    def verify_signature(
+        self,
+        body: Union[str, bytes],
+        headers: Mapping[str, str],
+        *,
+        secrets: Optional[List[str]] = None,
+        secret: Optional[str] = None,
+        tolerance_sec: int = 300,
+    ) -> bool:
+        """나가는 웹훅 서명 검증(HMAC). 서명 대상은 **raw 본문**이므로 파싱 전 raw body 를 넘긴다.
+
+        우선순위: ``secrets``(2키 권장) → ``secret`` → 생성자 ``signing_secret``.
+        """
+        return _verify_signature(
+            body,
+            headers,
+            secrets=secrets,
+            secret=secret,
+            default_secret=self._signing_secret,
+            tolerance_sec=tolerance_sec,
+        )

sendithq/_core.py

@@ -0,0 +1,165 @@
+# 순수 로직 — sync/async 클라이언트가 공유한다(transport 만 다름). 요청 바디 빌드, fire_at 해석,
+# 에러 매핑, 재시도 판정. API 요청 바디는 **camelCase 키**(targetUrl/fireAt/idempotencyKey)를
+# 쓴다(서버 zod 스키마 packages/shared/src/schemas/index.ts 와 일치). 응답은 snake_case 라
+# models.from_wire 가 그대로 매핑한다. 미러: packages/sdk/src/{index,client}.ts
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Mapping, Optional, Union
+
+from .duration import parse_duration
+from .errors import SendItError, SendItErrorCode
+
+__all__ = [
+    "KNOWN_CODES",
+    "DASHBOARD_URL",
+    "get_header",
+    "resolve_fire_at",
+    "build_schedule_body",
+    "build_clone_body",
+    "to_error",
+    "is_retriable",
+]
+
+# API 가 반환하는 코드(NETWORK 는 로컬 전용이라 제외). 미상 코드는 status 기반 폴백.
+KNOWN_CODES = frozenset(
+    {
+        "UNAUTHORIZED",
+        "FORBIDDEN",
+        "NOT_FOUND",
+        "VALIDATION",
+        "CONFLICT",
+        "RATE_LIMITED",
+        "INTERNAL",
+    }
+)
+
+# 키 발급·관리 안내 링크(생성자 검증 메시지에 첨부, DX).
+DASHBOARD_URL = "https://www.sendit-whenever.com"
+
+FireAt = Union[str, datetime]
+
+
+def get_header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    """헤더 맵에서 대소문자 무시 조회."""
+    target = name.lower()
+    for key, value in headers.items():
+        if key.lower() == target:
+            return value
+    return None
+
+
+def _to_iso8601(dt: datetime) -> str:
+    """tz-aware UTC ISO-8601(밀리초 + 'Z'). naive datetime 은 UTC 로 간주한다.
+
+    서버 스키마가 `.datetime({ offset: true })` 이므로 offset 이 반드시 있어야 한다.
+    """
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def resolve_fire_at(fire_at: Optional[FireAt], in_: Optional[str]) -> str:
+    """fire_at(절대) | in_(상대) 중 정확히 하나 → ISO-8601 문자열."""
+    if fire_at is not None and in_ is not None:
+        raise SendItError("VALIDATION", "provide either fire_at or in_, not both")
+    if in_ is not None:
+        return _to_iso8601(datetime.now(timezone.utc) + parse_duration(in_))
+    if fire_at is not None:
+        if isinstance(fire_at, datetime):
+            return _to_iso8601(fire_at)
+        try:
+            parsed = datetime.fromisoformat(fire_at.strip().replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise SendItError("VALIDATION", f"invalid fire_at: {fire_at!r}") from exc
+        return _to_iso8601(parsed)
+    raise SendItError("VALIDATION", "fire_at or in_ is required")
+
+
+def _serialize_payload(
+    payload: Any, headers: Dict[str, str]
+) -> Optional[str]:
+    """payload 직렬화: 문자열은 그대로, 그 외(객체)는 JSON + content-type 자동 주입.
+
+    ``headers`` 는 제자리에서 변형될 수 있다(유저 미지정 시 content-type 추가).
+    """
+    if payload is None:
+        return None
+    if isinstance(payload, str):
+        return payload
+    serialized = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+    if get_header(headers, "content-type") is None:
+        headers["content-type"] = "application/json"
+    return serialized
+
+
+def build_schedule_body(
+    *,
+    url: str,
+    fire_at: Optional[FireAt],
+    in_: Optional[str],
+    payload: Any,
+    method: Optional[str],
+    headers: Optional[Mapping[str, str]],
+    idempotency_key: Optional[str],
+) -> Dict[str, Any]:
+    """schedule()/schedule_many() 공통 요청 바디(camelCase 키)."""
+    resolved_fire_at = resolve_fire_at(fire_at, in_)
+    hdrs: Dict[str, str] = dict(headers or {})
+    serialized = _serialize_payload(payload, hdrs)
+
+    body: Dict[str, Any] = {"targetUrl": url, "fireAt": resolved_fire_at}
+    if method is not None:
+        body["method"] = method
+    if hdrs:
+        body["headers"] = hdrs
+    if serialized is not None:
+        body["payload"] = serialized
+    if idempotency_key is not None:
+        body["idempotencyKey"] = idempotency_key
+    return body
+
+
+def build_clone_body(
+    *, payload: Any, fire_at: Optional[FireAt], in_: Optional[str]
+) -> Dict[str, Any]:
+    """/clone 요청 바디. payload 직렬화 + 선택 fireAt(없으면 즉시 발사).
+
+    헤더·메서드는 서버가 원본에서 승계하므로 content-type 자동주입은 하지 않는다.
+    """
+    if payload is None:
+        raise SendItError("VALIDATION", "clone: payload is required")
+    serialized = payload if isinstance(payload, str) else json.dumps(
+        payload, separators=(",", ":"), ensure_ascii=False
+    )
+    body: Dict[str, Any] = {"payload": serialized}
+    if fire_at is not None or in_ is not None:
+        body["fireAt"] = resolve_fire_at(fire_at, in_)
+    return body
+
+
+def to_error(status: int, text: str) -> SendItError:
+    """에러 응답 바디({ error: { code, message } })를 SendItError 로 매핑."""
+    code: SendItErrorCode = "INTERNAL" if status >= 500 else "VALIDATION"
+    message = f"request failed with status {status}"
+    try:
+        parsed = json.loads(text)
+        err = parsed.get("error") if isinstance(parsed, dict) else None
+        if isinstance(err, dict):
+            c = err.get("code")
+            if isinstance(c, str) and c in KNOWN_CODES:
+                code = c  # type: ignore[assignment]
+            m = err.get("message")
+            if isinstance(m, str):
+                message = m
+    except (ValueError, AttributeError):
+        # 비-JSON 에러 바디(프록시 5xx 등)는 기본 코드/메시지 유지.
+        pass
+    return SendItError(code, message, status)
+
+
+def is_retriable(err: SendItError) -> bool:
+    """재시도 대상: 네트워크 실패 또는 5xx 일시 장애만. 4xx 는 즉시 표면화."""
+    return err.code == "NETWORK" or (err.status is not None and err.status >= 500)

sendithq/_signing.py

@@ -0,0 +1,89 @@
+# 나가는 웹훅 HMAC-SHA256 서명 검증 — TS 단일 구현처(packages/shared/src/crypto/hmac.ts)의
+# 크로스랭귀지 포팅이다. Python SDK 는 TS shared 를 import 할 수 없으므로 알고리즘을 포팅하되,
+# 두 언어가 동일한 골든 벡터(packages/shared/src/crypto/__fixtures__/hmac-vectors.json)에 묶여
+# 드리프트가 CI 에서 즉시 깨지도록 한다(CLAUDE.md §8 정신 보존).
+#
+# 헤더: `X-SendIt-Signature: t=<unix_ts>,v1=<hmac_sha256_hex>`
+# 서명 대상: `"{t}.{raw_body}"`, 키 = 유저별 Signing Secret(평문).
+# timestamp 포함 → 리플레이 차단(검증 측에서 허용 윈도우 초과 거부).
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Any, Dict, Optional, Union
+
+__all__ = [
+    "SIGNATURE_HEADER",
+    "sign_webhook",
+    "parse_signature_header",
+    "verify_webhook",
+]
+
+# 서명 헤더 이름(상수 — 오타로 인한 드리프트 방지).
+SIGNATURE_HEADER = "X-SendIt-Signature"
+
+
+def _to_bytes(body: Union[str, bytes]) -> bytes:
+    return body if isinstance(body, bytes) else body.encode("utf-8")
+
+
+def _compute_signature(secret: str, t: int, body: Union[str, bytes]) -> str:
+    """`"{t}.{body}"` 에 대한 HMAC-SHA256 hex 다이제스트."""
+    message = f"{t}.".encode("utf-8") + _to_bytes(body)
+    return hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
+
+
+def sign_webhook(
+    secret: str, body: Union[str, bytes], now_ms: Optional[int] = None
+) -> str:
+    """웹훅 본문에 서명해 헤더 값(`t=..,v1=..`)을 만든다.
+
+    주로 테스트·골든 벡터 생성용. ``now_ms`` 로 결정성 주입 가능(기본 현재시각).
+    """
+    now = time.time() * 1000 if now_ms is None else now_ms
+    t = int(now // 1000)
+    v1 = _compute_signature(secret, t, body)
+    return f"t={t},v1={v1}"
+
+
+def parse_signature_header(header: str) -> Optional[Dict[str, Any]]:
+    """헤더 문자열 `t=..,v1=..` 을 파싱한다. 형식 불량이면 None."""
+    t: Optional[int] = None
+    v1: Optional[str] = None
+    for part in header.split(","):
+        key, _, val = part.partition("=")
+        if key == "t" and val:
+            try:
+                t = int(val)
+            except ValueError:
+                continue
+        elif key == "v1" and val:
+            v1 = val
+    if t is None or v1 is None:
+        return None
+    return {"t": t, "v1": v1}
+
+
+def verify_webhook(
+    secret: str,
+    body: Union[str, bytes],
+    header: str,
+    *,
+    tolerance_sec: int = 300,
+    now_ms: Optional[int] = None,
+) -> bool:
+    """수신 측 검증. 서명 일치 + timestamp 허용 윈도우(기본 5분) 검사.
+
+    상수시간 비교(:func:`hmac.compare_digest`)로 타이밍 누수를 차단한다.
+    """
+    now = time.time() * 1000 if now_ms is None else now_ms
+    now_sec = int(now // 1000)
+    parsed = parse_signature_header(header)
+    if parsed is None:
+        return False
+    if abs(now_sec - parsed["t"]) > tolerance_sec:
+        return False
+    expected = _compute_signature(secret, parsed["t"], body)
+    return hmac.compare_digest(expected, parsed["v1"])