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:

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

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

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.

5.7 KiB Raw Blame History