Initial Commit

openspec/specs/network-intra-relay/spec.md

@@ -0,0 +1,94 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec: network-intra-relay
+
+**Package**: `@suaveplan/network-plugin-intra-relay`
+**Status**: CANONICAL.
+
+> Every requirement below carries a `**Verified by:**` line.
+
+## Requirements
+
+### Requirement: RelaySecurityManager authorises inbound relay messages
+
+The package SHALL export a `RelaySecurityManager` class that runs three checks in order against every inbound relay message: trusted-peer allowlist, `ed25519` signature validation, and per-peer + global token-bucket rate limit. The class SHALL throw a `NetworkIntraRelayError` carrying one of `RELAY_PEER_UNTRUSTED`, `RELAY_SIGNATURE_INVALID`, or `RELAY_RATE_LIMIT_EXCEEDED` on failure. The class SHALL accept a `RelaySecurityManagerConfig` carrying `{ policy: RelayAuthPolicy; rateLimit: RelayRateLimit; peerKeyResolver: PeerKeyResolver; clock?: () => number; signatureVerifier?: SignatureVerifier }`.
+
+**Verified by:** `src/security/relay-security-manager.spec-conformance.test.ts`
+
+#### Scenario: admits a peer in the trusted-set allowlist
+
+- **WHEN** `policy.trustedPeers` is `Set(["peer-a"])` and `authorize` is called with `senderPeerId: "peer-a"` and a valid signature
+- **THEN** the call does NOT throw
+
+#### Scenario: rejects a peer not in a non-empty allowlist
+
+- **WHEN** `policy.trustedPeers` is `Set(["peer-a"])` and `authorize` is called with `senderPeerId: "peer-b"`
+- **THEN** the call throws `NetworkIntraRelayError(RELAY_PEER_UNTRUSTED)`
+
+#### Scenario: empty allowlist admits any peer
+
+- **WHEN** `policy.trustedPeers` is the empty set
+- **THEN** any peer id is admitted (subject to the signature and rate-limit checks)
+
+#### Scenario: rejects bad signature with RELAY_SIGNATURE_INVALID
+
+- **WHEN** a message arrives with a signature that fails ed25519 verification against the resolved public key
+- **THEN** `authorize` throws `NetworkIntraRelayError(RELAY_SIGNATURE_INVALID)`
+
+#### Scenario: missing signature when policy requires one
+
+- **WHEN** `policy.requireSignature` is `true` and the input lacks a `signature`
+- **THEN** `authorize` throws `NetworkIntraRelayError(RELAY_SIGNATURE_INVALID)`
+
+#### Scenario: missing signature when policy does not require one
+
+- **WHEN** `policy.requireSignature` is `false` and the input lacks a `signature`
+- **THEN** `authorize` does NOT throw on the signature check
+
+#### Scenario: per-peer rate-limit exhaustion
+
+- **WHEN** a single peer consumes more than `rateLimit.burstSize` tokens before the clock advances enough to refill the bucket
+- **THEN** the next `authorize` call from that peer throws `NetworkIntraRelayError(RELAY_RATE_LIMIT_EXCEEDED)` with `context.scope === "per-peer"`
+
+#### Scenario: global rate-limit exhaustion separate from per-peer
+
+- **WHEN** multiple peers collectively exhaust the global bucket while each peer's individual bucket still has tokens
+- **THEN** further `authorize` calls throw `NetworkIntraRelayError(RELAY_RATE_LIMIT_EXCEEDED)` with `context.scope === "global"`
+
+#### Scenario: isRateLimited inspection without consuming
+
+- **WHEN** `isRateLimited(peerId)` is called
+- **THEN** the result reflects whether `authorize` would currently fail on the rate-limit check, without consuming a token
+
+### Requirement: error-code registry extended with three security codes
+
+The `NETWORK_INTRA_RELAY_CODES` registry SHALL include `RELAY_SIGNATURE_INVALID`, `RELAY_PEER_UNTRUSTED`, and `RELAY_RATE_LIMIT_EXCEEDED` as frozen members.
+
+**Verified by:** `src/error-codes.spec-conformance.test.ts`
+
+#### Scenario: registry exposes the three codes
+
+- **WHEN** `NETWORK_INTRA_RELAY_CODES` is inspected
+- **THEN** it contains `RELAY_SIGNATURE_INVALID`, `RELAY_PEER_UNTRUSTED`, `RELAY_RATE_LIMIT_EXCEEDED` mapped to `"NET_INTRA_RELAY.<KEY>"` values
+
+### Requirement: IntraRelayPlugin exposes a security getter
+
+`IntraRelayPlugin` SHALL accept an optional `security?: RelaySecurityManagerConfig` field in its constructor config and SHALL expose a `security` getter returning `RelaySecurityManager | null`. Omitting the field SHALL leave security disabled (`security` returns `null`); supplying it SHALL construct a `RelaySecurityManager` wired to the supplied policy / rate-limit / resolver.
+
+**Verified by:** `src/plugin/intra-relay-plugin.spec-conformance.test.ts`
+
+#### Scenario: security getter returns null when no config supplied
+
+- **WHEN** `IntraRelayPlugin` is constructed without `security`
+- **THEN** the `security` getter returns `null`
+
+#### Scenario: security getter returns a manager when configured
+
+- **WHEN** `IntraRelayPlugin` is constructed with a valid `security` config
+- **THEN** the `security` getter returns a `RelaySecurityManager` whose `isRateLimited` and `authorize` methods are wired correctly
+
+### Requirement: types are exported for consumers
+
+The package SHALL export `RelayAuthPolicy`, `RelayRateLimit`, and `RelaySecurityCheckInput` types from the root barrel and from a subpath export at `./security/security`.
+
+**Verified by:** `tests/dep-graph.test.ts`, package `exports` map.