Source code for fleetmesh_node.sidecar.fleetmesh_ssb

#!/usr/bin/env python3
"""Secure Scuttlebutt (SSB) Sidecar Daemon.

    fleetmesh-ssb DIR [--port N] [--host ADDR] [--socket PATH] [--network-key HEX]

Runs the Secure Scuttlebutt peer-to-peer transport daemon in a decoupled process:
- Listens on TCP (default port 8008) for inbound SSB peers.
- Binds 127.0.0.1 by default; pass `--host 0.0.0.0` (or set
  FLEETMESH_SSB_BIND_HOST) to accept peers from other hosts.
- Performs 4-phase Secret Handshake (SHS) mutual authentication.
- Wraps connections in 34-byte Box Stream duplex encryption.
- Multiplexes MuxRPC procedure calls (createHistoryStream, whoami, blobs).
- Communicates with meshnode over local Unix domain socket (ssb.sock) using
  newline-delimited JSON IPC protocol `fleetmesh-ssb/1`.
"""
from __future__ import annotations

import argparse
import base64
import hashlib
import json
import logging
import os
import signal
import socket
import sys
import threading
import time
from typing import Any, Mapping, MutableMapping, Optional, Sequence

_ROOT = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), '..'))
_CORE = os.path.abspath(os.path.join(_ROOT, '..', 'core'))
if _ROOT not in sys.path:
    sys.path.insert(0, _ROOT)
if _CORE not in sys.path:
    sys.path.insert(0, _CORE)

from cryptography.hazmat.primitives.asymmetric import ed25519

from fleetmesh_core.crypto.ssb import (
    BOX_STREAM_HEADER_LENGTH,
    SSB_MAINNET_NETWORK_KEY,
    BoxStreamDecryptor,
    BoxStreamEncryptor,
    SHSClient,
    SHSServer,
    format_ssb_feed_id,
    parse_ssb_feed_id,
)
from fleetmesh_node.protocols.ssb.muxrpc import (
    MuxRPCMessage,
    MuxRPCRouter,
    build_response,
    build_stream_end,
)

log = logging.getLogger('fleetmesh-ssb')

PROTOCOL_VERSION = "fleetmesh-ssb/1"
DEFAULT_PORT = 8008
# Loopback by default: the SSB TCP listener is reachable by anyone who can
# route to the host, and an alpha node should not expose a p2p port just
# because its config has an `ssb` block. Public binding is an explicit choice:
# `--host 0.0.0.0` (or FLEETMESH_SSB_BIND_HOST=0.0.0.0).
DEFAULT_BIND_HOST = "127.0.0.1"
BIND_HOST_ENV = "FLEETMESH_SSB_BIND_HOST"


[docs]class SSBSidecarClient: """IPC client used by meshnode compartments to communicate with the SSB daemon."""
[docs] def __init__(self, socket_path: str, timeout: float = 10.0): self.socket_path = socket_path self.timeout = timeout self._sock: Optional[socket.socket] = None self._lock = threading.RLock()
[docs] def connect(self) -> None: with self._lock: if self._sock is not None: return s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) s.settimeout(self.timeout) s.connect(self.socket_path) self._sock = s
[docs] def close(self) -> None: with self._lock: if self._sock: try: self._sock.close() except Exception: pass self._sock = None
[docs] def send_command(self, cmd: Mapping[str, Any]) -> Mapping[str, Any]: """Send a command dictionary and receive response.""" with self._lock: if self._sock is None: self.connect() assert self._sock is not None payload = json.dumps(cmd).encode('utf-8') + b'\n' self._sock.sendall(payload) # Read response line buf = bytearray() while b'\n' not in buf: chunk = self._sock.recv(4096) if not chunk: raise ConnectionResetError("SSB daemon closed IPC connection") buf.extend(chunk) line = bytes(buf.split(b'\n', 1)[0]) return json.loads(line.decode('utf-8'))
[docs] def status(self) -> Mapping[str, Any]: return self.send_command({"cmd": "status"})
[docs] def post(self, content: Mapping[str, Any]) -> Mapping[str, Any]: return self.send_command({"cmd": "post", "content": content})
[docs] def dial(self, host: str, port: int, feed_id: str) -> Mapping[str, Any]: return self.send_command({"cmd": "dial", "host": host, "port": port, "feed_id": feed_id})
[docs]class SSBSidecarDaemon: """The Secure Scuttlebutt TCP listener, Box Stream router, and IPC daemon."""
[docs] def __init__( self, node_dir: str, tcp_port: int = DEFAULT_PORT, bind_host: str = DEFAULT_BIND_HOST, uds_path: Optional[str] = None, network_key: bytes = SSB_MAINNET_NETWORK_KEY, secret_key_bytes: Optional[bytes] = None, ): self.node_dir = node_dir self.tcp_port = tcp_port self.bind_host = bind_host self.uds_path = uds_path or os.path.join(node_dir, "ssb.sock") self.network_key = network_key # Key setup if secret_key_bytes: self.priv_key = ed25519.Ed25519PrivateKey.from_private_bytes(secret_key_bytes) else: self.priv_key = self._load_or_create_key() self.sk_bytes = self.priv_key.private_bytes_raw() self.pk_bytes = self.priv_key.public_key().public_bytes_raw() self.feed_id = format_ssb_feed_id(self.pk_bytes) # MuxRPC Router self.router = MuxRPCRouter(local_feed_id=self.feed_id) self._register_rpc_methods() # State self._running = False self._tcp_sock: Optional[socket.socket] = None self._uds_sock: Optional[socket.socket] = None self._threads: list[threading.Thread] = [] self._ipc_clients: list[socket.socket] = [] self._ipc_subscribers: set[socket.socket] = set() self._peers: MutableMapping[str, Any] = {} self._lock = threading.RLock() # Local feed store (in-memory for demo / extensible to sqlite) self._messages: list[Mapping[str, Any]] = []
def _load_or_create_key(self) -> ed25519.Ed25519PrivateKey: """Load ed25519 key from keys.json or generate new one.""" keys_file = os.path.join(self.node_dir, "keys.json") if os.path.exists(keys_file): try: with open(keys_file, "r", encoding="utf-8") as f: data = json.load(f) seed_hex = data.get("transport_seed") or data.get("ed25519_seed") if seed_hex: seed = bytes.fromhex(seed_hex)[:32] return ed25519.Ed25519PrivateKey.from_private_bytes(seed) except Exception as e: log.warning("failed to load key from %s: %s", keys_file, e) return ed25519.Ed25519PrivateKey.generate() def _register_rpc_methods(self) -> None: """Register Scuttlebutt standard MuxRPC procedures.""" def _handle_create_history_stream(req_id: int, args: list[Any], rpc_type: str) -> list[MuxRPCMessage]: target_feed = None if args and isinstance(args[0], dict): target_feed = args[0].get("id") with self._lock: matching = [ m for m in self._messages if not target_feed or m.get("author") == target_feed ] out = [] for msg_doc in matching: out.append(build_response(req_id, msg_doc, is_stream=True)) out.append(build_stream_end(req_id)) return out self.router.register("createHistoryStream", _handle_create_history_stream)
[docs] def start(self) -> None: """Start TCP listener and IPC Unix domain socket listener.""" self._running = True # 1. Bind IPC UDS socket if os.path.exists(self.uds_path): try: os.unlink(self.uds_path) except Exception: pass os.makedirs(os.path.dirname(os.path.abspath(self.uds_path)), exist_ok=True) self._uds_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) self._uds_sock.bind(self.uds_path) self._uds_sock.listen(16) self._uds_sock.settimeout(1.0) # 2. Bind TCP server socket self._tcp_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self._tcp_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) self._tcp_sock.bind((self.bind_host, self.tcp_port)) # Update tcp_port if port 0 was passed self.tcp_port = self._tcp_sock.getsockname()[1] self._tcp_sock.listen(32) self._tcp_sock.settimeout(1.0) # Launch accept threads t_ipc = threading.Thread(target=self._ipc_accept_loop, daemon=True, name="ssb-ipc-accept") t_tcp = threading.Thread(target=self._tcp_accept_loop, daemon=True, name="ssb-tcp-accept") t_ipc.start() t_tcp.start() self._threads.extend([t_ipc, t_tcp]) log.info("SSB sidecar started. Feed: %s, TCP: %s:%d, IPC: %s", self.feed_id, self.bind_host, self.tcp_port, self.uds_path)
[docs] def stop(self) -> None: """Stop daemon and close sockets.""" self._running = False with self._lock: if self._tcp_sock: try: self._tcp_sock.close() except Exception: pass if self._uds_sock: try: self._uds_sock.close() except Exception: pass if os.path.exists(self.uds_path): try: os.unlink(self.uds_path) except Exception: pass for t in self._threads: t.join(timeout=1.0)
# ------------------------------------------------------------------------- # IPC Loop (Unix Domain Socket) # ------------------------------------------------------------------------- def _ipc_accept_loop(self) -> None: while self._running: try: assert self._uds_sock is not None conn, _ = self._uds_sock.accept() t = threading.Thread(target=self._handle_ipc_client, args=(conn,), daemon=True) t.start() except (socket.timeout, OSError): continue def _handle_ipc_client(self, conn: socket.socket) -> None: with self._lock: self._ipc_clients.append(conn) buf = bytearray() try: while self._running: chunk = conn.recv(4096) if not chunk: break buf.extend(chunk) while b'\n' in buf: line, buf = buf.split(b'\n', 1) if not line.strip(): continue try: cmd = json.loads(line.decode('utf-8')) resp = self._dispatch_ipc_command(conn, cmd) except Exception as e: resp = {"ok": False, "error": str(e)} conn.sendall(json.dumps(resp).encode('utf-8') + b'\n') except Exception: pass finally: with self._lock: if conn in self._ipc_clients: self._ipc_clients.remove(conn) self._ipc_subscribers.discard(conn) try: conn.close() except Exception: pass def _dispatch_ipc_command(self, conn: socket.socket, cmd: Mapping[str, Any]) -> Mapping[str, Any]: action = cmd.get("cmd") if action == "status": return { "ok": True, "protocol": PROTOCOL_VERSION, "feed_id": self.feed_id, "port": self.tcp_port, "peers_connected": len(self._peers), "messages_count": len(self._messages), } elif action == "subscribe": with self._lock: self._ipc_subscribers.add(conn) return {"ok": True, "status": "subscribed"} elif action == "post": content = cmd.get("content", {}) msg = self.publish_post(content) return {"ok": True, "message": msg} elif action == "dial": host = cmd.get("host", "127.0.0.1") port = int(cmd.get("port", DEFAULT_PORT)) remote_feed_id = cmd.get("feed_id", "") success, err = self.dial_peer(host, port, remote_feed_id) if success: return {"ok": True, "status": "connected"} return {"ok": False, "error": err} return {"ok": False, "error": f"unknown command '{action}'"} # ------------------------------------------------------------------------- # TCP Accept Loop & Peer Connections # ------------------------------------------------------------------------- def _tcp_accept_loop(self) -> None: while self._running: try: assert self._tcp_sock is not None conn, addr = self._tcp_sock.accept() t = threading.Thread(target=self._handle_inbound_peer, args=(conn, addr), daemon=True) t.start() except (socket.timeout, OSError): continue def _handle_inbound_peer(self, sock: socket.socket, addr: tuple[str, int]) -> None: """Handle incoming TCP connection from a remote SSB peer.""" sock.settimeout(15.0) try: # 1. SHS Handshake (as Server) server = SHSServer(self.sk_bytes, network_key=self.network_key) # Phase 1: Client Hello msg1 = self._recv_exact(sock, 64) server.verify_client_hello(msg1) # Phase 2: Server Hello msg2 = server.create_server_hello() sock.sendall(msg2) # Phase 3: Client Authenticate msg3 = self._recv_exact(sock, 112) remote_pk = server.verify_client_authenticate(msg3) remote_feed = format_ssb_feed_id(remote_pk) # Phase 4: Server Accept msg4 = server.create_server_accept() sock.sendall(msg4) # Box Stream session keys enc_k, enc_n, dec_k, dec_n = server.get_box_stream_keys() enc = BoxStreamEncryptor(enc_k, enc_n) dec = BoxStreamDecryptor(dec_k, dec_n) with self._lock: self._peers[remote_feed] = {"addr": addr, "sock": sock} log.info("Inbound SSB peer handshake authenticated: %s from %s", remote_feed, addr) # Multiplex MuxRPC over BoxStream self._muxrpc_loop(sock, enc, dec, remote_feed) except Exception as e: log.debug("SSB inbound peer session terminated: %s", e) finally: try: sock.close() except Exception: pass
[docs] def dial_peer(self, host: str, port: int, remote_feed_id: str) -> tuple[bool, str]: """Dial a remote peer, execute SHS, and start MuxRPC loop.""" try: remote_pk = parse_ssb_feed_id(remote_feed_id) except Exception as e: return False, f"invalid feed ID: {e}" sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.settimeout(15.0) try: sock.connect((host, port)) client = SHSClient(self.sk_bytes, server_ed25519_pk=remote_pk, network_key=self.network_key) # Phase 1: Client Hello msg1 = client.create_client_hello() sock.sendall(msg1) # Phase 2: Server Hello msg2 = self._recv_exact(sock, 64) client.verify_server_hello(msg2) # Phase 3: Client Authenticate msg3 = client.create_client_authenticate() sock.sendall(msg3) # Phase 4: Server Accept msg4 = self._recv_exact(sock, 80) client.verify_server_accept(msg4) # Box Stream session keys enc_k, enc_n, dec_k, dec_n = client.get_box_stream_keys() enc = BoxStreamEncryptor(enc_k, enc_n) dec = BoxStreamDecryptor(dec_k, dec_n) with self._lock: self._peers[remote_feed_id] = {"addr": (host, port), "sock": sock} t = threading.Thread( target=self._muxrpc_loop, args=(sock, enc, dec, remote_feed_id), daemon=True, ) t.start() return True, "" except Exception as e: try: sock.close() except Exception: pass return False, str(e)
def _muxrpc_loop( self, sock: socket.socket, enc: BoxStreamEncryptor, dec: BoxStreamDecryptor, remote_feed_id: str, ) -> None: """Read and write MuxRPC packets over decrypted Box Stream.""" muxrpc_buf = bytearray() try: while self._running: # Read 34-byte Box Stream header hdr_bytes = self._recv_exact(sock, BOX_STREAM_HEADER_LENGTH) length, tag = dec.decrypt_header(hdr_bytes) if length is None or tag is None: # Stream goodbye received break body_ciphertext = self._recv_exact(sock, length) payload_plaintext = dec.decrypt_body(tag, body_ciphertext) muxrpc_buf.extend(payload_plaintext) # Parse any complete MuxRPC messages while muxrpc_buf: rpc_msg, consumed = MuxRPCMessage.from_bytes(bytes(muxrpc_buf)) if rpc_msg is None: break muxrpc_buf = muxrpc_buf[consumed:] # Dispatch request and send responses if rpc_msg.req > 0: responses = self.router.handle_request(rpc_msg) for r in responses: pkt = enc.encrypt_packet(r.encode()) sock.sendall(pkt) except Exception as e: log.debug("MuxRPC loop ended for %s: %s", remote_feed_id, e) finally: with self._lock: self._peers.pop(remote_feed_id, None) try: sock.sendall(enc.encrypt_goodbye()) except Exception: pass try: sock.close() except Exception: pass def _recv_exact(self, sock: socket.socket, num_bytes: int) -> bytes: buf = bytearray() while len(buf) < num_bytes and self._running: chunk = sock.recv(num_bytes - len(buf)) if not chunk: raise ConnectionResetError("Socket closed prematurely") buf.extend(chunk) return bytes(buf)
[docs] def publish_post(self, content: Mapping[str, Any]) -> Mapping[str, Any]: """Create and sign a new post message on the local feed.""" with self._lock: seq = len(self._messages) + 1 prev = self._messages[-1].get("key") if self._messages else None now_ms = int(time.time() * 1000) msg_value = { "previous": prev, "author": self.feed_id, "sequence": seq, "timestamp": now_ms, "hash": "sha256", "content": dict(content), } canonical = json.dumps(msg_value, sort_keys=True, separators=(',', ':')).encode('utf-8') sig = self.priv_key.sign(canonical) sig_b64 = base64.b64encode(sig).decode('ascii') + ".sig.ed25519" msg_value["signature"] = sig_b64 msg_hash = hashlib.sha256(canonical).digest() msg_key = f"%{base64.b64encode(msg_hash).decode('ascii')}.sha256" record = { "key": msg_key, "value": msg_value, "timestamp": now_ms, } self._messages.append(record) # Notify IPC listeners self._notify_ipc({ "event": "message", "feed_id": self.feed_id, "sequence": seq, "message": record, }) return record
def _notify_ipc(self, event_doc: Mapping[str, Any]) -> None: payload = json.dumps(event_doc).encode('utf-8') + b'\n' with self._lock: dead = [] for client in self._ipc_subscribers: try: client.sendall(payload) except Exception: dead.append(client) for d in dead: self._ipc_subscribers.discard(d)
[docs]def main(argv: Optional[Sequence[str]] = None) -> int: parser = argparse.ArgumentParser(description="Fleetmesh Secure Scuttlebutt Sidecar Daemon") parser.add_argument("dir", help="Node state directory containing keys.json") parser.add_argument("--port", type=int, default=DEFAULT_PORT, help=f"TCP listen port (default {DEFAULT_PORT})") parser.add_argument("--host", default=os.environ.get(BIND_HOST_ENV, DEFAULT_BIND_HOST), help=f"TCP bind address (default {DEFAULT_BIND_HOST}; 0.0.0.0 is the " f"explicit public opt-in, or set {BIND_HOST_ENV})") parser.add_argument("--socket", help="Path to Unix domain socket") parser.add_argument("--network-key", help="Hex encoded 32-byte network capability key") args = parser.parse_args(argv) logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s") net_key = bytes.fromhex(args.network_key) if args.network_key else SSB_MAINNET_NETWORK_KEY daemon = SSBSidecarDaemon( node_dir=args.dir, tcp_port=args.port, bind_host=args.host, uds_path=args.socket, network_key=net_key, ) def _sig_handler(sig, frame): log.info("Received termination signal %s, shutting down...", sig) daemon.stop() sys.exit(0) signal.signal(signal.SIGINT, _sig_handler) signal.signal(signal.SIGTERM, _sig_handler) daemon.start() try: while daemon._running: time.sleep(1.0) except KeyboardInterrupt: daemon.stop() return 0
if __name__ == '__main__': sys.exit(main())