# @suaveplan/network-plugin-intra-relay - Intra-mesh peer-to-peer relay: RelayDiscovery (topology-driven candidate set with leaf exclusion), RelaySelector (5 strategies — LowestLatency / HighestReliability / FewestHops / TierOptimized / LoadBalanced), RelayConnectionManager (pending → active → degraded → closed FSM), RelayMessageEnvelope (hop-count + visited-nodes wrapper), LoopPrevention, RelayPerformanceMonitor, RelaySecurityManager (peer authentication, ed25519 signature validation, per-peer + global token-bucket rate limiting), and IntraRelayPlugin facade.

## Summary

Intra-mesh peer-to-peer relay for the Suaveplan network. When direct WebRTC fails (symmetric NAT, restrictive firewall), `IntraRelayPlugin` routes the message through an intermediate peer in the same mesh. `RelayDiscovery` builds a candidate set from `peer:connected` bus events and explicitly excludes leaf-tier peers (which lack forwarding capacity); `RelaySelector` picks the optimal relay using one of five strategies (`lowest-latency`, `highest-reliability`, `fewest-hops`, `tier-optimized`, `load-balanced`) with a deterministic peer-id tiebreak; `RelayConnectionManager` runs a `pending → active → degraded → closed` finite-state machine per `(sourceId, targetId)` pair and auto-closes paths after a configurable idle timeout; `RelayMessageEnvelope` wraps the original `MessageEnvelope` with `relayPath` / `hopCount` / `maxHops` / `visitedNodes`; `LoopPrevention` drops envelopes that exceed `maxHops` (default 8) or whose `visitedNodes` already contain the current peer, emitting `relay:loop-detected` for observability; `RelayPerformanceMonitor` samples per-path RTT and emits `relay:degraded` / `relay:recovered` when quality crosses configurable thresholds; `RelaySecurityManager` (optional, opt-in via `IntraRelayPluginConfig.security`) enforces a trusted-peer allowlist, validates `ed25519` signatures over canonical bytes, and applies per-peer + global token-bucket rate limits to prevent DoS. Wrapped in a single `IntraRelayPlugin` satisfying the `NetworkPlugin` lifecycle.

<!-- begin:auto-docs -->
## Documentation tree

- [connection](./src/connection/relay-connection-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [relay-connection-manager](./src/connection/relay-connection-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [relay-discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [relay-envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [loop](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [loop-prevention](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [relay-performance-monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [intra-relay-plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [security](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [relay-security-manager](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [relay-selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [error-codes](./src/error-codes.md) — Frozen `NET_INTRA_RELAY` error registry for `@suaveplan/network-plugin-intra-relay`. Every failure path the relay subsy…
<!-- end:auto-docs -->  - [relay-connection-manager](./src/connection/relay-connection-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_- [loop](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_- [loop-prevention](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_- [monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-performance-monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [intra-relay-plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-security-manager](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_INTRA_RELAY` error registry for `@suaveplan/network-plugin-intra-relay`. Every failure path the relay subsy…
- [relay-connection-manager](./src/connection/relay-connection-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_- [loop](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_- [loop-prevention](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_- [monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-performance-monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [intra-relay-plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-security-manager](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_INTRA_RELAY` error registry for `@suaveplan/network-plugin-intra-relay`. Every failure path the relay subsy…
- [relay-connection-manager](./src/connection/relay-connection-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_- [loop](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_- [loop-prevention](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_- [monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-performance-monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [intra-relay-plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-security-manager](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_- [relay-selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_INTRA_RELAY` error registry for `@suaveplan/network-plugin-intra-relay`. Every failure path the relay subsy…
- [relay-connection-manager](./src/connection/relay-connection-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_  - [relay-discovery](./src/discovery/relay-discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_  - [relay-envelope](./src/envelope/relay-envelope.md) — <!-- begin:auto-docs --> _(no submodules)_- [loop](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_  - [loop-prevention](./src/loop/loop-prevention.md) — <!-- begin:auto-docs --> _(no submodules)_- [monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_  - [relay-performance-monitor](./src/monitor/relay-performance-monitor.md) — <!-- begin:auto-docs --> _(no submodules)_- [plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_  - [intra-relay-plugin](./src/plugin/intra-relay-plugin.md) — <!-- begin:auto-docs --> _(no submodules)_- [security](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_  - [relay-security-manager](./src/security/relay-security-manager.md) — <!-- begin:auto-docs --> _(no submodules)_- [selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_  - [relay-selector](./src/selector/relay-selector.md) — <!-- begin:auto-docs --> _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_INTRA_RELAY` error registry for `@suaveplan/network-plugin-intra-relay`. Every failure path the relay subsy…

## Modules

- [Connection](src/connection/relay-connection-manager.md)
- [Discovery](src/discovery/relay-discovery.md)
- [Envelope](src/envelope/relay-envelope.md)
- [Error codes](src/error-codes.md)
- [Loop prevention](src/loop/loop-prevention.md)
- [Performance monitor](src/monitor/relay-performance-monitor.md)
- [Plugin facade](src/plugin/intra-relay-plugin.md)
- [Security manager](src/security/relay-security-manager.md)
- [Selector](src/selector/relay-selector.md)
- [Types — relay](src/types/relay.types.md)
- [Types — security](src/types/security.types.md)