python-mytnb 0.1.0__py3-none-any.whl

mytnb/client/client.py

@@ -0,0 +1,239 @@
+"""myTNB API client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+import tls_client
+
+from mytnb.auth import Credentials
+from mytnb.client.auth import login
+from mytnb.client.config import USER_AGENT
+from mytnb.client.legacy import _LegacyTransport
+from mytnb.client.rest import _RestTransport
+from mytnb.models import AccountUsage, BREligibility, SMRAccount
+
+
+class MyTNBClient:
+    """Client for interacting with the myTNB API.
+
+    This client supports two API backends:
+    - Legacy ASMX API (mytnbapp.tnb.com.my) - uses encrypted payloads
+    - REST API (api.mytnb.com.my) - uses JWT authentication
+
+    For the REST API, you need an API key and authorization token.
+    The legacy API payloads are automatically encrypted using the
+    embedded RSA public key + AES-256-CBC.
+    """
+
+    def __init__(
+        self,
+        credentials: Credentials,
+        timeout: float = 30.0,
+        *,
+        use_staging_key: bool = False,
+    ):
+        self._credentials = credentials
+        self._timeout = timeout
+        self._use_staging_key = use_staging_key
+        self._http_client: Optional[httpx.AsyncClient] = None
+        self._tls_session: Optional[tls_client.Session] = None
+        self._rest: Optional[_RestTransport] = None
+        self._legacy: Optional[_LegacyTransport] = None
+
+    @property
+    def credentials(self) -> Credentials:
+        """The authenticated credentials for this client."""
+        return self._credentials
+
+    @property
+    def _client(self) -> httpx.AsyncClient:
+        if self._http_client is None or self._http_client.is_closed:
+            self._http_client = httpx.AsyncClient(
+                timeout=self._timeout,
+                headers={"User-Agent": USER_AGENT},
+            )
+        return self._http_client
+
+    @property
+    def _legacy_client(self) -> tls_client.Session:
+        """Get or create a tls_client session for legacy ASMX requests.
+
+        Uses an Android TLS fingerprint to bypass CloudFront WAF.
+        """
+        if self._tls_session is None:
+            self._tls_session = tls_client.Session(
+                client_identifier="okhttp4_android_13",
+            )
+        return self._tls_session
+
+    @property
+    def _rest_transport(self) -> _RestTransport:
+        if self._rest is None:
+            self._rest = _RestTransport(self._client, self._credentials)
+        return self._rest
+
+    @property
+    def _legacy_transport(self) -> _LegacyTransport:
+        if self._legacy is None:
+            self._legacy = _LegacyTransport(
+                self._legacy_client,
+                self._credentials,
+                self._timeout,
+                self._use_staging_key,
+            )
+        return self._legacy
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._http_client and not self._http_client.is_closed:
+            await self._http_client.aclose()
+
+    async def __aenter__(self) -> "MyTNBClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    login = classmethod(login)
+
+    # ── REST API endpoints ──────────────────────────────────────────
+
+    async def get_bill_eligibility(
+        self, contract_accounts: list[str], user_id: str
+    ) -> list[BREligibility]:
+        """Get bill rendering eligibility indicators for accounts."""
+        body = {"caNos": contract_accounts, "userID": user_id}
+        data = await self._rest_transport.post(
+            "BillRendering/api/v1/BillRendering/BREligibilityIndicators",
+            body=body,
+        )
+        content = data.get("content", [])
+        return [BREligibility.model_validate(item) for item in content]
+
+    async def get_draft_application_status(self) -> dict:
+        """Get draft application status for MyHome."""
+        data = await self._rest_transport.post(
+            "myhome/myhome-svc/api/v1/GetDraftApplication/GetDraftApplicationStatus",
+            use_bearer=True,
+        )
+        return data.get("content") or data
+
+    async def get_eligibility_icons(self) -> dict:
+        """Get more icon list (eligibility features)."""
+        user_info = self._credentials.user_info
+        device_info = self._credentials.device_info
+
+        body = {}
+        if user_info and device_info:
+            body = {
+                "usrInf": {
+                    "userName": user_info.user_name,
+                    "userID": user_info.user_id,
+                    "sspuid": user_info.user_id,
+                    "deviceID": device_info.device_id,
+                    "language": user_info.language,
+                    "sec_auth_k1": self._credentials.secure_key or "",
+                    "sec_auth_k2": "",
+                    "isWhiteList": False,
+                },
+                "deviceInf": device_info.to_dict(),
+            }
+
+        data = await self._rest_transport.post(
+            "Eligibility/api/v1/Eligibility/GetMoreIconList",
+            body=body,
+        )
+        return data.get("content") or data
+
+    # ── Legacy API endpoints (auto-encrypted) ───────────────────────
+
+    async def get_account_usage_smart(
+        self,
+        account_number: str,
+        *,
+        is_owner: bool = True,
+    ) -> AccountUsage:
+        """Get smart meter account usage data."""
+        data = {
+            "contractAccount": account_number,
+            "isOwner": "true" if is_owner else "false",
+            "metercode": "",
+            "usrInf": self._legacy_transport.base_user_info(),
+        }
+        result = await self._legacy_transport.post("GetAccountUsageSmart", data)
+        return AccountUsage.from_api_response(result.get("data", {}))
+
+    async def get_smr_accounts(
+        self,
+        contract_accounts: list[str],
+    ) -> list[SMRAccount]:
+        """Get Smart Meter Reading account statuses."""
+        data = {
+            "contractAccounts": contract_accounts,
+            "usrInf": self._legacy_transport.base_user_info(),
+        }
+        result = await self._legacy_transport.post("GetAccountsSMRIcon", data)
+        accounts = result.get("data", [])
+        return [SMRAccount.model_validate(acc) for acc in accounts]
+
+    async def get_services(self) -> dict:
+        """Get available services (V4)."""
+        data = {"usrInf": self._legacy_transport.base_user_info()}
+        return await self._legacy_transport.post("GetServicesV4", data)
+
+    async def get_energy_recommendations(
+        self,
+        account_number: str,
+        *,
+        is_owner: bool = True,
+    ) -> dict:
+        """Get energy budget recommendations."""
+        data = {
+            "contractAccount": account_number,
+            "isOwner": "true" if is_owner else "false",
+            "usrInf": self._legacy_transport.base_user_info(),
+        }
+        result = await self._legacy_transport.post("GetUserEBRecommendations", data)
+        return result.get("data") or result
+
+    async def get_account_due_amount(
+        self,
+        account_number: str,
+        *,
+        is_owner: bool = True,
+    ) -> dict:
+        """Get account due amount."""
+        data = {
+            "contractAccount": account_number,
+            "isOwnedAccount": "true" if is_owner else "false",
+            "usrInf": self._legacy_transport.base_user_info(),
+        }
+        result = await self._legacy_transport.post("GetAccountDueAmount", data)
+        return result.get("data") or result
+
+    async def get_bill_history(
+        self,
+        account_number: str,
+        *,
+        is_owner: bool = True,
+    ) -> dict:
+        """Get bill payment history."""
+        data = {
+            "contractAccount": account_number,
+            "isOwnedAccount": "true" if is_owner else "false",
+            "usrInf": self._legacy_transport.base_user_info(),
+        }
+        result = await self._legacy_transport.post("GetBillHistory", data)
+        return result.get("data") or result
+
+    async def get_current_usage(self, account_number: str) -> dict:
+        """Get a simplified summary of current usage."""
+        usage = await self.get_account_usage_smart(account_number)
+        return {
+            "current_usage_kwh": usage.current_usage_kwh,
+            "current_cost_rm": usage.current_cost_rm,
+            "projected_cost_rm": usage.projected_cost_rm,
+            "date_range": usage.date_range,
+        }

mytnb/client/config.py

@@ -0,0 +1,35 @@
+"""myTNB API client configuration."""
+
+from __future__ import annotations
+
+import logging
+
+from mytnb.exceptions import AuthenticationError, GeoBlockedError, RateLimitError
+
+# Base URLs
+LEGACY_BASE_URL = "https://mytnbapp.tnb.com.my/v7/mytnbws.asmx"
+REST_BASE_URL = "https://api.mytnb.com.my"
+SITECORE_LOGIN_URL = "https://www.mytnb.com.my/api/sitecore/Account/Login"
+SSO_HANDLER_URL = "https://myaccount.mytnb.com.my/SSO/SSOHandler"
+
+# Default user agents
+USER_AGENT = "RestSharp/110.2.0.0"
+USER_AGENT_IOS = "myTNB/1425 CFNetwork/3860.500.112 Darwin/25.4.0"
+
+# Default API key for token generation (embedded in the mobile app)
+DEFAULT_API_KEY = "gpUS5pe4aO2yMbId7bFa13dGfYYnBWbjn3vqn0d7"
+
+# Default security key for legacy ASMX requests (embedded in the mobile app)
+DEFAULT_SECURE_KEY_K1 = "E6148656-205B-494C-BC95-CC241423E72F"
+
+logger = logging.getLogger(__name__)
+
+
+def _check_http_status(status_code: int, context: str = "API") -> None:
+    """Check for common HTTP error status codes."""
+    if status_code == 403:
+        raise GeoBlockedError()
+    if status_code == 401:
+        raise AuthenticationError("Authentication failed", error_code="401")
+    if status_code == 429:
+        raise RateLimitError(f"Rate limited by {context}")

mytnb/client/legacy.py

@@ -0,0 +1,120 @@
+"""Legacy ASMX API transport (mytnbapp.tnb.com.my) with encryption."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+
+import tls_client
+
+from mytnb.auth import Credentials
+from mytnb.client.config import (
+    DEFAULT_SECURE_KEY_K1,
+    LEGACY_BASE_URL,
+    USER_AGENT,
+    _check_http_status,
+)
+from mytnb.crypto import encrypt_request
+from mytnb.exceptions import (
+    APIError,
+    MyTNBError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _LegacyTransport:
+    """Internal helper for legacy ASMX API encrypted requests."""
+
+    def __init__(
+        self,
+        session: tls_client.Session,
+        credentials: Credentials,
+        timeout: float,
+        use_staging_key: bool,
+    ):
+        self._session = session
+        self._credentials = credentials
+        self._timeout = timeout
+        self._use_staging_key = use_staging_key
+
+    def headers(self) -> dict[str, str]:
+        """Build headers for legacy ASMX API requests."""
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "Accept": "application/json,text/json,text/x-json,text/javascript,application/xml,text/xml",
+            "Lang": "EN",
+        }
+
+        if self._credentials.user_info:
+            headers["UserInfo"] = json.dumps(self._credentials.user_info.to_dict())
+
+        if self._credentials.secure_key:
+            headers["SecureKey"] = self._credentials.secure_key
+
+        return headers
+
+    def base_user_info(self) -> dict:
+        """Build the usrInf object from credentials for legacy ASMX requests."""
+        ui = self._credentials.user_info
+        di = self._credentials.device_info
+        if not ui:
+            raise MyTNBError("user_info is required for legacy API calls")
+        return {
+            "eid": ui.user_name,
+            "sspuid": ui.user_id,
+            "did": di.device_id if di else "",
+            "ft": "",
+            "lang": ui.language,
+            "sec_auth_k1": DEFAULT_SECURE_KEY_K1,
+            "sec_auth_k2": "",
+            "ses_param1": "",
+            "ses_param2": "",
+        }
+
+    async def post(self, endpoint: str, data: Any) -> dict:
+        """Make a POST request to the legacy ASMX API.
+
+        Automatically encrypts the data using AES-256-CBC + RSA-OAEP.
+        Uses tls_client with an Android TLS fingerprint to bypass CloudFront WAF.
+        """
+        url = f"{LEGACY_BASE_URL}/{endpoint}"
+        req_headers = self.headers()
+        req_headers["User-Agent"] = USER_AGENT
+
+        payload = encrypt_request(data, use_staging_key=self._use_staging_key)
+        body = {"dt": payload.to_dict()}
+
+        response = await asyncio.to_thread(
+            self._session.post,
+            url,
+            headers=req_headers,
+            json=body,
+            timeout_seconds=int(self._timeout),
+        )
+        logger.debug("Legacy POST %s → %s", endpoint, response.status_code)
+
+        _check_http_status(response.status_code, context="legacy API")
+
+        if response.status_code != 200:
+            raise APIError(
+                message=f"Legacy API request failed with status {response.status_code}",
+                error_code=str(response.status_code),
+            )
+
+        data = response.json()
+
+        d = data.get("d", {})
+        error_code = d.get("ErrorCode")
+        if error_code and error_code not in ("7200", "7204"):
+            display_msg = d.get("DisplayMessage") or d.get("displayMessage")
+            msg = display_msg or d.get("Message") or d.get("message") or "Unknown error"
+            raise APIError(
+                message=msg,
+                error_code=error_code,
+                display_message=display_msg,
+            )
+
+        return d

mytnb/client/rest.py

@@ -0,0 +1,117 @@
+"""REST API transport (api.mytnb.com.my)."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+import httpx
+
+from mytnb.auth import Credentials
+from mytnb.client.config import REST_BASE_URL, _check_http_status
+from mytnb.exceptions import APIError
+
+logger = logging.getLogger(__name__)
+
+
+class _RestTransport:
+    """Internal helper for REST API HTTP requests."""
+
+    def __init__(self, client: httpx.AsyncClient, credentials: Credentials):
+        self._client = client
+        self._credentials = credentials
+
+    def headers(self) -> dict[str, str]:
+        """Build headers for REST API requests."""
+        headers: dict[str, str] = {
+            "Content-Type": "application/json; charset=utf-8",
+            "Accept": "*/*",
+            "x-api-key": self._credentials.api_key,
+            "Authorization": self._credentials.authorization_token,
+        }
+
+        if self._credentials.device_info:
+            view_info = {
+                "DeviceToken": self._credentials.device_info.device_id,
+                "AppVersion": self._credentials.device_info.app_version,
+                "RoleId": self._credentials.user_info.role_id
+                if self._credentials.user_info
+                else "16",
+                "Lang": "EN",
+                "FontSize": "L",
+                "OSType": self._credentials.device_info.os_type,
+            }
+            headers["ViewInfo"] = json.dumps(view_info)
+
+        if self._credentials.channel_api_key:
+            headers["ApiKey"] = self._credentials.channel_api_key
+
+        return headers
+
+    def bearer_headers(self) -> dict[str, str]:
+        """Build headers for Bearer-token authenticated endpoints."""
+        headers = self.headers()
+        if self._credentials.bearer_token:
+            headers["Authorization"] = f"Bearer {self._credentials.bearer_token}"
+        return headers
+
+    async def post(
+        self,
+        path: str,
+        body: Optional[dict] = None,
+        params: Optional[dict] = None,
+        use_bearer: bool = False,
+    ) -> dict:
+        """Make a POST request to the REST API."""
+        url = f"{REST_BASE_URL}/{path.lstrip('/')}"
+        req_headers = self.bearer_headers() if use_bearer else self.headers()
+
+        if params is None:
+            params = {"environment": "Prod"}
+
+        response = await self._client.post(
+            url,
+            headers=req_headers,
+            json=body or {},
+            params=params,
+        )
+        logger.debug("REST POST %s → %s", path, response.status_code)
+
+        _check_http_status(response.status_code)
+        response.raise_for_status()
+        data = response.json()
+
+        status = data.get("statusDetail", {})
+        if status.get("code") and status["code"] != "7200":
+            logger.error(
+                "REST API error code=%s desc=%s",
+                status.get("code"),
+                status.get("description"),
+            )
+            raise APIError(
+                message=status.get("description", "Unknown error"),
+                error_code=status.get("code"),
+            )
+
+        return data
+
+    async def get(
+        self,
+        path: str,
+        params: Optional[dict] = None,
+        use_bearer: bool = False,
+    ) -> dict:
+        """Make a GET request to the REST API."""
+        url = f"{REST_BASE_URL}/{path.lstrip('/')}"
+        req_headers = self.bearer_headers() if use_bearer else self.headers()
+
+        if params is None:
+            params = {"environment": "Prod"}
+
+        response = await self._client.get(url, headers=req_headers, params=params)
+        logger.debug("REST GET %s → %s", path, response.status_code)
+
+        _check_http_status(response.status_code)
+        response.raise_for_status()
+        return response.json()

mytnb/crypto.py

@@ -0,0 +1,142 @@
+"""Encryption module for myTNB API request payloads.
+
+Implements the AES-256-CBC + RSA-OAEP hybrid encryption used by the
+myTNB mobile app (APISecurityManager).
+
+Encryption flow:
+  1. Serialize request data to JSON
+  2. Generate random AES-256 key (32 bytes) and IV (16 bytes)
+  3. Encrypt JSON with AES-256-CBC, PKCS7 padding → base64 → `ae`
+  4. Encrypt AES key with RSA-OAEP (SHA-1) using embedded public key → base64 → `ak`
+  5. Base64-encode the IV → `av`
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+# ── RSA Public Keys (extracted from myTNB.Mobile.Resources.Keys) ──────────
+
+# Production key (PKey.txt) - 2048-bit RSA, exponent 65537
+_PROD_MODULUS_B64 = (
+    "2PUbfII3l4qZYNfvoIavtqL5PoXbnX093tJFHjre6Bspsy8gPMBoerv/GsjOpWVl"
+    "f44y9ey9XUBuIzFYLYmtfAG0CQX90pJ4aDgnUpCiw02D/NShwVRwmujyFjhB3T"
+    "beBbHofue/4KHZrbz2UQD0AgnC/HZiHRp2rFoWRGcud+xrUH6NJiF5YPYRgGKRi/"
+    "s0xOn4xHgU2kpDCuE9/u2HFwxcJQZM+ekQNzo3OMSM53IiTZocToVEi82fJRCBi"
+    "VuprgR3kpoK9gwQkvoScRNY8qcEhLmQr/qJKoI6jBLLkgdvKJoqAlUtKGy9XBsI5"
+    "v9JNV0p5IHFgyAhxP701uHKIQ=="
+)
+
+_PROD_EXPONENT_B64 = "AQAB"
+
+# Staging key (SKey.txt) - for development/testing
+_STAGING_MODULUS_B64 = (
+    "5NMh+MJ+Mb9Fly2tyOtA+SgUE/M5sfYx0xDyfFLuXvQwzTyyHUSRTGvSk1kv4Gz"
+    "7hY4AFHk+/0loQ4YxaWByFh+mMzu2JVJT4iR+xtLTMeY81wbELl78crKevMutJG"
+    "WPX8DEOBrAdpLo2REu6KB085sULrHhbVX9h2aLt0YFYb+IKErxWbkTkI2/VRQjR2"
+    "tU9kOmLxUTTH76ibkVD2GfD8AtZhKNJXSINuIPkovZ8sZPCQI11nhHurc07diCKF"
+    "6YHqJADwe6vukmhaa2Flyc03weQFBopFx3NcQvI69lrOf/URr0GZj8HX8vq8SWuK"
+    "GSbcvPuA3+5FsrEBIFKZg3wQ=="
+)
+
+_STAGING_EXPONENT_B64 = "AQAB"
+
+
+def _build_rsa_public_key(modulus_b64: str, exponent_b64: str) -> RSAPublicKey:
+    """Build an RSA public key from base64-encoded modulus and exponent."""
+    n = int.from_bytes(base64.b64decode(modulus_b64), byteorder="big")
+    e = int.from_bytes(base64.b64decode(exponent_b64), byteorder="big")
+    return rsa.RSAPublicNumbers(e, n).public_key()
+
+
+_PROD_KEY = _build_rsa_public_key(_PROD_MODULUS_B64, _PROD_EXPONENT_B64)
+_STAGING_KEY = _build_rsa_public_key(_STAGING_MODULUS_B64, _STAGING_EXPONENT_B64)
+
+
+# ── PKCS7 padding ────────────────────────────────────────────────────────
+
+def _pkcs7_pad(data: bytes, block_size: int = 16) -> bytes:
+    """Apply PKCS7 padding."""
+    pad_len = block_size - (len(data) % block_size)
+    return data + bytes([pad_len] * pad_len)
+
+
+def _pkcs7_unpad(data: bytes) -> bytes:
+    """Remove PKCS7 padding."""
+    pad_len = data[-1]
+    if pad_len < 1 or pad_len > 16:
+        raise ValueError("Invalid PKCS7 padding")
+    if data[-pad_len:] != bytes([pad_len] * pad_len):
+        raise ValueError("Invalid PKCS7 padding")
+    return data[:-pad_len]
+
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+@dataclass
+class EncryptedPayload:
+    """Encrypted request payload (dt object)."""
+
+    ae: str  # Base64(AES-256-CBC(JSON data))
+    ak: str  # Base64(RSA-OAEP(AES key))
+    av: str  # Base64(IV)
+
+    def to_dict(self) -> dict[str, str]:
+        return {"ae": self.ae, "ak": self.ak, "av": self.av}
+
+
+def encrypt_request(
+    data: Any,
+    *,
+    use_staging_key: bool = False,
+) -> EncryptedPayload:
+    """Encrypt a request payload for the myTNB legacy API.
+
+    Args:
+        data: The request data (will be JSON-serialized).
+        use_staging_key: Use the staging RSA key instead of production.
+
+    Returns:
+        EncryptedPayload with ae, ak, av fields.
+    """
+    rsa_key = _STAGING_KEY if use_staging_key else _PROD_KEY
+
+    # 1. Serialize to JSON bytes
+    json_str = json.dumps(data, separators=(",", ":"))
+    plaintext = json_str.encode("utf-8")
+
+    # 2. Generate random AES-256 key and IV
+    aes_key = os.urandom(32)  # 256-bit key
+    iv = os.urandom(16)  # 128-bit IV
+
+    # 3. AES-256-CBC encrypt with PKCS7 padding
+    padded = _pkcs7_pad(plaintext)
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    encryptor = cipher.encryptor()
+    ciphertext = encryptor.update(padded) + encryptor.finalize()
+    ae = base64.b64encode(ciphertext).decode("ascii")
+
+    # 4. RSA-OAEP encrypt the AES key
+    encrypted_key = rsa_key.encrypt(
+        aes_key,
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA1()),
+            algorithm=hashes.SHA1(),
+            label=None,
+        ),
+    )
+    ak = base64.b64encode(encrypted_key).decode("ascii")
+
+    # 5. Base64-encode the IV
+    av = base64.b64encode(iv).decode("ascii")
+
+    return EncryptedPayload(ae=ae, ak=ak, av=av)