authgent 0.1.0__py3-none-any.whl

authgent/__init__.py

@@ -0,0 +1,32 @@
+"""authgent SDK — token validation, delegation chains, DPoP for AI agents."""
+
+from authgent.verify import verify_token
+from authgent.delegation import verify_delegation_chain
+from authgent.dpop import verify_dpop_proof, DPoPClient
+from authgent.client import AgentAuthClient
+from authgent.models import AgentIdentity, DelegationChain, TokenClaims
+from authgent.errors import (
+    AuthgentError,
+    InvalidTokenError,
+    DelegationError,
+    DPoPError,
+    ServerError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "verify_token",
+    "verify_delegation_chain",
+    "verify_dpop_proof",
+    "DPoPClient",
+    "AgentAuthClient",
+    "AgentIdentity",
+    "DelegationChain",
+    "TokenClaims",
+    "AuthgentError",
+    "InvalidTokenError",
+    "DelegationError",
+    "DPoPError",
+    "ServerError",
+]

authgent/adapters/__init__.py

@@ -0,0 +1 @@
+"""SDK adapters for MCP and other protocols."""

authgent/adapters/langchain.py

@@ -0,0 +1,223 @@
+"""LangChain adapter — plug authgent into LangChain tool/agent pipelines.
+
+Provides:
+- AuthgentToolWrapper: wraps any LangChain tool with automatic token management
+- AuthgentCallbackHandler: logs auth events (token refresh, exchange) to LangChain callbacks
+- authgent_auth_header: helper to inject Bearer/DPoP headers into HTTP tool calls
+
+Usage:
+    from authgent.adapters.langchain import AuthgentToolWrapper
+    from langchain_core.tools import Tool
+
+    wrapper = AuthgentToolWrapper(
+        server_url="http://localhost:8000",
+        client_id="agnt_xxx",
+        client_secret="secret",
+        scope="read write",
+    )
+
+    # Wrap any tool to auto-inject auth headers
+    authed_tool = wrapper.wrap(my_http_tool)
+
+    # Or get headers directly for custom integrations
+    headers = await wrapper.get_auth_headers(resource="https://api.example.com")
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from authgent.client import AgentAuthClient, TokenResult
+from authgent.dpop import DPoPClient
+
+
+@dataclass
+class _CachedToken:
+    """In-memory token with expiry tracking."""
+
+    token: TokenResult
+    acquired_at: float = field(default_factory=time.monotonic)
+
+    def is_expired(self, buffer_seconds: int = 30) -> bool:
+        """Check if token is expired or about to expire."""
+        elapsed = time.monotonic() - self.acquired_at
+        return elapsed >= (self.token.expires_in - buffer_seconds)
+
+
+class AuthgentToolWrapper:
+    """Wraps LangChain tools with automatic authgent token management.
+
+    Handles:
+    - Client credentials token acquisition
+    - Token caching with automatic refresh
+    - Token exchange for downstream resource delegation
+    - Optional DPoP proof generation
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        client_id: str,
+        client_secret: str,
+        *,
+        scope: str | None = None,
+        resource: str | None = None,
+        use_dpop: bool = False,
+        token_buffer_seconds: int = 30,
+    ):
+        self._client = AgentAuthClient(server_url)
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._scope = scope
+        self._resource = resource
+        self._use_dpop = use_dpop
+        self._buffer = token_buffer_seconds
+        self._dpop: DPoPClient | None = DPoPClient() if use_dpop else None
+        self._cached: _CachedToken | None = None
+
+    async def get_token(self) -> TokenResult:
+        """Get a valid access token, refreshing if needed."""
+        if self._cached and not self._cached.is_expired(self._buffer):
+            return self._cached.token
+
+        result = await self._client.get_token(
+            client_id=self._client_id,
+            client_secret=self._client_secret,
+            scope=self._scope,
+            resource=self._resource,
+        )
+        self._cached = _CachedToken(token=result)
+        return result
+
+    async def exchange_for(
+        self,
+        audience: str,
+        scopes: list[str] | None = None,
+    ) -> TokenResult:
+        """Exchange the current token for a delegated token targeting a downstream resource."""
+        parent = await self.get_token()
+        return await self._client.exchange_token(
+            subject_token=parent.access_token,
+            audience=audience,
+            scopes=scopes,
+            client_id=self._client_id,
+            client_secret=self._client_secret,
+        )
+
+    async def get_auth_headers(
+        self,
+        *,
+        resource: str | None = None,
+        http_method: str = "GET",
+        http_uri: str | None = None,
+    ) -> dict[str, str]:
+        """Get authorization headers for an HTTP request.
+
+        If resource differs from the configured resource, performs a token exchange.
+        If DPoP is enabled, includes DPoP proof header.
+        """
+        if resource and resource != self._resource:
+            token = await self.exchange_for(resource)
+        else:
+            token = await self.get_token()
+
+        headers: dict[str, str] = {}
+
+        if self._dpop and http_uri:
+            proof_headers = self._dpop.create_proof_headers(
+                http_method=http_method,
+                http_uri=http_uri,
+                access_token=token.access_token,
+            )
+            headers.update(proof_headers)
+            headers["Authorization"] = f"DPoP {token.access_token}"
+        else:
+            headers["Authorization"] = f"Bearer {token.access_token}"
+
+        return headers
+
+    def wrap(self, tool: Any) -> Any:
+        """Wrap a LangChain tool to auto-inject auth metadata.
+
+        Returns a new tool that adds `authgent_headers` to the tool's
+        kwargs before invocation. The wrapped tool's function should
+        accept **kwargs and use `authgent_headers` for HTTP calls.
+
+        NOTE: This is a skeleton — full integration depends on the
+        LangChain tool interface version (BaseTool, StructuredTool, etc).
+        """
+        # Lazy import to avoid hard dependency on langchain
+        try:
+            from langchain_core.tools import StructuredTool
+        except ImportError:
+            raise ImportError(
+                "langchain-core is required for tool wrapping. "
+                "Install with: pip install langchain-core"
+            )
+
+        original_func = tool.func if hasattr(tool, "func") else tool._run
+        wrapper_self = self
+
+        async def _authed_func(*args: Any, **kwargs: Any) -> Any:
+            headers = await wrapper_self.get_auth_headers()
+            kwargs["authgent_headers"] = headers
+            if hasattr(original_func, "__call__"):
+                return await original_func(*args, **kwargs)
+            return original_func(*args, **kwargs)
+
+        return StructuredTool(
+            name=getattr(tool, "name", "wrapped_tool"),
+            description=getattr(tool, "description", ""),
+            coroutine=_authed_func,
+            args_schema=getattr(tool, "args_schema", None),
+        )
+
+    async def revoke(self) -> None:
+        """Revoke the current cached token."""
+        if self._cached:
+            await self._client.revoke_token(
+                self._cached.token.access_token,
+                client_id=self._client_id,
+            )
+            self._cached = None
+
+
+class AuthgentCallbackHandler:
+    """LangChain callback handler skeleton for auth event logging.
+
+    Logs token acquisition, refresh, and exchange events. Can be
+    extended to integrate with LangChain's callback system.
+
+    Usage:
+        from langchain_core.callbacks import CallbackManager
+        handler = AuthgentCallbackHandler()
+        callback_manager = CallbackManager([handler])
+    """
+
+    def __init__(self, *, verbose: bool = False):
+        self._verbose = verbose
+        self._events: list[dict[str, Any]] = []
+
+    def on_token_acquired(self, token_type: str, scope: str | None) -> None:
+        event = {"event": "token_acquired", "token_type": token_type, "scope": scope}
+        self._events.append(event)
+        if self._verbose:
+            print(f"[authgent] Token acquired: type={token_type} scope={scope}")
+
+    def on_token_exchanged(self, audience: str, scope: str | None) -> None:
+        event = {"event": "token_exchanged", "audience": audience, "scope": scope}
+        self._events.append(event)
+        if self._verbose:
+            print(f"[authgent] Token exchanged: audience={audience} scope={scope}")
+
+    def on_token_revoked(self) -> None:
+        event = {"event": "token_revoked"}
+        self._events.append(event)
+        if self._verbose:
+            print("[authgent] Token revoked")
+
+    @property
+    def events(self) -> list[dict[str, Any]]:
+        return list(self._events)

authgent/adapters/mcp.py

@@ -0,0 +1,40 @@
+"""MCP Auth Provider adapter — plug authgent into FastMCP servers."""
+
+from __future__ import annotations
+
+from authgent.client import AgentAuthClient
+from authgent.verify import verify_token
+from authgent.models import AgentIdentity
+
+
+class AgentAuthProvider:
+    """Auth provider adapter for FastMCP servers.
+
+    Usage:
+        from authgent.adapters.mcp import AgentAuthProvider
+        mcp = FastMCP("my-server")
+        mcp.auth_provider = AgentAuthProvider(server_url="http://localhost:8000")
+    """
+
+    def __init__(self, server_url: str, audience: str | None = None):
+        self._server_url = server_url.rstrip("/")
+        self._audience = audience
+        self._client = AgentAuthClient(server_url)
+
+    async def verify(self, token: str) -> AgentIdentity:
+        """Verify an access token and return the agent identity."""
+        return await verify_token(
+            token=token,
+            issuer=self._server_url,
+            audience=self._audience,
+        )
+
+    @property
+    def metadata_url(self) -> str:
+        """URL for OAuth server metadata discovery."""
+        return f"{self._server_url}/.well-known/oauth-authorization-server"
+
+    @property
+    def jwks_url(self) -> str:
+        """URL for JWKS endpoint."""
+        return f"{self._server_url}/.well-known/jwks.json"

authgent/adapters/protected_resource.py

@@ -0,0 +1,92 @@
+"""RFC 9728 — OAuth 2.0 Protected Resource Metadata generator.
+
+Generates the /.well-known/oauth-protected-resource JSON document
+that MCP servers and API servers should serve to advertise their
+authorization requirements to clients.
+
+Usage:
+    from authgent.adapters.protected_resource import ProtectedResourceMetadata
+
+    metadata = ProtectedResourceMetadata(
+        resource="https://mcp-server.example.com",
+        authorization_servers=["http://localhost:8000"],
+        scopes_supported=["tools:execute", "db:read", "db:write"],
+    )
+
+    # In FastAPI:
+    @app.get("/.well-known/oauth-protected-resource")
+    def protected_resource():
+        return metadata.to_dict()
+
+    # Or generate as JSON string:
+    json_str = metadata.to_json()
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ProtectedResourceMetadata:
+    """RFC 9728 Protected Resource Metadata document.
+
+    Attributes:
+        resource: The protected resource identifier (URL).
+        authorization_servers: List of authorization server URLs that can issue
+            tokens accepted by this resource.
+        scopes_supported: Scopes this resource understands.
+        bearer_methods_supported: Token presentation methods supported.
+        resource_signing_alg_values_supported: Signing algorithms accepted.
+        resource_documentation: URL to human-readable documentation.
+        resource_policy_uri: URL to the resource's policy.
+        resource_tos_uri: URL to the resource's terms of service.
+        dpop_signing_alg_values_supported: DPoP signing algorithms accepted.
+    """
+
+    resource: str
+    authorization_servers: list[str]
+    scopes_supported: list[str] = field(default_factory=list)
+    bearer_methods_supported: list[str] = field(default_factory=lambda: ["header"])
+    resource_signing_alg_values_supported: list[str] = field(
+        default_factory=lambda: ["ES256"]
+    )
+    resource_documentation: str | None = None
+    resource_policy_uri: str | None = None
+    resource_tos_uri: str | None = None
+    dpop_signing_alg_values_supported: list[str] | None = None
+
+    def to_dict(self) -> dict:
+        """Generate the RFC 9728 metadata document as a dictionary."""
+        doc: dict = {
+            "resource": self.resource,
+            "authorization_servers": self.authorization_servers,
+        }
+        if self.scopes_supported:
+            doc["scopes_supported"] = self.scopes_supported
+        if self.bearer_methods_supported:
+            doc["bearer_methods_supported"] = self.bearer_methods_supported
+        if self.resource_signing_alg_values_supported:
+            doc["resource_signing_alg_values_supported"] = (
+                self.resource_signing_alg_values_supported
+            )
+        if self.resource_documentation:
+            doc["resource_documentation"] = self.resource_documentation
+        if self.resource_policy_uri:
+            doc["resource_policy_uri"] = self.resource_policy_uri
+        if self.resource_tos_uri:
+            doc["resource_tos_uri"] = self.resource_tos_uri
+        if self.dpop_signing_alg_values_supported:
+            doc["dpop_signing_alg_values_supported"] = (
+                self.dpop_signing_alg_values_supported
+            )
+        return doc
+
+    def to_json(self, indent: int = 2) -> str:
+        """Generate the RFC 9728 metadata document as a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+    def fastapi_route(self) -> dict:
+        """Return the metadata dict, suitable as a FastAPI route return value."""
+        return self.to_dict()