flow_chat 0.4.2 → 0.5.2

data/SECURITY.md

@@ -0,0 +1,365 @@
+# FlowChat Security Guide
+
+This guide covers the security features and best practices for FlowChat, including webhook signature validation and simulator authentication.
+
+## Overview
+
+FlowChat includes comprehensive security features to protect your WhatsApp and USSD applications:
+
+- **Webhook Signature Validation**: Verify that WhatsApp webhooks are authentic
+- **Simulator Authentication**: Secure access to the testing simulator
+- **Configuration Validation**: Prevent insecure configurations
+- **Environment-Specific Security**: Different security levels per environment
+
+## WhatsApp Webhook Security
+
+### Signature Validation
+
+FlowChat automatically validates WhatsApp webhook signatures using HMAC-SHA256 to ensure requests come from WhatsApp.
+
+#### Required Configuration
+
+For webhook signature validation, you need to configure your WhatsApp app secret:
+
+```ruby
+# Using Rails credentials
+rails credentials:edit
+```
+
+```yaml
+whatsapp:
+  app_secret: "your_whatsapp_app_secret"
+  # ... other credentials
+```
+
+Or using environment variables:
+
+```bash
+export WHATSAPP_APP_SECRET="your_whatsapp_app_secret"
+```
+
+#### Security Modes
+
+FlowChat supports two security modes for webhook validation:
+
+**1. Full Security (Recommended for Production)**
+
+```ruby
+config = FlowChat::Whatsapp::Configuration.new
+config.app_secret = "your_whatsapp_app_secret"  # Required
+config.skip_signature_validation = false        # Default: enforce validation
+```
+
+**2. Development Mode (Testing Only)**
+
+```ruby
+config = FlowChat::Whatsapp::Configuration.new
+config.app_secret = nil                         # Not required when disabled
+config.skip_signature_validation = true         # Explicitly disable validation
+```
+
+⚠️ **Security Warning**: Never disable signature validation in production environments.
+
+#### Configuration Error Handling
+
+When `app_secret` is missing and validation is not explicitly disabled, FlowChat raises a `ConfigurationError`:
+
+```ruby
+begin
+  processor.run WelcomeFlow, :main_page
+rescue FlowChat::Whatsapp::ConfigurationError => e
+  Rails.logger.error "Security configuration error: #{e.message}"
+  head :internal_server_error
+end
+```
+
+The error message provides clear guidance:
+
+```
+WhatsApp app_secret is required for webhook signature validation. 
+Either configure app_secret or set skip_signature_validation=true to explicitly disable validation.
+```
+
+### Environment-Specific Security
+
+Configure different security levels per environment:
+
+```ruby
+# config/initializers/flowchat.rb
+case Rails.env
+when 'development'
+  # Relaxed security for easier development
+  config.skip_signature_validation = true
+  
+when 'test'
+  # Skip validation for deterministic testing
+  config.skip_signature_validation = true
+  
+when 'staging', 'production'
+  # Full security for production-like environments
+  config.skip_signature_validation = false
+  
+  # Ensure app_secret is configured
+  if ENV['WHATSAPP_APP_SECRET'].blank?
+    raise "WHATSAPP_APP_SECRET required for #{Rails.env} environment"
+  end
+end
+```
+
+## Simulator Security
+
+### Authentication System
+
+The FlowChat simulator uses secure HMAC-SHA256 signed cookies for authentication. This prevents unauthorized access to your simulator endpoints.
+
+#### Required Configuration
+
+Configure a simulator secret in your initializer:
+
+```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.simulator_secret = "your_secure_secret_here"
+```
+
+#### Environment-Specific Secrets
+
+Use different secrets per environment:
+
+```ruby
+case Rails.env
+when 'development', 'test'
+  # Use Rails secret key with environment suffix
+  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_#{Rails.env}"
+  
+when 'staging', 'production'
+  # Use environment variable for production
+  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
+  
+  if FlowChat::Config.simulator_secret.blank?
+    Rails.logger.warn "FLOWCHAT_SIMULATOR_SECRET not configured. Simulator will be unavailable."
+  end
+end
+```
+
+#### Cookie Security
+
+Simulator cookies are automatically configured with security best practices:
+
+- **HMAC-SHA256 signed**: Prevents tampering
+- **24-hour expiration**: Limits exposure window
+- **Secure flag**: Only sent over HTTPS in production
+- **HttpOnly flag**: Prevents XSS access
+- **SameSite=Lax**: CSRF protection
+
+#### Enabling Simulator Mode
+
+Enable simulator mode only when needed:
+
+```ruby
+# Enable simulator only in development/staging
+enable_simulator = Rails.env.development? || Rails.env.staging?
+
+processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: enable_simulator) do |config|
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  config.use_session_store FlowChat::Session::CacheSessionStore
+end
+```
+
+### Simulator Request Flow
+
+1. **User visits simulator**: Browser requests `/simulator`
+2. **Cookie generation**: Server generates HMAC-signed cookie
+3. **Simulator requests**: Include valid cookie for authentication
+4. **Cookie validation**: Server validates HMAC signature and timestamp
+5. **Request processing**: Continues if authentication succeeds
+
+## Security Best Practices
+
+### Production Checklist
+
+✅ **WhatsApp Security**
+- Configure `app_secret` for webhook validation
+- Set `skip_signature_validation = false`
+- Use environment variables for secrets
+- Handle `ConfigurationError` exceptions
+
+✅ **Simulator Security**  
+- Configure `simulator_secret` using environment variables
+- Enable simulator only in development/staging
+- Use unique secrets per environment
+
+✅ **Environment Configuration**
+- Different security levels per environment
+- Fail fast on missing required configuration
+- Log security warnings appropriately
+
+✅ **Error Handling**
+- Catch and log `ConfigurationError` exceptions
+- Return appropriate HTTP status codes
+- Don't expose sensitive information in errors
+
+### Development Guidelines
+
+**DO:**
+- Use Rails `secret_key_base` + suffix for development secrets
+- Skip webhook validation in development for easier testing
+- Enable simulator mode for testing
+- Use test-specific credentials in test environment
+
+**DON'T:**
+- Hardcode secrets in source code
+- Disable security in production
+- Use production secrets in development
+- Commit secrets to version control
+
+### Example Secure Configuration
+
+```ruby
+# config/initializers/flowchat.rb
+case Rails.env
+when 'development'
+  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_dev"
+  FlowChat::Config.whatsapp.message_handling_mode = :simulator
+  
+when 'test'
+  FlowChat::Config.simulator_secret = "test_secret_#{Rails.application.secret_key_base}"
+  FlowChat::Config.whatsapp.message_handling_mode = :simulator
+  
+when 'staging'
+  FlowChat::Config.simulator_secret = ENV.fetch('FLOWCHAT_SIMULATOR_SECRET')
+  FlowChat::Config.whatsapp.message_handling_mode = :inline
+  
+when 'production'
+  FlowChat::Config.simulator_secret = ENV.fetch('FLOWCHAT_SIMULATOR_SECRET')
+  FlowChat::Config.whatsapp.message_handling_mode = :background
+  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+end
+```
+
+## Testing Security Features
+
+### Webhook Signature Validation Tests
+
+```ruby
+test "webhook accepts valid signature" do
+  payload = valid_webhook_payload.to_json
+  signature = OpenSSL::HMAC.hexdigest(
+    OpenSSL::Digest.new("sha256"),
+    "your_app_secret",
+    payload
+  )
+
+  post "/whatsapp/webhook",
+    params: payload,
+    headers: { 
+      "Content-Type" => "application/json",
+      "X-Hub-Signature-256" => "sha256=#{signature}" 
+    }
+
+  assert_response :success
+end
+
+test "webhook rejects invalid signature" do
+  post "/whatsapp/webhook", 
+    params: valid_webhook_payload,
+    headers: { "X-Hub-Signature-256" => "sha256=invalid_signature" }
+
+  assert_response :unauthorized
+end
+
+test "webhook rejects missing signature" do
+  post "/whatsapp/webhook", params: valid_webhook_payload
+  assert_response :unauthorized
+end
+```
+
+### Simulator Authentication Tests
+
+```ruby
+test "simulator requires valid authentication" do
+  post "/whatsapp/webhook", params: {
+    simulator_mode: true,
+    # ... webhook payload
+  }
+
+  assert_response :unauthorized  # No valid simulator cookie
+end
+
+test "simulator accepts valid authentication" do
+  # Generate valid simulator cookie
+  timestamp = Time.now.to_i
+  message = "simulator:#{timestamp}"
+  signature = OpenSSL::HMAC.hexdigest(
+    OpenSSL::Digest.new("sha256"), 
+    FlowChat::Config.simulator_secret, 
+    message
+  )
+  
+  post "/whatsapp/webhook", 
+    params: { simulator_mode: true, /* ... */ },
+    cookies: { flowchat_simulator: "#{timestamp}:#{signature}" }
+
+  assert_response :success
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**1. ConfigurationError: app_secret required**
+
+```
+WhatsApp app_secret is required for webhook signature validation.
+```
+
+**Solution**: Configure `WHATSAPP_APP_SECRET` environment variable or disable validation explicitly.
+
+**2. Invalid webhook signature**
+
+```
+Invalid webhook signature received
+```
+
+**Solution**: Verify your `app_secret` matches your WhatsApp app configuration.
+
+**3. Simulator authentication failed**
+
+```
+Invalid simulator cookie format
+```
+
+**Solution**: Ensure `FlowChat::Config.simulator_secret` is properly configured.
+
+**4. Missing simulator secret**
+
+```
+Simulator secret not configured
+```
+
+**Solution**: Set `FLOWCHAT_SIMULATOR_SECRET` environment variable or configure in initializer.
+
+### Debug Mode
+
+Enable debug logging for security events:
+
+```ruby
+# config/initializers/flowchat.rb
+if Rails.env.development?
+  FlowChat::Config.logger.level = Logger::DEBUG
+end
+```
+
+This will log security validation attempts and help troubleshoot configuration issues.
+
+## Security Updates
+
+This security system was introduced in FlowChat v2.0.0 and includes:
+
+- HMAC-SHA256 webhook signature validation
+- Secure simulator authentication with signed cookies  
+- Environment-specific security configuration
+- Comprehensive error handling and logging
+- Timing-attack resistant signature comparison
+
+For the latest security updates and recommendations, check the FlowChat changelog and security advisories. 

data/examples/initializer.rb

@@ -19,6 +19,22 @@ FlowChat::Config.cache = Rails.cache
 # Configure logger (optional)
 FlowChat::Config.logger = Rails.logger
 
+# Configure simulator security (REQUIRED for simulator mode)
+# This secret is used to authenticate simulator requests via signed cookies
+case Rails.env
+when 'development', 'test'
+  # Use Rails secret key with environment suffix for development
+  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_#{Rails.env}"
+when 'staging', 'production'
+  # Use environment variable for production security
+  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
+  
+  # Fail fast if simulator secret is not configured but might be needed
+  if FlowChat::Config.simulator_secret.blank?
+    Rails.logger.warn "FLOWCHAT_SIMULATOR_SECRET not configured. Simulator mode will be unavailable."
+  end
+end
+
 # Configure USSD pagination (optional)
 FlowChat::Config.ussd.pagination_page_size = 140
 FlowChat::Config.ussd.pagination_back_option = "0"
@@ -29,3 +45,42 @@ FlowChat::Config.ussd.pagination_next_text = "More"
 # Configure resumable sessions (optional)
 FlowChat::Config.ussd.resumable_sessions_enabled = true
 FlowChat::Config.ussd.resumable_sessions_timeout_seconds = 300 # 5 minutes
+
+# Configure WhatsApp message handling mode based on environment
+case Rails.env
+when 'development'
+  # Development: Use simulator mode for easy testing
+  FlowChat::Config.whatsapp.message_handling_mode = :simulator
+  
+when 'test'
+  # Test: Use simulator mode for deterministic testing
+  FlowChat::Config.whatsapp.message_handling_mode = :simulator
+  
+when 'staging'
+  # Staging: Use inline mode for real WhatsApp testing
+  FlowChat::Config.whatsapp.message_handling_mode = :inline
+  
+when 'production'
+  # Production: Use background mode for high volume
+  FlowChat::Config.whatsapp.message_handling_mode = :background
+  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+end
+
+# Configure per-environment WhatsApp security
+# Note: These are global defaults. You can override per-configuration in your controllers.
+
+# Example of per-environment WhatsApp security configuration:
+# 
+# For development/test: You might want to disable signature validation for easier testing
+# For staging: Enable validation to match production behavior  
+# For production: Always enable validation for security
+#
+# Individual WhatsApp configurations can override these settings:
+#
+# config = FlowChat::Whatsapp::Configuration.new
+# config.access_token = "your_token"
+# config.app_secret = "your_app_secret"              # Required for webhook validation
+# config.skip_signature_validation = false           # false = validate signatures (recommended)
+#
+# Development override example:
+# config.skip_signature_validation = Rails.env.development? # Only skip in development

data/examples/multi_tenant_whatsapp_controller.rb

@@ -11,7 +11,11 @@ class MultiTenantWhatsappController < ApplicationController
     # Get tenant-specific WhatsApp configuration
     whatsapp_config = get_whatsapp_config_for_tenant(tenant)
 
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    # Enable simulator for local endpoint testing during development
+    # This allows testing different tenant endpoints via the simulator interface
+    enable_simulator = Rails.env.development? || Rails.env.staging?
+
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: enable_simulator) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end

data/examples/simulator_controller.rb

@@ -0,0 +1,95 @@
+# Example Simulator Controller
+# Add this to your Rails application as app/controllers/simulator_controller.rb
+
+class SimulatorController < ApplicationController
+  include FlowChat::Simulator::Controller
+
+  def index
+    flowchat_simulator
+  end
+
+  protected
+
+  # Define different local endpoints to test on the same server
+  def configurations
+    {
+      ussd_main: {
+        name: "Main USSD Endpoint",
+        description: "Primary USSD integration endpoint",
+        processor_type: "ussd",
+        provider: "nalo",
+        endpoint: "/ussd",
+        icon: "📱",
+        color: "#28a745"
+      },
+      whatsapp_main: {
+        name: "Main WhatsApp Endpoint", 
+        description: "Primary WhatsApp webhook endpoint",
+        processor_type: "whatsapp",
+        provider: "cloud_api",
+        endpoint: "/whatsapp/webhook",
+        icon: "💬",
+        color: "#25D366"
+      },
+      whatsapp_v2: {
+        name: "WhatsApp API v2",
+        description: "Alternative WhatsApp endpoint (v2 API)",
+        processor_type: "whatsapp",
+        provider: "cloud_api", 
+        endpoint: "/api/v2/whatsapp/webhook",
+        icon: "🔄",
+        color: "#17a2b8"
+      },
+      whatsapp_tenant_a: {
+        name: "Tenant A WhatsApp",
+        description: "Multi-tenant WhatsApp endpoint for Tenant A",
+        processor_type: "whatsapp",
+        provider: "cloud_api",
+        endpoint: "/tenants/a/whatsapp/webhook",
+        icon: "🏢",
+        color: "#fd7e14"
+      },
+      whatsapp_legacy: {
+        name: "Legacy WhatsApp",
+        description: "Legacy WhatsApp endpoint for backward compatibility",
+        processor_type: "whatsapp",
+        provider: "cloud_api",
+        endpoint: "/legacy/whatsapp",
+        icon: "📦",
+        color: "#6c757d"
+      }
+    }
+  end
+
+  # Default configuration to start with
+  def default_config_key
+    :whatsapp_main
+  end
+
+  # Default test phone number
+  def default_phone_number
+    "+1234567890"
+  end
+
+  # Default test contact name  
+  def default_contact_name
+    "Test User"
+  end
+end
+
+# Add this route to your config/routes.rb:
+# get '/simulator' => 'simulator#index'
+
+# Usage:
+# 1. Start your Rails server: rails server
+# 2. Visit http://localhost:3000/simulator
+# 3. Select different endpoints from the dropdown to test
+# 4. Send test messages to see how each endpoint responds
+# 5. View request/response logs in real-time
+
+# This allows you to test:
+# - Different controller implementations on the same server
+# - Different API versions (v1, v2, etc.)
+# - Multi-tenant endpoints with different configurations  
+# - Legacy endpoints alongside new ones
+# - Different flow implementations for different endpoints 

data/examples/whatsapp_controller.rb

@@ -5,17 +5,24 @@ class WhatsappController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    # Enable simulator mode for local endpoint testing in development
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
       # Use cache-based session store for longer WhatsApp conversations
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
     processor.run WelcomeFlow, :main_page
+  rescue FlowChat::Whatsapp::ConfigurationError => e
+    Rails.logger.error "WhatsApp configuration error: #{e.message}"
+    head :internal_server_error
+  rescue => e
+    Rails.logger.error "Unexpected error processing WhatsApp webhook: #{e.message}"
+    head :internal_server_error
   end
 end
 
-# Example with Custom Configuration
+# Example with Custom Configuration and Security
 class CustomWhatsappController < ApplicationController
   skip_forgery_protection
 
@@ -28,13 +35,95 @@ class CustomWhatsappController < ApplicationController
     custom_config.app_id = ENV["MY_WHATSAPP_APP_ID"]
     custom_config.app_secret = ENV["MY_WHATSAPP_APP_SECRET"]
     custom_config.business_account_id = ENV["MY_WHATSAPP_BUSINESS_ACCOUNT_ID"]
+    
+    # Security configuration
+    custom_config.skip_signature_validation = !Rails.env.production? # Only skip in non-production
 
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    # Enable simulator for local endpoint testing in non-production environments  
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
     processor.run WelcomeFlow, :main_page
+  rescue FlowChat::Whatsapp::ConfigurationError => e
+    Rails.logger.error "WhatsApp configuration error: #{e.message}"
+    head :internal_server_error
+  rescue => e
+    Rails.logger.error "Unexpected error processing WhatsApp webhook: #{e.message}"
+    head :internal_server_error
+  end
+end
+
+# Example with Environment-Specific Security
+class EnvironmentAwareWhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Configure security based on environment
+    custom_config = build_whatsapp_config
+    
+    # Enable simulator for local endpoint testing in development/staging
+    enable_simulator = Rails.env.development? || Rails.env.staging?
+
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: enable_simulator) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  rescue FlowChat::Whatsapp::ConfigurationError => e
+    Rails.logger.error "WhatsApp configuration error: #{e.message}"
+    head :internal_server_error
+  rescue => e
+    Rails.logger.error "Unexpected error processing WhatsApp webhook: #{e.message}"
+    head :internal_server_error
+  end
+
+  private
+
+  def build_whatsapp_config
+    config = FlowChat::Whatsapp::Configuration.new
+    
+    case Rails.env
+    when 'development'
+      # Development: More relaxed security for easier testing
+      config.access_token = ENV["WHATSAPP_ACCESS_TOKEN"]
+      config.phone_number_id = ENV["WHATSAPP_PHONE_NUMBER_ID"]
+      config.verify_token = ENV["WHATSAPP_VERIFY_TOKEN"]
+      config.app_id = ENV["WHATSAPP_APP_ID"]
+      config.app_secret = ENV["WHATSAPP_APP_SECRET"]  # Optional in development
+      config.business_account_id = ENV["WHATSAPP_BUSINESS_ACCOUNT_ID"]
+      config.skip_signature_validation = true  # Skip validation for easier development
+      
+    when 'test'
+      # Test: Use test credentials
+      config.access_token = "test_token"
+      config.phone_number_id = "test_phone_id"
+      config.verify_token = "test_verify_token"
+      config.app_id = "test_app_id"
+      config.app_secret = "test_app_secret"
+      config.business_account_id = "test_business_id"
+      config.skip_signature_validation = true  # Skip validation in tests
+      
+    when 'staging', 'production'
+      # Production: Full security enabled
+      config.access_token = ENV["WHATSAPP_ACCESS_TOKEN"]
+      config.phone_number_id = ENV["WHATSAPP_PHONE_NUMBER_ID"]
+      config.verify_token = ENV["WHATSAPP_VERIFY_TOKEN"]
+      config.app_id = ENV["WHATSAPP_APP_ID"]
+      config.app_secret = ENV["WHATSAPP_APP_SECRET"]  # Required for security
+      config.business_account_id = ENV["WHATSAPP_BUSINESS_ACCOUNT_ID"]
+      config.skip_signature_validation = false  # Always validate in production
+      
+      # Ensure required security configuration is present
+      if config.app_secret.blank?
+        raise FlowChat::Whatsapp::ConfigurationError, 
+          "WHATSAPP_APP_SECRET is required for webhook signature validation in #{Rails.env}"
+      end
+    end
+    
+    config
   end
 end
 

data/lib/flow_chat/base_processor.rb

@@ -4,9 +4,10 @@ module FlowChat
   class BaseProcessor
     attr_reader :middleware
 
-    def initialize(controller)
+    def initialize(controller, enable_simulator: nil)
       @context = FlowChat::Context.new
       @context["controller"] = controller
+      @context["enable_simulator"] = enable_simulator.nil? ? (defined?(Rails) && Rails.env.local?) : enable_simulator
       @middleware = ::Middleware::Builder.new(name: middleware_name)
 
       yield self if block_given?

data/lib/flow_chat/config.rb

@@ -3,6 +3,7 @@ module FlowChat
     # General framework configuration
     mattr_accessor :logger, default: Logger.new($stdout)
     mattr_accessor :cache, default: nil
+    mattr_accessor :simulator_secret, default: nil
 
     # USSD-specific configuration object
     def self.ussd
@@ -33,11 +34,12 @@ module FlowChat
 
     class WhatsappConfig
       attr_accessor :background_job_class
-      attr_reader :message_handling_mode
+      attr_reader :message_handling_mode, :api_base_url
 
       def initialize
         @message_handling_mode = :inline
         @background_job_class = "WhatsappMessageJob"
+        @api_base_url = "https://graph.facebook.com/v22.0"
       end
 
       # Validate message handling mode