robust_server_socket 0.3.3 → 0.4.3

data/README.en.md

@@ -2,7 +2,72 @@
 
 Gem for inter-service authorization, used in pair with RobustClientSocket
 
-### ⚠️ Not Production Tested (yet)
+### ⚠️ Not Production Tested (yet) but tested in staging environment
+
+`Not vibecoded`
+
+## WHY
+
+### The Problem
+
+When building microservice architecture, the server side faces:
+
+- **Lack of verification**: How to verify that a request came from a trusted service?
+- **Replay attacks**: Intercepted requests can be replayed
+- **DDoS attacks**: Need to limit request frequency
+- **Boilerplate code**: Repetitive validation logic in every service
+
+#### Even if infrastructure is behind a DMZ in a private network, there is still room for SSRF or OpenRedirect attacks
+
+### The Solution
+
+RobustServerSocket provides:
+
+- **RSA decryption**: Token authenticity verification
+- **Client whitelist**: Only authorized services allowed
+- **Replay protection**: Blacklist of used tokens in Redis
+- **Rate limiting**: Sliding window per-client request limits
+
+## HOW IT WORKS
+
+### Architecture
+
+```
+Incoming request with Secure-Token
+            │
+            v
+┌──────────────────────────────┐
+│    RobustServerSocket        │
+│                              │
+│  1. RSA Decrypt              │
+│  2. Validate Format          │
+│  3. Check Client Whitelist   │
+│  4. Check Rate Limit         │
+│  5. Check Token Reuse        │
+│  6. Check Token Expiration   │
+└──────────────┬───────────────┘
+               │
+      ┌────────┼────────┐
+      v                  v
+ ✅ Success          ❌ Error
+ (continue)         (401/403/429)
+```
+
+### Validation Flow
+
+1. **Decryption**: Base64 decode → RSA decrypt with private key
+2. **Parsing**: Extract `{client_name}_{timestamp_ms}` from token
+3. **Whitelist**: Verify client_name is in `allowed_services`
+4. **Rate limit**: Sliding window — check request count within `rate_limit_window_seconds`
+5. **Replay check**: Verify token hasn't been used (Redis)
+6. **Staleness**: Verify timestamp is current (with ±30s clock skew tolerance)
+
+### Modular System
+
+Checks are enabled via `using_modules`:
+- `:client_auth_protection` — client whitelist
+- `:replay_attack_protection` — prevent token reuse
+- `:rate_limit_protection` — sliding window rate limiting
 
 ## 📋 Table of Contents
 
@@ -19,28 +84,25 @@ RobustServerSocket implements a multi-layered protection system for inter-servic
 ### 1. Cryptographic Protection
 - **RSA-2048 Encryption**: Uses RSA key pairs with minimum 2048-bit length
 - **Key Validation**: Automatic key size verification during configuration
-- **Asymmetric Encryption**: Private key on server, public keys on clients
 
-### 2. Token Reuse Protection
-- **One-time Tokens**: Each token can only be used once
-- **Redis Blacklist**: Used tokens are automatically added to blacklist
-- **Atomic Verification**: Race conditions prevented via Redis Lua scripts
+### 2. Access Control
+- **Client Whitelist**: Only authorized services can connect, when `:client_auth_protection` module is enabled
+- **Name-based Identification**: Each client must be explicitly listed in `allowed_services`
 
-### 3. Time-based Restrictions
-- **Expiration Time**: Configurable token lifetime
-- **Automatic Expiration**: Tokens automatically become invalid after expiration
-- **Replay Attack Protection**: Old tokens cannot be reused
+### 3. Replay Attack Protection
+- **One-time Tokens**: Used tokens are added to a Redis blacklist, when `:replay_attack_protection` is enabled
+- **Staleness Check**: Tokens automatically become invalid after `token_expiration_time`
+- **Clock Skew Tolerance**: ±30 seconds (CLOCK_SKEW)
+- **Blacklist TTL**: Computed automatically as `token_expiration_time + CLOCK_SKEW`
 
-### 4. Access Control
-- **Client Whitelist**: Only authorized services can connect
-- **Name-based Identification**: Each client must be explicitly listed in `allowed_services`
-- **Token Format Validation**: Strict token structure verification
+### 4. Rate Limiting
+- **Sliding Window**: When `:rate_limit_protection` is enabled — precise request counting without the burst effect of fixed windows
+- **Fail-open Strategy**: If Redis is unavailable, requests are allowed through (for service reliability)
+- **Per-client Isolation**: Counter is tracked individually per `client_name`
 
-### 5. Rate Limiting (optional)
-- **DDoS Protection**: Limit number of requests from each client
-- **Sliding Window**: Fair distribution of requests over time
-- **Fail-open Strategy**: If Redis is unavailable, requests are allowed (for reliability)
-- **Per-client Limits**: Individual counters for each client
+### 5. SSL Stripping / MITM Protection
+- **Enforce HTTPS on server**: All requests should be made over HTTPS to protect tokens from interception
+- **Enabled on RobustClientSocket with `ssl_verify: true`**
 
 ### 6. Injection Protection
 - **Input Validation**: Type, length, and format verification of tokens
@@ -49,16 +111,13 @@ RobustServerSocket implements a multi-layered protection system for inter-servic
 
 ## 📦 Installation
 
-Add to Gemfile:
-
 ```ruby
 gem 'robust_server_socket'
 ```
 
-Then execute:
-
-```bash
-bundle install
+and on the client:
+```ruby
+gem 'robust_client_socket'
 ```
 
 ## ⚙️ Configuration
@@ -67,198 +126,120 @@ Create file `config/initializers/robust_server_socket.rb`:
 
 ```ruby
 RobustServerSocket.configure do |c|
-  # REQUIRED PARAMETERS
-  
+  c.using_modules = %i[
+    client_auth_protection
+    replay_attack_protection
+    rate_limit_protection
+  ]
+
   # Service private key (RSA-2048 or higher)
-  # IMPORTANT: Store in environment variables, DO NOT commit to git!
   c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
-  
-  # Token lifetime in seconds
-  # Recommendation: 1-3 seconds for production (time from client request to server)
-  c.token_expiration_time = 3
-  
+
+  # Token lifetime in seconds (must match TTL on client side)
+  c.token_expiration_time = 10
+
   # List of allowed services (whitelist)
-  # Must match names in client keychain
+  # Must match service_name in RobustClientSocket
   c.allowed_services = %w[core payments notifications]
-  
-  # Redis for storing used tokens
+
+  # Redis for replay_attack_protection and rate_limit_protection
   c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
-  c.redis_pass = ENV['REDIS_PASSWORD'] # can be nil for local development
-  
-  # OPTIONAL PARAMETERS: Rate Limiting
-  
-  # Enable rate limiting (default: false)
-  c.rate_limit_enabled = true
-  
-  # Maximum requests per time window (default: 100)
-  c.rate_limit_max_requests = 100
-  
-  # Time window size in seconds (default: 60)
-  c.rate_limit_window_seconds = 60
+  c.redis_pass = ENV['REDIS_PASSWORD']
+
+  # rate_limit_protection
+  c.rate_limit_max_requests = 100   # max requests per window (default: 100)
+  c.rate_limit_window_seconds = 60  # window size in seconds (default: 60)
 end
 
-# Load configuration with validation
 RobustServerSocket.load!
 ```
 
+### Configuration Options
+
+| Parameter                   | Type    | Required | Default                                                                             | Description                                     |
+|-----------------------------|---------|----------|-------------------------------------------------------------------------------------|-------------------------------------------------|
+| `private_key`               | String  | ✅       | —                                                                                   | Service private RSA key (RSA-2048 or higher)    |
+| `token_expiration_time`     | Integer | ✅       | 10                                                                                  | Token lifetime in seconds                       |
+| `allowed_services`          | Array   | ✅       | —                                                                                   | Allowed services whitelist                      |
+| `redis_url`                 | String  | ✅       | —                                                                                   | Redis connection URL                            |
+| `redis_pass`                | String  | ❌       | nil                                                                                 | Redis password                                  |
+| `using_modules`             | Array   | ❌       | `[:client_auth_protection, :rate_limit_protection, :replay_attack_protection]`      | Enabled modules                                 |
+| `rate_limit_max_requests`   | Integer | ❌       | 100                                                                                 | Max requests per window                         |
+| `rate_limit_window_seconds` | Integer | ❌       | 60                                                                                  | Window size in seconds                          |
+
+> `store_used_token_time` is no longer configurable — computed automatically as `token_expiration_time + 30` (CLOCK_SKEW).
+
+### Compatibility with RobustClientSocket
+
+The token contains a timestamp in **milliseconds**. RobustClientSocket starting from version X.X must generate:
+
+```ruby
+Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+```
+
+The legacy `Time.now.utc.to_i` (seconds) will cause all tokens to be rejected as `stale`.
+
 ## 🚀 Usage
 
 ### Basic Authorization
 
 ```ruby
-# In controller or middleware
 class ApiController < ApplicationController
   before_action :authenticate_service!
-  
+
   private
-  
+
   def authenticate_service!
-    # Header configured in RobustClientSocket (SECURE-TOKEN default)
     token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
-    
-    @current_service = RobustServerSocket::ClientToken.validate!(token) # bang method (raises errors)
+    @current_service = RobustServerSocket::ClientToken.validate!(token)
   rescue RobustServerSocket::ClientToken::InvalidToken
     render json: { error: 'Invalid token' }, status: :unauthorized
-  rescue RobustServerSocket::ClientToken::UnauthorizedClient
+  rescue RobustServerSocket::Modules::ClientAuthProtection::UnauthorizedClient
     render json: { error: 'Unauthorized service' }, status: :forbidden
-  rescue RobustServerSocket::ClientToken::UsedToken
+  rescue RobustServerSocket::Modules::ReplayAttackProtection::UsedToken
     render json: { error: 'Token already used' }, status: :unauthorized
-  rescue RobustServerSocket::ClientToken::StaleToken
+  rescue RobustServerSocket::Modules::ReplayAttackProtection::StaleToken
     render json: { error: 'Token expired' }, status: :unauthorized
   rescue RobustServerSocket::RateLimiter::RateLimitExceeded => e
     render json: { error: e.message }, status: :too_many_requests
   end
-  
-  def authenticate_service
-    token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
-    @current_service = RobustServerSocket::ClientToken.new(token)
-    
-    if @current_service.valid? # doesn't raise errors
-      # Token is valid
-    else
-      # Token is invalid
-      render json: { error: 'Unauthorized' }, status: :unauthorized
-    end
-  end
 end
 ```
 
-### Advanced Usage
+### valid? (non-raising)
 
 ```ruby
-# Create token object
-token_string = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
-client_token = RobustServerSocket::ClientToken.new(token_string)
+token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
+client_token = RobustServerSocket::ClientToken.new(token)
 
-# Check validity (returns true/false)
 if client_token.valid?
-  # Get client name
   client_name = client_token.client
-  puts "Authorized client: #{client_name}"
 else
-  # Token is invalid
   render json: { error: 'Unauthorized' }, status: :unauthorized
 end
-
-# Quick validation with exceptions (recommended)
-begin
-  service_token = RobustServerSocket::ClientToken.validate!(token_string)
-  client_name = service_token.client
-rescue => e
-  # Handle specific errors
-end
-```
-
-### Manual Rate Limiting
-
-```ruby
-# Check current attempt count
-attempts = RobustServerSocket::RateLimiter.current_attempts('core')
-puts "Core service made #{attempts} requests"
-
-# Reset counter for specific client
-RobustServerSocket::RateLimiter.reset!('core')
-
-# Check with exception on exceeded limit
-begin
-  RobustServerSocket::RateLimiter.check!('core')
-rescue RobustServerSocket::RateLimiter::RateLimitExceeded => e
-  puts e.message # "Rate limit exceeded for core: 101/100 requests per 60s"
-end
-
-# Check without exception (returns false when exceeded)
-if RobustServerSocket::RateLimiter.check('core')
-  # Limit not exceeded
-else
-  # Limit exceeded
-end
-```
-
-## 🚦 Rate Limiting (Request Rate Limiting)
-
-### How It Works
-
-Rate Limiter protects your service from overload by limiting the number of requests from each client within a time window.
-
-**Characteristics:**
-- **Per-client counters**: Separate counter for each service
-- **Sliding window**: Window resets automatically after time expires
-- **Atomicity**: Increment and check are performed atomically (Redis LUA script)
-- **Fail-open**: When Redis is unavailable, requests are allowed (not blocked)
-
-### Limit Configuration
-
-```ruby
-RobustServerSocket.configure do |c|
-  # Enable rate limiting
-  c.rate_limit_enabled = true
-
-  # For low-traffic microservices
-  c.rate_limit_max_requests = 50
-  c.rate_limit_window_seconds = 60
-end
-```
-
-### Monitoring
-
-```ruby
-# Check current state
-clients = ['core', 'payments', 'notifications']
-clients.each do |client|
-  attempts = RobustServerSocket::RateLimiter.current_attempts(client)
-  max = RobustServerSocket.configuration.rate_limit_max_requests
-  puts "#{client}: #{attempts}/#{max}"
-end
-
-# In metrics (Prometheus, StatsD, etc.)
-clients.each do |client|
-  attempts = RobustServerSocket::RateLimiter.current_attempts(client)
-  Metrics.gauge("rate_limiter.attempts.#{client}", attempts)
-end
 ```
 
 ## ❌ Error Handling
 
 ### Exception Types
 
-| Exception | Reason | HTTP Status | Action |
-|-----------|--------|-------------|--------|
-| `InvalidToken` | Token cannot be decrypted or has invalid format | 401 | Check token and key correctness |
-| `UnauthorizedClient` | Client not in whitelist | 403 | Add client to `allowed_services` |
-| `UsedToken` | Token has already been used | 401 | Client must request new token |
-| `StaleToken` | Token has expired | 401 | Client must request new token |
-| `RateLimitExceeded` | Rate limit exceeded | 429 | Client should wait or retry later |
+| Exception                                                  | Reason                                    | HTTP Status |
+|------------------------------------------------------------|-------------------------------------------|-------------|
+| `ClientToken::InvalidToken`                                | Token cannot be decrypted or wrong format | 401         |
+| `Modules::ClientAuthProtection::UnauthorizedClient`        | Client not in whitelist                   | 403         |
+| `Modules::ReplayAttackProtection::UsedToken`               | Token has already been used               | 401         |
+| `Modules::ReplayAttackProtection::StaleToken`              | Token expired or from the future (>30s)   | 401         |
+| `RateLimiter::RateLimitExceeded`                           | Rate limit exceeded                       | 429         |
 
 ### Centralized Error Handling
 
 ```ruby
-# In ApplicationController
 rescue_from RobustServerSocket::ClientToken::InvalidToken,
-            RobustServerSocket::ClientToken::UsedToken,
-            RobustServerSocket::ClientToken::StaleToken,
+            RobustServerSocket::Modules::ReplayAttackProtection::UsedToken,
+            RobustServerSocket::Modules::ReplayAttackProtection::StaleToken,
             with: :unauthorized_response
 
-rescue_from RobustServerSocket::ClientToken::UnauthorizedClient,
+rescue_from RobustServerSocket::Modules::ClientAuthProtection::UnauthorizedClient,
             with: :forbidden_response
 
 rescue_from RobustServerSocket::RateLimiter::RateLimitExceeded,
@@ -267,106 +248,24 @@ rescue_from RobustServerSocket::RateLimiter::RateLimitExceeded,
 private
 
 def unauthorized_response(exception)
-  render json: {
-    error: 'Authentication failed',
-    message: exception.message,
-    type: exception.class.name
-  }, status: :unauthorized
+  render json: { error: 'Authentication failed', message: exception.message }, status: :unauthorized
 end
 
 def forbidden_response(exception)
-  render json: {
-    error: 'Access denied',
-    message: exception.message,
-    type: exception.class.name
-  }, status: :forbidden
+  render json: { error: 'Access denied', message: exception.message }, status: :forbidden
 end
 
 def rate_limit_response(exception)
   render json: {
     error: 'Too many requests',
     message: exception.message,
-    type: exception.class.name,
     retry_after: RobustServerSocket.configuration.rate_limit_window_seconds
   }, status: :too_many_requests
 end
 ```
 
-## 💡 Usage Recommendations
-
-### 1. Key Management
-
-**✅ DO:**
-```ruby
-# Store keys in environment variables
-c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
-
-# Use secrets management (AWS Secrets Manager, Vault, etc.)
-c.private_key = Rails.application.credentials.dig(:robust_server, :private_key)
-
-# Generate keys correctly
-# openssl genrsa -out private_key.pem 2048
-# openssl rsa -in private_key.pem -pubout -out public_key.pem
-```
-
-**❌ DON'T:**
-```ruby
-# DON'T commit keys to git
-c.private_key = "-----BEGIN PRIVATE KEY-----\nMII..."
-
-# DON'T use weak keys
-# Minimum RSA-2048, RSA-4096 recommended for high security
-```
-
-### 2. Redis Configuration
-
-**✅ DO:**
-```ruby
-# Use separate namespace for each environment
-c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
-
-# Configure connection pool in production
-# In config/initializers/redis.rb
-Redis.current = ConnectionPool.new(size: 5, timeout: 5) do
-  Redis.new(url: ENV['REDIS_URL'], password: ENV['REDIS_PASSWORD'])
-end
-
-# Monitor Redis status
-# Use Redis Sentinel or Cluster for high availability
-```
-
-**❌ DON'T:**
-```ruby
-# DON'T use same Redis DB for all environments, use separate Redis DB
-# DON'T ignore Redis errors (rate limiter is already fail-open, but log them)
-```
-
-### 5. Service Whitelist
-
-```ruby
-# Explicitly specify only necessary services
-c.allowed_services = %w[core payments] # ✅
-
-# DON'T use wildcards or regular expressions
-c.allowed_services = %w[*] # ❌ DANGEROUS!
-
-# Synchronize with client keychain
-# Server (robust_server_socket):
-c.allowed_services = %w[core]
-
-# Client (robust_client_socket):
-c.keychain = {
-  core: { # ← Must match
-    base_uri: 'https://core.example.com',
-    public_key: '-----BEGIN PUBLIC KEY-----...'
-  }
-}
-```
-
 ## 🤝 Integration with RobustClientSocket
 
-For full functionality, configure the client side:
-
 ```ruby
 # On client (RobustClientSocket)
 RobustClientSocket.configure do |c|
@@ -374,272 +273,49 @@ RobustClientSocket.configure do |c|
   c.keychain = {
     payments: {
       base_uri: 'https://payments.example.com',
-      public_key: '-----BEGIN PUBLIC KEY-----...' # Public key of payments server
+      public_key: '-----BEGIN PUBLIC KEY-----...'
     }
   }
 end
 
 # On server (RobustServerSocket)
 RobustServerSocket.configure do |c|
-  c.allowed_services = %w[core] # ← Matches client's service_name
-  c.private_key = '-----BEGIN PRIVATE KEY-----...' # Private pair to public_key
+  c.allowed_services = %w[core]
+  c.private_key = '-----BEGIN PRIVATE KEY-----...'
 end
 ```
 
-## 📚 Additional Resources
-
-- [RobustClientSocket documentation](https://github.com/tee0zed/robust_client_socket)
-- [RSA encryption best practices](https://www.openssl.org/docs/)
-- [Redis security guide](https://redis.io/topics/security)
-
-## 📝 License
-
-See [MIT-LICENSE](MIT-LICENSE) file
-
-## 🐛 Bugs and Suggestions
-
-Report issues through your repository's issue tracker.
+## 📊 Performance
 
-
-#### Test: 1000 Requests with Token Validation
+### Benchmark: 1000 Requests with Token Validation
 
 **Without RobustServerSocket (plain HTTP controller):**
-```ruby
-Benchmark.measure do
-  1000.times do
-    # Regular request without authorization
-    get '/api/v1/partners/719a68e4-3457-45dd-8d7f-73f1d367b87a/merchants'
-  end
-end
-```
-
-**Results (approximate):**
-- **Real time**: ~2.5 seconds
-- No token verification
-- No RSA decryption
-- No Redis checks
-
----
+- Real time: ~2.5 seconds
+- No token verification, no RSA decryption, no Redis checks
 
 **With RobustServerSocket (full protection):**
-```ruby
-Benchmark.measure do
-  1000.times do
-    # Request with RobustClientSocket (RSA + tokens)
-    RobustClientSocket::CoreApi.get('/api/v1/partners/719a68e4-3457-45dd-8d7f-73f1d367b87a/merchants')
-  end
-end
-```
-
-**Results:**
-- **Real time**: 2.77 seconds
-- **User CPU**: 0.23 seconds
-- **System CPU**: 0.54 seconds
-- **Total CPU**: 0.77 seconds
-
-### 📊 Security Overhead Analysis
-
-| Operation | Time | % of Request |
-|-----------|------|-------------|
-| **RSA Decryption** | ~0.1-0.2ms | 3-7% |
-| **Redis Token Check** | ~0.05-0.1ms | 2-3% |
-| **Rate Limiting** | ~0.02-0.05ms | 1% |
-| **Whitelist Validation** | <0.01ms | <1% |
-| **Total Overhead** | **~0.2-0.4ms** | **~10-15%** |
-
-### 🎯 Key Findings
-
-1. **Minimal overhead (~0.3ms per request)**
-   - RSA-2048 decryption: ~0.15ms
-   - Redis operations: ~0.08ms
-   - Rate limiting: ~0.03ms
-   
-2. **Scales linearly**
-   - 100 req/s = +30ms overhead
-   - 1000 req/s = +300ms overhead
-   - Acceptable for most applications
-
-3. **Redis is main bottleneck**
-   - Use Redis Sentinel/Cluster
-   - Connection pooling is critical
-   - Fail-open strategy for reliability
-
-### 💡 Performance Optimization
-
-**1. Redis Connection Pool:**
-
-```ruby
-# config/initializers/redis.rb
-require 'connection_pool'
-
-REDIS_POOL = ConnectionPool.new(size: 25, timeout: 5) do
-  Redis.new(
-    url: ENV['REDIS_URL'],
-    password: ENV['REDIS_PASSWORD'],
-    reconnect_attempts: 3,
-    reconnect_delay: 0.5,
-    reconnect_delay_max: 5.0
-  )
-end
-
-# In RobustServerSocket::SecureToken::Cacher
-def self.with_redis
-  REDIS_POOL.with do |redis|
-    yield redis
-  end
-end
-```
-
-**2. Public Key Caching:**
-
-```ruby
-# Keys are already cached at load!, but can be optimized
-class RobustServerSocket::ClientToken
-  # Keys are loaded once at application startup
-  # No additional optimization needed
-end
-```
-
-**3. Rate Limiting Optimization:**
-
-```ruby
-RobustServerSocket.configure do |c|
-  # For high-load systems
-  c.rate_limit_enabled = true
-  c.rate_limit_max_requests = 1000  # Increase limit
-  c.rate_limit_window_seconds = 60
-  
-  # For low-load systems
-  c.rate_limit_max_requests = 100
-  c.rate_limit_window_seconds = 60
-end
-```
-
-**4. Token Expiration Optimization:**
-
-```ruby
-# Short lifetime = more requests for new tokens
-c.token_expiration_time = 10.minutes  # ❌ High traffic
-
-# Optimal time for inter-service calls
-c.token_expiration_time = 3  # ✅ 3 seconds is enough
-```
-
-### 🔬 Performance Monitoring
-
-**Metrics to Track:**
-
-```ruby
-class ApiController < ApplicationController
-  around_action :track_auth_performance
-  
-  private
-  
-  def track_auth_performance
-    start = Time.now
-    
-    begin
-      yield
-    ensure
-      duration = ((Time.now - start) * 1000).round(2)
-      
-      # Total request time
-      Metrics.timing('request.duration', duration, tags: [
-        "controller:#{controller_name}",
-        "action:#{action_name}"
-      ])
-      
-      # Authentication attempts
-      if @current_service
-        Metrics.increment('auth.success', tags: ["service:#{@current_service.client}"])
-      else
-        Metrics.increment('auth.failure')
-      end
-    end
-  end
-end
-
-# Specific metrics for RobustServerSocket
-module RobustServerSocket
-  class ClientToken
-    def self.validate_with_metrics!(token)
-      start = Time.now
-      result = validate!(token)
-      duration = ((Time.now - start) * 1000).round(2)
-      
-      Metrics.timing('robust_server.validation.duration', duration)
-      result
-    rescue StandardError => e
-      Metrics.increment('robust_server.validation.error', tags: ["error:#{e.class.name}"])
-      raise
-    end
-  end
-end
-```
+- Real time: ~2.77 seconds
+- User CPU: 0.23s, System CPU: 0.54s
 
-### 📈 Performance at Different Loads
+### Security Overhead Analysis
 
-| Req/s | Without Protection | With RobustServerSocket | Overhead | Acceptable |
-|-------|-------------------|------------------------|----------|-----------|
-| 10 | 100ms | 103ms | 3ms | ✅ Excellent |
-| 100 | 1s | 1.03s | 30ms | ✅ Excellent |
-| 500 | 5s | 5.15s | 150ms | ✅ Good |
-| 1,000 | 10s | 10.3s | 300ms | ✅ Acceptable |
-| 5,000 | 50s | 51.5s | 1.5s | ⚠️ Redis scaling needed |
-| 10,000 | 100s | 103s | 3s | ⚠️ Need Redis Cluster |
+| Operation              | Time        | % of Request |
+|------------------------|-------------|-------------|
+| RSA Decryption         | ~0.1–0.2ms  | 3–7%        |
+| Redis Token Check      | ~0.05–0.1ms | 2–3%        |
+| Rate Limiting          | ~0.02–0.05ms| 1%          |
+| Whitelist Validation   | <0.01ms     | <1%         |
+| **Total Overhead**     | **~0.2–0.4ms** | **~10–15%** |
 
-**Conclusion:** Up to 1000 req/s - excellent performance. Higher loads require Redis scaling.
+Up to 1000 req/s — excellent performance. Higher loads require Redis Sentinel/Cluster.
 
-### 🚀 Production Recommendations
+## 🗺️ TODO
 
-**For high-load systems (>1000 req/s):**
-
-1. **Redis Cluster** - distributed load
-2. **Connection Pool** - minimum 25-50 connections
-3. **Monitor Redis** - latency, memory, connections
-4. **Fail-over Strategy** - Redis Sentinel
-5. **CDN for static** - reduce overall load
-
-**For medium load (100-1000 req/s):**
-
-1. **Standalone Redis** with persistence
-2. **Connection Pool** - 10-25 connections
-3. **Basic monitoring**
-4. **Rate limiting** - spike protection
-
-**For low load (<100 req/s):**
-
-1. **Simple Redis** setup
-2. **Default connection pool** (5)
-3. **Standard configuration**
-
-## 🤝 Integration with RobustClientSocket
-
-For full functionality, configure the client side:
-
-```ruby
-# On client (RobustClientSocket)
-RobustClientSocket.configure do |c|
-  c.service_name = 'core' # ← Must be in server's allowed_services
-  c.keychain = {
-    payments: {
-      base_uri: 'https://payments.example.com',
-      public_key: '-----BEGIN PUBLIC KEY-----...' # Public key of payments server
-    }
-  }
-end
-
-# On server (RobustServerSocket)
-RobustServerSocket.configure do |c|
-  c.allowed_services = %w[core] # ← Matches client's service_name
-  c.private_key = '-----BEGIN PRIVATE KEY-----...' # Private pair to public_key
-end
-```
+- [ ] **Per-client rate limit keys** — configurable individual limits per `client_name` instead of a single global limit
 
 ## 📚 Additional Resources
 
-- [BENCHMARK_ANALYSIS.md](BENCHMARK_ANALYSIS.md)
-- [RobustClientSocket documentation](../robust_client_socket/README.md)
+- [RobustClientSocket](https://github.com/tee0zed/robust_client_socket)
 - [RSA encryption best practices](https://www.openssl.org/docs/)
 - [Redis security guide](https://redis.io/topics/security)
 
@@ -649,4 +325,4 @@ See [MIT-LICENSE](MIT-LICENSE) file
 
 ## 🐛 Bugs and Suggestions
 
-Report issues through your repository's issue tracker.
+Report issues via GitHub issues, or directly at Telegram @cruel_mango or email tee0zed@gmail.com