# 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`).