cradlewise-client 0.1.0__py3-none-any.whl

cradlewise_client/__init__.py

@@ -0,0 +1,57 @@
+"""Lightweight clients for Cradlewise local and cloud transports."""
+
+from .certificates import (
+    BrokerCertificateError,
+    materialize_credentials,
+    pin_server_ca,
+    validate_server_chain,
+)
+from .cloud import (
+    CloudAccountClient,
+    CloudApiError,
+    CloudAuthenticationError,
+    CloudProvisioningError,
+    CradleAccount,
+    ProvisionedCredentials,
+)
+from .commands import (
+    CommandError,
+    CommandUnavailable,
+    CradlewiseCommandHandler,
+    build_desired,
+    shadow_payload,
+)
+from .local import (
+    LocalConnectionError,
+    LocalCradleClient,
+    LocalCradleUpdate,
+    LocalCredentials,
+)
+from .remote import REMOTE_MQTT_ENDPOINT, RemoteCradleClient
+from .state import CradlewiseStateStore, normalize_device_state
+
+__all__ = [
+    "CommandError",
+    "CommandUnavailable",
+    "CloudAccountClient",
+    "CloudApiError",
+    "CloudAuthenticationError",
+    "CloudProvisioningError",
+    "BrokerCertificateError",
+    "CradleAccount",
+    "CradlewiseCommandHandler",
+    "LocalConnectionError",
+    "LocalCradleClient",
+    "LocalCradleUpdate",
+    "LocalCredentials",
+    "REMOTE_MQTT_ENDPOINT",
+    "RemoteCradleClient",
+    "ProvisionedCredentials",
+    "CradlewiseStateStore",
+    "normalize_device_state",
+    "materialize_credentials",
+    "pin_server_ca",
+    "build_desired",
+    "shadow_payload",
+    "validate_server_chain",
+]

cradlewise_client/certificates.py

@@ -0,0 +1,214 @@
+"""Safe broker certificate discovery and credential materialization."""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+import ssl
+from datetime import datetime, timezone
+from pathlib import Path
+
+from cryptography import x509
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.x509.oid import NameOID
+
+from .cloud import ProvisionedCredentials
+from .local import MQTT_PORT, LocalCredentials
+
+MQTT_BROKER_COMMON_NAME = "aws.greengrass.clientdevices.mqtt.Moquette"
+MQTT_CA_COMMON_NAME = "Greengrass Core CA"
+
+
+class BrokerCertificateError(RuntimeError):
+    """Raised when the local broker chain cannot be safely pinned."""
+
+
+def fetch_server_chain(
+    host: str,
+    client_certificate_path: Path,
+    client_private_key_path: Path,
+    *,
+    port: int = MQTT_PORT,
+) -> list[bytes]:
+    """Fetch the untrusted broker chain using the provisioned client identity."""
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.minimum_version = ssl.TLSVersion.TLSv1_2
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    context.load_cert_chain(client_certificate_path, client_private_key_path)
+    try:
+        with socket.create_connection((host, port), timeout=10) as raw_socket:
+            with context.wrap_socket(raw_socket, server_hostname=host) as tls_socket:
+                chain = _unverified_chain(tls_socket)
+    except BrokerCertificateError:
+        raise
+    except (OSError, ssl.SSLError) as exc:
+        raise BrokerCertificateError(
+            f"could not inspect local MQTT broker TLS: {exc}"
+        ) from exc
+    if len(chain) < 2:
+        raise BrokerCertificateError(
+            "local MQTT broker did not return a certificate chain"
+        )
+    return chain
+
+
+def validate_server_chain(
+    certificate_data: list[bytes],
+    host: str,
+    *,
+    now: datetime | None = None,
+) -> x509.Certificate:
+    """Validate the expected Greengrass broker shape before trusting its CA."""
+    certificates = [_load_certificate(value) for value in certificate_data]
+    leaf = certificates[0]
+    issuers = [
+        certificate
+        for certificate in certificates[1:]
+        if certificate.subject == leaf.issuer
+    ]
+    if len(issuers) != 1:
+        raise BrokerCertificateError(
+            "local MQTT broker chain has no unique issuer for its leaf"
+        )
+    ca = issuers[0]
+    if _common_name(leaf) != MQTT_BROKER_COMMON_NAME:
+        raise BrokerCertificateError(
+            "local MQTT broker certificate has an unexpected common name"
+        )
+    if _common_name(ca) != MQTT_CA_COMMON_NAME or ca.subject != ca.issuer:
+        raise BrokerCertificateError(
+            "local MQTT broker issuer is not a self-issued Greengrass Core CA"
+        )
+    try:
+        constraints = ca.extensions.get_extension_for_class(x509.BasicConstraints)
+    except x509.ExtensionNotFound as exc:
+        raise BrokerCertificateError(
+            "Greengrass Core CA is missing basic constraints"
+        ) from exc
+    if not constraints.value.ca:
+        raise BrokerCertificateError(
+            "Greengrass Core CA certificate is not marked as a CA"
+        )
+
+    current = now or datetime.now(timezone.utc)
+    for certificate in (leaf, ca):
+        if not (
+            certificate.not_valid_before_utc
+            <= current
+            <= certificate.not_valid_after_utc
+        ):
+            raise BrokerCertificateError(
+                "local MQTT broker chain contains an expired or future certificate"
+            )
+    try:
+        leaf.verify_directly_issued_by(ca)
+        ca.verify_directly_issued_by(ca)
+    except (InvalidSignature, ValueError, TypeError) as exc:
+        raise BrokerCertificateError(
+            "local MQTT broker chain signature validation failed"
+        ) from exc
+
+    try:
+        alternative_names = leaf.extensions.get_extension_for_class(
+            x509.SubjectAlternativeName
+        ).value
+    except x509.ExtensionNotFound as exc:
+        raise BrokerCertificateError(
+            "local MQTT broker certificate has no subject alternative name"
+        ) from exc
+    try:
+        expected_ip = ipaddress.ip_address(host)
+    except ValueError:
+        valid_host = host in alternative_names.get_values_for_type(x509.DNSName)
+    else:
+        valid_host = expected_ip in alternative_names.get_values_for_type(
+            x509.IPAddress
+        )
+    if not valid_host:
+        raise BrokerCertificateError(
+            f"local MQTT broker certificate is not valid for {host}"
+        )
+    return ca
+
+
+def pin_server_ca(
+    host: str,
+    client_certificate_path: Path,
+    client_private_key_path: Path,
+) -> str:
+    """Fetch, validate, and return the crib's current broker CA as PEM."""
+    chain = fetch_server_chain(
+        host,
+        client_certificate_path,
+        client_private_key_path,
+    )
+    ca = validate_server_chain(chain, host)
+    return ca.public_bytes(serialization.Encoding.PEM).decode("ascii")
+
+
+def materialize_credentials(
+    directory: Path,
+    credentials: ProvisionedCredentials,
+    *,
+    server_ca_certificate: str | None = None,
+) -> LocalCredentials:
+    """Write one runtime-only credential bundle for Paho MQTT."""
+    directory.mkdir(parents=True, exist_ok=True)
+    directory.chmod(0o700)
+    values = {
+        "ca.pem": credentials.group_ca_certificate,
+        "client_cert.pem": credentials.client_certificate,
+        "client_key.pem": credentials.client_private_key,
+        "device_id": credentials.device_id,
+    }
+    if server_ca_certificate is not None:
+        values["server_ca.pem"] = server_ca_certificate
+    for name, value in values.items():
+        path = directory / name
+        path.write_text(value, encoding="utf-8")
+        path.chmod(0o600)
+    return LocalCredentials.from_directory(directory)
+
+
+def _load_certificate(value: bytes) -> x509.Certificate:
+    if value.startswith(b"-----BEGIN"):
+        return x509.load_pem_x509_certificate(value)
+    return x509.load_der_x509_certificate(value)
+
+
+def _unverified_chain(tls_socket: ssl.SSLSocket) -> list[bytes]:
+    """Return the peer chain across supported Python SSL API versions."""
+    get_chain = getattr(tls_socket, "get_unverified_chain", None)
+    if get_chain is None:
+        ssl_object = getattr(tls_socket, "_sslobj", None)
+        get_chain = getattr(ssl_object, "get_unverified_chain", None)
+    if get_chain is None:
+        raise BrokerCertificateError(
+            "Python does not support retrieving the broker chain"
+        )
+    return [_certificate_bytes(certificate) for certificate in get_chain()]
+
+
+def _certificate_bytes(certificate: object) -> bytes:
+    if isinstance(certificate, bytes):
+        return certificate
+    public_bytes = getattr(certificate, "public_bytes", None)
+    if public_bytes is None:
+        raise BrokerCertificateError(
+            "Python returned an unsupported broker certificate object"
+        )
+    value = public_bytes()
+    if isinstance(value, str):
+        return value.encode("ascii")
+    if isinstance(value, bytes):
+        return value
+    raise BrokerCertificateError(
+        "Python returned an unsupported broker certificate encoding"
+    )
+
+
+def _common_name(certificate: x509.Certificate) -> str | None:
+    values = certificate.subject.get_attributes_for_oid(NameOID.COMMON_NAME)
+    return values[0].value if values else None

cradlewise_client/cloud.py

@@ -0,0 +1,421 @@
+"""Cradlewise account discovery and certificate provisioning."""
+
+from __future__ import annotations
+
+import datetime
+import json
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import boto3
+import requests
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+from botocore.credentials import Credentials
+from botocore.exceptions import BotoCoreError, ClientError
+from pycognito import Cognito
+
+USER_POOL_ID = "us-east-1_hRGLsOxun"
+CLIENT_ID = "4jnn2bbtroa3e6ra73dc8m8luh"
+# Public native-app configuration embedded in the distributed Android APK.
+# This is not an account credential and cannot be kept confidential by a
+# mobile client.
+CLIENT_SECRET = "qfmc9tv70upcacajmhpl4a9n3orehteo93icbng0fljkt6916em"
+IDENTITY_POOL_ID = "us-east-1:53b70db5-7440-4ecf-8dac-d6202eb6c1d2"
+REGION = "us-east-1"
+API_ENDPOINT = "https://backend.cradlewise.com/prod-latest"
+S3_BUCKET = "cradlewise-device-certs"
+REQUEST_TIMEOUT_SECONDS = 10
+
+
+class CloudAuthenticationError(RuntimeError):
+    """Raised when account credentials cannot be authenticated."""
+
+
+class CloudApiError(RuntimeError):
+    """Raised when a Cradlewise cloud request fails."""
+
+
+class CloudProvisioningError(CloudApiError):
+    """Raised when device certificates cannot be provisioned."""
+
+
+@dataclass(frozen=True)
+class CradleAccount:
+    """One baby profile and its associated cradle."""
+
+    baby_id: int
+    cradle_id: str
+    name: str
+
+
+@dataclass(frozen=True)
+class ProvisionedCredentials:
+    """PEM material returned for local and AWS IoT MQTT connections."""
+
+    device_id: str
+    client_certificate: str
+    client_private_key: str
+    group_ca_certificate: str
+
+
+def sign_request(
+    method: str,
+    url: str,
+    credentials: Credentials,
+    *,
+    body: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Sign one Cradlewise API request with temporary AWS credentials."""
+    request = AWSRequest(
+        method=method,
+        url=url,
+        data=body,
+        headers=headers or {},
+    )
+    SigV4Auth(credentials, "execute-api", REGION).add_auth(request)
+    return dict(request.headers)
+
+
+class CloudAccountClient:
+    """Blocking account client intended for an executor in async consumers."""
+
+    def __init__(
+        self,
+        *,
+        email: str,
+        password: str,
+        session: requests.Session | None = None,
+    ) -> None:
+        if not email.strip() or not password:
+            raise CloudAuthenticationError("email and password are required")
+        self.email = email.strip()
+        self._password = password
+        self._session = session or requests.Session()
+        self._credentials: Credentials | None = None
+        self._raw_credentials: dict[str, Any] | None = None
+
+    def authenticate(self) -> None:
+        """Authenticate with Cognito and cache temporary AWS credentials."""
+        try:
+            cognito = Cognito(
+                USER_POOL_ID,
+                CLIENT_ID,
+                username=self.email,
+                client_secret=CLIENT_SECRET,
+            )
+            cognito.authenticate(password=self._password)
+            if not cognito.id_token:
+                raise CloudAuthenticationError(
+                    "Cradlewise authentication returned no ID token"
+                )
+            identity = boto3.client("cognito-identity", region_name=REGION)
+            logins = {
+                f"cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}": (cognito.id_token)
+            }
+            identity_response = identity.get_id(
+                IdentityPoolId=IDENTITY_POOL_ID,
+                Logins=logins,
+            )
+            credentials_response = identity.get_credentials_for_identity(
+                IdentityId=identity_response["IdentityId"],
+                Logins=logins,
+            )
+            raw = credentials_response["Credentials"]
+            self._credentials = Credentials(
+                access_key=raw["AccessKeyId"],
+                secret_key=raw["SecretKey"],
+                token=raw["SessionToken"],
+            )
+            self._raw_credentials = raw
+        except CloudAuthenticationError:
+            raise
+        except ClientError as exc:
+            error = exc.response.get("Error", {})
+            if error.get("Code") in {
+                "NotAuthorizedException",
+                "PasswordResetRequiredException",
+                "UserNotConfirmedException",
+                "UserNotFoundException",
+            }:
+                raise CloudAuthenticationError(
+                    "Cradlewise account authentication failed"
+                ) from exc
+            raise CloudApiError(
+                "Cradlewise authentication service is unavailable"
+            ) from exc
+        except (BotoCoreError, requests.RequestException, OSError) as exc:
+            raise CloudApiError(
+                "Cradlewise authentication service is unavailable"
+            ) from exc
+        except Exception as exc:
+            raise CloudAuthenticationError(
+                "Cradlewise account authentication failed"
+            ) from exc
+
+    def list_accounts(self) -> list[CradleAccount]:
+        """List paired cradle profiles for the authenticated account."""
+        payload = self._request_json(
+            "GET",
+            f"{API_ENDPOINT}/accounts?emailId={quote(self.email)}",
+        )
+        accounts = payload.get("accounts")
+        if not isinstance(accounts, list):
+            raise CloudApiError("Cradlewise accounts response has no account list")
+        result = []
+        for account in accounts:
+            if not isinstance(account, dict) or not account.get("cradle_id"):
+                continue
+            try:
+                baby_id = int(account["baby_id"])
+            except (KeyError, TypeError, ValueError):
+                continue
+            result.append(
+                CradleAccount(
+                    baby_id=baby_id,
+                    cradle_id=str(account["cradle_id"]).strip(),
+                    name=str(account.get("name") or "Cradlewise"),
+                )
+            )
+        return result
+
+    def get_cradle_state(self, cradle_id: str) -> dict[str, Any]:
+        """Fetch the cloud shadow state through the Cradlewise REST API."""
+        return self._request_json(
+            "GET",
+            f"{API_ENDPOINT}/cradles/{cradle_id}/state",
+        )
+
+    def get_cradle_ip(self, cradle_id: str) -> str | None:
+        """Resolve the last reported local address, preferring onlineStatus v2."""
+        v2_error: CloudApiError | None = None
+        try:
+            payload = self._request_json(
+                "GET",
+                f"{API_ENDPOINT}/cradles/{cradle_id}/onlineStatus/v2",
+            )
+            state_message = payload.get("state_message")
+            if isinstance(state_message, str):
+                parsed = json.loads(state_message)
+                address = _local_ip(parsed)
+                if address:
+                    return address
+        except (CloudApiError, json.JSONDecodeError, TypeError) as exc:
+            v2_error = (
+                exc
+                if isinstance(exc, CloudApiError)
+                else CloudApiError("invalid onlineStatus v2 state message")
+            )
+
+        try:
+            payload = self._request_json(
+                "GET",
+                f"{API_ENDPOINT}/cradles/{cradle_id}/onlineStatus",
+            )
+            address = payload.get("local_ip")
+            return (
+                address.strip()
+                if isinstance(address, str) and address.strip()
+                else None
+            )
+        except CloudApiError as exc:
+            if v2_error is not None:
+                raise CloudApiError(
+                    f"Cradlewise online status failed: v2={v2_error}; v1={exc}"
+                ) from exc
+            raise
+
+    def provision_credentials(
+        self,
+        account: CradleAccount,
+        *,
+        app_version: str = "2.55.5",
+        timezone: str = "UTC",
+        country: str = "US",
+    ) -> ProvisionedCredentials:
+        """Register a Home Assistant client and download its MQTT certificate."""
+        body = json.dumps(
+            {
+                "email_id": self.email,
+                "baby_id": account.baby_id,
+                "fcm_token": "home_assistant",
+                "device": {
+                    "registration_date": datetime.date.today().isoformat(),
+                    "app_version": app_version,
+                    "country": country,
+                    "os": "android",
+                    "device_name": "Home Assistant",
+                    "os_version": "14",
+                    "timezone": timezone,
+                    "type": "phone",
+                    "resolution": "{1440,3120}",
+                },
+            },
+            separators=(",", ":"),
+        )
+        payload = self._request_json(
+            "POST",
+            f"{API_ENDPOINT}/cradles/pairedUsers/v3",
+            body=body,
+            headers={"Content-Type": "application/json"},
+        )
+        if payload.get("errorType") == "API_FAILED":
+            raise CloudProvisioningError(
+                str(payload.get("message") or "certificate provisioning failed")
+            )
+        device_config = payload.get("device_config")
+        if not isinstance(device_config, dict):
+            raise CloudProvisioningError(
+                "Cradlewise certificate response has no device configuration"
+            )
+        group_ca = device_config.get("group_ca_cert")
+        object_keys = device_config.get("s3_object_keys")
+        if not isinstance(group_ca, str) or not group_ca.strip():
+            raise CloudProvisioningError(
+                "Cradlewise certificate response has no group CA"
+            )
+        if not isinstance(object_keys, list) or not object_keys:
+            raise CloudProvisioningError(
+                "Cradlewise certificate response has no certificate objects"
+            )
+
+        raw = self._require_raw_credentials()
+        s3 = boto3.client(
+            "s3",
+            region_name=REGION,
+            aws_access_key_id=raw["AccessKeyId"],
+            aws_secret_access_key=raw["SecretKey"],
+            aws_session_token=raw["SessionToken"],
+        )
+        pem_objects = [self._download_s3_text(s3, str(key)) for key in object_keys]
+        client_certificate = next(
+            (value for value in pem_objects if "BEGIN CERTIFICATE" in value),
+            None,
+        )
+        private_key = next(
+            (value for value in pem_objects if "PRIVATE KEY" in value),
+            None,
+        )
+        if client_certificate is None or private_key is None:
+            raise CloudProvisioningError(
+                "Cradlewise certificate objects did not contain a certificate and key"
+            )
+
+        device_id = device_config.get("device_id")
+        if not isinstance(device_id, str) or not device_id.strip():
+            first_key = str(object_keys[0])
+            device_id = first_key.rsplit("/", 1)[-1].removesuffix(".pem")
+        if not device_id:
+            raise CloudProvisioningError(
+                "Cradlewise certificate response has no device identity"
+            )
+        return ProvisionedCredentials(
+            device_id=device_id.strip(),
+            client_certificate=client_certificate,
+            client_private_key=private_key,
+            group_ca_certificate=group_ca,
+        )
+
+    def _request_json(
+        self,
+        method: str,
+        url: str,
+        *,
+        body: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        credentials = self._require_credentials()
+        response = self._send(method, url, credentials, body=body, headers=headers)
+        if response.status_code in {401, 403}:
+            self.authenticate()
+            credentials = self._require_credentials()
+            response = self._send(
+                method,
+                url,
+                credentials,
+                body=body,
+                headers=headers,
+            )
+        try:
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            raise CloudApiError(
+                f"Cradlewise cloud request failed: HTTP {response.status_code}"
+            ) from exc
+        try:
+            payload = response.json()
+        except requests.JSONDecodeError as exc:
+            raise CloudApiError("Cradlewise cloud response was not JSON") from exc
+        if not isinstance(payload, dict):
+            raise CloudApiError("Cradlewise cloud response was not an object")
+        return payload
+
+    def _send(
+        self,
+        method: str,
+        url: str,
+        credentials: Credentials,
+        *,
+        body: str | None,
+        headers: dict[str, str] | None,
+    ) -> requests.Response:
+        signed_headers = sign_request(
+            method,
+            url,
+            credentials,
+            body=body,
+            headers=headers,
+        )
+        try:
+            return self._session.request(
+                method,
+                url,
+                headers=signed_headers,
+                data=body,
+                timeout=REQUEST_TIMEOUT_SECONDS,
+            )
+        except requests.RequestException as exc:
+            raise CloudApiError("Cradlewise cloud request failed") from exc
+
+    def _require_credentials(self) -> Credentials:
+        if self._credentials is None:
+            self.authenticate()
+        if self._credentials is None:
+            raise CloudAuthenticationError(
+                "Cradlewise authentication returned no AWS credentials"
+            )
+        return self._credentials
+
+    def _require_raw_credentials(self) -> dict[str, Any]:
+        self._require_credentials()
+        if self._raw_credentials is None:
+            raise CloudAuthenticationError(
+                "Cradlewise authentication returned no raw AWS credentials"
+            )
+        return self._raw_credentials
+
+    @staticmethod
+    def _download_s3_text(s3: Any, key: str) -> str:
+        errors = []
+        for candidate in (key, f"public/{key}"):
+            try:
+                response = s3.get_object(Bucket=S3_BUCKET, Key=candidate)
+                value = response["Body"].read().decode("utf-8")
+                if value.strip():
+                    return value
+            except Exception as exc:
+                errors.append(exc)
+        raise CloudProvisioningError(
+            f"could not download provisioned certificate object {key}"
+        ) from errors[-1]
+
+
+def _local_ip(payload: dict[str, Any]) -> str | None:
+    address = (
+        payload.get("info", {}).get("connectivity", {}).get("localIP")
+        if isinstance(payload.get("info"), dict)
+        else None
+    )
+    return address.strip() if isinstance(address, str) and address.strip() else None