airkeep 0.1.0__tar.gz

airkeep-0.1.0/LICENSE

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

airkeep-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: airkeep
+Version: 0.1.0
+Summary: Send Bambu AMS readings to your Airkeep dashboard
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: paho-mqtt>=2.1,<3
+Requires-Dist: pydantic>=2.12,<3
+Requires-Dist: httpx>=0.28,<1
+Requires-Python: >=3.14
+Project-URL: Homepage, https://airkeep.io
+Project-URL: Repository, https://github.com/danohn/airkeep
+Description-Content-Type: text/markdown
+
+# Airkeep LAN agent
+
+Run one agent on an always-on computer on the same LAN as your Bambu P2S. It subscribes to the printer over verified TLS and sends AMS humidity and temperature to your hosted Airkeep dashboard over outbound HTTPS.
+
+The printer IP, serial and LAN access code stay in the agent's private local SQLite database. The dashboard receives an opaque agent enrollment identity, printer connectivity status, AMS IDs and readings. Setup tests the printer certificate chain, its exact serial and MQTT login before starting dashboard sign-in.
+
+## Run with uv
+
+With [uv installed](https://docs.astral.sh/uv/getting-started/installation/), run:
+
+```sh
+uvx airkeep
+```
+
+To install the command for regular use:
+
+```sh
+uv tool install airkeep
+airkeep
+```
+
+On first run, open the local setup link printed by Airkeep, normally `http://127.0.0.1:8788/`. The wizard opens on the printer form.
+
+Enter the printer's private LAN IP, serial and eight-character LAN access code. The wizard tests the connection, then begins dashboard sign-in. The default hosted origin is `https://dashboard.airkeep.io`. You can enter your own HTTPS dashboard origin. Follow the displayed verification link, sign in and approve the displayed code. Keep the setup page open until it confirms completion. The setup listener closes automatically, and collection begins.
+
+Airkeep stores its SQLite database in `~/.local/state/airkeep` by default, or in `$XDG_STATE_HOME/airkeep` if set. Running from a checkout with an existing `.local/agent/agent.sqlite3` reuses that directory. To reuse it from another working directory, pass its absolute directory path with `--data-dir`. `AIRKEEP_AGENT_DATA` also sets the data directory. The directory has mode `0700` and newly created files have mode `0600`. Only one process can use each data directory at a time.
+
+For development, run `uv run --locked --project agent airkeep` from the repository root.
+
+## Docker on Linux
+
+The dedicated image is `ghcr.io/danohn/airkeep-agent`, built for `linux/amd64` and `linux/arm64`. Linux host networking lets the agent reach the LAN printer and keeps its setup listener on the host loopback interface.
+
+```sh
+docker run -d --name airkeep-agent \
+  --network host --restart unless-stopped \
+  --mount type=volume,source=airkeep-agent,target=/data \
+  ghcr.io/danohn/airkeep-agent:latest
+```
+
+Open the local setup page to configure the printer.
+
+For a headless Linux host, forward its loopback port over SSH and open `http://127.0.0.1:8788` on your computer.
+
+```sh
+ssh -L 8788:127.0.0.1:8788 user@agent-host
+```
+
+The host needs outbound TCP 8883 to the printer and outbound TCP 443 to the dashboard. IPv6 ULA and link-local printer addresses are supported alongside IPv4 private and link-local addresses. The setup port defaults to 8788 and can be changed with `--setup-port`. The wizard validates the exact loopback Host and Origin, so use the same local port when forwarding it.
+
+Build a local image from the repository root with the following command.
+
+```sh
+docker build -f agent/Dockerfile -t airkeep-agent:local .
+```
+
+The `LAN agent image` workflow tests and builds pull requests, then publishes the dedicated multi-platform image on main pushes and version tags. For a pinned release, replace `latest` with the published version or image digest.
+
+## Buffering and reconnecting
+
+The agent persists at most one reading per AMS every 30 seconds, retaining unsent readings for 24 hours. It uploads up to 100 readings per request. Fresh observations from the last 30 seconds are sent first, newest first, followed by replay history in original observation order. Each persisted event has a stable UUID. Successful HTTP 204 responses remove acknowledged events. Failed requests keep them for retry with exponential backoff and jitter. HTTP 429 responses honor a numeric Retry-After delay up to one hour.
+
+Readings retained across restarts, failed deliveries or beyond the 30-second live window carry `replay=true` and their original timestamps. A new observation remains eligible for live delivery while older history is buffered. MQTT reconnects automatically after interrupted LAN connections. Cloud status updates include printer connectivity on transitions and at least every 30 seconds while the dashboard is reachable. A revoked enrollment stops uploads and leaves a generic `enrollment_required` status in the process output. The process continues collecting within the same 24-hour retention window.
+
+If the dashboard permanently rejects an ingest request with HTTP 400 or 422, the agent reduces the batch size until it isolates the rejected reading. It then moves only that reading into a private local quarantine and continues delivering valid readings with their original event IDs. The quarantine retains at most 100 readings for 24 hours. Process output reports `invalid_reading_quarantined` and then `connected_with_quarantined_readings`, without including event contents or upstream error details. Check the host clock and agent version when this status appears. Successful replacement enrollment clears the quarantine along with previous buffered readings.
+
+To replace credentials or enroll again, stop the running agent and run the same command with `--setup`. In Docker, stop the service and run an interactive replacement using the same volume.
+
+```sh
+docker stop airkeep-agent
+docker run --rm -it --network host \
+  --mount type=volume,source=airkeep-agent,target=/data \
+  ghcr.io/danohn/airkeep-agent:latest airkeep --setup
+```
+
+This process continues running after setup. Stop it with Ctrl-C, then restart the original container with `docker start airkeep-agent`. Successful replacement enrollment atomically clears previous buffered readings and creates a new installation identity, preventing delivery of a previous account's history into the replacement account. An interrupted replacement keeps the saved enrollment intact.
+
+## Checks
+
+```sh
+uv run --locked --directory agent pytest -q
+```
+
+The tests cover queue persistence, 24-hour pruning, sample throttling, event ordering and IDs, retries, replay, heartbeat transitions, revoked enrollment, device-flow pacing, local setup and TLS serial validation. Testing against a physical P2S requires that printer's LAN settings and network access.
+
+## Publish to PyPI
+
+Configure the [PyPI Trusted Publisher](https://pypi.org/manage/account/publishing/) for project `airkeep`, owner `danohn`, repository `airkeep`, workflow `publish-agent.yml`, and environment `pypi`. Use a pending publisher before the first release. Configure the GitHub `pypi` environment to accept release tags matching `agent-v*`.
+
+Update the version in `agent/pyproject.toml`, then regenerate the agent and server lockfiles. Push a matching tag such as `agent-v0.1.0` to publish the wheel and source distribution. The workflow tests the agent and checks the tag against the package version before publishing. [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)

airkeep-0.1.0/README.md

@@ -0,0 +1,90 @@
+# Airkeep LAN agent
+
+Run one agent on an always-on computer on the same LAN as your Bambu P2S. It subscribes to the printer over verified TLS and sends AMS humidity and temperature to your hosted Airkeep dashboard over outbound HTTPS.
+
+The printer IP, serial and LAN access code stay in the agent's private local SQLite database. The dashboard receives an opaque agent enrollment identity, printer connectivity status, AMS IDs and readings. Setup tests the printer certificate chain, its exact serial and MQTT login before starting dashboard sign-in.
+
+## Run with uv
+
+With [uv installed](https://docs.astral.sh/uv/getting-started/installation/), run:
+
+```sh
+uvx airkeep
+```
+
+To install the command for regular use:
+
+```sh
+uv tool install airkeep
+airkeep
+```
+
+On first run, open the local setup link printed by Airkeep, normally `http://127.0.0.1:8788/`. The wizard opens on the printer form.
+
+Enter the printer's private LAN IP, serial and eight-character LAN access code. The wizard tests the connection, then begins dashboard sign-in. The default hosted origin is `https://dashboard.airkeep.io`. You can enter your own HTTPS dashboard origin. Follow the displayed verification link, sign in and approve the displayed code. Keep the setup page open until it confirms completion. The setup listener closes automatically, and collection begins.
+
+Airkeep stores its SQLite database in `~/.local/state/airkeep` by default, or in `$XDG_STATE_HOME/airkeep` if set. Running from a checkout with an existing `.local/agent/agent.sqlite3` reuses that directory. To reuse it from another working directory, pass its absolute directory path with `--data-dir`. `AIRKEEP_AGENT_DATA` also sets the data directory. The directory has mode `0700` and newly created files have mode `0600`. Only one process can use each data directory at a time.
+
+For development, run `uv run --locked --project agent airkeep` from the repository root.
+
+## Docker on Linux
+
+The dedicated image is `ghcr.io/danohn/airkeep-agent`, built for `linux/amd64` and `linux/arm64`. Linux host networking lets the agent reach the LAN printer and keeps its setup listener on the host loopback interface.
+
+```sh
+docker run -d --name airkeep-agent \
+  --network host --restart unless-stopped \
+  --mount type=volume,source=airkeep-agent,target=/data \
+  ghcr.io/danohn/airkeep-agent:latest
+```
+
+Open the local setup page to configure the printer.
+
+For a headless Linux host, forward its loopback port over SSH and open `http://127.0.0.1:8788` on your computer.
+
+```sh
+ssh -L 8788:127.0.0.1:8788 user@agent-host
+```
+
+The host needs outbound TCP 8883 to the printer and outbound TCP 443 to the dashboard. IPv6 ULA and link-local printer addresses are supported alongside IPv4 private and link-local addresses. The setup port defaults to 8788 and can be changed with `--setup-port`. The wizard validates the exact loopback Host and Origin, so use the same local port when forwarding it.
+
+Build a local image from the repository root with the following command.
+
+```sh
+docker build -f agent/Dockerfile -t airkeep-agent:local .
+```
+
+The `LAN agent image` workflow tests and builds pull requests, then publishes the dedicated multi-platform image on main pushes and version tags. For a pinned release, replace `latest` with the published version or image digest.
+
+## Buffering and reconnecting
+
+The agent persists at most one reading per AMS every 30 seconds, retaining unsent readings for 24 hours. It uploads up to 100 readings per request. Fresh observations from the last 30 seconds are sent first, newest first, followed by replay history in original observation order. Each persisted event has a stable UUID. Successful HTTP 204 responses remove acknowledged events. Failed requests keep them for retry with exponential backoff and jitter. HTTP 429 responses honor a numeric Retry-After delay up to one hour.
+
+Readings retained across restarts, failed deliveries or beyond the 30-second live window carry `replay=true` and their original timestamps. A new observation remains eligible for live delivery while older history is buffered. MQTT reconnects automatically after interrupted LAN connections. Cloud status updates include printer connectivity on transitions and at least every 30 seconds while the dashboard is reachable. A revoked enrollment stops uploads and leaves a generic `enrollment_required` status in the process output. The process continues collecting within the same 24-hour retention window.
+
+If the dashboard permanently rejects an ingest request with HTTP 400 or 422, the agent reduces the batch size until it isolates the rejected reading. It then moves only that reading into a private local quarantine and continues delivering valid readings with their original event IDs. The quarantine retains at most 100 readings for 24 hours. Process output reports `invalid_reading_quarantined` and then `connected_with_quarantined_readings`, without including event contents or upstream error details. Check the host clock and agent version when this status appears. Successful replacement enrollment clears the quarantine along with previous buffered readings.
+
+To replace credentials or enroll again, stop the running agent and run the same command with `--setup`. In Docker, stop the service and run an interactive replacement using the same volume.
+
+```sh
+docker stop airkeep-agent
+docker run --rm -it --network host \
+  --mount type=volume,source=airkeep-agent,target=/data \
+  ghcr.io/danohn/airkeep-agent:latest airkeep --setup
+```
+
+This process continues running after setup. Stop it with Ctrl-C, then restart the original container with `docker start airkeep-agent`. Successful replacement enrollment atomically clears previous buffered readings and creates a new installation identity, preventing delivery of a previous account's history into the replacement account. An interrupted replacement keeps the saved enrollment intact.
+
+## Checks
+
+```sh
+uv run --locked --directory agent pytest -q
+```
+
+The tests cover queue persistence, 24-hour pruning, sample throttling, event ordering and IDs, retries, replay, heartbeat transitions, revoked enrollment, device-flow pacing, local setup and TLS serial validation. Testing against a physical P2S requires that printer's LAN settings and network access.
+
+## Publish to PyPI
+
+Configure the [PyPI Trusted Publisher](https://pypi.org/manage/account/publishing/) for project `airkeep`, owner `danohn`, repository `airkeep`, workflow `publish-agent.yml`, and environment `pypi`. Use a pending publisher before the first release. Configure the GitHub `pypi` environment to accept release tags matching `agent-v*`.
+
+Update the version in `agent/pyproject.toml`, then regenerate the agent and server lockfiles. Push a matching tag such as `agent-v0.1.0` to publish the wheel and source distribution. The workflow tests the agent and checks the tag against the package version before publishing. [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)

airkeep-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "airkeep"
+version = "0.1.0"
+description = "Send Bambu AMS readings to your Airkeep dashboard"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["paho-mqtt>=2.1,<3", "pydantic>=2.12,<3", "httpx>=0.28,<1"]
+
+[project.scripts]
+airkeep = "airkeep.__main__:main"
+
+[project.urls]
+Homepage = "https://airkeep.io"
+Repository = "https://github.com/danohn/airkeep"
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8.4"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

airkeep-0.1.0/src/airkeep/__init__.py

@@ -0,0 +1 @@
+"""Airkeep LAN agent."""

airkeep-0.1.0/src/airkeep/__main__.py

@@ -0,0 +1,79 @@
+"""Airkeep LAN agent command line."""
+import argparse
+import fcntl
+import logging
+import os
+from pathlib import Path
+import signal
+import threading
+
+from .collector import Collector
+from .cloud import Cloud, Uploader
+from .setup import PrinterSettings, run_setup
+from .spool import Spool
+
+
+def default_data_dir():
+    configured = os.environ.get('AIRKEEP_AGENT_DATA')
+    if configured:
+        return Path(configured)
+    legacy = Path('.local/agent')
+    if (legacy / 'agent.sqlite3').is_file():
+        return legacy
+    state_dir = Path(os.environ.get('XDG_STATE_HOME') or Path.home() / '.local' / 'state')
+    return state_dir / 'airkeep'
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Collect Bambu telemetry locally for hosted Airkeep.')
+    parser.add_argument('--data-dir', type=Path, default=default_data_dir())
+    parser.add_argument('--setup', action='store_true', help='Replace enrollment and printer settings through local setup')
+    parser.add_argument('--setup-port', type=int, default=8788)
+    args = parser.parse_args()
+    if not 1 <= args.setup_port <= 65535:
+        parser.error('Choose a setup port between 1 and 65535.')
+    os.umask(0o077)
+    args.data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+    args.data_dir.chmod(0o700)
+    # Keep only one collector/uploader for this identity, including during setup.
+    with (args.data_dir / 'agent.lock').open('a') as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise SystemExit('An agent is already using this data directory.') from None
+        spool = Spool(args.data_dir / 'agent.sqlite3')
+        collector = cloud = None
+        stopped = threading.Event()
+        signal.signal(signal.SIGTERM, lambda *_: stopped.set())
+        signal.signal(signal.SIGINT, lambda *_: stopped.set())
+        try:
+            if args.setup or spool.configuration() is None:
+                run_setup(spool, args.setup_port, stopped)
+            config = spool.configuration()
+            settings = PrinterSettings.validate(config)
+            collector = Collector(settings, spool)
+            cloud = Cloud(config['origin'])
+            uploader = Uploader(cloud, spool, config['token'])
+            # Suppress transport logs that can contain IPs, URLs or credentials.
+            logging.getLogger('httpx').disabled = True
+            logging.getLogger('httpcore').disabled = True
+            collector.start()
+            status = None
+            while not stopped.is_set():
+                uploader.step(collector.connected)
+                if uploader.status != status:
+                    status = uploader.status
+                    print('Airkeep cloud ' + status, flush=True)
+                    if uploader.revoked:
+                        print('Stop the agent and run it with --setup to enroll again.', flush=True)
+                stopped.wait(1)
+        finally:
+            if collector:
+                collector.stop()
+            if cloud:
+                cloud.close()
+            spool.close()
+
+
+if __name__ == '__main__':
+    main()

airkeep-0.1.0/src/airkeep/bambu-ca.pem

@@ -0,0 +1,109 @@
+-----BEGIN CERTIFICATE-----
+MIIFfzCCA2egAwIBAgIUXtzR6tRiL/RHBRXOoyFU0+XrliowDQYJKoZIhvcNAQEL
+BQAwRjELMAkGA1UEBhMCQ04xITAfBgNVBAoMGEJCTCBUZWNobm9sb2dpZXMgQ28u
+IEx0ZDEUMBIGA1UEAwwLQkJMIENBMiBSU0EwIBcNMjUwNjE3MDEzODA4WhgPMjA1
+MDA2MTcwMTM4MDhaMEYxCzAJBgNVBAYTAkNOMSEwHwYDVQQKDBhCQkwgVGVjaG5v
+bG9naWVzIENvLiBMdGQxFDASBgNVBAMMC0JCTCBDQTIgUlNBMIICIjANBgkqhkiG
+9w0BAQEFAAOCAg8AMIICCgKCAgEAo4550G4c42gTKzQqixwKT089RizIdZpyOcGA
+679rPaOdWsMqVwnYPP2FpMqXKkjFbedE+SpGloi2NKCuiPNVRbq9PHOOZwTs7YLo
+bOwf53FJuO6vRFpzFfX1tlc9zlFqJvZnYO9NgHpMysidocWcgrDN/SIDywgPB5CV
+bYg3Vvzua9fwZx9e5KT9xd5IpTqdTrWS47jQOVKLhdQCbJFIlMrblOwLBAx+fHok
+wqh6tkI6Ktuyyjw8Dysebi1ndWjKtZ2mW47r8xZ/J+z3EZqcyJMY6MRtx/zb1jBF
+uHtkjrb5Kv1DMzSKlkaNJIbvC+Mk+hI97W+SjLSRuIdC7+oJUzWaSzgu9cjXCVfm
+q8t4IL/35hP69PK95LgLectIrP96CYAT/aVMG19FrFW0QWEyfT+kzG4jkumfPbHq
+Y2nNkEN0+tjj3h4WdzrWgQEojK/lhfcRFVkts74+aZoMpQP+vmL17CKmSzXk5o/e
+K21xgxJdzMbdztfTpibiXk0abfOpN+1VR+3NYa+bROAKNyGaReEGsyW2bjcjNx51
+5Vqzj3SVxhMSp5vfF9E4A1jE99M/l9jQDM6RzkT0lMccGAd5tUSdNvDlrqtQaQiK
+v/ZsXPgXLTWfOpvaLNEgwdMgZMuhjpkwvAZyoYfeF9kyydjDh7bvrX//cz/VopAU
+lxUtQtMCAwEAAaNjMGEwHQYDVR0OBBYEFNVJgQad1sNTN0jxVkwbJ/XM1an1MB8G
+A1UdIwQYMBaAFNVJgQad1sNTN0jxVkwbJ/XM1an1MA8GA1UdEwEB/wQFMAMBAf8w
+DgYDVR0PAQH/BAQDAgEGMA0GCSqGSIb3DQEBCwUAA4ICAQBFZDKMJfp/N4gBeFHh
+MiFehaUyMS6e9mzrTfMLJLJoj6Jopa9V9jIfcCEBGZuRThqFcATV+UdFHSINpUcH
+upcCYnazTRC4dn1hnxnQ1ojQcHxdGp9xGw/YclAKD97d8bPShfBMT1to9zbMK7T5
+L8zgqg01YIOKjQk0Hcd0+0iUr6m8zQ5P8Rl3QXqAyeWgqmYQrrjTWwPsgdfHNXKX
+vDrx7/cqry5lKU802hUplKMBxelv4W8407Ytj1lfJOwvxqxxsFU5jSwcUG3zo2vk
+QtjRs8m5BKup5K1OPYkkPu7Ld89X0XpU073/dNDG11uxb1eDKrtNP6vZuZjNE2Pq
+8HCoI1EtP+ItyqtUMvHi6Z2zsmlA25broVioeUKxjlIecpQ9JR/FhDu9CWNF/nDW
+LSORNaMMzgsMSzI+HCiUhqN+qMIvVP6rzGTJzwqz/lc5Lf+ZPCnGA9WJTT4uPIhf
+ufbZmnUJ35WuWKHxovDsqBh88zQ9sZ+ei4Hi4vVzOhUgfG3aLoSQEYqRoqaboANh
+wCwzyuW2Rv54u5QSBbd6Gx1OpvsWmLPWd2/iL2kISl5wfmLGVydvSJa+rbOfuAy7
+ycVQacVDQCAnbhoVrQy7+454QsKSW3ZV6BcyRrorewCyCYgd7nyxflxHZTBEykXX
+haGNe/KFNvJBMOIuIUzknRRmiQ==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIB8zCCAZmgAwIBAgIUe61jGQ4RzIC8k+sNuqbI/CaNqPIwCgYIKoZIzj0EAwIw
+RjELMAkGA1UEBhMCQ04xITAfBgNVBAoMGEJCTCBUZWNobm9sb2dpZXMgQ28uIEx0
+ZDEUMBIGA1UEAwwLQkJMIENBMiBFQ0MwIBcNMjUwNjE3MDEzODM1WhgPMjA1MDA2
+MTcwMTM4MzVaMEYxCzAJBgNVBAYTAkNOMSEwHwYDVQQKDBhCQkwgVGVjaG5vbG9n
+aWVzIENvLiBMdGQxFDASBgNVBAMMC0JCTCBDQTIgRUNDMFkwEwYHKoZIzj0CAQYI
+KoZIzj0DAQcDQgAEpKTF7wRSty4DXpGJzgCPwRh8ghLlxUC3qJbyEgLqTvJgbiwY
+APPHK7kVbVmerkqhHOT4QeWRlTG3dOQGLA2VpaNjMGEwHQYDVR0OBBYEFKuRpsjY
+REOyIKH7HwOE6jhGBd6NMB8GA1UdIwQYMBaAFKuRpsjYREOyIKH7HwOE6jhGBd6N
+MA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMCA0gA
+MEUCIErBiUm3VdtP3rz4kb8aLpI5p+BzL7M9vElBGWWJxpHMAiEA3r5tJWVGwuxi
+YCrB1c40KYFRFyahGrhOJZAj/YhRdnU=
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIEeTCCA2GgAwIBAgIUOq+lNIaC2xsswkFqj5JPyVBl45cwDQYJKoZIhvcNAQEL
+BQAwQjELMAkGA1UEBhMCQ04xIjAgBgNVBAoMGUJCTCBUZWNobm9sb2dpZXMgQ28u
+LCBMdGQxDzANBgNVBAMMBkJCTCBDQTAeFw0yNTA2MTcwMjAxMjdaFw0zNTA2MTUw
+MjAxMjdaMEYxCzAJBgNVBAYTAkNOMSEwHwYDVQQKDBhCQkwgVGVjaG5vbG9naWVz
+IENvLiBMdGQxFDASBgNVBAMMC0JCTCBDQTIgUlNBMIICIjANBgkqhkiG9w0BAQEF
+AAOCAg8AMIICCgKCAgEAo4550G4c42gTKzQqixwKT089RizIdZpyOcGA679rPaOd
+WsMqVwnYPP2FpMqXKkjFbedE+SpGloi2NKCuiPNVRbq9PHOOZwTs7YLobOwf53FJ
+uO6vRFpzFfX1tlc9zlFqJvZnYO9NgHpMysidocWcgrDN/SIDywgPB5CVbYg3Vvzu
+a9fwZx9e5KT9xd5IpTqdTrWS47jQOVKLhdQCbJFIlMrblOwLBAx+fHokwqh6tkI6
+Ktuyyjw8Dysebi1ndWjKtZ2mW47r8xZ/J+z3EZqcyJMY6MRtx/zb1jBFuHtkjrb5
+Kv1DMzSKlkaNJIbvC+Mk+hI97W+SjLSRuIdC7+oJUzWaSzgu9cjXCVfmq8t4IL/3
+5hP69PK95LgLectIrP96CYAT/aVMG19FrFW0QWEyfT+kzG4jkumfPbHqY2nNkEN0
++tjj3h4WdzrWgQEojK/lhfcRFVkts74+aZoMpQP+vmL17CKmSzXk5o/eK21xgxJd
+zMbdztfTpibiXk0abfOpN+1VR+3NYa+bROAKNyGaReEGsyW2bjcjNx515Vqzj3SV
+xhMSp5vfF9E4A1jE99M/l9jQDM6RzkT0lMccGAd5tUSdNvDlrqtQaQiKv/ZsXPgX
+LTWfOpvaLNEgwdMgZMuhjpkwvAZyoYfeF9kyydjDh7bvrX//cz/VopAUlxUtQtMC
+AwEAAaNjMGEwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAQYwHQYDVR0O
+BBYEFNVJgQad1sNTN0jxVkwbJ/XM1an1MB8GA1UdIwQYMBaAFI80QmjcZ06PxCKe
+xXxJ5avdRL4eMA0GCSqGSIb3DQEBCwUAA4IBAQAvS8tyfagaGsFf9YncA2ko/Na5
+9BVF+8TlUo+32oznwIVpS1AhSgLP6rNVekXNFKbuP5htudLQ17ZRBJI/UMVyYEDq
+IN7xv7Zj+zJwF6W6haYrjb2Vk8igw1XvNULZfvVNNKIkvJUiVqEslWrC+k74crk/
+Wv8ChVf+zqvfIN6LV3esaGRL02J3AprQGb7DDhR1EefQMScDkNpGJMUmvCmfknrl
+iK8qgvQN1SWO7JRf6fNKHsN1ZQvyP0pgLWxpT3V0/0/WttqX3cMGuJF+jVUzm/Nh
+xYhFewG8vc3KzTjnwQApMA6CW554FOJWFyOD2jn5yJLT3Vue+aYDQRp4bKMx
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIICrjCCAZagAwIBAgIUOq+lNIaC2xsswkFqj5JPyVBl45gwDQYJKoZIhvcNAQEL
+BQAwQjELMAkGA1UEBhMCQ04xIjAgBgNVBAoMGUJCTCBUZWNobm9sb2dpZXMgQ28u
+LCBMdGQxDzANBgNVBAMMBkJCTCBDQTAeFw0yNTA2MTcwMjAxNDdaFw0zNTA2MTUw
+MjAxNDdaMEYxCzAJBgNVBAYTAkNOMSEwHwYDVQQKDBhCQkwgVGVjaG5vbG9naWVz
+IENvLiBMdGQxFDASBgNVBAMMC0JCTCBDQTIgRUNDMFkwEwYHKoZIzj0CAQYIKoZI
+zj0DAQcDQgAEpKTF7wRSty4DXpGJzgCPwRh8ghLlxUC3qJbyEgLqTvJgbiwYAPPH
+K7kVbVmerkqhHOT4QeWRlTG3dOQGLA2VpaNjMGEwDwYDVR0TAQH/BAUwAwEB/zAO
+BgNVHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFKuRpsjYREOyIKH7HwOE6jhGBd6NMB8G
+A1UdIwQYMBaAFI80QmjcZ06PxCKexXxJ5avdRL4eMA0GCSqGSIb3DQEBCwUAA4IB
+AQCg6PjUSSZV+4bvejcVMvgXmKzfD95osWn0ctnoMBxPDa+m+Gg+BcLT2IlFAe3E
+KYMvu4T295WQc92rjKYqW6cirFppng9uEFW2mZLimxaSmutsTftE3sbMVMJ/SLYN
+PV7TFv6mcBSIFWXwmBOIpbh4BUcVfONTvdSfIqfyAVxsq4xzc2nc6hPBpAm21Ayj
+ToC1ev/TbDJ8VllFZiEVmWWlIP3aNzAm8S2mOpxPB2WnanaZHSrvXLFhstyzwrjD
+yO1/isOZ7wtr7rcuTJdEvvvCimOZlkfRhaDoTew9tQ0E2FVpzzSinw02qmQ1xIE9
+5/H5ZzJSPkpeAHWEPnKkxg0v
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIDZTCCAk2gAwIBAgIUV1FckwXElyek1onFnQ9kL7Bk4N8wDQYJKoZIhvcNAQEL
+BQAwQjELMAkGA1UEBhMCQ04xIjAgBgNVBAoMGUJCTCBUZWNobm9sb2dpZXMgQ28u
+LCBMdGQxDzANBgNVBAMMBkJCTCBDQTAeFw0yMjA0MDQwMzQyMTFaFw0zMjA0MDEw
+MzQyMTFaMEIxCzAJBgNVBAYTAkNOMSIwIAYDVQQKDBlCQkwgVGVjaG5vbG9naWVz
+IENvLiwgTHRkMQ8wDQYDVQQDDAZCQkwgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IB
+DwAwggEKAoIBAQDL3pnDdxGOk5Z6vugiT4dpM0ju+3Xatxz09UY7mbj4tkIdby4H
+oeEdiYSZjc5LJngJuCHwtEbBJt1BriRdSVrF6M9D2UaBDyamEo0dxwSaVxZiDVWC
+eeCPdELpFZdEhSNTaT4O7zgvcnFsfHMa/0vMAkvE7i0qp3mjEzYLfz60axcDoJLk
+p7n6xKXI+cJbA4IlToFjpSldPmC+ynOo7YAOsXt7AYKY6Glz0BwUVzSJxU+/+VFy
+/QrmYGNwlrQtdREHeRi0SNK32x1+bOndfJP0sojuIrDjKsdCLye5CSZIvqnbowwW
+1jRwZgTBR29Zp2nzCoxJYcU9TSQp/4KZuWNVAgMBAAGjUzBRMB0GA1UdDgQWBBSP
+NEJo3GdOj8QinsV8SeWr3US+HjAfBgNVHSMEGDAWgBSPNEJo3GdOj8QinsV8SeWr
+3US+HjAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQABlBIT5ZeG
+fgcK1LOh1CN9sTzxMCLbtTPFF1NGGA13mApu6j1h5YELbSKcUqfXzMnVeAb06Htu
+3CoCoe+wj7LONTFO++vBm2/if6Jt/DUw1CAEcNyqeh6ES0NX8LJRVSe0qdTxPJuA
+BdOoo96iX89rRPoxeed1cpq5hZwbeka3+CJGV76itWp35Up5rmmUqrlyQOr/Wax6
+itosIzG0MfhgUzU51A2P/hSnD3NDMXv+wUY/AvqgIL7u7fbDKnku1GzEKIkfH8hm
+Rs6d8SCU89xyrwzQ0PR853irHas3WrHVqab3P+qNwR0YirL0Qk7Xt/q3O1griNg2
+Blbjg3obpHo9
+-----END CERTIFICATE-----

airkeep-0.1.0/src/airkeep/cloud.py

@@ -0,0 +1,138 @@
+"""HTTPS-only device enrollment and idempotent telemetry delivery."""
+import random
+import time
+from urllib.parse import urlsplit
+
+import httpx
+
+CLIENT_ID = 'airkeep-relay'
+DEFAULT_ORIGIN = 'https://dashboard.airkeep.io'
+
+
+def https_origin(value):
+    url = urlsplit(value)
+    if (url.scheme != 'https' or not url.hostname or url.username is not None or url.password is not None
+            or url.path not in ('', '/') or '?' in value or '#' in value
+            or any(character.isspace() for character in value)):
+        raise ValueError('Enter an HTTPS dashboard origin without a path or credentials.')
+    if url.port is not None and not 1 <= url.port <= 65535:
+        raise ValueError('Enter a valid HTTPS port.')
+    return value.rstrip('/')
+
+
+class Cloud:
+    def __init__(self, origin, client=None):
+        self.origin = https_origin(origin)
+        self.client = client or httpx.Client(timeout=10, follow_redirects=False, trust_env=False)
+
+    def post(self, path, **kwargs):
+        # Explicitly prohibit redirects even for an injected/test client.
+        return self.client.post(self.origin + path, follow_redirects=False, **kwargs)
+
+    def begin(self, installation_id):
+        response = self.post('/auth/device/code', data={'client_id': CLIENT_ID, 'installation_id': installation_id})
+        if response.status_code != 200:
+            raise ValueError('The dashboard could not begin enrollment. Try again.')
+        data = response.json()
+        if not isinstance(data, dict):
+            raise ValueError('The dashboard returned an invalid enrollment response.')
+        if not isinstance(data.get('verification_uri'), str):
+            raise ValueError('The dashboard returned an invalid verification address.')
+        uri = urlsplit(data['verification_uri'])
+        if uri.scheme != 'https' or not uri.hostname or uri.username is not None or uri.password is not None:
+            raise ValueError('The dashboard returned an invalid verification address.')
+        expires, interval = data.get('expires_in'), data.get('interval', 5)
+        if (not isinstance(expires, (int, float)) or not isinstance(interval, (int, float))
+                or not 1 <= expires <= 86400 or not 1 <= interval <= 300):
+            raise ValueError('The dashboard returned invalid enrollment timing.')
+        if not all(isinstance(data.get(key), str) and data[key] for key in ('device_code', 'user_code')):
+            raise ValueError('The dashboard returned invalid enrollment codes.')
+        return data
+
+    def poll(self, device_code):
+        response = self.post('/auth/token', data={'client_id': CLIENT_ID,
+            'grant_type': 'urn:ietf:params:oauth:grant-type:device_code', 'device_code': device_code})
+        if response.status_code == 200:
+            data = response.json()
+            if not isinstance(data, dict):
+                raise ValueError('The dashboard returned an invalid enrollment response.')
+            token = data.get('access_token')
+            kind = data.get('token_type')
+            if not isinstance(kind, str) or kind.lower() != 'bearer' or not isinstance(token, str) or not token:
+                raise ValueError('The dashboard returned an invalid enrollment token.')
+            return {'access_token': token}
+        if response.status_code == 400:
+            data = response.json()
+            error = data.get('error') if isinstance(data, dict) else None
+            if error in ('authorization_pending', 'slow_down', 'access_denied', 'expired_token'):
+                return {'error': error}
+        raise ValueError('The dashboard could not check enrollment. Try again.')
+
+    def close(self):
+        self.client.close()
+
+
+class Uploader:
+    def __init__(self, cloud, spool, token):
+        self.cloud, self.spool, self.token = cloud, spool, token
+        self.next_attempt = 0
+        self.heartbeat_at = 0
+        self.last_connected = None
+        self.failures = 0
+        self.batch_limit = 100
+        self.revoked = False
+        self.status = 'connecting'
+
+    def step(self, connected, now=None):
+        now = time.monotonic() if now is None else now
+        if self.revoked or now < self.next_attempt:
+            return
+        batch = self.spool.batch(limit=self.batch_limit)
+        heartbeat = self.last_connected != connected or now >= self.heartbeat_at
+        if not batch and not heartbeat:
+            return
+        body = {'readings': batch}
+        if heartbeat:
+            body['printerConnected'] = connected
+        try:
+            response = self.cloud.post('/v1/ingest', headers={'Authorization': 'Bearer ' + self.token}, json=body)
+            status = response.status_code
+        except httpx.HTTPError:
+            status = 0
+        if status == 204:
+            self.spool.acknowledge(batch)
+            self.failures = 0
+            self.batch_limit = 100
+            self.next_attempt = now
+            self.status = 'connected_with_quarantined_readings' if self.spool.quarantined_count() else 'connected'
+            if heartbeat:
+                self.last_connected = connected
+                self.heartbeat_at = now + 30
+            return
+        if status in (400, 422) and batch:
+            # Validation is atomic at the ingest endpoint. Narrow the batch
+            # until only the rejected event is quarantined, retaining valid
+            # live observations and backlog with their original event IDs.
+            if len(batch) > 1:
+                self.batch_limit = len(batch) // 2
+                self.status = 'isolating_invalid_reading'
+            else:
+                self.spool.quarantine(batch[0], status)
+                self.batch_limit = 100
+                self.status = 'invalid_reading_quarantined'
+            self.next_attempt = now
+            return
+        self.spool.mark_replay(batch)
+        if status in (401, 403):
+            self.revoked = True
+            self.status = 'enrollment_required'
+            return
+        self.status = 'ingest_rejected' if status in (400, 422) else 'retrying'
+        self.failures = min(self.failures + 1, 8)
+        delay = min(300, 2 ** self.failures) * random.uniform(0.8, 1.2)
+        if status == 429:
+            try:
+                delay = max(delay, min(3600, float(response.headers.get('Retry-After', 0))))
+            except ValueError:
+                pass
+        self.next_attempt = now + delay

airkeep-0.1.0/src/airkeep/collector.py

@@ -0,0 +1,77 @@
+import json
+import logging
+from pathlib import Path
+import ssl
+from typing import Protocol
+from paho.mqtt import client as mqtt
+from .telemetry import Reading, parse_readings
+
+log = logging.getLogger("airkeep.mqtt")
+BAMBU_CA = Path(__file__).with_name('bambu-ca.pem')
+
+
+class ReadingSink(Protocol):
+    def save_reading(self, reading: Reading): ...
+
+
+class Collector:
+    def __init__(self, settings, store: ReadingSink):
+        self.settings, self.store = settings, store
+        self.connected = False
+        self.error: str | None = None
+        self.client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
+        self.client.username_pw_set("bblp", settings.printer_code)
+        context = ssl.create_default_context(cafile=str(settings.ca_path))
+        context.minimum_version = ssl.TLSVersion.TLSv1_2
+        context.maximum_version = ssl.TLSVersion.TLSv1_2
+        context.check_hostname = False  # Printer cert CN is its serial, not its IP.
+        self.client.tls_set_context(context)
+        self.client.on_socket_open = self.verify_serial
+        self.client.on_connect = self.on_connect
+        self.client.on_disconnect = self.on_disconnect
+        self.client.on_connect_fail = self.on_connect_fail
+        self.client.on_message = self.on_message
+        self.client.reconnect_delay_set(2, 60)
+        self.client.connect_timeout = 8
+
+    def verify_serial(self, client, userdata, sock):
+        serials = [value for rdn in sock.getpeercert().get("subject", ())
+                   for key, value in rdn if key == "commonName"]
+        if serials != [self.settings.printer_serial]:
+            # Paho invokes this callback before sending MQTT CONNECT (including
+            # the access code). Close before raising so a retry cannot reuse it.
+            sock.close()
+            raise ssl.CertificateError("Printer certificate serial does not match configured printer")
+
+    def on_connect(self, client, userdata, flags, reason, props):
+        self.connected = not reason.is_failure
+        self.error = None if self.connected else str(reason)
+        if self.connected:
+            client.subscribe(f"device/{self.settings.printer_serial}/report")
+
+    def on_connect_fail(self, client, userdata):
+        self.connected = False
+        self.error = "Printer connection failed; check LAN settings and certificate"
+
+    def on_disconnect(self, client, userdata, flags, reason, props):
+        self.connected = False
+        self.error = "Printer disconnected; reconnecting"
+
+    def on_message(self, client, userdata, message):
+        if len(message.payload) > 1024 * 1024:
+            return
+        try:
+            payload = json.loads(message.payload)
+            if isinstance(payload, dict):
+                for reading in parse_readings(payload):
+                    self.store.save_reading(reading)
+        except (ValueError, TypeError, RecursionError):
+            log.warning("Ignored malformed printer report")
+
+    def start(self):
+        self.client.connect_async(self.settings.printer_ip, 8883, 30)
+        self.client.loop_start()
+
+    def stop(self):
+        self.client.disconnect()
+        self.client.loop_stop()

airkeep-0.1.0/src/airkeep/setup.py

@@ -0,0 +1,227 @@
+"""One-time, loopback-only browser setup. Printer secrets never leave this host."""
+import html
+import ipaddress
+from pathlib import Path
+import re
+import time
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs
+import uuid
+
+import httpx
+
+from .cloud import Cloud, DEFAULT_ORIGIN, https_origin
+from .collector import BAMBU_CA, Collector
+
+
+@dataclass(repr=False)
+class PrinterSettings:
+    printer_ip: str
+    printer_serial: str
+    printer_code: str = field(repr=False)
+    ca_path: Path = BAMBU_CA
+
+    @classmethod
+    def validate(cls, fields):
+        address = ipaddress.ip_address(fields['printer_ip'].strip())
+        local = (ipaddress.ip_network('10.0.0.0/8'), ipaddress.ip_network('172.16.0.0/12'),
+                 ipaddress.ip_network('192.168.0.0/16'), ipaddress.ip_network('169.254.0.0/16'),
+                 ipaddress.ip_network('fc00::/7'), ipaddress.ip_network('fe80::/10'))
+        if not any(address in network for network in local):
+            raise ValueError('Enter the printer’s private LAN IP address.')
+        serial = fields['printer_serial'].strip()
+        code = fields['printer_code'].strip()
+        if not re.fullmatch(r'[A-Za-z0-9]{8,32}', serial):
+            raise ValueError('Enter the serial shown in printer settings.')
+        if not re.fullmatch(r'[A-Za-z0-9]{8}', code):
+            raise ValueError('Enter the eight-character LAN access code.')
+        return cls(str(address), serial, code)
+
+    def private_config(self):
+        return {'printer_ip': self.printer_ip, 'printer_serial': self.printer_serial, 'printer_code': self.printer_code}
+
+
+class DiscardReadings:
+    def save_reading(self, reading):
+        pass
+
+
+def test_printer(settings, timeout=12):
+    collector = Collector(settings, DiscardReadings())
+    try:
+        collector.start()
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if collector.connected:
+                return True
+            time.sleep(0.1)
+        return False
+    except (OSError, ValueError):
+        return False
+    finally:
+        collector.stop()
+
+
+class Setup:
+    def __init__(self, spool, port, printer_test=test_printer, cloud_factory=Cloud):
+        self.spool = spool
+        self.origin = f'http://127.0.0.1:{port}'
+        self.printer_test, self.cloud_factory = printer_test, cloud_factory
+        self.printer = None
+        self.cloud = None
+        self.enrollment = None
+        self.message = ''
+        self.completed_at = None
+        self.installation_id = uuid.uuid4().hex
+        self.interval = 5
+        self.next_poll = 0
+
+    def tick(self):
+        if not self.enrollment or self.completed_at is not None:
+            return
+        now = time.monotonic()
+        if now >= self.expires_at:
+            self.enrollment = None
+            self.message = 'The sign-in code expired. Begin sign-in again.'
+            return
+        if now < self.next_poll:
+            return
+        self.next_poll = now + self.interval
+        try:
+            result = self.cloud.poll(self.enrollment['device_code'])
+        except (ValueError, KeyError, httpx.HTTPError):
+            self.message = 'Waiting for the dashboard connection. Retrying.'
+            return
+        error = result.get('error')
+        if error == 'slow_down':
+            self.interval += 5
+            self.next_poll = now + self.interval
+        elif error in ('access_denied', 'expired_token'):
+            self.enrollment = None
+            self.message = 'Sign-in ended. Begin sign-in again.'
+        elif not error:
+            self.spool.configure(dict(self.printer.private_config(), origin=self.cloud.origin,
+                                      installation_id=self.installation_id, token=result['access_token']))
+            self.completed_at = time.monotonic()
+
+    def close(self):
+        if self.cloud:
+            self.cloud.close()
+
+    def page(self):
+        content = '<h1>Connect Airkeep</h1>'
+        if self.completed_at is not None:
+            content += '<p>Setup complete. The agent is collecting printer readings and sending them to your dashboard. You can close this window.</p>'
+        elif self.enrollment:
+            uri = html.escape(self.enrollment['verification_uri'], quote=True)
+            code = html.escape(self.enrollment['user_code'])
+            content += f'<p>Open <a href="{uri}" target="_blank" rel="noreferrer">your Airkeep dashboard</a>, sign in, and enter this code.</p><p><strong>{code}</strong></p><p>This page checks approval automatically.</p>'
+        elif self.printer:
+            content += '<p>Printer TLS, serial and LAN access code verified.</p><form method="post" action="/enroll"><button>Begin dashboard sign-in</button></form>'
+        else:
+            content += f'''<p>Keep your P2S on the same LAN, enable LAN access, and copy its settings here.</p>
+            <form method="post" action="/printer">
+            <label>Printer LAN IP <input name="printer_ip" required autocomplete="off"></label>
+            <label>Printer serial <input name="printer_serial" required autocomplete="off"></label>
+            <label>LAN access code <input name="printer_code" type="password" required autocomplete="off"></label>
+            <label>Dashboard HTTPS origin <input name="origin" value="{DEFAULT_ORIGIN}" type="url" required></label>
+            <button>Test printer connection</button></form>'''
+        if self.message:
+            content += '<p role="status">' + html.escape(self.message) + '</p>'
+        refresh = '<meta http-equiv="refresh" content="3">' if self.enrollment and self.completed_at is None else ''
+        return f'''<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">{refresh}<title>Airkeep setup</title>
+        <style>body{{font:18px system-ui;max-width:38rem;margin:4rem auto;padding:1rem;background:#faf8f1;color:#20251e}}label{{display:block;margin:1rem 0}}input{{display:block;width:95%;font:inherit;padding:.5rem}}button{{font:inherit;padding:.6rem 1rem}}strong{{font:2rem monospace}}</style><main>{content}</main></html>'''.encode()
+
+    def handler(self):
+        setup = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def setup(self):
+                super().setup()
+                self.connection.settimeout(5)
+
+            def log_message(self, *args):
+                # Keep form values and enrollment codes out of logs.
+                pass
+
+            def valid_host(self):
+                return self.headers.get('Host') == setup.origin.removeprefix('http://')
+
+            def respond(self, status=200, content=b''):
+                self.send_response(status)
+                self.send_header('Content-Type', 'text/html; charset=utf-8')
+                self.send_header('Content-Length', str(len(content)))
+                self.send_header('Cache-Control', 'no-store')
+                # Browsers need to send the real Origin on local form posts.
+                self.send_header('Referrer-Policy', 'same-origin')
+                self.send_header('X-Content-Type-Options', 'nosniff')
+                self.send_header('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'")
+                if status == 303:
+                    self.send_header('Location', '/')
+                self.end_headers()
+                self.wfile.write(content)
+
+            def do_GET(self):
+                if not self.valid_host() or self.path != '/':
+                    self.respond(403)
+                    return
+                self.respond(content=setup.page())
+
+            def do_POST(self):
+                if (not self.valid_host() or self.headers.get('Origin') != setup.origin
+                        or setup.completed_at is not None):
+                    self.respond(403)
+                    return
+                try:
+                    length = int(self.headers.get('Content-Length', '0'))
+                    if (not 0 <= length <= 4096 or (length == 0 and self.path != '/enroll')
+                            or self.headers.get('Content-Type') != 'application/x-www-form-urlencoded'):
+                        self.respond(400)
+                        return
+                    fields = {key: value[0] for key, value in parse_qs(self.rfile.read(length).decode(), max_num_fields=8).items() if len(value) == 1}
+                except (ValueError, UnicodeError):
+                    self.respond(400)
+                    return
+                try:
+                    if self.path == '/printer' and setup.enrollment is None:
+                        printer = PrinterSettings.validate(fields)
+                        origin = https_origin(fields['origin'].strip())
+                        if not setup.printer_test(printer):
+                            setup.message = 'Printer test failed. Check LAN reachability, serial, access code and LAN mode, then try again.'
+                        else:
+                            setup.printer = printer
+                            if setup.cloud:
+                                setup.cloud.close()
+                            setup.cloud = setup.cloud_factory(origin)
+                            setup.message = ''
+                    elif self.path == '/enroll' and setup.printer and setup.enrollment is None:
+                        setup.enrollment = setup.cloud.begin(setup.installation_id)
+                        setup.interval = float(setup.enrollment.get('interval', 5))
+                        setup.next_poll = time.monotonic() + setup.interval
+                        setup.expires_at = time.monotonic() + float(setup.enrollment['expires_in'])
+                        setup.message = ''
+                    else:
+                        self.respond(404)
+                        return
+                except (ValueError, KeyError, httpx.HTTPError):
+                    setup.message = 'Setup could not complete. Check the settings and dashboard connection, then try again.'
+                # The enrollment page refreshes automatically, so serve it at GET /.
+                self.respond(303)
+
+        return Handler
+
+
+def run_setup(spool, port, stopped=None):
+    setup = Setup(spool, port)
+    try:
+        with HTTPServer(('127.0.0.1', port), setup.handler()) as server:
+            server.timeout = 0.5
+            print(f'Open {setup.origin} to set up your printer.', flush=True)
+            while setup.completed_at is None or time.monotonic() - setup.completed_at < 4:
+                if stopped is not None and stopped.is_set():
+                    raise SystemExit('Local setup stopped.')
+                server.handle_request()
+                setup.tick()
+    finally:
+        setup.close()

airkeep-0.1.0/src/airkeep/spool.py

@@ -0,0 +1,102 @@
+"""Private configuration and bounded, transactional telemetry outbox."""
+import json
+import sqlite3
+import threading
+import time
+import uuid
+
+
+class Spool:
+    def __init__(self, path):
+        self.lock = threading.Lock()
+        self.db = sqlite3.connect(path, check_same_thread=False)
+        self.db.row_factory = sqlite3.Row
+        self.db.executescript('''
+            PRAGMA secure_delete=ON;
+            CREATE TABLE IF NOT EXISTS configuration (id INTEGER PRIMARY KEY CHECK(id=1), data TEXT NOT NULL);
+            CREATE TABLE IF NOT EXISTS samples (
+                sequence INTEGER PRIMARY KEY AUTOINCREMENT, event_id TEXT UNIQUE NOT NULL,
+                ams_id TEXT NOT NULL, observed REAL NOT NULL, data TEXT NOT NULL,
+                replay INTEGER NOT NULL DEFAULT 0);
+            CREATE TABLE IF NOT EXISTS sampling (ams_id TEXT PRIMARY KEY, observed REAL NOT NULL);
+            CREATE TABLE IF NOT EXISTS quarantine (
+                event_id TEXT PRIMARY KEY, rejected_at REAL NOT NULL,
+                status INTEGER NOT NULL, data TEXT NOT NULL);
+        ''')
+        self.mark_replay()
+
+    def configuration(self):
+        with self.lock:
+            row = self.db.execute('SELECT data FROM configuration WHERE id=1').fetchone()
+        return json.loads(row['data']) if row else None
+
+    def configure(self, config):
+        # Enrollment replacement and spool deletion commit together. Never send a
+        # previous account's backlog using a new account's bearer token.
+        with self.lock, self.db:
+            self.db.execute('DELETE FROM samples')
+            self.db.execute('DELETE FROM sampling')
+            self.db.execute('DELETE FROM quarantine')
+            self.db.execute('INSERT OR REPLACE INTO configuration VALUES (1,?)', (json.dumps(config),))
+
+    def save_reading(self, reading):
+        with self.lock, self.db:
+            self._prune(time.time())
+            previous = self.db.execute('SELECT observed FROM sampling WHERE ams_id=?', (reading.amsID,)).fetchone()
+            # Resume sampling after the system clock is corrected backwards.
+            if previous and 0 <= reading.observedAt - previous['observed'] < 30:
+                return
+            self.db.execute('INSERT INTO samples(event_id,ams_id,observed,data,replay) VALUES (?,?,?,?,?)',
+                            (str(uuid.uuid4()), reading.amsID, reading.observedAt,
+                             reading.model_dump_json(), 0))
+            self.db.execute('INSERT OR REPLACE INTO sampling VALUES (?,?)', (reading.amsID, reading.observedAt))
+
+    def _prune(self, now):
+        self.db.execute('DELETE FROM samples WHERE observed < ?', (now - 86400,))
+        self.db.execute('DELETE FROM sampling WHERE observed < ?', (now - 86400,))
+        self.db.execute('DELETE FROM quarantine WHERE rejected_at < ?', (now - 86400,))
+
+    def batch(self, now=None, limit=100):
+        now = time.time() if now is None else now
+        with self.lock, self.db:
+            self._prune(now)
+            # A fresh observation can resume live updates while history drains.
+            # Previously attempted events remain replay even if still recent.
+            rows = self.db.execute('''
+                SELECT *, (replay=0 AND observed BETWEEN ? AND ?) AS live
+                FROM samples
+                ORDER BY live DESC, CASE WHEN live THEN observed END DESC, observed,sequence
+                LIMIT ?
+            ''', (now - 30, now, min(100, max(1, limit)))).fetchall()
+        return [dict(json.loads(row['data']), eventID=row['event_id'],
+                     replay=not bool(row['live'])) for row in rows]
+
+    def acknowledge(self, readings):
+        with self.lock, self.db:
+            self.db.executemany('DELETE FROM samples WHERE event_id=?', [(item['eventID'],) for item in readings])
+
+    def mark_replay(self, readings=None):
+        with self.lock, self.db:
+            if readings is None:
+                self.db.execute('UPDATE samples SET replay=1')
+            else:
+                self.db.executemany('UPDATE samples SET replay=1 WHERE event_id=?',
+                                    [(item['eventID'],) for item in readings])
+
+    def quarantine(self, reading, status, now=None):
+        now = time.time() if now is None else now
+        with self.lock, self.db:
+            self.db.execute('INSERT OR REPLACE INTO quarantine VALUES (?,?,?,?)',
+                            (reading['eventID'], now, status, json.dumps(reading)))
+            self.db.execute('DELETE FROM samples WHERE event_id=?', (reading['eventID'],))
+            self._prune(now)
+            self.db.execute('''DELETE FROM quarantine WHERE event_id NOT IN (
+                SELECT event_id FROM quarantine ORDER BY rejected_at DESC,event_id LIMIT 100)''')
+
+    def quarantined_count(self):
+        with self.lock, self.db:
+            self._prune(time.time())
+            return self.db.execute('SELECT COUNT(*) FROM quarantine').fetchone()[0]
+
+    def close(self):
+        self.db.close()

airkeep-0.1.0/src/airkeep/telemetry.py

@@ -0,0 +1,65 @@
+"""Bambu AMS report parsing shared by the relay and dashboard server."""
+import math
+import time
+
+from pydantic import BaseModel
+
+
+class Reading(BaseModel):
+    amsID: str
+    humidity: float
+    temperature: float | None
+    rawIndex: int | None
+    observedAt: float
+
+
+def parse_readings(payload: dict, now: float | None = None) -> list[Reading]:
+    now = time.time() if now is None else now
+    if not isinstance(payload, dict) or not math.isfinite(now):
+        return []
+    values = []
+    report = payload.get("print")
+    if not isinstance(report, dict):
+        return []
+    ams = report.get("ams")
+    if not isinstance(ams, dict):
+        return []
+    units = ams.get("ams") or []
+    if not isinstance(units, list):
+        return []
+    for unit in units[:16]:
+        if not isinstance(unit, dict):
+            continue
+        try:
+            identifier = unit.get("id")
+            if isinstance(identifier, bool) or not isinstance(identifier, (str, int)):
+                continue
+            identifier = str(identifier)
+            if not 1 <= len(identifier) <= 8 or not identifier.isascii() or not identifier.isdecimal():
+                continue
+            # Missing humidity_raw is a delta update, never a zero reading.
+            if isinstance(unit.get("humidity_raw"), bool):
+                continue
+            humidity = float(unit["humidity_raw"])
+            if not math.isfinite(humidity) or not 1 <= humidity <= 100:
+                continue  # Zero is a known boot/sensor fault; do not label it dry.
+            temperature = None
+            if "temp" in unit:
+                try:
+                    temp = float(unit["temp"])
+                    if math.isfinite(temp) and 0 <= temp <= 100:
+                        temperature = temp
+                except (ValueError, TypeError, OverflowError):
+                    pass
+            index = None
+            try:
+                raw = int(unit.get("humidity", 0))
+                if 1 <= raw <= 5:
+                    index = raw
+            except (ValueError, TypeError, OverflowError):
+                pass
+            values.append(Reading(amsID=identifier, humidity=humidity,
+                                  temperature=temperature, rawIndex=index, observedAt=now))
+        except (KeyError, ValueError, TypeError, OverflowError):
+            continue
+    return values