ygo74-agent-runtime-security 0.1.0__py3-none-any.whl

ygo74/agent_runtime/domains/auth/agent_principal.py

@@ -0,0 +1,171 @@
+"""Who the agent is acting for, established outside the application.
+
+A serving surface authenticates a caller; the application must be *told* who that
+is rather than configured with it. :class:`AgentPrincipal` is the result of that
+authentication - a subject, an optional address, a display name and the roles the
+identity provider asserted.
+
+It is deliberately *not* a token. It carries no credential, so it may reach a log,
+an audit record or a prompt without leaking anything, and it is immutable, so the
+identity a piece of state is keyed by cannot be changed after the fact.
+
+Two things this model deliberately does not do:
+
+* It does not build an authorisation. Turning roles into permissions is an
+  application decision, and an identity that knew how to grant itself rights
+  would be the wrong shape.
+* It does not read a claim it has not modelled. What an application receives is
+  exactly what is declared here, so it cannot grow a dependency on a token's
+  internals by accident.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Final
+
+from pydantic import BaseModel, ConfigDict, Field
+from ygo74.agent_runtime.domains.auth.auth_context import AuthenticatedUserContext
+from ygo74.agent_runtime.domains.security.security_errors import SecurityError
+
+_IDENTITY: Final = "identity"
+_SUBJECT: Final = "subject"
+_USER_ID: Final = "userId"
+_EMAIL: Final = "email"
+_NAME: Final = "name"
+_USERNAME: Final = "username"
+_ROLES: Final = "roles"
+
+
+class PrincipalError(SecurityError):
+    """Raised when an authenticated caller cannot be turned into a principal.
+
+    Failing here is a refusal to serve, never a fallback to an anonymous or
+    default identity: acting for "somebody" is how one caller's data ends up
+    answering for another.
+    """
+
+
+class AgentPrincipal(BaseModel):
+    """An authenticated caller, without any credential.
+
+    Attributes:
+        subject: Stable identifier of the person, as asserted by the identity
+            provider. This is what conversation state, ledgers and audit entries
+            are partitioned by, so it must never be derived from client-supplied
+            data.
+        email: Address of the person, when the identity provider asserts one.
+            Optional because it is an attribute of an identity rather than a
+            requirement of every agent: a mailbox is addressed by e-mail, a wiki
+            account is not. An agent that needs one says so itself, through
+            ``require_email``, and fails loudly when it is absent, rather than
+            this model demanding it of agents that do not.
+        display_name: Human-readable name, for prompts and confirmations.
+        roles: Roles asserted by the identity provider. They are claims about the
+            caller, not permissions: mapping them to permissions is a decision of
+            the application.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    subject: str = Field(min_length=1)
+    email: str = ""
+    display_name: str = ""
+    roles: frozenset[str] = frozenset()
+
+    @classmethod
+    def from_context(
+        cls,
+        context: AuthenticatedUserContext,
+        *,
+        require_email: bool = True,
+    ) -> AgentPrincipal:
+        """Build a principal from the context the authenticator produced.
+
+        This is the typed path, and the one to prefer: it needs no dictionary and
+        cannot misread a key.
+        """
+        identity = context.identity
+        return cls._build(
+            subject=_text(identity.subject) or _text(identity.user_id),
+            email=_text(identity.email),
+            display_name=_text(identity.name) or _text(identity.username),
+            roles=frozenset(_text(role) for role in context.roles if _text(role)),
+            require_email=require_email,
+        )
+
+    @classmethod
+    def from_auth_context(
+        cls,
+        context: Mapping[str, object] | None,
+        *,
+        require_email: bool = True,
+    ) -> AgentPrincipal:
+        """Build a principal from the wire-shaped authentication context.
+
+        This is the shape an endpoint hands to a handler: loosely typed, because
+        it crossed a transport boundary. This is the single place allowed to read
+        it, so the rest of an application keeps working with a typed model.
+
+        The subject is taken from the verified authentication context and never
+        from the request body: a caller must not be able to name themselves.
+
+        Args:
+            context: The authentication context the transport established.
+            require_email: Whether a caller without an address is refused. An
+                agent that addresses its subject by e-mail leaves this at its
+                default; an agent whose accounts are not e-mail addresses passes
+                ``False`` rather than inventing an address to satisfy this model.
+        """
+        if not context:
+            raise PrincipalError("the request carried no authenticated caller")
+
+        identity = context.get(_IDENTITY)
+        identity_map: Mapping[str, object] = identity if isinstance(identity, Mapping) else {}
+
+        return cls._build(
+            subject=(
+                _text(identity_map.get(_SUBJECT))
+                or _text(identity_map.get(_USER_ID))
+                or _text(context.get(_USER_ID))
+            ),
+            email=_text(identity_map.get(_EMAIL)),
+            display_name=_text(identity_map.get(_NAME)) or _text(identity_map.get(_USERNAME)),
+            roles=_texts(context.get(_ROLES)),
+            require_email=require_email,
+        )
+
+    @classmethod
+    def _build(
+        cls,
+        *,
+        subject: str,
+        email: str,
+        display_name: str,
+        roles: frozenset[str],
+        require_email: bool,
+    ) -> AgentPrincipal:
+        """Apply the two refusals both entry points share."""
+        if not subject:
+            raise PrincipalError("the authenticated caller carries no subject")
+        if require_email and not email:
+            raise PrincipalError(f"the authenticated caller {subject!r} carries no email address")
+        return cls(subject=subject, email=email, display_name=display_name, roles=roles)
+
+    def has_role(self, role: str) -> bool:
+        """Whether the identity provider asserted a role for this caller."""
+        return role in self.roles
+
+
+def _text(value: object) -> str:
+    """Return a non-empty stripped string, or nothing at all."""
+    if not isinstance(value, str):
+        return ""
+    return value.strip()
+
+
+def _texts(value: object) -> frozenset[str]:
+    """Return the non-empty strings of a wire-shaped list, ignoring the rest."""
+    if not isinstance(value, (list, tuple, set, frozenset)):
+        return frozenset()
+    return frozenset(text for item in value if (text := _text(item)))

ygo74/agent_runtime/domains/auth/apikey_authenticator.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from ygo74.agent_runtime.domains.auth.auth_context import (
+    AuthenticatedUserContext,
+    ResolvedUser,
+)
+from ygo74.agent_runtime.domains.auth.auth_errors import AuthenticationError
+
+
+class ApiKeyUserResolver(Protocol):
+    """Contract a developer implements to map an API key to a user.
+
+    Returning ``None`` means the key is unknown and the request is rejected with
+    ``api_key_invalid``. The returned :class:`ResolvedUser` defines exactly which
+    user information is loaded into the handler's ``auth_context``.
+    """
+
+    def resolve_user(self, api_key: str) -> ResolvedUser | None:
+        ...
+
+
+@dataclass(slots=True)
+class StaticApiKeyUserResolver:
+    """In-memory resolver, mostly useful for local development and tests."""
+
+    users_by_key: dict[str, ResolvedUser]
+
+    def resolve_user(self, api_key: str) -> ResolvedUser | None:
+        return self.users_by_key.get(api_key)
+
+
+class ApiKeyAuthenticator:
+    """Authenticates callers presenting an API key header.
+
+    The raw key is never propagated into the resulting context: only the user
+    information returned by the resolver is exposed to the handler.
+
+    ``scheme`` exists because not every deployment carries its key in a header of
+    its own. A server reached at ``Authorization: Bearer <secret>`` is presenting an
+    API key wearing a scheme, and reading the raw header value there would resolve
+    the literal string ``Bearer <secret>`` as the key. When a scheme is named, a
+    header that does not carry it is not claimed at all - so this authenticator
+    cannot swallow a credential meant for another one sharing the same header.
+    """
+
+    DEFAULT_HEADER_NAME = "x-api-key"
+
+    def __init__(
+        self,
+        resolver: ApiKeyUserResolver,
+        *,
+        header_name: str = DEFAULT_HEADER_NAME,
+        scheme: str = "",
+    ) -> None:
+        self._resolver = resolver
+        self._header_name = header_name.lower()
+        self._scheme = scheme.strip().lower()
+
+    @property
+    def auth_type(self) -> str:
+        return "api_key"
+
+    @property
+    def header_name(self) -> str:
+        return self._header_name
+
+    def can_authenticate(self, headers: Mapping[str, Any]) -> bool:
+        return bool(self._presented(headers))
+
+    def missing_credential_error(self) -> AuthenticationError:
+        return AuthenticationError(
+            code="api_key_header_missing",
+            message=f"Missing {self._header_name} header",
+        )
+
+    def _presented(self, headers: Mapping[str, Any]) -> str:
+        """Return the key the request carries, or the empty string.
+
+        The empty string means "not for me", which is what keeps a chain of
+        authenticators sharing one header from stealing each other's requests.
+        """
+        header = headers.get(self._header_name)
+        if not isinstance(header, str) or not header.strip():
+            return ""
+
+        value = header.strip()
+        if not self._scheme:
+            return value
+
+        name, separator, credential = value.partition(" ")
+        if not separator or name.lower() != self._scheme:
+            return ""
+        return credential.strip()
+
+    def authenticate(self, headers: Mapping[str, Any]) -> AuthenticatedUserContext:
+        api_key = self._presented(headers)
+        if not api_key:
+            raise self.missing_credential_error()
+
+        return self.authenticate_key(api_key)
+
+    def authenticate_key(self, api_key: str) -> AuthenticatedUserContext:
+        if not api_key:
+            raise self.missing_credential_error()
+
+        user = self._resolve(api_key)
+
+        return AuthenticatedUserContext(
+            auth_type=self.auth_type,
+            identity=user.to_identity(),
+            roles=list(user.roles),
+            groups=list(user.groups),
+            scopes=list(user.scopes),
+            claims=dict(user.claims),
+            tenant_id=user.tenant_id,
+        )
+
+    def _resolve(self, api_key: str) -> ResolvedUser:
+        try:
+            resolved: object = self._resolver.resolve_user(api_key)
+        except AuthenticationError:
+            raise
+        except Exception as ex:
+            raise AuthenticationError(
+                code="user_resolution_failed",
+                message="API key user-resolution hook raised an error",
+            ) from ex
+
+        if resolved is None:
+            raise AuthenticationError(code="api_key_invalid", message="API key is not recognized")
+
+        if not isinstance(resolved, ResolvedUser):
+            raise AuthenticationError(
+                code="user_context_malformed",
+                message="API key user-resolution hook must return a ResolvedUser",
+            )
+
+        if not resolved.user_id or not resolved.user_id.strip():
+            raise AuthenticationError(
+                code="user_context_malformed",
+                message="API key user-resolution hook must provide a user_id",
+            )
+
+        return resolved

ygo74/agent_runtime/domains/auth/auth_context.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class UserIdentity:
+    """Normalized identity of the authenticated caller."""
+
+    user_id: str
+    subject: str | None = None
+    username: str | None = None
+    name: str | None = None
+    given_name: str | None = None
+    family_name: str | None = None
+    email: str | None = None
+    email_verified: bool | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "userId": self.user_id,
+            "subject": self.subject or self.user_id,
+            "username": self.username,
+            "name": self.name,
+            "givenName": self.given_name,
+            "familyName": self.family_name,
+            "email": self.email,
+            "emailVerified": self.email_verified,
+        }
+
+
+@dataclass(slots=True)
+class ResolvedUser:
+    """Return schema of an API key user-resolution hook.
+
+    This is the contract a developer must satisfy when mapping an API key to a
+    user: whatever is populated here is what the handler will find in its
+    ``auth_context``.
+    """
+
+    user_id: str
+    username: str | None = None
+    name: str | None = None
+    given_name: str | None = None
+    family_name: str | None = None
+    email: str | None = None
+    email_verified: bool | None = None
+    roles: list[str] = field(default_factory=list)
+    groups: list[str] = field(default_factory=list)
+    scopes: list[str] = field(default_factory=list)
+    tenant_id: str | None = None
+    claims: dict[str, Any] = field(default_factory=dict)
+
+    def to_identity(self) -> UserIdentity:
+        return UserIdentity(
+            user_id=self.user_id,
+            subject=self.user_id,
+            username=self.username,
+            name=self.name,
+            given_name=self.given_name,
+            family_name=self.family_name,
+            email=self.email,
+            email_verified=self.email_verified,
+        )
+
+
+@dataclass(slots=True)
+class AuthenticatedUserContext:
+    """Normalized authentication context handed to the handler.
+
+    ``to_dict`` produces the wire shape required by the Standard Exchange
+    contract (``userId`` and ``authType`` at the top level).
+    """
+
+    auth_type: str
+    identity: UserIdentity
+    roles: list[str] = field(default_factory=list)
+    groups: list[str] = field(default_factory=list)
+    scopes: list[str] = field(default_factory=list)
+    claims: dict[str, Any] = field(default_factory=dict)
+    tenant_id: str | None = None
+
+    @property
+    def user_id(self) -> str:
+        return self.identity.user_id
+
+    def has_role(self, role: str) -> bool:
+        return role in self.roles
+
+    def has_scope(self, scope: str) -> bool:
+        return scope in self.scopes
+
+    def to_dict(self) -> dict[str, Any]:
+        context: dict[str, Any] = {
+            "authType": self.auth_type,
+            "userId": self.identity.user_id,
+            "identity": self.identity.to_dict(),
+            "roles": list(self.roles),
+            "groups": list(self.groups),
+            "scopes": list(self.scopes),
+            "claims": dict(self.claims),
+        }
+
+        if self.tenant_id is not None:
+            context["tenantId"] = self.tenant_id
+
+        return context

ygo74/agent_runtime/domains/auth/auth_errors.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def auth_error(code: str, message: str, category: str, details: Any | None = None) -> dict[str, Any]:
+    err: dict[str, Any] = {"code": code, "category": category, "message": message}
+    if details is not None:
+        err["details"] = details
+    return err
+
+
+@dataclass(slots=True)
+class AuthenticationError(Exception):
+    code: str
+    message: str
+    category: str = "authentication"
+    details: Any | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return auth_error(self.code, self.message, self.category, self.details)
+
+
+@dataclass(slots=True)
+class AuthorizationError(Exception):
+    """Raised by developer-owned authorization logic to deny an authenticated request.
+
+    The runtime never raises this itself: authorization decisions belong to the
+    handler. When raised, the runtime short-circuits handler execution and maps
+    it to an HTTP 403 with a structured error envelope.
+    """
+
+    code: str = "forbidden"
+    message: str = "Access denied"
+    category: str = "authorization"
+    details: Any | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return auth_error(self.code, self.message, self.category, self.details)

ygo74/agent_runtime/domains/auth/authentication_policy.py

@@ -0,0 +1,189 @@
+"""Which authentication schemes a host accepts, said out loud.
+
+The schemes themselves already existed: an API key with a user resolver the host
+writes, a JWT validated against an OIDC issuer, and the :class:`Authenticator`
+protocol for anything a deployment actually has - Basic, Kerberos, mutual TLS. What
+was missing was a way to *declare* which of them a host accepts. A host declared it
+by which keyword arguments it happened to pass, and the absence of all of them meant
+"no authentication".
+
+That was survivable while agents were the only host, because an agent always needs
+a subject: without one there is nothing to partition conversation state by. It stops
+being survivable the moment an MCP server shares the model, because an MCP server
+over read-only public data may legitimately serve everyone.
+
+So anonymity becomes a decision rather than a residue. :meth:`AuthenticationPolicy.anonymous`
+is the only way to reach it, :meth:`AuthenticationPolicy.of` refuses to build a
+policy out of nothing, and :meth:`AuthenticationMode.named` refuses an unset value.
+A deployment that forgot to configure authentication stops; a deployment that chose
+to serve everyone says so, and can be asked about it later.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Self
+
+from ygo74.agent_runtime.domains.auth.apikey_authenticator import (
+    ApiKeyAuthenticator,
+    ApiKeyUserResolver,
+)
+from ygo74.agent_runtime.domains.auth.authenticator import (
+    Authenticator,
+    RequestAuthenticator,
+)
+from ygo74.agent_runtime.domains.auth.jwt_authenticator import (
+    JwtAuthenticator,
+    JwtValidationConfig,
+)
+
+
+class AuthenticationConfigurationError(RuntimeError):
+    """Raised when a host cannot be served safely as configured.
+
+    Deliberately fatal, and deliberately not an :class:`AuthenticationError`: this
+    is not a caller failing to authenticate, it is a deployment that never said how
+    callers would be authenticated at all. Answering a request would mean guessing.
+    """
+
+
+class AuthenticationMode(StrEnum):
+    """The schemes a host can be configured with.
+
+    ``CUSTOM`` is not something a configuration file names. It is what a policy
+    reports when a host supplied its own :class:`Authenticator`, so that a start-up
+    log still says something true about a scheme this enumeration never heard of.
+    """
+
+    NONE = "none"
+    API_KEY = "api_key"
+    JWT = "jwt"
+    CUSTOM = "custom"
+
+    @classmethod
+    def named(cls, value: str | None) -> AuthenticationMode:
+        """Read a mode a deployment asked for, refusing silence.
+
+        An unset value is the case this method exists for. Defaulting it to
+        ``NONE`` would turn a forgotten environment variable into an open door, and
+        the only sign of it would be the absence of a line in a log.
+
+        ``CUSTOM`` is refused too. It is what a policy *reports* when a host supplied
+        its own authenticator in code; naming it in a configuration file asks for a
+        scheme nothing can build.
+        """
+        text = (value or "").strip().lower()
+        known = ", ".join(mode.value for mode in cls if mode is not cls.CUSTOM)
+
+        if not text:
+            raise AuthenticationConfigurationError(
+                f"no authentication mode was configured: name one of {known}. "
+                "Serving without authentication is a decision, so it has to be written down as 'none'"
+            )
+
+        if text == cls.CUSTOM.value:
+            raise AuthenticationConfigurationError(
+                f"authentication mode 'custom' cannot be configured: it is what a policy reports "
+                f"when a host passes its own authenticator to AuthenticationPolicy.of(). "
+                f"Expected one of {known}"
+            )
+
+        try:
+            return cls(text)
+        except ValueError as error:
+            raise AuthenticationConfigurationError(
+                f"unknown authentication mode {text!r}: expected one of {known}"
+            ) from error
+
+
+class AuthenticationPolicy:
+    """The schemes a host accepts, and whether a credential is required.
+
+    Built through a named constructor rather than a keyword-argument soup, so that
+    reading the composition root tells you the security posture of the service
+    without having to work out what an omitted argument meant.
+    """
+
+    def __init__(self, mode: AuthenticationMode, authenticators: tuple[Authenticator, ...]) -> None:
+        self._mode = mode
+        self._authenticators = authenticators
+
+    @property
+    def mode(self) -> AuthenticationMode:
+        """Which scheme family this policy was built for."""
+        return self._mode
+
+    @property
+    def authenticators(self) -> tuple[Authenticator, ...]:
+        """The schemes, in the order they are tried."""
+        return self._authenticators
+
+    @property
+    def requires_authentication(self) -> bool:
+        """Whether a request without a credential is refused."""
+        return self._mode is not AuthenticationMode.NONE
+
+    @classmethod
+    def anonymous(cls) -> Self:
+        """Serve everyone, deliberately.
+
+        Legitimate for a server exposing public, read-only data. Not legitimate as
+        the consequence of an unset variable, which is why it has a name.
+        """
+        return cls(AuthenticationMode.NONE, ())
+
+    @classmethod
+    def api_key(
+        cls,
+        resolver: ApiKeyUserResolver,
+        *,
+        header_name: str = ApiKeyAuthenticator.DEFAULT_HEADER_NAME,
+        scheme: str = "",
+    ) -> Self:
+        """Authenticate a key, and let the host decide who that key is.
+
+        ``scheme`` covers the deployments that carry their key in an
+        ``Authorization`` header - the mail MCP server presents its shared secret
+        as ``Bearer <secret>``. Leave it empty and the raw header value is the key.
+        """
+        return cls(
+            AuthenticationMode.API_KEY,
+            (ApiKeyAuthenticator(resolver, header_name=header_name, scheme=scheme),),
+        )
+
+    @classmethod
+    def jwt(cls, validation: JwtValidationConfig) -> Self:
+        """Validate a bearer token against an issuer's published keys."""
+        return cls(AuthenticationMode.JWT, (JwtAuthenticator(validation),))
+
+    @classmethod
+    def of(cls, *authenticators: Authenticator) -> Self:
+        """Accept schemes the host supplies itself.
+
+        The extension point. Basic, Kerberos or mutual TLS are implementations of
+        :class:`Authenticator` written outside this package; none of them requires a
+        change here.
+
+        Order is precedence: the first authenticator claiming a request wins.
+        """
+        if not authenticators:
+            raise AuthenticationConfigurationError(
+                "no authentication scheme was supplied: pass at least one authenticator, "
+                "or say AuthenticationPolicy.anonymous() if serving everyone is the intent"
+            )
+        return cls(AuthenticationMode.CUSTOM, tuple(authenticators))
+
+    def build(self) -> RequestAuthenticator:
+        """Assemble the chain a transport runs against every request."""
+        return RequestAuthenticator(
+            list(self._authenticators),
+            require_authentication=self.requires_authentication,
+        )
+
+    def describe(self) -> str:
+        """One line for a start-up log, naming the posture rather than implying it."""
+        if self._mode is AuthenticationMode.NONE:
+            return "anonymous: every caller is served, no credential is checked"
+
+        schemes = ", ".join(authenticator.auth_type for authenticator in self._authenticators)
+        return f"authenticated: {schemes}"