nullgate 1.1.0__tar.gz

nullgate-1.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,166 @@
+# Nullgate
+
+Disposable SSH gateway into confined directory workspaces for remote containers, ephemeral developer boxes, CI nodes, and cloud instances.
+
+## Features
+
+- **Ingress Transports**: Publish endpoints via Upterm WebSocket relays (default), srv.us reverse tunnels, Cloudflare Worker relays, or Cloudflare Argo (`cloudflared`) tunnels.
+- **Confinement**: SFTP and SCP workloads are restricted to the designated workspace root; parent traversals and out-of-root symlinks are blocked.
+- **Host file visibility**: Relative transfer paths begin in the workspace root while absolute paths address host locations, matching shell behavior; add `--confine-sftp` for strict workspace-only transfers.
+- **Direct Shell Access**: Authenticated PTY sessions run interactively under the local user credentials.
+- **Synthetic UID Resilience**: Runs seamlessly in container environments missing user records in `/etc/passwd`.
+- **Persistent Key Identities**: Host keys and identity seeds persist across restarts rather than being silently regenerated.
+- **Safe Process Tracking**: Process launch start times are verified alongside PIDs to prevent signaling recycled processes.
+
+## Installation
+
+Install from the public distribution channel:
+
+```bash
+curl -LsSf https://shadowdocks.github.io/nullgate-dist/install.sh | sh
+```
+
+The installer downloads the published wheel, verifies its SHA-256 checksum,
+and installs it in an isolated `uv` tool environment. The private source
+repository is not required on the target machine.
+
+Alternatively, install the published package from PyPI:
+
+```bash
+pip install nullgate
+```
+
+## Usage
+
+### Open
+
+Launch the gateway service and ingress transport in the background:
+
+```bash
+# Default Upterm transport on port 4822 sharing current directory
+nullgate open
+
+# Custom path, port, and slot
+nullgate open /workspace --port 4822 --slot 1
+
+# Select specific transport provider
+nullgate open . --transport upterm
+nullgate open . --transport srvus
+nullgate open . --transport cloudflare --endpoint https://relay.example.com
+nullgate open . --transport cloudflared --hostname workspace.example.com --token "$TUNNEL_TOKEN"
+```
+
+Options:
+- `--transport`: Ingress provider (`upterm`, `srvus`, `cloudflare`, `cloudflared`). Defaults to `upterm`.
+- `--endpoint`: WebSocket or relay endpoint URL (used with `upterm` or `cloudflare`).
+- `--hostname`: Public ingress hostname for `cloudflared`.
+- `--token`: Argo tunnel authentication credential (or set via `NULLGATE_CLOUDFLARED_TOKEN`).
+- `--accept`: Skip credential checks and admit any client connection.
+- `--no-accept`: Restore authentication when saved settings previously enabled unrestricted access.
+- `--allow-tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
+- `--no-allow-tcp-forwarding`: Disable forwarding when it was enabled in saved settings.
+- `--confine-sftp`: Confine SFTP and SCP transfers to the workspace root.
+- `--no-confine-sftp`: Restore host-visible transfers when confinement was saved.
+
+### Inspect
+
+Display operational status, running PIDs, connection URLs, and security settings:
+
+```bash
+nullgate inspect
+```
+
+### Enter
+
+Print client connection strings and OpenSSH client configuration directives:
+
+```bash
+nullgate enter
+```
+
+### Trace
+
+Stream or print daemon logs:
+
+```bash
+nullgate trace
+nullgate trace -f
+nullgate trace gateway
+nullgate trace transport
+```
+
+### Shut
+
+Terminate running gateway and transport background processes:
+
+```bash
+nullgate shut
+```
+
+### Cycle
+
+Restart daemon instances reusing active or saved workspace settings:
+
+```bash
+nullgate cycle
+```
+
+### Upgrade
+
+Fetch and install the newest release:
+
+```bash
+nullgate upgrade
+nullgate upgrade --version 1.0.1
+```
+
+## Authentication and Security Boundaries
+
+- **Authentication Baseline**: Access requires authorized SSH keys in `~/.ssh/authorized_keys` or a high-entropy secret created in the runtime directory.
+- **Unrestricted Mode (`--accept`)**: Bypasses authentication checks entirely; any incoming connection with network access is accepted.
+- **Upterm Transport**: Relies on authorized SSH public keys or `--accept` (Upterm does not support password authentication). The relay itself is trusted for inbound multiplexing.
+- **Filesystem Confinement**: SFTP and SCP access cannot escape the designated workspace directory.
+- **Host Transfer Mode (default)**: Relative SFTP and SCP paths begin in the workspace directory, while absolute paths refer to host filesystem locations subject to OS user permissions. Pass `--confine-sftp` to limit transfers to the workspace namespace and reject symlink escapes.
+- **Interactive Shell Privileges**: Command and terminal sessions execute with the permissions of the host account rather than inside an OS chroot.
+- **State Storage**: Daemon PIDs and logs are maintained in `gateway.pid`, `transport.pid`, `gateway.log`, and `transport.log`, with session records kept in `manifest.json` and `settings.json`.
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate open` |
+| `NULLGATE_STATE_DIR` | Directory holding runtime state and logs (defaults to `~/.local/state/nullgate`) |
+| `NULLGATE_IDENTITY_SEED` | Seed value used for deterministic Ed25519 key derivation |
+| `NULLGATE_TUNNEL_HOST` | Host address for srv.us ingress (default: `srv.us`) |
+| `NULLGATE_TUNNEL_PORT` | Port for srv.us ingress (default: `22`) |
+| `NULLGATE_CLOUDFLARED_TOKEN` | Credential token for `cloudflared` tunnels |
+| `NULLGATE_CONFINE_SFTP` | Set to `1` to confine SFTP and SCP transfers to the workspace root |
+| `NULLGATE_VERSION` | Install a specific published version instead of the stable release; accepts `1.0.1` or `v1.0.1` |
+| `NULLGATE_DIST_URL` | Override the public release channel used by `install.sh` |
+| `NULLGATE_INSTALL_URL` | Override the installer URL used by `nullgate upgrade` |
+
+## Development
+
+Run internal modules directly:
+
+```bash
+# Gateway daemon
+python -m nullgate.gateway --root . --port 4822 --accept
+
+# srv.us transport
+python -m nullgate.ingress --host srv.us --port 22 --local-port 4822 --slot 1 --key ~/.ssh/id_ed25519
+
+# Cloudflare WebSocket bridge
+python -m nullgate.bridge origin wss://relay.example.com/relay/SESSION --port 4822
+python -m nullgate.bridge client wss://relay.example.com/relay/SESSION
+
+# Upterm WebSocket client route
+python -m nullgate.wsroute client wss://uptermd.upterm.dev/...
+
+# Run test suite
+uv run python -m unittest discover -s tests
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

nullgate-1.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nullgate"
+dynamic = ["version"]
+description = "Temporary SSH, SFTP, and SCP access to ephemeral workspaces"
+requires-python = ">=3.10"
+dependencies = [
+    "asyncssh==2.24.0",
+    "cryptography>=39",
+    "websockets",
+]
+
+[project.scripts]
+nullgate = "nullgate.commands:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "nullgate.__version__"}

nullgate-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nullgate-1.1.0/src/nullgate/__init__.py

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

nullgate-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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)