Add FFI binding for OAuthClient C API (#6)

RahulHere · dIvYaNshhh · commit 651707ffbfbf · 2026-04-24T11:37:14.000+05:30
Create ctypes bindings for gopher_auth_oauth_* functions providing
GopherOAuthClient class for token exchange, refresh, RFC 8693 token
exchange, and RFC 7591 dynamic client registration.

In loader.py:
- Bind 16 OAuthClient functions + 8 SessionManager + 1 auto-refresh
  + 3 validation + 2 URL + 3 metadata + 3 HTTP parsing (all specs
  added for future prompts)
- Add to _FUNCTION_SPECS and get_auth_functions() dict

New oauth_client.py:
- TokenResponse and RegistrationResponse dataclasses
- GopherOAuthClient class with handle-based lifecycle
- exchange_code(), refresh_token(), token_exchange(), register_client()
- Each method reads response via accessors then destroys handle
- Context manager support
diff --git a/gopher_mcp_python/ffi/auth/__init__.py b/gopher_mcp_python/ffi/auth/__init__.py
@@ -37,6 +37,12 @@
     GopherAuthConfig,
 )
 
+from gopher_mcp_python.ffi.auth.oauth_client import (
+    GopherOAuthClient,
+    TokenResponse,
+    RegistrationResponse,
+)
+
 from gopher_mcp_python.ffi.auth.auth_client import (
     GopherAuthClient,
     gopher_init_auth_library,
diff --git a/gopher_mcp_python/ffi/auth/loader.py b/gopher_mcp_python/ffi/auth/loader.py
@@ -270,6 +270,49 @@ def get_library() -> Optional[ctypes.CDLL]:
     ("gopher_auth_config_get_int", [c_void_p, c_char_p, POINTER(c_int)], c_int32),
     ("gopher_auth_config_get_bool", [c_void_p, c_char_p, POINTER(c_bool)], c_int32),
     ("gopher_auth_config_get_exchange_idps", [c_void_p, POINTER(c_char_p)], c_int32),
+    # OAuthClient
+    ("gopher_auth_oauth_client_create", [POINTER(c_void_p), c_char_p, c_char_p, c_char_p, c_int], c_int32),
+    ("gopher_auth_oauth_client_destroy", [c_void_p], c_int32),
+    ("gopher_auth_oauth_exchange_code", [c_void_p, c_char_p, c_char_p, c_char_p, POINTER(c_void_p)], c_int32),
+    ("gopher_auth_oauth_refresh_token", [c_void_p, c_char_p, POINTER(c_void_p)], c_int32),
+    ("gopher_auth_oauth_token_exchange", [c_void_p, c_char_p, c_char_p, c_char_p, c_char_p, POINTER(c_void_p)], c_int32),
+    ("gopher_auth_oauth_register_client", [c_void_p, c_char_p, c_char_p, POINTER(c_char_p), c_int, c_char_p, POINTER(c_void_p)], c_int32),
+    ("gopher_auth_token_response_get_access_token", [c_void_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_token_response_get_refresh_token", [c_void_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_token_response_get_expires_in", [c_void_p, POINTER(c_int64)], c_int32),
+    ("gopher_auth_token_response_get_error", [c_void_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_token_response_is_success", [c_void_p], c_bool),
+    ("gopher_auth_token_response_destroy", [c_void_p], c_int32),
+    ("gopher_auth_registration_response_get_client_id", [c_void_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_registration_response_get_client_secret", [c_void_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_registration_response_is_success", [c_void_p], c_bool),
+    ("gopher_auth_registration_response_destroy", [c_void_p], c_int32),
+    # SessionManager
+    ("gopher_auth_session_manager_create", [POINTER(c_void_p), c_int], c_int32),
+    ("gopher_auth_session_manager_destroy", [c_void_p], c_int32),
+    ("gopher_auth_session_store_token", [c_void_p, c_char_p, c_char_p, c_char_p, c_int64], c_int32),
+    ("gopher_auth_session_get_access_token", [c_void_p, c_char_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_session_get_refresh_token", [c_void_p, c_char_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_session_has_valid_token", [c_void_p, c_char_p, POINTER(c_bool)], c_int32),
+    ("gopher_auth_session_cleanup", [c_void_p], c_int32),
+    ("gopher_auth_session_generate_id", [POINTER(c_char_p)], c_int32),
+    # Auto-Refresh
+    ("gopher_auth_auto_refresh", [c_void_p, c_void_p, c_void_p, c_char_p, POINTER(c_char_p), POINTER(GopherAuthValidationResult)], c_int32),
+    # Validation
+    ("gopher_auth_validate_idp", [c_char_p, c_char_p, POINTER(c_bool)], c_int32),
+    ("gopher_auth_validate_all_scopes", [c_char_p, c_char_p, POINTER(c_bool)], c_int32),
+    ("gopher_auth_validate_any_scopes", [c_char_p, c_char_p, POINTER(c_bool)], c_int32),
+    # URL Utils
+    ("gopher_auth_url_encode", [c_char_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_url_decode", [c_char_p, POINTER(c_char_p)], c_int32),
+    # Metadata Builders
+    ("gopher_auth_metadata_build_protected_resource", [c_char_p, c_char_p, c_char_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_metadata_build_oauth_server", [c_char_p, c_char_p, c_char_p, c_char_p, c_char_p, c_char_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_metadata_build_oidc_discovery", [c_char_p, c_char_p, c_char_p, c_char_p, c_char_p, c_char_p, c_char_p, c_char_p, POINTER(c_char_p)], c_int32),
+    # HTTP Parsing
+    ("gopher_auth_http_extract_bearer_token", [c_char_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_http_extract_method", [c_char_p, POINTER(c_char_p)], c_int32),
+    ("gopher_auth_http_extract_path", [c_char_p, POINTER(c_char_p)], c_int32),
     # Utility
     ("gopher_auth_free_string", [c_char_p], None),
     ("gopher_auth_generate_www_authenticate", [c_char_p, c_char_p, c_char_p, POINTER(c_char_p)], c_int32),
@@ -421,6 +464,49 @@ def get_auth_functions() -> Dict[str, Any]:
         "config_get_int": _get_function("gopher_auth_config_get_int"),
         "config_get_bool": _get_function("gopher_auth_config_get_bool"),
         "config_get_exchange_idps": _get_function("gopher_auth_config_get_exchange_idps"),
+        # OAuthClient
+        "oauth_client_create": _get_function("gopher_auth_oauth_client_create"),
+        "oauth_client_destroy": _get_function("gopher_auth_oauth_client_destroy"),
+        "oauth_exchange_code": _get_function("gopher_auth_oauth_exchange_code"),
+        "oauth_refresh_token": _get_function("gopher_auth_oauth_refresh_token"),
+        "oauth_token_exchange": _get_function("gopher_auth_oauth_token_exchange"),
+        "oauth_register_client": _get_function("gopher_auth_oauth_register_client"),
+        "token_response_get_access_token": _get_function("gopher_auth_token_response_get_access_token"),
+        "token_response_get_refresh_token": _get_function("gopher_auth_token_response_get_refresh_token"),
+        "token_response_get_expires_in": _get_function("gopher_auth_token_response_get_expires_in"),
+        "token_response_get_error": _get_function("gopher_auth_token_response_get_error"),
+        "token_response_is_success": _get_function("gopher_auth_token_response_is_success"),
+        "token_response_destroy": _get_function("gopher_auth_token_response_destroy"),
+        "registration_response_get_client_id": _get_function("gopher_auth_registration_response_get_client_id"),
+        "registration_response_get_client_secret": _get_function("gopher_auth_registration_response_get_client_secret"),
+        "registration_response_is_success": _get_function("gopher_auth_registration_response_is_success"),
+        "registration_response_destroy": _get_function("gopher_auth_registration_response_destroy"),
+        # SessionManager
+        "session_manager_create": _get_function("gopher_auth_session_manager_create"),
+        "session_manager_destroy": _get_function("gopher_auth_session_manager_destroy"),
+        "session_store_token": _get_function("gopher_auth_session_store_token"),
+        "session_get_access_token": _get_function("gopher_auth_session_get_access_token"),
+        "session_get_refresh_token": _get_function("gopher_auth_session_get_refresh_token"),
+        "session_has_valid_token": _get_function("gopher_auth_session_has_valid_token"),
+        "session_cleanup": _get_function("gopher_auth_session_cleanup"),
+        "session_generate_id": _get_function("gopher_auth_session_generate_id"),
+        # Auto-Refresh
+        "auto_refresh": _get_function("gopher_auth_auto_refresh"),
+        # Validation
+        "validate_idp": _get_function("gopher_auth_validate_idp"),
+        "validate_all_scopes": _get_function("gopher_auth_validate_all_scopes"),
+        "validate_any_scopes": _get_function("gopher_auth_validate_any_scopes"),
+        # URL Utils
+        "url_encode": _get_function("gopher_auth_url_encode"),
+        "url_decode": _get_function("gopher_auth_url_decode"),
+        # Metadata Builders
+        "metadata_build_protected_resource": _get_function("gopher_auth_metadata_build_protected_resource"),
+        "metadata_build_oauth_server": _get_function("gopher_auth_metadata_build_oauth_server"),
+        "metadata_build_oidc_discovery": _get_function("gopher_auth_metadata_build_oidc_discovery"),
+        # HTTP Parsing
+        "http_extract_bearer_token": _get_function("gopher_auth_http_extract_bearer_token"),
+        "http_extract_method": _get_function("gopher_auth_http_extract_method"),
+        "http_extract_path": _get_function("gopher_auth_http_extract_path"),
         # Utility
         "free_string": _get_function("gopher_auth_free_string"),
         "generate_www_authenticate": _get_function("gopher_auth_generate_www_authenticate"),
diff --git a/gopher_mcp_python/ffi/auth/oauth_client.py b/gopher_mcp_python/ffi/auth/oauth_client.py
@@ -0,0 +1,184 @@
+"""
+GopherOAuthClient - FFI wrapper for OAuth HTTP client operations.
+
+Provides token exchange, refresh, RFC 8693 token exchange, and
+RFC 7591 dynamic client registration via the native C API.
+"""
+
+from ctypes import POINTER, byref, c_char_p, c_int64, c_void_p
+from dataclasses import dataclass
+from typing import List, Optional
+
+from gopher_mcp_python.ffi.auth.loader import get_auth_functions, is_auth_available, load_library
+from gopher_mcp_python.ffi.auth.types import GopherAuthError
+
+
+@dataclass
+class TokenResponse:
+    """Token endpoint response."""
+    access_token: str
+    refresh_token: Optional[str] = None
+    expires_in: int = 0
+    token_type: str = "Bearer"
+    error: Optional[str] = None
+    success: bool = False
+
+
+@dataclass
+class RegistrationResponse:
+    """Dynamic client registration response."""
+    client_id: str
+    client_secret: Optional[str] = None
+    success: bool = False
+    error: Optional[str] = None
+
+
+class GopherOAuthClient:
+    """OAuth HTTP client for token operations via native C API."""
+
+    def __init__(
+        self,
+        token_endpoint: str,
+        client_id: str,
+        client_secret: Optional[str] = None,
+        request_timeout: int = 30,
+    ) -> None:
+        if not is_auth_available():
+            load_library()
+
+        funcs = get_auth_functions()
+        create = funcs.get("oauth_client_create")
+        if not create:
+            raise RuntimeError("OAuth client functions not available")
+
+        self._handle = c_void_p()
+        result = create(
+            byref(self._handle),
+            token_endpoint.encode("utf-8"),
+            client_id.encode("utf-8"),
+            client_secret.encode("utf-8") if client_secret else None,
+            request_timeout,
+        )
+        if result != GopherAuthError.SUCCESS:
+            raise RuntimeError(f"Failed to create OAuth client: error {result}")
+        self._destroyed = False
+
+    def _read_token_response(self, resp_handle: c_void_p) -> TokenResponse:
+        funcs = get_auth_functions()
+        success = funcs.get("token_response_is_success")
+        is_ok = success(resp_handle) if success else False
+
+        at_out = c_char_p()
+        funcs.get("token_response_get_access_token", lambda *a: None)(resp_handle, byref(at_out))
+        rt_out = c_char_p()
+        funcs.get("token_response_get_refresh_token", lambda *a: None)(resp_handle, byref(rt_out))
+        exp_out = c_int64(0)
+        funcs.get("token_response_get_expires_in", lambda *a: None)(resp_handle, byref(exp_out))
+        err_out = c_char_p()
+        funcs.get("token_response_get_error", lambda *a: None)(resp_handle, byref(err_out))
+
+        funcs.get("token_response_destroy", lambda *a: None)(resp_handle)
+
+        return TokenResponse(
+            access_token=at_out.value.decode("utf-8") if at_out.value else "",
+            refresh_token=rt_out.value.decode("utf-8") if rt_out.value else None,
+            expires_in=exp_out.value,
+            error=err_out.value.decode("utf-8") if err_out.value and not is_ok else None,
+            success=is_ok,
+        )
+
+    def exchange_code(self, code: str, redirect_uri: str, code_verifier: Optional[str] = None) -> TokenResponse:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("oauth_exchange_code")
+        if not fn:
+            return TokenResponse(access_token="", error="ffi_error", success=False)
+        resp = c_void_p()
+        err = fn(self._handle, code.encode("utf-8"), redirect_uri.encode("utf-8"),
+                 code_verifier.encode("utf-8") if code_verifier else None, byref(resp))
+        if err != GopherAuthError.SUCCESS or not resp:
+            return TokenResponse(access_token="", error="ffi_error", success=False)
+        return self._read_token_response(resp)
+
+    def refresh_token(self, refresh_token: str) -> TokenResponse:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("oauth_refresh_token")
+        if not fn:
+            return TokenResponse(access_token="", error="ffi_error", success=False)
+        resp = c_void_p()
+        err = fn(self._handle, refresh_token.encode("utf-8"), byref(resp))
+        if err != GopherAuthError.SUCCESS or not resp:
+            return TokenResponse(access_token="", error="ffi_error", success=False)
+        return self._read_token_response(resp)
+
+    def token_exchange(self, subject_token: str, requested_issuer: str,
+                       audience: Optional[str] = None, scope: Optional[str] = None) -> TokenResponse:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("oauth_token_exchange")
+        if not fn:
+            return TokenResponse(access_token="", error="ffi_error", success=False)
+        resp = c_void_p()
+        err = fn(self._handle, subject_token.encode("utf-8"), requested_issuer.encode("utf-8"),
+                 audience.encode("utf-8") if audience else None,
+                 scope.encode("utf-8") if scope else None, byref(resp))
+        if err != GopherAuthError.SUCCESS or not resp:
+            return TokenResponse(access_token="", error="ffi_error", success=False)
+        return self._read_token_response(resp)
+
+    def register_client(self, registration_endpoint: str, client_name: str,
+                        redirect_uris: List[str], scopes: Optional[str] = None) -> RegistrationResponse:
+        self._ensure_not_destroyed()
+        funcs = get_auth_functions()
+        fn = funcs.get("oauth_register_client")
+        if not fn:
+            return RegistrationResponse(client_id="", error="ffi_error", success=False)
+        count = len(redirect_uris)
+        uris_arr = (c_char_p * count)(*(u.encode("utf-8") for u in redirect_uris))
+        resp = c_void_p()
+        err = fn(self._handle, registration_endpoint.encode("utf-8"),
+                 client_name.encode("utf-8"), uris_arr, count,
+                 scopes.encode("utf-8") if scopes else b"openid", byref(resp))
+        if err != GopherAuthError.SUCCESS or not resp:
+            return RegistrationResponse(client_id="", error="ffi_error", success=False)
+
+        is_ok = funcs.get("registration_response_is_success", lambda *a: False)(resp)
+        cid_out = c_char_p()
+        funcs.get("registration_response_get_client_id", lambda *a: None)(resp, byref(cid_out))
+        cs_out = c_char_p()
+        funcs.get("registration_response_get_client_secret", lambda *a: None)(resp, byref(cs_out))
+        funcs.get("registration_response_destroy", lambda *a: None)(resp)
+
+        return RegistrationResponse(
+            client_id=cid_out.value.decode("utf-8") if cid_out.value else "",
+            client_secret=cs_out.value.decode("utf-8") if cs_out.value else None,
+            success=is_ok,
+        )
+
+    def get_handle(self) -> c_void_p:
+        self._ensure_not_destroyed()
+        return self._handle
+
+    def destroy(self) -> None:
+        if self._destroyed:
+            return
+        funcs = get_auth_functions()
+        d = funcs.get("oauth_client_destroy")
+        if d and self._handle:
+            d(self._handle)
+        self._handle = None
+        self._destroyed = True
+
+    def is_destroyed(self) -> bool:
+        return self._destroyed
+
+    def __enter__(self) -> "GopherOAuthClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.destroy()
+
+    def _ensure_not_destroyed(self) -> None:
+        if self._destroyed:
+            raise RuntimeError("GopherOAuthClient has been destroyed")
diff --git a/tests/ffi/auth/test_oauth_client.py b/tests/ffi/auth/test_oauth_client.py
@@ -0,0 +1,59 @@
+"""Tests for GopherOAuthClient FFI binding."""
+
+import pytest
+from gopher_mcp_python.ffi.auth.loader import is_auth_available
+
+pytestmark = pytest.mark.skipif(not is_auth_available(), reason="Native library not available")
+
+from gopher_mcp_python.ffi.auth.oauth_client import GopherOAuthClient
+from gopher_mcp_python.ffi.auth.auth_client import gopher_init_auth_library
+
+@pytest.fixture(autouse=True)
+def init_lib():
+    gopher_init_auth_library()
+
+class TestOAuthClient:
+    def test_create_with_all_params(self):
+        client = GopherOAuthClient("http://kc:8080/token", "cid", "cs", 30)
+        assert not client.is_destroyed()
+        client.destroy()
+
+    def test_create_without_secret(self):
+        client = GopherOAuthClient("http://kc:8080/token", "cid")
+        assert not client.is_destroyed()
+        client.destroy()
+
+    def test_error_for_unreachable_server(self):
+        client = GopherOAuthClient("http://192.0.2.1:1/token", "cid", "cs", 1)
+        resp = client.exchange_code("code", "http://cb")
+        assert not resp.success
+        client.destroy()
+
+    def test_refresh_unreachable(self):
+        client = GopherOAuthClient("http://192.0.2.1:1/token", "cid", "cs", 1)
+        resp = client.refresh_token("rt")
+        assert not resp.success
+        client.destroy()
+
+    def test_token_exchange_unreachable(self):
+        client = GopherOAuthClient("http://192.0.2.1:1/token", "cid", "cs", 1)
+        resp = client.token_exchange("st", "google")
+        assert not resp.success
+        client.destroy()
+
+    def test_destroy_lifecycle(self):
+        client = GopherOAuthClient("http://kc:8080/token", "cid", "cs", 5)
+        client.destroy()
+        assert client.is_destroyed()
+
+    def test_call_after_destroy_raises(self):
+        client = GopherOAuthClient("http://kc:8080/token", "cid", "cs", 5)
+        client.destroy()
+        with pytest.raises(RuntimeError, match="destroyed"):
+            client.exchange_code("code", "http://cb")
+
+    def test_double_destroy_safe(self):
+        client = GopherOAuthClient("http://kc:8080/token", "cid", "cs", 5)
+        client.destroy()
+        client.destroy()
+        assert client.is_destroyed()
