add direct NOTICE delivery extension with destination identity support

2026-06-08 14:11:53 -07:00 · 2026-05-17 19:40:17 +00:00
parent 5ea91a011e
commit 1e109e8137
11 changed files with 306 additions and 10 deletions
@@ -2,6 +2,15 @@

 This project follows the versioning policy in VERSIONING.md.

+## 0.3.1 - 2026-05-17
+
+- Added a backward-compatible direct `NOTICE` extension using envelope key
+  `K_DST = 8` for full destination identity hashes
+- Added advisory `CAP_DIRECT_NOTICE = 2` to `WELCOME` capabilities so clients
+  can detect support before sending direct notices
+- Direct `NOTICE` delivery now returns `ERROR` for mixed room-plus-destination
+  envelopes and for unknown or offline destination identities
+
 ## 0.3.0 - 2026-05-16

 - Added core message type `ACTION` (`T_ACTION = 22`) routing with room-content semantics
@@ -52,6 +52,50 @@ syntax to generate `ACTION` envelopes, and clients are free to render incoming
 `rrcd` does not parse slash commands from `ACTION` bodies. Slash-command
 handling remains a `MSG`/`NOTICE` convention.

+## Extension: Direct NOTICE Delivery
+
+**Envelope Key**: `8` (`K_DST`)
+**Capability Key**: `2` (`CAP_DIRECT_NOTICE`)
+**Status**: Implemented (advisory)
+
+`rrcd` advertises `CAP_DIRECT_NOTICE` in `WELCOME` capabilities to indicate
+that the hub supports client-to-client `NOTICE` delivery using an explicit
+destination identity hash.
+
+When a client sends a `NOTICE` with `K_DST = 8`, the value must be the full
+destination identity hash as bytes. The hub resolves that identity against the
+currently connected sessions and forwards the `NOTICE` to exactly one link.
+
+Direct `NOTICE` delivery does not use room membership. `K_ROOM` must be omitted
+when `K_DST` is present; if both are present, the hub rejects the message with
+`ERROR` rather than guessing which delivery mode the sender intended.
+
+**Envelope structure**:
+
+```python
+{
+        0: 1,                 # protocol version (K_V)
+        1: 21,                # message type T_NOTICE (K_T)
+        2: <8-byte-id>,       # message ID (K_ID)
+        3: <timestamp>,       # millisecond timestamp (K_TS)
+        4: <sender-hash>,     # sender identity hash (K_SRC)
+        6: <body>,            # notice body (K_BODY)
+        8: <dest-hash>        # full destination identity hash (K_DST)
+}
+```
+
+**Delivery semantics**:
+
+- The hub overwrites `K_SRC` with the authenticated sender identity for the
+    current link.
+- The hub preserves `K_DST` on the forwarded envelope so the recipient can tell
+    that the `NOTICE` was direct-addressed to its identity.
+- The hub may normalize or attach `K_NICK` as a display hint, just as it does
+    for room `MSG`/`NOTICE` forwarding.
+- If the destination is not currently connected, the sender receives `ERROR`.
+- Nicknames and hash prefixes are not accepted in `K_DST`; this field is full
+    identity bytes only.
+
 The RRC specification has no concept of large message delivery beyond "chunk it
 yourself, good luck." This is fine for small messages but becomes obnoxious for:

@@ -507,9 +551,11 @@ If you're implementing a client or another hub, here's what you need to know:
 ### Enhanced Compatibility (Recommended)
 - Support `T_RESOURCE_ENVELOPE` (message type 50) and Reticulum resources
 - Handle `ACTION` (message type 22) as room content (rendering is client-defined)
+- Handle `K_DST` (envelope key 8) on incoming `NOTICE` if you want direct-message UX
 - Advertise `CAP_ACTION` in your `HELLO` capabilities if you support ACTION UX
 - Advertise `CAP_RESOURCE_ENVELOPE` in your `HELLO` capabilities if you support
   resources
+- Wait for `CAP_DIRECT_NOTICE` in `WELCOME` before sending direct `NOTICE` with `K_DST`
 - Expect hub greeting to arrive via `NOTICE` messages after `WELCOME`
 - Handle chunked `NOTICE` messages (multiple messages with the same content
   type)
@@ -145,6 +145,23 @@ Wire-level extensions (backwards-compatible):
    UTF-8 encodable, contain no newlines/NUL, and are at most `nick_max_chars`
    characters (default: 32).

+- **Direct NOTICE destination**: the hub supports client-to-client `NOTICE`
+    delivery using an optional envelope key `K_DST = 8` (bytes), containing the
+    full destination identity hash.
+
+    This extension applies only to `NOTICE`. When `K_DST` is present, the hub
+    delivers the message to exactly one connected client identified by that full
+    hash instead of broadcasting by room membership. The forwarded `NOTICE`
+    preserves `K_DST` so the recipient can distinguish direct delivery from
+    room traffic without out-of-band state.
+
+    Direct `NOTICE` messages must not also include `K_ROOM`. Mixed room and
+    direct-destination semantics are rejected with `ERROR`.
+
+    Support for this extension is advertised in `WELCOME` capabilities via
+    `CAP_DIRECT_NOTICE = 2`. Clients should only send `K_DST`-addressed notices
+    after confirming hub support.
+
 - **Large payload transfer via RNS.Resource**: For messages that exceed the link
    MTU (Maximum Data Unit), `rrcd` can automatically use RNS.Resource for
    reliable large payload transfer instead of manual chunking.
@@ -1,3 +1,3 @@
 __all__ = ["__version__"]

-__version__ = "0.3.0"
+__version__ = "0.3.1"
@@ -11,6 +11,7 @@ K_SRC = 4
 K_ROOM = 5
 K_BODY = 6
 K_NICK = 7
+K_DST = 8

 # Message types
 T_HELLO = 1
@@ -58,6 +59,7 @@ B_LIMIT_RATE_LIMIT_MSGS_PER_MINUTE = 4
 # Capabilities map keys (values are advisory). Keep these small and numeric.
 CAP_RESOURCE_ENVELOPE = 0
 CAP_ACTION = 1
+CAP_DIRECT_NOTICE = 2

 # RESOURCE_ENVELOPE body keys
 B_RES_ID = 0
@@ -3,7 +3,18 @@ from __future__ import annotations
 import os
 import time

-from .constants import K_BODY, K_ID, K_NICK, K_ROOM, K_SRC, K_T, K_TS, K_V, RRC_VERSION
+from .constants import (
+    K_BODY,
+    K_DST,
+    K_ID,
+    K_NICK,
+    K_ROOM,
+    K_SRC,
+    K_T,
+    K_TS,
+    K_V,
+    RRC_VERSION,
+)
 from .util import normalize_nick


@@ -19,6 +30,7 @@ def make_envelope(
    msg_type: int,
    *,
    src: bytes,
+    dst: bytes | None = None,
    room: str | None = None,
    body=None,
    nick: str | None = None,
@@ -32,6 +44,8 @@ def make_envelope(
        K_TS: ts or now_ms(),
        K_SRC: src,
    }
+    if dst is not None:
+        env[K_DST] = bytes(dst)
    if room is not None:
        env[K_ROOM] = room
    if body is not None:
@@ -90,3 +104,8 @@ def validate_envelope(env: dict) -> None:
        nick = env[K_NICK]
        if not isinstance(nick, str):
            raise TypeError("nickname must be a string")
+
+    if K_DST in env:
+        dst = env[K_DST]
+        if not isinstance(dst, (bytes, bytearray)):
+            raise TypeError("destination identity must be bytes")
@@ -18,6 +18,7 @@ from .constants import (
    B_WELCOME_LIMITS,
    B_WELCOME_VER,
    CAP_ACTION,
+    CAP_DIRECT_NOTICE,
    CAP_RESOURCE_ENVELOPE,
    T_ERROR,
    T_NOTICE,
@@ -144,6 +145,7 @@ class MessageHelper:

        caps: dict[int, bool] = {
            CAP_ACTION: True,
+            CAP_DIRECT_NOTICE: True,
        }
        if self.hub.config.enable_resource_transfer:
            caps[CAP_RESOURCE_ENVELOPE] = True
@@ -15,6 +15,7 @@ from .constants import (
    B_RES_SHA256,
    B_RES_SIZE,
    K_BODY,
+    K_DST,
    K_NICK,
    K_ROOM,
    K_SRC,
@@ -610,7 +611,11 @@ class MessageRouter:
                    peer_still_in_room = True
                    break

-        if remaining_members and self.hub.identity is not None and not peer_still_in_room:
+        if (
+            remaining_members
+            and self.hub.identity is not None
+            and not peer_still_in_room
+        ):
            notification_body = (
                [peer_hash] if self.hub.config.include_joined_member_list else None
            )
@@ -652,6 +657,7 @@ class MessageRouter:
        """Handle MSG, NOTICE, and ACTION messages."""
        t = env.get(K_T)
        room = env.get(K_ROOM)
+        dst = env.get(K_DST)
        body = env.get(K_BODY)

        if t in (T_MSG, T_NOTICE) and isinstance(body, str):
@@ -716,6 +722,9 @@ class MessageRouter:
                    )
                    return
        elif t == T_NOTICE:
+            if dst is not None:
+                self._handle_direct_notice(link, sess, peer_hash, env, outgoing)
+                return
            if not isinstance(room, str) or not room:
                return

@@ -829,6 +838,87 @@ class MessageRouter:
        else:
            self.hub.stats_manager.inc("notices_forwarded")

+    def _handle_direct_notice(
+        self,
+        link: RNS.Link,
+        sess: dict[str, Any],
+        peer_hash: bytes,
+        env: dict,
+        outgoing: list[tuple[RNS.Link, bytes]],
+    ) -> None:
+        """Handle client-to-client NOTICE delivery by destination identity."""
+        if self.hub.identity is None:
+            return
+
+        dst = env.get(K_DST)
+        room = env.get(K_ROOM)
+
+        if room is not None:
+            self.hub.message_helper.emit_error(
+                outgoing,
+                link,
+                src=self.hub.identity.hash,
+                text="direct notice must not include room",
+            )
+            return
+
+        if not isinstance(dst, (bytes, bytearray)):
+            self.hub.message_helper.emit_error(
+                outgoing,
+                link,
+                src=self.hub.identity.hash,
+                text="direct notice requires destination identity",
+            )
+            return
+
+        target_link = self.hub.session_manager.get_link_by_hash(bytes(dst))
+        if target_link is None:
+            self.hub.message_helper.emit_error(
+                outgoing,
+                link,
+                src=self.hub.identity.hash,
+                text="destination not connected",
+            )
+            return
+
+        env[K_SRC] = (
+            bytes(peer_hash) if isinstance(peer_hash, (bytes, bytearray)) else peer_hash
+        )
+
+        incoming_nick = env.get(K_NICK)
+        if incoming_nick is not None:
+            n = normalize_nick(incoming_nick, max_bytes=self.hub.config.max_nick_bytes)
+            if n is not None:
+                old_session_nick = sess.get("nick")
+                if old_session_nick != n:
+                    sess["nick"] = n
+                    self.hub.session_manager.update_nick_index(
+                        link, old_session_nick, n
+                    )
+                env[K_NICK] = n
+            else:
+                env.pop(K_NICK, None)
+        else:
+            nick = sess.get("nick")
+            n = normalize_nick(nick, max_bytes=self.hub.config.max_nick_bytes)
+            if n is not None:
+                env[K_NICK] = n
+
+        env[K_DST] = bytes(dst)
+        payload = encode(env)
+        self.hub.message_helper.queue_payload(outgoing, target_link, payload)
+
+        if self.log.isEnabledFor(logging.DEBUG):
+            self.log.debug(
+                "Forwarded direct NOTICE peer=%s nick=%r dst=%s body_type=%s",
+                self.hub._fmt_hash(peer_hash),
+                sess.get("nick"),
+                bytes(dst).hex(),
+                type(env.get(K_BODY)).__name__,
+            )
+
+        self.hub.stats_manager.inc("notices_forwarded")
+
    def _handle_ping(
        self,
        link: RNS.Link,
@@ -143,7 +143,12 @@ class SessionManager:
                        peer_still_in_room = True
                        break

-            if remaining_members and peer_hash and self.hub.identity and not peer_still_in_room:
+            if (
+                remaining_members
+                and peer_hash
+                and self.hub.identity
+                and not peer_still_in_room
+            ):
                notification_body = (
                    [peer_hash] if self.hub.config.include_joined_member_list else None
                )
@@ -4,7 +4,19 @@ import threading
 from dataclasses import dataclass

 from rrcd.codec import decode
-from rrcd.constants import B_WELCOME_CAPS, CAP_ACTION, CAP_RESOURCE_ENVELOPE, K_BODY, K_T, T_ACTION
+from rrcd.constants import (
+    B_WELCOME_CAPS,
+    CAP_ACTION,
+    CAP_DIRECT_NOTICE,
+    CAP_RESOURCE_ENVELOPE,
+    K_BODY,
+    K_DST,
+    K_NICK,
+    K_SRC,
+    K_T,
+    T_ACTION,
+    T_NOTICE,
+)
 from rrcd.envelope import make_envelope
 from rrcd.messages import MessageHelper
 from rrcd.router import MessageRouter
@@ -49,13 +61,26 @@ class _FakeRoomManager:


 class _FakeSessionManager:
-    def update_nick_index(self, link: object, old_nick: str | None, new_nick: str | None) -> None:
+    def __init__(self) -> None:
+        self.targets: dict[bytes, object] = {}
+
+    def update_nick_index(
+        self, link: object, old_nick: str | None, new_nick: str | None
+    ) -> None:
        return

+    def get_link_by_hash(self, peer_hash: bytes) -> object | None:
+        return self.targets.get(bytes(peer_hash))
+

 class _FakeMessageHelper:
-    def emit_error(self, outgoing, link, *, src: bytes, text: str, room: str | None = None) -> None:
-        raise AssertionError(f"unexpected error emitted: {text}")
+    def __init__(self) -> None:
+        self.errors: list[tuple[object, str, str | None]] = []
+
+    def emit_error(
+        self, outgoing, link, *, src: bytes, text: str, room: str | None = None
+    ) -> None:
+        self.errors.append((link, text, room))

    def queue_payload(self, outgoing, link, payload: bytes) -> None:
        outgoing.append((link, payload))
@@ -82,7 +107,7 @@ class _FakeLink:


 class _FakeHub:
-    def __init__(self, link: object) -> None:
+    def __init__(self, link: object, members: list[object] | None = None) -> None:
        import logging

        self.log = logging.getLogger("test")
@@ -90,7 +115,7 @@ class _FakeHub:
        self.config = _FakeConfig()
        self.stats_manager = _FakeStats()
        self.command_handler = _FakeCommandHandler()
-        self.room_manager = _FakeRoomManager([link])
+        self.room_manager = _FakeRoomManager(members if members is not None else [link])
        self.session_manager = _FakeSessionManager()
        self.message_helper = _FakeMessageHelper()
        self._state_lock = threading.RLock()
@@ -117,6 +142,7 @@ def test_action_is_forwarded_without_command_interpretation() -> None:
    router._handle_message(link, sess, b"peer", env, outgoing)

    assert hub.command_handler.called is False
+    assert hub.message_helper.errors == []
    assert hub.stats_manager.counters.get("actions_forwarded") == 1
    assert len(outgoing) == 1

@@ -152,4 +178,72 @@ def test_welcome_advertises_action_capability() -> None:
    decoded = decode(outgoing[0][1])
    caps = decoded[K_BODY][B_WELCOME_CAPS]
    assert caps[CAP_ACTION] is True
+    assert caps[CAP_DIRECT_NOTICE] is True
    assert caps[CAP_RESOURCE_ENVELOPE] is True
+
+
+def test_notice_is_forwarded_to_direct_destination() -> None:
+    sender_link = _FakeLink()
+    target_link = object()
+    hub = _FakeHub(sender_link)
+    hub.session_manager.targets[b"target"] = target_link
+    router = MessageRouter(hub)
+
+    sess = {"rooms": set(), "nick": "alice"}
+    env = make_envelope(T_NOTICE, src=b"spoofed", dst=b"target", body="hello")
+    outgoing: list[tuple[object, bytes]] = []
+
+    router._handle_message(sender_link, sess, b"peer", env, outgoing)
+
+    assert hub.message_helper.errors == []
+    assert hub.stats_manager.counters.get("notices_forwarded") == 1
+    assert len(outgoing) == 1
+    assert outgoing[0][0] is target_link
+
+    decoded = decode(outgoing[0][1])
+    assert decoded[K_T] == T_NOTICE
+    assert decoded[K_SRC] == b"peer"
+    assert decoded[K_DST] == b"target"
+    assert decoded[K_NICK] == "alice"
+    assert decoded[K_BODY] == "hello"
+
+
+def test_direct_notice_rejects_room_and_destination_combination() -> None:
+    sender_link = _FakeLink()
+    hub = _FakeHub(sender_link)
+    hub.session_manager.targets[b"target"] = object()
+    router = MessageRouter(hub)
+
+    sess = {"rooms": {"#general"}, "nick": "alice"}
+    env = make_envelope(
+        T_NOTICE,
+        src=b"peer",
+        dst=b"target",
+        room="#general",
+        body="hello",
+    )
+    outgoing: list[tuple[object, bytes]] = []
+
+    router._handle_message(sender_link, sess, b"peer", env, outgoing)
+
+    assert outgoing == []
+    assert hub.message_helper.errors == [
+        (sender_link, "direct notice must not include room", None)
+    ]
+
+
+def test_direct_notice_rejects_unknown_destination() -> None:
+    sender_link = _FakeLink()
+    hub = _FakeHub(sender_link)
+    router = MessageRouter(hub)
+
+    sess = {"rooms": set(), "nick": "alice"}
+    env = make_envelope(T_NOTICE, src=b"peer", dst=b"missing", body="hello")
+    outgoing: list[tuple[object, bytes]] = []
+
+    router._handle_message(sender_link, sess, b"peer", env, outgoing)
+
+    assert outgoing == []
+    assert hub.message_helper.errors == [
+        (sender_link, "destination not connected", None)
+    ]
@@ -3,6 +3,7 @@ import pytest
 from rrcd.constants import (
    B_HELLO_NICK_LEGACY,
    K_BODY,
+    K_DST,
    K_ID,
    K_NICK,
    K_SRC,
@@ -26,6 +27,12 @@ def test_validate_accepts_optional_nick_extension() -> None:
    validate_envelope(env)


+def test_validate_accepts_optional_destination_extension() -> None:
+    env = make_envelope(T_HELLO, src=b"peer", dst=b"target", body=None)
+    assert env[K_DST] == b"target"
+    validate_envelope(env)
+
+
 def test_validate_allows_ridiculous_or_empty_nick() -> None:
    env = make_envelope(T_HELLO, src=b"peer", body=None)
    env[K_NICK] = ""
@@ -89,3 +96,8 @@ def test_validate_rejects_wrong_field_types() -> None:
    env[K_NICK] = 123
    with pytest.raises(TypeError):
        validate_envelope(env)
+
+    env = make_envelope(T_HELLO, src=b"peer", body=None)
+    env[K_DST] = "not-bytes"
+    with pytest.raises(TypeError):
+        validate_envelope(env)