Add telnet server with 60pps paced output

Add gambaterm-telnet server using telnetlib3, with a simplified
architecture compared to the previous NUL-padding approach. Frame
output is paced at 60 packets per second via an asyncio forwarding
task combined with TCP_NODELAY, producing smooth rendering without
complex bandwidth estimation.

- TelnetTerminal blessed subclass (mirrors SSHTerminal pattern)
- Kitty keyboard protocol required for both SSH and telnet
- Per-user save state directories (SHA-256 hashed usernames)
- NAWS terminal resize support
- Connection stats logging and idle timeout
- --max-players and --robot-check support via telnetlib3 guard shells

Author: jquast

README.md

@@ -96,7 +96,42 @@ Optional arguments:
 SSH server
 ----------
 
-It is possible to serve the emulation through SSH. Clients with terminals supporting the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) can send input directly without X11 forwarding. Otherwise, X11 forwarding (`ssh -X`) can be used as a fallback. Use `gambaterm-ssh --help` for more information. 24-bit color is always true over ssh.
+It is possible to serve the emulation through SSH. Clients must use a terminal that supports the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), or use X11 forwarding (`ssh -X`) as a fallback. Use `gambaterm-ssh --help` for more information. 24-bit color is always assumed over SSH. Audio is not available over SSH.
+
+```shell
+$ gambaterm-ssh --password 123 myrom.gbc
+$ gambaterm-ssh --password 123 --bind 0.0.0.0 --port 8022 myrom.gbc  # Listen on all interfaces
+```
+
+Connect with ssh client:
+
+``shell
+ssh localhost -p 8022
+```
+
+Suggest removing keystroke timing obfuscation for better button latency:
+
+```shell
+ssh -o ObscureKeystrokeTiming=no example.com -p 8022
+```
+
+Telnet server
+-------------
+
+The emulator can also be served over telnet, requiring no authentication or SSH keys:
+
+```shell
+$ gambaterm-telnet myrom.gbc
+$ gambaterm-telnet --bind 0.0.0.0 --port 8023 myrom.gbc  # listen on all interfaces
+```
+
+Connect with any telnet client:
+
+```shell
+$ telnet localhost 8023
+```
+
+Clients must use a terminal that supports the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) -- connections without it are rejected. Use `--max-players N` to limit concurrent connections. 24-bit color is always assumed unless the client reports `TERM=ansi` (16 colors). Audio is not available over SSH or telnet.
 
 
 Terminal support
@@ -221,6 +256,7 @@ Here is the list of the dependencies used in this project, all great open source
 - [xlib](https://github.com/python-xlib/python-xlib)/[pynput](https://github.com/moses-palmer/pynput) - Getting keyboard inputs
 - [pygame](https://github.com/pygame/pygame) - Getting game controller inputs
 - [asyncssh](https://github.com/ronf/asyncssh) - Running the SSH server
+- [telnetlib3](https://github.com/jquast/telnetlib3) - Running the telnet server
 
 
 Contact

gambaterm/colors.py

@@ -28,6 +28,21 @@ class ColorMode(IntEnum):
     HAS_24_BIT_COLOR = 4
 
 
+def detect_color_mode(env: dict[str, str]) -> ColorMode:
+    """Detect color support from environment variables.
+
+    Assumes 24-bit color for all terminals except TERM='ansi' which
+    gets 16 colors.
+
+    :param env: environment dict with keys like TERM
+    :returns: detected :class:`ColorMode`
+    """
+    term_val = env.get("TERM", "").lower()
+    if term_val == "ansi":
+        return ColorMode.HAS_4_BIT_COLOR
+    return ColorMode.HAS_24_BIT_COLOR
+
+
 def detect_local_color_mode(term: Terminal) -> ColorMode:
     """Detect the color mode of the local terminal using blessed."""
     n = term.number_of_colors

gambaterm/ssh.py

@@ -2,6 +2,7 @@
 
 import os
 import time
+import hashlib
 import asyncio
 import argparse
 import traceback
@@ -107,12 +108,13 @@ async def ssh_process_handler(process: SSHServerProcess[str]) -> int:
         console_cls.add_console_arguments(parser)
         namespace = parser.parse_args(command.split(), namespace)
 
-    # Manage save directory
+    # Manage save directory — hash username to prevent path traversal
     if "save_directory" in namespace.__dict__:
+        safe_name = hashlib.sha256(username.encode("utf-8")).hexdigest()[:16]
         save_directory = (
             None
             if getattr(namespace, "input_file", False)
-            else Path("ssh_save") / username
+            else Path("ssh_save") / safe_name
         )
         setattr(namespace, "save_directory", save_directory)
 
@@ -197,13 +199,8 @@ def ssh_terminal_handler(
     else:
         assert False
 
-    # Default to 24-bit color since the vast majority of modern terminals
-    # support it.
-    color_mode = (
-        app_config.color_mode
-        if app_config.color_mode is not None
-        else ColorMode.HAS_24_BIT_COLOR
-    )
+    # Kitty keyboard protocol implies 24-bit color support
+    color_mode = app_config.color_mode or ColorMode.HAS_24_BIT_COLOR
 
     print(
         f"[Terminal Info] {username}: {terminal_type}, {input_source}, {term.width}x{term.height}"