Initial Commit

openspec/archive/2026-05-05-network-plugin-audit-mesh/proposal.md

@@ -0,0 +1,112 @@
+# 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.

openspec/archive/2026-05-05-network-plugin-audit-mesh/tasks.md

@@ -0,0 +1,82 @@
+# Tasks — network-plugin-audit-mesh
+
+> Blocked on: `network-core`, `network-plugin-crypto-messages`.
+
+## 1. Scaffold
+
+- [x] 1.1 `packages/network/network-plugin-audit-mesh/` with `package.json`, `tsconfig.json`, `vitest.config.ts`, `README.md`.
+- [x] 1.2 Workspace deps: `@suaveplan/network`, `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/crypto-hash`, `@suaveplan/timing`, `@opentelemetry/api`, `zod`.
+- [x] 1.3 `sideEffects: false`.
+
+## 2. Types
+
+- [x] 2.1 `src/types/log.types.ts` — `LogEntry`, `LogEventType`, `LogCheckpoint`.
+- [x] 2.2 `src/types/replication.types.ts` — `ReplicationTarget`, `ReplicationMode`.
+- [x] 2.3 `src/types/conflict.types.ts` — `ConflictResolution`, `DivergentChain`.
+- [x] 2.4 `src/error-codes.ts` — `defineCodes("NET_AUDIT", [...])`.
+
+## 3. Signed log
+
+- [x] 3.1 `src/log/signed-log.ts` — `SignedLog`.
+- [x] 3.2 Append-only with monotonic `seq`.
+- [x] 3.3 Each entry: `seq, timestamp, eventType, payload, prevHash, hostId, hostSignature`.
+
+## 4. Log replicator
+
+- [x] 4.1 `src/replicator/log-replicator.ts` — `LogReplicator`.
+- [x] 4.2 Replicates to `R` sibling hosts (default 2).
+- [x] 4.3 Tier-aware target selection.
+- [x] 4.4 Synchronous for CRITICAL, async for NORMAL.
+
+## 5. Log retriever
+
+- [x] 5.1 `src/retriever/log-retriever.ts` — `LogRetriever`.
+- [x] 5.2 Range queries: `getLogs(meshId, fromSeq, toSeq)`.
+- [x] 5.3 Pagination for large ranges.
+
+## 6. Integrity checker
+
+- [x] 6.1 `src/integrity/integrity-checker.ts` — `IntegrityChecker`.
+- [x] 6.2 Verifies hash chain on retrieval.
+- [x] 6.3 Detects gaps, forks, tampered entries.
+- [x] 6.4 Emits `audit:corruption-detected`.
+
+## 7. Conflict resolver
+
+- [x] 7.1 `src/conflict/conflict-resolver.ts` — `ConflictResolver`.
+- [x] 7.2 Longest chain wins.
+- [x] 7.3 Equal length: lexicographically smallest last-hash wins.
+
+## 8. Log compaction
+
+- [x] 8.1 `src/compaction/log-compaction.ts` — `LogCompaction`.
+- [x] 8.2 Periodic checkpoint creation.
+- [x] 8.3 Checkpoint = signed state snapshot at sequence number.
+
+## 9. Plugin wrapper
+
+- [x] 9.1 `src/plugin/audit-mesh-plugin.ts` — `AuditMeshPlugin` implements `NetworkPlugin`.
+
+## 10. Spec
+
+- [x] 10.1 Update `openspec/specs/network/spec.md` with `NET-AUDIT` requirements.
+
+## 11. Conformance tests
+
+- [x] 11.1 `src/log/signed-log.spec-conformance.test.ts` — append, chain, signature.
+- [x] 11.2 `src/replicator/log-replicator.spec-conformance.test.ts` — R-copy, target selection.
+- [x] 11.3 `src/integrity/integrity-checker.spec-conformance.test.ts` — gap, fork, tamper.
+- [x] 11.4 `src/conflict/conflict-resolver.spec-conformance.test.ts` — longest, tiebreak.
+- [x] 11.5 `src/compaction/log-compaction.spec-conformance.test.ts` — checkpoint, snapshot.
+- [x] 11.6 `src/retriever/log-retriever.spec-conformance.test.ts` — range, pagination.
+- [x] 11.7 `src/error-codes.spec-conformance.test.ts` — frozen registry.
+
+## 12. Verify
+
+- [x] 12.1 `bunx turbo lint typecheck test --filter=@suaveplan/network-plugin-audit-mesh` green.
+- [x] 12.2 `bunx turbo test:coverage --filter=@suaveplan/network-plugin-audit-mesh` 100/100/100/100.
+- [x] 12.3 `bun scripts/openspec-conformance.ts @suaveplan/network-plugin-audit-mesh` PASS.
+
+## Audit (2026-05-05)
+
+Shipped at 100/100/100/100 statement/branch/function/line coverage across 9 spec-conformance test files (85 tests). Documentation coverage: 11/11 files (100%). OpenSpec conformance: PASS. All eight `NETWORK_AUDIT_CODES` are wired — five are thrown (`REPLICATION_FAILED`, `CHECKPOINT_INVALID`, `CONFLICT_UNRESOLVED`, `INVALID_SEQ`, `RANGE_INVALID`) and three are report-only (`LOG_GAP`, `CHAIN_TAMPERED`, `SIGNATURE_INVALID`) carried on `CorruptionReport.code` via the `CORRUPTION_KIND_TO_CODE` map exported from `integrity-checker.ts`. Subsystems wired: `SignedLog`, `LogReplicator`, `LogRetriever`, `IntegrityChecker`, `ConflictResolver`, `LogCompaction`, plus the `AuditMeshPlugin` facade.