aevum-server 0.2.0__tar.gz

aevum_server-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+
+# Build
+dist/
+build/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Verify scripts (run locally, never commit)
+verify_phase*.py
+scripts/verify_phase*.py

aevum_server-0.2.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: aevum-server
+Version: 0.2.0
+Summary: Aevum HTTP API server — wraps the five functions for any consumer.
+Project-URL: Homepage, https://aevum.build
+Project-URL: Repository, https://github.com/aevum-labs/aevum
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aevum-core
+Requires-Dist: fastapi<0.136,>=0.115
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.50b0
+Requires-Dist: opentelemetry-sdk>=1.25
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: uvicorn[standard]>=0.30
+Description-Content-Type: text/markdown
+
+# aevum-server
+
+FastAPI HTTP server wrapping the five governed Aevum kernel functions (`ingest`, `query`, `review`, `commit`, `replay`).
+
+```bash
+pip install aevum-server
+aevum server start --graph memory
+```
+
+See the [main repository README](https://github.com/aevum-labs/aevum) for configuration and deployment options.
+

aevum_server-0.2.0/README.md

@@ -0,0 +1,11 @@
+# aevum-server
+
+FastAPI HTTP server wrapping the five governed Aevum kernel functions (`ingest`, `query`, `review`, `commit`, `replay`).
+
+```bash
+pip install aevum-server
+aevum server start --graph memory
+```
+
+See the [main repository README](https://github.com/aevum-labs/aevum) for configuration and deployment options.
+

aevum_server-0.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "aevum-server"
+version = "0.2.0"
+description = "Aevum HTTP API server — wraps the five functions for any consumer."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aevum-core",
+    "fastapi>=0.115,<0.136",
+    "uvicorn[standard]>=0.30",
+    "pydantic-settings>=2.0",
+    "opentelemetry-instrumentation-fastapi>=0.50b0",
+    "opentelemetry-sdk>=1.25",
+    "python-dotenv>=1.2.2", # CVE-2026-28684 fixed in 1.2.2
+]
+
+[project.urls]
+Homepage = "https://aevum.build"
+Repository = "https://github.com/aevum-labs/aevum"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aevum"]
+
+[tool.uv.sources]
+aevum-core = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--tb=short"
+pythonpath = ["src", "tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+mypy_path = "src"
+explicit_package_bases = true
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 130
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I", "ANN"]
+ignore = ["ANN401"]

aevum_server-0.2.0/src/aevum/server/__init__.py

@@ -0,0 +1,7 @@
+"""aevum.server — HTTP API server wrapping the Aevum kernel."""
+
+from aevum.server.app import create_app
+
+__version__ = "0.1.0"
+
+__all__ = ["create_app"]

aevum_server-0.2.0/src/aevum/server/__main__.py

@@ -0,0 +1,33 @@
+"""
+python -m aevum.server — development convenience entrypoint.
+
+Starts aevum-server with an in-memory Engine and default settings.
+NOT for production. Production operators use:
+  uvicorn aevum.server.app:create_app --factory
+  gunicorn aevum.server.app:create_app -k uvicorn.workers.UvicornWorker
+
+Configuration via environment variables (see aevum/server/core/config.py).
+For full CLI control use the aevum-cli package: `aevum server start`.
+"""
+
+import uvicorn
+from aevum.core.engine import Engine
+
+from aevum.server.app import create_app
+from aevum.server.core.config import Settings
+
+
+def main() -> None:
+    settings = Settings()
+    engine = Engine(opa_url=settings.opa_url or None)
+    app = create_app(engine, settings=settings)
+    uvicorn.run(
+        app,
+        host=settings.host,
+        port=settings.port,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

aevum_server-0.2.0/src/aevum/server/app.py

@@ -0,0 +1,165 @@
+"""
+create_app — FastAPI application factory.
+
+Usage:
+    from aevum.core import Engine
+    from aevum.server.app import create_app
+
+    engine = Engine()
+    app = create_app(engine)
+
+    # Production:
+    # uvicorn aevum.server.app:create_app --factory
+    # gunicorn aevum.server.app:create_app -k uvicorn.workers.UvicornWorker
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from aevum.core.engine import Engine
+from aevum.core.exceptions import (
+    AevumError,
+    BarrierViolationError,
+    ConsentRequiredError,
+    ProvenanceRequiredError,
+    ReplayNotFoundError,
+    ReviewAlreadyResolvedError,
+    ReviewNotFoundError,
+)
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from aevum.server.core.config import Settings
+from aevum.server.middleware import AevumMiddleware
+from aevum.server.routes import admin, data, health, replay, review
+
+logger = logging.getLogger(__name__)
+
+# RFC 9457 problem type → HTTP status code mapping
+_PROBLEM_STATUS: dict[type[AevumError], int] = {
+    ConsentRequiredError: 403,
+    ProvenanceRequiredError: 400,
+    ReplayNotFoundError: 404,
+    ReviewNotFoundError: 404,
+    ReviewAlreadyResolvedError: 409,
+    BarrierViolationError: 403,
+}
+
+_PROBLEM_TYPES: dict[type[AevumError], str] = {
+    ConsentRequiredError: "consent-required",
+    ProvenanceRequiredError: "validation-error",
+    ReplayNotFoundError: "replay-not-found",
+    ReviewNotFoundError: "review-not-found",
+    ReviewAlreadyResolvedError: "review-already-resolved",
+    BarrierViolationError: "barrier-triggered",
+}
+
+
+def _problem_response(
+    exc: AevumError,
+    status: int,
+    problem_type: str,
+    request_id: str | None = None,
+) -> JSONResponse:
+    """Return RFC 9457 application/problem+json response."""
+    body: dict[str, Any] = {
+        "type": f"https://aevum.build/problems/{problem_type}",
+        "title": exc.__class__.__name__,
+        "status": status,
+        "detail": str(exc),
+    }
+    if request_id:
+        body["request_id"] = request_id
+    return JSONResponse(
+        content=body,
+        status_code=status,
+        media_type="application/problem+json",
+    )
+
+
+def create_app(
+    engine: Engine | None = None,
+    settings: Settings | None = None,
+) -> FastAPI:
+    """
+    Create the Aevum HTTP API FastAPI application.
+
+    Args:
+        engine: Aevum kernel instance. Creates Engine() with defaults if None.
+        settings: Server settings. Reads from environment if None.
+
+    Returns:
+        Configured FastAPI application.
+    """
+    if engine is None:
+        engine = Engine()
+    if settings is None:
+        settings = Settings()
+
+    app = FastAPI(
+        title="Aevum HTTP API",
+        version="0.2.0",
+        description="Replay-first, policy-governed context kernel — HTTP surface.",
+        docs_url="/v1/docs",
+        openapi_url="/v1/openapi.json",
+        redoc_url=None,
+    )
+
+    # Store engine and settings on app state for dependency injection
+    app.state.engine = engine
+    app.state.settings = settings
+
+    # Middleware (order matters: outermost runs first on request, last on response)
+    app.add_middleware(
+        AevumMiddleware,
+        rate_limit_per_minute=settings.rate_limit_per_minute,
+    )
+
+    # OTel instrumentation (sanitize X-Aevum-Key from spans)
+    if settings.otel_enabled:
+        try:
+            from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+            FastAPIInstrumentor.instrument_app(
+                app,
+                # Sanitize auth header — must NOT appear in trace exports
+                excluded_urls="",
+                http_capture_headers_server_request=["x-request-id"],
+                http_capture_headers_server_response=["x-request-id", "x-response-time-ms"],
+            )
+            logger.info("OTel FastAPI instrumentation enabled")
+        except ImportError:
+            logger.warning("opentelemetry-instrumentation-fastapi not available")
+
+    # Global exception handler — RFC 9457 format
+    @app.exception_handler(AevumError)
+    async def aevum_error_handler(request: Request, exc: AevumError) -> JSONResponse:
+        request_id = request.headers.get("x-request-id")
+        status = _PROBLEM_STATUS.get(type(exc), 500)
+        problem_type = _PROBLEM_TYPES.get(type(exc), "internal-error")
+        return _problem_response(exc, status, problem_type, request_id)
+
+    @app.exception_handler(Exception)
+    async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
+        # Never expose internal details to callers
+        logger.exception("Unhandled exception in request %s %s", request.method, request.url.path)
+        request_id = request.headers.get("x-request-id")
+        body: dict[str, Any] = {
+            "type": "https://aevum.build/problems/internal-error",
+            "title": "Internal Server Error",
+            "status": 500,
+            "detail": "An unexpected error occurred.",
+        }
+        if request_id:
+            body["request_id"] = request_id
+        return JSONResponse(content=body, status_code=500, media_type="application/problem+json")
+
+    # Routes
+    app.include_router(health.router, prefix="/v1")
+    app.include_router(data.router, prefix="/v1")
+    app.include_router(replay.router, prefix="/v1")
+    app.include_router(review.router, prefix="/v1")
+    app.include_router(admin.router, prefix="/_aevum/v1")
+
+    return app

aevum_server-0.2.0/src/aevum/server/core/__init__.py

@@ -0,0 +1 @@
+"""aevum.server.core — config, security, shared dependencies."""

aevum_server-0.2.0/src/aevum/server/core/config.py

@@ -0,0 +1,29 @@
+"""
+Server configuration via environment variables.
+All settings have safe defaults for development.
+"""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="AEVUM_", case_sensitive=False)
+
+    # Network
+    host: str = "0.0.0.0"
+    port: int = 8000
+
+    # Auth
+    api_key: str = "dev-insecure-key-change-in-production"
+
+    # Policy (optional — permissive stub if not set)
+    opa_url: str = ""
+
+    # Rate limiting (headers always present; enforcement is operator responsibility)
+    rate_limit_per_minute: int = 1000
+
+    # OTel
+    otel_enabled: bool = False
+    otel_service_name: str = "aevum-server"

aevum_server-0.2.0/src/aevum/server/core/deps.py

@@ -0,0 +1,86 @@
+"""
+FastAPI shared dependencies.
+Injected via Depends() into route handlers.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from aevum.core.engine import Engine
+from fastapi import Header, HTTPException, Request, status
+
+from aevum.server.core.config import Settings
+from aevum.server.core.security import require_api_key
+
+
+def get_engine(request: Request) -> Engine:
+    """Extract Engine from app state (set in create_app)."""
+    return request.app.state.engine  # type: ignore[no-any-return]
+
+
+def get_settings(request: Request) -> Settings:
+    """Extract Settings from app state."""
+    return request.app.state.settings  # type: ignore[no-any-return]
+
+
+async def get_actor(
+    request: Request,
+    x_aevum_key: Annotated[str | None, Header()] = None,
+    authorization: Annotated[str | None, Header()] = None,
+) -> str:
+    """
+    Validate auth and return actor identity.
+
+    Precedence:
+      1. Authorization: Bearer <token>  →  resolved via installed OIDC complication
+         (fail-closed: rejects Bearer if no OIDC complication is active)
+      2. X-Aevum-Key header             →  API key validation
+
+    The actor string returned is used throughout the kernel as the principal
+    identity for consent and audit purposes.
+    """
+    settings: Settings = request.app.state.settings
+    engine: Engine = request.app.state.engine
+
+    if authorization and authorization.lower().startswith("bearer "):
+        token = authorization[7:].strip()
+        oidc_comp = engine.get_active_complication_by_capability("oidc-validation")
+        if oidc_comp is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail={
+                    "type": "https://aevum.build/problems/authentication-required",
+                    "title": "Authentication Required",
+                    "status": 401,
+                    "detail": "Bearer token presented but no OIDC complication is active.",
+                },
+                headers={"Content-Type": "application/problem+json"},
+            )
+        result: dict[str, Any] = await oidc_comp.run(
+            {"metadata": {"bearer_token": token}}, {}
+        )
+        if not result.get("oidc_validated"):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail={
+                    "type": "https://aevum.build/problems/authentication-required",
+                    "title": "Authentication Required",
+                    "status": 401,
+                    "detail": result.get("reason", "Bearer token validation failed."),
+                },
+                headers={"Content-Type": "application/problem+json"},
+            )
+        actor: str = result["resolved_actor"]
+        return actor
+
+    return require_api_key(x_aevum_key, settings.api_key)
+
+
+def get_correlation_id(
+    request: Request,
+    x_request_id: Annotated[str | None, Header()] = None,
+) -> str:
+    """Return client-provided or server-generated correlation ID."""
+    import uuid
+    return x_request_id or str(uuid.uuid4())

aevum_server-0.2.0/src/aevum/server/core/security.py

@@ -0,0 +1,47 @@
+"""
+Authentication — X-Aevum-Key header validation.
+
+API key authentication only. For OIDC bearer token support install
+the aevum-oidc complication and add it to the Engine.
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, status
+from fastapi.security import APIKeyHeader
+
+_API_KEY_HEADER = APIKeyHeader(name="X-Aevum-Key", auto_error=False)
+
+
+def require_api_key(
+    api_key_value: str | None,
+    configured_key: str,
+) -> str:
+    """
+    Validate the X-Aevum-Key header.
+    Returns the key value (used as actor identity) if valid.
+    Raises 401 if absent or invalid.
+    """
+    if not api_key_value:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail={
+                "type": "https://aevum.build/problems/authentication-required",
+                "title": "Authentication Required",
+                "status": 401,
+                "detail": "X-Aevum-Key header is required.",
+            },
+            headers={"Content-Type": "application/problem+json"},
+        )
+    if api_key_value != configured_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail={
+                "type": "https://aevum.build/problems/authentication-required",
+                "title": "Authentication Required",
+                "status": 401,
+                "detail": "Invalid API key.",
+            },
+            headers={"Content-Type": "application/problem+json"},
+        )
+    return api_key_value

aevum_server-0.2.0/src/aevum/server/middleware.py

@@ -0,0 +1,57 @@
+"""
+Middleware — correlation IDs, security headers, rate limit headers.
+Applied to every response via app.middleware("http").
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+
+class AevumMiddleware(BaseHTTPMiddleware):
+    """
+    Single middleware handling:
+    1. Correlation ID propagation (X-Request-ID)
+    2. Security headers on every response
+    3. Rate limit info headers (headers always present; enforcement is operator concern)
+    4. Request timing
+    """
+
+    def __init__(self, app: ASGIApp, rate_limit_per_minute: int = 1000) -> None:
+        super().__init__(app)
+        self._rate_limit = rate_limit_per_minute
+
+    async def dispatch(self, request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Response:
+        start = time.perf_counter()
+
+        # Correlation ID
+        correlation_id = request.headers.get("x-request-id") or str(uuid.uuid4())
+
+        response: Response = await call_next(request)
+
+        duration_ms = int((time.perf_counter() - start) * 1000)
+
+        # Correlation ID echo
+        response.headers["X-Request-ID"] = correlation_id
+
+        # Security headers (spec Section 10.8)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Strict-Transport-Security"] = "max-age=31536000"
+        response.headers["Content-Security-Policy"] = "default-src 'none'"
+
+        # Rate limit info headers (spec Section 10.7)
+        response.headers["X-RateLimit-Limit"] = str(self._rate_limit)
+        response.headers["X-RateLimit-Remaining"] = str(self._rate_limit)
+        response.headers["X-RateLimit-Reset"] = "60"
+
+        # Timing
+        response.headers["X-Response-Time-Ms"] = str(duration_ms)
+
+        return response

aevum_server-0.2.0/src/aevum/server/routes/__init__.py

@@ -0,0 +1 @@
+"""aevum.server.routes — All route handlers."""

aevum_server-0.2.0/src/aevum/server/routes/admin.py

@@ -0,0 +1,108 @@
+"""
+/_aevum/v1/* — admin API for complication lifecycle and server diagnostics.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from aevum.core.engine import Engine
+from aevum.core.exceptions import ComplicationError
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+
+from aevum.server.core.deps import get_actor, get_engine
+
+router = APIRouter()
+
+
+class ApproveRequest(BaseModel):
+    pass
+
+
+class SuspendRequest(BaseModel):
+    pass
+
+
+@router.get("/complications")
+async def list_complications(
+    actor: Annotated[str, Depends(get_actor)],
+    engine: Annotated[Engine, Depends(get_engine)],
+) -> dict[str, Any]:
+    """List all complications with their current lifecycle state."""
+    return {"complications": engine.list_complications()}
+
+
+@router.post("/complications/{complication_id}/approve")
+async def approve_complication(
+    complication_id: str,
+    body: ApproveRequest,
+    actor: Annotated[str, Depends(get_actor)],
+    engine: Annotated[Engine, Depends(get_engine)],
+) -> dict[str, Any]:
+    """Approve a PENDING complication → ACTIVE."""
+    try:
+        engine.approve_complication(complication_id)
+        return {"approved": True, "name": complication_id}
+    except ComplicationError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={"type": "https://aevum.build/problems/complication-error",
+                    "title": "Complication Error", "status": 409, "detail": str(e)},
+        ) from e
+
+
+@router.post("/complications/{complication_id}/suspend")
+async def suspend_complication(
+    complication_id: str,
+    body: SuspendRequest,
+    actor: Annotated[str, Depends(get_actor)],
+    engine: Annotated[Engine, Depends(get_engine)],
+) -> dict[str, Any]:
+    """Suspend an ACTIVE complication."""
+    try:
+        engine.suspend_complication(complication_id)
+        return {"suspended": True, "name": complication_id}
+    except ComplicationError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={"type": "https://aevum.build/problems/complication-error",
+                    "title": "Complication Error", "status": 409, "detail": str(e)},
+        ) from e
+
+
+@router.get("/complications/{complication_id}/health")
+async def complication_health(
+    complication_id: str,
+    actor: Annotated[str, Depends(get_actor)],
+    engine: Annotated[Engine, Depends(get_engine)],
+) -> dict[str, Any]:
+    """Check health of a specific complication."""
+    complications = engine.list_complications()
+    if complication_id not in complications:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"type": "https://aevum.build/problems/complication-not-found",
+                    "title": "Not Found", "status": 404,
+                    "detail": f"Complication '{complication_id}' not found"},
+        )
+    entry = complications[complication_id]
+    return {
+        "name": complication_id,
+        "state": entry["state"],
+        "healthy": entry["state"] == "ACTIVE",
+    }
+
+
+@router.get("/usage")
+async def get_usage(
+    actor: Annotated[str, Depends(get_actor)],
+) -> dict[str, Any]:
+    return {"usage": {}, "note": "Install a complication to see usage metrics here."}
+
+
+@router.get("/federation/peers")
+async def list_federation_peers(
+    actor: Annotated[str, Depends(get_actor)],
+) -> dict[str, Any]:
+    return {"peers": [], "note": "Install a complication to see it listed here."}