nullgate 1.1.1__tar.gz → 1.2.0__tar.gz

{nullgate-1.1.1/src/nullgate.egg-info → nullgate-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nullgate
-Version: 1.1.1
+Version: 1.2.0
 Summary: Disposable SSH gateway into confined directory workspaces
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -18,7 +18,7 @@ Disposable SSH gateway into confined directory workspaces for remote containers,
 
 - **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.
+- **Host file visibility**: Relative transfer paths begin in the workspace root while absolute paths address host locations, matching shell behavior; add `--restrict-file-transfer` 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.
@@ -44,77 +44,77 @@ pip install nullgate
 
 ## Usage
 
-### Open
+### Start
 
 Launch the gateway service and ingress transport in the background:
 
 ```bash
 # Default Upterm transport on port 4822 sharing current directory
-nullgate open
+nullgate start
 
 # Custom path, port, and slot
-nullgate open /workspace --port 4822 --slot 1
+nullgate start /workspace --ssh-port 4822 --tunnel-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"
+nullgate start . --provider upterm
+nullgate start . --provider srvus
+nullgate start . --provider cloudflare --relay-url https://relay.example.com
+nullgate start . --provider cloudflared --public-hostname workspace.example.com --cloudflare-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
+- `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
+- `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
+- `--public-hostname`: Public hostname used with `cloudflared`.
+- `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
+- `--public-access`: Allow connections without credentials. This is unsafe on public endpoints.
+- `--no-public-access`: Require authentication.
+- `--tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
+- `--no-tcp-forwarding`: Disable SSH TCP tunneling.
+- `--restrict-file-transfer`: Keep SFTP and SCP inside the workspace.
+- `--no-restrict-file-transfer`: Allow host-visible file transfers.
+
+### Status
 
 Display operational status, running PIDs, connection URLs, and security settings:
 
 ```bash
-nullgate inspect
+nullgate status
 ```
 
-### Enter
+### Connect
 
 Print client connection strings and OpenSSH client configuration directives:
 
 ```bash
-nullgate enter
+nullgate connect
 ```
 
-### Trace
+### Logs
 
 Stream or print daemon logs:
 
 ```bash
-nullgate trace
-nullgate trace -f
-nullgate trace gateway
-nullgate trace transport
+nullgate logs
+nullgate logs -f
+nullgate logs gateway
+nullgate logs transport
 ```
 
-### Shut
+### Stop
 
 Terminate running gateway and transport background processes:
 
 ```bash
-nullgate shut
+nullgate stop
 ```
 
-### Cycle
+### Restart
 
 Restart daemon instances reusing active or saved workspace settings:
 
 ```bash
-nullgate cycle
+nullgate restart
 ```
 
 ### Upgrade
@@ -126,13 +126,17 @@ nullgate upgrade
 nullgate upgrade --version 1.0.1
 ```
 
+The earlier command names `open`, `shut`, `inspect`, `enter`, `trace`, and
+`cycle` remain available as compatibility aliases. Their earlier option names
+also remain accepted, but new scripts should use the names documented above.
+
 ## 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.
+- **Public access (`--public-access`)**: Bypasses authentication checks entirely; any incoming connection with network access is accepted.
+- **Upterm Transport**: Relies on authorized SSH public keys or `--public-access` (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.
+- **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 `--restrict-file-transfer` 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`.
 
@@ -140,7 +144,7 @@ nullgate upgrade --version 1.0.1
 
 | Variable | Description |
 |---|---|
-| `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate open` |
+| `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate start` |
 | `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-1.1.1 → nullgate-1.2.0}/README.md

@@ -6,7 +6,7 @@ Disposable SSH gateway into confined directory workspaces for remote containers,
 
 - **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.
+- **Host file visibility**: Relative transfer paths begin in the workspace root while absolute paths address host locations, matching shell behavior; add `--restrict-file-transfer` 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.
@@ -32,77 +32,77 @@ pip install nullgate
 
 ## Usage
 
-### Open
+### Start
 
 Launch the gateway service and ingress transport in the background:
 
 ```bash
 # Default Upterm transport on port 4822 sharing current directory
-nullgate open
+nullgate start
 
 # Custom path, port, and slot
-nullgate open /workspace --port 4822 --slot 1
+nullgate start /workspace --ssh-port 4822 --tunnel-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"
+nullgate start . --provider upterm
+nullgate start . --provider srvus
+nullgate start . --provider cloudflare --relay-url https://relay.example.com
+nullgate start . --provider cloudflared --public-hostname workspace.example.com --cloudflare-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
+- `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
+- `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
+- `--public-hostname`: Public hostname used with `cloudflared`.
+- `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
+- `--public-access`: Allow connections without credentials. This is unsafe on public endpoints.
+- `--no-public-access`: Require authentication.
+- `--tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
+- `--no-tcp-forwarding`: Disable SSH TCP tunneling.
+- `--restrict-file-transfer`: Keep SFTP and SCP inside the workspace.
+- `--no-restrict-file-transfer`: Allow host-visible file transfers.
+
+### Status
 
 Display operational status, running PIDs, connection URLs, and security settings:
 
 ```bash
-nullgate inspect
+nullgate status
 ```
 
-### Enter
+### Connect
 
 Print client connection strings and OpenSSH client configuration directives:
 
 ```bash
-nullgate enter
+nullgate connect
 ```
 
-### Trace
+### Logs
 
 Stream or print daemon logs:
 
 ```bash
-nullgate trace
-nullgate trace -f
-nullgate trace gateway
-nullgate trace transport
+nullgate logs
+nullgate logs -f
+nullgate logs gateway
+nullgate logs transport
 ```
 
-### Shut
+### Stop
 
 Terminate running gateway and transport background processes:
 
 ```bash
-nullgate shut
+nullgate stop
 ```
 
-### Cycle
+### Restart
 
 Restart daemon instances reusing active or saved workspace settings:
 
 ```bash
-nullgate cycle
+nullgate restart
 ```
 
 ### Upgrade
@@ -114,13 +114,17 @@ nullgate upgrade
 nullgate upgrade --version 1.0.1
 ```
 
+The earlier command names `open`, `shut`, `inspect`, `enter`, `trace`, and
+`cycle` remain available as compatibility aliases. Their earlier option names
+also remain accepted, but new scripts should use the names documented above.
+
 ## 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.
+- **Public access (`--public-access`)**: Bypasses authentication checks entirely; any incoming connection with network access is accepted.
+- **Upterm Transport**: Relies on authorized SSH public keys or `--public-access` (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.
+- **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 `--restrict-file-transfer` 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`.
 
@@ -128,7 +132,7 @@ nullgate upgrade --version 1.0.1
 
 | Variable | Description |
 |---|---|
-| `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate open` |
+| `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate start` |
 | `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-1.2.0/src/nullgate/__init__.py

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

nullgate-1.2.0/src/nullgate/commands.py

@@ -0,0 +1,246 @@
+"""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 = (
+    "start",
+    "stop",
+    "status",
+    "connect",
+    "logs",
+    "restart",
+    "upgrade",
+    "open",
+    "shut",
+    "inspect",
+    "enter",
+    "trace",
+    "cycle",
+)
+
+
+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")
+
+    start_parser = sub.add_parser(
+        "start",
+        aliases=["open"],
+        description="Start SSH access to a workspace.",
+        help="Start SSH access to a workspace (alias: open).",
+    )
+    start_parser.add_argument(
+        "workspace",
+        nargs="?",
+        help="Directory to make available (default: current directory).",
+    )
+    start_parser.add_argument(
+        "--ssh-port",
+        dest="port",
+        type=int,
+        default=None,
+        help=f"Local SSH server port (default: {session.DEFAULT_PORT}).",
+    )
+    start_parser.add_argument("--port", dest="port", type=int, help=argparse.SUPPRESS)
+    start_parser.add_argument(
+        "--tunnel-slot",
+        dest="slot",
+        type=int,
+        default=None,
+        help=f"srv.us tunnel slot (default: {session.DEFAULT_SLOT}).",
+    )
+    start_parser.add_argument("--slot", dest="slot", type=int, help=argparse.SUPPRESS)
+    start_parser.add_argument(
+        "--provider",
+        dest="transport",
+        choices=transports.VALID_TRANSPORTS,
+        default=None,
+        help=f"Public connection provider (default: {transports.DEFAULT_TRANSPORT}).",
+    )
+    start_parser.add_argument(
+        "--transport",
+        dest="transport",
+        choices=transports.VALID_TRANSPORTS,
+        help=argparse.SUPPRESS,
+    )
+    start_parser.add_argument(
+        "--public-access",
+        dest="accept",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Allow connections without SSH credentials (unsafe on public endpoints).",
+    )
+    start_parser.add_argument(
+        "--accept",
+        dest="accept",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    start_parser.add_argument(
+        "--tcp-forwarding",
+        dest="allow_tcp_forwarding",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Allow SSH port forwarding.",
+    )
+    start_parser.add_argument(
+        "--allow-tcp-forwarding",
+        dest="allow_tcp_forwarding",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    start_parser.add_argument(
+        "--restrict-file-transfer",
+        dest="confine_sftp",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Keep SFTP and SCP transfers inside the workspace.",
+    )
+    start_parser.add_argument(
+        "--confine-sftp",
+        dest="confine_sftp",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    start_parser.add_argument(
+        "--relay-url",
+        dest="endpoint",
+        help="WebSocket relay URL (for upterm or cloudflare providers).",
+    )
+    start_parser.add_argument("--endpoint", dest="endpoint", help=argparse.SUPPRESS)
+    start_parser.add_argument(
+        "--public-hostname",
+        dest="hostname",
+        help="Public hostname (for the cloudflared provider).",
+    )
+    start_parser.add_argument("--hostname", dest="hostname", help=argparse.SUPPRESS)
+    start_parser.add_argument(
+        "--cloudflare-token",
+        dest="token",
+        help="Cloudflare tunnel token (for the cloudflared provider).",
+    )
+    start_parser.add_argument("--token", dest="token", help=argparse.SUPPRESS)
+
+    sub.add_parser(
+        "stop",
+        aliases=["shut"],
+        description="Stop SSH access and its connection provider.",
+        help="Stop SSH access (alias: shut).",
+    )
+
+    sub.add_parser(
+        "status",
+        aliases=["inspect"],
+        description="Show service health, connection details, and security settings.",
+        help="Show current status (alias: inspect).",
+    )
+
+    sub.add_parser(
+        "connect",
+        aliases=["enter"],
+        description="Show how to connect with SSH.",
+        help="Show SSH connection instructions (alias: enter).",
+    )
+
+    logs_parser = sub.add_parser(
+        "logs",
+        aliases=["trace"],
+        description="View or follow service logs.",
+        help="View or follow service logs (alias: trace).",
+    )
+    logs_parser.add_argument(
+        "target",
+        nargs="?",
+        default="all",
+        choices=["all", "gateway", "transport"],
+        help="Target log stream to inspect (default all).",
+    )
+    logs_parser.add_argument(
+        "-f",
+        "--follow",
+        dest="f",
+        action="store_true",
+        help="Follow log stream output continuously.",
+    )
+
+    sub.add_parser(
+        "restart",
+        aliases=["cycle"],
+        description="Restart SSH access using the saved settings.",
+        help="Restart using saved settings (alias: cycle).",
+    )
+
+    upgrade_parser = sub.add_parser(
+        "upgrade",
+        description="Fetch and install latest Nullgate release.",
+        help="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 = {
+        "start": session.cmd_open,
+        "open": session.cmd_open,
+        "stop": session.cmd_shut,
+        "shut": session.cmd_shut,
+        "status": session.cmd_inspect,
+        "inspect": session.cmd_inspect,
+        "connect": session.cmd_enter,
+        "enter": session.cmd_enter,
+        "logs": session.cmd_trace,
+        "trace": session.cmd_trace,
+        "restart": session.cmd_cycle,
+        "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())

{nullgate-1.1.1 → nullgate-1.2.0}/src/nullgate/session.py

@@ -1,6 +1,6 @@
 """Session lifecycle orchestration for Nullgate.
 
-Provides handlers for open, shut, inspect, enter, trace, cycle, and upgrade.
+Provides handlers for start, stop, status, connect, logs, restart, and upgrade.
 """
 
 from __future__ import annotations
@@ -96,14 +96,14 @@ def _print_url_row(color: _Color, known: bool, url: str) -> None:
     if known:
         print(f"  url       {url}")
     else:
-        print("  url       pending   " + _Color(sys.stdout.isatty()).dim("(nullgate trace transport -f)"))
+        print("  url       pending   " + _Color(sys.stdout.isatty()).dim("(nullgate logs transport -f)"))
 
 
 def _print_auth_rows(color: _Color, state: Path) -> None:
     accept = st.manifest_get("accept")
     allow = st.manifest_get("allow_tcp_forwarding")
     if accept == "1":
-        print("  auth      none " + color.dim("(--accept); anyone can connect"))
+        print("  auth      none " + color.dim("(--public-access); anyone can connect"))
     else:
         password_file = state / "password"
         if password_file.is_file():
@@ -116,12 +116,12 @@ def _print_auth_rows(color: _Color, state: Path) -> None:
     if allow == "1":
         print("  forward   enabled")
     else:
-        print("  forward   disabled " + color.dim("(--allow-tcp-forwarding)"))
+        print("  forward   disabled " + color.dim("(--tcp-forwarding)"))
     confine = st.manifest_get("confine_sftp")
     if not confine:
         confine = st.read_settings().get("confine_sftp")
     if confine == "1":
-        print("  sftp      confined " + color.dim("(--confine-sftp)"))
+        print("  sftp      confined " + color.dim("(--restrict-file-transfer)"))
     else:
         print("  sftp      host")
 
@@ -203,8 +203,8 @@ def _show_status() -> int:
     _print_auth_rows(color, state)
     if target is not None:
         print()
-        print("  enter     " + color.bold(f"ssh {target.user or current_username()}@{target.host}"))
-        print("            " + color.dim("first time here: nullgate enter"))
+        print("  connect   " + color.bold(f"ssh {target.user or current_username()}@{target.host}"))
+        print("            " + color.dim("first time here: nullgate connect"))
     return 0 if (gateway_running and transport_running) else 1
 
 
@@ -269,7 +269,10 @@ def cmd_open(args: Any) -> int:
         transports.prompt_authorized_key()
         keys = Path(os.path.expanduser("~/.ssh/authorized_keys"))
         if not keys.is_file() or not keys.stat().st_size:
-            die("The upterm transport requires an SSH authorized key or the --accept flag")
+            die(
+                "The upterm provider requires an SSH authorized key or "
+                "the --public-access flag"
+            )
         (state / "password").unlink(missing_ok=True)
         password = ""
     else:
@@ -409,7 +412,7 @@ def cmd_enter(args: Any = None) -> int:
     transport = st.manifest_get("transport") or transports.DEFAULT_TRANSPORT
     target = transports.resolve_target(transport, state)
     if target is None:
-        die("No published address yet; check nullgate inspect.")
+        die("No published address yet; check `nullgate status`.")
     color = _colorizer()
     ssh_user = target.user or current_username()
     print("Run once on the machine you are connecting from:")
@@ -451,7 +454,7 @@ def cmd_cycle(args: Any = None) -> int:
     del args
     st.setup_state()
     if not st.read_settings():
-        die("No saved configuration found to cycle; run open with desired options first.")
+        die("No saved settings found; run `nullgate start` with the desired options first.")
     cmd_shut()
     return cmd_open(
         argparse.Namespace(

{nullgate-1.1.1 → nullgate-1.2.0/src/nullgate.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nullgate
-Version: 1.1.1
+Version: 1.2.0
 Summary: Disposable SSH gateway into confined directory workspaces
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -18,7 +18,7 @@ Disposable SSH gateway into confined directory workspaces for remote containers,
 
 - **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.
+- **Host file visibility**: Relative transfer paths begin in the workspace root while absolute paths address host locations, matching shell behavior; add `--restrict-file-transfer` 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.
@@ -44,77 +44,77 @@ pip install nullgate
 
 ## Usage
 
-### Open
+### Start
 
 Launch the gateway service and ingress transport in the background:
 
 ```bash
 # Default Upterm transport on port 4822 sharing current directory
-nullgate open
+nullgate start
 
 # Custom path, port, and slot
-nullgate open /workspace --port 4822 --slot 1
+nullgate start /workspace --ssh-port 4822 --tunnel-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"
+nullgate start . --provider upterm
+nullgate start . --provider srvus
+nullgate start . --provider cloudflare --relay-url https://relay.example.com
+nullgate start . --provider cloudflared --public-hostname workspace.example.com --cloudflare-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
+- `--provider`: Public connection provider (`upterm`, `srvus`, `cloudflare`, or `cloudflared`). Defaults to `upterm`.
+- `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
+- `--public-hostname`: Public hostname used with `cloudflared`.
+- `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
+- `--public-access`: Allow connections without credentials. This is unsafe on public endpoints.
+- `--no-public-access`: Require authentication.
+- `--tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
+- `--no-tcp-forwarding`: Disable SSH TCP tunneling.
+- `--restrict-file-transfer`: Keep SFTP and SCP inside the workspace.
+- `--no-restrict-file-transfer`: Allow host-visible file transfers.
+
+### Status
 
 Display operational status, running PIDs, connection URLs, and security settings:
 
 ```bash
-nullgate inspect
+nullgate status
 ```
 
-### Enter
+### Connect
 
 Print client connection strings and OpenSSH client configuration directives:
 
 ```bash
-nullgate enter
+nullgate connect
 ```
 
-### Trace
+### Logs
 
 Stream or print daemon logs:
 
 ```bash
-nullgate trace
-nullgate trace -f
-nullgate trace gateway
-nullgate trace transport
+nullgate logs
+nullgate logs -f
+nullgate logs gateway
+nullgate logs transport
 ```
 
-### Shut
+### Stop
 
 Terminate running gateway and transport background processes:
 
 ```bash
-nullgate shut
+nullgate stop
 ```
 
-### Cycle
+### Restart
 
 Restart daemon instances reusing active or saved workspace settings:
 
 ```bash
-nullgate cycle
+nullgate restart
 ```
 
 ### Upgrade
@@ -126,13 +126,17 @@ nullgate upgrade
 nullgate upgrade --version 1.0.1
 ```
 
+The earlier command names `open`, `shut`, `inspect`, `enter`, `trace`, and
+`cycle` remain available as compatibility aliases. Their earlier option names
+also remain accepted, but new scripts should use the names documented above.
+
 ## 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.
+- **Public access (`--public-access`)**: Bypasses authentication checks entirely; any incoming connection with network access is accepted.
+- **Upterm Transport**: Relies on authorized SSH public keys or `--public-access` (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.
+- **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 `--restrict-file-transfer` 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`.
 
@@ -140,7 +144,7 @@ nullgate upgrade --version 1.0.1
 
 | Variable | Description |
 |---|---|
-| `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate open` |
+| `NULLGATE_PASSWORD` | Gateway-process credential; normally managed internally by `nullgate start` |
 | `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-1.1.1 → nullgate-1.2.0}/tests/test_commands.py

@@ -122,7 +122,7 @@ def state_dir(state_base):
 class CLILifecycleTests(unittest.TestCase):
     def test_redesigned_defaults_and_boolean_overrides(self):
         parser = commands.build_parser()
-        defaults = parser.parse_args(["open"])
+        defaults = parser.parse_args(["start"])
         self.assertEqual(session.DEFAULT_PORT, 4822)
         self.assertEqual(transports.DEFAULT_TRANSPORT, "upterm")
         self.assertIsNone(defaults.workspace)
@@ -133,13 +133,37 @@ class CLILifecycleTests(unittest.TestCase):
         self.assertIsNone(defaults.confine_sftp)
 
         restricted = parser.parse_args(
-            ["open", "--no-accept", "--no-allow-tcp-forwarding", "--no-confine-sftp"]
+            [
+                "start",
+                "--no-public-access",
+                "--no-tcp-forwarding",
+                "--restrict-file-transfer",
+            ]
         )
         self.assertFalse(restricted.accept)
         self.assertFalse(restricted.allow_tcp_forwarding)
-        self.assertFalse(restricted.confine_sftp)
-        confined = parser.parse_args(["open", "--confine-sftp"])
-        self.assertTrue(confined.confine_sftp)
+        self.assertTrue(restricted.confine_sftp)
+
+        clearer = parser.parse_args(
+            [
+                "start",
+                "--ssh-port", "2222",
+                "--tunnel-slot", "2",
+                "--provider", "upterm",
+                "--relay-url", "wss://relay.example",
+            ]
+        )
+        self.assertEqual(clearer.port, 2222)
+        self.assertEqual(clearer.slot, 2)
+        self.assertEqual(clearer.transport, "upterm")
+        self.assertEqual(clearer.endpoint, "wss://relay.example")
+
+        legacy = parser.parse_args(
+            ["open", "--no-accept", "--no-allow-tcp-forwarding", "--confine-sftp"]
+        )
+        self.assertFalse(legacy.accept)
+        self.assertFalse(legacy.allow_tcp_forwarding)
+        self.assertTrue(legacy.confine_sftp)
 
         upgrade = parser.parse_args(["upgrade"])
         self.assertIsNone(upgrade.version)
@@ -318,13 +342,13 @@ class CLILifecycleTests(unittest.TestCase):
             try:
                 code, out, err = run_cli(
                     [
-                        "open",
+                        "start",
                         str(root),
-                        "--port",
+                        "--ssh-port",
                         str(ssh_port),
-                        "--slot",
+                        "--tunnel-slot",
                         str(relay_forward),
-                        "--transport",
+                        "--provider",
                         "srvus",
                     ],
                     env=env,
@@ -336,28 +360,28 @@ class CLILifecycleTests(unittest.TestCase):
                 self.assertEqual(key.stat().st_mode & 0o777, 0o600)
                 self.assertTrue((state / "password").is_file())
 
-                code, out, err = run_cli(["inspect"], env=env)
+                code, out, err = run_cli(["status"], env=env)
                 self.assertEqual(code, 0)
                 self.assertIn("gateway   running   pid", out)
                 self.assertIn("transport running   pid", out)
                 self.assertIn(f"url       https://{SRVUS_HOST}/", out)
                 self.assertNotIn("\x1b[", out)
-                self.assertIn(f"enter     ssh {getpass.getuser()}@{SRVUS_HOST}", out)
+                self.assertIn(f"connect   ssh {getpass.getuser()}@{SRVUS_HOST}", out)
                 self.assertIn("keys      disabled", out)
-                self.assertNotIn("trace transport -f", out)
+                self.assertNotIn("logs transport -f", out)
 
-                code, out, err = run_cli(["enter"], env=env)
+                code, out, err = run_cli(["connect"], env=env)
                 self.assertEqual(code, 0, err)
                 self.assertIn("openssl s_client", out)
                 self.assertIn("-quiet", out)
                 self.assertIn("-no_ign_eof", out)
                 self.assertIn("Host *.srv.us", out)
 
-                code, out, err = run_cli(["trace", "transport"], env=env)
+                code, out, err = run_cli(["logs", "transport"], env=env)
                 self.assertEqual(code, 0)
                 self.assertIn("remote forward ready", out)
 
-                code, out, err = run_cli(["shut"], env=env)
+                code, out, err = run_cli(["stop"], env=env)
                 self.assertEqual(code, 0)
                 self.assertIn("Nullgate stopped.", out)
             finally:
@@ -367,7 +391,7 @@ class CLILifecycleTests(unittest.TestCase):
                         with contextlib.suppress(OSError):
                             os.kill(pid, 9)
 
-            code, out, err = run_cli(["inspect"], env=env)
+            code, out, err = run_cli(["status"], env=env)
             self.assertEqual(code, 1)
             self.assertIn("gateway   stopped", out)
             self.assertIn("transport stopped", out)
@@ -483,7 +507,7 @@ class CLILifecycleTests(unittest.TestCase):
                 )
             )
             code, out, err = run_cli(["inspect"], env=env)
-            self.assertIn("auth      none (--accept); anyone can connect", out)
+            self.assertIn("auth      none (--public-access); anyone can connect", out)
 
     def test_open_refuses_occupied_port(self):
         with tempfile.TemporaryDirectory() as temp:
@@ -548,7 +572,7 @@ class CLILifecycleTests(unittest.TestCase):
             env = make_env(home, state_base)
             code, out, err = run_cli(["cycle"], env=env)
             self.assertNotEqual(code, 0)
-            self.assertIn("No saved configuration found to cycle", err)
+            self.assertIn("No saved settings found", err)
 
     def test_inspect_non_tty_has_no_ansi(self):
         with tempfile.TemporaryDirectory() as temp:
@@ -572,8 +596,8 @@ class CLILifecycleTests(unittest.TestCase):
             code, out, err = run_cli(["inspect"], env=env)
             self.assertNotIn("\x1b[", out)
             self.assertIn("url       ssh://glacier.vctx.io", out)
-            self.assertIn("first time here: nullgate enter", out)
-            code, out, err = run_cli(["enter"], env=env)
+            self.assertIn("first time here: nullgate connect", out)
+            code, out, err = run_cli(["connect"], env=env)
             self.assertEqual(code, 0, err)
             self.assertIn("cloudflared must be installed", out)
             self.assertNotIn("\x1b[", out)

nullgate-1.1.1/src/nullgate/__init__.py

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

nullgate-1.1.1/src/nullgate/commands.py

@@ -1,179 +0,0 @@
-"""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.",
-        help="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.",
-        help="Halt running gateway and transport services.",
-    )
-
-    sub.add_parser(
-        "inspect",
-        description="Display service health, access URLs, and authentication status.",
-        help="Display service health, access URLs, and authentication status.",
-    )
-
-    sub.add_parser(
-        "enter",
-        description="Show SSH connection strings and client setup commands.",
-        help="Show SSH connection strings and client setup commands.",
-    )
-
-    trace_parser = sub.add_parser(
-        "trace",
-        description="View or stream service operational logs.",
-        help="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.",
-        help="Restart services using active or saved configuration.",
-    )
-
-    upgrade_parser = sub.add_parser(
-        "upgrade",
-        description="Fetch and install latest Nullgate release.",
-        help="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())