adaraz 0.1.0__py3-none-any.whl

adaraz/__init__.py

@@ -0,0 +1,99 @@
+"""ADARAZ Link: secure connection between ADARAZ devices and servers.
+
+See ``docs/protocol.md`` in the repository for the wire protocol.
+"""
+
+from __future__ import annotations
+
+from .codes import derive_psk, format_code, generate_code, normalize_code
+from .const import PROTOCOL_VERSION, RELAY_COMMANDS, SUBPROTOCOL
+from .exceptions import (
+    AdarazError,
+    ConnectionClosed,
+    DeviceNotConnected,
+    DeviceNotFound,
+    InvalidCodeError,
+    PairingCancelled,
+    PairingError,
+    PairingExpired,
+    PairingFailed,
+    PairingRejected,
+    ProtocolError,
+    RelayTimeout,
+)
+from .messages import Cursor, Hello, RelayResult, State
+from .noise import generate_private_key, public_key_from_private
+from .server import (
+    DeviceConnected,
+    DeviceDisconnected,
+    DevicePaired,
+    DeviceSession,
+    DeviceUnpaired,
+    LinkEvent,
+    LinkServer,
+    PairingWindow,
+    PunchReceived,
+    StateChanged,
+    server_id,
+)
+from .storage import (
+    InMemoryStorage,
+    LinkStorage,
+    PairedDevice,
+    PunchDeduplicator,
+    PunchKey,
+    PunchRecord,
+)
+from .transport import MemoryTransport, Transport, build_ws_url, memory_pipe
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "RELAY_COMMANDS",
+    "SUBPROTOCOL",
+    "AdarazError",
+    "ConnectionClosed",
+    "Cursor",
+    "DeviceConnected",
+    "DeviceDisconnected",
+    "DeviceNotConnected",
+    "DeviceNotFound",
+    "DevicePaired",
+    "DeviceSession",
+    "DeviceUnpaired",
+    "Hello",
+    "InMemoryStorage",
+    "InvalidCodeError",
+    "LinkEvent",
+    "LinkServer",
+    "LinkStorage",
+    "MemoryTransport",
+    "PairedDevice",
+    "PairingCancelled",
+    "PairingError",
+    "PairingExpired",
+    "PairingFailed",
+    "PairingRejected",
+    "PairingWindow",
+    "ProtocolError",
+    "PunchDeduplicator",
+    "PunchKey",
+    "PunchReceived",
+    "PunchRecord",
+    "RelayResult",
+    "RelayTimeout",
+    "State",
+    "StateChanged",
+    "Transport",
+    "__version__",
+    "build_ws_url",
+    "derive_psk",
+    "format_code",
+    "generate_code",
+    "generate_private_key",
+    "memory_pipe",
+    "normalize_code",
+    "public_key_from_private",
+    "server_id",
+]

adaraz/_channel.py

@@ -0,0 +1,130 @@
+"""Encrypted message channel shared by the server and the device implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import itertools
+import logging
+
+from .const import CLOSE_GOING_AWAY, MAX_NOISE_MESSAGE
+from .exceptions import ConnectionClosed, ProtocolError
+from .messages import Message, Ping, Pong, UnknownMessage, decode, encode
+from .noise import CipherState, NoiseError
+from .transport import Transport
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class SecureChannel:
+    """Noise transport messages over a :class:`Transport`.
+
+    * serialises sends (the Noise nonce must match the order on the wire),
+    * answers ``ping`` with ``pong`` and swallows ``pong`` and unknown types,
+    * rejects known types that are not valid in this direction (close 4000),
+    * implements liveness (:meth:`run_liveness`).
+    """
+
+    def __init__(
+        self,
+        transport: Transport,
+        send_cipher: CipherState,
+        recv_cipher: CipherState,
+        *,
+        accept: frozenset[type[Message]],
+        ping_interval: float,
+        idle_timeout: float,
+    ) -> None:
+        self.transport = transport
+        self._send_cipher = send_cipher
+        self._recv_cipher = recv_cipher
+        self._accept = accept
+        self._ping_interval = ping_interval
+        self._idle_timeout = idle_timeout
+        self._lock = asyncio.Lock()
+        loop = asyncio.get_running_loop()
+        self._time = loop.time
+        self._last_send = self._last_recv = self._time()
+        self._ping_ids = itertools.count(1)
+        self.close_code: int | None = None
+
+    async def send(self, message: Message) -> None:
+        payload = encode(message)
+        async with self._lock:
+            if self.close_code is not None:
+                raise ConnectionClosed("channel closed")
+            data = self._send_cipher.encrypt_with_ad(b"", payload)
+            self._last_send = self._time()
+            try:
+                await self.transport.send(data)
+            except ConnectionClosed:
+                raise
+            except Exception as err:
+                raise ConnectionClosed(str(err)) from err
+
+    async def recv(self) -> Message | None:
+        """Return the next application message, or ``None`` when the connection ends."""
+        while True:
+            message = await self.recv_any()
+            if message is None:
+                return None
+            if await self.filter(message):
+                return message
+
+    async def recv_any(self) -> Message | None:
+        """Receive, decrypt and decode the next transport message, whatever its type.
+
+        Returns ``None`` when the connection ends. Nothing is answered or filtered;
+        pass the message to :meth:`filter` before using it.
+        """
+        data = await self.transport.recv()
+        if data is None:
+            return None
+        self._last_recv = self._time()
+        if len(data) > MAX_NOISE_MESSAGE:
+            raise ProtocolError("message too large")
+        try:
+            payload = self._recv_cipher.decrypt_with_ad(b"", data)
+        except NoiseError as err:
+            raise ProtocolError(f"cannot decrypt transport message: {err}") from err
+        return decode(payload)
+
+    async def filter(self, message: Message) -> bool:
+        """Handle the channel level part of a message; True if it is for the application.
+
+        ``ping`` is answered with ``pong``; ``pong`` and unknown types are swallowed;
+        a known type not valid in this direction raises :class:`ProtocolError`.
+        """
+        if isinstance(message, Ping):
+            # If the connection is gone, the next recv returns None.
+            with contextlib.suppress(ConnectionClosed):
+                await self.send(Pong(id=message.id))
+            return False
+        if isinstance(message, (Pong, UnknownMessage)):
+            return False
+        if type(message) not in self._accept:
+            raise ProtocolError(f"unexpected message type {message.T!r}")
+        return True
+
+    async def close(self, code: int) -> None:
+        if self.close_code is None:
+            self.close_code = code
+        await self.transport.close(code)
+
+    async def run_liveness(self) -> None:
+        """Send ``ping`` when idle and close the connection when the peer is silent."""
+        while self.close_code is None:
+            now = self._time()
+            idle_deadline = self._last_recv + self._idle_timeout
+            ping_deadline = self._last_send + self._ping_interval
+            if now >= idle_deadline:
+                _LOGGER.debug("peer silent for %.0f s, closing", self._idle_timeout)
+                await self.close(CLOSE_GOING_AWAY)
+                return
+            if now >= ping_deadline:
+                try:
+                    await self.send(Ping(id=next(self._ping_ids)))
+                except ConnectionClosed:
+                    return
+                continue
+            await asyncio.sleep(min(idle_deadline, ping_deadline) - now)

adaraz/aiohttp_ws.py

@@ -0,0 +1,80 @@
+"""aiohttp adapter (server and client side). Requires the ``aiohttp`` extra."""
+
+from __future__ import annotations
+
+import contextlib
+from typing import TYPE_CHECKING
+
+import aiohttp
+from aiohttp import WSMsgType, web
+
+from .const import CLOSE_NORMAL, CLOSE_PROTOCOL_ERROR, MAX_WS_MESSAGE, SUBPROTOCOL
+from .exceptions import ConnectionClosed, ProtocolError
+from .transport import build_ws_url
+
+if TYPE_CHECKING:
+    from .server import LinkServer
+
+__all__ = ["AiohttpTransport", "connect", "handle_request"]
+
+_CLOSED = (WSMsgType.CLOSE, WSMsgType.CLOSING, WSMsgType.CLOSED, WSMsgType.ERROR)
+
+
+class AiohttpTransport:
+    """:class:`adaraz.Transport` over an aiohttp WebSocket (either side)."""
+
+    def __init__(self, ws: web.WebSocketResponse | aiohttp.ClientWebSocketResponse) -> None:
+        self.ws = ws
+
+    @property
+    def close_code(self) -> int | None:
+        return self.ws.close_code
+
+    async def recv(self) -> bytes | None:
+        if self.ws.closed:
+            return None
+        msg = await self.ws.receive()
+        if msg.type == WSMsgType.BINARY:
+            data: bytes = msg.data
+            return data
+        if msg.type == WSMsgType.TEXT:
+            raise ProtocolError("text WebSocket message", CLOSE_PROTOCOL_ERROR)
+        if msg.type in _CLOSED:
+            return None
+        raise ProtocolError(f"unexpected WebSocket message type {msg.type!r}")
+
+    async def send(self, data: bytes) -> None:
+        if self.ws.closed:
+            raise ConnectionClosed("WebSocket closed")
+        try:
+            await self.ws.send_bytes(data)
+        except (ConnectionError, RuntimeError, aiohttp.ClientError) as err:
+            raise ConnectionClosed(str(err)) from err
+
+    async def close(self, code: int = CLOSE_NORMAL) -> None:
+        if self.ws.closed:
+            return
+        with contextlib.suppress(ConnectionError, RuntimeError, aiohttp.ClientError):
+            await self.ws.close(code=code)
+
+
+async def handle_request(server: LinkServer, request: web.Request) -> web.WebSocketResponse:
+    """Accept a WebSocket request and run it as an ADARAZ Link connection."""
+    ws = web.WebSocketResponse(protocols=(SUBPROTOCOL,), max_msg_size=MAX_WS_MESSAGE, autoping=True)
+    await ws.prepare(request)
+    await server.handle_connection(AiohttpTransport(ws))
+    return ws
+
+
+async def connect(
+    session: aiohttp.ClientSession, base_url: str, *, timeout: float = 10.0
+) -> AiohttpTransport:
+    """Open a client WebSocket to a server base URL (device side, for tests/tools)."""
+    ws = await session.ws_connect(
+        build_ws_url(base_url),
+        protocols=(SUBPROTOCOL,),
+        max_msg_size=MAX_WS_MESSAGE,
+        autoping=True,
+        timeout=aiohttp.ClientWSTimeout(ws_receive=None, ws_close=timeout),
+    )
+    return AiohttpTransport(ws)

adaraz/codes.py

@@ -0,0 +1,68 @@
+"""Pairing codes and PSK derivation (protocol section 2, "Pairing code and PSK")."""
+
+from __future__ import annotations
+
+import secrets
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from .exceptions import InvalidCodeError
+
+__all__ = [
+    "ALPHABET",
+    "CODE_LENGTH",
+    "GROUP_LENGTH",
+    "PSK_INFO",
+    "PSK_SALT",
+    "derive_psk",
+    "format_code",
+    "generate_code",
+    "normalize_code",
+]
+
+#: Crockford Base32 alphabet.
+ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+#: Number of symbols in a pairing code (60 bits).
+CODE_LENGTH = 12
+#: Symbols per group in the display form ``XXXX-XXXX-XXXX``.
+GROUP_LENGTH = 4
+PSK_SALT = b"ADARAZ pairing v1"
+PSK_INFO = b"psk"
+
+_MAP = str.maketrans({"O": "0", "I": "1", "L": "1"})
+
+
+def generate_code() -> str:
+    """Return a new random pairing code formatted as ``XXXX-XXXX-XXXX``."""
+    raw = "".join(secrets.choice(ALPHABET) for _ in range(CODE_LENGTH))
+    return format_code(raw)
+
+
+def normalize_code(code: str) -> str:
+    """Normalise a code as typed by a person.
+
+    Uppercase, remove ``-`` and spaces, map ``O`` to ``0`` and ``I``/``L`` to ``1``.
+    Raises :class:`InvalidCodeError` if the result is not 12 alphabet symbols.
+    """
+    if not code.isascii():
+        raise InvalidCodeError("pairing code contains non-ASCII characters")
+    norm = code.upper().replace("-", "").replace(" ", "").translate(_MAP)
+    if len(norm) != CODE_LENGTH or any(ch not in ALPHABET for ch in norm):
+        raise InvalidCodeError(
+            f"pairing code must be {CODE_LENGTH} symbols of 0-9 and A-Z (without U)"
+        )
+    return norm
+
+
+def format_code(code: str) -> str:
+    """Return the display form ``XXXX-XXXX-XXXX`` of a code (normalised first)."""
+    norm = normalize_code(code)
+    return "-".join(norm[i : i + GROUP_LENGTH] for i in range(0, CODE_LENGTH, GROUP_LENGTH))
+
+
+def derive_psk(code: str) -> bytes:
+    """Derive the 32 byte Noise PSK from a pairing code (normalised first)."""
+    norm = normalize_code(code)
+    hkdf = HKDF(algorithm=hashes.SHA256(), length=32, salt=PSK_SALT, info=PSK_INFO)
+    return hkdf.derive(norm.encode("ascii"))

adaraz/const.py

@@ -0,0 +1,56 @@
+"""Protocol constants (ADARAZ Link protocol, version 1)."""
+
+from __future__ import annotations
+
+from typing import Final
+
+PROTOCOL_VERSION: Final = 1
+SUBPROTOCOL: Final = "adaraz.v1"
+DEFAULT_PATH: Final = "/api/adaraz/ws"
+
+MODE_PAIR: Final = 0x50  # "P"
+MODE_SESSION: Final = 0x53  # "S"
+
+PROLOGUE_PAIR: Final = b"ADARAZ/1 pair"
+PROLOGUE_SESSION: Final = b"ADARAZ/1 session"
+
+#: Largest Noise message (payload plus 16 byte tag).
+MAX_NOISE_MESSAGE: Final = 4096
+#: Largest JSON payload of a transport message.
+MAX_PAYLOAD: Final = MAX_NOISE_MESSAGE - 16
+#: Largest WebSocket message accepted at the WebSocket layer. Anything above
+#: MAX_NOISE_MESSAGE (+1 for the mode byte) and below this is closed with 4000 by the
+#: protocol code; anything above this is closed by the WebSocket library.
+MAX_WS_MESSAGE: Final = 65536
+
+MAX_PUNCH_ITEMS: Final = 100
+#: Largest log index, count, cursor position and punch timestamp (uint32).
+MAX_UINT32: Final = 0xFFFFFFFF
+
+CLOSE_NORMAL: Final = 1000
+CLOSE_GOING_AWAY: Final = 1001
+CLOSE_INTERNAL_ERROR: Final = 1011
+CLOSE_PROTOCOL_ERROR: Final = 4000
+CLOSE_UNKNOWN_DEVICE: Final = 4001
+CLOSE_SUPERSEDED: Final = 4002
+CLOSE_PAIRING_REJECTED: Final = 4003
+
+PING_INTERVAL: Final = 30.0
+IDLE_TIMEOUT: Final = 90.0
+#: A session that is not established (the server has not decrypted the device's first
+#: transport message) within this time is closed (protocol section 4).
+ESTABLISH_TIMEOUT: Final = 10.0
+#: Time the server has to send ``paired`` after pairing message 3.
+PAIRED_DEADLINE: Final = 10.0
+#: Pairing window lifetime and attempt limit.
+PAIRING_WINDOW: Final = 600.0
+PAIRING_MAX_FAILURES: Final = 5
+#: Punches older than this at arrival are "late".
+LATE_AFTER: Final = 300.0
+
+RELAY_COMMANDS: Final = ("open", "on", "off", "pulse")
+PULSE_MS_MIN: Final = 100
+PULSE_MS_MAX: Final = 10000
+
+CAP_PUNCHES: Final = "punches"
+CAP_RELAY: Final = "relay"