ssh-tunnel-cli 0.1.1__py3-none-any.whl

ssh_tunnel_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: ssh-tunnel-cli
+Version: 0.1.1
+Summary: Guided local SSH tunnels using your existing OpenSSH configuration
+Project-URL: Repository, https://github.com/maneeshv/ssh-tunnel-cli
+Project-URL: Issues, https://github.com/maneeshv/ssh-tunnel-cli/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet
+Requires-Python: >=3.11
+Requires-Dist: prompt-toolkit==3.0.53
+Requires-Dist: questionary==2.1.1
+Description-Content-Type: text/markdown
+
+# tunnel
+
+Create and manage local SSH tunnels without remembering forwarding syntax. Pick an alias from your SSH config, answer the prompts, review the exact commands, and choose **Start tunnel**.
+
+Python + Questionary, using your Mac's existing OpenSSH client for connections and authentication. No remote agent or installed manager service.
+
+## Install
+
+Requires macOS, Python 3.11 or later, [uv](https://docs.astral.sh/uv/), and `/usr/bin/ssh`.
+
+```sh
+uv tool install ssh-tunnel-cli
+tunnel
+```
+
+Alternatively, use `pipx install ssh-tunnel-cli`, or `python -m pip install ssh-tunnel-cli` inside a virtual environment. The Python package exposes the same `tunnel` command.
+
+If your shell cannot find `tunnel`, run `uv tool update-shell` and restart the shell.
+
+To run or develop from a checkout:
+
+```sh
+git clone https://github.com/maneeshv/ssh-tunnel-cli.git
+cd ssh-tunnel-cli
+uv sync --locked
+uv run tunnel
+```
+
+From that checkout, `uv tool install .` installs the command for everyday use.
+
+Your config must already contain a literal alias, for example:
+
+```sshconfig
+Host other-mac
+    HostName your-other-machine
+    User your-username
+```
+
+Configure and verify SSH access yourself first. `tunnel` does not edit SSH config, set up Tailscale, or save credentials. Add hosts to your config manually and reload the picker.
+
+## Use
+
+- **New tunnel:** machine → remote app port → local port → destination → mode → review.
+- **Background:** returns to the shell; SSH keeps running after that terminal closes.
+- **Foreground:** remains attached; Ctrl+C stops this tunnel.
+- **Manage tunnels:** inspect commands and diagnostics, stop, or review a restart.
+- **Recent tunnels:** reuse successful settings, with a fresh review before connecting.
+- **Esc:** back, retaining answers. **Ctrl+C:** cancel. Arrow keys select; type to filter the host picker.
+
+```sh
+tunnel list
+tunnel stop
+tunnel restart
+tunnel --help
+```
+
+The app port is different from the SSH server port. SSH's server port comes from your configuration. The destination `127.0.0.1` means loopback **on the selected remote machine**; the local listener is always `127.0.0.1` **on this Mac**. No public/LAN bind option is provided.
+
+**Running means SSH is active, not that the remote app is healthy.** Browser opening is optional and only appropriate for web apps. Tailscale is optional existing connectivity, not something this utility configures or guarantees.
+
+## Connection ownership
+
+Every attempt has its own private control socket. The reviewed launch has two commands: first start an isolated SSH connection with inherited forwards cleared, then add the one selected local forward through that socket. This avoids accidentally launching forwards defined elsewhere in SSH configuration. SSH continues to resolve keys, users, jump hosts, and authentication settings. LocalCommand, agent/X11 forwarding, tunnel devices, and persistent/shared control settings are overridden for this utility.
+
+Only tool-owned connections appear in the inventory. Stop never searches by port or kills an arbitrary PID. Closing the menu does not stop a background tunnel. Network failures require a manual restart; no auto-start or reconnect service is installed.
+
+Native SSH authentication and host-key prompts appear only after Start. User SSH config is trusted: connection configuration such as ProxyCommand or Match exec can execute its configured commands at connection time. Host discovery itself does not execute those directives.
+
+## State and limitations
+
+Records, a lock file, SSH control sockets, and diagnostics live in `~/.tunnel/`, with owner-only permissions. Override the location with `--state-dir`; use `--config` for a separate SSH config. A short state path is required by Unix control-socket limits. An unsafe or corrupt state store is reported and preserved, not silently repaired or discarded.
+
+Host discovery supports literal ASCII aliases and ordinary nested/globbed Includes. Conditional Includes and paths containing SSH tokens or environment expansions are skipped with a warning that the list may be incomplete. Wildcard/negated Host patterns are not selectable machines. Relative user Includes resolve under `~/.ssh`, including when `--config` points elsewhere, matching OpenSSH.
+
+Diagnostics contain SSH errors, not remote application logs or typed authentication input. Each log is trimmed to its last 64 KiB when viewed. Without a background manager, logs can grow between views. Old records and diagnostics remain in the private state directory; no automatic history deletion is performed.
+
+Foreground/background lifecycle is macOS-first. Other operating systems and every OpenSSH configuration combination are not promised.
+
+## Verify
+
+Unit and prompt tests (no real hosts):
+
+```sh
+uv run python -m unittest discover -s tests -v
+```
+
+Opt-in integration tests start an isolated loopback `sshd`, generate disposable keys, and exercise actual forwarding. They do not read your SSH keys or configuration, change system SSH settings, or contact remote machines. They require permission to bind/connect loopback ports, `/usr/sbin/sshd`, `/usr/bin/ssh-keygen`, and `trash` for fixture cleanup.
+
+```sh
+TUNNEL_SSH_INTEGRATION=1 uv run python -m unittest tests.test_ssh_integration -v
+```
+
+See [the specification](https://github.com/maneeshv/ssh-tunnel-cli/blob/main/SPEC.md) for requirements, decisions, and the [original Warp mockup](https://github.com/maneeshv/ssh-tunnel-cli/blob/main/design/tunnel-mockup.png). The mockup is a design reference, not a screenshot of the implemented terminal UI.
+
+Verified on 2026-11-04 with Python 3.11.11 and macOS OpenSSH 10.3p1: all 73 tests passed, including 12 real-SSH integration tests. The wheel and source archive build successfully, and the wheel's CLI runs independently of the source checkout. Menus were inspected in a 96-column terminal with color disabled. Manual Warp rendering and password/passphrase authentication were not checked; generated-key authentication and native host-key confirmation were exercised through a PTY.
+
+## TypeScript comparison
+
+A separate [TypeScript alternative](https://github.com/maneeshv/ssh-tunnel-cli/tree/main/typescript-version) is available for comparison. Run `npm ci && npm run build && npm start` from `typescript-version/`. It uses the `tunnel-ts` command and its own state directory; npm publication is pending evaluation.
+
+## Contributing
+
+Small fixes and improvements are welcome. Open an issue for substantial behavior changes before implementing them. Use absolute imports, keep dependencies minimal, and run the checks above before submitting a pull request. Include a regression test for behavior changes. CI runs unit/prompt tests and package smoke checks on macOS; real-SSH tests remain opt-in.
+
+When reporting a bug, include the macOS, Python, and OpenSSH versions and sanitized reproduction steps. Remove hostnames, usernames, addresses, credentials, and private configuration from pasted diagnostics.
+
+## License
+
+[MIT](https://github.com/maneeshv/ssh-tunnel-cli/blob/main/LICENSE). The mockup is an AI-generated design reference; the project is not affiliated with Warp.

ssh_tunnel_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+tunnel_cli/__init__.py,sha256=NBntThTKm44yTq_eM_WoRJPUb4INAxZPsOnz0i6dSEc,60
+tunnel_cli/cli.py,sha256=IrqWezGYlRyh7hQKkDvLSJw5ole4j7wk0c_DYH9y2o4,12953
+tunnel_cli/config.py,sha256=Ie9xf47vkqB6VWhBpTXxnqsGe2IJ5JJuUkZWyP2xpWA,4763
+tunnel_cli/core.py,sha256=jCjfsYkaurVLD4tlBL0R-kY9TEXGRIdyZzaIBa3n8qo,19003
+tunnel_cli/prompts.py,sha256=py_hWnyFTK5YVOojHAov-YFccn4wtsb0TeYjsklw2H0,4443
+ssh_tunnel_cli-0.1.1.dist-info/METADATA,sha256=SN7RTqacPQdrEep-t_cPH0xNALGzHzOkPLkQiIupRJ4,7817
+ssh_tunnel_cli-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+ssh_tunnel_cli-0.1.1.dist-info/entry_points.txt,sha256=9MTJNX4HXvKedLmEekeLC3-QOv2pLiX7N6pIeDSQv0s,47
+ssh_tunnel_cli-0.1.1.dist-info/licenses/LICENSE,sha256=UeK6aVwkxvwo_r9FUsupT345hKjgzrtP3DXbBQSAB0g,1064
+ssh_tunnel_cli-0.1.1.dist-info/RECORD,,

ssh_tunnel_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ssh_tunnel_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tunnel = tunnel_cli.cli:main

ssh_tunnel_cli-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maneesh
+
+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.

tunnel_cli/__init__.py

@@ -0,0 +1 @@
+"""Interactive local forwards managed by system OpenSSH."""

tunnel_cli/cli.py

@@ -0,0 +1,263 @@
+"""Guided setup and management, with no connection before a reviewed Start."""
+
+import argparse
+from pathlib import Path
+import shlex
+import shutil
+import sys
+import textwrap
+import webbrowser
+
+from questionary import Choice
+
+from tunnel_cli.config import discover_hosts
+from tunnel_cli.core import Manager, Settings, TunnelError, available_port, validate_destination, validate_port
+from tunnel_cli.prompts import Back, choose, say, text
+
+
+def label(record: dict) -> str:
+    s = record["settings"]
+    return f"{s['alias']}  127.0.0.1:{s['local_port']} → {s['destination']}:{s['remote_port']}  {record['status']}"
+
+
+def show_commands(record: dict):
+    say("\nExact commands — private SSH connection, then the selected forward:")
+    width = max(40, shutil.get_terminal_size().columns - 4)
+    for index, command in enumerate(record["commands"], 1):
+        say(textwrap.fill(shlex.join(command), width=width,
+                          initial_indent=f"  {index}. ", subsequent_indent="     ",
+                          break_long_words=False, break_on_hyphens=False))
+
+
+def show_details(record: dict):
+    say(f"\n{label(record)}\nID: {record['id']}\nMode: {record['settings']['mode']}\nCreated: {record['created_at']}")
+    if record.get("last_error"):
+        say(f"Last diagnostic: {record['last_error']}")
+    say("Running describes the SSH tunnel; application health is not checked.")
+
+
+def _host(manager: Manager, default: str | None):
+    while True:
+        discovery = discover_hosts(manager.config_path)
+        for warning in discovery.warnings:
+            say(f"Warning: {warning}")
+        if discovery.aliases:
+            return choose("Choose a machine", discovery.aliases,
+                          default=default if default in discovery.aliases else None, search=True)
+        say("No literal SSH aliases found. Add a Host alias to your SSH config manually, then reload.")
+        if choose("Next", ["Reload hosts", "Back"]) == "Back":
+            raise Back
+
+
+def same_route(first: dict, second: dict) -> bool:
+    return all(first[key] == second[key] for key in ("alias", "local_port", "remote_port", "destination"))
+
+
+def _started(record: dict):
+    settings = record["settings"]
+    say(f"\nTunnel running in {settings['mode']}: 127.0.0.1:{settings['local_port']}\nID: {record['id']}")
+    say("Tunnel active; application health not checked.")
+    if settings["mode"] == "foreground":
+        say("Ctrl+C stops this tunnel.")
+
+
+def run_wizard(manager: Manager, initial: dict | None = None, restart: dict | None = None) -> bool:
+    answers = dict(initial or {})
+    step = 5 if initial else 0
+    editing = False
+    fields = ["Machine", "Remote port", "Local port", "Destination", "Run mode"]
+    while True:
+        try:
+            if step == 0:
+                answers["alias"] = _host(manager, answers.get("alias"))
+            elif step == 1:
+                say("Remote application port — the SSH server port comes from SSH config.")
+                answers["remote_port"] = validate_port(text("Remote port", str(answers.get("remote_port", "")),
+                                                            validate=validate_port))
+            elif step == 2:
+                def local_port(value):
+                    port = validate_port(value)
+                    owned_port = restart and restart["status"] == "Running" and restart["settings"]["local_port"] == port
+                    if not owned_port and not available_port(port):
+                        raise ValueError(f"Port {port} is unavailable. Enter another local port.")
+                    return port
+                answers["local_port"] = validate_port(text("Local port", str(answers.get("local_port", answers["remote_port"])),
+                                                           validate=local_port))
+            elif step == 3:
+                say("127.0.0.1 means the selected remote machine. Advanced: another host/IP reachable from it.")
+                answers["destination"] = validate_destination(text("Destination", answers.get("destination", "127.0.0.1"),
+                                                                   validate=validate_destination))
+            elif step == 4:
+                say("Background returns to your shell. Foreground stays attached until Ctrl+C.")
+                answers["mode"] = choose("How should it run?", [Choice("Background", "background"), Choice("Foreground", "foreground")],
+                                         default=answers.get("mode", "background"))
+            else:
+                record = manager.prepare(Settings(**answers))
+                say("\nReady to start")
+                say(f"  Machine       {answers['alias']}\n  Local         127.0.0.1:{answers['local_port']}"
+                    f"\n  Destination   {answers['destination']}:{answers['remote_port']} on {answers['alias']}"
+                    f"\n  Mode          {answers['mode'].capitalize()}")
+                if restart:
+                    say(f"Restart will stop tunnel {restart['id']} before starting this route. Existing connections will be interrupted.")
+                show_commands(record)
+                action = choose("Review", ["Start tunnel", "Edit settings", "Cancel"])
+                if action == "Cancel":
+                    return False
+                if action == "Edit settings":
+                    editing = True
+                    step = choose("Edit which setting?", [Choice(name, index) for index, name in enumerate(fields)])
+                    continue
+                current = manager.records()
+                for existing in current:
+                    if existing["status"] == "Running" and same_route(existing["settings"], answers) and (not restart or existing["id"] != restart["id"]):
+                        say("That route is already running. Opening its management actions.")
+                        return manage(manager, existing["id"])
+                if restart:
+                    if answers["alias"] not in discover_hosts(manager.config_path).aliases:
+                        raise TunnelError("Selected alias is no longer discoverable. Edit Machine before restarting; existing tunnel was left running.")
+                    original = next((item for item in current if item["id"] == restart["id"]), None)
+                    owns_port = original and original["status"] == "Running" and original["settings"]["local_port"] == answers["local_port"]
+                    if not owns_port and not available_port(answers["local_port"]):
+                        raise TunnelError("Replacement port is unavailable. Edit Local port; existing tunnel was left running.")
+                    manager.stop(restart["id"])
+                    restart = None
+                say(f"Connecting to {answers['alias']}… SSH may request authentication.")
+                result = manager.start(record, on_started=_started)
+                if answers["mode"] == "foreground":
+                    say(f"Tunnel {result['status'].lower()}.")
+                else:
+                    try:
+                        action = choose("Next", ["Return to shell", "Open as HTTP website", "Open as HTTPS website"])
+                        if action != "Return to shell":
+                            scheme = "https" if action == "Open as HTTPS website" else "http"
+                            if not webbrowser.open(f"{scheme}://127.0.0.1:{answers['local_port']}"):
+                                say("Could not open the browser. Open the local address manually.")
+                    except (Back, KeyboardInterrupt):
+                        say("Tunnel remains running in the background.")
+                return True
+            step = 5 if editing else step + 1
+            editing = False
+        except Back:
+            if editing:
+                step, editing = 5, False
+            elif step == 0:
+                return False
+            else:
+                step -= 1
+        except (TunnelError, OSError, ValueError) as exc:
+            say(f"Could not start tunnel: {exc}")
+            # Review is rebuilt for every attempt, so retry cannot reuse a reserved ID.
+
+
+def manage(manager: Manager, tunnel_id: str | None = None, action: str | None = None) -> bool:
+    while True:
+        try:
+            records = manager.records()
+            if not records:
+                say("No managed tunnels yet.")
+                return False
+            if tunnel_id is None:
+                tunnel_id = choose("Manage tunnels", [Choice(label(item), item["id"]) for item in records] + [Choice("Back", "back")])
+                if tunnel_id == "back":
+                    return False
+            record = next((item for item in records if item["id"] == tunnel_id), None)
+            if record is None:
+                raise TunnelError("Tunnel not found. Use tunnel list for managed IDs.")
+            selected = action or choose(label(record), ["Details", "Show command", "View logs", "Stop tunnel", "Restart tunnel", "Back"])
+            if selected == "Details":
+                show_details(record)
+            elif selected == "Show command":
+                show_commands(record)
+            elif selected == "View logs":
+                say(manager.logs(tunnel_id))
+            elif selected in ("Stop tunnel", "stop"):
+                if choose(f"Stop {record['settings']['alias']} on local port {record['settings']['local_port']}?", ["Cancel", "Stop tunnel"]) == "Stop tunnel":
+                    manager.stop(tunnel_id)
+                    say("Tunnel stopped.")
+            elif selected in ("Restart tunnel", "restart"):
+                return run_wizard(manager, record["settings"], restart=record)
+            else:
+                return False
+            if action:
+                return False
+        except Back:
+            return False
+
+
+def recent(manager: Manager) -> bool:
+    records = [item for item in reversed(manager.records()) if item["successful"]]
+    unique = {}
+    for item in records:
+        unique.setdefault(tuple(sorted(item["settings"].items())), item)
+    if not unique:
+        say("No successful tunnels to reuse yet.")
+        return False
+    try:
+        item = choose("Recent tunnels", [Choice(label(record), record) for record in unique.values()])
+        if item["status"] == "Running":
+            return manage(manager, item["id"])
+        return run_wizard(manager, item["settings"])
+    except Back:
+        return False
+
+
+def home(manager: Manager):
+    while True:
+        try:
+            count = sum(item["status"] == "Running" for item in manager.records())
+            choice = choose("What would you like to do?", ["New tunnel", f"Manage tunnels · {count} running", "Recent tunnels", "Exit"])
+            if choice == "Exit":
+                return
+            if choice == "New tunnel":
+                finished = run_wizard(manager)
+            elif choice == "Recent tunnels":
+                finished = recent(manager)
+            else:
+                finished = manage(manager)
+            if finished:
+                return
+        except Back:
+            return
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Guided local SSH tunnels using existing config aliases.")
+    parser.add_argument("--config", type=Path, help="SSH config to use (default: ~/.ssh/config)")
+    parser.add_argument("--state-dir", type=Path, help="Private, short state directory (default: ~/.tunnel)")
+    parser.add_argument("--version", action="version", version="tunnel 0.1.1")
+    commands = parser.add_subparsers(dest="command")
+    commands.add_parser("list", help="Print owned tunnel status without prompting")
+    for name in ("stop", "restart"):
+        command = commands.add_parser(name, help=f"Interactively {name} a managed tunnel")
+        command.add_argument("id", nargs="?", help="Tunnel ID; omit to select interactively")
+    args = parser.parse_args(argv)
+    if args.command != "list" and (not sys.stdin.isatty() or not sys.stdout.isatty()):
+        say("Interactive commands need a terminal. Use tunnel list for noninteractive status.")
+        return 2
+    try:
+        manager = Manager(args.config, args.state_dir)
+        if args.command == "list":
+            records = manager.records()
+            if not records:
+                say("No managed tunnels.")
+            else:
+                say("ID            MACHINE / LOCAL → DESTINATION / STATUS")
+                for record in records:
+                    say(f"{record['id']}  {label(record)}")
+        elif args.command:
+            manage(manager, args.id, args.command)
+        else:
+            home(manager)
+        return 0
+    except KeyboardInterrupt:
+        say("\nCancelled.")
+        return 130
+    except Back:
+        return 0
+    except (TunnelError, OSError, ValueError) as exc:
+        say(f"Error: {exc}")
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tunnel_cli/config.py

@@ -0,0 +1,105 @@
+"""Discover explicit SSH aliases without evaluating SSH conditions or commands."""
+
+import glob
+import re
+import shlex
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Discovery:
+    aliases: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+def is_alias(value: str) -> bool:
+    """Accept literal aliases that cannot be interpreted as SSH options."""
+    return re.fullmatch(r"[A-Za-z0-9_][A-Za-z0-9_.-]*", value) is not None
+
+
+def discover_hosts(config_path: Path | None = None) -> Discovery:
+    """Read aliases, conservatively skipping conditional and dynamic Includes.
+
+    Relative user Includes use ~/.ssh, including with a custom config path.
+    Included Host/Match directives affect the following parent-file lines.
+    This is a discovery reader, not an evaluator of OpenSSH configuration.
+    """
+    config_path = config_path or Path.home() / ".ssh" / "config"
+    base = Path.home() / ".ssh"
+    result = Discovery()
+    seen: set[str] = set()
+    active: set[Path] = set()
+
+    def read(path: Path, unconditional: bool, depth: int) -> bool:
+        try:
+            path = path.resolve()
+            if path in active:
+                result.warnings.append(f"{path}: Include cycle skipped; host list may be incomplete.")
+                return unconditional
+            if depth > 16:
+                result.warnings.append(f"{path}: Include depth limit reached; host list may be incomplete.")
+                return unconditional
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except (OSError, UnicodeError, RuntimeError) as exc:
+            result.warnings.append(f"{path}: Cannot read SSH config ({exc}); host list may be incomplete.")
+            return unconditional
+
+        active.add(path)
+        try:
+            for number, line in enumerate(lines, 1):
+                match = re.match(r"\s*([^\s=#]+)(?:\s*=\s*|\s+)?(.*)", line)
+                if not match:
+                    continue
+                keyword, arguments = match.groups()
+                keyword = keyword.lower()
+                if keyword not in {"host", "match", "include"}:
+                    continue
+                location = f"{path}:{number}"
+                try:
+                    values = shlex.split(arguments, comments=True)
+                    if not values:
+                        raise ValueError("missing argument")
+                except ValueError as exc:
+                    result.warnings.append(f"{location}: Invalid {keyword} ({exc}); host list may be incomplete.")
+                    if keyword in {"host", "match"}:
+                        unconditional = False
+                    continue
+
+                if keyword == "host":
+                    unconditional = values == ["*"]
+                    for alias in values:
+                        if any(character in alias for character in "*?!"):
+                            continue
+                        if not is_alias(alias):
+                            result.warnings.append(f"{location}: Unsupported alias {alias!r} skipped.")
+                        elif alias not in seen:
+                            seen.add(alias)
+                            result.aliases.append(alias)
+                elif keyword == "match":
+                    unconditional = len(values) == 1 and values[0].lower() == "all"
+                elif not unconditional:
+                    result.warnings.append(f"{location}: Conditional Include skipped; host list may be incomplete.")
+                else:
+                    for value in values:
+                        if "$" in value or "%" in value:
+                            result.warnings.append(f"{location}: Dynamic Include {value!r} skipped; host list may be incomplete.")
+                            continue
+                        try:
+                            pattern = Path(value).expanduser()
+                        except (KeyError, RuntimeError) as exc:
+                            result.warnings.append(f"{location}: Cannot expand Include {value!r} ({exc}).")
+                            continue
+                        if not pattern.is_absolute():
+                            pattern = base / pattern
+                        paths = sorted(glob.glob(str(pattern)))
+                        if not paths:
+                            result.warnings.append(f"{location}: Include {value!r} matched no files; host list may be incomplete.")
+                        for included in paths:
+                            unconditional = read(Path(included), unconditional, depth + 1)
+        finally:
+            active.remove(path)
+        return unconditional
+
+    read(config_path.expanduser(), True, 0)
+    return result

tunnel_cli/core.py

@@ -0,0 +1,402 @@
+"""Native SSH lifecycle and private, durable ownership records."""
+
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import errno
+import fcntl
+import ipaddress
+import json
+import os
+from pathlib import Path
+import re
+import signal
+import socket
+import stat
+import subprocess
+import time
+from typing import Callable
+import uuid
+
+from tunnel_cli.config import discover_hosts, is_alias
+
+
+class TunnelError(Exception):
+    """An actionable failure, suitable for displaying without a traceback."""
+
+
+def validate_port(value: str | int) -> int:
+    if isinstance(value, bool) or not re.fullmatch(r"[0-9]{1,5}", str(value)):
+        raise ValueError("Enter a decimal port from 1 to 65535.")
+    port = int(value)
+    if not 1 <= port <= 65535:
+        raise ValueError("Enter a decimal port from 1 to 65535.")
+    return port
+
+
+def validate_destination(value: str) -> str:
+    if not isinstance(value, str):
+        raise ValueError("Destination must be a hostname or IP address string.")
+    try:
+        return str(ipaddress.ip_address(value))
+    except ValueError:
+        if len(value) > 253 or not all(
+            re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?", part)
+            for part in value.rstrip(".").split(".")
+        ):
+            raise ValueError("Enter a hostname or IP address, without a port or URL.") from None
+        return value
+
+
+def available_port(port: int) -> bool:
+    with socket.socket() as listener:
+        try:
+            listener.bind(("127.0.0.1", validate_port(port)))
+        except OSError:
+            return False
+    return True
+
+
+@dataclass(frozen=True)
+class Settings:
+    alias: str
+    remote_port: int
+    local_port: int
+    destination: str = "127.0.0.1"
+    mode: str = "background"
+
+    def __post_init__(self):
+        if not isinstance(self.alias, str) or not is_alias(self.alias):
+            raise ValueError("Choose a literal SSH-config alias.")
+        validate_port(self.remote_port)
+        validate_port(self.local_port)
+        if type(self.remote_port) is not int or type(self.local_port) is not int:
+            raise ValueError("Stored ports must be integers.")
+        validate_destination(self.destination)
+        if self.mode not in ("background", "foreground"):
+            raise ValueError("Run mode must be background or foreground.")
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _interrupt(*_):
+    raise KeyboardInterrupt
+
+
+class Manager:
+    def __init__(self, config_path: Path | None = None, state_dir: Path | None = None):
+        self.config_path = Path(config_path).expanduser().absolute() if config_path else None
+        self.state_dir = Path(state_dir or Path.home() / ".tunnel").expanduser().absolute()
+        self.ssh = "/usr/bin/ssh"
+        if not Path(self.ssh).is_file():
+            raise TunnelError("System OpenSSH was not found at /usr/bin/ssh.")
+        self.state_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        info = self.state_dir.lstat()
+        if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+            raise TunnelError(f"State directory must be owned by you, private (0700), and not a symlink: {self.state_dir}")
+        if len(os.fsencode(self.state_dir / ('0' * 12 + '.sock'))) >= 100:
+            raise TunnelError("State path is too long for SSH control sockets. Choose a shorter --state-dir.")
+
+    def _path(self, tunnel_id: str, suffix: str) -> Path:
+        if not re.fullmatch(r"[0-9a-f]{12}", tunnel_id):
+            raise TunnelError("Invalid tunnel ID.")
+        return self.state_dir / f"{tunnel_id}.{suffix}"
+
+    def _open(self, path: Path, flags: int):
+        fd = os.open(path, flags | os.O_NOFOLLOW | os.O_NONBLOCK, 0o600)
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077 or info.st_nlink != 1:
+            os.close(fd)
+            raise TunnelError(f"Unsafe state file (expected a private regular file): {path}")
+        return fd
+
+    @contextmanager
+    def _locked(self):
+        fd = self._open(self.state_dir / "lock", os.O_RDWR | os.O_CREAT)
+        try:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                raise TunnelError("Another tunnel command is changing state. Try again when it finishes.") from None
+            yield
+        finally:
+            os.close(fd)
+
+    def _read(self) -> list[dict]:
+        try:
+            fd = self._open(self.state_dir / "registry.json", os.O_RDONLY)
+        except FileNotFoundError:
+            return []
+        try:
+            with os.fdopen(fd) as file:
+                data = json.load(file)
+            if data["version"] != 1 or not isinstance(data["tunnels"], list):
+                raise ValueError("unsupported schema")
+            ids = set()
+            for record in data["tunnels"]:
+                self._path(record["id"], "sock")
+                if record["id"] in ids:
+                    raise ValueError("duplicate tunnel ID")
+                ids.add(record["id"])
+                Settings(**record["settings"])
+                if not isinstance(record["created_at"], str):
+                    raise ValueError("invalid creation time")
+                if record.get("last_error") is not None and not isinstance(record["last_error"], str):
+                    raise ValueError("invalid diagnostic")
+                if record["status"] not in ("Connecting", "Running", "Stopped", "Disconnected", "Failed", "Unknown"):
+                    raise ValueError("unknown status")
+                if not isinstance(record["successful"], bool) or not isinstance(record["commands"], list):
+                    raise ValueError("invalid record")
+                if not record["commands"] or any(
+                    not isinstance(command, list) or not command or not all(isinstance(arg, str) for arg in command)
+                    for command in record["commands"]
+                ):
+                    raise ValueError("invalid saved command")
+            return data["tunnels"]
+        except (ValueError, TypeError, KeyError, TunnelError) as exc:
+            raise TunnelError(f"Cannot read registry; preserved it unchanged: {exc}") from exc
+
+    def _save(self, records: list[dict]):
+        pending = self.state_dir / "registry.pending"
+        fd = self._open(pending, os.O_WRONLY | os.O_CREAT)
+        with os.fdopen(fd, "w") as file:
+            file.truncate(0)
+            json.dump({"version": 1, "tunnels": records}, file, indent=2)
+            file.flush()
+            os.fsync(file.fileno())
+        os.replace(pending, self.state_dir / "registry.json")
+        directory = os.open(self.state_dir, os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+
+    def _control_args(self, record: dict, operation: str) -> list[str]:
+        # Management must never re-evaluate user configuration or fall back to a new connection.
+        return [self.ssh, "-F", "/dev/null", "-S", str(self._path(record["id"], "sock")),
+                "-O", operation, record["settings"]["alias"]]
+
+    def _control(self, record: dict, operation: str) -> subprocess.CompletedProcess:
+        return subprocess.run(self._control_args(record, operation), capture_output=True, text=True, timeout=5)
+
+    def _probe(self, record: dict) -> str:
+        path = self._path(record["id"], "sock")
+        try:
+            info = path.lstat()
+            if not stat.S_ISSOCK(info.st_mode) or info.st_uid != os.getuid():
+                return "Unknown"
+            result = self._control(record, "check")
+            if result.returncode == 0:
+                return "Alive"
+            # Distinguish stale/unlinked sockets from inspection failures.
+            with socket.socket(socket.AF_UNIX) as client:
+                client.settimeout(1)
+                try:
+                    client.connect(str(path))
+                except OSError as exc:
+                    if exc.errno in (errno.ENOENT, errno.ECONNREFUSED):
+                        return "Gone"
+            return "Unknown"
+        except FileNotFoundError:
+            return "Gone"
+        except (OSError, subprocess.TimeoutExpired):
+            return "Unknown"
+
+    def _status(self, record: dict) -> str:
+        probe = self._probe(record)
+        if probe == "Unknown":
+            return "Unknown"
+        if probe == "Alive":
+            return "Running" if record["status"] == "Running" else "Unknown"
+        return record["status"] if record["status"] in ("Stopped", "Failed") else "Disconnected"
+
+    def records(self) -> list[dict]:
+        return [dict(record, status=self._status(record)) for record in self._read()]
+
+    def commands(self, record: dict) -> list[list[str]]:
+        settings = Settings(**record["settings"])
+        master = [self.ssh]
+        if self.config_path:
+            master += ["-F", str(self.config_path)]
+        master += ["-n", "-N", "-T", "-M", "-S", str(self._path(record["id"], "sock")),
+                   "-E", str(self._path(record["id"], "log"))]
+        for option in ("ClearAllForwardings=yes", "ControlPersist=no", "ExitOnForwardFailure=yes",
+                       "PermitLocalCommand=no", "RemoteCommand=none", "ForwardAgent=no",
+                       "ForwardX11=no", "Tunnel=no", "ServerAliveInterval=15", "ServerAliveCountMax=3",
+                       "LogLevel=ERROR", "ConnectTimeout=15", "ConnectionAttempts=1",
+                       f"ForkAfterAuthentication={'yes' if settings.mode == 'background' else 'no'}"):
+            master += ["-o", option]
+        master += [settings.alias]
+        destination = f"[{settings.destination}]" if ":" in settings.destination else settings.destination
+        forward = self._control_args(record, "forward")
+        forward[-1:-1] = ["-o", "ClearAllForwardings=no", "-L",
+                          f"127.0.0.1:{settings.local_port}:{destination}:{settings.remote_port}"]
+        return [master, forward]
+
+    def prepare(self, settings: Settings) -> dict:
+        record = {"id": uuid.uuid4().hex[:12], "settings": asdict(settings), "created_at": now(),
+                  "status": "Connecting", "successful": False, "last_error": None}
+        record["commands"] = self.commands(record)
+        return record
+
+    def _find(self, records: list[dict], tunnel_id: str) -> dict:
+        self._path(tunnel_id, "sock")
+        for record in records:
+            if record["id"] == tunnel_id:
+                return record
+        raise TunnelError("Tunnel not found. Use tunnel list to see managed IDs.")
+
+    def logs(self, tunnel_id: str) -> str:
+        self._find(self._read(), tunnel_id)
+        path = self._path(tunnel_id, "log")
+        try:
+            fd = self._open(path, os.O_RDWR)
+        except FileNotFoundError:
+            return "No SSH diagnostics recorded. Application logs are not collected."
+        with os.fdopen(fd, "r+b") as file:
+            file.seek(0, os.SEEK_END)
+            size = file.tell()
+            file.seek(max(0, size - 65536))
+            output = file.read()
+            # shortcut: SSH owns the log; trim on access, add rotation if continuous log growth matters.
+            if size > 65536:
+                file.seek(0)
+                file.write(output)
+                file.truncate()
+        return output.decode(errors="replace") or "No SSH diagnostics recorded. Application logs are not collected."
+
+    def _exit(self, record: dict):
+        probe = self._probe(record)
+        if probe == "Unknown":
+            raise TunnelError("Cannot verify the owned control socket. No process was killed.")
+        if probe == "Gone":
+            return
+        try:
+            result = self._control(record, "exit")
+        except subprocess.TimeoutExpired as exc:
+            raise TunnelError("Timed out stopping the owned SSH connection; inspect its status.") from exc
+        for _ in range(30):
+            if self._probe(record) == "Gone":
+                return
+            time.sleep(0.1)
+        raise TunnelError(result.stderr.strip() or "SSH shutdown could not be verified.")
+
+    def stop(self, tunnel_id: str) -> dict:
+        with self._locked():
+            records = self._read()
+            record = self._find(records, tunnel_id)
+            self._exit(record)
+            record.update(status="Stopped", stopped_at=now(), last_error=None)
+            self._save(records)
+            return dict(record)
+
+    def _cleanup_attempt(self, record: dict, process: subprocess.Popen | None):
+        if process is not None and process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+        self._exit(record)
+
+    def start(self, record: dict, on_started: Callable[[dict], None] | None = None) -> dict:
+        settings = Settings(**record["settings"])
+        process = None
+        previous_hup = None
+        try:
+            previous_hup = signal.signal(signal.SIGHUP, _interrupt)
+            with self._locked():
+                records = self._read()
+                if settings.alias not in discover_hosts(self.config_path).aliases:
+                    raise TunnelError("The selected alias is no longer in the discovered SSH configuration.")
+                if any(item["id"] == record["id"] for item in records):
+                    raise TunnelError("This launch was already attempted. Review a fresh attempt before retrying.")
+                for existing in records:
+                    route = ("alias", "destination", "local_port", "remote_port")
+                    if all(existing["settings"][key] == record["settings"][key] for key in route) and self._probe(existing) == "Alive":
+                        raise TunnelError(f"This tunnel is already active: {existing['id']}. Open Manage tunnels.")
+                if not available_port(settings.local_port):
+                    raise TunnelError(f"Port {settings.local_port} is unavailable. Choose another local port.")
+                if self._path(record["id"], "sock").exists():
+                    raise TunnelError("Control path already exists. Review a fresh attempt.")
+                if record["commands"] != self.commands(record):
+                    raise TunnelError("Launch settings changed after review. Review again before starting.")
+                record = dict(record, status="Connecting", started_at=now())
+                records.append(record)
+                self._save(records)
+                try:
+                    fd = self._open(self._path(record["id"], "log"), os.O_WRONLY | os.O_CREAT | os.O_EXCL)
+                    os.close(fd)
+                    process = subprocess.Popen(record["commands"][0])
+                    while self._probe(record) != "Alive":
+                        if process.poll() is not None:
+                            # A background master may publish its socket just after its parent exits.
+                            if settings.mode == "background" and process.returncode == 0:
+                                for _ in range(30):
+                                    if self._probe(record) == "Alive":
+                                        break
+                                    time.sleep(0.1)
+                                else:
+                                    raise TunnelError("SSH exited without a responsive owned control socket.")
+                                break
+                            raise TunnelError(f"SSH startup failed (exit {process.returncode}). {self.logs(record['id'])}")
+                        time.sleep(0.05)
+                    if settings.mode == "background":
+                        process.wait(timeout=5)
+                        if process.returncode:
+                            raise TunnelError(f"SSH backgrounding failed (exit {process.returncode}).")
+                    result = subprocess.run(record["commands"][1], capture_output=True, text=True, timeout=10)
+                    if result.returncode:
+                        raise TunnelError(result.stderr.strip() or "SSH refused the requested forward.")
+                    if self._probe(record) != "Alive":
+                        raise TunnelError("SSH disconnected while opening the forward.")
+                    record.update(status="Running", successful=True, last_error=None)
+                    self._save(records)
+                except BaseException as exc:
+                    try:
+                        self._cleanup_attempt(record, process)
+                        record["status"] = "Failed"
+                    except (TunnelError, OSError) as cleanup_error:
+                        record["status"] = "Unknown"
+                        record["last_error"] = f"Cleanup needs attention: {cleanup_error}"
+                    record["last_error"] = record["last_error"] or ("Cancelled during startup." if isinstance(exc, KeyboardInterrupt) else str(exc))
+                    record["successful"] = False
+                    try:
+                        self._save(records)
+                    except OSError as save_error:
+                        raise TunnelError(f"Launch failed; could not save its outcome. Record {record['id']} was reserved before launch. {save_error}") from exc
+                    if isinstance(exc, (KeyboardInterrupt, SystemExit)):
+                        raise
+                    raise TunnelError(record["last_error"]) from exc
+            if settings.mode == "foreground":
+                interrupted = False
+                try:
+                    if on_started:
+                        on_started(dict(record))
+                    try:
+                        process.wait()
+                    except KeyboardInterrupt:
+                        interrupted = True
+                finally:
+                    stopped = interrupted or process.poll() is None
+                    # Release the owned connection even if updating the registry later fails.
+                    self._exit(record)
+                    process.wait(timeout=5)
+                    with self._locked():
+                        records = self._read()
+                        stored = self._find(records, record["id"])
+                        if stopped:
+                            stored.update(status="Stopped", stopped_at=now(), last_error=None)
+                        elif stored["status"] != "Stopped":
+                            stored.update(status="Disconnected", last_error=f"SSH exited ({process.returncode}).")
+                        self._save(records)
+                return dict(stored)
+            if on_started:
+                on_started(dict(record))
+            return dict(record)
+        finally:
+            if previous_hup is not None:
+                signal.signal(signal.SIGHUP, previous_hup)

tunnel_cli/prompts.py

@@ -0,0 +1,120 @@
+"""Small prompt layer over Questionary: Esc raises Back, search never submits
+an unmatched host, and say() prints untrusted text without control sequences."""
+
+import os
+import re
+
+import questionary
+from prompt_toolkit.filters import Condition
+from prompt_toolkit.key_binding import KeyBindings, merge_key_bindings
+from prompt_toolkit.output import ColorDepth
+from prompt_toolkit.styles import Style
+from prompt_toolkit.validation import ValidationError, Validator
+from questionary.prompts.common import InquirerControl
+
+_HINT = "Esc back · Ctrl+C cancel"
+
+
+class Back(Exception):
+    """The user pressed Esc to go back one step; collected answers stay valid."""
+
+
+_UNSAFE = re.compile(
+    r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?"  # OSC (title/hyperlink injection)
+    r"|\x1b\[[0-?]*[ -/]*[@-~]?"  # CSI sequences
+    r"|\x1b.?"  # any other escape, even truncated
+    r"|[\x00-\x08\x0b-\x1f\x7f\x80-\x9f]"  # C0 except \t\n, DEL, C1
+)
+
+
+def say(message: str = "") -> None:
+    """Print possibly untrusted text (SSH diagnostics, config warnings) with
+    terminal control characters removed; newlines and tabs survive."""
+    print(_UNSAFE.sub("", str(message)))
+
+
+def _style() -> Style:
+    return Style(
+        [("qmark", "fg:ansicyan"), ("pointer", "fg:ansicyan"),
+         ("highlighted", "fg:ansicyan"), ("answer", "fg:ansicyan")]
+    )
+
+
+def _color() -> dict:
+    """NO_COLOR present (even empty) forces monochrome rendering. A Style([])
+    would merge with Questionary's defaults and not suppress colors; the
+    application's color depth does."""
+    return {"color_depth": ColorDepth.DEPTH_1_BIT} if "NO_COLOR" in os.environ else {}
+
+
+class _Checked(Validator):
+    """Adapt a callable that raises ValueError (or returns False) for invalid text."""
+
+    def __init__(self, check):
+        self._check = check
+
+    def validate(self, document):
+        try:
+            ok = self._check(document.text)
+        except ValueError as error:
+            raise ValidationError(message=str(error), cursor_position=len(document.text)) from None
+        if ok is False:
+            raise ValidationError(message="Invalid input.", cursor_position=len(document.text))
+
+
+def _ask(question, *extra_bindings):
+    """Run a questionary question with a shared Esc-goes-back binding."""
+    application = question.application
+    back = KeyBindings()
+
+    @back.add("escape", eager=True)
+    def _back(event):
+        event.app.exit(exception=Back())
+
+    application.key_bindings = merge_key_bindings(
+        [bindings for bindings in (application.key_bindings, back, *extra_bindings) if bindings]
+    )
+    application.ttimeoutlen = 0.1  # resolve a lone Esc quickly
+    return question.unsafe_ask()
+
+
+def choose(message: str, choices: list, default=None, search: bool = False, **io):
+    """Arrow-key menu. With search=True, typing filters the choices and Enter is
+    ignored while the filter matches nothing, so an invisible choice can never
+    be submitted and typed text is never the answer. Raises Back on Esc."""
+    hint = ("type to filter · " if search else "") + f"↑↓ navigate · Enter select · {_HINT}"
+    question = questionary.select(
+        message, choices=choices, default=default, style=_style(),
+        instruction=f"({hint})",
+        use_search_filter=search, use_jk_keys=False, use_shortcuts=False,
+        **_color(), **io,
+    )
+    extra = []
+    if search:
+        control = next(
+            window.content
+            for window in question.application.layout.find_all_windows()
+            if isinstance(window.content, InquirerControl)
+        )
+
+        @Condition
+        def unmatched():
+            # shortcut: pinned Questionary 2.1.1 control internals, recheck on upgrade.
+            needle = (control.search_filter or "").lower()
+            return bool(needle) and not any(
+                needle in choice.title.lower() for choice in control.choices
+            )
+
+        block = KeyBindings()
+        block.add("enter", eager=True, filter=unmatched)(lambda event: None)
+        extra.append(block)
+    return _ask(question, *extra)
+
+
+def text(message: str, default: str = "", validate=None, **io) -> str:
+    """One-line answer with optional validation; Esc raises Back."""
+    question = questionary.text(
+        message, default=default, style=_style(), instruction=f"({_HINT}) ",
+        validate=_Checked(validate) if validate else None, **_color(), **io,
+    )
+    return _ask(question)