usmp 0.2.0__py3-none-any.whl

usmp/__init__.py

@@ -0,0 +1,55 @@
+# src/usmp/__init__.py
+
+from .types import USMPFrame, SessionInfo, PacketType, ErrorCode
+from .errors import (
+    USMPError,
+    FrameError,
+    CRCError,
+    MagicError,
+    VersionError,
+    PayloadError,
+    HandshakeError,
+    AuthError,
+    CryptoError,
+    SequenceError,
+    TimeoutError,
+    ConnectionClosedError,
+)
+from ._frame import encode_frame, decode_frame, read_frame, write_frame
+from ._session import USMPSession
+from ._server import USMPServer
+from ._client import USMPClient
+
+__all__ = [
+    # Types
+    "USMPFrame",
+    "SessionInfo",
+    "PacketType",
+    "ErrorCode",
+    # Errors
+    "USMPError",
+    "FrameError",
+    "CRCError",
+    "MagicError",
+    "VersionError",
+    "PayloadError",
+    "HandshakeError",
+    "AuthError",
+    "CryptoError",
+    "SequenceError",
+    "TimeoutError",
+    "ConnectionClosedError",
+    # Frame
+    "encode_frame",
+    "decode_frame",
+    "read_frame",
+    "write_frame",
+    # Session
+    "USMPSession",
+    # Server
+    "USMPServer",
+    # Client
+    "USMPClient",
+]
+
+__version__ = "0.2.0"

usmp/_client.py

@@ -0,0 +1,68 @@
+# src/usmp/_client.py
+
+import asyncio
+import os
+from ._handshake import client_handshake
+from ._session import USMPSession
+from .types import USMP_DEVICE_ID_LEN
+
+
+class USMPClient:
+    """
+    Asyncio USMP client. Used to connect to a USMP server from Python.
+    Useful for testing, CLI tools, or Python-to-Python USMP communication.
+
+    Usage:
+        client = USMPClient(host="192.168.137.1", port=9000, psk=b"your-psk")
+        await client.connect()
+        await client.send(b"hello")
+        data = await client.recv()
+        await client.disconnect()
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        psk: bytes,
+        device_id: bytes | None = None,
+    ):
+        self._host = host
+        self._port = port
+        self._psk = psk
+        self._device_id = device_id or os.urandom(USMP_DEVICE_ID_LEN)
+        self._session: USMPSession | None = None
+
+    async def connect(self) -> None:
+        """Connect to a USMP server and complete the handshake."""
+        reader, writer = await asyncio.open_connection(self._host, self._port)
+        info = await client_handshake(reader, writer, self._psk, self._device_id)
+        self._session = USMPSession(reader, writer, info)
+        print(
+            f"[USMP] Connected to {self._host}:{self._port} session={info.session_id_str}"
+        )
+
+    async def send(self, data: bytes) -> None:
+        self._ensure_connected()
+        await self._session.send(data)
+
+    async def recv(self) -> bytes:
+        self._ensure_connected()
+        return await self._session.recv()
+
+    async def ping(self) -> None:
+        self._ensure_connected()
+        await self._session.ping()
+
+    async def disconnect(self) -> None:
+        if self._session:
+            await self._session.bye()
+            self._session = None
+
+    def _ensure_connected(self) -> None:
+        if self._session is None:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session.session_id if self._session else None

usmp/_crypto.py

@@ -0,0 +1,121 @@
+# src/usmp/_crypto.py
+
+import struct
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from .types import USMP_SESSION_KEY_LEN, USMP_TAG_LEN
+from .errors import CryptoError
+
+
+def generate_keypair() -> tuple[X25519PrivateKey, bytes]:
+    """Generate an ephemeral X25519 keypair. Returns (private_key, public_key_bytes)."""
+    priv = X25519PrivateKey.generate()
+    pub = priv.public_key().public_bytes_raw()
+    return priv, pub
+
+
+def derive_session_key(
+    priv_key: X25519PrivateKey,
+    peer_pub: bytes,
+    nonce: bytes,
+    pub_c: bytes,
+    pub_s: bytes,
+) -> bytes:
+    """
+    Derive session key via X25519 + HKDF-SHA256.
+
+    session_key = HKDF-SHA256(
+        ikm  = X25519(priv, peer_pub),
+        salt = nonce,
+        info = "usmp-v1" || pub_C || pub_S,
+        len  = 32
+    )
+    """
+    peer_key = X25519PublicKey.from_public_bytes(peer_pub)
+    shared_secret = priv_key.exchange(peer_key)
+    info = b"usmp-v1" + pub_c + pub_s
+
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=USMP_SESSION_KEY_LEN,
+        salt=nonce,
+        info=info,
+    ).derive(shared_secret)
+
+
+def build_gcm_nonce(seq: int, session_id: bytes) -> bytes:
+    """Build a 12-byte GCM nonce: seq(4 LE) || session_id(4) || 0x00000000(4)."""
+    return struct.pack("<I", seq) + session_id[:4] + b"\x00" * 4
+
+
+def build_aad(
+    magic: int,
+    version: int,
+    type_: int,
+    seq: int,
+    length: int,
+) -> bytes:
+    """
+    Build AAD for AES-GCM.
+    AAD = magic(2 LE) || version(1) || type(1) || seq(4 LE) || length(2 LE)
+    Total: 10 bytes.
+    """
+    return (
+        struct.pack("<H", magic)
+        + struct.pack("<B", version)
+        + struct.pack("<B", type_)
+        + struct.pack("<I", seq)
+        + struct.pack("<H", length)
+    )
+
+
+def encrypt(
+    key: bytes,
+    seq: int,
+    session_id: bytes,
+    type_: int,
+    version: int,
+    magic: int,
+    plaintext: bytes,
+) -> bytes:
+    """
+    Encrypt plaintext with AES-256-GCM.
+    Returns ciphertext + tag (len(plaintext) + 16 bytes).
+    """
+    nonce = build_gcm_nonce(seq, session_id)
+    # AAD uses the post-encryption length (plaintext + tag)
+    enc_length = len(plaintext) + USMP_TAG_LEN
+    aad = build_aad(magic, version, type_, seq, enc_length)
+
+    aesgcm = AESGCM(key)
+    # cryptography library appends tag to ciphertext automatically
+    return aesgcm.encrypt(nonce, plaintext, aad)
+
+
+def decrypt(
+    key: bytes,
+    seq: int,
+    session_id: bytes,
+    type_: int,
+    version: int,
+    magic: int,
+    length: int,
+    ciphertext_and_tag: bytes,
+) -> bytes:
+    """
+    Decrypt and verify AES-256-GCM ciphertext+tag.
+    Raises CryptoError if authentication fails.
+    """
+    nonce = build_gcm_nonce(seq, session_id)
+    aad = build_aad(magic, version, type_, seq, length)
+
+    aesgcm = AESGCM(key)
+    try:
+        return aesgcm.decrypt(nonce, ciphertext_and_tag, aad)
+    except Exception as e:
+        raise CryptoError(f"Decryption failed: {e}") from e

usmp/_frame.py

@@ -0,0 +1,137 @@
+# src/usmp/_frame.py
+
+import struct
+from .types import (
+    USMPFrame,
+    PacketType,
+    USMP_MAGIC,
+    USMP_VERSION,
+    USMP_HEADER_SIZE,
+    USMP_MAX_PAYLOAD,
+)
+from .errors import MagicError, VersionError, PayloadError, CRCError, FrameError
+
+
+def crc16(data: bytes) -> int:
+    """CRC-16/IBM — polynomial 0xA001, initial value 0xFFFF."""
+    crc = 0xFFFF
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            if crc & 1:
+                crc = (crc >> 1) ^ 0xA001
+            else:
+                crc >>= 1
+    return crc
+
+
+def compute_frame_crc(
+    magic: int,
+    version: int,
+    type_: int,
+    seq: int,
+    length: int,
+    payload: bytes,
+) -> int:
+    """Compute CRC over header bytes [0..9] + payload."""
+    header = struct.pack("<HBBI", magic, version, type_, seq)
+    header += struct.pack("<H", length)
+    return crc16(header + payload)
+
+
+def encode_frame(
+    type_: PacketType,
+    payload: bytes,
+    seq: int = 0,
+    version: int = USMP_VERSION,
+) -> bytes:
+    """Encode a USMP frame to bytes."""
+    if len(payload) > USMP_MAX_PAYLOAD:
+        raise PayloadError(
+            f"Payload too large: {len(payload)} bytes, max {USMP_MAX_PAYLOAD}"
+        )
+
+    length = len(payload)
+    crc = compute_frame_crc(USMP_MAGIC, version, int(type_), seq, length, payload)
+
+    header = struct.pack("<HBBI", USMP_MAGIC, version, int(type_), seq)
+    header += struct.pack("<HH", length, crc)
+    return header + payload
+
+
+def decode_frame(data: bytes, verify_crc: bool = True) -> USMPFrame:
+    """Decode a USMP frame from bytes."""
+    if len(data) < USMP_HEADER_SIZE:
+        raise FrameError(f"Frame too short: {len(data)} bytes, need {USMP_HEADER_SIZE}")
+
+    magic = struct.unpack_from("<H", data, 0)[0]
+    version = data[2]
+    type_ = data[3]
+    seq = struct.unpack_from("<I", data, 4)[0]
+    length = struct.unpack_from("<H", data, 8)[0]
+    crc = struct.unpack_from("<H", data, 10)[0]
+
+    if magic != USMP_MAGIC:
+        raise MagicError(f"Bad magic: 0x{magic:04X}, expected 0x{USMP_MAGIC:04X}")
+
+    if version != USMP_VERSION:
+        raise VersionError(f"Unsupported version: {version}")
+
+    if length > USMP_MAX_PAYLOAD:
+        raise PayloadError(f"Payload too large: {length} bytes")
+
+    if len(data) < USMP_HEADER_SIZE + length:
+        raise PayloadError(
+            f"Payload truncated: have {len(data) - USMP_HEADER_SIZE}, need {length}"
+        )
+
+    payload = data[USMP_HEADER_SIZE : USMP_HEADER_SIZE + length]
+
+    if verify_crc:
+        expected_crc = compute_frame_crc(magic, version, type_, seq, length, payload)
+        if crc != expected_crc:
+            raise CRCError(
+                f"CRC mismatch: got 0x{crc:04X}, expected 0x{expected_crc:04X}"
+            )
+
+    return USMPFrame(
+        magic=magic,
+        version=version,
+        type=PacketType(type_),
+        seq=seq,
+        length=length,
+        crc=crc,
+        payload=payload,
+    )
+
+
+async def read_frame(reader, verify_crc: bool = True) -> USMPFrame:
+    """
+    Read exactly one USMP frame from an asyncio StreamReader.
+    Reads header first, then exact payload bytes — handles TCP stream fragmentation.
+    """
+    header = await reader.readexactly(USMP_HEADER_SIZE)
+
+    magic = struct.unpack_from("<H", header, 0)[0]
+    if magic != USMP_MAGIC:
+        raise MagicError(f"Bad magic: 0x{magic:04X}")
+
+    length = struct.unpack_from("<H", header, 8)[0]
+    if length > USMP_MAX_PAYLOAD:
+        raise PayloadError(f"Payload too large: {length}")
+
+    payload = await reader.readexactly(length) if length > 0 else b""
+
+    return decode_frame(header + payload, verify_crc=verify_crc)
+
+
+async def write_frame(
+    writer,
+    type_: PacketType,
+    payload: bytes,
+    seq: int = 0,
+) -> None:
+    """Write a USMP frame to an asyncio StreamWriter."""
+    data = encode_frame(type_, payload, seq)
+    writer.write(data)
+    await writer.drain()

usmp/_handshake.py

@@ -0,0 +1,158 @@
+import asyncio
+import hmac
+import hashlib
+import os
+from .types import (
+    PacketType,
+    SessionInfo,
+    USMP_NONCE_LEN,
+    USMP_DEVICE_ID_LEN,
+    USMP_PUB_KEY_LEN,
+    USMP_HMAC_LEN,
+    USMP_SESSION_ID_LEN,
+)
+from ._frame import read_frame, write_frame
+from ._crypto import generate_keypair, derive_session_key
+from .errors import HandshakeError, AuthError
+
+
+def _compute_hmac(psk: bytes, *parts: bytes) -> bytes:
+    """HMAC-SHA256(psk, part1 || part2 || ...)"""
+    data = b"".join(parts)
+    return hmac.new(psk, data, hashlib.sha256).digest()
+
+
+async def server_handshake(
+    reader,
+    writer,
+    psk: bytes,
+) -> SessionInfo:
+    """
+    Run the server side of the USMP handshake.
+    Returns SessionInfo on success, raises HandshakeError on failure.
+    """
+
+    # ── Step 1: Receive HELLO [device_id(6) || pub_C(32)] ────────────────────
+    try:
+        frame = await read_frame(reader, verify_crc=False)
+    except asyncio.IncompleteReadError as e:
+        raise HandshakeError("Connection closed before HELLO") from e
+
+    if frame.type != PacketType.HELLO:
+        raise HandshakeError(f"Expected HELLO, got {frame.type_name()}")
+
+    if frame.length != USMP_DEVICE_ID_LEN + USMP_PUB_KEY_LEN:
+        raise HandshakeError(f"Bad HELLO length: {frame.length}")
+
+    device_id = frame.payload[:USMP_DEVICE_ID_LEN]
+    pub_c = frame.payload[USMP_DEVICE_ID_LEN : USMP_DEVICE_ID_LEN + USMP_PUB_KEY_LEN]
+
+    # ── Generate server keypair ───────────────────────────────────────────────
+    priv_s, pub_s = generate_keypair()
+
+    # ── Step 2: Send CHALLENGE [nonce(32) || pub_S(32)] ──────────────────────
+    nonce = os.urandom(USMP_NONCE_LEN)
+    await write_frame(writer, PacketType.CHALLENGE, nonce + pub_s)
+
+    # ── Derive session key ────────────────────────────────────────────────────
+    session_key = derive_session_key(priv_s, pub_c, nonce, pub_c, pub_s)
+
+    # ── Step 3: Receive HELLO_ACK [hmac_client(32)] ──────────────────────────
+    try:
+        frame = await read_frame(reader, verify_crc=False)
+    except asyncio.IncompleteReadError as e:
+        raise HandshakeError("Connection closed before HELLO_ACK") from e
+
+    if frame.type != PacketType.HELLO_ACK:
+        raise HandshakeError(f"Expected HELLO_ACK, got {frame.type_name()}")
+
+    if frame.length != USMP_HMAC_LEN:
+        raise HandshakeError(f"Bad HELLO_ACK length: {frame.length}")
+
+    # ── Verify client HMAC ────────────────────────────────────────────────────
+    expected_client = _compute_hmac(psk, nonce, device_id)
+    received_client = frame.payload[:USMP_HMAC_LEN]
+
+    if not hmac.compare_digest(expected_client, received_client):
+        raise AuthError("Client HMAC verification failed")
+
+    # ── Step 4: Send SESSION_OK [session_id(4) || hmac_server(32)] ───────────
+    session_id = os.urandom(USMP_SESSION_ID_LEN)
+    hmac_server = _compute_hmac(psk, nonce, session_id)
+    await write_frame(writer, PacketType.SESSION_OK, session_id + hmac_server)
+
+    return SessionInfo(
+        device_id=device_id,
+        session_id=session_id,
+        session_key=session_key,
+    )
+
+
+async def client_handshake(
+    reader,
+    writer,
+    psk: bytes,
+    device_id: bytes,
+) -> SessionInfo:
+    """
+    Run the client side of the USMP handshake.
+    """
+
+    # ── Generate client keypair ───────────────────────────────────────────────
+    priv_c, pub_c = generate_keypair()
+
+    # ── Step 1: Send HELLO [device_id(6) || pub_C(32)] ───────────────────────
+    await write_frame(writer, PacketType.HELLO, device_id + pub_c)
+
+    # ── Step 2: Receive CHALLENGE [nonce(32) || pub_S(32)] ───────────────────
+    try:
+        frame = await read_frame(reader, verify_crc=False)
+    except asyncio.IncompleteReadError as e:
+        raise HandshakeError("Connection closed before CHALLENGE") from e
+
+    if frame.type != PacketType.CHALLENGE:
+        raise HandshakeError(f"Expected CHALLENGE, got {frame.type_name()}")
+
+    if frame.length != USMP_NONCE_LEN + USMP_PUB_KEY_LEN:
+        raise HandshakeError(f"Bad CHALLENGE length: {frame.length}")
+
+    nonce = frame.payload[:USMP_NONCE_LEN]
+    pub_s = frame.payload[USMP_NONCE_LEN : USMP_NONCE_LEN + USMP_PUB_KEY_LEN]
+
+    # ── Derive session key ────────────────────────────────────────────────────
+    session_key = derive_session_key(priv_c, pub_s, nonce, pub_c, pub_s)
+
+    # ── Step 3: Send HELLO_ACK [hmac_client(32)] ─────────────────────────────
+    hmac_client = _compute_hmac(psk, nonce, device_id)
+    await write_frame(writer, PacketType.HELLO_ACK, hmac_client)
+
+    # ── Step 4: Receive SESSION_OK [session_id(4) || hmac_server(32)] ────────
+    try:
+        frame = await read_frame(reader, verify_crc=False)
+    except asyncio.IncompleteReadError as e:
+        raise HandshakeError(
+            "Connection closed by server — PSK rejected or server error"
+        ) from e
+
+    if frame.type != PacketType.SESSION_OK:
+        raise HandshakeError(f"Expected SESSION_OK, got {frame.type_name()}")
+
+    expected_len = USMP_SESSION_ID_LEN + USMP_HMAC_LEN
+    if frame.length != expected_len:
+        raise HandshakeError(f"Bad SESSION_OK length: {frame.length}")
+
+    session_id = frame.payload[:USMP_SESSION_ID_LEN]
+    hmac_server = frame.payload[
+        USMP_SESSION_ID_LEN : USMP_SESSION_ID_LEN + USMP_HMAC_LEN
+    ]
+
+    # ── Verify server HMAC ────────────────────────────────────────────────────
+    expected_server = _compute_hmac(psk, nonce, session_id)
+    if not hmac.compare_digest(expected_server, hmac_server):
+        raise AuthError("Server HMAC verification failed — possible rogue server")
+
+    return SessionInfo(
+        device_id=device_id,
+        session_id=session_id,
+        session_key=session_key,
+    )

usmp/_server.py

@@ -0,0 +1,174 @@
+# src/usmp/_server.py
+
+import asyncio
+import logging
+import time
+from typing import Callable, Awaitable
+from ._handshake import server_handshake
+from ._session import USMPSession
+from .errors import HandshakeError, USMPError
+
+logger = logging.getLogger("usmp")
+
+
+class USMPServer:
+    """
+    Asyncio USMP server. Accepts multiple concurrent device connections.
+
+    Usage:
+        server = USMPServer(
+            host="0.0.0.0",
+            port=9000,
+            psk=b"your-psk",
+            session_timeout=60.0,
+            on_timeout=my_callback,   # optional async fn(device_id, session_id)
+        )
+
+        @server.on_session
+        async def handle(session: USMPSession):
+            data = await session.recv()
+            await session.send(b"ACK")
+
+        asyncio.run(server.serve())
+    """
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 9000,
+        psk: bytes = b"",
+        handshake_timeout: float = 10.0,
+        session_timeout: float = 60.0,
+        on_timeout: Callable[[str, str], Awaitable[None]] | None = None,
+    ):
+        self._host = host
+        self._port = port
+        self._psk = psk
+        self._handshake_timeout = handshake_timeout
+        self._session_timeout = session_timeout
+        self._on_timeout = on_timeout
+        self._handler: Callable[[USMPSession], Awaitable[None]] | None = None
+
+    def on_session(
+        self,
+        fn: Callable[[USMPSession], Awaitable[None]],
+    ) -> Callable[[USMPSession], Awaitable[None]]:
+        """Decorator to register a session handler."""
+        self._handler = fn
+        return fn
+
+    async def _watchdog(self, session: USMPSession) -> None:
+        """
+        Monitors session activity. Closes the session if no DATA or PING
+        is received within session_timeout seconds.
+        Checks every session_timeout/2 seconds to keep the window tight.
+        """
+        interval = self._session_timeout / 2
+        while True:
+            await asyncio.sleep(interval)
+            elapsed = time.monotonic() - session._last_recv
+            if elapsed > self._session_timeout:
+                logger.warning(
+                    "Session timeout: device=%s session=%s (no activity for %.1fs)",
+                    session.device_id,
+                    session.session_id,
+                    elapsed,
+                )
+                if self._on_timeout is not None:
+                    try:
+                        await self._on_timeout(session.device_id, session.session_id)
+                    except Exception as e:
+                        logger.error("on_timeout callback raised: %s", e)
+                # Close the underlying writer — causes read_frame to raise in the
+                # handler, which unblocks and exits the session naturally
+                session._writer.close()
+                return
+
+    async def _handle_client(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        addr = writer.get_extra_info("peername")
+        logger.info("TCP connected: %s", addr)
+
+        watchdog_task: asyncio.Task | None = None
+
+        try:
+            info = await asyncio.wait_for(
+                server_handshake(reader, writer, self._psk),
+                timeout=self._handshake_timeout,
+            )
+            logger.info(
+                "Session established: device=%s session=%s",
+                info.device_id_str,
+                info.session_id_str,
+            )
+
+            session = USMPSession(reader, writer, info)
+
+            # Start watchdog alongside the handler
+            watchdog_task = asyncio.create_task(
+                self._watchdog(session),
+                name=f"usmp-watchdog-{info.session_id_str}",
+            )
+
+            if self._handler:
+                await self._handler(session)
+
+        except HandshakeError as e:
+            logger.warning("Handshake failed (%s): %s", addr, e)
+        except asyncio.TimeoutError:
+            logger.warning("Handshake timeout (%s)", addr)
+        except USMPError as e:
+            logger.warning("Protocol error (%s): %s", addr, e)
+        except Exception as e:
+            logger.error("Unexpected error (%s): %s", addr, e)
+        except HandshakeError as e:
+            logger.warning("Handshake failed (%s): %s", addr, e)
+        except asyncio.TimeoutError:
+            logger.warning("Handshake timeout (%s)", addr)
+        except USMPError as e:
+            logger.warning("Protocol error (%s): %s", addr, e)
+        except (OSError, ConnectionResetError, EOFError) as e:
+            logger.warning("Connection lost (%s): %s", addr, e)
+        except Exception as e:
+            logger.error("Unexpected error (%s): %s", addr, e)
+        except (OSError, ConnectionResetError, EOFError) as e:
+            logger.warning("Connection lost (%s): %s", addr, e)
+        except asyncio.IncompleteReadError:
+            logger.warning("Connection closed mid-frame (%s)", addr)
+        except Exception as e:
+            logger.error("Unexpected error (%s): %s", addr, e)
+
+        finally:
+            # Always cancel watchdog when handler exits for any reason
+            if watchdog_task is not None and not watchdog_task.done():
+                watchdog_task.cancel()
+                try:
+                    await watchdog_task
+                except asyncio.CancelledError:
+                    pass
+
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+            logger.info("Disconnected: %s", addr)
+
+    async def serve(self) -> None:
+        """Start the server and serve forever."""
+        if self._handler is None:
+            raise RuntimeError("No session handler registered. Use @server.on_session")
+
+        srv = await asyncio.start_server(
+            self._handle_client,
+            self._host,
+            self._port,
+        )
+        addr = srv.sockets[0].getsockname()
+        logger.info("Listening on %s:%d", addr[0], addr[1])
+
+        async with srv:
+            await srv.serve_forever()

usmp/_session.py

@@ -0,0 +1,131 @@
+# src/usmp/_session.py
+
+import time
+from .types import PacketType, SessionInfo, USMP_MAGIC, USMP_VERSION
+from ._frame import read_frame, write_frame
+from ._crypto import encrypt, decrypt
+from .errors import SequenceError, ConnectionClosedError
+
+
+class USMPSession:
+    """
+    Represents an established USMP session.
+    Handles encrypted send/recv with sequence number tracking.
+    """
+
+    def __init__(
+        self,
+        reader,
+        writer,
+        info: SessionInfo,
+    ):
+        self._reader = reader
+        self._writer = writer
+        self._info = info
+        self._last_recv: float = time.monotonic()  # updated on every inbound frame
+
+    @property
+    def device_id(self) -> str:
+        return self._info.device_id_str
+
+    @property
+    def session_id(self) -> str:
+        return self._info.session_id_str
+
+    async def send(self, data: bytes) -> None:
+        """Encrypt and send a DATA frame."""
+        seq = self._info.tx_seq
+        ciphertext = encrypt(
+            key=self._info.session_key,
+            seq=seq,
+            session_id=self._info.session_id,
+            type_=int(PacketType.DATA),
+            version=USMP_VERSION,
+            magic=USMP_MAGIC,
+            plaintext=data,
+        )
+        await write_frame(self._writer, PacketType.DATA, ciphertext, seq=seq)
+        self._info.tx_seq += 1
+
+    async def recv(self) -> bytes:
+        """Receive and decrypt a DATA frame. Transparently handles inbound PING/PONG."""
+        frame = await read_frame(self._reader)
+        self._last_recv = time.monotonic()
+
+        if frame.type == PacketType.BYE:
+            raise ConnectionClosedError("Remote sent BYE")
+
+        if frame.type == PacketType.PING:
+            self._info.rx_seq += 1  # ← add this
+            await self._send_pong()
+            return await self.recv()
+
+        if frame.type == PacketType.PONG:
+            self._info.rx_seq += 1
+            return await self.recv()
+
+        if frame.type != PacketType.DATA:
+            raise ValueError(f"Unexpected frame type: {frame.type_name()}")
+
+        if frame.seq != self._info.rx_seq:
+            raise SequenceError(
+                f"Sequence mismatch: expected {self._info.rx_seq}, got {frame.seq}"
+            )
+
+        plaintext = decrypt(
+            key=self._info.session_key,
+            seq=frame.seq,
+            session_id=self._info.session_id,
+            type_=int(frame.type),
+            version=frame.version,
+            magic=frame.magic,
+            length=frame.length,
+            ciphertext_and_tag=frame.payload,
+        )
+        self._info.rx_seq += 1
+        return plaintext
+
+    async def ping(self) -> None:
+        """Send a PING frame."""
+        seq = self._info.tx_seq
+        ciphertext = encrypt(
+            key=self._info.session_key,
+            seq=seq,
+            session_id=self._info.session_id,
+            type_=int(PacketType.PING),
+            version=USMP_VERSION,
+            magic=USMP_MAGIC,
+            plaintext=b"",
+        )
+        await write_frame(self._writer, PacketType.PING, ciphertext, seq=seq)
+        self._info.tx_seq += 1
+
+    async def bye(self) -> None:
+        """Send a BYE frame and close the connection."""
+        seq = self._info.tx_seq
+        ciphertext = encrypt(
+            key=self._info.session_key,
+            seq=seq,
+            session_id=self._info.session_id,
+            type_=int(PacketType.BYE),
+            version=USMP_VERSION,
+            magic=USMP_MAGIC,
+            plaintext=b"",
+        )
+        await write_frame(self._writer, PacketType.BYE, ciphertext, seq=seq)
+        self._info.tx_seq += 1
+        self._writer.close()
+
+    async def _send_pong(self) -> None:
+        seq = self._info.tx_seq
+        ciphertext = encrypt(
+            key=self._info.session_key,
+            seq=seq,
+            session_id=self._info.session_id,
+            type_=int(PacketType.PONG),
+            version=USMP_VERSION,
+            magic=USMP_MAGIC,
+            plaintext=b"",
+        )
+        await write_frame(self._writer, PacketType.PONG, ciphertext, seq=seq)
+        self._info.tx_seq += 1

usmp/errors.py

@@ -0,0 +1,49 @@
+# src/usmp/errors.py
+
+
+class USMPError(Exception):
+    """Base exception for all USMP errors."""
+
+
+class FrameError(USMPError):
+    """Malformed or invalid frame."""
+
+
+class CRCError(FrameError):
+    """CRC verification failed."""
+
+
+class MagicError(FrameError):
+    """Bad magic bytes — not a USMP frame."""
+
+
+class VersionError(FrameError):
+    """Unsupported protocol version."""
+
+
+class PayloadError(FrameError):
+    """Payload truncated or exceeds maximum size."""
+
+
+class HandshakeError(USMPError):
+    """Handshake failed."""
+
+
+class AuthError(HandshakeError):
+    """HMAC verification failed — PSK mismatch or tampered frame."""
+
+
+class CryptoError(USMPError):
+    """AES-GCM decryption or tag verification failed."""
+
+
+class SequenceError(USMPError):
+    """Sequence number out of order — possible replay attack."""
+
+
+class TimeoutError(USMPError):
+    """Handshake or keepalive timeout."""
+
+
+class ConnectionClosedError(USMPError):
+    """Connection closed by remote."""

usmp/types.py

@@ -0,0 +1,87 @@
+# src/usmp/types.py
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class PacketType(IntEnum):
+    HELLO = 0x01
+    CHALLENGE = 0x02
+    HELLO_ACK = 0x03
+    SESSION_OK = 0x04
+    DATA = 0x05
+    PING = 0x06
+    PONG = 0x07
+    BYE = 0x08
+    ERROR = 0xFF
+
+
+class ErrorCode(IntEnum):
+    ERR_VERSION = 0x01
+    ERR_AUTH = 0x02
+    ERR_SEQ = 0x03
+    ERR_CRYPTO = 0x04
+    ERR_BAD_FRAME = 0x05
+    ERR_TIMEOUT = 0x06
+    ERR_INTERNAL = 0x07
+
+
+# Protocol constants
+USMP_MAGIC = 0xABCD
+USMP_VERSION = 0x01
+USMP_HEADER_SIZE = 12  # magic(2)+ver(1)+type(1)+seq(4)+len(2)+crc(2)
+USMP_MAX_PAYLOAD = 480  # max payload bytes (keeps total frame under 512)
+USMP_TAG_LEN = 16  # AES-GCM tag length
+USMP_NONCE_LEN = 32  # handshake nonce length
+USMP_DEVICE_ID_LEN = 6  # MAC address length
+USMP_PUB_KEY_LEN = 32  # X25519 public key length
+USMP_HMAC_LEN = 32  # HMAC-SHA256 output length
+USMP_SESSION_ID_LEN = 4  # session ID length
+USMP_SESSION_KEY_LEN = 32  # AES-256 key length
+USMP_GCM_NONCE_LEN = 12  # AES-GCM nonce length
+
+
+@dataclass
+class USMPFrame:
+    magic: int
+    version: int
+    type: PacketType
+    seq: int
+    length: int
+    crc: int
+    payload: bytes
+
+    def type_name(self) -> str:
+        try:
+            return PacketType(self.type).name
+        except ValueError:
+            return f"UNKNOWN(0x{self.type:02X})"
+
+    def __str__(self) -> str:
+        return (
+            f"USMPFrame("
+            f"type={self.type_name()}, "
+            f"seq={self.seq}, "
+            f"version={self.version}, "
+            f"length={self.length}, "
+            f"crc=0x{self.crc:04X}, "
+            f"payload={self.payload.hex()}"
+            f")"
+        )
+
+
+@dataclass
+class SessionInfo:
+    device_id: bytes
+    session_id: bytes
+    session_key: bytes
+    tx_seq: int = 0
+    rx_seq: int = 0
+
+    @property
+    def device_id_str(self) -> str:
+        return self.device_id.hex(":")
+
+    @property
+    def session_id_str(self) -> str:
+        return self.session_id.hex()

usmp-0.2.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: usmp
+Version: 0.2.0
+Summary: USMP — Unified Secure Multi-transport Protocol. Secure, encrypted device communication for ESP32, Arduino and IoT.
+Author: winterx64
+Author-email: winterx64 <itswinterx64@gmail.com>
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/MetaLoomLabs/usmp
+Project-URL: Repository, https://github.com/MetaLoomLabs/usmp
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# USMP — Unified Secure Multi-transport Protocol
+
+Secure, encrypted communication for ESP32, Arduino, and IoT devices.
+
+USMP sits between raw TCP (no security) and full TLS (too heavy for microcontrollers) — giving any constrained device a fully encrypted, mutually authenticated session in three function calls.
+
+```python
+pip install usmp
+```
+
+## What it gives you
+
+- **Mutual authentication** — both device and server verify each other via HMAC-SHA256 + PSK
+- **Forward secrecy** — X25519 ephemeral key exchange, new keys every session
+- **Encryption** — AES-256-GCM, mandatory, no plaintext mode
+- **Replay protection** — monotonic sequence numbers
+
+## Quickstart
+
+### Server
+
+```python
+import asyncio
+from usmp import USMPServer, USMPSession, ConnectionClosedError
+
+server = USMPServer(host="0.0.0.0", port=9000, psk=b"your-psk-here")
+
+@server.on_session
+async def handle(session: USMPSession):
+    print(f"Device connected: {session.device_id}")
+    try:
+        while True:
+            data = await session.recv()
+            print(f"RX: {data}")
+            await session.send(b"got it")
+    except ConnectionClosedError:
+        print(f"Device disconnected: {session.device_id}")
+
+asyncio.run(server.serve())
+```
+
+### Client (Python)
+
+```python
+import asyncio
+from usmp import USMPClient, ConnectionClosedError
+
+async def main():
+    client = USMPClient(host="127.0.0.1", port=9000, psk=b"your-psk-here")
+    async with client.connect() as session:
+        await session.send(b"hello")
+        reply = await session.recv()
+        print(f"RX: {reply}")
+
+asyncio.run(main())
+```
+
+### Client (ESP32 / Arduino)
+
+```cpp
+#include <USMP.h>
+
+USMPClient usmp("your-psk-here");
+
+void setup() {
+    usmp.begin(USMP::TCP("192.168.1.100").wifi("SSID", "password"));
+    usmp.send("hello from esp32");
+}
+
+void loop() {
+    usmp.maintain(); // keepalive + reconnect
+
+    if (usmp.available()) {
+        Serial.println(usmp.read());
+    }
+}
+```
+
+## Protocol overview
+
+```
+Device                        Server
+  |                              |
+  |-- HELLO (device_id, pub_C) -->|
+  |<- CHALLENGE (nonce, pub_S) ---|
+  |-- HELLO_ACK (HMAC) ---------->|
+  |<- SESSION_OK (session_id) ----|
+  |                              |
+  |== AES-256-GCM encrypted ======|
+```
+
+4-step handshake, then every frame is AES-256-GCM encrypted with a session key derived via X25519 + HKDF-SHA256.
+
+## Installation
+
+```
+pip install usmp
+```
+
+Requires Python 3.11+.
+
+## ESP32 / Arduino library
+
+The Arduino library and ESP-IDF component are available at [github.com/MetaLoomLabs/usmp](https://github.com/MetaLoomLabs/usmp).

usmp-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+usmp/__init__.py,sha256=WLOs7KnzaTRgjJVrRlVtiTdAc-P89g1K99WOB5TrKNw,1106
+usmp/_client.py,sha256=kZeBuOxW2VZ73NSnfjf6p5Hu84_39XL0srNKHEwsB6U,2151
+usmp/_crypto.py,sha256=LbISd6QOtZX3kJdudP3b2pRbU7RLGyHeKYqcWQ2QUS4,3300
+usmp/_frame.py,sha256=poaKBJuKLtANyp2Gty0rlX5qEs57RCHHI8U1fStcaXM,4042
+usmp/_handshake.py,sha256=PnC1o1UdRfcpIl6HFdBNoMm1FNn5LbTtO1jeBjjSsSw,6837
+usmp/_server.py,sha256=IUVTEHPqmW3LEaX4LLSXL_UlEMYGeUTlIXcTpkmbCuE,6279
+usmp/_session.py,sha256=PnmjyYYg_xguIoJPYdQPEwscrhekea8_MZEZH6AseOc,4242
+usmp/errors.py,sha256=tKZM6ZFmTE1o0MMsyI1DA3kFqeLkAn2HMzbT0ASqHK4,1036
+usmp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+usmp/types.py,sha256=jLLyWiLnT_o6Na8mnlf-X5HOJdIpRvS6EYHfmj5K-VI,2081
+usmp-0.2.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
+usmp-0.2.0.dist-info/METADATA,sha256=fps3kV4Toirnl_LlVfnCfrkg5gjrf_ojw-w4vERaTqg,3297
+usmp-0.2.0.dist-info/RECORD,,

usmp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.19
+Root-Is-Purelib: true
+Tag: py3-none-any