A TypeScript/JavaScript implementation of XML security standards using Web Crypto API for both browsers and Node.js.
This monorepo contains three interconnected packages, released together with one version:
- xml-core: a foundational library for working with XML in JavaScript/TypeScript with schema validation through decorators.
- xmldsigjs: XML Digital Signature implementation based on Web Crypto API with support for various cryptographic algorithms and canonicalization methods.
- xadesjs: XML Advanced Electronic Signatures (XAdES) implementation that extends XMLDSIGjs with additional signature formats and metadata.
npm install xml-core # Core XML utilities
npm install xmldsigjs # XML Digital Signatures
npm install xadesjs # XML Advanced Electronic Signaturesnpm 7+ installs the peer dependencies (xml-core, xmldsigjs, pkijs, asn1js, xpath, @xmldom/xmldom) automatically. In Node.js, register @xmldom/xmldom and xpath with setNodeDependencies (see the package READMEs).
v3 is ESM-only and requires Node.js ^20.19.0 || >=22.12.0 (was >=16). xml-core, xmldsigjs and xadesjs now share one version, so all three move to 3.0.0 together (xml-core skips 2 and goes from 1.2.6 to 3.0.0); don't mix them with xml-core 1 or xmldsigjs/xadesjs 2. CommonJS code can still require() them on these versions; Node.js 22.0–22.11 can't (ERR_REQUIRE_ESM). The public API is unchanged, apart from the decoding changes below.
- One ESM build per package:
build/cjs,build/esmandbuild/typesare replaced bybuild/*.jswith.d.tsfiles next to them. Deep imports (xmldsigjs/build/...) are blocked byexports; import from the package name. - TypeScript compiling to CommonJS: use
"module": "node20"or"nodenext"(node16fails with TS1479). ESM and bundler setups need no changes. Using the classes doesn't needexperimentalDecorators; only code that declares its own XML schemas with@XmlElement/@XmlChildElement/@XmlAttributedoes, as before. - Jest in CommonJS mode: switch to ESM mode or Vitest, or configure an ESM-to-CommonJS transformer and make sure
transformIgnorePatternsdoesn't excludexml-core,xmldsigjs,xadesjs,pkijs,asn1jsand@peculiar/*. - Peer dependencies, one copy per app:
setNodeDependencies, the decorator schemas,Application.setEngineand the algorithm and transform registries are module-level state, and pkijs checks asn1js objects withinstanceof, so a second copy of any of these packages breaks at runtime. They are now peers: xmldsigjs hasxml-core^3.0.0,pkijs^4.0.0andasn1js^4.0.0; xadesjs hasxml-coreandxmldsigjs^3.0.0; xml-core keeps@xmldom/xmldom^0.9.10andxpath(now^0.0.34 || ^0.0.35). xmldsigjs no longer depends onxpathdirectly. A conflicting version now fails at install (ERESOLVE) instead of at runtime. - pkijs 4 and asn1js 4: both are ESM-only, and objects built with asn1js 3 fail their
instanceofchecks; see the pkijs and asn1js notes. - Stricter decoding in xml-core's
Convert:FromBase64/FromBase64UrlthrowTypeErrorfor text that isn't Base64 (was aDOMException); whitespace and missing padding are still accepted.FromHexthrowsTypeErrorfor odd-length text or non-hex characters (was silently wrong bytes) and ignores the separators space, tab, newline,:,-and..ToUtf8String/FromUtf8Stringreplace invalid UTF-8 and lone surrogates with U+FFFD instead of throwingURIError, andToUtf8Stringno longer overflows the stack on inputs over about 125 KB.From*methods are typedUint8Array<ArrayBuffer>. - XML passed to
SignedXmlas bytes is decoded withTextDecoder, so invalid UTF-8 becomes U+FFFD instead of throwingURIError. - Dependencies:
tslib,pvtsutilsandpvutilsare gone; xml-core and xmldsigjs use@peculiar/utils^4.1.0.
All packages work in:
- Modern browsers with Web Crypto API support
- Node.js
^20.19.0 || >=22.12.0with its WebCrypto (official API) or Web Crypto polyfills (webcrypto) - Hardware Security Modules via node-webcrypto-p11
See CONTRIBUTING.md.
MIT License. See individual package directories for specific license files.