nullgate 1.1.0__py3-none-any.whl

nullgate/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.1.0"

nullgate/account.py

@@ -0,0 +1,23 @@
+"""Current-account helpers for hosts without a passwd database entry."""
+
+from __future__ import annotations
+
+import getpass
+import os
+
+
+def current_username(default: str = "nullgate") -> str:
+    """Return the current username, or a stable fallback for synthetic UIDs."""
+    try:
+        return getpass.getuser() or default
+    except (KeyError, OSError):
+        return default
+
+
+def ensure_username_environment(username: str | None = None) -> str:
+    """Populate the account variables required by libraries such as AsyncSSH."""
+    resolved = username or current_username()
+    for name in ("USER", "LOGNAME"):
+        if not os.environ.get(name):
+            os.environ[name] = resolved
+    return resolved

nullgate/bridge.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Stdio/TCP <-> WebSocket bridge for the Nullgate cloudflare transport.
+
+Two modes pump a raw byte stream across a WebSocket relay (a Cloudflare Worker):
+
+  origin  Connects out to the relay and, on the first inbound byte, dials the
+          local SSH server, splicing the two. Loops to serve many sessions.
+  client  Connects out to the relay and splices it to stdin/stdout, so it can be
+          used as an ssh ProxyCommand.
+
+The relay pairs one "origin" and one "client" socket per tunnel id. The role
+is the final path segment of ``/relay/<session>/<role>``.
+
+Launched by the CLI as ``python -m nullgate.bridge`` for both the origin
+(remote) and client (ProxyCommand) roles; it needs the websockets package.
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+
+import websockets
+
+CHUNK = 65536
+CONNECT_KWARGS = dict(max_size=None, ping_interval=20, ping_timeout=20, close_timeout=5)
+
+
+def log(message):
+    sys.stderr.write("nullgate-bridge: " + message + "\n")
+    sys.stderr.flush()
+
+
+def role_url(base, role):
+    return base.rstrip("/") + "/" + role
+
+
+def _write_all(fd, data):
+    view = memoryview(data)
+    while view:
+        written = os.write(fd, view)
+        view = view[written:]
+
+
+async def _await_first_completed(*coros):
+    tasks = [asyncio.ensure_future(coro) for coro in coros]
+    done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+    for task in pending:
+        task.cancel()
+    for task in pending:
+        try:
+            await task
+        except (asyncio.CancelledError, Exception):  # noqa: BLE001 - draining only
+            pass
+    for task in done:
+        exc = task.exception()
+        if exc is not None:
+            raise exc
+
+
+async def run_client(base):
+    url = role_url(base, "client")
+    async with websockets.connect(url, **CONNECT_KWARGS) as ws:
+        loop = asyncio.get_event_loop()
+        stdin_fd = sys.stdin.fileno()
+
+        async def stdin_to_ws():
+            while True:
+                data = await loop.run_in_executor(None, os.read, stdin_fd, CHUNK)
+                if not data:
+                    break
+                await ws.send(data)
+
+        async def ws_to_stdout():
+            async for message in ws:
+                if isinstance(message, str):
+                    message = message.encode()
+                _write_all(1, message)
+
+        await _await_first_completed(stdin_to_ws(), ws_to_stdout())
+
+
+async def run_origin_once(base, host, port):
+    url = role_url(base, "origin")
+    async with websockets.connect(url, **CONNECT_KWARGS) as ws:
+        # Wait for the client's first byte before dialing the local server, so
+        # the server's SSH banner is never emitted into a peerless relay.
+        try:
+            first = await ws.recv()
+        except websockets.ConnectionClosed:
+            return
+        if isinstance(first, str):
+            first = first.encode()
+        reader, writer = await asyncio.open_connection(host, port)
+        writer.write(first)
+        await writer.drain()
+
+        async def tcp_to_ws():
+            while True:
+                data = await reader.read(CHUNK)
+                if not data:
+                    break
+                await ws.send(data)
+
+        async def ws_to_tcp():
+            async for message in ws:
+                if isinstance(message, str):
+                    message = message.encode()
+                writer.write(message)
+                await writer.drain()
+
+        try:
+            await _await_first_completed(tcp_to_ws(), ws_to_tcp())
+        finally:
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:  # noqa: BLE001 - best-effort teardown
+                pass
+
+
+async def run_origin(base, host, port):
+    delay = 1
+    while True:
+        try:
+            await run_origin_once(base, host, port)
+            delay = 1
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - keep the tunnel alive
+            log("origin session ended: " + repr(exc))
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, 30)
+            continue
+        await asyncio.sleep(0.5)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Nullgate WebSocket bridge")
+    sub = parser.add_subparsers(dest="mode", required=True)
+
+    client = sub.add_parser("client", help="stdio <-> relay (ssh ProxyCommand)")
+    client.add_argument("url", help="base relay URL, e.g. wss://host/relay/ID")
+
+    origin = sub.add_parser("origin", help="local SSH server <-> relay")
+    origin.add_argument("url", help="base relay URL, e.g. wss://host/relay/ID")
+    origin.add_argument("--host", default="127.0.0.1")
+    origin.add_argument("--port", type=int, required=True)
+
+    args = parser.parse_args(argv)
+    try:
+        if args.mode == "client":
+            asyncio.run(run_client(args.url))
+        else:
+            asyncio.run(run_origin(args.url, args.host, args.port))
+    except KeyboardInterrupt:  # pragma: no cover
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nullgate/client_config.py

@@ -0,0 +1,116 @@
+"""The ssh-config block for Nullgate.
+
+``ssh-config`` prints a ``Host`` block so plain ``ssh USER@HOST`` works on the
+connecting machine. With no HOST it prints the default ``Host *.srv.us`` block
+for the srv.us transport; with a HOST it prints a block for that host using the
+currently configured transport's ProxyCommand. ``--write`` appends it to
+~/.ssh/config (never prepends, which would drag any leading global keywords
+under the new Host block), is idempotent, chmods the file to 0600, and then runs
+``ssh -G`` to confirm the block actually took effect.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SRVUS_PROXY_COMMAND = (
+    "openssl s_client -quiet -no_ign_eof -verify_return_error "
+    "-verify_hostname %h -connect %h:443 -servername %h 2>/dev/null"
+)
+DEFAULT_HOST = "*.srv.us"
+
+
+def block(host: str, proxy_command: str) -> str:
+    """Build the ssh-config block for a host and ProxyCommand."""
+    return (
+        f"Host {host}\n"
+        f"  ProxyCommand {proxy_command}\n"
+        "  StrictHostKeyChecking no\n"
+        "  UserKnownHostsFile /dev/null\n"
+        "  LogLevel ERROR"
+    )
+
+
+def config_path() -> Path:
+    return Path(os.path.expanduser("~/.ssh/config"))
+
+
+def print_block(
+    host: str = DEFAULT_HOST, proxy_command: str = SRVUS_PROXY_COMMAND
+) -> None:
+    print(block(host, proxy_command))
+
+
+def write(
+    host: str = DEFAULT_HOST, proxy_command: str = SRVUS_PROXY_COMMAND
+) -> int:
+    config = config_path()
+    ssh_dir = config.parent
+    try:
+        ssh_dir.mkdir(parents=True, exist_ok=True)
+        ssh_dir.chmod(0o700)
+    except OSError:
+        _error(f"Unable to prepare {ssh_dir}")
+        return 1
+
+    try:
+        present = config.is_file() and any(
+            line.strip().startswith("Host " + host)
+            for line in config.read_text().splitlines()
+        )
+    except OSError:
+        present = False
+    if present:
+        print(f"Already present in {config}")
+    else:
+        # Appending never changes the meaning of existing lines, unlike
+        # prepending, which would pull any leading global keywords under this
+        # Host block.
+        try:
+            with open(config, "a") as handle:
+                if config.exists() and config.stat().st_size > 0:
+                    handle.write("\n")
+                handle.write(block(host, proxy_command) + "\n")
+            config.chmod(0o600)
+        except OSError as error:
+            _error(f"Unable to write {config}: {error}")
+            return 1
+        print(f"Added the {host} block to {config}")
+
+    # ssh takes the first value it finds for each keyword, so an earlier
+    # matching block wins. Ask ssh what it will actually do rather than assuming.
+    ssh = shutil.which("ssh")
+    if ssh:
+        probe = host.replace("*", "example")
+        try:
+            resolved = subprocess.run(
+                [ssh, "-G", probe],
+                capture_output=True,
+                text=True,
+                timeout=15,
+            ).stdout
+        except (OSError, subprocess.SubprocessError):
+            return 0
+        proxycommand = next(
+            (
+                line.split(" ", 1)[1].strip()
+                for line in resolved.splitlines()
+                if line.lower().startswith("proxycommand ")
+            ),
+            "",
+        )
+        marker = proxy_command.split()[0]
+        if marker not in proxycommand:
+            _error(
+                f"Warning: an earlier block in {config} overrides it; move the "
+                f'{host} block above any "Host *" block.'
+            )
+    return 0
+
+
+def _error(message: str) -> None:
+    print(message, file=sys.stderr)

nullgate/commands.py

@@ -0,0 +1,172 @@
+"""Command-line parser and entry point dispatch for Nullgate."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from nullgate import session, transports
+
+SUBCOMMANDS = ("open", "shut", "inspect", "enter", "trace", "cycle", "upgrade")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nullgate",
+        description="Disposable SSH gateway into confined directory workspaces.",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"nullgate {session._version()}",
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="command")
+
+    open_parser = sub.add_parser(
+        "open",
+        description="Launch gateway daemon and ingress transport.",
+    )
+    open_parser.add_argument(
+        "workspace",
+        nargs="?",
+        help="Directory exposed by the gateway (default: current directory).",
+    )
+    open_parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help=f"Local SSH listen port (default: {session.DEFAULT_PORT}).",
+    )
+    open_parser.add_argument(
+        "--slot",
+        type=int,
+        default=None,
+        help=f"Ingress slot number (default: {session.DEFAULT_SLOT}).",
+    )
+    open_parser.add_argument(
+        "--transport",
+        choices=transports.VALID_TRANSPORTS,
+        default=None,
+        help=f"Ingress transport provider (default {transports.DEFAULT_TRANSPORT}).",
+    )
+    open_parser.add_argument(
+        "--accept",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Permit any client without credentials; --no-accept restores authentication.",
+    )
+    open_parser.add_argument(
+        "--allow-tcp-forwarding",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Allow SSH port forwarding; use --no-allow-tcp-forwarding to disable it.",
+    )
+    open_parser.add_argument(
+        "--confine-sftp",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Confine SFTP and SCP to the workspace; --no-confine-sftp restores host visibility.",
+    )
+    open_parser.add_argument(
+        "--endpoint",
+        help="WebSocket ingress endpoint URL (for upterm or cloudflare transports).",
+    )
+    open_parser.add_argument(
+        "--hostname",
+        help="Public hostname (for cloudflared transport).",
+    )
+    open_parser.add_argument(
+        "--token",
+        help="Cloudflare Argo tunnel token (for cloudflared transport).",
+    )
+
+    sub.add_parser(
+        "shut",
+        description="Halt running gateway and transport services.",
+    )
+
+    sub.add_parser(
+        "inspect",
+        description="Display service health, access URLs, and authentication status.",
+    )
+
+    sub.add_parser(
+        "enter",
+        description="Show SSH connection strings and client setup commands.",
+    )
+
+    trace_parser = sub.add_parser(
+        "trace",
+        description="View or stream service operational logs.",
+    )
+    trace_parser.add_argument(
+        "target",
+        nargs="?",
+        default="all",
+        choices=["all", "gateway", "transport"],
+        help="Target log stream to inspect (default all).",
+    )
+    trace_parser.add_argument(
+        "-f",
+        "--follow",
+        dest="f",
+        action="store_true",
+        help="Follow log stream output continuously.",
+    )
+
+    sub.add_parser(
+        "cycle",
+        description="Restart services using active or saved configuration.",
+    )
+
+    upgrade_parser = sub.add_parser(
+        "upgrade",
+        description="Fetch and install latest Nullgate release.",
+    )
+    upgrade_parser.add_argument(
+        "--version",
+        help="Install a specific published version instead of the latest stable release.",
+    )
+
+    proxy_parser = sub.add_parser(
+        "proxy",
+        description=argparse.SUPPRESS,
+    )
+    proxy_parser.add_argument("url")
+
+    upterm_proxy = sub.add_parser(
+        "upterm-proxy",
+        description=argparse.SUPPRESS,
+    )
+    upterm_proxy.add_argument("url")
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    handlers = {
+        "open": session.cmd_open,
+        "shut": session.cmd_shut,
+        "inspect": session.cmd_inspect,
+        "enter": session.cmd_enter,
+        "trace": session.cmd_trace,
+        "cycle": session.cmd_cycle,
+        "upgrade": session.cmd_upgrade,
+        "proxy": transports.cmd_proxy,
+        "upterm-proxy": transports.cmd_upterm_proxy,
+    }
+
+    handler = handlers.get(args.command)
+    if handler is None:
+        parser.print_help(sys.stderr)
+        return 2
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())