clavem 0.1.0__py3-none-any.whl

clavem/channel.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import asyncio
+import ssl
+import struct
+from types import TracebackType
+
+MAX_MESSAGE = 65_536
+_HEADER = struct.Struct("!I")
+
+
+class MessageTooLarge(ValueError):
+    """A message exceeds the channel's 64 KiB limit."""
+
+
+class Channel:
+    """One reader and serialized writers on a length-prefixed byte stream."""
+
+    def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        self._reader: asyncio.StreamReader = reader
+        self._writer: asyncio.StreamWriter = writer
+        self._send_lock: asyncio.Lock = asyncio.Lock()
+
+    async def send(self, message: bytes) -> None:
+        """Send one message; concurrent senders cannot interleave frames."""
+        if len(message) > MAX_MESSAGE:
+            raise MessageTooLarge("message exceeds 64 KiB")
+        async with self._send_lock:
+            self._writer.write(_HEADER.pack(len(message)) + message)
+            await self._writer.drain()
+
+    async def receive(self) -> bytes:
+        """Read one message. Only one task may receive at a time."""
+        header = await self._reader.readexactly(_HEADER.size)
+        (length,) = _HEADER.unpack(header)
+        if length > MAX_MESSAGE:
+            self._writer.close()
+            raise MessageTooLarge("peer message exceeds 64 KiB; channel closed")
+        return await self._reader.readexactly(length)
+
+    async def close(self) -> None:
+        """Close the stream, bounded by its configured TLS shutdown timeout."""
+        self._writer.close()
+        try:
+            await self._writer.wait_closed()
+        except (ConnectionError, ssl.SSLError, TimeoutError):
+            # A disconnected peer cannot acknowledge TLS shutdown.
+            pass
+
+    async def __aenter__(self) -> Channel:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()

clavem/tls.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import ssl
+from collections.abc import Mapping
+
+
+def _validate(identity: str, key: bytes) -> None:
+    if not identity or len(identity.encode("utf-8")) > 255 or "\0" in identity:
+        raise ValueError("identity must contain 1-255 UTF-8 bytes without NUL")
+    if len(key) != 32:
+        raise ValueError("key must contain 32 randomly generated bytes")
+
+
+def _context(protocol: int) -> ssl.SSLContext:
+    if not ssl.HAS_PSK:
+        raise RuntimeError("this Python/OpenSSL build does not support TLS-PSK")
+    context = ssl.SSLContext(protocol)
+    context.minimum_version = ssl.TLSVersion.TLSv1_3
+    context.maximum_version = ssl.TLSVersion.TLSv1_3
+    return context
+
+
+def client_context(identity: str, key: bytes) -> ssl.SSLContext:
+    """Authenticate with an external PSK; do not trust certificate fallback."""
+    _validate(identity, key)
+    context = _context(ssl.PROTOCOL_TLS_CLIENT)
+    context.check_hostname = False
+    # A successful external-PSK handshake needs no CA. Certificate fallback
+    # must still fail verification rather than authenticate an unrelated peer.
+    context.verify_mode = ssl.CERT_REQUIRED
+    context.set_psk_client_callback(lambda _hint: (identity, key))
+    return context
+
+
+def server_context(keys: Mapping[str, bytes]) -> ssl.SSLContext:
+    """Accept only the supplied identities and their external PSKs."""
+    if not keys:
+        raise ValueError("at least one identity is required")
+    allowed = dict(keys)
+    for identity, key in allowed.items():
+        _validate(identity, key)
+    context = _context(ssl.PROTOCOL_TLS_SERVER)
+    context.num_tickets = 0
+
+    def lookup(identity: str | None) -> bytes:
+        if identity not in allowed:
+            return b""  # Decline unknown PSKs; no certificate fallback is configured.
+        return allowed[identity]
+
+    context.set_psk_server_callback(lookup)
+    return context

clavem/transport.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import asyncio
+import socket
+import ssl
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import asynccontextmanager
+
+from clavem.channel import MAX_MESSAGE, Channel
+from clavem.tls import client_context, server_context
+
+Handler = Callable[[Channel], Awaitable[None]]
+
+
+async def connect(
+    host: str,
+    port: int,
+    *,
+    identity: str,
+    key: bytes,
+    timeout: float = 5,  # noqa: ASYNC109 - also bounds the TLS handshake.
+) -> Channel:
+    """Establish a TLS 1.3 external-PSK channel within timeout seconds."""
+    if timeout <= 0:
+        raise ValueError("timeout must be positive")
+    context = client_context(identity, key)
+    async with asyncio.timeout(timeout):
+        reader, writer = await asyncio.open_connection(
+            host,
+            port,
+            ssl=context,
+            server_hostname="",
+            ssl_handshake_timeout=timeout,
+            ssl_shutdown_timeout=2,
+            limit=MAX_MESSAGE + 4,
+        )
+    channel = Channel(reader, writer)
+    if not writer.get_extra_info("ssl_object").session_reused:
+        await channel.close()
+        raise ssl.SSLError("peer did not authenticate with an external PSK")
+    return channel
+
+
+@asynccontextmanager
+async def serve(
+    handler: Handler,
+    host: str,
+    port: int,
+    *,
+    keys: Mapping[str, bytes],
+    handshake_timeout: float = 5,
+) -> AsyncIterator[asyncio.Server]:
+    """Own a listener and its handlers; cancel handlers when leaving the context.
+
+    A handler owns one authenticated channel for its lifetime. Unexpected
+    handler errors propagate through the task group and stop the listener.
+    Applications should handle expected disconnects in their handler.
+    """
+    if handshake_timeout <= 0:
+        raise ValueError("handshake_timeout must be positive")
+    context = server_context(keys)
+    tasks: set[asyncio.Task[None]] = set()
+
+    async def run(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        async with Channel(reader, writer) as channel:
+            if not writer.get_extra_info("ssl_object").session_reused:
+                raise ssl.SSLError("peer did not authenticate with an external PSK")
+            # Accepted sockets do not consistently inherit asyncio's TCP_NODELAY default.
+            writer.get_extra_info("socket").setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+            await handler(channel)
+
+    async with asyncio.TaskGroup() as group:
+
+        def accept(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+            task = group.create_task(run(reader, writer))
+            tasks.add(task)
+            task.add_done_callback(tasks.discard)
+
+        server = await asyncio.start_server(
+            accept,
+            host,
+            port,
+            ssl=context,
+            ssl_handshake_timeout=handshake_timeout,
+            ssl_shutdown_timeout=2,
+            limit=MAX_MESSAGE + 4,
+        )
+        try:
+            yield server
+        finally:
+            server.close()
+            for task in tasks:
+                task.cancel()
+            await server.wait_closed()

clavem-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: clavem
+Version: 0.1.0
+Summary: Small async TLS-PSK message channels.
+Project-URL: Repository, https://github.com/Chamkang6093/clavem
+Author: Cham
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,messaging,psk,tls
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# clavem
+
+Small async TLS-PSK message channels. Python 3.13+, no third-party runtime dependencies.
+
+Clavem authenticates peers with a shared random key and carries length-prefixed byte
+messages over one TLS 1.3 connection. It does not reconnect, schedule heartbeats,
+serialize application data, or configure logging.
+
+## Install
+
+```bash
+pip install clavem
+```
+
+For an unpublished checkout, use `uv sync` and `uv run` instead. Both endpoints
+need a Python/OpenSSL build with PSK support:
+
+```bash
+python -c "import ssl; print(ssl.OPENSSL_VERSION, ssl.HAS_PSK)"
+```
+
+`HAS_PSK` must be `True`. Check this on the exact interpreter used for deployment
+and on the interpreter bundled into a desktop executable.
+
+## Connect and exchange messages
+
+Create one 32-byte random key and securely provision the same bytes on both peers.
+Use a different key for unrelated services. The identity is public, not a password.
+
+```python
+from pathlib import Path
+import asyncio
+
+from clavem.transport import connect
+
+
+async def main() -> None:
+    key = Path("psk.bin").read_bytes()
+    async with await connect("127.0.0.1", 9443, identity="home", key=key) as channel:
+        await channel.send(b"hello")
+        async with asyncio.timeout(5):
+            reply = await channel.receive()
+        print(reply)
+
+
+asyncio.run(main())
+```
+
+One task receives messages; multiple tasks may send, with complete frames serialized
+by the channel. TCP_NODELAY is enabled on both peers: the client uses asyncio's
+default, and the server explicitly enables it on accepted TLS sockets. Messages
+can be empty and are limited to 65,536 bytes. The wire format is a four-byte
+unsigned network-order length followed by that many bytes.
+
+## Serve
+
+```python
+from pathlib import Path
+import asyncio
+
+from clavem.channel import Channel
+from clavem.transport import serve
+
+
+async def echo(channel: Channel) -> None:
+    try:
+        while True:
+            async with asyncio.timeout(30):
+                message = await channel.receive()
+                await channel.send(message)
+    except (asyncio.IncompleteReadError, ConnectionError, TimeoutError):
+        return
+
+
+async def main() -> None:
+    key = Path("psk.bin").read_bytes()
+    async with serve(echo, "127.0.0.1", 9443, keys={"home": key}) as server:
+        await server.serve_forever()
+
+
+asyncio.run(main())
+```
+
+`serve()` owns accepted channels and handler tasks. Returning from a handler closes
+its channel. Leaving the server context closes the listener and cancels and awaits
+remaining handlers. Handle expected peer disconnects in your handler; unexpected
+handler exceptions stop the server and propagate through its task group.
+
+## Contract
+
+| API | Behavior |
+| --- | --- |
+| `connect(..., timeout=5)` | Bounds TCP connection and TLS authentication together. Returns a `Channel`. |
+| `serve(..., handshake_timeout=5)` | Async context manager yielding an `asyncio.Server`. |
+| `Channel.send(bytes)` | Checks the size before writing and applies stream backpressure. |
+| `Channel.receive()` | Reads a complete frame; EOF raises `asyncio.IncompleteReadError`. |
+| `Channel.close()` | Closes the stream; supported by `async with channel`. |
+| `client_context()` / `server_context()` | TLS contexts for applications that need lower-level asyncio integration. |
+
+An oversized incoming frame raises `clavem.channel.MessageTooLarge` and closes
+the stream. An oversized outgoing message raises the same error before writing.
+Network, TLS, and timeout exceptions retain their standard-library types. After
+cancelling or timing out an in-progress receive or send, close the channel rather
+than trying to reuse a potentially partial exchange.
+
+TLS contexts require external PSK authentication. The client loads no trusted CAs,
+the server loads no certificate and issues no session tickets, and the transport
+checks that PSK authentication was negotiated. There is no plaintext fallback.
+Clavem sets neither application idle timeouts nor connection-count limits; the
+hosting application owns those policies.
+
+## Development and release
+
+Use `uv sync` for the environment and committed `uv.lock`. Run `uv run pytest` for real
+loopback TLS regressions: normal PSK exchange, rejection of untrusted and trusted
+certificate fallback, and TCP_NODELAY checks on both peers. The publish workflow
+runs these checks before building distributions.
+
+Versions live in `pyproject.toml` and `uv.lock`. Release with a matching `vX.Y.Z`
+tag after configuring the repository's `pypi` environment and the PyPI Trusted
+Publisher. The workflow builds distributions, verifies an isolated wheel import,
+publishes to PyPI, and attaches distributions to a GitHub Release.

clavem-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+clavem/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clavem/channel.py,sha256=ZvDG9b-p2PMlMxj2WohOC-m2MgreTsjltA8uurys_yg,2002
+clavem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clavem/tls.py,sha256=ar8telR9WCfZUqyfjuB_I7pc5uomSmt8JPG3mtjWs1Q,1914
+clavem/transport.py,sha256=Omp_VRtj7Nub6YfRhrcr8kW68hLP-3UfpJvtPeCWWFY,3176
+clavem-0.1.0.dist-info/METADATA,sha256=g8XOweb2O0JJyJeUWD56Gx8AZlJMmPYx3g2ZZnkDamg,5201
+clavem-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+clavem-0.1.0.dist-info/licenses/LICENSE,sha256=R2JKtKOoqKohwk31ygpA8Udqk6nZjU-sWPhtwYxj0M8,1061
+clavem-0.1.0.dist-info/RECORD,,

clavem-0.1.0.dist-info/WHEEL

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

clavem-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.