gitpane 1.0.0__py3-none-any.whl

gitpane/account/authentication_worker.py

@@ -0,0 +1,836 @@
+"""Perform credential exchanges in an isolated child owned by the process supervisor."""
+
+from __future__ import annotations
+
+import base64
+import http.client
+import json
+import os
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from dataclasses import asdict
+from typing import TYPE_CHECKING
+from urllib.parse import quote, urlsplit, urlunsplit
+
+from gitpane.account.authentication import (
+    ACCOUNT_NAMESPACE_PREFIX,
+    BITBUCKET_OAUTH_GIT_USERNAME,
+    BROWSER_AUTH_MODE_BY_SETTING,
+    BROWSER_GIT_USERNAME_SET,
+    BROWSER_SIGN_IN_UNAVAILABLE_TEXT,
+    BROWSER_TIMEOUT_TEXT,
+    CHECK_COPY_ERASED_KEY,
+    CHECK_FAILED_TEXT,
+    CHECK_NAMESPACE_SUFFIX,
+    GCM_DISABLED_VALUE,
+    GENERIC_PROVIDER,
+    GIT_EXEC_PATH_KEY,
+    GIT_MISSING_TEXT,
+    GITHUB_PROVIDER,
+    GITLAB_OAUTH_GIT_USERNAME,
+    GITLAB_PROVIDER,
+    GITPANE_REFUSAL_KEY,
+    MANAGED_CREDENTIAL_PROVIDER,
+    MANAGED_CREDENTIAL_STORE,
+    PROVIDER_HOST_BY_NAME,
+    SECRET_LOOKUP_FIELDS,
+    TOKEN_PAGE_PATH_BY_PROVIDER,
+    AccountSelection,
+    AuthenticationAction,
+    SecretPresence,
+    account_namespace,
+    credential_configuration,
+    endpoint_origin,
+    generic_account,
+    isolated_http_arguments,
+    token_page_url,
+    validate_text,
+)
+from gitpane.account.credential_manager import GIT_EXEC_PATH_ENVIRONMENT_NAME
+from gitpane.config import (
+    APPLICATION_NAME,
+    AUTHENTICATION_TIMEOUT_MS,
+    BROWSER_SIGN_IN_TIMEOUT_MS,
+    GCM_ENVIRONMENT_NAME_BY_SETTING,
+    GCM_ENVIRONMENT_PREFIX,
+    GIT_LOCAL_ENVIRONMENT_NAMES,
+    GIT_READ_TIMEOUT_MS,
+    MILLISECONDS_PER_SECOND,
+    PROCESS_CHUNK_BYTES,
+    PROCESS_TREE_STOP_TIMEOUT_MS,
+    READ_SIZE_SENTINEL_BYTES,
+    SERVER_PROBE_TIMEOUT_MS,
+    TRACE_ENVIRONMENT_PREFIXES,
+    TRACE_UNIT_LIMIT_BYTES,
+)
+from gitpane.operation.diagnostic import SensitiveTextFilter
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.process.process_group import JobBreakawayRefusedError, ReleasedChildJob
+from gitpane.transport.git_refusal import RefusalKind, credential_store_unavailable, git_output_lines, refusal_kind
+
+if TYPE_CHECKING:
+    from email.message import Message
+
+# A rejection and a removal both erase the selected account's secret, and nothing else.
+ERASE_ACTION_SET = frozenset({AuthenticationAction.REJECT, AuthenticationAction.REMOVE})
+BROWSER_NAMESPACE = "gitpane-browser"
+# Every Git Credential Manager setting is a Git configuration key under this section.
+CREDENTIAL_SETTING_PREFIX = "credential."
+# A browser sign-in stores nothing itself: only the token whose identity was verified afterwards is stored.
+BROWSER_CREDENTIAL_STORE = "none"
+# The process group ID that asks for a new group led by the started process itself.
+NEW_PROCESS_GROUP_ID = 0
+# Names of the variables that could make the account test ask anyone else for a secret, or trace what it sends.
+CHECK_REMOVED_ENVIRONMENT_NAME_SET = frozenset({"GIT_ASKPASS", "SSH_ASKPASS", "GIT_CURL_VERBOSE", "GIT_SSL_KEYLOGFILE"})
+# The account test sets these itself: its own helper settings, and where repository discovery must stop.
+CHECK_KEPT_ENVIRONMENT_NAME_SET = frozenset({"GIT_CONFIG_COUNT", "GIT_CEILING_DIRECTORIES"})
+CHECK_TIMEOUT_CAUSE = "Testing the sign-in with {url} did not finish within {seconds} seconds. Nothing was saved."
+WINDOWS_DEFAULT_ROOT_DIR = "C:\\Windows"
+USER_AGENT = APPLICATION_NAME
+# A server is recognised from its host name only when that name has at least this many labels (github.corp.example),
+# so a bare github.example tells nothing.
+PROVIDER_HOST_MINIMUM_LABEL_COUNT = 3
+FIRST_LABEL_INDEX = 0
+# Headers by which a server tells which software it runs, read on its answer to one HEAD request.
+GITHUB_REQUEST_ID_HEADER = "X-GitHub-Request-Id"
+GITLAB_FEATURE_CATEGORY_HEADER = "X-Gitlab-Feature-Category"
+AUTHENTICATE_HEADER = "WWW-Authenticate"
+GITLAB_REALM_TEXT = 'realm="gitlab"'
+# Git Credential Manager's setting that names the OAuth application of a GitLab server: without one, a self-hosted
+# GitLab cannot offer browser sign-in.
+GITLAB_OAUTH_CLIENT_KEY = "credential.gitLabDevClientId"
+
+
+class BrowserTimeoutError(Exception):
+    """The browser did not answer a browser sign-in within the wait; its helper was stopped before anything was stored."""
+
+
+class AccountMismatchError(ValueError):
+    """GitPane refused the account a sign-in returned, because it is not the account asked for; the message is GitPane's own sentence."""
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Keep authentication headers on the explicitly selected API host."""
+
+    def redirect_request(self, request: urllib.request.Request, response: object, code: int, message: str, headers: object, new_url: str) -> None:
+        """Refuse API redirects so credentials cannot reach an unapproved destination."""
+        return
+
+
+def helper_environment(data_by_key: dict[str, object], namespace: str, *, browser: bool, trace: bool) -> dict[str, str]:
+    """Return the environment that makes the helper work in one namespace with this exchange's own settings only.
+
+    Inherited helper settings, askpass programs and traces are dropped. GitPane's own settings are given both as Git
+    configuration and as Git Credential Manager's variables, which win over any configuration of the user, so the
+    user's settings can never choose another store, namespace, provider or prompt mode for GitPane's accounts; the
+    settings GitPane does not depend on stay the user's. ``trace`` turns on the helper's diagnostics, which never
+    include secrets; without it nothing is traced at all. The helper started directly gets the folder of
+    the programs of the Git it was found for, so it finds Git even when Git is not on the PATH; an inherited folder,
+    which may belong to another Git, is never passed on.
+    """
+    environment_by_name = dict(os.environ)
+    for name in tuple(environment_by_name):
+        if name.startswith((GCM_ENVIRONMENT_PREFIX, *TRACE_ENVIRONMENT_PREFIXES, "GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_")) or name in {"GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT", "GIT_ASKPASS", "SSH_ASKPASS"}:
+            environment_by_name.pop(name)
+    environment_by_name.pop(GIT_EXEC_PATH_ENVIRONMENT_NAME, None)
+    exec_path = str(data_by_key.get(GIT_EXEC_PATH_KEY) or "")
+    if exec_path:
+        environment_by_name[GIT_EXEC_PATH_ENVIRONMENT_NAME] = exec_path
+    origin = str(data_by_key["origin"])
+    provider = str(data_by_key["provider"]).lower() if browser else MANAGED_CREDENTIAL_PROVIDER
+    store = BROWSER_CREDENTIAL_STORE if browser else MANAGED_CREDENTIAL_STORE
+    namespace = namespace or BROWSER_NAMESPACE
+    setting_pairs = [("credential.helper", ""), ("credential.provider", provider), (f"credential.{origin}.provider", provider),
+                     ("credential.interactive", "true" if browser else GCM_DISABLED_VALUE), ("credential.credentialStore", store), (f"credential.{origin}.credentialStore", store),
+                     ("credential.namespace", namespace), (f"credential.{origin}.namespace", namespace),
+                     ("credential.trace", "true" if trace else "false"), ("credential.traceSecrets", GCM_DISABLED_VALUE), ("credential.useHttpPath", "false")]
+    for setting, mode in BROWSER_AUTH_MODE_BY_SETTING.items():
+        setting_pairs.append((CREDENTIAL_SETTING_PREFIX + setting, mode))
+    environment_by_name["GIT_CONFIG_COUNT"] = str(len(setting_pairs))
+    for index, (key, value) in enumerate(setting_pairs):
+        environment_by_name[f"GIT_CONFIG_KEY_{index}"] = key
+        environment_by_name[f"GIT_CONFIG_VALUE_{index}"] = value
+    if trace:
+        environment_by_name["GCM_TRACE"] = "1"
+    # The same settings again as Git Credential Manager's own variables, which it reads before any Git configuration:
+    # a setting the user scoped to this address would otherwise win over the unscoped one above. Settings scoped to the
+    # address here, and settings outside the table, give no variable.
+    for key, value in setting_pairs:
+        setting = key.removeprefix(CREDENTIAL_SETTING_PREFIX)
+        if setting in GCM_ENVIRONMENT_NAME_BY_SETTING:
+            environment_by_name[GCM_ENVIRONMENT_NAME_BY_SETTING[setting]] = value
+    return environment_by_name
+
+
+def credential_request_content(credential_by_key: dict[str, str]) -> bytes:
+    """Write the credential request the helper reads on its standard input: one key=value line each, then an empty line."""
+    content = ""
+    for key, value in credential_by_key.items():
+        validate_text(value, allow_empty=True)
+        content += key + "=" + value + "\n"
+    content += "\n"
+    return content.encode("utf-8")
+
+
+def helper_response(data_by_key: dict[str, object], credential_by_key: dict[str, str], return_code: int | None, stdout: bytes, stderr: bytes) -> dict[str, str]:
+    """Read the helper's answer, writing its diagnostics without any secret, and refuse the answer of a failed helper."""
+    response_by_key: dict[str, str] = {}
+    for line in stdout.decode("utf-8", errors="strict").splitlines():
+        key, separator, value = line.partition("=")
+        if separator:
+            response_by_key[key] = value
+    filter = SensitiveTextFilter({"token": str(data_by_key.get("token", "")), "password": response_by_key.get("password", credential_by_key.get("password", ""))})
+    diagnostic = filter.redact(stderr.decode("utf-8", errors="replace"))
+    if diagnostic:
+        print(diagnostic, file=sys.stderr, flush=True)
+    if return_code != 0:
+        raise ValueError(diagnostic or "The credential helper failed without an error message")
+    return response_by_key
+
+
+def helper_exchange(data_by_key: dict[str, object], action: str, credential_by_key: dict[str, str], *, namespace: str = "") -> dict[str, str]:
+    """Call only the captured helper with private stdin and command-scoped configuration."""
+    environment_by_name = helper_environment(data_by_key, namespace, browser=False, trace=True)
+    result = subprocess.run([*data_by_key["helper_commands"], action], input=credential_request_content(credential_by_key), capture_output=True, env=environment_by_name,
+                            timeout=AUTHENTICATION_TIMEOUT_MS / MILLISECONDS_PER_SECOND, check=False)
+    return helper_response(data_by_key, credential_by_key, result.returncode, result.stdout, result.stderr)
+
+
+def lookup_environment(data_by_key: dict[str, object], namespace: str) -> dict[str, str]:
+    """Return the environment of a check of one stored secret: the account's own namespace, no prompt, no trace and no network.
+
+    Nothing is traced, prompts are off both through Git's setting and through Git Credential Manager's own variable, and
+    Git is told it may not ask on the terminal either.
+    """
+    environment_by_name = helper_environment(data_by_key, namespace, browser=False, trace=False)
+    environment_by_name[GCM_ENVIRONMENT_NAME_BY_SETTING["interactive"]] = GCM_DISABLED_VALUE
+    # Without this, Git Credential Manager asks the server whether it accepts integrated Windows authentication as soon
+    # as the secret is missing: a network request this check must never make.
+    environment_by_name[GCM_ENVIRONMENT_NAME_BY_SETTING["allowWindowsAuth"]] = GCM_DISABLED_VALUE
+    environment_by_name["GIT_TERMINAL_PROMPT"] = "0"
+    return environment_by_name
+
+
+def lookup_timeout_ms(data_by_key: dict[str, object]) -> int:
+    """Return how long the whole check of the stored secrets may take, refusing anything but a positive number of milliseconds."""
+    value = data_by_key.get("lookup_timeout_ms")
+    if type(value) is not int or value <= 0:
+        raise ValueError("The secret check time limit must be a positive number of milliseconds")
+    return value
+
+
+def lookup_account(value: object) -> dict[str, str]:
+    """Read one account of a check of the stored secrets, refusing anything but the expected nonsecret text fields.
+
+    The namespace must be one of GitPane's own, so the check can never be pointed at another program's secrets.
+    """
+    if not isinstance(value, dict) or set(value) != set(SECRET_LOOKUP_FIELDS):
+        raise ValueError("The secret check received an invalid account")
+    account_by_key = {}
+    for name in SECRET_LOOKUP_FIELDS:
+        account_by_key[name] = validate_text(value[name])
+    if not account_by_key["namespace"].startswith(ACCOUNT_NAMESPACE_PREFIX):
+        raise ValueError("The secret check received a namespace that is not GitPane's")
+    return account_by_key
+
+
+def lookup_status(git_username: str, return_code: int | None, stdout: bytes, stderr: bytes) -> SecretPresence:
+    """Classify the helper's answer to the check of one stored secret: present, missing or unknown.
+
+    Only the secret of this account's own Git username counts as present. An answer without any secret, or Git
+    Credential Manager saying it may not prompt (which it only needs when nothing is stored), means the secret is gone.
+    Any other failure tells nothing. A credential store that cannot be reached (no desktop session, no session bus, a
+    locked keyring or a cancelled unlock) says nothing about the secret either, whatever else the message holds; Git
+    Credential Manager wraps its messages at about 80 columns, so they are read with their lines merged. The message
+    itself is written to the diagnostics as Git Credential Manager wrote it. The secret is never kept nor written anywhere.
+    """
+    response_by_key: dict[str, str] = {}
+    for line in stdout.decode("utf-8", errors="replace").splitlines():
+        key, separator, value = line.partition("=")
+        if separator:
+            response_by_key[key] = value
+    password = response_by_key.pop("password", "")
+    diagnostic = SensitiveTextFilter({"password": password}).redact(stderr.decode("utf-8", errors="replace")).strip()
+    if diagnostic:
+        print(diagnostic, file=sys.stderr, flush=True)
+    if return_code != 0:
+        merged = " ".join(diagnostic.split())
+        if credential_store_unavailable(merged):
+            return SecretPresence.UNKNOWN
+        return SecretPresence.MISSING if refusal_kind(merged) is RefusalKind.CREDENTIALS_MISSING else SecretPresence.UNKNOWN
+    if not password:
+        return SecretPresence.MISSING
+    if response_by_key.get("username") != git_username:
+        return SecretPresence.UNKNOWN
+    return SecretPresence.PRESENT
+
+
+def lookup_secret(data_by_key: dict[str, object], account_by_key: dict[str, str], timeout_ms: int) -> SecretPresence:
+    """Ask the captured helper, with ``get`` only, whether this account's secret is still stored, within ``timeout_ms``.
+
+    ``account_by_key`` holds the fields of ``lookup_account``. Nothing is ever stored or erased. A helper that cannot
+    start, or does not answer in time, gives an unknown answer; one that runs too long is stopped with every process it started.
+    """
+    parsed = urlsplit(account_by_key["origin"])
+    credential_by_key = {"protocol": parsed.scheme, "host": parsed.netloc, "username": account_by_key["git_username"]}
+    request_by_key = {"origin": account_by_key["origin"], "provider": MANAGED_CREDENTIAL_PROVIDER, GIT_EXEC_PATH_KEY: data_by_key.get(GIT_EXEC_PATH_KEY, "")}
+    environment_by_name = lookup_environment(request_by_key, account_by_key["namespace"])
+    try:
+        process = subprocess.Popen([*data_by_key["helper_commands"], "get"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=environment_by_name,
+                                   process_group=own_process_group())
+    except OSError as error:
+        print("The credential helper could not start: " + str(error), file=sys.stderr, flush=True)
+        return SecretPresence.UNKNOWN
+    try:
+        stdout, stderr = process.communicate(credential_request_content(credential_by_key), timeout=timeout_ms / MILLISECONDS_PER_SECOND)
+    except subprocess.TimeoutExpired:
+        stop_process_tree(process)
+        try:
+            process.communicate(timeout=PROCESS_TREE_STOP_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+        except subprocess.TimeoutExpired:
+            pass
+        return SecretPresence.UNKNOWN
+    return lookup_status(account_by_key["git_username"], process.returncode, stdout, stderr)
+
+
+def run_lookup(data_by_key: dict[str, object]) -> dict[str, object]:
+    """Check every requested account's stored secret, one after the other, within one time limit for them all.
+
+    Only the namespaces are published, sorted into present, missing and unknown; accounts not reached before the time
+    limit are unknown. Each classification is also written to the diagnostics, by account label and address.
+    """
+    deadline = time.monotonic() + lookup_timeout_ms(data_by_key) / MILLISECONDS_PER_SECOND
+    namespaces_by_presence: dict[SecretPresence, list[str]] = {}
+    for presence in SecretPresence:
+        namespaces_by_presence[presence] = []
+    accounts = []
+    for value in data_by_key["accounts"]:
+        accounts.append(lookup_account(value))
+    for account_by_key in accounts:
+        remaining_ms = int((deadline - time.monotonic()) * MILLISECONDS_PER_SECOND)
+        presence = lookup_secret(data_by_key, account_by_key, remaining_ms) if remaining_ms > 0 else SecretPresence.UNKNOWN
+        print("Stored secret of " + account_by_key["label"] + " (" + urlsplit(account_by_key["origin"]).netloc + "): " + presence.value, file=sys.stderr, flush=True)
+        namespaces_by_presence[presence].append(account_by_key["namespace"])
+    result_by_key: dict[str, object] = {"status": OperationStatus.SUCCESS.value}
+    for presence, namespaces in namespaces_by_presence.items():
+        result_by_key[presence.value] = namespaces
+    return result_by_key
+
+
+def browser_timeout_ms(data_by_key: dict[str, object]) -> int:
+    """Return how long the browser may take to answer, refusing anything but a positive number of milliseconds."""
+    value = data_by_key.get("browser_timeout_ms", BROWSER_SIGN_IN_TIMEOUT_MS)
+    if type(value) is not int or value <= 0:
+        raise ValueError("The browser wait must be a positive number of milliseconds")
+    return value
+
+
+def browser_helper_exchange(data_by_key: dict[str, object], credential_by_key: dict[str, str]) -> dict[str, str]:
+    """Ask the helper for a browser sign-in and wait for the browser's answer at most ``browser_timeout_ms``.
+
+    Nothing is stored by this step: only a token whose identity is checked afterwards is stored, so stopping the helper
+    at the end of the wait leaves nothing behind. The helper is stopped at the end of the wait, and with this worker
+    when the worker is stopped or GitPane dies, by the guard of the system: a private job on Windows, the kernel's
+    parent-death signal on Linux, a small watcher that is the helper's parent on macOS and hands its output and exit
+    code on unchanged. The browser the helper opened is the user's own program and is never stopped. When a job that
+    holds GitPane keeps the helper, the helper is stopped before it runs and the sign-in fails with
+    ``BROWSER_SIGN_IN_UNAVAILABLE_TEXT``: the browser would otherwise be closed with that job.
+    """
+    environment_by_name = helper_environment(data_by_key, "", browser=True, trace=True)
+    content = credential_request_content(credential_by_key)
+    wait_ms = browser_timeout_ms(data_by_key)
+    job = ReleasedChildJob()
+    try:
+        try:
+            process = job.start([*data_by_key["helper_commands"], "get"], environment_by_name)
+        except JobBreakawayRefusedError:
+            raise OSError(BROWSER_SIGN_IN_UNAVAILABLE_TEXT) from None
+        try:
+            stdout, stderr = process.communicate(content, timeout=wait_ms / MILLISECONDS_PER_SECOND)
+        except subprocess.TimeoutExpired:
+            # Workaround: stopping the helper can fail, for instance when it ended just as the wait did. Releasing the job
+            # below stops it anyway, and the user must be told that the browser did not answer, not why the stop failed.
+            try:
+                job.stop()
+            except OSError:
+                pass
+            try:
+                process.communicate(timeout=PROCESS_TREE_STOP_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+            except subprocess.TimeoutExpired:
+                pass
+            raise BrowserTimeoutError(BROWSER_TIMEOUT_TEXT) from None
+    finally:
+        job.close()
+    return helper_response(data_by_key, credential_by_key, process.returncode, stdout, stderr)
+
+
+def read_response_prefix(response: object, limit_bytes: int) -> bytes:
+    """Read an HTTP answer in chunks until it ends, keeping at most ``limit_bytes`` of it.
+
+    The length the server announces is not trusted: it neither sizes a buffer nor says when the answer is complete.
+    A short chunk is not the end either; only an empty read is.
+    """
+    content = bytearray()
+    while len(content) < limit_bytes:
+        chunk = response.read(min(PROCESS_CHUNK_BYTES, limit_bytes - len(content)))
+        if not chunk:
+            break
+        content.extend(chunk)
+    return bytes(content)
+
+
+def controlled_origin(data_by_key: dict[str, object]) -> str:
+    """Return the loopback address that isolated tests put in place of every server, or an empty text in normal use.
+
+    Only plain HTTP on 127.0.0.1 is accepted, so a request can never redirect a real secret to another host this way.
+    """
+    validation_origin = data_by_key.get("validation_origin")
+    if not validation_origin:
+        return ""
+    controlled = urlsplit(str(validation_origin))
+    if controlled.scheme != "http" or controlled.hostname != "127.0.0.1":
+        raise ValueError("Controlled authentication requires an explicit loopback endpoint")
+    return str(validation_origin)
+
+
+def validate_identity(data_by_key: dict[str, object], password: str, *, browser: bool) -> AccountSelection:
+    """Read the provider's authenticated-user endpoint before accepting or storing a secret."""
+    provider = str(data_by_key["provider"])
+    origin = endpoint_origin(str(data_by_key["origin"]))
+    parsed = urlsplit(origin)
+    if provider == "GitHub":
+        api_url = "https://api.github.com/user" if parsed.hostname == "github.com" else origin + "/api/v3/user"
+    elif provider == "GitLab":
+        api_url = origin + ("/oauth/token/info" if browser else "/api/v4/user")
+    else:
+        if parsed.hostname != "bitbucket.org":
+            raise ValueError("Bitbucket Cloud sign-in requires https://bitbucket.org")
+        api_url = "https://api.bitbucket.org/2.0/user"
+    validation_origin = controlled_origin(data_by_key)
+    if validation_origin:
+        api_url = validation_origin + urlsplit(api_url).path
+    else:
+        parsed_api = urlsplit(api_url)
+        hostname = parsed_api.hostname.encode("idna").decode("ascii")
+        if ":" in hostname:
+            hostname = "[" + hostname + "]"
+        authority = hostname + (":" + str(parsed_api.port) if parsed_api.port else "")
+        api_url = urlunsplit((parsed_api.scheme, authority, quote(parsed_api.path, safe="/%"), "", ""))
+    authorization = "Bearer " + password
+    if provider == "Bitbucket" and not browser:
+        api_email = validate_text(data_by_key.get("api_email"))
+        authorization = "Basic " + base64.b64encode((api_email + ":" + password).encode("utf-8")).decode("ascii")
+    filter = SensitiveTextFilter({"password": password, "authorization": authorization})
+    request = urllib.request.Request(api_url, headers={"Authorization": authorization, "Accept": "application/json", "User-Agent": USER_AGENT})
+    opener = urllib.request.build_opener(NoRedirect())
+    try:
+        with opener.open(request, timeout=GIT_READ_TIMEOUT_MS / MILLISECONDS_PER_SECOND) as response:
+            body = read_response_prefix(response, TRACE_UNIT_LIMIT_BYTES + READ_SIZE_SENTINEL_BYTES)
+            if len(body) > TRACE_UNIT_LIMIT_BYTES:
+                raise ValueError("The authentication response exceeded the supported size")
+            response_by_key = json.loads(body)
+            if not isinstance(response_by_key, dict):
+                raise TypeError("The provider returned an invalid account response")
+            print(filter.redact(f"GET {api_url}\nHTTP {response.status}\n" + body.decode("utf-8")), file=sys.stderr, flush=True)
+    except urllib.error.HTTPError as error:
+        body = read_response_prefix(error, TRACE_UNIT_LIMIT_BYTES).decode("utf-8", errors="replace")
+        scope_help = ""
+        if error.code == 403:
+            scope_help = "Account identity could not be verified; Git access may still be valid. "
+            scope_help += "GitLab personal tokens need read_user (or api) in addition to repository access.\n" if provider == "GitLab" else "Grant access to the current account profile, then try again.\n"
+        raise ValueError(filter.redact(f"{scope_help}GET {api_url}\nHTTP {error.code}\n{body}")) from None
+    if provider == "GitHub":
+        account = validate_text(response_by_key.get("login"))
+        identity = str(positive_account_id(response_by_key.get("id")))
+        git_username = account
+    elif provider == "GitLab":
+        identity = str(positive_account_id(response_by_key.get("resource_owner_id") if browser else response_by_key.get("id")))
+        account = identity
+        git_username = GITLAB_OAUTH_GIT_USERNAME if browser else validate_text(response_by_key.get("username"))
+    else:
+        account = validate_text(response_by_key.get("uuid") or response_by_key.get("account_id"))
+        identity = str(data_by_key.get("api_email")) if not browser else account
+        git_username = BITBUCKET_OAUTH_GIT_USERNAME if browser else "x-bitbucket-api-token-auth"
+    label = "GitLab account " + identity if provider == "GitLab" and browser else validate_text(response_by_key.get("nickname") or response_by_key.get("login") or response_by_key.get("username") or account)
+    hint = str(data_by_key.get("account_hint", ""))
+    if hint and hint not in (account, label):
+        raise ValueError("The provider returned a different account. Choose that account explicitly or sign in again.")
+    namespace = account_namespace(provider, origin, account)
+    if any(password in value for value in (account, git_username, identity, label)):
+        raise ValueError("The provider returned credential data in an account identity field")
+    return AccountSelection(provider, origin, account, git_username, identity, label, namespace)
+
+
+def positive_account_id(value: object) -> int:
+    """Require the provider's actual numeric identity rather than inventing one for a null response."""
+    if type(value) is not int or value <= 0:
+        raise ValueError("The provider returned no valid account identity")
+    return value
+
+
+def run_exchange(data_by_key: dict[str, object]) -> dict[str, object]:
+    """Separate rejected authentication from successful identity with failed secure storage."""
+    action = AuthenticationAction(data_by_key["action"])
+    if action == AuthenticationAction.LOOKUP:
+        return run_lookup(data_by_key)
+    origin = endpoint_origin(str(data_by_key["origin"]))
+    credential_by_key = {"protocol": "https", "host": urlsplit(origin).netloc}
+    password = str(data_by_key.get("token", ""))
+    selection = AccountSelection(**data_by_key["selection"]) if data_by_key.get("selection") else None
+    if data_by_key["provider"] == GENERIC_PROVIDER:
+        return run_generic_exchange(data_by_key, credential_by_key, selection)
+    if action == AuthenticationAction.GET or action in ERASE_ACTION_SET:
+        credential_by_key["username"] = selection.git_username
+        response_by_key = helper_exchange(data_by_key, "erase" if action in ERASE_ACTION_SET else "get", credential_by_key, namespace=selection.namespace)
+        if action in ERASE_ACTION_SET:
+            return {"status": OperationStatus.SUCCESS.value, "stored": False, "authenticated": False}
+        password = response_by_key.get("password", "")
+        if not password or response_by_key.get("username") != selection.git_username:
+            raise ValueError("The selected account is absent from the secure store. Sign in again.")
+        data_by_key["account_hint"] = selection.account
+        data_by_key["api_email"] = selection.api_identity
+    browser = not password
+    if browser:
+        hint = str(data_by_key.get("account_hint", ""))
+        if hint:
+            credential_by_key["username"] = hint
+        response_by_key = browser_helper_exchange(data_by_key, credential_by_key)
+        password = response_by_key.get("password", "")
+        if not password:
+            raise ValueError("Browser sign-in returned no credential. Sign in again or use a token.")
+    if action == AuthenticationAction.GET:
+        browser = selection.git_username in BROWSER_GIT_USERNAME_SET
+    validated = validate_identity(data_by_key, password, browser=browser)
+    if selection is not None and validated.account != selection.account:
+        if action == AuthenticationAction.APPROVE:
+            raise AccountMismatchError(f"You signed in as {validated.label}, but Reconnect was for {selection.label}. Nothing was changed.")
+        raise AccountMismatchError("The stored credential belongs to a different account. Sign in again.")
+    if action == AuthenticationAction.GET:
+        return {"status": OperationStatus.SUCCESS.value, "selection": asdict(selection), "authenticated": True, "stored": True}
+    return store_and_check(data_by_key, credential_by_key, validated, password, authenticated=True)
+
+
+def store_and_check(data_by_key: dict[str, object], credential_by_key: dict[str, str], validated: AccountSelection, password: str, *, authenticated: bool) -> dict[str, object]:
+    """Store the secret in the account's namespace, then read it back, so an account is only listed once the secure store really holds it.
+
+    A store that refuses or returns something else gives a partial result: the account is not listed. ``authenticated``
+    tells whether the server accepted the identity before this step.
+    """
+    credential_by_key = dict(credential_by_key)
+    credential_by_key["username"] = validated.git_username
+    credential_by_key["password"] = password
+    try:
+        helper_exchange(data_by_key, "store", credential_by_key, namespace=validated.namespace)
+        lookup_by_key = dict(credential_by_key)
+        lookup_by_key.pop("password")
+        observed_by_key = helper_exchange(data_by_key, "get", lookup_by_key, namespace=validated.namespace)
+        if observed_by_key.get("username") != validated.git_username or observed_by_key.get("password") != password:
+            raise ValueError("The secure store did not return the approved credential. Configure the system credential store, then sign in again.")
+    except (OSError, ValueError, subprocess.TimeoutExpired) as error:
+        safe_error = SensitiveTextFilter({"password": password}).redact(str(error))
+        return {"status": OperationStatus.PARTIAL.value, "selection": asdict(validated), "authenticated": authenticated, "stored": False, "error": safe_error}
+    return {"status": OperationStatus.SUCCESS.value, "selection": asdict(validated), "authenticated": authenticated, "stored": True}
+
+
+def check_copy_credential(data_by_key: dict[str, object], selection: AccountSelection) -> dict[str, str]:
+    """Describe the temporary copy of a secret under test the way Git asks the helper for it: protocol, host and username."""
+    parsed = urlsplit(controlled_origin(data_by_key) or selection.origin)
+    return {"protocol": parsed.scheme, "host": parsed.netloc, "username": selection.git_username}
+
+
+def check_arguments(data_by_key: dict[str, object], validated: AccountSelection, check_namespace: str) -> tuple[list[str], str]:
+    """Return the Git arguments that list the repository to test with the typed username, and the URL Git contacts.
+
+    Git may only ask GitPane's helper for the secret, in the test namespace: every inherited helper and askpass program
+    is disabled and inherited HTTP headers are cleared. The secret itself is never part of the arguments.
+    """
+    check_url = str(data_by_key["check_url"])
+    command_url = validated.command_url(check_url)
+    scope_origin = validated.origin
+    loopback_origin = controlled_origin(data_by_key)
+    if loopback_origin:
+        loopback = urlsplit(loopback_origin)
+        command_url = urlunsplit((loopback.scheme, quote(validated.git_username, safe="") + "@" + loopback.netloc, urlsplit(check_url).path, "", ""))
+        scope_origin = loopback_origin
+    parsed_command = urlsplit(command_url)
+    plain_url = urlunsplit((parsed_command.scheme, parsed_command.netloc.rsplit("@", 1)[-1], parsed_command.path, "", ""))
+    arguments = [*credential_configuration(scope_origin, validated.git_username, check_namespace, tuple(data_by_key["helper_commands"])), "-c", "core.askPass=",
+                 *isolated_http_arguments(plain_url), "ls-remote", "--heads", "--", command_url]
+    return arguments, command_url
+
+
+def check_environment(data_by_key: dict[str, object], check_namespace: str, neutral_dir: str) -> dict[str, str]:
+    """Return the environment of the Git test: the helper's own settings, no prompt, no trace and no repository to find.
+
+    Git starts in ``neutral_dir``, an empty folder, and may not look for a repository above it, so no repository
+    configuration is read and nothing of any repository is written.
+    """
+    environment_by_name = helper_environment(data_by_key, check_namespace, browser=False, trace=False)
+    for name in tuple(environment_by_name):
+        upper_name = name.upper()
+        repository_name = upper_name in GIT_LOCAL_ENVIRONMENT_NAMES and upper_name not in CHECK_KEPT_ENVIRONMENT_NAME_SET
+        if repository_name or upper_name in CHECK_REMOVED_ENVIRONMENT_NAME_SET or upper_name.startswith(TRACE_ENVIRONMENT_PREFIXES):
+            environment_by_name.pop(name)
+    environment_by_name["GIT_TERMINAL_PROMPT"] = "0"
+    environment_by_name["LC_ALL"] = "C"
+    environment_by_name["GIT_CEILING_DIRECTORIES"] = os.path.dirname(neutral_dir)
+    return environment_by_name
+
+
+def own_process_group() -> int | None:
+    """Answer the ``process_group`` option that starts a helper tree in a process group of its own, which ``stop_process_tree`` stops as a whole.
+
+    The group stays inside this worker's session (a new session would leave it): when the worker itself is stopped, on
+    Cancel or when GitPane closes, the supervisor on Linux stops every group of that session with it, as the Windows
+    job does. Windows has no POSIX process groups; there the job holds the whole tree.
+    """
+    return NEW_PROCESS_GROUP_ID if os.name != "nt" else None
+
+
+def stop_process_tree(process: subprocess.Popen) -> None:
+    """Stop a process and every process it started, so no helper started by Git can still store the secret afterwards."""
+    try:
+        if os.name == "nt":
+            taskkill_filename = os.path.join(os.environ.get("SystemRoot", WINDOWS_DEFAULT_ROOT_DIR), "System32", "taskkill.exe")
+            subprocess.run([taskkill_filename, "/F", "/T", "/PID", str(process.pid)], capture_output=True, timeout=PROCESS_TREE_STOP_TIMEOUT_MS / MILLISECONDS_PER_SECOND, check=False)
+        else:
+            os.killpg(process.pid, signal.SIGKILL)
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    process.kill()
+
+
+def run_check_git(command: list[str], neutral_dir: str, environment_by_name: dict[str, str], timeout_ms: int) -> tuple[int | None, str]:
+    """Run the Git test and return its exit code, or None when it ran out of time, with its standard error.
+
+    Standard input is empty, so nothing can be typed into it; Git's own list of branches is not needed and is discarded.
+    """
+    process = subprocess.Popen(command, cwd=neutral_dir, env=environment_by_name, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+                               process_group=own_process_group())
+    try:
+        _stdout, stderr = process.communicate(timeout=timeout_ms / MILLISECONDS_PER_SECOND)
+    except subprocess.TimeoutExpired:
+        stop_process_tree(process)
+        try:
+            _stdout, stderr = process.communicate(timeout=PROCESS_TREE_STOP_TIMEOUT_MS / MILLISECONDS_PER_SECOND)
+        except subprocess.TimeoutExpired:
+            stderr = b""
+        return None, (stderr or b"").decode("utf-8", errors="replace")
+    return process.returncode, stderr.decode("utf-8", errors="replace")
+
+
+def erase_check_copy(data_by_key: dict[str, object], selection: AccountSelection, password: str = "") -> bool:
+    """Erase the temporary copy of a secret under test and tell whether the helper did; a failure is written to the diagnostics and changes no result."""
+    try:
+        helper_exchange(data_by_key, "erase", check_copy_credential(data_by_key, selection), namespace=selection.namespace + CHECK_NAMESPACE_SUFFIX)
+    except (OSError, ValueError, subprocess.TimeoutExpired) as error:
+        print(SensitiveTextFilter({"password": password}).redact("The temporary copy of the tested secret could not be erased: " + str(error)), file=sys.stderr, flush=True)
+        return False
+    return True
+
+
+# Recognising the server after a refused password follows the rules of Git Credential Manager's own detection: host
+# name first, then one HEAD request and its known headers. That detection is not asked for here because it records its
+# answer as credential.<url>.provider in the user's global Git configuration, and GitPane must never write there. The
+# rules are therefore reproduced in Python, reading only.
+def server_provider_from_host(host: str) -> str:
+    """Name the provider (GitHub or GitLab) a server's host name gives away, or return an empty text when it tells nothing.
+
+    The provider's own host counts, and so does any name of at least three labels whose first label is the provider's
+    name (github.corp.example, gitlab.company.example). The port is ignored and letters may be in any case.
+    """
+    try:
+        hostname = urlsplit("//" + host).hostname or ""
+    except ValueError:
+        return ""
+    labels = hostname.split(".")
+    for provider in TOKEN_PAGE_PATH_BY_PROVIDER:
+        if hostname == PROVIDER_HOST_BY_NAME[provider]:
+            return provider
+        if len(labels) >= PROVIDER_HOST_MINIMUM_LABEL_COUNT and labels[FIRST_LABEL_INDEX] == provider.lower():
+            return provider
+    return ""
+
+
+def provider_from_headers(header_by_name: Message) -> str:
+    """Name the provider whose known headers appear in a server's answer, or return an empty text."""
+    if header_by_name.get(GITHUB_REQUEST_ID_HEADER) is not None:
+        return GITHUB_PROVIDER
+    if header_by_name.get(GITLAB_FEATURE_CATEGORY_HEADER) is not None:
+        return GITLAB_PROVIDER
+    for challenge in header_by_name.get_all(AUTHENTICATE_HEADER) or []:
+        if GITLAB_REALM_TEXT in challenge.lower():
+            return GITLAB_PROVIDER
+    return ""
+
+
+def probe_server_provider(url: str, timeout_ms: int) -> str:
+    """Send one HEAD request to the tested repository and name the provider its headers give away, or return an empty text.
+
+    The request carries no credentials and no cookie, and a redirect is never followed: only the server's own first
+    answer is read, error statuses included. A server that does not answer within ``timeout_ms`` tells nothing.
+    """
+    request = urllib.request.Request(url, method="HEAD", headers={"User-Agent": USER_AGENT})
+    opener = urllib.request.build_opener(NoRedirect())
+    try:
+        with opener.open(request, timeout=timeout_ms / MILLISECONDS_PER_SECOND) as response:
+            return provider_from_headers(response.headers)
+    except urllib.error.HTTPError as error:
+        header_by_name = error.headers
+        error.close()
+        return provider_from_headers(header_by_name) if header_by_name is not None else ""
+    except (OSError, http.client.HTTPException, ValueError):
+        return ""
+
+
+def gitlab_oauth_configured(git_filename: str, url: str, environment_by_name: dict[str, str], cwd: str) -> bool:
+    """Tell whether the Git configuration names a GitLab OAuth application for this address, so browser sign-in can work there.
+
+    Git only reads its configuration here; a missing Git or a failed read counts as no application.
+    """
+    command = [git_filename, "config", "--get-urlmatch", GITLAB_OAUTH_CLIENT_KEY, url]
+    try:
+        result = subprocess.run(command, cwd=cwd, env=environment_by_name, stdin=subprocess.DEVNULL, capture_output=True,
+                                timeout=GIT_READ_TIMEOUT_MS / MILLISECONDS_PER_SECOND, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return result.returncode == 0 and bool(result.stdout.strip())
+
+
+def server_guidance(data_by_key: dict[str, object], git_output: str, neutral_dir: str, environment_by_name: dict[str, str]) -> dict[str, str]:
+    """After an authentication refusal, say which provider the tested server runs, whether it offers browser sign-in, and where to create a token.
+
+    Nothing is looked up for any other failure. The host name is enough for most servers; otherwise one HEAD request
+    asks the server itself, on the loopback address that isolated tests put in place of every server. A GitHub server
+    offers browser sign-in; a GitLab server only when an OAuth application is configured for its address. Return an
+    empty mapping when the server is not recognised.
+    """
+    if refusal_kind(git_output) is None:
+        return {}
+    check_url = str(data_by_key["check_url"])
+    parsed = urlsplit(check_url)
+    plain_netloc = parsed.netloc.rsplit("@", 1)[-1]
+    provider = server_provider_from_host(plain_netloc)
+    if not provider:
+        loopback_origin = controlled_origin(data_by_key)
+        probe_url = loopback_origin + parsed.path if loopback_origin else urlunsplit((parsed.scheme, plain_netloc, parsed.path, "", ""))
+        provider = probe_server_provider(probe_url, SERVER_PROBE_TIMEOUT_MS)
+    if not provider:
+        return {}
+    plain_url = urlunsplit((parsed.scheme, plain_netloc, parsed.path, "", ""))
+    browser_provider = provider
+    if provider == GITLAB_PROVIDER and not gitlab_oauth_configured(str(data_by_key["git_filename"]), plain_url, environment_by_name, neutral_dir):
+        browser_provider = ""
+    return {"server_provider": provider, "browser_provider": browser_provider, "token_page_url": token_page_url(provider, plain_url)}
+
+
+def check_account(data_by_key: dict[str, object], validated: AccountSelection, password: str) -> tuple[dict[str, object] | None, bool]:
+    """Test a username + password on a repository of its server with `git ls-remote` before anything is saved for the account.
+
+    The secret reaches Git only through GitPane's helper, as a temporary copy in a test namespace that is erased
+    afterwards whatever happens. Return None when the server accepted, otherwise the failed result to publish: nothing
+    stored, a short cause and Git's whole output without any secret; then whether the temporary copy was really erased.
+    """
+    check_namespace = validated.namespace + CHECK_NAMESPACE_SUFFIX
+    arguments, _command_url = check_arguments(data_by_key, validated, check_namespace)
+    git_filename = str(data_by_key["git_filename"])
+    if not os.path.isabs(git_filename):
+        raise ValueError(GIT_MISSING_TEXT)
+    check_url = str(data_by_key["check_url"])
+    timeout_ms = int(data_by_key["check_timeout_ms"])
+    password_filter = SensitiveTextFilter({"password": password, "token": str(data_by_key.get("token", ""))})
+    copy_by_key = dict(check_copy_credential(data_by_key, validated))
+    copy_by_key["password"] = password
+    store_failure_by_key = None
+    try:
+        try:
+            helper_exchange(data_by_key, "store", copy_by_key, namespace=check_namespace)
+        except (OSError, ValueError, subprocess.TimeoutExpired) as error:
+            store_failure_by_key = {"status": OperationStatus.PARTIAL.value, "selection": asdict(validated), "authenticated": False, "stored": False, "error": password_filter.redact(str(error))}
+        else:
+            with tempfile.TemporaryDirectory(prefix="gitpane-check-", ignore_cleanup_errors=True) as neutral_dir:
+                return_code, stderr_text = run_check_git([git_filename, *arguments], neutral_dir, check_environment(data_by_key, check_namespace, neutral_dir), timeout_ms)
+    finally:
+        copy_erased = erase_check_copy(data_by_key, validated, password)
+    if store_failure_by_key is not None:
+        return store_failure_by_key, copy_erased
+    if return_code == 0:
+        return None, copy_erased
+    if return_code is None:
+        cause = CHECK_TIMEOUT_CAUSE.format(url=check_url, seconds=timeout_ms // MILLISECONDS_PER_SECOND)
+    else:
+        cause = CHECK_FAILED_TEXT.format(url=check_url)
+    git_output = "\n".join(git_output_lines(password_filter.redact(stderr_text)))
+    print(git_output, file=sys.stderr, flush=True)
+    check_by_key = {"git_output": git_output, "url": check_url}
+    with tempfile.TemporaryDirectory(prefix="gitpane-check-", ignore_cleanup_errors=True) as neutral_dir:
+        check_by_key.update(server_guidance(data_by_key, git_output, neutral_dir, check_environment(data_by_key, check_namespace, neutral_dir)))
+    return {"status": OperationStatus.FAILED.value, "stored": False, "authenticated": False, "error": cause, "check": check_by_key}, copy_erased
+
+
+def run_generic_exchange(data_by_key: dict[str, object], credential_by_key: dict[str, str], selection: AccountSelection | None) -> dict[str, object]:
+    """Handle a username + password account; no provider API is ever called for it.
+
+    Adding or reconnecting first tests the typed password with Git on a repository of the server; only an accepted test
+    stores it, so a refused Reconnect keeps the secret that was saved before. A Reconnect keeps the account's username,
+    so it can never turn one account into another.
+    """
+    action = AuthenticationAction(data_by_key["action"])
+    origin = endpoint_origin(str(data_by_key["origin"]))
+    if action != AuthenticationAction.SIGN_IN and (selection is None or selection.provider != GENERIC_PROVIDER or selection.origin != origin):
+        raise ValueError("The selected account does not match this request. Nothing was changed.")
+    if action == AuthenticationAction.ERASE_CHECK:
+        erase_check_copy(data_by_key, selection)
+        return {"status": OperationStatus.SUCCESS.value, "stored": False, "authenticated": False}
+    if action == AuthenticationAction.GET:
+        lookup_by_key = dict(credential_by_key)
+        lookup_by_key["username"] = selection.git_username
+        response_by_key = helper_exchange(data_by_key, "get", lookup_by_key, namespace=selection.namespace)
+        if not response_by_key.get("password") or response_by_key.get("username") != selection.git_username:
+            raise ValueError("The selected account is absent from the secure store. Add it again.")
+        return {"status": OperationStatus.SUCCESS.value, "selection": asdict(selection), "authenticated": False, "stored": True}
+    if action in ERASE_ACTION_SET:
+        erase_by_key = dict(credential_by_key)
+        erase_by_key["username"] = selection.git_username
+        helper_exchange(data_by_key, "erase", erase_by_key, namespace=selection.namespace)
+        # A test copy an earlier account test could not erase goes with the account.
+        erase_check_copy(data_by_key, selection)
+        return {"status": OperationStatus.SUCCESS.value, "stored": False, "authenticated": False}
+    username = selection.git_username if action == AuthenticationAction.APPROVE else str(data_by_key.get("username", ""))
+    password = str(data_by_key.get("token", ""))
+    if not password:
+        raise ValueError("Enter a password or token.")
+    validated = generic_account(origin, username)
+    if action == AuthenticationAction.APPROVE and validated.namespace != selection.namespace:
+        raise ValueError("Reconnect must keep the account's username. Nothing was changed.")
+    failure_by_key, copy_erased = check_account(data_by_key, validated, password)
+    result_by_key = failure_by_key if failure_by_key is not None else store_and_check(data_by_key, credential_by_key, validated, password, authenticated=True)
+    result_by_key[CHECK_COPY_ERASED_KEY] = copy_erased
+    return result_by_key
+
+
+def main() -> None:
+    """Accept private JSON on stdin and publish only nonsecret results on private stdout."""
+    data_by_key: dict[str, object] = {}
+    try:
+        data_by_key = json.loads(sys.stdin.buffer.read())
+        result_by_key = run_exchange(data_by_key)
+    except BrowserTimeoutError:
+        result_by_key = {"status": OperationStatus.SIGN_IN_TIMEOUT.value, "error": BROWSER_TIMEOUT_TEXT}
+    except AccountMismatchError as error:
+        safe_error = SensitiveTextFilter({"token": str(data_by_key.get("token", ""))}).redact(str(error))
+        result_by_key = {"status": OperationStatus.FAILED.value, "error": safe_error, GITPANE_REFUSAL_KEY: True}
+    except (OSError, ValueError, KeyError, TypeError, subprocess.TimeoutExpired) as error:
+        safe_error = SensitiveTextFilter({"token": str(data_by_key.get("token", ""))}).redact(str(error))
+        result_by_key = {"status": OperationStatus.FAILED.value, "error": safe_error}
+    sys.stdout.buffer.write(json.dumps(result_by_key, ensure_ascii=False).encode("utf-8"))
+    sys.stdout.buffer.flush()
+
+
+if __name__ == "__main__":
+    main()