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

tollgate/registry.py

@@ -1,5 +1,8 @@
+import fnmatch
 import hashlib
+import re
 from pathlib import Path
+from typing import Any
 
 import yaml
 
@@ -7,13 +10,36 @@ from .types import Effect
 
 
 class ToolRegistry:
-    """A registry of trusted tool metadata."""
+    """A registry of trusted tool metadata.
 
-    def __init__(self, manifest_path: str | Path):
+    Supports:
+      - Tool effect / resource_type resolution (core v1.0)
+      - Parameter schema validation (v1.1 — roadmap 1.1)
+      - Tool constraints such as URL allowlisting (v1.1 — roadmap 1.4)
+      - Cryptographic manifest signing verification (v1.2 — roadmap 2.2)
+    """
+
+    def __init__(
+        self,
+        manifest_path: str | Path,
+        *,
+        signing_key: bytes | None = None,
+    ):
         self.path = Path(manifest_path)
         if not self.path.exists():
             raise FileNotFoundError(f"Manifest file not found: {manifest_path}")
 
+        # 2.2: Verify manifest signature before loading
+        if signing_key is not None:
+            from .manifest_signing import verify_manifest
+
+            if not verify_manifest(self.path, secret_key=signing_key):
+                raise ValueError(
+                    f"Manifest signature verification failed for {manifest_path}. "
+                    "The manifest may have been tampered with, or the "
+                    "signature file (.sig) is missing."
+                )
+
         with self.path.open("r") as f:
             content = f.read()
             self.data = yaml.safe_load(content)
@@ -56,3 +82,200 @@ class ToolRegistry:
         effect = Effect(meta.get("effect", "unknown"))
         resource_type = meta.get("resource_type", "unknown")
         return effect, resource_type, self.version
+
+    # ------------------------------------------------------------------
+    # 1.1  Parameter Schema Validation
+    # ------------------------------------------------------------------
+
+    def get_params_schema(self, tool_key: str) -> dict[str, Any] | None:
+        """Return the params_schema for a tool, or None if not defined."""
+        meta = self.tools.get(tool_key)
+        if not meta:
+            return None
+        return meta.get("params_schema")
+
+    def validate_params(
+        self, tool_key: str, params: dict[str, Any]
+    ) -> list[str]:
+        """Validate tool parameters against the manifest schema.
+
+        Returns a list of validation error strings.  An empty list means
+        the parameters are valid (or no schema is defined for this tool).
+
+        The validator is intentionally self-contained (no ``jsonschema``
+        dependency) and supports a practical subset of JSON Schema:
+
+        - ``type`` (string, number, integer, boolean, object, array, null)
+        - ``required`` (list of required property names)
+        - ``properties`` (per-property sub-schemas)
+        - ``pattern`` (regex for string values)
+        - ``maxLength`` / ``minLength``
+        - ``minimum`` / ``maximum``
+        - ``enum``
+        """
+        schema = self.get_params_schema(tool_key)
+        if schema is None:
+            return []  # No schema ⇒ no validation errors
+
+        return self._validate_value(params, schema, path="params")
+
+    def _validate_value(
+        self, value: Any, schema: dict[str, Any], path: str
+    ) -> list[str]:
+        """Recursively validate a value against a JSON-Schema-like dict."""
+        errors: list[str] = []
+
+        # --- type ---
+        if "type" in schema:
+            expected = schema["type"]
+            if not self._type_matches(value, expected):
+                errors.append(f"{path}: expected type '{expected}', got {type(value).__name__}")
+                return errors  # No point checking further if type is wrong
+
+        # --- enum ---
+        if "enum" in schema and value not in schema["enum"]:
+            errors.append(f"{path}: value {value!r} not in enum {schema['enum']}")
+
+        # --- string constraints ---
+        if isinstance(value, str):
+            if "minLength" in schema and len(value) < schema["minLength"]:
+                errors.append(f"{path}: length {len(value)} < minLength {schema['minLength']}")
+            if "maxLength" in schema and len(value) > schema["maxLength"]:
+                errors.append(f"{path}: length {len(value)} > maxLength {schema['maxLength']}")
+            if "pattern" in schema and not re.search(schema["pattern"], value):
+                errors.append(f"{path}: value does not match pattern '{schema['pattern']}'")
+
+        # --- numeric constraints ---
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            if "minimum" in schema and value < schema["minimum"]:
+                errors.append(f"{path}: value {value} < minimum {schema['minimum']}")
+            if "maximum" in schema and value > schema["maximum"]:
+                errors.append(f"{path}: value {value} > maximum {schema['maximum']}")
+
+        # --- object: required + properties ---
+        if isinstance(value, dict):
+            if "required" in schema:
+                for req_key in schema["required"]:
+                    if req_key not in value:
+                        errors.append(f"{path}: missing required key '{req_key}'")
+
+            if "properties" in schema:
+                for prop_key, prop_schema in schema["properties"].items():
+                    if prop_key in value:
+                        errors.extend(
+                            self._validate_value(
+                                value[prop_key], prop_schema, path=f"{path}.{prop_key}"
+                            )
+                        )
+
+        # --- array: items ---
+        if isinstance(value, list) and "items" in schema:
+            for i, item in enumerate(value):
+                errors.extend(
+                    self._validate_value(item, schema["items"], path=f"{path}[{i}]")
+                )
+
+        return errors
+
+    @staticmethod
+    def _type_matches(value: Any, expected: str) -> bool:
+        """Check if a Python value matches a JSON Schema type string."""
+        type_map = {
+            "string": str,
+            "integer": int,
+            "number": (int, float),
+            "boolean": bool,
+            "object": dict,
+            "array": list,
+            "null": type(None),
+        }
+        py_type = type_map.get(expected)
+        if py_type is None:
+            return True  # Unknown type ⇒ permissive
+        # bool is a subtype of int in Python — exclude it for "integer"/"number"
+        if expected in ("integer", "number") and isinstance(value, bool):
+            return False
+        return isinstance(value, py_type)
+
+    # ------------------------------------------------------------------
+    # 1.4  Tool Constraints (e.g. URL allowlisting)
+    # ------------------------------------------------------------------
+
+    def get_constraints(self, tool_key: str) -> dict[str, Any] | None:
+        """Return the constraints dict for a tool, or None."""
+        meta = self.tools.get(tool_key)
+        if not meta:
+            return None
+        return meta.get("constraints")
+
+    def check_constraints(
+        self, tool_key: str, params: dict[str, Any]
+    ) -> list[str]:
+        """Check tool parameters against manifest constraints.
+
+        Currently supports:
+          - ``allowed_url_patterns``: list of glob patterns. Any param
+            value that looks like a URL (starts with ``http://`` or
+            ``https://``) is checked against these patterns.
+          - ``blocked_url_patterns``: list of glob patterns that are
+            explicitly denied.
+          - ``param_constraints``: per-parameter constraints with
+            ``allowed_values`` or ``pattern``.
+
+        Returns a list of violation strings (empty = OK).
+        """
+        constraints = self.get_constraints(tool_key)
+        if not constraints:
+            return []
+
+        violations: list[str] = []
+
+        # --- URL allowlisting ---
+        allowed_urls = constraints.get("allowed_url_patterns")
+        blocked_urls = constraints.get("blocked_url_patterns")
+
+        if allowed_urls or blocked_urls:
+            for param_key, param_val in params.items():
+                if isinstance(param_val, str) and (
+                    param_val.startswith("http://") or param_val.startswith("https://")
+                ):
+                    # Check blocked first
+                    if blocked_urls:
+                        for pattern in blocked_urls:
+                            if fnmatch.fnmatch(param_val, pattern):
+                                violations.append(
+                                    f"Parameter '{param_key}': URL '{param_val}' "
+                                    f"matches blocked pattern '{pattern}'"
+                                )
+
+                    # Check allowed (only if allowlist is defined)
+                    if allowed_urls:
+                        if not any(
+                            fnmatch.fnmatch(param_val, p) for p in allowed_urls
+                        ):
+                            violations.append(
+                                f"Parameter '{param_key}': URL '{param_val}' "
+                                f"does not match any allowed URL pattern"
+                            )
+
+        # --- Per-parameter constraints ---
+        param_constraints = constraints.get("param_constraints")
+        if param_constraints:
+            for param_key, pc in param_constraints.items():
+                if param_key not in params:
+                    continue
+                val = params[param_key]
+
+                if "allowed_values" in pc and val not in pc["allowed_values"]:
+                    violations.append(
+                        f"Parameter '{param_key}': value {val!r} "
+                        f"not in allowed_values {pc['allowed_values']}"
+                    )
+                if "pattern" in pc and isinstance(val, str):
+                    if not re.search(pc["pattern"], val):
+                        violations.append(
+                            f"Parameter '{param_key}': value does not match "
+                            f"pattern '{pc['pattern']}'"
+                        )
+
+        return violations

tollgate/tower.py

@@ -8,10 +8,14 @@ from .approvals import Approver, compute_request_hash
 from .audit import AuditSink
 from .exceptions import (
     TollgateApprovalDenied,
+    TollgateConstraintViolation,
     TollgateDeferred,
     TollgateDenied,
+    TollgateRateLimited,
 )
+from .grants import GrantStore
 from .policy import PolicyEvaluator
+from .registry import ToolRegistry
 from .types import (
     AgentContext,
     ApprovalOutcome,
@@ -25,21 +29,44 @@ from .types import (
 
 
 class ControlTower:
-    """Async-first control tower for tool execution enforcement."""
+    """Async-first control tower for tool execution enforcement.
+
+    Enforcement pipeline (in order):
+      0. Verify agent identity (if verify_fn configured)
+      0.5. Check circuit breaker (if circuit_breaker configured)   [2.1]
+      1. Check rate limits (if rate_limiter configured)
+      2. Evaluate policy
+      2.5. Check global network policy (if network_guard configured) [2.3]
+      3. Validate parameters against schema (if registry configured)
+      4. Check constraints (if registry configured)
+      5. Handle DENY / ASK / ALLOW
+      6. Execute tool → record success/failure in circuit breaker
+      7. Audit
+    """
 
     def __init__(
         self,
         policy: PolicyEvaluator,
         approver: Approver,
         audit: AuditSink,
-        grant_store: Any | None = None,
+        grant_store: GrantStore | None = None,
         redact_fn: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+        rate_limiter: Any | None = None,  # RateLimiter protocol
+        registry: ToolRegistry | None = None,
+        verify_fn: Callable[[AgentContext], bool] | None = None,
+        circuit_breaker: Any | None = None,  # CircuitBreaker protocol
+        network_guard: Any | None = None,  # NetworkGuard
     ):
         self.policy = policy
         self.approver = approver
         self.audit = audit
         self.grant_store = grant_store
         self.redact_fn = redact_fn or self._default_redact
+        self.rate_limiter = rate_limiter
+        self.registry = registry
+        self.verify_fn = verify_fn
+        self.circuit_breaker = circuit_breaker
+        self.network_guard = network_guard
 
     @staticmethod
     def _default_redact(params: dict[str, Any]) -> dict[str, Any]:
@@ -70,10 +97,147 @@ class ControlTower:
         correlation_id = str(uuid.uuid4())
         request_hash = compute_request_hash(agent_ctx, intent, tool_request)
 
-        # 1. Evaluate Policy
+        # 0. Verify agent identity (roadmap 1.6)
+        if self.verify_fn is not None:
+            if not self.verify_fn(agent_ctx):
+                decision = Decision(
+                    decision=DecisionType.DENY,
+                    reason="Agent identity verification failed.",
+                )
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    Outcome.BLOCKED,
+                )
+                raise TollgateDenied("Agent identity verification failed.")
+
+        # 0.5. Check circuit breaker (roadmap 2.1)
+        if self.circuit_breaker is not None:
+            cb_allowed, cb_reason = await self.circuit_breaker.before_call(
+                tool_request.tool, tool_request.action
+            )
+            if not cb_allowed:
+                decision = Decision(
+                    decision=DecisionType.DENY,
+                    reason=cb_reason or "Circuit breaker open.",
+                )
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    Outcome.BLOCKED,
+                )
+                raise TollgateDenied(cb_reason or "Circuit breaker open.")
+
+        # 1. Check rate limits (roadmap 1.2)
+        if self.rate_limiter is not None:
+            allowed, reason, retry_after = await self.rate_limiter.check_rate_limit(
+                agent_ctx, tool_request
+            )
+            if not allowed:
+                decision = Decision(
+                    decision=DecisionType.DENY,
+                    reason=reason or "Rate limit exceeded.",
+                )
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    Outcome.BLOCKED,
+                )
+                raise TollgateRateLimited(
+                    reason or "Rate limit exceeded.", retry_after
+                )
+
+        # 2. Evaluate Policy
         decision = self.policy.evaluate(agent_ctx, intent, tool_request)
 
-        # 2. Handle DENY
+        # 2.5. Check global network policy (roadmap 2.3)
+        if (
+            decision.decision != DecisionType.DENY
+            and self.network_guard is not None
+        ):
+            net_violations = self.network_guard.check(tool_request.params)
+            if net_violations:
+                deny_reason = (
+                    f"Network policy violation: {'; '.join(net_violations)}"
+                )
+                decision = Decision(
+                    decision=DecisionType.DENY,
+                    reason=deny_reason,
+                )
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    Outcome.BLOCKED,
+                )
+                raise TollgateConstraintViolation(deny_reason)
+
+        # 3. Validate parameters against schema (roadmap 1.1)
+        if (
+            decision.decision != DecisionType.DENY
+            and self.registry is not None
+        ):
+            schema_errors = self.registry.validate_params(
+                tool_request.tool, tool_request.params
+            )
+            if schema_errors:
+                deny_reason = (
+                    f"Parameter validation failed: {'; '.join(schema_errors)}"
+                )
+                decision = Decision(
+                    decision=DecisionType.DENY,
+                    reason=deny_reason,
+                )
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    Outcome.BLOCKED,
+                )
+                raise TollgateDenied(deny_reason)
+
+            # 3.5. Check per-tool constraints (roadmap 1.4)
+            constraint_violations = self.registry.check_constraints(
+                tool_request.tool, tool_request.params
+            )
+            if constraint_violations:
+                deny_reason = (
+                    f"Constraint violation: {'; '.join(constraint_violations)}"
+                )
+                decision = Decision(
+                    decision=DecisionType.DENY,
+                    reason=deny_reason,
+                )
+                self._log(
+                    correlation_id,
+                    request_hash,
+                    agent_ctx,
+                    intent,
+                    tool_request,
+                    decision,
+                    Outcome.BLOCKED,
+                )
+                raise TollgateConstraintViolation(deny_reason)
+
+        # 4. Handle DENY
         if decision.decision == DecisionType.DENY:
             self._log(
                 correlation_id,
@@ -86,15 +250,14 @@ class ControlTower:
             )
             raise TollgateDenied(decision.reason)
 
-        # 3. Handle ASK
+        # 5. Handle ASK
         if decision.decision == DecisionType.ASK:
-            # 3.1 Check Grants
+            # 5.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,
@@ -107,13 +270,12 @@ class ControlTower:
                     )
                     return result
 
-            # 3.2 Request Approval if no grant found
+            # 5.2 Request Approval if no grant found
             outcome = await self.approver.request_approval_async(
                 agent_ctx, intent, tool_request, request_hash, decision.reason
             )
 
             if outcome == ApprovalOutcome.DEFERRED:
-                # Audit the deferral
                 self._log(
                     correlation_id,
                     request_hash,
@@ -121,7 +283,7 @@ class ControlTower:
                     intent,
                     tool_request,
                     decision,
-                    Outcome.BLOCKED,  # Deferral is a temporary block
+                    Outcome.BLOCKED,
                 )
                 raise TollgateDeferred("pending")
 
@@ -142,7 +304,7 @@ class ControlTower:
                 )
                 raise TollgateApprovalDenied(f"Approval failed: {outcome.value}")
 
-        # 4. Execute tool (Policy ALLOW or Approval APPROVED)
+        # 6. Execute tool (Policy ALLOW or Approval APPROVED)
         return await self._execute_and_log(
             correlation_id,
             request_hash,
@@ -171,6 +333,11 @@ class ControlTower:
             result = await exec_async()
         except Exception as e:
             outcome = Outcome.FAILED
+            # Record failure in circuit breaker (roadmap 2.1)
+            if self.circuit_breaker is not None:
+                await self.circuit_breaker.record_failure(
+                    tool_request.tool, tool_request.action
+                )
             result_summary = self._sanitize_exception(e)
             self._log(
                 correlation_id,
@@ -185,6 +352,12 @@ class ControlTower:
             )
             raise
 
+        # Record success in circuit breaker (roadmap 2.1)
+        if self.circuit_breaker is not None:
+            await self.circuit_breaker.record_success(
+                tool_request.tool, tool_request.action
+            )
+
         # Final Audit
         result_summary = self._truncate_result(result)
         self._log(
@@ -269,7 +442,6 @@ class ControlTower:
 
     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:

tollgate/types.py

@@ -40,9 +40,27 @@ class AgentContext:
     version: str
     owner: str
     metadata: dict[str, Any] = field(default_factory=dict)
+    delegated_by: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def delegation_depth(self) -> int:
+        """Number of agents in the delegation chain (0 = direct call)."""
+        return len(self.delegated_by)
+
+    @property
+    def is_delegated(self) -> bool:
+        """Whether this agent was delegated to by another agent."""
+        return len(self.delegated_by) > 0
+
+    @property
+    def root_agent(self) -> str:
+        """The original (root) agent that started the delegation chain."""
+        return self.delegated_by[0] if self.delegated_by else self.agent_id
 
     def to_dict(self) -> dict[str, Any]:
-        return asdict(self)
+        d = asdict(self)
+        d["delegated_by"] = list(self.delegated_by)
+        return d
 
 
 @dataclass(frozen=True)
@@ -130,9 +148,11 @@ class AuditEvent:
     result_summary: str | None = None
     policy_version: str | None = None
     manifest_version: str | None = None
+    schema_version: str = "1.0"
 
     def to_dict(self) -> dict[str, Any]:
         return {
+            "schema_version": self.schema_version,
             "timestamp": self.timestamp,
             "correlation_id": self.correlation_id,
             "request_hash": self.request_hash,

tollgate/verification.py

@@ -0,0 +1,81 @@
+"""Agent identity verification via HMAC signing.
+
+Provides utilities to sign and verify AgentContext instances so that
+the ControlTower can trust agent_id claims are authentic.
+
+Usage:
+    from tollgate.verification import sign_agent_context, make_verifier
+
+    # At agent startup — sign the context
+    ctx = sign_agent_context(
+        AgentContext(agent_id="my-agent", version="1.0", owner="team-a"),
+        secret_key=b"shared-secret",
+    )
+
+    # At ControlTower — verify incoming contexts
+    tower = ControlTower(
+        policy=policy,
+        approver=approver,
+        audit=audit,
+        verify_fn=make_verifier(b"shared-secret"),
+    )
+"""
+
+import hashlib
+import hmac
+from dataclasses import replace
+from typing import Any
+
+from .types import AgentContext
+
+
+def _compute_signature(agent_ctx: AgentContext, secret_key: bytes) -> str:
+    """Compute HMAC-SHA256 over the canonical agent identity fields."""
+    payload = f"{agent_ctx.agent_id}|{agent_ctx.version}|{agent_ctx.owner}"
+    return hmac.new(secret_key, payload.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def sign_agent_context(
+    agent_ctx: AgentContext, secret_key: bytes
+) -> AgentContext:
+    """Return a new AgentContext with an HMAC signature in metadata.
+
+    The signature covers ``agent_id``, ``version``, and ``owner``.
+    It is stored under ``metadata["_signature"]``.
+    """
+    sig = _compute_signature(agent_ctx, secret_key)
+    new_meta: dict[str, Any] = {**agent_ctx.metadata, "_signature": sig}
+    return replace(agent_ctx, metadata=new_meta)
+
+
+def verify_agent_context(
+    agent_ctx: AgentContext, secret_key: bytes
+) -> bool:
+    """Verify that the AgentContext signature is valid.
+
+    Returns True if the signature matches, False otherwise.
+    Returns False if no signature is present.
+    """
+    sig = agent_ctx.metadata.get("_signature")
+    if not sig or not isinstance(sig, str):
+        return False
+    expected = _compute_signature(agent_ctx, secret_key)
+    return hmac.compare_digest(sig, expected)
+
+
+def make_verifier(
+    secret_key: bytes,
+) -> "callable[[AgentContext], bool]":
+    """Create a verification function suitable for ControlTower.verify_fn.
+
+    Example:
+        tower = ControlTower(
+            ...,
+            verify_fn=make_verifier(b"my-secret"),
+        )
+    """
+
+    def _verify(agent_ctx: AgentContext) -> bool:
+        return verify_agent_context(agent_ctx, secret_key)
+
+    return _verify