ssh-tunnel-switch 0.1.0__tar.gz

ssh_tunnel_switch-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+dist/
+/config.yaml
+.env
+.DS_Store

ssh_tunnel_switch-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Initial standalone SSH tunnel rotation server, copied from the existing MIT-licensed project.
+- SOCKS5 tunnels, HTTP forwarding, HTTPS CONNECT, bearer-authenticated REST API and CLI.

ssh_tunnel_switch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Use a feature branch and a pull request. Include validation results and keep credentials out of code, logs, and issues.
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[test]' build twine
+.venv/bin/python -m pytest -q
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+.venv/bin/tunnel-switch validate --config examples/config.yaml
+```
+
+Tests use local sockets and subprocess fixtures, without remote SSH accounts or JavaScript dependencies. Python 3.12+ and OpenSSH are required to run the server.
+
+## Releases
+
+Update the version in `pyproject.toml` and the changelog. Publish a GitHub release tagged `service-v<version>` from an approved commit. CI validates the package before the publish job uploads the exact artifacts to PyPI. Versions cannot be overwritten.
+
+Before the first release, create a pending Trusted Publisher in your PyPI account with project name `ssh-tunnel-switch`, owner `timlaing`, repository `ssh-tunnel-switch`, workflow `publish-pypi.yml`, and environment `pypi`. Configure the GitHub `pypi` environment and any desired reviewer protection. No PyPI API token is needed. See https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/ . A pending publisher does not guarantee name availability; PyPI confirms acceptance on publication.
+
+After publishing, verify the registry version and install `ssh-tunnel-switch==<version>` in a clean environment. Check `tunnel-switch --help` and example configuration validation before announcing the release.

ssh_tunnel_switch-0.1.0/LICENSE

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

ssh_tunnel_switch-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: ssh-tunnel-switch
+Version: 0.1.0
+Summary: SSH SOCKS5 tunnel rotation service with an HTTP proxy and REST API
+Project-URL: Homepage, https://github.com/timlaing/ssh-tunnel-switch
+Project-URL: Repository, https://github.com/timlaing/ssh-tunnel-switch
+Project-URL: Issues, https://github.com/timlaing/ssh-tunnel-switch/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: h11<1,>=0.16
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: ruamel-yaml<0.20,>=0.18
+Requires-Dist: typer<1,>=0.15
+Requires-Dist: uvicorn<1,>=0.34
+Provides-Extra: test
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# SSH Tunnel Switch
+
+Rotate between SSH SOCKS5 tunnels using a REST API or CLI. A built-in HTTP proxy forwards HTTP requests and HTTPS CONNECT traffic through the active tunnel, with remote DNS resolution through SOCKS5.
+
+The server runs independently. It requires Python 3.12+ and OpenSSH; no OpenCode, Node.js, Bun, or plugin is needed.
+
+## Install and run
+
+Install from a checkout until the first PyPI release is available:
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install .
+cp examples/config.yaml config.yaml
+```
+
+After publication, install with `python -m pip install ssh-tunnel-switch`. The executable remains `tunnel-switch`, and Python imports use `tunnel_switch`.
+
+Edit `config.yaml` with your SSH host aliases and the SOCKS, HTTP proxy and API bind IP/port. Only `host` is required for each SSH server. `name` defaults to `host`; `user`, `port` and `identity_file` are optional overrides. When omitted (or null), the SSH command leaves them unset, so the system SSH client inherits settings from `~/.ssh/config` for the account running the service. Without configured SSH values, OpenSSH uses its own defaults. Identity paths relative to the YAML file resolve from its directory; `~` expands. YAML is mandatory for every CLI command. Unknown fields, invalid IPs/ports, duplicate server names and missing identity files are rejected.
+
+A host-only server list can use existing SSH config aliases:
+
+```yaml
+servers:
+  - host: ssh-one
+  - host: ssh-two
+```
+
+Normal `HostName`, `User`, `Port`, `IdentityFile`, `ProxyJump` and other SSH config settings apply. An explicit YAML `user`, `port` or `identity_file` is passed as `-l`, `-p` or `-i`. Existing configurations with named servers and explicit values still work. Effective server names must remain unique, including names derived from host aliases.
+
+Authenticate to each SSH server once using your normal SSH client and verify its host key. The service requires key/agent authentication (`BatchMode=yes`) and known hosts (`StrictHostKeyChecking=yes`). It does not prompt for passwords or accept unknown host keys. The SSH accounts must permit TCP forwarding.
+
+The API token lives in `api.token` in the YAML file. On startup, `serve` generates and saves a random token if the field is missing, null or blank. Existing tokens are reused. In both cases it prints `API token: ...` to the console before starting the API. Generated-token writes are atomic, preserve YAML comments, and save the file with mode 0600. If saving fails, startup fails rather than using an unsaved token.
+
+```sh
+.venv/bin/tunnel-switch validate --config config.yaml
+.venv/bin/tunnel-switch serve --config config.yaml
+```
+
+No token environment variable is used. `status` and `rotate` read the saved YAML token; they do not generate one. `serve` starts the first tunnel unless `start_on_launch: false`. Ctrl-C cleans up its SSH process. Each command supports `--help`; command/configuration/network failures print an error and CLI help with a nonzero exit code.
+
+Run exactly one service process for a given SOCKS socket. The supplied CLI uses one Uvicorn worker, without reload. It manages only SSH processes it spawned. An existing process occupying the SOCKS address is rejected rather than terminated. The cooldown also applies after startup and failed rotations, so an immediate rotation within the default 30 seconds returns 429.
+
+## Use the proxy with any client
+
+Start the service, then configure an HTTP proxy-aware client:
+
+```sh
+curl --proxy http://127.0.0.1:8118 https://example.com/
+```
+
+Alternatively, set `HTTP_PROXY` and `HTTPS_PROXY` to `http://127.0.0.1:8118` for clients that support those variables. Keep local control requests direct using `NO_PROXY=localhost,127.0.0.1,::1` or `curl --noproxy '*'`. SOCKS5-aware clients can use `socks5h://127.0.0.1:1080` directly.
+
+The HTTP proxy defaults to enabled on loopback port 8118. It streams HTTP/1.1 requests and supports HTTPS CONNECT without decrypting TLS. Forwarding fails when SOCKS is unavailable; it never falls back to a direct destination connection. Rotation closes existing tunneled connections. The API remains responsive during rotation. There is no automatic SSH restart loop.
+
+The HTTP and SOCKS listeners are unauthenticated. Keep them on loopback or restrict access with a firewall. The bearer token protects only the REST API. Use a TLS reverse proxy for remote API access. See [security](SECURITY.md).
+
+## REST API and CLI
+
+All endpoints require `Authorization: Bearer <token>`. FastAPI interactive API docs are available at `/docs`.
+
+| Endpoint | Result |
+| --- | --- |
+| `GET /status` | State, connection ID, start time, server, SOCKS and HTTP proxy addresses, and last error |
+| `POST /rotate` | Stops current tunnel, starts next server, returns status after readiness |
+
+Overlapping rotations and cooldown violations return **429**, with `Retry-After`; callers must trigger again later. They are not queued. Startup/SSH failures return **503** and leave the service disconnected; another trigger after the cooldown advances to the next server. A single-server list restarts the same server. Status remains responsive during rotation and returns `state: "rotating"`; connection ID/start time are null until the new tunnel is ready. After SSH exits, status reports disconnected and clears active connection fields. There is no automatic restart loop.
+
+```sh
+.venv/bin/tunnel-switch status --config config.yaml
+.venv/bin/tunnel-switch rotate --config config.yaml
+curl --noproxy '*' -H "Authorization: Bearer <token-from-YAML>" http://127.0.0.1:8765/status
+curl --noproxy '*' -X POST -H "Authorization: Bearer <token-from-YAML>" http://127.0.0.1:8765/rotate
+```
+
+Example connected status:
+
+```json
+{
+  "state": "connected",
+  "connection_id": "9d7e9746-c4e2-4a43-8da5-674ab452cb91",
+  "started_at": "2026-10-14T12:00:00+00:00",
+  "server": "first",
+  "proxy": {"ip": "127.0.0.1", "port": 1080},
+  "http_proxy": {"enabled": true, "ip": "127.0.0.1", "port": 8118},
+  "last_error": null
+}
+```
+
+## Development and deployment
+
+- [Contributing and releases](CONTRIBUTING.md)
+- [Linux systemd deployment](docs/deployment.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE).

ssh_tunnel_switch-0.1.0/README.md

@@ -0,0 +1,99 @@
+# SSH Tunnel Switch
+
+Rotate between SSH SOCKS5 tunnels using a REST API or CLI. A built-in HTTP proxy forwards HTTP requests and HTTPS CONNECT traffic through the active tunnel, with remote DNS resolution through SOCKS5.
+
+The server runs independently. It requires Python 3.12+ and OpenSSH; no OpenCode, Node.js, Bun, or plugin is needed.
+
+## Install and run
+
+Install from a checkout until the first PyPI release is available:
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install .
+cp examples/config.yaml config.yaml
+```
+
+After publication, install with `python -m pip install ssh-tunnel-switch`. The executable remains `tunnel-switch`, and Python imports use `tunnel_switch`.
+
+Edit `config.yaml` with your SSH host aliases and the SOCKS, HTTP proxy and API bind IP/port. Only `host` is required for each SSH server. `name` defaults to `host`; `user`, `port` and `identity_file` are optional overrides. When omitted (or null), the SSH command leaves them unset, so the system SSH client inherits settings from `~/.ssh/config` for the account running the service. Without configured SSH values, OpenSSH uses its own defaults. Identity paths relative to the YAML file resolve from its directory; `~` expands. YAML is mandatory for every CLI command. Unknown fields, invalid IPs/ports, duplicate server names and missing identity files are rejected.
+
+A host-only server list can use existing SSH config aliases:
+
+```yaml
+servers:
+  - host: ssh-one
+  - host: ssh-two
+```
+
+Normal `HostName`, `User`, `Port`, `IdentityFile`, `ProxyJump` and other SSH config settings apply. An explicit YAML `user`, `port` or `identity_file` is passed as `-l`, `-p` or `-i`. Existing configurations with named servers and explicit values still work. Effective server names must remain unique, including names derived from host aliases.
+
+Authenticate to each SSH server once using your normal SSH client and verify its host key. The service requires key/agent authentication (`BatchMode=yes`) and known hosts (`StrictHostKeyChecking=yes`). It does not prompt for passwords or accept unknown host keys. The SSH accounts must permit TCP forwarding.
+
+The API token lives in `api.token` in the YAML file. On startup, `serve` generates and saves a random token if the field is missing, null or blank. Existing tokens are reused. In both cases it prints `API token: ...` to the console before starting the API. Generated-token writes are atomic, preserve YAML comments, and save the file with mode 0600. If saving fails, startup fails rather than using an unsaved token.
+
+```sh
+.venv/bin/tunnel-switch validate --config config.yaml
+.venv/bin/tunnel-switch serve --config config.yaml
+```
+
+No token environment variable is used. `status` and `rotate` read the saved YAML token; they do not generate one. `serve` starts the first tunnel unless `start_on_launch: false`. Ctrl-C cleans up its SSH process. Each command supports `--help`; command/configuration/network failures print an error and CLI help with a nonzero exit code.
+
+Run exactly one service process for a given SOCKS socket. The supplied CLI uses one Uvicorn worker, without reload. It manages only SSH processes it spawned. An existing process occupying the SOCKS address is rejected rather than terminated. The cooldown also applies after startup and failed rotations, so an immediate rotation within the default 30 seconds returns 429.
+
+## Use the proxy with any client
+
+Start the service, then configure an HTTP proxy-aware client:
+
+```sh
+curl --proxy http://127.0.0.1:8118 https://example.com/
+```
+
+Alternatively, set `HTTP_PROXY` and `HTTPS_PROXY` to `http://127.0.0.1:8118` for clients that support those variables. Keep local control requests direct using `NO_PROXY=localhost,127.0.0.1,::1` or `curl --noproxy '*'`. SOCKS5-aware clients can use `socks5h://127.0.0.1:1080` directly.
+
+The HTTP proxy defaults to enabled on loopback port 8118. It streams HTTP/1.1 requests and supports HTTPS CONNECT without decrypting TLS. Forwarding fails when SOCKS is unavailable; it never falls back to a direct destination connection. Rotation closes existing tunneled connections. The API remains responsive during rotation. There is no automatic SSH restart loop.
+
+The HTTP and SOCKS listeners are unauthenticated. Keep them on loopback or restrict access with a firewall. The bearer token protects only the REST API. Use a TLS reverse proxy for remote API access. See [security](SECURITY.md).
+
+## REST API and CLI
+
+All endpoints require `Authorization: Bearer <token>`. FastAPI interactive API docs are available at `/docs`.
+
+| Endpoint | Result |
+| --- | --- |
+| `GET /status` | State, connection ID, start time, server, SOCKS and HTTP proxy addresses, and last error |
+| `POST /rotate` | Stops current tunnel, starts next server, returns status after readiness |
+
+Overlapping rotations and cooldown violations return **429**, with `Retry-After`; callers must trigger again later. They are not queued. Startup/SSH failures return **503** and leave the service disconnected; another trigger after the cooldown advances to the next server. A single-server list restarts the same server. Status remains responsive during rotation and returns `state: "rotating"`; connection ID/start time are null until the new tunnel is ready. After SSH exits, status reports disconnected and clears active connection fields. There is no automatic restart loop.
+
+```sh
+.venv/bin/tunnel-switch status --config config.yaml
+.venv/bin/tunnel-switch rotate --config config.yaml
+curl --noproxy '*' -H "Authorization: Bearer <token-from-YAML>" http://127.0.0.1:8765/status
+curl --noproxy '*' -X POST -H "Authorization: Bearer <token-from-YAML>" http://127.0.0.1:8765/rotate
+```
+
+Example connected status:
+
+```json
+{
+  "state": "connected",
+  "connection_id": "9d7e9746-c4e2-4a43-8da5-674ab452cb91",
+  "started_at": "2026-10-14T12:00:00+00:00",
+  "server": "first",
+  "proxy": {"ip": "127.0.0.1", "port": 1080},
+  "http_proxy": {"enabled": true, "ip": "127.0.0.1", "port": 8118},
+  "last_error": null
+}
+```
+
+## Development and deployment
+
+- [Contributing and releases](CONTRIBUTING.md)
+- [Linux systemd deployment](docs/deployment.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE).

ssh_tunnel_switch-0.1.0/SECURITY.md

@@ -0,0 +1,30 @@
+# Security policy
+
+Report vulnerabilities privately using [GitHub private vulnerability reporting](https://github.com/timlaing/ssh-tunnel-switch/security/advisories/new). Do not post sensitive details in public issues. If reporting is unavailable, request a private reporting channel without disclosing the vulnerability. No response-time guarantee is offered. Fixes target the latest release and current development branch.
+
+## Deployment boundaries
+
+- The bearer token protects REST status and rotation endpoints. HTTP and SOCKS
+  proxy listeners have no authentication. Use loopback or firewall access limited
+  to intended clients; do not expose an unrestricted proxy to the Internet.
+- Use TLS in front of a remotely accessed REST API. HTTPS CONNECT transports
+  destination TLS unchanged; the service does not decrypt it.
+- The YAML and client configuration contain the REST token. Keep both private.
+  The CLI deliberately prints the token at every startup, including to systemd
+  journal logs. Restrict log access and redact diagnostics before sharing.
+- Protect the dedicated SSH key and verify host keys. The service uses batch
+  authentication and strict host-key checking. It runs as one account and reads
+  that account's SSH configuration. Configuration-write access can change hosts
+  and exposed listeners, so grant it only to trusted administrators.
+- Token rotation: stop the service, replace `api.token` with a fresh secret (or
+  set it to null to generate one on the next startup), start the service, update
+  every client using that token. Existing tokens are loaded
+  at startup; editing the file alone does not revoke the running token.
+- Run one API worker and one service instance per SOCKS socket. Coordination is
+  within one process, not across multiple instances.
+- Forwarding fails when SOCKS is unavailable. Tunnel rotation does not establish
+  that a provider quota was reset and does not replace provider account controls.
+
+Dependency audits and updates complement review; passing audits are not a claim
+that the code has no vulnerabilities. See the [deployment guide](docs/deployment.md)
+for service-account and filesystem settings.

ssh_tunnel_switch-0.1.0/deploy/systemd/tunnel-switch.service

@@ -0,0 +1,33 @@
+[Unit]
+Description=SSH tunnel rotation API and HTTP proxy
+Wants=network-online.target
+After=network-online.target
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=tunnel-switch
+Group=tunnel-switch
+WorkingDirectory=/var/lib/tunnel-switch
+ExecStart=/opt/tunnel-switch/.venv/bin/tunnel-switch serve --config /etc/tunnel-switch/config.yaml
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=30
+KillMode=mixed
+UMask=0077
+Environment=PYTHONUNBUFFERED=1
+Environment=PYTHONDONTWRITEBYTECODE=1
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/etc/tunnel-switch /var/lib/tunnel-switch
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+CapabilityBoundingSet=
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+
+[Install]
+WantedBy=multi-user.target

ssh_tunnel_switch-0.1.0/docs/deployment.md

@@ -0,0 +1,125 @@
+# Deploying the Python service
+
+The supplied [systemd unit](../deploy/systemd/tunnel-switch.service) targets
+Linux with systemd, Python 3.12 or newer, and OpenSSH. macOS users can run the
+foreground CLI described in the README; no launchd service is supplied.
+These instructions install files on a deployment host, not on your workstation.
+
+## Install
+
+Check out an approved repository revision at `/opt/tunnel-switch`. Code and its virtual environment should be root-owned and
+not writable by the service account. On Debian/Ubuntu, install `openssh-client`
+and the `python3-venv` package matching a supported Python version first.
+
+```sh
+sudo useradd --system --user-group --create-home \
+  --home-dir /var/lib/tunnel-switch --shell /usr/sbin/nologin tunnel-switch
+sudo install -d -m 0700 -o tunnel-switch -g tunnel-switch /etc/tunnel-switch
+sudo install -d -m 0700 -o tunnel-switch -g tunnel-switch /var/lib/tunnel-switch/.ssh
+sudo python3 -m venv /opt/tunnel-switch/.venv
+sudo /opt/tunnel-switch/.venv/bin/python -m pip install /opt/tunnel-switch
+sudo install -m 0600 -o tunnel-switch -g tunnel-switch \
+  /opt/tunnel-switch/examples/config.yaml /etc/tunnel-switch/config.yaml
+sudoedit /etc/tunnel-switch/config.yaml
+```
+
+Run `useradd` only when the account does not already exist. The configuration
+directory is writable by the service because saving a newly generated token
+uses an atomic file replacement. The unit permits writes only to that directory,
+the service's home, and its private temporary directory. Root owns the executable
+and unit. Configuration values can select SSH hosts, identities and bind sockets,
+so write access to the YAML is operational control of the service.
+
+## Configure SSH under the service account
+
+Host-only YAML entries use `/var/lib/tunnel-switch/.ssh/config`, not your own
+account's SSH configuration. Provision the necessary SSH config, known-host
+entries and a dedicated authentication key for this account. Set `.ssh` to mode
+0700 and config/private-key files to 0600 with owner `tunnel-switch`.
+
+Example SSH config, with deployment-specific values substituted:
+
+```sshconfig
+Host ssh-one
+    HostName ssh-one.example.org
+    User tunnel
+    IdentityFile /var/lib/tunnel-switch/.ssh/id_ed25519
+    IdentitiesOnly yes
+```
+
+Verify each server's host-key fingerprint through a trusted channel before
+adding it to this account's `known_hosts`. Test the effective configuration and
+key authentication as the actual account:
+
+```sh
+sudo -u tunnel-switch ssh -G ssh-one
+sudo -u tunnel-switch ssh -o BatchMode=yes -o StrictHostKeyChecking=yes ssh-one true
+sudo -u tunnel-switch /opt/tunnel-switch/.venv/bin/tunnel-switch \
+  validate --config /etc/tunnel-switch/config.yaml
+```
+
+Repeat for every host. A restricted SSH account may reject the `true` remote
+command even when authentication works; use its administrator-approved check
+instead. SSH diagnostic output can contain private hostnames and paths.
+
+The unit does not inherit your desktop SSH agent. Encrypted keys require a
+separately managed agent reachable by this service; its socket must also be
+accessible inside the unit sandbox. A dedicated noninteractive key should have
+narrow server-side permissions and carefully restricted local access. The SSH
+server must allow TCP forwarding. `ProxyJump` works when its authentication
+requirements are also satisfied under this account.
+
+## Start and verify
+
+Keep the default loopback listeners for a local deployment. Install the unit:
+
+```sh
+sudo install -m 0644 /opt/tunnel-switch/deploy/systemd/tunnel-switch.service \
+  /etc/systemd/system/tunnel-switch.service
+sudo systemd-analyze verify /etc/systemd/system/tunnel-switch.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now tunnel-switch.service
+sudo systemctl status tunnel-switch.service
+sudo -u tunnel-switch /opt/tunnel-switch/.venv/bin/tunnel-switch \
+  status --config /etc/tunnel-switch/config.yaml
+```
+
+The status command should report `connected`, a connection ID and a start time.
+`systemctl` reporting `active` only confirms the Python process is running; it
+does not confirm SSH connectivity. Configure clients after checking `/status`.
+
+Startup prints the API token as required by the CLI, so under systemd it appears
+in the journal. Read it only through a trusted local administrator session:
+
+```sh
+sudo journalctl -u tunnel-switch.service -n 50 --no-pager
+```
+
+Do not paste this output into issues or share it unredacted. See [SECURITY.md](../SECURITY.md).
+
+## Remote clients and updates
+
+For remote clients, bind the HTTP proxy to a reachable interface and
+restrict both HTTP and SOCKS access using the host firewall. Keep SOCKS on
+loopback when only the built-in bridge needs it. Protect a remotely accessed
+REST API with TLS at a reverse proxy and configure clients to use HTTPS.
+The built-in API serves HTTP; it does not terminate TLS. The CLI accesses the
+configured local HTTP socket directly. Wildcard API bindings are mapped to
+loopback by CLI status/rotate commands.
+
+The unit hides `/home`, `/root` and `/run/user`; place SSH files in its own home
+and adjust any `Include`, `IdentityFile` or `ProxyJump` dependencies accordingly.
+Its filesystem restrictions follow [systemd's execution settings](https://github.com/systemd/systemd/blob/main/man/systemd.exec.xml).
+
+Before upgrading, preserve a protected copy of the configuration and current
+revision outside the checkout. Stop the service, install the approved new
+revision into the existing virtual environment, validate YAML as the service
+account, then start it and verify status. Restore the previous revision and
+configuration if validation fails. Changing YAML requires a service restart;
+changing HTTP proxy settings also requires updating client configuration.
+
+The unit restarts a failed Python process. An SSH subprocess exiting while the
+API stays alive does not trigger a systemd restart; use `/status`, diagnose SSH,
+and request rotation after the cooldown. `KillMode=mixed` lets the Python process
+clean up its tunnel before systemd forcibly stops remaining child processes at
+the shutdown deadline. Keep `TimeoutStopSec` longer than configured stop timeouts.

ssh_tunnel_switch-0.1.0/examples/config.yaml

@@ -0,0 +1,29 @@
+servers:
+  # Host aliases from ~/.ssh/config; User, Port and IdentityFile are inherited.
+  - host: ssh-one
+  - host: ssh-two
+  # Optional per-server overrides:
+  # - host: ssh-three
+  #   name: third
+  #   user: tunnel
+  #   port: 2222
+  #   identity_file: ~/.ssh/id_ed25519
+proxy:
+  ip: 127.0.0.1
+  port: 1080
+http_proxy:
+  enabled: true
+  ip: 127.0.0.1
+  port: 8118
+  connect_timeout_seconds: 10
+  idle_timeout_seconds: 120
+  max_connections: 128
+api:
+  ip: 127.0.0.1
+  port: 8765
+  # Leave unset to generate and save a token on service startup.
+  token: null
+cooldown_seconds: 30
+startup_timeout_seconds: 15
+stop_timeout_seconds: 5
+start_on_launch: true

ssh_tunnel_switch-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ssh-tunnel-switch"
+version = "0.1.0"
+description = "SSH SOCKS5 tunnel rotation service with an HTTP proxy and REST API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["fastapi>=0.115,<1", "uvicorn>=0.34,<1", "typer>=0.15,<1", "pydantic>=2.10,<3", "PyYAML>=6,<7", "ruamel.yaml>=0.18,<0.20", "httpx>=0.28,<1", "h11>=0.16,<1"]
+
+[project.urls]
+Homepage = "https://github.com/timlaing/ssh-tunnel-switch"
+Repository = "https://github.com/timlaing/ssh-tunnel-switch"
+Issues = "https://github.com/timlaing/ssh-tunnel-switch/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8,<10", "pytest-asyncio>=0.25,<2"]
+
+[project.scripts]
+tunnel-switch = "tunnel_switch.cli:main"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tunnel_switch"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/examples", "/deploy", "/docs", "/README.md", "/LICENSE", "/SECURITY.md", "/CONTRIBUTING.md", "/CHANGELOG.md", "/pyproject.toml"]

ssh_tunnel_switch-0.1.0/src/tunnel_switch/__init__.py

@@ -0,0 +1 @@
+"""SSH SOCKS tunnel rotation service."""

ssh_tunnel_switch-0.1.0/src/tunnel_switch/api.py

@@ -0,0 +1,51 @@
+from contextlib import asynccontextmanager
+import secrets
+from fastapi import Depends, FastAPI, Header, HTTPException
+from .config import Config
+from .http_proxy import HTTPProxyServer
+from .tunnel import RotationRejected, TunnelFailure, TunnelManager
+
+
+def create_app(config: Config, token: str, manager: TunnelManager | None = None) -> FastAPI:
+    if not token:
+        raise ValueError("API token must not be empty")
+    manager = manager or TunnelManager(config)
+    proxy = HTTPProxyServer(config)
+
+    @asynccontextmanager
+    async def lifespan(app):
+        try:
+            if config.start_on_launch:
+                await manager.rotate()
+            await proxy.start()
+            yield
+        finally:
+            try:
+                await proxy.close()
+            finally:
+                await manager.close()
+
+    app = FastAPI(title="Tunnel Switch", lifespan=lifespan)
+    app.state.manager = manager
+    app.state.http_proxy = proxy
+
+    async def authorize(authorization: str | None = Header(default=None)):
+        if authorization is None or not secrets.compare_digest(authorization.encode(), f"Bearer {token}".encode()):
+            raise HTTPException(status_code=401, detail="Invalid bearer token")
+
+    @app.get("/status", dependencies=[Depends(authorize)])
+    async def status():
+        return {**manager.status(), "http_proxy": {
+            "enabled": config.http_proxy.enabled, "ip": str(config.http_proxy.ip),
+            "port": config.http_proxy.port}}
+
+    @app.post("/rotate", dependencies=[Depends(authorize)])
+    async def rotate():
+        try:
+            return await manager.rotate()
+        except RotationRejected as exc:
+            raise HTTPException(status_code=429, detail=str(exc), headers={"Retry-After": str(exc.retry_after)}) from exc
+        except TunnelFailure as exc:
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+    return app