python-casahome 0.2.0__py3-none-any.whl

casahome/auth.py

@@ -0,0 +1,199 @@
+"""Firebase refresh-token auth for the Casa API.
+
+Casa signs members in with Firebase Phone Auth. SMS sign-in can't be reproduced
+off-device (Firebase requires APNs app verification), so this library starts
+from a refresh token taken from the member's own app session and exchanges it for short-lived
+ID tokens via the standard Firebase secure token endpoint.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from collections.abc import Awaitable, Callable
+
+import aiohttp
+from pydantic import ValidationError
+
+from ._base_http import wrap_connection_errors
+from .const import (
+    DEFAULT_TIMEOUT_SECONDS,
+    FIREBASE_API_KEY,
+    FIREBASE_BUNDLE_ID,
+    FIREBASE_CLIENT_VERSION,
+    FIREBASE_GMP_ID,
+    SECURETOKEN_URL,
+    TOKEN_REFRESH_LEEWAY_SECONDS,
+)
+from .exceptions import CasaAuthError, CasaConnectionError, CasaError
+from .models._base import CasaModel
+
+_LOGGER = logging.getLogger("casahome")
+
+_FATAL_REFRESH_ERRORS = frozenset(
+    {"TOKEN_EXPIRED", "USER_DISABLED", "USER_NOT_FOUND", "INVALID_REFRESH_TOKEN"}
+)
+
+
+class TokenResponse(CasaModel):
+    """Response from ``securetoken.googleapis.com/v1/token``."""
+
+    access_token: str
+    expires_in: str
+    token_type: str
+    refresh_token: str
+    id_token: str
+    user_id: str
+    project_id: str
+
+
+class FirebaseAuth:
+    """Exchanges a Firebase refresh token for ID tokens, caching until near expiry.
+
+    Firebase may rotate the refresh token on any refresh. Pass
+    ``on_refresh_token_rotated`` (sync or async) to persist the new one, or read
+    :attr:`refresh_token` after use.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        refresh_token: str,
+        *,
+        api_key: str = FIREBASE_API_KEY,
+        token_url: str = SECURETOKEN_URL,
+        on_refresh_token_rotated: Callable[[str], Awaitable[None] | None] | None = None,
+    ) -> None:
+        if not refresh_token:
+            raise CasaAuthError("refresh_token is required")
+        self._session = session
+        self._refresh_token = refresh_token
+        self._api_key = api_key
+        self._token_url = token_url
+        self._id_token: str | None = None
+        self._expires_at: float = 0.0
+        self._user_id: str | None = None
+        self._lock = asyncio.Lock()
+        self._on_rotated = on_refresh_token_rotated
+
+    @property
+    def refresh_token(self) -> str:
+        """The current refresh token, possibly rotated by Firebase."""
+        return self._refresh_token
+
+    @property
+    def user_id(self) -> str | None:
+        """Firebase uid, known after the first refresh."""
+        return self._user_id
+
+    def _token_is_fresh(self) -> bool:
+        return (
+            self._id_token is not None
+            and self._expires_at - time.monotonic() > TOKEN_REFRESH_LEEWAY_SECONDS
+        )
+
+    async def get_id_token(self) -> str:
+        """Return a valid ID token, refreshing if it expires within the leeway."""
+        if self._token_is_fresh():
+            assert self._id_token is not None
+            return self._id_token
+        async with self._lock:
+            if not self._token_is_fresh():
+                await self._refresh_locked()
+            assert self._id_token is not None
+            return self._id_token
+
+    def invalidate(self, token: str | None = None) -> None:
+        """Drop the cached ID token so the next call refreshes.
+
+        Pass the token that was rejected. If another request already replaced
+        it, this is a no-op, so a burst of concurrent 401s costs one refresh.
+        """
+        if token is not None and token != self._id_token:
+            return
+        self._id_token = None
+        self._expires_at = 0.0
+
+    async def refresh(self) -> TokenResponse:
+        """Force a refresh regardless of cached token state."""
+        async with self._lock:
+            return await self._refresh_locked()
+
+    async def _refresh_locked(self) -> TokenResponse:
+        _LOGGER.debug("Refreshing Firebase ID token")
+        headers = {
+            "X-Ios-Bundle-Identifier": FIREBASE_BUNDLE_ID,
+            "X-Firebase-GMPID": FIREBASE_GMP_ID,
+            "X-Client-Version": FIREBASE_CLIENT_VERSION,
+        }
+        data = {"grant_type": "refresh_token", "refresh_token": self._refresh_token}
+        async with (
+            wrap_connection_errors(),
+            self._session.post(
+                self._token_url,
+                params={"key": self._api_key},
+                data=data,
+                headers=headers,
+                timeout=aiohttp.ClientTimeout(total=DEFAULT_TIMEOUT_SECONDS),
+            ) as resp,
+        ):
+            text = await resp.text()
+            if resp.status >= 400:
+                raise _auth_error(resp.status, text)
+            try:
+                token = TokenResponse.model_validate_json(text)
+            except ValidationError as err:
+                # A 200 that isn't a token response is a proxy or portal, not a bad credential.
+                raise CasaConnectionError(
+                    f"Token endpoint returned an unexpected body: {text[:200]}"
+                ) from err
+
+        self._id_token = token.id_token
+        previous = self._refresh_token
+        self._refresh_token = token.refresh_token or self._refresh_token
+        self._user_id = token.user_id
+        try:
+            lifetime = int(token.expires_in)
+        except ValueError:
+            lifetime = 3600
+        self._expires_at = time.monotonic() + lifetime
+        if self._refresh_token != previous and self._on_rotated is not None:
+            await self._notify_rotated(self._refresh_token)
+        return token
+
+    async def _notify_rotated(self, new_token: str) -> None:
+        """Run the rotation callback. Its failures are logged, never raised.
+
+        Auth already succeeded at this point. A broken persistence hook must
+        not fail the request that triggered the refresh.
+        """
+        assert self._on_rotated is not None
+        try:
+            result = self._on_rotated(new_token)
+            if result is not None:
+                await result
+        except Exception:
+            _LOGGER.exception("on_refresh_token_rotated callback failed; new token not persisted")
+
+
+def _auth_error(status: int, body: str) -> CasaError:
+    """Map a token endpoint failure.
+
+    Only 4xx means the credential itself is bad. 5xx is Google having a bad
+    day and must not trigger reauth in Home Assistant.
+    """
+    message = ""
+    try:
+        payload = json.loads(body)
+        error = payload.get("error", {})
+        message = error.get("message", "") if isinstance(error, dict) else str(error)
+    except (ValueError, AttributeError):
+        pass
+    if message in _FATAL_REFRESH_ERRORS:
+        return CasaAuthError(message)
+    excerpt = message or body[:200]
+    if status >= 500 or status == 429:
+        return CasaConnectionError(f"Token endpoint unavailable (HTTP {status}): {excerpt}")
+    return CasaAuthError(f"Token refresh failed (HTTP {status}): {excerpt}")

casahome/client.py

@@ -0,0 +1,168 @@
+"""Low-level authenticated HTTP client for the Casa foundation API."""
+
+from __future__ import annotations
+
+import json as jsonlib
+import logging
+from collections.abc import AsyncIterator, Mapping
+from contextlib import asynccontextmanager
+from typing import Any
+
+import aiohttp
+
+from ._base_http import wrap_connection_errors
+from .auth import FirebaseAuth
+from .const import (
+    CASA_APP,
+    CASA_APP_VERSION,
+    DEFAULT_TIMEOUT_SECONDS,
+    FOUNDATION_BASE_URL,
+    USER_AGENT,
+)
+from .exceptions import CasaApiError, CasaAuthError
+
+_LOGGER = logging.getLogger("casahome")
+
+
+class CasaClient:
+    """Sends authenticated requests and turns Casa error envelopes into exceptions.
+
+    The client never owns the aiohttp session. Callers create and close it, which
+    is what Home Assistant expects. For scripts, use :meth:`create`.
+    """
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        auth: FirebaseAuth,
+        *,
+        base_url: str = FOUNDATION_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        self._session = session
+        self.auth = auth
+        self._base_url = base_url.rstrip("/")
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+
+    @classmethod
+    @asynccontextmanager
+    async def create(
+        cls,
+        refresh_token: str,
+        *,
+        base_url: str = FOUNDATION_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> AsyncIterator[CasaClient]:
+        """Build a client with its own session. Convenience for scripts."""
+        async with aiohttp.ClientSession() as session:
+            auth = FirebaseAuth(session, refresh_token)
+            yield cls(session, auth, base_url=base_url, timeout=timeout)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: Mapping[str, str] | None = None,
+        retry_on_401: bool | None = None,
+    ) -> Any:
+        """Send a request and return decoded JSON (or None for empty bodies).
+
+        ``retry_on_401`` defaults to True for GET only. Writes (POST, PATCH,
+        DELETE) default to a single attempt: a 401 after the server may have
+        acted would turn a retry into a duplicate write. Non-retrying requests
+        start with a force-refreshed ID token instead, so an expiring token
+        can't trigger the 401 in the first place. A 401 still invalidates the
+        rejected token and raises ``CasaAuthError``.
+
+        Non-GET error bodies never fall back to raw response text. Only the
+        structured error envelope fields are kept, since a write's error body
+        could echo the private content that was sent.
+        """
+        retry = method == "GET" if retry_on_401 is None else retry_on_401
+        scrub = method != "GET"
+        _LOGGER.debug("%s %s", method, path)
+        if not retry:
+            await self.auth.refresh()
+        status, body, used = await self._send(method, path, json=json, params=params)
+        if status == 401:
+            self.auth.invalidate(used)
+            if not retry:
+                raise CasaAuthError(f"Casa rejected the ID token (HTTP 401) on {method}")
+            _LOGGER.debug("401 on %s %s, refreshing token and retrying once", method, path)
+            status, body, _ = await self._send(method, path, json=json, params=params)
+            if status == 401:
+                raise CasaAuthError("Casa rejected the refreshed token (HTTP 401)")
+
+        if status == 304 or (200 <= status < 300 and not body.strip()):
+            return None
+        if 200 <= status < 300:
+            try:
+                return jsonlib.loads(body)
+            except ValueError:
+                display = "" if scrub else body[:200]
+            # Raised outside the handler so the decode error's context is dropped.
+            raise CasaApiError(status, "invalid_json", display_message=display)
+        raise _api_error(status, body, raw_fallback=not scrub)
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None,
+        params: Mapping[str, str] | None,
+    ) -> tuple[int, str, str]:
+        token = await self.auth.get_id_token()
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "X-Casa-App": CASA_APP,
+            "X-Casa-App-Version": CASA_APP_VERSION,
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+        }
+        kwargs: dict[str, Any] = {"headers": headers, "timeout": self._timeout}
+        if json is not None:
+            headers["Content-Type"] = "application/json"
+            kwargs["data"] = jsonlib.dumps(json)
+        if params:
+            kwargs["params"] = dict(params)
+        url = self._base_url + path
+        async with (
+            wrap_connection_errors(),
+            self._session.request(method, url, **kwargs) as resp,
+        ):
+            return resp.status, await resp.text(), token
+
+    async def get(self, path: str, *, params: Mapping[str, str] | None = None) -> Any:
+        return await self.request("GET", path, params=params)
+
+    async def post(self, path: str, *, json: Any | None = None, retry_on_401: bool = False) -> Any:
+        return await self.request("POST", path, json=json, retry_on_401=retry_on_401)
+
+    async def patch(self, path: str, *, json: Any | None = None) -> Any:
+        return await self.request("PATCH", path, json=json, retry_on_401=False)
+
+    async def delete(self, path: str) -> Any:
+        return await self.request("DELETE", path, retry_on_401=False)
+
+
+def _api_error(status: int, body: str, *, raw_fallback: bool = True) -> CasaApiError:
+    try:
+        payload = jsonlib.loads(body)
+    except ValueError:
+        payload = None
+    if isinstance(payload, dict) and isinstance(payload.get("error"), dict):
+        err = payload["error"]
+        return CasaApiError(
+            status,
+            str(err.get("code", "unknown")),
+            str(err.get("displayTitle", "")),
+            str(err.get("displayMessage", "")),
+            str(err.get("requestId", "")),
+        )
+    if isinstance(payload, dict) and isinstance(payload.get("error"), str):
+        # Second observed shape: {"error": "Invalid user device info"}
+        return CasaApiError(status, "unknown", display_message=payload["error"])
+    return CasaApiError(status, "unknown", display_message=body[:500] if raw_fallback else "")

casahome/const.py

@@ -0,0 +1,34 @@
+"""Constants observed in Casa iOS app traffic and bundle metadata."""
+
+from __future__ import annotations
+
+FOUNDATION_BASE_URL = "https://foundation.platform.casa"
+UTILITY_CONNECT_BASE_URL = "https://utility-connect.platform.casa"  # not used yet
+
+# Firebase project the app authenticates against. The API key is a public client
+# identifier shipped inside the iOS bundle (GoogleService-Info.plist), not a secret.
+FIREBASE_API_KEY = "AIzaSyA4XygCbi-oW1M8lP5z51NSX19O2AX2j14"
+FIREBASE_PROJECT_ID = "casa-technologies-inc"
+FIREBASE_GMP_ID = "1:312296672090:ios:5a8ecec7caa297a05b4163"
+FIREBASE_BUNDLE_ID = "casa-technologies.member-ios"
+FIREBASE_CLIENT_VERSION = "iOS/FirebaseSDK/12.18.0/FirebaseCore-iOS"
+SECURETOKEN_URL = "https://securetoken.googleapis.com/v1/token"
+
+# App identity headers the Casa backend expects.
+CASA_APP = "member-ios"
+# The bootstrap body spells it with an underscore. Header uses a dash. Both VERIFIED.
+CASA_DEVICE_APP = "member_ios"
+CASA_APP_VERSION = "698"
+# Same build as an integer. The app sends it as the feed's ``app_build`` and
+# release notes' ``currentBuild`` query values (CFBundleVersion parsed as Int32).
+CASA_APP_BUILD = int(CASA_APP_VERSION)
+# The app's Int32 ceiling, also its fallback when the bundle build is missing.
+MAX_APP_BUILD = 2_147_483_647
+APP_MARKETING_VERSION = "2026.38.2"
+USER_AGENT = (
+    f"Casa/{APP_MARKETING_VERSION} ({FIREBASE_BUNDLE_ID}; build:{CASA_APP_VERSION}; "
+    "iOS 27.0.0) Alamofire/5.12.0"
+)
+
+TOKEN_REFRESH_LEEWAY_SECONDS = 120
+DEFAULT_TIMEOUT_SECONDS = 30

casahome/exceptions.py

@@ -0,0 +1,52 @@
+"""Exception hierarchy for python-casahome."""
+
+from __future__ import annotations
+
+
+class CasaError(Exception):
+    """Base class for all library errors."""
+
+
+class CasaAuthError(CasaError):
+    """Authentication failed or the refresh token is no longer valid."""
+
+
+class CasaConnectionError(CasaError):
+    """Network failure or timeout talking to Casa or Firebase."""
+
+
+class CasaResponseError(CasaError):
+    """Casa answered, but the body didn't match the expected schema.
+
+    Usually means Casa changed a response shape. ``__cause__`` carries the
+    underlying pydantic ValidationError.
+    """
+
+
+class CasaRequestError(CasaError, ValueError):
+    """A write body failed validation before any I/O.
+
+    The message carries only the model name and error count. Pydantic's own
+    error would echo the rejected input, which can be private message text.
+    Subclasses ``ValueError`` so existing ``except ValueError`` callers still work.
+    """
+
+
+class CasaApiError(CasaError):
+    """Casa returned a non-success response."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        display_title: str = "",
+        display_message: str = "",
+        request_id: str = "",
+    ) -> None:
+        self.status = status
+        self.code = code
+        self.display_title = display_title
+        self.display_message = display_message
+        self.request_id = request_id
+        detail = display_message or display_title or code
+        super().__init__(f"HTTP {status} [{code}] {detail}".strip())