COMMONSXML-4: Make the resolver floors ignore-all with a throw-on-unresolved toggle

[ppkarwasz]

Stacked on #28 (feature/reduce-shade-footprint); only the commits above that branch belong to this PR.

Implements COMMONSXML-4: a consistent contract for denied external fetches, with ignore-all as the default and an opt-in system property that switches to throwing.

Why

The deny-all resolver floors rejected every unresolved external reference with an exception, so a document that merely carries a DOCTYPE (without needing anything from it) failed to parse. Resolving unresolved references to empty content keeps the identical security property, nothing is fetched and nothing leaks, while letting such documents parse. The ignore outcome is best-effort: where an implementation prescribes a rejection, the block remains an acceptable outcome. Per the COMMONSXML-4 discussion, silently empty resolutions can also hide problems during debugging, so a system property lets deployments opt into rejection instead.

What

1. Make the resolver floors ignore-all instead of deny-all. The four floors resolve unresolved lookups to empty content and are renamed FallbackDeny* to FallbackIgnore*. The deny/ignore split made several variants redundant (DtdAwareDenyResolver, DtdSubsetFloor, the old Woodstox-only FallbackIgnoreXMLResolver); removing them takes the shade closure from 33 to 30 classes. The StAX floor collapses into the HardeningXMLInputFactory constructor, with a single setXMLResolver covering both the JDK Zephyr and Woodstox.
2. Drop XERCES_LOAD_EXTERNAL_DTD from the hardening recipes. Skipping the external DTD subset up front is redundant once the floor resolves it to empty. Actually requesting the subset exposed two gaps, fixed here: the floors now echo the requested identifiers on the empty source they return (Xerces derives the entity's base URI from the system id and fails on null), and the LSResourceResolver floor hands its content over as a character stream because the JDK's DOMEntityResolverWrapper discards empty string data.
3. Extend the ignore-all floor to Saxon resource resolution. Saxon's ALLOWED_PROTOCOLS="" lockdown was the odd one out, rejecting instead of ignoring. It is replaced by a nature-aware ignore-all ResourceResolver on the HardenedConfiguration (EmptySource for XML/XSLT/XSD natures, an empty StreamSource for text, null for entity/DTD natures so the lookup falls through to the hardened reader's floor and caller allow-listing keeps working), made non-removable by a setResourceResolver override (plain-JAXP TransformerFactory.setURIResolver replaces the Configuration resolver wholesale), plus CollectionFn.EMPTY_COLLECTION for fn:collection, the one channel that bypasses the resolver.
4. Resolve ignored URIs to a well-formed empty document. An empty character stream is not well-formed XML, so XSLTC rejected it for document() and both XSLTC and Xalan rejected an ignored xsl:include/xsl:import at compile time. The URIResolver floor now answers with an empty DOM document that every engine digests, and the include, import and document() tests assert the strict no-leak outcome on all implementations.
5. State the undeclared-entity contract precisely. The dual "blocks or does not leak" assertion survives only where an entity is genuinely undeclared after hardening: all of ExternalParameterEntityTest (the JDK parser reports the reference as a well-formedness fatal although XML 1.0 section 4.1 demotes it to an unreported validity constraint when the internal subset contains a parameter-entity reference; Apache Xerces implements the demotion) and the StAX case of ExternalDtdTest (Woodstox rejects undeclared references unconditionally). Every other hardened test asserts the strict no-leak outcome, test method names state the assertion they make, and the Woodstox-only undeclared-entity-resolver override is removed from the StAX recipe as a per-implementation workaround the contract no longer needs.
6. Add the COMMONSXML-4 toggle. Setting -Dorg.apache.commons.xml.throwOnUnresolved=true switches every floor, including Saxon's resource resolver and collection finder, from resolving an unresolved reference to empty content to rejecting it with the resolution hook's exception (SAXException, XMLStreamException, LSException, TransformerException, XPathException), carrying the pre-existing HardeningException.forbidden message with the full identifier tuple. The property is read at resolution time so it applies to existing factories, the failure message names the denied identifier and the enabling property, and references resolved by a caller-supplied resolver are unaffected. Documented in the XmlFactories Javadoc and the threat model, which now records the one system property the library reads.

Testing

Full surefire matrix green (stock JDK, Xerces, Xalan, Xalan+Xerces, Saxon, Saxon+Xerces, Woodstox; 84 reports). DenyUnresolvedTest exercises the toggle at the resolver level. ShadingFootprintTest keeps pinning the per-hardener shade closures; the StAX closure deliberately gains HardeningException, which now carries the shared toggle mechanism and denial message.

🤖 Generated with Claude Code

[ppkarwasz]

How to read this PR

This is probably one of the most disruptive PRs, since it inverts the default behavior that was there from the start.

TL;DR: to accommodate as many users as possible, the (non-configurable) behavior of the library is as forgiving as possible. Users that want more drastic behavior will be allowed to do that themselves, e.g. set disallow-doctype-decl to have parsers throw (if they support the feature). However that behavior will be devoid of any security implications since the security floor is assured.

Cases where this PR can not prevent the occurrence of exceptions or parsing errors reported through ErrorHandler/ErrorListener are those where the implementation structurally cannot proceed with empty content:

• An entity left undeclared by an emptied DTD. Emptying an external subset or a parameter entity erases the declarations it carried, so a later reference to such an entity is undeclared. XML 1.0 section 4.1 demotes that to an unreported validity constraint (Apache Xerces conforms), but the JDK's parser reports a well-formedness fatal unless the DOCTYPE has a system identifier, and Woodstox rejects every undeclared reference unconditionally. This reaches every surface parsing with the JDK parser (DOM, SAX, schema, validation, TrAX stylesheet and input parsing) and StAX on Woodstox.
• XInclude with parse="xml". The emptied include target is not a well-formed XML document, so the include fails on every implementation; parse="text" completes with empty content.
• XML Schema composition and location hints. An XSD whose xs:import, xs:include or xs:redefine target was emptied does not compile, and validation driven by an xsi:schemaLocation/xsi:noNamespaceSchemaLocation hint pointing at an unresolved schema fails the same way: an empty document is not a schema document.
• Secure-processing limits (unrelated to resolution): oversized entity expansion such as Billion Laughs and similar limits still abort the parse on every implementation.

Emptied xsl:include/xsl:import and document() are deliberately absent from this list: they now compile and evaluate to no content on every engine.

[garydgregory]

@ppkarwasz
Do I still get errors/exceptions if I register a listener?

[ppkarwasz]

Every external fetch will return an empty stream or DOMSource, depending on the JAXP factory.

That operation alone will not cause any errors, but its side-effects will: a missing entity declaration, an empty imported schema, and so on.

This PR also defines a system property org.apache.commons.xml.throwOnUnresolved that throws on any external fetch, if set to true.

[ppkarwasz]

I documented the system property in: 8edd19b