asap-protocol 2.4.1__tar.gz → 2.5.0__tar.gz

{asap_protocol-2.4.1 → asap_protocol-2.5.0}/CHANGELOG.md

@@ -12,7 +12,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `extra="forbid"` on ingress payload models (`TaskRequestConfig`, `CommonMetadata`)
 - Opt-in protection for operator APIs (`/usage`, `/sla`, `/audit`)
 - Redis-backed `JtiReplayCache` and distributed Next.js rate limits
-- Bump optional `pydantic-ai` extra (CVE-2026-46678)
+- `@asap-protocol/mcp-auth` HTTP/SSE middleware (deferred from v2.5.0 — see [2.5.0] TypeScript note and [typescript-mcp-auth-spike.md](engineering/tasks/v2.5.0/typescript-mcp-auth-spike.md))
+
+### Fixed
+
+- **CI security (`pip-audit`)**: Raised `cryptography` to `>=48.0.1,<49` (GHSA-537c-gmf6-5ccf), `python-multipart>=0.0.31` (CVE-2026-53538–53540), and `starlette>=1.3.1` (CVE-2026-54282 / CVE-2026-54283) via `pyproject.toml` floors and `tool.uv.override-dependencies`.
+- **pydantic-ai (CVE-2026-46678)**: Optional `[pydanticai]` extra pins `pydantic-ai>=1.99.0`; removed obsolete `pip-audit` ignore from CI.
+
+---
+
+## [2.5.0] - 2026-06-24
+
+**MCP Auth Bridge** — ASAP Host/Agent JWT and capability grants as an **opt-in**
+authorization layer for native **stdio MCP** `tools/call` (Mode A). Unprotected
+`MCPServer` usage is unchanged. No wire-protocol or manifest schema breaking
+changes.
+
+### Added
+
+- **feat(adapters): MCP Auth Bridge (`asap.adapters.mcp`)**
+  - **`protect_server(server, config)`** — wraps `MCPServer` via
+    `ProtectedMCPServer`; intercepts `_handle_tools_call` only (MCP-AUTH-006).
+  - **`MCPAuthConfig`** (`config.py`) — `host_store`, `agent_store`,
+    `capability_registry`, `tool_capability_map`, `public_tools`,
+    `enforce_grants`, `jwt_extractor`, `jti_replay_cache`, `expected_audience`.
+  - **Token carriage (stdio)** — Agent JWT in `tools/call` params
+    `_meta.asap_agent_jwt`; optional dev-only `ASAP_AGENT_JWT` when
+    `allow_env_jwt_fallback=True`.
+  - **Grant enforcement** — `verify_agent_jwt` + `CapabilityRegistry.check_grant`
+    with constraint validation on tool arguments; MCP-safe `asap:*` error codes
+    (`asap:auth_required`, `asap:invalid_token`, `asap:capability_denied`,
+    `asap:constraint_violation`).
+  - **Tool → capability mapping** — explicit `tool_capability_map`, register-time
+    metadata, or default identity (tool name == capability); optional startup
+    validation (`validate_tools_at_startup`).
+  - **Reference example** — `examples/mcp_auth_bridge/` (protected stdio server +
+    client, smoke tests in `tests/examples/test_mcp_auth_bridge_example.py`).
+  - **Docs** — [MCP Auth Bridge adapter](docs/adapters/mcp-auth-bridge.md);
+    [MCP integration](docs/mcp-integration.md) distinguishes Mode A (native MCP +
+    bridge) vs Mode B (MCP-over-ASAP envelope).
+- **feat(compliance): `mcp-auth-bridge` profile** (`asap-compliance`) — stdio MCP
+  release gate: auth paths, grants, constraints, manifest tools ⊆ registered
+  tools (MCP-DISC-003). Requires `asap-protocol>=2.5.0`.
+- **test(adapters/mcp)** — unit, grant, startup, and stdio integration coverage
+  (≥90% on `asap.adapters.mcp`).
+
+### Deferred (not in v2.5.0)
+
+- **`hide_unauthorized_tools` / `tools/list` filtering** (MCP-MAP-004) — no
+  standard JWT carriage on stdio `tools/list` today; see
+  [design lock](engineering/tasks/v2.5.0/design-lock-mcp-auth-bridge.md).
+- **`initialize` session-token handshake** (PRD §4.3 SHOULD) — clients pass JWT
+  on each protected `tools/call` in v2.5.0.
+
+### TypeScript
+
+- **`@asap-protocol/mcp-auth` deferred to v2.5.0.1** — MCP-TS-001..003 (HTTP/SSE
+  Bearer middleware) are SHOULD-scope; v2.5.0 ships the Python stdio bridge as the
+  release gate. Rationale and implementation checklist:
+  [typescript-mcp-auth-spike.md](engineering/tasks/v2.5.0/typescript-mcp-auth-spike.md);
+  carry-over tracked in
+  [PRD v2.5.1 §3](product/prd/prd-v2.5.1-adapter-lab-ii.md#3-carry-over-from-v250-asap-protocolmcp-auth).
+  Existing `@asap-protocol/*` npm packages remain at **2.4.1** until a separate
+  publish.
+
+### Migration
+
+- **v2.4.1 → v2.5.0**: **No breaking changes.** MCP servers without
+  `protect_server` behave as before. To enforce Agent JWT + capabilities on native
+  MCP, wrap your server with `protect_server` and configure grants — see
+  [MCP Auth Bridge adapter](docs/adapters/mcp-auth-bridge.md).
 
 ---
 

{asap_protocol-2.4.1 → asap_protocol-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asap-protocol
-Version: 2.4.1
+Version: 2.5.0
 Summary: Async Simple Agent Protocol - A streamlined protocol for agent-to-agent communication
 Project-URL: Homepage, https://github.com/adriannoes/asap-protocol
 Project-URL: Documentation, https://adriannoes.github.io/asap-protocol
@@ -23,7 +23,7 @@ Requires-Python: >=3.13
 Requires-Dist: aiosqlite>=0.20
 Requires-Dist: authlib<2,>=1.6.12
 Requires-Dist: brotli>=1.2.0
-Requires-Dist: cryptography<47,>=46.0.7
+Requires-Dist: cryptography<49,>=48.0.1
 Requires-Dist: fastapi>=0.136.1
 Requires-Dist: httpx[http2]>=0.28.1
 Requires-Dist: jcs>=0.2.0
@@ -95,7 +95,7 @@ Description-Content-Type: text/markdown
 
 > A production-ready protocol for agent-to-agent communication and task coordination.
 
-**Quick Info**: `v2.4.1` (PyPI) · **npm TS [`2.4.1`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.4.1)** | `Apache 2.0` | `Python 3.13+` | [Documentation](https://github.com/adriannoes/asap-protocol/blob/main/docs/index.md) | **[PyPI `asap-protocol`](https://pypi.org/project/asap-protocol/)** | **[npm `@asap-protocol/client`](https://www.npmjs.com/package/@asap-protocol/client)** | [Changelog](https://github.com/adriannoes/asap-protocol/blob/main/CHANGELOG.md)
+**Quick Info**: `v2.5.0` (release branch; PyPI/npm publish on `v2.5.0` tag) · **npm TS [`2.4.1`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.4.1)** (latest published) | `Apache 2.0` | `Python 3.13+` | [Documentation](https://github.com/adriannoes/asap-protocol/blob/main/docs/index.md) | **[PyPI `asap-protocol`](https://pypi.org/project/asap-protocol/)** | **[npm `@asap-protocol/client`](https://www.npmjs.com/package/@asap-protocol/client)** | [Changelog](https://github.com/adriannoes/asap-protocol/blob/main/CHANGELOG.md)
 
 > 📦 Install the ASAP **Python SDK / protocol** from **`https://pypi.org/project/asap-protocol/`** — package name **`asap-protocol`** on [PyPI](https://pypi.org/project/asap-protocol/).
 
@@ -176,10 +176,10 @@ uv run python -m asap.examples.run_demo
 uv run pytest -n auto --tb=short
 ```
 
-With coverage:
+With coverage (separate run — do not combine with `-n auto`):
 
 ```bash
-uv run pytest --cov=src --cov-report=term-missing
+uv run pytest --tb=short --cov=asap --cov-report=term-missing --cov-fail-under=85
 ```
 
 [Testing Guide](https://github.com/adriannoes/asap-protocol/blob/main/docs/testing.md) (structure, fixtures, property/load/chaos tests). [Contributing](https://github.com/adriannoes/asap-protocol/blob/main/CONTRIBUTING.md) (dev setup, CI).

{asap_protocol-2.4.1 → asap_protocol-2.5.0}/README.md

@@ -7,7 +7,7 @@
 
 > A production-ready protocol for agent-to-agent communication and task coordination.
 
-**Quick Info**: `v2.4.1` (PyPI) · **npm TS [`2.4.1`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.4.1)** | `Apache 2.0` | `Python 3.13+` | [Documentation](https://github.com/adriannoes/asap-protocol/blob/main/docs/index.md) | **[PyPI `asap-protocol`](https://pypi.org/project/asap-protocol/)** | **[npm `@asap-protocol/client`](https://www.npmjs.com/package/@asap-protocol/client)** | [Changelog](https://github.com/adriannoes/asap-protocol/blob/main/CHANGELOG.md)
+**Quick Info**: `v2.5.0` (release branch; PyPI/npm publish on `v2.5.0` tag) · **npm TS [`2.4.1`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.4.1)** (latest published) | `Apache 2.0` | `Python 3.13+` | [Documentation](https://github.com/adriannoes/asap-protocol/blob/main/docs/index.md) | **[PyPI `asap-protocol`](https://pypi.org/project/asap-protocol/)** | **[npm `@asap-protocol/client`](https://www.npmjs.com/package/@asap-protocol/client)** | [Changelog](https://github.com/adriannoes/asap-protocol/blob/main/CHANGELOG.md)
 
 > 📦 Install the ASAP **Python SDK / protocol** from **`https://pypi.org/project/asap-protocol/`** — package name **`asap-protocol`** on [PyPI](https://pypi.org/project/asap-protocol/).
 
@@ -88,10 +88,10 @@ uv run python -m asap.examples.run_demo
 uv run pytest -n auto --tb=short
 ```
 
-With coverage:
+With coverage (separate run — do not combine with `-n auto`):
 
 ```bash
-uv run pytest --cov=src --cov-report=term-missing
+uv run pytest --tb=short --cov=asap --cov-report=term-missing --cov-fail-under=85
 ```
 
 [Testing Guide](https://github.com/adriannoes/asap-protocol/blob/main/docs/testing.md) (structure, fixtures, property/load/chaos tests). [Contributing](https://github.com/adriannoes/asap-protocol/blob/main/CONTRIBUTING.md) (dev setup, CI).

{asap_protocol-2.4.1 → asap_protocol-2.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "asap-protocol"
-version = "2.4.1"
+version = "2.5.0"
 description = "Async Simple Agent Protocol - A streamlined protocol for agent-to-agent communication"
 authors = [
     {name = "ASAP Protocol Contributors"}
@@ -23,7 +23,7 @@ classifiers = [
 dependencies = [
     "aiosqlite>=0.20",
     # Upper-bound majors per SECURITY.md dependency policy.
-    "cryptography>=46.0.7,<47",
+    "cryptography>=48.0.1,<49",
     "jcs>=0.2.0",
     "jsonschema>=4.23.0",
     "pydantic>=2.12.5,<3",
@@ -121,17 +121,20 @@ Issues = "https://github.com/adriannoes/asap-protocol/issues"
 # - zeroconf>=0.149.5 for CVE-2026-47180/47183/47184 ([dns-sd] extra)
 # - pyasn1>=0.6.3 for CVE-2026-30922 (DoS via unbounded recursion)
 # - tinytag>=2.2.1 for CVE-2026-32889
-# - cryptography>=46.0.7 for CVE-2026-39892 / CVE-2026-34073 (name-constraint / peer identity)
+# - cryptography>=48.0.1 for GHSA-537c-gmf6-5ccf (CVE-2026-39892 / CVE-2026-34073 baseline at 46.0.7)
 # - requests>=2.33.0 for CVE-2026-25645 (extract_zipped_paths temp file)
 # - pillow>=12.2.0 for CVE-2026-40192 (transitive, e.g. pdf/vision stacks)
 # - pytest>=9.0.3 for CVE-2025-71176 (dev)
-# - python-multipart>=0.0.27 for CVE-2026-42561 / CVE-2026-40347 (FastAPI stack)
+# - python-multipart>=0.0.31 for CVE-2026-53538–53540 (FastAPI stack; prior floor 0.0.27)
+# - starlette>=1.3.1 for CVE-2026-54282 / CVE-2026-54283 (FastAPI stack)
 # - pygments>=2.20.0 for CVE-2026-4539
-# - langsmith>=0.8.0 for CVE-2026-45134 (prior: GHSA-rr7j-v2q5-chgv)
+# - langsmith>=0.8.18 for GHSA-f4xh-w4cj-qxq8 (prior: CVE-2026-45134 at >=0.8.0)
 # - langchain-core>=1.3.3 for CVE-2026-44843
 # - urllib3>=2.7.0 for CVE-2026-44431 / CVE-2026-44432
 # - pip>=26.1.2 for PYSEC-2026-196 (CVE-2026-6357 baseline at 26.1)
 # - python-dotenv>=1.2.2 for CVE-2026-28684 (transitive, e.g. pydantic-settings / uvicorn stacks)
+# - pydantic-settings>=2.14.2 for GHSA-4xgf-cpjx-pc3j (transitive, e.g. langchain / mcp stacks)
+# - msgpack>=1.2.1 for GHSA-6v7p-g79w-8964 (transitive, e.g. locust / cache stacks)
 # - idna>=3.15 for CVE-2026-45409 (DoS in idna.encode; transitive via httpx/requests)
 # - markdown>=3.10.2 for PYSEC-2026-89 (DoS in html.parser during Markdown parse; mkdocs stack)
 # - pymdown-extensions>=10.21.3 for CVE-2026-46338 (snippets base_path prefix bypass; mkdocs stack)
@@ -141,13 +144,14 @@ override-dependencies = [
     "pyjwt>=2.13.0,<3",
     "pyasn1>=0.6.3",
     "tinytag>=2.2.1",
-    "cryptography>=46.0.7,<47",
+    "cryptography>=48.0.1,<49",
     "requests>=2.33.0",
     "pillow>=12.2.0",
     "pytest>=9.0.3",
-    "python-multipart>=0.0.27",
+    "python-multipart>=0.0.31",
+    "starlette>=1.3.1",
     "pygments>=2.20.0",
-    "langsmith>=0.8.0",
+    "langsmith>=0.8.18",
     "langchain-core>=1.3.3",
     "urllib3>=2.7.0",
     "pip>=26.1.2",
@@ -156,6 +160,8 @@ override-dependencies = [
     "idna>=3.15",
     "markdown>=3.10.2",
     "pymdown-extensions>=10.21.3",
+    "pydantic-settings>=2.14.2",
+    "msgpack>=1.2.1",
 ]
 
 [project.scripts]
@@ -306,7 +312,7 @@ addopts = [
     "--strict-markers",
     "--strict-config",
 ]
-# Coverage options: use explicitly when needed (e.g., pytest --cov=src --cov-report=xml)
+# Coverage options: use explicitly when needed (e.g., pytest --tb=short --cov=asap --cov-report=xml --cov-fail-under=85)
 # NOT included in addopts to avoid conflicts with pytest-xdist (-n auto)
 testpaths = ["tests"]
 # Note: benchmarks/ excluded from testpaths - Locust monkey-patches gevent/ssl which

{asap_protocol-2.4.1 → asap_protocol-2.5.0}/src/asap/__init__.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from typing import Any
 
-__version__ = "2.4.1"
+__version__ = "2.5.0"
 
 __all__ = ["__version__", "create_from_openapi"]
 

asap_protocol-2.5.0/src/asap/adapters/mcp/__init__.py

@@ -0,0 +1,17 @@
+"""MCP Auth Bridge adapter (v2.5.0).
+
+Opt-in protection for native ``MCPServer`` via ``protect_server``.
+"""
+
+from __future__ import annotations
+
+from asap.adapters.mcp.auth_middleware import protect_server
+from asap.adapters.mcp.config import MCPAuthConfig, resolve_jwt_extractor
+from asap.adapters.mcp.protected_server import ProtectedMCPServer
+
+__all__ = [
+    "MCPAuthConfig",
+    "ProtectedMCPServer",
+    "protect_server",
+    "resolve_jwt_extractor",
+]

asap_protocol-2.5.0/src/asap/adapters/mcp/auth_middleware.py

@@ -0,0 +1,33 @@
+"""MCP Auth Bridge middleware entry point (v2.5.0)."""
+
+from __future__ import annotations
+
+from asap.adapters.mcp.config import MCPAuthConfig, resolve_jwt_extractor
+from asap.adapters.mcp.protected_server import ProtectedMCPServer
+from asap.mcp.server import MCPServer
+
+__all__ = ["MCPAuthConfig", "protect_server", "resolve_jwt_extractor"]
+
+
+def protect_server(server: MCPServer, config: MCPAuthConfig) -> ProtectedMCPServer:
+    """Return an MCP server with JWT and capability enforcement on ``tools/call``.
+
+    Verifies Agent JWT extraction/verification, the ``public_tools`` allowlist, and
+    (when ``enforce_grants=True``) JWT capability claims plus
+    :meth:`~asap.auth.capabilities.CapabilityRegistry.check_grant`.
+
+    ``from_server`` copies register-time capability metadata onto the protected instance
+    without mutating ``config``.
+
+    See PRD v2.5.0 MCP Auth Bridge (``product/prd/prd-v2.5.0-mcp-auth-bridge.md``)
+    and design lock ADR (``engineering/tasks/v2.5.0/design-lock-mcp-auth-bridge.md``).
+
+    Args:
+        server: Native MCP server with registered tools.
+        config: Auth configuration (identity stores, capability registry, extractors).
+
+    Returns:
+        Protected server instance; unprotected ``MCPServer`` usage remains valid when
+        this function is not called.
+    """
+    return ProtectedMCPServer.from_server(server, config)

asap_protocol-2.5.0/src/asap/adapters/mcp/capability_map.py

@@ -0,0 +1,74 @@
+"""Tool-to-capability resolution for MCP Auth Bridge (v2.5.0)."""
+
+from __future__ import annotations
+
+from asap.adapters.mcp.config import MCPAuthConfig
+from asap.auth.capabilities import ConstraintViolation
+from asap.mcp.server import MCPServer
+
+
+def resolve_capability(
+    tool_name: str,
+    config: MCPAuthConfig,
+    *,
+    server: MCPServer | None = None,
+) -> str:
+    """Resolve an MCP tool name to an ASAP capability name.
+
+    Resolution order (MCP-MAP-001, MCP-MAP-002):
+
+    1. ``config.tool_capability_map`` (explicit runtime override)
+    2. ``server.get_tool_capability(tool_name)`` when register-time metadata is set
+    3. Identity default: ``tool_name`` unchanged
+
+    Args:
+        tool_name: Registered MCP tool name from ``tools/call``.
+        config: MCP auth configuration including capability maps.
+        server: MCP server providing register-time capability metadata.
+
+    Returns:
+        ASAP capability name used for grant checks.
+
+    Example:
+        >>> from asap.adapters.mcp.config import MCPAuthConfig
+        >>> from asap.auth.capabilities import CapabilityRegistry
+        >>> from asap.auth.identity import InMemoryAgentStore, InMemoryHostStore
+        >>> from asap.mcp.server import MCPServer
+        >>> agents = InMemoryAgentStore()
+        >>> config = MCPAuthConfig(
+        ...     host_store=InMemoryHostStore(agent_store=agents),
+        ...     agent_store=agents,
+        ...     capability_registry=CapabilityRegistry(),
+        ...     tool_capability_map={"search": "web_search"},
+        ... )
+        >>> resolve_capability("search", config)
+        'web_search'
+        >>> resolve_capability("echo", config)
+        'echo'
+    """
+    if tool_name in config.tool_capability_map:
+        return config.tool_capability_map[tool_name]
+    if server is not None:
+        registered = server.get_tool_capability(tool_name)
+        if registered is not None:
+            return registered
+    return tool_name
+
+
+def format_constraint_violations(violations: list[ConstraintViolation]) -> str:
+    """Format grant constraint violations for MCP ``tools/call`` error detail.
+
+    Args:
+        violations: Constraint failures from :meth:`CapabilityRegistry.check_grant`.
+
+    Returns:
+        Human-readable detail string joined with ``; ``.
+
+    Example:
+        >>> from asap.auth.capabilities import ConstraintViolation
+        >>> format_constraint_violations([
+        ...     ConstraintViolation("tokens", "max", 100, 150, "tokens: 150 exceeds maximum 100"),
+        ... ])
+        'tokens: 150 exceeds maximum 100'
+    """
+    return "; ".join(v.message for v in violations)

asap_protocol-2.5.0/src/asap/adapters/mcp/config.py

@@ -0,0 +1,70 @@
+"""MCP Auth Bridge configuration (v2.5.0)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from asap.adapters.mcp.jwt_extractor import default_jwt_extractor
+from asap.auth.agent_jwt import JtiReplayCache
+from asap.auth.capabilities import CapabilityRegistry
+from asap.auth.identity import AgentStore, HostStore
+from asap.mcp.protocol import CallToolRequestParams
+
+
+MCP_COMPLIANCE_ENV_VAR = "ASAP_MCP_COMPLIANCE"
+
+
+@dataclass
+class MCPAuthConfig:
+    """Configuration for ASAP auth on a native MCP server.
+
+    JWT extraction: middleware MUST call :func:`resolve_jwt_extractor` (or
+    equivalent ``config.jwt_extractor or`` closure over
+    :func:`default_jwt_extractor` with ``allow_env_fallback=config.allow_env_jwt_fallback``).
+    Do not invoke a ``None`` extractor.
+
+    ``hide_unauthorized_tools`` is reserved for MCP-MAP-004 (deferred per design-lock §6);
+    stdio ``tools/list`` has no standard JWT carriage in v2.5.0.
+
+    Example:
+        >>> config = MCPAuthConfig(
+        ...     host_store=host_store,
+        ...     agent_store=agent_store,
+        ...     capability_registry=registry,
+        ... )
+    """
+
+    host_store: HostStore
+    agent_store: AgentStore
+    capability_registry: CapabilityRegistry
+    tool_capability_map: dict[str, str] = field(default_factory=dict)
+    public_tools: frozenset[str] = frozenset()
+    enforce_grants: bool = True
+    hide_unauthorized_tools: bool = False
+    validate_tools_at_startup: bool = False
+    jwt_extractor: Callable[[CallToolRequestParams], str | None] | None = None
+    allow_env_jwt_fallback: bool = False
+    jti_replay_cache: JtiReplayCache | None = None
+    expected_audience: str | list[str] | None = None
+    manifest_url: str | None = None
+
+
+def resolve_jwt_extractor(config: MCPAuthConfig) -> Callable[[CallToolRequestParams], str | None]:
+    """Return the JWT extractor for middleware (custom or default with config flags).
+
+    Args:
+        config: MCP auth configuration.
+
+    Returns:
+        Callable that extracts an Agent JWT from ``tools/call`` params.
+    """
+    if config.jwt_extractor is not None:
+        return config.jwt_extractor
+
+    allow_env = config.allow_env_jwt_fallback
+
+    def extract(params: CallToolRequestParams) -> str | None:
+        return default_jwt_extractor(params, allow_env_fallback=allow_env)
+
+    return extract

asap_protocol-2.5.0/src/asap/adapters/mcp/errors.py

@@ -0,0 +1,32 @@
+"""MCP-facing ASAP auth error codes and result helpers (v2.5.0)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from asap.mcp.protocol import CallToolResult, TextContent
+
+AUTH_REQUIRED = "asap:auth_required"
+INVALID_TOKEN = "asap:invalid_token"
+CAPABILITY_DENIED = "asap:capability_denied"
+CONSTRAINT_VIOLATION = "asap:constraint_violation"
+
+
+def tool_error_result(code: str, detail: str | None = None) -> dict[str, Any]:
+    """Build a ``tools/call`` error payload with ``isError: true``.
+
+    Args:
+        code: ASAP-namespaced error code (e.g. ``asap:auth_required``).
+        detail: Optional human-readable detail appended after the code.
+
+    Returns:
+        Dict suitable for JSON-RPC ``result`` (``CallToolResult`` shape).
+
+    Example:
+        >>> tool_error_result(AUTH_REQUIRED)["isError"]
+        True
+    """
+    text = code if detail is None else f"{code}: {detail}"
+    result = CallToolResult(content=[TextContent(text=text).model_dump(by_alias=True)])
+    result.is_error = True
+    return result.model_dump(by_alias=True, exclude_none=True)

asap_protocol-2.5.0/src/asap/adapters/mcp/jwt_extractor.py

@@ -0,0 +1,52 @@
+"""JWT extraction helpers for MCP Auth Bridge (v2.5.0)."""
+
+from __future__ import annotations
+
+import os
+
+from asap.mcp.protocol import CallToolRequestParams
+
+_META_JWT_KEY = "asap_agent_jwt"
+_ENV_JWT_KEY = "ASAP_AGENT_JWT"
+
+
+def default_jwt_extractor(
+    params: CallToolRequestParams,
+    *,
+    allow_env_fallback: bool = False,
+) -> str | None:
+    """Extract Agent JWT from ``tools/call`` params or optional dev-only environment.
+
+    Reads ``params.meta["asap_agent_jwt"]`` (MCP ``_meta`` field). When
+    ``allow_env_fallback`` is ``True``, falls back to ``ASAP_AGENT_JWT`` for
+    single-agent local testing only.
+
+    Args:
+        params: Parsed ``tools/call`` request parameters.
+        allow_env_fallback: When ``True``, read ``ASAP_AGENT_JWT`` if meta is absent.
+            Defaults to ``False`` so production cannot inherit a process-wide token.
+
+    Returns:
+        Stripped JWT string, or ``None`` when no token is present.
+
+    Example:
+        >>> from asap.mcp.protocol import CallToolRequestParams
+        >>> params = CallToolRequestParams.model_validate(
+        ...     {"name": "t", "_meta": {"asap_agent_jwt": "  token  "}}
+        ... )
+        >>> default_jwt_extractor(params)
+        'token'
+    """
+    meta = params.meta or {}
+    token = meta.get(_META_JWT_KEY)
+    if isinstance(token, str) and token.strip():
+        return token.strip()
+
+    if not allow_env_fallback:
+        return None
+
+    env_token = os.environ.get(_ENV_JWT_KEY)
+    if isinstance(env_token, str) and env_token.strip():
+        return env_token.strip()
+
+    return None