docs(crypto): verify_attestation docstring claims 'Verifies a sender's JWT signature' — false trust signal in security API

[rahuldass19]

Audit Finding — New (cross-references existing #19)

What's happening

crypto.py:156 contains a docstring on the verify_attestation method that is factually wrong:

def verify_attestation(
    self, token: str
) -> Tuple[bool, Optional[Dict[str, Any]], Optional[str]]:
    """
    Verifies a sender's JWT signature for a given message payload.
    ...

The method:

1. Does not verify a "sender's JWT signature" — it verifies the interceptor's own attestation (signed with the interceptor's ES256 key)
2. Does not take "a given message payload" as input — it takes a token: str only, with no payload or context parameter
3. Does not perform sender signature verification — that capability does not exist in the codebase (see issue fix(schema): AgentMessage.signature field accepted but never verified — creates false trust signal #19)

Why this matters

This docstring creates a false trust signal in the code itself:

• A developer reading the docstring reasonably believes verify_attestation() verifies message sender signatures
• The method name + docstring together claim a capability that does not exist
• Unlike issue fix(schema): AgentMessage.signature field accepted but never verified — creates false trust signal #19 (which is about the AgentMessage.signature field being unverified), this is about the crypto API itself claiming it verifies something it doesn't
• This is a documentation bug in the security-sensitive API — the risk is that integrators rely on this claimed capability

Current behavior

verify_attestation(token)
  → docstring claims: "Verifies a sender's JWT signature for a given message payload"
  → actual: verifies token was signed by THIS interceptor, no sender or payload context
  → misleading

Expected behavior

Docstring must accurately describe what the method does:

verify_attestation(token)
  → docstring: "Verifies that a JWT attestation token was issued by this interceptor instance.
     Validates signature, expiration, and required claims (iss, sub, iat, exp, jti).
     Returns (True, claims, None) if the token is valid and not expired."
  → no false claims about sender verification or payload binding

Or, if the intent is to eventually add sender signature verification here, the docstring should clearly say "NOT YET IMPLEMENTED."

Files to change

• src/qwed_a2a/security/crypto.py:156 — correct the verify_attestation() docstring

Acceptance criteria

• Docstring accurately describes what the method actually does
• No mention of "sender's JWT signature" or "given message payload"
• If the method remains context-free, document this limitation explicitly
• Cross-reference linked issues (fix(schema): AgentMessage.signature field accepted but never verified — creates false trust signal #19, fix(crypto): verify_attestation() checks signature only — no context-binding, enables detached attestation acceptance #14) for context-binding and sender signature verification when implemented