mailschema 0.2.0 → 0.3.0

data/lib/mailschema/patterns.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # The regular expressions a contract's schemas may use: the subset that ECMA-262 (with the u
+  # flag) and other engines read alike, so every implementation enforces the same contract.
+  class Patterns
+    SYNTAX_CHARACTERS = "^$\\.*+?()[]{}|/"
+    CONTROL_ESCAPES = { "t" => 0x09, "n" => 0x0a, "f" => 0x0c, "r" => 0x0d }.freeze
+    QUANTIFIERS = "*+?{"
+    BOUNDS = /\A\{([0-9]{1,4})(?:(,)([0-9]{1,4})?)?\}/
+    # A class member that is an unescaped hyphen.
+    HYPHEN = :hyphen
+
+    # Why a pattern is outside the portable subset, or nil. The subset is printable ASCII
+    # text, with any other code point written as \uXXXX. It has literal characters and escaped
+    # syntax characters; \t, \n, \f, \r and \d, the ASCII digits; non-empty classes of literal
+    # or escaped members and ranges, with a literal hyphen only first or last; (?: groups;
+    # alternation; ^ and $; and one *, +, ?, {n}, {n,} or {n,m} after an atom. Other class
+    # escapes and the dot match different characters in different engines, and brackets, && or
+    # a stray brace inside a class, or a quantifier on a quantifier, are read differently or
+    # refused by one of them. ^ and $ anchor the whole value, as in ECMA-262; an engine whose
+    # anchors also match at line breaks must read them so.
+    def self.unportable(pattern) = new(pattern).problem
+
+    def initialize(pattern)
+      @pattern = pattern
+      @at = 0
+    end
+
+    def problem
+      return "a character outside printable ASCII" unless /\A[\x20-\x7e]*\z/.match?(@pattern)
+
+      disjunction(0)
+    end
+
+    private
+
+    def disjunction(depth)
+      quantifiable = false
+      while @at < @pattern.length
+        char = @pattern[@at]
+        return depth.zero? ? "an unmatched )" : nil if char == ")"
+
+        problem, quantifiable = QUANTIFIERS.include?(char) ? quantified(char, quantifiable) : term(char, depth)
+        return problem if problem
+      end
+    end
+
+    # The problem with the term at `char`, or nil and whether a quantifier may follow it.
+    def term(char, depth)
+      case char
+      when "|", "^", "$"
+        @at += 1
+        [nil, false]
+      when "(" then [group(depth), true]
+      when "[" then [character_class, true]
+      when "\\"
+        code = escape(false)
+        [(code if code.is_a?(String)), true]
+      when "." then ["an unescaped dot"]
+      when "]", "}" then ["an unescaped #{char}"]
+      else
+        @at += 1
+        [nil, true]
+      end
+    end
+
+    def group(depth)
+      return "a group other than (?:" unless @pattern[@at, 3] == "(?:"
+
+      @at += 3
+      problem = disjunction(depth + 1)
+      return problem if problem
+      return "an unclosed group" unless @pattern[@at] == ")"
+
+      @at += 1
+      nil
+    end
+
+    def quantified(char, quantifiable)
+      return [char == "{" ? "an unescaped {" : "a quantifier with nothing to repeat"] unless quantifiable
+
+      if char == "{"
+        bounds = BOUNDS.match(@pattern[@at..])
+        return ["a malformed {n,m} quantifier"] unless bounds
+        return ["a {n,m} quantifier with m below n"] if bounds[3] && bounds[3].to_i < bounds[1].to_i
+
+        @at += bounds[0].length
+      else
+        @at += 1
+      end
+      following = @pattern[@at]
+      [("a quantifier on a quantifier" if following && QUANTIFIERS.include?(following)), false]
+    end
+
+    # One escaped code point, -1 for the digit class outside a class, or a problem.
+    def escape(in_class)
+      following = @pattern[@at + 1]
+      return "a trailing backslash" if following.nil?
+      return unicode_escape if following == "u"
+
+      @at += 2
+      return -1 if following == "d" && !in_class
+      return CONTROL_ESCAPES[following] if CONTROL_ESCAPES.key?(following)
+      return following.ord if SYNTAX_CHARACTERS.include?(following) || (in_class && following == "-")
+
+      "the escape \\#{following}"
+    end
+
+    def unicode_escape
+      digits = @pattern[@at + 2, 4].to_s
+      return "a malformed \\u escape" unless /\A\h{4}\z/.match?(digits)
+
+      code = digits.hex
+      return "a surrogate \\u escape" if code.between?(0xd800, 0xdfff)
+
+      @at += 6
+      code
+    end
+
+    def character_class
+      @at += @pattern[@at + 1] == "^" ? 2 : 1
+      # Each member's code point, or HYPHEN.
+      members = []
+      until @pattern[@at] == "]"
+        problem = class_member(members)
+        return problem if problem
+      end
+      @at += 1
+      return "an empty character class" if members.empty?
+
+      range_problem(members)
+    end
+
+    def class_member(members)
+      char = @pattern[@at]
+      return "an unclosed character class" if char.nil?
+      return "a bracket inside a class" if char == "["
+      return "&& inside a class" if char == "&" && @pattern[@at + 1] == "&"
+
+      if char == "\\"
+        code = escape(true)
+        return code if code.is_a?(String)
+
+        members << code
+      else
+        members << (char == "-" ? HYPHEN : char.ord)
+        @at += 1
+      end
+      nil
+    end
+
+    def range_problem(members)
+      last = members.size - 1
+      index = 0
+      while index <= last
+        low = members[index]
+        if low == HYPHEN
+          return "an ambiguous hyphen in a class" unless [0, last].include?(index)
+        elsif members[index + 1] == HYPHEN && index + 2 <= last
+          high = members[index + 2]
+          return "an ambiguous hyphen in a class" if high == HYPHEN
+          return "a class range out of order" if high < low
+
+          index += 2
+          return "an ambiguous hyphen in a class" if members[index + 1] == HYPHEN && index + 1 != last
+        end
+        index += 1
+      end
+    end
+  end
+  private_constant :Patterns
+end

data/lib/mailschema/subschemas.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # The schemas within a JSON Schema 2020-12 schema, by the JSON Pointers that name them.
+  module Subschemas
+    SCHEMA = %w[additionalProperties propertyNames items contains not if then else unevaluatedItems
+                unevaluatedProperties].freeze
+    SCHEMA_LISTS = %w[allOf anyOf oneOf prefixItems].freeze
+    SCHEMA_MAPS = %w[properties patternProperties $defs dependentSchemas].freeze
+    # The keywords that apply their subschemas to the value itself, not to a member or item.
+    IN_PLACE = %w[not if then else allOf anyOf oneOf dependentSchemas].freeze
+
+    class << self
+      # Every schema within a schema, object or boolean, with its JSON Pointer, the schema
+      # itself first.
+      def all(schema, pointer)
+        return [[pointer, schema]] if [true, false].include?(schema)
+        return [] unless schema.is_a?(Hash)
+
+        [[pointer, schema], *children(schema, pointer).flat_map { |_keyword, at, item| all(item, at) }]
+      end
+
+      # Whether applying the schema can never finish: from its root, a chain of $ref and
+      # in-place keywords returns to a schema without moving into a member or item.
+      def endless?(schema)
+        links = all(schema, "").to_h { |at, node| [at, node.is_a?(Hash) ? links(at, node) : []] }
+        reachable = [""]
+        seen = Set[""]
+        reachable.each { |at| links.fetch(at, []).map(&:first).each { |to| reachable << to if seen.add?(to) } }
+        state = {}
+        visit = lambda do |at|
+          return state[at] == :open if state.key?(at)
+
+          state[at] = :open
+          looped = links.fetch(at, []).any? { |to, in_place| in_place && visit.call(to) }
+          state[at] = :done
+          looped
+        end
+        reachable.any? { |at| visit.call(at) }
+      end
+
+      private
+
+      # The values a schema object holds where schemas belong, as [keyword, pointer, value].
+      def children(schema, pointer)
+        lists = SCHEMA_LISTS.select { |keyword| schema[keyword].is_a?(Array) }
+        maps = SCHEMA_MAPS.select { |keyword| schema[keyword].is_a?(Hash) }
+        [
+          *SCHEMA.filter_map { |keyword| [keyword, "#{pointer}/#{keyword}", schema[keyword]] if schema.key?(keyword) },
+          *lists.flat_map do |keyword|
+            schema[keyword].each_with_index.map { |item, index| [keyword, "#{pointer}/#{keyword}/#{index}", item] }
+          end,
+          *maps.flat_map do |keyword|
+            schema[keyword].map { |name, item| [keyword, "#{pointer}/#{keyword}/#{escape(name)}", item] }
+          end
+        ]
+      end
+
+      # Where a schema object sends its value: [pointer, whether it is the same value].
+      def links(at, node)
+        applied = children(node, at).reject { |keyword, _at, _item| keyword == "$defs" }
+                                    .map { |keyword, to, _item| [to, IN_PLACE.include?(keyword)] }
+        node.key?("$ref") ? [*applied, [node["$ref"][1..], true]] : applied
+      end
+
+      def escape(name) = name.gsub("~", "~0").gsub("/", "~1")
+    end
+  end
+  private_constant :Subschemas
+end

data/lib/mailschema/version.rb

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

data/lib/mailschema.rb

@@ -1,41 +1,31 @@
 # frozen_string_literal: true
 
-require "bigdecimal"
 require "digest"
 require "json"
 require "json_schemer"
+require "mail"
+require "strscan"
 require "time"
+require "uri"
 
 require_relative "mailschema/version"
-require_relative "mailschema/limits"
 require_relative "mailschema/jcs"
-require_relative "mailschema/document"
+require_relative "mailschema/json"
+require_relative "mailschema/formats"
 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/origin"
+require_relative "mailschema/patterns"
+require_relative "mailschema/subschemas"
+require_relative "mailschema/description"
 require_relative "mailschema/contract"
-require_relative "mailschema/documents"
-require_relative "mailschema/http"
+require_relative "mailschema/implementation"
+require_relative "mailschema/header"
 require_relative "mailschema/message"
+require_relative "mailschema/authentication"
 
-# 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.
+# Mail Action Protocol 0.3 processing: strict MAP JSON, RFC 8785 digests, descriptions, type
+# contracts and implementation records, the MAP part of an email, and the qualifying DKIM
+# signature rules. It does not verify DKIM, resolve DNS, fetch anything named in an email,
+# 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

data/sig/mailschema.rbs

@@ -1,92 +1,100 @@
-# Mail Action Protocol 0.2 tooling.
+# Mail Action Protocol 0.3 processing.
 module Mailschema
   type json = Hash[String, untyped] | Array[untyped] | String | Integer | Float | bool | nil
   type document = Hash[String, untyped]
-  type input_error = Hash[String, String]
+  type capability_kind = { effects: Array[String], max_lifetime_seconds: Integer }
 
   VERSION: String
 
   PROFILE: String
-  CORE_SCHEMA: String
-  FORMS_SCHEMA: String
-  CONTRACT_FORMAT: String
   CONTEXT: String
-  CONTRIBUTION_SCHEMA: String
-  ARTIFACTS: Hash[String, String]
-  APPROVAL_REASONS: Array[String]
-  PROBLEM_STATUS: Hash[String, Integer]
-  PROBLEM_TYPES: String
-  NON_TERMINAL_STATES: Array[String]
-  MAX_BYTES: Integer
+  DESCRIPTION_MEDIA_TYPE: String
+  DESCRIPTION_MAX_BYTES: Integer
+  CONTRACT_MAX_BYTES: Integer
   MAX_DEPTH: Integer
-  EXACT_NUMBER: Integer
-
-  class Error < StandardError
-  end
+  EFFECTS: String
+  FORMATS: Array[String]
+  CAPABILITY_KINDS: Hash[String, capability_kind]
 
-  class InvalidDocument < Error
-  end
+  # A document that is not MAP JSON, or not the document it claims to be.
+  class InvalidDocument < StandardError
+    attr_reader errors: Array[String]
 
-  class InvalidContract < Error
+    def initialize: (String message, ?Array[String] errors) -> void
   end
 
-  def self.parse: (String json) -> json
+  def self.parse: (String input, Integer max_bytes) -> json
   def self.canonicalize: (json value) -> String
   def self.digest: (json value) -> String
-  def self.reached?: (Time now, untyped deadline, ?after: Numeric) -> bool
-
-  def self.artifact: (String url) -> String
-  def self.document: (String url) -> document
-
-  def self.map_errors: (untyped document) -> Array[String]
-  def self.description_errors: (untyped description) -> Array[String]
-  def self.request_errors: (untyped request) -> Array[String]
-  def self.result_errors: (untyped result) -> Array[String]
-  def self.problem_errors: (untyped problem) -> Array[String]
-  def self.request_id?: (untyped value) -> bool
-
-  def self.capability: (document description) -> String
-  def self.written_path: (String? url) -> String
-
-  def self.result: (document request, state: String, target: document, result_url: String, recorded_at: Time,
-                    ?output: document, ?reason: String?, ?approval_url: String?, ?actor: String?) -> document
-  def self.transition: (document result, state: String, recorded_at: Time, ?reason: String?, ?output: document) -> document
-  def self.problem: (String code, title: String, detail: String, ?request_id: String?, ?interaction_id: String?,
-                     ?result_url: String?, ?target: document?, ?errors: Array[input_error]?) -> document
-  def self.result_status: (document result) -> Integer
-  def self.json_request?: (String? content_type) -> bool
-  DESCRIPTION_MEDIA_TYPE: String
-  def self.description_part?: (String? media_type, String? profile_parameter) -> bool
-  def self.result_url: (document description, String request_id) -> String
-  def self.retain_until: (document description, Time recorded_at) -> Time
-  def self.settle: (document result, document description, Time now) -> document?
 
-  # A type contract an implementation vendors, verified by digest and compiled once.
-  class Contract
-    # A MAP problem a request earns before the service's own state is consulted.
-    class Problem < Data
-      attr_reader code: String
-      attr_reader title: String
-      attr_reader detail: String
-
-      def self.new: (String code, String title, String detail) -> instance
-                  | (code: String, title: String, detail: String) -> instance
-    end
+  def self.description_errors: (untyped value) -> Array[String]
+  def self.parse_description: (String input) -> document
 
+  def self.contract_errors: (untyped value) -> Array[String]
+
+  def self.implementation_errors: (untyped value) -> Array[String]
+  def self.parse_implementation: (String input) -> document
+
+  # A valid contract with its digest and compiled schemas.
+  class Contract
     attr_reader document: document
     attr_reader digest: String
-    attr_reader request_schema: document
 
-    def initialize: (document contract, document request_schema, digest: String,
-                     ?dependencies: Hash[String, document]) -> void
+    def self.parse: (String input) -> Contract
+
+    def initialize: (untyped value) -> void
     def id: () -> String
     def version: () -> String
-    def type_reference: () -> Hash[String, String]
-    def operation: (String? id) -> document?
-    def decision?: (String id) -> bool
-    def description_errors: (document description) -> Array[String]
-    def request_problem: (document description, document request, now: Time) -> Problem?
-    def input_errors: (document description, document request) -> Array[input_error]
-    def result_errors: (document result) -> Array[String]
+    def operation: (String id) -> document?
+    def details_errors: (untyped details) -> Array[String]
+    def input_errors: (String operation_id, ?untyped input) -> Array[String]
+    def description_errors: (untyped description) -> Array[String]
+  end
+
+  # The MAP part of an email.
+  module Message
+    class Result < Data
+      attr_reader status: :none | :invalid | :valid
+      attr_reader reason: Symbol?
+      attr_reader description: document?
+
+      def self.new: (Symbol status, Symbol? reason, document? description) -> instance
+                  | (status: Symbol, reason: Symbol?, description: document?) -> instance
+    end
+
+    NONE: Result
+
+    # `mail` is a Mail::Message read from the received bytes.
+    def self.extract: (untyped mail) -> Result
+
+    # Returns a Mail::Part.
+    def self.part: (document description) -> untyped
+  end
+
+  # Core "Qualifying message authentication" over a DKIM verifier's facts.
+  module Authentication
+    class Signature < Data
+      attr_reader pass: bool
+      attr_reader domain: String
+      attr_reader body_length_limited: bool
+      attr_reader algorithm: String
+      attr_reader key_type: String
+      attr_reader key_bits: Integer
+      attr_reader signed_headers: Array[String]
+
+      def self.new: (bool pass, String domain, bool body_length_limited, String algorithm, String key_type,
+                     Integer key_bits, Array[String] signed_headers) -> instance
+                  | (pass: bool, domain: String, body_length_limited: bool, algorithm: String, key_type: String,
+                     key_bits: Integer, signed_headers: Array[String]) -> instance
+
+      def pass?: () -> bool
+      def body_length_limited?: () -> bool
+    end
+
+    REQUIRED: Array[String]
+    CONDITIONAL: Array[String]
+
+    def self.qualifying: (raw_message: String, signatures: Array[Signature],
+                          ?organizational_domain: ^(String) -> String?) -> Signature?
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mailschema
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - MailSchema contributors
@@ -10,61 +10,36 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bigdecimal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '5'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3.1'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '5'
-- !ruby/object:Gem::Dependency
-  name: json
+  name: json_schemer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.21'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4'
+        version: '2.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.21'
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '4'
+        version: '2.5'
 - !ruby/object:Gem::Dependency
-  name: json_schemer
+  name: mail
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
-description: Parse, canonicalize, digest and validate Mail Action Protocol 0.2 documents,
-  verify the type contracts an implementation vendors, and build results and problems.
+        version: '2.8'
+description: Parse, canonicalize, digest and validate Mail Action Protocol 0.3 descriptions,
+  type contracts and implementation records, extract and build the MAP part of an
+  email, and decide whether a verified DKIM signature qualifies a message.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -72,33 +47,33 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- contexts/map-0.2.jsonld
+- artifacts/context.jsonld
+- artifacts/contract.schema.json
+- artifacts/core.schema.json
+- artifacts/implementation.schema.json
+- artifacts/profile.json
 - lib/mailschema.rb
 - lib/mailschema/artifacts.rb
-- lib/mailschema/capability.rb
+- lib/mailschema/authentication.rb
 - lib/mailschema/contract.rb
-- lib/mailschema/document.rb
-- lib/mailschema/documents.rb
-- lib/mailschema/forms.rb
-- lib/mailschema/http.rb
+- lib/mailschema/description.rb
+- lib/mailschema/formats.rb
+- lib/mailschema/header.rb
+- lib/mailschema/implementation.rb
 - lib/mailschema/jcs.rb
-- lib/mailschema/limits.rb
+- lib/mailschema/json.rb
 - lib/mailschema/message.rb
-- lib/mailschema/pointer.rb
-- lib/mailschema/references.rb
-- lib/mailschema/schema_walk.rb
+- lib/mailschema/origin.rb
+- lib/mailschema/patterns.rb
+- lib/mailschema/subschemas.rb
 - lib/mailschema/version.rb
-- schemas/contribution.schema.json
-- schemas/forms-0.1.schema.json
-- schemas/map-0.2.schema.json
-- schemas/type-contract-0.2.schema.json
 - sig/mailschema.rbs
-homepage: https://mailschema.org/tools
+homepage: https://mailschema.org
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://mailschema.org/tools
+  homepage_uri: https://mailschema.org
   source_code_uri: https://github.com/mailschema/ruby
   changelog_uri: https://github.com/mailschema/ruby/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/mailschema/ruby/issues
@@ -119,5 +94,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: Mail Action Protocol 0.2 tooling
+summary: Mail Action Protocol 0.3 processing
 test_files: []