mesa-memory 0.9.0__py3-none-any.whl

mesa_api/__init__.py

@@ -0,0 +1,9 @@
+"""Versioned MESA HTTP contracts.
+
+``mesa_api.v4_router`` exposes the breaking full-cognitive catalog, immutable
+session, mutation, provenance, search, replay and rollback contract.
+"""
+
+from .v4_router import create_v4_router
+
+__all__ = ["create_v4_router"]

mesa_api/admission.py

@@ -0,0 +1,23 @@
+"""Shared API admission policy for storage-root mutations."""
+
+from fastapi import HTTPException
+
+from mesa_storage.dao import MemoryDAO
+
+
+async def require_mutation_admission(
+    dao: MemoryDAO, *, require_projection_consumer: bool = False
+) -> None:
+    """Fail closed while a durable projection rebuild owns the storage root."""
+    if require_projection_consumer and dao.canonical_v4_writes_enabled is False:
+        raise HTTPException(
+            status_code=503,
+            detail="canonical_processing_unavailable",
+            headers={"Retry-After": "5"},
+        )
+    if await dao.rebuild_admission.is_pending():
+        raise HTTPException(
+            status_code=503,
+            detail="maintenance_pending",
+            headers={"Retry-After": "5"},
+        )

mesa_api/identifier_validation.py

@@ -0,0 +1,67 @@
+"""Shared public identifier constraints for versioned API boundaries."""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated
+
+from pydantic import AfterValidator, Field
+
+_RESERVED_SENTINELS = frozenset({"__unset__", "__system__", ""})
+_ALLOWED_IDENTIFIER_PATTERN = re.compile(r"^[a-zA-Z0-9._-]+$")
+_CONTROL_CHAR_PATTERN = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def validate_public_identifier(
+    value: str,
+    field_name: str = "identifier",
+    *,
+    max_length: int = 128,
+    restricted_charset: bool = True,
+) -> str:
+    """Validate one caller-controlled public identifier.
+
+    The 128-character form covers tenant, workspace, dataset, agent, session,
+    mutation, and operation identifiers.  Source-owned document, revision, and
+    chunk identifiers retain their established 256-character boundary.
+    """
+    if _CONTROL_CHAR_PATTERN.search(value):
+        raise ValueError(
+            f"{field_name} contains illegal control characters. "
+            "Only printable ASCII characters are allowed."
+        )
+
+    stripped = value.strip()
+    if stripped in _RESERVED_SENTINELS:
+        raise ValueError(f"{field_name} cannot be empty or a reserved value")
+    if len(stripped) > max_length:
+        raise ValueError(f"{field_name} must be between 1 and {max_length} characters")
+    if restricted_charset and not _ALLOWED_IDENTIFIER_PATTERN.fullmatch(stripped):
+        raise ValueError(
+            f"{field_name} may contain only alphanumeric characters, hyphens, "
+            "underscores, or dots"
+        )
+    return stripped
+
+
+def _validate_standard_identifier(value: str) -> str:
+    return validate_public_identifier(value)
+
+
+def _validate_source_identifier(value: str) -> str:
+    # Document/revision/chunk aliases historically permit external naming
+    # punctuation.  Preserve that compatibility while enforcing the shared
+    # control-character, sentinel, and size boundaries.
+    return validate_public_identifier(value, max_length=256, restricted_charset=False)
+
+
+PublicIdentifier = Annotated[
+    str,
+    Field(min_length=1, max_length=128),
+    AfterValidator(_validate_standard_identifier),
+]
+SourceIdentifier = Annotated[
+    str,
+    Field(min_length=1, max_length=256),
+    AfterValidator(_validate_source_identifier),
+]

mesa_api/routers/control/router.py

@@ -0,0 +1,276 @@
+# mypy: disable-error-code="no-untyped-def,untyped-decorator"
+from typing import Any, Callable
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel
+
+
+def create_control_router(
+    get_client_repo: Callable,
+    get_conn_repo: Callable,
+    get_settings_repo: Callable,
+    get_policy_repo: Callable,
+    get_activity_repo: Callable,
+    get_approval_repo: Callable,
+    get_credential_repo: Callable | None = None,
+    get_codex_profile_repo: Callable | None = None,
+    get_access_control: Callable | None = None,
+    prefix: str = "/control/mcp",
+) -> APIRouter:
+    async def require_control_admin(request: Request) -> None:
+        principal = getattr(request.state, "principal", None)
+        if principal is None or getattr(principal, "status", None) != "active":
+            raise HTTPException(
+                status_code=401, detail="Active authenticated principal required"
+            )
+        if get_access_control is None:
+            raise HTTPException(status_code=503, detail="Control authorization unavailable")
+        if not await get_access_control().check_control_role(
+            str(principal.principal_id), "ADMIN"
+        ):
+            raise HTTPException(status_code=403, detail="Control administrator role required")
+
+    router = APIRouter(
+        prefix=prefix,
+        tags=["mcp-control"],
+        dependencies=[Depends(require_control_admin)],
+    )
+
+    class ClientCreateReq(BaseModel):
+        client_id: str
+        display_name: str
+        client_type: str
+        principal_id: str
+        metadata: dict[str, Any] = {}
+
+    @router.post("/clients", status_code=201)
+    async def create_client(req: ClientCreateReq, repo=Depends(get_client_repo)):
+        await repo.create_client(
+            client_id=req.client_id,
+            display_name=req.display_name,
+            client_type=req.client_type,
+            principal_id=req.principal_id,
+            metadata=req.metadata,
+        )
+        return {"status": "created", "client_id": req.client_id}
+
+    @router.get("/clients")
+    async def list_clients(repo=Depends(get_client_repo)):
+        clients = await repo.list_clients()
+        return {"clients": clients}
+
+    @router.get("/clients/{client_id}")
+    async def get_client(client_id: str, repo=Depends(get_client_repo)):
+        client = await repo.get_client(client_id)
+        if not client:
+            raise HTTPException(status_code=404, detail="Client not found")
+        return client
+
+    @router.get("/connections")
+    async def list_connections(
+        client_id: str | None = None, repo=Depends(get_conn_repo)
+    ):
+        conns = await repo.list_active_connections(client_id=client_id)
+        return {"connections": conns}
+
+    @router.get("/settings")
+    async def get_settings(repo=Depends(get_settings_repo)):
+        settings = await repo.get_all_settings()
+        return {"settings": settings}
+
+    @router.post("/settings")
+    async def update_setting(key: str, value: Any, repo=Depends(get_settings_repo)):
+        await repo.set_setting(key, value)
+        return {"status": "updated", "key": key}
+
+    class PolicyCreateReq(BaseModel):
+        rule_id: str
+        scope_type: str
+        operation: str
+        effect: str
+        created_by: str
+        scope_id: str | None = None
+        priority: int = 100
+        conditions: dict[str, Any] = {}
+
+    @router.post("/policies", status_code=201)
+    async def create_policy(req: PolicyCreateReq, repo=Depends(get_policy_repo)):
+        await repo.create_rule(
+            rule_id=req.rule_id,
+            scope_type=req.scope_type,
+            operation=req.operation,
+            effect=req.effect,
+            created_by=req.created_by,
+            scope_id=req.scope_id,
+            priority=req.priority,
+            conditions=req.conditions,
+        )
+        return {"status": "created", "rule_id": req.rule_id}
+
+    @router.get("/policies")
+    async def list_policies(
+        operation: str | None = None, repo=Depends(get_policy_repo)
+    ):
+        rules = await repo.list_rules(operation=operation)
+        return {"rules": rules}
+
+    @router.put("/clients/{client_id}/enabled")
+    async def toggle_client_enabled(
+        client_id: str, enabled: bool, repo=Depends(get_client_repo)
+    ):
+        await repo.toggle_client_enabled(client_id, enabled)
+        return {"status": "updated", "client_id": client_id, "enabled": enabled}
+
+    @router.get("/clients/{client_id}/bindings")
+    async def list_bindings(client_id: str, repo=Depends(get_client_repo)):
+        bindings = await repo.list_bindings(client_id)
+        return {"bindings": bindings}
+
+    @router.get("/managed-clients")
+    @router.get("/codex", include_in_schema=False)
+    async def list_managed_clients(
+        client_repo=Depends(get_client_repo),
+        conn_repo=Depends(get_conn_repo),
+        approval_repo=Depends(get_approval_repo),
+    ):
+        """Secret-safe Codex state; credentials are summaries only."""
+        if get_credential_repo is None or get_codex_profile_repo is None:
+            raise HTTPException(
+                status_code=503, detail="Codex control plane unavailable"
+            )
+        credential_repo = get_credential_repo()
+        profile_repo = get_codex_profile_repo()
+        active = await conn_repo.list_active_connections()
+        pending = await approval_repo.list_pending_approvals()
+        result = []
+        for client in await client_repo.list_clients():
+            if client.get("client_type") not in {"codex", "antigravity"}:
+                continue
+            bindings = await client_repo.list_bindings(client["client_id"])
+            entries = []
+            for binding in bindings:
+                entries.append(
+                    {
+                        "binding": binding,
+                        "profile": await profile_repo.get(binding["binding_id"]),
+                        "credentials": await credential_repo.list_for_binding(
+                            binding["binding_id"]
+                        ),
+                        "active_connections": sum(
+                            1
+                            for connection in active
+                            if connection["client_id"] == client["client_id"]
+                            and connection.get("project_id")
+                            == binding["external_project_id"]
+                        ),
+                        "pending_approvals": sum(
+                            1
+                            for approval in pending
+                            if approval["client_id"] == client["client_id"]
+                        ),
+                    }
+                )
+            result.append({"client": client, "bindings": entries})
+        return {"clients": result}
+
+    @router.post("/credentials/{credential_id}/revoke")
+    @router.post("/codex/credentials/{credential_id}/revoke", include_in_schema=False)
+    async def revoke_managed_credential(credential_id: str):
+        if get_credential_repo is None:
+            raise HTTPException(
+                status_code=503, detail="Codex control plane unavailable"
+            )
+        credential = await get_credential_repo().get_summary(credential_id)
+        if credential is None:
+            raise HTTPException(status_code=404, detail="Credential not found")
+        if not await get_credential_repo().revoke(credential_id):
+            raise HTTPException(status_code=409, detail="Credential is not active")
+        return {"status": "revoked", "credential_id": credential_id}
+
+    @router.get("/activity")
+    async def list_activity(
+        limit: int = 50,
+        offset: int = 0,
+        client_id: str | None = None,
+        status: str | None = None,
+        repo=Depends(get_activity_repo),
+    ):
+        calls = await repo.list_recent_calls(
+            limit=limit, offset=offset, client_id=client_id, status=status
+        )
+        return {"activity": calls}
+
+    @router.get("/activity/{call_id}")
+    async def get_activity_call(call_id: str, repo=Depends(get_activity_repo)):
+        call = await repo.get_call(call_id)
+        if not call:
+            raise HTTPException(status_code=404, detail="Call not found")
+        return call
+
+    @router.get("/approvals")
+    async def list_approvals(
+        status: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        repo=Depends(get_approval_repo),
+    ):
+        approvals = await repo.list_approvals(status=status, limit=limit, offset=offset)
+        return {"approvals": approvals}
+
+    @router.get("/approvals/pending")
+    async def list_pending_approvals_endpoint(
+        client_id: str | None = None, repo=Depends(get_approval_repo)
+    ):
+        approvals = await repo.list_pending_approvals(client_id=client_id)
+        return {"approvals": approvals}
+
+    class DecideApprovalReq(BaseModel):
+        status: str
+        reason: str | None = None
+
+    @router.post("/approvals/{approval_id}/decide")
+    async def decide_approval_endpoint(
+        approval_id: str,
+        req: DecideApprovalReq,
+        request: Request,
+        repo=Depends(get_approval_repo),
+    ):
+        if req.status not in ("APPROVED", "REJECTED"):
+            raise HTTPException(
+                status_code=400, detail="Status must be APPROVED or REJECTED"
+            )
+        principal = getattr(request.state, "principal", None)
+        if principal is None or getattr(principal, "status", None) != "active":
+            raise HTTPException(
+                status_code=401, detail="Active authenticated principal required"
+            )
+        decided = await repo.decide_approval(
+            approval_id, req.status, str(principal.principal_id), req.reason
+        )
+        if not decided:
+            if await repo.get_approval_request(approval_id) is None:
+                raise HTTPException(status_code=404, detail="Approval not found")
+            raise HTTPException(status_code=409, detail="Approval is no longer pending")
+        return {"status": "decided", "approval_id": approval_id, "decision": req.status}
+
+    @router.get("/overview")
+    async def get_overview(
+        client_repo=Depends(get_client_repo),
+        conn_repo=Depends(get_conn_repo),
+        activity_repo=Depends(get_activity_repo),
+        approval_repo=Depends(get_approval_repo),
+    ):
+        clients = await client_repo.list_clients()
+        conns = await conn_repo.count_by_status()
+        pending = await approval_repo.count_pending()
+        calls = await activity_repo.count_calls_by_status()
+
+        return {
+            "total_clients": len(clients),
+            "active_clients": len([c for c in clients if c.get("enabled")]),
+            "connections_by_status": conns,
+            "pending_approvals": pending,
+            "calls_by_status": calls,
+        }
+
+    return router

mesa_api/schemas.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ErrorResponse(BaseModel):
+    """Standardised error response for all API error paths."""
+
+    model_config = ConfigDict(frozen=True)
+
+    error: str = Field(..., description="Machine-readable error code")
+    detail: str = Field(..., description="Human-readable error description")
+    status_code: int = Field(..., ge=400, le=599)
+    retryable: bool = Field(
+        default=False, description="Whether retrying unchanged may succeed later"
+    )