marshalsea 0.1.0

data/lib/marshalsea/psych/inspector.rb

@@ -0,0 +1,277 @@
+# ©AngelaMos | 2026
+# inspector.rb
+# frozen_string_literal: true
+
+require "psych"
+
+module Marshalsea
+  module Psych
+    class DocumentError < StandardError; end
+
+    class MalformedDocumentError < DocumentError; end
+
+    class InputTypeError < DocumentError; end
+
+    class LimitExceededError < DocumentError; end
+
+    module Tags
+      PATTERN = %r{\A!ruby/(?<kind>[a-z_-]+)(?::(?<class_name>.+))?\z}
+
+      KIND_OBJECT = "object"
+      KIND_HASH = "hash"
+      KIND_ARRAY = "array"
+      KIND_STRING = "string"
+      KIND_STRUCT = "struct"
+      KIND_EXCEPTION = "exception"
+      KIND_MARSHALABLE = "marshalable"
+
+      REVIVAL_METHODS = {
+        KIND_OBJECT => "init_with",
+        KIND_HASH => "[]=",
+        KIND_ARRAY => "init_with",
+        KIND_STRING => "init_with",
+        KIND_STRUCT => "init_with",
+        KIND_EXCEPTION => "init_with",
+        KIND_MARSHALABLE => "marshal_load"
+      }.freeze
+
+      GATED_KINDS = [KIND_MARSHALABLE].freeze
+
+      module_function
+
+      def parse(tag)
+        match = PATTERN.match(tag.to_s)
+        return nil unless match
+
+        [match[:kind], match[:class_name]]
+      end
+    end
+
+    class Limits
+      DEFAULT_MAX_BYTES = 1_048_576
+      DEFAULT_MAX_DEPTH = 64
+      DEFAULT_MAX_NODES = 10_000
+      DEFAULT_MAX_ALIASES = 64
+      DEFAULT_MAX_DOCUMENTS = 8
+
+      ROLE_BYTES = "document bytes"
+      ROLE_DEPTH = "nesting depth"
+      ROLE_NODES = "nodes"
+      ROLE_ALIASES = "aliases"
+      ROLE_DOCUMENTS = "documents"
+
+      attr_reader :max_bytes, :max_depth, :max_nodes, :max_aliases, :max_documents
+
+      def initialize(max_bytes: DEFAULT_MAX_BYTES, max_depth: DEFAULT_MAX_DEPTH,
+                     max_nodes: DEFAULT_MAX_NODES, max_aliases: DEFAULT_MAX_ALIASES,
+                     max_documents: DEFAULT_MAX_DOCUMENTS)
+        @max_bytes = max_bytes
+        @max_depth = max_depth
+        @max_nodes = max_nodes
+        @max_aliases = max_aliases
+        @max_documents = max_documents
+      end
+    end
+
+    class Reference
+      attr_reader :class_name, :kind, :key_position
+
+      def initialize(class_name:, kind:, key_position:)
+        @class_name = class_name
+        @kind = kind
+        @key_position = key_position
+      end
+
+      def key_position?
+        @key_position
+      end
+
+      def gated?
+        Tags::GATED_KINDS.include?(kind)
+      end
+
+      def revival_method
+        Tags::REVIVAL_METHODS.fetch(kind, nil)
+      end
+
+      def to_s
+        "#{class_name} (!ruby/#{kind})"
+      end
+    end
+
+    class Document
+      attr_reader :references, :alias_count, :node_count, :document_count
+
+      def initialize(references:, alias_count:, node_count:, document_count:)
+        @references = references
+        @alias_count = alias_count
+        @node_count = node_count
+        @document_count = document_count
+      end
+
+      def class_names
+        references.filter_map(&:class_name).uniq
+      end
+
+      def revivable
+        references.reject { |reference| reference.class_name.nil? }
+      end
+
+      def key_position_references
+        references.select(&:key_position?)
+      end
+
+      def gated_references
+        references.select(&:gated?)
+      end
+    end
+
+    class Inspector
+      Decision = Marshalsea::Marshal::BoundaryDetector::Decision
+
+      REASON_INPUT_TYPE = "input is not a String"
+      REASON_MALFORMED = "document is not parseable YAML: %s"
+      REASON_UNAPPROVED = "document revives unapproved class %s through %s"
+      REASON_KEY_DISPATCH = "document puts %s in a mapping key, so its #hash and #== run " \
+                            "while the mapping is rebuilt"
+
+      LIMITATION_NOTICE = <<~NOTICE
+        SECURITY LIMITATION
+
+        Marshalsea::Psych::Inspector reads a YAML document through Psych.parse_stream, which
+        builds an AST and revives nothing. It never calls YAML.load or YAML.unsafe_load.
+
+        Unlike Marshal, Psych's own allowlist is a real veto: Psych checks the tag before it
+        revives the object, where Marshal runs its proc after the callback has already fired.
+        Same intent, opposite outcome, decided entirely by where the check sits. That means
+        YAML.safe_load with permitted_classes is a boundary and this inspector is only
+        detection and reporting on top of it.
+
+        Prefer YAML.safe_load. Use this to see what a document would revive, to log it, or
+        to reject a document before it reaches a loader you do not control.
+
+        Alias expansion is not performed here, so an alias bomb costs nothing to inspect.
+        It still costs whatever the eventual loader spends expanding it, which is why the
+        alias count is bounded and reported rather than ignored.
+      NOTICE
+
+      def initialize(permitted_class_names: [], limits: Limits.new)
+        @permitted_class_names = permitted_class_names.map(&:to_s).freeze
+        @limits = limits
+      end
+
+      def inspect_document(input)
+        return reject(REASON_INPUT_TYPE) unless input.is_a?(String)
+
+        snapshot = input.dup.freeze
+        enforce_size(snapshot)
+        evaluate(read(snapshot), snapshot)
+      rescue DocumentError => e
+        reject(format(REASON_MALFORMED, e.class.name.split("::").last))
+      end
+
+      def read(source)
+        Walk.new(limits).call(::Psych.parse_stream(source))
+      rescue ::Psych::SyntaxError => e
+        raise MalformedDocumentError, e.message
+      end
+
+      private
+
+      attr_reader :permitted_class_names, :limits
+
+      def enforce_size(source)
+        return if source.bytesize <= limits.max_bytes
+
+        raise LimitExceededError, "#{Limits::ROLE_BYTES} #{source.bytesize} exceeds #{limits.max_bytes}"
+      end
+
+      def evaluate(document, snapshot)
+        violation = violation_for(document)
+        return reject(violation) if violation
+
+        Decision.new(state: Decision::STATE_PROCEED, snapshot: snapshot, result: document)
+      end
+
+      def violation_for(document)
+        keyed = document.key_position_references.first
+        return format(REASON_KEY_DISPATCH, keyed.class_name.inspect) if keyed
+
+        unapproved = document.revivable.reject do |reference|
+          permitted_class_names.include?(reference.class_name)
+        end
+        return nil if unapproved.empty?
+
+        format(REASON_UNAPPROVED, unapproved.first.class_name.inspect,
+               unapproved.first.revival_method)
+      end
+
+      def reject(reason)
+        Decision.new(state: Decision::STATE_BLOCKED, reason: reason)
+      end
+    end
+
+    class Walk
+      MAPPING_KEY_STRIDE = 2
+
+      def initialize(limits)
+        @limits = limits
+        @references = []
+        @aliases = 0
+        @nodes = 0
+        @documents = 0
+      end
+
+      def call(stream)
+        @documents = stream.children.length
+        check(@documents, limits.max_documents, Limits::ROLE_DOCUMENTS)
+        stream.children.each { |child| visit(child, 1, false) }
+        Document.new(references: @references.freeze, alias_count: @aliases,
+                     node_count: @nodes, document_count: @documents)
+      end
+
+      private
+
+      attr_reader :limits
+
+      def check(value, ceiling, role)
+        return if value <= ceiling
+
+        raise LimitExceededError, "#{role} #{value} exceeds #{ceiling}"
+      end
+
+      def visit(node, depth, key_position)
+        check(depth, limits.max_depth, Limits::ROLE_DEPTH)
+        @nodes += 1
+        check(@nodes, limits.max_nodes, Limits::ROLE_NODES)
+
+        if node.is_a?(::Psych::Nodes::Alias)
+          @aliases += 1
+          check(@aliases, limits.max_aliases, Limits::ROLE_ALIASES)
+        end
+
+        record(node, key_position)
+        descend(node, depth)
+      end
+
+      def record(node, key_position)
+        return unless node.respond_to?(:tag)
+
+        kind, class_name = Tags.parse(node.tag)
+        return unless kind
+
+        @references << Reference.new(class_name: class_name, kind: kind, key_position: key_position)
+      end
+
+      def descend(node, depth)
+        children = node.children
+        return unless children
+
+        mapping = node.is_a?(::Psych::Nodes::Mapping)
+        children.each_with_index do |child, index|
+          visit(child, depth + 1, mapping && (index % MAPPING_KEY_STRIDE).zero?)
+        end
+      end
+    end
+  end
+end

data/lib/marshalsea/scanner.rb

@@ -0,0 +1,397 @@
+# ©AngelaMos | 2026
+# scanner.rb
+# frozen_string_literal: true
+
+module Marshalsea
+  class ParseRecoveredError < StandardError
+    def initialize(errors)
+      super("Prism recovered an incomplete tree from #{errors} syntax errors")
+    end
+  end
+
+  class Scanner
+    GATE_GATED = :gated
+    GATE_SOFT = :soft
+    GATE_UNGATED = :ungated
+    GATE_LINK = :link
+
+    FORMAT_MARSHAL = :marshal
+    FORMAT_PSYCH = :psych
+
+    VARIADIC = -1
+
+    ENTRY_POINTS = {
+      "marshal_load" => { gate: GATE_GATED, arity: 1, formats: [FORMAT_MARSHAL, FORMAT_PSYCH] },
+      "_load_data" => { gate: GATE_GATED, arity: 1, formats: [FORMAT_MARSHAL] },
+      "_load" => { gate: GATE_GATED, arity: 1, formats: [FORMAT_MARSHAL], singleton: true },
+      "init_with" => { gate: GATE_SOFT, arity: 1, formats: [FORMAT_PSYCH] },
+      "hash" => { gate: GATE_UNGATED, arity: 0, formats: [FORMAT_MARSHAL, FORMAT_PSYCH] },
+      "eql?" => { gate: GATE_UNGATED, arity: 1, formats: [FORMAT_MARSHAL, FORMAT_PSYCH] },
+      "<=>" => { gate: GATE_UNGATED, arity: 1, formats: [FORMAT_MARSHAL] },
+      "==" => { gate: GATE_UNGATED, arity: 1, formats: [FORMAT_PSYCH] },
+      "[]=" => { gate: GATE_UNGATED, arity: 2, formats: [FORMAT_PSYCH] },
+      "method_missing" => { gate: GATE_UNGATED, arity: VARIADIC, formats: [FORMAT_MARSHAL, FORMAT_PSYCH] },
+      "respond_to_missing?" => { gate: GATE_UNGATED, arity: 2, formats: [FORMAT_MARSHAL, FORMAT_PSYCH] },
+      "respond_to?" => { gate: GATE_UNGATED, arity: VARIADIC, formats: [FORMAT_PSYCH] },
+      "to_s" => { gate: GATE_LINK, arity: 0, formats: [] },
+      "coerce" => { gate: GATE_LINK, arity: 1, formats: [] }
+    }.freeze
+
+    GATED_METHODS = ENTRY_POINTS.select { |_, spec| spec[:gate] == GATE_GATED && !spec[:singleton] }
+                                .keys.freeze
+    GATED_SINGLETON_METHODS = ENTRY_POINTS.select { |_, spec| spec[:singleton] }.keys.freeze
+    UNGATED_METHODS = ENTRY_POINTS.select { |_, spec| spec[:gate] == GATE_UNGATED }.keys.freeze
+    LINK_METHODS = ENTRY_POINTS.select { |_, spec| spec[:gate] == GATE_LINK }.keys.freeze
+    INSTANCE_METHODS = ENTRY_POINTS.reject { |_, spec| spec[:singleton] }.keys.freeze
+    SINGLETON_METHODS = GATED_SINGLETON_METHODS
+
+    PRISM_AVAILABLE = begin
+      require "prism"
+      true
+    rescue LoadError
+      false
+    end
+
+    LOCATION_SEPARATOR = ":"
+    UNKNOWN_LOCATION = nil
+
+    STATE_UNREADABLE = :unreadable
+    STATE_UNANALYSABLE = :unanalysable
+    STATE_VERDICTS = [true, false].freeze
+
+    SITE_MODULE_NAME = :module_name
+    SITE_OWN_METHODS = :own_methods
+    SITE_CANDIDATE = :candidate
+    SITE_SOURCE_PARSE = :source_parse
+    SITE_STATE_ANALYSIS = :state_analysis
+
+    SITES = [SITE_MODULE_NAME, SITE_OWN_METHODS, SITE_CANDIDATE,
+             SITE_SOURCE_PARSE, SITE_STATE_ANALYSIS].freeze
+
+    LOSSY_SITES = [SITE_MODULE_NAME, SITE_OWN_METHODS, SITE_CANDIDATE].freeze
+
+    SUBJECT_UNNAMED = "(module that cannot report a name)"
+
+    class Candidate
+      attr_reader :class_name, :method_name, :gate, :source_location, :arity, :formats
+
+      def initialize(class_name:, method_name:, gate:, source_location:, arity:, singleton:,
+                     touches_state:, formats:)
+        @class_name = class_name
+        @method_name = method_name
+        @gate = gate
+        @source_location = source_location
+        @arity = arity
+        @singleton = singleton
+        @touches_state = touches_state
+        @formats = formats
+      end
+
+      def singleton?
+        @singleton
+      end
+
+      def gated?
+        gate == GATE_GATED
+      end
+
+      def soft_gated?
+        gate == GATE_SOFT
+      end
+
+      def link?
+        gate == GATE_LINK
+      end
+
+      def entry_point?
+        !link?
+      end
+
+      def dispatch_arity
+        ENTRY_POINTS.fetch(method_name).fetch(:arity)
+      end
+
+      def accepts_dispatch?
+        required = dispatch_arity
+        return true if required == VARIADIC
+        return arity == required unless arity.negative?
+
+        required >= (arity.abs - 1)
+      end
+
+      def zero_arity?
+        arity.zero?
+      end
+
+      def touches_state?
+        @touches_state == true
+      end
+
+      def state_known?
+        STATE_VERDICTS.include?(@touches_state)
+      end
+
+      def unanalysable?
+        @touches_state == STATE_UNANALYSABLE
+      end
+
+      def unreadable_source?
+        @touches_state == STATE_UNREADABLE
+      end
+
+      def reachable?
+        return false unless entry_point?
+        return false unless accepts_dispatch?
+        return true if gated? || soft_gated?
+
+        touches_state? || unreadable_source?
+      end
+
+      def to_s
+        "#{class_name}#{singleton? ? '.' : '#'}#{method_name}"
+      end
+    end
+
+    class Suppression
+      attr_reader :site, :subject, :error_class
+
+      def initialize(site:, subject:, error_class:)
+        @site = site
+        @subject = subject
+        @error_class = error_class
+      end
+
+      def lossy?
+        LOSSY_SITES.include?(site)
+      end
+
+      def to_s
+        "#{site} #{subject} (#{error_class})"
+      end
+    end
+
+    class Report
+      attr_reader :candidates, :scanned_modules, :suppressions
+
+      def initialize(candidates, scanned_modules, suppressions)
+        @candidates = candidates
+        @scanned_modules = scanned_modules
+        @suppressions = suppressions
+      end
+
+      def suppressed_count
+        suppressions.length
+      end
+
+      def suppressions_by_site
+        suppressions.each_with_object({}) do |suppression, counts|
+          counts[suppression.site] = counts.fetch(suppression.site, 0) + 1
+        end
+      end
+
+      def complete?
+        suppressions.empty?
+      end
+
+      def candidates_lost?
+        suppressions.any?(&:lossy?)
+      end
+
+      def unanalysable
+        candidates.select(&:unanalysable?)
+      end
+
+      def fully_analysed?
+        candidates.all?(&:state_known?)
+      end
+
+      def gated
+        candidates.select(&:gated?)
+      end
+
+      def ungated
+        candidates.select { |candidate| candidate.gate == GATE_UNGATED }
+      end
+
+      def links
+        candidates.select(&:link?)
+      end
+
+      def entry_points
+        candidates.select(&:entry_point?)
+      end
+
+      def reachable
+        candidates.select(&:reachable?)
+      end
+
+      def reachable_in(format)
+        reachable.select { |candidate| candidate.formats.include?(format) }
+      end
+
+      def prism_available?
+        PRISM_AVAILABLE
+      end
+    end
+
+    def initialize(namespace: nil)
+      @namespace = namespace
+      @candidates = []
+      @definition_cache = {}
+      @scanned_modules = 0
+      @suppressions = []
+    end
+
+    def scan
+      each_named_module do |mod, name|
+        @scanned_modules += 1
+        collect_instance_methods(mod, name)
+        collect_singleton_methods(mod, name)
+      end
+
+      Report.new(@candidates.sort_by(&:to_s), @scanned_modules, @suppressions.freeze)
+    end
+
+    private
+
+    attr_reader :namespace
+
+    def suppress(site, subject, error)
+      @suppressions << Suppression.new(site: site, subject: subject, error_class: error.class.name)
+    end
+
+    def each_named_module
+      ObjectSpace.each_object(Module) do |mod|
+        name = safe_name(mod)
+        next unless name
+        next unless in_namespace?(name)
+
+        yield mod, name
+      end
+    end
+
+    def safe_name(mod)
+      name = mod.name
+      name if name.is_a?(String) && !name.empty?
+    rescue StandardError => e
+      suppress(SITE_MODULE_NAME, SUBJECT_UNNAMED, e)
+      nil
+    end
+
+    def in_namespace?(name)
+      namespace.nil? || name == namespace || name.start_with?("#{namespace}::")
+    end
+
+    def collect_instance_methods(mod, name)
+      (own_instance_methods(mod, name) & INSTANCE_METHODS).each do |method_name|
+        record(mod, name, method_name, singleton: false)
+      end
+    end
+
+    def collect_singleton_methods(mod, name)
+      (own_singleton_methods(mod, name) & SINGLETON_METHODS).each do |method_name|
+        record(mod, name, method_name, singleton: true)
+      end
+    end
+
+    def own_instance_methods(mod, name)
+      (mod.instance_methods(false) +
+       mod.private_instance_methods(false) +
+       mod.protected_instance_methods(false)).map(&:to_s)
+    rescue StandardError => e
+      suppress(SITE_OWN_METHODS, name, e)
+      []
+    end
+
+    def own_singleton_methods(mod, name)
+      (mod.singleton_methods(false) +
+       mod.singleton_class.private_instance_methods(false)).map(&:to_s)
+    rescue StandardError => e
+      suppress(SITE_OWN_METHODS, name, e)
+      []
+    end
+
+    def qualified(name, method_name, singleton)
+      "#{name}#{singleton ? '.' : '#'}#{method_name}"
+    end
+
+    def record(mod, name, method_name, singleton:)
+      spec = ENTRY_POINTS.fetch(method_name)
+      handle = singleton ? mod.singleton_class.instance_method(method_name) : mod.instance_method(method_name)
+
+      @candidates << Candidate.new(
+        class_name: name,
+        method_name: method_name,
+        gate: spec.fetch(:gate),
+        source_location: format_location(handle.source_location),
+        arity: handle.arity,
+        singleton: singleton,
+        touches_state: state_reference_in(handle, qualified(name, method_name, singleton)),
+        formats: spec.fetch(:formats)
+      )
+    rescue StandardError, ScriptError => e
+      suppress(SITE_CANDIDATE, qualified(name, method_name, singleton), e)
+      nil
+    end
+
+    def format_location(location)
+      return UNKNOWN_LOCATION unless location
+
+      location.join(LOCATION_SEPARATOR)
+    end
+
+    def state_reference_in(handle, subject)
+      return STATE_UNANALYSABLE unless PRISM_AVAILABLE
+
+      path, line = handle.source_location
+      return STATE_UNANALYSABLE unless path && line
+
+      definitions = definitions_for(path)
+      return STATE_UNREADABLE unless definitions
+
+      node = definitions[line]
+      return STATE_UNREADABLE unless node
+
+      node.compact_child_nodes.any? { |child| state_reference?(child) }
+    rescue StandardError, ScriptError => e
+      suppress(SITE_STATE_ANALYSIS, subject, e)
+      STATE_UNREADABLE
+    end
+
+    def definitions_for(path)
+      return @definition_cache[path] if @definition_cache.key?(path)
+
+      @definition_cache[path] = parse_definitions(path)
+    end
+
+    def parse_definitions(path)
+      parsed = Prism.parse_file(path)
+      if parsed.failure?
+        suppress(SITE_SOURCE_PARSE, path, ParseRecoveredError.new(parsed.errors.length))
+        return nil
+      end
+
+      found = {}
+      collect_definitions(parsed.value, found)
+      found
+    rescue StandardError, ScriptError => e
+      suppress(SITE_SOURCE_PARSE, path, e)
+      nil
+    end
+
+    def collect_definitions(node, found)
+      return unless node.is_a?(Prism::Node)
+
+      found[node.location.start_line] = node if node.is_a?(Prism::DefNode)
+      node.compact_child_nodes.each { |child| collect_definitions(child, found) }
+    end
+
+    def state_reference?(node)
+      return false unless node.is_a?(Prism::Node)
+      return true if node.is_a?(Prism::InstanceVariableReadNode)
+      return true if node.is_a?(Prism::CallNode) && node.receiver.nil?
+
+      node.compact_child_nodes.any? { |child| state_reference?(child) }
+    end
+  end
+end

data/lib/marshalsea/version.rb

@@ -0,0 +1,7 @@
+# ©AngelaMos | 2026
+# version.rb
+# frozen_string_literal: true
+
+module Marshalsea
+  VERSION = "0.1.0"
+end

data/lib/marshalsea.rb

@@ -0,0 +1,19 @@
+# ©AngelaMos | 2026
+# marshalsea.rb
+# frozen_string_literal: true
+
+require_relative "marshalsea/version"
+require_relative "marshalsea/marshal/constants"
+require_relative "marshalsea/marshal/errors"
+require_relative "marshalsea/marshal/node"
+require_relative "marshalsea/marshal/float_body"
+require_relative "marshalsea/marshal/limits"
+require_relative "marshalsea/marshal/parser"
+require_relative "marshalsea/marshal/boundary_detector"
+require_relative "marshalsea/marshal/load_guard"
+require_relative "marshalsea/psych/inspector"
+require_relative "marshalsea/scanner"
+require_relative "marshalsea/chains"
+
+module Marshalsea
+end