Source code for fleetmesh_node.transport.didcomm_inbound

"""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 fleetmesh_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


[docs]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. """
[docs] 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()
[docs] 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
[docs] 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
[docs]class Inbound: """One delivered message: the plaintext, who sent it, and how it was sealed."""
[docs] def __init__( self, message: DIDCommMessage, sender_pk: str, authenticated: bool, wrap_id: str, sealed: bool = False, wrap_kind: Optional[int] = None, ) -> 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 # True for control/1.0 sealed by a person's own key (plan D25): no # DIDComm envelope, and the answer must go back sealed the same way. self.sealed: bool = sealed self.wrap_kind: Optional[int] = wrap_kind # the kind it came in, so a sealed answer mirrors it
@property def thid(self) -> Optional[str]: return self.message.get('thid') or self.message.get('id')
[docs]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__
[docs]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
[docs]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