toolbound 0.2.0__py3-none-any.whl

toolbound/core/network.py

@@ -0,0 +1,267 @@
+"""Network policy: URL construction and target checks (SSRF defences).
+
+This module is pure: it never performs I/O. URL-level checks happen here for
+every request. IP-level checks (after DNS resolution) use :func:`check_ip` and
+are performed by the transport, because only the transport knows which address
+it actually connects to. The default :class:`~toolbound.SecureTransport`
+resolves the host, checks **every** address, and connects to the checked
+address, which defeats DNS rebinding between check and connect.
+
+Residual risk is documented in ``docs/security.md``: a library cannot see
+sidecar proxies, service meshes, or an upstream API that itself fetches URLs.
+Run agents with egress firewall rules when they sit next to sensitive networks.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any
+from urllib.parse import quote, urlencode, urlsplit
+
+from .contracts import NetworkPolicy, host_allowed
+from .errors import ErrorCode, NetworkBlocked, ToolFailure
+
+IPAddress = ipaddress.IPv4Address | ipaddress.IPv6Address
+
+_HOST_CHARS = re.compile(r"^[a-z0-9.-]+$")
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+_NAT64 = ipaddress.ip_network("64:ff9b::/96")
+_NAT64_LOCAL = ipaddress.ip_network("64:ff9b:1::/48")
+
+#: IANA special-purpose ranges that are never treated as public, independent of
+#: the running Python's ``ipaddress.is_global`` (whose answers changed across
+#: patch releases, e.g. CVE-2024-4032). Belt and braces with ``is_global``.
+_SPECIAL_PURPOSE = tuple(
+    ipaddress.ip_network(cidr)
+    for cidr in (
+        "0.0.0.0/8",
+        "10.0.0.0/8",
+        "100.64.0.0/10",
+        "127.0.0.0/8",
+        "169.254.0.0/16",
+        "172.16.0.0/12",
+        "192.0.0.0/24",
+        "192.0.2.0/24",
+        "192.88.99.0/24",
+        "192.168.0.0/16",
+        "198.18.0.0/15",
+        "198.51.100.0/24",
+        "203.0.113.0/24",
+        "224.0.0.0/4",
+        "240.0.0.0/4",
+        "::/128",
+        "::1/128",
+        "::ffff:0:0:0/96",
+        "64:ff9b:1::/48",
+        "100::/64",
+        "2001::/23",
+        "2001:db8::/32",
+        "3fff::/20",
+        "5f00::/16",
+        "fc00::/7",
+        "fe80::/10",
+        "fec0::/10",
+        "ff00::/8",
+    )
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Target:
+    """A URL that passed URL-level policy checks."""
+
+    url: str
+    scheme: str
+    host: str
+    port: int
+    is_ip_literal: bool
+
+    @property
+    def origin(self) -> tuple[str, str, int]:
+        return (self.scheme, self.host, self.port)
+
+
+def check_url(url: str, policy: NetworkPolicy) -> Target:
+    """Validate ``url`` against ``policy``. Raises :class:`NetworkBlocked`."""
+    if _CONTROL.search(url) or "\\" in url or " " in url:
+        raise NetworkBlocked("URL contains forbidden characters")
+    try:
+        parts = urlsplit(url)
+        port = parts.port
+    except ValueError as exc:
+        raise NetworkBlocked("URL could not be parsed") from exc
+    scheme = parts.scheme.lower()
+    if scheme == "http" and not policy.allow_http:
+        raise NetworkBlocked("plain HTTP is not allowed for this service")
+    if scheme not in ("http", "https"):
+        raise NetworkBlocked(f"scheme {scheme!r} is not allowed")
+    if "@" in parts.netloc or parts.username is not None or parts.password is not None:
+        raise NetworkBlocked("URLs with userinfo are not allowed")
+    host = (parts.hostname or "").rstrip(".")
+    if not host:
+        raise NetworkBlocked("URL has no host")
+    ip = _parse_ip_literal(host)
+    if ip is None:
+        try:
+            host = host.encode("idna").decode("ascii").lower()
+        except UnicodeError as exc:
+            raise NetworkBlocked("host name is not valid") from exc
+        if not _HOST_CHARS.match(host) or ".." in host:
+            raise NetworkBlocked("host name is not valid")
+        if _looks_numeric(host):
+            # "2130706433", "0x7f.1", "017700000001": resolvers may treat these as IPs.
+            raise NetworkBlocked("numeric host names are not allowed")
+    else:
+        host = str(ip)
+        check_ip(ip, policy)
+    if not host_allowed(host, policy):
+        raise NetworkBlocked(f"host {host!r} is not in the service allowlist")
+    effective_port = port if port is not None else (443 if scheme == "https" else 80)
+    if effective_port not in policy.allow_ports:
+        raise NetworkBlocked(f"port {effective_port} is not allowed")
+    return Target(url, scheme, host, effective_port, ip is not None)
+
+
+def _parse_ip_literal(host: str) -> IPAddress | None:
+    try:
+        return ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return None
+
+
+def _looks_numeric(host: str) -> bool:
+    labels = host.split(".")
+    return all(re.fullmatch(r"(0x[0-9a-f]*|[0-9]+)", label) for label in labels if label)
+
+
+@lru_cache(maxsize=256)
+def _networks(cidrs: tuple[str, ...]) -> tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...]:
+    return tuple(ipaddress.ip_network(c, strict=False) for c in cidrs)
+
+
+def _embedded_ipv4(ip: IPAddress) -> ipaddress.IPv4Address | None:
+    if isinstance(ip, ipaddress.IPv4Address):
+        return None
+    if ip.ipv4_mapped is not None:
+        return ip.ipv4_mapped
+    if ip.sixtofour is not None:
+        return ip.sixtofour
+    if ip.teredo is not None:
+        return ip.teredo[1]
+    if ip in _NAT64 or ip in _NAT64_LOCAL:
+        return ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
+    # Deprecated IPv4-compatible addresses (::a.b.c.d).
+    if int(ip) >> 32 == 0 and int(ip) > 1:
+        return ipaddress.IPv4Address(int(ip))
+    return None
+
+
+def is_public_ip(ip: IPAddress) -> bool:
+    """True if ``ip`` is a globally routable unicast address."""
+    embedded = _embedded_ipv4(ip)
+    if embedded is not None and not is_public_ip(embedded):
+        return False
+    if any(ip in net for net in _SPECIAL_PURPOSE if net.version == ip.version):
+        return False
+    return bool(ip.is_global) and not ip.is_multicast and not ip.is_unspecified
+
+
+def check_ip(ip: IPAddress | str, policy: NetworkPolicy) -> None:
+    """Raise :class:`NetworkBlocked` unless ``ip`` may be contacted under ``policy``.
+
+    Non-public addresses (loopback, private, link-local including cloud metadata,
+    CGNAT, ULA, multicast, reserved, and IPv4 embedded in IPv6) are blocked unless
+    they fall inside one of ``policy.allow_networks``.
+    """
+    address = ipaddress.ip_address(ip) if isinstance(ip, str) else ip
+    trusted = _networks(policy.allow_networks)
+    if any(address in net for net in trusted if net.version == address.version):
+        return
+    embedded = _embedded_ipv4(address)
+    if embedded is not None and any(embedded in net for net in trusted if net.version == 4):
+        return
+    if is_public_ip(address):
+        return
+    raise NetworkBlocked(f"address {address} is not a public address and is not allowlisted")
+
+
+# --------------------------------------------------------------------------- building
+
+
+def encode_path_param(name: str, value: Any) -> str:
+    """Encode one path parameter strictly. Raises ``invalid_arguments``."""
+    if isinstance(value, bool) or not isinstance(value, str | int | float):
+        raise ToolFailure(ErrorCode.INVALID_ARGUMENTS, f"{name}: path values must be scalars")
+    text = str(value)
+    if (
+        text == ""
+        or text in (".", "..")
+        or _CONTROL.search(text)
+        or any(c in text for c in "/\\?#")
+    ):
+        raise ToolFailure(
+            ErrorCode.INVALID_ARGUMENTS,
+            f"{name}: value is not allowed in a URL path segment",
+        )
+    lowered = text.lower()
+    if "%2e" in lowered or "%2f" in lowered or "%5c" in lowered:
+        raise ToolFailure(
+            ErrorCode.INVALID_ARGUMENTS,
+            f"{name}: encoded path separators are not allowed",
+        )
+    return quote(text, safe="")
+
+
+def build_url(
+    base_url: str,
+    path_template: str,
+    path_values: Mapping[str, Any],
+    query: Sequence[tuple[str, Any]],
+) -> str:
+    """Join trusted base URL and template with encoded values and query pairs."""
+    path = path_template
+    for name, value in path_values.items():
+        path = path.replace("{" + name + "}", encode_path_param(name, value))
+    base = urlsplit(base_url)
+    full_path = (base.path.rstrip("/") + path) if path != "/" else (base.path or "/")
+    url = f"{base.scheme}://{base.netloc}{full_path}"
+    pairs = _flatten_query(query)
+    if pairs:
+        url += "?" + urlencode(pairs, doseq=False)
+    built = urlsplit(url)
+    if built.netloc != base.netloc or not built.path.startswith(base.path.rstrip("/") or "/"):
+        raise NetworkBlocked("constructed URL escaped the service base URL")
+    return url
+
+
+def _flatten_query(query: Sequence[tuple[str, Any]]) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    for name, value in query:
+        if value is None:
+            continue
+        values = value if isinstance(value, list) else [value]
+        for item in values:
+            if isinstance(item, dict | list):
+                raise ToolFailure(
+                    ErrorCode.INVALID_ARGUMENTS, f"{name}: query values must be scalars"
+                )
+            if isinstance(item, bool):
+                out.append((name, "true" if item else "false"))
+            else:
+                out.append((name, str(item)))
+    return out
+
+
+def same_origin(a: str, b: str) -> bool:
+    pa, pb = urlsplit(a), urlsplit(b)
+    port_a = pa.port or (443 if pa.scheme == "https" else 80)
+    port_b = pb.port or (443 if pb.scheme == "https" else 80)
+    return (pa.scheme, (pa.hostname or "").lower(), port_a) == (
+        pb.scheme,
+        (pb.hostname or "").lower(),
+        port_b,
+    )

toolbound/core/observe.py

@@ -0,0 +1,60 @@
+"""Structured events for logging, metrics and tracing.
+
+Events carry identifiers, timings and outcomes only. Argument values, request
+bodies, response bodies and credentials are never included.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+logger = logging.getLogger("toolbound")
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """One observable step.
+
+    ``name`` is one of ``call.start``, ``call.end``, ``http.attempt``,
+    ``approval.required``, ``approval.granted``, ``policy.denied``,
+    ``network.blocked``, ``schema.warning``.
+    """
+
+    name: str
+    tool: str
+    actor: str
+    request_id: str
+    tenant: str | None = None
+    outcome: str | None = None
+    duration_ms: float | None = None
+    http_status: int | None = None
+    attempt: int | None = None
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+
+class NullObserver:
+    def on_event(self, event: Event) -> None:
+        return None
+
+
+class LoggingObserver:
+    """Logs events to the ``toolbound`` logger at INFO (failures at WARNING)."""
+
+    def __init__(self, log: logging.Logger | None = None) -> None:
+        self._log = log or logger
+
+    def on_event(self, event: Event) -> None:
+        level = logging.WARNING if event.outcome not in (None, "ok") else logging.INFO
+        self._log.log(
+            level,
+            "%s tool=%s actor=%s outcome=%s status=%s duration_ms=%s request_id=%s",
+            event.name,
+            event.tool,
+            event.actor,
+            event.outcome,
+            event.http_status,
+            None if event.duration_ms is None else round(event.duration_ms, 2),
+            event.request_id,
+        )

toolbound/core/paths.py

@@ -0,0 +1,138 @@
+"""A tiny, safe path language for selecting values from JSON.
+
+Grammar (no evaluation, no functions, no wildcards over keys)::
+
+    path     := "$" | step ( "." step )*
+    step     := name suffix* | suffix+
+    suffix   := "[]" | "[" integer "]"
+    name     := [A-Za-z0-9_\\-@:]+
+
+Examples: ``title``, ``user.login``, ``labels[].name``, ``items[0].id``,
+``[].id`` (each element of a root array), ``$`` (the whole document).
+
+Paths are parsed once at registration time. Evaluation is linear in the size of
+the selected data and can never execute code or reach outside the document.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Final
+
+from .errors import ConfigurationError
+
+
+class _Missing:
+    _instance: _Missing | None = None
+
+    def __new__(cls) -> _Missing:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+MISSING: Final = _Missing()
+"""Sentinel returned when a path does not exist in the document."""
+
+
+@dataclass(frozen=True, slots=True)
+class Key:
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class Index:
+    index: int
+
+
+@dataclass(frozen=True, slots=True)
+class Each:
+    pass
+
+
+Step = Key | Index | Each
+
+_NAME = re.compile(r"[A-Za-z0-9_\-@:]+")
+_SUFFIX = re.compile(r"\[(\d*)\]")
+_MAX_PATH_LENGTH = 256
+_MAX_STEPS = 32
+
+
+@dataclass(frozen=True, slots=True)
+class Path:
+    """A parsed, immutable path."""
+
+    text: str
+    steps: tuple[Step, ...]
+
+    @property
+    def is_root(self) -> bool:
+        return not self.steps
+
+    def get(self, data: Any) -> Any:
+        """Return the selected value, or :data:`MISSING`."""
+        return _walk(data, self.steps)
+
+    def __str__(self) -> str:
+        return self.text
+
+
+def parse_path(text: str) -> Path:
+    """Parse ``text`` into a :class:`Path`, raising :class:`ConfigurationError`."""
+    if not isinstance(text, str) or not text:
+        raise ConfigurationError("path must be a non-empty string")
+    if len(text) > _MAX_PATH_LENGTH:
+        raise ConfigurationError(f"path is longer than {_MAX_PATH_LENGTH} characters")
+    if text == "$":
+        return Path(text, ())
+    steps: list[Step] = []
+    for raw in text.split("."):
+        if not raw:
+            raise ConfigurationError(f"invalid path {text!r}: empty segment")
+        pos = 0
+        match = _NAME.match(raw)
+        if match:
+            steps.append(Key(match.group(0)))
+            pos = match.end()
+        elif not raw.startswith("["):
+            raise ConfigurationError(f"invalid path {text!r}: bad segment {raw!r}")
+        while pos < len(raw):
+            suffix = _SUFFIX.match(raw, pos)
+            if not suffix:
+                raise ConfigurationError(f"invalid path {text!r}: bad segment {raw!r}")
+            steps.append(Each() if suffix.group(1) == "" else Index(int(suffix.group(1))))
+            pos = suffix.end()
+    if len(steps) > _MAX_STEPS:
+        raise ConfigurationError(f"path {text!r} has more than {_MAX_STEPS} steps")
+    return Path(text, tuple(steps))
+
+
+def _walk(data: Any, steps: tuple[Step, ...]) -> Any:
+    current = data
+    for i, step in enumerate(steps):
+        if isinstance(step, Key):
+            if not isinstance(current, dict) or step.name not in current:
+                return MISSING
+            current = current[step.name]
+        elif isinstance(step, Index):
+            if not isinstance(current, list) or step.index >= len(current):
+                return MISSING
+            current = current[step.index]
+        else:
+            if not isinstance(current, list):
+                return MISSING
+            rest = steps[i + 1 :]
+            out = []
+            for item in current:
+                value = _walk(item, rest)
+                if value is not MISSING:
+                    out.append(value)
+            return out
+    return current

toolbound/core/ports.py

@@ -0,0 +1,166 @@
+"""Ports: the small interfaces through which the core talks to the outside world.
+
+Each port has a default implementation; replace any of them by passing your own
+object to :class:`~toolbound.Gateway`. All are plain :class:`typing.Protocol`
+types: no base class to inherit from, no registration.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from .contracts import NetworkPolicy
+
+if TYPE_CHECKING:
+    from .approval import PendingApproval
+    from .context import ExecutionContext
+    from .contracts import ToolSpec
+    from .observe import Event
+
+
+# --------------------------------------------------------------------------- transport
+
+
+@dataclass(frozen=True, slots=True)
+class HttpRequest:
+    """A fully built request that already passed URL-level policy checks."""
+
+    method: str
+    url: str
+    headers: tuple[tuple[str, str], ...]
+    body: bytes | None
+    network: NetworkPolicy
+    timeout: float
+    connect_timeout: float
+    max_response_bytes: int
+
+    def __repr__(self) -> str:
+        # Headers, body and query values can hold credentials: never print them.
+        base, _, query = self.url.partition("?")
+        names = sorted({k.lower() for k, _ in self.headers})
+        body = f"<{len(self.body)} bytes>" if self.body else None
+        return (
+            f"HttpRequest(method={self.method!r}, url={base + ('?…' if query else '')!r}, "
+            f"headers={names!r}, body={body})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+    """A bounded upstream response. ``headers`` keys are lower-case."""
+
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+    url: str
+    elapsed_ms: float = 0.0
+    extensions: Mapping[str, Any] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        return (
+            f"HttpResponse(status={self.status}, url={self.url.partition('?')[0]!r}, "
+            f"body=<{len(self.body)} bytes>)"
+        )
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Sends one HTTP request. Must not follow redirects (the core does that).
+
+    Production transports must enforce IP-level policy with
+    :func:`toolbound.core.network.check_ip` on the address they connect to, cap
+    the (decompressed) body at ``max_response_bytes`` and raise:
+
+    * :class:`toolbound.core.errors.NetworkBlocked` for policy violations,
+    * :class:`toolbound.core.errors.ToolFailure` with ``TIMEOUT``,
+      ``UPSTREAM_UNAVAILABLE`` or ``RESPONSE_TOO_LARGE`` for transport failures.
+    """
+
+    async def send(self, request: HttpRequest) -> HttpResponse: ...
+
+    async def aclose(self) -> None: ...
+
+
+# --------------------------------------------------------------------------- credentials
+
+
+@runtime_checkable
+class CredentialProvider(Protocol):
+    """Returns the secret value for a credential *name* (sync or async)."""
+
+    def get(self, name: str, ctx: ExecutionContext) -> str | Awaitable[str | None] | None: ...
+
+
+# --------------------------------------------------------------------------- policy
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizationRequest:
+    """What the authorizer sees: who, which tool, which validated arguments."""
+
+    ctx: ExecutionContext
+    tool: ToolSpec
+    arguments: Mapping[str, Any]
+    bound: Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """An authorization decision. ``reason`` is shown to the model when denied."""
+
+    allowed: bool
+    reason: str = "not permitted"
+
+    @classmethod
+    def allow(cls) -> Decision:
+        return cls(True, "")
+
+    @classmethod
+    def deny(cls, reason: str = "not permitted") -> Decision:
+        return cls(False, reason)
+
+
+class Authorizer(Protocol):
+    """Application-owned policy hook (sync or async), returning bool or Decision."""
+
+    def __call__(
+        self, request: AuthorizationRequest
+    ) -> bool | Decision | Awaitable[bool | Decision]: ...
+
+
+class Approver(Protocol):
+    """Inline human-approval hook (sync or async). Return True to approve."""
+
+    def __call__(self, pending: PendingApproval) -> bool | Awaitable[bool]: ...
+
+
+# --------------------------------------------------------------------------- utilities
+
+
+@runtime_checkable
+class TokenEstimator(Protocol):
+    """Estimates how many tokens a string uses for a model."""
+
+    def count(self, text: str) -> int: ...
+
+
+@runtime_checkable
+class Observer(Protocol):
+    """Receives structured events. Events never contain argument or body values."""
+
+    def on_event(self, event: Event) -> None: ...
+
+
+@runtime_checkable
+class StateStore(Protocol):
+    """Shared state for replay protection (single-use approvals, call-id dedupe).
+
+    The default is in-memory and per-process. For multiple workers, implement
+    ``claim`` on a shared store (for example Redis ``SET key 1 NX EX ttl``).
+    """
+
+    async def claim(self, key: str, ttl_seconds: float) -> bool:
+        """Atomically record ``key``. Return False if it was already present."""
+        ...