aaa-server 0.1.0__py3-none-any.whl

aaa_server/auth.py

@@ -0,0 +1,255 @@
+"""Authentication: who is calling, and which tenant they belong to.
+
+The tenant, user and scopes of a request come ONLY from the `Principal` an `Authenticator` returns. Nothing in
+a request body, query string or header other than the credential is ever read as an identity."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+import httpx
+
+from aaa.runtime.tenancy import valid_tenant
+
+SCOPE_RUN = "run"  # start runs, read events, cancel
+SCOPE_APPROVE = "approve"  # resolve tool approvals (a separate, rarer privilege)
+SCOPE_SESSION = "session"  # sessions and their messages
+SCOPE_ADMIN = "admin"  # read the tenant's usage and quota
+ALL_SCOPES = frozenset({SCOPE_RUN, SCOPE_APPROVE, SCOPE_SESSION, SCOPE_ADMIN})
+
+
+class AuthError(Exception):
+    """The credential is missing, malformed, unknown, expired or otherwise not acceptable.
+
+    The message is for server-side logs; the HTTP response is always the same generic 401."""
+
+
+@dataclass(frozen=True)
+class Principal:
+    tenant: str
+    subject: str
+    scopes: frozenset[str] = frozenset({SCOPE_RUN, SCOPE_SESSION})
+
+    def __post_init__(self) -> None:
+        valid_tenant(self.tenant)
+        if not self.subject:
+            raise ValueError("a principal needs a subject")
+
+    def can(self, scope: str) -> bool:
+        return scope in self.scopes
+
+
+@runtime_checkable
+class Authenticator(Protocol):
+    async def authenticate(self, headers: Mapping[str, str]) -> Principal:
+        """Return the caller or raise `AuthError`. `headers` keys are lower-case."""
+        ...
+
+
+def bearer_token(headers: Mapping[str, str]) -> str:
+    raw = headers.get("authorization", "")
+    scheme, _, token = raw.partition(" ")
+    if scheme.lower() != "bearer" or not token.strip():
+        raise AuthError("missing bearer token")
+    return token.strip()
+
+
+def hash_api_key(key: str) -> str:
+    """SHA-256 hex of an API key. Keys are long random strings, so a fast hash is the right tool (there is
+    nothing to brute-force); store this, never the key."""
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class ApiKey:
+    key_hash: str
+    tenant: str
+    subject: str
+    scopes: frozenset[str] = frozenset({SCOPE_RUN, SCOPE_SESSION})
+
+
+class ApiKeyAuthenticator:
+    """Static API keys, held as hashes. Every candidate is compared in constant time, so the response time does
+    not reveal how much of a key was right or which keys exist."""
+
+    def __init__(self, keys: Sequence[ApiKey]) -> None:
+        self._keys = tuple(keys)
+
+    @classmethod
+    def from_keys(
+        cls,
+        mapping: Mapping[str, tuple[str, str] | tuple[str, str, Sequence[str]]],
+    ) -> ApiKeyAuthenticator:
+        """`{"<the key>": ("tenant", "subject"[, scopes])}` for tests and small deployments. Prefer
+        `ApiKey(key_hash=...)` entries loaded from a secret store."""
+        out = []
+        for key, spec in mapping.items():
+            tenant, subject = spec[0], spec[1]
+            scopes = frozenset(spec[2]) if len(spec) > 2 else frozenset({SCOPE_RUN, SCOPE_SESSION})  # type: ignore[misc]
+            out.append(ApiKey(hash_api_key(key), tenant, subject, scopes))
+        return cls(out)
+
+    async def authenticate(self, headers: Mapping[str, str]) -> Principal:
+        digest = hash_api_key(bearer_token(headers))
+        found: ApiKey | None = None
+        for k in self._keys:  # no early exit: every entry is compared
+            if hmac.compare_digest(k.key_hash, digest):
+                found = k
+        if found is None:
+            raise AuthError("unknown api key")
+        return Principal(found.tenant, found.subject, found.scopes)
+
+
+class JWKSKeys:
+    """Signing keys fetched from a JWKS URL and cached; an unknown `kid` triggers one refetch (rotation),
+    rate-limited so a stream of bogus tokens cannot make the server hammer the identity provider."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        client: httpx.AsyncClient | None = None,
+        ttl_s: float = 600.0,
+        min_refetch_s: float = 30.0,
+        clock: Callable[[], float] | None = None,
+    ) -> None:
+        import time
+
+        self.url, self._client, self.ttl_s, self.min_refetch_s = url, client, ttl_s, min_refetch_s
+        self._clock = clock or time.monotonic
+        self._keys: dict[str, Any] = {}
+        self._fetched = float("-inf")
+
+    async def _fetch(self) -> None:
+        from jwt import PyJWK
+
+        client = self._client or httpx.AsyncClient(timeout=10.0, trust_env=False)
+        try:
+            r = await client.get(self.url)
+            r.raise_for_status()
+            doc = r.json()
+        except (httpx.HTTPError, ValueError) as e:
+            raise AuthError(f"jwks fetch failed: {type(e).__name__}") from None
+        finally:
+            if self._client is None:
+                await client.aclose()
+        keys: dict[str, Any] = {}
+        for jwk in doc.get("keys", []):
+            if jwk.get("use") not in (None, "sig") or "kid" not in jwk:
+                continue
+            try:
+                keys[jwk["kid"]] = PyJWK(jwk).key
+            except Exception:  # noqa: BLE001, S112 - an unusable key in the set must not break the others
+                continue
+        self._keys, self._fetched = keys, self._clock()
+
+    async def key(self, kid: str) -> Any:
+        now = self._clock()
+        if (kid not in self._keys and now - self._fetched >= self.min_refetch_s) or (
+            now - self._fetched >= self.ttl_s
+        ):
+            await self._fetch()
+        try:
+            return self._keys[kid]
+        except KeyError:
+            raise AuthError("unknown signing key") from None
+
+
+@dataclass
+class JWTAuthenticator:
+    """Verifies a bearer JWT. Safe by construction:
+
+    - the algorithm allow-list is fixed by YOU (asymmetric by default); the token's own `alg` header is never trusted,
+      and `none` and the HS* family are refused unless you configure a shared `secret` (and then only HS*);
+    - `exp`, `iss` and `aud` are required and checked;
+    - the tenant, subject and scopes come from claims you name, and a token without a tenant claim is rejected."""
+
+    issuer: str
+    audience: str
+    keys: JWKSKeys | None = None
+    secret: str | None = None
+    algorithms: tuple[str, ...] = ("RS256", "ES256", "EdDSA")
+    tenant_claim: str = "tenant"
+    scope_claim: str = "scope"
+    leeway_s: float = 30.0
+    default_scopes: frozenset[str] = field(
+        default_factory=lambda: frozenset({SCOPE_RUN, SCOPE_SESSION})
+    )
+
+    def __post_init__(self) -> None:
+        if (self.keys is None) == (self.secret is None):
+            raise ValueError("give exactly one of `keys` (JWKS) or `secret` (HS256)")
+        if self.secret is not None:
+            self.algorithms = ("HS256",)
+            if len(self.secret.encode()) < 32:
+                raise ValueError("a shared JWT secret must be at least 32 bytes")
+        elif any(a.lower() == "none" or a.upper().startswith("HS") for a in self.algorithms):
+            raise ValueError("a JWKS-verified token must use an asymmetric algorithm")
+
+    async def authenticate(self, headers: Mapping[str, str]) -> Principal:
+        import jwt
+
+        token = bearer_token(headers)
+        try:
+            header = jwt.get_unverified_header(token)
+            if header.get("alg") not in self.algorithms:
+                raise AuthError("algorithm not allowed")
+            if self.keys is not None:
+                kid = header.get("kid")
+                if not isinstance(kid, str):
+                    raise AuthError("token has no kid")
+                key: Any = await self.keys.key(kid)
+            else:
+                key = self.secret
+            claims = jwt.decode(
+                token,
+                key,
+                algorithms=list(self.algorithms),
+                audience=self.audience,
+                issuer=self.issuer,
+                leeway=self.leeway_s,
+                options={"require": ["exp", "iss", "aud", "sub"]},
+            )
+        except AuthError:
+            raise
+        except jwt.PyJWTError as e:
+            raise AuthError(f"invalid token: {type(e).__name__}") from None
+        tenant = claims.get(self.tenant_claim)
+        if not isinstance(tenant, str):
+            raise AuthError("token has no tenant")
+        try:
+            valid_tenant(tenant)
+        except ValueError:
+            raise AuthError("token tenant is invalid") from None
+        raw = claims.get(self.scope_claim)
+        if raw is None:
+            scopes = self.default_scopes
+        elif isinstance(raw, str):
+            scopes = frozenset(raw.split()) & ALL_SCOPES
+        elif isinstance(raw, list):
+            scopes = frozenset(str(s) for s in raw) & ALL_SCOPES
+        else:
+            raise AuthError("token scope is malformed")
+        return Principal(tenant, str(claims["sub"]), scopes)
+
+
+__all__ = [
+    "ALL_SCOPES",
+    "SCOPE_ADMIN",
+    "SCOPE_APPROVE",
+    "SCOPE_RUN",
+    "SCOPE_SESSION",
+    "ApiKey",
+    "ApiKeyAuthenticator",
+    "AuthError",
+    "Authenticator",
+    "JWKSKeys",
+    "JWTAuthenticator",
+    "Principal",
+    "bearer_token",
+    "hash_api_key",
+]

aaa_server/cli.py

@@ -0,0 +1,100 @@
+"""`aaa-server serve module:factory` - run the server for the configuration your factory builds.
+
+The factory is a function (sync or async) returning a `ServerConfig`; it is where you choose the store, the LLM client, the
+algorithms, the authenticator and the limits. The command only adds the network listener, and listens on loopback unless you
+pass `--host`."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import inspect
+import sys
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from .app import ServerConfig, create_app
+
+
+def load_factory(spec: str) -> Callable[[], Any]:
+    module, _, attr = spec.partition(":")
+    if not module or not attr:
+        raise SystemExit("expected module:factory, e.g. myapp.server:build")
+    sys.path.insert(0, "")
+    fn = getattr(importlib.import_module(module), attr)
+    return fn if callable(fn) else (lambda: fn)
+
+
+async def _build(factory: Callable[[], Any]) -> ServerConfig:
+    cfg = factory()
+    if inspect.isawaitable(cfg):
+        cfg = await cfg
+    if not isinstance(cfg, ServerConfig):
+        raise SystemExit(f"the factory must return a ServerConfig, got {type(cfg).__name__}")
+    return cfg
+
+
+def load_config(spec: str) -> ServerConfig:
+    """Build the configuration now (for tests and sync code). The server itself builds it inside its own event loop."""
+    return asyncio.run(_build(load_factory(spec)))
+
+
+class LazyApp:
+    """An ASGI app that builds the configuration INSIDE the server's event loop, at startup. A factory that opens connection
+    pools (asyncpg, redis) must run in the loop that will use them, which `asyncio.run(factory())` before `uvicorn.run` is not."""
+
+    def __init__(self, factory: Callable[[], Any]) -> None:
+        self.factory, self.app = factory, None
+
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
+        if scope["type"] == "lifespan":
+            while True:
+                msg = await receive()
+                if msg["type"] == "lifespan.startup":
+                    try:
+                        cfg = await _build(self.factory)
+                        stack = cfg.engine
+                        await stack.__aenter__()
+                        self.app = create_app(cfg)
+                    except BaseException as e:  # noqa: BLE001 - report the failure to the server, which exits
+                        await send(
+                            {
+                                "type": "lifespan.startup.failed",
+                                "message": f"{type(e).__name__}: {e}",
+                            }
+                        )
+                        return
+                    await send({"type": "lifespan.startup.complete"})
+                elif msg["type"] == "lifespan.shutdown":
+                    await stack.__aexit__(None, None, None)
+                    await send({"type": "lifespan.shutdown.complete"})
+                    return
+        elif self.app is None:
+            raise RuntimeError("the server has not finished starting")
+        else:
+            await self.app(scope, receive, send)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="aaa-server")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sv = sub.add_parser("serve", help="run the HTTP server")
+    sv.add_argument("factory", help="module:function returning a ServerConfig")
+    sv.add_argument("--host", default="127.0.0.1", help="default: loopback only")
+    sv.add_argument("--port", type=int, default=8000)
+    a = ap.parse_args(argv)
+    import uvicorn
+
+    app = LazyApp(load_factory(a.factory))
+    if a.host not in ("127.0.0.1", "localhost", "::1"):
+        print(
+            f"warning: listening on {a.host}. Put TLS and a reverse proxy (body/header timeouts) in front; see the server guide.",
+            file=sys.stderr,
+        )
+    uvicorn.run(app, host=a.host, port=a.port, log_level="info", server_header=False)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aaa_server/mcp_http.py

@@ -0,0 +1,64 @@
+"""MCP over Streamable HTTP, served by `aaa-server` so the same authentication, tenant and rate-limit rules apply.
+
+This is the stateless subset of the transport: every POST carries one JSON-RPC message and gets one JSON answer (no sessions, no
+server-initiated messages, so `GET` is `405`). That is enough for `initialize`, `ping`, `tools/list` and `tools/call`, which is
+all a tool server needs, and it is what lets the tenant of every call come from the authenticated principal instead of from
+anything the MCP client says."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aaa.mcp.server import MCPToolServer
+
+SUPPORTED = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INVALID_PARAMS = -32700, -32600, -32601, -32602
+
+
+def _error(id_: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": id_, "error": {"code": code, "message": message}}
+
+
+async def handle(
+    core: MCPToolServer, message: Any, *, tenant: str, user: str
+) -> dict[str, Any] | None:
+    """Answer one JSON-RPC message, or `None` for a notification / client response (which get `202`)."""
+    if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
+        return _error(None, INVALID_REQUEST, "expected a JSON-RPC 2.0 object")
+    method, id_, params = message.get("method"), message.get("id"), message.get("params") or {}
+    if method is None:  # a response to something we never sent
+        return None
+    if id_ is None:  # a notification
+        return None
+    if not isinstance(method, str) or not isinstance(params, dict):
+        return _error(id_, INVALID_REQUEST, "malformed request")
+    if method == "initialize":
+        asked = params.get("protocolVersion")
+        return {
+            "jsonrpc": "2.0",
+            "id": id_,
+            "result": {
+                "protocolVersion": asked if asked in SUPPORTED else SUPPORTED[0],
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": core.name, "version": "0.1"},
+            },
+        }
+    if method == "ping":
+        return {"jsonrpc": "2.0", "id": id_, "result": {}}
+    if method == "tools/list":
+        tools = [
+            {"name": t.name, "description": t.description, "inputSchema": t.input_schema}
+            for t in core.list_tools()
+        ]
+        return {"jsonrpc": "2.0", "id": id_, "result": {"tools": tools}}
+    if method == "tools/call":
+        name, args = params.get("name"), params.get("arguments") or {}
+        if not isinstance(name, str) or not isinstance(args, dict):
+            return _error(id_, INVALID_PARAMS, "tools/call needs a name and an arguments object")
+        r = await core.call(name, args, tenant=tenant, user=user)
+        return {
+            "jsonrpc": "2.0",
+            "id": id_,
+            "result": {"content": [{"type": "text", "text": r.text}], "isError": r.is_error},
+        }
+    return _error(id_, METHOD_NOT_FOUND, f"method {method!r} is not supported")

aaa_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: aaa-server
+Version: 0.1.0
+Summary: HTTP/SSE server for AAA agents: authentication, tenant isolation, rate limits, quotas, approvals.
+Project-URL: Homepage, https://github.com/innerkorehq/AutonomousAgentArchitecture
+Project-URL: Documentation, https://innerkorehq.github.io/AutonomousAgentArchitecture/server/
+Project-URL: Source, https://github.com/innerkorehq/AutonomousAgentArchitecture/tree/master/packages/aaa-server
+Project-URL: Library, https://pypi.org/project/autonomous-agent-architecture/
+Project-URL: Changelog, https://innerkorehq.github.io/AutonomousAgentArchitecture/about/changelog/
+Project-URL: Threat model, https://innerkorehq.github.io/AutonomousAgentArchitecture/security/server/
+Project-URL: Issues, https://github.com/innerkorehq/AutonomousAgentArchitecture/issues
+Author: Innerkore Technologies
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,asgi,llm,multi-tenant,server,sse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: autonomous-agent-architecture>=0.3.1
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: jwt
+Requires-Dist: pyjwt[crypto]>=2.8; extra == 'jwt'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# aaa-server
+
+HTTP/SSE server for [AAA](https://github.com/innerkorehq/AutonomousAgentArchitecture) agents ([`autonomous-agent-architecture`](https://pypi.org/project/autonomous-agent-architecture/)): bearer authentication, tenants taken only from the credential, rate limits and quotas, server-side budgets, human approvals over HTTP, resumable event streams, plus MCP and (experimental) A2A endpoints.
+
+**Documentation:** [overview](https://innerkorehq.github.io/AutonomousAgentArchitecture/server/) · [server guide](https://innerkorehq.github.io/AutonomousAgentArchitecture/guides/server/) · [threat model](https://innerkorehq.github.io/AutonomousAgentArchitecture/security/server/) · [API reference](https://innerkorehq.github.io/AutonomousAgentArchitecture/reference/api/server/) · [library docs](https://innerkorehq.github.io/AutonomousAgentArchitecture/) · [changelog](https://innerkorehq.github.io/AutonomousAgentArchitecture/about/changelog/)
+
+```bash
+pip install aaa-server                  # needs autonomous-agent-architecture>=0.3.0 (installed automatically)
+pip install "aaa-server[jwt,redis]"    # + JWT/JWKS auth, + the shared Redis rate limiter
+```
+
+```python
+# myapp/server.py
+from aaa.algos import ToolLoop
+from aaa.runtime import Budget, Engine
+from aaa.tools import ToolRegistry
+from aaa_server import ApiKeyAuthenticator, ServerConfig
+
+async def build() -> ServerConfig:
+    engine = Engine()   # + attach your LLM and tool handlers; use Postgres in production
+    return ServerConfig(
+        engine=engine,
+        authenticator=ApiKeyAuthenticator.from_keys({"s3cret-key": ("acme", "ann")}),
+        algorithms={"agent": ToolLoop(ToolRegistry([]))},
+        budget=Budget(max_steps=20, deadline_s=60),
+    )
+```
+
+```bash
+aaa-server serve myapp.server:build     # 127.0.0.1:8000 by default
+```
+
+Read the [threat model](https://innerkorehq.github.io/AutonomousAgentArchitecture/security/server/) before exposing it: put a TLS-terminating reverse proxy in front.
+Status: **alpha (0.1)**. MIT licensed. Source: <https://github.com/innerkorehq/AutonomousAgentArchitecture/tree/master/packages/aaa-server>.

aaa_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+aaa_server/__init__.py,sha256=5Xg3Da6oOw6ySZ-EmZkPs1ki1DU7Qq2fHEhofOM51oA,978
+aaa_server/a2a.py,sha256=pFUgvXeL-2BdZhkvfGYM4mMfUbEdL6PTXSEVZ9ScSO0,14380
+aaa_server/admission.py,sha256=5zTN3zO5mKjT2eGzzQnVmweO7jvNS8bVvK-ufvAv4Kk,9086
+aaa_server/app.py,sha256=Fh0e0PIhl0nX1wp2U-sFm4aNaixgwmIp9Eg5Ws5eJ9A,30738
+aaa_server/auth.py,sha256=YsQ-B5sH5r9wDa3VlnjevEzAcU3zGaNb8YRisKkIghg,9303
+aaa_server/cli.py,sha256=LKT_4vyIPY9VOWqXib5TXxlYh5uoaipFEsxqxy0eEow,4048
+aaa_server/mcp_http.py,sha256=1QeVAdkv3MbVwAoN9-kpUdjYZzkLM_gIu5hD-l4DNDk,3039
+aaa_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aaa_server-0.1.0.dist-info/METADATA,sha256=78g8jFvhSWBPTFJakOe9LPZMFm8hM8nVpRy09X4wqAs,3759
+aaa_server-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+aaa_server-0.1.0.dist-info/entry_points.txt,sha256=_pmXG6lotsoMixXcqcywxlfUqwybjCx61M6WyL75G3E,51
+aaa_server-0.1.0.dist-info/licenses/LICENSE,sha256=inG0UPjirLkSwEpASZlLycVzvrsbuJmvStPTEUzEcys,1079
+aaa_server-0.1.0.dist-info/RECORD,,

aaa_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aaa_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aaa-server = aaa_server.cli:main

aaa_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Innerkore Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.