moxml 0.5.117 → 0.5.118

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e55a5915424bfa9e3977ed2d9d5207502c42c48eb8b1f48de5406017d8e7cfa5
-  data.tar.gz: '01315569d92e95d97e8d466a20da3e26be9db15d876c1062e45d739179399273'
+  metadata.gz: 60a08183c240700f3cde7675fb3428b47340f0dba11e723309c5afb09aa988bb
+  data.tar.gz: 42e790020feb09861560717610f16f6e8996fb7435689eae1f989a05cb90ab0a
 SHA512:
-  metadata.gz: 5138b1d6a1a60d5b0a6f1a6517599a6b6d05b34cf14266309a0cc9cc3082e332cb62c8cd76477363853beb7b1ae8d7ef6b3833bf17e07ee950ce7f71a68e4bdb
-  data.tar.gz: 9b6ba4c742f717ad843eb1bdd08d58957eea374b33988b11dac6d9ece9e8a199739198057c09621c97af94462b329049916f3f0283612941adca7ac199bb73ba
+  metadata.gz: 4accde9025cb43cbe09661c68be8d31047f39339f035f2a80d895e3e8b03a786b7b0d492880a39d0f2f4b57b0209002e62cc79c7c71b3c4373091ceaac4481ee
+  data.tar.gz: 203fb7db9d8e46a7a028218dda254367cc0cb1c8ac096b516102937874ba0f14b2bbe1f06cfcb413334567722d31f94f4e00fe2850e2c3a20f1334a3bfce5f70

data/Gemfile

@@ -9,7 +9,7 @@ gemspec
 gem "benchmark"
 gem "benchmark-ips"
 gem "get_process_mem"
-gem "leptris", "~> 1.9.280"
+gem "leptris", "~> 1.9.320"
 gem "libxml-ruby", ">= 5.0"
 gem "nokogiri", "~> 1.18"
 gem "openssl", "~> 3.0"

data/README.adoc

@@ -119,7 +119,7 @@ carries the plan-ABI surface, the 1.9.290 XSLT-params and
 bulk-append faces, and the 1.9.292 engine deep-copy root install).
 |===
 
-NOTE: moxml's dev Gemfile pins `leptris ~> 1.9.174`, `nokogiri ~> 1.18`,
+NOTE: moxml's dev Gemfile pins `leptris ~> 1.9.320` (the tested pair; the gemspec itself has zero runtime dependencies). Consumers of the leptris adapter should run leptris 1.9.320+ — earlier engines carry silent wrong-answer plan-path defects (moxml#344); moxml gates degrade to the always-correct slower paths below it.
 `ox ~> 2.14`, `libxml-ruby >= 5.0`, and the vendored oga fork — the CI
 matrix tests exactly those floors.
 

data/docs/c14n/README.md

@@ -0,0 +1,39 @@
+# Canonicalization (C14N)
+
+Canonicalization is the load-bearing primitive for XML signature and a
+top-level moxml feature, sibling to `Moxml::XPath`, `Moxml::Builder`,
+and `Moxml::SAX`. Two documents that differ only in surface
+representation (whitespace, attribute order, namespace prefix choice)
+produce identical canonical bytes.
+
+## Pages
+
+- [Algorithms](algorithms.md) — Inclusive C14N 1.0/1.1 (canon-port) and
+  Exclusive C14N 1.0 (moxml-native), the data model, output invariants,
+  and adapter delegation.
+- [API](api.md) — the full public surface: canonicalize, exclusive,
+  subset, digests, and the comparison helper.
+- [Examples](examples.md) — patterns: whole-document, subset,
+  cross-adapter verification, digests.
+
+## Quick start
+
+```ruby
+# Canonical octets (inclusive C14N 1.0)
+Moxml::C14n.canonicalize(node_or_xml)
+
+# Exclusive C14N 1.0 (signatures over moved subdocuments)
+Moxml::C14n.canonicalize_exclusive(node_or_xml,
+                                   inclusive_namespaces: ["foo"])
+
+# Node-set subset canonicalization (same-document references)
+Moxml::C14n.canonicalize_subset(node_or_xml, "//signed")
+
+# Canonical comparison (testing, regression, signature debugging)
+Moxml::C14n.same_canonical_form?(left, right)
+```
+
+`node_or_xml` accepts a `Moxml::Node`, `Moxml::Document`, or XML
+`String`. Engines without a native canonicalizer take the pure-Ruby
+path — results are byte-identical across adapters, which is what keeps
+cross-adapter signature verification sound.

data/docs/c14n/algorithms.md

@@ -0,0 +1,65 @@
+# C14N algorithms
+
+## Inclusive C14N 1.0 / 1.1
+
+- W3C: <https://www.w3.org/TR/xml-c14n/>, <https://www.w3.org/TR/xml-c14n11/>
+- Implementation: **ported from `lutaml/canon`** (~1,200 lines)
+- Files: `lib/moxml/c14n/inclusive_10.rb`, `inclusive_11.rb`,
+  `data_model.rb`, `processor.rb`, `namespace_handler.rb`,
+  `attribute_handler.rb`, `xml_base_handler.rb`, `character_encoder.rb`,
+  `node.rb`, `nodes/*.rb`
+- "Attracts" ancestor context: at the apex, every in-scope namespace is
+  rendered, including those inherited from outside the canonicalization
+  subset.
+
+## Exclusive C14N 1.0
+
+- W3C: <https://www.w3.org/TR/xml-exc-c14n/>
+- Implementation: **moxml-native** (canon does not implement exclusive)
+- Files: `lib/moxml/c14n/exclusive.rb`, `writer.rb`, `namespace_context.rb`
+- "Repels" ancestor context: only namespaces visibly used by the apex
+  element's qualified name or attributes are rendered. Keeps signatures
+  valid when subdocuments move between XML contexts (e.g., into a SOAP
+  envelope).
+
+## Adapter delegation
+
+Adapters whose engines ship a native canonicalizer delegate through a
+lazy byte-safety probe — the pure-Ruby path remains the fallback and
+the arbiter: all routes produce byte-identical output (pinned by
+`spec/moxml/c14n/adapter_delegation_spec.rb`).
+
+- **leptris**: engine-delegated inclusive C14N — an order of magnitude
+  faster than the Ruby path on large documents.
+- **nokogiri**: libxml2 native canonicalization.
+
+## Data model
+
+The canon-derived inclusive engines walk an intermediate data model
+(`Moxml::C14n::Nodes::*`) rather than the live `Moxml::Node` tree,
+because canonicalization needs:
+
+- **Node-set membership flags** for subset canonicalization (spec §3).
+- **Sorted namespace and attribute axes** per spec §2.3 / §2.4.
+- **xml:base fixup** per RFC 3986 with C14N 1.1 modifications.
+- **xml:\* inheritable attribute resolution** (xml:lang, xml:space)
+  from omitted ancestors.
+
+The data model is built from `Moxml::Node` via `Moxml::C14n::DataModel`.
+
+## Output invariants
+
+- UTF-8 encoded, no BOM
+- NFC characters preserved
+- Document-order traversal
+- Entity references: `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`
+- Attribute values: also escape `"`, tab, LF, CR
+- Empty elements expanded: `<foo/>` → `<foo></foo>`
+- Line endings normalized to LF (the parser already does this)
+
+## Cross-verification
+
+The libxmlsec1-produced fixtures in `spec/fixtures/xmldsig/` verify
+byte-exact against our C14N output — the implementation matches
+libxml2's C-based canonicalization for the cases the Ruby reference
+exercises.

data/docs/c14n/api.md

@@ -0,0 +1,62 @@
+# C14N API
+
+`node_or_xml` accepts a `Moxml::Node`, `Moxml::Document`, or XML
+`String` on every entry point.
+
+## Convenience methods
+
+```ruby
+# Inclusive C14N 1.0
+Moxml::C14n.canonicalize(node_or_xml, with_comments: false)
+
+# Exclusive C14N 1.0
+Moxml::C14n.canonicalize_exclusive(
+  node_or_xml,
+  with_comments: false,
+  inclusive_namespaces: [],  # InclusiveNamespacesPrefixList parameter
+)
+
+# Inclusive C14N 1.1
+Moxml::C14n.canonicalize_inclusive11(node_or_xml, with_comments: false)
+
+# Node-set subset canonicalization: only nodes matched by the XPath
+# render (position-path matching — see docs on enveloped signatures)
+Moxml::C14n.canonicalize_subset(node_or_xml, "//signed",
+                                with_comments: false)
+
+# Canonical comparison: do two inputs share one canonical form?
+# (inclusive C14N 1.0, comments dropped, on both sides)
+Moxml::C14n.same_canonical_form?(left, right)  # nodes or raw strings
+```
+
+All canonicalize methods return canonical UTF-8 octet strings.
+
+## Direct engine access
+
+Used by the signature algorithms:
+
+```ruby
+Moxml::C14n::Inclusive10.new.canonicalize(node, with_comments:,
+                                          inclusive_namespaces:)
+Moxml::C14n::Inclusive11.new.canonicalize(node, with_comments:,
+                                          inclusive_namespaces:)
+Moxml::C14n::Exclusive.new.canonicalize(node, with_comments:,
+                                        inclusive_namespaces:)
+```
+
+## Digests
+
+`Node#digest` (engine-delegated where available) computes the canonical
+digest of a subtree:
+
+```ruby
+node.digest                    # SHA-256 over inclusive C14N 1.0
+node.digest(drop_ws_text: true)
+```
+
+## Backward-compat escape helpers
+
+```ruby
+Moxml::C14n.escape_text("a & b < c > d")
+Moxml::C14n.escape_attribute(%(a"b\tc\nd))
+```

data/docs/c14n/examples.md

@@ -0,0 +1,47 @@
+# C14N examples
+
+## Whole-document canonicalization
+
+```ruby
+doc = Moxml.new.parse(xml)
+Moxml::C14n.canonicalize(doc)
+# => "<?xml version=\"1.0\"?>\n<a b=\"1\">text</a>\n"
+```
+
+## Subset canonicalization (enveloped signature shape)
+
+Only nodes matched by the XPath expression render — the same-document
+reference pattern:
+
+```ruby
+Moxml::C14n.canonicalize_subset(doc, "//ds:SignedInfo",
+                                { "ds" => "http://www.w3.org/2000/09/xmldsig#" })
+```
+
+## Canonical comparison
+
+Testing two documents for semantic equality — whitespace, attribute
+order, and prefix choice are eliminated before comparison:
+
+```ruby
+Moxml::C14n.same_canonical_form?(v1_document, v2_document)   # => true
+Moxml::C14n.same_canonical_form?(fixture_xml, output_string) # => true
+```
+
+## Cross-adapter verification
+
+A signature produced with one adapter must verify with another — the
+canonical bytes are byte-identical across adapters:
+
+```ruby
+%i[leptris nokogiri rexml ox libxml].map do |adapter|
+  Moxml.new(adapter).parse(xml).then { |d| Moxml::C14n.canonicalize(d) }
+end.uniq.size # => 1
+```
+
+## Digest of a subtree
+
+```ruby
+signed_element.digest
+# engine-delegated SHA-256 over the subtree's canonical form
+```

data/docs/signature/c14n.md

@@ -1,4 +1,4 @@
-# Canonicalization (C14N)
+# Canonicalization (C14N) in XML signature
 
 Canonicalization is the load-bearing primitive for XML signature.
 Two documents that differ only in surface representation (whitespace,
@@ -6,7 +6,9 @@ attribute order, namespace prefix choice) must produce identical
 canonical bytes — otherwise signatures won't verify.
 
 `Moxml::C14n` is a top-level moxml feature, sibling to `Moxml::XPath`,
-`Moxml::Builder`, and `Moxml::SAX`.
+`Moxml::Builder`, and `Moxml::SAX`. The full C14N documentation tree
+lives at [docs/c14n/](../c14n/README.md) — this page covers the
+signature-specific view.
 
 ## Algorithms
 
@@ -97,10 +99,10 @@ and it's much faster than pure Ruby. But:
 3. **Canon already had the mature pure-Ruby implementation.** Porting it
    was less work than building a hybrid adapter-delegated system.
 
-**Future work:** add an optional adapter-level C14N delegation. The
-Nokogiri adapter could expose `canonicalize(node, ...)` and the
-`Moxml::C14n` top-level method would delegate when available. This is
-documented in TODO.complete/19.
+**Shipped:** optional adapter-level C14N delegation — the Nokogiri
+(libxml2) and leptris (engine) adapters expose native canonicalization
+behind a lazy byte-safety probe, byte-identical with the pure-Ruby
+path (see [docs/c14n/algorithms.md](../c14n/algorithms.md#adapter-delegation)).
 
 ## Cross-verification
 

data/lib/moxml/adapter/leptris.rb

@@ -725,7 +725,16 @@ module Moxml
       # exactly the plan's shape, with no wrapper minting at all.
       # Marker-bearing documents stay on the generic path (the bulk
       # stream has no marker split).
-      NATIVE_PLAN_ROWS = true
+      # moxml#344: engines 1.9.314-1.9.319 mis-match on the plan
+      # path — child-row exact-URI ns_uri pointed into build
+      # buffers (rows vanish after GC, leptris#1585) and plain
+      # attribute rows did not leniently match namespace-qualified
+      # wire attributes (nil captures, leptris#1586). Both are
+      # SILENT wrong answers, so the gate names the fixed engine:
+      # below 1.9.320.0 the plan faces degrade to the
+      # always-correct generic wrapper walk.
+      NATIVE_PLAN_ROWS =
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.320.0")
 
       # leptris-ruby#272 (binding 1.9.201.1): Native.plan_structs —
       # the C struct executor behind Moxml::StructPlan. The floor
@@ -735,9 +744,12 @@ module Moxml
       # below the fix. The probe guards the version gate: a
       # numerically newer lockstep can publish without the face
       # (1.9.199.0 shipped without it), and the gate alone would
-      # NoMethodError.
+      # NoMethodError. Floor also carries moxml#344: 1.9.314-1.9.319
+      # mis-match on the plan path (leptris#1585/#1586, silent nil
+      # captures) — the struct executor degrades to the Ruby Plan
+      # fallback below the fix, same as the varargs-mint floor.
       NATIVE_PLAN_STRUCTS =
-        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.201.1") &&
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.320.0") &&
         (!defined?(::Leptris::XML::Native) ||
          ::Leptris::XML::Native.respond_to?(:plan_structs))
 
@@ -781,7 +793,7 @@ module Moxml
       end
 
       def self.plan_rows(native)
-        return nil unless NATIVE_READ_LAYER
+        return nil unless NATIVE_READ_LAYER && NATIVE_PLAN_ROWS
 
         doc = if native.is_a?(::Leptris::XML::Document)
                 native

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.117"
+  VERSION = "0.5.118"
 end

data/spec/moxml/plan_conformance_spec.rb

@@ -77,4 +77,28 @@ RSpec.describe "Moxml::Plan adapter conformance" do
       )
     end
   end
+
+  describe "plan-gate floors (moxml#344)" do
+    let(:gate_ctx) { Moxml.new(:leptris) }
+
+    it "arms both plan faces on engines carrying the #1585/#1586 fixes" do
+      skip "testing engine predates the floor" unless
+        Gem::Version.new(Leptris::VERSION) >= Gem::Version.new("1.9.320.0")
+
+      expect(Moxml::Adapter::Leptris::NATIVE_PLAN_ROWS).to be(true)
+      expect(Moxml::Adapter::Leptris::NATIVE_PLAN_STRUCTS).to be(true)
+    end
+
+    it "captures namespace-qualified wire attributes (leptris#1586)" do
+      skip "plan faces degraded below 1.9.320 (moxml#344)" unless
+        Moxml::Adapter::Leptris::NATIVE_PLAN_ROWS
+
+      plan = Moxml::Plan.new do
+        on("e") { |attrs| @captured = attrs }
+      end
+      plan.parse('<r xmlns:w="urn:w"><e w:name="Aptos"/></r>', gate_ctx)
+      captured = plan.instance_variable_get(:@captured)
+      expect(captured).to include("w:name" => "Aptos")
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.117
+  version: 0.5.118
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-07 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -89,6 +89,10 @@ files:
 - docs/_tutorials/index.adoc
 - docs/_tutorials/namespace-handling.adoc
 - docs/_tutorials/xpath-queries.adoc
+- docs/c14n/README.md
+- docs/c14n/algorithms.md
+- docs/c14n/api.md
+- docs/c14n/examples.md
 - docs/index.adoc
 - docs/signature/algorithms.md
 - docs/signature/architecture.md