"""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 `fleetmesh_node/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 `fleetmesh_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 fleetmesh_node.compartment import stores as st
from fleetmesh_node.compartment import Command, Need
from fleetmesh_node.config import P2PConfig
from fleetmesh_node.config.parameter import Parameter
from fleetmesh_node.compartment.lifecycle import Lifecycle
from fleetmesh_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
[docs]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]
)
[docs]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)
[docs]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
[docs]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
[docs]class P2PError(SidecarError):
"""Raised when communication with the p2p sidecar fails."""
[docs]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
[docs]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',
),
)
[docs] 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 -----------------------------------------------------------
[docs] def endpoint(self) -> str:
return socket_path(self.dir)
[docs] def wanted(self) -> bool:
return bool(self.config('p2p', False))
[docs] def forget(self) -> None:
self.connected = False
self.peer_id = None
self.addrs = [] # not a store: cleared on forget
[docs] 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
[docs] def sections(self) -> Mapping[str, Any]:
return {
'bridge': self.bridge_state(),
'p2p': self.state(),
}
[docs] 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
[docs] 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
[docs] 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
[docs] 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]
[docs] def drain_cmd(self) -> Any:
return self.call('drain')
[docs] 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}