offbox 0.1.0__py3-none-any.whl

offbox/setup.py

@@ -0,0 +1,181 @@
+from collections.abc import Callable
+from pathlib import Path
+from typing import Literal
+
+from offbox import console
+from offbox.config import Model
+from offbox.doctor import NO_DEFAULT_HOST, Check, diagnose
+from offbox.errors import OffboxError, PreconditionError
+from offbox.host.create import CreateOptions, create_host
+from offbox.host.init import InitOptions, init_host
+from offbox.paths import Paths
+from offbox.providers import credentials_env, discover_provider
+from offbox.runner import Runner
+from offbox.ssh import default_ssh_key, ensure_include, sync_config
+from offbox.state import StateStore
+from offbox.tools import ToolDiscovery, download_prompt, install_mutagen
+
+INSTALLATION_DOCS = "https://github.com/o-avdieiev/offbox/blob/master/docs/installation.md"
+KEYGEN_COMMAND = 'ssh-keygen -t ed25519 -N "" -C offbox -f ~/.ssh/offbox_ed25519'
+
+
+class SetupOptions(Model):
+    provider: Literal["hetzner", "gcp", "ssh"] | None = None
+    action: Literal["check", "create", "init"] | None = None
+    name: str = "main"
+    ssh_key: Path | None = None
+    size: str | None = None
+    region: str | None = None
+    target: str | None = None
+    port: int = 22
+    accept_host_key: bool = False
+    host_key_fingerprint: str | None = None
+
+
+def credential_fix(provider: str, paths: Paths) -> str | None:
+    if provider == "hetzner":
+        return (
+            f"export HCLOUD_TOKEN=... in your shell profile, or set token under [hetzner] in {paths.credentials} (chmod 600); "
+            f"see {INSTALLATION_DOCS}#hetzner"
+        )
+    if provider == "gcp":
+        return f"export GOOGLE_PROJECT=your-project-id and run gcloud auth application-default login; see {INSTALLATION_DOCS}#google-cloud"
+    return None
+
+
+def select_key(runner: Runner, requested: Path | None, offer: Callable[[str], bool] | None, *, create: bool) -> Path | None:
+    """Return the SSH key setup should use, or None to keep the ~/.ssh/id_ed25519 default."""
+    if requested is not None:
+        return requested
+    key = default_ssh_key()
+    if key.name == "offbox_ed25519":
+        console.info(f"Using SSH key {key}")
+        return key
+    if key.exists() or key.with_name(key.name + ".pub").exists():
+        return None
+    directory = key.parent
+    dedicated = directory / "offbox_ed25519"
+    if not create:
+        return None
+    if offer is None:
+        raise PreconditionError("No SSH key found", f"Run {KEYGEN_COMMAND}, then rerun offbox setup.")
+    if not offer("No SSH key found. Create a dedicated key ~/.ssh/offbox_ed25519 for offbox hosts?"):
+        raise PreconditionError("No SSH key found", f"Run {KEYGEN_COMMAND}, or pass --ssh-key PATH.")
+    try:
+        directory.mkdir(mode=0o700, exist_ok=True)
+    except OSError as exc:
+        raise PreconditionError(f"Cannot create {directory}", f"Create {directory} with mode 0700 and retry.") from exc
+    runner.run(["ssh-keygen", "-t", "ed25519", "-N", "", "-C", "offbox", "-f", str(dedicated)], timeout=30)
+    console.success(f"Created SSH key {dedicated}")
+    return dedicated
+
+
+def _offer_mutagen(paths: Paths, tools: ToolDiscovery, checks: list[Check], offer: Callable[[str], bool] | None) -> list[Check]:
+    if offer is None or not any(check.name == "mutagen" and check.message == "Missing tool: mutagen" for check in checks):
+        return checks
+    if not offer(download_prompt(paths.cache)):
+        return checks
+    install_mutagen(paths.cache)
+    try:
+        tool = tools.check("mutagen")
+        replacement = Check(name="mutagen", ok=True, message=f"{tool.name} {tool.version} ({tool.path})")
+    except OffboxError as exc:
+        replacement = Check(name="mutagen", ok=False, message=exc.message, fix=exc.fix)
+    return [replacement if check.name == "mutagen" else check for check in checks]
+
+
+def setup(
+    paths: Paths,
+    runner: Runner,
+    options: SetupOptions,
+    *,
+    ask: Callable[[str, str], str] | None = None,
+    confirm: Callable[[str], bool] | None = None,
+    offer: Callable[[str], bool] | None = None,
+    ssh_config: Path | None = None,
+    tools: ToolDiscovery | None = None,
+) -> None:
+    provider = options.provider
+    if provider is None:
+        if ask is None:
+            raise PreconditionError(
+                "Setup needs a provider", "Pass --provider hetzner, --provider gcp or --provider ssh with an explicit --action."
+            )
+        choice = ask("Provider (hetzner, gcp or ssh)", "hetzner")
+        if choice not in ("hetzner", "gcp", "ssh"):
+            raise PreconditionError("Unknown setup provider", "Pass --provider hetzner, --provider gcp or --provider ssh.")
+        provider = "hetzner" if choice == "hetzner" else "gcp" if choice == "gcp" else "ssh"
+    action = options.action
+    if action is None:
+        if confirm is None:
+            raise PreconditionError("Setup needs an explicit action", "Pass --action check, --action create or --action init.")
+        action = (
+            ("create" if provider != "ssh" else "init")
+            if confirm("Create a billable cloud host?" if provider != "ssh" else "Bootstrap an existing SSH host?")
+            else "check"
+        )
+    discovery = tools or ToolDiscovery(runner, paths.cache)
+    ssh_key = select_key(runner, options.ssh_key, offer, create=action != "check")
+    report = diagnose(paths, runner, ssh_key=ssh_key, tools=discovery)
+    report.checks = _offer_mutagen(paths, discovery, report.checks, offer)
+    fatal: list[Check] = []
+    for check in report.checks:
+        required = not (check.name == "host" and (action != "check" or check.message == NO_DEFAULT_HOST)) and not (
+            check.name == "tofu" and not (provider != "ssh" and action == "create")
+        )
+        if check.ok:
+            console.success(check.message)
+        elif required:
+            fatal.append(check)
+            console.error(check.message, check.fix)
+        else:
+            console.warn(f"{check.message}. Fix: {check.fix}")
+    if fatal:
+        raise PreconditionError("Setup prerequisites are not satisfied", fatal[0].fix or "Run offbox doctor and follow its Fix lines.")
+    manifest = discover_provider(provider, paths)
+    try:
+        credentials_env(manifest.manifest, paths)
+    except PreconditionError as exc:
+        fix = credential_fix(provider, paths)
+        if fix is None or not exc.message.startswith("Missing"):
+            raise
+        raise PreconditionError(exc.message, fix) from exc
+    if action == "create":
+        if provider == "ssh":
+            raise PreconditionError(
+                "The SSH provider cannot create a cloud host", "Use --provider ssh --action init --target USER@ADDRESS."
+            )
+        ensure_include(paths, ssh_config)
+        sync_config(paths, StateStore(paths.state).read())
+        create_host(
+            paths,
+            runner,
+            CreateOptions(name=options.name, provider=provider, ssh_key=ssh_key, size=options.size, region=options.region),
+            ssh_config=ssh_config,
+        )
+    elif action == "init":
+        if provider != "ssh":
+            raise PreconditionError("Existing host initialization requires the SSH provider", "Use --provider ssh --action init.")
+        target = options.target or (ask("Existing host USER@ADDRESS (--target)", "") if ask else None)
+        if not target:
+            raise PreconditionError(
+                "Setup needs an SSH target",
+                "Pass --provider ssh --action init --target USER@ADDRESS --host-key-fingerprint SHA256:...",
+            )
+        ensure_include(paths, ssh_config)
+        sync_config(paths, StateStore(paths.state).read())
+        init_host(
+            paths,
+            runner,
+            InitOptions(
+                target=target,
+                name=options.name,
+                port=options.port,
+                ssh_key=ssh_key,
+                accept_host_key=options.accept_host_key,
+                host_key_fingerprint=options.host_key_fingerprint,
+            ),
+            confirm=confirm,
+            ssh_config=ssh_config,
+        )
+    console.info("Next: cd <your repo> && offbox up")

offbox/share.py

@@ -0,0 +1,286 @@
+import base64
+import hashlib
+import logging
+from collections.abc import Mapping, Sequence
+from pathlib import Path, PurePosixPath
+
+from offbox import console
+from offbox.config import GitConfig, Model, ProjectConfig
+from offbox.errors import CommandFailed, ConnectionError_, PreconditionError
+from offbox.naming import Worktree
+from offbox.runner import Runner
+from offbox.ssh import ssh_argv
+from offbox.state import EnvState, HostState, StateStore
+from offbox.timings import stage
+
+logger = logging.getLogger(__name__)
+MAX_COPY_BYTES = 1024 * 1024
+_BLOCKED_COPIES = (PurePosixPath(".ssh"), PurePosixPath(".config/offbox"), PurePosixPath(".gnupg"))
+_CONTAINER_HOME = PurePosixPath("/home/dev")
+_BLOCKED_FIX = "Remove SSH, GnuPG and offbox configuration files from files.copy; offbox config shows which source sets it."
+_MIRROR_REF = "refs/offbox/head"
+DEFAULT_BRANCH = "origin/HEAD"
+DEFAULT_GIT_SHARING = ("HEAD", DEFAULT_BRANCH)
+
+_WRITE_FILE = r"""set -eu
+umask 077
+target=$1
+mkdir -p -- "$(dirname -- "$target")"
+tmp=$(mktemp "$target.XXXXXXXXXX")
+trap 'rm -f -- "$tmp"' EXIT HUP INT TERM
+base64 -d > "$tmp"
+mv -f -- "$tmp" "$target"
+"""
+_INIT_REPOSITORY = r"""set -eu
+command -v git >/dev/null 2>&1 || { echo missing-git; exit 0; }
+cd /work
+[ -d .git ] || git init -q
+git config receive.shallowUpdate true
+git config receive.denyCurrentBranch ignore
+"""
+_CHECKOUT = r"""set -eu
+cd /work
+head=$1
+branch=$2
+if [ -n "$branch" ]; then
+    git update-ref "refs/heads/$branch" "$head"
+    git symbolic-ref HEAD "refs/heads/$branch"
+else
+    git update-ref --no-deref HEAD "$head"
+fi
+git update-ref -d refs/offbox/head
+mkdir -p .git/info
+cat > .git/info/exclude
+git reset -q --mixed
+"""
+
+
+class MirrorPlan(Model):
+    head: str
+    branch: str | None
+    refs: dict[str, str]
+    exclude: str
+
+    def fingerprint(self) -> str:
+        return hashlib.sha256(self.model_dump_json().encode()).hexdigest()
+
+
+def git_sharing(config: GitConfig) -> list[str]:
+    """What the git mirror sends to the environment, as the list offbox up approves; origin/HEAD is the remote's default branch."""
+    return [*DEFAULT_GIT_SHARING, *sorted(set(config.refs) - set(DEFAULT_GIT_SHARING))] if config.mirror else []
+
+
+def copy_path(entry: str) -> PurePosixPath:
+    """The home-relative path of a files.copy entry; only regular paths under ~/ outside key and offbox directories."""
+    relative = PurePosixPath(entry[2:]) if entry.startswith("~/") else None
+    if (
+        relative is None
+        or not relative.parts
+        or any(part in ("", ".", "..") for part in entry[2:].split("/"))
+        or any(ord(char) < 32 or ord(char) == 127 for char in entry)
+    ):
+        raise PreconditionError(f"Invalid files.copy entry: {entry}", "Use paths below your home directory written as ~/path/to/file.")
+    if _blocked(relative):
+        raise PreconditionError(f"files.copy must not copy {entry}", _BLOCKED_FIX)
+    return relative
+
+
+def _blocked(relative: PurePosixPath) -> bool:
+    """Case-insensitive, because macOS home directories usually are."""
+    folded = PurePosixPath(str(relative).casefold())
+    return any(folded.is_relative_to(blocked) for blocked in _BLOCKED_COPIES)
+
+
+def unapproved(configured: Sequence[str], approved: Sequence[str] | None) -> list[str]:
+    return sorted(set(configured) - set(approved or ()))
+
+
+def check_sharing(project: ProjectConfig, recorded: EnvState) -> None:
+    """Refuse files.copy entries and git refs that offbox up has not approved; the VM can edit offbox.toml through sync."""
+    for entry in project.files.copy_:
+        copy_path(entry)
+    files = unapproved(project.files.copy_, recorded.approved_files)
+    refs = unapproved(git_sharing(project.git), DEFAULT_GIT_SHARING if recorded.approved_git is None else recorded.approved_git)
+    if files or refs:
+        names = [*(f"files.copy {entry}" for entry in files), *(f"git {ref}" for ref in refs)]
+        raise PreconditionError(
+            "offbox up has not approved sharing: " + ", ".join(names),
+            "Review files.copy and git with offbox config, then run offbox up to approve them.",
+        )
+
+
+def sharing_additions(project: ProjectConfig, recorded: EnvState) -> list[str]:
+    """Newly configured sharing that this up approves; the first up of an environment approves silently."""
+    messages: list[str] = []
+    for entry in project.files.copy_:
+        copy_path(entry)
+    if recorded.approved_files is not None and (files := unapproved(project.files.copy_, recorded.approved_files)):
+        messages.append("Copying new local files to the environment: " + ", ".join(files))
+    if recorded.approved_git is not None and (refs := unapproved(git_sharing(project.git), recorded.approved_git)):
+        messages.append("Mirroring new git refs to the environment: " + ", ".join(refs))
+    return messages
+
+
+class Sharing:
+    def __init__(self, runner: Runner, home: Path | None = None) -> None:
+        self.runner = runner
+        self.home = home or Path.home()
+
+    def _container(self, host: HostState, work: Worktree, script: str, args: Sequence[str], *, input: str, timeout: float) -> str:
+        argv = ["docker", "exec", "-i", "-u", "dev", work.container, "sh", "-c", script, "offbox-share", *args]
+        result = self.runner.run(ssh_argv(host.name, argv), check=False, input=input, timeout=timeout)
+        if result.returncode == 255:
+            raise ConnectionError_(f"Cannot reach host {host.name}", f"Run offbox host ssh {host.name} and check connectivity.")
+        if result.returncode:
+            raise CommandFailed(["docker", "exec", work.container, "offbox-share"], result.returncode, result.stderr)
+        return result.stdout
+
+    def copy_files(
+        self, work: Worktree, host: HostState, entries: Sequence[str], copied: Mapping[str, str], *, force: bool
+    ) -> dict[str, str]:
+        """Copy changed files.copy entries into the container home and return the digests now present there."""
+        result: dict[str, str] = {}
+        for entry in entries:
+            relative = copy_path(entry)
+            source = self.home.joinpath(*relative.parts)
+            fix = f"Create {source} or remove {entry} from files.copy; offbox config shows which source sets it."
+            try:
+                if not source.is_file():
+                    raise PreconditionError(f"files.copy source is not a regular file: {source}", fix)
+                home = self.home.resolve()
+                resolved = source.resolve()
+                if not resolved.is_relative_to(home) or _blocked(PurePosixPath(resolved.relative_to(home).as_posix())):
+                    raise PreconditionError(f"files.copy must not copy {entry}, which resolves to {resolved}", _BLOCKED_FIX)
+                if source.stat().st_size > MAX_COPY_BYTES:
+                    raise PreconditionError(f"files.copy source is larger than 1 MiB: {source}", "Copy large files another way.")
+                content = source.read_bytes()
+            except OSError as exc:
+                raise PreconditionError(f"Cannot read files.copy source {source}", fix) from exc
+            digest = hashlib.sha256(content).hexdigest()
+            if force or copied.get(entry) != digest:
+                target = _CONTAINER_HOME.joinpath(*relative.parts)
+                self._container(host, work, _WRITE_FILE, [str(target)], input=base64.b64encode(content).decode(), timeout=60)
+                logger.info("copied %s into %s", entry, work.name)
+            result[entry] = digest
+        return result
+
+    def _git(self, root: Path, *args: str) -> str:
+        return self.runner.run(["git", "-C", str(root), *args], timeout=30).stdout.strip()
+
+    def plan(self, root: Path, refs: Sequence[str]) -> MirrorPlan | None:
+        """What to mirror, or None while the repository has no commit yet."""
+        current = self.runner.run(["git", "-C", str(root), "rev-parse", "--verify", "-q", "HEAD^{commit}"], check=False, timeout=30)
+        if current.returncode:
+            return None
+        head = current.stdout.strip()
+        symbolic = self.runner.run(["git", "-C", str(root), "symbolic-ref", "-q", "--short", "HEAD"], check=False, timeout=30)
+        resolved: dict[str, str] = {}
+        for ref in sorted(set(refs)):
+            named = self.runner.run(["git", "-C", str(root), "rev-parse", "--symbolic-full-name", ref], check=False, timeout=30)
+            full = named.stdout.strip()
+            if named.returncode or not full.startswith("refs/"):
+                raise PreconditionError(
+                    f"git.refs entry is not a local branch, tag or remote-tracking ref: {ref}",
+                    "Fetch it or remove it from git.refs; offbox config shows which source sets it.",
+                )
+            resolved[full] = self._git(root, "rev-parse", "--verify", f"{full}^{{commit}}")
+        exclude = root / self._git(root, "rev-parse", "--git-path", "info/exclude")
+        try:
+            text = exclude.read_text() if exclude.is_file() else ""
+        except OSError as exc:
+            raise PreconditionError(f"Cannot read {exclude}", "Check the repository's info/exclude permissions.") from exc
+        default = self.runner.run(["git", "-C", str(root), "symbolic-ref", "-q", "refs/remotes/origin/HEAD"], check=False, timeout=30)
+        target = default.stdout.strip()
+        if default.returncode == 0 and target.startswith("refs/remotes/origin/") and target not in resolved:
+            commit = self.runner.run(
+                ["git", "-C", str(root), "rev-parse", "--verify", "-q", f"{target}^{{commit}}"], check=False, timeout=30
+            )
+            if commit.returncode == 0:
+                resolved[target] = commit.stdout.strip()
+            else:
+                logger.info("origin/HEAD points to missing %s; mirroring without the default branch", target)
+        branch = symbolic.stdout.strip() if symbolic.returncode == 0 and symbolic.stdout.strip() else None
+        return MirrorPlan(head=head, branch=branch, refs=resolved, exclude=text)
+
+    def mirror(self, work: Worktree, host: HostState, plan: MirrorPlan) -> bool:
+        """Push HEAD and the configured refs into /work/.git and point its index at HEAD without touching synced files.
+
+        Returns False without pushing when the environment image has no git."""
+        if self._container(host, work, _INIT_REPOSITORY, [], input="", timeout=60).strip() == "missing-git":
+            return False
+        receive = f"docker exec -i -u dev {work.container} git-receive-pack"
+        specs = [f"{plan.head}:{_MIRROR_REF}", *(f"{sha}:{ref}" for ref, sha in plan.refs.items())]
+        result = self.runner.run(
+            [
+                "git",
+                "-C",
+                str(work.root),
+                "push",
+                "--force",
+                "--quiet",
+                "--no-verify",
+                "--receive-pack",
+                receive,
+                f"offbox-{host.name}:/work",
+                *specs,
+            ],
+            check=False,
+            env={"GIT_SSH_COMMAND": "ssh"},
+            timeout=600,
+        )
+        if result.returncode:
+            raise PreconditionError(
+                "Cannot mirror git history to the environment: " + (result.stderr.strip().splitlines() or ["git push failed"])[-1],
+                "Check offbox status, then retry; set git.mirror = false (or OFFBOX_GIT_MIRROR=false) to run without git.",
+            )
+        try:
+            self._container(host, work, _CHECKOUT, [plan.head, plan.branch or ""], input=plan.exclude, timeout=120)
+        except CommandFailed as exc:
+            raise PreconditionError(
+                "Cannot check out the mirrored commit in the environment: " + (exc.stderr_tail.splitlines() or ["git failed"])[-1],
+                "Check git in the environment image, then retry; set git.mirror = false (or OFFBOX_GIT_MIRROR=false) to run without git.",
+            ) from exc
+        logger.info("mirrored %s into %s", plan.head, work.name)
+        return True
+
+    def apply(
+        self,
+        store: StateStore,
+        work: Worktree,
+        host: HostState,
+        project: ProjectConfig,
+        *,
+        force: bool,
+        git: bool = True,
+        repository: bool = True,
+    ) -> None:
+        """Bring copied files and the git mirror up to date; repository=False means /work/.git is gone and must be pushed again."""
+        recorded = store.read().envs.get(work.name)
+        if recorded is None:
+            raise PreconditionError("Environment registration disappeared", "Run offbox up.")
+        copied = dict(recorded.copied_files)
+        if project.files.copy_:
+            with stage("File copies"):
+                copied = self.copy_files(work, host, project.files.copy_, recorded.copied_files, force=force)
+        mirrored = recorded.mirrored_git
+        if project.git.mirror and git:
+            with stage("Git mirror"):
+                plan = self.plan(work.root, project.git.refs)
+                if plan is not None:
+                    fingerprint = plan.fingerprint()
+                    skipped = f"no-git:{fingerprint}"
+                    unchanged = recorded.mirrored_git == fingerprint and repository
+                    if force or not (unchanged or recorded.mirrored_git == skipped):
+                        mirrored = fingerprint if self.mirror(work, host, plan) else skipped
+                        if mirrored == skipped:
+                            console.warn(
+                                "The environment image has no git, so the git mirror was skipped. "
+                                "Fix: add git to the image or set git.mirror = false."
+                            )
+        if copied == recorded.copied_files and mirrored == recorded.mirrored_git:
+            return
+        with store.transaction() as state:
+            current = state.envs.get(work.name)
+            if current is not None and current.host == host.name:
+                current.copied_files = copied
+                current.mirrored_git = mirrored

offbox/ssh.py

@@ -0,0 +1,179 @@
+import os
+import re
+import shlex
+import stat
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from offbox import console
+from offbox.errors import ConnectionError_, PreconditionError
+from offbox.paths import Paths
+from offbox.providers import validate_name
+from offbox.runner import Runner
+from offbox.state import HostState, State
+
+
+def master_pid(runner: Runner, name: str) -> int | None:
+    validate_name(name)
+    result = runner.run(["ssh", "-O", "check", f"offbox-{name}"], check=False, env={"LC_ALL": "C"}, timeout=10)
+    if result.returncode:
+        diagnostics = [line.strip() for line in result.stderr.splitlines() if line.strip()]
+        if diagnostics and all(
+            re.fullmatch(r"Control socket connect\(.+\): (No such file or directory|Connection refused)", line) for line in diagnostics
+        ):
+            return None
+        raise ConnectionError_(
+            f"Cannot check SSH master for {name}: {result.stderr.strip()}",
+            f"Check SSH configuration and control socket permissions for offbox-{name}, then retry.",
+        )
+    match = re.search(r"Master running \(pid=([1-9][0-9]*)\)", result.stderr + "\n" + result.stdout)
+    if match is None:
+        raise PreconditionError("Cannot identify the SSH master", "Check OpenSSH multiplexing output and retry.")
+    return int(match[1])
+
+
+def close_master(runner: Runner, name: str) -> None:
+    if master_pid(runner, name) is None:
+        return
+    result = runner.run(["ssh", "-O", "exit", f"offbox-{name}"], check=False, env={"LC_ALL": "C"}, timeout=10)
+    if result.returncode:
+        raise ConnectionError_(
+            f"Cannot close SSH master for {name}: {result.stderr.strip()}", f"Run ssh -O exit offbox-{name}, then retry cleanup."
+        )
+
+
+def write_private(path: Path, content: str) -> None:
+    temporary: Path | None = None
+    try:
+        destination = path.resolve() if path.is_symlink() else path
+        destination.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        mode = stat.S_IMODE(destination.stat().st_mode) if destination.exists() else 0o600
+        with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=destination.parent, delete=False) as target:
+            temporary = Path(target.name)
+            target.write(content)
+            target.flush()
+            os.fsync(target.fileno())
+        temporary.chmod(mode)
+        os.replace(temporary, destination)
+    except OSError as exc:
+        raise PreconditionError(f"Cannot write {path}", "Check directory permissions and free disk space.") from exc
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+def validate_address(address: str) -> str:
+    if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9.:-]*", address) is None:
+        raise PreconditionError("Invalid SSH address", "Use a hostname or IP address without SSH options or whitespace.")
+    return address
+
+
+def validate_user(user: str) -> str:
+    if re.fullmatch(r"[a-z_][a-z0-9_.-]*", user) is None:
+        raise PreconditionError("Invalid SSH user", "Use a valid SSH username.")
+    return user
+
+
+def quote_path(value: Path) -> str:
+    text = str(value)
+    if any(char in text for char in "\r\n\0"):
+        raise PreconditionError("Unsafe path in SSH configuration", "Choose a path without control characters.")
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"').replace("%", "%%") + '"'
+
+
+def include_line(paths: Paths) -> str:
+    return f"Include {quote_path(paths.config / 'ssh_config')}"
+
+
+def remove_include(paths: Paths, config: Path | None = None) -> None:
+    target = config or Path.home() / ".ssh/config"
+    try:
+        previous = target.read_bytes()
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        raise PreconditionError(f"Cannot read SSH configuration {target}", "Check SSH configuration permissions.") from exc
+    owned = include_line(paths).encode()
+    remaining = b"".join(line for line in previous.splitlines(keepends=True) if line.rstrip(b"\r\n") != owned)
+    if remaining != previous:
+        try:
+            content = remaining.decode("utf-8")
+        except UnicodeError as exc:
+            raise PreconditionError(f"Cannot read SSH configuration {target}", "Correct its UTF-8 encoding.") from exc
+        write_private(target, content)
+
+
+def ensure_include(paths: Paths, config: Path | None = None) -> None:
+    target = config or Path.home() / ".ssh/config"
+    include = include_line(paths)
+    try:
+        previous = target.read_text(encoding="utf-8") if target.exists() else ""
+    except (OSError, UnicodeError) as exc:
+        raise PreconditionError(f"Cannot read SSH configuration {target}", "Check SSH configuration permissions.") from exc
+    remaining = [line for line in previous.splitlines(keepends=True) if line.strip() != include]
+    updated = include + "\n" + "".join(remaining)
+    if updated != previous:
+        write_private(target, updated)
+        console.info(f"Added offbox Include at the top of {target}")
+
+
+def default_ssh_key() -> Path:
+    """~/.ssh/id_ed25519 unless only the dedicated ~/.ssh/offbox_ed25519 that setup creates exists."""
+    directory = Path.home() / ".ssh"
+    default = directory / "id_ed25519"
+    dedicated = directory / "offbox_ed25519"
+    if not default.exists() and not default.with_name("id_ed25519.pub").exists() and dedicated.exists():
+        return dedicated
+    return default
+
+
+def sync_config(paths: Paths, state: State) -> None:
+    control = paths.ensure_control()
+    blocks: list[str] = []
+    for name, host in sorted(state.hosts.items()):
+        validate_name(name)
+        if not host.address:
+            continue
+        validate_address(host.address)
+        validate_user(host.ssh_user)
+        key = (host.ssh_key or Path.home() / ".ssh/id_ed25519").expanduser()
+        blocks.append(
+            f"Host offbox-{name}\n"
+            f"  HostName {host.address}\n"
+            f"  User {host.ssh_user}\n"
+            f"  Port {host.ssh_port}\n"
+            f"  IdentityFile {quote_path(key)}\n"
+            f"  UserKnownHostsFile {quote_path(host.known_hosts_path)}\n"
+            f"  HostKeyAlias offbox-{name}\n"
+            "  HostKeyAlgorithms ssh-ed25519\n"
+            "  StrictHostKeyChecking yes\n"
+            "  BatchMode yes\n"
+            "  IdentitiesOnly yes\n"
+            "  ForwardAgent no\n"
+            "  ForwardX11 no\n"
+            "  ControlMaster auto\n"
+            f"  ControlPath {quote_path(control / '%C').replace('%%C', '%C')}\n"
+            "  ControlPersist 30m\n"
+            "  ServerAliveInterval 15\n"
+            "  ServerAliveCountMax 4\n"
+        )
+    write_private(paths.config / "ssh_config", "\n".join(blocks))
+
+
+def ssh_argv(name: str, argv: Sequence[str] = (), *, options: Sequence[str] = ()) -> list[str]:
+    validate_name(name)
+    command = ["ssh", *options, f"offbox-{name}"]
+    return [*command, "--", shlex.join(argv)] if argv else command
+
+
+def known_host(name: str, public_key: str) -> str:
+    validate_name(name)
+    fields = public_key.strip().split()
+    if len(fields) < 2 or fields[0] != "ssh-ed25519" or re.fullmatch(r"[A-Za-z0-9+/=]+", fields[1]) is None:
+        raise PreconditionError("Invalid ed25519 SSH public key", "Use an ed25519 host key and retry.")
+    return f"offbox-{name} {fields[0]} {fields[1]}\n"
+
+
+def host_key_path(host: HostState) -> Path:
+    return host.known_hosts_path.parent / "ssh_host_ed25519_key"