30 lines
2.0 KiB
Markdown
30 lines
2.0 KiB
Markdown
# 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`).
|