gitpane 1.0.0__py3-none-any.whl

gitpane/account/keyring_reader.py

@@ -0,0 +1,135 @@
+"""Read, without changing anything, what the session bus tells of its Secret Service.
+
+Four questions only, always in this order, and the read stops at the first answer that decides: the bus daemon is
+asked whether anyone owns the Secret Service name, then which process owns it, then the service which object its
+``default`` alias names, then that object whether it is locked. The owning process is turned into a program name
+through /proc, which tells which keyring answers. Asking the bus daemon first, and refusing D-Bus activation on every
+message, keeps a Secret Service that does not run from being started by this read; nothing is created, aliased or
+unlocked, and no secret is ever read. Each call is bounded, and the read blocks, so it belongs on a worker thread only.
+
+Only Linux reads, through a table indexed by the system; the connection is received through a factory, so the tests
+read a private bus and only ``read_session_keyring_state`` reaches the user's session bus.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from PySide6.QtDBus import QDBus, QDBusConnection, QDBusMessage, QDBusObjectPath, QDBusVariant
+
+from gitpane.account.keyring_state import NO_DEFAULT_COLLECTION_PATH, UNKNOWN_KEYRING_READING, KeyringReading, SecretServiceAnswers, keyring_reading
+from gitpane.config import KEYRING_READ_TIMEOUT_MS, LINUX_PLATFORM
+from gitpane.system.process_program import program_name_of_process
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    ConnectionFactory = Callable[[], QDBusConnection]
+
+SECRET_SERVICE_NAME = "org.freedesktop.secrets"
+SECRET_SERVICE_PATH = "/org/freedesktop/secrets"
+SECRET_SERVICE_INTERFACE = "org.freedesktop.Secret.Service"
+SECRET_COLLECTION_INTERFACE = "org.freedesktop.Secret.Collection"
+DBUS_SERVICE_NAME = "org.freedesktop.DBus"
+DBUS_PATH = "/org/freedesktop/DBus"
+DBUS_INTERFACE = "org.freedesktop.DBus"
+PROPERTIES_INTERFACE = "org.freedesktop.DBus.Properties"
+NAME_HAS_OWNER_METHOD = "NameHasOwner"
+GET_CONNECTION_UNIX_PROCESS_ID_METHOD = "GetConnectionUnixProcessID"
+READ_ALIAS_METHOD = "ReadAlias"
+GET_PROPERTY_METHOD = "Get"
+DEFAULT_ALIAS = "default"
+LOCKED_PROPERTY = "Locked"
+# The only methods this read ever calls: each one reads, none changes the keyring or returns a secret.
+READ_ONLY_METHOD_NAME_SET = frozenset({NAME_HAS_OWNER_METHOD, GET_CONNECTION_UNIX_PROCESS_ID_METHOD, READ_ALIAS_METHOD, GET_PROPERTY_METHOD})
+# Each of the four replies carries exactly one value.
+REPLY_ARGUMENT_COUNT = 1
+REPLY_VALUE_INDEX = 0
+
+
+def read_only_call(connection: QDBusConnection, service: str, path: str, interface: str, method: str, arguments: Sequence[object], timeout_ms: int) -> QDBusMessage:
+    """Send one method call that may not start its service, wait at most ``timeout_ms`` for the reply, and return it.
+
+    D-Bus activation is refused on the message, so a Secret Service that is installed but not running is never
+    started by GitPane. A reply that does not come in time comes back as an error message.
+    """
+    message = QDBusMessage.createMethodCall(service, path, interface, method)
+    message.setArguments(list(arguments))
+    message.setAutoStartService(False)
+    return connection.call(message, QDBus.CallMode.Block, timeout_ms)
+
+
+def single_reply_value(reply: QDBusMessage) -> object:
+    """Return the one value a successful reply carries, or None for an error or a reply of another shape."""
+    if reply.type() != QDBusMessage.MessageType.ReplyMessage:
+        return None
+    values = reply.arguments()
+    if len(values) != REPLY_ARGUMENT_COUNT:
+        return None
+    return values[REPLY_VALUE_INDEX]
+
+
+def read_secret_service_answers(connection: QDBusConnection, timeout_ms: int, read_program_name: Callable[[int], str] = program_name_of_process) -> SecretServiceAnswers:
+    """Ask the four questions in order and keep the answers, stopping at the first one that decides.
+
+    No owner stops before anything else is asked. The owner's process number is asked of the bus daemon and passed to
+    ``read_program_name``; a number that cannot be read leaves the program name empty and the read goes on, since the
+    state of the collection does not depend on it. An alias that names no collection, or an empty one, stops before
+    the property read. Each answer is kept only when it has the type the question expects (a boolean, an integer, an
+    object path, a variant), and the aliased path is passed on exactly as the service wrote it.
+    """
+    owner = single_reply_value(read_only_call(connection, DBUS_SERVICE_NAME, DBUS_PATH, DBUS_INTERFACE, NAME_HAS_OWNER_METHOD, (SECRET_SERVICE_NAME,), timeout_ms))
+    if type(owner) is not bool:
+        return SecretServiceAnswers()
+    if not owner:
+        return SecretServiceAnswers(owner_present=False)
+    pid = single_reply_value(read_only_call(connection, DBUS_SERVICE_NAME, DBUS_PATH, DBUS_INTERFACE, GET_CONNECTION_UNIX_PROCESS_ID_METHOD, (SECRET_SERVICE_NAME,), timeout_ms))
+    program = read_program_name(pid) if type(pid) is int else ""
+    alias = single_reply_value(read_only_call(connection, SECRET_SERVICE_NAME, SECRET_SERVICE_PATH, SECRET_SERVICE_INTERFACE, READ_ALIAS_METHOD, (DEFAULT_ALIAS,), timeout_ms))
+    if type(alias) is not QDBusObjectPath:
+        return SecretServiceAnswers(owner_present=True, owner_program=program)
+    alias_path = alias.path()
+    if not alias_path or alias_path == NO_DEFAULT_COLLECTION_PATH:
+        return SecretServiceAnswers(owner_present=True, alias_path=alias_path, owner_program=program)
+    locked_reply = read_only_call(connection, SECRET_SERVICE_NAME, alias_path, PROPERTIES_INTERFACE, GET_PROPERTY_METHOD, (SECRET_COLLECTION_INTERFACE, LOCKED_PROPERTY), timeout_ms)
+    if locked_reply.type() == QDBusMessage.MessageType.ErrorMessage:
+        return SecretServiceAnswers(owner_present=True, alias_path=alias_path, locked_error_name=locked_reply.errorName(), owner_program=program)
+    locked = single_reply_value(locked_reply)
+    if type(locked) is not QDBusVariant:
+        return SecretServiceAnswers(owner_present=True, alias_path=alias_path, owner_program=program)
+    return SecretServiceAnswers(owner_present=True, alias_path=alias_path, locked=locked.variant(), owner_program=program)
+
+
+def read_linux_keyring_state(connect: ConnectionFactory, timeout_ms: int, read_program_name: Callable[[int], str] = program_name_of_process) -> KeyringReading:
+    """Read the state of the default collection and its owning program on the bus ``connect`` opens; a bus that cannot be reached is UNKNOWN, with no call."""
+    connection = connect()
+    if not connection.isConnected():
+        return UNKNOWN_KEYRING_READING
+    return keyring_reading(read_secret_service_answers(connection, timeout_ms, read_program_name))
+
+
+# The systems whose keyring GitPane can read without changing it. Any other system reads as UNKNOWN without opening a
+# connection: macOS and Windows keep their credentials elsewhere, and GitPane says nothing it does not know.
+KEYRING_READ_BY_PLATFORM = {
+    LINUX_PLATFORM: read_linux_keyring_state,
+}
+
+
+def read_keyring_state(platform: str, connect: ConnectionFactory, timeout_ms: int = KEYRING_READ_TIMEOUT_MS) -> KeyringReading:
+    """Read the state of the default keyring collection on ``platform``, and the program that holds it, through the bus ``connect`` opens.
+
+    A system missing from the table gives UNKNOWN and never calls ``connect``.
+    """
+    read = KEYRING_READ_BY_PLATFORM.get(platform)
+    if read is None:
+        return UNKNOWN_KEYRING_READING
+    return read(connect, timeout_ms)
+
+
+def read_session_keyring_state() -> KeyringReading:
+    """Read the state of the default keyring collection of the running session, and the program that holds it.
+
+    Blocks for up to four times the read bound when the service does not answer, so it runs only on a worker thread.
+    """
+    return read_keyring_state(sys.platform, QDBusConnection.sessionBus)

gitpane/account/keyring_state.py

@@ -0,0 +1,158 @@
+"""Classify the answers of a read-only Secret Service read, without any D-Bus.
+
+The read asks four questions in turn: whether anyone owns the Secret Service name on the bus, which process owns it,
+which object the ``default`` alias names, and whether that object is locked. The answers are classified here, so every
+case can be checked from any system. An alias that names an object absent from the bus, the case where the GNOME
+keyring cannot store anything, is told apart from an alias that names no collection at all, where the credential
+manager's library asks the desktop to create one, and both from a state GitPane could not read; any answer of an
+unexpected shape stays unknown, which gives no sentence rather than a wrong one.
+
+The program that owns the name says which keyring answers: KDE Wallet, the GNOME keyring, KeePassXC or another one. It
+only chooses the words said to the user, except for one answer already seen with the GNOME keyring, which stops a
+sign-in before anything is sent; the same answer from any other program lets the sign-in go.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class KeyringState(Enum):
+    """What a read that changes nothing can tell of the Secret Service's default collection."""
+
+    AVAILABLE = "available"
+    """The default collection is published and unlocked."""
+    LOCKED = "locked"
+    """The default collection is published but locked: the desktop asks for its password before anything is stored."""
+    UNPUBLISHED = "unpublished"
+    """The alias names an object absent from the bus, the defect of the very first session of a new system or user: nothing can be stored."""
+    NO_DEFAULT_COLLECTION = "no_default_collection"
+    """The alias names no collection: the credential manager's library asks the desktop to create one when it stores, so nothing is stopped."""
+    NO_SERVICE = "no_service"
+    """Nobody owns the Secret Service name on the bus, as on a desktop without the GNOME keyring."""
+    UNKNOWN = "unknown"
+    """No bus, no answer in time, an error or an answer of an unexpected shape, or a system without this read."""
+
+
+# What the ``default`` alias reads when no default collection is assigned.
+NO_DEFAULT_COLLECTION_PATH = "/"
+# The errors a property read on the aliased object can answer when that object is absent from the bus. It is the set on
+# which libsecret concludes that the collection does not exist: the GNOME keyring answers UnknownMethod, a QtDBus
+# service UnknownObject, and the Secret Service specification names NoSuchObject.
+UNPUBLISHED_ERROR_NAME_SET = frozenset({
+    "org.freedesktop.DBus.Error.UnknownMethod",
+    "org.freedesktop.DBus.Error.UnknownObject",
+    "org.freedesktop.Secret.Error.NoSuchObject",
+})
+
+
+@dataclass(frozen=True)
+class SecretServiceAnswers:
+    """The answers of the reads, each None when that read gave no usable answer or was not made."""
+
+    owner_present: bool | None = None
+    """Whether someone owns the Secret Service name, as the bus daemon answers it."""
+    alias_path: str | None = None
+    """The object path the ``default`` alias names, exactly as the service wrote it."""
+    locked: object = None
+    """The value of the ``Locked`` property of that object; only a boolean is a usable answer."""
+    locked_error_name: str = ""
+    """The D-Bus error name the ``Locked`` read answered, empty when it answered a value or was not made."""
+    owner_program: str = ""
+    """The name of the program that owns the Secret Service name, read in /proc; empty when it could not be read."""
+
+
+def keyring_state(answers: SecretServiceAnswers) -> KeyringState:
+    """Classify the answers of a read-only Secret Service read into the state of its default collection.
+
+    Each step decides only on an answer of the expected type: the owner on a boolean, the alias on a non-empty path
+    compared character for character with ``/``, the lock on a boolean or on one of the errors of an absent object.
+    Anything else is UNKNOWN, so GitPane never says more than the bus told it.
+    """
+    if type(answers.owner_present) is not bool:
+        return KeyringState.UNKNOWN
+    if not answers.owner_present:
+        return KeyringState.NO_SERVICE
+    if not answers.alias_path:
+        return KeyringState.UNKNOWN
+    if answers.alias_path == NO_DEFAULT_COLLECTION_PATH:
+        return KeyringState.NO_DEFAULT_COLLECTION
+    if answers.locked_error_name:
+        if answers.locked_error_name in UNPUBLISHED_ERROR_NAME_SET:
+            return KeyringState.UNPUBLISHED
+        return KeyringState.UNKNOWN
+    if type(answers.locked) is not bool:
+        return KeyringState.UNKNOWN
+    if answers.locked:
+        return KeyringState.LOCKED
+    return KeyringState.AVAILABLE
+
+
+class KeyringProvider(Enum):
+    """Which keyring answers as the Secret Service, told by the name of the program that owns the name on the bus."""
+
+    GNOME_KEYRING = "gnome_keyring"
+    """The GNOME keyring, ``gnome-keyring-daemon``."""
+    KDE_WALLET = "kde_wallet"
+    """KDE Wallet, through ``ksecretd`` or an older ``kwalletd``."""
+    KEEPASSXC = "keepassxc"
+    """KeePassXC with its Secret Service integration turned on."""
+    OTHER = "other"
+    """A program GitPane does not know; the sentences name it as read."""
+    UNREADABLE = "unreadable"
+    """The program could not be read, or nobody owns the name; the sentences name no program."""
+
+
+# The keyring each known program name stands for. The key is the program name exactly as /proc gives it, compared as
+# is: the base name of the executable, or the command name of a process whose executable link is refused.
+KEYRING_PROVIDER_BY_PROGRAM = {
+    "ksecretd": KeyringProvider.KDE_WALLET,
+    "kwalletd6": KeyringProvider.KDE_WALLET,
+    "kwalletd5": KeyringProvider.KDE_WALLET,
+    "gnome-keyring-daemon": KeyringProvider.GNOME_KEYRING,
+    # The daemon's name as /proc/<pid>/comm gives it, cut to 15 characters: read when the kernel refuses its executable
+    # link, which happens where the daemon is started with a file capability. Debian 13 installs it without any, so its
+    # link reads and this name is not needed there; the refusal itself was seen for kwin_wayland and its cap_sys_nice.
+    "gnome-keyring-d": KeyringProvider.GNOME_KEYRING,
+    "keepassxc": KeyringProvider.KEEPASSXC,
+}
+
+
+def keyring_provider(program: str) -> KeyringProvider:
+    """Return the keyring a program name stands for: UNREADABLE for an empty name, OTHER for a name the table does not know."""
+    if not program:
+        return KeyringProvider.UNREADABLE
+    return KEYRING_PROVIDER_BY_PROGRAM.get(program, KeyringProvider.OTHER)
+
+
+@dataclass(frozen=True)
+class KeyringReading:
+    """What a read of the Secret Service tells: the state of its default collection and which program answered."""
+
+    state: KeyringState
+    """The state of the default collection."""
+    provider: KeyringProvider
+    """The keyring the owning program stands for."""
+    program: str
+    """The name of the owning program as read, empty when it could not be read."""
+
+
+def keyring_reading(answers: SecretServiceAnswers) -> KeyringReading:
+    """Classify the answers into the state of the default collection and the keyring that answered."""
+    return KeyringReading(keyring_state(answers), keyring_provider(answers.owner_program), answers.owner_program)
+
+
+# What a read that could not be made, or failed, tells: nothing, so no sentence and no stop.
+UNKNOWN_KEYRING_READING = KeyringReading(KeyringState.UNKNOWN, KeyringProvider.UNREADABLE, "")
+
+# The readings that stop a sign-in before anything is sent. Only an answer already seen with this owner stops it: the
+# GNOME keyring's unpublished collection of the very first session, where nothing can be stored. The same answer from
+# another program, or from a program that could not be read, lets the exchange go, so the credential manager's own
+# output tells what happened instead of a guess.
+SIGN_IN_STOPPING_READING_SET = frozenset({(KeyringProvider.GNOME_KEYRING, KeyringState.UNPUBLISHED)})
+
+
+def keyring_stops_sign_in(reading: KeyringReading) -> bool:
+    """Tell whether this reading stops a sign-in before anything is sent to the credential manager."""
+    return (reading.provider, reading.state) in SIGN_IN_STOPPING_READING_SET

gitpane/account/ssh.py

@@ -0,0 +1,312 @@
+"""Give Git network commands a verified OpenSSH client with a private prompt channel."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from gitpane.account.ssh_prompt import SshPromptBridge
+from gitpane.config import GIT_OPEN_TIMEOUT_MS, SYSTEM_ROOT_ENVIRONMENT_NAME, WINDOWS_PLATFORM
+from gitpane.process.process_runner import LOCAL_WRITE_PROFILE, NETWORK_PROFILE, ProcessRequest, ProcessResult, ProcessRunner, ProcessStatus
+from gitpane.system.network_folder import network_directory
+from gitpane.tool.git_executable import GIT_BINARY_DIR_BASENAME, GIT_SHELL_DIR_BASENAME, PATH_ENVIRONMENT_NAME, git_root_dirs
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from gitpane.history.repository_value import RepositoryContext
+    from gitpane.operation.repository_operation import RepositoryOperationService
+    from gitpane.preference.preference_store import PreferenceStore
+
+
+SSH_UNAVAILABLE_TEXT = "SSH client is unavailable. Choose an executable in Settings and verify it."
+# OpenSSH option that turns every question (host key, passphrase, password) into a failure: a background read must never show one.
+SSH_BATCH_MODE_OPTION = "-o BatchMode=yes"
+
+
+@dataclass(frozen=True)
+class SshConfiguration:
+    """Keep an exact executable and optional Windows utility directory per launch."""
+
+    ssh_filename: str = ""
+    utility_dir: str = ""
+    variant: str = "ssh"
+
+    def validate(self, *, windows: bool | None = None, optional: bool = False) -> None:
+        """Reject shell expressions and unavailable tools before launching native SSH."""
+        windows = os.name == "nt" if windows is None else windows
+        if not self.ssh_filename:
+            if not optional:
+                raise ValueError(SSH_UNAVAILABLE_TEXT)
+        elif not os.path.isabs(self.ssh_filename) or not os.path.isfile(self.ssh_filename):
+            raise ValueError("SSH executable was not found. Choose an existing absolute filename in Settings.")
+        elif not os.access(self.ssh_filename, os.X_OK) or (windows and os.path.splitext(self.ssh_filename)[1].lower() != ".exe"):
+            raise ValueError("SSH client is not an executable file. Choose an OpenSSH executable in Settings.")
+        if self.variant != "ssh":
+            raise ValueError("Only verified OpenSSH clients are supported.")
+        if windows and self.utility_dir and (not os.path.isabs(self.utility_dir) or not os.path.isdir(self.utility_dir)):
+            raise ValueError("Git utilities directory (Windows) must be an existing absolute directory.")
+
+
+SSH_WINDOWS_BASENAME = "ssh.exe"
+SSH_BASENAME = "ssh"
+# Where Windows installs its own OpenSSH client, below the Windows folder.
+WINDOWS_OPENSSH_DIR_PARTS = ("System32", "OpenSSH")
+GIT_FOR_WINDOWS_SOURCE_TEXT = "Git for Windows"
+WINDOWS_OPENSSH_SOURCE_TEXT = "Windows OpenSSH"
+PATH_SOURCE_TEXT = "PATH"
+SAVED_SOURCE_TEXT = "Application settings"
+DETECTED_SOURCE_PREFIX = "Detected: "
+NO_SSH_SOURCE_TEXT = "No SSH client found"
+
+
+@dataclass(frozen=True)
+class SshDetection:
+    """Name the OpenSSH client found on this machine and where it was found; both are empty when none was found."""
+
+    filename: str = ""
+    source: str = ""
+
+
+def absolute_executable_available(filename: str) -> bool:
+    """Tell whether a candidate is an existing executable file given by an absolute name.
+
+    A relative name is refused because it would depend on the folder GitPane happens to run in.
+    """
+    return os.path.isabs(filename) and os.path.isfile(filename) and os.access(filename, os.X_OK)
+
+
+def no_ssh_detection() -> SshDetection:
+    """Report that no client was found, for a service that is given no way to search."""
+    return SshDetection()
+
+
+def detect_ssh_client(git_filename: str, platform: str, environment_by_name: Mapping[str, str],
+                      available: Callable[[str], bool] = absolute_executable_available, network: Callable[[str], bool] = network_directory) -> SshDetection:
+    """Find the OpenSSH client used while none is saved: the one of the Git in use, then Windows OpenSSH, then the PATH.
+
+    On Windows, the ssh.exe of Git for Windows sits in usr/bin below the installation root, one or two folders above
+    git.exe. Linux and macOS only look at the PATH. Nothing is started and nothing is saved.
+
+    The search runs on the window's thread the first time an operation needs the client, so on Windows a PATH entry on
+    a network share is skipped: a disconnected share would freeze the window. A client kept on a share can still be
+    chosen in Settings.
+    """
+    candidates: list[tuple[str, str]] = []
+    windows = platform == WINDOWS_PLATFORM
+    if windows:
+        for root_dir in git_root_dirs(git_filename):
+            candidates.append((os.path.join(root_dir, GIT_SHELL_DIR_BASENAME, GIT_BINARY_DIR_BASENAME, SSH_WINDOWS_BASENAME), GIT_FOR_WINDOWS_SOURCE_TEXT))
+        system_root_dir = environment_by_name.get(SYSTEM_ROOT_ENVIRONMENT_NAME, "")
+        if system_root_dir:
+            candidates.append((os.path.join(system_root_dir, *WINDOWS_OPENSSH_DIR_PARTS, SSH_WINDOWS_BASENAME), WINDOWS_OPENSSH_SOURCE_TEXT))
+    # The PATH is read here instead of with shutil.which, which on Windows looks in the current folder first: a
+    # client dropped there, or in a relative PATH entry, must never be launched for every network operation.
+    for path_dir in environment_by_name.get(PATH_ENVIRONMENT_NAME, "").split(os.pathsep):
+        if os.path.isabs(path_dir) and not (windows and network(path_dir)):
+            candidates.append((os.path.join(path_dir, SSH_WINDOWS_BASENAME if windows else SSH_BASENAME), PATH_SOURCE_TEXT))
+    for filename, source in candidates:
+        if available(filename):
+            return SshDetection(os.path.abspath(filename), source)
+    return SshDetection()
+
+
+class SshClientFinder:
+    """Find the OpenSSH client used while none is saved, once per Git executable for this launch.
+
+    The search only looks at files, but operations ask for it every time they start; keeping the answer per Git
+    executable means a Git changed in Settings is searched again. The answer is never saved in the preferences.
+    """
+
+    def __init__(self, current_git_filename: Callable[[], str], platform: str, environment_by_name: Mapping[str, str], *, log_line: Callable[[str], None]) -> None:
+        """Take the Git in use, read at each search, and the line writer of the --log file, which ignores lines when there is none."""
+        self.current_git_filename = current_git_filename
+        self.platform = platform
+        self.environment_by_name = environment_by_name
+        self.log_line = log_line
+        # The OpenSSH client found on this machine, per Git executable, used while none is saved.
+        self.ssh_detection_by_git_filename: dict[str, SshDetection] = {}
+
+    def find(self) -> SshDetection:
+        """Answer the client of the Git in use, searching the machine only the first time this Git asks."""
+        git_filename = self.current_git_filename()
+        detection = self.ssh_detection_by_git_filename.get(git_filename)
+        if detection is not None:
+            return detection
+        detection = detect_ssh_client(git_filename, self.platform, self.environment_by_name)
+        self.ssh_detection_by_git_filename[git_filename] = detection
+        self.log_line("SSH client detected: " + (detection.filename + " (" + detection.source + ")" if detection.filename else "none"))
+        return detection
+
+
+def effective_source(saved: SshConfiguration, detection: SshDetection) -> str:
+    """Say where the client used by operations comes from: the saved setting, a detection, or nowhere."""
+    if saved.ssh_filename:
+        return SAVED_SOURCE_TEXT
+    if detection.filename:
+        return DETECTED_SOURCE_PREFIX + detection.source
+    return NO_SSH_SOURCE_TEXT
+
+
+@dataclass(frozen=True)
+class SshVerification:
+    """Report the captured candidate and native version without publishing a draft."""
+
+    configuration: SshConfiguration
+    version: str = ""
+    cause: str = ""
+
+    @property
+    def succeeded(self) -> bool:
+        """Require an identified OpenSSH version before a candidate can be saved."""
+        return bool(self.version) and not self.cause
+
+
+class SshService(QObject):
+    """Verify tools asynchronously and provide isolated network environment values."""
+
+    question_requested = Signal(object)
+    question_closed = Signal(str)
+
+    def __init__(self, preference: PreferenceStore, runner: ProcessRunner, parent: QObject | None = None, *, repository_operation: RepositoryOperationService | None = None,
+                 detect_client: Callable[[], SshDetection] = no_ssh_detection) -> None:
+        """Reuse the application process owner so verification drains during shutdown.
+
+        detect_client names the client to use while none is saved; the application gives one that searches the machine.
+        """
+        # Retain the runner in Python without making it an implicit Qt owner: releasing
+        # its last reference during deferred service deletion must not delete this child again.
+        super().__init__(parent)
+        self.preference = preference
+        self.runner = runner
+        self.repository_operation = repository_operation
+        self.detect_client = detect_client
+        self.bridge_by_id: dict[str, SshPromptBridge] = {}
+        self.verification_by_id: dict[str, tuple[SshConfiguration, Callable[[SshVerification], None], bytearray]] = {}
+        runner.stdout_chunk.connect(self._stdout)
+        runner.finished.connect(self._finished)
+        runner.stop_requested.connect(self._stopping)
+
+    def prompt(self, request: ProcessRequest, *, context: RepositoryContext | None = None, generation: int = 0,
+               is_current: Callable[[], bool] | None = None) -> ProcessRequest:
+        """Attach a private prompt owner to a captured network command before it is started."""
+        if request.profile != NETWORK_PROFILE or not request.operation_id or request.request_id in self.bridge_by_id:
+            raise ValueError("SSH prompting requires a unique supervised network operation")
+        if context is not None:
+            owner = self.repository_operation.active_by_id.get(request.operation_id) if self.repository_operation is not None else None
+            if owner is None or owner.context != context or owner.generation != generation or owner.session_id != request.session_id:
+                raise ValueError("SSH operation does not own the captured repository session")
+        try:
+            bridge = SshPromptBridge(request, self.runner, is_current or (lambda: True), self)
+        except OSError as error:
+            raise OSError("SSH prompt helper could not be prepared. Check temporary-directory permissions or repair the GitPane installation.") from error
+        self.bridge_by_id[request.request_id] = bridge
+        bridge.question_requested.connect(self.question_requested)
+        bridge.dismissed.connect(lambda: self.question_closed.emit(request.operation_id))
+        environment_by_name = dict(request.environment_by_name)
+        environment_by_name.update(bridge.environment())
+        return replace(request, environment_by_name=environment_by_name)
+
+    def close(self) -> None:
+        """Refuse questions while retaining each bridge until its process has drained."""
+        for request_id, bridge in tuple(self.bridge_by_id.items()):
+            bridge.refuse()
+            if request_id in self.runner.active_by_id or any(request.request_id == request_id for request in self.runner.pending_requests):
+                self.runner.cancel(request_id)
+            else:
+                self.bridge_by_id.pop(request_id, None)
+                bridge.close()
+
+    def _stopping(self, request: ProcessRequest, cause: str) -> None:
+        """Dismiss pending questions when their captured command begins stopping."""
+        bridge = self.bridge_by_id.get(request.request_id)
+        if bridge is not None:
+            bridge.refuse()
+
+    def saved_configuration(self) -> SshConfiguration:
+        """Read only accepted preferences: what the Settings form shows and what its Save may write back."""
+        self.preference.refresh()
+        return SshConfiguration(str(self.preference.value_by_key["ssh_filename"]), str(self.preference.value_by_key["git_utility_dir"]))
+
+    def configuration(self) -> SshConfiguration:
+        """Give the tools a new operation captures: the saved client, or the detected one while none is saved.
+
+        The detected client is never written to the preferences, so a later installation is found again.
+        """
+        saved = self.saved_configuration()
+        if saved.ssh_filename:
+            return saved
+        return replace(saved, ssh_filename=self.detection().filename)
+
+    def detection(self) -> SshDetection:
+        """Report the client found on this machine, whether or not one is saved."""
+        return self.detect_client()
+
+    def verify(self, configuration: SshConfiguration, complete: Callable[[SshVerification], None]) -> str:
+        """Identify the selected executable with a bounded native version request."""
+        request_id = uuid.uuid4().hex
+        try:
+            configuration.validate()
+        except ValueError as error:
+            QTimer.singleShot(0, self, lambda cause=str(error): complete(SshVerification(configuration, cause=cause)))
+            return request_id
+        self.verification_by_id[request_id] = (configuration, complete, bytearray())
+        self.runner.start(ProcessRequest(request_id, configuration.ssh_filename, ["-V"], os.path.dirname(configuration.ssh_filename), GIT_OPEN_TIMEOUT_MS,
+                                         operation="Verify SSH client", profile=LOCAL_WRITE_PROFILE, operation_id=request_id))
+        return request_id
+
+    def process_environment(self, configuration: SshConfiguration | None = None, *, parent_path: str | None = None, windows: bool | None = None) -> dict[str, str]:
+        """Preserve native Host, identity and agent settings without editing the parent PATH."""
+        configuration = configuration or self.configuration()
+        configuration.validate(windows=windows)
+        environment_by_name = {"GIT_SSH": configuration.ssh_filename, "GIT_SSH_VARIANT": configuration.variant}
+        windows = os.name == "nt" if windows is None else windows
+        if windows and configuration.utility_dir:
+            environment_by_name[PATH_ENVIRONMENT_NAME] = os.pathsep.join((configuration.utility_dir, os.environ.get(PATH_ENVIRONMENT_NAME, "") if parent_path is None else parent_path))
+        return environment_by_name
+
+    def command_configuration(self, configuration: SshConfiguration | None = None, *, batch_mode: bool = False) -> tuple[list[str], dict[str, str]]:
+        """Keep a repository's core.sshCommand from silently replacing the selected executable.
+
+        With ``batch_mode`` OpenSSH never asks anything: an unknown host key or a key protected by a passphrase makes
+        the command fail instead. Work the user did not start explicitly, such as reading branches while a URL is typed,
+        uses it.
+        """
+        configuration = configuration or self.configuration()
+        environment_by_name = self.process_environment(configuration)
+        # Git's core.sshCommand precedes GIT_SSH. Quote only the verified filename, never user-supplied command text.
+        ssh_command = shlex.quote(configuration.ssh_filename.replace("\\", "/") if os.name == "nt" else configuration.ssh_filename)
+        if batch_mode:
+            ssh_command += " " + SSH_BATCH_MODE_OPTION
+        arguments = ["-c", "core.sshCommand=" + ssh_command]
+        return arguments, environment_by_name
+
+    def _stdout(self, request: ProcessRequest, data: bytes) -> None:
+        """Collect version output only for the matching executable verification."""
+        pending = self.verification_by_id.get(request.request_id)
+        if pending is not None:
+            _, _, output = pending
+            output.extend(data)
+
+    def _finished(self, result: ProcessResult) -> None:
+        """Release drained prompt resources and publish the captured tool verification."""
+        bridge = self.bridge_by_id.pop(result.request.request_id, None)
+        if bridge is not None:
+            bridge.close()
+        pending = self.verification_by_id.pop(result.request.request_id, None)
+        if pending is None:
+            return
+        configuration, complete, output = pending
+        version = (bytes(output) + result.stderr).decode("utf-8", "replace").strip()
+        if result.status != ProcessStatus.SUCCESS:
+            complete(SshVerification(configuration, cause=result.cause or "SSH verification failed. Choose another executable in Settings."))
+        elif not version.startswith("OpenSSH_"):
+            complete(SshVerification(configuration, cause="This executable did not identify itself as OpenSSH. Choose an OpenSSH client in Settings."))
+        else:
+            complete(SshVerification(configuration, version=version))