ipguard-api 0.1.1__tar.gz → 0.1.2__tar.gz

{ipguard_api-0.1.1 → ipguard_api-0.1.2}/DEVELOPMENT.md

@@ -53,4 +53,4 @@ Keep the Android handset profile independent of package releases. Human-readable
 
 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.
+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. See [Protocol behavior and limits](docs/PROTOCOL.md) for transport security and verification limits. [API usage](docs/USAGE.md) covers client setup and examples.

{ipguard_api-0.1.1 → ipguard_api-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipguard-api
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -42,7 +42,7 @@ See the [API guide](docs/USAGE.md) for account setup and examples.
 
 Incoming-call notifications are passive by default. Set `auto_hangup=True` to make one immediate hangup attempt after a notification. This is intended to trigger carrier-call fallback sooner. The provider and account configuration determine the actual routing and timing.
 
-Enrollment uses unencrypted TCP, including retrieval of the server public key. The authenticated connection then uses ZeroMQ CURVE. A door-release acknowledgement does not confirm that the physical door opened. See [transport and logging](docs/USAGE.md#transport-and-logging) for details. Tests use synthetic accounts and do not establish current provider acceptance or physical door outcomes.
+Enrollment uses unencrypted TCP. A door-release acknowledgement does not confirm that the physical door opened. See [protocol behavior and limits](docs/PROTOCOL.md) for transport security, supported behavior and verification limits.
 
 ## Development
 

{ipguard_api-0.1.1 → ipguard_api-0.1.2}/README.md

@@ -26,7 +26,7 @@ See the [API guide](docs/USAGE.md) for account setup and examples.
 
 Incoming-call notifications are passive by default. Set `auto_hangup=True` to make one immediate hangup attempt after a notification. This is intended to trigger carrier-call fallback sooner. The provider and account configuration determine the actual routing and timing.
 
-Enrollment uses unencrypted TCP, including retrieval of the server public key. The authenticated connection then uses ZeroMQ CURVE. A door-release acknowledgement does not confirm that the physical door opened. See [transport and logging](docs/USAGE.md#transport-and-logging) for details. Tests use synthetic accounts and do not establish current provider acceptance or physical door outcomes.
+Enrollment uses unencrypted TCP. A door-release acknowledgement does not confirm that the physical door opened. See [protocol behavior and limits](docs/PROTOCOL.md) for transport security, supported behavior and verification limits.
 
 ## Development
 

ipguard_api-0.1.2/docs/PROTOCOL.md

@@ -0,0 +1,33 @@
+# Protocol behavior and compatibility limits
+
+This document describes the behavior and limits of `ipguard-api`. The library supports account enrollment, saved authorization, relay discovery, door-release commands and incoming-call notifications. For client setup and code examples, see [API usage](USAGE.md).
+
+## Enrollment and saved authorization
+
+Verification requests and resends require an explicit method call. A reconnection with saved authorization does not request another code or replace an installation. The library refuses replacement by default. The application must obtain user consent before it enables replacement, which can disable the previous installation. Revoked authorization stops reconnection and requires enrollment again.
+
+Serialized sessions contain the account identifier, installation UUID, verification code, server public key and any activation credential returned by the service. The application is responsible for private storage of this data. Treat serialized sessions and their backups as credentials. Do not include them in issue reports or debug captures. The SDK omits credentials, raw packets and arbitrary provider error text from diagnostics.
+
+## Transport security
+
+The default enrollment endpoint is `tcp://zmq.campiserveur.com:5579`. This connection is not encrypted. The client gets the server public key during that exchange. ZeroMQ CURVE then protects the authenticated connection at `tcp://zmq.campiserveur.com:5577` with that key.
+
+CURVE does not protect the earlier enrollment exchange. Enrollment does not use HTTPS, and the SDK has no encrypted enrollment fallback. Do not disable CURVE authentication to work around connection failures.
+
+## Door-release commands
+
+A relay can receive a release command only if it has current remote-release permission and does not need badge confirmation. The SDK checks permission immediately before transmission. It rejects unavailable or busy operations. It does not put a release command in a queue for a later connection.
+
+A successful result means that the board sent a matching acknowledgement. It does not show if the physical door moved, or if it is open or locked. If a command may have been sent but there is no matching acknowledgement, its outcome is unknown. The SDK does not automatically replay release commands. The application must report the uncertainty and leave any further attempt to the user.
+
+## Incoming calls
+
+A fresh, validated incoming call on the active account connection causes a callback. Callbacks include sanitized board information when the caller can be identified. Unknown callers still cause a callback. The SDK suppresses duplicates for a limited time. It validates and discards media descriptions. It does not expose call tokens, caller routes or media credentials through callbacks. Calls missed during a disconnection are not recovered.
+
+The SDK is passive by default. It does not acknowledge, answer or hang up an incoming call. An application can set `auto_hangup=True` to enable one immediate hangup attempt after notification. This is intended to start carrier-call fallback sooner. Routing and timing depend on the provider and account configuration. The SDK skips the attempt if the call or connection is no longer current or the write is busy. It cancels pending work on disconnect or close. It does not queue, retry or replay an uncertain write. See [Automatic hangup](USAGE.md#automatic-hangup) for client configuration.
+
+Video calls, camera streaming, audio conversation, call answering, manual call controls, Firebase, Bluetooth and SIP calling are not supported. Incoming calls do not cause a door release.
+
+## Verification limits
+
+Automated SDK tests use synthetic accounts and loopback plaintext/CURVE servers. These checks validate client behavior against fixtures. They do not establish current provider acceptance, credential lifetime, account aliases, simultaneous mobile installations, incoming-call delivery, carrier routing or a physical door release. Routing and delivery depend on the provider and account configuration. A live account or physical check requires explicit user direction.

{ipguard_api-0.1.1 → ipguard_api-0.1.2}/docs/USAGE.md

@@ -81,7 +81,7 @@ Video calling and camera streaming are not supported. The SDK has no API to reta
 
 ### 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**.
+`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 SDK defaults to `auto_hangup=False`. In that mode, it gives incoming-call notifications without sending a hangup. Applications enable this option separately for each client.
 
 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.
 
@@ -97,7 +97,7 @@ The SDK checks the current permission and rejects a concurrent release for the s
 
 ## 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.
+For the default endpoints and enrollment security, see [Transport security](PROTOCOL.md#transport-security). Do not disable CURVE authentication to work around connection failures.
 
 The constructor accepts test endpoints, `timeout`, `reconnect_delay`, and `max_reconnect_delay`. Saved sessions retain their endpoints.
 

{ipguard_api-0.1.1 → ipguard_api-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ipguard-api"
-version = "0.1.1"
+version = "0.1.2"
 description = "Typed asynchronous client for the IPGUARD cloud service"
 readme = "README.md"
 requires-python = ">=3.14.2,<3.15"
@@ -58,6 +58,7 @@ only-include = [
     "uv.lock",
     "build-constraints.txt",
     "DEVELOPMENT.md",
+    "docs/PROTOCOL.md",
     "docs/USAGE.md",
     "README.md",
     "LICENSE",

{ipguard_api-0.1.1 → ipguard_api-0.1.2}/uv.lock

@@ -136,7 +136,7 @@ wheels = [
 
 [[package]]
 name = "ipguard-api"
-version = "0.1.1"
+version = "0.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "pyzmq" },