fleetmesh-node 0.2.0__py3-none-any.whl

node/transport/rung.py

@@ -0,0 +1,276 @@
+"""One rung of the transport ladder, and the four the node has.
+
+The router used to know how every rung dials: four if-blocks, each with
+its own seal, its own breaker lookup, its own cascade note. Now a rung is
+one object that says whether it is up, whether it can reach a peer and
+where, and makes one delivery attempt; the router walks the ladder and
+keeps the books. A rung that is a compartment elsewhere (the relay rung,
+the libp2p transport) is reached through a thin adapter here so that it
+need not know the ladder exists.
+
+Adapters read their daemon off the router at call time (`router.fips`,
+`router.iroh`, `router.p2p`) rather than at construction: a test swaps a
+fake in after the router is built, and a sidecar registers itself later.
+
+Every rung answers the same four questions the same way - up?, where?,
+deliver, and what it did (health(), fault_log()) - so the router walks the
+ladder blindly for all of them. There is no rung the router knows by name.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Mapping, Optional, Protocol, TypedDict, runtime_checkable
+
+from . import fips_rung as fips_transport
+from .const import TransportError
+from .ladder import FaultLog
+
+Verdict = dict[str, tuple[bool, str]]
+Jwe = Mapping[str, Any]          # a DIDComm JWE as didcomm.encrypt returns it
+Seal = Callable[[Mapping[str, Any], str, bool], Jwe]
+
+
+class RungHealth(TypedDict, total=False):
+    """What a rung reports about itself; the daemon-backed rungs add their own keys."""
+    available: bool
+
+
+@runtime_checkable
+class RungProtocol(Protocol):
+    """What the ladder needs from a rung, and nothing it does not."""
+
+    name: str      # the scheme negotiate() ranks: 'fips-native', 'iroh', 'libp2p', 'nostr'
+    rank: int      # this node's preference; lower is tried first
+
+    def available(self) -> bool:
+        """The local side of this rung is up (daemon reachable, listener bound)."""
+        ...
+
+    def target_of(self, desc: Optional[Mapping[str, Any]], theirs: Mapping[str, int]) -> Optional[str]:
+        """Where this rung would reach the peer that published `desc`, or
+        None when the descriptor does not advertise it. `theirs` is the
+        peer's scheme -> preference map already read from the descriptor."""
+        ...
+
+    def deliver(self, message: Mapping[str, Any], to_pubkey: str, target: str, anonymous: bool) -> Verdict:
+        """One attempt. Returns {scheme: (delivered, note)}; raises on failure
+        so the ladder records it and moves on."""
+        ...
+
+    def health(self) -> Optional[Mapping[str, Any]]:
+        """What this rung reports about itself, or None when its daemon is
+        not built; the router keys it by rung name."""
+        ...
+
+    def fault_log(self) -> Optional[FaultLog]:
+        """The log of what this rung refused or lost, or None when it keeps
+        none; the router merges every log it is given."""
+        ...
+
+
+class Rung:
+    """Defaults for a rung that has nothing to report. The four rungs here
+    and any test double inherit it so the ladder never probes for a method."""
+
+    name: str = 'rung'
+    rank: int = 50
+
+    def available(self) -> bool:
+        return False
+
+    def target_of(self, desc: Optional[Mapping[str, Any]], theirs: Mapping[str, int]) -> Optional[str]:
+        return None
+
+    def deliver(self, message: Mapping[str, Any], to_pubkey: str, target: str, anonymous: bool) -> Verdict:
+        raise TransportError('%s rung does not deliver' % self.name)
+
+    def health(self) -> Optional[Mapping[str, Any]]:
+        return None
+
+    def fault_log(self) -> Optional[FaultLog]:
+        return None
+
+
+def _log_of(owner: Any) -> Optional[FaultLog]:
+    log = getattr(owner, 'faults', None)
+    return log if isinstance(log, FaultLog) else None
+
+
+def endpoints_of(desc: Optional[Mapping[str, Any]]) -> tuple[dict[str, int], dict[str, str]]:
+    """A descriptor's advertised rungs: (scheme -> preference, scheme -> address).
+
+    The 'key' tag with a fips transport key counts as a fips-native endpoint
+    at the strongest preference, the way the handshake reads it.
+    """
+    theirs: dict[str, int] = {}
+    where: dict[str, str] = {}
+    if desc is None:
+        return theirs, where
+    for t in desc.get('tags', []):
+        if not t:
+            continue
+        if t[0] == 'endpoint' and len(t) > 2:
+            scheme = 'fips-native' if t[1] == 'fips' else t[1]
+            pref = int(t[3]) if len(t) > 3 and str(t[3]).isdigit() else 50
+            theirs[scheme] = pref
+            where[scheme] = t[2]
+        elif t[0] == 'key' and len(t) > 2 and t[1] == 'fips':
+            where['fips-native'] = t[2]
+            theirs['fips-native'] = 5
+    return theirs, where
+
+
+class FipsRung(Rung):
+    """Datagram flows through the fips sidecar; mesh-encrypted by the daemon."""
+
+    name = 'fips-native'
+    rank = 5
+
+    def __init__(self, router: Any, seal: Seal) -> None:
+        self.router = router
+        self.seal = seal
+
+    def available(self) -> bool:
+        return self.router.fips is not None
+
+    def target_of(self, desc: Optional[Mapping[str, Any]], theirs: Mapping[str, int]) -> Optional[str]:
+        _, where = endpoints_of(desc)
+        if 'fips-native' in where:
+            return where['fips-native']
+        return '' if 'fips-native' in theirs else None
+
+    def deliver(self, message: Mapping[str, Any], to_pubkey: str, target: str, anonymous: bool) -> Verdict:
+        fips = self.router.fips
+        peer_key = target or to_pubkey
+        port = self.router.fips_port
+        if ':' in peer_key and not peer_key.startswith('did:'):
+            host, _, p = peer_key.partition(':')
+            if p.isdigit():
+                peer_key, port = host, int(p)
+        their_agree = self.router.peers.agreement(to_pubkey)
+        if their_agree is None:
+            raise TransportError('no live agreement key for peer %s' % to_pubkey[:16])
+        flow = fips.open_flow(peer_key, port=port)
+        jwe = self.seal(message, to_pubkey, anonymous)
+        raw = json.dumps(jwe, separators=(',', ':'), sort_keys=True).encode('utf-8')
+        # Fragments to the flow's max_payload; raises rather than silently
+        # dropping an oversize datagram, so the ladder cascades.
+        fips.send_message(flow, raw, flags=fips_transport.FLAG_DIDCOMM)
+        return {self.name: (True, 'delivered via fips native flow to %s:%d' % (peer_key, port))}
+
+    def health(self) -> Optional[Mapping[str, Any]]:
+        fips = self.router.fips
+        if fips is None:
+            return None
+        return {
+            'available': fips.is_available(),
+            'sock_path': getattr(fips, 'sock_path', None),
+            'port': self.router.fips_port,
+            'listening': getattr(self.router, '_fips_listener_sock', None) is not None,
+            'flows_count': len(getattr(fips, 'open_flows', {})),
+            'listeners_count': len(getattr(fips, 'listeners', {})),
+            'success_count': self.router.success_counts['fips-native'],
+        }
+
+
+class IrohRung(Rung):
+    """EXPERIMENTAL. A direct stream the wire itself neither encrypts nor
+    authenticates; only the JWE inside does. Built only when configured."""
+
+    name = 'iroh'
+    rank = 10
+
+    def __init__(self, router: Any) -> None:
+        self.router = router
+
+    def available(self) -> bool:
+        return self.router.iroh is not None
+
+    def target_of(self, desc: Optional[Mapping[str, Any]], theirs: Mapping[str, int]) -> Optional[str]:
+        _, where = endpoints_of(desc)
+        # Without a ticket there is nothing to dial, whatever the preference says.
+        return where.get('iroh') or None
+
+    def deliver(self, message: Mapping[str, Any], to_pubkey: str, target: str, anonymous: bool) -> Verdict:
+        res: Verdict = self.router.iroh.send(message, to_pubkey, ticket=target, anonymous=anonymous)
+        return res
+
+    def health(self) -> Optional[Mapping[str, Any]]:
+        iroh = self.router.iroh
+        return None if iroh is None else dict(iroh.health)
+
+    def fault_log(self) -> Optional[FaultLog]:
+        return _log_of(self.router.iroh)
+
+
+class Libp2pRung(Rung):
+    """A stream through the p2p sidecar; the target is derived from the
+    descriptor's transport key, so the dial is bound to what it signed."""
+
+    name = 'libp2p'
+    rank = 20
+
+    def __init__(self, router: Any, seal: Seal) -> None:
+        self.router = router
+        self.seal = seal
+
+    def available(self) -> bool:
+        p2p = self.router.p2p
+        return p2p is not None and bool(getattr(p2p, 'connected', False))
+
+    def target_of(self, desc: Optional[Mapping[str, Any]], theirs: Mapping[str, int]) -> Optional[str]:
+        if 'libp2p' not in theirs:
+            return None
+        from ..planes.transport.p2p import compartment as p2p_wire
+        target, why = p2p_wire.target_of(desc)
+        # An advertised but unusable endpoint is still an attempt the ladder
+        # should record as this rung's failure, not skip in silence.
+        return target if target is not None else 'unusable: %s' % why
+
+    def deliver(self, message: Mapping[str, Any], to_pubkey: str, target: str, anonymous: bool) -> Verdict:
+        if target.startswith('unusable: '):
+            raise TransportError('libp2p endpoint ' + target)
+        their_agree = self.router.peers.agreement(to_pubkey)
+        if their_agree is None:
+            raise TransportError('no live agreement key for peer %s' % to_pubkey[:16])
+        jwe = self.seal(message, to_pubkey, anonymous)
+        sent, note = self.router.p2p.send_direct(target, jwe)
+        if not sent:
+            raise TransportError(note or 'libp2p stream not acknowledged')
+        return {self.name: (True, note)}
+
+    def health(self) -> Optional[Mapping[str, Any]]:
+        p2p = self.router.p2p
+        return None if p2p is None else RungHealth(available=self.available())
+
+
+class RelayRungAdapter(Rung):
+    """The floor of the ladder: gift-wraps over the relays. Reaches every
+    peer, so it never says no; the relay rung itself reports which relays
+    took the wrap."""
+
+    name = 'nostr'
+    rank = 100
+
+    def __init__(self, router: Any) -> None:
+        self.router = router
+
+    def available(self) -> bool:
+        return True
+
+    def target_of(self, desc: Optional[Mapping[str, Any]], theirs: Mapping[str, int]) -> Optional[str]:
+        return ''
+
+    def deliver(self, message: Mapping[str, Any], to_pubkey: str, target: str, anonymous: bool) -> Verdict:
+        res: Verdict = self.router.nostr.send(message, to_pubkey, anonymous=anonymous, stored=False)
+        return res
+
+    def health(self) -> Optional[Mapping[str, Any]]:
+        return dict(self.router.nostr.health)
+
+    def fault_log(self) -> Optional[FaultLog]:
+        return _log_of(self.router.nostr)
+
+
+__all__ = ['FipsRung', 'IrohRung', 'Jwe', 'Libp2pRung', 'RelayRungAdapter', 'RungHealth', 'RungProtocol', 'Seal',
+           'Verdict', 'endpoints_of']

node/transport/ssb_rung.py

@@ -0,0 +1,166 @@
+"""Secure Scuttlebutt (SSB) transport ladder rung for TransportRouter.
+
+Integrates SSB peer-to-peer delivery into the Fleetmesh transport ladder:
+- Checks sidecar availability over local Unix domain socket.
+- Resolves peer SSB endpoints from node descriptors (scheme 'ssb').
+- Delivers messages to remote SSB peers via SHS BoxStream.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Mapping, Optional
+
+from node.transport.const import TransportError
+from node.transport.ladder import FaultLog
+from node.transport.rung import Rung, Verdict, endpoints_of
+from sidecar.fleetmesh_ssb import SSBSidecarClient
+
+log = logging.getLogger('ssb_rung')
+
+__all__ = [
+    'SSBRung',
+]
+
+
+class SSBRung(Rung):
+    """Transport rung delegating outbound deliveries to the SSB sidecar daemon."""
+
+    name: str = 'ssb'
+    rank: int = 25  # P2P tier between libp2p and relay
+
+    def __init__(
+        self,
+        router: Optional[Any] = None,
+        sidecar_client: Optional[SSBSidecarClient] = None,
+        socket_path: Optional[str] = None,
+        clock: Optional[Callable[[], int]] = None,
+    ):
+        self.router = router
+        self._client = sidecar_client
+        self._socket_path = socket_path
+        clk = clock or (getattr(router, 'clock', None) if router else None)
+        self._faults = FaultLog('ssb', clock=clk)
+
+    @property
+    def faults(self) -> FaultLog:
+        return self._faults
+
+    def fault_log(self) -> Optional[FaultLog]:
+        return self._faults
+
+    def _get_client(self) -> Optional[SSBSidecarClient]:
+        if self._client is not None:
+            return self._client
+        sock_path = self._socket_path
+        if sock_path is None and self.router is not None:
+            node_dir = getattr(self.router, 'dir', None) or getattr(self.router, 'node_dir', None)
+            if node_dir:
+                import os
+                sock_path = os.path.join(node_dir, 'ssb.sock')
+        if sock_path:
+            self._client = SSBSidecarClient(sock_path)
+        return self._client
+
+    def available(self) -> bool:
+        """Returns True if the SSB sidecar socket is reachable and healthy."""
+        client = self._get_client()
+        if client is None:
+            return False
+        try:
+            st = client.status()
+            return bool(st.get('ok'))
+        except Exception:
+            return False
+
+    def target_of(self, desc: Optional[Mapping[str, Any]], theirs: Mapping[str, int]) -> Optional[str]:
+        """Extract SSB endpoint target from descriptor."""
+        if desc is None:
+            return None
+        _, where = endpoints_of(desc)
+        if 'ssb' in where:
+            return where['ssb']
+
+        # Check raw tags
+        for t in desc.get('tags', []):
+            if len(t) > 2 and t[0] in ('endpoint', 'address') and t[1] == 'ssb':
+                return t[2]
+            if len(t) > 2 and t[0] == 'ssb':
+                return t[1]
+        return None
+
+    def deliver(
+        self,
+        message: Mapping[str, Any],
+        to_pubkey: str,
+        target: str,
+        anonymous: bool = False,
+    ) -> Verdict:
+        """Attempt delivery of message to target SSB endpoint."""
+        client = self._get_client()
+        if client is None:
+            self._faults.record('ssb-client-unavailable', ident=to_pubkey)
+            raise TransportError('SSB sidecar client not configured')
+
+        # Parse target format (e.g. "net:192.168.1.100:8008~shs:@pubkey.ed25519" or "host:port:feed_id")
+        host = "127.0.0.1"
+        port = 8008
+        feed_id = target
+
+        if '~shs:' in target:
+            addr_part, shs_part = target.split('~shs:', 1)
+            feed_id = shs_part
+            if addr_part.startswith('net:'):
+                addr_part = addr_part[4:]
+            parts = addr_part.split(':')
+            if len(parts) >= 2:
+                host = parts[0]
+                port = int(parts[1])
+        elif ':' in target:
+            parts = target.split(':')
+            if len(parts) == 3:
+                host, port_str, feed_id = parts
+                port = int(port_str)
+
+        try:
+            # 1. Connect / dial peer if not connected
+            dial_res = client.dial(host=host, port=port, feed_id=feed_id)
+            if not dial_res.get('ok') and dial_res.get('error') != 'already connected':
+                err_msg = dial_res.get('error', 'unknown dial failure')
+                self._faults.record(f'dial-failed: {err_msg}', ident=to_pubkey)
+                raise TransportError(f"SSB dial failed: {err_msg}")
+
+            # 2. Publish message payload
+            post_res = client.post({
+                "type": "fleetmesh-transport",
+                "recipient": to_pubkey,
+                "payload": dict(message),
+                "anonymous": anonymous,
+            })
+
+            if not post_res.get('ok'):
+                err_msg = post_res.get('error', 'unknown post failure')
+                self._faults.record(f'post-failed: {err_msg}', ident=to_pubkey)
+                raise TransportError(f"SSB post failed: {err_msg}")
+
+            return {self.name: (True, 'delivered via ssb sidecar')}
+
+        except Exception as e:
+            if not isinstance(e, TransportError):
+                self._faults.record(str(e), ident=to_pubkey)
+                raise TransportError(f"SSB delivery error: {e}") from e
+            raise
+
+    def health(self) -> Optional[Mapping[str, Any]]:
+        client = self._get_client()
+        if client is None:
+            return {"available": False, "status": "no_client"}
+        try:
+            st = client.status()
+            return {
+                "available": bool(st.get("ok")),
+                "feed_id": st.get("feed_id"),
+                "peers_connected": st.get("peers_connected", 0),
+                "messages_count": st.get("messages_count", 0),
+            }
+        except Exception as e:
+            return {"available": False, "error": str(e)}