mail_dude 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4295c748cd2ec159f3c65a9934183b3e306d3cd9279b4c296e04e1735e561d9
+  data.tar.gz: fc04779985ad537dc15c46f574885accba01bf9936fdc49b017e477c38b330c1
+SHA512:
+  metadata.gz: 4644564f8c0f6a88f709c93715d6f0c74ed8eec7160f19b829896aab43aa3bc24aaad5f9b51dcd103da9ae26ed8138ecdd082a8090976e6495dfd0b214a7e6e1
+  data.tar.gz: 93fdd84bbaf8c540e4d270303490170fc074edbba00953486d95dcdaf4e2bc816e0dae13c0cf2b3071f1cf4c4d8f833f71297c96f621008368c819f43d2fcde3

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- Initial MailDude Rails engine implementation.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 MailDude contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,237 @@
+# MailDude
+
+MailDude is a mountable Rails engine and Ruby gem that captures Action Mailer deliveries in development, QA, and test-like environments. It registers an Action Mailer delivery method named `:mail_dude`, stores outgoing email instead of sending it externally, and exposes a mailbox UI for reviewing messages, headers, raw source, and attachments.
+
+## Why It Exists
+
+Local and QA applications often need realistic email delivery flows without risking real SMTP delivery to customers. MailDude captures the final `Mail::Message` through a delivery method, which prevents SMTP, sendmail, or other external delivery agents from being used.
+
+## Installation
+
+```ruby
+group :development, :qa do
+  gem "mail_dude"
+end
+```
+
+Run the installer:
+
+```bash
+bin/rails generate mail_dude:install
+```
+
+For database storage:
+
+```bash
+bin/rails generate mail_dude:install --database
+bin/rails db:migrate
+```
+
+## Action Mailer Configuration
+
+```ruby
+config.action_mailer.delivery_method = :mail_dude
+config.action_mailer.perform_deliveries = true
+```
+
+MailDude registers this delivery method when Action Mailer loads:
+
+```ruby
+ActiveSupport.on_load(:action_mailer) do
+  add_delivery_method :mail_dude, MailDude::DeliveryMethod
+end
+```
+
+## Secure Mounting
+
+MailDude does not authenticate or authorize users. Mount it behind your host application’s existing controls.
+
+```ruby
+authenticate :user, lambda { |u| Ability.new(u).can?(:manage, MailDude::Dashboard) } do
+  mount MailDude::Engine, at: "/mail_dude"
+end
+```
+
+Example CanCanCan-style subject:
+
+```ruby
+class Ability
+  include CanCan::Ability
+
+  def initialize(user)
+    return unless user
+
+    can :manage, MailDude::Dashboard if user.admin?
+  end
+end
+```
+
+MailDude does not depend on Devise, CanCanCan, Sidekiq, Redis, or a host app user model.
+
+## Configuration
+
+```ruby
+MailDude.configure do |config|
+  config.enabled_environments = %w[development qa test]
+  config.storage = :file
+  config.storage_path = Rails.root.join("tmp", "mail_dude")
+  config.max_messages = 1_000
+  config.retention_period = 7.days
+  config.max_message_size = 25.megabytes
+  config.allow_production = false
+  config.capture_attachments = true
+  config.capture_mailer_metadata_headers = true
+  config.default_per_page = 50
+  config.live_updates = false
+  config.live_update_stream_name = "mail_dude:#{Rails.env}:messages"
+  config.live_update_authorizer = ->(_connection) { false }
+end
+```
+
+`MailDude.enabled?`, `MailDude.store`, `MailDude.reset_store!`, and `MailDude.reset_configuration!` are available. The reset helpers mainly exist for tests and isolated tooling.
+
+## Storage Options
+
+| Storage | Best for | Pros | Cons |
+|---|---|---|---|
+| `:file` | Local development and single-node QA | No DB migrations, easy to inspect, easy to clear | Local disk may be ephemeral; not shared across containers/dynos |
+| `:database` | QA/staging-like environments with multiple app processes | Shared, persistent, searchable, works across nodes | Requires migration; can store sensitive content in DB; needs cleanup |
+| `:memory` | Tests and throwaway demos | Fast, simple | Process-local, lost on restart |
+
+## FileStore Path
+
+The default FileStore path is `Rails.root/tmp/mail_dude`. MailDude does not default to global `/tmp/mail_dude`, because multiple Rails apps on the same machine could collide. If Rails root is unavailable, MailDude falls back to `Dir.tmpdir/mail_dude`.
+
+FileStore under `Rails.root/tmp/mail_dude` may be wiped by deploys, container restarts, or cleanup scripts. Use `:database` or persistent shared disk for multi-node QA.
+
+## DatabaseStore Setup
+
+Use database storage when QA runs multiple processes, containers, or dynos:
+
+```ruby
+config.storage = :database
+```
+
+Then copy and run the migration:
+
+```bash
+bin/rails generate mail_dude:install --database
+bin/rails db:migrate
+```
+
+DatabaseStore uses `mail_dude_stored_emails` and does not require Active Storage.
+
+## MemoryStore
+
+MemoryStore is useful for tests and throwaway demos:
+
+```ruby
+config.storage = :memory
+```
+
+It is thread-safe but process-local and loses messages on restart.
+
+## UI Overview
+
+Mounting the engine exposes a mailbox UI with a message list, selected message metadata, HTML preview in a sandboxed iframe, plain text, headers, raw source, search, pagination, delete, clear, and attachment download links.
+
+## Action Cable Live Updates
+
+MailDude can optionally use Action Cable to show a “New message captured” banner without requiring a page reload. This is disabled by default.
+
+```ruby
+MailDude.configure do |config|
+  config.live_updates = true
+  config.live_update_stream_name = "mail_dude:#{Rails.env}:messages"
+  config.live_update_authorizer = lambda { |connection|
+    user = connection.respond_to?(:current_user) ? connection.current_user : nil
+    user && Ability.new(user).can?(:manage, MailDude::Dashboard)
+  }
+end
+```
+
+The authorizer receives the Action Cable `connection`, not a controller. This is intentional: mounting `/mail_dude` behind a route constraint does not protect `/cable`. Your host app must expose whatever identity the authorizer needs from `ApplicationCable::Connection`.
+
+Example host connection:
+
+```ruby
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = find_verified_user
+    end
+
+    private
+
+    def find_verified_user
+      env["warden"].user || reject_unauthorized_connection
+    end
+  end
+end
+```
+
+MailDude rejects cable subscriptions when `live_updates` is false or when `live_update_authorizer` returns false. Broadcast payloads include only list metadata such as id, subject, sender, recipients, captured time, and attachment count. They do not include raw source, headers, bodies, or attachment bytes.
+
+## Cleanup And Retention
+
+MailDude prunes after capture using:
+
+```ruby
+config.max_messages = 1_000
+config.retention_period = 7.days
+```
+
+Set either value to `nil` to disable that pruning dimension.
+
+## Rake Tasks
+
+```bash
+bin/rails mail_dude:clear
+bin/rails mail_dude:prune
+bin/rails mail_dude:stats
+```
+
+`clear` removes all captured messages. `prune` applies the configured retention and count limits. `stats` prints the storage adapter, total count, and storage location details.
+
+## Security Considerations
+
+Captured emails may contain PII, password reset links, invoices, tokens, and secrets.
+
+Do not expose `/mail_dude` publicly. Do not enable in production unless you fully understand the risk. Prefer short retention. Prefer DatabaseStore or persistent disk in multi-node QA. FileStore under `Rails.root/tmp/mail_dude` may be wiped by deploys, container restarts, or cleanup scripts.
+
+Captured HTML is rendered in a sandboxed iframe with a restrictive Content Security Policy. Attachments are extracted from raw `.eml` data on request and filenames are sanitized.
+
+If Action Cable live updates are enabled, protect subscriptions with `live_update_authorizer`. The `/mail_dude` route constraint does not authorize `/cable`.
+
+## Production Warning
+
+Production is disabled by default. If `:mail_dude` is configured in a disabled environment, delivery raises `MailDude::DisabledEnvironmentError` and does not store or send the email.
+
+An escape hatch exists:
+
+```ruby
+config.allow_production = true
+```
+
+Avoid this unless you have a reviewed operational and data-retention plan.
+
+## Testing The Gem Locally
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+bundle exec rake
+```
+
+The test suite uses a dummy Rails app, SQLite for DatabaseStore specs, RSpec, and SimpleCov with 100% line and branch coverage gates.
+
+## Contributing
+
+Keep changes small, covered, and consistent with Rails engine conventions. Do not add host-app authentication dependencies to MailDude itself.
+
+## License
+
+MIT. See `LICENSE.txt`.

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

@@ -0,0 +1,180 @@
+.mail-dude {
+  background: #f7f8fa;
+  color: #1d2433;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  margin: 0;
+}
+
+.mail-dude-shell {
+  min-height: 100vh;
+}
+
+.mail-dude-header {
+  align-items: center;
+  background: #ffffff;
+  border-bottom: 1px solid #d8dee8;
+  display: flex;
+  gap: 16px;
+  padding: 14px 18px;
+}
+
+.mail-dude-brand {
+  align-items: center;
+  display: flex;
+  gap: 10px;
+  margin-right: auto;
+  min-width: 0;
+}
+
+.mail-dude-logo {
+  flex: 0 0 58px;
+  height: 40px;
+  object-fit: contain;
+  width: 58px;
+}
+
+.mail-dude-header h1 {
+  font-size: 20px;
+  margin: 0;
+}
+
+.mail-dude-search {
+  align-items: center;
+  display: flex;
+  gap: 8px;
+}
+
+.mail-dude-search input {
+  border: 1px solid #b9c2d0;
+  border-radius: 6px;
+  font: inherit;
+  padding: 7px 9px;
+}
+
+.mail-dude-search input[type="submit"],
+.mail-dude-danger {
+  border: 1px solid #a91f2f;
+  border-radius: 6px;
+  background: #ffffff;
+  color: #8a1422;
+  cursor: pointer;
+  font: inherit;
+  padding: 7px 10px;
+}
+
+.mail-dude-layout {
+  display: grid;
+  grid-template-columns: minmax(260px, 34%) 1fr;
+  min-height: calc(100vh - 65px);
+}
+
+.mail-dude-list {
+  background: #ffffff;
+  border-right: 1px solid #d8dee8;
+  overflow: auto;
+}
+
+.mail-dude-list ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.mail-dude-list-item {
+  border-bottom: 1px solid #e6ebf2;
+  color: inherit;
+  display: grid;
+  gap: 3px;
+  padding: 12px 14px;
+  text-decoration: none;
+}
+
+.mail-dude-list-item.is-active {
+  background: #e8f2ff;
+  box-shadow: inset 4px 0 0 #1c68d1;
+}
+
+.mail-dude-list-item span {
+  color: #596579;
+  font-size: 13px;
+}
+
+.mail-dude-pane {
+  padding: 18px;
+}
+
+.mail-dude-pane-header {
+  align-items: center;
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+}
+
+.mail-dude-pane-header h2 {
+  font-size: 22px;
+  margin: 0;
+}
+
+.mail-dude-metadata {
+  display: grid;
+  grid-template-columns: 130px 1fr;
+  margin: 18px 0;
+}
+
+.mail-dude-metadata dt,
+.mail-dude-metadata dd {
+  border-top: 1px solid #d8dee8;
+  margin: 0;
+  padding: 8px 0;
+}
+
+.mail-dude-metadata dt {
+  color: #596579;
+  font-weight: 700;
+}
+
+.mail-dude-tabs {
+  display: flex;
+  gap: 10px;
+  margin-bottom: 10px;
+}
+
+.mail-dude-message-html-frame {
+  background: #ffffff;
+  border: 1px solid #d8dee8;
+  border-radius: 6px;
+  min-height: 420px;
+  width: 100%;
+}
+
+.mail-dude-empty,
+.mail-dude-error,
+.mail-dude-live-banner,
+.mail-dude-notice {
+  padding: 18px;
+}
+
+.mail-dude-live-banner {
+  background: #e8f2ff;
+  border-bottom: 1px solid #9bbce8;
+}
+
+.mail-dude-pagination {
+  align-items: center;
+  display: flex;
+  gap: 12px;
+  padding: 12px 14px;
+}
+
+@media (max-width: 800px) {
+  .mail-dude-header,
+  .mail-dude-layout {
+    display: block;
+  }
+
+  .mail-dude-list {
+    border-bottom: 1px solid #d8dee8;
+    border-right: 0;
+    max-height: 45vh;
+  }
+}

data/app/channels/mail_dude/messages_channel.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MailDude
+  class MessagesChannel < ActionCable::Channel::Base
+    def subscribed
+      return reject unless authorized?
+
+      stream_from MailDude.configuration.live_update_stream_name
+    end
+
+    private
+
+    def authorized?
+      MailDude.configuration.live_updates &&
+        MailDude.configuration.live_update_authorizer.call(connection)
+    end
+  end
+end

data/app/controllers/mail_dude/application_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module MailDude
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+    layout 'mail_dude/application'
+
+    rescue_from AttachmentNotFoundError, MessageNotFoundError, with: :render_not_found
+    rescue_from InvalidConfigurationError, StorageError, with: :render_storage_error
+
+    private
+
+    def render_not_found
+      respond_to do |format|
+        format.html { render 'mail_dude/messages/error', status: :not_found, locals: { message: 'Message not found.' } }
+        format.any { head :not_found }
+      end
+    end
+
+    def render_storage_error(error)
+      diagnostic = Rails.env.production? ? 'MailDude storage is unavailable.' : error.message
+      render 'mail_dude/messages/error', status: :internal_server_error, locals: { message: diagnostic }
+    end
+  end
+end

data/app/controllers/mail_dude/attachments_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MailDude
+  class AttachmentsController < ApplicationController
+    SAFE_INLINE_TYPES = %w[image/gif image/jpeg image/png image/webp image/svg+xml].freeze
+
+    def show
+      record = MailDude.store.find(params[:message_id] || params[:id])
+      attachment = AttachmentLocator.new(record).find(params[:attachment_id])
+      send_data attachment.data,
+                filename: attachment.filename,
+                type: attachment.content_type,
+                disposition: disposition_for(attachment)
+    end
+
+    private
+
+    def disposition_for(attachment)
+      if params[:inline] == '1' && attachment.inline? && SAFE_INLINE_TYPES.include?(attachment.content_type)
+        return 'inline'
+      end
+
+      'attachment'
+    end
+  end
+end

data/app/controllers/mail_dude/messages_controller.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module MailDude
+  class MessagesController < ApplicationController
+    before_action :load_page, only: %i[index show]
+
+    def index
+      @selected_message = first_message
+    end
+
+    def show
+      @selected_message = MailDude.store.find(params[:id])
+      render :index
+    end
+
+    def html
+      presenter = presenter_for(params[:id])
+      response.headers['Content-Security-Policy'] =
+        "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; font-src data:; " \
+        "base-uri 'none'; form-action 'none'; script-src 'none'"
+      render html: renderer_for(presenter).render.html_safe, layout: false
+    end
+
+    def text
+      render plain: presenter_for(params[:id]).text_body.presence || 'This message does not include a plain text body.'
+    end
+
+    def headers
+      render plain: presenter_for(params[:id]).raw_headers.presence || 'This message does not include headers.'
+    end
+
+    def raw
+      record = MailDude.store.find(params[:id])
+      response.headers['Content-Disposition'] = %(inline; filename="#{record.id}.eml")
+      render plain: record.raw_source, content_type: 'text/plain'
+    end
+
+    def destroy
+      raise MessageNotFoundError, 'Message not found' unless MailDude.store.delete(params[:id])
+
+      redirect_to messages_path, notice: 'Message deleted.'
+    end
+
+    def clear
+      count = MailDude.store.clear
+      redirect_to messages_path, notice: "#{count} messages cleared."
+    end
+
+    private
+
+    def first_message
+      first_record = @page.records.first
+      first_record ? MailDude.store.find(first_record.id) : nil
+    end
+
+    def load_page
+      @query = params[:q]
+      @page = MailDude.store.list(page: params[:page], per_page: params[:per_page], query: @query)
+    end
+
+    def presenter_for(id)
+      MessagePresenter.new(MailDude.store.find(id))
+    end
+
+    def renderer_for(presenter)
+      HtmlBodyRenderer.new(presenter,
+                           attachment_url: lambda do |attachment_id, **|
+                             attachment_message_path(presenter.id, attachment_id, inline: '1')
+                           end)
+    end
+  end
+end

data/app/helpers/mail_dude/application_helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MailDude
+  module ApplicationHelper
+    def mail_dude_address_list(values)
+      Array(values).presence&.join(', ') || 'None'
+    end
+
+    def mail_dude_selected?(message)
+      @selected_message&.id == message.id
+    end
+  end
+end

data/app/models/mail_dude/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MailDude
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/mail_dude/stored_email.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MailDude
+  class StoredEmail < ApplicationRecord
+    self.table_name = 'mail_dude_stored_emails'
+  end
+end