moxml 0.1.25 → 0.2.0

data/lib/moxml/entity.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Entity-reference round-trip pipeline.
+  #
+  # XML libraries split into two camps: those that preserve named
+  # entity references natively (nokogiri) and those that expand or
+  # reject them at parse (ox, rexml, oga, libxml, leptris). Moxml
+  # bridges the camps with one pipeline, owned here and delegated to
+  # by Adapter::Base:
+  #
+  # 1. Parse time — .preprocess_entities rewrites non-standard
+  #    entity references to a two-character marker (see MARKER) so
+  #    the reference survives native parsing verbatim. The five
+  #    standard entities (& < > " ') are NOT
+  #    converted.
+  # 2. Read time — marker-bearing text is split into text and
+  #    Entity::Reference nodes (adapters whose natives cannot hold
+  #    references), or decoded in place (.decode_entities covers the
+  #    five standard entities plus numeric character references).
+  # 3. Serialize time — .restore_entities maps markers back to named
+  #    references, including markers a native serializer already
+  #    rendered as character references.
+  #
+  # How references are STORED between parse and serialize is
+  # adapter-shaped (in-tree value objects for ox, attachment
+  # sequences for rexml/libxml, text markers for oga/leptris); the
+  # marker lifecycle and the Entity::Reference value type are the
+  # shared, single-sourced parts.
+  module Entity
+    autoload :Reference, "moxml/entity/reference"
+
+    # Marker for adapters that resolve entities during parsing.
+    # U+FFFC (Object Replacement Character) + U+FEFF (BOM) is a
+    # two-character sentinel chosen because this exact sequence
+    # followed by a valid entity name pattern is vanishingly unlikely
+    # in real XML content.
+    MARKER = "\u{FFFC}\u{FEFF}"
+    NAME_PATTERN = "[a-zA-Z_][\\w.:-]*"
+    NAME_RE = /&(#{NAME_PATTERN});/
+    MARKER_RE = /\u{FFFC}\u{FEFF}(#{NAME_PATTERN});/
+    SERIALIZED_MARKER_RE = /(#{NAME_PATTERN});/
+    STANDARD_ENTITIES = %w[amp lt gt quot apos].freeze
+
+    NAMED_DECODE_MAP = {
+      "amp" => "&", "lt" => "<", "gt" => ">",
+      "quot" => '"', "apos" => "'"
+    }.freeze
+    private_constant :NAMED_DECODE_MAP
+
+    DECODE_RE = /&(?:(amp|lt|gt|quot|apos)|#(?:(\d+)|[xX]([0-9a-fA-F]+)));/
+    private_constant :DECODE_RE
+
+    module_function
+
+    # Replace non-standard entity references with markers before
+    # parsing. Always returns a UTF-8 encoded string.
+    def preprocess_entities(xml)
+      return "" if xml.nil?
+
+      str = if xml.encoding == Encoding::BINARY
+              # Binary strings are assumed to be UTF-8. If the bytes are
+              # not valid UTF-8, fall back to encoding as UTF-8 with
+              # replacement to avoid raising on gsub.
+              dup = xml.dup.force_encoding("UTF-8")
+              if dup.valid_encoding?
+                dup
+              else
+                xml.dup.encode("UTF-8",
+                               "ASCII-8BIT", invalid: :replace, undef: :replace)
+              end
+            elsif xml.encoding == Encoding::UTF_8
+              xml
+            else
+              xml.encode("UTF-8")
+            end
+      # Fast path: no `&` means no entity references to mark — skip
+      # the regex scan and string allocation entirely. The vast
+      # majority of XML payloads contain no entity references.
+      return str unless str.include?("&")
+
+      str.gsub(NAME_RE) do |match|
+        STANDARD_ENTITIES.include?(::Regexp.last_match(1)) ? match : "#{MARKER}#{::Regexp.last_match(1)};"
+      end
+    end
+
+    # Resolve numeric (&#NN; / &#xNN;) and the five standard named
+    # (&amp; &lt; &gt; &quot; &apos;) XML entity references in one
+    # single pass. The resulting characters are data; no further
+    # decoding is applied. Numeric refs producing invalid UTF-8
+    # (NUL, surrogate halves, > U+10FFFF) are preserved verbatim
+    # to avoid silently emitting malformed bytes.
+    def decode_entities(text)
+      return text unless text.is_a?(String) && text.include?("&")
+
+      text.gsub(DECODE_RE) do
+        if (named = ::Regexp.last_match(1))
+          NAMED_DECODE_MAP[named]
+        else
+          code = ::Regexp.last_match(2) ? ::Regexp.last_match(2).to_i : ::Regexp.last_match(3).to_i(16)
+          if code.zero? || code.between?(0xD800, 0xDFFF) || code > 0x10FFFF
+            ::Regexp.last_match(0)
+          else
+            [code].pack("U")
+          end
+        end
+      end
+    end
+
+    # Restore entity markers back to named entity references.
+    def restore_entities(text)
+      return text unless text.is_a?(String)
+
+      # Force UTF-8 encoding since markers are UTF-8 characters
+      str = text.encoding == Encoding::UTF_8 ? text : text.dup.force_encoding("UTF-8")
+      # Fast path: the vast majority of documents carry no entity
+      # markers — two C-level scans beat two regex passes.
+      return str unless str.include?(MARKER) ||
+        str.include?("&#xFFFC;")
+
+      result = str.gsub(MARKER_RE, '&\1;')
+      result.gsub(SERIALIZED_MARKER_RE, '&\1;')
+    end
+  end
+end

data/lib/moxml/node.rb

@@ -55,6 +55,8 @@ module Moxml
       refreshed = adapter.actual_native(node.native, @native)
       node.refresh_native!(refreshed) if refreshed && refreshed != node.native
       node.parent_node = self
+      # The adopted subtree's in-scope namespaces changed
+      node.invalidate_namespace_cache!
       invalidate_children_cache!
       self
     end
@@ -77,9 +79,15 @@ module Moxml
       invalidate_parent_children_cache!
       adapter.remove(@native)
       invalidate_children_cache!
+      # The detached subtree left its declaring ancestors behind
+      invalidate_namespace_cache!
       self
     end
 
+    # Namespace-scope caches live on Element; the base no-op lets tree
+    # mutations invalidate uniformly without type checks.
+    def invalidate_namespace_cache!; end
+
     def replace(node)
       node = prepare_node(node)
       invalidate_parent_children_cache!
@@ -103,7 +111,10 @@ module Moxml
     end
 
     def xpath(expression, namespaces = {})
-      NodeSet.new(adapter.xpath(@native, expression, namespaces), context)
+      result = adapter.xpath(@native, expression, namespaces)
+      # Adapter contract: Array<native> | scalar. Scalars (count(),
+      # string-length(), booleans) pass through unwrapped.
+      result.is_a?(Array) ? NodeSet.new(result, context) : result
     end
 
     def at_xpath(expression, namespaces = {})
@@ -186,6 +197,69 @@ module Moxml
       children.each(&block)
     end
 
+    # Returns all ancestor nodes from the parent up to and including
+    # the document node.
+    #
+    # @return [NodeSet] ancestors ordered nearest-first
+    def ancestors
+      return NodeSet.new([], context) if document?
+
+      natives = []
+      current = parent
+      while current
+        natives << current.native
+        break if current.document?
+
+        current = current.parent
+      end
+      NodeSet.new(natives, context)
+    end
+
+    # Returns all descendant nodes (children, grandchildren, and so on),
+    # excluding the node itself.
+    #
+    # @return [NodeSet] descendants in document order
+    def descendants
+      natives = []
+      each_node { |node| natives << node.native }
+      NodeSet.new(natives, context)
+    end
+
+    # Returns an XPath expression that uniquely locates this node within
+    # its document. Positional predicates are emitted only when sibling
+    # elements share the same qualified name, keeping paths minimal.
+    #
+    # @return [String] XPath expression
+    # @raise [Moxml::NotImplementedError] for node types other than
+    #   element and document
+    def path
+      return "/" if document?
+
+      unless element?
+        raise Moxml::NotImplementedError.new(
+          "path is only supported for element and document nodes",
+          feature: "path",
+        )
+      end
+
+      segments = []
+      current = self
+      while current && !current.document?
+        segments.unshift(path_segment_for(current))
+        current = current.parent
+      end
+      "/#{segments.join('/')}"
+    end
+
+    # Returns the 1-based line number where this node appears in the
+    # source XML, or nil when the underlying adapter does not track
+    # source positions.
+    #
+    # @return [Integer, nil]
+    def line_number
+      adapter.line_number(@native)
+    end
+
     def outer_xml
       to_xml
     end
@@ -286,6 +360,21 @@ module Moxml
 
     private
 
+    # XPath segment for an element: the qualified name, plus a positional
+    # predicate only when same-named element siblings make it ambiguous.
+    def path_segment_for(element)
+      name = element.name
+      parent = element.parent
+      return name unless parent
+
+      same_name = parent.children.select do |child|
+        child.element? && child.name == name
+      end
+      return name if same_name.size == 1
+
+      "#{name}[#{same_name.find_index(element) + 1}]"
+    end
+
     def prepare_node(node)
       case node
       when String then Text.new(adapter.create_text(node), context)

data/lib/moxml/sax/namespace_splitter.rb

@@ -9,6 +9,8 @@ module Moxml
     # attribute. This module provides a single implementation.
     module NamespaceSplitter
       # @param attributes [Hash, Array<Array>] attributes as a hash or array of pairs
+      # @yieldparam value [Object] raw attribute/namespace value
+      # @yieldreturn [Object] transformed value to store
       # @return [Array(Hash, Hash)] [regular_attrs, namespaces]
       def split_attributes_and_namespaces(attributes)
         attrs = {}
@@ -16,11 +18,12 @@ module Moxml
 
         each_attribute(attributes) do |name, value|
           name_s = name.to_s
+          v = block_given? ? yield(value) : value
           if name_s == "xmlns" || name_s.start_with?("xmlns:")
             prefix = name_s == "xmlns" ? nil : name_s.sub("xmlns:", "")
-            ns[prefix] = value
+            ns[prefix] = v
           else
-            attrs[name_s] = value
+            attrs[name_s] = v
           end
         end
 

data/lib/moxml/signature/algorithms/base64_transform.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base64 decode transform (W3C §6.6.2).
+      #
+      # Input: octets or nodeset. For nodeset, logically applies self::text(),
+      # sorts nodes by document order, concatenates string values, then decodes.
+      # Output: octets.
+      class Base64Transform < TransformBase
+        identifier "http://www.w3.org/2000/09/xmldsig#base64"
+
+        def self.input_type; :octets; end
+        def self.output_type; :octets; end
+
+        def transform(input)
+          text = input.is_a?(Array) ? input.map { |n| text_of(n) }.join : input.to_s
+          stripped = text.gsub(/\s+/, "")
+          Base64.strict_decode64(stripped)
+        rescue ArgumentError => e
+          raise TransformError.new(
+            "base64 decode failed: #{e.message}",
+            algorithm: self.class.identifier_uri,
+          )
+        end
+
+        private
+
+        def text_of(node)
+          return node.text if node.is_a?(::Moxml::Node)
+
+          node.to_s
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/canonicalization_base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base class for canonicalization algorithms.
+      #
+      # Subclasses declare `identifier "http://..."` and implement #engine
+      # (returning a Moxml::C14n::* walker). Canonicalizers operate on a
+      # Moxml::Node subtree and return UTF-8 octets.
+      #
+      # Canonicalization algorithms can also be used as transforms per
+      # spec §6.6.1. The base class provides the #transform method that
+      # adapts the canonicalize interface to the transform pipeline.
+      class CanonicalizationBase
+        class << self
+          # Canonicalization presents the transform interface (spec §6.6.1).
+          # Input: octet stream or node-set. Output: octet stream.
+          def input_type; :nodeset; end
+
+          def output_type; :octets; end
+
+          def identifier(uri)
+            Algorithms.register(:canonicalization, uri, self)
+          end
+
+          def for_uri(uri, **opts)
+            new(identifier_uri: uri, **opts)
+          end
+        end
+
+        attr_reader :identifier_uri, :with_comments, :inclusive_namespaces,
+                    :context
+
+        # `context:` is required when this algorithm is used as a transform
+        # so that octet-stream input can be parsed with the same adapter
+        # the caller used for the rest of the document.
+        def initialize(identifier_uri: nil, with_comments: nil,
+                       inclusive_namespaces: [], context: nil, **_unused)
+          @identifier_uri = identifier_uri
+          @with_comments = with_comments.nil? ? uri_has_comments?(identifier_uri) : with_comments
+          @inclusive_namespaces = inclusive_namespaces || []
+          @context = context
+        end
+
+        def canonicalize(node)
+          engine.canonicalize(
+            node,
+            with_comments: @with_comments,
+            inclusive_namespaces: @inclusive_namespaces,
+          )
+        end
+
+        # Adapt to the transform interface (spec §6.6.1). Octet-stream
+        # input is parsed using the same Moxml::Context the caller used;
+        # this preserves the byte-exact invariant across adapters.
+        def transform(input)
+          return canonicalize(input) if input.is_a?(::Moxml::Node)
+
+          if context.nil?
+            raise TransformError,
+                  "canonicalization transform requires a context to parse " \
+                  "octet-stream input; none was provided"
+          end
+
+          parsed = context.parse(input.to_s)
+          canonicalize(parsed.root)
+        end
+
+        private
+
+        def uri_has_comments?(uri)
+          return false if uri.nil?
+
+          uri.end_with?("#WithComments")
+        end
+
+        def engine
+          raise NotImplementedError,
+                "#{self.class} must implement #engine"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/digest_base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # Base class for message digest algorithms (SHA family).
+      #
+      # Subclasses MUST declare:
+      #   - `identifier "http://..."` to register
+      #   - either `digest_bits N` and `openssl_digest_name "SHA256"` etc.,
+      #     OR override `#compute_digest`.
+      class DigestBase
+        class << self
+          attr_reader :identifier_uri, :digest_size_bits
+
+          def identifier(uri)
+            @identifier_uri = uri
+            Algorithms.register(:digest, uri, self)
+          end
+
+          def digest_bits(bits)
+            @digest_size_bits = bits
+          end
+
+          def openssl_digest_name(name)
+            define_method(:compute_digest) do |data|
+              OpenSSL::Digest.digest(name, data)
+            end
+          end
+        end
+
+        def digest(data)
+          compute_digest(data.to_s)
+        end
+
+        def digest_base64(data)
+          Base64.strict_encode64(digest(data))
+        end
+
+        def compute_digest(_data)
+          raise NotImplementedError,
+                "#{self.class} must implement #compute_digest " \
+                "or declare openssl_digest_name"
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/dsa_sha.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # DSA signature methods per FIPS 186-3.
+      #
+      # Two URIs:
+      #   - SHA1 (1024-bit, q=160): wire format r‖s with 20-byte halves
+      #   - SHA256 (2048-bit, q=256): wire format r‖s with N-byte halves
+      #     where N = byte length of q (32 for SHA-256 case)
+      #
+      # OpenSSL returns DER; we convert to raw r‖s.
+      class DsaSha < SignatureMethodBase
+        PAIRINGS = {
+          "http://www.w3.org/2000/09/xmldsig#dsa-sha1" => "SHA1",
+          "http://www.w3.org/2009/xmldsig11#dsa-sha256" => "SHA256",
+        }.freeze
+
+        PAIRINGS.each_key { |uri| identifier uri }
+
+        def initialize(identifier_uri:, parameters: nil)
+          super(nil)
+          @identifier_uri = identifier_uri
+          @parameters = parameters
+        end
+
+        def compute_signature(data, key)
+          dsa = coerce_signing_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          der_signature = dsa.sign(digest_name, data)
+          der_to_raw(der_signature, coordinate_bytes_for(dsa))
+        end
+
+        def verify_signature(data, key, signature)
+          dsa = coerce_verify_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          n_bytes = coordinate_bytes_for(dsa)
+          der_signature = raw_to_der(signature, n_bytes)
+          dsa.verify(digest_name, der_signature, data)
+        rescue ArgumentError
+          false
+        end
+
+        private
+
+        def coerce_signing_key(key)
+          case key
+          when OpenSSL::PKey::DSA
+            key
+          else
+            raise SignatureKeyError,
+                  "DSA signature method requires OpenSSL::PKey::DSA, " \
+                  "got #{key.class}"
+          end
+        end
+
+        def coerce_verify_key(key)
+          coerce_signing_key(key)
+        end
+
+        def coordinate_bytes_for(dsa)
+          # q is the subgroup order. byte length of q.
+          q_bits = dsa.q.num_bits
+          (q_bits + 7) / 8
+        end
+
+        def der_to_raw(der, n_bytes)
+          seq = OpenSSL::ASN1.decode(der)
+          r = seq.value[0].value
+          s = seq.value[1].value
+          i2osp(r, n_bytes) + i2osp(s, n_bytes)
+        end
+
+        def raw_to_der(raw, n_bytes)
+          raise ArgumentError, "raw signature has wrong size" if raw.bytesize != (2 * n_bytes)
+
+          r = raw.byteslice(0, n_bytes)
+          s = raw.byteslice(n_bytes, n_bytes)
+          seq = OpenSSL::ASN1::Sequence.new([
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(r)),
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(s)),
+                                            ])
+          seq.to_der
+        end
+
+        def i2osp(value, length)
+          n = value.to_i
+          raise ArgumentError, "I2OSP: integer too large" if n >= (1 << (8 * length))
+
+          bytes = Array.new(length, 0)
+          (length - 1).downto(0) do |i|
+            bytes[i] = n & 0xff
+            n >>= 8
+          end
+          bytes.pack("C*")
+        end
+
+        def asn1_integer_value(octets)
+          octets.bytes.reduce(0) { |acc, byte| (acc << 8) | byte }
+        end
+      end
+    end
+  end
+end

data/lib/moxml/signature/algorithms/ecdsa_sha.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Moxml
+  module Signature
+    module Algorithms
+      # ECDSA signature methods per FIPS 186-3, bound to a digest.
+      #
+      # Spec §6.4.3 requires support for ECDSAwithSHA256 over the P-256
+      # curve. Recommended: P-384, P-521.
+      #
+      # The wire format is base64(I2OSP(r, n_bytes) || I2OSP(s, n_bytes))
+      # where n_bytes is the byte length of the base point order
+      # (32 for P-256, 48 for P-384, 66 for P-521).
+      #
+      # OpenSSL returns a DER-encoded ASN.1 sequence of (r, s). We convert
+      # to the raw r||s form on sign, and back from raw to DER on verify.
+      class EcdsaSha < SignatureMethodBase
+        PAIRINGS = {
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1" => "SHA1",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha224" => "SHA224",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256" => "SHA256",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384" => "SHA384",
+          "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512" => "SHA512",
+        }.freeze
+
+        # Map OpenSSL curve name → byte length of base point order.
+        CURVE_ORDER_BYTES = {
+          "prime256v1" => 32,   # P-256
+          "secp384r1" => 48,    # P-384
+          "secp521r1" => 66,    # P-521 (ceil(521/8) = 66)
+        }.freeze
+
+        PAIRINGS.each_key { |uri| identifier uri }
+
+        def initialize(identifier_uri:, parameters: nil)
+          super(nil)
+          @identifier_uri = identifier_uri
+          @parameters = parameters
+        end
+
+        def compute_signature(data, key)
+          ec_key = coerce_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          der_signature = ec_key.sign(digest_name, data)
+          der_to_raw(der_signature, coordinate_bytes_for(ec_key))
+        end
+
+        def verify_signature(data, key, signature)
+          ec_key = coerce_key(key)
+          digest_name = self.class::PAIRINGS.fetch(@identifier_uri)
+          n_bytes = coordinate_bytes_for(ec_key)
+          der_signature = raw_to_der(signature, n_bytes)
+          ec_key.verify(digest_name, der_signature, data)
+        rescue ArgumentError
+          false
+        end
+
+        private
+
+        def coerce_key(key)
+          case key
+          when OpenSSL::PKey::EC then key
+          when OpenSSL::PKey::EC::Point
+            raise SignatureKeyError,
+                  "ECDSA requires an EC key, not a bare Point"
+          else
+            raise SignatureKeyError,
+                  "ECDSA signature method requires OpenSSL::PKey::EC, " \
+                  "got #{key.class}"
+          end
+        end
+
+        def coordinate_bytes_for(ec_key)
+          curve_name = ec_key.group.curve_name
+          self.class::CURVE_ORDER_BYTES.fetch(curve_name) do
+            raise SignatureError,
+                  "ECDSA curve #{curve_name.inspect} not supported; " \
+                  "add it to EcdsaSha::CURVE_ORDER_BYTES"
+          end
+        end
+
+        # Convert ASN.1 DER sequence of two INTEGERs to raw r‖s octets.
+        def der_to_raw(der, n_bytes)
+          seq = OpenSSL::ASN1.decode(der)
+          r = seq.value[0].value
+          s = seq.value[1].value
+          i2osp(r, n_bytes) + i2osp(s, n_bytes)
+        end
+
+        # Convert raw r‖s octets back to ASN.1 DER.
+        def raw_to_der(raw, n_bytes)
+          raise ArgumentError, "raw signature has wrong size" if raw.bytesize != (2 * n_bytes)
+
+          r = raw.byteslice(0, n_bytes)
+          s = raw.byteslice(n_bytes, n_bytes)
+          seq = OpenSSL::ASN1::Sequence.new([
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(r)),
+                                              OpenSSL::ASN1::Integer.new(asn1_integer_value(s)),
+                                            ])
+          seq.to_der
+        end
+
+        # Integer to octet stream (I2OSP), minimal length parameter.
+        def i2osp(value, length)
+          n = value.to_i
+          raise ArgumentError, "I2OSP: integer too large" if n >= (1 << (8 * length))
+
+          bytes = Array.new(length, 0)
+          (length - 1).downto(0) do |i|
+            bytes[i] = n & 0xff
+            n >>= 8
+          end
+          bytes.pack("C*")
+        end
+
+        # Interpret an octet string as a positive integer (OS2IP).
+        def asn1_integer_value(octets)
+          octets.bytes.reduce(0) { |acc, byte| (acc << 8) | byte }
+        end
+      end
+    end
+  end
+end