nullgate 1.2.4__tar.gz → 1.2.5__tar.gz

{nullgate-1.2.4/src/nullgate.egg-info → nullgate-1.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nullgate
-Version: 1.2.4
+Version: 1.2.5
 Summary: Disposable SSH gateway into confined directory workspaces
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -36,8 +36,9 @@ uvx nullgate status
 uvx nullgate connect
 ```
 
-Nullgate allows connections without credentials by default. Use
-`--no-public-access` to require an authorized SSH key or generated password.
+Nullgate requires authentication by default (an authorized SSH key and/or a
+generated password). Pass `--public-access` to allow connections without
+credentials (unsafe on public endpoints).
 
 ## Features
 
@@ -71,7 +72,9 @@ pip install nullgate
 
 ### Start
 
-Launch the gateway service and ingress transport in the background:
+Start the gateway service and ingress transport, then report readiness once the
+gateway listens, the transport stays alive, and srv.us has announced a
+hostname (for that provider):
 
 ```bash
 # Default srv.us transport on port 4822 sharing current directory
@@ -97,12 +100,22 @@ Options:
 - `-e`, `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
 - `-H`, `--public-hostname`: Public hostname used with `cloudflared`.
 - `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
-- `--public-access`: Allow connections without credentials. Enabled by default and unsafe on public endpoints.
+- `--identity-seed VALUE`: srv.us identity seed value (visible in argv and shell history; flag overrides seed file and `NULLGATE_IDENTITY_SEED`; other providers ignore it). Prefer `--identity-seed-file PATH` to avoid history exposure. The direct value is never printed or saved; `restart` cannot reuse it because only the seed-file path is persisted. The seed only matters when the identity key does not yet exist.
+- `--identity-seed-file PATH`: Read the srv.us identity seed from a file (overrides `NULLGATE_IDENTITY_SEED`; other providers ignore it). The file must hold nonempty UTF-8 text; only the path is saved for `restart`, never the seed value. `restart` revalidates the saved file before stopping the running session. The seed only matters when the identity key does not yet exist.
+- `--public-access`: Allow connections without credentials (unsafe on public endpoints). Off by default; only `restart` reuses a saved setting, a fresh `start` always defaults to authenticated access.
 - `--no-public-access`: Require authentication.
-- `--tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
-- `--no-tcp-forwarding`: Disable SSH TCP tunneling.
+- `--tcp-forwarding`: Allow SSH TCP tunneling (`ssh -L`; enabled by default on fresh `start`).
+- `--no-tcp-forwarding`: Disable SSH TCP tunneling. `restart` reuses the saved effective setting.
 - `--restrict-file-transfer`: Keep SFTP and SCP inside the workspace.
 - `--no-restrict-file-transfer`: Allow host-visible file transfers.
+- `--foreground`: Stay in the foreground and supervise gateway and transport instead of exiting after readiness. The parent handles SIGINT and SIGTERM and stops both children, exiting nonzero with recent log tails if either child dies.
+- `--json`: Emit machine-readable JSON on stdout (the only stdout in JSON mode). `start --foreground --json` prints one readiness object, flushes it, then supervises.
+
+A fresh `start` uses documented defaults and the current directory when no
+workspace is given; only `restart` reuses saved workspace, provider, port,
+and security settings. Only the hidden external-launcher flags `--notte-api`
+(boolean) and `--notte-user VALUE` are accepted for compatibility; any other
+unknown flag fails normally.
 
 ### Status
 
@@ -110,16 +123,26 @@ Display operational status, running PIDs, connection URLs, and security settings
 
 ```bash
 nullgate status
+nullgate status --json
 ```
 
+When stdout is not a TTY, `status` emits only a directly usable SSH fallback
+command plus a `password: VALUE` line when a generated password exists; with no
+live target it prints `stopped` or `pending`. `--json` is the stable full
+machine interface.
+
 ### Connect
 
 Print client connection strings and OpenSSH client configuration directives:
 
 ```bash
 nullgate connect
+nullgate connect --json
 ```
 
+On an interactive TTY `connect` keeps the setup instructions; piped output
+emits only the directly usable fallback command.
+
 ### Logs
 
 Stream or print daemon logs:
@@ -141,7 +164,10 @@ nullgate stop
 
 ### Restart
 
-Restart daemon instances reusing active or saved workspace settings:
+Restart daemon instances reusing the saved workspace, provider, port, and
+security settings from the previous start. A direct `--identity-seed` value
+from the original start is intentionally not persisted, so `restart` cannot
+reuse it; only the seed-file path is saved and revalidated.
 
 ```bash
 nullgate restart
@@ -160,12 +186,12 @@ Short command aliases are `up`, `down`, `ps`, `ssh`, `log`, and `reload`.
 The earlier 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.
-Unknown flags and their optional values are ignored for compatibility with
-external launchers.
+Unknown flags fail normally; only the hidden external-launcher flags
+`--notte-api` (boolean) and `--notte-user VALUE` are accepted as no-ops.
 
 ## Authentication and Security Boundaries
 
-- **Authentication Baseline**: Public access is enabled by default. Pass `--no-public-access` to require authorized SSH keys from `~/.ssh/authorized_keys` or a high-entropy secret created in the runtime directory.
+- **Authentication Baseline**: Authenticated access is the default. Pass `--public-access` to allow connections without credentials (unsafe on public endpoints). Without it, srv.us secure startup uses authorized SSH keys from `~/.ssh/authorized_keys` and/or a generated high-entropy password stored in the runtime directory.
 - **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.
@@ -179,7 +205,7 @@ external launchers.
 |---|---|
 | `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_IDENTITY_SEED` | Seed for deterministic Ed25519 key derivation; only used when creating the identity file, never when it already exists |
 | `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 |
@@ -187,6 +213,42 @@ external launchers.
 | `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` |
+| `NO_COLOR` | Set to any value to disable ANSI color output (non-TTY output never uses color) |
+
+## Automation/CI
+
+- Noninteractive runs never prompt: with stdin closed or piped, `start` skips
+  the key prompt and generates the password for srv.us secure mode. Upterm
+  secure mode without authorized keys fails immediately instead of hanging.
+- Readiness is decisive: `start` returns success only after the gateway
+  listens, the transport stays alive, and (for srv.us) a hostname is
+  announced. On timeout or failure both processes are stopped, recent
+  transport logs go to stderr, and the exit code is nonzero.
+- `start --foreground` keeps the parent alive supervising both children,
+  handles SIGINT/SIGTERM by stopping them, and exits nonzero with recent log tails if
+  either child dies. Background start remains the default.
+- `start`, `status`, and `connect` accept `--json` for machine-readable
+  output. JSON is the only stdout in JSON mode and carries the operational
+  fields agents need: version, provider, running state and PIDs, port,
+  workspace, URL, host, user, proxy command, auth mode, TCP forwarding, and
+  file-transfer mode. `--json` is the stable agent contract; human output may
+  change. `start --foreground --json` prints one readiness object,
+  flushes it, then supervises.
+- Piped output is compact: successful `start`, `status`, and `connect` with a
+  target emit only a directly usable SSH fallback command plus one
+  `password: VALUE` line when a generated password exists. With no live
+  usable target, `status` prints `stopped` or `pending`.
+- Identity seeds: `--identity-seed-file PATH` keeps the value out of argv
+and history (flag overrides `NULLGATE_IDENTITY_SEED`); `--identity-seed
+VALUE` is also accepted but is visible in argv and shell history. Both apply
+only to the srv.us provider, fail before launch when absent, unreadable, or
+empty (direct value: nonempty after stripping), pass the seed only to the
+srv.us child environment (every other child gets a seed-free environment even
+when the parent exported one), and never print or persist the value. Only the
+seed-file path is saved for `restart`, which revalidates the saved srv.us seed
+file before stopping anything; a direct `--identity-seed` from the original
+start is intentionally not persisted, so `restart` cannot reuse it. The seed
+only takes effect when the identity key does not yet exist.
 
 ## Development
 

{nullgate-1.2.4 → nullgate-1.2.5}/README.md

@@ -24,8 +24,9 @@ uvx nullgate status
 uvx nullgate connect
 ```
 
-Nullgate allows connections without credentials by default. Use
-`--no-public-access` to require an authorized SSH key or generated password.
+Nullgate requires authentication by default (an authorized SSH key and/or a
+generated password). Pass `--public-access` to allow connections without
+credentials (unsafe on public endpoints).
 
 ## Features
 
@@ -59,7 +60,9 @@ pip install nullgate
 
 ### Start
 
-Launch the gateway service and ingress transport in the background:
+Start the gateway service and ingress transport, then report readiness once the
+gateway listens, the transport stays alive, and srv.us has announced a
+hostname (for that provider):
 
 ```bash
 # Default srv.us transport on port 4822 sharing current directory
@@ -85,12 +88,22 @@ Options:
 - `-e`, `--relay-url`: WebSocket relay URL used with `upterm` or `cloudflare`.
 - `-H`, `--public-hostname`: Public hostname used with `cloudflared`.
 - `--cloudflare-token`: Cloudflare tunnel credential, or set `NULLGATE_CLOUDFLARED_TOKEN`.
-- `--public-access`: Allow connections without credentials. Enabled by default and unsafe on public endpoints.
+- `--identity-seed VALUE`: srv.us identity seed value (visible in argv and shell history; flag overrides seed file and `NULLGATE_IDENTITY_SEED`; other providers ignore it). Prefer `--identity-seed-file PATH` to avoid history exposure. The direct value is never printed or saved; `restart` cannot reuse it because only the seed-file path is persisted. The seed only matters when the identity key does not yet exist.
+- `--identity-seed-file PATH`: Read the srv.us identity seed from a file (overrides `NULLGATE_IDENTITY_SEED`; other providers ignore it). The file must hold nonempty UTF-8 text; only the path is saved for `restart`, never the seed value. `restart` revalidates the saved file before stopping the running session. The seed only matters when the identity key does not yet exist.
+- `--public-access`: Allow connections without credentials (unsafe on public endpoints). Off by default; only `restart` reuses a saved setting, a fresh `start` always defaults to authenticated access.
 - `--no-public-access`: Require authentication.
-- `--tcp-forwarding`: Enable SSH TCP tunneling (`ssh -L`).
-- `--no-tcp-forwarding`: Disable SSH TCP tunneling.
+- `--tcp-forwarding`: Allow SSH TCP tunneling (`ssh -L`; enabled by default on fresh `start`).
+- `--no-tcp-forwarding`: Disable SSH TCP tunneling. `restart` reuses the saved effective setting.
 - `--restrict-file-transfer`: Keep SFTP and SCP inside the workspace.
 - `--no-restrict-file-transfer`: Allow host-visible file transfers.
+- `--foreground`: Stay in the foreground and supervise gateway and transport instead of exiting after readiness. The parent handles SIGINT and SIGTERM and stops both children, exiting nonzero with recent log tails if either child dies.
+- `--json`: Emit machine-readable JSON on stdout (the only stdout in JSON mode). `start --foreground --json` prints one readiness object, flushes it, then supervises.
+
+A fresh `start` uses documented defaults and the current directory when no
+workspace is given; only `restart` reuses saved workspace, provider, port,
+and security settings. Only the hidden external-launcher flags `--notte-api`
+(boolean) and `--notte-user VALUE` are accepted for compatibility; any other
+unknown flag fails normally.
 
 ### Status
 
@@ -98,16 +111,26 @@ Display operational status, running PIDs, connection URLs, and security settings
 
 ```bash
 nullgate status
+nullgate status --json
 ```
 
+When stdout is not a TTY, `status` emits only a directly usable SSH fallback
+command plus a `password: VALUE` line when a generated password exists; with no
+live target it prints `stopped` or `pending`. `--json` is the stable full
+machine interface.
+
 ### Connect
 
 Print client connection strings and OpenSSH client configuration directives:
 
 ```bash
 nullgate connect
+nullgate connect --json
 ```
 
+On an interactive TTY `connect` keeps the setup instructions; piped output
+emits only the directly usable fallback command.
+
 ### Logs
 
 Stream or print daemon logs:
@@ -129,7 +152,10 @@ nullgate stop
 
 ### Restart
 
-Restart daemon instances reusing active or saved workspace settings:
+Restart daemon instances reusing the saved workspace, provider, port, and
+security settings from the previous start. A direct `--identity-seed` value
+from the original start is intentionally not persisted, so `restart` cannot
+reuse it; only the seed-file path is saved and revalidated.
 
 ```bash
 nullgate restart
@@ -148,12 +174,12 @@ Short command aliases are `up`, `down`, `ps`, `ssh`, `log`, and `reload`.
 The earlier 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.
-Unknown flags and their optional values are ignored for compatibility with
-external launchers.
+Unknown flags fail normally; only the hidden external-launcher flags
+`--notte-api` (boolean) and `--notte-user VALUE` are accepted as no-ops.
 
 ## Authentication and Security Boundaries
 
-- **Authentication Baseline**: Public access is enabled by default. Pass `--no-public-access` to require authorized SSH keys from `~/.ssh/authorized_keys` or a high-entropy secret created in the runtime directory.
+- **Authentication Baseline**: Authenticated access is the default. Pass `--public-access` to allow connections without credentials (unsafe on public endpoints). Without it, srv.us secure startup uses authorized SSH keys from `~/.ssh/authorized_keys` and/or a generated high-entropy password stored in the runtime directory.
 - **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.
@@ -167,7 +193,7 @@ external launchers.
 |---|---|
 | `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_IDENTITY_SEED` | Seed for deterministic Ed25519 key derivation; only used when creating the identity file, never when it already exists |
 | `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 |
@@ -175,6 +201,42 @@ external launchers.
 | `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` |
+| `NO_COLOR` | Set to any value to disable ANSI color output (non-TTY output never uses color) |
+
+## Automation/CI
+
+- Noninteractive runs never prompt: with stdin closed or piped, `start` skips
+  the key prompt and generates the password for srv.us secure mode. Upterm
+  secure mode without authorized keys fails immediately instead of hanging.
+- Readiness is decisive: `start` returns success only after the gateway
+  listens, the transport stays alive, and (for srv.us) a hostname is
+  announced. On timeout or failure both processes are stopped, recent
+  transport logs go to stderr, and the exit code is nonzero.
+- `start --foreground` keeps the parent alive supervising both children,
+  handles SIGINT/SIGTERM by stopping them, and exits nonzero with recent log tails if
+  either child dies. Background start remains the default.
+- `start`, `status`, and `connect` accept `--json` for machine-readable
+  output. JSON is the only stdout in JSON mode and carries the operational
+  fields agents need: version, provider, running state and PIDs, port,
+  workspace, URL, host, user, proxy command, auth mode, TCP forwarding, and
+  file-transfer mode. `--json` is the stable agent contract; human output may
+  change. `start --foreground --json` prints one readiness object,
+  flushes it, then supervises.
+- Piped output is compact: successful `start`, `status`, and `connect` with a
+  target emit only a directly usable SSH fallback command plus one
+  `password: VALUE` line when a generated password exists. With no live
+  usable target, `status` prints `stopped` or `pending`.
+- Identity seeds: `--identity-seed-file PATH` keeps the value out of argv
+and history (flag overrides `NULLGATE_IDENTITY_SEED`); `--identity-seed
+VALUE` is also accepted but is visible in argv and shell history. Both apply
+only to the srv.us provider, fail before launch when absent, unreadable, or
+empty (direct value: nonempty after stripping), pass the seed only to the
+srv.us child environment (every other child gets a seed-free environment even
+when the parent exported one), and never print or persist the value. Only the
+seed-file path is saved for `restart`, which revalidates the saved srv.us seed
+file before stopping anything; a direct `--identity-seed` from the original
+start is intentionally not persisted, so `restart` cannot reuse it. The seed
+only takes effect when the identity key does not yet exist.
 
 ## Development
 

nullgate-1.2.5/src/nullgate/__init__.py

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

{nullgate-1.2.4 → nullgate-1.2.5}/src/nullgate/commands.py

@@ -118,7 +118,7 @@ def build_parser() -> argparse.ArgumentParser:
         dest="allow_tcp_forwarding",
         action=argparse.BooleanOptionalAction,
         default=None,
-        help="Allow SSH port forwarding.",
+        help="Allow SSH port forwarding (enabled by default; --no-tcp-forwarding disables).",
     )
     start_parser.add_argument(
         "--allow-tcp-forwarding",
@@ -161,6 +161,43 @@ def build_parser() -> argparse.ArgumentParser:
         help="Cloudflare tunnel token (for the cloudflared provider).",
     )
     start_parser.add_argument("--token", dest="token", help=argparse.SUPPRESS)
+    seed_group = start_parser.add_mutually_exclusive_group()
+    seed_group.add_argument(
+        "--identity-seed",
+        dest="identity_seed",
+        metavar="VALUE",
+        default=None,
+        help="srv.us identity seed value (visible in argv/history; ignored by other providers).",
+    )
+    seed_group.add_argument(
+        "--identity-seed-file",
+        dest="identity_seed_file",
+        metavar="PATH",
+        default=None,
+        help="File holding the srv.us identity seed (overrides NULLGATE_IDENTITY_SEED; ignored by other providers).",
+    )
+    start_parser.add_argument(
+        "--foreground",
+        dest="foreground",
+        action="store_true",
+        help="Stay in the foreground and supervise gateway and transport.",
+    )
+    start_parser.add_argument(
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Emit machine-readable JSON on stdout.",
+    )
+    start_parser.add_argument(
+        "--notte-api", dest="notte_api", action="store_true", help=argparse.SUPPRESS
+    )
+    start_parser.add_argument(
+        "--notte-user",
+        dest="notte_user",
+        metavar="VALUE",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
 
     sub.add_parser(
         "stop",
@@ -169,19 +206,31 @@ def build_parser() -> argparse.ArgumentParser:
         help="Stop SSH access (aliases: down, shut).",
     )
 
-    sub.add_parser(
+    status_parser = sub.add_parser(
         "status",
         aliases=["ps", "inspect"],
         description="Show service health, connection details, and security settings.",
         help="Show current status (aliases: ps, inspect).",
     )
+    status_parser.add_argument(
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Emit machine-readable JSON on stdout.",
+    )
 
-    sub.add_parser(
+    connect_parser = sub.add_parser(
         "connect",
         aliases=["ssh", "enter"],
         description="Show how to connect with SSH.",
         help="Show SSH connection instructions (aliases: ssh, enter).",
     )
+    connect_parser.add_argument(
+        "--json",
+        dest="json",
+        action="store_true",
+        help="Emit machine-readable JSON on stdout.",
+    )
 
     logs_parser = sub.add_parser(
         "logs",
@@ -236,47 +285,12 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _known_options(parser: argparse.ArgumentParser) -> set[str]:
-    options = set(parser._option_string_actions)
-    for action in parser._actions:
-        if isinstance(action, argparse._SubParsersAction):
-            for child in action.choices.values():
-                options.update(_known_options(child))
-    return options
-
-
-def _discard_unknown_options(
-    parser: argparse.ArgumentParser, argv: Sequence[str]
-) -> list[str]:
-    """Drop integration flags, including a following value when present."""
-
-    known = _known_options(parser)
-    filtered: list[str] = []
-    index = 0
-    while index < len(argv):
-        token = argv[index]
-        option = token.split("=", 1)[0]
-        if token.startswith("-") and option not in known:
-            index += 1
-            if (
-                "=" not in token
-                and index < len(argv)
-                and not argv[index].startswith("-")
-                and argv[index] not in SUBCOMMANDS
-            ):
-                index += 1
-            continue
-        filtered.append(token)
-        index += 1
-    return filtered
-
-
 def main(argv: Sequence[str] | None = None) -> int:
     parser = build_parser()
     supplied = list(sys.argv[1:] if argv is None else argv)
     if supplied in (["--help"], ["api", "--help"]):
         supplied = ["start"]
-    args = parser.parse_args(_discard_unknown_options(parser, supplied))
+    args = parser.parse_args(supplied)
 
     handlers = {
         "start": session.cmd_open,