ygo74-agent-runtime-security 0.1.0__tar.gz

ygo74_agent_runtime_security-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: ygo74-agent-runtime-security
+Version: 0.1.0
+Summary: Security and authentication foundation of the ygo74 agent runtime
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.7
+Requires-Dist: PyJWT>=2.8

ygo74_agent_runtime_security-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ygo74-agent-runtime-security"
+version = "0.1.0"
+description = "Security and authentication foundation of the ygo74 agent runtime"
+# 3.12 is the floor the shipped code needs.
+requires-python = ">=3.12"
+
+# The foundation of the runtime: the security model (permissions, user context,
+# operation classification, security floor, audit, untrusted content) and the
+# authentication schemes (API key with a pluggable user resolver, JWT against an
+# OIDC issuer, and the `Authenticator` protocol a host extends).
+#
+# It depends on no other domain of this runtime, which is what lets an agent host
+# and an MCP server host share one authentication model instead of growing two.
+dependencies = [
+  "pydantic>=2.7",
+  # `domains.auth.jwt_authenticator` validates tokens against a published key set.
+  "PyJWT>=2.8",
+]
+
+[tool.setuptools.packages.find]
+include = ["ygo74*"]
+namespaces = true
+
+# `ygo74`, `ygo74.agent_runtime` and `ygo74.agent_runtime.domains` are namespace
+# portions shared with the other distributions, so the typing marker cannot sit at
+# any of those levels - two distributions shipping the same path would collide.
+# It goes in each domain this distribution alone owns. Without it a consumer's type
+# checker silently treats every type here as `Any`, which is exactly the wrong
+# place to lose type safety.
+[tool.setuptools.package-data]
+"ygo74.agent_runtime.domains.security" = ["py.typed"]
+"ygo74.agent_runtime.domains.auth" = ["py.typed"]

ygo74_agent_runtime_security-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ygo74_agent_runtime_security-0.1.0/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_security-0.1.0/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_security-0.1.0/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_security-0.1.0/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)