Audit the public export surface and deprecate internal helpers ahead of 7.0

[cjbarth]

Summary

The package publishes 40 symbols, and a good share of them are internal helpers that became public by accident rather than by design. Now that src/index.ts lists its exports explicitly instead of using export * from, we can see the whole surface and decide what belongs in it.

The goal for 7.0 is to shrink the surface. This issue covers the audit and the 6.x deprecation pass that has to come first — a name cannot simply vanish in 7.0 without consumers having seen a warning.

How the surface got this wide

src/index.ts did:

export * from "./types";
export * from "./utils";

Every module-level export in utils.ts was therefore public automatically. Adding a helper there — even one intended purely for use by signed-xml.ts — silently widened the package's API, because a sibling module and an external consumer reach it through the same export keyword. That is how findChilds stayed published with no callers, and how each new helper joined the surface without anyone choosing to publish it.

Current surface

40 symbols: 18 types and 1 value from types.ts, 16 values from utils.ts, plus SignedXml and the four canonicalization classes.

The 18 types are genuinely consumer-facing — dependents such as node-saml import Reference, SignedXmlOptions and friends directly. Expect that block to survive mostly intact. The utils block is where the work is:

Export	Callers outside utils.ts	Notes
findChilds	0	deprecated alias; see #550
isArrayHasLength	17	internal predicate
findChildren	16	internal DOM helper
findAttr	5	internal DOM helper
encodeSpecialCharactersInText	5	internal serialization helper
isDescendantOf	4	internal DOM helper
encodeSpecialCharactersInAttribute	3	internal serialization helper
validateDigestValue	3	internal; constant-time comparison
findAncestorNs	3	plausibly useful to implementors
EXTRACT_X509_CERTS	2	internal regex
derToPem	2	plausibly useful to consumers
pemToDer	2	plausibly useful to consumers
findAncestorNsForNode	2	added recently; internal
BASE64_REGEX	1	internal regex
PEM_FORMAT_REGEX	1	internal regex
normalizePem	1	plausibly useful to consumers

Rough grouping to argue about, not a decision:

• Almost certainly internal: the three regexes, isArrayHasLength, findAttr, findChildren, isDescendantOf, both encodeSpecialCharacters*, findAncestorNsForNode.
• Worth keeping or reshaping: derToPem, pemToDer, normalizePem — key-format conversion is a real consumer need. findAncestorNs is useful to anyone implementing a custom canonicalization algorithm.
• Needs care: validateDigestValue performs the constant-time digest comparison. If anything external depends on it, removing it may push someone toward a naive ===. Check before dropping.

A caveat on the call counts: they measure our usage, not consumers'. Low internal use does not prove nobody imports it. Worth a look at how dependents actually import from this package before committing to a list — node-saml first, since a break there is a break for most of the ecosystem.

Proposed approach

1. Decide which names stay. The table above is a starting point, not a conclusion.

2. In a 6.x release, mark everything on the removal list @deprecated with a replacement named, plus a runtime warning so JavaScript consumers see it too. House pattern, from src/signed-xml.ts:

   import { deprecate } from "util";
   
   const warnX = deprecate(() => {}, "`x()` is deprecated and will be removed in a future version. Use `y()` instead.", "XML_CRYPTO_X");

   A bare /** @deprecated */ with no replacement and no runtime warning — what findChilds has today — is not enough. It is invisible to JavaScript consumers, and it tells TypeScript users nothing about what to switch to.

3. In 7.0, delete the deprecated entries from the export list in src/index.ts and drop the export keyword from the ones that stay internal to utils.ts.

4. Document the removals and their replacements in the changelog and the README API section.

Guard against regrowth

Removing names once does not stop the surface growing back the same way. Worth considering:

• An api-extractor report, or a snapshot test over the exported names, so that widening the surface shows up as a reviewable diff rather than a side effect of adding a helper.
• Splitting genuinely-internal helpers into a module that index.ts never re-exports, so "public" becomes a deliberate act.

Related

• Remove deprecated findChilds() alias #550 — remove findChilds, the clearest single instance.

[cjbarth]

Consumer survey: who actually imports what

The table in the issue counts our calls, so here is the missing half — what consumers import. Two passes: the npm dependents that matter by volume, and a GitHub code search per symbol.

Method

1. Dependents. Pulled the published tarball of every package with a direct xml-crypto dependency I could identify, and grepped for what it reaches for through the package.
2. Code search. For each of the 16 utils exports plus createOptionalCallbackFunction, searched GitHub for files containing both the symbol and the string xml-crypto, excluding this repo. Then opened each non-obvious hit and checked whether it imports the symbol from us or merely defines a local function of the same name.

Step 2 is the part worth doing carefully: raw hit counts are almost entirely noise. Of ~200 matches, the large majority are forks of this repo, vendored copies under node_modules, or CVE-reproduction corpora (BUseclab/cve-genie, kana112/cve-genie-deepseek, simran639/vuln-bridge, dieter1199/rag-based-vulnerability-detection) that check our own utils.js into git for CVE-2024-32962 / CVE-2025-29774 / CVE-2025-29775. findChilds looks like 55 hits and turns out to have zero real importers.

The dependents only use SignedXml

Package	Downloads/wk	Range	What it uses
@node-saml/node-saml	909k	^6.1.2	SignedXml (6 sites)
samlify	827k	^6.1.2	SignedXml (2 sites)
@node-saml/passport-saml	446k	via node-saml	—
saml2-js	127k	^6.1.2	SignedXml (1 site)
passport-wsfed-saml2	3.3k	^6.x	SignedXml (2 sites)
node-saml (deprecated)	2.3k	^2.1.4	xmlCrypto.xpath

xml-crypto itself is ~2.82M/wk, so the ecosystem's headline consumers touch none of the utils block. The one exception is the deprecated unscoped node-saml, which calls xmlCrypto.xpath — an export we do not have any more, so it is already broken on 6.x and is not a constraint.

Per-symbol findings

Confirmed importers, verified by reading the file:

Export	Verdict	Evidence
findAncestorNs	imported by real consumers	akira-io/node-efatura, kacheablecr-jpg/nervus-backend, dressoria/sri-signing-worker all do import { C14nCanonicalization, findAncestorNs } from "xml-crypto". Two more (JUANMANUEL416/SionFe, Rzyfront/Vendix) reimplement it and name us in the comment explaining why.
pemToDer	imported	shunkica/fiskalizacija2-js: import { pemToDer, SignedXml } from "xml-crypto".
derToPem	no importer found	Every hit defines its own (NXD-Foundation/nxd-wallet-conformance-backend).
normalizePem	no importer found	Every hit defines its own (Sundsvallskommun/web-app-fake-idp-admin, AlphaLuppi/mnm).
validateDigestValue	no importer found	metriport/metriport has its own validateDigestValues, unrelated to ours.
findAttr	no importer found	Four hits, all local findAttribute helpers over SAML attribute statements — a name collision, not a use.
findChildren / findChilds	no importer found	Local functions or derived copies. The Meteor saml_utils.js copies define their own.
isArrayHasLength, encodeSpecialCharactersInText, encodeSpecialCharactersInAttribute	no importer found	Mifiel/xml-fiesta-js is a port of our canonicalization with the helpers copied in, not an importer.
EXTRACT_X509_CERTS, BASE64_REGEX, PEM_FORMAT_REGEX	no importer found	CVE corpora only.
isDescendantOf, findAncestorNsForNode	zero hits at all	—
createOptionalCallbackFunction	no importer found	Forks and CVE corpora only. Relevant to #546.

What this changes about the proposed grouping

Mostly it confirms it, with one move in each direction:

• findAncestorNs is load-bearing and should stay. The issue guessed "plausibly useful to implementors"; it is more than plausible. Every confirmed use pairs it with C14nCanonicalization to canonicalize a document subset by hand — i.e. it is already functioning as part of the custom-canonicalization extension contract, and it is the one export outside SignedXml with several independent real consumers. Worth documenting as such rather than merely keeping.
• validateDigestValue can go internal. The issue flagged it as "needs care" in case removing it pushed someone toward a naive ===. Nobody imports it, so that risk is not realised. It should stay internal precisely because it is the constant-time comparison — publishing it invites reimplementation.
• derToPem / normalizePem have no evidence either way. Nobody imports them, but three separate projects hand-rolled a normalizePem and two hand-rolled a derToPem, which is a decent argument that the need is real and the export is merely undiscoverable. Keeping the key-format trio together (derToPem, pemToDer, normalizePem) is coherent and cheap; splitting it because only one of the three has a proven importer is not.

Everything else in the table has no external importer, and can lose its export without a deprecation cycle mattering to anyone we can find.

One thing the search turned up that is not in this issue

shunkica/fiskalizacija2-js does:

import { pemToDer, SignedXml } from "xml-crypto";
import { Sha256 } from "xml-crypto/lib/hash-algorithms.js";

That second line reaches past the barrel into lib/ for a hash algorithm class we never export. Shrinking index.ts does not stop that, and package.json has no exports map, so lib/** is reachable and effectively public whatever we decide here. If the goal is that "public" becomes a deliberate act, an exports map is the lever, and it would be a breaking change worth doing in the same major. Happy to open that separately.

Caveats

GitHub code search only indexes default branches of public repositories, so private and enterprise consumers are invisible; every "no importer found" is an absence of evidence over that corpus, not proof. It is, however, the same corpus for every symbol, and the contrast between findAncestorNs (three importers) and validateDigestValue (none) is a real difference rather than noise.

Raw data — per-symbol hit lists and the dependent-by-dependent grep — available if useful.