nat-engine 1__py3-none-any.whl

mannf/product/integrations/auth.py

@@ -0,0 +1,190 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Pluggable authentication strategies for :class:`HttpApiSUT`.
+
+Each strategy implements :meth:`AuthStrategy.apply` which receives the
+``kwargs`` dict that will be forwarded to ``httpx.AsyncClient.request`` and
+returns a (possibly modified) copy with the appropriate credentials injected.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any
+
+
+class AuthStrategy(ABC):
+    """Base class for pluggable authentication strategies."""
+
+    @abstractmethod
+    async def apply(self, request_kwargs: Dict[str, Any]) -> Dict[str, Any]:
+        """Inject authentication credentials into *request_kwargs*.
+
+        Parameters
+        ----------
+        request_kwargs:
+            The keyword arguments that will be passed to
+            ``httpx.AsyncClient.request``.  This method should return a
+            (possibly new) dict with credentials added.
+
+        Returns
+        -------
+        dict
+            Modified request kwargs with credentials applied.
+        """
+
+
+class NoAuth(AuthStrategy):
+    """Passthrough strategy — no authentication is applied."""
+
+    async def apply(self, request_kwargs: Dict[str, Any]) -> Dict[str, Any]:
+        return request_kwargs
+
+
+class ApiKeyAuth(AuthStrategy):
+    """Adds an API key to a request header.
+
+    Parameters
+    ----------
+    key:
+        The API key value.
+    header_name:
+        The HTTP header name to use (default: ``"X-API-Key"``).
+    """
+
+    def __init__(self, key: str, header_name: str = "X-API-Key") -> None:
+        self.key = key
+        self.header_name = header_name
+
+    async def apply(self, request_kwargs: Dict[str, Any]) -> Dict[str, Any]:
+        kwargs = dict(request_kwargs)
+        headers = dict(kwargs.get("headers") or {})
+        headers[self.header_name] = self.key
+        kwargs["headers"] = headers
+        return kwargs
+
+
+class BearerTokenAuth(AuthStrategy):
+    """Adds a Bearer token to the ``Authorization`` header.
+
+    Parameters
+    ----------
+    token:
+        The bearer token value (without the ``Bearer `` prefix).
+    """
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    async def apply(self, request_kwargs: Dict[str, Any]) -> Dict[str, Any]:
+        kwargs = dict(request_kwargs)
+        headers = dict(kwargs.get("headers") or {})
+        headers["Authorization"] = f"Bearer {self.token}"
+        kwargs["headers"] = headers
+        return kwargs
+
+
+class OAuth2Auth(AuthStrategy):
+    """OAuth2 authentication with automatic token refresh.
+
+    Supports ``client_credentials`` and ``password`` grant flows.
+    Caches the token and refreshes automatically on expiry.
+
+    Parameters
+    ----------
+    token_url:
+        URL of the OAuth2 token endpoint.
+    client_id:
+        OAuth2 client ID.
+    client_secret:
+        OAuth2 client secret.
+    scopes:
+        List of OAuth2 scopes to request.
+    grant_type:
+        OAuth2 grant type — ``"client_credentials"`` (default) or ``"password"``.
+    username:
+        Resource-owner username (required for ``password`` grant).
+    password:
+        Resource-owner password (required for ``password`` grant).
+    """
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scopes: list = None,
+        grant_type: str = "client_credentials",
+        username: str = None,
+        password: str = None,
+    ) -> None:
+        import time as _time_mod  # noqa: PLC0415 — stored for test injection
+        self.token_url = token_url
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.scopes: list = scopes or []
+        self.grant_type = grant_type
+        self.username = username
+        self.password = password
+        self._access_token: str | None = None
+        self._token_expiry: float = 0.0
+        self._time = _time_mod  # stored for easier unit-testing
+
+    async def refresh_token(self) -> str:
+        """Fetch a new access token via an httpx POST to ``token_url``.
+
+        Parses ``access_token`` and ``expires_in`` from the JSON response and
+        caches the result with a 10 % safety margin on the expiry time.
+
+        Returns
+        -------
+        str
+            The new access token.
+
+        Raises
+        ------
+        ValueError
+            If the token endpoint returns a non-2xx response.
+        """
+        import httpx
+
+        data: Dict[str, Any] = {
+            "grant_type": self.grant_type,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+        if self.scopes:
+            data["scope"] = " ".join(self.scopes)
+        if self.grant_type == "password":
+            data["username"] = self.username or ""
+            data["password"] = self.password or ""
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(self.token_url, data=data)
+
+        if response.status_code >= 400:
+            raise ValueError(
+                f"OAuth2 token request failed with status {response.status_code}: "
+                f"{response.text}"
+            )
+
+        payload = response.json()
+        self._access_token = payload["access_token"]
+        expires_in: float = float(payload.get("expires_in", 3600))
+        # Use 90 % of the lifetime so we refresh before the token actually expires
+        self._token_expiry = self._time.monotonic() + expires_in * 0.9
+        return self._access_token
+
+    async def apply(self, request_kwargs: Dict[str, Any]) -> Dict[str, Any]:
+        """Add an OAuth2 Bearer token, refreshing automatically if expired."""
+        if self._access_token is None or self._time.monotonic() >= self._token_expiry:
+            await self.refresh_token()
+
+        kwargs = dict(request_kwargs)
+        headers = dict(kwargs.get("headers") or {})
+        headers["Authorization"] = f"Bearer {self._access_token}"
+        kwargs["headers"] = headers
+        return kwargs

mannf/product/integrations/graphql_parser.py

@@ -0,0 +1,436 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""GraphQL introspection parser and test-case generator.
+
+Parses the result of a standard GraphQL introspection query into
+:class:`GraphQLSchema` and produces :class:`~mannf.core.testing.models.TestCase`
+objects that exercise the schema in both positive and negative ways.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from mannf.core.testing.models import TestCase
+
+if TYPE_CHECKING:
+    from mannf.product.llm.base import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GraphQLArg:
+    """A single argument on a GraphQL field or operation."""
+
+    name: str
+    type_name: str
+    is_required: bool
+    default_value: Any = None
+
+
+@dataclass
+class GraphQLField:
+    """A field belonging to a GraphQL type."""
+
+    name: str
+    type_name: str
+    is_required: bool
+    is_list: bool
+    args: List[GraphQLArg] = field(default_factory=list)
+
+
+@dataclass
+class GraphQLOperation:
+    """A top-level query or mutation in the schema."""
+
+    name: str
+    kind: str  # "query" | "mutation"
+    args: List[GraphQLArg] = field(default_factory=list)
+    return_type: str = ""
+
+
+@dataclass
+class GraphQLSchema:
+    """Parsed representation of a GraphQL schema."""
+
+    query_type: str
+    mutation_type: Optional[str]
+    subscription_type: Optional[str]
+    types: Dict[str, List[GraphQLField]]
+    queries: List[GraphQLOperation]
+    mutations: List[GraphQLOperation]
+
+
+def _unwrap_type(type_ref: Optional[dict]) -> tuple[str, bool, bool]:
+    """Recursively unwrap NON_NULL / LIST wrappers.
+
+    Returns
+    -------
+    (type_name, is_required, is_list)
+    """
+    if type_ref is None:
+        return ("", False, False)
+
+    is_required = False
+    is_list = False
+
+    node = type_ref
+    while node:
+        kind = node.get("kind", "")
+        if kind == "NON_NULL":
+            is_required = True
+            node = node.get("ofType")
+        elif kind == "LIST":
+            is_list = True
+            node = node.get("ofType")
+        else:
+            return (node.get("name") or "", is_required, is_list)
+
+    return ("", is_required, is_list)
+
+
+def _parse_args(raw_args: list) -> List[GraphQLArg]:
+    result: List[GraphQLArg] = []
+    for arg in raw_args or []:
+        name = arg.get("name", "")
+        type_name, is_required, _ = _unwrap_type(arg.get("type"))
+        default_value = arg.get("defaultValue")
+        result.append(GraphQLArg(name=name, type_name=type_name, is_required=is_required, default_value=default_value))
+    return result
+
+
+class GraphQLParser:
+    """Parse GraphQL introspection results and generate test cases.
+
+    Parameters
+    ----------
+    introspection_result:
+        The raw dict returned by a ``{ __schema { ... } }`` introspection query.
+    """
+
+    def __init__(self, introspection_result: dict, llm_provider: Optional["LLMProvider"] = None) -> None:
+        self._raw = introspection_result
+        self.llm_provider = llm_provider
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def parse(self) -> GraphQLSchema:
+        """Parse the introspection result into a :class:`GraphQLSchema`."""
+        data = self._raw.get("data") or self._raw
+        schema = data.get("__schema") or {}
+
+        query_type = (schema.get("queryType") or {}).get("name") or "Query"
+        mutation_type_info = schema.get("mutationType")
+        mutation_type: Optional[str] = (mutation_type_info or {}).get("name") if mutation_type_info else None
+        subscription_type_info = schema.get("subscriptionType")
+        subscription_type: Optional[str] = (subscription_type_info or {}).get("name") if subscription_type_info else None
+
+        types: Dict[str, List[GraphQLField]] = {}
+        queries: List[GraphQLOperation] = []
+        mutations: List[GraphQLOperation] = []
+
+        for type_def in schema.get("types") or []:
+            type_name = type_def.get("name") or ""
+            # Skip built-in introspection types
+            if type_name.startswith("__"):
+                continue
+            if type_def.get("kind") not in ("OBJECT", "INTERFACE"):
+                continue
+
+            fields: List[GraphQLField] = []
+            for f in type_def.get("fields") or []:
+                field_name = f.get("name") or ""
+                field_type_name, field_required, field_list = _unwrap_type(f.get("type"))
+                field_args = _parse_args(f.get("args") or [])
+                fields.append(
+                    GraphQLField(
+                        name=field_name,
+                        type_name=field_type_name,
+                        is_required=field_required,
+                        is_list=field_list,
+                        args=field_args,
+                    )
+                )
+
+            types[type_name] = fields
+
+            # Register query/mutation operations
+            if type_name == query_type:
+                for gf in fields:
+                    queries.append(
+                        GraphQLOperation(
+                            name=gf.name,
+                            kind="query",
+                            args=gf.args,
+                            return_type=gf.type_name,
+                        )
+                    )
+            elif mutation_type and type_name == mutation_type:
+                for gf in fields:
+                    mutations.append(
+                        GraphQLOperation(
+                            name=gf.name,
+                            kind="mutation",
+                            args=gf.args,
+                            return_type=gf.type_name,
+                        )
+                    )
+
+        return GraphQLSchema(
+            query_type=query_type,
+            mutation_type=mutation_type,
+            subscription_type=subscription_type,
+            types=types,
+            queries=queries,
+            mutations=mutations,
+        )
+
+    def generate_test_cases(self, schema: GraphQLSchema, base_url: str) -> List[TestCase]:
+        """Generate :class:`~mannf.core.testing.models.TestCase` objects from *schema*.
+
+        For each operation the following cases are generated:
+
+        * **valid** — query with sensible variable placeholders.
+        * **missing required vars** — query without required variables.
+        * **wrong type vars** — query with invalid variable types.
+        * **depth attack** — deeply nested query (10 levels).
+        * **batch query** — array of 5 identical queries.
+        * **introspection** — probe to detect whether introspection is exposed.
+        """
+        cases: List[TestCase] = []
+
+        for op in schema.queries + schema.mutations:
+            # -- positive case --------------------------------------------------
+            valid_query = self._build_operation_query(op)
+            valid_vars = self._build_valid_variables(op)
+            cases.append(
+                TestCase(
+                    target=base_url,
+                    inputs={
+                        "method": "POST",
+                        "json": {"query": valid_query, "variables": valid_vars},
+                        "expected_status_codes": [200],
+                    },
+                    expected_behavior=f"Valid {op.kind} '{op.name}' returns 200 with data",
+                    metadata={"operation": op.name, "case_type": "valid"},
+                )
+            )
+
+            # -- missing required variables -------------------------------------
+            if any(a.is_required for a in op.args):
+                cases.append(
+                    TestCase(
+                        target=base_url,
+                        inputs={
+                            "method": "POST",
+                            "json": {"query": valid_query, "variables": {}},
+                            "expected_status_codes": [200],
+                        },
+                        expected_behavior=(
+                            f"'{op.name}' with missing required variables returns "
+                            "200 with GraphQL errors"
+                        ),
+                        metadata={"operation": op.name, "case_type": "missing_vars"},
+                    )
+                )
+
+            # -- wrong type variables -------------------------------------------
+            wrong_vars = self._build_wrong_type_variables(op)
+            if wrong_vars:
+                cases.append(
+                    TestCase(
+                        target=base_url,
+                        inputs={
+                            "method": "POST",
+                            "json": {"query": valid_query, "variables": wrong_vars},
+                            "expected_status_codes": [200],
+                        },
+                        expected_behavior=(
+                            f"'{op.name}' with wrong-type variables returns "
+                            "200 with GraphQL errors"
+                        ),
+                        metadata={"operation": op.name, "case_type": "wrong_type"},
+                    )
+                )
+
+        # -- depth attack (schema-independent) ----------------------------------
+        depth_query = self._build_depth_query(10)
+        cases.append(
+            TestCase(
+                target=base_url,
+                inputs={
+                    "method": "POST",
+                    "json": {"query": depth_query},
+                    "expected_status_codes": [200],
+                },
+                expected_behavior="Deeply nested query should be rejected or limited by the server",
+                metadata={"case_type": "depth_attack"},
+            )
+        )
+
+        # -- batch query --------------------------------------------------------
+        first_op_query = "{ __typename }"
+        if schema.queries:
+            first_op_query = self._build_operation_query(schema.queries[0])
+        batch = [{"query": first_op_query} for _ in range(5)]
+        cases.append(
+            TestCase(
+                target=base_url,
+                inputs={
+                    "method": "POST",
+                    "json": batch,
+                    "expected_status_codes": [200],
+                },
+                expected_behavior="Batch of 5 queries — server should limit batching",
+                metadata={"case_type": "batch_query"},
+            )
+        )
+
+        # -- introspection probe ------------------------------------------------
+        introspection_query = "{ __schema { types { name } } }"
+        cases.append(
+            TestCase(
+                target=base_url,
+                inputs={
+                    "method": "POST",
+                    "json": {"query": introspection_query},
+                    "expected_status_codes": [200],
+                },
+                expected_behavior="Introspection query — production endpoints should disable this",
+                metadata={"case_type": "introspection"},
+            )
+        )
+
+        return cases
+
+    async def generate_test_cases_with_llm(
+        self, schema: GraphQLSchema, base_url: str
+    ) -> List[TestCase]:
+        """Generate test cases and augment with LLM-generated cases when available.
+
+        Falls back to :meth:`generate_test_cases` when no LLM provider is
+        configured or when it is unavailable (fail-safe).
+        """
+        cases = self.generate_test_cases(schema, base_url)
+
+        if self.llm_provider is None or not self.llm_provider.is_available():
+            return cases
+
+        for op in schema.queries + schema.mutations:
+            try:
+                endpoint_info = {
+                    "method": "POST",
+                    "path": base_url,
+                    "description": f"GraphQL {op.kind} '{op.name}'",
+                    "parameters": [
+                        {"name": a.name, "type": a.type_name, "required": a.is_required}
+                        for a in op.args
+                    ],
+                    "schema": {
+                        "operation_name": op.name,
+                        "kind": op.kind,
+                        "return_type": op.return_type,
+                    },
+                }
+                raw_cases = await self.llm_provider.generate_test_cases(
+                    endpoint_info, {}, n=3
+                )
+                for raw in raw_cases:
+                    if not isinstance(raw, dict):
+                        continue
+                    inputs = raw.get("inputs", {})
+                    if not isinstance(inputs, dict):
+                        inputs = {}
+                    inputs.setdefault("method", "POST")
+                    cases.append(
+                        TestCase(
+                            target=base_url,
+                            inputs=inputs,
+                            expected_behavior=raw.get(
+                                "expected_behavior", f"[llm] {op.kind} '{op.name}'"
+                            ),
+                            metadata={
+                                "operation": op.name,
+                                "case_type": raw.get("test_type", "llm"),
+                                "generator": "llm",
+                                "generation_strategy": "llm_edge_case",
+                            },
+                        )
+                    )
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "GraphQLParser: LLM generation failed for %s '%s': %s",
+                    op.kind, op.name, exc,
+                )
+
+        return cases
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _build_operation_query(op: GraphQLOperation) -> str:
+        """Build a minimal valid GraphQL operation string."""
+        if op.args:
+            arg_str = ", ".join(
+                f"${a.name}: {a.type_name}{'!' if a.is_required else ''}"
+                for a in op.args
+            )
+            pass_str = ", ".join(f"{a.name}: ${a.name}" for a in op.args)
+            return (
+                f"{op.kind} ({arg_str}) {{ "
+                f"{op.name}({pass_str}) {{ id name }} }}"
+            )
+        return f"{{ {op.name} {{ id name }} }}"
+
+    @staticmethod
+    def _build_valid_variables(op: GraphQLOperation) -> dict:
+        """Build a variables dict with sensible placeholder values."""
+        vars_: dict = {}
+        for arg in op.args:
+            tn = (arg.type_name or "").upper()
+            if "INT" in tn:
+                vars_[arg.name] = 1
+            elif "FLOAT" in tn or "DOUBLE" in tn:
+                vars_[arg.name] = 1.0
+            elif "BOOL" in tn:
+                vars_[arg.name] = True
+            elif "ID" in tn:
+                vars_[arg.name] = "1"
+            else:
+                vars_[arg.name] = "test"
+        return vars_
+
+    @staticmethod
+    def _build_wrong_type_variables(op: GraphQLOperation) -> dict:
+        """Build a variables dict where values have the wrong type."""
+        vars_: dict = {}
+        for arg in op.args:
+            tn = (arg.type_name or "").upper()
+            if "INT" in tn or "FLOAT" in tn:
+                vars_[arg.name] = "not-a-number"
+            elif "BOOL" in tn:
+                vars_[arg.name] = "not-a-bool"
+            elif "ID" in tn:
+                vars_[arg.name] = {"nested": "object"}
+            else:
+                vars_[arg.name] = 12345
+        return vars_
+
+    @staticmethod
+    def _build_depth_query(depth: int) -> str:
+        """Build a deeply nested query string *depth* levels deep."""
+        inner = "id"
+        field_name = "a"
+        for _ in range(depth):
+            inner = f"{field_name} {{ {inner} }}"
+        return f"{{ {inner} }}"