fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/transport/mediation/types.py

@@ -0,0 +1,20 @@
+"""Types and records for the Mediation compartment."""
+from __future__ import annotations
+
+from typing import Any, Optional, TypedDict
+
+
+class DeliveredMessage(TypedDict):
+    """Message unwrapped and delivered via mediation pickup."""
+    id: str
+    recipient_key: str
+    sender: str
+    attachments: list[Any]
+    enqueued_at: int
+
+
+class MediationGrantInfo(TypedDict):
+    """Information regarding a granted mediation contract."""
+    routing_keys: list[str]
+    endpoint: Optional[str]
+    granted_at: int

node/planes/transport/p2p/__init__.py

@@ -0,0 +1,7 @@
+"""Direct libp2p P2P transport, reached through a sidecar, as a compartment.
+
+One-module compartment: everything is in compartment.py.
+"""
+from .compartment import P2PTransport
+
+__all__ = ['P2PTransport']

node/planes/transport/p2p/compartment.py

@@ -0,0 +1,349 @@
+"""Direct libp2p P2P transport, reached through a sidecar, as a compartment.
+
+Protocol: `/fleetmesh/didcomm/1.0.0` as declared in `schema/messages.json`.
+One stream carries one JWE; the other side answers one ack line once it has
+queued the message for its node. The libp2p process is `sidecar/fleetmesh_p2p.py`,
+talked to over `p2p.sock` in the node's directory, and it holds the Ed25519
+transport key: its PeerId *is* the `key transport` Multikey the descriptor
+publishes, which is how a dial is bound to a descriptor and not to whatever
+multiaddr the descriptor happened to carry (see `target_of`).
+
+What this compartment does with a stream it drained is what the FIPS path
+does with a datagram: hands the bytes to the router's one envelope-opening
+rule (`didcomm_inbound.open_inbound`). The sidecar's word on who wrote a
+stream is a hint the router checks against the sender's descriptor, never a
+proof of who sent the message; that proof is the ECDH-1PU agreement or nothing.
+
+Like `node/announce.py`, if the sidecar is absent the node operates over the
+relays, which is the rung the specification says always works.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from typing import Any, Callable, Mapping, Optional
+
+
+from node.compartment import stores as st
+from node.compartment import Command, Need
+from node.config import P2PConfig
+from node.config.parameter import Parameter
+from node.compartment.lifecycle import Lifecycle
+from node.compartment.sidecar import Bridge, Sidecar, SidecarError, jsonline_call
+from fleetmesh_core.crypto import keys
+from fleetmesh_core.identity.did import b58encode as _b58  # base58btc, written once (audit D9)
+
+SOCK: str = 'p2p.sock'
+PROTOCOL: str = 'fleetmesh-p2p/1'
+STREAM_PROTOCOL: str = '/fleetmesh/didcomm/1.0.0'
+SCHEME: str = 'libp2p'
+MAX_LINE: int = 1 << 20
+DRAIN_MAX: int = 64
+
+
+
+def socket_path(directory: str) -> str:
+    """Derive the unix socket path for the p2p sidecar."""
+    real = os.path.realpath(directory)
+    p = os.path.join(real, SOCK)
+    if len(p.encode('utf-8')) < 100:
+        return p
+    return os.path.join(
+        tempfile.gettempdir(),
+        'fleetmesh-p2p-%s.sock' % hashlib.sha256(real.encode('utf-8')).hexdigest()[:16]
+    )
+
+
+def peer_id_of(raw_ed25519: bytes) -> str:
+    """The libp2p PeerId of an Ed25519 public key: the key itself, inlined.
+
+    A 32-byte key fits under the identity multihash, so the id is the
+    protobuf `PublicKey{Type: Ed25519, Data: key}` wrapped as
+    `multihash(0x00, len, pb)` and base58btc-encoded - the `12D3KooW...`
+    form. No hashing, so a descriptor's `key transport` Multikey and a
+    stream's remote PeerId are the same 32 bytes spelled two ways.
+    """
+    if len(raw_ed25519) != 32:
+        raise ValueError('an Ed25519 public key is 32 bytes')
+    pb = b'\x08\x01\x12\x20' + raw_ed25519
+    return _b58(b'\x00' + bytes([len(pb)]) + pb)
+
+
+def transport_key_of(desc: Optional[Mapping[str, Any]]) -> Optional[bytes]:
+    """The raw Ed25519 transport key a descriptor publishes, or None."""
+    if desc is None:
+        return None
+    for t in desc.get('tags', []):
+        if len(t) > 2 and t[0] == 'key' and t[1] == 'transport':
+            try:
+                kind, raw = keys.parse_multikey(t[2])
+            except ValueError:
+                return None
+            return raw if kind == 'transport' else None
+    return None
+
+
+def target_of(desc: Optional[Mapping[str, Any]]) -> tuple[Optional[str], Optional[str]]:
+    """The multiaddr to dial for a descriptor, or why there is none.
+
+    Returns (target, None) or (None, reason). The target always ends in
+    `/p2p/<PeerId>` derived from the descriptor's own `key transport`: the
+    libp2p handshake then refuses any host at that address that does not
+    hold the key the descriptor signed over. A descriptor whose endpoint
+    already names a PeerId must name the same one; a different one is a
+    descriptor that contradicts itself, and is not dialled.
+    """
+    if desc is None:
+        return None, 'no descriptor'
+    addr = None
+    for t in desc.get('tags', []):
+        if len(t) > 2 and t[0] == 'endpoint' and t[1] == SCHEME:
+            addr = t[2]
+            break
+    if not addr:
+        return None, 'no libp2p endpoint'
+    raw = transport_key_of(desc)
+    if raw is None:
+        return None, 'no transport key'
+    pid = peer_id_of(raw)
+    if '/p2p/' in addr:
+        head, _, named = addr.rpartition('/p2p/')
+        if named != pid:
+            return None, 'endpoint names a PeerId that is not the transport key'
+        addr = head
+    return '%s/p2p/%s' % (addr.rstrip('/'), pid), None
+
+
+class P2PError(SidecarError):
+    """Raised when communication with the p2p sidecar fails."""
+
+
+def ask_sidecar(directory: str, cmd: str, timeout: float = 5.0, **args: Any) -> Any:
+    """Send one request to the p2p sidecar over its unix domain socket."""
+    path = socket_path(directory)
+    try:
+        result, _ = jsonline_call(path, cmd, timeout=timeout, **args)
+        return result
+    except SidecarError as e:
+        raise P2PError(str(e)) from e
+
+
+from .types import P2PState, SendResult
+
+
+class P2PTransport(Bridge):
+
+    optional: bool = True
+    enabled_by: Optional[str] = 'p2p'
+    """The direct libp2p transport compartment."""
+
+    name: str = 'p2p'
+    reads: tuple[str, ...] = ('p2p', 'endpoints')
+    config_cls = P2PConfig
+
+    SIDECAR = Sidecar(
+        name='p2p',
+        protocol=PROTOCOL,
+        upstream='py-libp2p stream transport on %s' % STREAM_PROTOCOL,
+        standalone='fleetmesh-p2p NODE_DIR',
+        probe='status',
+    )
+    CONSEQUENCE: str = 'direct libp2p connections are unavailable; falling back to relays'
+    LIFECYCLE = Lifecycle(restart=True)
+
+    # Declared by the bridge from SIDECAR (p2p_sidecar_reachable / _unreachable / _incompatible).
+    SIDECAR_REACHABLE: str = 'p2p.sidecar.reachable'
+    SIDECAR_UNREACHABLE: str = 'p2p.sidecar.unreachable'
+    SIDECAR_INCOMPATIBLE: str = 'p2p.sidecar.incompatible'
+
+    NEEDS = (
+        Need('directory', 'dir'),
+        Need('peers', 'peers'),
+        Need('transport', 'transport'),
+        Need('ks', 'ks'),
+    )
+    STORES = (
+        st.Store(key='egress_queue', description='outbound frames queued for libp2p sidecar',
+                 kind=st.RING, shape=bytes, bound=1024),
+    )
+    COMMANDS = (
+        Command(
+            key='status',
+            name='P2P Status',
+            description='display libp2p sidecar connectivity and stream counters',
+            tags=('p2p', 'status'),
+            permission='p2p/status',
+            run='state',
+            reply='dict',
+        ),
+        Command(
+            key='drain',
+            name='Drain P2P Streams',
+            description='drain inbound direct P2P messages from the sidecar',
+            tags=('p2p', 'drain'),
+            permission='p2p/drain',
+            run='drain_cmd',
+            reply='dict',
+        ),
+        Command(
+            key='send',
+            name='Send P2P Message',
+            description='dispatch one already-sealed JWE over a libp2p stream',
+            tags=('p2p', 'send'),
+            parameters=(
+                Parameter(key='target', name='target', description='target multiaddr', type=str, default='', required=True),
+                Parameter(key='payload', name='payload', description='sealed JWE payload', type=dict, default=dict, required=True),
+            ),
+            permission='p2p/send',
+            run='send_cmd',
+            reply='dict',
+        ),
+    )
+
+    def __init__(self, directory: str, peers: Any = None, transport: Any = None, clock: Optional[Callable[[], int]] = None, node: Any = None,
+                 ks: Any = None) -> None:
+        super().__init__(node, clock)
+        # The keystore whose transport key the sidecar's peer id is checked against.
+        self.ks: Any = ks if ks is not None else getattr(node, 'ks', None)
+        self.dir: str = directory
+        self.peers: Any = peers
+        self.transport: Any = transport
+        self.connected: bool = False
+        self.sent_count: int = 0
+        self.recv_count: int = 0
+        self.refused_count: int = 0
+        self.last_drain_at: Optional[int] = None
+        self.peer_id: Optional[str] = None
+        self.addrs: list[str] = []  # not a store: the local node's p2p multiaddrs from sidecar
+        self._said_missing: bool = False
+        if transport is not None and hasattr(transport, 'p2p'):
+            transport.p2p = self
+
+    # ---- the bridge -----------------------------------------------------------
+    def endpoint(self) -> str:
+        return socket_path(self.dir)
+
+    def wanted(self) -> bool:
+        return bool(self.config('p2p', False))
+
+    def forget(self) -> None:
+        self.connected = False
+        self.peer_id = None
+        self.addrs = []  # not a store: cleared on forget
+
+    def state(self) -> P2PState:
+        st: P2PState = {
+            'enabled': bool(self.config('p2p', True)),
+            'socket': self.endpoint(),
+            'connected': self.connected,
+            'peer_id': self.peer_id,
+            'addrs': self.addrs,
+            'sent_count': self.sent_count,
+            'recv_count': self.recv_count,
+            'refused_count': self.refused_count,
+            'last_drain_at': self.last_drain_at,
+        }
+        if self.connected:
+            try:
+                st['sidecar'] = self.call('status', timeout=1.0)
+            except Exception:
+                pass
+        return st
+
+    def sections(self) -> Mapping[str, Any]:
+        return {
+            'bridge': self.bridge_state(),
+            'p2p': self.state(),
+        }
+
+    def trouble(self) -> list[str]:
+        out = list(super().trouble())
+        if self.connected and self.peer_id and self.ks is not None:
+            mine = peer_id_of(keys.raw_public(self.ks.transport_pub))
+            if mine != self.peer_id:
+                out.append('p2p sidecar holds a different transport key (%s) than this node publishes (%s)'
+                           % (self.peer_id[:16], mine[:16]))
+        return out
+
+    def tick(self, now: int) -> list[tuple[Any, ...]]:
+        did: list[tuple[Any, ...]] = []
+        if not self.config('p2p', True):
+            return did
+
+        was_connected = self.connected
+        # Check sidecar liveness
+        try:
+            res = self.call('status', timeout=1.0)
+            self.peer_id = res.get('peer_id')
+            self.addrs = list(res.get('addrs') or [])  # not a store: the local node's p2p multiaddrs from sidecar
+            if not was_connected:
+                self.connected = True
+                self._said_missing = False
+                did.append(('p2p sidecar connected', (self.peer_id or 'unknown')[:16]))
+        except (P2PError, SidecarError) as e:
+            if was_connected:
+                self.connected = False
+                did.append(('p2p sidecar dropped', str(e)))
+            elif not self._said_missing and self.config('p2p', False):
+                self._said_missing = True
+            return did
+
+        # Drain inbound streams and hand each to the router's envelope rule.
+        try:
+            res = self.call('drain', timeout=2.0, max_items=DRAIN_MAX)
+        except (P2PError, SidecarError) as e:
+            self.refusals.refuse('p2p', 'drain failed', detail={'error': str(e)})
+            return did
+        items = res.get('items') or [] if isinstance(res, dict) else []
+        for reason, n in ((res.get('refused') or {}) if isinstance(res, dict) else {}).items():
+            self.refusals.refuse('p2p', 'sidecar refused a stream: %s' % reason, detail={'count': n})
+        if items:
+            self.recv_count += len(items)
+            self.last_drain_at = now
+            did.append(('p2p drained', len(items)))
+            for it in items:
+                why = self.deliver(it)
+                if why is not None:
+                    self.refused_count += 1
+                    self.refusals.refuse('p2p', why, detail={'from_peer': str(it.get('from_peer', ''))[:24]})
+        return did
+
+    def deliver(self, item: Mapping[str, Any]) -> Optional[str]:
+        """One drained stream to the router. Returns None, or why it was refused.
+
+        `injected` items are what the sidecar's test hook queued: no stream
+        was authenticated, so no origin key is asserted for them.
+        """
+        msg = item.get('message')
+        if not isinstance(msg, dict):
+            return 'stream carried no object'
+        origin = None if item.get('injected') else item.get('from_key')
+        if self.transport is None or not hasattr(self.transport, 'deliver_direct'):
+            return 'no router to deliver to'
+        wrap_id = 'libp2p-%s' % hashlib.sha256(
+            json.dumps(msg, sort_keys=True, separators=(',', ':')).encode('utf-8')).hexdigest()[:16]
+        result: Optional[str] = self.transport.deliver_direct(SCHEME, msg, wrap_id, origin=origin)
+        return result
+
+    def send_direct(self, target_multiaddr: str, payload: Mapping[str, Any]) -> tuple[bool, str]:
+        """Deliver one sealed JWE to `target_multiaddr`; True only after the peer acked."""
+        try:
+            res = ask_sidecar(self.dir, 'send', timeout=6.0, target=target_multiaddr, payload=payload)
+        except (P2PError, SidecarError) as e:
+            self.refusals.refuse('p2p', 'direct send failed', detail={'target': target_multiaddr[:80], 'error': str(e)})
+            return False, str(e)
+        if not isinstance(res, dict) or not res.get('accepted'):
+            return False, 'sidecar did not report an acknowledged delivery'
+        self.sent_count += 1
+        return True, 'delivered via libp2p stream to %s' % res.get('peer_id', target_multiaddr)[:24]
+
+    def drain_cmd(self) -> Any:
+        return self.call('drain')
+
+    def send_cmd(self, args: Mapping[str, Any]) -> SendResult:
+        ok, note = self.send_direct(str(args['target']), dict(args['payload']))
+        return {'accepted': ok, 'note': note}
+
+

node/planes/transport/p2p/types.py

@@ -0,0 +1,22 @@
+"""Types and records for the P2P transport compartment."""
+from __future__ import annotations
+
+from typing import Any, Optional, TypedDict
+
+
+class P2PState(TypedDict, total=False):
+    enabled: bool
+    socket: str
+    connected: bool
+    peer_id: Optional[str]
+    addrs: list[str]
+    sent_count: int
+    recv_count: int
+    refused_count: int
+    last_drain_at: Optional[int]
+    sidecar: Any
+
+
+class SendResult(TypedDict):
+    accepted: bool
+    note: str

node/protocols/__init__.py

@@ -0,0 +1,277 @@
+"""Pluggable protocol suites and package registry for Fleetmesh node.
+
+Manages dynamic discovery, configuration, lifecycle, and multiplexing
+across all supported open protocol families:
+- Nostr & Blossom (`fleetmesh-protocol-nostr`)
+- AT Protocol (`fleetmesh-protocol-atproto`)
+- ActivityPub & ActivityStreams 2.0 (`fleetmesh-protocol-activitypub`)
+- Secure Scuttlebutt (`fleetmesh-protocol-ssb`)
+- p2panda (`fleetmesh-protocol-p2panda`)
+- Rhio (`fleetmesh-protocol-rhio`)
+"""
+from __future__ import annotations
+
+import importlib
+import logging
+from typing import Any, Callable, Mapping, Optional
+
+from fleetmesh_core.wire.interfaces import (
+    ProtocolHealth,
+    ProtocolHostRouter,
+    ProtocolPackage,
+)
+
+log = logging.getLogger(__name__)
+
+# Registry of built-in protocol packages
+BUILTIN_PACKAGE_LOADERS: dict[str, tuple[str, str]] = {
+    'nostr': ('node.protocols.nostr.package', 'NostrProtocolPackage'),
+    'atproto': ('node.protocols.atproto.package', 'AtprotoProtocolPackage'),
+    'activitypub': ('node.protocols.activitypub.package', 'ActivityPubProtocolPackage'),
+    'ssb': ('node.protocols.ssb.package', 'SSBProtocolPackage'),
+    'p2panda': ('node.protocols.p2panda.package', 'P2PandaProtocolPackage'),
+    'rhio': ('node.protocols.rhio.package', 'RhioProtocolPackage'),
+}
+
+_CUSTOM_PACKAGES: dict[str, type[ProtocolPackage]] = {}
+
+
+def register_protocol(name: str, package_cls: type[ProtocolPackage]) -> None:
+    """Register a custom or third-party protocol package class."""
+    clean_name = name.lower().strip()
+    _CUSTOM_PACKAGES[clean_name] = package_cls
+
+
+def get_available_protocols() -> tuple[str, ...]:
+    """Return all currently registered protocol names."""
+    return tuple(sorted(set(BUILTIN_PACKAGE_LOADERS.keys()) | set(_CUSTOM_PACKAGES.keys())))
+
+
+def load_protocol_package_class(name: str) -> type[ProtocolPackage]:
+    """Dynamically load and return the ProtocolPackage class for a given name."""
+    clean_name = name.lower().strip()
+    if clean_name in _CUSTOM_PACKAGES:
+        return _CUSTOM_PACKAGES[clean_name]
+
+    if clean_name in BUILTIN_PACKAGE_LOADERS:
+        mod_name, cls_name = BUILTIN_PACKAGE_LOADERS[clean_name]
+        try:
+            mod = importlib.import_module(mod_name)
+            cls = getattr(mod, cls_name)
+            return cls
+        except Exception as e:
+            raise ImportError(f"Failed to load protocol package '{clean_name}' from {mod_name}.{cls_name}: {e}") from e
+
+    raise KeyError(f"Unknown protocol package '{name}'. Available: {get_available_protocols()}")
+
+
+def create_protocol_package(name: str, **kwargs) -> ProtocolPackage:
+    """Instantiate a protocol package by name with provided arguments."""
+    cls = load_protocol_package_class(name)
+    return cls(**kwargs)
+
+
+class ProtocolManager:
+    """Orchestrates configuration, lifecycle, and routing across all protocol packages."""
+
+    def __init__(
+        self,
+        node_dir: Optional[str] = None,
+        keystore: Optional[Any] = None,
+        clock: Optional[Callable[[], int]] = None,
+        name: str = 'meshnode',
+    ):
+        self.node_dir = node_dir
+        self.keystore = keystore
+        self.clock = clock
+        self.node_name = name
+
+        self._packages: dict[str, ProtocolPackage] = {}
+        self._mounted_host: Optional[ProtocolHostRouter] = None
+
+    @property
+    def packages(self) -> Mapping[str, ProtocolPackage]:
+        return dict(self._packages)
+
+    def get_package(self, name: str) -> Optional[ProtocolPackage]:
+        return self._packages.get(name.lower().strip())
+
+    def load_suites_config(
+        self,
+        suites_config: Any,
+        backend_store: Optional[Any] = None,
+        blob_store: Optional[Any] = None,
+        grants: Optional[Any] = None,
+        node_instance: Optional[Any] = None,
+        private_key: Optional[Any] = None,
+        strain_ledger: Optional[Any] = None,
+    ) -> dict[str, ProtocolPackage]:
+        """Initialize protocol packages based on ProtocolSuitesConfig or mapping."""
+        suites_dict: Mapping[str, Any] = {}
+        if hasattr(suites_config, 'to_dict'):
+            suites_dict = suites_config.to_dict()
+        elif hasattr(suites_config, 'as_dict'):
+            suites_dict = suites_config.as_dict()
+        elif hasattr(suites_config, '__dict__'):
+            suites_dict = {
+                k: getattr(suites_config, k).to_dict() if hasattr(getattr(suites_config, k), 'to_dict') else (getattr(suites_config, k).as_dict() if hasattr(getattr(suites_config, k), 'as_dict') else getattr(suites_config, k))
+                for k in ('nostr', 'atproto', 'activitypub', 'ssb', 'p2panda', 'rhio')
+                if getattr(suites_config, k, None) is not None
+            }
+        elif isinstance(suites_config, Mapping):
+            suites_dict = dict(suites_config)
+
+        if self._packages:
+            self.stop_all()
+            self._packages.clear()
+
+        # 1. Nostr
+        cfg_nostr = suites_dict.get('nostr')
+        if cfg_nostr is not None and (isinstance(cfg_nostr, Mapping) and cfg_nostr.get('enabled', True)):
+            from node.protocols.nostr.package import NostrProtocolPackage
+            pkg_nostr = NostrProtocolPackage(
+                backend=backend_store,
+                blob_store=blob_store,
+                grants=grants,
+                node=node_instance,
+                clock=self.clock,
+                name=self.node_name,
+                pubkey=getattr(self.keystore, 'node_pk', None) if self.keystore else None,
+            )
+            pkg_nostr.configure(cfg_nostr if isinstance(cfg_nostr, Mapping) else {})
+            self._packages['nostr'] = pkg_nostr
+
+        # 2. ATProto
+        cfg_atp = suites_dict.get('atproto')
+        if cfg_atp is not None and (isinstance(cfg_atp, Mapping) and cfg_atp.get('enabled', True)):
+            from node.protocols.atproto.package import AtprotoProtocolPackage
+            pkg_atp = AtprotoProtocolPackage(
+                blob_store=blob_store,
+                keystore=self.keystore,
+            )
+            pkg_atp.configure(cfg_atp if isinstance(cfg_atp, Mapping) else {})
+            self._packages['atproto'] = pkg_atp
+
+        # 3. ActivityPub
+        cfg_ap = suites_dict.get('activitypub')
+        if cfg_ap is not None and (isinstance(cfg_ap, Mapping) and cfg_ap.get('enabled', True)):
+            from node.protocols.activitypub.package import ActivityPubProtocolPackage
+            domain = cfg_ap.get('domain', 'node.fleetmesh.local') if isinstance(cfg_ap, Mapping) else 'node.fleetmesh.local'
+            pkg_ap = ActivityPubProtocolPackage(
+                domain=domain,
+                username="node",
+                private_key=private_key or getattr(self.keystore, 'ed25519_sk', None),
+                blob_store=blob_store,
+                strain_ledger=strain_ledger,
+                keystore=self.keystore,
+            )
+            pkg_ap.configure(cfg_ap if isinstance(cfg_ap, Mapping) else {})
+            self._packages['activitypub'] = pkg_ap
+
+        # 4. SSB
+        cfg_ssb = suites_dict.get('ssb')
+        if cfg_ssb is not None and (isinstance(cfg_ssb, Mapping) and cfg_ssb.get('enabled', True)):
+            from node.protocols.ssb.package import SSBProtocolPackage
+            pkg_ssb = SSBProtocolPackage(
+                node_dir=self.node_dir or "/tmp/fleetmesh-ssb",
+                private_key=private_key or getattr(self.keystore, 'ed25519_sk', None),
+            )
+            pkg_ssb.configure(cfg_ssb if isinstance(cfg_ssb, Mapping) else {})
+            self._packages['ssb'] = pkg_ssb
+
+        # 5. P2Panda
+        cfg_p2p = suites_dict.get('p2panda')
+        if cfg_p2p is not None and (isinstance(cfg_p2p, Mapping) and cfg_p2p.get('enabled', False)):
+            if 'p2panda' in _CUSTOM_PACKAGES or 'p2panda' in BUILTIN_PACKAGE_LOADERS:
+                try:
+                    pkg_p2p = create_protocol_package(
+                        'p2panda',
+                        node_dir=self.node_dir,
+                        keystore=self.keystore,
+                        blob_store=blob_store,
+                    )
+                    pkg_p2p.configure(cfg_p2p if isinstance(cfg_p2p, Mapping) else {})
+                    self._packages['p2panda'] = pkg_p2p
+                except Exception as e:
+                    log.warning("Could not instantiate p2panda protocol package: %s", e)
+
+        # 6. Rhio
+        cfg_rhio = suites_dict.get('rhio')
+        if cfg_rhio is not None and (isinstance(cfg_rhio, Mapping) and cfg_rhio.get('enabled', False)):
+            if 'rhio' in _CUSTOM_PACKAGES or 'rhio' in BUILTIN_PACKAGE_LOADERS:
+                try:
+                    pkg_rhio = create_protocol_package(
+                        'rhio',
+                        node_dir=self.node_dir,
+                        keystore=self.keystore,
+                        blob_store=blob_store,
+                    )
+                    pkg_rhio.configure(cfg_rhio if isinstance(cfg_rhio, Mapping) else {})
+                    self._packages['rhio'] = pkg_rhio
+                except Exception as e:
+                    log.warning("Could not instantiate rhio protocol package: %s", e)
+
+        return dict(self._packages)
+
+    def mount_ingress(self, host: ProtocolHostRouter) -> None:
+        """Mount all active protocol packages onto the shared host multiplexer."""
+        self._mounted_host = host
+        for name, pkg in self._packages.items():
+            try:
+                pkg.mount_ingress(host)
+                log.info("Mounted ingress for protocol '%s'", name)
+            except Exception as e:
+                log.exception("Failed to mount ingress for protocol '%s': %s", name, e)
+
+    def mount_transport_rungs(self, router: Any) -> list[Any]:
+        """Mount outbound rungs into TransportRouter ladder."""
+        mounted = []
+        for name, pkg in self._packages.items():
+            try:
+                rung = pkg.transport_rung(router)
+                if rung is not None:
+                    if hasattr(router, 'register_rung'):
+                        router.register_rung(rung)
+                    elif hasattr(router, 'add_rung'):
+                        router.add_rung(rung)
+                    mounted.append(rung)
+            except Exception as e:
+                log.exception("Failed to build transport rung for protocol '%s': %s", name, e)
+        return mounted
+
+    def start_all(self) -> None:
+        """Start all configured protocol packages."""
+        for name, pkg in self._packages.items():
+            try:
+                pkg.start()
+            except Exception as e:
+                log.exception("Error starting protocol package '%s': %s", name, e)
+
+    def stop_all(self) -> None:
+        """Stop all configured protocol packages and unmount ingress."""
+        for name, pkg in self._packages.items():
+            try:
+                pkg.stop()
+            except Exception as e:
+                log.exception("Error stopping protocol package '%s': %s", name, e)
+        if self._mounted_host is not None:
+            for name in self._packages:
+                try:
+                    self._mounted_host.unmount_all(name)
+                except Exception:
+                    pass
+            self._mounted_host = None
+
+    def health(self) -> dict[str, ProtocolHealth]:
+        """Collect health telemetry across all loaded protocol packages."""
+        return {name: pkg.health() for name, pkg in self._packages.items()}
+
+    def descriptor_capabilities(self) -> tuple[tuple[str, str], ...]:
+        """Aggregate descriptor capabilities from all active packages."""
+        caps: list[tuple[str, str]] = []
+        for pkg in self._packages.values():
+            try:
+                caps.extend(pkg.descriptor_capabilities())
+            except Exception:
+                pass
+        return tuple(caps)