dark-chat 2.1.0__py3-none-any.whl

dark_chat-2.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: dark-chat
+Version: 2.1.0
+Summary: Minimal two-person encrypted terminal chat and WebSocket relay
+Project-URL: Repository, https://github.com/iZubayr/dark-terminal-chat
+Project-URL: Issues, https://github.com/iZubayr/dark-terminal-chat/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography<50,>=44
+Requires-Dist: websockets<18,>=15
+Requires-Dist: prompt-toolkit<4,>=3.0.48
+
+# Dark Terminal Chat
+
+A plain, English terminal chat for two people. No banner, logo, animation, or forced color. Python 3.10 or newer is required. The client and WebSocket server install from the same Python package.
+
+Version 2 uses a new session protocol. Use version 2 clients and servers together. Source: [GitHub](https://github.com/iZubayr/dark-terminal-chat).
+
+## Install
+
+Install from [PyPI](https://pypi.org/project/dark-chat/):
+
+~~~sh
+pip install dark-chat
+~~~
+
+Create a chat:
+
+~~~sh
+dark-chat --new
+~~~
+
+Join a chat:
+
+~~~sh
+dark-chat --chat
+~~~
+
+Enter your name when asked. The creator receives a code and shares it with the peer. The peer enters that code when asked. Both commands connect to the hosted server automatically.
+
+For development, install from this folder on Windows:
+
+~~~powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install .
+~~~
+
+On Linux or macOS:
+
+~~~sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+~~~
+
+The package provides two commands: dark-chat and dark-chat-server. You can also use python -m dark_terminal_chat and python -m dark_terminal_chat.server.
+
+## Local use
+
+Open three terminals with the Python environment activated.
+
+~~~sh
+# Server
+dark-chat-server
+
+# Creator
+dark-chat --server ws://127.0.0.1:8080/ws --new --name elliot
+
+# Peer, in another terminal
+dark-chat --server ws://127.0.0.1:8080/ws --chat --name whiterose
+~~~
+
+The creator receives a line starting with "Code:". The peer pastes that code at "Code:". The code is hidden while entering it. If no name is supplied, the program asks "Name:". Running dark-chat without either mode asks "Create or join? [c/j]:".
+
+The interface contains only prompts, messages, and relevant connection/error notices. Example:
+
+~~~text
+Code: <invite code>
+Waiting for peer.
+whiterose joined.
+whiterose> Hello.
+elliot>
+~~~
+
+On Windows, chat.cmd and server.cmd use this folder's .venv when available.
+
+## Session rules
+
+- Each chat has two participant slots. A third participant is refused.
+- Leaving with /exit or Ctrl+C releases the participant's slot immediately while connected.
+- When both participants leave, the room is removed. Joining with its old code fails; create a new chat for a new code.
+- A dropped connection reserves the same participant's slot for 60 seconds. Only that participant's in-memory resume token can reclaim it.
+- The client tries to reconnect for up to 60 seconds. When a server restarts, room state is lost and a new chat is needed.
+- Sending is paused while the peer is offline. The draft remains editable.
+- Messages are not queued or automatically resent. If receipt isn't confirmed, the draft is kept and a short notice is shown. A lost receipt can mean the peer already saw the message; check before manually resending.
+- Messages and drafts are not written to files. Old messages are not replayed after reconnecting.
+
+## Internet use
+
+The deployed server is available at wss://zubayr.alwaysdata.net/dark-chat/ws:
+
+~~~sh
+dark-chat --new
+dark-chat --chat
+~~~
+
+Share the code with the peer. To use your own relay, pass --server wss://YOUR_SERVER/ws. Use wss:// for internet connections. TLS certificates are checked; --ca ca.pem supports a private certificate authority.
+
+DARK_CHAT_SERVER can override the default relay. --server overrides that environment variable. DARK_CHAT_CODE is supported for non-interactive clients; interactive clients ask for the code instead.
+
+For local Wi-Fi, use --host 0.0.0.0 on the server and --server ws://LAN_IP:8080/ws --allow-insecure on clients.
+
+[AlwaysData setup beside MediaHub](docs/alwaysdata.md).
+
+## Commands
+
+| Command | Action |
+| --- | --- |
+| /help | List commands |
+| /who | Show the connected participants whose names are known |
+| /clear | Clear the screen |
+| /exit or Ctrl+C | Leave |
+
+## Privacy
+
+Messages and names are encrypted on the client with AES-256-GCM. Keys are derived from a random 32-byte invite code with HKDF-SHA256. The invite code is never sent to the relay. The relay sees opaque room/session identifiers, IP addresses, message sizes, timing, and delivery-control metadata.
+
+An invite code is shared access, and a name is not verified identity. Keep the code private. The terminal scrollback may retain displayed messages and the creator's code; /clear is not secure erasure. There is no forward secrecy, anonymity guarantee, or independent security audit.
+
+The relay holds only session metadata and temporary network buffers. There is no message history or application-level message queue. The default server limit is 128 connections/rooms, with two participant slots per room and a 40-packet limit per connection per 10 seconds. Run one relay process; separate instances do not share rooms.
+
+## Build and check
+
+~~~sh
+python -m pip install -e . build twine
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+~~~
+
+[Package distribution](docs/distribution.md).
+
+GitHub Actions tests the installed wheel on Linux with Python 3.10/3.12 and on Windows with Python 3.12. After all jobs pass, it advances the deploy branch. AlwaysData checks that branch every five minutes and tests the candidate again before changing the running version. See [automatic updates](docs/alwaysdata.md#automatic-updates).
+
+The earlier Node.js TCP experiment remains as reference source only. It does not support the current session protocol. The Python client/server is the application.

dark_chat-2.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dark_terminal_chat/__init__.py,sha256=Tjp_C8ZOtL3SBxNSxtUk2lcIOpQ_gCUYBZk_0qFPFvg,69
+dark_terminal_chat/__main__.py,sha256=dBYQQw4fGaTMLk7QksrvZzZEbDRD9TajoO8arFHMcLs,33
+dark_terminal_chat/client.py,sha256=hpRLH6x52t8MY_urB7PoWThNgDGB84jN3cZe82rllDg,19410
+dark_terminal_chat/protocol.py,sha256=XHBCZvaZm0-FOlLgAtBTT6HoQ8kpf6X4fAJB3uAzyAU,3697
+dark_terminal_chat/server.py,sha256=hC5EnKYUquoRg69tARv164y2lkDWMc0-9Q6uTEvSXpo,10527
+dark_chat-2.1.0.dist-info/METADATA,sha256=SwL4S3xVfFiAmOxiqV9QsoHXQi8PlZrUn4-ZMUxy7bA,6056
+dark_chat-2.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+dark_chat-2.1.0.dist-info/entry_points.txt,sha256=qOA0m8GL1bvCXkx29FZlgllYXKFh6x6R91IUvxWfyIM,111
+dark_chat-2.1.0.dist-info/top_level.txt,sha256=mm_1CFI5qdY-x85cSU8uEWqJXc9BfKaBzj-2qGT26Hw,19
+dark_chat-2.1.0.dist-info/RECORD,,

dark_chat-2.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dark_chat-2.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dark-chat = dark_terminal_chat.client:main
+dark-chat-server = dark_terminal_chat.server:main

dark_chat-2.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dark_terminal_chat

dark_terminal_chat/__init__.py

@@ -0,0 +1,3 @@
+"""Encrypted terminal chat over WebSocket."""
+
+__version__ = "2.1.0"

dark_terminal_chat/__main__.py

@@ -0,0 +1,3 @@
+from .client import main
+
+main()

dark_terminal_chat/client.py

@@ -0,0 +1,406 @@
+"""Minimal English terminal client with a 60-second reconnect window."""
+
+import argparse
+import asyncio
+import contextlib
+import os
+import re
+import ssl
+import sys
+import threading
+import time
+import uuid
+from urllib.parse import urlsplit, urlunsplit
+
+from cryptography.exceptions import InvalidTag
+from prompt_toolkit import PromptSession, prompt
+from prompt_toolkit.history import DummyHistory
+from prompt_toolkit.patch_stdout import patch_stdout
+from websockets.asyncio.client import connect
+from websockets.exceptions import ConnectionClosed, InvalidHandshake
+
+from . import __version__
+from .protocol import MAX_FRAME, MAX_TEXT, SESSION, decrypt, dumps, encrypt, new_code, parse, room_keys, safe_text, valid_message
+
+RECONNECT_SECONDS = 60
+DEFAULT_SERVER = "wss://zubayr.alwaysdata.net/dark-chat/ws"
+
+
+class SessionError(Exception):
+    pass
+
+
+def server_url(value, allow_insecure=False):
+    value = value.strip()
+    if any(ord(char) < 33 for char in value):
+        raise ValueError("Server address cannot contain spaces or control characters.")
+    url = urlsplit(value)
+    scheme = {"https": "wss", "http": "ws"}.get(url.scheme, url.scheme)
+    if (scheme not in {"ws", "wss"} or not url.hostname
+            or url.username is not None or url.password is not None or url.query or url.fragment):
+        raise ValueError("Use a server address such as wss://ACCOUNT.alwaysdata.net/dark-chat/ws.")
+    if url.port is not None and not 1 <= url.port <= 65535:
+        raise ValueError("Invalid server port.")
+    if scheme == "ws" and url.hostname not in {"localhost", "127.0.0.1", "::1"} and not allow_insecure:
+        raise ValueError("Use wss:// over the internet. For a local network, use --allow-insecure.")
+    return urlunsplit((scheme, url.netloc, url.path or "/ws", "", ""))
+
+
+class Terminal:
+    def __init__(self):
+        self.interactive = sys.stdin.isatty() and sys.stdout.isatty()
+
+    def say(self, text):
+        print(safe_text(text), flush=True)
+
+    def ask(self, text, secret=False):
+        if not self.interactive:
+            raise ValueError("Use an interactive terminal, or provide --name and DARK_CHAT_CODE.")
+        return prompt(text, is_password=secret, history=DummyHistory()).strip()
+
+
+class Chat:
+    def __init__(self, terminal, keys, name, reconnect_seconds=RECONNECT_SECONDS):
+        self.terminal = terminal
+        self.keys = keys
+        self.name = name
+        self.session = str(uuid.uuid4())
+        self.seq = 0
+        self.peers = {}
+        self.online = {self.session}
+        self.peer_ready = False
+        self.token = None
+        self.ws = None
+        self.finished = asyncio.Event()
+        self.pending = {}
+        self.draft = ""
+        self.reconnect_seconds = reconnect_seconds
+
+    def packet(self, kind, text="", **extra):
+        self.seq += 1
+        envelope = encrypt(self.keys, {"kind": kind, "name": self.name, "text": text,
+                                       "session": self.session, "seq": self.seq, **extra})
+        envelope["id"] = self.seq
+        envelope["receipt"] = kind == "chat"
+        return envelope
+
+    def fail_pending(self):
+        for future in self.pending.values():
+            if not future.done():
+                future.set_result(False)
+
+    async def receive(self, ws):
+        async for raw in ws:
+            frame = parse(raw)
+            if frame.get("type") == "presence":
+                online, reserved = frame.get("sessions"), frame.get("reserved")
+                if (not isinstance(online, list) or not isinstance(reserved, list)
+                        or not 1 <= len(reserved) <= 2 or not 1 <= len(online) <= 2
+                        or not all(isinstance(sid, str) and SESSION.fullmatch(sid) for sid in reserved + online)
+                        or len(set(reserved)) != len(reserved) or len(set(online)) != len(online)
+                        or not set(online) <= set(reserved) or self.session not in online):
+                    raise SessionError("Invalid server response.")
+                new_online = set(online)
+                for sid in self.online - new_online:
+                    peer = self.peers.get(sid)
+                    if peer and peer["online"]:
+                        action = "disconnected" if sid in reserved else "left"
+                        self.terminal.say(f"{peer['name']} {action}.")
+                        peer["online"] = False
+                    if sid not in reserved:
+                        self.peers.pop(sid, None)
+                if len(new_online) == 1:
+                    if self.peer_ready:
+                        self.fail_pending()
+                    self.peer_ready = False
+                    if not self.peers:
+                        self.terminal.say("Waiting for peer.")
+                newcomers = new_online - self.online
+                self.online = new_online
+                if newcomers:
+                    await ws.send(dumps(self.packet("hello")))
+                continue
+            if frame.get("type") == "not_delivered":
+                if type(frame.get("id")) is not int:
+                    raise SessionError("Invalid server response.")
+                future = self.pending.get(frame.get("id"))
+                if future and not future.done():
+                    future.set_result(False)
+                self.peer_ready = False
+                continue
+            if frame.get("type") != "message":
+                raise SessionError("Invalid server response.")
+            try:
+                message = decrypt(self.keys, frame)
+            except (ValueError, InvalidTag, UnicodeError):
+                self.terminal.say("Invalid encrypted message ignored.")
+                continue
+            if (not valid_message(message) or message["session"] != frame.get("sender")
+                    or message["seq"] != frame.get("id")
+                    or message["session"] not in self.online or message["session"] == self.session):
+                continue
+            sid = message["session"]
+            old = self.peers.get(sid)
+            if old and old["seq"] >= message["seq"]:
+                continue
+            name = safe_text(message["name"])
+            self.peers[sid] = {"name": name, "seq": message["seq"], "online": True}
+            self.peer_ready = True
+            if message["kind"] == "hello":
+                if not old:
+                    self.terminal.say(f"{name} joined.")
+                elif not old["online"]:
+                    self.terminal.say(f"{name} reconnected.")
+            elif message["kind"] == "chat":
+                self.terminal.say(f"{name}> {safe_text(message['text'])}")
+                await ws.send(dumps(self.packet("ack", ack=message["seq"])))
+            elif message["kind"] == "ack":
+                future = self.pending.get(message["ack"])
+                if future and not future.done():
+                    future.set_result(True)
+        raise ConnectionError("Connection closed.")
+
+    async def send_message(self, text):
+        if self.ws is None or not self.peer_ready:
+            self.terminal.say("Sending paused. Draft kept.")
+            return False
+        envelope = self.packet("chat", text)
+        message_id = envelope["id"]
+        future = asyncio.get_running_loop().create_future()
+        self.pending[message_id] = future
+        try:
+            await self.ws.send(dumps(envelope))
+            confirmed = await asyncio.wait_for(future, timeout=8)
+        except (ConnectionClosed, OSError, TimeoutError, asyncio.TimeoutError):
+            confirmed = False
+        finally:
+            self.pending.pop(message_id, None)
+        if not confirmed:
+            self.terminal.say("Delivery not confirmed. Draft kept.")
+        return confirmed
+
+    async def send_input(self):
+        terminal = self.terminal
+        if terminal.interactive:
+            session = PromptSession(history=DummyHistory())
+
+            async def read():
+                return await session.prompt_async(f"{self.name}> ", default=self.draft)
+        else:
+            # A daemon reader allows Windows to exit while stdin is blocked.
+            queue = asyncio.Queue()
+            loop = asyncio.get_running_loop()
+            stopped = threading.Event()
+
+            def feed():
+                for raw in sys.stdin:
+                    if stopped.is_set():
+                        return
+                    try:
+                        loop.call_soon_threadsafe(queue.put_nowait, raw.rstrip("\r\n"))
+                    except RuntimeError:
+                        return
+                if not stopped.is_set():
+                    with contextlib.suppress(RuntimeError):
+                        loop.call_soon_threadsafe(queue.put_nowait, None)
+
+            threading.Thread(target=feed, daemon=True).start()
+
+            async def read():
+                value = await queue.get()
+                if value is None:
+                    raise EOFError
+                return value
+        try:
+            while not self.finished.is_set():
+                try:
+                    text = safe_text(await read())
+                except (EOFError, KeyboardInterrupt):
+                    return
+                command = text.strip()
+                if not command:
+                    self.draft = ""
+                    continue
+                if command in {"/exit", "/quit"}:
+                    return
+                if command == "/help":
+                    terminal.say("/who  /clear  /exit")
+                elif command == "/who":
+                    names = [peer["name"] for sid, peer in self.peers.items()
+                             if sid in self.online and peer["online"]]
+                    terminal.say(f"Participants: {', '.join([self.name, *names])}")
+                elif command == "/clear":
+                    if terminal.interactive:
+                        sys.stdout.write("\x1b[2J\x1b[H")
+                        sys.stdout.flush()
+                elif command.startswith("/"):
+                    terminal.say("Unknown command. Use /help.")
+                elif len(text) > MAX_TEXT:
+                    self.draft = text
+                    terminal.say("Message limit: 2000 characters.")
+                else:
+                    self.draft = text
+                    if await self.send_message(text):
+                        self.draft = ""
+                        if not terminal.interactive:
+                            terminal.say(f"{self.name}> {text}")
+        finally:
+            if not terminal.interactive:
+                stopped.set()
+            self.finished.set()
+
+    async def run(self, url, create=False, code_to_show=None, ca=None):
+        kwargs = {}
+        if ca:
+            if not url.startswith("wss://"):
+                raise ValueError("--ca requires wss://.")
+            kwargs["ssl"] = ssl.create_default_context(cafile=ca)
+        input_task = None
+        stop_task = asyncio.create_task(self.finished.wait())
+        receiver = None
+        deadline = None
+        try:
+            while not self.finished.is_set():
+                if deadline is not None and time.monotonic() >= deadline:
+                    raise SessionError("Reconnect window expired. Start a new chat.")
+                timeout = 10 if deadline is None else min(10, max(0.1, deadline - time.monotonic()))
+                try:
+                    async with connect(url, compression=None, max_size=MAX_FRAME, max_queue=16,
+                                       open_timeout=timeout, ping_interval=5, ping_timeout=5,
+                                       close_timeout=1, proxy=None, **kwargs) as ws:
+                        action = "resume" if self.token else "create" if create else "join"
+                        hello = {"type": action, "room": self.keys.room, "session": self.session}
+                        if self.token:
+                            hello["token"] = self.token
+                        await ws.send(dumps(hello))
+                        remaining = 10 if deadline is None else min(10, max(0.1, deadline - time.monotonic()))
+                        reply = parse(await asyncio.wait_for(ws.recv(), remaining))
+                        if reply.get("type") == "error":
+                            if not isinstance(reply.get("code"), str):
+                                raise SessionError("Invalid server response.")
+                            messages = {
+                                "invalid_room": "Invalid or expired code.",
+                                "invalid_resume": "Session expired. Start a new chat.",
+                                "full": "This chat already has two participants.",
+                                "exists": "Create a new chat with a new code.",
+                                "busy": "Server is busy. Try again later.",
+                            }
+                            if reply.get("code") == "busy" and self.token:
+                                raise ConnectionError("Server busy.")
+                            raise SessionError(messages.get(reply.get("code"), "Unable to join chat."))
+                        if (reply.get("type") != "ready" or reply.get("version") != 2
+                                or not isinstance(reply.get("token"), str)
+                                or not re.fullmatch(r"[A-Za-z0-9_-]{43}", reply["token"])):
+                            raise SessionError("Incompatible server.")
+                        reconnected = self.token is not None
+                        self.token = reply["token"]
+                        self.ws = ws
+                        self.online = {self.session}
+                        self.peer_ready = False
+                        deadline = None
+                        if reconnected:
+                            self.terminal.say("Reconnected.")
+                        elif code_to_show:
+                            self.terminal.say(f"Code: {code_to_show}")
+                        await ws.send(dumps(self.packet("hello")))
+                        if input_task is None:
+                            input_task = asyncio.create_task(self.send_input())
+                        receiver = asyncio.create_task(self.receive(ws))
+                        try:
+                            done, _ = await asyncio.wait({receiver, input_task, stop_task},
+                                                         return_when=asyncio.FIRST_COMPLETED)
+                        except asyncio.CancelledError:
+                            with contextlib.suppress(ConnectionClosed, OSError):
+                                await ws.send(dumps({"type": "leave"}))
+                            raise
+                        if input_task in done:
+                            input_task.result()
+                        if self.finished.is_set():
+                            with contextlib.suppress(ConnectionClosed, OSError):
+                                await ws.send(dumps({"type": "leave"}))
+                            return
+                        receiver.result()
+                except (ConnectionClosed, ConnectionError, OSError, TimeoutError, asyncio.TimeoutError, InvalidHandshake) as error:
+                    if not self.token:
+                        raise
+                    if isinstance(error, ConnectionClosed) and error.rcvd and error.rcvd.code in {1008, 4001}:
+                        raise SessionError("Session ended. Start a new chat.") from error
+                    if isinstance(error, ssl.SSLCertVerificationError):
+                        raise
+                    if deadline is None:
+                        deadline = time.monotonic() + self.reconnect_seconds
+                        self.terminal.say("Disconnected. Reconnecting...")
+                finally:
+                    self.ws = None
+                    self.peer_ready = False
+                    self.online = {self.session}
+                    self.fail_pending()
+                    for peer in self.peers.values():
+                        peer["online"] = False
+                    if receiver:
+                        receiver.cancel()
+                        await asyncio.gather(receiver, return_exceptions=True)
+                        receiver = None
+                if deadline is not None:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        raise SessionError("Reconnect window expired. Start a new chat.")
+                    with contextlib.suppress(TimeoutError, asyncio.TimeoutError):
+                        await asyncio.wait_for(self.finished.wait(), min(1, remaining))
+        finally:
+            self.finished.set()
+            self.fail_pending()
+            for task in (input_task, receiver, stop_task):
+                if task:
+                    task.cancel()
+            await asyncio.gather(*(task for task in (input_task, receiver, stop_task) if task),
+                                 return_exceptions=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="dark-chat", description="Two-person encrypted terminal chat.")
+    parser.add_argument("--server", default=os.environ.get("DARK_CHAT_SERVER", DEFAULT_SERVER),
+                        help="Server address (defaults to the hosted relay)")
+    parser.add_argument("--name", help="Name (1-24 characters)")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--new", action="store_true", help="Create a chat and get an invite code")
+    mode.add_argument("--chat", action="store_true", help="Join a chat using its invite code")
+    parser.add_argument("--allow-insecure", action="store_true", help="Allow ws:// on a local network")
+    parser.add_argument("--ca", help="Private TLS CA certificate")
+    parser.add_argument("--version", action="version", version=__version__)
+    args = parser.parse_args()
+    terminal = Terminal()
+    try:
+        url = server_url(args.server, args.allow_insecure)
+        name = safe_text(args.name if args.name is not None else terminal.ask("Name: ")).strip()
+        if not 1 <= len(name) <= 24:
+            raise ValueError("Name must be 1-24 characters.")
+        code = os.environ.pop("DARK_CHAT_CODE", "").strip()
+        create = args.new
+        if not create and not args.chat and not code:
+            choice = terminal.ask("Create or join? [c/j]: ").lower()
+            if choice not in {"c", "j", ""}:
+                raise ValueError("Enter c to create or j to join.")
+            create = choice == "c"
+        if create:
+            code = new_code()
+        elif not code:
+            code = terminal.ask("Code: ", secret=True)
+        keys = room_keys(code)
+        stdout_context = patch_stdout() if terminal.interactive else contextlib.nullcontext()
+        with stdout_context:
+            asyncio.run(Chat(terminal, keys, name).run(url, create, code if create else None, args.ca))
+        terminal.say("Closed.")
+    except (KeyboardInterrupt, EOFError):
+        terminal.say("Closed.")
+    except SessionError as error:
+        terminal.say(str(error))
+        raise SystemExit(1) from None
+    except (ValueError, OSError, ConnectionClosed, ConnectionError, TimeoutError, asyncio.TimeoutError, InvalidHandshake) as error:
+        detail = str(error) if isinstance(error, ValueError) else type(error).__name__
+        terminal.say(f"Error: {detail}")
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    main()

dark_terminal_chat/protocol.py

@@ -0,0 +1,105 @@
+"""The encryption format is shared with the original Node.js client."""
+
+import base64
+import hashlib
+import json
+import re
+import secrets
+import unicodedata
+from dataclasses import dataclass
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+MAX_FRAME = 20_000
+MAX_TEXT = 2_000
+SESSION = re.compile(r"[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}\Z")
+
+
+def encode(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def decode(value: str) -> bytes:
+    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+
+
+def new_code() -> str:
+    return encode(secrets.token_bytes(32))
+
+
+@dataclass(frozen=True)
+class RoomKeys:
+    room: str
+    key: bytes
+
+
+def room_keys(code: str) -> RoomKeys:
+    if not re.fullmatch(r"[A-Za-z0-9_-]{43}", code):
+        raise ValueError("Enter the 43-character code from the chat creator.")
+    secret = decode(code)
+    if encode(secret) != code:
+        raise ValueError("Invalid code.")
+    room = hashlib.sha256(b"dark-terminal-room-v1:" + secret).hexdigest()
+    key = HKDF(algorithm=hashes.SHA256(), length=32, salt=b"dark-terminal-v1",
+               info=b"message-encryption").derive(secret)
+    return RoomKeys(room, key)
+
+
+def dumps(value: dict) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+
+
+def parse(raw: str | bytes) -> dict:
+    if not isinstance(raw, str) or len(raw.encode("utf-8")) > MAX_FRAME:
+        raise ValueError("Invalid packet.")
+    try:
+        value = json.loads(raw)
+    except (RecursionError, json.JSONDecodeError) as error:
+        raise ValueError("Invalid JSON.") from error
+    if not isinstance(value, dict):
+        raise ValueError("Packet must be an object.")
+    return value
+
+
+def valid_envelope(value: dict) -> bool:
+    return isinstance(value, dict) and value.get("type") == "message" and all(
+        isinstance(value.get(field), str) and re.fullmatch(pattern, value[field])
+        for field, pattern in (
+            ("iv", r"[A-Za-z0-9_-]{16}"),
+            ("tag", r"[A-Za-z0-9_-]{22}"),
+            ("body", r"[A-Za-z0-9_-]{1,16000}"),
+        )
+    )
+
+
+def encrypt(keys: RoomKeys, message: dict) -> dict:
+    iv = secrets.token_bytes(12)
+    encrypted = AESGCM(keys.key).encrypt(iv, dumps(message).encode("utf-8"), keys.room.encode())
+    return {"type": "message", "iv": encode(iv), "body": encode(encrypted[:-16]),
+            "tag": encode(encrypted[-16:])}
+
+
+def decrypt(keys: RoomKeys, envelope: dict) -> dict:
+    if not valid_envelope(envelope):
+        raise ValueError("Invalid encrypted packet.")
+    raw = AESGCM(keys.key).decrypt(decode(envelope["iv"]),
+                                  decode(envelope["body"]) + decode(envelope["tag"]), keys.room.encode())
+    return parse(raw.decode("utf-8"))
+
+
+def safe_text(value: str) -> str:
+    return "".join(char for char in value if unicodedata.category(char) not in {"Cc", "Cf", "Zl", "Zp", "Cs"})
+
+
+def valid_message(value: dict) -> bool:
+    return (
+        isinstance(value, dict)
+        and isinstance(value.get("kind"), str) and value["kind"] in {"hello", "chat", "ack"}
+        and isinstance(value.get("name"), str) and 1 <= len(value["name"]) <= 24
+        and isinstance(value.get("session"), str) and SESSION.fullmatch(value["session"]) is not None
+        and type(value.get("seq")) is int and 1 <= value["seq"] <= 2**53 - 1
+        and isinstance(value.get("text"), str) and len(value["text"]) <= MAX_TEXT
+        and (value["kind"] != "ack" or type(value.get("ack")) is int and 1 <= value["ack"] <= 2**53 - 1)
+    )

dark_terminal_chat/server.py

@@ -0,0 +1,247 @@
+"""Two-person WebSocket relay. Only room/session metadata lives in memory."""
+
+import argparse
+import asyncio
+import logging
+import os
+import re
+import secrets
+import signal
+import time
+from dataclasses import dataclass, field
+from http import HTTPStatus
+from urllib.parse import urlsplit
+
+from websockets.asyncio.server import serve
+from websockets.exceptions import ConnectionClosed
+
+from . import __version__
+from .protocol import MAX_FRAME, SESSION, dumps, new_code, parse, valid_envelope
+
+RECONNECT_SECONDS = 60
+
+
+@dataclass
+class Participant:
+    socket: object
+    token: str = field(default_factory=new_code)
+    expiry: object = None
+
+
+@dataclass
+class Room:
+    participants: dict = field(default_factory=dict)
+
+
+class Relay:
+    def __init__(self, max_clients=128, reconnect_seconds=RECONNECT_SECONDS):
+        self.rooms = {}
+        self.clients = set()
+        self.max_clients = max_clients
+        self.reconnect_seconds = reconnect_seconds
+        self.tasks = set()
+
+    @staticmethod
+    def http_request(connection, request):
+        path = urlsplit(request.path).path.rstrip("/") or "/"
+        if path == "/health":
+            response = connection.respond(HTTPStatus.OK, '{"status":"ok"}\n')
+            response.headers["Content-Type"] = "application/json"
+            response.headers["Cache-Control"] = "no-store"
+            return response
+        if path not in {"/", "/ws"}:
+            return connection.respond(HTTPStatus.NOT_FOUND, "Not found\n")
+        if request.headers.get("Upgrade", "").lower() != "websocket":
+            return connection.respond(HTTPStatus.OK, "Chat server is running.\n")
+        return None
+
+    async def send(self, ws, frame):
+        try:
+            await asyncio.wait_for(ws.send(dumps(frame)), timeout=3)
+            return True
+        except (ConnectionClosed, TimeoutError, asyncio.TimeoutError):
+            await ws.close(code=1013, reason="Connection lost")
+            return False
+
+    async def reject(self, ws, code, message):
+        await self.send(ws, {"type": "error", "code": code, "message": message})
+        await ws.close(code=1013 if code == "busy" else 1008, reason=message)
+
+    async def presence(self, room_id):
+        room = self.rooms.get(room_id)
+        if room:
+            online = {sid: peer.socket for sid, peer in room.participants.items() if peer.socket is not None}
+            frame = {"type": "presence", "sessions": list(online), "reserved": list(room.participants)}
+            await asyncio.gather(*(self.send(ws, frame) for ws in online.values()))
+
+    def expire(self, room_id, session, participant):
+        room = self.rooms.get(room_id)
+        if not room or room.participants.get(session) is not participant or participant.socket is not None:
+            return
+        room.participants.pop(session)
+        if not room.participants:
+            self.rooms.pop(room_id)
+        else:
+            task = asyncio.create_task(self.presence(room_id))
+            self.tasks.add(task)
+            task.add_done_callback(self.tasks.discard)
+
+    def close(self):
+        for room in self.rooms.values():
+            for peer in room.participants.values():
+                if peer.expiry:
+                    peer.expiry.cancel()
+        for task in self.tasks:
+            task.cancel()
+        self.rooms.clear()
+
+    async def handler(self, ws):
+        if len(self.clients) >= self.max_clients:
+            await self.reject(ws, "busy", "Server is busy. Try again later.")
+            return
+        self.clients.add(ws)
+        room_id = session = participant = None
+        left = False
+        try:
+            frame = parse(await asyncio.wait_for(ws.recv(), timeout=10))
+            room_id, session, action = frame.get("room"), frame.get("session"), frame.get("type")
+            if (not isinstance(action, str) or action not in {"create", "join", "resume"}
+                    or not isinstance(room_id, str) or not re.fullmatch(r"[a-f0-9]{64}", room_id)
+                    or not isinstance(session, str) or not SESSION.fullmatch(session)):
+                raise ValueError("Invalid handshake")
+            room = self.rooms.get(room_id)
+            if action == "create":
+                if room:
+                    await self.reject(ws, "exists", "Create a new chat with a new code.")
+                    return
+                if len(self.rooms) >= self.max_clients:
+                    await self.reject(ws, "busy", "Server is busy. Try again later.")
+                    return
+                room = Room()
+                self.rooms[room_id] = room
+            elif not room:
+                await self.reject(ws, "invalid_room", "Invalid or expired code.")
+                return
+
+            if action == "resume":
+                participant = room.participants.get(session)
+                token = frame.get("token")
+                if (not participant or not isinstance(token, str)
+                        or not re.fullmatch(r"[A-Za-z0-9_-]{43}", token)
+                        or not secrets.compare_digest(token, participant.token)):
+                    participant = None
+                    await self.reject(ws, "invalid_resume", "Session expired. Create a new chat.")
+                    return
+                old_socket = participant.socket
+                participant.socket = ws
+                if participant.expiry:
+                    participant.expiry.cancel()
+                    participant.expiry = None
+                if old_socket is not None and old_socket is not ws:
+                    await old_socket.close(code=4001, reason="Connection replaced")
+            else:
+                if len(room.participants) >= 2:
+                    await self.reject(ws, "full", "This chat already has two participants.")
+                    return
+                if session in room.participants:
+                    await self.reject(ws, "invalid_resume", "Session already exists.")
+                    return
+                participant = Participant(ws)
+                room.participants[session] = participant
+
+            await self.send(ws, {"type": "ready", "version": 2, "token": participant.token})
+            await self.presence(room_id)
+            window, budget = time.monotonic(), 40
+            async for raw in ws:
+                if participant.socket is not ws:
+                    break
+                if time.monotonic() - window >= 10:
+                    window, budget = time.monotonic(), 40
+                budget -= 1
+                if budget < 0:
+                    left = True
+                    await ws.close(code=1008, reason="Rate limit exceeded")
+                    break
+                frame = parse(raw)
+                if frame.get("type") == "leave":
+                    left = True
+                    await ws.close(code=1000, reason="Left chat")
+                    break
+                message_id, receipt = frame.get("id"), frame.get("receipt", False)
+                if (not valid_envelope(frame) or type(message_id) is not int
+                        or not 1 <= message_id <= 2**53 - 1 or type(receipt) is not bool):
+                    left = True
+                    raise ValueError("Invalid message")
+                room = self.rooms.get(room_id)
+                target = next((peer.socket for sid, peer in room.participants.items()
+                               if sid != session and peer.socket is not None), None) if room else None
+                outgoing = {key: frame[key] for key in ("type", "iv", "body", "tag", "id")}
+                outgoing["sender"] = session
+                delivered = target is not None and await self.send(target, outgoing)
+                if receipt and not delivered:
+                    await self.send(ws, {"type": "not_delivered", "id": message_id})
+        except ConnectionClosed as error:
+            if error.rcvd and error.rcvd.code == 1008:
+                left = True
+        except (ValueError, TimeoutError, asyncio.TimeoutError, UnicodeError):
+            left = True
+            await ws.close(code=1008, reason="Invalid protocol")
+        finally:
+            self.clients.discard(ws)
+            room = self.rooms.get(room_id) if isinstance(room_id, str) else None
+            if room and participant and participant.socket is ws:
+                participant.socket = None
+                if left:
+                    room.participants.pop(session, None)
+                    if not room.participants:
+                        self.rooms.pop(room_id, None)
+                else:
+                    participant.expiry = asyncio.get_running_loop().call_later(
+                        self.reconnect_seconds, self.expire, room_id, session, participant)
+                await self.presence(room_id)
+
+    def serve(self, host, port, **kwargs):
+        return serve(self.handler, host, port, process_request=self.http_request,
+                     origins=[None], compression=None, max_size=MAX_FRAME,
+                     max_queue=16, write_limit=32768, ping_interval=5,
+                     ping_timeout=5, close_timeout=3, server_header=None, **kwargs)
+
+
+async def run(args):
+    relay = Relay(args.max_clients)
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, stop.set)
+        except NotImplementedError:
+            pass
+    try:
+        async with relay.serve(args.host, args.port) as server:
+            address = server.sockets[0].getsockname()
+            print(f"Listening on {address[0]}:{address[1]}", flush=True)
+            await stop.wait()
+    finally:
+        relay.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Two-person encrypted chat server.")
+    parser.add_argument("--host", default=os.environ.get("IP", "127.0.0.1"))
+    parser.add_argument("--port", type=int, default=os.environ.get("PORT", "8080"))
+    parser.add_argument("--max-clients", type=int, default=128)
+    parser.add_argument("--version", action="version", version=__version__)
+    args = parser.parse_args()
+    if not 1 <= args.port <= 65535 or not 1 <= args.max_clients <= 1024:
+        parser.error("Port must be 1–65535; max-clients must be 1–1024.")
+    logging.basicConfig(level=logging.WARNING)
+    try:
+        asyncio.run(run(args))
+    except KeyboardInterrupt:
+        pass
+    except OSError as error:
+        parser.exit(1, f"Server error: {error.strerror or type(error).__name__}\n")
+
+
+if __name__ == "__main__":
+    main()