langgraph-secure-agents 0.1.0__py3-none-any.whl

langgraph_secure_agents/__init__.py

@@ -0,0 +1,20 @@
+"""Reusable security primitives for LangGraph agents."""
+
+from .guard import AuthorizationDenied, protect_callable
+from .models import AccessRequest, Decision, DecisionReason, Effect, PolicyRule, Principal
+from .policy import PolicyEngine
+
+__version__ = "0.1.0a0"
+
+__all__ = [
+    "AccessRequest",
+    "AuthorizationDenied",
+    "Decision",
+    "DecisionReason",
+    "Effect",
+    "PolicyEngine",
+    "PolicyRule",
+    "Principal",
+    "__version__",
+    "protect_callable",
+]

langgraph_secure_agents/_resolver_safety.py

@@ -0,0 +1,45 @@
+"""Internal helpers for fail-closed, side-effect-free policy resolvers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from copy import deepcopy
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def call_resolver_without_mutation(
+    resolver: Callable[P, R],
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> R:
+    """Call a trusted resolver on detached inputs and reject input mutation.
+
+    Resource/action resolvers participate in the authorization decision. Letting
+    them mutate a request object can cause the checked resource to differ from
+    the resource later consumed by the protected operation. Inputs are deep-copied
+    and snapshotted; if copying or comparison cannot be performed safely, the
+    caller fails closed before the protected operation executes.
+    """
+
+    try:
+        resolver_args = deepcopy(args)
+        resolver_kwargs = deepcopy(kwargs)
+        args_before = deepcopy(resolver_args)
+        kwargs_before = deepcopy(resolver_kwargs)
+    except Exception as exc:
+        raise ValueError("resolver inputs must be safely copyable") from exc
+
+    result = resolver(*resolver_args, **resolver_kwargs)
+
+    try:
+        mutated = resolver_args != args_before or resolver_kwargs != kwargs_before
+    except Exception as exc:
+        raise ValueError("resolver input mutation could not be checked safely") from exc
+
+    if mutated:
+        raise ValueError("authorization resolvers must not mutate their inputs")
+
+    return result

langgraph_secure_agents/guard.py

@@ -0,0 +1,130 @@
+"""Execution guards for ordinary Python callables."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from inspect import iscoroutinefunction
+from typing import Any, ParamSpec, TypeVar, cast, overload
+
+from ._resolver_safety import call_resolver_without_mutation
+from .models import AccessRequest, Decision, Principal
+from .policy import PolicyEngine
+
+P = ParamSpec("P")
+R = TypeVar("R")
+AuditCallback = Callable[[AccessRequest, Decision], None]
+ResourceResolver = Callable[P, str]
+
+
+class AuthorizationDenied(PermissionError):
+    """Raised when a protected callable is invoked without authorization."""
+
+    def __init__(self, request: AccessRequest, decision: Decision) -> None:
+        self.request = request
+        self.decision = decision
+        super().__init__(f"Access denied for action {request.action!r} ({decision.reason}).")
+
+
+@overload
+def protect_callable(
+    function: Callable[P, Awaitable[R]],
+    *,
+    policy: PolicyEngine,
+    principal_resolver: Callable[[], Principal],
+    action: str = "execute",
+    resource_resolver: ResourceResolver[P] | None = None,
+    audit_callback: AuditCallback | None = None,
+) -> Callable[P, Awaitable[R]]: ...
+
+
+@overload
+def protect_callable(
+    function: Callable[P, R],
+    *,
+    policy: PolicyEngine,
+    principal_resolver: Callable[[], Principal],
+    action: str = "execute",
+    resource_resolver: ResourceResolver[P] | None = None,
+    audit_callback: AuditCallback | None = None,
+) -> Callable[P, R]: ...
+
+
+def protect_callable(
+    function: Callable[P, Any],
+    *,
+    policy: PolicyEngine,
+    principal_resolver: Callable[[], Principal],
+    action: str = "execute",
+    resource_resolver: ResourceResolver[P] | None = None,
+    audit_callback: AuditCallback | None = None,
+) -> Callable[P, Any]:
+    """Return a callable that authorizes immediately before protected execution.
+
+    Coroutine functions are authorized when their returned coroutine is awaited,
+    not when the coroutine object is created. This ensures the trusted principal
+    and policy are checked at the point execution begins.
+
+    The principal resolver must obtain identity from trusted application context,
+    not from arguments controlled by an LLM. The resource resolver must identify
+    the same resource the wrapped function will actually access. The resolver
+    receives detached argument copies; mutating them is rejected. Resolvers must
+    otherwise be trusted, side-effect-free application code. If auditing is
+    configured and the callback fails, execution fails closed.
+    """
+
+    if not callable(function):
+        raise TypeError("function must be callable")
+    if not isinstance(policy, PolicyEngine):
+        raise TypeError("policy must be a PolicyEngine instance")
+    if not callable(principal_resolver):
+        raise TypeError("principal_resolver must be callable")
+    if resource_resolver is not None and not callable(resource_resolver):
+        raise TypeError("resource_resolver must be callable")
+    if audit_callback is not None and not callable(audit_callback):
+        raise TypeError("audit_callback must be callable")
+    if not isinstance(action, str) or not action.strip() or action.strip() == "*":
+        raise ValueError("action must be a non-empty concrete action")
+
+    normalized_action = action.strip()
+    if resource_resolver is None:
+        resource_name = getattr(function, "__name__", type(function).__name__)
+
+    def authorize(*args: P.args, **kwargs: P.kwargs) -> None:
+        principal = principal_resolver()
+        if not isinstance(principal, Principal):
+            raise TypeError("principal_resolver must return a Principal instance")
+
+        if resource_resolver is None:
+            resource = resource_name
+        else:
+            resource = call_resolver_without_mutation(resource_resolver, *args, **kwargs)
+
+        request = AccessRequest(
+            principal=principal,
+            action=normalized_action,
+            resource=resource,
+        )
+        decision = policy.evaluate(request)
+
+        if audit_callback is not None:
+            audit_callback(request, decision)
+
+        if not decision.allowed:
+            raise AuthorizationDenied(request, decision)
+
+    if iscoroutinefunction(function):
+
+        @wraps(function)
+        async def guarded_async(*args: P.args, **kwargs: P.kwargs) -> Any:
+            authorize(*args, **kwargs)
+            return await cast(Awaitable[Any], function(*args, **kwargs))
+
+        return guarded_async
+
+    @wraps(function)
+    def guarded(*args: P.args, **kwargs: P.kwargs) -> Any:
+        authorize(*args, **kwargs)
+        return function(*args, **kwargs)
+
+    return guarded

langgraph_secure_agents/middleware.py

@@ -0,0 +1,344 @@
+"""Optional middleware that enforces policies before agent tools execute."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware, wrap_tool_call
+from langchain_core.messages import ToolMessage
+from langgraph.types import interrupt
+
+from ._resolver_safety import call_resolver_without_mutation
+from .models import AccessRequest, Decision, DecisionReason, PolicyRule, Principal
+from .policy import PolicyEngine
+
+PrincipalResolver = Callable[[object], Principal]
+ActionResolver = Callable[[str, Mapping[str, Any]], str]
+ResourceResolver = Callable[[str, Mapping[str, Any]], str]
+AuditCallback = Callable[[AccessRequest, Decision], None]
+ApprovalValidator = Callable[[Mapping[str, Any], AccessRequest, str], bool]
+
+
+def _canonical_json_value(value: Any) -> Any:
+    """Normalize supported values to unambiguous, standards-compliant JSON data."""
+
+    if value is None or type(value) in (str, bool, int):
+        return value
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise ValueError("approval fingerprints cannot contain non-finite numbers")
+        return value
+    if isinstance(value, Mapping):
+        normalized: dict[str, Any] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ValueError("approval fingerprints require string keys in JSON objects")
+            normalized[key] = _canonical_json_value(item)
+        return normalized
+    if isinstance(value, (list, tuple)):
+        return [_canonical_json_value(item) for item in value]
+    raise ValueError("approval fingerprints can only contain JSON-compatible values")
+
+
+def _approval_execution_scope(runtime: Any) -> dict[str, str]:
+    """Get stable checkpoint scope for binding a human approval to one execution."""
+
+    execution_info = getattr(runtime, "execution_info", None)
+    thread_id = getattr(execution_info, "thread_id", None)
+    checkpoint_id = getattr(execution_info, "checkpoint_id", None)
+    checkpoint_ns = getattr(execution_info, "checkpoint_ns", None)
+    task_id = getattr(execution_info, "task_id", None)
+
+    if (
+        not isinstance(thread_id, str)
+        or not thread_id
+        or not isinstance(checkpoint_id, str)
+        or not checkpoint_id
+        or not isinstance(checkpoint_ns, str)
+        or not isinstance(task_id, str)
+        or not task_id
+    ):
+        raise RuntimeError(
+            "approval-required tool calls need LangGraph 1.2+ execution metadata "
+            "and an active checkpointer"
+        )
+
+    return {
+        "thread_id": thread_id,
+        "checkpoint_id": checkpoint_id,
+        "checkpoint_ns": checkpoint_ns,
+        "task_id": task_id,
+    }
+
+
+def _approval_fingerprint(
+    *,
+    tool_name: str,
+    tool_args: Mapping[str, Any],
+    tool_call_id: str,
+    access_request: AccessRequest,
+    matched_rule_ids: tuple[str, ...],
+    matched_policy_rules: tuple[PolicyRule, ...],
+    execution_scope: Mapping[str, str],
+) -> str:
+    """Bind approval to one execution, request data, and matched policy definitions."""
+
+    payload = {
+        "execution_scope": dict(execution_scope),
+        "tool_name": tool_name,
+        "tool_args": dict(tool_args),
+        "tool_call_id": tool_call_id,
+        "principal_id": access_request.principal.principal_id,
+        "roles": sorted(access_request.principal.roles),
+        "action": access_request.action,
+        "resource": access_request.resource,
+        "matched_rule_ids": list(matched_rule_ids),
+        "matched_policy_rules": [
+            {
+                "rule_id": rule.rule_id,
+                "effect": rule.effect.value,
+                "actions": sorted(rule.actions),
+                "resources": sorted(rule.resources),
+                "principal_ids": sorted(rule.principal_ids),
+                "roles": sorted(rule.roles),
+            }
+            for rule in matched_policy_rules
+        ],
+    }
+    try:
+        canonical_payload = _canonical_json_value(payload)
+        serialized = json.dumps(
+            canonical_payload,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+            allow_nan=False,
+        )
+    except (TypeError, ValueError, RecursionError) as exc:
+        raise ValueError("approval-required tool arguments must be JSON-serializable") from exc
+    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+
+def create_authorization_middleware(
+    policy: PolicyEngine,
+    principal_resolver: PrincipalResolver,
+    *,
+    action_resolver: ActionResolver | None = None,
+    resource_resolver: ResourceResolver | None = None,
+    audit_callback: AuditCallback | None = None,
+    approval_validator: ApprovalValidator | None = None,
+) -> Any:
+    """Create middleware that authorizes every tool call before execution.
+
+    The principal resolver receives the agent runtime's context. It must derive
+    identity from trusted application data, never from tool arguments or LLM
+    output. By default, the requested action is execute and the resource is
+    the tool name. Custom resolvers can map tool calls to domain actions and
+    resources. A denied call returns an error ToolMessage without invoking the
+    tool handler.
+
+    For REQUIRE_APPROVAL decisions, LangGraph interrupt() pauses execution before
+    delegation. Resume the same checkpoint/thread with a trusted approval result
+    containing both a boolean 'approved' field and the exact request_fingerprint
+    shown in the interrupt payload. The host application must authenticate the
+    reviewer and authorize access to the resume operation; the payload alone is
+    not proof that an authorized human approved the action. The fingerprint is
+    deterministic, not a one-time token. Configure approval_validator when the
+    host needs reviewer authentication/authorization and durable one-time
+    approval consumption. The callback receives the approval mapping, access
+    request, and fingerprint; it must authenticate/authorize the reviewer and
+    atomically consume the approval, returning literal True only for the first
+    valid use. Any other return value fails closed. If the callback raises, the
+    exception propagates and the tool handler is not invoked. Its result must
+    not be based on untrusted model output. Without this callback, the host
+    remains responsible for these controls externally.
+
+    Custom action/resource resolvers receive detached argument copies. Mutating
+    those copies raises an error before the protected tool runs. Resolvers must
+    otherwise be trusted, side-effect-free application code.
+
+    If configured auditing raises, the tool handler is not invoked (fail closed).
+    Approval outcomes are audited after the interrupt resumes.
+    """
+
+    if not isinstance(policy, PolicyEngine):
+        raise TypeError("policy must be a PolicyEngine instance")
+    if not callable(principal_resolver):
+        raise TypeError("principal_resolver must be callable")
+    if action_resolver is not None and not callable(action_resolver):
+        raise TypeError("action_resolver must be callable")
+    if resource_resolver is not None and not callable(resource_resolver):
+        raise TypeError("resource_resolver must be callable")
+    if audit_callback is not None and not callable(audit_callback):
+        raise TypeError("audit_callback must be callable")
+    if approval_validator is not None and not callable(approval_validator):
+        raise TypeError("approval_validator must be callable")
+
+    @wrap_tool_call(name="secure_agent_authorization")
+    def enforce_authorization(request: Any, handler: Callable[[Any], Any]) -> Any:
+        tool_call = getattr(request, "tool_call", None)
+        if not isinstance(tool_call, Mapping):
+            raise TypeError("middleware request must contain a tool_call mapping")
+
+        tool_name = tool_call.get("name")
+        tool_args = tool_call.get("args", {})
+        tool_call_id = tool_call.get("id")
+
+        if not isinstance(tool_name, str) or not tool_name.strip():
+            raise ValueError("tool call must include a non-empty name")
+        if not isinstance(tool_args, Mapping):
+            raise TypeError("tool call args must be a mapping")
+
+        runtime = getattr(request, "runtime", None)
+        runtime_context = getattr(runtime, "context", None)
+        principal = principal_resolver(runtime_context)
+        if not isinstance(principal, Principal):
+            raise TypeError("principal_resolver must return a Principal instance")
+
+        action = (
+            "execute"
+            if action_resolver is None
+            else call_resolver_without_mutation(action_resolver, tool_name, tool_args)
+        )
+        resource = (
+            tool_name
+            if resource_resolver is None
+            else call_resolver_without_mutation(resource_resolver, tool_name, tool_args)
+        )
+        access_request = AccessRequest(
+            principal=principal,
+            action=action,
+            resource=resource,
+        )
+        decision = policy.evaluate(access_request)
+
+        if decision.requires_approval:
+            if not isinstance(tool_call_id, str) or not tool_call_id:
+                raise ValueError("approval-required tool calls must include a tool-call id")
+
+            matched_policy_rules = tuple(
+                rule for rule in policy.rules if rule.rule_id in decision.matched_rule_ids
+            )
+            if tuple(rule.rule_id for rule in matched_policy_rules) != decision.matched_rule_ids:
+                raise RuntimeError("policy decision refers to an unknown policy rule")
+
+            execution_scope = _approval_execution_scope(runtime)
+            fingerprint = _approval_fingerprint(
+                tool_name=tool_name,
+                tool_args=tool_args,
+                tool_call_id=tool_call_id,
+                access_request=access_request,
+                matched_rule_ids=decision.matched_rule_ids,
+                matched_policy_rules=matched_policy_rules,
+                execution_scope=execution_scope,
+            )
+            approval = interrupt(
+                {
+                    "type": "authorization_approval",
+                    "message": "A human decision is required before this tool can execute.",
+                    "tool_name": tool_name,
+                    "tool_call_id": tool_call_id,
+                    "principal_id": principal.principal_id,
+                    "roles": sorted(principal.roles),
+                    "action": access_request.action,
+                    "resource": access_request.resource,
+                    "policy_rule_ids": list(decision.matched_rule_ids),
+                    "execution_scope": execution_scope,
+                    "request_fingerprint": fingerprint,
+                }
+            )
+
+            approval_valid = (
+                isinstance(approval, Mapping)
+                and type(approval.get("approved")) is bool
+                and approval.get("request_fingerprint") == fingerprint
+            )
+            if approval_valid and approval_validator is not None:
+                validation_result = approval_validator(
+                    approval,
+                    access_request,
+                    fingerprint,
+                )
+                approval_valid = type(validation_result) is bool and validation_result
+
+            if not approval_valid:
+                outcome = Decision(
+                    allowed=False,
+                    reason=DecisionReason.APPROVAL_INVALID,
+                    matched_rule_ids=decision.matched_rule_ids,
+                )
+                if audit_callback is not None:
+                    audit_callback(access_request, outcome)
+                return ToolMessage(
+                    content="Approval response invalid; tool was not executed.",
+                    tool_call_id=tool_call_id,
+                    status="error",
+                )
+
+            if not approval["approved"]:
+                outcome = Decision(
+                    allowed=False,
+                    reason=DecisionReason.APPROVAL_DENIED,
+                    matched_rule_ids=decision.matched_rule_ids,
+                )
+                if audit_callback is not None:
+                    audit_callback(access_request, outcome)
+                return ToolMessage(
+                    content="Human approval denied.",
+                    tool_call_id=tool_call_id,
+                    status="error",
+                )
+
+            outcome = Decision(
+                allowed=True,
+                reason=DecisionReason.HUMAN_APPROVED,
+                matched_rule_ids=decision.matched_rule_ids,
+            )
+            if audit_callback is not None:
+                audit_callback(access_request, outcome)
+            return handler(request)
+
+        if audit_callback is not None:
+            audit_callback(access_request, decision)
+
+        if not decision.allowed:
+            if not isinstance(tool_call_id, str) or not tool_call_id:
+                raise ValueError("denied tool calls must include a tool-call id")
+            return ToolMessage(
+                content="Authorization denied.",
+                tool_call_id=tool_call_id,
+                status="error",
+            )
+
+        return handler(request)
+
+    sync_middleware = enforce_authorization
+    sentinel = ToolMessage(
+        content="authorization sentinel",
+        tool_call_id="__secure_agents_sentinel__",
+    )
+
+    async def enforce_authorization_async(request: Any, handler: Any) -> Any:
+        # Reuse the exact synchronous authorization path, substituting a sentinel
+        # handler so the real async tool is only awaited after authorization passes.
+        result = sync_middleware.wrap_tool_call(request, lambda _: sentinel)
+        if result is sentinel:
+            return await handler(request)
+        return result
+
+    async_middleware = wrap_tool_call(name="secure_agent_authorization_async")(
+        enforce_authorization_async
+    )
+
+    class _CombinedAuthorizationMiddleware(AgentMiddleware[Any, Any, Any]):
+        def wrap_tool_call(self, request: Any, handler: Any) -> Any:
+            return sync_middleware.wrap_tool_call(request, handler)
+
+        async def awrap_tool_call(self, request: Any, handler: Any) -> Any:
+            return await async_middleware.awrap_tool_call(request, handler)
+
+    return _CombinedAuthorizationMiddleware()

langgraph_secure_agents/models.py

@@ -0,0 +1,205 @@
+"""Immutable domain models for authorization decisions."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+def _normalized_text(value: str, field_name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field_name} must be a non-empty string")
+    return value.strip()
+
+
+def _normalized_set(
+    values: Iterable[str],
+    field_name: str,
+    *,
+    allow_empty: bool = False,
+) -> frozenset[str]:
+    if isinstance(values, (str, bytes)):
+        raise ValueError(f"{field_name} must be a collection of strings, not a string")
+    normalized: set[str] = set()
+    try:
+        for value in values:
+            normalized.add(_normalized_text(value, field_name))
+    except TypeError as exc:
+        raise ValueError(f"{field_name} must be an iterable of strings") from exc
+    if not normalized and not allow_empty:
+        raise ValueError(f"{field_name} must contain at least one value")
+    return frozenset(normalized)
+
+
+class Effect(StrEnum):
+    """The effect a matching policy rule has on an access request."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    REQUIRE_APPROVAL = "require_approval"
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """An authenticated identity supplied by trusted application code.
+
+    This object does not authenticate users. Applications must construct it
+    from a trusted identity source, never directly from untrusted LLM output.
+    """
+
+    principal_id: str
+    roles: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        normalized_id = _normalized_text(self.principal_id, "principal_id")
+        object.__setattr__(self, "principal_id", normalized_id)
+        object.__setattr__(
+            self,
+            "roles",
+            _normalized_set(self.roles, "roles", allow_empty=True),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AccessRequest:
+    """A concrete request to perform an action on a resource."""
+
+    principal: Principal
+    action: str
+    resource: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.principal, Principal):
+            raise ValueError("principal must be a Principal instance")
+        action = _normalized_text(self.action, "action")
+        resource = _normalized_text(self.resource, "resource")
+        if action == "*" or resource == "*":
+            raise ValueError("access requests must name a concrete action and resource")
+        object.__setattr__(self, "action", action)
+        object.__setattr__(self, "resource", resource)
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyRule:
+    """A policy rule with explicit subject, action, resource, and effect.
+
+    Selectors are exact matches unless the whole action/resource selector is
+    the wildcard. A principal wildcard explicitly targets every principal.
+    When both principal IDs and roles are supplied, both constraints must match.
+    """
+
+    rule_id: str
+    effect: Effect
+    actions: frozenset[str]
+    resources: frozenset[str]
+    principal_ids: frozenset[str] = frozenset()
+    roles: frozenset[str] = frozenset()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "rule_id", _normalized_text(self.rule_id, "rule_id"))
+        try:
+            effect = Effect(self.effect)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("effect must be ALLOW, DENY, or REQUIRE_APPROVAL") from exc
+        object.__setattr__(self, "effect", effect)
+
+        actions = _normalized_set(self.actions, "actions")
+        resources = _normalized_set(self.resources, "resources")
+        principal_ids = _normalized_set(self.principal_ids, "principal_ids", allow_empty=True)
+        roles = _normalized_set(self.roles, "roles", allow_empty=True)
+
+        for field_name, selectors in (("actions", actions), ("resources", resources)):
+            if "*" in selectors and selectors != frozenset({"*"}):
+                raise ValueError(f"{field_name} cannot combine '*' with specific selectors")
+            if any("*" in selector and selector != "*" for selector in selectors):
+                raise ValueError(f"{field_name} only supports the standalone '*' wildcard")
+
+        if not principal_ids and not roles:
+            raise ValueError("a policy rule must specify principal_ids or roles")
+        if "*" in principal_ids and principal_ids != frozenset({"*"}):
+            raise ValueError("principal_ids cannot combine '*' with specific identities")
+        if "*" in principal_ids and roles:
+            raise ValueError("principal_ids={'*'} cannot be combined with role constraints")
+
+        object.__setattr__(self, "actions", actions)
+        object.__setattr__(self, "resources", resources)
+        object.__setattr__(self, "principal_ids", principal_ids)
+        object.__setattr__(self, "roles", roles)
+
+
+class DecisionReason(StrEnum):
+    """Stable machine-readable reasons emitted by the policy layer."""
+
+    EXPLICIT_ALLOW = "explicit_allow"
+    EXPLICIT_DENY = "explicit_deny"
+    DEFAULT_DENY = "default_deny"
+    APPROVAL_REQUIRED = "approval_required"
+    APPROVAL_INVALID = "approval_invalid"
+    APPROVAL_DENIED = "approval_denied"
+    HUMAN_APPROVED = "human_approved"
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """A deterministic authorization outcome and its explainable basis."""
+
+    allowed: bool
+    reason: DecisionReason
+    matched_rule_ids: tuple[str, ...] = ()
+    requires_approval: bool = False
+
+    def __post_init__(self) -> None:
+        if type(self.allowed) is not bool:
+            raise ValueError("allowed must be a boolean")
+
+        normalized_reason = _normalized_text(self.reason, "reason")
+        try:
+            reason = DecisionReason(normalized_reason)
+        except ValueError as exc:
+            raise ValueError("reason must be a known DecisionReason") from exc
+
+        if type(self.requires_approval) is not bool:
+            raise ValueError("requires_approval must be a boolean")
+
+        if isinstance(self.matched_rule_ids, (str, bytes)):
+            raise ValueError("matched_rule_ids must be a collection of rule IDs")
+        try:
+            rule_ids = tuple(
+                _normalized_text(rule_id, "matched_rule_ids") for rule_id in self.matched_rule_ids
+            )
+        except TypeError as exc:
+            raise ValueError("matched_rule_ids must be an iterable of strings") from exc
+
+        if len(set(rule_ids)) != len(rule_ids):
+            raise ValueError("matched_rule_ids cannot contain duplicates")
+
+        if self.requires_approval != (reason is DecisionReason.APPROVAL_REQUIRED):
+            raise ValueError(
+                "requires_approval must be true exactly when reason is 'approval_required'"
+            )
+
+        allowed_reasons = {
+            DecisionReason.EXPLICIT_ALLOW,
+            DecisionReason.HUMAN_APPROVED,
+        }
+        if self.allowed and reason not in allowed_reasons:
+            raise ValueError(f"reason {reason.value!r} cannot describe an allowed decision")
+        if not self.allowed and reason in allowed_reasons:
+            raise ValueError(f"reason {reason.value!r} cannot describe a denied decision")
+
+        rule_required_reasons = {
+            DecisionReason.EXPLICIT_ALLOW,
+            DecisionReason.EXPLICIT_DENY,
+            DecisionReason.APPROVAL_REQUIRED,
+            DecisionReason.APPROVAL_INVALID,
+            DecisionReason.APPROVAL_DENIED,
+            DecisionReason.HUMAN_APPROVED,
+        }
+        if reason in rule_required_reasons and not rule_ids:
+            raise ValueError(f"reason {reason.value!r} requires matched_rule_ids")
+        if reason is DecisionReason.DEFAULT_DENY and rule_ids:
+            raise ValueError("default_deny cannot have matched_rule_ids")
+
+        object.__setattr__(self, "reason", reason)
+        object.__setattr__(self, "matched_rule_ids", rule_ids)

langgraph_secure_agents/policy.py

@@ -0,0 +1,99 @@
+"""Deterministic policy evaluation with deny-overrides semantics."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .models import AccessRequest, Decision, DecisionReason, Effect, PolicyRule
+
+
+class PolicyEngine:
+    """Evaluate authorization requests without involving an LLM.
+
+    A matching DENY rule always overrides every other effect. Otherwise a
+    matching REQUIRE_APPROVAL rule takes precedence over ALLOW and returns a
+    non-allowing decision that an approval-aware integration may handle.
+    Requests not covered by an allow or approval rule are denied by default.
+
+    Rules are immutable after construction. Create a new engine to change policy.
+    """
+
+    __slots__ = ("_rules",)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        if name == "_rules" and hasattr(self, "_rules"):
+            raise AttributeError("PolicyEngine rules are immutable after construction")
+        object.__setattr__(self, name, value)
+
+    def __init__(self, rules: Iterable[PolicyRule] = ()) -> None:
+        materialized_rules = tuple(rules)
+        seen_ids: set[str] = set()
+        for rule in materialized_rules:
+            if not isinstance(rule, PolicyRule):
+                raise TypeError("rules must contain only PolicyRule instances")
+            if rule.rule_id in seen_ids:
+                raise ValueError(f"duplicate policy rule id: {rule.rule_id}")
+            seen_ids.add(rule.rule_id)
+        self._rules = materialized_rules
+
+    @property
+    def rules(self) -> tuple[PolicyRule, ...]:
+        """Return the policy rules as an immutable tuple."""
+
+        return self._rules
+
+    def evaluate(self, request: AccessRequest) -> Decision:
+        """Return the authorization decision for a concrete access request."""
+
+        if not isinstance(request, AccessRequest):
+            raise TypeError("request must be an AccessRequest instance")
+
+        matching_rules = tuple(rule for rule in self._rules if self._matches(rule, request))
+        denying_rule_ids = tuple(
+            rule.rule_id for rule in matching_rules if rule.effect is Effect.DENY
+        )
+        if denying_rule_ids:
+            return Decision(
+                allowed=False,
+                reason=DecisionReason.EXPLICIT_DENY,
+                matched_rule_ids=denying_rule_ids,
+            )
+
+        approval_rule_ids = tuple(
+            rule.rule_id for rule in matching_rules if rule.effect is Effect.REQUIRE_APPROVAL
+        )
+        if approval_rule_ids:
+            return Decision(
+                allowed=False,
+                reason=DecisionReason.APPROVAL_REQUIRED,
+                matched_rule_ids=approval_rule_ids,
+                requires_approval=True,
+            )
+
+        allowing_rule_ids = tuple(
+            rule.rule_id for rule in matching_rules if rule.effect is Effect.ALLOW
+        )
+        if allowing_rule_ids:
+            return Decision(
+                allowed=True,
+                reason=DecisionReason.EXPLICIT_ALLOW,
+                matched_rule_ids=allowing_rule_ids,
+            )
+
+        return Decision(allowed=False, reason=DecisionReason.DEFAULT_DENY)
+
+    @staticmethod
+    def _matches(rule: PolicyRule, request: AccessRequest) -> bool:
+        if rule.actions != frozenset({"*"}) and request.action not in rule.actions:
+            return False
+        if rule.resources != frozenset({"*"}) and request.resource not in rule.resources:
+            return False
+
+        if rule.principal_ids and rule.principal_ids != frozenset({"*"}):
+            if request.principal.principal_id not in rule.principal_ids:
+                return False
+
+        if rule.roles and not request.principal.roles.intersection(rule.roles):
+            return False
+
+        return True

langgraph_secure_agents-0.1.0.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: langgraph-secure-agents
+Version: 0.1.0
+Summary: Deterministic access control for LangGraph agents.
+Project-URL: Homepage, https://github.com/peymanpro/LangGraph-SecureAgents
+Project-URL: Repository, https://github.com/peymanpro/LangGraph-SecureAgents
+Project-URL: Issues, https://github.com/peymanpro/LangGraph-SecureAgents/issues
+Project-URL: Security, https://github.com/peymanpro/LangGraph-SecureAgents/blob/main/SECURITY.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: access-control,ai-agents,authorization,langgraph,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: langchain<2.0,>=1.0; extra == 'dev'
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: langchain-agents
+Requires-Dist: langchain-core<2.0,>=1.0; extra == 'langchain-agents'
+Requires-Dist: langchain<2.0,>=1.0; extra == 'langchain-agents'
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'langchain-agents'
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# LangGraph-SecureAgents
+
+**Deterministic access control for LangGraph-powered agents.**
+
+LangGraph-SecureAgents is an experimental Python library for enforcing authorization at agent tool-execution boundaries. Agent orchestration may be handled by LangGraph; authorization decisions are made by trusted application code, never by an LLM.
+
+> **Status:** early development. The policy engine, guarded-callable primitive, and optional agent middleware are implemented, but the API is not stable and has not received an independent security audit. Do not use this project to protect production data yet.
+
+## Security principles
+
+Read the [threat model](docs/threat-model.md) for trust boundaries and deployment guidance, and [SECURITY.md](SECURITY.md) for vulnerability reporting and security limitations.
+
+1. **Default deny:** no matching allow policy means access is denied.
+2. **Deny overrides:** an explicit deny rule wins over any matching allow rule.
+3. **Deterministic authorization:** model output cannot grant permissions.
+4. **Enforce at execution:** evaluate policy immediately before a protected operation.
+5. **Trusted identity:** the application must resolve principal identity and roles from authenticated context, never from LLM-controlled tool arguments.
+6. **Fail closed:** resolver or configured audit failures prevent protected execution.
+7. **Least privilege:** rules specify a principal or role, action, and resource.
+
+## Installation
+
+Requires Python 3.11 or newer.
+
+### Install the published package
+
+After the first PyPI release is available, install the alpha package with its optional agent middleware:
+
+```bash
+python -m pip install --pre "langgraph-secure-agents[langchain-agents]"
+```
+
+For the core policy engine and callable guard without LangGraph middleware:
+
+```bash
+python -m pip install --pre langgraph-secure-agents
+```
+
+The `--pre` flag is needed while the latest published version is an alpha pre-release. Until the package is available on PyPI, use the source-install instructions below.
+
+### Install from a source checkout
+
+Clone this repository, then install the core package and development tools:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Install the optional middleware dependencies from the same checkout:
+
+```bash
+python -m pip install -e ".[langchain-agents]"
+```
+
+The core policy engine and callable guard do not require LangGraph or an LLM provider.
+
+## Run the model-free LangGraph example
+
+The example uses fake payroll records and a trusted runtime context. It needs no model API key:
+
+```bash
+python examples/policy_guarded_workflow.py
+```
+
+It demonstrates an allowed HR request, a denied request for an unapproved resource, and a denied request from a user without the required role.
+
+## Quick start: deterministic policy engine
+
+```python
+from langgraph_secure_agents import (
+    AccessRequest,
+    DecisionReason,
+    Effect,
+    PolicyEngine,
+    PolicyRule,
+    Principal,
+)
+
+policy = PolicyEngine(
+    [
+        PolicyRule(
+            rule_id="analysts-read-reports",
+            effect=Effect.ALLOW,
+            principal_ids=frozenset(),
+            roles=frozenset({"analyst"}),
+            actions=frozenset({"read"}),
+            resources=frozenset({"reports"}),
+        )
+    ]
+)
+
+decision = policy.evaluate(
+    AccessRequest(
+        principal=Principal("user-123", roles=frozenset({"analyst"})),
+        action="read",
+        resource="reports",
+    )
+)
+
+assert decision.allowed
+assert decision.reason is DecisionReason.EXPLICIT_ALLOW
+```
+
+### Decision outcomes and policy updates
+
+`Decision.reason` is a public `DecisionReason` enum with stable machine-readable values: `explicit_allow`, `explicit_deny`, `default_deny`, `approval_required`, `approval_invalid`, `approval_denied`, and `human_approved`. Use the enum constants in application code rather than comparing free-form strings. `matched_rule_ids` identifies the policy rules responsible for a rule-based outcome; a default-deny decision has no matched rule IDs. `requires_approval` is true only for `approval_required`.
+
+A `PolicyEngine`'s rules cannot be replaced after construction. To deploy a policy change, construct and validate a new engine, then switch the application to it using the application's own configuration/reload mechanism. Do not mutate private state on a live engine. This matters for approval pauses: the request fingerprint binds approval to the matched rule definitions, so a resumed decision must still refer to the policy that produced the interrupt.
+
+## Protect a Python callable
+
+```python
+from langgraph_secure_agents import PolicyEngine, Principal, protect_callable
+
+# This resolver must read a trusted, request-scoped identity source.
+current_principal = lambda: Principal("user-123", roles=frozenset({"analyst"}))
+
+protected_lookup = protect_callable(
+    lookup_report,
+    policy=policy,
+    principal_resolver=current_principal,
+    action="read",
+    resource_resolver=lambda report_id: f"report:{report_id}",
+)
+```
+
+The resource resolver must describe the same resource the wrapped function actually accesses. Resolver callbacks receive detached copies of arguments, and attempts to mutate those copies fail closed before execution. Resolvers must otherwise be trusted, side-effect-free application code. For multi-user applications, the principal resolver must read request-scoped trusted context; do not capture one user's identity in a process-wide shared tool.
+
+## Optional agent middleware
+
+The optional module `langgraph_secure_agents.middleware` provides `create_authorization_middleware` for LangChain agents built on LangGraph. It intercepts tool calls before execution. By default, the policy action is `execute` and the resource is the tool name. Custom resolvers can map tool calls to domain-level actions and resources.
+
+The middleware receives runtime context from the agent invocation. The application must configure a principal resolver that validates this context and creates a `Principal` from trusted identity data. Custom action/resource resolvers receive detached copies of tool arguments; attempts to mutate these copies fail closed. Denied calls return an error tool message and do not invoke the tool handler.
+
+## Human approval for sensitive actions
+
+A policy can explicitly require approval instead of granting access immediately:
+
+```python
+approval_policy = PolicyEngine(
+    [
+        PolicyRule(
+            rule_id="approval-required-payroll-read",
+            effect=Effect.REQUIRE_APPROVAL,
+            actions=frozenset({"read"}),
+            resources=frozenset({"payroll:employee-7"}),
+            roles=frozenset({"hr"}),
+        )
+    ]
+)
+```
+
+When this policy is used with the optional agent middleware, LangGraph pauses at an interrupt before the tool handler executes. The paused payload describes the principal, action, resource, policy rule, tool, and a request fingerprint. After a reviewer makes a decision, the host application resumes the same checkpoint/thread with a value shaped like:
+
+```python
+{
+    "approved": True,
+    "request_fingerprint": fingerprint_from_interrupt_payload,
+}
+```
+
+The middleware rejects missing, malformed, or mismatched approval responses. The fingerprint binds the response to the current principal, roles, tool call, arguments, action, resource, exact matched policy definitions, and LangGraph execution scope (`thread_id`, `checkpoint_id`, `checkpoint_ns`, and `task_id`). This makes the fingerprint different in another checkpointed execution even when request fields and the tool-call ID are repeated. Approval-required calls need LangGraph 1.2 or newer with an active checkpointer; missing execution metadata fails closed. Fingerprinting rejects non-string JSON object keys, non-finite numbers, cyclic structures, and other non-JSON argument values. **The fingerprint is a deterministic request-binding check, not proof of reviewer identity, permission, or one-time use.** The host application must authenticate the reviewer, authorize who can resume the paused run, and protect the resume endpoint. For side-effecting tools, ensure request IDs are unique per operation and durably consume each approval once. The `approval_validator` callback described below can enforce reviewer validation and atomic consumption at the middleware boundary. An explicit matching deny rule always takes precedence over approval.
+
+For deployments that need enforcement in the library boundary, pass an `approval_validator` callback to `create_authorization_middleware`. It receives the resumed approval mapping, the resolved `AccessRequest`, and the request fingerprint. It should authenticate and authorize the reviewer, then atomically claim/consume the fingerprint in a durable store; return the literal `True` only for a valid first use. A false or non-boolean result rejects the approval, and an exception fails closed by preventing tool execution. Implement this callback with your application's identity provider and transactional storage—do not use an in-memory set for multi-process or persistent workloads. The callback is invoked for validly-shaped approval and rejection responses, so the host can consume either human decision once. If the callback is omitted, the host must enforce these controls outside the library. An explicit matching deny rule always takes precedence over approval.
+
+## Validation
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest
+```
+
+GitHub Actions runs these checks across Python 3.11, 3.12, and 3.13 on pull requests and pushes to `main`, with a 98% minimum line-coverage gate. A separate packaging job builds both a wheel and source distribution, validates metadata, smoke-tests the installed wheel in a clean environment, and installs the `langchain-agents` extra in a separate environment to verify the optional middleware dependencies.
+
+After a change is merged into `main`, the automatic release workflow analyzes Conventional Commit messages. If a release-worthy change exists and all release quality checks pass, it updates the version and changelog, creates a version commit and Git tag, builds distributions, creates a GitHub Release, and publishes to PyPI using Trusted Publishing. No manual tag creation is required. See [the release process](docs/releasing.md).
+
+## Roadmap
+
+- [x] Typed package foundation, license, and CI
+- [x] Policy models and default-deny evaluation
+- [x] Deny-overrides semantics and constrained wildcards
+- [x] Guarded callable and fail-closed auditing
+- [x] Optional agent tool-call middleware
+- [x] Model-free LangGraph workflow example with mock payroll data
+- [ ] Example conversational agent using a model provider
+- [x] Human-approval interrupt integration for selected sensitive actions
+- [x] Initial threat model and security reporting guidance
+- [ ] API review and release-readiness checks
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for user-facing changes and release notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Disclaimer
+
+This project is experimental and is not a substitute for a complete application security review. Integrators remain responsible for authenticating principals, validating trusted context, enforcing tenant boundaries, and protecting downstream resources.

langgraph_secure_agents-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+langgraph_secure_agents/__init__.py,sha256=Z7aXJLBKqH68CG4SdJko1U02p4Gbo59tUbD_g0gvvl8,477
+langgraph_secure_agents/_resolver_safety.py,sha256=-HLqzybPuhMc4kLk9zh4bldKQGJLvOZldZt1DnZCoVI,1521
+langgraph_secure_agents/guard.py,sha256=Rsu-IjZewoRuO06vRx-_C2QEq_fi8D5nOmmOOAiBwmg,4722
+langgraph_secure_agents/middleware.py,sha256=6LDWo78mF-ZkXlyD2v0Af8uIbpxMSLMaEIqGhdSUoDk,14536
+langgraph_secure_agents/models.py,sha256=yOxktNz4mKELSeTZwek1e0b-tRRhe1bL7KXF0lZhS64,7937
+langgraph_secure_agents/policy.py,sha256=JjnMwkIIj2qn4ZJUvx3wJiiIcEpCZxicdGuPczfydL4,3763
+langgraph_secure_agents/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langgraph_secure_agents-0.1.0.dist-info/METADATA,sha256=9nfHqEP3fM1VWLSO-V9wsqnrv35h5ibMrM2mEAbsEFY,12881
+langgraph_secure_agents-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+langgraph_secure_agents-0.1.0.dist-info/licenses/LICENSE,sha256=PlEz0DYFMMxhspuBc-XnidURFTIdmRkYIYMCqmo2tBc,1070
+langgraph_secure_agents-0.1.0.dist-info/RECORD,,

langgraph_secure_agents-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

langgraph_secure_agents-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peyman Salimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.