nullgate 1.1.0__py3-none-any.whl

nullgate/ingress.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""srv.us reverse tunnel for the Nullgate srvus transport.
+
+Holds one AsyncSSH connection to srv.us with a remote port forward pointing back
+at the local SSH server. AsyncSSH is already required by the server, so speaking
+SSH in-process here removes the OpenSSH client and ssh-keygen from the host's
+requirements; the tunnel then works on stripped images that ship neither.
+
+Launch with asyncssh available, e.g.:
+  python -m nullgate.ingress --local-port 4822 --slot 1
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import hashlib
+import os
+import signal
+import sys
+from pathlib import Path
+
+import asyncssh
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from nullgate.account import current_username, ensure_username_environment
+
+
+IDENTITY_SEED_ENV = "NULLGATE_IDENTITY_SEED"
+
+
+class TunnelClient(asyncssh.SSHClient):
+    """Surface srv.us protocol messages in the tunnel log.
+
+    srv.us reports the assigned https URL over the session channel, and reports
+    errors as SSH debug messages or an auth banner. The launcher scrapes the log
+    for that URL, so all three have to land on stdout.
+    """
+
+    def debug_msg_received(self, msg: str, lang: str, always_display: bool) -> None:
+        del lang, always_display
+        print(msg, flush=True)
+
+    def auth_banner_received(self, msg: str, lang: str) -> None:
+        del lang
+        print(msg, flush=True)
+
+
+def ensure_key(path: Path) -> None:
+    """Create the tunnel key when missing; reuse it for a stable hostname.
+
+    srv.us derives the hostname from this key, so it is written once and kept.
+    """
+    if path.exists():
+        if path.is_symlink() or not path.is_file():
+            raise ValueError(f"Tunnel key must be a regular file: {path}")
+        return
+
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    seed = os.getenv(IDENTITY_SEED_ENV, "")
+    if seed:
+        private = Ed25519PrivateKey.from_private_bytes(
+            hashlib.sha256(b"nullgate/srv.us/v1\0" + seed.encode()).digest()
+        )
+        encoded = private.private_bytes(
+            serialization.Encoding.PEM,
+            serialization.PrivateFormat.PKCS8,
+            serialization.NoEncryption(),
+        )
+        key = asyncssh.import_private_key(encoded)
+    else:
+        key = asyncssh.generate_private_key("ssh-ed25519")
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "wb") as output:
+            output.write(key.export_private_key())
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, path)
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            temporary.unlink()
+    source = IDENTITY_SEED_ENV if seed else "random identity"
+    print(f"nullgate-ingress: created {path} from {source}", flush=True)
+
+
+async def pump(reader: asyncssh.SSHReader, writer) -> None:
+    while True:
+        data = await reader.read(4096)
+        if not data:
+            return
+        writer.write(data)
+        writer.flush()
+
+
+async def run(
+    host: str,
+    port: int,
+    local_host: str,
+    local_port: int,
+    slot: int,
+    key: Path,
+    username: str,
+) -> int:
+    ensure_username_environment(username)
+    ensure_key(key)
+
+    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)
+
+    # known_hosts=None matches the connection commands this project prints: the
+    # ingress is disposable and only carries bytes, so it is not authenticated.
+    connection = await asyncssh.connect(
+        host,
+        port=port,
+        username=username,
+        client_keys=[str(key)],
+        known_hosts=None,
+        client_factory=TunnelClient,
+        keepalive_interval=30,
+        keepalive_count_max=3,
+    )
+
+    process = None
+    listener = None
+    tasks: list[asyncio.Task] = []
+    try:
+        # srv.us withholds its tcpip-forward reply until a session channel
+        # exists, so open the shell first and keep reading it.
+        process = await connection.create_process(request_pty=False)
+        tasks = [
+            asyncio.create_task(pump(process.stdout, sys.stdout)),
+            asyncio.create_task(pump(process.stderr, sys.stderr)),
+        ]
+        with contextlib.suppress(ConnectionError, BrokenPipeError, asyncssh.Error):
+            process.stdin.write_eof()
+            await process.stdin.drain()
+
+        listener = await connection.forward_remote_port(
+            "", slot, local_host, local_port
+        )
+        print(
+            f"remote forward ready on slot {listener.get_port()} "
+            f"-> {local_host}:{local_port}",
+            flush=True,
+        )
+
+        closed = asyncio.create_task(connection.wait_closed())
+        requested = asyncio.create_task(stopped.wait())
+        tasks.extend((closed, requested))
+        await asyncio.wait((closed, requested), return_when=asyncio.FIRST_COMPLETED)
+        if requested.done():
+            return 0
+        print("nullgate-ingress: connection closed by the server", flush=True)
+        return 1
+    finally:
+        if listener is not None:
+            listener.close()
+        if process is not None:
+            process.stdin.close()
+        connection.close()
+        await connection.wait_closed()
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="srv.us", help="tunnel host")
+    parser.add_argument("--port", type=int, default=22, help="tunnel host port")
+    parser.add_argument("--local-host", default="127.0.0.1", help="forward destination")
+    parser.add_argument("--local-port", type=int, required=True, help="local SSH port")
+    parser.add_argument("--slot", type=int, required=True, help="srv.us slot")
+    parser.add_argument("--key", required=True, help="tunnel private key path")
+    parser.add_argument("--username", default=None, help="tunnel username")
+    args = parser.parse_args(argv)
+
+    try:
+        return asyncio.run(
+            run(
+                args.host,
+                args.port,
+                args.local_host,
+                args.local_port,
+                args.slot,
+                Path(args.key).expanduser(),
+                args.username or current_username(),
+            )
+        )
+    except KeyboardInterrupt:  # pragma: no cover
+        return 130
+    except (OSError, ValueError, asyncssh.Error) as error:
+        print(f"nullgate-ingress: {error}", file=sys.stderr, flush=True)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nullgate/runtime.py

@@ -0,0 +1,236 @@
+"""Runtime state for the Nullgate CLI.
+
+Owns the state directory, PID files (with process-identity protection against
+recycled PIDs), credentials, manifest, session IDs, and key permissions.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import re
+import secrets
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+DEFAULT_PORT = 4822
+SRVUS_HOST_RE = re.compile(r"https://([A-Za-z0-9.-]+\.srv\.us)/?")
+
+
+def state_dir() -> Path:
+    default = os.environ.get(
+        "XDG_STATE_HOME",
+        os.path.join(os.path.expanduser("~"), ".local", "state"),
+    )
+    return Path(os.environ.get("NULLGATE_STATE_DIR", default)) / "nullgate"
+
+
+def setup_state() -> Path:
+    """Create the state directory with owner-only access."""
+    directory = state_dir()
+    os.umask(0o077)
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    directory.chmod(0o700)
+    return directory
+
+
+def process_identity(pid: int) -> str | None:
+    """Hash an origin for ``pid`` so a recycled pid is never mistaken for ours.
+
+    Uses /proc/PID/stat field 20 (starttime) when available, else the ps start
+    time. Returns None when the pid cannot be inspected.
+    """
+    proc_stat = Path("/proc") / str(pid) / "stat"
+    try:
+        if proc_stat.is_file():
+            data = proc_stat.read_text().rsplit(")", 1)[1].split()[19]
+        else:
+            data = subprocess.check_output(
+                ["ps", "-p", str(pid), "-o", "lstart="], text=True
+            ).strip()
+    except (OSError, IndexError, subprocess.SubprocessError):
+        return None
+    if not data:
+        return None
+    return hashlib.sha256(data.encode()).hexdigest()
+
+
+def read_pid(pid_file: Path) -> int | None:
+    """Return the pid recorded in ``pid_file``, or None if malformed/absent."""
+    with contextlib.suppress(OSError):
+        fields = pid_file.read_text().split()
+        if len(fields) == 2 and fields[0].isdigit():
+            return int(fields[0])
+    return None
+
+
+def _identity_of(pid_file: Path) -> str | None:
+    with contextlib.suppress(OSError):
+        fields = pid_file.read_text().split()
+        if len(fields) == 2:
+            return fields[1]
+    return None
+
+
+def is_running(pid_file: Path) -> bool:
+    """True when the recorded pid is alive and still matches its identity."""
+    pid = read_pid(pid_file)
+    if pid is None:
+        return False
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    identity = process_identity(pid)
+    return identity is not None and identity == _identity_of(pid_file)
+
+
+def write_pid(pid_file: Path, pid: int) -> bool:
+    """Record ``pid IDENTITY``; fails rather than track an unidentifiable pid."""
+    identity = process_identity(pid)
+    if identity is None:
+        return False
+    try:
+        pid_file.write_text(f"{pid} {identity}\n")
+    except OSError:
+        return False
+    return True
+
+
+def kill_untracked(pid: int) -> None:
+    """Stop a background process we cannot track via a pid file."""
+    with contextlib.suppress(OSError):
+        os.kill(pid, 15)
+    for _ in range(50):
+        try:
+            os.kill(pid, 0)
+        except OSError:
+            break
+        time.sleep(0.1)
+    else:
+        with contextlib.suppress(OSError):
+            os.kill(pid, 9)
+
+
+def stop_one(pid_file: Path) -> None:
+    """Stop the process recorded in ``pid_file``, guarding against recycled pids."""
+    pid = read_pid(pid_file)
+    if pid is None:
+        pid_file.unlink(missing_ok=True)
+        return
+    if is_running(pid_file):
+        with contextlib.suppress(OSError):
+            os.kill(pid, 15)
+        for _ in range(50):
+            if not is_running(pid_file):
+                break
+            time.sleep(0.1)
+        else:
+            with contextlib.suppress(OSError):
+                os.kill(pid, 9)
+    pid_file.unlink(missing_ok=True)
+
+
+def port_open(port: int) -> bool:
+    with contextlib.suppress(OSError):
+        connection = socket.create_connection(("127.0.0.1", port), 0.2)
+        connection.close()
+        return True
+    return False
+
+
+def extract_host(transport_log: Path) -> str:
+    """Return the last srv.us https host the transport log announced, if any."""
+    try:
+        text = transport_log.read_text(errors="replace")
+    except OSError:
+        return ""
+    hosts = SRVUS_HOST_RE.findall(text)
+    return hosts[-1] if hosts else ""
+
+
+def generate_password() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def get_or_create_session() -> str:
+    """Reuse the persisted session id so the tunnel URL is stable across restarts."""
+    session_file = state_dir() / "session"
+    try:
+        persisted = session_file.read_text().strip()
+        if persisted:
+            return persisted
+    except OSError:
+        pass
+    session = secrets.token_urlsafe(24)
+    session_file.write_text(session + "\n")
+    return session
+
+
+def manifest_get(key: str) -> str:
+    """Read a field from manifest.json; return '' when missing."""
+    manifest_file = state_dir() / "manifest.json"
+    try:
+        data = json.loads(manifest_file.read_text())
+        if isinstance(data, dict):
+            val = data.get(key, "")
+            return str(val) if val is not None else ""
+    except (OSError, json.JSONDecodeError):
+        pass
+    return ""
+
+
+def write_manifest(entries: dict[str, Any]) -> None:
+    """Record active session state in manifest.json."""
+    directory = setup_state()
+    manifest_file = directory / "manifest.json"
+    manifest_file.write_text(json.dumps(entries, indent=2) + "\n")
+
+
+def read_settings() -> dict[str, Any]:
+    """Return parameters persisted in settings.json by the previous open command."""
+    settings_file = state_dir() / "settings.json"
+    try:
+        data = json.loads(settings_file.read_text())
+        if isinstance(data, dict):
+            return data
+    except (OSError, json.JSONDecodeError):
+        pass
+    return {}
+
+
+def write_settings(entries: dict[str, Any]) -> None:
+    """Persist parameters to settings.json with owner-only access permissions."""
+    directory = setup_state()
+    settings_file = directory / "settings.json"
+    cleaned = {k: v for k, v in entries.items() if v is not None and v != ""}
+    settings_file.write_text(json.dumps(cleaned, indent=2) + "\n")
+    with contextlib.suppress(OSError):
+        settings_file.chmod(0o600)
+
+
+def repair_key_permissions(key: Path) -> None:
+    """chmod an srv.us tunnel key to 0600, mirroring OpenSSH's restriction."""
+    if not key.is_file():
+        return
+    mode = key.stat().st_mode & 0o777
+    if mode == 0o600:
+        return
+    try:
+        key.chmod(0o600)
+    except OSError:
+        print(
+            f"Warning: could not fix permissions on {key} (mode {mode:03o})",
+            file=sys.stderr,
+        )
+        return
+    print(
+        f"Fixed permissions on {key} (was {mode:03o}, now 600)",
+        file=sys.stderr,
+    )