teems 0.3.3 → 0.8.0

data/lib/teems/services/mail_id_cache.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Remembers full Graph message IDs for the short IDs `teems mail list` and `search` print,
+    # so `teems mail read <short id>` works afterwards. Kept in the XDG cache dir.
+    class MailIdCache
+      MAX_ENTRIES = 2000
+
+      def initialize(paths: Support::XdgPaths.new)
+        @path = paths.cache_file('mail-ids.json')
+      end
+
+      def remember(messages)
+        return if messages.empty?
+
+        # Listed IDs move to the end, so the ones in use are the last evicted
+        listed = messages.to_h { |message| [message.short_id, message.id] }
+        ids = load.except(*listed.keys).merge(listed)
+        FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+        File.write(@path, JSON.generate(ids.to_a.last(MAX_ENTRIES).to_h))
+      end
+
+      # Full ID for a short ID or unique prefix of one (4+ hex digits); full IDs pass through
+      def resolve(token)
+        prefix = self.class.short_prefix(token)
+        return token.to_s.strip unless prefix
+
+        matches = ids_starting_with(prefix)
+        matches.one? ? matches.first : nil
+      end
+
+      # Lowercased short ID (or prefix) for a token that looks like one, else nil
+      def self.short_prefix(token)
+        stripped = token.to_s.strip
+        stripped.match?(/\A\h{4,16}\z/) ? stripped.downcase : nil
+      end
+
+      private
+
+      def ids_starting_with(prefix) = load.select { |short, _id| short.start_with?(prefix) }.values.uniq
+
+      def load
+        data = File.file?(@path) ? JSON.parse(File.read(@path)) : {}
+        data.is_a?(Hash) ? data : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/teems/services/mail_legacy_files.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Finds Markdown files an older outlook-cli sync wrote for the same message, so syncing
+    # into an existing ~/Mail adopts them instead of writing duplicates. outlook-cli named
+    # messages by AppleScript integer IDs, so files are matched on received time (to the
+    # second, in local time, the exact second first), subject (ignoring case and
+    # punctuation) and sender address. The sender matters for bursts such as a dozen
+    # "Automatic reply" messages arriving in the same couple of seconds.
+    class MailLegacyFiles
+      DATE_FORMATS = ['%A, %B %d, %Y at %I:%M:%S %p', '%B %d, %Y at %I:%M:%S %p', '%m/%d/%Y %I:%M:%S %p'].freeze
+      HEADER_BYTES = 4096
+      # Long recipient lists push the closing --- past HEADER_BYTES; give up beyond this
+      MAX_HEADER_BYTES = 65_536
+
+      def initialize(dir, known_files: [])
+        @dir = dir
+        @known = known_files.to_set
+        @entries = nil
+      end
+
+      # File name of an unclaimed legacy file for this message, or nil. Each file matches once.
+      def match(message)
+        received = message.received_at
+        return unless received
+
+        wanted = { subject: subject_key(message.subject), sender: message.from[:address].downcase }
+        candidates = [0, -1, 1].flat_map { |offset| entries.fetch(received.to_i + offset, []) }
+        found = candidates.find { |candidate| same_message?(candidate, wanted) }
+        found&.store(:claimed, true)
+        found&.fetch(:file)
+      end
+
+      def count = entries.sum { |_time, list| list.length }
+
+      private
+
+      # Unclaimed, same subject, and the same sender unless one side has no address
+      def same_message?(candidate, wanted)
+        return false if candidate[:claimed] || candidate[:subject] != wanted[:subject]
+
+        senders = [candidate[:sender], wanted[:sender]]
+        senders.include?('') || senders.uniq.one?
+      end
+
+      def entries
+        @entries ||= Dir.glob(File.join(@dir, '*.md')).filter_map { |path| legacy_entry(path) }
+                                                      .group_by { |entry| entry[:time] }
+      end
+
+      def legacy_entry(path)
+        file = File.basename(path)
+        return if @known.include?(file)
+
+        fields = frontmatter(path)
+        return unless fields['id'].to_s.match?(/\A\d+\z/)
+
+        time = parse_date(fields['date'].to_s)
+        time && { time: time.to_i, subject: subject_key(fields['subject'].to_s), sender: sender_key(fields['from']),
+                  file: file }
+      end
+
+      def frontmatter(path)
+        block = frontmatter_block(path, HEADER_BYTES) || frontmatter_block(path, MAX_HEADER_BYTES)
+        block.to_s.scan(/^(\w+):[ \t]*(.*)$/).to_h.transform_values { |value| unquote(value) }
+      end
+
+      def frontmatter_block(path, bytes)
+        head = File.read(path, bytes).to_s.force_encoding(Encoding::UTF_8).scrub('')
+        head[/\A---\n(.*?)\n---/m, 1]
+      end
+
+      def unquote(value) = value.strip.delete_prefix('"').delete_suffix('"').gsub('\\"', '"')
+
+      def parse_date(text)
+        text = text.tr("\u202f\u00a0", '  ').squeeze(' ').strip
+        DATE_FORMATS.each do |format|
+          return Time.strptime(text, format)
+        rescue ArgumentError
+          next
+        end
+        nil
+      end
+
+      def subject_key(subject) = subject.downcase.gsub(/[^[:alnum:]]/, '')
+
+      # Address from "Name <address>" (or a bare address), lower case; '' when there is none
+      def sender_key(from)
+        text = from.to_s
+        address = text[/<([^<>@\s]+@[^<>\s]+)>/, 1] || text[/\A[^<>@\s]+@[^<>\s]+\z/]
+        address.to_s.downcase
+      end
+    end
+  end
+end

data/lib/teems/services/mail_sync_attachments.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # A message's attachments during mail sync: lists them for its Markdown file and, with
+    # the attachments option, saves file attachments under <folder>/attachments/<short id>/.
+    # The listing is also where S/MIME encrypted mail shows itself: Exchange wraps it as TNEF,
+    # so only an empty body and an smime.p7m attachment give it away.
+    # One that fails the same way every time is skipped with a warning. Raising would fail
+    # the page before its checkpoint, so every later run would stop there too.
+    class MailSyncAttachments
+      FILE_ATTACHMENT = '#microsoft.graph.fileAttachment'
+      # 4xx errors that can succeed on a later run, unlike a missing or forbidden attachment
+      RETRYABLE_STATUSES = [401, 408, 429].freeze
+      # Local failures that can clear up (disk full, I/O), unlike a name the disk refuses
+      RETRYABLE_ERRNOS = [Errno::ENOSPC, Errno::EIO, Errno::EDQUOT].freeze
+
+      # names: attachment names for the Markdown; encrypted: an S/MIME envelope stood in for the body
+      Listing = Data.define(:names, :encrypted)
+
+      # options as for MailSyncEngine: attachments and on_warning
+      def initialize(api:, store:, options:)
+        @api = api
+        @store = store
+        @options = options
+      end
+
+      # The message's attachments other than inline images and, for a message with no body, its
+      # S/MIME envelope: ciphertext, so neither listed nor saved as a file
+      def listing(message, folder_path)
+        envelopes, files = list(message).partition { |item| message.bodyless? && Models::MailEncryption.envelope?(item) }
+        download_all(message, files, File.join(@store.folder_dir(folder_path), 'attachments')) if @options[:attachments]
+        Listing.new(names: Models::MailMessage.attachment_names(files), encrypted: envelopes.any?)
+      end
+
+      def self.permanent?(error)
+        return RETRYABLE_ERRNOS.none? { |errno| error.is_a?(errno) } unless error.is_a?(ApiError)
+
+        status = error.status_code.to_i
+        status.between?(400, 499) && !RETRYABLE_STATUSES.include?(status)
+      end
+
+      # The attachment's safe file name, or "name (2).ext" and so on when an earlier one in
+      # the message took it (compared without case, as on macOS). The first keeps the plain
+      # name, so files saved before stay where they are.
+      def self.unique_name(name, taken)
+        base = Formatters::FormatUtils.safe_filename(name.to_s)
+        ext = File.extname(base)
+        candidates = (2..).lazy.map { |number| "#{base.delete_suffix(ext)} (#{number})#{ext}" }
+        unique = [base].lazy.chain(candidates).find { |candidate| !taken.include?(candidate.downcase) }
+        taken << unique.downcase
+        unique
+      end
+
+      private
+
+      # A listing Graph refuses for good leaves the message without attachment names
+      def list(message)
+        @api.attachments(message.id).reject { |attachment| attachment['isInline'] }
+      rescue ApiError => e
+        skip(e, "attachments of message #{message.short_id}")
+        []
+      end
+
+      # Item and reference attachments (attached emails, cloud links) have no file to save
+      def download_all(message, files, attachments_dir)
+        dir = File.join(attachments_dir, message.short_id)
+        taken = Set.new
+        files.each do |attachment|
+          next unless attachment.fetch('@odata.type', FILE_ATTACHMENT) == FILE_ATTACHMENT
+
+          download_or_skip(message, attachment, File.join(dir, self.class.unique_name(attachment['name'], taken)))
+        end
+      end
+
+      def download_or_skip(message, attachment, path)
+        download(message, attachment, path)
+      rescue SystemCallError, ApiError => e
+        skip(e, "attachment #{attachment['name'].to_s.inspect} of message #{message.short_id}")
+      end
+
+      def skip(error, what)
+        raise error unless self.class.permanent?(error)
+
+        @options[:on_warning]&.call("Skipped #{what}: #{error.message}")
+      end
+
+      # Skipped when a file of the same size is already there
+      def download(message, attachment, path)
+        attachment_id, size = attachment.values_at('id', 'size')
+        return if File.size?(path) == size
+
+        bytes = @api.attachment(message.id, attachment_id)['contentBytes']
+        save(path, bytes) if bytes
+      end
+
+      def save(path, encoded)
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        File.binwrite(path, encoded.unpack1('m'))
+      end
+    end
+  end
+end

data/lib/teems/services/mail_sync_engine.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Incremental mail sync for one folder at a time using Graph delta queries. Each page is
+    # written and checkpointed before the next is fetched, so an interrupted run resumes where
+    # it stopped. Messages that leave a folder keep their file; the index records removed_at.
+    class MailSyncEngine
+      # Graph's answers to a delta link it can no longer use: 410 Gone, or 400 with one of
+      # these codes (compared without case; the last is Exchange's, for an old or malformed
+      # delta token)
+      RESYNC_CODES = %w[syncstatenotfound syncstateinvalid resyncrequired errorinvalidsyncstatedata].freeze
+
+      # Raised by fetch_page when Graph rejects the delta link itself (cause: the ApiError).
+      # A 400 anywhere else, such as one message's attachments, must not restart the folder.
+      class ResyncNeeded < StandardError; end
+
+      # options: since (Time limiting the first sync of a folder; nil syncs everything),
+      # attachments (also download file attachments) and on_warning (called with problems
+      # that are skipped rather than raised)
+      def initialize(api:, store:, options: {})
+        @api = api
+        @store = store
+        @options = options
+        @folder = nil
+      end
+
+      # Syncs one Models::MailFolder; returns counts keyed by MailSyncFolder::STAT_KEYS.
+      # A delta link Graph rejects starts the folder over once; a second rejection raises
+      # Graph's error.
+      def sync(folder)
+        attempts = 0
+        begin
+          @folder = MailSyncFolder.new(folder, @store)
+          run_delta
+        rescue ResyncNeeded => e
+          raise e.cause unless (attempts += 1) == 1
+
+          @folder.reset_state
+          retry
+        end
+        @folder.stats
+      end
+
+      def self.resync?(error)
+        case error.status_code
+        when 410 then true
+        when 400 then RESYNC_CODES.include?(error.error_code.to_s.downcase)
+        else false
+        end
+      end
+
+      private
+
+      # Each page is checkpointed, so an interrupted run resumes from its last page
+      def run_delta
+        link = @folder.resume_link
+        loop do
+          page = fetch_page(link)
+          page['value'].to_a.each { |item| process(item) }
+          @folder.checkpoint(page)
+          link = page['@odata.nextLink']
+          break unless link
+        end
+      end
+
+      def fetch_page(link)
+        link ? @api.delta_page(link) : @api.delta(folder: @folder.id, since: @options[:since])
+      rescue ApiError => e
+        raise ResyncNeeded if self.class.resync?(e)
+
+        raise
+      end
+
+      def process(item)
+        return @folder.mark_removed(item['id']) if item.key?('@removed')
+
+        message = Models::MailMessage.from_api(item)
+        legacy_file = @folder.legacy_file(message)
+        return @folder.adopt(message, legacy_file) if legacy_file
+
+        write(message)
+      end
+
+      def attachments = MailSyncAttachments.new(api: @api, store: @store, options: @options)
+
+      def write(message)
+        path = @folder.path
+        file = @folder.file_for(message)
+        listing = attachments.listing(message, path) if message.attachments_to_list?
+        message = message.with(protection: 'smime') if listing&.encrypted
+        content = Formatters::MailMarkdown.render(message, folder: path, attachments: listing ? listing.names : [])
+        @folder.count(@store.write_message(path, file, content))
+        @folder.record(message, file)
+      end
+    end
+  end
+end

data/lib/teems/services/mail_sync_folder.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # The index of one synced mail folder: Graph message ID -> file name and summary, plus
+    # the matcher for files an older outlook-cli sync left in the same directory
+    class MailSyncIndex
+      def initialize(messages, legacy:)
+        @messages = messages
+        @snapshot = JSON.generate(messages)
+        @legacy = legacy
+      end
+
+      def to_h = @messages
+
+      def entry(message_id) = @messages[message_id]
+
+      def include?(message_id) = @messages.key?(message_id)
+
+      # Legacy file already recorded for this message, or an unclaimed one that matches it
+      def legacy_file(message)
+        entry = @messages[message.id]
+        return entry['legacy'] ? entry['file'] : nil if entry
+
+        @legacy.match(message)
+      end
+
+      def self.entry_for(message, file)
+        { 'file' => file, 'short_id' => message.short_id, 'subject' => message.subject,
+          'from' => message.from[:address], 'received' => message.received_at&.utc&.iso8601,
+          'read' => message.read? }
+      end
+
+      def record(message, file)
+        @messages[message.id] = MailSyncIndex.entry_for(message, file)
+      end
+
+      # Records a legacy file (left as it is) as this message's file
+      def adopt(message, file)
+        record(message, file)['legacy'] = true
+      end
+
+      # Marks a known message removed; true unless it was unknown or already marked
+      def mark_removed?(message_id)
+        return false unless removable?(message_id)
+
+        @messages[message_id]['removed_at'] = Time.now.utc.iso8601
+        true
+      end
+
+      def changed? = JSON.generate(@messages) != @snapshot
+
+      def mark_saved
+        @snapshot = JSON.generate(@messages)
+      end
+
+      private
+
+      # Unknown IDs fall back to an entry that already counts as removed
+      def removable?(message_id) = !@messages.fetch(message_id, { 'removed_at' => nil }).key?('removed_at')
+    end
+
+    # Index, delta state, and counts for the folder a MailSyncEngine is syncing
+    class MailSyncFolder
+      STAT_KEYS = %i[created updated unchanged adopted removed].freeze
+
+      attr_reader :stats
+
+      def initialize(folder, store)
+        @folder = folder
+        @store = store
+        @index = load_index
+        @stats = STAT_KEYS.to_h { |key| [key, 0] }
+        # Without an index the files the delta link already covered are gone: start over
+        reset_state unless store.index_exists?(path)
+      end
+
+      def id = @folder.id
+      def path = @folder.path
+
+      def resume_link
+        state = @store.load_state[id] || {}
+        state['next_link'] || state['delta_link']
+      end
+
+      def reset_state
+        states = @store.load_state
+        states.delete(id) && @store.save_state(states)
+      end
+
+      def legacy_file(message) = @index.legacy_file(message)
+
+      def file_for(message) = @index.entry(message.id)&.fetch('file') || Formatters::MailMarkdown.filename(message)
+
+      def count(result) = @stats[result] += 1
+
+      def record(message, file) = @index.record(message, file)
+
+      # Legacy files are never rewritten, so seeing one again leaves it unchanged
+      def adopt(message, file)
+        count(@index.include?(message.id) ? :unchanged : :adopted)
+        @index.adopt(message, file)
+      end
+
+      def mark_removed(message_id)
+        count(:removed) if @index.mark_removed?(message_id)
+      end
+
+      # Saves the index (when anything changed) and the link to continue from
+      def checkpoint(page)
+        save_index if @index.changed? || !@store.index_exists?(path)
+        states = @store.load_state
+        states[id] = next_state(states[id] || {}, page)
+        @store.save_state(states)
+      end
+
+      private
+
+      def load_index
+        messages = @store.load_index(path)
+        known = messages.values.map { |entry| entry['file'] }
+        legacy = MailLegacyFiles.new(@store.folder_dir(path), known_files: known)
+        MailSyncIndex.new(messages, legacy: legacy)
+      end
+
+      def save_index
+        @store.save_index(path, @index.to_h)
+        @index.mark_saved
+      end
+
+      def next_state(state, page)
+        next_link = page['@odata.nextLink']
+        update = next_link ? { 'next_link' => next_link } : finished_state(page)
+        state.merge('name' => path, **update)
+      end
+
+      def finished_state(page)
+        { 'next_link' => nil, 'delta_link' => page['@odata.deltaLink'], 'last_synced_at' => Time.now.utc.iso8601 }
+      end
+    end
+  end
+end

data/lib/teems/services/mail_sync_store.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # On-disk layout for `teems mail sync`:
+    #
+    #   <root>/<Folder>/<YYYY-MM-DD>-<subject>-<short id>.md   one file per message
+    #   <root>/<Folder>/index.json                             message ID -> file and summary
+    #   <root>/<Folder>/attachments/<short id>/                with --attachments
+    #
+    # <Folder> is the folder path with "/" as "-", as outlook-cli named them, so its files
+    # are adopted. A folder whose name another folder's index already claims (Projects/Reports
+    # and a top-level Projects-Reports), or that is no usable directory name ("." or ".."),
+    # gets "<Folder> (<8 hex digits>)" instead.
+    #
+    # Delta links and the run lock live in the XDG state dir, outside the root, so a run that
+    # changes no mail changes nothing under the root (watchers keyed on mtimes stay quiet).
+    class MailSyncStore
+      include SyncFileOps
+
+      INDEX_FILE = 'index.json'
+      STATE_FILE = 'mail-sync.json'
+      UNUSABLE_NAMES = ['', '.', '..'].freeze
+
+      attr_reader :root
+
+      def self.default_root = File.join(Support::XdgPaths.new.data_dir, SyncStore::SYNC_DIR, 'mail')
+
+      def self.default_state_dir
+        File.join(ENV.fetch('XDG_STATE_HOME') { File.join(Dir.home, '.local', 'state') }, 'teems')
+      end
+
+      def initialize(root: MailSyncStore.default_root, state_dir: MailSyncStore.default_state_dir)
+        @root = File.expand_path(root)
+        @state_dir = state_dir
+        @folder_dirs = {}
+      end
+
+      def folder_dir(folder_path) = @folder_dirs[folder_path] ||= File.join(root, dir_name(folder_path))
+
+      def index_exists?(folder_path) = File.file?(index_path(folder_path))
+
+      def load_index(folder_path)
+        read_json(index_path(folder_path)).fetch('messages', {})
+      end
+
+      def save_index(folder_path, messages)
+        dir = ensure_dir(folder_dir(folder_path))
+        atomic_write(File.join(dir, INDEX_FILE),
+                     JSON.pretty_generate('version' => 1, 'folder' => folder_path, 'messages' => messages))
+      end
+
+      # :created, :updated, or :unchanged (identical content is never rewritten)
+      def write_message(folder_path, filename, content)
+        path = File.join(ensure_dir(folder_dir(folder_path)), filename)
+        existed = File.exist?(path)
+        return :unchanged if existed && File.read(path) == content
+
+        atomic_write(path, content)
+        existed ? :updated : :created
+      end
+
+      # Delta state for this root, keyed by Graph folder ID
+      def load_state
+        folders = read_json(state_path).dig('roots', root, 'folders')
+        folders.is_a?(Hash) ? folders : {}
+      end
+
+      def save_state(folders)
+        data = read_json(state_path)
+        (data['roots'] ||= {})[root] = { 'folders' => folders }
+        ensure_dir(@state_dir)
+        atomic_write(state_path, JSON.pretty_generate(data))
+      end
+
+      # Yields while holding the mail sync lock; returns :locked without yielding if another run holds it
+      def with_lock
+        ensure_dir(@state_dir)
+        File.open(File.join(@state_dir, 'mail-sync.lock'), File::RDWR | File::CREAT, 0o600) do |lock|
+          return :locked unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+          yield
+        end
+      end
+
+      private
+
+      def index_path(folder_path) = File.join(folder_dir(folder_path), INDEX_FILE)
+
+      def dir_name(folder_path)
+        name = folder_path.tr('/', '-')
+        return name unless UNUSABLE_NAMES.include?(name) || claimed_by_another?(name, folder_path)
+
+        "#{name} (#{Digest::SHA256.hexdigest(folder_path)[0, 8]})"
+      end
+
+      # An index records the folder path it was saved for
+      def claimed_by_another?(name, folder_path)
+        read_json(File.join(root, name, INDEX_FILE)).fetch('folder', folder_path) != folder_path
+      end
+
+      def state_path = File.join(@state_dir, STATE_FILE)
+
+      def ensure_dir(dir)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+        dir
+      end
+
+      # A JSON object from the file, or {} for anything else
+      def read_json(path)
+        data = load_json_or_default(path, {})
+        data.is_a?(Hash) ? data : {}
+      end
+    end
+  end
+end

data/lib/teems/services/smime_content.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # What a decrypted S/MIME message says: its body (HTML when there is one, as Outlook
+    # shows it), the names of its attachments, and whether it was also signed. A signature
+    # is unwrapped to reach the content but not checked.
+    class SmimeContent
+      # body: text in body_type ('html' or 'text'); attachments: file names; signed: true/false
+      Result = Data.define(:body, :body_type, :attachments, :signed) do
+        # The bodyless message Graph returned, with the decrypted body in its place
+        def apply_to(message) = message.with(body: Models::MailMessage.clean(body), body_type: body_type)
+
+        def attachment_names = attachments.map { |name| Models::MailMessage.clean(name) }
+      end
+      BODY_TYPES = %w[text/html text/plain].freeze
+
+      def self.parse(mime) = new.parse(Support::MimePart.parse(mime))
+
+      def parse(entity)
+        content, signed = entity.unsigned
+        leaves = content.leaves
+        body = body_part(leaves)
+        Result.new(body: body ? body.text : '', body_type: body&.content_type == 'text/html' ? 'html' : 'text',
+                   attachments: leaves.select(&:attachment?).map { |part| part.filename.to_s }, signed: signed)
+      end
+
+      private
+
+      def body_part(leaves)
+        leaves.select { |part| part.text? && !part.attachment? }
+              .min_by { |part| BODY_TYPES.index(part.content_type) }
+      end
+    end
+  end
+end

data/lib/teems/services/smime_decryptor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Teems
+  module Services
+    # Decrypts an S/MIME envelope with macOS's `security cms -D`, which finds the matching
+    # private key among keychain identities, PIV card keys (current and retired key management
+    # keys) included, and shows the system PIN dialog when the card needs it. The ciphertext
+    # goes in on stdin and the plaintext comes back on stdout, so neither touches the disk.
+    class SmimeDecryptor
+      # SEC_ERROR_NOT_A_RECIPIENT: no key here matches any recipient of the message
+      NOT_A_RECIPIENT = '-8147'
+      COMMAND = %w[security cms -D].freeze
+
+      def decrypt(envelope)
+        plain, errors, status = Support::Subprocess.capture3(*COMMAND, stdin_data: envelope, binmode: true)
+        return plain if status.success?
+
+        raise Error, failure(errors)
+      rescue Errno::ENOENT
+        raise Error, 'Decrypting needs the macOS security command'
+      end
+
+      private
+
+      def failure(errors)
+        if errors.include?(NOT_A_RECIPIENT)
+          return 'None of your keys can open this message: it was encrypted for other certificates. ' \
+                 'Is your PIV card inserted?'
+        end
+
+        detail = errors.lines.map(&:strip).reject(&:empty?).first
+        "Could not decrypt the message#{": #{detail.delete_prefix('security: ')}" if detail}"
+      end
+    end
+  end
+end