suaveplan/openspec/archive/2026-05-10-network-plugin-intra-relay-security/proposal.md

OpenSpec Change: network-plugin-intra-relay-security

• Change ID: network-plugin-intra-relay-security
• Package: @suaveplan/network-plugin-intra-relay (extension)
• Status: PROPOSED
• Type: extension
• Date: 2026-05-05

Why

The core network-plugin-intra-relay change shipped the relay primitives (discovery, selection, FSM, envelope, loop prevention, performance monitor) but deferred RelaySecurityManager per the parent proposal's ## Deferred to follow-up changes block. The security manager couples to network-plugin-crypto-messages for PeerIdentityVerifier and adds per-peer relay rate limiting; both warranted their own design + test surface rather than landing inline with the core.

This change adds RelaySecurityManager to the existing package without breaking the core surface.

What changes

• ADDED: RelaySecurityManager class — authenticates relay nodes using the PeerIdentityVerifier from @suaveplan/network-plugin-crypto-messages, validates relay-message signatures, and enforces per-peer relay rate limits to prevent DoS.
• ADDED: RelayAuthPolicy — { requireSignature: boolean; trustedPeers: ReadonlySet<string> } for callers that want to allowlist a specific relay set.
• ADDED: RelayRateLimit — { maxMessagesPerSecond: number; burstSize: number } token-bucket configuration.
• ADDED: Three error codes appended to NETWORK_INTRA_RELAY_CODES: RELAY_SIGNATURE_INVALID, RELAY_PEER_UNTRUSTED, RELAY_RATE_LIMIT_EXCEEDED.
• ADDED: IntraRelayPlugin.security getter wires the new subsystem onto the plugin facade.

Verification approach

• src/security/relay-security-manager.spec-conformance.test.ts — pins peer-identity verification, signature validation, rate-limit enforcement (per-peer + global), trusted-peer allowlist, signature-required toggle.

Migration impact

None — additive only. Existing consumers of IntraRelayPlugin see one new optional config field (security?: RelaySecurityConfig).