teems 0.3.2 → 0.8.0

data/lib/teems/services/sync_dir_ownership.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Keeps every chat directory owned by exactly one chat.
+    #
+    # Older teems versions could give several chats the same directory (see SyncDirNaming), and
+    # syncing then merged their messages there. Stored messages carry no chat ID, so a shared
+    # directory can't be split back into its chats reliably. Instead it is detached: the directory
+    # and its files are left untouched, and each chat that used it forgets it (recording the path
+    # under 'legacy_shared_dir') and re-syncs into its own directory, starting from the oldest
+    # message in the shared one ('resync_from') so no history is left behind only there.
+    module SyncDirOwnership
+      # One chat's claim on a directory relative to chats/. A detached claim (attached: false) is a
+      # directory the chat no longer syncs into but whose files still hold its older messages.
+      DirClaim = Data.define(:chat_id, :path, :attached) do
+        def key = SyncDirOwnership.fold(path)
+
+        # A chat's claims: the directory it syncs into, and the shared one it was detached from
+        def self.for_entry(chat_id, entry)
+          name, legacy = entry.values_at('dir_name', 'legacy_shared_dir')
+          own = new(chat_id, File.join(SyncDirNaming.type_dir(entry['chat_type']), name), true) if name
+          [own, (new(chat_id, legacy, false) if legacy)].compact
+        end
+      end
+
+      # Directory names compare case-insensitively and NFC-normalized, as on macOS and Windows
+      def self.fold(path) = path.unicode_normalize(:nfc).downcase(:fold)
+
+      # Directories that more than one chat has synced into, with the chats still syncing into
+      # them: { "groups/Group Chat (19_abc)" => [chat_id, ...] }. With only:, just that chat.
+      # Chats that never synced (404 on their first sync) don't count: nothing of theirs is there.
+      def shared_dirs(state, only: nil)
+        owner_claims(state.fetch('chats', {})).group_by(&:key).values.filter_map do |claims|
+          shared_dir_entry(claims, only)
+        end.to_h
+      end
+
+      # Detaches shared directories (see #shared_dirs) from their chats; returns what it detached
+      def detach_shared_dirs(state, only: nil)
+        shared = shared_dirs(state, only: only)
+        chats = state['chats']
+        oldest = shared.keys.to_h { |path| [path, oldest_message_time(path)] }
+        shared.flat_map { |path, ids| ids.product([path]) }.each do |id, path|
+          detach_entry(chats[id], path, oldest[path])
+        end
+        shared
+      end
+
+      # Directories chats were detached from that still exist: { path => [chat_id, ...] }
+      def legacy_shared_dirs(state)
+        detached = dir_claims(state.fetch('chats', {})).reject(&:attached)
+        existing = detached.group_by(&:path).select { |path, _claims| File.directory?(chats_path(path)) }
+        existing.transform_values { |claims| claims.map(&:chat_id) }
+      end
+
+      # Where a detached chat's re-sync starts: the oldest message in the directory it left
+      def resync_from(state, chat_id) = parse_synced_at(state.dig('chats', chat_id, 'resync_from'))
+
+      private
+
+      def owner_claims(chats) = dir_claims(chats.select { |_id, entry| ever_synced?(entry) })
+
+      def dir_claims(chats) = chats.flat_map { |id, entry| DirClaim.for_entry(id, entry) }
+
+      # Only update_chat_state writes the first two. last_synced_at alone isn't enough: cursors get
+      # cleared to force a re-fetch, which doesn't make the chat's existing files go away. A detached
+      # chat's older messages are in its legacy_shared_dir.
+      def ever_synced?(entry) = entry.values_at('last_synced_at', 'message_count', 'legacy_shared_dir').any?
+
+      def shared_dir_entry(claims, only)
+        return if claims.map(&:chat_id).uniq.one?
+
+        attached = claims.select(&:attached)
+        ids = attached.map(&:chat_id)
+        ids &= [only] if only
+        [attached.first.path, ids] unless ids.empty?
+      end
+
+      # Any claim by another chat blocks a new name, even one that never synced (it may be mid-run)
+      def dir_claimed?(others, path) = claims_dir?(dir_claims(others), path)
+
+      # Whether another chat has files in the directory, so it must not be moved or reused
+      def owned?(others, path) = claims_dir?(owner_claims(others), path)
+
+      def claims_dir?(claims, path)
+        key = SyncDirOwnership.fold(path)
+        claims.any? { |claim| claim.key == key }
+      end
+
+      def fallback_dir_name(chat_id) = "#{sanitize_id(chat_id)}-#{Digest::SHA256.hexdigest(chat_id)[0, 8]}"
+
+      def detach_entry(entry, path, oldest)
+        entry.delete('dir_name')
+        entry.delete('last_synced_at')
+        entry['legacy_shared_dir'] = path
+        entry['resync_from'] = oldest.iso8601 if oldest
+      end
+
+      # Read-only on purpose: unlike load_json_or_default it never renames a corrupt file
+      def oldest_message_time(path)
+        messages = JSON.parse(File.read(File.join(chats_path(path), 'messages.json')))
+        Array(messages).filter_map { |msg| parse_synced_at(msg['created_at']) if msg.is_a?(Hash) }.min
+      rescue SystemCallError, JSON::ParserError
+        nil
+      end
+
+      def chats_path(path) = File.join(sync_dir, SyncStore::CHATS_DIR, path)
+    end
+  end
+end

data/lib/teems/services/sync_dir_planning.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Decides which directory each chat syncs into.
+    #
+    # Existing directory names are kept, so upgrading doesn't rename everything. A chat gets a new
+    # "<name> (<full ID>)" directory (see SyncDirNaming) only when it is new, was detached from a
+    # shared directory, or its display name or type changed. The name is checked against every
+    # other chat's directories when it is assigned, which is what prevents collisions.
+    #
+    # plan_chat_dir only updates state, so a dry run can preview every move; ensure_chat_dir also
+    # carries the move out on disk.
+    module SyncDirPlanning
+      # A chat's directory change, with paths relative to chats/. Kinds:
+      #   :kept     same directory as before
+      #   :new      first directory for the chat
+      #   :split    new directory for a chat detached from the shared directory in from
+      #   :release  new directory; from holds another chat's files too, so it stays put
+      #   :move     from will be (or was) renamed to to
+      #   :repoint  to already exists, so the chat switches to it and from is left in place
+      #   :retarget from no longer exists (e.g. an interrupted run already moved it)
+      DirMove = Data.define(:chat_id, :from, :to, :kind) do
+        def to_s = "#{from} → #{to}"
+      end
+
+      # A chat's state entry plus the display name and type this sync found for it. A nil name or
+      # type means unknown (sync --chat has no chat metadata), so the stored one is kept.
+      ChatDirRequest = Data.define(:chat_id, :entry, :wanted, :migrate) do
+        def self.build(chats, chat_info)
+          chat_id = chat_info[:chat_id]
+          entry = chats[chat_id] ||= {}
+          wanted = { 'display_name' => chat_info[:display_name] || entry['display_name'],
+                     'chat_type' => chat_info[:chat_type] || entry['chat_type'] }
+          new(chat_id, entry, wanted, chat_info[:migrate])
+        end
+
+        def current_dir
+          name = entry['dir_name']
+          dir_for(name, entry['chat_type']) if name
+        end
+
+        # migrate: true treats every chat as changed, giving it a full-ID name
+        def unchanged? = !migrate && entry.slice('display_name', 'chat_type') == wanted
+
+        def display_name = wanted['display_name']
+
+        def wanted_dir(name) = dir_for(name, wanted['chat_type'])
+
+        def assign(name)
+          entry.merge!('dir_name' => name, 'chat_type' => wanted['chat_type'])
+          wanted_dir(name)
+        end
+
+        # The move for a chat that had no directory: from is the shared one it was detached from
+        def first_move(to)
+          legacy = entry['legacy_shared_dir']
+          DirMove.new(chat_id, legacy, to, legacy ? :split : :new)
+        end
+
+        private
+
+        def dir_for(name, chat_type) = File.join(SyncDirNaming.type_dir(chat_type), name)
+      end
+
+      # Picks the chat's directory and records it in state without touching the filesystem
+      def plan_chat_dir(state, chat_info)
+        chat_id = chat_info[:chat_id]
+        chats = state['chats'] ||= {}
+        request = ChatDirRequest.build(chats, chat_info)
+        others = chats.except(chat_id)
+        from = request.current_dir
+        to = keep_dir?(request, others, from) ? from : assign_dir(request, others, chat_id)
+        from ? DirMove.new(chat_id, from, to, existing_dir_kind(others, from, to)) : request.first_move(to)
+      end
+
+      # Like plan_chat_dir, then renames the old directory when that is safe. If the rename fails, the
+      # chat's entry is restored so state never points at a directory its files weren't moved to.
+      def ensure_chat_dir(state, chat_info:)
+        entry = (state['chats'] ||= {})[chat_info[:chat_id]] ||= {}
+        saved = entry.dup
+        move = plan_chat_dir(state, chat_info)
+        rename_chat_dir(move) if move.kind == :move
+        move
+      rescue SystemCallError
+        entry.replace(saved)
+        raise
+      end
+
+      # Records directory changes (paths relative to root) as dir-maps/<time>.json; returns its path
+      def write_dir_map(moves, time: Time.now)
+        dir = File.join(sync_dir, 'dir-maps')
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "#{time.strftime('%Y%m%d-%H%M%S')}.json")
+        map = { 'root' => File.join(sync_dir, SyncStore::CHATS_DIR), 'moves' => moves.map(&:to_h) }
+        atomic_write(path, JSON.pretty_generate(map))
+        path
+      end
+
+      private
+
+      def keep_dir?(request, others, from) = from && request.unchanged? && !owned?(others, from)
+
+      def assign_dir(request, others, chat_id)
+        name = build_dir_name(chat_id, request.display_name)
+        name = fallback_dir_name(chat_id) if dir_claimed?(others, request.wanted_dir(name))
+        request.assign(name)
+      end
+
+      def existing_dir_kind(others, from, to)
+        return :kept if from == to
+        return :release if owned?(others, from)
+
+        from_path = chats_path(from)
+        return :retarget unless File.directory?(from_path)
+
+        target_taken?(from_path, chats_path(to)) ? :repoint : :move
+      end
+
+      # On a case-insensitive volume a case-only rename finds the chat's own directory at the new path
+      def target_taken?(from_path, to_path) = File.exist?(to_path) && !File.identical?(from_path, to_path)
+
+      def rename_chat_dir(move)
+        new_path = chats_path(move.to)
+        FileUtils.mkdir_p(File.dirname(new_path))
+        File.rename(chats_path(move.from), new_path)
+      end
+    end
+  end
+end

data/lib/teems/services/sync_engine.rb

@@ -23,7 +23,8 @@ module Teems
             { 'type' => reaction[:type], 'count' => reaction[:count] }
           end,
           'attachments' => message.attachments, 'importance' => message.importance,
-          'edited' => message.edited, 'mentions' => message.mentions
+          'edited' => message.edited, 'mentions' => message.mentions,
+          'images' => message.images.map(&:as_json)
         }
       end
 
@@ -49,7 +50,8 @@ module Teems
           attachments: stored_default(data, 'attachments', []),
           importance: data['importance'],
           edited: stored_default(data, 'edited', false),
-          mentions: stored_default(data, 'mentions', []) }
+          mentions: stored_default(data, 'mentions', []),
+          images: Array(data['images']).filter_map { |image| Models::InlineImage.from_h(image) } }
       end
 
       def stored_default(data, key, fallback) = data[key] || fallback
@@ -140,10 +142,11 @@ module Teems
         filter_and_sort_messages(messages, start_time)
       end
 
-      def merge_and_write(chat, existing_raw, new_messages)
+      # Yields (chat_dir, merged_messages) before writing, e.g. to save inline images first
+      def merge_and_write(chat, existing_raw, new_messages, &)
         existing = existing_raw.map { |data| message_from_stored(data) }
         all_messages = merge_messages(existing, new_messages)
-        write_chat_files(chat, all_messages)
+        write_chat_files(chat, all_messages, &)
         all_messages
       end
 
@@ -172,10 +175,13 @@ module Teems
       def index_by_id(messages) = messages.to_h { |msg| [msg.id, msg] }
 
       def write_chat_files(chat, messages)
-        fmt = Formatters::MarkdownFormatter.new(chat_name: chat.display_name,
-                                                chat_type: chat.chat_type, synced_at: Time.now)
+        chat_id = chat.id
+        chat_dir = @sync_store.chat_dir(chat_id, state: @state)
+        yield(chat_dir, messages) if block_given?
+        fmt = Formatters::MarkdownFormatter.new(chat_name: chat.display_name, chat_type: chat.chat_type,
+                                                synced_at: Time.now, image_link: SyncImages.link_resolver(chat_dir))
         json = JSON.pretty_generate(messages.map { |msg| message_to_hash(msg) })
-        @sync_store.write_messages(chat.id, messages_md: fmt.format(messages), messages_json: json, state: @state)
+        @sync_store.write_messages(chat_id, messages_md: fmt.format(messages), messages_json: json, state: @state)
         write_metadata(chat)
       end
 

data/lib/teems/services/sync_images.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Inline images saved beside a synced chat (`teems sync --images`) and linked from messages.md.
+    # Files are named by AMS object id, so images already on disk are never fetched again.
+    class SyncImages
+      DIR = 'images'
+
+      # { file stem => file name } for the images already saved for a chat
+      def self.saved(chat_dir)
+        dir = File.join(chat_dir, DIR)
+        return {} unless File.directory?(dir)
+
+        Dir.children(dir).reject { |name| name.end_with?('.tmp') }.to_h { |name| [File.basename(name, '.*'), name] }
+      end
+
+      # Callable for MarkdownFormatter: relative path of a saved image, or nil
+      def self.link_resolver(chat_dir)
+        saved = saved(chat_dir)
+        lambda do |image|
+          name = saved[image.file_stem]
+          "#{DIR}/#{name}" if name
+        end
+      end
+
+      def initialize(downloader:, output: nil)
+        @downloader = downloader
+        @output = output
+      end
+
+      # Downloads images not yet on disk; returns how many were saved
+      def save(chat_dir, messages)
+        existing = self.class.saved(chat_dir)
+        pending = messages.flat_map(&:images).uniq(&:file_stem).reject { |image| existing.key?(image.file_stem) }
+        pending.sum { |image| save_image(File.join(chat_dir, DIR), image) }
+      end
+
+      private
+
+      def save_image(dir, image)
+        stem = image.file_stem
+        result = @downloader.fetch(image)
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "#{stem}.#{result.extension}")
+        File.binwrite("#{path}.tmp", result.body)
+        File.rename("#{path}.tmp", path)
+        1
+      rescue StandardError => e
+        @output&.warn("  Could not download image #{stem}: #{e.message}")
+        0
+      end
+    end
+  end
+end

data/lib/teems/services/sync_store.rb

@@ -2,12 +2,13 @@
 
 module Teems
   module Services
-    # File I/O helpers for SyncStore: atomic writes, backup, and JSON persistence
+    # File I/O helpers for SyncStore and MailSyncStore: atomic writes, backup, and JSON persistence
     module SyncFileOps
       private
 
+      # The temporary name carries the PID, so two processes never write the same one
       def atomic_write(path, content)
-        tmp_path = "#{path}.tmp"
+        tmp_path = "#{path}.tmp.#{Process.pid}"
         File.write(tmp_path, content)
         File.rename(tmp_path, path)
       end
@@ -20,7 +21,7 @@ module Teems
       end
 
       def load_json_or_default(path, default)
-        return default unless File.exist?(path)
+        return default unless File.file?(path)
 
         JSON.parse(File.read(path))
       rescue JSON::ParserError
@@ -48,13 +49,11 @@ module Teems
 
     # Chat state mutation operations for SyncStore
     module SyncStateMutation
+      # A nil display name or chat type (sync --chat) keeps the stored one
       def update_chat_state(state, chat_id, attrs:)
-        display_name, synced_at, count, chat_type =
-          attrs.values_at(:display_name, :last_synced_at, :message_count, :chat_type)
         entry = (state['chats'] ||= {})[chat_id] ||= {}
-        entry.merge!('last_synced_at' => synced_at.iso8601, 'message_count' => count,
-                     'display_name' => display_name, 'chat_type' => chat_type,
-                     'dir_name' => build_dir_name(chat_id, display_name))
+        dir_name = dir_name_for(entry, chat_id, attrs[:display_name])
+        entry.merge!(synced_fields(attrs, dir_name)).delete('resync_from')
         state
       end
 
@@ -68,6 +67,13 @@ module Teems
 
       private
 
+      def synced_fields(attrs, dir_name)
+        display_name, synced_at, count, chat_type =
+          attrs.values_at(:display_name, :last_synced_at, :message_count, :chat_type)
+        { 'last_synced_at' => synced_at.iso8601, 'message_count' => count, 'display_name' => display_name,
+          'chat_type' => chat_type, 'dir_name' => dir_name }.compact
+      end
+
       def apply_unavailable(entry)
         entry.merge!('unavailable' => true, 'unavailable_at' => Time.now.iso8601)
       end
@@ -79,9 +85,11 @@ module Teems
       def apply_display_info(entry, chat_id, display_name)
         return unless display_name
 
-        entry.merge!('display_name' => display_name,
-                     'dir_name' => build_dir_name(chat_id, display_name))
+        entry.merge!('display_name' => display_name, 'dir_name' => dir_name_for(entry, chat_id, display_name))
       end
+
+      # ensure_chat_dir owns the directory name; this only fills it in for callers that skipped it
+      def dir_name_for(entry, chat_id, display_name) = entry['dir_name'] || build_dir_name(chat_id, display_name)
     end
 
     # Chat directory resolution for SyncStore
@@ -118,40 +126,17 @@ module Teems
       end
     end
 
-    # Directory rename helpers for SyncStore
-    module SyncRenameOps
-      private
-
-      def rename_entry_dir(entry, new_dir_name, chat_type)
-        old_name = entry['dir_name']
-        old_type = entry['chat_type']
-        if old_name && (old_name != new_dir_name || old_type != chat_type)
-          move_chat_dir(chat_type_path(old_type, old_name),
-                        chat_type_path(chat_type, new_dir_name))
-        end
-        entry.merge!('dir_name' => new_dir_name, 'chat_type' => chat_type)
-      end
-
-      def move_chat_dir(old_path, new_path)
-        return if old_path == new_path || !File.directory?(old_path) || File.exist?(new_path)
-
-        FileUtils.mkdir_p(File.dirname(new_path))
-        File.rename(old_path, new_path)
-      end
-
-      def chat_type_path(type, name) = File.join(sync_dir, SyncStore::CHATS_DIR, type_dir(type), name)
-    end
-
     # Manages local sync state and file storage for the sync command.
     # Stores chat history as Markdown + JSON in XDG data directory.
     class SyncStore
       include SyncDirNaming
+      include SyncDirOwnership
+      include SyncDirPlanning
       include SyncFileOps
       include SyncStateQuery
       include SyncStateMutation
       include SyncChatDir
       include SyncChatWrite
-      include SyncRenameOps
 
       SYNC_DIR = 'sync'
       STATE_FILE = 'sync_state.json'
@@ -180,14 +165,6 @@ module Teems
         FileUtils.mkdir_p(sync_dir)
         atomic_write(File.join(sync_dir, STATE_FILE), JSON.pretty_generate(state))
       end
-
-      def ensure_dir_name(state, chat_info:)
-        chat_id, display_name, chat_type = chat_info.values_at(:chat_id, :display_name, :chat_type)
-        new_dir_name = build_dir_name(chat_id, display_name)
-        entry = (state['chats'] ||= {})[chat_id] ||= {}
-        rename_entry_dir(entry, new_dir_name, chat_type)
-        new_dir_name
-      end
     end
   end
 end

data/lib/teems/services/token_extractor.rb

@@ -298,6 +298,10 @@ module Teems
         try_headless_extract || try_safari_oauth || safari_extract
       end
 
+      # Only the headless helper: renews tokens from the cached sign-in session without
+      # opening Safari or any window, or returns nil when there is no such session
+      def extract_silently = try_headless_extract
+
       def manual_instructions = MANUAL_TOKEN_INSTRUCTIONS
 
       private

data/lib/teems/support/control_chars.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Teems
+  module Support
+    # Removes C0 and C1 control characters, other than tab and newline, from text a sender
+    # controls. Printed to a terminal they are escape sequences: ESC ]52 sets the clipboard
+    # on terminals that allow OSC 52, and others move the cursor or rewrite the screen.
+    module ControlChars
+      CONTROLS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/
+
+      module_function
+
+      def strip(text)
+        string = text.to_s
+        string.match?(CONTROLS) ? string.gsub(CONTROLS, '') : string
+      end
+    end
+  end
+end

data/lib/teems/support/mime_header.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Teems
+  module Support
+    # Header fields with parameters, e.g. `text/plain; charset="utf-8"` (RFC 2045), including
+    # RFC 2231 (filename*=utf-8''...) and RFC 2047 encoded words (=?utf-8?B?...?=)
+    module MimeHeader
+      ENCODED_WORD = /=\?([^?]+)\?([BbQq])\?([^?]*)\?=/
+      # Parameters split on ";" outside quotes
+      PARAMS = /(?:"(?:\\.|[^"\\])*"|[^;"])+/
+
+      module_function
+
+      # [lowercased value, { lowercased name => value }]
+      def field(text)
+        value, *params = text.to_s.scan(PARAMS)
+        [value.to_s.strip.downcase, params.to_h { |param| parameter(param) }]
+      end
+
+      def parameter(text)
+        name, value = text.split('=', 2)
+        value = value.to_s.strip
+        value = value[1...-1].gsub(/\\(.)/, '\1') if value.start_with?('"') && value.end_with?('"')
+        [name.strip.downcase, value]
+      end
+
+      # A parameter's text, preferring the RFC 2231 form (name*) when present
+      def decoded(params, name)
+        extended = params["#{name}*"]
+        return percent_decoded(extended) if extended
+
+        plain = params[name]
+        words_decoded(plain) if plain
+      end
+
+      def percent_decoded(text)
+        charset, _language, encoded = text.split("'", 3)
+        return text unless encoded
+
+        transcode(encoded.gsub(/%(\h\h)/) { ::Regexp.last_match(1).hex.chr }, charset)
+      end
+
+      def words_decoded(text)
+        text.gsub(ENCODED_WORD) do
+          charset, kind, encoded = ::Regexp.last_match.captures
+          bytes = kind.casecmp?('B') ? encoded.unpack1('m') : encoded.tr('_', ' ').unpack1('M')
+          transcode(bytes, charset)
+        end
+      end
+
+      # Bytes in charset as UTF-8; unknown charsets are read as UTF-8, and bad bytes become "?"
+      def transcode(bytes, charset)
+        text = bytes.dup
+        encoding = Encoding.find(charset.to_s.strip.empty? ? 'UTF-8' : charset)
+        text.force_encoding(encoding).encode('UTF-8', invalid: :replace, undef: :replace, replace: '?')
+      rescue ArgumentError
+        text.force_encoding('UTF-8').scrub('?')
+      end
+    end
+  end
+end

data/lib/teems/support/mime_part.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Teems
+  module Support
+    # One MIME entity (RFC 2045/2046): headers, a decoded body, and parts when multipart.
+    # Enough to read a decrypted S/MIME message: text and HTML bodies, attachment names,
+    # nested multiparts.
+    class MimePart
+      SIGNED_MULTIPART = 'multipart/signed'
+      PKCS7_TYPES = %w[application/pkcs7-mime application/x-pkcs7-mime].freeze
+
+      attr_reader :headers, :body
+
+      def self.parse(raw)
+        raw = raw.b
+        return new({}, raw.sub(/\A\r?\n/, '')) if raw.match?(/\A\r?\n/)
+
+        head, body = raw.split(/\r?\n\r?\n/, 2)
+        new(header_fields(head.to_s), body.to_s)
+      end
+
+      # Unfolded, names lowercased; the first of a repeated header wins
+      def self.header_fields(head)
+        head.gsub(/\r?\n[ \t]+/, ' ').split(/\r?\n/).each_with_object({}) do |line, fields|
+          name, value = line.split(':', 2)
+          fields[name.strip.downcase] ||= value.strip if value
+        end
+      end
+
+      def initialize(headers, body)
+        @headers = headers
+        @body = body
+      end
+
+      def content_type = type_field.first.then { |type| type.empty? ? 'text/plain' : type }
+      def multipart? = content_type.start_with?('multipart/')
+      def text? = %w[text/plain text/html].include?(content_type)
+
+      def parts
+        boundary = type_field.last['boundary']
+        return [] unless multipart? && boundary
+
+        sections = body.split(/(?:\A|\r?\n)--#{Regexp.escape(boundary.b)}/).drop(1)
+        sections.take_while { |section| !section.start_with?('--') }.map do |section|
+          MimePart.parse(section.sub(/\A[ \t]*\r?\n/, ''))
+        end
+      end
+
+      # The parts with no parts of their own, in order (this part when it is not multipart)
+      def leaves = multipart? ? parts.flat_map(&:leaves) : [self]
+
+      # [the content inside any signature layers, whether there were any]
+      def unsigned
+        inner = signed_content
+        inner ? [inner.unsigned.first, true] : [self, false]
+      end
+
+      # The part a signature wraps (multipart/signed keeps its first part, opaque signed
+      # PKCS #7 gives up the content inside it), or nil when this part is not signed
+      def signed_content
+        type = content_type
+        return parts.first if type == SIGNED_MULTIPART
+
+        MimePart.parse(SignedData.content(decoded)) if PKCS7_TYPES.include?(type)
+      end
+
+      # The body with its transfer encoding undone, as bytes
+      def decoded
+        case headers['content-transfer-encoding'].to_s.strip.downcase
+        when 'base64' then body.unpack1('m')
+        when 'quoted-printable' then body.gsub("\r\n", "\n").unpack1('M')
+        else body
+        end
+      end
+
+      # The decoded body as UTF-8 text, from its charset
+      def text = MimeHeader.transcode(decoded, type_field.last['charset'])
+
+      def filename
+        params = MimeHeader.field(headers['content-disposition']).last
+        MimeHeader.decoded(params, 'filename') || MimeHeader.decoded(type_field.last, 'name')
+      end
+
+      # Something a person attached, as opposed to the message body or an image shown inline
+      def attachment?
+        disposition = MimeHeader.field(headers['content-disposition']).first
+        return true if disposition == 'attachment'
+
+        disposition.empty? && !text? && !headers.key?('content-id') && !filename.to_s.empty?
+      end
+
+      private
+
+      def type_field = @type_field ||= MimeHeader.field(headers['content-type'])
+    end
+  end
+end