krendelhoff/hash-of-wisdom
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Organize documentation structure

Browse source
This commit is contained in:
Savely Krendelhoff 2025-08-22 13:41:29 +07:00
parent dec7e04c39
commit b4a08c2bc1
No known key found for this signature in database
GPG key ID: F70DFD34F40238DE
4 changed files with 461 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
CLAUDE.md Normal file
View file

@ -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`

159
docs/IMPLEMENTATION.md Normal file
View file

@ -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

235
docs/POW_ANALYSIS.md Normal file
View file

@ -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.

18
PROTOCOL.md → docs/PROTOCOL.md
View file

@ -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