✨ Feature / SafeXml — single hardened xmerl_scan entry point

[docJerem]

Part of #32 — first PR of the SAML XML parsing surface hardening initiative.

Summary

• New module ExSaml.Core.Xml.SafeXml — single entry point for parsing untrusted SAML/XML via :xmerl_scan. Always forces allow_entities: false, namespace_conformant: true, quiet: true; callers cannot weaken these options.

• Tuple-only API. SafeXml.scan/1 returns {:ok, xml()} | {:error, :invalid_xml} — no raising variant. Errors are values, composable in with/case pipelines.

• Tuple cascade through callers. Binding.decode_response/2 (public), Sp.decrypt_assertion/2 (private) and Helper.decode_saml_payload/2 (private) all propagate the tuple. The previous rescue in Helper is replaced by a case; the error reason is now an atom ({:invalid_response, :invalid_xml}) instead of a stringified inspect(error).

• Configurable error hook for SIEM / OCSF pipelines:

  config :ex_saml, :safe_xml,
    on_error: &MyApp.SIEM.report_xml_error/1

  The arity-1 handler receives %{reason: :invalid_xml, kind: :error | :exit | :throw, payload: …}. Any exception from the handler is silently caught — it can never mask the original parse failure or alter control flow.

• De-duplication of the four pre-existing :xmerl_scan.string call sites (Metadata.parse/1, Binding.decode_response/2 × 2, Sp.decrypt_assertion/2). The binary→charlist conversion (the source of the 🐛 Fix / UTF-8 characters in SAMLResponse rejected by xmerl_scan #22 UTF-8 fix that had to patch four files) is centralised in SafeXml.scan/1 — future encoding changes are now a one-file diff.

Why this PR

This is PR 1 of #32 (SAML XML parsing surface hardening). The umbrella issue lays out the full four-PR plan; the short version is that the original mix security.check_release task drafted in #15 relied on regex source-scanning, which was silently contournable. The root cause was upstream: :xmerl_scan was called in four different files with slightly different options. With a single hardened call site, a future audit check (PR 2 of #32) becomes incontournable: any reference to :xmerl_scan.* outside safe_xml.ex is a violation.

Behaviour notes

• Preserved: Metadata.parse/1 still returns {:error, invalid_xml_violation()} on any parse failure or non-element root.
• Changed (deliberate): Binding.decode_response/2 return shape goes from xml() to {:ok, xml()} | {:error, :invalid_xml}. Public spec change. Single intra-lib caller (Helper.decode_saml_payload/2) updated; tests updated.
• Changed (deliberate): Helper.decode_saml_payload/2 error shape {:invalid_response, …} now carries an atom reason instead of an interpolated inspect(error) string. No caller pattern-matches on it (verified via grep).
• Changed (deliberate): Binding.decode_response/2 now passes quiet: true to :xmerl_scan (only Metadata.parse/1 did before). Malformed-payload xmerl warning logs are now silent; error semantics unchanged.

Test plan

• mix compile --warnings-as-errors clean
• mix format --check-formatted clean
• mix credo --strict — no issues
• mix sobelow --config --skip — scan complete, no findings
• mix test — 211 tests, 0 failures, including:
  • 7 SafeXml.scan/1 cases (well-formed, binary/charlist parity, UTF-8, malformed, empty, XXE external entity, internal entity)
  • 5 :on_error hook cases (called once per failure, not called on success, swallows handler errors, no-op when unconfigured, no-op when value is not an arity-1 function)
  • 7 updated Binding.decode_response/2 callers in binding_test.exs (deflate + non-deflate roundtrip + full UTF-8 regression matrix)
• grep -rn ':xmerl_scan.string' lib/ — only invocation lives at safe_xml.ex:59
• grep -rn 'scan!' lib/ test/ — no remaining callers (no raising API surface)