π« Toolkit to help you get started with SDD or any other process!
feat(auth): support GitHub CLI credentials (#4960)
Manfred Riem67e0f7294e6e
diff --git a/docs/reference/authentication.md b/docs/reference/authentication.mdindex 9e0ff2144..f7f2e0274 100644--- a/docs/reference/authentication.md+++ b/docs/reference/authentication.md@@ -59,6 +59,7 @@ Either `token` or `token_env` must be set for the `bearer`, `basic-pat`, and `ba| Scheme | Header | Use for ||---|---|---|| `bearer` | `Authorization: Bearer <token>` | PATs, fine-grained PATs, OAuth tokens, GitHub App tokens |+| `github-cli` | `Authorization: Bearer <token>` | Credentials acquired on demand via `gh auth token` |**Example β PAT via environment variable:**@@ -71,6 +72,51 @@ Either `token` or `token_env` must be set for the `bearer`, `basic-pat`, and `ba}```+**Example β GitHub CLI:**++```json+{+ "providers": [+ {+ "hosts": [+ "github.com",+ "api.github.com",+ "raw.githubusercontent.com",+ "codeload.github.com"+ ],+ "provider": "github",+ "auth": "github-cli"+ }+ ]+}+```++Install [GitHub CLI](https://cli.github.com/) and run `gh auth login` before+using this mode. Specify runs the fixed command+`gh auth token --hostname github.com` without a shell, caches the result in+memory for the current process, and never writes the token to disk.+Surrounding whitespace is trimmed; tokens containing non-ASCII characters,+embedded carriage returns, or newlines are rejected without including the+token in the error.+Credential acquisition failures fail the affected request without trying another+credential or an unauthenticated request. They use the existing URL-error+category, so callers retain their normal error handling (for example, warning+and skipping an unavailable catalog).+Release checks and upgrades preserve the authentication diagnostic rather than+reporting a network outage. Online bundle catalog fetching and reference+validation treat authentication failures as errors, not as availability+fallbacks to packaged snapshots or unchecked references.++For `github-cli` only, the **first hostname in `hosts`** is passed to+`gh auth token --hostname`. Put `github.com` or your enterprise instance's+GitHub CLI login hostname first. It must be an exact hostname, not a wildcard.+All listed hosts remain request-matching destinations authorized to receive+that credential; later entries may use supported wildcards. Specify does not+infer the credential hostname from service prefixes or the requested URL.+The in-memory cache is keyed by the first hostname. Use separate provider+entries for hosts requiring different credentials. Host order has no effect+on existing authentication modes.+### GitHub Enterprise Server (GHES)To use a private catalog or extension hosted on a GitHub Enterprise Server@@ -98,6 +144,28 @@ and `codeload.` subdomains your catalog/extension URLs use. A`*.ghes.example.com` wildcard matches subdomains but **not** the bare host,so always include the bare host explicitly.+With `auth: "github-cli"`, list your enterprise instance's GitHub CLI login+hostname first, followed by any request hosts or wildcard patterns that should+receive the same credential:++```json+{+ "hosts": [+ "ghes.example.com",+ "raw.ghes.example.com",+ "codeload.ghes.example.com"+ ],+ "provider": "github",+ "auth": "github-cli"+}+```++Specify runs `gh auth token --hostname ghes.example.com`, using the first+hostname exactly as configured. Use separate provider entries for separate+GitHub instances. The selected host must already be+authenticated in GitHub CLI; failures suggest `gh auth login --hostname <host>`+without including GitHub CLI command output.+### GitHub Enterprise Cloud with data residency (GHE.com)GHE.com tenants use separate web and REST API hostnames. List both hosts so@@ -264,10 +332,13 @@ You can configure multiple entries for different hosts or organizations:1. For each outbound HTTP request, the URL hostname is matched againstthe `hosts` patterns in `auth.json`.2. If a match is found, the corresponding provider resolves the token- and attaches the appropriate `Authorization` header.-3. If the request receives a 401 or 403, the next matching entry is tried.-4. After all matching entries are exhausted, an unauthenticated request- is attempted as a final fallback.+ and attaches the appropriate `Authorization` header. A `github-cli`+ acquisition failure ends the request immediately, without trying later+ matching entries or making an unauthenticated request.+3. After successful token acquisition, if the request receives a 401 or 403,+ the next matching entry is tried.+4. After all matching entries are exhausted without an acquisition failure,+ an unauthenticated request is attempted as a final fallback.5. On redirects, the `Authorization` header is stripped if the redirecttarget leaves the entry's declared hosts β preventing credentialleakage to CDNs or third-party services.diff --git a/src/specify_cli/_version.py b/src/specify_cli/_version.pyindex 93b4c6a61..c8fcad7c7 100644--- a/src/specify_cli/_version.py+++ b/src/specify_cli/_version.py@@ -37,6 +37,7 @@ _RESOLUTION_FAILURE_RATE_LIMITED = ("rate limited (configure ~/.specify/auth.json with a GitHub token)")_RESOLUTION_FAILURE_HTTP_PREFIX = "HTTP "+_RESOLUTION_FAILURE_AUTH_PREFIX = "authentication error: "_FAILURE_INSTALLER_MISSING = "installer-missing"_FAILURE_INSTALLER_INVALID = "installer-invalid"_FAILURE_TARGET_TAG_UNPARSEABLE = "target-tag-unparseable"@@ -108,11 +109,12 @@ def _fetch_latest_release_tag() -> tuple[str | None, str | None]:"""Return (tag, failure_category). Exactly one outbound call, 5 s timeout.On success: (tag_name, None).- On a documented network/HTTP failure (added in T029/T030): (None, category).+ On a documented authentication/network/HTTP failure: (None, category).On anything else β including a malformed response body β the exceptionpropagates; there is no catch-all (research D-006)."""from .authentication.http import open_url+ from .authentication.github import GitHubCliAuthErrortry:with open_url(@@ -131,6 +133,8 @@ def _fetch_latest_release_tag() -> tuple[str | None, str | None]:if not isinstance(tag, str) or not tag:raise ValueError("GitHub API response missing valid tag_name")return tag, None+ except GitHubCliAuthError as exc:+ return None, f"{_RESOLUTION_FAILURE_AUTH_PREFIX}{exc.reason}"except urllib.error.HTTPError as e:# Order matters: HTTPError is a subclass of URLError.# 403 (primary rate limit / abuse detection) and 429 (Too Many Requests /@@ -1021,7 +1025,10 @@ def _emit_failure("""Render user-facing output for resolver, installer, or verification failures."""if (category in _RESOLUTION_FAILURE_CATEGORIES- or category.startswith(_RESOLUTION_FAILURE_HTTP_PREFIX)+ or category.startswith((+ _RESOLUTION_FAILURE_HTTP_PREFIX,+ _RESOLUTION_FAILURE_AUTH_PREFIX,+ ))):console.print(f"Upgrade aborted: {category}", soft_wrap=True)returndiff --git a/src/specify_cli/authentication/github.py b/src/specify_cli/authentication/github.pyindex 3797d8292..655063e33 100644--- a/src/specify_cli/authentication/github.py+++ b/src/specify_cli/authentication/github.py@@ -2,23 +2,144 @@from __future__ import annotations+import os+import shutil+import subprocess+from typing import TYPE_CHECKING+from urllib.error import URLError+from .base import AuthProvider+if TYPE_CHECKING:+ from .config import AuthConfigEntry-class GitHubAuth(AuthProvider):- """GitHub authentication provider.- Supports the ``bearer`` auth scheme, used for PATs, fine-grained PATs,- OAuth tokens, and GitHub App installation tokens.- """+_GITHUB_CLI_TIMEOUT_SECONDS = 10+++def _is_safe_cli_hostname(hostname: str) -> bool:+ """Return whether *hostname* is a shell-safe DNS hostname."""+ if not hostname or len(hostname) > 253 or not hostname.isascii():+ return False+ labels = hostname.split(".")+ return all(+ 0 < len(label) <= 63+ and label[0].isalnum()+ and label[-1].isalnum()+ and all(char.isalnum() or char == "-" for char in label)+ for label in labels+ )+++class GitHubCliAuthError(URLError):+ """Raised when GitHub CLI cannot provide a configured credential."""+++class GitHubAuth(AuthProvider):+ """GitHub authentication provider."""key = "github"- supported_auth_schemes = ("bearer",)+ supported_auth_schemes = ("bearer", "github-cli")++ def __init__(self) -> None:+ self._github_cli_cache: dict[str, tuple[bool, str]] = {}def auth_headers(self, token: str, auth_scheme: str) -> dict[str, str]:- """Return ``Authorization: Bearer <token>``."""- if auth_scheme != "bearer":+ """Return a bearer authorization header."""+ if auth_scheme not in self.supported_auth_schemes:raise ValueError(f"GitHubAuth does not support auth scheme {auth_scheme!r}")- return {"Authorization": f"Bearer {token}"}+ return {"Authorization": "Bearer " + token}++ def resolve_token(self, entry: AuthConfigEntry) -> str | None:+ """Resolve a configured token or acquire one from GitHub CLI."""+ if entry.auth != "github-cli":+ return super().resolve_token(entry)++ credential_host = self._credential_hostname(entry)+ cached = self._github_cli_cache.get(credential_host)+ if cached is not None:+ succeeded, value = cached+ if succeeded:+ return value+ raise GitHubCliAuthError(value)++ try:+ token = self._acquire_via_gh_cli(credential_host)+ except GitHubCliAuthError as exc:+ message = str(exc.reason)+ self._github_cli_cache[credential_host] = (False, message)+ raise GitHubCliAuthError(message) from None++ self._github_cli_cache[credential_host] = (True, token)+ return token++ @staticmethod+ def _credential_hostname(entry: AuthConfigEntry) -> str:+ """Use the first configured host for GitHub CLI credential acquisition."""+ hostname = entry.hosts[0]+ if "*" in hostname:+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ "the first hostname in a github-cli entry must be an exact "+ "hostname, not a wildcard."+ )+ return hostname++ @staticmethod+ def _acquire_via_gh_cli(hostname: str) -> str:+ """Run the fixed GitHub CLI token command for *hostname*."""+ if not _is_safe_cli_hostname(hostname):+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ "the configured hostname is not valid for GitHub CLI authentication."+ )++ resolved = shutil.which("gh")+ if not resolved or not os.path.isabs(resolved):+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ "GitHub CLI ('gh') was not found."+ )++ try:+ result = subprocess.run( # noqa: S603+ [resolved, "auth", "token", "--hostname", hostname],+ capture_output=True,+ text=True,+ timeout=_GITHUB_CLI_TIMEOUT_SECONDS,+ check=False,+ shell=False,+ )+ except subprocess.TimeoutExpired:+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ f"GitHub CLI timed out while requesting a token for {hostname!r}."+ ) from None+ except (OSError, UnicodeDecodeError):+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ f"GitHub CLI could not provide a token for {hostname!r}."+ ) from None++ if result.returncode != 0:+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ f"GitHub CLI could not provide a token for {hostname!r}. "+ f"Run 'gh auth login --hostname {hostname}'."+ )++ token = result.stdout.strip()+ if not token:+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ f"GitHub CLI returned an empty token for {hostname!r}. "+ f"Run 'gh auth login --hostname {hostname}'."+ )+ if not token.isascii() or "\r" in token or "\n" in token:+ raise GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': "+ f"GitHub CLI returned a malformed token for {hostname!r}."+ )+ return tokendiff --git a/src/specify_cli/authentication/http.py b/src/specify_cli/authentication/http.pyindex 7dabc752a..795b491e1 100644--- a/src/specify_cli/authentication/http.py+++ b/src/specify_cli/authentication/http.py@@ -133,6 +133,8 @@ def build_request(url: str, extra_headers: dict[str, str] | None = None) -> urllUses the first matching entry from ``auth.json`` whose token resolves.Returns a plain request when no entry matches or the file doesn't exist.+ A ``github-cli`` acquisition failure raises immediately, without trying+ later matching entries or returning an unauthenticated request."""headers: dict[str, str] = {}if extra_headers:@@ -174,9 +176,12 @@ def open_url("""Open *url* with config-driven auth, redirect stripping, and fallthrough.1. Find ``auth.json`` entries whose hosts match the URL.- 2. For each entry, resolve the token and try the request.- 3. On 401/403 move to the next matching entry.- 4. After all entries exhausted (or none matched), try unauthenticated.+ 2. For each entry, resolve the token and try the request. A ``github-cli``+ acquisition failure raises immediately, with no credential or+ unauthenticated fallback.+ 3. On HTTP 401/403 after successful acquisition, try the next matching entry.+ 4. After all entries exhausted without an acquisition failure (or none+ matched), try unauthenticated.5. Non-auth errors (404, 500, network) raise immediately.*extra_headers* (e.g. ``Accept``) are merged into every attempt.diff --git a/src/specify_cli/bundles/adapters.py b/src/specify_cli/bundles/adapters.pyindex 46433cb00..fb4c6571c 100644--- a/src/specify_cli/bundles/adapters.py+++ b/src/specify_cli/bundles/adapters.py@@ -228,6 +228,7 @@ def _http_get_json(source_id: str, url: str) -> dict:HTTPS/host guarantee from ``_validate_remote_url`` is preserved end to endrather than only on the initial URL."""+ from ..authentication.github import GitHubCliAuthErrorfrom ..authentication.http import RedirectPolicyError, open_urldef _validate_redirect(_old_url: str, new_url: str) -> None:@@ -258,9 +259,9 @@ def _http_get_json(source_id: str, url: str) -> dict:raise BundlerError(f"Failed to fetch catalog from {url}: {exc}") from exc- except RedirectPolicyError as exc:- # Unsafe/malformed redirects are security failures and must surface as- # a hard error instead of being downgraded to catalog unavailability.+ except (GitHubCliAuthError, RedirectPolicyError) as exc:+ # Authentication and redirect-policy failures are definitive, not+ # transient catalog unavailability.raise BundlerError(f"Failed to fetch catalog from {url}: {exc}") from excdiff --git a/src/specify_cli/bundles/component_catalog.py b/src/specify_cli/bundles/component_catalog.pyindex d4b7a107c..aef547e6a 100644--- a/src/specify_cli/bundles/component_catalog.py+++ b/src/specify_cli/bundles/component_catalog.py@@ -6,6 +6,7 @@ import sslfrom http.client import HTTPExceptionfrom urllib.error import HTTPError, URLError+from ..authentication.github import GitHubCliAuthErrorfrom ..authentication.http import RedirectPolicyErrorfrom . import BundlerErrorfrom .manifest import ComponentRef@@ -19,7 +20,7 @@ def _is_unavailable(exc: BaseException) -> bool:seen: set[int] = set()while exc is not None and id(exc) not in seen:seen.add(id(exc))- if isinstance(exc, RedirectPolicyError):+ if isinstance(exc, (GitHubCliAuthError, RedirectPolicyError)):return Falseif isinstance(exc, HTTPError):return exc.code in (408, 429) or 500 <= exc.code <= 599diff --git a/tests/specify_cli/authentication/test_authentication.py b/tests/specify_cli/authentication/test_authentication.pyindex 45c0a4b83..31c94f2ad 100644--- a/tests/specify_cli/authentication/test_authentication.py+++ b/tests/specify_cli/authentication/test_authentication.py@@ -30,7 +30,7 @@ from specify_cli.authentication.config import (find_entries_for_url,load_auth_config,)-from specify_cli.authentication.github import GitHubAuth+from specify_cli.authentication.github import GitHubAuth, GitHubCliAuthError# ---------------------------------------------------------------------------@@ -49,6 +49,22 @@ def _github_entry(token_env: str = "GH_TOKEN", token: str | None = None) -> Auth)+def _github_cli_entry(+ hosts: tuple[str, ...] = (+ "github.com",+ "api.github.com",+ "raw.githubusercontent.com",+ "codeload.github.com",+ ),+) -> AuthConfigEntry:+ """Build a GitHub CLI config entry."""+ return AuthConfigEntry(+ hosts=hosts,+ provider="github",+ auth="github-cli",+ )++def _ado_basic_entry(token_env: str = "AZURE_DEVOPS_PAT") -> AuthConfigEntry:"""Build an ADO basic-pat config entry."""return AuthConfigEntry(@@ -94,6 +110,23 @@ class TestLoadAuthConfig:assert entries[0].auth == "bearer"assert entries[0].token_env == "GH_TOKEN"+ def test_valid_github_cli_config(self, tmp_path):+ cfg = tmp_path / "auth.json"+ cfg.write_text(json.dumps({+ "providers": [{+ "hosts": ["github.com", "api.github.com"],+ "provider": "github",+ "auth": "github-cli",+ }]+ }))++ entries = load_auth_config(cfg)++ assert len(entries) == 1+ assert entries[0].auth == "github-cli"+ assert entries[0].token is None+ assert entries[0].token_env is None+def test_padded_token_env_is_normalized_and_resolves(self, tmp_path, monkeypatch):# token_env is validated on its stripped form but was stored raw, so a# padded env-var name passed validation yet broke the verbatim@@ -589,6 +622,272 @@ class TestGitHubAuth:def test_bearer_headers(self):assert GitHubAuth().auth_headers("my-token", "bearer") == {"Authorization": "Bearer my-token"}+ def test_github_cli_headers(self):+ assert GitHubAuth().auth_headers("my-token", "github-cli") == {+ "Authorization": "Bearer my-token"+ }++ def test_github_cli_resolves_token_with_fixed_command(self):+ from unittest.mock import MagicMock, patch++ result = MagicMock(returncode=0, stdout=" cli-token\n")+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ ) as run:+ token = GitHubAuth().resolve_token(_github_cli_entry())++ assert token == "cli-token"+ run.assert_called_once_with(+ [executable, "auth", "token", "--hostname", "github.com"],+ capture_output=True,+ text=True,+ timeout=10,+ check=False,+ shell=False,+ )++ def test_github_cli_uses_bare_enterprise_host(self):+ from unittest.mock import MagicMock, patch++ entry = _github_cli_entry((+ "ghes.example.com",+ "raw.ghes.example.com",+ "codeload.ghes.example.com",+ ))+ result = MagicMock(returncode=0, stdout="enterprise-token")+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ ) as run:+ assert GitHubAuth().resolve_token(entry) == "enterprise-token"++ assert run.call_args.args[0][-2:] == ["--hostname", "ghes.example.com"]++ @pytest.mark.parametrize("hosts", [+ ("api.company.example",),+ ("raw.company.example", "api.raw.company.example"),+ ("api.github.com", "github.com"),+ ("ghes.example.com", "*.ghes.example.com"),+ ("first.example.com", "second.example.com"),+ ])+ def test_github_cli_uses_first_hostname(self, hosts):+ from unittest.mock import patch++ with patch.object(+ GitHubAuth, "_acquire_via_gh_cli", return_value="cli-token",+ ) as acquire:+ assert GitHubAuth().resolve_token(_github_cli_entry(hosts)) == "cli-token"++ acquire.assert_called_once_with(hosts[0])++ def test_github_cli_rejects_wildcard_first_hostname(self):+ from unittest.mock import patch++ entry = _github_cli_entry(("*.ghes.example.com", "ghes.example.com"))+ with patch(+ "specify_cli.authentication.github.shutil.which",+ ) as which, patch(+ "specify_cli.authentication.github.subprocess.run",+ ) as run, pytest.raises(GitHubCliAuthError, match="first hostname"):+ GitHubAuth().resolve_token(entry)++ which.assert_not_called()+ run.assert_not_called()++ def test_github_cli_caches_by_first_hostname(self):+ from unittest.mock import patch++ provider = GitHubAuth()+ with patch.object(+ GitHubAuth, "_acquire_via_gh_cli", side_effect=["first-token", "second-token"],+ ) as acquire:+ assert provider.resolve_token(_github_cli_entry((+ "first.example.com", "api.first.example.com",+ ))) == "first-token"+ assert provider.resolve_token(_github_cli_entry((+ "first.example.com", "*.first.example.com",+ ))) == "first-token"+ assert provider.resolve_token(_github_cli_entry((+ "second.example.com", "first.example.com",+ ))) == "second-token"++ assert [call.args for call in acquire.call_args_list] == [+ ("first.example.com",), ("second.example.com",),+ ]++ def test_github_cli_caches_token_per_process(self):+ from unittest.mock import MagicMock, patch++ provider = GitHubAuth()+ result = MagicMock(returncode=0, stdout="cached-token")+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ ) as run:+ assert provider.resolve_token(_github_cli_entry()) == "cached-token"+ assert provider.resolve_token(_github_cli_entry()) == "cached-token"++ run.assert_called_once()++ @pytest.mark.parametrize("executable", [None, r".\gh.exe", "gh.exe", "./gh"])+ def test_github_cli_rejects_missing_or_relative_executable(self, executable):+ from unittest.mock import patch++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ ) as run, pytest.raises(GitHubCliAuthError, match="was not found"):+ GitHubAuth().resolve_token(_github_cli_entry())++ run.assert_not_called()++ def test_github_cli_nonzero_suggests_login_without_command_output(self):+ from unittest.mock import MagicMock, patch++ secret = "ghp_must_not_leak"+ result = MagicMock(returncode=1, stdout=secret, stderr=secret)+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ ), pytest.raises(GitHubCliAuthError) as exc_info:+ GitHubAuth().resolve_token(_github_cli_entry())++ message = str(exc_info.value)+ assert "gh auth login --hostname github.com" in message+ assert secret not in message++ def test_github_cli_empty_output_raises(self):+ from unittest.mock import MagicMock, patch++ result = MagicMock(returncode=0, stdout=" \n", stderr="")+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ ), pytest.raises(GitHubCliAuthError, match="empty token"):+ GitHubAuth().resolve_token(_github_cli_entry())++ @pytest.mark.parametrize("invalid_text", ["\r", "\n", "\r\n", "\u00e9", "\u2603"])+ def test_github_cli_caches_sanitized_malformed_token_failure(self, invalid_text):+ from unittest.mock import MagicMock, patch++ secret = "synthetic_credential"+ result = MagicMock(returncode=0, stdout=f" {secret}{invalid_text}extra\n")+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")+ provider = GitHubAuth()+ messages = []++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ ) as run:+ for _ in range(2):+ with pytest.raises(GitHubCliAuthError, match="malformed token") as exc_info:+ provider.resolve_token(_github_cli_entry())+ messages.append(str(exc_info.value))+ assert secret not in messages[-1]+ assert "extra" not in messages[-1]++ assert messages[0] == messages[1]+ assert provider._github_cli_cache == {+ "github.com": (False, exc_info.value.reason),+ }+ run.assert_called_once()++ def test_github_cli_timeout_raises(self):+ import subprocess+ from unittest.mock import patch++ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ side_effect=subprocess.TimeoutExpired(["gh"], 10),+ ), pytest.raises(GitHubCliAuthError, match="timed out"):+ GitHubAuth().resolve_token(_github_cli_entry())++ @pytest.mark.parametrize("error", [+ None,+ PermissionError("secret"),+ UnicodeDecodeError("utf-8", b"secret\xff", 6, 7, "secret"),+ ], ids=["nonzero-exit", "permission-error", "decode-error"])+ def test_github_cli_caches_sanitized_failure(self, error):+ from unittest.mock import MagicMock, patch++ provider = GitHubAuth()+ result = MagicMock(returncode=1, stdout="secret", stderr="secret")+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")+ messages = []++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ side_effect=error,+ ) as run:+ for _ in range(2):+ with pytest.raises(GitHubCliAuthError) as exc_info:+ provider.resolve_token(_github_cli_entry())+ assert "secret" not in str(exc_info.value)+ messages.append(str(exc_info.value))++ assert messages[0] == messages[1]+ assert "provider 'github'" in messages[0]+ assert "could not provide a token" in messages[0]+ run.assert_called_once()++ def test_github_cli_rejects_shell_unsafe_host_without_echoing_it(self):+ from unittest.mock import patch++ unsafe_host = "a&whoami&b.ghes.example.com"+ entry = _github_cli_entry((unsafe_host,))++ with patch(+ "specify_cli.authentication.github.shutil.which",+ ) as which, patch(+ "specify_cli.authentication.github.subprocess.run",+ ) as run, pytest.raises(GitHubCliAuthError) as exc_info:+ GitHubAuth().resolve_token(entry)++ assert unsafe_host not in str(exc_info.value)+ which.assert_not_called()+ run.assert_not_called()+def test_unsupported_scheme_raises(self):with pytest.raises(ValueError, match="basic-pat"):GitHubAuth().auth_headers("tok", "basic-pat")@@ -616,7 +915,7 @@ class TestGitHubAuth:assert GitHubAuth.key == "github"def test_supported_schemes(self):- assert GitHubAuth.supported_auth_schemes == ("bearer",)+ assert GitHubAuth.supported_auth_schemes == ("bearer", "github-cli")# ---------------------------------------------------------------------------@@ -1234,6 +1533,261 @@ class TestAuthenticatedHttpNegative:open_url("https://example.com/file")+# ---------------------------------------------------------------------------+# GitHub CLI β registered provider HTTP wiring+# ---------------------------------------------------------------------------+++class TestGitHubCliAuthenticatedHttp:+ @pytest.fixture(autouse=True)+ def isolate_config_and_cache(self, monkeypatch):+ from specify_cli.authentication import http++ provider = get_provider("github")+ assert isinstance(provider, GitHubAuth)+ monkeypatch.setattr(provider, "_github_cli_cache", {})+ monkeypatch.setattr(http, "_config_override", [_github_cli_entry()])++ @pytest.mark.parametrize("helper", ["build_request", "open_url"])+ def test_resolved_token_becomes_bearer_header(self, helper):+ from unittest.mock import MagicMock, patch+ from specify_cli.authentication import http++ result = MagicMock(returncode=0, stdout=" cli-token\n")+ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")+ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=result,+ ) as run, patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener:+ if helper == "build_request":+ request = http.build_request("https://api.github.com/repos/org/repo")+ build_opener.assert_not_called()+ else:+ response = http.open_url("https://api.github.com/repos/org/repo")+ opener = build_opener.return_value+ assert response is opener.open.return_value+ opener.open.assert_called_once()+ request = opener.open.call_args.args[0]++ assert request.get_header("Authorization") == "Bearer cli-token"+ run.assert_called_once_with(+ [executable, "auth", "token", "--hostname", "github.com"],+ capture_output=True,+ text=True,+ timeout=10,+ check=False,+ shell=False,+ )++ @pytest.mark.parametrize("helper", ["build_request", "open_url"])+ def test_acquisition_failure_stops_credential_and_anonymous_fallback(+ self, monkeypatch, helper,+ ):+ from unittest.mock import patch+ from specify_cli.authentication import http++ entry = _github_cli_entry()+ monkeypatch.setattr(http, "_config_override", [+ entry, _github_entry(token="backup-token"),+ ])+ provider = get_provider("github")+ assert isinstance(provider, GitHubAuth)+ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=None,+ ) as which, patch(+ "specify_cli.authentication.github.subprocess.run",+ ) as run, patch.object(+ provider, "resolve_token", wraps=provider.resolve_token,+ ) as resolve, patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener, pytest.raises(GitHubCliAuthError, match="was not found"):+ getattr(http, helper)("https://api.github.com/repos/org/repo")++ resolve.assert_called_once_with(entry)+ which.assert_called_once_with("gh")+ run.assert_not_called()+ build_opener.assert_not_called()++ @pytest.mark.parametrize("target,expected_auth", [+ ("https://codeload.github.com/org/repo/zip", "Bearer cli-token"),+ ("https://unlisted.example.com/archive.zip", None),+ ])+ def test_open_url_wires_declared_redirect_hosts(self, target, expected_auth):+ from unittest.mock import MagicMock, patch+ from specify_cli.authentication import http++ executable = os.path.join(os.path.abspath(os.sep), "opt", "gh", "gh")+ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=executable,+ ), patch(+ "specify_cli.authentication.github.subprocess.run",+ return_value=MagicMock(returncode=0, stdout="cli-token"),+ ), patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener:+ http.open_url("https://github.com/org/repo/archive.zip")++ handler = build_opener.call_args.args[0]+ request = build_opener.return_value.open.call_args.args[0]+ redirected = handler.redirect_request(+ request, io.BytesIO(b""), 302, "Found", {}, target,+ )+ assert redirected is not None+ assert redirected.get_header("Authorization") == expected_auth++ def test_failed_cli_catalog_does_not_abort_other_catalogs(+ self, tmp_path, monkeypatch, capsys,+ ):+ from unittest.mock import MagicMock, patch+ from specify_cli.integrations import IntegrationCatalog, IntegrationCatalogEntry++ catalog = IntegrationCatalog(tmp_path)+ entries = [+ IntegrationCatalogEntry(+ url="https://github.com/org/private/catalog.json",+ name="private", priority=1, install_allowed=True,+ ),+ IntegrationCatalogEntry(+ url="https://catalog.example.com/catalog.json",+ name="public", priority=2, install_allowed=True,+ ),+ ]+ monkeypatch.setattr(catalog, "get_active_catalogs", lambda: entries)+ response = MagicMock()+ response.__enter__.return_value = response+ response.geturl.return_value = entries[1].url+ response.read.side_effect = io.BytesIO(json.dumps({+ "schema_version": "1.0",+ "integrations": {"example": {"name": "Example"}},+ }).encode()).read+ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=None,+ ), patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener:+ build_opener.return_value.open.return_value = response+ results = catalog.search()++ assert [item["id"] for item in results] == ["example"]+ warning = capsys.readouterr().err+ assert "Could not fetch catalog 'private'" in warning+ assert "GitHub CLI ('gh') was not found" in warning+ build_opener.return_value.open.assert_called_once()++ def test_release_check_preserves_cli_failure_reason(self):+ from unittest.mock import patch+ from specify_cli._version import _fetch_latest_release_tag++ with patch(+ "specify_cli.authentication.github.shutil.which",+ return_value=None,+ ), patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener:+ tag, reason = _fetch_latest_release_tag()++ assert tag is None+ assert reason is not None+ assert "GitHub CLI ('gh') was not found" in reason+ assert "offline or timeout" not in reason++ build_opener.assert_not_called()++ @pytest.mark.parametrize("detail", [+ "GitHub CLI ('gh') was not found.",+ "Run 'gh auth login --hostname github.com'.",+ ])+ @pytest.mark.parametrize("command,exit_code", [("check", 0), ("upgrade", 1)])+ def test_release_commands_preserve_cli_failure(self, detail, command, exit_code):+ from unittest.mock import patch+ from typer.testing import CliRunner+ from specify_cli import app, _version++ error = GitHubCliAuthError(+ "GitHub authentication failed for provider 'github': " + detail+ )+ with patch.object(+ GitHubAuth, "_acquire_via_gh_cli", side_effect=error,+ ), patch.object(+ _version, "_detect_install_method", return_value=_version._InstallMethod.UV_TOOL,+ ), patch.object(+ _version, "_get_installed_version", return_value="1.0.0",+ ), patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener, patch.object(_version.subprocess, "run") as run:+ result = CliRunner().invoke(app, ["self", command])++ assert result.exit_code == exit_code, result.output+ output = " ".join(result.output.split())+ assert detail in output+ assert "offline or timeout" not in output+ build_opener.assert_not_called()+ run.assert_not_called()++ @pytest.mark.parametrize("url", [+ "builtin://default",+ "https://github.com/org/repo/catalog.json",+ ])+ def test_bundle_catalog_auth_failure_does_not_use_snapshot(self, url):+ from unittest.mock import patch+ from specify_cli.bundles import BundlerError, adapters+ from specify_cli.bundles.catalogs import CatalogSource, InstallPolicy++ source = CatalogSource(+ id="test", url=url, priority=1,+ install_policy=InstallPolicy.INSTALL_ALLOWED,+ )+ with patch(+ "specify_cli.authentication.github.shutil.which", return_value=None,+ ), patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener, patch.object(+ adapters, "_load_packaged_catalog",+ ) as snapshot, pytest.raises(BundlerError, match="was not found") as exc_info:+ adapters.make_catalog_fetcher(allow_network=True)(source)++ assert not isinstance(exc_info.value, adapters._CatalogUnavailable)+ snapshot.assert_not_called()+ build_opener.assert_not_called()++ def test_bundle_reference_auth_failure_is_not_left_unchecked(self, tmp_path):+ from types import SimpleNamespace+ from unittest.mock import patch+ from specify_cli.bundles.manifest import ComponentRef+ from specify_cli.bundles.references import make_reference_checker+ from specify_cli.extensions import ExtensionCatalog++ source = SimpleNamespace(+ name="private", install_allowed=True,+ url="https://github.com/org/repo/catalog.json",+ )+ warnings = []+ with patch.object(+ ExtensionCatalog, "get_active_catalogs", return_value=[source],+ ), patch(+ "specify_cli.authentication.github.shutil.which", return_value=None,+ ), patch(+ "specify_cli.authentication.http.urllib.request.build_opener",+ ) as build_opener:+ check = make_reference_checker(tmp_path, allow_network=True, warnings=warnings)+ problem = check(ComponentRef(+ kind="extensions", id="private-extension", version="1.0.0", source="private",+ ))++ assert problem is not None+ assert "GitHub CLI ('gh') was not found" in problem+ assert warnings == []+ build_opener.assert_not_called()++# ---------------------------------------------------------------------------# _load_config caching# ---------------------------------------------------------------------------