flow_chat 0.9.0 → 0.10.0

data/lib/flow_chat/whatsapp/gateway/cloud_api.rb

@@ -1,16 +1,14 @@
 require "net/http"
 require "json"
-require "openssl"
 
 module FlowChat
   module Whatsapp
-    # Configuration-related errors
-    class ConfigurationError < StandardError; end
-
     module Gateway
       class CloudApi
         include FlowChat::Instrumentation
         include FlowChat::GatewayAsyncSupport
+        include FlowChat::Meta::SignatureValidation
+        include FlowChat::Meta::WebhookVerification
 
         attr_reader :context
 
@@ -63,6 +61,23 @@ module FlowChat
           FlowChat.logger.debug { "CloudApi: Added Whatsapp::Middleware::ChoiceMapper" }
         end
 
+        # What this gateway is, for the shared Meta:: modules. Public because
+        # FlowChat::Meta::GatewayIdentity declares them public: a gateway saying
+        # which platform it speaks for is not a secret, unlike how it validates a
+        # signature. Keeping them here rather than below `private` means every
+        # Meta gateway answers these the same way.
+        def platform
+          :whatsapp
+        end
+
+        def platform_label
+          "WhatsApp"
+        end
+
+        def configuration_error_class
+          FlowChat::Whatsapp::ConfigurationError
+        end
+
         private
 
         def determine_message_handler(context)
@@ -76,34 +91,6 @@ module FlowChat
           end
         end
 
-        def handle_verification(context)
-          params = @controller.request.params
-
-          verify_token = @config.verify_token
-          provided_token = params["hub.verify_token"]
-          challenge = params["hub.challenge"]
-
-          FlowChat.logger.debug { "CloudApi: Webhook verification - provided token matches: #{provided_token == verify_token}" }
-
-          if provided_token == verify_token
-            # Use instrumentation for webhook verification success
-            instrument(Events::WEBHOOK_VERIFIED, {
-              challenge: challenge,
-              platform: :whatsapp
-            })
-
-            @controller.render plain: challenge
-          else
-            # Use instrumentation for webhook verification failure
-            instrument(Events::WEBHOOK_FAILED, {
-              reason: "Invalid verify token",
-              platform: :whatsapp
-            })
-
-            @controller.head :forbidden
-          end
-        end
-
         def handle_webhook(context)
           # Parse body
           begin
@@ -131,164 +118,232 @@ module FlowChat
 
           FlowChat.logger.debug { "CloudApi: Webhook signature validation passed" }
 
-          # Extract message data from WhatsApp webhook
-          entry = @body.dig("entry", 0)
-          unless entry
+          # A delivery can carry several accounts and several kinds of change at
+          # once, so every entry and every change gets looked at rather than only
+          # the first of each.
+          entries = @body["entry"]
+          unless entries.is_a?(Array) && entries.any?
             FlowChat.logger.debug { "CloudApi: No entry found in webhook body - returning OK" }
             return @controller.head :ok
           end
 
-          changes = entry.dig("changes", 0)
-          unless changes
-            FlowChat.logger.debug { "CloudApi: No changes found in webhook entry - returning OK" }
-            return @controller.head :ok
-          end
-
-          value = changes["value"]
-          unless value
-            FlowChat.logger.debug { "CloudApi: No value found in webhook changes - returning OK" }
-            return @controller.head :ok
-          end
-
-          # Handle incoming messages
-          if value["messages"]&.any?
-            message = value["messages"].first
-            contact = value["contacts"]&.first
-
-            phone_number = FlowChat::PhoneNumberUtil.to_e164(message["from"])
-            message_id = message["id"]
-            contact_name = contact&.dig("profile", "name")
-            business_phone_number = value.dig("metadata", "display_phone_number")
-            business_phone_number_id = value.dig("metadata", "phone_number_id")
-
-            # Validate that webhook is for our configured phone number
-            if business_phone_number_id != @config.phone_number_id
-              FlowChat.logger.warn { "CloudApi: Webhook received for phone_number_id '#{business_phone_number_id}' but configured for '#{@config.phone_number_id}' - rejecting" }
-              return @controller.head :forbidden
-            end
-
-            context["request.id"] = phone_number
-            context["request.user_id"] = phone_number
-            context["request.user_name"] = contact_name if contact_name
-            context["request.msisdn"] = phone_number
-            context["request.gateway"] = :whatsapp_cloud_api
-            context["request.platform"] = :whatsapp
-            context["request.message_id"] = message_id
-            context["request.timestamp"] = Time.current.iso8601
-            context["request.body"] = @body
-
-            context["whatsapp.business.phone_number"] = FlowChat::PhoneNumberUtil.to_e164(business_phone_number)
-            context["whatsapp.business.phone_number_id"] = business_phone_number_id
-            context["whatsapp.client"] = @client
-
-            # Extract message content based on type
-            extract_message_content!(message, context)
-
-            if context.input.present?
-              # Use instrumentation for message received
-              instrument(Events::MESSAGE_RECEIVED, {
-                from: phone_number,
-                message: context.input,
-                message_type: message["type"],
-                message_id: message_id
-              })
-            end
-
-            FlowChat.logger.debug { "CloudApi: Message content extracted - Type: #{message["type"]}, Input: '#{context.input}'" }
-
-            # Determine routing: async enqueue, background execute, or inline
-            if should_enqueue_async?
-              # Webhook with async enabled → enqueue job and return immediately
-              enqueue_async_job
-              return @controller.head :ok
-            else
-              # Background OR inline → process message
-              # Determine message handling mode (simulator vs inline)
-              handler_mode = determine_message_handler(context)
-
-              # Process the message based on handling mode
-              case handler_mode
-              when :inline
-                handle_message_inline(context, @controller)
-              when :simulator
-                # Return early from simulator mode to preserve the JSON response
-                return handle_message_simulator(context, @controller)
+          # Only one change per delivery can drive a flow, because only one can own
+          # the response to this request.
+          flow_ran = false
+
+          entries.each do |entry|
+            changes = entry["changes"]
+            next unless changes.is_a?(Array)
+
+            changes.each do |change|
+              value = change["value"]
+              next unless value.is_a?(Hash)
+
+              case webhook_field(change, value)
+              when "messages"
+                # There is no separate `statuses` field to subscribe to: Meta
+                # reports delivery status under `messages` as well, in a change
+                # carrying `statuses` and no `messages`. Handled before the flow
+                # slot is claimed, or a status arriving ahead of a message in the
+                # same delivery would spend the slot and drop the message.
+                #
+                # Foreground only. With async enabled the job re-enters this
+                # method on the same body, so publishing in both announced every
+                # status twice and delivery receipts double-counted. The request
+                # publishes them: it already holds the delivery, so a receipt is
+                # announced when it arrives rather than when the queue reaches
+                # it, and survives a job that is never picked up.
+                handle_statuses(value) if value["statuses"].present? && !in_background?
+
+                next if value["messages"].blank?
+
+                if flow_ran
+                  FlowChat.logger.warn { "CloudApi: A second messages change arrived in the same delivery and was not processed" }
+                  next
+                end
+                flow_ran = true
+
+                case handle_messages(context, value)
+                when :rejected then return @controller.head :forbidden
+                when :enqueued then return @controller.head :ok
+                when :rendered then return nil # simulator already wrote the response
+                end
+              when "statuses"
+                # Only reachable for a payload built without a field name, which
+                # our own fixtures do and Meta does not.
+                handle_statuses(value) unless in_background?
+              else
+                # Anything that is not a message or its delivery. Coexistence
+                # echoes, contact syncs, imported history, account bans, template
+                # approvals: all of it is the application's domain, so it is
+                # published rather than interpreted here.
+                handle_unmodelled_field(change["field"], value, entry["id"]) unless in_background?
               end
             end
           end
 
-          # Handle message status updates
-          if value["statuses"]&.any?
-            statuses = value["statuses"]
-            FlowChat.logger.info { "CloudApi: Received #{statuses.size} status update(s)" }
-            FlowChat.logger.debug { "CloudApi: Status updates: #{statuses.inspect}" }
-          end
-
           @controller.head :ok
         end
 
-        # Validate webhook signature to ensure request comes from WhatsApp
-        def valid_webhook_signature?(request)
-          # Check if signature validation is explicitly disabled
-          if @config.skip_signature_validation
-            FlowChat.logger.debug { "CloudApi: Webhook signature validation is disabled" }
-            return true
-          end
+        # Meta names the change in `field`. Older payloads, and the ones our own
+        # tests build, leave it out, so fall back to what the value carries.
+        def webhook_field(change, value)
+          return change["field"] if change["field"].present?
+          return "messages" if value["messages"].is_a?(Array) && value["messages"].any?
+          return "statuses" if value["statuses"].is_a?(Array) && value["statuses"].any?
+
+          nil
+        end
 
-          # Require app_secret for signature validation
-          unless @config.app_secret && !@config.app_secret.empty?
-            error_msg = "WhatsApp app_secret is required for webhook signature validation. " \
-                       "Either configure app_secret or set skip_signature_validation=true to explicitly disable validation."
-            FlowChat.logger.error { "CloudApi: #{error_msg}" }
-            raise FlowChat::Whatsapp::ConfigurationError, error_msg
+        # Returns what happened, so the caller can decide whether it still owns the
+        # response: :rejected, :enqueued, :rendered, :processed or :skipped.
+        def handle_messages(context, value)
+          message = value["messages"]&.first
+          return :skipped unless message
+
+          contact = value["contacts"]&.first
+
+          phone_number = FlowChat::PhoneNumberUtil.to_e164(message["from"])
+          message_id = message["id"]
+          contact_name = contact&.dig("profile", "name")
+          business_phone_number = value.dig("metadata", "display_phone_number")
+          business_phone_number_id = value.dig("metadata", "phone_number_id")
+
+          # Validate that webhook is for our configured phone number. Skipped
+          # in simulator mode rather than requiring the simulator to send an
+          # id that matches a real configuration: the simulator's whole
+          # point is running a turn with no live credentials at hand. Safe
+          # to skip, not a hole for real traffic, because
+          # context["simulator_mode"] is only ever true once simulate? has
+          # already checked the signed simulator cookie, above in
+          # handle_webhook.
+          if !context["simulator_mode"] && business_phone_number_id != @config.phone_number_id
+            FlowChat.logger.warn { "CloudApi: Webhook received for phone_number_id '#{business_phone_number_id}' but configured for '#{@config.phone_number_id}' - rejecting" }
+            return :rejected
           end
 
-          signature_header = request.headers["X-Hub-Signature-256"]
-          unless signature_header
-            FlowChat.logger.warn { "CloudApi: No X-Hub-Signature-256 header found in request" }
-            return false
+          context["request.id"] = phone_number
+          context["request.user_id"] = phone_number
+          context["request.user_name"] = contact_name if contact_name
+          context["request.msisdn"] = phone_number
+          context["request.gateway"] = :whatsapp_cloud_api
+          context["request.platform"] = :whatsapp
+          context["request.message_id"] = message_id
+          context["request.timestamp"] = Time.current.iso8601
+          context["request.body"] = @body
+
+          context["whatsapp.business.phone_number"] = FlowChat::PhoneNumberUtil.to_e164(business_phone_number)
+          context["whatsapp.business.phone_number_id"] = business_phone_number_id
+          context["whatsapp.client"] = @client
+
+          # Extract message content based on type
+          extract_message_content!(message, context)
+
+          if inbound_message?(context)
+            # Use instrumentation for message received
+            instrument(Events::MESSAGE_RECEIVED, {
+              from: phone_number,
+              message: context.input,
+              message_type: message["type"],
+              message_id: message_id
+            })
           end
 
-          # Extract signature from header (format: "sha256=<signature>")
-          expected_signature = signature_header.sub("sha256=", "")
+          FlowChat.logger.debug { "CloudApi: Message content extracted - Type: #{message["type"]}, Input: '#{context.input}'" }
 
-          # Get raw request body
-          request.body.rewind
-          body = request.body.read
-          request.body.rewind
+          # Determine routing: async enqueue, background execute, or inline
+          if should_enqueue_async?
+            # Webhook with async enabled → enqueue job and return immediately
+            enqueue_async_job
+            return :enqueued
+          end
 
-          # Calculate HMAC signature
-          calculated_signature = OpenSSL::HMAC.hexdigest(
-            OpenSSL::Digest.new("sha256"),
-            @config.app_secret,
-            body
-          )
+          # Background OR inline → process message
+          case determine_message_handler(context)
+          when :inline
+            handle_message_inline(context, @controller)
+            :processed
+          when :simulator
+            handle_message_simulator(context, @controller)
+            :rendered
+          end
+        end
 
-          # Compare signatures using secure comparison to prevent timing attacks
-          signature_valid = secure_compare(expected_signature, calculated_signature)
+        def handle_statuses(value)
+          statuses = value["statuses"]
+          return if statuses.blank?
 
-          if signature_valid
-            FlowChat.logger.debug { "CloudApi: Webhook signature validation successful" }
-          else
-            FlowChat.logger.warn { "CloudApi: Webhook signature validation failed - signatures do not match" }
-          end
+          FlowChat.logger.info { "CloudApi: Received #{statuses.size} status update(s)" }
+          FlowChat.logger.debug { "CloudApi: Status updates: #{statuses.inspect}" }
 
-          signature_valid
-        rescue FlowChat::Whatsapp::ConfigurationError
-          raise
-        rescue => e
-          FlowChat.logger.error { "CloudApi: Error validating webhook signature: #{e.class.name}: #{e.message}" }
-          false
+          statuses.each do |status|
+            instrument(Events::MESSAGE_STATUS, {
+              platform: :whatsapp,
+              gateway: :whatsapp_cloud_api,
+              business_phone_number_id: value.dig("metadata", "phone_number_id"),
+              message_id: status["id"],
+              recipient: status["recipient_id"],
+              status: status["status"],
+              timestamp: status["timestamp"],
+              errors: status["errors"],
+              # Meta reports more about a delivery than a status and a time: what
+              # it billed the conversation as, and its own view of the window.
+              # None of it is this gem's business to interpret, and all of it is
+              # gone if the named keys are the only way through.
+              value: status
+            })
+          end
         end
 
-        # Secure string comparison to prevent timing attacks
-        def secure_compare(a, b)
-          return false unless a.bytesize == b.bytesize
+        # Everything that is not a message or its delivery. Verified, named, and
+        # handed on whole for the application to make sense of.
+        #
+        # The account id comes from the entry rather than the value because a change
+        # about the account itself names no phone number: a ban, a review outcome, a
+        # template approval. Without it those arrive identifying nothing, and an
+        # application holding several businesses cannot tell whose they are.
+        def handle_unmodelled_field(field, value, business_account_id)
+          FlowChat.logger.info {
+            "CloudApi: Publishing webhook field '#{field}' (value keys: #{value.keys.join(", ")})"
+          }
+
+          payload = {
+            platform: :whatsapp,
+            gateway: :whatsapp_cloud_api,
+            field: field,
+            business_account_id: business_account_id,
+            business_phone_number: value.dig("metadata", "display_phone_number"),
+            business_phone_number_id: value.dig("metadata", "phone_number_id"),
+            value: value
+          }
+
+          origin = echo_origin(field, value)
+          payload[:echo_origin] = origin if origin
+
+          instrument(Events::WEBHOOK_RECEIVED, payload)
+        end
 
-          l = a.unpack("C*")
-          res = 0
-          b.each_byte { |byte| res |= byte ^ l.shift }
-          res == 0
+        # An echo reports a message sent on the thread by someone other than the
+        # user we are talking to. Which someone matters: a human replying from the
+        # business inbox usually means the application should stand the flow
+        # down, while our own send coming back means nothing at all. Only the
+        # app_id separates them, and only this gateway knows our own, so it is
+        # derived here rather than left for every subscriber to work out.
+        #
+        # Meta names the coexistence echo field "smb_message_echoes" and nests the
+        # echoes themselves under "message_echoes"; both are matched precisely
+        # rather than by a loose "echo" substring or "first array in the value",
+        # since a field this gateway does not otherwise interpret could carry
+        # other arrays under other names.
+        def echo_origin(field, value)
+          return nil unless field == "smb_message_echoes"
+
+          app_id = value["message_echoes"]&.first&.dig("app_id")
+
+          return :human_agent if app_id.blank?
+          return :self if app_id.to_s == @config.app_id.to_s
+
+          :other_app
         end
 
         def extract_message_content!(message, context)
@@ -319,7 +374,7 @@ module FlowChat
               address: message.dig("location", "address")
             }
             context["request.location"] = location
-            context.input = FlowChat::Input::LOCATION
+            context.input = ""
             FlowChat.logger.debug { "CloudApi: Location received - Lat: #{location[:latitude]}, Lng: #{location[:longitude]}" }
           when "image", "document", "audio", "video", "sticker"
             media_data = message[message["type"]]
@@ -332,7 +387,8 @@ module FlowChat
               sha256: media_data["sha256"],
               animated: media_data["animated"]
             }
-            context.input = FlowChat::Input::MEDIA
+            # The caption (if any) is the turn's text; a text-less media message has blank input.
+            context.input = media_data["caption"].presence || ""
             FlowChat.logger.debug { "CloudApi: Media received - Type: #{message["type"]}, ID: #{media_data["id"]}" }
           when "contacts"
             # WhatsApp sends contacts as an array, take the first one
@@ -346,7 +402,7 @@ module FlowChat
                 phones: phones.map { |p| p["phone"] },
                 phone_number: phones.first&.dig("phone")
               }
-              context.input = FlowChat::Input::CONTACT
+              context.input = ""
               FlowChat.logger.debug { "CloudApi: Contact received - Name: #{context["request.contact"][:name]}" }
             end
           end
@@ -356,9 +412,24 @@ module FlowChat
           response = @app.call(context)
           if response
             type, prompt, choices, media = response
-            result = @client.send_message(context["request.msisdn"], prompt, choices: choices, media: media)
+            result = report_delivery_failure(
+              context,
+              to: context["request.msisdn"],
+              session_id: context["request.id"],
+              message: prompt,
+              message_type: (type == :prompt) ? "prompt" : "terminal",
+              gateway: :whatsapp_cloud_api,
+              platform: :whatsapp
+            ) do
+              @client.send_message(context["request.msisdn"], prompt, choices: choices, media: media)
+            end
             context["whatsapp.message_result"] = result
 
+            # report_delivery_failure already reported this; a nil result
+            # means the platform did not accept the message, and instrumenting
+            # MESSAGE_SENT anyway counted a delivery that never happened.
+            return unless result
+
             # Instrument message sent
             instrument(Events::MESSAGE_SENT, {
               to: context["request.msisdn"],
@@ -368,11 +439,21 @@ module FlowChat
               gateway: :whatsapp_cloud_api,
               platform: :whatsapp,
               content_length: prompt.to_s.length,
+              # What Meta called it, so this and message.status can be joined.
+              platform_message_id: platform_message_id_from(result),
+              duration_ms: context[FlowChat::Instrumentation::DELIVERY_DURATION_KEY],
               timestamp: context["request.timestamp"]
             })
           end
         end
 
+        # Meta answers a send with the ids it assigned.
+        def platform_message_id_from(result)
+          return nil unless result.is_a?(Hash)
+
+          result.dig("messages", 0, "id")
+        end
+
         def handle_message_simulator(context, controller)
           response = @app.call(context)
 
@@ -404,39 +485,9 @@ module FlowChat
           # Check if simulator mode is enabled for this processor
           return false unless context["enable_simulator"]
 
-          # Then check if simulator mode is requested and valid
-          @body.dig("simulator_mode") && valid_simulator_cookie?(context)
-        end
-
-        def valid_simulator_cookie?(context)
-          simulator_secret = FlowChat::Config.simulator_secret
-          return false unless simulator_secret && !simulator_secret.empty?
-
-          # Check for simulator cookie
-          simulator_cookie = @controller.request.cookies["flowchat_simulator"]
-          return false unless simulator_cookie
-
-          # Verify the cookie is a valid HMAC signature
-          # Cookie format: "timestamp:signature" where signature = HMAC(simulator_secret, "simulator:timestamp")
-          begin
-            timestamp_str, signature = simulator_cookie.split(":", 2)
-            return false unless timestamp_str && signature
-
-            # Check timestamp is recent (within 24 hours for reasonable session duration)
-            timestamp = timestamp_str.to_i
-            return false if timestamp <= 0
-            return false if (Time.now.to_i - timestamp).abs > 86400 # 24 hours
-
-            # Calculate expected signature
-            message = "simulator:#{timestamp_str}"
-            expected_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), simulator_secret, message)
-
-            # Use secure comparison
-            secure_compare(signature, expected_signature)
-          rescue => e
-            Rails.logger.warn "Invalid simulator cookie format: #{e.message}"
-            false
-          end
+          # Then check if simulator mode is requested and authorized
+          @body.dig("simulator_mode") &&
+            FlowChat::Security.valid_simulator_cookie?(@controller.request.cookies[FlowChat::Security::SIMULATOR_COOKIE_NAME])
         end
 
         def parse_request_body(request)