Read privateKey and decryptionPvk at construction, and refuse a key the option can't use #507

privateKey and decryptionPvk are read the first time they are used. privateKey is read when a request, a logout message or metadata is signed, and decryptionPvk when an encrypted assertion or NameID arrives. A key that is malformed, or of a kind the option can't use, constructs without complaint and fails on the first request that needs it. For most such keys the error is OpenSSL's, and it doesn't name the option. With #447 merged, on Node 26:

In the next major, constructing a SAML with either option set to a value it can't use throws a TypeError naming the option, as a missing callbackUrl, issuer or idpCert already does.

Scope

• initialize() reads privateKey and decryptionPvk the way they are read at use, through privateKeyToPem() and decryptionPvkToPem(). A value those refuse is refused at construction, with the same message.
• Each must then hold a private key of a type the option can use. The type comes from Node's crypto.createPrivateKey().asymmetricKeyType. For decryptionPvk that is RSA, because xml-encryption unwraps the content key only with rsa-oaep-mgf1p or rsa-1_5. For privateKey it is RSA, because every signatureAlgorithm value is an RSA signature. Whether the data fits its PEM label stays with xml-crypto's toPem().
• A PEM decryptionPvk is still handed to Node as given, so text around the message, such as Bag Attributes, stays accepted. The check at construction reads it the same way.
• README.md: the privateKey and decryptionPvk sections say that the key is checked at construction, and which key types each option takes.

Why the next major

A configuration that holds an unusable key and never uses it works today, and would throw at startup. Examples are a decryptionPvk set although the IdP never encrypts, and a placeholder key in a test suite.

Decide first

• Keep the check at use, or keep what construction read. SAML.options is public and can be changed after construction, so the check at use stays unless options becomes read-only. Keeping the PEM that construction produced would also stop every request from reading the key again.
• idpCert, publicCert and decryptionCert. A plain value of each could be read at construction too. An idpCert callback can only be read when it runs, at verification.
• rsa-pss keys. Node types an RSA-PSS key rsa-pss, not rsa. Decide whether privateKey may be one when signatureAlgorithm is sha256-mgf1.

Related: #422 requires signatureAlgorithm when signing, so the privateKey check can rely on it.

🤖 Generated with Claude Code