teems 0.3.2 → 0.8.0

data/lib/teems/formatters/mail_rule_text.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Teems
+  module Formatters
+    # One line saying what an Inbox rule does, e.g.
+    #   from jira@example.com, except subject has "urgent" -> move to Inbox/Jira, stop
+    # Keys this does not know are spelled out from their Graph names, so nothing is hidden.
+    class MailRuleText
+      LABELS = {
+        'fromAddresses' => 'from', 'sentToAddresses' => 'to', 'subjectContains' => 'subject has',
+        'bodyContains' => 'body has', 'bodyOrSubjectContains' => 'subject or body has',
+        'senderContains' => 'sender has', 'recipientContains' => 'recipient has',
+        'headerContains' => 'header has', 'moveToFolder' => 'move to', 'copyToFolder' => 'copy to',
+        'assignCategories' => 'categories', 'markImportance' => 'importance',
+        'forwardTo' => 'FORWARD to', 'forwardAsAttachmentTo' => 'FORWARD as attachment to',
+        'redirectTo' => 'REDIRECT to'
+      }.freeze
+      # Conditions and actions that are simply on
+      SWITCHES = { 'markAsRead' => 'mark read', 'stopProcessingRules' => 'stop',
+                   'delete' => 'delete', 'permanentDelete' => 'PERMANENTLY delete',
+                   'isMeetingRequest' => 'meeting requests', 'hasAttachments' => 'with attachments' }.freeze
+      FOLDER_ACTIONS = %w[moveToFolder copyToFolder].freeze
+
+      # folder_names: Graph folder ID => path, to name a rule's destination
+      def initialize(folder_names = {})
+        @folder_names = folder_names
+      end
+
+      def describe(rule)
+        exceptions = phrases(rule.exceptions)
+        tests = phrases(rule.conditions).join(', ')
+        tests = 'all mail' if tests.empty?
+        tests += ", except #{exceptions.join(', ')}" if exceptions.any?
+        "#{tests} -> #{phrases(rule.actions).join(', ')}"
+      end
+
+      private
+
+      def phrases(settings) = settings.filter_map { |key, value| phrase(key, value) }
+
+      def phrase(key, value)
+        return if [false, nil, []].include?(value)
+
+        switch = value == true
+        label = (switch ? SWITCHES : LABELS).fetch(key) { spelled(key) }
+        switch ? label : "#{label} #{values_text(key, value)}"
+      end
+
+      def values_text(key, value) = Array(value).map { |item| item_text(key, item) }.join(', ')
+
+      def item_text(key, item)
+        return @folder_names.fetch(item, 'another folder') if FOLDER_ACTIONS.include?(key)
+        return recipient_text(item) if item.is_a?(Hash)
+
+        key.end_with?('Contains') ? %("#{item}") : item.to_s
+      end
+
+      def recipient_text(item)
+        address = item['emailAddress'] || item
+        address.values_at('address', 'name').compact.first.to_s
+      end
+
+      # isAutomaticReply -> is automatic reply
+      def spelled(key) = key.gsub(/[A-Z]/) { |letter| " #{letter.downcase}" }
+    end
+  end
+end

data/lib/teems/formatters/markdown_formatter.rb

@@ -15,10 +15,12 @@ module Teems
         '1f440_eyes' => "\u{1F440}", 'thumbsdown' => "\u{1F44E}"
       }.freeze
 
-      def initialize(chat_name:, chat_type: nil, synced_at: nil)
+      # image_link: optional callable returning a relative path for a locally saved InlineImage
+      def initialize(chat_name:, chat_type: nil, synced_at: nil, image_link: nil)
         @chat_name = chat_name
         @chat_type = chat_type
         @synced_at = synced_at
+        @image_link = image_link
       end
 
       # Format an array of Message objects into a Markdown string.
@@ -68,6 +70,7 @@ module Teems
         content = msg.content
         result = content.to_s.empty? ? [] : [content]
         result.concat(format_message_attachments(msg))
+        result.concat(msg.images.map { |image| format_image(image) })
         result.concat(format_message_reactions(msg))
       end
 
@@ -93,6 +96,12 @@ module Teems
         url&.start_with?('https://') ? "\u{1F4CE} [#{name}](#{url})" : "\u{1F4CE} #{name}"
       end
 
+      def format_image(image)
+        label = "image: #{image.label}"
+        path = @image_link&.call(image)
+        path ? "![#{label}](#{path})" : "[#{label}]"
+      end
+
       def format_message_reactions(msg)
         reactions = msg.reactions
         return [] unless displayable_reactions?(reactions)

data/lib/teems/formatters/message_formatter.rb

@@ -21,8 +21,8 @@ module Teems
 
       def format(message)
         content = highlight_mentions(message.content, message.mentions)
-        [format_header(message), "  #{content}", format_attachments(message), format_reactions(message)]
-          .compact.join("\n")
+        [format_header(message), "  #{content}", format_attachments(message), format_images(message),
+         format_reactions(message)].compact.join("\n")
       end
 
       private
@@ -44,6 +44,11 @@ module Teems
         "  #{@output.gray("\u{1F4CE} #{attachment_names(attachments)}")}"
       end
 
+      def format_images(message)
+        summary = FormatUtils.image_summary(message.images)
+        "  #{@output.gray("\u{1F5BC}\u{FE0F} #{summary}")}" unless summary.empty?
+      end
+
       def format_reactions(message)
         reactions = message.reactions
         return unless reactions.any?

data/lib/teems/formatters/output.rb

@@ -22,6 +22,14 @@ module Teems
       end
     end
 
+    # Stands in for stdout or stderr once its reader has gone away (see Output#to_stdout)
+    module NullIO
+      def self.puts(*) = nil
+      def self.print(*) = nil
+      def self.flush = self
+      def self.tty? = false
+    end
+
     # Terminal output with ANSI color support
     class Output
       include OutputColors
@@ -52,23 +60,34 @@ module Teems
       def tty? = @io.tty?
 
       def puts(message = '')
-        write_unless_quiet { @io.puts(message) }
+        write_unless_quiet { |io| io.puts(message) }
       end
 
       def print(message)
-        write_unless_quiet { @io.print(message) }
+        write_unless_quiet { |io| io.print(message) }
       end
 
       def flush
-        @io.flush
+        to_stdout(&:flush)
       end
 
       def error(message)
-        @err.puts(colorize("#{red('Error:')} #{message}"))
+        to_stderr { |err| err.puts(colorize("#{red('Error:')} #{message}")) }
       end
 
       def warn(message)
-        write_unless_quiet { @err.puts(colorize("#{yellow('Warning:')} #{message}")) }
+        note("#{yellow('Warning:')} #{message}")
+      end
+
+      # A question for the person at the terminal: on stderr, so piped stdout stays data, and
+      # shown under --quiet too, since an unseen question would just hang (stderr is unbuffered)
+      def prompt(message)
+        to_stderr { |err| err.print(message) }
+      end
+
+      # Commentary that should not mix with data on stdout (shown unless --quiet)
+      def note(message)
+        to_stderr { |err| err.puts(colorize(message)) } unless quiet?
       end
 
       def success(message)
@@ -82,13 +101,31 @@ module Teems
       def debug(message)
         return unless verbose?
 
-        @err.puts(colorize("#{gray('[debug]')} #{message}"))
+        to_stderr { |err| err.puts(colorize("#{gray('[debug]')} #{message}")) }
       end
 
       private
 
-      def write_unless_quiet
-        yield unless quiet?
+      def write_unless_quiet(&)
+        to_stdout(&) unless quiet?
+      end
+
+      # A reader that stops early (`teems ... | head`) is not an error: drop the
+      # rest of stdout and let the command finish quietly. Raising instead would
+      # surface as "Unexpected error: Broken pipe", or be caught by a per-item
+      # rescue and reported as a failed chat or download.
+      def to_stdout
+        yield @io
+      rescue Errno::EPIPE
+        @io = NullIO
+      end
+
+      # The same for stderr, which `teems ... 2>&1 | head` closes along with stdout. A
+      # warning that raised here would also escape the per-item rescues that report it.
+      def to_stderr
+        yield @err
+      rescue Errno::EPIPE
+        @err = NullIO
       end
 
       def wrap(color, text)

data/lib/teems/formatters/transcript_markdown.rb

@@ -7,8 +7,18 @@ module Teems
     # Converts Teams WebVTT transcripts into speaker-turn Markdown for local search indexes.
     # Consecutive cues from the same speaker are merged so each paragraph carries context.
     class TranscriptMarkdown
+      # One timed WebVTT cue: its start timestamp, speaker (nil when unattributed), and plain text
       Cue = Data.define(:start, :speaker, :text)
 
+      # Consecutive cues from one speaker, merged into a paragraph until it is too long to index well
+      Turn = Struct.new(:start, :speaker, :text) do
+        def self.from(cue) = new(cue.start, cue.speaker, +cue.text)
+
+        def accepts?(cue) = cue.speaker == speaker && text.length < MAX_TURN_CHARS
+
+        def add(cue) = text << ' ' << cue.text
+      end
+
       TIMING = /\A(?<start>(?:\d+:)?\d{2}:\d{2}\.\d{3})\s+-->/
       VOICE = /<v(?:\.[^\s>]+)?\s+([^>]+)>/
       ENTITIES = {
@@ -39,11 +49,7 @@ module Teems
 
       def append_cue(turns, cue)
         last = turns.last
-        if last && last[:speaker] == cue.speaker && last[:text].length < MAX_TURN_CHARS
-          last[:text] << ' ' << cue.text
-        else
-          turns << { start: cue.start, speaker: cue.speaker, text: +cue.text }
-        end
+        last&.accepts?(cue) ? last.add(cue) : turns << Turn.from(cue)
       end
 
       def cues
@@ -51,12 +57,10 @@ module Teems
         normalized.split(/\n{2,}/).filter_map { |block| parse_cue(block) }
       end
 
+      # Cue text is every line after the timing line; identifier lines before it are skipped
       def parse_cue(block)
-        lines = block.lines.map(&:chomp)
-        timing_index = lines.index { |line| TIMING.match?(line) }
-        return unless timing_index
-
-        build_cue(lines[timing_index][TIMING, :start], lines[(timing_index + 1)..].join(' '))
+        timing, *text = block.lines(chomp: true).drop_while { |line| !TIMING.match?(line) }
+        build_cue(timing[TIMING, :start], text.join(' ')) if timing
       end
 
       def build_cue(start, raw)
@@ -85,8 +89,8 @@ module Teems
       end
 
       def format_turn(turn)
-        speaker = turn[:speaker] || 'Unknown speaker'
-        "**#{speaker}** (#{turn[:start].sub(/\.\d+\z/, '')}): #{turn[:text]}"
+        speaker = turn.speaker || 'Unknown speaker'
+        "**#{speaker}** (#{turn.start.sub(/\.\d+\z/, '')}): #{turn.text}"
       end
     end
   end

data/lib/teems/models/chat.rb

@@ -30,18 +30,22 @@ module Teems
       end
 
       def self.from_ngmsg(data)
-        thread_props = data['threadProperties'] || {}
+        id = data['id']
         props = data['properties'] || {}
         new(
-          id: data['id'],
-          topic: thread_props['topic'] || thread_props['spaceThreadTopic'],
-          chat_type: normalize_chat_type(thread_props['threadType']),
-          created_at: parse_time(thread_props['createdat']),
+          id: id,
           last_updated: parse_time(props['lastimreceivedtime']),
+          **ngmsg_thread(id, data['threadProperties'] || {}),
           **ngmsg_status(props, data['lastMessage'])
         )
       end
 
+      def self.ngmsg_thread(id, thread_props)
+        { topic: thread_props['topic'] || thread_props['spaceThreadTopic'],
+          chat_type: ngmsg_chat_type(id, thread_props),
+          created_at: parse_time(thread_props['createdat']) }
+      end
+
       def self.ngmsg_status(props, last_message)
         horizon = props['consumptionhorizon']
         last_msg_id = last_message&.dig('id')
@@ -52,6 +56,13 @@ module Teems
         }
       end
 
+      # ng.msg reports 1:1 chats with threadType 'chat', like group chats. They are marked by
+      # productThreadType 'OneToOneChat' and a "19:<user>_<user>@unq.gbl.spaces" ID.
+      def self.ngmsg_chat_type(id, thread_props)
+        one_on_one = thread_props['productThreadType'] == 'OneToOneChat' || id.to_s.end_with?('@unq.gbl.spaces')
+        one_on_one ? 'oneOnOne' : normalize_chat_type(thread_props['threadType'])
+      end
+
       # Normalize ng.msg threadType to a consistent chat type.
       # ng.msg uses: 'chat' (group), 'meeting', 'topic' (channel), 'space'
       # Normalized to: 'group', 'meeting', 'channel', 'space'
@@ -79,6 +90,9 @@ module Teems
 
       def chat_type_label = CHAT_TYPE_LABELS.fetch(chat_type, chat_type)
 
+      # What sync uses to name and place the chat's directory
+      def sync_identity = { chat_id: id, display_name: display_name, chat_type: chat_type }
+
       def unread? = unread
       def favorite? = favorite
       def pinned? = pinned

data/lib/teems/models/event.rb

@@ -24,6 +24,7 @@ module Teems
       :event_type
     ) do
       extend Parsing
+      include EventDisplay
 
       def self.from_api(data)
         new(**event_attrs(data))
@@ -90,29 +91,6 @@ module Teems
       def cancelled? = is_cancelled
       def recurring? = %w[occurrence exception].include?(event_type)
 
-      def time_range_display
-        return 'ALL DAY' if all_day?
-        return '' unless start_time && end_time
-
-        "#{start_time.strftime('%H:%M')}-#{end_time.strftime('%H:%M')}"
-      end
-
-      def date_display
-        if all_day?
-          "#{start_time&.strftime('%Y-%m-%d')} (all day)"
-        elsif start_time && end_time
-          "#{start_time.strftime('%Y-%m-%d %H:%M')}-#{end_time.strftime('%H:%M')}"
-        end
-      end
-
-      def create_summary_lines
-        lines = []
-        lines << date_display if date_display
-        lines << "Location: #{location}" if location && !location.empty?
-        lines << "Teams link: #{online_meeting_url}" if online_meeting_url
-        lines
-      end
-
       def required_attendees = attendees.select { |att| att[:type] == 'required' }
       def optional_attendees = attendees.select { |att| att[:type] == 'optional' }
       def accepted_attendees = attendees.select { |att| att[:response] == 'accepted' }

data/lib/teems/models/event_display.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # Date and time labels for an Event (expects start_time, end_time, all_day?, location, online_meeting_url)
+    module EventDisplay
+      def time_range_display
+        return 'ALL DAY' if all_day?
+        return '' unless start_time && end_time
+
+        "#{start_time.strftime('%H:%M')}-#{end_time.strftime('%H:%M')}"
+      end
+
+      def date_display
+        if all_day?
+          "#{all_day_span} (all day)"
+        elsif start_time && end_time
+          "#{start_time.strftime('%Y-%m-%d %H:%M')}-#{end_time.strftime('%H:%M')}"
+        end
+      end
+
+      # Graph ends all-day events at midnight after the last day, so a span is "first to last"
+      def all_day_span
+        first_day = start_time&.to_date
+        last_day = end_time&.to_date&.prev_day
+        return first_day.to_s unless first_day && last_day && last_day > first_day
+
+        "#{first_day} to #{last_day}"
+      end
+
+      def create_summary_lines
+        lines = []
+        lines << date_display if date_display
+        lines << "Location: #{location}" if location && !location.empty?
+        lines << "Teams link: #{online_meeting_url}" if online_meeting_url
+        lines
+      end
+    end
+  end
+end

data/lib/teems/models/ics_event.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # A calendarView event as `teems cal ics` exports it. Built from Graph data requested
+    # with Prefer: outlook.timezone="UTC", so timed events carry UTC times and all-day
+    # events carry their (floating) dates.
+    IcsEvent = Data.define(:uid, :subject, :starts, :ends, :all_day, :location, :organizer, :attendees,
+                           :body, :join_url, :status) do
+      def self.from_api(data)
+        new(uid: data['iCalUId'] || data['id'], subject: data['subject'].to_s, **time_attrs(data),
+            location: data.dig('location', 'displayName').to_s, organizer: Event.parse_organizer(data['organizer']),
+            attendees: Event.parse_attendees(data['attendees']), body: data['body'] || {},
+            join_url: data.dig('onlineMeeting', 'joinUrl').to_s, status: status_attrs(data))
+      end
+
+      # Dates for all-day events (Graph sends their midnights without a zone), UTC Times otherwise
+      def self.time_attrs(data)
+        all_day = data['isAllDay'] || false
+        parser = all_day ? :graph_date : :graph_utc
+        { starts: send(parser, data['start']), ends: send(parser, data['end']), all_day: all_day }
+      end
+
+      def self.graph_date(value) = graph_stamp(value) { |stamp| Date.parse(stamp) }
+
+      def self.graph_utc(value) = graph_stamp(value) { |stamp| Time.parse("#{stamp.delete_suffix('Z')}Z").utc }
+
+      def self.graph_stamp(value)
+        stamp = Hash(value)['dateTime']
+        stamp && yield(stamp)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.status_attrs(data) = { cancelled: data['isCancelled'] || false, show_as: data['showAs'].to_s }
+
+      def dated? = [starts, ends].all?
+
+      def cancelled? = status[:cancelled]
+
+      def free? = status[:show_as] == 'free'
+
+      # Plain-text body, links listed at the end
+      def description
+        content = body['content'].to_s
+        body['contentType'] == 'html' ? Formatters::HtmlText.convert(content).to_s : content.strip
+      end
+
+      # True when one of addresses organizes the event or has accepted it, so it is already
+      # on that address's own calendar. An invitation alone does not count.
+      def involves?(addresses)
+        return false if addresses.empty?
+
+        accepted = attendees.select { |attendee| attendee[:response] == 'accepted' }
+        [Hash(organizer)[:email], *accepted.map { |attendee| attendee[:email] }]
+          .any? { |email| addresses.include?(email.to_s.downcase) }
+      end
+    end
+  end
+end

data/lib/teems/models/inline_image.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Teems
+  module Models
+    # Extracts inline images (screenshots pasted into a message) from Teams message HTML.
+    # Teams stores them in its AMS object store and references them with
+    # <img itemtype="http://schema.skype.com/AMSImage" src="https://<ams-host>/v1/objects/<id>/views/imgo">.
+    module InlineImageParsing
+      IMG_TAG = /<img\b[^>]*>/i
+      ATTRIBUTE = /([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/
+      AMS_ITEMTYPE = 'schema.skype.com/AMSImage'
+      AMS_PATH = %r{\Ahttps://[^/\s]+/v1/objects/([^/?#\s]+)/views/}
+
+      module_function
+
+      def parse(html)
+        return [] unless html.is_a?(String) && html.match?(/<img/i)
+
+        html.scan(IMG_TAG).filter_map { |tag| image_from(tag_attributes(tag)) }.uniq(&:url)
+      end
+
+      def tag_attributes(tag)
+        tag.scan(ATTRIBUTE).to_h { |name, double, single| [name.downcase, CGI.unescapeHTML(double || single)] }
+      end
+
+      def image_from(attrs)
+        url = attrs['src'].to_s
+        return unless ams_image?(attrs, url)
+
+        InlineImage.new(id: attrs['itemid'] || url[AMS_PATH, 1], url: url, alt: attrs['alt'],
+                        width: dimension(attrs['width']), height: dimension(attrs['height']),
+                        format: attrs['itemscope'])
+      end
+
+      def ams_image?(attrs, url)
+        url.start_with?('https://') && (attrs['itemtype'].to_s.include?(AMS_ITEMTYPE) || url.match?(AMS_PATH))
+      end
+
+      def dimension(value) = Integer(value.to_s, exception: false)&.then { |num| num.positive? ? num : nil }
+    end
+
+    # An image pasted inline into a Teams message body
+    InlineImage = Data.define(:id, :url, :alt, :width, :height, :format) do
+      def self.parse_html(html) = InlineImageParsing.parse(html)
+
+      # Rebuilds an image from its stored (JSON) hash form
+      def self.from_h(hash)
+        return unless hash.is_a?(Hash)
+
+        attrs = hash.transform_keys(&:to_sym).slice(*members)
+        attrs[:url] ? new(**attrs) : nil
+      end
+
+      # Only the URL is required; the other attributes default to nil
+      def initialize(url:, **optional)
+        super(url: url, id: nil, alt: nil, width: nil, height: nil, format: nil, **optional)
+      end
+
+      # The original upload: `src` usually points at a recompressed JPEG preview,
+      # while this view is what Teams opens for "view full image".
+      def full_size_url
+        url.sub(%r{(/v1/objects/[^/]+/views/)[^/?#]+}, '\1imgpsh_fullsize_anim')
+      end
+
+      # JSON form: the stored attributes plus the original-resolution URL
+      def as_json = to_h.merge(full_size_url: full_size_url)
+
+      def dimensions = width && height ? "#{width}x#{height}" : nil
+
+      def label
+        name = alt.to_s.strip
+        name = 'image' if name.empty?
+        size = dimensions
+        size ? "#{name} (#{size})" : name
+      end
+
+      # Filesystem-safe name derived from the AMS object id
+      def file_stem = (id || url[%r{/v1/objects/([^/]+)/}, 1] || 'image').to_s.gsub(/[^\w.-]/, '_')
+    end
+  end
+end

data/lib/teems/models/mail_conversation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # A conversation's messages (oldest first), Graph folder ID => path for naming the folder
+    # each one sits in (a thread spans the Inbox, Sent Items, Archive and so on), message ID =>
+    # attachment names once with_attachment_names has fetched them, and message ID => how a
+    # decrypted message was opened (see MailEncryption)
+    MailConversation = Data.define(:messages, :folders, :attachments, :encryptions) do
+      def initialize(messages:, folders:, attachments: {}, encryptions: {}) = super
+
+      def folder(message) = folders[message.folder_id]
+
+      def with_attachment_names(api)
+        with(attachments: messages.to_h { |message| [message.id, message.attachment_names_from(api)] })
+      end
+
+      # Marks these messages S/MIME encrypted and not opened; the envelope is not listed as a file
+      def with_locked(message_ids)
+        no_files = message_ids.to_h { |id| [id, []] }
+        locked = no_files.transform_values { { type: 'smime', decrypted: false } }
+        with(encryptions: encryptions.merge(locked), attachments: attachments.merge(no_files))
+      end
+
+      # opened: message ID => Services::SmimeContent::Result for each message decrypted
+      def with_decrypted(opened)
+        with(messages: messages.map { |message| opened[message.id]&.apply_to(message) || message },
+             attachments: attachments.merge(opened.transform_values(&:attachment_names)),
+             encryptions: encryptions.merge(opened.transform_values { |content| MailEncryption.decrypted(content) }))
+      end
+
+      # Each message's JSON (from the block) with its folder path
+      def json = messages.map { |message| yield(message).merge(folder: folder(message)) }
+
+      # As `read --json` gives each message, plus its folder
+      def full_json
+        json do |message|
+          encryption = encryption(message)
+          hash = message.full_json_hash(attachments: names(message))
+          encryption ? hash.merge(encryption: encryption) : hash
+        end
+      end
+
+      # As `read` prints each message, with its folder (and how it was protected) before the ID
+      def texts = messages.map { |message| message.to_text(attachments: names(message), notes: notes(message)) }
+
+      # list's tab-separated columns plus the folder path
+      def tsv_rows = messages.map { |message| "#{message.tsv_row}\t#{folder(message).to_s.tr("\t", ' ')}" }
+
+      private
+
+      def names(message) = attachments.fetch(message.id, [])
+
+      def encryption(message) = message.encryption_in(encryptions)
+
+      def notes(message)
+        protection = MailEncryption.notes(encryption(message), web_link: message.web_link)
+        { 'Folder' => folder(message) }.compact.merge(protection)
+      end
+    end
+  end
+end

data/lib/teems/models/mail_encryption.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Teems
+  module Models
+    # How protected mail was shown, as { type: 'smime' | 'purview', decrypted:, signed: } (signed
+    # only once decrypted), and the header lines `read` and `thread --full` print for it. Purview
+    # mail gets its Outlook on the web link, where Exchange decrypts it for you.
+    module MailEncryption
+      LOCKED_HINT = 'S/MIME encrypted; read it with --decrypt (macOS asks for your PIV PIN)'
+
+      # 'purview' (rights-managed, Content-Class rpmsg.message), 'smime' (an S/MIME envelope),
+      # or nil, from a message's internet headers. Drafts have none, and Exchange wraps most
+      # S/MIME mail as TNEF (see envelope?), so nil is not proof of plain mail.
+      def self.from_headers(headers)
+        fields = Array(headers).to_h { |header| [header['name'].to_s.downcase, header['value'].to_s.downcase] }
+        return 'purview' if fields['content-class'].to_s.start_with?('rpmsg.message')
+
+        type, params = Support::MimeHeader.field(fields['content-type'])
+        'smime' if Support::MimePart::PKCS7_TYPES.include?(type) && params['smime-type'] != 'signed-data'
+      end
+
+      def self.notes(encryption, web_link: nil)
+        return {} unless encryption
+
+        type = encryption[:type]
+        return { 'Encryption' => MailMessage::PROTECTION_NOTES[type], 'Open' => web_link }.compact if type == 'purview'
+        return { 'Encryption' => LOCKED_HINT } unless encryption[:decrypted]
+
+        { 'Encryption' => 'S/MIME, decrypted', 'Signature' => encryption[:signed] ? 'Signed (not checked)' : '' }
+          .reject { |_name, value| value.empty? }
+      end
+
+      def self.decrypted(content) = { type: 'smime', decrypted: true, signed: content.signed }
+
+      # An S/MIME envelope (smime.p7m) among a message's Graph attachments
+      def self.envelope?(attachment)
+        Support::MimePart::PKCS7_TYPES.include?(Support::MimeHeader.field(attachment['contentType']).first)
+      end
+    end
+  end
+end