#!/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())