place-integration-api 0.1.0__tar.gz

place_integration_api-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Gentex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

place_integration_api-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: place-integration-api
+Version: 0.1.0
+Summary: Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place.
+Author-email: Nicholas Aelick <niaexa@syntronic.com>, Andrew Tran <andrew.tran@gentex.com>
+License: Proprietary
+Project-URL: Homepage, https://pypi.org/project/place-integration-api/
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3
+Requires-Dist: aiohttp
+Requires-Dist: paho-mqtt
+Requires-Dist: six
+Requires-Dist: python-decouple
+Provides-Extra: dev
+Requires-Dist: basedpyright; extra == "dev"
+Dynamic: license-file
+
+# Place integration API
+
+This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration

place_integration_api-0.1.0/README.md

@@ -0,0 +1,3 @@
+# Place integration API
+
+This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration

place_integration_api-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "place-integration-api"
+version = "0.1.0"
+description = "Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+  { name="Nicholas Aelick", email="niaexa@syntronic.com" },
+  { name="Andrew Tran", email="andrew.tran@gentex.com" },
+]
+license = { text = "Proprietary" }
+dependencies = [
+  "boto3",
+  "aiohttp",
+  "paho-mqtt",
+  "six",
+  "python-decouple"
+]
+
+[project.optional-dependencies]
+dev = [
+  "basedpyright",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/place-integration-api/"
+
+[tool.setuptools.packages.find]
+where = ["src"]

place_integration_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

place_integration_api-0.1.0/src/place/auth/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .srp_auth import login, get_iot_credentials
+
+__all__ = [
+    "login",
+    "get_iot_credentials",
+]
+

place_integration_api-0.1.0/src/place/auth/abstract_auth.py

@@ -0,0 +1,33 @@
+from abc import ABC, abstractmethod
+from aiohttp import ClientSession, ClientResponse
+
+
+class AbstractAuth(ABC):
+    """Abstract class to make authenticated requests."""
+
+    def __init__(self, websession: ClientSession) -> None:
+        """Initialize the auth."""
+        self.websession = websession
+
+    @abstractmethod
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token."""
+
+    async def request(self, method, url, **kwargs) -> ClientResponse:
+        """Make a request."""
+        headers = kwargs.get("headers")
+
+        if headers is None:
+            headers = {}
+        else:
+            headers = dict(headers)
+
+        access_token = await self.async_get_access_token()
+        headers["authorization"] = f"Bearer {access_token}"
+
+        return await self.websession.request(
+            method,
+            url,
+            **kwargs,
+            headers=headers,
+        )

place_integration_api-0.1.0/src/place/auth/aws_srp.py

@@ -0,0 +1,321 @@
+# Taken from https://github.com/capless/warrant/blob/master/warrant/aws_srp.py
+import base64
+import binascii
+import datetime
+import hashlib
+import hmac
+import re
+
+import os
+
+os.environ.setdefault("AWS_SHARED_CREDENTIALS_FILE", os.devnull)
+os.environ.setdefault("AWS_CONFIG_FILE", os.devnull)
+
+import boto3
+from botocore import UNSIGNED
+from botocore.config import Config
+import six
+
+
+class WarrantException(Exception):
+    """Base class for all Warrant exceptions"""
+
+
+class ForceChangePasswordException(WarrantException):
+    """Raised when the user is forced to change their password"""
+
+
+# https://github.com/aws/amazon-cognito-identity-js/blob/master/src/AuthenticationHelper.js#L22
+n_hex = (
+    "FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD1"
+    + "29024E088A67CC74020BBEA63B139B22514A08798E3404DD"
+    + "EF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245"
+    + "E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED"
+    + "EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3D"
+    + "C2007CB8A163BF0598DA48361C55D39A69163FA8FD24CF5F"
+    + "83655D23DCA3AD961C62F356208552BB9ED529077096966D"
+    + "670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B"
+    + "E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9"
+    + "DE2BCBF6955817183995497CEA956AE515D2261898FA0510"
+    + "15728E5A8AAAC42DAD33170D04507A33A85521ABDF1CBA64"
+    + "ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7"
+    + "ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6B"
+    + "F12FFA06D98A0864D87602733EC86A64521F2B18177B200C"
+    + "BBE117577A615D6C770988C0BAD946E208E24FA074E5AB31"
+    + "43DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF"
+)
+# https://github.com/aws/amazon-cognito-identity-js/blob/master/src/AuthenticationHelper.js#L49
+g_hex = "2"
+info_bits = bytearray("Caldera Derived Key", "utf-8")
+
+
+def hash_sha256(buf):
+    """AuthenticationHelper.hash"""
+    a = hashlib.sha256(buf).hexdigest()
+    return (64 - len(a)) * "0" + a
+
+
+def hex_hash(hex_string):
+    return hash_sha256(bytearray.fromhex(hex_string))
+
+
+def hex_to_long(hex_string):
+    return int(hex_string, 16)
+
+
+def long_to_hex(long_num):
+    return "%x" % long_num
+
+
+def get_random(nbytes):
+    random_hex = binascii.hexlify(os.urandom(nbytes))
+    return hex_to_long(random_hex)
+
+
+def pad_hex(long_int):
+    """
+    Converts a Long integer (or hex string) to hex format padded with zeroes for hashing
+    :param {Long integer|String} long_int Number or string to pad.
+    :return {String} Padded hex string.
+    """
+    if not isinstance(long_int, six.string_types):
+        hash_str = long_to_hex(long_int)
+    else:
+        hash_str = long_int
+    if len(hash_str) % 2 == 1:
+        hash_str = "0%s" % hash_str
+    elif hash_str[0] in "89ABCDEFabcdef":
+        hash_str = "00%s" % hash_str
+    return hash_str
+
+
+def compute_hkdf(ikm, salt):
+    """
+    Standard hkdf algorithm
+    :param {Buffer} ikm Input key material.
+    :param {Buffer} salt Salt value.
+    :return {Buffer} Strong key material.
+    @private
+    """
+    prk = hmac.new(salt, ikm, hashlib.sha256).digest()
+    info_bits_update = info_bits + bytearray(chr(1), "utf-8")
+    hmac_hash = hmac.new(prk, info_bits_update, hashlib.sha256).digest()
+    return hmac_hash[:16]
+
+
+def calculate_u(big_a, big_b):
+    """
+    Calculate the client's value U which is the hash of A and B
+    :param {Long integer} big_a Large A value.
+    :param {Long integer} big_b Server B value.
+    :return {Long integer} Computed U value.
+    """
+    u_hex_hash = hex_hash(pad_hex(big_a) + pad_hex(big_b))
+    return hex_to_long(u_hex_hash)
+
+
+class AWSSRP(object):
+
+    NEW_PASSWORD_REQUIRED_CHALLENGE = "NEW_PASSWORD_REQUIRED"
+    PASSWORD_VERIFIER_CHALLENGE = "PASSWORD_VERIFIER"
+
+    def __init__(
+        self,
+        username,
+        password,
+        pool_id,
+        client_id,
+        pool_region=None,
+        client=None,
+        client_secret=None,
+    ):
+        if pool_region is not None and client is not None:
+            raise ValueError(
+                "pool_region and client should not both be specified "
+                "(region should be passed to the boto3 client instead)"
+            )
+
+        self.username = username
+        self.password = password
+        self.pool_id = pool_id
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.client = (
+            client if client else boto3.client(
+                "cognito-idp",
+                region_name=pool_region,
+                config=Config(signature_version=UNSIGNED),
+            )
+        )
+        self.big_n = hex_to_long(n_hex)
+        self.g = hex_to_long(g_hex)
+        self.k = hex_to_long(hex_hash("00" + n_hex + "0" + g_hex))
+        self.small_a_value = self.generate_random_small_a()
+        self.large_a_value = self.calculate_a()
+
+    def generate_random_small_a(self):
+        """
+        helper function to generate a random big integer
+        :return {Long integer} a random value.
+        """
+        random_long_int = get_random(128)
+        return random_long_int % self.big_n
+
+    def calculate_a(self):
+        """
+        Calculate the client's public value A = g^a%N
+        with the generated random number a
+        :param {Long integer} a Randomly generated small A.
+        :return {Long integer} Computed large A.
+        """
+        big_a = pow(self.g, self.small_a_value, self.big_n)
+        # safety check
+        if (big_a % self.big_n) == 0:
+            raise ValueError("Safety check for A failed")
+        return big_a
+
+    def get_password_authentication_key(self, username, password, server_b_value, salt):
+        """
+        Calculates the final hkdf based on computed S value, and computed U value and the key
+        :param {String} username Username.
+        :param {String} password Password.
+        :param {Long integer} server_b_value Server B value.
+        :param {Long integer} salt Generated salt.
+        :return {Buffer} Computed HKDF value.
+        """
+        u_value = calculate_u(self.large_a_value, server_b_value)
+        if u_value == 0:
+            raise ValueError("U cannot be zero.")
+        username_password = "%s%s:%s" % (self.pool_id.split("_")[1], username, password)
+        username_password_hash = hash_sha256(username_password.encode("utf-8"))
+
+        x_value = hex_to_long(hex_hash(pad_hex(salt) + username_password_hash))
+        g_mod_pow_xn = pow(self.g, x_value, self.big_n)
+        int_value2 = server_b_value - self.k * g_mod_pow_xn
+        s_value = pow(int_value2, self.small_a_value + u_value * x_value, self.big_n)
+        hkdf = compute_hkdf(
+            bytearray.fromhex(pad_hex(s_value)),
+            bytearray.fromhex(pad_hex(long_to_hex(u_value))),
+        )
+        return hkdf
+
+    def get_auth_params(self):
+        auth_params = {
+            "USERNAME": self.username,
+            "SRP_A": long_to_hex(self.large_a_value),
+        }
+        if self.client_secret is not None:
+            auth_params.update(
+                {
+                    "SECRET_HASH": self.get_secret_hash(
+                        self.username, self.client_id, self.client_secret
+                    )
+                }
+            )
+        return auth_params
+
+    @staticmethod
+    def get_secret_hash(username, client_id, client_secret):
+        message = bytearray(username + client_id, "utf-8")
+        hmac_obj = hmac.new(bytearray(client_secret, "utf-8"), message, hashlib.sha256)
+        return base64.standard_b64encode(hmac_obj.digest()).decode("utf-8")
+
+    def process_challenge(self, challenge_parameters):
+        user_id_for_srp = challenge_parameters["USER_ID_FOR_SRP"]
+        salt_hex = challenge_parameters["SALT"]
+        srp_b_hex = challenge_parameters["SRP_B"]
+        secret_block_b64 = challenge_parameters["SECRET_BLOCK"]
+        # re strips leading zero from a day number (required by AWS Cognito)
+        timestamp = re.sub(
+            r" 0(\d) ",
+            r" \1 ",
+            datetime.datetime.utcnow().strftime("%a %b %d %H:%M:%S UTC %Y"),
+        )
+        hkdf = self.get_password_authentication_key(
+            user_id_for_srp, self.password, hex_to_long(srp_b_hex), salt_hex
+        )
+        secret_block_bytes = base64.standard_b64decode(secret_block_b64)
+        msg = (
+            bytearray(self.pool_id.split("_")[1], "utf-8")
+            + bytearray(user_id_for_srp, "utf-8")
+            + bytearray(secret_block_bytes)
+            + bytearray(timestamp, "utf-8")
+        )
+        hmac_obj = hmac.new(hkdf, msg, digestmod=hashlib.sha256)
+        signature_string = base64.standard_b64encode(hmac_obj.digest())
+        response = {
+            "TIMESTAMP": timestamp,
+            "USERNAME": user_id_for_srp,
+            "PASSWORD_CLAIM_SECRET_BLOCK": secret_block_b64,
+            "PASSWORD_CLAIM_SIGNATURE": signature_string.decode("utf-8"),
+        }
+        if self.client_secret is not None:
+            response.update(
+                {
+                    "SECRET_HASH": self.get_secret_hash(
+                        self.username, self.client_id, self.client_secret
+                    )
+                }
+            )
+        return response
+
+    def authenticate_user(self, client=None):
+        boto_client = self.client or client
+        auth_params = self.get_auth_params()
+        response = boto_client.initiate_auth(
+            AuthFlow="USER_SRP_AUTH",
+            AuthParameters=auth_params,
+            ClientId=self.client_id,
+        )
+        if response["ChallengeName"] == self.PASSWORD_VERIFIER_CHALLENGE:
+            challenge_response = self.process_challenge(response["ChallengeParameters"])
+            tokens = boto_client.respond_to_auth_challenge(
+                ClientId=self.client_id,
+                ChallengeName=self.PASSWORD_VERIFIER_CHALLENGE,
+                ChallengeResponses=challenge_response,
+            )
+
+            if tokens.get("ChallengeName") == self.NEW_PASSWORD_REQUIRED_CHALLENGE:
+                raise ForceChangePasswordException(
+                    "Change password before authenticating"
+                )
+
+            return tokens
+        else:
+            raise NotImplementedError(
+                "The %s challenge is not supported" % response["ChallengeName"]
+            )
+
+    def set_new_password_challenge(self, new_password, client=None):
+        boto_client = self.client or client
+        auth_params = self.get_auth_params()
+        response = boto_client.initiate_auth(
+            AuthFlow="USER_SRP_AUTH",
+            AuthParameters=auth_params,
+            ClientId=self.client_id,
+        )
+        if response["ChallengeName"] == self.PASSWORD_VERIFIER_CHALLENGE:
+            challenge_response = self.process_challenge(response["ChallengeParameters"])
+            tokens = boto_client.respond_to_auth_challenge(
+                ClientId=self.client_id,
+                ChallengeName=self.PASSWORD_VERIFIER_CHALLENGE,
+                ChallengeResponses=challenge_response,
+            )
+
+            if tokens["ChallengeName"] == self.NEW_PASSWORD_REQUIRED_CHALLENGE:
+                challenge_response = {
+                    "USERNAME": auth_params["USERNAME"],
+                    "NEW_PASSWORD": new_password,
+                }
+                new_password_response = boto_client.respond_to_auth_challenge(
+                    ClientId=self.client_id,
+                    ChallengeName=self.NEW_PASSWORD_REQUIRED_CHALLENGE,
+                    Session=tokens["Session"],
+                    ChallengeResponses=challenge_response,
+                )
+                return new_password_response
+            return tokens
+        else:
+            raise NotImplementedError(
+                "The %s challenge is not supported" % response["ChallengeName"]
+            )

place_integration_api-0.1.0/src/place/auth/srp_auth.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import boto3
+from botocore import UNSIGNED
+from botocore.config import Config
+
+
+from .aws_srp import AWSSRP
+from ..config import REGION, COGNITO_CLIENT_ID, COGNITO_USER_POOL_ID, COGNITO_IDENTITY_POOL_ID
+from ..models import Credentials
+
+
+def login(username: str, password: str) -> Dict[str, Any]:
+    return get_tokens_via_srp(
+        user_pool_id=COGNITO_USER_POOL_ID,
+        client_id=COGNITO_CLIENT_ID,
+        username=username,
+        password=password,
+    )
+
+def get_iot_credentials(id_token: str, access_token: str) -> Credentials:
+    """Exchange a Cognito ID token for AWS IoT credentials."""
+    identity = boto3.client(
+        "cognito-identity",
+        region_name=REGION,
+        config=Config(signature_version=UNSIGNED),
+    )
+    provider_key = f"cognito-idp.{REGION}.amazonaws.com/{COGNITO_USER_POOL_ID}"
+    logins = {provider_key: id_token}
+
+    identity_id = identity.get_id(
+        IdentityPoolId=COGNITO_IDENTITY_POOL_ID, Logins=logins
+    )["IdentityId"]
+
+    creds = identity.get_credentials_for_identity(
+        IdentityId=identity_id, Logins=logins
+    )["Credentials"]
+
+    return Credentials(
+        access_key_id=creds["AccessKeyId"],
+        secret_access_key=creds["SecretKey"],
+        session_token=creds["SessionToken"],
+        identity_id=identity_id,
+        access_token=access_token,
+    )
+
+
+def get_tokens_via_srp(
+    *,
+    user_pool_id: str,
+    client_id: str,
+    username: str,
+    password: str,
+    region: str = REGION,
+    client_secret: str | None = None,
+) -> Dict[str, Any]:
+    aws = AWSSRP(
+        username=username,
+        password=password,
+        pool_id=user_pool_id,
+        client_id=client_id,
+        pool_region=region,
+        client_secret=client_secret,
+    )
+    return aws.authenticate_user()
+
+

place_integration_api-0.1.0/src/place/config.py

@@ -0,0 +1,31 @@
+import decouple
+
+REGION = decouple.config("AWS_REGION", default="us-east-2")
+SERVICE = decouple.config("AWS_SERVICE", default="iotdevicegateway")
+ALGORITHM = decouple.config("AWS_ALGORITHM", default="AWS4-HMAC-SHA256")
+SCHEME = decouple.config("AWS_SCHEME", default="wss")
+PATH = decouple.config("AWS_PATH", default="/mqtt")
+EXPIRE_SEC = decouple.config("AWS_EXPIRE_SEC", default=86400)
+KEEP_ALIVE_SEC = decouple.config("AWS_KEEP_ALIVE_SEC", default=30)
+FULFILLMENT_URL = decouple.config(
+    "AWS_FULFILLMENT_URL",
+    default="https://ymxta4fyrl.execute-api.us-east-2.amazonaws.com/prod/fulfillment",
+)
+# Note: must be the regional IoT endpoint for now. Currently the custom IoT endpoint/domain configuration uses ApplicationProtocol.SECURE_MQTT
+# a second domain configuration must be created for ApplicationProtocol.MQTT_WSS in order to use the custom IoT endpoint instead.
+IOT_ENDPOINT = decouple.config(
+    "AWS_IOT_ENDPOINT", default="a2ksnv5v3x6m50-ats.iot.us-east-2.amazonaws.com"
+)
+COGNITO_USER_POOL_ID = decouple.config(
+    "AWS_COGNITO_USER_POOL_ID", default="us-east-2_LKSPO9tT6"
+)
+COGNITO_CLIENT_ID = decouple.config(
+    "AWS_COGNITO_CLIENT_ID", default="5blr1qf2evvj4ivircqbpqikev"
+)
+COGNITO_IDENTITY_POOL_ID = decouple.config(
+    "AWS_COGNITO_IDENTITY_POOL_ID",
+    default="us-east-2:77c64042-63a1-4126-bdae-bd4150a73ad1",
+)
+OAUTH2_TOKEN_URL = decouple.config(
+    "OAUTH2_TOKEN_URL", default="https://auth.connectedsmoke.com/oauth2/token"
+)

place_integration_api-0.1.0/src/place/messages.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .mqtt_client import MqttClient
+
+
+HOUSEHOLD_PREFIX = "connectedsmoke/household"
+SHADOW_GET_PREFIX = "$aws/things"
+
+
+def parse_payload(raw: bytes) -> dict[str, Any]:
+    if not raw or not raw.strip():
+        return {}
+    try:
+        return json.loads(raw.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return {}
+
+
+def message_kind(topic: str, payload: dict[str, Any]) -> str:
+    checks = [
+        (lambda: "state" in payload and payload.get("state", {}).get("reported") is not None, "shadow"),
+        (lambda: "connectivity" in topic.lower(), "presence"),
+        (lambda: "command/response" in topic, "command"),
+        (lambda: "events/" in topic, "event"),
+        (lambda: topic.startswith("connectedsmoke/household/"), "household"),
+    ]
+    return next((label for pred, label in checks if pred()), "msg")
+
+
+def household_subscription_topic(household_id: str) -> str:
+    return f"{HOUSEHOLD_PREFIX}/{household_id}/#"
+
+
+def shadow_get_topic(thing_name: str) -> str:
+    return f"{SHADOW_GET_PREFIX}/{thing_name}/shadow/get"
+
+
+def shadow_subscription_topic(thing_name: str) -> str:
+    return f"{SHADOW_GET_PREFIX}/{thing_name}/shadow/#"
+
+
+def describe_message(topic: str, raw: bytes) -> str:
+    payload = parse_payload(raw)
+    kind = message_kind(topic, payload)
+    extra = (
+        f" -> reported: {list(payload.get('state', {}).get('reported', {}).keys())}"
+        if kind == "shadow"
+        else f" {payload}"
+        if kind == "msg"
+        else ""
+    )
+    return f"[{kind}] {topic}{extra}"
+
+
+class PlaceMessages:
+    def __init__(self, client: MqttClient):
+        self._client = client
+
+    def subscribe_household(self, household_id: str, qos: int = 1) -> str:
+        hid = household_id.strip()
+        assert hid
+        topic = household_subscription_topic(hid)
+        self._client.subscribe(topic, qos=qos)
+        return hid
+
+    def subscribe_shadow(self, thing_name: str, qos: int = 1) -> str:
+        name = thing_name.strip()
+        assert name
+        topic = shadow_subscription_topic(name)
+        self._client.subscribe(topic, qos=qos)
+        return name
+
+    def publish_shadow_get(self, thing_name: str, qos: int = 1) -> str:
+        name = thing_name.strip()
+        assert name
+        topic = shadow_get_topic(name)
+        self._client.publish(topic, qos=qos)
+        return name
+
+    def describe(self, topic: str, raw: bytes) -> str:
+        return describe_message(topic, raw)
+
+

place_integration_api-0.1.0/src/place/models/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from .credentials import Credentials
+from .discover_device import DiscoverDevice
+from .mqtt_message import MqttMessage
+
+__all__ = [
+    "Credentials",
+    "DiscoverDevice",
+    "MqttMessage",
+]
+

place_integration_api-0.1.0/src/place/models/credentials.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Credentials:
+    access_key_id: str
+    secret_access_key: str
+    session_token: str
+    identity_id: str
+    access_token: str | None = None
+

place_integration_api-0.1.0/src/place/models/discover_device.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+def _as_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _as_bool(value: Any) -> bool | None:
+    if value is None:
+        return None
+    return bool(value)
+
+
+@dataclass
+class DiscoverDevice:
+    location: str | None
+    shadow: dict[str, Any]
+    device_name: str | None
+    thing_name: str | None
+    firmware_version: str | None
+    model_number: str | None
+    device_id: str | None
+    online: bool | None
+
+    @staticmethod
+    def from_dict(data: Mapping[str, Any]) -> DiscoverDevice:
+        return DiscoverDevice(
+            location=_as_str(data.get("location")),
+            shadow=dict(data.get("shadow") or {}),
+            device_name=_as_str(data.get("deviceName")),
+            thing_name=_as_str(data.get("thingName")),
+            firmware_version=_as_str(data.get("firmwareVersion")),
+            model_number=_as_str(data.get("modelNumber")),
+            device_id=_as_str(data.get("deviceId")),
+            online=_as_bool(data.get("online")),
+        )

place_integration_api-0.1.0/src/place/models/models.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .credentials import Credentials
+from .mqtt_message import MqttMessage
+

place_integration_api-0.1.0/src/place/models/mqtt_message.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class MqttMessage:
+    topic: str
+    payload: dict[str, Any]
+

place_integration_api-0.1.0/src/place/mqtt_client.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import uuid
+from datetime import datetime, timezone
+from typing import Callable
+from urllib.parse import quote
+
+import paho.mqtt.client as mqtt
+
+from .config import ALGORITHM, EXPIRE_SEC, KEEP_ALIVE_SEC, PATH, REGION, SCHEME, SERVICE
+from .models import Credentials
+
+
+def _hmac_sha256(key: bytes, msg: str) -> bytes:
+    return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
+
+
+def _sha256_hex(msg: str) -> str:
+    return hashlib.sha256(msg.encode("utf-8")).hexdigest().lower()
+
+
+def _sign(key: bytes, msg: str) -> bytes:
+    return _hmac_sha256(key, msg)
+
+
+def get_signed_uri(
+    *,
+    access_key_id: str,
+    secret_access_key: str,
+    session_token: str,
+    host: str,
+) -> str:
+    now = datetime.now(timezone.utc)
+    date_stamp = now.strftime("%Y%m%d")
+    amz_date = now.strftime("%Y%m%dT%H%M%SZ")
+    credential_scope = f"{access_key_id}/{date_stamp}/{REGION}/{SERVICE}/aws4_request"
+    signed_headers = "host"
+    canonical_headers = f"host:{host}\n"
+    payload_hash = _sha256_hex("")
+
+    def enc(s: str) -> str:
+        return quote(str(s), safe="")
+
+    query = {
+        "X-Amz-Algorithm": ALGORITHM,
+        "X-Amz-Credential": credential_scope,
+        "X-Amz-Date": amz_date,
+        "X-Amz-Expires": str(EXPIRE_SEC),
+        "X-Amz-SignedHeaders": signed_headers,
+    }
+    canonical_query = "&".join(f"{enc(k)}={enc(v)}" for k, v in sorted(query.items()))
+    canonical_request = "\n".join(
+        [
+            "GET",
+            PATH,
+            canonical_query,
+            canonical_headers,
+            signed_headers,
+            payload_hash,
+        ]
+    )
+    request_hash = _sha256_hex(canonical_request)
+    string_to_sign = "\n".join(
+        [
+            ALGORITHM,
+            amz_date,
+            f"{date_stamp}/{REGION}/{SERVICE}/aws4_request",
+            request_hash,
+        ]
+    )
+    k_date = _sign(("AWS4" + secret_access_key).encode("utf-8"), date_stamp)
+    k_region = _sign(k_date, REGION)
+    k_service = _sign(k_region, SERVICE)
+    k_signing = _sign(k_service, "aws4_request")
+    signature = hmac.new(k_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+    query["X-Amz-Signature"] = signature
+    query["X-Amz-Security-Token"] = session_token
+    query_string = "&".join(f"{enc(k)}={enc(v)}" for k, v in sorted(query.items()))
+    return f"{SCHEME}://{host}{PATH}?{query_string}"
+
+
+class MqttClient:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        credentials: Credentials,
+    ):
+        self.endpoint = endpoint
+        self.credentials = credentials
+        self._client: mqtt.Client | None = None
+
+    def connect(
+        self,
+        on_message: Callable[[str, bytes], None] | None = None,
+        on_connect: Callable[[], None] | None = None,
+    ) -> None:
+        signed_uri = get_signed_uri(
+            access_key_id=self.credentials.access_key_id,
+            secret_access_key=self.credentials.secret_access_key,
+            session_token=self.credentials.session_token,
+            host=self.endpoint,
+        )
+        client_id = f"{self.credentials.identity_id}-{uuid.uuid4()}"
+
+        client = mqtt.Client(
+            callback_api_version=mqtt.CallbackAPIVersion.VERSION2,
+            client_id=client_id,
+            transport="websockets",
+            protocol=mqtt.MQTTv311,
+        )
+        path_with_query = "/mqtt" + signed_uri.split("/mqtt", 1)[1]
+        print(f"WebSocket path: {path_with_query[:80]}...")
+        client.ws_set_options(path=path_with_query, headers={"Host": self.endpoint})
+        client.tls_set()
+
+        def _on_connect(_client, _userdata, _flags, reason_code, _properties):
+            if reason_code.is_failure:
+                print(f"Connect failed: {reason_code}")
+                return
+            print("Connected")
+            if on_connect:
+                try:
+                    on_connect()
+                except Exception as exc:
+                    print(f"on_connect error: {exc}")
+
+        def _on_message(_client, _userdata, msg):
+            if on_message:
+                on_message(msg.topic, msg.payload)
+
+        def _on_disconnect(_client, _userdata, _flags, reason_code, _properties):
+            print(f"Disconnected: {reason_code}")
+
+        client.on_connect = _on_connect
+        client.on_message = _on_message
+        client.on_disconnect = _on_disconnect
+        client.enable_logger()
+        client.connect(self.endpoint, 443, KEEP_ALIVE_SEC)
+        self._client = client
+
+    def disconnect(self):
+        if self._client:
+            self._client.loop_stop()
+            self._client.disconnect()
+
+    def subscribe(self, topic: str, qos: int = 1) -> None:
+        assert self._client is not None
+        self._client.subscribe(topic, qos=qos)
+
+    def publish(self, topic: str, payload: str | bytes = b"", qos: int = 1) -> None:
+        assert self._client is not None
+        data = payload.encode("utf-8") if isinstance(payload, str) else payload
+        self._client.publish(topic, data, qos=qos)
+
+    def loop_start(self):
+        assert self._client is not None
+        self._client.loop_start()
+
+    def loop_forever(self) -> None:
+        assert self._client is not None
+        self._client.loop_forever()
+

place_integration_api-0.1.0/src/place/provider.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from .auth.abstract_auth import AbstractAuth
+from .models.discover_device import DiscoverDevice
+from .config import FULFILLMENT_URL
+
+class Provider:
+    def __init__(self, authorized_session: AbstractAuth) -> None:
+        self.authorized_session = authorized_session
+
+
+    async def discover(self) -> list[DiscoverDevice]:
+        body = {"command": "DISCOVER", "data": {}}
+        resp = await self.authorized_session.request("POST", FULFILLMENT_URL, json=body)
+        data = await resp.json()
+        if not data.get("success", True):
+            raise RuntimeError(f"Home Assistant error: {data.get('message', data)}")
+        devices_raw = (data.get("data") or {}).get("devices") or []
+        devices: list[DiscoverDevice] = []
+        for raw in devices_raw:
+            devices.append(DiscoverDevice.from_dict(raw))
+        return devices
+
+    async def enable(self):
+        body = {"command": "ENABLE", "data": {}}
+        resp = await self.authorized_session.request("POST", FULFILLMENT_URL, json=body)
+        data = await resp.json()
+        if not data.get("success", True):
+            raise RuntimeError(f"Home Assistant error: {data.get('message', data)}")
+        return data
+    
+    async def disable(self):
+        body = {"command": "DISABLE", "data": {}}
+        resp = await self.authorized_session.request("POST", FULFILLMENT_URL, json=body)
+        data = await resp.json()
+        if not data.get("success", True):
+            raise RuntimeError(f"Home Assistant error: {data.get('message', data)}")
+        return data

place_integration_api-0.1.0/src/place_integration_api.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: place-integration-api
+Version: 0.1.0
+Summary: Python APIs for Cognito-authenticated MQTT flows and Home Assistant discovery for Gentex Place.
+Author-email: Nicholas Aelick <niaexa@syntronic.com>, Andrew Tran <andrew.tran@gentex.com>
+License: Proprietary
+Project-URL: Homepage, https://pypi.org/project/place-integration-api/
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3
+Requires-Dist: aiohttp
+Requires-Dist: paho-mqtt
+Requires-Dist: six
+Requires-Dist: python-decouple
+Provides-Extra: dev
+Requires-Dist: basedpyright; extra == "dev"
+Dynamic: license-file
+
+# Place integration API
+
+This project contains a python API to connect MQTT data from Place devices to Place's Home Assistant integration

place_integration_api-0.1.0/src/place_integration_api.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+src/place/config.py
+src/place/messages.py
+src/place/mqtt_client.py
+src/place/provider.py
+src/place/auth/__init__.py
+src/place/auth/abstract_auth.py
+src/place/auth/aws_srp.py
+src/place/auth/srp_auth.py
+src/place/models/__init__.py
+src/place/models/credentials.py
+src/place/models/discover_device.py
+src/place/models/models.py
+src/place/models/mqtt_message.py
+src/place_integration_api.egg-info/PKG-INFO
+src/place_integration_api.egg-info/SOURCES.txt
+src/place_integration_api.egg-info/dependency_links.txt
+src/place_integration_api.egg-info/requires.txt
+src/place_integration_api.egg-info/top_level.txt
+tests/test_auth.py
+tests/test_mqtt_client.py
+tests/test_provider.py

place_integration_api-0.1.0/src/place_integration_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

place_integration_api-0.1.0/src/place_integration_api.egg-info/requires.txt

@@ -0,0 +1,8 @@
+boto3
+aiohttp
+paho-mqtt
+six
+python-decouple
+
+[dev]
+basedpyright

place_integration_api-0.1.0/src/place_integration_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+place

place_integration_api-0.1.0/tests/test_auth.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from place_integration_api.auth import get_credentials_via_cognito
+
+
+@patch("place_integration_api.auth.srp_auth.boto3")
+@patch("place_integration_api.auth.srp_auth.get_tokens_via_srp")
+def test_get_credentials_via_cognito_success(
+    mock_get_tokens_via_srp: MagicMock, mock_boto3: MagicMock
+) -> None:
+    identity_client = MagicMock()
+    mock_boto3.client.return_value = identity_client
+
+    mock_get_tokens_via_srp.return_value = {
+        "AuthenticationResult": {
+            "IdToken": "id-token",
+            "AccessToken": "access-token",
+        }
+    }
+    identity_client.get_id.return_value = {"IdentityId": "identity-123"}
+    identity_client.get_credentials_for_identity.return_value = {
+        "Credentials": {
+            "AccessKeyId": "AKIA...",
+            "SecretKey": "secret",
+            "SessionToken": "session",
+        }
+    }
+
+    creds = get_credentials_via_cognito(
+        user_pool_id="pool",
+        client_id="client",
+        identity_pool_id="identity-pool",
+        username="user",
+        password="pass",
+        region="us-east-2",
+    )
+
+    assert creds.access_key_id == "AKIA..."
+    assert creds.secret_access_key == "secret"
+    assert creds.session_token == "session"
+    assert creds.identity_id == "identity-123"
+    assert creds.access_token == "access-token"
+

place_integration_api-0.1.0/tests/test_mqtt_client.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from place_integration_api.models import Credentials
+from place_integration_api.mqtt_client import get_signed_uri, run_mqtt_flow
+
+
+def test_get_signed_uri_includes_host_and_token() -> None:
+    uri = get_signed_uri(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token123",
+        host="example.iot.amazonaws.com",
+    )
+    assert uri.startswith("wss://example.iot.amazonaws.com/mqtt?")
+    assert "X-Amz-Algorithm=" in uri
+    assert "X-Amz-Signature=" in uri
+    assert "X-Amz-Security-Token=token123" in uri
+
+
+@patch("place_integration_api.mqtt_client.mqtt.Client")
+@patch("place_integration_api.mqtt_client.get_signed_uri")
+def test_run_mqtt_flow_sets_up_client(
+    mock_get_signed_uri: MagicMock,
+    mock_client_cls: MagicMock,
+) -> None:
+    mock_get_signed_uri.return_value = "wss://example.iot.amazonaws.com/mqtt?x=1"
+    client = MagicMock()
+    mock_client_cls.return_value = client
+
+    creds = Credentials(
+        access_key_id="AKIA...",
+        secret_access_key="secret",
+        session_token="token",
+        identity_id="identity-123",
+    )
+
+    run_mqtt_flow(
+        endpoint="example.iot.amazonaws.com",
+        credentials=creds,
+        household_ids=["hh1"],
+        thing_names=["thing1"],
+    )
+
+    mock_get_signed_uri.assert_called_once()
+    client.ws_set_options.assert_called()
+    client.tls_set.assert_called_once()
+    client.connect.assert_called_once()
+    client.loop_forever.assert_called_once()
+

place_integration_api-0.1.0/tests/test_provider.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import asyncio
+
+from place_integration_api.auth.abstract_auth import AbstractAuth
+from place_integration_api.config import FULFILLMENT_URL
+from place_integration_api.provider import Provider
+
+
+def test_provider_discover_parses_response() -> None:
+    payload = {
+        "success": True,
+        "data": {
+            "devices": [
+                {"householdId": "h1", "thingName": "t1", "deviceId": "d1"},
+                {"householdId": "h2", "thingName": "t2", "deviceId": "d2"},
+            ]
+        },
+    }
+
+    class DummyAuth(AbstractAuth):
+        def __init__(self) -> None:
+            self.calls: list[tuple[str, str, dict]] = []
+
+        async def async_get_access_token(self) -> str:
+            return "token"
+
+        async def request(self, method, url, **kwargs):
+            self.calls.append((method, url, kwargs))
+
+            class DummyResponse:
+                async def json(self_inner):
+                    return payload
+
+            return DummyResponse()
+
+    auth = DummyAuth()
+    provider = Provider(auth)
+    devices = asyncio.run(provider.discover())
+
+    assert auth.calls == [("POST", FULFILLMENT_URL, {"json": {"command": "DISCOVER", "data": {}}})]
+
+    household_ids = sorted(
+        {d.household_id for d in devices if d.household_id is not None}
+    )
+    thing_names = sorted(
+        {d.thing_name for d in devices if d.thing_name is not None}
+    )
+
+    assert household_ids == ["h1", "h2"]
+    assert thing_names == ["t1", "t2"]
+    assert [d.device_id for d in devices] == ["d1", "d2"]
+
+
+def test_provider_enable_sends_enable_command() -> None:
+    payload = {"success": True, "data": {"status": "enabled"}}
+
+    class DummyAuth(AbstractAuth):
+        def __init__(self) -> None:
+            self.calls: list[tuple[str, str, dict]] = []
+
+        async def async_get_access_token(self) -> str:
+            return "token"
+
+        async def request(self, method, url, **kwargs):
+            self.calls.append((method, url, kwargs))
+
+            class DummyResponse:
+                async def json(self_inner):
+                    return payload
+
+            return DummyResponse()
+
+    auth = DummyAuth()
+    provider = Provider(auth)
+    result = asyncio.run(provider.enable())
+
+    assert auth.calls == [("POST", FULFILLMENT_URL, {"json": {"command": "ENABLE", "data": {}}})]
+    assert result == payload
+
+
+def test_provider_disable_sends_disable_command() -> None:
+    payload = {"success": True, "data": {"status": "disabled"}}
+
+    class DummyAuth(AbstractAuth):
+        def __init__(self) -> None:
+            self.calls: list[tuple[str, str, dict]] = []
+
+        async def async_get_access_token(self) -> str:
+            return "token"
+
+        async def request(self, method, url, **kwargs):
+            self.calls.append((method, url, **kwargs))
+
+            class DummyResponse:
+                async def json(self_inner):
+                    return payload
+
+            return DummyResponse()
+
+    auth = DummyAuth()
+    provider = Provider(auth)
+    result = asyncio.run(provider.disable())
+
+    assert auth.calls == [("POST", FULFILLMENT_URL, {"json": {"command": "DISABLE", "data": {}}})]
+    assert result == payload
+