actenon-kernel 0.1.0__py3-none-any.whl

actenon/__init__.py

@@ -0,0 +1,11 @@
+"""Public package front door for the Actenon kernel."""
+
+from .gate import ActenonGate, GateOutcome
+from .models import ActionIntent, PCCB
+
+__all__ = [
+    "ActenonGate",
+    "ActionIntent",
+    "GateOutcome",
+    "PCCB",
+]

actenon/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""Provider adapter interfaces for protected consequential actions."""
+
+from .base import (
+    ProviderAdapter,
+    ProviderAdapterContext,
+    ProviderAdapterRequest,
+    ProviderAdapterResult,
+    ReconciliationCapableProviderAdapter,
+)
+from .edge import EdgeConfigurationError, ProtectedEdge
+
+__all__ = [
+    "EdgeConfigurationError",
+    "ProtectedEdge",
+    "ProviderAdapter",
+    "ProviderAdapterContext",
+    "ProviderAdapterRequest",
+    "ProviderAdapterResult",
+    "ReconciliationCapableProviderAdapter",
+]

actenon/adapters/_authorization.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from actenon.models import PCCB
+from actenon.preflight import PreflightEvidence
+
+
+@dataclass(frozen=True)
+class AdapterAuthorization:
+    """Proof material supplied by framework runtime context, never model input."""
+
+    proof: Mapping[str, Any] | PCCB | None
+    evidence: Mapping[str, Any] | PreflightEvidence | None = None
+
+
+def authorization_from_mapping(raw: Any) -> AdapterAuthorization:
+    if not isinstance(raw, Mapping):
+        return AdapterAuthorization(proof=None)
+    evidence = raw.get("evidence")
+    if evidence is not None and not isinstance(
+        evidence,
+        (Mapping, PreflightEvidence),
+    ):
+        evidence = None
+    return AdapterAuthorization(
+        proof=raw.get("proof"),
+        evidence=evidence,
+    )

actenon/adapters/base.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Protocol
+
+from actenon.models.contracts import ActionSpec, PCCB, TargetRef
+from actenon.models.runtime import ProtectedExecutionRequest
+
+if TYPE_CHECKING:  # pragma: no cover
+    from actenon.reconciliation.base import ProviderReconciliationSnapshot
+
+
+@dataclass(frozen=True)
+class ProviderAdapterContext:
+    """Execution context passed from the kernel to a provider adapter.
+
+    The context contains only execution-relevant identifiers and timing metadata.
+    It intentionally avoids embedding host-specific control-plane state so that
+    adapter implementations remain portable across integration environments.
+    """
+
+    request_id: str
+    intent_id: str
+    pccb_id: str
+    tenant_id: str
+    subject_id: str
+    audience: str
+    executed_at: datetime
+
+
+@dataclass(frozen=True)
+class ProviderAdapterRequest:
+    """Portable provider-adapter request produced after proof verification.
+
+    Adapters receive a normalized request derived from the protected execution
+    path. The request carries only the action, target, and execution context the
+    adapter needs to perform a side effect or translate the call into a
+    provider-specific operation.
+    """
+
+    action: ActionSpec
+    target: TargetRef
+    context: ProviderAdapterContext
+    pccb: PCCB
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_execution_request(cls, request: ProtectedExecutionRequest, *, metadata: dict[str, Any] | None = None) -> "ProviderAdapterRequest":
+        """Build a portable adapter request from a verified execution request."""
+
+        return cls(
+            action=request.intent.action,
+            target=request.intent.target,
+            context=ProviderAdapterContext(
+                request_id=request.context.request_id,
+                intent_id=request.intent.intent_id,
+                pccb_id=request.pccb.pccb_id,
+                tenant_id=request.intent.tenant.tenant_id,
+                subject_id=request.intent.requester.id,
+                audience=f"{request.context.audience.type}:{request.context.audience.id}",
+                executed_at=request.context.now,
+            ),
+            pccb=request.pccb,
+            metadata=dict(metadata or {}),
+        )
+
+
+@dataclass(frozen=True)
+class ProviderAdapterResult:
+    """Normalized side-effect result returned by a provider adapter.
+
+    The adapter result is intentionally generic. It lets the kernel or a future
+    reconciliation layer capture stable references without committing this
+    repository to a particular provider or control-plane product model.
+    """
+
+    provider_reference: str | None
+    provider_state: str
+    side_effect_reference: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+class ProviderAdapter(Protocol):
+    """Protocol for execution adapters that call consequential downstream systems.
+
+    Concrete provider integrations belong outside the open kernel. This
+    interface gives the paid or external ecosystem a stable execution boundary
+    without embedding those integrations here.
+    """
+
+    adapter_id: str
+    provider_name: str
+    supported_capabilities: tuple[str, ...]
+
+    def execute(self, request: ProviderAdapterRequest) -> ProviderAdapterResult:
+        """Execute a verified protected action against a downstream provider."""
+
+
+class ReconciliationCapableProviderAdapter(ProviderAdapter, Protocol):
+    """Optional provider-adapter extension for reconciliation-aware integrations."""
+
+    def fetch_reconciliation_snapshot(self, provider_reference: str) -> "ProviderReconciliationSnapshot":
+        """Return the latest provider view for a previously executed side effect."""

actenon/adapters/edge.py

@@ -0,0 +1,129 @@
+"""Hardened resource-side adapter for exact-request proof enforcement."""
+
+from __future__ import annotations
+
+import copy
+import inspect
+from typing import Any, Callable, Mapping, Union
+
+from actenon.credentials import BrokeredCredential
+from actenon.gate import ActenonGate, GateOutcome
+from actenon.models import ActionIntent, AudienceRef, PCCB
+from actenon.preflight import PreflightEvidence
+from actenon.proof import canonicalize_json
+
+
+RawRequestedAction = Mapping[str, Any]
+IntentBuilder = Callable[
+    [RawRequestedAction],
+    Union[ActionIntent, dict[str, Any]],
+]
+BrokeredBackend = Callable[[ActionIntent, BrokeredCredential], Any]
+
+
+class EdgeConfigurationError(ValueError):
+    """Raised when an edge cannot bind every requested field into its intent."""
+
+
+class ProtectedEdge:
+    """Verify an agent request before a brokered resource-side side effect.
+
+    The raw request is snapshotted and must appear exactly in
+    ``ActionIntent.action.parameters``. The backend receives only the verified
+    request intent and a brokered credential; it never receives the PCCB or an
+    action reconstructed from proof contents.
+    """
+
+    def __init__(
+        self,
+        gate: ActenonGate,
+        *,
+        intent_builder: IntentBuilder,
+        backend: BrokeredBackend,
+        audience: AudienceRef | str | None = None,
+    ) -> None:
+        if not isinstance(gate, ActenonGate):
+            raise TypeError("gate must be an ActenonGate")
+        if not callable(intent_builder):
+            raise TypeError("intent_builder must be callable")
+        if not callable(backend):
+            raise TypeError("backend must be callable")
+        if inspect.iscoroutinefunction(intent_builder):
+            raise TypeError("ProtectedEdge currently requires a synchronous intent_builder")
+        if inspect.iscoroutinefunction(backend):
+            raise TypeError("ProtectedEdge currently requires a synchronous backend")
+        self._gate = gate
+        self._intent_builder = intent_builder
+        self._backend = backend
+        self._audience = audience
+
+    def intent_for(self, requested_action: RawRequestedAction) -> ActionIntent:
+        """Build a detached Action Intent that binds the complete raw request."""
+
+        if isinstance(requested_action, ActionIntent) or not isinstance(
+            requested_action, Mapping
+        ):
+            raise TypeError("requested_action must be a raw mapping, not an ActionIntent")
+        request_snapshot = copy.deepcopy(dict(requested_action))
+        try:
+            request_canonical = canonicalize_json(request_snapshot)
+        except (TypeError, ValueError, RecursionError) as exc:
+            raise EdgeConfigurationError(
+                "requested_action must be valid canonical JSON data"
+            ) from exc
+
+        built = self._intent_builder(copy.deepcopy(request_snapshot))
+        try:
+            intent = (
+                ActionIntent.from_dict(built.to_dict())
+                if isinstance(built, ActionIntent)
+                else ActionIntent.from_dict(built)
+            )
+        except (TypeError, ValueError) as exc:
+            raise EdgeConfigurationError(
+                "intent_builder must return a valid ActionIntent or Action Intent mapping"
+            ) from exc
+
+        try:
+            bound_parameters = canonicalize_json(intent.action.parameters)
+        except (TypeError, ValueError, RecursionError) as exc:
+            raise EdgeConfigurationError(
+                "intent_builder produced action parameters that are not canonical JSON"
+            ) from exc
+        if bound_parameters != request_canonical:
+            raise EdgeConfigurationError(
+                "intent_builder must bind the complete raw requested action exactly "
+                "as ActionIntent.action.parameters"
+            )
+        return intent
+
+    def execute(
+        self,
+        requested_action: RawRequestedAction,
+        proof: Mapping[str, Any] | PCCB | None,
+        *,
+        evidence: Mapping[str, Any] | PreflightEvidence | None = None,
+    ) -> GateOutcome:
+        """Execute only the raw request proven by the supplied PCCB."""
+
+        intent = self.intent_for(requested_action)
+        return self._gate.protect(
+            intent,
+            proof,
+            lambda protected_request, credential: self._backend(
+                protected_request.intent,
+                credential,
+            ),
+            audience=self._audience,
+            evidence=evidence,
+            _missing_proof_reason_code="NO_PROOF",
+        )
+
+
+__all__ = [
+    "BrokeredBackend",
+    "EdgeConfigurationError",
+    "IntentBuilder",
+    "ProtectedEdge",
+    "RawRequestedAction",
+]

actenon/adapters/fastapi.py

@@ -0,0 +1,161 @@
+"""FastAPI dependency for proof-gated endpoint execution."""
+
+from __future__ import annotations
+
+import base64
+import inspect
+import json
+from typing import Any, Callable, Mapping, Optional, Union
+
+from actenon.core import ContractValidationError
+from actenon.gate import ActenonGate, GateOutcome
+from actenon.models import ActionIntent, PCCB
+from actenon.preflight import PreflightEvidence
+
+try:
+    from fastapi import HTTPException, Request
+    from pydantic import ValidationError
+except ImportError as exc:  # pragma: no cover - exercised without the optional extra
+    raise ImportError(
+        "Actenon's FastAPI adapter requires the 'fastapi' extra: "
+        "python -m pip install 'actenon-kernel[fastapi]'"
+    ) from exc
+
+
+ACTENON_PROOF_HEADER = "X-Actenon-Proof"
+ACTENON_EVIDENCE_HEADER = "X-Actenon-Evidence"
+
+ActionBuilder = Callable[[Mapping[str, Any]], Union[ActionIntent, dict[str, Any]]]
+EvidenceBuilder = Callable[
+    [Mapping[str, Any]],
+    Optional[Union[Mapping[str, Any], PreflightEvidence]],
+]
+SideEffect = Callable[[Mapping[str, Any]], Any]
+
+
+def encode_json_header(value: Mapping[str, Any] | PCCB) -> str:
+    payload = value.to_dict() if isinstance(value, PCCB) else dict(value)
+    encoded = base64.urlsafe_b64encode(
+        json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    )
+    return encoded.decode("ascii").rstrip("=")
+
+
+def _decode_json_header(value: str, *, field_name: str) -> dict[str, Any]:
+    try:
+        padded = value + ("=" * (-len(value) % 4))
+        decoded = base64.urlsafe_b64decode(padded.encode("ascii"))
+        payload = json.loads(decoded.decode("utf-8"))
+    except (ValueError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{field_name} must be base64url-encoded JSON") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"{field_name} must decode to a JSON object")
+    return payload
+
+
+def fastapi_dependency(
+    gate: ActenonGate,
+    *,
+    action_builder: ActionBuilder,
+    side_effect: SideEffect,
+    body_model: type[Any] | None = None,
+    audience: Optional[str] = None,
+    evidence_builder: Optional[EvidenceBuilder] = None,
+    proof_header: str = ACTENON_PROOF_HEADER,
+    evidence_header: str = ACTENON_EVIDENCE_HEADER,
+) -> Callable[[Request], Any]:
+    """Build a dependency that executes the protected operation before the route.
+
+    The HTTP body contains only domain fields. The proof and optional local
+    evidence travel in base64url-encoded headers outside that domain schema.
+    """
+
+    if inspect.iscoroutinefunction(side_effect):
+        raise TypeError(
+            "fastapi_dependency currently requires a synchronous side_effect"
+        )
+
+    async def dependency(request: Request) -> GateOutcome:
+        try:
+            body = await request.json()
+        except (ValueError, UnicodeError, json.JSONDecodeError) as exc:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": "INVALID_JSON_BODY", "message": str(exc)},
+            ) from exc
+        if not isinstance(body, dict):
+            raise HTTPException(
+                status_code=400,
+                detail={
+                    "error": "INVALID_JSON_BODY",
+                    "message": "The protected endpoint body must be a JSON object.",
+                },
+            )
+        if body_model is not None:
+            try:
+                if hasattr(body_model, "model_validate"):
+                    validated = body_model.model_validate(body)
+                    body = validated.model_dump()
+                else:  # pragma: no cover - Pydantic v1 compatibility
+                    validated = body_model.parse_obj(body)
+                    body = validated.dict()
+            except ValidationError as exc:
+                raise HTTPException(status_code=422, detail=exc.errors()) from exc
+
+        proof: dict[str, Any] | None = None
+        raw_proof = request.headers.get(proof_header)
+        if raw_proof:
+            try:
+                proof = _decode_json_header(raw_proof, field_name=proof_header)
+            except ValueError:
+                # Let the gate emit the canonical schema Refusal and refused Receipt.
+                proof = {}
+
+        if evidence_builder is not None:
+            evidence = evidence_builder(body)
+        else:
+            evidence = None
+            raw_evidence = request.headers.get(evidence_header)
+            if raw_evidence:
+                try:
+                    evidence = _decode_json_header(
+                        raw_evidence,
+                        field_name=evidence_header,
+                    )
+                except ValueError as exc:
+                    raise HTTPException(
+                        status_code=400,
+                        detail={
+                            "error": "INVALID_ACTENON_EVIDENCE",
+                            "message": str(exc),
+                        },
+                    ) from exc
+
+        try:
+            action = action_builder(body)
+        except (ContractValidationError, KeyError, TypeError, ValueError) as exc:
+            raise HTTPException(
+                status_code=400,
+                detail={"error": "INVALID_ACTION", "message": str(exc)},
+            ) from exc
+
+        outcome = gate.protect(
+            action,
+            proof,
+            lambda: side_effect(body),
+            audience=audience,
+            evidence=evidence,
+        )
+        if not outcome.ok:
+            raise HTTPException(status_code=403, detail=outcome.to_dict())
+        return outcome
+
+    return dependency
+
+
+__all__ = [
+    "ACTENON_EVIDENCE_HEADER",
+    "ACTENON_PROOF_HEADER",
+    "encode_json_header",
+    "fastapi_dependency",
+]

actenon/adapters/langchain.py

@@ -0,0 +1,111 @@
+"""LangChain StructuredTool adapter with out-of-band proof injection."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Mapping, Optional, Union
+
+from actenon.gate import ActenonGate
+from actenon.models import ActionIntent, PCCB
+from actenon.preflight import PreflightEvidence
+
+from ._authorization import authorization_from_mapping
+
+try:
+    from langchain_core.runnables import RunnableConfig
+    from langchain_core.tools import StructuredTool, create_schema_from_function
+except ImportError as exc:  # pragma: no cover - exercised without the optional extra
+    raise ImportError(
+        "Actenon's LangChain adapter requires the 'langchain' extra: "
+        "python -m pip install 'actenon-kernel[langchain]'"
+    ) from exc
+
+
+ACTENON_CONFIG_KEY = "actenon"
+ActionBuilder = Callable[[Mapping[str, Any]], Union[ActionIntent, dict[str, Any]]]
+EvidenceBuilder = Callable[
+    [Mapping[str, Any]],
+    Optional[Union[Mapping[str, Any], PreflightEvidence]],
+]
+
+
+def actenon_runnable_config(
+    proof: Optional[Union[Mapping[str, Any], PCCB]],
+    *,
+    evidence: Optional[Union[Mapping[str, Any], PreflightEvidence]] = None,
+) -> RunnableConfig:
+    """Build runtime-only LangChain config; it is excluded from tool schemas."""
+
+    return {
+        "configurable": {
+            ACTENON_CONFIG_KEY: {
+                "proof": proof,
+                "evidence": evidence,
+            }
+        }
+    }
+
+
+def protected_structured_tool(
+    gate: ActenonGate,
+    domain_function: Callable[..., Any],
+    *,
+    action_builder: ActionBuilder,
+    audience: Optional[str] = None,
+    evidence_builder: Optional[EvidenceBuilder] = None,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    return_direct: bool = False,
+) -> StructuredTool:
+    """Wrap a plain sync function without exposing proof fields to the model."""
+
+    if not callable(domain_function):
+        raise TypeError("domain_function must be callable")
+    if inspect.iscoroutinefunction(domain_function):
+        raise TypeError(
+            "protected_structured_tool currently requires a synchronous domain function"
+        )
+    tool_name = name or domain_function.__name__
+    tool_description = description or domain_function.__doc__
+    if not tool_description:
+        raise ValueError("LangChain tools require a description or function docstring")
+    args_schema = create_schema_from_function(
+        f"{tool_name.title().replace('_', '')}Input",
+        domain_function,
+    )
+
+    def protected_call(config: RunnableConfig, **domain_args: Any) -> dict[str, Any]:
+        authorization = authorization_from_mapping(
+            config.get("configurable", {}).get(ACTENON_CONFIG_KEY)
+        )
+        evidence = (
+            evidence_builder(domain_args)
+            if evidence_builder is not None
+            else authorization.evidence
+        )
+        action = action_builder(domain_args)
+        outcome = gate.protect(
+            action,
+            authorization.proof,
+            lambda: domain_function(**domain_args),
+            audience=audience,
+            evidence=evidence,
+        )
+        return outcome.to_dict()
+
+    protected_call.__name__ = tool_name
+    protected_call.__doc__ = tool_description
+    return StructuredTool.from_function(
+        func=protected_call,
+        name=tool_name,
+        description=tool_description,
+        args_schema=args_schema,
+        return_direct=return_direct,
+    )
+
+
+__all__ = [
+    "ACTENON_CONFIG_KEY",
+    "actenon_runnable_config",
+    "protected_structured_tool",
+]

actenon/adapters/mcp.py

@@ -0,0 +1,118 @@
+"""FastMCP decorator for proof-gated tools with request-metadata proof."""
+
+from __future__ import annotations
+
+import inspect
+from functools import wraps
+from typing import Any, Callable, Mapping
+
+from actenon.gate import ActenonGate
+from actenon.models import ActionIntent, PCCB
+from actenon.preflight import PreflightEvidence
+
+from ._authorization import authorization_from_mapping
+
+try:
+    from mcp.server.fastmcp import Context
+except ImportError as exc:  # pragma: no cover - exercised without the optional extra
+    raise ImportError(
+        "Actenon's MCP adapter requires the 'mcp' extra: "
+        "python -m pip install 'actenon-kernel[mcp]'"
+    ) from exc
+
+
+ACTENON_MCP_META_KEY = "actenon"
+ActionBuilder = Callable[[Mapping[str, Any]], ActionIntent | dict[str, Any]]
+EvidenceBuilder = Callable[
+    [Mapping[str, Any]],
+    Mapping[str, Any] | PreflightEvidence | None,
+]
+
+
+def mcp_authorization_meta(
+    proof: Mapping[str, Any] | PCCB | None,
+    *,
+    evidence: Mapping[str, Any] | PreflightEvidence | None = None,
+) -> dict[str, Any]:
+    if isinstance(proof, PCCB):
+        proof = proof.to_dict()
+    if isinstance(evidence, PreflightEvidence):
+        evidence = evidence.to_dict()
+    return {
+        ACTENON_MCP_META_KEY: {
+            "proof": proof,
+            "evidence": evidence,
+        }
+    }
+
+
+def _context_meta(context: Context[Any, Any, Any]) -> Mapping[str, Any]:
+    request_context = context.request_context
+    meta = getattr(request_context, "meta", None)
+    return meta if isinstance(meta, Mapping) else {}
+
+
+def protected_mcp_tool(
+    gate: ActenonGate,
+    *,
+    action_builder: ActionBuilder,
+    audience: str | None = None,
+    evidence_builder: EvidenceBuilder | None = None,
+    context_parameter: str = "ctx",
+) -> Callable[[Callable[..., Any]], Callable[..., dict[str, Any]]]:
+    """Decorate an arbitrary sync FastMCP tool using injected request Context."""
+
+    def decorator(domain_function: Callable[..., Any]) -> Callable[..., dict[str, Any]]:
+        if inspect.iscoroutinefunction(domain_function):
+            raise TypeError(
+                "protected_mcp_tool currently requires a synchronous tool function"
+            )
+        signature = inspect.signature(domain_function)
+        context = signature.parameters.get(context_parameter)
+        if context is None:
+            raise TypeError(
+                f"protected MCP tool must declare an injected '{context_parameter}: Context' parameter"
+            )
+
+        @wraps(domain_function)
+        def protected_call(*args: Any, **kwargs: Any) -> dict[str, Any]:
+            bound = signature.bind(*args, **kwargs)
+            bound.apply_defaults()
+            mcp_context = bound.arguments.get(context_parameter)
+            if not isinstance(mcp_context, Context):
+                raise TypeError(
+                    f"'{context_parameter}' must be an mcp.server.fastmcp.Context"
+                )
+            domain_args = {
+                key: value
+                for key, value in bound.arguments.items()
+                if key != context_parameter
+            }
+            authorization = authorization_from_mapping(
+                _context_meta(mcp_context).get(ACTENON_MCP_META_KEY)
+            )
+            evidence = (
+                evidence_builder(domain_args)
+                if evidence_builder is not None
+                else authorization.evidence
+            )
+            action = action_builder(domain_args)
+            outcome = gate.protect(
+                action,
+                authorization.proof,
+                lambda: domain_function(*args, **kwargs),
+                audience=audience,
+                evidence=evidence,
+            )
+            return outcome.to_dict()
+
+        return protected_call
+
+    return decorator
+
+
+__all__ = [
+    "ACTENON_MCP_META_KEY",
+    "mcp_authorization_meta",
+    "protected_mcp_tool",
+]