tollgate 1.0.3__py3-none-any.whl → 1.0.5__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 GrantStore, 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.3"
+__version__ = "1.0.5"
 
 __all__ = [
     "ControlTower",
@@ -42,6 +44,8 @@ __all__ = [
     "Decision",
     "DecisionType",
     "Effect",
+    "Grant",
+    "GrantStore",
     "AuditEvent",
     "Outcome",
     "ApprovalOutcome",
@@ -57,6 +61,7 @@ __all__ = [
     "ToolRegistry",
     "PolicyEvaluator",
     "YamlPolicyEvaluator",
+    "InMemoryGrantStore",
     "TollgateError",
     "TollgateDenied",
     "TollgateApprovalDenied",

tollgate/grants.py

@@ -0,0 +1,149 @@
+import asyncio
+import time
+from typing import Protocol, runtime_checkable
+
+from .types import AgentContext, Grant, ToolRequest
+
+
+@runtime_checkable
+class GrantStore(Protocol):
+    """Protocol for grant storage backends.
+
+    Implement this protocol to use a custom storage backend (Redis, SQLite, etc.).
+
+    Example Redis implementation:
+
+        class RedisGrantStore:
+            def __init__(self, redis_client):
+                self.redis = redis_client
+
+            async def create_grant(self, grant: Grant) -> str:
+                await self.redis.hset(f"grant:{grant.id}", mapping=grant.to_dict())
+                await self.redis.expireat(f"grant:{grant.id}", int(grant.expires_at))
+                return grant.id
+
+            async def find_matching_grant(self, agent_ctx, tool_request) -> Grant | None:
+                # Implement matching logic with Redis SCAN or secondary indexes
+                ...
+
+    All methods must be async. The InMemoryGrantStore serves as the reference implementation.
+    """
+
+    async def create_grant(self, grant: Grant) -> str:
+        ...
+
+    async def find_matching_grant(
+        self, agent_ctx: AgentContext, tool_request: ToolRequest
+    ) -> Grant | None:
+        ...
+
+    async def revoke_grant(self, grant_id: str) -> bool:
+        ...
+
+    async def list_active_grants(self, agent_id: str | None = None) -> list[Grant]:
+        ...
+
+    async def cleanup_expired(self) -> int:
+        ...
+
+    async def get_usage_count(self, grant_id: str) -> int:
+        ...
+
+
+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/tower.py

@@ -11,6 +11,7 @@ from .exceptions import (
     TollgateDeferred,
     TollgateDenied,
 )
+from .grants import GrantStore
 from .policy import PolicyEvaluator
 from .types import (
     AgentContext,
@@ -32,11 +33,13 @@ class ControlTower:
         policy: PolicyEvaluator,
         approver: Approver,
         audit: AuditSink,
+        grant_store: GrantStore | 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 +89,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 +143,35 @@ 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
-            # Security: Sanitize exception message to avoid info disclosure
             result_summary = self._sanitize_exception(e)
             self._log(
                 correlation_id,
@@ -137,11 +181,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,
@@ -151,6 +196,7 @@ class ControlTower:
             tool_request,
             decision,
             outcome,
+            grant_id=grant_id,
             result_summary=result_summary,
         )
 
@@ -177,7 +223,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,
@@ -189,6 +237,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
@@ -212,47 +261,20 @@ 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
         s = str(result)
         return s[:max_chars] + "..." if len(s) > max_chars else s
-
-    def _sanitize_exception(self, e: Exception, max_chars: int = 100) -> str:
-        """
-        Sanitize exception message for audit logging.
-
-        Removes potentially sensitive information like file paths, stack traces,
-        and internal details while preserving the exception type.
-        """
-        exc_type = type(e).__name__
-
-        # For common safe exceptions, include a truncated message
-        safe_exceptions = {
-            "ValueError",
-            "TypeError",
-            "KeyError",
-            "IndexError",
-            "AttributeError",
-            "RuntimeError",
-        }
-
-        if exc_type in safe_exceptions:
-            msg = str(e)
-            # Remove file paths (Unix and Windows style)
-            import re
-
-            msg = re.sub(r"['\"]?(/[^\s'\"]+|[A-Za-z]:\\[^\s'\"]+)['\"]?", "[PATH]", msg)
-            # Truncate to avoid leaking too much info
-            if len(msg) > max_chars:
-                msg = msg[:max_chars] + "..."
-            return f"{exc_type}: {msg}"
-
-        # For unknown exceptions, only log the type
-        return f"{exc_type}: [details redacted]"

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.3.dist-info → tollgate-1.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tollgate
-Version: 1.0.3
+Version: 1.0.5
 Summary: Runtime enforcement layer for AI agent tool calls using Identity + Intent + Policy
 Author: Tollgate Maintainers
 License-Expression: Apache-2.0
@@ -77,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.3.dist-info → tollgate-1.0.5.dist-info}/RECORD

@@ -1,12 +1,13 @@
-tollgate/__init__.py,sha256=_JKKvkQRE_LpYbFTewyi_TC6BBKxaKqIJIQEIsVUHts,1322
+tollgate/__init__.py,sha256=KWxtUI6D0Cm4QHCAaVv5VdEiQIo_krw7jzbXofxW_FM,1441
 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=H5soShiNcyQiY3gLJRqqP7ffAo2Udmnj3iU15sGi3os,5177
 tollgate/helpers.py,sha256=ZFMi19_ogpTlV_svFtgJ9kkmA1sPte1dmDnHYVdWGyo,1657
 tollgate/policy.py,sha256=1_6HcbdpGfZtwmgqapqeRzItc_wbEg_L-fOA-BVIWNg,6110
 tollgate/registry.py,sha256=ENKT-GnwFq0xXZj6qNlKFhAGYsxxBwtZsAdPZp2qlHM,2031
-tollgate/tower.py,sha256=JSCRTEyKpxst7bm_8trttvPeUXt-PZZLBVYgxLeOX_s,7801
-tollgate/types.py,sha256=Y__9nseQ7aM8TI1m2Voo5Ph-qJ5aDj7fLgJ-My2GsXc,3025
+tollgate/tower.py,sha256=rPG2sdVe2GpdGiyHwWz8K4k7EJCL2NqDAGsMUkKlt30,8574
+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
@@ -14,7 +15,7 @@ tollgate/interceptors/__init__.py,sha256=0c3MYyVKGYrBOZ1mMolgrAowrqZrULzAl0vv-s8
 tollgate/interceptors/base.py,sha256=uJxHzH0eurcGEVknbk1kQkk_2u2qNtnM--ZRCp52Wyo,1390
 tollgate/interceptors/langchain.py,sha256=_8vXCjWkRKeTlxtXm33a67Gf4po9YiHS7faThMJLohc,2963
 tollgate/interceptors/openai.py,sha256=cHnOQ8keQJRYBm_1RpohKWk3D9Ask22hpuQghm9iahU,3337
-tollgate-1.0.3.dist-info/METADATA,sha256=bnpYItrHUP0lRCYmTYfRxog1J79JI1S8VAmpymzV-ZU,6963
-tollgate-1.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tollgate-1.0.3.dist-info/licenses/LICENSE,sha256=EZ9SehMCkcatlggcoT7WV0tx-ku4OsAoQf9LmJZvG1g,10806
-tollgate-1.0.3.dist-info/RECORD,,
+tollgate-1.0.5.dist-info/METADATA,sha256=zPDa8CQ7Qqx5GoQ6XojAZgur47ErP6KeWoUCfhTQOXs,7748
+tollgate-1.0.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tollgate-1.0.5.dist-info/licenses/LICENSE,sha256=EZ9SehMCkcatlggcoT7WV0tx-ku4OsAoQf9LmJZvG1g,10806
+tollgate-1.0.5.dist-info/RECORD,,