moxml 0.1.25 → 0.1.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed30996109d8cfb8057f216677cba8ca3cd3856287c38b6a7edab3251ebb2064
-  data.tar.gz: f93d7c13863ef9d437e40403e4a48434ed1e1c5530ea2424cdeff710740243a0
+  metadata.gz: d829252809a02c146a09b8458ec5d9a297e5a31e91e6b04b6b6eda27a31e30a9
+  data.tar.gz: '09018d566262901ac5fe3fd864cd80e52dfe05f449e5b9e03054624044cab1af'
 SHA512:
-  metadata.gz: 9b09c144a268507bb02a16a4c6ba7caf6d1a2fa003718a6fa0960a8b68ba03a09584a66fb9475b1c23cd2d79071f1cc8c313200749f997d317aa90e61fba3811
-  data.tar.gz: 6389858a232d82faad5f6bbfd22d4828801c7a6d45a55a2a0f08d28c44647a588b52d2106649d408777453b571815b40c191f48c374cc49b648c58ad2be1e835
+  metadata.gz: 56cc005125bd3953a3e40f2867ef76f4bd2ea4823e3363904ff20330e67d62740ae26c444b10d6706d66d4c7b0f38ba4805e957cfbf6cb4cdf413a6480eefd03
+  data.tar.gz: 58ec645d3a117ecd8ad275705fc03a345da7b52485b8119e8e0c0ebb12611c36dc01a12600b4871db050a23c7ac93d04b77632499307b94b5f7bb6000ccf366b

data/.github/workflows/release.yml

@@ -13,6 +13,14 @@ on:
           Next release version. Possible values: x.y.z, major, minor, patch or pre|rc|etc
         required: true
         default: 'skip'
+      gated:
+        description: |
+          Defer rubygems publish to a separate repository_dispatch (do-release) run.
+          - false (default): bump + tag + publish in one step.
+          - true: bump + tag only; publish when do-release is triggered.
+        required: false
+        default: false
+        type: boolean
   repository_dispatch:
     types: [ do-release ]
 
@@ -21,6 +29,7 @@ jobs:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
+      gated: ${{ inputs.gated == true }}
     secrets:
       rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.GITHUB_TOKEN }}

data/README.adoc

@@ -559,6 +559,70 @@ ruby examples/api_client/api_client.rb
 See the link:examples/README.md[examples README] for complete documentation and
 learning paths.
 
+== XML Signature (Moxml::Signature)
+
+Moxml includes an XML-implementation-agnostic implementation of W3C XML
+Signature (xmldsig-core-1.1). Sign and verify documents with any moxml
+adapter; the canonicalization engine produces byte-exact output that
+cross-verifies with libxmlsec1.
+
+=== Quick start
+
+[source,ruby]
+----
+require "moxml"
+require "moxml/signature"
+require "openssl"
+
+ctx = Moxml.new(:nokogiri)
+key = OpenSSL::PKey::RSA.generate(2048)
+doc = ctx.parse("<doc><greeting>Hello, World!</greeting></doc>")
+
+# Sign
+signature = Moxml::Signature.sign(
+  context: ctx, document: doc, key: key,
+  signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+  canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+  digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+  reference_uri: "",
+  transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+)
+serialized = Moxml::Signature::Serializer.new(context: ctx).serialize(signature)
+doc.root.add_child(serialized.root)
+
+# Verify (auto-extracts key from KeyInfo if absent)
+result = Moxml::Signature.verify(context: ctx, document: doc, key: key)
+result.valid?  # => true
+----
+
+=== Supported algorithms
+
+Digests:: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512
+Signature methods:: RSA-PKCS1v1.5, HMAC, ECDSA (P-256/P-384/P-521), DSA
+Canonicalization:: Exclusive C14N 1.0, Inclusive C14N 1.0, Inclusive C14N 1.1
+Transforms:: base64, Enveloped Signature
+
+Adding a custom algorithm means declaring `identifier "http://..."` on a
+subclass — no edits to existing code. See
+link:docs/signature/algorithms.md[the algorithms doc].
+
+=== Canonicalization (Moxml::C14n)
+
+C14N is a top-level moxml feature (sibling to XPath, Builder, SAX).
+Inclusive C14N is ported from the sibling `canon` gem; Exclusive C14N
+is moxml-native. See link:docs/signature/c14n.md[the C14N doc].
+
+=== Documentation
+
+* link:docs/signature/architecture.md[Architecture]
+* link:docs/signature/algorithms.md[Algorithm registry]
+* link:docs/signature/c14n.md[Canonicalization]
+* link:docs/signature/flows.md[Signer and Verifier flows]
+* link:docs/signature/key-extraction.md[Key extraction] (TODO)
+* link:docs/signature/security.md[Security considerations]
+* link:docs/signature/quick-reference.md[Quick reference]
+* link:examples/signature/[Runnable examples]
+
 == Working with documents
 
 === Using the builder pattern

data/docs/signature/algorithms.md

@@ -0,0 +1,108 @@
+# Algorithm registry
+
+The `Moxml::Signature::Algorithms` module is the open-closed hub for
+all W3C XML Signature algorithms. Algorithms are identified by URI;
+the registry maps URI → class for each of four categories:
+
+| Category             | W3C spec section | Base class                                    |
+| -------------------- | ---------------- | --------------------------------------------- |
+| `:digest`            | §6.2             | `Algorithms::DigestBase`                      |
+| `:signature_method`  | §6.3, §6.4       | `Algorithms::SignatureMethodBase`             |
+| `:canonicalization`  | §6.5             | `Algorithms::CanonicalizationBase`            |
+| `:transform`         | §6.6             | `Algorithms::TransformBase`                   |
+
+## Built-in algorithms
+
+### Digests (§6.2)
+
+| URI                                                        | Class            |
+| ---------------------------------------------------------- | ---------------- |
+| `http://www.w3.org/2000/09/xmldsig#sha1`                   | `SHA1`           |
+| `http://www.w3.org/2001/04/xmldsig-more#sha224`            | `SHA224`         |
+| `http://www.w3.org/2001/04/xmlenc#sha256` (REQUIRED)       | `SHA256`         |
+| `http://www.w3.org/2001/04/xmldsig-more#sha384`            | `SHA384`         |
+| `http://www.w3.org/2001/04/xmlenc#sha512`                  | `SHA512`         |
+
+### Signature methods (§6.3, §6.4)
+
+| URI                                                        | Class            | Notes |
+| ---------------------------------------------------------- | ---------------- | ----- |
+| `…xmldsig#rsa-sha1`                                        | `RsaPkcs1Sha`    | Verification only (BP: SHA-1 discouraged) |
+| `…xmldsig-more#rsa-sha224`                                 | `RsaPkcs1Sha`    | |
+| `…xmldsig-more#rsa-sha256` (REQUIRED)                      | `RsaPkcs1Sha`    | |
+| `…xmldsig-more#rsa-sha384`                                 | `RsaPkcs1Sha`    | |
+| `…xmldsig-more#rsa-sha512`                                 | `RsaPkcs1Sha`    | |
+| `…xmldsig#hmac-sha1`                                       | `HmacSha`        | Truncation enforced per §4.4.2 |
+| `…xmldsig-more#hmac-sha224`                                | `HmacSha`        | |
+| `…xmldsig-more#hmac-sha256` (REQUIRED)                     | `HmacSha`        | |
+| `…xmldsig-more#hmac-sha384`                                | `HmacSha`        | |
+| `…xmldsig-more#hmac-sha512`                                | `HmacSha`        | |
+| `…xmldsig-more#ecdsa-sha1`                                 | `EcdsaSha`       | |
+| `…xmldsig-more#ecdsa-sha224`                               | `EcdsaSha`       | |
+| `…xmldsig-more#ecdsa-sha256` (REQUIRED)                    | `EcdsaSha`       | P-256/P-384/P-521 |
+| `…xmldsig-more#ecdsa-sha384`                               | `EcdsaSha`       | |
+| `…xmldsig-more#ecdsa-sha512`                               | `EcdsaSha`       | |
+| `…xmldsig#dsa-sha1`                                        | `DsaSha`         | |
+| `…xmldsig11#dsa-sha256`                                    | `DsaSha`         | |
+
+### Canonicalization (§6.5)
+
+| URI                                                        | Engine                       |
+| ---------------------------------------------------------- | ---------------------------- |
+| `http://www.w3.org/TR/2001/REC-xml-c14n-20010315`          | `Moxml::C14n::Inclusive10` (canon-ported) |
+| `…REC-xml-c14n-20010315#WithComments`                      | same, `with_comments: true`  |
+| `http://www.w3.org/2006/12/xml-c14n11`                     | `Moxml::C14n::Inclusive11`   |
+| `…xml-c14n11#WithComments`                                 | same, `with_comments: true`  |
+| `http://www.w3.org/2001/10/xml-exc-c14n#`                  | `Moxml::C14n::Exclusive` (moxml-native) |
+| `…xml-exc-c14n#WithComments`                               | same, `with_comments: true`  |
+
+### Transforms (§6.6)
+
+| URI                                                        | Class                          |
+| ---------------------------------------------------------- | ------------------------------ |
+| `http://www.w3.org/2000/09/xmldsig#base64`                 | `Base64Transform`              |
+| `http://www.w3.org/2000/09/xmldsig#enveloped-signature`    | `EnvelopedSignatureTransform`  |
+
+Canonicalization algorithms can also be used as transforms per §6.6.1.
+The `TransformPipeline` looks them up in the canonicalization registry
+as a fallback.
+
+## Adding a custom algorithm
+
+```ruby
+require "moxml/signature"
+
+module MyAlgo
+  class SHA3_256 < Moxml::Signature::Algorithms::DigestBase
+    identifier "http://www.w3.org/2007/xmldsig-more#sha3-256"
+
+    def compute_digest(data)
+      OpenSSL::Digest.digest("SHA3-256", data)
+    end
+  end
+end
+
+# Now the URI resolves:
+Moxml::Signature::Algorithms.lookup(
+  :digest,
+  "http://www.w3.org/2007/xmldsig-more#sha3-256",
+)
+# => MyAlgo::SHA3_256
+```
+
+The `identifier` declaration registers the class on load. No edits to
+existing code are required — pure OCP.
+
+## API
+
+```ruby
+Algorithms.lookup(:digest, uri)       # → class, raises UnknownAlgorithm
+Algorithms.registered?(:digest, uri)  # → bool
+Algorithms[:digest]                   # → { uri => class, ... }
+```
+
+## Lazy loading
+
+The registry autoloads built-in algorithm classes on first lookup
+(`load_builtins!` references each constant, triggering autoload).
+Custom algorithms register themselves on `require` of their file.

data/docs/signature/architecture.md

@@ -0,0 +1,148 @@
+# Moxml::Signature — Architecture
+
+## Where it lives
+
+`Moxml::Signature` is a sub-module of moxml that implements W3C XML
+Signature (xmldsig-core-1.1). It is **XML implementation agnostic** —
+every XML operation flows through `Moxml::Document` / `Moxml::Element`,
+so the same signature code works whether you parse with Nokogiri, Oga,
+REXML, Ox, or LibXML.
+
+C14N itself is a top-level `Moxml::C14n` feature, sibling to
+`Moxml::XPath`, `Moxml::Builder`, and `Moxml::SAX`. Signature uses it;
+so can any other consumer (e.g., the sibling `canon` gem).
+
+## Module layout
+
+```
+lib/moxml.rb                              # top-level, autoloads Signature and C14n
+lib/moxml/signature.rb                    # Signature namespace + .sign/.verify entry points
+
+lib/moxml/signature/errors.rb             # error hierarchy
+lib/moxml/signature/algorithms.rb         # OCP registry hub
+lib/moxml/signature/algorithms/           # concrete algorithms (digests, sig methods, transforms)
+lib/moxml/signature/model/                # PORO models
+lib/moxml/signature/serializer.rb         # model → XML (uses moxml primitives)
+lib/moxml/signature/parser.rb             # XML → model
+lib/moxml/signature/reference_resolver.rb # Reference URI → node-set / octets
+lib/moxml/signature/transform_pipeline.rb # shared transform chain (DRY)
+lib/moxml/signature/signer.rb             # spec §3.1 signing flow
+lib/moxml/signature/verifier.rb           # spec §3.2 verification flow
+lib/moxml/signature/key_extractor.rb      # X509 / RSA / DSA / EC / KeyName → OpenSSL key
+lib/moxml/signature/verification_result.rb
+lib/moxml/signature/single_verification_result.rb
+lib/moxml/signature/reference_result.rb
+
+lib/moxml/c14n.rb                         # top-level C14n namespace
+lib/moxml/c14n/                           # canon-ported engine + moxml-native Exclusive
+```
+
+## Layering
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ Application code                                                 │
+│   Moxml::Signature.sign / .verify                                │
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+┌──────────────────────────────────────────────────────────────────┐
+│ Orchestration:  Signer, Verifier, TransformPipeline, KeyExtractor│
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+┌──────────────────────┐   ┌──────────────────────────────────────┐
+│ Algorithms (OCP hub) │   │ Models: Signature, SignedInfo, etc.  │
+└──────────────────────┘   └──────────────────────────────────────┘
+                                ↕
+┌──────────────────────────────────────────────────────────────────┐
+│ Moxml::C14n (canon-ported Inclusive + moxml-native Exclusive)    │
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+┌──────────────────────────────────────────────────────────────────┐
+│ Moxml::Document / Element / Text / Namespace / Attribute          │
+│   (adapter-agnostic — Nokogiri, Oga, REXML, Ox, LibXML)           │
+└──────────────────────────────────────────────────────────────────┘
+                                ↕
+                          OpenSSL (crypto)
+```
+
+## Core design decisions
+
+### 1. Algorithm registry as the OCP hub
+
+Every W3C algorithm (digest, signature method, canonicalization,
+transform) is identified by URI. The `Moxml::Signature::Algorithms`
+module is the registry; adding a new algorithm means:
+
+1. Subclass the relevant base (`DigestBase`, `SignatureMethodBase`,
+   `CanonicalizationBase`, `TransformBase`).
+2. Declare `identifier "http://..."` on the subclass.
+3. Add an autoload entry in `algorithms.rb` and a reference in
+   `load_builtins!`.
+
+No edits to existing code. The registry has four categories:
+`:digest`, `:signature_method`, `:canonicalization`, `:transform`.
+
+### 2. Models are POROs; serialization is a service
+
+Models (`Model::Signature`, `Model::SignedInfo`, `Model::Reference`,
+etc.) are plain Ruby objects with `attr_accessor`. They do **not** own
+their wire shape. A dedicated `Serializer` translates model → XML using
+moxml primitives; `Parser` translates XML → model. This keeps the data
+shape and the wire shape independent, and matches the user's global
+rule ("no hand-rolled serialization on model classes").
+
+### 3. Signer / Verifier orchestrate, don't compute
+
+`Signer` walks the references, delegates to the transform pipeline,
+computes digests via `DigestMethod` instances, and signs the
+canonicalized SignedInfo. It contains no algorithm-specific logic.
+
+`Verifier` follows Best Practice 1: authenticate SignatureValue first,
+then run reference transforms. Errors are captured into the result
+object (`SingleVerificationResult#error`), not raised, so a malicious
+signature cannot panic the application.
+
+### 4. TransformPipeline is shared by Signer and Verifier
+
+The transform-chain logic (lookup algorithm, coerce input type, apply,
+repeat) is the same for signing and verifying. It lives in
+`TransformPipeline` — DRY.
+
+### 5. C14N is shared infrastructure
+
+Inclusive C14N is ported from `~/src/lutaml/canon` (mature, ~1,200
+lines, full node-set subset support, xml:base fixup, xml:* inheritable
+attribute resolution). Exclusive C14N is moxml-native (canon doesn't
+implement it). Both expose the same `#canonicalize(node, with_comments:,
+inclusive_namespaces:)` interface.
+
+## Adapter-agnostic invariant
+
+Every XML operation — parse, walk, serialize, canonicalize — goes
+through `Moxml::Node`. The signature module never imports Nokogiri,
+Oga, REXML, Ox, or LibXML directly. Switching adapters does not change
+signature behavior.
+
+The one exception is the `context:` parameter threaded through every
+constructor. When a transform receives octet-stream input, it parses
+with the same adapter the caller used (`context.parse(...)`), preserving
+byte-exact canonicalization across adapters.
+
+## Cross-verification
+
+`spec/fixtures/xmldsig/sign2-result.xml` and `sign3-result.xml` are
+real libxmlsec1-produced signatures (from the Ruby
+`nokogiri-xmlsec-instructure` reference). Both verify byte-exact against
+`Moxml::Signature.verify`, proving the C14N and signing logic matches a
+battle-tested C implementation.
+
+## What this module deliberately doesn't do
+
+- **XPath Filter transform** — Best Practice 5 says avoid. The Enveloped
+  Signature transform walks ancestors directly, no XPath needed.
+- **XSLT transform** — Best Practice 3 says avoid. Disabled.
+- **External URI dereferencing** — Best Practice 8 says constrain.
+  Applications must provide their own resolver.
+- **X.509 chain validation** — application responsibility (trust policy).
+- **XML Encryption** — separate spec (xmlenc-core-1.1).
+- **XAdES** — separate spec (ETSI TS 101 903).

data/docs/signature/c14n.md

@@ -0,0 +1,110 @@
+# Canonicalization (C14N)
+
+Canonicalization is the load-bearing primitive for XML signature.
+Two documents that differ only in surface representation (whitespace,
+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`.
+
+## 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 `~/src/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 are moved between XML contexts (e.g., into a
+  SOAP envelope).
+
+## Public API
+
+```ruby
+# Convenience: inclusive C14N 1.0
+Moxml::C14n.canonicalize(node_or_xml, with_comments: false)
+# → canonical UTF-8 octet String
+
+# Convenience: exclusive C14N 1.0
+Moxml::C14n.canonicalize_exclusive(
+  node_or_xml,
+  with_comments: false,
+  inclusive_namespaces: [],  # InclusiveNamespacesPrefixList parameter
+)
+# → canonical UTF-8 octet String
+
+# Direct engine access (used by signature algorithms)
+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:)
+```
+
+`node_or_xml` accepts a `Moxml::Node`, `Moxml::Document`, or XML `String`.
+
+## Data model
+
+The canon-derived inclusive C14N walks an intermediate data model
+(`Moxml::C14n::Nodes::*`) rather than the live `Moxml::Node` tree. This
+is because canonicalization needs:
+
+- **Node-set membership flags** for subset canonicalization (spec §3).
+  Same-document references select a node-set; only selected nodes are
+  rendered.
+- **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
+
+All algorithms produce canonical octets with these properties:
+
+- 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 (XML parser already does this)
+
+## Why not delegate to Nokogiri's native C14N?
+
+Nokogiri (via libxml2) has both inclusive and exclusive C14N built-in,
+and it's much faster than pure Ruby. But:
+
+1. **XML-agnosticity.** Moxml's whole point is that switching adapters
+   doesn't change behavior. If C14N were Nokogiri-only, Oga/REXML/Ox
+   users would get no canonicalization.
+2. **Adapter-coupled canonicalization breaks cross-adapter signature
+   verification.** A signature produced with Nokogiri must verify with
+   Oga — same canonical bytes.
+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.
+
+## Cross-verification
+
+The libxmlsec1-produced fixtures in `spec/fixtures/xmldsig/` verify
+byte-exact against our C14N output. This proves the implementation
+matches libxml2's C-based canonicalization for the cases the Ruby
+reference exercises.

data/docs/signature/examples.md

@@ -0,0 +1,109 @@
+# Examples
+
+Runnable examples live in `examples/signature/`. Run with:
+
+```bash
+bundle exec ruby examples/signature/enveloped_rsa.rb
+bundle exec ruby examples/signature/hmac.rb
+bundle exec ruby examples/signature/auto_key_extraction.rb
+```
+
+## Minimal enveloped RSA-SHA256 signature
+
+```ruby
+require "moxml"
+require "moxml/signature"
+require "openssl"
+
+ctx = Moxml.new(:nokogiri)
+key = OpenSSL::PKey::RSA.generate(2048)
+
+doc = ctx.parse("<doc><greeting>Hello, World!</greeting></doc>")
+
+# Sign — produces a Model::Signature
+signature = Moxml::Signature.sign(
+  context: ctx,
+  document: doc,
+  key: key,
+  signature_method: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
+  canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+  digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+  reference_uri: "",
+  transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+)
+
+# Serialize the signature into XML and attach to the document
+serialized = Moxml::Signature::Serializer.new(context: ctx).serialize(signature)
+doc.root.add_child(serialized.root)
+
+puts doc.to_xml
+```
+
+## Verify with the public key
+
+```ruby
+result = Moxml::Signature.verify(
+  context: ctx,
+  document: doc,
+  key: key,   # private key works; public key alone is enough
+)
+
+puts "Valid: #{result.valid?}"
+puts "Signature count: #{result.signature_count}"
+result.results.each do |r|
+  puts "  signature_valid=#{r.signature_valid?}"
+  r.references.each { |ref| puts "    ref #{ref.uri.inspect}: #{ref.valid?}" }
+end
+```
+
+## Auto-extract key from X509Certificate
+
+```ruby
+# sign3-result.xml embeds the signing certificate in KeyInfo.
+# No explicit key is needed — the Verifier extracts it automatically.
+doc = ctx.parse(File.read("spec/fixtures/xmldsig/sign3-result.xml"))
+result = Moxml::Signature.verify(context: ctx, document: doc)
+puts "Auto-extracted: #{result.valid?}"
+```
+
+## KeyName-based key resolution
+
+```ruby
+# Signer used <KeyName>my-key</KeyName>; verifier resolves via key_map:
+result = Moxml::Signature.verify(
+  context: ctx,
+  document: doc,
+  key_map: { "my-key" => trusted_public_key },
+)
+```
+
+## HMAC with truncation
+
+```ruby
+signature = Moxml::Signature.sign(
+  context: ctx,
+  document: doc,
+  key: "shared-secret",
+  signature_method: "http://www.w3.org/2001/04/xmldsig-more#hmac-sha256",
+  canonicalization_method: "http://www.w3.org/2001/10/xml-exc-c14n#",
+  digest_method: "http://www.w3.org/2001/04/xmlenc#sha256",
+  reference_uri: "",
+  transforms: ["http://www.w3.org/2000/09/xmldsig#enveloped-signature"],
+)
+```
+
+HMAC `OutputLength` truncation below `max(hash_bits/2, 80)` is rejected.
+
+## Adding a custom algorithm
+
+```ruby
+class MyDigest < Moxml::Signature::Algorithms::DigestBase
+  identifier "http://example.com/my-digest"
+
+  def compute_digest(data)
+    OpenSSL::Digest.digest("SHA3-256", data)
+  end
+end
+
+# Now usable in any Reference#digest_method
+```