robust_server_socket 0.3.2 → 0.4.2

data/README.md

@@ -0,0 +1,326 @@
+# RobustServerSocket
+
+Gem для межсервисной аутентификации, используется в паре с RobustClientSocket
+
+### ⚠️ 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
+
+## 📋 Содержание
+
+- [Функции безопасности](#функции-безопасности)
+- [Установка](#установка)
+- [Конфигурация](#конфигурация)
+- [Использование](#использование)
+- [Обработка ошибок](#обработка-ошибок)
+
+## 🔒 Функции безопасности
+
+RobustServerSocket реализует многоуровневую систему защиты для межсервисных коммуникаций:
+
+### 1. Криптографическая защита
+- **RSA-2048 шифрование**: Используется пара ключей RSA с минимальной длиной 2048 бит
+- **Валидация ключей**: Автоматическая проверка размера ключа при конфигурации
+
+### 2. Контроль доступа
+- **Whitelist клиентов**: Только авторизованные сервисы могут подключаться, при включенном модуле `:client_auth_protection`
+- **Идентификация по имени**: Каждый клиент должен быть явно указан в `allowed_services`
+
+### 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 недоступен, запросы пропускаются (для надёжности)
+
+-
+### 5. Защита от SSL stripping MITM attack
+- **Принудительное HTTPS на сервере**: Все запросы должны быть совершены по HTTPS, чтобы защитить токены от перехвата
+- **Включается на RobustClientSoket, ключём `ssl_verify: true`**
+
+## 📦 Установка
+
+```ruby
+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']
+  c.token_expiration_time = 3
+  
+  # Список разрешённых сервисов (whitelist)
+  # Должен совпадать с именами RobustClientSocket клиента
+  # Для client_auth_protection
+  c.allowed_services = %w[core payments notifications]
+  
+  # Redis для работы replay_attack_protection и ddos_attack_protection
+  c.redis_url = ENV.fetch('REDIS_URL', 'redis://localhost:6379/0')
+  c.redis_pass = ENV['REDIS_PASSWORD']
+
+  # ddos_attack_protection
+  # Максимальное количество запросов в окне времени (по умолчанию: 100)
+  c.rate_limit_max_requests = 100
+  # Размер временного окна в секундах (по умолчанию: 60)
+  c.rate_limit_window_seconds = 60
+end
+
+# Загрузка конфигурации с валидацией
+RobustServerSocket.load!
+```
+`using_modules` - это используемые модули, добавление или удаление которых изменит поведение гема.
+
+### Опции конфигурации сервиса
+
+| Параметр                    | Тип | Обязательный | 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                                                                           | Размер временного окна в секундах               |
+
+## 🚀 Использование
+
+### Базовая авторизация
+
+```ruby
+# В контроллере или middleware
+class ApiController < ApplicationController
+  before_action :authenticate_service!
+  
+  private
+  
+  def authenticate_service!
+    # Хедер, прописанный в RobustClientSocket (SECURE-TOKEN default)
+    token = request.headers['SECURE-TOKEN']&.sub(/^Bearer /, '')
+    
+    @current_service = RobustServerSocket::ClientToken.validate!(token) # bang method (рейзит ошибки)
+  rescue RobustServerSocket::ClientToken::InvalidToken
+    render json: { error: 'Invalid token' }, status: :unauthorized
+  rescue RobustServerSocket::ClientToken::UnauthorizedClient
+    render json: { error: 'Unauthorized service' }, status: :forbidden
+  rescue RobustServerSocket::ClientToken::UsedToken
+    render json: { error: 'Token already used' }, status: :unauthorized
+  rescue RobustServerSocket::ClientToken::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.valid?(token) # не рейзит
+    
+    if @current_service
+      # Токен валиден
+    else
+      # Токен невалиден
+      render json: { error: 'Unauthorized' }, status: :unauthorized
+    end
+  end
+end
+```
+
+### Расширенное использование
+
+```ruby
+# Создание объекта токена
+token_string = request.headers['Authorization']&.sub(/^Bearer /, '')
+client_token = RobustServerSocket::ClientToken.new(token_string)
+
+# Проверка валидности (возвращает true/false)
+if client_token.valid?
+  # Получение имени клиента
+  client_name = client_token.client
+  puts "Authorized client: #{client_name}"
+else
+  # Токен невалиден
+  render json: { error: 'Unauthorized' }, status: :unauthorized
+end
+
+# Быстрая валидация с исключениями
+begin
+  service_token = RobustServerSocket::ClientToken.validate!(token_string)
+  client_name = service_token.client
+rescue => e
+  # Обработка специфичных ошибок
+end
+```
+
+## ❌ Обработка ошибок
+
+### Типы исключений
+
+| Исключение | Причина | HTTP статус | Действие |
+|-----------|---------|-------------|----------|
+| `InvalidToken` | Токен не может быть расшифрован или имеет неверный формат | 401 | Проверьте корректность токена и ключей |
+| `UnauthorizedClient` | Клиент не в whitelist | 403 | Добавьте клиента в `allowed_services` |
+| `UsedToken` | Токен уже был использован | 401 | Клиент должен запросить новый токен |
+| `StaleToken` | Токен истёк | 401 | Клиент должен запросить новый токен |
+| `RateLimitExceeded` | Превышен лимит запросов | 429 | Клиент должен подождать или ретраить позже |
+
+### Централизованная обработка
+
+```ruby
+# В ApplicationController
+rescue_from RobustServerSocket::ClientToken::InvalidToken,
+            RobustServerSocket::ClientToken::UsedToken,
+            RobustServerSocket::ClientToken::StaleToken,
+            with: :unauthorized_response
+
+rescue_from RobustServerSocket::ClientToken::UnauthorizedClient,
+            with: :forbidden_response
+
+rescue_from RobustServerSocket::RateLimiter::RateLimitExceeded,
+            with: :rate_limit_response
+
+private
+
+def unauthorized_response(exception)
+  render json: {
+    error: 'Authentication failed',
+    message: exception.message,
+    type: exception.class.name
+  }, status: :unauthorized
+end
+
+def forbidden_response(exception)
+  render json: {
+    error: 'Access denied',
+    message: exception.message,
+    type: exception.class.name
+  }, 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
+```
+
+## 🤝 Интеграция с RobustClientSocket
+
+Для полноценной работы необходимо настроить клиентскую часть:
+
+```ruby
+# На клиенте (RobustClientSocket)
+RobustClientSocket.configure do |c|
+  c.service_name = 'core' # ← Должно быть в allowed_services сервера
+  c.keychain = {
+    payments: {
+      base_uri: 'https://payments.example.com',
+      public_key: '-----BEGIN PUBLIC KEY-----...' # Публичный ключ сервера payments
+    }
+  }
+end
+
+# На сервере (RobustServerSocket)
+RobustServerSocket.configure do |c|
+  c.allowed_services = %w[core] # ← Соответствует service_name клиента
+  c.private_key = '-----BEGIN PRIVATE KEY-----...' # Приватная пара к public_key
+end
+```
+
+## 📚 Дополнительные ресурсы
+
+- [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)
+
+## 📝 Лицензия
+
+См. файл [MIT-LICENSE](MIT-LICENSE)
+
+## 🐛 Баги и предложения
+
+Сообщайте о багах через ишью, или напрямую тг @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,35 +1,12 @@
-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|
-        raise InvalidToken unless instance.decrypted_token
-        raise UnauthorizedClient unless instance.client
-
-        RateLimiter.check!(instance.client)
-
-        result = instance.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
+        instance.validate!
       end
     end
 
@@ -38,15 +15,25 @@ module RobustServerSocket
       @client = nil
     end
 
+    def validate!
+      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
@@ -54,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
@@ -97,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