tollgate 1.0.3__tar.gz → 1.0.4__tar.gz

{tollgate-1.0.3 → tollgate-1.0.4}/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-01-28
+### Added
+- **Session Grants**: Introduced `Grant` and `InMemoryGrantStore` to allow bypassing human approval for specific, pre-authorized actions.
+- **Grant ID Auto-generation**: Grant IDs are now automatically generated if not provided.
+- **Grant Usage Tracking**: Added usage counters to `InMemoryGrantStore`.
+- **Audit Integration**: Audit events now include `grant_id` when a grant is used.
+- **Security**: Re-added and enforced exception sanitization in audit logs.
+
 ## [1.0.0] - 2026-01-27
 ### Added
 - **Interception-First Architecture**: Added `TollgateInterceptor` and framework adapters for LangChain and OpenAI.

{tollgate-1.0.3 → tollgate-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tollgate
-Version: 1.0.3
+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
@@ -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 → tollgate-1.0.4}/README.md

@@ -52,6 +52,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 → tollgate-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tollgate"
-version = "1.0.3"
+version = "1.0.4"
 description = "Runtime enforcement layer for AI agent tool calls using Identity + Intent + Policy"
 readme = "README.md"
 requires-python = ">=3.10"

{tollgate-1.0.3 → tollgate-1.0.4}/src/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.3"
+__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-1.0.4/src/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-1.0.3 → tollgate-1.0.4}/src/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,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 +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,
@@ -151,6 +195,7 @@ class ControlTower:
             tool_request,
             decision,
             outcome,
+            grant_id=grant_id,
             result_summary=result_summary,
         )
 
@@ -177,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,
@@ -189,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
@@ -212,47 +260,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-1.0.3 → tollgate-1.0.4}/src/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.4/tests/test_grants.py

@@ -0,0 +1,286 @@
+import asyncio
+import time
+
+import pytest
+
+from tollgate import (
+    AgentContext,
+    ControlTower,
+    Decision,
+    DecisionType,
+    Effect,
+    Grant,
+    InMemoryGrantStore,
+    Intent,
+    Outcome,
+    ToolRequest,
+)
+
+
+class MockPolicy:
+    def evaluate(self, _ctx, _intent, _req):
+        return Decision(
+            decision=DecisionType.ASK, reason="Needs approval", policy_version="1"
+        )
+
+
+class MockApprover:
+    async def request_approval_async(self, *_args):
+        # This should NOT be called if a grant matches
+        pytest.fail("Approver should not be called when a grant matches")
+
+
+class MockAudit:
+    def __init__(self):
+        self.events = []
+
+    def emit(self, event):
+        self.events.append(event)
+
+
+@pytest.fixture
+def agent_ctx():
+    return AgentContext(agent_id="agent-1", version="1.0.0", owner="user-1")
+
+
+@pytest.fixture
+def tool_req():
+    return ToolRequest(
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        effect=Effect.READ,
+        params={"id": 1},
+    )
+
+
+@pytest.mark.asyncio
+async def test_create_and_find_grant(agent_ctx, tool_req):
+    store = InMemoryGrantStore()
+    # Test auto-generating ID
+    grant = Grant(
+        agent_id="agent-1",
+        effect=Effect.READ,
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    assert grant.id is not None
+    await store.create_grant(grant)
+
+    found = await store.find_matching_grant(agent_ctx, tool_req)
+    assert found is not None
+    assert found.id == grant.id
+
+
+@pytest.mark.asyncio
+async def test_grant_usage_counter(agent_ctx, tool_req):
+    store = InMemoryGrantStore()
+    grant = Grant(
+        agent_id="agent-1",
+        effect=Effect.READ,
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    await store.create_grant(grant)
+
+    assert await store.get_usage_count(grant.id) == 0
+    await store.find_matching_grant(agent_ctx, tool_req)
+    assert await store.get_usage_count(grant.id) == 1
+    await store.find_matching_grant(agent_ctx, tool_req)
+    assert await store.get_usage_count(grant.id) == 2
+
+
+@pytest.mark.asyncio
+async def test_grant_expiry(agent_ctx, tool_req):
+    store = InMemoryGrantStore()
+    grant = Grant(
+        agent_id="agent-1",
+        effect=Effect.READ,
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() - 1,  # Expired
+        granted_by="admin",
+        created_at=time.time() - 3600,
+    )
+    await store.create_grant(grant)
+
+    found = await store.find_matching_grant(agent_ctx, tool_req)
+    assert found is None
+
+
+@pytest.mark.asyncio
+async def test_grant_wildcard_agent(tool_req):
+    store = InMemoryGrantStore()
+    grant = Grant(
+        agent_id=None,  # Wildcard
+        effect=Effect.READ,
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    await store.create_grant(grant)
+
+    ctx2 = AgentContext(agent_id="any-agent", version="1", owner="o")
+    found = await store.find_matching_grant(ctx2, tool_req)
+    assert found is not None
+
+
+@pytest.mark.asyncio
+async def test_grant_wildcard_effect(agent_ctx, tool_req):
+    store = InMemoryGrantStore()
+    grant = Grant(
+        agent_id="agent-1",
+        effect=None,  # Wildcard
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    await store.create_grant(grant)
+
+    found = await store.find_matching_grant(agent_ctx, tool_req)
+    assert found is not None
+
+
+@pytest.mark.asyncio
+async def test_grant_tool_prefix_match(agent_ctx, tool_req):
+    store = InMemoryGrantStore()
+    grant = Grant(
+        agent_id="agent-1",
+        effect=Effect.READ,
+        tool="mcp:*",  # Prefix match
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    await store.create_grant(grant)
+
+    found = await store.find_matching_grant(agent_ctx, tool_req)
+    assert found is not None
+
+
+@pytest.mark.asyncio
+async def test_grant_no_match(agent_ctx):
+    store = InMemoryGrantStore()
+    grant = Grant(
+        agent_id="agent-1",
+        effect=Effect.WRITE,  # Mismatch (READ vs WRITE)
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    await store.create_grant(grant)
+
+    req = ToolRequest(
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        effect=Effect.READ,
+        params={},
+    )
+    found = await store.find_matching_grant(agent_ctx, req)
+    assert found is None
+
+
+@pytest.mark.asyncio
+async def test_revoke_grant(agent_ctx, tool_req):
+    store = InMemoryGrantStore()
+    grant = Grant(
+        agent_id="agent-1",
+        effect=Effect.READ,
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    await store.create_grant(grant)
+    await store.revoke_grant(grant.id)
+
+    found = await store.find_matching_grant(agent_ctx, tool_req)
+    assert found is None
+
+
+@pytest.mark.asyncio
+async def test_cleanup_expired():
+    store = InMemoryGrantStore()
+    g1 = Grant(
+        agent_id=None,
+        effect=None,
+        tool=None,
+        action=None,
+        resource_type=None,
+        expires_at=time.time() - 1,
+        granted_by="a",
+        created_at=time.time(),
+    )
+    g2 = Grant(
+        agent_id=None,
+        effect=None,
+        tool=None,
+        action=None,
+        resource_type=None,
+        expires_at=time.time() + 10,
+        granted_by="a",
+        created_at=time.time(),
+    )
+    await store.create_grant(g1)
+    await store.create_grant(g2)
+
+    cleaned = await store.cleanup_expired()
+    assert cleaned == 1
+    active = await store.list_active_grants()
+    assert len(active) == 1
+    assert active[0].id == g2.id
+
+
+@pytest.mark.asyncio
+async def test_tower_uses_grant(agent_ctx, tool_req):
+    store = InMemoryGrantStore()
+    audit = MockAudit()
+    approver = MockApprover()
+    tower = ControlTower(MockPolicy(), approver, audit, grant_store=store)
+
+    grant = Grant(
+        agent_id="agent-1",
+        effect=Effect.READ,
+        tool="mcp:server.read",
+        action="read",
+        resource_type="data",
+        expires_at=time.time() + 3600,
+        granted_by="admin",
+        created_at=time.time(),
+    )
+    await store.create_grant(grant)
+
+    async def tool_fn():
+        return "ok"
+
+    intent = Intent(action="test", reason="test")
+    result = await tower.execute_async(agent_ctx, intent, tool_req, tool_fn)
+
+    assert result == "ok"
+    assert len(audit.events) > 0
+    event = audit.events[-1]
+    assert event.grant_id == grant.id
+    assert event.outcome == Outcome.EXECUTED