ipguard-api 0.1.0b6__tar.gz

ipguard_api-0.1.0b6/.gitignore

@@ -0,0 +1,32 @@
+.venv/
+.cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+upload/
+build/
+.ha-dev/
+.env
+.env.*
+.ipguard/
+*.session.json
+.storage/
+session.json
+credentials.json
+credentials.yaml
+credentials.yml
+*.credentials.json
+*.credentials.yaml
+*.credentials.yml
+*.session.yaml
+*.session.yml
+*.pem
+*.key
+.DS_Store

ipguard_api-0.1.0b6/.python-version

@@ -0,0 +1 @@
+3.14.8

ipguard_api-0.1.0b6/DEVELOPMENT.md

@@ -0,0 +1,56 @@
+# Development
+
+This repository builds and tests `ipguard-api` independently. It does not require Home Assistant, a workspace member, or a sibling checkout. [pyproject.toml](pyproject.toml) declares the runtime requirements and development tools. [uv.lock](uv.lock) records the resolved versions and hashes. Use the interpreter selected by [.python-version](.python-version). Use the `uv` version pinned in the [checks workflow](.github/workflows/checks.yml).
+
+## Local checks
+
+```sh
+uv sync --locked
+uv run --no-sync ruff check .
+uv run --no-sync ruff format --check .
+uv run --no-sync mypy
+uv run --no-sync pytest
+uv run --no-sync python -m scripts.release_metadata
+uv build --build-constraints build-constraints.txt --require-hashes
+uv run --no-sync python -m scripts.release_metadata --dist dist --write-checksums
+```
+
+Use a clean `dist` directory when you build a different version. Validation rejects stale or unexpected archives. The development environment and caches are local and ignored.
+
+`conftest.py` guards ordinary Python sockets, DNS resolution, and native ZeroMQ connections. It permits only loopback or in-process fixtures. Tests use synthetic accounts. Tests must not contact the provider, send verification messages, replace a mobile installation, answer a call, or actuate a physical door. Secure transport tests require native ZeroMQ CURVE support.
+
+The package tests build the wheel and source distribution in temporary directories. They verify exact contents and metadata. They also test rejection of altered or extra files, unsafe paths, links, changed checksums, and invalid release identity. Network-guard tests verify the Python and native ZeroMQ restrictions. CI also runs the pinned `actionlint` workflow validator.
+
+## Package boundaries
+
+The explicit Hatch `only-include` lists in [pyproject.toml](pyproject.toml) are the authoritative package allowlists. The wheel contains only `ipguard_api`, its type marker, the license, and generated metadata. The source distribution also contains the development-only test harness (`conftest.py`), package validators, usage and development documentation, and reproducible environment inputs. It does not contain local credentials, caches, application artifacts, or integration files.
+
+[scripts/packaging_policy.py](scripts/packaging_policy.py) checks all allowed source bytes. It rejects stray or missing source files, symbolic links, unsafe archive paths, and duplicate members. Wheel RECORD hashes and sizes must describe exactly the approved payload. [scripts/release_metadata.py](scripts/release_metadata.py) also checks the distribution identity, runtime requirements, README, license, URLs, Python requirements, and pure-Python wheel tags against the checked source. Both archives must match their SHA-256 manifest.
+
+[build-constraints.txt](build-constraints.txt) pins and hashes the complete isolated Hatch build dependency set. It must agree exactly with the lockfile and the build backend declaration. When you change the backend, review and update all three together. Do not relax an allowlist or hash check to make an unexpected build pass.
+
+## Publishing to PyPI
+
+The SDK repository is [KennyTangHK/ipguard-api](https://github.com/KennyTangHK/ipguard-api). Its default branch is `master`. Ordinary CI checks run on pushes to `master` and on pull requests.
+
+Before the first release, configure PyPI Trusted Publishing for the `ipguard-api` project. Use repository owner `KennyTangHK`, repository name `ipguard-api`, workflow filename `publish.yml`, and GitHub environment `pypi`. Configure the matching GitHub environment and its release approval and tag rules as appropriate. See [PyPI publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) or [creating a new PyPI project](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/). Confirm package-name availability and publisher ownership in the target account.
+
+When you have explicit authorization to release SDK changes:
+
+1. Set the intended version in [pyproject.toml](pyproject.toml). Run `uv lock` and the local checks. Use `X.Y.ZbN` for beta releases or `X.Y.Z` for stable releases. Review the lockfile change. A package version change must not silently upgrade external dependencies.
+2. Commit and push the reviewed changes to `master` in the independent SDK repository.
+3. Push the matching `vX.Y.ZbN` or `vX.Y.Z` tag. The tag must match the committed package version exactly. Do not move or reuse a published tag or version.
+
+The [publication workflow](.github/workflows/publish.yml) calls the checks workflow for the tagged commit. It downloads the three checked assets from that run. It then validates the event, tag, clean checkout, tested commit, remote tag, archive payloads, and hashes again. It stages only the two validated distribution archives for upload.
+
+The separate publishing job uses the `pypi` environment. Only this job receives `id-token: write`. Ordinary checks have read-only repository access. [PyPA's publishing action](https://github.com/pypa/gh-action-pypi-publish) uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/) and produces attestations. It does not need a stored PyPI password or API token.
+
+If no source changes are necessary, you can rerun a failed run from GitHub Actions or manually dispatch it against the same tag. The workflow rejects branch dispatches. Publication does not skip existing distributions. After an uncertain or partial upload, inspect PyPI before you decide what to release next. A source or workflow fix requires a new version and tag. Published artifacts are never overwritten. Publishing the SDK does not release the separate Home Assistant integration.
+
+## Runtime invariants
+
+Keep the Android handset profile independent of package releases. Human-readable provider metadata uses the configured Android strings. Preserve opaque identifiers, credentials, and call tokens exactly. Enrollment, resends, and installation replacement must remain explicit. Release operations must check current permission, reject busy or unavailable operations, and never queue or replay a command with an uncertain outcome.
+
+Incoming-call callbacks expose only sanitized board information. The SDK is passive by default. An explicit `auto_hangup=True` enables one immediate hangup attempt with cause zero after notification. The SDK does not retain media offers, answer calls, or implement media transport. Disconnect and shutdown cancel owned work. The SDK never replays uncertain attempts.
+
+Store credentials in the consumer's private session storage. Keep raw packets, session contents, arbitrary provider errors, call tokens, and media data out of logs, tracebacks, and callback data. [README.md](README.md) and [API usage](docs/USAGE.md) document the plaintext enrollment stage and other protocol limits. Synthetic tests show local client behavior. They do not show current provider acceptance, account-wide routing guarantees, or physical door outcomes.

ipguard_api-0.1.0b6/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ipguard_api-0.1.0b6/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: ipguard-api
+Version: 0.1.0b6
+Summary: Typed asynchronous client for the IPGUARD cloud service
+Project-URL: Repository, https://github.com/KennyTangHK/ipguard-api
+Project-URL: Issues, https://github.com/KennyTangHK/ipguard-api/issues
+Project-URL: Documentation, https://github.com/KennyTangHK/ipguard-api/blob/master/docs/USAGE.md
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.14.2
+Requires-Dist: pyzmq<28,>=27.2.0
+Description-Content-Type: text/markdown
+
+# ipguard-api
+
+Source repository: [KennyTangHK/ipguard-api](https://github.com/KennyTangHK/ipguard-api). The default branch is `master`.
+
+**Beta software.** This software is not a stable release.
+
+This is an independent community project. It is not affiliated with, sponsored by, or endorsed by IPGUARD, NACD, or Noralsy.
+
+Use this software lawfully. Use it only with your own authorized account and with buildings or doors that you have permission to access and control. Do not use it for unauthorized access or abuse.
+
+**Use at your own risk.** To the extent permitted by applicable law, the software is provided without warranty. Its authors and contributors accept no responsibility or liability for its use. The warranty and liability limits in the [Apache-2.0 license](LICENSE) apply.
+
+`ipguard-api` is a typed asynchronous Python library for an authorized IPGUARD cloud account. It supports phone and email enrollment, ZeroMQ CURVE connections, relay discovery, incoming-call callbacks, and explicit remote release commands. It does not depend on Home Assistant.
+
+**Video calling and camera streaming are not supported.** By default, incoming calls give passive notifications. The library does not retain media offers or answer calls. To attempt one immediate hangup after the notification, set `auto_hangup=True` for the client. This attempt is intended to trigger carrier-call fallback sooner. The provider and account configuration determine the actual routing and timing.
+
+For enrollment, saved sessions, event subscriptions, and command errors, see [API usage](docs/USAGE.md). For tests and release builds, see [Development](DEVELOPMENT.md).
+
+The [package metadata](pyproject.toml) defines the Python and dependency requirements. The [lockfile](uv.lock) records the resolved dependencies. The PyPI package is `ipguard-api`; the import package is `ipguard_api`. The separate Home Assistant integration is at [hass-ipguard](https://github.com/KennyTangHK/hass-ipguard).
+
+The [protocol implementation](src/ipguard_api/protocol.py) defines the protocol behavior. The [handset profile](src/ipguard_api/models.py) defines the client metadata values. Direct enrollment uses unencrypted TCP to retrieve the server public key. The authenticated channel then uses CURVE. A board acknowledgement does not show the physical state of a door. Bluetooth, SIP, pickup, and media transport and decoding are outside the scope of this library. Local fixtures test client behavior with synthetic accounts. They do not show current provider acceptance or physical door outcomes.
+
+## Installation
+
+After a release is published to PyPI, install the package:
+
+```sh
+python -m pip install --pre ipguard-api
+```
+
+The `--pre` option permits beta releases. To install this checkout, use `python -m pip install .`. For a locked test environment, see the [development guide](DEVELOPMENT.md). Installation and import do not enroll an account or open a connection.

ipguard_api-0.1.0b6/README.md

@@ -0,0 +1,31 @@
+# ipguard-api
+
+Source repository: [KennyTangHK/ipguard-api](https://github.com/KennyTangHK/ipguard-api). The default branch is `master`.
+
+**Beta software.** This software is not a stable release.
+
+This is an independent community project. It is not affiliated with, sponsored by, or endorsed by IPGUARD, NACD, or Noralsy.
+
+Use this software lawfully. Use it only with your own authorized account and with buildings or doors that you have permission to access and control. Do not use it for unauthorized access or abuse.
+
+**Use at your own risk.** To the extent permitted by applicable law, the software is provided without warranty. Its authors and contributors accept no responsibility or liability for its use. The warranty and liability limits in the [Apache-2.0 license](LICENSE) apply.
+
+`ipguard-api` is a typed asynchronous Python library for an authorized IPGUARD cloud account. It supports phone and email enrollment, ZeroMQ CURVE connections, relay discovery, incoming-call callbacks, and explicit remote release commands. It does not depend on Home Assistant.
+
+**Video calling and camera streaming are not supported.** By default, incoming calls give passive notifications. The library does not retain media offers or answer calls. To attempt one immediate hangup after the notification, set `auto_hangup=True` for the client. This attempt is intended to trigger carrier-call fallback sooner. The provider and account configuration determine the actual routing and timing.
+
+For enrollment, saved sessions, event subscriptions, and command errors, see [API usage](docs/USAGE.md). For tests and release builds, see [Development](DEVELOPMENT.md).
+
+The [package metadata](pyproject.toml) defines the Python and dependency requirements. The [lockfile](uv.lock) records the resolved dependencies. The PyPI package is `ipguard-api`; the import package is `ipguard_api`. The separate Home Assistant integration is at [hass-ipguard](https://github.com/KennyTangHK/hass-ipguard).
+
+The [protocol implementation](src/ipguard_api/protocol.py) defines the protocol behavior. The [handset profile](src/ipguard_api/models.py) defines the client metadata values. Direct enrollment uses unencrypted TCP to retrieve the server public key. The authenticated channel then uses CURVE. A board acknowledgement does not show the physical state of a door. Bluetooth, SIP, pickup, and media transport and decoding are outside the scope of this library. Local fixtures test client behavior with synthetic accounts. They do not show current provider acceptance or physical door outcomes.
+
+## Installation
+
+After a release is published to PyPI, install the package:
+
+```sh
+python -m pip install --pre ipguard-api
+```
+
+The `--pre` option permits beta releases. To install this checkout, use `python -m pip install .`. For a locked test environment, see the [development guide](DEVELOPMENT.md). Installation and import do not enroll an account or open a connection.

ipguard_api-0.1.0b6/build-constraints.txt

@@ -0,0 +1,7 @@
+# Exact isolated build dependencies from uv.lock. Update and verify together.
+hatchling==1.32.4 --hash=sha256:08ecf7548fb48205e7f213d70c71e67b8271b7242093dc3f1da578b42c734a2c --hash=sha256:c4468f73144c054d2aab4ef0f0378c43b9878bf07f8ffd6b79690e970d375f07
+packaging==26.3 --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+pathspec==1.1.1 --hash=sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a --hash=sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189
+pluggy==1.6.0 --hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 --hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
+tomlkit==0.15.1 --hash=sha256:177a05aece5a8ca5266fd3c448abb47b8d352f09d477d3ca8332db4d89b24304 --hash=sha256:e25bbf38843005246210a12982776f27f99cb9be67160e14434d0c0d21ee1e97
+trove-classifiers==2026.9.21.13 --hash=sha256:0a9ebc8d4e2f3e8a22848c5258033035bec17a3012ac3fea16dbaa764489eb71 --hash=sha256:8b1ff4f9c191b1040b71c37f1e445ab99732911e3cd91de52838453a854d7a17

ipguard_api-0.1.0b6/conftest.py

@@ -0,0 +1,93 @@
+"""Confine Python and native ZeroMQ test traffic to synthetic local fixtures."""
+
+import ipaddress
+import re
+import socket
+from collections.abc import Iterator
+from typing import Any
+
+import pytest
+import zmq
+
+
+def _check_host(host: object) -> None:
+    if host == "localhost":
+        return
+    try:
+        if isinstance(host, str) and ipaddress.ip_address(host).is_loopback:
+            return
+    except ValueError:
+        pass
+    raise AssertionError("Tests may only use loopback hosts.")
+
+
+def _check_address(sock: socket.socket, address: Any) -> None:
+    if sock.family == socket.AF_UNIX:
+        return
+    if not isinstance(address, tuple) or not address:
+        raise AssertionError("Tests may only use loopback addresses.")
+    _check_host(address[0])
+
+
+@pytest.fixture(autouse=True)
+def prevent_provider_traffic(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
+    """Guard native libzmq separately from ordinary Python socket methods."""
+    for method in ("connect", "connect_ex", "bind"):
+        original = getattr(socket.socket, method)
+
+        def guarded(
+            sock: socket.socket, address: Any, *, _original: Any = original
+        ) -> Any:
+            _check_address(sock, address)
+            return _original(sock, address)
+
+        monkeypatch.setattr(socket.socket, method, guarded)
+    sendto = socket.socket.sendto
+
+    def local_sendto(sock: socket.socket, *args: Any) -> int:
+        _check_address(sock, args[-1])
+        return sendto(sock, *args)
+
+    monkeypatch.setattr(socket.socket, "sendto", local_sendto)
+    if hasattr(socket.socket, "sendmsg"):
+        sendmsg = socket.socket.sendmsg
+
+        def local_sendmsg(sock: socket.socket, *args: Any) -> int:
+            if len(args) >= 4 and args[3] is not None:
+                _check_address(sock, args[3])
+            return sendmsg(sock, *args)
+
+        monkeypatch.setattr(socket.socket, "sendmsg", local_sendmsg)
+    getaddrinfo = socket.getaddrinfo
+
+    def local_getaddrinfo(host: Any, *args: Any, **kwargs: Any) -> Any:
+        _check_host(host)
+        return getaddrinfo(host, *args, **kwargs)
+
+    monkeypatch.setattr(socket, "getaddrinfo", local_getaddrinfo)
+    for method in ("gethostbyname", "gethostbyname_ex", "gethostbyaddr"):
+        resolve = getattr(socket, method)
+
+        def local_resolve(host: Any, *, _resolve: Any = resolve) -> Any:
+            _check_host(host)
+            return _resolve(host)
+
+        monkeypatch.setattr(socket, method, local_resolve)
+    for method in ("connect", "bind"):
+        zmq_original = getattr(zmq.Socket, method)
+
+        def local_zmq(
+            sock: zmq.Socket[Any], endpoint: str, *, _original: Any = zmq_original
+        ) -> Any:
+            if (
+                not endpoint.startswith("inproc://")
+                and re.fullmatch(
+                    r"tcp://(?:127\.0\.0\.1|\[::1\]):(?:[0-9]{1,5}|\*)", endpoint
+                )
+                is None
+            ):
+                raise AssertionError("Protocol tests may only use loopback endpoints.")
+            return _original(sock, endpoint)
+
+        monkeypatch.setattr(zmq.Socket, method, local_zmq)
+    yield

ipguard_api-0.1.0b6/docs/USAGE.md

@@ -0,0 +1,106 @@
+# API usage
+
+Create the asynchronous client in an active event loop. Always close it or use its async context manager. Client construction and cached properties do not send messages. Enrollment and release occur only when you call the related methods.
+
+## Enrollment
+
+```python
+from ipguard_api import ExistingInstallationError, IpguardClient
+
+
+async def enroll(identifier: str, label: str, read_code):
+    async with IpguardClient() as client:
+        await client.async_request_verification(identifier, label)
+        code = await read_code()
+        await client.async_verify_code(code)
+        try:
+            return await client.async_complete_registration()
+        except ExistingInstallationError:
+            # Ask the user before explicitly requesting replacement.
+            raise
+```
+
+Use the email address or international phone number registered to the account. The client normalizes phone numbers to the Android API's `00` format. Keep verification codes as strings of six ASCII digits. Include leading zeros. Use a personal name or Android device name as the installation label. The handset model is separate and is fixed to `Pixel 7`.
+
+`async_request_verification` requests an SMS or email. It resets the challenge credentials but preserves the identity for the same pending account. A second call explicitly requests a resend. `async_verify_code` validates the code and gets a server public key. `async_complete_registration` performs secure registration, requires fresh configuration and relay inventory, and returns an activated `Session`.
+
+If registration would replace an installation, the client raises `ExistingInstallationError`. Replacement can disable the previous installation. After the user gives explicit consent, call `async_complete_registration(replace_existing=True)`. If the connection is interrupted while you wait for consent, do not send another code or replacement command without an explicit call. Enrollment and discovery do not test a physical release.
+
+## Saved authorization and updates
+
+Store `Session.to_dict()` in private storage. It contains credentials. Its `repr` omits sensitive fields. Use `Session.from_dict(data)` to restore it. Restoration alone does not authenticate the session.
+
+```python
+from ipguard_api import IpguardClient, Session
+
+
+async def observe(saved_data, on_snapshot):
+    session = Session.from_dict(saved_data)
+    async with IpguardClient(session=session) as client:
+        unsubscribe = client.subscribe(on_snapshot)
+        try:
+            await client.async_connect(session)
+            return await client.async_get_relays()
+        finally:
+            unsubscribe()
+```
+
+For normal startup, call `async_connect`. This does not request a code or replace an installation. Keep the context open to receive cloud pushes. `subscribe` registers a synchronous event-loop callback and returns an unsubscribe function. Do not block inside a callback.
+
+A `ClientSnapshot` contains cached relays, connection and revocation flags, a classified error, and the current session. If credentials change, explicitly serialize the session to save them. `client.connected`, `client.session`, and `client.snapshot` read cached values. Background recovery uses bounded exponential backoff and the saved session. Revocation stops reconnection and requires user-driven enrollment. `async_close` closes sockets, cancels recovery, and clears callbacks. You can call it more than once.
+
+## Incoming calls
+
+Call `subscribe_calls` before you connect, and keep the client open. It registers a synchronous event-loop callback and returns an unsubscribe function:
+
+```python
+from ipguard_api import IncomingCall, IpguardClient, Session
+
+
+async def listen(saved_data, stop):
+    def on_call(call: IncomingCall) -> None:
+        print(call.board.name if call.board else "Incoming intercom call")
+
+    session = Session.from_dict(saved_data)
+    async with IpguardClient(session=session) as client:
+        unsubscribe = client.subscribe_calls(on_call)
+        try:
+            await client.async_connect(session)
+            await stop.wait()
+        finally:
+            unsubscribe()
+```
+
+`IncomingCall` contains only an optional `Board`. The client matches the board by exact identity against the latest cached inventory. Unknown or ambiguous callers still cause a callback, with `board=None`. Malformed or oversized optional board and site labels, and site identities, are omitted. Callback data does not expose call tokens, routing senders, SDP, or media credentials. The client validates and discards media descriptions. Offers must come from the current authenticated transport for an activated installation. The client ignores malformed offers and continues relay updates.
+
+Callbacks can arrive before `async_connect` completes, including during reconnection. If your interface is not ready, briefly buffer sanitized notifications. With the default constructor, call receipt does not acknowledge an offer, answer, pick up, hang up, or negotiate media. The client does not use Firebase. Delivery depends on the provider routing the call to the active account connection.
+
+The client suppresses repeated offers in a bounded in-memory cache. The cache expires after inactivity. It stays available across reconnects for the same installation. Explicit close or an installation change clears it. The client does not fetch or replay disconnected call history.
+
+Video calling and camera streaming are not supported. The SDK has no API to retain offers, answer calls, or manage media sessions. It does not send ring acknowledgements or pickup commands.
+
+### Automatic hangup
+
+`IpguardClient(auto_hangup=True)` enables one immediate hangup attempt after each fresh, validated incoming-call notification. This is intended to trigger carrier-call fallback sooner. The provider and account configuration determine the actual routing and timing. The standalone SDK defaults to `auto_hangup=False`. In that mode, it gives incoming-call notifications without sending a hangup. Home Assistant has an **Auto hangup** option for each account. It is enabled by default. Find it under **Settings → Devices & services → IPGUARD → Configure**.
+
+An attempt requires a current call, connection, and installation. The client skips busy, stale, disconnected, or superseded attempts. Call termination, disconnect, or shutdown cancels pending work. The client does not queue or replay attempts. It does not retry a send with an uncertain outcome. Duplicate suppression stays available across reconnects for the same installation. It does not persist after the client closes or the process restarts. The SDK has no manual hangup or call-answering API.
+
+Sanitized DEBUG messages report `IPGUARD auto hangup outcome=attempted`, `sent`, `uncertain`, or `skipped`. `sent` confirms only a local transport write. It does not confirm carrier-call delivery.
+
+## Release one relay
+
+Select a current `Relay` with `remote_allowed=True` and no pending confirmation. Only for a deliberate user action, call `await client.async_release(relay.board_identity, relay.number)`. The SDK accepts relay numbers from 1 to 3.
+
+The SDK checks the current permission and rejects a concurrent release for the same relay. It does not queue actions for a later connection. Success means that the board sent a matching acknowledgement. It does not show whether the door is physically open or closed.
+
+`OutcomeUnknownError` means that the command can have reached the board. Report the uncertainty and do not replay the command automatically. `ReleaseRejectedError` reports a matching rejection. `RelayUnavailableError` covers absent or unpermitted relays. `AuthRevokedError` requires enrollment. `ConnectionFailureError` reports ordinary connection failures. All these errors derive from `IpguardError`. Authentication failures derive from `AuthenticationError`.
+
+## Transport and logging
+
+The default activation endpoint is `tcp://zmq.campiserveur.com:5579`. The default secure messaging endpoint is `tcp://zmq.campiserveur.com:5577`. Activation uses unencrypted TCP, including for retrieval of the server public key. CURVE protects the subsequent authenticated connection. The client does not implement an encrypted enrollment fallback. Do not disable CURVE authentication to work around handshake failures.
+
+The constructor accepts test endpoints, `timeout`, `reconnect_delay`, and `max_reconnect_delay`. Saved sessions retain their endpoints.
+
+Enable `ipguard_api` at DEBUG level for sanitized stage and event information. Outgoing metadata uses Android app values or mock Android handset details from the [handset profile](../src/ipguard_api/models.py). The [protocol implementation](../src/ipguard_api/protocol.py) validates these values. Do not log raw packets, identifiers, UUIDs, codes, passwords, keys, tokens, or arbitrary server text.
+
+The supported timeout range is 0.001–300 seconds. Reconnect delays are 0.001–3,600 seconds. The maximum delay must be at least the initial delay. Routing identities must be valid UTF-8, with a maximum of 255 bytes and no NUL. Service messages are limited to 16 frames and 8 MiB in total. Inventory updates permit a maximum of 256 sites and 1,024 board entries. An oversized inventory update fails as a whole. These limits do not change saved session serialization.