fleetmesh-node 0.2.0__py3-none-any.whl

node/transport/iroh_rung/quic.py

@@ -0,0 +1,942 @@
+"""Experimental QUIC-shaped framing over UDP for the iroh rung. Not encrypted.
+
+What this module is: a pure-stdlib framing layer that borrows QUIC's wire
+shapes (RFC 9000 variable-length integers, long and short headers, STREAM /
+ACK / PING / CONNECTION_CLOSE frames, per-stream offset reassembly, a
+STUN-style reflexive probe for NAT pinholes) so that several DIDComm
+messages can be in flight on one UDP 4-tuple without head-of-line blocking.
+
+What it is not: QUIC. There is no TLS 1.3 handshake, no packet protection,
+no header protection, no connection-ID authentication. Every byte on the
+wire is readable and forgeable by anyone on the path, and a datagram
+claiming a connection ID is believed. The module used to describe itself as
+a real QUIC transport; that was not true and the words are corrected here
+because a reader deciding what this rung protects must not be misled.
+
+Confidentiality and authenticity come from one place only: the DIDComm JWE
+carried inside each stream. The receiving side opens every completed stream
+with didcomm_inbound.open_inbound, which refuses plaintext and binds the
+sender's name to the ECDH-1PU skid, so a forged datagram can at worst waste
+a stream, never speak as a peer. Anything this layer offers beyond that -
+ordering, reassembly, the probe - is best-effort plumbing, and it is bounded
+(MAX_CONNECTIONS, MAX_STREAM_BYTES, MAX_CHUNKS_PER_STREAM, MAX_STREAMS_PER_CONN)
+because an unauthenticated UDP listener's only defence against a flood is
+to refuse to remember too much of it.
+"""
+from __future__ import annotations
+
+import collections
+import json
+import logging
+import os
+import queue
+import socket
+import struct
+import threading
+import time
+from typing import (
+    Any,
+    Callable,
+    Counter,
+    Deque,
+    Mapping,
+    Optional,
+    Union,
+)
+
+from fleetmesh_core.identity.did import did_nostr
+from fleetmesh_core.identity import didcomm
+from .. import didcomm_inbound
+from .. import const as transport_const
+from ..const import Inbound, TransportError
+from fleetmesh_core.identity.iroh_ticket import ALPN, IrohTicket
+
+log = logging.getLogger(__name__)
+
+# QUIC Packet Header Types
+PACKET_TYPE_INITIAL: int = 0x00
+PACKET_TYPE_0RTT: int = 0x01
+PACKET_TYPE_HANDSHAKE: int = 0x02
+PACKET_TYPE_RETRY: int = 0x03
+
+# QUIC Version (1 = RFC 9000, 0x49524f48 = IROH)
+QUIC_VERSION_1: int = 0x00000001
+IROH_ALPN: str = ALPN
+
+# QUIC Frame Types
+FRAME_PADDING: int = 0x00
+FRAME_PING: int = 0x01
+FRAME_ACK: int = 0x02
+FRAME_RESET_STREAM: int = 0x04
+FRAME_STREAM: int = 0x08  # 0x08..0x0f
+FRAME_CONNECTION_CLOSE: int = 0x1c
+FRAME_PROBE_REQ: int = 0x50   # Fleetmesh P2P NAT Probe Request
+FRAME_PROBE_RESP: int = 0x51  # Fleetmesh P2P NAT Probe Response
+
+# Stream Frame Flags
+STREAM_FLAG_OFF: int = 0x04
+STREAM_FLAG_LEN: int = 0x02
+STREAM_FLAG_FIN: int = 0x01
+
+MAX_DATAGRAM_SIZE: int = 1472  # Standard Ethernet MTU minus IP/UDP headers
+
+# Bounds on what an unauthenticated UDP listener will remember. A stream
+# carries one DIDComm envelope, so a stream larger than the envelope cap is
+# not a message; chunks are counted as well because a sender can fill the
+# byte budget with one-byte pieces at distinct offsets and the dict of
+# offsets is what grows. Connections are evicted oldest-idle-first when the
+# table is full, because a single host on the path can mint as many
+# connection IDs as it has packets.
+MAX_CONNECTIONS: int = 256
+MAX_STREAMS_PER_CONN: int = 64
+MAX_STREAM_BYTES: int = didcomm_inbound.MAX_ENVELOPE_BYTES
+MAX_CHUNKS_PER_STREAM: int = 4096
+
+
+# ---------------------------------------------------------------------------
+# QUIC Variable-Length Integer Encoding (RFC 9000 Section 16)
+# ---------------------------------------------------------------------------
+
+def encode_varint(v: int) -> bytes:
+    """Encode an integer into QUIC variable-length format (1, 2, 4, or 8 bytes)."""
+    if v < 0:
+        raise ValueError(f"QUIC varint cannot be negative: {v}")
+    if v < 64:
+        return bytes([v])
+    elif v < 16384:
+        return struct.pack('>H', 0x4000 | v)
+    elif v < 1073741824:
+        return struct.pack('>I', 0x80000000 | v)
+    elif v < (1 << 62):
+        return struct.pack('>Q', 0xc000000000000000 | v)
+    raise ValueError(f"QUIC varint value out of range: {v}")
+
+
+def decode_varint(data: bytes, offset: int = 0) -> tuple[int, int]:
+    """Decode QUIC variable-length integer. Returns (value, next_offset)."""
+    if offset >= len(data):
+        raise ValueError("truncated varint buffer")
+    first = data[offset]
+    prefix = first >> 6
+    if prefix == 0:
+        return first & 0x3f, offset + 1
+    elif prefix == 1:
+        if offset + 2 > len(data):
+            raise ValueError("truncated 2-byte varint")
+        val = struct.unpack('>H', data[offset:offset + 2])[0] & 0x3fff
+        return val, offset + 2
+    elif prefix == 2:
+        if offset + 4 > len(data):
+            raise ValueError("truncated 4-byte varint")
+        val = struct.unpack('>I', data[offset:offset + 4])[0] & 0x3fffffff
+        return val, offset + 4
+    else:
+        if offset + 8 > len(data):
+            raise ValueError("truncated 8-byte varint")
+        val = struct.unpack('>Q', data[offset:offset + 8])[0] & 0x3fffffffffffffff
+        return val, offset + 8
+
+
+# ---------------------------------------------------------------------------
+# QUIC Frame Structures
+# ---------------------------------------------------------------------------
+
+class StreamFrame:
+    """QUIC STREAM Frame (RFC 9000 Section 19.8)."""
+
+    def __init__(
+        self,
+        stream_id: int,
+        offset: int = 0,
+        data: bytes = b'',
+        fin: bool = False,
+    ) -> None:
+        self.stream_id: int = stream_id
+        self.offset: int = offset
+        self.data: bytes = data
+        self.fin: bool = fin
+
+    def encode(self) -> bytes:
+        flags = 0x08
+        if self.offset > 0:
+            flags |= STREAM_FLAG_OFF
+        flags |= STREAM_FLAG_LEN
+        if self.fin:
+            flags |= STREAM_FLAG_FIN
+
+        out = [bytes([flags]), encode_varint(self.stream_id)]
+        if self.offset > 0:
+            out.append(encode_varint(self.offset))
+        out.append(encode_varint(len(self.data)))
+        out.append(self.data)
+        return b''.join(out)
+
+    @classmethod
+    def decode(cls, data: bytes, offset: int) -> tuple[StreamFrame, int]:
+        first = data[offset]
+        flags = first
+        offset += 1
+
+        stream_id, offset = decode_varint(data, offset)
+        stream_offset = 0
+        if flags & STREAM_FLAG_OFF:
+            stream_offset, offset = decode_varint(data, offset)
+
+        if flags & STREAM_FLAG_LEN:
+            length, offset = decode_varint(data, offset)
+        else:
+            length = len(data) - offset
+
+        chunk = data[offset:offset + length]
+        offset += length
+        fin = bool(flags & STREAM_FLAG_FIN)
+        return cls(stream_id=stream_id, offset=stream_offset, data=chunk, fin=fin), offset
+
+
+class AckFrame:
+    """QUIC ACK Frame (RFC 9000 Section 19.3)."""
+
+    def __init__(self, largest_ack: int, ack_delay_ms: int = 0) -> None:
+        self.largest_ack: int = largest_ack
+        self.ack_delay_ms: int = ack_delay_ms
+
+    def encode(self) -> bytes:
+        return b''.join([
+            bytes([FRAME_ACK]),
+            encode_varint(self.largest_ack),
+            encode_varint(self.ack_delay_ms),
+            encode_varint(0),  # ACK range count
+            encode_varint(0),  # First ACK range
+        ])
+
+    @classmethod
+    def decode(cls, data: bytes, offset: int) -> tuple[AckFrame, int]:
+        offset += 1  # Skip frame type byte
+        largest_ack, offset = decode_varint(data, offset)
+        ack_delay, offset = decode_varint(data, offset)
+        range_count, offset = decode_varint(data, offset)
+        first_range, offset = decode_varint(data, offset)
+        for _ in range(range_count):
+            _, offset = decode_varint(data, offset)
+            _, offset = decode_varint(data, offset)
+        return cls(largest_ack=largest_ack, ack_delay_ms=ack_delay), offset
+
+
+class ConnectionCloseFrame:
+    """QUIC CONNECTION_CLOSE Frame (RFC 9000 Section 19.19)."""
+
+    def __init__(self, error_code: int = 0, reason: str = '') -> None:
+        self.error_code: int = error_code
+        self.reason: str = reason
+
+    def encode(self) -> bytes:
+        reason_bytes = self.reason.encode('utf-8')
+        return b''.join([
+            bytes([FRAME_CONNECTION_CLOSE]),
+            encode_varint(self.error_code),
+            encode_varint(0),  # frame type
+            encode_varint(len(reason_bytes)),
+            reason_bytes,
+        ])
+
+    @classmethod
+    def decode(cls, data: bytes, offset: int) -> tuple[ConnectionCloseFrame, int]:
+        offset += 1
+        code, offset = decode_varint(data, offset)
+        _, offset = decode_varint(data, offset)
+        rlen, offset = decode_varint(data, offset)
+        reason = data[offset:offset + rlen].decode('utf-8', errors='replace')
+        return cls(error_code=code, reason=reason), offset + rlen
+
+
+# ---------------------------------------------------------------------------
+# QUIC Packet Serialization (Long and Short Headers)
+# ---------------------------------------------------------------------------
+
+class QuicPacket:
+    """QUIC Packet representation (Long Header for handshake, Short Header for 1-RTT data)."""
+
+    def __init__(
+        self,
+        is_long_header: bool,
+        dcid: bytes,
+        packet_number: int,
+        scid: Optional[bytes] = None,
+        packet_type: int = PACKET_TYPE_INITIAL,
+        version: int = QUIC_VERSION_1,
+        payload: bytes = b'',
+    ) -> None:
+        self.is_long_header: bool = is_long_header
+        self.dcid: bytes = dcid
+        self.scid: bytes = scid or b''
+        self.packet_number: int = packet_number
+        self.packet_type: int = packet_type
+        self.version: int = version
+        self.payload: bytes = payload
+
+    def encode(self) -> bytes:
+        pn_bytes = struct.pack('>I', self.packet_number)
+        if self.is_long_header:
+            # Long Header: Form=1 (0x80), Fixed=1 (0x40), Type (2 bits), PN len (2 bits: 3 = 4 bytes)
+            first_byte = 0xc0 | (self.packet_type << 4) | 0x03
+            header = struct.pack('>B I B', first_byte, self.version, len(self.dcid))
+            header += self.dcid
+            header += bytes([len(self.scid)]) + self.scid
+            # Token length = 0 for normal packets
+            header += encode_varint(0)
+            # Length = len(pn_bytes) + len(self.payload)
+            header += encode_varint(len(pn_bytes) + len(self.payload))
+            return header + pn_bytes + self.payload
+        else:
+            # Short Header: Form=0 (0x00), Fixed=1 (0x40), Key Phase=0, PN len=3 (4 bytes)
+            first_byte = 0x43
+            header = bytes([first_byte]) + self.dcid + pn_bytes
+            return header + self.payload
+
+    @classmethod
+    def decode(cls, data: bytes) -> QuicPacket:
+        if len(data) < 2:
+            raise ValueError("datagram too short for QUIC header")
+        first = data[0]
+        is_long = bool(first & 0x80)
+
+        if is_long:
+            if len(data) < 7:
+                raise ValueError("datagram too short for QUIC long header")
+            ptype = (first >> 4) & 0x03
+            version = struct.unpack('>I', data[1:5])[0]
+            dcil = data[5]
+            offset = 6
+            if offset + dcil > len(data):
+                raise ValueError("truncated destination CID in long header")
+            dcid = data[offset:offset + dcil]
+            offset += dcil
+
+            if offset >= len(data):
+                raise ValueError("missing source CID length in long header")
+            scil = data[offset]
+            offset += 1
+            if offset + scil > len(data):
+                raise ValueError("truncated source CID in long header")
+            scid = data[offset:offset + scil]
+            offset += scil
+
+            token_len, offset = decode_varint(data, offset)
+            offset += token_len
+
+            length, offset = decode_varint(data, offset)
+            if offset + 4 > len(data):
+                raise ValueError("truncated packet number in long header")
+            pn = struct.unpack('>I', data[offset:offset + 4])[0]
+            offset += 4
+            payload = data[offset:offset + (length - 4)]
+            return cls(
+                is_long_header=True,
+                dcid=dcid,
+                scid=scid,
+                packet_number=pn,
+                packet_type=ptype,
+                version=version,
+                payload=payload,
+            )
+        else:
+            # Short header: 1-byte flag, 8-byte DCID, 4-byte PN
+            if len(data) < 13:
+                raise ValueError("datagram too short for QUIC short header")
+            dcid = data[1:9]
+            pn = struct.unpack('>I', data[9:13])[0]
+            payload = data[13:]
+            return cls(
+                is_long_header=False,
+                dcid=dcid,
+                packet_number=pn,
+                payload=payload,
+            )
+
+
+# ---------------------------------------------------------------------------
+# Multiplexed Stream State
+# ---------------------------------------------------------------------------
+
+class StreamRefused(Exception):
+    """A stream grew past what one message may be; it is abandoned."""
+
+
+class QuicStream:
+    """A multiplexed unidirectional or bidirectional stream on a QUIC connection."""
+
+    def __init__(self, stream_id: int, on_complete: Optional[Callable[[int, bytes], None]] = None) -> None:
+        self.stream_id: int = stream_id
+        self.on_complete: Optional[Callable[[int, bytes], None]] = on_complete
+        self.chunks: dict[int, bytes] = {}  # offset -> data
+        self.received_bytes: int = 0
+        self.fin_received: bool = False
+        self.final_offset: Optional[int] = None
+        self.completed: bool = False
+        self.refused: bool = False
+        self.send_offset: int = 0
+        self._lock: threading.Lock = threading.Lock()
+
+    def receive_chunk(self, offset: int, data: bytes, fin: bool) -> None:
+        with self._lock:
+            if self.completed or self.refused:
+                return
+            if data:
+                # Bound before storing: the offset alone can name a byte
+                # position past any message, and the byte count is the sum
+                # of what has actually been kept, so neither a far offset
+                # nor a flood of tiny pieces gets to grow the dict.
+                if offset + len(data) > MAX_STREAM_BYTES or self.received_bytes + len(data) > MAX_STREAM_BYTES:
+                    self.refused = True
+                    self.chunks.clear()
+                    raise StreamRefused('stream %d exceeds %d bytes' % (self.stream_id, MAX_STREAM_BYTES))
+                if offset not in self.chunks and len(self.chunks) >= MAX_CHUNKS_PER_STREAM:
+                    self.refused = True
+                    self.chunks.clear()
+                    raise StreamRefused('stream %d exceeds %d chunks' % (self.stream_id, MAX_CHUNKS_PER_STREAM))
+                self.received_bytes += len(data)
+                self.chunks[offset] = data
+            if fin:
+                self.fin_received = True
+                self.final_offset = offset + len(data)
+
+            if self.fin_received and not self.completed:
+                target_len = self.final_offset if self.final_offset is not None else 0
+                if target_len == 0:
+                    self.completed = True
+                    if self.on_complete:
+                        self.on_complete(self.stream_id, b'')
+                    return
+
+                # Assemble contiguous chunks starting from 0
+                assembled = bytearray()
+                curr = 0
+                sorted_offsets = sorted(self.chunks.keys())
+                for off in sorted_offsets:
+                    if off == curr:
+                        chunk = self.chunks[off]
+                        assembled.extend(chunk)
+                        curr += len(chunk)
+                    elif off < curr:
+                        overlap = curr - off
+                        if overlap < len(self.chunks[off]):
+                            chunk = self.chunks[off][overlap:]
+                            assembled.extend(chunk)
+                            curr += len(chunk)
+
+                if curr >= target_len:
+                    self.completed = True
+                    payload = bytes(assembled[:target_len])
+                    if self.on_complete:
+                        self.on_complete(self.stream_id, payload)
+
+
+# ---------------------------------------------------------------------------
+# QUIC Connection State Machine
+# ---------------------------------------------------------------------------
+
+class QuicConnection:
+    """Manages state for one peer-to-peer QUIC connection."""
+
+    def __init__(
+        self,
+        local_cid: bytes,
+        remote_cid: bytes,
+        remote_addr: tuple[str, int],
+        is_server: bool = False,
+        on_stream_complete: Optional[Callable[[QuicConnection, int, bytes], None]] = None,
+    ) -> None:
+        self.local_cid: bytes = local_cid
+        self.remote_cid: bytes = remote_cid
+        self.remote_addr: tuple[str, int] = remote_addr
+        self.is_server: bool = is_server
+        self.on_stream_complete: Optional[Callable[[QuicConnection, int, bytes], None]] = on_stream_complete
+        self.state: str = 'INITIAL' if not is_server else 'ESTABLISHED'
+
+        self.next_packet_number: int = 0
+        self.largest_received_pn: int = -1
+        self.rtt_estimate_ms: float = 20.0
+        self.last_sent_at: float = 0.0
+        self.last_received_at: float = time.time()
+
+        self.streams: dict[int, QuicStream] = {}
+        self.next_stream_id: int = 0 if not is_server else 1
+        self._lock: threading.Lock = threading.Lock()
+
+        # Completed streams queue
+        self.incoming_messages: queue.Queue[bytes] = queue.Queue(maxsize=1000)
+
+    def next_pn(self) -> int:
+        with self._lock:
+            pn = self.next_packet_number
+            self.next_packet_number += 1
+            return pn
+
+    def get_or_create_stream(self, stream_id: int) -> QuicStream:
+        with self._lock:
+            if stream_id not in self.streams:
+                # Completed streams are dropped as new ones open, so the
+                # cap counts streams still being assembled, not history.
+                if len(self.streams) >= MAX_STREAMS_PER_CONN:
+                    for sid in [k for k, v in self.streams.items() if v.completed or v.refused]:
+                        del self.streams[sid]
+                if len(self.streams) >= MAX_STREAMS_PER_CONN:
+                    raise StreamRefused('connection has %d open streams' % MAX_STREAMS_PER_CONN)
+                s = QuicStream(stream_id, on_complete=self._on_stream_complete)
+                self.streams[stream_id] = s
+            return self.streams[stream_id]
+
+    def _on_stream_complete(self, stream_id: int, data: bytes) -> None:
+        try:
+            self.incoming_messages.put_nowait(data)
+        except queue.Full:
+            # Bounded (1000) per connection; a blocking put here would stall
+            # the engine's receive loop on one slow consumer. The engine's
+            # raw_inbox is the delivery path anyway; this queue is a mirror.
+            log.warning('iroh_live: per-connection inbox full, stream %d not mirrored', stream_id)
+        if self.on_stream_complete:
+            try:
+                self.on_stream_complete(self, stream_id, data)
+            except Exception:
+                # The callback is the engine's (or a test's); a fault in it
+                # must not kill the UDP receive loop that called us, but it
+                # is a bug and gets logged, not hidden.
+                log.exception('iroh_live: on_stream_complete callback failed for stream %d', stream_id)
+
+
+# ---------------------------------------------------------------------------
+# Live Iroh P2P QUIC Transport Engine
+# ---------------------------------------------------------------------------
+
+class IrohLiveEngine:
+    """High-performance UDP-based QUIC P2P streaming engine for Fleetmesh.
+
+    Zero external dependencies: uses Python standard library socket.SOCK_DGRAM.
+    """
+
+    def __init__(
+        self,
+        node_id: str,
+        host: str = '127.0.0.1',
+        port: int = 0,
+        alpn: str = IROH_ALPN,
+        timeout: float = 5.0,
+    ) -> None:
+        self.node_id: str = node_id.lower()
+        self.host: str = host
+        self.port: int = port
+        self.alpn: str = alpn
+        self.timeout: float = timeout
+
+        self.sock: Optional[socket.socket] = None
+        self._rx_thread: Optional[threading.Thread] = None
+        self._running: bool = False
+
+        self.connections: dict[bytes, QuicConnection] = {}         # CID -> QuicConnection
+        self.addr_to_conn: dict[tuple[str, int], QuicConnection] = {}  # (host, port) -> QuicConnection
+        self._lock: threading.Lock = threading.Lock()
+
+        # Telemetry & Performance counters
+        self.packets_in: int = 0
+        self.packets_out: int = 0
+        self.bytes_in: int = 0
+        self.bytes_out: int = 0
+        self.streams_in: int = 0
+        self.streams_out: int = 0
+        self.dropped: Deque[tuple[str, Optional[str]]] = collections.deque(maxlen=200)
+        # Replay and freshness for streams this engine opens itself
+        # (receive_didcomm). Wall clock, as send_didcomm dates with.
+        self.guard: didcomm_inbound.InboundGuard = didcomm_inbound.InboundGuard()
+        self.anonymous_refused: int = 0
+        self.evicted: int = 0
+        self.drop_counts: Counter[str] = collections.Counter()
+        self.probe_responses: dict[str, tuple[str, int]] = {}  # nonce -> (reflexive_ip, reflexive_port)
+
+        # Inbound queues for multiplexed streams and unpacked DIDComm events
+        self.raw_inbox: queue.Queue[tuple[QuicConnection, int, bytes]] = queue.Queue(maxsize=10000)
+        self.inbox: queue.Queue[Inbound] = queue.Queue(maxsize=10000)
+
+    @property
+    def endpoint(self) -> str:
+        return f"{self.host}:{self.port}"
+
+    @property
+    def ticket(self) -> str:
+        return IrohTicket(self.node_id, self.host, self.port).encode()
+
+    def start(self) -> IrohLiveEngine:
+        """Bind UDP socket on host:port and launch background async receiver thread."""
+        if self.sock is not None:
+            return self
+
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((self.host, self.port))
+        self.port = s.getsockname()[1]
+        s.settimeout(0.5)
+        self.sock = s
+
+        self._running = True
+        self._rx_thread = threading.Thread(target=self._rx_loop, daemon=True, name=f"iroh-quic-{self.port}")
+        self._rx_thread.start()
+        return self
+
+    def stop(self) -> None:
+        """Gracefully stop engine and close UDP socket."""
+        self._running = False
+        if self.sock:
+            try:
+                self.sock.close()
+            except OSError:
+                pass  # best-effort close; the socket may already be gone
+            self.sock = None
+        if self._rx_thread and self._rx_thread.is_alive():
+            self._rx_thread.join(timeout=1.0)
+
+    def _evict_idle_locked(self) -> None:
+        """Forget the connection idle longest. Called with self._lock held."""
+        by_addr = list(self.addr_to_conn.items())
+        if not by_addr:
+            return
+        addr, victim = min(by_addr, key=lambda kv: kv[1].last_received_at)
+        self.addr_to_conn.pop(addr, None)
+        for cid in [k for k, v in self.connections.items() if v is victim]:
+            del self.connections[cid]
+        self.evicted += 1
+
+    def _drop(self, reason: str, ident: Optional[str] = None) -> None:
+        prefix = reason.split(':', 1)[0].strip()
+        self.drop_counts[prefix] += 1
+        self.dropped.append((reason, ident))
+
+    def _on_conn_stream_complete(self, conn: QuicConnection, stream_id: int, data: bytes) -> None:
+        try:
+            self.raw_inbox.put_nowait((conn, stream_id, data))
+        except queue.Full:
+            # raw_inbox is bounded (10000): a full one means the consumer
+            # is not keeping up, and the stream is dropped and counted
+            # like every other drop rather than blocking the receive loop.
+            self._drop('inbox full: raw_inbox', '%s:%d' % conn.remote_addr)
+
+    # -----------------------------------------------------------------------
+    # Background Packet Receive Loop
+    # -----------------------------------------------------------------------
+
+    def _rx_loop(self) -> None:
+        while self._running and self.sock:
+            try:
+                raw_bytes, sender_addr = self.sock.recvfrom(65535)
+            except (socket.timeout, OSError):
+                continue
+
+            if not raw_bytes:
+                continue
+
+            self.packets_in += 1
+            self.bytes_in += len(raw_bytes)
+
+            try:
+                # 1. Check for NAT Probe frames
+                if raw_bytes.startswith(bytes([FRAME_PROBE_REQ])):
+                    nonce = raw_bytes[1:17].hex()
+                    resp = (
+                        bytes([FRAME_PROBE_RESP])
+                        + bytes.fromhex(nonce)
+                        + socket.inet_aton(sender_addr[0])
+                        + struct.pack('>H', sender_addr[1])
+                    )
+                    if self.sock:
+                        try:
+                            self.sock.sendto(resp, sender_addr)
+                        except OSError:
+                            pass
+                    continue
+                elif raw_bytes.startswith(bytes([FRAME_PROBE_RESP])):
+                    nonce = raw_bytes[1:17].hex()
+                    ref_ip = socket.inet_ntoa(raw_bytes[17:21])
+                    ref_port = struct.unpack('>H', raw_bytes[21:23])[0]
+                    self.probe_responses[nonce] = (ref_ip, ref_port)
+                    continue
+
+                # 2. Parse QUIC packet
+                pkt = QuicPacket.decode(raw_bytes)
+                self._handle_packet(pkt, sender_addr)
+            except Exception as e:
+                self._drop(f"bad packet: {e}", f"{sender_addr[0]}:{sender_addr[1]}")
+
+    def _handle_packet(self, pkt: QuicPacket, sender_addr: tuple[str, int]) -> None:
+        conn = None
+        with self._lock:
+            # Match by DCID or sender address
+            conn = self.connections.get(pkt.dcid) or self.addr_to_conn.get(sender_addr)
+            if conn is None and pkt.is_long_header:
+                # Inbound new connection request. When the table is full
+                # the connection that has been quiet longest goes; a peer
+                # that is still talking is never the one evicted for a
+                # stranger's first packet.
+                if len(self.addr_to_conn) >= MAX_CONNECTIONS:
+                    self._evict_idle_locked()
+                local_cid = pkt.dcid
+                remote_cid = pkt.scid or os.urandom(8)
+                conn = QuicConnection(
+                    local_cid=local_cid,
+                    remote_cid=remote_cid,
+                    remote_addr=sender_addr,
+                    is_server=True,
+                    on_stream_complete=self._on_conn_stream_complete,
+                )
+                self.connections[local_cid] = conn
+                self.connections[remote_cid] = conn
+                self.addr_to_conn[sender_addr] = conn
+
+        if conn is None:
+            return
+
+        conn.last_received_at = time.time()
+        conn.largest_received_pn = max(conn.largest_received_pn, pkt.packet_number)
+
+        # Parse frames inside payload
+        offset = 0
+        data = pkt.payload
+        while offset < len(data):
+            ftype = data[offset]
+            if ftype == FRAME_PING:
+                offset += 1
+                self._send_ack(conn)
+            elif ftype == FRAME_ACK:
+                ack, offset = AckFrame.decode(data, offset)
+            elif (ftype & 0xf8) == FRAME_STREAM:
+                sframe, offset = StreamFrame.decode(data, offset)
+                self.streams_in += 1
+                try:
+                    stream = conn.get_or_create_stream(sframe.stream_id)
+                    stream.receive_chunk(sframe.offset, sframe.data, sframe.fin)
+                except StreamRefused as e:
+                    self._drop('stream refused: %s' % e, f"{sender_addr[0]}:{sender_addr[1]}")
+                    continue
+                self._send_ack(conn)
+            elif ftype == FRAME_CONNECTION_CLOSE:
+                cclose, offset = ConnectionCloseFrame.decode(data, offset)
+                conn.state = 'CLOSED'
+            else:
+                offset += 1  # Skip unknown byte
+
+    def _send_ack(self, conn: QuicConnection) -> None:
+        if conn.largest_received_pn >= 0:
+            ack_frame = AckFrame(conn.largest_received_pn, ack_delay_ms=2)
+            pkt = QuicPacket(
+                is_long_header=False,
+                dcid=conn.remote_cid,
+                packet_number=conn.next_pn(),
+                payload=ack_frame.encode(),
+            )
+            self._send_packet(pkt, conn.remote_addr)
+
+    def _send_packet(self, pkt: QuicPacket, dest_addr: tuple[str, int]) -> None:
+        if not self.sock:
+            return
+        raw = pkt.encode()
+        try:
+            self.sock.sendto(raw, dest_addr)
+            self.packets_out += 1
+            self.bytes_out += len(raw)
+        except Exception as e:
+            self._drop(f"send failed: {e}", f"{dest_addr[0]}:{dest_addr[1]}")
+
+    # -----------------------------------------------------------------------
+    # Connection Management & Stream Dispatch
+    # -----------------------------------------------------------------------
+
+    def get_or_connect(self, ticket: Union[str, IrohTicket]) -> QuicConnection:
+        """Establish or retrieve live QUIC connection to an Iroh peer ticket."""
+        t = IrohTicket.parse(ticket) if isinstance(ticket, str) else ticket
+        remote_addr = (t.host, t.port)
+
+        with self._lock:
+            conn = self.addr_to_conn.get(remote_addr)
+            if conn and conn.state != 'CLOSED':
+                return conn
+
+        # Handshake: allocate connection IDs
+        local_cid = os.urandom(8)
+        remote_cid = os.urandom(8)
+        conn = QuicConnection(
+            local_cid=local_cid,
+            remote_cid=remote_cid,
+            remote_addr=remote_addr,
+            is_server=False,
+            on_stream_complete=self._on_conn_stream_complete,
+        )
+
+        with self._lock:
+            self.connections[local_cid] = conn
+            self.connections[remote_cid] = conn
+            self.addr_to_conn[remote_addr] = conn
+
+        # Send Initial packet with PING
+        init_pkt = QuicPacket(
+            is_long_header=True,
+            dcid=remote_cid,
+            scid=local_cid,
+            packet_number=conn.next_pn(),
+            packet_type=PACKET_TYPE_INITIAL,
+            payload=bytes([FRAME_PING]),
+        )
+        self._send_packet(init_pkt, remote_addr)
+        conn.state = 'ESTABLISHED'
+        return conn
+
+    def send_stream(self, conn: QuicConnection, data: bytes, stream_id: Optional[int] = None) -> int:
+        """Transmit payload across a new or existing multiplexed QUIC stream."""
+        sid = stream_id if stream_id is not None else conn.next_stream_id
+        if stream_id is None:
+            conn.next_stream_id += 4
+
+        # Chunk payload into MTU-safe STREAM frames
+        max_chunk = MAX_DATAGRAM_SIZE - 64
+        offset = 0
+        while offset < len(data) or len(data) == 0:
+            chunk = data[offset:offset + max_chunk]
+            offset += len(chunk)
+            fin = (offset >= len(data))
+
+            sframe = StreamFrame(stream_id=sid, offset=offset - len(chunk), data=chunk, fin=fin)
+            pkt = QuicPacket(
+                is_long_header=False,
+                dcid=conn.remote_cid,
+                packet_number=conn.next_pn(),
+                payload=sframe.encode(),
+            )
+            self._send_packet(pkt, conn.remote_addr)
+            self.streams_out += 1
+            if len(data) == 0 or offset >= len(data):
+                break
+
+        return sid
+
+    def receive_stream(self, timeout: Optional[float] = 5.0) -> Optional[tuple[QuicConnection, int, bytes]]:
+        """Fetch completed raw stream (conn, stream_id, payload) from incoming queue."""
+        try:
+            return self.raw_inbox.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def probe_nat(self, target_host: str, target_port: int, timeout: float = 1.0) -> Optional[tuple[str, int]]:
+        """Probe remote endpoint for reflexive NAT address discovery."""
+        nonce = os.urandom(16)
+        probe_req = bytes([FRAME_PROBE_REQ]) + nonce
+        if self.sock:
+            try:
+                self.sock.sendto(probe_req, (target_host, target_port))
+            except OSError:
+                return None
+
+        deadline = time.time() + timeout
+        n_hex = nonce.hex()
+        while time.time() < deadline:
+            if n_hex in self.probe_responses:
+                return self.probe_responses.pop(n_hex)
+            time.sleep(0.02)
+        return None
+
+    def punch_hole(self, target_host: str, target_port: int, count: int = 5, interval: float = 0.05) -> None:
+        """Send repeated probe bursts to open/punch NAT pinholes to a remote peer."""
+        for _ in range(count):
+            nonce = os.urandom(16)
+            probe_req = bytes([FRAME_PROBE_REQ]) + nonce
+            if self.sock:
+                try:
+                    self.sock.sendto(probe_req, (target_host, target_port))
+                except OSError:
+                    pass
+            if interval > 0:
+                time.sleep(interval)
+
+    # -----------------------------------------------------------------------
+    # High-Level DIDComm Integration
+    # -----------------------------------------------------------------------
+
+    def send_didcomm(
+        self,
+        keystore: Any,
+        peers: Any,
+        message: Mapping[str, Any],
+        to_pubkey: str,
+        ticket: Union[str, IrohTicket],
+        anonymous: bool = False,
+    ) -> tuple[bool, str]:
+        """Encrypt and dispatch a DIDComm v2 message over a QUIC stream."""
+        conn = self.get_or_connect(ticket)
+        their_agree = peers.agreement(to_pubkey) if hasattr(peers, 'agreement') else None
+        if their_agree is None:
+            raise TransportError(f"no live agreement key for peer {to_pubkey[:16]}")
+
+        msg_dict = dict(message)
+        msg_dict.setdefault('from', keystore.did)
+        recipient_did = did_nostr(to_pubkey)
+        msg_dict.setdefault('to', [recipient_did])
+        msg_dict.setdefault('created_time', int(time.time()))
+
+        kid = did_nostr(to_pubkey) + '#agree'
+        sender = None if anonymous else (keystore.kid('agreement'), keystore.agreement_priv)
+        jwe = didcomm.encrypt(msg_dict, [(kid, their_agree)], sender=sender)
+        envelope_bytes = json.dumps(jwe, separators=(',', ':'), sort_keys=True).encode('utf-8')
+
+        sid = self.send_stream(conn, envelope_bytes)
+        return True, f"delivered via iroh quic stream {sid} to {conn.remote_addr[0]}:{conn.remote_addr[1]}"
+
+    def receive_didcomm(
+        self,
+        keystore: Any,
+        peers: Any,
+        timeout: float = 5.0,
+    ) -> Optional[Inbound]:
+        """Wait for and unpack incoming DIDComm message from any active connection."""
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            rem = max(0.01, deadline - time.time())
+            try:
+                conn, stream_id, raw_bytes = self.raw_inbox.get(timeout=rem)
+            except queue.Empty:
+                break
+
+            # One rule for every rung (didcomm_inbound): a JWE this node can
+            # open, sender proven by the agreement, or a drop with a reason.
+            # The plaintext branch that used to sit here is gone; see
+            # iroh_transport._process_inbound_bytes for why.
+            inbound, why = didcomm_inbound.open_inbound(raw_bytes, keystore, peers, f"iroh-quic-{stream_id}",
+                                                        guard=self.guard, now=int(time.time()))
+            if inbound is None:
+                self._drop(f"unpack error: {why}", f"{conn.remote_addr[0]}:{conn.remote_addr[1]}")
+                continue
+            if not inbound.authenticated and not transport_const.anonymous_allowed(inbound.message.get('type')):
+                self.anonymous_refused += 1
+                self._drop('unauthenticated: anoncrypt %s is not a first-contact type'
+                           % str(inbound.message.get('type'))[:80], f"{conn.remote_addr[0]}:{conn.remote_addr[1]}")
+                continue
+            try:
+                self.inbox.put_nowait(inbound)
+            except queue.Full:
+                self._drop('inbox full')
+            return inbound
+        return None
+
+    def status(self) -> Mapping[str, Any]:
+        """Telemetry snapshot of the live Iroh QUIC engine."""
+        return {
+            'node_id': self.node_id,
+            'host': self.host,
+            'port': self.port,
+            'alpn': self.alpn,
+            'running': self._running,
+            'endpoint': self.endpoint,
+            'ticket': self.ticket,
+            'connections_count': len(self.addr_to_conn),
+            'packets_in': self.packets_in,
+            'packets_out': self.packets_out,
+            'bytes_in': self.bytes_in,
+            'bytes_out': self.bytes_out,
+            'streams_in': self.streams_in,
+            'streams_out': self.streams_out,
+            'drops': dict(self.drop_counts),
+        }