tollgate 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

tollgate/__init__.py

@@ -1,5 +1,4 @@
 from .approvals import (
-    ApprovalOutcome,
     ApprovalStore,
     Approver,
     AsyncQueueApprover,
@@ -15,23 +14,26 @@ from .exceptions import (
     TollgateDenied,
     TollgateError,
 )
+from .grants import InMemoryGrantStore
 from .helpers import guard, wrap_tool
 from .policy import PolicyEvaluator, YamlPolicyEvaluator
 from .registry import ToolRegistry
 from .tower import ControlTower
 from .types import (
     AgentContext,
+    ApprovalOutcome,
     AuditEvent,
     Decision,
     DecisionType,
     Effect,
+    Grant,
     Intent,
     NormalizedToolCall,
     Outcome,
     ToolRequest,
 )
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 
 __all__ = [
     "ControlTower",
@@ -42,6 +44,7 @@ __all__ = [
     "Decision",
     "DecisionType",
     "Effect",
+    "Grant",
     "AuditEvent",
     "Outcome",
     "ApprovalOutcome",
@@ -57,6 +60,7 @@ __all__ = [
     "ToolRegistry",
     "PolicyEvaluator",
     "YamlPolicyEvaluator",
+    "InMemoryGrantStore",
     "TollgateError",
     "TollgateDenied",
     "TollgateApprovalDenied",

tollgate/approvals.py

@@ -56,6 +56,7 @@ class InMemoryApprovalStore(ApprovalStore):
     def __init__(self):
         self._requests: dict[str, dict[str, Any]] = {}
         self._events: dict[str, asyncio.Event] = {}
+        self._lock = asyncio.Lock()
 
     async def create_request(
         self, agent_ctx, intent, tool_request, request_hash, reason, expiry
@@ -77,19 +78,21 @@ class InMemoryApprovalStore(ApprovalStore):
     async def set_decision(
         self, approval_id, outcome, decided_by, decided_at, request_hash
     ):
-        if approval_id in self._requests:
-            req = self._requests[approval_id]
-            # Replay protection: hash must match
-            if req["request_hash"] != request_hash:
-                raise ValueError(
-                    "Request hash mismatch. Approval bound to a different request."
-                )
-
-            req["outcome"] = outcome
-            req["decided_by"] = decided_by
-            req["decided_at"] = decided_at
-            if approval_id in self._events:
-                self._events[approval_id].set()
+        # Security: Use lock for atomic read-modify-write operation
+        async with self._lock:
+            if approval_id in self._requests:
+                req = self._requests[approval_id]
+                # Replay protection: hash must match
+                if req["request_hash"] != request_hash:
+                    raise ValueError(
+                        "Request hash mismatch. Approval bound to a different request."
+                    )
+
+                req["outcome"] = outcome
+                req["decided_by"] = decided_by
+                req["decided_at"] = decided_at
+                if approval_id in self._events:
+                    self._events[approval_id].set()
 
     async def get_request(self, approval_id):
         return self._requests.get(approval_id)
@@ -172,21 +175,35 @@ class AutoApprover:
 class CliApprover:
     """Async-wrapped CLI approver for development."""
 
-    def __init__(self, show_emojis: bool = True):
+    def __init__(self, show_emojis: bool = True, timeout: float = 300.0):
+        """
+        Initialize CliApprover.
+
+        :param show_emojis: Whether to display emojis in prompts.
+        :param timeout: Timeout in seconds for user input (default 5 minutes).
+        """
         self.show_emojis = show_emojis
+        self.timeout = timeout
 
     async def request_approval_async(
         self, agent_ctx, intent, tool_request, _hash, reason
     ) -> ApprovalOutcome:
         loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(
-            None,
-            self._sync_request,
-            agent_ctx,
-            intent,
-            tool_request,
-            reason,
-        )
+        try:
+            return await asyncio.wait_for(
+                loop.run_in_executor(
+                    None,
+                    self._sync_request,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    reason,
+                ),
+                timeout=self.timeout,
+            )
+        except asyncio.TimeoutError:
+            print("\nApproval request timed out.")
+            return ApprovalOutcome.TIMEOUT
 
     def _sync_request(self, agent_ctx, intent, tool_request, reason) -> ApprovalOutcome:
         prefix = "🚦 " if self.show_emojis else ""

tollgate/grants.py

@@ -0,0 +1,103 @@
+import asyncio
+import time
+
+from .types import AgentContext, Grant, ToolRequest
+
+
+class InMemoryGrantStore:
+    """In-memory store for action grants with thread-safe matching logic."""
+
+    def __init__(self):
+        self._grants: dict[str, Grant] = {}
+        self._usage_counts: dict[str, int] = {}
+        self._lock = asyncio.Lock()
+
+    async def create_grant(self, grant: Grant) -> str:
+        """Store a new grant."""
+        async with self._lock:
+            self._grants[grant.id] = grant
+            self._usage_counts[grant.id] = 0
+            return grant.id
+
+    async def find_matching_grant(
+        self, agent_ctx: AgentContext, tool_request: ToolRequest
+    ) -> Grant | None:
+        """Find a non-expired grant that matches the request."""
+        now = time.time()
+        async with self._lock:
+            for grant in self._grants.values():
+                # 1. Skip expired
+                if grant.expires_at <= now:
+                    continue
+
+                # 2. Match agent_id
+                if grant.agent_id is not None and grant.agent_id != agent_ctx.agent_id:
+                    continue
+
+                # 3. Match effect
+                if grant.effect is not None and grant.effect != tool_request.effect:
+                    continue
+
+                # 4. Match tool (exact or prefix with *)
+                if grant.tool is not None:
+                    if grant.tool.endswith("*"):
+                        prefix = grant.tool[:-1]
+                        if not tool_request.tool.startswith(prefix):
+                            continue
+                    elif grant.tool != tool_request.tool:
+                        continue
+
+                # 5. Match action
+                if grant.action is not None and grant.action != tool_request.action:
+                    continue
+
+                # 6. Match resource_type
+                if (
+                    grant.resource_type is not None
+                    and grant.resource_type != tool_request.resource_type
+                ):
+                    continue
+
+                # Match found! Increment usage count
+                self._usage_counts[grant.id] += 1
+                return grant
+            return None
+
+    async def get_usage_count(self, grant_id: str) -> int:
+        """Get the number of times a grant has been used."""
+        async with self._lock:
+            return self._usage_counts.get(grant_id, 0)
+
+    async def revoke_grant(self, grant_id: str) -> bool:
+        """Remove a grant by ID."""
+        async with self._lock:
+            if grant_id in self._grants:
+                del self._grants[grant_id]
+                if grant_id in self._usage_counts:
+                    del self._usage_counts[grant_id]
+                return True
+            return False
+
+    async def list_active_grants(self, agent_id: str | None = None) -> list[Grant]:
+        """List all non-expired grants, optionally filtered by agent."""
+        now = time.time()
+        async with self._lock:
+            active = []
+            for grant in self._grants.values():
+                if grant.expires_at > now:
+                    if agent_id is None or grant.agent_id == agent_id:
+                        active.append(grant)
+            return active
+
+    async def cleanup_expired(self) -> int:
+        """Remove all expired grants from the store."""
+        now = time.time()
+        async with self._lock:
+            to_remove = [
+                gid for gid, g in self._grants.items() if g.expires_at <= now
+            ]
+            for gid in to_remove:
+                del self._grants[gid]
+                if gid in self._usage_counts:
+                    del self._usage_counts[gid]
+            return len(to_remove)

tollgate/interceptors/openai.py

@@ -3,6 +3,7 @@ import json
 from collections.abc import Callable
 from typing import Any
 
+from ..exceptions import TollgateDenied
 from ..registry import ToolRegistry
 from ..tower import ControlTower
 from ..types import AgentContext, Intent, NormalizedToolCall, ToolRequest
@@ -26,10 +27,23 @@ class OpenAIAdapter:
             kwargs = {}
 
         tool_name = tc_dict.get("function", {}).get("name") or tc_dict.get("name")
+
+        # Security: Validate tool_name is not None or empty
+        if not tool_name:
+            raise TollgateDenied("Tool call missing required 'name' field")
+
         args_str = tc_dict.get("function", {}).get("arguments") or tc_dict.get(
             "arguments"
         )
-        args = json.loads(args_str) if isinstance(args_str, str) else args_str
+
+        # Security: Safe JSON parsing with proper error handling
+        if isinstance(args_str, str):
+            try:
+                args = json.loads(args_str)
+            except json.JSONDecodeError as e:
+                raise TollgateDenied(f"Invalid JSON in tool arguments: {e.msg}") from e
+        else:
+            args = args_str if args_str is not None else {}
 
         registry_key = f"openai:{tool_name}"
         effect, resource_type, manifest_version = self.registry.resolve_tool(
@@ -48,6 +62,10 @@ class OpenAIAdapter:
             manifest_version=manifest_version,
         )
 
+        # Security: Handle missing tool in tool_map
+        if tool_name not in self.tool_map:
+            raise TollgateDenied(f"Unknown tool: {tool_name}")
+
         func = self.tool_map[tool_name]
 
         async def _exec_async():

tollgate/policy.py

@@ -20,6 +20,10 @@ class PolicyEvaluator(Protocol):
 class YamlPolicyEvaluator:
     """YAML-based policy evaluator with safe defaults."""
 
+    # Security: Whitelist of allowed attributes for agent_ctx and intent matching
+    ALLOWED_AGENT_ATTRS = frozenset({"agent_id", "version", "environment", "role"})
+    ALLOWED_INTENT_ATTRS = frozenset({"action", "reason", "session_id"})
+
     def __init__(
         self,
         policy_path: str | Path,
@@ -108,15 +112,21 @@ class YamlPolicyEvaluator:
         if "effect" in rule and rule["effect"] != req.effect.value:
             return False
 
-        # Match Agent Context
+        # Match Agent Context (with attribute whitelist)
         if "agent" in rule:
             for key, expected_val in rule["agent"].items():
+                # Security: Only allow whitelisted attributes
+                if key not in self.ALLOWED_AGENT_ATTRS:
+                    continue
                 if getattr(agent_ctx, key, None) != expected_val:
                     return False
 
-        # Match Intent
+        # Match Intent (with attribute whitelist)
         if "intent" in rule:
             for key, expected_val in rule["intent"].items():
+                # Security: Only allow whitelisted attributes
+                if key not in self.ALLOWED_INTENT_ATTRS:
+                    continue
                 if getattr(intent, key, None) != expected_val:
                     return False
 

tollgate/tower.py

@@ -32,11 +32,13 @@ class ControlTower:
         policy: PolicyEvaluator,
         approver: Approver,
         audit: AuditSink,
+        grant_store: Any | None = None,
         redact_fn: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
     ):
         self.policy = policy
         self.approver = approver
         self.audit = audit
+        self.grant_store = grant_store
         self.redact_fn = redact_fn or self._default_redact
 
     @staticmethod
@@ -86,6 +88,26 @@ class ControlTower:
 
         # 3. Handle ASK
         if decision.decision == DecisionType.ASK:
+            # 3.1 Check Grants
+            if self.grant_store:
+                matching_grant = await self.grant_store.find_matching_grant(
+                    agent_ctx, tool_request
+                )
+                if matching_grant:
+                    # Grant found! Proceed to execution without asking approver
+                    result = await self._execute_and_log(
+                        correlation_id,
+                        request_hash,
+                        agent_ctx,
+                        intent,
+                        tool_request,
+                        decision,
+                        exec_async,
+                        grant_id=matching_grant.id,
+                    )
+                    return result
+
+            # 3.2 Request Approval if no grant found
             outcome = await self.approver.request_approval_async(
                 agent_ctx, intent, tool_request, request_hash, decision.reason
             )
@@ -120,14 +142,36 @@ class ControlTower:
                 )
                 raise TollgateApprovalDenied(f"Approval failed: {outcome.value}")
 
-        # 4. Execute tool
+        # 4. Execute tool (Policy ALLOW or Approval APPROVED)
+        return await self._execute_and_log(
+            correlation_id,
+            request_hash,
+            agent_ctx,
+            intent,
+            tool_request,
+            decision,
+            exec_async,
+        )
+
+    async def _execute_and_log(
+        self,
+        correlation_id: str,
+        request_hash: str,
+        agent_ctx: AgentContext,
+        intent: Intent,
+        tool_request: ToolRequest,
+        decision: Decision,
+        exec_async: Callable[[], Awaitable[Any]],
+        grant_id: str | None = None,
+    ) -> Any:
+        """Internal helper to execute tool and log result."""
         result = None
         outcome = Outcome.EXECUTED
         try:
             result = await exec_async()
         except Exception as e:
             outcome = Outcome.FAILED
-            result_summary = f"{type(e).__name__}: {str(e)}"
+            result_summary = self._sanitize_exception(e)
             self._log(
                 correlation_id,
                 request_hash,
@@ -136,11 +180,12 @@ class ControlTower:
                 tool_request,
                 decision,
                 outcome,
+                grant_id=grant_id,
                 result_summary=result_summary,
             )
             raise
 
-        # 5. Final Audit
+        # Final Audit
         result_summary = self._truncate_result(result)
         self._log(
             correlation_id,
@@ -150,6 +195,7 @@ class ControlTower:
             tool_request,
             decision,
             outcome,
+            grant_id=grant_id,
             result_summary=result_summary,
         )
 
@@ -176,7 +222,9 @@ class ControlTower:
         async def _exec():
             return exec_sync()
 
-        return asyncio.run(self.execute_async(agent_ctx, intent, tool_request, _exec))
+        return asyncio.run(
+            self.execute_async(agent_ctx, intent, tool_request, _exec)
+        )
 
     def _log(
         self,
@@ -188,6 +236,7 @@ class ControlTower:
         decision: Decision,
         outcome: Outcome,
         approval_id: str | None = None,
+        grant_id: str | None = None,
         result_summary: str | None = None,
     ):
         # Redact params before logging
@@ -211,12 +260,18 @@ class ControlTower:
             decision=decision,
             outcome=outcome,
             approval_id=approval_id,
+            grant_id=grant_id,
             result_summary=result_summary,
             policy_version=decision.policy_version,
             manifest_version=req.manifest_version,
         )
         self.audit.emit(event)
 
+    def _sanitize_exception(self, e: Exception) -> str:
+        """Sanitize exception message to avoid leaking sensitive data."""
+        # Only include the exception type and a generic message for security
+        return f"{type(e).__name__}: Execution failed"
+
     def _truncate_result(self, result: Any, max_chars: int = 200) -> str | None:
         if result is None:
             return None

tollgate/types.py

@@ -1,3 +1,4 @@
+import uuid
 from collections.abc import Awaitable, Callable
 from dataclasses import asdict, dataclass, field
 from enum import Enum
@@ -92,6 +93,28 @@ class Decision:
         return d
 
 
+@dataclass(frozen=True)
+class Grant:
+    """A grant that allows bypassing human approval for specific actions."""
+
+    agent_id: str | None  # None = any agent
+    effect: Effect | None  # None = any effect
+    tool: str | None  # None = any tool, supports prefix like "mcp:*"
+    action: str | None  # None = any action
+    resource_type: str | None  # None = any resource
+    expires_at: float  # Unix timestamp
+    granted_by: str
+    created_at: float
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    reason: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        if self.effect:
+            d["effect"] = self.effect.value
+        return d
+
+
 @dataclass(frozen=True)
 class AuditEvent:
     timestamp: str
@@ -103,6 +126,7 @@ class AuditEvent:
     decision: Decision
     outcome: Outcome
     approval_id: str | None = None
+    grant_id: str | None = None
     result_summary: str | None = None
     policy_version: str | None = None
     manifest_version: str | None = None
@@ -118,6 +142,7 @@ class AuditEvent:
             "decision": self.decision.to_dict(),
             "outcome": self.outcome.value,
             "approval_id": self.approval_id,
+            "grant_id": self.grant_id,
             "result_summary": self.result_summary,
             "policy_version": self.policy_version,
             "manifest_version": self.manifest_version,

{tollgate-1.0.2.dist-info → tollgate-1.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tollgate
-Version: 1.0.2
+Version: 1.0.4
 Summary: Runtime enforcement layer for AI agent tool calls using Identity + Intent + Policy
 Author: Tollgate Maintainers
 License-Expression: Apache-2.0
@@ -29,6 +29,9 @@ Runtime enforcement layer for AI agent tool calls using **Identity + Intent + Po
 
 `tollgate` provides a deterministic safety boundary for AI agents. It ensures every tool call is validated against a policy before execution, with support for async human-in-the-loop approvals, framework interception (MCP, Strands, LangChain, OpenAI), and structured audit logging.
 
+> [!CAUTION]
+> **Disclaimer**: This project is an exploratory implementation intended for learning and discussion. It is not production-hardened and comes with no guarantees.
+
 **[🚀 Quickstart Guide](https://github.com/ravi-labs/tollgate/blob/main/QUICKSTART.md) | [📊 Integration Comparison](https://github.com/ravi-labs/tollgate/blob/main/COMPARISON.md)**
 
 ```
@@ -74,6 +77,30 @@ Runtime enforcement layer for AI agent tool calls using **Identity + Intent + Po
 
 ## 🚀 v1 Integrations
 
+### 🎟️ Session Grants
+Grants allow you to pre-authorize specific actions for an agent session, bypassing human-in-the-loop approvals for repetitive or low-risk tasks.
+
+```python
+from tollgate import Grant, InMemoryGrantStore, Effect
+
+# 1. Setup a grant store
+grant_store = InMemoryGrantStore()
+tower = ControlTower(..., grant_store=grant_store)
+
+# 2. Issue a grant (e.g., after initial human approval)
+grant = Grant(
+    agent_id="my-agent",
+    effect=Effect.WRITE,
+    tool="mcp:*", # Wildcard prefix: matches any MCP tool (e.g., "mcp:server.write")
+    action=None,  # Wildcard: matches any action
+    resource_type=None,
+    expires_at=time.time() + 3600, # Valid for 1 hour
+    granted_by="admin-user",
+    created_at=time.time()
+)
+await grant_store.create_grant(grant)
+```
+
 ### MCP (Model Context Protocol)
 Wrap an MCP client to gate all tool calls:
 ```python

{tollgate-1.0.2.dist-info → tollgate-1.0.4.dist-info}/RECORD

@@ -1,20 +1,21 @@
-tollgate/__init__.py,sha256=o-IL79mjKN0M_68YJ6y54aECDhpPQFbRxNNByCpmofI,1322
-tollgate/approvals.py,sha256=82DjgRSugFnJGlH6TNYjGwC5jWAtOmEWV8rJju7G5LI,7083
+tollgate/__init__.py,sha256=6Q6_5rZP0-LOOX-ARz73_wL3EBjxjNnDSIMozJaf2oQ,1411
+tollgate/approvals.py,sha256=lalvun6i5yaZ2EGZ-apQJBrLVmht5OfwgiUFsImPdYE,7814
 tollgate/audit.py,sha256=ugMhuuLoyBNdYD2S_MjGN_ac4nHdtRz15MElqElREIs,1279
 tollgate/exceptions.py,sha256=2yYY3esnHz26dyJlx_Cd_J64ryhexrgc4KliDmiVJSs,882
+tollgate/grants.py,sha256=nPQ0hb2mxFDq6axzFc5mOgSHiT01SiSqhwbQBdFPkaY,3738
 tollgate/helpers.py,sha256=ZFMi19_ogpTlV_svFtgJ9kkmA1sPte1dmDnHYVdWGyo,1657
-tollgate/policy.py,sha256=43-vfwbvpoMrjJZtZLicV4JveFWudTiKm7_nkzRYVEc,5521
+tollgate/policy.py,sha256=1_6HcbdpGfZtwmgqapqeRzItc_wbEg_L-fOA-BVIWNg,6110
 tollgate/registry.py,sha256=ENKT-GnwFq0xXZj6qNlKFhAGYsxxBwtZsAdPZp2qlHM,2031
-tollgate/tower.py,sha256=eCKmkzoR2nkLxDeXRPGlgJwkdGoRw6VLY3Q5R6bujs4,6609
-tollgate/types.py,sha256=Y__9nseQ7aM8TI1m2Voo5Ph-qJ5aDj7fLgJ-My2GsXc,3025
+tollgate/tower.py,sha256=JI8BGSCC7u0hkxIJmtrH9jflhTKm7py44JUJoz1NJbU,8536
+tollgate/types.py,sha256=Ks3HNawhPzEAggTCab7NLb8zl06777ehEusASJWSj_g,3811
 tollgate/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tollgate/integrations/mcp.py,sha256=jBy1d64Yc55fO4JSVfhKqiffVCZdBMmmNLRta9SVfDE,1750
 tollgate/integrations/strands.py,sha256=_AWsIyva_iwLFIQeTMxxbEzLSjneo0YumWfY9oayKeM,3003
 tollgate/interceptors/__init__.py,sha256=0c3MYyVKGYrBOZ1mMolgrAowrqZrULzAl0vv-s8IFFg,305
 tollgate/interceptors/base.py,sha256=uJxHzH0eurcGEVknbk1kQkk_2u2qNtnM--ZRCp52Wyo,1390
 tollgate/interceptors/langchain.py,sha256=_8vXCjWkRKeTlxtXm33a67Gf4po9YiHS7faThMJLohc,2963
-tollgate/interceptors/openai.py,sha256=--xSussx3HY5DYBLO4F7_h6_amer47PtpqGyRDUPwGc,2680
-tollgate-1.0.2.dist-info/METADATA,sha256=Q5Njrg5fscAEimYJafqwarIqMv_JFiTZM0ybn4-Udd0,6787
-tollgate-1.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tollgate-1.0.2.dist-info/licenses/LICENSE,sha256=EZ9SehMCkcatlggcoT7WV0tx-ku4OsAoQf9LmJZvG1g,10806
-tollgate-1.0.2.dist-info/RECORD,,
+tollgate/interceptors/openai.py,sha256=cHnOQ8keQJRYBm_1RpohKWk3D9Ask22hpuQghm9iahU,3337
+tollgate-1.0.4.dist-info/METADATA,sha256=JnYhkyYWulY-WQ0cEuGfvsk6gQsDthGtvrTqCZIlAgk,7748
+tollgate-1.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tollgate-1.0.4.dist-info/licenses/LICENSE,sha256=EZ9SehMCkcatlggcoT7WV0tx-ku4OsAoQf9LmJZvG1g,10806
+tollgate-1.0.4.dist-info/RECORD,,