mcp 1.8.1 → 1.9.0

data/lib/mcp/skill/directory.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module MCP
+  class Skill
+    # Directory-backed skills (SEP-2640): `from_directory` turns every directory under a root that holds
+    # a `SKILL.md` into a skill whose files the server's default `resources/read` serves, with the digests and
+    # sizes computed here.
+    #
+    # Rules fixed for the first release: regular files only (symbolic links, FIFOs, sockets, and devices are
+    # skipped, hard links refused), dotfiles skipped, everything else published (editor backups included), every directory and file
+    # name limited to the unreserved URI characters, a directory holding its own `SKILL.md` a skill of its own
+    # whose files the enclosing skill lists as supporting files too, files read at request time and refused
+    # with one generic error when they changed since registration.
+    class << self
+      # Scans `root` and returns the skills found under it (an Array of `MCP::Skill`, ordered by URI); every
+      # problem is an `ArgumentError` naming the path. `root` is resolved once with `File.realpath`, so
+      # a symbolic link to the directory is fine; a `SKILL.md` directly under `root`, or no skill at all, is
+      # refused, because `root` is the container of skill directories, not a skill.
+      #
+      # The tree is trusted as the operator's: it must be writable only by the operator while skills are built
+      # and served. The checks on each file narrow what a concurrent change to the tree can do; they do not
+      # confine a writer who can change it.
+      def from_directory(root)
+        root = root.to_path if root.respond_to?(:to_path)
+        raise ArgumentError, "The skills root must be a path String (got #{root.class})." unless root.is_a?(String)
+
+        real_root = begin
+          File.realpath(root)
+        rescue SystemCallError => e
+          raise ArgumentError, "The skills root #{root} cannot be resolved (#{e.class})."
+        end
+        raise ArgumentError, "The skills root #{real_root} is not a directory." unless File.directory?(real_root)
+        if File.exist?(File.join(real_root, Uri::MANIFEST))
+          raise ArgumentError, "The skills root #{real_root} holds a SKILL.md itself; pass the directory that contains the skill directories."
+        end
+
+        skills = []
+        scan_directory(real_root, [], skills)
+        raise ArgumentError, "No directory holding a SKILL.md was found under #{real_root}." if skills.empty?
+
+        skills.sort_by(&:uri)
+      end
+
+      # Serves one file of a directory-backed skill for a custom `resources_read_handler`, which replaces
+      # the default reader and with it the serving of skill files: returns the `contents` Array holding one item,
+      # or nil when `uri` is not a file of any of `skills`. A file that changed since registration raises
+      # the same `-32603` the default reader answers. The files of a nested skill are files of the enclosing skill
+      # as well, so a caller given the enclosing skill reads them whether or not the nested one is among `skills`.
+      def read_file(skills, uri)
+        record = file_map(skills)[uri]
+        return unless record
+
+        [read_record_item(record)]
+      rescue FileError => e
+        raise file_changed_error(nil, e)
+      end
+
+      # The default reader's path for a file record found in the server's map.
+      #
+      # @api private
+      def read_record(record, request)
+        [read_record_item(record)]
+      rescue FileError => e
+        raise file_changed_error(request, e)
+      end
+
+      private
+
+      # Internal: a file could not be read as registered; the message names the path and is reported only.
+      class FileError < StandardError; end
+
+      # Frozen through, so a custom reader handed `read_file`'s item cannot alter the URI later responses carry.
+      FileRecord = Struct.new(:uri, :path, :size, :digest, :dev, :ino, :text, keyword_init: true) do
+        def initialize(**kwargs)
+          super(**kwargs)
+          each { |member| member.freeze if member.is_a?(String) }
+          freeze
+        end
+      end
+
+      MIME_TYPES = { ".md" => "text/markdown" }.freeze
+
+      def scan_directory(directory, segments, skills)
+        children_of(directory).each do |name|
+          next if name.start_with?(".")
+
+          path = File.join(directory, name)
+          next unless lstat_of(path).directory?
+
+          check_name!(name, path)
+          child_segments = segments + [name]
+          if skill_directory?(path)
+            skills << collect_skill(path, child_segments, skills)
+          else
+            scan_directory(path, child_segments, skills)
+          end
+        end
+      end
+
+      def skill_directory?(path)
+        File.lstat(File.join(path, Uri::MANIFEST)).file?
+      rescue SystemCallError
+        false
+      end
+
+      def check_name!(name, path)
+        return if Uri::LOCAL_SEGMENT.match?(name)
+
+        raise ArgumentError, "The name of #{path} may only use letters, digits, -, ., _, and ~, so that it can be a skill:// URI segment."
+      end
+
+      # Directory listing and `lstat` in a stable order; a filesystem error is reported as an `ArgumentError`
+      # like every other construction problem, since the input is the operator's own tree.
+      def children_of(directory)
+        Dir.children(directory).sort
+      rescue SystemCallError => e
+        raise ArgumentError, "The directory #{directory} cannot be listed (#{e.class})."
+      end
+
+      def lstat_of(path)
+        File.lstat(path)
+      rescue SystemCallError => e
+        raise ArgumentError, "The entry #{path} cannot be examined (#{e.class})."
+      end
+
+      # Builds the skill rooted at `directory`: walks its files, reads the frontmatter from the same bytes
+      # the manifest's digest was computed over, and attaches the file records.
+      def collect_skill(directory, segments, skills)
+        root_uri = Uri.root(segments)
+        manifest_uri = "#{root_uri}/#{Uri::MANIFEST}"
+        walk = { records: {}, manifest_uri: manifest_uri, manifest_bytes: nil, budget: MAX_TOTAL_SIZE }
+        walk_skill_files(directory, segments, walk, skills)
+
+        records = walk[:records].sort_by { |uri, _record| uri }.to_h
+        manifest_bytes = walk[:manifest_bytes]
+        # `skill_directory?` saw the file, so only a change to the tree during the scan leaves it unread.
+        raise ArgumentError, "The SKILL.md of #{directory} disappeared while the directory was being scanned." if manifest_bytes.nil?
+
+        frontmatter = begin
+          Frontmatter.load(manifest_bytes)
+        rescue Frontmatter::Error => e
+          raise ArgumentError, "The frontmatter of #{records.fetch(manifest_uri).path} cannot be read (#{e.reason}); see the frontmatter rules in the Skills documentation."
+        end
+
+        entries = records.values.map { |record| ResourceEntry.new(uri: record.uri, digest: record.digest, size: record.size) }
+        begin
+          with_file_records(uri: manifest_uri, frontmatter: frontmatter, resources: entries, file_records: records.freeze)
+        rescue ArgumentError => e
+          raise ArgumentError, "#{directory}: #{e.message}"
+        end
+      end
+
+      def walk_skill_files(directory, segments, walk, skills)
+        children_of(directory).each do |name|
+          next if name.start_with?(".")
+
+          path = File.join(directory, name)
+          stat = lstat_of(path)
+          next unless stat.directory? || stat.file?
+
+          check_name!(name, path)
+          child_segments = segments + [name]
+          if stat.directory?
+            if skill_directory?(path)
+              # A nested skill is published on its own, and its files are supporting files of the enclosing
+              # skill as well: the records are shared, so both manifests carry the same digests and sizes.
+              nested = collect_skill(path, child_segments, skills)
+              skills << nested
+              adopt_records(nested.__send__(:file_records), walk)
+            else
+              walk_skill_files(path, child_segments, walk, skills)
+            end
+          else
+            uri = Uri.root(child_segments)
+            record, bytes = capture_file(path, uri, walk)
+            walk[:records][uri] = record
+            walk[:manifest_bytes] = bytes if uri == walk[:manifest_uri]
+          end
+        end
+      end
+
+      # Adds a nested skill's records to the enclosing skill's walk; they count against its size budget like
+      # its own files, since the specification counts the limits over every listed entry.
+      def adopt_records(records, walk)
+        records.each_value do |record|
+          if record.size > walk[:budget]
+            raise ArgumentError, "#{record.path} takes the enclosing skill past the #{MAX_TOTAL_SIZE} byte limit of SEP-2640"
+          end
+
+          walk[:budget] -= record.size
+          walk[:records][record.uri] = record
+        end
+      end
+
+      # Hashes one file and returns its record with the bytes it hashed. The skill's remaining size budget is
+      # checked against `fstat` before anything is read, so an oversized file is refused without loading it, and
+      # the read itself stops one byte past the budget, so a file growing after that check is never held whole.
+      def capture_file(path, uri, walk)
+        # The paths come from the resolved root, so `realpath` must return the path unchanged; an intermediate
+        # directory swapped for a symbolic link after `lstat` breaks that. Checked before and after the open,
+        # so passing takes two swaps inside that window instead of one.
+        raise FileError, "#{path} is not the file its path names" unless resolved_path?(path)
+
+        open_regular_file(path) do |io, stat|
+          # A hard link reaches a file outside the tree the way a symbolic link would, so it is refused rather than
+          # skipped, which tells the operator that a file is missing from the manifest. The handle must also be
+          # the file its path names now.
+          raise FileError, "#{path} has more than one hard link" if stat.nlink > 1
+
+          current = File.stat(path)
+          unless resolved_path?(path) && current.dev == stat.dev && current.ino == stat.ino
+            raise FileError, "#{path} is not the file its path names"
+          end
+
+          if stat.size > walk[:budget]
+            raise FileError, "#{path} takes the skill past the #{MAX_TOTAL_SIZE} byte limit of SEP-2640"
+          end
+
+          bytes = io.read(walk[:budget] + 1) || "".b
+          if bytes.bytesize > walk[:budget]
+            raise FileError, "#{path} takes the skill past the #{MAX_TOTAL_SIZE} byte limit of SEP-2640"
+          end
+
+          walk[:budget] -= bytes.bytesize
+          record = FileRecord.new(
+            uri: uri,
+            path: path,
+            size: bytes.bytesize,
+            digest: "sha256:#{Digest::SHA256.hexdigest(bytes)}",
+            dev: stat.dev,
+            ino: stat.ino,
+            text: bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding?,
+          )
+          [record, bytes]
+        end
+      rescue FileError => e
+        raise ArgumentError, e.message
+      end
+
+      def resolved_path?(path)
+        File.realpath(path) == path
+      rescue SystemCallError
+        false
+      end
+
+      # Opens a regular file for reading without following a symbolic link in its last component, and hands
+      # the handle and its `fstat` to the block; everything the block reads comes from the handle it checked.
+      # Where the platform lacks `NOFOLLOW`, an `lstat` before the open refuses a symbolic link instead;
+      # the `fstat` comparison and the digest over the served bytes still close the race.
+      def open_regular_file(path)
+        if !nofollow_supported? && File.lstat(path).symlink?
+          raise FileError, "#{path} is a symbolic link"
+        end
+
+        File.open(path, open_flags) do |io|
+          io.binmode
+          stat = io.stat
+          raise FileError, "#{path} is not a regular file" unless stat.file?
+
+          yield io, stat
+        end
+      rescue SystemCallError, IOError => e
+        raise FileError, "#{path} cannot be read (#{e.class})"
+      end
+
+      def open_flags
+        flags = File::RDONLY | File::NONBLOCK
+        flags |= File::NOFOLLOW if nofollow_supported?
+        flags
+      end
+
+      def nofollow_supported?
+        File::Constants.const_defined?(:NOFOLLOW)
+      end
+
+      # Reads a registered file for serving: the handle must still be the recorded inode with the recorded size
+      # and no additional hard link (`nlink` is compared the way registration does, so a filesystem that reports 0
+      # is served), and the bytes read (at most one more than recorded, so growth shows) must still have
+      # the recorded digest.
+      def read_record_item(record)
+        open_regular_file(record.path) do |io, stat|
+          unless stat.size == record.size && stat.dev == record.dev && stat.ino == record.ino && stat.nlink <= 1
+            raise FileError, "#{record.path} changed since registration (inode, size, or link count)"
+          end
+
+          data = io.read(record.size + 1) || "".b
+          unless data.bytesize == record.size && "sha256:#{Digest::SHA256.hexdigest(data)}" == record.digest
+            raise FileError, "#{record.path} changed since registration (content)"
+          end
+
+          item = { uri: record.uri }
+          mime_type = MIME_TYPES[File.extname(record.path)]
+          item[:mimeType] = mime_type if mime_type
+          if record.text
+            item[:text] = data.force_encoding(Encoding::UTF_8)
+          else
+            item[:blob] = [data].pack("m0")
+          end
+          item
+        end
+      end
+
+      def file_changed_error(request, cause)
+        Server::RequestHandlerError.new(
+          "Skill file changed since registration",
+          request,
+          error_type: :internal_error,
+          error_code: JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+          original_error: cause,
+        )
+      end
+    end
+  end
+end

data/lib/mcp/skill/frontmatter.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "psych"
+
+module MCP
+  class Skill
+    # Reads and compares the YAML frontmatter of a `SKILL.md`, the same way on the server (where
+    # `from_directory` publishes it) and on the client (where a host compares what it fetched with the entry
+    # it holds, a SEP-2640 MUST). The rules are stricter than YAML so that every YAML library reads the block
+    # the same way: one document, no directives or document markers, no tags, no aliases or merge keys, keys
+    # that are untagged Strings, and no plain scalar whose YAML 1.1 reading (Psych's) differs from its
+    # YAML 1.2 core-schema reading (the JavaScript and Go libraries'); such a value is written quoted instead.
+    # Values must be JSON-representable because the entry travels as JSON.
+    module Frontmatter
+      extend self
+
+      # Raised internally with `reason` `:parse` (the block cannot be read under these rules) or `:frontmatter`
+      # (it reads fine but differs from the entry); callers translate it into their own error types.
+      class Error < StandardError
+        attr_reader :reason
+
+        def initialize(reason, message = "frontmatter #{reason}")
+          super(message)
+          @reason = reason
+        end
+      end
+
+      BOM = "\xEF\xBB\xBF".b.freeze
+      DELIMITER = "---"
+      # NEL, LINE SEPARATOR, and PARAGRAPH SEPARATOR: line breaks in YAML 1.1 (Psych) but not in YAML 1.2.
+      UNICODE_BREAKS = Regexp.union([0x85, 0x2028, 0x2029].map { |codepoint| codepoint.chr(Encoding::UTF_8) }).freeze
+      MERGE_KEY = "<<"
+      # An SDK loading limit for the frontmatter block, not a protocol rule: the file itself may be 16 MiB.
+      MAX_BLOCK_BYTES = 64 * 1024
+      MAX_DEPTH = 64
+
+      # Resolves plain scalars by the YAML 1.2 core schema, to compare with Psych's YAML 1.1 resolution.
+      module CoreSchema
+        extend self
+
+        NULL = /\A(?:null|Null|NULL|~)?\z/.freeze
+        TRUE = /\A(?:true|True|TRUE)\z/.freeze
+        FALSE = /\A(?:false|False|FALSE)\z/.freeze
+        INT10 = /\A[-+]?[0-9]+\z/.freeze
+        INT8 = /\A0o[0-7]+\z/.freeze
+        INT16 = /\A0x[0-9a-fA-F]+\z/.freeze
+        FLOAT = /\A[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?\z/.freeze
+        INF = /\A[-+]?\.(?:inf|Inf|INF)\z/.freeze
+        NAN = /\A\.(?:nan|NaN|NAN)\z/.freeze
+
+        def resolve(text)
+          case text
+          when NULL then nil
+          when TRUE then true
+          when FALSE then false
+          when INT10 then Integer(text, 10)
+          when INT8 then text[2..-1].to_i(8)
+          when INT16 then text[2..-1].to_i(16)
+          when INF then text.start_with?("-") ? -Float::INFINITY : Float::INFINITY
+          when NAN then Float::NAN
+          # Ruby's Float() rejects a trailing dot, which the core schema allows.
+          when FLOAT then Float(text.sub(/\.(?=[eE]|\z)/, ".0"))
+          else text
+          end
+        end
+
+        # Whether Psych's reading of a plain scalar differs in type or value from the core-schema reading.
+        # A scanner failure counts as a difference, because the other side would not fail the same way.
+        def divergent?(scanner, text)
+          psych = scanner.tokenize(text)
+          core = resolve(text)
+          return true unless psych.class.equal?(core.class)
+          return false if core.is_a?(Float) && core.nan? && psych.nan?
+
+          psych != core
+        rescue StandardError
+          true
+        end
+      end
+
+      # Builds the AST as `Psych.parse_stream` does and stops the parser at the first collection nested beyond
+      # `MAX_DEPTH`. The scan in libyaml costs the square of the flow nesting, so a block within the size limit
+      # could otherwise take seconds before `check_nodes!` ever saw its depth.
+      class BoundedTreeBuilder < Psych::TreeBuilder
+        def initialize
+          super
+          @depth = 0
+        end
+
+        def start_sequence(*)
+          descend
+          super
+        end
+
+        def start_mapping(*)
+          descend
+          super
+        end
+
+        def end_sequence
+          @depth -= 1
+          super
+        end
+
+        def end_mapping
+          @depth -= 1
+          super
+        end
+
+        private
+
+        def descend
+          @depth += 1
+          raise Error.new(:parse) if @depth > MAX_DEPTH
+        end
+      end
+      private_constant :BoundedTreeBuilder
+
+      # Extracts and parses the frontmatter of a `SKILL.md` given as bytes; returns a Hash with String keys.
+      def load(bytes)
+        parse(extract(bytes))
+      end
+
+      # The text between the opening `---` line and the next `---` line. A leading UTF-8 BOM is skipped
+      # here only; digests always cover the raw bytes. Lines end with `\n` or `\r\n`.
+      def extract(bytes)
+        data = bytes.b
+        data = data.byteslice(BOM.bytesize..-1) if data.start_with?(BOM)
+        text = data.force_encoding(Encoding::UTF_8)
+        raise Error.new(:parse) unless text.valid_encoding?
+
+        lines = text.each_line
+        first = begin
+          lines.next
+        rescue StopIteration
+          raise Error.new(:parse)
+        end
+        raise Error.new(:parse) unless delimiter_line?(first) && first.end_with?("\n") && !foreign_break?(first)
+
+        block = +""
+        closed = false
+        # `loop` ends when `next` raises StopIteration at the end of the text; `each` would restart from
+        # the first line instead of continuing after it.
+        loop do
+          line = lines.next
+          raise Error.new(:parse) if foreign_break?(line)
+
+          if delimiter_line?(line)
+            closed = true
+            break
+          end
+
+          block << line
+          raise Error.new(:parse) if block.bytesize > MAX_BLOCK_BYTES
+        end
+        raise Error.new(:parse) unless closed
+
+        block
+      end
+
+      # Parses an extracted block under the rules above.
+      def parse(block)
+        document = single_document(block)
+        check_nodes!(document.root)
+
+        value = begin
+          Psych.safe_load(block, permitted_classes: [], permitted_symbols: [], aliases: false)
+        rescue Psych::Exception
+          raise Error.new(:parse)
+        end
+        raise Error.new(:parse) unless value.is_a?(Hash)
+
+        begin
+          Json.normalize(value)
+        rescue ArgumentError
+          raise Error.new(:parse)
+        end
+      end
+
+      # Whether two normalized frontmatter Hashes are equal, with Integer and Float kept distinct.
+      def equal?(expected, actual)
+        Json.equal?(expected, actual)
+      end
+
+      private
+
+      def delimiter_line?(line)
+        line.chomp == DELIMITER
+      end
+
+      # A line break the delimiter scan above does not see but Psych does: a carriage return that is not part of
+      # a `\r\n` ending, or one of the YAML 1.1-only separators. The scan and Psych must never disagree, and neither
+      # must Psych and a YAML 1.2 reader. Only an exact `\r\n` suffix is taken off before looking (`chomp` would
+      # also strip a lone `\r` or the `\r` of `\r\r\n`).
+      def foreign_break?(line)
+        line.delete_suffix("\r\n").include?("\r") || line.match?(UNICODE_BREAKS)
+      end
+
+      # `Psych.parse` and `safe_load` read only the first document, so a `...` or a second `---` inside
+      # the block would hide content from every check; the stream must hold exactly one implicit document.
+      def single_document(block)
+        stream = begin
+          parser = Psych::Parser.new(BoundedTreeBuilder.new)
+          parser.parse(block)
+          parser.handler.root
+        rescue Psych::Exception
+          raise Error.new(:parse)
+        end
+        documents = stream.children
+        raise Error.new(:parse) unless documents.size == 1
+
+        document = documents.first
+        version = document.version
+        unless (version.nil? || version.empty?) && document.tag_directives.empty? &&
+            document.implicit && document.implicit_end && document.root.is_a?(Psych::Nodes::Mapping)
+          raise Error.new(:parse)
+        end
+
+        document
+      end
+
+      # Walks the AST iteratively, before `safe_load` ever builds Ruby objects from it.
+      def check_nodes!(root)
+        scanner = Psych::ScalarScanner.new(Psych::ClassLoader.new)
+        stack = [[root, 1]]
+        until stack.empty?
+          node, depth = stack.pop
+          raise Error.new(:parse) if depth > MAX_DEPTH
+          raise Error.new(:parse) if node.respond_to?(:tag) && node.tag
+
+          case node
+          when Psych::Nodes::Scalar
+            raise Error.new(:parse) if node.plain && CoreSchema.divergent?(scanner, node.value)
+          when Psych::Nodes::Sequence
+            node.children.each { |child| stack.push([child, depth + 1]) }
+          when Psych::Nodes::Mapping
+            check_mapping!(node, depth, stack, scanner)
+          else
+            raise Error.new(:parse)
+          end
+        end
+      end
+
+      def check_mapping!(node, depth, stack, scanner)
+        keys = {}
+        node.children.each_slice(2) do |key, value|
+          raise Error.new(:parse) unless key.is_a?(Psych::Nodes::Scalar) && key.tag.nil?
+
+          text = key.value
+          if key.plain
+            raise Error.new(:parse) if CoreSchema.divergent?(scanner, text)
+            raise Error.new(:parse) unless CoreSchema.resolve(text).is_a?(String)
+          end
+          raise Error.new(:parse) if text == MERGE_KEY || keys.key?(text)
+
+          keys[text] = true
+          stack.push([value, depth + 1])
+        end
+      end
+    end
+  end
+end

data/lib/mcp/skill/resource_entry.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module MCP
+  class Skill
+    # One file of a skill as its manifest lists it: `{ uri, digest, size }` (SEP-2640). The `digest` is
+    # `sha256:` followed by 64 lowercase hex characters over the file's raw bytes, `size` is the byte length.
+    # Only the shape is checked here; whether the URI lies under the skill's root is checked by `MCP::Skill`,
+    # which knows the root.
+    class ResourceEntry
+      DIGEST_PATTERN = /\Asha256:[0-9a-f]{64}\z/.freeze
+
+      # The keys `from` accepts in a Hash, as Symbols or Strings.
+      HASH_KEYWORDS = { "uri" => :uri, "digest" => :digest, "size" => :size }.freeze
+      private_constant :HASH_KEYWORDS
+
+      class << self
+        # Returns `value` when it is already a `ResourceEntry`, builds one from a Hash, and refuses anything else.
+        def from(value)
+          return value if value.is_a?(ResourceEntry)
+
+          unless value.is_a?(Hash)
+            raise ArgumentError, "A skill resource entry must be an MCP::Skill::ResourceEntry or a Hash (got #{value.class})."
+          end
+
+          keywords = {}
+          value.each do |key, member|
+            unless key.is_a?(Symbol) || key.is_a?(String)
+              raise ArgumentError, "A skill resource entry Hash key must be a Symbol or a String (got #{key.class})."
+            end
+
+            keyword = HASH_KEYWORDS[key.to_s]
+            unless keyword
+              raise ArgumentError, "A skill resource entry Hash may only hold uri, digest, and size (got #{key.inspect})."
+            end
+            raise ArgumentError, "A skill resource entry Hash gives #{keyword} twice." if keywords.key?(keyword)
+
+            keywords[keyword] = member
+          end
+
+          new(**keywords)
+        end
+
+        # Builds an entry from a server's wire Hash (String or Symbol keys), reading `uri`, `digest`, and `size` and
+        # ignoring any other member a server may add; `from` refuses unknown members for local definitions instead.
+        #
+        # @api private
+        def from_wire(value)
+          return value if value.is_a?(ResourceEntry)
+          raise ArgumentError, "A skill resource entry must be a Hash (got #{value.class})." unless value.is_a?(Hash)
+
+          new(uri: wire_member(value, "uri"), digest: wire_member(value, "digest"), size: wire_member(value, "size"))
+        end
+
+        # Builds the entry for a file from the exact bytes the resource will serve, so an author never formats
+        # a digest by hand: pass `File.binread` output for a binary file and UTF-8 text for a text file.
+        def from_content(uri:, content:)
+          unless content.is_a?(String)
+            raise ArgumentError, "The value of content must be a String (got #{content.class})."
+          end
+
+          new(uri: uri, digest: "sha256:#{Digest::SHA256.hexdigest(content.b)}", size: content.bytesize)
+        end
+
+        private
+
+        def wire_member(hash, key)
+          value = hash[key]
+          value.nil? ? hash[key.to_sym] : value
+        end
+      end
+
+      attr_reader :uri, :digest, :size
+
+      def initialize(uri:, digest:, size:)
+        unless uri.is_a?(String) && Uri.structural?(uri)
+          raise ArgumentError, "The value of uri must be a skill:// URI with non-empty path segments."
+        end
+
+        unless digest.is_a?(String) && digest.encoding.ascii_compatible? && DIGEST_PATTERN.match?(digest)
+          raise ArgumentError, "The value of digest must be sha256: followed by 64 lowercase hex characters."
+        end
+
+        unless size.is_a?(Integer) && size >= 0
+          raise ArgumentError, "The value of size must be a non-negative Integer (got #{size.class})."
+        end
+
+        @uri = -uri
+        @digest = -digest
+        @size = size
+        freeze
+      end
+
+      def to_h
+        { uri: uri, digest: digest, size: size }
+      end
+
+      def ==(other)
+        other.is_a?(ResourceEntry) && to_h == other.to_h
+      end
+      alias_method :eql?, :==
+
+      def hash
+        to_h.hash
+      end
+    end
+  end
+end