docs/IMPLEMENTATION.md

@@ -1,50 +1,22 @@
 # Word of Wisdom Server - Implementation Plan
 
-## Phase 1: Proof of Work Package Implementation
+## Phase 1: Project Setup & Core Architecture
-**Goal**: Create standalone, testable PoW package with HMAC-signed stateless challenges
+- [ ] Initialize Go module and project structure
-
-- [ ] **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
-- [ ] Integrate PoW package into server architecture
+- [ ] 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
@@ -184,4 +156,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,143 +201,6 @@ 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

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