ses-dashboard 0.1.0

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

@@ -0,0 +1,24 @@
+<%= form_with model: project, url: (project.persisted? ? project_path(project) : projects_path), local: true do |f| %>
+  <% if project.errors.any? %>
+    <div class="flash flash-alert">
+      <ul style="margin:0;padding-left:1rem;">
+        <% project.errors.full_messages.each do |msg| %>
+          <li><%= msg %></li>
+        <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="form-group">
+    <%= f.label :name, class: "form-label" %>
+    <%= f.text_field :name, class: "form-control", placeholder: "My Rails App" %>
+  </div>
+
+  <div class="form-group">
+    <%= f.label :description, class: "form-label" %>
+    <%= f.text_area :description, class: "form-control", placeholder: "Optional description" %>
+  </div>
+
+  <%= f.submit class: "btn btn-primary" %>
+  <%= link_to "Cancel", projects_path, class: "btn btn-outline" %>
+<% end %>

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

@@ -0,0 +1,6 @@
+<div class="page-header">
+  <h1 class="page-title">Edit Project</h1>
+</div>
+<div class="card" style="max-width:560px;">
+  <%= render "ses_dashboard/projects/form", project: @project %>
+</div>

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

@@ -0,0 +1,42 @@
+<div class="page-header">
+  <h1 class="page-title">Projects</h1>
+  <%= link_to "New project", new_project_path, class: "btn btn-primary btn-sm" %>
+</div>
+
+<div class="table-wrapper">
+  <table>
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Token</th>
+        <th>Emails</th>
+        <th>Actions</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @projects.each do |project| %>
+        <tr>
+          <td><%= link_to project.name, project_path(project) %></td>
+          <td>
+            <span class="token-display"><%= project.token[0..7] %>&hellip;</span>
+            <button class="btn btn-sm btn-outline" data-copy="<%= project.token %>">Copy token</button>
+          </td>
+          <td><%= number_with_delimiter(project.emails.count) %></td>
+          <td style="display:flex;gap:.4rem;">
+            <%= link_to "View",   project_path(project),      class: "btn btn-sm btn-outline" %>
+            <%= link_to "Edit",   edit_project_path(project), class: "btn btn-sm btn-outline" %>
+            <%= link_to "Delete", project_path(project),
+                  method: :delete,
+                  data: { confirm: "Delete project '#{project.name}' and all its emails?" },
+                  class: "btn btn-sm btn-danger" %>
+          </td>
+        </tr>
+      <% end %>
+      <% if @projects.empty? %>
+        <tr><td colspan="4" style="color:var(--color-text-muted);text-align:center;padding:2rem;">
+          No projects yet. <%= link_to "Create one", new_project_path %>.
+        </td></tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

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

@@ -0,0 +1,6 @@
+<div class="page-header">
+  <h1 class="page-title">New Project</h1>
+</div>
+<div class="card" style="max-width:560px;">
+  <%= render "ses_dashboard/projects/form", project: @project %>
+</div>

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

@@ -0,0 +1,47 @@
+<div class="page-header">
+  <h1 class="page-title"><%= @project.name %></h1>
+  <div style="display:flex;gap:.5rem;">
+    <%= link_to "Edit",          edit_project_path(@project),         class: "btn btn-outline btn-sm" %>
+    <%= link_to "Activity log",  project_emails_path(@project),       class: "btn btn-outline btn-sm" %>
+    <%= link_to "Send test email", new_project_test_email_path(@project), class: "btn btn-primary btn-sm" %>
+  </div>
+</div>
+
+<% if @project.description.present? %>
+  <p style="color:var(--color-text-muted);margin-bottom:1rem;"><%= @project.description %></p>
+<% end %>
+
+<%# SNS Webhook URL %>
+<div class="card" style="margin-bottom:1.5rem;">
+  <div class="card-title">SNS Webhook URL</div>
+  <p style="font-size:.8125rem;color:var(--color-text-muted);margin:.25rem 0 .75rem;">
+    Configure this URL as an SNS topic subscription endpoint (HTTPS) in your AWS console.
+  </p>
+  <div class="webhook-url-wrap">
+    <% url = webhook_url_for(@project) %>
+    <input type="text" class="form-control webhook-url-input" value="<%= url %>" readonly>
+    <button class="btn btn-outline btn-sm" data-copy="<%= url %>">Copy</button>
+  </div>
+</div>
+
+<%# Date range picker %>
+<form method="get" style="display:flex;gap:.5rem;align-items:center;margin-bottom:1rem;">
+  <input type="date" name="from" class="form-control" value="<%= @from.to_date %>" style="width:auto;">
+  <span>to</span>
+  <input type="date" name="to"   class="form-control" value="<%= @to.to_date   %>" style="width:auto;">
+  <button type="submit" class="btn btn-outline btn-sm">Apply</button>
+</form>
+
+<div class="stat-grid">
+  <%= render "ses_dashboard/shared/stat_card", label: "Sent",          value: @counters[:total],         color: "var(--color-text)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Delivered",     value: @counters[:delivered],     color: "var(--color-delivered)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Opens",         value: @total_opens,              color: "var(--color-primary)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Clicks",        value: @total_clicks,             color: "var(--color-primary)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Not Delivered", value: @counters[:not_delivered], color: "var(--color-bounced)" %>
+</div>
+
+<div class="card chart-card">
+  <div class="card-title">Email volume (by day)</div>
+  <canvas id="activity-chart"></canvas>
+</div>
+<%= chart_data_tag(@chart_data) %>

data/app/views/ses_dashboard/shared/_flash.html.erb

@@ -0,0 +1,3 @@
+<% flash.each do |type, message| %>
+  <div class="flash flash-<%= type %>"><%= message %></div>
+<% end %>

data/app/views/ses_dashboard/shared/_pagination.html.erb

@@ -0,0 +1,15 @@
+<% if pagination[:total_pages] > 1 %>
+  <div class="pagination">
+    <%= pagination_link("&laquo; Prev".html_safe, pagination[:prev_page]) %>
+    <span class="pagination-info">
+      Page <%= pagination[:page] %> of <%= pagination[:total_pages] %>
+      &nbsp;&middot;&nbsp;
+      <%= number_with_delimiter(pagination[:total_count]) %> total
+    </span>
+    <%= pagination_link("Next &raquo;".html_safe, pagination[:next_page]) %>
+  </div>
+<% else %>
+  <div class="pagination">
+    <span class="pagination-info"><%= number_with_delimiter(pagination[:total_count]) %> records</span>
+  </div>
+<% end %>

data/app/views/ses_dashboard/shared/_stat_card.html.erb

@@ -0,0 +1,4 @@
+<div class="card">
+  <div class="card-title"><%= label %></div>
+  <div class="card-value" style="color: <%= color %>"><%= number_with_delimiter(value) %></div>
+</div>

data/app/views/ses_dashboard/test_emails/new.html.erb

@@ -0,0 +1,38 @@
+<div class="page-header">
+  <h1 class="page-title">Send test email — <%= @project.name %></h1>
+  <%= link_to "&larr; Back".html_safe, project_path(@project), class: "btn btn-outline btn-sm" %>
+</div>
+
+<div class="card" style="max-width:560px;">
+  <% if flash[:alert] %>
+    <div class="flash flash-alert"><%= flash[:alert] %></div>
+  <% end %>
+
+  <%= form_with url: project_test_email_path(@project), method: :post, local: true do |f| %>
+    <div class="form-group">
+      <label class="form-label" for="from">From</label>
+      <input type="email" name="from" id="from" class="form-control"
+             value="<%= @from %>"
+             placeholder="sender@yourdomain.com" required>
+    </div>
+
+    <div class="form-group">
+      <label class="form-label" for="to">To</label>
+      <input type="email" name="to" id="to" class="form-control"
+             placeholder="recipient@example.com" required>
+    </div>
+
+    <div class="form-group">
+      <label class="form-label" for="subject">Subject</label>
+      <input type="text" name="subject" id="subject" class="form-control"
+             value="Test email from SES Dashboard">
+    </div>
+
+    <div class="form-group">
+      <label class="form-label" for="body">Body</label>
+      <textarea name="body" id="body" class="form-control">This is a test email sent from SES Dashboard.</textarea>
+    </div>
+
+    <button type="submit" class="btn btn-primary">Send email</button>
+  <% end %>
+</div>

data/config/routes.rb

@@ -0,0 +1,16 @@
+SesDashboard::Engine.routes.draw do
+  root to: "dashboard#index"
+
+  resources :projects do
+    resources :emails, only: [:index, :show] do
+      collection do
+        get :export
+      end
+    end
+    resource :test_email, only: [:new, :create]
+  end
+
+  # SNS posts to this endpoint; authenticated by the project token in the URL,
+  # not by the session-based auth applied to all other routes.
+  post "webhook/:project_token", to: "webhooks#create", as: :webhook
+end

data/db/migrate/20240101000001_create_ses_dashboard_projects.rb

@@ -0,0 +1,13 @@
+class CreateSesDashboardProjects < ActiveRecord::Migration[8.0]
+  def change
+    create_table :ses_dashboard_projects do |t|
+      t.string :name,        null: false
+      t.string :token,       null: false
+      t.text   :description
+
+      t.timestamps
+    end
+
+    add_index :ses_dashboard_projects, :token, unique: true
+  end
+end

data/db/migrate/20240101000002_create_ses_dashboard_emails.rb

@@ -0,0 +1,21 @@
+class CreateSesDashboardEmails < ActiveRecord::Migration[8.0]
+  def change
+    create_table :ses_dashboard_emails do |t|
+      t.references :project,    null: false, foreign_key: { to_table: :ses_dashboard_projects }
+      t.string     :message_id, null: false
+      t.text       :destination, null: false  # JSON-serialized array of recipient addresses
+      t.string     :source,      null: false  # From: address
+      t.string     :subject
+      t.string     :status,      null: false, default: "sent"
+      t.integer    :opens,       null: false, default: 0
+      t.integer    :clicks,      null: false, default: 0
+      t.datetime   :sent_at
+
+      t.timestamps
+    end
+
+    add_index :ses_dashboard_emails, :message_id, unique: true
+    add_index :ses_dashboard_emails, :status
+    add_index :ses_dashboard_emails, [:project_id, :sent_at]
+  end
+end

data/db/migrate/20240101000003_create_ses_dashboard_email_events.rb

@@ -0,0 +1,15 @@
+class CreateSesDashboardEmailEvents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :ses_dashboard_email_events do |t|
+      t.references :email,      null: false, foreign_key: { to_table: :ses_dashboard_emails }
+      t.string     :event_type, null: false
+      t.text       :event_data               # JSON blob of the full SNS notification payload
+      t.datetime   :occurred_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :ses_dashboard_email_events, [:email_id, :event_type]
+    add_index :ses_dashboard_email_events, :occurred_at
+  end
+end

data/docker-compose.yml

@@ -0,0 +1,45 @@
+services:
+  localstack:
+    image: localstack/localstack:3
+    ports:
+      - "4566:4566"
+    environment:
+      - SERVICES=ses,sns
+      - DEBUG=1
+      - AWS_ACCESS_KEY_ID=test
+      - AWS_SECRET_ACCESS_KEY=test
+      - AWS_DEFAULT_REGION=us-east-1
+    volumes:
+      - "./localstack:/var/lib/localstack"
+
+  chrome:
+    image: selenium/standalone-chromium:latest
+    ports:
+      - "4444:4444"   # Selenium WebDriver
+      - "7900:7900"   # noVNC — open http://localhost:7900 (no password) to watch tests live
+    shm_size: "2g"    # prevents Chrome tab crashes under load
+    environment:
+      - JAVA_OPTS=-Dwebdriver.chrome.whitelistedIps=
+      - SE_VNC_NO_PASSWORD=1
+
+  web:
+    build: .
+    command: bundle exec rspec
+    ports:
+      - "4001:4001"   # Puma server
+    depends_on:
+      - localstack
+      - chrome
+    volumes:
+      - .:/usr/src/app
+      - bundle:/usr/local/bundle
+    environment:
+      - AWS_ENDPOINT_URL=http://localstack:4566
+      - AWS_ACCESS_KEY_ID=test
+      - AWS_SECRET_ACCESS_KEY=test
+      - AWS_DEFAULT_REGION=us-east-1
+      - AWS_REGION=us-east-1
+      - SELENIUM_REMOTE_URL=http://chrome:4444/wd/hub
+
+volumes:
+  bundle:

data/lib/ses_dashboard/auth/base.rb

@@ -0,0 +1,31 @@
+require "rack"
+require "json"
+
+module SesDashboard
+  module Auth
+    class Base
+      def initialize(app = nil)
+        @app = app
+      end
+
+      def authenticate(request = nil)
+        raise NotImplementedError, "Auth adapter must implement authenticate(request)"
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        if authenticate(request)
+          @app.call(env)
+        else
+          unauthorized_response
+        end
+      end
+
+      private
+
+      def unauthorized_response
+        [401, { "Content-Type" => "application/json" }, [{ error: "Unauthorized" }.to_json]]
+      end
+    end
+  end
+end

data/lib/ses_dashboard/auth/cloudflare_adapter.rb

@@ -0,0 +1,106 @@
+require "net/http"
+require "uri"
+require "base64"
+require "openssl"
+require "json"
+
+module SesDashboard
+  module Auth
+    # Validates Cloudflare Zero Trust JWT tokens.
+    #
+    # Configure in your initializer:
+    #   SesDashboard.configure do |c|
+    #     c.authentication_adapter  = :cloudflare
+    #     c.cloudflare_team_domain  = "myteam.cloudflareaccess.com"
+    #     c.cloudflare_aud          = "your-application-audience-tag"
+    #   end
+    #
+    class CloudflareAdapter < Base
+      JWKS_CACHE_TTL = 600 # seconds
+
+      def authenticate(request = nil)
+        return false unless request
+        token = extract_token(request)
+        return false unless token
+
+        payload = validate_jwt(token)
+        return false unless payload
+
+        config = SesDashboard.configuration
+        return false if config.cloudflare_aud && payload["aud"] != [config.cloudflare_aud]
+
+        true
+      rescue => e
+        log_error("Cloudflare JWT validation failed: #{e.message}")
+        false
+      end
+
+      private
+
+      def extract_token(request)
+        # Cloudflare sets this cookie and/or header
+        request.cookies["CF_Authorization"] ||
+          request.get_header("HTTP_CF_ACCESS_JWT_ASSERTION")
+      end
+
+      def validate_jwt(token)
+        header_b64, payload_b64, signature_b64 = token.split(".")
+        return nil unless header_b64 && payload_b64 && signature_b64
+
+        header  = JSON.parse(Base64.urlsafe_decode64(pad(header_b64)))
+        payload = JSON.parse(Base64.urlsafe_decode64(pad(payload_b64)))
+
+        return nil if payload["exp"].to_i < Time.now.to_i  # expired
+
+        kid = header["kid"]
+        key = fetch_public_key(kid)
+        return nil unless key
+
+        signing_input = "#{header_b64}.#{payload_b64}"
+        signature     = Base64.urlsafe_decode64(pad(signature_b64))
+
+        verified = key.verify(OpenSSL::Digest::SHA256.new, signature, signing_input)
+        verified ? payload : nil
+      end
+
+      def fetch_public_key(kid)
+        jwks = cached_jwks
+        jwk  = jwks["keys"]&.find { |k| k["kid"] == kid }
+        return nil unless jwk
+
+        # Build RSA public key from JWK n/e parameters
+        rsa = OpenSSL::PKey::RSA.new
+        n   = OpenSSL::BN.new(Base64.urlsafe_decode64(pad(jwk["n"])), 2)
+        e   = OpenSSL::BN.new(Base64.urlsafe_decode64(pad(jwk["e"])), 2)
+        rsa.set_key(n, e, nil)
+        rsa
+      rescue
+        nil
+      end
+
+      def cached_jwks
+        @jwks_fetched_at ||= 0
+        if Time.now.to_i - @jwks_fetched_at > JWKS_CACHE_TTL || @jwks_cache.nil?
+          @jwks_cache      = fetch_jwks
+          @jwks_fetched_at = Time.now.to_i
+        end
+        @jwks_cache
+      end
+
+      def fetch_jwks
+        team_domain = SesDashboard.configuration.cloudflare_team_domain
+        url = "https://#{team_domain}/cdn-cgi/access/certs"
+        response = Net::HTTP.get(URI(url))
+        JSON.parse(response)
+      end
+
+      def pad(str)
+        str + "=" * ((4 - str.length % 4) % 4)
+      end
+
+      def log_error(msg)
+        defined?(Rails) ? Rails.logger.warn("[SesDashboard] #{msg}") : nil
+      end
+    end
+  end
+end

data/lib/ses_dashboard/auth/devise_adapter.rb

@@ -0,0 +1,22 @@
+module SesDashboard
+  module Auth
+    class DeviseAdapter < Base
+      def initialize(app = nil, controller: nil)
+        super(app)
+        @controller = controller
+      end
+
+      def authenticate(request = nil)
+        return false unless controller
+        controller.authenticate_user!
+        !controller.current_user.nil?
+      rescue StandardError
+        false
+      end
+
+      private
+
+      attr_reader :controller
+    end
+  end
+end

data/lib/ses_dashboard/client.rb

@@ -0,0 +1,95 @@
+require "aws-sdk-ses"
+
+module SesDashboard
+  class Client
+    def initialize(options = {})
+      @options    = options.dup
+      @ses_client = build_ses_client
+      @cache      = {}
+    end
+
+    # ── SES monitoring API calls ─────────────────────────────────────────
+
+    def send_quota
+      cached(:send_quota) { ses_client.get_send_quota }
+    end
+
+    # Returns send data points from the last 14 days.
+    # The SES v1 API accepts no date parameters — it always returns the last 14 days.
+    def send_statistics
+      cached(:send_statistics) { ses_client.get_send_statistics }
+    end
+
+    def list_identities
+      cached(:identities) { ses_client.list_identities(types: ["EmailAddress", "Domain"]) }
+    end
+
+    def get_identity_verification_attributes(identities)
+      cached(:verification_attributes, identities.sort.join(",")) do
+        ses_client.get_identity_verification_attributes(identities: Array(identities))
+      end
+    end
+
+    def get_identity_dkim_attributes(identities)
+      cached(:dkim_attributes, identities.sort.join(",")) do
+        ses_client.get_identity_dkim_attributes(identities: Array(identities))
+      end
+    end
+
+    # ── Email sending ─────────────────────────────────────────────────────
+
+    # Sends a plain-text email via SES SendEmail API.
+    # Options: from:, to:, subject:, body:, configuration_set: (optional)
+    def send_email(from:, to:, subject:, body:, configuration_set: nil)
+      params = {
+        source:       from,
+        destinations: [to],
+        message:      {
+          subject: { data: subject, charset: "UTF-8" },
+          body:    { text: { data: body, charset: "UTF-8" } }
+        }
+      }
+      params[:configuration_set_name] = configuration_set if configuration_set
+      ses_client.send_email(params)
+    end
+
+    private
+
+    attr_reader :ses_client, :options
+
+    def build_ses_client
+      # Only set region and stub_responses by default; let the AWS SDK credential
+      # chain handle auth (SSO, IAM roles, instance profiles, env vars, etc.).
+      # Explicit credentials can be supplied via options or configuration for
+      # cases like CI where a static key pair is used.
+      params = {
+        region:        options[:region] || SesDashboard.configuration&.aws_region,
+        stub_responses: options.fetch(:stub_responses, false)
+      }
+
+      config      = SesDashboard.configuration
+      access_key  = options[:access_key_id]     || config&.aws_access_key_id
+      secret_key  = options[:secret_access_key] || config&.aws_secret_access_key
+      endpoint    = options[:endpoint]           || config&.endpoint
+
+      params[:access_key_id]     = access_key if access_key
+      params[:secret_access_key] = secret_key if secret_key
+      params[:endpoint]          = endpoint   if endpoint
+
+      Aws::SES::Client.new(params)
+    end
+
+    def cached(key, *context)
+      return yield unless enable_cache?
+
+      cache_key = [key, context].flatten.compact.join("-")
+      return @cache[cache_key] if @cache.key?(cache_key)
+
+      @cache[cache_key] = yield
+    end
+
+    def enable_cache?
+      options.fetch(:cache_enabled, SesDashboard.configuration&.cache_enabled != false)
+    end
+  end
+end

data/lib/ses_dashboard/engine.rb

@@ -0,0 +1,39 @@
+require "rails"
+require "active_record"
+require "action_controller"
+require "action_view"
+
+module SesDashboard
+  class Engine < ::Rails::Engine
+    isolate_namespace SesDashboard
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.assets false
+      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)
+        app.config.assets.precompile += %w[
+          ses_dashboard/application.css
+          ses_dashboard/application.js
+        ]
+      end
+    end
+
+    # Expose the engine's helpers to its own views
+    config.to_prepare do
+      SesDashboard::ApplicationController.helper(SesDashboard::ApplicationHelper) if
+        defined?(SesDashboard::ApplicationController)
+    end
+  end
+end

data/lib/ses_dashboard/paginatable.rb

@@ -0,0 +1,30 @@
+module SesDashboard
+  # Lightweight pagination that avoids requiring kaminari or will_paginate.
+  # Returns [records, pagination_info] where pagination_info is a Hash.
+  #
+  # Usage:
+  #   records, pagination = Paginatable.paginate(scope, page: 2, per_page: 25)
+  #
+  module Paginatable
+    def self.paginate(scope, page:, per_page: nil)
+      per_page    = (per_page || SesDashboard.configuration.per_page).to_i
+      page        = [page.to_i, 1].max
+      total_count = scope.count
+      total_pages = [(total_count.to_f / per_page).ceil, 1].max
+      page        = [page, total_pages].min
+
+      records = scope.offset((page - 1) * per_page).limit(per_page)
+
+      pagination = {
+        page:        page,
+        per_page:    per_page,
+        total_count: total_count,
+        total_pages: total_pages,
+        prev_page:   page > 1 ? page - 1 : nil,
+        next_page:   page < total_pages ? page + 1 : nil
+      }
+
+      [records, pagination]
+    end
+  end
+end