robust_server_socket 0.3.3 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 626993a0fda547dc940291eb09015b688a1f761cb5345664488996ed28a1906c
-  data.tar.gz: c5bb810563a9e6682c021b6553296477b3e34ecffeeecc2121534b8e397c7377
+  metadata.gz: b7b680d77f57104621b01b7abca736c21d819abc4e59355f5e70c3dff05df2eb
+  data.tar.gz: 15d86badaa9f0c76c97f330886188a3517b7d4dfd38d94c27f7c000cee1088d3
 SHA512:
-  metadata.gz: 9361de5026c683ce6e4a92aad34b8a3358248f4774bff96eb423148ee5daf2556fe1c16f7bd98658acba11218b1e6eae67f8f3af714970474070aa256132e2e7
-  data.tar.gz: a24681663c355f6117040fcaa538b73fa5bf9a4ff43edf6e962c9d8a3727e2d107bc222233efddffefd5fdb76a282c16c56e1c7eb323488168274175e0f29993
+  metadata.gz: cbc390327dc4b6d4f382333c822cc367d0b936958d6ad8def8149e6b55a97d4137ff30690b3c3f4d9156120726a02ef12550e65065effb827a0adbe1bd196597
+  data.tar.gz: f8bc821809cabf3d0769c37549160f3d7b1456c0bc5bb3b787530171ba0eb83389fb9b4a4f65f94abc182fea34cabc740c1ca54ccd0f08d7578d5407956b0865

data/README.en.md

@@ -2,7 +2,70 @@
 
 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
+
+### 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**: 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}` from token
+3. **Whitelist**: Verify client_name is in `allowed_services`
+4. **Rate limit**: Check request count within window
+5. **Replay check**: Verify token hasn't been used (Redis)
+6. **Staleness**: Verify timestamp is current
+
+### Modular System
+
+Checks are enabled via `using_modules`:
+- `:client_auth_protection` — client whitelist
+- `:replay_attack_protection` — prevent token reuse
+- `:dos_attack_protection` — rate limiting
 
 ## 📋 Table of Contents
 
@@ -84,12 +147,7 @@ RobustServerSocket.configure do |c|
   # Redis for storing used tokens
   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
   
@@ -169,74 +227,6 @@ rescue => e
 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
@@ -292,32 +282,6 @@ def rate_limit_response(exception)
 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:**
@@ -482,7 +446,7 @@ REDIS_POOL = ConnectionPool.new(size: 25, timeout: 5) do
   )
 end
 
-# In RobustServerSocket::SecureToken::Cacher
+# In RobustServerSocket::Cacher
 def self.with_redis
   REDIS_POOL.with do |redis|
     yield redis
@@ -505,7 +469,6 @@ end
 ```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
   
@@ -638,7 +601,6 @@ end
 
 ## 📚 Additional Resources
 
-- [BENCHMARK_ANALYSIS.md](BENCHMARK_ANALYSIS.md)
 - [RobustClientSocket documentation](../robust_client_socket/README.md)
 - [RSA encryption best practices](https://www.openssl.org/docs/)
 - [Redis security guide](https://redis.io/topics/security)
@@ -649,4 +611,4 @@ See [MIT-LICENSE](MIT-LICENSE) file
 
 ## 🐛 Bugs and Suggestions
 
-Report issues through your repository's issue tracker.
+Report issues to my telegram @cruel_mango or to email tee0zed@gmail.com

data/README.md

@@ -1,8 +1,71 @@
 # RobustServerSocket
 
-Gem для межсервисной авторизации, используется в паре с RobustClientSocket
+Gem для межсервисной аутентификации, используется в паре с RobustClientSocket
 
-### ⚠️ Not Production Tested (yet)
+### ⚠️ Not Production Tested (yet) but tested in staging environment
+
+`Not vibecoded`
+
+## ПОЧЕМУ (WHY)
+
+### Проблема
+
+При построении микросервисной архитектуры серверная сторона сталкивается с:
+
+- **Отсутствием верификации**: Как проверить, что запрос пришёл от доверенного сервиса?
+- **Replay-атаками**: Перехваченные запросы могут быть повторены
+- **DDoS-атаками**: Необходимость ограничения частоты запросов
+- **Boilerplate кодом**: Повторяющаяся логика валидации в каждом сервисе
+
+### Решение
+
+RobustServerSocket предоставляет:
+
+- **RSA-дешифрование**: Проверка подлинности токенов
+- **Whitelist клиентов**: Только разрешённые сервисы
+- **Защиту от replay**: Блэклист использованных токенов в Redis
+- **Rate limiting**: Ограничение запросов на клиента
+
+## КАК ЭТО РАБОТАЕТ (HOW)
+
+### Архитектура
+
+```
+Входящий запрос с 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)
+```
+
+### Поток валидации
+
+1. **Расшифровка**: Base64 decode → RSA decrypt с приватным ключом
+2. **Парсинг**: Извлечение `{client_name}_{timestamp}` из токена
+3. **Whitelist**: Проверка client_name в `allowed_services`
+4. **Rate limit**: Проверка количества запросов в окне
+5. **Replay check**: Проверка, что токен не использован (Redis)
+6. **Staleness**: Проверка timestamp на актуальность
+
+### Модульная система
+
+Проверки подключаются через `using_modules`:
+- `:client_auth_protection` — whitelist клиентов
+- `:replay_attack_protection` — защита от повторного использования
+- `:dos_attack_protection` — rate limiting
 
 ## 📋 Содержание
 
@@ -19,33 +82,27 @@ RobustServerSocket реализует многоуровневую систем
 ### 1. Криптографическая защита
 - **RSA-2048 шифрование**: Используется пара ключей RSA с минимальной длиной 2048 бит
 - **Валидация ключей**: Автоматическая проверка размера ключа при конфигурации
-- **Асимметричное шифрование**: Приватный ключ на сервере, публичный — у клиентов
-
-### 2. Защита от повторного использования токенов
-- **Одноразовые токены**: Каждый токен может быть использован только один раз
-- **Blacklist в Redis**: Использованные токены автоматически добавляются в черный список
-- **Атомарная проверка**: Race condition защищена благодаря Redis Lua скриптам
-
-### 3. Временные ограничения
-- **Expiration time**: Настраиваемое время жизни токена
-- **Автоматическое истечение**: Токены автоматически становятся недействительными после истечения времени
-- **Защита от replay attacks**: Старые токены не могут быть использованы повторно
 
-### 4. Контроль доступа
-- **Whitelist клиентов**: Только авторизованные сервисы могут подключаться
+### 2. Контроль доступа
+- **Whitelist клиентов**: Только авторизованные сервисы могут подключаться, при включенном модуле `:client_auth_protection`
 - **Идентификация по имени**: Каждый клиент должен быть явно указан в `allowed_services`
-- **Валидация формата токена**: Строгая проверка структуры токена
 
-### 5. Rate Limiting (опционально)
-- **Защита от DDoS**: Ограничение количества запросов от каждого клиента
-- **Sliding window**: Справедливое распределение запросов во времени
+### 3. Защита от перехвата токенов (replay-attack)
+- **Защита от replay-attack**: использованные токены добавляются в черный список и имеют время жизни, при включенном модуле `:replay_attack_protection`
+- **Staleness**: Токены автоматически становятся недействительными после истечения времени
+- **Blacklisting использованных токенов**: Redis как хранилище черного списка
+- **Настраиваемое время жизни токенов в черном списке**: по умолчанию 10 минут
+- **Настраиваемое ttl токена**: Должно быть в окно ответа между серверами, по умолчанию 10сек
+
+### 4. Защита от DoS
+- **Защита от DDoS**: Ограничение количества запросов от каждого клиента, при включенном модуле `:dos_attack_protection`
+- **Sliding window**: Распределение запросов во времени
 - **Fail-open стратегия**: Если Redis недоступен, запросы пропускаются (для надёжности)
-- **Per-client лимиты**: Индивидуальные счётчики для каждого клиента
 
-### 6. Защита от инъекций
-- **Валидация входных данных**: Проверка типа, длины и формата токенов
-- **Максимальная длина токена**: Ограничение 2048 символов
-- **Проверка на пустые значения**: Отклонение пустых или некорректных токенов
+-
+### 5. Защита от SSL stripping MITM attack
+- **Принудительное HTTPS на сервере**: Все запросы должны быть совершены по HTTPS, чтобы защитить токены от перехвата
+- **Включается на RobustClientSoket, ключём `ssl_verify: true`**
 
 ## 📦 Установка
 
@@ -53,13 +110,21 @@ RobustServerSocket реализует многоуровневую систем
 gem 'robust_server_socket'
 ```
 
+и на клиенте:
+```ruby
+gem 'robust_client_socket'
+```
 ## ⚙️ Конфигурация
 
 Создайте файл `config/initializers/robust_server_socket.rb`:
 
 ```ruby
 RobustServerSocket.configure do |c|
-  # ОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ
+  c.using_modules = %i[
+    :client_auth_protection
+    :replay_attack_protection
+    :dos_attack_protection
+  ]
   
   # Приватный ключ сервиса (RSA-2048 или выше)
   c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
@@ -67,15 +132,14 @@ RobustServerSocket.configure do |c|
   
   # Список разрешённых сервисов (whitelist)
   # Должен совпадать с именами RobustClientSocket клиента
+  # Для client_auth_protection
   c.allowed_services = %w[core payments notifications]
   
-  # Redis для работы replay-attack protection и throttling
+  # Redis для работы replay_attack_protection и ddos_attack_protection
   c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
   c.redis_pass = ENV['REDIS_PASSWORD']
 
-  # НЕОБЯЗАТЕЛЬНЫЕ ПАРАМЕТРЫ
-  # Включить ограничение частоты запросов (по умолчанию: false)
-  c.rate_limit_enabled = true
+  # ddos_attack_protection
   # Максимальное количество запросов в окне времени (по умолчанию: 100)
   c.rate_limit_max_requests = 100
   # Размер временного окна в секундах (по умолчанию: 60)
@@ -85,19 +149,21 @@ end
 # Загрузка конфигурации с валидацией
 RobustServerSocket.load!
 ```
+`using_modules` - это используемые модули, добавление или удаление которых изменит поведение гема.
 
 ### Опции конфигурации сервиса
 
-| Параметр | Тип | Обязательный | Default | Описание |
-|----------|-----|--------------|---------|----------|
-| `private_key` | String | ✅ | - | Приватный RSA ключ сервиса (RSA-2048 или выше) |
-| `token_expiration_time` | Integer | ✅ | - | Время жизни токена в секундах |
-| `allowed_services` | Array | ✅ | - | Список разрешённых сервисов (whitelist) |
-| `redis_url` | String | ✅ | - | URL для подключения к Redis |
-| `redis_pass` | String | ❌ | nil | Пароль для Redis (если требуется) |
-| `rate_limit_enabled` | Boolean | ❌ | false | Включить ограничение частоты запросов |
-| `rate_limit_max_requests` | Integer | ❌ | 100 | Максимальное количество запросов в окне времени |
-| `rate_limit_window_seconds` | Integer | ❌ | 60 | Размер временного окна в секундах |
+| Параметр                    | Тип | Обязательный | Default                                                                      | Описание                                        |
+|-----------------------------|-----|-------------|------------------------------------------------------------------------------|-------------------------------------------------|
+| `private_key`               | String | ✅ | -                                                                            | Приватный RSA ключ сервиса (RSA-2048 или выше)  |
+| `token_expiration_time`     | Integer | ✅ | 10                                                                           | Время жизни токена в секундах                   |
+| `store_used_token_time`     | Integer | ✅ | 600                                                                          | Время жизни токена в блеклисте в секундах       |
+| `allowed_services`          | Array | ❌ | -                                                                            | Список разрешённых сервисов (whitelist)         |
+| `redis_url`                 | String | ✅ | -                                                                            | URL для подключения к Redis                     |
+| `using_modules`             | Array | ❌ | [:client_auth_protection, :replay_attack_protection, :dos_attack_protection] | Используемые модули                             |
+| `redis_pass`                | String | ❌ | nil                                                                          | Пароль для Redis (если требуется)               |
+| `rate_limit_max_requests`   | Integer | ❌ | 100                                                                          | Максимальное количество запросов в окне времени |
+| `rate_limit_window_seconds` | Integer | ❌ | 60                                                                           | Размер временного окна в секундах               |
 
 ## 🚀 Использование
 
@@ -167,61 +233,6 @@ rescue => e
 end
 ```
 
-### Rate Limiting вручную
-
-```ruby
-# Проверка текущего количества попыток
-attempts = RobustServerSocket::RateLimiter.current_attempts('core')
-puts "Core service made #{attempts} requests"
-
-# Сброс счётчика для конкретного клиента
-RobustServerSocket::RateLimiter.reset!('core')
-
-# Проверка с исключением при превышении
-begin
-  RobustServerSocket::RateLimiter.check!('core')
-rescue RobustServerSocket::RateLimiter::RateLimitExceeded => e
-  puts e.message # "Rate limit exceeded for core: 101/100 requests per 60s"
-end
-
-# Проверка без исключения (возвращает false при превышении)
-if RobustServerSocket::RateLimiter.check('core')
-  # Лимит не превышен
-else
-  # Лимит превышен
-end
-```
-
-## 🚦 Rate Limiting (Ограничение частоты запросов)
-
-### Принцип работы
-
-Rate Limiter защищает ваш сервис от перегрузки, ограничивая количество запросов от каждого клиента в определённом временном окне.
-
-**Характеристики:**
-- **Per-client counters**: Отдельный счётчик для каждого сервиса
-- **Sliding window**: Окно сбрасывается автоматически после истечения времени
-- **Атомарность**: Инкремент и проверка выполняются атомарно (Redis LUA script)
-- **Fail-open**: При недоступности Redis запросы пропускаются (не блокируются)
-
-### Мониторинг
-
-```ruby
-# Проверка текущего состояния
-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
-
-# В метриках (Prometheus, StatsD и т.д.)
-clients.each do |client|
-  attempts = RobustServerSocket::RateLimiter.current_attempts(client)
-  Metrics.gauge("rate_limiter.attempts.#{client}", attempts)
-end
-```
-
 ## ❌ Обработка ошибок
 
 ### Типы исключений
@@ -277,77 +288,6 @@ def rate_limit_response(exception)
 end
 ```
 
-## 💡 Рекомендации по использованию
-
-### 1. Управление ключами
-
-**✅ DO:**
-```ruby
-# Храните ключи в переменных окружения
-c.private_key = ENV['ROBUST_SERVER_PRIVATE_KEY']
-
-# Используйте secrets management (AWS Secrets Manager, Vault, и т.д.)
-c.private_key = Rails.application.credentials.dig(:robust_server, :private_key)
-
-# Генерируйте ключи правильно
-# openssl genrsa -out private_key.pem 2048
-# openssl rsa -in private_key.pem -pubout -out public_key.pem
-```
-
-**❌ DON'T:**
-```ruby
-# НЕ коммитьте ключи в git
-c.private_key = "-----BEGIN PRIVATE KEY-----\nMII..."
-
-# НЕ используйте слабые ключи
-# Минимум RSA-2048, рекомендуется RSA-4096 для высокой безопасности
-```
-
-### 2. Конфигурация Redis
-
-**✅ DO:**
-```ruby
-# Используйте отдельный namespace для каждого окружения
-c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
-
-# Настройте connection pool в production
-# В config/initializers/redis.rb
-Redis.current = ConnectionPool.new(size: 5, timeout: 5) do
-  Redis.new(url: ENV['REDIS_URL'], password: ENV['REDIS_PASSWORD'])
-end
-
-# Мониторьте состояние Redis
-# Используйте Redis Sentinel или Cluster для высокой доступности
-```
-
-**❌ DON'T:**
-```ruby
-# НЕ используйте одну БД Redis для всех окружений, используйте отдельную bd redis
-# НЕ игнорируйте ошибки Redis (rate limiter уже fail-open, но логируйте их)
-```
-
-### 5. Whitelist сервисов
-
-```ruby
-# Явно указывайте только необходимые сервисы
-c.allowed_services = %w[core payments] # ✅
-
-# НЕ используйте wildcards или регулярные выражения
-c.allowed_services = %w[*] # ❌ ОПАСНО!
-
-# Синхронизируйте с keychain клиента
-# Server (robust_server_socket):
-c.allowed_services = %w[core]
-
-# Client (robust_client_socket):
-c.keychain = {
-  core: { # ← Должно совпадать
-    base_uri: 'https://core.example.com',
-    public_key: '-----BEGIN PUBLIC KEY-----...'
-  }
-}
-```
-
 ## 🤝 Интеграция с RobustClientSocket
 
 Для полноценной работы необходимо настроить клиентскую часть:
@@ -373,7 +313,6 @@ end
 
 ## 📚 Дополнительные ресурсы
 
-- [BENCHMARK_ANALYSIS.md](BENCHMARK_ANALYSIS.md)
 - [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)
@@ -384,4 +323,4 @@ end
 
 ## 🐛 Баги и предложения
 
-Сообщайте о проблемах через issue tracker вашего репозитория.
+Сообщайте о багах через ишью, или напрямую тг @cruel_mango или email tee0zed@gmail.com

data/lib/robust_server_socket/cacher.rb

@@ -0,0 +1,132 @@
+module RobustServerSocket
+  module Cacher
+    class RedisConnectionError < StandardError; end
+
+    class << self
+      # Atomically validate token: check expiration and usage, then mark as used
+      # Returns: 'ok', 'stale', or 'used'
+      def atomic_validate_and_log(key, ttl, timestamp, expiration_time)
+        current_time = Time.now.utc.to_i
+
+        redis.with do |conn|
+          conn.eval(
+            lua_atomic_validate_and_log,
+            keys: [key],
+            argv: [ttl, timestamp, expiration_time, current_time]
+          )
+        end
+      rescue ::Redis::BaseConnectionError => e
+        handle_redis_error(e, 'atomic_validate_and_log')
+        raise RedisConnectionError, "Failed to validate token: #{e.message}"
+      end
+
+      def incr(key)
+        redis.with do |conn|
+          conn.pipelined do |pipeline|
+            pipeline.incrby(key, 1)
+            pipeline.expire(key, ttl_seconds)
+          end
+        end
+      rescue ::Redis::BaseConnectionError => e
+        handle_redis_error(e, 'incr')
+        raise RedisConnectionError, "Failed to increment key: #{e.message}"
+      end
+
+      def get(key)
+        redis.with do |conn|
+          conn.get(key)
+        end
+      rescue ::Redis::BaseConnectionError => e
+        handle_redis_error(e, 'get')
+        nil
+      end
+
+      def health_check
+        redis.with do |conn|
+          conn.ping == 'PONG'
+        end
+      rescue ::Redis::BaseConnectionError
+        false
+      end
+
+      def with_redis(&block)
+        redis.with(&block)
+      rescue ::Redis::BaseConnectionError => e
+        handle_redis_error(e, 'with_redis')
+        raise ::RedisConnectionError, "Redis operation failed: #{e.message}"
+      end
+
+      # Clear cached Redis connection pool (useful for hot reloading in development)
+      def clear_redis_pool_cache!
+        @pool = nil
+      end
+
+      private
+
+      def lua_atomic_validate_and_log
+        <<~LUA
+          local key = KEYS[1]
+          local ttl = tonumber(ARGV[1])
+          local timestamp = tonumber(ARGV[2])
+          local expiration_time = tonumber(ARGV[3])
+          local current_time = tonumber(ARGV[4])
+                  
+          -- Check if token is expired
+          if expiration_time <= (current_time - timestamp) then
+            return 'stale'
+          end
+                  
+          -- Check if token was already used
+          local current = redis.call('GET', key)
+          if current and tonumber(current) > 0 then
+            return 'used'
+          end
+                  
+          -- Mark token as used
+          redis.call('INCRBY', key, 1)
+          redis.call('EXPIRE', key, ttl)
+                  
+          return 'ok'
+        LUA
+      end
+
+      def ttl_seconds
+        # `+ 10` secs, for token storing and expiration check validity
+        ::RobustServerSocket.configuration.token_expiration_time + 10
+      end
+
+      # Cache Redis connection pool at module level for the lifetime of the Rails process
+      # This avoids recreating the connection pool on every Redis operation
+      def redis
+        @pool ||= ::ConnectionPool::Wrapper.new(**pool_config) do
+          ::Redis.new(redis_config)
+        end
+      end
+
+      def pool_config
+        {
+          size: ENV.fetch('REDIS_POOL_SIZE', 25).to_i,
+          timeout: ENV.fetch('REDIS_POOL_TIMEOUT', 1).to_f
+        }
+      end
+
+      def redis_config
+        config = {
+          url: ::RobustServerSocket.configuration.redis_url,
+          reconnect_attempts: 3,
+          timeout: 1.0,
+          connect_timeout: 2.0
+        }
+
+        password = ::RobustServerSocket.configuration.redis_pass
+        config[:password] = password if password && !password.empty?
+
+        config
+      end
+
+      def handle_redis_error(error, operation)
+        warn "Redis operation '#{operation}' failed: #{error.class} - #{error.message}"
+      end
+    end
+  end
+end

data/lib/robust_server_socket/client_token.rb

@@ -1,15 +1,8 @@
-require_relative 'secure_token/cacher'
-require_relative 'secure_token/decrypt'
-require_relative 'rate_limiter'
-
 module RobustServerSocket
   class ClientToken
     TOKEN_REGEXP = /\A(.+)_(\d{10,})\z/.freeze
 
     InvalidToken = Class.new(StandardError)
-    UnauthorizedClient = Class.new(StandardError)
-    UsedToken = Class.new(StandardError)
-    StaleToken = Class.new(StandardError)
 
     def self.validate!(secure_token)
       new(secure_token).tap do |instance|
@@ -23,34 +16,24 @@ module RobustServerSocket
     end
 
     def validate!
-      raise InvalidToken unless decrypted_token
-      raise UnauthorizedClient unless client
-
-      RateLimiter.check!(client)
-
-      result = atomic_validate_and_log_token
-
-      case result
-      when 'stale'
-        raise StaleToken
-      when 'used'
-        raise UsedToken
-      when 'ok'
-        true
-      else
-        raise InvalidToken, "Unexpected validation result: #{result}"
-      end
+      raise InvalidToken unless validate_decrypted_token
+      modules_checks!
     end
 
     def valid?
-      !!(decrypted_token &&
-        client &&
-        RateLimiter.check(client) &&
-        atomic_validate_and_log_token == 'ok')
+      validate_decrypted_token && modules_checks
     rescue StandardError
       false
     end
 
+    def modules_checks
+      true
+    end
+
+    def modules_checks!
+      true
+    end
+
     def client
       @client ||= begin
         target = client_name.strip
@@ -58,23 +41,14 @@ module RobustServerSocket
       end
     end
 
-    def token_not_expired?
-      token_expiration_time > Time.now.utc.to_i - timestamp
-    end
-
-    def atomic_validate_and_log_token
-      SecureToken::Cacher.atomic_validate_and_log(
-        decrypted_token,
-        token_expiration_time + 300,
-        timestamp,
-        token_expiration_time
-      )
-    end
-
     def decrypted_token
       @decrypted_token ||= SecureToken::Decrypt.call(@secure_token)
     end
 
+    def validate_decrypted_token
+      !!decrypted_token
+    end
+
     private
 
     def allowed_clients
@@ -101,6 +75,7 @@ module RobustServerSocket
       RobustServerSocket.configuration.token_expiration_time
     end
 
+
     # Do we need it? It would be useful only if public_key compromised
     # def secure_compare(a, b)
     #   return false unless a.bytesize == b.bytesize

data/lib/robust_server_socket/configuration.rb

@@ -4,6 +4,14 @@ module RobustServerSocket
 
     attr_reader :configuration, :configured
 
+    def _push_modules_check_code(code)
+      configuration._modules_check_rows.push(code)
+    end
+
+    def _push_bang_modules_check_code(code)
+      configuration._bang_modules_check_rows.push(code)
+    end
+
     def configure
       @configuration ||= ConfigStore.new
       yield(configuration)
@@ -43,13 +51,24 @@ module RobustServerSocket
   end
 
   class ConfigStore
-    attr_accessor :allowed_services, :private_key, :token_expiration_time, :redis_url, :redis_pass,
-                  :rate_limit_enabled, :rate_limit_max_requests, :rate_limit_window_seconds
+    attr_accessor :allowed_services, :private_key, :token_expiration_time, :store_used_token_time, :redis_url, :redis_pass,
+                  :rate_limit_max_requests, :rate_limit_window_seconds, :using_modules
+
+    attr_reader :_modules_check_rows, :_bang_modules_check_rows
 
     def initialize
-      @rate_limit_enabled = false
       @rate_limit_max_requests = 100
       @rate_limit_window_seconds = 60
+      @store_used_token_time = 600
+      @token_expiration_time = 10
+      @using_modules = %i[
+        client_auth_protection
+        dos_attack_protection
+        replay_attack_protection
+      ]
+
+      @_modules_check_rows = []
+      @_bang_modules_check_rows = []
     end
   end
 end

data/lib/robust_server_socket/modules/client_auth_protection.rb

@@ -0,0 +1,20 @@
+module RobustServerSocket
+  module Modules
+    module ClientAuthProtection
+      UnauthorizedClient = Class.new(StandardError)
+
+      def self.included(_base)
+        RobustServerSocket._push_modules_check_code('validate_client')
+        RobustServerSocket._push_bang_modules_check_code("validate_client!\n")
+      end
+
+      def validate_client
+        !!client
+      end
+
+      def validate_client!
+        raise UnauthorizedClient unless validate_client
+      end
+    end
+  end
+end

data/lib/robust_server_socket/modules/dos_attack_protection.rb

@@ -0,0 +1,21 @@
+require_relative '../cacher'
+require_relative '../rate_limiter'
+
+module RobustServerSocket
+  module Modules
+    module DosAttackProtection
+      def self.included(_base)
+        RobustServerSocket._push_modules_check_code('validate_rate_limit')
+        RobustServerSocket._push_bang_modules_check_code("validate_rate_limit!\n")
+      end
+
+      def validate_rate_limit
+        !!RateLimiter.check(client)
+      end
+
+      def validate_rate_limit!
+        RateLimiter.check!(client)
+      end
+    end
+  end
+end

data/lib/robust_server_socket/modules/replay_attack_protection.rb

@@ -0,0 +1,50 @@
+require_relative '../cacher'
+
+module RobustServerSocket
+  module Modules
+    module ReplayAttackProtection
+      UsedToken = Class.new(StandardError)
+      StaleToken = Class.new(StandardError)
+
+      def self.included(_base)
+        RobustServerSocket._push_modules_check_code('atomic_validate_and_log_token')
+        RobustServerSocket._push_bang_modules_check_code("atomic_validate_and_log_token!\n")
+      end
+
+      def atomic_validate_and_log_token!
+        result = Cacher.atomic_validate_and_log(
+          decrypted_token,
+          store_used_token_time,
+          timestamp,
+          token_expiration_time
+        )
+
+        case result
+          when 'ok'
+            true
+          when 'stale'
+            raise StaleToken
+          when 'used'
+            raise UsedToken
+          else
+            raise StandardError, "Unexpected result: #{result}"
+          end
+      end
+
+      def atomic_validate_and_log_token
+        Cacher.atomic_validate_and_log(
+          decrypted_token,
+          store_used_token_time, # window for storing used token
+          timestamp,
+          token_expiration_time
+        ) == 'ok'
+      end
+
+      private
+
+      def store_used_token_time
+        RobustServerSocket.configuration.store_used_token_time
+      end
+    end
+  end
+end

data/lib/robust_server_socket/rate_limiter.rb

@@ -1,5 +1,3 @@
-require_relative 'secure_token/cacher'
-
 module RobustServerSocket
   class RateLimiter
     RateLimitExceeded = Class.new(StandardError)
@@ -8,6 +6,7 @@ module RobustServerSocket
       def check!(client_name)
         unless (attempts = check(client_name))
           actual_attempts = current_attempts(client_name)
+
           raise RateLimitExceeded, "Rate limit exceeded for #{client_name}: #{actual_attempts}/#{max_requests} requests per #{window_seconds}s"
         end
 
@@ -15,8 +14,6 @@ module RobustServerSocket
       end
 
       def check(client_name)
-        return 0 unless rate_limit_enabled?
-
         key = rate_limit_key(client_name)
         attempts = increment_attempts(key)
 
@@ -26,18 +23,16 @@ module RobustServerSocket
       end
 
       def current_attempts(client_name)
-        return 0 unless rate_limit_enabled?
-
         key = rate_limit_key(client_name)
-        SecureToken::Cacher.get(key).to_i
+        Cacher.get(key).to_i
       end
 
       def reset!(client_name)
         key = rate_limit_key(client_name)
-        SecureToken::Cacher.with_redis do |conn|
+        Cacher.with_redis do |conn|
           conn.del(key)
         end
-      rescue SecureToken::Cacher::RedisConnectionError => e
+      rescue Cacher::RedisConnectionError => e
         handle_redis_error(e, 'reset')
         nil
       end
@@ -45,13 +40,13 @@ module RobustServerSocket
       private
 
       def increment_attempts(key)
-        SecureToken::Cacher.with_redis do |conn|
+        Cacher.with_redis do |conn|
           attempts = conn.incr(key)
           # Set expiration only on first attempt to ensure atomic window
           conn.expire(key, window_seconds) if attempts == 1
           attempts
         end
-      rescue SecureToken::Cacher::RedisConnectionError => e
+      rescue Cacher::RedisConnectionError => e
         handle_redis_error(e, 'increment_attempts')
         0 # Fail open: allow request if Redis is down
       end
@@ -60,10 +55,6 @@ module RobustServerSocket
         "rate_limit:#{client_name}"
       end
 
-      def rate_limit_enabled?
-        RobustServerSocket.configuration.rate_limit_enabled
-      end
-
       def max_requests
         RobustServerSocket.configuration.rate_limit_max_requests
       end

data/lib/robust_server_socket/secure_token/decrypt.rb

@@ -1,5 +1,3 @@
-require 'openssl'
-
 module RobustServerSocket
   module SecureToken
     BASE64_REGEXP = /\A[A-Za-z0-9+\/]*={0,2}\z/.freeze

data/lib/robust_server_socket.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
+require 'base64'
+require 'openssl'
+require 'redis'
+require 'connection_pool'
+
 require_relative 'robust_server_socket/configuration'
+require_relative 'robust_server_socket/secure_token/decrypt'
+require_relative 'robust_server_socket/client_token'
 
 module RobustServerSocket
   extend RobustServerSocket::Configuration
@@ -10,12 +17,21 @@ module RobustServerSocket
   def load!
     raise 'You must correctly configure RobustServerSocket first!' unless configured?
 
-    require 'openssl'
-    require 'base64'
-    require 'redis'
-    require 'connection_pool'
+    configuration.using_modules.each do |mod|
+      raise ArgumentError, 'Module must be a Symbol!' unless mod.is_a?(Symbol)
+
+      require_relative "robust_server_socket/modules/#{mod}"
+      ClientToken.include eval(mod.to_s.split('_').map(&:capitalize).unshift('Modules::').join)
+    end
+
+    ClientToken.class_eval(<<~METHOD)
+      def modules_checks
+        #{(RobustServerSocket.configuration._modules_check_rows.empty? ? ['true'] : RobustServerSocket.configuration._modules_check_rows.map(&:strip)).join(' && ')}
+      end
 
-    require_relative 'robust_server_socket/rate_limiter'
-    require_relative 'robust_server_socket/client_token'
+      def modules_checks!
+        #{(RobustServerSocket.configuration._bang_modules_check_rows.empty? ? ['true'] : RobustServerSocket.configuration._bang_modules_check_rows).join}
+      end
+    METHOD
   end
 end

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobustServerSocket
-  VERSION = '0.3.3'
+  VERSION = '0.4.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robust_server_socket
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.2
 platform: ruby
 authors:
 - tee_zed
@@ -79,10 +79,13 @@ files:
 - README.md
 - Rakefile
 - lib/robust_server_socket.rb
+- lib/robust_server_socket/cacher.rb
 - lib/robust_server_socket/client_token.rb
 - lib/robust_server_socket/configuration.rb
+- lib/robust_server_socket/modules/client_auth_protection.rb
+- lib/robust_server_socket/modules/dos_attack_protection.rb
+- lib/robust_server_socket/modules/replay_attack_protection.rb
 - lib/robust_server_socket/rate_limiter.rb
-- lib/robust_server_socket/secure_token/cacher.rb
 - lib/robust_server_socket/secure_token/decrypt.rb
 - lib/version.rb
 - robust_server_socket.gemspec
@@ -103,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Robust Server Socket gem for RobustPro
 test_files: []

data/lib/robust_server_socket/secure_token/cacher.rb

@@ -1,138 +0,0 @@
-require 'redis'
-require 'connection_pool'
-
-module RobustServerSocket
-  module SecureToken
-    module Cacher
-      class RedisConnectionError < StandardError; end
-
-      class << self
-        # Atomically validate token: check expiration and usage, then mark as used
-        # Returns: 'ok', 'stale', or 'used'
-        def atomic_validate_and_log(key, ttl, timestamp, expiration_time)
-          current_time = Time.now.utc.to_i
-
-          redis.with do |conn|
-            conn.eval(
-              lua_atomic_validate,
-              keys: [key],
-              argv: [ttl, timestamp, expiration_time, current_time]
-            )
-          end
-        rescue ::Redis::BaseConnectionError => e
-          handle_redis_error(e, 'atomic_validate_and_log')
-          raise RedisConnectionError, "Failed to validate token: #{e.message}"
-        end
-
-        def incr(key, ttl = nil)
-          ttl_value = ttl || ttl_seconds
-
-          redis.with do |conn|
-            conn.pipelined do |pipeline|
-              pipeline.incrby(key, 1)
-              pipeline.expire(key, ttl_value)
-            end
-          end
-        rescue ::Redis::BaseConnectionError => e
-          handle_redis_error(e, 'incr')
-          raise RedisConnectionError, "Failed to increment key: #{e.message}"
-        end
-
-        def get(key)
-          redis.with do |conn|
-            conn.get(key)
-          end
-        rescue ::Redis::BaseConnectionError => e
-          handle_redis_error(e, 'get')
-          nil # Fallback for reads
-        end
-
-        def health_check
-          redis.with do |conn|
-            conn.ping == 'PONG'
-          end
-        rescue ::Redis::BaseConnectionError
-          false
-        end
-
-        def with_redis(&block)
-          redis.with(&block)
-        rescue ::Redis::BaseConnectionError => e
-          handle_redis_error(e, 'with_redis')
-          raise ::RedisConnectionError, "Redis operation failed: #{e.message}"
-        end
-
-        # Clear cached Redis connection pool (useful for hot reloading in development)
-        def clear_redis_pool_cache!
-          @pool = nil
-        end
-
-        private
-
-        def lua_atomic_validate
-          <<~LUA
-            local key = KEYS[1]
-            local ttl = tonumber(ARGV[1])
-            local timestamp = tonumber(ARGV[2])
-            local expiration_time = tonumber(ARGV[3])
-            local current_time = tonumber(ARGV[4])
-                    
-            -- Check if token is expired
-            if expiration_time <= (current_time - timestamp) then
-              return 'stale'
-            end
-                    
-            -- Check if token was already used
-            local current = redis.call('GET', key)
-            if current and tonumber(current) > 0 then
-              return 'used'
-            end
-                    
-            -- Mark token as used
-            redis.call('INCRBY', key, 1)
-            redis.call('EXPIRE', key, ttl)
-                    
-            return 'ok'
-          LUA
-        end
-
-        def ttl_seconds
-          ::RobustServerSocket.configuration.token_expiration_time + 60
-        end
-
-        # Cache Redis connection pool at module level for the lifetime of the Rails process
-        # This avoids recreating the connection pool on every Redis operation
-        def redis
-          @pool ||= ::ConnectionPool::Wrapper.new(**pool_config) do
-            ::Redis.new(redis_config)
-          end
-        end
-
-        def pool_config
-          {
-            size: ENV.fetch('REDIS_POOL_SIZE', 25).to_i,
-            timeout: ENV.fetch('REDIS_POOL_TIMEOUT', 1).to_f
-          }
-        end
-
-        def redis_config
-          config = {
-            url: ::RobustServerSocket.configuration.redis_url,
-            reconnect_attempts: 3,
-            timeout: 1.0,
-            connect_timeout: 2.0
-          }
-
-          password = ::RobustServerSocket.configuration.redis_pass
-          config[:password] = password if password && !password.empty?
-
-          config
-        end
-
-        def handle_redis_error(error, operation)
-          warn "Redis operation '#{operation}' failed: #{error.class} - #{error.message}"
-        end
-      end
-    end
-  end
-end