mailschema 0.2.0 → 0.3.0

data/lib/mailschema/formats.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # The formats MAP schemas may assert, defined as the reference implementation asserts them
+  # (ajv-formats' full definitions), so a value has a format here exactly when it has it there.
+  # Its uri and email expressions are ASCII-only and case-insensitive; Ruby folds case beyond
+  # ASCII, so other text is refused before they run.
+  module Formats
+    DATE = /\A(\d\d\d\d)-(\d\d)-(\d\d)\z/
+    DAYS = [nil, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
+    # The time of a date-time, whose zone ajv-formats requires.
+    TIME = /\A(\d\d):(\d\d):(\d\d(?:\.\d+)?)(z|([+-])(\d\d)(?::?(\d\d))?)\z/i
+    # A date-time splits at t or at ECMAScript's \s.
+    SEPARATOR = /[tT\t\n\v\f\r\u{2028}\u{2029}\u{FEFF}\p{Zs}]/
+    EMAIL = Regexp.new(<<~'PATTERN'.delete("\n"), Regexp::IGNORECASE)
+      \A[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+
+      [a-z0-9](?:[a-z0-9-]*[a-z0-9])?\z
+    PATTERN
+    URI = Regexp.new(<<~'PATTERN'.delete("\n"), Regexp::IGNORECASE)
+      \A(?:[a-z][a-z0-9+\-.]*:)(?:\/?\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:]|%[0-9a-f]{2})*@)?(?:\[(?:(?:(?:(?:[0-9a-f]{1,4}:){6}
+      |::(?:[0-9a-f]{1,4}:){5}|(?:[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){4}|(?:(?:[0-9a-f]{1,4}:){0,1}[0-9a-f]{1,4})?::(?:[0-9a
+      -f]{1,4}:){3}|(?:(?:[0-9a-f]{1,4}:){0,2}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){2}|(?:(?:[0-9a-f]{1,4}:){0,3}[0-9a-f]{1,4}
+      )?::[0-9a-f]{1,4}:|(?:(?:[0-9a-f]{1,4}:){0,4}[0-9a-f]{1,4})?::)(?:[0-9a-f]{1,4}:[0-9a-f]{1,4}|(?:(?:25[0-5]|2[0-4]\d|[
+      01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?))|(?:(?:[0-9a-f]{1,4}:){0,5}[0-9a-f]{1,4})?::[0-9a-f]{1,4}|(?:(?:[0-9a
+      -f]{1,4}:){0,6}[0-9a-f]{1,4})?::)|[Vv][0-9a-f]+\.[a-z0-9\-._~!$&'()*+,;=:]+)\]|(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3
+      }(?:25[0-5]|2[0-4]\d|[01]?\d\d?)|(?:[a-z0-9\-._~!$&'()*+,;=]|%[0-9a-f]{2})*)(?::\d*)?(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@
+      ]|%[0-9a-f]{2})*)*|\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*
+      )*)?|(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)(?:\?(?:[a-z0-9\-
+      ._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?(?:#(?:[a-z0-9\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?\z
+    PATTERN
+
+    class << self
+      def date?(value)
+        match = DATE.match(value) or return false
+        year, month, day = match.captures.map(&:to_i)
+        month.between?(1, 12) && day.between?(1, month == 2 && leap?(year) ? 29 : DAYS[month])
+      end
+
+      def date_time?(value)
+        parts = value.split(SEPARATOR, -1)
+        parts.size == 2 && date?(parts[0]) && time?(parts[1])
+      end
+
+      def email?(value) = value.ascii_only? && EMAIL.match?(value)
+
+      def uri?(value) = value.ascii_only? && value.match?(%r{[/:]}) && URI.match?(value)
+
+      # The checks json_schemer runs: these four, on strings only, and no other format.
+      def checks
+        own = { "date" => method(:date?), "date-time" => method(:date_time?), "email" => method(:email?),
+                "uri" => method(:uri?) }
+        JSONSchemer::Draft202012::FORMATS.transform_values { false }.merge(
+          own.transform_values { |check| ->(value, _format) { !value.is_a?(String) || check.call(value) } }
+        )
+      end
+
+      private
+
+      def leap?(year) = (year % 4).zero? && (!(year % 100).zero? || (year % 400).zero?)
+
+      # A time with a zone, allowing a leap second only at 23:59 UTC.
+      def time?(value)
+        match = TIME.match(value) or return false
+        hour, minute, zone_hour, zone_minute = match.values_at(1, 2, 6, 7).map(&:to_i)
+        second = match[3].to_f
+        return false if zone_hour > 23 || zone_minute > 59
+        return true if hour <= 23 && minute <= 59 && second < 60
+
+        sign = match[5] == "-" ? -1 : 1
+        utc_minute = minute - (zone_minute * sign)
+        utc_hour = hour - (zone_hour * sign) - (utc_minute.negative? ? 1 : 0)
+        [23, -1].include?(utc_hour) && [59, -1].include?(utc_minute) && second < 61
+      end
+    end
+  end
+  private_constant :Formats
+end

data/lib/mailschema/header.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # Header fields read from an entity's original bytes. A parsed message collapses repeated
+  # fields and keeps the last of repeated parameters, so MAP's uniqueness rules are checked
+  # here, where different parsers cannot read one header differently.
+  module Header
+    FIELD = /\A([!-9;-~]+):[ \t]*(.*)\z/m
+    PARAMETER = /\A\s*([!\#$%&'*+.^_`|~0-9A-Za-z-]+)\s*=/
+
+    class << self
+      # The unfolded fields of a raw entity's header block as [lowercase name, value] pairs, or
+      # nil when it is malformed. Lines end with CRLF. `lax` also accepts LF, and skips the
+      # line break a MIME part's raw source keeps from its boundary line.
+      def fields(raw, lax: false)
+        raw = raw.b
+        block, separator, = raw.partition(lax ? /\r?\n\r?\n/ : "\r\n\r\n")
+        return if separator.empty?
+
+        lines = block.split(lax ? /\r?\n/ : "\r\n", -1)
+        unfold(lax ? lines.drop_while(&:empty?) : lines)
+      end
+
+      # Whether every parameter of a Content-Type value has its own name. RFC 2231 sections and
+      # charset markers belong to the name they extend, so profile and profile* are one name.
+      def unique_parameters?(value)
+        segments = parameters(value) or return false
+        names = segments.drop(1).map do |segment|
+          name = PARAMETER.match(segment)&.[](1) or return false
+          name.downcase.sub(/\*.*\z/, "")
+        end
+        names.uniq.size == names.size
+      end
+
+      private
+
+      # The fields of header lines, each folded line joined to its field, or nil when a line is
+      # neither or holds another line break.
+      def unfold(lines)
+        lines.each_with_object([]) do |line, fields|
+          return nil if line.match?(/[\r\n]/)
+
+          if line.start_with?(" ", "\t")
+            return nil if fields.empty?
+
+            fields.last[1] << " " << line.strip
+          else
+            name, value = FIELD.match(line)&.captures
+            return nil unless name
+
+            fields << [name.downcase, value]
+          end
+        end
+      end
+
+      # The value split at each semicolon outside a quoted string, or nil when a quoted string
+      # or an escape is left open.
+      def parameters(value)
+        segments = [+""]
+        quoted = escaped = false
+        value.each_char do |char|
+          next segments << +"" if char == ";" && !quoted
+
+          if escaped then escaped = false
+          elsif quoted && char == "\\" then escaped = true
+          elsif char == '"' then quoted = !quoted
+          end
+          segments.last << char
+        end
+        segments unless quoted || escaped
+      end
+    end
+  end
+  private_constant :Header
+end

data/lib/mailschema/implementation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# An implementation record: a Registry declaration or report of a service's support for exact
+# contract versions.
+module Mailschema
+  # Why the value is not an implementation record, or no reasons.
+  def self.implementation_errors(value)
+    errors = Schemas.errors(Schemas::IMPLEMENTATION, value)
+    return errors if errors.any?
+
+    origin = Origin.of(value["service"])
+    unless origin && [origin, "#{origin}/"].include?(value["service"])
+      errors << "/service: must be an HTTPS origin, not an operation path"
+    end
+    errors << "/operations: identifiers must be unique" if value["operations"].uniq.size != value["operations"].size
+    errors
+  end
+
+  # The record in the bytes or text, or InvalidDocument with every reason it is not one.
+  def self.parse_implementation(input)
+    value = parse(input, CONTRACT_MAX_BYTES)
+    errors = implementation_errors(value)
+    raise InvalidDocument.new("The value is not an implementation record.", errors) if errors.any?
+
+    value
+  end
+end

data/lib/mailschema/jcs.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Mailschema
-  # The JSON Canonicalization Scheme of RFC 8785: members sorted by their UTF-16
-  # code units, the minimal string escapes of ECMAScript and its number format.
+  # The JSON Canonicalization Scheme of RFC 8785: members sorted by their UTF-16 code units,
+  # ECMAScript's minimal string escapes and its number format.
   module JCS
     ESCAPES = {
       '"' => '\\"', "\\" => "\\\\", "\b" => "\\b", "\f" => "\\f",
@@ -23,13 +23,13 @@ module Mailschema
       when true then "true"
       when false then "false"
       when nil then "null"
-      else raise ArgumentError, "#{value.class} is not a JSON value"
+      else raise TypeError, "#{value.class} is not a JSON value."
       end
     end
 
     def object(value)
       members = value.map do |name, member|
-        raise ArgumentError, "object member names must be strings" unless name.is_a?(String)
+        raise TypeError, "Object member names must be strings." unless name.is_a?(String)
 
         [utf8(name).encode(Encoding::UTF_16BE).unpack("n*"), name, member]
       end
@@ -37,6 +37,7 @@ module Mailschema
       "{#{pairs.join(",")}}"
     end
 
+    # The string as JSON.stringify writes it.
     def quote(value)
       escaped = utf8(value).gsub(/["\\\x00-\x1f]/) { |char| ESCAPES.fetch(char) { format("\\u%04x", char.ord) } }
       %("#{escaped}")
@@ -44,16 +45,16 @@ module Mailschema
 
     def utf8(value)
       string = value.encoding == Encoding::UTF_8 ? value : value.encode(Encoding::UTF_8)
-      raise ArgumentError, "strings must be valid UTF-8" unless string.valid_encoding?
+      raise TypeError, "Strings must be valid UTF-8." unless string.valid_encoding?
 
       string
     rescue EncodingError
-      raise ArgumentError, "strings must be valid UTF-8"
+      raise TypeError, "Strings must be valid UTF-8."
     end
 
     # ECMA-262 Number::toString, from the shortest round-trip digits Float#to_s gives.
     def number(value)
-      raise ArgumentError, "numbers must be finite" unless value.finite?
+      raise TypeError, "Numbers must be finite." unless value.finite?
       return "0" if value.zero?
       return "-#{number(-value)}" if value.negative?
 
@@ -71,8 +72,8 @@ module Mailschema
       end
     end
 
-    # The significant digits of a positive double, and where its decimal point falls:
-    # the value is 0.digits × 10^point.
+    # The significant digits of a positive double, and where its decimal point falls: the
+    # value is 0.digits x 10^point.
     def shortest(value)
       mantissa, exponent = value.to_s.split("e")
       whole, fraction = mantissa.split(".")
@@ -81,7 +82,7 @@ module Mailschema
       [digits[leading..].sub(/0+\z/, ""), whole.length + exponent.to_i - leading]
     end
 
-    private_class_method :object, :quote, :utf8, :number, :shortest
+    private_class_method :object, :utf8, :number, :shortest
   end
   private_constant :JCS
 end

data/lib/mailschema/json.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+# MAP JSON: I-JSON parsed from its original text, and the RFC 8785 digests that identify
+# contracts and descriptions.
+module Mailschema
+  # A document that is not MAP JSON, or not the document it claims to be.
+  class InvalidDocument < StandardError
+    attr_reader :errors
+
+    def initialize(message, errors = [message])
+      super(message)
+      @errors = errors
+    end
+  end
+
+  MAX_DEPTH = 32
+
+  # Parse MAP JSON from its original text or bytes: UTF-8 I-JSON (RFC 7493) of at most
+  # `max_bytes`, with no byte order mark, duplicate member names, lone surrogates,
+  # noncharacters or U+0000, no container deeper than 32 counting the root as 1, and every
+  # number a finite token of at most 64 characters within +/-(2^53-1) that does not underflow
+  # to zero. These rules apply to the original tokens, before a general parser could erase
+  # them. A number with no fractional part is an Integer: I-JSON numbers are doubles, so 1 and
+  # 1.0 are one number.
+  def self.parse(input, max_bytes)
+    text = utf8(input)
+    raise InvalidDocument, "A byte order mark is not allowed." if text.start_with?("\u{FEFF}")
+    raise InvalidDocument, "The JSON exceeds #{max_bytes} bytes." if text.bytesize > max_bytes
+
+    Reader.new(text).document
+  end
+
+  # The RFC 8785 canonical form of a JSON value.
+  def self.canonicalize(value) = JCS.canonicalize(value)
+
+  # `sha-256:` and the SHA-256 of the value's RFC 8785 form, as MAP identifies contracts.
+  def self.digest(value) = "sha-256:#{Digest::SHA256.hexdigest(canonicalize(value))}"
+
+  NOT_UTF8 = "The JSON is not valid UTF-8."
+  private_constant :NOT_UTF8
+
+  # The text, from bytes or a string in any encoding, refusing anything but well-formed UTF-8.
+  def self.utf8(input)
+    raise TypeError, "MAP JSON is text or bytes." unless input.is_a?(String)
+
+    text = input.encoding == Encoding::BINARY ? input.dup.force_encoding(Encoding::UTF_8) : input.encode(Encoding::UTF_8)
+    return text if text.valid_encoding?
+
+    raise InvalidDocument, NOT_UTF8
+  rescue EncodingError
+    raise InvalidDocument, NOT_UTF8
+  end
+  private_class_method :utf8
+
+  # json.ts's reader: the grammar of RFC 8259 over the text, failing at the first token that
+  # breaks a MAP rule.
+  class Reader
+    MAX_NUMBER_TOKEN = 64
+    EXACT = (2**53) - 1
+    # Half the smallest subnormal: a nonzero token at or below it rounds to zero.
+    TINY = Rational(1, 2**1075)
+    NUMBER = /-?(0|[1-9][0-9]*)(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?/
+    STRING = /"((?>[^"\\]+|\\.)*)"/m
+    WELL_FORMED = %r{\A(?>[^\\\x00-\x1f]+|\\["\\/bfnrt]|\\u\h{4})*\z}
+    UNESCAPE = { '"' => '"', "\\" => "\\", "/" => "/", "b" => "\b", "f" => "\f", "n" => "\n", "r" => "\r",
+                 "t" => "\t" }.freeze
+    LITERALS = { "true" => true, "false" => false, "null" => nil }.freeze
+
+    def initialize(text)
+      @scanner = StringScanner.new(text)
+    end
+
+    def document
+      result = value(0)
+      space
+      refuse("trailing content") unless @scanner.eos?
+      result
+    end
+
+    private
+
+    # The offset counts UTF-16 code units, as json.ts reports it.
+    def refuse(reason, beyond = 0)
+      offset = (@scanner.string.byteslice(0, @scanner.pos).encode(Encoding::UTF_16LE).bytesize / 2) + beyond
+      raise InvalidDocument, "Invalid MAP JSON at offset #{offset}: #{reason}."
+    end
+
+    def space = @scanner.skip(/[ \t\n\r]*/)
+
+    # `depth` counts the containers enclosing the value.
+    def value(depth)
+      space
+      case @scanner.peek(1)
+      when "{", "["
+        refuse("nesting deeper than #{MAX_DEPTH}") if depth >= MAX_DEPTH
+        @scanner.getch == "{" ? object(depth + 1) : array(depth + 1)
+      when '"' then string
+      else
+        literal = @scanner.scan(/true|false|null/)
+        literal ? LITERALS.fetch(literal) : number
+      end
+    end
+
+    def object(depth)
+      result = {}
+      space
+      return result if @scanner.skip(/\}/)
+
+      loop do
+        space
+        refuse("expected a member name") unless @scanner.peek(1) == '"'
+        name = string
+        refuse("duplicate member #{JCS.quote(name)}") if result.key?(name)
+        space
+        refuse('expected ":"') unless @scanner.skip(/:/)
+        result[name] = value(depth)
+        space
+        next if @scanner.skip(/,/)
+        return result if @scanner.skip(/\}/)
+
+        refuse('expected "," or "}"')
+      end
+    end
+
+    def array(depth)
+      result = []
+      space
+      return result if @scanner.skip(/\]/)
+
+      loop do
+        result << value(depth)
+        space
+        next if @scanner.skip(/,/)
+        return result if @scanner.skip(/\]/)
+
+        refuse('expected "," or "]"')
+      end
+    end
+
+    def string
+      unless @scanner.scan(STRING)
+        # json.ts steps over an escape's two characters, past the end when the text ends in one.
+        escape = @scanner.rest[1..][/\\*\z/].length.odd?
+        @scanner.terminate
+        refuse("unterminated string", escape ? 1 : 0)
+      end
+      refuse("malformed string") unless WELL_FORMED.match?(@scanner[1])
+      text = unescape(@scanner[1]) or refuse("lone surrogate")
+      refuse("U+0000 or a noncharacter") if text.each_codepoint.any? { |point| forbidden?(point) }
+      text
+    end
+
+    # JSON escapes name UTF-16 code units, so a string with escapes is rebuilt in UTF-16,
+    # where a lone surrogate is invalid.
+    def unescape(body)
+      return body unless body.include?("\\")
+
+      units = body.scan(/\\u(\h{4})|\\(.)|([^\\]+)/m).flat_map do |code, escape, text|
+        if code then [code.hex]
+        elsif escape then [UNESCAPE.fetch(escape).ord]
+        else text.encode(Encoding::UTF_16LE).unpack("v*")
+        end
+      end
+      text = units.pack("v*").force_encoding(Encoding::UTF_16LE)
+      text.encode(Encoding::UTF_8) if text.valid_encoding?
+    end
+
+    def forbidden?(point) = point.zero? || point.between?(0xfdd0, 0xfdef) || point & 0xfffe == 0xfffe
+
+    def number
+      token = @scanner.scan(NUMBER) or refuse("unexpected token")
+      refuse("a number token longer than #{MAX_NUMBER_TOKEN} characters") if token.length > MAX_NUMBER_TOKEN
+      digits = "#{@scanner[1]}#{@scanner[2]}".sub(/\A0+/, "")
+      return 0 if digits.empty?
+
+      # Float rounds correctly but warns when a token overflows or underflows, so the decimal
+      # exponent settles both first. The value lies in [10^(magnitude-1), 10^magnitude).
+      scale = @scanner[3].to_i - @scanner[2].to_s.length
+      magnitude = digits.length + scale
+      refuse("a number outside the I-JSON range") if magnitude > 17
+      if magnitude < -323 || (magnitude == -323 && Rational(digits.to_i, 10**-scale) <= TINY)
+        refuse("a number that underflows to zero")
+      end
+      number = Float(token)
+      refuse("a number outside the I-JSON range") if number.abs > EXACT
+      number.to_i == number ? number.to_i : number
+    end
+  end
+  private_constant :Reader
+end

data/lib/mailschema/message.rb

@@ -1,17 +1,132 @@
 # frozen_string_literal: true
 
-# The Structured Email binding: how a message carries a description.
 module Mailschema
-  # The Content-Type of the part that carries a description: JSON-LD labelled with the
-  # profile through the media type's profile parameter.
-  DESCRIPTION_MEDIA_TYPE = %(application/ld+json; profile="#{PROFILE}").freeze
-
-  # Whether a designated part carries a description of this profile: its media type is
-  # application/ld+json, compared case-insensitively, and its profile parameter lists
-  # the profile among its space-separated URIs. A client processes the one such part
-  # outside any attached message and ignores every other structured part.
-  def self.description_part?(media_type, profile_parameter)
-    media_type.to_s.casecmp?("application/ld+json") &&
-      profile_parameter.to_s.split(/[ \t]+/).include?(PROFILE)
+  # The MAP part of an email (Core, "Email representation"): the one designated description of
+  # this profile, in a multipart/related entity whose root is the readable content it
+  # describes. A description inside an attachment or an attached message is never read.
+  module Message
+    # What a message carries: status :none; :invalid, with the reason the part cannot be used;
+    # or :valid, with the description.
+    Result = Data.define(:status, :reason, :description)
+
+    NONE = Result.new(status: :none, reason: nil, description: nil)
+    READABLE = %w[text/plain text/html].freeze
+    TRANSFER_ENCODINGS = %w[base64 quoted-printable].freeze
+    SINGLE_FIELDS = %w[content-type content-purpose content-transfer-encoding].freeze
+
+    class << self
+      # The MAP description of a received Mail::Message, read from its original bytes (for
+      # example with Mail.new(raw)). It never raises for untrusted input. Reasons:
+      # :multiple_parts, :ambiguous_headers, :transfer_encoding, :media_type,
+      # :not_partial_representation, :invalid_description and :unreadable.
+      def extract(mail)
+        designated = entities(mail).select { |part, _parent| designated?(part) }
+        return NONE if designated.empty?
+        return invalid(:multiple_parts) if designated.size > 1
+
+        part, parent = designated.first
+        reason = problem(part, parent)
+        return invalid(reason) if reason
+
+        Result.new(status: :valid, reason: nil, description: Mailschema.parse_description(part.body.decoded.b))
+      rescue InvalidDocument
+        invalid(:invalid_description)
+      rescue StandardError
+        invalid(:unreadable)
+      end
+
+      # The MIME part that carries a description: compact JSON in quoted-printable, since one
+      # line of JSON is usually longer than SMTP's 998 octets and 8bit cannot carry it. It
+      # raises InvalidDocument unless that JSON is a valid description.
+      def part(description)
+        json = JSON.generate(description)
+        Mailschema.parse_description(json)
+        Mail::Part.new.tap do |part|
+          part.content_type = "#{DESCRIPTION_MEDIA_TYPE}; charset=UTF-8"
+          part.content_transfer_encoding = "quoted-printable"
+          part.header["Content-Purpose"] = "Machine-readable"
+          # Mail takes a body assigned under a transfer encoding as already encoded.
+          part.body = Mail::Encodings::QuotedPrintable.encode(json)
+        end
+      end
+
+      private
+
+      def invalid(reason) = Result.new(status: :invalid, reason: reason, description: nil)
+
+      # Every part with its parent, at any depth. An attachment or an attached message is a
+      # leaf, so nothing inside one is read.
+      def entities(entity)
+        entity.parts.flat_map do |part|
+          attached?(part) || part.mime_type == "message/rfc822" ? [] : [[part, entity], *entities(part)]
+        end
+      end
+
+      def attached?(part) = part.content_disposition.to_s.downcase.start_with?("attachment")
+
+      # Every Content-Purpose the part declares, however many times it repeats it.
+      def machine_readable?(part)
+        part.header.fields.any? do |field|
+          field.name.casecmp?("Content-Purpose") && field.value.to_s.casecmp?("Machine-readable")
+        end
+      end
+
+      # A designated part labelled with this profile, judged from its original header lines,
+      # before a parser picks one of repeated fields or parameters.
+      def designated?(part)
+        return false unless machine_readable?(part)
+
+        types = content_types(part)
+        types.any? { |value| value.downcase.include?("application/ld+json") } &&
+          types.any? { |value| value.include?(PROFILE) }
+      end
+
+      def content_types(entity)
+        Array(Header.fields(entity.raw_source.to_s, lax: true)).filter_map do |name, value|
+          value if name == "content-type"
+        end
+      end
+
+      def problem(part, parent)
+        return :ambiguous_headers unless unambiguous?(part)
+        return :transfer_encoding unless TRANSFER_ENCODINGS.include?(part.content_transfer_encoding.to_s.downcase)
+        return :media_type unless description_part?(part)
+
+        :not_partial_representation unless partial_representation?(parent)
+      end
+
+      # Each field that decides how the part is read appears once, with each parameter once.
+      def unambiguous?(part)
+        fields = Header.fields(part.raw_source.to_s, lax: true) or return false
+        counts = fields.map(&:first).tally
+        SINGLE_FIELDS.all? { |name| counts[name] == 1 } && Header.unique_parameters?(fields.assoc("content-type").last)
+      end
+
+      def description_part?(part)
+        part.mime_type == "application/ld+json" && part.content_type_parameters&.[]("profile") == PROFILE
+      end
+
+      # A multipart/related entity with one unambiguous Content-Type, whose root (its start
+      # parameter's part, or else its first) is readable.
+      def partial_representation?(entity)
+        return false unless entity.mime_type == "multipart/related"
+
+        types = content_types(entity)
+        return false unless types.one? && Header.unique_parameters?(types.first)
+
+        start = entity.content_type_parameters&.[]("start")
+        roots = start.to_s.empty? ? entity.parts.first(1) : entity.parts.select { |part| content_id(part) == start }
+        roots.one? && readable?(roots.first)
+      end
+
+      def content_id(part) = part.header["Content-ID"]&.value.to_s.strip
+
+      def readable?(part)
+        return false if attached?(part)
+        return part.parts.any? { |alternative| readable?(alternative) } if part.mime_type == "multipart/alternative"
+
+        READABLE.include?(part.mime_type) && !part.body.decoded.b.strip.empty?
+      end
+    end
   end
 end

data/lib/mailschema/origin.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # The RFC 6454 origin of an absolute URL, serialized as the WHATWG URL parser does: its
+  # scheme, its lowercased host, and its port unless that is the scheme's default.
+  module Origin
+    def self.of(url)
+      uri = URI.parse(url)
+      return if uri.scheme.nil? || uri.host.to_s.empty?
+
+      port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+      "#{uri.scheme.downcase}://#{uri.host.downcase}#{port}"
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+  private_constant :Origin
+end