mysa-client 0.1.0__tar.gz

mysa_client-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: Validate client
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+permissions: {}
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install validation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install '.[homekit]' --group test --group lint --group build
+      - name: Check formatting, lint, types, and docs
+        run: |
+          ruff format --check .
+          ruff check .
+          mypy --python-version '${{ matrix.python }}'
+          python tools/check_docs.py
+      - name: Build and inspect release artifacts
+        run: |
+          python -m build
+          python -m twine check --strict dist/*
+          python tools/check_distribution.py
+      - name: Test the installed wheel
+        run: |
+          python -m pip install --force-reinstall --no-deps dist/*.whl
+          python -m pytest --cov=mysa_client --cov-report=term-missing
+          python examples/cloud_basic.py --help
+          python examples/homekit_basic.py --help
+      - name: Verify a cloud-only installation
+        run: |
+          python -m venv /tmp/mysa-cloud-only
+          /tmp/mysa-cloud-only/bin/python -m pip install dist/*.whl
+          /tmp/mysa-cloud-only/bin/python -I -c 'import importlib.util; import mysa_client.cloud; assert importlib.util.find_spec("aiohomekit") is None; assert importlib.util.find_spec("homeassistant") is None'

mysa_client-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Publish client
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag matching the package version (for example v0.1.0)
+        required: true
+        type: string
+
+permissions: {}
+
+jobs:
+  validate:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: validate
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+      - name: Verify the tag names the validated commit and package version
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          python - <<'PY'
+          import os
+          import subprocess
+          import tomllib
+          from pathlib import Path
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          tag = os.environ["RELEASE_TAG"]
+          assert tag == f"v{version}", "Release tag must match package metadata"
+          def revision(ref):
+              return subprocess.check_output(["git", "rev-parse", "--verify", ref], text=True).strip()
+          assert revision(f"refs/tags/{tag}^{{commit}}") == revision("HEAD"), "Tag must identify the validated commit"
+          PY
+      - name: Build, inspect, and publish through PyPI trusted publishing
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --group build
+          python -m build
+          python -m twine check --strict dist/*
+          python tools/check_distribution.py
+          python -m twine upload --non-interactive dist/*

mysa_client-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+
+# Tools
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editors
+.vscode/
+.idea/
+.DS_Store
+
+.env
+*.flow
+*.har

mysa_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 (2026-10-12)
+
+Initial standalone release, extracted from Mysa Local for Home Assistant.
+
+- Extract the cloud and HomeKit protocol clients into `mysa_client`.
+- Add caller-owned session, credential persistence, and semantic device APIs.
+- Add standalone usage examples and document reverse-engineering and hardware
+  validation limits.
+
+- Preserve the existing protocol APIs and MIT attribution; keep HTTP sessions,
+  Zeroconf, polling, and credential persistence under caller ownership.
+- Support Python 3.11–3.14, cloud-only installation, the optional HomeKit extra,
+  and typed wheel distributions.
+- Cover authentication, retries, parsing, pairing rollback, and example
+  lifecycle with an independent test suite that does not install Home Assistant.

mysa_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Sokolsky
+
+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.

mysa_client-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: mysa-client
+Version: 0.1.0
+Summary: Standalone async cloud and HomeKit clients for Mysa thermostats
+Project-URL: Repository, https://github.com/SokolskyNikita/mysa-client
+Project-URL: Issues, https://github.com/SokolskyNikita/mysa-client/issues
+Project-URL: Changelog, https://github.com/SokolskyNikita/mysa-client/blob/main/CHANGELOG.md
+Author: Nikita Sokolsky
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.11
+Provides-Extra: homekit
+Requires-Dist: aiohomekit<5,>=4.0.1; extra == 'homekit'
+Requires-Dist: cryptography>=48.0.1; extra == 'homekit'
+Requires-Dist: zeroconf>=0.149.16; extra == 'homekit'
+Description-Content-Type: text/markdown
+
+# Mysa Client
+
+`mysa-client` is an asynchronous Python library for the reverse-engineered Mysa
+cloud API and the Mysa thermostat HomeKit interface. It exposes the two
+protocols independently; it does not choose between them or provide an
+application polling, persistence, or device-state confirmation policy.
+
+The API is based on behavior observed in the Mysa apps and, where noted, on
+Baseboard Lite hardware. It is not a vendor API contract. The only hardware
+validation recorded so far is on two Baseboard Lite `BB-V2-0-L` thermostats
+running firmware `3.17.5.13`. Other model behavior is app/code-derived or
+simulated and should be treated as experimental until checked on matching
+hardware. See the [cloud protocol guide](https://github.com/SokolskyNikita/mysa-client/blob/main/src/mysa_client/cloud/README.md) and
+[HomeKit protocol guide](https://github.com/SokolskyNikita/mysa-client/blob/main/src/mysa_client/homekit/README.md) for limits and
+evidence.
+
+## Installation
+
+Python 3.11 or newer is required. Install the cloud client from PyPI:
+
+```sh
+python -m pip install mysa-client
+```
+
+That installs the cloud API and its `aiohttp` dependency. HomeKit support is an
+optional extra:
+
+```sh
+python -m pip install 'mysa-client[homekit]'
+```
+
+To run the examples or develop the library, clone this repository and install
+from its checkout:
+
+```sh
+git clone https://github.com/SokolskyNikita/mysa-client.git
+cd mysa-client
+python -m pip install -e '.[homekit]' --group test --group lint --group build
+```
+
+Import from `mysa_client.cloud` or `mysa_client.homekit`. Importing the package
+root does not load either protocol's optional transport dependencies.
+
+## Cloud example
+
+The [cloud example](https://github.com/SokolskyNikita/mysa-client/blob/main/examples/cloud_basic.py) signs in with SRP, saves the
+refresh token through a caller-owned callback, discovers devices, and reads
+state. It sends a setpoint command only when `MYSA_SET_CELSIUS` is explicitly
+set in the environment. Never put an account password or token in source
+control. The example creates its token file with owner-only permissions.
+
+```sh
+export MYSA_EMAIL='account@example.com'
+export MYSA_PASSWORD='your-password'
+export MYSA_REFRESH_TOKEN_FILE="$HOME/.config/mysa-client/refresh-token"
+python examples/cloud_basic.py
+```
+
+To request a heating target, explicitly set a safe value for your device and
+run the example again:
+
+```sh
+MYSA_SET_CELSIUS=20.5 python examples/cloud_basic.py
+```
+
+The command's successful HTTP response means the API accepted the request. It
+does not prove that the thermostat applied it. Read reported state separately
+and use an application-specific confirmation policy.
+
+## HomeKit example
+
+The [HomeKit example](https://github.com/SokolskyNikita/mysa-client/blob/main/examples/homekit_basic.py) discovers nearby accessories,
+can complete PIN pairing and persist the returned credentials, and can load
+those credentials for reads, events, and an explicitly requested target write.
+It creates and closes its own asynchronous Zeroconf instance and stops the
+protocol controller and device session on exit. Pairing credentials are secret
+key material; keep the JSON file private and make a protected backup.
+
+List discovered accessories:
+
+```sh
+python examples/homekit_basic.py --discover
+```
+
+Pair using the accessory ID shown by discovery and the code printed on the
+thermostat's faceplate:
+
+```sh
+python examples/homekit_basic.py --pair-id 'AA:BB:CC:DD:EE:FF' --pin 123-45-678
+```
+
+Load the saved pairing, observe events, and read semantic values:
+
+```sh
+python examples/homekit_basic.py --pairing-file "$HOME/.config/mysa-client/pairing.json"
+```
+
+HomeKit write acceptance also is not physical confirmation. The example reads
+back the target after a requested write, but the caller remains responsible
+for freshness and application policy.
+
+## Ownership and error handling
+
+Both clients use resources supplied by the caller. Cloud `MysaAuth` and
+`MysaClient` share a caller-owned `aiohttp.ClientSession`; close it with an
+`async with` block. The cloud client uses a 20-second request timeout and
+refreshes/retries once after a 401. It does not automatically retry an
+ambiguous command after a timeout, connection loss, cancellation, 429, or
+server error. `MysaRateLimitError.retry_after` carries the server's backoff hint
+when available. Authentication, connection, rate-limit, not-found, and API
+errors derive from `MysaError`.
+
+`HomeKitProtocol` receives an externally managed asynchronous Zeroconf
+instance. Start and stop the protocol within that instance's lifetime, close
+each loaded `HomeKitDevice`, and then close Zeroconf. Reads have a default
+three-second deadline; controller discovery/pairing and accessory metadata
+operations have bounded internal timeouts. Writes have no fixed caller
+deadline and are not replayed automatically. HomeKit errors derive from
+`HomeKitError`, including typed read and rejected-write errors. Pairing
+completion awaits the caller's credential-save callback before fetching
+accessory details; if saving fails, the library attempts bounded key removal.
+That cleanup is best effort if the accessory is unreachable.
+
+The caller owns long-term refresh-token and pairing-data storage, polling,
+freshness, retries after ambiguous outcomes, validation against advertised
+capabilities, and command confirmation. HomeKit `state` is a cached view, not
+a freshness guarantee. Cloud reported state can lag behind a successful
+response. A fresh read after a write is useful evidence, but may still not
+prove the device's physical behavior.
+
+## Public API
+
+The public cloud surface is exported from `mysa_client.cloud`: `MysaAuth`,
+`Tokens`, `MysaClient`, response models, model and command enums, typed errors,
+and the documented command helpers. HomeKit's public semantic API is exported
+from `mysa_client.homekit`: `HomeKitProtocol`, `HomeKitDevice`, `PairingSession`,
+`Field`, mode/action and event models, discovery records, and typed errors.
+
+The Home Assistant consumer also uses supported helpers from
+`mysa_client.cloud.commands`, `.const`, `.observations`, `.trace`, and
+`.validation`. Those submodule helpers are documented in the [cloud API
+surface](https://github.com/SokolskyNikita/mysa-client/blob/main/src/mysa_client/cloud/README.md#public-api-and-integration-helpers).
+They are part of the maintained consumer API even when they are not re-exported
+at `mysa_client.cloud`. Other underscored names and implementation details are
+private.
+
+See [examples](https://github.com/SokolskyNikita/mysa-client/tree/main/examples),
+[cloud authentication](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/cloud-auth.md),
+[cloud state and models](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/cloud-state.md),
+[cloud workflows](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/cloud-workflows.md),
+the protocol guides, and the [change log](https://github.com/SokolskyNikita/mysa-client/blob/main/CHANGELOG.md).
+
+## Development and release
+
+The project is licensed under MIT; see [LICENSE](https://github.com/SokolskyNikita/mysa-client/blob/main/LICENSE). Protocol behavior
+and test fixtures are maintained in this repository. Automated tests and
+documentation checks use simulated data and do not contact Mysa or local
+thermostats. Hardware validation must be performed separately with explicit
+operator intent and reversible commands.
+
+Release order, tag requirements, and PyPI trusted-publisher setup are documented
+in [releasing](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/releasing.md).

mysa_client-0.1.0/README.md

@@ -0,0 +1,162 @@
+# Mysa Client
+
+`mysa-client` is an asynchronous Python library for the reverse-engineered Mysa
+cloud API and the Mysa thermostat HomeKit interface. It exposes the two
+protocols independently; it does not choose between them or provide an
+application polling, persistence, or device-state confirmation policy.
+
+The API is based on behavior observed in the Mysa apps and, where noted, on
+Baseboard Lite hardware. It is not a vendor API contract. The only hardware
+validation recorded so far is on two Baseboard Lite `BB-V2-0-L` thermostats
+running firmware `3.17.5.13`. Other model behavior is app/code-derived or
+simulated and should be treated as experimental until checked on matching
+hardware. See the [cloud protocol guide](https://github.com/SokolskyNikita/mysa-client/blob/main/src/mysa_client/cloud/README.md) and
+[HomeKit protocol guide](https://github.com/SokolskyNikita/mysa-client/blob/main/src/mysa_client/homekit/README.md) for limits and
+evidence.
+
+## Installation
+
+Python 3.11 or newer is required. Install the cloud client from PyPI:
+
+```sh
+python -m pip install mysa-client
+```
+
+That installs the cloud API and its `aiohttp` dependency. HomeKit support is an
+optional extra:
+
+```sh
+python -m pip install 'mysa-client[homekit]'
+```
+
+To run the examples or develop the library, clone this repository and install
+from its checkout:
+
+```sh
+git clone https://github.com/SokolskyNikita/mysa-client.git
+cd mysa-client
+python -m pip install -e '.[homekit]' --group test --group lint --group build
+```
+
+Import from `mysa_client.cloud` or `mysa_client.homekit`. Importing the package
+root does not load either protocol's optional transport dependencies.
+
+## Cloud example
+
+The [cloud example](https://github.com/SokolskyNikita/mysa-client/blob/main/examples/cloud_basic.py) signs in with SRP, saves the
+refresh token through a caller-owned callback, discovers devices, and reads
+state. It sends a setpoint command only when `MYSA_SET_CELSIUS` is explicitly
+set in the environment. Never put an account password or token in source
+control. The example creates its token file with owner-only permissions.
+
+```sh
+export MYSA_EMAIL='account@example.com'
+export MYSA_PASSWORD='your-password'
+export MYSA_REFRESH_TOKEN_FILE="$HOME/.config/mysa-client/refresh-token"
+python examples/cloud_basic.py
+```
+
+To request a heating target, explicitly set a safe value for your device and
+run the example again:
+
+```sh
+MYSA_SET_CELSIUS=20.5 python examples/cloud_basic.py
+```
+
+The command's successful HTTP response means the API accepted the request. It
+does not prove that the thermostat applied it. Read reported state separately
+and use an application-specific confirmation policy.
+
+## HomeKit example
+
+The [HomeKit example](https://github.com/SokolskyNikita/mysa-client/blob/main/examples/homekit_basic.py) discovers nearby accessories,
+can complete PIN pairing and persist the returned credentials, and can load
+those credentials for reads, events, and an explicitly requested target write.
+It creates and closes its own asynchronous Zeroconf instance and stops the
+protocol controller and device session on exit. Pairing credentials are secret
+key material; keep the JSON file private and make a protected backup.
+
+List discovered accessories:
+
+```sh
+python examples/homekit_basic.py --discover
+```
+
+Pair using the accessory ID shown by discovery and the code printed on the
+thermostat's faceplate:
+
+```sh
+python examples/homekit_basic.py --pair-id 'AA:BB:CC:DD:EE:FF' --pin 123-45-678
+```
+
+Load the saved pairing, observe events, and read semantic values:
+
+```sh
+python examples/homekit_basic.py --pairing-file "$HOME/.config/mysa-client/pairing.json"
+```
+
+HomeKit write acceptance also is not physical confirmation. The example reads
+back the target after a requested write, but the caller remains responsible
+for freshness and application policy.
+
+## Ownership and error handling
+
+Both clients use resources supplied by the caller. Cloud `MysaAuth` and
+`MysaClient` share a caller-owned `aiohttp.ClientSession`; close it with an
+`async with` block. The cloud client uses a 20-second request timeout and
+refreshes/retries once after a 401. It does not automatically retry an
+ambiguous command after a timeout, connection loss, cancellation, 429, or
+server error. `MysaRateLimitError.retry_after` carries the server's backoff hint
+when available. Authentication, connection, rate-limit, not-found, and API
+errors derive from `MysaError`.
+
+`HomeKitProtocol` receives an externally managed asynchronous Zeroconf
+instance. Start and stop the protocol within that instance's lifetime, close
+each loaded `HomeKitDevice`, and then close Zeroconf. Reads have a default
+three-second deadline; controller discovery/pairing and accessory metadata
+operations have bounded internal timeouts. Writes have no fixed caller
+deadline and are not replayed automatically. HomeKit errors derive from
+`HomeKitError`, including typed read and rejected-write errors. Pairing
+completion awaits the caller's credential-save callback before fetching
+accessory details; if saving fails, the library attempts bounded key removal.
+That cleanup is best effort if the accessory is unreachable.
+
+The caller owns long-term refresh-token and pairing-data storage, polling,
+freshness, retries after ambiguous outcomes, validation against advertised
+capabilities, and command confirmation. HomeKit `state` is a cached view, not
+a freshness guarantee. Cloud reported state can lag behind a successful
+response. A fresh read after a write is useful evidence, but may still not
+prove the device's physical behavior.
+
+## Public API
+
+The public cloud surface is exported from `mysa_client.cloud`: `MysaAuth`,
+`Tokens`, `MysaClient`, response models, model and command enums, typed errors,
+and the documented command helpers. HomeKit's public semantic API is exported
+from `mysa_client.homekit`: `HomeKitProtocol`, `HomeKitDevice`, `PairingSession`,
+`Field`, mode/action and event models, discovery records, and typed errors.
+
+The Home Assistant consumer also uses supported helpers from
+`mysa_client.cloud.commands`, `.const`, `.observations`, `.trace`, and
+`.validation`. Those submodule helpers are documented in the [cloud API
+surface](https://github.com/SokolskyNikita/mysa-client/blob/main/src/mysa_client/cloud/README.md#public-api-and-integration-helpers).
+They are part of the maintained consumer API even when they are not re-exported
+at `mysa_client.cloud`. Other underscored names and implementation details are
+private.
+
+See [examples](https://github.com/SokolskyNikita/mysa-client/tree/main/examples),
+[cloud authentication](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/cloud-auth.md),
+[cloud state and models](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/cloud-state.md),
+[cloud workflows](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/cloud-workflows.md),
+the protocol guides, and the [change log](https://github.com/SokolskyNikita/mysa-client/blob/main/CHANGELOG.md).
+
+## Development and release
+
+The project is licensed under MIT; see [LICENSE](https://github.com/SokolskyNikita/mysa-client/blob/main/LICENSE). Protocol behavior
+and test fixtures are maintained in this repository. Automated tests and
+documentation checks use simulated data and do not contact Mysa or local
+thermostats. Hardware validation must be performed separately with explicit
+operator intent and reversible commands.
+
+Release order, tag requirements, and PyPI trusted-publisher setup are documented
+in [releasing](https://github.com/SokolskyNikita/mysa-client/blob/main/docs/releasing.md).

mysa_client-0.1.0/docs/cloud-auth.md

@@ -0,0 +1,75 @@
+# Cloud authentication
+
+The [cloud protocol reference](../src/mysa_client/cloud/README.md) owns endpoint availability, S/R/L terminology, observed limitations, and recommended client policy. This page supplies detailed wire mechanics; Home Assistant's implementation status belongs to its [cloud tracker](https://github.com/SokolskyNikita/mysa-homeassistant/blob/main/docs/implementation/cloud.md).
+
+The protocols were reverse-engineered from the original Mysa apps. Hardware observations cover Baseboard Lite `BB-V2-0-L`, firmware `3.17.5.13`. Other-model behavior remains app/code-derived unless explicitly stated.
+
+## Connection and authentication
+
+### Service hosts
+
+| Host | Use |
+| --- | --- |
+| `mysa-backend.mysa.cloud` | Current HTTPS API and migrated legacy REST routes |
+| `app-prod.mysa.cloud` | Legacy REST host; still advertised as `regionApiBaseUrl`, with some push-registration and account routes |
+| `cognito-idp.us-east-1.amazonaws.com` | Sign-in and token refresh |
+| `i18n.mysa.cloud` | Static country and time-zone lists |
+| `chunk.mysa.cloud/track` | Analytics |
+
+Routing depends on feature flags: `MONOLITH_API_ACCESS` moves legacy routes to
+`mysa-backend`, and `DISABLE_LEGACY_FALLBACK` disables retrying them on `app-prod`.
+Both were enabled for the tested account. A host name alone therefore does not
+identify the protocol family. Mysa Local's host selection is described in the
+[cloud guide](../src/mysa_client/cloud/README.md#how-it-is-organized).
+
+### Cognito sign-in
+
+Current and legacy clients share these public Cognito identifiers:
+
+| Setting | Value |
+| --- | --- |
+| AWS region | `us-east-1` |
+| User pool | `us-east-1_GUFWfhI7g` |
+| App client | `6cktj934gasnc72f7jo2cmf6rt` |
+| Identity pool | `us-east-1:e27f246e-ad23-41ce-ac80-eda86f8be424` |
+
+The app client has no client secret. Cognito requests go to `https://cognito-idp.us-east-1.amazonaws.com/` with:
+
+```http
+X-Amz-Target: AWSCognitoIdentityProviderService.<Action>
+Content-Type: application/x-amz-json-1.1
+```
+
+No AWS request signature is required for these user-pool calls. Sign-in uses `InitiateAuth` with `AuthFlow: "USER_SRP_AUTH"` and `AuthParameters` containing `USERNAME` and `SRP_A`. A `PASSWORD_VERIFIER` challenge follows. `RespondToAuthChallenge` sends `PASSWORD_CLAIM_SIGNATURE`, `PASSWORD_CLAIM_SECRET_BLOCK`, `TIMESTAMP` and `USERNAME` as `ChallengeResponses`, plus the challenge session if supplied. The response contains `IdToken`, `AccessToken`, `RefreshToken` and `ExpiresIn: 3600`.
+
+The Python SRP implementation uses Cognito's 3072-bit group, SHA-256 and a 16-byte derived authentication key. Use the challenge's `USER_ID_FOR_SRP` when computing the response, even when sign-in began with an email address. Cognito also expects an English UTC timestamp with an unpadded day, for example `Fri Jan 2 03:04:05 UTC 2026`. The [SRP implementation](../src/mysa_client/cloud/srp.py) contains the calculation.
+
+API authorization headers, token handling and supported challenges are described
+in the cloud guide: [authentication](../src/mysa_client/cloud/README.md#using-the-client) and [request handling](../src/mysa_client/cloud/README.md#errors-timeouts-retries-and-caller-responsibilities).
+
+Refresh uses `GetTokensFromRefreshToken` with:
+
+[Cognito refresh request (credential placeholder only)](../examples/cloud/cognito-refresh.request.json)
+
+The observed refresh response supplied ID and access tokens with a one-hour
+lifetime and no replacement refresh token. The Identity Pool is not needed for
+HTTPS; the examined mobile app uses it for SNS push registration. Its credential exchange and
+MQTT role are covered in the [MQTT connection model](https://github.com/SokolskyNikita/mysa-homeassistant/blob/main/docs/mqtt.md#connection-and-authorization-model).
+
+For HTTP errors and retries, see the [cloud error reference](../src/mysa_client/cloud/README.md#errors-timeouts-retries-and-caller-responsibilities).
+The examined mobile app treats 409 as success generally; the Python client handles it specially
+only for [device claims](cloud-workflows.md#claiming-an-older-model).
+
+### Browser access
+
+The tested APIs do not support ordinary cross-origin browser access:
+
+| Service | Browser behavior |
+| --- | --- |
+| Cognito | Browser sign-in allowed |
+| `mysa-backend` | Authorization/Content-Type preflights returned 404; actual responses also lacked `Access-Control-Allow-Origin` |
+| `app-prod` | Legacy-route preflights allowed access, but actual responses lacked `Access-Control-Allow-Origin`; newer pairing, state and bootstrap routes returned 403 |
+
+Successful Cognito sign-in therefore does not make Mysa's API responses readable
+by a webpage. Cloud requests need a backend, such as Home Assistant, or an
+extension with the appropriate host permissions.