nullgate 1.1.0__py3-none-any.whl

nullgate/wsroute.py

@@ -0,0 +1,483 @@
+#!/usr/bin/env python3
+"""Upterm WSS ingress for the Nullgate upterm transport.
+
+Nullgate connects outbound to an Upterm relay over WebSocket, registers a
+session via Upterm's SSH protocol, and reverse-forwards incoming connections back
+to the local AsyncSSH server.
+
+The client connects through Nullgate's ``upterm-proxy`` subcommand, which bridges
+stdin/stdout to the Upterm relay over WebSocket.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import contextlib
+import json
+import os
+import shlex
+import signal
+import socket
+import struct
+import sys
+from pathlib import Path
+from urllib.parse import quote, urlsplit, urlunsplit
+
+import asyncssh
+import websockets
+
+from nullgate.account import current_username, ensure_username_environment
+from nullgate.ingress import ensure_key
+
+DEFAULT_ENDPOINT = "wss://uptermd.upterm.dev"
+CHUNK = 65536
+WS_OPTIONS = dict(
+    max_size=None,
+    ping_interval=20,
+    ping_timeout=20,
+    close_timeout=5,
+)
+
+# Uptermd routes WebSocket connections by these exact HTTP header values. They
+# are full SSH identification strings, unlike AsyncSSH's ``client_version``
+# option below, which expects the value without the ``SSH-2.0-`` prefix.
+CLIENT_CLIENT_VERSION = "SSH-2.0-upterm-client-client"
+HOST_CLIENT_VERSION = "SSH-2.0-upterm-host-client"
+SESSION_REQUEST = b"upterm-create-session@upterm.dev"
+MSG_REQUEST_SUCCESS = 81
+
+
+def log(message: str) -> None:
+    sys.stderr.write("nullgate-wsroute: " + message + "\n")
+    sys.stderr.flush()
+
+
+def _encode_varint(value: int) -> bytes:
+    parts = bytearray()
+    while True:
+        towrite = value & 0x7F
+        value >>= 7
+        if value:
+            parts.append(towrite | 0x80)
+        else:
+            parts.append(towrite)
+            break
+    return bytes(parts)
+
+
+def _decode_varint(data: bytes, offset: int = 0) -> tuple[int, int]:
+    value = 0
+    shift = 0
+    while offset < len(data):
+        byte = data[offset]
+        offset += 1
+        value |= (byte & 0x7F) << shift
+        if not (byte & 0x80):
+            return value, offset
+        shift += 7
+    raise ValueError("Truncated protobuf varint")
+
+
+def _encode_bytes_field(field_number: int, data: bytes) -> bytes:
+    tag = _encode_varint((field_number << 3) | 2)
+    return tag + _encode_varint(len(data)) + data
+
+
+def _encode_string_field(field_number: int, text: str) -> bytes:
+    return _encode_bytes_field(field_number, text.encode())
+
+
+def encode_create_session(
+    status: str,
+    host_keys: list[bytes],
+    authorized_keys: list[bytes],
+) -> bytes:
+    """Encode an Upterm CreateSessionRequest protobuf message."""
+    chunks: list[bytes] = []
+    if status:
+        chunks.append(_encode_string_field(1, status))
+    for host_key in host_keys:
+        chunks.append(_encode_bytes_field(2, host_key))
+    for authorized_key in authorized_keys:
+        chunks.append(_encode_bytes_field(3, authorized_key))
+    return b"".join(chunks)
+
+
+def decode_create_session_response(data: bytes) -> dict[str, str]:
+    """Decode an Upterm CreateSessionResponse protobuf message."""
+    offset = 0
+    session_id = ""
+    node_addr = ""
+    user = ""
+    while offset < len(data):
+        tag, offset = _decode_varint(data, offset)
+        field_number = tag >> 3
+        wire_type = tag & 0x07
+        if wire_type == 0:
+            _, offset = _decode_varint(data, offset)
+        elif wire_type == 2:
+            length, offset = _decode_varint(data, offset)
+            if offset + length > len(data):
+                raise ValueError("Truncated protobuf length-delimited field")
+            field_data = data[offset : offset + length]
+            offset += length
+            if field_number == 1:
+                session_id = field_data.decode(errors="replace")
+            elif field_number == 2:
+                node_addr = field_data.decode(errors="replace")
+            elif field_number == 3:
+                user = field_data.decode(errors="replace")
+        else:
+            raise ValueError(f"Unsupported protobuf wire type: {wire_type}")
+    return {"session_id": session_id, "node_addr": node_addr, "ssh_user": user}
+
+
+def _clean_websocket_url(url: str) -> tuple[str, str, str]:
+    parsed = urlsplit(url)
+    if parsed.scheme not in ("ws", "wss") or not parsed.hostname:
+        raise ValueError(f"Invalid Upterm WebSocket URL: {url}")
+    username = parsed.username or ""
+    password = parsed.password or ""
+    host = parsed.hostname
+    if parsed.port:
+        host += f":{parsed.port}"
+    clean = urlunsplit((parsed.scheme, host, parsed.path or "/", parsed.query, ""))
+    return clean, username, password
+
+
+def websocket_headers(username: str, password: str, *, client: bool) -> dict[str, str]:
+    credentials = base64.b64encode(f"{username}:{password}".encode()).decode()
+    return {
+        "Authorization": f"Basic {credentials}",
+        "Upterm-Client-Version": (
+            CLIENT_CLIENT_VERSION if client else HOST_CLIENT_VERSION
+        ),
+    }
+
+
+def client_proxy_url(endpoint: str, session_id: str, node_addr: str) -> str:
+    clean, _, _ = _clean_websocket_url(endpoint)
+    parsed = urlsplit(clean)
+    encoded_node = base64.urlsafe_b64encode(node_addr.encode()).decode()
+    userinfo = f"{quote(session_id, safe='')}:{quote(encoded_node, safe='')}@"
+    return urlunsplit(
+        (parsed.scheme, userinfo + parsed.netloc, parsed.path, parsed.query, "")
+    )
+
+
+def endpoint_host(endpoint: str) -> str:
+    clean, _, _ = _clean_websocket_url(endpoint)
+    return urlsplit(clean).hostname or "uptermd.upterm.dev"
+
+
+def session_proxy_url(session: dict[str, str]) -> str:
+    return client_proxy_url(
+        session["endpoint"], session["session_id"], session["node_addr"]
+    )
+
+
+def ssh_proxy_url(session: dict[str, str]) -> str:
+    """Escape an Upterm URL for OpenSSH ProxyCommand percent expansion."""
+    return session_proxy_url(session).replace("%", "%%")
+
+
+def read_session(path: Path) -> dict[str, str] | None:
+    try:
+        value = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return None
+    required = ("session_id", "node_addr", "ssh_user", "endpoint")
+    if not all(isinstance(value.get(key), str) and value[key] for key in required):
+        return None
+    return value
+
+
+def _write_json_atomic(path: Path, value: dict[str, str]) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    temporary.write_text(json.dumps(value, separators=(",", ":")) + "\n")
+    temporary.chmod(0o600)
+    os.replace(temporary, path)
+
+
+def _write_bytes_atomic(path: Path, value: bytes) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    temporary.write_bytes(value)
+    temporary.chmod(0o600)
+    os.replace(temporary, path)
+
+
+def _authorized_public_keys(path: Path) -> list[bytes]:
+    if not path.is_file():
+        return []
+    keys: list[bytes] = []
+    for raw_line in path.read_text(errors="replace").splitlines():
+        try:
+            fields = shlex.split(raw_line, comments=True)
+        except ValueError:
+            continue
+        for index in range(max(0, len(fields) - 1)):
+            try:
+                key = asyncssh.import_public_key(
+                    f"{fields[index]} {fields[index + 1]}"
+                )
+            except (asyncssh.KeyImportError, ValueError):
+                continue
+            keys.append(key.export_public_key())
+            break
+    return keys
+
+
+class WebSocketSocketBridge:
+    """Expose a WebSocket byte stream as one side of a socketpair."""
+
+    def __init__(self, websocket, ssh_socket: socket.socket, pump_socket: socket.socket):
+        self.websocket = websocket
+        self.ssh_socket = ssh_socket
+        self.pump_socket = pump_socket
+        self.tasks: list[asyncio.Task] = []
+
+    @classmethod
+    async def open(cls, url: str, headers: dict[str, str]) -> "WebSocketSocketBridge":
+        websocket = await websockets.connect(
+            url, additional_headers=headers, **WS_OPTIONS
+        )
+        ssh_socket, pump_socket = socket.socketpair()
+        ssh_socket.setblocking(False)
+        pump_socket.setblocking(False)
+        bridge = cls(websocket, ssh_socket, pump_socket)
+        bridge.tasks = [
+            asyncio.create_task(bridge._socket_to_websocket()),
+            asyncio.create_task(bridge._websocket_to_socket()),
+        ]
+        return bridge
+
+    async def _socket_to_websocket(self) -> None:
+        loop = asyncio.get_running_loop()
+        try:
+            while data := await loop.sock_recv(self.pump_socket, CHUNK):
+                await self.websocket.send(data)
+        except (OSError, websockets.ConnectionClosed):
+            pass
+        finally:
+            with contextlib.suppress(Exception):
+                await self.websocket.close()
+
+    async def _websocket_to_socket(self) -> None:
+        loop = asyncio.get_running_loop()
+        try:
+            async for message in self.websocket:
+                if isinstance(message, str):
+                    message = message.encode()
+                await loop.sock_sendall(self.pump_socket, message)
+        except (OSError, websockets.ConnectionClosed):
+            pass
+        finally:
+            with contextlib.suppress(OSError):
+                self.pump_socket.shutdown(socket.SHUT_RDWR)
+
+    async def close(self) -> None:
+        with contextlib.suppress(Exception):
+            await self.websocket.close()
+        for sock in (self.ssh_socket, self.pump_socket):
+            with contextlib.suppress(OSError):
+                sock.close()
+        for task in self.tasks:
+            task.cancel()
+        for task in self.tasks:
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await task
+
+
+async def request_session(connection, payload: bytes) -> dict[str, str]:
+    method = getattr(connection, "_make_global_request", None)
+    if method is None:
+        raise RuntimeError("AsyncSSH no longer supports Upterm global requests")
+    packet_type, packet = await method(SESSION_REQUEST, payload)
+    if packet_type != MSG_REQUEST_SUCCESS:
+        raise RuntimeError("Upterm rejected the session request")
+    return decode_create_session_response(packet.get_remaining_payload())
+
+
+async def run_origin_once(args: argparse.Namespace) -> bool:
+    endpoint, _, _ = _clean_websocket_url(args.endpoint)
+    ensure_username_environment(args.username)
+    ensure_key(args.key)
+    control_key = asyncssh.read_private_key(str(args.key))
+    host_key = asyncssh.read_private_key(str(args.host_key))
+    client_keys = [] if args.accept else _authorized_public_keys(args.authorized_keys)
+    if not args.accept and not client_keys:
+        raise ValueError("Upterm requires an authorized key unless --accept is set")
+
+    bridge = await WebSocketSocketBridge.open(
+        endpoint, websocket_headers(args.username, "", client=False)
+    )
+    connection = None
+    listener = None
+    try:
+        connection = await asyncssh.connect(
+            endpoint_host(endpoint),
+            sock=bridge.ssh_socket,
+            username=args.username,
+            client_keys=[control_key],
+            known_hosts=None,
+            client_version="upterm-host-client",
+            keepalive_interval=10,
+            keepalive_count_max=3,
+            login_timeout=20,
+        )
+        relay_key = connection.get_server_host_key()
+        if relay_key is None:
+            raise RuntimeError("Upterm relay did not present an SSH host key")
+        _write_bytes_atomic(args.ca_keys, relay_key.export_public_key())
+
+        payload = encode_create_session(
+            args.username,
+            [host_key.export_public_key()],
+            client_keys,
+        )
+        session = await request_session(connection, payload)
+        listener = await connection.forward_remote_path_to_port(
+            session["session_id"], args.local_host, args.local_port
+        )
+        published = {**session, "endpoint": endpoint}
+        _write_json_atomic(args.session_file, published)
+        proxy = session_proxy_url(published)
+        log(f"session ready: ssh {session['ssh_user']}@{endpoint_host(endpoint)}")
+        log(f"client proxy: nullgate upterm-proxy {proxy}")
+        await connection.wait_closed()
+        return True
+    finally:
+        args.session_file.unlink(missing_ok=True)
+        if listener is not None:
+            listener.close()
+            await listener.wait_closed()
+        if connection is not None:
+            connection.close()
+            await connection.wait_closed()
+        await bridge.close()
+
+
+async def run_origin(args: argparse.Namespace) -> None:
+    stopped = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for signum in (signal.SIGINT, signal.SIGTERM):
+        with contextlib.suppress(NotImplementedError):
+            loop.add_signal_handler(signum, stopped.set)
+    delay = 1
+    args.session_file.unlink(missing_ok=True)
+    while not stopped.is_set():
+        origin = asyncio.create_task(run_origin_once(args))
+        stopping = asyncio.create_task(stopped.wait())
+        try:
+            done, _ = await asyncio.wait(
+                (origin, stopping), return_when=asyncio.FIRST_COMPLETED
+            )
+            if stopping in done:
+                origin.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await origin
+                break
+            stopping.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await stopping
+            if not await origin:
+                raise RuntimeError("Upterm connection ended before publishing a session")
+            delay = 1
+        except asyncio.CancelledError:
+            origin.cancel()
+            stopping.cancel()
+            raise
+        except Exception as error:  # noqa: BLE001 - tunnel supervisor
+            stopping.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await stopping
+            log(f"connection ended: {error!r}; retrying in {delay}s")
+            try:
+                await asyncio.wait_for(stopped.wait(), timeout=delay)
+            except (TimeoutError, asyncio.TimeoutError):
+                pass
+            delay = min(delay * 2, 30)
+
+
+async def run_client(url: str) -> None:
+    endpoint, session_id, encoded_node = _clean_websocket_url(url)
+    if not session_id:
+        raise ValueError("Upterm proxy URL is missing its session ID")
+    async with websockets.connect(
+        endpoint,
+        additional_headers=websocket_headers(session_id, encoded_node, client=True),
+        **WS_OPTIONS,
+    ) as websocket:
+        loop = asyncio.get_running_loop()
+
+        async def stdin_to_websocket() -> None:
+            try:
+                while data := await loop.run_in_executor(None, os.read, 0, CHUNK):
+                    await websocket.send(data)
+            except websockets.ConnectionClosed:
+                pass
+
+        async def websocket_to_stdout() -> None:
+            try:
+                async for message in websocket:
+                    if isinstance(message, str):
+                        message = message.encode()
+                    view = memoryview(message)
+                    while view:
+                        view = view[os.write(1, view) :]
+            except (websockets.ConnectionClosed, BrokenPipeError):
+                pass
+
+        tasks = [
+            asyncio.create_task(stdin_to_websocket()),
+            asyncio.create_task(websocket_to_stdout()),
+        ]
+        done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        for task in pending:
+            task.cancel()
+        for task in pending:
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        for task in done:
+            with contextlib.suppress(websockets.ConnectionClosed, BrokenPipeError):
+                task.result()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="mode", required=True)
+    origin = sub.add_parser("origin")
+    origin.add_argument("--endpoint", default=DEFAULT_ENDPOINT)
+    origin.add_argument("--local-host", default="127.0.0.1")
+    origin.add_argument("--local-port", type=int, required=True)
+    origin.add_argument("--username", default=current_username())
+    origin.add_argument("--key", type=Path, required=True)
+    origin.add_argument("--host-key", type=Path, required=True)
+    origin.add_argument("--authorized-keys", type=Path, required=True)
+    origin.add_argument("--ca-keys", type=Path, required=True)
+    origin.add_argument("--session-file", type=Path, required=True)
+    origin.add_argument("--accept", action="store_true")
+    client = sub.add_parser("client")
+    client.add_argument("url")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.mode == "origin":
+            asyncio.run(run_origin(args))
+        else:
+            asyncio.run(run_client(args.url))
+    except KeyboardInterrupt:  # pragma: no cover
+        return 130
+    except (OSError, ValueError, RuntimeError, asyncssh.Error) as error:
+        print(f"nullgate-wsroute: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nullgate-1.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: nullgate
+Version: 1.1.0
+Summary: Temporary SSH, SFTP, and SCP access to ephemeral workspaces
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: asyncssh==2.24.0
+Requires-Dist: cryptography>=39
+Requires-Dist: websockets
+Dynamic: license-file

nullgate-1.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+nullgate/__init__.py,sha256=LGVQyDsWifdACo7qztwb8RWWHds1E7uQ-ZqD8SAjyw4,22
+nullgate/account.py,sha256=TaUkEfUhtoZebDlmUMSYSy_j8Lwd70QmvdTgM-GHV5g,713
+nullgate/bridge.py,sha256=wOsyZQAMVpGF69x0YqTeindlt7aVdjgkNG6vRo_504A,5161
+nullgate/client_config.py,sha256=BHLn3E2f7j8eJINPH6MYxlTv36dgY1Qkzh0tTwNDZkQ,3705
+nullgate/commands.py,sha256=vhkKXINvVLR9_9APljPgfkSe49FWKGzIYqEJoiUS8yQ,4846
+nullgate/gateway.py,sha256=O_c2yuWxtcn6KpQ5SxZbtSRMhGfvgA-QnkpF-jgPnIM,32410
+nullgate/ingress.py,sha256=pMcVcAZ-LyhH5U0iMx6wurexigMGWCxKcNQAHINAlvo,7040
+nullgate/runtime.py,sha256=xV9fDUSIoSY51bqXM-gxIcdoqBv_PJY6SDQu4qXXtQ4,6959
+nullgate/session.py,sha256=YV2xXwWAVy-al6OddG-wmOrVEVTkV6iEh5vtLM_EgMU,16873
+nullgate/transports.py,sha256=lyDQ9G0HMrXwMRM2NjLFNqWa1IG5IhzX_eghC0f7w5k,12711
+nullgate/wsroute.py,sha256=rWAVePLSBH1LLNgzuIk7KM4euO06S9T2v3WcsKhI15c,17351
+nullgate-1.1.0.dist-info/licenses/LICENSE,sha256=XTtNEUzWx0pTKaR1SeI8HmOd6REwQNBqk4GutP5vpYo,1061
+nullgate-1.1.0.dist-info/METADATA,sha256=Hc33AibtGpaqaw3pFWxnTPBvGO83siITnn4IcByKR8M,279
+nullgate-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nullgate-1.1.0.dist-info/entry_points.txt,sha256=ievLSlQlI80j6--FPOmePbO1aCPPNIObGiMW8S9X1gQ,52
+nullgate-1.1.0.dist-info/top_level.txt,sha256=3Q1qRFLv7W5b4CFGRbkBHqrUx6Dos2iiiTksU9BcEWI,9
+nullgate-1.1.0.dist-info/RECORD,,

nullgate-1.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
+

nullgate-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nullgate = nullgate.commands:main

nullgate-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lars
+
+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.

nullgate-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nullgate