rfed 0.1.0__tar.gz

rfed-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: rfed
+Version: 0.1.0
+Summary: Python client for RFed (Reticulum Federation) channels
+Author: Henri Bergius
+License: EUPL-1.2
+Project-URL: Homepage, https://github.com/bergie/rfed-python
+Project-URL: Repository, https://github.com/bergie/rfed-python
+Project-URL: Issues, https://github.com/bergie/rfed-python/issues
+Project-URL: Changelog, https://github.com/bergie/rfed-python/releases
+Project-URL: Specification, https://github.com/jrl290/RFed
+Project-URL: Related, https://github.com/bergie/dacar
+Keywords: reticulum,rns,rfed,federation,lxmf,mesh,offline,pubsub
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: msgpack>=1.0
+Requires-Dist: rns>=1.5.4
+
+# rfed-python
+
+Python client for **[RFed (Reticulum Federation)](https://github.com/jrl290/RFed)**
+channels — publish/subscribe over [Reticulum](https://github.com/markqvist/Reticulum).
+
+A from-scratch port of the canonical `@reticulum/core` `RFedClient`
+(JavaScript) and the [RFed spec](https://github.com/jrl290/RFed)'s `SPEC.md`
+"CANONICAL WIRE FORMAT" (Rust reference node), byte-compatible with both: channel hashes, EC envelopes, LXMF tails,
+and PoW stamps cross-validate across implementations. Extracted from the
+[Dacar](https://github.com/bergie/dacar) Python implementation, where it was
+originally developed.
+
+## Install
+
+```sh
+pip install rfed
+```
+
+Dependencies: [`rns`](https://pypi.org/project/rns/) (>= 1.5.4) and
+`msgpack` — the same stack the rest of the Reticulum ecosystem uses.
+
+## Usage
+
+```python
+import RNS
+from rfed._lxmf import LxmfMessage
+from rfed.client import RFedClient
+
+reticulum = RNS.Reticulum()  # boots a transport (e.g. AutoInterface)
+identity = RNS.Identity()    # your subscriber identity
+client = RFedClient(identity, reticulum)
+
+NODE = bytes.fromhex("…")            # any rfed.* destination hash of a node
+CHANNEL = "my.channel.v1"
+
+# Subscribe — also caches the node's advertised PoW stamp cost.
+result = client.subscribe(NODE, CHANNEL)
+print(result.ok, result.stamp_cost)
+
+# Publish an LXMF-envelope message (fire-and-forget SEND).
+message = LxmfMessage(content=b"hello over rfed")
+client.publish(NODE, CHANNEL, message)
+
+# Listen for live fanout deliveries on your rfed.delivery destination.
+def on_message(decoded):
+    print(decoded.message.content, decoded.signature_valid)
+
+client.listen(on_message)
+
+# Or catch up after being offline: drain the node's deferred queue.
+page = client.pull(NODE, CHANNEL)
+while page.more_pending:
+    page = client.pull(NODE, CHANNEL)
+```
+
+RFed treats the encrypted `inner_blob` **opaquely**, so applications may
+carry their own inner format instead of the LXMF envelope (Dacar, for
+example, ships a compact Delta format that fits more payload under the RNS
+MTU). For that, use the raw primitives:
+
+- `client.send_publish(node_hash, rfed_payload)` — fire-and-forget SEND of a
+  pre-wrapped payload,
+- `client.listen_raw(on_fanout)` — undecoded `(channel_name,
+  channel_identity, inner_blob)` deliveries, decrypt/decode yourself.
+
+The pure codec modules (`rfed.constants`, `rfed.channel`, `rfed._lxmf`,
+`rfed.blob`, `rfed.stamp`) work **without a running Reticulum** — only
+`RFedClient`'s network methods need a live transport.
+
+## Wire format
+
+```
+plaintext    = "RTID"(4) ‖ sender_identity_pub(64) ‖ LXMF_tail
+LXMF_tail    = source_hash(16) ‖ signature(64) ‖ msgpack_payload
+inner_blob   = EC_encrypt(channel_identity.X25519_pub, plaintext)
+rfed_payload = channel_hash(16) ‖ inner_blob ‖ stamp(32)?
+```
+
+Channels are derived deterministically from their name
+(`rfed.channel.derive_channel`), so any party knowing the name can derive the
+shared keypair — no registration. Stamps use the standard LXMF PoW mechanism
+(memory-hard HKDF workblock) at rfed's 16 expansion rounds.
+
+## Status
+
+Early beta (0.x). The wire format follows the RFed spec's "CANONICAL WIRE
+FORMAT" and cross-validates with `@reticulum/core` (JS) and the Rust
+reference node, but the RFed protocol itself is still evolving.
+
+## License
+
+EUPL-1.2, same as Dacar and Reticulum.

rfed-0.1.0/README.md

@@ -0,0 +1,92 @@
+# rfed-python
+
+Python client for **[RFed (Reticulum Federation)](https://github.com/jrl290/RFed)**
+channels — publish/subscribe over [Reticulum](https://github.com/markqvist/Reticulum).
+
+A from-scratch port of the canonical `@reticulum/core` `RFedClient`
+(JavaScript) and the [RFed spec](https://github.com/jrl290/RFed)'s `SPEC.md`
+"CANONICAL WIRE FORMAT" (Rust reference node), byte-compatible with both: channel hashes, EC envelopes, LXMF tails,
+and PoW stamps cross-validate across implementations. Extracted from the
+[Dacar](https://github.com/bergie/dacar) Python implementation, where it was
+originally developed.
+
+## Install
+
+```sh
+pip install rfed
+```
+
+Dependencies: [`rns`](https://pypi.org/project/rns/) (>= 1.5.4) and
+`msgpack` — the same stack the rest of the Reticulum ecosystem uses.
+
+## Usage
+
+```python
+import RNS
+from rfed._lxmf import LxmfMessage
+from rfed.client import RFedClient
+
+reticulum = RNS.Reticulum()  # boots a transport (e.g. AutoInterface)
+identity = RNS.Identity()    # your subscriber identity
+client = RFedClient(identity, reticulum)
+
+NODE = bytes.fromhex("…")            # any rfed.* destination hash of a node
+CHANNEL = "my.channel.v1"
+
+# Subscribe — also caches the node's advertised PoW stamp cost.
+result = client.subscribe(NODE, CHANNEL)
+print(result.ok, result.stamp_cost)
+
+# Publish an LXMF-envelope message (fire-and-forget SEND).
+message = LxmfMessage(content=b"hello over rfed")
+client.publish(NODE, CHANNEL, message)
+
+# Listen for live fanout deliveries on your rfed.delivery destination.
+def on_message(decoded):
+    print(decoded.message.content, decoded.signature_valid)
+
+client.listen(on_message)
+
+# Or catch up after being offline: drain the node's deferred queue.
+page = client.pull(NODE, CHANNEL)
+while page.more_pending:
+    page = client.pull(NODE, CHANNEL)
+```
+
+RFed treats the encrypted `inner_blob` **opaquely**, so applications may
+carry their own inner format instead of the LXMF envelope (Dacar, for
+example, ships a compact Delta format that fits more payload under the RNS
+MTU). For that, use the raw primitives:
+
+- `client.send_publish(node_hash, rfed_payload)` — fire-and-forget SEND of a
+  pre-wrapped payload,
+- `client.listen_raw(on_fanout)` — undecoded `(channel_name,
+  channel_identity, inner_blob)` deliveries, decrypt/decode yourself.
+
+The pure codec modules (`rfed.constants`, `rfed.channel`, `rfed._lxmf`,
+`rfed.blob`, `rfed.stamp`) work **without a running Reticulum** — only
+`RFedClient`'s network methods need a live transport.
+
+## Wire format
+
+```
+plaintext    = "RTID"(4) ‖ sender_identity_pub(64) ‖ LXMF_tail
+LXMF_tail    = source_hash(16) ‖ signature(64) ‖ msgpack_payload
+inner_blob   = EC_encrypt(channel_identity.X25519_pub, plaintext)
+rfed_payload = channel_hash(16) ‖ inner_blob ‖ stamp(32)?
+```
+
+Channels are derived deterministically from their name
+(`rfed.channel.derive_channel`), so any party knowing the name can derive the
+shared keypair — no registration. Stamps use the standard LXMF PoW mechanism
+(memory-hard HKDF workblock) at rfed's 16 expansion rounds.
+
+## Status
+
+Early beta (0.x). The wire format follows the RFed spec's "CANONICAL WIRE
+FORMAT" and cross-validates with `@reticulum/core` (JS) and the Rust
+reference node, but the RFed protocol itself is still evolving.
+
+## License
+
+EUPL-1.2, same as Dacar and Reticulum.

rfed-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rfed"
+version = "0.1.0"
+description = "Python client for RFed (Reticulum Federation) channels"
+readme = "README.md"
+license = { text = "EUPL-1.2" }
+requires-python = ">=3.9"
+authors = [{ name = "Henri Bergius" }]
+keywords = ["reticulum", "rns", "rfed", "federation", "lxmf", "mesh", "offline", "pubsub"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Communications",
+    "Topic :: System :: Networking",
+]
+dependencies = [
+    # LXMF-tail msgpack payload codec.
+    "msgpack>=1.0",
+    # Reticulum Network Stack: destinations, links, requests, crypto
+    # (pulls in `cryptography`). 1.5.4 pairs with the @reticulum/* 0.8.2
+    # wire protocol (rfed link publishes, pull error codes).
+    "rns>=1.5.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/bergie/rfed-python"
+Repository = "https://github.com/bergie/rfed-python"
+Issues = "https://github.com/bergie/rfed-python/issues"
+Changelog = "https://github.com/bergie/rfed-python/releases"
+Specification = "https://github.com/jrl290/RFed"
+Related = "https://github.com/bergie/dacar"
+
+[tool.setuptools]
+packages = ["rfed"]

rfed-0.1.0/rfed/__init__.py

@@ -0,0 +1,25 @@
+"""RFed (Reticulum Federation) channel client for Python.
+
+A from-scratch Python port of the canonical ``@reticulum/core`` ``RFedClient``
+(JS) and the ``RFed/SPEC.md`` "CANONICAL WIRE FORMAT" (Rust). Extracted from
+the Dacar Python implementation (https://github.com/bergie/dacar), where it
+was originally developed.
+
+It depends only on ``rns`` + ``msgpack`` (+ ``cryptography`` via ``rns``).
+The pure codec modules (:mod:`rfed.constants`, :mod:`rfed.channel`,
+:mod:`rfed._lxmf`, :mod:`rfed.blob`, :mod:`rfed.stamp`) work **without a
+running Reticulum**; only :class:`rfed.client.RFedClient`'s network methods
+need a live transport (``RNS.Destination`` / ``RNS.Link`` creation).
+
+Submodules:
+- :mod:`rfed.constants` — wire-format constants.
+- :mod:`rfed.channel`     — deterministic channel derivation.
+- :mod:`rfed._lxmf`        — minimal canonical LXMF wire codec.
+- :mod:`rfed.blob`         — Phase-0 RTID envelope (wrap/unwrap).
+- :mod:`rfed.stamp`        — rfed PoW stamp contract.
+- :mod:`rfed.client`      — ``RFedClient`` (subscribe/publish/pull/listen).
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []  # submodules imported explicitly by callers

rfed-0.1.0/rfed/_lxmf.py

@@ -0,0 +1,181 @@
+"""Minimal canonical LXMF message wire codec.
+
+The rfed channel envelope wraps a propagation-style LXMF message (§5.2/§5.1).
+Rather than depend on the external ``lxmf`` package — whose
+:class:`LXMF.LXMessage.pack()` requires a real :class:`RNS.Destination` (and
+thus a running Reticulum) — this module reimplements just the wire format. It
+is byte-for-byte compatible with Python LXMF's ``pack()`` /
+``unpack_from_bytes()`` and with ``@reticulum/core``'s ``Message.serialize``,
+so signatures and hashes cross-validate across all three.
+
+Wire format::
+
+    direct:   destination_hash(16) ‖ source_hash(16) ‖ signature(64) ‖ msgpack_payload
+    payload:  [timestamp(float64), title(bin), content(bin), fields(map)] [, stamp(bin32)]
+
+Signature (§5.5) is computed over ``destination_hash ‖ source_hash ‖
+msgpack_payload ‖ message_hash``, where ``message_hash = SHA-256(dest ‖ src ‖
+msgpack_payload)``. The optional 5th stamp element is stripped before hashing
+(matching ``LXMessage.unpack_from_bytes``).
+
+Uses :mod:`RNS` only for crypto (``full_hash`` / ``sign`` / ``validate``) and
+:mod:`msgpack` for the payload, so it works without a running Reticulum.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional, Tuple
+
+import msgpack
+import RNS
+
+__all__ = ["DESTINATION_LENGTH", "SIGNATURE_LENGTH", "LxmfMessage"]
+
+#: LXMF destination / source hash length (``TRUNCATED_HASHLENGTH // 8``).
+DESTINATION_LENGTH = 16
+#: Ed25519 signature length (``SIGLENGTH // 8``).
+SIGNATURE_LENGTH = 64
+
+
+def _to_bytes(value) -> bytes:
+    """Coerce a str/bytes value to bytes (UTF-8) for bin encoding."""
+    if value is None:
+        return b""
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    if isinstance(value, (bytes, bytearray)):
+        return bytes(value)
+    raise TypeError(f"expected str or bytes, got {type(value).__name__}")
+
+
+def _pack_payload(
+    timestamp: float,
+    title: bytes,
+    content: bytes,
+    fields: Dict[str, Any],
+    stamp: Optional[bytes] = None,
+) -> bytes:
+    """Canonical msgpack payload: float64 timestamp, bin title/content, map fields.
+
+    ``use_single_float=False`` forces float64 (matching JS ``encodeFloat64``),
+    and bytes encode as bin (``use_bin_type`` default).
+    """
+    payload: list = [timestamp, title, content, fields]
+    if stamp is not None:
+        payload.append(stamp)
+    return msgpack.packb(payload, use_single_float=False)
+
+
+class LxmfMessage:
+    """A minimal LXMF message carrying an application payload.
+
+    ``destination_hash`` / ``source_hash`` are the ``lxmf.delivery`` destination
+    hashes (channel and sender respectively) — NOT bare identity hashes. For a
+    channel message these are forced by :func:`rfed.blob.wrap_channel_message`
+    before serialization, so placeholders are fine pre-publish.
+    """
+
+    def __init__(
+        self,
+        destination_hash: bytes = b"\x00" * 16,
+        source_hash: bytes = b"\x00" * 16,
+        content: bytes = b"",
+        title: bytes = b"",
+        fields: Optional[Dict[str, Any]] = None,
+        timestamp: Optional[float] = None,
+    ) -> None:
+        self.destination_hash = bytes(destination_hash)
+        self.source_hash = bytes(source_hash)
+        self.content = _to_bytes(content)
+        self.title = _to_bytes(title)
+        self.fields: Dict[str, Any] = dict(fields) if fields else {}
+        self.timestamp = timestamp
+        self.signature: Optional[bytes] = None
+        #: message_id = SHA-256(dest ‖ src ‖ msgpack_payload).
+        self.hash: Optional[bytes] = None
+        self.signature_validated: bool = False
+        #: Optional LXMF PoW stamp (5th payload element); rfed uses its own stamp.
+        self.stamp: Optional[bytes] = None
+
+    def serialize(self, source_identity: RNS.Identity) -> bytes:
+        """Sign and serialize to the canonical LXMF wire format.
+
+        Sets :attr:`hash` (message_id), :attr:`signature`, and returns the wire
+        bytes ``dest ‖ source ‖ signature ‖ msgpack_payload``.
+        """
+        if self.timestamp is None:
+            self.timestamp = time.time()
+        packed = _pack_payload(
+            self.timestamp, self.title, self.content, self.fields, stamp=None
+        )
+        hashed = self.destination_hash + self.source_hash + packed
+        self.hash = RNS.Identity.full_hash(hashed)
+        self.signature = source_identity.sign(hashed + self.hash)
+        return self.destination_hash + self.source_hash + self.signature + packed
+
+    @staticmethod
+    def deserialize(
+        wire: bytes, sender_pub: bytes
+    ) -> "LxmfMessage":
+        """Reconstruct and signature-verify an LXMF message from wire bytes.
+
+        Parameters
+        ----------
+        wire:
+            ``dest(16) ‖ source(16) ‖ signature(64) ‖ msgpack_payload``.
+        sender_pub:
+            The 64-byte sender public-key bundle (from the rfed RTID prelude),
+            used to verify the Ed25519 signature.
+
+        The hash is computed over the received ``msgpack_payload`` bytes when the
+        payload has exactly 4 elements (the canonical, unambiguous path); a 5th
+        stamp element is stripped and the first 4 re-packed before hashing,
+        matching ``LXMF.LXMessage.unpack_from_bytes``.
+        """
+        if len(wire) < 2 * DESTINATION_LENGTH + SIGNATURE_LENGTH:
+            raise ValueError(
+                f"LXMF wire too short: {len(wire)} bytes "
+                f"(need at least {2 * DESTINATION_LENGTH + SIGNATURE_LENGTH})"
+            )
+        dest_hash = wire[:DESTINATION_LENGTH]
+        source_hash = wire[DESTINATION_LENGTH : 2 * DESTINATION_LENGTH]
+        signature = wire[
+            2 * DESTINATION_LENGTH : 2 * DESTINATION_LENGTH + SIGNATURE_LENGTH
+        ]
+        packed = wire[2 * DESTINATION_LENGTH + SIGNATURE_LENGTH :]
+
+        unpacked = msgpack.unpackb(packed, raw=False, strict_map_key=False)
+        if not isinstance(unpacked, list) or len(unpacked) < 4:
+            raise ValueError("LXMF payload is not a 4+-element msgpack array")
+        stamp: Optional[bytes] = None
+        if len(unpacked) > 4:
+            stamp = unpacked[4]
+            unpacked = unpacked[:4]
+            # Re-pack the 4 elements for hashing (matches LXMF unpack_from_bytes).
+            packed_for_hash = msgpack.packb(unpacked, use_single_float=False)
+        else:
+            packed_for_hash = packed
+
+        hashed = dest_hash + source_hash + packed_for_hash
+        message_hash = RNS.Identity.full_hash(hashed)
+        timestamp, title, content, fields = unpacked[:4]
+
+        msg = LxmfMessage(
+            destination_hash=dest_hash,
+            source_hash=source_hash,
+            content=content if isinstance(content, (bytes, bytearray)) else _to_bytes(content),
+            title=title if isinstance(title, (bytes, bytearray)) else _to_bytes(title),
+            fields=fields if isinstance(fields, dict) else {},
+            timestamp=timestamp,
+        )
+        msg.signature = bytes(signature)
+        msg.hash = message_hash
+        msg.stamp = stamp
+
+        sender_identity = RNS.Identity(create_keys=False)
+        sender_identity.load_public_key(bytes(sender_pub))
+        msg.signature_validated = sender_identity.validate(
+            bytes(signature), hashed + message_hash
+        )
+        return msg

rfed-0.1.0/rfed/blob.py

@@ -0,0 +1,220 @@
+"""rfed channel message envelope codec (the "RTID" prelude).
+
+A channel message is a propagation-style LXMF message wrapped in the RTID
+source-identity prelude, then EC-encrypted to the channel identity. The
+resulting ``inner_blob`` is what rfed stores, syncs, and fans out verbatim —
+rfed never decrypts or inspects it.
+
+Layered wire format (``RFed/SPEC.md`` "CANONICAL WIRE FORMAT")::
+
+    plaintext    = "RTID"(4) ‖ sender_identity_pub(64) ‖ LXMF_tail
+    LXMF_tail    = source_hash(16) ‖ signature(64) ‖ msgpack_payload
+    inner_blob   = EC_encrypt(channel_identity.X25519_pub, plaintext)
+    rfed_payload = channel_hash(16) ‖ inner_blob ‖ stamp(32)
+
+``source_hash`` is the sender's ``lxmf.delivery`` *destination* hash —
+``truncated_hash(name_hash("lxmf.delivery") ‖ identity_hash)`` — NOT the bare
+identity hash. Integrity is the LXMF Ed25519 signature; cache poisoning is
+impossible because reaching the EC-decrypt step already required the channel
+private key (i.e. an authorised subscriber).
+
+Applications may carry other inner formats instead of the LXMF tail: rfed
+treats ``inner_blob`` opaquely, so the plaintext after the RTID prelude is a
+private agreement between publishers and subscribers of a channel (keyed by
+``channel_hash``); use :meth:`rfed.client.RFedClient.send_publish` /
+:meth:`rfed.client.RFedClient.listen_raw` for those.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import RNS
+
+from rfed._lxmf import DESTINATION_LENGTH, LxmfMessage
+from rfed.channel import delivery_hash_for
+from rfed.constants import (
+    HASH_LENGTH,
+    MAGIC_LENGTH,
+    MAGIC_RTID,
+    PRELUDE_LENGTH,
+    STAMP_SIZE,
+)
+from rfed.stamp import generate_channel_stamp
+
+__all__ = [
+    "RfedPayload",
+    "DecodedChannelMessage",
+    "wrap_channel_message",
+    "parse_fanout_payload",
+    "parse_send_payload",
+    "unwrap_channel_message",
+]
+
+
+@dataclass(frozen=True)
+class RfedPayload:
+    """A fully-wrapped rfed SEND payload and its constituent parts."""
+
+    rfed_payload: bytes
+    channel_hash: bytes
+    channel_delivery_hash: bytes
+    inner_blob: bytes
+    stamp: Optional[bytes]
+
+
+@dataclass
+class DecodedChannelMessage:
+    """A decoded channel fanout message."""
+
+    message: LxmfMessage
+    sender_pub: bytes
+    sender_identity: RNS.Identity
+    source_hash: bytes
+    signature_valid: bool
+
+
+def wrap_channel_message(
+    *,
+    channel_identity: RNS.Identity,
+    sender_identity: RNS.Identity,
+    sender_lxm_delivery_hash: bytes,
+    lxm_message: LxmfMessage,
+    stamp_cost: Optional[int] = None,
+) -> RfedPayload:
+    """Wrap an LXMF message into a rfed channel SEND payload.
+
+    The LXMF message is serialised (signed by ``sender_identity``), the RTID
+    prelude + sender public key are prepended to the LXMF tail, the whole thing
+    is EC-encrypted to the channel identity, and the channel hash + optional PoW
+    stamp are framed around it.
+
+    ``lxm_message.destination_hash`` / ``source_hash`` are forced to the correct
+    ``lxmf.delivery`` hashes (channel and sender respectively) so the classic
+    "source_hash is the identity hash" bug cannot occur.
+    """
+    channel_hash = channel_identity.hash
+    channel_delivery_hash = delivery_hash_for(channel_identity)
+
+    # Force correct LXMF addressing: source_hash MUST be the sender's
+    # lxmf.delivery destination hash, never the bare identity hash.
+    lxm_message.destination_hash = bytes(channel_delivery_hash)
+    lxm_message.source_hash = bytes(sender_lxm_delivery_hash)
+
+    wire = lxm_message.serialize(sender_identity)
+    sender_pub = sender_identity.get_public_key()
+    # LXMF tail = wire after the destination hash: source ‖ signature ‖ payload.
+    lxmf_tail = wire[DESTINATION_LENGTH:]
+
+    plaintext = MAGIC_RTID + sender_pub + lxmf_tail
+    inner_blob = channel_identity.encrypt(plaintext)
+
+    stamp: Optional[bytes] = None
+    if stamp_cost and stamp_cost > 0:
+        stamp, _ = generate_channel_stamp(channel_hash, inner_blob, stamp_cost)
+
+    rfed_payload = (
+        bytes(channel_hash) + bytes(inner_blob) + (bytes(stamp) if stamp else b"")
+    )
+    return RfedPayload(
+        rfed_payload=rfed_payload,
+        channel_hash=bytes(channel_hash),
+        channel_delivery_hash=bytes(channel_delivery_hash),
+        inner_blob=bytes(inner_blob),
+        stamp=stamp,
+    )
+
+
+def parse_fanout_payload(payload: bytes) -> tuple:
+    """Split a fanout payload ``[ channel_hash(16) ‖ inner_blob ]``.
+
+    The fanout hop carries no stamp (it was validated and stripped at ingest).
+    """
+    if len(payload) < HASH_LENGTH:
+        raise ValueError(
+            f"rfed fanout payload too short: {len(payload)} bytes "
+            f"(need at least {HASH_LENGTH})"
+        )
+    return payload[:HASH_LENGTH], payload[HASH_LENGTH:]
+
+
+def parse_send_payload(payload: bytes) -> tuple:
+    """Split a SEND payload ``[ channel_hash(16) ‖ inner_blob ‖ stamp(32) ]``.
+
+    Use when a stamp is known to be present (the node's ``stamp_cost`` is
+    non-nil); use :func:`parse_fanout_payload` for the stamp-free fanout form.
+    """
+    min_len = HASH_LENGTH + STAMP_SIZE
+    if len(payload) < min_len:
+        raise ValueError(
+            f"rfed SEND payload too short: {len(payload)} bytes "
+            f"(need at least {min_len})"
+        )
+    return (
+        payload[:HASH_LENGTH],
+        payload[HASH_LENGTH : len(payload) - STAMP_SIZE],
+        payload[len(payload) - STAMP_SIZE :],
+    )
+
+
+def unwrap_channel_message(
+    *, inner_blob: bytes, channel_identity: RNS.Identity, channel_delivery_hash: bytes
+) -> DecodedChannelMessage:
+    """Decrypt and reconstruct an LXMF message from a channel ``inner_blob``.
+
+    Inverse of :func:`wrap_channel_message`: EC-decrypts with the channel
+    identity, verifies the RTID magic, extracts the embedded sender public key,
+    and feeds the reconstructed LXMF wire block to
+    :meth:`LxmfMessage.deserialize`. The sender identity is cached via
+    :func:`RNS.Identity.remember` so subsequent messages from the same sender
+    validate without the prelude (best-effort).
+
+    The returned ``signature_valid`` is **the** integrity check: a forged
+    ``sender_identity_pub`` produces a signature mismatch.
+    """
+    plaintext = channel_identity.decrypt(bytes(inner_blob))
+    if plaintext is None:
+        raise ValueError("rfed inner_blob EC-decryption failed (wrong channel?)")
+    plaintext = bytes(plaintext)
+    if len(plaintext) < PRELUDE_LENGTH + DESTINATION_LENGTH:
+        raise ValueError(
+            f"rfed prelude plaintext too short: {len(plaintext)} bytes"
+        )
+
+    # Verify magic — receivers MUST refuse blobs without "RTID".
+    magic = plaintext[:MAGIC_LENGTH]
+    if magic != MAGIC_RTID:
+        raise ValueError(
+            f'rfed prelude magic mismatch: expected "RTID", got {magic!r}'
+        )
+
+    sender_pub = plaintext[MAGIC_LENGTH:PRELUDE_LENGTH]
+    lxmf_tail = plaintext[PRELUDE_LENGTH:]
+
+    # Reconstruct the canonical LXMF block: dest_hash(16) ‖ source ‖ sig ‖ payload.
+    full_wire = bytes(channel_delivery_hash) + lxmf_tail
+    message = LxmfMessage.deserialize(full_wire, sender_pub)
+
+    sender_identity = RNS.Identity(create_keys=False)
+    sender_identity.load_public_key(sender_pub)
+
+    # Cache the sender identity so future messages validate without the prelude.
+    # Best-effort: decode must still succeed without it.
+    try:
+        RNS.Identity.remember(
+            message.hash or message.source_hash,
+            message.source_hash,
+            sender_pub,
+            None,
+        )
+    except Exception:
+        pass
+
+    return DecodedChannelMessage(
+        message=message,
+        sender_pub=bytes(sender_pub),
+        sender_identity=sender_identity,
+        source_hash=message.source_hash,
+        signature_valid=message.signature_validated,
+    )