agent-easy-framework 0.0.3__py3-none-any.whl

agent_server/auth/base.py

@@ -0,0 +1,67 @@
+"""Pluggable authentication.
+
+Auth providers validate inbound credentials and return a :class:`Principal`, or
+raise :class:`AuthError`. They register by name and are selected per profile via
+``server.auth.provider`` - the same plugin pattern as secrets and data sources.
+Enforced on the HTTP and gRPC transports; stdio is a trusted local channel.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+
+class AuthError(Exception):
+    """Raised when authentication fails."""
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """The authenticated caller."""
+
+    subject: str
+    claims: Mapping[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class AuthProvider(Protocol):
+    """Validates credentials carried in transport headers/metadata."""
+
+    async def authenticate(self, headers: Mapping[str, str]) -> Principal:
+        """Return the Principal for valid credentials, else raise AuthError."""
+        ...
+
+
+AuthProviderFactory = Callable[[Mapping[str, Any]], AuthProvider]
+
+_REGISTRY: dict[str, AuthProviderFactory] = {}
+
+
+def register_auth_provider(
+    name: str,
+) -> Callable[[AuthProviderFactory], AuthProviderFactory]:
+    """Register an auth provider factory under ``name``."""
+
+    def decorate(factory: AuthProviderFactory) -> AuthProviderFactory:
+        if name in _REGISTRY:
+            raise ValueError(f"Auth provider {name!r} already registered")
+        _REGISTRY[name] = factory
+        return factory
+
+    return decorate
+
+
+def build_auth_provider(name: str, options: Mapping[str, Any]) -> AuthProvider:
+    """Instantiate a registered auth provider by name."""
+    try:
+        factory = _REGISTRY[name]
+    except KeyError as exc:
+        known = ", ".join(sorted(_REGISTRY)) or "<none>"
+        raise KeyError(f"Unknown auth provider {name!r}. Registered: {known}") from exc
+    return factory(options)
+
+
+def registered_auth_providers() -> tuple[str, ...]:
+    return tuple(sorted(_REGISTRY))

agent_server/auth/basic.py

@@ -0,0 +1,95 @@
+"""Ephemeral API-key authentication for local testing.
+
+This provider generates a fresh, random API key at construction time and
+accepts only that key. It exists so that a freshly scaffolded server can be
+exercised over an authenticated transport without standing up a real identity
+provider.
+
+It is deliberately **not** production-safe: the key lives only in process
+memory, rotates on every restart, and is printed to the logs. To make that
+impossible to miss, construction emits a loud, bordered WARNING that repeats
+the key and states it is for testing only. Real deployments must select the
+``oidc`` provider instead.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from collections.abc import Mapping
+from typing import Any
+
+from agent_server.auth.base import (
+    AuthError,
+    AuthProvider,
+    Principal,
+    register_auth_provider,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize(headers: Mapping[str, str]) -> dict[str, str]:
+    """Return a case-insensitive view of ``headers`` keyed by lower-case name."""
+    return {key.lower(): value for key, value in headers.items()}
+
+
+class BasicAuthProvider:
+    """Accept a single, runtime-generated API key.
+
+    The key is created with :func:`secrets.token_urlsafe` and compared in
+    constant time. Callers may present it as either ``Authorization: Bearer
+    <key>`` or ``X-Api-Key: <key>``.
+    """
+
+    def __init__(self, *, subject: str = "test-user") -> None:
+        self.subject = subject
+        self.api_key: str = secrets.token_urlsafe(32)
+        self._warn_testing_only()
+
+    def _warn_testing_only(self) -> None:
+        """Emit a hard-to-miss warning so the ephemeral key is never trusted."""
+        border = "=" * 72
+        logger.warning(
+            "\n%s\n"
+            "BasicAuthProvider generated an ephemeral API key:\n"
+            "    %s\n"
+            "FOR TESTING PURPOSES ONLY - DO NOT USE IN PRODUCTION.\n"
+            "%s",
+            border,
+            self.api_key,
+            border,
+        )
+
+    async def authenticate(self, headers: Mapping[str, str]) -> Principal:
+        """Validate the presented key and return the configured principal.
+
+        Raises :class:`AuthError` when no key is supplied or it does not match.
+        """
+        presented = self._extract_key(headers)
+        if presented is None or not secrets.compare_digest(presented, self.api_key):
+            raise AuthError("Invalid or missing API key")
+        return Principal(
+            subject=self.subject,
+            claims={"auth": "basic", "testing_only": True},
+        )
+
+    @staticmethod
+    def _extract_key(headers: Mapping[str, str]) -> str | None:
+        """Read the key from an ``Authorization`` bearer or ``X-Api-Key`` header."""
+        normalized = _normalize(headers)
+        api_key = normalized.get("x-api-key")
+        if api_key:
+            return api_key.strip()
+        value = normalized.get("authorization")
+        if value:
+            scheme, _, token = value.partition(" ")
+            if scheme.lower() == "bearer" and token.strip():
+                return token.strip()
+        return None
+
+
+@register_auth_provider("basic")
+def _build(options: Mapping[str, Any]) -> AuthProvider:
+    """Construct a :class:`BasicAuthProvider` from profile options."""
+    return BasicAuthProvider(subject=options.get("subject", "test-user"))

agent_server/auth/none.py

@@ -0,0 +1,28 @@
+"""The default 'no authentication' provider.
+
+Selected when ``server.auth.provider`` is ``none`` (the default). Every request
+is accepted as an anonymous principal. Appropriate for stdio and trusted
+internal networks; production HTTP/gRPC deployments should select ``oidc``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from agent_server.auth.base import AuthProvider, Principal, register_auth_provider
+
+
+class NoAuthProvider:
+    """Accept every caller as anonymous."""
+
+    async def authenticate(self, headers: Mapping[str, str]) -> Principal:
+        # No credentials are inspected; every caller is anonymous. We bind the
+        # parameter explicitly so the interface stays honest under all builds.
+        _ = headers
+        return Principal(subject="anonymous", claims={})
+
+
+@register_auth_provider("none")
+def _build(options: Mapping[str, Any]) -> AuthProvider:
+    return NoAuthProvider()

agent_server/auth/oidc.py

@@ -0,0 +1,114 @@
+"""OIDC / OAuth2 bearer-JWT authentication.
+
+Validates inbound ``Authorization: Bearer <jwt>`` credentials against an
+OpenID Connect / OAuth2 identity provider. Signing keys are fetched from the
+issuer's JWKS endpoint and the token is verified for signature, ``audience``,
+and ``issuer``. This is the recommended provider for production HTTP/gRPC
+deployments.
+
+The heavy dependencies (``PyJWT`` and its crypto backend, plus the JWKS HTTP
+client) are imported lazily inside :meth:`OidcAuthProvider.authenticate`. A
+bootstrap importer loads every provider module unconditionally, so importing
+this module must never require the optional ``oidc`` extra to be installed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from agent_server.auth.base import (
+    AuthError,
+    AuthProvider,
+    Principal,
+    register_auth_provider,
+)
+
+if TYPE_CHECKING:
+    from jwt import PyJWKClient
+
+
+def _normalize(headers: Mapping[str, str]) -> dict[str, str]:
+    """Return a case-insensitive view of ``headers`` keyed by lower-case name."""
+    return {key.lower(): value for key, value in headers.items()}
+
+
+class OidcAuthProvider:
+    """Authenticate callers via signed OIDC/OAuth2 bearer JWTs.
+
+    The JWKS client is created on first use and cached on the instance so that
+    signing keys are reused across requests (PyJWKClient performs its own key
+    caching internally).
+    """
+
+    def __init__(
+        self,
+        *,
+        issuer: str,
+        audience: str,
+        jwks_uri: str,
+        algorithms: Sequence[str] | None = None,
+    ) -> None:
+        self.issuer = issuer
+        self.audience = audience
+        self.jwks_uri = jwks_uri
+        self.algorithms: list[str] = list(algorithms) if algorithms else ["RS256"]
+        self._jwks_client: PyJWKClient | None = None
+
+    def _client(self) -> PyJWKClient:
+        """Lazily construct and cache the JWKS client."""
+        if self._jwks_client is None:
+            from jwt import PyJWKClient  # noqa: PLC0415
+
+            self._jwks_client = PyJWKClient(self.jwks_uri)
+        return self._jwks_client
+
+    async def authenticate(self, headers: Mapping[str, str]) -> Principal:
+        """Validate the bearer JWT and return the caller's :class:`Principal`.
+
+        Raises :class:`AuthError` if the ``Authorization`` header is missing or
+        malformed, or if signature/claim verification fails.
+        """
+        token = self._extract_bearer(headers)
+
+        import jwt  # noqa: PLC0415
+
+        try:
+            signing_key = self._client().get_signing_key_from_jwt(token)
+            claims: dict[str, Any] = jwt.decode(
+                token,
+                signing_key.key,
+                algorithms=self.algorithms,
+                audience=self.audience,
+                issuer=self.issuer,
+            )
+        except Exception as exc:
+            raise AuthError("OIDC token verification failed") from exc
+
+        subject = claims.get("sub")
+        if not isinstance(subject, str) or not subject:
+            raise AuthError("OIDC token missing 'sub' claim")
+        return Principal(subject=subject, claims=claims)
+
+    @staticmethod
+    def _extract_bearer(headers: Mapping[str, str]) -> str:
+        """Pull the raw token out of an ``Authorization: Bearer <token>`` header."""
+        normalized = _normalize(headers)
+        value = normalized.get("authorization")
+        if not value:
+            raise AuthError("Missing Authorization header")
+        scheme, _, token = value.partition(" ")
+        if scheme.lower() != "bearer" or not token.strip():
+            raise AuthError("Malformed Authorization header; expected 'Bearer <token>'")
+        return token.strip()
+
+
+@register_auth_provider("oidc")
+def _build(options: Mapping[str, Any]) -> AuthProvider:
+    """Construct an :class:`OidcAuthProvider` from profile options."""
+    return OidcAuthProvider(
+        issuer=options["issuer"],
+        audience=options["audience"],
+        jwks_uri=options["jwks_uri"],
+        algorithms=options.get("algorithms"),
+    )

agent_server/bootstrap.py

@@ -0,0 +1,32 @@
+"""Import-time registration of all pluggable components.
+
+Calling :func:`bootstrap` imports every provider and tool module so their
+``@register_*`` / ``@tool`` side effects populate the registries. Provider
+modules must keep heavy third-party imports inside their factories (not at
+module top level) so this stays import-safe even when an optional dependency is
+not installed.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+_MODULES: tuple[str, ...] = (
+    "agent_server.config.secrets.file_provider",
+    "agent_server.auth.none",
+    "agent_server.auth.oidc",
+    "agent_server.auth.basic",
+    "agent_server.datasources.postgres",
+    "agent_server.datasources.neo4j",
+    "agent_server.core.tools",
+)
+
+_imported: set[str] = set()
+
+
+def bootstrap() -> None:
+    """Idempotently import all registration modules."""
+    for module in _MODULES:
+        if module not in _imported:
+            importlib.import_module(module)
+            _imported.add(module)

agent_server/checks/__init__.py

@@ -0,0 +1,12 @@
+"""Golden-path fact-checks: importable invariants for an agent-server project.
+
+These checks codify what it means for a project scaffolded by this framework to
+stay on the golden path. They are deliberately importable (not just a script) so
+pre-commit, ``make factcheck``, and tests can all share one implementation.
+"""
+
+from __future__ import annotations
+
+from agent_server.checks.invariants import Problem, check_project
+
+__all__ = ["Problem", "check_project"]

agent_server/checks/invariants.py

@@ -0,0 +1,324 @@
+"""The golden-path invariants, as importable fact-check logic.
+
+:func:`check_project` runs eight invariants against a project directory and returns
+one :class:`Problem` per violation (an empty list means the project is healthy).
+The checks introspect the *running* code where structure alone cannot prove
+correctness - importing the project package, bootstrapping its registries, and
+loading every config profile. Every check degrades gracefully: if something
+cannot be loaded it reports a ``Problem`` rather than raising, so a broken
+sub-system never masks the rest of the report.
+
+The single source of truth for "the package under test" is :data:`PACKAGE`. For
+this repository that is ``agent_server``.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel
+
+PACKAGE = "agent_server"
+
+# Keys whose string values must never hold a raw secret. Matched case-insensitively
+# as a substring so e.g. ``db_password`` and ``apiKey`` are caught.
+_SECRET_KEY = re.compile(r"(password|secret|token|apikey|api_key|private_key)", re.IGNORECASE)
+# A value is acceptable iff it is purely a ``${secret:...}`` reference.
+_SECRET_REF = re.compile(r"\$\{secret:[^}]+\}")
+
+
+@dataclass(frozen=True)
+class Problem:
+    """A single invariant violation: a stable ``code`` and a human ``message``."""
+
+    code: str
+    message: str
+
+
+def check_project(project_dir: Path) -> list[Problem]:
+    """Run every golden-path invariant and collect the violations."""
+    project_dir = project_dir.resolve()
+    problems: list[Problem] = []
+    problems += _check_required_files(project_dir)
+    problems += _check_ops_endpoints()
+    problems += _check_tool_contract()
+    problems += _check_config_and_secrets(project_dir)
+    problems += _check_datasource_resolution(project_dir)
+    problems += _check_docs_in_sync()
+    problems += _check_ops_typed_responses()
+    problems += _check_transport_separation()
+    return problems
+
+
+def _check_required_files(project_dir: Path) -> list[Problem]:
+    """Invariant 1: the project layout the framework guarantees is present."""
+    problems: list[Problem] = []
+
+    base = project_dir / "config" / "base.yaml"
+    if not base.is_file():
+        problems.append(Problem("files.base_config", "config/base.yaml is missing"))
+
+    profiles = project_dir / "config" / "profiles"
+    if not profiles.is_dir():
+        problems.append(Problem("files.profiles_dir", "config/profiles/ is missing"))
+    elif not any(profiles.glob("*.yaml")) and not any(profiles.glob("*.yml")):
+        problems.append(
+            Problem("files.profiles_empty", "config/profiles/ contains no profile YAML")
+        )
+
+    src = project_dir / "src"
+    packages = (
+        [p for p in src.iterdir() if p.is_dir() and (p / "__init__.py").is_file()]
+        if src.is_dir()
+        else []
+    )
+    if not packages:
+        problems.append(Problem("files.src_package", "no src/<pkg> package with __init__.py found"))
+
+    for name in ("Makefile", ".pre-commit-config.yaml"):
+        if not (project_dir / name).is_file():
+            problems.append(Problem("files.required", f"{name} is missing"))
+
+    return problems
+
+
+def _check_ops_endpoints() -> list[Problem]:
+    """Invariant 2: the ops app exposes /health and /ready."""
+    try:
+        ctx = _build_context()
+    except Exception as exc:
+        return [Problem("ops.context", f"could not build app context: {exc}")]
+
+    try:
+        ops = importlib.import_module(f"{PACKAGE}.ops.app")
+        app = ops.create_ops_app(ctx)
+    except Exception as exc:
+        return [Problem("ops.import", f"could not build ops app: {exc}")]
+
+    paths = {getattr(route, "path", None) for route in app.routes}
+    return [
+        Problem("ops.endpoint", f"ops app does not expose {required}")
+        for required in ("/health", "/ready")
+        if required not in paths
+    ]
+
+
+def _check_tool_contract() -> list[Problem]:
+    """Invariant 3: every registered tool honours the tool contract."""
+    try:
+        registry = _registry()
+    except Exception as exc:
+        return [Problem("tools.registry", f"could not load tool registry: {exc}")]
+
+    problems: list[Problem] = []
+    for spec in registry.all():
+        label = getattr(spec, "name", None) or "<unnamed>"
+        if not getattr(spec, "name", ""):
+            problems.append(Problem("tools.name", "a tool has an empty name"))
+        if not (getattr(spec, "description", "") or "").strip():
+            problems.append(Problem("tools.description", f"tool {label!r} has no description"))
+        model = getattr(spec, "input_model", None)
+        if not (isinstance(model, type) and issubclass(model, BaseModel)):
+            problems.append(
+                Problem("tools.input_model", f"tool {label!r} input_model is not a BaseModel")
+            )
+        output = getattr(spec, "output_model", None)
+        if not (isinstance(output, type) and issubclass(output, BaseModel)):
+            problems.append(
+                Problem("tools.output_model", f"tool {label!r} output_model is not a BaseModel")
+            )
+    return problems
+
+
+def _check_config_and_secrets(project_dir: Path) -> list[Problem]:
+    """Invariant 4: every profile validates, and no raw secrets are committed."""
+    problems: list[Problem] = []
+    config_dir = project_dir / "config"
+    profiles_dir = config_dir / "profiles"
+
+    try:
+        loader = importlib.import_module(f"{PACKAGE}.config.loader")
+    except Exception as exc:
+        return [Problem("config.loader", f"could not import config loader: {exc}")]
+
+    profile_files = sorted(profiles_dir.glob("*.yaml")) + sorted(profiles_dir.glob("*.yml"))
+    for profile_file in profile_files:
+        name = profile_file.stem
+        try:
+            loader.load_config(profile=name, config_dir=config_dir, resolve_secrets=False)
+        except Exception as exc:
+            problems.append(
+                Problem("config.invalid", f"profile {name!r} fails to load/validate: {exc}")
+            )
+
+    base = config_dir / "base.yaml"
+    for yaml_file in ([base] if base.is_file() else []) + profile_files:
+        problems += _scan_for_raw_secrets(yaml_file)
+
+    return problems
+
+
+def _scan_for_raw_secrets(path: Path) -> list[Problem]:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        return [Problem("config.unreadable", f"{path.name} could not be parsed: {exc}")]
+
+    problems: list[Problem] = []
+    for key, value in _walk(data):
+        if (
+            isinstance(value, str)
+            and value.strip()
+            and _SECRET_KEY.search(key)
+            and not _SECRET_REF.fullmatch(value.strip())
+        ):
+            problems.append(
+                Problem(
+                    "secrets.raw",
+                    f"{path.name}: key {key!r} looks like a raw secret; "
+                    f"use a ${{secret:...}} reference",
+                )
+            )
+    return problems
+
+
+def _walk(node: Any, key: str = "") -> Iterator[tuple[str, Any]]:
+    """Yield ``(key, value)`` for every scalar leaf in a nested structure."""
+    if isinstance(node, dict):
+        for k, v in node.items():
+            yield from _walk(v, str(k))
+    elif isinstance(node, list):
+        for item in node:
+            yield from _walk(item, key)
+    else:
+        yield key, node
+
+
+def _check_datasource_resolution(project_dir: Path) -> list[Problem]:
+    """Invariant 5: every datasource type used in any profile is registered."""
+    config_dir = project_dir / "config"
+    profiles_dir = config_dir / "profiles"
+
+    try:
+        _bootstrap()
+        ds_base = importlib.import_module(f"{PACKAGE}.datasources.base")
+        loader = importlib.import_module(f"{PACKAGE}.config.loader")
+    except Exception as exc:
+        return [Problem("datasources.import", f"could not load datasource registry: {exc}")]
+
+    registered = set(ds_base.registered_datasources())
+    problems: list[Problem] = []
+    seen: set[tuple[str, str]] = set()
+    for profile_file in sorted(profiles_dir.glob("*.yaml")) + sorted(profiles_dir.glob("*.yml")):
+        name = profile_file.stem
+        try:
+            cfg = loader.load_config(profile=name, config_dir=config_dir, resolve_secrets=False)
+        except Exception:
+            continue
+        for ds_name, ds in cfg.server.datasources.items():
+            if ds.type in registered:
+                continue
+            marker = (name, ds.type)
+            if marker in seen:
+                continue
+            seen.add(marker)
+            problems.append(
+                Problem(
+                    "datasources.unregistered",
+                    f"profile {name!r} datasource {ds_name!r} uses unregistered type {ds.type!r}",
+                )
+            )
+    return problems
+
+
+def _check_docs_in_sync() -> list[Problem]:
+    """Invariant 6: the docs tool list covers every registered tool."""
+    try:
+        ctx = _build_context()
+        docs = importlib.import_module(f"{PACKAGE}.docs.server")
+        registry = _registry()
+    except Exception as exc:
+        return [Problem("docs.import", f"could not load docs generator: {exc}")]
+
+    documented = {str(entry["name"]) for entry in docs.tool_index(ctx)}
+    registered = set(registry.names())
+    missing = registered - documented
+    return [
+        Problem("docs.drift", f"tool {name!r} is registered but missing from the docs index")
+        for name in sorted(missing)
+    ]
+
+
+def _check_ops_typed_responses() -> list[Problem]:
+    """Invariant 7: ops endpoints declare Pydantic response models."""
+    try:
+        ctx = _build_context()
+        ops = importlib.import_module(f"{PACKAGE}.ops.app")
+        app = ops.create_ops_app(ctx)
+    except Exception as exc:
+        return [Problem("ops.import", f"could not build ops app: {exc}")]
+
+    problems: list[Problem] = []
+    for route in app.routes:
+        path = getattr(route, "path", None)
+        if path not in {"/health", "/ready", "/admin/tools"}:
+            continue
+        model = getattr(route, "response_model", None)
+        if model is None:
+            problems.append(
+                Problem("ops.response_model", f"ops route {path!r} has no response_model")
+            )
+    return problems
+
+
+def _check_transport_separation() -> list[Problem]:
+    """Invariant 8: auth stays in transport middleware; service layer stays typed."""
+    problems: list[Problem] = []
+    try:
+        mcp_app = importlib.import_module(f"{PACKAGE}.transports.mcp_app")
+        importlib.import_module(f"{PACKAGE}.transports.dispatch")
+    except Exception as exc:
+        return [Problem("transport.import", f"could not import transport modules: {exc}")]
+
+    try:
+        http = importlib.import_module(f"{PACKAGE}.transports.http")
+    except ModuleNotFoundError:
+        http = None
+
+    if http is not None and not hasattr(http, "_AuthMiddleware"):
+        problems.append(Problem("transport.auth", "HTTP transport is missing _AuthMiddleware"))
+
+    mcp_source = inspect.getsource(mcp_app)
+    if "authenticate" in mcp_source or "AuthProvider" in mcp_source:
+        problems.append(
+            Problem(
+                "transport.auth_leak",
+                "mcp_app must not perform auth; use transport middleware instead",
+            )
+        )
+
+    return problems
+
+
+def _bootstrap() -> None:
+    importlib.import_module(f"{PACKAGE}.bootstrap").bootstrap()
+
+
+def _registry() -> Any:
+    _bootstrap()
+    return importlib.import_module(f"{PACKAGE}.core.registry").get_registry()
+
+
+def _build_context() -> Any:
+    """Bootstrap registries, load the active config, and build an AppContext."""
+    _bootstrap()
+    loader = importlib.import_module(f"{PACKAGE}.config.loader")
+    context = importlib.import_module(f"{PACKAGE}.core.context")
+    return context.AppContext(loader.load_config(resolve_secrets=False))