docs/IMPLEMENTATION.md

@@ -1,22 +1,50 @@
 # Word of Wisdom Server - Implementation Plan
 
-## Phase 1: Project Setup & Core Architecture
+## Phase 1: Proof of Work Package Implementation
-- [ ] Initialize Go module and project structure
+**Goal**: Create standalone, testable PoW package with HMAC-signed stateless challenges
+
+- [ ] **Project Setup**
+  - [ ] Initialize Go module and basic project structure
+  - [ ] Create PoW challenge structure and types
+  - [ ] Set up testing framework and utilities
+
+- [ ] **Challenge Generation & HMAC Security**
+  - [ ] Implement HMAC-signed challenge generation (stateless)
+  - [ ] Create challenge authenticity verification
+  - [ ] Add timestamp validation for replay protection (5 minutes TTL)
+  - [ ] Implement canonical challenge field ordering for HMAC
+  - [ ] Add Base64URL encoding for HMAC signatures
+  - [ ] Implement challenge string construction (`quotes:timestamp:difficulty:random`)
+
+- [ ] **PoW Algorithm Implementation**
+  - [ ] Implement SHA-256 based PoW solution algorithm
+  - [ ] Implement leading zero bit counting for difficulty
+  - [ ] Create nonce iteration and solution finding
+  - [ ] Add difficulty scaling (3-10 bits range)
+  - [ ] Create challenge string format: `quotes:timestamp:difficulty:random:nonce`
+  - [ ] Implement hash verification for submitted solutions
+
+- [ ] **Verification & Validation**
+  - [ ] Create challenge verification logic with HMAC validation
+  - [ ] Add solution validation against original challenge
+  - [ ] Test HMAC tamper detection and validation
+  - [ ] Add difficulty adjustment mechanisms
+
+- [ ] **Testing & Performance**
+  - [ ] Unit tests for challenge generation and verification
+  - [ ] Unit tests for HMAC signing and validation
+  - [ ] Unit tests for PoW solution finding and verification
+  - [ ] Benchmark tests for different difficulty levels
+  - [ ] Test edge cases (expired challenges, invalid HMAC, wrong difficulty)
+  - [ ] Performance tests for concurrent challenge operations
+
+## Phase 2: Basic Server Architecture
 - [ ] 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
+- [ ] Integrate PoW package into server architecture
-
-## 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
@@ -156,4 +184,4 @@
 - [ ] 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
+- [ ] Clear documentation for deployment and operation

docs/POW_ANALYSIS.md

@@ -201,6 +201,143 @@ Our implementation addresses SHA-256 hashcash limitations:
 - **Forgery Prevention**: Server secret prevents challenge generation attacks
 - **Scalability**: No server state enables horizontal scaling without coordination
 
+## HMAC Stateless Design Analysis
+
+### HMAC vs Storage-Based Challenge Management
+
+#### Stateless Approach (HMAC) - CHOSEN
+
+**How it works**:
+1. Server generates challenge data with timestamp and random values
+2. Server computes HMAC signature: `hmac = HMAC-SHA256(secret_key, challenge_fields)`
+3. Server sends challenge + HMAC signature (stores nothing)
+4. Client submits solution with original challenge + HMAC
+5. Server recomputes HMAC to verify challenge authenticity
+6. If HMAC valid and timestamp within TTL, verify PoW solution
+
+**Advantages**:
+- **Zero Storage**: No database or memory requirements for active challenges
+- **Horizontal Scaling**: Any server instance can validate any challenge
+- **High Performance**: No database lookups during attack conditions
+- **Fault Tolerance**: Server restarts don't invalidate active challenges
+- **Simple Architecture**: No challenge cleanup or garbage collection needed
+- **Cost Effective**: Minimal infrastructure requirements for scaling
+
+**Security Guarantees**:
+- **Authenticity**: Only server with secret key can create valid challenges
+- **Integrity**: Any tampering with challenge fields invalidates HMAC
+- **Expiration**: Timestamp validation prevents stale challenge reuse
+- **Non-repudiation**: Server can verify it issued specific challenge
+
+#### Stateful Approach (Storage-Based) - REJECTED
+
+**How it would work**:
+1. Server generates challenge and stores in database/memory
+2. Server sends challenge to client (no HMAC needed)
+3. Client submits solution with challenge ID
+4. Server looks up stored challenge to verify solution
+5. Server removes challenge from storage after use
+
+**Advantages**:
+- **Perfect Replay Protection**: Each challenge used exactly once
+- **Granular Control**: Individual challenge revocation possible
+- **Rich Analytics**: Track per-challenge usage patterns
+- **Complex Rate Limiting**: Per-challenge attempt limits
+- **Audit Trail**: Complete challenge lifecycle logging
+
+**Disadvantages**:
+- **Storage Overhead**: Database/memory requirements grow with concurrent users
+- **Scaling Complexity**: Challenge synchronization across server instances
+- **Performance Impact**: Database queries during high-load attack scenarios
+- **Single Point of Failure**: Database outage invalidates all active challenges
+- **Cleanup Complexity**: Expired challenge garbage collection required
+- **Infrastructure Cost**: Database clustering for high availability
+
+### Security Trade-offs Analysis
+
+#### Replay Attack Comparison
+
+**HMAC Approach**:
+- **Risk**: Same challenge reusable within 5-minute TTL window
+- **Mitigation**: Short TTL limits replay window
+- **Impact**: Acceptable for DDoS protection use case
+- **Real Risk**: Low (attacker gains no significant advantage)
+
+**Storage Approach**:
+- **Risk**: Zero replay attacks (perfect single-use enforcement)
+- **Cost**: Significant infrastructure and complexity overhead
+- **Impact**: Minimal benefit for DDoS protection scenario
+
+#### Rate Limiting Capabilities
+
+**HMAC Limitations**:
+- Cannot track per-challenge attempt counts
+- Cannot revoke specific problematic challenges
+- Fixed TTL for all challenges regardless of client behavior
+
+**HMAC Mitigations**:
+- IP-based rate limiting remains fully functional
+- Failed solution tracking per IP provides abuse detection
+- Adaptive difficulty scaling responds to attack patterns
+- Connection-level limits prevent resource exhaustion
+
+**Storage Benefits**:
+- Per-challenge attempt counting
+- Individual challenge blacklisting
+- Dynamic TTL adjustment per client
+- Rich forensic analysis capabilities
+
+### Design Decision Rationale
+
+For the Word of Wisdom DDoS protection system, **HMAC stateless design** is optimal because:
+
+#### Primary Requirements Met
+- **High Availability**: System remains functional during database outages
+- **Horizontal Scaling**: Simple load balancer distribution without coordination
+- **Attack Resistance**: Performance doesn't degrade with concurrent challenges
+- **Operational Simplicity**: Minimal infrastructure for production deployment
+
+#### Acceptable Trade-offs
+- **Replay Window**: 5-minute replay risk acceptable vs infrastructure complexity
+- **Rate Limiting**: IP-based limits sufficient for DDoS protection use case
+- **Analytics**: Basic failure tracking adequate for adaptive difficulty
+- **Forensics**: Connection-level logging provides sufficient attack analysis
+
+#### Use Case Alignment
+- **DDoS Protection Focus**: System optimized for availability under attack
+- **Quote Service**: Low-value target doesn't justify complex security measures
+- **Temporary Challenges**: Short-lived challenges reduce replay attack value
+- **Cost Sensitivity**: Minimal infrastructure preferred for educational/demo system
+
+### When Storage-Based Would Be Better
+
+**High-Security Applications**:
+- Financial services requiring perfect replay protection
+- Authentication systems with strict single-use requirements
+- High-value resource protection where replay attacks have significant impact
+
+**Complex Rate Limiting Needs**:
+- Per-user challenge quotas required
+- Sophisticated abuse pattern detection needed
+- Real-time challenge analytics essential for operations
+
+**Rich Monitoring Requirements**:
+- Detailed forensic analysis of attack patterns
+- Challenge lifecycle tracking for security auditing
+- Complex rate limiting with per-challenge granularity
+
+### Implementation Validation
+
+The HMAC approach successfully addresses all primary security concerns:
+
+1. **Challenge Authenticity**: HMAC prevents forged challenges
+2. **Data Integrity**: Tampering detection through signature validation  
+3. **Replay Protection**: Timestamp + TTL limits reuse window
+4. **Server Scalability**: No coordination required between instances
+5. **Attack Resilience**: Performance maintained under high challenge volume
+
+The trade-offs (limited replay protection, reduced analytics) are acceptable given the system's primary goal of DDoS mitigation for a quote service.
+
 ### Addressing SHA-256 Cons
 
 1. **ASIC Advantage**: Mitigated by low difficulty and temporary challenges

go.mod

@@ -0,0 +1,3 @@
+module word-of-wisdom
+
+go 1.24.3