lupaxa-github-token-validator 0.1.0__py3-none-any.whl

lupaxa/github_token_validator/__init__.py

@@ -0,0 +1,7 @@
+"""Report what a GitHub token is allowed to do."""
+
+from __future__ import annotations
+
+from lupaxa.github_token_validator.cli import main
+
+__all__ = ["main"]

lupaxa/github_token_validator/__main__.py

@@ -0,0 +1,8 @@
+"""python -m lupaxa.github_token_validator."""
+
+from __future__ import annotations
+
+from lupaxa.github_token_validator.cli import main
+
+if __name__ == "__main__":
+    main()

lupaxa/github_token_validator/classify.py

@@ -0,0 +1,52 @@
+"""Classify a GitHub token from its prefix."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+PermissionSource = Literal["oauth", "accepted", "fine_grained"]
+
+
+@dataclass(frozen=True, slots=True)
+class TokenKind:
+    """Prefix classification decided before any API call."""
+
+    label: str
+    calls_api: bool
+    requires_target: bool
+    checks_account: bool
+    permission_source: PermissionSource
+
+
+_UNKNOWN = TokenKind("Unknown", True, True, True, "oauth")
+
+_PREFIXES: tuple[tuple[str, TokenKind], ...] = (
+    (
+        "github_pat_",
+        TokenKind(
+            "Fine-grained personal access token", True, True, True, "fine_grained"
+        ),
+    ),
+    ("ghp_", TokenKind("Classic personal access token", True, False, True, "oauth")),
+    ("gho_", TokenKind("OAuth access token", True, False, True, "oauth")),
+    (
+        "ghu_",
+        TokenKind("GitHub App user-to-server token", True, False, True, "oauth"),
+    ),
+    (
+        "ghs_",
+        TokenKind(
+            "GitHub App installation or Actions token", True, True, False, "accepted"
+        ),
+    ),
+    ("ghr_", TokenKind("Refresh token", False, False, False, "oauth")),
+)
+
+
+def classify_token(token: str) -> TokenKind:
+    """Return the kind for ``token`` from the first matching prefix."""
+    for prefix, kind in _PREFIXES:
+        if token.startswith(prefix):
+            return kind
+    return _UNKNOWN

lupaxa/github_token_validator/cli.py

@@ -0,0 +1,150 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Mapping, Sequence
+import os
+import sys
+from typing import NoReturn
+
+from lupaxa.github_token_validator.classify import classify_token
+from lupaxa.github_token_validator.client import GitHubClient, RequestsGitHubClient
+from lupaxa.github_token_validator.constants import (
+    DEFAULT_TIMEOUT,
+    EXIT_INTERRUPTED,
+    EXIT_USAGE,
+    PROGRAM_NAME,
+    PROGRAM_VERSION_STRING,
+)
+from lupaxa.github_token_validator.probes import run_validation
+from lupaxa.github_token_validator.report import render_report
+
+
+def default_client_factory(token: str, timeout: int) -> GitHubClient:
+    """Build the requests client."""
+    return RequestsGitHubClient(token, timeout)
+
+
+def main(
+    argv: Sequence[str] | None = None,
+    *,
+    client_factory: Callable[[str, int], GitHubClient] = default_client_factory,
+) -> None:
+    """Parse arguments, run probes, and exit."""
+    try:
+        code = execute(argv, client_factory, os.environ)
+    except KeyboardInterrupt:
+        print("Interrupted.", file=sys.stderr)
+        code = EXIT_INTERRUPTED
+    raise SystemExit(code)
+
+
+def execute(
+    argv: Sequence[str] | None,
+    client_factory: Callable[[str, int], GitHubClient],
+    environ: Mapping[str, str],
+) -> int:
+    """Return the process exit code."""
+    args = _parser().parse_args(None if argv is None else list(argv))
+    token = _token(args.token, environ)
+    if token is None:
+        print(
+            "A token is required. Pass --token or set GITHUB_TOKEN.",
+            file=sys.stderr,
+        )
+        return EXIT_USAGE
+    org = None if args.org is None else args.org.strip()
+    if args.org is not None and org == "":
+        print("--org must not be blank.", file=sys.stderr)
+        return EXIT_USAGE
+    if org is not None and not _single_name(org):
+        print("--org must be a single name.", file=sys.stderr)
+        return EXIT_USAGE
+    kind = classify_token(token)
+    if kind.requires_target and org is None and args.repo is None:
+        print(f"{kind.label} requires --org or --repo.", file=sys.stderr)
+        return EXIT_USAGE
+    client = client_factory(token, args.timeout) if kind.calls_api else None
+    try:
+        report = run_validation(kind=kind, org=org, repo=args.repo, client=client)
+        render_report(report)
+        return report.exit_code
+    finally:
+        _close(client)
+
+
+class _Parser(argparse.ArgumentParser):
+    """Argument errors never echo the values the user passed."""
+
+    def error(self, message: str) -> NoReturn:
+        """Print a usage error and exit 2."""
+        if message.startswith("unrecognized arguments:"):
+            message = "unrecognized arguments."
+        self.print_usage(sys.stderr)
+        print(f"{self.prog}: error: {message}", file=sys.stderr)
+        self.exit(2)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = _Parser(
+        prog=PROGRAM_NAME,
+        description="Report what a GitHub token is allowed to do.",
+    )
+    parser.add_argument(
+        "-V", "--version", action="version", version=PROGRAM_VERSION_STRING
+    )
+    parser.add_argument("-t", "--token", default=None)
+    parser.add_argument("-T", "--timeout", type=_positive_int, default=DEFAULT_TIMEOUT)
+    parser.add_argument(
+        "--org",
+        default=None,
+        help=(
+            "Organisation to check. Required for fine-grained, installation, "
+            "and unknown tokens unless --repo is set"
+        ),
+    )
+    parser.add_argument(
+        "--repo",
+        type=_repo,
+        default=None,
+        help=(
+            "Repository to check as OWNER/NAME. Required for fine-grained, "
+            "installation, and unknown tokens unless --org is set"
+        ),
+    )
+    return parser
+
+
+def _positive_int(value: str) -> int:
+    if not value.isdigit() or int(value) <= 0:
+        raise argparse.ArgumentTypeError("--timeout must be an integer greater than 0.")
+    return int(value)
+
+
+def _single_name(value: str) -> bool:
+    return "/" not in value and not any(character.isspace() for character in value)
+
+
+def _repo(value: str) -> tuple[str, str]:
+    owner, separator, name = value.partition("/")
+    invalid = separator != "/" or "/" in name or owner == "" or name == ""
+    if invalid or any(character.isspace() for character in owner + name):
+        raise argparse.ArgumentTypeError("--repo must be OWNER/NAME.")
+    return owner, name
+
+
+def _close(client: GitHubClient | None) -> None:
+    close = getattr(client, "close", None)
+    if callable(close):
+        close()
+
+
+def _token(flag: str | None, environ: Mapping[str, str]) -> str | None:
+    raw = flag if flag is not None else environ.get("GITHUB_TOKEN")
+    if raw is None:
+        return None
+    token = raw.strip()
+    if token == "":
+        return None
+    return token

lupaxa/github_token_validator/client.py

@@ -0,0 +1,131 @@
+"""Read-only GitHub GET client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Protocol
+
+import requests
+from requests import Session
+
+from lupaxa.github_token_validator.constants import (
+    API_BASE_URL,
+    API_VERSION,
+    USER_AGENT,
+)
+
+
+class GitHubUnauthorizedError(Exception):
+    """GitHub returned HTTP 401."""
+
+
+class GitHubRateLimitError(Exception):
+    """GitHub returned HTTP 429."""
+
+
+class GitHubTransportError(Exception):
+    """The request timed out or the connection failed."""
+
+
+@dataclass(frozen=True, slots=True)
+class GitHubResponse:
+    """Status, headers, and the optional login from GET /user."""
+
+    status_code: int
+    headers: dict[str, str]
+    login: str | None
+
+
+class GitHubClient(Protocol):
+    """Injectable GET client used by the probe runner."""
+
+    def get(self, path: str, *, read_login: bool = False) -> GitHubResponse:
+        """Perform one GET and return status data."""
+        raise NotImplementedError
+
+
+class RequestsGitHubClient:
+    """requests-backed client. The token is sent only as a Bearer header."""
+
+    def __init__(
+        self, token: str, timeout: int, session: Session | None = None
+    ) -> None:
+        """Store the token, timeout, and session."""
+        self._token = token
+        self._timeout = timeout
+        self._owns_session = session is None
+        self._session = requests.Session() if session is None else session
+
+    def close(self) -> None:
+        """Close the session this client created."""
+        if self._owns_session:
+            self._session.close()
+
+    def get(self, path: str, *, read_login: bool = False) -> GitHubResponse:
+        """GET ``path`` and discard the body unless ``read_login`` is set."""
+        try:
+            response = self._session.get(
+                f"{API_BASE_URL}{path}",
+                headers={
+                    "Authorization": f"Bearer {self._token}",
+                    "Accept": "application/vnd.github+json",
+                    "X-GitHub-Api-Version": API_VERSION,
+                    "User-Agent": USER_AGENT,
+                },
+                timeout=self._timeout,
+            )
+        except requests.Timeout:
+            raise GitHubTransportError("GitHub request timed out.") from None
+        except requests.ConnectionError:
+            raise GitHubTransportError(
+                "GitHub request failed: connection error."
+            ) from None
+        except requests.RequestException:
+            raise GitHubTransportError("GitHub request failed.") from None
+        if response.status_code == 401:
+            raise GitHubUnauthorizedError("GitHub rejected the token (HTTP 401).")
+        if _rate_limited(response.status_code, response.headers):
+            raise GitHubRateLimitError(
+                f"GitHub rate limit exceeded (HTTP {response.status_code})."
+            )
+        return GitHubResponse(
+            response.status_code,
+            {str(key): str(value) for key, value in response.headers.items()},
+            _login(response) if read_login else None,
+        )
+
+
+def _rate_limited(status_code: int, headers: Mapping[str, str]) -> bool:
+    """Return whether this response is a primary or secondary rate limit."""
+    if status_code == 429:
+        return True
+    if status_code != 403:
+        return False
+    remaining = _header(headers, "X-RateLimit-Remaining")
+    if remaining == "0":
+        return True
+    return _header(headers, "Retry-After") is not None
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    """Return one header, ignoring case and blank text."""
+    wanted = name.lower()
+    for key, value in headers.items():
+        text = str(value).strip()
+        if key.lower() == wanted and text != "":
+            return text
+    return None
+
+
+def _login(response: requests.Response) -> str | None:
+    try:
+        payload: object = response.json()
+    except ValueError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+    value = payload.get("login")
+    if isinstance(value, str) and value.strip() != "":
+        return value
+    return None

lupaxa/github_token_validator/constants.py

@@ -0,0 +1,37 @@
+"""Stable names, version, API constants, and exit codes."""
+
+from __future__ import annotations
+
+from typing import Final
+
+__all__ = [
+    "API_BASE_URL",
+    "API_VERSION",
+    "DEFAULT_TIMEOUT",
+    "EXIT_FAILURE",
+    "EXIT_INTERRUPTED",
+    "EXIT_SUCCESS",
+    "EXIT_USAGE",
+    "PROGRAM_ALIAS",
+    "PROGRAM_NAME",
+    "PROGRAM_VERSION",
+    "PROGRAM_VERSION_STRING",
+    "PROJECT_NAME",
+    "USER_AGENT",
+]
+
+PROGRAM_NAME: Final[str] = "github-token-validator"
+PROGRAM_ALIAS: Final[str] = "gtv"
+PROJECT_NAME: Final[str] = "lupaxa-github-token-validator"
+PROGRAM_VERSION: Final[str] = "0.1.0"
+PROGRAM_VERSION_STRING: Final[str] = f"{PROGRAM_NAME} v{PROGRAM_VERSION}"
+
+API_BASE_URL: Final[str] = "https://api.github.com"
+API_VERSION: Final[str] = "2022-11-28"
+USER_AGENT: Final[str] = "lupaxa-github-token-validator"
+DEFAULT_TIMEOUT: Final[int] = 10
+
+EXIT_SUCCESS: Final[int] = 0
+EXIT_FAILURE: Final[int] = 1
+EXIT_USAGE: Final[int] = 2
+EXIT_INTERRUPTED: Final[int] = 130