# OpenSpec Change: network-plugin-crypto-messages

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

## Why

In a decentralized mesh where the central server may be offline, peers must cryptographically verify each other's authority. A malicious peer cannot be allowed to create arbitrary sessions, spoof host identities, or forge activity logs. This plugin provides cryptographic integrity for the entire network layer: every host-signed message, server-signed session tokens, peer identity verification, and append-only signed log chains. It consumes `@suaveplan/crypto-cipher`, `@suaveplan/crypto-hash`, and `@suaveplan/crypto-keys`.

## What changes

- **ADDED**: `CryptoMessagesPlugin` class implementing `NetworkPlugin`.
- **ADDED**: `MessageSigner` — signs every outbound message with the sender's private key using Ed25519. Verifies signatures on inbound messages using peer public keys from the registry.
- **ADDED**: `SessionTokenAuthority` — validates server-signed session tokens. Every session creation requires a token signed by the central server's private key. Tokens include: `sessionId`, `parentSessionId`, `capacity`, `rulesHash`, `expiresAt`, `serverSignature`. Peers reject `session:create` without a valid token.
- **ADDED**: `MeshTokenAuthority` — validates server-signed mesh tokens. Every mesh creation requires a server-signed token with: `meshId`, `maxCapacity`, `allowedTiers`, `expiresAt`, `serverSignature`.
- **ADDED**: `PeerIdentityVerifier` — verifies peer identity via challenge-response during handshake. Prevents peer ID spoofing.
- **ADDED**: `LogChainSigner` — signs activity log entries in a hash chain: `entry[n] = sign(hash(entry[n-1]) + payload)`. Provides tamper-evident audit trails.
- **ADDED**: `KeyRotationManager` — rotates signing keys periodically and broadcasts new public keys to the mesh. Old signatures remain valid for a grace period.
- **ADDED**: `NETWORK_CRYPTO_CODES` — frozen error registry.

## Token format

```typescript
interface SessionToken {
  readonly sessionId: string;
  readonly parentSessionId: string | null;
  readonly capacity: number;
  readonly rulesHash: string;       // hash of session rules
  readonly issuedAt: number;
  readonly expiresAt: number;
  readonly serverSignature: Uint8Array;  // Ed25519 signature
}

interface MeshToken {
  readonly meshId: string;
  readonly maxCapacity: number;
  readonly allowedTiers: number;
  readonly issuedAt: number;
  readonly expiresAt: number;
  readonly serverSignature: Uint8Array;
}
```

## Offline operation model

- Tokens have an `expiresAt` timestamp. While tokens are valid, the mesh operates autonomously.
- When tokens expire, new sessions/meshes cannot be created. Existing sessions continue.
- Token refresh requires server connectivity (via `network-plugin-server-bridge`).
- During extended outages, hosts can request emergency token extension via a quorum of peer signatures (Byzantine-tolerant voting).

## Out of scope

- Full Byzantine fault tolerance for voting → future hardening.
- Quantum-resistant signatures → future `network-plugin-crypto-pq`.
- Hardware security module (HSM) integration → future scope.

## Source mapping

This is a **new design** — suaveplan has no equivalent cryptographic integrity layer for the network mesh.

### Requirements with no source line

| Requirement | Justification |
|---|---|
| Server-signed session tokens | Prevents rogue peers from creating arbitrary sessions when server is offline |
| Server-signed mesh tokens | Prevents mesh sprawl and unauthorized topology changes |
| Ed25519 message signatures | Every host message is attributable and tamper-evident |
| Challenge-response peer identity | Prevents peer ID spoofing in the registry |
| Hash-chained signed logs | Append-only, tamper-evident audit trail for server reconciliation |
| Key rotation | Limits blast radius if a private key is compromised |
| Token expiry with quorum extension | Balances security (server authority) with resilience (offline operation) |

## Verification approach

- `src/signer/signer.spec-conformance.test.ts` — pins sign/verify roundtrip, invalid signature rejection.
- `src/session-token/session-token.spec-conformance.test.ts` — pins valid token acceptance, expired rejection, forged rejection.
- `src/mesh-token/mesh-token.spec-conformance.test.ts` — pins mesh token validation.
- `src/identity/identity.spec-conformance.test.ts` — pins challenge-response, spoof detection.
- `src/log-chain/log-chain.spec-conformance.test.ts` — pins hash chain integrity, tamper detection.
- `src/key-rotation/key-rotation.spec-conformance.test.ts` — pins rotation, grace period, broadcast.
- `src/error-codes.spec-conformance.test.ts` — frozen registry.

## Enhancement: Plugin Security Verifier

**Source**: `docs/old-network-planning/RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §PluginSecurityVerifier, `MODULAR_IMPLEMENTATION_PHASE_6.md` §Security Verifier

Because the architecture is plugin-based, a compromised plugin could hijack the mesh. The crypto-messages plugin extends with plugin integrity verification:

- `PluginSecurityVerifier` — validates plugin integrity before registration. Checks code signatures, declared capabilities vs requested capabilities.
- `PluginCapabilityValidator` — enforces that plugins cannot exceed their declared capability set.
- `PluginActivityMonitor` — monitors plugin message patterns for anomalous behavior (e.g., excessive broadcast, unauthorized peer kicks).
- `SandboxedPluginContext` — restricts plugin access to sensitive node operations via capability-based access control.

## Enhancement: Tier-Specific Security Policies

**Source**: `docs/old-network-planning/RELAY_SECURITY_IMPLEMENTATION_PLAN.md` §Tier-Specific Security

Security policies vary by tier:

- `TierSecurityPolicy` — configurable rules per tier:
  - Tier 0 (Host): full authority — can sign messages, issue tokens, override votes.
  - Tier 1 (SubHost): relay authority + voting, no token issuance, no override.
  - Tier 2 (Leaf): read-only for sensitive ops, can send game state, cannot sign logs.
- `CrossTierCredentialDelegation` — cross-tier operations require explicit credential delegation from higher tier.
- `GeographicSecurityPolicy` — optional regional restrictions on sensitive operations.

## Migration impact

None — additive only.