rfed 0.1.0__py3-none-any.whl

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/_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/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,
+    )

rfed/channel.py

@@ -0,0 +1,94 @@
+"""Deterministic rfed channel derivation.
+
+A channel is a deterministic :class:`RNS.Identity` derived from a plain-text
+channel name. Any party that knows the name independently arrives at the same
+identity hash ("channel hash") and keypair, so senders can encrypt to the
+channel and subscribers can decrypt — with no server-side registration.
+
+Algorithm (``RFed/SPEC.md`` §1)::
+
+    seed          = SHA-256(channel_name)                 → 32 bytes
+    x25519_priv   = seed
+    ed25519_priv   = seed
+    x25519_pub    = X25519_public_key(seed)               → 32 bytes
+    ed25519_pub   = Ed25519_public_key(seed)              → 32 bytes
+    bundle        = x25519_pub ‖ ed25519_pub              → 64 bytes
+    channel_hash  = SHA-256(bundle)[0..16]                → 16 bytes
+
+The channel's private-key bundle is ``seed ‖ seed`` (the same 32-byte
+``SHA-256(name)`` scalar used for both X25519 and Ed25519), matching the Rust
+reference's ``private_key_bundle = seed || seed`` and the canonical Python
+``channel_hash.compute_channel_hash`` vectors.
+
+This module uses :mod:`RNS` only for its cryptography primitives
+(:func:`RNS.Identity.full_hash` / :func:`RNS.Identity.truncated_hash`), so it
+works **without a running Reticulum** — only :class:`~RNS.Destination` creation
+needs a live transport.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Tuple
+
+import RNS
+
+from rfed.constants import LXMF_DELIVERY_NAME
+
+__all__ = ["derive_channel", "delivery_hash_for", "channel_path"]
+
+
+def _identity_from_seed(seed: bytes) -> RNS.Identity:
+    """Build a full RNS Identity (both private keys) from a 32-byte seed.
+
+    The private-key bundle is ``seed ‖ seed`` (X25519 seed ‖ Ed25519 seed),
+    matching the Rust/Python references.
+    """
+    if len(seed) != 32:
+        raise ValueError("channel seed must be 32 bytes")
+    identity = RNS.Identity(create_keys=False)
+    identity.load_private_key(seed + seed)
+    return identity
+
+
+def derive_channel(name: str) -> Tuple[RNS.Identity, bytes]:
+    """Derive a channel's deterministic Identity and 16-byte channel hash.
+
+    Parameters
+    ----------
+    name:
+        Dot-separated channel name (e.g. ``"dacar.policy.v1"`` or a
+        ``"<hex>.<segments>"`` private channel).
+
+    Returns
+    -------
+    (identity, channel_hash)
+        ``identity`` is a full RNS Identity holding both private keys, so it can
+        encrypt, decrypt, and derive its ``lxmf.delivery`` hash.
+        ``channel_hash`` is the 16-byte channel identity hash used as the rfed
+        routing label.
+    """
+    seed = hashlib.sha256(name.encode("utf-8")).digest()
+    identity = _identity_from_seed(seed)
+    # identity.hash is SHA-256(pub_bundle)[:16], already the channel hash.
+    return identity, identity.hash
+
+
+def delivery_hash_for(identity: RNS.Identity) -> bytes:
+    """Compute the ``lxmf.delivery`` destination hash for an Identity.
+
+    The 16-byte truncated ``SHA-256(name_hash("lxmf.delivery") ‖ identity_hash)``.
+
+    For a channel message this is the LXMF ``destination_hash`` the sender signs
+    over (the channel's delivery address), **not** the bare channel identity
+    hash. Confusing the two is the classic rfed bug — see
+    ``RFed/SPEC.md`` "CANONICAL WIRE FORMAT" invariants.
+    """
+    name_hash = RNS.Identity.full_hash(LXMF_DELIVERY_NAME.encode("utf-8"))
+    name_hash = name_hash[: RNS.Identity.NAME_HASH_LENGTH // 8]  # first 10 bytes
+    return RNS.Identity.truncated_hash(name_hash + identity.hash)
+
+
+def channel_path(*segments: str) -> str:
+    """Join channel-name segments with ``.`` (mirrors RNS aspect notation)."""
+    return ".".join(segments)