sealkeeper 0.1.0__py3-none-any.whl

sealkeeper/__init__.py

@@ -0,0 +1,37 @@
+"""Look up and verify SealKeeper SEALs, and gate calls on them."""
+
+from ._version import __version__
+from .client import AsyncSealKeeper, SealKeeper
+from .errors import BadTargetError, SealBroken, SealKeeperError, UnavailableError
+from .gate import BLOCK_CODES, PASS_CODES, Block, Gate, Pass
+from .lookup import Lookup
+from .seal import (
+    SEAL_BROKEN_REASONS,
+    SEAL_VERSIONS,
+    VerifiedSeal,
+    agent_id_from_did_key,
+    read_keys,
+    verify_with_keys,
+)
+
+__all__ = [
+    "BLOCK_CODES",
+    "PASS_CODES",
+    "SEAL_BROKEN_REASONS",
+    "SEAL_VERSIONS",
+    "AsyncSealKeeper",
+    "BadTargetError",
+    "Block",
+    "Gate",
+    "Lookup",
+    "Pass",
+    "SealBroken",
+    "SealKeeper",
+    "SealKeeperError",
+    "UnavailableError",
+    "VerifiedSeal",
+    "__version__",
+    "agent_id_from_did_key",
+    "read_keys",
+    "verify_with_keys",
+]

sealkeeper/_protocol.py

@@ -0,0 +1,277 @@
+"""The requests the clients send and how they read the answers.
+
+Pure functions and one small key cache. The sync and async clients only
+move bytes, so both read every answer the same way.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import unquote, urlsplit
+
+from ._version import __version__
+from .errors import BadTargetError, SealKeeperError, UnavailableError
+from .seal import DID_KEY_PREFIX, agent_id_from_did_key, is_agent_id
+
+MCP_URL = "https://api.sealkeeper.run/mcp"
+KEYS_URL = "https://sealkeeper.run/.well-known/seal.json"
+PAGE_ORIGIN = ("sealkeeper.run", "https")
+API_ORIGIN = ("api.sealkeeper.run", "https")
+MCP_PROTOCOL_VERSION = "2025-11-25"
+
+TIMEOUT_SECONDS = 5.0
+ANSWER_MAX_BYTES = 64 * 1024
+# How long a copy of the keys is used before it is fetched again.
+KEYS_MAX_AGE_SECONDS = 300
+
+# The longest line of server text an exception carries.
+_TEXT_MAX_CHARS = 500
+_SUFFIX = re.compile(r"[!-~]+(?: [!-~]+)*")
+_SUFFIX_MAX_CHARS = 128
+_PAGE_PATH = re.compile(r"/agents/([^/]+)(?:/([^/]+))?/?")
+_API_CARD_PATH = re.compile(r"/v1/agents/([A-Za-z0-9_-]{43})/card/?")
+_URL = re.compile(r"([A-Za-z][A-Za-z0-9+.-]*://)([^/?#]*)(.*)", re.DOTALL)
+_HTTP_URL = re.compile(r"https?://", re.IGNORECASE)
+
+
+def user_agent(suffix: str | None) -> str:
+    """sealkeeper-py/<version>, then suffix, such as a wrapper's own name."""
+    base = f"sealkeeper-py/{__version__}"
+    if suffix is None:
+        return base
+    if (
+        not isinstance(suffix, str)
+        or len(suffix) > _SUFFIX_MAX_CHARS
+        or not _SUFFIX.fullmatch(suffix)
+    ):
+        raise ValueError("user_agent_suffix must be printable ASCII words")
+    return f"{base} {suffix}"
+
+
+def mcp_headers(agent: str) -> dict[str, str]:
+    return {
+        "content-type": "application/json",
+        "accept": "application/json, text/event-stream",
+        "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+        "user-agent": agent,
+    }
+
+
+def keys_headers(agent: str) -> dict[str, str]:
+    return {"accept": "application/json", "user-agent": agent}
+
+
+def tool_call(name: str, arguments: Mapping[str, Any]) -> bytes:
+    """One stateless JSON-RPC tools/call, the whole request body."""
+    message = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "tools/call",
+        "params": {"name": name, "arguments": dict(arguments)},
+    }
+    return json.dumps(message, separators=(",", ":")).encode("utf-8")
+
+
+def retry_wait(status: int, headers: Mapping[str, str], attempt: int) -> float | None:
+    """The seconds to wait before the one retry of a 429, else None.
+
+    Only the first answer is retried, and only when Retry-After names
+    whole seconds no longer than the timeout.
+    """
+    if status != 429 or attempt > 0:
+        return None
+    value = headers.get("retry-after", "").strip()
+    if not value.isascii() or not value.isdigit():
+        return None
+    seconds = int(value)
+    return float(seconds) if seconds <= TIMEOUT_SECONDS else None
+
+
+def _short(text: str) -> str:
+    return text if len(text) <= _TEXT_MAX_CHARS else text[:_TEXT_MAX_CHARS] + "..."
+
+
+def _json(body: bytes) -> object:
+    try:
+        return json.loads(body.decode("utf-8"))
+    except (ValueError, RecursionError):
+        return None
+
+
+def _error_message(parsed: object) -> str:
+    error = parsed.get("error") if isinstance(parsed, dict) else None
+    message = error.get("message") if isinstance(error, dict) else None
+    return _short(message) if isinstance(message, str) else "no message"
+
+
+def read_answer(status: int, body: bytes) -> dict[str, Any]:
+    """The structuredContent of a tools/call answer, or the error it is.
+
+    A 429 or a 5xx is UnavailableError. A tool error is BadTargetError with
+    the server's line. Any other status, a JSON-RPC error or an answer
+    that is not a tool result is SealKeeperError.
+    """
+    if status == 429:
+        raise UnavailableError("SealKeeper is rate limiting this caller")
+    if status >= 500:
+        raise UnavailableError(f"SealKeeper answered HTTP {status}")
+    parsed = _json(body)
+    if status != 200:
+        raise SealKeeperError(
+            f"SealKeeper refused the request, HTTP {status}: {_error_message(parsed)}"
+        )
+    if not isinstance(parsed, dict):
+        raise SealKeeperError("SealKeeper's answer is not a JSON object")
+    if "error" in parsed:
+        raise SealKeeperError(f"SealKeeper answered an error: {_error_message(parsed)}")
+    result = parsed.get("result")
+    if not isinstance(result, dict):
+        raise SealKeeperError("SealKeeper's answer has no result")
+    if result.get("isError") is True:
+        raise BadTargetError(_first_text(result))
+    data = result.get("structuredContent")
+    if not isinstance(data, dict):
+        raise SealKeeperError("SealKeeper's answer has no structuredContent")
+    return data
+
+
+def _first_text(result: dict[str, Any]) -> str:
+    content = result.get("content")
+    if isinstance(content, list):
+        for item in content:
+            if isinstance(item, dict) and isinstance(item.get("text"), str):
+                return _short(item["text"])
+    return "SealKeeper refused the input"
+
+
+def read_keys_answer(status: int, body: bytes) -> object:
+    """The key document of a 200 answer. Anything else is UnavailableError."""
+    if status != 200:
+        raise UnavailableError(f"could not load the SealKeeper keys, HTTP {status}")
+    parsed = _json(body)
+    if parsed is None:
+        raise UnavailableError("the SealKeeper key document is not JSON")
+    return parsed
+
+
+def page_url(agent_id: str) -> str:
+    return f"https://sealkeeper.run/agents/{agent_id}"
+
+
+def own_url_id(target: str) -> tuple[bool, str | None]:
+    """Whether target is a SealKeeper page or API card URL, and its agent id.
+
+    A page is /agents/<first>/<name> or /agents/<id> on sealkeeper.run, a
+    card /v1/agents/<id>/card on api.sealkeeper.run. Only the id forms name
+    an id.
+    """
+    if not _HTTP_URL.match(target):
+        return False, None
+    try:
+        parts = urlsplit(target)
+        port = parts.port
+    except ValueError:
+        return False, None
+    origin = (parts.hostname, parts.scheme) if port in (None, 443) else None
+    path = parts.path
+    if origin == PAGE_ORIGIN:
+        page = _PAGE_PATH.fullmatch(path)
+        if page is None:
+            return False, None
+        first = unquote(page.group(1))
+        return True, first if page.group(2) is None and is_agent_id(first) else None
+    if origin == API_ORIGIN:
+        card = _API_CARD_PATH.fullmatch(path)
+        if card is None:
+            return False, None
+        return True, card.group(1) if is_agent_id(card.group(1)) else None
+    return False, None
+
+
+def trust_target(target: object) -> tuple[str, str | None]:
+    """What get_trust is sent for target, and the agent id target names.
+
+    A bare agent id goes as its page URL, and a did:key as the page URL of
+    the id it names. Every other target goes as given.
+    """
+    if not isinstance(target, str) or not target.strip():
+        raise BadTargetError("the target must be a non-empty string")
+    text = target.strip()
+    if text.startswith(DID_KEY_PREFIX):
+        agent_id = agent_id_from_did_key(text)
+        if agent_id is None:
+            raise BadTargetError("the target is not an Ed25519 did:key")
+        return page_url(agent_id), agent_id
+    if is_agent_id(text):
+        return page_url(text), text
+    return target, own_url_id(text)[1]
+
+
+def is_http_url(target: str) -> bool:
+    return _HTTP_URL.match(target.strip()) is not None
+
+
+def is_listed_url(target: str) -> bool:
+    """Whether target is an http or https URL other than SealKeeper's own."""
+    return is_http_url(target) and not own_url_id(target.strip())[0]
+
+
+def host_lowered(url: str) -> str:
+    """url with only its host in lower case, and an empty path read as /."""
+    match = _URL.fullmatch(url.strip())
+    if match is None:
+        return url
+    scheme, authority, rest = match.groups()
+    userinfo, at, host = authority.rpartition("@")
+    return f"{scheme}{userinfo}{at}{host.lower()}{rest or '/'}"
+
+
+def host_of(url: str) -> str | None:
+    try:
+        return urlsplit(url.strip()).hostname
+    except ValueError:
+        return None
+
+
+def verify_arguments(
+    seal: str, agent: str | None, at: datetime | str | None
+) -> dict[str, str]:
+    """verify_seal's arguments. A datetime at must carry its time zone."""
+    arguments = {"seal": seal}
+    if agent is not None:
+        arguments["agent"] = agent
+    if isinstance(at, datetime):
+        if at.tzinfo is None:
+            raise ValueError("at must carry its time zone")
+        utc = at.astimezone(timezone.utc)
+        arguments["at"] = (
+            utc.strftime("%Y-%m-%dT%H:%M:%S.") + f"{utc.microsecond // 1000:03d}Z"
+        )
+    elif at is not None:
+        arguments["at"] = at
+    return arguments
+
+
+class KeyCache:
+    """The last key document fetched, kid to x, and when it was fetched."""
+
+    def __init__(self) -> None:
+        self._keys: dict[str, str] = {}
+        self._fetched_at: float | None = None
+
+    def usable(self, kid: str, now: float) -> dict[str, str] | None:
+        """The keys while the copy is younger than five minutes and knows kid.
+
+        A copy dated after now counts as too old.
+        """
+        if self._fetched_at is None or kid not in self._keys:
+            return None
+        age = now - self._fetched_at
+        return self._keys if 0 <= age < KEYS_MAX_AGE_SECONDS else None
+
+    def store(self, keys: dict[str, str], now: float) -> None:
+        self._keys, self._fetched_at = keys, now

sealkeeper/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sealkeeper/client.py

@@ -0,0 +1,303 @@
+"""SealKeeper and AsyncSealKeeper, the two clients. They only do I/O.
+
+Every request and every answer goes through _protocol, and every SEAL
+through seal.verify_with_keys, so both clients behave the same.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from . import _protocol as p
+from .errors import SealBroken, SealKeeperError, UnavailableError
+from .lookup import Lookup, lookup_of, seal_to_check
+from .seal import (
+    DID_KEY_PREFIX,
+    VerifiedSeal,
+    agent_id_from_did_key,
+    is_agent_id,
+    read_keys,
+    seal_kid,
+    verify_with_keys,
+)
+
+Clock = Callable[[], float]
+_Answer = tuple[int, Mapping[str, str], bytes]
+
+
+def _expected_id(expected_agent_id: str) -> str:
+    """The raw agent id, from an agent id or its did:key."""
+    agent_id: object = expected_agent_id
+    if isinstance(agent_id, str) and agent_id.startswith(DID_KEY_PREFIX):
+        agent_id = agent_id_from_did_key(agent_id)
+    if not is_agent_id(agent_id):
+        raise ValueError("expected_agent_id must be an agent id or its did:key")
+    return agent_id
+
+
+def _keys_of(status: int, body: bytes) -> dict[str, str]:
+    try:
+        return read_keys(p.read_keys_answer(status, body))
+    except ValueError as error:
+        raise UnavailableError(f"could not use the SealKeeper keys, {error}") from None
+
+
+def _too_large() -> SealKeeperError:
+    return SealKeeperError(
+        f"SealKeeper's answer is larger than {p.ANSWER_MAX_BYTES} bytes"
+    )
+
+
+def _timed_out() -> UnavailableError:
+    return UnavailableError(
+        f"SealKeeper did not answer within {p.TIMEOUT_SECONDS} seconds"
+    )
+
+
+def _unreachable(error: Exception) -> UnavailableError:
+    return UnavailableError(f"could not reach SealKeeper, {type(error).__name__}")
+
+
+def _read_capped(chunks: Iterator[bytes], deadline: float) -> bytes:
+    body = bytearray()
+    for chunk in chunks:
+        body += chunk
+        if len(body) > p.ANSWER_MAX_BYTES:
+            raise _too_large()
+        if time.monotonic() > deadline:
+            raise _timed_out()
+    return bytes(body)
+
+
+async def _aread_capped(chunks: AsyncIterator[bytes], deadline: float) -> bytes:
+    body = bytearray()
+    async for chunk in chunks:
+        body += chunk
+        if len(body) > p.ANSWER_MAX_BYTES:
+            raise _too_large()
+        if time.monotonic() > deadline:
+            raise _timed_out()
+    return bytes(body)
+
+
+class SealKeeper:
+    """Reads trust from SealKeeper and verifies SEALs, one blocking call each.
+
+    http_client is an httpx.Client to send through, for a caller's own
+    transport or a test. One is made and closed with the client when none
+    is given. clock answers Unix seconds and decides whether a SEAL is
+    current. user_agent_suffix is added to the User-Agent, such as
+    "langchain-sealkeeper/0.1.0". sleep waits before the one retry of a 429.
+    """
+
+    def __init__(
+        self,
+        *,
+        http_client: httpx.Client | None = None,
+        clock: Clock | None = None,
+        user_agent_suffix: str | None = None,
+        sleep: Callable[[float], None] | None = None,
+    ) -> None:
+        agent = p.user_agent(user_agent_suffix)
+        self._mcp_headers = p.mcp_headers(agent)
+        self._keys_headers = p.keys_headers(agent)
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client()
+        self.clock: Clock = clock if clock is not None else time.time
+        self._sleep = sleep if sleep is not None else time.sleep
+        self._keys = p.KeyCache()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> SealKeeper:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def get_trust(self, target: str) -> dict[str, Any]:
+        """get_trust's answer for a handle, a URL, an agent id or a did:key.
+
+        The answer as SealKeeper sends it. Its agent fields are unsigned,
+        so a decision reads lookup instead.
+        """
+        return self._call("get_trust", {"agent": p.trust_target(target)[0]})
+
+    def verify_seal(
+        self, seal: str, agent: str | None = None, at: datetime | str | None = None
+    ) -> dict[str, Any]:
+        """SealKeeper's own check of a SEAL, with its record of holds.
+
+        agent is the agent id expected, at a time to check at in place of
+        now. The answer as SealKeeper sends it.
+        """
+        return self._call("verify_seal", p.verify_arguments(seal, agent, at))
+
+    def verify(self, seal: str, expected_agent_id: str) -> VerifiedSeal:
+        """Verifies a SEAL here, against SealKeeper's published keys.
+
+        Raises SealBroken with the reason, or UnavailableError when the keys
+        cannot be had and no copy younger than five minutes knows the kid.
+        """
+        expected = _expected_id(expected_agent_id)
+        now = self.clock()
+        kid = seal_kid(seal)
+        keys = self._keys.usable(kid, now)
+        if keys is None:
+            status, _, body = self._send("GET", p.KEYS_URL, None, self._keys_headers)
+            keys = _keys_of(status, body)
+            self._keys.store(keys, now)
+        return verify_with_keys(seal, keys, now, expected)
+
+    def lookup(self, target: str) -> Lookup:
+        """get_trust for target, with the SEAL in its answer verified here."""
+        argument, named_id = p.trust_target(target)
+        answer = self._call("get_trust", {"agent": argument})
+        check = seal_to_check(answer, named_id)
+        if check is None:
+            return lookup_of(answer, None, None)
+        try:
+            return lookup_of(answer, self.verify(*check), None)
+        except SealBroken as error:
+            return lookup_of(answer, None, error.reason)
+
+    def _call(self, name: str, arguments: Mapping[str, Any]) -> dict[str, Any]:
+        body = p.tool_call(name, arguments)
+        attempt = 0
+        while True:
+            status, headers, answer = self._send(
+                "POST", p.MCP_URL, body, self._mcp_headers
+            )
+            wait = p.retry_wait(status, headers, attempt)
+            if wait is None:
+                return p.read_answer(status, answer)
+            self._sleep(wait)
+            attempt += 1
+
+    def _send(
+        self, method: str, url: str, body: bytes | None, headers: dict[str, str]
+    ) -> _Answer:
+        deadline = time.monotonic() + p.TIMEOUT_SECONDS
+        try:
+            with self._http.stream(
+                method,
+                url,
+                content=body,
+                headers=headers,
+                timeout=p.TIMEOUT_SECONDS,
+                follow_redirects=False,
+            ) as response:
+                data = _read_capped(response.iter_bytes(), deadline)
+                return response.status_code, response.headers, data
+        except httpx.TimeoutException:
+            raise _timed_out() from None
+        except httpx.TransportError as error:
+            raise _unreachable(error) from None
+
+
+class AsyncSealKeeper:
+    """SealKeeper with every call awaited, the same methods and answers.
+
+    http_client is an httpx.AsyncClient. sleep is awaited before the one
+    retry of a 429, asyncio.sleep unless another is given.
+    """
+
+    def __init__(
+        self,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        clock: Clock | None = None,
+        user_agent_suffix: str | None = None,
+        sleep: Callable[[float], Awaitable[None]] | None = None,
+    ) -> None:
+        agent = p.user_agent(user_agent_suffix)
+        self._mcp_headers = p.mcp_headers(agent)
+        self._keys_headers = p.keys_headers(agent)
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        self.clock: Clock = clock if clock is not None else time.time
+        self._sleep = sleep if sleep is not None else asyncio.sleep
+        self._keys = p.KeyCache()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSealKeeper:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()
+
+    async def get_trust(self, target: str) -> dict[str, Any]:
+        return await self._call("get_trust", {"agent": p.trust_target(target)[0]})
+
+    async def verify_seal(
+        self, seal: str, agent: str | None = None, at: datetime | str | None = None
+    ) -> dict[str, Any]:
+        return await self._call("verify_seal", p.verify_arguments(seal, agent, at))
+
+    async def verify(self, seal: str, expected_agent_id: str) -> VerifiedSeal:
+        expected = _expected_id(expected_agent_id)
+        now = self.clock()
+        kid = seal_kid(seal)
+        keys = self._keys.usable(kid, now)
+        if keys is None:
+            status, _, body = await self._send(
+                "GET", p.KEYS_URL, None, self._keys_headers
+            )
+            keys = _keys_of(status, body)
+            self._keys.store(keys, now)
+        return verify_with_keys(seal, keys, now, expected)
+
+    async def lookup(self, target: str) -> Lookup:
+        argument, named_id = p.trust_target(target)
+        answer = await self._call("get_trust", {"agent": argument})
+        check = seal_to_check(answer, named_id)
+        if check is None:
+            return lookup_of(answer, None, None)
+        try:
+            return lookup_of(answer, await self.verify(*check), None)
+        except SealBroken as error:
+            return lookup_of(answer, None, error.reason)
+
+    async def _call(self, name: str, arguments: Mapping[str, Any]) -> dict[str, Any]:
+        body = p.tool_call(name, arguments)
+        attempt = 0
+        while True:
+            status, headers, answer = await self._send(
+                "POST", p.MCP_URL, body, self._mcp_headers
+            )
+            wait = p.retry_wait(status, headers, attempt)
+            if wait is None:
+                return p.read_answer(status, answer)
+            await self._sleep(wait)
+            attempt += 1
+
+    async def _send(
+        self, method: str, url: str, body: bytes | None, headers: dict[str, str]
+    ) -> _Answer:
+        deadline = time.monotonic() + p.TIMEOUT_SECONDS
+        try:
+            async with self._http.stream(
+                method,
+                url,
+                content=body,
+                headers=headers,
+                timeout=p.TIMEOUT_SECONDS,
+                follow_redirects=False,
+            ) as response:
+                data = await _aread_capped(response.aiter_bytes(), deadline)
+                return response.status_code, response.headers, data
+        except httpx.TimeoutException:
+            raise _timed_out() from None
+        except httpx.TransportError as error:
+            raise _unreachable(error) from None

sealkeeper/errors.py

@@ -0,0 +1,23 @@
+"""The exceptions the library raises. Every one is a SealKeeperError."""
+
+from __future__ import annotations
+
+
+class SealKeeperError(Exception):
+    """SealKeeper answered something this library cannot use."""
+
+
+class BadTargetError(SealKeeperError):
+    """SealKeeper refused the target or the input, with its line saying why."""
+
+
+class UnavailableError(SealKeeperError):
+    """SealKeeper could not be reached, timed out or asked to slow down."""
+
+
+class SealBroken(SealKeeperError):
+    """A SEAL that did not verify. reason is one of SEAL_BROKEN_REASONS."""
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(f"broken SEAL: {reason}")
+        self.reason = reason