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