mailschema 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd3f1015f63294ef11a1d3a9ff43bcc18af342fd1a55e13e3d04d94b2091302e
+  data.tar.gz: 1f697fbcc3877ad1ea40d70c2ca33f2adf4aa6412ebcef98ea0d26968708cead
+SHA512:
+  metadata.gz: e5a64d0eb6e599247ecd12397b3f370e55ac628d425dfc97f0a3b0450ecc1abf8496601b57ec25eae53d45d65c68ef550459d22972fe3db9065c902bdf0f0742
+  data.tar.gz: 0dd2ea492f2280c0dc443e46b655ad244e363243613599e61eab58b06f6145d03e794d0db9d59871f91c1686a15d42695a4c27394426f6c4357486c498997647

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-26
+
+- First release, for Mail Action Protocol 0.2.
+- Parse MAP documents as I-JSON within the core limits, and canonicalize and digest them with RFC 8785.
+- Verify a vendored type contract against its pinned digest, and check descriptions, requests, inputs and results against it.
+- Build results, state transitions and problems, and apply result retention and approval expiry.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailSchema contributors
+
+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,114 @@
+# mailschema for Ruby
+
+Mail Action Protocol 0.2 tooling for Ruby. The gem parses, canonicalizes, digests and validates MAP documents, verifies 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. Possession mode needs DKIM and DMARC checks on the raw message, which this gem leaves to the client.
+
+```sh
+gem install mailschema
+```
+
+Ruby 3.3 or later.
+
+## A service
+
+Vendor the exact contract and request schema your service implements, and pin the contract by the digest you reviewed. The gem refuses any other contract.
+
+```ruby
+require "mailschema"
+
+CONTRACT = Mailschema::Contract.new(
+  JSON.parse(File.read("config/mailschema/content-review-0.3.json")),
+  JSON.parse(File.read("config/mailschema/content-review-0.3.schema.json")),
+  digest: "sha-256:…"
+)
+```
+
+Before sending a description, check it against every rule of the core and the contract, and store its digest or keep it rebuildable from the interaction:
+
+```ruby
+CONTRACT.description_errors(description) # => []
+Mailschema.digest(description)           # => "sha-256:…"
+```
+
+When a request arrives, check it in this order. No step applies an effect for a problem, and a refusal before the description is resolved and its digest matched leaves the request identifier unclaimed:
+
+```ruby
+# Answer 415 unless Mailschema.json_request?(content_type). Under possession authority,
+# answer an unknown capability with a plain 404 and a lapsed one with a plain 410
+# before reading the body; under credential authority, authenticate the principal.
+request = Mailschema.parse(body)   # raises Mailschema::InvalidDocument
+Mailschema.request_errors(request) # any errors: invalid-request
+
+# Resolve the description you issued for request["interactionId"]. Refuse an unknown
+# interaction, or a request whose descriptionDigest is not Mailschema.digest(description).
+
+# Request identifiers are claimed within your tenant: the account, or the capability.
+# If request["requestId"] is already claimed there, refuse another principal, and a
+# principal whose permission has been revoked, with an uncorrelated refused problem
+# (Mailschema.problem without request_id): the refusal says nothing about the request.
+# Answer any change to the request, compared by Mailschema.digest, with
+# idempotency-conflict. Otherwise settle the recorded result with Mailschema.settle and
+# return it, or expired-interaction once Mailschema.retain_until has passed. Nothing is
+# applied again.
+
+problem = CONTRACT.request_problem(description, request, now: Time.now)
+# problem.code is unsupported-type, unsupported-operation or expired-interaction,
+# with the title and detail Mailschema.problem takes. Then your own state:
+# already-decided, or stale-target.
+
+CONTRACT.input_errors(description, request)
+# => [{ "detail" => "...", "pointer" => "/feedback" }], a claimed invalid-request
+```
+
+Then apply the approval lifecycle or the effect, and record the result:
+
+```ruby
+Mailschema.result(
+  request,
+  state: "accepted",
+  target: description["target"],
+  result_url: Mailschema.result_url(description, request["requestId"]),
+  recorded_at: Time.now,
+  output: { "feedbackRecorded" => true, "feedbackId" => "fb-1" }
+)
+```
+
+## API
+
+| Call                                                                                                 | Does                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Mailschema.parse(json)`                                                                             | Parses a MAP document as I-JSON within the core limits, integral numbers as Integers, or raises `Mailschema::InvalidDocument`                                                                                                                                                                                                                                                                        |
+| `Mailschema.canonicalize(value)`, `Mailschema.digest(value)`                                         | RFC 8785 canonical JSON, and `sha-256:` over it                                                                                                                                                                                                                                                                                                                                                      |
+| `Mailschema.map_errors(document)`                                                                    | Checks a description, request, result or problem against the core schema                                                                                                                                                                                                                                                                                                                             |
+| `Mailschema.description_errors`, `Mailschema.request_errors`                                         | Check a description or a request against its core definition only                                                                                                                                                                                                                                                                                                                                    |
+| `Mailschema.result_errors`, `Mailschema.problem_errors`                                              | Check a result or a problem against its core definition only                                                                                                                                                                                                                                                                                                                                         |
+| `Mailschema::Contract.new(contract, request_schema, digest:, dependencies: {})`                      | Checks the contract's format and profile, refuses any contract but the one pinned by `digest`, checks its pinned dependencies and request schema digest, validates every schema against JSON Schema 2020-12 and compiles every validator once, or raises `Mailschema::InvalidContract`; `dependencies:` supplies, by URL, any pinned schema the gem does not bundle                                  |
+| `contract.description_errors(description)`                                                           | Checks a description against every rule of the core and the contract                                                                                                                                                                                                                                                                                                                                 |
+| `contract.request_problem(description, request, now:)`                                               | The exact type, an offered operation the authority permits, and expiry, as a `Contract::Problem` or nil                                                                                                                                                                                                                                                                                              |
+| `contract.input_errors(description, request)`                                                        | Checks an operation's input and field bindings, with JSON Pointers into `input`                                                                                                                                                                                                                                                                                                                      |
+| `contract.result_errors(result)`                                                                     | Checks a result against the core, the declared output schema and the declared reason                                                                                                                                                                                                                                                                                                                 |
+| `contract.type_reference`, `contract.operation(id)`, `contract.decision?(id)`                        | The type reference descriptions and requests name, one of its operations, and whether completing it decides the interaction                                                                                                                                                                                                                                                                          |
+| `contract.id`, `contract.version`, `contract.digest`, `contract.document`, `contract.request_schema` | The contract's identity, and frozen copies of the documents it verified                                                                                                                                                                                                                                                                                                                              |
+| `Mailschema.result`, `Mailschema.transition`, `Mailschema.problem`                                   | Build results, state transitions and problems with their correlation members, or raise `ArgumentError` rather than return a document the core refuses. A problem stays within the core limits: a title of at most 240 characters, a detail cut at 4000, and as many of the first 100 input errors, each bounded, as fit in 64 KiB as `JSON.generate` writes them, so send documents written that way |
+| `Mailschema.result_url`, `Mailschema.result_status`, `Mailschema.request_id?`                        | The result resource of a request, a result's HTTP status, and whether a value is a request identifier, the only thing a result URL names                                                                                                                                                                                                                                                             |
+| `Mailschema.json_request?(content_type)`                                                             | Whether a `Content-Type` admits a request rather than a 415                                                                                                                                                                                                                                                                                                                                          |
+| `Mailschema::DESCRIPTION_MEDIA_TYPE`, `Mailschema.description_part?(media_type, profile_parameter)`  | The `Content-Type` of the part that carries a description, and whether a designated part is labelled with this profile; a client processes the one such part outside any attached message and ignores every other structured part                                                                                                                                                                    |
+| `Mailschema.retain_until`, `Mailschema.settle`, `Mailschema.reached?`                                | Result retention, the expiry of an undecided approval, and whether a deadline has passed                                                                                                                                                                                                                                                                                                             |
+| `Mailschema.capability(description)`, `Mailschema.written_path(url)`                                 | The possession capability: the last segment of the execution URL's path as written                                                                                                                                                                                                                                                                                                                   |
+| `Mailschema.artifact(url)`, `Mailschema.document(url)`                                               | The bundled core artifacts, as exact bytes or as a fresh parsed copy                                                                                                                                                                                                                                                                                                                                 |
+
+Type rules a contract cannot express, such as a meeting slot being one of the slots offered, belong to each type's implementation.
+
+## Bundled artifacts
+
+The gem carries the MAP 0.2 core schema, its JSON-LD context, the type contract format and the form fields block, and the Registry contribution schema that every MailSchema package binds. Each is byte-identical to the file [mailschema.org](https://mailschema.org) publishes. The gem does not validate contributions; the JavaScript and Python packages do. Type contracts are not bundled: an implementation vendors the contracts it supports, and `Mailschema::Contract` verifies them by digest.
+
+JSON Schema validation uses `json_schemer` with ECMA-262 regular expressions. Lexical forms such as date-times and addresses are core schema patterns, so `format` is never asserted. References resolve only against pinned schemas, never over the network.
+
+## Links
+
+- [Specification](https://mailschema.org/specification/profile)
+- [Source](https://github.com/mailschema/ruby)
+
+MIT License.

data/contexts/map-0.2.jsonld

@@ -0,0 +1,91 @@
+{
+  "@context": {
+    "@version": 1.1,
+    "map": "https://mailschema.org/ns/map#",
+    "schema": "https://schema.org/",
+    "MailAction": "map:MailAction",
+    "profile": {
+      "@id": "map:profile",
+      "@type": "@id"
+    },
+    "type": {
+      "@id": "map:interactionType",
+      "@context": {
+        "id": {
+          "@id": "map:id",
+          "@type": "@id"
+        }
+      }
+    },
+    "version": "schema:version",
+    "contractDigest": "map:contractDigest",
+    "describedAt": {
+      "@id": "schema:dateCreated",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    },
+    "expiresAt": {
+      "@id": "schema:expires",
+      "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+    },
+    "service": {
+      "@id": "schema:provider",
+      "@context": {
+        "id": {
+          "@id": "map:id",
+          "@type": "@id"
+        }
+      }
+    },
+    "name": "schema:name",
+    "authority": "map:authority",
+    "onBehalfOf": {
+      "@id": "map:onBehalfOf",
+      "@context": {
+        "id": {
+          "@id": "map:id",
+          "@type": "@id"
+        }
+      }
+    },
+    "resource": {
+      "@id": "map:resource",
+      "@type": "@id"
+    },
+    "execution": "map:execution",
+    "url": {
+      "@id": "schema:url",
+      "@type": "@id"
+    },
+    "resultUrlTemplate": "map:resultUrlTemplate",
+    "resultRetentionSeconds": "map:resultRetentionSeconds",
+    "humanUrl": {
+      "@id": "map:humanUrl",
+      "@type": "@id"
+    },
+    "target": {
+      "@id": "schema:object",
+      "@context": {
+        "id": {
+          "@id": "map:id",
+          "@type": "@id"
+        }
+      }
+    },
+    "recipient": "schema:recipient",
+    "details": {
+      "@id": "map:details",
+      "@type": "@json"
+    },
+    "revision": "schema:version",
+    "title": "schema:name",
+    "digest": "map:digest",
+    "operations": {
+      "@id": "schema:potentialAction",
+      "@container": "@set",
+      "@context": {
+        "id": "map:operationId"
+      }
+    },
+    "description": "schema:description"
+  }
+}

data/lib/mailschema/artifacts.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# The bundled core artifacts and the validators built from them.
+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"
+
+  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)
+      JSONSchemer.schema(
+        value,
+        regexp_resolver: "ecma",
+        format: false,
+        ref_resolver: proc { |uri| references[uri.to_s.delete_suffix("#")] }
+      )
+    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")
+
+    # Errors as `pointer message` lines, as the other MailSchema packages report them.
+    # `prefix` places the pointers inside an enclosing document.
+    def errors(schema, value, prefix = "")
+      schema.validate(value).first(100).map do |error|
+        pointer = "#{prefix}#{error.fetch("data_pointer")}"
+        "#{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)
+  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)
+end

data/lib/mailschema/capability.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# The possession capability and the rules its URLs meet.
+module Mailschema
+  # The possession capability: the last segment of the execution URL path as written.
+  def self.capability(description)
+    written_path(description.dig("service", "execution", "url")).split("/", -1).last.to_s
+  end
+
+  # The path of an absolute URL exactly as written, with no dot segments removed and
+  # nothing decoded.
+  def self.written_path(url) = url.to_s[%r{\A[A-Za-z][A-Za-z0-9+.-]*://[^/?#]*([^?#]*)}, 1].to_s
+
+  # The rules a possession description's capability URLs must meet when it is issued.
+  module Capability
+    UNGUESSABLE = /\A[A-Za-z0-9_-]{22,}\z/
+    DOT_SEGMENT = /\A(?:\.|%2e){1,2}\z/i
+
+    module_function
+
+    def problems(description)
+      execution = description.dig("service", "execution")
+      capability = Mailschema.capability(description)
+      problems = []
+      problems << "The capability is too short to be unguessable." unless UNGUESSABLE.match?(capability)
+      if [execution.fetch("url"), execution.fetch("resultUrlTemplate")].any? { |url| dot_segment?(url) }
+        problems << "A capability URL must not contain dot segments."
+      end
+      unless execution.fetch("resultUrlTemplate").start_with?("#{execution.fetch("url")}/")
+        problems << "The result template must extend the execution URL and its capability."
+      end
+      if description.dig("service", "humanUrl").include?(capability)
+        problems << "The human route must not carry the capability."
+      end
+      problems
+    end
+
+    def dot_segment?(url) = Mailschema.written_path(url).split("/", -1).any? { |segment| DOT_SEGMENT.match?(segment) }
+  end
+  private_constant :Capability
+end