protege 0.1.0.alpha.1

data/lib/protege/gateway/mail/outbound.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'mail'
+
+module Protege
+  module Gateway
+    module Mail
+      # Builder for outbound +::Mail::Message+ objects — the one place the engine assembles mail it
+      # sends, whether a brand-new console conversation or a threaded reply.
+      #
+      # Centralizing construction keeps the conventions (a synthetic angle-bracketed Message-ID, a
+      # UTF-8 plain-text body, a Date stamp) and the threading-header normalization (+In-Reply-To+ via
+      # +MessageId+, +References+ via +References+) in a single tested spot, rather than duplicated
+      # across +RepliesController+, +ThreadsController+, and host tools like +SendEmailTool+.
+      #
+      # @example A threaded reply
+      #   Outbound.build(
+      #     from:        persona.email_address,
+      #     to:          inbound.from_address,
+      #     subject:     'Re: Hello',
+      #     body:        'Thanks!',
+      #     in_reply_to: inbound.message_id,
+      #     references:  inbound.references_header
+      #   )
+      class Outbound
+        class << self
+          # Build and return a ready-to-deliver +::Mail::Message+.
+          #
+          # @param from [String] the sender address.
+          # @param to [String, Array<String>] the recipient address(es).
+          # @param subject [String] the subject line.
+          # @param body [String] the plain-text body.
+          # @param cc [String, Array<String>] carbon-copy recipient(s); omitted from the message when empty.
+          # @param bcc [String, Array<String>] blind-carbon-copy recipient(s); omitted when empty.
+          # @param in_reply_to [String, MessageId, nil] the parent message id, normalized when present.
+          # @param references [References, Array<String>, String, nil] the prior reference chain;
+          #   Strings are split on whitespace, Arrays/References normalized per id.
+          # @param attachments [Array<Mail::Attachment>] files to attach; when any are present the message
+          #   is assembled as multipart with the body as a text part.
+          # @return [::Mail::Message] the assembled message.
+          def build(
+            from:,
+            to:,
+            subject:,
+            body:,
+            cc: [],
+            bcc: [],
+            in_reply_to: nil,
+            references: nil,
+            attachments: []
+          )
+            new(
+              from:,
+              to:,
+              subject:,
+              body:,
+              cc:,
+              bcc:,
+              in_reply_to:,
+              references:,
+              attachments:
+            ).message
+          end
+        end
+
+        # Store the envelope and threading inputs. Prefer the +.build+ factory.
+        #
+        # @param (see .build)
+        def initialize(
+          from:,
+          to:,
+          subject:,
+          body:,
+          cc: [],
+          bcc: [],
+          in_reply_to: nil,
+          references: nil,
+          attachments: []
+        )
+          @from        = from
+          @to          = to
+          @subject     = subject
+          @body        = body
+          @cc          = cc
+          @bcc         = bcc
+          @in_reply_to = in_reply_to
+          @references  = references
+          @attachments = attachments
+        end
+
+        # Assemble the +::Mail::Message+ from the stored inputs.
+        #
+        # @return [::Mail::Message] the message with envelope, body, id, date, and threading headers set.
+        def message
+          ::Mail.new.tap do |m|
+            m.from        = @from
+            m.to          = @to
+            m.cc          = @cc
+            m.bcc         = @bcc
+            m.subject     = @subject
+            m.message_id  = MessageId.synthetic(domain: sender_domain).value
+            m.date        = Time.current
+            m.in_reply_to = parent_id if parent_id
+            m.references  = reference_values if reference_values.any?
+
+            assign_content(m)
+          end
+        end
+
+        private
+
+        # Set the body on +mail+: a single +text/plain+ part when there are no attachments, otherwise a
+        # multipart message whose first part is the plain-text body and whose remaining parts are the
+        # attachments. Forcing a top-level +text/plain+ content type would break the multipart case, so
+        # it is only set when single-part.
+        #
+        # @param mail [::Mail::Message] the message under construction
+        # @return [void]
+        def assign_content(mail)
+          if @attachments.empty?
+            mail.body         = @body
+            mail.content_type = 'text/plain; charset=UTF-8'
+            return
+          end
+
+          text              = ::Mail::Part.new
+          text.content_type = 'text/plain; charset=UTF-8'
+          text.body         = @body
+          mail.text_part    = text
+
+          @attachments.each do |attachment|
+            mail.attachments[attachment.filename] = {
+              mime_type: attachment.content_type,
+              content:   attachment.bytes
+            }
+          end
+        end
+
+        # The domain for the outbound Message-ID — the +From+ address's domain, so the id carries the
+        # real sending domain (recipients like Gmail distrust a bogus domain and won't thread). A
+        # persona (or the console) always sends from a full address, so a From with no domain is a
+        # caller bug rather than something to paper over.
+        #
+        # @return [String] the sending domain.
+        # @raise [Protege::ContractViolationError] when the From address has no parseable domain.
+        def sender_domain
+          @from.to_s[/@(.+)\z/, 1]&.strip.presence ||
+            raise(Protege::ContractViolationError,
+                  "cannot derive a sender domain from From address #{@from.inspect} — it has no domain")
+        end
+
+        # The normalized parent message id, or nil when no reply target was given.
+        #
+        # @return [String, nil] the angle-bracketed id.
+        def parent_id
+          return nil if @in_reply_to.nil?
+
+          MessageId.parse(@in_reply_to).value
+        end
+
+        # The normalized reference chain as angle-bracketed id strings.
+        #
+        # @return [Array<String>] the chain, possibly empty.
+        def reference_values
+          @reference_values ||= reference_chain.to_a.map(&:to_s)
+        end
+
+        # Coerce the +references+ input into a +References+ chain.
+        #
+        # @return [References] the normalized chain.
+        def reference_chain
+          case @references
+          when References then @references
+          when String     then References.parse(@references.split)
+          else                 References.parse(Array(@references))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protege/gateway/mail/references.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Protege
+  module Gateway
+    module Mail
+      # Value object representing an ordered chain of Message-IDs from the
+      # +References+ and +In-Reply-To+ headers of an email thread.
+      #
+      # Instances are frozen and Enumerable. Construct via +.parse+; build
+      # reply chains with +#with_parent_appended+ rather than mutating.
+      class References
+        include Enumerable
+
+        class << self
+          # Parse a list of raw header values into a +References+ chain.
+          #
+          # +nil+ entries and blank/whitespace-only strings are dropped; surviving entries are
+          # normalized via +MessageId.parse+. Duplicates are preserved.
+          #
+          # @param items [Array<String, nil>] raw message-id strings from +References+/+In-Reply-To+.
+          # @return [References] the normalized chain.
+          def parse(items)
+            parsed = items.filter_map do |item|
+              next if item.nil?
+
+              stripped = item.to_s.strip
+              next if stripped.empty?
+
+              MessageId.parse(stripped)
+            end
+            new(parsed)
+          end
+        end
+
+        # Wrap a pre-parsed array of +MessageId+s and freeze. Prefer +.parse+.
+        #
+        # @param message_ids [Array<MessageId>] the ordered chain entries.
+        def initialize(message_ids)
+          @items = message_ids.dup.freeze
+          freeze
+        end
+
+        # Yield each +MessageId+ in order.
+        #
+        # @yield [message_id] each entry in chain order.
+        # @yieldparam message_id [MessageId] the current entry.
+        # @return [Enumerator, References] an enumerator without a block, else self.
+        def each(&)
+          @items.each(&)
+        end
+
+        # Return the first +MessageId+ in the chain.
+        #
+        # @return [MessageId, nil] the first entry, or +nil+ when empty.
+        def first
+          @items.first
+        end
+
+        # Report whether the chain has no entries.
+        #
+        # @return [Boolean] +true+ when empty.
+        def empty?
+          @items.empty?
+        end
+
+        # Return the number of entries.
+        #
+        # @return [Integer] the chain length.
+        def size
+          @items.size
+        end
+
+        # Return the underlying entries as a frozen array.
+        #
+        # @return [Array<MessageId>] the chain contents.
+        def to_a
+          @items
+        end
+
+        # Return a new +References+ with +parent+ appended (immutable update).
+        #
+        # @param parent [String, MessageId] the parent id; Strings are parsed, +MessageId+s reused.
+        # @return [References] a new chain with +parent+ at the end.
+        def with_parent_appended(parent)
+          message_id = parent.is_a?(MessageId) ? parent : MessageId.parse(parent)
+          self.class.new(@items + [message_id])
+        end
+
+        # Compare by element-wise value equality.
+        #
+        # @param other [Object] the value to compare against.
+        # @return [Boolean] +true+ when +other+ is a +References+ with equal entries.
+        def ==(other)
+          other.is_a?(References) && other.to_a == @items
+        end
+        alias eql? ==
+
+        # Hash by the underlying array contents.
+        #
+        # @return [Integer] the hash code.
+        def hash
+          @items.hash
+        end
+      end
+    end
+  end
+end

data/lib/protege/gateway.rb

@@ -0,0 +1,398 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module Protege
+  # Namespace for all inbound/outbound email concerns — mail parsing,
+  # address handling, delivery transport.
+  #
+  # Module methods here are the cross-namespace entry points. Other namespaces (Orchestrator, Loop) and
+  # the Rails layer call these rather than reaching into the +Mail::*+ value objects or +AccessControl+.
+  module Gateway
+    # Native Ruby autoloads for the Gateway's value types and composer. Unlike Zeitwerk (which isn't set
+    # up yet when host +config/initializers+ run), plain +autoload+ resolves these on first reference at
+    # any time — so +Gateway.build_access_policy+ works in a boot-time initializer without eager-loading
+    # the files. Zeitwerk still manages the same paths for ordinary runtime/reloads.
+    autoload :AccessPolicy, 'protege/gateway/access_policy'
+    autoload :AccessControl, 'protege/gateway/access_control'
+    autoload :AttachmentPolicy, 'protege/gateway/attachment_policy'
+
+    extend self
+
+    # Accept a message typed into the dashboard console.
+    #
+    # Finds or creates the +EmailThread+ for +mail+, persists an inbound +Message+ marked
+    # +:pending+, and enqueues a +ConsoleInferenceJob+ (delayed one second so the record is
+    # committed and visible before the job runs). The +mail.message_id+ is propagated as the
+    # correlation id so events across the run can be traced.
+    #
+    # @param mail [::Mail::Message] the console-authored message.
+    # @param persona [Persona] the persona receiving the message.
+    # @param attachments [Array<ActiveStorage::Blob, ActiveStorage::Attachment, #original_filename, Hash>]
+    #   files for the persona to read. Each entry is normalized to a blob (see {#blob_for}) and attached by
+    #   reference (mirroring +deliver+) — an already-stored blob/attachment reuses its blob, an uploaded
+    #   file or a +{ filename:, content_type:, bytes: }+ Hash is uploaded once. Attached after +save!+ so
+    #   they are committed before the (delayed) job reads the message; the persona sees them via
+    #   +Message#content_parts+ / the +read_attachment+ tool.
+    # @return [Message] the saved inbound message record.
+    def accept_console_message(mail:, persona:, attachments: [])
+      correlation_id            = Mail::MessageId.ensure(mail.message_id).value
+      thread                    = EmailThread.find_or_create_for(mail:, persona:)
+      message                   = Message.build_from_mail(mail:, direction: :inbound, thread:, persona:)
+      message.processing_status = :pending
+      message.save!
+
+      # Drop blank entries before coercing: a console file field submits a stray "" when nothing is
+      # chosen (an empty multipart part Rack parses as an empty string). Filtering here — at the shared
+      # array intake — keeps every caller (reply, new thread, host Gateway.message) clean while blob_for
+      # stays strict for genuinely-unsupported values.
+      files = attachments.compact_blank
+      message.attachments.attach(files.map { blob_for(_1) }) if files.any?
+
+      ConsoleInferenceJob
+        .set(wait: 1.second)
+        .perform_later(message_id:     message.id,
+                       persona_id:     persona.id,
+                       correlation_id:)
+
+      message
+    end
+
+    # Send a message to a persona from the host application — the reverse of tools/resolvers.
+    #
+    # Where tools and resolvers let the agent reach *into* the app, this lets ordinary application code
+    # (a service object, controller, or state machine) hand the agent something to act on:
+    #
+    #   Protege::Gateway.message(to: 'security@acme.com', subject: 'Large transfer flagged',
+    #                            body: 'Review activity for user #678; alert ops@ if suspicious.')
+    #
+    # It is a thin convenience over +build_outbound+ + +accept_console_message+ — the exact sequence the
+    # dashboard console uses — so the brief flows through the same "inbound message starts a thread" path
+    # (+ReplyHarness+ and the persona's +message_resolvers+). +to+ is an address, not a record: it is
+    # resolved through +Persona.lookup+ (honouring case and +tag+ subaddressing), so a caller can pass a
+    # literal address or +persona.email_address+ without loading the record first.
+    #
+    # Fire-and-forget: it returns the persisted inbound +Message+ for reference/tracing, not an LLM
+    # response — the agent's actions (any mail it chooses to send) are the outcome. The persona reads it,
+    # reasons, and uses its (scoped) tools; there is nothing it must reply to.
+    #
+    # Attachments meet the host where its file already is — a stored blob/attachment (e.g.
+    # +transaction.receipt+, reused by reference), an +ActionDispatch::Http::UploadedFile+ (a controller
+    # upload, passed straight through), or a plain +{ filename:, content_type:, bytes: }+ Hash (raw/
+    # generated bytes, uploaded once). So a caller never constructs a +Gateway::Mail::Attachment+ by hand.
+    # See {#blob_for} for the full set of accepted shapes.
+    #
+    # @param to [String] the recipient persona's address (or +persona.email_address+).
+    # @param subject [String, nil] the message subject (the thread's title).
+    # @param body [String] the brief the persona acts on.
+    # @param attachments [Array] files for the persona to read; see {#accept_console_message} / {#blob_for}.
+    # @return [Message] the saved inbound message record.
+    # @raise [ArgumentError] when no active persona owns +to+, or an attachment is an unsupported shape.
+    def message(to:, body:, subject: nil, attachments: [])
+      persona = Persona.lookup(to)
+      raise ArgumentError, "no active persona for address: #{to.inspect}" unless persona
+
+      mail = build_outbound(from:    Protege.configuration.console_address,
+                            to:      persona.email_address,
+                            subject:,
+                            body:)
+
+      accept_console_message(mail:, persona:, attachments:)
+    end
+
+    # Accept an inbound email arriving via SMTP / Action Mailbox.
+    #
+    # Unlike the console path, ingestion (persisting the +Message+, building the thread) happens
+    # inside +InferenceJob+; this method only enqueues that job with the persona and the inbound
+    # email reference, carrying the mail's message id as the correlation id.
+    #
+    # @param inbound_email [ActionMailbox::InboundEmail] the ingress email record.
+    # @param persona [Persona] the persona the message was routed to.
+    # @return [void]
+    def accept_smtp_message(inbound_email:, persona:)
+      InferenceJob.perform_later(
+        persona_id:       persona.id,
+        inbound_email_id: inbound_email.id,
+        correlation_id:   Mail::MessageId.ensure(inbound_email.mail.message_id).value
+      )
+    end
+
+    # Deliver an outbound message on behalf of a persona and record it.
+    #
+    # Sends over SMTP via +mail.deliver!+ unless the recipient is the local console address, in
+    # which case the conversation stays entirely in-app. Either way the message is persisted as an
+    # +:outbound+ +Message+ on its thread with +delivered_at+ stamped to now.
+    #
+    # Attachments are persisted by *reference*: the outbound record does not rebuild them from the
+    # mail's MIME parts (which would mint a duplicate blob) — instead the caller passes the +attachments+
+    # (blobs already in storage) and they are attached directly. So a file, wherever it came from, is
+    # uploaded once and thereafter only referenced.
+    #
+    # @param mail [::Mail::Message] the outbound mail to deliver.
+    # @param persona [Persona] the sending persona.
+    # @param attachments [Array<ActiveStorage::Blob>] blobs to attach to the outbound record by reference.
+    # @return [Message] the saved outbound message record.
+    def deliver(mail:, persona:, attachments: [])
+      deliver_over_transport(mail) unless local_delivery?(mail)
+
+      thread = EmailThread.find_or_create_for(mail:, persona:)
+
+      Message.build_from_mail(
+        mail:,
+        thread:,
+        persona:,
+        direction:        :outbound,
+        attach_from_mail: false
+      ).tap do |record|
+        record.delivered_at = Time.current
+        record.attachments.attach(attachments) if attachments.any?
+        record.save!
+      end
+    end
+
+    # Build an outbound +::Mail::Message+ with Protege's threading/id/date conventions. The single
+    # place callers (controllers, the send-email tool) assemble outbound mail without touching the
+    # +Mail::Outbound+ builder directly. Keyword arguments are forwarded to the builder (+from:+, +to:+,
+    # +subject:+, +body:+, +cc:+, +bcc:+, +in_reply_to:+, +references:+, +attachments:+).
+    #
+    # @return [::Mail::Message] the composed outbound mail
+    def build_outbound(**)
+      Mail::Outbound.build(**)
+    end
+
+    # Build an inbound access policy — one layer of the sender-authorization guardrail. The public way
+    # to construct an +AccessPolicy+, whether the global ceiling (+config.inbound_access+) or a
+    # per-persona layer (+AccessRule.policy_for+). +build_+ marks it as an instance factory, not a
+    # persisted record. Keyword arguments are forwarded (+allow:+, +deny:+, +default_decision:+).
+    #
+    # @return [Protege::Gateway::AccessPolicy] the composed policy layer
+    def build_access_policy(**)
+      AccessPolicy.new(**)
+    end
+
+    # Build an attachment policy — the inbound/outbound attachment limits enforced at the mail edges.
+    # The public way to construct an +AttachmentPolicy+ (assigned as +config.attachment_policy+).
+    # +build_+ marks it as an instance factory, not a persisted record. Keyword arguments are forwarded
+    # (+enabled:+, +max_bytes:+, +max_count:+, +max_total_bytes:+).
+    #
+    # @return [Protege::Gateway::AttachmentPolicy] the attachment limits policy
+    def build_attachment_policy(**)
+      AttachmentPolicy.new(**)
+    end
+
+    # Normalize a raw Message-ID header to its canonical, angle-bracketed value.
+    #
+    # @param raw [String, nil] the raw Message-ID (or In-Reply-To) value
+    # @return [String] the canonical id
+    def canonical_message_id(raw)
+      Mail::MessageId.ensure(raw).value
+    end
+
+    # Parse a single Message-ID header to its canonical value (nil-safe on blank input).
+    #
+    # @param raw [String, nil] the raw header value
+    # @return [String, nil] the canonical id, or nil when blank
+    def parse_message_id(raw)
+      return nil if raw.blank?
+
+      Mail::MessageId.parse(raw).value
+    end
+
+    # Parse a References / In-Reply-To chain into an ordered list of canonical id strings.
+    #
+    # @param items [Array<String>, String, nil] the raw header value(s)
+    # @return [Array<String>] the ordered canonical ids
+    def reference_ids(items)
+      Mail::References.parse(Array(items)).map(&:to_s)
+    end
+
+    # The routing key (tag-stripped, lowercased +local@domain+) for an inbound recipient address.
+    #
+    # @param address [String, nil] the raw email address
+    # @return [String] the routing key
+    # @raise [ArgumentError] when the address is blank or malformed
+    def routing_key(address)
+      Mail::Address.parse(address).routing_key
+    end
+
+    # Report whether a sender may reach a persona, per the persona's inbound access guardrail.
+    #
+    # @param persona [Persona] the routed persona
+    # @param address [String, nil] the sender's address
+    # @return [Boolean] true when every access layer permits the sender
+    def permits?(persona:, address:)
+      AccessControl.for(persona:).permits?(address:)
+    end
+
+    # Report whether an inbound email is addressed to a domain Protege receives for — the Action
+    # Mailbox routing predicate. Domain-scoped on purpose: the engine claims only mail for its own
+    # domains and leaves everything else to the host's own mailbox routing, so mounting Protege never
+    # hijacks a host's other inbound mail. Per-persona/subaddress validation stays in +AgentMailbox+.
+    #
+    # @param inbound_email [ActionMailbox::InboundEmail] the received email
+    # @return [Boolean] true when any recipient's domain is one of ours
+    def claims?(inbound_email:)
+      Array(inbound_email.mail.to).any? { |address| EmailDomain.receives?(address) }
+    end
+
+    # ── MTA provisioning (push) ────────────────────────────────────────────────
+
+    # The full set of signing material the self-hosted MTA needs — every +EmailDomain+ with its DKIM
+    # key. The app pushes this whole manifest to the mail accessory on any domain change (see
+    # {#push_mail_provisioning}); the accessory rewrites its OpenDKIM/Postfix config from it, so the
+    # manifest is always complete state, never a delta.
+    #
+    # @return [Hash] +{ domains: [...] }+, one entry per domain (see +EmailDomain#to_provisioning+)
+    def mail_provisioning_manifest
+      { domains: EmailDomain.all.map(&:to_provisioning) }
+    end
+
+    # The self-hosted mail accessory's network name, or nil. Reuses the *existing* setting that already
+    # names the accessory for outbound SMTP (+config.action_mailer.smtp_settings[:address]+ =
+    # +ENV['MAIL_RELAY_HOST']+) — no separate config knob. Its presence is also the self-hosted signal:
+    # unset means provider mode, where there is no MTA to provision.
+    #
+    # @return [String, nil] the accessory host, or nil when not self-hosting
+    def mail_accessory_host
+      ENV['MAIL_RELAY_HOST'].presence
+    end
+
+    # Push the whole provisioning manifest to the mail accessory's internal control listener, which
+    # writes the DKIM keys + Postfix tables and reloads. Event-driven (called from
+    # +MailProvisioningJob+ on any +EmailDomain+ change, and by the console "Sync now" button) — no
+    # polling, no public endpoint. Authenticates with the already-shared +RAILS_INBOUND_EMAIL_PASSWORD+.
+    #
+    # A no-op in provider mode (no accessory host). Never raises: a domain save or a button click must
+    # not break because the MTA is momentarily down — failures are logged and reported in the result
+    # (the job's retry, or the button, re-pushes).
+    #
+    # @return [Hash] +{ ok:, count:, message: }+ describing the outcome
+    def push_mail_provisioning
+      host = mail_accessory_host
+      return provisioning_result(success: false, count: 0, message: 'No mail accessory configured') if host.blank?
+
+      manifest = mail_provisioning_manifest
+      deliver_provisioning(host:, manifest:)
+      count    = manifest[:domains].size
+      provisioning_result(success: true, count:, message: "Pushed #{count} domain(s) to the mail server")
+    rescue StandardError => e
+      Protege.configuration.logger.warn("[protege] mail provisioning push failed: #{e.class}: #{e.message}")
+      provisioning_result(success: false, count: 0, message: "Mail server unreachable: #{e.message}")
+    end
+
+    private
+
+    # Coerce one caller-supplied attachment into an +ActiveStorage::Blob+ to attach by reference. A blob
+    # passes through; an attachment yields its blob (both reuse storage, no new upload); a
+    # +{ filename:, content_type:, bytes: }+ Hash and an uploaded file (anything responding to
+    # +original_filename+, i.e. an +ActionDispatch::Http::UploadedFile+) are each uploaded once. Any other
+    # shape is a caller error.
+    #
+    # @param attachment [ActiveStorage::Blob, ActiveStorage::Attachment, ActionDispatch::Http::UploadedFile, Hash]
+    # @return [ActiveStorage::Blob] the blob to attach
+    # @raise [ArgumentError] on an unsupported shape
+    def blob_for(attachment)
+      case attachment
+      when ActiveStorage::Blob       then attachment
+      when ActiveStorage::Attachment then attachment.blob
+      when Hash                      then upload_blob(**attachment.symbolize_keys)
+      else                                uploaded_file_blob(attachment)
+      end
+    end
+
+    # Upload an +ActionDispatch::Http::UploadedFile+ (or any object exposing +original_filename+/
+    # +content_type+/+read+ — e.g. +Rack::Test::UploadedFile+) as a new blob. Duck-typed rather than
+    # matched by class so a controller can hand +params[...]+ uploads straight through.
+    #
+    # @param file [#original_filename, #content_type, #read] the uploaded file
+    # @return [ActiveStorage::Blob] the created blob
+    # @raise [ArgumentError] when +file+ is not an uploaded-file-like object
+    def uploaded_file_blob(file)
+      unless file.respond_to?(:original_filename)
+        raise ArgumentError,
+              "unsupported attachment #{file.class}: pass a blob, an attachment, an uploaded file, or " \
+              '{ filename:, content_type:, bytes: }'
+      end
+
+      upload_blob(filename: file.original_filename, content_type: file.content_type, bytes: file.read)
+    end
+
+    # Upload raw bytes as a new blob for a host-supplied +{ filename:, content_type:, bytes: }+ attachment.
+    #
+    # @param filename [String] the file name
+    # @param bytes [String] the raw file contents
+    # @param content_type [String, nil] the MIME type (Active Storage infers when omitted)
+    # @return [ActiveStorage::Blob] the created blob
+    def upload_blob(filename:, bytes:, content_type: nil)
+      ActiveStorage::Blob.create_and_upload!(io: StringIO.new(bytes), filename:, content_type:)
+    end
+
+    # POST the manifest JSON to the accessory's control listener over the internal network.
+    #
+    # @param host [String] the accessory network name
+    # @param manifest [Hash] the provisioning manifest to send
+    # @return [void]
+    # @raise [StandardError] on a transport error or non-2xx response (caught by the caller)
+    def deliver_provisioning(host:, manifest:)
+      uri                     = URI("http://#{host}:#{mail_provision_port}/provision")
+      request                 = Net::HTTP::Post.new(uri)
+      request.body            = manifest.to_json
+      request['Content-Type'] = 'application/json'
+      request.basic_auth('provision', ENV.fetch('RAILS_INBOUND_EMAIL_PASSWORD', ''))
+
+      Net::HTTP.start(uri.host, uri.port, open_timeout: 5, read_timeout: 10) do |http|
+        response = http.request(request)
+        raise "accessory returned HTTP #{response.code}" unless response.code.to_i.between?(200, 299)
+      end
+    end
+
+    # The accessory's internal control port. A constant (env-overridable) matched by the mail image's
+    # +provision.py+ listener — deliberately not a +Configuration+ option.
+    #
+    # @return [Integer] the control port (default 8025)
+    def mail_provision_port
+      ENV.fetch('MAIL_PROVISION_PORT', 8025).to_i
+    end
+
+    # Build the small outcome record the console flashes and callers branch on.
+    #
+    # @param success [Boolean] whether the push reached the accessory
+    # @return [Hash] +{ ok:, count:, message: }+
+    # @param [Object] count
+    # @param [Object] message
+    def provisioning_result(success:, count:, message:)
+      { ok: success, count:, message: }
+    end
+
+    # Send a raw outbound +Mail::Message+ over Action Mailer's configured transport.
+    #
+    # The Gateway builds bare +Mail::Message+ objects (via +Gateway::Mail::Outbound+), and
+    # +Mail::Message#deliver!+ on its own ignores +config.action_mailer.smtp_settings+ — it falls
+    # back to the Mail gem's default of SMTP to +localhost:25+. +wrap_delivery_behavior+ is the same
+    # hook Action Mailer applies to its own messages: it sets the delivery method, settings,
+    # +perform_deliveries+, and +raise_delivery_errors+ from +ActionMailer::Base+, so the message
+    # goes to the real SMTP host in production and to the +:test+ collector under test.
+    #
+    # @param mail [::Mail::Message] the outbound mail to send
+    # @return [void]
+    def deliver_over_transport(mail)
+      ActionMailer::Base.wrap_delivery_behavior(mail)
+      mail.deliver!
+    end
+
+    # Report whether +mail+ is addressed to the local console (no SMTP needed).
+    #
+    # Compares the first recipient's routing key (tag-stripped, lowercased +local@domain+, via
+    # +Mail::Address+) against the configured console address. A nil/malformed recipient is treated
+    # as non-local so it falls through to ordinary SMTP delivery.
+    #
+    # @param mail [::Mail::Message] the outbound mail under inspection.
+    # @return [Boolean] +true+ when the recipient is the console address.
+    def local_delivery?(mail)
+      Mail::Address.parse(Array(mail.to).first).routing_key ==
+        Mail::Address.parse(Protege.configuration.console_address).routing_key
+    rescue ArgumentError
+      false
+    end
+  end
+end