mailschema 0.2.0 → 0.3.0

data/artifacts/implementation.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mailschema.org/artifacts/map-0.3/schemas/implementation.schema.json",
+  "title": "MAP implementation record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "service",
+    "maintainer",
+    "type",
+    "operations",
+    "binding",
+    "status",
+    "documentation",
+    "evidence"
+  ],
+  "dependentRequired": {
+    "artifact": ["format"],
+    "format": ["artifact"]
+  },
+  "properties": {
+    "service": {
+      "type": "string",
+      "minLength": 1,
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "maintainer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "url"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "format": "uri",
+          "pattern": "^https://"
+        }
+      }
+    },
+    "type": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "version",
+        "contractDigest"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "format": "uri",
+          "pattern": "^https://"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "contractDigest": {
+          "type": "string",
+          "pattern": "^sha-256:[0-9a-f]{64}$"
+        }
+      }
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "binding": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://",
+      "description": "Identifier of the binding specification or documented service binding. It is not a request destination. Clients must explicitly support it."
+    },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "url",
+        "digest",
+        "digestMode"
+      ],
+      "properties": {
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "format": "uri",
+          "pattern": "^https://"
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^sha-256:[0-9a-f]{64}$"
+        },
+        "digestMode": {
+          "enum": [
+            "canonical-json",
+            "bytes"
+          ],
+          "description": "canonical-json hashes the RFC 8785 representation; bytes hashes the exact downloaded artifact. Both use SHA-256."
+        }
+      }
+    },
+    "format": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "enum": [
+        "Draft",
+        "Experimental",
+        "Stable",
+        "Deprecated",
+        "Superseded"
+      ]
+    },
+    "documentation": {
+      "type": "string",
+      "minLength": 1,
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "kind",
+          "url",
+          "summary"
+        ],
+        "properties": {
+          "kind": {
+            "enum": [
+              "declaration",
+              "test-report"
+            ]
+          },
+          "url": {
+            "type": "string",
+            "minLength": 1,
+            "format": "uri",
+            "pattern": "^https://"
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "successor": {
+      "type": "string",
+      "minLength": 1,
+      "format": "uri",
+      "pattern": "^https://"
+    }
+  }
+}

data/artifacts/profile.json

@@ -0,0 +1,27 @@
+{
+  "id": "https://mailschema.org/profiles/map/0.3",
+  "name": "Mail Action Protocol 0.3",
+  "status": "working-draft",
+  "description": "An action description carried in Structured Email. A trusted service binding maps each decision to the service's existing operations, and the service enforces permission and exact terms. Types are defined by digest-bound contracts.",
+  "context": "https://mailschema.org/contexts/map-0.3.jsonld",
+  "schema": "https://mailschema.org/artifacts/map-0.3/schemas/core.schema.json",
+  "contractFormat": "https://mailschema.org/artifacts/map-0.3/schemas/contract.schema.json",
+  "specification": "https://mailschema.org/specification/core",
+  "artifacts": {
+    "context": {
+      "url": "https://mailschema.org/contexts/map-0.3.jsonld",
+      "sha256": "a51490d1fe8af695c14ea508aad88fd0429d18564791b6b52f3ab07d5c51aab3"
+    },
+    "schema": {
+      "url": "https://mailschema.org/artifacts/map-0.3/schemas/core.schema.json",
+      "sha256": "0ad09a6955a47e7a2c1c1eec0747a3e0b15c08a79860e90ce4e65da11983aeb3"
+    },
+    "contractFormat": {
+      "url": "https://mailschema.org/artifacts/map-0.3/schemas/contract.schema.json",
+      "sha256": "86bf057529c4fd2c7f0a880825774afeed31e9f7ba1d99760858a585fe28d18d"
+    },
+    "conformance": {
+      "url": "https://github.com/mailschema/mailschema/blob/main/conformance/map-0.3/README.md"
+    }
+  }
+}

data/lib/mailschema/artifacts.rb

@@ -1,94 +1,51 @@
 # frozen_string_literal: true
 
-# The bundled core artifacts and the validators built from them.
+# MAP 0.3's identifiers, limits and schema validation.
 module Mailschema
-  PROFILE = "https://mailschema.org/profiles/map/0.2"
-  CORE_SCHEMA = "https://mailschema.org/schemas/map-0.2.schema.json"
-  FORMS_SCHEMA = "https://mailschema.org/schemas/forms-0.1.schema.json"
-  CONTRACT_FORMAT = "https://mailschema.org/schemas/type-contract-0.2.schema.json"
-  CONTEXT = "https://mailschema.org/contexts/map-0.2.jsonld"
-  # The Registry contribution schema every MailSchema package binds, carried as bytes.
-  CONTRIBUTION_SCHEMA = "https://mailschema.org/schemas/contribution.schema.json"
+  PROFILE = "https://mailschema.org/profiles/map/0.3"
+  CONTEXT = "https://mailschema.org/contexts/map-0.3.jsonld"
+  # The Content-Type of the MIME part that carries a description.
+  DESCRIPTION_MEDIA_TYPE = %(application/ld+json; profile="#{PROFILE}").freeze
+  DESCRIPTION_MAX_BYTES = 65_536
+  CONTRACT_MAX_BYTES = 262_144
+  # The namespace of the initial effect vocabulary.
+  EFFECTS = "https://mailschema.org/effects/"
+  # The formats MAP schemas may assert. Every implementation checks exactly these.
+  FORMATS = %w[date date-time email uri].freeze
+
+  # JSON Schema 2020-12 as MAP reads it: the listed formats asserted and no other, ECMA-262
+  # regular expressions, so ^ and $ anchor the whole value, and references resolved only
+  # within the schema, never over the network.
+  module Schemas
+    ARTIFACTS = File.expand_path("../../artifacts", __dir__)
+    FORMAT_CHECKS = Formats.checks.freeze
 
-  ROOT = File.expand_path("../..", __dir__)
-  # Canonical artifacts, byte for byte, by the URL MailSchema publishes them at.
-  ARTIFACTS = {
-    CORE_SCHEMA => "schemas/map-0.2.schema.json",
-    FORMS_SCHEMA => "schemas/forms-0.1.schema.json",
-    CONTRACT_FORMAT => "schemas/type-contract-0.2.schema.json",
-    CONTEXT => "contexts/map-0.2.jsonld",
-    CONTRIBUTION_SCHEMA => "schemas/contribution.schema.json"
-  }.freeze
-
-  # The exact bytes of a bundled artifact.
-  def self.artifact(url) = File.binread(File.join(ROOT, ARTIFACTS.fetch(url))).freeze
-
-  # A fresh parsed copy of a bundled artifact.
-  def self.document(url) = JSON.parse(artifact(url))
-
-  # The schemas a contract may depend on without supplying them itself.
-  BUNDLED = [CORE_SCHEMA, FORMS_SCHEMA].to_h { |url| [url, JSON.parse(artifact(url)).freeze] }.freeze
-
-  # JSON Schema 2020-12 as MAP reads it. Lexical forms are the core schema's patterns,
-  # so `format` stays an annotation: format checkers differ between validators. MAP
-  # patterns use a subset ECMA-262 and Ruby read alike, and references resolve only
-  # against schemas already in hand, never over the network.
-  module Validation
     module_function
 
-    def schema(value, references = BUNDLED)
+    def compile(schema)
       JSONSchemer.schema(
-        value,
+        schema,
+        formats: FORMAT_CHECKS,
         regexp_resolver: "ecma",
-        format: false,
-        ref_resolver: proc { |uri| references[uri.to_s.delete_suffix("#")] }
+        ref_resolver: proc { |uri| raise JSONSchemer::UnknownRef, uri.to_s }
       )
     end
 
-    # The first way a schema is not valid JSON Schema 2020-12, or nil.
-    def invalid_schema(value) = JSONSchemer.validate_schema(value).first&.fetch("error")
+    # A schema the gem bundles, by its file name in artifacts/.
+    def bundled(name) = compile(JSON.parse(File.read(File.join(ARTIFACTS, name))))
 
-    # Errors as `pointer message` lines, as the other MailSchema packages report them.
-    # `prefix` places the pointers inside an enclosing document.
+    # Each validation error as its JSON Pointer and message, the pointer placed inside an
+    # enclosing document by `prefix`; an error at the document's root is at /.
     def errors(schema, value, prefix = "")
-      schema.validate(value).first(100).map do |error|
+      schema.validate(value).map do |error|
         pointer = "#{prefix}#{error.fetch("data_pointer")}"
-        "#{pointer.empty? ? "/" : pointer} #{error.fetch("error")}"
+        "#{pointer.empty? ? "/" : pointer}: #{error.fetch("error")}"
       end
     end
-  end
-
-  CORE = Validation.schema(BUNDLED.fetch(CORE_SCHEMA))
-  DEFINITIONS = %w[description request result problem].to_h { |name| [name, CORE.ref("#/$defs/#{name}")] }.freeze
-  DATE_TIME = CORE.ref("#/$defs/dateTime")
-  REQUEST_ID = CORE.ref("#/$defs/uuidUrn")
-  CONTRACTS = Validation.schema(document(CONTRACT_FORMAT))
-
-  private_constant :ROOT, :BUNDLED, :Validation, :CORE, :DEFINITIONS, :DATE_TIME, :REQUEST_ID, :CONTRACTS
 
-  # Whether a value is a request identifier: the core UUID URN form. Only one names a
-  # result resource. Anything else, bytes that are not text included, is not one.
-  def self.request_id?(value)
-    return false if value.is_a?(String) && !value.valid_encoding?
-
-    REQUEST_ID.valid?(value)
+    CORE = bundled("core.schema.json")
+    CONTRACT = bundled("contract.schema.json")
+    IMPLEMENTATION = bundled("implementation.schema.json")
   end
-
-  # Checks any MAP 0.2 description, request, result or problem against the core schema.
-  def self.map_errors(document) = Validation.errors(CORE, document)
-
-  # Checks a description against the core description definition only. A description
-  # of a type the caller has no contract for can be checked this far.
-  def self.description_errors(description) = Validation.errors(DEFINITIONS.fetch("description"), description)
-
-  # Checks a request against the core request definition. A request that fails here
-  # is not claimed: its identifier stays free.
-  def self.request_errors(request) = Validation.errors(DEFINITIONS.fetch("request"), request)
-
-  # Checks a result against the core result definition only.
-  def self.result_errors(result) = Validation.errors(DEFINITIONS.fetch("result"), result)
-
-  # Checks a problem against the core problem definition, including the agreement of
-  # its type, status and code.
-  def self.problem_errors(problem) = Validation.errors(DEFINITIONS.fetch("problem"), problem)
+  private_constant :Schemas
 end

data/lib/mailschema/authentication.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Mailschema
+  # Core "Qualifying message authentication", applied to the facts a DKIM verifier reports. The
+  # gem verifies no signature and makes no DNS query: the caller's verifier does both, and this
+  # module decides whether one verified signature qualifies the message for MAP actions.
+  module Authentication
+    # One signature as the verifier found it: whether it verified, its d= domain, whether it
+    # carries an l= body length, its a= algorithm, its key's type and size, and its h= names.
+    Signature = Data.define(:pass, :domain, :body_length_limited, :algorithm, :key_type, :key_bits,
+                            :signed_headers) do
+      def pass? = pass == true
+      def body_length_limited? = body_length_limited != false
+    end
+
+    # Present exactly once and signed.
+    REQUIRED = %w[from to subject date message-id mime-version content-type].freeze
+    # Present at most once, and signed when present.
+    CONDITIONAL = %w[cc supersedes expires].freeze
+
+    class << self
+      # The first signature that qualifies the message, or nil. `raw_message` is the message as
+      # received, with CRLF line endings. Alignment with the From author domain is strict:
+      # equal domains, ignoring case. Given `organizational_domain`, a callable that returns a
+      # domain's organizational domain (RFC 9989, found through DNS by the caller), alignment
+      # is relaxed: the two organizational domains are equal.
+      def qualifying(raw_message:, signatures:, organizational_domain: nil)
+        fields = Header.fields(raw_message) or return
+        counts = fields.map(&:first).tally
+        covered = REQUIRED + CONDITIONAL.select { |name| counts.key?(name) }
+        return unless covered.all? { |name| counts[name] == 1 }
+
+        author = author_domain(fields.assoc("from").last) or return
+        signatures.find do |signature|
+          qualifies?(signature, covered) && aligned?(signature.domain.to_s, author, organizational_domain)
+        end
+      end
+
+      private
+
+      # It verified the whole body with an acceptable key, and signed every covered header.
+      def qualifies?(signature, covered)
+        signature.pass? && !signature.body_length_limited? && acceptable_key?(signature) &&
+          (covered - signature.signed_headers.map { |name| name.strip.downcase }).empty?
+      end
+
+      # The domain of the From field's one mailbox, or nil unless it names exactly one.
+      def author_domain(value)
+        list = Mail::AddressList.new(value.dup.force_encoding(Encoding::UTF_8))
+        return unless list.addresses.one? && list.group_names.empty?
+
+        domain = list.addresses.first.domain.to_s
+        domain unless domain.empty?
+      rescue Mail::Field::ParseError
+        nil
+      end
+
+      # RFC 8301 and RFC 8463: RSA of at least 1,024 bits with SHA-256, or Ed25519.
+      def acceptable_key?(signature)
+        case signature.algorithm
+        when "rsa-sha256" then signature.key_type == "rsa" && signature.key_bits.to_i >= 1024
+        when "ed25519-sha256" then signature.key_type == "ed25519"
+        else false
+        end
+      end
+
+      def aligned?(signer, author, organizational_domain)
+        return false if signer.empty?
+        return true if signer.casecmp?(author)
+        return false unless organizational_domain
+
+        organization = organizational_domain.call(author).to_s
+        !organization.empty? && organization.casecmp?(organizational_domain.call(signer).to_s)
+      end
+    end
+  end
+end