Initial Commit

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

@@ -0,0 +1,29 @@
+# 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`).