tina4ruby 3.13.37 → 3.13.38

data/lib/tina4/env.rb

@@ -74,13 +74,17 @@ module Tina4
   end
 
   module Env
+    # NOTE: TINA4_SECRET is deliberately ABSENT here. The default signing
+    # secret must never become a guessable built-in. A blank secret is the
+    # signal for Auth.ensure_dev_secret to mint a per-machine random dev secret
+    # (saved to gitignored .env.local) in dev, or to emit the actionable
+    # "set TINA4_SECRET" warning in CI/prod. Parity with the Python master.
     DEFAULT_ENV = {
       "PROJECT_NAME" => "Tina4 Ruby Project",
       "TINA4_SWAGGER_VERSION" => "1.0.0",
       "TINA4_LOCALE" => "en",
       "TINA4_DEBUG" => "true",
-      "TINA4_LOG_LEVEL" => "[TINA4_LOG_ALL]",
-      "TINA4_SECRET" => "tina4-secret-change-me"
+      "TINA4_LOG_LEVEL" => "[TINA4_LOG_ALL]"
     }.freeze
 
     # Typed env-var coercion — parity with tina4_python's Env class,
@@ -157,9 +161,27 @@ module Tina4
         unless File.exist?(env_file)
           create_default_env(env_file)
         end
+        # Precedence: real-env > .env.local > .env. Both loads are first-wins
+        # (override=false / `ENV[key] ||= value`), so a key already present in
+        # the real process environment is NEVER clobbered. .env.local loads
+        # FIRST so its values beat .env, but a real env var set before boot
+        # still wins over both. This is the security-correct ordering: a stray
+        # gitignored .env.local (e.g. a stale auto-generated dev secret) must
+        # not override an explicitly-set real TINA4_SECRET. The ensure-dev-secret
+        # bootstrap runs AFTER this (only mints a secret if still unset in dev).
+        load_local_env(root_dir)
         parse_env_file(env_file)
       end
 
+      # Load .env.local with first-wins semantics (override=false). A real
+      # process env var already present wins; this only fills keys not already
+      # set. Loaded BEFORE .env so .env.local beats .env (real-env > .env.local
+      # > .env). No-op when the file is absent (common for fresh checkouts).
+      def load_local_env(root_dir = Dir.pwd)
+        local_file = File.join(root_dir, ".env.local")
+        parse_env_file(local_file) if File.exist?(local_file)
+      end
+
       # Get an env var value, with optional default
       def get_env(key, default = nil)
         ENV[key.to_s] || default
@@ -213,7 +235,17 @@ module Tina4
         File.write(path, content)
       end
 
-      def parse_env_file(path)
+      # Parse a dotenv file into ENV.
+      #
+      # override=false (default): `ENV[key] ||= value` — first-wins; a key
+      # already present (real env var, or a higher-precedence file loaded
+      # earlier) is never clobbered. Both .env.local and .env are loaded this
+      # way; ordering (.env.local first) gives the precedence real-env >
+      # .env.local > .env.
+      # override=true: `ENV[key] = value` — unconditional set. NOT used by the
+      # boot load sequence; kept only as an explicit opt-in for callers that
+      # genuinely need to force values.
+      def parse_env_file(path, override: false)
         return unless File.exist?(path)
         File.readlines(path).each do |line|
           line = line.strip
@@ -221,7 +253,11 @@ module Tina4
           if (match = line.match(/\A([A-Za-z_][A-Za-z0-9_]*)=["']?(.*)["']?\z/))
             key = match[1]
             value = match[2].gsub(/["']\z/, "")
-            ENV[key] ||= value
+            if override
+              ENV[key] = value
+            else
+              ENV[key] ||= value
+            end
             @loaded_keys ||= []
             @loaded_keys << key
           end

data/lib/tina4/events.rb

@@ -60,13 +60,28 @@ module Tina4
       #
       #   results = Tina4::Events.emit("user.created", user_data)
       #
-      def emit(event, *args)
+      # Listener isolation (visible-but-resilient): each listener is called
+      # inside a rescue so ONE throwing listener never aborts the rest of the
+      # emit. A failed listener is LOGGED (never silent) and contributes a nil
+      # slot, so N listeners always yield N results in priority order. Pass
+      # strict: true to RE-RAISE on the first listener error instead of
+      # isolating (later listeners then do NOT run).
+      def emit(event, *args, strict: false)
         entries = @listeners[event].dup
         results = []
         entries.each do |entry|
-          # Remove one-time listeners before calling so re-entrant emits are safe
+          # Remove one-time listeners before calling so re-entrant emits are
+          # safe AND so the one-shot is gone before any throw — cleanup stays
+          # correct under isolation.
           @listeners[event].delete(entry) if entry[:once]
-          results << entry[:callback].call(*args)
+          begin
+            results << entry[:callback].call(*args)
+          rescue StandardError, ScriptError => error
+            raise if strict
+
+            log_listener_error(event, error)
+            results << nil
+          end
         end
         results
       end
@@ -82,19 +97,29 @@ module Tina4
       end
 
       # Fire an event asynchronously. Each listener runs in its own thread.
-      # Errors in listeners are silently caught.
       #
       #   Tina4::Events.emit_async("user.created", user_data)
       #
-      def emit_async(event, *args)
+      # Listener isolation: each threaded listener is wrapped so one rejection
+      # never aborts the others. A failed listener is LOGGED (never silent).
+      # Pass strict: true to RE-RAISE the first listener error on the main
+      # thread (the thread that raised aborts on join) instead of isolating.
+      def emit_async(event, *args, strict: false)
         return unless @listeners&.key?(event)
 
-        @listeners[event].sort_by { |l| -(l[:priority] || 0) }.each do |listener|
+        @listeners[event].sort_by { |l| -(l[:priority] || 0) }.map do |listener|
           Thread.new do
+            # In strict mode the error is re-raised to surface on #join; mute
+            # the per-thread auto-report so the deliberate raise doesn't spam
+            # stderr (the caller still sees it via join).
+            Thread.current.report_on_exception = false if strict
             begin
               listener[:callback].call(*args)
-            rescue => e
-              # Async emit silently catches errors
+            rescue StandardError, ScriptError => error
+              raise if strict
+
+              log_listener_error(event, error)
+              nil
             end
           end
         end
@@ -104,6 +129,27 @@ module Tina4
       def clear
         @listeners.clear
       end
+
+      private
+
+      # NEVER silently swallow a listener error — always surface it. Logs via
+      # Tina4::Log.warning with BOTH the event name and the error class+message.
+      # Wrapped so a broken logger can't break the bus: on any logger failure it
+      # falls back to $stderr so the error is still seen.
+      def log_listener_error(event, error)
+        Tina4::Log.warning(
+          "Event listener for '#{event}' raised #{error.class.name}: #{error.message}"
+        )
+      rescue StandardError
+        begin
+          $stderr.puts(
+            "Event listener for '#{event}' raised #{error.class.name}: #{error.message}"
+          )
+          $stderr.flush
+        rescue StandardError
+          # Last-resort: never let logging break the event bus.
+        end
+      end
     end
   end
 end

data/lib/tina4/graphql.rb

@@ -463,12 +463,33 @@ module Tina4
         arguments = parse_arguments
       end
 
+      # Directives (@skip, @include, @auth, @role, @guest, ...) appear after the
+      # field's arguments and before its selection set. Without parsing them the
+      # executor's check_directives never fires — @skip/@include are silently
+      # ignored. Each directive is { name:, arguments: } to match check_directives.
+      directives = parse_directives
+
       selection_set = nil
       if current&.value == "{"
         selection_set = parse_selection_set
       end
 
-      { kind: :field, name: field_name, alias: alias_name, arguments: arguments, selection_set: selection_set }
+      { kind: :field, name: field_name, alias: alias_name, arguments: arguments, directives: directives, selection_set: selection_set }
+    end
+
+    # Parse a run of leading @directive(args) tokens into an array of
+    # { name:, arguments: } hashes (the shape GraphQLExecutor#check_directives
+    # consumes). Returns [] when no directive is present.
+    def parse_directives
+      directives = []
+      while current && current.type == :punct && current.value == "@"
+        advance # consume '@'
+        name = expect(:name).value
+        args = {}
+        args = parse_arguments if current&.value == "("
+        directives << { name: name, arguments: args }
+      end
+      directives
     end
 
     def parse_arguments
@@ -575,8 +596,13 @@ module Tina4
   # ─── Executor ─────────────────────────────────────────────────────────
 
   class GraphQLExecutor
-    def initialize(schema)
+    # max_depth bounds selection-set nesting (DoS / stack-overflow guard).
+    # Threaded down from the owning GraphQL instance; <= 0 disables the guard.
+    attr_accessor :max_depth
+
+    def initialize(schema, max_depth: 50)
       @schema = schema
+      @max_depth = max_depth
     end
 
     def execute(document, variables: {}, context: {}, operation_name: nil)
@@ -618,8 +644,12 @@ module Tina4
       data = {}
       errors = []
 
+      # Top-level selections start at depth 1. Depth is incremented on every
+      # recursive entry (sub-selections, fragment spreads, inline fragments) so
+      # an over-deep query OR a circular fragment is caught before the
+      # interpreter stack overflows.
       operation[:selection_set].each do |selection|
-        resolve_selection(selection, root_fields, nil, resolved_vars, context, fragments, data, errors)
+        resolve_selection(selection, root_fields, nil, resolved_vars, context, fragments, data, errors, 1)
       end
 
       result = { "data" => data }
@@ -629,25 +659,31 @@ module Tina4
 
     private
 
-    def resolve_selection(selection, fields, parent, variables, context, fragments, data, errors)
+    def resolve_selection(selection, fields, parent, variables, context, fragments, data, errors, depth = 1)
+      # Depth guard — append a structured error and stop recursing this branch.
+      if @max_depth && @max_depth > 0 && depth > @max_depth
+        errors << { "message" => "Query exceeds maximum depth of #{@max_depth}" }
+        return
+      end
+
       case selection[:kind]
       when :field
-        resolve_field(selection, fields, parent, variables, context, fragments, data, errors)
+        resolve_field(selection, fields, parent, variables, context, fragments, data, errors, depth)
       when :fragment_spread
         frag = fragments[selection[:name]]
         if frag
           frag[:selection_set].each do |sel|
-            resolve_selection(sel, fields, parent, variables, context, fragments, data, errors)
+            resolve_selection(sel, fields, parent, variables, context, fragments, data, errors, depth + 1)
           end
         end
       when :inline_fragment
         selection[:selection_set].each do |sel|
-          resolve_selection(sel, fields, parent, variables, context, fragments, data, errors)
+          resolve_selection(sel, fields, parent, variables, context, fragments, data, errors, depth + 1)
         end
       end
     end
 
-    def resolve_field(selection, fields, parent, variables, context, fragments, data, errors)
+    def resolve_field(selection, fields, parent, variables, context, fragments, data, errors, depth = 1)
       field_name = selection[:name]
       output_name = selection[:alias] || field_name
 
@@ -687,7 +723,7 @@ module Tina4
               nested = {}
               sub_fields = item.is_a?(Hash) ? item_fields(item) : {}
               selection[:selection_set].each do |sel|
-                resolve_selection(sel, sub_fields, item, variables, context, fragments, nested, errors)
+                resolve_selection(sel, sub_fields, item, variables, context, fragments, nested, errors, depth + 1)
               end
               nested
             end
@@ -695,7 +731,7 @@ module Tina4
             nested = {}
             sub_fields = item_fields(value)
             selection[:selection_set].each do |sel|
-              resolve_selection(sel, sub_fields, value, variables, context, fragments, nested, errors)
+              resolve_selection(sel, sub_fields, value, variables, context, fragments, nested, errors, depth + 1)
             end
             data[output_name] = nested
           else
@@ -705,7 +741,12 @@ module Tina4
           data[output_name] = coerce_value(value)
         end
       rescue => e
-        errors << { "message" => e.message, "path" => [output_name] }
+        # Log the real cause; only surface the detail to the client in debug
+        # mode — a resolver exception can carry internal state (DB errors,
+        # credentials) that must not leak. Mirrors the Python master.
+        Tina4::Log.error("GraphQL resolver '#{field_name}' failed: #{e.message}")
+        detail = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"]) ? e.message : "Internal server error"
+        errors << { "message" => detail, "path" => [output_name] }
         data[output_name] = nil
       end
     end
@@ -845,6 +886,16 @@ module Tina4
   class GraphQL
     attr_reader :schema
 
+    # Maximum selection-set nesting depth (DoS / stack-overflow guard).
+    # Read from TINA4_GRAPHQL_MAX_DEPTH (default 50; <= 0 disables). Exposed so
+    # tests/app code can override it; the writer keeps the executor in sync.
+    attr_reader :max_depth
+
+    def max_depth=(value)
+      @max_depth = value
+      @executor&.max_depth = value
+    end
+
     # Class-level toggle for ORM auto-schema generation. Defaults to true,
     # can be disabled via TINA4_GRAPHQL_AUTO_SCHEMA=false. Initializers and
     # user app code can branch on this before calling `schema.from_orm(...)`.
@@ -912,7 +963,12 @@ module Tina4
 
     def initialize(schema = nil)
       @schema = schema || GraphQLSchema.new
-      @executor = GraphQLExecutor.new(@schema)
+      # Maximum selection-set nesting depth. A deeply nested query (or a
+      # circular fragment) would otherwise recurse without bound — a classic
+      # GraphQL DoS / stack-overflow vector. Default 50 is far beyond any
+      # legitimate query; TINA4_GRAPHQL_MAX_DEPTH <= 0 disables the guard.
+      @max_depth = Integer(ENV.fetch("TINA4_GRAPHQL_MAX_DEPTH", "50"), exception: false) || 50
+      @executor = GraphQLExecutor.new(@schema, max_depth: @max_depth)
       @field_resolvers = {}
 
       # Drain any resolvers registered via the class-level GraphQL.resolve()

data/lib/tina4/html_element.rb

@@ -1,6 +1,30 @@
 # frozen_string_literal: true
 
 module Tina4
+  # Marker for trusted, pre-sanitised HTML that must render UNESCAPED.
+  #
+  # String/scalar children of an HtmlElement are HTML-escaped by default to
+  # prevent stored/reflected XSS. Wrap a value in Raw to opt out of escaping
+  # when (and only when) you have already sanitised it yourself.
+  #
+  #   Tina4::HtmlElement.new("div").call("<b>x</b>")             # &lt;b&gt;x&lt;/b&gt;  (escaped)
+  #   Tina4::HtmlElement.new("div").call(Tina4::Raw.new("<b>x</b>"))  # <b>x</b>         (raw)
+  #
+  # Raw is the primary name; SafeString is the alias (and is the same class
+  # Frond already uses to mark trusted output, so a SafeString returned by a
+  # Frond filter also renders raw as an HtmlElement child). Defined defensively
+  # in case this file is ever loaded before Frond.
+  SafeString = Class.new(String) unless defined?(Tina4::SafeString)
+
+  # Primary name for the trusted-markup wrapper — an alias of SafeString.
+  Raw = SafeString
+
+  # Convenience constructor so callers can write Tina4::Raw("<b>x</b>")
+  # in addition to Tina4::Raw.new("<b>x</b>").
+  def self.Raw(value)
+    Raw.new(value.to_s)
+  end
+
   # Programmatic HTML builder — avoids string concatenation.
   #
   # Usage:
@@ -14,6 +38,9 @@ module Tina4
   #   include Tina4::HtmlHelpers
   #   html = _div({ class: "card" }, _p("Hello"))
   #
+  # String/scalar children are HTML-escaped by default to defeat XSS; nested
+  # HtmlElement children render themselves (already escaped, no double-escape);
+  # a Raw / SafeString child renders verbatim (explicit opt-in for trusted markup).
   class HtmlElement
     VOID_TAGS = %w[
       area base br col embed hr img input
@@ -90,12 +117,7 @@ module Tina4
         when false, nil
           next
         else
-          escaped = value.to_s
-            .gsub("&", "&amp;")
-            .gsub('"', "&quot;")
-            .gsub("<", "&lt;")
-            .gsub(">", "&gt;")
-          html << " #{key}=\"#{escaped}\""
+          html << " #{key}=\"#{escape_text(value.to_s)}\""
         end
       end
 
@@ -107,12 +129,38 @@ module Tina4
       html << ">"
 
       @children.each do |child|
-        html << child.to_s
+        case child
+        when HtmlElement
+          # Nested elements render themselves (they already escape their own
+          # children) — emit as-is to avoid double-escaping.
+          html << child.to_s
+        when Raw
+          # Explicitly trusted markup — emit unescaped. Raw subclasses String,
+          # so this branch MUST come before the generic scalar escape below.
+          html << child.to_s
+        else
+          # Plain string/scalar child — escape to defeat stored/reflected XSS.
+          html << escape_text(child.to_s)
+        end
       end
 
       html << "</#{@tag}>"
       html
     end
+
+    private
+
+    # HTML-escape a string for safe inclusion in text content or a
+    # double-quoted attribute value. Mirrors Python's html.escape(quote=True):
+    # & < > " ' are all encoded.
+    def escape_text(value)
+      value
+        .gsub("&", "&amp;")
+        .gsub("<", "&lt;")
+        .gsub(">", "&gt;")
+        .gsub('"', "&quot;")
+        .gsub("'", "&#x27;")
+    end
   end
 
   # Module providing _div, _p, _span, etc. helper methods.

data/lib/tina4/mcp.rb

@@ -651,9 +651,16 @@ module Tina4
         db = Tina4.database
         return { "error" => "No database connection" } if db.nil?
         param_list = params.is_a?(String) ? JSON.parse(params) : params
-        result = db.execute(sql, param_list)
-        db.commit rescue nil
-        { "success" => true, "affected_rows" => (result.respond_to?(:count) ? result.count : 0) }
+        # db.execute() now RAISES on a SQL error (it no longer returns false).
+        # Catch it and return a clean { error: } payload instead of letting the
+        # exception escape the tool handler.
+        begin
+          result = db.execute(sql, param_list)
+          db.commit rescue nil
+          { "success" => true, "affected_rows" => (result.respond_to?(:count) ? result.count : 0) }
+        rescue => e
+          { "error" => db.get_error || e.message }
+        end
       }, "Execute arbitrary SQL (INSERT/UPDATE/DELETE/DDL)")
 
       server.register_tool("database_tables", lambda {

data/lib/tina4/messenger.rb

@@ -13,8 +13,44 @@ end
 require "base64"
 require "securerandom"
 require "time"
+require "socket"
+require "timeout"
+begin
+  require "openssl"
+rescue LoadError
+  # openssl is part of stdlib; absence only affects TLS error classification
+end
 
 module Tina4
+  # Raised on a messenger failure (base class).
+  class MessengerError < StandardError; end
+
+  # Raised when an IMAP read fails to connect, authenticate, or speak the
+  # protocol. Distinct from a successful fetch that simply has no messages —
+  # that still returns an empty result ([]/nil/0/{}), NOT an error.
+  #
+  # Subclasses MessengerError so existing `rescue Tina4::MessengerError`
+  # handlers still catch it.
+  class MessengerConnectionError < MessengerError; end
+
+  # Errors that mean "we could not talk to the mail server", as opposed to
+  # "we talked fine and the mailbox is empty". These must fail loud — LOG and
+  # RAISE — never be silently swallowed into an empty result. Mirrors the
+  # Python master's _IMAP_CONNECTION_ERRORS tuple.
+  #
+  # Built lazily so a missing net/imap gem (LoadError above) doesn't break
+  # loading this file.
+  IMAP_CONNECTION_ERRORS = [
+    SocketError,            # DNS / host resolution failures
+    IOError,                # closed/broken stream, EOF mid-conversation
+    SystemCallError,        # Errno::ECONNREFUSED / ECONNRESET / ETIMEDOUT etc.
+    Timeout::Error,         # connect/read timeout (Net::OpenTimeout descends from this)
+    MessengerError          # our own protocol-failure signal (re-raised as-is)
+  ].tap do |errors|
+    errors << Net::IMAP::Error if defined?(Net::IMAP::Error)
+    errors << OpenSSL::SSL::SSLError if defined?(OpenSSL::SSL::SSLError)
+  end.freeze
+
   # Tina4 Messenger — Email sending (SMTP) and reading (IMAP).
   #
   # Unified .env-driven configuration with constructor override.
@@ -120,9 +156,14 @@ module Tina4
 
     # ── IMAP operations ──────────────────────────────────────────────────
 
-    # List messages in a folder
+    # List messages in a folder.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/auth/protocol
+    # failure (FAILS LOUD — never returns [] to hide it). A successful fetch
+    # from an empty folder returns [] (that is NOT an error).
     def inbox(folder: "INBOX", limit: 20, offset: 0)
-      imap_connect do |imap|
+      imap = imap_open("inbox")
+      begin
         imap.select(folder)
         uids = imap.uid_search(["ALL"])
         uids = uids.reverse # newest first
@@ -131,15 +172,20 @@ module Tina4
 
         envelopes = imap.uid_fetch(page, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
         (envelopes || []).map { |msg| parse_envelope(msg) }
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("inbox", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP inbox failed: #{e.message}")
-      []
     end
 
-    # Read a single message by UID
+    # Read a single message by UID.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
+    # A successful fetch for a non-existent UID returns nil (that is NOT an error).
     def read(uid, folder: "INBOX", mark_read: true)
-      imap_connect do |imap|
+      imap = imap_open("read")
+      begin
         imap.select(folder)
         data = imap.uid_fetch(uid, ["ENVELOPE", "FLAGS", "BODY[]", "RFC822.SIZE"])
         return nil if data.nil? || data.empty?
@@ -150,28 +196,38 @@ module Tina4
 
         msg = data.first
         parse_full_message(msg)
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("read", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP read failed: #{e.message}")
-      nil
     end
 
-    # Count unread messages
+    # Count unread messages.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
+    # A successful query with no unseen messages returns 0 (NOT an error).
     def unread(folder: "INBOX")
-      imap_connect do |imap|
+      imap = imap_open("unread")
+      begin
         imap.select(folder)
         uids = imap.uid_search(["UNSEEN"])
         uids.length
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("unread", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP unread count failed: #{e.message}")
-      0
     end
 
-    # Search messages with filters
+    # Search messages with filters.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
+    # A successful search with no matches returns [] (NOT an error).
     def search(folder: "INBOX", subject: nil, sender: nil, since: nil,
                before: nil, unseen_only: false, limit: 20)
-      imap_connect do |imap|
+      imap = imap_open("search")
+      begin
         imap.select(folder)
         criteria = build_search_criteria(
           subject: subject, sender: sender, since: since,
@@ -184,21 +240,26 @@ module Tina4
 
         envelopes = imap.uid_fetch(page, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
         (envelopes || []).map { |msg| parse_envelope(msg) }
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("search", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP search failed: #{e.message}")
-      []
     end
 
-    # List all IMAP folders
+    # List all IMAP folders.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
     def folders
-      imap_connect do |imap|
+      imap = imap_open("folders")
+      begin
         boxes = imap.list("", "*")
         (boxes || []).map(&:name)
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("folders", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP folders failed: #{e.message}")
-      []
     end
 
     # Mark a message as read (set \Seen flag).
@@ -393,6 +454,50 @@ module Tina4
 
     # ── IMAP helpers ─────────────────────────────────────────────────────
 
+    # Open and authenticate an IMAP connection. On a connection/auth/protocol
+    # failure this FAILS LOUD — logs and raises MessengerConnectionError —
+    # rather than swallowing the error into an empty result.
+    def imap_open(method)
+      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
+      imap.login(@username, @password)
+      imap
+    rescue *IMAP_CONNECTION_ERRORS => e
+      raise imap_fail(method, e)
+    end
+
+    # Best-effort teardown of an IMAP connection. Never raises.
+    def imap_cleanup(imap)
+      return if imap.nil?
+
+      begin
+        imap.logout
+      rescue StandardError
+        # ignore — already closing
+      end
+      begin
+        imap.disconnect
+      rescue StandardError
+        # ignore — already closed
+      end
+    end
+
+    # Log an IMAP connection/protocol failure and return the error to raise.
+    # A genuinely empty mailbox is NOT an error and never reaches here.
+    # Re-raises a MessengerError as-is; otherwise wraps in
+    # MessengerConnectionError. Callers do `raise imap_fail(name, exc)`.
+    def imap_fail(method, exc)
+      Tina4::Log.error(
+        "Messenger IMAP #{method}() failed: #{exc.class}: #{exc.message}"
+      )
+      return exc if exc.is_a?(MessengerError)
+
+      MessengerConnectionError.new("IMAP #{method} failed: #{exc.message}")
+    end
+
+    # Connect, yield, then tear down — used by the mutators / connectivity test
+    # that keep their own result-style error handling (mark_read,
+    # test_imap_connection). Read methods use imap_open + ensure directly so
+    # they can fail loud.
     def imap_connect(&block)
       imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
       imap.login(@username, @password)