113 lines
5.7 KiB
Markdown
113 lines
5.7 KiB
Markdown
# OpenSpec Change: network-plugin-audit-mesh
|
|
|
|
- **Change ID**: network-plugin-audit-mesh
|
|
- **Package**: `@suaveplan/network-plugin-audit-mesh` (new)
|
|
- **Status**: PROPOSED
|
|
- **Type**: new-package
|
|
- **Date**: 2026-04-29
|
|
|
|
## Why
|
|
|
|
When the central server is offline, the mesh operates autonomously — but activity must still be auditable. Hosts generate signed logs of session events, peer joins/leaves, host elections, and state changes. These logs must be replicated across multiple hosts for durability (so a single host failure doesn't erase history) and must be retrievable by the server when it comes back online. This plugin provides tamper-evident, cryptographically signed, append-only log chains with cross-host replication.
|
|
|
|
## What changes
|
|
|
|
- **ADDED**: `AuditMeshPlugin` class implementing `NetworkPlugin`.
|
|
- **ADDED**: `SignedLog` — append-only log structure:
|
|
|
|
```typescript
|
|
interface LogEntry {
|
|
readonly seq: number; // monotonic sequence
|
|
readonly timestamp: number; // injectable Clock
|
|
readonly meshId: string;
|
|
readonly sessionId: string | null;
|
|
readonly eventType: LogEventType; // 'peer-joined' | 'peer-left' | 'host-elected' | 'session-created' | ...
|
|
readonly payload: unknown; // event-specific data
|
|
readonly prevHash: string; // BLAKE3 hash of previous entry
|
|
readonly hostId: string; // host that produced this entry
|
|
readonly hostSignature: Uint8Array; // Ed25519 signature of hash(entry)
|
|
}
|
|
```
|
|
|
|
- **ADDED**: `LogReplicator` — replicates logs to `R` sibling hosts (configurable, default 2). Uses mesh topology to select replication targets: Tier 0 replicates to other Tier 0s; Tier 1 replicates to its Tier 0 parent and a sibling Tier 1. Provides cross-tier durability.
|
|
- **ADDED**: `LogRetriever` — responds to log queries from other hosts or from the server bridge. Supports range queries: `getLogs(meshId, fromSeq, toSeq)`.
|
|
- **ADDED**: `IntegrityChecker` — verifies the hash chain on retrieval. Detects gaps, forks, or tampered entries. Reports `audit:corruption-detected` on the bus.
|
|
- **ADDED**: `ConflictResolver` — when the server retrieves logs from multiple hosts and finds divergent chains, resolves using: (1) longest chain wins, (2) if equal length, lexicographically smallest last-hash wins (deterministic tiebreak).
|
|
- **ADDED**: `LogCompaction` — periodically compacts old logs into checkpoints. A checkpoint is a signed snapshot of mesh/session state at a given sequence number. Reduces replay volume when server reconnects.
|
|
- **ADDED**: `NETWORK_AUDIT_CODES` — frozen error registry.
|
|
|
|
## Replication topology
|
|
|
|
```text
|
|
Tier 0 Host A (primary log for Mesh 1)
|
|
│
|
|
├── replicates to ──► Tier 0 Host B (Mesh 2)
|
|
│
|
|
└── replicates to ──► Tier 1 SubHost C (Mesh 1, local redundancy)
|
|
|
|
Tier 1 SubHost C
|
|
│
|
|
├── replicates to ──► Tier 0 Host A (parent)
|
|
└── replicates to ──► Tier 1 SubHost D (sibling)
|
|
```
|
|
|
|
**Replication rules**:
|
|
|
|
- Every log entry is stored on at least `R+1` hosts (original + R replicas).
|
|
- Replicas are updated synchronously for CRITICAL events (host election, session creation).
|
|
- Replicas are updated asynchronously for NORMAL events (peer join/leave, state update).
|
|
|
|
## Server reconciliation flow
|
|
|
|
```text
|
|
Server comes online
|
|
│
|
|
├── queries all Tier 0 hosts for log checkpoints
|
|
├── finds latest common checkpoint across hosts
|
|
├── requests differential logs from that checkpoint forward
|
|
├── validates all signatures and hash chains
|
|
├── detects conflicts → runs ConflictResolver
|
|
├── applies reconciled state to server database
|
|
└── broadcasts `server:reconciled` to all mesh hosts
|
|
```
|
|
|
|
## Out of scope
|
|
|
|
- Server-side log storage and analysis → API gateway / audit-logging packages.
|
|
- Real-time streaming analytics → future `network-plugin-analytics`.
|
|
- Legal/compliance retention policies → future `network-plugin-compliance`.
|
|
|
|
## Source mapping
|
|
|
|
This derives from `../suaveplan/enterprise/audit-logging.md` and `../suaveplan/packages/universal/audit-logging/`.
|
|
|
|
| Requirement | Source lines | Notes |
|
|
|---|---|---|
|
|
| Structured audit logs | `audit-logging/README.md` §Logs | reworded; mesh-specific format |
|
|
| Log integrity | `audit-logging/README.md` §Integrity | reworded; hash chain + signatures |
|
|
|
|
### Requirements with no source line
|
|
|
|
| Requirement | Justification |
|
|
|---|---|
|
|
| Cross-host log replication | Durability — single host failure must not erase audit history |
|
|
| Hash-chained append-only logs | Tamper evidence — any modification breaks the chain |
|
|
| Host signatures on every entry | Accountability — every event is attributable to a specific host |
|
|
| Conflict resolution for divergent chains | Required when hosts disagree on history during partition |
|
|
| Log compaction into checkpoints | Required for efficient server reconciliation after long outages |
|
|
| Synchronous replication for critical events | Host elections must be durable before acknowledged |
|
|
|
|
## Verification approach
|
|
|
|
- `src/log/signed-log.spec-conformance.test.ts` — pins append, hash chain, signature.
|
|
- `src/replicator/log-replicator.spec-conformance.test.ts` — pins R-copy replication, target selection.
|
|
- `src/integrity/integrity-checker.spec-conformance.test.ts` — pins gap detection, fork detection, tamper detection.
|
|
- `src/conflict/conflict-resolver.spec-conformance.test.ts` — pins longest-chain, tiebreak, merge.
|
|
- `src/compaction/log-compaction.spec-conformance.test.ts` — pins checkpoint creation, state snapshot.
|
|
- `src/retriever/log-retriever.spec-conformance.test.ts` — pins range queries, pagination.
|
|
- `src/error-codes.spec-conformance.test.ts` — frozen registry.
|
|
|
|
## Migration impact
|
|
|
|
None — additive only.
|