fix(agent-mesh): skip flask-dependent raw-target tests without flask

Two tests added with the raw request-target work imported Flask through a
shared helper while the file's `flask` skip marker was defined below them,
so they ran unguarded and failed collection wherever Flask is absent. That
broke `test (agent-mesh, 3.11/3.12/3.13)` and `docker-compose-test`.

Move the existing marker above its first use and apply it to just those two
tests, not the class, so the three raw-target regressions that need no
framework keep running everywhere. Verified in a Flask-free virtualenv:
the two tests skip and the rest pass.

Also document the v2 signing envelope: undecoded request target, target
mode, server-chosen covered headers, verification deadlines, and
`install_fastapi_trust`. Drop the four references to the HTTP middleware
guide that pointed at a file which was never tracked.

Signed-off-by: Prayag Upadhyay <prayag.upd@gmail.com>

Author: prayagupa

BREAKING_CHANGES.md

@@ -5,6 +5,64 @@ entries appear first.
 
 ---
 
+## `TrustMiddleware` requires signed requests and an explicit trust anchor
+
+**Date:** TBD
+
+**Affected**
+
+- `agentmesh.integrations.TrustMiddleware` and the Flask/FastAPI decorators
+  `flask_trust_required` / `fastapi_trust_required`
+- any client that authenticated by sending only an `X-Agent-DID` header
+
+**What changed**
+
+`TrustMiddleware` treated a caller-supplied `X-Agent-DID` header as proof of
+identity: `verify_request` started from a trust score of `1.0` and only lowered
+it inside an `except` branch that could never run, because
+`AgentIdentity.verify_signature` returns a `bool` and never raises. Any caller
+who set the header was verified with full trust, and `X-Agent-Capabilities` was
+honoured as self-asserted authorization.
+
+Callers now prove possession of a registered Ed25519 key over a canonical
+envelope binding DID, audience, timestamp, nonce, method, undecoded request
+target, target mode, covered request headers, and body digest, with single-use
+nonce replay protection. Verification keys and capabilities come only from a
+peer resolver, never from headers — `did:mesh` identifiers are random rather
+than key-derived, so a DID is not self-certifying and a presented public key can
+never authenticate anyone.
+
+**How to update**
+
+Servers:
+
+| Before | After |
+|--------|-------|
+| `TrustMiddleware(identity)` | `TrustMiddleware.from_registry(registry, TrustConfig(audience=...))`; `audience`, `peer_resolver` and `replay_cache` are required and raise `ValueError` when missing |
+| `verify_request(headers)` | Pass `method`, `request_target` and `body`; omitting them fails closed with `500` |
+| `TrustConfig(permissive_mode=True)` | Also set `required_trust_score=0.0` and remove `required_capabilities` |
+| Anonymous callers reached `*_trust_required` | Use `flask_trust_optional` / `fastapi_trust_optional` and branch on `result.authenticated` |
+| `err["reason"]` on a `401` | Removed from the client-visible body; read `result.reason` server-side |
+| `VerificationResult` was mutable | Now frozen, and gained `authenticated` |
+| `TrustConfig` was mutable | Now frozen; assigning a field after construction raises `FrozenInstanceError` |
+| `TrustConfig(required_capabilities="admin")` | Rejected with `ValueError`; pass a sequence such as `("admin",)`. A bare string was silently expanded into five single-character capabilities |
+| A raising `peer_resolver` yielded `401` | Now `503`. A registry outage is a server fault, not a credential failure |
+| Custom `replay_cache` returned `False` when full | Must now raise `ReplayCacheFull`, which yields `503`. `False` still means "nonce already used" and yields `401` |
+| FastAPI body limit | Build the dependency with `install_fastapi_trust(app, middleware)`, which installs the pre-routing `SignedBodyLimitMiddleware` guard and binds the dependency to it. The dependency alone runs after FastAPI has buffered the body, and now fails closed with `500` if the guard is absent |
+| The signed target was the percent-decoded path | It is now the undecoded target, read from `RAW_URI`/`REQUEST_URI`/`scope["raw_path"]`. Servers that publish none of these fail with `500` until you set `request_target_mode="decoded"` (or `AGENTMESH_REQUEST_TARGET_MODE`). Django's `runserver` and `RequestFactory` are in this group; gunicorn, uWSGI and mod_wsgi are not |
+| `build_request_signature_payload(..., content_type=...)` | Pass `target_mode=` and `signed_headers=` instead. Covered headers are chosen by the server via `TrustConfig.signed_header_names` (default `("content-type",)`), and an absent header is omitted rather than signed as `""` |
+| Verification had no time bound | `TrustConfig.io_timeout_seconds` (default `5.0`) budgets the whole verification. Resolvers and replay caches that declare a `timeout_seconds` parameter receive the remaining budget; exhaustion denies with `503` before the nonce is consumed |
+| Django exempt views saw `request.agent_did` | Exempt views and exempt path prefixes verify nothing and now set `agent_did=None`, `agent_trust_score=None`, `agent_authenticated=False`. Check `request.agent_authenticated` first |
+
+Clients must sign each request; `build_request_signature_payload` in
+`agent-governance-python/agent-mesh/src/agentmesh/integrations/request_auth.py`
+builds the canonical envelope and is the authority on its contents.
+
+Both sides must be upgraded together: an unpatched client cannot authenticate
+against a patched server, by design.
+
+---
+
 ## `HostSession.post_tool_call` and `pre_model_call` emit the adapter snapshot shape
 
 **Date:** TBD

agent-governance-python/agent-mesh/AGENTS.md

@@ -60,7 +60,8 @@ black --check .
 - All data models use Pydantic `BaseModel`
 - Identity: `AgentIdentity` with `.sign(data: bytes) -> str` (base64 Ed25519 signatures)
 - Trust scores: 5 dimensions — competence, integrity, availability, predictability, transparency
-- DID format: `did:mesh:{hex}` — derived from public key
+- DID format: `did:mesh:{hex}` — see the proof-of-possession note under Boundaries: `registry/app.py`
+  derives DIDs from the public key, while `AgentDID.generate` mints a random identifier
 - Private keys stored as `_private_key` (never serialized)
 - AICard: `from_identity()` creates signed cards; `from_trusted_agent_card()` bridges existing formats
 - Tests in `tests/` directory
@@ -70,7 +71,8 @@ black --check .
 - **Never serialize** private keys in JSON/YAML output
 - **Never commit** secrets, API keys, or credentials
 - **Never weaken** trust thresholds — only tighten
-- **Never accept public keys without proof-of-possession** — any HTTP endpoint that accepts a `public_key` or `verification_key` MUST verify the caller controls the corresponding private key via Ed25519 signature over `(key || timestamp)`. DIDs MUST be derived from `SHA-256(public_key)`, never client-supplied. See `registry/app.py` for the reference implementation. CI enforces this via `scripts/ci/no-unauthed-registration.sh`.
+- **Never accept public keys without proof-of-possession** — any HTTP endpoint that accepts a `public_key` or `verification_key` MUST verify the caller controls the corresponding private key via Ed25519 signature over `(key || timestamp)`. DIDs issued by the registry MUST be derived from `SHA-256(public_key)`, never client-supplied. See `registry/app.py` for the reference implementation. CI enforces this via `scripts/ci/no-unauthed-registration.sh`.
+- **A `did:mesh` identifier is not self-certifying** — `AgentDID.generate` mints a random identifier (`secrets.token_hex(16)`, `identity/agent_id.py`), so it is *not* derived from the key and carries no cryptographic binding to one. Only registry-issued DIDs are key-derived. Consequently, request authentication MUST resolve the DID's key through a trusted registry and MUST NOT trust a caller-supplied public key, even when it "matches" the DID. See `integrations/request_auth.py`.
 - Keep backward compatibility with existing protocol messages
 - the repo root are standalone — changes there need their own test suite
 

agent-governance-python/agent-mesh/CHANGELOG.md

@@ -9,6 +9,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+- **HTTP trust middleware request authentication.** `TrustMiddleware` no longer
+  accepts a caller-supplied `X-Agent-DID` header as proof of identity. It
+  previously started from a trust score of `1.0` and only lowered it inside an
+  `except` branch that could never execute, so any caller who set the header was
+  verified with full trust and `X-Agent-Capabilities` was honoured as
+  self-asserted authorization. Callers now prove possession of a registered
+  Ed25519 key over a canonical envelope binding DID, audience, timestamp, nonce,
+  method, undecoded request target, target mode, covered request headers, and
+  body digest, with single-use nonce replay protection. Verification keys and
+  capabilities are resolved only from a
+  trusted registry, never from request headers. The Flask, FastAPI, and Django
+  integrations now share one envelope implementation, and the header lookup is
+  case-insensitive so the FastAPI path no longer silently misses the trust
+  headers Starlette lowercases. See `BREAKING_CHANGES.md` — clients must be
+  upgraded alongside servers.
+- **The signed target is the undecoded one.** Signing the percent-decoded path
+  made `/files/a%2Fb` and `/files/a/b` produce identical signed bytes, so a
+  signature captured for one was valid for the other wherever a proxy, gateway,
+  or audit log reads the target before the application decodes it. All three
+  integrations now sign the raw origin-form target from `RAW_URI`,
+  `REQUEST_URI`, or `scope["raw_path"]`, and servers that publish none of these
+  fail with `500` rather than silently downgrading. `target_mode` travels inside
+  the signed bytes, so a raw↔decoded downgrade fails closed.
+- **Covered headers are chosen by the server and bind presence.** `Content-Type`
+  was signed as `""` when absent, so an attacker could add one the signer never
+  sent — enough to change how a body is parsed. Headers named by
+  `TrustConfig.signed_header_names` are now omitted from the envelope when
+  absent, so adding or stripping one invalidates the signature. The covered set
+  is server-configured rather than caller-declared, so a caller cannot narrow
+  its own coverage.
+- **Verification is time-bounded.** `TrustConfig.io_timeout_seconds` (default
+  `5.0`) budgets an entire verification rather than each dependency call, so a
+  slow peer resolver cannot hand its remaining time to a slow replay cache. The
+  remaining budget is passed to resolvers and caches that declare a
+  `timeout_seconds` parameter, the budget is re-checked before the nonce is
+  consumed so a doomed request never burns a single-use nonce, and exhaustion
+  denies with `503`.
+- **Django exempt routes no longer publish an unverified DID.** `@trust_exempt`
+  views and exempt path prefixes copied the attacker-controlled `X-Agent-DID`
+  header onto `request.agent_did`, so a view that logged or authorized on it
+  received a value nothing had verified. Exempt and denied requests now set
+  `agent_did=None`, `agent_trust_score=None`, and `agent_authenticated=False`.
+- **`@trust_required(min_score=0)` still requires authentication.** The Django
+  gate compared only the trust score, so a zero floor admitted a caller whose
+  signature had failed — a deliberately open route silently became an
+  unauthenticated one. Authentication is now checked before the score.
+- **Anonymous callers cannot reach protected routes.** `flask_trust_required`
+  and `fastapi_trust_required` reject any result that is not cryptographically
+  authenticated, so a `permissive_mode` deployment no longer admits an
+  unauthenticated caller to a route that requires capabilities. Serving
+  anonymous callers now requires the explicitly-named `flask_trust_optional` /
+  `fastapi_trust_optional` variants, and `TrustConfig` refuses to combine
+  `permissive_mode` with an authorization gate.
+- **Unauthenticated request-handling hardening.** The signed body is read
+  against `max_signed_body_bytes` before buffering, so an unauthenticated caller
+  cannot force unbounded memory allocation; `install_fastapi_trust` installs the
+  pre-routing body guard and returns a dependency bound to it, and that
+  dependency now fails closed with `500` when the guard is absent rather than
+  verifying a body FastAPI has already buffered without limit; a presented
+  public key is compared as
+  decoded bytes rather than base64 text, so a non-ASCII header value can no
+  longer raise inside the auth path; `401` responses no longer disclose which
+  DIDs are registered; DIDs are bounded and charset-checked before reaching a
+  resolver or a log sink; replay-cache exhaustion is reported as `503` rather
+  than being recorded as a replay attempt; and replay keys are namespaced by
+  audience so services sharing a cache cannot burn each other's nonces.
+- **Server faults are no longer reported as authentication failures.** A peer
+  resolver that raises, an unreadable request body, and any unexpected internal
+  error now return `503` instead of `401`, so an identity-store outage cannot
+  masquerade as every caller presenting bad credentials and stays visible to
+  alerting keyed on server errors. `TrustConfig` is frozen so the
+  `permissive_mode` guard cannot be voided by post-construction assignment, and
+  it rejects a bare string for `required_capabilities`, which was previously
+  expanded character-by-character into an unsatisfiable authorization gate.
+- **Denial telemetry and decorator hardening.** Pre-authentication failures stay
+  at `DEBUG` so they cannot be used to flood logs, but each distinct denial
+  reason now also emits a rate-limited `WARNING` carrying a coarse reason and
+  status — never the DID — so an attack is visible at default log levels. The
+  Flask and FastAPI decorators extend `verify_request`'s never-raise guarantee
+  over the body read that precedes it, and both derive the signed request target
+  from the raw query bytes, so a client disconnect or a non-UTF-8 query no longer
+  produces a `500` and both frameworks sign identical payloads. Internal-fault
+  tracebacks are emitted at most once per minute per call site, so a failing peer
+  resolver cannot amplify one fault into an `ERROR` traceback per request, and a
+  missing-capability denial is now logged with the agent's DID so privilege
+  probing by an authenticated agent is visible.
 - **AgentMesh transport message authentication.** `MeshClient` no longer lets a
   sender-supplied `plaintext` wire flag select the legacy no-crypto receive path;
   whether an inbound message is treated as plaintext is decided solely by the

agent-governance-python/agent-mesh/docs/integrations/django-middleware.md

@@ -56,8 +56,9 @@ Every authenticated request requires these headers:
 | `X-Agent-Nonce` | Unique base64url value containing 16 to 64 random bytes |
 | `X-Agent-Signature` | Base64-encoded Ed25519 signature of the canonical request payload |
 
-Use `build_request_signature_payload` to produce the canonical bytes. The path must include the
-query string in its transmitted order, and `body` must contain the exact bytes sent on the wire.
+Use `build_request_signature_payload` to produce the canonical bytes. `request_target` must be the
+**undecoded** target exactly as it goes on the wire, including the query string in its transmitted
+order, and `body` must contain the exact bytes sent.
 
 ```python
 import base64
@@ -80,8 +81,9 @@ payload = build_request_signature_payload(
     nonce=nonce,
     method="POST",
     request_target="/v1/payments?mode=immediate",
+    target_mode="raw",
     body=body,
-    content_type=content_type,
+    signed_headers={"content-type": content_type},
 )
 signature = base64.b64encode(private_key.sign(payload)).decode("ascii")
 
@@ -94,9 +96,45 @@ headers = {
 }
 ```
 
-The signed envelope binds the DID, configured audience, timestamp, nonce, HTTP method, path and
-query, content type, and SHA-256 body digest. Changing any of these values invalidates the
-signature. A correctly signed nonce is accepted once and retained in the replay cache for the
-configured replay window. Cache errors fail closed.
+The signed envelope binds the DID, configured audience, timestamp, nonce, HTTP method, undecoded
+request target, target mode, covered request headers, and SHA-256 body digest. Changing any of
+these values invalidates the signature. A correctly signed nonce is accepted once and retained in
+the replay cache for the configured replay window. Cache errors fail closed with `503`.
+
+Only headers that are actually present are covered, so *removing* `Content-Type` invalidates the
+signature just as surely as changing it. The covered set is chosen by the server
+(`AGENTMESH_SIGNED_HEADERS`), never declared by the caller — a caller who could pick which headers
+are signed could simply decline to sign the ones that matter.
+
+### Undecoded request targets
+
+`AGENTMESH_REQUEST_TARGET_MODE` defaults to `"raw"`, which signs the target as sent. This requires
+a WSGI server that publishes it as `RAW_URI` or `REQUEST_URI` — gunicorn, uWSGI, and mod_wsgi all
+do. Django's `runserver` and `RequestFactory` do **not**, so the middleware returns `500` with an
+actionable message rather than silently verifying something weaker.
+
+For development, set:
+
+```python
+AGENTMESH_REQUEST_TARGET_MODE = "decoded"
+```
+
+`"decoded"` signs Django's percent-decoded `request.path`, which cannot distinguish `/files/a%2Fb`
+from `/files/a/b`. Both forms travel inside the signed bytes, so a signature produced in one mode
+is never accepted in the other.
+
+### Identity attributes on the request
+
+After the middleware runs, views can read:
+
+| Attribute | Meaning |
+|-----------|---------|
+| `request.agent_authenticated` | `True` only when a signature verified |
+| `request.agent_did` | Verified DID, or `None` |
+| `request.agent_trust_score` | Verified score, or `None` |
+
+Check `request.agent_authenticated` before acting on `request.agent_did`. Exempt views and exempt
+path prefixes verify nothing, so they set `agent_did` to `None` — the raw `X-Agent-DID` header is
+attacker-controlled and is never published to application code.
 
 Signatures over only the agent DID are not accepted.