Initial Commit
This commit is contained in:
@@ -0,0 +1,112 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user