puremethod 0.1.0__py3-none-any.whl

app/scan.py

@@ -0,0 +1,65 @@
+"""The one cross-tenant query: what needs a worker (08-app.md §5 step 2). Returns ids only.
+Supervisor side; `app.api` may not import it (import-linter)."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from app import leases
+from app.db import Database
+from app.statuses import DRIVABLE
+
+log = logging.getLogger("app.scan")
+
+
+@dataclass(frozen=True)
+class Work:
+    kind: str  # run | preflight | credcheck | llmsearch | profilecheck | literature
+    tenant_id: str
+    id: str
+
+    @property
+    def lease_key(self) -> str:
+        return f"{self.kind}:{self.id}"
+
+
+def work(db: Database, status_of: Callable[[str], str | None], now: float) -> list[Work]:
+    """Runs that are queued, interrupted at start, have pending commands, or are drivable;
+    pending executor preflights and credential checks. Anything whose lease is held is
+    skipped."""
+    with db.tx() as c:
+        runs = c.execute(
+            "SELECT r.tenant_id, r.id, r.state, r.ledger_run_id, r.worker_error, "
+            "EXISTS (SELECT 1 FROM commands m WHERE m.run_id = r.id AND m.state = 'pending') "
+            "FROM runs r WHERE r.state <> 'start_failed' ORDER BY r.created_at, r.id")
+        checks = c.execute("SELECT tenant_id, id FROM preflight_checks WHERE state = 'pending' "
+                           "ORDER BY created_at, id")
+        creds = c.execute("SELECT tenant_id, id FROM credential_checks WHERE state = 'pending' "
+                          "ORDER BY created_at, id")
+        searches = c.execute("SELECT tenant_id, id FROM llm_searches WHERE state = 'pending' "
+                             "ORDER BY created_at, id")
+        profile_checks = c.execute("SELECT tenant_id, id FROM profile_checks "
+                                   "WHERE state = 'pending' ORDER BY created_at, id")
+        # `starting` too: a start whose worker died is taken up again once its lease is free.
+        bundled = c.execute("SELECT tenant_id FROM bundled_services "
+                            "WHERE state IN ('pending', 'starting') ORDER BY updated_at, tenant_id")
+    out: list[Work] = []
+    for tenant_id, run_id, state, ledger_run_id, worker_error, pending in runs:
+        if worker_error:
+            continue  # a new command clears it (TenantRepo.add_command)
+        wanted = state in ("queued", "starting") or bool(pending)
+        if not wanted and ledger_run_id is not None:
+            try:
+                wanted = status_of(ledger_run_id) in DRIVABLE
+            except Exception as exc:  # one unreadable run must not stop scheduling the rest
+                log.warning("cannot read the status of run %s: %s", run_id, type(exc).__name__)
+        if wanted:
+            out.append(Work("run", tenant_id, run_id))
+    out += [Work("preflight", t, i) for t, i in checks]
+    out += [Work("credcheck", t, i) for t, i in creds]
+    out += [Work("llmsearch", t, i) for t, i in searches]
+    out += [Work("profilecheck", t, i) for t, i in profile_checks]
+    out += [Work("literature", t, t) for (t,) in bundled]
+    return [w for w in out if not leases.held(db, w.lease_key, now)]

app/server.py

@@ -0,0 +1,24 @@
+"""Builds what the API process holds (08-app.md §5 step 8): the app database, the ledger
+behind `ReadOnlyLedger`, a status-only `Loop`, sign-in, the output store and the link key."""
+
+from __future__ import annotations
+
+from app.accounts import LocalTokenAuth, Sessions, SigninCodes
+from app.api.common import Ctx
+from app.db import Database
+from app.keys import link_key
+from app.outputs import LocalOutputs
+from app.readonly import ReadOnlyLedger, status_loop
+from app.settings import Settings
+from ledger import Ledger
+
+
+def build_ctx(settings: Settings, db: Database | None = None) -> Ctx:
+    settings.ensure_dirs()
+    db = db or Database(settings.app_db)
+    ledger = ReadOnlyLedger(Ledger(settings.ledger_url, settings.artifact_root))
+    return Ctx(settings=settings, db=db, ledger=ledger,
+               status=status_loop(ledger, settings.output_root), auth=LocalTokenAuth(db),
+               sessions=Sessions(db),
+               outputs=LocalOutputs(settings.output_root, settings.tmp_dir),
+               link_key=link_key(settings.master_key), codes=SigninCodes(db))

app/settings.py

@@ -0,0 +1,125 @@
+"""Deployment settings, read from `PM_*` environment variables (08-app.md §5 steps 3, 8, 9)."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from app import paths
+
+KEY_BYTES = paths.KEY_BYTES
+Mode = Literal["self-hosted", "hosted"]
+# An installed wheel carries the built UI inside the package (08-app.md §5 step 11); a source
+# checkout uses the static export that `pnpm build` in implementation/web writes.
+_PACKAGED_WEB_DIR = Path(__file__).resolve().parent / "_web"
+DEFAULT_WEB_DIR = (_PACKAGED_WEB_DIR if (_PACKAGED_WEB_DIR / "index.html").is_file()
+                   else Path(__file__).resolve().parents[2] / "web" / "out")
+
+
+class SettingsError(Exception):
+    """The deployment cannot start as configured."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    mode: Mode
+    data_dir: Path
+    master_key: bytes = field(repr=False)
+    host: str = "127.0.0.1"
+    port: int = 8400
+    purescholar_url: str | None = None
+    puretrace_url: str | None = None
+    tectonic_image: str | None = None
+    purescholar_image: str | None = None  # development and tests only (08 §5 step 12)
+    web_dir: Path | None = None  # the built web UI (static export); served at `/` if present
+
+    @property
+    def app_db(self) -> Path:
+        return self.data_dir / "app.db"
+
+    @property
+    def ledger_url(self) -> str:
+        return f"sqlite:///{self.data_dir / 'ledger.db'}"
+
+    @property
+    def artifact_root(self) -> Path:
+        return self.data_dir / "artifacts"
+
+    @property
+    def output_root(self) -> Path:
+        return self.data_dir / "outputs"
+
+    @property
+    def executor_root(self) -> Path:
+        return self.data_dir / "executors"
+
+    @property
+    def tmp_dir(self) -> Path:
+        return self.data_dir / "tmp"
+
+    def ensure_dirs(self) -> None:
+        # 0700 on POSIX: the app database holds token hashes and credential ciphertexts.
+        self.data_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        for d in (self.artifact_root, self.output_root, self.executor_root, self.tmp_dir):
+            d.mkdir(parents=True, exist_ok=True)
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> Settings:
+        env = os.environ if env is None else env
+        mode = env.get("PM_MODE", "self-hosted")
+        if mode not in ("self-hosted", "hosted"):
+            raise SettingsError("PM_MODE is self-hosted or hosted")
+        data_dir = data_dir_from(env)
+        return cls(mode=mode,  # type: ignore[arg-type]
+                   data_dir=data_dir, master_key=load_master_key(env, data_dir),
+                   host=env.get("PM_HOST", "127.0.0.1"), port=int(env.get("PM_PORT", "8400")),
+                   purescholar_url=env.get("PM_PURESCHOLAR_URL") or None,
+                   puretrace_url=env.get("PM_PURETRACE_URL") or None,
+                   tectonic_image=env.get("PM_TECTONIC_IMAGE") or None,
+                   purescholar_image=env.get("PM_PURESCHOLAR_IMAGE") or None,
+                   web_dir=Path(env["PM_WEB_DIR"]).resolve() if env.get("PM_WEB_DIR")
+                   else DEFAULT_WEB_DIR)
+
+
+def data_dir_from(env: Mapping[str, str]) -> Path:
+    return (Path(env["PM_DATA_DIR"]) if env.get("PM_DATA_DIR")
+            else paths.default_data_dir()).resolve()
+
+
+def key_file(env: Mapping[str, str]) -> Path:
+    """The key file `serve` reads when `PM_MASTER_KEY` is not set, and the launcher creates."""
+    return Path(env["PM_MASTER_KEY_FILE"]).resolve() if env.get("PM_MASTER_KEY_FILE") \
+        else paths.default_key_file().resolve()
+
+
+def load_master_key(env: Mapping[str, str], data_dir: Path) -> bytes:
+    """32 bytes from `PM_MASTER_KEY` (base64), or from a key file outside the data directory:
+    `PM_MASTER_KEY_FILE`, else the default location (KB-025). No key, no start (KB-021);
+    only the launcher creates the file. Errors never echo key material."""
+    raw: bytes
+    if env.get("PM_MASTER_KEY"):
+        try:
+            raw = base64.b64decode(env["PM_MASTER_KEY"], validate=True)
+        except (binascii.Error, ValueError):
+            raise SettingsError("PM_MASTER_KEY is not valid base64") from None
+    elif env.get("PM_MASTER_KEY_FILE") or key_file(env).is_file():
+        path = key_file(env)
+        if path.is_relative_to(data_dir):
+            raise SettingsError("the master key file must be outside the data directory")
+        try:
+            raw = base64.b64decode(path.read_bytes().strip(), validate=True)
+        except OSError:
+            raise SettingsError(f"cannot read the master key file {path}") from None
+        except (binascii.Error, ValueError):
+            raise SettingsError("the master key file does not hold valid base64") from None
+    else:
+        raise SettingsError("no master key: run `puremethod`, which creates one, or set "
+                            "PM_MASTER_KEY or PM_MASTER_KEY_FILE")
+    if len(raw) != KEY_BYTES:
+        raise SettingsError(f"the master key must be {KEY_BYTES} bytes")
+    return raw

app/setup.py

@@ -0,0 +1,117 @@
+"""Setup status (08-app.md §5 steps 13 and 14, KB-029), computed from configuration already
+stored: credential checks, executor preflights and the service settings. There is no separate
+setup state. Reads metadata only; nothing here decrypts (INV-2)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from app.repo import TenantRepo
+
+PURESCHOLAR_CREDENTIAL = "purescholar"
+PURETRACE_CREDENTIAL = "puretrace"
+LOCAL_NOT_YET = "the bundled PureScholar is not available in this version; use a remote one"
+
+
+@dataclass(frozen=True)
+class ServiceStatus:
+    state: str  # stopped | starting | ready | failed
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class Setup:
+    model_key: bool
+    literature: ServiceStatus
+    executor: bool
+    missing: list[str] = field(default_factory=list)
+
+    @property
+    def complete(self) -> bool:
+        return not self.missing
+
+    def as_dict(self) -> dict[str, Any]:
+        return {"model_key": self.model_key, "executor": self.executor,
+                "literature": {"state": self.literature.state,
+                               "reason": self.literature.reason},
+                "missing": self.missing, "complete": self.complete}
+
+
+LocalStatus = Callable[[TenantRepo], ServiceStatus]
+
+
+def local_not_yet(repo: TenantRepo) -> ServiceStatus:
+    return ServiceStatus("failed", LOCAL_NOT_YET)
+
+
+def _passed(report: dict[str, Any] | None) -> bool:
+    return bool(report and report.get("ok"))
+
+
+def literature_status(repo: TenantRepo, local: LocalStatus = local_not_yet) -> ServiceStatus:
+    setting = repo.service_setting("literature")
+    if setting is None:
+        return ServiceStatus("stopped", "no literature service is configured")
+    if setting.get("mode") == "local":
+        return local(repo)
+    url = setting.get("url")
+    cred = next((c for c in repo.list_credentials() if c.name == PURESCHOLAR_CREDENTIAL), None)
+    if cred is None:
+        return ServiceStatus("failed", f"no {PURESCHOLAR_CREDENTIAL!r} credential is stored")
+    check = repo.latest_credential_check(cred.id)
+    if check is None or check.request.get("url") != url:
+        return ServiceStatus("failed", "the PureScholar key has not been checked against "
+                                       "this URL; check it again")
+    if check.state == "pending":
+        return ServiceStatus("starting", "checking the PureScholar key")
+    if _passed(check.report):
+        return ServiceStatus("ready")
+    problems = (check.report or {}).get("problems") or ["the check failed"]
+    return ServiceStatus("failed", "; ".join(str(p) for p in problems))
+
+
+def setup_status(repo: TenantRepo, local: LocalStatus = local_not_yet) -> Setup:
+    # 08 §5 step 14 (KB-037): a passed credential check, or a passed profile check (a model
+    # that needs no key has no credential to check).
+    model_key = any(
+        c.type == "llm-key" and _passed(getattr(repo.latest_credential_check(c.id),
+                                                "report", None))
+        for c in repo.list_credentials()) or any(
+        repo.profile_checked(p) for p in repo.list_profiles())
+    executor = any(_passed(getattr(repo.latest_preflight(x.id), "report", None))
+                   for x in repo.list_executors())
+    literature = literature_status(repo, local)
+    missing = []
+    if not model_key:
+        missing.append("model: choose a model and check it")
+    if literature.state != "ready":
+        missing.append(f"literature service: {literature.reason or literature.state}")
+    if not executor:
+        missing.append("executor: add one and run its check")
+    return Setup(model_key, literature, executor, missing)
+
+
+LOCAL = "local"  # a run's PureScholar is the bundled one (08 §5 step 12)
+
+
+def run_services(repo: TenantRepo, purescholar_fallback: str | None,
+                 puretrace_fallback: str | None) -> dict[str, str | None]:
+    """What a new run records about its services, like its executor: later setting changes
+    never move a run to another service (review of slice 3, Auditor MEDIUM-2)."""
+    lit = repo.service_setting("literature")
+    ps = LOCAL if lit and lit.get("mode") == "local" else \
+        service_url(repo, "literature", purescholar_fallback)
+    return {"purescholar": ps, "puretrace": service_url(repo, "puretrace", puretrace_fallback)}
+
+
+def service_url(repo: TenantRepo, service: str, fallback: str | None) -> str | None:
+    """The URL a run uses (08 §4, KB-029): the tenant's remote setting, else the `PM_*`
+    fallback. Local mode's URL comes from the bundled containers (§5 step 12)."""
+    setting = repo.service_setting(service)
+    if setting and setting.get("mode") == "local":
+        return None  # the bundled PureScholar's address comes from app.bundled, never a fallback
+    if setting and setting.get("url"):
+        return str(setting["url"])
+    return fallback

app/ssh_chain.py

@@ -0,0 +1,102 @@
+"""SSH connections through jump hosts, for `app`'s own SSH work (KB-036): the Docker probe
+of onboarding step 3 and, with `via_ssh` model endpoints, tunnels. `executor` has its own
+connection code for jobs; `app` does not reach into it (05-executor.md §3).
+
+Every hop trusts exactly its confirmed host key and refuses any other (INV-10). Failures
+name the hop."""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import paramiko
+
+from app.ssh_hosts import load_private, parse_host_key
+
+TIMEOUT_S = 15.0
+
+
+class HopFailed(OSError):
+    """A hop could not be reached or refused us. The message names the hop, never key data."""
+
+
+@dataclass
+class Chain:
+    """Open connections, first hop first; `client` is the target's."""
+    clients: list[paramiko.SSHClient]
+
+    @property
+    def client(self) -> paramiko.SSHClient:
+        return self.clients[-1]
+
+    def close(self) -> None:
+        for c in reversed(self.clients):
+            c.close()
+
+
+def _trusting(host: str, port: int, host_key: str) -> paramiko.SSHClient:
+    hk = parse_host_key(host_key)
+    client = paramiko.SSHClient()
+    name = host if port == 22 else f"[{host}]:{port}"
+    client.get_host_keys().add(name, hk.type, paramiko.PKey.from_type_string(
+        hk.type, base64.b64decode(hk.key)))
+    client.set_missing_host_key_policy(paramiko.RejectPolicy())
+    return client
+
+
+def _reason(exc: Exception, host: str, port: int, user: str) -> str:
+    if isinstance(exc, paramiko.BadHostKeyException):
+        return (f"{host}'s host key does not match the confirmed one; the server may have been "
+                "replaced or impersonated")
+    if isinstance(exc, paramiko.AuthenticationException):
+        return f"{host} refused the SSH key for user {user!r}"
+    if isinstance(exc, ValueError):
+        return f"the SSH key for {host} is missing or is not a supported private key"
+    return f"cannot reach {host}:{port} ({type(exc).__name__})"
+
+
+def connect(hops: list[dict[str, Any]], private_key: Callable[[str], str],
+            timeout: float = TIMEOUT_S) -> Chain:
+    """Connects through `hops` in order; the last is the target. Each hop is a dict with
+    host, user, port, key_credential and host_key. `private_key(name)` returns a key's text."""
+    clients: list[paramiko.SSHClient] = []
+    sock: Any = None
+    try:
+        for i, hop in enumerate(hops):
+            host, port, user = str(hop["host"]), int(hop.get("port", 22)), str(hop["user"])
+            if not hop.get("host_key"):
+                raise HopFailed(f"{host} has no confirmed host key")
+            client = _trusting(host, port, str(hop["host_key"]))
+            try:
+                client.connect(host, port=port, username=user, sock=sock,
+                               pkey=load_private(private_key(str(hop["key_credential"]))),
+                               timeout=timeout, banner_timeout=timeout, auth_timeout=timeout,
+                               allow_agent=False, look_for_keys=False)
+            except (paramiko.SSHException, OSError, EOFError, ValueError) as exc:
+                client.close()
+                raise HopFailed(_reason(exc, host, port, user)) from None
+            clients.append(client)
+            if i + 1 < len(hops):
+                nxt = hops[i + 1]
+                transport = client.get_transport()
+                try:
+                    if transport is None:
+                        raise paramiko.SSHException("no transport")
+                    sock = transport.open_channel(
+                        "direct-tcpip", (str(nxt["host"]), int(nxt.get("port", 22))),
+                        ("127.0.0.1", 0), timeout=timeout)
+                except (paramiko.SSHException, OSError) as exc:
+                    raise HopFailed(f"{host} cannot reach {nxt['host']}:{nxt.get('port', 22)} "
+                                    f"({type(exc).__name__})") from None
+    except BaseException:
+        Chain(clients).close()
+        raise
+    return Chain(clients)
+
+
+def hops_of(config: dict[str, Any]) -> list[dict[str, Any]]:
+    """The connection order for an `ssh` executor config: its jumps, then the machine."""
+    return [*config.get("jumps", []), config]

app/ssh_hosts.py

@@ -0,0 +1,244 @@
+"""SSH conveniences for adding an `ssh` executor (08-app.md §3 Onboarding step 3, KB-035).
+
+Self-hosted only, except `fetch_host_key`: the user's `~/.ssh/config` hosts, their key files,
+and `known_hosts`. Host keys are confirmed by fingerprint before an executor stores one
+(INV-10). Private keys are returned only to be sealed as credentials: never logged, never in
+a response.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import io
+import socket
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import paramiko
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+FETCH_TIMEOUT_S = 10.0
+KnownState = Literal["known", "unknown", "changed"]
+
+
+class SSHSetupError(ValueError):
+    """A reason the user can act on. Never carries key material."""
+
+
+def ssh_dir() -> Path:
+    """The user's `~/.ssh`. Tests point it elsewhere."""
+    return Path.home() / ".ssh"
+
+
+# ---- ~/.ssh/config ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class SSHHost:
+    name: str
+    address: str
+    user: str | None
+    port: int
+    has_key_file: bool
+    proxy_jump: tuple[str, ...] = ()  # hops in order, as written: names or [user@]host[:port]
+
+
+def _config() -> paramiko.SSHConfig:
+    path = ssh_dir() / "config"
+    return paramiko.SSHConfig.from_path(str(path)) if path.is_file() else paramiko.SSHConfig()
+
+
+def _key_files(entry: paramiko.SSHConfigDict) -> list[Path]:
+    return [Path(p).expanduser() for p in entry.get("identityfile", [])]
+
+
+def list_hosts() -> list[SSHHost]:
+    """Named hosts from `~/.ssh/config`; wildcard patterns are not hosts."""
+    cfg = _config()
+    out = []
+    for name in sorted(cfg.get_hostnames()):
+        if any(ch in name for ch in "*?!"):
+            continue
+        entry = cfg.lookup(name)
+        jump = str(entry.get("proxyjump", "")).strip()
+        hops = tuple(h.strip() for h in jump.split(",") if h.strip()) \
+            if jump.lower() not in ("", "none") else ()
+        out.append(SSHHost(name=name, address=str(entry.get("hostname", name)),
+                           user=entry.get("user"), port=int(entry.get("port", 22)),
+                           has_key_file=any(p.is_file() for p in _key_files(entry)),
+                           proxy_jump=hops))
+    return out
+
+
+def parse_hop(text: str) -> tuple[str | None, str, int]:
+    """`[user@]host[:port]` from a `ProxyJump` list: (user, host, port)."""
+    user, _, rest = text.rpartition("@")
+    host, port = rest, 22
+    if rest.startswith("["):  # [v6]:port
+        host, _, tail = rest[1:].partition("]")
+        port = int(tail[1:]) if tail.startswith(":") else 22
+    elif rest.count(":") == 1:
+        host, _, p = rest.partition(":")
+        port = int(p)
+    return (user or None), host, port
+
+
+def read_key_for(name: str) -> tuple[str, str]:
+    """The private key file `~/.ssh/config` names for host `name`, read once:
+    (private key text, public key line). Passphrase-protected keys are refused."""
+    if name not in {h.name for h in list_hosts()}:
+        raise SSHSetupError(f"no host named {name!r} in ~/.ssh/config")
+    files = [p for p in _key_files(_config().lookup(name)) if p.is_file()]
+    if not files:
+        raise SSHSetupError(f"~/.ssh/config names no existing key file for {name!r}")
+    text = files[0].read_text(encoding="utf-8")
+    return text, public_line(load_private(text))
+
+
+# ---- keys ------------------------------------------------------------------------------------
+
+def load_private(text: str) -> paramiko.PKey:
+    for cls in (paramiko.Ed25519Key, paramiko.ECDSAKey, paramiko.RSAKey):
+        try:
+            return cls.from_private_key(io.StringIO(text))
+        except paramiko.PasswordRequiredException:
+            raise SSHSetupError("the key is protected by a passphrase; puremethod cannot use "
+                                "it. Generate a key here instead, or use one without a "
+                                "passphrase") from None
+        except (paramiko.SSHException, ValueError):
+            continue
+    raise SSHSetupError("the file is not a supported private key (Ed25519, ECDSA or RSA)")
+
+
+def public_line(key: paramiko.PKey) -> str:
+    return f"{key.get_name()} {key.get_base64()} puremethod"
+
+
+def generate() -> tuple[str, str]:
+    """A new Ed25519 key pair: (OpenSSH private key text, public key line)."""
+    private = Ed25519PrivateKey.generate()
+    text = private.private_bytes(serialization.Encoding.PEM,
+                                 serialization.PrivateFormat.OpenSSH,
+                                 serialization.NoEncryption()).decode()
+    pub = private.public_key().public_bytes(serialization.Encoding.OpenSSH,
+                                            serialization.PublicFormat.OpenSSH).decode()
+    return text, f"{pub} puremethod"
+
+
+# ---- host keys (INV-10) ----------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class HostKey:
+    type: str
+    key: str  # base64
+    fingerprint: str  # "SHA256:<base64>", as `ssh` prints it
+
+    @property
+    def line(self) -> str:
+        return f"{self.type} {self.key}"
+
+
+def fingerprint(key_b64: str) -> str:
+    digest = hashlib.sha256(base64.b64decode(key_b64)).digest()
+    return "SHA256:" + base64.b64encode(digest).decode().rstrip("=")
+
+
+def parse_host_key(line: str) -> HostKey:
+    """Validates a stored `<type> <base64>` host key."""
+    parts = line.split()
+    if len(parts) != 2:
+        raise SSHSetupError("a host key is '<type> <base64>'")
+    try:
+        paramiko.PKey.from_type_string(parts[0], base64.b64decode(parts[1], validate=True))
+    except (ValueError, paramiko.SSHException):
+        raise SSHSetupError("the host key is not a valid SSH public key") from None
+    return HostKey(parts[0], parts[1], fingerprint(parts[1]))
+
+
+def fetch_host_key(host: str, port: int, timeout: float = FETCH_TIMEOUT_S) -> HostKey:
+    """The key `host` presents, without logging in."""
+    try:
+        sock = socket.create_connection((host, port), timeout=timeout)
+    except OSError as exc:
+        raise SSHSetupError(f"cannot reach {host}:{port} ({type(exc).__name__})") from None
+    t = paramiko.Transport(sock)
+    try:
+        t.start_client(timeout=timeout)
+        k = t.get_remote_server_key()
+    except (paramiko.SSHException, OSError, EOFError) as exc:
+        raise SSHSetupError(f"{host}:{port} did not answer as an SSH server "
+                            f"({type(exc).__name__})") from None
+    finally:
+        t.close()
+    return HostKey(k.get_name(), k.get_base64(), fingerprint(k.get_base64()))
+
+
+def known_state(host: str, port: int, key: HostKey) -> KnownState:
+    """Whether the user's `~/.ssh/known_hosts` trusts this key for this host."""
+    path = ssh_dir() / "known_hosts"
+    if not path.is_file():
+        return "unknown"
+    try:
+        hk = paramiko.HostKeys(str(path))
+    except (OSError, paramiko.SSHException, ValueError):
+        return "unknown"
+    name = host if port == 22 else f"[{host}]:{port}"
+    entry = hk.lookup(name)
+    if not entry:
+        return "unknown"
+    if key.type in entry:
+        return "known" if entry[key.type].get_base64() == key.key else "changed"
+    return "unknown"  # trusted under another key type; this one is confirmed by fingerprint
+
+
+def known_key(host: str, port: int) -> HostKey | None:
+    """The key `~/.ssh/known_hosts` trusts for this host, if any (ed25519 first). For a host
+    the engine cannot reach directly, such as one behind a jump host, a matching entry is the
+    confirmation (INV-10, KB-036)."""
+    path = ssh_dir() / "known_hosts"
+    if not path.is_file():
+        return None
+    try:
+        entry = paramiko.HostKeys(str(path)).lookup(host if port == 22 else f"[{host}]:{port}")
+    except (OSError, paramiko.SSHException, ValueError):
+        return None
+    if not entry:
+        return None
+    for kind in ("ssh-ed25519", "ecdsa-sha2-nistp256", "rsa-sha2-512", "ssh-rsa",
+                 *entry.keys()):
+        if kind in entry:
+            b64 = entry[kind].get_base64()
+            return HostKey(type=kind, key=b64, fingerprint=fingerprint(b64))
+    return None
+
+
+# ---- Docker on the host (onboarding step 3) ----------------------------------------------------
+
+def docker_answers(host: str, port: int, user: str, private_key: str, host_key: str,
+                   timeout: float = FETCH_TIMEOUT_S) -> bool:
+    """Whether `docker version` answers for `user` on the host, over the confirmed host key."""
+    hop: dict[str, object] = {"host": host, "port": port, "user": user, "key_credential": "target",
+           "host_key": host_key}
+    return docker_answers_via([hop], lambda _: private_key, timeout)
+
+
+def docker_answers_via(hops: list[dict[str, object]], private_key: Callable[[str], str],
+                       timeout: float = FETCH_TIMEOUT_S) -> bool:
+    """`docker_answers` through jump hosts: `hops` ends with the target (KB-036)."""
+    from app import ssh_chain  # imports this module, so not at the top
+
+    try:
+        chain = ssh_chain.connect(list(hops), private_key, timeout)
+    except (paramiko.SSHException, OSError, EOFError, SSHSetupError):
+        return False
+    try:
+        _, out, _ = chain.client.exec_command("docker version --format '{{.Server.Version}}'",
+                                              timeout=timeout)
+        return out.channel.recv_exit_status() == 0 and bool(out.read().strip())
+    except (paramiko.SSHException, OSError, EOFError):
+        return False
+    finally:
+        chain.close()