feat: Add a User representation to ServerCallContext (#116)

* Start sketching out auth handling ideas

* Introduce simple server request auth structures

* Make ServerCallContext a pydantic model

* Update check-spelling metadata

* Fix broken tests

* Delete empty file

Author: mikeas1

.github/actions/spelling/excludes.txt

@@ -1,8 +1,8 @@
 # See https://github.com/check-spelling/check-spelling/wiki/Configuration-Examples:-excludes
+(?:^|/)(?i).gitignore\E$
+(?:^|/)(?i)CODE_OF_CONDUCT.md\E$
 (?:^|/)(?i)COPYRIGHT
 (?:^|/)(?i)LICEN[CS]E
-(?:^|/)(?i)CODE_OF_CONDUCT.md\E$
-(?:^|/)(?i).gitignore\E$
 (?:^|/)3rdparty/
 (?:^|/)go\.sum$
 (?:^|/)package(?:-lock|)\.json$
@@ -33,6 +33,7 @@
 \.gif$
 \.git-blame-ignore-revs$
 \.gitattributes$
+\.gitignore\E$
 \.gitkeep$
 \.graffle$
 \.gz$
@@ -62,6 +63,7 @@
 \.pyc$
 \.pylintrc$
 \.qm$
+\.ruff.toml$
 \.s$
 \.sig$
 \.so$
@@ -71,6 +73,7 @@
 \.tgz$
 \.tiff?$
 \.ttf$
+\.vscode/
 \.wav$
 \.webm$
 \.webp$
@@ -82,8 +85,7 @@
 \.zip$
 ^\.github/actions/spelling/
 ^\.github/workflows/
-\.gitignore\E$
-\.vscode/
-noxfile.py
-\.ruff.toml$
+^\Qsrc/a2a/auth/__init__.py\E$
+^\Qsrc/a2a/server/request_handlers/context.py\E$
 CHANGELOG.md
+noxfile.py

.github/actions/spelling/expect.txt

@@ -1,3 +1,4 @@
+AUser
 excinfo
 GVsb
 notif

src/a2a/auth/__init__.py

@@ -0,0 +1,29 @@
+"""Authenticated user information."""
+
+from abc import ABC, abstractmethod
+
+
+class User(ABC):
+    """A representation of an authenticated user."""
+
+    @property
+    @abstractmethod
+    def is_authenticated(self) -> bool:
+        """Returns whether the current user is authenticated."""
+
+    @property
+    @abstractmethod
+    def user_name(self) -> str:
+        """Returns the user name of the current user."""
+
+
+class UnauthenticatedUser(User):
+    """A representation that no user has been authenticated in the request."""
+
+    @property
+    def is_authenticated(self):
+        return False
+
+    @property
+    def user_name(self) -> str:
+        return ''

src/a2a/auth/user.py

@@ -1,32 +1,53 @@
+import contextlib
 import json
 import logging
 import traceback
+
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator
 from typing import Any
 
 from pydantic import ValidationError
 from sse_starlette.sse import EventSourceResponse
 from starlette.applications import Starlette
+from starlette.authentication import BaseUser
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 from starlette.routing import Route
 
+from a2a.auth.user import UnauthenticatedUser
+from a2a.auth.user import User as A2AUser
 from a2a.server.context import ServerCallContext
 from a2a.server.request_handlers.jsonrpc_handler import JSONRPCHandler
 from a2a.server.request_handlers.request_handler import RequestHandler
-from a2a.types import (A2AError, A2ARequest, AgentCard, CancelTaskRequest,
-                       GetTaskPushNotificationConfigRequest, GetTaskRequest,
-                       InternalError, InvalidRequestError, JSONParseError,
-                       JSONRPCError, JSONRPCErrorResponse, JSONRPCResponse,
-                       SendMessageRequest, SendStreamingMessageRequest,
-                       SendStreamingMessageResponse,
-                       SetTaskPushNotificationConfigRequest,
-                       TaskResubscriptionRequest, UnsupportedOperationError)
+from a2a.types import (
+    A2AError,
+    A2ARequest,
+    AgentCard,
+    CancelTaskRequest,
+    GetTaskPushNotificationConfigRequest,
+    GetTaskRequest,
+    InternalError,
+    InvalidRequestError,
+    JSONParseError,
+    JSONRPCError,
+    JSONRPCErrorResponse,
+    JSONRPCResponse,
+    SendMessageRequest,
+    SendStreamingMessageRequest,
+    SendStreamingMessageResponse,
+    SetTaskPushNotificationConfigRequest,
+    TaskResubscriptionRequest,
+    UnsupportedOperationError,
+)
 from a2a.utils.errors import MethodNotImplementedError
 
+
 logger = logging.getLogger(__name__)
 
+# Register Starlette User as an implementation of a2a.auth.user.User
+A2AUser.register(BaseUser)
+
 
 class CallContextBuilder(ABC):
     """A class for building ServerCallContexts using the Starlette Request."""
@@ -36,6 +57,18 @@ def build(self, request: Request) -> ServerCallContext:
         """Builds a ServerCallContext from a Starlette Request."""
 
 
+class DefaultCallContextBuilder(CallContextBuilder):
+    """A default implementation of CallContextBuilder."""
+
+    def build(self, request: Request) -> ServerCallContext:
+        user = UnauthenticatedUser()
+        state = {}
+        with contextlib.suppress(Exception):
+            user = request.user
+            state['auth'] = request.auth
+        return ServerCallContext(user=user, state=state)
+
+
 class A2AStarletteApplication:
     """A Starlette application implementing the A2A protocol server endpoints.
 
@@ -75,7 +108,7 @@ def __init__(
             logger.error(
                 'AgentCard.supportsAuthenticatedExtendedCard is True, but no extended_agent_card was provided. The /agent/authenticatedExtendedCard endpoint will return 404.'
             )
-        self._context_builder = context_builder
+        self._context_builder = context_builder or DefaultCallContextBuilder()
 
     def _generate_error_response(
         self, request_id: str | int | None, error: JSONRPCError | A2AError
@@ -137,11 +170,7 @@ async def _handle_requests(self, request: Request) -> Response:
         try:
             body = await request.json()
             a2a_request = A2ARequest.model_validate(body)
-            call_context = (
-                self._context_builder.build(request)
-                if self._context_builder
-                else None
-            )
+            call_context = self._context_builder.build(request)
 
             request_id = a2a_request.root.id
             request_obj = a2a_request.root
@@ -344,7 +373,9 @@ async def _handle_get_authenticated_extended_agent_card(
         # extended_agent_card was provided during server initialization,
         # return a 404
         return JSONResponse(
-            {'error': 'Authenticated extended agent card is supported but not configured on the server.'},
+            {
+                'error': 'Authenticated extended agent card is supported but not configured on the server.'
+            },
             status_code=404,
         )
 

src/a2a/server/apps/starlette_app.py

@@ -3,22 +3,21 @@
 import collections.abc
 import typing
 
+from pydantic import BaseModel, ConfigDict, Field
+
+from a2a.auth.user import UnauthenticatedUser, User
+
 
 State = collections.abc.MutableMapping[str, typing.Any]
 
 
-class ServerCallContext:
+class ServerCallContext(BaseModel):
     """A context passed when calling a server method.
 
     This class allows storing arbitrary user data in the state attribute.
     """
 
-    def __init__(self, state: State | None = None):
-        if state is None:
-            state = {}
-        self._state = state
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    @property
-    def state(self) -> State:
-        """Get the user-provided state."""
-        return self._state
+    state: State = Field(default={})
+    user: User = Field(default=UnauthenticatedUser())