gamlastan 0.9.0

//! # gamlastan::xml
//!
//! XML layer for SAML 2.0 - backed by the `uppsala` XML parser.
//!
//! This module is the XML boundary for gamlastan. Incoming SAML XML should be
//! parsed with [`parse_secure`] so DTDs/entities and resource limits are handled
//! before any profile logic sees the document. The parsed [`Document`] is then
//! deserialized into borrowed `*Ref<'a>` types with [`parse_saml`].
//!
//! This module provides:
//!
//! - [`SamlDeserialize`] trait for zero-copy deserialization from XML into borrowed SAML types
//! - [`SamlSerialize`] trait for serialization of owned SAML types to XML
//! - [`helpers`] module with utility functions for XML element navigation and attribute access
//! - [`XmlError`] error types for XML-related operations
//!
//! ## Zero-Copy Parsing Flow
//!
//! ```text
//! XML string ──→ uppsala::parse() ──→ Document<'a> ──→ SamlDeserialize::from_xml()
//!                                                         │
//!                                                         ▼
//!                                                    ResponseRef<'a>  (borrows from XML string)
//!                                                         │
//!                                                         ▼ .to_owned()
//!                                                    Response         (owned, for storage)
//! ```
//!
//! ## Example
//!
//! ```
//! use gamlastan::core::protocol::AuthnRequestRef;
//! use gamlastan::profiles::sso::sp::create_authn_request;
//! use gamlastan::profiles::sso::web_browser::AuthnRequestOptions;
//! use gamlastan::xml::{parse_saml, parse_secure, SamlSerialize};
//!
//! let request = create_authn_request(&AuthnRequestOptions {
//!     sp_entity_id: "https://sp.example.org/metadata".to_string(),
//!     ..Default::default()
//! })?;
//! let xml = request.to_xml_string()?;
//!
//! let doc = parse_secure(&xml)?;
//! let parsed = parse_saml::<AuthnRequestRef<'_>>(&doc)?;
//! let owned = parsed.to_owned();
//!
//! assert_eq!(
//!     owned.base.issuer.unwrap().value,
//!     "https://sp.example.org/metadata"
//! );
//!
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ## Trusted vs Untrusted XML
//!
//! Use [`parse_secure`] for attacker-controlled protocol XML: browser POSTs,
//! Redirect messages, SOAP/PAOS envelopes, and decrypted assertions. Use
//! [`parse_secure_metadata`] for remote metadata and metadata-derived KeyInfo
//! fragments; it retains the security limits while permitting structural
//! comments and processing instructions used by federation aggregates. Direct
//! `uppsala::parse` is appropriate only for trusted XML generated by this
//! process or tightly controlled test fixtures.
//!
//! ## Re-exports
//!
//! This crate re-exports key `uppsala` types for convenience.

pub mod assertion;
pub mod deserialize;
pub mod error;
pub mod helpers;
pub mod protocol;
pub mod serialize;

// Re-export the core traits.
pub use deserialize::{
    parse_saml, parse_secure, parse_secure_metadata, parse_secure_with_config, SamlDeserialize,
    SecureParseConfig,
};
pub use error::XmlError;
pub use serialize::SamlSerialize;

// Re-export commonly used uppsala types for consumers of this crate.
pub use uppsala::{self, Document, NodeId, XmlWriter};