petaledge-bridge 0.2.0__tar.gz

petaledge_bridge-0.2.0/LICENSE

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

petaledge_bridge-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# What goes into the source distribution (the wheel only ever holds the petaledge_bridge package).
+# The wire protocol document ships with the source; tests, release tooling and build output do not.
+include LICENSE
+include README.md
+include PROTOCOL.md
+prune tests
+prune packaging
+prune build
+prune dist

petaledge_bridge-0.2.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: petaledge-bridge
+Version: 0.2.0
+Summary: Petal Edge Camera Bridge: relays IP / CCTV cameras on a local network to the Petal Edge Model Playground (outbound only).
+Author: Petal Edge
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://edge.petalsautomation.com
+Project-URL: Documentation, https://edge.petalsautomation.com/docs/
+Keywords: petal edge,cctv,ip camera,rtsp,mjpeg,edge ai,model playground
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: av>=12
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=9.5
+Requires-Dist: websockets>=12
+Requires-Dist: cryptography>=41
+Requires-Dist: keyring>=24
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# Petal Edge Camera Bridge
+
+A small program that runs on a computer on the same network as your IP / CCTV cameras and relays
+their video to your **Model Playground** in Petal Edge, so you can try a model on a live camera.
+
+- The bridge reads the camera (RTSP or HTTP MJPEG) on your local network, keeps only the newest
+  frame, shrinks it, and sends JPEG frames to Petal Edge over one outbound, encrypted WebSocket.
+- Prediction runs on the Petal Edge server, in your Playground session. The bridge never gets
+  the model.
+- It only makes **outbound** connections. It opens no listening port, needs no port forwarding,
+  no VPN and no admin rights.
+
+The wire protocol is documented in `PROTOCOL.md` in the source distribution.
+
+## Install
+
+Python 3.10 or newer.
+
+```bash
+pip install petaledge-bridge
+petaledge-bridge --version
+```
+
+Or, to keep it out of your other Python projects, `pipx install petaledge-bridge`.
+
+Dependencies (installed automatically): `av` (PyAV, bundles FFmpeg), `numpy`, `pillow`,
+`websockets`, `cryptography` and `keyring`.
+
+## Pairing
+
+1. In the Model Playground choose the **CCTV** source. The page shows a command like
+   `petaledge-bridge connect K7Q4MPX2.AAISEM2EKVTHPCEZVK54ZXPO74 --server https://api.edge.petalsautomation.com`
+2. Run it on the computer next to your cameras. Spaces, dashes and lower case in the code are fine.
+3. The bridge prints a **key fingerprint** such as `2E1E·61CE`. Check that the Playground shows
+   the same one. If it doesn't, stop and pair again.
+4. Leave the bridge running. Add cameras in the Playground: the browser encrypts each camera's
+   address and password for this bridge only.
+
+Later, after a restart: `petaledge-bridge run`.
+
+| Command | What it does |
+|---|---|
+| `petaledge-bridge connect <code> [--server URL] [--name NAME] [--allow-public-cameras]` | Pair, save the pairing, then run |
+| `petaledge-bridge run [--allow-public-cameras]` | Reconnect with the saved pairing |
+| `petaledge-bridge status` | Show the saved pairing and its key fingerprint |
+| `petaledge-bridge forget` | Delete the saved pairing (and any saved camera passwords) from this computer |
+| `petaledge-bridge cameras` | List the cameras whose passwords this bridge keeps; `--forget <id>` or `--forget-all` removes them |
+
+Add `-v` before the command for debug logs (`petaledge-bridge -v run`).
+
+The server defaults to `$PETALEDGE_API_URL`, else `https://api.edge.petalsautomation.com`.
+Only `https://` servers are accepted; `http://` is accepted for `localhost` and `127.0.0.1`
+(development).
+
+The pairing is saved in `~/.petaledge/bridge.json` (set `PETALEDGE_BRIDGE_HOME` to use another
+folder). It holds the bridge id, the bridge token, the pairing secret and the server address,
+**never camera addresses or passwords**. Camera passwords you choose to save ("Save the password on
+the bridge" in the Playground) go to the operating system's password store (Windows Credential Manager,
+macOS Keychain, Secret Service on Linux desktops) through `keyring`, bound to that camera's address;
+`cameras.json` next to `bridge.json` lists them by name and host:port only. A computer without a secure
+password store (a headless Raspberry Pi, say) simply doesn't offer saving. The server forgets bridge
+tokens after 24 hours (30 days without use for a bridge you chose to remember); the
+bridge then tells you to pair again.
+
+## Requirements for the bridge computer
+
+**Host**
+- An always-on computer on the **same network or VLAN as the camera** (or one that can route to it).
+- Windows 10/11, macOS 12+, or Linux x86_64 / arm64 (including Raspberry Pi 4/5 with a 64-bit OS),
+  with Python 3.10+.
+- About **1 CPU core and 300 MB RAM per stream at 720p**. Use the camera's **sub-stream**;
+  decoding a 4K main stream on a Raspberry Pi is not supported.
+- Runs as a normal user. No admin rights, drivers or GPU.
+
+**Network**
+- Outbound HTTPS / WSS on **port 443** to the Petal Edge API host.
+- From the bridge to the camera on the LAN: RTSP (554 / 8554) or HTTP (80 / 8080 / the camera's port).
+- **No inbound ports**, no port forwarding, no VPN; works behind NAT.
+- Upload per stream: about 0.25-0.6 Mbit/s at 5 fps / 640 px, 1-2.5 Mbit/s at 10 fps / 960 px.
+
+**Camera**
+- RTSP (H.264, H.265, MJPEG) over TCP (default) or UDP, or HTTP MJPEG. NVR channels are addressed
+  by their own RTSP path.
+- Use the **sub-stream at 720p or below**.
+- Create a **viewer-only camera account** for the bridge (least privilege).
+- ONVIF discovery, PTZ and two-way audio are not supported.
+
+## Security properties
+
+- **No listening socket.** Everything is outbound.
+- **Sealed commands only.** Every camera command is encrypted and authenticated in your browser
+  (AES-256-GCM under a key derived from the pairing secret, which the server never sees). The
+  bridge refuses anything that doesn't open with its key, is for another bridge / operation /
+  stream, is more than 60 s old, or repeats a nonce. Only then does it contact the camera. The
+  camera address is inside the seal, so a compromised server can neither read the password nor
+  point the bridge somewhere else.
+- **Local networks only by default.** The camera host is resolved once and must be a private
+  (10/8, 172.16/12, 192.168/16), loopback, link-local, CGNAT (100.64/10) or IPv6 ULA / link-local
+  address; the bridge then connects to that IP (no second lookup). Public addresses need
+  `--allow-public-cameras` (not saved; give it on each `run`).
+- **Credentials stay in memory**, only for the stream's lifetime. The camera URL is built inside
+  the bridge; every log line, error and result is redacted (`rtsp://user:pass@host` becomes
+  `rtsp://***@host`). FFmpeg's own logging is turned off.
+- The settings file is written atomically with mode 0600 (folder 0700) on macOS / Linux. On
+  Windows it relies on your user profile folder's default, user-only permissions.
+- Revoke a bridge any time with **Disconnect bridge** in the Playground, and/or
+  `petaledge-bridge forget` on the computer.
+
+## Troubleshooting (error codes)
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `auth_failed` | The camera refused the username / password (401) or the account may not view this stream (403) | Check the credentials; use an account allowed to view the stream. The bridge does not retry, to avoid account lock-outs. |
+| `not_found` | No stream at that path (404) | Check the RTSP path for your camera / NVR channel (often the sub-stream path). |
+| `refused` | The camera refused the connection | Check the port and that RTSP / HTTP streaming is enabled on the camera. |
+| `timeout` | No answer, or no picture in time | Check that this computer can reach the camera (same network, firewall, VPN routes). Try the TCP transport. |
+| `unreachable` | Name not found or no route to the camera | Check the address; use the camera's IP address. |
+| `unsupported` | Not a stream the bridge can decode | Use H.264 / H.265 / MJPEG over RTSP, or HTTP MJPEG. |
+| `blocked_address` | The camera address is not on a local network | Use the camera's LAN address, or start the bridge with `--allow-public-cameras` if you really mean a public camera. |
+| `bad_seal` | The bridge refused the command | Check that this computer's clock is correct (within 60 s). If the fingerprints don't match, pair again. |
+| `bad_request` | The camera details are not valid | Check the scheme (rtsp / http), host, port and path. |
+| `error` | Anything else, or the camera ended the stream | Run with `-v` for details (credentials are redacted). |
+
+Other messages:
+- *"Pairing failed"* / *"The server no longer accepts this bridge"*: the code was wrong, used or
+  expired (10 minutes), or the bridge token expired / was revoked. Get a new code in the
+  Playground and run `petaledge-bridge connect <code>`.
+- *"Not connected to Petal Edge. Retrying..."*: the bridge reconnects by itself (1 s up to 30 s).
+  Check that outbound port 443 is allowed.
+- A clock warning after connecting: sync this computer's clock, or sealed commands will be refused.
+
+## Development
+
+The tests live in the Petal Edge repository, not in the PyPI package. From a checkout of it:
+
+```bash
+pip install -e "camera_bridge[test]"
+python -m pytest camera_bridge/tests -q
+```
+
+They need no network and no camera: they generate a short video with PyAV and read it through an
+internal test hook, and they run a tiny local WebSocket server that plays the Petal Edge API side.
+
+## License
+
+Apache License 2.0. See `LICENSE`.

petaledge_bridge-0.2.0/PROTOCOL.md

@@ -0,0 +1,172 @@
+# Petal Edge Camera Bridge: protocol v1
+
+The single source of truth for the three parties of Model Playground CCTV / IP camera input
+(plan: `docs/New_implementation/playground.md` §7):
+
+- **Browser**: the Model Playground page (`app/src/components/playground/sources/ip-camera/*`).
+- **Server**: the Petal Edge API (`api/app/services/playground/{bridges,streams}.py`,
+  routes in `api/app/api/v1/endpoints/playground.py`).
+- **Bridge**: this package, running on a computer on the camera's network. It only makes
+  **outbound** connections and never opens a listening socket.
+
+Prediction always happens on the server, in the user's Playground model session, through the same
+image handler as uploads and the webcam. The bridge only reads the camera and relays frames.
+
+---
+
+## 1. Pairing (user-scoped, no project)
+
+1. The browser generates a 16-byte random **pairing secret `S`** (WebCrypto). `S` is never sent to
+   the server.
+2. The browser calls `POST /api/v1/playground/bridges/pairing` and receives a **server code** `C`
+   (8 characters from `23456789ABCDEFGHJKLMNPQRSTUVWXYZ`, single use, 10 minutes, bound to the user).
+3. The browser shows the command
+   `petaledge-bridge connect <C>.<base32(S)> --server <API origin>`
+   where `base32` is RFC 4648, upper case, **no padding** (26 characters for 16 bytes).
+   The bridge ignores spaces and `-` in the code, and accepts lower case.
+4. The bridge opens the bridge WebSocket (§3) and sends `hello` with `pairing_code: C` (**never `S`**).
+5. The server binds the bridge to the user who created `C`, answers `hello_ack` with a new
+   `bridge_id` and a `bridge_token` (for reconnects; the server stores only its SHA-256).
+6. Browser and bridge both derive the command key `K` and a fingerprint (§2) and show the
+   fingerprint, so the user can confirm they match.
+
+The bridge keeps `bridge_id`, `bridge_token`, `S` and the server origin in its config file
+(`~/.petaledge/bridge.json`, mode 0600). It reconnects with `bridge_token` (not the code).
+Bridge tokens expire after 24 h on the server; the bridge then asks the user to pair again.
+
+## 2. Keys and sealed commands
+
+All binary values travelling in JSON are **standard base64 with padding**.
+
+```
+K           = HKDF-SHA256(ikm = S, salt = UTF-8(bridge_id), info = "pe-bridge-v1",             L = 32 bytes)
+fingerprint = HKDF-SHA256(ikm = S, salt = UTF-8(bridge_id), info = "pe-bridge-fingerprint-v1", L = 4 bytes)
+              shown as upper-case hex "AABB·CCDD" (two groups of 4, U+00B7 between them)
+```
+
+A **sealed command** is authored by the browser and opened only by the bridge:
+
+```
+plaintext = UTF-8(JSON) of
+  { "v": 1,
+    "op": "camera_test" | "stream_start",
+    "bridge_id": "<bridge_id>",
+    "stream_id": "<stream_id>"            (stream_start only; omitted for camera_test)
+    "nonce": "<base64 of 16 random bytes>",
+    "issued_at": <unix seconds, integer>,
+    "camera": { "name": str, "scheme": "rtsp" | "http",
+                "host": str, "port": int | null, "path": str | null,
+                "transport": "tcp" | "udp" | null },
+    "username": str | null,
+    "password": str | null,
+    "profile": { "id": "pf_…", "save": bool }   (optional, since 0.2; only to a bridge advertising "profiles") }
+
+aad    = UTF-8("<bridge_id>|<op>|<stream_id or empty string>")
+iv     = 12 random bytes
+ct     = AES-256-GCM(key = K, iv, aad, plaintext)      ciphertext || 16-byte tag (WebCrypto / cryptography layout)
+sealed = { "v": 1, "iv": base64(iv), "ct": base64(ct) }
+```
+
+The bridge **refuses** (error code `bad_seal`) a sealed command when:
+- it does not decrypt under its own `K` with the AAD built from its own `bridge_id` and the
+  envelope's `op` / `stream_id`;
+- the plaintext `v` is not 1, or its `op`, `bridge_id` or `stream_id` differ from the envelope;
+- `|now − issued_at| > 60` seconds;
+- its `nonce` was already seen in the last 10 minutes.
+
+The camera address is inside the seal, so a server can neither read credentials nor redirect the
+bridge to another host. Test vectors: `camera_bridge/tests/vectors.json` (both implementations must
+reproduce `K`, the fingerprint, and `ct` for the given `iv`).
+
+**Saved camera profiles (0.2, optional).** A bridge whose OS keyring is usable advertises
+`"capabilities": ["profiles"]` in its `hello`. The browser then names each camera's profile inside the
+seal: `id = "pf_" + base64url(SHA-256(UTF-8("<bridge_id>|<scheme>|<host, lower case>|<port>|<path>")))[:24]`
+(derived, so the browser stores nothing about the camera). With `"save": true` on a `camera_test` that
+succeeds, the bridge stores `{username, password}` in its OS keyring under service `petaledge-bridge`,
+bound to the camera address, and answers `"profile_saved": true|false`. A later command with no
+`password` and the same profile id gets the saved credentials filled in by the bridge, but only for the
+exact address they were saved for (otherwise `bad_request`) and only when its `username` is empty or the
+same. Nothing saved is not an error (the camera may need no password). No plaintext fallback exists:
+without a secure keyring the capability isn't advertised. `petaledge-bridge cameras` lists and forgets
+profiles (names and host:port only); `forget` removes them all.
+
+Credential hygiene: the browser clears the password from its state right after sealing. The bridge
+keeps credentials in memory for the stream's lifetime only, builds the camera URL internally, and
+redacts every string that leaves the process (logs, errors, results): `rtsp://user:pass@host`
+becomes `rtsp://***@host`.
+
+## 3. Bridge ↔ server WebSocket
+
+`wss://<api>/api/v1/playground/bridges/ws`. Text frames are JSON; binary frames are video frames.
+The first message must be `hello` within 10 s, otherwise the server closes with 1008.
+
+| Direction | Message | Notes |
+|---|---|---|
+| bridge → server | `{"type":"hello","pairing_code":C}` or `{"type":"hello","bridge_token":T,"bridge_id":B}` plus `"name"`, `"version"`, `"os"`, `"key_fingerprint"`, and since 0.2 `"capabilities":["profiles"]?` | `name` ≤ 64 chars (computer name by default); unknown capabilities are dropped |
+| server → bridge | `{"type":"hello_ack","bridge_id":B,"bridge_token":T?,"server_time":unix}` | `bridge_token` only on pairing |
+| bridge → server | `{"type":"key_fingerprint","key_fingerprint":"AABB·CCDD"}` | once, right after a **pairing** `hello_ack` (the pairing `hello` sends `key_fingerprint: null`, because the fingerprint needs `bridge_id`); the server keeps the first value |
+| server → bridge | `{"type":"error","code":...,"message":...}` then close 1008 | bad code / token |
+| server → bridge | `{"type":"camera_test","req_id":R,"sealed":{...}}` | |
+| bridge → server | `{"type":"camera_test_result","req_id":R,"ok":true,"width":W,"height":H,"fps":F\|null,"codec":"h264"\|...,"thumbnail_jpeg_b64":"...","profile_saved":bool?}` or `{"type":"camera_test_result","req_id":R,"ok":false,"error_code":E,"message":M}` | thumbnail ≤ 50 KB; message already redacted |
+| server → bridge | `{"type":"stream_start","stream_id":S,"stream_no":N,"sealed":{...},"max_fps":F,"max_side":P}` | `stream_no` is a u32 used in frame headers |
+| server → bridge | `{"type":"stream_stop","stream_id":S}` | |
+| server → bridge | `{"type":"credit","stream_id":S,"n":k}` | the bridge may send `k` more frames for S |
+| bridge → server | `{"type":"stream_state","stream_id":S,"state":"connecting"\|"live"\|"reconnecting"\|"stopped"\|"error","attempt":n?,"error_code":E?,"message":M?}` | |
+| bridge → server | **binary frame** (§4) | only while it holds a credit; at most `max_fps` per second |
+| both | `{"type":"ping"}` / `{"type":"pong"}` | server pings every 20 s; a bridge silent for 45 s is offline |
+
+Error codes the bridge reports (camera test and stream state): `auth_failed`, `not_found`,
+`refused`, `timeout`, `unreachable`, `unsupported`, `blocked_address`, `bad_seal`, `bad_request`,
+`error`. Messages are plain language and contain the user's host and port but never credentials.
+
+Credits: the server grants 2 credits (a separate `credit` message) right after `stream_start`, one
+more each time it has taken a frame, and 2 again when a bridge reconnects while the stream is still
+running. A bridge keeps its streams across a dropped connection (60 s, camera open, credits reset to
+0) and resumes them on the server's credits; it stops a stream itself after 120 s without credits. The bridge keeps only the newest decoded frame (no queue); when it has a credit and its
+`max_fps` interval has passed, it encodes and sends the newest frame.
+
+## 4. Binary frame
+
+```
+offset size  field
+0      4     magic "PGF1"
+4      4     stream_no   u32 little-endian
+8      4     seq         u32 little-endian (per stream, starts at 0)
+12     8     ts_ms       u64 little-endian (bridge wall clock, ms since epoch)
+20     2     width       u16 little-endian
+22     2     height      u16 little-endian
+24     …     JPEG bytes  (≤ 512 KB; long side ≤ max_side; quality ≈ 80)
+```
+
+The server forwards the same frame format to the browser (§5), with its own `stream_no`.
+
+## 5. Browser ↔ server
+
+REST (all require the user's JWT; another user's ids are 404):
+
+| Method & path | Body | Returns |
+|---|---|---|
+| `POST /playground/bridges/pairing` | — | `{"server_code","expires_at"}` |
+| `GET /playground/bridges` | — | `[{"bridge_id","name","online","version","os","key_fingerprint","pairing_code","connected_at","last_seen","remembered","expires_at","capabilities"}]` |
+| `PUT /playground/bridges/{bridge_id}/remember` | `{"remember": bool}` | the bridge as listed. On: its token lives 30 days without use (each reconnect restarts the period) and its record (no secrets; the token only as a SHA-256) is persisted, so it survives API restarts; the browser keeps K, non-extractable, in IndexedDB. Off: back to the 24 h lifetime, not persisted. |
+| `DELETE /playground/bridges/{bridge_id}` | — | 204; revokes the token and closes the bridge socket |
+| `POST /playground/bridges/{bridge_id}/camera-test` | `{"sealed":{...}}` | the bridge's `camera_test_result` minus `type`/`req_id` (504 `bridge_timeout` after 12 s, 409 `bridge_offline`) |
+| `POST /playground/streams` | `{"stream_id","session_id","bridge_id","sealed","preview_fps","inference_fps"}` | `{"stream_id","state"}`; `stream_id` is client-generated (22-64 chars `[A-Za-z0-9_-]`) because it is bound into the seal |
+| `PATCH /playground/streams/{stream_id}` | `{"inference": bool?, "threshold": number\|null?}` | `{"stream_id","inference","threshold"}` |
+| `DELETE /playground/streams/{stream_id}` | — | 204 |
+| `POST /playground/streams/{stream_id}/ws-token` | — | `{"token","expires_at"}` (single use, 60 s) |
+
+Browser stream WebSocket: `wss://<api>/api/v1/playground/streams/{stream_id}/ws?token=...`
+
+| Direction | Message |
+|---|---|
+| server → browser | binary frame (§4) for preview, while the browser holds a credit, at most `preview_fps` |
+| server → browser | `{"type":"result","seq":n,"ts_ms":t,"result":<PlaygroundPrediction>}` when inference is on |
+| server → browser | `{"type":"state","state":"waiting_for_bridge"\|"connecting"\|"live"\|"reconnecting"\|"bridge_offline"\|"stopped","reason":str?,"error_code":E?,"message":M?}` |
+| server → browser | `{"type":"stats","preview_fps":x,"model_fps":y,"latency_ms":z}` every 2 s |
+| browser → server | `{"type":"ack","n":1}` (one credit per frame drawn; the server starts with 2) |
+| browser → server | `{"type":"pause"}` / `{"type":"resume"}` (stop / restart preview frames, e.g. tab hidden) |
+
+A stream stops on: `DELETE`, the browser socket closed for more than 30 s, `pause` held for more
+than 60 s, the model session removed or expired, the bridge offline for more than 60 s, 30 minutes
+of total time, or server shutdown. Limits: 1 live stream per user, 3 per API process.