public extension PureXML.Canonical { /// Produces the Canonical XML (C14N) form of a node (the libxml2 `c14n.h` /// model): UTF-8 text with namespace declarations and attributes in canonical /// order, empty elements expanded to start/end pairs, character and attribute /// escaping normalized, and namespaces rendered per the inclusive or exclusive /// rules. Comments are omitted unless requested. Reimplemented from the C14N /// specification. struct Canonicalizer: Sendable { public let options: Options public init(options: Options = .inclusive) { self.options = options } /// Canonicalizes a node. public func canonicalize(_ node: PureXML.Model.Node) -> String { if options.prefixRewrite == .sequential { // C14N 2.0 sequential rewrite: rebuild with canonical prefixes, // then render exclusive-style so declarations land at first use. let rewritten = PrefixRewriter.rewrite(node, labels: options.qnameAwareLabels) var rendering = options rendering.prefixRewrite = .retain rendering.mode = .exclusive return Canonicalizer(options: rendering).canonicalize(rewritten) } var output = "" emit(node, inScope: [:], rendered: [:], output: &output) return output } /// Canonicalizes a subtree that may sit inside a larger document (the C14N /// node-subset case). The apex element receives the namespace context in /// scope from its omitted ancestors, and inherits their in-scope `xml:*` /// attributes (`xml:base`, `xml:lang`, `xml:space`) when it does not set /// them itself, so signing a fragment yields the same bytes regardless of /// where the fragment sat in the document. (Inherited `xml:base` follows /// the C14N 1.0 nearest-ancestor rule, not 1.1 URI joining.) public func canonicalize(_ subtree: PureXML.Model.TreeNode) -> String { guard subtree.kind == .element, case let .element(apex) = subtree.node else { return canonicalize(subtree.node) } let ancestorNamespaces = Self.inScopeNamespaces(above: subtree) let mergeBase = options.mergeInheritedBase let inheritedXML = Self.inheritedXMLAttributes(above: subtree, apex: apex, mergeBase: mergeBase) var output = "" switch options.mode { case .inclusive: let augmented = Self.augmentedApex(apex, inheritedXML: inheritedXML, mergingNamespaces: ancestorNamespaces, stripApexBase: mergeBase) emit(augmented, inScope: [:], rendered: [:], output: &output) case .exclusive: let augmented = Self.augmentedApex(apex, inheritedXML: inheritedXML, mergingNamespaces: nil, stripApexBase: mergeBase) emit(augmented, inScope: ancestorNamespaces, rendered: [:], output: &output) } return output } private func emit( _ node: PureXML.Model.Node, inScope: [String: String], rendered: [String: String], output: inout String, ) { switch node { case let .document(children): // Top-level comments, PIs, and the document element are // separated from one another by single line feeds. var renderings: [String] = [] for child in children { var rendering = "" emit(child, inScope: inScope, rendered: rendered, output: &rendering) if !rendering.isEmpty { renderings.append(rendering) } } output += renderings.joined(separator: "\n") case let .element(element): emit(element, inScope: inScope, rendered: rendered, output: &output) case let .text(value), let .cdata(value): let text = options.trimTextNodes ? value.trimmingXMLWhitespace() : value output += Self.escapeText(text) case let .comment(value): if options.includeComments { output += "" } case let .processingInstruction(target, data): output += data.isEmpty ? "" : "" } } private func emit( _ element: PureXML.Model.Element, inScope: [String: String], rendered: [String: String], output: inout String, ) { let declarations = Self.namespaceDeclarations(element) var childInScope = inScope for (prefix, uri) in declarations { childInScope[prefix] = uri } let attributes = Self.plainAttributes(element) let toRender = namespacesToRender(element, declarations: declarations, inScope: childInScope, attributes: attributes, rendered: rendered) var childRendered = rendered for (prefix, uri) in toRender { childRendered[prefix] = uri } output += "<" + element.name.description for (prefix, uri) in toRender.sorted(by: { $0.0 < $1.0 }) { output += Self.renderNamespace(prefix, uri) } for attribute in attributes.sorted(by: Self.attributeOrder) { output += " \(attribute.name.description)=\"\(Self.escapeAttribute(attribute.value))\"" } output += ">" for child in element.children { emit(child, inScope: childInScope, rendered: childRendered, output: &output) } output += "" } // MARK: Namespace selection private func namespacesToRender( _ element: PureXML.Model.Element, declarations: [(String, String)], inScope: [String: String], attributes: [PureXML.Model.Attribute], rendered: [String: String], ) -> [(String, String)] { switch options.mode { case .inclusive: declarations.filter { prefix, uri in guard rendered[prefix] != uri else { return false } // An empty default declaration is superfluous unless a // non-empty default namespace was rendered above. if prefix.isEmpty, uri.isEmpty { return !(rendered[""] ?? "").isEmpty } return true } case .exclusive: exclusiveNamespaces(element, inScope: inScope, attributes: attributes, rendered: rendered) } } private func exclusiveNamespaces( _ element: PureXML.Model.Element, inScope: [String: String], attributes: [PureXML.Model.Attribute], rendered: [String: String], ) -> [(String, String)] { var utilized: Set = [element.name.prefix ?? ""] for attribute in attributes where attribute.name.prefix != nil { utilized.insert(attribute.name.prefix ?? "") } utilized.formUnion(options.inclusiveNamespacePrefixes) var result: [(String, String)] = [] for prefix in utilized { let uri = inScope[prefix] ?? "" if prefix.isEmpty { if uri != (rendered[""] ?? "") { result.append(("", uri)) } } else if !uri.isEmpty, rendered[prefix] != uri { result.append((prefix, uri)) } } return result } // MARK: Attribute and namespace rendering private static func renderNamespace(_ prefix: String, _ uri: String) -> String { prefix.isEmpty ? " xmlns=\"\(escapeAttribute(uri))\"" : " xmlns:\(prefix)=\"\(escapeAttribute(uri))\"" } private static func attributeOrder(_ lhs: PureXML.Model.Attribute, _ rhs: PureXML.Model.Attribute) -> Bool { let leftURI = lhs.name.namespaceURI ?? "" let rightURI = rhs.name.namespaceURI ?? "" if leftURI != rightURI { return leftURI < rightURI } return lhs.name.localName < rhs.name.localName } private static func namespaceDeclarations(_ element: PureXML.Model.Element) -> [(String, String)] { element.attributes.compactMap { attribute in let name = attribute.name if name.prefix == nil, name.localName == "xmlns" { return ("", attribute.value) } if name.prefix == "xmlns" { return (name.localName, attribute.value) } return nil } } private static func plainAttributes(_ element: PureXML.Model.Element) -> [PureXML.Model.Attribute] { element.attributes.filter { attribute in let name = attribute.name return name.prefix != "xmlns" && !(name.prefix == nil && name.localName == "xmlns") } } // MARK: Node-subset context /// The apex element with its inherited `xml:*` attributes added, and (for /// inclusive mode) the namespaces in scope from omitted ancestors merged in /// as declarations so the apex renders its full namespace context. private static func augmentedApex( _ apex: PureXML.Model.Element, inheritedXML: [PureXML.Model.Attribute], mergingNamespaces ancestorNamespaces: [String: String]?, stripApexBase: Bool, ) -> PureXML.Model.Element { // Under 1.1, the apex's own xml:base is folded into the merged base in // inheritedXML, so drop the original to avoid emitting it twice. let own = stripApexBase ? apex.attributes.filter { !($0.name.prefix == "xml" && $0.name.localName == "base") } : apex.attributes var attributes = own + inheritedXML if let ancestorNamespaces { let declared = Set(apex.attributes.map(\.name.description)) for (prefix, uri) in ancestorNamespaces { let name = prefix.isEmpty ? "xmlns" : "xmlns:\(prefix)" if !declared.contains(name) { attributes.append(PureXML.Model.Attribute(name, uri)) } } } return PureXML.Model.Element(name: apex.name, attributes: attributes, children: apex.children) } /// The namespace declarations in scope from a node's omitted ancestors, /// nearest ancestor winning (so an inner redeclaration is preserved). private static func inScopeNamespaces(above node: PureXML.Model.TreeNode) -> [String: String] { var result: [String: String] = [:] var current = node.parent while let ancestor = current { for attribute in ancestor.attributes { guard let prefix = declaredPrefix(of: attribute.name), result[prefix] == nil else { continue } result[prefix] = attribute.value } current = ancestor.parent } return result } /// The `xml:*` attributes in scope from a node's omitted ancestors that the /// apex does not already set, nearest ancestor winning. private static func inheritedXMLAttributes(above node: PureXML.Model.TreeNode, apex: PureXML.Model.Element, mergeBase: Bool) -> [PureXML.Model.Attribute] { let present = Set(apex.attributes.map(\.name.description)) if mergeBase { return inherited11XMLAttributes(above: node, apex: apex, present: present) } // Canonical XML 1.0: the nearest of every in-scope xml:* attribute the // apex does not already set. var seen: Set = [] var result: [PureXML.Model.Attribute] = [] var current = node.parent while let ancestor = current { for attribute in ancestor.attributes where attribute.name.prefix == "xml" { let key = attribute.name.description guard !present.contains(key), seen.insert(key).inserted else { continue } result.append(attribute) } current = ancestor.parent } return result } /// The prefix a namespace declaration binds (empty for the default /// namespace), or nil when the attribute is not a namespace declaration. private static func declaredPrefix(of name: PureXML.Model.QualifiedName) -> String? { if name.prefix == nil, name.localName == "xmlns" { return "" } if name.prefix == "xmlns" { return name.localName } return nil } } } public extension PureXML.Canonical.Canonicalizer { /// Canonicalizes a node-set: only the nodes the predicate selects appear in /// the output (C14N's XPath/position-based node selection). An excluded /// element's start and end tags are omitted but its selected descendants are /// kept, with each one rendering the namespace context in scope at its /// position, so signing a discontiguous selection is well defined. Predicate /// identity is by ``PureXML/Model/TreeNode`` reference, so a caller can select /// specific nodes (for example an XPath result set). func canonicalize(_ node: PureXML.Model.TreeNode, including predicate: (PureXML.Model.TreeNode) -> Bool) -> String { var output = "" emitSelected(node, inScope: Self.inScopeNamespaces(above: node), rendered: [:], including: predicate, output: &output) return output } private func emitSelected( _ node: PureXML.Model.TreeNode, inScope: [String: String], rendered: [String: String], including predicate: (PureXML.Model.TreeNode) -> Bool, output: inout String, ) { switch node.kind { case .document: for child in node.children { emitSelected(child, inScope: inScope, rendered: rendered, including: predicate, output: &output) } case .element: emitSelected(element: node, inScope: inScope, rendered: rendered, including: predicate, output: &output) case .text, .cdata: if predicate(node) { output += Self.escapeText(options.trimTextNodes ? node.value.trimmingXMLWhitespace() : node.value) } case .comment: if predicate(node), options.includeComments { output += "" } case .processingInstruction: if predicate(node) { output += node.value.isEmpty ? "" : "" } case .doctype, .entityReference, .namespace: break } } private func emitSelected( element node: PureXML.Model.TreeNode, inScope: [String: String], rendered: [String: String], including predicate: (PureXML.Model.TreeNode) -> Bool, output: inout String, ) { let element = PureXML.Model.Element(name: node.name ?? .init(""), attributes: node.attributes, children: []) var childInScope = inScope for (prefix, uri) in Self.namespaceDeclarations(element) { childInScope[prefix] = uri } guard predicate(node) else { // Omitted element: its namespaces stay in scope for descendants, but // nothing is rendered, so a selected descendant renders them itself. for child in node.children { emitSelected(child, inScope: childInScope, rendered: rendered, including: predicate, output: &output) } return } let attributes = Self.plainAttributes(element) let toRender = selectedNamespaces(element, inScope: childInScope, attributes: attributes, rendered: rendered) var childRendered = rendered for (prefix, uri) in toRender { childRendered[prefix] = uri } output += "<" + element.name.description for (prefix, uri) in toRender.sorted(by: { $0.0 < $1.0 }) { output += Self.renderNamespace(prefix, uri) } for attribute in attributes.sorted(by: Self.attributeOrder) { output += " \(attribute.name.description)=\"\(Self.escapeAttribute(attribute.value))\"" } output += ">" for child in node.children { emitSelected(child, inScope: childInScope, rendered: childRendered, including: predicate, output: &output) } output += "" } /// The namespaces a selected element renders: in inclusive mode every in-scope /// binding not yet rendered (so an exposed element re-declares its inherited /// context); in exclusive mode only those it visibly uses. private func selectedNamespaces( _ element: PureXML.Model.Element, inScope: [String: String], attributes: [PureXML.Model.Attribute], rendered: [String: String], ) -> [(String, String)] { switch options.mode { case .inclusive: inScope.filter { rendered[$0.key] != $0.value }.map { ($0.key, $0.value) } case .exclusive: exclusiveNamespaces(element, inScope: inScope, attributes: attributes, rendered: rendered) } } } public extension PureXML.Canonical { /// Canonicalizes a node with the given options. static func canonicalize(_ node: PureXML.Model.Node, options: Options = .inclusive) -> String { Canonicalizer(options: options).canonicalize(node) } }