@turquoisebay/mqtt 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.16] - 2026-02-03
+
+### Docs
+- Remove real IPs from documentation
+- Add security note for trusted MQTT clients
+- Add pairing/handshake TODO
+
+## [0.1.15] - 2026-02-03
+
+### Added
+- Echo `correlationId` from inbound JSON in outbound replies
+
+### Docs
+- Clarify how `senderId` maps to sessions vs `correlationId`
+
 ## [0.1.14] - 2026-02-03
 
 ### Fixed
@@ -89,6 +104,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [ ] GitHub Actions CI
 - [ ] Last Will and Testament support
 - [ ] Multiple topic subscriptions
+- [ ] Pairing/handshake for trusted clients
 
 ## [0.1.0] - Unreleased
 

package/README.md

@@ -60,6 +60,13 @@ openclaw gateway restart
 
 ## Usage
 
+### Sessions & correlation IDs (important)
+
+- **Sessions are keyed by `senderId`** → OpenClaw uses `mqtt:{senderId}` as the SessionKey, so memory and conversation history are grouped by sender.
+- **`correlationId` is request‑level only** → if you include it in inbound JSON, it’s echoed back in the outbound reply for client-side matching. It does **not** create a new session or change memory.
+
+If you want separate conversations, use distinct `senderId`s.
+
 ### Receiving messages (inbound)
 
 Messages published to your `inbound` topic will be processed by OpenClaw.
@@ -70,7 +77,7 @@ You can send either plain text or JSON (recommended):
 mosquitto_pub -t "openclaw/inbound" -m "Alert: Service down on playground"
 
 # JSON (recommended)
-mosquitto_pub -t "openclaw/inbound" -m '{"senderId":"pg-cli","text":"hello"}'
+mosquitto_pub -t "openclaw/inbound" -m '{"senderId":"pg-cli","text":"hello","correlationId":"abc-123"}'
 ```
 
 ### Sending messages (outbound)
@@ -117,11 +124,15 @@ automation:
         payload: "{{ trigger.payload }}"
 ```
 
+## Security
+
+**Important:** Any client that can publish to the inbound topic has full access to your OpenClaw agent. Treat MQTT as a **trusted channel only** (restricted broker, auth, private network). If you need untrusted access, add a validation layer before publishing to `openclaw/inbound`.
+
 ## Development
 
 ```bash
-# Clone
-git clone turq@10.0.20.9:/opt/git/openclaw-mqtt.git
+# Clone (replace with your host)
+git clone ssh://<host>/opt/git/openclaw-mqtt.git
 cd openclaw-mqtt
 
 # Install deps

package/dist/src/channel.js

@@ -144,6 +144,7 @@ async function handleInboundMessage(opts) {
         // Extract message body and sender from payload
         let messageBody;
         let senderId;
+        let correlationId;
         if (parsedPayload && typeof parsedPayload === "object") {
             messageBody =
                 parsedPayload.message ??
@@ -159,6 +160,10 @@ async function handleInboundMessage(opts) {
                     parsedPayload.from ??
                     parsedPayload.service ??
                     topic.replace(/\//g, "-");
+            correlationId =
+                parsedPayload.correlationId ??
+                    parsedPayload.requestId ??
+                    undefined;
         }
         else {
             messageBody = text;
@@ -202,6 +207,7 @@ async function handleInboundMessage(opts) {
                                 text: payload.text,
                                 kind: info.kind,
                                 ts: Date.now(),
+                                ...(correlationId ? { correlationId } : {}),
                             });
                             await mqttClient.publish(outboundTopic, outboundPayload, qos);
                             log?.info?.(`MQTT: sent reply to ${outboundTopic}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turquoisebay/mqtt",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "MQTT channel plugin for OpenClaw - bidirectional messaging via MQTT brokers",
   "type": "module",
   "main": "dist/index.js",