frp-jump 0.1.1__tar.gz

frp_jump-0.1.1/LICENSE

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

frp_jump-0.1.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: frp-jump
+Version: 0.1.1
+Summary: P2P-with-relay-fallback ssh/http/tcp tunnels between Linux boxes, built on frp
+Author: Alexander Degtyarev
+Author-email: Alexander Degtyarev <a.degtyarev@struhe.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.9
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-multipart>=0.0.17
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: cryptography>=43.0
+Requires-Dist: tomli-w>=1.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# frp-jump
+
+Connect Linux boxes (including Wiren Board controllers) to each other over
+the internet using the SSH/HTTP/TCP clients you already have — no manual
+port juggling, and no caring whether the link ended up peer-to-peer or
+relayed through your server.
+
+- **Tunneling** is [frp](https://github.com/fatedier/frp) (frpc/frps),
+  driven through an abstract `TunnelDriver`/`RelayDriver` interface — see
+  [`docs/architecture.md`](docs/architecture.md).
+- **P2P with relay fallback** is frp's own `xtcp` + `fallbackTo` feature: a
+  device pair first tries a direct (hole-punched) connection, and
+  transparently falls back to relaying through your server if that doesn't
+  complete within a timeout. Not something this project implements itself.
+- **Security**: a private CA (run by your server) issues an mTLS cert to
+  every enrolled device, so nothing unenrolled can reach the relay at all;
+  a per-pair secret means even enrolled devices can't reach each other's
+  services without an explicit grant; the WebUI is behind passwordless
+  magic-link auth (no passwords, no SMTP — links are generated by the
+  server and you hand-deliver them yourself); only an admin can add
+  devices, wire up services/grants, or revoke them — an invited non-admin
+  user can view the dashboard but not change it. Revoking a device or
+  grant takes effect on its next sync, not instantly — see
+  [`docs/architecture.md`](docs/architecture.md) for what that does and
+  doesn't cover.
+- **UX goal**: after setup, `ssh <name>` and `http://127.0.0.1:<port>` just
+  work with stock clients, whether the path underneath is p2p or relayed.
+
+## Installing the CLI
+
+Not published to PyPI — install on **every** machine that will run either
+`frp-jump server ...` or `frp-jump client ...` (the server box, and each
+device you connect), Python 3.12+ required (already present on any recent
+Debian/Ubuntu, including Wiren Board controllers). Two ways:
+
+**From a tagged release** (built by `.github/workflows/release.yml`,
+shows up under this repo's *Releases* tab):
+
+```sh
+python3 -m venv .venv    # needs the venv module: on Debian/Ubuntu that's
+                          # a separate package, `apt install python3-venv`
+gh release download v0.1.0 --repo aadegtyarev/frp-jump --pattern '*.whl' -O frp_jump.whl
+.venv/bin/pip install frp_jump.whl
+```
+
+Needs the [`gh` CLI](https://cli.github.com/) authenticated
+(`gh auth login`) since the repo is private — fine on your own machine,
+probably not worth installing just for a headless device (see below).
+
+**Directly from a git tag** (no release/wheel involved, works anywhere
+you can already `git clone` the repo — e.g. via the same **read-only
+deploy key** pattern used for node1 in `docs/architecture.md`; `gh repo
+deploy-key add` to mint one per device):
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install "git+ssh://git@github.com/aadegtyarev/frp-jump.git@v0.1.0"
+```
+
+Either way you end up with `frp-jump` in that venv — put `.venv/bin` on
+`PATH`, or call `.venv/bin/frp-jump` directly. The rest of this README
+just says `frp-jump`.
+
+To cut a new release: `git tag vX.Y.Z && git push origin vX.Y.Z` (bump
+`version` in `pyproject.toml` first) — the workflow builds and publishes
+it automatically.
+
+## Quick start
+
+On the **server** (a box with a public IP/domain):
+
+```sh
+export FRP_JUMP_RELAY_PUBLIC_ADDR=tunnel.example.com   # or a bare IP
+frp-jump server init --admin-email you@example.com
+# -> prints an admin login link: open it in a browser to sign in
+frp-jump server run
+```
+
+Lost that link, or need to sign in from somewhere else? It's not your
+only way in — mint a fresh one any time:
+
+```sh
+frp-jump server login-link you@example.com             # new login link
+frp-jump server login-link friend@example.com --invite # invite someone else
+```
+
+(Under the systemd deployment below, `server login-link` needs the same
+`FRP_JUMP_*` env vars as `server run`, which it won't pick up on its own
+outside of systemd's `EnvironmentFile` — see
+[`packaging/scripts/frp-jump-login-link`](packaging/scripts/frp-jump-login-link)
+for a copy-pasteable wrapper.)
+
+In the WebUI: **Add device** for each box you want to connect — this is
+also where the enroll token comes from, there's no other source for it.
+It prints a one-time `frp-jump client enroll <url> <token>` command; run
+that *on the device itself* (not on the server). Then define a
+**service** on the exposing device (e.g. `wb01-ssh`, protocol `ssh`, local
+port `22`) and a **grant** wiring a consuming device to it.
+
+On **each device** (after [installing the CLI](#installing-the-cli) there
+too):
+
+```sh
+frp-jump client enroll https://tunnel.example.com <token-from-webui>
+frp-jump client run          # foreground; wrap with systemd for real use
+```
+
+Once the consuming device has synced (its agent polls every
+`agent_poll_interval_seconds`, default 30s):
+
+```sh
+ssh wb01-ssh                 # just works — see `frp-jump client status` for
+                              # the local address of a non-ssh grant
+```
+
+## Configuration
+
+Everything configurable lives in one place:
+[`src/frp_jump/common/settings.py`](src/frp_jump/common/settings.py) — set
+via `FRP_JUMP_<FIELD>` environment variables, or a TOML file
+(`$FRP_JUMP_CONFIG_FILE`, else the first of `./frp-jump.toml`,
+`~/.config/frp-jump/config.toml`, `/etc/frp-jump/config.toml` that
+exists). Env vars win over the file. Nothing else in the codebase
+hardcodes a port, TTL, or version pin.
+
+The only setting with no sane default is `relay_public_addr` — the
+address other devices dial to reach your relay; `server init`/`server run`
+refuse to start without it.
+
+## systemd
+
+See [`packaging/systemd/`](packaging/systemd/). The client unit's comments
+explain a real gotcha: a device that *consumes* an SSH grant needs the
+agent running as the actual human (so it can maintain their real
+`~/.ssh/config`) — a `--user` unit, not a system one, unless you point
+`FRP_JUMP_SSH_CONFIG_PATH` at that user's config explicitly. A
+device that only *exposes* services (e.g. a Wiren Board controller) is
+fine as a system service.
+
+On the server, also install
+[`packaging/scripts/frp-jump-login-link`](packaging/scripts/frp-jump-login-link)
+to `/usr/local/bin/` (`chmod 755`, `root:root`) — a one-line wrapper
+around `server login-link` that loads the systemd unit's env file for
+you, so minting a fresh login/invite link doesn't mean hand-assembling
+`env $(sudo cat /etc/frp-jump/server.env | xargs) sudo -u frp-jump ...`
+every time.
+
+## Development
+
+```sh
+uv sync
+uv run pytest tests/unit -q        # fast, no network
+uv run ruff check .
+uv run pytest tests/integration -m integration -q   # downloads real frp binaries; loopback only
+```
+
+The integration test proves the whole chain works over loopback (real frp
+binaries, real mTLS, real xtcp-timeout-then-stcp-fallback), but it can't
+prove real NAT hole-punching across two separate networks — that's the one
+thing to manually check on your own machines after this lands.
+
+## Layout
+
+```
+src/frp_jump/
+  common/     PKI (private CA), opaque tokens, settings, DB models
+  driver/     TunnelDriver/RelayDriver abstraction; driver/frp/ = the frp
+              implementation (config rendering, binary download+checksum,
+              process supervision)
+  server/     control-plane: registry (CRUD), auth (magic links), the
+              agent-facing API, the WebUI, bootstrap (`server init`)
+  agent/      runs on every device: enroll, the sync loop, ssh_config
+              management
+  cli/        `frp-jump server ...` / `frp-jump client ...`
+```
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Changes are tracked in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

frp_jump-0.1.1/README.md

@@ -0,0 +1,184 @@
+# frp-jump
+
+Connect Linux boxes (including Wiren Board controllers) to each other over
+the internet using the SSH/HTTP/TCP clients you already have — no manual
+port juggling, and no caring whether the link ended up peer-to-peer or
+relayed through your server.
+
+- **Tunneling** is [frp](https://github.com/fatedier/frp) (frpc/frps),
+  driven through an abstract `TunnelDriver`/`RelayDriver` interface — see
+  [`docs/architecture.md`](docs/architecture.md).
+- **P2P with relay fallback** is frp's own `xtcp` + `fallbackTo` feature: a
+  device pair first tries a direct (hole-punched) connection, and
+  transparently falls back to relaying through your server if that doesn't
+  complete within a timeout. Not something this project implements itself.
+- **Security**: a private CA (run by your server) issues an mTLS cert to
+  every enrolled device, so nothing unenrolled can reach the relay at all;
+  a per-pair secret means even enrolled devices can't reach each other's
+  services without an explicit grant; the WebUI is behind passwordless
+  magic-link auth (no passwords, no SMTP — links are generated by the
+  server and you hand-deliver them yourself); only an admin can add
+  devices, wire up services/grants, or revoke them — an invited non-admin
+  user can view the dashboard but not change it. Revoking a device or
+  grant takes effect on its next sync, not instantly — see
+  [`docs/architecture.md`](docs/architecture.md) for what that does and
+  doesn't cover.
+- **UX goal**: after setup, `ssh <name>` and `http://127.0.0.1:<port>` just
+  work with stock clients, whether the path underneath is p2p or relayed.
+
+## Installing the CLI
+
+Not published to PyPI — install on **every** machine that will run either
+`frp-jump server ...` or `frp-jump client ...` (the server box, and each
+device you connect), Python 3.12+ required (already present on any recent
+Debian/Ubuntu, including Wiren Board controllers). Two ways:
+
+**From a tagged release** (built by `.github/workflows/release.yml`,
+shows up under this repo's *Releases* tab):
+
+```sh
+python3 -m venv .venv    # needs the venv module: on Debian/Ubuntu that's
+                          # a separate package, `apt install python3-venv`
+gh release download v0.1.0 --repo aadegtyarev/frp-jump --pattern '*.whl' -O frp_jump.whl
+.venv/bin/pip install frp_jump.whl
+```
+
+Needs the [`gh` CLI](https://cli.github.com/) authenticated
+(`gh auth login`) since the repo is private — fine on your own machine,
+probably not worth installing just for a headless device (see below).
+
+**Directly from a git tag** (no release/wheel involved, works anywhere
+you can already `git clone` the repo — e.g. via the same **read-only
+deploy key** pattern used for node1 in `docs/architecture.md`; `gh repo
+deploy-key add` to mint one per device):
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install "git+ssh://git@github.com/aadegtyarev/frp-jump.git@v0.1.0"
+```
+
+Either way you end up with `frp-jump` in that venv — put `.venv/bin` on
+`PATH`, or call `.venv/bin/frp-jump` directly. The rest of this README
+just says `frp-jump`.
+
+To cut a new release: `git tag vX.Y.Z && git push origin vX.Y.Z` (bump
+`version` in `pyproject.toml` first) — the workflow builds and publishes
+it automatically.
+
+## Quick start
+
+On the **server** (a box with a public IP/domain):
+
+```sh
+export FRP_JUMP_RELAY_PUBLIC_ADDR=tunnel.example.com   # or a bare IP
+frp-jump server init --admin-email you@example.com
+# -> prints an admin login link: open it in a browser to sign in
+frp-jump server run
+```
+
+Lost that link, or need to sign in from somewhere else? It's not your
+only way in — mint a fresh one any time:
+
+```sh
+frp-jump server login-link you@example.com             # new login link
+frp-jump server login-link friend@example.com --invite # invite someone else
+```
+
+(Under the systemd deployment below, `server login-link` needs the same
+`FRP_JUMP_*` env vars as `server run`, which it won't pick up on its own
+outside of systemd's `EnvironmentFile` — see
+[`packaging/scripts/frp-jump-login-link`](packaging/scripts/frp-jump-login-link)
+for a copy-pasteable wrapper.)
+
+In the WebUI: **Add device** for each box you want to connect — this is
+also where the enroll token comes from, there's no other source for it.
+It prints a one-time `frp-jump client enroll <url> <token>` command; run
+that *on the device itself* (not on the server). Then define a
+**service** on the exposing device (e.g. `wb01-ssh`, protocol `ssh`, local
+port `22`) and a **grant** wiring a consuming device to it.
+
+On **each device** (after [installing the CLI](#installing-the-cli) there
+too):
+
+```sh
+frp-jump client enroll https://tunnel.example.com <token-from-webui>
+frp-jump client run          # foreground; wrap with systemd for real use
+```
+
+Once the consuming device has synced (its agent polls every
+`agent_poll_interval_seconds`, default 30s):
+
+```sh
+ssh wb01-ssh                 # just works — see `frp-jump client status` for
+                              # the local address of a non-ssh grant
+```
+
+## Configuration
+
+Everything configurable lives in one place:
+[`src/frp_jump/common/settings.py`](src/frp_jump/common/settings.py) — set
+via `FRP_JUMP_<FIELD>` environment variables, or a TOML file
+(`$FRP_JUMP_CONFIG_FILE`, else the first of `./frp-jump.toml`,
+`~/.config/frp-jump/config.toml`, `/etc/frp-jump/config.toml` that
+exists). Env vars win over the file. Nothing else in the codebase
+hardcodes a port, TTL, or version pin.
+
+The only setting with no sane default is `relay_public_addr` — the
+address other devices dial to reach your relay; `server init`/`server run`
+refuse to start without it.
+
+## systemd
+
+See [`packaging/systemd/`](packaging/systemd/). The client unit's comments
+explain a real gotcha: a device that *consumes* an SSH grant needs the
+agent running as the actual human (so it can maintain their real
+`~/.ssh/config`) — a `--user` unit, not a system one, unless you point
+`FRP_JUMP_SSH_CONFIG_PATH` at that user's config explicitly. A
+device that only *exposes* services (e.g. a Wiren Board controller) is
+fine as a system service.
+
+On the server, also install
+[`packaging/scripts/frp-jump-login-link`](packaging/scripts/frp-jump-login-link)
+to `/usr/local/bin/` (`chmod 755`, `root:root`) — a one-line wrapper
+around `server login-link` that loads the systemd unit's env file for
+you, so minting a fresh login/invite link doesn't mean hand-assembling
+`env $(sudo cat /etc/frp-jump/server.env | xargs) sudo -u frp-jump ...`
+every time.
+
+## Development
+
+```sh
+uv sync
+uv run pytest tests/unit -q        # fast, no network
+uv run ruff check .
+uv run pytest tests/integration -m integration -q   # downloads real frp binaries; loopback only
+```
+
+The integration test proves the whole chain works over loopback (real frp
+binaries, real mTLS, real xtcp-timeout-then-stcp-fallback), but it can't
+prove real NAT hole-punching across two separate networks — that's the one
+thing to manually check on your own machines after this lands.
+
+## Layout
+
+```
+src/frp_jump/
+  common/     PKI (private CA), opaque tokens, settings, DB models
+  driver/     TunnelDriver/RelayDriver abstraction; driver/frp/ = the frp
+              implementation (config rendering, binary download+checksum,
+              process supervision)
+  server/     control-plane: registry (CRUD), auth (magic links), the
+              agent-facing API, the WebUI, bootstrap (`server init`)
+  agent/      runs on every device: enroll, the sync loop, ssh_config
+              management
+  cli/        `frp-jump server ...` / `frp-jump client ...`
+```
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Changes are tracked in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

frp_jump-0.1.1/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "frp-jump"
+version = "0.1.1"
+description = "P2P-with-relay-fallback ssh/http/tcp tunnels between Linux boxes, built on frp"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.15",
+    "rich>=13.9",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.32",
+    "jinja2>=3.1",
+    "python-multipart>=0.0.17",
+    "sqlmodel>=0.0.22",
+    "cryptography>=43.0",
+    "tomli-w>=1.1",
+    "httpx>=0.27",
+    "pydantic-settings>=2.15.0",
+]
+
+[[project.authors]]
+name = "Alexander Degtyarev"
+email = "a.degtyarev@struhe.com"
+
+[project.scripts]
+frp-jump = "frp_jump.cli.main:app"
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.7",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["integration: downloads/spins up real frp binaries and hits the network; excluded by default"]
+addopts = [
+    "-m",
+    "not integration",
+]
+asyncio_mode = "auto"

frp_jump-0.1.1/pyproject.toml.orig

@@ -0,0 +1,53 @@
+[project]
+name = "frp-jump"
+version = "0.1.1"
+description = "P2P-with-relay-fallback ssh/http/tcp tunnels between Linux boxes, built on frp"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Alexander Degtyarev", email = "a.degtyarev@struhe.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.15",
+    "rich>=13.9",
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.32",
+    "jinja2>=3.1",
+    "python-multipart>=0.0.17",
+    "sqlmodel>=0.0.22",
+    "cryptography>=43.0",
+    "tomli-w>=1.1",
+    "httpx>=0.27",
+    "pydantic-settings>=2.15.0",
+]
+
+[project.scripts]
+frp-jump = "frp_jump.cli.main:app"
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.7",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: downloads/spins up real frp binaries and hits the network; excluded by default",
+]
+addopts = ["-m", "not integration"]
+asyncio_mode = "auto"

frp_jump-0.1.1/src/frp_jump/agent/enroll.py

@@ -0,0 +1,40 @@
+"""One-time enrollment: trade an admin-issued enroll token for this
+device's identity (cert, api token, relay connection info), and persist it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+
+from frp_jump.agent.state import AgentState, save
+
+
+class EnrollError(RuntimeError):
+    pass
+
+
+def enroll(*, control_url: str, token: str, data_dir: Path) -> AgentState:
+    control_url = control_url.rstrip("/")
+    try:
+        resp = httpx.post(f"{control_url}/api/agent/enroll", json={"token": token}, timeout=30.0)
+    except httpx.HTTPError as exc:
+        raise EnrollError(f"could not reach {control_url}: {exc}") from exc
+    if resp.status_code != 200:
+        raise EnrollError(f"enroll failed ({resp.status_code}): {resp.text}")
+
+    body = resp.json()
+    state = AgentState(
+        device_id=body["device_id"],
+        device_name=body["device_name"],
+        control_url=control_url,
+        relay_addr=body["server_addr"],
+        relay_port=body["server_port"],
+        api_token=body["api_token"],
+        cert_pem=body["cert_pem"],
+        key_pem=body["key_pem"],
+        ca_cert_pem=body["ca_cert_pem"],
+    )
+    save(data_dir, state)
+    return state

frp_jump-0.1.1/src/frp_jump/agent/hosts.py

@@ -0,0 +1,47 @@
+"""Make consumed SSH grants reachable via `ssh <service-name>`.
+
+We never edit ``~/.ssh/config`` beyond ensuring a single ``Include`` line
+at its top; every ``Host`` block frp-jump manages lives in its own file,
+fully regenerated on every apply so it always matches the current grants.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_MANAGED_HEADER = "# managed by frp-jump -- do not edit, changes are overwritten on the next sync\n"
+
+
+def managed_config_path(data_dir: Path) -> Path:
+    return data_dir / "ssh_config"
+
+
+def render_ssh_config(entries: list[tuple[str, int]]) -> str:
+    """``entries``: (service_name, local_port) for each consumed SSH grant."""
+    lines = [_MANAGED_HEADER]
+    for name, port in entries:
+        lines.append(f"\nHost {name}\n    HostName 127.0.0.1\n    Port {port}\n")
+    return "".join(lines)
+
+
+def write_ssh_config(data_dir: Path, entries: list[tuple[str, int]]) -> Path:
+    path = managed_config_path(data_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_ssh_config(entries))
+    return path
+
+
+def ensure_include(ssh_config_path: Path, managed_path: Path) -> bool:
+    """Idempotently prepend ``Include <managed_path>`` to ``ssh_config_path``.
+
+    Prepended (not appended) so frp-jump's ``Host`` entries are matched
+    before any conflicting ones the user already has -- ssh_config uses
+    first-match-wins per keyword. Returns True if it had to add the line.
+    """
+    include_line = f"Include {managed_path}\n"
+    ssh_config_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = ssh_config_path.read_text() if ssh_config_path.exists() else ""
+    if str(managed_path) in existing:
+        return False
+    ssh_config_path.write_text(include_line + existing)
+    return True