anycubic-cloud-client 0.1.0__tar.gz

anycubic_cloud_client-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

anycubic_cloud_client-0.1.0/LICENSE

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

anycubic_cloud_client-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: anycubic-cloud-client
+Version: 0.1.0
+Summary: Async client for the Anycubic cloud: sign-in, HTTP API, cloud MQTT, files, printing and camera signalling.
+Project-URL: Source, https://github.com/Nino6689/anycubic-cloud-client
+Project-URL: Issues, https://github.com/Nino6689/anycubic-cloud-client/issues
+Author: Nino Bondonno
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d-printer,anycubic,asyncio,home-assistant,mqtt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: anycubic-lan>=0.1.0
+Requires-Dist: bcrypt>=4.0
+Requires-Dist: cryptography>=43
+Requires-Dist: paho-mqtt>=2.1
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# anycubic-cloud-client
+
+An async Python client for the **Anycubic cloud**: account sign-in, the cloud
+HTTP API, the cloud MQTT feed, files, printing and the cloud camera's
+signalling. It is written for the `anycubic_cloud` Home Assistant integration
+(version 3.0), but it has no Home Assistant code.
+
+The protocol is described in [`docs/PROTOCOL.md`](docs/PROTOCOL.md) and the API
+the integration needs in [`docs/INTEGRATION-SPEC.md`](docs/INTEGRATION-SPEC.md).
+The code is written under clean-room rules ([`docs/CLEAN-ROOM.md`](docs/CLEAN-ROOM.md)).
+Open questions are in [`docs/QUESTIONS.md`](docs/QUESTIONS.md).
+
+## No Anycubic credentials inside
+
+Anycubic has no public API. Its cloud expects the credentials of its own apps:
+client and app identifiers, an app secret, and a TLS client certificate and key
+for the MQTT broker. This library **does not contain any of them**. The caller
+passes them in a `CloudSecrets` object when it creates a client, and releases
+are checked for key material before publishing. The library works as far as
+those credentials let it.
+
+This project is **not affiliated with or endorsed by Anycubic**. If Anycubic
+publishes an official developer API, this library will move to it.
+
+## Install
+
+```sh
+pip install anycubic-cloud-client
+```
+
+Python 3.13 or later. Dependencies: `aiohttp`, `paho-mqtt`, `cryptography`,
+`bcrypt` and [`anycubic-lan`](https://github.com/Nino6689/anycubic-lan), whose
+report parser is reused for the MQTT bodies the cloud shares with LAN Mode.
+
+## Usage
+
+```python
+import asyncio
+
+import aiohttp
+
+from anycubic_cloud_client import (
+    AnycubicCloudClient,
+    AnycubicCloudError,
+    AuthMode,
+    CloudMqttClient,
+    CloudSecrets,
+    CredentialsRejectedError,
+    Region,
+)
+
+
+async def main(secrets: CloudSecrets, pasted_token: str, stored: dict) -> None:
+    async with aiohttp.ClientSession() as session:
+        cloud = AnycubicCloudClient.from_entry(
+            session,
+            secrets,
+            token=pasted_token,  # the Slicer Next access token
+            auth_mode=AuthMode.SLICER,
+            region=Region.INTERNATIONAL,
+            store=stored,  # the saved token store, if any
+        )
+        try:
+            account = await cloud.check()  # exchange + userInfo, with retries
+        except CredentialsRejectedError as err:
+            print("ask the user for a new token:", err.reason)
+            return
+        if cloud.tokens_changed:
+            stored = cloud.export_token_store()  # save it, then:
+            cloud.mark_tokens_saved()
+
+        printers = await cloud.get_printers()
+        latest = await cloud.get_latest_jobs([p.id for p in printers if p.id])
+        for printer in printers:
+            detail = await cloud.get_printer(printer.id)
+            print(detail.name, detail.nozzle_temp, latest[printer.id])
+
+        link = CloudMqttClient(cloud)
+        link.add_message_listener(lambda message: print(message.kind, message.update))
+        for printer in printers:
+            link.subscribe_printer(printer.key, printer.machine_type)
+        await link.connect()
+        try:
+            await link.wait_until_connected()  # never send before the link exists
+            await cloud.query_peripherals(printers[0].id)  # the answer comes over MQTT
+            await asyncio.sleep(30)
+        except AnycubicCloudError as err:
+            print("cloud error:", err)
+        finally:
+            await link.disconnect()
+
+
+# The caller builds CloudSecrets from wherever it keeps Anycubic's app
+# credentials; this library never ships them.
+secrets = CloudSecrets(
+    app_id="...",
+    app_secret="...",
+    client_id_web="...",
+    client_id_app="...",
+    mqtt_ca_pem=b"-----BEGIN CERTIFICATE-----...",
+    mqtt_client_cert_pem=b"-----BEGIN CERTIFICATE-----...",
+    mqtt_client_key_pem=b"-----BEGIN RSA PRIVATE KEY-----...",
+)
+```
+
+`CloudSecrets` is validated when it is built and its `repr` never shows a
+value. Tokens, signatures and secrets are never logged.
+
+### Setting up right after a sign-in
+
+The cloud refuses a second exchange of the same access token within a few
+seconds (a rate limit, PROTOCOL A §4.3). The client waits it out (10 s by
+default, `rate_limit_delay=` to change it) and raises
+`ServiceUnavailableError`, never a credentials error, if it persists. To
+avoid it altogether, reuse the tokens of the sign-in instead of exchanging
+again:
+
+```python
+result = await sign_in_any(session, secrets, pasted_token)
+stored = result.tokens.to_store()  # save this as the token store
+cloud = AnycubicCloudClient.from_entry(
+    session,
+    secrets,
+    token=pasted_token,
+    auth_mode=result.auth_mode,
+    store=result.tokens,  # a TokenState or a saved store dict
+)
+await cloud.check()  # userInfo only: no second exchange
+```
+
+### Lights
+
+`set_light(printer_id, on)` sends the light type the printer reported over
+the cloud MQTT link (the lowest one), and 1 only when none has been reported
+yet (PROTOCOL B §5.4.7). The link records the types as `light` messages
+arrive; the printer id is tied to its key by `get_printers()` or
+`get_printer()`. To restore types remembered across a restart, call
+`cloud.note_light_types(printer_key, types)`. An explicit `light_type=` wins.
+
+## What is supported
+
+- **Sign-in** in the three modes (web, Android, slicer) and both regions
+  (international, China): the token exchange with its retry and its
+  rate-limit cooldown, the web fallback, the displaced-token retry, `sign_in_any()` for a config flow, the
+  2.x token-store format in and out, and token helpers (extraction from
+  pasted text or a Slicer Next config file, unverified claims, the RS256
+  pre-check against the JWKS with signature trimming).
+- **Errors that stay distinct**: credentials rejected (invalid, expired, wrong
+  token type), service unavailable, unexpected response, printer removed,
+  order refused, file not found, secrets invalid. Only the first may lead to
+  re-authentication.
+- **HTTP**: printers and their detail (firmware, ACE units, external holder,
+  capabilities), the job list (fetched once for all printers) and job
+  detail, sliced-file detail, rename, printer and ACE firmware updates.
+- **Orders** in their exact body shapes: pause, resume, cancel, light, fans,
+  temperatures, speed mode and print settings, axis moves and homing,
+  motors off, ACE feed/retract/drying/slot/auto-refill, file lists and
+  deletes on the printer and USB stick, AI detection, peripherals and light
+  queries, and a generic `send_order()`.
+- **Files and printing**: cloud file list, delete and quota; upload (the
+  storage lock is always released, also after a failure); print a cloud file,
+  a printer or USB file, or a fresh upload, with the ACE slot mapping and
+  G-code header parsing.
+- **Cloud MQTT**: identity per mode, the pinned-CA TLS context, subscription
+  and routing, parsing of every message kind (reusing `anycubic-lan` where the
+  body is the LAN body), reconnect with back-off, printers subscribed as soon
+  as they are added, a clear error when the broker refuses the login, and
+  firmware update progress.
+- **Cloud camera**: the camera-open order with its retry after a fresh login,
+  and an Agora WebRTC **signalling** client that turns the credentials and a
+  browser's SDP offer into an SDP answer (no media passes through it).
+  Encrypted channels work out of the box: the library ships Agora's public
+  key from its Web SDK (`agora-rtc-sdk-ng` 4.24.0, PROTOCOL D §1.7) as the
+  default, so a caller passes nothing. `sdk_public_key_pem` stays as an
+  optional override ([Q6](docs/QUESTIONS.md)).
+
+## Credits
+
+The Agora signalling (`agora.py`, `agora_sdp.py`) is adapted from the Agora
+client of [homeassistant_petkit](https://github.com/Jezza34000/homeassistant_petkit)
+by @Jezza34000, used under its MIT licence; its copyright notice is kept in
+those files.
+
+## Licence
+
+MIT, see [`LICENSE`](LICENSE).

anycubic_cloud_client-0.1.0/README.md

@@ -0,0 +1,186 @@
+# anycubic-cloud-client
+
+An async Python client for the **Anycubic cloud**: account sign-in, the cloud
+HTTP API, the cloud MQTT feed, files, printing and the cloud camera's
+signalling. It is written for the `anycubic_cloud` Home Assistant integration
+(version 3.0), but it has no Home Assistant code.
+
+The protocol is described in [`docs/PROTOCOL.md`](docs/PROTOCOL.md) and the API
+the integration needs in [`docs/INTEGRATION-SPEC.md`](docs/INTEGRATION-SPEC.md).
+The code is written under clean-room rules ([`docs/CLEAN-ROOM.md`](docs/CLEAN-ROOM.md)).
+Open questions are in [`docs/QUESTIONS.md`](docs/QUESTIONS.md).
+
+## No Anycubic credentials inside
+
+Anycubic has no public API. Its cloud expects the credentials of its own apps:
+client and app identifiers, an app secret, and a TLS client certificate and key
+for the MQTT broker. This library **does not contain any of them**. The caller
+passes them in a `CloudSecrets` object when it creates a client, and releases
+are checked for key material before publishing. The library works as far as
+those credentials let it.
+
+This project is **not affiliated with or endorsed by Anycubic**. If Anycubic
+publishes an official developer API, this library will move to it.
+
+## Install
+
+```sh
+pip install anycubic-cloud-client
+```
+
+Python 3.13 or later. Dependencies: `aiohttp`, `paho-mqtt`, `cryptography`,
+`bcrypt` and [`anycubic-lan`](https://github.com/Nino6689/anycubic-lan), whose
+report parser is reused for the MQTT bodies the cloud shares with LAN Mode.
+
+## Usage
+
+```python
+import asyncio
+
+import aiohttp
+
+from anycubic_cloud_client import (
+    AnycubicCloudClient,
+    AnycubicCloudError,
+    AuthMode,
+    CloudMqttClient,
+    CloudSecrets,
+    CredentialsRejectedError,
+    Region,
+)
+
+
+async def main(secrets: CloudSecrets, pasted_token: str, stored: dict) -> None:
+    async with aiohttp.ClientSession() as session:
+        cloud = AnycubicCloudClient.from_entry(
+            session,
+            secrets,
+            token=pasted_token,  # the Slicer Next access token
+            auth_mode=AuthMode.SLICER,
+            region=Region.INTERNATIONAL,
+            store=stored,  # the saved token store, if any
+        )
+        try:
+            account = await cloud.check()  # exchange + userInfo, with retries
+        except CredentialsRejectedError as err:
+            print("ask the user for a new token:", err.reason)
+            return
+        if cloud.tokens_changed:
+            stored = cloud.export_token_store()  # save it, then:
+            cloud.mark_tokens_saved()
+
+        printers = await cloud.get_printers()
+        latest = await cloud.get_latest_jobs([p.id for p in printers if p.id])
+        for printer in printers:
+            detail = await cloud.get_printer(printer.id)
+            print(detail.name, detail.nozzle_temp, latest[printer.id])
+
+        link = CloudMqttClient(cloud)
+        link.add_message_listener(lambda message: print(message.kind, message.update))
+        for printer in printers:
+            link.subscribe_printer(printer.key, printer.machine_type)
+        await link.connect()
+        try:
+            await link.wait_until_connected()  # never send before the link exists
+            await cloud.query_peripherals(printers[0].id)  # the answer comes over MQTT
+            await asyncio.sleep(30)
+        except AnycubicCloudError as err:
+            print("cloud error:", err)
+        finally:
+            await link.disconnect()
+
+
+# The caller builds CloudSecrets from wherever it keeps Anycubic's app
+# credentials; this library never ships them.
+secrets = CloudSecrets(
+    app_id="...",
+    app_secret="...",
+    client_id_web="...",
+    client_id_app="...",
+    mqtt_ca_pem=b"-----BEGIN CERTIFICATE-----...",
+    mqtt_client_cert_pem=b"-----BEGIN CERTIFICATE-----...",
+    mqtt_client_key_pem=b"-----BEGIN RSA PRIVATE KEY-----...",
+)
+```
+
+`CloudSecrets` is validated when it is built and its `repr` never shows a
+value. Tokens, signatures and secrets are never logged.
+
+### Setting up right after a sign-in
+
+The cloud refuses a second exchange of the same access token within a few
+seconds (a rate limit, PROTOCOL A §4.3). The client waits it out (10 s by
+default, `rate_limit_delay=` to change it) and raises
+`ServiceUnavailableError`, never a credentials error, if it persists. To
+avoid it altogether, reuse the tokens of the sign-in instead of exchanging
+again:
+
+```python
+result = await sign_in_any(session, secrets, pasted_token)
+stored = result.tokens.to_store()  # save this as the token store
+cloud = AnycubicCloudClient.from_entry(
+    session,
+    secrets,
+    token=pasted_token,
+    auth_mode=result.auth_mode,
+    store=result.tokens,  # a TokenState or a saved store dict
+)
+await cloud.check()  # userInfo only: no second exchange
+```
+
+### Lights
+
+`set_light(printer_id, on)` sends the light type the printer reported over
+the cloud MQTT link (the lowest one), and 1 only when none has been reported
+yet (PROTOCOL B §5.4.7). The link records the types as `light` messages
+arrive; the printer id is tied to its key by `get_printers()` or
+`get_printer()`. To restore types remembered across a restart, call
+`cloud.note_light_types(printer_key, types)`. An explicit `light_type=` wins.
+
+## What is supported
+
+- **Sign-in** in the three modes (web, Android, slicer) and both regions
+  (international, China): the token exchange with its retry and its
+  rate-limit cooldown, the web fallback, the displaced-token retry, `sign_in_any()` for a config flow, the
+  2.x token-store format in and out, and token helpers (extraction from
+  pasted text or a Slicer Next config file, unverified claims, the RS256
+  pre-check against the JWKS with signature trimming).
+- **Errors that stay distinct**: credentials rejected (invalid, expired, wrong
+  token type), service unavailable, unexpected response, printer removed,
+  order refused, file not found, secrets invalid. Only the first may lead to
+  re-authentication.
+- **HTTP**: printers and their detail (firmware, ACE units, external holder,
+  capabilities), the job list (fetched once for all printers) and job
+  detail, sliced-file detail, rename, printer and ACE firmware updates.
+- **Orders** in their exact body shapes: pause, resume, cancel, light, fans,
+  temperatures, speed mode and print settings, axis moves and homing,
+  motors off, ACE feed/retract/drying/slot/auto-refill, file lists and
+  deletes on the printer and USB stick, AI detection, peripherals and light
+  queries, and a generic `send_order()`.
+- **Files and printing**: cloud file list, delete and quota; upload (the
+  storage lock is always released, also after a failure); print a cloud file,
+  a printer or USB file, or a fresh upload, with the ACE slot mapping and
+  G-code header parsing.
+- **Cloud MQTT**: identity per mode, the pinned-CA TLS context, subscription
+  and routing, parsing of every message kind (reusing `anycubic-lan` where the
+  body is the LAN body), reconnect with back-off, printers subscribed as soon
+  as they are added, a clear error when the broker refuses the login, and
+  firmware update progress.
+- **Cloud camera**: the camera-open order with its retry after a fresh login,
+  and an Agora WebRTC **signalling** client that turns the credentials and a
+  browser's SDP offer into an SDP answer (no media passes through it).
+  Encrypted channels work out of the box: the library ships Agora's public
+  key from its Web SDK (`agora-rtc-sdk-ng` 4.24.0, PROTOCOL D §1.7) as the
+  default, so a caller passes nothing. `sdk_public_key_pem` stays as an
+  optional override ([Q6](docs/QUESTIONS.md)).
+
+## Credits
+
+The Agora signalling (`agora.py`, `agora_sdp.py`) is adapted from the Agora
+client of [homeassistant_petkit](https://github.com/Jezza34000/homeassistant_petkit)
+by @Jezza34000, used under its MIT licence; its copyright notice is kept in
+those files.
+
+## Licence
+
+MIT, see [`LICENSE`](LICENSE).

anycubic_cloud_client-0.1.0/docs/ACCEPTANCE.md

@@ -0,0 +1,80 @@
+# Acceptance reports
+
+Functional results from the specification team's tests: observed behaviour against expected, never code.
+The implementation team fixes the items under **To fix** and marks each one `**Fixed in <sha>.**`.
+
+## Live test — 2026-09-28, `clean/implementation-v0.1.0` @ `e8f7ad8`
+
+**Method.** The public API only. The real account from a 2.x install was used: Slicer mode, international,
+with a Kobra S1 and one ACE Pro. `CloudSecrets` were built by the caller, as the integration will build them.
+Nothing was written back to the live install.
+
+**Passed.**
+
+- `CloudSecrets` shows every field as `<set>` and never shows a value.
+- `check()` works in two ways. With the saved store it succeeds in 0.5 s without exchanging. From the entry alone it
+  exchanges, succeeds, and sets `tokens_changed`. The exported store keys are exactly `auth_access_token`, `auth_mode`,
+  `auth_token` and `device_id`.
+- `sign_in_any()` picks SLICER in 0.6 s. A made-up token raises `CredentialsRejectedError` with reason `invalid`.
+- `get_printers`, `get_printer` (firmware installed and target, ACE firmware, tools, external holder, ACE units with
+  slots and drying), `get_latest_jobs`, `get_storage_quota` and `list_cloud_files` all return typed data that
+  matches the account.
+- **The first ACE's box id is 0** in the cloud printer detail too (answers the open point in INTEGRATION-SPEC §11).
+- MQTT connects in 0.5 s with mutual TLS. Peripherals, ACE info, light, video and work-status messages arrive and
+  are understood. Bodies that match LAN are passed on as `anycubic-lan` reports.
+- Fan to 20 % and back (`fan/setSpeed` `done`). Local and USB file lists: a real list of printer files, and an empty
+  USB list.
+- `open_camera()` returns the full credentials block (channel, token, uids, encryption mode, key and salt).
+- Light orders with the printer's reported light type (2) are done by the printer (`light/control` `done`).
+
+**To fix.**
+
+| # | Observed | Expected |
+|---|---|---|
+| L1 | `set_light()` defaults `light_type` to 1. The Kobra S1 answers `light/control` **failed** and the light doesn't change, although the HTTP order is accepted. With `light_type=2` it works. | PROTOCOL B §5.4.7: send the light type the printer **last reported** (from its `light` reports), and 1 only if none has been reported. Make the default do that: for example, the MQTT link records the reported types and the client uses them when the caller passes none. A caller should not have to know. |
+| L2 | Two exchanges of the same access token within about 3 s: the second is refused on both attempts (2 s apart). The client then falls back to web and raises `CredentialsRejectedError`. The server's answer was a **rate limit**: `code` 0, `msg` `请求过于频繁。请稍后再试` (PROTOCOL A §4.3, now documented). | A rate-limit answer is transient. Wait out the cooldown (≥ 5 s) and try again, never fall back to web, and never raise a credentials verdict. If it persists, raise `ServiceUnavailableError`. Refusal log lines should include the server's `msg`, never the token. Also make it easy to reuse a sign-in's tokens (e.g. `SignInResult.tokens` feeding `from_entry(store=…)`), so a setup straight after a sign-in doesn't exchange again. |
+
+- L1: **Fixed in af47a5b.** `set_light()` without `light_type` sends the lowest type the printer reported in its `light`
+  messages (recorded by the MQTT link), and 1 only when none has been reported. An explicit value still wins.
+- L2: **Fixed in 7ddca36.** The rate-limit answer is retried after a cooldown (10 s by default, injectable), never
+  leads to the web fallback or a credentials verdict, and raises `ServiceUnavailableError` after 3 retries. Refusals
+  are logged with the server's `msg`. `from_entry(store=result.tokens)` reuses a sign-in's tokens (README).
+
+**Not tested live yet:** the upload and print paths (they'd start a real print), the Agora stream end to end
+(it needs a browser offer; this will be tested through the integration), firmware update (it would update the
+printer), and reconnect/backoff under a real outage.
+
+## Round 2 re-test — 2026-09-28, `clean/implementation-v0.1.0` @ `e5df26f`
+
+Re-tested live against the same account.
+
+- **L1 confirmed fixed.** `set_light()` with no `light_type` sent the type the printer had reported, and the printer answered
+  `light/control` **done** for both off and on.
+- **L2 confirmed fixed.** `sign_in_any()` followed at once by a fresh client from the entry alone, with no pause in between, signs in.
+  Previously this ended in `CredentialsRejectedError`.
+- The similarity check is unchanged (see `CLEAN-ROOM.md`), and the secret scan found no hits in 38 files.
+
+**Result: v0.1.0 accepted.**
+
+## Integration test — 2026-09-28, `hass-anycubic-next` PR #4 (`clean/cloud` @ `a60314f`) with v0.1.0
+
+Through the integration, on the live account: sign-in, the config flow, polling, MQTT, commands and the
+panel all worked. One library item was found.
+
+| # | Observed | Expected |
+|---|---|---|
+| L3 | The cloud camera never streams. Opening it in Home Assistant fails with *"The camera channel is encrypted: pass the Agora SDK public key (sdk_public_key_pem)"*. The integration doesn't pass the key, and nothing tells it to. | Ship Agora's public key (PROTOCOL D §1.7, 'Agora's key', answer to Q6) as the default. `sdk_public_key_pem` becomes an optional override. Add a test that joins an encrypted channel without passing a key, checking that the join message carries `aes_secret` wrapped under that key: decrypt it in the test with a throwaway key only when the override is used, and otherwise check its length and base64. |
+
+- L3: **Fixed in 92225c7.** `agora.AGORA_SDK_PUBLIC_KEY` holds Agora's key (base64 SPKI text from PROTOCOL D §1.7) and is
+  the default; `sdk_public_key_pem` is only an optional override. Tests join an encrypted channel with no key passed (the
+  join carries `aes_secret` as base64 of exactly 128 bytes) and with a throwaway override key (the secret decrypts to the
+  channel key's raw UTF-8 bytes).
+
+## Round 3 re-test — 2026-09-28, `clean/round-3` @ `a2a398c` (PR #2)
+
+- The default key in `agora.py` is byte-for-byte the one in Agora's `agora-rtc-sdk-ng` 4.24.0 bundle.
+- **L3 confirmed fixed live.** The cloud camera streams: WebKit opened `camera.…_cloud_camera` through Home Assistant's WebRTC, and the live
+  picture of the printer's chamber appeared. The integration passes no key, so the default is what's used.
+- Similarity is unchanged, and the secret scan found no hits in 36 files.
+
+**Result: accepted.**

anycubic_cloud_client-0.1.0/docs/CLEAN-ROOM.md

@@ -0,0 +1,63 @@
+# Clean-room record
+
+This library is written so that it contains **no code or expression** from
+these GPL-3.0 projects:
+
+- `WaresWichall/hass-anycubic_cloud` (the original Anycubic Cloud integration)
+- `Nino6689/hass-anycubic` and `Nino6689/anycubic-cloud-api` (its fork and the
+  fork's API library, published on PyPI as `anycubic-cloud-api`)
+
+The fork's maintainer (Nino Bondonno) has worked on those projects, so the
+work is split into two teams.
+
+## Roles
+
+| Role | Who | May read | Must not read |
+|---|---|---|---|
+| **Specification team** ("dirty") | Nino Bondonno, and Claude sessions on his machine that have read the GPL projects | Everything | — |
+| **Implementation team** ("clean") | A separate Claude cloud session per phase, with no access to Nino's machine | This repository's `docs/`; `Nino6689/anycubic-lan` and `Nino6689/hass-anycubic-next` (both MIT); Python and dependency documentation; the MIT project `Jezza34000/homeassistant_petkit` for its Agora client | The three repositories above, the **source** of the PyPI package `anycubic-cloud-api`, any 0.x release of `anycubic-cloud-frontend`, and any other Anycubic integration or client |
+
+Rules:
+
+1. The specification team writes **facts and requirements only**: protocol
+   behaviour, formulas, field names, captured payloads with personal data
+   removed. It never writes or edits code in this repository.
+2. The implementation team writes **all code**, from `docs/` and public
+   documentation. When a fact is missing it asks in `docs/QUESTIONS.md`; it
+   does not look elsewhere.
+3. Feedback from live testing reaches the implementation team only as
+   functional reports (observed behaviour against expected), never as code.
+4. Before publication, the code is compared mechanically with the GPL
+   projects and the result is recorded below.
+
+## Anycubic's credentials
+
+The cloud only answers clients that present Anycubic's own app credentials:
+client ids, an app id, an app secret, and a TLS CA, client certificate and
+client key for MQTT. These are Anycubic's data. **This library contains none of
+them**, and neither do its specification or tests. `docs/` names each one
+only by its role. The library takes them from its caller as one object (see
+`INTEGRATION-SPEC.md`). Tests use obvious dummy values.
+
+The `anycubic_cloud` 3.0 integration supplies them at run time from the
+`anycubic-cloud-api` package, which every 2.x install already has. It loads
+the named resource files and constants listed in the integration's own spec;
+nobody needs to read that package's source for this.
+
+## Log
+
+| Date | Team | Session | Inputs given | Outputs | Did not read the excluded repos |
+|---|---|---|---|---|---|
+| 2026-09-28 | Specification | Claude (local, Nino's machine) and four local helper sessions | The 2.x integration `hass-anycubic` 2.9.4 and library `anycubic-cloud-api` 0.4.32 source, tests and captured fixtures; field notes | `PROTOCOL.md` (Parts A–D), `INTEGRATION-SPEC.md`, this file, `README.md`, `LICENSE`, CI workflows. Credentials named by role only; scanned against the real values: no match | n/a — specification team |
+| 2026-09-28 | Implementation | Claude cloud session (routine, v0.1.0) | This repository's `docs/` (`PROTOCOL.md` Parts A–D, `INTEGRATION-SPEC.md`, `CLEAN-ROOM.md`, `QUESTIONS.md`), `README.md` and CI workflows; `Nino6689/anycubic-lan` (`src/anycubic_lan/` `__init__.py`, `reports.py`, `models.py`, `exceptions.py`, `client.py`; `pyproject.toml`; `README.md`) and its PyPI wheel 0.1.0 (compared: identical to that source); `Nino6689/hass-anycubic-next` `docs/BEHAVIOUR.md` (§2.17, §2.18, §5, §6, §7, §9), `docs/COMPAT.md` (§6), `docs/CLOUD.md`, `docs/DECISIONS.md`; `Jezza34000/homeassistant_petkit` at commit `a749d54` (`LICENSE`, `custom_components/petkit/agora_api.py`, `agora_websocket.py`, `agora_sdp.py`, `webrtc_common.py`; `camera.py` searched for its Agora calls only) | `src/anycubic_cloud_client/` (all modules; `agora.py` and `agora_sdp.py` adapted from petkit with its MIT notice), `tests/`, `pyproject.toml`, `README.md`, `docs/QUESTIONS.md` Q1–Q15, this row. The Agora SDK's npm package was not fetched (Q6) | Yes |
+| 2026-09-28 | Specification | Claude (local) | PR #1 @ `e8f7ad8`, black-box against a real account; the 2.x code for the light-type fact | `ACCEPTANCE.md` (L1, L2); PROTOCOL A §3.7, §4.2 and §4.3 (the rate limit, success code 1), B §2.3.9 (the function names are compatibility data) | n/a — specification team |
+| 2026-09-28 | Implementation | Claude cloud session (round 2) | This repository: `docs/CLEAN-ROOM.md`, `docs/ACCEPTANCE.md`, the `origin/main` diff of `docs/PROTOCOL.md` (A §3.7, §4.2, §4.3; B §2.3.9), PROTOCOL B §5.4.7 and C §4.7, `README.md`, CI workflow, and the branch's own `src/` and `tests/`; `Nino6689/anycubic-lan` `src/anycubic_lan/reports.py` (its `Light`/`LightReport` parser) and the installed PyPI wheel's exports | L1 and L2 fixes in `client.py`, `mqtt.py`, `messages.py`; tests; `README.md` (reusing a sign-in's tokens, lights); the fix notes in `ACCEPTANCE.md`; this row | Yes |
+| 2026-09-28 | Specification | Claude (local) | PR #1 @ `e5df26f`, black-box against the live account | L1 and L2 confirmed on hardware; v0.1.0 accepted; similarity and secret scan unchanged | n/a — specification team |
+| 2026-09-28 | Implementation | Claude cloud session (round 3) | This repository: `docs/CLEAN-ROOM.md`, `docs/ACCEPTANCE.md` (L3), `docs/QUESTIONS.md` (Q6 and its answer), the `origin/main` diff of `docs/PROTOCOL.md` (D §1.7 'Agora's key' and the encryption-fields row), `README.md`, the CI and publish workflows, and the repository's own `src/anycubic_cloud_client/agora.py`, `__init__.py` and `tests/test_agora.py`; the `cryptography` package's API | L3 fix in `agora.py` (Agora's key as the default, override kept); tests in `test_agora.py`; `README.md`; Q6 marked applied in `QUESTIONS.md`; the fix note in `ACCEPTANCE.md`; this row. No key file added; the wheel was built and checked for key files: none | Yes |
+| 2026-09-28 | Specification | Claude (local) | Agora's `agora-rtc-sdk-ng` 4.24.0 npm package (to extract its public key); PR #2 run through the integration against the live account | PROTOCOL D §1.7 'Agora's key' with provenance; L3 confirmed live (the camera streams) | n/a — specification team |
+
+## Similarity checks
+
+| Date | Artefact | Compared against | Longest identical run (non-blank, non-comment lines) | Result |
+|---|---|---|---|---|
+| 2026-09-28 | `src/`, `tests/` @ `e8f7ad8` | 2.x integration, 2.x library, WaresWichall | 25: Agora join-message fields. The same block is in the MIT `homeassistant_petkit` `agora_websocket.py`, which both 3.0 and 2.x adapted with credit. 23: the function-id names, which are compatibility data (BEH §2.14 `supported_functions`) given in PROTOCOL B §2.3.9. 6: SDP field names from the same MIT source. 5: order names from the spec's order table. 4: dataclass field names | Clean |