fix: prevent RF crosstalk via ServiceEnvelope payload mutation for virtual channels (#41)

* docs: amend v1.6.2 release notes

* fix: prevent RF crosstalk via ServiceEnvelope payload mutation for virtual channels

Virtual channel topic rewriting was insufficient to prevent RF rebroadcast.
The radio firmware uses packet.channel (PSK hash) to look up the decryption
key, not the MQTT topic string. Packets from extra MQTT roots sharing the
same channel key (e.g. LongFast/AQ==) were being decrypted and rebroadcast
over RF by the local node, bridging two independent MQTT server regions.

Fix: mutate the ServiceEnvelope protobuf before radio injection:
- envelope.channel_id -> virtual channel name (e.g. 'NC-LongFast')
- packet.channel      -> synthetic hash unique to the virtual channel name

The radio firmware finds no matching PSK for the synthetic hash, cannot
decrypt, and does not rebroadcast. The encrypted payload bytes are unchanged,
so MeshMonitor can still decrypt using the original key via its Channel
Database entry for the virtual channel name.

Confirmed via live MQTT packet inspection: packet.channel carries the PSK
hash (not a slot index), and radio firmware matches by hash, not by name.

* docs: update Virtual Channels documentation with MeshMonitor Channel Database setup

* fix: elevate virtual channel rewrite log to INFO; fix docs log example

* chore: release v1.6.3

* docs: clarify MeshMonitor Channel DB matches by PSK not channel name

* docs: add MeshMonitor Enforce Channel Name Validation guidance for shared-PSK channels

* docs: remove confusing MeshMonitor custom name setup, channels work natively

* fix: revert channel_id mutation, keep original names for native MeshMonitor support

* docs: clarify Enforce Channel Name Validation usage for shared keys

* docs: document known defect where MeshMonitor merges shared-key channels

Author: LN4CY

CONFIG.md

@@ -122,26 +122,46 @@ BLE support requires custom implementation using the `bleak` library. See the [m
 
 ### Extra MQTT Roots (Virtual Channels)
 
-Monitor encrypted traffic from additional regions beyond your primary root topic **without causing RF crosstalk**.
+Monitor encrypted traffic from additional MQTT servers or root topics beyond your primary node configuration **without causing RF crosstalk**.
 
 **Configuration:**
 ```env
-EXTRA_MQTT_ROOTS=msh/US/OH, msh/US/CA:California
+# Format: <root>:<alias>, ...
+# The alias becomes the channel prefix in MeshMonitor (e.g. NC-LongFast)
+EXTRA_MQTT_ROOTS=msh/US/NC:NC, msh/US/OH:Ohio
 ```
 
-When configured, the proxy automatically subscribes to `{root}/2/e/#` for each specified root in addition to your node's primary root. 
+When configured, the proxy subscribes to `{root}/2/e/#` for each extra root in addition to your node's primary root.
 
-**Topic Rewriting (Virtual Channels)**:
-To prevent "crosstalk" (where downloading Ohio's `LongFast` traffic inadvertently causes your local Michigan USB radio to broadcast it over RF), the proxy utilizes a **Virtual Channel** mapping.
+**How Virtual Channels Work:**
 
-If a packet arrives from an extra root, its channel name is rewritten on-the-fly to include a prefix:
-- `msh/US/OH` defaults to the prefix `OH` ➔ `OH-LongFast`
-- `msh/US/CA:California` uses custom prefix `California` ➔ `California-LongFast`
+When a packet arrives from an extra root, the proxy performs a two-part rewrite before injecting it into the radio:
 
-By rewriting the channel name to a "Virtual Channel" (e.g., `OH-LongFast`), your local USB radio ignores it. However, if you are using MeshMonitor's Channel Database, the encrypted payload is successfully decrypted, allowing you to seamlessly monitor cross-region traffic!
+1. **Topic rewrite:** The MQTT topic channel name is prefixed with the alias.
+   - `msh/US/NC/2/e/LongFast/!abc123` → `msh/US/2/e/NC-LongFast/!abc123`
+
+2. **Payload mutation (crosstalk prevention):** The proxy mutates the `packet.channel` field inside the `ServiceEnvelope` protobuf.
+   - `packet.channel` integer (PSK hash) → a synthetic hash derived from the virtual channel name
+
+   The radio firmware uses this PSK hash to look up its decryption key. Since no local channel has the synthetic hash configured, the radio **cannot decrypt the packet and will not rebroadcast it over RF** — completely preventing cross-region crosstalk.
+
+**MeshMonitor Channel Database Setup:**
+
+Because the proxy preserves the original `channel_id` string and leaves the encrypted payload bytes untouched, MeshMonitor natively receives the exact original packet data.
+
+You just need to ensure the original channel name and PSK exist in your MeshMonitor Channel Database. You do **not** need to create special `NC-` prefixed names.
+
+> [!CAUTION]
+> **Known Limitation (Shared Keys):** If you use the same key for multiple channels (e.g., both your local `LongFast` and the virtual `LongFast` use `AQ==`), **MeshMonitor will decode traffic for both into the exact same channel display**. 
+> 
+> You cannot turn on "Enforce Channel Name Validation" in MeshMonitor to separate them. Because the proxy must fake the PSK hash to prevent the physical radio from transmitting the packet, MeshMonitor's strict "Enforce Name" validation will fail the hash check and refuse to decrypt entirely.
+> 
+> As a result, virtual channel traffic will simply be merged into your existing local channel display if they share a key.
+> **Monitoring only:** Virtual Channels are strictly read-only. Because the hardware radio does not know about virtual channels, there is no way to send a reply on a virtual channel. This is by design — the feature is intended for safe, passive cross-region monitoring without bridging two networks.
+
+> [!IMPORTANT]
+> **Loop Prevention:** When MeshMonitor echoes a virtual channel packet back to the proxy, the proxy's uplink filter automatically drops it (since the virtual channel is not defined on the physical radio). This prevents an infinite `proxy → MeshMonitor → MQTT → proxy` feedback loop.
 
-> [!TIP]
-> **Loop Prevention & MeshMonitor Architecture:** Virtual Channels are intentionally sent to the proxy's transmission queue so they can be received natively over the socket connection by MeshMonitor (which acts as a Virtual Node Server). When MeshMonitor echoes the packed back to the proxy, the proxy automatically **drops** the Virtual Channel instead of republishing it. This breaks the infinite MQTT loop while keeping MeshMonitor informed!
 
 ## Meshtastic Node Configuration
 

README.md

@@ -2,7 +2,7 @@
 
 A production-ready MQTT proxy for Meshtastic devices that enables bidirectional message forwarding between Meshtastic nodes and MQTT brokers. Supports TCP and Serial interface connections with a clean factory pattern architecture.
 
-**Version**: 1.6.2
+**Version**: 1.6.3
 
 ## Features
 
@@ -21,6 +21,7 @@ A production-ready MQTT proxy for Meshtastic devices that enables bidirectional
 - ✅ **Traffic Optimization** - Smart subscription strategy (`msh/2/e/#`) to prevent serial link saturation
 - ✅ **Hammering Prevention** - Correctly flags retained messages to avoid `NO_RESPONSE` storms
 - ✅ **Channel Filtering** - Respects `uplink_enabled` and `downlink_enabled` channel settings
+- ✅ **Virtual Channels** - Monitor cross-region MQTT traffic via `EXTRA_MQTT_ROOTS` without RF crosstalk (payload mutation prevents radio decryption & rebroadcast)
 - ✅ **MeshMonitor Compatible** - Seamless integration with MeshMonitor and other tools
 
 **Note:** BLE interface is not currently supported. Use TCP or Serial interfaces.
@@ -437,28 +438,28 @@ Because this repository enforces **Pull Request requirements** for the `master`
 
 1. **Create a Release Branch:**
    ```bash
-   git checkout -b release/v1.6.0
+   git checkout -b release/v1.6.3
    ```
 
 2. **Run the Release Script:**
    Use the provided automation script to bump the version in `version.py` and `README.md`:
    ```bash
-   python scripts/release.py 1.6.0
+   python scripts/release.py 1.6.3
    ```
-   *This will create a local "chore: release v1.6.0" commit and a local `v1.6.0` tag.*
+   *This will create a local "chore: release v1.6.3" commit and a local `v1.6.3` tag.*
 
 3. **Push and Open a PR:**
    Push the branch and open a Pull Request to `master`.
    ```bash
-   git push origin release/v1.6.0
+   git push origin release/v1.6.3
    ```
 
 4. **Merge and Tag:**
    Once the PR is merged into `master`, push the local tag to GitHub to trigger the release pipeline:
    ```bash
    git checkout master
    git pull
-   git push origin v1.6.0
+   git push origin v1.6.3
    ```
 
 The GitHub Actions will automatically detect the new tag, build the Windows executable, and publish the Docker images.
@@ -499,7 +500,7 @@ while the source code of this proxy is MIT licensed, it depends on third-party l
 
 - **Issues**: [GitHub Issues](https://github.com/LN4CY/mqtt-proxy/issues)
 - **Meshtastic Discord**: [Join](https://discord.gg/meshtastic)
-- **Version**: 1.6.2
+- **Version**: 1.6.3
 - **Documentation**: [Configuration Guide](CONFIG.md) | [Architecture](ARCHITECTURE.md)
 
 ## Roadmap

RELEASE_NOTES.md

@@ -1,3 +1,24 @@
+# Release v1.6.3
+
+## Virtual Channel RF Crosstalk Prevention
+
+This release fixes a critical bug where Virtual Channel packets injected into the local radio (via `EXTRA_MQTT_ROOTS`) could be decrypted and rebroadcast over RF to nearby nodes, effectively bridging two independent MQTT server regions against the user's intent.
+
+## 🐛 Bug Fixes
+
+* **Fix: Virtual Channel RF Crosstalk** (PR #41)
+  * **Root Cause:** The radio firmware uses `packet.channel` — a PSK hash integer embedded in the `ServiceEnvelope` protobuf payload — to look up its decryption key. Because the topic-only rewrite (`NC-LongFast`) left the original PSK hash intact, the radio could still match its local channel key and decrypt the packet, causing it to rebroadcast over RF.
+  * **Fix:** The proxy now mutates the `packet.channel` field in the protobuf payload before injecting it into the radio:
+    * `packet.channel` — replaced with a synthetic hash unique to the virtual channel name that no local radio will ever have configured
+  * The `packet.encrypted` bytes and original `channel_id` string are left completely untouched. MeshMonitor natively decrypts the message using its standard Channel Database. **Known Defect:** Because the PSK hash is faked, MeshMonitor's "Enforce Channel Name Validation" cannot be used. Consequently, if multiple channels share the exact same key, MeshMonitor will decode and merge their traffic into a single channel display.
+  * Added `INFO`-level log entry on every virtual channel rewrite for easy discovery of exact virtual channel names.
+
+## 📝 Documentation
+
+* Updated `CONFIG.md` Virtual Channels section to accurately describe the payload mutation mechanism and added **MeshMonitor Channel Database setup instructions** explaining which channel name and key to configure for each virtual channel.
+
+---
+
 # Release v1.6.2
 
 This release introduces two major new features to handle advanced broker routing and to improve fidelity with Meshtastic node configurations: **Virtual Channels (Multi-Root)** and **Per-Channel Uplink/Downlink Filtering**.

handlers/mqtt.py

@@ -131,6 +131,59 @@ def publish(self, topic, payload, retain=False):
                 return False
         return False
 
+    def _compute_virtual_channel_hash(self, channel_name):
+        """
+        Compute a synthetic PSK hash for a virtual channel name.
+        
+        Meshtastic firmware uses packet.channel (a uint32 PSK hash) to look up
+        the decryption key for incoming packets. By replacing the real hash with
+        a deterministic but synthetic value derived from the virtual channel name,
+        the radio will find no matching key and cannot decrypt or rebroadcast.
+        
+        The hash is intentionally kept in the range 200-254 to avoid colliding
+        with real channel hashes (LongFast=0, and most common values near 0).
+        """
+        h = 0
+        for b in channel_name.encode('utf-8'):
+            h = (h * 31 + b) & 0xFF
+        # Shift into 200-254 range to reduce collision likelihood with real channels
+        return 200 + (h % 55)
+
+    def _mutate_virtual_channel_payload(self, payload, new_channel_name):
+        """
+        Mutate ServiceEnvelope protobuf to rewrite the PSK hash.
+
+        Changes:
+          - packet.channel       : PSK hash    → synthetic hash unique to the virtual channel
+
+        The string name (envelope.channel_id) and encrypted payload bytes 
+        (packet.encrypted) are left completely untouched. 
+        MeshMonitor can still decrypt the message using the original key and original
+        channel name via its Channel Database entry.
+
+        This prevents the radio firmware from matching its local PSK and rebroadcasting
+        the packet over RF, which would cause crosstalk between MQTT server regions.
+        """
+        try:
+            from meshtastic.protobuf import mqtt_pb2
+            envelope = mqtt_pb2.ServiceEnvelope()
+            envelope.ParseFromString(payload)
+
+            original_channel_hash = envelope.packet.channel
+
+            # Rewrite only the PSK hash to blind the radio firmware
+            envelope.packet.channel = self._compute_virtual_channel_hash(new_channel_name)
+
+            mutated = envelope.SerializeToString()
+            logger.debug(
+                "🔒 Payload mutation: packet.channel %d→%d",
+                original_channel_hash, envelope.packet.channel
+            )
+            return mutated
+        except Exception as e:
+            logger.warning("⚠️ Failed to mutate virtual channel payload, using original: %s", e)
+            return payload
+
     def _on_connect(self, client, userdata, flags, rc, props=None):
         logger.info("✅ MQTT Connected with result code: %s", rc)
         if rc == 0:
@@ -243,6 +296,7 @@ def _on_message(self, client, userdata, message):
                 return
 
             modified_topic = message.topic
+            modified_payload = message.payload
 
             # Virtual Channel mapping for Extra Roots
             extra_roots = getattr(self.config, 'extra_mqtt_roots', [])
@@ -260,17 +314,29 @@ def _on_message(self, client, userdata, message):
                             new_channel_name = f"{er_prefix}-{channel_name}"
                             parts[-2] = new_channel_name
                             modified_topic = "/".join(parts)
-                            logger.debug("🔄 Virtual Channel Rewrite: %s -> %s for extra root %s", 
-                                         channel_name, new_channel_name, er_root)
+                            # CRITICAL: Also mutate the protobuf payload to change the channel
+                            # identity field (packet.channel PSK hash).
+                            # The radio firmware uses packet.channel (PSK hash) to look up
+                            # its decryption key. By replacing it with a synthetic hash that
+                            # no local radio has configured, the firmware cannot decrypt the
+                            # packet and will NOT rebroadcast it over RF.
+                            # The encrypted bytes and original channel_id string are left 
+                            # untouched so MeshMonitor can still decrypt using the original 
+                            # key and channel name via its Channel Database.
+                            modified_payload = self._mutate_virtual_channel_payload(
+                                message.payload, new_channel_name
+                            )
+                            logger.info("🔄 Virtual Channel Rewrite: %s -> %s (extra root: %s)",
+                                        channel_name, new_channel_name, er_root)
                     break
 
             self.last_activity = time.time()
             self.rx_count += 1
 
-            logger.info("📥 MQTT->Node: Topic=%s Size=%d bytes Retained=%s", modified_topic, len(message.payload), message.retain)
+            logger.info("📥 MQTT->Node: Topic=%s Size=%d bytes Retained=%s", modified_topic, len(modified_payload), message.retain)
 
             if self.on_message_callback:
-                self.on_message_callback(modified_topic, message.payload, message.retain)
+                self.on_message_callback(modified_topic, modified_payload, message.retain)
 
         except Exception as e:
             logger.error("❌ Error handling MQTT message: %s", e)

mqtt-proxy.py

@@ -234,9 +234,15 @@ def _is_channel_downlink_enabled(self, channel_name):
                 enabled = getattr(ch.settings, "downlink_enabled", True)
                 return enabled
 
-        # Should we be strict? For now, we allow unknown channels to pass down to the "node"
-        # so that MeshMonitor (acting as a virtual node) can see Virtual Channels.
-        logger.debug("⚠️ Channel '%s' not found in node config, allowing by default", channel_name)
+        # Virtual Channel Pass-Through:
+        # If the channel is not defined on the physical radio, we still
+        # forward the packet to the radio. The proxy has already mutated the packet.channel
+        # PSK hash, so the radio has no matching key and CANNOT decrypt or rebroadcast it.
+        # However, the raw encrypted packet is sent to all connected TCP clients 
+        # (e.g. MeshMonitor), which can natively decrypt it using its own Channel Database 
+        # based on the original channelname embedded in the packet.
+        # This keeps the key off the node, preventing RF crosstalk while allowing monitoring.
+        logger.debug("📡 Channel '%s' not defined on radio, forwarding for MeshMonitor (virtual channel passthrough)", channel_name)
         return True
 
     def _is_channel_uplink_enabled(self, channel_name):

pr_body.md

@@ -0,0 +1,25 @@
+## Problem
+
+Virtual channel topic rewriting (renaming `LongFast` → `NC-LongFast` in the MQTT topic) was insufficient to prevent RF rebroadcast crosstalk.
+
+The radio firmware uses **`packet.channel`** (a PSK hash integer inside the `ServiceEnvelope` protobuf payload) to look up the decryption key — **not** the MQTT topic string. When packets from extra MQTT roots shared the same PSK as a local channel (e.g. `LongFast` / `AQ==`), the radio successfully decrypted and rebroadcast them over RF, effectively bridging two independent MQTT server regions.
+
+## Fix
+
+Mutate the `ServiceEnvelope` protobuf **before** injecting to the radio:
+- `packet.channel` → synthetic hash derived from the virtual channel name (range 200-254)
+
+The radio firmware finds no matching PSK for the synthetic hash → cannot decrypt → **does not rebroadcast over RF** ✅
+
+The `packet.encrypted` bytes and the `channel_id` string name are **completely untouched**. This allows MeshMonitor to decrypt the packet using its standard Channel Database natively. 
+
+**Known Defect:** Because the PSK hash is faked to prevent radio crosstalk, MeshMonitor's "Enforce Channel Name Validation" cannot be used (it strictly fails the hash check). Consequently, if multiple monitored channels share the exact same key, MeshMonitor will decode and merge their traffic into a single channel display.
+
+## Setup for Users
+
+Users just ensure the original PSK exists in their MeshMonitor Channel Database. No custom `NC-` prefixed entries are required. "Enforce Channel Name Validation" must remain OFF.
+
+## Testing
+- All 67 existing tests pass
+- Live verified: `packet.channel` carries PSK hash (not slot index) via `inspect_payload.py`
+- Confirmed MeshMonitor successfully decrypts natively, with documentation updated on the shared-PSK defect.

version.py

@@ -1,3 +1,3 @@
 """Version definition for MQTT Proxy."""
 
-__version__ = "1.6.2"
+__version__ = "1.6.3"