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:31:49 +07:00
commit da06452d27
No known key found for this signature in database
GPG key ID: F70DFD34F40238DE
3 changed files with 784 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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.

390
docs/PROTOCOL.md Normal file
View file

@ -0,0 +1,390 @@
# Word of Wisdom Protocol Specification
## Overview
The **Word of Wisdom** protocol is a TCP-based challenge-response protocol designed to mitigate DDoS attacks by requiring clients to solve a **Proof-of-Work (PoW)** puzzle before accessing protected resources (quotes).
The protocol uses **HMAC-signed challenges** for stateless server operation, aggressive timeouts to prevent slowloris attacks, and a simple binary framing with JSON payloads. It is **stateless** on the server thanks to HMAC-signed challenges, eliminating the need for challenge storage.
## Proof of Work Algorithm Choice
### Selected Algorithm: SHA-256 Hashcash with HMAC Authentication
The protocol uses **SHA-256 based Hashcash** with **HMAC-signed challenges** for secure, stateless operation.
For detailed analysis of alternative PoW algorithms and comprehensive justification of this choice, see [POW_ANALYSIS.md](./POW_ANALYSIS.md).
### 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
- **Normal Operations**: 4-bit difficulty (average 16 hash attempts)
- **Load-Based Adjustment**: +1 bit difficulty when server load exceeds threshold
- **Failure-Based Penalty**: +2 bits per 5 failed attempts in 2-minute window (capped at +6 extra bits)
- **Success Reset**: Failure counter resets to zero after successful solution
## Protocol Flow
### Successful Flow
```
Client Server
| |
|-------- CHALLENGE_REQUEST ------------->|
| |
|<------- CHALLENGE_RESPONSE -------------| (HMAC-signed)
| |
|-------- SOLUTION_REQUEST -------------->|
| |
|<------- QUOTE_RESPONSE -----------------| (if solution valid)
| |
```
### Error Flow
```
Client Server
|-------- CHALLENGE_REQUEST ------------->|
|<------- CHALLENGE_RESPONSE -------------|
|-------- SOLUTION_REQUEST (invalid) ---->|
|<------- ERROR_RESPONSE -----------------| (if solution invalid)
```
## Message Format
All protocol messages use a binary format with the following structure:
```
+------------------+------------------+------------------+
| Message Type | Length | Payload |
| (1 byte) | (4 bytes) | (N bytes) |
+------------------+------------------+------------------+
```
- **Message Type**: Single byte indicating message type (see table below)
- **Length**: 32-bit big-endian integer indicating payload length in bytes
- **Payload**: Variable-length payload (can be empty, maximum 8KB for security)
### Encoding Details
- **Endianness**: All multi-byte integers use big-endian encoding
- **JSON Format**: UTF-8 encoding, compact format (no pretty-printing)
- **Size Limits**: Maximum 8KB payload to prevent memory exhaustion attacks
## Message Types
| Type | Value | Name | Direction | Description |
|------|-------|------|-----------|-------------|
| 0x01 | CHALLENGE_REQUEST | Client → Server | Client requests a new PoW challenge |
| 0x02 | CHALLENGE_RESPONSE | Server → Client | Server issues HMAC-signed challenge |
| 0x03 | SOLUTION_REQUEST | Client → Server | Client submits challenge + nonce |
| 0x04 | QUOTE_RESPONSE | Server → Client | Server sends quote (if solution valid) |
| 0x05 | ERROR_RESPONSE | Server → Client | Server reports an error |
## Message Payloads
### CHALLENGE_REQUEST (0x01)
- **Payload**: Empty
- **Description**: Client requests a new challenge from the server
- **Usage**: First message in the protocol flow
### CHALLENGE_RESPONSE (0x02)
- **Payload**: JSON-encoded challenge object
- **Description**: Server provides HMAC-signed challenge for PoW computation
- **Format**:
```json
{
"id": "challenge_unique_id",
"timestamp": 1640995200,
"difficulty": 4,
"resource": "192.168.1.100:8080",
"random": "a1b2c3d4e5f6",
"hmac": "base64url_encoded_signature"
}
```
**Field Descriptions**:
- **id**: Unique identifier for this challenge
- **timestamp**: Unix timestamp when challenge was created
- **difficulty**: Number of leading zero bits required in solution hash
- **resource**: Server resource identifier (typically IP:port)
- **random**: Random hex string for challenge uniqueness
- **hmac**: HMAC-SHA256 signature of canonical challenge fields
**Security Notes**:
- Server is **stateless**: no need to store challenges locally
- HMAC signature prevents challenge forgery and tampering
- Timestamp enables TTL validation without server-side storage
### SOLUTION_REQUEST (0x03)
- **Payload**: JSON-encoded solution object
- **Description**: Client submits PoW solution with original challenge
- **Format**:
```json
{
"challenge": {
"id": "challenge_unique_id",
"timestamp": 1640995200,
"difficulty": 4,
"resource": "192.168.1.100:8080",
"random": "a1b2c3d4e5f6",
"hmac": "base64url_encoded_signature"
},
"nonce": "solution_nonce_value"
}
```
**Requirements**:
- Client must echo the complete original challenge object
- Nonce must produce a valid PoW hash with required difficulty
- Challenge must not be expired (within TTL window)
### QUOTE_RESPONSE (0x04)
- **Payload**: JSON-encoded quote object
- **Description**: Server sends inspirational quote after successful PoW verification
- **Format**:
```json
{
"text": "The only way to do great work is to love what you do.",
"author": "Steve Jobs",
"category": "motivation"
}
```
**Field Descriptions**:
- **text**: The inspirational quote text
- **author**: Attribution for the quote
- **category**: Thematic category (motivation, wisdom, success, etc.)
### ERROR_RESPONSE (0x05)
- **Payload**: JSON-encoded error object
- **Description**: Server reports errors in client requests or server state
- **Format**:
```json
{
"code": "INVALID_SOLUTION",
"message": "The provided PoW solution is incorrect",
"retry_after": 30
}
```
**Field Descriptions**:
- **code**: Machine-readable error code (see Error Codes section)
- **message**: Human-readable error description
- **retry_after**: Optional delay in seconds before client should retry
## Error Codes
| Code | Description | Client Action | Server Action |
|------|-------------|---------------|---------------|
| **MALFORMED_MESSAGE** | Invalid frame format or JSON parsing error | Disconnect and retry with correct format | Log error and close connection |
| **INVALID_CHALLENGE** | Challenge HMAC signature verification failed | Request new challenge from server | Generate new valid challenge |
| **INVALID_SOLUTION** | PoW hash verification failed for submitted nonce | Retry with correct nonce computation | Log failed attempt for rate limiting |
| **EXPIRED_CHALLENGE** | Challenge timestamp exceeds TTL window | Request fresh challenge from server | Generate new challenge with current timestamp |
| **RATE_LIMITED** | Client exceeds request rate limits | Wait for `retry_after` seconds before retry | Apply temporary throttling to client IP |
| **SERVER_ERROR** | Internal server error or temporary unavailability | Retry connection after delay | Log error and investigate system health |
| **TOO_MANY_CONNECTIONS** | Server at maximum connection capacity | Retry connection later | Reject new connections until capacity available |
| **DIFFICULTY_TOO_HIGH** | Adaptive difficulty exceeds client capabilities | Request new challenge or give up | May reduce difficulty if appropriate |
### Error Response Format
All errors follow the consistent ERROR_RESPONSE format:
```json
{
"code": "ERROR_CODE_NAME",
"message": "Human readable description of the error",
"retry_after": 30,
"details": {
"additional_context": "Optional additional error context"
}
}
```
### Error Handling Strategy
- **Client Errors**: Provide specific actionable error codes
- **Server Errors**: Log detailed information server-side, return generic client errors
- **Rate Limiting**: Include retry timing information in error responses
- **Security**: Avoid exposing internal system details in error messages
## Hashcash Challenge Format
The server uses **SHA-256 based Hashcash** with **HMAC authentication** for Proof of Work challenges.
### Challenge String Structure
```
resource:timestamp:difficulty:random
```
**Example**:
```
192.168.1.100:8080:1640995200:4:a1b2c3d4e5f6
```
### Solution Process
1. **Receive**: Client receives HMAC-signed challenge from server
2. **Extract**: Client extracts challenge fields to construct challenge string
3. **Iterate**: Client appends different nonce values to challenge string
4. **Hash**: Client computes SHA-256 hash of `challenge_string:nonce`
5. **Check**: Client checks if hash has required number of leading zero bits
6. **Repeat**: If not valid, increment nonce and repeat from step 4
7. **Submit**: When valid nonce found, submit solution to server
### Verification Process
Server verifies solutions through the following steps:
1. **HMAC Verification**: Verify challenge HMAC signature against server secret
2. **TTL Check**: Verify challenge timestamp is within TTL window (5 minutes)
3. **Reconstruction**: Reconstruct challenge string from submitted challenge fields
4. **Hash Computation**: Compute SHA-256 hash of `challenge_string:nonce`
5. **Difficulty Check**: Verify hash has required number of leading zero bits
6. **Success**: If all checks pass, grant access to quote resource
### Difficulty Examples
| Difficulty | Leading Zero Bits | Average Attempts | Example Hash |
|------------|-------------------|------------------|---------------|
| 3 | 3 bits | 8 | `000a1b2c...` |
| 4 | 4 bits | 16 | `0001a2b3...` |
| 5 | 5 bits | 32 | `0000a1b2...` |
| 6 | 6 bits | 64 | `00001a2b...` |
## Connection Management
### Connection Lifecycle
1. **Connect**: Client establishes TCP connection to server
2. **Challenge**: Client requests and receives HMAC-signed challenge
3. **Solve**: Client solves PoW challenge offline (can take time)
4. **Submit**: Client submits solution with challenge proof
5. **Receive**: Client receives quote (if valid) or error (if invalid)
6. **Disconnect**: Connection closes automatically after response
### Timeouts and Limits
| Parameter | Value | Purpose |
|-----------|-------|----------|
| **Challenge TTL** | 5 minutes | Prevents stale challenge reuse |
| **Solution Timeout** | 5 seconds | Prevents slowloris attacks |
| **Connection Timeout** | 15 seconds | Limits connection holding time |
| **Message Size Limit** | 8KB | Prevents memory exhaustion |
| **Max Connections** | 1000 | Global server capacity limit |
### Timeout Behavior
- **Challenge Expiry**: Challenges become invalid after 5 minutes from timestamp
- **Solution Window**: Client has 5 seconds to submit solution after challenge
- **Connection Limits**: Connections auto-close after 15 seconds of inactivity
- **Resource Protection**: Aggressive timeouts prevent resource exhaustion attacks
## Rate Limiting & DDOS Protection
### Connection-Level Protection (HAProxy/Envoy)
Handled **before application layer** by reverse proxy:
| Metric | Limit | Purpose |
|--------|-------|----------|
| **New Connections/sec** | ≤10 per IP | Prevents connection flooding |
| **Concurrent Connections** | ≤20 per IP | Limits resource usage per client |
| **Burst Allowance** | 30 connections | Handles legitimate traffic spikes |
| **Global Connection Cap** | 1000 total | Protects server capacity |
### Application-Level Protection
#### Failed Solution Tracking
- **Counter**: Track invalid solution attempts per client IP/identifier
- **Window**: Rolling 2-minute time window for failure counting
- **Penalty**: Each group of 5 failures increases difficulty by +2 bits
- **Cap**: Maximum +6 additional difficulty bits to prevent client DOS
- **Reset**: Successful solution resets failure counter to zero
#### Adaptive Difficulty Scaling
- **Load-Based**: +1 difficulty bit when server CPU/memory exceeds threshold
- **Attack Response**: Automatic difficulty increase during detected attacks
- **Recovery**: Gradual difficulty reduction as attack subsides
- **Monitoring**: Continuous monitoring of success/failure ratios
### Rate Limiting Rules
| Rule | Limit | Action |
|------|-------|--------|
| **Challenge Requests** | 10 per minute per IP | Temporary IP throttling |
| **Solution Attempts** | 5 per minute per IP | Increased difficulty penalty |
| **Invalid Solutions** | 5 per 2 minutes | +2 difficulty bits |
| **Connection Frequency** | 10 per second per IP | Connection rejection |
## Security Considerations
### PoW Security
- **Minimum Difficulty**: 3 leading zero bits (prevents trivial bypass attempts)
- **Maximum Difficulty**: 10 leading zero bits (prevents excessive client DOS)
- **Dynamic Scaling**: Adjusts automatically based on server load and attack patterns
- **CPU-Bound Work**: Memory-independent computation ensures fairness across hardware
### Challenge Security
- **Uniqueness**: Each challenge includes timestamp and cryptographic random data
- **Expiration**: Challenges automatically expire after 5-minute TTL window
- **HMAC Authentication**: Prevents challenge forgery and tampering
- **Stateless Verification**: No server-side storage required for validation
- **Replay Protection**: Timestamp and HMAC combination prevents replay attacks
### Input Validation
- **Message Size**: Strict 8KB maximum per message (prevents memory exhaustion)
- **JSON Schema**: All JSON payloads validated against strict schemas
- **Challenge Format**: Rigorous validation of challenge structure and fields
- **Nonce Validation**: Proper integer bounds checking for nonce values
- **Encoding Validation**: UTF-8 encoding validation for all text fields
### Network Security
- **Connection Limits**: Per-IP and global connection rate limiting
- **Timeout Protection**: Aggressive timeouts prevent slowloris attacks
- **Resource Binding**: Challenges tied to client connection context
- **Error Information**: Limited error details to prevent information disclosure
### Operational Security
- **HMAC Secret**: Server maintains secret key for challenge signing
- **Logging**: Comprehensive attack detection and monitoring
- **Metrics**: Real-time visibility into attack patterns and system health
- **Graceful Degradation**: System remains functional under attack conditions
## Implementation Notes
### Protocol Implementation
- **Endianness**: All multi-byte integers use big-endian encoding for consistency
- **JSON Encoding**: UTF-8 encoding for all text, compact format (no pretty-printing)
- **Required Fields**: All JSON fields marked as required must be present
- **Optional Fields**: Handle optional fields gracefully with sensible defaults
### Server Implementation
- **HMAC Secret**: Server maintains cryptographically secure secret key
- **Challenge Generation**: Use cryptographically secure random number generator
- **Quote Storage**: Preload quotes from file/database on startup
- **Concurrent Handling**: Support for multiple simultaneous client connections
- **Resource Management**: Proper cleanup of connections and temporary resources
### Client Implementation
- **PoW Computation**: Efficient nonce iteration and hash computation
- **Connection Management**: Proper TCP connection lifecycle handling
- **Error Handling**: Graceful handling of all error conditions
- **Retry Logic**: Intelligent retry with exponential backoff
### Error Handling
- **Server Errors**: Always send ERROR_RESPONSE for client-detectable errors
- **Logging**: Comprehensive server-side logging for debugging and monitoring
- **Connection Termination**: Graceful connection closure on errors
- **Client Recovery**: Clients should handle errors and retry appropriately
### Performance Considerations
- **Keep-Alive**: Not supported (one quote per connection for simplicity)
- **Connection Pooling**: Server supports concurrent connection handling
- **Memory Efficiency**: Minimal memory footprint per connection
- **CPU Efficiency**: Optimized hash computation and verification
- **Scalability**: Stateless design enables horizontal scaling
### Future Extensions
- **Resource Types**: Protocol designed to support resources beyond quotes
- **Authentication**: Framework supports future authentication mechanisms
- **Compression**: Payload compression can be added without protocol changes
- **Encryption**: TLS termination recommended at load balancer level