closedhumanPR #146Communication

: add replay-safe comms plugin with sequence-bound envelopes

A new replay_safe comms plugin that extends authenticated with replay attack detection via per-peer monotonic sequence numbers. This PR closes the gap explicitly called out in PR #114:

Author

AdityaDarke97 avatar

@AdityaDarke97

github profile →
Status
Closed without merging
Opened on
Jul 9
Branch
feat/replay-safe-comms

Description

The pitch.

## What this adds

A new `replay_safe` comms plugin that extends `authenticated` with **replay attack detection** via per-peer monotonic sequence numbers. This PR closes the gap explicitly called out in PR #114:

> "out scope replay: a verbatim re-send of a genuine envelope still verifies. Bind a nonce/sequence into metadata to close that separately."

## Why this matters

`authenticated` solved **tamper-evidence** (HMAC-SHA256 over the envelope detects version rollback and field stripping). However, it has a critical vulnerability: **a captured genuine envelope can be replayed verbatim, and the receiver cannot tell.**

Two concrete attacks slip through `authenticated`:
1. **Message Replay:** An adversary captures a legitimate `bid:item-1:100` envelope and re-sends it later. The receiver processes it again, double-counting the bid.
2. **State Manipulation:** An adversary replays a `rotate:key:old:new` envelope to force an agent to re-apply an old rotation, potentially resurrecting a compromised key.

## Empirical Proof

I wrote adversarial validators that test both plugins:

```python
from nest_plugins_reference.comms.authenticated import AuthenticatedComms
from nest_plugins_reference.comms.replay_safe import ReplaySafeComms
from nest_plugins_reference.validators import (
    check_comms_replay_rejected,
)

# Test authenticated (should FAIL - allows replay)
alice_auth = AuthenticatedComms(AgentId("alice"))
envelope = alice_auth.serialize(msg)
result_auth = check_comms_replay_rejected(alice_auth, envelope, "alice", "bob")
print(f"Authenticated allows replay: {not result_auth}")  # True

# Test replay_safe (should PASS - rejects replay)
alice_safe = ReplaySafeComms(AgentId("alice"))
envelope = alice_safe.serialize(msg)
result_safe = check_comms_replay_rejected(alice_safe, envelope, "alice", "bob")
print(f"ReplaySafe rejects replay: {result_safe}")  # True
```
Result:

    authenticated → FAILS (allows replay attacks)
    replay_safe → PASSES (rejects replay attacks)

How it works
Each agent maintains a per-peer sequence counter that increments with every outgoing message. The receiver tracks the highest seen sequence per peer and rejects any envelope with a sequence number ≤ the last accepted value.
Key features:

    Strict superset of authenticated: Inherits HMAC authentication, version negotiation, and unknown-field preservation
    Sliding window buffer: Handles out-of-order delivery (up to WINDOW_SIZE=10 messages ahead)
    Per-peer tracking: Sequences are independent for each sender-receiver pair

Scenario File
Added scenarios/comms_replay_attack.yaml that runs 10 peers through the replay_safe comms plugin:

    Task: Reuses comms_versioning traffic generator
    Failures: message_drop: 0.05 — intentionally drops 5% of packets to trigger and verify the sliding window out-of-order buffer
    Output: Generates traces/comms_replay_attack.jsonl for trace validation
    
Test Results
All 8 unit tests pass:

uv run pytest packages/nest-plugins-reference/tests/test_replay_safe.py -v

test_serialize_deserialize_roundtrip PASSED
test_sequence_increments PASSED
test_replay_rejected PASSED
test_adversarial_validator_replay PASSED
test_adversarial_validator_rollback PASSED
test_different_peers_independent_sequences PASSED
test_concurrent_sending_no_duplicates PASSED
test_out_of_order_delivery_buffering PASSED

8 passed

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/146/head:pr-146
git checkout pr-146