Source code for fleetmesh_node.transport.fips_rung.core

"""FIPS Native Datagram API Transport Client for Fleetmesh.

Spec reference: docs/fips-native-transport.md.
Connects to the FIPS v0.5.1 native API socket (/var/run/fips/api.sock, ~/.fips/api.sock, ...),
requests FSP service flows and listener descriptors via SCM_RIGHTS, and exchanges binary-framed
datagrams addressed to peer npub identities without requiring TUN/IPv6 adapters or root privileges.
"""
from __future__ import annotations

import array
import errno
import json
import os
import socket
import struct
import threading
import time
from typing import Any, Mapping, MutableMapping, Optional, Union

from .types import FipsArrivalInfo

# Protocol Framing Constants (docs/fips-native-transport.md section 6)
FRAMING_MAGIC: int = 0x4D  # 'M'
FRAMING_VERSION: int = 0x01
FRAME_MAGIC: bytes = bytes([FRAMING_MAGIC, FRAMING_VERSION])
HEADER_FORMAT: str = '!BBHBBH'
HEADER_SIZE: int = struct.calcsize(HEADER_FORMAT)  # 8 bytes

FLAG_FINAL: int = 0x01
FLAG_COMPRESSED: int = 0x02
FLAG_DIDCOMM: int = 0x04
FLAG_ACK_REQUESTED: int = 0x08

# Where a FIPS daemon may be found when the operator did not say. Every path
# here is one only root or this user can create: /var/run and /run are
# root-owned, ~/.fips is ours. /tmp/fips/api.sock used to be on this list and
# is not any more, because any local user can create /tmp/fips first, and a
# node that then connected to it would hand its flows - and, until the
# envelope became mandatory on this rung, its peers' plaintext - to whoever
# squatted the name. An operator with a daemon in /tmp names it explicitly.
DEFAULT_SOCKET_PATHS: tuple[str, ...] = (
    "/var/run/fips/api.sock",
    "/run/fips/api.sock",
    os.path.expanduser("~/.fips/api.sock"),
    "/var/run/fips/control.sock",
    os.path.expanduser("~/.fips/control.sock"),
)

# Standard FSP Service Ports
PORT_PEERING: int = 11801
PORT_TELEMETRY: int = 21801
PORT_ACCOUNTING: int = 30801
PORT_COMPUTE_MARKET: int = 30810
PORT_COMPUTE_STREAM: int = 30811
PORT_COMPUTE_CANCEL: int = 30812

# FIPS v0.5.1 advertises max_payload per flow (1170 over a UDP transport,
# 1362 in-process); fall back to the smaller value when a flow did not say.
DEFAULT_MAX_PAYLOAD: int = 1170
# Upper bound on frames per message; larger messages raise so the transport
# ladder can cascade to a stream-capable rung (iroh / nostr) instead.
MAX_FRAGMENTS: int = 64
REASSEMBLY_TIMEOUT_S: float = 30.0


[docs]def find_api_socket() -> Optional[str]: """Find first existing and accessible FIPS Native API socket path, or None.""" for p in DEFAULT_SOCKET_PATHS: if os.path.exists(p) and os.access(p, os.R_OK | os.W_OK): return p return None
[docs]class FipsTransportError(Exception): """Raised when FIPS control or flow operations fail."""
[docs]def encode_frame( seq: int, payload: bytes, is_final: bool = False, is_didcomm: bool = True, compressed: bool = False, ack_requested: bool = False, flags: Optional[int] = None, reserved: int = 0, ) -> bytes: """Pack payload with 8-byte binary framing header. ``reserved`` carries the message id used to reassemble fragmented messages. """ if len(payload) > 65535: raise FipsTransportError(f"payload exceeds maximum 65535 bytes ({len(payload)})") if flags is not None: computed_flags = flags if is_final: computed_flags |= FLAG_FINAL else: computed_flags = 0 if is_final: computed_flags |= FLAG_FINAL if compressed: computed_flags |= FLAG_COMPRESSED if is_didcomm: computed_flags |= FLAG_DIDCOMM if ack_requested: computed_flags |= FLAG_ACK_REQUESTED header = struct.pack( HEADER_FORMAT, FRAMING_MAGIC, FRAMING_VERSION, seq & 0xFFFF, computed_flags, reserved & 0xFF, # message id for fragment reassembly len(payload), ) return header + payload
[docs]def decode_frame_ex(data: bytes) -> tuple[int, int, int, bytes]: """Like decode_frame but also returns the message id: (seq, flags, msg_id, payload).""" seq, flags, payload = decode_frame(data) return seq, flags, data[5], payload
[docs]class Reassembler: """Rebuild messages split by FipsNativeTransport.send_message on one flow. Frames with message id 0 are legacy single-frame messages and pass through. Frames arrive in order on a FIPS flow but may be lost. A message is delivered only when fragments 0..N arrive contiguously for one message id and fragment N has FLAG_FINAL; any gap discards the partial message. """
[docs] def __init__(self, timeout_s: float = REASSEMBLY_TIMEOUT_S, max_fragments: int = MAX_FRAGMENTS, clock: Any = time.monotonic) -> None: self.timeout_s = timeout_s self.max_fragments = max_fragments self.clock = clock self._msg_id: Optional[int] = None self._parts: list[bytes] = [] self._flags: int = 0 self._started: float = 0.0 self.dropped: int = 0
def _reset(self, dropped: bool) -> None: if dropped and self._parts: self.dropped += 1 self._msg_id, self._parts, self._flags = None, [], 0
[docs] def feed(self, seq: int, flags: int, msg_id: int, payload: bytes) -> Optional[tuple[int, bytes]]: """Feed one frame; returns (flags, full_payload) when a message completes.""" if msg_id == 0: # Pre-fragmentation sender (reserved byte was always 0): one frame = one message. return flags, payload now = self.clock() if self._parts and now - self._started > self.timeout_s: self._reset(dropped=True) if seq == 0: self._reset(dropped=True) self._msg_id, self._flags, self._started = msg_id, flags, now elif msg_id != self._msg_id or seq != len(self._parts): self._reset(dropped=True) # gap, loss, or interleaving: discard return None self._parts.append(payload) if flags & FLAG_FINAL: out = (self._flags | FLAG_FINAL, b"".join(self._parts)) self._reset(dropped=False) return out if len(self._parts) >= self.max_fragments: self._reset(dropped=True) return None
[docs]def decode_frame(data: bytes) -> tuple[int, int, bytes]: """Unpack 8-byte binary framing header. Returns: (seq, flags, payload) """ if len(data) < HEADER_SIZE: raise FipsTransportError(f"frame truncated ({len(data)} < {HEADER_SIZE} bytes)") magic, ver, seq, flags, _, plen = struct.unpack(HEADER_FORMAT, data[:HEADER_SIZE]) if magic != FRAMING_MAGIC: raise FipsTransportError(f"invalid framing magic 0x{magic:02x} (expected 0x{FRAMING_MAGIC:02x})") if ver != FRAMING_VERSION: raise FipsTransportError(f"unsupported framing version {ver} (expected {FRAMING_VERSION})") payload = data[HEADER_SIZE:HEADER_SIZE + plen] if len(payload) != plen: raise FipsTransportError(f"payload length mismatch ({len(payload)} != {plen})") return seq, flags, payload
[docs]def pubkey_to_npub(pubkey: object) -> str: """Normalize a pubkey (hex, did:nostr:, or npub) to standard npub format. Takes `object` because config and CLI hand it whatever they parsed; a non-string is stringified rather than refused, as before.""" if not isinstance(pubkey, str): return str(pubkey) if pubkey.startswith("npub1"): return pubkey if pubkey.startswith("did:nostr:"): pubkey = pubkey[len("did:nostr:"):] if len(pubkey) == 64: try: from fleetmesh_core.crypto.bech32 import bech32_encode return bech32_encode("npub", bytes.fromhex(pubkey)) except Exception: pass return pubkey
[docs]class FipsNativeTransport: """Manages bilateral datagram flows over FIPS Native Control API."""
[docs] def __init__(self, sock_path: Optional[str] = None, node_pk: Optional[str] = None) -> None: self.sock_path = sock_path or self._discover_socket() self.node_pk: Optional[str] = node_pk self.ctrl_sock: Optional[socket.socket] = None self._lock: threading.Lock = threading.Lock() self.open_flows: dict[str, socket.socket] = {} self.listeners: dict[int, socket.socket] = {} # fileno -> max datagram size the daemon reported for that flow self.flow_max_payload: dict[int, int] = {} self._msg_counter: int = 0
@staticmethod def _discover_socket() -> str: for p in DEFAULT_SOCKET_PATHS: if os.path.exists(p): return p return DEFAULT_SOCKET_PATHS[0]
[docs] def is_available(self) -> bool: """Check if local FIPS control socket exists and is accessible.""" return os.path.exists(self.sock_path) and os.access(self.sock_path, os.R_OK | os.W_OK)
[docs] def connect(self) -> None: """Connect to local FIPS Unix control socket.""" if not self.is_available(): raise FipsTransportError(f"FIPS control socket not accessible at {self.sock_path}") with self._lock: if self.ctrl_sock is not None: return s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) s.connect(self.sock_path) self.ctrl_sock = s
[docs] def open_flow(self, peer_npub: str, port: int, timeout_s: float = 5.0) -> socket.socket: """Request connected FSP datagram flow descriptor from FIPS via SCM_RIGHTS.""" if self.ctrl_sock is None: self.connect() assert self.ctrl_sock is not None norm_peer = pubkey_to_npub(peer_npub) params: MutableMapping[str, Any] = { "peer": norm_peer, "remote_port": int(port), } cmd_dict: MutableMapping[str, Any] = { "command": "connect", "params": params, } if self.node_pk: norm_caller = pubkey_to_npub(self.node_pk) params["caller"] = norm_caller req = json.dumps(cmd_dict) + "\n" with self._lock: try: self.ctrl_sock.settimeout(timeout_s) self.ctrl_sock.sendall(req.encode("utf-8")) fds = array.array("i") cmsg_space = socket.CMSG_SPACE(fds.itemsize * 4) msg, ancdata, flags, addr = self.ctrl_sock.recvmsg(4096, cmsg_space) except (OSError, BrokenPipeError, ConnectionResetError) as e: try: self.ctrl_sock.close() except Exception: pass self.ctrl_sock = None raise FipsTransportError(f"FIPS control socket disconnected: {e}") if not msg and not ancdata: try: self.ctrl_sock.close() except Exception: pass self.ctrl_sock = None raise FipsTransportError("FIPS control socket closed unexpectedly (EOF)") for cmsg_level, cmsg_type, cmsg_data in ancdata: if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS: fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) if fds: raw_fd = fds[0] for extra_fd in fds[1:]: try: os.close(extra_fd) except OSError: pass try: flow_sock = socket.fromfd(raw_fd, socket.AF_UNIX, socket.SOCK_DGRAM) finally: try: os.close(raw_fd) except OSError: pass key = f"{peer_npub}:{port}" self.open_flows[key] = flow_sock self._record_max_payload(flow_sock, msg) return flow_sock resp = {} if msg: try: resp = json.loads(msg.decode("utf-8")) except Exception: pass err_msg = resp.get("message") or resp.get("error") or "no descriptor received" raise FipsTransportError(f"FIPS flow connect failed: {err_msg}")
[docs] def listen_port(self, port: int, timeout_s: float = 5.0) -> socket.socket: """Register inbound listener on FSP port, receiving descriptor via SCM_RIGHTS.""" if self.ctrl_sock is None: self.connect() assert self.ctrl_sock is not None params: MutableMapping[str, Any] = { "local_port": int(port), } cmd_dict: MutableMapping[str, Any] = { "command": "listen", "params": params, } if self.node_pk: norm_pk = pubkey_to_npub(self.node_pk) params["node_pk"] = norm_pk req = json.dumps(cmd_dict) + "\n" with self._lock: try: self.ctrl_sock.settimeout(timeout_s) self.ctrl_sock.sendall(req.encode("utf-8")) fds = array.array("i") cmsg_space = socket.CMSG_SPACE(fds.itemsize * 4) msg, ancdata, flags, addr = self.ctrl_sock.recvmsg(4096, cmsg_space) except (OSError, BrokenPipeError, ConnectionResetError) as e: try: self.ctrl_sock.close() except Exception: pass self.ctrl_sock = None raise FipsTransportError(f"FIPS control socket disconnected: {e}") if not msg and not ancdata: try: self.ctrl_sock.close() except Exception: pass self.ctrl_sock = None raise FipsTransportError("FIPS control socket closed unexpectedly (EOF)") for cmsg_level, cmsg_type, cmsg_data in ancdata: if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS: fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) if fds: raw_fd = fds[0] for extra_fd in fds[1:]: try: os.close(extra_fd) except OSError: pass try: listener_sock = socket.fromfd(raw_fd, socket.AF_UNIX, socket.SOCK_DGRAM) finally: try: os.close(raw_fd) except OSError: pass self.listeners[port] = listener_sock return listener_sock resp = {} if msg: try: resp = json.loads(msg.decode("utf-8")) except Exception: pass err_msg = resp.get("message") or resp.get("error") or "no descriptor received" raise FipsTransportError(f"FIPS listen failed: {err_msg}")
[docs] def accept_flow( self, listener_sock: socket.socket, timeout_s: Optional[float] = 5.0, ) -> tuple[socket.socket, FipsArrivalInfo]: """Accept an incoming flow on a registered listener socket. In FIPS v0.5.1, when a remote peer initiates a flow to a listening port, the listener descriptor receives an arrival notice datagram with SCM_RIGHTS carrying the new connected flow datagram socket. Returns: (flow_socket, arrival_info_dict) """ if timeout_s is not None: listener_sock.settimeout(timeout_s) fds = array.array("i") cmsg_space = socket.CMSG_SPACE(fds.itemsize * 4) msg, ancdata, flags, addr = listener_sock.recvmsg(4096, cmsg_space) flow_fd = None for cmsg_level, cmsg_type, cmsg_data in ancdata: if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS: fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) if fds: flow_fd = fds[0] for extra_fd in fds[1:]: try: os.close(extra_fd) except OSError: pass break if flow_fd is None: raise FipsTransportError("no flow descriptor received in listener arrival") try: flow_sock = socket.fromfd(flow_fd, socket.AF_UNIX, socket.SOCK_DGRAM) finally: try: os.close(flow_fd) except OSError: pass arrival_info: FipsArrivalInfo = {} if msg: try: arrival_info = json.loads(msg.decode("utf-8")) except Exception: pass peer = arrival_info.get("peer") remote_port = arrival_info.get("remote_port") if peer and remote_port: self.open_flows[f"{peer}:{remote_port}"] = flow_sock self._record_max_payload(flow_sock, arrival_info) return flow_sock, arrival_info
[docs] def accept_listener_event( self, listener_sock: socket.socket, ) -> tuple[Optional[socket.socket], Mapping[str, Any], bytes]: """Receive the next incoming event on a registered listener socket. Returns: (flow_sock, arrival_info, direct_msg) If an incoming flow arrived via SCM_RIGHTS: returns (flow_sock, arrival_info, b"") If a direct binary frame arrived: returns (None, {}, direct_msg) If empty/timeout: returns (None, {}, b"") """ fds = array.array("i") cmsg_space = socket.CMSG_SPACE(fds.itemsize * 4) msg, ancdata, flags, addr = listener_sock.recvmsg(65536, cmsg_space) if not msg and not ancdata: return None, {}, b"" flow_fd = None for cmsg_level, cmsg_type, cmsg_data in ancdata: if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS: fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) if fds: flow_fd = fds[0] for extra_fd in fds[1:]: try: os.close(extra_fd) except OSError: pass break if flow_fd is not None: try: flow_sock = socket.fromfd(flow_fd, socket.AF_UNIX, socket.SOCK_DGRAM) finally: try: os.close(flow_fd) except OSError: pass arrival_info = {} if msg: try: arrival_info = json.loads(msg.decode("utf-8")) peer = arrival_info.get("peer") rport = arrival_info.get("remote_port") if peer and rport: self.open_flows[f"{peer}:{rport}"] = flow_sock except (ValueError, UnicodeDecodeError, AttributeError): pass self._record_max_payload(flow_sock, arrival_info) return flow_sock, arrival_info, b"" return None, {}, msg
def _record_max_payload(self, flow_sock: socket.socket, reply: Any) -> None: """Remember the per-flow datagram ceiling from a connect reply or arrival.""" info: Any = reply if isinstance(reply, (bytes, bytearray)): try: info = json.loads(bytes(reply).decode("utf-8")) except Exception: info = {} if isinstance(info, dict) and isinstance(info.get("data"), dict): info = info["data"] mp = info.get("max_payload") if isinstance(info, dict) else None if isinstance(mp, int) and mp > HEADER_SIZE: try: self.flow_max_payload[flow_sock.fileno()] = mp except Exception: pass
[docs] def max_payload_for(self, flow_sock: socket.socket) -> int: """Largest datagram (header included) this flow will carry.""" try: return self.flow_max_payload.get(flow_sock.fileno(), DEFAULT_MAX_PAYLOAD) except Exception: return DEFAULT_MAX_PAYLOAD
[docs] def send_message( self, flow_sock: socket.socket, payload: bytes, flags: int = 0, max_fragments: int = MAX_FRAGMENTS, ) -> int: """Send one logical message, fragmenting it to fit the flow's max_payload. Every frame carries the same message id in the header's reserved byte and a per-message fragment index in ``seq``; the last frame sets FLAG_FINAL. Raises FipsTransportError before sending anything if the message would need more than ``max_fragments`` frames, so callers can fall back to a transport without a datagram ceiling. Returns the number of frames sent. """ raw = bytes(payload) chunk = self.max_payload_for(flow_sock) - HEADER_SIZE if chunk <= 0: raise FipsTransportError("flow max_payload too small for framing header") parts = [raw[i:i + chunk] for i in range(0, len(raw), chunk)] or [b""] if len(parts) > max_fragments: raise FipsTransportError( f"message of {len(raw)} bytes needs {len(parts)} frames " f"(limit {max_fragments} at {chunk} bytes/frame)" ) with self._lock: # ids 1..255; 0 marks a legacy/unfragmented frame self._msg_counter = self._msg_counter % 255 + 1 msg_id = self._msg_counter base = flags & ~FLAG_FINAL for idx, part in enumerate(parts): fl = base | (FLAG_FINAL if idx == len(parts) - 1 else 0) packet = encode_frame(seq=idx, payload=part, flags=fl, is_final=False, reserved=msg_id) sent = 0 for attempt in range(10): try: sent = flow_sock.send(packet) break except OSError as e: if e.errno == getattr(errno, 'ENOBUFS', 55) and attempt < 9: time.sleep(0.005 * (attempt + 1)) continue raise if sent != len(packet): raise FipsTransportError(f"short datagram write ({sent} of {len(packet)} bytes)") return len(parts)
[docs] def send_framed( self, flow_sock: socket.socket, payload: Union[bytes, str, Mapping[str, Any]], seq: int = 0, is_final: bool = False, flags: Optional[int] = None, ) -> int: """Transmit binary-framed datagram over open flow socket.""" if isinstance(payload, Mapping): raw_bytes = json.dumps(payload, sort_keys=True).encode("utf-8") is_didcomm = True elif isinstance(payload, str): raw_bytes = payload.encode("utf-8") is_didcomm = False else: raw_bytes = bytes(payload) is_didcomm = False packet = encode_frame( seq=seq, payload=raw_bytes, is_final=is_final, is_didcomm=is_didcomm, flags=flags, ) limit = self.max_payload_for(flow_sock) if len(packet) > limit: raise FipsTransportError( f"frame of {len(packet)} bytes exceeds flow max_payload {limit}; use send_message()" ) for attempt in range(10): try: return flow_sock.send(packet) except OSError as e: if e.errno == getattr(errno, 'ENOBUFS', 55) and attempt < 9: time.sleep(0.005 * (attempt + 1)) continue raise return flow_sock.send(packet)
[docs] def recv_framed( self, flow_sock: socket.socket, timeout_s: Optional[float] = 5.0, ) -> tuple[int, bool, bytes]: """Receive and decode framed datagram. Returns (seq, is_final, payload_bytes).""" if timeout_s is not None: flow_sock.settimeout(timeout_s) data = flow_sock.recv(65536) seq, flags, payload = decode_frame(data) is_final = bool(flags & FLAG_FINAL) return seq, is_final, payload
[docs] def recv_raw_frame( self, flow_sock: socket.socket, timeout_s: Optional[float] = 5.0, ) -> tuple[int, int, bytes]: """Receive and decode raw frame with exact integer bitflags. Returns (seq, flags, payload_bytes).""" if timeout_s is not None: flow_sock.settimeout(timeout_s) data = flow_sock.recv(65536) return decode_frame(data)
[docs] def close(self) -> None: """Close all open flows, listeners, and control connection.""" with self._lock: for s in self.open_flows.values(): try: s.close() except Exception: pass self.open_flows.clear() for s in self.listeners.values(): try: s.close() except Exception: pass self.listeners.clear() if self.ctrl_sock is not None: try: self.ctrl_sock.close() except Exception: pass self.ctrl_sock = None