Initial import of the CBDDC codebase with docs and tests. Add a .NET-focused gitignore to keep generated artifacts out of source control.

2026-02-20 13:03:21 -05:00
commit 08bfc17218
218 changed files with 33910 additions and 0 deletions
--- a/docs/security.md
+++ b/docs/security.md
@@ -0,0 +1,145 @@
+# Network Security
+
+**CBDDC v0.6.0** introduces optional **secure networking** to protect data in transit between peers using industry-standard cryptography.
+
+## Overview
+
+The security layer provides:
+- **ECDH (Elliptic Curve Diffie-Hellman)** key exchange for establishing shared secrets
+- **AES-256-CBC** encryption for all synchronized data
+- **HMAC-SHA256** authentication to prevent tampering
+- **Perfect Forward Secrecy** - each session uses unique ephemeral keys
+
+## When to Use Secure Networking
+
+### ✅ Recommended For:
+- **Sensitive data** (customer information, financial records, health data)
+- **Compliance requirements** (GDPR, HIPAA, PCI-DSS)
+- **Untrusted network segments** within your LAN
+- **Production deployments** where data confidentiality is important
+
+### ⚠️ Consider Performance Impact:
+- Encryption adds ~5-10ms latency per message
+- CPU overhead for encryption/decryption
+- Not necessary for public/non-sensitive data
+
+## How It Works
+
+### Handshake Process
+
+```
+Peer A                               Peer B
+  |                                     |
+  |  1. Generate ECDH keypair           |
+  |------ Public Key A ---------------->|  2. Generate ECDH keypair
+  |                                     |
+  |<----- Public Key B -----------------|
+  |                                     |
+  3. Compute shared secret           3. Compute shared secret
+  4. Derive encryption keys          4. Derive encryption keys
+  |                                 |
+  |==== Encrypted Communication ====|
+```
+
+### Encryption Details
+
+1. **Key Exchange**: NIST P-256 elliptic curve (secp256r1)
+2. **Encryption**: AES-256 in CBC mode with random IV per message
+3. **Authentication**: HMAC-SHA256 over ciphertext
+4. **Message Format**: `IV (16 bytes) + Ciphertext + HMAC (32 bytes)`
+
+## Usage
+
+### Enable Security
+
+```csharp
+using CBDDC.Network.Security;
+
+// Register secure handshake service
+services.AddSingleton<IPeerHandshakeService, SecureHandshakeService>();
+
+// Network will automatically use encryption if service is registered
+services.AddCBDDCNetwork(nodeId, tcpPort, authToken);
+```
+
+### Console Sample (--secure flag)
+
+```bash
+# Start with encryption enabled
+dotnet run --secure
+
+# Or without encryption (faster, less secure)
+dotnet run
+```
+
+### UI Clients
+
+If you build a UI client, enable secure mode by default to avoid mixed-security clusters.
+
+### Verify Security Status
+
+UI clients should display security status:
+- **🔒 Encrypted** - Secure communication active
+- **🔓 Plaintext** - No encryption (Console sample default)
+
+## Configuration
+
+### Optional: Custom Security Settings
+
+Currently, security uses default secure parameters. Future versions may support:
+- Custom curve selection
+- Cipher suite configuration  
+- Certificate pinning
+
+## Security Considerations
+
+### ✅ What This Protects Against:
+- **Eavesdropping**: Data is encrypted in transit
+- **Tampering**: HMAC prevents message modification
+- **Man-in-the-Middle**: ECDH provides authenticity
+
+### ⚠️ Out of Scope:
+- **Data at Rest**: SQLite databases are NOT encrypted. Use OS-level encryption if needed.
+- **Authentication**: No peer identity verification beyond shared auth token.
+- **Public Internet**: Still designed for trusted LANs. Use VPN/firewall for internet exposure.
+
+## Performance Impact
+
+Benchmarks on typical workloads:
+
+| Operation | Plaintext | Encrypted | Overhead |
+|-----------|-----------|-----------|----------|
+| Small sync (10 docs) | 15ms | 22ms | +47% |
+| Large sync (1000 docs) | 450ms | 520ms | +16% |
+| Handshake | N/A | 8ms | Initial |
+
+**Recommendation**: Enable for production. Disable for development/testing if needed.
+
+## Compatibility
+
+- **Secure ↔ Secure**: ✅ Works
+- **Plaintext ↔ Plaintext**: ✅ Works  
+- **Secure ↔ Plaintext**: ❌ Connection fails (by design)
+
+All nodes in a network must use the **same security mode**.
+
+## FAQ
+
+**Q: Can I use this over the public internet?**  
+A: While encryption helps, CBDDC is still designed for LANs. Use VPN, firewall rules, and consider TLS/SSL wrapping for internet exposure.
+
+**Q: How do I encrypt the SQLite database?**  
+A: Use SQLCipher or OS-level disk encryption (BitLocker, LUKS, FileVault).
+
+**Q: Can different nodes use different keys?**  
+A: No. All nodes in a mesh share the same `authToken`. Key rotation is not yet supported.
+
+**Q: What about .NET Standard 2.0 support?**  
+A: Security works on all target frameworks (netstandard2.0, net6.0, net8.0) with appropriate polyfills.
+
+---
+
+**See Also:**
+- [Getting Started](getting-started.html)
+- [Architecture](architecture.html)
+- [Production Hardening](production-hardening.html)