clue2app-cli 0.2.7__py3-none-any.whl

clue2app_cli/creds_module.py

@@ -0,0 +1,253 @@
+"""Git credential management for kpack-backed apps.
+
+Background: every kpack `Image` resource references a `kubernetes.io/basic-auth`
+secret with `username` + `password` (a GitHub PAT or `gho_*` OAuth token).
+When those tokens expire — and `gho_*` ones in particular do silently — the
+next git poll fails with no clear surface in the platform UI. The app stays
+on its last successful build for weeks or months. The user only finds out
+when they push to main and notice their app didn't update.
+
+This module provides:
+
+  - `c2a creds rotate <secret> [--namespace NS]` — interactive (or `--token`
+    flag, or `--from-gh` to grab from the local `gh` CLI's authed token).
+    Updates ONLY the `password` field of the named secret.
+  - `c2a creds check [--all-namespaces]` — read-only scan that finds all
+    kpack `Image` resources, reads each one's referenced git secret, probes
+    GitHub with the embedded PAT, and reports which ones are dead.
+
+These are the "supportable" surface that lets a user (or a future agent)
+recover from a stuck-build state without dropping to kubectl.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Low-level helpers (no Click dependency — keeps these unit-testable)
+# ---------------------------------------------------------------------------
+
+
+def _kubectl(args: list[str], *, capture: bool = True) -> subprocess.CompletedProcess:
+    """Shell out to kubectl. Returns the CompletedProcess so callers can
+    decide how to surface stderr."""
+    return subprocess.run(
+        ["kubectl", *args],
+        capture_output=capture,
+        text=True,
+        timeout=60,
+    )
+
+
+def get_gh_token() -> Optional[str]:
+    """Return the local `gh` CLI's active token, or None if gh is not
+    installed/authed. Surface but don't crash on failure."""
+    if shutil.which("gh") is None:
+        return None
+    try:
+        r = subprocess.run(
+            ["gh", "auth", "token"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if r.returncode != 0:
+            return None
+        token = r.stdout.strip()
+        return token or None
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def rotate_password_secret(secret_name: str, namespace: str, new_password: str) -> tuple[bool, str]:
+    """Update the `password` field of a kubernetes.io/basic-auth secret.
+
+    Returns `(ok, message)`. Does NOT touch the `username` field — most
+    kpack basic-auth secrets have `username=git` or a real GitHub username
+    that doesn't change when the PAT rotates.
+    """
+    if not new_password:
+        return False, "refused to write an empty password"
+    b64 = base64.b64encode(new_password.encode("utf-8")).decode("ascii")
+    patch = json.dumps({"data": {"password": b64}})
+    r = _kubectl(
+        ["patch", "secret", secret_name, "-n", namespace, "--type=merge", "-p", patch],
+    )
+    if r.returncode != 0:
+        return False, (r.stderr or r.stdout).strip()
+    return True, (r.stdout or r.stderr).strip()
+
+
+def trigger_kpack_rebuild(image_name: str, namespace: str) -> tuple[bool, str]:
+    """Annotate a kpack Image with `kpack.io/rebuild=<RFC3339-now>` to
+    force a fresh build. Idempotent — kpack picks up the new annotation
+    timestamp and runs build N+1 on the next reconcile loop."""
+    import datetime
+
+    ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    r = _kubectl([
+        "annotate", "image.kpack.io", image_name, "-n", namespace,
+        f"kpack.io/rebuild={ts}", "--overwrite",
+    ])
+    if r.returncode != 0:
+        return False, (r.stderr or r.stdout).strip()
+    return True, ts
+
+
+# ---------------------------------------------------------------------------
+# Cred liveness probe (read-only — no writes)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CredStatus:
+    """Result of probing one git secret's PAT against GitHub.
+
+    `alive`: bool — token authenticated successfully against GitHub.
+    `reason`: short tag for grouping (e.g. "ok", "401-unauthorized",
+              "saml-required", "no-password", "unreachable").
+    `detail`: human-readable extra info (which scope was missing, etc.).
+    """
+
+    alive: bool
+    reason: str
+    detail: str = ""
+
+
+def probe_github_pat(token: str, *, timeout_s: float = 10.0) -> CredStatus:
+    """Hit `GET https://api.github.com/user` with the token. 200 means the
+    token is valid AND has at least basic identity scope. 401 means
+    expired/revoked. 403 with `X-GitHub-SSO` header means the org needs
+    SAML SSO authorization for this token (the most common 'silent break'
+    in clue2solve's setup)."""
+    import urllib.error
+    import urllib.request
+
+    if not token:
+        return CredStatus(False, "no-password", "secret has no password value")
+
+    req = urllib.request.Request(
+        "https://api.github.com/user",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "c2a-creds-check/1.0",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as r:
+            if r.status == 200:
+                return CredStatus(True, "ok")
+            return CredStatus(False, f"unexpected-{r.status}", "")
+    except urllib.error.HTTPError as e:
+        if e.code == 401:
+            return CredStatus(False, "401-unauthorized", "token expired or revoked")
+        if e.code == 403:
+            # GitHub uses 403 + the X-GitHub-SSO header to indicate
+            # SAML-SSO authorization is missing for the org.
+            sso = e.headers.get("X-GitHub-SSO") if e.headers else None
+            if sso:
+                return CredStatus(False, "saml-required", f"X-GitHub-SSO: {sso}")
+            return CredStatus(False, "403-forbidden", "")
+        return CredStatus(False, f"http-{e.code}", "")
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        return CredStatus(False, "unreachable", str(e))
+
+
+# ---------------------------------------------------------------------------
+# Cluster discovery — find all kpack Image -> git secret references
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class KpackImageGitRef:
+    namespace: str
+    image_name: str          # the kpack Image resource name
+    git_url: str
+    git_revision: str
+    service_account: str
+    git_secret_name: str     # discovered via the SA's secrets list
+
+
+def list_kpack_image_git_refs(*, all_namespaces: bool = True, namespace: Optional[str] = None) -> list[KpackImageGitRef]:
+    """Walk every kpack `Image` in scope, follow its serviceAccountName to
+    find the attached `kubernetes.io/basic-auth` secret. Returns one ref per
+    Image; secrets referenced by multiple Images appear once per Image."""
+    args = ["get", "image.kpack.io", "-o", "json"]
+    if all_namespaces:
+        args.insert(0 + 1, "-A")  # `get image.kpack.io -A -o json`
+    elif namespace:
+        args += ["-n", namespace]
+    r = _kubectl(args)
+    if r.returncode != 0:
+        raise RuntimeError(f"kubectl get image.kpack.io failed: {r.stderr or r.stdout}")
+    try:
+        doc = json.loads(r.stdout)
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"non-JSON kubectl output: {e}") from e
+
+    refs: list[KpackImageGitRef] = []
+    for item in doc.get("items", []):
+        md = item.get("metadata", {})
+        ns = md.get("namespace", "")
+        image_name = md.get("name", "")
+        sa = item.get("spec", {}).get("serviceAccountName", "")
+        git = item.get("spec", {}).get("source", {}).get("git", {})
+        url = git.get("url", "")
+        rev = git.get("revision", "")
+
+        secret_name = _resolve_basic_auth_secret(ns, sa) if sa else ""
+        refs.append(KpackImageGitRef(
+            namespace=ns,
+            image_name=image_name,
+            git_url=url,
+            git_revision=rev,
+            service_account=sa,
+            git_secret_name=secret_name,
+        ))
+    return refs
+
+
+def _resolve_basic_auth_secret(namespace: str, service_account: str) -> str:
+    """Inspect a ServiceAccount and return the name of the first
+    `kubernetes.io/basic-auth` secret it references, or "" if none."""
+    r = _kubectl([
+        "get", "sa", service_account, "-n", namespace, "-o", "json",
+    ])
+    if r.returncode != 0:
+        return ""
+    try:
+        doc = json.loads(r.stdout)
+    except json.JSONDecodeError:
+        return ""
+    for sec_ref in doc.get("secrets", []):
+        sec_name = sec_ref.get("name", "")
+        if not sec_name:
+            continue
+        # Check the secret's type — only basic-auth ones hold git PATs.
+        r2 = _kubectl(["get", "secret", sec_name, "-n", namespace,
+                       "-o", "jsonpath={.type}"])
+        if r2.returncode == 0 and r2.stdout.strip() == "kubernetes.io/basic-auth":
+            return sec_name
+    return ""
+
+
+def read_secret_password(secret_name: str, namespace: str) -> Optional[str]:
+    """Decode the `password` field of a secret. Returns None if the secret
+    or field is missing."""
+    r = _kubectl([
+        "get", "secret", secret_name, "-n", namespace,
+        "-o", "jsonpath={.data.password}",
+    ])
+    if r.returncode != 0 or not r.stdout.strip():
+        return None
+    try:
+        return base64.b64decode(r.stdout.strip()).decode("utf-8", errors="replace")
+    except (ValueError, base64.binascii.Error):
+        return None