kade-agent-sdk 0.1.0__tar.gz

kade_agent_sdk-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.DS_Store
+
+# Local runtime data (results backend, load-test output)
+.data/
+.design/

kade_agent_sdk-0.1.0/LICENSE

@@ -0,0 +1,93 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+Required Notice: Copyright (c) 2026 TaskmasterGPT (https://taskmastergpt.nl)
+
+Licensor Line of Business: a marketplace that lists, bills and pays out AI agents and MCP servers sold per use, and the tools and SDKs for building agents for it.

kade_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: kade-agent-sdk
+Version: 0.1.0
+Summary: Creator SDK for Kade: verify gateway requests and report billable events
+Project-URL: Homepage, https://kade.taskmastergpt.nl/creators
+Project-URL: Documentation, https://kade.taskmastergpt.nl/docs/creator
+License-Expression: LicenseRef-PolyForm-Shield-1.0.0
+License-File: LICENSE
+Keywords: agents,fastmcp,kade,marketplace,mcp
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: <3.15,>=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: pyjwt[crypto]>=2.10
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=4.1; extra == 'fastmcp'
+Description-Content-Type: text/markdown
+
+# kade-agent-sdk
+
+Creator SDK for [Kade](https://kade.taskmastergpt.nl): verify that requests come from the Kade
+gateway, report billable events and answer data-subject (export/erase) requests.
+
+```bash
+uv add "kade-agent-sdk[fastmcp]"     # import name: marketplace_sdk
+```
+
+```python
+from fastmcp import FastMCP
+from marketplace_sdk import GatewayVerifier, gateway_claims, report_event
+from marketplace_sdk.fastmcp import MarketplaceMiddleware, add_data_subject_tools
+
+mcp = FastMCP("my-agent")
+verifier = GatewayVerifier(
+    jwks_url="https://kade.taskmastergpt.nl/.well-known/jwks.json",
+    issuer="https://mcp.kade.taskmastergpt.nl",
+    agent_id="agt_…",                       # from your creator console
+)
+mcp.add_middleware(MarketplaceMiddleware(verifier))
+
+@mcp.tool
+async def lookup(query: str) -> dict:
+    report_event("record_found", 3)          # billed at your event price, capped per call
+    return {"run_id": gateway_claims().run_id, "query": query}
+
+# Required to publish. Stateless agents:
+add_data_subject_tools(mcp, stores_no_user_data=True)
+# ...or, if you keep data per user (subject = pseudonymous `sub` from the gateway token):
+# add_data_subject_tools(mcp, erase=lambda s: db.delete(s), export=lambda s: db.records(s))
+
+app = mcp.http_app(path="/mcp")             # serve with uvicorn on HTTPS
+```
+
+- `GatewayVerifier` checks EdDSA signature (JWKS cached 1 h, `kid` rotation), `iss`, `aud =
+  agent:<agent_id>`, `exp` and `scope` (`call`, `register`, `verify`, `erase`, `export`).
+- `MarketplaceMiddleware` verifies every request, rejects `register` tokens on tool calls, tokens
+  issued for another tool and `erase`/`export` tokens outside the reserved tools, and merges
+  reported events into the result `_meta`.
+- `add_data_subject_tools` registers `kade_erase_subject` and `kade_export_subject`; Kade strips
+  them from your listing and calls them only with `scope=erase`/`export` (SPEC §7.5).
+- Not using FastMCP? Wrap your ASGI app in `marketplace_sdk.asgi.GatewayAuthMiddleware` and add
+  `billing_meta({"record_found": 3})` to your result `_meta`.
+- `gateway_claims().test` is true for creator test calls and verification runs (never billed).
+
+## License
+
+[PolyForm Shield 1.0.0](LICENSE). In short: use it, change it and ship it in your agents,
+including agents you sell on Kade; suggest changes to us. What it does not allow is offering the
+SDK, or a product built with it, that competes with it or with Kade, for example reselling the SDK
+or running a rival marketplace on it. This is a source-available license, not an OSI open-source
+license.

kade_agent_sdk-0.1.0/README.md

@@ -0,0 +1,53 @@
+# kade-agent-sdk
+
+Creator SDK for [Kade](https://kade.taskmastergpt.nl): verify that requests come from the Kade
+gateway, report billable events and answer data-subject (export/erase) requests.
+
+```bash
+uv add "kade-agent-sdk[fastmcp]"     # import name: marketplace_sdk
+```
+
+```python
+from fastmcp import FastMCP
+from marketplace_sdk import GatewayVerifier, gateway_claims, report_event
+from marketplace_sdk.fastmcp import MarketplaceMiddleware, add_data_subject_tools
+
+mcp = FastMCP("my-agent")
+verifier = GatewayVerifier(
+    jwks_url="https://kade.taskmastergpt.nl/.well-known/jwks.json",
+    issuer="https://mcp.kade.taskmastergpt.nl",
+    agent_id="agt_…",                       # from your creator console
+)
+mcp.add_middleware(MarketplaceMiddleware(verifier))
+
+@mcp.tool
+async def lookup(query: str) -> dict:
+    report_event("record_found", 3)          # billed at your event price, capped per call
+    return {"run_id": gateway_claims().run_id, "query": query}
+
+# Required to publish. Stateless agents:
+add_data_subject_tools(mcp, stores_no_user_data=True)
+# ...or, if you keep data per user (subject = pseudonymous `sub` from the gateway token):
+# add_data_subject_tools(mcp, erase=lambda s: db.delete(s), export=lambda s: db.records(s))
+
+app = mcp.http_app(path="/mcp")             # serve with uvicorn on HTTPS
+```
+
+- `GatewayVerifier` checks EdDSA signature (JWKS cached 1 h, `kid` rotation), `iss`, `aud =
+  agent:<agent_id>`, `exp` and `scope` (`call`, `register`, `verify`, `erase`, `export`).
+- `MarketplaceMiddleware` verifies every request, rejects `register` tokens on tool calls, tokens
+  issued for another tool and `erase`/`export` tokens outside the reserved tools, and merges
+  reported events into the result `_meta`.
+- `add_data_subject_tools` registers `kade_erase_subject` and `kade_export_subject`; Kade strips
+  them from your listing and calls them only with `scope=erase`/`export` (SPEC §7.5).
+- Not using FastMCP? Wrap your ASGI app in `marketplace_sdk.asgi.GatewayAuthMiddleware` and add
+  `billing_meta({"record_found": 3})` to your result `_meta`.
+- `gateway_claims().test` is true for creator test calls and verification runs (never billed).
+
+## License
+
+[PolyForm Shield 1.0.0](LICENSE). In short: use it, change it and ship it in your agents,
+including agents you sell on Kade; suggest changes to us. What it does not allow is offering the
+SDK, or a product built with it, that competes with it or with Kade, for example reselling the SDK
+or running a rival marketplace on it. This is a source-available license, not an OSI open-source
+license.

kade_agent_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "kade-agent-sdk"
+version = "0.1.0"
+description = "Creator SDK for Kade: verify gateway requests and report billable events"
+readme = "README.md"
+license = "LicenseRef-PolyForm-Shield-1.0.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.12,<3.15"
+keywords = ["kade", "mcp", "fastmcp", "agents", "marketplace"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "pyjwt[crypto]>=2.10",
+    "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://kade.taskmastergpt.nl/creators"
+Documentation = "https://kade.taskmastergpt.nl/docs/creator"
+
+[project.optional-dependencies]
+fastmcp = ["fastmcp>=4.1"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/marketplace_sdk"]

kade_agent_sdk-0.1.0/src/marketplace_sdk/__init__.py

@@ -0,0 +1,18 @@
+"""Kade creator SDK: verify gateway requests and report billable events.
+
+from marketplace_sdk import GatewayVerifier, report_event, gateway_claims
+from marketplace_sdk.fastmcp import MarketplaceMiddleware
+"""
+
+from marketplace_sdk.context import BILLING_META_KEY, billing_meta, gateway_claims, report_event
+from marketplace_sdk.verifier import GatewayClaims, GatewayVerifier, VerificationError
+
+__all__ = [
+    "BILLING_META_KEY",
+    "GatewayClaims",
+    "GatewayVerifier",
+    "VerificationError",
+    "billing_meta",
+    "gateway_claims",
+    "report_event",
+]

kade_agent_sdk-0.1.0/src/marketplace_sdk/asgi.py

@@ -0,0 +1,44 @@
+"""ASGI middleware for non-FastMCP servers: 401 unless the gateway JWT verifies; claims are
+available to handlers via `gateway_claims()`. Return events with `billing_meta(...)`."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from marketplace_sdk.context import begin_call, end_call
+from marketplace_sdk.verifier import GatewayVerifier, VerificationError
+
+
+class GatewayAuthMiddleware:
+    def __init__(self, app: Any, verifier: GatewayVerifier, path_prefix: str = "/mcp") -> None:
+        self.app = app
+        self.verifier = verifier
+        self.path_prefix = path_prefix
+
+    async def __call__(self, scope: dict, receive: Any, send: Any) -> None:
+        if scope["type"] != "http" or not scope["path"].startswith(self.path_prefix):
+            await self.app(scope, receive, send)
+            return
+        headers = {k.decode().lower(): v.decode() for k, v in scope.get("headers", [])}
+        try:
+            claims = self.verifier.verify_header(headers.get("authorization"))
+        except VerificationError as exc:
+            body = json.dumps({"error": "unauthorized", "detail": str(exc)}).encode()
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 401,
+                    "headers": [
+                        (b"content-type", b"application/json"),
+                        (b"www-authenticate", b'Bearer realm="kade"'),
+                    ],
+                }
+            )
+            await send({"type": "http.response.body", "body": body})
+            return
+        tokens = begin_call(claims)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            end_call(tokens)

kade_agent_sdk-0.1.0/src/marketplace_sdk/context.py

@@ -0,0 +1,57 @@
+"""Per-call context: verified gateway claims and accumulated billing events (contextvars)."""
+
+from __future__ import annotations
+
+import os
+import re
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from marketplace_sdk.verifier import GatewayClaims
+
+META_NS = os.environ.get("MARKETPLACE_META_NS", "nl.taskmastergpt.kade")
+BILLING_META_KEY = f"{META_NS}/billing"
+_EVENT_NAME = re.compile(r"^[a-z0-9_]{1,32}$")
+
+_claims: ContextVar[GatewayClaims | None] = ContextVar("marketplace_claims", default=None)
+_events: ContextVar[dict[str, int] | None] = ContextVar("marketplace_events", default=None)
+
+
+def gateway_claims() -> GatewayClaims | None:
+    """Claims of the gateway request being served (run_id, sub, max_cost_micros, test …)."""
+    return _claims.get()
+
+
+def report_event(name: str, count: int = 1) -> None:
+    """Record `count` billable events for this call. The gateway caps counts at your configured
+    `max_per_call` and ignores names you have not priced."""
+    if not _EVENT_NAME.match(name):
+        raise ValueError("event name must match ^[a-z0-9_]{1,32}$")
+    if count < 0:
+        raise ValueError("count must be >= 0")
+    events = _events.get()
+    if events is None:  # outside a gateway call (e.g. local tests): start a bucket
+        events = {}
+        _events.set(events)
+    events[name] = events.get(name, 0) + int(count)
+
+
+def billing_meta(events: dict[str, int] | list[dict[str, Any]]) -> dict[str, Any]:
+    """`_meta` fragment for a tool result, for servers not using the FastMCP middleware."""
+    if isinstance(events, dict):
+        items = [{"name": n, "count": c} for n, c in events.items() if c]
+    else:
+        items = [e for e in events if e.get("count")]
+    return {BILLING_META_KEY: {"events": items}}
+
+
+def begin_call(claims: GatewayClaims | None) -> tuple[Token, Token]:
+    return _claims.set(claims), _events.set({})
+
+
+def end_call(tokens: tuple[Token, Token]) -> dict[str, int]:
+    events = _events.get() or {}
+    _claims.reset(tokens[0])
+    _events.reset(tokens[1])
+    return events

kade_agent_sdk-0.1.0/src/marketplace_sdk/fastmcp.py

@@ -0,0 +1,131 @@
+"""FastMCP 4 middleware: verify the gateway JWT on every request, expose claims to tools, and
+merge `report_event` counts into the tool result `_meta`."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from fastmcp.exceptions import ToolError
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.base import ToolResult
+from mcp.shared.exceptions import MCPError
+
+from marketplace_sdk.context import BILLING_META_KEY, begin_call, end_call, gateway_claims
+from marketplace_sdk.verifier import GatewayVerifier, VerificationError
+
+UNAUTHORIZED = -32001
+ERASE_TOOL = "kade_erase_subject"
+EXPORT_TOOL = "kade_export_subject"
+DATA_SCOPES = {ERASE_TOOL: "erase", EXPORT_TOOL: "export"}
+
+
+class MarketplaceMiddleware(Middleware):
+    def __init__(self, verifier: GatewayVerifier, *, allow_unauthenticated_local: bool = False):
+        self.verifier = verifier
+        self.allow_unauthenticated_local = allow_unauthenticated_local
+
+    def _claims(self):  # noqa: ANN202
+        headers = get_http_headers(include_all=True)
+        auth = headers.get("authorization")
+        if not headers:  # in-process (stdio/memory) — no HTTP request at all
+            if self.allow_unauthenticated_local:
+                return None
+            raise MCPError(code=UNAUTHORIZED, message="gateway token required")
+        if auth is None and self.allow_unauthenticated_local:
+            return None
+        try:
+            return self.verifier.verify_header(auth)
+        except VerificationError as exc:
+            raise MCPError(code=UNAUTHORIZED, message=f"invalid gateway token: {exc}") from exc
+
+    async def on_request(self, context: MiddlewareContext, call_next: CallNext) -> Any:
+        if context.method in ("tools/call",):
+            return await call_next(context)  # verified in on_call_tool (needs tool name)
+        if context.method not in ("initialize", "ping", "server/discover"):
+            self._claims()
+        return await call_next(context)
+
+    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext) -> ToolResult:
+        claims = self._claims()
+        if claims is not None:
+            if claims.scope == "register":
+                raise MCPError(code=UNAUTHORIZED, message="register scope cannot call tools")
+            required = DATA_SCOPES.get(context.message.name)
+            if required and claims.scope != required:
+                raise MCPError(
+                    code=UNAUTHORIZED, message=f"{context.message.name} needs {required}"
+                )
+            if not required and claims.scope in ("erase", "export"):
+                raise MCPError(code=UNAUTHORIZED, message=f"{claims.scope} scope cannot call tools")
+            if claims.tool and claims.tool != context.message.name:
+                raise MCPError(code=UNAUTHORIZED, message="token was issued for another tool")
+        tokens = begin_call(claims)
+        try:
+            result = await call_next(context)
+        finally:
+            events = end_call(tokens)
+        if not events or result.is_error:
+            return result
+        meta = dict(result.meta or {})
+        meta[BILLING_META_KEY] = {
+            "events": [{"name": n, "count": c} for n, c in events.items() if c]
+        }
+        return ToolResult(
+            content=result.content,
+            structured_content=result.structured_content,
+            meta=meta,
+            is_error=result.is_error,
+        )
+
+
+DataFn = Callable[[str], Any]
+
+
+async def _maybe_await(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+def _subject(scope: str) -> str:
+    claims = gateway_claims()
+    if claims is None or claims.scope != scope:
+        raise ToolError(f"a gateway token with scope={scope} is required")
+    return claims.sub
+
+
+def add_data_subject_tools(
+    mcp: Any,
+    *,
+    erase: DataFn | None = None,
+    export: DataFn | None = None,
+    stores_no_user_data: bool = False,
+) -> None:
+    """Register Kade's reserved data-subject tools (required to publish).
+
+    - `erase(subject) -> bool`: delete everything stored for this pseudonymous subject; return
+      True if anything was deleted.
+    - `export(subject) -> list[dict]`: every record stored for this subject (JSON-serialisable).
+    - `stores_no_user_data=True`: the agent keeps nothing per user; both tools answer accordingly.
+
+    The subject always comes from the verified gateway token, never from arguments. Kade strips
+    these tools from your listing; consumers never see or call them.
+    """
+    if stores_no_user_data:
+        if erase or export:
+            raise ValueError("pass erase/export or stores_no_user_data=True, not both")
+    elif erase is None or export is None:
+        raise ValueError("provide both erase and export, or stores_no_user_data=True")
+
+    @mcp.tool(name=ERASE_TOOL, description="Kade data-subject erasure (platform only).")
+    async def kade_erase_subject(request_id: str) -> dict:
+        subject = _subject("erase")
+        deleted = False if stores_no_user_data else bool(await _maybe_await(erase(subject)))
+        return {"subject": subject, "status": "erased" if deleted else "nothing_stored"}
+
+    @mcp.tool(name=EXPORT_TOOL, description="Kade data-subject export (platform only).")
+    async def kade_export_subject(request_id: str) -> dict:
+        subject = _subject("export")
+        records = [] if stores_no_user_data else list(await _maybe_await(export(subject)))
+        return {"subject": subject, "records": records}

kade_agent_sdk-0.1.0/src/marketplace_sdk/verifier.py

@@ -0,0 +1,122 @@
+"""Gateway JWT verification: EdDSA (Ed25519), JWKS cached for 1 h, `kid` rotation."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+import jwt
+from jwt.algorithms import OKPAlgorithm
+
+ALLOWED_SCOPES = frozenset({"call", "register", "verify", "erase", "export"})
+
+
+class VerificationError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class GatewayClaims:
+    sub: str
+    scope: str
+    agent_id: str
+    run_id: str | None = None
+    tool: str | None = None
+    max_cost_micros: int | None = None
+    events: list[dict[str, Any]] = field(default_factory=list)
+    test: bool = False
+    raw: dict[str, Any] = field(default_factory=dict)
+
+
+class GatewayVerifier:
+    def __init__(
+        self,
+        *,
+        jwks_url: str,
+        issuer: str,
+        agent_id: str,
+        cache_seconds: int = 3600,
+        leeway_seconds: int = 30,
+        http_client: httpx.Client | None = None,
+        allowed_scopes: frozenset[str] = ALLOWED_SCOPES,
+    ) -> None:
+        self.jwks_url = jwks_url
+        self.issuer = issuer.rstrip("/")
+        self.agent_id = agent_id
+        self.cache_seconds = cache_seconds
+        self.leeway = leeway_seconds
+        self.allowed_scopes = allowed_scopes
+        self._http = http_client
+        self._keys: dict[str, Any] = {}
+        self._fetched_at = 0.0
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------ JWKS
+    def _fetch(self) -> None:
+        client = self._http or httpx.Client(timeout=10)
+        try:
+            resp = client.get(self.jwks_url)
+            resp.raise_for_status()
+            keys = {}
+            for jwk in resp.json().get("keys", []):
+                if jwk.get("kty") == "OKP" and jwk.get("crv") == "Ed25519" and jwk.get("kid"):
+                    keys[jwk["kid"]] = OKPAlgorithm.from_jwk(json.dumps(jwk))
+        finally:
+            if self._http is None:
+                client.close()
+        self._keys = keys
+        self._fetched_at = time.monotonic()
+
+    def _key(self, kid: str) -> Any:
+        with self._lock:
+            stale = time.monotonic() - self._fetched_at > self.cache_seconds
+            if stale or (kid not in self._keys and time.monotonic() - self._fetched_at > 10):
+                self._fetch()
+            key = self._keys.get(kid)
+        if key is None:
+            raise VerificationError(f"unknown signing key {kid!r}")
+        return key
+
+    # ------------------------------------------------------------ verify
+    def verify(self, token: str) -> GatewayClaims:
+        """Verify signature, issuer, audience (`agent:<agent_id>`), expiry and scope."""
+        if not token:
+            raise VerificationError("missing gateway token")
+        try:
+            header = jwt.get_unverified_header(token)
+            if header.get("alg") != "EdDSA":
+                raise VerificationError("unexpected algorithm")
+            claims = jwt.decode(
+                token,
+                self._key(str(header.get("kid"))),
+                algorithms=["EdDSA"],
+                audience=f"agent:{self.agent_id}",
+                issuer=self.issuer,
+                leeway=self.leeway,
+                options={"require": ["exp", "iat", "aud", "iss", "sub"]},
+            )
+        except jwt.PyJWTError as exc:
+            raise VerificationError(str(exc)) from exc
+        scope = claims.get("scope")
+        if scope not in self.allowed_scopes:
+            raise VerificationError(f"scope {scope!r} not allowed")
+        return GatewayClaims(
+            sub=claims["sub"],
+            scope=scope,
+            agent_id=self.agent_id,
+            run_id=claims.get("run_id"),
+            tool=claims.get("tool"),
+            max_cost_micros=claims.get("max_cost_micros"),
+            events=list(claims.get("events") or []),
+            test=bool(claims.get("test", False)),
+            raw=claims,
+        )
+
+    def verify_header(self, authorization: str | None) -> GatewayClaims:
+        if not authorization or not authorization.lower().startswith("bearer "):
+            raise VerificationError("missing bearer token")
+        return self.verify(authorization[7:].strip())