hanko_xml 0.1.0

data/ext/hanko_xml/src/errors.rs

@@ -0,0 +1,151 @@
+//! Error callback capture for libxmlsec1.
+//!
+//! libxmlsec1's default error handler prints to stderr, which is
+//! unacceptable in a library. This module installs a custom callback
+//! via `xmlSecErrorsSetCallback` that captures error messages into a
+//! thread-local buffer. Each native call should bracket with
+//! [`clear_errors`] / [`drain_errors`] to collect diagnostics.
+//!
+//! Thread-safety: the GVL is held for the entire duration of every
+//! native call (§7.1), so a thread-local `RefCell<Vec<String>>` is
+//! sufficient — no `Mutex` needed.
+
+use std::cell::{Cell, RefCell};
+use std::ffi::CStr;
+use std::os::raw::{c_char, c_int, c_void};
+
+thread_local! {
+    static ERROR_BUF: RefCell<Vec<String>> = const { RefCell::new(Vec::new()) };
+    /// How many error-level libxml2 diagnostics the structured handler has
+    /// seen on this thread. Callers compare it before and after a parse.
+    static LIBXML2_ERRORS: Cell<usize> = const { Cell::new(0) };
+}
+
+/// Clears the thread-local error buffer. Call at the start of each
+/// native entry point.
+pub fn clear_errors() {
+    ERROR_BUF.with(|buf| buf.borrow_mut().clear());
+}
+
+/// Drains and returns all captured error messages since the last
+/// [`clear_errors`]. Call at the end of each native entry point.
+pub fn drain_errors() -> Vec<String> {
+    ERROR_BUF.with(|buf| {
+        let mut b = buf.borrow_mut();
+        let drained = b.clone();
+        b.clear();
+        drained
+    })
+}
+
+/// The `extern "C"` callback installed via `xmlSecErrorsSetCallback`.
+///
+/// Signature matches `xmlSecErrorsCallback`:
+/// ```c
+/// typedef void (*xmlSecErrorsCallback)(
+///     const char* file, int line, const char* func,
+///     const char* errorObject, const char* errorSubject,
+///     int reason, const char* msg);
+/// ```
+///
+/// # Safety
+///
+/// Called by libxmlsec1 internally. All pointer arguments are either
+/// valid C strings or null. We treat null as empty and never retain
+/// any pointer past this function's return.
+unsafe extern "C" fn error_callback(
+    file: *const c_char,
+    line: c_int,
+    func: *const c_char,
+    error_object: *const c_char,
+    error_subject: *const c_char,
+    reason: c_int,
+    msg: *const c_char,
+) {
+    let safe_str = |ptr: *const c_char| -> &str {
+        if ptr.is_null() {
+            ""
+        } else {
+            // SAFETY: libxmlsec1 passes NUL-terminated C strings or null.
+            unsafe { CStr::from_ptr(ptr) }.to_str().unwrap_or("")
+        }
+    };
+
+    let file_s = safe_str(file);
+    let func_s = safe_str(func);
+    let obj_s = safe_str(error_object);
+    let subj_s = safe_str(error_subject);
+    let msg_s = safe_str(msg).trim_end();
+
+    let entry = format!(
+        "func={func_s}:file={file_s}:line={line}:obj={obj_s}:subj={subj_s}:error={reason}:{msg_s}"
+    );
+
+    ERROR_BUF.with(|buf| {
+        buf.borrow_mut().push(entry);
+    });
+}
+
+/// Installs our error callback. Must be called once during
+/// `init_xmlsec()`, after `xmlSecInit()`.
+///
+/// # Safety
+///
+/// `xmlSecErrorsSetCallback` is safe to call after `xmlSecInit()`.
+pub unsafe fn install_error_callback() {
+    unsafe {
+        crate::sys::xmlSecErrorsSetCallback(Some(error_callback));
+    }
+}
+
+/// libxml2's structured error handler, installed around each native parse
+/// and schema validation by `dsig::Libxml2Capture`. Keeps libxml2's
+/// diagnostics off stderr and in the same buffer as xmlsec's, so they reach
+/// `#xmlsec_errors` and never `#message`: they can quote the document.
+///
+/// Only error and fatal levels are kept. Warnings are dropped, matching
+/// what a strict Nokogiri parse rejects (§6.3).
+///
+/// # Safety
+///
+/// Called by libxml2 with a valid `xmlError` or null, and never retained.
+/// Declared with `*const` (libxml2 2.12+); 2.9 passes the same pointer as
+/// `*mut`, which has the same ABI.
+unsafe extern "C" fn libxml2_error_callback(_ctx: *mut c_void, error: *const crate::sys::xmlError) {
+    if error.is_null() {
+        return;
+    }
+    // SAFETY: libxml2 passes a valid xmlError for the duration of the call.
+    let err = unsafe { &*error };
+    if (err.level as i64) < (crate::sys::xmlErrorLevel_XML_ERR_ERROR as i64) {
+        return;
+    }
+    let message = if err.message.is_null() {
+        ""
+    } else {
+        // SAFETY: a non-null message is a NUL-terminated C string.
+        unsafe { CStr::from_ptr(err.message) }.to_str().unwrap_or("")
+    };
+    let entry = format!("{}:{}: ERROR: {}", err.line, err.int2, message.trim_end());
+
+    LIBXML2_ERRORS.with(|count| count.set(count.get() + 1));
+    ERROR_BUF.with(|buf| buf.borrow_mut().push(entry));
+}
+
+/// The handler above, typed as libxml2's `xmlStructuredErrorFunc`, whose
+/// pointer argument is `*mut` before libxml2 2.12 and `*const` after.
+#[allow(
+    clippy::useless_transmute,
+    reason = "a no-op on libxml2 2.12+, where the types already match; needed on 2.9"
+)]
+pub fn libxml2_error_handler() -> crate::sys::xmlStructuredErrorFunc {
+    let handler: unsafe extern "C" fn(*mut c_void, *const crate::sys::xmlError) = libxml2_error_callback;
+    // SAFETY: both spellings of the callback type have the same ABI; only
+    // the constness of the xmlError pointer differs between libxml2 versions.
+    unsafe { std::mem::transmute(Some(handler)) }
+}
+
+/// Error-level libxml2 diagnostics seen on this thread so far.
+pub fn libxml2_error_count() -> usize {
+    LIBXML2_ERRORS.with(Cell::get)
+}

data/ext/hanko_xml/src/lib.rs

@@ -0,0 +1,490 @@
+//! Magnus glue: 5 functions on `HankoXml::Native`, matching the §7 contract.
+//!
+//! Every argument from Ruby is copied into a Rust-owned `Vec<u8>` or `String`
+//! **before** any native call, so there is no `unsafe` in this file — no
+//! `RString::as_slice()` across a call that might release the GVL.
+
+mod dsig;
+mod errors;
+mod sys;
+
+use magnus::{
+    function, prelude::*, Error, ExceptionClass, IntoValue, RArray, RHash, RModule, RString,
+    Ruby, TryConvert, Value,
+};
+use std::collections::HashMap;
+use std::sync::Once;
+
+static INIT: Once = Once::new();
+
+/// Runs [`dsig::init_xmlsec`] exactly once per process.
+fn ensure_initialized() -> Result<(), &'static str> {
+    let mut result = Ok(());
+    INIT.call_once(|| result = dsig::init_xmlsec());
+    result
+}
+
+// ---------------------------------------------------------------------------
+// Error construction helpers
+// ---------------------------------------------------------------------------
+
+fn error_class(ruby: &Ruby, class_name: &str) -> ExceptionClass {
+    ruby.eval::<ExceptionClass>(class_name)
+        .unwrap_or_else(|_| ruby.exception_runtime_error())
+}
+
+fn native_error(ruby: &Ruby, message: String) -> Error {
+    Error::new(error_class(ruby, "HankoXml::NativeError"), message)
+}
+
+/// Converts a [`dsig::DsigError`] into the matching `HankoXml::Error`
+/// subclass (S-13). The class comes from `err.kind`, and the message is the
+/// fixed string from `dsig.rs`. The xmlsec log captured during the call is
+/// drained here and set as `#xmlsec_errors`, never appended to `#message`:
+/// it can contain document text (hrefs, URIs, node names) that applications
+/// commonly log or display.
+fn dsig_error(ruby: &Ruby, err: dsig::DsigError) -> Error {
+    let class_name = match err.kind {
+        dsig::ErrorKind::Parse => "HankoXml::ParseError",
+        dsig::ErrorKind::KeyLoad => "HankoXml::KeyLoadError",
+        dsig::ErrorKind::Signing => "HankoXml::SigningError",
+        dsig::ErrorKind::Native => "HankoXml::NativeError",
+    };
+    let cls = error_class(ruby, class_name);
+    let xmlsec_errors = errors::drain_errors();
+
+    let exception = match cls.new_instance((err.message,)) {
+        Ok(exception) => exception,
+        Err(e) => return e,
+    };
+    if let Ok(log) = string_slice_to_rarray(ruby, &xmlsec_errors) {
+        // Best effort: without the attribute the typed error is still right.
+        let _: Result<Value, Error> = exception.funcall("xmlsec_errors=", (log,));
+    }
+    Error::from(exception)
+}
+
+// ---------------------------------------------------------------------------
+// Argument extraction and Ruby array helpers
+// ---------------------------------------------------------------------------
+
+/// Extracts an RString to an owned Vec<u8>.
+fn rstring_to_bytes(s: RString) -> Vec<u8> {
+    // SAFETY: s is a live Ruby String argument on the call stack.
+    // We immediately copy to a Vec<u8> so the slice is not retained.
+    unsafe { s.as_slice() }.to_vec()
+}
+
+/// Converts a slice of Strings to a Ruby Array of RStrings.
+fn string_slice_to_rarray(ruby: &Ruby, strings: &[String]) -> Result<RArray, Error> {
+    let arr = ruby.ary_new();
+    for s in strings {
+        arr.push(ruby.str_new(s))
+            .map_err(|e| native_error(ruby, format!("array push error: {e}")))?;
+    }
+    Ok(arr)
+}
+
+/// Extracts an RArray of RString into a Vec<Vec<u8>>.
+fn rarray_to_byte_vecs(ruby: &Ruby, arr: RArray) -> Result<Vec<Vec<u8>>, Error> {
+    let mut result = Vec::new();
+    for item in arr.into_iter() {
+        let s: RString = TryConvert::try_convert(item)
+            .map_err(|_| native_error(ruby, "array element is not a String".into()))?;
+        result.push(rstring_to_bytes(s));
+    }
+    Ok(result)
+}
+
+/// Extracts an RArray of `[String, String]` pairs into a map.
+fn rarray_to_byte_pairs(ruby: &Ruby, arr: RArray) -> Result<HashMap<Vec<u8>, Vec<u8>>, Error> {
+    let mut result = HashMap::new();
+    for item in arr.into_iter() {
+        let pair: RArray = TryConvert::try_convert(item)
+            .map_err(|_| native_error(ruby, "referenced document is not a [uri, bytes] pair".into()))?;
+        let [uri, bytes] = rarray_to_byte_vecs(ruby, pair)?
+            .try_into()
+            .map_err(|_| native_error(ruby, "referenced document is not a [uri, bytes] pair".into()))?;
+        result.insert(uri, bytes);
+    }
+    Ok(result)
+}
+
+/// Extracts an RArray of RString into a Vec<String>.
+fn rarray_to_strings(ruby: &Ruby, arr: RArray) -> Result<Vec<String>, Error> {
+    let mut result = Vec::new();
+    for item in arr.into_iter() {
+        let s: RString = TryConvert::try_convert(item)
+            .map_err(|_| native_error(ruby, "array element is not a String".into()))?;
+        result.push(
+            String::from_utf8(rstring_to_bytes(s))
+                .map_err(|_| native_error(ruby, "id_attribute is not valid UTF-8".into()))?,
+        );
+    }
+    Ok(result)
+}
+
+// ---------------------------------------------------------------------------
+// Native functions — the §7 contract
+// ---------------------------------------------------------------------------
+
+/// `HankoXml::Native.sign(xml, key_pem, cert_pems, id_attributes, signature_index)`
+///
+/// Signs the document's nth `<ds:Signature>` template and returns the
+/// complete signed XML as a binary String.
+fn native_sign(
+    ruby: &Ruby,
+    xml: RString,
+    key_pem: RString,
+    cert_pems: RArray,
+    id_attributes: RArray,
+    signature_index: usize,
+) -> Result<RString, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let xml_bytes = rstring_to_bytes(xml);
+    let key_bytes = rstring_to_bytes(key_pem);
+    let cert_bytes = rarray_to_byte_vecs(ruby, cert_pems)?;
+    let id_attrs = rarray_to_strings(ruby, id_attributes)?;
+
+    match dsig::sign_document(&xml_bytes, &key_bytes, &cert_bytes, &id_attrs, signature_index) {
+        Ok(signed_bytes) => Ok(ruby.str_from_slice(&signed_bytes)),
+        Err(err) => Err(dsig_error(ruby, err)),
+    }
+}
+
+/// `HankoXml::Native.verify(xml, trusted_pems, untrusted_pems, id_attributes, signature_index, referenced_documents)`
+///
+/// Verifies the nth `<ds:Signature>` and returns a Hash:
+/// `{ status:, errors:, reference_element_indexes: Array<Integer|nil>,
+///   reference_valid: Array<true|false|nil> }`
+///
+/// `reference_element_indexes` is the document-order element index of each
+/// SignedInfo Reference's target as resolved by libxml2's ID table (the same
+/// table xmlsec used for `#id` verification). Empty-URI references report the
+/// root. Unresolved / non-fragment URIs are `nil`.
+///
+/// `reference_valid` is each SignedInfo Reference's own digest verification
+/// status, same order, independent of the overall signature/key outcome
+/// (S-09): a harmless-fragment Reference and the payload Reference can
+/// genuinely disagree. `nil` means the reference was never processed
+/// (verification aborted before reaching it).
+///
+/// Only raises for conditions that are not a verification verdict.
+#[allow(
+    clippy::too_many_arguments,
+    reason = "one positional argument per Native.verify parameter (API_CONTRACT §7)"
+)]
+fn native_verify(
+    ruby: &Ruby,
+    xml: RString,
+    trusted_pems: RArray,
+    untrusted_pems: RArray,
+    id_attributes: RArray,
+    signature_index: usize,
+    referenced_documents: RArray,
+    allow_xpath_filter2: bool,
+) -> Result<RHash, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let xml_bytes = rstring_to_bytes(xml);
+    let trusted = rarray_to_byte_vecs(ruby, trusted_pems)?;
+    let untrusted = rarray_to_byte_vecs(ruby, untrusted_pems)?;
+    let id_attrs = rarray_to_strings(ruby, id_attributes)?;
+    let referenced = rarray_to_byte_pairs(ruby, referenced_documents)?;
+
+    match dsig::verify_document(
+        &xml_bytes,
+        &trusted,
+        &untrusted,
+        &id_attrs,
+        signature_index,
+        referenced,
+        allow_xpath_filter2,
+    ) {
+        Ok(result) => {
+            let hash = ruby.hash_new();
+            let status_sym = ruby.to_symbol(result.status.as_str());
+            hash.aset(ruby.to_symbol("status"), status_sym)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            let errors_array = string_slice_to_rarray(ruby, &result.errors)?;
+            hash.aset(ruby.to_symbol("errors"), errors_array)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            let indexes = ruby.ary_new();
+            for entry in &result.reference_element_indexes {
+                let value = match entry {
+                    Some(i) => ruby.integer_from_i64(*i as i64).as_value(),
+                    None => ruby.qnil().as_value(),
+                };
+                indexes
+                    .push(value)
+                    .map_err(|e| native_error(ruby, format!("array error: {e}")))?;
+            }
+            hash.aset(ruby.to_symbol("reference_element_indexes"), indexes)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            let reference_valid = ruby.ary_new();
+            for entry in &result.reference_valid {
+                let value = match entry {
+                    Some(valid) => valid.into_value_with(ruby),
+                    None => ruby.qnil().as_value(),
+                };
+                reference_valid
+                    .push(value)
+                    .map_err(|e| native_error(ruby, format!("array error: {e}")))?;
+            }
+            hash.aset(ruby.to_symbol("reference_valid"), reference_valid)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            let trusted_index = match result.trusted_index {
+                Some(i) => ruby.integer_from_i64(i as i64).as_value(),
+                None => ruby.qnil().as_value(),
+            };
+            hash.aset(ruby.to_symbol("trusted_index"), trusted_index)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            Ok(hash)
+        }
+        Err(err) => Err(dsig_error(ruby, err)),
+    }
+}
+
+/// `HankoXml::Native.scan(xml, id_attributes, strict)`
+///
+/// Returns the document's structure as a Hash, without cryptography:
+/// `{ signature_count:, signature_values: Array<bool>,
+///   signature_element_indexes: Array<Integer|nil>, duplicate_ids: bool,
+///   root_ids: Array<String> }`. `strict` rejects any libxml2 error with a
+/// `ParseError`, as a strict Nokogiri parse would (#102).
+fn native_scan(ruby: &Ruby, xml: RString, id_attributes: RArray, strict: bool) -> Result<RHash, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let xml_bytes = rstring_to_bytes(xml);
+    let id_attrs = rarray_to_strings(ruby, id_attributes)?;
+
+    let result = dsig::scan_document(&xml_bytes, &id_attrs, strict).map_err(|err| dsig_error(ruby, err))?;
+    let hash = ruby.hash_new();
+    let set = |key: &str, value: Value| {
+        hash.aset(ruby.to_symbol(key), value)
+            .map_err(|e| native_error(ruby, format!("hash error: {e}")))
+    };
+    set("signature_count", ruby.integer_from_i64(result.signature_count as i64).as_value())?;
+    let values = ruby.ary_new();
+    for present in result.signature_values {
+        values.push(present).map_err(|e| native_error(ruby, format!("array error: {e}")))?;
+    }
+    set("signature_values", values.as_value())?;
+    let indexes = ruby.ary_new();
+    for entry in result.signature_element_indexes {
+        let value = match entry {
+            Some(i) => ruby.integer_from_i64(i as i64).as_value(),
+            None => ruby.qnil().as_value(),
+        };
+        indexes.push(value).map_err(|e| native_error(ruby, format!("array error: {e}")))?;
+    }
+    set("signature_element_indexes", indexes.as_value())?;
+    set("duplicate_ids", result.duplicate_ids.into_value_with(ruby))?;
+    set("root_ids", string_slice_to_rarray(ruby, &result.root_ids)?.as_value())?;
+    Ok(hash)
+}
+
+/// `HankoXml::Native.validate_schema(xml, signature_index, xsd_path)`
+///
+/// Validates a copy of the nth `<ds:Signature>` against the XSD at
+/// `xsd_path`. Returns libxml2's validation errors; empty means valid.
+fn native_validate_schema(
+    ruby: &Ruby,
+    xml: RString,
+    signature_index: usize,
+    xsd_path: String,
+) -> Result<RArray, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let xml_bytes = rstring_to_bytes(xml);
+    let messages = dsig::validate_signature_schema(&xml_bytes, signature_index, &xsd_path)
+        .map_err(|err| dsig_error(ruby, err))?;
+    string_slice_to_rarray(ruby, &messages)
+}
+
+/// `HankoXml::Native.inspect_sig(xml, signature_index)`
+///
+/// Returns metadata about the nth `<ds:Signature>` without performing
+/// any cryptography. Used by Policy enforcement before verify/sign.
+fn native_inspect(
+    ruby: &Ruby,
+    xml: RString,
+    signature_index: usize,
+) -> Result<RHash, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let xml_bytes = rstring_to_bytes(xml);
+
+    errors::clear_errors();
+    match dsig::inspect_document(&xml_bytes, signature_index) {
+        Ok(result) => {
+            let hash = ruby.hash_new();
+
+            hash.aset(
+                ruby.to_symbol("signature_method"),
+                ruby.str_new(&result.signature_method),
+            )
+            .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            hash.aset(
+                ruby.to_symbol("canonicalization_method"),
+                ruby.str_new(&result.canonicalization_method),
+            )
+            .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            hash.aset(
+                ruby.to_symbol("signature_count"),
+                result.signature_count,
+            )
+            .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            // key_names array
+            let key_names = string_slice_to_rarray(ruby, &result.key_names)?;
+            hash.aset(ruby.to_symbol("key_names"), key_names)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            // certificates array
+            let certs = string_slice_to_rarray(ruby, &result.certificates)?;
+            hash.aset(ruby.to_symbol("certificates"), certs)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            // references array of hashes
+            let refs = ruby.ary_new();
+            for r in &result.references {
+                let ref_hash = ruby.hash_new();
+                ref_hash
+                    .aset(ruby.to_symbol("uri"), ruby.str_new(&r.uri))
+                    .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+                ref_hash
+                    .aset(ruby.to_symbol("digest_method"), ruby.str_new(&r.digest_method))
+                    .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+                let transforms = string_slice_to_rarray(ruby, &r.transforms)?;
+                ref_hash
+                    .aset(ruby.to_symbol("transforms"), transforms)
+                    .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+                ref_hash
+                    .aset(
+                        ruby.to_symbol("id"),
+                        r.id.as_ref()
+                            .map(|s| ruby.str_new(s).as_value())
+                            .unwrap_or_else(|| ruby.qnil().as_value()),
+                    )
+                    .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+                ref_hash
+                    .aset(
+                        ruby.to_symbol("type"),
+                        r.r#type
+                            .as_ref()
+                            .map(|s| ruby.str_new(s).as_value())
+                            .unwrap_or_else(|| ruby.qnil().as_value()),
+                    )
+                    .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+                let filters = ruby.ary_new();
+                for f in &r.xpath_filters {
+                    let filter = ruby.hash_new();
+                    let namespaces = ruby.hash_new();
+                    for (prefix, href) in &f.namespaces {
+                        namespaces
+                            .aset(ruby.str_new(prefix), ruby.str_new(href))
+                            .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+                    }
+                    for (key, value) in [
+                        ("filter", ruby.str_new(&f.filter).as_value()),
+                        ("expression", ruby.str_new(&f.expression).as_value()),
+                        ("namespaces", namespaces.as_value()),
+                    ] {
+                        filter
+                            .aset(ruby.to_symbol(key), value)
+                            .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+                    }
+                    filters.push(filter).map_err(|e| native_error(ruby, format!("array error: {e}")))?;
+                }
+                ref_hash
+                    .aset(ruby.to_symbol("xpath_filters"), filters)
+                    .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+                refs.push(ref_hash)
+                    .map_err(|e| native_error(ruby, format!("array error: {e}")))?;
+            }
+            hash.aset(ruby.to_symbol("references"), refs)
+                .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+
+            hash.aset(
+                ruby.to_symbol("has_retrieval_method"),
+                result.has_retrieval_method.into_value_with(ruby),
+            )
+            .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+            for (key, value) in [
+                ("empty_key_names", result.empty_key_names),
+                ("key_derived_values", result.key_derived_values),
+            ] {
+                hash.aset(ruby.to_symbol(key), value.into_value_with(ruby))
+                    .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+            }
+
+            Ok(hash)
+        }
+        Err(err) => Err(dsig_error(ruby, err)),
+    }
+}
+
+/// `HankoXml::Native.versions`
+///
+/// Returns `{ xmlsec: "1.3.12", libxml2: "2.15.3", crypto: "openssl" }`.
+fn native_versions(ruby: &Ruby) -> Result<RHash, Error> {
+    ensure_initialized().map_err(|msg| native_error(ruby, msg.into()))?;
+
+    let (xmlsec, libxml2, crypto) = dsig::versions();
+    let hash = ruby.hash_new();
+    hash.aset(ruby.to_symbol("xmlsec"), ruby.str_new(&xmlsec))
+        .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+    hash.aset(ruby.to_symbol("libxml2"), ruby.str_new(&libxml2))
+        .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+    hash.aset(ruby.to_symbol("crypto"), ruby.str_new(&crypto))
+        .map_err(|e| native_error(ruby, format!("hash error: {e}")))?;
+    Ok(hash)
+}
+
+/// `HankoXml::Native.check_version` — kept from the POC.
+///
+/// Exact-match check: true only when the loaded libxmlsec1 is the same
+/// major.minor.patch these bindings were generated against.
+fn native_check_version() -> bool {
+    dsig::check_version()
+}
+
+/// `HankoXml::Native.abi_compatible?`
+///
+/// True when the loaded libxmlsec1 is ABI compatible with the headers this
+/// extension was compiled against. `HankoXml::NativeVersion` calls this at
+/// require time; see [`dsig::abi_compatible`] for why it has to be fatal.
+fn native_abi_compatible() -> bool {
+    dsig::abi_compatible()
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("HankoXml")?;
+    let native: RModule = module.define_module("Native")?;
+
+    native.define_singleton_method("check_version", function!(native_check_version, 0))?;
+    native.define_singleton_method("abi_compatible?", function!(native_abi_compatible, 0))?;
+    native.define_singleton_method("versions", function!(native_versions, 0))?;
+    native.define_singleton_method("sign", function!(native_sign, 5))?;
+    native.define_singleton_method("verify", function!(native_verify, 7))?;
+    native.define_singleton_method("inspect_sig", function!(native_inspect, 2))?;
+    native.define_singleton_method("scan", function!(native_scan, 3))?;
+    native.define_singleton_method("validate_schema", function!(native_validate_schema, 3))?;
+
+    Ok(())
+}

data/ext/hanko_xml/src/sys.rs

@@ -0,0 +1,43 @@
+//! Raw FFI bindings generated by bindgen from the xmlsec1/libxml2 headers,
+//! plus thin aliases for the enum constants whose generated names are
+//! unreadable (§7.2).
+//!
+//! Nothing in here is safe to call directly — every call site must uphold
+//! libxmlsec1's own invariants (init-before-use, non-null docs/nodes,
+//! matching create/destroy pairs, etc). [`crate::dsig`] is the only module
+//! that calls into this one; everything *it* exposes is safe.
+
+#![allow(
+    non_upper_case_globals,
+    non_camel_case_types,
+    non_snake_case,
+    dead_code,
+    clippy::upper_case_acronyms
+)]
+
+include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+
+// --- Readable aliases for bindgen's unreadable enum constant names ------
+
+/// PEM key data format (`xmlSecKeyDataFormatPem`).
+pub const KEY_FORMAT_PEM: xmlSecKeyDataFormat =
+    xmlSecKeyDataFormat_xmlSecKeyDataFormatPem;
+
+/// PEM certificate format (`xmlSecKeyDataFormatCertPem`).
+pub const KEY_FORMAT_CERT_PEM: xmlSecKeyDataFormat =
+    xmlSecKeyDataFormat_xmlSecKeyDataFormatCertPem;
+
+/// Trusted key data type (`xmlSecKeyDataTypeTrusted`).
+pub const KEY_DATA_TYPE_TRUSTED: xmlSecKeyDataType = xmlSecKeyDataTypeTrusted;
+
+/// DSig verification succeeded.
+pub const DSIG_STATUS_SUCCEEDED: xmlSecDSigStatus =
+    xmlSecDSigStatus_xmlSecDSigStatusSucceeded;
+
+/// DSig verification found an invalid signature.
+pub const DSIG_STATUS_INVALID: xmlSecDSigStatus =
+    xmlSecDSigStatus_xmlSecDSigStatusInvalid;
+
+/// Same-document Reference URIs: empty `URI=""` and `URI="#id"`.
+pub const URI_TYPE_EMPTY: xmlSecTransformUriType = xmlSecTransformUriTypeEmpty;
+pub const URI_TYPE_SAME_DOCUMENT: xmlSecTransformUriType = xmlSecTransformUriTypeSameDocument;