mailschema 0.2.0 → 0.3.0

data/lib/mailschema/contract.rb

@@ -1,331 +1,234 @@
 # frozen_string_literal: true
 
-# Type contracts an implementation vendors, verified by digest and compiled once.
+# A type contract: the digest-bound definition of an interaction's details, operations,
+# effects and permitted bindings.
 module Mailschema
-  # A type contract that fails its own checks or its pinned digest.
-  class InvalidContract < Error; end
-
-  # Reasons the core assigns to the approval lifecycle.
-  APPROVAL_REASONS = %w[declined stale-target expired superseded].freeze
-
-  # A type contract an implementation vendors, verified against the digest it was
-  # pinned by and compiled once. It checks the descriptions, requests, inputs and
-  # results of that exact type. The Registry has already applied the contract rules,
-  # such as portable patterns, to the contract that digest names; loading refuses
-  # anything that would otherwise fail at request time.
-  class Contract
-    # A MAP problem a request earns before the service's own state is consulted.
-    Problem = Data.define(:code, :title, :detail)
-
-    FIELD_VALIDATORS = 128
-    private_constant :FIELD_VALIDATORS
-
-    attr_reader :document, :digest, :request_schema
-
-    # `digest` is the contract digest the implementation pinned; `dependencies`
-    # supplies, by URL, any pinned schema the gem does not bundle.
-    def initialize(contract, request_schema, digest:, dependencies: {})
-      errors = Validation.errors(CONTRACTS, contract)
-      raise InvalidContract, "invalid type contract: #{errors.join("; ")}" if errors.any?
-      raise InvalidContract, "the contract is for another MAP profile" unless contract["profile"] == PROFILE
-
-      @document = frozen_copy(contract)
-      @digest = Mailschema.digest(@document)
-      raise InvalidContract, "the contract digest is #{@digest}, not the pinned #{digest}" unless @digest == digest
-
-      @request_schema = frozen_copy(request_schema)
-      @references = pin(@document.fetch("dependencies", []), dependencies)
-      verify_structure
-      compile
-    end
+  # The capability binding's kinds: the exact effects each declares and its longest lifetime.
+  CAPABILITY_KINDS = {
+    "refusal" => { effects: %w[refusal state].freeze, max_lifetime_seconds: 604_800 }.freeze,
+    "protective-report" => { effects: %w[protection state].freeze, max_lifetime_seconds: 259_200 }.freeze,
+    "address-confirmation" => { effects: %w[assertion state].freeze, max_lifetime_seconds: 86_400 }.freeze
+  }.freeze
+
+  # The schemas a contract supplies, held to what every implementation enforces alike.
+  module ContractSchemas
+    # The JSON Schema 2020-12 keywords a contract's schemas may use. Every implementation
+    # enforces all of them alike; scope-resolved references and content annotations are absent.
+    KEYWORDS = Set.new(
+      %w[
+        $schema $ref $defs $comment
+        allOf anyOf oneOf not if then else dependentSchemas
+        prefixItems items contains properties patternProperties
+        additionalProperties propertyNames unevaluatedItems unevaluatedProperties
+        type enum const multipleOf maximum exclusiveMaximum minimum
+        exclusiveMinimum maxLength minLength pattern maxItems minItems
+        uniqueItems maxContains minContains maxProperties minProperties required
+        dependentRequired format
+        title description default deprecated readOnly writeOnly examples
+      ]
+    ).freeze
+    DIALECT = "https://json-schema.org/draft/2020-12/schema"
+
+    class << self
+      # Why a schema a contract supplies cannot be enforced alike everywhere, if it cannot.
+      def problems(schema, pointer)
+        within = Subschemas.all(schema, pointer)
+        schemas = within.to_set { |at, _node| at.delete_prefix(pointer) }
+        found = within.flat_map do |at, node|
+          node.is_a?(Hash) ? node_problems(at, node, at == pointer, schemas) : []
+        end
+        return found if found.any?
+        return ["#{pointer}: $ref leads back without moving into the value"] if Subschemas.endless?(schema)
 
-    def id = document.fetch("id")
-    def version = document.fetch("version")
+        [compile_problem(schema, within, pointer)].compact
+      end
 
-    # The type reference a description and a request of this contract name exactly.
-    def type_reference = { "id" => id, "version" => version, "contractDigest" => digest }
+      private
 
-    def operation(id) = document.fetch("operations").find { |operation| operation.fetch("id") == id }
+      def node_problems(at, node, root, schemas)
+        problems = node.keys.reject { |keyword| KEYWORDS.include?(keyword) }
+                       .map { |keyword| "#{keyword} is not a MAP schema keyword" }
+        problems << "$schema names JSON Schema 2020-12, at the schema's root only" if stray_schema?(node, root)
+        problems << "$ref is a JSON Pointer to a schema within this schema" if unresolved?(node, schemas)
+        problems << "format is one of #{FORMATS.join(", ")}" if node.key?("format") && !FORMATS.include?(node["format"])
+        problems << "multipleOf is an integer" if node["multipleOf"].is_a?(Float) && node["multipleOf"] % 1 != 0
+        (problems + pattern_problems(node)).map { |problem| "#{at}: #{problem}" }
+      end
 
-    # Whether completing the operation decides the interaction.
-    def decision?(id)
-      found = operation(id) or raise ArgumentError, "#{id} is not an operation of this type"
-      !found.fetch("repeatable", false)
-    end
+      def stray_schema?(node, root) = node.key?("$schema") && !(root && node["$schema"] == DIALECT)
 
-    # Every rule a description must satisfy beyond the core schema, for the service
-    # that issues it and the client that receives it.
-    def description_errors(description)
-      errors = Mailschema.description_errors(description)
-      return errors if errors.any?
-      return ["The description names another type contract."] unless description.fetch("type") == type_reference
+      # A $ref other than # and the exact RFC 6901 pointer Subschemas gives a schema (the root or a
+      # subschema, object or boolean) in the same root. Any other value or spelling is refused,
+      # and every $ref is checked, in a definition nothing uses too.
+      def unresolved?(node, schemas)
+        return false unless node.key?("$ref")
 
-      problems = details_problems(description)
-      problems.concat(operation_problems(description))
-      unless Time.iso8601(description.fetch("describedAt")) < Time.iso8601(description.fetch("expiresAt"))
-        problems << "The interaction expires before it was described."
+        ref = node["$ref"]
+        !(ref.is_a?(String) && ref.start_with?("#") && schemas.include?(ref[1..]))
       end
-      problems.concat(Capability.problems(description)) if description.dig("service", "authority") == "possession"
-      problems
-    end
 
-    # The checks a service makes on a request once it has resolved the description it
-    # issued, compared the description digest and established the caller: the exact
-    # type, an offered operation the authority permits, and expiry. Nil when they
-    # pass. The service then applies its own state (a decided interaction, a stale
-    # target) and `input_errors`, in that order, before any effect.
-    def request_problem(description, request, now:)
-      unless request["type"] == type_reference && description["type"] == type_reference
-        return Problem.new("unsupported-type", "Unsupported interaction type",
-                           "The service does not implement this exact interaction type contract.")
-      end
-      unless offered?(description, request["operation"])
-        return Problem.new("unsupported-operation", "Unsupported operation",
-                           "The operation was not offered in this interaction.")
+      def pattern_problems(node)
+        patterns = [
+          *(node["pattern"] if node["pattern"].is_a?(String)),
+          *(node["patternProperties"].keys if node["patternProperties"].is_a?(Hash))
+        ]
+        patterns.filter_map do |pattern|
+          problem = Patterns.unportable(pattern)
+          "pattern #{JCS.quote(pattern)} uses #{problem}" if problem
+        end
       end
-      return unless Mailschema.reached?(now, description.fetch("expiresAt"))
-
-      Problem.new("expired-interaction", "Interaction expired",
-                  "The interaction expired before the request was processed.")
-    end
-
-    # Input problems for one request, each with a detail and a JSON Pointer into its
-    # input: the operation's input schema, then its field bindings against the
-    # description's details. Type rules a contract cannot express are the caller's.
-    def input_errors(description, request)
-      found = operation(request["operation"])
-      schema = @inputs[request["operation"]]
-      return [problem("The operation is not part of this type.", "")] unless found && schema
-
-      errors = pointer_errors(schema, request["input"])
-      return errors.first(100) if errors.any?
-
-      found.fetch("fieldBindings", [])
-           .flat_map { |binding| binding_errors(binding, description["details"], request["input"]) }
-           .first(100)
-    end
-
-    # The core result definition, then the output schema and reason this contract
-    # declares for the result's operation and state.
-    def result_errors(result)
-      errors = Mailschema.result_errors(result)
-      return errors if errors.any?
-      return ["The result names another type contract."] unless result.fetch("type") == type_reference
 
-      found = operation(result.fetch("operation"))
-      return ["#{result["operation"]} is not an operation of this type."] unless found
+      # Why the schema would not compile, or nil: it is not valid JSON Schema 2020-12, or a
+      # reference cannot be resolved now, so validation never fails on one later.
+      def compile_problem(schema, nodes, pointer)
+        invalid = JSONSchemer.validate_schema(schema).first
+        return "#{pointer}: #{invalid.fetch("error")}" if invalid
 
-      declared = found.fetch("results").find { |entry| entry.fetch("state") == result.fetch("state") }
-      return ["#{found["id"]} does not declare the state #{result["state"]}."] unless declared
-
-      problems = Validation.errors(@outputs.fetch([found["id"], declared["state"]]), result.fetch("output"), "/output")
-      if result["state"] == "failed" && !declared.fetch("reasons", []).include?(result["reason"])
-        problems << "#{found["id"]} does not declare the reason #{result["reason"]}."
+        compiled = Schemas.compile(schema)
+        nodes.filter_map { |_at, node| node["$ref"] if node.is_a?(Hash) }.each { |ref| compiled.ref(ref) }
+        nil
+      rescue StandardError => e
+        "#{pointer}: #{e.message}"
       end
-      problems
     end
+  end
+  private_constant :ContractSchemas
+
+  # Why the value is not a MAP 0.3 type contract, or no reasons.
+  def self.contract_errors(value)
+    errors = Schemas.errors(Schemas::CONTRACT, value)
+    return errors if errors.any?
+
+    # The canonical form has JSON.stringify's bytes in another order.
+    errors << "/: exceeds #{CONTRACT_MAX_BYTES} bytes" if canonicalize(value).bytesize > CONTRACT_MAX_BYTES
+    ids = value["operations"].map { |operation| operation["id"] }
+    errors << "/operations: identifiers must be unique" if ids.uniq.size != ids.size
+    errors.concat(ContractSchemas.problems(value["detailsSchema"], "/detailsSchema"))
+    value["operations"].each_with_index do |operation, index|
+      at = "/operations/#{index}"
+      errors.concat(ContractSchemas.problems(operation["inputSchema"], "#{at}/inputSchema")) if operation["inputSchema"]
+      errors.concat(capability_errors(operation, at)) if operation["capability"]
+    end
+    errors
+  end
 
-    private
-
-    def frozen_copy(value) = deep_freeze(JSON.parse(JSON.generate(value)))
-
-    def deep_freeze(value)
-      case value
-      when Hash then value.each_value { |member| deep_freeze(member) }
-      when Array then value.each { |item| deep_freeze(item) }
-      end
-      value.freeze
+  def self.capability_errors(operation, at)
+    name = operation.dig("capability", "kind")
+    kind = CAPABILITY_KINDS.fetch(name)
+    expected = kind[:effects].map { |effect| "#{EFFECTS}#{effect}" }.sort
+    errors = []
+    if operation["effects"].sort != expected
+      errors << "#{at}/effects: a #{name} capability declares exactly #{expected.join(" and ")}"
     end
+    if operation.dig("capability", "maxLifetimeSeconds") > kind[:max_lifetime_seconds]
+      errors << "#{at}/capability/maxLifetimeSeconds: at most #{kind[:max_lifetime_seconds]}"
+    end
+    errors
+  end
+  private_class_method :capability_errors
 
-    def pin(dependencies, supplied)
-      references = dependencies.to_h do |dependency|
-        url = dependency.fetch("url")
-        schema = BUNDLED[url] || supplied[url]
-        raise InvalidContract, "unknown dependency #{url}" unless schema
-        unless Mailschema.digest(schema) == dependency.fetch("canonicalDigest")
-          raise InvalidContract, "the pinned digest of #{url} differs"
-        end
-
-        [url, schema.frozen? ? schema : frozen_copy(schema)]
-      end
-      raise InvalidContract, "the core schema must be pinned" unless references.key?(CORE_SCHEMA)
+  # A valid contract with its digest and compiled schemas.
+  class Contract
+    # The contract's frozen document.
+    attr_reader :document
+    # `sha-256:` and the SHA-256 of the contract's RFC 8785 form.
+    attr_reader :digest
 
-      references.freeze
-    end
+    # The contract in the bytes or text, read as MAP JSON within the contract limit.
+    def self.parse(input) = new(Mailschema.parse(input, CONTRACT_MAX_BYTES))
 
-    def verify_structure
-      verify_schemas
-      verify_request_schema
-      verify_operations
-      References.verify(inline_schemas, request_schema, @references, unbundled)
-    end
+    # The contract, or InvalidDocument with every reason the value is not one.
+    def initialize(value)
+      errors = Mailschema.contract_errors(value)
+      raise InvalidDocument.new("The value is not a MAP 0.3 type contract.", errors) if errors.any?
 
-    # The schemas the contract carries itself: its details and every output.
-    def inline_schemas
-      outputs = document.fetch("operations").flat_map do |operation|
-        operation.fetch("results").map { |result| result["outputSchema"] }
-      end
-      [document["detailsSchema"], *outputs].compact
+      @document = frozen(value)
+      @digest = Mailschema.digest(@document)
+      @details = Schemas.compile(@document["detailsSchema"])
+      @inputs = @document["operations"].filter_map do |operation|
+        [operation["id"], Schemas.compile(operation["inputSchema"])] if operation["inputSchema"]
+      end.to_h
     end
 
-    # Every schema is valid JSON Schema 2020-12, so no malformed keyword fails when a
-    # request arrives.
-    def verify_schemas
-      [*inline_schemas, request_schema, *unbundled].each do |schema|
-        problem = Validation.invalid_schema(schema)
-        raise InvalidContract, "a schema is not valid JSON Schema 2020-12: #{problem}" if problem
-      end
-    end
+    def id = document["id"]
 
-    def verify_request_schema
-      reference = document.fetch("requestSchema")
-      unless request_schema["$schema"] == "https://json-schema.org/draft/2020-12/schema"
-        raise InvalidContract, "the request schema must declare JSON Schema 2020-12"
-      end
-      unless request_schema["$id"] == reference["url"]
-        raise InvalidContract, "the request schema $id differs from the contract"
-      end
-      unless Mailschema.digest(request_schema) == reference["canonicalDigest"]
-        raise InvalidContract, "the request schema digest differs from the contract"
-      end
+    def version = document["version"]
 
-      constants = SchemaWalk.values(request_schema, "const").grep(String)
-      [id, version, *operation_ids].each do |expected|
-        raise InvalidContract, "the request schema does not bind #{expected}" unless constants.include?(expected)
-      end
-    end
+    def operation(id) = document["operations"].find { |operation| operation["id"] == id }
 
-    def verify_operations
-      raise InvalidContract, "duplicate operation identifiers" unless operation_ids.uniq == operation_ids
+    # Why the details do not satisfy the contract's details schema, or no reasons.
+    def details_errors(details) = Schemas.errors(@details, details, "/details")
 
-      document.fetch("operations").each do |operation|
-        states = operation.fetch("results").map { |result| result.fetch("state") }
-        raise InvalidContract, "duplicate #{operation["id"]} result states" unless states.uniq == states
-      end
-    end
+    # Why the input is not acceptable for the operation, or no reasons. An operation whose
+    # inputSchema is null accepts no input: pass nil.
+    def input_errors(operation_id, input = nil)
+      return ["/operation: #{operation_id} is not an operation of this contract"] unless operation(operation_id)
 
-    def operation_ids = document.fetch("operations").map { |operation| operation.fetch("id") }
-
-    # Every validator now, so a pattern that does not compile refuses the contract
-    # rather than a request.
-    def compile
-      references = @references.merge(request_schema.fetch("$id") => request_schema)
-      @schema = ->(value) { Validation.schema(value, references) }
-      compile_deferred
-      @details = @schema.call(document["detailsSchema"]) if document.key?("detailsSchema")
-      @inputs = branches.to_h { |operation, input| [operation, @schema.call(input)] }
-      @outputs = document.fetch("operations").flat_map do |operation|
-        operation.fetch("results").map do |result|
-          [[operation["id"], result["state"]], @schema.call(result.fetch("outputSchema"))]
-        end
-      end.to_h
-      resolve_references
-      @fields = {}
-    rescue RegexpError, JSONSchemer::InvalidEcmaRegexp => e
-      raise InvalidContract, "a pattern does not compile: #{e.message}"
-    rescue JSONSchemer::InvalidRefPointer, JSONSchemer::InvalidRefResolution, JSONSchemer::UnknownRef => e
-      raise InvalidContract, "a reference does not resolve: #{e.message}"
-    end
+      schema = @inputs[operation_id]
+      return input.nil? ? [] : ["/input: this operation accepts no input"] unless schema
 
-    # The pinned schemas the gem does not bundle.
-    def unbundled = @references.reject { |url, _| BUNDLED.key?(url) }.values
-
-    # What the validator would otherwise compile at first use: pinned schemas the gem
-    # does not bundle, and the names of patternProperties.
-    def compile_deferred
-      unbundled.each { |schema| @schema.call(schema) }
-      [document, request_schema, *unbundled]
-        .flat_map { |schema| SchemaWalk.values(schema, "patternProperties").grep(Hash).flat_map(&:keys) }
-        .each { |pattern| @schema.call({ "pattern" => pattern }) }
+      Schemas.errors(schema, input, "/input")
     end
 
-    # Every reference resolved now, into every schema it reaches, as a request would
-    # otherwise resolve it first.
-    def resolve_references = [@details, *@inputs.values, *@outputs.values].compact.each(&:bundle)
+    # Why a description does not use this contract as it allows, or no reasons: it is a
+    # description; it names this contract by identifier, version and digest; it offers only
+    # declared operations; a capability appears only where the contract permits one, at the
+    # service's origin and within the kind's lifetime; and its details satisfy the details
+    # schema.
+    def description_errors(description)
+      errors = Mailschema.description_errors(description)
+      return errors if errors.any?
 
-    # Each operation's branch of the request schema, with its input schema.
-    def branches
-      last = request_schema.fetch("allOf", []).last || {}
-      (last["oneOf"] || [last]).to_h do |branch|
-        properties = branch["properties"] || {}
-        [properties.dig("operation", "const"), properties.fetch("input", {})]
+      errors.concat(type_errors(description))
+      lifetime = Time.iso8601(description["expiresAt"]) - Time.iso8601(description["issuedAt"])
+      origin = authority(description.dig("service", "id"))
+      description["operations"].each_with_index do |offered, index|
+        errors.concat(offer_errors(offered, "/operations/#{index}", lifetime, origin))
       end
+      errors.concat(details_errors(description["details"]))
     end
 
-    def offered?(description, id)
-      authority = description.dig("service", "authority")
-      description.fetch("operations").any? { |offered| offered["id"] == id } &&
-        operation(id)&.fetch("authority")&.include?(authority)
-    end
+    private
 
-    def operation_problems(description)
-      ids = description.fetch("operations").map { |offered| offered.fetch("id") }
-      authority = description.dig("service", "authority")
-      problems = ids.uniq.size == ids.size ? [] : ["An operation is offered twice."]
-      ids.each do |offered|
-        unless operation(offered)&.fetch("authority")&.include?(authority)
-          problems << "#{offered} is not a #{authority} operation of this type."
-        end
+    def type_errors(description)
+      type = description["type"]
+      errors = []
+      if type["id"] != id || type["version"] != version
+        errors << "/type: names #{type["id"]} #{type["version"]}, not this contract"
       end
-      problems
+      errors << "/type/contractDigest: does not match" if type["contractDigest"] != digest
+      errors << "/profile: differs from the contract profile" if description["profile"] != document["profile"]
+      errors
     end
 
-    def details_problems(description)
-      details = description.key?("details") ? description["details"] : Pointer::MISSING
-      missing = details.equal?(Pointer::MISSING)
-      valid = @details ? !missing && @details.valid?(details) : missing
-      return ["The details do not satisfy the type contract."] unless valid
+    def offer_errors(offered, at, lifetime, origin)
+      declared = operation(offered["id"])
+      return ["#{at}/id: #{offered["id"]} is not an operation of this contract"] unless declared
+      return [] unless offered["capability"]
 
-      blocks = document.fetch("operations").flat_map do |operation|
-        operation.fetch("fieldBindings", []).map { |binding| binding["fields"] }
+      errors = []
+      if !declared["capability"]
+        errors << "#{at}/capability: the contract permits no capability for #{offered["id"]}"
+      elsif lifetime > declared.dig("capability", "maxLifetimeSeconds")
+        errors << "/expiresAt: a #{offered["id"]} capability lasts at most " \
+                  "#{declared.dig("capability", "maxLifetimeSeconds")} seconds"
       end
-      blocks.uniq.flat_map do |pointer|
-        fields = Pointer.member(details, pointer)
-        fields.equal?(Pointer::MISSING) ? [] : Forms.problems(fields).map { |found| "#{pointer}: #{found}" }
+      if authority(offered.dig("capability", "url")) != origin
+        errors << "#{at}/capability/url: must have the service's origin"
       end
+      errors
     end
 
-    # A form-shaped input holds only the fields the details define, and satisfies them.
-    def binding_errors(binding, details, input)
-      fields = Pointer.member(details, binding.fetch("fields"))
-      values = Pointer.member(input, binding.fetch("input"))
-      if fields.equal?(Pointer::MISSING)
-        return [] if values.equal?(Pointer::MISSING)
-
-        [problem("This interaction defines no fields for these values.", binding["input"])]
-      elsif values.equal?(Pointer::MISSING)
-        return [] if fields.fetch("required", []).empty?
+    # An HTTPS URL's host and port as an origin compares them: lowercase, without :443.
+    def authority(url) = url[%r{\Ahttps://([^/?#]*)}i, 1]&.downcase&.delete_suffix(":443")
 
-        [problem("Values for the required fields are missing.", binding["input"])]
-      else
-        pointer_errors(fields_schema(fields), values, binding["input"])
+    # A frozen copy of a JSON value, so the document keeps its digest.
+    def frozen(value)
+      case value
+      when Hash then value.to_h { |name, member| [name, frozen(member)] }.freeze
+      when Array then value.map { |item| frozen(item) }.freeze
+      else value.dup.freeze
       end
     end
-
-    # The compiled schema of a fields block's values. Least recently used blocks leave
-    # first, so a long-running service stays bounded.
-    def fields_schema(fields)
-      key = Mailschema.digest(fields)
-      schema = @fields.delete(key) || @schema.call(Forms.values_schema(fields))
-      @fields[key] = schema
-      @fields.shift while @fields.size > FIELD_VALIDATORS
-      schema
-    end
-
-    # Validation errors as a detail and a JSON Pointer, naming a missing member itself.
-    def pointer_errors(schema, value, prefix = "")
-      schema.validate(value).flat_map do |error|
-        at = error.fetch("data_pointer")
-        if error["type"] == "required"
-          error.dig("details", "missing_keys").map do |name|
-            problem(error["error"], "#{prefix}#{at}/#{Pointer.escape(name)}")
-          end
-        else
-          [problem(error["error"], "#{prefix}#{at}")]
-        end
-      end.uniq
-    end
-
-    def problem(detail, pointer) = Limits.input_error(detail, pointer)
   end
 end

data/lib/mailschema/description.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# A MAP description: the JSON-LD a message carries beside its readable content.
+module Mailschema
+  # Whitespace, controls, bidirectional and invisible formatting characters.
+  UNSAFE = /\p{White_Space}|\p{Cc}|\p{Cf}/
+  private_constant :UNSAFE
+
+  # Why the value is not a MAP 0.3 description, or no reasons. Beyond the core schema: expiry
+  # follows issuance, operation identifiers are unique, and no security-sensitive identifier
+  # contains whitespace, a control or a formatting character.
+  def self.description_errors(value)
+    errors = Schemas.errors(Schemas::CORE, value)
+    return errors if errors.any?
+
+    if Time.iso8601(value["expiresAt"]) <= Time.iso8601(value["issuedAt"])
+      errors << "/expiresAt: must be later than issuedAt"
+    end
+    ids = value["operations"].map { |operation| operation["id"] }
+    errors << "/operations: identifiers must be unique" if ids.uniq.size != ids.size
+    identifiers(value).each do |pointer, identifier|
+      next unless identifier && UNSAFE.match?(identifier)
+
+      errors << "#{pointer}: must not contain whitespace, controls or formatting characters"
+    end
+    errors
+  end
+
+  # The description in the bytes or text, or InvalidDocument with every reason it is not one.
+  def self.parse_description(input)
+    value = parse(input, DESCRIPTION_MAX_BYTES)
+    errors = description_errors(value)
+    raise InvalidDocument.new("The value is not a MAP 0.3 description.", errors) if errors.any?
+
+    value
+  end
+
+  # The security-sensitive identifiers of a description, by their JSON Pointers.
+  def self.identifiers(value)
+    capabilities = value["operations"].each_with_index.map do |operation, index|
+      ["/operations/#{index}/capability/url", operation.dig("capability", "url")]
+    end
+    [
+      ["/@id", value["@id"]],
+      ["/type/id", value.dig("type", "id")],
+      ["/service/id", value.dig("service", "id")],
+      ["/service/tenant", value.dig("service", "tenant")],
+      ["/recipient", value["recipient"]],
+      ["/subject/id", value.dig("subject", "id")],
+      ["/terms/id", value.dig("terms", "id")],
+      ["/human/url", value.dig("human", "url")],
+      *capabilities
+    ]
+  end
+  private_class_method :identifiers
+end