nat-engine 1__py3-none-any.whl

mannf/product/admin/routes.py

@@ -0,0 +1,514 @@
+# 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.
+
+"""Admin API routes for tenant management.
+
+All routes are mounted under ``/api/v1/admin`` and protected by the
+``X-Admin-Key`` header (checked against the ``NAT_ADMIN_KEY`` env var).
+
+Endpoints:
+    POST   /api/v1/admin/tenants              — Create tenant
+    GET    /api/v1/admin/tenants              — List tenants
+    GET    /api/v1/admin/tenants/{id}         — Get tenant details
+    PUT    /api/v1/admin/tenants/{id}         — Update tenant
+    DELETE /api/v1/admin/tenants/{id}         — Deactivate tenant
+    POST   /api/v1/admin/tenants/{id}/rotate-key — Rotate API key
+    GET    /api/v1/admin/tenants/{id}/usage   — Get usage stats
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from fastapi import APIRouter, Header, HTTPException, Query
+from pydantic import BaseModel
+
+from mannf.product.billing.tenant_manager import TenantManager
+
+router = APIRouter(prefix="/api/v1/admin", tags=["admin"])
+
+_manager = TenantManager()
+
+
+# ---------------------------------------------------------------------------
+# Auth helper
+# ---------------------------------------------------------------------------
+
+
+def _require_admin_key(x_admin_key: Optional[str]) -> None:
+    """Raise 401 / 403 if the X-Admin-Key header is missing or invalid."""
+    admin_key = os.environ.get("NAT_ADMIN_KEY", "")
+    if not admin_key:
+        raise HTTPException(
+            status_code=503,
+            detail={
+                "error": {
+                    "code": "ADMIN_NOT_CONFIGURED",
+                    "message": "Admin API is not configured — set NAT_ADMIN_KEY.",
+                }
+            },
+        )
+    if not x_admin_key:
+        raise HTTPException(
+            status_code=401,
+            detail={
+                "error": {
+                    "code": "MISSING_ADMIN_KEY",
+                    "message": "X-Admin-Key header is required.",
+                }
+            },
+        )
+    if x_admin_key != admin_key:
+        raise HTTPException(
+            status_code=403,
+            detail={
+                "error": {
+                    "code": "INVALID_ADMIN_KEY",
+                    "message": "Invalid admin key.",
+                }
+            },
+        )
+
+
+# ---------------------------------------------------------------------------
+# Request / response models
+# ---------------------------------------------------------------------------
+
+
+class CreateTenantRequest(BaseModel):
+    name: str
+    email: str
+    plan: str = "free"
+
+
+class UpdateTenantRequest(BaseModel):
+    plan: Optional[str] = None
+    monthly_scan_quota: Optional[int] = None
+    monthly_security_scan_quota: Optional[int] = None
+    is_active: Optional[bool] = None
+
+
+class CreateWorkspaceRequest(BaseModel):
+    name: str
+    description: Optional[str] = None
+
+
+class CreateProjectRequest(BaseModel):
+    name: str
+    description: Optional[str] = None
+    parent_project_id: Optional[str] = None
+
+
+class InviteUserRequest(BaseModel):
+    email: str
+    name: str
+    role: str = "viewer"
+
+
+class AssignRoleRequest(BaseModel):
+    role: str
+    workspace_id: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Routes
+# ---------------------------------------------------------------------------
+
+
+@router.post("/tenants", status_code=201)
+async def create_tenant(
+    body: CreateTenantRequest,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Create a new tenant and return its API key (shown once)."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.create_tenant(
+            name=body.name,
+            email=body.email,
+            plan_tier=body.plan,
+        )
+    except (RuntimeError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail={"error": {"code": "BAD_REQUEST", "message": str(exc)}}) from exc
+
+
+@router.get("/tenants")
+async def list_tenants(
+    plan: Optional[str] = Query(default=None),
+    active_only: bool = Query(default=True),
+    limit: int = Query(default=100, ge=1, le=1000),
+    x_admin_key: Optional[str] = Header(default=None),
+) -> list:
+    """List tenants with optional plan/status filtering."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.list_tenants(
+            plan_filter=plan,
+            active_only=active_only,
+            limit=limit,
+        )
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.get("/tenants/{tenant_id}")
+async def get_tenant(
+    tenant_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Get tenant details by ID."""
+    _require_admin_key(x_admin_key)
+    try:
+        result = await _manager.get_tenant(tenant_id)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+    if result is None:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": f"Tenant {tenant_id!r} not found."}})
+    return result
+
+
+@router.put("/tenants/{tenant_id}")
+async def update_tenant(
+    tenant_id: str,
+    body: UpdateTenantRequest,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Update tenant plan, quotas, or active status."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.update_tenant(
+            tenant_id=tenant_id,
+            plan_tier=body.plan,
+            monthly_scan_quota=body.monthly_scan_quota,
+            monthly_security_scan_quota=body.monthly_security_scan_quota,
+            is_active=body.is_active,
+        )
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except (RuntimeError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail={"error": {"code": "BAD_REQUEST", "message": str(exc)}}) from exc
+
+
+@router.delete("/tenants/{tenant_id}")
+async def deactivate_tenant(
+    tenant_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Soft-delete a tenant — mark as inactive and revoke API keys."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.deactivate_tenant(tenant_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.post("/tenants/{tenant_id}/rotate-key")
+async def rotate_api_key(
+    tenant_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Revoke the current API key and issue a new one (shown once)."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.rotate_api_key(tenant_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.get("/tenants/{tenant_id}/usage")
+async def get_tenant_usage(
+    tenant_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Get current month's usage statistics for a tenant."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.get_tenant_usage(tenant_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.get("/tenants/{tenant_id}/events")
+async def get_tenant_billing_events(
+    tenant_id: str,
+    limit: int = Query(default=100, ge=1, le=500),
+    event_type: Optional[str] = Query(default=None),
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Get billing event audit log for a specific tenant."""
+    _require_admin_key(x_admin_key)
+    try:
+        from mannf.product.billing.audit import get_billing_events  # noqa: PLC0415
+
+        events = await get_billing_events(tenant_id, limit=limit, event_type=event_type)
+        return {"tenant_id": tenant_id, "events": events, "count": len(events)}
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail={"error": {"code": "BAD_REQUEST", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+# ---------------------------------------------------------------------------
+# Workspace endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/tenants/{tenant_id}/workspaces", status_code=201)
+async def create_workspace(
+    tenant_id: str,
+    body: CreateWorkspaceRequest,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Create a workspace for a tenant."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.create_workspace(
+            tenant_id=tenant_id,
+            name=body.name,
+            description=body.description,
+        )
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.get("/tenants/{tenant_id}/workspaces")
+async def list_workspaces(
+    tenant_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> list:
+    """List workspaces for a tenant."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.list_workspaces(tenant_id=tenant_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.delete("/tenants/{tenant_id}/workspaces/{workspace_id}")
+async def delete_workspace(
+    tenant_id: str,
+    workspace_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Deactivate a workspace."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.delete_workspace(tenant_id=tenant_id, workspace_id=workspace_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+# ---------------------------------------------------------------------------
+# Project endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/tenants/{tenant_id}/workspaces/{workspace_id}/projects", status_code=201)
+async def create_project(
+    tenant_id: str,
+    workspace_id: str,
+    body: CreateProjectRequest,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Create a project in a workspace."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.create_project(
+            tenant_id=tenant_id,
+            workspace_id=workspace_id,
+            name=body.name,
+            description=body.description,
+            parent_project_id=body.parent_project_id,
+        )
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except (RuntimeError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail={"error": {"code": "BAD_REQUEST", "message": str(exc)}}) from exc
+
+
+@router.get("/tenants/{tenant_id}/workspaces/{workspace_id}/projects")
+async def list_projects(
+    tenant_id: str,
+    workspace_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> list:
+    """List projects in a workspace."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.list_projects(tenant_id=tenant_id, workspace_id=workspace_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.delete("/tenants/{tenant_id}/projects/{project_id}")
+async def delete_project(
+    tenant_id: str,
+    project_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Deactivate a project."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.delete_project(tenant_id=tenant_id, project_id=project_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+# ---------------------------------------------------------------------------
+# User endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.post("/tenants/{tenant_id}/users", status_code=201)
+async def invite_user(
+    tenant_id: str,
+    body: InviteUserRequest,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Invite a user to a tenant."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.invite_user(
+            tenant_id=tenant_id,
+            email=body.email,
+            name=body.name,
+            role=body.role,
+        )
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail={"error": {"code": "SEAT_LIMIT_EXCEEDED" if "SEAT_LIMIT_EXCEEDED" in str(exc) else "BAD_REQUEST", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.get("/tenants/{tenant_id}/users")
+async def list_users(
+    tenant_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> list:
+    """List users in a tenant."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.list_users(tenant_id=tenant_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+@router.put("/tenants/{tenant_id}/users/{user_id}/role")
+async def assign_user_role(
+    tenant_id: str,
+    user_id: str,
+    body: AssignRoleRequest,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Assign or update a user's role."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.assign_role(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            role=body.role,
+            workspace_id=body.workspace_id,
+        )
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except (RuntimeError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail={"error": {"code": "BAD_REQUEST", "message": str(exc)}}) from exc
+
+
+@router.delete("/tenants/{tenant_id}/users/{user_id}")
+async def remove_user(
+    tenant_id: str,
+    user_id: str,
+    x_admin_key: Optional[str] = Header(default=None),
+) -> dict:
+    """Deactivate a user."""
+    _require_admin_key(x_admin_key)
+    try:
+        return await _manager.remove_user(tenant_id=tenant_id, user_id=user_id)
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail={"error": {"code": "NOT_FOUND", "message": str(exc)}}) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+
+# ---------------------------------------------------------------------------
+# Audit log endpoint
+# ---------------------------------------------------------------------------
+
+
+@router.get("/audit-log")
+async def get_audit_log(
+    tenant_id: Optional[str] = Query(default=None),
+    method: Optional[str] = Query(default=None),
+    path_prefix: Optional[str] = Query(default=None),
+    limit: int = Query(default=100, ge=1, le=500),
+    x_admin_key: Optional[str] = Header(default=None),
+) -> list:
+    """Query the API audit log."""
+    _require_admin_key(x_admin_key)
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+        from mannf.product.models import ApiAuditLog  # noqa: PLC0415
+        from sqlalchemy import select  # noqa: PLC0415
+        import uuid as _uuid  # noqa: PLC0415
+    except ImportError as exc:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": str(exc)}}) from exc
+
+    if _build_engine() is None or _async_session_factory is None:
+        raise HTTPException(status_code=503, detail={"error": {"code": "DB_UNAVAILABLE", "message": "Database not configured"}})
+
+    async with _async_session_factory() as session:
+        stmt = select(ApiAuditLog).order_by(ApiAuditLog.created_at.desc()).limit(limit)
+
+        if tenant_id:
+            try:
+                tid = _uuid.UUID(tenant_id)
+                stmt = stmt.where(ApiAuditLog.tenant_id == tid)
+            except ValueError:
+                pass
+
+        if method:
+            stmt = stmt.where(ApiAuditLog.method == method.upper())
+
+        if path_prefix:
+            stmt = stmt.where(ApiAuditLog.path.startswith(path_prefix))
+
+        result = await session.execute(stmt)
+        entries = result.scalars().all()
+
+    return [
+        {
+            "id": str(e.id),
+            "tenant_id": str(e.tenant_id) if e.tenant_id else None,
+            "user_id": str(e.user_id) if e.user_id else None,
+            "method": e.method,
+            "path": e.path,
+            "status_code": e.status_code,
+            "request_summary": e.request_summary,
+            "source_ip": e.source_ip,
+            "created_at": e.created_at.isoformat() if e.created_at else None,
+        }
+        for e in entries
+    ]

mannf/product/auth/__init__.py

@@ -0,0 +1,5 @@
+# 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.
+
+from __future__ import annotations