msg_extractor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b63aa09723b0c4324a3d3189885557dfe8f72ea5b32b54631183c5f562fabe0
+  data.tar.gz: 2e9d0f2ac08c1d3c0df6c69f5110b7015275eca0a58927575c6969e87b36b152
+SHA512:
+  metadata.gz: c75dba1d0761bd47f24dc08897ee9846a50be175e5f43a92254364a8d11615bb58536a72db3cca6307ef40d8e236f9e914d093a9b2b30a4c2659f34ed7310ccd
+  data.tar.gz: 9fcfb42cff93e849fc4bd86003e714effa0de02d73c83fbead084b9553d7b4d559f3375f9bd299e7171f6a954e19b82936a3a29d20e151c5bf640d856eead773

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (2026-06-12)
+
+- Initial release: parse Outlook .msg files (emails, contacts, appointments,
+  tasks) into Ruby objects.
+- Attachment access including embedded .msg attachments.
+- RTF body decompression (LZFu) and RTF-encapsulated HTML extraction.
+- Save-to-folder helpers and a msg_extractor CLI with --json output.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bart Duchesne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# msg_extractor
+
+Pure Ruby parser for Microsoft Outlook `.msg` files. Parses the OLE2/CFBF
+container and MAPI properties into structured Ruby objects — no native
+extensions, no runtime dependencies, no Python. Built for use in Ruby and
+Rails applications.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "msg_extractor"
+```
+
+Requires Ruby >= 3.1.
+
+## Usage
+
+```ruby
+require "msg_extractor"
+
+msg = MsgExtractor.open("invoice.msg")   # also accepts an IO or a binary String
+
+msg.subject        # => "Invoice 2026-001"
+msg.sender         # => #<MsgExtractor::Recipient name="Bob" email="bob@example.com">
+msg.to             # => [Recipient, ...]   (also: cc, bcc, recipients)
+msg.date           # => Time (UTC)
+msg.body           # => plain text body (UTF-8)
+msg.html_body      # => HTML body; extracted from the RTF body when absent
+msg.rtf_body       # => decompressed RTF (binary) or nil
+msg.headers        # => case-insensitive transport headers: msg.headers["Subject"]
+
+msg.attachments.each do |att|
+  att.filename     # => "report.pdf"
+  att.mime_type    # => "application/pdf"
+  att.content_id   # => for matching cid: URLs in html_body
+  att.data         # => raw bytes — hand to ActiveStorage, S3, etc.
+  att.save(dir: "tmp/")
+  att.message      # => parsed MsgExtractor::Message when the attachment
+                   #    is itself an embedded .msg (att.embedded_message?)
+end
+
+msg.save(dir: "out/")  # writes message.txt, message.html and attachments
+```
+
+`MsgExtractor.open` returns a typed object based on the message class:
+
+| Message class | Returned type | Extra readers |
+|---|---|---|
+| IPM.Note, REPORT.* | `Message` | — |
+| IPM.Contact, IPM.DistList | `Contact` | `display_name`, `given_name`, `surname`, `company`, `job_title`, `business_phone`, `home_phone`, `mobile_phone`, `postal_address`, `emails` |
+| IPM.Appointment, IPM.Schedule.Meeting.* | `Appointment` | `starts_at`, `ends_at`, `location`, `all_day?`, `organizer`, `required_attendees`, `optional_attendees` |
+| IPM.Task | `Task` | `starts_on`, `due_on`, `status`, `percent_complete`, `complete?`, `owner` |
+
+Other message classes raise `MsgExtractor::UnsupportedTypeError`; pass
+`strict: false` to get a generic `MessageObject` instead.
+
+Errors: all inherit from `MsgExtractor::Error` — `InvalidFormatError`,
+`UnsupportedTypeError`, `CorruptFileError`.
+
+## CLI
+
+```
+msg_extractor FILE... [--out DIR] [--json] [--attachments-only]
+```
+
+## Development
+
+```
+bundle install
+rake test
+```
+
+Test fixtures and oracle data come from the Python
+[extract_msg](https://github.com/TeamMsgExtractor/msg-extractor) project,
+which this gem uses as a black-box behavioral reference (no code is
+translated from it). See `tool/generate_oracle.py`.
+
+## Credits
+
+This gem was developed with [Claude Code](https://claude.com/claude-code)
+(Anthropic's Claude Fable 5 model), implementing the Microsoft open
+specifications ([MS-CFB], [MS-OXMSG], [MS-OXRTFCP], [MS-OXRTFEX]) and
+validated against the output of the Python extract_msg library.
+
+## License
+
+MIT.

data/exe/msg_extractor

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require "msg_extractor"
+require "msg_extractor/cli"
+
+exit MsgExtractor::CLI.run(ARGV)

data/lib/msg_extractor/appointment.rb

@@ -0,0 +1,20 @@
+module MsgExtractor
+  # IPM.Appointment and IPM.Schedule.Meeting.* items. Times come from
+  # PSETID_Appointment named properties and are returned as UTC Time.
+  class Appointment < MessageObject
+    PSETID_APPOINTMENT = "00062002-0000-0000-c000-000000000046"
+
+    LID_START_WHOLE = 0x820D
+    LID_END_WHOLE = 0x820E
+    LID_LOCATION = 0x8208
+    LID_ALL_DAY = 0x8215
+
+    def starts_at = named_value(PSETID_APPOINTMENT, LID_START_WHOLE)
+    def ends_at = named_value(PSETID_APPOINTMENT, LID_END_WHOLE)
+    def location = named_value(PSETID_APPOINTMENT, LID_LOCATION)
+    def all_day? = named_value(PSETID_APPOINTMENT, LID_ALL_DAY) == true
+    def organizer = sender
+    def required_attendees = to
+    def optional_attendees = cc
+  end
+end

data/lib/msg_extractor/attachment.rb

@@ -0,0 +1,57 @@
+module MsgExtractor
+  class Attachment
+    BY_VALUE = 1
+    EMBEDDED_MSG = 5
+
+    attr_reader :properties
+
+    def initialize(cfbf, storage, named: nil)
+      @cfbf = cfbf
+      @storage = storage
+      @named = named
+      @properties = Mapi::PropertyStore.new(cfbf, storage, :attachment)
+    end
+
+    def filename
+      properties[Mapi::PR_ATTACH_LONG_FILENAME] || properties[Mapi::PR_ATTACH_FILENAME]
+    end
+
+    def mime_type = properties[Mapi::PR_ATTACH_MIME_TAG]
+    def content_id = properties[Mapi::PR_ATTACH_CONTENT_ID]
+    def attach_method = properties[Mapi::PR_ATTACH_METHOD] || BY_VALUE
+    def embedded_message? = attach_method == EMBEDDED_MSG
+
+    def inline?
+      properties[Mapi::PR_ATTACHMENT_HIDDEN] == true || !content_id.nil?
+    end
+
+    # Bytes are memoized on first read and pinned until this Attachment is GC'd.
+    # That is deliberate: size, save, and data all reuse the same single read.
+    def data
+      return nil if embedded_message?
+      return @data if defined?(@data)
+      @data = properties.raw(Mapi::PR_ATTACH_DATA)
+    end
+
+    def size = data&.bytesize
+
+    # The parsed embedded message, when this attachment is a nested .msg.
+    # Always lenient (strict: false): raising lazily from an accessor would
+    # surprise callers, and embedded items are often non-email types.
+    def message
+      return @message if defined?(@message)
+      @message =
+        if embedded_message? && (sub = @storage.children["__SUBSTG1.0_3701000D"]) && sub.storage?
+          MsgExtractor.from_storage(@cfbf, sub, named: @named, kind: :embedded, strict: false)
+        end
+    end
+
+    def save(dir: ".")
+      raise Error, "cannot save an embedded message attachment as a file" if embedded_message?
+      raise Error, "attachment #{filename.inspect} has no data stream" if data.nil?
+      path = Util.dedupe_path(::File.join(dir, Util.sanitize_filename(filename || "attachment")))
+      ::File.binwrite(path, data)
+      path
+    end
+  end
+end

data/lib/msg_extractor/cfbf/directory.rb

@@ -0,0 +1,84 @@
+module MsgExtractor
+  module Cfbf
+    # One 128-byte directory entry: a storage (folder), stream (file), or root.
+    class Entry
+      TYPE_STORAGE = 1
+      TYPE_STREAM = 2
+      TYPE_ROOT = 5
+
+      attr_reader :name, :type, :left, :right, :child, :start_sector, :size
+      attr_accessor :children
+
+      def initialize(record)
+        name_len = record.byteslice(64, 2).unpack1("v")
+        name_len = 64 if name_len > 64
+        @name = if name_len >= 2
+                  record.byteslice(0, name_len - 2)
+                        .force_encoding(Encoding::UTF_16LE)
+                        .encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+                else
+                  ""
+                end
+        @type = record.getbyte(66)
+        @left, @right, @child = record.byteslice(68, 12).unpack("V3")
+        @start_sector = record.byteslice(116, 4).unpack1("V")
+        @size = record.byteslice(120, 8).unpack1("Q<")
+        @children = {}
+      end
+
+      def storage? = @type == TYPE_STORAGE || @type == TYPE_ROOT
+      def stream? = @type == TYPE_STREAM
+    end
+
+    # Parses the directory sector chain and links each storage's red-black
+    # sibling tree into a flat children hash (keyed by upcased name).
+    class Directory
+      attr_reader :root
+
+      def initialize(dir_bytes)
+        @entries = []
+        (dir_bytes.bytesize / 128).times do |i|
+          record = dir_bytes.byteslice(i * 128, 128)
+          @entries << (record.getbyte(66).to_i.zero? ? nil : Entry.new(record))
+        end
+        @root = @entries[0]
+        unless @root && @root.type == Entry::TYPE_ROOT
+          raise CorruptFileError, "compound file has no root directory entry"
+        end
+        link_all_children
+      end
+
+      private
+
+      # Iterative directory walk with a single visited-set shared across all
+      # storages.  Each work-queue item is [parent_entry, child_index].
+      # Raises CorruptFileError if any entry index is visited more than once
+      # (catches both sibling-tree cycles and cross-storage back-references).
+      def link_all_children
+        visited = {}
+        # queue items: [parent_entry, entry_index_to_process]
+        queue = []
+        queue.push([@root, @root.child]) unless @root.child == NOSTREAM
+
+        until queue.empty?
+          parent, index = queue.shift
+          next if index == NOSTREAM
+          raise CorruptFileError, "directory entry cycle at index #{index}" if visited[index]
+          visited[index] = true
+
+          child = @entries[index]
+          raise CorruptFileError, "directory references missing entry #{index}" unless child
+
+          parent.children[child.name.upcase] = child
+
+          queue.push([parent, child.left])  unless child.left  == NOSTREAM
+          queue.push([parent, child.right]) unless child.right == NOSTREAM
+
+          if child.storage? && child.child != NOSTREAM
+            queue.push([child, child.child])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/msg_extractor/cfbf/fat.rb

@@ -0,0 +1,75 @@
+module MsgExtractor
+  module Cfbf
+    # The File Allocation Table: maps each sector index to the next sector in
+    # its chain. Built from the header DIFAT plus chained DIFAT sectors.
+    class Fat
+      def initialize(data, header)
+        @data = data
+        @header = header
+        @entries = build_entries
+      end
+
+      def sector_bytes(sector)
+        offset = (sector + 1) * @header.sector_size
+        bytes = @data.byteslice(offset, @header.sector_size)
+        if bytes.nil? || bytes.empty?
+          raise CorruptFileError, "sector #{sector} beyond end of file"
+        end
+        bytes
+      end
+
+      def chain(start)
+        sectors = []
+        seen = {}
+        sector = start
+        while sector != ENDOFCHAIN
+          raise CorruptFileError, "FAT chain cycle at sector #{sector}" if seen[sector]
+          if sector >= @entries.size
+            raise CorruptFileError, "FAT chain references invalid sector #{sector}"
+          end
+          seen[sector] = true
+          sectors << sector
+          sector = @entries[sector]
+        end
+        sectors
+      end
+
+      def read_chain(start)
+        chain(start).map { |s| sector_bytes(s) }.join
+      end
+
+      private
+
+      def build_entries
+        max_sectors = @data.bytesize / @header.sector_size
+        fat_sectors = @header.difat_head.reject { |s| s == FREESECT }
+        difat_sector = @header.first_difat_sector
+        seen_difat = {}
+        iterations = 0
+        while difat_sector != ENDOFCHAIN && difat_sector != FREESECT
+          if seen_difat[difat_sector]
+            raise CorruptFileError, "DIFAT sector cycle at #{difat_sector}"
+          end
+          seen_difat[difat_sector] = true
+          iterations += 1
+          if iterations > max_sectors
+            raise CorruptFileError, "DIFAT chain exceeds file size"
+          end
+          slice = sector_bytes(difat_sector)
+          if slice.bytesize < @header.sector_size
+            raise CorruptFileError, "DIFAT sector #{difat_sector} is truncated"
+          end
+          values = slice.unpack("V*")
+          next_difat = values.pop
+          fat_sectors.concat(values.reject { |s| s == FREESECT })
+          # M2: stop appending if fat_sectors count would exceed max possible sectors
+          if fat_sectors.size > max_sectors
+            raise CorruptFileError, "FAT sector list exceeds file size"
+          end
+          difat_sector = next_difat
+        end
+        fat_sectors.flat_map { |s| sector_bytes(s).unpack("V*") }
+      end
+    end
+  end
+end

data/lib/msg_extractor/cfbf/file.rb

@@ -0,0 +1,114 @@
+module MsgExtractor
+  module Cfbf
+    # The assembled compound file: directory tree plus stream extraction.
+    # Streams smaller than the mini-stream cutoff (4096) live in the
+    # ministream and are chained through the miniFAT; larger streams are
+    # chained directly through the FAT.
+    class File
+      attr_reader :root
+
+      # Accepts a filesystem path, a binary String of file content, or an IO.
+      # Strings beginning with the OLE signature are treated as content;
+      # all other Strings are treated as filesystem paths.
+      def self.read(source)
+        data =
+          if source.is_a?(::String)
+            b = source.b
+            if b.byteslice(0, 8) == Header::SIGNATURE
+              b
+            else
+              begin
+                ::File.binread(source)
+              rescue Errno::ENAMETOOLONG, Errno::EINVAL, ArgumentError
+                raise InvalidFormatError, "not an OLE2 file and not a readable path"
+              end
+            end
+          elsif source.respond_to?(:read)
+            source.read.b
+          else
+            raise ArgumentError, "cannot read MSG from #{source.class}"
+          end
+        new(data)
+      end
+
+      def initialize(data)
+        @data = data.encoding == Encoding::BINARY ? data : data.b
+        raise InvalidFormatError, "file too small to be an OLE2 file" if @data.bytesize < 512
+        @header = Header.new(@data.byteslice(0, 512))
+        @fat = Fat.new(@data, @header)
+        @directory = Directory.new(@fat.read_chain(@header.first_dir_sector))
+        @root = @directory.root
+        @mini_stream =
+          if @root.size.zero?
+            "".b
+          else
+            if @root.size > @data.bytesize
+              raise CorruptFileError, "root ministream size #{@root.size} exceeds file size"
+            end
+            chain_bytes = @fat.read_chain(@root.start_sector)
+            if chain_bytes.bytesize < @root.size
+              raise CorruptFileError, "root ministream chain shorter than declared size"
+            end
+            chain_bytes.byteslice(0, @root.size)
+          end
+        @minifat =
+          if @header.num_minifat_sectors.positive? && @header.first_minifat_sector != ENDOFCHAIN
+            @fat.read_chain(@header.first_minifat_sector).unpack("V*")
+          else
+            []
+          end
+      end
+
+      # Path components separated by "/", matched case-insensitively.
+      def entry(path)
+        current = @root
+        path.split("/").each do |part|
+          current = current.children[part.upcase]
+          return nil unless current
+        end
+        current
+      end
+
+      def stream(path)
+        e = entry(path)
+        e&.stream? ? read_stream(e) : nil
+      end
+
+      def read_stream(entry)
+        return "".b if entry.size.zero?
+        if entry.size > @data.bytesize
+          raise CorruptFileError, "stream entry size #{entry.size} exceeds file size"
+        end
+        if entry.size < @header.mini_stream_cutoff
+          read_mini_stream(entry)
+        else
+          chain_bytes = @fat.read_chain(entry.start_sector)
+          if chain_bytes.bytesize < entry.size
+            raise CorruptFileError, "FAT stream chain shorter than declared size"
+          end
+          chain_bytes.byteslice(0, entry.size)
+        end
+      end
+
+      private
+
+      def read_mini_stream(entry)
+        out = +"".b
+        size = @header.mini_sector_size
+        sector = entry.start_sector
+        seen = {}
+        while sector != ENDOFCHAIN
+          if seen[sector] || sector >= @minifat.size
+            raise CorruptFileError, "broken miniFAT chain at #{sector}"
+          end
+          seen[sector] = true
+          slice = @mini_stream.byteslice(sector * size, size)
+          raise CorruptFileError, "mini-stream sector #{sector} out of range" if slice.nil?
+          out << slice
+          sector = @minifat[sector]
+        end
+        out.byteslice(0, entry.size)
+      end
+    end
+  end
+end

data/lib/msg_extractor/cfbf/header.rb

@@ -0,0 +1,40 @@
+module MsgExtractor
+  # Reader for the OLE2 / Compound File Binary Format ([MS-CFB]) used as the
+  # container of .msg files.
+  module Cfbf
+    FREESECT   = 0xFFFFFFFF
+    ENDOFCHAIN = 0xFFFFFFFE
+    FATSECT    = 0xFFFFFFFD
+    DIFSECT    = 0xFFFFFFFC
+    NOSTREAM   = 0xFFFFFFFF
+
+    class Header
+      SIGNATURE = "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b.freeze
+
+      attr_reader :sector_size, :mini_sector_size, :num_fat_sectors,
+                  :first_dir_sector, :mini_stream_cutoff,
+                  :first_minifat_sector, :num_minifat_sectors,
+                  :first_difat_sector, :num_difat_sectors, :difat_head
+
+      def initialize(bytes)
+        unless bytes && bytes.bytesize >= 512 && bytes.byteslice(0, 8) == SIGNATURE
+          raise InvalidFormatError, "not an OLE2 compound file (bad signature)"
+        end
+        sector_shift = bytes.byteslice(30, 2).unpack1("v")
+        mini_shift   = bytes.byteslice(32, 2).unpack1("v")
+        unless sector_shift == 9 || sector_shift == 12
+          raise InvalidFormatError, "invalid sector shift #{sector_shift} (must be 9 or 12)"
+        end
+        unless mini_shift == 6
+          raise InvalidFormatError, "invalid mini sector shift #{mini_shift} (must be 6)"
+        end
+        @sector_size = 1 << sector_shift
+        @mini_sector_size = 1 << mini_shift
+        @num_fat_sectors, @first_dir_sector, _txn_sig, @mini_stream_cutoff,
+          @first_minifat_sector, @num_minifat_sectors,
+          @first_difat_sector, @num_difat_sectors = bytes.byteslice(44, 32).unpack("V8")
+        @difat_head = bytes.byteslice(76, 436).unpack("V109")
+      end
+    end
+  end
+end

data/lib/msg_extractor/cli.rb

@@ -0,0 +1,77 @@
+require "optparse"
+require "json"
+require "time"
+require "fileutils"
+
+module MsgExtractor
+  class CLI
+    def self.run(argv, stdout: $stdout, stderr: $stderr)
+      options = { out: ".", json: false, attachments_only: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: msg_extractor FILE... [options]"
+        opts.on("--out DIR", "Output directory (default: current directory)") do |dir|
+          options[:out] = dir
+        end
+        opts.on("--json", "Print one JSON object per file to stdout instead of saving") do
+          options[:json] = true
+        end
+        opts.on("--attachments-only", "Save only the attachments, flat into --out") do
+          options[:attachments_only] = true
+        end
+        opts.on("--version", "Print version") do
+          stdout.puts MsgExtractor::VERSION
+          return 0
+        end
+      end
+
+      begin
+        files = parser.parse(argv)
+      rescue OptionParser::ParseError => e
+        stderr.puts e.message
+        stderr.puts parser.banner
+        return 2
+      end
+      if files.empty?
+        stderr.puts parser.banner
+        return 2
+      end
+
+      status = 0
+      files.each do |file|
+        msg = MsgExtractor.open(file)
+        if options[:json]
+          stdout.puts JSON.generate(json_for(msg, file))
+        elsif options[:attachments_only]
+          FileUtils.mkdir_p(options[:out])
+          msg.attachments.reject(&:embedded_message?).each { |a| a.save(dir: options[:out]) }
+        else
+          FileUtils.mkdir_p(options[:out])
+          msg.save(dir: options[:out])
+        end
+      rescue MsgExtractor::Error, SystemCallError => e
+        stderr.puts "#{file}: #{e.message}"
+        status = 1
+      end
+      status
+    end
+
+    def self.json_for(msg, file)
+      {
+        file: file,
+        message_class: msg.message_class,
+        subject: msg.subject,
+        date: msg.date&.utc&.iso8601,
+        sender: msg.sender && { name: msg.sender.name, email: msg.sender.email },
+        to: msg.to.map { |r| { name: r.name, email: r.email } },
+        cc: msg.cc.map { |r| { name: r.name, email: r.email } },
+        bcc: msg.bcc.map { |r| { name: r.name, email: r.email } },
+        body: msg.body,
+        html_body: msg.html_body,
+        attachments: msg.attachments.map do |a|
+          { filename: a.filename, mime_type: a.mime_type, content_id: a.content_id,
+            size: a.size, embedded_message: a.embedded_message? }
+        end
+      }
+    end
+  end
+end

data/lib/msg_extractor/contact.rb

@@ -0,0 +1,23 @@
+module MsgExtractor
+  # IPM.Contact / IPM.DistList. Email addresses live in PSETID_Address named
+  # properties (Email1/2/3 EmailAddress LIDs).
+  class Contact < MessageObject
+    PSETID_ADDRESS = "00062004-0000-0000-c000-000000000046"
+
+    EMAIL_LIDS = [0x8083, 0x8093, 0x80A3].freeze
+
+    def display_name = properties[Mapi::PR_DISPLAY_NAME] || subject
+    def given_name = properties[Mapi::PR_GIVEN_NAME]
+    def surname = properties[Mapi::PR_SURNAME]
+    def company = properties[Mapi::PR_COMPANY_NAME]
+    def job_title = properties[Mapi::PR_JOB_TITLE]
+    def business_phone = properties[Mapi::PR_BUSINESS_PHONE]
+    def home_phone = properties[Mapi::PR_HOME_PHONE]
+    def mobile_phone = properties[Mapi::PR_MOBILE_PHONE]
+    def postal_address = properties[Mapi::PR_POSTAL_ADDRESS]
+
+    def emails
+      EMAIL_LIDS.filter_map { |lid| named_value(PSETID_ADDRESS, lid) }
+    end
+  end
+end

data/lib/msg_extractor/errors.rb

@@ -0,0 +1,12 @@
+module MsgExtractor
+  class Error < StandardError; end
+
+  # Not an OLE file, or an OLE file without MSG property streams.
+  class InvalidFormatError < Error; end
+
+  # Recognized MSG container but an unsupported message class.
+  class UnsupportedTypeError < Error; end
+
+  # Structurally broken file (bad FAT chains, truncated streams, bad records).
+  class CorruptFileError < Error; end
+end

data/lib/msg_extractor/headers.rb

@@ -0,0 +1,39 @@
+module MsgExtractor
+  # Parsed RFC 5322 transport headers with case-insensitive lookup.
+  #
+  # * +[]+ and +all+ are case-insensitive (e.g. h["subject"] == h["Subject"]).
+  # * +[]+ returns the first value for a header name.
+  # * +all+ returns every value for a header name.
+  # * +to_h+ keeps the original case of each header name and is first-value-wins
+  #   when the same name appears more than once.
+  class Headers
+    include Enumerable
+
+    def self.parse(text)
+      return new([]) if text.nil? || text.empty?
+      fields = []
+      text.each_line(chomp: true) do |line|
+        break if line.empty? # end of the header block
+        if line.start_with?(" ", "\t")
+          fields.last[1] << " " << line.strip unless fields.empty?
+        elsif (match = /\A([!-9;-~]+):[ \t]*(.*)\z/.match(line))
+          fields << [match[1], +match[2]]
+        end
+      end
+      new(fields)
+    end
+
+    def initialize(fields)
+      @fields = fields
+      # Build a downcased-name → values hash for O(1) lookup.
+      @index = {}
+      @fields.each { |name, value| (@index[name.downcase] ||= []) << value }
+    end
+
+    def [](key) = @index[key.downcase]&.first
+    def all(key) = (@index[key.downcase] || []).dup
+    def each(&block) = @fields.each(&block)
+    def to_h = @fields.each_with_object({}) { |(name, value), h| h[name] ||= value }
+    def empty? = @fields.empty?
+  end
+end