fleetmesh-node 0.2.0__py3-none-any.whl

node/transport/didcomm_inbound.py

@@ -0,0 +1,251 @@
+"""Opening an inbound DIDComm envelope: one place, every transport.
+
+Four paths carry a JWE into this node - a gift wrap off a relay, an iroh
+stream, an iroh QUIC stream, and a FIPS native flow - and until this module
+each of them opened the envelope its own way. Three of the four were wrong in
+the same direction: they took the plaintext's `from` as the sender's name
+without anything that proved it. A frame that was never encrypted, written by
+anyone who could reach the socket, arrived as a message from whoever it named,
+and on two of the paths it arrived marked authenticated. The transport that
+got it right was the relay one, which is the oldest, and its rule is the rule
+here: the names must agree, and a name nobody proved is not a name.
+
+What proves a sender is the ECDH-1PU agreement. didcomm.decrypt only succeeds
+under authcrypt if the static key `skid` names took part in the key
+agreement, so a decrypted authcrypt message was written by the holder of that
+key. The plaintext's `from` is then required to name the same node, and on
+the relay path the seal's signer too. Anoncrypt has no skid and therefore no
+sender: the message is delivered with `authenticated=False` and its `from` is
+recorded as a claim, which is what first contact is.
+
+Anything that is not a JWE is refused. There is no plaintext path, not for
+discovery and not for ping: a transport that wants an unauthenticated
+protocol runs it beside DIDComm, not inside the queue that request() waits
+on. The reason strings are the ones node/transport/ has always recorded, so an
+operator who learned to read `dropped` reads the same words from every rung.
+
+Replay. A JWE is a fixed string of bytes, and a direct rung (fips flow, iroh
+stream, libp2p stream) carries it as-is: anyone who captured one can write
+it to the socket again, and the agreement proves exactly what it proved the
+first time - the holder of the key wrote this message, once. The relay rung
+has always deduplicated by wrap id; the direct rungs had nothing. So each
+direct rung holds an InboundGuard and hands it to open_inbound, which
+refuses a message id it has already opened and a `created_time` outside the
+skew window the schema tolerates. A message with no `created_time` is still
+accepted (the id check alone covers it); the gift-wrap rung passes no guard
+because a stored wrap is legitimately delivered days late and the wrap id
+is already its replay key.
+"""
+from __future__ import annotations
+
+import collections
+import json
+import threading
+import time
+from typing import Any, Optional
+
+from fleetmesh_core.identity import didcomm
+from fleetmesh_core.wire import schema_files
+from fleetmesh_core.wire.wire_types import DIDCommMessage
+from fleetmesh_core.identity.did import node_of_did
+
+# A DIDComm message must fit in one wrap fragment set; a transport that has
+# no smaller framing limit of its own still refuses anything past this
+# before it is parsed, so a peer cannot make json.loads build a giant object.
+MAX_ENVELOPE_BYTES: int = 16 * 1024 * 1024
+
+# How far a direct-rung message's `created_time` may sit from this node's
+# clock, either way: the schema's one tolerance for judging a peer by time,
+# read through ref like every other constant. (It used to be a path
+# computed from __file__ with a silent 300s fallback; moving this module
+# one directory down turned the window from 60s to 300s and nothing but
+# the test noticed. A constant the schema owns is not read by path.)
+FRESH_WINDOW_SECONDS: int = int(schema_files.load_constants()['grant']['max_clock_skew_seconds'])
+# How many message ids a guard remembers. Past this the oldest is forgotten,
+# which is safe because anything that old is also outside the fresh window.
+SEEN_IDS_MAX: int = 4096
+
+
+class InboundGuard:
+    """Per-rung replay and freshness state: a bounded id-LRU and a clock window.
+
+    One per transport instance (never module-level: two nodes in one
+    process must not share what they have seen). `refused` counts by reason
+    so an operator can tell a replaying peer from a drifting clock.
+    """
+
+    def __init__(self, window: int = FRESH_WINDOW_SECONDS, capacity: int = SEEN_IDS_MAX) -> None:
+        self.window: int = int(window)
+        self.capacity: int = int(capacity)
+        self._seen: collections.OrderedDict[str, None] = collections.OrderedDict()
+        self._lock = threading.Lock()
+        self.refused: collections.Counter[str] = collections.Counter()
+
+    def stale(self, created_time: Any, now: int) -> Optional[str]:
+        """None if `created_time` is absent or inside the window, else why not."""
+        if created_time is None:
+            return None
+        if isinstance(created_time, bool) or not isinstance(created_time, (int, float)):
+            self.refused['created_time'] += 1
+            return 'created_time is not a number'
+        delta = int(created_time) - int(now)
+        if abs(delta) > self.window:
+            self.refused['stale'] += 1
+            return 'stale: created_time is %ds %s this node\'s clock (window %ds)' % (
+                abs(delta), 'ahead of' if delta > 0 else 'behind', self.window)
+        return None
+
+    def first_time(self, message_id: str) -> bool:
+        """True and remembered if this id is new; False if it has been opened before."""
+        with self._lock:
+            if message_id in self._seen:
+                self._seen.move_to_end(message_id)
+                self.refused['replay'] += 1
+                return False
+            self._seen[message_id] = None
+            while len(self._seen) > self.capacity:
+                self._seen.popitem(last=False)
+        return True
+
+
+class Inbound:
+    """One delivered message: the plaintext, who sent it, and how it was sealed."""
+
+    def __init__(
+        self,
+        message: DIDCommMessage,
+        sender_pk: str,
+        authenticated: bool,
+        wrap_id: str,
+    ) -> None:
+        self.message: DIDCommMessage = message
+        self.sender: str = sender_pk
+        self.authenticated: bool = authenticated   # False for anoncrypt (first contact)
+        self.wrap_id: str = wrap_id
+
+    @property
+    def thid(self) -> Optional[str]:
+        return self.message.get('thid') or self.message.get('id')
+
+
+def foreign(payload: Any) -> str:
+    """Why a decrypted payload is not one of ours, in a few words.
+
+    A protocol that shares kind 21059 says whose message it is the same way
+    DIDComm does, in a `type`, so that is what is named when there is one and
+    it is the counted half of the reason. Nothing else about the payload is
+    reported: it decrypted under this node's key, so it may be somebody's
+    private traffic that merely arrived at the wrong daemon.
+    """
+    if isinstance(payload, dict):
+        kind = payload.get('type')
+        if isinstance(kind, str) and kind.strip():
+            return 'another protocol: %s' % kind.strip()[:80]
+        members = ', '.join(sorted(str(k)[:16] for k in list(payload)[:6]))
+        return 'payload is not a JWE: an object carrying %s' % (members or 'nothing')
+    return 'payload is not a JWE: %s' % type(payload).__name__
+
+
+def is_jwe(payload: Any) -> bool:
+    """The shape didcomm.decrypt will look at. Anything else is not tried."""
+    return isinstance(payload, dict) and 'protected' in payload and 'recipients' in payload
+
+
+def _pubkey_or_none(name: Any) -> Optional[str]:
+    """did:nostr:<pk>[#frag] -> pk, or None. Never raises: a malformed name
+    from the wire is a reason to drop, not a way to end a reader thread."""
+    if not isinstance(name, str):
+        return None
+    try:
+        return node_of_did(name)
+    except (ValueError, AttributeError):
+        return None
+
+
+def open_inbound(
+    payload: Any,
+    keystore: Any,
+    peers: Any,
+    wrap_id: str,
+    seal_pk: Optional[str] = None,
+    guard: Optional[InboundGuard] = None,
+    now: Optional[int] = None,
+) -> tuple[Optional[Inbound], Optional[str]]:
+    """Open one inbound envelope. Returns (Inbound, None) or (None, reason).
+
+    payload: the bytes off the wire, or the object a transport already parsed
+    (the relay path parses before it can tell a fragment from a whole).
+    seal_pk: on the relay path, the key that signed the seal, which every
+    other name must then equal. Transports without a seal pass None and the
+    agreement between `skid` and `from` is what is checked.
+    guard: a direct rung's InboundGuard. When given, a message id already
+    opened through it is refused as a replay, and a `created_time` outside
+    the guard's window of `now` (the rung's clock; time.time() if None) is
+    refused as stale. The relay rung passes none: its wrap id is the key.
+
+    Exactly one of the pair is None, so a caller writes
+        inbound, why = open_inbound(...)
+        if inbound is None: self._drop(why, wrap_id); return
+    and the reason it records is the same on every rung.
+    """
+    if isinstance(payload, (bytes, bytearray, memoryview)):
+        raw = bytes(payload)
+        if len(raw) > MAX_ENVELOPE_BYTES:
+            return None, 'envelope: %d bytes is larger than this node opens' % len(raw)
+        try:
+            payload = json.loads(raw.decode('utf-8'))
+        except (ValueError, UnicodeDecodeError):
+            return None, 'payload is not a JWE: not JSON'
+    if not is_jwe(payload):
+        # Named apart from malformed traffic when it can be, because on a
+        # shared kind this is somebody else's healthy protocol. On a direct
+        # transport it is somebody sending plaintext, which is refused for
+        # the reason in the module docstring: nothing about it is proven.
+        return None, foreign(payload)
+    try:
+        message, skid = didcomm.decrypt(payload, keystore.kid('agreement'), keystore.agreement_priv,
+                                        resolve_sender=peers.resolve_sender)
+    except didcomm.EnvelopeError as e:
+        return None, 'envelope: %s' % e
+    except Exception as e:      # a resolver that raised, a header of the wrong type
+        return None, 'envelope: %s: %s' % (type(e).__name__, e)
+    if (not isinstance(message, dict) or not isinstance(message.get('type'), str)
+            or not isinstance(message.get('id'), str)):
+        return None, 'plaintext is not a DIDComm message'
+    claimed = _pubkey_or_none(message.get('from', ''))
+    if claimed is None:
+        return None, 'from is not a did:nostr'
+    signer: Optional[str] = None
+    if skid is not None:
+        signer = _pubkey_or_none(skid)
+        if signer is None:
+            return None, 'skid is not a did:nostr'
+    # The names must agree. With a seal there are three; without one, the
+    # skid the agreement proved is the anchor and `from` must match it.
+    if seal_pk is not None:
+        if claimed != seal_pk:
+            return None, 'from %s does not match the seal signer %s' % (claimed[:8], seal_pk[:8])
+        if signer is not None and signer != seal_pk:
+            return None, 'skid does not match the seal signer'
+        sender = seal_pk
+    elif signer is not None:
+        if claimed != signer:
+            return None, 'from %s does not match the skid %s' % (claimed[:8], signer[:8])
+        sender = signer
+    else:
+        # Anoncrypt on a transport with no seal: nobody proved anything, so
+        # what is recorded as the sender is the claim, and it says so.
+        sender = claimed
+    raw_thid: Any = message.get('thid')
+    if raw_thid is not None and not isinstance(raw_thid, str):
+        return None, 'thid is not a string'
+    if guard is not None:
+        # Freshness first, then the id: a stale message is refused without
+        # being remembered, so a flood of old captures cannot push live ids
+        # out of the LRU.
+        why = guard.stale(message.get('created_time'), int(time.time()) if now is None else now)
+        if why is not None:
+            return None, why
+        if not guard.first_time(message['id']):
+            return None, 'replay: message %s was already opened' % message['id'][:32]
+    return Inbound(message, sender, authenticated=signer is not None, wrap_id=wrap_id), None

node/transport/dnstxt.py

@@ -0,0 +1,169 @@
+"""A minimal DNS TXT lookup, because the standard library has none.
+
+The nsite gateway binds a custom domain to a site through a TXT record at
+`_nsite.<domain>`. `socket` can resolve A/AAAA, not TXT, and pulling in a
+DNS library for one record type is not worth a dependency: this is a single
+UDP query (RFC 1035, with the RFC 1123 TCP fallback when the answer is
+truncated), to the resolvers `/etc/resolv.conf` names, following CNAMEs in
+the answer section.
+
+Returned strings are the TXT character-strings of one record joined, one
+entry per record, decoded as UTF-8 with errors replaced. The caller decides
+what a value means.
+"""
+from __future__ import annotations
+
+import os
+import random
+import socket
+import struct
+from typing import Callable, Optional, Sequence
+
+TYPE_TXT = 16
+TYPE_CNAME = 5
+CLASS_IN = 1
+MAX_LABEL = 63
+MAX_NAME = 253
+
+Resolver = Callable[[str], list[str]]
+
+
+class DnsError(Exception):
+    """The lookup could not be completed (network, malformed answer)."""
+
+
+def system_nameservers(path: str = '/etc/resolv.conf') -> list[str]:
+    out: list[str] = []
+    try:
+        with open(path, encoding='utf-8', errors='replace') as f:
+            for line in f:
+                parts = line.split()
+                if len(parts) >= 2 and parts[0] == 'nameserver':
+                    out.append(parts[1])
+    except OSError:
+        pass
+    return out or ['127.0.0.53', '1.1.1.1']
+
+
+def _encode_name(name: str) -> bytes:
+    name = name.rstrip('.')
+    if len(name) > MAX_NAME:
+        raise DnsError('name too long')
+    out = b''
+    for label in name.split('.'):
+        raw = label.encode('idna') if label else b''
+        if not raw or len(raw) > MAX_LABEL:
+            raise DnsError('bad label in %r' % name)
+        out += bytes([len(raw)]) + raw
+    return out + b'\x00'
+
+
+def _read_name(msg: bytes, off: int, depth: int = 0) -> tuple[str, int]:
+    labels: list[str] = []
+    jumped_to: Optional[int] = None
+    while True:
+        if off >= len(msg):
+            raise DnsError('truncated name')
+        ln = msg[off]
+        if ln & 0xC0 == 0xC0:
+            if depth > 8:
+                raise DnsError('pointer loop')
+            ptr = struct.unpack('!H', msg[off:off + 2])[0] & 0x3FFF
+            name, _ = _read_name(msg, ptr, depth + 1)
+            labels.append(name)
+            return '.'.join(x for x in labels if x), (jumped_to if jumped_to is not None else off + 2)
+        off += 1
+        if ln == 0:
+            return '.'.join(labels), off
+        labels.append(msg[off:off + ln].decode('ascii', errors='replace'))
+        off += ln
+
+
+def _query(name: str, server: str, timeout: float, tcp: bool = False) -> bytes:
+    qid = random.randrange(0, 1 << 16)
+    header = struct.pack('!HHHHHH', qid, 0x0100, 1, 0, 0, 0)       # RD set
+    q = header + _encode_name(name) + struct.pack('!HH', TYPE_TXT, CLASS_IN)
+    fam = socket.AF_INET6 if ':' in server else socket.AF_INET
+    if tcp:
+        with socket.socket(fam, socket.SOCK_STREAM) as s:
+            s.settimeout(timeout)
+            s.connect((server, 53))
+            s.sendall(struct.pack('!H', len(q)) + q)
+            ln = s.recv(2)
+            if len(ln) < 2:
+                raise DnsError('short tcp answer')
+            want = struct.unpack('!H', ln)[0]
+            buf = b''
+            while len(buf) < want:
+                chunk = s.recv(want - len(buf))
+                if not chunk:
+                    break
+                buf += chunk
+            resp = buf
+    else:
+        with socket.socket(fam, socket.SOCK_DGRAM) as s:
+            s.settimeout(timeout)
+            s.sendto(q, (server, 53))
+            resp, _ = s.recvfrom(4096)
+    if len(resp) < 12 or struct.unpack('!H', resp[:2])[0] != qid:
+        raise DnsError('answer id mismatch')
+    return resp
+
+
+def _parse_txt(resp: bytes, name: str) -> list[str]:
+    _, flags, qd, an, _, _ = struct.unpack('!HHHHHH', resp[:12])
+    rcode = flags & 0xF
+    if rcode == 3:
+        return []                              # NXDOMAIN: no such name, not an error
+    if rcode != 0:
+        raise DnsError('rcode %d' % rcode)
+    if flags & 0x0200:
+        raise _Truncated()
+    off = 12
+    for _ in range(qd):
+        _, off = _read_name(resp, off)
+        off += 4
+    wanted = {name.rstrip('.').lower()}
+    out: list[str] = []
+    for _ in range(an):
+        rname, off = _read_name(resp, off)
+        rtype, _, _, rdlen = struct.unpack('!HHIH', resp[off:off + 10])
+        off += 10
+        rdata = resp[off:off + rdlen]
+        off += rdlen
+        if rname.lower() not in wanted:
+            continue
+        if rtype == TYPE_CNAME:
+            target, _ = _read_name(resp, off - rdlen)
+            wanted.add(target.lower())
+        elif rtype == TYPE_TXT:
+            i, parts = 0, []
+            while i < len(rdata):
+                ln = rdata[i]
+                parts.append(rdata[i + 1:i + 1 + ln])
+                i += 1 + ln
+            out.append(b''.join(parts).decode('utf-8', errors='replace'))
+    return out
+
+
+class _Truncated(Exception):
+    pass
+
+
+def lookup_txt(name: str, servers: Optional[Sequence[str]] = None, timeout: float = 3.0) -> list[str]:
+    """TXT records at `name`. Empty list = the name has none (incl. NXDOMAIN).
+    Raises DnsError when no resolver answered usably."""
+    servers = list(servers) if servers else system_nameservers()
+    if os.environ.get('FLEETMESH_DNS_SERVERS'):
+        servers = os.environ['FLEETMESH_DNS_SERVERS'].split(',')
+    last: Optional[Exception] = None
+    for server in servers:
+        try:
+            try:
+                return _parse_txt(_query(name, server, timeout), name)
+            except _Truncated:
+                return _parse_txt(_query(name, server, timeout, tcp=True), name)
+        except (OSError, DnsError, struct.error) as e:
+            last = e
+            continue
+    raise DnsError('no resolver answered for %s: %s' % (name, last))

node/transport/fips_rung/__init__.py

@@ -0,0 +1,67 @@
+"""FIPS Native Datagram API transport rung package.
+
+Exports the client, framing codecs, reassembly engine, and listener mixin.
+"""
+from __future__ import annotations
+
+from .types import FipsArrivalInfo
+from .core import (
+    DEFAULT_MAX_PAYLOAD,
+    DEFAULT_SOCKET_PATHS,
+    FLAG_ACK_REQUESTED,
+    FLAG_COMPRESSED,
+    FLAG_DIDCOMM,
+    FLAG_FINAL,
+    FRAME_MAGIC,
+    FRAMING_MAGIC,
+    FRAMING_VERSION,
+    HEADER_FORMAT,
+    HEADER_SIZE,
+    MAX_FRAGMENTS,
+    PORT_ACCOUNTING,
+    PORT_COMPUTE_CANCEL,
+    PORT_COMPUTE_MARKET,
+    PORT_COMPUTE_STREAM,
+    PORT_PEERING,
+    PORT_TELEMETRY,
+    REASSEMBLY_TIMEOUT_S,
+    FipsNativeTransport,
+    FipsTransportError,
+    Reassembler,
+    decode_frame,
+    decode_frame_ex,
+    encode_frame,
+    find_api_socket,
+)
+from .listener import FipsRungMixin
+
+__all__ = [
+    'FipsArrivalInfo',
+    'FipsNativeTransport',
+    'FipsRungMixin',
+    'FipsTransportError',
+    'Reassembler',
+    'encode_frame',
+    'decode_frame',
+    'decode_frame_ex',
+    'find_api_socket',
+    'FLAG_FINAL',
+    'FLAG_COMPRESSED',
+    'FLAG_DIDCOMM',
+    'FLAG_ACK_REQUESTED',
+    'FRAMING_MAGIC',
+    'FRAMING_VERSION',
+    'FRAME_MAGIC',
+    'HEADER_FORMAT',
+    'HEADER_SIZE',
+    'PORT_PEERING',
+    'PORT_TELEMETRY',
+    'PORT_ACCOUNTING',
+    'PORT_COMPUTE_MARKET',
+    'PORT_COMPUTE_STREAM',
+    'PORT_COMPUTE_CANCEL',
+    'DEFAULT_SOCKET_PATHS',
+    'DEFAULT_MAX_PAYLOAD',
+    'MAX_FRAGMENTS',
+    'REASSEMBLY_TIMEOUT_S',
+]