mailbox-kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 186fcaea489075063aeb25ee886080ff243289eb3ec02fdfac110f9c7e5c9081
+  data.tar.gz: 81071f06cf54c2de754bf16a056e6be93ae7dcbbca6604c3636a8e3ed19e3169
+SHA512:
+  metadata.gz: 6df3f4be7cd2b1b07eebbd164a609c4fa488572b2bed5c65312e1363e4c21c04312ad11d3b6cf73cf636ff0893dc7d4b066a31f7f842beb1d1a829819db783ef
+  data.tar.gz: ba69a55126f0a291dc21296230532c4c575a183d45f49c37dbeeb4295762847a43c47b7fa091c8e835b2b0cd3bdbf87fd697baebd9244ff52345d46795997df5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cole
+
+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,104 @@
+# Mailbox Kit
+
+Persistent inboxes and a management UI built on Rails Action Mailbox.
+Use it when your application needs named inboxes, aliases, read/archive state,
+and access control. SQLite works out of the box; database tenancy is opt-in.
+
+Rails already stores raw email, parses it, routes it to handlers, and runs
+processing jobs. Mailbox Kit adds the inbox your users interact with.
+
+## Choose your setup
+
+- **Cloudflare receiving or sending:** follow the [Cloudflare Rails guide](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/getting-started.md).
+  It includes this core; use the Cloudflare installer.
+- **An existing Action Mailbox integration:** install this core and attach received
+  email to inboxes. Follow the example below.
+- **Only processing incoming email:** Action Mailbox alone may be enough.
+
+Add Mailbox Kit 0.1 to your Gemfile:
+
+```ruby
+gem "mailbox-kit", "~> 0.1.0"
+```
+
+For a new Rails 7.2–8.1 application:
+
+```sh
+bundle install
+bin/rails action_mailbox:install
+bin/rails generate mailbox_kit:install
+bin/rails db:migrate
+```
+
+Already using Cloudflare mailboxes? Follow the [upgrade guide](docs/upgrading.md)
+instead of creating the tables again.
+
+## Create an inbox in code
+
+After configuring and verifying your provider's receiving route:
+
+```ruby
+boxes = MailboxKit::Mailboxes
+domain = boxes.register_domain(domain: "in.example.com", tenant_key: "workspace")
+boxes.activate_domain!(domain.id, evidence: "Receiving route verified")
+
+boxes.for_tenant("workspace") do |session|
+  inbox = session.create(name: "Support", address: "support@in.example.com")
+  session.activate_address!(inbox.addresses.first.id, evidence: "Receiving route verified")
+end
+```
+
+`workspace` scopes inboxes within the default database. It does not enable separate
+tenant databases. Creating an address does not configure DNS or authorize sending.
+
+## Connect received email
+
+If your authenticated integration already has an Action Mailbox record:
+
+```ruby
+MailboxKit::Mailboxes.for_tenant(trusted_tenant_key) do |session|
+  session.attach(recipient: verified_envelope_recipient,
+                 inbound_email_id: inbound_email.id)
+end
+```
+
+Authorize the record in the application first. Use the provider's verified
+envelope recipient, not an untrusted email header. Keep your ordinary
+`ApplicationMailbox` handlers: attachment does not process the email again.
+The Cloudflare inbox ingress already performs this integration for you.
+
+## Read and manage
+
+```ruby
+MailboxKit::Mailboxes.for_tenant("workspace") do |session|
+  unread = session.messages(inbox_id).inbox.unread
+  session.mark_read(inbox_id, message_id)
+  session.archive(inbox_id, message_id)
+end
+```
+
+The optional management engine provides a server-rendered UI with no frontend
+build. Your application supplies authentication and authorizes each action;
+access is denied until configured. See [management setup](docs/integration.md#management-interface).
+
+## The split
+
+| Layer | Owns |
+| --- | --- |
+| Rails | Raw MIME, Active Storage, parsing, routing, processing jobs/status, cleanup policy, Action Mailer |
+| Mailbox Kit | Inbox identities, addresses/aliases, memberships, read/archive state, selective retention, optional tenant context, management UI |
+| Cloudflare | Request verification, authoritative envelope metadata, Worker retries/storage, sending, delivery feedback, provisioning |
+| Your app | Users/organizations/sites, ownership lifecycle, authorization, sender acceptance, business effects |
+
+Inbound and outbound can use different providers through Rails. The core does
+not send email or supply a universal outbound adapter registry. `owner_ref` is an
+application-managed reference; it is not an automatic `has_mailbox` association
+or permission grant.
+
+Inbox-associated messages survive Rails' automatic incineration. For retaining
+all inbound messages, Rails already offers `config.action_mailbox.incinerate = false`.
+Raw storage and processing remain Rails responsibilities.
+
+See the [integration guide](docs/integration.md) for aliases, catch-all addresses,
+verified source ingestion, duplicates, retention, authorization and optional
+database tenancy. See [upgrading](docs/upgrading.md) for existing installations.

data/app/controllers/mailbox_kit/management/mailboxes_controller.rb

@@ -0,0 +1,171 @@
+module MailboxKit
+  module Management
+    class MailboxesController < ActionController::Base
+      layout "layouts/mailbox_kit/management"
+      protect_from_forgery with: :exception
+      self.forgery_protection_origin_check = true
+      around_action :with_host_context
+      helper_method :allowed?, :host_back_path
+
+      class Denied < StandardError; end
+      class InvalidInput < StandardError; end
+
+      rescue_from Denied do
+        head :forbidden
+      end
+      rescue_from "ActiveRecord::RecordNotFound" do
+        head :not_found
+      end
+      rescue_from InvalidInput, "ActiveRecord::RecordInvalid", MailboxKit::Error do
+        redirect_to(@mailbox ? mailbox_path(@mailbox) : root_path,
+          alert: "The changes could not be saved. Check the address, registered domain and required fields.",
+          status: :see_other)
+      end
+      rescue_from MailboxKit::ConfigurationError do
+        head :service_unavailable
+      end
+
+      def index
+        authorize!(:index)
+        @mailboxes = page(scoped_mailboxes)
+        @domains = permitted_domains if allowed?(:create)
+      end
+
+      def show
+        load_mailbox!(:show)
+        @addresses = @session.addresses(@mailbox.id).order(:id).to_a
+        @domains = allowed?(:add_address, @mailbox) ? permitted_domains : []
+        @messages = allowed?(:show_message, @mailbox) ? page(@session.messages(@mailbox.id)) : []
+      end
+
+      def create
+        authorize!(:create)
+        input = params.require(:mailbox)
+        raise InvalidInput unless input.is_a?(ActionController::Parameters)
+        values = input.permit(:name, :address)
+        name = values[:name].to_s.strip
+        raise InvalidInput unless (1..255).cover?(name.length)
+        address = permitted_address!(values[:address])
+        Mailboxes::Mailbox.transaction do
+          @mailbox = @adapter.create_mailbox(@session, name: name, address: address)
+          # A hook cannot turn an arbitrary return value into a readable mailbox.
+          @mailbox = scoped_mailboxes.find(@mailbox.id)
+        end
+        redirect_to mailbox_path(@mailbox), notice: "Mailbox created. Review address setup below.", status: :see_other
+      end
+
+      def add_address
+        load_mailbox!(:add_address)
+        @adapter.add_address(@session, @mailbox, address: permitted_address!(params[:address]))
+        redirect_to mailbox_path(@mailbox), notice: "Address added. Review its setup status.", status: :see_other
+      end
+
+      def suspend
+        load_mailbox!(:suspend)
+        @session.suspend(@mailbox.id)
+        redirect_to mailbox_path(@mailbox), notice: "Mailbox suspended. Messages are retained.", status: :see_other
+      end
+
+      def resume
+        load_mailbox!(:resume)
+        @session.resume(@mailbox.id)
+        redirect_to mailbox_path(@mailbox), notice: "Mailbox resumed. Pending addresses still need setup.", status: :see_other
+      end
+
+      def message
+        load_mailbox!(:show_message)
+        @entry = @session.messages(@mailbox.id).find(params[:message_id])
+        raw = @session.inbound_email(@mailbox.id, @entry.id).mail
+        @subject = raw.subject.to_s
+        @from = Array(raw.from).join(", ")
+        part = raw.text_part || (raw.mime_type == "text/plain" ? raw : nil)
+        @body = part ? part.decoded.to_s.encode("UTF-8", invalid: :replace, undef: :replace).first(100_000) :
+          "This message has no plain-text body. HTML rendering is disabled in this management interface."
+        @attachments = raw.attachments.map { |attachment| attachment.filename.to_s }
+        render :message
+      end
+
+      def mark_read
+        load_mailbox!(:mark_read)
+        @session.mark_read(@mailbox.id, params[:message_id], read: boolean_param(:read))
+        redirect_to mailbox_path(@mailbox), status: :see_other
+      end
+
+      def archive
+        load_mailbox!(:archive)
+        @session.archive(@mailbox.id, params[:message_id], archived: boolean_param(:archived))
+        redirect_to mailbox_path(@mailbox), status: :see_other
+      end
+
+      private
+
+      def with_host_context
+        response.headers["Cache-Control"] = "no-store"
+        response.headers["Referrer-Policy"] = "same-origin"
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["Content-Security-Policy"] = "default-src 'none'; style-src 'self'; img-src 'none'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'"
+        factory = Management.configuration.adapter
+        unless factory.respond_to?(:call) && defined?(Mailboxes) && Mailboxes.enabled?
+          return head :service_unavailable
+        end
+        @adapter = factory.call(self)
+        authenticated = @adapter.authenticate!
+        return if performed?
+        return head :unauthorized unless authenticated == true
+        Mailboxes.for_tenant(@adapter.tenant_key) do |session|
+          @session = session
+          yield
+        end
+      end
+
+      def allowed?(action, mailbox = nil)
+        @adapter.allowed?(action, mailbox) == true
+      end
+
+      def authorize!(action, mailbox = nil)
+        raise Denied unless allowed?(action, mailbox)
+      end
+
+      def scoped_mailboxes
+        # Always retain the gem's tenant condition even if a host scope omits it.
+        @session.mailboxes.where(id: @adapter.mailboxes(@session).reselect(:id))
+      end
+
+      def load_mailbox!(action)
+        @mailbox = scoped_mailboxes.find(params[:id])
+        authorize!(action, @mailbox)
+      end
+
+      def permitted_domains
+        granted = Array(@adapter.domains(@session)).map(&:to_s)
+        Mailboxes::ReceivingDomain.active.where(tenant_key: @session.tenant_key, domain: granted).order(:domain).pluck(:domain)
+      end
+
+      def permitted_address!(value)
+        address = Mailboxes.canonical_address(value)
+        raise InvalidInput unless permitted_domains.include?(address.split("@", 2).last)
+        address
+      end
+
+      def page(relation)
+        cursor = params[:after].to_s
+        raise InvalidInput unless cursor.empty? || cursor.match?(/\A[0-9]{1,18}\z/)
+        rows = relation.where("id > ?", cursor.to_i).order(:id).limit(51).to_a
+        @next_cursor = rows.length > 50 ? rows[49].id : nil
+        rows.first(50)
+      end
+
+      def boolean_param(key)
+        value = params[key]
+        raise InvalidInput unless %w[true false].include?(value)
+        value == "true"
+      end
+
+      def host_back_path
+        callback = Management.configuration.back_path
+        value = callback.call(self) if callback.respond_to?(:call)
+        value if value.is_a?(String) && value.start_with?("/") && !value.start_with?("//") && !value.match?(/[\\\r\n]/)
+      end
+    end
+  end
+end

data/app/controllers/mailbox_kit/management/styles_controller.rb

@@ -0,0 +1,11 @@
+module MailboxKit
+  module Management
+    class StylesController < ActionController::Base
+      def show
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        send_data File.binread(File.expand_path("../../../../lib/mailbox_kit/management/management.css", __dir__)),
+          type: "text/css; charset=utf-8", disposition: "inline"
+      end
+    end
+  end
+end

data/app/views/layouts/mailbox_kit/management.html.erb

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Mailbox management</title>
+    <%= csrf_meta_tags %>
+    <%= stylesheet_link_tag style_path %>
+  </head>
+  <body>
+    <a class="skip-link" href="#main">Skip to content</a>
+    <header class="site-header">
+      <div class="shell header-content">
+        <%= link_to "Mailbox management", root_path, class: "brand" %>
+        <span class="header-caption">Mailboxes</span>
+        <% if host_back_path %><%= link_to "Back to app", host_back_path %><% end %>
+      </div>
+    </header>
+    <main id="main" class="shell" tabindex="-1">
+      <% if flash[:notice].present? %>
+        <div class="notice" role="status"><%= flash[:notice] %></div>
+      <% end %>
+      <% if flash[:alert].present? %>
+        <div class="notice notice-error" role="alert"><%= flash[:alert] %></div>
+      <% end %>
+      <%= yield %>
+    </main>
+  </body>
+</html>

data/app/views/mailbox_kit/management/mailboxes/index.html.erb

@@ -0,0 +1,65 @@
+<div class="page-heading">
+  <div>
+    <p class="eyebrow">Email workspace</p>
+    <h1>Mailboxes</h1>
+    <p class="muted">Manage accepted addresses and the messages delivered to them.</p>
+  </div>
+</div>
+
+<div class="workspace-grid">
+  <section class="panel" aria-labelledby="mailboxes-heading">
+    <div class="panel-heading"><h2 id="mailboxes-heading">Your mailboxes</h2></div>
+    <% if @mailboxes.empty? %>
+      <div class="empty-state">
+        <h3>No mailboxes to show</h3>
+        <p>Create a mailbox to give incoming email a home.</p>
+      </div>
+    <% else %>
+      <ul class="record-list">
+        <% @mailboxes.each do |mailbox| %>
+          <li class="record-row">
+            <div class="record-content">
+              <% if allowed?(:show, mailbox) %>
+                <%= link_to mailbox.name, mailbox_path(mailbox.id), class: "record-title" %>
+              <% else %>
+                <span class="record-title"><%= mailbox.name %></span>
+              <% end %>
+              <p class="muted small">Mailbox #<%= mailbox.id %></p>
+            </div>
+            <span class="badge"><%= mailbox.state.capitalize %></span>
+          </li>
+        <% end %>
+      </ul>
+    <% end %>
+    <% if @next_cursor.present? %>
+      <nav class="pagination" aria-label="Mailbox pages">
+        <%= link_to "Next mailboxes →", root_path(after: @next_cursor), class: "button button-secondary" %>
+      </nav>
+    <% end %>
+  </section>
+
+  <% if allowed?(:create) %>
+    <section class="panel" aria-labelledby="create-heading">
+      <div class="panel-heading"><h2 id="create-heading">Create a mailbox</h2></div>
+      <div class="panel-body">
+        <% if @domains.empty? %>
+          <p class="muted">An administrator needs to register an active receiving domain before you can create a mailbox.</p>
+        <% else %>
+          <%= form_with url: mailboxes_path, scope: :mailbox, local: true, class: "stack" do |form| %>
+            <div class="field">
+              <%= form.label :name, "Mailbox name" %>
+              <%= form.text_field :name, required: true, maxlength: 255, placeholder: "Customer support" %>
+            </div>
+            <div class="field">
+              <%= form.label :address, "Email address" %>
+              <%= form.email_field :address, required: true, maxlength: 254, placeholder: "support@#{@domains.first}", aria: { describedby: "create-domains" } %>
+              <p id="create-domains" class="field-help">Available domains: <%= @domains.join(", ") %></p>
+            </div>
+            <p class="field-help">New addresses start pending. Your administrator must confirm their routing before they can receive mail.</p>
+            <%= form.submit "Create mailbox", class: "button" %>
+          <% end %>
+        <% end %>
+      </div>
+    </section>
+  <% end %>
+</div>

data/app/views/mailbox_kit/management/mailboxes/message.html.erb

@@ -0,0 +1,34 @@
+<nav class="breadcrumbs" aria-label="Breadcrumb">
+  <%= link_to "Mailboxes", root_path %> <span aria-hidden="true">/</span>
+  <%= link_to @mailbox.name, mailbox_path(@mailbox.id) %> <span aria-hidden="true">/</span>
+  <span>Message</span>
+</nav>
+<div class="page-heading">
+  <div><p class="eyebrow">Received message</p><h1><%= @subject.presence || "(No subject)" %></h1></div>
+  <div class="actions">
+    <% if allowed?(:mark_read, @mailbox) %>
+      <%= button_to(@entry.read_at ? "Mark unread" : "Mark read", mark_read_mailbox_path(@mailbox.id), method: :post, params: { message_id: @entry.id, read: @entry.read_at ? "false" : "true" }, class: "button button-secondary") %>
+    <% end %>
+    <% if allowed?(:archive, @mailbox) %>
+      <%= button_to(@entry.archived_at ? "Unarchive" : "Archive", archive_mailbox_path(@mailbox.id), method: :post, params: { message_id: @entry.id, archived: @entry.archived_at ? "false" : "true" }, class: "button button-secondary") %>
+    <% end %>
+  </div>
+</div>
+<article class="panel" aria-label="Email message">
+  <div class="panel-body">
+    <dl class="message-metadata">
+      <dt>From</dt><dd><%= @from.presence || "(Unknown sender)" %></dd>
+      <dt>To</dt><dd><%= @entry.recipient %></dd>
+      <dt>Received</dt><dd><time datetime="<%= @entry.created_at.iso8601 %>"><%= @entry.created_at.utc.strftime("%b %-d, %Y · %H:%M UTC") %></time></dd>
+      <dt>Status</dt><dd><%= @entry.read_at ? "Read" : "Unread" %><%= " · Archived" if @entry.archived_at %></dd>
+    </dl>
+  </div>
+  <div class="message-body"><pre><%= @body.presence || "No text content is available for this message." %></pre></div>
+  <% if @attachments.any? %>
+    <section class="panel-body attachments" aria-labelledby="attachments-heading">
+      <h2 id="attachments-heading">Attachments</h2>
+      <p class="field-help">File names are shown for reference. Downloads are not available in this dashboard.</p>
+      <ul><% @attachments.each do |filename| %><li><%= filename.presence || "Unnamed attachment" %></li><% end %></ul>
+    </section>
+  <% end %>
+</article>

data/app/views/mailbox_kit/management/mailboxes/show.html.erb

@@ -0,0 +1,86 @@
+<nav class="breadcrumbs" aria-label="Breadcrumb"><%= link_to "Mailboxes", root_path %> <span aria-hidden="true">/</span> <span><%= @mailbox.name %></span></nav>
+<div class="page-heading">
+  <div>
+    <p class="eyebrow">Mailbox</p>
+    <h1><%= @mailbox.name %></h1>
+    <p class="muted"><%= @mailbox.state == "suspended" ? "Receiving is paused for every address in this mailbox." : "Addresses receive mail when both their address and domain are active." %></p>
+  </div>
+  <div class="actions">
+    <span class="badge"><%= @mailbox.state.capitalize %></span>
+    <% if @mailbox.state == "active" && allowed?(:suspend, @mailbox) %>
+      <%= button_to "Suspend mailbox", suspend_mailbox_path(@mailbox.id), method: :post, class: "button button-secondary" %>
+    <% elsif @mailbox.state == "suspended" && allowed?(:resume, @mailbox) %>
+      <%= button_to "Resume mailbox", resume_mailbox_path(@mailbox.id), method: :post, class: "button" %>
+    <% end %>
+  </div>
+</div>
+
+<div class="workspace-grid">
+  <section class="panel" aria-labelledby="messages-heading">
+    <div class="panel-heading"><h2 id="messages-heading">Received messages</h2><p class="muted small">Includes archived messages</p></div>
+    <% if @messages.empty? %>
+      <div class="empty-state"><h3>No messages to show</h3><p>Messages appear here after delivery to an active address.</p></div>
+    <% else %>
+      <ul class="record-list">
+        <% @messages.each do |entry| %>
+          <li class="record-row">
+            <div class="record-content">
+              <% if allowed?(:show_message, @mailbox) %>
+                <%= link_to "Message to #{entry.recipient}", message_mailbox_path(@mailbox.id, message_id: entry.id), class: "record-title" %>
+              <% else %>
+                <span class="record-title">Message to <%= entry.recipient %></span>
+              <% end %>
+              <p class="muted small"><time datetime="<%= entry.created_at.iso8601 %>"><%= entry.created_at.utc.strftime("%b %-d, %Y · %H:%M UTC") %></time></p>
+            </div>
+            <div class="status-list">
+              <span class="badge"><%= entry.read_at ? "Read" : "Unread" %></span>
+              <% if entry.archived_at %><span class="badge">Archived</span><% end %>
+            </div>
+          </li>
+        <% end %>
+      </ul>
+    <% end %>
+    <% if @next_cursor.present? %>
+      <nav class="pagination" aria-label="Message pages"><%= link_to "Next messages →", mailbox_path(@mailbox.id, after: @next_cursor), class: "button button-secondary" %></nav>
+    <% end %>
+  </section>
+
+  <div class="stack">
+    <section class="panel" aria-labelledby="addresses-heading">
+      <div class="panel-heading"><h2 id="addresses-heading">Addresses</h2></div>
+      <ul class="record-list">
+        <% @addresses.each do |address| %>
+          <% receiving = @mailbox.state == "active" && address.state == "active" && address.receiving_domain&.state == "active" %>
+          <li class="record-row address-row">
+            <span class="record-title"><%= address.address %></span>
+            <% if address.has_attribute?(:catch_all) && address[:catch_all] %>
+              <span class="badge">Domain catch-all configured</span>
+            <% end %>
+            <span class="badge"><%= receiving ? "Accepting mail" : address.state == "pending" ? "Pending setup" : "Receiving paused" %></span>
+          </li>
+        <% end %>
+      </ul>
+      <div class="panel-body"><p class="field-help">Pending addresses need routing confirmation from your administrator. Resuming a mailbox preserves each address’s existing setup state.</p></div>
+    </section>
+
+    <% if allowed?(:add_address, @mailbox) %>
+      <section class="panel" aria-labelledby="alias-heading">
+        <div class="panel-heading"><h2 id="alias-heading">Add an alias</h2></div>
+        <div class="panel-body">
+          <% if @domains.empty? %>
+            <p class="muted">No active receiving domains are available. Contact your administrator.</p>
+          <% else %>
+            <%= form_with url: aliases_mailbox_path(@mailbox.id), local: true, class: "stack" do |form| %>
+              <div class="field">
+                <%= form.label :address, "Alias email address" %>
+                <%= form.email_field :address, required: true, maxlength: 254, aria: { describedby: "alias-domains" } %>
+                <p id="alias-domains" class="field-help">Available domains: <%= @domains.join(", ") %>. Messages to this alias will appear in this mailbox.</p>
+              </div>
+              <%= form.submit "Add alias", class: "button" %>
+            <% end %>
+          <% end %>
+        </div>
+      </section>
+    <% end %>
+  </div>
+</div>