flow_chat 0.8.2 → 0.10.0

data/SECURITY.md

@@ -1,365 +1,58 @@
-# FlowChat Security Guide
+# Security Policy
 
-This guide covers the security features and best practices for FlowChat, including webhook signature validation and simulator authentication.
+We take the security of FlowChat seriously. Because FlowChat is a framework for
+building conversational interfaces that other applications are built on, a
+vulnerability here can affect many downstream apps. We appreciate your help in
+disclosing issues responsibly.
 
-## Overview
+## Supported Versions
 
-FlowChat includes comprehensive security features to protect your WhatsApp and USSD applications:
+FlowChat is pre-1.0 and evolving quickly. Security fixes are released against
+the **latest published version** only. If you are running an older release,
+please upgrade before reporting an issue to confirm it still reproduces.
 
-- **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
+| Version | Supported          |
+| ------- | ------------------ |
+| Latest release (`0.10.x`) | :white_check_mark: |
+| Older releases | :x: |
 
-## WhatsApp Webhook Security
+## Reporting a Vulnerability
 
-### Signature Validation
+**Please do not report security vulnerabilities through public GitHub issues,
+discussions, or pull requests.**
 
-FlowChat automatically validates WhatsApp webhook signatures using HMAC-SHA256 to ensure requests come from WhatsApp.
+Instead, use one of the following private channels:
 
-#### Required Configuration
+- **Preferred:** [Open a private vulnerability report](https://github.com/radioactive-labs/flow_chat/security/advisories/new)
+  via GitHub Security Advisories.
+- **Email:** [sfroelich01@gmail.com](mailto:sfroelich01@gmail.com) with the
+  subject line `[SECURITY] FlowChat`.
 
-For webhook signature validation, you need to configure your WhatsApp app secret:
+To help us triage quickly, please include as much of the following as you can:
 
-```ruby
-# Using Rails credentials
-rails credentials:edit
-```
+- The FlowChat version (and Rails version) affected.
+- A description of the vulnerability and its impact.
+- Steps to reproduce, or a proof-of-concept.
+- Any known workarounds.
 
-```yaml
-whatsapp:
-  app_secret: "your_whatsapp_app_secret"
-  # ... other credentials
-```
+## What to Expect
 
-Or using environment variables:
+- **Acknowledgement:** We aim to acknowledge your report within **3 business days**.
+- **Assessment:** We will investigate and let you know whether the report is
+  accepted, along with our expected timeline for a fix.
+- **Disclosure:** We follow a coordinated disclosure process. We will work with
+  you to agree on a disclosure date once a fix is available, and we are happy to
+  credit you in the advisory unless you prefer to remain anonymous.
 
-```bash
-export WHATSAPP_APP_SECRET="your_whatsapp_app_secret"
-```
+Please give us a reasonable opportunity to address the issue before any public
+disclosure.
 
-#### Security Modes
+## Scope
 
-FlowChat supports two security modes for webhook validation:
+Security reports about the FlowChat framework code in this repository are in
+scope. Issues in applications *built with* FlowChat, or in third-party
+dependencies, should be reported to their respective maintainers — though if you
+believe a dependency issue is triggered by how FlowChat uses it, we would like
+to hear about it.
 
-**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. 
+Thank you for helping keep FlowChat and its community safe.

data/docs/architecture.md

@@ -0,0 +1,83 @@
+# Architecture
+
+FlowChat turns a stateless webhook into a stateful conversation by re-running your flow method from the top on every request and replaying its answers out of a session. This document explains the pieces that make that work.
+
+## The middleware stack
+
+A `FlowChat::Processor` builds one middleware stack per request, in a fixed order. Each layer wraps the next and calls it:
+
+```
+Gateway
+  -> Session::Middleware
+    -> platform middleware (and your custom middleware)
+      -> Executor
+        -> your Flow
+```
+
+The order is set in `Processor#create_middleware_stack`:
+
+1. **Gateway** runs first. It parses the platform's webhook into normalized context values (`request.msisdn`, `context.input`, and so on) and, after the inner stack returns, renders the result back to the platform. See [gateway-development.md](gateway-development.md).
+2. **`Session::Middleware`** computes the session id from the configured boundaries and identifier, and attaches the session store. See [configuration.md](configuration.md#sessions).
+3. **Platform middleware** is inserted by the gateway if it defines `configure_middleware_stack`. USSD uses this to add pagination and choice-number mapping, and it is where your custom middleware runs. A gateway without that hook just runs your custom middleware here.
+4. **Executor** runs last. Nothing runs after it. It instantiates your flow and calls the action.
+
+## The Executor and control flow by exception
+
+`FlowChat::Executor` builds a `FlowChat::App`, instantiates your flow with it, and calls the action method. Control flow is driven by exceptions raised from inside the flow and caught here:
+
+```ruby
+flow = flow_class.new(app)
+flow.send(action)
+raise FlowChat::Interrupt::Terminate, "Unexpected end of flow."
+rescue FlowChat::Interrupt::RestartFlow
+  retry
+rescue FlowChat::Interrupt::Prompt => e
+  [:prompt, e.prompt, e.choices, e.media]
+rescue FlowChat::Interrupt::Terminate => e
+  context.session.destroy
+  [:terminal, e.prompt, nil, e.media]
+```
+
+The three interrupts live in `FlowChat::Interrupt`:
+
+| Interrupt | Raised by | Effect |
+|---|---|---|
+| `Prompt` | `prompt.ask` / `select` / `yes?` when no input is available | Unwinds to the Executor, which returns the prompt for the gateway to render. Carries the message, choices, and media. |
+| `Terminate` | `app.say` and `prompt.say` | Ends the flow, destroys the session, and returns a terminal message. |
+| `RestartFlow` | `app.go_back` | Caught with `retry`, which re-runs the flow from the top against a fresh `App`. |
+
+If the action method returns normally without prompting or terminating, the Executor raises `Terminate` with "Unexpected end of flow", since a flow is expected to either prompt for more input or end with a message.
+
+These interrupts subclass `Exception`, not `StandardError`. This is deliberate: a `rescue` in your flow code (a bare `rescue => e` catches `StandardError`) will not swallow a prompt or terminate and break the engine. Avoid `rescue Exception` inside a flow, since that would catch them.
+
+## The replay model
+
+There is no saved program counter between requests. Each webhook rebuilds the `App` and re-runs the flow method from the first line. Progress is reconstructed from the session:
+
+- `app.screen(key)` checks the session for `key`. If a value is stored, it returns immediately without yielding the block. This fast-forwards through every screen already answered.
+- The first screen without a stored answer yields a `Prompt`. If the current turn has input for it, the prompt validates and transforms it, stores the result with `session.set(key, value)`, and returns, so execution falls through to the next screen. If not, the prompt raises `Interrupt::Prompt` and the turn ends there.
+
+Two rules follow. One inbound message is consumed by one screen per turn: once a screen takes the input, later screens in the same run see no input and prompt. And a given screen key may be presented only once per run; re-entering a key raises `ArgumentError`. To revisit a screen, use `app.go_back`, which clears the current screen's answer and raises `RestartFlow`.
+
+## The App
+
+`FlowChat::App` is the single object your flow talks to. It wraps the context and exposes:
+
+- `screen(key)`, the unit of interaction.
+- `say(msg, media:)`, to end the flow.
+- `go_back`, to return to the previous screen.
+- Read accessors for the turn: `text`, `media`, `location`, `contact`, `attachment_type`, and identity values `msisdn`, `user_id`, `platform`, `gateway`, `message_id`, `timestamp`, `contact_name`.
+
+`Flow` itself is a thin base class: it stores the `app` and nothing else. All conversation logic lives in the methods you write.
+
+## Sessions
+
+The session is a key-value store keyed by the session id. `FlowChat::Session::CacheSessionStore` persists it in `FlowChat::Config.cache`, so a session outlives the request. `screen` reads and writes it, `Terminate` destroys it. Boundaries and identifiers, which decide what shares a session, are covered in [configuration.md](configuration.md#sessions).
+
+## Async
+
+Gateways with an outbound API can run the flow in a background job instead of inline. The gateway detects async support, serializes the request, and enqueues a job that reconstructs a controller and re-runs the same stack in the background. USSD cannot do this, since its protocol needs a synchronous response. See [async-background-processing.md](async-background-processing.md) and [factory-pattern.md](factory-pattern.md).
+
+## Instrumentation
+
+Each stage emits `ActiveSupport::Notifications` events (flow execution, messages received and sent, session lifecycle, pagination, webhook verification). Subscribe to feed metrics and logs into your own backend. See [instrumentation.md](instrumentation.md).

data/docs/async-background-processing.md

@@ -0,0 +1,64 @@
+# Async and background processing
+
+A webhook has a response deadline. If a flow does slow work (calling the platform API, hitting your own services) the webhook can time out and the platform will retry, sometimes delivering the same message twice. Async processing acknowledges the webhook immediately and runs the flow in a background job.
+
+This works on gateways with an outbound API (WhatsApp, Telegram, HTTP, Intercom), because the job can send the reply through that API afterward. USSD cannot use it: its protocol requires the answer in the webhook response itself.
+
+## Enabling it
+
+Call `use_async` in the processor. It has two forms.
+
+Use a factory, and let FlowChat provide the job class:
+
+```ruby
+config.use_async(factory: :whatsapp)
+```
+
+Or use your own ActiveJob subclass, with optional job params:
+
+```ruby
+config.use_async(MyFlowJob, deployment_id: 123)
+```
+
+The `factory:` form is the common one and needs no custom job class. See [factory-pattern.md](factory-pattern.md).
+
+## How it works
+
+The `GatewayAsyncSupport` concern, mixed into every async-capable gateway, does the detection and enqueueing.
+
+1. On a real webhook, the gateway calls `should_enqueue_async?`. It returns true when async is enabled, the gateway supports it (`async_supported?`), and the request is not already running in the background.
+2. If so, the gateway serializes the request (params, method, headers, host, path, body, remote ip) and enqueues the job with `perform_later(request_context: ..., **job_params)`, then returns an immediate acknowledgement to the platform.
+3. The job reconstructs a `FlowChat::BackgroundController` from the serialized request. It quacks like a Rails controller (its `render` and `head` are no-ops, its `request` is a `BackgroundRequest` rebuilt from the serialized data), so the same gateway code runs against it.
+4. Running in the background, `should_enqueue_async?` now returns false (the controller is a `BackgroundController`), so the gateway processes the flow inline and sends the reply through the platform API.
+
+The same gateway and the same flow run in both passes. The only difference is who calls them: the webhook the first time, the job the second.
+
+## Custom jobs
+
+`FlowChat::AsyncJob` is the base class. It handles reconstructing the controller in `perform`; you implement `execute(controller, **job_params)`:
+
+```ruby
+class MyFlowJob < FlowChat::AsyncJob
+  def execute(controller, **job_params)
+    deployment_id = job_params[:deployment_id]
+    processor = FlowChat::Processor.new(controller) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+      config.use_async(MyFlowJob, deployment_id: deployment_id)
+    end
+    processor.run(WhatsAppFlow, :start)
+  end
+end
+```
+
+The job params you pass to `use_async` are forwarded to `execute`, so the background pass can rebuild the same processor. `FlowChat::GenericAsyncJob` is exactly this pattern wrapped around a factory, which is why the `factory:` form needs no job class of your own.
+
+## ActiveJob is optional
+
+`FlowChat::AsyncJob` subclasses `ActiveJob::Base` when ActiveJob is available. Without ActiveJob, FlowChat falls back to a plain class, so requiring the gem does not fail; you supply the queueing yourself in that case.
+
+## Related
+
+- [Factory pattern](factory-pattern.md)
+- [Configuration](configuration.md#async-processing)
+- [Architecture](architecture.md)