moxml 0.1.25 → 0.1.26

data/lib/moxml/signature/reference_resolver.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Translates a Reference URI to a node (subtree) or octet string ready
+    # for the transform pipeline.
+    #
+    # Only same-document references and bare-octet inputs are handled in
+    # this tier. External URI dereferencing is documented in
+    # TODO.complete/11.
+    class ReferenceResolver
+      attr_reader :context, :document
+
+      def initialize(context:, document:)
+        @context = context
+        @document = document
+      end
+
+      # Returns:
+      #   - Moxml::Node for same-document references (subtree apex)
+      #   - String (octets) for octet inputs
+      def resolve(uri)
+        case uri.to_s
+        when ""
+          document.root
+        when /\A#/
+          resolve_fragment(uri[1..])
+        else
+          uri.to_s
+        end
+      end
+
+      private
+
+      def resolve_fragment(fragment)
+        case fragment
+        when /\Axpointer\(\/\)\z/
+          document.root
+        when /\Axpointer\(id\(['"]([^'"]+)['"]\)\)\z/
+          find_by_id(::Regexp.last_match(1))
+        else
+          find_by_id(fragment)
+        end
+      end
+
+      def find_by_id(id)
+        candidate = search_by_xml_id(id) || search_by_attribute_id(id)
+        unless candidate
+          raise MalformedSignatureError.new(
+            "Reference URI ##{id.inspect} does not resolve to any element",
+          )
+        end
+        candidate
+      end
+
+      def search_by_xml_id(id)
+        result = document.at_xpath("//*[@xml:id='#{xpath_escape(id)}']")
+        return nil unless result
+        return nil unless result.is_a?(::Moxml::Element)
+
+        result
+      end
+
+      def search_by_attribute_id(id)
+        matches = document
+          .xpath("//*[@Id='#{xpath_escape(id)}'] | " \
+                 "//*[@ID='#{xpath_escape(id)}']")
+          .grep(::Moxml::Element)
+        return nil if matches.empty?
+
+        matches.first
+      end
+
+      def xpath_escape(value)
+        value.to_s.gsub("'", "''")
+      end
+    end
+  end
+end

data/lib/moxml/signature/reference_result.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Per-reference digest comparison result. `valid?` is true iff the
+    # freshly-computed digest matches the expected DigestValue.
+    class ReferenceResult
+      attr_reader :uri, :digest_method, :expected, :computed
+
+      def initialize(uri:, digest_method:, expected:, computed:)
+        @uri = uri
+        @digest_method = digest_method
+        @expected = expected
+        @computed = computed
+      end
+
+      def valid?
+        expected == computed
+      end
+    end
+  end
+end

data/lib/moxml/signature/serializer.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Moxml
+  module Signature
+    # Translates a Model::Signature into a Moxml::Document.
+    #
+    # All XML construction goes through moxml primitives
+    # (create_element, []=, add_child, create_text). No string templates,
+    # no manual attribute escaping — moxml handles entity encoding
+    # correctly per the XML spec.
+    class Serializer
+      DS_PREFIX = "ds"
+
+      attr_reader :context
+
+      def initialize(context:)
+        @context = context
+      end
+
+      def serialize(signature)
+        doc = context.create_document
+        root = create_namespaced_element("Signature", doc)
+        root["Id"] = signature.id if signature.id
+        doc.root = root
+
+        if signature.signed_info
+          root.add_child(build_signed_info(signature.signed_info, doc))
+        end
+        if signature.signature_value
+          root.add_child(build_signature_value(signature.signature_value, doc))
+        end
+        if signature.key_info
+          root.add_child(build_key_info(signature.key_info, doc))
+        end
+        signature.objects.each do |obj|
+          root.add_child(build_object(obj, doc))
+        end
+
+        doc
+      end
+
+      # Produces a standalone ds:SignedInfo document. Used by the Signer
+      # when canonicalizing SignedInfo in isolation.
+      def serialize_signed_info(signed_info)
+        doc = context.create_document
+        root = create_namespaced_element("SignedInfo", doc)
+        root["Id"] = signed_info.id if signed_info.id
+        doc.root = root
+        populate_signed_info(root, signed_info, doc)
+        doc
+      end
+
+      private
+
+      def build_signed_info(signed_info, doc)
+        el = create_namespaced_element("SignedInfo", doc)
+        el["Id"] = signed_info.id if signed_info.id
+        populate_signed_info(el, signed_info, doc)
+        el
+      end
+
+      def populate_signed_info(root, signed_info, doc)
+        if signed_info.canonicalization_method
+          root.add_child(
+            build_algorithm_method("CanonicalizationMethod",
+                                   signed_info.canonicalization_method, doc),
+          )
+        end
+        if signed_info.signature_method
+          root.add_child(
+            build_algorithm_method("SignatureMethod",
+                                   signed_info.signature_method, doc),
+          )
+        end
+        signed_info.references.each do |ref|
+          root.add_child(build_reference(ref, doc))
+        end
+      end
+
+      def build_algorithm_method(name, method, doc)
+        el = create_namespaced_element(name, doc)
+        el["Algorithm"] = method.algorithm
+        if method.parameters.is_a?(Hash) && method.parameters[:hmac_output_length]
+          len = create_namespaced_element("HMACOutputLength", doc)
+          len.add_child(doc.create_text(method.parameters[:hmac_output_length].to_s))
+          el.add_child(len)
+        end
+        el
+      end
+
+      def build_reference(reference, doc)
+        el = create_namespaced_element("Reference", doc)
+        el["Id"] = reference.id if reference.id
+        el["URI"] = reference.uri if reference.uri
+        el["Type"] = reference.type if reference.type
+
+        if reference.transforms && !reference.transforms.empty?
+          tf = create_namespaced_element("Transforms", doc)
+          reference.transforms.each do |transform|
+            tr = create_namespaced_element("Transform", doc)
+            tr["Algorithm"] = transform.algorithm
+            tf.add_child(tr)
+          end
+          el.add_child(tf)
+        end
+
+        if reference.digest_method
+          dm = create_namespaced_element("DigestMethod", doc)
+          dm["Algorithm"] = reference.digest_method.algorithm
+          el.add_child(dm)
+        end
+
+        dv = create_namespaced_element("DigestValue", doc)
+        dv.add_child(doc.create_text(reference.digest_value || ""))
+        el.add_child(dv)
+        el
+      end
+
+      def build_signature_value(signature_value, doc)
+        el = create_namespaced_element("SignatureValue", doc)
+        el["Id"] = signature_value.id if signature_value.id
+        if signature_value.value
+          el.add_child(doc.create_text(Base64.strict_encode64(signature_value.value)))
+        end
+        el
+      end
+
+      def build_key_info(key_info, doc)
+        el = create_namespaced_element("KeyInfo", doc)
+        el["Id"] = key_info.id if key_info.id
+        if key_info.key_name
+          kn = create_namespaced_element("KeyName", doc)
+          kn.add_child(doc.create_text(key_info.key_name))
+          el.add_child(kn)
+        end
+        key_info.raw_elements.each { |raw| el.add_child(raw.dup) }
+        el
+      end
+
+      def build_object(obj, doc)
+        el = create_namespaced_element("Object", doc)
+        el["Id"] = obj.id if obj.id
+        el["MimeType"] = obj.mime_type if obj.mime_type
+        el["Encoding"] = obj.encoding if obj.encoding
+        # Payload content (Manifest, SignatureProperties, XAdES
+        # QualifyingProperties) comes in later tiers.
+        el
+      end
+
+      # Create an element in the xmldsig# namespace with the conventional
+      # `ds` prefix. The namespace declaration is added once on the
+      # element itself; descendants inherit it.
+      def create_namespaced_element(local_name, doc)
+        el = doc.create_element(local_name)
+        el.add_namespace(DS_PREFIX, DSIG_NS)
+        el.namespace = { DS_PREFIX => DSIG_NS }
+        el
+      end
+    end
+  end
+end

data/lib/moxml/signature/signer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Reference generation + SignatureValue computation per spec §3.1.
+    #
+    # Flow:
+    #   1. For each Reference in signed_info.references:
+    #      a. Resolve URI (same-document or octet).
+    #      b. Apply each Transform in order.
+    #      c. Compute digest via DigestMethod.
+    #      d. Store base64 digest on Reference#digest_value.
+    #   2. Serialize SignedInfo.
+    #   3. Canonicalize per CanonicalizationMethod.
+    #   4. Sign via SignatureMethod#sign(canonical_octets, key).
+    #   5. Set signature.signature_value.
+    class Signer
+      attr_reader :context, :signature, :document, :key
+
+      def initialize(context:, signature:, document:, key:)
+        @context = context
+        @signature = signature
+        @document = document
+        @key = key
+      end
+
+      def sign
+        Algorithms.load_builtins!
+
+        signature.signed_info.references.each do |ref|
+          digest = compute_reference_digest(ref)
+          ref.digest_value = digest
+        end
+
+        signature.signature_value = Model::SignatureValue.new(
+          value: compute_signature_value,
+        )
+        signature
+      end
+
+      private
+
+      def compute_reference_digest(reference)
+        resolver = ReferenceResolver.new(context: context, document: document)
+        input = resolver.resolve(reference.uri)
+        pipeline = TransformPipeline.new(context: context, signature_element: nil)
+        transformed = pipeline.apply(input, reference.transforms)
+        canonical = pipeline.to_octets(transformed, reference)
+        digest_algo = Algorithms.lookup(:digest, reference.digest_method.algorithm).new
+        digest_algo.digest_base64(canonical)
+      end
+
+      def compute_signature_value
+        signed_info = signature.signed_info
+        serializer = Serializer.new(context: context)
+        signed_info_doc = serializer.serialize_signed_info(signed_info)
+
+        c14n_uri = signed_info.canonicalization_method.algorithm
+        c14n_klass = Algorithms.lookup(:canonicalization, c14n_uri)
+        c14n = c14n_klass.new(identifier_uri: c14n_uri)
+        canonical_octets = c14n.canonicalize(signed_info_doc.root)
+
+        sm_uri = signed_info.signature_method.algorithm
+        sm_klass = Algorithms.lookup(:signature_method, sm_uri)
+        sm = sm_klass.new(
+          identifier_uri: sm_uri,
+          parameters: signed_info.signature_method.parameters,
+        )
+        sm.sign(canonical_octets, key)
+      end
+    end
+  end
+end

data/lib/moxml/signature/single_verification_result.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Verification outcome for a single Signature element. Carries the
+    # cryptographic-result boolean, per-reference results, and (when
+    # applicable) the error that caused failure.
+    class SingleVerificationResult
+      attr_reader :signature_id, :references, :error
+
+      def initialize(signature_id:, signature_valid:, references:, error: nil)
+        @signature_id = signature_id
+        @signature_valid = signature_valid
+        @references = references
+        @error = error
+      end
+
+      def signature_valid?
+        @signature_valid
+      end
+
+      def valid?
+        @signature_valid && references.all?(&:valid?)
+      end
+
+      def failing_references
+        references.reject(&:valid?)
+      end
+    end
+  end
+end

data/lib/moxml/signature/transform_pipeline.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Shared transform-pipeline logic used by both Signer (signing flow,
+    # signature_element: nil) and Verifier (verification flow, with the
+    # containing Signature element so the Enveloped Signature transform
+    # can remove it from the digest input).
+    #
+    # Each Transform in the chain is looked up via Algorithms.lookup(:transform, uri),
+    # with a fallback to Algorithms.lookup(:canonicalization, uri) per
+    # spec §6.6.1 (any canonicalization algorithm can be used as a transform).
+    #
+    # Type coercion matches spec §4.4.3.2 reference processing model:
+    #   - octets → nodeset: parse as XML
+    #   - nodeset → octets: apply inclusive C14N 1.0
+    class TransformPipeline
+      attr_reader :context, :signature_element
+
+      def initialize(context:, signature_element: nil)
+        @context = context
+        @signature_element = signature_element
+      end
+
+      def apply(input, transforms_model)
+        current = input
+        current_type = type_of(current)
+        transforms = transforms_from(transforms_model)
+
+        transforms.each do |transform_model|
+          algo_class = lookup(transform_model.algorithm)
+          transform = algo_class.new(
+            parameters: transform_model.parameters,
+            context: context,
+            signature_element: signature_element,
+          )
+          current_type, current = coerce(current, current_type,
+                                         algo_class.input_type)
+          current = transform.transform(current)
+          current_type = algo_class.output_type
+        end
+
+        current
+      end
+
+      # Final step: convert the pipeline output (which may still be a node)
+      # to octets suitable for digesting. Uses inclusive C14N 1.0 as the
+      # default mapping per spec §4.4.3.2.
+      def to_octets(value, reference = nil)
+        return value if value.is_a?(String)
+
+        c14n_uri = canonicalization_from(reference) || DEFAULT_OCTET_C14N
+        klass = Algorithms.lookup(:canonicalization, c14n_uri)
+        klass.new(identifier_uri: c14n_uri).canonicalize(value)
+      end
+
+      DEFAULT_OCTET_C14N = "http://www.w3.org/TR/2001/REC-xml-c14n-20010315"
+
+      private_constant :DEFAULT_OCTET_C14N
+
+      private
+
+      def transforms_from(transforms_model)
+        return [] unless transforms_model
+
+        transforms_model.transforms
+      end
+
+      def lookup(uri)
+        Algorithms.lookup(:transform, uri)
+      rescue UnknownAlgorithm
+        Algorithms.lookup(:canonicalization, uri)
+      end
+
+      def type_of(value)
+        case value
+        when ::Moxml::Node, Array then :nodeset
+        else :octets
+        end
+      end
+
+      def coerce(input, from, to)
+        return [to, input] if from == to
+
+        case [from, to]
+        when %i[octets nodeset]
+          parsed = context.parse(input.to_s)
+          [:nodeset, parsed.root]
+        when %i[nodeset octets]
+          octets = C14n::Inclusive10.new.canonicalize(input)
+          [:octets, octets]
+        else
+          raise TransformError, "cannot coerce #{from} to #{to}"
+        end
+      end
+
+      def canonicalization_from(reference)
+        return nil unless reference&.transforms
+
+        reference.transforms.transforms.reverse_each.find do |t|
+          Algorithms.registered?(:canonicalization, t.algorithm)
+        end&.algorithm
+      end
+    end
+  end
+end

data/lib/moxml/signature/verification_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Aggregated verification result for a document. A document may
+    # contain multiple Signature elements; this result wraps them all.
+    class VerificationResult
+      attr_reader :results
+
+      def initialize(results:)
+        @results = results
+      end
+
+      def valid?
+        results.all?(&:valid?)
+      end
+
+      def signature_count
+        results.size
+      end
+
+      def failing
+        results.reject(&:valid?)
+      end
+    end
+  end
+end

data/lib/moxml/signature/verifier.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Signature
+    # Core Validation per spec §3.2, with the safe ordering prescribed by
+    # Best Practice 1: verify SignatureValue BEFORE running any reference
+    # transforms (which could be hostile).
+    class Verifier
+      attr_reader :context, :document, :key, :key_map
+
+      def initialize(context:, document:, key: nil, key_map: {}, **_options)
+        @context = context
+        @document = document
+        @key = key
+        @key_map = key_map || {}
+      end
+
+      def verify
+        Algorithms.load_builtins!
+        signatures = find_signatures
+
+        results = signatures.map { |sig_elem| verify_one(sig_elem) }
+        VerificationResult.new(results: results)
+      end
+
+      private
+
+      def find_signatures
+        document.xpath("//ds:Signature", "ds" => DSIG_NS)
+          .grep(::Moxml::Element)
+      end
+
+      def verify_one(signature_element)
+        signature = Parser.new(context: context).parse(signature_element)
+        signature_value_ok, error = verify_signature_value(signature, signature_element)
+        reference_results = if signature_value_ok
+                              verify_references(signature, signature_element)
+                            else
+                              []
+                            end
+
+        SingleVerificationResult.new(
+          signature_id: signature.id,
+          signature_valid: signature_value_ok,
+          references: reference_results,
+          error: error,
+        )
+      end
+
+      # Returns [Boolean, ErrorOrNil] so the caller can attach the error
+      # to the result for debugging. The error is never raised — Best
+      # Practice 1 says authenticate first; surfacing why auth failed is
+      # an application concern, not a panic.
+      def verify_signature_value(signature, signature_element)
+        return [false, nil] if signature.signature_value.nil?
+        return [false, nil] if signature.signature_value.value.nil?
+
+        signed_info_elem = signature_element.at_xpath(
+          "./ds:SignedInfo", "ds" => DSIG_NS
+        )
+        return [false, nil] if signed_info_elem.nil?
+
+        c14n_uri = signature.signed_info.canonicalization_method&.algorithm
+        return [false, nil] if c14n_uri.nil?
+
+        canonical = canonicalize_signed_info(c14n_uri, signed_info_elem)
+        sm_uri = signature.signed_info.signature_method.algorithm
+        sm = Algorithms.lookup(:signature_method, sm_uri).new(
+          identifier_uri: sm_uri,
+          parameters: signature.signed_info.signature_method.parameters,
+        )
+        verification_key = resolve_key(signature)
+        return [false, nil] if verification_key.nil?
+
+        ok = sm.verify(canonical, verification_key, signature.signature_value.value)
+        [ok, nil]
+      rescue VerificationError, UnknownAlgorithm => e
+        [false, e]
+      end
+
+      # Canonicalize the original SignedInfo element as it appears in the
+      # document. Re-serializing the parsed model would change namespace
+      # prefixes (e.g. SignedInfo → ds:SignedInfo) and break byte-exact
+      # verification.
+      def canonicalize_signed_info(c14n_uri, signed_info_elem)
+        Algorithms.lookup(:canonicalization, c14n_uri)
+          .new(identifier_uri: c14n_uri)
+          .canonicalize(signed_info_elem)
+      end
+
+      def resolve_key(signature)
+        return key if key
+        return nil unless signature.key_info
+
+        KeyExtractor.new(key_map: key_map).extract(signature.key_info)
+      end
+
+      def verify_references(signature, signature_element)
+        signature.signed_info.references.map do |ref|
+          verify_reference(ref, signature_element)
+        end
+      end
+
+      def verify_reference(reference, signature_element)
+        resolver = ReferenceResolver.new(context: context, document: document)
+        input = resolver.resolve(reference.uri)
+        pipeline = TransformPipeline.new(
+          context: context,
+          signature_element: signature_element,
+        )
+        transformed = pipeline.apply(input, reference.transforms)
+        canonical = pipeline.to_octets(transformed, reference)
+
+        digest_algo = Algorithms.lookup(
+          :digest, reference.digest_method.algorithm
+        ).new
+        computed = digest_algo.digest_base64(canonical)
+        expected = (reference.digest_value || "").strip
+
+        ReferenceResult.new(
+          uri: reference.uri,
+          digest_method: reference.digest_method.algorithm,
+          expected: expected,
+          computed: computed,
+        )
+      end
+    end
+  end
+end