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

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

@@ -7,17 +7,139 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Follow-up (not in this release)
+### Follow-up (planned v2.5.3+)
 
-- `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
-- `@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))
+- **Adapter Lab II** — enterprise/workflow adapters ([prd-v2.5.3-adapter-lab-ii.md](product/prd/prd-v2.5.3-adapter-lab-ii.md)).
+- **Distribution Loop** — homepage, templates, metrics ([prd-v2.5.4-distribution-loop.md](product/prd/prd-v2.5.4-distribution-loop.md)).
+- **Formal Spec & Interop** — RFC spec, introspection, privacy ([prd-v2.5.5-formal-spec-interop.md](product/prd/prd-v2.5.5-formal-spec-interop.md)).
+- `@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)).
+- Collapse the dual `UsageMetrics`/`InMemoryMeteringStore` pair retained in S1 for API stability.
+- Reduce the `asap.transport.client` package aggregate LOC below the S2 target.
+
+---
+
+## [2.5.2] - 2026-07-08
+
+**Security & correctness follow-up** — operator API auth, tighter ingress
+validation, Redis JTI replay, web distributed rate limits, v2.5.1 CR follow-ups,
+and registry fixes. Scope: [prd-v2.5.2-security-follow-up.md](product/prd/prd-v2.5.2-security-follow-up.md).
+Wire protocol and manifest schema are unchanged aside from rejecting unknown
+`config` / `metadata` keys (see Migration).
+
+### Added
+
+- **Opt-in operator API auth (#209)**: `create_app(require_operator_auth=True)`
+  requires an OAuth2 Bearer JWT with scope ``asap:admin`` on ``/usage``,
+  ``/sla``, and ``/audit``. Default remains open (local/operator ergonomics)
+  with the existing startup warnings. Requires ``oauth2_config``.
+- **Redis-backed JTI replay cache (#209)**: Optional
+  :class:`~asap.auth.jti_replay_cache.RedisJtiReplayCache` for multi-worker
+  Host/Agent JWT replay protection. Default remains in-memory
+  :class:`~asap.auth.agent_jwt.JtiReplayCache`. Requires
+  ``pip install 'asap-protocol[redis]'``. Inject via
+  ``create_app(identity_jti_cache=...)`` or ``MCPAuthConfig.jti_replay_cache``.
+
+### Changed
+
+- **Ingress validation (#209)**: `TaskRequestConfig` and `CommonMetadata` now reject
+  unknown fields (`extra="forbid"`, inherited from `ASAPBaseModel`). Previously these
+  models allowed arbitrary extension keys; clients sending custom `config` or
+  `metadata` properties must use known fields only or nest extensions under
+  `TaskRequest.input` / envelope `extensions`. See
+  [migration guide](docs/migration.md#upgrading-from-v251).
+- **CLI legacy imports (#242)**: `DEFAULT_SCHEMAS_DIR`, `export_all_schemas`, and
+  `_repl_namespace` are no longer re-exported from `asap.cli` root. Import from
+  `asap.cli._compat` (shim) or the owning submodules (`asap.cli.schemas`,
+  `asap.schemas`, `asap.cli.repl`). The `_compat` shim is removed in v2.6.0
+  ([#275](https://github.com/adriannoes/asap-protocol/issues/275)).
+  See [migration guide](docs/migration.md#upgrading-from-v251).
+- **Web app (`apps/web`)**: Optional distributed rate limits via Upstash Redis
+  or Vercel KV when `UPSTASH_REDIS_REST_URL` + `UPSTASH_REDIS_REST_TOKEN` (or
+  `KV_REST_API_URL` + `KV_REST_API_TOKEN`) are set; local dev without Redis
+  keeps the existing in-memory per-instance limiter
+  ([#209](https://github.com/adriannoes/asap-protocol/issues/209)).
+- **Auth scope parsing (#243)**: `parse_scope` lives in `asap.auth._scope_parse` so
+  `OAuth2Middleware` no longer needs an inline import to break a cycle.
+
+### Fixed
+
+- **CI security (`pip-audit`)**: Raised `joserfc` to `>=1.6.7,<2` (CVE-2026-48990) and added overrides for `python-engineio>=4.13.2` (CVE-2026-48802 / CVE-2026-48809) and `python-socketio>=5.16.2` (CVE-2026-48804). See [SECURITY.md](SECURITY.md).
+- **Streaming correlation binding (#247)**: SSE and WebSocket streaming now require `TaskStream` chunks to echo the request envelope `id` (not an arbitrary request `correlation_id`), and streamed response payloads reject missing or mismatched `correlation_id` values.
+- **SQLite write serialization (#245)**: `AsyncSqliteRepository.execute()` now holds the same `asyncio.Lock` as other write paths so concurrent writers cannot interleave on a shared connection.
+- **Agent status JTI replay (#249)**: `GET /asap/agent/status` now records JWT `jti` in the replay cache (same hardening as other identity routes).
+- **Registry signed manifests (#224)**: Registration paths accept signed manifest envelopes (unwrap before validation).
+- **Registry validation errors (#227)**: Auto-registration maps `ManifestValidationError` to HTTP 400 instead of a 500.
+
+### Migration
+
+- **v2.5.1 → v2.5.2**: See [migration guide](docs/migration.md#upgrading-from-v251).
+  Breaking for clients that sent unknown keys on `TaskRequest.config` /
+  `CommonMetadata`. Operator auth and Redis JTI remain opt-in.
+
+---
+
+## [2.5.1] - 2026-06-25
+
+**Code quality patch** — behavior-preserving refactor of the transport, storage,
+auth, and integration layers accumulated through v2.5.0, plus six correctness and
+security fixes. No wire-protocol, manifest schema, or public API breaking changes.
+Deprecated import paths keep working via shims until v2.6.0.
+
+### Fixed
+
+- **`revoke_cascade` atomicity**: delegation revocation now runs in a single SQLite transaction (BEGIN→walk→COMMIT, rollback on failure); the in-memory store holds an `asyncio.Lock` across the cascade so concurrent `register_issued` can't leave children un-revoked.
+- **`usage_events` schema**: one canonical DDL owner in `state/stores/sqlite.py`; both indexes created with `IF NOT EXISTS` regardless of store init order, fixing schema/query-plan divergence.
+- **Host-JWT verifier**: collapsed the divergent verifiers into one `verify_host_bearer`; revoked hosts now return 403 (was 401) on every protected route, including `/asap/agent/reactivate`.
+- **WebSocket OAuth2 bypass**: `/asap/ws` no longer skips `OAuth2Middleware`. In OAuth2-only deployments the WS path now requires a Bearer JWT in the handshake `Authorization` header and rejects with close code 4401 when absent or invalid. Deploys without an OAuth2 IdP are unchanged.
+- **OpenAPI handler**: hoisted the inline `format_www_authenticate_asap` import to module top; `OpenAPIPathParameterError.__init__` no longer raises (validation moved to `for_missing()`/`for_invalid()` factories). `resolve_headers` stays as documented public API.
+- **Client correlation binding**: the client now asserts `response.correlation_id == request.id` in `send()`, `batch()`, and the WS recv loop, raising `ProtocolCorrelationError` (previously only checked non-empty).
+
+### Changed
+
+- **Storage consolidation**: six SQLite backends (snapshot, metering, delegation, SLA, audit, plus the economics metering store) now subclass a shared `AsyncSqliteRepository` (`state/stores/_sqlite_base.py`) with one WAL setup, `transaction()`, `parse_iso`, and `build_where`. `server.py` uses the new `MeteringStorageBridge` directly; `metering_storage_adapter` is kept as a one-line shim.
+- **`server.py` decomposition**: split into `create_*_router` factories plus `routes/{health,jsonrpc,websocket,audit}.py` (2256 → 1000 LOC); `create_app` is thin wiring. Shared request prep (`parse→auth→envelope→timestamp→nonce`) moved to `ASAPRequestHandler._prepare_request`.
+- **`client.py` decomposition**: split into a `client/` package (`_core`, `_send`, `_discovery`, `_helpers`); `get_manifest`/`discover` now share `_fetch_and_cache_manifest`, and `send`'s Retry-After parser is extracted. `from asap.transport.client import ASAPClient` is unchanged.
+- **`websocket.py` decomposition**: split into `asap/transport/ws/` (`codecs`, `client`, `server`, `pool`, `_recv`, `_ack`, `_dispatch`, `_actions`, `_errors`); `_make_fake_request` is gone and WS dispatches envelopes directly through `_prepare_request`. `websocket.py` stays as a re-export shim.
+- **Integrations**: shared `asap/integrations/_base.py` centralizes JSON-schema→Pydantic conversion, URN-scoped skill resolve cache, and per-exception error formatting; `langchain`/`crewai`/`llamaindex`/`smolagents` slimmed to glue-only (71–80 LOC each).
+- **`OAuth2Middleware` JWKS**: delegates to one shared `JWKSValidator` instead of its own cache; HTTP and WS now use the same validator and TTL (`JWKS_CACHE_TTL_SECONDS=86400`).
+- **`MCPServer` tool registration**: the untyped 5-tuple is now a frozen `ToolRegistration` dataclass with per-tool capability metadata.
+- **`RemoteRPCError`**: `RemoteFatalRPCError`/`RemoteRecoverableRPCError` collapse into one `RemoteRPCError` with an `is_recoverable` property; the old names stay as deprecated subclasses.
+- **Identity rate limiting**: the 9 inline limiter checks now use `Depends(require_identity_limiter)`; a missing limiter returns 503 (was `AttributeError` → 500).
+- **`auth/` modules**: `claims`→`jwks`/`middleware`, `utils`→`scopes`, `lifecycle`→`identity`; `WebAuthnSelfAuthVerifier` deleted (`WebAuthnVerifierImpl` satisfies the protocol directly).
+- **MCP Auth Bridge**: folded `asap.adapters.mcp.*` into `asap.mcp.auth.*`; `asap.adapters.mcp` stays as a re-export shim.
+
+### Removed
+
+- **`asap.transport` root re-exports**: `start_periodic_cleanup`, `WebhookDelivery`, `RetryPolicy`, `compute_signature`, and other tuning/webhook internals are no longer re-exported from `asap.transport.__init__` — import them from their owning modules (`asap.transport.cache`, `asap.transport.webhook`).
+- **`asap.transport.codecs` package**: inlined into `asap.transport.lambda_codec`; WS framing primitives moved to `asap.transport.ws.codecs`. No shim (grep-verified zero external callers).
+- **`NonceStore.is_used` / `mark_used`**: replaced by the atomic `check_and_mark`. Custom nonce stores should switch to the one-method protocol.
+- **`OpenAPIExecutionKind.ASYNC_POLLING`**: pruned; a `202 + Location` OpenAPI operation now classifies as `SYNC`.
+- **Dead binary/base64 WS framing**: frames are JSON text only.
+
+### Deprecated (remove in v2.6.0)
+
+- `from asap.cli._compat import ...` — use `asap.cli.schemas`, `asap.schemas`, or
+  `asap.cli.repl` directly ([#242](https://github.com/adriannoes/asap-protocol/issues/242);
+  removal tracked in [#275](https://github.com/adriannoes/asap-protocol/issues/275)).
+- `from asap.transport.websocket import ...` — use `asap.transport.ws` directly.
+- `from asap.adapters.mcp import ...` — use `asap.mcp.auth` directly.
+- `RemoteFatalRPCError` / `RemoteRecoverableRPCError` — use `RemoteRPCError` + `is_recoverable`.
+- `metering_storage_adapter` — use `MeteringStorageBridge`.
+- `FRAME_ENCODING_BINARY` — binary framing is gone; the literal remains on the shim for import compat only.
+
+### Migration
+
+- **v2.5.0 → v2.5.1**: No breaking changes. Update deprecated import paths at your convenience (removed in v2.6.0). If you run an OAuth2-only deployment, note that `/asap/ws` now requires a Bearer JWT in the handshake — see [migration guide](docs/migration.md#upgrading-from-v250-to-v251).
+
+---
+
+## [2.5.0.1] - 2026-06-24
+
+**Compliance package publish** — no change to `asap-protocol` Python API (remains **2.5.0** on PyPI). Git tag **`v2.5.0.1`** is **compliance-only** (not an npm TypeScript release).
 
 ### 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.
+- **PyPI `asap-compliance`**: Bump to **1.3.0** and publish the `mcp-auth-bridge` stdio MCP profile shipped in v2.5.0. The v2.5.0 tag did not upload a new compliance wheel because `release.yml` uses `skip-existing` and the version was still **1.2.0** (February 2026 artifact without MCP auth checks). Requires `asap-protocol>=2.5.0`.
 
 ---
 
@@ -67,14 +189,11 @@ changes.
 
 ### 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:
+- **`@asap-protocol/mcp-auth` deferred** — 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 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.
+  [backlog](engineering/tasks/v2.5.0/backlog-mcp-auth-typescript.md).
+  **Note:** git tag **`v2.5.0.1`** was used for **`asap-compliance` 1.3.0** only; the npm middleware targets a **future patch** (TBD tag, e.g. `v2.5.0.2`).
+  Existing `@asap-protocol/*` npm packages remain at **2.4.1** until that publish.
 
 ### Migration
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asap-protocol
-Version: 2.5.0
+Version: 2.5.2
 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
@@ -27,7 +27,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
-Requires-Dist: joserfc<2,>=1.6.3
+Requires-Dist: joserfc<2,>=1.6.7
 Requires-Dist: jsonschema>=4.23.0
 Requires-Dist: limits>=3.0
 Requires-Dist: opentelemetry-api>=1.20
@@ -48,6 +48,7 @@ Requires-Dist: crewai>=0.80; extra == 'crewai'
 Provides-Extra: dev
 Requires-Dist: asgi-lifespan>=2.1.0; extra == 'dev'
 Requires-Dist: brotli>=1.1.0; extra == 'dev'
+Requires-Dist: fakeredis>=2.26.0; extra == 'dev'
 Requires-Dist: mypy>=1.19.1; extra == 'dev'
 Requires-Dist: pip-audit>=2.7; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
@@ -61,9 +62,12 @@ Provides-Extra: dns-sd
 Requires-Dist: zeroconf>=0.149.5; extra == 'dns-sd'
 Provides-Extra: docs
 Requires-Dist: ghp-import>=2.1.0; extra == 'docs'
+Requires-Dist: joserfc<2,>=1.6.7; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.21.3; extra == 'docs'
+Requires-Dist: python-engineio>=4.13.2; extra == 'docs'
+Requires-Dist: python-socketio>=5.16.2; extra == 'docs'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
 Provides-Extra: llamaindex
@@ -83,7 +87,7 @@ Requires-Dist: smolagents>=1.24.0; extra == 'smolagents'
 Provides-Extra: telemetry
 Requires-Dist: pypistats>=1.11.0; extra == 'telemetry'
 Provides-Extra: webauthn
-Requires-Dist: webauthn<3,>=2.6; extra == 'webauthn'
+Requires-Dist: webauthn<4,>=2.6; extra == 'webauthn'
 Description-Content-Type: text/markdown
 
 # ASAP: Async Simple Agent Protocol
@@ -95,40 +99,57 @@ Description-Content-Type: text/markdown
 
 > A production-ready protocol for agent-to-agent communication and task coordination.
 
-**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)
+**Quick Info**: [`v2.5.2`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.5.2) | `Apache 2.0` | `Python 3.13+` | [Documentation](docs/index.md) | [Changelog](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/).
+> 📦 **Install** — [`asap-protocol` on PyPI](https://pypi.org/project/asap-protocol/) (Python) · [`@asap-protocol/client` on npm](https://www.npmjs.com/package/@asap-protocol/client) (TypeScript)
 
-> 🚀 **Live now** our [**agentic marketplace**](https://asap-protocol.com/) — browse agents, register yours, request verification.
+🚀 **Live now** our [**agentic marketplace**](https://asap-protocol.com/) — browse agents, register yours, request verification.
 
 ## Why ASAP?
 
-Building multi-agent systems today suffers from three core technical challenges that existing protocols like A2A don't fully address:
-1. **$N^2$ Connection Complexity**: Most protocols assume static point-to-point HTTP connections that don't scale.
-2. **State Drift**: Lack of native persistence makes it impossible to reliably resume long-running agentic workflows.
-3. **Fragmentation**: No unified way to handle task delegation, artifact exchange and tool execution (MCP) in a single envelope.
+Multi-agent systems hit three walls that point-to-point agent protocols often leave open:
 
-**ASAP** provides a production-ready communication layer that simplifies these complexities. It's ideal for **multi-agent orchestration**, **stateful workflows** (persistence, resumability), **MCP support** and **production systems** requiring high-performance, type-safe agent communication. 
+1. **Connection sprawl** — pairwise HTTP does not scale as orchestrators fan out.
+2. **State drift** — long workflows stall without durable task state and resumability.
+3. **Fragmentation** — delegation, artifacts, and MCP tool calls end up in incompatible layers.
 
-For simple point-to-point communication, a basic HTTP API might suffice; ASAP shines when you need orchestration, state management and multi-agent coordination. See the [documentation](https://github.com/adriannoes/asap-protocol/blob/main/docs/index.md) for the current protocol overview and features.
+**ASAP** answers with a schema-first protocol and reference SDKs in **Python** and **TypeScript**:
+
+- **Resumable orchestration** — task state machine, snapshot store, SSE streaming, and built-in `trace_id` / `correlation_id`.
+- **One typed envelope** — tasks, MCP tool execution, and artifact exchange on the same JSON Schema contract.
+- **Production trust** — Ed25519 signed manifests, Host/Agent JWTs, constrained capabilities, OAuth2, opt-in WebAuthn — plus the **MCP Auth Bridge** (v2.5.0) for scoped native `tools/call`.
+- **Ecosystem-ready** — [agentic marketplace](https://asap-protocol.com/), Lite Registry, edge-AI discovery, OpenAPI import, and framework adapters ([Python & npm](#framework-ecosystem)).
+
+Plain HTTP between two agents is enough for the simplest cases. ASAP is built for **multi-agent orchestration**, **stateful workflows**, and **governed capability access** in production — see [documentation](docs/index.md) and the feature table below.
 
 ### Key Features
 
-- **Stateful orchestration** — Task state machine with snapshotting for resumable workflows.
-- **Schema-first** — Pydantic v2 + JSON Schema for cross-agent interoperability.
-- **Async-native** — `asyncio` + `httpx`; sync and async handlers supported.
-- **MCP integration** — Tool execution and coordination in a single envelope.
-- **Observable** — `trace_id` and `correlation_id` for debugging.
-- **Security** — Bearer auth, OAuth2/JWT, Ed25519 signed manifests, optional mTLS, replay prevention, HTTPS, rate limiting. [Security Model](https://github.com/adriannoes/asap-protocol/blob/main/docs/security/v1.1-security-model.md) (trust limits, Custom Claims).
-- **Identity & capabilities (v2.2, WebAuthn real in v2.2.1)** — Per-runtime Host/Agent JWTs, capability grants with constraints (`max`, `min`, `in`, `not_in`), approval flows (device authorization / CIBA-style), real WebAuthn attestation/assertion for high-risk registration (opt-in via `asap-protocol[webauthn]`).
-- **Streaming & wire protocol (v2.2)** — `POST /asap/stream` (SSE / `TaskStream`), JSON-RPC 2.0 batch on `POST /asap`, `ASAP-Version` negotiation, tamper-evident audit logging, Compliance Harness v2.
-- **Adoption Multiplier (v2.3.0)** — OpenAPI → ASAP via `create_from_openapi` (`[openapi]` extra), official **`@asap-protocol/client`** on npm (Vercel AI / OpenAI / Anthropic adapters), optional **Auto-Registration** (`POST /registry/agents`), **capability escalation**, and **ASAP `WWW-Authenticate`** discovery challenges. All opt-in; wire protocol unchanged. See [docs/index.md](docs/index.md) and [docs/migration.md](docs/migration.md).
-- **Edge-AI discovery (v2.4.0)** — Optional `manifest.capabilities.hardware` + `inference`, Lite Registry mirror, marketplace browse filters, and `@asap-protocol/client@2.4.1` discovery types. Wire protocol unchanged. See [Migration (v2.3.x → v2.4.0)](docs/migration.md#upgrading-from-v23x-to-v240) and [ShellClaw registry guide](docs/guides/shellclaw-registry.md).
-- **Framework adapters (v2.3.1+, npm)** — **`@asap-protocol/mastra`** and **`@asap-protocol/openai-agents`** expose ASAP capabilities as Mastra tools and OpenAI Agents SDK `tool()` definitions. See [Migration (v2.3.0 → v2.3.1)](docs/migration.md#upgrading-from-v230-to-v231).
-- **Economics** — Usage metering, delegation tokens, SLA framework with breach alerts.
-
-### 🆕 Framework Ecosystem
-ASAP is built for interoperability. Seamlessly integrate your agents into **OpenClaw**, **LangChain**, **CrewAI** and **LlamaIndex** workflows using our growing library of native adapters and standardized tool-calling schemas.
+| Area | Highlights | Docs |
+| --- | --- | --- |
+| Stateful orchestration | Task state machine, snapshotting, resumable workflows | [State management](docs/state-management.md) |
+| Schema-first | Pydantic v2 + JSON Schema for cross-agent interchange | [API reference](docs/api-reference.md) |
+| Async-native | `asyncio` + `httpx`; sync and async handlers | [Transport](docs/transport.md) |
+| MCP integration | Tool execution and coordination in one envelope (Mode B) | [MCP integration](docs/mcp-integration.md) |
+| MCP Auth Bridge | Opt-in Agent JWT + capability grants on native stdio MCP `tools/call` (Mode A) | [MCP Auth Bridge](docs/adapters/mcp-auth-bridge.md) |
+| Observability | `trace_id` and `correlation_id` for debugging | [Observability](docs/observability.md) |
+| Security | OAuth2/JWT, Ed25519 manifests, mTLS, rate limiting | [Security](docs/security.md) |
+| Identity & capabilities | Host/Agent JWTs, constrained grants, approval flows, opt-in WebAuthn | [Capabilities](docs/capabilities/index.md) |
+| Streaming & wire protocol | SSE `/asap/stream`, JSON-RPC batch, `ASAP-Version` negotiation | [Transport](docs/transport.md) |
+| Adoption tools | OpenAPI adapter, `@asap-protocol/client`, auto-registration, escalation | [Migration (v2.2 → v2.3)](docs/migration.md#upgrading-from-v22x-to-v230) |
+| Edge-AI discovery | Hardware/inference manifests, registry mirror, marketplace filters | [ShellClaw guide](docs/guides/shellclaw-registry.md) |
+| Framework adapters (npm) | `@asap-protocol/mastra` and `@asap-protocol/openai-agents` tool bridges | [Mastra](docs/integrations/mastra.md) · [OpenAI Agents](docs/integrations/openai-agents.md) |
+| Economics | Usage metering, delegation tokens, SLA breach alerts | [Audit log](docs/audit.md) |
+
+Full overview and upgrade paths: [docs/index.md](docs/index.md).
+
+### Framework Ecosystem
+
+ASAP meets agents where they run — optional Python extras, npm tool bridges, and protocol-native MCP.
+
+| Runtime | Integrations | Docs |
+| --- | --- | --- |
+| **Python** | LangChain, CrewAI, LlamaIndex, PydanticAI, SmolAgents, OpenClaw (`pip install "asap-protocol[extra]"`); Vercel AI SDK router; MCP; MCP Auth Bridge; A2H | [OpenClaw](docs/guides/openclaw-integration.md) · [Vercel AI SDK](docs/guides/vercel-ai-sdk.md) · [MCP](docs/mcp-integration.md) · [MCP Auth Bridge](docs/adapters/mcp-auth-bridge.md) |
+| **TypeScript** (npm) | `@asap-protocol/client` (Vercel AI / OpenAI / Anthropic adapters), `@asap-protocol/mastra`, `@asap-protocol/openai-agents` | [TypeScript SDK](docs/sdks/typescript.md) · [Mastra](docs/integrations/mastra.md) · [OpenAI Agents](docs/integrations/openai-agents.md) |
 
 ## Installation
 
@@ -144,11 +165,11 @@ Or with pip:
 pip install asap-protocol
 ```
 
-**npm** (TypeScript / JavaScript — [`@asap-protocol/client`](https://www.npmjs.com/package/@asap-protocol/client), **`2.4.1`**). The `latest` dist-tag matches **`npm view @asap-protocol/client version`**.
+**TypeScript** (npm, **`2.4.1`** — unchanged for v2.5.2; `@asap-protocol/mcp-auth` HTTP middleware still deferred):
 
-**npm** Mastra [**`@asap-protocol/mastra@2.4.1`**](https://www.npmjs.com/package/@asap-protocol/mastra) bridges ASAP capabilities onto **`@mastra/core`** tools; docs: [`docs/integrations/mastra.md`](docs/integrations/mastra.md), demo: [`apps/example-mastra/README.md`](apps/example-mastra/README.md).
-
-**npm** OpenAI Agents SDK [**`@asap-protocol/openai-agents@2.4.1`**](https://www.npmjs.com/package/@asap-protocol/openai-agents) exposes ASAP capabilities as **`@openai/agents`** `tool()` definitions — **not** the Chat Completions helper [`adapters/openai`](packages/typescript/client/src/adapters/openai.ts); docs: [`docs/integrations/openai-agents.md`](docs/integrations/openai-agents.md), demo: [`apps/example-openai-agents/README.md`](apps/example-openai-agents/README.md).
+- [`@asap-protocol/client`](https://www.npmjs.com/package/@asap-protocol/client) — [SDK docs](docs/sdks/typescript.md)
+- [`@asap-protocol/mastra`](https://www.npmjs.com/package/@asap-protocol/mastra) — [docs](docs/integrations/mastra.md) · [demo](apps/example-mastra/README.md)
+- [`@asap-protocol/openai-agents`](https://www.npmjs.com/package/@asap-protocol/openai-agents) — [docs](docs/integrations/openai-agents.md) · [demo](apps/example-openai-agents/README.md)
 
 ```bash
 npm install @asap-protocol/client@2.4.1
@@ -156,7 +177,7 @@ npm install @asap-protocol/mastra@2.4.1 @asap-protocol/client @mastra/core zod
 npm install @asap-protocol/openai-agents@2.4.1 @asap-protocol/client @openai/agents zod
 ```
 
-📦 **Canonical listing:** **[https://pypi.org/project/asap-protocol/](https://pypi.org/project/asap-protocol/)** — package **`asap-protocol`** (`pip install asap-protocol`). Prefer `uv` for reproducible environments when possible.
+**Python v2.5.2** (security follow-up): `uv add asap-protocol` or `pip install asap-protocol==2.5.2` — see [Migration (v2.5.1 → v2.5.2)](docs/migration.md#upgrading-from-v251).
 
 ## Quick Start
 
@@ -189,17 +210,20 @@ uv run pytest --tb=short --cov=asap --cov-report=term-missing --cov-fail-under=8
 Validate that your agent follows the ASAP protocol:
 
 ```bash
-uv add asap-compliance
+uv add "asap-compliance>=1.3.0"
 pytest --asap-agent-url https://your-agent.example.com -m asap_compliance
 ```
 
+For **MCP Auth Bridge** stdio gates (`mcp-auth-bridge` profile), use **`asap-compliance` 1.3.0+** with **`asap-protocol` 2.5.0+** — published on PyPI via tag [`v2.5.0.1`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.5.0.1).
+
 See [Compliance Testing Guide](https://github.com/adriannoes/asap-protocol/blob/main/docs/guides/compliance-testing.md) for handshake, schema and state machine validation.
 
 ## Documentation
 
 **Learn**
-- [Docs](https://github.com/adriannoes/asap-protocol/blob/main/docs/index.md) | [API Reference](https://github.com/adriannoes/asap-protocol/blob/main/docs/api-reference.md)
-- [TypeScript client SDK](https://github.com/adriannoes/asap-protocol/blob/main/docs/sdks/typescript.md) — `@asap-protocol/client` (identity, capabilities, streaming, adapters)
+- [Docs](docs/index.md) | [API Reference](docs/api-reference.md)
+- [MCP Auth Bridge](docs/adapters/mcp-auth-bridge.md) — v2.5.0 opt-in JWT + capability grants for native stdio MCP
+- [TypeScript client SDK](docs/sdks/typescript.md) — `@asap-protocol/client` (identity, capabilities, streaming, adapters)
 - [Tutorials](https://github.com/adriannoes/asap-protocol/tree/main/docs/tutorials) — First agent to production checklist
 - [Migration from A2A/MCP](https://github.com/adriannoes/asap-protocol/blob/main/docs/migration.md)
 - [Raw Fetch (non-Python)](https://github.com/adriannoes/asap-protocol/blob/main/docs/raw-fetch.md) — Fetch registry.json and revoked_agents.json with curl/fetch; implement your own client.
@@ -222,17 +246,18 @@ See [Compliance Testing Guide](https://github.com/adriannoes/asap-protocol/blob/
 
 ```bash
 asap --version                                    # Show version
-asap list-schemas                                 # List all available schemas
-asap export-schemas                               # Export JSON schemas to file
-asap compliance-check --url https://agent.example # Compliance Harness v2 (HTTP(S))
+asap list-schemas                                 # List JSON schemas
+asap export-schemas                               # Export schemas to disk
+asap validate-schema payload.json                 # Validate JSON against a schema
+asap compliance-check --url https://agent.example # Remote Compliance Harness v2
 asap audit export --store memory --format json    # Export audit log (stdout)
-asap keys generate -o key.pem                     # Generate Ed25519 keypair
-asap manifest sign -k key.pem manifest.json       # Sign manifest
-asap manifest verify signed.json                  # Verify signature
-asap manifest info signed.json                    # Show trust level
+asap keys generate -o key.pem                     # Ed25519 keypair
+asap manifest sign -k key.pem manifest.json       # Sign agent manifest
+asap delegation create -d <urn> -s read -k key.pem --delegator <urn>
+asap trace <trace-id> --log-file asap.log         # Visualize request flow from logs
 ```
 
-See the [CLI reference](docs/cli.md) for `compliance-check` and `audit export` flag details, the [CI compliance gate](docs/ci-compliance.md) for wiring `compliance-check` into GitHub Actions, the [audit export guide](docs/audit.md), [Identity Signing](docs/guides/identity-signing.md), or run `asap --help` for the full command surface.
+See [docs/cli.md](docs/cli.md) for delegation tokens, schema validation, trace visualization, REPL, and full flag reference. Run `asap --help` for your installed version.
 
 ## Version History
 
@@ -240,7 +265,12 @@ High-level only — see **[Changelog](https://github.com/adriannoes/asap-protoco
 
 | Version | What shipped |
 | :-- | :-- |
-| **v2.4.0** | **Edge-AI discovery** — **[GitHub Release `v2.4.0`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.4.0)** · optional `hardware` / `inference` manifest fields, registry mirror, marketplace filters, **`@asap-protocol/client@2.4.0`**, ShellClaw onboarding docs. See [CHANGELOG](https://github.com/adriannoes/asap-protocol/blob/main/CHANGELOG.md#240---2026-05-24) and [Migration (v2.3.x → v2.4.0)](https://github.com/adriannoes/asap-protocol/blob/main/docs/migration.md#upgrading-from-v23x-to-v240) |
+| **v2.5.2** | **Security & correctness follow-up** — opt-in operator API auth, `extra="forbid"` ingress, Redis JTI replay, web distributed rate limits, v2.5.1 CR follow-ups (#245–#249), registry signed-manifest/400 fixes. See [CHANGELOG](CHANGELOG.md#252---2026-07-08), [PRD](product/prd/prd-v2.5.2-security-follow-up.md), and [Migration (v2.5.1 → v2.5.2)](docs/migration.md#upgrading-from-v251) |
+| **v2.5.1** | **Code quality patch** — behavior-preserving refactor (transport/server, client, websocket, SQLite storage, auth, integrations) + six correctness/security fixes (atomic `revoke_cascade`, `usage_events` DDL, unified Host-JWT verifier, **WS now enforces OAuth2**, OpenAPI handler cleanup, client `correlation_id` binding). Deprecated import paths removed in v2.6.0. See [CHANGELOG](CHANGELOG.md#251---2026-06-25) and [Migration (v2.5.0 → v2.5.1)](docs/migration.md#upgrading-from-v250-to-v251) |
+| **v2.5.0.1** | **Compliance publish** — **[GitHub Release `v2.5.0.1`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.5.0.1)** · PyPI **`asap-compliance` 1.3.0** (`mcp-auth-bridge` profile; requires `asap-protocol>=2.5.0`). No `asap-protocol` API change. See [CHANGELOG](CHANGELOG.md#2501---2026-06-24) |
+| **v2.5.0** | **MCP Auth Bridge** — **[GitHub Release `v2.5.0`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.5.0)** · opt-in `protect_server` for stdio MCP; Agent JWT + capability grants; reference example `examples/mcp_auth_bridge/`. See [CHANGELOG](CHANGELOG.md#250---2026-06-24) and [Migration (v2.4.1 → v2.5.0)](docs/migration.md#upgrading-from-v241-to-v250) |
+| **v2.4.1** | **Security hardening** — OAuth2 `iss`/`aud`, fail-closed identity binding, web SSRF/redirect fixes, dependency bumps. See [CHANGELOG](CHANGELOG.md#241---2026-06-14) and [Migration (v2.4.0 → v2.4.1)](docs/migration.md#upgrading-from-v240-to-v241) |
+| **v2.4.0** | **Edge-AI discovery** — optional `hardware` / `inference` manifest fields, registry mirror, marketplace filters, **`@asap-protocol/client@2.4.0`**, ShellClaw onboarding docs. See [CHANGELOG](CHANGELOG.md#240---2026-05-24) and [Migration (v2.3.x → v2.4.0)](docs/migration.md#upgrading-from-v23x-to-v240) |
 | **v2.3.1** | **npm TS patch** — **[GitHub Release `v2.3.1`](https://github.com/adriannoes/asap-protocol/releases/tag/v2.3.1)** · **`@asap-protocol/mastra`**, **`@asap-protocol/openai-agents`**, **`@asap-protocol/client@2.3.1`** (additive adapter exports). Python **2.3.0** unchanged. See [CHANGELOG](https://github.com/adriannoes/asap-protocol/blob/main/CHANGELOG.md#231---2026-05-20) and [Migration (v2.3.0 → v2.3.1)](https://github.com/adriannoes/asap-protocol/blob/main/docs/migration.md#upgrading-from-v230-to-v231) |
 | **v2.3.0** | **OpenAPI Adapter** (`[openapi]`) · **TypeScript client** (`@asap-protocol/client`) · **Auto-Registration** · **Capability escalation** · **ASAP HTTP challenge** — see [CHANGELOG](https://github.com/adriannoes/asap-protocol/blob/main/CHANGELOG.md#230---2026-05-04) and [Migration](https://github.com/adriannoes/asap-protocol/blob/main/docs/migration.md#upgrading-from-v22x-to-v230) |
 | **v2.2.1** | Opt-in **WebAuthn** (`asap-protocol[webauthn]`) · `asap compliance-check` & `asap audit export` · stricter `ResolvedAgent.run()` · `AuditChainBroken` · [pinned security deps](https://github.com/adriannoes/asap-protocol/blob/main/SECURITY.md#dependency-policy) |
@@ -254,7 +284,14 @@ High-level only — see **[Changelog](https://github.com/adriannoes/asap-protoco
 
 ## 🔭 What's Next?
 
-ASAP is evolving toward an **Agent Marketplace** — an open ecosystem where AI agents discover, trust and collaborate autonomously. See the [ADR index](https://github.com/adriannoes/asap-protocol/blob/main/product/decision-records/README.md) and [v2.0 roadmap PRD](https://github.com/adriannoes/asap-protocol/blob/main/product/prd/prd-v2.0-roadmap.md). Detailed long-term strategy narratives are maintained privately (not shipped in this repository).
+The [agentic marketplace](https://asap-protocol.com/) and Lite Registry are live. The **v2.5.x train** focuses on interop and adoption:
+
+- **v2.5.3** — enterprise/workflow adapter spikes (Adapter Lab II)
+- **v2.5.4** — distribution loop (homepage templates, starter kits, adoption metrics)
+- **`@asap-protocol/mcp-auth`** (npm) — HTTP/SSE MCP middleware
+- **Formal spec track** (v2.5.5) — introspection, privacy, cross-protocol interop on the path to v3.0 economy
+
+See the [v2.5 roadmap PRD](https://github.com/adriannoes/asap-protocol/blob/main/product/prd/prd-v2.5-roadmap.md) and [ADR index](https://github.com/adriannoes/asap-protocol/blob/main/product/decision-records/README.md).
 
 ## Contributing
 
@@ -266,11 +303,11 @@ Check out our [contributing guidelines](https://github.com/adriannoes/asap-proto
 
 ## Contact
 
-For **general questions** about the protocol, the marketplace, partnerships, or press (not security vulnerabilities — use [SECURITY.md](https://github.com/adriannoes/asap-protocol/blob/main/SECURITY.md) for those):
-
-- **Email:** [info@asap-protocol.com](mailto:info@asap-protocol.com)
-
-You can also use [GitHub Discussions](https://github.com/adriannoes/asap-protocol/discussions) or [Issues](https://github.com/adriannoes/asap-protocol/issues) for public project topics.
+| Channel | Use for |
+| --- | --- |
+| [GitHub Discussions](https://github.com/adriannoes/asap-protocol/discussions) or [Issues](https://github.com/adriannoes/asap-protocol/issues) | Public questions, bugs, and feature ideas |
+| [info@asap-protocol.com](mailto:info@asap-protocol.com) | Private coordination — protocol, marketplace, partnerships, press |
+| [SECURITY.md](SECURITY.md) | Security vulnerabilities only — **do not** use email or public issues |
 
 ## Privacy
 
@@ -282,4 +319,4 @@ This project is licensed under the Apache 2.0 License - see the [license](https:
 
 ---
 
-**Built with [Cursor](https://cursor.com/)** using Opus 4.6/4.7, Composer 1.5/2.0, Gemini 3.1 Pro and Kimi K2.5.
+**Built with [Cursor](https://cursor.com/)**, with Composer, Opus, Gemini, Kimi and more.