hanko_xml 0.1.0-x86_64-linux

data/lib/hanko_xml/xml.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# XML digital signature verification backed by libxmlsec1.
+module HankoXml
+  # XML-DSig namespace prefixes used in every XPath this library runs
+  # internally -- never //Signature, never local-name(). See
+  # API_CONTRACT.md §6.8.
+  NS = {
+    "ds" => "http://www.w3.org/2000/09/xmldsig#",
+    "ds11" => "http://www.w3.org/2009/xmldsig11#",
+    "ec" => "http://www.w3.org/2001/10/xml-exc-c14n#"
+  }.freeze
+
+  class << self
+    # Parses +source+ (a String, IO, or path-like object) the one way that
+    # does not break XML-DSig: strict (no RECOVER), nonet, never NOBLANKS,
+    # never NOENT, never HUGE. See API_CONTRACT.md §6.3.
+    #
+    # Raises HankoXml::NokogiriRequired without Nokogiri, HankoXml::ParseError
+    # on malformed input.
+    def parse(source)
+      Dom.require!("HankoXml.parse")
+
+      doc, errors = Dom.parse(source)
+      raise parse_error(errors) if errors.any?
+
+      doc
+    end
+
+    # libxml2's diagnostics can quote the document (tag names, text), so they
+    # go in #xmlsec_errors, never in #message (#96, API_CONTRACT.md §5.10).
+    def parse_error(errors)
+      HankoXml::ParseError.new("the document is not well-formed XML", xmlsec_errors: errors.map(&:message))
+    end
+    private :parse_error
+
+    # Byte-faithful serialization: AS_XML only, never FORMAT (which
+    # reindents the tree and invalidates any signature over it). See
+    # API_CONTRACT.md §6.3.
+    def serialize(doc)
+      Dom.require!("HankoXml.serialize")
+
+      Dom.to_xml(doc)
+    end
+
+    # Coerces any of the accepted document input shapes (§6.2) into a
+    # Nokogiri::XML::Document: an existing Document as-is, a Node via its
+    # #document, a String of markup, a path-like object, or anything
+    # responding to #read.
+    #
+    # +policy+, when given, applies its +max_document_size+ to unparsed
+    # input before it is read or parsed (S-12): see #read_source. An
+    # existing Document/Node is not checked here; Signer/Verifier check its
+    # serialized form before any native call.
+    #
+    # @api private
+    def coerce_document(input, policy: nil)
+      return input if Dom.document?(input)
+      return input.document if Dom.node?(input)
+
+      parse(read_source(input, policy: policy))
+    end
+
+    # Reads unparsed input (§6.2) without parsing it: a String as-is, a
+    # path-like object's file, or anything responding to #read. +policy+'s
+    # +max_document_size+ applies before the input is read (S-12): a String
+    # by #bytesize, a path by File.size, an IO by reading at most one byte
+    # past the limit.
+    #
+    # @api private
+    def read_source(input, policy: nil)
+      limit = policy&.max_document_size
+      limit = nil unless limit&.finite?
+
+      case input
+      when String
+        policy&.enforce_document_size!(input.bytesize)
+        input
+      when ->(obj) { obj.respond_to?(:to_path) }
+        policy&.enforce_document_size!(::File.size(input.to_path))
+        ::File.binread(input.to_path)
+      when ->(obj) { obj.respond_to?(:read) }
+        source = limit ? input.read(limit + 1) : input.read
+        policy&.enforce_document_size!(source.to_s.bytesize)
+        source.to_s
+      else
+        raise ArgumentError,
+              "expected a Nokogiri::XML::Document/Node, an XML String, a path-like object " \
+              "(Pathname/File), or an IO, got #{input.class}"
+      end
+    end
+  end
+end

data/lib/hanko_xml/xmldsig-core-schema.xsd

@@ -0,0 +1,332 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE schema
+  PUBLIC "-//W3C//DTD XMLSchema 200102//EN" "http://www.w3.org/2001/XMLSchema.dtd"
+ [
+   <!ATTLIST schema 
+     xmlns:ds CDATA #FIXED "http://www.w3.org/2000/09/xmldsig#">
+   <!ENTITY dsig 'http://www.w3.org/2000/09/xmldsig#'>
+   <!ENTITY % p ''>
+   <!ENTITY % s ''>
+  ]>
+
+<!-- Schema for XML Signatures
+    http://www.w3.org/2000/09/xmldsig#
+    $Revision: 1.2 $ on $Date: 2013/04/16 12:48:49 $ by $Author: denis $
+
+    Copyright 2001 The Internet Society and W3C (Massachusetts Institute
+    of Technology, Institut National de Recherche en Informatique et en
+    Automatique, Keio University). All Rights Reserved.
+    http://www.w3.org/Consortium/Legal/
+
+    This document is governed by the W3C Software License [1] as described
+    in the FAQ [2].
+
+    [1] http://www.w3.org/Consortium/Legal/copyright-software-19980720
+    [2] http://www.w3.org/Consortium/Legal/IPR-FAQ-20000620.html#DTD
+-->
+
+
+<schema xmlns="http://www.w3.org/2001/XMLSchema"
+        xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
+        targetNamespace="http://www.w3.org/2000/09/xmldsig#"
+        version="0.1" elementFormDefault="qualified"> 
+
+<!-- HankoXml: <ec:InclusiveNamespaces> may appear under the strict
+     CanonicalizationMethod wildcard (#61). -->
+<import namespace="http://www.w3.org/2001/10/xml-exc-c14n#" schemaLocation="exc-c14n.xsd"/>
+
+<!-- Basic Types Defined for Signatures -->
+
+<simpleType name="CryptoBinary">
+  <restriction base="base64Binary">
+  </restriction>
+</simpleType>
+
+<!-- Start Signature -->
+
+<element name="Signature" type="ds:SignatureType"/>
+<complexType name="SignatureType">
+  <sequence> 
+    <element ref="ds:SignedInfo"/> 
+    <element ref="ds:SignatureValue"/> 
+    <element ref="ds:KeyInfo" minOccurs="0"/> 
+    <element ref="ds:Object" minOccurs="0" maxOccurs="unbounded"/> 
+  </sequence>  
+  <attribute name="Id" type="ID" use="optional"/>
+</complexType>
+
+  <element name="SignatureValue" type="ds:SignatureValueType"/> 
+  <complexType name="SignatureValueType">
+    <simpleContent>
+      <extension base="base64Binary">
+        <attribute name="Id" type="ID" use="optional"/>
+      </extension>
+    </simpleContent>
+  </complexType>
+
+<!-- Start SignedInfo -->
+
+<element name="SignedInfo" type="ds:SignedInfoType"/>
+<complexType name="SignedInfoType">
+  <sequence> 
+    <element ref="ds:CanonicalizationMethod"/> 
+    <element ref="ds:SignatureMethod"/> 
+    <element ref="ds:Reference" maxOccurs="unbounded"/> 
+  </sequence>  
+  <attribute name="Id" type="ID" use="optional"/> 
+</complexType>
+
+  <element name="CanonicalizationMethod" type="ds:CanonicalizationMethodType"/> 
+  <complexType name="CanonicalizationMethodType" mixed="true">
+    <sequence>
+      <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
+      <!-- (0,unbounded) elements from (1,1) namespace -->
+    </sequence>
+    <attribute name="Algorithm" type="anyURI" use="required"/> 
+  </complexType>
+
+  <element name="SignatureMethod" type="ds:SignatureMethodType"/>
+  <complexType name="SignatureMethodType" mixed="true">
+    <sequence>
+      <element name="HMACOutputLength" minOccurs="0" type="ds:HMACOutputLengthType"/>
+      <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
+      <!-- (0,unbounded) elements from (1,1) external namespace -->
+    </sequence>
+    <attribute name="Algorithm" type="anyURI" use="required"/> 
+  </complexType>
+
+<!-- Start Reference -->
+
+<element name="Reference" type="ds:ReferenceType"/>
+<complexType name="ReferenceType">
+  <sequence> 
+    <element ref="ds:Transforms" minOccurs="0"/> 
+    <element ref="ds:DigestMethod"/> 
+    <element ref="ds:DigestValue"/> 
+  </sequence>
+  <attribute name="Id" type="ID" use="optional"/> 
+  <attribute name="URI" type="anyURI" use="optional"/> 
+  <attribute name="Type" type="anyURI" use="optional"/> 
+</complexType>
+
+  <element name="Transforms" type="ds:TransformsType"/>
+  <complexType name="TransformsType">
+    <sequence>
+      <element ref="ds:Transform" maxOccurs="unbounded"/>  
+    </sequence>
+  </complexType>
+
+  <element name="Transform" type="ds:TransformType"/>
+  <complexType name="TransformType" mixed="true">
+    <choice minOccurs="0" maxOccurs="unbounded"> 
+      <any namespace="##other" processContents="lax"/>
+      <!-- (1,1) elements from (0,unbounded) namespaces -->
+      <element name="XPath" type="string"/> 
+    </choice>
+    <attribute name="Algorithm" type="anyURI" use="required"/> 
+  </complexType>
+
+<!-- End Reference -->
+
+<element name="DigestMethod" type="ds:DigestMethodType"/>
+<complexType name="DigestMethodType" mixed="true"> 
+  <sequence>
+    <any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
+  </sequence>    
+  <attribute name="Algorithm" type="anyURI" use="required"/> 
+</complexType>
+
+<element name="DigestValue" type="ds:DigestValueType"/>
+<simpleType name="DigestValueType">
+  <restriction base="base64Binary"/>
+</simpleType>
+
+<!-- End SignedInfo -->
+
+<!-- Start KeyInfo -->
+
+<element name="KeyInfo" type="ds:KeyInfoType"/> 
+<complexType name="KeyInfoType" mixed="true">
+  <choice maxOccurs="unbounded">     
+    <element ref="ds:KeyName"/> 
+    <element ref="ds:KeyValue"/> 
+    <element ref="ds:RetrievalMethod"/> 
+    <element ref="ds:X509Data"/> 
+    <element ref="ds:PGPData"/> 
+    <element ref="ds:SPKIData"/>
+    <element ref="ds:MgmtData"/>
+    <any processContents="lax" namespace="##other"/>
+    <!-- (1,1) elements from (0,unbounded) namespaces -->
+  </choice>
+  <attribute name="Id" type="ID" use="optional"/> 
+</complexType>
+
+  <element name="KeyName" type="string"/>
+  <element name="MgmtData" type="string"/>
+
+  <element name="KeyValue" type="ds:KeyValueType"/> 
+  <complexType name="KeyValueType" mixed="true">
+   <choice>
+     <element ref="ds:DSAKeyValue"/>
+     <element ref="ds:RSAKeyValue"/>
+     <any namespace="##other" processContents="lax"/>
+   </choice>
+  </complexType>
+
+  <element name="RetrievalMethod" type="ds:RetrievalMethodType"/> 
+  <complexType name="RetrievalMethodType">
+    <sequence>
+      <element ref="ds:Transforms" minOccurs="0"/> 
+    </sequence>  
+    <attribute name="URI" type="anyURI"/>
+    <attribute name="Type" type="anyURI" use="optional"/>
+  </complexType>
+
+<!-- Start X509Data -->
+
+<element name="X509Data" type="ds:X509DataType"/> 
+<complexType name="X509DataType">
+  <sequence maxOccurs="unbounded">
+    <choice>
+      <element name="X509IssuerSerial" type="ds:X509IssuerSerialType"/>
+      <element name="X509SKI" type="base64Binary"/>
+      <element name="X509SubjectName" type="string"/>
+      <element name="X509Certificate" type="base64Binary"/>
+      <element name="X509CRL" type="base64Binary"/>
+      <any namespace="##other" processContents="lax"/>
+    </choice>
+  </sequence>
+</complexType>
+
+<complexType name="X509IssuerSerialType"> 
+  <sequence> 
+    <element name="X509IssuerName" type="string"/> 
+    <!-- HankoXml: the lexical space of xs:integer as a pattern. libxml2
+         before 2.12 rejects any xs:integer over 24 digits, and an X.509
+         serial may be 20 octets (49 digits), so a valid signature failed
+         schema: :default wherever Nokogiri ran on an older libxml2. -->
+    <element name="X509SerialNumber">
+      <simpleType>
+        <restriction base="token">
+          <pattern value="[+\-]?[0-9]+"/>
+        </restriction>
+      </simpleType>
+    </element>
+  </sequence>
+</complexType>
+
+<!-- End X509Data -->
+
+<!-- Begin PGPData -->
+
+<element name="PGPData" type="ds:PGPDataType"/> 
+<complexType name="PGPDataType"> 
+  <choice>
+    <sequence>
+      <element name="PGPKeyID" type="base64Binary"/> 
+      <element name="PGPKeyPacket" type="base64Binary" minOccurs="0"/> 
+      <any namespace="##other" processContents="lax" minOccurs="0"
+       maxOccurs="unbounded"/>
+    </sequence>
+    <sequence>
+      <element name="PGPKeyPacket" type="base64Binary"/> 
+      <any namespace="##other" processContents="lax" minOccurs="0"
+       maxOccurs="unbounded"/>
+    </sequence>
+  </choice>
+</complexType>
+
+<!-- End PGPData -->
+
+<!-- Begin SPKIData -->
+
+<element name="SPKIData" type="ds:SPKIDataType"/> 
+<complexType name="SPKIDataType">
+  <sequence maxOccurs="unbounded">
+    <element name="SPKISexp" type="base64Binary"/>
+    <any namespace="##other" processContents="lax" minOccurs="0"/>
+  </sequence>
+</complexType> 
+
+<!-- End SPKIData -->
+
+<!-- End KeyInfo -->
+
+<!-- Start Object (Manifest, SignatureProperty) -->
+
+<element name="Object" type="ds:ObjectType"/> 
+<complexType name="ObjectType" mixed="true">
+  <sequence minOccurs="0" maxOccurs="unbounded">
+    <any namespace="##any" processContents="lax"/>
+  </sequence>
+  <attribute name="Id" type="ID" use="optional"/> 
+  <attribute name="MimeType" type="string" use="optional"/> <!-- add a grep facet -->
+  <attribute name="Encoding" type="anyURI" use="optional"/> 
+</complexType>
+
+<element name="Manifest" type="ds:ManifestType"/> 
+<complexType name="ManifestType">
+  <sequence>
+    <element ref="ds:Reference" maxOccurs="unbounded"/> 
+  </sequence>
+  <attribute name="Id" type="ID" use="optional"/> 
+</complexType>
+
+<element name="SignatureProperties" type="ds:SignaturePropertiesType"/> 
+<complexType name="SignaturePropertiesType">
+  <sequence>
+    <element ref="ds:SignatureProperty" maxOccurs="unbounded"/> 
+  </sequence>
+  <attribute name="Id" type="ID" use="optional"/> 
+</complexType>
+
+   <element name="SignatureProperty" type="ds:SignaturePropertyType"/> 
+   <complexType name="SignaturePropertyType" mixed="true">
+     <choice maxOccurs="unbounded">
+       <any namespace="##other" processContents="lax"/>
+       <!-- (1,1) elements from (1,unbounded) namespaces -->
+     </choice>
+     <attribute name="Target" type="anyURI" use="required"/> 
+     <attribute name="Id" type="ID" use="optional"/> 
+   </complexType>
+
+<!-- End Object (Manifest, SignatureProperty) -->
+
+<!-- Start Algorithm Parameters -->
+
+<simpleType name="HMACOutputLengthType">
+  <restriction base="integer"/>
+</simpleType>
+
+<!-- Start KeyValue Element-types -->
+
+<element name="DSAKeyValue" type="ds:DSAKeyValueType"/>
+<complexType name="DSAKeyValueType">
+  <sequence>
+    <sequence minOccurs="0">
+      <element name="P" type="ds:CryptoBinary"/>
+      <element name="Q" type="ds:CryptoBinary"/>
+    </sequence>
+    <element name="G" type="ds:CryptoBinary" minOccurs="0"/>
+    <element name="Y" type="ds:CryptoBinary"/>
+    <element name="J" type="ds:CryptoBinary" minOccurs="0"/>
+    <sequence minOccurs="0">
+      <element name="Seed" type="ds:CryptoBinary"/>
+      <element name="PgenCounter" type="ds:CryptoBinary"/>
+    </sequence>
+  </sequence>
+</complexType>
+
+<element name="RSAKeyValue" type="ds:RSAKeyValueType"/>
+<complexType name="RSAKeyValueType">
+  <sequence>
+    <element name="Modulus" type="ds:CryptoBinary"/> 
+    <element name="Exponent" type="ds:CryptoBinary"/> 
+  </sequence>
+</complexType> 
+
+<!-- End KeyValue Element-types -->
+
+<!-- End Signature -->
+
+</schema>

data/lib/hanko_xml.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "hanko_xml/version"
+
+# A precompiled platform gem serves several Ruby versions at once, so
+# rake-compiler ships one extension per ABI under lib/hanko_xml/<major.minor>/.
+# A gem built from source has a single lib/hanko_xml/hanko_xml.<so|bundle>
+# instead. Try the versioned path first and fall back, so both layouts load.
+begin
+  require_relative "hanko_xml/#{RUBY_VERSION[/\d+\.\d+/]}/hanko_xml"
+rescue LoadError
+  require_relative "hanko_xml/hanko_xml"
+end
+require_relative "hanko_xml/errors"
+require_relative "hanko_xml/native_version"
+require_relative "hanko_xml/dom"
+require_relative "hanko_xml/algorithms"
+require_relative "hanko_xml/xml"
+require_relative "hanko_xml/input"
+require_relative "hanko_xml/key"
+require_relative "hanko_xml/transform"
+require_relative "hanko_xml/reference"
+require_relative "hanko_xml/key_info"
+require_relative "hanko_xml/placement"
+require_relative "hanko_xml/signature_info"
+require_relative "hanko_xml/policy"
+require_relative "hanko_xml/template"
+require_relative "hanko_xml/signer"
+require_relative "hanko_xml/verification"
+require_relative "hanko_xml/verifier"
+require_relative "hanko_xml/signed_document"
+require_relative "hanko_xml/xades"
+
+# Refuse to run against a libxmlsec1 the extension was not built for, before
+# any signing or verification can produce a wrong answer. See
+# HankoXml::NativeVersion.
+HankoXml::NativeVersion.check!
+
+# XML digital signature verification backed by libxmlsec1.
+module HankoXml
+  class << self
+    # True when Nokogiri is loaded. See §6.1.
+    def nokogiri?
+      Dom.available?
+    end
+
+    # Which capabilities are available given whether Nokogiri is loaded.
+    # See §6.1.
+    def capabilities
+      Dom.capabilities
+    end
+
+    # Signs an XML document, returning a safely-serializable +SignedDocument+ wrapper.
+    # This is a convenience shortcut that creates a +Signer+ and calls +#sign+.
+    # The original document is not modified (a deep clone is created).
+    #
+    # @param doc_or_xml [String, Nokogiri::XML::Node, Nokogiri::XML::Document, IO] The XML to sign.
+    # @param kwargs [Hash] Configuration options passed to {Signer#initialize}.
+    # @return [HankoXml::SignedDocument] A wrapper around the cloned, signed document.
+    def sign(doc_or_xml, **kwargs)
+      HankoXml::Signer.new(**kwargs).sign(doc_or_xml)
+    end
+
+    # Signs a Nokogiri XML document in place.
+    # This is a convenience shortcut that creates a +Signer+ and calls +#sign!+.
+    #
+    # @param doc [Nokogiri::XML::Node, Nokogiri::XML::Document] The document to mutate.
+    # @param kwargs [Hash] Configuration options passed to {Signer#initialize}.
+    # @return [Nokogiri::XML::Node, Nokogiri::XML::Document] The mutated original document.
+    def sign!(doc, **kwargs)
+      HankoXml::Signer.new(**kwargs).sign!(doc)
+    end
+
+    # Verifies an XML signature and answers with a plain boolean, so it is safe
+    # directly in a conditional. This is a convenience shortcut that creates a
+    # +Verifier+ and calls +#valid?+.
+    #
+    # There is deliberately no +HankoXml.verify+: a {Verification} is always
+    # truthy, so +if HankoXml.verify(doc, ...)+ would be a security bug that reads
+    # like correct code (API_CONTRACT §5.1). For the rich object use {verify!} or
+    # {Verifier#verify}.
+    #
+    # @param xml [String, Nokogiri::XML::Node, Nokogiri::XML::Document, IO] The signed XML.
+    # @param kwargs [Hash] Configuration options passed to {Verifier#initialize}.
+    # @raise [HankoXml::Error] If parsing fails or trust sources are misconfigured.
+    # @return [Boolean] True only when the signature verified under the policy.
+    def valid?(xml, **kwargs)
+      HankoXml::Verifier.new(**kwargs).valid?(xml)
+    end
+
+    # Verifies an XML signature, raising an exception if invalid.
+    # This is a convenience shortcut that creates a +Verifier+ and calls +#verify!+.
+    #
+    # @param xml [String, Nokogiri::XML::Node, Nokogiri::XML::Document, IO] The signed XML.
+    # @param kwargs [Hash] Configuration options passed to {Verifier#initialize}.
+    # @raise [HankoXml::VerificationError] If the signature is cryptographically invalid or violates policy.
+    # @raise [HankoXml::Error] If parsing fails or trust sources are misconfigured.
+    # @return [HankoXml::Verification] The valid verification result.
+    def verify!(xml, **kwargs)
+      HankoXml::Verifier.new(**kwargs).verify!(xml)
+    end
+
+    # Checks whether the document contains at least one populated <ds:Signature>.
+    # Does NOT verify the signature's cryptographic validity.
+    #
+    # @param xml [String, Nokogiri::XML::Node, Nokogiri::XML::Document, IO] The XML to check.
+    # @return [Boolean] True if a non-empty <ds:SignatureValue> exists, false otherwise.
+    def signature_present?(xml)
+      # Structural, from the native parse; needs no DOM (#102).
+      HankoXml::Input.read(xml).scan([])[:signature_values].any?
+    end
+
+    # Returns whether zero-copy DOM verification is available on this platform.
+    #
+    # @return [Boolean] Always false (libxmlsec1 requires serialization).
+    def zero_copy_available?
+      false
+    end
+  end
+
+  ::Xmlsec = HankoXml unless defined?(::Xmlsec)
+end

data/sig/hanko_xml/key.rbs

@@ -0,0 +1,48 @@
+module HankoXml
+  class Key
+    @material: OpenSSL::PKey::PKey | OpenSSL::X509::Certificate
+    @disposed: bool
+
+    def self.from_pem: (String pem, ?password: String?) -> instance
+    def self.from_der: (String der) -> instance
+    def self.from_file: (String | _ToPath path, ?password: String?) -> instance
+    def self.from_pkcs12: (String | _ToPath path, password: String) -> Bundle
+    def self.coerce: (untyped input, ?password: String?) -> instance
+
+    def initialize: (OpenSSL::PKey::PKey | OpenSSL::X509::Certificate material) -> void
+    def certificate?: () -> bool
+    def private_key?: () -> bool
+    def to_pem: () -> String
+    def to_openssl: () -> (OpenSSL::PKey::PKey | OpenSSL::X509::Certificate)
+    def dispose!: () -> void
+    def disposed?: () -> bool
+
+    class Bundle
+      attr_reader key: Key
+      attr_reader certificate: Key
+      attr_reader certificates: Array[Key]
+
+      def initialize: (key: Key, certificate: Key, certificates: Array[Key]) -> void
+      def to_h: () -> { key: Key, certificate: Key, certificates: Array[Key] }
+    end
+  end
+
+  module KeyInfo
+    class Clause
+      attr_reader name: Symbol
+      attr_reader value: String?
+
+      def initialize: (Symbol | String name, ?String? value) -> void
+    end
+
+    def self.coerce: (Symbol | Hash[Symbol, String] | Array[Symbol | Hash[Symbol, String] | Clause] info) -> Array[Clause]
+
+    class Parsed
+      attr_reader key_names: Array[String]
+      # PEM Strings, as <KeyInfo> carried them: untrusted, and never parsed here.
+      attr_reader certificates: Array[String]
+
+      def initialize: (?key_names: Array[String], ?certificates: Array[String]) -> void
+    end
+  end
+end

data/sig/hanko_xml/native.rbs

@@ -0,0 +1,12 @@
+module HankoXml
+  module Native
+    def self.check_version: () -> bool
+    def self.abi_compatible?: () -> bool
+    def self.versions: () -> Hash[Symbol, String]
+    def self.inspect_sig: (String xml_bytes, Integer index) -> Hash[Symbol, untyped]
+    def self.verify: (String xml_bytes, Array[String] trusted, Array[String] untrusted, Array[String] id_attributes, Integer index, Array[[String, String]] referenced_documents, bool allow_xpath_filter2) -> Hash[Symbol, untyped]
+    def self.sign: (String xml_bytes, String key_pem, Array[String] cert_pems, Array[String] id_attributes, Integer index) -> String
+    def self.scan: (String xml_bytes, Array[String] id_attributes, bool strict) -> Hash[Symbol, untyped]
+    def self.validate_schema: (String xml_bytes, Integer index, String xsd_path) -> Array[String]
+  end
+end

data/sig/hanko_xml/native_version.rbs

@@ -0,0 +1,13 @@
+module HankoXml
+  module NativeVersion
+    SKIP_ENV: String
+
+    def self.check!: () -> (:ok | :abi_compatible | :skipped)
+    def self.build_versions: () -> Hash[Symbol, String]
+
+    private
+
+    def self.skip: () -> String?
+    def self.mismatch_message: () -> String
+  end
+end

data/sig/hanko_xml/nokogiri_ext.rbs

@@ -0,0 +1,23 @@
+# These methods exist only after `require "hanko_xml/nokogiri_ext"`, which is
+# opt-in (API_CONTRACT.md §6.6). `require "hanko_xml"` alone does not add them.
+module HankoXml
+  module NokogiriExt
+    def sign: (**untyped kwargs) -> HankoXml::SignedDocument
+    def sign!: (**untyped kwargs) -> self
+    def signature_valid?: (**untyped kwargs) -> bool
+    def signatures: () -> Nokogiri::XML::NodeSet
+    def signature_present?: () -> bool
+  end
+end
+
+module Nokogiri
+  module XML
+    class Node
+      # Only after require "hanko_xml/nokogiri_ext".
+      include HankoXml::NokogiriExt
+    end
+
+    class Document < Node
+    end
+  end
+end

data/sig/hanko_xml/placement.rbs

@@ -0,0 +1,27 @@
+module HankoXml
+  class Placement
+    type target = String | Nokogiri::XML::Node
+
+    MODES: Array[Symbol]
+
+    attr_reader mode: Symbol
+    attr_reader target: target?
+    attr_reader namespaces: Hash[String | Symbol, String]
+    attr_reader block: (^(Nokogiri::XML::Document, Nokogiri::XML::Node) -> void)?
+
+    def self.append_to_root: () -> instance
+    def self.prepend_to_root: () -> instance
+    def self.after: (target node_or_xpath, ?namespaces: Hash[String | Symbol, String]) -> instance
+    def self.before: (target node_or_xpath, ?namespaces: Hash[String | Symbol, String]) -> instance
+    def self.append_to: (target node_or_xpath, ?namespaces: Hash[String | Symbol, String]) -> instance
+    def self.prepend_to: (target node_or_xpath, ?namespaces: Hash[String | Symbol, String]) -> instance
+    def self.detached: () -> instance
+    def self.custom: () { (Nokogiri::XML::Document, Nokogiri::XML::Node) -> void } -> instance
+    def self.coerce: (instance | Symbol | nil input) -> instance?
+
+    def initialize: (Symbol | String mode, ?target: target?, ?namespaces: Hash[String | Symbol, String]) ?{ (Nokogiri::XML::Document, Nokogiri::XML::Node) -> void } -> void
+    def detached?: () -> bool
+    def resolve: (Nokogiri::XML::Document doc, ?namespaces: Hash[String | Symbol, String]?) -> Nokogiri::XML::Node
+    def insert: (Nokogiri::XML::Document doc, Nokogiri::XML::Node signature_node, ?namespaces: Hash[String | Symbol, String]?) -> Nokogiri::XML::Node
+  end
+end