From b4a08c2bc18ce600564bec8885d3514cd3c7746c Mon Sep 17 00:00:00 2001 From: Savely Krendelhoff Date: Fri, 22 Aug 2025 13:41:29 +0700 Subject: [PATCH] Organize documentation structure --- CLAUDE.md | 58 ++++++++ docs/IMPLEMENTATION.md | 159 +++++++++++++++++++++ docs/POW_ANALYSIS.md | 235 ++++++++++++++++++++++++++++++++ PROTOCOL.md => docs/PROTOCOL.md | 18 +-- 4 files changed, 461 insertions(+), 9 deletions(-) create mode 100644 CLAUDE.md create mode 100644 docs/IMPLEMENTATION.md create mode 100644 docs/POW_ANALYSIS.md rename PROTOCOL.md => docs/PROTOCOL.md (95%) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3eb3159 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,58 @@ +# Word of Wisdom TCP Server + +## Implementation Details + +### Technology Stack +- **Language**: Go (Golang) +- **Protocol**: Custom TCP protocol as defined in PROTOCOL.md +- **Implementation Plan**: Follow the detailed plan and checkboxes in IMPLEMENTATION.md + +### Development Guidelines + +#### Commit Strategy +- Create a commit after every finished change +- Commit messages must answer: "What should I do to make this change?" +- Example: "Add proof of work challenge generation", "Implement quote storage service" + +#### Code Quality Standards +- No AI-generated code indicators (avoid verbose comments or watermarks) +- Production-grade implementation required + +#### Production Requirements + +##### Observability +- Structured logging throughout the application +- Metrics collection for monitoring +- Proper error handling and reporting + +##### Documentation +- Comprehensive documentation for all server components +- Clear API documentation +- Usage examples and deployment guides + +##### Testability & Architecture +- Dependency Injection (DI) pattern for all major components +- Easily testable architecture +- Mock implementations for external dependencies + +##### Testing Strategy +- Unit tests for all major functionality +- Integration tests for end-to-end workflows +- Test coverage for critical paths + +##### Deployment +- Dockerfiles for both server and client +- Docker Compose file for orchestration +- Production-ready configuration + +##### Data Storage +- Use fake/in-memory implementations for quick development +- Architecture must support easy swapping to real databases +- DI pattern enables seamless production deployment upgrades + +## Quick Start +1. Follow protocol specification in docs/PROTOCOL.md +2. Complete implementation tasks in docs/IMPLEMENTATION.md +3. Run tests: `go test ./...` +4. Build containers: `docker-compose build` +5. Start services: `docker-compose up` \ No newline at end of file diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md new file mode 100644 index 0000000..90f37fe --- /dev/null +++ b/docs/IMPLEMENTATION.md @@ -0,0 +1,159 @@ +# Word of Wisdom Server - Implementation Plan + +## Phase 1: Project Setup & Core Architecture +- [ ] Initialize Go module and project structure +- [ ] Set up dependency injection framework (wire/dig) +- [ ] Create core interfaces and contracts +- [ ] Set up structured logging (zerolog/logrus) +- [ ] Set up metrics collection (prometheus) +- [ ] Create configuration management +- [ ] Set up testing framework and test utilities + +## Phase 2: Proof of Work Implementation +- [ ] Implement PoW challenge generation service +- [ ] Implement SHA-256 based PoW algorithm +- [ ] Create challenge storage interface (in-memory fake) +- [ ] Implement solution verification logic +- [ ] Add difficulty adjustment mechanism +- [ ] Create PoW service with full DI support +- [ ] Write comprehensive unit tests for PoW components + +## Phase 3: Quote Management System +- [ ] Define quote storage interface +- [ ] Implement in-memory quote repository (fake) +- [ ] Create quote selection service (random) +- [ ] Load initial quote collection from file/config +- [ ] Add quote validation and sanitization +- [ ] Write unit tests for quote management + +## Phase 4: TCP Protocol Implementation +- [ ] Implement binary message protocol codec +- [ ] Create protocol message types and structures +- [ ] Implement connection handler with proper error handling +- [ ] Add message serialization/deserialization (JSON) +- [ ] Create protocol state machine +- [ ] Implement connection lifecycle management +- [ ] Write unit tests for protocol components + +## Phase 5: Server Core & Request Handling +- [ ] Implement TCP server with connection pooling +- [ ] Create request router and handler dispatcher +- [ ] Add connection timeout and lifecycle management +- [ ] Implement graceful shutdown mechanism +- [ ] Add request/response logging middleware +- [ ] Create health check endpoints +- [ ] Write integration tests for server core + +## Phase 6: DDOS Protection & Rate Limiting +- [ ] Implement IP-based connection limiting +- [ ] Create rate limiting service with time windows +- [ ] Add automatic difficulty adjustment based on load +- [ ] Implement temporary IP blacklisting +- [ ] Create circuit breaker for overload protection +- [ ] Add monitoring for attack detection +- [ ] Write tests for protection mechanisms + +## Phase 7: Observability & Monitoring +- [ ] Add structured logging throughout application +- [ ] Implement metrics for key performance indicators: + - [ ] Active connections count + - [ ] Challenge generation rate + - [ ] Solution verification rate + - [ ] Success/failure ratios + - [ ] Response time histograms +- [ ] Create logging middleware for request tracing +- [ ] Add error categorization and reporting +- [ ] Implement health check endpoints + +## Phase 8: Configuration & Environment Setup +- [ ] Create configuration structure with validation +- [ ] Support environment variables and config files +- [ ] Add configuration for different environments (dev/prod) +- [ ] Implement feature flags for protection levels +- [ ] Create deployment configuration templates +- [ ] Add configuration validation and defaults + +## Phase 9: Client Implementation +- [ ] Create client application structure +- [ ] Implement PoW solver algorithm +- [ ] Create client-side protocol implementation +- [ ] Add retry logic and error handling +- [ ] Implement connection management +- [ ] Create CLI interface for client +- [ ] Add client metrics and logging +- [ ] Write client unit and integration tests + +## Phase 10: Docker & Deployment +- [ ] Create multi-stage Dockerfile for server +- [ ] Create Dockerfile for client +- [ ] Create docker-compose.yml for local development +- [ ] Add docker-compose for production deployment +- [ ] Create health check scripts for containers +- [ ] Add environment-specific configurations +- [ ] Create deployment documentation + +## Phase 11: Testing & Quality Assurance +- [ ] Write comprehensive unit tests (>80% coverage): + - [ ] PoW algorithm tests + - [ ] Protocol handler tests + - [ ] Rate limiting tests + - [ ] Quote service tests + - [ ] Configuration tests +- [ ] Create integration tests: + - [ ] End-to-end client-server communication + - [ ] Load testing scenarios + - [ ] Failure recovery tests + - [ ] DDOS protection validation +- [ ] Add benchmark tests for performance validation +- [ ] Create stress testing scenarios + +## Phase 12: Documentation & Final Polish +- [ ] Write comprehensive README with setup instructions +- [ ] Create API documentation for all interfaces +- [ ] Add inline code documentation +- [ ] Create deployment guide +- [ ] Write troubleshooting guide +- [ ] Add performance tuning recommendations +- [ ] Create monitoring and alerting guide + +## Phase 13: Production Readiness Checklist +- [ ] Security audit of all components +- [ ] Performance benchmarking and optimization +- [ ] Memory leak detection and prevention +- [ ] Resource cleanup validation +- [ ] Error handling coverage review +- [ ] Logging security (no sensitive data exposure) +- [ ] Configuration security (secrets management) +- [ ] Container security hardening + +## Directory Structure +``` +/ +├── cmd/ +│ ├── server/ # Server application entry point +│ └── client/ # Client application entry point +├── internal/ +│ ├── server/ # Server core logic +│ ├── protocol/ # Protocol implementation +│ ├── pow/ # Proof of Work implementation +│ ├── quotes/ # Quote management +│ ├── ratelimit/ # Rate limiting & DDOS protection +│ ├── config/ # Configuration management +│ ├── metrics/ # Metrics collection +│ └── logger/ # Structured logging +├── pkg/ # Public packages +├── test/ # Integration tests +├── docker/ # Docker configurations +├── deployments/ # Deployment configurations +└── docs/ # Additional documentation +``` + +## Success Criteria +- [ ] Server handles 1000+ concurrent connections +- [ ] PoW protection prevents DDOS attacks effectively +- [ ] All tests pass with >80% code coverage +- [ ] Docker containers build and run successfully +- [ ] Client successfully solves challenges and receives quotes +- [ ] Comprehensive logging and metrics in place +- [ ] Production-ready error handling and recovery +- [ ] Clear documentation for deployment and operation \ No newline at end of file diff --git a/docs/POW_ANALYSIS.md b/docs/POW_ANALYSIS.md new file mode 100644 index 0000000..a315d4d --- /dev/null +++ b/docs/POW_ANALYSIS.md @@ -0,0 +1,235 @@ +# Proof of Work Algorithm Analysis + +## Overview + +This document analyzes various Proof of Work (PoW) algorithms considered for the Word of Wisdom protocol and provides detailed justification for the chosen approach. + +## PoW Algorithm Alternatives + +### 1. SHA-256 Hashcash (CHOSEN) + +**Description**: Bitcoin-style hashcash requiring hash output with specific number of leading zero bits. + +**Pros**: +- Widely tested and battle-proven in Bitcoin +- Simple to implement and verify +- CPU-bound computation (fair across hardware) +- Adjustable difficulty through leading zero bits +- Fast verification (single SHA-256 hash) +- No memory requirements +- Deterministic verification time + +**Cons**: +- Vulnerable to ASIC mining (specialized hardware advantage) +- Power consumption scales with difficulty +- Brute force approach (no early termination) + +**Our Mitigation**: +- DDOS protection doesn't require ASIC resistance (temporary challenges) +- Difficulty kept low (3-6 bits) to minimize power consumption +- Server-controlled difficulty prevents client-side optimization attacks + +### 2. Scrypt + +**Description**: Memory-hard function designed to resist ASIC mining. + +**Pros**: +- ASIC-resistant design +- Memory-hard computation +- Battle-tested in Litecoin +- Configurable memory and time parameters + +**Cons**: +- Complex implementation +- Memory requirements may disadvantage mobile clients +- Slower verification than simple hashing +- Parameter tuning complexity +- Potential denial-of-service on client memory + +**Why Not Chosen**: +- Unnecessary complexity for DDOS protection use case +- Memory requirements create client hardware discrimination +- Verification overhead impacts server performance under attack + +### 3. Equihash + +**Description**: Memory-hard algorithm based on birthday paradox, used in Zcash. + +**Pros**: +- ASIC-resistant through memory requirements +- Mathematically elegant approach +- Proven in production cryptocurrency +- Configurable memory parameters + +**Cons**: +- Very complex implementation +- High memory requirements (150+ MB typically) +- Slow verification process +- Not suitable for lightweight clients +- Complex parameter selection + +**Why Not Chosen**: +- Excessive complexity and resource requirements +- Poor fit for anti-DDOS use case requiring quick challenges +- Would exclude mobile and embedded clients + +### 4. Argon2 + +**Description**: Modern password hashing function winner, memory-hard with multiple variants. + +**Pros**: +- Designed for modern security requirements +- Multiple variants (Argon2i, Argon2d, Argon2id) +- Configurable time/memory trade-offs +- Resistant to side-channel attacks +- ASIC-resistant design + +**Cons**: +- Primarily designed for password hashing, not PoW +- Memory requirements create client inequality +- Complex implementation with many parameters +- Slower than simple hashing functions +- Not optimized for network protocols + +**Why Not Chosen**: +- Over-engineered for DDOS protection scenario +- Memory requirements discriminate against resource-constrained clients +- Verification overhead impacts server scalability + +### 5. CryptoNight + +**Description**: Memory-hard algorithm designed for CPU mining, used in Monero. + +**Pros**: +- CPU-optimized design +- ASIC-resistant through memory requirements +- Ring buffer memory pattern +- Proven in cryptocurrency applications + +**Cons**: +- 2MB memory requirement per instance +- Complex implementation +- Slower verification than simple hashing +- Memory requirements exclude lightweight clients +- Frequent algorithm updates needed for ASIC resistance + +**Why Not Chosen**: +- Memory requirements too high for general clients +- Complexity outweighs benefits for anti-DDOS use case +- Algorithm instability due to frequent updates + +### 6. Cuckoo Cycle + +**Description**: Graph-theoretic PoW based on finding cycles in random graphs. + +**Pros**: +- Memory-hard through graph traversal +- Mathematically interesting approach +- ASIC-resistant design +- Adjustable memory requirements + +**Cons**: +- Very complex implementation +- High memory requirements +- Slow verification process +- Limited production experience +- Complex parameter tuning + +**Why Not Chosen**: +- Excessive complexity for simple DDOS protection +- Memory requirements create client barriers +- Unproven in high-throughput server scenarios + +### 7. X11/X16R (Multi-Hash) + +**Description**: Combines multiple hash functions in sequence or rotation. + +**Pros**: +- ASIC-resistant through algorithm diversity +- Harder to optimize with specialized hardware +- Proven in some cryptocurrencies + +**Cons**: +- Complex implementation requiring multiple hash functions +- Slower than single-hash approaches +- More attack surface (multiple algorithms) +- Difficult to verify implementation correctness +- Higher CPU usage for verification + +**Why Not Chosen**: +- Unnecessary complexity for anti-DDOS use case +- Multiple algorithms increase implementation risk +- Verification overhead impacts server performance + +## Decision Matrix + +| Algorithm | Complexity | Speed | Memory | ASIC Resistance | Implementation Risk | Server Impact | +|-----------|------------|-------|--------|-----------------|-------------------|---------------| +| **SHA-256 Hashcash** | Low | High | None | Low | Low | Low | +| Scrypt | Medium | Medium | High | High | Medium | Medium | +| Equihash | High | Low | Very High | High | High | High | +| Argon2 | High | Low | High | High | Medium | Medium | +| CryptoNight | High | Low | High | High | High | High | +| Cuckoo Cycle | Very High | Low | High | High | Very High | High | +| X11/X16R | High | Medium | Low | Medium | High | Medium | + +## Final Decision: SHA-256 Hashcash + +### Primary Justifications + +1. **Simplicity**: Single, well-understood hash function with minimal implementation complexity +2. **Performance**: Fast computation and near-instant verification enable high server throughput +3. **Universality**: No memory requirements ensure compatibility across all client types +4. **Proven Reliability**: Battle-tested in Bitcoin with 15+ years of production experience +5. **Adjustable Difficulty**: Fine-grained control through leading zero bits (3-10 bits practical range) + +### ASIC Resistance Not Required + +For DDOS protection, ASIC resistance is unnecessary because: + +- **Temporary Challenges**: Each challenge is unique and expires within minutes +- **Cost vs. Benefit**: ASIC development cost far exceeds potential attack value +- **Dynamic Difficulty**: Server can adjust difficulty faster than ASIC deployment +- **Legitimate Use**: No financial incentive for specialized hardware development + +### Enhanced Security Through HMAC Integration + +Our implementation addresses SHA-256 hashcash limitations: + +- **Stateless Operation**: HMAC signatures eliminate server storage requirements +- **Replay Protection**: Timestamp + HMAC prevents challenge reuse +- **Forgery Prevention**: Server secret prevents challenge generation attacks +- **Scalability**: No server state enables horizontal scaling without coordination + +### Addressing SHA-256 Cons + +1. **ASIC Advantage**: Mitigated by low difficulty and temporary challenges +2. **Power Consumption**: Limited by max 6-bit difficulty (average 64 attempts) +3. **Brute Force**: Acceptable for anti-DDOS where work proof is the goal + +### Alternative Deployment Scenarios + +If future requirements change, our architecture supports algorithm swapping: + +- **Mobile-Heavy Clients**: Reduce difficulty to 2-3 bits +- **High-Security Environments**: Increase difficulty to 8-10 bits +- **Algorithm Migration**: Protocol supports algorithm field for future updates +- **Hybrid Approach**: Different algorithms per client capability + +## Implementation Recommendations + +### Difficulty Scaling Strategy + +- **Start Conservative**: Begin with 4-bit difficulty (16 attempts average) +- **Monitor Performance**: Track client success rates and completion times +- **Adjust Dynamically**: Increase difficulty under attack, decrease during normal operation +- **Client Feedback**: Monitor error rates to avoid excluding legitimate clients + +### Future Evolution Path + +1. **Phase 1**: SHA-256 hashcash with HMAC (current) +2. **Phase 2**: Optional client capability negotiation +3. **Phase 3**: Multi-algorithm support for different client classes +4. **Phase 4**: Machine learning-based difficulty adjustment + +The chosen SHA-256 hashcash approach provides the optimal balance of simplicity, performance, and security for our anti-DDOS use case while maintaining flexibility for future enhancement. \ No newline at end of file diff --git a/PROTOCOL.md b/docs/PROTOCOL.md similarity index 95% rename from PROTOCOL.md rename to docs/PROTOCOL.md index aed99a3..d203f1e 100644 --- a/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -8,19 +8,19 @@ The protocol uses **HMAC-signed challenges** for stateless server operation, agg ## Proof of Work Algorithm Choice -### Algorithm: Hashcash with HMAC Authentication +### Selected Algorithm: SHA-256 Hashcash with HMAC Authentication The protocol uses **SHA-256 based Hashcash** with **HMAC-signed challenges** for secure, stateless operation. -### Rationale +For detailed analysis of alternative PoW algorithms and comprehensive justification of this choice, see [POW_ANALYSIS.md](./POW_ANALYSIS.md). -- **Proven Security**: SHA-256 is cryptographically secure and widely tested in production systems -- **Stateless Server**: HMAC signatures eliminate the need for challenge storage, enabling horizontal scaling -- **Adjustable Difficulty**: Can dynamically scale protection based on attack severity and server load -- **CPU-Bound**: Requires computational work, not memory, making it fair across different client hardware -- **Fast Verification**: Server can quickly verify both PoW solutions and HMAC signatures without maintaining state -- **Replay Protection**: HMAC signatures combined with TTL prevent replay and forgery attacks -- **Industry Standard**: Similar to Bitcoin's approach, well-understood and battle-tested +### Key Benefits + +- **Proven Security**: Battle-tested in Bitcoin with 15+ years of production experience +- **Stateless Server**: HMAC signatures eliminate challenge storage, enabling horizontal scaling +- **Universal Compatibility**: No memory requirements ensure compatibility across all client types +- **Fast Verification**: Near-instant verification enables high server throughput under attack +- **Adjustable Difficulty**: Fine-grained control through leading zero bits (3-10 bits practical range) ### Difficulty Scaling Strategy