# OpenSpec Change: network-plugin-intra-relay

- **Change ID**: network-plugin-intra-relay
- **Package**: `@suaveplan/network-plugin-intra-relay` (new)
- **Status**: PROPOSED
- **Type**: new-package
- **Date**: 2026-04-29

## Why

The WebRTC mesh (`network-plugin-webrtc`) connects peers directly, but symmetric NAT, corporate firewalls, and restrictive ISPs prevent direct peer-to-peer connections between some peers. The existing `network-plugin-relay` handles cross-mesh routing (Mesh A → Mesh B), but there is no mechanism for intra-mesh relay: routing messages between two peers in the *same* mesh when they cannot connect directly. Without intra-mesh relay, a single symmetric NAT can partition the mesh from within.

This plugin provides **indirect peer-to-peer communication through intermediate peers** within the same mesh. It discovers relay candidates, selects optimal relay paths, maintains relay connections, and prevents relay loops.

## What changes

- **ADDED**: `IntraRelayPlugin` class implementing `NetworkPlugin`.
- **ADDED**: `RelayDiscovery` — discovers potential relay nodes from the mesh topology. Candidates are peers that have direct connections to both the source and target. Excludes leaf-tier peers (they cannot forward traffic).
- **ADDED**: `RelaySelector` — selects the optimal relay from candidates using strategies:
  - `LowestLatency` — minimize end-to-end RTT through relay
  - `HighestReliability` — maximize stability score (uptime, packet loss)
  - `FewestHops` — prefer direct relay over multi-hop
  - `TierOptimized` — prefer higher-tier peers (more capable hosts)
  - `LoadBalanced` — avoid overloading a single relay peer
- **ADDED**: `RelayConnectionManager` — tracks active relay paths per peer pair. Maintains `RelayConnection` state: `pending → active → degraded → closed`.
- **ADDED**: `RelayMessageEnvelope` — wraps original `MessageEnvelope` with relay metadata: `relayPath` (array of peer IDs), `hopCount`, `maxHops`, `visitedNodes` (for loop prevention).
- **ADDED**: `RelayPerformanceMonitor` — tracks relay path quality: RTT, packet loss, bandwidth, stability. Publishes `relay:degraded` / `relay:recovered` on `NetworkBus`.
- **ADDED**: `RelaySecurityManager` — authenticates relay nodes using peer identities from `network-plugin-crypto-messages`. Validates relay message integrity (signature + hop count). Enforces relay rate limits per peer to prevent DoS.
- **ADDED**: `LoopPrevention` — drops messages where `hopCount >= maxHops` (default 8) or where `visitedNodes` contains the current peer.
- **ADDED**: `NETWORK_INTRA_RELAY_CODES` — frozen error registry.

## Relay path example

```text
Peer A wants to send to Peer B, but direct ICE fails.

Peer A ──► Relay R (Tier 1 host, connected to both A and B)
             Relay R ──► Peer B

Envelope from A:
  original: { senderId: "A", targetId: "B", payload: ... }
  relay wrapper: {
    relayPath: ["A", "R", "B"],
    hopCount: 0,
    maxHops: 8,
    visitedNodes: ["A"]
  }

R forwards to B with hopCount: 1, visitedNodes: ["A", "R"]
```

## Out of scope

- Cross-mesh relay → handled by `network-plugin-relay`.
- TURN server integration → future `network-plugin-turn`.
- STUN server discovery → handled by `network-plugin-webrtc` ICE.

## Deferred to follow-up changes

To keep this initial change feature-complete on the surface it claims (per `openspec/AGENTS.md §2c`), the cryptographic relay-node authentication is split into a separate proposal so the core relay primitives ship without coupling to `network-plugin-crypto-messages`. None of the listed `## ADDED` registry elements are removed — the security manager and its conformance test (`security.spec-conformance.test.ts`) migrate to the follow-up:

- **RelaySecurityManager** → follow-up `network-plugin-intra-relay-security`. Authenticates relay nodes via the `PeerIdentityVerifier` from `network-plugin-crypto-messages`, validates relay-message signatures, and enforces per-peer relay rate limits to prevent DoS.

The core change shipped here covers: `RelayDiscovery`, `RelaySelector` (all 5 strategies), `RelayConnectionManager` (full FSM), `RelayMessageEnvelope` (with helper functions), `LoopPrevention` (max-hops + visited-nodes), `RelayPerformanceMonitor` (RTT-based degraded/recovered with hysteresis), and the `IntraRelayPlugin` facade.

## Source mapping

This derives from `docs/old-network-planning/RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §Relay Module and `PHASE_2_5.md` §RelayConnectionManager.

| Requirement | Source lines | Notes |
|---|---|---|
| Relay discovery from topology | `RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §RelayDiscovery | reworded; uses `NetworkBus` instead of direct topology import |
| Relay selection strategies | `RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §RelaySelector | reworded; 5 strategies |
| Relay message envelope | `RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §RelayMessage | reworded; wraps genesis `MessageEnvelope` |
| Loop prevention | `RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §Loop Prevention | verbatim: hop count + visited-node tracking |
| Relay security | `RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §Relay Security | reworded; uses `crypto-messages` for identity |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| `RelayConnectionManager` FSM | Required for graceful relay lifecycle management |
| `RelayPerformanceMonitor` | Required to detect degraded relay paths and trigger re-selection |
| Exclude leaf-tier from relay candidates | Leaf peers lack forwarding capacity; relaying through them would saturate their connection |

## Verification approach

- `src/discovery/discovery.spec-conformance.test.ts` — pins candidate discovery, leaf exclusion, topology awareness.
- `src/selector/selector.spec-conformance.test.ts` — pins 5 strategy behaviors, tie-breaking, load balancing.
- `src/connection/connection.spec-conformance.test.ts` — pins relay path establishment, teardown, degradation.
- `src/envelope/envelope.spec-conformance.test.ts` — pins relay wrapper format, hop count increment, visited tracking.
- `src/loop/loop.spec-conformance.test.ts` — pins max-hops drop, visited-node drop, no infinite loops.
- `src/security/security.spec-conformance.test.ts` — pins relay authentication, rate limiting, DoS prevention.
- `src/monitor/monitor.spec-conformance.test.ts` — pins RTT tracking, degradation detection, recovery.
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
- `tests/dep-graph.test.ts` — pins no direct import of webrtc or topology packages.

## Migration impact

None — additive only.