carterkit 0.5.0__tar.gz → 0.5.2__tar.gz

{carterkit-0.5.0 → carterkit-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: carterkit
-Version: 0.5.0
+Version: 0.5.2
 Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
 Author: Carter Beaudoin
 License-Expression: MIT

{carterkit-0.5.0 → carterkit-0.5.2}/carterkit/__init__.py

@@ -21,7 +21,9 @@ from pathlib import Path
 from . import catalog, grid, codegen, infer, theming, tune, dynamic
 from .buffer import LayoutBuffer, BufferError
 from .validate import validate_layout as _validate_layout, format_findings
-from .client import CarterClient, notify_http, CarterNotifyError
+from .client import (CarterClient, notify_http, CarterNotifyError,
+                     device_refresh_http, CarterDeviceRevoked)
+from .relay import LocalRelay, port_in_use, lan_ip
 from . import bind
 from .controls import build, control
 from .layout import Layout, Fragment, Control, Condition
@@ -78,6 +80,7 @@ def lint_dynamic_traffic(layout: dict, observed, catalog_: dict = None) -> list:
 __all__ = [
     "__version__", "PROTOCOL_VERSION",
     "CarterClient", "notify_http", "CarterNotifyError",
+    "device_refresh_http", "CarterDeviceRevoked",
     "LayoutBuffer", "BufferError",
     "controls", "doc", "doc_markdown", "examples", "validate_layout",
     "lint_dynamic_traffic", "format_findings", "controldocs_dir",

carterkit-0.5.2/carterkit/client.py

@@ -0,0 +1,298 @@
+"""carter_connect — minimal Connect+ hub client. Wraps MeshSocket + E2EE so a maker
+connects hardware to the Connect+ relay in a few lines. Transparent encryption when an
+e2ee_key is provided (broadcasts AND request replies); cleartext otherwise.
+
+Also exposes `notify_http(...)` and `CarterClient.notify(...)` for sending a one-shot
+push to every device on a Connect+ account (POST /alerts/notify). `notify_http` is
+stdlib-only (urllib) so a cron job can fire a notification without the MeshSocket stack."""
+import asyncio
+import base64
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+try:
+    from meshsocket import MeshSocket          # pip install meshsocket
+    from .e2ee import E2EESession
+except ImportError:  # keep notify_http importable without the MeshSocket/crypto stack
+    MeshSocket = None
+    E2EESession = None
+
+
+class CarterNotifyError(Exception):
+    """Raised when /alerts/notify rejects a send. `status` is the HTTP code (0 for a
+    client-side/config error); `detail` is the server body or a description."""
+    def __init__(self, status, detail):
+        super().__init__(f"notify failed ({status}): {detail}")
+        self.status = status
+        self.detail = detail
+
+
+def notify_http(validator_url, session_jwt, title, body, *, channel=None, category=None,
+                badge=None, sound="default", data=None, _send=None):
+    """Send a one-shot push to every device on the account (POST /alerts/notify).
+
+    Stdlib-only. `validator_url` is the Connect+ validator base URL; `session_jwt` is the
+    Connect+ account session token (NOT the MeshSocket auth token). Returns the parsed
+    `{"sent": N, "stale": M}` response. Raises CarterNotifyError on an HTTP error or
+    ValueError on invalid title/body. `_send` is a test seam: a callable
+    (url, headers, body_bytes) -> dict that bypasses the network."""
+    if not title or len(title) > 256:
+        raise ValueError("title must be non-empty and <= 256 chars")
+    if not body or len(body) > 256:
+        raise ValueError("body must be non-empty and <= 256 chars")
+
+    payload = {"title": title, "body": body, "sound": sound}
+    if channel is not None:
+        payload["channel"] = channel
+    if category is not None:
+        payload["category"] = category
+    if badge is not None:
+        payload["badge"] = badge
+    if data is not None:
+        payload["data"] = data
+
+    url = validator_url.rstrip("/") + "/alerts/notify"
+    headers = {"Authorization": session_jwt, "Content-Type": "application/json"}
+    body_bytes = json.dumps(payload).encode()
+
+    if _send is not None:
+        return _send(url, headers, body_bytes)
+
+    req = urllib.request.Request(url, data=body_bytes, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        raise CarterNotifyError(e.code, e.read().decode(errors="replace")) from None
+
+
+class CarterDeviceRevoked(Exception):
+    """Raised when an external device's refresh is denied (HTTP 403) — the owner revoked the
+    device or their Connect+ lapsed. Terminal: the device should stop trying to reconnect."""
+
+
+def device_refresh_http(validator_url, device_id, refresh_token, *, _send=None):
+    """Re-mint an external device's short-lived relay token (POST /devices/sessions/refresh).
+
+    Stdlib-only, mirroring `notify_http`. `validator_url` is the Connect+ validator base URL;
+    `device_id` + `refresh_token` are the long-lived credential handed to the device at mint
+    time. Returns the parsed `{"deviceToken": ..., "expiresAt": ...}`. Raises
+    CarterDeviceRevoked on HTTP 403 (revoked / owner lapsed); other HTTP errors propagate so a
+    caller can retry transient failures. `_send` is a test seam: (url, headers, body) -> dict."""
+    url = validator_url.rstrip("/") + "/devices/sessions/refresh"
+    headers = {"Content-Type": "application/json"}
+    body_bytes = json.dumps({"deviceId": device_id, "refreshToken": refresh_token}).encode()
+
+    def _do():
+        if _send is not None:
+            return _send(url, headers, body_bytes)
+        req = urllib.request.Request(url, data=body_bytes, headers=headers, method="POST")
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read().decode())
+
+    try:
+        return _do()
+    except urllib.error.HTTPError as e:
+        if e.code == 403:
+            raise CarterDeviceRevoked(e.read().decode(errors="replace")) from None
+        raise CarterNotifyError(e.code, e.read().decode(errors="replace")) from None
+
+
+class CarterClient:
+    def __init__(self, gateway_url, token, channel, role="device", name="hub", e2ee_key=None,
+                 validator_url=None, session_jwt=None, room=False,
+                 device_id=None, refresh_token=None, refresh_interval=2400):
+        if MeshSocket is None:
+            raise ImportError("MeshSocket is unavailable; run `pip install meshsocket`. "
+                              "(notify_http does not need it.)")
+        self._sock = MeshSocket(url=gateway_url, name=name, auth_token=token,
+                                channel=channel, role=role, can_broadcast=True, can_route=False)
+        # `room=True` matches the app's `mode: room`: a symmetric group cipher so the hub
+        # shares an encrypted room with several members. Otherwise the directional 1:1 cipher.
+        if e2ee_key:
+            secret = base64.b64decode(e2ee_key)
+            self._session = (E2EESession.group(secret) if room
+                             else E2EESession(secret, is_device_side=(role in ("device", "hub"))))
+        else:
+            self._session = None
+        # Connect+ validator credentials for notify(); distinct from the mesh auth token.
+        self._validator_url = validator_url
+        self._session_jwt = session_jwt
+        # External-device self-refresh: a headless device provisioned via POST /devices holds
+        # a long-lived refresh secret and re-mints its short-lived relay token before expiry,
+        # updating the socket's auth_token so any reconnect uses the fresh one. Revocation
+        # (HTTP 403) surfaces as `revoked = True` and tears the socket down.
+        self._device_id = device_id
+        self._refresh_token = refresh_token
+        self._refresh_interval = refresh_interval
+        self._refresh_task = None
+        self.revoked = False
+        # Control-state authority (matches the app's Phase 2): when enabled, this hub answers
+        # a replica's control_sync_request with a snapshot of set_control_state() values.
+        self._control_state = {}
+        self._state_version = 0
+        self._is_state_authority = False
+        self._broadcast_handler = None
+        self._broadcast_registered = False
+
+    def _open(self, payload):
+        if self._session and isinstance(payload, dict) and E2EESession.is_envelope(payload):
+            return self._session.open(payload)
+        return payload
+
+    def _seal(self, data):
+        return self._session.seal(data) if (self._session and data is not None) else data
+
+    def on(self, msg_type, handler):
+        """Register a command handler. handler(data: dict) gets DECRYPTED data and may return a
+        dict reply (auto-encrypted). Sync or async handlers are supported."""
+        async def wrapper(payload):
+            data = self._open(payload)
+            result = handler(data)
+            if asyncio.iscoroutine(result):
+                result = await result
+            return self._seal(result) if result is not None else None
+        self._sock.on(msg_type, wrapper)
+
+    def on_broadcast(self, handler):
+        """Register a handler for relayed broadcasts. handler(data: dict) gets DECRYPTED data."""
+        self._broadcast_handler = handler
+        self._ensure_broadcast_listener()
+
+    def _ensure_broadcast_listener(self):
+        """Arm the single 'broadcast' socket listener (one handler per event) that dispatches
+        to the control-state responder and then the user's on_broadcast handler."""
+        if self._broadcast_registered:
+            return
+        self._broadcast_registered = True
+
+        async def wrapper(payload):
+            await self._dispatch_broadcast(self._open(payload))
+            return None
+        self._sock.on("broadcast", wrapper)
+
+    async def _dispatch_broadcast(self, data):
+        # Control-state sync frames are protocol, not app data — consume them here so they
+        # never reach the user's on_broadcast handler. Only an authority answers a request.
+        if isinstance(data, dict) and data.get("msg_type") in ("control_sync_request", "control_snapshot"):
+            if self._is_state_authority and data.get("msg_type") == "control_sync_request":
+                await self._answer_control_sync(data)
+            return
+        if self._broadcast_handler is not None:
+            result = self._broadcast_handler(data)
+            if asyncio.iscoroutine(result):
+                await result
+
+    def set_control_state(self, control_id, value):
+        """Record the authoritative current value of a control so the hub can answer a
+        replica's control_sync_request. Call this alongside your normal broadcast of the
+        value — it only updates the snapshot served to late joiners / reconnecting devices."""
+        self._control_state[control_id] = value
+
+    def enable_state_authority(self):
+        """Declare this hub the source of truth for control state. It will answer replicas'
+        control_sync_request broadcasts with a control_snapshot of set_control_state()
+        values — the hub side of the app's Phase 2 designated-authority sync."""
+        self._is_state_authority = True
+        self._ensure_broadcast_listener()
+
+    async def _answer_control_sync(self, data):
+        to = data.get("from")
+        if not to or not self._control_state:
+            return
+        self._state_version += 1
+        await self.broadcast("control_snapshot",
+                             {"to": to, "v": self._state_version, "controls": dict(self._control_state)})
+
+    async def broadcast(self, msg_type, data):
+        await self._sock.send("broadcast_request", self._seal({**data, "msg_type": msg_type}))
+
+    async def chat(self, text, *, name="Server", role="device", channel=None, msg_id=None, **extra):
+        """Send a channel chat message a chat control will display, as a bubble from `name`.
+
+        Builds the exact shape the app requires — a unique `id`, a `sender.name`, an
+        ISO-8601 `timestamp`, and the `chat_message` type — which is easy to get subtly
+        wrong by hand (a missing `id` is silently dropped). Extra keys pass through
+        (e.g. `_from=` to tag your own echo). Returns the message id."""
+        mid = msg_id or uuid.uuid4().hex
+        payload = {
+            "id": mid,
+            "text": text,
+            "sender": {"name": name, "role": role},
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        }
+        if channel is not None:
+            payload["channel"] = channel
+        payload.update(extra)
+        await self.broadcast("chat_message", payload)
+        return mid
+
+    async def request(self, command, data, timeout=5.0):
+        reply = await self._sock.request(command, self._seal(data), timeout=timeout)
+        return self._open(reply) if reply is not None else None
+
+    async def notify(self, title, body, *, channel=None, category=None,
+                     badge=None, sound="default", data=None):
+        """Send a one-shot push to every device on the account. Requires `validator_url`
+        and `session_jwt` to have been passed to the constructor (the mesh auth token is
+        NOT the session JWT — distinct credentials). Returns `{"sent": N, "stale": M}`."""
+        if not self._validator_url or not self._session_jwt:
+            raise CarterNotifyError(0, "notify() requires validator_url and session_jwt "
+                                       "on the CarterClient constructor")
+        return await asyncio.to_thread(
+            notify_http, self._validator_url, self._session_jwt, title, body,
+            channel=channel, category=category, badge=badge, sound=sound, data=data)
+
+    async def refresh_device_token(self):
+        """Re-mint this device's relay token from its refresh secret and apply it to the
+        socket, so any reconnect uses the fresh token. Returns the parsed response. Raises
+        CarterDeviceRevoked if the device was revoked or the owner's Connect+ lapsed."""
+        if not (self._validator_url and self._device_id and self._refresh_token):
+            raise CarterNotifyError(0, "refresh_device_token() needs validator_url, device_id, "
+                                       "and refresh_token on the CarterClient constructor")
+        res = await asyncio.to_thread(device_refresh_http, self._validator_url,
+                                      self._device_id, self._refresh_token)
+        token = res.get("deviceToken") if isinstance(res, dict) else None
+        if token:
+            self._sock.auth_token = token  # MeshSocket re-sends this on every (re)connect
+        return res
+
+    async def _device_refresh_loop(self):
+        """Keep the short-lived device token fresh ahead of expiry. On revocation, stop the
+        socket and flag `revoked`; transient errors are retried on the next tick."""
+        while True:
+            await asyncio.sleep(self._refresh_interval)
+            try:
+                await self.refresh_device_token()
+            except CarterDeviceRevoked:
+                self.revoked = True
+                await self._sock.stop()
+                return
+            except Exception:
+                pass  # transient (network/5xx) — retry next interval
+
+    async def connect(self):
+        await self._sock.start()
+        await self._sock.wait_until_ready()
+        # Auto-start the refresh loop only for a self-refreshing external device.
+        if self._device_id and self._refresh_token and self._validator_url and self._refresh_task is None:
+            self._refresh_task = asyncio.create_task(self._device_refresh_loop())
+
+    async def close(self):
+        if self._refresh_task is not None:
+            self._refresh_task.cancel()
+            self._refresh_task = None
+        await self._sock.stop()
+
+    async def __aenter__(self):
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+        return False

{carterkit-0.5.0 → carterkit-0.5.2}/carterkit/controldocs/index.md

@@ -29,7 +29,7 @@ A layout defines **tabs**, each containing a **grid** of controls. Controls rang
 
 ## The Control System
 
-Every control in CAR-TER is declared as a JSON object with a `type`, `id`, and grid `position`. The system supports **28 control types** across three categories:
+Every control in CAR-TER is declared as a JSON object with a `type`, `id`, and grid `position`. The system supports **27 control types** across three categories:
 
 ### Input Controls
 Buttons, toggles, sliders, steppers, pickers, date pickers, text inputs, color pickers, and segmented controls. These send user actions to your server. Container controls — **carousels**, **flip cards**, and **accordions** — arrange sets of groups into swipeable pages, flippable faces, and collapsible sections.

{carterkit-0.5.0 → carterkit-0.5.2}/carterkit/controldocs/label.md

@@ -16,9 +16,9 @@ fields:
     description: SF Symbol before text
   - name: style
     type: enum
-    values: [default, headline, title, caption, mono, large-mono]
+    values: [default, headline, title, caption, mono, large-mono, terminal]
     default: default
-    description: Text style variant
+    description: Text style variant (terminal = ANSI terminal renderer)
   - name: tint
     type: color
     default: "#FFFFFF"
@@ -28,6 +28,10 @@ fields:
     values: [leading, center, trailing]
     default: leading
     description: Text alignment
+  - name: scrollable
+    type: bool
+    default: false
+    description: Fixed-height scrolling terminal/log view that keeps the latest line in view (pair with controlHeight)
   - name: formatValue
     type: string
     description: Value display format (see formatValue table)
@@ -58,8 +62,9 @@ Inherits all [[shared-properties]]. Key fields:
 | `label` | string | — | Alternative to `text` |
 | `icon` | string | — | SF Symbol before text |
 | `style` | string | `"default"` | See [[style-properties#Label Styles]] |
-| `tint` | string | white | Text and icon color |
+| `tint` | string | white | Text and icon color (terminal: default text colour over the dark backdrop) |
 | `align` | string | `"leading"` | `"leading"`, `"center"`, `"trailing"` |
+| `scrollable` | bool | `false` | Fixed-height scrolling terminal/log view (pair with `controlHeight`) |
 | `formatValue` | string | — | Value display format (see formatValue table below) |
 
 ## Format Values
@@ -86,6 +91,29 @@ Inherits all [[shared-properties]]. Key fields:
 | `"caption"` | `.caption` |
 | `"mono"` | `.subheadline` monospaced |
 | `"large-mono"` | `.title3` monospaced medium |
+| `"terminal"` | Monospaced **ANSI terminal** — see [Terminal style](#terminal-style) |
+
+## Terminal style
+
+`style: "terminal"` (and, as a shortcut, **`mono`/`large-mono` + `scrollable`**) renders the
+text as a real terminal instead of a plain mono label — purpose-built for piping a captured
+shell/tmux pane to the phone:
+
+- **ANSI styling** — colour (16 / 256 / truecolor), **bold**, dim, *italic*, underline, and
+  reverse are parsed from the escape codes and rendered. Plain text (no escapes) renders
+  normally.
+- **Pane-matched scaling** — the font auto-scales so the source's column width exactly fills
+  the view, so box-drawing and ASCII line up like the real pane. If a server prepends a
+  `CSI 8;rows;cols t` size report, that column count is used; otherwise the widest line is.
+- **Dark backdrop** — drawn on its own dark background (independent of the app theme) so
+  ANSI colours have the contrast they were designed for.
+- **Pinch to zoom** — pinch to scale the text past the fitted size; **double-tap** snaps back
+  to fit. Content wider/taller than the view scrolls both ways.
+- **Sizing** — set `controlHeight` for the on-screen height; `fontSize` caps the fitted font
+  before zoom. Keeps the latest line in view and auto-scrolls on update.
+
+Feed it like any synced label (a `.string` value); see the
+[tmux-bridge](https://carterbeaudoin.net/CAR-TER) server for a complete example.
 
 ## Examples
 
@@ -127,6 +155,21 @@ Inherits all [[shared-properties]]. Key fields:
 }
 ```
 
+### Terminal snapshot (live pane)
+```json
+{
+  "type": "label",
+  "id": "pane-snapshot",
+  "position": [1, 0],
+  "span": [5, 4],
+  "style": "terminal",
+  "scrollable": true,
+  "controlHeight": 360,
+  "text": "(waiting for pane…)",
+  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "snapshot" }, "valuePath": "text" }]
+}
+```
+
 ## Behavior
 - When synced, the `text` field serves as a placeholder until the first sync value arrives
 - Text updates animate with a smooth numeric content transition

{carterkit-0.5.0 → carterkit-0.5.2}/carterkit/controldocs/log-console.md

@@ -75,6 +75,11 @@ themeFields:
 
 A scrolling terminal-style log viewer. Displays timestamped log lines pushed via sync, with color-coded severity levels and monospace rendering.
 
+> For a full **ANSI terminal** — raw escape-code colour/bold, pane-width auto-scaling and
+> pinch-to-zoom (e.g. mirroring a captured shell/tmux pane) — use a [[label]] with
+> `style: "terminal"` instead. The log console is line-oriented (level colours), not an
+> escape-code renderer.
+
 ## Type
 `"logConsole"`
 

{carterkit-0.5.0 → carterkit-0.5.2}/carterkit/controldocs/text-input.md

@@ -22,6 +22,34 @@ fields:
     values: [default, search, multiline]
     default: default
     description: Display style variant
+  - name: sendButton
+    type: bool
+    default: false
+    description: Growing composer with a Send button (Return inserts a newline)
+  - name: minLines
+    type: number
+    default: 1
+    description: Composer starting line count
+  - name: maxLines
+    type: number
+    default: 6
+    description: Composer max lines before it scrolls internally
+  - name: autocorrect
+    type: bool
+    default: false
+    description: Default autocorrect/caps (off = ASCII keyboard, terminal-friendly)
+  - name: autocorrectToggle
+    type: bool
+    default: false
+    description: Inline Aa button that flips autocorrect on the live keyboard
+  - name: keyboard
+    type: enum
+    values: [ascii, default, url, email, numbers]
+    description: Keyboard type
+  - name: clearOnSubmit
+    type: bool
+    default: false
+    description: Clear the field after the return-key submit
   - name: tint
     type: color
     default: "#667eea"
@@ -87,6 +115,12 @@ Inherits all [[shared-properties]]. Key fields:
 | `defaultValue` | string | — | Initial text |
 | `style` | string | `"default"` | `"default"`, `"search"`, `"multiline"` |
 | `tint` | string | `"#667eea"` | Accent color |
+| `sendButton` | bool | `false` | Turn the field into a growing composer with a Send button (Return = newline) |
+| `minLines` | int | `1` | Composer starting line count |
+| `maxLines` | int | `6` | Composer max lines before it scrolls internally |
+| `autocorrect` | bool | `false` | Default autocorrect/caps; off ⇒ ASCII keyboard (terminal-friendly) |
+| `autocorrectToggle` | bool | `false` | Show the inline **Aa** toggle |
+| `keyboard` | string | — | `"ascii"`, `"default"`, `"url"`, `"email"`, `"numbers"` |
 | `clearOnSubmit` | bool | `false` | Clear the field after the return-key submit (for entry forms where the typed value shouldn't linger) |
 | `hideBackground` | bool | `false` | Remove glass background |
 | `hideLabel` | bool | `false` | Hide the header label |
@@ -102,6 +136,23 @@ Search-style field with magnifying glass icon and clear button.
 ### `"multiline"`
 Expands vertically for multi-line text entry.
 
+## Composer & keyboard
+
+Set `sendButton: true` to turn the field into a **growing composer**: it grows from `minLines`
+up to `maxLines` then scrolls inside, **Return inserts a newline**, and a **Send** button
+submits. Ideal for chat or command entry.
+
+Keyboard behaviour, tuned for command entry:
+
+- **`autocorrect`** defaults to `false` — autocorrect/autocapitalization off with an ASCII
+  keyboard, so typed commands aren't "corrected." Set `true` for prose. `keyboard` overrides
+  the keyboard type explicitly.
+- **`autocorrectToggle`** shows an inline **Aa** button that flips autocorrect at runtime and
+  reconfigures the **live** keyboard immediately (no refocus needed). It also appears on the
+  above-keyboard bar.
+- An above-keyboard **Hide** button lets you dismiss the keyboard to reach the
+  controls/tabs underneath it.
+
 ## Example
 
 ```json
@@ -117,8 +168,26 @@ Expands vertically for multi-line text entry.
 }
 ```
 
+### Command composer
+```json
+{
+  "type": "textInput",
+  "id": "pane-input",
+  "position": [7, 0],
+  "span": [1, 4],
+  "placeholder": "type a command…",
+  "icon": "chevron.right",
+  "sendButton": true,
+  "autocorrectToggle": true,
+  "autocorrect": false,
+  "maxLines": 6,
+  "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast", "payload": { "msg_type": "command", "text": "{{value}}" } }
+}
+```
+
 ## Behavior
-- Action fires when the user presses return/submit
+- Default field: the action fires when the user presses return/submit
+- Composer (`sendButton: true`): **Send** submits and **Return inserts a newline**
 - The `{{value}}` placeholder is replaced with the current text content
 
 ## Related

{carterkit-0.5.0 → carterkit-0.5.2}/carterkit/e2ee.py

@@ -19,14 +19,27 @@ def _nonce(counter: int) -> bytes:
 
 
 class E2EESession:
-    def __init__(self, secret: bytes, is_device_side: bool, seal_salt: bytes = None):
+    def __init__(self, secret: bytes, is_device_side: bool = False, seal_salt: bytes = None,
+                 is_group: bool = False):
         self._secret = secret
-        self._seal_info = b"d2c v2" if is_device_side else b"c2d v2"
-        self._open_info = b"c2d v2" if is_device_side else b"d2c v2"
+        if is_group:
+            # Symmetric room mode: every member seals AND opens with the same "grp v2" label,
+            # so any member reads any other. Multi-sender nonce reuse is prevented because each
+            # sender carries an independent per-session salt (in the envelope).
+            self._seal_info = self._open_info = b"grp v2"
+        else:
+            self._seal_info = b"d2c v2" if is_device_side else b"c2d v2"
+            self._open_info = b"c2d v2" if is_device_side else b"d2c v2"
         self._seal_salt = seal_salt if seal_salt is not None else os.urandom(16)
         self._seal_key = derive_key(secret, self._seal_salt, self._seal_info)
         self._counter = 0
 
+    @classmethod
+    def group(cls, secret: bytes, seal_salt: bytes = None) -> "E2EESession":
+        """Symmetric room session matching the app's `mode: room` group cipher — used by a
+        hub that shares an encrypted room with several members."""
+        return cls(secret, is_group=True, seal_salt=seal_salt)
+
     def seal(self, payload: dict) -> dict:
         n = self._counter
         self._counter += 1

carterkit-0.5.2/carterkit/relay.py

@@ -0,0 +1,101 @@
+"""Run a tiny embedded MeshSocket relay for local / LAN testing of a layout.
+
+The relay is the WebSocket hub both the app and your server connect to. For real
+self-hosting you point at the Connect+ relay (``wss://relay…``); for a quick local
+test this spins one up in-process so there's nothing else to run.
+
+It refuses to start on a port that's already in use — the usual cause of a confusing
+"connects then immediately drops" loop: a second relay silently fails to bind, its
+hub lands on the *first* one, and two same-named hubs evict each other every couple
+of seconds. Failing fast with a clear message beats debugging that.
+
+    from carterkit import LocalRelay, CarterClient
+
+    async with LocalRelay(port=8765, key="dev-key") as relay:
+        hub = CarterClient("ws://127.0.0.1:8765", token="dev-key",
+                           channel="home", role="device")
+        await hub.connect()
+        ...                       # push values; the app connects to the same relay
+"""
+from __future__ import annotations
+
+import asyncio
+import socket as _socket
+
+try:                                  # ships with the meshsocket dependency
+    from socket_server import MeshServer
+except ImportError:                   # pragma: no cover - environment guard
+    MeshServer = None
+
+
+def lan_ip(override: str | None = None) -> str:
+    """This machine's LAN IP — the address to bake into a layout so a phone can reach
+    the relay. Returns `override` if given, or falls back to 127.0.0.1 when offline."""
+    if override:
+        return override
+    s = _socket.socket(_socket.AF_INET, _socket.SOCK_DGRAM)
+    try:
+        s.connect(("8.8.8.8", 80))        # no packets sent; just picks the egress interface
+        return s.getsockname()[0]
+    except OSError:
+        return "127.0.0.1"
+    finally:
+        s.close()
+
+
+def port_in_use(port: int, host: str = "127.0.0.1") -> bool:
+    """True if something is already accepting connections on ``(host, port)``.
+
+    A 0.0.0.0 listener also answers on 127.0.0.1, so the default probe catches the
+    common "another relay is already running" case."""
+    probe = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
+    probe.settimeout(0.3)
+    try:
+        return probe.connect_ex((host if host not in ("", "0.0.0.0") else "127.0.0.1", port)) == 0
+    finally:
+        probe.close()
+
+
+class LocalRelay:
+    """An in-process MeshSocket relay with shared-key auth, for local testing.
+
+    ``key`` is the shared key clients must present (``""`` runs open, no auth).
+    ``on_join(name, ip)`` fires when a client authenticates — handy for pushing a
+    fresh snapshot to a device the moment it connects. Use it as an async context
+    manager, or call :meth:`start` / :meth:`stop` yourself. Raises ``RuntimeError``
+    if the port is already in use and ``ImportError`` if the server isn't installed.
+    """
+
+    def __init__(self, port: int = 8765, key: str = "", host: str = "0.0.0.0", on_join=None):
+        if MeshServer is None:
+            raise ImportError("LocalRelay needs the MeshSocket server; run `pip install meshsocket`.")
+        self.port, self.key, self.host, self.on_join = port, key, host, on_join
+        self._server = None
+        self._task: asyncio.Task | None = None
+
+    async def start(self) -> "LocalRelay":
+        if port_in_use(self.port, self.host):
+            raise RuntimeError(
+                f"port {self.port} is already in use — another relay or tester is probably "
+                f"running. Stop it (e.g. `pkill -f tester.py`) or pass a different port.")
+        auth = (lambda tok, ip: tok == self.key) if self.key else (lambda tok, ip: True)
+        on_auth = None
+        if self.on_join:
+            on_auth = lambda client, ip, tok: self.on_join(getattr(client, "name", "?"), ip)
+        self._server = MeshServer(host=self.host, port=self.port,
+                                  auth_handler=auth, on_authenticated=on_auth)
+        self._task = asyncio.create_task(self._server.start())
+        await asyncio.sleep(0.5)      # let the listener bind before clients dial in
+        return self
+
+    async def stop(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+
+    async def __aenter__(self) -> "LocalRelay":
+        return await self.start()
+
+    async def __aexit__(self, *exc) -> bool:
+        await self.stop()
+        return False