wazzapi 0.1.1__tar.gz → 0.1.2__tar.gz

{wazzapi-0.1.1 → wazzapi-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wazzapi
-Version: 0.1.1
+Version: 0.1.2
 Summary: Typed Python SDK for WazzAPI
 Project-URL: Homepage, https://github.com/wazzapihq/wazzapi-py
 Project-URL: API, https://api.wazzapi.com
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: cryptography<45.0,>=44.0
 Requires-Dist: httpx<1.0,>=0.28
 Requires-Dist: pydantic<3.0,>=2.11
 Description-Content-Type: text/markdown

{wazzapi-0.1.1 → wazzapi-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wazzapi"
-version = "0.1.1"
+version = "0.1.2"
 description = "Typed Python SDK for WazzAPI"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -19,6 +19,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "cryptography>=44.0,<45.0",
   "httpx>=0.28,<1.0",
   "pydantic>=2.11,<3.0",
 ]
@@ -30,6 +31,7 @@ API = "https://api.wazzapi.com"
 [dependency-groups]
 dev = [
   "pytest>=8.3,<9.0",
+  "pytest-asyncio>=0.25,<1.0",
   "twine>=6.1,<7.0",
 ]
 
@@ -52,3 +54,4 @@ include = [
 [tool.pytest]
 python_files = ["test_*.py"]
 testpaths = ["tests"]
+asyncio_mode = "auto"

{wazzapi-0.1.1 → wazzapi-0.1.2}/tests/smoke_test.py

@@ -10,7 +10,7 @@ from wazzapi import (
 
 
 def main() -> None:
-    assert __version__ == "0.1.1"
+    assert __version__ == "0.1.2"
 
     client = WazzapiClient(api_key="smoke-test-token")
     try:

wazzapi-0.1.2/tests/test_media.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives import hmac as crypto_hmac
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from wazzapi.errors import WazzapiMediaError
+from wazzapi.media import _decrypt_wa_media, _media_info_bytes, download_media
+
+PLAINTEXT = b"hello world this is a test file"
+MIMETYPE = "application/pdf"
+_MEDIA_KEY_BYTES = b"\x00" * 32
+MEDIA_KEY = base64.b64encode(_MEDIA_KEY_BYTES).decode()
+
+
+def _encrypt_wa_media(plaintext: bytes, media_key: bytes, mimetype: str) -> bytes:
+    info = _media_info_bytes(mimetype)
+    hkdf = HKDF(algorithm=hashes.SHA256(), length=112, salt=None, info=info)
+    expanded = hkdf.derive(media_key)
+    iv = expanded[:16]
+    aes_key = expanded[16:48]
+    mac_key = expanded[48:80]
+
+    pad_len = 16 - (len(plaintext) % 16)
+    padded = plaintext + bytes([pad_len] * pad_len)
+
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    encryptor = cipher.encryptor()
+    ciphertext = encryptor.update(padded) + encryptor.finalize()
+
+    h = crypto_hmac.HMAC(mac_key, hashes.SHA256())
+    h.update(iv + ciphertext)
+    mac = h.finalize()[:10]
+
+    return ciphertext + mac
+
+
+ENC_BLOB = _encrypt_wa_media(PLAINTEXT, _MEDIA_KEY_BYTES, MIMETYPE)
+FILE_SHA256 = base64.b64encode(hashlib.sha256(PLAINTEXT).digest()).decode()
+ENC_SHA256 = base64.b64encode(hashlib.sha256(ENC_BLOB).digest()).decode()
+
+
+def _mock_client(enc_data: bytes, status_code: int = 200) -> AsyncMock:
+    mock_client = AsyncMock(spec=httpx.AsyncClient)
+    request = httpx.Request("GET", "https://cdn.example.com/file")
+    mock_client.get.return_value = httpx.Response(status_code, content=enc_data, request=request)
+    mock_client.aclose = AsyncMock()
+    return mock_client
+
+
+def test_decrypt_wa_media_success() -> None:
+    result = _decrypt_wa_media(MEDIA_KEY, ENC_BLOB, MIMETYPE)
+    assert result == PLAINTEXT
+
+
+def test_decrypt_wa_media_mac_failure() -> None:
+    bad_blob = ENC_BLOB[:-10] + b"\x00" * 10
+    with pytest.raises(WazzapiMediaError, match="MAC verification failed"):
+        _decrypt_wa_media(MEDIA_KEY, bad_blob, MIMETYPE)
+
+
+def test_decrypt_wa_media_short_data() -> None:
+    with pytest.raises(WazzapiMediaError, match="Encrypted data too short"):
+        _decrypt_wa_media(MEDIA_KEY, b"123", MIMETYPE)
+
+
+def test_decrypt_wa_media_bad_base64_key() -> None:
+    with pytest.raises(WazzapiMediaError, match="Invalid media_key base64"):
+        _decrypt_wa_media("not-valid-b64!!!", ENC_BLOB, MIMETYPE)
+
+
+def test_media_info_bytes_mapping() -> None:
+    assert _media_info_bytes("image/jpeg") == b"WhatsApp Image Keys"
+    assert _media_info_bytes("video/mp4") == b"WhatsApp Video Keys"
+    assert _media_info_bytes("audio/ogg") == b"WhatsApp Audio Keys"
+    assert _media_info_bytes("application/pdf") == b"WhatsApp Document Keys"
+
+
+@pytest.mark.asyncio
+async def test_download_media_success() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    result = await download_media(
+        url="https://cdn.example.com/file",
+        media_key=MEDIA_KEY,
+        mimetype=MIMETYPE,
+        file_sha256=FILE_SHA256,
+        file_enc_sha256=ENC_SHA256,
+        file_name="test.pdf",
+        http_client=mock_client,
+    )
+    assert result.content == PLAINTEXT
+    assert result.mimetype == MIMETYPE
+    assert result.file_name == "test.pdf"
+    assert result.file_size == len(PLAINTEXT)
+    mock_client.get.assert_awaited_once_with("https://cdn.example.com/file")
+    mock_client.aclose.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_download_media_http_error() -> None:
+    mock_client = _mock_client(b"not found", status_code=404)
+    with pytest.raises(WazzapiMediaError, match="CDN fetch failed: 404"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_network_error() -> None:
+    mock_client = AsyncMock(spec=httpx.AsyncClient)
+    mock_client.get.side_effect = httpx.RequestError(
+        "connection refused", request=httpx.Request("GET", "https://cdn.example.com/file")
+    )
+    mock_client.aclose = AsyncMock()
+    with pytest.raises(WazzapiMediaError, match="CDN fetch error:"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_enc_sha_mismatch() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    with pytest.raises(WazzapiMediaError, match="file_enc_sha256 mismatch"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            file_enc_sha256=base64.b64encode(hashlib.sha256(b"wrong").digest()).decode(),
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_plain_sha_mismatch() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    with pytest.raises(WazzapiMediaError, match="file_sha256 mismatch after decryption"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            file_sha256=base64.b64encode(hashlib.sha256(b"wrong").digest()).decode(),
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_no_checksums() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    result = await download_media(
+        url="https://cdn.example.com/file",
+        media_key=MEDIA_KEY,
+        mimetype=MIMETYPE,
+        http_client=mock_client,
+    )
+    assert result.content == PLAINTEXT
+    assert result.file_name == "media"

{wazzapi-0.1.1 → wazzapi-0.1.2}/wazzapi/__init__.py

@@ -1,6 +1,7 @@
 from . import models
 from .client import WazzapiClient
-from .errors import WazzapiAPIError, WazzapiError
+from .errors import WazzapiAPIError, WazzapiError, WazzapiMediaError
+from .media import MediaDownloadResult, download_media
 from .models import *
 from .webhooks import (
     EVENT_HEADER,
@@ -15,18 +16,21 @@ from .webhooks import (
     verify_webhook_signature,
 )
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 __all__ = [
     "EVENT_HEADER",
     "EVENT_ID_HEADER",
     "SIGNATURE_HEADER",
     "__version__",
+    "download_media",
     "generate_webhook_signature",
     "parse_webhook",
+    "MediaDownloadResult",
     "WazzapiAPIError",
     "WazzapiClient",
     "WazzapiError",
+    "WazzapiMediaError",
     "WazzapiWebhookError",
     "WazzapiWebhookParseError",
     "WazzapiWebhookVerificationError",

{wazzapi-0.1.1 → wazzapi-0.1.2}/wazzapi/errors.py

@@ -58,3 +58,7 @@ class WazzapiAPIError(WazzapiError):
             details=details,
             response_text=response.text,
         )
+
+
+class WazzapiMediaError(WazzapiError):
+    """Raised when media download or decryption fails."""

wazzapi-0.1.2/wazzapi/media.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+
+import httpx
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives import hmac as crypto_hmac
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from .errors import WazzapiMediaError
+from .models.media import MediaDownloadResult
+
+logger = logging.getLogger("wazzapi.media")
+
+# https://github.com/tgalal/python-axolotl/wiki/WhatsApp-media-encryption
+_WA_MEDIA_INFO: dict[str, bytes] = {
+    "image": b"WhatsApp Image Keys",
+    "video": b"WhatsApp Video Keys",
+    "audio": b"WhatsApp Audio Keys",
+    "ptt": b"WhatsApp Audio Keys",
+    "document": b"WhatsApp Document Keys",
+    "sticker": b"WhatsApp Image Keys",
+    "history": b"WhatsApp History Keys",
+}
+
+
+def _media_info_bytes(mimetype: str) -> bytes:
+    mt = mimetype.lower()
+    if mt.startswith("image/"):
+        return _WA_MEDIA_INFO["image"]
+    if mt.startswith("video/"):
+        return _WA_MEDIA_INFO["video"]
+    if mt.startswith("audio/"):
+        return _WA_MEDIA_INFO["audio"]
+    return _WA_MEDIA_INFO["document"]
+
+
+def _decrypt_wa_media(media_key_b64: str, enc_data: bytes, mimetype: str) -> bytes:
+    if len(enc_data) < 10:
+        raise WazzapiMediaError("Encrypted data too short")
+
+    try:
+        media_key = base64.b64decode(media_key_b64)
+    except Exception as exc:
+        raise WazzapiMediaError("Invalid media_key base64") from exc
+
+    info = _media_info_bytes(mimetype)
+
+    hkdf = HKDF(algorithm=hashes.SHA256(), length=112, salt=None, info=info)
+    expanded = hkdf.derive(media_key)
+
+    iv = expanded[:16]
+    aes_key = expanded[16:48]
+    mac_key = expanded[48:80]
+
+    ciphertext = enc_data[:-10]
+    mac = enc_data[-10:]
+
+    h = crypto_hmac.HMAC(mac_key, hashes.SHA256())
+    h.update(iv + ciphertext)
+    computed_mac = h.finalize()[:10]
+    if computed_mac != mac:
+        raise WazzapiMediaError(
+            "MAC verification failed — media may be corrupted or mediaKey is wrong"
+        )
+
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    decryptor = cipher.decryptor()
+    plaintext_padded = decryptor.update(ciphertext) + decryptor.finalize()
+
+    if not plaintext_padded:
+        raise WazzapiMediaError("Decrypted plaintext is empty")
+
+    pad_len = plaintext_padded[-1]
+    if pad_len > 16 or pad_len == 0 or pad_len > len(plaintext_padded):
+        raise WazzapiMediaError("Invalid PKCS7 padding")
+    if any(b != pad_len for b in plaintext_padded[-pad_len:]):
+        raise WazzapiMediaError("Invalid PKCS7 padding")
+
+    return plaintext_padded[:-pad_len]
+
+
+async def download_media(
+    url: str,
+    media_key: str,
+    mimetype: str,
+    *,
+    file_sha256: str | None = None,
+    file_enc_sha256: str | None = None,
+    file_name: str | None = None,
+    http_client: httpx.AsyncClient | None = None,
+) -> MediaDownloadResult:
+    logger.info("Downloading media url=%s mimetype=%s", url, mimetype)
+
+    client = http_client or httpx.AsyncClient(follow_redirects=True, timeout=30)
+    owns_client = http_client is None
+
+    try:
+        resp = await client.get(url)
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        logger.error("CDN fetch failed: %s", exc)
+        raise WazzapiMediaError(f"CDN fetch failed: {exc.response.status_code}") from exc
+    except httpx.RequestError as exc:
+        logger.error("CDN network error: %s", exc)
+        raise WazzapiMediaError(f"CDN fetch error: {exc}") from exc
+    finally:
+        if owns_client:
+            await client.aclose()
+
+    enc_data = resp.content
+
+    if file_enc_sha256:
+        expected_enc = base64.b64decode(file_enc_sha256)
+        actual_enc = hashlib.sha256(enc_data).digest()
+        if actual_enc != expected_enc:
+            raise WazzapiMediaError(
+                f"file_enc_sha256 mismatch: CDN returned wrong data (got {len(enc_data)} bytes)"
+            )
+
+    plaintext = _decrypt_wa_media(media_key, enc_data, mimetype)
+
+    if file_sha256:
+        expected = base64.b64decode(file_sha256)
+        actual = hashlib.sha256(plaintext).digest()
+        if actual != expected:
+            raise WazzapiMediaError("file_sha256 mismatch after decryption")
+
+    result = MediaDownloadResult(
+        content=plaintext,
+        mimetype=mimetype,
+        file_name=file_name or "media",
+        file_size=len(plaintext),
+    )
+    logger.info("Media download success url=%s size=%d", url, result.file_size)
+    return result
+
+
+__all__ = [
+    "MediaDownloadResult",
+    "_decrypt_wa_media",
+    "_media_info_bytes",
+    "download_media",
+]

{wazzapi-0.1.1 → wazzapi-0.1.2}/wazzapi/models/__init__.py

@@ -1,6 +1,8 @@
 from .base import WazzapiModel
 from .contacts import *
 from .contacts import __all__ as contacts_all
+from .media import *
+from .media import __all__ as media_all
 from .messages import *
 from .messages import __all__ as messages_all
 from .templates import *
@@ -8,4 +10,4 @@ from .templates import __all__ as templates_all
 from .webhooks import *
 from .webhooks import __all__ as webhooks_all
 
-__all__ = ["WazzapiModel", *contacts_all, *messages_all, *templates_all, *webhooks_all]
+__all__ = ["WazzapiModel", *contacts_all, *media_all, *messages_all, *templates_all, *webhooks_all]

wazzapi-0.1.2/wazzapi/models/media.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from .base import WazzapiModel
+
+
+class MediaDownloadResult(WazzapiModel):
+    content: bytes
+    mimetype: str
+    file_name: str
+    file_size: int
+
+
+__all__ = ["MediaDownloadResult"]