Fix #865: RFC: Security middleware layer for uAgent message handlers ...

[JiwaniZakir]

Closes #865

Proposed Changes

Adds an allowed_senders parameter to Protocol.on_message (and the corresponding Agent.on_message wrapper) that restricts handler execution to a declared set of agent addresses.

python/src/uagents/protocol.py

• Protocol.on_message and Protocol._add_message_handler accept a new allowed_senders: set[str] | None parameter.
• When allowed_senders is provided, _add_message_handler wraps the original callback in _guarded, an async closure that checks sender against a frozenset of permitted addresses. Unauthorized senders produce a logger.warning and return without invoking the handler.

python/src/uagents/agent.py

• Agent.on_message passes the new allowed_senders argument through to self._protocol.on_message.

python/tests/test_protocol.py

• test_protocol_allowed_senders_registered: confirms the handler digest is stored in _signed_message_handlers when allowed_senders is set.
• test_protocol_allowed_senders_blocks_unauthorized: exercises the _guarded wrapper end-to-end — verifies an unauthorized sender is dropped and an authorized sender reaches the callback.

Linked Issues

Addresses the authorization gap described in #865: any signed message from any registered agent could trigger any handler regardless of whether the receiving agent should accept commands from that sender.

Types of changes

• Bug fix (non-breaking change that fixes an issue).
• New feature added (non-breaking change that adds functionality).
• Breaking change (fix or feature that would cause existing functionality to stop working as expected).
• Documentation update.
• Something else (e.g., tests, scripts, example, deployment, infrastructure).

Checklist

• I have read the CONTRIBUTING guide
• Checks and tests pass locally

If applicable

• I have added tests that prove my fix is effective or that my feature works
• I have added/updated the documentation (executed the script in python/scripts/generate_api_docs.py)

Further comments

This is a minimal, in-framework authorization primitive that doesn't require an external policy gateway. It operates at the handler registration site, so the allow-list is co-located with the handler definition and remains visible in code review. The frozenset conversion in _add_message_handler ensures the provided set is not mutated after registration.

The _guarded wrapper only applies when allowed_senders is not None; omitting the parameter preserves existing behaviour exactly. No existing handler registration paths are affected.

This approach is intentionally narrower in scope than the full SINT middleware proposed in #865 — it addresses the most common case (static allow-lists known at registration time) without introducing a runtime policy dependency. Dynamic or tier-based authorization (T0–T3 approval flows, rate limiting, CSML drift detection) remains out of scope for this PR and would require a separate middleware hook point in the dispatch layer.

---

This PR was created with AI assistance (Claude). The changes were reviewed by quality gates and a critic model before submission.