docs: add security considerations and threat model for Partial Messages extension

[adarsh-7-satyam]

Description

The Partial Messages extension for Gossipsub 1.4 introduces a fundamentally different message propagation model where peers exchange fragments of large payloads rather than complete messages. While this dramatically reduces bandwidth in high-throughput environments like Ethereum's Data Availability Sampling, it also introduces an entirely new class of attack vectors that do not exist in standard Gossipsub. The current partial-messages.md specification addresses security in a single paragraph, advising implementations to "limit peer-initiated state" without specifying how or what limits to apply. This leaves every implementation team — from py-libp2p to nim-libp2p — to independently discover and mitigate these threats, often only after encountering them in production.

Problem

There is no formal threat model for the Partial Messages extension anywhere in the specification repository. The existing Gossipsub security mechanisms defined in gossipsub-v1.1.md (Peer Scoring, Spam Caps) and red.md (Random Early Drop) were designed for full message propagation and do not account for the new state management challenges introduced by groupID tracking, partsMetadata exchange, and application-layer reassembly.

Changes Made

Added a new document pubsub/gossipsub/security-considerations.md that provides a comprehensive security and threat model for the Partial Messages extension. The document is structured as follows:

Existing Security Foundations — Enumerates the existing v1.1 and v1.2 security mechanisms that implementations MUST maintain when adding Partial Messages support, including Peer Scoring (P4, P7), RED, control message caps, IDONTWANT limits, and PRUNE backoff.

Threat Model — Identifies and details six new attack vectors specific to the Partial Messages extension:

1. GroupID State Exhaustion — An attacker floods a node with unique groupIDs causing memory exhaustion in partsMetadata tracking. Mitigated by per-peer groupID limits and LRU cache eviction.
2. Bandwidth Amplification — A small partsMetadata request triggers a disproportionately large partialMessage response, reaching ~32x amplification in Ethereum DAS contexts. Mitigated by response budgets and per-peer rate limits, drawing on QUIC's 3x amplification limit as prior art.
3. Incomplete Group Buffering — An attacker sends most parts of a message group but withholds the final parts, exhausting reassembly buffers indefinitely. Mitigated by application-level timeouts and purging mechanisms.
4. Malicious Metadata Flooding — Excessive partsMetadata updates that do not reflect actual peer state waste CPU on diffing and bandwidth on redundant signaling. Mitigated by rate limiting metadata updates per peer per heartbeat.
5. Cache Probing — An attacker sends partsMetadata for an unknown groupID to probe whether a node has data cached before global announcement, leaking private cache state. Mitigated by a seen-check that ignores partsMetadata for groupIDs not in the mcache.
6. Reassembly CPU Attack — Malformed parts requiring expensive cryptographic verification like KZG proofs are used to cause CPU DoS. Mitigated by RED integration and strict P7 penalties for peers sending invalid parts.

Application-Library Interface Security Requirements — Since partsMetadata and partialMessage are application-defined opaque bytes, the Gossipsub library cannot validate them directly. This section specifies that the interface MUST allow the application to signal P7 Behavioural Penalties back to the library, drawing on BitTorrent piece hashes as prior art for part integrity verification.

Implementation Checklist — An actionable checklist of seven security requirements that implementations MUST verify before deploying Partial Messages support.

How It Solves The Problem

By providing a shared formal threat model with concrete mitigations, this document gives all Gossipsub implementation teams a common reference for building secure Partial Messages support. Rather than each team discovering these vulnerabilities independently, they can use this document as a security review checklist during implementation and audit.

Impact

• Reduces the risk of security incidents in production deployments of Gossipsub 1.4 Large Message Handling
• Provides a shared vocabulary for security discussions across implementation teams
• Strengthens the specification's readiness for Candidate Recommendation status by addressing security considerations as required by the libp2p spec lifecycle
• Directly supports safe interoperability validation between py-libp2p and nim-libp2p

Related Issue

Closes #14