Improve OAuth diagnostics and bump version to 0.1.24

Include offending values in OAuthResourceMetadata validation errors and
add diagnostic logging for JWT claim mismatches on authentication failure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rustyconover

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-rpc"
-version = "0.1.23"
+version = "0.1.24"
 description = "Vector Gateway Interface - RPC framework based on Apache Arrow"
 readme = "README.md"
 requires-python = ">=3.13"

uv.lock

@@ -86,23 +86,23 @@ def __post_init__(self) -> None:
             raise ValueError("OAuthResourceMetadata.authorization_servers must contain at least one entry")
         if self.client_id is not None and not _URL_SAFE_RE.fullmatch(self.client_id):
             raise ValueError(
-                "OAuthResourceMetadata.client_id must contain only URL-safe characters "
-                "(alphanumeric, hyphen, underscore, period, tilde)"
+                f"OAuthResourceMetadata.client_id must contain only URL-safe characters "
+                f"(alphanumeric, hyphen, underscore, period, tilde), got: {self.client_id!r}"
             )
         if self.client_secret is not None and not _URL_SAFE_RE.fullmatch(self.client_secret):
             raise ValueError(
-                "OAuthResourceMetadata.client_secret must contain only URL-safe characters "
-                "(alphanumeric, hyphen, underscore, period, tilde)"
+                f"OAuthResourceMetadata.client_secret must contain only URL-safe characters "
+                f"(alphanumeric, hyphen, underscore, period, tilde), got: {self.client_secret!r}"
             )
         if self.device_code_client_id is not None and not _URL_SAFE_RE.fullmatch(self.device_code_client_id):
             raise ValueError(
-                "OAuthResourceMetadata.device_code_client_id must contain only URL-safe characters "
-                "(alphanumeric, hyphen, underscore, period, tilde)"
+                f"OAuthResourceMetadata.device_code_client_id must contain only URL-safe characters "
+                f"(alphanumeric, hyphen, underscore, period, tilde), got: {self.device_code_client_id!r}"
             )
         if self.device_code_client_secret is not None and not _URL_SAFE_RE.fullmatch(self.device_code_client_secret):
             raise ValueError(
-                "OAuthResourceMetadata.device_code_client_secret must contain only URL-safe characters "
-                "(alphanumeric, hyphen, underscore, period, tilde)"
+                f"OAuthResourceMetadata.device_code_client_secret must contain only URL-safe characters "
+                f"(alphanumeric, hyphen, underscore, period, tilde), got: {self.device_code_client_secret!r}"
             )
 
     def to_json_dict(self) -> dict[str, object]:

vgi_rpc/http/_oauth.py

@@ -12,10 +12,13 @@
 
 from __future__ import annotations
 
+import logging
 import threading
 from collections.abc import Callable, Mapping
 from typing import Any
 
+logger = logging.getLogger(__name__)
+
 import falcon
 import httpx
 
@@ -105,6 +108,28 @@ def _get_key_set(force_refresh: bool = False) -> _KeySet:
     if claims_options:
         base_claims_options.update(claims_options)
 
+    def _log_claim_mismatch(token: str, keys: _KeySet, exc: JoseError) -> None:
+        """Log expected vs actual claims on JWT validation failure."""
+        try:
+            # Decode without validation to inspect the payload
+            raw_claims = jwt.decode(token, keys)
+            token_aud = raw_claims.get("aud")
+            token_iss = raw_claims.get("iss")
+            logger.warning(
+                "JWT validation failed: %s\n"
+                "  expected iss: %s\n"
+                "  token   iss: %s\n"
+                "  expected aud (any of): %s\n"
+                "  token   aud: %s",
+                exc,
+                issuer,
+                token_iss,
+                list(audiences),
+                token_aud,
+            )
+        except Exception:
+            logger.warning("JWT validation failed: %s (could not decode token for diagnostics)", exc)
+
     def authenticate(req: falcon.Request) -> AuthContext:
         auth_header = req.get_header("Authorization") or ""
         if not auth_header.startswith("Bearer "):
@@ -123,9 +148,11 @@ def authenticate(req: falcon.Request) -> AuthContext:
                 claims = jwt.decode(token, keys, claims_options=base_claims_options)
                 claims.validate()
             except JoseError as exc:
+                _log_claim_mismatch(token, keys, exc)
                 raise ValueError(f"Invalid JWT: {exc}") from exc
         except JoseError as exc:
             # Expired tokens, bad claims, etc. — no point refreshing keys
+            _log_claim_mismatch(token, keys, exc)
             raise ValueError(f"Invalid JWT: {exc}") from exc
 
         principal = str(claims.get(principal_claim, ""))