aiperture 0.3.0__py3-none-any.whl

aiperture/__init__.py

@@ -0,0 +1,3 @@
+"""AIperture — The permission layer for AI agents."""
+
+__version__ = "0.2.0"

aiperture/api/__init__.py

@@ -0,0 +1,5 @@
+"""AIperture API — FastAPI application."""
+
+from aiperture.api.app import create_app
+
+__all__ = ["create_app"]

aiperture/api/app.py

@@ -0,0 +1,44 @@
+"""FastAPI application factory."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI
+
+from aiperture import plugins
+from aiperture.api.auth import require_api_key
+from aiperture.api.routes import artifacts, audit, config, health, intelligence, metrics, permissions
+from aiperture.db import init_db
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    plugins.load_all()
+    init_db()
+    yield
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="AIperture",
+        description="The permission layer for AI agents. Controls what passes through.",
+        version="0.3.0",
+        lifespan=lifespan,
+        dependencies=[Depends(require_api_key)],
+    )
+
+    app.include_router(permissions.router, prefix="/permissions", tags=["permissions"])
+    app.include_router(artifacts.router, prefix="/artifacts", tags=["artifacts"])
+    app.include_router(audit.router, prefix="/audit", tags=["audit"])
+    app.include_router(intelligence.router, prefix="/intelligence", tags=["intelligence"])
+    app.include_router(config.router, prefix="/config", tags=["config"])
+    app.include_router(health.router, tags=["health"])
+    app.include_router(metrics.router, tags=["metrics"])
+
+    # Register plugin routers if any
+    plugin_router = plugins.get("router")
+    if plugin_router is not None:
+        for router_info in plugin_router.get_routers():
+            app.include_router(router_info)
+
+    return app

aiperture/api/auth.py

@@ -0,0 +1,46 @@
+"""Bearer token authentication for the AIperture HTTP API.
+
+If AIPERTURE_API_KEY is empty or unset, all requests are allowed (local dev mode).
+If set, every request must include an ``Authorization: Bearer <key>`` header
+whose value matches the configured key exactly.
+
+A plugin ``auth_backend`` can replace or extend the default bearer-token check.
+
+The MCP server (stdio transport) is unaffected — this dependency is only wired
+into the FastAPI application.
+"""
+
+from __future__ import annotations
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+import aiperture.config
+from aiperture import plugins
+
+# optional=True so the scheme does not return 403 when the header is absent;
+# we handle the missing-header case ourselves with a clear 401.
+_bearer_scheme = HTTPBearer(auto_error=False)
+
+
+async def require_api_key(
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None = Depends(_bearer_scheme),
+) -> None:
+    """FastAPI dependency that enforces Bearer token auth when an API key is configured."""
+    # Delegate to plugin auth backend if present
+    auth_backend = plugins.get("auth_backend")
+    if auth_backend is not None:
+        await auth_backend.authenticate(request)
+        return
+
+    configured_key = aiperture.config.settings.api_key
+    if not configured_key:
+        # No key configured — open access (local dev mode).
+        return
+
+    if credentials is None or credentials.credentials != configured_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or missing API key",
+        )

aiperture/api/routes/artifacts.py

@@ -0,0 +1,181 @@
+"""Artifact API — store, retrieve, verify, and track costs.
+
+External runtimes call these endpoints to:
+1. Store every output as a verified artifact
+2. Retrieve artifacts for audit or review
+3. Re-verify artifact integrity
+4. Get cost summaries across runtimes/models
+"""
+
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from aiperture.stores.artifact_store import ArtifactStore
+
+router = APIRouter()
+store = ArtifactStore()
+
+
+# --- Request/Response schemas ---
+
+
+class StoreRequest(BaseModel):
+    content: str
+    artifact_type: str = "custom"
+    organization_id: str = "default"
+    session_id: str = ""
+    task_id: str = ""
+    runtime_id: str = ""
+    tool_name: str = ""
+    tool_args: dict | None = None
+    summary: str = ""
+    extra: dict | None = None
+    tokens_input: int = 0
+    tokens_output: int = 0
+    cost_usd: float = 0.0
+    model_used: str = ""
+    provider_used: str = ""
+
+
+class ArtifactResponse(BaseModel):
+    artifact_id: str
+    type: str
+    content_hash: str
+    verification_status: str
+    tool_name: str
+    summary: str
+    tokens_input: int
+    tokens_output: int
+    cost_usd: float
+    model_used: str
+    provider_used: str
+    created_at: str
+
+
+# --- Endpoints ---
+
+
+@router.post("/store", response_model=ArtifactResponse)
+def store_artifact(req: StoreRequest):
+    """Store an artifact with automatic SHA-256 verification.
+
+    Every tool call, every LLM response, every output from any
+    external runtime gets persisted here as the canonical record.
+    """
+    artifact = store.store(
+        content=req.content,
+        artifact_type=req.artifact_type,
+        organization_id=req.organization_id,
+        session_id=req.session_id,
+        task_id=req.task_id,
+        runtime_id=req.runtime_id,
+        tool_name=req.tool_name,
+        tool_args=req.tool_args,
+        summary=req.summary,
+        extra=req.extra,
+        tokens_input=req.tokens_input,
+        tokens_output=req.tokens_output,
+        cost_usd=req.cost_usd,
+        model_used=req.model_used,
+        provider_used=req.provider_used,
+    )
+    return ArtifactResponse(
+        artifact_id=artifact.artifact_id,
+        type=artifact.type,
+        content_hash=artifact.content_hash,
+        verification_status=artifact.verification_status,
+        tool_name=artifact.tool_name,
+        summary=artifact.summary,
+        tokens_input=artifact.tokens_input,
+        tokens_output=artifact.tokens_output,
+        cost_usd=artifact.cost_usd,
+        model_used=artifact.model_used,
+        provider_used=artifact.provider_used,
+        created_at=artifact.created_at.isoformat(),
+    )
+
+
+@router.get("/costs/summary")
+def cost_summary(
+    organization_id: str = "default",
+    task_id: str | None = None,
+    runtime_id: str | None = None,
+):
+    """Get cost summary across artifacts.
+
+    Breaks down by provider and model. Shows total tokens and cost.
+    """
+    return store.get_cost_summary(
+        organization_id=organization_id,
+        task_id=task_id,
+        runtime_id=runtime_id,
+    )
+
+
+@router.get("/task/{task_id}")
+def list_by_task(task_id: str, organization_id: str = "default"):
+    """List all artifacts for a task."""
+    artifacts = store.list_by_task(task_id, organization_id)
+    return {
+        "task_id": task_id,
+        "count": len(artifacts),
+        "artifacts": [
+            {
+                "artifact_id": a.artifact_id,
+                "type": a.type,
+                "content_hash": a.content_hash,
+                "verification_status": a.verification_status,
+                "tool_name": a.tool_name,
+                "summary": a.summary,
+                "cost_usd": a.cost_usd,
+                "created_at": a.created_at.isoformat(),
+            }
+            for a in artifacts
+        ],
+    }
+
+
+@router.get("/{artifact_id}")
+def get_artifact(artifact_id: str):
+    """Retrieve a stored artifact."""
+    artifact = store.get(artifact_id)
+    if not artifact:
+        raise HTTPException(status_code=404, detail="Artifact not found")
+    return {
+        "artifact_id": artifact.artifact_id,
+        "type": artifact.type,
+        "content_hash": artifact.content_hash,
+        "verification_status": artifact.verification_status,
+        "content": artifact.content if artifact.storage_backend == "inline" else None,
+        "tool_name": artifact.tool_name,
+        "tool_args": artifact.tool_args,
+        "summary": artifact.summary,
+        "extra": artifact.extra,
+        "tokens_input": artifact.tokens_input,
+        "tokens_output": artifact.tokens_output,
+        "cost_usd": artifact.cost_usd,
+        "model_used": artifact.model_used,
+        "provider_used": artifact.provider_used,
+        "runtime_id": artifact.runtime_id,
+        "created_at": artifact.created_at.isoformat(),
+    }
+
+
+@router.post("/{artifact_id}/verify")
+def verify_artifact(artifact_id: str):
+    """Re-verify an artifact's integrity.
+
+    Recomputes SHA-256 hash and compares to stored hash.
+    Returns current verification status.
+    """
+    try:
+        artifact = store.verify(artifact_id)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    return {
+        "artifact_id": artifact.artifact_id,
+        "verification_status": artifact.verification_status,
+        "content_hash": artifact.content_hash,
+        "verified_at": artifact.verified_at.isoformat() if artifact.verified_at else None,
+    }

aiperture/api/routes/audit.py

@@ -0,0 +1,137 @@
+"""Audit API — immutable event trail.
+
+Everything that happens in Aperture is logged here.
+This is the compliance backbone.
+"""
+
+from datetime import datetime
+
+from fastapi import APIRouter, HTTPException
+
+from aiperture.stores.audit_store import AuditStore
+
+router = APIRouter()
+store = AuditStore()
+
+
+@router.get("/events")
+def list_events(
+    organization_id: str = "default",
+    event_type: str | None = None,
+    entity_type: str | None = None,
+    entity_id: str | None = None,
+    actor_id: str | None = None,
+    runtime_id: str | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+):
+    """Query audit events with filters."""
+    limit = min(limit, 1000)
+    try:
+        since_dt = datetime.fromisoformat(since) if since else None
+    except ValueError:
+        raise HTTPException(status_code=422, detail=f"Invalid 'since' date format: {since!r}")
+    try:
+        until_dt = datetime.fromisoformat(until) if until else None
+    except ValueError:
+        raise HTTPException(status_code=422, detail=f"Invalid 'until' date format: {until!r}")
+
+    events = store.list_events(
+        organization_id=organization_id,
+        event_type=event_type,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        actor_id=actor_id,
+        runtime_id=runtime_id,
+        since=since_dt,
+        until=until_dt,
+        limit=limit,
+        offset=offset,
+    )
+    return {
+        "count": len(events),
+        "events": [
+            {
+                "event_id": e.event_id,
+                "event_type": e.event_type,
+                "entity_type": e.entity_type,
+                "entity_id": e.entity_id,
+                "summary": e.summary,
+                "actor_id": e.actor_id,
+                "actor_type": e.actor_type,
+                "runtime_id": e.runtime_id,
+                "details": e.details,
+                "created_at": e.created_at.isoformat(),
+            }
+            for e in events
+        ],
+    }
+
+
+@router.get("/events/{event_id}")
+def get_event(event_id: str):
+    """Get a single audit event with full details."""
+    event = store.get_event(event_id)
+    if not event:
+        raise HTTPException(status_code=404, detail="Audit event not found")
+    return {
+        "event_id": event.event_id,
+        "event_type": event.event_type,
+        "entity_type": event.entity_type,
+        "entity_id": event.entity_id,
+        "summary": event.summary,
+        "actor_id": event.actor_id,
+        "actor_type": event.actor_type,
+        "runtime_id": event.runtime_id,
+        "details": event.details,
+        "previous_state": event.previous_state,
+        "new_state": event.new_state,
+        "created_at": event.created_at.isoformat(),
+    }
+
+
+@router.get("/entity/{entity_type}/{entity_id}")
+def entity_history(
+    entity_type: str,
+    entity_id: str,
+    organization_id: str = "default",
+    limit: int = 50,
+):
+    """Full audit history of a specific entity."""
+    limit = min(limit, 1000)
+    events = store.get_entity_history(entity_type, entity_id, organization_id, limit)
+    return {
+        "entity_type": entity_type,
+        "entity_id": entity_id,
+        "count": len(events),
+        "events": [
+            {
+                "event_id": e.event_id,
+                "event_type": e.event_type,
+                "summary": e.summary,
+                "actor_id": e.actor_id,
+                "details": e.details,
+                "created_at": e.created_at.isoformat(),
+            }
+            for e in events
+        ],
+    }
+
+
+@router.get("/count")
+def event_count(organization_id: str = "default"):
+    """Total audit event count."""
+    return {"count": store.count(organization_id)}
+
+
+@router.get("/verify-chain")
+def verify_chain(organization_id: str = "default"):
+    """Verify the hash chain integrity of the audit trail.
+
+    Walks the entire chain and checks that each event's hash matches
+    its computed value and links to the previous event's hash.
+    Any deletion, reordering, or tampering breaks the chain.
+    """
+    return store.verify_chain(organization_id)

aiperture/api/routes/config.py

@@ -0,0 +1,36 @@
+"""Configuration API — GET /config and PATCH /config for tunable settings."""
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+import aiperture.config
+
+router = APIRouter()
+
+
+class ConfigPatchRequest(BaseModel):
+    settings: dict[str, Any]
+
+
+@router.get("")
+def get_config():
+    """Return current tunable settings and their descriptions."""
+    return {
+        "settings": aiperture.config.get_tunable_config(),
+        "descriptions": dict(aiperture.config.Settings.TUNABLE_DESCRIPTIONS),
+    }
+
+
+@router.patch("")
+def patch_config(body: ConfigPatchRequest):
+    """Update tunable settings at runtime. Persists to .aiperture.env."""
+    try:
+        aiperture.config.update_settings(body.settings)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    return {
+        "updated": True,
+        "settings": aiperture.config.get_tunable_config(),
+    }

aiperture/api/routes/health.py

@@ -0,0 +1,57 @@
+"""Health check endpoint — database connectivity probe."""
+
+import logging
+
+from fastapi import APIRouter
+from sqlalchemy import text
+from sqlmodel import Session
+
+from aiperture import plugins
+from aiperture.db import get_engine
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get("/health")
+def health_check():
+    """Check service health including database connectivity.
+
+    Returns:
+        200 with {"status": "healthy", "database": "connected"} when DB is reachable.
+        200 with {"status": "degraded", "database": "error", "detail": "..."} when DB is unreachable.
+
+    Always returns 200 so load balancers can distinguish between
+    "service is up but degraded" vs "service is down".
+    """
+    result = {
+        "service": "aiperture",
+        "version": "0.2.0",
+    }
+
+    try:
+        with Session(get_engine()) as session:
+            session.execute(text("SELECT 1"))
+        result["status"] = "healthy"
+        result["database"] = "connected"
+    except Exception as exc:
+        detail = str(exc)
+        logger.warning("Health check: database unreachable — %s", detail)
+        result["status"] = "degraded"
+        result["database"] = "error"
+        result["detail"] = detail
+
+    # Run plugin health checkers
+    health_checker = plugins.get("health_checker")
+    if health_checker is not None:
+        try:
+            plugin_result = health_checker.check()
+            result[health_checker.name] = plugin_result
+            if plugin_result.get("status") != "healthy":
+                result["status"] = "degraded"
+        except Exception as exc:
+            result[health_checker.name] = {"status": "error", "detail": str(exc)}
+            result["status"] = "degraded"
+
+    return result

aiperture/api/routes/intelligence.py

@@ -0,0 +1,41 @@
+"""Intelligence API — cross-org anonymized permission signals."""
+
+from fastapi import APIRouter
+
+from aiperture.permissions.intelligence import IntelligenceEngine
+
+router = APIRouter()
+
+
+@router.get("/global-signal")
+def get_global_signal(
+    tool: str,
+    action: str,
+    scope: str,
+):
+    """Get cross-organization permission signal for a pattern.
+
+    Returns DP-protected aggregate statistics. Only available when
+    enough organizations have contributed data (min_orgs threshold).
+    """
+    import aiperture.config
+
+    intel = IntelligenceEngine(
+        min_orgs=aiperture.config.settings.intelligence_min_orgs,
+        default_epsilon=aiperture.config.settings.intelligence_epsilon,
+    )
+    signal = intel.get_global_signal(tool, action, scope)
+
+    if signal is None:
+        return {"available": False, "reason": "Insufficient cross-org data"}
+
+    return {
+        "available": True,
+        "total_orgs": signal.total_orgs,
+        "estimated_allow_rate": round(signal.estimated_allow_rate, 3),
+        "confidence_interval": [
+            round(signal.confidence_interval[0], 3),
+            round(signal.confidence_interval[1], 3),
+        ],
+        "sample_size": signal.sample_size,
+    }

aiperture/api/routes/metrics.py

@@ -0,0 +1,13 @@
+"""Prometheus metrics endpoint."""
+
+from fastapi import APIRouter
+from fastapi.responses import PlainTextResponse
+from prometheus_client import generate_latest
+
+router = APIRouter()
+
+
+@router.get("/metrics", response_class=PlainTextResponse)
+def metrics():
+    """Prometheus-compatible metrics endpoint."""
+    return generate_latest()