AccessGate 0.2.0a1__py3-none-any.whl

access_gate/mcp/server.py

@@ -0,0 +1,378 @@
+"""Dependency-free JSON-RPC stdio MCP server for AccessGate."""
+
+from __future__ import annotations
+
+import json
+import math
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, cast
+
+from ..abac import (
+    AttributePolicy,
+    OperatorRegistry,
+    PolicySchemaError,
+    load_policy_schema,
+    loads_policy,
+)
+
+PROTOCOL_VERSION = "2025-06-18"
+CONTRACT_PATH = Path(__file__).with_name("agent-contract.json")
+MAX_MESSAGE_CHARS = 1_100_000
+MAX_JSON_NUMBER_CHARS = 256
+
+
+def _reject_json_constant(value: str) -> None:
+    raise ValueError(f"Unsupported JSON constant: {value}")
+
+
+def _reject_duplicate_json_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    value: dict[str, object] = {}
+    for key, item in pairs:
+        if key in value:
+            raise ValueError(f"Duplicate JSON object key: {key}")
+        value[key] = item
+    return value
+
+
+def _parse_json_integer(value: str) -> int:
+    if len(value) > MAX_JSON_NUMBER_CHARS:
+        raise ValueError("JSON integer exceeds the digit limit.")
+    return int(value)
+
+
+def _parse_json_float(value: str) -> float:
+    if len(value) > MAX_JSON_NUMBER_CHARS:
+        raise ValueError("JSON number exceeds the digit limit.")
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError("JSON numbers must be finite.")
+    return number
+
+
+def parse_message(document: str) -> object:
+    """Parse one bounded, unambiguous JSON-RPC message."""
+
+    if not isinstance(document, str):
+        raise TypeError("MCP messages must be strings.")
+    if len(document) > MAX_MESSAGE_CHARS:
+        raise ValueError("MCP message exceeds the size limit.")
+    return json.loads(
+        document,
+        parse_constant=_reject_json_constant,
+        parse_float=_parse_json_float,
+        parse_int=_parse_json_integer,
+        object_pairs_hook=_reject_duplicate_json_object,
+    )
+
+
+def load_contract() -> dict[str, Any]:
+    with CONTRACT_PATH.open("r", encoding="utf-8") as handle:
+        return cast(dict[str, Any], json.load(handle))
+
+
+def compact_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def pretty_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, indent=2)
+
+
+def write_message(message: dict[str, Any]) -> None:
+    sys.stdout.write(compact_json(message) + "\n")
+    sys.stdout.flush()
+
+
+def result(request_id: Any, payload: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": payload}
+
+
+def error(request_id: Any, code: int, message: str, data: Any | None = None) -> dict[str, Any]:
+    body: dict[str, Any] = {"code": code, "message": message}
+    if data is not None:
+        body["data"] = data
+    return {"jsonrpc": "2.0", "id": request_id, "error": body}
+
+
+def list_resources(contract: dict[str, Any]) -> dict[str, Any]:
+    offering_id = contract["offering"]["id"]
+    resources = [
+        {
+            "uri": f"opensource://{offering_id}/agent-contract",
+            "name": "agent-contract",
+            "title": "Full Agent Contract",
+            "description": "The complete public MCP operating contract for AccessGate.",
+            "mimeType": "application/json",
+        },
+        {
+            "uri": f"opensource://{offering_id}/policy-schema",
+            "name": "policy-schema",
+            "title": "ABAC Policy JSON Schema",
+            "description": "The packaged access_gate.policy.v1 JSON Schema.",
+            "mimeType": "application/schema+json",
+        },
+    ]
+    for resource in contract.get("resources", []):
+        resources.append(
+            {
+                "uri": resource["uri"],
+                "name": resource.get("name", resource["uri"].rsplit("/", 1)[-1]),
+                "title": resource.get("title", resource.get("name", resource["uri"])),
+                "description": resource.get("description", ""),
+                "mimeType": resource.get("mimeType", "application/json"),
+            }
+        )
+    return {"resources": resources}
+
+
+def read_resource(contract: dict[str, Any], uri: str) -> dict[str, Any]:
+    offering_id = contract["offering"]["id"]
+    if uri == f"opensource://{offering_id}/agent-contract":
+        text = pretty_json(contract)
+        mime_type = "application/json"
+    elif uri == f"opensource://{offering_id}/policy-schema":
+        text = pretty_json(load_policy_schema())
+        mime_type = "application/schema+json"
+    else:
+        for resource in contract.get("resources", []):
+            if resource.get("uri") == uri:
+                value = resource.get("content", resource.get("data", resource))
+                text = value if isinstance(value, str) else pretty_json(value)
+                mime_type = resource.get("mimeType", "application/json")
+                break
+        else:
+            raise KeyError(uri)
+    return {"contents": [{"uri": uri, "mimeType": mime_type, "text": text}]}
+
+
+def list_tools(contract: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "tools": [
+            {
+                "name": tool["name"],
+                "title": tool.get("title", tool["name"].replace("_", " ").title()),
+                "description": tool.get("description", ""),
+                "inputSchema": tool.get("inputSchema", {"type": "object", "properties": {}}),
+                "outputSchema": tool.get("outputSchema"),
+                "annotations": tool.get("annotations", {}),
+            }
+            for tool in contract.get("tools", [])
+        ]
+    }
+
+
+def _validation_result(arguments: dict[str, Any]) -> dict[str, Any]:
+    policy_value = arguments.get("policy")
+    try:
+        if isinstance(policy_value, str):
+            policy = loads_policy(policy_value)
+        elif isinstance(policy_value, Mapping):
+            policy = AttributePolicy.from_dict(cast(Mapping[str, object], policy_value))
+        else:
+            raise PolicySchemaError("policy must be a JSON object or JSON string.")
+    except PolicySchemaError as validation_error:
+        message = str(validation_error)
+        return {
+            "content": [{"type": "text", "text": f"Policy validation failed: {message}"}],
+            "structuredContent": {"valid": False, "errors": [message]},
+            "isError": True,
+        }
+    return {
+        "content": [{"type": "text", "text": "Policy is valid for access_gate.policy.v1."}],
+        "structuredContent": {"valid": True, "policy": policy.to_dict(), "errors": []},
+        "isError": False,
+    }
+
+
+def call_tool(contract: dict[str, Any], name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    configured = next(
+        (tool for tool in contract.get("tools", []) if tool.get("name") == name),
+        None,
+    )
+    if configured is None:
+        raise KeyError(name)
+    if name == "validate_policy_document":
+        return _validation_result(arguments)
+    if name == "list_builtin_operators":
+        names = OperatorRegistry().names
+        return {
+            "content": [
+                {"type": "text", "text": "Built-in ABAC operators: " + ", ".join(names)}
+            ],
+            "structuredContent": {"operators": list(names)},
+            "isError": False,
+        }
+    if name == "get_policy_schema":
+        return {
+            "content": [{"type": "text", "text": "AccessGate ABAC policy JSON Schema."}],
+            "structuredContent": {"schema": load_policy_schema()},
+            "isError": False,
+        }
+
+    structured = {
+        "offering": contract["offering"],
+        "tool": configured,
+        "arguments": arguments,
+        "executionMode": configured.get("executionMode", "contract"),
+        "access": contract.get("publicAccess", {}),
+        "security": contract.get("security", {}),
+    }
+    return {
+        "content": [
+            {
+                "type": "text",
+                "text": (
+                    f"{configured.get('title', name)} is available for AccessGate.\n\n"
+                    f"Purpose: {configured.get('description', '')}\n\n"
+                    "Use the structured content to prepare a reviewed authorization design."
+                ),
+            }
+        ],
+        "structuredContent": structured,
+        "isError": False,
+    }
+
+
+def list_prompts(contract: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "prompts": [
+            {
+                "name": prompt["name"],
+                "title": prompt.get("title", prompt["name"].replace("_", " ").title()),
+                "description": prompt.get("description", ""),
+                "arguments": prompt.get("arguments", []),
+            }
+            for prompt in contract.get("prompts", [])
+        ]
+    }
+
+
+def get_prompt(contract: dict[str, Any], name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    for prompt in contract.get("prompts", []):
+        if prompt.get("name") == name:
+            text = prompt.get("template", "")
+            for key, value in arguments.items():
+                text = text.replace("{" + key + "}", str(value))
+            return {
+                "description": prompt.get("description", ""),
+                "messages": [{"role": "user", "content": {"type": "text", "text": text}}],
+            }
+    raise KeyError(name)
+
+
+def handle(message: object, contract: dict[str, Any]) -> dict[str, Any] | None:
+    if not isinstance(message, Mapping):
+        return error(None, -32600, "Invalid Request")
+
+    is_notification = "id" not in message
+    request_id = message.get("id")
+    if message.get("jsonrpc") != "2.0":
+        return None if is_notification else error(request_id, -32600, "Invalid Request")
+    if not is_notification and (
+        isinstance(request_id, bool) or not isinstance(request_id, str | int | type(None))
+    ):
+        return error(None, -32600, "Invalid Request")
+    method = message.get("method")
+    if not isinstance(method, str) or not method:
+        return None if is_notification else error(request_id, -32600, "Invalid Request")
+    raw_params = message.get("params", {})
+    if raw_params is None:
+        raw_params = {}
+    if not isinstance(raw_params, Mapping):
+        return None if is_notification else error(request_id, -32602, "Invalid params")
+    params = cast(Mapping[str, Any], raw_params)
+
+    response: dict[str, Any]
+    try:
+        if method == "initialize":
+            response = result(
+                request_id,
+                {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "capabilities": {
+                        "resources": {"listChanged": False},
+                        "tools": {"listChanged": False},
+                        "prompts": {"listChanged": False},
+                    },
+                    "serverInfo": {
+                        "name": contract["server"]["name"],
+                        "title": contract["server"].get("title", "AccessGate"),
+                        "version": contract["server"].get("version", "0.2.0a1"),
+                    },
+                    "instructions": contract.get("instructions", ""),
+                },
+            )
+        elif method == "resources/list":
+            response = result(request_id, list_resources(contract))
+        elif method == "resources/read":
+            uri = params["uri"]
+            if not isinstance(uri, str):
+                raise TypeError("uri must be a string")
+            response = result(request_id, read_resource(contract, uri))
+        elif method == "tools/list":
+            response = result(request_id, list_tools(contract))
+        elif method == "tools/call":
+            name = params["name"]
+            arguments = params.get("arguments", {})
+            if arguments is None:
+                arguments = {}
+            if not isinstance(name, str) or not isinstance(arguments, Mapping):
+                raise TypeError("tool name and arguments have invalid types")
+            response = result(
+                request_id,
+                call_tool(contract, name, dict(arguments)),
+            )
+        elif method == "prompts/list":
+            response = result(request_id, list_prompts(contract))
+        elif method == "prompts/get":
+            name = params["name"]
+            arguments = params.get("arguments", {})
+            if arguments is None:
+                arguments = {}
+            if not isinstance(name, str) or not isinstance(arguments, Mapping):
+                raise TypeError("prompt name and arguments have invalid types")
+            response = result(
+                request_id,
+                get_prompt(contract, name, dict(arguments)),
+            )
+        else:
+            response = error(request_id, -32601, f"Method not found: {method}")
+    except (KeyError, TypeError, ValueError) as request_error:
+        response = error(request_id, -32602, f"Unknown or invalid parameter: {request_error}")
+    except Exception as internal_error:  # pragma: no cover - defensive protocol boundary
+        response = error(
+            request_id,
+            -32603,
+            "Internal error",
+            {"detail": type(internal_error).__name__},
+        )
+    return None if is_notification else response
+
+
+def main() -> None:
+    contract = load_contract()
+    while True:
+        line = sys.stdin.readline(MAX_MESSAGE_CHARS + 1)
+        if not line:
+            break
+        if len(line) > MAX_MESSAGE_CHARS:
+            while line and not line.endswith("\n"):
+                line = sys.stdin.readline(MAX_MESSAGE_CHARS + 1)
+            write_message(error(None, -32700, "Message exceeds the size limit"))
+            continue
+        if not line.strip():
+            continue
+        try:
+            message = parse_message(line)
+        except (json.JSONDecodeError, RecursionError, TypeError, ValueError) as parse_error:
+            write_message(error(None, -32700, "Parse error", {"detail": str(parse_error)}))
+            continue
+        response = handle(message, contract)
+        if response is not None:
+            write_message(response)
+
+
+if __name__ == "__main__":
+    main()

access_gate/policies.py

@@ -0,0 +1,242 @@
+"""Small, composable policies for common authorization models."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Collection
+from dataclasses import dataclass, field
+from enum import Enum
+
+from .types import AuthorizationRequest, Decision
+
+
+class MissEffect(str, Enum):
+    """What a granting policy should do when its condition does not match."""
+
+    DENY = "deny"
+    ABSTAIN = "abstain"
+
+
+_MAX_CONFIGURED_NAMES = 4_096
+
+
+def _targets(action: str, actions: frozenset[str] | None) -> bool:
+    return actions is None or action in actions
+
+
+def _names(
+    values: Collection[str],
+    *,
+    field_name: str,
+    allow_empty: bool = False,
+) -> frozenset[str]:
+    if isinstance(values, str):
+        raise TypeError(f"{field_name} must be a collection of names, not a string.")
+    names = frozenset(values)
+    if not allow_empty and not names:
+        raise ValueError(f"{field_name} must contain at least one name.")
+    if len(names) > _MAX_CONFIGURED_NAMES:
+        raise ValueError(f"{field_name} exceeds the maximum item count.")
+    if not all(isinstance(value, str) and value for value in names):
+        raise TypeError(f"{field_name} must contain only non-empty strings.")
+    return names
+
+
+def _actions(values: Collection[str] | None) -> frozenset[str] | None:
+    return None if values is None else _names(values, field_name="actions")
+
+
+def _policy_name(value: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise TypeError("policy name must be a non-empty string.")
+    return value
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class FunctionPolicy:
+    """Adapt an application callable to the Policy protocol."""
+
+    name: str
+    evaluator: Callable[[AuthorizationRequest], Decision | None]
+    actions: frozenset[str] | None = None
+
+    def __init__(
+        self,
+        name: str,
+        evaluator: Callable[[AuthorizationRequest], Decision | None],
+        *,
+        actions: Collection[str] | None = None,
+    ) -> None:
+        object.__setattr__(self, "name", _policy_name(name))
+        if not callable(evaluator):
+            raise TypeError("policy evaluator must be callable.")
+        object.__setattr__(self, "evaluator", evaluator)
+        object.__setattr__(self, "actions", _actions(actions))
+
+    def evaluate(self, request: AuthorizationRequest) -> Decision | None:
+        if not _targets(request.action, self.actions):
+            return None
+        return self.evaluator(request)
+
+
+@dataclass(frozen=True, slots=True)
+class RolePolicy:
+    """Allow subjects possessing any or all required roles."""
+
+    required_roles: frozenset[str]
+    actions: frozenset[str] | None = None
+    require_all: bool = False
+    on_miss: MissEffect = MissEffect.DENY
+    name: str = "role"
+
+    def __init__(
+        self,
+        required_roles: Collection[str],
+        *,
+        actions: Collection[str] | None = None,
+        require_all: bool = False,
+        on_miss: MissEffect = MissEffect.DENY,
+        name: str = "role",
+    ) -> None:
+        object.__setattr__(
+            self,
+            "required_roles",
+            _names(required_roles, field_name="required_roles"),
+        )
+        if not isinstance(require_all, bool):
+            raise TypeError("require_all must be a boolean.")
+        if not isinstance(on_miss, MissEffect):
+            raise TypeError("on_miss must be a MissEffect value.")
+        object.__setattr__(self, "actions", _actions(actions))
+        object.__setattr__(self, "require_all", require_all)
+        object.__setattr__(self, "on_miss", on_miss)
+        object.__setattr__(self, "name", _policy_name(name))
+
+    def evaluate(self, request: AuthorizationRequest) -> Decision | None:
+        if not _targets(request.action, self.actions):
+            return None
+        roles = request.subject.roles
+        matches = (
+            self.required_roles <= roles
+            if self.require_all
+            else bool(self.required_roles & roles)
+        )
+        if matches:
+            return Decision.allow("The subject has a required role.", policy=self.name)
+        if self.on_miss is MissEffect.ABSTAIN:
+            return None
+        return Decision.deny("The subject lacks a required role.", policy=self.name)
+
+
+@dataclass(frozen=True, slots=True)
+class OwnerPolicy:
+    """Allow when a resource owner attribute equals the subject identifier."""
+
+    actions: frozenset[str] | None = None
+    owner_attribute: str = "owner_id"
+    on_miss: MissEffect = MissEffect.DENY
+    name: str = "owner"
+
+    def __init__(
+        self,
+        *,
+        actions: Collection[str] | None = None,
+        owner_attribute: str = "owner_id",
+        on_miss: MissEffect = MissEffect.DENY,
+        name: str = "owner",
+    ) -> None:
+        object.__setattr__(self, "actions", _actions(actions))
+        if not isinstance(owner_attribute, str) or not owner_attribute:
+            raise TypeError("owner_attribute must be a non-empty string.")
+        if not isinstance(on_miss, MissEffect):
+            raise TypeError("on_miss must be a MissEffect value.")
+        object.__setattr__(self, "owner_attribute", owner_attribute)
+        object.__setattr__(self, "on_miss", on_miss)
+        object.__setattr__(self, "name", _policy_name(name))
+
+    def evaluate(self, request: AuthorizationRequest) -> Decision | None:
+        if not _targets(request.action, self.actions):
+            return None
+        owner_id = None
+        if request.resource is not None:
+            owner_id = request.resource.attributes.get(self.owner_attribute)
+        if (
+            request.subject.authenticated
+            and request.subject.identifier
+            and isinstance(owner_id, str)
+            and owner_id == request.subject.identifier
+        ):
+            return Decision.allow("The subject owns the resource.", policy=self.name)
+        if self.on_miss is MissEffect.ABSTAIN:
+            return None
+        return Decision.deny("The subject does not own the resource.", policy=self.name)
+
+
+@dataclass(frozen=True, slots=True)
+class TenantBoundaryPolicy:
+    """Deny cross-tenant access without granting same-tenant access by itself."""
+
+    actions: frozenset[str] | None = None
+    subject_attribute: str = "tenant_id"
+    resource_attribute: str = "tenant_id"
+    name: str = "tenant_boundary"
+
+    def __init__(
+        self,
+        *,
+        actions: Collection[str] | None = None,
+        subject_attribute: str = "tenant_id",
+        resource_attribute: str = "tenant_id",
+        name: str = "tenant_boundary",
+    ) -> None:
+        object.__setattr__(self, "actions", _actions(actions))
+        if not isinstance(subject_attribute, str) or not subject_attribute:
+            raise TypeError("subject_attribute must be a non-empty string.")
+        if not isinstance(resource_attribute, str) or not resource_attribute:
+            raise TypeError("resource_attribute must be a non-empty string.")
+        object.__setattr__(self, "subject_attribute", subject_attribute)
+        object.__setattr__(self, "resource_attribute", resource_attribute)
+        object.__setattr__(self, "name", _policy_name(name))
+
+    def evaluate(self, request: AuthorizationRequest) -> Decision | None:
+        if not _targets(request.action, self.actions):
+            return None
+        subject_tenant = request.subject.attributes.get(self.subject_attribute)
+        resource_tenant = None
+        if request.resource is not None:
+            resource_tenant = request.resource.attributes.get(self.resource_attribute)
+        if subject_tenant is None or resource_tenant is None:
+            return Decision.deny("Tenant scope is missing.", policy=self.name)
+        if (
+            not isinstance(subject_tenant, str)
+            or not subject_tenant
+            or not isinstance(resource_tenant, str)
+            or not resource_tenant
+        ):
+            return Decision.deny("Tenant scope is invalid.", policy=self.name)
+        if subject_tenant != resource_tenant:
+            return Decision.deny("Cross-tenant access is forbidden.", policy=self.name)
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticatedPolicy:
+    """Allow authenticated subjects for selected actions."""
+
+    actions: frozenset[str] | None = field(default=None)
+    name: str = "authenticated"
+
+    def __init__(
+        self,
+        *,
+        actions: Collection[str] | None = None,
+        name: str = "authenticated",
+    ) -> None:
+        object.__setattr__(self, "actions", _actions(actions))
+        object.__setattr__(self, "name", _policy_name(name))
+
+    def evaluate(self, request: AuthorizationRequest) -> Decision | None:
+        if not _targets(request.action, self.actions):
+            return None
+        if request.subject.authenticated:
+            return Decision.allow("The subject is authenticated.", policy=self.name)
+        return Decision.deny("Authentication is required.", policy=self.name)

access_gate/protocols.py

@@ -0,0 +1,51 @@
+"""Extension interfaces for application-specific authorization behaviour."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol, TypeVar
+
+from .types import AuthorizationRequest, Decision, Resource, Subject
+
+SubjectSource = TypeVar("SubjectSource", contravariant=True)
+ResourceSource = TypeVar("ResourceSource", contravariant=True)
+
+
+class Policy(Protocol):
+    """Evaluate one authorization concern.
+
+    Returning ``None`` means that the policy abstains. Returning a decision
+    means that the policy explicitly allows or denies the request.
+    """
+
+    name: str
+
+    def evaluate(self, request: AuthorizationRequest) -> Decision | None: ...
+
+
+class DecisionStrategy(Protocol):
+    """Combine individual policy results into one final decision."""
+
+    def combine(
+        self,
+        request: AuthorizationRequest,
+        decisions: Sequence[Decision],
+    ) -> Decision: ...
+
+
+class AuditSink(Protocol):
+    """Receive every final authorization decision."""
+
+    def record(self, request: AuthorizationRequest, decision: Decision) -> None: ...
+
+
+class SubjectResolver(Protocol[SubjectSource]):
+    """Convert an application identity into an AccessGate subject."""
+
+    def resolve_subject(self, source: SubjectSource) -> Subject: ...
+
+
+class ResourceResolver(Protocol[ResourceSource]):
+    """Convert an application object into an AccessGate resource."""
+
+    def resolve_resource(self, source: ResourceSource) -> Resource: ...