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

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.

6.4 KiB Raw Blame History