ses-dashboard 0.1.0 → 0.5.0

data/app/assets/stylesheets/ses_dashboard/application.css

@@ -217,10 +217,75 @@ tr:hover td { background: var(--color-bg); }
 /* ── Token display ───────────────────────────────────────── */
 .token-display { font-family: monospace; font-size: .8125rem; background: var(--color-bg); padding: .25rem .5rem; border-radius: .25rem; border: 1px solid var(--color-border); }
 
+/* ── Webhook Forwards builder ────────────────────────────── */
+.wf-target {
+  margin-bottom: .75rem;
+  padding: 1rem;
+}
+
+.wf-target-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: .75rem;
+}
+
+.wf-target-title {
+  font-weight: 600;
+  font-size: .875rem;
+}
+
+.wf-rules {
+  display: flex;
+  flex-direction: column;
+  gap: .5rem;
+  margin-bottom: .5rem;
+}
+
+.wf-rule {
+  display: flex;
+  align-items: flex-start;
+  gap: .5rem;
+}
+
+.wf-rule .wf-field    { flex: 0 0 140px; }
+.wf-rule .wf-operator { flex: 0 0 130px; }
+.wf-rule .wf-value-wrap { flex: 1; min-width: 0; }
+.wf-rule .wf-value    { width: 100%; }
+.wf-rule .btn         { flex-shrink: 0; align-self: flex-start; margin-top: 1px; }
+
+.wf-checkboxes {
+  display: flex;
+  flex-wrap: wrap;
+  gap: .15rem .75rem;
+  padding: .4rem .25rem;
+}
+
+.wf-checkbox-label {
+  display: inline-flex;
+  align-items: center;
+  gap: .3rem;
+  font-size: .8125rem;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.form-hint {
+  display: block;
+  font-size: .8125rem;
+  color: var(--color-text-muted);
+  margin-top: .25rem;
+}
+
+#wf-add-target { margin-top: .25rem; }
+
 /* ── Responsive ──────────────────────────────────────────── */
 @media (max-width: 640px) {
   .stat-grid { grid-template-columns: 1fr 1fr; }
   .page-header { flex-direction: column; align-items: flex-start; gap: .5rem; }
   .filter-bar { flex-direction: column; }
   .filter-bar .form-control { width: 100%; }
+  .wf-rule { flex-wrap: wrap; }
+  .wf-rule .wf-field, .wf-rule .wf-operator { flex: 1 1 45%; }
+  .wf-rule .wf-value-wrap { flex: 1 1 100%; }
 }

data/app/controllers/ses_dashboard/projects_controller.rb

@@ -55,7 +55,7 @@ module SesDashboard
     end
 
     def project_params
-      params.require(:project).permit(:name, :description)
+      params.require(:project).permit(:name, :description, :webhook_forwards_text)
     end
 
     def parse_date(str)

data/app/controllers/ses_dashboard/webhooks_controller.rb

@@ -9,7 +9,11 @@ module SesDashboard
 
     def create
       project = Project.find_by!(token: params[:project_token])
-      body    = request.body.read
+      request.body.rewind
+      body   = request.body.read
+      sns    = parse_sns_json(body)
+
+      verify_sns_signature!(sns) if sns && SesDashboard.configuration.verify_sns_signature
 
       result = WebhookProcessor.new(body).process
 
@@ -18,11 +22,15 @@ module SesDashboard
         confirm_subscription(result.subscribe_url)
       when :process_event
         WebhookEventPersistor.new(project, result).persist
+        WebhookForwarder.new(project, result).forward
       end
 
       head :ok
     rescue ActiveRecord::RecordNotFound
       head :not_found
+    rescue SnsSignatureVerifier::VerificationError => e
+      Rails.logger.warn("[SesDashboard] SNS signature rejected: #{e.message}") if defined?(Rails)
+      head :forbidden
     rescue => e
       Rails.logger.error("[SesDashboard] Webhook error: #{e.message}") if defined?(Rails)
       head :unprocessable_entity
@@ -35,5 +43,18 @@ module SesDashboard
     rescue => e
       Rails.logger.warn("[SesDashboard] SNS subscription confirm failed: #{e.message}") if defined?(Rails)
     end
+
+    def parse_sns_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def verify_sns_signature!(sns)
+      # Skip verification for raw delivery — no SNS envelope means no signature fields.
+      return unless sns&.key?("SigningCertURL")
+
+      SnsSignatureVerifier.new(sns).verify!
+    end
   end
 end

data/app/models/ses_dashboard/project.rb

@@ -6,15 +6,63 @@ module SesDashboard
 
     validates :name,  presence: true
     validates :token, presence: true, uniqueness: true
+    validate  :webhook_forwards_must_be_valid_json
 
     before_validation :generate_token, on: :create
 
     scope :ordered, -> { order(:name) }
 
+    # Manual JSON serialization for the webhook_forwards column.
+    # Avoids Rails serialize API which changed between 7.0 (positional)
+    # and 8.0 (keyword-only coder:).
+    def webhook_forwards
+      raw = read_attribute(:webhook_forwards)
+      return [] if raw.blank?
+      return raw if raw.is_a?(Array)
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      []
+    end
+
+    def webhook_forwards=(value)
+      write_attribute(:webhook_forwards, value.is_a?(String) ? value : Array(value).to_json)
+    end
+
+    # Virtual accessor for editing webhook_forwards as a JSON string in forms.
+    def webhook_forwards_text
+      forwards = Array(webhook_forwards)
+      forwards.empty? ? "" : JSON.pretty_generate(forwards)
+    end
+
+    def webhook_forwards_text=(value)
+      if value.blank?
+        self.webhook_forwards = []
+        return
+      end
+
+      parsed = JSON.parse(value)
+      self.webhook_forwards = Array(parsed)
+    rescue JSON::ParserError
+      @webhook_forwards_invalid = true
+    end
+
+    # Returns the effective forwards: project-level if configured, else global config.
+    def effective_webhook_forwards
+      project_level = Array(webhook_forwards).select { |f| (f[:url] || f["url"]).present? }
+      return project_level if project_level.any?
+
+      Array(SesDashboard.configuration&.webhook_forwards)
+    end
+
     private
 
     def generate_token
       self.token ||= SecureRandom.hex(16)
     end
+
+    def webhook_forwards_must_be_valid_json
+      errors.add(:webhook_forwards, "is not valid JSON") if @webhook_forwards_invalid
+    end
   end
 end

data/app/views/ses_dashboard/projects/_form.html.erb

@@ -19,6 +19,22 @@
     <%= f.text_area :description, class: "form-control", placeholder: "Optional description" %>
   </div>
 
+  <div class="form-group">
+    <label class="form-label">Webhook Forwards</label>
+    <small class="form-hint" style="margin-bottom:.5rem;display:block;">
+      Forward events to external URLs (e.g. Zapier). Add rules to filter which events are forwarded.
+      All rules must match. Leave empty to use global defaults.
+    </small>
+
+    <%= f.hidden_field :webhook_forwards_text, id: "webhook-forwards-json" %>
+
+    <div id="wf-targets"></div>
+
+    <button type="button" class="btn btn-outline btn-sm" id="wf-add-target">+ Add Forward Target</button>
+
+    <script type="application/json" id="wf-initial-data"><%= raw project.webhook_forwards_text.html_safe %></script>
+  </div>
+
   <%= f.submit class: "btn btn-primary" %>
   <%= link_to "Cancel", projects_path, class: "btn btn-outline" %>
 <% end %>

data/db/migrate/20240101000001_create_ses_dashboard_projects.rb

@@ -1,4 +1,10 @@
-class CreateSesDashboardProjects < ActiveRecord::Migration[8.0]
+_migration = begin
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"]
+rescue ArgumentError
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.0"]
+end
+
+class CreateSesDashboardProjects < _migration
   def change
     create_table :ses_dashboard_projects do |t|
       t.string :name,        null: false

data/db/migrate/20240101000002_create_ses_dashboard_emails.rb

@@ -1,4 +1,10 @@
-class CreateSesDashboardEmails < ActiveRecord::Migration[8.0]
+_migration = begin
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"]
+rescue ArgumentError
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.0"]
+end
+
+class CreateSesDashboardEmails < _migration
   def change
     create_table :ses_dashboard_emails do |t|
       t.references :project,    null: false, foreign_key: { to_table: :ses_dashboard_projects }

data/db/migrate/20240101000003_create_ses_dashboard_email_events.rb

@@ -1,4 +1,10 @@
-class CreateSesDashboardEmailEvents < ActiveRecord::Migration[8.0]
+_migration = begin
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"]
+rescue ArgumentError
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.0"]
+end
+
+class CreateSesDashboardEmailEvents < _migration
   def change
     create_table :ses_dashboard_email_events do |t|
       t.references :email,      null: false, foreign_key: { to_table: :ses_dashboard_emails }

data/db/migrate/20240101000004_add_webhook_forwards_to_ses_dashboard_projects.rb

@@ -0,0 +1,11 @@
+_migration = begin
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}"]
+rescue ArgumentError
+  ActiveRecord::Migration["#{Rails::VERSION::MAJOR}.0"]
+end
+
+class AddWebhookForwardsToSesDashboardProjects < _migration
+  def change
+    add_column :ses_dashboard_projects, :webhook_forwards, :text
+  end
+end

data/lib/ses/dashboard.rb

@@ -0,0 +1 @@
+require "ses_dashboard"

data/lib/ses_dashboard/client.rb

@@ -42,9 +42,9 @@ module SesDashboard
     # Options: from:, to:, subject:, body:, configuration_set: (optional)
     def send_email(from:, to:, subject:, body:, configuration_set: nil)
       params = {
-        source:       from,
-        destinations: [to],
-        message:      {
+        source:      from,
+        destination: { to_addresses: [to] },
+        message:     {
           subject: { data: subject, charset: "UTF-8" },
           body:    { text: { data: body, charset: "UTF-8" } }
         }

data/lib/ses_dashboard/engine.rb

@@ -13,13 +13,6 @@ module SesDashboard
       g.helper false
     end
 
-    # Make engine migrations available to the host app via `rails ses_dashboard:install:migrations`
-    initializer "ses_dashboard.add_migrations" do |app|
-      unless app.root.to_s == root.to_s
-        config.paths["db/migrate"].to_a.each { |path| app.config.paths["db/migrate"] << path }
-      end
-    end
-
     # Precompile engine assets
     initializer "ses_dashboard.assets" do |app|
       if app.config.respond_to?(:assets)

data/lib/ses_dashboard/forward_rule.rb

@@ -0,0 +1,72 @@
+module SesDashboard
+  # Evaluates a single forwarding rule against a WebhookProcessor::Result.
+  #
+  # A rule is a Hash with three keys:
+  #   "field"    — which Result attribute to test
+  #   "operator" — how to compare
+  #   "value"    — what to compare against
+  #
+  # Supported fields:
+  #   "event_type"  — string  ("bounce", "delivery", "complaint", …)
+  #   "source"      — string  (From: address)
+  #   "destination" — array   (To: addresses — rule passes if ANY element matches)
+  #   "subject"     — string  (email subject)
+  #
+  # Supported operators:
+  #   "in"          — field value is included in the given array
+  #   "not_in"      — field value is NOT included in the given array
+  #   "eq"          — exact string equality
+  #   "not_eq"      — string inequality
+  #   "starts_with" — prefix match (for arrays: any element matches)
+  #   "ends_with"   — suffix match (for arrays: any element matches)
+  #   "contains"    — substring match (for arrays: any element matches)
+  #
+  # New fields/operators can be added by extending the private methods below.
+  #
+  class ForwardRule
+    def initialize(rule_hash)
+      @field    = (rule_hash["field"]    || rule_hash[:field]).to_s
+      @operator = (rule_hash["operator"] || rule_hash[:operator]).to_s
+      @value    = rule_hash["value"]     || rule_hash[:value]
+    end
+
+    def match?(result)
+      field_value = extract_field(result)
+      evaluate(field_value)
+    end
+
+    private
+
+    def extract_field(result)
+      case @field
+      when "event_type"  then result.event_type
+      when "source"      then result.source
+      when "destination" then result.destination
+      when "subject"     then result.subject
+      end
+    end
+
+    def evaluate(field_value)
+      case @operator
+      when "in"          then Array(@value).include?(field_value)
+      when "not_in"      then !Array(@value).include?(field_value)
+      when "eq"          then any_string_match(field_value) { |v| v == @value.to_s }
+      when "not_eq"      then !any_string_match(field_value) { |v| v == @value.to_s }
+      when "starts_with" then any_string_match(field_value) { |v| v.start_with?(@value.to_s) }
+      when "ends_with"   then any_string_match(field_value) { |v| v.end_with?(@value.to_s) }
+      when "contains"    then any_string_match(field_value) { |v| v.include?(@value.to_s) }
+      else false
+      end
+    end
+
+    # For array fields (e.g. destination), passes if ANY element matches.
+    # For scalar fields, tests the single value.
+    def any_string_match(field_value, &block)
+      if field_value.is_a?(Array)
+        field_value.any? { |v| block.call(v.to_s) }
+      else
+        block.call(field_value.to_s)
+      end
+    end
+  end
+end

data/lib/ses_dashboard/sns_signature_verifier.rb

@@ -0,0 +1,92 @@
+require "net/http"
+require "uri"
+require "openssl"
+require "base64"
+
+module SesDashboard
+  # Verifies the authenticity of an SNS HTTP POST using AWS's RSA signature.
+  #
+  # SNS signs messages with SHA1 (SignatureVersion "1") or SHA256
+  # (SignatureVersion "2") using a per-region X.509 certificate hosted at
+  # a amazonaws.com URL included in every message.
+  #
+  # Verification steps:
+  #   1. Validate the SigningCertURL is from amazonaws.com (prevents substitution attacks)
+  #   2. Fetch and parse the X.509 certificate
+  #   3. Reconstruct the canonical string-to-sign
+  #   4. Verify the Signature against the cert's public key
+  #
+  class SnsSignatureVerifier
+    # Only trust certs hosted on Amazon's own infrastructure.
+    CERT_URL_PATTERN = %r{\Ahttps://sns\.[a-z0-9\-]+\.amazonaws\.com/}.freeze
+
+    class VerificationError < SesDashboard::Error; end
+
+    def initialize(sns_message)
+      @msg = sns_message
+    end
+
+    # Returns true if valid, raises VerificationError if not.
+    def verify!
+      validate_cert_url!
+      cert   = fetch_cert
+      digest = signature_version == "2" ? OpenSSL::Digest::SHA256.new : OpenSSL::Digest::SHA1.new
+
+      unless cert.public_key.verify(digest, decoded_signature, string_to_sign)
+        raise VerificationError, "SNS signature verification failed"
+      end
+
+      true
+    end
+
+    private
+
+    def signature_version
+      @msg["SignatureVersion"] || "1"
+    end
+
+    def validate_cert_url!
+      url = @msg["SigningCertURL"].to_s
+      unless url.match?(CERT_URL_PATTERN)
+        raise VerificationError, "Invalid SigningCertURL: #{url.inspect}"
+      end
+    end
+
+    def fetch_cert
+      url  = URI(@msg["SigningCertURL"])
+      pem  = Net::HTTP.get(url)
+      OpenSSL::X509::Certificate.new(pem)
+    rescue => e
+      raise VerificationError, "Failed to fetch signing certificate: #{e.message}"
+    end
+
+    def decoded_signature
+      Base64.decode64(@msg["Signature"].to_s)
+    end
+
+    # AWS canonical string-to-sign — field order is fixed per message type.
+    # https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message.html
+    def string_to_sign
+      fields = case @msg["Type"]
+               when "Notification"
+                 notification_fields
+               when "SubscriptionConfirmation", "UnsubscribeConfirmation"
+                 subscription_fields
+               else
+                 raise VerificationError, "Unknown SNS message type: #{@msg["Type"].inspect}"
+               end
+
+      fields.map { |key| "#{key}\n#{@msg[key]}\n" }.join
+    end
+
+    def notification_fields
+      fields = %w[Message MessageId Subject Timestamp TopicArn Type]
+      # Subject is optional — omit if absent (AWS does the same)
+      @msg["Subject"] ? fields : fields - ["Subject"]
+    end
+
+    def subscription_fields
+      %w[Message MessageId SubscribeURL Timestamp Token TopicArn Type]
+    end
+  end
+end

data/lib/ses_dashboard/version.rb

@@ -1,3 +1,3 @@
 module SesDashboard
-  VERSION = "0.1.0"
+  VERSION = "0.5.0"
 end

data/lib/ses_dashboard/webhook_forwarder.rb

@@ -0,0 +1,105 @@
+require "net/http"
+require "uri"
+require "json"
+
+module SesDashboard
+  # Forwards processed SES events to external webhook URLs based on configurable rules.
+  #
+  # Rules are resolved per-project (see Project#effective_webhook_forwards), with a
+  # global fallback from SesDashboard.configuration.webhook_forwards.
+  #
+  # Each forward entry supports a `rules` array — all rules must match (AND logic).
+  # If no rules are specified, every event is forwarded.
+  #
+  #   [
+  #     {
+  #       "url": "https://hooks.zapier.com/hooks/catch/abc/xyz/",
+  #       "rules": [
+  #         { "field": "event_type", "operator": "in", "value": ["bounce", "complaint"] },
+  #         { "field": "source",     "operator": "ends_with", "value": "@myapp.com" }
+  #       ]
+  #     }
+  #   ]
+  #
+  # Legacy shorthand `event_types` is still supported and auto-converted to a rule:
+  #   { "url": "...", "event_types": ["bounce"] }
+  #   ⟶ rules: [{ field: "event_type", operator: "in", value: ["bounce"] }]
+  #
+  class WebhookForwarder
+    OPEN_TIMEOUT = 5  # seconds
+    READ_TIMEOUT = 10 # seconds
+
+    def initialize(project, result)
+      @project = project
+      @result  = result
+    end
+
+    def forward
+      forwards = @project.effective_webhook_forwards
+      return if forwards.empty?
+
+      forwards.each do |config|
+        url = config[:url] || config["url"]
+        next if url.blank?
+        next unless matches_rules?(config)
+
+        post_to(url)
+      rescue => e
+        log_warn("Forward to #{url} failed: #{e.message}")
+      end
+    end
+
+    private
+
+    def matches_rules?(config)
+      rules = resolve_rules(config)
+      return true if rules.empty?
+
+      rules.all? { |rule| ForwardRule.new(rule).match?(@result) }
+    end
+
+    # Supports both the new `rules` format and the legacy `event_types` shorthand.
+    def resolve_rules(config)
+      rules = Array(config["rules"] || config[:rules])
+      return rules if rules.any?
+
+      event_types = Array(config["event_types"] || config[:event_types])
+      return [] if event_types.empty?
+
+      [{ "field" => "event_type", "operator" => "in", "value" => event_types }]
+    end
+
+    def post_to(url)
+      uri  = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+
+      req                  = Net::HTTP::Post.new(uri.request_uri)
+      req["Content-Type"]  = "application/json"
+      req.body             = build_payload
+
+      response = http.request(req)
+      unless response.is_a?(Net::HTTPSuccess)
+        log_warn("Forward to #{url} returned HTTP #{response.code}")
+      end
+    end
+
+    def build_payload
+      {
+        event_type:  @result.event_type,
+        message_id:  @result.message_id,
+        source:      @result.source,
+        destination: @result.destination,
+        subject:     @result.subject,
+        occurred_at: @result.occurred_at&.iso8601,
+        raw:         @result.raw_payload
+      }.to_json
+    end
+
+    def log_warn(msg)
+      Rails.logger.warn("[SesDashboard] #{msg}") if defined?(Rails)
+    end
+  end
+end

data/lib/ses_dashboard/webhook_processor.rb

@@ -42,7 +42,9 @@ module SesDashboard
       when "Notification"
         process_notification(sns)
       else
-        unknown_result
+        # SNS raw message delivery — the body is the SES event payload directly,
+        # with no SNS envelope. Treat it as a notification message directly.
+        process_raw_ses_event(sns)
       end
     rescue => e
       Rails.logger.error("[SesDashboard] WebhookProcessor error: #{e.message}") if defined?(Rails)
@@ -55,6 +57,16 @@ module SesDashboard
       message = parse_json(sns["Message"])
       return unknown_result unless message
 
+      process_ses_message(message, sns["Timestamp"])
+    end
+
+    # SNS raw message delivery — body is the SES event directly, no envelope.
+    def process_raw_ses_event(message)
+      process_ses_message(message, nil)
+    end
+
+    def process_ses_message(message, sns_timestamp)
+
       # SES supports two notification formats:
       # - Event Publishing (newer): uses "eventType" key
       # - Feedback Notifications (legacy): uses "notificationType" key
@@ -62,7 +74,7 @@ module SesDashboard
       event_type = normalize_event_type(raw_event_type)
 
       mail      = message["mail"] || {}
-      timestamp = parse_time(mail["timestamp"] || sns["Timestamp"])
+      timestamp = parse_time(mail["timestamp"] || sns_timestamp)
 
       Result.new(
         action:      :process_event,

data/lib/ses_dashboard.rb

@@ -1,12 +1,3 @@
-require_relative "ses_dashboard/version"
-require_relative "ses_dashboard/client"
-require_relative "ses_dashboard/webhook_processor"
-require_relative "ses_dashboard/stats_aggregator"
-require_relative "ses_dashboard/paginatable"
-require_relative "ses_dashboard/auth/base"
-require_relative "ses_dashboard/auth/devise_adapter"
-require_relative "ses_dashboard/auth/cloudflare_adapter"
-
 module SesDashboard
   class Error < StandardError; end
 
@@ -46,6 +37,15 @@ module SesDashboard
     attr_accessor :cloudflare_team_domain  # e.g. "myteam.cloudflareaccess.com"
     attr_accessor :cloudflare_aud          # JWT audience (your CF application AUD)
 
+    # Webhook forwarding — forward specific event types to external URLs (e.g. Zapier)
+    # Format: array of hashes with :url and :event_types keys
+    # Example:
+    #   c.webhook_forwards = [
+    #     { url: "https://hooks.zapier.com/...", event_types: ["bounce", "complaint"] }
+    #   ]
+    # Omit :event_types (or set to []) to forward all event types.
+    attr_accessor :webhook_forwards
+
     def initialize
       @aws_region              = ENV.fetch("AWS_REGION", "us-east-1")
       @aws_access_key_id       = nil
@@ -59,8 +59,20 @@ module SesDashboard
       @verify_sns_signature    = false
       @cloudflare_team_domain  = nil
       @cloudflare_aud          = nil
+      @webhook_forwards        = []
     end
   end
-
-  autoload :Engine, "ses_dashboard/engine"
 end
+
+require_relative "ses_dashboard/version"
+require_relative "ses_dashboard/client"
+require_relative "ses_dashboard/webhook_processor"
+require_relative "ses_dashboard/forward_rule"
+require_relative "ses_dashboard/webhook_forwarder"
+require_relative "ses_dashboard/sns_signature_verifier"
+require_relative "ses_dashboard/stats_aggregator"
+require_relative "ses_dashboard/paginatable"
+require_relative "ses_dashboard/auth/base"
+require_relative "ses_dashboard/auth/devise_adapter"
+require_relative "ses_dashboard/auth/cloudflare_adapter"
+require "ses_dashboard/engine"