feat: cache auth check api calls

`check_client_api_key` hits `/v1/metadata` and `/v1/api_tokens/self` on every invocation. When a caller runs bursty scans — notably the VSCode extension, which rescans on every save — this is two API round-trips per scan even though the key state rarely changes between them. This commit introduces a cache for auth calls.

Author: Kevin Westphal

changelog.d/20260423_145903_6d7a_cache_api_calls.md

@@ -0,0 +1,3 @@
+### Changed
+
+- Successful API key checks are now cached on disk for 5 minutes.

ggshield/core/auth_check_cache.py

@@ -0,0 +1,97 @@
+import hashlib
+import logging
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import yaml
+from pygitguardian.models import TokenScope
+
+from ggshield.core.config.utils import load_yaml_dict, save_yaml_dict
+from ggshield.core.dirs import get_cache_dir
+from ggshield.core.errors import UnexpectedError
+
+
+logger = logging.getLogger(__name__)
+
+# How long a successful auth check (metadata + token scopes) stays valid.
+# Short enough that revoked tokens and scope changes propagate quickly;
+# long enough that a burst of scans (e.g. IDE on-save) shares one check.
+TTL_SECONDS = 300
+
+
+def _cache_file() -> Path:
+    # Resolved lazily so GG_CACHE_DIR overrides (tests, sandboxed envs) are honored.
+    return get_cache_dir() / "auth_check.yaml"
+
+
+@dataclass
+class CachedAuthCheck:
+    # The API key has been verified against /v1/metadata and is usable.
+    metadata_verified: bool
+    # If not None, these are the scopes fetched from /v1/api_tokens/self.
+    # None means we haven't fetched scopes yet (e.g. from an auth-login flow
+    # where no specific scopes were required).
+    scopes: Optional[set[TokenScope]]
+
+
+def _key_hash(instance_url: str, api_key: str) -> str:
+    return hashlib.sha256(f"{instance_url}\0{api_key}".encode("utf-8")).hexdigest()[:16]
+
+
+def load(instance_url: str, api_key: str) -> Optional[CachedAuthCheck]:
+    """Return the cached auth check for this (instance, key) pair, or None on miss."""
+    try:
+        data = load_yaml_dict(_cache_file())
+    except (OSError, ValueError, yaml.YAMLError) as e:
+        logger.warning("Could not load auth check cache: %s", repr(e))
+        return None
+
+    if not data:
+        return None
+    if data.get("key_hash") != _key_hash(instance_url, api_key):
+        return None
+    if data.get("expires_at", 0) < time.time():
+        return None
+
+    raw_scopes = data.get("scopes")
+    scopes: Optional[set[TokenScope]]
+    if raw_scopes is None:
+        scopes = None
+    else:
+        scopes = set()
+        for scope_str in raw_scopes:
+            try:
+                scopes.add(TokenScope(scope_str))
+            except ValueError:
+                logger.debug("Ignoring unknown cached scope: '%s'", scope_str)
+
+    return CachedAuthCheck(metadata_verified=True, scopes=scopes)
+
+
+def store(instance_url: str, api_key: str, scopes: Optional[set[TokenScope]]) -> None:
+    """Record a successful auth check.
+
+    Pass scopes=None if token scopes were not fetched (only metadata was checked).
+    """
+    try:
+        save_yaml_dict(
+            {
+                "key_hash": _key_hash(instance_url, api_key),
+                "scopes": (None if scopes is None else sorted(s.value for s in scopes)),
+                "expires_at": int(time.time()) + TTL_SECONDS,
+            },
+            _cache_file(),
+            restricted=True,
+        )
+    except (OSError, UnexpectedError) as e:
+        logger.warning("Could not save auth check cache: %s", repr(e))
+
+
+def invalidate() -> None:
+    """Drop the cached auth check, typically after a 401 from any API call."""
+    try:
+        _cache_file().unlink(missing_ok=True)
+    except OSError as e:
+        logger.warning("Could not invalidate auth check cache: %s", repr(e))

ggshield/core/client.py

@@ -9,7 +9,7 @@
 from requests import Session
 from requests.adapters import HTTPAdapter
 
-from . import ui
+from . import auth_check_cache, ui
 from .config import Config
 from .constants import DEFAULT_INSTANCE_URL
 from .errors import (
@@ -117,32 +117,50 @@ def check_client_api_key(client: GGClient, required_scopes: set[TokenScope]) ->
     (either it is invalid or unset). Raises UnexpectedError if the API is down.
 
     If required_scopes is not empty, also checks that the API key has the required scopes.
+
+    Successful checks are cached on disk for a short TTL so bursty callers (e.g. the
+    GitGuardian VSCode extension) do not re-hit /v1/metadata and
+    /v1/api_tokens/self on every invocation.
     """
-    try:
-        response = client.read_metadata()
-    except requests.exceptions.ConnectionError as e:
-        raise UnexpectedError(
-            "Failed to connect to GitGuardian server. Check your"
-            f" instance URL settings.\nDetails: {e}."
-        )
+    cached = auth_check_cache.load(client.base_uri, client.api_key)
+    if cached is not None and (
+        not required_scopes
+        or (cached.scopes is not None and required_scopes <= cached.scopes)
+    ):
+        return
+
+    # The cache either missed or does not prove the scopes we need. We still get to
+    # skip /v1/metadata when the cache told us the key was recently verified.
+    if cached is None or not cached.metadata_verified:
+        try:
+            response = client.read_metadata()
+        except requests.exceptions.ConnectionError as e:
+            raise UnexpectedError(
+                "Failed to connect to GitGuardian server. Check your"
+                f" instance URL settings.\nDetails: {e}."
+            )
 
-    if response is None:
-        # None means success
-        pass
-    elif response.status_code == 401:
-        raise APIKeyCheckError(client.base_uri, "Invalid GitGuardian API key.")
-    elif response.status_code == 404:
-        raise UnexpectedError(
-            "The server returned a 404 error. Check your instance URL settings.",
-        )
-    elif response.status_code is not None and 500 <= response.status_code < 600:
-        raise ServiceUnavailableError(
-            message=f"GitGuardian server is not responding.\nDetails: {response.detail}",
-        )
-    else:
-        raise UnexpectedError(
-            f"GitGuardian server is not responding as expected.\nDetails: {response.detail}"
-        )
+        if response is None:
+            # None means success
+            pass
+        elif response.status_code == 401:
+            raise APIKeyCheckError(client.base_uri, "Invalid GitGuardian API key.")
+        elif response.status_code == 404:
+            raise UnexpectedError(
+                "The server returned a 404 error. Check your instance URL settings.",
+            )
+        elif response.status_code is not None and 500 <= response.status_code < 600:
+            raise ServiceUnavailableError(
+                message=f"GitGuardian server is not responding.\nDetails: {response.detail}",
+            )
+        else:
+            raise UnexpectedError(
+                f"GitGuardian server is not responding as expected.\nDetails: {response.detail}"
+            )
+
+    api_scopes: Optional[set[TokenScope]] = (
+        cached.scopes if cached is not None else None
+    )
 
     # Check token scopes if required_scopes is not empty
     if required_scopes:
@@ -164,3 +182,5 @@ def check_client_api_key(client: GGClient, required_scopes: set[TokenScope]) ->
         missing_scopes = required_scopes - api_scopes
         if missing_scopes:
             raise MissingScopesError(list(missing_scopes))
+
+    auth_check_cache.store(client.base_uri, client.api_key, api_scopes)

ggshield/core/errors.py

@@ -213,6 +213,11 @@ def handle_api_error(detail: Detail) -> None:
     logger.error("status_code=%s", detail.status_code)
     logger.debug("detail=%s", detail.detail)
     if detail.status_code == 401:
+        # The cached metadata/scopes check must not keep masking a revoked
+        # or rotated API key within its TTL.
+        from ggshield.core import auth_check_cache
+
+        auth_check_cache.invalidate()
         raise click.UsageError(detail.detail)
     if detail.status_code is None:
         raise UnexpectedError(f"Scanning failed: {detail.detail}")