mailschema 0.2.0

data/lib/mailschema/jcs.rb

@@ -0,0 +1,87 @@
+# 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.
+  module JCS
+    ESCAPES = {
+      '"' => '\\"', "\\" => "\\\\", "\b" => "\\b", "\f" => "\\f",
+      "\n" => "\\n", "\r" => "\\r", "\t" => "\\t"
+    }.freeze
+    # Integers up to this magnitude are exact as IEEE 754 doubles.
+    EXACT = 2**53
+
+    module_function
+
+    def canonicalize(value)
+      case value
+      when Hash then object(value)
+      when Array then "[#{value.map { |item| canonicalize(item) }.join(",")}]"
+      when String then quote(value)
+      when Integer then value.abs <= EXACT ? value.to_s : number(value.to_f)
+      when Float then number(value)
+      when true then "true"
+      when false then "false"
+      when nil then "null"
+      else raise ArgumentError, "#{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)
+
+        [utf8(name).encode(Encoding::UTF_16BE).unpack("n*"), name, member]
+      end
+      pairs = members.sort_by(&:first).map { |_, name, member| "#{quote(name)}:#{canonicalize(member)}" }
+      "{#{pairs.join(",")}}"
+    end
+
+    def quote(value)
+      escaped = utf8(value).gsub(/["\\\x00-\x1f]/) { |char| ESCAPES.fetch(char) { format("\\u%04x", char.ord) } }
+      %("#{escaped}")
+    end
+
+    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?
+
+      string
+    rescue EncodingError
+      raise ArgumentError, "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?
+      return "0" if value.zero?
+      return "-#{number(-value)}" if value.negative?
+
+      digits, point = shortest(value)
+      count = digits.length
+      if point.between?(count, 21)
+        digits + ("0" * (point - count))
+      elsif point.between?(1, 21)
+        "#{digits[0, point]}.#{digits[point..]}"
+      elsif point.between?(-5, 0)
+        "0.#{"0" * -point}#{digits}"
+      else
+        significand = count == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+        "#{significand}e#{point.positive? ? "+" : "-"}#{(point - 1).abs}"
+      end
+    end
+
+    # The significant digits of a positive double, and where its decimal point falls:
+    # the value is 0.digits × 10^point.
+    def shortest(value)
+      mantissa, exponent = value.to_s.split("e")
+      whole, fraction = mantissa.split(".")
+      digits = "#{whole}#{fraction}"
+      leading = digits[/\A0*/].length
+      [digits[leading..].sub(/0+\z/, ""), whole.length + exponent.to_i - leading]
+    end
+
+    private_class_method :object, :quote, :utf8, :number, :shortest
+  end
+  private_constant :JCS
+end

data/lib/mailschema/limits.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # MAP documents within the core limits, with lengths counted in code points as JSON
+  # Schema counts them.
+  module Limits
+    TITLE = 240
+    DETAIL = 4000
+    POINTER = 1000
+    ERROR_DETAIL = 2000
+    ERRORS = 100
+
+    module_function
+
+    # The text, or its first limit - 1 code points and an ellipsis.
+    def cut(text, limit) = text.length > limit ? "#{text[0, limit - 1]}…" : text
+
+    # An input error within the core problem's limits. A pointer too long to report
+    # names its nearest ancestor that fits, with a detail that says so, and a detail
+    # too long is cut.
+    def input_error(detail, pointer)
+      if pointer.length > POINTER
+        pointer = Pointer.within(pointer, POINTER)
+        detail = "A member within this value does not satisfy the contract."
+      end
+      { "detail" => cut(detail, ERROR_DETAIL), "pointer" => pointer }
+    end
+
+    # A problem's title, detail and input errors within the core limits. An empty or
+    # overlong title, an empty detail or an empty error list is the caller's mistake.
+    def problem_members(title, detail, errors)
+      raise ArgumentError, "a problem title is 1 to #{TITLE} characters" unless title.length.between?(1, TITLE)
+      raise ArgumentError, "a problem detail is not empty" if detail.empty?
+
+      [title, cut(detail, DETAIL), errors && bounded_errors(errors)]
+    end
+
+    def bounded_errors(errors)
+      raise ArgumentError, "errors, when given, name at least one input error" if errors.empty?
+      raise ArgumentError, "an input error has a detail" if errors.any? { |error| error.fetch("detail").empty? }
+
+      errors.first(ERRORS).map { |error| input_error(error.fetch("detail"), error.fetch("pointer")) }
+    end
+
+    # The problem with as many of its errors, in order, as fit within the document limit.
+    def within_document(problem)
+      errors = problem["errors"]
+      return problem unless errors
+
+      errors = errors.dup
+      errors.pop while errors.size > 1 && JSON.generate(problem.merge("errors" => errors)).bytesize > MAX_BYTES
+      problem.merge("errors" => errors)
+    end
+  end
+  private_constant :Limits
+end

data/lib/mailschema/message.rb

@@ -0,0 +1,17 @@
+# 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)
+  end
+end

data/lib/mailschema/pointer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # JSON Pointer (RFC 6901).
+  module Pointer
+    # What a pointer names when nothing is there, as distinct from null.
+    MISSING = Object.new.freeze
+    INDEX = /\A(?:0|[1-9][0-9]*)\z/
+
+    module_function
+
+    def escape(name) = name.to_s.gsub("~", "~0").gsub("/", "~1")
+
+    def segments(pointer) = pointer.split("/", -1).drop(1).map { |segment| segment.gsub("~1", "/").gsub("~0", "~") }
+
+    # The pointer, or its nearest ancestor no longer than limit characters.
+    def within(pointer, limit)
+      tokens = pointer.split("/", -1)
+      tokens.pop while tokens.join("/").length > limit
+      tokens.join("/")
+    end
+
+    # The value a pointer names through objects and arrays, or MISSING.
+    def resolve(value, pointer)
+      segments(pointer).reduce(value) do |current, name|
+        case current
+        when Hash then current.fetch(name) { return MISSING }
+        when Array then INDEX.match?(name) && name.to_i < current.size ? current[name.to_i] : (return MISSING)
+        else return MISSING
+        end
+      end
+    end
+
+    # The value a pointer names through object members only, or MISSING. The contract
+    # rules bind form fields only through object properties, so no binding indexes an
+    # array.
+    def member(value, pointer)
+      segments(pointer).reduce(value) do |current, name|
+        return MISSING unless current.is_a?(Hash) && current.key?(name)
+
+        current[name]
+      end
+    end
+  end
+  private_constant :Pointer
+end

data/lib/mailschema/references.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # The references of a contract's schemas. Each must name a schema inside a pinned
+  # dependency when the contract loads, so none can fail when a request arrives.
+  module References
+    # A plain JSON Pointer fragment: nothing percent-encoded, nothing to decode.
+    FRAGMENT = %r{\A(?:/[A-Za-z0-9._~!$&'()*+,;=:@-]*)*\z}
+    SCHEMA = [Hash, TrueClass, FalseClass].freeze
+    # Keywords that resolve by scope rather than by a pinned address.
+    UNPINNED = %w[$dynamicRef $recursiveRef $dynamicAnchor $recursiveAnchor $anchor].freeze
+
+    module_function
+
+    # Raises InvalidContract for the first keyword in the contract's schemas, or the
+    # pinned schemas the gem does not bundle, that resolves by scope. In the contract's
+    # own schemas, it raises for an $id or $schema anywhere but the request schema's
+    # root, which would move references or change the dialect a subschema is read in;
+    # for a type list; for autocomplete, the form fields block's annotation; and for a
+    # reference that is not a string or names no schema in the pinned documents, by URL.
+    def verify(inline, request_schema, pinned, unbundled)
+      [*inline, request_schema, *unbundled].each do |schema|
+        found = UNPINNED.find { |keyword| SchemaWalk.values(schema, keyword).any? }
+        raise InvalidContract, "#{found} is not pinned by any digest" if found
+      end
+      [*inline, request_schema].each do |schema|
+        nodes = SchemaWalk.nodes(schema)
+        verify_keywords(schema.equal?(request_schema) ? nodes.drop(1) : nodes, nodes)
+        refs = SchemaWalk.values(schema, "$ref")
+        raise InvalidContract, "a $ref is not a string" unless refs.all?(String)
+
+        refs.each { |ref| verify_one(ref, pinned) }
+      end
+    end
+
+    # `nested` are the schema objects that may not declare $id or $schema.
+    def verify_keywords(nested, nodes)
+      raise InvalidContract, "a nested $id would move references" if nested.any? { _1.key?("$id") }
+      raise InvalidContract, "a nested $schema would change the dialect" if nested.any? { _1.key?("$schema") }
+      raise InvalidContract, "type names one type, never a list" if nodes.any? { _1["type"].is_a?(Array) }
+      return unless nodes.any? { _1.key?("autocomplete") }
+
+      raise InvalidContract, "autocomplete belongs to the form fields block"
+    end
+
+    def verify_one(ref, pinned)
+      base, fragment = ref.split("#", 2)
+      raise InvalidContract, "#{ref} is not a pinned dependency" unless pinned.key?(base)
+
+      fragment = fragment.to_s
+      unless fragment.empty? || fragment.start_with?("/")
+        raise InvalidContract, "#{ref} names an anchor, not a JSON Pointer"
+      end
+      raise InvalidContract, "#{ref} is not a plain JSON Pointer" unless FRAGMENT.match?(fragment)
+
+      target = Pointer.resolve(pinned[base], fragment)
+      raise InvalidContract, "#{ref} does not name a schema" unless SCHEMA.include?(target.class)
+    end
+    private_class_method :verify_one
+  end
+  private_constant :References
+end

data/lib/mailschema/schema_walk.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # The schema objects within a schema, as JSON Schema 2020-12 nests them.
+  module SchemaWalk
+    # The keywords whose value is a schema, a list of schemas, or a map from names to
+    # schemas. A name in a map is never a keyword, whatever it is called.
+    SUBSCHEMA = %w[additionalProperties propertyNames items contains not if then else unevaluatedItems
+                   unevaluatedProperties contentSchema].freeze
+    LISTS = %w[allOf anyOf oneOf prefixItems].freeze
+    MAPS = %w[properties patternProperties $defs dependentSchemas].freeze
+
+    module_function
+
+    # Every schema object within a schema, the schema itself first.
+    def nodes(schema)
+      return [] unless schema.is_a?(Hash)
+
+      [schema] +
+        SUBSCHEMA.flat_map { |keyword| nodes(schema[keyword]) } +
+        LISTS.flat_map { |keyword| schema[keyword].is_a?(Array) ? schema[keyword].flat_map { nodes(_1) } : [] } +
+        MAPS.flat_map { |keyword| schema[keyword].is_a?(Hash) ? schema[keyword].values.flat_map { nodes(_1) } : [] }
+    end
+
+    # Every value a keyword has in the schema objects within a schema.
+    def values(schema, keyword) = nodes(schema).filter_map { |node| node[keyword] if node.key?(keyword) }
+  end
+  private_constant :SchemaWalk
+end

data/lib/mailschema/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mailschema
+  VERSION = "0.2.0"
+end

data/lib/mailschema.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "digest"
+require "json"
+require "json_schemer"
+require "time"
+
+require_relative "mailschema/version"
+require_relative "mailschema/limits"
+require_relative "mailschema/jcs"
+require_relative "mailschema/document"
+require_relative "mailschema/artifacts"
+require_relative "mailschema/pointer"
+require_relative "mailschema/schema_walk"
+require_relative "mailschema/references"
+require_relative "mailschema/forms"
+require_relative "mailschema/capability"
+require_relative "mailschema/contract"
+require_relative "mailschema/documents"
+require_relative "mailschema/http"
+require_relative "mailschema/message"
+
+# Mail Action Protocol 0.2 tooling. The module parses,
+# canonicalizes, digests and validates MAP documents, checks the type contracts an
+# implementation vendors, and builds results and problems. It does not establish
+# endpoint trust, verify email authentication, grant authority or send email.
+module Mailschema
+  # RFC 8785 canonical JSON of a value.
+  def self.canonicalize(value) = JCS.canonicalize(value)
+
+  # `sha-256:` and the SHA-256 of the RFC 8785 canonical form: the digest MAP uses
+  # for descriptions, contracts and pinned schemas.
+  def self.digest(value) = "sha-256:#{Digest::SHA256.hexdigest(JCS.canonicalize(value))}"
+
+  # Whether a deadline, a core date-time plus `after` seconds, has been reached.
+  # Anything but a core date-time counts as reached, so a mistake fails closed.
+  def self.reached?(now, deadline, after: 0)
+    !(DATE_TIME.valid?(deadline) && now < Time.iso8601(deadline) + after)
+  end
+end