ses-dashboard 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7165bdb98b1bf82aa3b6a65e7346101bc9792eb81e7b81fd8c1c9128865697f
-  data.tar.gz: 520bc27a98c191b442b307bb7878cc4566883d2567db36373ea62396e867748b
+  metadata.gz: 58342ca28ca9d49b31764e988689df488d9a43061fdb145ded04a7d2dbb038b6
+  data.tar.gz: da07fcf3d2549fc68bdf24aceb72d289e3a8bf5d93238cd807932b71ef4d7cec
 SHA512:
-  metadata.gz: c77bbac1e82db66182c2bd4141d8ab66ea9e9fb267dc0f33b0a082add3af7bf5ed72bdfb7c6bb2dd772d5db4ae19db61b120681d8f6d8001816ed90dbb8f7dfc
-  data.tar.gz: 8e3f511a3be5108a96247ff6fb42cfa05aed17003637f9d43c92863b6629a653cfd71ce74f5606952750a0655018fbfb01c8d06eedfd8f89cfdd6dce7f2b12d9
+  metadata.gz: 8757e8e5024c11d93826bdb890e46dcf6fef0bac259d43da0dbec7bd64e16f07765b01967a2d7b5bbfa75de2d11f9bf193b1949f81c937b2e450fba6b2c13092
+  data.tar.gz: b222f9246a72fd94869c85e316a69668519536e8fc973e205036ce64ea92c02dd233a6268f889dde3a871759478a1a915e6379e4bed36845c41409acf5c2d208

data/README.md

@@ -1,7 +1,44 @@
 # SES Dashboard
+[![codecov](https://codecov.io/gh/antodoms/ses_dashboard/graph/badge.svg?token=0SSO12E12W)](https://codecov.io/gh/antodoms/ses_dashboard)
+[![Gem Version](https://badge.fury.io/rb/ses-dashboard.svg)](https://badge.fury.io/rb/ses-dashboard)
 
 A mountable Rails engine that provides a real-time dashboard for Amazon SES, tracking email delivery, bounces, complaints, opens, and clicks via SNS webhooks.
 
+## Screenshots
+
+![Combined Dashboard](docs/screenshots/combined-projects-dashboard.png)
+
+<table>
+  <tr>
+    <td><img src="docs/screenshots/project-dashboard-view-page.png" alt="Project Dashboard" /></td>
+    <td><img src="docs/screenshots/project-activity-page.png" alt="Activity Log" /></td>
+  </tr>
+  <tr>
+    <td align="center"><em>Per-project stats &amp; email volume chart</em></td>
+    <td align="center"><em>Paginated activity log with search &amp; export</em></td>
+  </tr>
+  <tr>
+    <td colspan="2"><img src="docs/screenshots/email-details.png" alt="Email Detail" /></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center"><em>Email detail with full SNS event timeline</em></td>
+  </tr>
+</table>
+
+## Features
+
+- **Real-time webhook processing** -- receives SNS notifications for delivery, bounce, complaint, open, click, reject, and rendering failure events
+- **Per-project dashboards** -- stat cards, email volume charts (Chart.js), and paginated activity logs
+- **Pluggable authentication** -- ships with Devise, Cloudflare Zero Trust, and no-auth adapters; bring your own with any object that responds to `#authenticate(request)`
+- **CSV/JSON export** -- export filtered email activity from any project
+- **Test email sending** -- send test emails directly from the dashboard via the SES API
+- **Status state machine** -- unidirectional email status transitions (sent -> delivered/bounced/etc.)
+- **SNS signature verification** -- validates RSA signatures (SHA1 and SHA256) on incoming SNS messages
+- **Database agnostic** -- works with SQLite, PostgreSQL, and MySQL
+- **Lightweight pagination** -- no external pagination gem required
+
+## Architecture
+
 ```mermaid
 graph TB
     subgraph Host["Host Rails App"]
@@ -29,6 +66,7 @@ graph TB
         subgraph Core["Core Library (lib/)"]
             Client["Client<br/>AWS SES SDK wrapper"]
             WP["WebhookProcessor<br/>SNS message parser"]
+            SV["SnsSignatureVerifier"]
             SA["StatsAggregator<br/>Dashboard statistics"]
             Pag["Paginatable"]
         end
@@ -54,7 +92,8 @@ graph TB
     DC --> SA
     EC --> Pag
     TC --> Client
-    WC -->|"POST /webhook/:token"| WP
+    WC -->|"POST /webhook/:token"| SV
+    SV --> WP
     WP --> WEP
     WEP --> Models
     Client --> SES
@@ -68,31 +107,22 @@ graph TB
     style Host fill:#e8f5e9,stroke:#4caf50
 ```
 
-## Features
-
-- **Real-time webhook processing** -- receives SNS notifications for delivery, bounce, complaint, open, click, reject, and rendering failure events
-- **Per-project dashboards** -- stat cards, email volume charts (Chart.js), and paginated activity logs
-- **Pluggable authentication** -- ships with Devise, Cloudflare Zero Trust, and no-auth adapters; bring your own with any object that responds to `#authenticate(request)`
-- **CSV/JSON export** -- export filtered email activity from any project
-- **Test email sending** -- send test emails directly from the dashboard via the SES API
-- **Status state machine** -- unidirectional email status transitions (sent -> delivered/bounced/etc.)
-- **Database agnostic** -- works with SQLite, PostgreSQL, and MySQL
-- **Lightweight pagination** -- no external pagination gem required
-
 ## Installation
 
 Add the gem to your Gemfile:
 
 ```ruby
-gem "ses_dashboard"
+gem "ses-dashboard"
 ```
 
+The gem name uses a hyphen (`ses-dashboard`) — Bundler will auto-require the correct entry point automatically.
+
 Then run:
 
 ```bash
 bundle install
-rails ses_dashboard:install:migrations
-rails db:migrate
+bin/rails railties:install:migrations
+bin/rails db:migrate
 ```
 
 ## Mounting
@@ -128,8 +158,8 @@ SesDashboard.configure do |c|
   c.cloudflare_aud         = "your-application-aud"
 
   # Dashboard behaviour
-  c.per_page       = 25     # rows per page in the activity log
-  c.time_zone      = "UTC"  # timezone for chart date grouping
+  c.per_page        = 25     # rows per page in the activity log
+  c.time_zone       = "UTC"  # timezone for chart date grouping
   c.test_email_from = "noreply@example.com"
 
   # Caching & security
@@ -144,24 +174,55 @@ Every controller action (except the webhook endpoint) runs through the configure
 
 | Adapter | Value | Notes |
 |---|---|---|
-| None | `:none` | Open access -- suitable for development |
+| None | `:none` | Open access — suitable for development |
 | Devise | `:devise` | Calls `authenticate_user!` via Warden |
 | Cloudflare Zero Trust | `:cloudflare` | Validates `CF_Authorization` JWT against JWKS |
 | Custom | any object | Must respond to `#authenticate(request)` returning truthy/falsy |
 
+### Custom adapter
+
+Use a custom adapter when your app has its own authentication system (e.g. custom session-based auth, API keys, JWT):
+
 ```ruby
-# Example custom adapter
-class ApiKeyAuth
+# config/initializers/ses_dashboard.rb
+
+my_auth = Class.new(SesDashboard::Auth::Base) do
   def authenticate(request)
-    request.headers["X-Api-Key"] == Rails.application.credentials.dashboard_key
+    session = request.session
+    # your auth logic here — return truthy to allow, falsy to deny
+    session[:user_id].present?
   end
 end
 
 SesDashboard.configure do |c|
-  c.authentication_adapter = ApiKeyAuth.new
+  c.authentication_adapter = my_auth.new
 end
 ```
 
+For apps with session timeout and whitelist checks (e.g. custom Rails session auth):
+
+```ruby
+my_auth = Class.new(SesDashboard::Auth::Base) do
+  def authenticate(request)
+    session = request.session
+    user_id      = session[:user_id]
+    logged_in_at = session[:logged_in_at]
+
+    return false unless user_id && logged_in_at
+    return false unless logged_in_at > 12.hours.ago
+
+    user = User.find_by(id: user_id)
+    user&.active? || false
+  end
+end
+
+SesDashboard.configure do |c|
+  c.authentication_adapter = my_auth.new
+end
+```
+
+The adapter is defined inline using `Class.new` so it is available at initializer load time without depending on Zeitwerk autoloading.
+
 ## SNS Webhook Setup
 
 Each project gets a unique webhook URL displayed on its dashboard page:
@@ -178,17 +239,17 @@ To connect it to SES:
 
 The webhook endpoint authenticates via the project token in the URL and does not require a session.
 
-## Database Schema
+### SNS Signature Verification
 
-The engine creates three tables (prefixed `ses_dashboard_`):
+When `verify_sns_signature = true`, the engine validates the RSA signature on every incoming SNS message before processing it. Both `SignatureVersion` `"1"` (SHA1) and `"2"` (SHA256) are supported.
 
-| Table | Key Columns |
-|---|---|
-| `ses_dashboard_projects` | `name`, `token` (unique, auto-generated), `description` |
-| `ses_dashboard_emails` | `project_id`, `message_id` (unique), `source`, `destination` (JSON), `subject`, `status`, `opens`, `clicks`, `sent_at` |
-| `ses_dashboard_email_events` | `email_id`, `event_type`, `event_data` (JSON), `occurred_at` |
+For **raw message delivery** (SNS subscription setting), signature verification is automatically skipped as SNS does not include signature fields in raw payloads — the project token in the URL provides authentication instead.
 
-Email statuses: `sent`, `delivered`, `bounced`, `complained`, `rejected`, `failed`.
+Enable in production:
+
+```ruby
+c.verify_sns_signature = Rails.env.production?
+```
 
 ## Development
 
@@ -226,13 +287,27 @@ bundle exec rspec spec/models/ses_dashboard/email_spec.rb:15
 | Service | Purpose | Ports |
 |---|---|---|
 | `localstack` | Local AWS (SES + SNS) | 4566 |
-| `chrome` | Selenium standalone Chromium | 4444 (WebDriver), 7900 (noVNC -- watch tests live) |
+| `chrome` | Selenium standalone Chromium | 4444 (WebDriver), 7900 (noVNC — watch tests live) |
 | `web` | Runs the test suite | 4001 (Puma) |
 
 ### Watching System Tests
 
 Open http://localhost:7900 in your browser (no password) to watch Chrome execute system specs in real time via noVNC.
 
+## Database Schema
+
+The engine creates three tables (prefixed `ses_dashboard_`):
+
+| Table | Key Columns |
+|---|---|
+| `ses_dashboard_projects` | `name`, `token` (unique, auto-generated), `description` |
+| `ses_dashboard_emails` | `project_id`, `message_id` (unique), `source`, `destination` (JSON), `subject`, `status`, `opens`, `clicks`, `sent_at` |
+| `ses_dashboard_email_events` | `email_id`, `event_type`, `event_data` (JSON), `occurred_at` |
+
+Email statuses: `sent`, `delivered`, `bounced`, `complained`, `rejected`, `failed`.
+
+Migrations are compatible with Rails 7.x and 8.x — the migration version is resolved automatically from the host app's Rails version at install time.
+
 ## License
 
 MIT

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
 
@@ -23,6 +27,9 @@ module SesDashboard
       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 +42,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/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/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/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.4.0"
 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
 
@@ -61,6 +52,15 @@ module SesDashboard
       @cloudflare_aud          = nil
     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/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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ses-dashboard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - antodoms
@@ -332,6 +332,7 @@ files:
 - db/migrate/20240101000002_create_ses_dashboard_emails.rb
 - db/migrate/20240101000003_create_ses_dashboard_email_events.rb
 - docker-compose.yml
+- lib/ses/dashboard.rb
 - lib/ses_dashboard.rb
 - lib/ses_dashboard/auth/base.rb
 - lib/ses_dashboard/auth/cloudflare_adapter.rb
@@ -339,6 +340,7 @@ files:
 - lib/ses_dashboard/client.rb
 - lib/ses_dashboard/engine.rb
 - lib/ses_dashboard/paginatable.rb
+- lib/ses_dashboard/sns_signature_verifier.rb
 - lib/ses_dashboard/stats_aggregator.rb
 - lib/ses_dashboard/version.rb
 - lib/ses_dashboard/webhook_processor.rb